refactor(vocabulary): les noms publiés parlent la langue de la cible, et un test le tient

La correction de nomenclature du 2026-07-30 — en amont un *wallet* n'est qu'un
trousseau, ce qui possède des stores est un **user** (un *site*) — s'était faite
à la main. `walletInbox` y a échappé et a vécu des semaines, en faisant des
dégâts : le nom rendait « une inbox par wallet » évident, masquant qu'un user en
a **deux** en amont (repos de store public et protected, les deux seuls
`AddInboxCap` du moteur). Une discipline appliquée à la main en oublie un ; un
test non.

D'où `test/vocabulary.test.ts` : tout nom publié est bâti sur des mots que la
CIBLE emploie — vérifiés dans `nextgraph-rs` — ou porte un marqueur disant
POURQUOI il n'existe qu'ici (`virtual`, `physical`, `shim`, `emulated`,
`polyfill`), ce qui dit aussi quand il disparaît. Un échec n'est pas « renommer
pour faire passer le test », c'est une question : la cible a-t-elle un mot pour
ça ? la chose n'existe-t-elle qu'ici ? le mot est-il vraiment de la glue ?

Ce que le test a trouvé, et les réponses :

- `walletInbox` → `userInbox`, avec l'écart de cardinalité écrit noir sur blanc
  plutôt que caché par le nom.
- `accounts` / `AccountRecord` / `AccountStorage` → `virtualUsers` /
  `VirtualUserRecord` / `VirtualUserStorage`, module `accounts.ts` →
  `virtual-users.ts`. « account » n'est pas de la cible : c'est notre mot pour
  l'utilisateur virtuel, et le marqueur le dit désormais.
- `readModel` → la fonction `readUnion`, exposée directement. « model » n'était
  ni de la cible ni de la glue, et le namespace ne tenait qu'une fonction.
