From f202ea80a94f52c5a43b114498de9d84cfb60066 Mon Sep 17 00:00:00 2001 From: Mark Beacom Date: Wed, 5 Aug 2026 19:05:25 -0400 Subject: [PATCH] docs(catalog): the provenance gap is closed, so stop describing it as open MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase E flagged that once the data-model §10 reconciliation landed, its module notes would be stale rather than wrong - they would describe a gap the contract had since closed. §10 merged as 86ddeb5 (#91), so they are. provenance.ts's module note now records that the gap was reported while implementing the module and that the contract has since been reconciled to match: §10 states provenance is a declaration about the source, carried onto every derived entity and vacuous for annotation-absent ones, that only the pair (ownershipState, provenance) is unambiguous, and that the declaration is required with no default. The reasoning in that note is therefore the contract's, not a local workaround - which is the part worth correcting, since a reader would otherwise think the implementation was compensating for a spec that had not caught up. Deliberately NOT touched: sc-009.test.ts. Its note is about accept-corpus materialization, which is genuinely still open, and acceptCorpusIsMaterialized is designed to fail the day someone vendors the corpus. Phase F is vendoring it now, so that test tripping is the design working rather than a defect. Docs only, no behaviour change. bun test 1721 pass / 0 fail, typecheck clean, check:freeze-hashes ok. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../catalog-backstage/src/envelope/provenance.ts | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/packages/adapters/catalog-backstage/src/envelope/provenance.ts b/packages/adapters/catalog-backstage/src/envelope/provenance.ts index 1631479b..a9e785f1 100644 --- a/packages/adapters/catalog-backstage/src/envelope/provenance.ts +++ b/packages/adapters/catalog-backstage/src/envelope/provenance.ts @@ -47,7 +47,7 @@ * source is invalid input, not a guess. See `failure/triggers.ts` for why that lands on * the `other-invalid-input` backstop rather than on one of the fourteen named classes. * - * # One gap, reported rather than papered over + * # What `provenance` means when there is no annotation * * The domain has **no** value for "this descriptor carries no annotation at all", and * `ownershipState: 'annotation-absent'` is the overwhelmingly common real-corpus case @@ -69,7 +69,12 @@ * asserts that a third party adopted the annotation. {@link isAdoptionClaim} names that * pair so a check can assert on it directly. * - * The gap itself belongs to `data-model.md` §10 and is reported, not fixed here. + * This was reported as a gap in `data-model.md` §10 while implementing this module, and + * **the contract has since been reconciled to match** (2026-08-05): §10 now states that + * `provenance` is a declaration about the *source*, carried onto every derived entity + * and **vacuous** for `annotation-absent` ones, that only the pair is unambiguous, and + * that the declaration is required with no default in either direction. The reasoning + * above is therefore the contract's, not a local workaround. * * @see `specs/010-catalog-backstage/data-model.md` §10 * @see `specs/010-catalog-backstage/spec.md` FR-043 @@ -210,9 +215,9 @@ export function provenanceFor( * `annotation-absent` is never an adoption claim whatever its provenance, because * there is no annotation to have been adopted. * - * This is the predicate that makes the module note's gap safe, and it is exported so a - * check can assert on the pair rather than on `provenance` in isolation — which is - * where the misreading would otherwise happen. + * This is the predicate `data-model.md` §10 names when it says only the pair is + * unambiguous, and it is exported so a check can assert on the pair rather than on + * `provenance` in isolation — which is where the misreading would otherwise happen. */ export function isAdoptionClaim( ownershipState: OwnershipState,