Sylvain Duchesne
3.6 KiB
id, title, parent, depends_on, created, claimed_by, claimed_at, blocked
| id | title | parent | depends_on | created | claimed_by | claimed_at | blocked |
|---|---|---|---|---|---|---|---|
| T01.a | A provenance annotation for a target announced but not yet written | T01 | 2026-09-16 | null | null | false |
Description
Extend the @provenance mechanism so that a symbol aligned on a target its developers have announced but not yet written can be annotated honestly, and make the reference requirement enforced.
Why this runs first. Every later child in this batch annotates at least one symbol that has no upstream path:symbol to cite — useShapeQuery has zero occurrences in nextgraph-rs. The weakness is recorded, deliberately unfixed, in .project/rules/nextgraph/surface-mirrors-the-sdk.md § "The gap that same example exposes": an author holding the strongest possible justification has only two bad moves left — cite an approximate symbol, which is precisely the readUnion failure, or declare invention, which understates the alignment and tells a later reader the shape is ours to change. Fix the mechanism before anyone has to use it.
Files in scope: packages/polyfill/test/provenance.test.ts (the format and its checks), the @provenance header block in packages/polyfill/src/index.ts, the kind table in .project/rules/nextgraph/no-divergence-from-nextgraph.md (the taxonomy lives there and must gain the same entry), and any existing annotation whose kind changes under the new taxonomy.
This child does NOT change the published surface. No symbol is added, removed or re-signed, so there is no contract edit and no version bump here. Do not touch .project/concepts/app-contract/polyfill-surface/contract_polyfill-surface.md — the children that change the surface each own their own edit to it.
Open questions — record the decision beside the code, do not guess a design:
- "A mandatory reference on every function, which must resolve" collides with a reason already written down.
test/provenance.test.tsstates, at length, that it deliberately does not check therefpath exists on disk:nextgraph-rsis a sibling checkout that may be absent on another machine, and a test that goes red for that reason teaches nothing — it just trains people to skip it. Decide what "must resolve" means here (a well-formed citation into a named checkout; resolve when the checkout is present and skip otherwise; resolve against a pinned commit) and record the reasoning next to the test. If it cannot be settled from the doctrine leaves, stop and ask rather than inventing a checker that will be skipped. - What the new kind is called, and what it takes as evidence. There is no
file:symbol, so the citation has to be the statement itself — whose statement, and where it was made. Neither existing kind fits:declared-not-wiredneeds a declaration in the tree,reserved-nameneeds a name in the tree. Name it so it can never be read asinvention, because the whole point is that it is the strongest justification, not the weakest.
Pass condition. The hard gate below, plus: every published symbol still carries a well-formed annotation; the new kind is exercised by a test case (its first real annotation belongs to T01.c, which reads this child's ## Result before annotating); and the taxonomy in the rule file and the one in the test agree.
Hard gate: bun test → 0 fail; bunx tsc --noEmit -p packages/polyfill/tsconfig.json → exit 0; bunx tsc --noEmit -p packages/polyfill/e2e/tsconfig.json → exit 0; python3 ~/.claude/skills/concept/lint.py → 0 ERROR. Anti-cheat: no any, no @ts-ignore, no deleting or skipping a test, no widening an assertion.