- Le reste était du vocabulaire légitime à déclarer (`subject`, `base`,
  `schema`, `connected`, le modèle réactif de l'ORM).

Corrigé au passage, sur signalement du contrat interne : l'en-tête d'`open-repo`
justifiait son correctif par un mécanisme que le source contredit. Un repo absent
de `self.repos` lève bien `RepoNotFound`
(`engine/verifier/src/request_processor.rs:264,269`). Les 0 lignes observées
viennent d'ailleurs — `Verifier::load` repeuple `self.repos` depuis le stockage
sur un profil persistant (`verifier.rs:535-560`), et notre propre `readDoc`
attrape toute erreur et rend `[]`. Le correctif est bon, le diagnostic écrit à
côté ne l'était pas.

159 tests unitaires, typecheck src/test/e2e vert, e2e 40/40 contre le broker.

packages/client/test/vocabulary.test.ts

@@ -0,0 +1,127 @@
+/**
+ * The published names may only use words the TARGET uses, or a marker that says why
+ * they exist here.
+ *
+ * ── Why this is a test and not a rule ─────────────────────────────────────
+ * The library corrected its vocabulary on 2026-07-30 — upstream a *wallet* is only a
+ * keyring, and what owns stores is a **user** (a *site*) — by a manual pass over the
+ * code and docs. `walletInbox` survived that pass and lived on for weeks, and it did
+ * damage: the name made "one inbox per wallet" sound obvious, hiding that a user
+ * upstream has **two** (public store repo and protected store repo — the only two
+ * `AddInboxCap` commits in the engine, `engine/verifier/src/site.rs:128,149`). A
+ * discipline applied by hand misses one; a test does not.
+ *
+ * So this pins the naming half of the design principle (`README.md`): a name either
+ * belongs to the target's vocabulary — in which case it needs no translation and
+ * survives migration — or it carries a marker saying WHY it exists only here, which
+ * also says when it disappears.
+ *
+ * ── What it checks, and what it deliberately does not ─────────────────────
+ * Only the PUBLISHED names, the ones a consumer application types. Internal names are
+ * held to the same intent but not mechanically: the folder they live in already states
+ * their fate, and pinning every internal identifier would fight refactoring for little.
+ */
+import { test, expect } from "bun:test";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/**
+ * Words the TARGET itself uses, verified in `nextgraph-rs`. A published name built
+ * from these needs no translation at migration.
+ */
+const TARGET_WORDS = new Set([
+  // addressing and objects
+  "nuri", "doc", "docs", "document", "repo", "store", "stores", "branch", "graph",
+  "overlay", "cap", "caps", "read", "write", "link", "links", "shape", "shapes",
+  // actors and containers
+  "user", "users", "session", "wallet", "inbox", "inboxes", "site", "principal",
+  // scopes (upstream store types, `StoreRepo::from_type_and_repo`)
+  "public", "protected", "private", "group", "dialog", "scope",
+  // acts the target performs
+  "create", "subscribe", "unsubscribe", "query", "update", "post", "share", "open",
+  "fetch", "init", "watch", "sparql", "ng", "orm", "type", "types",
+  // RDF / SPARQL terms the engine's own query paths use
+  "subject", "base", "schema", "connected",
+  // the reactive model the ORM exposes (`OrmSubscription`, `DeepSignalSet`)
+  "observable", "deep", "signal", "set",
+]);
+
+/**
+ * Markers that name WHY something exists only in this library. Each says when it
+ * disappears, which a bare `fake`/`tmp` would not.
+ */
+const EMULATION_MARKERS = new Set(["virtual", "physical", "shim", "emulated", "polyfill"]);
+
+/** Glue with no domain meaning — never the load-bearing part of a name. */
+const NEUTRAL = new Set([
+  "get", "set", "is", "has", "to", "for", "of", "my", "own", "all", "by", "with",
+  "current", "reset", "configure", "config", "deps", "id", "ids", "address", "entity",
+  "list", "resolve", "assert", "escape", "literal", "iri", "record", "registry",
+  "change", "changed", "state", "value", "data", "info", "count", "the", "a", "an",
+  "options", "opts", "result", "error", "signal", "filter", "placement", "and", "or",
+  "make", "use", "on", "off", "from", "into", "at", "in", "out", "up", "down",
+  // `union` is OURS — the bounded multi-document read — but it names an operation,
+  // not a domain notion a consumer would have to unlearn. `eventually` is the
+  // library's own name.
+  "union", "eventually",
+]);
+
+/** `documentInboxAddress` → ["document","inbox","address"] ; `NG` → ["ng"]. */
+function words(name: string): string[] {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+    .split(/[\s_]+/)
+    .map((w) => w.toLowerCase())
+    .filter(Boolean);
+}
+
+const SRC = path.join(import.meta.dir, "..", "src");
+
+/** Every identifier the two entry points publish, read from the `export` statements. */
+function publishedNames(): string[] {
+  const out = new Set<string>();
+  for (const entry of ["index.ts", "polyfill.ts"]) {
+    const text = fs.readFileSync(path.join(SRC, entry), "utf8");
+    // `export * as ns from "…"`
+    for (const m of text.matchAll(/export \* as (\w+) from/g)) out.add(m[1]!);
+    // `export { a, b as c }` / `export type { … }`, single- and multi-line
+    for (const m of text.matchAll(/export (?:type )?\{([^}]*)\}/g)) {
+      for (const raw of m[1]!.split(",")) {
+        const name = raw.trim().replace(/^type /, "").split(/\s+as\s+/).pop()?.trim();
+        if (name) out.add(name);
+      }
+    }
+    // `export const x` / `export function x` / `export interface x`
+    for (const m of text.matchAll(/export (?:declare )?(?:const|function|class|interface|type) (\w+)/g)) {
+      out.add(m[1]!);
+    }
+  }
+  return [...out];
+}
+
+test("every published name is built from the target's vocabulary, or carries an emulation marker", () => {
+  const offenders: string[] = [];
+  for (const name of publishedNames()) {
+    const ws = words(name);
+    // A marker anywhere in the name licenses the whole name: it declares the thing
+    // as ours and says when it goes.
+    if (ws.some((w) => EMULATION_MARKERS.has(w))) continue;
+    const unknown = ws.filter((w) => !TARGET_WORDS.has(w) && !NEUTRAL.has(w));
+    if (unknown.length > 0) offenders.push(`${name} → ${unknown.join(", ")}`);
+  }
+  // A failure here is not "rename to satisfy the test": it is a question. Does the
+  // target have a word for this? Use it. Does the thing exist only here? Say so with a
+  // marker. Is the word genuinely neutral glue? Add it to NEUTRAL, deliberately.
+  expect(offenders).toEqual([]);
+});
+
+test("no published name says `wallet` where the target says `user`", () => {
+  // The specific regression that motivated this file. `wallet` is a legitimate target
+  // word (a keyring IS a wallet upstream), so the generic check above cannot catch it —
+  // what is wrong is using it for the thing that owns stores and inboxes.
+  const wrong = publishedNames().filter((n) =>
+    /wallet/i.test(n) && /(inbox|store|doc|cap)/i.test(n),
+  );
+  expect(wrong).toEqual([]);
+});