Ingest source units and supporting material

Type: ../../types/design-proposal.md

Archived (see archive README). Adopted by ADR 072: the live source authority and primary/secondary design now reside in that ADR, the source collection contract, and the ingest-report type. What remains here is the dated pre-migration state and corpus observations that the decision was tested against.

Current state (as of 2026-08-22)

  • The ingest-report type required one repository-relative source_snapshot string. The paired tracked snapshot supplied the canonical source URL, capture metadata, and genre; the ingest carried no primary checksum.
  • ADR 045 made the snapshot the single genre authority and required ingestion to edit that value when closer reading changed the classification.
  • The ingest type optionally accepted code_revisions, an array of immutable GitHub commit URLs. Three ingests used it.
  • The paper-with-code procedure treated the version-pinned paper as primary and repositories as corroborating implementation evidence. It already allowed several repositories when they implemented distinct claim-bearing parts.
  • The directory-ingest procedure treated one ephemeral, usually ignored directory as a source unit. That directory could contain a repository, a paper with supplements, or grouped captures, while the durable report recorded only an upstream pin where one existed.
  • Ordinary tracked snapshots, ignored repository checkouts, and grouped working copies therefore used different storage and capture paths while producing the same ingest-report type. No general durable relation stated why an additional external resource belonged to the primary source or what evidential role it played.

Corpus observations behind adoption

  • Ordinary ingests remained single-source in practice, so an empty companion structure would have taxed the common case.
  • The three code-grounded ingests established a real multi-resource case, and the existing procedure's several-repository allowance ruled out a fixed document-plus-one-repository pair.
  • Repository evidence qualified implementation claims without becoming co-authority for the paper's title, genre, reported results, or limitations.
  • Directory ingestion could conceal arbitrary member cardinality, but the corpus supplied no worked case that required a genuinely co-equal primary bundle.