Epic B: Source Adapter SDK — common interface, provenance hooks, and conformance fixtures

[hummbl-dev]

Parent

• Standing program ledger: https://github.com/hummbl-dev/hummbl-research/issues/67

Status

CLOSEABLE PROGRAM EPIC — CANDIDATE INTERFACE — NON-CANONICAL UNTIL REVIEWED

Objective

Define the common adapter contract used to discover, resolve, retrieve, snapshot or reference, normalize, verify, cite, refresh, and invalidate records from heterogeneous public and authorized-private sources.

The SDK must preserve source-specific semantics. A uniform interface must not flatten a paper, Git commit, government filing, archived page, dataset version, transcript segment, and private connector object into an indistinguishable text blob.

Required contract

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

Each adapter must explicitly declare supported, unsupported, restricted, and authorization-gated operations.

Required deliverables

• adapter interface specification;
• capability-declaration schema;
• normalized result envelope linked to the universal source registry;
• provenance hooks for canonical URI, stable identifier, version, checksum, retrieval time, and transformation lineage;
• error and failure taxonomy;
• rate-limit, retry, pagination, and partial-result behavior;
• external-reference-only versus bounded-snapshot behavior;
• authentication and secret-handling boundary;
• public/private data-plane marker;
• conformance fixtures and validator;
• reference adapters spanning at least API, repository, archive, multimedia, and connector patterns;
• adapter_conformance_receipt.v0.1 integration with execution-receipts.

Mandatory failure cases

• ambiguous identity resolution;
• mutable record presented as immutable;
• missing license or privacy posture;
• unauthorized connector access;
• rate limiting and pagination truncation;
• unavailable transcript or full text;
• stale or superseded version;
• checksum mismatch;
• malformed upstream metadata;
• source deletion or correction;
• partial retrieval presented as complete.

Acceptance criteria

• An adapter can be tested without live production credentials through deterministic fixtures.
• Unsupported operations fail explicitly rather than silently degrading.
• Every result carries a registry identity and provenance envelope.
• Exact source locators survive normalization.
• Public and private records cannot be confused by downstream consumers.
• Conformance tests cover positive, negative, and adversarial behavior.
• At least five structurally different reference adapters pass the suite.
• Receipt generation is deterministic and reviewable.

Non-goals

• one universal parser for every content type;
• embedding-generation policy;
• uncontrolled bulk mirroring;
• hiding source-specific restrictions behind a generic success response.

[hummbl-dev]

First approved implementation slice

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

This child issue implements the v0.1 adapter contract, capability manifest, provenance envelope, failure taxonomy, deterministic conformance fixtures, and receipt profile. Keep this epic open for broader SDK and provider-binding work after the first slice closes.