Implement Adapter Contract & Conformance Suite v0.1 — capabilities, provenance, failures, and receipts

[hummbl-dev]

Parents

• Program ledger: https://github.com/hummbl-dev/hummbl-research/issues/67
• Adapter SDK epic: Epic B: Source Adapter SDK — common interface, provenance hooks, and conformance fixtures #9

Status

APPROVED EXECUTABLE FIRST SLICE — CLOSEABLE — CANDIDATE UNTIL REVIEWED AND MERGED

Mission

Implement the smallest complete adapter contract and deterministic conformance suite needed to govern the twelve-adapter reference wave.

Before choosing paths, languages, or dependencies, inspect and follow this repository's existing conventions. Reuse existing schemas and receipt patterns where compatible; do not create parallel abstractions merely for naming consistency.

Required implementation

1. Adapter contract

Specify the semantics of:

discover(query)
resolve(identifier_or_uri)
retrieve(record)
snapshot(record)
normalize(record)
verify(record)
cite(record)
refresh(record)
delete_or_invalidate(record)

For every operation, define:

• inputs and outputs;
• supported, unsupported, restricted, and authorization-gated states;
• completeness posture;
• retry, pagination, and rate-limit behavior;
• provenance requirements;
• deterministic failure representation.

2. Capability declaration

Create a machine-readable adapter manifest covering:

• adapter and source-registry identity;
• supported operations;
• access mode;
• public/private data-plane class;
• authentication requirements;
• snapshot versus external-reference behavior;
• version and checksum support;
• exact-locator support;
• known limitations;
• conformance status and receipt link.

3. Result and provenance envelope

Every result must preserve, where applicable:

• canonical source URI;
• stable source-specific identifier;
• collection, item, and version identity;
• retrieval timestamp;
• publication/modification date;
• content type;
• checksum or explicit checksum-unavailable posture;
• license and privacy posture reference;
• exact source locator;
• acquisition method;
• transformation parent/child relationships;
• completeness and partial-result state.

4. Error taxonomy

Model at least:

• not found;
• ambiguous identity;
• unauthorized or permission denied;
• rate limited;
• partial pagination;
• unsupported operation;
• restricted content;
• stale or superseded record;
• checksum mismatch;
• malformed upstream metadata;
• source correction or deletion;
• transient upstream failure;
• policy-blocked operation.

5. Conformance suite

Create deterministic fixtures and tests for at least five structural patterns:

1. scholarly metadata API;
2. versioned code repository;
3. archive or historical item;
4. timestamped multimedia item;
5. private or authorization-gated connector abstraction.

Tests must include positive, negative, and adversarial cases.

6. Receipt

Define and emit adapter_conformance_receipt.v0.1, aligned with execution-receipts, containing exact commands, fixture versions, results, failures, environment facts that are locally observed, and unresolved limitations.

Acceptance criteria

• The contract distinguishes unsupported, restricted, unavailable, and failed operations.
• Partial results cannot appear as complete success.
• Source-specific semantics and exact locators survive normalization.
• Public/private posture is mandatory and preserved.
• The suite runs without live production credentials.
• At least five reference adapter fixtures pass the positive path.
• Negative fixtures fail for the intended reason.
• Receipt output is deterministic and reviewable.
• The implementation documents how real adapters bind to the contract without claiming that those adapters already exist.

Execution order

1. inspect repository and cross-repo conventions;
2. draft invariants and capability states;
3. create adversarial fixtures;
4. implement schema/validator and minimal harness;
5. implement five structural reference fixtures;
6. run conformance and claim-honesty review;
7. open a governed draft PR with exact receipts.

Dependencies

• Registry implementation issue: https://github.com/hummbl-dev/hummbl-bibliography/issues/94
• Receipt authority: hummbl-dev/execution-receipts

Explicit non-goals

• live credentials or production deployment;
• provider-specific optimization;
• bulk crawling;
• hiding provider restrictions behind a uniform success response.

[hummbl-dev]

2026-07-11 — implementation branch and draft PR opened

• Draft PR: feat: add Source Adapter Contract and Conformance Suite v0.1 #11
• Branch: feat/chatgpt/adapter-contract-v0-1
• Current head commit: 3e058cfc997832f5ed170b77bee960774ffc67fc
• GitHub state: open, draft, mergeable, unmerged

Implemented scope

• adapter capability manifest schema;
• result/provenance envelope schema;
• conformance-receipt schema;
• stdlib-only deterministic Python validator;
• five valid structural adapter patterns;
• eight adversarial failure patterns;
• contract documentation and local execution receipt.

Observed local validation

Python 3.13.5:

• valid structural fixtures: 5/5 PASS;
• invalid/adversarial fixtures: 8/8 correctly rejected.

Supplemental jsonschema 4.26.0 audit:

• manifest, result, and receipt components across five patterns: 15/15 with 0 validation errors.

Claim-honesty posture

IMPLEMENTED_ON_BRANCH_PENDING_NON_AUTHOR_REVIEW

No merge, GitHub Actions pass, live provider binding, production deployment, or adapter promotion is claimed. GitHub reported no commit status checks at the time of review.

[hummbl-dev]

Batch 7 dependency-risk receipt � 2026-07-22

PORTFOLIO_MONITORING_DEPENDENCY_RISK
Risk tier: HIGH

Dependency map

• Parents/Blockers: Universal Source Program baseline (research#67)
• Blocks: Source adapter standardization across hummbl-bibliography and hummbl-research
• Cross-repo consumers: All source-adapter implementations in Universal Source Program

State

Adapter Contract and Conformance Suite v0.1 implementation. Part of standing program ledger #67. Candidate until reviewed/merged.

Non-mutations

No mutations.

[hummbl-dev]

---

Automated triage run (2026-07-24)

• Category: feature
• Priority: P1
• Severity: high
• Staleness: fresh
• Recommended next action: Review the candidate implementation against acceptance criteria and merge or close if the adapter contract and conformance suite are accepted.

Notes: This is marked "APPROVED EXECUTABLE FIRST SLICE — CLOSEABLE" and is the most actionable item in the knowledge-as-code queue. Merging it unblocks downstream adapter consumers across the Universal Source Program.