docs: chaque symbole dit d'où il vient

98 annotations posées à côté des déclarations, et un test qui les exige sur la
surface publiée. Elles portent trois choses : le niveau qui répond, la référence
amont, et la catégorie parmi les cinq.

La cinquième est celle qui manquait : declared-not-wired, quand la cible DÉFINIT
la forme et ne la câble pas. Neuf symboles en relèvent, dont readLinks — que
j'avais classé « notre invention » en raisonnant depuis l'absence, alors que
c'est le meilleur alignement disponible.

Les références citent un SYMBOLE, jamais une ligne : trois citations du document
avaient déjà pourri. Cinq corrections au passage, toutes vérifiées à la source —
un chemin ORM qui n'existe pas, deux plages de lignes fausses, et surtout
docs.* et subscribeDoc étiquetés PASSTHROUGH alors qu'ils sont alignés : nos
noms, plus un argument jamais transmis. La sémantique survit à la migration,
les sites d'appel non, et la nuance disparaissait sous une étiquette trop
flatteuse.

Le test échoue à l'annotation retirée, à la catégorie mal orthographiée, et à
une invention qui prétendrait citer une référence — vérifié en cassant les
trois. Il a aussi attrapé un défaut en lui-même : le gabarit de format placé
dans index.ts se faisait analyser comme une annotation.

La classification couvre l'interne qui prétend ressembler à la cible — tout
emulated-verifier — et exclut ce qui ne le prétend pas. La faute d'origine
portait sur une fonction non exportée ; n'être pas publié n'a protégé personne.

Quatre symboles ont résisté et sont annotés avec leur catégorie dominante, la
seconde nommée dans la note plutôt que lissée.

packages/polyfill/src/index.ts

@@ -43,8 +43,20 @@
  */
 
 // ── SDK-SHAPED — a target counterpart for every symbol ──────────────────────
-// At migration the build alias is removed and these resolve to the real SDK. The
-// per-symbol ruling, with its epistemic label, is in `docs/api-contract.md`.
+// At migration the build alias is removed and these resolve to the real SDK.
+//
+// WHAT each symbol is aligned on is recorded BESIDE IT, not in a document that drifts:
+//
+//   // @provenance <name> kind=<kind> level=<1|2|3|none> ref=<path:symbol|none> — <note>
+//
+// `level` numbers the target's stack from the bottom (1 engine, 2 wasm binding /
+// `@ng-org/web`, 3 JS ORM); `ref` cites a SYMBOL in `nextgraph-rs`, never a line number.
+// `kind` is closed: `passthrough` (upstream's own symbol, name and shape), `aligned` (our
+// name or ergonomics, upstream's semantics), `declared-not-wired` (upstream DEFINES the
+// shape and constructs it nowhere — an absence, which is NOT evidence the thing is ours),
+// `invention` (nothing answers, a documented bet), `divergent` (upstream does this, we do
+// it differently). Pinned by `test/provenance.test.ts`; the reasoning behind each ruling
+// stays in `docs/api-contract.md`, and where the two disagree the annotation wins.
 
 // A type is published only when a PUBLISHED SIGNATURE uses it. `export *` published
 // eight in one gesture (2026-08-10: it was a blanket re-export), of which two named
@@ -81,8 +93,13 @@ export * as storeRegistry from "./surface/placement";
 // SDK type re-exports — so the app imports these from @ng-eventually/polyfill too, not from
 // @ng-org. `export type` is ERASED at build, so this adds NO runtime @ng-org import to
 // the lib (no risk of a duplicate SDK copy in the bundle).
+// @provenance ShapeType kind=passthrough level=3 ref=sdk/js/shex-orm/src/types.ts:ShapeType
+// @provenance BaseType kind=passthrough level=3 ref=sdk/js/shex-orm/src/types.ts:BaseType
+// @provenance Schema kind=passthrough level=3 ref=sdk/js/shex-orm/src/types.ts:Schema
 export type { ShapeType, BaseType, Schema } from "@ng-org/shex-orm";
+// @provenance DeepSignalSet kind=passthrough level=3 ref=sdk/js/alien-deepsignals/src/types.ts:DeepSignalSet
 export type { DeepSignalSet } from "@ng-org/alien-deepsignals";
+// @provenance NG kind=passthrough level=2 ref=sdk/js/web/src/index.ts:NG — 88 members, all forwarded; the proxy adds none and removes none
 export type { NG } from "@ng-org/web";
 
 // ── POLYFILL-ERA — THE DELETION LIST ────────────────────────────────────────
@@ -150,4 +167,5 @@ import { makeNg } from "./surface/ng-proxy";
  * `Record<string, any>` until 2026-08-14, which announced a different surface from the one
  * it forwards to: an application got no completion and no check on any of the 88 members.
  */
+// @provenance ng kind=passthrough level=2 ref=sdk/js/web/src/index.ts:ng — a Proxy over the injected real `ng`; only `sparql_update` is overridden (the emulated write guard)
 export const ng: NG = makeNg();