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/surface/inbox.ts

@@ -58,6 +58,7 @@ import type { Nuri, NuriLike, PrincipalId, ReadCap } from "../model/types";
 // --- deposit model --------------------------------------------------------
 
 /** One deposit as materialized from an inbox document. */
+// @provenance inbox.Deposit kind=aligned level=1 ref=engine/net/src/types.rs:InboxMsgBody — `from` optional like `from_inbox`, and NO target-document field because the address identifies the recipient repo; `payload`/`ts` have no upstream field
 export interface Deposit {
   /** The sender, if identified; `null` when the deposit was anonymous. */
   from: PrincipalId | null;
@@ -68,6 +69,7 @@ export interface Deposit {
 }
 
 /** Options for {@link post}. `from` and `ts` are both optional. */
+// @provenance inbox.PostOptions kind=aligned level=1 ref=engine/net/src/types.rs:InboxMsgBody — same shape as Deposit on the way in; `from: null` mirrors `from_inbox: None`
 export interface PostOptions {
   /**
    * Who is depositing. Omit (or pass `null`) for an ANONYMOUS deposit; pass a
@@ -169,6 +171,7 @@ function readBindings(result: unknown): Array<Record<string, { value: string }>>
  * another's identity. This check is redundant once the seal enforces it, but
  * until then it closes the spoof the shared wallet would otherwise allow.
  */
+// @provenance inbox.post kind=aligned level=1 ref=engine/verifier/src/inbox_processor.rs:post_to_inbox — the act exists at level 1 and the broker routes it (`inbox_post`); no JS surface at level 2/3. An arbitrary `payload` is a BET — `InboxMsgContent` has no generic variant
 export async function post(targetInboxLike: NuriLike, opts: PostOptions): Promise<void> {
   const targetInbox = toNuri(targetInboxLike, "inbox.post");
   const current = getCurrentUser();
@@ -269,6 +272,7 @@ export async function post(targetInboxLike: NuriLike, opts: PostOptions): Promis
  * address in advance, because an application must name a document or a person, never an
  * inbox.
  */
+// @provenance inbox.postToDocument kind=declared-not-wired level=1 ref=engine/repo/src/repo.rs:Repo — every repo carries `inbox: Option<PrivKey>`, but nothing opens one for a plain document. Resolving the address by READING the document is our divergence — see `publishInboxAddress`
 export async function postToDocument(docLike: NuriLike, opts: PostOptions): Promise<void> {
   const doc = toNuri(docLike, "inbox.postToDocument");
   const target = await documentInboxAddress(doc);
@@ -364,6 +368,7 @@ function capOfPayload(payload: unknown): ReadCap | null {
  * The shape is right; the implementation is absent at both ends, so we emulate it
  * meanwhile.
  */
+// @provenance inbox.share kind=declared-not-wired level=1 ref=engine/net/src/types.rs:ContactDetails — `read_cap: Option<ReadCap>` is defined; building the message is `unimplemented!()`, its only caller passes `with_readcap: false`, and the receiving arm never reads the field
 export async function share(doc: NuriLike, toUser: string): Promise<void> {
   const target = toNuri(doc, "inbox.share");
   // Names the DOCUMENT and the PERSON — the two things an application has. Neither the
@@ -431,6 +436,7 @@ export async function share(doc: NuriLike, toUser: string): Promise<void> {
  * no more reason to handle an inbox address than a depositor does. Empty when the
  * document has no inbox, which is a state and not an error.
  */
+// @provenance inbox.readForDocument kind=divergent level=1 ref=engine/verifier/src/inbox_processor.rs:process_inbox — upstream an inbox is a queue the verifier consumes and APPLIES; this enumerates it instead, non-destructively
 export async function readForDocument(docLike: NuriLike): Promise<Deposit[]> {
   const doc = toNuri(docLike, "inbox.readForDocument");
   const address = await documentInboxAddress(doc);
@@ -484,6 +490,7 @@ async function assertOwnInbox(targetInbox: Nuri, op: string): Promise<void> {
  * watching its inbox gets them, and the resulting change re-triggers the
  * reads that were empty for want of that cap.
  */
+// @provenance inbox.read kind=divergent level=1 ref=engine/verifier/src/inbox_processor.rs:process_inbox — same: a re-readable list where upstream has a consumed queue. Coding a mailbox UI on this is coding against emulation detail
 export async function read(targetInboxLike: NuriLike): Promise<Deposit[]> {
   const targetInbox = toNuri(targetInboxLike, "inbox.read");
   await assertOwnInbox(targetInbox, "read");
@@ -578,6 +585,7 @@ export async function read(targetInboxLike: NuriLike): Promise<Deposit[]> {
  * `discovery.readIndex` does. Idempotent per session (no polling); a no-op open on
  * the unit fake-ng path (no `doc_subscribe`) so `bun test` is unaffected.
  */
+// @provenance inbox.readSynced kind=divergent level=1 ref=engine/verifier/src/inbox_processor.rs:process_inbox — same as `read`, gated on the sync barrier first
 export async function readSynced(targetInboxLike: NuriLike): Promise<Deposit[]> {
   const targetInbox = toNuri(targetInboxLike, "inbox.readSynced");
   // Marks the cold, connection-triggered entry point in the trace — the BARRIER
@@ -604,6 +612,7 @@ export async function readSynced(targetInboxLike: NuriLike): Promise<Deposit[]>
  * second tab, a reconnect) costs nothing. Returns the consumer deposits, exactly as
  * {@link read} does — Links are never surfaced.
  */
+// @provenance inbox.processInbox kind=aligned level=1 ref=engine/verifier/src/inbox_processor.rs:process_inbox — unseal-and-apply: Links are filed durably and never surfaced. Returning the remaining deposits is the divergent half it shares with `read`
 export async function processInbox(targetInboxLike: NuriLike): Promise<Deposit[]> {
   const targetInbox = toNuri(targetInboxLike, "inbox.processInbox");
   const deposits = await readSynced(targetInbox);
@@ -711,6 +720,7 @@ async function processForOwner(targetInbox: Nuri): Promise<void> {
  * there is no polling. (The inbox document is a single doc, so this is immune to
  * the ORM fan-out hang — see {@link subscribeDoc}.)
  */
+// @provenance inbox.watch kind=divergent level=1 ref=engine/verifier/src/verifier.rs:inbox — upstream a message is applied on arrival and there is nothing to subscribe to; this pushes the raw deposit list on every change
 export function watch(
   targetInboxLike: NuriLike,
   onDeposits: (deposits: Deposit[]) => void,