Sylvain Duchesne
34 lines
3.6 KiB
Markdown
34 lines
3.6 KiB
Markdown
---
|
|
id: T01.a
|
|
title: A provenance annotation for a target announced but not yet written
|
|
parent: T01
|
|
depends_on: []
|
|
created: 2026-09-16
|
|
claimed_by: null
|
|
claimed_at: null
|
|
blocked: 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:**
|
|
|
|
1. *"A mandatory reference on every function, which must resolve"* collides with a reason already written down. `test/provenance.test.ts` states, at length, that it deliberately does **not** check the `ref` path exists on disk: `nextgraph-rs` is 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.
|
|
2. 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-wired` needs a declaration in the tree, `reserved-name` needs a name in the tree. Name it so it can never be read as `invention`, 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.
|
|
|
|
## Progress
|
|
|
|
## Result
|