docs: le contrat cesse d-enumerer l-etat de ses propres tags, et pose la regle

Une clause du Change policy enumerait quelles versions n-avaient pas de tag.
Poser un tag l-a rendue fausse dans l-heure. Elle est remplacee par la regle
qu-elle tenait lieu de dire - une version et son tag atterrissent ensemble -
plus la commande qui repond pour n-importe quelle version. Un engagement ne
doit pas porter un fait sur son propre depot qui se perime sans que personne
ne touche la feuille.

.gitignore

@@ -2,6 +2,7 @@ node_modules/
 dist/
 *.tsbuildinfo
 .DS_Store
+bun.lock
 bun.lockb
 
 # SDK e2e real-broker harness — dedicated wallet profile + bundle (never committed)

.project/VOCABULARY.md

@@ -4,15 +4,17 @@
 
 ```text
   «app-contract»
-   `reference`      a NURI that names a document and grants nothing — what an application circulates            (never: link, lien, share-link · see: contract_polyfill-surface)
-   `ReadCap`        upstream's word for what opens a document — a reference carrying its secret                 (never: token, credential, permission)
-   `polyfill-era`   a published symbol with no counterpart in the target SDK, deleted at migration              (never: transitional, shim-only · see: knowledge_what-an-app-deletes-at-migration)
+   `reference`       a NURI that names a document and grants nothing — what an application circulates                                  (never: link, lien, share-link · see: contract_polyfill-surface)
+   `ReadCap`         upstream's word for what opens a document — a reference carrying its secret                                       (never: token, credential, permission)
+   `shape read`      a read whose selector is a ShEx shape, i.e. which predicates an object carries, never a list of documents         (never: typed read, shape-based read, lecture par forme · see: knowledge_what-a-read-scope-is-upstream)
+   `document read`   a read selected by naming documents - upstream anchors ONE, so naming several is this package's own composition   (never: bulk read, union read, lecture par document)
+   `polyfill-era`    a published symbol with no counterpart in the target SDK, deleted at migration                                    (never: transitional, shim-only · see: knowledge_what-an-app-deletes-at-migration)
 
   «e2e-harness»
-   `journey`        one named end-to-end story in the applicative suite, reported pass or fail as a whole       (never: scenario, test case, spec)
-   `batch`          one run of a suite, which mints its own physical user and discards the previous one         (never: session, campaign)
+   `journey`         one named end-to-end story in the applicative suite, reported pass or fail as a whole                             (never: scenario, test case, spec)
+   `batch`           one run of a suite, which mints its own physical user and discards the previous one                               (never: session, campaign)
 
   «sign-in»
-   `settle`         decide which identity is acting, from the URL, storage, or the barrier — needs no session   (never: resolve identity, determine user, login · see: knowledge_settling-is-not-connecting)
-   `barrier`        the full-screen overlay this package mounts to hand out the wallet and take an identifier   (never: modal, popup, login screen)
+   `settle`          decide which identity is acting, from the URL, storage, or the barrier — needs no session                         (never: resolve identity, determine user, login · see: knowledge_settling-is-not-connecting)
+   `barrier`         the full-screen overlay this package mounts to hand out the wallet and take an identifier                         (never: modal, popup, login screen)
 ```

.project/concepts/app-contract/_overview.md

@@ -2,12 +2,14 @@
 type: overview
 summary: What an application may rely on from @ng-eventually/polyfill, and what it will have to delete
 triggers:
-  keywords: [polyfill, sdk, surface, contract, publish, published, entry, export, migration, unlearn, consumer, app-facing, inbox, deposit, IRI, urn, namespace, vocabulary, ontology, predicate]
+  keywords: [polyfill, sdk, surface, contract, publish, published, entry, export, migration, unlearn, consumer, app-facing, inbox, deposit, IRI, urn, namespace, vocabulary, ontology, predicate, orm, useShape, getObjects, insertObject, OrmSubscription, ngSession, read filter, docChannel]
   paths:
     - "packages/polyfill/src/index.ts"
     - "packages/polyfill/src/surface/**"
     - "packages/polyfill/src/emulated-verifier/machinery.ts"
     - "packages/polyfill/src/emulated-verifier/index-deposit.ts"
+    - "packages/polyfill/src/emulated-verifier/read-filter.ts"
+    - "packages/polyfill/src/emulated-verifier/open-repo.ts"
     - "packages/polyfill/README.md"
     - "examples/notebook/**"
     - "docs/api-contract.md"
@@ -19,6 +21,13 @@ vocabulary:
   - term: ReadCap
     gloss: upstream's word for what opens a document — a reference carrying its secret
     not: [token, credential, permission]
+  - term: shape read
+    gloss: a read whose selector is a ShEx shape, i.e. which predicates an object carries, never a list of documents
+    not: [typed read, shape-based read, lecture par forme]
+    see: knowledge_what-a-read-scope-is-upstream
+  - term: document read
+    gloss: a read selected by naming documents - upstream anchors ONE, so naming several is this package's own composition
+    not: [bulk read, union read, lecture par document]
   - term: polyfill-era
     gloss: a published symbol with no counterpart in the target SDK, deleted at migration
     not: [transitional, shim-only]
@@ -29,15 +38,20 @@ vocabulary:
 
 This library exists so an application can be **written today against the NextGraph that does not ship yet**, and keep its code when it does. Everything under this concept governs that boundary: what the package publishes, what a caller may rely on, what it must not, and what disappears at migration.
 
-The distinguishing question, asked at every choice — published signature as much as internal mechanism: **does the target do this?** If it does it differently, we do it their way, whatever that costs. *Would a caller have to unlearn it?* comes second, and measures how bad a divergence is — never whether one is allowed. See `rule_no-divergence-from-nextgraph`.
+The distinguishing question, asked at every choice — published signature as much as internal mechanism: **does the target do this?** If it does it differently, we do it their way, whatever that costs. *Would a caller have to unlearn it?* comes second, and measures how bad a divergence is — never whether one is allowed. See `.project/rules/nextgraph/no-divergence-from-nextgraph.md`.
 
 This repo is the **provider** of `polyfill-surface`; consuming applications live in other repos, pull the engagement, and declare back what they actually consume — one `usage_<consumer>.md` beside the contract, in the interface folder. The per-symbol ruling, with an epistemic label on every target-side claim, stays here in `docs/api-contract.md` — that is maintainer material, not the engagement.
 
 ## Read first
 
 - `polyfill-surface/contract_polyfill-surface` — the engagement itself, written from the caller's point of view.
-- `rule_no-divergence-from-nextgraph` — the test that decides what may be built at all.
+- `.project/rules/nextgraph/no-divergence-from-nextgraph.md` — the test that decides what may be built at all.
 - `knowledge_what-an-app-deletes-at-migration` — the two fates a published symbol can have.
 - `knowledge_what-an-iri-says-upstream` — the same two fates for a written *triple*: NextGraph's own vocabulary, ours, and which of our IRIs must outlive the migration.
+- `knowledge_what-a-read-scope-is-upstream` — what the target offers for reading many objects at once, and the one question it cannot express.
+- `knowledge_what-a-failed-read-answers-upstream` - the other half of the same question: what an unreachable, an unsynced and an empty document each answer, and which of them a caller can tell apart.
+- `knowledge_what-the-orm-writes-and-deletes-upstream` — the writing half: removal is a set mutation wired end to end, and an ORM write never passes through `sparql_update`.
 - `knowledge_what-an-inbox-is-upstream` — what the target actually offers around inboxes, and where a choice of ours begins.
 - `knowledge_who-processes-an-inbox` — the division of labour along a deposit's path: what this package applies, what it merely delivers, and what a layer above owes itself.
+- `knowledge_what-stands-between-identities` - the one module that isolates identities sharing a wallet: two views repaired together, a decided-or-refused default, and the hole host introspection leaves open.
+- `knowledge_one-answer-to-whether-a-document-is-open` - openness is asked of the document's one real subscription and never remembered, and the sweep that established it counted eleven records where the problem had named three.

.project/concepts/app-contract/bug_useshape-live-read-needs-a-newer-broker.md

@@ -1,52 +0,0 @@
----
-type: bug
-summary: A live read through the published `useShape` never starts against a broker deployed before `orm_start` was renamed `orm_start_graph` — it stays empty and pending forever, with one console error as the only trace
-severity: major
-opened: 2026-08-17
-last_checked: 2026-08-17
----
-
-# `useShape` opens no live read against the deployed broker
-
-The published `useShape` is a passthrough to `@ng-org/orm`'s hook (`packages/polyfill/src/surface/use-shape.ts`) — this package adds the read filter and forwards. Against the broker deployed today, the subscription that hook opens **never starts**: its set stays empty, its readiness never settles, no engine update ever arrives, and the only trace is one `console.error`. An application sees "this scope holds nothing", indefinitely, which is the exact confusion the rest of the read surface is built to prevent.
-
-The cause is upstream, in NextGraph. **Nothing in this package can work around it** — the failure is a name lookup two hops below our surface.
-
-## The mechanism — one method name, kept in three places by hand
-
-VERIFIED 2026-08-17 by reading `/home/sylvain/projects/nextgraph/nextgraph-rs` at `213338f6`.
-
-A live ORM read is one call, and it is streamed: the engine pushes into a callback rather than answering once. Nothing in the transport infers that — each hop looks the method up in a **hand-maintained table** mapping method name to the index of its callback argument, and a method missing from the table takes the plain request/response branch instead.
-
-1. `sdk/js/orm/src/connector/GraphOrmSubscription.ts` — the `OrmSubscription` constructor is the only place a live graph read begins: `ng.orm_start_graph(scope.graphs, scope.subjects, shapeType, session.session_id, this.onBackendMessage)`. Five arguments, callback last. `useShape` reaches it through `OrmSubscription.getOrCreate` (`sdk/js/orm/src/frontendAdapters/react/useShape.ts`).
-2. `sdk/js/web/src/index.ts` — the application-side `ng` proxy. `streamed_api` must contain the method, or `rpc` posts the arguments verbatim to the parent window, callback included. A function is not structured-cloneable, so that post throws.
-3. `sdk/js/api-web/main.ts` — the broker-side proxy, an independent copy of the same table. Same fallback into `myWorker.postMessage`, same throw.
-
-The hops between the two tables carry no table of their own and cannot repair a mismatch: `infra/ngnet/auth/src/main.ts` forwards `{method, args, streamed, port}` unchanged, and `engine/broker/auth/src/App.svelte` re-appends a callback **only** when `streamed` is true.
-
-**The name changed.** Both tables keyed the method as `orm_start` until commit `d5ecd0fd` (2026-01-16, "refactor discrete orm for yjs") renamed it to `orm_start_graph` in both files at once — while the ORM had been calling `orm_start_graph`. A build made before that commit therefore does not recognise the method a live read needs.
-
-**The application side is already correct**, and that is what isolates the defect. This package pins `@ng-org/web@0.1.2-alpha.13` (`packages/polyfill/package.json`), which is the version at `213338f6` — the rename is in it. `@ng-org/api-web` is `private: true` and has never been version-bumped past `0.1.2`: it is **not published**, it ships only inside the broker build. Its table is whatever the operator last deployed, and no consumer can pin it.
-
-**Why it fails in silence:** `orm_start_graph` is awaited inside a `try` whose `catch` is `console.error(e)`, and `resolveReady()` is called on one path only — the arrival of initial data. A rejected start leaves the readiness promise pending forever and the set permanently empty. This is the same upstream property already recorded in `docs/api-contract.md` (a failed read *is* an eternal pending upstream), reached here through a different door.
-
-## What is affected, and what is not
-
-- **Affected:** the published `useShape`, and only it.
-- **Not affected:** `watchShape`, `subscribeDoc`, `subscribeDocs`, `readUnion`. These open one `doc_subscribe` per document, and `doc_subscribe: 2` has been in both tables continuously under a stable name. `watchShape` is built on that path, not on the ORM subscription — it is a working reactive read today.
-
-That is why the library's own suites and the reference application do not show it: nothing in this package calls `useShape` internally.
-
-## Not verified
-
-The deployed broker's table was **not read**. `https://nextgraph.net/redir/` returns a page containing none of the protocol markers, so it is not the bundle that holds it, and probing further was out of mandate. What is established is the mechanism and its exact precondition — a broker built before `d5ecd0fd` — not that the running deployment sits before it. The symptom was reported by the consuming application, not reproduced here.
-
-## What to do
-
-- **Do not build on live `useShape`.** Use `watchShape` for a reactive read, `readUnion` for a one-shot one. This is stated in the contract's `## Non-guarantees` so a consumer meets it without reading this leaf.
-- **The fix is not ours.** It is a NextGraph deployment: rebuild and redeploy the broker from a source at or after `d5ecd0fd`. Nothing to change in this repository, and nothing to open upstream from here — report it, do not patch around it.
-- **To check whether it is closed:** open a live `useShape` against the deployment and watch for an initial payload. A permanently empty set with one `console.error` naming `orm_start_graph` means the table is still stale.
-
-## The shape worth remembering
-
-A method name duplicated across three independently-deployed artifacts, with a **silent** fallback when they disagree, is a defect that cannot be caught by any one repository's tests. Renaming it in the two tables in one commit fixed the source; it did not fix anything already running. Anything this package routes through a streamed method inherits the same exposure — that is the reason `subscribeDocs` composing per-document `doc_subscribe` is worth more than it looks.

.project/concepts/app-contract/knowledge_one-answer-to-whether-a-document-is-open.md

@@ -0,0 +1,66 @@
+---
+type: knowledge
+summary: Openness is the state of the document's ONE real subscription, asked and never remembered - the sweep that established it counted eleven pieces of state where the problem had named three, and the lesson is to count exhaustively, including what merely implies the fact, before designing
+last_checked: 2026-10-01
+---
+
+# One answer to whether a document is open in this session
+
+"Is this document open in this session" must have exactly ONE answer. It had several, and they disagreed - six rounds of work on the predecessor task kept finding the same defect in a narrower corner before anyone named the cause. This leaf records the invariant that closed it, why each displaced record had to GO rather than be repaired, and the counting discipline that is the transferable part.
+
+## The invariant, and where it is written
+
+**The answer is the state of the document's ONE real subscription - `docChannel(nuri)` in `surface/subscribe.ts` - and `emulated-verifier/open-repo.ts` records only the bootstrap open it ASKED FOR: the listener it took out, which fan-out that listener joined, and the bounded wait around it. Never whether that listener became a live channel or crossed a barrier.** So no answer in `open-repo` can outlive the channel it describes, because none is kept.
+
+It is written three times, each beside the state it governs: `open-repo.ts`'s header block, `subscribe.ts`'s header under *This module OWNS "is this document open in this session"*, and on the `DocChannel` type. A branch upstream holds exactly one subscriber - a second `doc_subscribe` EVICTS the first - which is why the fan-out exists at all and why it is the physical truth: a listener exists or it does not.
+
+`docChannel` answers from the fan-out and nothing else. `establishing` says an attempt STANDS (left true after success, so on its own it cannot tell "asked" from "open"), `realUnsub` says that attempt's call ANSWERED, `lastState` is the barrier, `incarnation` says WHICH fan-out stands so a caller holding a listener can tell its entry was replaced under it, and `attempt` qualifies the rest so a late outcome can tell whether it is still the one being waited on.
+
+## The count was ELEVEN, and the gap is the finding
+
+The problem was stated with THREE records, and that number is still in the published contract's `1.0.0-dev.10` entry - **it is the count of the opening hypothesis, not of the finding, and the gap is the point.** An inventory pass over every module-level `Map`/`Set` in `src`, plus every reader, then checked by hand, found eleven.
+
+Five in `open-repo.ts`, all deleted: `held` ("this session holds a live bootstrap subscription"), `syncState` (the barrier), `inFlight` ("an open is under way", read as a short-circuit), `settleInFlight` (the same set of documents with a different payload - a second record of `inFlight`), and `registryEpoch` plus each open's `myEpoch` (a record ABOUT the records, which existed only because the records did). **The last two merely IMPLIED openness through a short-circuit and had never been counted by anyone**, including six adversarial rounds on the predecessor task.
+
+Five in `surface/subscribe.ts`, which survive as the single answer: `fanOuts`, `establishing`, `realUnsub`, `lastState` and `attempt`. **`lastState` turned out to have been a second barrier record all along, and the correct one** - it is forgotten when the channel is released, when the session changes under it, and when the attempt that produced it fails, which is exactly when a barrier stops meaning anything.
+
+The eleventh is `boundSessionId`, counted and KEPT: it is not per-document, and says which session the registry belongs to.
+
+Also counted and ruled OUT, each with its reason, because ruling out is part of counting: `inbox-observer`'s `obs.inboxes` (a different fact - watched by the observation, not open in the verifier - and its teardown is already paired with the one that broke the others), `public-store`'s `attempted` (nominally a cap memo, but a memo hit skips an `ensurePhysicalRepoOpen` inside it, and nothing resets it on `configure` - left alone and reported), and the in-flight or being-serviced maps in `branch-registers`, `inbox-drain`, `inbox-processor`, `connect`, `surface/inbox` and `account-registry`. ORM land holds no openness record at all: `orm_start_graph` is deliberately unused, and there is no graph registry or refcount anywhere in `src`.
+
+## Why two records of one fact cannot be reconciled
+
+They disagreed in both directions, and each failure was measured:
+
+- **A reset cleared one and left the other standing.** `configure()` is PUBLISHED and calls `resetDocSubscriptions()`, which drops every fan-out listener and tells `open-repo` nothing. `held` kept a dead entry and `syncState` kept `"synced"`, so the short-circuit skipped the re-open for ever: after a second `configure`, a named `shape read` over a previously synced document made zero `doc_subscribe` calls and published `{isPending:false, isSuccess:true, data:[]}` - an empty success asserting AUTHORITY for a document the session had never subscribed, unrecoverable even through a refetch.
+- **A subscribe the broker REJECTED was recorded as opened**, blocking the retry the subscription layer already offered through a channel nothing had wired. Measured with a `doc_subscribe` rejecting at 200ms against a 20ms fallback: one subscribe call after the retry where the claimed behaviour needs two.
+
+The repair is therefore deletion, not notification: nothing outside `subscribe.ts` records openness, so teardown is safe BY CONSTRUCTION and no cross-module notification was added. **A guard at the READER cannot fix a fact that is wrong at the source** - the first draft put the channel question in `getSyncState` instead of forgetting the barrier at the source, which only MASKED a stale barrier while the fan-out went on replaying a dead `State` to the next joiner.
+
+## A record is written when the fact becomes TRUE, not when it is requested
+
+`held` was written the moment `subscribeDocUnguarded` returned - which is BEFORE the `doc_subscribe` behind it has been placed, since `establish` awaits the session id first - so it meant *"we asked"*: the exact looser meaning an `opened` set had been deleted for one round earlier. That is a claim about what a call's return implies, written and never run; see [[justify-a-return-value-by-running-it]].
+
+`BootstrapOpen.release` is held to the same rule and says only *"am I still listening"*. It cannot answer *"is this document open"*, because `resetDocSubscriptions` drops a listener from under this module without a word - so `stillStanding` asks three questions, every one of them of the thing that owns the answer: do I hold a listener at all, is it in the fan-out that stands NOW (`channel.incarnation !== open.incarnation`), and does an attempt stand behind it. An attempt that has not ANSWERED yet counts as standing, deliberately: a second `doc_subscribe` cannot be placed while one is in flight, so a fresh attempt buys nothing and costs the caller the whole bounded fallback again.
+
+## The four sync states, and why `"unknown"` is authoritative
+
+`getSyncState` DERIVES all four on every call and stores none. `"synced"` - a `State` has arrived on the channel standing NOW; the truth signal, so a zero-row read MEANS zero. `"syncing"` - inside the bounded wait. `"timed-out"` - opened here with no barrier to show for it, whether the wait gave up, the subscribe was refused, or the channel was taken away; never `"unknown"`, which is why a reset DISOWNS a document rather than forgetting it. `"unknown"` - never opened here, or the no-`doc_subscribe` path with no `State` semantics.
+
+**`"unknown"` passes as authoritative, deliberately: where there are no `State` semantics there is no barrier to have missed.** Refusing it instead is an inert-case regression that has shipped twice. Its two readers in `src` disagree only in the direction each must be safe in - `index-deposit`'s `noRowsMeansAbsent` accepts `"synced"` and `"unknown"`, and `use-shape-query`'s `namedDocumentsArrived` refuses `"timed-out"` and `"syncing"`. `inbox-observer` reads NEITHER; it keeps its own watch record, and counting is what settled that (see `bug_a-lost-inbox-watch-is-never-retried`).
+
+## Every teardown path, and what each leaves behind
+
+- `configure()` and `resetConfig()` (PUBLISHED) call `resetDocSubscriptions` and `stopObservingInboxes`, and NOT `resetOpenedRepos`. They leave `open-repo`'s records holding a listener whose fan-out is gone - now inert by construction: `stillStanding` sees a changed `incarnation` and re-opens, and `getSyncState` reads `"timed-out"` off a channel in state `"none"`.
+- `resetDocSubscriptions()` clears every listener, releases each fan-out and empties the map. It leaves `obs.inboxes`, `public-store.attempted` and `seenByInbox`.
+- `resetOpenedRepos()` - ONE caller in `src`, `syncSession` on a session-id change - releases each bootstrap listener, ENDS the abandoned wait (without which a caller hangs the full fallback on a subscription that no longer exists), replaces each record with a disowned one, clears `boundSessionId`, then calls `resubscribeDocs`. It leaves the same three.
+- `resubscribeDocs()` re-opens each channel ON THE SAME entry, forgetting `lastState` because the barrier belonged to the session that is gone, and keeps the keys and listeners on purpose so an `inbox.watch` survives the change. This is why entry identity cannot answer which attempt is current, and `attempt` must.
+- `releaseFanOut()` takes one entry out of the map with its barrier; `reportSetupFailure()` clears `establishing` (retryable) and `lastState` (a barrier belongs to the attempt that produced it) for the CURRENT attempt only - a superseded one is logged and nothing else.
+- `setCurrentUser()` calls `stopObservingInboxes` only, and correctly: an identity change is not a session change. There is no sign-out or `session_stop` path in `src`; `setCurrentUser(null)` is the disconnection.
+- `forgetEverything()` (TEST-ONLY) never clears `seenByInbox`, `running`, `openInboxInFlight` or `connect.inFlight`.
+
+## The lesson, which is the transferable part
+
+**Count exhaustively FIRST - including anything that merely INFERS the fact - and write the count down before designing anything.** Two attempts failed by fixing a WRITER without knowing who read it, and the two records nobody had counted were both short-circuits that implied openness rather than stating it. Enumerate the readers and the teardown paths from the code and verify the list rather than trusting it; the count is what produced the invariant, not the other way round.
+
+The caller-facing consequence is in `knowledge_what-a-failed-read-answers-upstream` (its third rule) and in `polyfill-surface/contract_polyfill-surface` at `1.0.0-dev.10`, where the pending-until-the-barrier guarantee lost its session-scoped qualification. The other half of what a shape read may show is `knowledge_what-stands-between-identities`: this leaf decides whether a named document is an answer, that one bounds what the answer may contain.

.project/concepts/app-contract/knowledge_what-a-failed-read-answers-upstream.md

@@ -0,0 +1,45 @@
+---
+type: knowledge
+summary: What the target answers for an unreachable, an unsynced and an empty document - a read rejects or it does not, so "not known to me" and "does not exist" are one answer while "unsynced" and "genuinely empty" are another
+last_checked: 2026-09-21
+---
+
+# What a failed read answers upstream, and what a caller can tell apart
+
+The question a caller actually asks: **when a read comes back with nothing, what can I conclude?** This leaf records the target's answer, because every version of the failure-as-absence defect in this package has come from getting it wrong in one direction or the other - either swallowing a breakdown into an empty result, or turning a real emptiness into an error.
+
+## The engine's observable: a read REJECTS, or it does not
+
+An anchored SPARQL query resolves its target through `resolve_target_for_sparql`, whose first act is `self.repos.get(repo_id).ok_or(NgError::RepoNotFound)?` (`engine/verifier/src/request_processor.rs:269`, at `213338f6`). A repo the verifier does not hold is an **error**, not an empty result. It crosses into JavaScript as a **rejected promise carrying the string `RepoNotFound`** (`sdk/js/lib-wasm/src/lib.rs:403` for nodejs, `:606` for the browser).
+
+So the target offers exactly **two** observable outcomes for a read, and no third: it rejects, or it resolves with rows - possibly zero of them. There is no "partially answered", no "could not find out but here is what I have", and no status object. Any richer vocabulary in this package would be something a caller learns here and unlearns at migration.
+
+## The three states a caller wants to distinguish, and the two it gets
+
+| the document is... | what the engine does | what a caller can conclude |
+|---|---|---|
+| **not in `self.repos`** - never existed, or exists but this session does not know it | REJECTS with `RepoNotFound` | "I could not read it." **Not** *why*. |
+| **in `self.repos` but unsynced** - a persistent profile reloads every known repo at `Verifier::load` (`engine/verifier/src/verifier.rs:535-560`), so a fresh session over the same wallet has the repo without its remote commits | resolves, **zero rows** | nothing distinguishes this from the row below |
+| **in `self.repos`, synced, and genuinely empty** | resolves, **zero rows** | nothing distinguishes this from the row above |
+
+Two collapses, and they run in opposite directions. Above the line, **"does not exist" and "exists but I do not know it" are indistinguishable** - the partition the engine exposes is membership of `self.repos`, and nothing finer. Below it, **"known but unsynced" collides with "genuinely empty"** - both are a legitimate zero-row answer, and the error channel is not involved at all.
+
+That second collapse is the one a caller gets bitten by, because zero rows looks like an answer. The only thing that separates the two is a **sync barrier**: `doc_subscribe` pushes `TabInfo` and then the first `State`, and past that first `State` presence is guaranteed and absence definitive (pinned empirically by CONTRACT 3 in `packages/polyfill/e2e/`). Crossing it is what turns "zero rows" into a statement.
+
+## There is no capability check on the read path at all
+
+`resolve_target_for_sparql` reads `nuri.target` and nothing else. Upstream a document you cannot read is one whose `ReadCap` does not open it - the refusal is cryptographic and happens further down, never as a "may I?" question answered on the way in. So **a read never fails for want of a right granted to you**; it fails because the repo is not there, or it succeeds.
+
+This is why this package's `fetchReadCap` (the emulated *"downloaded from the outer overlay"*, `PublicRepoLinkV0`) has **no upstream counterpart to mirror**: there is no signature at any level to copy, and the alignment falls to the engine's model instead. That is the reasoning behind `1.0.0-dev.9`: the emulation's own step was collapsing "the store could not be asked" into "the document exposes no key", so the honest projection of a failed emulation step is the one outcome the engine has for a read that cannot happen - a rejection.
+
+## What this package does with it, and the line it must not cross
+
+Three rules follow, and all three are load-bearing:
+
+1. **A breakdown rejects.** Anything that stops a read from happening - a repo that will not open, a broker that does not answer, an emulation step that could not be performed - reaches the caller as a failure. `A rejection means "unknown", never "absent"` is the contract's own wording.
+2. **An empty document is a SUCCESS holding zero objects.** The repair for (1) must never be bought by making a real emptiness into an error; that only moves the lie. An empty document, an empty scope, a document nobody opened an inbox on, a document in a public store that exposes no key - each is an answer, and each stays one.
+3. **The unsynced/empty collision is closed by the barrier, and where the barrier was not crossed the read says so rather than answering.** Crossing it is what makes a zero-row answer mean something (`emulated-verifier/open-repo.ts`, which keeps `synced` and `timed-out` deliberately apart). A reactive read over documents it NAMES consults that distinction and stays PENDING when the barrier was not reached - "I have no authoritative answer" rather than "there is nothing". Turning it into a rejection would be inventing a third outcome the engine does not have, and answering a success would be the collapse this whole leaf is about.
+
+   **What an application can see of this, exactly.** `useShapeQuery` folds it into its own states, and that is the only published channel: a named scope whose barrier was not crossed does not reach `isSuccess`. That held only **within one ordinary session** until `1.0.0-dev.10`: a second `configure(...)` tore down the subscription layer without telling the open registry, and a broker refusing a subscription after this package had stopped waiting left the document recorded as open - in both, a document recorded as open was not; the first answered an empty or stale success, and the second left the read withheld with no way back, since the retry it invites was blocked by that record. Closed by giving the question ONE answer: openness is the state of the document's one real subscription, read rather than remembered, so no record of it can outlive the channel it describes. The REACHABILITY half was never affected. `inbox.readSyncedForDocument` is the same guarantee on the inbox path. `getSyncState` is INTERNAL and is deliberately not published - this leaf offered it until 2026-09-24, which was a pointer at something no caller can import. It stays internal because it has no counterpart upstream at any level: publishing it would hand an application a polyfill-era symbol to unlearn at migration, on a surface that is busy removing exactly those. The consequence to state plainly rather than paper over: a caller using the anchored `docs.sparqlQuery` directly gets zero rows for an unsynced document and has **no published way to tell that from an empty one** - that is the collapse upstream has too, and it is why the reactive read is the one that carries the distinction.
+
+Related: `knowledge_what-a-read-scope-is-upstream` (what a read request can SAY, including the `[]` that means the empty set and the `[]` that means no filtering), and `polyfill-surface/contract_polyfill-surface` `## Guarantees` for the caller-facing form of all of this.

.project/concepts/app-contract/knowledge_what-a-read-scope-is-upstream.md

@@ -0,0 +1,78 @@
+---
+type: knowledge
+summary: What the target offers for reading many objects — a graph is one document, a store's graph holds only its containment triples, and scoping a read by store is not expressible at all
+last_checked: 2026-09-24
+---
+
+# What a read scope is upstream
+
+Read at the source in `nextgraph-rs` (`213338f6`), which declares OLDER releases than this repo installs - the `ANCHOR` in `packages/polyfill/test/provenance.test.ts` holds the gap and checks both its ends. Every claim points at a symbol or a module rather than a line, so `git grep` settles any doubt after the code moves. The question answered here is the one a caller actually asks: **how do I ask for many objects at once, and what can the request say?**
+
+## The type, and the two axes it filters on
+
+`Scope = { graphs?: string[] | string; subjects?: string[] }` (`sdk/js/orm/src/types.ts` at `213338f6`), normalised by `normalizeScope` into `{ graphs: string[]; subjects: string[] }`. **In the installed `@ng-org/orm@0.1.2-alpha.21`, `graphs` is REQUIRED** (`graphs: string[] | string`, `dist/types.d.ts`); `subjects?` stays optional. A caller that omitted `graphs` no longer compiles.
+
+**The two axes read `[]` in OPPOSITE directions, and this is the trap.** Upstream documents each field separately, and they do not agree:
+
+| field | `["did:ng:i"]` or `[""]` | `[]` or `undefined` |
+|---|---|---|
+| `graphs` | the whole dataset | **no objects at all** - the EMPTY set |
+| `subjects` | n/a | **no filtering** - every subject |
+
+So `{ graphs: [], subjects: [] }` returns nothing, and it is `graphs` alone that decides it. Reading the pair as symmetrical is how a read that should have been unscoped becomes a read that matches nothing, silently, since a shape query matching nothing is indistinguishable from a scope holding nothing. Two axes, no third.
+
+## A `graphs` entry is one document's graph, never a set of them
+
+At the binding, `orm_start_graph` (`sdk/js/lib-wasm/src/lib.rs`) passes each string through `NuriV0::new_from` (`engine/net/src/app_protocol.rs`). That function accepts exactly five forms and rejects everything else: `did:ng:i`; a repo id `did:ng:o:<repo>`; a file read-cap `did:ng:j:<id>:k:<key>`; a repo graph `did:ng:o:<repo>:v:<overlay>`; a branch `did:ng:o:<repo>:v:<overlay>:b:<branch>`. **No string parses to a store target.** And `nuri_to_string` (`engine/verifier/src/orm/graph/utils.rs`) then collapses every non-`UserSite` NURI to a single repo graph name, `did:ng:o:<repo>:v:<overlay>` — one document's graph, whatever went in.
+
+## Naming a store's graph reaches its containment triples, not its documents
+
+`Verifier::doc_create` (`engine/verifier/src/request_processor.rs`) writes `<store> <http://www.w3.org/ns/ldp#contains> <did:ng:o:doc>` into the **store's** graph, while the new document's own triples live in **its** repo graph. The object of that triple is the bare repo-id form, not even a graph name.
+
+So the obvious formulation — *"search my private store"* — resolves to the store's graph, matches the containment triples, and returns **an empty set for the shape being asked about**. Silently: no error exists for it, because a shape query matching nothing is indistinguishable from a scope holding nothing.
+
+## `did:ng:i` and `""` replace the whole list
+
+In `orm_start_graph`, an entry equal to `""` or `did:ng:i` **discards every other entry** and substitutes `NuriV0::new_entire_user_site()`; `nuri_to_string` renders that back as the string `did:ng:i`. Downstream, `query_quads_for_shape` and `query_graph_subjects` (`engine/verifier/src/orm/graph/query.rs`) test `nuris[0] == "did:ng:i"` — positional, which holds because the binding has already collapsed the list to a singleton — and when it does, they **drop the graph filter entirely**: the emitted SELECT carries no `FILTER(?g …)` and runs over the whole local dataset.
+
+Nothing is added to the query to narrow it by what the reader may open. `query_sparql_select` parses the SPARQL and runs it against the verifier's dataset as-is. The only bound is what the verifier has **materialised locally** — documents opened from a held `ReadCap`, `load_repo_from_read_cap` (`engine/verifier/src/verifier.rs`) — not a check performed when the query runs.
+
+## The graph filter is literal
+
+`schema_shape_to_sparql` (`engine/verifier/src/orm/graph/query.rs`) emits `FILTER(?g IN (<g1>, <g2>, …))` from the list verbatim. **No prefix, pattern or hierarchy matching**: a graph is in the list or it is not. `StorageReader::repos_in_store` (`engine/oxigraph/src/oxigraph/storage/mod.rs`) could enumerate a store's repos — and has **zero callers**.
+
+## `entire_store` is the shape to align on, and nothing wires it
+
+`NuriV0.entire_store` (`engine/net/src/app_protocol.rs`) is documented *"If it is a store, will include all the docs belonging to the store"*. Every constructor sets it `false`, **nothing anywhere sets it `true`**, and its only three readings are guards (`is_branch_identifier`, `is_valid_for_sparql_update`, `is_valid_for_discrete_update`) that require it false. No code expands it into a graph list.
+
+That is `declared-not-wired` in the taxonomy of [[no-divergence-from-nextgraph]]: the target has written down the shape of the question even though nothing answers it yet — and a declared shape is the strongest thing to align on, far stronger than the absence of an implementation is evidence against it.
+
+## `subjects` filters the root shape only
+
+`query_quads_for_shape` seeds the caller's subject list as the pending set of the **root** shape; every nested shape gets its subjects from what the root query discovered, not from the caller. The emitted filter is `FILTER(?s IN (…))` over root-subject IRIs.
+
+## How far `where`, `orderBy` and `pageSize` are known to travel
+
+`OrmConfig` (`engine/net/src/orm.rs`) carries `where_`, `order_by`, `select`, `page_size` and `max_active_pages`; `OrmConfig::from_json` parses all five and refuses a `pageSize` greater than zero without an `orderBy`; and every one of them is consumed downstream - `schema_shape_to_sparql` takes the where config, the order-by config and a `(limit, offset)` pair and emits `FILTER`, `ORDER BY`, `LIMIT` and `OFFSET` from them, while `initialize.rs` drives its paging window and its page eviction from `page_size` and `max_active_pages`. The config machinery is implemented, not stubbed.
+
+One hop is missing, at the ENTRY: `Verifier::start_orm` takes no config argument at all - `request_processor.rs` calls it with three - so it builds one from `json!({})` behind a `// TODO`. `OrmConfig::from_json` names the missing hop in its own TODO, *"Use json in libwasm context"*, and that is exactly what is absent there: `orm_start_graph` (`sdk/js/lib-wasm/src/lib.rs`) declares FIVE parameters at this commit, with no slot for a config.
+
+**That absence describes `213338f6` and nothing later, and the installed releases are past it.** `@ng-org/web@0.1.2-alpha.14` ships `orm_start_graph` with SIX parameters, `config` at index 4, and `@ng-org/orm@0.1.2-alpha.21` calls it with six, passing its whole options object into that slot - both read in the shipped artifacts, not inferred. So at the releases this repo installs the config LEAVES level 3 and is ACCEPTED at level 2. Whether the engine behind that binding feeds it to `from_json` is **settled by nothing reachable**: the shipped wasm carries no source, and this tree is demonstrably older than the binding it would be asked about. Only a live measurement answers it, and none has been made.
+
+Reading the `json!({})` as *"level 1 discards the richness"* is inference from an absent implementation, which [[no-divergence-from-nextgraph]] forbids - and it was written here once, as *"no caller can reach any of it"*.
+
+## "Not ready" and "ready and empty" are distinguishable — one level down
+
+`OrmSubscription` (`sdk/js/orm/src/connector/GraphOrmSubscription.ts`) is exported from the package entry — `core.ts`, which `@ng-org/orm` resolves `.` to — and carries a public `readyPromise` getter. In the installed alpha.21 both the symbol and its file are renamed, to `RdfOrmSubscription` and `connector/RdfOrmSubscription.ts`, and it gains an `isReady` getter that answers the same question without awaiting. So at that level the two states **are** distinguishable. The React `useShape` adapter drops the distinction: what it publishes beside the data is an `isLoading`, which says whether the initial payload has arrived and has no value for a read that will never answer - and its own doc still describes the data as *"the orm objects or an empty set, if still loading"*. The gap is between level 3's class and level 3's hook, not between us and the target.
+
+## What this package does instead
+
+`useShape` here is a passthrough (`packages/polyfill/src/surface/use-shape.ts`, annotated `kind=passthrough level=3`): **the scope goes to the injected SDK hook unchanged**, and the rights filter is applied to the *results* before they reach the caller. `makeReadFilteredView` (`packages/polyfill/src/emulated-verifier/read-filter.ts`) keeps only items whose document — their `@graph` — the current holder has a cap for, annotated `kind=aligned level=1 ref=engine/verifier/src/verifier.rs:load_repo_from_read_cap`.
+
+That is the emulation of what the broker will bound **at delivery**, done where the target does it: per document, on what comes back. It disappears at migration, with the module — see [[knowledge_what-an-app-deletes-at-migration]].
+
+## What follows
+
+**Scoping a read by *store* is a question the SDK cannot express.** No string names a store as a read target; the store's own graph holds containment triples and nothing else; the one field that would mean it is declared and unwired. Nor is it a question an application needs to ask: an application names the documents it holds — it cannot discover, it can only follow a reference ([[knowledge_what-an-iri-says-upstream]] for what those references say). **Enumerating documents is only forced if you insist on asking by store.**
+
+Where the target does answer, it answers on two axes — by document (`graphs`) and by subject (`subjects`) — and those are the two to build on.

.project/concepts/app-contract/knowledge_what-an-app-deletes-at-migration.md

@@ -7,9 +7,13 @@ summary: The two fates a published symbol can have, and why the deletion list is
 
 Every published symbol has exactly one of two fates, and knowing which is the whole point of this boundary.
 
-**Replaced in place.** The build alias resolving `@ng-eventually/polyfill` is removed, the import resolves to the real SDK, and the application's code is unchanged. This is almost everything: `ng`, `useShape`, `watchShape`, `init`, `initNg`, `readUnion`, `subscribeDoc(s)`, `docs.*`, `inbox.*`, `storeRegistry.*`, and the types.
+**Replaced in place.** The build alias resolving `@ng-eventually/polyfill` is removed, the import resolves to the real SDK, and the application's code is unchanged. This is almost everything: `ng`, `useShape`, `useShapeQuery`, `init`, `initNg`, `getObjects`, `insertObject`, `subscribeDoc(s)`, `docs.*`, `inbox.*`, `storeRegistry.*`, and every type a published signature actually uses - a type that no signature uses has the third fate below, not this one.
 
-**Deleted.** The symbol has no counterpart at any level of the target, exists only because one shared wallet hosts every user, and goes with its call site. Today that is `configure` and its config type.
+**A third fate exists and is not one of the two: withdrawn before migration.** `readUnion` and `UnionSubject` were listed above as replaced in place, and they were never going to be: a batch over N anchored queries has no counterpart at any level, so nothing would have resolved to it. They left the surface in `1.0.0-dev.8`, and an application reads one document with `docs.sparqlQuery` instead. `Schema` and `DeepSignalSet` followed in `1.0.0-dev.12`, for a different reason worth keeping apart: not that the target lacks a counterpart - it has both - but that no published signature here used them, so they were surface an application could name and never needed. That is the reason this leaf exists - a symbol whose fate is asserted rather than checked is how the list goes wrong, and the two withdrawals show the question is asked twice: does the target carry it, and does our own surface need it.
+
+**Deleted.** The symbol has no counterpart at any level of the target, exists only because one shared wallet hosts every user, and goes with its call site. Today that is `configure` and `EventuallyConfig`, the five types that describe that config's fields, and `ShapeObservable`.
+
+`ShapeObservable` is the instructive one, because its fate is COUPLED rather than independent. It is what `useShapeQuery` returns, and it is not a framework adapter: it carries the capability filter behind `getSnapshot` and the capability-arrival re-publish keyed on the held-caps signal. A capability arrives mid-session only because the wallet is shared, so in the target there is nothing to filter and no arrival to react to - and an announced hook returning a snapshot has nowhere to hang such a subscription because it needs none. It therefore goes exactly when the shared wallet goes, not before and not on its own. Read the deletion list as naming one migration there, not four removals.
 
 `ensureIdentity` sits between the two and is worth stating precisely: its **substance** is scaffolding — a barrier that hands out a shared wallet file and takes an identifier, a step that exists only because users share a wallet — while its **call site survives**, because an application still awaits a session before it renders. Its signature was designed for that: it takes no identifier, so the line does not change the day the wallet supplies the identity and the barrier stops appearing.
 
@@ -27,4 +31,4 @@ The trade was deliberate and it is a real reduction in enforcement: a documentar
 
 ## The direction of travel
 
-The polyfill-era list only shrinks. It has gone from four published calls to one, and each removal was a symbol an application should never have had: naming its own identity, awaiting the connection, wiring a second bootstrap, reaching a machinery accessor. A symbol added to that block is a promise to delete it later — so the question at every addition is whether the application genuinely needs it, or whether the library is passing on a problem of its own.
+The polyfill-era CALLS only shrink - from four to one, each removal a symbol an application should never have had: naming its own identity, awaiting the connection, wiring a second bootstrap, reaching a machinery accessor. The BLOCK does not: it grew by six type entries in `1.0.0-dev.13` and `-dev.14`, when five config field types and `ShapeObservable` were found sitting in the SDK-shaped section while honestly annotated as having no counterpart. That was a correction, not a regression - the block got longer because it got true - and the distinction matters, because reading monotonicity as the invariant is how a misplaced symbol stays misplaced to protect a trend. A symbol added to that block is a promise to delete it later — so the question at every addition is whether the application genuinely needs it, or whether the library is passing on a problem of its own.

.project/concepts/app-contract/knowledge_what-an-inbox-is-upstream.md

@@ -26,7 +26,7 @@ Anything built here therefore aligns on the **engine's model**, because levels 2
 
 `InboxMsgContent` declares eight variants. `ContactDetails` and `SocialQuery` carry data and have processors. **`Link`, `Patch`, `ServiceRequest`, `ExtRequest`, `RemoteQuery` and `DialogRequest` carry nothing at all** — they are bare unit variants, so they cannot hold a reference, name a servicer, or describe an operation.
 
-That distinction decides how much they bind us, and it is why the provenance taxonomy in [[rule_no-divergence-from-nextgraph]] separates a reserved name from a declared shape.
+That distinction decides how much they bind us, and it is why the provenance taxonomy in the no-divergence rule (`.project/rules/nextgraph/no-divergence-from-nextgraph.md`) separates a reserved name from a declared shape.
 
 ## Processing is closed, and so is posting
 

.project/concepts/app-contract/knowledge_what-an-iri-says-upstream.md

@@ -44,7 +44,7 @@ The `urn:` strings that appear upstream are unit-test fixtures and nothing else:
 
 **`urn:ng-eventually:` — `MACHINERY_NS`** (`packages/polyfill/src/emulated-verifier/machinery.ts`), in two families: `urn:ng-eventually:shim:…`, the compartments `shared-wallet/account-registry.ts` uses to emulate a repo's branches inside one document, and `urn:ng-eventually:inbox:…`, the deposit envelope and the deposit kinds `emulated-verifier/inbox-dispatch.ts` dispatches on.
 
-**Triples under it are dropped on read.** `isMachinerySubject` is called from `readUnion` (`packages/polyfill/src/surface/read-model.ts`), which skips every row whose **subject** starts with the prefix before the caller ever sees it. By subject only — a machinery predicate on an ordinary subject comes straight through.
+**Triples under it are dropped on this package's OWN read, and nowhere else.** `isMachinerySubject` is called from `readDocumentSubjects` (`packages/polyfill/src/surface/read-document.ts`), which skips every row whose **subject** starts with the prefix. By subject only — a machinery predicate on an ordinary subject comes straight through. That read is INTERNAL since `1.0.0-dev.8`: the published `readUnion` used to apply the same filter for an application, and with it gone **an anchored `docs.sparqlQuery` returns the machinery rows** and the application ignores them itself. No right moves with that: the only registers an ordinary document carries are its inbox address and, for a public document, the read key its store already serves to whoever asks.
 
 **That filtering has no upstream counterpart: it is an invention, and the source annotates it as one** (`kind=invention level=none`). It exists because this package has no branches, so a compartment upstream keeps in a separate CRDT has to live as a reserved subject in the same graph. Do not read our reservation as mirroring anything upstream — nothing there is filtered out of a document's own graph.
 
@@ -62,8 +62,8 @@ Naming them alike would say the wrong thing about both: it would promise the sca
 
 **Settled, read at the source.** Nothing upstream reserves, filters or validates a namespace; the engine stores and returns arbitrary IRIs; there is no extension convention to comply with and no procedure for claiming a segment. **Nothing upstream binds our choice, and nothing upstream breaks if we keep a `urn:` scheme.**
 
-**A bet.** That upstream will not later claim `urn:` or begin separating by prefix. Nothing says it will; nothing says it will not — and *the absence of an implementation says nothing about what the target will do* ([[rule_no-divergence-from-nextgraph]]). The exposure is small and it falls on the scaffolding side, which is the half designed to disappear.
+**A bet.** That upstream will not later claim `urn:` or begin separating by prefix. Nothing says it will; nothing says it will not — and *the absence of an implementation says nothing about what the target will do* (the no-divergence rule (`.project/rules/nextgraph/no-divergence-from-nextgraph.md`)). The exposure is small and it falls on the scaffolding side, which is the half designed to disappear.
 
 **A bet, and the more expensive one.** Writing `urn:ng-helpers:` from here. Two packages now share one data format with no owner and no agreement about who may change it.
 
-**Not a bet — a divergence, if it were ever done.** Putting our own terms under `did:ng:x:…`. That segment is the target's vocabulary space, `did:ng:x:ng#` is the engine's own, and `x` means nothing to the address grammar — so borrowing it would dress an invention in the target's vocabulary, which [[rule_no-divergence-from-nextgraph]] names as the most dangerous kind of all.
+**Not a bet — a divergence, if it were ever done.** Putting our own terms under `did:ng:x:…`. That segment is the target's vocabulary space, `did:ng:x:ng#` is the engine's own, and `x` means nothing to the address grammar — so borrowing it would dress an invention in the target's vocabulary, which the no-divergence rule (`.project/rules/nextgraph/no-divergence-from-nextgraph.md`) names as the most dangerous kind of all.

.project/concepts/app-contract/knowledge_what-stands-between-identities.md

@@ -0,0 +1,61 @@
+---
+type: knowledge
+summary: One module stands between identities sharing a wallet - its rule lives in TWO views that must be repaired together, its default is decided-or-refused because no type test separates a count from a config echo, and host introspection is the one hole no trap can close
+last_checked: 2026-10-01
+---
+
+# What stands between identities on a read
+
+This package emulates a world in which each identity reads only its own data, while physically every identity shares ONE wallet that opens everything. `emulated-verifier/read-filter.ts` is the whole of what stands between them. Three ways to break it, and all three happened while it was being built: a READ hole discloses another identity's objects, a WRITE hole lets one identity plant into or destroy a document it cannot read, and an OVER-BROAD refusal takes the owner's own data away from them. A repair that removes a leak by refusing more is not a repair - the third cost the owner 18 declared members of an ordered result. This leaf is why the module has the shape it has, so that an agent changing it keeps the shape.
+
+## TWO views, one rule, and the defect that is always the same
+
+The module publishes two proxies, and the distinction is not cosmetic: `makeReadFilteredView` wraps a COLLECTION (a `DeepSignalSet`, or the array-like `DeepSignal<ReadOnlyArray>` an `orderBy` config produces), and `makeReadFilteredShapeResult` wraps the SDK's result ENVELOPE, whose members are of two kinds - some carry the items, some are the request's own state. One object cannot be both: the envelope was wrapped in the collection view until `1.0.0-dev.10`, so `[...result]` and `.size` threw while `data`, `promise` and `subscription` each came back raw, each carrying every identity's items.
+
+**Every defect in this family has been one rule applied to one view of two.** So what can be shared is shared as CODE rather than as a convention: `writeTraps` is a single object spread into both proxies, and `answerUndecidedMember`, `filteredDescriptor`, `cannotReachAnItem` and `readable` are one function each, called from both. What is NOT shared is the member decisions, because the two shapes answer different questions. The discipline that follows: **a defect found in one view is checked in the other before it is called fixed** - the round that added five write traps to the collection view and not to the envelope had just found and trapped two of them, on one view of two.
+
+## The default is DECIDED-OR-REFUSED, and the type-based alternative was tried
+
+What the file has decided it serves, it serves; **everything else refuses, whatever its type**. The one exception is a member the target does not carry at all, which answers `undefined` - there is nothing behind it to derive anything from, and refusing it would refuse a question nobody asked.
+
+Keep the reason, because the obvious alternative shipped and failed. The default used to be *"a primitive cannot reach an item, so it passes"*. **There is no type-level test that separates a primitive which is a value from one derived from the collection**: a number is a number, and nothing observable about a getter says whether its 7 counts items or echoes a page size. The file already contradicted itself on this - `size` and `length` were computed precisely because a count describes the items - so a third spelling went through raw, and a holder entitled to one of three items read `totalCount` as 3. `@ng-org/orm` already ships `pageSize`, `maxActivePages` and `nextPage`, so a count member is an ordinary next bump rather than a hypothesis.
+
+The asymmetry that decides it: **a default that lets an unknown member THROUGH breaks silently at the next SDK bump; one that refuses it breaks loudly, naming itself.** That is what makes the current default safe for a shape nobody has seen - not that it classifies correctly, but that it refuses. See [[justify-a-return-value-by-running-it]], whose third corollary is this rule and four of whose five cases are this module.
+
+A function is refused AT THE CALL rather than at the read, deliberately: a function value is read by things that never call it - a logger, a devtools inspection, a `typeof` guard.
+
+## Nine traps on the collection, seven on the envelope, and which share one answer
+
+`get` is not the only door. `Object.getOwnPropertyDescriptor` - and the spread, `Object.keys`, `Object.entries`, `JSON.stringify` and a console inspection built on it - reads a property WITHOUT going through `get`, which is how one leak was found: a view that filtered `get` alone handed the raw collection back to whoever asked for the descriptor, and handed over the ORM handle that `get` throws on. So the two VALUE-bearing doors are wired to ONE `read` function per view, passed into `filteredDescriptor` as the very function `get` calls, and they cannot drift. That holds for an ACCESSOR as much as for a value - a descriptor carries no value of its own, so handing one back untouched was a door around the view, and its getter is re-pointed at the view's own read while its setter is refused.
+
+The collection view carries **nine** traps: `get`, `getOwnPropertyDescriptor`, `has`, `ownKeys`, plus the five writes. The envelope carries **seven** - the same five writes and the same two reads, and no `has` or `ownKeys`, because those are questions about POSITIONS and an envelope has none. Be precise about the routing rather than repeating the header's own wording: `has` and `ownKeys` do not go through `read`; they answer from the same `kept` projection, which is what keeps an index, `length`, `in` and `Object.keys` telling one story on the array form. Forwarding an array's own keys published how many items the collection held while `length` said how many may be read - the two disagreed by exactly the leak. Membership of a NON-index key forwards, deliberately: it discloses the SDK's published shape, which is in the package rather than in the holder's data.
+
+The five writes are `set`, `deleteProperty`, `defineProperty`, `setPrototypeOf` and `preventExtensions`. The last two are there for a different reason from the first three - they reach the target without naming a property and **damaged the real collection for EVERY identity rather than leaking**: `setPrototypeOf` replaced its prototype, after which iterating it throws for everyone, and `preventExtensions` (what `Object.freeze` begins with) strands the index projection, which is lawful only while the target is extensible.
+
+## A mutation asks the question the view already answers
+
+`add`, `delete` and `clear` reach the collection underneath - the view must not break writes or the reactivity they drive - under one rule: **a mutation may not act past what the view shows, and may not hand back what the view hides.** Gating two of three was the asymmetry rather than a half-measure: an ungated `add` MANUFACTURED the state the other two then handled partially, so a holder could plant an item into a document it cannot read, never see it again, and watch `clear()` leave it behind.
+
+`add`'s gate is the stricter form of the same question, and the difference is load-bearing. On the READ side an item with no `@graph` is KEPT, because it names no document and so there is no cap to ask about; on the WRITE side that reading makes the gate VACUOUS - the object landed in the collection every identity shares. So a write must NAME a document and the holder must hold it.
+
+They answer differently **by their own contracts, not by residual asymmetry**: `delete` returns `false`, the Set contract's own word for "it was not there" and true of the view, while `add` returns the collection whether or not it acted, so it has no such value and THROWS rather than report a write that did not happen. `add`'s return is also why anything a member hands back is held to the rule: `Set.prototype.add` returns `this`, so the result becomes the VIEW - the collection, handed back, is every identity's items.
+
+## The restated member lists, and how to verify this leaf cheaply
+
+Every member `@ng-org/alien-deepsignals` declares non-mutating is SERVED, computed over the readable items against a fresh `Array` or `Set` built from `kept` - refusing them is what cost the owner those 18 members. The three lists are restated rather than imported, because the package's `exports` map has no subpath for `iteratorHelpers` and `src/` may not import an optional peer at runtime anyway.
+
+**A restatement drifts unless something reads the original, so something does, and that is the cheap way to check this leaf:** `test/read-filter.test.ts`, "the declared non-mutating surface still matches what upstream ships", parses the shipped `dist/iteratorHelpers.js` and asserts a PARTITION - upstream's effective list equals the union exactly, the three parts are disjoint, the exception set is exactly one named member, and the SYMBOL entries are read too. The partition is the point: comparing each list against upstream minus the exceptions is satisfied by any number of exceptions, so a copy with `{copyWithin, slice}` excepted and `slice` dropped from the served list ran green while `data.slice()` had silently gone from the owner.
+
+## ONE deliberate divergence, measured
+
+`copyWithin` is REFUSED although upstream's list declares it non-mutating. Re-measured against the installed package on 2026-10-01: `ro.copyWithin` reads as a `function` with no throw, and `ro.copyWithin(0, 1)` turns `["A","B","C"]` into `["B","C","C"]` - the first element is destroyed - while `push`, `splice`, `sort`, `reverse`, `fill` and `shift` all THROW on the READ. Upstream's `readOnlyArray` refuses every mutator it knows about, and `copyWithin` escapes that refusal because the guard is built from the same mislabelled list the name sits in: upstream's list and upstream's guard agree with each other and are both wrong.
+
+So refusing it is **STRICTER than the target**, not equal to it. Record it as a deliberate divergence with its measurement and never as equivalence - this is the one place in the module where [[no-divergence-from-nextgraph]] is answered by diverging, and the alternative was worse: serving it over the snapshot made it succeed and discard in silence, teaching a caller that a write worked.
+
+## What it cannot close, and what the contract therefore tells applications
+
+**Host introspection.** `console.log(result)` inspects the object BEHIND the proxy and prints every identity's items, and no trap can prevent it - re-measured on 2026-10-01 against `makeReadFilteredView`, where the view yields one item through every trapped path and `console.log(view)` prints `Set(2)` with both. It is a property of runtime introspection, not a hole a version can close, and the published contract already says so: **do not log or inspect what a `shape read` hands you when more than one identity shares the page** - iterate `data` and log what you mean to show.
+
+Two smaller limits, neither a hole: the filter is SYNCHRONOUS, so a public-store document whose `ReadCap` nobody has asked for yet is dropped until some read path asks; and refusing at the ASK is a different question from filtering the RESULT - under `did:ng:i` nothing is named and this filter is the whole answer, while on a named scope the sync barrier decides whether the document is an answer at all (`knowledge_one-answer-to-whether-a-document-is-open`) and the filter still keeps that answer honest per `@graph`.
+
+The whole module is `polyfill-era` and goes at migration, when the broker delivers only what the holder's keys open (`knowledge_what-an-app-deletes-at-migration`). The caller-facing form of everything here is `polyfill-surface/contract_polyfill-surface` `## Guarantees`.

.project/concepts/app-contract/knowledge_what-the-orm-writes-and-deletes-upstream.md

@@ -0,0 +1,64 @@
+---
+type: knowledge
+summary: What the target offers for writing and removing — deletion is a SET MUTATION wired end to end, it removes the shape's predicates rather than the subject, and the ORM's writes never pass through `sparql_update`
+last_checked: 2026-09-24
+---
+
+# What the ORM writes and deletes upstream
+
+Read at the source in `nextgraph-rs` (`213338f697df15afc086c042f4bab1bffd01aa04`), which declares `@ng-org/orm@0.1.2-alpha.18`, `@ng-org/web@0.1.2-alpha.13`, `@ng-org/shex-orm@0.1.2-alpha.8` and `@ng-org/alien-deepsignals@0.1.2-alpha.11`. `packages/polyfill` installs `@ng-org/orm@0.1.2-alpha.21`, `@ng-org/web@0.1.2-alpha.14`, `@ng-org/shex-orm@0.1.2-alpha.9` and `@ng-org/alien-deepsignals@0.1.2-alpha.13` - the published packages are AHEAD of the source this repo cites, so where the two disagree both are named below. That gap is checked rather than remembered: the `ANCHOR` in `packages/polyfill/test/provenance.test.ts` holds it once and goes red from either end. Every claim points at a symbol rather than a line, so `git grep` settles any doubt after the code moves. Companion to [[knowledge_what-a-read-scope-is-upstream]], which answers the reading half.
+
+## Removing an object is a set mutation, and LEVEL 3 answers
+
+`sdk/js/orm/README.md` teaches it as one line — `dogs.delete(aDog)` — on the `DeepSignalSet` a subscription hands back. There is no `deleteObject` symbol at any version: `sdk/js/orm/src/core.ts` at the cited commit exports exactly `initNg`, `ngSession`, `OrmSubscription`, `DiscreteOrmSubscription`, `insertObject`, `getObjects`, plus `getRaw`/`watch`/`effect` re-exported from `@ng-org/alien-deepsignals`. The installed `@ng-org/orm@0.1.2-alpha.21` renames `OrmSubscription` to `RdfOrmSubscription` and adds one export the source does not carry, `removeObject(graphNuri, subjectIri): Promise<void>` - see the note at the end of this section. That absence is **not** the finding, and per [[no-divergence-from-nextgraph]] it would prove nothing on its own — the finding is that the set mutation is fully implemented, so the cascade stops at level 3 and there is nothing to invent.
+
+**`removeObject` exists in the package and not in the source.** Its own documentation declares a wider effect than the set mutation: `DELETE WHERE { GRAPH <graphNuri> { <subjectIri> ?p ?o } }`, every predicate of the subject rather than the shape's own, while claiming in the same comment to have "the same effect" as a `delete()` on a subscription's object. The two cannot both hold, and nothing in the cited source settles it. It stays unpublished here for the reason `contract_polyfill-surface` records: a symbol whose only evidence is an npm build is not something to build a guarantee on.
+
+## The path, hop by hop
+
+1. **The set proxy.** `deepSignal`'s set handler (`sdk/js/alien-deepsignals/src/deepSignal.ts`, the `delete` branch) emits, for an OBJECT member, `{ path: [...containerPath, syntheticId], op: "remove" }` — a `DeepPatch` with no `type`. For a LITERAL inside a multi-valued property it emits `{ path: containerPath, op: "remove", type: "set", value }` instead.
+2. **The synthetic id is `"<graph>|<subject>"`**, minted by `OrmSubscription.signalObjectPropGenerator` (`RdfOrmSubscription` in alpha.21), which also generates a subject IRI (`<first 53 chars of the graph NURI>:q:<33 random bytes base64url>`) when `@id` is `""`.
+3. **`deepPatchesToWasm`** (`sdk/js/orm/src/connector/utils.ts`) joins the path into the string `/<graph>|<subject>`.
+4. **`OrmSubscription.onSignalObjectUpdate`** (`RdfOrmSubscription` in alpha.21) batches in a microtask (or into `pendingPatches` inside a transaction) and calls `ng.graph_orm_update(subscriptionId, patches, session_id)`.
+5. **The binding.** `graph_orm_update` (`sdk/js/lib-wasm/src/lib.rs`) deserialises `OrmPatches` — `OrmPatch { op, valType, path, value }` with `OrmPatchOp::{add, remove}` and `OrmPatchType::set` (`engine/net/src/orm.rs`) — into `AppRequest::new_orm_update`.
+6. **The engine.** `Verifier::orm_frontend_update` → `create_sparql_update_query_for_patches` (`engine/verifier/src/orm/graph/handle_frontend_update.rs`): a `remove` whose path resolves to a ROOT object (one segment, no predicate) calls `SparqlBuilder::remove_object` and marks the tracked object `TrackedOrmObjectValidity::Invalid`. The queries are then run through `process_sparql_update`, anchored on the graph taken from the first patch's path.
+
+**The trap that makes a delete a no-op.** The patch is emitted only when `target.delete(rawValue)` returned true **and** a synthetic id is known for that object. So the object passed must be the one the set is holding — reached by iterating it, by `.first()` or by `.getBy(graph, subject)`. `getObjects` returns a `deepClone`, so deleting an item of ITS result removes nothing and reports nothing.
+
+## `remove_object` deletes the SHAPE's predicates, not the subject and not the document
+
+`SparqlBuilder::remove_object` loops the shape's own `predicates` and emits one `DELETE { GRAPH <g> { <s> <p> ?o } } WHERE { … }` per predicate. Triples on the same subject under a predicate the shape does not declare **survive**, and so does the document: nothing on this path deletes a document, and the ORM offers no call that does.
+
+Removing a child from a parent's multi-valued object property is a different arm — `remove_link`, a `DELETE DATA` of the one triple that ties parent to child. The README states the consequence plainly: only that tie goes, the child's own quads stay.
+
+## `getObjects` and `insertObject` — the exact surface
+
+```ts
+getObjects<T extends BaseType>(shapeType: ShapeType<T>, scope: Scope | string): Promise<DeepSignalSet<T>>
+insertObject<T extends BaseType>(shapeType: ShapeType<T>, object: T): Promise<void>
+```
+
+Both return types are **inferred**, not annotated, and both functions are thin wrappers over `OrmSubscription`.
+
+- **`getObjects`** (`sdk/js/orm/src/connector/getObjects.ts`) — `getOrCreate(shapeType, normalizeScope(scope))`, awaits `readyPromise`, schedules `close()` one second later, returns `deepClone(signalObject)`. The result is **detached**: a plain `Set` of plain objects, no two-way binding, no reactivity. `docs/api-contract.md` § 6 records this accurately — checked against the source, not re-derived.
+- **`insertObject`** (`sdk/js/orm/src/connector/insertObject.ts`) — opens a subscription scoped to `{ graphs: [] }` (deliberately subscribing to no document), awaits ready, `signalObject.add(object)`, `close()`. The object **must** carry `@graph`: a root object without one makes `signalObjectPropGenerator` throw *"When adding new root orm objects, you must specify the @graph"*. `@id: ""` means "generate one".
+
+## The three remaining symbols
+
+**`OrmSubscription`**, `RdfOrmSubscription` in alpha.21 — a class, and the machinery every other read and write goes through. Private constructor; `static getOrCreate(shapeType, scope)` pooled on `"<shape>|<graphs>|<subjects>"` with refcounting and a 500 ms close delay. Instance surface: `signalObject: DeepSignalSet<T>`, `readyPromise`, `close()`, `beginTransaction()`, `commitTransaction()`, `inTransaction`, `shapeType`, `scope`. In alpha.21 the second argument is no longer a bare `Scope` but an `RdfOrmConfig` (`Scope & { where?, orderBy?, pageSize?, maxActivePages? }`), `readyPromise` resolves to the subscription data rather than to nothing, and the instance also carries `mode`, `isReady`, `addChangeListener`, `removeChangeListener`, `nextPage` and `previousPage`. How far that config travels is answered in [[knowledge_what-a-read-scope-is-upstream]]: the shipped binding takes it at index 4 and the shipped ORM sends it there, while what the engine behind that binding does with it is settled by nothing reachable. The `json!({})` in `213338f6`'s `Verifier::start_orm` does NOT settle it, and reading it as *"level 1 discards the richness"* - the claim this leaf used to carry - is inference from an absent implementation. It hands a caller nothing the target will not hand them — a shape, a scope and a set — and `useShape`, `getObjects` and `insertObject` are all built on it.
+
+**`DiscreteOrmSubscription`** — the same class shape for JSON-CRDT documents. `static getOrCreate(documentId: string)`; `signalObject` is `DeepSignal<DiscreteArray | DiscreteObject> | undefined` (a getter, undefined before the initial payload); it reaches the engine through `orm_start_discrete` and `discrete_orm_update`. Its unit of subscription is **one document id**, never a `Scope`.
+
+**`ngSession`** — not a function and not a class: a module-level `Promise<{ ng: NG; session: Session }>` (`sdk/js/orm/src/connector/initNg.ts`), resolved exactly once by `initNg`. Every subscription awaits it before touching the engine. Its value is the SDK handle plus the session object.
+
+## A write never passes through `sparql_update`
+
+`graph_orm_update` is its own SDK member, distinct from `sparql_update`. So a guard implemented by overriding `ng.sparql_update` — which is what `packages/polyfill/src/surface/ng-proxy.ts` does — **does not see an ORM write at all**, neither an add nor a delete. The read-filtered view (`packages/polyfill/src/emulated-verifier/read-filter.ts`) is symmetrical by design: it forwards `add`, `delete` and `clear` to the underlying set untouched, because those yield no items to leak.
+
+That is a fact about where a guard can sit, not a proposal for one.
+
+## Live behaviour against the deployed broker
+
+Verified by measurement, not by reading: a live ORM read STARTS against the deployment, and the delete reaches the document. `packages/polyfill/e2e/orm-live-read.ts` is the measurement - `5 passed, 0 failed` on 2026-09-21, the read ready in 13ms, the seeded subject's triples gone after `.delete()`.
+
+The read was blocked until 2026-09-21, and the recorded reason was wrong twice over. It was not that the broker needed to catch up: the DEPLOYMENT was ahead and the pinned client packages were behind, `orm_start_graph` having gained a `config` parameter at index 4, before the callback, which the five-argument client of the day filled with its callback. Updating the packages answered it. The bug leaf that carried the wrong mechanism was deleted with the question it described.

.project/concepts/app-contract/knowledge_who-processes-an-inbox.md

@@ -30,8 +30,8 @@ What it never does: **process an inbox so that a `ReadCap` sent to it arrives**.
 
 The two arms this package has:
 
-- **A `ReadCap` delivery** (`inbox-dispatch.LINK_KIND`, whose name is upstream's own word for the variant) — held for the owner's ring and filed durably with `branch-registers.addLink`, the emulated `AddLink { read_cap }`. A payload declaring itself one of these and carrying nothing that reads is REFUSED and reported, which is the envelope validation above; it used to be handed back as consumer data.
-- **A bare `reference`** — a deposit whose payload IS a `did:ng:` reference and nothing else: no operation, no claim, no copy of any value. `emulated-verifier/index-deposit.ts`, `applyIndexDeposit`, resolves it and LOOKS: which document the inbox belongs to (the owner's own `AddInboxCap` pairing, `readInboxCapPairs`), what that document declares it indexes by (`urn:ng-helpers:index:field`, on the document's own NURI as subject), whether the reference is already in, what the referenced object says for that field — and only then writes ONE entry (`urn:ng-helpers:index:value`, subject = the object's NURI). Since anyone may deposit, a payload carrying an operation would be a licence to rewrite someone else's document, and a payload carrying a value would put in the index something the object does not say. **An index only ever grows**: nothing there removes an entry and nothing there can express a removal, which is what makes an empty read harmless — absent, unreadable and failed all mean *not added this time*, and a later deposit adds it. An unresolved reference is reported and costs nothing; an already-indexed object is passed over; a document declaring no field, or several, refuses rather than write something wrong — and that refusal leaves READING its entries untouched.
+- **A `ReadCap` delivery** (`inbox-dispatch.LINK_KIND`, whose name is upstream's own word for the variant) — held for the owner's ring and filed durably with `branch-registers.addLink`, the emulated `AddLink { read_cap }`. A payload declaring itself one of these and carrying nothing that reads is REFUSED and reported, which is the envelope validation above; it used to be handed back as consumer data. Being refused does not save it: the arm ran, so the deposit was already consumed.
+- **A bare `reference`** — a deposit whose payload IS a `did:ng:` reference and nothing else: no operation, no claim, no copy of any value. `emulated-verifier/index-deposit.ts`, `applyIndexDeposit`, resolves it and LOOKS: which document the inbox belongs to (the owner's own `AddInboxCap` pairing, `readInboxCapPairs`), what that document declares it indexes by (`urn:ng-helpers:index:field`, on the document's own NURI as subject), whether the reference is already in, what the referenced object says for that field — and only then writes ONE entry (`urn:ng-helpers:index:value`, subject = the object's NURI). Since anyone may deposit, a payload carrying an operation would be a licence to rewrite someone else's document, and a payload carrying a value would put in the index something the object does not say. **An index only ever grows**: nothing there removes an entry and nothing there can express a removal. That once made an empty read harmless — absent, unreadable and failed all meant *not added this time*, and a later drain settled it. Consumption ends that, and forces a distinction the read layer erases: `read-model.readDoc` answers `[]` whether the document is empty or the broker failed. Three sources of "no rows" are now told apart (`index-deposit.noRowsMeansAbsent`). A read that **threw** — reported through the new `onUnreadable` hook — is `unreadable`. A repo whose sync this session never confirmed is also `unreadable`, and this is the one that is easy to miss: on a fresh session over a persistent wallet the repo is present but its commits have not arrived, so the anchored query matches nothing **and raises nothing** — `open-repo` keeps `synced` and `timed-out` apart for exactly this, and says so in those words. A document this holder cannot even attempt — no cap, so the read layer drops it before issuing a query — is `unreadable` too, and that one is counter-intuitive enough to state plainly: "no cap" LOOKS deterministic and is not, because for a stranger's public document possession comes from a network fetch that swallows its errors and memoises the failure, so one outage is indistinguishable from a document that never existed. Only a document that was actually QUERIED, from a confirmed repo, and still read empty is genuinely absent — that is `refused`: reported, costs its own deposit, and the deposits behind it keep their turn. `unreadable` THROWS and stops the drain, so an outage cannot walk the queue. Getting the split wrong is costly in both directions and both were shipped before it settled: treating a failure as an absence destroyed whole queues on a cold start, and treating an absence as a failure let one dead reference — deposited by anyone — stall an index's queue one deposit per connection. An unresolved reference costs its own deposit and is reported; an already-indexed object is passed over; a document declaring no field, or several, refuses rather than write something wrong (both are clean reads, so both are `refused` and neither stops the drain) — and that refusal leaves READING its entries untouched.
 
 *(Those two IRIs are `@ng-helpers/indexing`'s namespace, kept letter for letter because renaming them is a data-format change nobody decided. This package writing another package's namespace is odd, and it is recorded as odd rather than acted on.)*
 
@@ -43,9 +43,15 @@ The two arms this package has:
 
 **After a deposit whose recipient is absent.** A deposit that landed arms a deferred stand-in for the session the owner does not have. What it achieves is the only part written down outside the package: **deposits converge** — a share becomes readable without the recipient re-opening the page. *How* is deliberately not documented here. The mechanism is unpublished by design: nothing lets a caller ask for it, name another user's inbox, or turn it off, and the confidentiality of the whole shared-wallet emulation rests on its being unreachable. Its limit is stated rather than hidden — it lives in a page, so if the page goes away the deposit waits for its owner's next connection, which is the real path and not a repair.
 
-**And it applies the registers, not the documents.** Running for an owner who is not the one holding the page, it takes the arms that write the verifier's own bookkeeping and stops there: writing application data into an absent owner's documents from a stranger's session is a different act, and this package does not take it. So a `reference` deposit is left — traced, not reported, because waiting is not failing — and the owner's own next connection applies it. Nothing is lost: see below.
+**And it applies the registers, not the documents.** Running for an owner who is not the one holding the page, it takes the arms that write the verifier's own bookkeeping and stops there: writing application data into an absent owner's documents from a stranger's session is a different act, and this package does not take it. So a `reference` deposit is left — traced, not reported, because waiting is not failing — and the owner's own next connection applies it. It is left in the QUEUE too, not merely unapplied: what a stranger's drain declines to apply it must not consume either, or the owner would lose it to a session that was never going to apply it. See below.
 
-**Nothing is ever consumed.** No path retires an applied deposit: an inbox here is re-readable where upstream it is a queue. That is what makes every abandon, every reported refusal and every watch that could not be opened harmless — what was not applied is still there for the next push or the next connection. It is also what makes re-applying safe: every arm is idempotent, so seeing every deposit again on every run lands on the same result.
+**What is applied is CONSUMED — one act, one place.** Since 2026-08-26 a deposit this package claims is retired from its inbox by `emulated-verifier/inbox-consume.ts`, which holds the only removal and the only loop that performs it; both triggers above call it and neither carries a copy. The order is upstream's, read in its source: the broker removes the message from the queue *before* delivering it (`take_first_msg` → `MSGS.take_first_value`, a read followed by a `del`), and the verifier then applies it and merely logs what it could not (`log_err!("Error during process_inbox {e}")`, never re-enqueued). So **remove, apply, log, move on** — a deposit is delivered once whether or not its arm succeeded, and a refusal is reported once instead of at every push and every connection for ever.
+
+**What is NOT claimed is not consumed**, and the distinction carries the safety of the whole thing. Two things are left in the queue: a consumer's own payload, which declares no kind of this package's and is not a message at all; and an arm that belongs to the owner's own session while a stranger's is running — the `reference` case above. `inbox-dispatch.claimsDeposit` asks that question *before* the removal, precisely so that what a stranger's drain declines to apply it also declines to pop. Upstream the question does not arise, because only a registered reader is ever popped for (`inbox_pop_for_user`); here one inbox mixes both kinds, so it has to be read off the payload. Getting it backwards is the one way consuming could lose data outright — a stranger's timer retiring a reference the owner never indexed.
+
+**A failure that happens before the pop still leaves the deposit.** A drain whose *read* fails takes nothing out, so what is queued waits for the next attempt; a drain whose *arm* fails has already consumed what it was given. The two are different sentences and the package's log says which is which.
+
+**The idempotence that remains is not a replay compensation.** Filing the same Link twice is still a no-op, and a reference already in an index is still passed over — because the same cap or the same object can legitimately arrive as **two distinct deposits** (a re-share, a rotation, two depositors pointing at one thing), not because one deposit is seen twice. Upstream keeps the same check with a queue that pops (`ContactAlreadyExists`), which is the proof it never answered the replay.
 
 ## NextGraph itself
 

.project/concepts/app-contract/polyfill-surface/contract_polyfill-surface.md

@@ -9,13 +9,16 @@ summary: The API @ng-eventually/polyfill exposes to an application — signature
 
 This package is a polyfill of NextGraph's SDK.
 
-This package covers placement (creating and listing an application's documents by scope), reading (a document's subjects, one-shot or reactive), sharing a document with a named user, and depositing into inboxes. It does not cover user management, display names, transport, or the operation of a deployment.
+This package covers placement (creating an application's documents in one of its three stores), reading (a document's subjects, one-shot or reactive, by shape), writing one shape-typed object, sharing a document with a named user, and depositing into inboxes. It does not cover user management, display names, transport, or the operation of a deployment.
 
 ### Deployment requirements
 
 An application using this package must:
 
 - serve a wallet file (`.ngw`) from its own bundle, and pass its URL and password to `configure` as `sharedWallet: { fileUrl, password }`;
+- pass `configure` the SDK's shape query (`ormSubscription: RdfOrmSubscription.getOrCreate`, from `@ng-org/orm`) and its `initNg`, and call this package's `initNg(ng, session)` once a session has arrived, if it uses `useShapeQuery`. That read goes through the SDK now, and the SDK is injected here rather than imported; without the injection the read publishes `isError` naming the field;
+- pass `configure` the SDK's `getObjects` and `insertObject` (from `@ng-org/orm`, as they stand) if it calls the calls of the same name here. Same reason and same shape as the shape query: they are injected rather than imported, and without the injection each throws naming the field to pass;
+- call this package's `initNg`, not the SDK's, whenever it uses anything of the ORM. That call decides which `ng` the ORM reaches the engine through, and this package substitutes its own - the same object `ng` publishes - so that an ORM write meets the same guard every other write meets. Calling `@ng-org/orm`'s `initNg` directly leaves ORM writes ungoverned;
 - call `init(…)` — this package's, not the one it passed to `configure` — and then await `ensureIdentity()`, in a browser context, before rendering its interface. `ensureIdentity()` resolves once a session is open, and a session arrives only through `init`: awaited before `init` has been called, it throws and names the call to make first;
 - **declare this package exactly once**, so that everything in the application resolves to one copy of it — see the single-copy rule under `## Non-guarantees`, which is the one packaging mistake this surface cannot protect you from.
 
@@ -30,7 +33,16 @@ Full typed shape: the package's `types` entry, `@ng-eventually/polyfill`. A type
 export function configure(c: EventuallyConfig): void;
 export interface EventuallyConfig {
   ng: NgLike;                                    // the `ng` object from @ng-org/web
-  useShape: UseShapeLike;                        // `useShape` from @ng-org/orm
+  // The ORM's REACT hook. It is NOT on `@ng-org/orm`'s main entry - that resolves to
+  // `core`, which exports no `useShape` - so import it from `@ng-org/orm/react` (the
+  // default export) or as `reactUseShape` from `@ng-org/orm/all`. Pass it as it
+  // stands; no wrapper, no cast.
+  useShape: UseShapeLike;
+  // `RdfOrmSubscription.getOrCreate` from @ng-org/orm - the SDK's shape query, which
+  // `useShapeQuery` reads through. Pass it as it stands; no wrapper, no cast.
+  ormSubscription?: OrmSubscriptionLike;
+  getObjects?: GetObjectsLike;                   // `getObjects` from @ng-org/orm
+  insertObject?: InsertObjectLike;               // `insertObject` from @ng-org/orm
   sharedWallet?: SharedWalletConfig;             // { fileUrl, password, importUrl? }
   debugAccessLog?: boolean;
   init?: (...args: any[]) => any;
@@ -43,34 +55,57 @@ export async function ensureIdentity(): Promise<PrincipalId>;   // returns who y
 // ── addressing ───────────────────────────────────────────────────────────
 export type Nuri     = `did:ng:${string}`;
 export type NuriLike = Nuri | string;
-export type Scope    = "public" | "protected" | "private";
+// The SDK's own scope, re-exported unchanged. It scopes a READ, on two axes and no third.
+export type Scope    = { graphs?: string[] | string; subjects?: string[] };
 
 // ── placement: where an application's documents live ─────────────────────
+// A store is named by its REFERENCE — one accessor per store, and `createEntityDoc` takes
+// one of them. Omit it and the document goes to the private store.
 export const storeRegistry: {          // no identity parameter — a session is one user's
-  createEntityDoc(scope: Scope): Promise<Nuri>;
-  listMyEntityDocs(scope: Scope): Promise<Nuri[]>;
-  resolveScopeGraph(scope: Scope): Promise<Nuri>;
-  resolveWriteGraph(scope: Scope): Promise<Nuri>;
+  privateStore(): Promise<Nuri>;
+  protectedStore(): Promise<Nuri>;
+  publicStore(): Promise<Nuri>;
+  createEntityDoc(store?: NuriLike): Promise<Nuri>;
   openDocumentInbox(doc: NuriLike): Promise<Nuri>;
 };
 
 // ── reading ──────────────────────────────────────────────────────────────
-export async function readUnion(docs: NuriLike[]): Promise<UnionSubject[]>;
-export interface UnionSubject { subject: string; graph: Nuri; props: Record<string, string[]> }
-export function useShape(shapeType: unknown, scope: unknown): unknown;   // read-filtered view
-// TWO positional arguments — the same pair `useShape` takes. `ShapeQuery` is what you
-// READ BACK (the snapshot), never what you pass in.
-export function watchShape<T = UnionSubject>(shapeType: unknown, scope: Scope): ShapeObservable<T>;
-export interface ShapeObservable<T = UnionSubject> {
+// Reading a document BY NAME is `docs.sparqlQuery` below - one anchored query, one
+// document. `readUnion` and `UnionSubject` were published here until `1.0.0-dev.8`;
+// nothing takes their place, because they were that call in a loop plus policies of
+// this package's own. See `## Change policy`.
+export function useShape<T extends BaseType>(                            // read-filtered view
+  shapeType: ShapeType<T>,
+  conf: RdfOrmConfig<T> | string | undefined,
+): ShapeResult;                          // { data, promise, subscription, isLoading, nextPage?, previousPage? }
+// TWO positional arguments — the same pair `useShape` takes, both of them the SDK's own
+// types. `ShapeQuery` is what you READ BACK (the snapshot), never what you pass in, and
+// its items are the SHAPE's objects: `@id`, `@graph` and the shape's readable predicates.
+export function useShapeQuery<T extends BaseType = BaseType>(
+  shapeType: ShapeType<T>,
+  scope: Scope,
+): ShapeObservable<T>;
+export interface ShapeObservable<T extends BaseType = BaseType> {
   getSnapshot(): ShapeQuery<T>;                  // stable reference until the state changes
   subscribe(onChange: () => void): () => void;   // returns its own unsubscribe
-  refetch(): void;                               // re-resolve and re-read now; never polls
+  refetch(): void;                               // ask again now; never polls
 }
-export interface ShapeQuery<T = UnionSubject> {
+export interface ShapeQuery<T extends BaseType = BaseType> {
   data: T[]; isPending: boolean; isSuccess: boolean; isError: boolean; error: unknown;
 }
+// The ORM's one-shot read, at the SDK's own name and signature. `config` is a `Scope`
+// plus `where` and `orderBy`; the result is an ARRAY when it carries an `orderBy` and a
+// `Set` otherwise, and it is a CLONE - mutating or deleting an item of it reaches nothing.
+export async function getObjects<T extends BaseType>(
+  shapeType: ShapeType<T>,
+  config: Omit<RdfOrmConfig<T>, "pageSize" | "maxActivePages">,
+): Promise<T[] | Set<T>>;
+export type RdfOrmConfig<T> = Scope & { where?: ...; orderBy?: ... };  // the SDK's own
 export function subscribeDoc(nuri: NuriLike, onChange: (r: DocChange, t: DocChangeType) => void): Unsubscribe;
 export function subscribeDocs(nuris: NuriLike[], onChange: (r: DocChange, t: DocChangeType) => void): Unsubscribe;
+// Extracts the variant key from a DocChange - "State" / "Patch" / "TabInfo" / ... -
+// a convenience over the verified payload shape, not an upstream call.
+export function docChangeType(resp: DocChange): DocChangeType;
 
 // ── low-level document / SPARQL primitives ───────────────────────────────
 export const docs: {
@@ -84,6 +119,12 @@ export const docs: {
   sparqlUpdate(sessionId: string | number, query: string, anchor?: NuriLike, label?: string): Promise<unknown>;
 };
 
+// -- writing one shape-typed object ---------------------------------------
+// The SDK's own name and signature. The object MUST carry `@graph` - it is the only
+// thing that says which document the write lands in - and what comes back is the object
+// with its `@id` filled in where one was left empty.
+export async function insertObject<T extends BaseType>(shapeType: ShapeType<T>, object: T): Promise<T>;
+
 // ── inbox: giving to read, and depositing ────────────────────────────────
 export const inbox: {
   share(doc: NuriLike, toUser: string): Promise<void>;      // give a reader the key
@@ -102,29 +143,90 @@ export interface Deposit { from: PrincipalId | null; payload: unknown; ts: numbe
 
 // ── the wrapped SDK objects ──────────────────────────────────────────────
 export const ng: NG;                    // call this instead of the `ng` passed to `configure`
-                                        // `NG` is upstream's own type (`@ng-org/web`), 88 typed
+                                        // `NG` is upstream's own type (`@ng-org/web`), fully typed
                                         // members; it was `Record<string, any>` until 2026-08-14
 export function init(...args: any[]): any;      // likewise — not the `init` passed to `configure`
-export function initNg(...args: any[]): any;
+export function initNg(...args: any[]): any;    // likewise, and position 0 is DISCARDED - see below
 ```
 
+**A shape, in full, because one has to be written by hand.** `ShapeType` asks for `readablePredicate`, `minCardinality` and `maxCardinality` on every predicate, a `schema` keyed by the shape's own IRI, and objects carrying `@id` and `@graph` - and assembling that from the SDK's type declarations is a read this leaf exists to spare you. The shape below is `examples/notebook/app.ts`'s, predicate for predicate - that application reads with it against a deployed broker - and `rdf-orm build` generates exactly this object from a `.shex` file, so nothing here depends on the generator. The object interface and the type argument beside it are not that application's: it reads an untyped snapshot and narrows at the call site, which works and types nothing.
+
+```ts
+import { useShapeQuery } from "@ng-eventually/polyfill";
+import type { BaseType, ShapeType } from "@ng-eventually/polyfill";
+
+const RDF_TYPE = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type";
+
+// What a read HANDS BACK: `@id` and `@graph` come from `BaseType`, plus one field per
+// predicate, named by that predicate's `readablePredicate`.
+interface NoteObject extends BaseType {
+  type: string;
+  title: string;
+  body: string;
+}
+
+const NoteShape = {
+  shape: "urn:notebook:NoteShape",             // the shape's own IRI...
+  schema: {
+    "urn:notebook:NoteShape": {                // ...which is also the `schema` key...
+      iri: "urn:notebook:NoteShape",           // ...and the shape's own `iri`
+      predicates: [
+        // The matching constraint: a subject carrying `rdf:type urn:notebook:Note`.
+        { iri: RDF_TYPE, readablePredicate: "type",
+          dataTypes: [{ valType: "iri", literals: ["urn:notebook:Note"] }],
+          minCardinality: 1, maxCardinality: 1 },
+        // And the fields that come BACK. A predicate the shape does not NAME is not
+        // projected, so a shape written only to match returns objects with no fields.
+        { iri: "urn:notebook:title", readablePredicate: "title",
+          dataTypes: [{ valType: "string" }], minCardinality: 1, maxCardinality: 1 },
+        { iri: "urn:notebook:body", readablePredicate: "body",
+          dataTypes: [{ valType: "string" }], minCardinality: 1, maxCardinality: 1 },
+      ],
+    },
+  },
+} satisfies ShapeType<NoteObject>;
+
+// Pass the object type as the TYPE ARGUMENT. `ShapeType<T>` mentions `T` in none of its
+// members (it is `{ schema, shape }`), so nothing infers it from the shape: left out, `T`
+// is `BaseType` and the snapshot is untyped. MEASURED - `tsc` refuses the assignment.
+const notes = useShapeQuery<NoteObject>(NoteShape, { graphs: "did:ng:i" });
+```
+
+`minCardinality: 1` is what turns a predicate into a required triple pattern, so a shape whose every predicate is optional matches every subject in reach. `maxCardinality: -1` is unbounded. `valType` is one of `"number" | "string" | "boolean" | "iri" | "shape"`, and `literals` pins the required value - which is how the `rdf:type` entry above becomes the match rather than a field you read.
+
+**`initNg`'s FIRST ARGUMENT IS DISCARDED, and what goes in its place is the `ng` above.** The Deployment requirements say to call `initNg(ng, session)` while `## Surface` says to use this package's `ng` rather than the one `configure` received, so there is a choice to make - and it makes none: this call drops whatever sits in position 0 and hands NextGraph's ORM the published `ng`, the same object, then passes every remaining argument and the return value straight through. MEASURED on `1.0.0-dev.14`: a sentinel object passed in position 0 never arrives, and what does arrive is `===` the exported `ng`. That is deliberate rather than a defect - the ORM reaches the engine through whatever this call resolves, an ORM write leaves by `ng.graph_orm_update`, and that is where the write guard sits - but it is not something to have to establish by experiment. The parameter stays in the signature because upstream's `initNg(ngImpl, session)` has it, and a call site written for the target must keep compiling.
+
+**`ShapeObservable` is on the deletion list, and it goes WITH the shared wallet, not before it.** It is not a framework adapter: it carries the capability filter (`getSnapshot()` returns a view filtered by the capabilities held) and the capability-arrival re-publish (a subscription that re-publishes when a capability arrives). A capability arrives mid-session only because the wallet is shared; in the target an identity holds its own wallet and its capabilities from the start, so there is nothing to filter and no arrival to re-publish on. The announced form, a hook returning `{ data, isPending, isSuccess, isError, error }`, has nowhere to hang such a subscription, because the target does not need one. The type stays exported and you may write it down; what you cannot do is plan to drop it on its own ahead of the rest of the shared-wallet code.
+
+**`refetch()` has NO RECORDED COUNTERPART.** It is the only published way out of a read that is stuck pending. The announcement recorded in this repository lists five fields, `{ data, isPending, isSuccess, isError, error }`, and `refetch` is not among them. That is a statement about the RECORD, nothing more: TanStack Query's own `useQuery` does return a `refetch`, so a successor may well exist, but this repository holds no record of one and cannot name what an application leaning on `refetch()` would migrate onto. Treat it as an open migration point, not as a call that has a mapped replacement.
+
 ## Guarantees
 
 Every entry accepts `NuriLike` and validates at the door; what it returns is a precise `Nuri`. No type guard is published.
 
-A returned reference carries no key — not `createEntityDoc`, not `listMyEntityDocs`, not `UnionSubject.subject` / `.graph`. A reference found inside a document yields a name, not a key.
+A returned reference carries no key — not `createEntityDoc`, not the three store accessors. A reference found inside a document yields a name, not a key.
 
 You read a document whose key you hold: you created it, it was shared with you, or it sits in a public store, which serves its read key to whoever asks. No call answers "may I read this?".
 
 What was shared with you becomes readable after `ensureIdentity()`.
 
-`readUnion` returns one entry per distinct subject present in a document. `subject` is that subject's IRI exactly as written, and is a `string`, because a subject may be any IRI; `graph` is the document reference you passed in, and is the `Nuri` to hand back to this surface. Properties of different subjects are never merged, and the same subject IRI found in two documents stays two entries, told apart by `graph`. Several objects in one document are allowed. Recommended placement is one document per business entity: access is granted per document.
+**An anchored `docs.sparqlQuery` reads exactly the document you name, and returns its triples as written.** The anchor makes that document's graph the query's default graph, so a body with no `GRAPH <...>` wrapper reads that document and nothing else; a body that DOES carry one iterates the named graphs regardless of the anchor, so do not write one. Subjects come back as the document carries them — several subjects in one document is allowed and each stays its own, since a subject may be any IRI. Reading several documents is this call once per document; there is no call that takes a list, and composing one with an anchorless query instead would silently widen what the read reaches. Recommended placement is one document per business entity: access is granted per document.
 
-`urn:ng-eventually:` is reserved, and the reservation has two faces. In a document: triples whose **subject** falls under that prefix are dropped on read and never returned by `readUnion`; every other IRI is returned. In a deposit: two payload shapes are this package's own and it acts on them — a payload that IS a reference (a bare `did:ng:…` string and nothing else), and an object whose `kind` property is a string starting with `urn:ng-eventually:inbox:`. **Every other payload is yours, and is delivered to you untouched.**
+**And a document it cannot read is refused OUT LOUD, never swallowed into an empty answer.** A document you hold no capability for - and whose public store has none to give - is refused before the read leaves, naming the document; a public store that could not be ASKED rejects with that failure instead, because both stop the read and only one of them tells you to try again. Nothing is skipped on your behalf: tolerating one unreadable document was the removed `readUnion`'s own policy, and it went with it in `1.0.0-dev.8`, so whether one ends a loop over several is now your decision at your call site. A rejection means "unknown", never "absent", here as everywhere.
 
-**Do not use either shape to carry your own data.** Depositing one is still accepted and it is still returned to you by `inbox.read` and its variants — nothing is withheld — but this package now also acts on it, and what you observe is one of two things: it writes an entry into the document the inbox belongs to, if that document is one it can index; otherwise it reports a refusal on its own log stream (`console.error`, ungated, as below). That refusal does not clear on its own the way an unreachable inbox does: a deposit is not consumed, so the same refusal is reported again at every arrival on that inbox and at every connection, for as long as the deposit sits there. Carry your own data in an object with a `kind` of your own — `{ kind: "join", … }` is yours and stays yours — and never as a bare reference on its own.
+**Which reads reach a document in a public store from nothing but its `reference`.** This is the stranger's case - the document was shared with nobody, its `reference` circulated, and the reader holds no key for it - and two calls serve it. An anchored `docs.sparqlQuery` asks the public store for the key before it reads, and already did so before `1.0.0-dev.6`: the removed `readUnion` was that same ask, once per document, so a one-shot `document read` of one named public document is exactly what it always was. `useShapeQuery` asks too, since `1.0.0-dev.9`, once per document NAMED in `scope.graphs` - so a `shape read` serves the same case now, reactively and typed, and a holder of nothing opens a public document named that way (measured in the unit suite, and live against the broker). The three that do NOT ask, and in which such a document therefore does not appear: `useShape`, `getObjects`, and `useShapeQuery` under `graphs: "did:ng:i"` or `""` - naming no document, there is nobody to ask about. Read it once by naming it and the key lands in what you hold, which all three re-read on.
 
-Only a document's owner writes to it. Holding its read key never grants a write.
+`urn:ng-eventually:` is reserved, and the reservation has two faces. In a document: this package writes its own registers under subjects carrying that prefix, in the same graph as your data — so **an anchored `docs.sparqlQuery` returns them alongside your triples, and it is yours to ignore them**. Until `1.0.0-dev.8` the removed `readUnion` dropped them for you; nothing does now. This is not a gain of rights: the two registers an ordinary document carries are a document's inbox address and, for a public document, the read key its store already serves to whoever asks. Nothing else of this package's is written into your documents. Do not write under that prefix yourself. In a deposit: two payload shapes are this package's own and it acts on them — a payload that IS a reference (a bare `did:ng:…` string and nothing else), and an object whose `kind` property is a string starting with `urn:ng-eventually:inbox:`. **Every other payload is yours, and is delivered to you untouched.**
+
+**Do not use either shape to carry your own data.** Depositing one is still accepted and it is still returned to you by `inbox.read` and its variants — nothing is withheld — but this package now also acts on it, and what you observe is one of two things: it writes an entry into the document the inbox belongs to, if that document is one it can index; otherwise it reports a refusal on its own log stream (`console.error`, ungated, as below). That refusal is reported ONCE and then the deposit is gone: this package consumes what it claims, whether or not the arm succeeded. Until `1.0.0-dev.4` the same refusal came back at every arrival on that inbox and at every connection, for as long as the deposit sat there. The same now applies when the referenced document resolves but carries **nothing for the field its index declares** — a draft, say: the reference is discarded and reported, where before it sat in the queue and would have been indexed by a later drain once the document gained that field. Deposit the reference again after the document says what it needs to say. Carry your own data in an object with a `kind` of your own — `{ kind: "join", … }` is yours and stays yours — and never as a bare reference on its own.
+
+Only a document's owner writes to it. Holding its read key never grants a write. **Since `1.0.0-dev.7` that covers what you write through NextGraph's ORM too** - `insertObject`, and a mutation of the live set a shape query handed you (`set.add(...)`, `set.delete(...)`, assigning a property). It used to cover only `docs.sparqlUpdate`: an ORM write leaves by a different door, and nothing was standing at it. Refusal happens before the write is attempted, and one document you may not write refuses the whole batch the ORM was flushing.
+
+**`getObjects(shapeType, config)` answers with what you hold, and nothing else.** Objects living in documents you have no key for are not in the result - the same rule the two shape reads follow, applied per document on what comes back. The collection keeps the shape the SDK gave it: an `orderBy` in the config yields an array, anything else a `Set`. What you get is a CLONE, detached from the database: changing an item of it changes nothing anywhere, and deleting an item of it removes nothing and reports nothing.
+
+**`insertObject(shapeType, object)` needs the object's `@graph`**, and refuses a document you do not own. The `@graph` is the only thing that says which document the write lands in - upstream the insert subscribes to no document at all - and it is also what decides the refusal, so there is nothing extra to pass. An object with no `@graph` is forwarded and NextGraph refuses it in its own words.
+
+**"This document has no inbox" is an answer, and only an answer, since `1.0.0-dev.9`.** `inbox.postToDocument` refuses a document whose owner never opened an inbox, and `inbox.readForDocument` / `readSyncedForDocument` answer `[]` for one - both unchanged, both still the ordinary case. What changed is that a read which could not HAPPEN no longer arrives as one of those: a broker that cannot answer for the document, or a public store that cannot be asked for its key, now rejects. Until this version a depositor was told the owner had opened nothing, and a reader was handed an empty list, for a document whose inbox is full.
 
 `inbox.share(doc, toUser)` names the document and the person; the recipient calls nothing. It refuses a recipient nobody has signed in as, rather than creating them.
 
@@ -154,15 +256,35 @@ Where a call must first find out whether something already exists — a document
 
 **`storeRegistry.openDocumentInbox(doc)` is idempotent, including when calls overlap.** Asks for the same document that are in flight together are answered by one call, and every one of them gets the same inbox — you do not have to serialise them yourself, and firing one per component as they mount is a supported way to use it. This holds **within one page**; two pages doing it in the same moment is a non-guarantee below, and it is the only part of this you have to think about.
 
-**A reactive read says "nothing" and "I could not find out" differently.** `watchShape` answers in three states and only two of them are answers about your data: `isPending` while the question is still open, `isSuccess` once it has been answered, `isError` when it could not be. An empty `data` under `isSuccess` means this scope holds no document of that shape — the distinction the surface exists for. Until 2026-08-17 a scope whose listing did not answer published that very snapshot, so an interface showed "you have created nothing" for "the store did not answer"; it now publishes `isError` carrying the error. And because an observable cannot take back a list a subscriber has already rendered, `data` under `isError` keeps the **last read that answered** rather than emptying — so an empty `data` is never handed to you as a failure's answer. Read the load state before `data`: **a rejection means "unknown", never "absent"** here too.
+**A reactive read says "nothing" and "I could not find out" differently.** `useShapeQuery` answers in three states and only two of them are answers about your data: `isPending` while the question is still open, `isSuccess` once it has been answered, `isError` when it could not be. An empty `data` under `isSuccess` means this scope holds nothing of that shape — the distinction the surface exists for, and the one thing it will never do is publish that snapshot for a read that did not happen. And because an observable cannot take back a list a subscriber has already rendered, `data` under `isError` keeps the **last read that answered** rather than emptying — so an empty `data` is never handed to you as a failure's answer. Read the load state before `data`: **a rejection means "unknown", never "absent"** here too.
 
-The same rule reaches what a call hands BACK, not only what it looked up first: **`listMyEntityDocs` returns a listing whose documents you can open, or it throws.** It reads which documents are in the store and what opens each, and it throws if either did not answer — including when the documents came back and their keys did not. Nothing about a keyless listing is visible to you: it is the same `Nuri[]`, and the difference would only appear at the next read, empty, long after the cause. An empty array therefore means this account created nothing.
+**A document you NAME in `graphs` is reached before the read opens, since `1.0.0-dev.9`.** Naming a document in a scope is the same act as anchoring `docs.sparqlQuery` on it, and it is now answered the same way: the key is asked of a public store if you do not already hold it, the document is refused out loud if you hold no key for it, and its repo is synced before the question is put. A named document you cannot read publishes `isError`, where until this version it reached the engine, came back, and was emptied by the per-document filter into `isSuccess` with `data: []` - the one snapshot this surface reserves for "this scope holds nothing". A named document that has never synced published that same snapshot for a document that is not empty; it now stays **PENDING** instead - the sync barrier is consulted on every publication, and a named document whose barrier was not crossed is not an answer. **Since `1.0.0-dev.10` that half carries no qualification.** It held only within one ordinary session until then, and the two situations that broke it - a second `configure(...)`, which published an empty or stale success, and a broker refusing a subscription after this package had stopped waiting for the document's first push, which left the read withheld with no way back - are closed: "is this document open in this session" now has exactly one answer, the state of the document's one real subscription, rather than three records that could disagree. Nothing failed there, so it is not `isError`: the subscribe succeeded and the read did not throw, what is missing is the authority to say the document is empty. If the document later syncs and brings data, the read answers by itself. If it never does, the read stays pending for that session - handle a `isPending` that does not end, as you already must for a shape query the engine refuses. **Naming SEVERAL documents fails as a whole** when one of them cannot be reached: a short list is the same lie as an empty one, so nothing is answered rather than half of it. What is NOT touched, and each stays a success: `graphs: "did:ng:i"` or `""` (you named no document - the per-document filter is the whole of the answer there, and an empty result means you hold nothing of that shape), `graphs: []` (no objects, by NextGraph's own definition), and a named document you can read that holds nothing of the shape.
 
-**A deposit made while a person is looking at the page arrives while they are looking at it.** For as long as an identity is connected, every inbox it may read is watched and what lands in one is applied as it lands — its own inbox, and the inbox of every document it has opened one on, including a document whose inbox it opens later in the same session. So a `ReadCap` sent with `inbox.share` becomes usable in the recipient's live session with no reload and no call from the application, and a `watchShape` that was empty for want of that `ReadCap` re-reads and publishes the document it now opens. Until 2026-08-17 only the backlog waiting at connection was applied, and a deposit made in front of its recipient converged only when that person reloaded the page.
+**And it converges by itself.** A named scope refused this way is not a dead view. Whether you may reach the documents you named is re-read on every publication rather than decided once, so a key arriving turns the refusal into the document through the same channel that already re-published a filtered read - and a scope whose barrier failed outright is attempted again on that signal. The ordinary sequences all converge with no call from the application: a page whose components subscribe before the connection work has restored its keys, a document shared with you while you are looking at the screen, a broker that hiccupped once and healed, and a key arriving in the same instant the read was deciding. One consequence to design for: an interface that renders `isError` will briefly show it where it used to show an empty success, so branch on the load state rather than on `data` alone. Nothing here polls, so a scope refused in a session whose keyring never moves again stays `isError` until your own `refetch()` - which is what `isError` has always meant here, and what it means for every other failure this call reports.
+
+**A named scope goes back to PENDING when the session changes under it.** Signing in again inside the same page gives a new session, whose repos this package has synced nothing for yet - so a named scope that was answering returns to its loading state until the documents it names are confirmed again, and `refetch()` is what confirms them. Withholding is deliberate: a barrier crossed in the session that has just gone is not one the new session has crossed, and the alternative is answering from a subscription nothing re-established. This is the one case where a read that had answered stops answering, and it does not arise on an ordinary page load - there the whole page is new.
+
+**A standing failure is the SAME snapshot.** While a refusal persists unchanged, the snapshot object does not change either, so `useSyncExternalStore` and anything else comparing by identity see no update - even though the read is being attempted again underneath. A failure that says something different is published normally.
+
+**What it costs.** One public-store ask and one sync barrier per document named, once per session. The opens for a scope naming several documents run together, so the wait is the slowest of them rather than their sum. The wait itself is bounded internally, so a document that never answers does not hold the open for ever - but the READ over it stays pending, because a barrier that was never crossed is not authority to call anything empty.
+
+**Which failure lands in `isError` changed in `1.0.0-dev.6`, and one of them now stays PENDING.** The read goes through the SDK's own shape query, so what `isError` carries is the query failing to open: a shape the ORM cannot subscribe, or a `configure` that was never given `ormSubscription`. A start the underlying engine REFUSES does not reach it: NextGraph catches that failure and logs it, and its readiness signal is only ever resolved, never rejected, so such a read stays `isPending` indefinitely. The guarantee above is unaffected — you are still never told "there is nothing" for "nobody answered" — but an interface that handles only `isError` will show its loading state where it used to show an error. Handle a `isPending` that does not end.
+
+**A read is scoped by document and by subject, never by store.** `Scope` has two axes and there is no third: `graphs` names one document's graph per entry — `did:ng:i` or `""` for the whole local dataset, `[]` or `undefined` for no objects at all — and `subjects` filters subject IRIs literally, with no prefix or hierarchy matching. There is no call that lists the documents in a store, and naming a store in `graphs` is not the question you meant: a store's graph holds its containment triples and nothing of the shape you asked for, so it answers empty rather than raising. That is the target's own shape, not a narrowing this package chose — and since `1.0.0-dev.6` nothing is translated on the way: the `Scope` object you write is the object the SDK receives.
+
+**A deposit made while a person is looking at the page arrives while they are looking at it.** For as long as an identity is connected, every inbox it may read is watched and what lands in one is applied as it lands — its own inbox, and the inbox of every document it has opened one on, including a document whose inbox it opens later in the same session. So a `ReadCap` sent with `inbox.share` becomes usable in the recipient's live session with no reload and no call from the application, and a `useShapeQuery` that was empty for want of that `ReadCap` re-reads and publishes the document it now opens. Until 2026-08-17 only the backlog waiting at connection was applied, and a deposit made in front of its recipient converged only when that person reloaded the page.
 
 **The watching is in place by the time `ensureIdentity()` resolves**, whatever else that call made of its own work: a connection that could not restore something still rejects, and the identity it settled is watched all the same. It lasts exactly as long as that identity stays connected — changing identity or clearing it stops it, and whoever connects next is watched in their own right, so nothing of the previous one keeps applying.
 
-**Failing to apply one inbox denies nothing.** It is reported on this package's own log stream (`console.error`, carrying this package's prefix) and never gated by `debugAccessLog` — a diagnostic may be opt-in, a failure may not. The deposit stays in its queue, so the next arrival on that inbox, or the next connection, applies it; the other inboxes were never involved, and nobody is refused anything.
+**A deposit this package applies is delivered ONCE, and a failure is not retried.** It is taken out of its inbox before the arm that handles it runs, so it is gone whether that arm succeeded or not — the same order the target has, where the broker removes a message from the queue as it hands it over and the verifier merely logs what it could not apply. A failure is reported on this package's own log stream (`console.error`, carrying this package's prefix), never gated by `debugAccessLog` — a diagnostic may be opt-in, a failure may not — and then the next deposit is processed. **Do not count on a failed deposit being applied later: there is no retry, no dead-letter queue and no way to ask what was lost.** If an arrival matters to your application, the record you keep of it must be your own. What this buys is the end of the opposite behaviour: an inbox that grew for ever, and one malformed deposit re-reported at every arrival and every connection for the life of the session.
+
+**An unapplicable item and a failed one are not the same event.** A deposit this package cannot make sense of is reported and the next one is processed — one malformed item never holds up the queue behind it. A deposit whose handling could not be COMPLETED is different: the drain STOPS, the inbox is reported, and everything not yet taken out is preserved. Only the deposit in flight is lost. So a failing broker costs one deposit per attempt, not the whole queue, and a drain that stopped is retried by your next `ensureIdentity()`.
+
+**A reference this package cannot read counts as failed, not as absent** — including a document you hold no capability for. That is deliberate and it costs latency: such a deposit stops one drain, and the deposits behind it land on the next connection instead of this one. The alternative was worse and was measured: treating "cannot read it" as "it is not there" destroyed deposits on a transient outage, and destroyed the re-deposits sent to repair them, because a failed capability fetch is remembered for the session. Only a document actually queried, from a synced repo, that still reads empty is called absent. **Consequence to plan for:** a queue holding many references you cannot read drains one per connection.
+
+**`inbox.processInbox` now REJECTS on a broker failure**, where it used to resolve — including when a document a deposit referenced could not be READ. A referenced document that is merely absent is a different case: that is reported and the queue carries on. Awaiting it, handle the rejection: the deposit it was applying at that moment is already consumed, the rest of that inbox is intact, and calling again resumes from the next one. Connection-time draining is unaffected — `ensureIdentity()` reports such a queue and still grants the session, exactly as before.
+
+**Failing to apply one inbox still denies nothing else.** The other inboxes were never involved, the session is not refused, and deposits this package does not claim — your own payloads — are untouched and stay readable through `inbox.read` and `inbox.watch`.
 
 **Any number of subscriptions on one document coexist.** Opening a document, watching an inbox and following a scope no longer silence one another. Until 2026-08-17 a second `subscribeDoc` on a document killed the first, silently — nothing rejected, the first caller's unsubscribe still appeared to work, and what an application saw was a view that stopped re-reading and an inbox that stopped notifying, with no trace anywhere near the cause. A subscriber that joins a document somebody else already opened is handed the initial `State` its own subscription would have pushed it, so joining late is not the same as never firing; and unsubscribing silences that caller and no other, including when it happens from inside a push.
 
@@ -172,7 +294,15 @@ The same rule reaches what a call hands BACK, not only what it looked up first:
 
 **Naming an identity proves nothing about who named it.** Any visitor may type any identifier at the barrier, or arrive on a URL that already carries one, and act as that identity — the wallet and its password are handed out on the barrier itself. The identifier is a choice of space, never a proof: anyone who knows one can act as it, so do not treat `ensureIdentity()`'s answer as an authenticated subject.
 
-**No live read through `useShape` against a deployed broker.** The reactive subscription it opens is dispatched by method name at two hops below this package, and a broker deployed before that name last changed does not recognise it: the read never starts, its set stays empty, its readiness never settles, and one console error is the only trace — indistinguishable from "this scope is empty". The cause is upstream in NextGraph and the remedy is a broker redeployment; nothing in this package can work around it. Use `watchShape` for a reactive read and `readUnion` for a one-shot one — neither goes through that path.
+**The wrapped `ng` is a wrapper, and a wrapper can be wrong.** It forwards every member to the object you gave `configure`, adding two refusals of its own and nothing else. Until `1.0.0-dev.7` it did not forward them at all - every member came back as a promise, and calling one failed with NextGraph's own `<member> is not a function`. The cause, for anyone who met it: the passthrough did `Reflect.get(ng, prop).bind(ng)`, and `@ng-org/web`'s `ng` is ITSELF a proxy whose `get` trap answers every key - `bind` included - with a fresh path-carrying callable, so `bind` never reached `Function.prototype.bind` and what came back was a Promise. It is `Reflect.apply` since `1.0.0-dev.7`, pinned by a unit test that drives a proxy-shaped `ng` rather than the plain objects every other fake in the suite is. **What it cost most was a `shape read`**, and that is the part to read if you hit it: an application that passed this `ng` to `initNg` had the ORM call `ng.orm_start_graph`, which is where the Promise landed, and `@ng-org/orm` catches that to the console - so `orm_start_graph is not a function` on the console, with a `useShapeQuery` that never leaves `isPending`, is THIS defect and not the engine refusing your shape. Pin `1.0.0-dev.7` or later and it is gone. The lesson to keep is that a member of `ng` that misbehaves is worth reporting here rather than worked around: nothing in this package's own code goes through that wrapper, so this surface is the only place such a defect shows.
+
+**A shape query the engine refuses never finishes loading.** Both shape reads — `useShape` and `useShapeQuery` — open a subscription through NextGraph's ORM, and a start the engine refuses is caught there, written to the console and nothing more: the set stays empty, its readiness never settles, and the only trace is that one console line. `useShapeQuery` reports it as a `isPending` that does not end (see the guarantee above); `useShape` answers with the ORM's own two states, which do not carry the distinction - its `isLoading` says whether the initial payload has arrived and has no value for "it never will". The cause is upstream and nothing in this package can work around it, and it is MEASURED in the release this package builds against rather than inferred: in `@ng-org/orm@0.1.2-alpha.21`'s shipped `dist/connector/RdfOrmSubscription.js`, `readyPromise_` is built with `resolve` alone and nothing anywhere rejects it, `resolveReady` is called on one path only (initial data arriving), and `ng.orm_start_graph` is awaited inside a `catch` whose whole body is `console.error(e)`. This was a total outage until the client packages caught up with the deployed broker on 2026-09-21; it is the residual failure mode, not the ordinary case. Since `1.0.0-dev.9` the commonest way in is closed for `useShapeQuery`: a document NAMED in `graphs` is opened and refused before the query is handed over, so an unreachable named document reads `isError` rather than pending for ever. What remains is the start the engine refuses for a document you can perfectly well reach, and everything under `graphs: "did:ng:i"`, where there was no name to check. **So the two faults you can tell apart today are the BARRIER refusing (named document, `isError`, naming the document) and the wiring being absent (`isError` naming the `configure` field); the two you cannot are the engine rejecting your shape and the ORM never having started, which arrive as the same unending `isPending`.** A way to separate those last two has been asked for and is not decided: it would have to be invented here, since there is nothing upstream to mirror and nothing upstream to read it from.
+
+**No object removal call, and no document deletion at all.** There is no `deleteObject` and no `removeDocument` at any level of NextGraph, so there is none here. You remove an object by deleting it from the LIVE set a shape query handed you - the item the set is holding, reached by iterating it, by `.first()` or by `.getBy(graph, subject)`. What that removes is the predicates your SHAPE declares on that subject: triples under a predicate the shape does not name survive, the subject survives, and the document survives. Deleting an item of a `getObjects` result removes nothing, because that result is a clone. `@ng-org/orm@0.1.2-alpha.21` ships a `removeObject(graphNuri, subjectIri)`; it is not published here, because it exists in the package and not in the source this package is verified against, and a symbol whose only evidence is what an npm build happens to export is not something to build a guarantee on.
+
+**A refused ORM write does not always reach you as a failed call.** `insertObject` rejects, and you can await it. A mutation of a live set does not: NextGraph batches those into one call it does not await, so a refusal surfaces as an unhandled rejection in the console rather than as an error at the line that made the change - the write did not happen, and nothing in your code was told. Write into documents you own, and treat a document you merely hold the key for as read-only.
+
+**Nothing of NextGraph's ORM is re-exported as it stands.** `getObjects` and `insertObject` are the two this package offers, wrapped. `RdfOrmSubscription`, `DiscreteOrmSubscription`, `ngSession`, `getRaw`, `watch` and `effect` are NOT published and importing them from `@ng-org/orm` defeats everything above: one wallet hosts every identity here, so an unwrapped read returns every identity's objects and an unwrapped write reaches any document. `RdfOrmSubscription` in particular pools its subscriptions on the shape and the scope alone, with no identity in the key - what makes that safe is the filtering this package does on the way out.
 
 **No revocation.** `inbox.share` cannot be undone.
 
@@ -188,24 +318,123 @@ The same rule reaches what a call hands BACK, not only what it looked up first:
 
 **TWO COPIES OF THIS PACKAGE IN ONE APPLICATION MISBEHAVE SILENTLY, and nothing here can detect it.** What this package remembers it keeps in the package itself, not in any handle you hold: which documents are subscribed and who is listening for them, which identity the session settled on, which documents are open. None of that is shared between two copies. An application that ends up with two therefore runs two of everything — a document subscribed through one copy is invisible to the other, so changes to it simply never arrive; and the identity settled in one is not the identity the other acts as, so the same call writes as one user or the other depending on which copy it reached. Nothing raises, nothing warns, and no call can report it: from every entry point a second copy is indistinguishable from the first, and the symptoms surface far from the cause as missing updates and writes attributed to the wrong person. This is a packaging property, not a behaviour to code around — **declare this package once, as one dependency of the application**, and let your own code and every library built on it resolve to that copy. A library that builds on this package should declare it a *peer* rather than a dependency for exactly this reason, so that the application remains the one place it is named.
 
-**No unfiltered read through `useShape`.** Members that yield items are filtered and mutations pass through; anything else throws. A document reached through that view alone, read nowhere else first, does not appear.
+**No unfiltered read through `useShape`, and no way round it through the object it hands back.** What the call returns is NextGraph's own result, filtered: `data` and `promise` carry only items in documents you hold the key for, `isLoading` passes through, the two page commands run and whatever they hand back is held to the same rule as any other member, and `subscription` - the ORM's own handle, which reads and writes with no capability filter at all - is refused out loud rather than handed on. **Any member this package has not DECIDED is refused, whatever its type** - that is how a member a later `@ng-org/orm` adds is settled before anyone has seen it. It is not decided by type: a COUNT is a plain number that describes the items, and nothing separates it from a page size, so nothing undecided passes. A member the SDK does not carry at all reads `undefined`, since there is nothing behind it. Inside `data`, every member that yields items is filtered, and an ordered result addresses and counts the items you may read: `size`, `length`, an index, `Object.keys`, `in` and `JSON.stringify` all agree, and none of them says how many you may not. **Reading a member's DESCRIPTOR answers exactly what reading the member answers**, which is not a detail: `Object.getOwnPropertyDescriptor` - and the spread, `Object.entries` and console inspection built on it - reads a property without going through the view's own read, so a refused member throws there too rather than handing its value over. That holds for an ACCESSOR as much as for a value: the getter you are handed reads through the view, and its setter is refused. **A mutation reaches the collection underneath, and neither hands back nor acts past what the view shows.** Writing is not broken - your own `add` reaches the document and the reactivity it drives. **All three ask the same question**: `add` THROWS for an object naming a document you hold no key for, and for one naming NO document (there is then nothing that owns it, and it would land in a collection every identity shares - set `@graph` to a document you hold) (it returns the collection whether or not it did anything, so it has no value meaning "that did not happen"), `delete` of an item the view does not show answers `false` - the Set contract's own word for "it was not there", and true of the view - and `clear` empties the view rather than the collection every identity shares. `add` hands back the VIEW rather than the collection, because `Set.prototype.add` returns the collection so calls can chain and chaining onto the unfiltered one gives it away entirely. **Writing to what you are handed is refused** - `data[0] = x`, `delete data[0]`, `data.length = 0`, `Object.defineProperty`, `Object.setPrototypeOf` and `Object.freeze` - on the RESULT OBJECT as much as on `data`, and on this package's own account rather than because the ordered collection upstream happens to refuse some of them too. **Every member `@ng-org/alien-deepsignals` declares non-mutating answers**, computed over the items you may read: the iterator helpers, the array reads (`at`, `slice`, `join`, `indexOf`, `toSorted`, `with`) and the ES2025 set combinators (`union`, `difference`, `isSubsetOf`). The one exception is `copyWithin`, which that list names and which WRITES: it is refused here, and that is STRICTER than NextGraph's own ordered collection, which runs it and destroys an element (its guard is built from the same mislabelled list). A deliberate difference, stated so you do not discover it as a surprise. A document reached through that view alone, read nowhere else first, does not appear.
+
+**`isLoading` does not mean what its name says, and the fault is upstream's.** `@ng-org/orm`'s declaration describes it as "`true` when no data is available yet"; the hook that ships computes it as the subscription's `isReady`, which is the inverse. Both artifacts were read and they disagree. This package forwards the value it is handed rather than correcting it, because a layer that quietly improves the target teaches you a behaviour you would have to unlearn. **Branch on `data === undefined`**, which is unambiguous, and treat `isLoading` as unusable until upstream settles it.
+
+**`getObjects` does not fetch a public store's key for you either**, for the same reason as the two shape reads below: it goes through the same ORM query and spends no round-trip asking. Read the document once by naming it — `docs.sparqlQuery` anchored on it — and it appears.
+
+**`useShape` does not fetch a public store's key for you, and `useShapeQuery` does so only for what you NAME.** A document in a public store gives up its key to whoever asks, but asking is a round-trip: `useShape`'s signature is NextGraph's own and has no await to spend, so a public document you have read nowhere else never appears in it. `useShapeQuery` spent none either until `1.0.0-dev.9`; it now asks once per document named in `graphs`, which is what lets a bare reference to a public document be read through that call. It still asks nothing under `graphs: "did:ng:i"` - the whole local dataset names no document, so there is nobody to ask about. For those two cases, read the document once by naming it - `docs.sparqlQuery` anchored on it, which is the whole of what `readUnion` did for this before it was removed in `1.0.0-dev.8` - and both reads pick it up: the key lands in what you hold, and that is a change both of them re-read on.
 
 **A watch on one inbox that could not be opened does not come back on its own.** Opening it can fail — a broker that does not answer in that moment — and the failure is reported rather than passed over, but what follows is event-driven and this package deliberately never polls. The watch is opened again at the next moment this identity comes to hold something it did not: it creates a document, it opens an inbox on a document, a `ReadCap` reaches it through an inbox still being watched, it reads a public-store document for the first time. A session that does none of those goes on without that inbox — deposits made into it are not applied, nothing raises, and they wait unconsumed for the next connection. The exposed case is the identity that only ever READS, since it produces none of those events, where an identity that goes on creating recovers as a by-product of its own work. Awaiting `ensureIdentity()` again applies what is waiting — it drains every one of this identity's queues before it resolves, and shows no barrier a second time — but the watching itself comes back only on a fresh page.
 
+### Asked for, not decided
+
+Each of these is a standing request from an application, recorded here rather than answered in a message. None is refused on principle; each is an addition to a published surface, so each waits on a decision that is this package's to make. They are listed so that an application knows it is not missing a call it simply failed to find.
+
+**`configure`'s `useShape` is REQUIRED even for an application that never calls it.** `@ng-org/orm` publishes `useShape` only through its react / svelte / vue adapters, so a page with no framework can produce none of them - and the field is not optional in `EventuallyConfig`, so such an application invents a value to satisfy the signature. What it does with that value is unobservable: the injected hook is consulted in exactly one place, inside this package's own `useShape`, so an application that reads through `useShapeQuery` never reaches it. This repository's own frameworkless example passes `useShape: (() => {}) as never` (`examples/notebook/app.ts`) and reads live with `useShapeQuery` beside it; a function that THROWS is equally sound and says more if anything ever does call it. Making the field optional is a change to a published signature, hence this list rather than a fix.
+
+**No published NURI type guard, and no published escaping helpers.** Neither is an oversight. On the guard: every entry takes `NuriLike` and runs its own validation at the door - permissive in, precise out - so a guard would put validation in a caller's hands where the door already does it, and invite the cast the types exist to prevent. On the escaping: `escapeIri` / `escapeLiteral` were published until the surface was narrowed, and they came out under the rule that governs this whole leaf - a symbol with no counterpart at any level of the target is a symbol an application would have to unlearn, and neither `@ng-org/web` nor the ORM exposes an equivalent (the engine escapes ad hoc where it builds SPARQL). The consequence is stated rather than denied: an application composing SPARQL against `docs.sparqlUpdate` carries its own escaper, which is a second implementation of one rule, and the one running there is not the one this package tests.
+
+**No published way to write triples above `docs.sparqlUpdate`.** The write that IS published above the raw primitive is `insertObject(shapeType, object)` - the SDK's own name and signature, which takes a shape-typed object, needs its `@graph`, and composes no SPARQL at all, so it removes the query building, the escaping and the NURI validation from a caller in one move. What it costs is the ORM: it is injected through `configure` (`insertObject`), so a library that wires no `@ng-org/*` of its own cannot reach it, and it writes shape-typed objects rather than arbitrary triples. An "add these triples to this document" entry, taking triples and no shape, is what has been asked for and is not decided.
+
+**No call says WHICH STORE holds a document.** Not the enumeration that `storeRegistry.listMyEntityDocs` was - that was removed in `1.0.0-dev.5` because nothing upstream lists a store's documents - but the narrower question about a document whose `reference` the caller already holds. There is no accessor for it, and the consequence is worth stating plainly: an application cannot verify its own placement, so a document written to the wrong store is undetectable from here until some reader fails to open it.
+
+**No per-deposit outcome, and no count that says a queue has been drained.** `## Guarantees` says a deposit this package applies is consumed whether or not the arm succeeded, that a refusal goes to this package's own log stream, and that there is no way to ask what was lost. The gap an application feels is the one before that: nothing distinguishes "this deposit was examined and discarded" from "this deposit has not been examined yet", so a check that an ineligible deposit produced NO entry cannot be waited for - only timed out, which makes it weaker than its name. Anything observable would close it, a per-deposit outcome or merely a counter that moves when a queue has been drained; neither exists.
+
 ## Change policy
 
 **Semver, and majors are the normal case.** This surface converges on a NextGraph that does not ship yet, so most steps toward the target remove or narrow something — the major number will move often, and that frequency is the honest signal about this package, not an apology. Refusing to version would not slow the churn down; it would only take away the one tool you have for managing it. Pin a version, upgrade deliberately, and re-pull this contract each time.
 
 What each level means here, in this package's own terms:
 
-- **major** — a published symbol is removed (`getSession`, `normalizeId`, `currentUser`, `RegistrySession` and `inbox.materialize` all left this way), **or** an existing call narrows: it now throws where it returned (`listMyEntityDocs` refuses a listing whose documents you could not open; `ensureIdentity` rejects rather than resolve on an incomplete restore), or it reports a state you did not have to handle before (`watchShape` publishing `isError` where it used to publish a synced-empty snapshot). A signature change a caller must react to counts; one that only accepts more than before does not.
+- **major** — a published symbol is removed (`getSession`, `normalizeId`, `currentUser`, `RegistrySession`, `inbox.materialize`, `storeRegistry.listMyEntityDocs`, `resolveScopeGraph`, `resolveWriteGraph`, `readUnion` and `UnionSubject` all left this way), **or** a published symbol is renamed (`watchShape` became `useShapeQuery`), **or** an existing call narrows: it now throws where it returned (`ensureIdentity` rejects rather than resolve on an incomplete restore), it reports a state you did not have to handle before (`useShapeQuery` publishing `isError` where it used to publish a synced-empty snapshot), or what it HANDS BACK changes shape (`useShapeQuery`'s `data` carrying the shape's own objects where it carried property bags). A signature change a caller must react to counts; one that only accepts more than before does not.
 - **minor** — a symbol is added and nothing existing moves (`inbox.readSyncedForDocument` arrived this way).
 - **patch** — a fix that changes neither the published surface nor anything above under `## Guarantees`.
 
-**A tag says where it comes from.** A release cut on `main` carries a **full version** (`1.0.0`), and the three rules above govern what changes between two full versions. Work still on a branch carries a **pre-release** of the version it is heading for (`1.0.0-dev.3`), which sorts *below* that version by construction — so you can pin what exists today while the tag itself tells you the surface has not been released and may still move before it is. Between two pre-releases of the same version nothing is promised: re-pull and read this leaf again. When the branch lands, the full version appears alongside; the pre-release keeps resolving, so no reference you pinned is ever withdrawn from under you.
+**A tag says where it comes from.** A release cut on `main` carries a **full version** (`1.0.0`), and the three rules above govern what changes between two full versions. Work still on a branch carries a **pre-release** of the version it is heading for (`1.0.0-dev.16`), which sorts *below* that version by construction - so you can pin what exists today while the tag itself tells you the surface has not been released and may still move before it is. Between two pre-releases of the same version nothing is promised: re-pull and read this leaf again. When the branch lands, the full version appears alongside; the pre-release keeps resolving, so no reference you pinned is ever withdrawn from under you.
 
-**Tags carry the package name**, because this repository publishes more than one engagement and their versions move independently: `polyfill/v1.0.0-dev.3` is this package, `ng-e2e-helpers/v…` is the other one. A bare `v…` tag would say nothing about which surface it froze the day the two diverge — which is the day one of them takes a major and the other does not.
+**Tags carry the package name**, because this repository publishes more than one engagement and their versions move independently: `polyfill/v1.0.0-dev.16` is this package, `ng-e2e-helpers/v...` is the other one. A bare `v...` tag would say nothing about which surface it froze the day the two diverge - which is the day one of them takes a major and the other does not.
 
-`1.0.0` is a baseline, not a claim of maturity: it is the number that makes your pin mean something. Nothing was released before it, so none of the changes named above is a bump from anything — but the next release very likely is a major. What exists today is `1.0.0-dev.3`, on a branch: pin that string exactly, and anchor your `usage_` leaf's `against:` on it — `against: @ng-eventually/polyfill@1.0.0-dev.3`, the string you pinned, never the version it is heading for. `1.0.0-dev.3` narrows an existing call rather than moving a signature: two payload shapes an application could carry freely are now this package's own, and one it cannot apply is reported — a state you did not have to handle before, which is a **major** by the rules above. It lands inside the pre-release line rather than on a new major number because `1.0.0` has not been cut, so there is nothing yet to break away from.
+**THE TAG IS THE PIN, and here is exactly what exists to pin.** The acquisition channel is agreed per application and carries no version of its own, so the mechanical anchor this engagement offers is the git tag `polyfill/v<version>` on this repository, cut over the commit at which `packages/polyfill/package.json` reads `<version>`. What an application should pin is that tag, and what its `usage_` leaf's `against:` should name is the version string the tag carries - `against: @ng-eventually/polyfill@1.0.0-dev.16`. There is deliberately no promise beyond that: **nothing is published to a registry, nothing is fetchable by version, and no range resolves** - a `*` peer range against a filesystem checkout compiles whatever is checked out at the other end, uncommitted edits included, and no pin on this side can prevent that. **A version and its tag land together**, from `1.0.0-dev.16` onward: the commit that bumps `package.json` is the commit the tag names, and it is pushed with it. That discipline is what makes the sentence above a mechanism rather than an intention. Do not take a version's tag on faith either - `git ls-remote --tags origin 'polyfill/*'` answers in one command - and versions cut before this discipline (`1.0.0-dev.4` through `-dev.14`) have none and will not get one retroactively: for those, the commit at which `package.json` reads the version is the exact pin, which is a real pin and not a workaround. Until the tag for a version is cut, the only pin that names a version exactly is the COMMIT at which package.json reads it - which is what a `usage_` leaf's `against:` line names in parentheses, and it is a real pin, not a workaround. Pin the tag where there is one, the commit where there is not, and say which in the `against:` line either way.
+
+`1.0.0` is a baseline, not a claim of maturity: it is the number that makes your pin mean something. Nothing was released before it, so none of the changes named above is a bump from anything - but the next release very likely is a major. What exists today is `1.0.0-dev.16`, on a branch: pin that string exactly, and anchor your `usage_` leaf's `against:` on it - `against: @ng-eventually/polyfill@1.0.0-dev.16`, the string you pinned, never the version it is heading for.
+
+`1.0.0-dev.16` is a **patch** (2026-10-01): one clause of this section ENUMERATED which versions carried no tag, and pushing a tag falsified it within the hour. It is replaced by the rule it was standing in for - a version and its tag land together from here on - plus the one command that answers the question for any version. An engagement should not carry a fact about its own repository that goes stale while nobody touches this leaf. No surface changed.
+
+`1.0.0-dev.15` is a **patch** (2026-10-01), and it answers a consumer's standing requests. No signature changed, nothing was added or removed from the entry, and no behaviour moved - what moved is what this leaf SAYS, which is the only channel such a request has. `## Surface` gains a complete hand-written shape, with the type argument that types the snapshot, and the statement that `initNg` discards its first argument and substitutes the published `ng` (MEASURED, not inferred). `## Guarantees` now says out loud that an anchored `docs.sparqlQuery` refuses a document it cannot read instead of swallowing it - true since `1.0.0-dev.8`, stated only in that version's release note until now - and names, in one place, which reads reach a document in a public store from nothing but its `reference` (the anchored query, always; `useShapeQuery` on a document NAMED in `graphs`, since `1.0.0-dev.9`) and which do not. `## Non-guarantees` says what the `orm_start_graph is not a function` outage actually was (this package's own `ng` wrapper, fixed in `1.0.0-dev.7`, NOT the engine refusing a shape), pins the upstream swallow to the shipped artifact it was read in, and gains an **Asked for, not decided** list so that a request an application made leaves a trace here rather than in a message. `## Change policy` says which pin exists, and that the tags lag the versions.
+
+`1.0.0-dev.14` is a **patch** (2026-10-01): `ShapeObservable` moved from the entry's SDK-SHAPED section to its POLYFILL-ERA one, and `## Surface` now states that `refetch()` has no recorded counterpart. No signature changed - same name, same shape, still exported from this one entry - so nothing under `## Guarantees` moved. The type was already annotated `kind=invention level=none ref=none` (no upstream observable exists), under a heading that promises a target counterpart for every symbol it lists. It stays exported because applications genuinely write the type down. What the move records is that it is not a framework adapter: it carries the capability filter and the capability-arrival re-publish, both of which exist only because one wallet is shared, so it is deleted when the shared wallet is, as one coupled migration. `ShapeQuery` stays SDK-SHAPED: its record exists and states `{ data, isPending, isSuccess, isError, error }` field for field.
+
+`1.0.0-dev.13` is a **patch**: `NgLike`, `UseShapeLike`, `OrmSubscriptionLike`, `GetObjectsLike` and `InsertObjectLike` moved from the entry's SDK-SHAPED section to its POLYFILL-ERA one, beside `EventuallyConfig`, whose fields they type. No signature changed - same five names, same five shapes, all still exported from this one entry - so nothing under `## Surface` or `## Guarantees` moved, which is the patch/major line this leaf draws itself. What changed is classification only: each was already honestly annotated `kind=invention level=none ref=none` (no target counterpart, at any level), sitting under a heading that promises one for every symbol it lists, because each exists solely to describe what `configure` receives and `configure` was already on the deletion list. An application that already understood it would stop typing these five the day it deletes its `configure()` call was not misled about behaviour; this patch only makes the surface say so, instead of implying the opposite.
+
+`1.0.0-dev.12` is a **major**, and it is one removal: **`Schema` (`@ng-org/shex-orm`) and `DeepSignalSet` (`@ng-org/alien-deepsignals`) are gone from the entry, and nothing replaces them.** Both were re-exported type-only under `## Surface`'s own rule - a type is published only when a published signature uses it - and neither was: `DeepSignalSet` is named only in prose describing what `useShape`'s result carries, never as an actual type anywhere in this package, and `Schema` was named nowhere at all beyond the re-export itself. The same rule already removed `ReadCap` and `InboxScope` from this list; this is that rule catching a second, later recurrence. If your code names either type, it stays DEFINED nowhere in this package to fall back on - name the SDK package directly (`@ng-org/shex-orm`, `@ng-org/alien-deepsignals`) if you need it.
+
+`1.0.0-dev.11` is a **major**, and all of it is one rule: **`useShape` hands back NextGraph's own RESULT OBJECT, filtered - and the filter no longer decides what to hand on by what a member is CALLED.** Nothing is added, renamed or removed from the entry.
+
+- **Read your objects through `data`, not by iterating what the call returned.** `@ng-org/orm`'s React hook returns `{ data, promise, subscription, isLoading, nextPage?, previousPage? }` around the collection, and it has for every release this package builds against. This package went on treating the return AS the collection: `[...result]` and `result.size` threw, and `result.data`, `result.promise` and `result.subscription` each handed back **every identity's items**, with nothing raised anywhere. If you were reading `.data`, you were reading unfiltered. That is the defect this version closes, and it is why this entry is worth reading before upgrading rather than after.
+- **`subscription` is REFUSED where it used to be handed over.** It is the ORM's own `RdfOrmSubscription`, which reads and writes with no capability filter at all and which `## Non-guarantees` has always said this package does not publish. Reading it now throws, naming itself. `data`, `promise`, `isLoading` and the two page commands are what remains, and they are what a caller needs: the SDK's own example destructures `data` and `isLoading` and nothing else.
+- **A member of that object that this package has not DECIDED is refused, whatever its type.** All six of the members `@ng-org/orm` ships are decided; a seventh that a later version adds refuses until someone decides it. Two earlier rules were tried and both let a leak through - "anything that is not a function is harmless", which handed over three members of the current shape, and "a plain scalar cannot reach an item", which handed over any count not spelled `size` or `length`. There is no test on a value's type that separates a count derived from your data from a page size, so the rule is not about types at all: it is that nothing undecided is answered.
+- **The two arguments are the SDK's own types**, where the signature took `unknown` for both. `useShape(shapeType: ShapeType<T>, conf: RdfOrmConfig<T> | string | undefined)`, which is what the surface already said the pair was. A caller passing the SDK's shape and config compiles unchanged; one passing something else now does not, which is why this counts.
+- **`size` and `length` count what you may read, and so does every other way of asking.** An ordered config (`orderBy`) makes the collection an array, which says how many items it holds in four places - `length`, `Object.keys`, `in`, and the descriptor of each index - and only the first was filtered. `data[0]` now names the first item you may read rather than the first the engine returned, and the positions past them do not exist.
+- **A member's DESCRIPTOR answers what reading it answers.** `Object.getOwnPropertyDescriptor(result, "data")` returned the collection UNFILTERED, and `...(result, "subscription")` the handle that reading it refuses: that call does not go through the view's own read. Neither does a spread, `Object.entries`, `JSON.stringify` or a console inspection, so all of them were reading round the filter. They now read through it - which also means `{...result}` and `Object.keys(result)` THROW on `subscription`, where they used to hand it over. **But do not read that as "logging is filtered".** A console is the HOST's, not this package's: `console.log(result)` in Bun and in a browser devtools inspects the object BEHIND the view and prints `data` and `subscription` in full, for every identity, and no interception can prevent it - measured. That is a property of runtime introspection, not a hole a version can close. **Do not log or inspect what a shape read hands you when more than one identity shares the page**; iterate `data` and log what you mean to show.
+- **A mutation no longer hands back the collection, nor acts past the view, and all three ask the same question.** `add` returned the collection - `Set.prototype.add` returns `this` so calls chain, measured on the plain `Set` and on the real `DeepSignalSet` alike - so `view.add(x)` gave every identity's items to a caller whose every way IN was filtered, through the first member the ORM's own example reaches for. It now hands back the view, and it now REFUSES an object naming a document you hold no key for: ungated, it let you plant an object into someone else's document, never see it again, and have the two-way binding commit it there. `delete` removed an item the view declines to confirm the existence of; `clear` emptied the collection every identity shares. **Your own writes still reach the document** - that is the one thing that must not change, and `e2e/orm-live-read.ts` measures it against the deployed broker.
+- **A write to the collection itself is refused.** `data[0] = x`, `delete data[0]` and `data.length = 0` all went through against a collection that allowed them, the last defeating the emptying rule outright; `Object.setPrototypeOf(data, ...)` replaced the real collection's prototype, after which iterating it throws for every identity, and `Object.freeze(data)` made it non-extensible. The view refuses all of them itself now, rather than relying on the ordered collection upstream refusing some of them for it.
+- **The members upstream declares non-mutating answer again.** Eighteen array reads on an ordered result, plus `includes` and the seven set combinators, were throwing for the holder whose data it was - a leak traded for an outage. They are served over the items you may read.
+- **A member this package has not decided is refused, whatever its type.** The rule used to be "a plain scalar cannot reach an item, so it passes", and a COUNT is a plain scalar that describes the items: a member spelled `totalCount` published how many objects exist while you could read one. `size` and `length` were right only because they were computed by name. Nothing undecided passes now - what a later version adds refuses, loudly, naming itself.
+- **The RESULT OBJECT is as write-protected as `data`.** `delete result.data`, `result.isLoading = x`, `Object.setPrototypeOf(result, ...)` and `Object.preventExtensions(result)` all reached the SDK's own object; the last two had been closed on `data` one version earlier and not here.
+- **`add` refuses an object that names no document.** The gate asked the same question a READ asks, where an absent `@graph` means "names no document, nothing to check" - which let an object with no `@graph` into the collection every identity shares. Set `@graph` to a document you hold.
+- **An ordered result yields indices where it used to yield items.** `keys()` handed back items, `entries()` handed back `[item, item]` and `forEach` handed the item as its second argument - the Set contract, applied to an array. No leak, and wrong output on your own data.
+- **Unchanged**: the read still spends no round-trip asking a public store for a key, a document you have read nowhere else still does not appear, and nothing about `useShapeQuery`, `getObjects` or `insertObject` moves.
+
+`1.0.0-dev.10` is a **major**, and all of it is one rule: **"is this document open in this session" now has exactly one answer.** This package kept three records of that fact - a set of live bootstrap subscriptions, a per-document barrier state, and the subscription layer's own listeners - and the first two outlived the third. Only one remains, the state of the document's one real subscription; the other two are gone rather than reconciled, because two records of one fact can disagree and these did. Nothing is added, renamed or removed from the entry.
+
+- **The ARRIVAL half of a named scope's guarantee is delivered in full**, and the two non-guarantees `1.0.0-dev.9` carried against it are withdrawn. A second `configure(...)` no longer leaves a document recorded as synced against a subscription it tore down - that one DID publish an empty or stale success, and now stays pending until the document is heard from. A subscription the broker refuses no longer leaves the document recorded as open, in the one case where that was unbounded: when the refusal arrives after the subscription layer has been torn down from under it, nothing was ever told, and the document could not be opened again for the rest of the session. In both, the document is now re-opened and the read answers once it has actually been heard from.
+- **What a caller sees change, and the two situations differ - said per situation rather than lumped together.** After a second `configure(...)` a named scope publishes `isPending` where it published `isSuccess`, and that is why this is counted a **major** on the conservative reading: `isPending` is a state this call already reports and this surface already requires you to handle, so no new state arrives at the caller, but an interface branching on `isSuccess` is handed a different value. When the broker refuses late, the read was already withheld - it is the RECOVERY that changes: the retry now subscribes again instead of being blocked for the rest of the session, so `refetch()` is an exit where it was not. **Calling `configure` once, at start-up, is still what the deployment requirements ask for**; this makes a second call recoverable rather than supported.
+- **Unchanged, and each is still a success**: a named document you can read that holds nothing of the shape, `graphs: []`, and `graphs: "did:ng:i"` or `""`. Turning a genuine emptiness into a failure would only move the lie, and nothing here does.
+
+`1.0.0-dev.9` is a **major**, and all of it is one rule: **a read that could not reach its document now FAILS, where it used to answer as though the document were empty.** Nothing is added, nothing is renamed, nothing is removed from the entry - three existing calls narrow.
+
+- **`useShapeQuery` publishes `isError` for a document you NAME and cannot read.** Until this version a document named in `scope.graphs` was handed straight to the engine; whatever came back was filtered per document by what you hold, and a document you hold no key for was emptied out of the result. The snapshot was `isSuccess` with `data: []` - indistinguishable, byte for byte, from the scope genuinely holding nothing. It now asks the public store for the key, refuses out loud if there is none to be had, and crosses the sync barrier first, so the same read answers `isError`. **Handle `isError` on a named scope**; an interface that only branched on `isPending` / `isSuccess` will show its success state with nothing in it. Naming several documents fails as a whole when one of them fails.
+- **A named document that has not SYNCED keeps the read pending**, where it used to publish the same empty success. Reaching a document and hearing back from it are two questions, and only the first was being asked. An interface must therefore expect a named scope to sit in its loading state while a document it named is not answering, rather than reading an empty success as "nothing there". The same applies after an in-page re-login, which returns a named scope to pending until its documents are confirmed under the new session - see `## Guarantees`. Complete since `1.0.0-dev.10`; in `1.0.0-dev.9` it held only within one ordinary session, and the two situations that broke it were carried as non-guarantees.
+- **A named scope now costs round-trips it did not cost before**, once per named document per session: the key fetch, and the subscribe that syncs the repo. The opens run together, so several named documents cost the slowest wait rather than the sum. `graphs: "did:ng:i"` is unchanged and spends nothing.
+- **A refused named scope RECOVERS on its own.** Reachability is re-read on every publication rather than remembered, and a scope whose barrier failed is attempted again when the keyring moves - including when the move happened while the read was still deciding. Without that a refusal would be terminal, and trading a silent empty answer for a permanently stuck error would have been no improvement at all. Expect to see `isError` briefly on a page that subscribes before its keys are restored. There is no polling: in a session whose keyring never moves again, `refetch()` is the recovery, as it is for every other failure this call reports.
+- **`inbox.postToDocument`, `inbox.readForDocument` and `inbox.readSyncedForDocument` reject where they used to report "no inbox".** Resolving a document's inbox address reads that document, and when the read could not happen - the broker could not answer for it, or its public store could not be asked for the key - all three used to render the breakdown as the document's owner having opened nothing: a refusal on the deposit side, an empty list on the read side. They now reject. A document that genuinely has no inbox is unchanged, and still answers exactly as before.
+- **Nothing that was already an ANSWER moves.** An empty document is a success holding zero objects, `graphs: []` is a success holding none, a document in a public store that exposes no key is a plain "no", and a document with no inbox answers `[]`. The whole change is that a *failure* stopped borrowing those shapes.
+- **Why this direction, and not a richer set of outcomes.** The step that collapsed the two was this package's own emulation of a public store serving its key; NextGraph has no counterpart for it, because upstream nothing consults a capability on the read path at all. So there is no signature to mirror, and the alignment falls to the engine's own observable: an anchored query on a repo the verifier does not hold answers `NgError::RepoNotFound`, a rejected promise - **a read rejects, or it does not**. Inventing a third outcome for a caller to branch on would have been a vocabulary the target will never grow.
+
+`1.0.0-dev.8` is a **major**, and it is one removal: **`readUnion` and `UnionSubject` are gone from this surface, and nothing replaces them.**
+
+- **What they were.** `readUnion(docs)` issued one anchored `docs.sparqlQuery` per document, in parallel, and added four policies of its own on top: it swallowed a document it could not read into an empty answer, it dropped a document whose key you do not hold instead of refusing it, it grouped the rows into per-(document, subject) property bags, and it removed the reserved-prefix registers from the result. Nothing at any level of NextGraph answers that composition. Its own provenance annotation cited `sparql_query`, which is a citation a reader checks, finds correct, and moves on from - while the claim attached to it was false. **A composition cannot be aligned on a single function**, and that is the rule this removal serves.
+- **What to call instead.** `docs.sparqlQuery(sessionId, "SELECT ?s ?p ?o WHERE { ?s ?p ?o }", undefined, doc)` - the primitive `readUnion` was built on, published beside it all along. It is the same anchored query and the same public-store key fetch, so **a bare `reference` is still enough to read a document in a public store**: nothing about that property moves. Reading several documents is this call once per document.
+- **What comes back to you, and it is not a detail.** Three of the four policies were the batch's, and they are now yours: a read that FAILS rejects instead of reading as an empty document, so whether one unreadable document ends your loop is your decision at your call site; a document you hold no key for is REFUSED out loud instead of being dropped from a result; and the rows are rows - grouping them into objects is yours, or use `getObjects` / `useShapeQuery`, which return the SDK's own typed objects. The fourth is in `## Guarantees`: subjects under `urn:ng-eventually:` are no longer filtered out for you.
+- **Why the losses are alignment rather than regression.** Upstream, an anchored query on a repo the verifier does not hold REJECTS (`resolve_target_for_sparql` -> `NgError::RepoNotFound`), which reaches JavaScript as a rejected promise. A "skip this one and carry on" policy is something the target does not have and will not grow, so a caller that learned it would have had to unlearn it. The one thing that genuinely disappears is the convenience, and it is three lines at your call site.
+
+`1.0.0-dev.7` is a **major**, and what makes it one is not the two calls it adds but the rule it starts enforcing. Symbol by symbol:
+
+- **`getObjects` and `insertObject` are published**, at NextGraph's own names, parameters and returns, wrapping the SDK's. That part is a minor on its own: nothing existing moves. Import them from this package rather than from `@ng-org/orm` - which is the point, since the unwrapped ones bypass the capability filter and the shared-wallet identity boundary entirely. Both are injected through `configure` (`getObjects`, `insertObject`), like the shape query beside them.
+- **An ORM write into a document you do not own is now refused**, where it used to succeed. This is the major. It applies to `insertObject` and to every mutation of a live set a shape query handed you, because both leave by a door that had no guard on it. The guarantee itself did not move - *only a document's owner writes to it* has been in this contract from the start - but the implementation only enforced it on `docs.sparqlUpdate`. Code that relied on writing through the ORM into somebody else's document was relying on a hole. Note that a live-set mutation is refused WITHOUT your call failing: see the non-guarantee above.
+- **`initNg` must be this package's**, and it now substitutes the `ng` it hands NextGraph's ORM. An application that calls `@ng-org/orm`'s `initNg` directly still works and is still unguarded - which is exactly the state being left behind, so call this package's.
+- **`RdfOrmConfig` joins the published types**, because `getObjects`'s signature names it. It is re-exported from the SDK's `/all` subpath, which is where the SDK puts it.
+- **`ng` works.** Until this version the published `ng` answered every one of its members with a promise instead of the function, so `ng.<anything>(...)` failed with NextGraph's own `<member> is not a function`. If you passed it anywhere - and the surface tells you to use it instead of the one you gave `configure` - that is what you were hitting, including a `useShapeQuery` that never left `isPending` because NextGraph swallows the failure it gets from `orm_start_graph`. Nothing about the call changes; it simply answers now.
+
+`1.0.0-dev.6` is a **major**, and all of it is one change: `useShapeQuery` reads through NextGraph's OWN shape query instead of a read this package built. Nothing was renamed and nothing was removed from the entry, but three things move under a caller:
+
+- **`data` items are the shape's objects, not property bags.** `ShapeQuery<T>`'s `T` is now the shape's type: each item carries `@id`, `@graph` and one field per predicate the shape DECLARES, under that predicate's readable name. `note.props["urn:notebook:title"]?.[0]` becomes `note.title`, and `note.graph` becomes `note["@graph"]`. **A predicate your shape does not name is not projected**, so a shape written only to match — an `rdf:type` constraint and nothing else — now comes back with no fields at all: declare the ones you read. (`readUnion` was unchanged by this version, and was removed in `1.0.0-dev.8`.)
+- **`shapeType` is typed.** It was `unknown`; it is `ShapeType<T>` (the SDK's own, re-exported here), so the snapshot is typed without a cast — and a hand-written shape object must now satisfy that type, which means `readablePredicate`, `minCardinality` and `maxCardinality` on every predicate.
+- **`configure` takes one more thing.** `ormSubscription: RdfOrmSubscription.getOrCreate`, plus `initNg` and a call to this package's `initNg(ng, session)` once the session has arrived. Optional in the type, required in practice for this read: without it `useShapeQuery` publishes `isError` naming the field.
+
+And one guarantee narrows, which is the part to read twice: a shape query the engine REFUSES no longer reaches `isError` — it stays `isPending` for ever, because NextGraph swallows that failure. See `## Guarantees`.
+
+`1.0.0-dev.5` before it was the largest **major** of the line: it renames one call, changes the parameter of two, and removes three. Every change is one step toward the surface NextGraph will ship, so none of them is reversible by asking. Symbol by symbol, with what replaces it:
+
+- **`watchShape(shapeType, scope)` → `useShapeQuery(shapeType, scope)`.** The name is the target's own; `watchShape` appears nowhere in NextGraph and spends a verb the ORM already uses for signal observation. Everything you read back is unchanged — the same `ShapeObservable`, the same `ShapeQuery` snapshot, the same three states.
+- **`Scope` is no longer `"public" | "protected" | "private"`.** The published `Scope` is now the SDK's own, `{ graphs?: string[] | string; subjects?: string[] }`, re-exported from `@ng-org/orm`, and it is what `useShapeQuery` takes. `watchShape(Shape, "protected")` becomes `useShapeQuery(Shape, { graphs: "did:ng:i" })` for everything you hold, or `useShapeQuery(Shape, { graphs: [doc1, doc2] })` for named documents. **There is no translation for "the documents in my protected store"**: that question is not expressible against the target, and the three strings were this package's own way of asking it.
+- **`storeRegistry.createEntityDoc(scope)` → `createEntityDoc(store?)`.** `store` is a reference, not a word: `await storeRegistry.protectedStore()`, `publicStore()` or `privateStore()`. Omitting it places the document in the private store, exactly as `doc_create` does when no store is given. `createEntityDoc("protected")` becomes `createEntityDoc(await storeRegistry.protectedStore())`.
+- **`storeRegistry.listMyEntityDocs(scope)` is REMOVED, with no replacement call.** There is no `doc_list` upstream, at any level. What replaces it is the read itself: ask `useShapeQuery` for a shape over `{ graphs: "did:ng:i" }` and what you hold of that shape comes back. An application that listed its documents in order to read them was doing in two steps what the read does in one — but it must now write something the shape can match, typically an `rdf:type` triple, since nothing indexes a document for you.
+- **`storeRegistry.resolveScopeGraph(scope)` is REMOVED.** It handed out a value whose stated use was a read scope, and a store's graph holds its containment triples and nothing else — so pointing a shape query at it matches nothing and says so with an empty set, silently. If you were using it as a write anchor, use the store's reference from the accessor of the same name.
+- **`storeRegistry.resolveWriteGraph(scope)` is REMOVED.** It returned the very reference `privateStore()` / `protectedStore()` / `publicStore()` return. One value, one published name.
+
+`1.0.0-dev.4` before it narrowed a **guarantee** and added a rejection: a deposit this package applies is now consumed, so a failure that used to be retried at the next arrival or the next connection is now final and reported once; and `inbox.processInbox` rejects on a broker failure where it used to resolve. An application that leaned on the retry — however implicitly — has to keep its own record instead, and one that awaited `processInbox` without a `catch` now has a rejection to handle. `1.0.0-dev.3` before that narrowed an existing call the same way: two payload shapes an application could carry freely became this package's own, and one it cannot apply is reported. All of them land inside the pre-release line rather than on a new major number because `1.0.0` has not been cut, so there is nothing yet to break away from.
 
 There is no changelog file and no deprecation window: **the sections above are the release note.** A removal or a narrowing lands in `## Surface` and `## Guarantees` in the same version that ships it, and a symbol is never left published-but-dead as a courtesy. Diff this leaf between two pulls — `## Guarantees` and `## Non-guarantees` before `## Surface`, because that is where a narrowing shows up first.

.project/concepts/app-contract/polyfill-surface/usage_ng-helpers.md

@@ -0,0 +1,94 @@
+---
+type: usage
+summary: The polyfill entries the indexing layer and its end-to-end application stand on - placement by store reference, one anchored write, the deposit that becomes an entry, the one-shot read, and one shape query
+against: "@ng-eventually/polyfill@1.0.0-dev.6 (pulled 77e78ec81de81959e90e40da8d302e274b025c51)"
+pulled_from: git@gitea.reconnexion.apps.gueraud.net:Sylvain/ng-helpers.git/.project/concepts/indexing/polyfill-surface/usage_ng-helpers.md
+pulled_version: 71667ca14eae86bf8a327fae09383a4d4e7541dd
+pulled_at: 2026-10-01
+---
+
+# usage_ng-helpers - `@ng-helpers/indexing` on `polyfill-surface`
+
+The consumer is the indexing layer: an index is an ordinary public document that declares a field, anyone may hand it a reference by depositing into it, and its entries appear because the layer below applies that deposit. NextGraph has no indexing concept, so nothing of what a deposit MEANS belongs upstream - the polyfill's inbox stays generic and carries an opaque payload.
+
+Two callers here, and they consume different things. The **library** (`src/`) reaches the polyfill from exactly ONE file, `src/polyfill-adapter.ts`: everything else is written against an internal port, so a change to the engagement breaks that one file and nothing else. The **end-to-end application** (`e2e/indexing-app.ts`, `e2e/bridge.ts`) is written the way a consumer of `@ng-helpers/indexing` writes one, and consumes the polyfill directly for its bootstrap and for reading - which is the point: if something is awkward there, it is awkward for every application.
+
+## Consumed surface
+
+**Library - placement, write, inbox** (`src/polyfill-adapter.ts`)
+
+- `storeRegistry.publicStore()` then `storeRegistry.createEntityDoc(store)` - the index document, in its creator's public store. A store is named by the REFERENCE the accessor hands back, and the argument is never omitted: omitting it places the document in the private store, and an index nobody but its owner can open is not an index. This is the call that was still passing the withdrawn string `"public"` against the previous version.
+- `storeRegistry.openDocumentInbox(doc)` - called once, at creation, under the owner. The address it returns is deliberately dropped.
+- `docs.sparqlUpdate(sessionId, update, anchor)` - the only write this package makes, always an anchored `INSERT DATA` of one triple.
+- `inbox.postToDocument(doc, { payload })` - the deposit, where the payload IS a bare `did:ng:` reference.
+- Types `Nuri` and `NuriLike`, type-only, so they are literally the published ones rather than a copy that can drift.
+
+**End-to-end application - bootstrap, reading, and one observation** (`e2e/indexing-app.ts`, `e2e/bridge.ts`)
+
+- `configure({ ng, useShape, ormSubscription, init, initNg, sharedWallet })`, this package's own `init(callback, true, [])` for the `session_id` its callback delivers, this package's `initNg(ng, session)` once that session has arrived, and `ensureIdentity()`. `ormSubscription` is `RdfOrmSubscription.getOrCreate` and the injected `initNg` is the SDK's, both from `@ng-org/orm@0.1.2-alpha.21`, passed as they stand; the `ng` and `init` handed to `configure` are `@ng-org/web@0.1.2-alpha.14`'s.
+- The package's own published `ng`, as the argument `initNg` is given.
+- `readUnion([doc])` and the type `UnionSubject` - how an index is read, and how a referenced document is read. See `## Needs`.
+- `docs.sparqlQuery(sessionId, query, undefined, anchor)` - an anchored SELECT, as the second of the two ways anyone reads an index.
+- `useShapeQuery(shape, { graphs: "did:ng:i" })`, `ShapeObservable`'s three members (`getSnapshot`, `subscribe`, `refetch`), the three states of `ShapeQuery` and its `data`, and the types `Scope` and `ShapeType`. ONE use, and it is an observation rather than a business read: after a failure is injected into the inbox step of `create`, this is how the suite finds the document that was left behind. The shape is hand-written and names one predicate - the descriptor `create` writes - which is what makes an index document matchable at all.
+
+**Not consumed**, and safely evolvable as far as this repository is concerned: `useShape` (a function that REFUSES is handed to `configure`, and nothing calls it - see `## Frictions`), `subscribeDoc` / `subscribeDocs`, `docs.docCreate`, `storeRegistry.privateStore` / `protectedStore`, `inbox.share` / `post` / `read` / `readForDocument` / `readSynced` / `readSyncedForDocument` / `processInbox` / `watch`, and the types `Deposit` and `PrincipalId`.
+
+## Constraints
+
+**A bare reference deposited into a document's inbox becomes an entry on that document.** This is the single guarantee the whole layer rests on: `add` deposits a `did:ng:` reference and nothing else, precisely because that shape is this engagement's own and it acts on it. Nothing of indexing's meaning travels in the payload, and there is no second shape to fall back on.
+
+**An index is created in its creator's PUBLIC store, named by that store's reference.** The public store is what serves an index's read key to whoever asks, and that is the whole reason a stranger can reach one from its reference alone. The unit suite pins both halves - where the document landed, and that the store travelled as the reference an accessor produced - so the private placement that omitting the argument would give is red rather than silent.
+
+**One handle is one identity.** The session is one user's and no call takes an identifier, so an `Indexing` handle is one person's. Two users mean two handles - which is also what keeps the multi-actor end-to-end journeys honest: a depositor obtains the index reference the way an application does.
+
+**`sessionId` is relayed, never converted.** It is carried at the engagement's own `string | number` and handed back untouched.
+
+**The ORM is the APPLICATION's to wire, and the library never touches it.** `src/` performs no shape read of any kind, so a consumer of `@ng-helpers/indexing` that wants none wires nothing and declares no `@ng-org/*` dependency of its own. Only the end-to-end application here wires it, and only because one observation has no other door.
+
+**A reactive read's load state is read before its data, and a pending read is bounded.** An empty `data` means "this scope holds nothing" only under `isSuccess`; under anything else it means nobody answered, and the two never reach a check as one value - the state travels out to the report beside the result. The bound exists because a shape query the engine refuses never finishes loading, so without one that failure would be a hang rather than an observation.
+
+**The write is add-only, and structurally so.** There is no delete builder anywhere in this package and the only statement it can compose is an anchored `INSERT DATA`; the unit suite executes that SPARQL against an engine that refuses anything else, so a removal is unrunnable rather than merely absent. What this asks of the engagement is exactly one write primitive and no more.
+
+**The document is named once, as the anchor.** The statement carries no `GRAPH <...>` wrapper, because the anchor already scopes the write to that repo's default graph. Naming it twice would be two chances to disagree.
+
+**A document's inbox is opened from ONE place** - `create`, under the owner, at the moment the document is created - and no address is held anywhere above that call. The non-guarantee about `openDocumentInbox` not coalescing across pages is therefore respected by construction rather than by care.
+
+**This package declares the polyfill a PEER dependency**, so the application above remains the one place it is named. The single-copy rule is the one packaging mistake the surface cannot protect anyone from, and a library that declared it a direct dependency would be manufacturing exactly that.
+
+**Every NURI is validated before it reaches a query or a deposit**, because no type guard is published (see `## Frictions`).
+
+**This layer stays out of `urn:ng-eventually:` entirely.** Its predicates are `urn:ng-helpers:` and the subjects it writes are always `did:ng:` references, so nothing it writes falls under the reserved prefix and nothing it writes is dropped on read.
+
+**An empty read is never concluded from.** Where the end-to-end suite reads an index it polls to a bound and reports what the index held instead, rather than reading once and calling an empty answer an answer.
+
+**The identity `ensureIdentity()` returns is opaque here** - checked for non-emptiness, carried, printed in a run report, never parsed or rendered as a name.
+
+## Frictions
+
+**The acquisition channel carries no version, so the Change policy has nothing to bite on.** The engagement asks for a pinned version and says the channel by which the source reaches an application is agreed with that application; nothing has been agreed here. This repository reaches the package as a filesystem link and declares the peer range `*`, so what it compiles against is whatever is checked out at the other end - uncommitted edits included. That is not theoretical: while this declaration was being rewritten the linked tree moved from `1.0.0-dev.6` to work heading for `1.0.0-dev.7`, and the end-to-end suite's result moved with it, mid-session, with no pin able to prevent it. The `against:` line above pins the last COMMIT, which is the only pin that exists on this side. A tag-addressable, fetchable source would turn the whole semver discipline from a description into a mechanism.
+
+**At the pinned version the one shape read here never starts, and the engagement says it cannot be told apart from a shape written wrong.** `useShapeQuery` is wired exactly as the Deployment requirements describe - `ormSubscription: RdfOrmSubscription.getOrCreate`, the SDK's `initNg` injected, this package's `initNg(ng, session)` called once the session has arrived - and against the broker the ORM's call into `ng` fails with `orm_start_graph is not a function` on the console. Per `## Non-guarantees` NextGraph swallows that and the read stays `isPending` for ever, so the observation it feeds reports `observed=pending` and the two end-to-end checks that rest on it fail. Reproduced on three consecutive runs, 2026-09-21. Measured through the published surface: the SDK's own `ng` answers that member, and the `ng` an application hands `initNg` makes no difference because the call substitutes one of its own. Nothing on this side can work around it - the withdrawn `listMyEntityDocs` had no other replacement - so this is carried as a failing check rather than hidden behind a looser one.
+
+**`configure` requires `useShape`, and a frameworkless application has nothing to give it.** `@ng-org/orm` publishes `useShape` only through its react / svelte / vue adapters; a page with no framework can produce none of them. The field is not optional in `EventuallyConfig`, so this application hands over a function that THROWS if anything ever calls it - better than the `() => undefined` it carried before, which a caller could not tell from an empty read-filtered view, but still a value invented to satisfy a signature. Making the field optional, or saying in the engagement what a frameworkless application should pass, removes it.
+
+**A shape has to be hand-written, and the engagement carries no example.** `ShapeType` demands `readablePredicate`, `minCardinality` and `maxCardinality` on every predicate, plus a `schema` keyed by the shape's own IRI and a type carrying `@id` and `@graph`. The Change policy names three of those requirements in one clause and shows none of the shape. What was written here was assembled from the SDK's own type declarations - a read this contract exists to make unnecessary. Three lines of example in `## Surface` would cover every application that has no generated shape to hand.
+
+**`initNg`'s first argument has no effect.** The Deployment requirements say to call `initNg(ng, session)`, and `## Surface` says of the published `ng` that it is the one to call instead of the one `configure` was given - so an application has a choice to make. Measured through the published surface: the call substitutes an `ng` of its own and the argument is discarded, so both readings behave identically and neither can be told apart from the outside. Saying so - or dropping the parameter - saves the next application the experiment.
+
+**No published NURI type guard.** `## Guarantees` says so plainly, so this layer carries its own. It is a guess at what the engagement considers a valid `Nuri`, and a wrong guess either rejects a legitimate reference or lets one through into a query.
+
+**No published escaping helpers.** The engagement lists no `escapeIri` / `escapeLiteral`, and this package composes SPARQL against `docs.sparqlUpdate` - so it carries its own escaping rather than reach into the provider. That is a security-relevant duplication: two implementations of one rule, and the one running here is not the one the provider tests.
+
+**No published way to write triples above the raw SPARQL primitive.** `docs.sparqlUpdate` is the level this layer had to align on, which is where the two frictions above come from. An "add these triples to this document" entry would delete the query composition, the escaping and the NURI validation from this package in a single move.
+
+**`readUnion` has no stated behaviour for a document it cannot read.** `## Guarantees` says what it returns for a document it can, and it says elsewhere that a rejection means "unknown, never absent" - but not whether an unreadable document inside the list comes back as a rejection or is swallowed into the result. The worst is assumed (swallowed, therefore indistinguishable from empty) and every read path here is written defensively around that guess. One sentence in `## Guarantees` would replace it.
+
+## Needs
+
+**A one-shot read of a named document's subjects - `readUnion` as it stands, or something that answers the same question for a document whose key the reader does not yet hold.** The ORM is wired here now, so `useShapeQuery` is reachable and the earlier objection - that this application wires none - has fallen. It still does not replace this read, and the reason is the engagement's own: **neither shape read fetches a public store's key**, so a public document read nowhere else appears in neither, and the way to make it appear is to read it once by naming it, with `readUnion` or an anchored SELECT. An index IS a public document and its central case is a STRANGER reaching it from its reference alone - precisely the case no shape read serves. Three smaller costs sit on top: a shape read is reactive and three-stated where a page-load read is one-shot; it projects only the predicates a shape declares, so an index's entries and the index's own declaration take two shapes where `readUnion([index])` takes one call; and it pushes the ORM, a hand-written shape and the `useShape` friction above onto every consumer of `@ng-helpers/indexing`, which today needs none of them. This package publishes to its own consumers that an index is an ordinary document, read with `readUnion([index])` and recognised by two IRIs; withdrawing it leaves the anchored SELECT as the only fallback, which puts every reader of an index back on raw SPARQL - where three of the frictions above come from.
+
+**A way to tell which store holds a document whose reference is already held.** The withdrawn `listMyEntityDocs` had one use here, and the shape read now covers most of it: after a failure is injected into the inbox step of `create`, the suite finds the document left behind by asking for every index document this identity HOLDS and diffing. What that cannot say is WHERE it sits, so the check it feeds now establishes that a document survived, and no longer that it survived in the public store. This is not the question the Change policy declined: it enumerates nothing, it names a document the caller already holds, and a store's graph is said to hold exactly the containment triples that would answer it. As it stands an application cannot verify its own placement at all - a document written to the wrong store is undetectable until some reader fails to open it.
+
+**A way to tell a shape the ENGINE refused from a shape the application wrote wrong.** `## Non-guarantees` says a refused shape query is caught upstream, written to the console and nothing more: the set stays empty and its readiness never settles. From an application both faults look identical - an `isPending` that does not end - and the console line is not something a page can act on. That is the whole diagnostic surface for the one thing an application must hand-write itself (see `## Frictions`), so the first shape anybody writes has no way of telling "the engine would not take this" from "the ORM was never started". Anything that separates them - a refusal that reaches `isError`, or a state that says "never opened" - turns a silent hang into something an interface can report.
+
+**A way to tell "examined and discarded" from "not examined yet".** A deposit this engagement applies is consumed whether or not it produced an entry, and a refusal goes to the provider's own log stream - nothing an application can observe, and by the engagement's own words there is no way to ask what was lost. The cost here is concrete: the journey that checks that an object carrying nothing for an index's field is NOT indexed cannot be waited for, because no reading distinguishes "the deposit was examined and skipped" from "the deposit has not been examined yet" - and this repository's suite says so in its own header rather than hiding it, declaring that check weaker than its name. Anything observable from the application - a per-deposit outcome, or merely a count that moves when a queue has been drained - would make it a real one. This layer holds nothing of its own on purpose: an index only ever grows, and the reference is the whole of what is deposited.

.project/concepts/e2e-harness/_overview.md

@@ -17,7 +17,7 @@ vocabulary:
 
 # e2e-harness — the suites, and what they can and cannot tell you
 
-Three suites drive real browsers against the real broker and the real wallet application. They are the only place the emulation meets what it emulates, so a green unit suite says nothing about them.
+Four runners drive real browsers against the real broker and the real wallet application — three suites that judge this package, and one measurement that judges the deployment. They are the only place the emulation meets what it emulates, so a green unit suite says nothing about them.
 
 They are also expensive and, on a machine whose network moves, unreliable in ways that look exactly like product defects. Most of what this concept holds exists so an agent does not spend hours diagnosing a product bug that is a transport failure — or, worse, trust a green run that measured nothing.
 

.project/concepts/e2e-harness/knowledge_what-each-suite-judges.md

@@ -11,7 +11,9 @@ summary: Which suite answers which question, what a batch costs, and why two run
 
 **The reactivity suite** isolates document subscription.
 
-A unit suite cannot replace any of them, and none of them replaces the unit suite: they are slow, they depend on live external services, and they cannot enumerate a case space.
+**The ORM live-read measurement** asks one question of the deployment rather than of this package: does a live `useShape` read actually start. It is the only runner that imports `@ng-org/orm`, which the polyfill declares an OPTIONAL PEER - so an application that does not name the ORM gets nothing, and a checkout without the ORM must still be able to run the other three, which is why this runner stands apart from the polyfill suite instead of inside it. It exited non-zero for as long as the deployed broker and the published client packages disagreed on `orm_start_graph`; since the packages caught up on 2026-09-21 it is GREEN, and a red run now means they have drifted apart again. Do not read the optional peer as "this checkout has no ORM": `packages/polyfill` also lists it in its devDependencies, so `pnpm install` here fetches it and the runner's bundle builds with no extra step - measured 2026-09-24 by installing from an empty `node_modules`. The optional peer governs what a CONSUMER receives, not what this repository installs.
+
+A unit suite cannot replace any of the first three, and none of them replaces the unit suite: they are slow, they depend on live external services, and they cannot enumerate a case space.
 
 ## What a batch costs, and why
 

.project/concepts/e2e-harness/ng-e2e-helpers/usage_ng-helpers.md

@@ -0,0 +1,55 @@
+---
+type: usage
+summary: What this repository's end-to-end suite calls from ng-e2e-helpers - bounds, profiles, the minted wallet, the broker crossing, and the run report
+against: "ng-e2e-helpers@1.0.0-dev.2 (pulled d44063961682f84d4b804e5b349cd0a791dd9550)"
+pulled_from: git@gitea.reconnexion.apps.gueraud.net:Sylvain/ng-helpers.git/.project/concepts/indexing/ng-e2e-helpers/usage_ng-helpers.md
+pulled_version: 71667ca14eae86bf8a327fae09383a4d4e7541dd
+pulled_at: 2026-10-01
+---
+
+# usage_ng-helpers - `@ng-helpers/indexing`'s end-to-end suite on `ng-e2e-helpers`
+
+The consumer is this repository's end-to-end suite: one run that builds a small indexing application, serves it, gets two real people into it through the real broker, and drives depositing and curating between them.
+
+Everything generic - the wallet lifecycle, the broker crossing, per-run profiles, bounds, the report shape, the recognition of the known browser failure modes - comes from the engagement and is **used, never reimplemented**. What is specific to this repository is the page that carries the application, the name its runs mint, and the journeys themselves. Two files touch the engagement: `e2e/harness-page.ts` and `e2e/run.ts`.
+
+## Consumed surface
+
+- **Bounds** - `within`, `armSuiteDeadline`, `closeQuietly`, `firstLine`.
+- **Measurement** - `measured`.
+- **Browser and profiles** - `launchWatchedContext`, `closeContext`, `newPage`, and the type `RunProfile`.
+- **Wallet** - `mintWalletProfile` and the type `WalletCredentials`. Each run mints its own.
+- **Broker crossing** - `setupBrokerPage`.
+- **Serving** - `serveOnEphemeralPort`, for the application bundle.
+- **Known failure modes** - `browserTrouble`, wired as the suite's `diagnose`.
+- **Report** - `declareSuite` and the type `Prerequisite`; on the handle it returns, all three of `check`, `journey` and `finish`. The `JourneyDeclaration`, `JourneySpec` and `SuiteOptions` shapes are consumed structurally, through those calls, rather than imported.
+- **Constants** - `BROKER_ROUND_TRIP_MS`, `NEW_PAGE_MS`, each used as a term of a bound this suite composes.
+- **Browser types** - `BrowserContext`, `Page` and `Frame`, obtained by DERIVING them from the helpers that return them (`Awaited<ReturnType<typeof ...>>`) rather than by importing them. See `## Constraints`.
+
+**Not consumed**, and safely evolvable as far as this suite is concerned: `completeBrokerLogin`, `brokerRedirectFor`, `BROKER_SCREENS` and the screen inventory types, `WALLET_APP` / `WALLET_CREATION` / `WALLET_IMPORT`, `emptyProfileContext`, `importWalletFile`, `exportWalletBytes` / `exportWalletFile`, `mintWalletBytes`, `mintWalletProfileKeepingContext`, `createWalletInContext`, `newRunProfile`, `isAlive`, `browserLost`, `lossDeclared`, `enclosingBound`, `frameTrouble`, `record`, `timingsWanted`, `printTimings`, `DEFAULT_WALLET_NAME`, the exported error classes `DeadlineExceeded` and `BrowserGone`, the `ng-mint-wallet` executable, and the remaining `*_MS` constants.
+
+## Constraints
+
+**The browser types are DERIVED from the helpers, never imported from `playwright` here.** The engagement declares Playwright a peer dependency and this package reaches this repository as symlinked files, so TypeScript resolves the helpers' `playwright` from where those files really live. Importing the driver in this repository as well produced two structurally different copies of `BrowserContext`, and a context this suite had opened could not be handed back to the helper that opens contexts. Taking the types from the calls that return them leaves exactly one set. The engagement now re-exports those same three types from its own entry point, which reaches the same single-set guarantee by a shorter road; what must keep holding either way is that there is exactly ONE resolution of the driver in this repository.
+
+**One wallet per run, minted, never carried.** The run's wallet name is stable and its identity is not; nothing survives a run, and no result depends on a previous one. That is also what lets this suite run beside another repository's at the same time, against the same broker, without a lock.
+
+**Nothing generic is reimplemented here.** Where a helper exists, it is called. That is a standing rule for this suite, not a preference - the crossing alone has cost days of misdiagnosis upstream, and a local copy of it would not carry those lessons.
+
+**Every wait is entered bounded.** No page or frame operation runs outside `within` or a helper that bounds it itself.
+
+**No failure text is parsed.** What `browserTrouble` answers and what a deadline carries are reported to a human reading the run and never matched on or branched on; a failed check carries an unexpected VALUE, and that is what the suite decides from.
+
+**Two suites never share this run's machinery.** One suite deadline is armed and one timings table is kept, and nothing here assumes either can be shared - the engagement offers no concurrency guarantee and this suite asks for none.
+
+## Frictions
+
+**The acquisition channel carries no version, so the Change policy has nothing to bite on.** The engagement asks for a pinned version; this repository reaches the package as a filesystem link, so what it compiles and runs against is whatever branch happens to be checked out at the other end - and the `ref:` pinned for this contract is a branch, for the same reason. The `against:` line above is the only pin that actually exists on this side. A tag-addressable, fetchable source would turn the semver discipline from a description into a mechanism.
+
+**Nothing bounds a call into the application iframe.** `frame.evaluate` carries no timeout of its own, so this suite wraps every bridge call itself. The engagement offers no way to obtain that bound, so each consumer re-derives the same wrapper - and the derivation is not free: the calls this suite reached for outside its own wrapper are exactly the ones that can still hang a run. A bounded `evaluate` here would delete the wrapper and close the gap in one move.
+
+**"Measured and bounded" is one intent and two calls.** Sizing a bound from its own measurement is the discipline the engagement itself prescribes, yet every step in this suite has to compose `measured(what, ms, (bound) => within(what, bound, task))` by hand, in a local helper written for that purpose alone. Two consumers writing the same three-line helper is the tell that the pair belongs on the engagement.
+
+## Needs
+
+**A bounded read-until-it-holds that reports what it saw.** Convergence in NextGraph is asynchronous everywhere - nothing on any surface says "it has arrived" - so a check that reads the instant after an act reads too early, and this suite has to carry its own loop: read, test, sleep, and on expiry throw naming what never arrived AND what was held instead, so the journey's remaining checks are reported unreached with an observation rather than a bare timeout. That is not specific to indexing; it is what any application's suite needs against a system that converges, and it sits exactly where the engagement's bounds already sit. What must not be lost if it moves onto the engagement: the assertions run ONCE on the reading handed back, never re-run inside the loop - a loop that retried the assertions would turn a flapping result into a green one.

.project/concepts/e2e-harness/ng-e2e-helpers/usage_polyfill-e2e.md

@@ -53,3 +53,7 @@ Everything else the package exports is offered and NOT consumed here — the scr
 **`declareSuite` fits a journey suite and not a check batch.** Only the applicative suite uses it; the other three declare a local `record`/`check` pair and print their own summary, because their shape is a flat list of checks discovered as the run goes rather than named journeys declared up front. The up-front declaration is exactly what makes the report bounded, so this is not a request to relax it — but three of four suites falling outside it suggests the package covers one of two real shapes.
 
 **The screen inventory is exported and unreachable in practice.** `BROKER_SCREENS` and the `WALLET_*` page descriptions are published, but a suite that crosses the broker with `setupBrokerPage` never needs them, and one that wanted to extend the crossing has no supported way to hand a modified inventory back in. As it stands they read as internals that happen to be exported.
+
+## Needs
+
+**A bounded wait for a condition, reporting what it last saw.** These suites hand-roll one in at least three places — polling until `listMyEntityDocs` shows a new document, until an append is visible in this session, until a triple lands — each with its own loop, its own bound and its own failure message. A second consumer, the indexing layer's suite in another repository, independently wrote the same thing to know when a deposit had become an entry. The shape both arrived at is the same: re-READ by ordinary means until a predicate holds, return the first reading that satisfies it, and on expiry name what never arrived **and the last reading seen** — the second half is what turns a timeout into a diagnosis. It is not `within`: that bounds one call, this bounds a convergence. Two independent rediscoveries suggest it belongs on the engagement rather than in each suite.

.project/concepts/sign-in/knowledge_how-a-user-gets-in.md

@@ -11,7 +11,7 @@ A newcomer holds nothing. To act they need a wallet imported once into the walle
 
 Then the page is handed to the broker, which opens the wallet and reloads the application **inside an iframe it hosts**. Outside that iframe there is no session.
 
-**The redirect is not ours.** `@ng-org/web`'s `init()` performs it as its first statement — same host, same URL shape, same frame check. Verified in its shipped bundle: when `window.self === window.top` it assigns `window.location.href` from a hard-coded `redirect` constant. This package must not reimplement it; doing so would double a function of the layer below and diverge from it in the meantime (see `app-contract/rule_no-divergence-from-nextgraph`).
+**The redirect is not ours.** `@ng-org/web`'s `init()` performs it as its first statement — same host, same URL shape, same frame check. Verified in its shipped bundle: when `window.self === window.top` it assigns `window.location.href` from a hard-coded `redirect` constant. This package must not reimplement it; doing so would double a function of the layer below and diverge from it in the meantime (see `.project/rules/nextgraph/no-divergence-from-nextgraph.md`).
 
 What is genuinely ours is the one thing `init()` cannot do: **put the identifier into the URL before `init()` reads it**. `init()` hands over `window.location.href`; it does not know the parameter exists.
 

.project/rules/INDEX.md

@@ -0,0 +1,9 @@
+# Rules (local)
+
+Each rule lists its one-line summary. **Read the full file** when a rule looks relevant - it contains the *why* and *how to apply* needed to use the rule with judgment.
+
+## nextgraph
+
+- **justify-a-return-value-by-running-it** - Never justify what a value returns without running it - five defects here, two of them rights leaks -> `.project/rules/nextgraph/justify-a-return-value-by-running-it.md`
+- **no-divergence-from-nextgraph** - Never diverge from NextGraph — ask "does the target do this?" FIRST, and only then how badly a caller would be misled -> `.project/rules/nextgraph/no-divergence-from-nextgraph.md`
+- **surface-mirrors-the-sdk** - Publish the SDK's names, parameters and returns — a difference must be justified beside the code -> `.project/rules/nextgraph/surface-mirrors-the-sdk.md`

.project/rules/nextgraph/justify-a-return-value-by-running-it.md

@@ -0,0 +1,32 @@
+---
+name: justify-a-return-value-by-running-it
+summary: Never justify what a value returns without running it - five defects here, two of them rights leaks
+group: nextgraph
+scope: local
+created: 2026-09-24
+---
+
+# A claim about what a value returns must be RUN before it is written
+
+**Rule:** Before writing a comment, a docstring or a contract clause that says a value is safe to pass on, forward, skip or trust BECAUSE OF WHAT IT RETURNS OR CARRIES, execute it. One line against the real artifact - the installed package's shipped `dist`, not the checkout this repo cites, and not the language semantics you remember. If the claim cannot be run, it is a bet: label it one, and name the version you did not check.
+
+**Why:** Five defects in this repository had one cause, and each was found only after the justification had been written, reviewed and shipped. Two of them were RIGHTS LEAKS in a package whose central promise is that one identity of a shared wallet cannot read another's data.
+
+- *"A plain property carries no items"* - true of the orm release this repo CITES, false of the one it BUILDS AGAINST, whose `useShape` hangs every identity's items off `data`, `promise` and `subscription`. A stranger read all three.
+- *"The `get` trap is the read"* - false for `Object.getOwnPropertyDescriptor`, which handed back the raw collection and the refused handle.
+- *"They take an item and return void or a boolean, so they yield nothing to leak"* - `Set.prototype.add` returns `this`. One line in a REPL says so. Holding what it returned also unlocked destruction.
+- *"A primitive cannot reach an item"* - a COUNT is a primitive that describes the items, so any count member not spelled `size` or `length` published how many the holder may not read. The test suite asserted that as CORRECT, six lines above a test calling the same thing the defect.
+- *"`$?` after a pipeline gives the command's status"* - it gives the LAST command's, so an exit-code check measured `tail`. Written by the agent that had just explained this failure mode to its user.
+
+Adjacent and the same shape: *"the summary line says 46 passed, so the suite is green"* - the runner prints a clean verdict and then intermittently hangs until its own deadline aborts it, so the summary is not the exit code.
+
+Every one of these was reasonable, was written with confidence, and was never executed. That is the whole pattern: not carelessness, but a plausible sentence about a value nobody ran.
+
+**How to apply:** The tell is a comment whose grammar is *"X is safe because it returns/carries Y"* - forwarding, passing through, skipping, trusting, not filtering. Those are the sentences to run, and they are cheap to run: `bun -e` or a throwaway probe, against `node_modules/<pkg>/dist`, takes less time than writing the justification did.
+
+Three corollaries, each earned:
+- **Verify against what SHIPS, not what is cited.** This repo's provenance annotations point at a `nextgraph-rs` checkout that is three releases behind the packages it compiles against. A claim about the installed release refuted by reading that tree is refuted against the wrong version - which happened twice, and was caught twice.
+- **A fake that has never been compared to the shipped shape makes every gate meaningless.** The first rights leak above survived ten adversarial passes and every re-run suite, because the only artifact exercising that path was hand-written and nobody had asked whether it resembled what the SDK returns. A green suite is worth exactly the fidelity of its doubles - in BOTH directions: one of these fakes was later found more CORRECT than the target, and another more permissive.
+- **A default that passes the unknown breaks silently at the next version; one that refuses it breaks loudly.** The prohibition worth keeping is not on enumerating - it is on letting an unrecognised member through. Prefer decided-or-refused.
+
+Read through [[rules-allow-judgment]]. The sibling rule [[surface-mirrors-the-sdk]] covers the same gap at the level of CITATIONS (a true reference attached to a false claim); this one covers it at the level of RUNTIME. A claim you have run needs no hedging - the target is the claim nobody executed.

.project/rules/nextgraph/no-divergence-from-nextgraph.md

@@ -1,6 +1,9 @@
 ---
-type: rule
-summary: Never implement anything that diverges from NextGraph — ask "does the target do this?" first, and only then how badly a caller would be misled
+name: no-divergence-from-nextgraph
+summary: Never diverge from NextGraph — ask "does the target do this?" FIRST, and only then how badly a caller would be misled
+group: nextgraph
+scope: local
+created: 2026-08-27
 ---
 
 # No divergence from NextGraph
@@ -32,18 +35,27 @@ When a divergence is genuinely unavoidable it must be **deliberate, documented a
 
 ## Every symbol says where it comes from
 
-Answering *does the target do this?* once, in conversation, does not survive the week. So each symbol carries its own provenance, beside the code rather than in a document that drifts: the **level** that answers (1 the engine, 2 the binding, 3 the ORM), the upstream `path:symbol` it aligns on, and one of five kinds.
+Answering *does the target do this?* once, in conversation, does not survive the week. So each symbol carries its own provenance, beside the code rather than in a document that drifts: the **level** that answers (1 the engine, 2 the binding, 3 the ORM), the `path:symbol` it cites — a symbol in `nextgraph-rs`, or, for the one kind that has nothing upstream to cite, the record in this working copy — and one kind from a closed set.
 
 | kind | meaning |
 |---|---|
 | `passthrough` | upstream's own symbol, same name and shape |
 | `aligned` | our name or ergonomics, upstream's semantics and model |
 | `declared-not-wired` | upstream **defines** the shape; nothing constructs it yet; we implement it |
+| `announced-not-written` | upstream's developers have **stated** this is the direction; nothing in the tree carries it — not a definition, not even a name |
 | `reserved-name` | upstream has declared a NAME with no shape behind it — it binds nothing, so building on it is a bet |
 | `invention` | nothing at any level answers — a deliberate, documented bet |
 | `divergent` | upstream does this, and we do it differently |
 
-A test requires the annotation on every published symbol; it cannot check that the citation is *true*, and that is fine — a citation is refutable by a reader in seconds, prose is not. The classification also applies to unpublished code that **claims to resemble the target**: the mistake this section exists for was made on an internal function, and being unexported protected nobody.
+**A citation names a symbol, not a version - and the checkout is behind.** Every citation into `engine/` and `sdk/` resolves against one sibling checkout, which declares older releases than the packages this repo installs. So a citation proves *"this was true at the cited releases"*, never *"this is true of what we build against"*. The version is a property of that checkout, not of a citation, so it is recorded **once** - the `ANCHOR` in `packages/polyfill/test/provenance.test.ts` - and checked at **both** ends: the releases the checkout declares, and the ones the workspace pins and installs. Both, because a gap statement goes stale from either end, and it went stale from the far one already: the packages moved and the checkout, which cannot follow, was left describing releases nothing here installs.
+
+The consequence is a rule about evidence, and it has already been broken here: **a claim about a shipped release cannot be refuted by reading the checkout.** Doing so refutes it against the older releases instead, which is a different statement. The tell is a sentence of the form *"the published package declares X, but upstream `foo()` still does Y"* - `foo()` at the cited release, and that says nothing about the release in the build. Worse, the usual shape of Y is an ABSENCE, and inferring from an absent implementation is what the top of this rule forbids: the pinned engine building its ORM config from `json!({})` behind a `// TODO` was read as *"the engine discards the config"* and written into two leaves, when the declaration it feeds is complete, every field of it is consumed downstream, and the only missing hop is a binding parameter the shipped binding already has. Settle a claim about a release against that release's own shipped artifact, and say plainly when the artifact cannot settle it.
+
+A test requires the annotation on every published symbol; it cannot check that the citation is *true*, and that is fine — a citation is refutable by a reader in seconds, prose is not. It does check that the citation still **resolves**, which a reader cannot: into `nextgraph-rs` when that sibling checkout is present — absent, it asks nothing rather than going red for a reason that would only teach people to skip the suite — and into this working copy always, for the one kind whose record lives here. The classification also applies to unpublished code that **claims to resemble the target**: the mistake this section exists for was made on an internal function, and being unexported protected nobody.
+
+**An announced target has no file to cite, and that is not a reason to call it ours.** `announced-not-written` covers the case the other kinds leave out: the developers have said what the direction is, and the tree carries nothing yet — no definition, not even a name. It is the **strongest** justification available there, because deviating *toward* what the target has announced is alignment, and it is the rest of the surface that will have to catch up. The two moves it replaces are both bad: citing an approximate symbol, which is the `readUnion` failure — a true citation attached to a false claim — or declaring `invention`, which understates the alignment and tells a later reader the shape is ours to change when it is not.
+
+Being the strongest, it is the **hardest to assert**. It names **who** stated it and **when** (`announced-by=<who>@<YYYY-MM-DD>`), and its `ref` is not a symbol upstream — there is none — but the **document in this working copy where the statement is on record**, plus the announced name it is on record for. That record is prose and may never be one of our own source files: our code standing as the evidence for its own shape is a circle, and the circle would wear the strongest label in the set. An announcement nobody wrote down is hearsay, and hearsay is exactly how *"every document has a native inbox"* became an implementation before anyone checked it. The date is there to be weighed: a direction announced long ago and still unwritten is worth less than one stated last week, and without a date nobody can tell the two apart.
 
 **A reserved name is not a declared shape, and the gap between them is the whole point.** `declared-not-wired` is strong *because the shape constrains us*: implementing it is realising something the target wrote down. A name with nothing behind it constrains nothing, so what we build under it is our own invention wearing the target's vocabulary — the most dangerous kind, because the borrowed name makes it read as alignment.
 

.project/rules/nextgraph/surface-mirrors-the-sdk.md

@@ -0,0 +1,42 @@
+---
+name: surface-mirrors-the-sdk
+summary: Publish the SDK's names, parameters and returns — a difference must be justified beside the code
+group: nextgraph
+scope: local
+created: 2026-09-16
+---
+
+# The published surface mirrors the SDK
+
+**Rule:** What this package publishes exposes, as far as possible, functions of the **same NAMES**, taking the **same PARAMETERS**, returning the **same VALUES** as the target SDK. A difference is allowed — but it must be **duly justified**, and the best justification of all is that the difference is **NextGraph's own direction, as announced by its developers**. The justification lives in the symbol's provenance annotation, beside the code, never in a conversation or a prose document.
+
+This is the surface-level sibling of [[no-divergence-from-nextgraph]], which asks *does the target do this?* of the model and the semantics. That question can be answered correctly and this one still failed: a symbol may carry the target's semantics exactly and still be published under a name the target never uses, taking a parameter the target cannot express. An application does not consume semantics. It types a name, passes an argument, reads a return — those three are what it will have to unlearn.
+
+**Why.** The abstract statement of this rule was available for weeks and changed nothing, so what follows is what actually happened, verified in the tree.
+
+**A name the target never uses.** `watchShape` has **zero** occurrences in `nextgraph-rs`. Worse, it spends `watch`, a verb the ORM has already spent on signal observation — `watch as watchDeepSignal` in `sdk/js/orm/src/connector/GraphOrmSubscription.ts`, `watchEffect` in the Vue adapter. So the name is not merely absent upstream, it reads as something upstream already means. The target's stated name is `useShapeQuery`.
+
+**A parameter that had to be translated.** Its `scope` is `Scope = "public" | "protected" | "private"` (`packages/polyfill/src/model/types.ts`) — three invented literals. The SDK's own `Scope` is `{ graphs?: string[] | string; subjects?: string[] }` (`sdk/js/orm/src/types.ts`). Not equivalent, therefore **not passable through**: the polyfill has to translate one into the other, and that translation is what forced an entire home-grown read pipeline beneath it — scope resolution, document enumeration, a sync barrier, a batch read. **A parameter that must be translated is the tell that a mechanism below it is about to become ours.** The cost of a re-invented parameter is never the parameter.
+
+**A true citation attached to the wrong claim.** `readUnion` has no counterpart upstream — it is N calls plus a batch policy — yet its head annotation reads `kind=aligned level=2 ref=sdk/js/lib-wasm/src/lib.rs:sparql_query`. That symbol exists and does what the annotation says it does. The citation is exact; the claim is false. A *composition* cannot be "aligned" on a single function. **This is the tell to watch for**, because it defeats the very thing annotations are for: a reader checks the citation, finds it correct, and moves on. The rest of the surface offers the honest form by contrast — `useShape` is annotated `kind=passthrough level=3` and the cited symbol *is* the function it forwards to. (The annotation has since been split so that the enumeration and the failure policy are marked `invention`; the head claim of alignment is still there.)
+
+**The legitimate deviation, so nobody concludes every difference is a fault.** `watchShape` returns a `ShapeQuery` shaped like TanStack Query's `useQuery` — `{ data, isPending, isSuccess, isError, error }` — where the SDK's `useShape` returns a result carrying the data and a load state and no failure at all (`{ data, promise, subscription, isLoading, nextPage, previousPage }`; the revision cited above returned the collection on its own, and that difference is the anchor's, not this rule's). That is a real difference from what the SDK ships today, and it is **justified**: NextGraph's direction, as reported by its developers, is a `useShapeQuery` returning exactly that shape. Deviating *toward* the announced target is alignment, not divergence — it is the rest of the surface that will have to catch up.
+
+**The gap that same example exposed — closed by `announced-not-written`.** A target **stated by its developers but not yet written** has no `file:symbol` to cite: `useShapeQuery` has zero occurrences in the tree. The taxonomy in [[no-divergence-from-nextgraph]] had no kind for it either — `declared-not-wired` needs a declaration, `reserved-name` needs a name present in the tree — so an author holding the strongest possible justification had 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. The kind `announced-not-written` is the third move: in place of a symbol upstream it cites the **record of the statement**, and it names who made it and when.
+
+```
+// @provenance useShapeQuery kind=announced-not-written level=3 ref=.project/rules/nextgraph/surface-mirrors-the-sdk.md:useShapeQuery announced-by=nextgraph-developers@2026-09-16 - the SDK ships `useShape`, whose result carries data and a load state and no failure; the announced direction is a `useShapeQuery` returning a TanStack-shaped snapshot
+```
+
+**This section is that record**, and the annotation above points back at it. The statement it holds: NextGraph's direction is a `useShapeQuery` returning `{ data, isPending, isSuccess, isError, error }`, reported from its developers and written down here on 2026-09-16 — the date the annotation carries, so a later reader can weigh how long the direction has been announced and still unwritten. An announcement nobody wrote down is hearsay: `packages/polyfill/test/provenance.test.ts` refuses an annotation of this kind whose record is missing, is a source file rather than prose, or no longer names the symbol.
+
+**How to apply.**
+
+- **Before naming a published symbol**, find the target's own name and use it. If the target has not named it, check the verb is *free* at the target: one it already spends elsewhere is taken, and borrowing it says something false.
+- **Prefer passing the target's type through to translating it.** When a parameter cannot be passed through, stop and ask what will have to be built beneath it — that is the real decision, and it is being made by the parameter.
+- **Return what the SDK returns**, unless the difference is the target's announced direction — then say whose statement it is, in the annotation's `announced-by` field and against a record the reader can open. "Whose statement" is a field the test checks, not a remark.
+- **"Duly justified" has a fixed cost**: one annotation line, beside the code, naming what the target does, what was chosen instead, and why. The test is refutability — a reader must be able to check it by opening one file.
+- **Check every citation against the CLAIM, not just against the tree.** Same granularity on both sides: a function may cite a function; a composition, a pipeline or a policy cites nothing at level 2 and must say so. "The reference resolves" is not "the annotation is true".
+- **Applies to what is published.** An internal helper that claims to resemble the target falls under [[no-divergence-from-nextgraph]]; this rule is about the symbols an application types.
+
+**Pending, not done.** Renaming `watchShape` to `useShapeQuery` and removing `readUnion` are **decided and not yet applied**. Read the two as live examples, not as history.

.tasks/INDEX.md

@@ -0,0 +1,21 @@
+# Task Index
+_Generated from filesystem._
+
+
+## T01 Align the published surface on the NextGraph SDK - done
+- T01.a A provenance annotation for a target announced but not yet written - done
+- T01.b What the ORM offers for writing and deleting, and what the three remaining symbols are - done
+- T01.c watchShape becomes useShapeQuery and takes the SDK's Scope - done
+- T01.d useShapeQuery reads through the SDK's shape query - done
+- T01.e Publish the ORM family with the rights filter - done
+- T01.f Remove readUnion, and the documents that cite it - done
+- T01.g Adversarial review of the whole published surface - done
+- T01.h Refresh the NextGraph packages to their latest published versions - done
+- T01.i Clear two mechanical leftovers from the removal - done
+- T01.j A read that cannot reach its document must fail, not answer empty - done
+- T01.k A provenance citation must say which version it describes - done
+- T01.l pnpm everywhere, and two dependency ranges that are looser than they look - done
+- T01.m There must be ONE answer to whether a document is open in this session - done
+- T01.n The polyfill's peer ranges exclude exactly the versions it needs - done
+- T01.o The read filter is bypassed by plain properties, and no fake shows it - done
+- T01.p Four minor faults on the published surface - done

.tasks/done/T01-align-the-published-surface.md

@@ -0,0 +1,76 @@
+---
+id: T01
+title: Align the published surface on the NextGraph SDK
+parent: null
+depends_on: []
+created: 2026-09-16
+claimed_by: null
+claimed_at: null
+blocked: false
+---
+
+## Description
+
+The polyfill's published surface has drifted from the SDK's: invented names, invented parameters, and symbols with no upstream counterpart. This task brings it back and installs what stops it recurring.
+
+**The principle to apply** — `.project/rules/nextgraph/surface-mirrors-the-sdk.md`, and its semantic sibling `no-divergence-from-nextgraph.md`. Publish the SDK's **names**, **parameters** and **return values**; a difference must be duly justified beside the code, and the best justification is that it is NextGraph's own direction as announced by its developers.
+
+**The facts this rests on** — `.project/concepts/app-contract/knowledge_what-a-read-scope-is-upstream.md`. In particular: a `graphs` entry is one document's graph; a store's graph holds only its containment triples, so "search my private store" returns empty silently; `did:ng:i` means the whole local dataset with no permission narrowing; scoping a read by store is not expressible at all.
+
+**Four pieces of work:**
+
+1. `watchShape` becomes `useShapeQuery`, takes the SDK's `Scope` (`{ graphs?, subjects? }`) instead of the three literals `"public" | "protected" | "private"`, and reads through the SDK's shape query instead of enumerating documents. The `ShapeQuery` return shape (TanStack-like) and the capability filter both stay — that difference is the justified kind.
+2. Wrap the ORM family the polyfill does not expose: `getObjects` and `insertObject` at identical signatures with the rights filter; arbitrate `OrmSubscription`, `DiscreteOrmSubscription`, `ngSession`; establish upstream's shape for deletion before specifying it. Today an application must import them straight from `@ng-org/orm`, and then receives every identity's data from the shared wallet with nothing signalling it — a rights hole, not a missing convenience.
+3. Remove `readUnion` entirely once nothing internal calls it. Three single-document reads become an anchored SPARQL query. `ng-helpers`' contract cites it and must be revised.
+4. The annotation mechanism: a mandatory reference on every function, which must **resolve**; plus a form for "target announced by the developers, not yet written", which the current format cannot express — so an author holding the strongest justification is pushed to miscite or to understate.
+
+**Boundary that must not be lost:** the store axis survives for **creation** (`docCreate` takes a destination upstream) and dies for **reading**.
+
+**Success criteria:** every published symbol either mirrors an SDK symbol in name, parameters and return, or carries a justified annotation; no symbol without an upstream counterpart survives unjustified; gates green (`bun test`, both typechecks, `lint.py` 0 ERROR, e2e); and an adversarial review over the whole published surface finds nothing unaddressed.
+
+## Progress
+
+## Result
+
+## Subtasks
+- T01.a A provenance annotation for a target announced but not yet written
+- T01.b What the ORM offers for writing and deleting, and what the three remaining symbols are (reconnaissance)
+- T01.c watchShape becomes useShapeQuery and takes the SDK's Scope (deps: T01.a)
+- T01.d useShapeQuery reads through the SDK's shape query (deps: T01.c)
+- T01.e Publish the ORM family with the rights filter (deps: T01.b, T01.d)
+- T01.f Remove readUnion, and the documents that cite it (deps: T01.e)
+- T01.g Adversarial review of the whole published surface (deps: all)
+
+- T01.i Clear two mechanical leftovers from the removal (deps: T01.h)
+- T01.j A read that cannot reach its document must fail, not answer empty (deps: T01.i)
+- T01.l pnpm everywhere, and two dependency ranges that are looser than they look (deps: T01.j)
+- T01.m There must be ONE answer to whether a document is open in this session (deps: T01.j)
+- T01.n The polyfill's peer ranges exclude exactly the versions it needs (deps: T01.m)
+- T01.k A provenance citation must say which version it describes (deps: T01.n)
+
+- T01.o The read filter is bypassed by plain properties, and no fake shows it
+- T01.p Four minor faults on the published surface (deps: T01.o)
+
+## Result
+
+The published surface now mirrors the SDK's names, parameters and returns, or carries an annotation that says why not and can be checked. Sixteen children, ten of them reviewed adversarially - the read path alone took six rounds before being split, and the rights leak the closing review found took five more. Two rights defects closed, both from the same cause: a written justification about a value nobody had executed, now the project rule `justify-a-return-value-by-running-it`. One item stays open and is the owner's: whether `ShapeObservable` survives migration.
+
+## Learnings digest
+
+- T01.a — the taxonomy gains `announced-not-written`: its `ref` points at the `.md` in THIS repo where the statement is on record, never a source file, plus `announced-by=<who>@<date>`. Upstream citations now resolve-check only when the sibling checkout is present; announced records always. Two latent defects fell out: the test's closed set was missing `reserved-name`, and the rule said "five kinds" over six rows. All 92 existing refs already resolved.
+- T01.b — deletion is answered at level 3 and fully wired: `DeepSignalSet.delete` -> a remove patch -> `graph_orm_update` -> `SparqlBuilder::remove_object`, which removes the SHAPE's predicates, not the subject; no document deletion exists at any level. `getObjects` returns a DETACHED clone; `insertObject` throws without `@graph`. Proposals: publish `OrmSubscription` as-is (the read filter applies to `signalObject`), publish NEITHER `DiscreteOrmSubscription` (JSON-CRDT, no `@graph`, nothing for a per-document filter to read) NOR `ngSession` (hands out the SDK handle and the session). MEASURED: `useShape` is still broken live, and the bug leaf's mechanism was FALSE - the deployment is AHEAD of our pinned `@ng-org/*`, its `orm_start_graph` takes `config` BEFORE the callback, so the five-argument client lands its callback in the wrong slot. T01.d's blocker STANDS. Also VERIFIED: ORM writes bypass `sparql_update` entirely, so the emulated write guard never sees an ORM add or delete.
+- T01.c - `useShapeQuery` takes the SDK's `Scope`, re-exported as a passthrough. Our three literals became `StoreType`, internal only: VERIFIED they are upstream's own `store_type`, so only the NAME was invented. A store is now named by its REFERENCE (`privateStore()` / `protectedStore()` / `publicStore()`), and `createEntityDoc(store?)` takes one, private when omitted, as `doc_create` does. `listMyEntityDocs`, `resolveScopeGraph` and `resolveWriteGraph` unpublished, still internal - T01.d removes the read path's last caller. VERIFIED: public and protected share one store id here, so the reference must be the index document. `1.0.0-dev.5`.
+- Package refresh (2026-09-21) - `@ng-org/*` moved to web alpha.14 / orm alpha.21 / shex-orm alpha.9 / alien-deepsignals alpha.13. The live ORM read now STARTS against the deployed broker: `6 passed, 0 failed, 6 declared`, ready in 16ms, delete reached the document. `bug_useshape-live-read-needs-a-newer-broker` DELETED - the deployment was never behind, our packages were. T01.d's blocker LIFTS. Also surfaced: `OrmSubscription` is now `RdfOrmSubscription` (T01.e's proposal names the old one); `Scope.graphs` is REQUIRED and its `[]` means the EMPTY set while `subjects: []` means NO filtering - the two axes read `[]` in opposite directions, which T01.d must not get wrong; six e2e files imported `ng-e2e-helpers` without the polyfill declaring it, fixed as `workspace:*`.
+- T01.d - `useShapeQuery` reads through `RdfOrmSubscription.getOrCreate`, injected as `configure({ ormSubscription })`; absent, the read publishes `isError` naming it. Scope resolution, the `ensureReposOpen` barrier, `readUnion` and the `@type` filter are gone from that path; `graphs`/`subjects`/`did:ng:i` reach the engine verbatim. The observable, snapshot, state and capability filter stay ours. `isError` KEPT, wired to the one real failure (the query refusing to open). A start the ENGINE refuses is swallowed upstream, so it reads `isPending` for ever - recorded in code and contract, no timeout invented. `userStoreDoc` and `liveStartWithConfig` deleted. VERIFIED: `listMyEntityDocs` is NOT dead, its own suite and an e2e journey call it. The change silently broke `examples/notebook/`, repaired out of boundary and deliberately. `1.0.0-dev.6`, major, 42/42 e2e.
+- T01.e - `getObjects` and `insertObject` published WRAPPED at upstream's names, parameters and returns. Read is capability-filtered per `@graph`; the write takes `assertMayReach` + `assertMayWrite` BEFORE the call, and `graph_orm_update` now carries the same ownership guard, so the ORM rights hole is closed. NOT published, each with a checkable reason: `RdfOrmSubscription` (pooled with no identity in the key), `DiscreteOrmSubscription`, `ngSession`, `getRaw`, `watch`/`effect`, `removeObject` (in alpha.21 but absent from the pinned `nextgraph-rs`, so no citation resolves). `1.0.0-dev.7`, MAJOR. ROOT CAUSE FOUND for the consumer's `orm_start_graph is not a function`: `makeNg()`'s passthrough did `.bind(ng)`, and the SDK's `ng` is an async proxy whose `get` trap answers EVERY key including `bind` with a path-carrying callable - so the published `ng` returned a PROMISE for all 88 members. Now `Reflect.apply`, pinned by `test/ng-proxy.test.ts`. The e2e only proves it since `initNg` routes the ORM through the wrapper - before, `polyfill-entry.ts` handed `initNg` the raw SDK object, which is why the suite stayed green while the documented path was dead.
+
+- T01.f - `readUnion` and `UnionSubject` unpublished, `read-model.ts` deleted, replaced by an internal `readDocumentSubjects(doc)` doing ONE anchored query. The blocker recorded on this task was MISDIAGNOSED: it was stated as "no shape read serves a public index", but an index is read BY ANCHOR, not by shape, and `docs.sparqlQuery` already calls `fetchReadCap(anchor)` - so the public read already worked and `useShapeQuery` never needed touching. The barrier written for it was reverted. VERIFIED UPSTREAM (`engine/verifier/src/request_processor.rs:269`, `let repo = self.repos.get(repo_id).ok_or(NgError::RepoNotFound)?`): an anchored query on a repo the verifier does not know REJECTS, crossing to JS as a rejected Promise carrying `"RepoNotFound"` (`sdk/js/lib-wasm/src/lib.rs:403,606`). The observable partition is "in `self.repos`" vs "not in" - "does not exist" and "not known to me" are INDISTINGUISHABLE, while "known but unsynced" collides with "genuinely empty". No read-capability check exists on that path at all, which confirms `fetchReadCap` is emulation machinery with no upstream counterpart. Consequence: `readUnion`'s `onUnreadable` was an INVENTION, not a heritage, so shedding it is an alignment gain; the tolerance is RELOCATED to the callers, with a visible `catch`, and no tolerant batch helper replaced it. Two behaviour changes: an unreachable document is now refused out loud, and an application composing its own raw SPARQL sees the `urn:ng-eventually:` scaffolding that `readUnion` filtered - no rights move (VERIFIED: `exposeReadCap` is called only for `scope === "public"`, `account-registry.ts:1205`), but a MODEL LEAK the application must unlearn at migration. `1.0.0-dev.8`, major. The `ng-helpers` citation of `readUnion` lives in THEIR usage declaration, never in this repo's leaves - the parent's claim named the wrong document. Follow-ups left open: `useShapeQuery` opens nothing named in `scope.graphs`, `ensureReposOpen` is now dead, `examples/notebook/tsconfig.json` fails typecheck (pre-existing).
+- T01.h - NO version moved: all four `@ng-org/*` were already at their latest published version (web alpha.14, orm alpha.21, shex-orm alpha.9, alien-deepsignals alpha.13). The refresh this task was written for had already happened inside T01.d. What the install DID surface: the tree was BUN-installed, not pnpm-installed - every `@ng-org` symlink pointed into `node_modules/.bun/`, which still held web alpha.13, shex-orm alpha.8 and alien-deepsignals alpha.11 BESIDE the current ones. Resolved versions were right, so the single-instance hazard was latent rather than active; reconciled by `CI=true pnpm install --no-frozen-lockfile`, lockfile unmoved. Gates: `424 pass / 0 fail`, both typechecks exit 0, lint 0 ERROR, `orm-live-read` `5 passed / 0 failed`, e2e `43 passed / 0 failed`. THE HEADLINE, VERIFIED INDEPENDENTLY: the pinned `nextgraph-rs` checkout (`213338f6`) declares orm `0.1.2-alpha.18` while this repo compiles against `0.1.2-alpha.21` - THREE releases behind, so every `ref=` citation in the provenance mechanism describes a version no longer used. Second-order consequence to watch: a claim about alpha.21 REFUTED by reading the pinned tree is refuted against alpha.18, which is not the same statement. Three doctrine leaves corrected (`knowledge_what-the-orm-writes-and-deletes-upstream`, `knowledge_what-a-read-scope-is-upstream`, `knowledge_what-each-suite-judges`), each carrying facts that had become false. Also found: web/shex-orm/alien-deepsignals publish a bare `0.1.2` that semver ranks ABOVE the alphas but dates from 2025 - exact pins exclude it, but `ng-e2e-helpers`' peer range `>=0.1.2-alpha.13` would admit it. Follow-ups: `pnpm-workspace.yaml` lists only `packages/*` while root `workspaces` also lists `examples/*`, so `examples/notebook` is outside pnpm entirely; the dead `.bun` store is still on disk and a future `bun install` would re-point symlinks back into it; `playwright` 1.61.1 -> 1.63.0.
+- T01.i - `ensureReposOpen` deleted (dead, grep-verified); its 3 tests went with it and that is legitimate, they asserted the BATCH's own properties (parallelism, deduplication, empty input) which no longer have a subject - the 4th, exercising `ensureRepoOpen` singular, was kept and relocated. `424 -> 421 pass`, the gap fully accounted. THE LEAD ON THE EXAMPLE WAS WRONG and the agent disproved it: the `pnpm-workspace.yaml` omission was real but NOT the cause of the `TS2345`; the actual cause was a `NoteShape` literal missing its `satisfies ShapeType<BaseType>` clause, so `valType` widened from `"iri"`/`"string"` to `string`. Proven by fixing only that, with the workspace untouched. The workspace gap was fixed anyway because item 3 needed it, and the duplication check came back clean - `examples/notebook` now resolves `@ng-org/*` to the same store paths as `packages/polyfill`. Bun store deleted (88M), and the RECURRENCE TRIGGER found: `bun.lock` was tracked in git while `.gitignore` only covered the older `bun.lockb`; now untracked, both ignored, and `packageManager: pnpm@10.26.0` declared. Left alone, reported: `docs/internal-contract.md`'s open-repo section was already stale (wrong line numbers, names a non-existent `ensurePhysicalRepoOpen`) and now also names the deleted `ensureReposOpen`; an orphaned `@ng-org/web@0.1.2-alpha.13` sits in the pnpm store with zero referencing symlinks.
+- T01.j - SPLIT after six independent adversarial rounds. DELIVERED, none of it faulted across those six reviews: the four call sites propagate instead of collapsing (`docs.sparqlQuery`, `ensureRepoOpen`, `documentInboxAddress`, and `fetchReadCap`, which stops turning a rejected download into `false`), `fetchReadCaps` deleted (dead), the `knowledge_what-a-failed-read-answers-upstream` leaf, the empty-is-success guards, e2e named-scope coverage run live by TWO independent reviewers, and the REACHABILITY half of the barrier - a holder of nothing gets `isError` with `dataLen: 0`, a public document opens from a bare reference. NOT delivered, and now written into the contract as a non-guarantee pointing at T01.m: the ARRIVAL half holds only within one session, and fails across `configure()` and when a broker rejects after the open timeout. `1.0.0-dev.9`, `449 pass / 0 fail`, e2e `46 passed / 46`. THE ROOT CAUSE, which is T01.m's subject: "is this document open in this session" has THREE answers that can disagree - `held` and `syncState` in `open-repo.ts`, and `fanOuts` in `subscribe.ts`, the one nobody counted. Round 6 replaced one of two disagreeing records; there were three. TWO PROCESS LESSONS worth more than the code. First, a round counter is the wrong stopping rule: rounds 2-5 each fixed the reported corner and opened another, and what finally decided the split was a review producing the COMMON CAUSE rather than one more corner - stop when a review explains, not when a counter trips. Second, the implementer asserted three times that a change had simplified or shrunk something and all three were contradicted by measurement (534->563, 664->727, and a numstat of 34 insertions / 8 deletions for "a condition was removed"); two were relayed to the owner before being measured. The rule now held, and written into T01.m: a structural claim carries its `wc -l` or `git show --numstat` in the same sentence, or it is not written. Also found along the way, each fixed at its source: `subscribe.ts` already offered `onSetupFailed` for a refused subscribe and nothing had wired it; `resetOpenedRepos` abandoned in-flight opens without settling them, so a caller waited the full fallback and proceeded with sync state `"unknown"`, which `index-deposit.noRowsMeansAbsent` accepts as a definitive absence - a latent failure-as-absence bug found by instrumenting a one-in-four flaky test instead of re-running it.
+- T01.l - `ng-e2e-helpers`' peer range tightened to `>=0.1.2-alpha.13 <0.1.2`, MEASURED BY RESOLUTION: before, 4 versions admitted with `maxSatisfying` = the bare `0.1.2` of 2025-10-19; after, 3, and pnpm resolves `0.1.2-alpha.15`. The premise it was handed was half wrong and it said so: pnpm never actually RESOLVED to `0.1.2` because it prefers the `latest` dist-tag, which upstream happens to point at alpha.15 - so the trap was one dist-tag move from firing, and only resolution testing shows that either way. `playwright` 1.61.1 -> 1.63.0 (raises `engines.node` to `>=20`, drops `fsevents`), e2e `46 passed / 46` on the first run. Both `typecheck` scripts moved from `bunx tsc` to `pnpm exec tsc`, VERIFIED with `~/.bun/bin` off PATH and `command -v bun` empty. MEASURED about the optional peer: a consumer of the packed polyfill receives NO `@ng-org` package under pnpm, so the old `bun install` semantics survived the tool change - but THIS checkout does get the ORM, through `packages/polyfill/package.json:33`'s devDependency, so the runner's "install it in packages/polyfill" was a false lead and both texts now say the optional peer governs what a CONSUMER receives. `pnpm link` PERFORMED and it works: the polyfill resolves to the checkout and stays at ONE copy, so the single-instance hazard is untripped - but `@ng-org/web` and `@ng-org/orm` end up at TWO copies when the app also imports the SDK, pnpm warning by name, and `file:` gives one copy at the cost of repacking, which forfeits live editing. Left alone, reported: the polyfill's own four `"*"` peers admit ONLY the bare `0.1.2` of 16 published versions and EXCLUDE every alpha, because `*` matches no pre-release - inert while the polyfill is unpublished, certain to bite at first publish (now T01.n); `examples/notebook` has no `typecheck` script; `bun build` at `orm-live-read.ts:128` and `bun run` in `mint-wallet` are still bun-bound.
+- T01.m - THE COUNT WAS ELEVEN, not the three the split had named. Deleted from `open-repo.ts`: `held`, `syncState`, `inFlight`, `settleInFlight`, `registryEpoch` - the last two IMPLIED openness through a short-circuit and nobody had ever counted them, including six adversarial rounds of T01.j. Surviving as the one answer, in `surface/subscribe.ts` (NOT `emulated-verifier/`, which is what the task file wrongly said): `fanOuts`, `establishing`, `realUnsub`, `lastState`, `attempt` - and `lastState` turned out to have been a second barrier record all along, the correct one. THE INVARIANT, written at `open-repo.ts:100-128` and on `DocChannel`: "is this document open in this session" is answered in ONE place, `docChannel(nuri)`, and `open-repo` records only the bootstrap open it ASKED FOR. Teardown is now safe BY CONSTRUCTION with no cross-module notification added, because nothing outside records openness any more; `resetOpenedRepos` disowns rather than forgets, since forgetting yields the lax `"unknown"`. CONTRACT: both non-guarantees DELETED and the arrival guarantee unqualified, `1.0.0-dev.10`, guarantee and test in the same commit - and an INDEPENDENT review attacked that first and hardest and could not break it. `462 pass / 0 fail` six times, e2e `46 passed / 46`. My own spec was wrong twice and the agent said so instead of contorting to satisfy it: the module path, and failure B's acceptance test ("2 subscribes in-window"), which is UNACHIEVABLE because the fan-out correctly dedupes. Four adversarial passes found SIX real defects in the agent's own work, including two regressions and a test of its own that asserted the defect. THE LESSON WORTH KEEPING, from the last one: it had the right fix, could not make a test discriminate, and REVERTED it - correctly - but recorded "could not construct an ordering" as an OPEN QUESTION rather than a clean bill. That wording is what let a later pass finish it. The window is exactly ONE microtask hop, swept 0-6: at 0 the clear has not happened so delivery is legitimate, at 1 a forgotten barrier is delivered, at 2+ `lastState` is already null so nothing is queued. Its earlier fake put the rejection three hops behind the replay, so the replay always won - what it had wrong was the TEST, not the remedy. Also verified by the independent review, and worth knowing because the guarantee is right for a reason nobody had written down: `"unknown"` is unreachable where a barrier was expected NOT for the stated reason, but because `fetchReadCap` -> `downloadReadCap` -> `ensurePhysicalRepoOpen` populates the open record BEFORE `mustNotAttempt` is evaluated, so even the refused path leaves a trace. Follow-ups left open: a never-settling `doc_subscribe` is unrecoverable; `public-store.attempted` skips an open after `configure`; `forgetEverything` clears four maps never.
+- T01.n - the four `@ng-org` peer ranges fixed, VERIFIED BY RESOLUTION against the registry with the real node-semver engine rather than by reading. WORSE THAN THE TASK STATED: `@ng-org/orm`'s `"*"` admitted ZERO of its 22 published versions - that library publishes no bare `0.1.2` at all, so the range was UNSATISFIABLE, not merely wrong. The other three admitted exactly 1, the stale bare `0.1.2` of 2025, and excluded every alpha. After: web `>=0.1.2-alpha.14 <0.1.2` (2 admitted, maxSatisfying alpha.15), orm `>=0.1.2-alpha.21 <0.1.2` (2), shex-orm `>=0.1.2-alpha.9 <0.1.2` (2), alien-deepsignals `>=0.1.2-alpha.13 <0.1.2` (2). The floor was taken PER PACKAGE from its own devDependencies pin rather than copying the sibling package's `alpha.13` that the task offered as an example - that floor predates its own devDep bump and is a stale artifact, not a rule. `peerDependenciesMeta: optional` confirmed correct for all four and VERIFIED rather than assumed: every `@ng-org/*` reference in `packages/polyfill/src` is `import type` only, zero runtime imports, the application injecting the real functions through `bootstrap.ts`. `examples/notebook` gained the `typecheck` script it lacked. Fresh install ends with ONE `.pnpm` store entry per package and every consuming project's realpath matching. `462 pass / 0 fail`. It also caught an error of MINE: the task file I wrote carried a baseline of 449 while the measurement says 462 - written before T01.m added its tests and never refreshed. That is the second of my own specs to carry a wrong number, after T01.m's unachievable acceptance test. Left alone, reported: `ng-e2e-helpers`' own floor looks stale for the same reason (INFERRED, out of scope).
+- T01.g - the closing review REFUTED the parent's success criterion, which is what it was for. 8 findings over 53 published symbols (not the 25 the orchestrator's naive grep counted - it measured export STATEMENTS), 41 clean. THE BLOCKING ONE IS A RIGHTS LEAK, and it is this batch's whole failure mode applied to access control: `read-filter.ts` returned non-function members RAW on the written ground that "a plain property carries no items" - true of the CITED tree (orm alpha.18, a bare `DeepSignalSet`), FALSE of the INSTALLED alpha.21, whose `useShape` returns a `UseShapeResult` carrying every identity's items on the plain properties `data`, `promise` and `subscription`. A stranger read the owner's data through all three and nothing threw. It became T01.o. Three majors: the contract instructed an injection that does not resolve (`@ng-org/orm`'s `.` maps to `core.d.ts`, which has no `useShape`); four present-tense claims that the SDK returns a bare `DeepSignalSet` are false of alpha.21, TWO of them load-bearing provenance grounds - the `readUnion` failure mode again, invisible to `provenance.test.ts` by construction; and the only live gate for the published `useShape` injects a HAND-WRITTEN substitute, so no fake in the repository returned the shipped shape, which is exactly why every gate was green. Four minors became T01.p. THE LESSON FOR THE ORCHESTRATOR, not the code: ten adversarial passes and every re-run gate of this batch were blind to this, because the only artifact exercising that path was a fake that had never been checked against what ships. A green suite is worth what its fakes are faithful to, and nobody had asked.
+- T01.o - THE RIGHTS LEAK IS CLOSED, after FIVE independent adversarial rounds. Delivered: two views (collection and result envelope) sharing one rule and one set of write traps in a single object so neither can be repaired without the other; DECIDED-OR-REFUSED as the default, which is the round-4 inversion - what the file has decided it serves is served, everything else refuses whatever its type; nine traps per view all routed through one `read` so `get`, descriptors, `has` and `ownKeys` cannot diverge; all three mutations gated on the same question with `add` additionally requiring the object to NAME a held document; every member `@ng-org/alien-deepsignals` declares non-mutating served over the readable items, pinned by a test that PARSES the shipped `dist/iteratorHelpers.js` and asserts a PARTITION (union equal, parts disjoint, exception set exactly one member) so neither a dropped member nor a smuggled second exception can pass. `1.0.0-dev.11`, `491 pass / 0 fail` exit 0, e2e exit 0 47/47, orm-live-read exit 0. WHAT THE FIVE ROUNDS FOUND, in order: three read leaks through plain properties; `add` returning the raw collection because `Set.prototype.add` returns `this`; the write side unsound plus 18 owner members broken by an over-broad refusal; a COUNT leaking through any member not spelled `size`/`length`, with the suite ASSERTING that as correct six lines above a test calling it the defect; and finally the record contradicting the code plus a gate that could not fail. THE CAUSE WAS ONE THING EVERY TIME - a justification about a value nobody executed: "a plain property carries no items" (true of the cited release, false of the built one), "the `get` trap is the read" (false for `getOwnPropertyDescriptor`), "they return void or a boolean" (false for `add`), "a primitive cannot reach an item" (false for a count), "upstream's `readOnlyArray` throws on `copyWithin`" (false - MEASURED: it runs and DESTROYS an element, while push/splice/sort/reverse/fill/shift all do throw, so refusing it is STRICTER than the target and is now recorded as a deliberate divergence), and the ECMAScript carve-out reasoning that the spec closes the KEY SET rather than the VALUE. Now a project rule, `justify-a-return-value-by-running-it`. TWO THINGS THE ORCHESTRATOR OWES: my own exit-code check read `$?` after a pipeline and measured `tail`, and every e2e figure I relayed before this task came off a SUMMARY LINE while the runner intermittently hangs after printing a clean verdict - pre-existing, now a named follow-up. AND THE STRUCTURAL LESSON: ten adversarial passes and every re-run gate were blind to the original leak because the only artifact exercising that path was a HAND-WRITTEN fake nobody had compared to the shipped shape - which then diverged twice more, once too correct (it fixed upstream's inverted `isLoading`), once too permissive (a plain array where `readOnlyArray` refuses). A green suite is worth exactly the fidelity of its doubles. Also recorded, unclosable: `console.log(result)` prints every identity's items from behind the proxy - host introspection no trap can prevent - so the contract now says not to inspect what a shape read hands you when several identities share a page.
+- T01.p - three items closed on the first pass, one BLOCKED correctly and then split. `Schema` and `DeepSignalSet` unpublished (VERIFIED unused by any published signature across `src`, `test`, `e2e` and `examples`), following the `ReadCap`/`InboxScope` precedent - MAJOR, `1.0.0-dev.12`. `docChangeType` joined the concept contract's `## Surface`, and that block is now PINNED by a test, verified by removing the export and watching it fail. The stray `@provenance` on `storeRegistry.resolveScopeGraph`, unpublished since `1.0.0-dev.5`, deleted. Item 2 - seven `kind=invention level=none ref=none` symbols above the polyfill-era divider - was blocked for the right reason (it decides what an application must DELETE at migration) and split into three: the five `EventuallyConfig` field types moved BELOW the divider after VERIFYING the precondition that `configure`/`EventuallyConfig` already sit there, a PATCH per the contract's own policy since no signature changed and neither doc ever listed them standalone, `1.0.0-dev.13`; `ShapeQuery` re-kinded from `invention` to `announced-not-written` because the record EXISTS and was checked, not assumed - `surface-mirrors-the-sdk.md` states the announced shape `{ data, isPending, isSuccess, isError, error }` field-for-field identical to the declared interface, so it now cites the same `announced-by=nextgraph-developers@2026-09-16` as `useShapeQuery`. STILL OPEN AND THE OWNER'S: `ShapeObservable` keeps `kind=invention level=none ref=none` while sitting ABOVE a divider that promises a target counterpart. That inconsistency is deliberate and unresolved - its `getSnapshot`/`subscribe`/`refetch` wrapper has no textual grounding in any announcement, so whether an application deletes it at migration is unknowable from this repository. Three fates are open: polyfill-era (below the divider), `announced-not-written` (needs a who and a when only the owner can attest), or an honestly labelled bet. Also confirmed and left alone: seven imports in `account-registry.ts` appear only in their import line, pre-existing, invisible to `tsc` because `noUnusedLocals` is off in both tsconfigs.

.tasks/done/T01.a-provenance-for-an-announced-target.md

@@ -0,0 +1,50 @@
+---
+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.
+
+**Resolved since planning (2026-09-16).** The "the `ref` must resolve" proposal FALLS: `provenance.test.ts` documents why it deliberately does not check disk — `nextgraph-rs` is a sibling checkout that may be absent, and a test red for that reason trains people to skip it. That reason holds. The third way to implement instead: check resolution ONLY when the sibling checkout is present, skip otherwise — the argument is preserved and a dead citation is still caught where it can be. The new kind for "announced by the developers, not yet written" is still needed.
+
+## Progress
+
+- 2026-09-16 — Baseline before any edit: `bun test` 394 pass / 0 fail, `lint.py` 0 ERROR. Proof set is `provenance.test.ts` plus every source file carrying an annotation.
+- 2026-09-16 — Measured the "must resolve" question instead of guessing: all 92 existing `ref`s resolve in `../nextgraph-rs` today, path AND symbol. So the third way costs nothing to adopt and catches rot the reader cannot (the citation is the thing that moved). Implemented it: upstream refs checked only when the checkout is present (`../nextgraph-rs` or `$NEXTGRAPH_RS`), announced records checked ALWAYS because they point into this working copy.
+- 2026-09-16 — Named the kind `announced-not-written`, parallel to `declared-not-wired`: it says what is there (a statement) and what is not (anything in the tree). Evidence is `ref` = the `.md` record here + the announced name, plus `announced-by=<who>@<YYYY-MM-DD>`. The record must be prose, never one of our own source files — otherwise our code stands as the evidence for its own shape, wearing the strongest label in the set.
+- 2026-09-16 — Found a pre-existing disagreement the pass condition forces to fix: the test's closed set had five kinds, the rule file's table six (`reserved-name` missing from the test), and the rule's prose said "five kinds" over a six-row table. Test, `src/index.ts` header and rule table now carry the same seven; the prose says "a closed set" instead of a number that rots.
+- 2026-09-16 — Mutation-checked both new checks rather than trusting green: a renamed upstream symbol goes red; a real `announced-not-written` line in a `.ts` file parses end to end and goes red when `announced-by` is dropped. Both probes reverted, `git diff` clean on the probed files.
+- 2026-09-16 — Gate: `bun test` 397 pass / 0 fail; both `tsc` exit 0; `lint.py` 0 ERROR.
+
+## Result
+
+**Done.** The provenance taxonomy gains `announced-not-written`: upstream's developers have stated the direction, and the tree carries nothing — not a definition, not even a name. Being the strongest kind available there, it is the hardest to assert: its `ref` is the `.md` in this working copy where the statement is on record (never a source file), and it carries `announced-by=<who>@<YYYY-MM-DD>`, refused on every other kind. The third way on resolution is implemented: upstream citations are checked only when `../nextgraph-rs` (or `$NEXTGRAPH_RS`) is present; announced records are checked always: they point here. The kind is exercised by a fixture test over a pure `malformations()`, and verified through the parser.
+
+**Files.** `packages/polyfill/test/provenance.test.ts`, `packages/polyfill/src/index.ts` (header block), `.project/rules/nextgraph/no-divergence-from-nextgraph.md`, `.project/rules/nextgraph/surface-mirrors-the-sdk.md`.
+
+**Surprises.** The test's closed set was missing `reserved-name`, which the rule table already had, and the rule said "five kinds" over six rows — both fixed. All 92 existing refs already resolve, so the new check cost no fix-ups.
+
+**Follow-ups.** T01.c's annotation is written out verbatim in `surface-mirrors-the-sdk.md` § "The gap that same example exposed" — copy it. `announced-by` is `nextgraph-developers`; a named individual would be stronger evidence, and the record names none.

.tasks/done/T01.b-what-the-orm-offers-for-writing-and-deleting.md

@@ -0,0 +1,31 @@
+---
+id: T01.b
+title: What the ORM offers for writing and deleting, and what the three remaining symbols are
+parent: T01
+depends_on: []
+created: 2026-09-16
+claimed_by: null
+claimed_at: null
+blocked: false
+---
+
+## Description
+
+**Reconnaissance, not implementation.** Piece 2 of the parent task rests on a fact nobody has established: upstream's shape for **deletion**. Specifying a wrapper before knowing it is how this project has invented before. This child establishes the facts and proposes the arbitrations; T01.e implements against its `## Result
+
+**Done:** reconnaissance only, no product code. Findings: `.project/concepts/app-contract/knowledge_what-the-orm-writes-and-deletes-upstream.md` (`nextgraph-rs` read at `213338f697df15afc086c042f4bab1bffd01aa04`).
+
+1. **Deletion — LEVEL 3 answers and is fully wired.** `DeepSignalSet.delete` → `{op:"remove", path:"/<graph>|<subject>"}` → `deepPatchesToWasm` → `ng.graph_orm_update` → `Verifier::orm_frontend_update` → `SparqlBuilder::remove_object`, which deletes only the SHAPE's declared predicates. No document deletion exists at any level. Nothing to invent.
+2. **`getObjects(shapeType, scope: Scope|string)`** returns a detached `deepClone` (mutations reach nothing); **`insertObject(shapeType, object)`** throws without `@graph`. `docs/api-contract.md` §6 checked — accurate, no drift.
+3. **Proposals (owner decides):** publish `OrmSubscription` as-is — the read filter applies to `signalObject` exactly as `surface/use-shape.ts` already does. Do NOT publish `DiscreteOrmSubscription` (JSON-CRDT, no `@graph`, so a per-document filter has nothing to read) nor `ngSession` (hands the caller the SDK handle and the session — the rule's own tell).
+4. **`useShape` live: MEASURED, still broken, and the bug leaf's mechanism was FALSE.** The name resolves; the deployed `orm_start_graph` takes `config` BEFORE the callback, so the published five-argument client lands its callback there. The deployment is AHEAD of the pinned `@ng-org/*`, not behind. Bug leaf rewritten, still open/major — T01.d's blocker STANDS.
+
+**Open question for the owner:** the consumer reports `ngSet.delete()` "works again", yet no ORM subscription can start against this deployment. Which broker were they on?
+
+**Surprises:** ORM writes go through `graph_orm_update`, NOT `ng.sparql_update` — so `surface/ng-proxy.ts`'s emulated write guard never sees an ORM add or delete (VERIFIED). `@ng-org/orm` is an optional peer with no lock entry; only the new runner imports it.
+
+**Files:** `packages/polyfill/e2e/orm-live-read.ts`, `packages/polyfill/e2e/orm-live-entry.ts` (new); `.project/concepts/app-contract/{knowledge_what-the-orm-writes-and-deletes-upstream.md,bug_useshape-live-read-needs-a-newer-broker.md,_overview.md}`; `.project/concepts/e2e-harness/{_overview.md,knowledge_what-each-suite-judges.md}`; `_debt.md` reconciled and deleted.
+
+**Gate:** `bun test` → 397 pass, 0 fail. `tsc -p packages/polyfill/tsconfig.json` → exit 0. `tsc -p packages/polyfill/e2e/tsconfig.json` → exit 0. `concept/lint.py` → 0 ERROR. e2e: `══ Polyfill e2e summary: 42 passed, 0 failed, 42 total — batch 4.0 min, slowest cold sync 30s ══` (unchanged) and `══ ORM live-read summary: 2 passed, 4 failed, 6 declared — run 1.7 min ══` (the new measurement; non-zero exit is its verdict on the deployment).
+
+**Follow-ups:** add `@ng-org/orm` to `packages/polyfill` devDependencies so the new runner survives a clean `bun install`; `docs/api-contract.md` says nothing about deletion or `graph_orm_update` — T01.e's call.

.tasks/done/T01.c-use-shape-query-name-and-scope.md

@@ -0,0 +1,62 @@
+---
+id: T01.c
+title: watchShape becomes useShapeQuery and takes the SDK's Scope
+parent: T01
+depends_on: [T01.a]
+created: 2026-09-16
+claimed_by: null
+claimed_at: null
+blocked: false
+---
+
+## Description
+
+`watchShape` becomes **`useShapeQuery`** and takes the SDK's `Scope` — `{ graphs?: string[] | string; subjects?: string[] }` (`sdk/js/orm/src/types.ts`) — in place of the three invented literals `"public" | "protected" | "private"` (`packages/polyfill/src/model/types.ts`).
+
+**The name and the parameter only.** The read path underneath stays as it is in this child; T01.d replaces it. The translation from the SDK `Scope` down to what the current pipeline needs lives here and is **explicitly temporary** — say so beside the code, because *a parameter that must be translated is the tell that a mechanism below it is about to become ours* (`.project/rules/nextgraph/surface-mirrors-the-sdk.md`).
+
+**What stays, and why that is not a fault.** The `ShapeQuery` return shape (TanStack-like: `{ data, isPending, isSuccess, isError, error }`) and the capability filter both survive. That is the **justified** kind of difference: NextGraph's direction, as reported by its developers, is a `useShapeQuery` returning exactly that shape, and deviating *toward* the announced target is alignment. `useShape` (the existing passthrough to the SDK's current hook, `packages/polyfill/src/surface/use-shape.ts`) is a different symbol and keeps its own life — do not collapse the two.
+
+**Facts — cite them, do not re-derive them.** `.project/concepts/app-contract/knowledge_what-a-read-scope-is-upstream.md`: a `graphs` entry is **one document's graph**, never a set of them; `did:ng:i` or `""` discards every other entry and means the whole local dataset **with no permission narrowing**; a store's graph holds only its containment triples, so *"search my private store"* returns empty **silently**; `[]` or `undefined` returns no objects at all; the graph filter is literal, with no prefix or hierarchy matching; **scoping a read by store is not expressible at all**.
+
+**The boundary that must not be lost.** The store axis survives for **creation** — `docs.docCreate` takes a destination upstream, and `storeRegistry.createEntityDoc(scope)` keeps its three literals — and dies for **reading**.
+
+**Open question — settle it in the open, or escalate.** After this change two different types would want the name `Scope`. The published `Scope` today is the three literals and is used by `storeRegistry.createEntityDoc / listMyEntityDocs / resolveScopeGraph / resolveWriteGraph`. The SDK's `Scope` is the object. The rule says publish the SDK's names, so the SDK's type should take the name and the **placement axis needs a name of its own** — but what that name is, and whether `listMyEntityDocs` (a *read* keyed by the store axis) survives at all, is settled by no leaf. Propose it in `## Progress`; if `listMyEntityDocs`'s fate is genuinely in question, **stop and ask** rather than removing a published symbol on your own judgment.
+
+**This child owns the contract edit and the version bump for its own change.** Edit `.project/concepts/app-contract/polyfill-surface/contract_polyfill-surface.md`: `## Surface` (the signature, the `Scope` type block), `## Non-guarantees` (every mention of `watchShape`), `## Change policy` (the new pre-release string and what it narrows). By the contract's own `## Change policy` this is a **major** — a published symbol is removed, and an existing call changes a parameter a caller must react to. No other child edits the contract for this change; do not touch the sections another child owns.
+
+**Also in scope:** `packages/polyfill/src/surface/watch-shape.ts`, `packages/polyfill/src/index.ts` (export and the comments around it), `packages/polyfill/src/model/types.ts`, `test/vocabulary.test.ts` and `test/app-surface.test.ts` (they pin the export inventory and the vocabulary), `test/watch-shape.test.ts`, `test/watch-shape-surfaces-failure.test.ts`, `docs/api-contract.md`, `packages/polyfill/README.md`, `packages/polyfill/docs/polyfill-reference.md`, `examples/notebook/app.ts`, and the `packages/polyfill/e2e/` callers.
+
+**The annotation.** `useShapeQuery` has zero occurrences in `nextgraph-rs`; its justification is NextGraph's own direction as stated by its developers. Read T01.a's `## Result` and use the form it installed. Do **not** cite an approximate symbol — that is the `readUnion` failure this whole task exists to undo.
+
+**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.
+
+**Resolved since planning (2026-09-16).** Our `Scope` type is NOT renamed — it DISAPPEARS. A renamed invented name is still an invented name. This extends to creation: the earlier note that "the store axis survives for creation" was preserving an invention because it looked necessary. Upstream `docCreate(sessionId, crdt, cls, dest, store?)` does take a store, so the NOTION survives; what is invented is our three-literal encoding. The creation path aligns on `docCreate`'s own parameters. **`listMyEntityDocs` is DELETED**: no upstream equivalent exists (no `doc_list`, no `list_docs`, nothing in the binding), and listing one's documents is an ordinary query over the store graph's `ldp:contains` — sugar over an expressible query, the same shape as `readUnion`.
+
+## Progress
+
+**2026-09-16 — the open question, settled in the open.** The planning note left two things unsettled: what the placement axis should be called once the SDK's `Scope` takes the name, and whether `listMyEntityDocs` survives. The Resolved block answered the second (deleted) and refused a rename of the first (`Scope` disappears, a renamed invented name is still invented). That forces a third answer the note did not ask for, because `resolveScopeGraph` and `resolveWriteGraph` took the same three literals and could not keep them.
+
+**What the three literals actually are.** They are not this package's invention as VALUES: `local_broker::doc_create(session_id, crdt, class_name, destination, store_type, store_repo)` takes a `store_type` of exactly `"public" | "protected" | "private"` and turns it into a `StoreRepo` with `from_type_and_repo`. What was invented is publishing them under the name `Scope`, for a READ. So the type survives as `StoreType`, DEFINED in `model/types.ts` and published nowhere - the standing `ReadCap` and `InboxScope` already have.
+
+**How an application names a store now.** By its REFERENCE, which is what `doc_create` takes and what upstream's `Session` hands out (`private_store_id`, `protected_store_id`, `public_store_id`). Three accessors, one per store, and `createEntityDoc(store?)` takes one of them - private when omitted, as upstream. A reference that is not one of the connected identity's three is refused rather than silently placed.
+
+Verified obstacle, which is why the reference is the per-store INDEX document and not the session store NURI: in this emulation public and protected are co-located on one physical store id (`store-registry.test.ts` pins `resolveScopeGraph("public") === resolveScopeGraph("protected")`), so a session store NURI cannot tell the two apart.
+
+**`resolveScopeGraph` unpublished, not re-parameterised.** Its stated use was a READ scope, and `knowledge_what-a-read-scope-is-upstream` establishes that a store's graph holds its containment triples and nothing else - so upstream that query matches nothing and says so with an empty set. `resolveWriteGraph` returned the very reference the three accessors return. Both stay internal; the e2e isolation probe reaches `resolveScopeGraph` by its internal path, which is what a harness may do.
+
+**The translation, and why it is only half a translation.** `graphs` naming documents needs none - it IS the doc set. Only `did:ng:i` / `""` does, and it is served by enumerating the identity's documents across the three stores. `subjects` is applied literally to the union's subject IRIs, as `FILTER(?s IN (…))` is upstream. `[]` / `undefined` returns no objects at all, as `Scope`'s own documentation states.
+
+**The example application is where the removal bites.** `myNotes(scope)` was `listMyEntityDocs` + `readUnion`, and there is no per-store read to replace it with. It now holds ONE `useShapeQuery` over `{ graphs: "did:ng:i" }` and writes an `rdf:type` triple so the shape can match. The shelf selector governs where the next note is WRITTEN and nothing else. Every list assertion in the applicative e2e is an `includes` positive or a cross-identity negative, so all of them survive a global list.
+
+## Result
+
+**Done.** `watchShape` is `useShapeQuery` and takes the SDK's `Scope` (`{ graphs, subjects }`, re-exported from `@ng-org/orm`); `ShapeQuery` and the capability filter are unchanged. The annotation is `announced-not-written`, copied verbatim from the rule. Our three-literal `Scope` is gone from the published surface: it is `StoreType`, defined in `model/types.ts`, published nowhere. A store is now named by its REFERENCE - `storeRegistry.privateStore() / protectedStore() / publicStore()` - and `createEntityDoc(store?)` takes one, private when omitted, as `doc_create` does. `listMyEntityDocs`, `resolveScopeGraph` and `resolveWriteGraph` are unpublished (still internal). Contract leaf rewritten with a symbol-by-symbol migration note; `1.0.0-dev.5`.
+
+**Files.** `packages/polyfill/src/{index,model/types,surface/placement,surface/use-shape-query,shared-wallet/account-registry,emulated-verifier/caps,emulated-verifier/branch-registers}.ts`, 13 test files, `e2e/{polyfill-entry,run,notebook}.ts`, `examples/notebook/app.ts`, `docs/api-contract.md`, both READMEs, `contract_polyfill-surface.md`, `package.json`.
+
+**Gate.** `bun test` 401 pass / 0 fail; both `tsc` exit 0; concept lint 0 ERROR; grep on `index.ts` no match.
+
+**Surprises.** VERIFIED: the three literals are upstream's own `store_type`, so only the NAME was invented. VERIFIED: public and protected share one store id here, so the store reference must be the index document. VERIFIED: `listMyEntityDocs` is still the read path's - T01.d removes the last caller.
+
+**Follow-ups.** The whole-dataset read now opens three store documents instead of one. `surface-mirrors-the-sdk.md` still calls the rename "not yet applied". `docs/internal-contract.md`, `docs/simulation.md` and the root `README.md` still name the removed symbols.

.tasks/done/T01.d-use-shape-query-reads-through-the-sdk.md

@@ -0,0 +1,54 @@
+---
+id: T01.d
+title: useShapeQuery reads through the SDK's shape query
+parent: T01
+depends_on: [T01.c]
+created: 2026-09-16
+claimed_by: T01.d-worker
+claimed_at: 2026-09-21
+blocked: false
+---
+
+## Description
+
+`useShapeQuery` stops resolving a logical scope, enumerating documents, awaiting a sync barrier and calling `readUnion`, and reads through the **SDK's shape query** instead. The `ShapeQuery` snapshot and the capability filter survive; the home-grown pipeline goes.
+
+**What "the pipeline" is, concretely.** `packages/polyfill/src/surface/watch-shape.ts` owns four steps today: resolve the logical scope to a document set (`listMyEntityDocs` in `shared-wallet/account-registry.ts`), open them through `ensureReposOpen` / `getSyncState` (`emulated-verifier/open-repo.ts`) which is the sync barrier `isPending` waits on, call `readUnion(docs)`, then filter the union by the shape's `@type` IRI. All four are the mechanism a translated parameter forced into existence, and all four are what this child removes.
+
+**A blocker to resolve BEFORE implementing, not after.** `.project/concepts/app-contract/bug_useshape-live-read-needs-a-newer-broker.md` is an **open MAJOR bug**: the SDK's ORM subscription **never starts** against the broker deployed today — `orm_start_graph` is missing from two hand-maintained, independently-copied dispatch tables in any build made before commit `d5ecd0fd` — and the failure is an eternal pending set with one `console.error` as its only trace, indistinguishable from "this scope holds nothing". That leaf states explicitly that `watchShape` is **not affected**, because it is built on `doc_subscribe` (continuously present in both tables under a stable name), and the contract's `## Non-guarantees` tells applications to use `watchShape` for a reactive read for exactly that reason.
+
+So this change takes the one reactive read that works and puts it on the path that does not, and the workaround the contract publishes stops existing. Establish what happens to that guarantee — a broker redeployment, a documented narrowing of the contract, a fallback — **before** writing the change. If it cannot be settled from the leaves, **stop and ask**. Do not implement and discover the consequence afterwards.
+
+**`isError` has no counterpart at any level**, and that is recorded rather than assumed: `OrmSubscription`'s readiness promise is built with `resolve` alone, nothing rejects it, and `resolveReady()` runs on one path only — the arrival of initial data — so upstream's *"I could not find out"* **is** its *"still pending"* (annotation on `ShapeQuery` in `watch-shape.ts`; `docs/api-contract.md` § 6). Whatever replaces the pipeline must still be able to publish `isError`, or dropping it is a contract narrowing of its own that has to be declared.
+
+**Facts — cite them, do not re-derive them.** `.project/concepts/app-contract/knowledge_what-a-read-scope-is-upstream.md`: the two axes and nothing else; the graph filter is literal; `did:ng:i` drops the graph filter entirely and runs over the whole local dataset with **nothing** added to narrow it by what the reader may open; the only bound is what the verifier has materialised locally; `subjects` filters the **root** shape only; `OrmSubscription.readyPromise` distinguishes not-ready from ready-and-empty at level 3 while the React `useShape` adapter drops that distinction. Also relevant: `makeReadFilteredView` (`packages/polyfill/src/emulated-verifier/read-filter.ts`) is the emulation of what the broker will bound **at delivery**, applied per document on what comes back — that is where the rights filter belongs, and `packages/polyfill/src/surface/use-shape.ts` already shows the shape of it.
+
+**Leave `readUnion` alone here.** After this child `watch-shape.ts` no longer calls it, but `packages/polyfill/src/emulated-verifier/index-deposit.ts:253` and `:304` still do. Removing the symbol is T01.f's work.
+
+**This child owns the contract edit and the version bump for its own change.** Edit `.project/concepts/app-contract/polyfill-surface/contract_polyfill-surface.md` — `## Guarantees` and `## Non-guarantees` first, because that is where a narrowing shows up, then `## Surface`, then `## Change policy`. Apply the contract's own rules to decide the level rather than assuming one. No other child edits the contract for this change.
+
+**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.
+
+**Resolved since planning (2026-09-16).** `useShapeQuery` does NOT delegate to the SDK's `useShape` — that return type cannot carry the request state, which is the whole point. It KEEPS `watchShape`'s implementation: the observable and the state tracking are ours. What changes is the PARAMETER (the SDK's `Scope`) and what is queried underneath (the SDK's shape query instead of `readUnion`). **`isError` stays.** The reasoning "it survives only if the SDK exposes an error channel" is wrong: the polyfill's mission is to ENRICH the SDK in its announced direction, not to be bounded by what it exposes today. Wire real errors if you can; otherwise the field stays and is filled later.
+
+## Progress
+
+- Blocker confirmed LIFTED before writing anything: the deleted bug leaf's premise was the pinned packages, and `RdfOrmSubscription.getOrCreate` is reachable at `@ng-org/orm@0.1.2-alpha.21`.
+- Read the doctrine first (`surface-mirrors-the-sdk`, `no-divergence-from-nextgraph`, `knowledge_what-a-read-scope-is-upstream`), then the SDK's installed typings to establish what the shape query offers: `readyPromise` (pending vs ready-and-empty), `signalObject`, `addChangeListener`, `close`.
+- Established, by reading `dist/connector/RdfOrmSubscription.js`, that `orm_start_graph` failing is caught and only `console.error`'d and that `readyPromise` is built with `resolve` alone. So the ONLY real error channel on this path is the query refusing to open; `isError` is wired to that and the rest is recorded rather than invented (no timeout was added).
+- Chose injection over a runtime import: the package never hard-imports the SDK, and `useShape` is React's hook, unusable from an observable. `configure({ ormSubscription })` mirrors the `ng` / `useShape` fields beside it, and `RdfOrmSubscription.getOrCreate` is assignable to it with no wrapper (probed with `tsc` before committing to the type).
+- Rewrote both suites against a new `test/orm-fake.ts` - a small engine honouring the two scope axes the way `schema_shape_to_sparql` does, so the scope tests still prove something. Nothing deleted: 7 -> 11 and 12 -> 15 tests.
+- The e2e harness now injects the REAL ORM, so the two `useShapeQuery` journeys measure the deployed broker. First run died in the broker login (a transient before any assertion); the second passed 42/42.
+
+
+## Result
+
+**Done.** `useShapeQuery` reads through the SDK's shape query (`RdfOrmSubscription.getOrCreate`, injected as `configure({ ormSubscription })`; absent, the read publishes `isError` naming it). Scope resolution, the `ensureReposOpen` barrier, `readUnion` and the `@type` filter are gone; `graphs`/`subjects`/`did:ng:i` reach the engine verbatim. The observable, snapshot, state tracking and capability filter stay ours. `data` items are the shape's own objects and `shapeType` is `ShapeType<T>`. **`isError` stays**, wired to the one real failure - the query refusing to open. A start the ENGINE refuses is swallowed upstream, so it reads `isPending` for ever: recorded in code and contract, no timeout invented. `userStoreDoc` deleted; `liveStartWithConfig` retired. `1.0.0-dev.6`, major.
+
+**Files.** `packages/polyfill/` src (7), test (4, incl. new `orm-fake.ts`), e2e (4), `package.json`, `README.md`; `docs/{api-contract,internal-contract}.md`; the contract leaf. Out of boundary, deliberately: `examples/notebook/` + `bun.lock` - the change silently broke the reference consumer.
+
+**Gate.** `bun test` 408 pass / 0 fail; both `tsc` exit 0; lint 0 ERROR; `42 passed, 0 failed, 42 total - batch 3.3 min`.
+
+**Surprises.** VERIFIED: `listMyEntityDocs` is NOT dead - its own suite and an e2e journey call it. VERIFIED: `bun.lock` was stale before this; `bun install` synced it.
+
+**Follow-ups.** `readUnion` keeps two `index-deposit.ts` callers (T01.f). `knowledge_what-the-orm-writes-and-deletes-upstream.md` links the deleted bug leaf. `watchShape` survives as a stale name in ~10 src comments.

.tasks/done/T01.e-publish-the-orm-family.md

@@ -0,0 +1,58 @@
+---
+id: T01.e
+title: Publish the ORM family with the rights filter
+parent: T01
+depends_on: [T01.b, T01.d]
+created: 2026-09-16
+claimed_by: worker-T01.e
+claimed_at: 2026-09-21
+blocked: false
+---
+
+## Description
+
+Wrap and publish the ORM family this package does not expose: `getObjects` and `insertObject` at **identical signatures**, with the rights filter; deletion in whatever shape T01.b established; and whatever T01.b's arbitration settled for `OrmSubscription`, `DiscreteOrmSubscription` and `ngSession`.
+
+**Why the dependencies.** On **T01.b**: the deletion shape and the three arbitrations are established there — read its `## Result` and the `knowledge_` leaf it names, rather than re-reading `nextgraph-rs`. On **T01.d**: both children change the published surface and edit the same contract, and they must not run concurrently.
+
+**The problem is a rights hole, not a missing convenience.** Today an application has to import these straight from `@ng-org/orm`, and then receives **every identity's data** out of the shared wallet with **nothing signalling it**. The filter that closes it is `makeReadFilteredView` (`packages/polyfill/src/emulated-verifier/read-filter.ts`, annotated `kind=aligned level=1 ref=engine/verifier/src/verifier.rs:load_repo_from_read_cap`): it keeps only items whose document — their `@graph` — the current holder has a cap for, applied per document on what comes back. That is the emulation of what the broker will bound at delivery, done where the target does it. `packages/polyfill/src/surface/use-shape.ts` is the existing example of a passthrough that filters results.
+
+**Identical signature means passed through, not translated.** If a parameter cannot be passed through, stop and say what would have to be built beneath it — that is the real decision, and it is being made by the parameter (`.project/rules/nextgraph/surface-mirrors-the-sdk.md`). Do not invent an ergonomic wrapper that an application would have to unlearn.
+
+**Open questions to carry or close — do not invent past them:**
+
+- If T01.b left the **deletion** shape unestablished, this child does **not** specify one. Report it and publish the rest.
+- **A write path cannot be rights-filtered the way a read is.** The filter is a read emulation. `packages/polyfill/src/surface/ng-proxy.ts` already overrides `sparql_update` with an emulated write guard — read it before deciding what `insertObject` does with an unauthorized write. Do not invent a write guard the target does not have; if the answer is "the existing guard covers it", say which line does.
+- If T01.b's arbitration for `OrmSubscription` / `DiscreteOrmSubscription` / `ngSession` is a proposal the user has not confirmed, and acting on it would **remove or rename** something, stop and ask. Adding is reversible; removing a published symbol is a major that a caller pays for.
+
+**This child owns the contract edit and the version bump for its own change.** Edit `.project/concepts/app-contract/polyfill-surface/contract_polyfill-surface.md` — `## Surface`, `## Guarantees` (what the filter promises about what comes back), `## Non-guarantees`, `## Change policy`. By the contract's own rules, symbols added with nothing existing moved is a **minor**; if the arbitration removes or narrows anything it is a **major**. Apply the rule, do not assume a level. No other child edits the contract for this change.
+
+**Also in scope:** `packages/polyfill/src/index.ts` (the export and its `@provenance` lines — each new symbol needs one, in the form T01.a installed), `test/vocabulary.test.ts` and `test/app-surface.test.ts` (they pin the export inventory), `test/provenance.test.ts` coverage, `docs/api-contract.md`, `packages/polyfill/README.md`, `packages/polyfill/docs/polyfill-reference.md`. New behaviour needs new tests, including the rights case: a second identity's data must not come back.
+
+**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.
+
+**Resolved since planning (2026-09-16).** A write is not rights-filtered like a read: upstream bounds a write by write capability, not by hiding results. So `insertObject` gets a GUARD BEFORE the write, following the package's existing pattern (`assertOwnInbox`, `mustNotAttempt`, `assertMayReach`) — never a filter over what it returns.
+
+**Resolved since planning (2026-09-21), and it overturns T01.b's proposal.** NO SDK element is published as-is, ever. Re-exporting one hands the caller a path straight to the SDK that SHORT-CIRCUITS this package's emulation - the capability filter, and above all the shared-wallet identity boundary. T01.b proposed publishing `OrmSubscription` unchanged; that proposal is void. Every symbol this package offers from the ORM family is WRAPPED, at the same name and signature, with the emulation applied. If a symbol cannot be wrapped meaningfully, it is not published at all - that is a valid outcome, not a failure.
+
+Note also: `OrmSubscription` was renamed `RdfOrmSubscription` in `@ng-org/orm@0.1.2-alpha.21`, and `getOrCreate` returns a narrowed `RdfOrmSubscriptionFor<...>` rather than the class. T01.b's proposal named the old symbol.
+
+## Progress
+
+- Read the two governing rules, T01.b's and T01.d's `## Result`, the parent's `## Learnings digest`, and `knowledge_what-the-orm-writes-and-deletes-upstream.md`. Baseline taken first: `bun test` 408/0, both `tsc` 0, lint 0 ERROR.
+- Read the ORM family AT THE SOURCE and in the installed `@ng-org/orm@0.1.2-alpha.21`: `getObjects`, `insertObject`, `removeObject` (NEW, absent from the pinned `nextgraph-rs`), `RdfOrmSubscription`, `DiscreteOrmSubscription`, `ngSession`, plus `getRaw`/`watch`/`effect`. Decided each against the "nothing published as-is" rule; reasons recorded in `src/surface/orm.ts` and `docs/api-contract.md` section 6bis.
+- Published `getObjects` and `insertObject` wrapped, at upstream's own names, parameters and returns, injected through `configure` like the shape query beside them. `getObjects`'s config parameter is `RdfOrmConfig` (alpha.21's widening of `Scope | string`), which forced publishing that type from the SDK's `/all` subpath.
+- Closed the `graph_orm_update` rights hole in two pieces: the guard (an override in `ng-proxy.ts`, ownership via `assertMayWrite`, reading the document out of each patch's `path`), and the door it sits on (`initNg` now hands the ORM this package's wrapped `ng`, because both consumers in the repo hand it the raw SDK object).
+- That substitution turned the e2e RED on the two `useShapeQuery` journeys; the reference run was green, so it was mine. Measured the cause: `makeNg()`'s passthrough did `Reflect.get(ng, prop).bind(ng)`, and `@ng-org/web`'s `ng` is itself a Proxy answering every key - `bind` included - with a path-carrying callable returning a Promise. The published `ng` therefore answered all 88 members with a promise. Forwarded with `Reflect.apply` instead; pinned by a test whose fake is shaped like the real proxy, and which was verified to FAIL on the old line.
+- Contract leaf edited (Scope, Deployment requirements, Surface, Guarantees, Non-guarantees, Change policy), bumped to `1.0.0-dev.7` as a MAJOR under the leaf's own policy, and in `package.json`. `docs/api-contract.md` (new section 6bis, sections 2/3/14 and the appendix), `docs/internal-contract.md`, `README.md`, `docs/polyfill-reference.md` updated.
+
+
+## Result
+
+**Done.** `getObjects` and `insertObject` are published WRAPPED, at upstream's names, parameters and returns, injected through `configure`. The read is capability-filtered per `@graph` (collection shape preserved); the write takes `assertMayReach` + `assertMayWrite` BEFORE the call. `graph_orm_update` now carries the same ownership guard in `ng-proxy.ts`, and `initNg` substitutes this package's wrapped `ng` so the ORM knocks on that door - the rights hole is closed. NOT published, each with a checkable reason: `RdfOrmSubscription` (pooled with no identity in the key), `DiscreteOrmSubscription`, `ngSession`, `getRaw`, `watch`/`effect`, and `removeObject` (exists in alpha.21, absent from the pinned `nextgraph-rs`, so no citation resolves). `1.0.0-dev.7`, MAJOR: an ORM write into a document you do not own is now refused.
+
+**Found and fixed, MEASURED.** `makeNg()`'s passthrough did `.bind(ng)`; the SDK's `ng` is itself a Proxy answering every key including `bind`, so the published `ng` returned a PROMISE for all 88 members - `orm_start_graph is not a function`, swallowed by the ORM, read pending for ever. Now `Reflect.apply`. The e2e proves it only since `initNg` routes the ORM through the wrapper.
+
+**Gate.** `bun test` 424 pass / 0 fail; both `tsc` exit 0; lint 0 ERROR; `== Polyfill e2e summary: 42 passed, 0 failed, 42 total - batch 3.3 min, slowest cold sync 27s ==`.
+
+**Follow-ups.** `examples/notebook` fails its OWN `tsc` on HEAD already (its shape literal needs `satisfies`). `discrete_orm_update` is unguarded. `removeObject` awaits a refreshed `nextgraph-rs`.

.tasks/done/T01.f-remove-read-union.md

@@ -0,0 +1,141 @@
+---
+id: T01.f
+title: Remove readUnion, and the documents that cite it
+parent: T01
+depends_on: [T01.e]
+created: 2026-09-16
+claimed_by: T01.f-worker
+claimed_at: 2026-09-21
+blocked: false
+---
+
+## Description
+
+Remove `readUnion` — and `UnionSubject` with it, if no published signature still uses it — from the published surface entirely, once nothing internal calls it. The remaining internal single-document reads become **anchored SPARQL queries**.
+
+**Why it goes.** It has no counterpart upstream: it is N calls plus a batch policy. Its head annotation reads `kind=aligned level=2 ref=sdk/js/lib-wasm/src/lib.rs:sparql_query` — a citation that is exact, attached to a claim that is false, which is the worst failure mode of the annotation mechanism because a reader checks it, finds it correct, and moves on (`.project/rules/nextgraph/surface-mirrors-the-sdk.md`). A **composition cannot be aligned on a single function**.
+
+**Call sites at planning time — verify, they may have moved.** In `src`: `packages/polyfill/src/emulated-verifier/index-deposit.ts:253` and `:304`, both single-document reads; `packages/polyfill/src/surface/watch-shape.ts:351`, which T01.d should have removed — confirm it is gone rather than assuming. Outside `src`: `examples/notebook/app.ts:108` and `:130`; `packages/polyfill/e2e/polyfill-entry.ts:402, 425, 427, 675`. Tests that exercise it: `test/read-model.test.ts`, `test/open-repo.test.ts`, `test/cross-user-access.test.ts`, `test/reload-own-document.test.ts`, `test/watch-shape.test.ts`, `test/inbox-dispatch.test.ts`, `test/listing-surfaces-failure.test.ts`, `test/deferred-inbox-processing.test.ts`. The anti-cheat applies in full: a test that proved behaviour **through** `readUnion` is re-pointed at whatever replaces it, never deleted and never weakened. `test/open-repo.test.ts` in particular uses it as the only integration path onto `ensureRepoOpen` — that coverage has to survive by another route.
+
+**Anchored, not anchorless.** The mechanics are level-1 VERIFIED and recorded in `docs/api-contract.md` § 6: an anchor restricts the query to that repo's graph as default graph (`resolve_target_for_sparql`, `engine/verifier/src/request_processor.rs`), while an **anchorless** query unions every named graph in the session store. Replacing several anchored reads with one anchorless query would be a silent widening of what a read can reach — do not do it.
+
+**Two documents cite it, and both must be revised.**
+
+1. `.project/concepts/app-contract/polyfill-surface/contract_polyfill-surface.md` — `## Surface` (the signature and the `UnionSubject` interface) and `## Non-guarantees`, where the entry for the `useShape` broker bug currently tells applications *"Use `watchShape` for a reactive read and `readUnion` for a one-shot one — neither goes through that path"*. With `watchShape` renamed (T01.c), possibly re-pathed (T01.d), and `readUnion` gone, that published workaround **for an open MAJOR bug** no longer exists. Say what replaces it, or say plainly that nothing does. Do not leave the sentence standing.
+2. The parent task states that `ng-helpers`' contract cites `readUnion` and must be revised. At planning time a grep of `.project/concepts/e2e-harness/ng-e2e-helpers/` found **no** such citation — neither `contract_ng-e2e-helpers.md` nor `usage_polyfill-e2e.md` names it — while the e2e **code** under `packages/polyfill/e2e/` uses it heavily. Find where the citation actually lives before revising anything; if it turns out to be only the code, record that in `## Result
+
+Status: done. `1.0.0-dev.8`, major. Two commits: `0c21ade` (the removal) and `0a2b8b1` (the documents).
+
+### The opening barrier in `useShapeQuery` was NOT added
+
+The orchestrator first framed the blocker as "no shape read serves a public index", then withdrew it: an index is read BY ANCHOR, not by shape, and `docs.sparqlQuery` already fetches the public store's key at its door (`packages/polyfill/src/surface/docs.ts:155`). The barrier had been written and verified against a new test; both were reverted, uncommitted, on instruction. `use-shape-query.ts` carries one comment edit in this task and nothing else.
+
+### What unblocks the removal, and how it was verified
+
+VERIFIED: `packages/polyfill/test/cross-user-access.test.ts` — *"a bare reference is enough for a PUBLIC document, and not for a protected one"*. It now asserts, under Bob, that he holds no capability for either document, reads the public one through the anchored `docs.sparqlQuery`, and holds its key afterwards — obtained from the document, not handed across by the test. That is the property `readUnion` was protecting, and it belongs to the primitive underneath it.
+
+### What was removed, and what each call site became
+
+`readUnion` and `UnionSubject` are gone from the entry. `packages/polyfill/src/surface/read-model.ts` is deleted; `packages/polyfill/src/surface/read-document.ts` replaces it with `readDocumentSubjects(doc)` — ONE anchored query, INTERNAL, `kind=invention` (the anchored query itself is `docs.sparqlQuery`, annotated there; what is ours is the cold-start open and the row grouping).
+
+- `index-deposit.ts` (two sites) — the `onUnreadable` callback became a `catch`; both still return `unreadable`, and `noRowsMeansAbsent` still consults `getSyncState`, which is why the `ensureRepoOpen` in front of the read cannot move to the caller.
+- `examples/notebook/app.ts`, `packages/polyfill/e2e/polyfill-entry.ts` — each composes its own read over the published `docs.sparqlQuery`. The two multi-document e2e sites carry a VISIBLE `catch` and report what they skipped.
+- Tests re-pointed, none deleted or weakened. `open-repo.test.ts` keeps its integration path onto `ensureRepoOpen` by the same route. `read-model.test.ts` → `read-document.test.ts`: three cases that tested the batch POLICY were re-pointed at what replaced it (a failed read throws; an empty document answers `[]`; two reads never merge), and the file header says which and why.
+
+### The per-document tolerance
+
+RELOCATED to the caller, not lost — and shedding it is an alignment gain, since upstream an anchored query on a repo the verifier does not hold rejects (`resolve_target_for_sparql` → `NgError::RepoNotFound`). No tolerant batch helper was introduced anywhere.
+
+### Two behaviour changes, both recorded in the contract
+
+1. A document the holder has no capability for is REFUSED out loud instead of dropped from a batch.
+2. Subjects under the reserved `urn:ng-eventually:` prefix are no longer filtered for an application. No rights move: the only registers an ordinary document carries are its inbox address and, for a public document, the key its store already serves to whoever asks; the cap-bearing `inboxCap` register lives in its owner's private store.
+
+### Does our emulation reject, or answer empty?
+
+VERIFIED: it REJECTS, and it does not swallow. `docs.sparqlQuery` has no `catch` — it forwards `ng.sparql_query`'s rejection unchanged — and `readDocumentSubjects` has none either. The swallow that existed was `readDoc` inside the deleted module. One nuance, pre-existing: for a document whose public-store cap fetch failed transiently, `fetchReadCap` returns `false` and the rejection that reaches the caller is this package's "you hold no cap", not the broker's outage. That conflation is documented in `public-store.ts` and is not introduced here.
+
+### Where `ng-helpers` cites `readUnion`
+
+In its OWN published `usage_ng-helpers.md` against `polyfill-surface`, under `## Consumed surface` and `## Needs` — not in any leaf of this repo, and not in `contract_ng-e2e-helpers.md` / `usage_polyfill-e2e.md`. The planner's grep was right about where it is NOT; the parent's claim that "`ng-helpers`' contract cites `readUnion`" was wrong about which document. Read through the declaration only, never their code.
+
+### Follow-ups (not fixed here)
+
+- `useShapeQuery` never opens the documents named in `scope.graphs`, so an application naming an unopened or public-store document gets an empty result with no error. Real, out of scope, probably deserves a `bug_` leaf in `app-contract`.
+- `ensureReposOpen` now has no production caller (only `open-repo.test.ts`). Internal dead code.
+- `examples/notebook/tsconfig.json` does not typecheck — PRE-EXISTING, verified against the branch tip before any edit: the hand-written `NoteShape` does not satisfy `ShapeType<BaseType>`.
+- The `ng-helpers` declaration still reports `1 passed / 29 failed`-era breakage and three Needs this removal does not answer; their `against:` pin is `1.0.0-dev.6` and the surface is now `1.0.0-dev.8`.
+- `.project/concepts/app-contract/_debt.md` carries markers for `orm.ts` and `use-shape-query.ts` raised before this task; left alone.
+- The dated `docs/briefs/` were deliberately not rewritten: they describe a July state that the documents themselves date.
+- The e2e suite was NOT run (it needs a live broker); it is not part of this task's gate.
+` so the parent's claim is corrected rather than silently dropped.
+
+**This child owns the contract edit and the version bump for its own change** — a published symbol removed is a **major** by the contract's own `## Change policy`. No other child edits the contract for this change.
+
+**Also in scope:** `packages/polyfill/src/surface/read-model.ts` (the module goes if nothing else lives in it), `packages/polyfill/src/index.ts`, `test/vocabulary.test.ts` and `test/app-surface.test.ts`, `docs/api-contract.md`, `packages/polyfill/README.md`, `packages/polyfill/docs/polyfill-reference.md`, and the `docs/` briefs only where they state something that is now false.
+
+**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.
+
+**Resolved since planning (2026-09-16).** Do NOT read `ng-helpers` — not its code, not its tests. The isolation discipline says a counterpart is reached through its engagement and its usage declaration only. The planner's finding (that no contract leaf cites `readUnion`) was correct but obtained by a forbidden method. If this task needs to know who depends on `readUnion`, the answer belongs in a `usage_` declaration; `ng-helpers` has never authored one, and producing that is the fix, not a workaround by reading.
+
+**Resolved since planning (2026-09-21) - `readUnion` HAS a declared consumer.** `ng-helpers` published its usage declaration (`polyfill-surface--ng-helpers`) and it says YES: `e2e/indexing-app.ts` calls `readUnion([doc])` twice, and `src/index.ts` REPUBLISHES it to ng-helpers' own consumers as the documented way to read an index. No ORM is wired there (`useShape: () => undefined`), so `useShapeQuery` is unreachable for them; their only fallback is an anchored `docs.sparqlQuery`. They declared this as a Need at full strength.
+
+So the removal is not free. Before removing, decide with the owner what a consumer with no ORM reads with. Their declaration is the channel: read it at `ng-helpers`' repo through its published `usage_` leaf, never by reading their code.
+
+**Also relevant, and worse than it looks.** That declaration reports `ng-helpers` still calling `createEntityDoc("public")` and `listMyEntityDocs("public")`, both invalid since `1.0.0-dev.5`, while its own test suite stays green because it runs against a fake that still models the superseded surface. A consumer can therefore be broken against us with nothing red on either side. Do not treat their green suite as evidence.
+
+**Update (2026-09-21) - wiring the ORM does NOT unblock the removal, and the reason is ours.** `ng-helpers` wired the ORM as the contract prescribes and re-measured. Its verdict, recorded in its published usage declaration: neither shape read fetches a PUBLIC STORE's key, so a stranger reading a public index **from its reference alone** - the central case for an index - is served by no shape query at all. `readUnion` is the only thing that serves it today.
+
+So the removal is blocked by a capability gap on OUR side, not by a consumer's reluctance. Before removing, either that gap closes or the removal does not happen. Read their declaration for the three secondary costs they list; do not read their code.
+
+Their e2e also went from a measured `1 passed / 29 failed` (they were already broken against us, with both suites green) to `28 passed / 2 failed`, the two remaining being a provider defect: `useShapeQuery` never starts because `orm_start_graph is not a function`, swallowed, `isPending` for ever - measured on three consecutive runs, with the SDK's `ng` answering that member and `initNg` discarding its first argument.
+
+## Progress
+
+## Result
+
+Status: done. `1.0.0-dev.8`, major. Two commits: `0c21ade` (the removal) and `0a2b8b1` (the documents).
+
+### The opening barrier in `useShapeQuery` was NOT added
+
+The orchestrator first framed the blocker as "no shape read serves a public index", then withdrew it: an index is read BY ANCHOR, not by shape, and `docs.sparqlQuery` already fetches the public store's key at its door (`packages/polyfill/src/surface/docs.ts:155`). The barrier had been written and verified against a new test; both were reverted, uncommitted, on instruction. `use-shape-query.ts` carries one comment edit in this task and nothing else.
+
+### What unblocks the removal, and how it was verified
+
+VERIFIED: `packages/polyfill/test/cross-user-access.test.ts` — *"a bare reference is enough for a PUBLIC document, and not for a protected one"*. It now asserts, under Bob, that he holds no capability for either document, reads the public one through the anchored `docs.sparqlQuery`, and holds its key afterwards — obtained from the document, not handed across by the test. That is the property `readUnion` was protecting, and it belongs to the primitive underneath it.
+
+### What was removed, and what each call site became
+
+`readUnion` and `UnionSubject` are gone from the entry. `packages/polyfill/src/surface/read-model.ts` is deleted; `packages/polyfill/src/surface/read-document.ts` replaces it with `readDocumentSubjects(doc)` — ONE anchored query, INTERNAL, `kind=invention` (the anchored query itself is `docs.sparqlQuery`, annotated there; what is ours is the cold-start open and the row grouping).
+
+- `index-deposit.ts` (two sites) — the `onUnreadable` callback became a `catch`; both still return `unreadable`, and `noRowsMeansAbsent` still consults `getSyncState`, which is why the `ensureRepoOpen` in front of the read cannot move to the caller.
+- `examples/notebook/app.ts`, `packages/polyfill/e2e/polyfill-entry.ts` — each composes its own read over the published `docs.sparqlQuery`. The two multi-document e2e sites carry a VISIBLE `catch` and report what they skipped.
+- Tests re-pointed, none deleted or weakened. `open-repo.test.ts` keeps its integration path onto `ensureRepoOpen` by the same route. `read-model.test.ts` → `read-document.test.ts`: three cases that tested the batch POLICY were re-pointed at what replaced it (a failed read throws; an empty document answers `[]`; two reads never merge), and the file header says which and why.
+
+### The per-document tolerance
+
+RELOCATED to the caller, not lost — and shedding it is an alignment gain, since upstream an anchored query on a repo the verifier does not hold rejects (`resolve_target_for_sparql` → `NgError::RepoNotFound`). No tolerant batch helper was introduced anywhere.
+
+### Two behaviour changes, both recorded in the contract
+
+1. A document the holder has no capability for is REFUSED out loud instead of dropped from a batch.
+2. Subjects under the reserved `urn:ng-eventually:` prefix are no longer filtered for an application. No rights move: the only registers an ordinary document carries are its inbox address and, for a public document, the key its store already serves to whoever asks; the cap-bearing `inboxCap` register lives in its owner's private store.
+
+### Does our emulation reject, or answer empty?
+
+VERIFIED: it REJECTS, and it does not swallow. `docs.sparqlQuery` has no `catch` — it forwards `ng.sparql_query`'s rejection unchanged — and `readDocumentSubjects` has none either. The swallow that existed was `readDoc` inside the deleted module. One nuance, pre-existing: for a document whose public-store cap fetch failed transiently, `fetchReadCap` returns `false` and the rejection that reaches the caller is this package's "you hold no cap", not the broker's outage. That conflation is documented in `public-store.ts` and is not introduced here.
+
+### Where `ng-helpers` cites `readUnion`
+
+In its OWN published `usage_ng-helpers.md` against `polyfill-surface`, under `## Consumed surface` and `## Needs` — not in any leaf of this repo, and not in `contract_ng-e2e-helpers.md` / `usage_polyfill-e2e.md`. The planner's grep was right about where it is NOT; the parent's claim that "`ng-helpers`' contract cites `readUnion`" was wrong about which document. Read through the declaration only, never their code.
+
+### Follow-ups (not fixed here)
+
+- `useShapeQuery` never opens the documents named in `scope.graphs`, so an application naming an unopened or public-store document gets an empty result with no error. Real, out of scope, probably deserves a `bug_` leaf in `app-contract`.
+- `ensureReposOpen` now has no production caller (only `open-repo.test.ts`). Internal dead code.
+- `examples/notebook/tsconfig.json` does not typecheck — PRE-EXISTING, verified against the branch tip before any edit: the hand-written `NoteShape` does not satisfy `ShapeType<BaseType>`.
+- The `ng-helpers` declaration still reports `1 passed / 29 failed`-era breakage and three Needs this removal does not answer; their `against:` pin is `1.0.0-dev.6` and the surface is now `1.0.0-dev.8`.
+- `.project/concepts/app-contract/_debt.md` carries markers for `orm.ts` and `use-shape-query.ts` raised before this task; left alone.
+- The dated `docs/briefs/` were deliberately not rewritten: they describe a July state that the documents themselves date.
+- The e2e suite was NOT run (it needs a live broker); it is not part of this task's gate.
+

.tasks/done/T01.g-adversarial-review-of-the-published-surface.md

@@ -0,0 +1,98 @@
+---
+id: T01.g
+title: Adversarial review of the whole published surface
+parent: T01
+depends_on: [T01.a, T01.b, T01.c, T01.d, T01.e, T01.f, T01.h, T01.i, T01.j, T01.k, T01.l, T01.m, T01.n]
+created: 2026-09-16
+claimed_by: adversarial-reviewer
+claimed_at: 2026-09-24
+blocked: false
+---
+
+## Description
+
+An adversarial pass over the **whole** published surface — every symbol exported from `packages/polyfill/src/index.ts`, not only the ones this batch touched — trying to **refute** the parent task's success criterion: *every published symbol either mirrors an SDK symbol in name, parameters and return, or carries a justified annotation*.
+
+**Method, in this order.** For each published symbol ask the two questions of `.project/rules/nextgraph/no-divergence-from-nextgraph.md` in their stated order: *does the target do this?* **first**, verified in `nextgraph-rs` or stated by its author; *would an application have to unlearn it?* second, and only to rank severity — never to authorise a divergence. Then, for the name and the shape (`.project/rules/nextgraph/surface-mirrors-the-sdk.md`): is this the target's own name, does the verb belong to something else upstream, is the parameter passed through or translated, is the return the SDK's.
+
+**Check every `@provenance` line against the CLAIM, not just against the tree.** Same granularity on both sides: a function may cite a function; a composition, a pipeline or a policy cites nothing at level 2 and must say so. *"The reference resolves"* is not *"the annotation is true"* — that is precisely how `readUnion` survived. Use the mechanism as T01.a left it, including whatever the new kind for an announced-but-unwritten target requires as evidence.
+
+**Known, and not findings.** The three open `bug_` leaves in `.project/concepts/app-contract/`: `bug_useshape-live-read-needs-a-newer-broker` (MAJOR), `bug_a-lost-inbox-watch-is-never-retried` (MAJOR), `bug_an-empty-inbox-list-can-mean-a-failure`. Do not re-report them as new. **Do** report it if a change in this batch altered their status, or invalidated a workaround they or the contract publish — the `useShape` bug leaf and the contract's `## Non-guarantees` both name `watchShape` and `readUnion` as the unaffected paths, and both were changed here.
+
+**Check the contract as delivered**, since three children edited it in sequence: `## Surface` matches the actual exports symbol for symbol; `## Change policy` records a version whose bump level follows the contract's own rules for what actually changed; no section was half-edited or edited twice for the same change; nothing published is left described by a sentence that is no longer true.
+
+**Findings are leads, not mandates, and this child fixes nothing.** A finding without a reproducible failure scenario or a checkable citation does not count. Report symptom, precise location (`file:line`, the failing assertion, the offending extract) and, where it is already known, the cause — but do not instrument, bisect or repair. Each fix is a new task.
+
+**Deliverable.** In `## Result`: findings by severity (blocking / major / minor), atomic, numbered `1.1`, `1.2`, … so they can be answered precisely. Neutral tone, no first or second person. One line of verdict on the test suites, not a list of what passes.
+
+**Pass condition for this child** (it writes no code): run `bun test`, `bunx tsc --noEmit -p packages/polyfill/tsconfig.json`, `bunx tsc --noEmit -p packages/polyfill/e2e/tsconfig.json` and `python3 ~/.claude/skills/concept/lint.py` to **establish** the delivered state and report it verbatim; the review covers every symbol exported from `packages/polyfill/src/index.ts`, with the ones found clean stated as a count rather than an inventory.
+
+## Progress
+
+## Result
+
+Read-only pass. Nothing in the delivered code was changed; one throwaway probe was run and deleted, and `git status` shows only this task file's own move.
+
+### Delivered state, measured
+
+- `bun test` -> `465 pass / 0 fail`, 1316 `expect()` calls, 40 files. MATCHES the figure on record.
+- `pnpm exec tsc --noEmit -p packages/polyfill/tsconfig.json` -> exit 0. MATCHES.
+- `pnpm exec tsc --noEmit -p packages/polyfill/e2e/tsconfig.json` -> exit 0. MATCHES.
+- `python3 ~/.claude/skills/concept/lint.py` -> **0 ERROR** (11 items across 4 WARNING classes). MATCHES.
+- `packages/polyfill/src/index.ts` carries **21** `export` statements. MATCHES. It **DIFFERS** on the symbol count: those 21 statements name **37** top-level names, of which 3 are namespace groupings (`docs`, `inbox`, `storeRegistry`), so the published surface as `test/provenance.test.ts:publishedSymbols` itself computes it is **53** (34 direct + 3 `docs` + 11 `inbox` + 5 `storeRegistry`), which is also exactly what `docs/api-contract.md`'s appendix lists. Not 25.
+- 123 `@provenance` annotations in `src`, covering the 53 published symbols plus 70 internal ones.
+
+### Blocking
+
+**1.1 The read filter on the published `useShape` is bypassed by the SDK version this repo builds against, and every identity's objects reach the caller out of the one shared wallet. PROVED.**
+
+`src/surface/use-shape.ts:14-17` hands whatever the injected hook returned to `makeReadFilteredView`. `read-filter.ts:179-180` passes any non-function member through untouched, on the header's stated ground that "a plain property carries no items".
+
+That ground held for `@ng-org/orm@0.1.2-alpha.18`, the version in the cited `nextgraph-rs` checkout: `sdk/js/orm/src/frontendAdapters/react/useShape.ts:123` ends `return state as DeepSignalSet<T>` - a bare set, whose item-yielding members are all functions the whitelist covers. It is FALSE of `@ng-org/orm@0.1.2-alpha.21`, which the `ANCHOR` calls the build and which is installed under `packages/polyfill/node_modules`: `dist/frontendAdapters/react/useShape.d.ts` declares the return `UseShapeResult`, an object carrying `data`, `promise`, `subscription`, `isLoading`, `nextPage`, `previousPage`. `data`, `promise` and `subscription` are plain PROPERTIES holding the items.
+
+Repro run against the delivered `read-filter.ts` and `caps.ts`, with a `CapRegistry` in which alice and bob each minted one document, `isEnforcing() === true`, and bob the current holder, over an object of exactly the shape `useShape.d.ts` declares:
+
+```
+alpha.18 shape -> iterated:                            [ "bob-own" ]
+alpha.21 shape -> .data items :                        [ "bob-own", "alice-private" ]
+alpha.21 shape -> .subscription.signalObject items:    [ "bob-own", "alice-private" ]
+alpha.21 shape -> await .promise items:                [ "bob-own", "alice-private" ]
+did anything throw? no.
+```
+
+The contract instructs exactly the injection that opens this: `docs/api-contract.md:50` reads `useShape: UseShapeLike;   // the REAL @ng-org/orm useShape`, and `contract_polyfill-surface.md:36` says the same. `EventuallyConfig.useShape` is not optional, so every application passes something, and `UseShapeLike = (...args: any[]) => any` (`src/model/types.ts:83`) accepts either return shape without a type error - which is why both typechecks stay at exit 0.
+
+Two published statements are falsified by the run. `contract_polyfill-surface.md:256`: "**No unfiltered read through `useShape`.** Members that yield items are filtered and mutations pass through; anything else throws" - nothing throws, and the unfiltered items come back on three separate properties. And `docs/api-contract.md:345`'s rationale for wrapping the ORM, "an unwrapped ORM read returns EVERY identity's data out of the shared wallet with nothing signalling it", describes the WRAPPED `useShape`'s current behaviour on this version.
+
+### Major
+
+**2.1 `@ng-org/orm` does not export `useShape` at the specifier the contract names. CONFIRMED.** The installed manifest maps `"."` to `dist/core.d.ts`, and `core.d.ts` exports `initNg`, `ngSession`, `RdfOrmSubscription`, `DiscreteOrmSubscription`, `insertObject`, `removeObject`, `getObjects`, the `types.ts` re-export and three `alien-deepsignals` members. No `useShape`. The hook is at `@ng-org/orm/react` (also `/svelte`, `/svelte4`, `/vue`), or as `reactUseShape` from `@ng-org/orm/all`. An application following `contract_polyfill-surface.md:36` or `docs/api-contract.md:50` literally fails to resolve the import. Note the neighbouring claim that IS correct and was checked: `index.ts:162`'s reason for taking `RdfOrmConfig` from `/all` holds, since `core.d.ts` really does not carry it.
+
+**2.2 Four present-tense claims that the SDK's `useShape` returns a bare `DeepSignalSet` are false of the version built against, and two of them are the stated ground of a provenance ruling. CONFIRMED.** The claim is at `src/model/types.ts:124`, `src/surface/use-shape-query.ts:11` and `:33`, and `contract_polyfill-surface.md:234` ("`useShape` returns a set you cannot tell from an empty one"). In `alpha.21` the return carries `isLoading` and `promise`. The two that are load-bearing:
+
+- `src/surface/use-shape-query.ts:284`, the `announced-not-written` annotation, whose note reads "the SDK ships `useShape` returning a bare `DeepSignalSet`; the announced direction is a `useShapeQuery` returning a TanStack-shaped snapshot". The premise is false of what the SDK ships; the shipped hook already returns a load-state-carrying object.
+- `src/surface/use-shape-query.ts:193`, `ShapeQuery kind=invention level=none ref=none`, whose note opens "no upstream type carries load state". `UseShapeResult.isLoading` is an upstream load state at level 3. `ref=none` and `level=none` assert that nothing answers at any level.
+
+This is the failure mode the mechanism exists to catch, in its documented form: the citations resolve, and the claims attached to them do not hold at the version a consumer compiles against. `test/provenance.test.ts` cannot see it by construction (it pins that a claim was made, not that it is true), and the `ANCHOR`'s own comment predicted this class of error.
+
+**2.3 The one gate that exercises the published `useShape` against a live broker injects a hand-written substitute rather than the SDK's hook, which is why 1.1 is green. CONFIRMED.** `packages/polyfill/e2e/orm-live-entry.ts:101-105` defines `realOrmUseShape` as `RdfOrmSubscription.getOrCreate(...)` returning `sub.signalObject`, and `:109` injects that. The file's header states the substitution and its reason ("without a React tree to mount"). The state it fabricates - a hook returning a bare set - is the one `alpha.21` no longer produces, so the suite measures the `alpha.18` shape exclusively. Every unit fake does the same (`test/orm-fake.ts`, `e2e/polyfill-entry.ts:191`).
+
+### Minor
+
+**3.1 Two published types have no published signature using them, against the entry's own rule. CONFIRMED.** `src/index.ts:78` states "A type is published only when a PUBLISHED SIGNATURE uses it", and `:87-96` enumerates the warrants. `Schema` (`index.ts:149`) appears in no signature anywhere: `grep -rn "\bSchema\b"` over the working copy outside `node_modules` returns only its own export line, its annotation, and three document copies of that line. `DeepSignalSet` (`index.ts:151`) appears in `src` only inside prose and one annotation, never in a type position; no published signature returns one, since `useShape` returns `unknown`. This is the defect for which `ReadCap` and `InboxScope` were unpublished on 2026-08-10, with the rationale still at `index.ts:79-86`.
+
+**3.2 Seven published symbols carrying `kind=invention level=none ref=none` sit under the block headed "a target counterpart for every symbol". CONFIRMED.** `src/index.ts:45-46` heads the first block "SDK-SHAPED - a target counterpart for every symbol / At migration the build alias is removed and these resolve to the real SDK", and `:166-169` heads the second "POLYFILL-ERA - THE DELETION LIST / nothing below has a target counterpart". Exported above the divider and annotated `invention`, which the taxonomy defines as "nothing at any level answers": `NgLike`, `UseShapeLike`, `OrmSubscriptionLike`, `GetObjectsLike`, `InsertObjectLike` (`:111-120`) and `ShapeQuery`, `ShapeObservable` (`:123`). The five `...Like` types are used by exactly one published signature each, all of them fields of `EventuallyConfig`, which is itself on the deletion list. `docs/api-contract.md:822` states the matching count as "exactly ONE is polyfill-era with no target counterpart".
+
+**3.3 A published function is absent from the contract's `## Surface`. CONFIRMED.** `docChangeType` is exported at `src/index.ts:132` and listed in the appendix, and `contract_polyfill-surface.md`'s `## Surface` block shows only the type `DocChangeType`, inside the two `subscribeDoc` signatures (`:97-98`). Nothing pins that block: `test/vocabulary.test.ts` checks `docs/api-contract.md`, never the concept leaf.
+
+**3.4 A stale annotation claims a published namespace name for an internal symbol. CONFIRMED.** `src/shared-wallet/account-registry.ts:971` annotates `storeRegistry.resolveScopeGraph`, and the format's own rule (`test/provenance.test.ts:22-24`) reserves the qualified form for a published namespace member. `resolveScopeGraph` was unpublished in `1.0.0-dev.5` (`src/surface/placement.ts:135,144`; `contract_polyfill-surface.md:325`), `surface/placement.ts` does not re-export it, and it is absent from the 53-symbol set `publishedSymbols()` computes.
+
+### Found clean
+
+**41 of the 53 published symbols** were walked against `nextgraph-rs` or the installed `.d.ts` and faulted on nothing. The 12 named above are `useShape`, `useShapeQuery`, `ShapeQuery`, `ShapeObservable`, `Schema`, `DeepSignalSet`, `docChangeType`, `NgLike`, `UseShapeLike`, `OrmSubscriptionLike`, `GetObjectsLike`, `InsertObjectLike`.
+
+Checked and HOLDING, listed only because each was a plausible refutation that failed: `getObjects` and `insertObject` mirror `alpha.21`'s declared signatures exactly, including `Omit<RdfOrmConfig<T>, "pageSize" | "maxActivePages">`, and their `passthrough` notes disclose the filter and the guard; `RdfOrmConfig`'s `/all` subpath justification is true of the installed manifest; `Scope` is genuinely on `core.d.ts` via `export * from "./types.ts"`; `ng`, `NG`, `init`, `initNg`, `subscribeDoc`, `subscribeDocs`, the three `docs` members, the eleven `inbox` members and the five `storeRegistry` members carry annotations whose claims match their code. `## Change policy` records `1.0.0-dev.10`, which `packages/polyfill/package.json:3` pins, and its "Nothing is added, renamed or removed from the entry" is true: `git diff de9b8a0..HEAD -- packages/polyfill/src/index.ts` moves no `export` line.
+
+### Verdict on the suites
+
+Green as delivered and reproduced verbatim above, and 1.1 shows the green is not evidence: no fake in `test/` or `e2e/` returns the shape the installed SDK returns, so the suites exercise a hook shape that `@ng-org/orm@0.1.2-alpha.21` does not produce.

.tasks/done/T01.h-refresh-the-nextgraph-packages.md

@@ -0,0 +1,95 @@
+---
+id: T01.h
+title: Refresh the NextGraph packages to their latest published versions
+parent: T01
+depends_on: [T01.f]
+created: 2026-09-21
+claimed_by: T01.h-worker
+claimed_at: 2026-09-21T14:17:00+02:00
+blocked: false
+---
+
+## Description
+
+Once the surface work is done, bring `@ng-org/web`, `@ng-org/orm`, `@ng-org/shex-orm` and `@ng-org/alien-deepsignals` to their latest published versions, in BOTH workspace packages, and reconcile whatever the update surfaces.
+
+**Why this is its own task and not a chore.** The 2026-09-21 update from `alpha.13/19/8/11` to `alpha.14/21/9/13` was expected to be routine and was not: it revealed that `orm_start_graph` had gained a sixth parameter (`config`, before the callback), which is exactly what a live measurement had observed against the deployed broker and attributed to the deployment being ahead. It also renamed `OrmSubscription` to `RdfOrmSubscription`, made `Scope.graphs` required, and — through a clean reinstall — exposed that six e2e files imported `ng-e2e-helpers` without the polyfill declaring it. An update against this SDK is a source of findings, so it gets a task and a gate.
+
+**What to do.** Check the published version of each of the four packages. Bump them in `packages/polyfill/package.json` and `packages/ng-e2e-helpers/package.json` together, so no two versions of a package with module-level state coexist in the tree — that duplication is the single-instance hazard the polyfill's own contract names. Reinstall with pnpm (`CI=true pnpm install --no-frozen-lockfile` when the lockfile has drifted), then read what the typechecks and the suites say rather than assuming the update was invisible.
+
+**Then verify against the real broker**, not only by typecheck: run `packages/polyfill/e2e/orm-live-read.ts` and the polyfill e2e suite. A signature that matches at compile time can still disagree with the deployment.
+
+**Record what the update revealed.** If it changes a fact already written in a doctrine leaf — an arity, a symbol name, a type's optionality — fix the leaf in the same pass. A stale fact in doctrine is worse than an absent one.
+
+## Progress
+
+## Result
+
+Status: done
+
+### The four version moves: NONE. All four were already at their latest published version.
+
+| package | declared before | latest published | moved |
+|---|---|---|---|
+| `@ng-org/web` | `0.1.2-alpha.14` | `0.1.2-alpha.14` | no |
+| `@ng-org/orm` | `0.1.2-alpha.21` | `0.1.2-alpha.21` | no |
+| `@ng-org/shex-orm` | `0.1.2-alpha.9` | `0.1.2-alpha.9` | no |
+| `@ng-org/alien-deepsignals` | `0.1.2-alpha.13` | `0.1.2-alpha.13` | no |
+
+VERIFIED three ways: the `latest` dist-tag from a direct uncached `registry.npmjs.org` fetch, the full version list, and `pnpm outdated` (reports nothing for `@ng-org/*` in either workspace package). No `package.json` was touched, and nothing was pinned back - there was simply nothing newer to move to. The refresh this task was written for had already happened, earlier the same day, inside T01.d.
+
+**The `0.1.2` trap.** Three of the four (`web`, `shex-orm`, `alien-deepsignals`) also publish a bare `0.1.2`, which semver ranks ABOVE every `0.1.2-alpha.N`. It is a legacy release from 2025-10/2025-12; the alphas are from 2026. "Upgrading" to it would go back roughly a year. The exact pins in the `devDependencies` are what keep it out. `ng-e2e-helpers` declares the peer range `"@ng-org/web": ">=0.1.2-alpha.13"`, which DOES admit `0.1.2` - latent, since a peer is not auto-installed, but it is the one declaration in the tree that would accept the regression.
+
+### Breaking changes surfaced, and how each was reconciled
+
+The version bump surfaced none, because there was none. The install DID surface one thing, and the doctrine audit surfaced the rest.
+
+1. **The tree was bun-installed, not pnpm-installed.** Every `@ng-org` symlink under both workspace packages pointed into `node_modules/.bun/`, and that store still held `web@alpha.13`, `shex-orm@alpha.8` and `alien-deepsignals@alpha.11` beside the current ones. The resolved versions were correct, so the single-instance hazard was latent rather than active. Reconciled by `CI=true pnpm install --no-frozen-lockfile`, which re-pointed every symlink into `.pnpm/`. The lockfile did not move ("Lockfile is up to date"). The dead `.bun` store was left in place - it is an untracked artifact, and removing it was not asked for.
+
+2. **The doctrine's citation anchor is three orm releases behind the installed package.** This is the finding of the task. The pinned `nextgraph-rs` checkout `213338f6` declares orm `alpha.18` / web `alpha.13` / shex-orm `alpha.8` / alien-deepsignals `alpha.11`, while `packages/polyfill` compiles against `alpha.21/14/9/13`. Every leaf citing `sdk/js/orm/src/...` therefore describes a version this repo no longer uses. Reconciled by naming BOTH anchors wherever they disagree, rather than rewriting citations that would then be false for the commit they point at.
+
+### The four gates, verbatim
+
+- `bun test` -> `424 pass`, `0 fail`, `1162 expect() calls`, `Ran 424 tests across 39 files.` Baseline before any change was identical (`424 pass / 0 fail`), matching the figure recorded on this task.
+- `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` (warnings only; the `broken [[...]] links - 1` warning present at baseline is now GONE)
+
+### The live measurements, against the real broker
+
+- `packages/polyfill/e2e/orm-live-read.ts` -> `ORM live-read summary: 5 passed, 0 failed, 5 declared - run 0.6 min`. The read is ready in 13ms and the delete reached the document. `5 declared` and not the `6` in the parent digest because the characterisation row was retired with the question it answered - the runner's own header records that, so this is not a lost row.
+- `packages/polyfill/e2e/run.ts` -> `Polyfill e2e summary: 43 passed, 0 failed, 43 total - batch 3.2 min, slowest cold sync 26s`.
+
+### Doctrine leaves corrected, and the false fact each carried
+
+`app-contract/knowledge_what-the-orm-writes-and-deletes-upstream.md`
+- announced `orm@alpha.19 / web@alpha.13 / alien-deepsignals@alpha.11` as installed - all three wrong
+- "`core.ts` exports exactly `initNg, ngSession, OrmSubscription, DiscreteOrmSubscription, insertObject, getObjects`" - alpha.21 renames `OrmSubscription` to `RdfOrmSubscription` AND adds `removeObject`, so "exactly" was false
+- `getOrCreate(shapeType, scope)` - alpha.21 takes an `RdfOrmConfig` (`Scope & {where?, orderBy?, pageSize?, maxActivePages?}`), and the instance gained `mode`, `isReady`, `addChangeListener`, `removeChangeListener`, `nextPage`, `previousPage`
+- "a live ORM read still does not start against the deployment" - false, measured 5/5 today
+- `[[bug_useshape-live-read-needs-a-newer-broker]]` - dangling, the leaf was deleted by the previous refresh
+
+`app-contract/knowledge_what-a-read-scope-is-upstream.md`
+- "`Scope = { graphs?: ... }`" - `graphs` is REQUIRED in alpha.21; a caller that omitted it no longer compiles
+- "`[]` or `undefined` returns no objects at all", stated of the type as a whole - true of `graphs`, FALSE of `subjects`, where `[]` means no filtering. Now a two-row table, because this is the trap the repo has already paid for once
+- `OrmSubscription` / `connector/GraphOrmSubscription.ts` - both symbol and file renamed in alpha.21
+
+`e2e-harness/knowledge_what-each-suite-judges.md`
+- "It is EXPECTED to exit non-zero while the deployed broker and the published client packages disagree" plus a pointer to the deleted bug leaf - the runner is green now, and a red run means they have drifted apart again
+
+`contract_polyfill-surface.md` was checked and needed nothing: it already records `removeObject` at alpha.21 and the 2026-09-21 catch-up correctly.
+
+### The three out-of-scope follow-ups: none got worse
+
+- (a) `useShapeQuery` opens nothing named in `scope.graphs` - unchanged, scope still passed through untouched
+- (b) `ensureReposOpen` dead - unchanged, still called only from its own test file
+- (c) `examples/notebook/tsconfig.json` - still exactly `1 error TS2345`, the same `ShapeType` structural mismatch. Not worse
+
+### Surprises
+
+- **The task's premise did not hold: there was nothing to update.** VERIFIED. The work turned out to be the reconciliation half - the previous refresh moved the packages and left the doctrine behind.
+- **The pinned source checkout is behind the installed packages.** VERIFIED (`nextgraph-rs` at `213338f6` declares orm `alpha.18`). This weakens every source citation in the concept leaves, and it is the structural version of the trap this task names: a fact read at the cited source can disagree with the package the code actually compiles against, exactly as a compile-time signature can disagree with the deployment.
+- **`removeObject`'s own documentation contradicts itself.** VERIFIED from `connector/removeObject.d.ts`: it declares `DELETE WHERE { GRAPH <g> { <s> ?p ?o } }` - every predicate of the subject - while claiming in the same comment to have "the same effect" as a `delete()` on a subscription's object, which removes only the SHAPE's predicates. Nothing in the cited source settles which holds. Recorded in the leaf; it stays unpublished, per T01.e.
+- **I nearly wrote a new false fact while fixing false facts.** I first wrote that alpha.21's `where`/`orderBy`/`pageSize` "became reachable from level 3". INFERRED from the JS surface alone, and the pinned engine refutes it: `Verifier::start_orm` still builds `OrmConfig::from_json(&json!({}))` behind a `// TODO`. Corrected before committing to say the richness is expressible at level 3 and discarded at level 1, and that measuring it is not done here.
+- `playwright` is outdated in `ng-e2e-helpers` (`1.61.1` -> `1.63.0`). Out of scope - not one of the four packages. Reported, not touched.
+- `pnpm-workspace.yaml` lists only `packages/*` while the root `package.json` `workspaces` also lists `examples/*`, so `examples/notebook` is outside pnpm's scope entirely. VERIFIED (`pnpm install` reports "all 3 workspace projects"). Plausibly related to follow-up (c); not investigated, not touched.

.tasks/done/T01.i-two-leftovers-from-the-removal.md

@@ -0,0 +1,74 @@
+---
+id: T01.i
+title: Clear two mechanical leftovers from the removal
+parent: T01
+depends_on: [T01.h]
+created: 2026-09-21
+claimed_by: worker-agent
+claimed_at: 2026-09-21
+blocked: false
+---
+
+## Description
+
+Two small, independent leftovers reported by T01.f. Neither carries a design question; if one turns out to, stop and report rather than deciding it here.
+
+### 1. Remove `ensureReposOpen`, now dead
+
+T01.f removed its last caller. VERIFY that with a grep across `packages/`, `examples/` and `e2e/` before deleting - if a caller survives, leave it and say so. `ensureRepoOpen` (SINGULAR) is NOT dead, it is on the live path, and must stay.
+
+### 2. Make the example typecheck
+
+`examples/notebook/tsconfig.json` fails typecheck. T01.f reports this as pre-existing and verified as such. The owner has asked for the example to be repaired.
+
+**A strong lead on the cause, found by T01.h and VERIFIED independently: `examples/notebook` is outside pnpm entirely.** The root `package.json` `workspaces` field lists `packages/*` AND `examples/*`, but `pnpm-workspace.yaml` lists only `packages/*`. So pnpm never installs the example's dependencies, and that is the likely reason its single `error TS2345` stands. Check this FIRST. If adding `examples/*` to `pnpm-workspace.yaml` is the repair, make it and re-run the whole gate - bringing a package into the workspace can move resolutions for everyone, which is exactly the single-instance hazard this repo watches for, so verify no `@ng-org` package ends up duplicated.
+
+Make it typecheck WITHOUT weakening the configuration. If the only way through is to loosen a compiler option, disable a check, or annotate a real type error away, STOP and report - that is a finding, not a repair. The example exists to be the honest demonstration of what an application writes, so an example that only compiles because the rules were relaxed for it is worse than one that does not compile.
+
+### 3. Remove the dead bun store
+
+`node_modules/.bun` is still on disk, holding OLD versions of `@ng-org/web`, `@ng-org/shex-orm` and `@ng-org/alien-deepsignals` beside the current ones. It is inert right now - T01.h re-installed with pnpm and every symlink resolves correctly - but a future `bun install` in this tree would re-point symlinks back into that stale store, which is the single-instance hazard arriving silently. Delete the directory, and if there is a cheap way to keep it from coming back (a note in the README's setup section, a package manager declaration), do the cheap thing and say what you did. Do NOT build tooling for it.
+
+**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; the example's own typecheck -> exit 0; `python3 ~/.claude/skills/concept/lint.py` -> 0 ERROR. Anti-cheat: no `any`, no `@ts-ignore`, no `as unknown as`, no deleted or skipped test, no weakened assertion, no loosened compiler option.
+
+## Progress
+
+- Item 1 (ensureReposOpen): VERIFIED dead by grep (only its own definition, its own provenance comment, a historical doc comment in use-shape-query.ts, and its dedicated test describe block). Deleted the function from open-repo.ts. In open-repo.test.ts, deleted the 3 tests that called ensureReposOpen directly; kept and moved the 4th test ("the anchored document read triggers doc_subscribe...") under the ensureRepoOpen describe block, since it exercises readDocumentSubjects/ensureRepoOpen, not the deleted function. Commit 51b6278.
+- Item 2 (example typecheck): VERIFIED the pnpm-workspace.yaml lead independently (examples/notebook absent from pnpm-lock.yaml entirely; ran on a stray hand-made node_modules symlinked into node_modules/.bun, including a dangling @ng-eventually/sdk link to a package that no longer exists). Added examples/* to pnpm-workspace.yaml and reinstalled (CI=true pnpm install --no-frozen-lockfile). BUT this did not by itself fix the TS2345 - see Result for actual cause. Fixed app.ts's NoteShape by adding `satisfies ShapeType<BaseType>` (types re-exported by @ng-eventually/polyfill already), matching the existing pattern in packages/polyfill/test/use-shape-query.test.ts. Commit 2dc2896.
+- Item 3 (dead bun store): deleted node_modules/.bun. Found and removed the actual recurrence trigger: bun.lock was TRACKED in git (gitignore only listed the older bun.lockb), so a future `bun install` would happily use it. Removed the tracked bun.lock, added both bun.lock and bun.lockb to .gitignore, and added `"packageManager": "pnpm@10.26.0"` to package.json. Commit ee82a4a.
+
+## Result
+
+Status: done
+
+All three items completed. Branch caps-p1a-and-virtual-user-boundary, commits 51b6278, 2dc2896, ee82a4a.
+
+### 1. ensureReposOpen - done
+Grepped packages/, examples/, e2e/ (no top-level e2e/ dir exists; packages/polyfill/e2e checked). No production caller anywhere (VERIFIED); the plural form's only occurrences were its own definition, its own @provenance comment, a historical doc-comment mention in use-shape-query.ts (describing an already-replaced mechanism, left untouched - not a live claim), and its own dedicated test block. Deleted the function. In open-repo.test.ts, 3 of the 4 tests in `describe("ensureReposOpen", ...)` called the deleted function directly and were deleted with it; the 4th ("the anchored document read triggers doc_subscribe then returns data (integration path)") calls `readDocumentSubjects`, not ensureReposOpen - kept, moved under `describe("ensureRepoOpen", ...)` where it actually belongs. `ensureRepoOpen` (singular) untouched.
+
+### 2. Example typecheck - done
+**Actual cause, VERIFIED empirically (not the hypothesized one):** the TS2345 was a plain TypeScript literal-widening bug in app.ts's own `NoteShape` object literal - `dataTypes[].valType: "iri"` / `"string"` widened to plain `string` because the const had no `satisfies ShapeType<BaseType>` clause. Proven by fixing ONLY this (importing the already re-exported `ShapeType`/`BaseType` from `@ng-eventually/polyfill`) with pnpm-workspace.yaml untouched: typecheck passed (exit 0) immediately, using the pre-existing stray bun-store-backed node_modules. The pnpm-workspace.yaml omission (VERIFIED: examples/notebook was entirely absent from pnpm-lock.yaml) was a real, separate problem, not the cause of THIS error - but fixing it was still necessary for coherence with item 3 (examples/notebook's node_modules symlinked directly into node_modules/.bun, which item 3 deletes). Did both.
+
+**Did the workspace change move any resolution / duplication check:** No. Before: `.pnpm` store held @ng-org/orm@0.1.2-alpha.21, @ng-org/web@0.1.2-alpha.14 (+ a pre-existing, already-orphaned @ng-org/web@0.1.2-alpha.13 with zero referencing symlinks anywhere, unrelated to this change - not touched). After adding examples/* and reinstalling: identical set of `.pnpm` store directories, zero new entries. examples/notebook/node_modules/@ng-org/{orm,web} now symlink into the exact same node_modules/.pnpm/@ng-org+... paths that packages/polyfill uses (checked directly). No @ng-org/* package ended up duplicated. VERIFIED.
+
+### 3. Dead bun store - done
+Deleted node_modules/.bun (88M). Every symlink in the tree already resolved through node_modules/.pnpm (checked before deleting) so nothing broke. Cheap recurrence guard: found bun.lock was tracked in git (the .gitignore only listed the old bun.lockb, so this newer text-format lockfile had slipped through) - removed it from git and added both bun.lock and bun.lockb to .gitignore, and added `"packageManager": "pnpm@10.26.0"` to package.json. No tooling built.
+
+### Gate (verbatim, run after all three commits)
+- `bun test` -> `421 pass / 0 fail` (baseline 424 pass/0 fail minus the 3 ensureReposOpen-only tests deleted with the dead function = 421; matches exactly)
+- `bunx tsc --noEmit -p packages/polyfill/tsconfig.json` -> EXIT=0
+- `bunx tsc --noEmit -p packages/polyfill/e2e/tsconfig.json` -> EXIT=0
+- example's own typecheck (`cd examples/notebook && bunx tsc --noEmit -p tsconfig.json`) -> EXIT=0
+- `python3 ~/.claude/skills/concept/lint.py` -> 0 ERROR (5 pre-existing WARNINGs, none introduced by this task, none blocking)
+
+Anti-cheat: no `any`, no `@ts-ignore`, no `as unknown as`, no test deleted to dodge a failure (the 3 removed tests tested the function being intentionally deleted, not a workaround), no weakened assertion, no compiler option touched.
+
+### Surprises
+- INFERRED->VERIFIED-FALSE: the task's "strong lead" that pnpm-workspace.yaml's examples/* omission was "the likely reason" for TS2345 - independently disproven; root cause was the missing `satisfies` clause. The workspace omission was still real and worth fixing (VERIFIED via absence from pnpm-lock.yaml) for reasons independent of this specific error.
+- VERIFIED: examples/notebook/node_modules had a dangling symlink `@ng-eventually/sdk -> ../../../../packages/sdk` - packages/sdk does not exist in this tree at all, and nothing in examples/notebook imports @ng-eventually/sdk. Pure fossil from the stray hand-made install; gone now that pnpm manages the folder.
+- VERIFIED: a second @ng-org/web version (0.1.2-alpha.13) sits in node_modules/.pnpm with zero referencing symlinks anywhere - pre-existing orphan store entry, inert, unrelated to this task's three items. Left alone (pruning the pnpm store was not asked for).
+
+### Found but left alone (out of scope)
+- docs/internal-contract.md section 6 (open-repo.ts internal export inventory) is already stale independent of this task: wrong line numbers throughout, and it lists `ensurePhysicalRepoOpen` as an export of open-repo.ts, which does not exist under that name in the current file (only referenced in comments). It also now additionally lists the just-deleted `ensureReposOpen`. Did not touch this doc - the drift is broad and pre-existing, a full fix is out of scope for T01.i.
+- docs/api-contract.md and use-shape-query.ts's doc-comment both mention `ensureReposOpen` by name, but only as history ("Four steps went with the change" - i.e. already replaced before this task). Left as-is, not misleading.
+- Did not touch anything under T01.j's territory (fetchReadCap, useShapeQuery's scope.graphs handling) - only read use-shape-query.ts's top doc-comment for context, made no edits there.

.tasks/done/T01.j-a-failure-must-not-read-as-an-absence.md

@@ -0,0 +1,309 @@
+---
+id: T01.j
+title: A read that cannot reach its document must fail, not answer empty
+parent: T01
+depends_on: [T01.i]
+created: 2026-09-21
+claimed_by: T01.j-worker
+claimed_at: 2026-09-21T14:45:49+02:00
+blocked: false
+---
+
+## Description
+
+A read whose document is unreachable currently answers an EMPTY SUCCESS. It must answer a failure. This is the "failure disguised as an absence" family, which this repo has closed roughly eight times and still carries two open `bug_` leaves for. Study it properly before changing anything: the facts below are established, the DESIGN is not.
+
+### The established facts - do NOT re-derive them, and do NOT read `nextgraph-rs` for them
+
+**Upstream (VERIFIED).** An anchored SPARQL query on a repo the verifier does not know REJECTS. The deciding line is `engine/verifier/src/request_processor.rs:269`: `let repo = self.repos.get(repo_id).ok_or(NgError::RepoNotFound)?;` inside `resolve_target_for_sparql`. It crosses into JS as a REJECTED PROMISE carrying the string `"RepoNotFound"` (`sdk/js/lib-wasm/src/lib.rs:403` nodejs, `:606` browser). The observable partition upstream is "in `self.repos`" vs "not in `self.repos`": "does not exist" and "exists but this session does not know it" are INDISTINGUISHABLE, while "known but unsynced" collides with "genuinely empty". There is NO read-capability check anywhere on that path - `resolve_target_for_sparql` reads only `nuri.target`.
+
+**Our chain, three layers (VERIFIED by reading this working copy).**
+
+- `fetchReadCap` (`packages/polyfill/src/emulated-verifier/public-store.ts:190`) returns a `boolean` collapsing three unrelated situations: the emulation is not in force (`:196`), the network could not be asked (`:223`), the document exposes no cap (`:225`). Its own comment at `:220` states the collapse out loud. `downloadReadCap`, directly below, DELIBERATELY distinguishes resolving from rejecting and documents why - so the distinction is produced and then destroyed one line later. And NO caller reads the boolean: `ensureRepoOpen:208`, `docs.sparqlQuery:155`, `branch-registers.ts:316`, `fetchReadCaps:277` all call it as a bare statement.
+- The read then proceeds on a document that was never opened.
+- `useShapeQuery` answers `isSuccess` holding zero objects.
+
+**What the target says the answer should be.** `useShapeQuery`'s return type is modelled on TanStack Query's `useQuery`, which distinguishes purely by whether the query function REJECTS: a rejection gives `isError` with the error; a resolution gives `isSuccess` with whatever data, empty included. That maps exactly onto upstream's `RepoNotFound`. So an unreachable document must surface as `isError`, and `isSuccess` with zero objects must mean "it is there and it holds nothing".
+
+### The design is yours to establish, and the enumeration comes FIRST
+
+Do NOT start from a preferred shape. `.project/rules/nextgraph/no-divergence-from-nextgraph.md` and `polyfill-must-match-the-target` both apply, and so does the discipline of listing the cases before concluding - this repo has a recorded incident of deciding from one convenient case and having to be dragged back row by row.
+
+**List the callers and their states before choosing anything.** For each of the four call sites above: what is it doing, what does it already hold, and what should it do when the cap cannot be obtained? Include the INERT case - before the first cap exists the emulation deliberately does not enforce, and reading works anyway; whatever you build must stay inert there or it will break every early path.
+
+**The constraint that shapes the answer.** `fetchReadCap` has NO upstream counterpart - upstream never consults a capability on the read path. So there is no SDK signature to mirror, and the cascade goes to the ENGINE'S MODEL: upstream's observable is that a read REJECTS or it does not. That is an argument about where the distinction should become visible, not a licence to invent a rich vocabulary of outcomes that the target does not have. Weigh it; do not treat this paragraph as the decision.
+
+**Re-examine the reverted barrier on its own merits.** `useShapeQuery` opens nothing named in `scope.graphs` - the barrier was removed by T01.d. A fix was written during T01.f and REVERTED, because it had been justified as unblocking `readUnion`'s removal, which was FALSE (an index is read by anchor, not by shape). The revert killed a bad JUSTIFICATION, not a bad change. The defect is real and unowned: an application that names an unopened document gets an empty success. Decide it fresh, on the enumeration.
+
+**Check the two open bug leaves** (`bug_a-lost-inbox-watch-is-never-retried`, `bug_an-empty-inbox-list-can-mean-a-failure`). They are the same family. State whether this work closes either. Do NOT claim it does without a test that proves it - a bug leaf deleted on a plausible argument is worse than one left open.
+
+### Blast radius - this is a behaviour change applications see
+
+Reads that silently answered empty will start failing. That is the POINT, and it is also how this breaks callers that were quietly relying on the silence. So: the published contract at `.project/concepts/app-contract/polyfill-surface/contract_polyfill-surface.md` must state the new behaviour, with a version bump per its own `## Change policy` (a call that narrows is a MAJOR). Follow the existing pre-release scheme, do not invent one. Expect internal callers and tests to surface real breakage - each one is a case to understand, never a reason to soften the change.
+
+**Record the durable fact** in `.project/concepts/app-contract/` as a `knowledge_` leaf: what the target answers for an unreachable, an unsynced and an empty document, and which of those a caller can tell apart. That fact is worth keeping whatever the fix turns out to be. Do NOT open a `bug_` leaf for something this task repairs.
+
+### One incidental repair, since you are in this territory anyway
+
+`docs/internal-contract.md`'s `open-repo.ts` section is stale: wrong line numbers, it names a non-existent `ensurePhysicalRepoOpen` export, and since T01.i it also names the deleted `ensureReposOpen`. Correct what that section says about the functions you touch. Do NOT undertake a general sweep of that document - the drift is broad and pre-existing, and fixing all of it is not this task.
+
+### Verification
+
+**The e2e must run.** Unit tests cannot judge this: the whole subject is what happens when the network does not answer. Run the polyfill e2e suite and report its counts verbatim. If the broker is unreachable, report the suite as UNRUN - never substitute a typecheck for the measurement.
+
+**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 `as unknown as`, no deleted or skipped test, no weakened assertion. Specifically forbidden here: catching the new failure somewhere upstream to keep an old test green - if a test breaks, it is telling you something.
+
+**An adversarial review is part of this task, not optional.** When the work is done, it goes to a fresh reviewer mandated to REFUTE it, on at least these angles: a path where the failure is still swallowed; a path where the change now fails something that legitimately has nothing (an empty document must still be a SUCCESS); and the inert case. A finding counts only with a concrete failure scenario. Re-run the adversary on whatever you fix in response.
+
+## Progress
+
+### The enumeration, written before any code
+
+Every row was read in this working copy. `fetchReadCap` reaches the network only when `caps.isEnforcing()` AND `caps.capFor(doc) === undefined` - held or inert, it answers without asking, so most rows below are already unaffected by whatever the network does.
+
+**Site 1 - `ensureRepoOpen(nuri, holderKey?)`, `open-repo.ts:209`.** Doing: bringing a repo into the session before an anchored read (the cold-start heal), asking the public store first so a bare reference to a public document suffices. Holds: the nuri. Asks only when `holderKey === undefined`. Today, when the cap cannot be obtained: `fetchReadCap` answers `false` exactly as if the document exposed none, `mustNotAttempt` is then true, and the function returns SILENTLY. Its eight live callers (`readDocumentSubjects`, `readUserStore`, `restoreOwnCaps`, `readInboxCapPairs`, `readLinks`, `inbox.readSynced`, `inbox.readSyncedForDocument`, `inbox.processInbox`) all read straight afterwards, so the failure does surface - as `assertMayReach`'s "the connected user does not hold this document's cap", which is the WRONG reason and calls for the wrong action (give up, rather than retry). Should: propagate. INERT: returns before any round-trip, `mustNotAttempt` false, the open proceeds - unchanged. Note the six callers reading their own store/inbox hold that cap already, so they never ask at all.
+
+**Site 2 - `docs.sparqlQuery`, `docs.ts:155`** (published). Doing: the anchored read itself; the ask is what makes a bare reference to a public document readable. Today: `false`, then `assertMayReach` throws the same wrong reason. A failure, but mislabelled. Should: reject, with the true reason. INERT: no ask, `mayReach` true, the read proceeds - unchanged.
+
+**Site 3 - `documentInboxAddress(doc)`, `branch-registers.ts:317`.** Doing: reading a document's Header branch for its inbox address - the question a third party arrives with holding nothing but the reference. Today: `false` -> `mustNotAttempt` -> returns `undefined`, which means "this document has no inbox". `inbox.postToDocument` renders that as "its owner never opened one"; `inbox.readForDocument` / `readSyncedForDocument` render it as zero deposits. **This is the pure failure-as-absence, on a published call, in both directions.** The same function carries a SECOND one: the `try/catch` around the address query returns `undefined` for a broker that did not answer - the comment beside it justifies the catch by a refusal that `mustNotAttempt` has already excluded one line above, so what it actually swallows is breakdowns. Both repaired. Should: propagate; `undefined` keeps meaning "no inbox", which is an answer. INERT: unchanged.
+
+**Site 4 - `fetchReadCaps(docs)`, `public-store.ts:277`.** Doing: the batch form, `Promise.all` over the singular with a tolerance of its own. Holds: nothing. **Zero callers** - grep-verified across `src`, `test` and `e2e`, and it is not exported from `src/index.ts`. Should: deleted, on T01.i's own precedent for `ensureReposOpen`. Leaving it would leave an unowned batch policy over a call that now rejects.
+
+**Site 5, the one that is not a `fetchReadCap` call site - `useShapeQuery`** (published). It asks nothing and opens nothing since T01.d. Doing: one shape in one SDK `Scope`, read through `RdfOrmSubscription`. Holds: `scope.graphs`, which NAMES documents. Today, for a named document whose cap is not held: the ORM answers, `filterReadable` drops every item, and the snapshot is `isSuccess` with `data: []` - **the empty success this task is named after**. For a named document whose cap IS held but which this session has never synced: the ORM answers nothing and the snapshot is again `isSuccess` with `data: []`, for a document that is not empty. Should: before the query opens, each NAMED document in `graphs` is asked of the public store, refused out loud if its cap is not held, and crossed over the sync barrier; any of those failing publishes `isError`.
+
+**The cases that must NOT change, and why each is a success rather than a failure:**
+
+- `graphs: "did:ng:i"` or `""` (the SDK's `normalizeScope` maps `""` to `did:ng:i`): the whole local dataset. The application named no document, so there is nothing to guard and the capability filter is the right and only answer - `isSuccess` with `data: []` means "you hold nothing of this shape". Untouched.
+- `graphs: []` or `undefined`: no objects, by the SDK's own definition. `isSuccess` with `data: []`. Untouched.
+- a `graphs` entry that is not a `did:ng:` reference: it names no document this library can hold a cap for, so there is no cap question; left to the engine.
+- a named document, held and synced, holding nothing of the shape: the barrier passes, the ORM answers empty, `isSuccess` with `data: []`. **This is the line that must not move.**
+- a held document exposing no read cap: `fetchReadCap` answers `false` and MEMOISES it. An absence was read; it is an answer.
+- a held document with no inbox: `documentInboxAddress` answers `undefined`, `depositsForDocument` answers `[]`.
+- the INERT case throughout: before the first cap exists, `isEnforcing()` is false, `fetchReadCap` returns without a round-trip, `mayReach` answers true for everything, and nothing new refuses. **CORRECTED 2026-09-21 after an adversarial review**: this row said "every row above is unchanged there", and that was FALSE. The REFUSAL is inert; the OPEN is not. `ensureRepoOpen` runs whatever the registry is enforcing, so a named scope now issues a real `doc_subscribe` and waits on the sync barrier where it used to open the query at once. That is deliberate - without it a named document this session has never synced answers `isSuccess` with `data: []`, the very lie the barrier removes - but it is a change, and calling it "unchanged" hid a cost. Pinned by `use-shape-query.test.ts` (u).
+
+**Partial scopes.** `graphs: [docA, docB]` with only docB held refuses the WHOLE query rather than answering docB's objects. A short answer is the same lie as an empty one, and this repo has already ruled twice against skip-and-carry-on: `readUnion`'s per-document tolerance was removed as an invention in `1.0.0-dev.8`, and an ORM write refuses the whole batch when one document is not writable.
+
+### Round 5 - the sync-state enumeration, written before the condition
+
+`useShapeQuery` checked that a named document may be REACHED and never that the open it had just awaited ARRIVED. Every value `getSyncState` can answer with, in every state it can be in when `reachNamedDocuments` has resolved - because treating the wrong one as not-synced is how the inert case regressed in rounds 1 and 3:
+
+| value | what it means (`open-repo.ts`) | how it is reached after the open resolved | verdict |
+|---|---|---|---|
+| `"synced"` | the first `State` arrived - the TRUTH signal | the ordinary path with a real `doc_subscribe` | **authoritative.** Zero rows MEANS zero objects; `isSuccess` with `data: []` is the answer, and this is the line four passes have held |
+| `"timed-out"` | the bounded fallback fired with NO `State`; opened best-effort, sync UNCONFIRMED | a broker that accepts the subscription and never pushes | **not authoritative.** This is the whole defect: the document may hold anything, and the read has no standing to call it empty |
+| `"syncing"` | subscribed, no `State` yet | unreachable once the open has resolved - the open resolves on `State` or on the fallback, and each sets its own value. Treated as not authoritative anyway, because if it ever IS reached the barrier demonstrably was not | **not authoritative** (defensively) |
+| `"unknown"` | never requested, **or the fake-ng no-op path: no `State` semantics** | an injected `ng` with no `doc_subscribe` - the whole unit suite, and any consumer whose `ng` lacks it. Also, until round 5 fixed it, a stale `opened` entry left by a reset | **authoritative, deliberately.** There is no barrier to have missed where there are no barrier semantics. Treating it as not-synced is exactly the inert regression rounds 1 and 3 shipped, and it would leave every early path pending for ever |
+
+So the condition is `"timed-out"` or `"syncing"`, and `"unknown"` passes. With a real broker the post-open state is only ever `"synced"` or `"timed-out"`, so the check bites precisely where `State` semantics exist.
+
+**`isPending` rather than `isError`**, and the contract allows either (`:196`, `:280`). Chosen because nothing FAILED: the subscribe succeeded, the query opened, the read did not throw - what is missing is an authoritative answer, and `isPending` is this surface's word for a question still open, while `isError` has meant "something threw" through five passes. It also needs no recovery machinery of its own: `publish` re-reads the level on every publication, so if the `State` does arrive later and brings data, the ORM's own change signal republishes and the read succeeds. What remains, and it is stated rather than hidden: a document whose `State` never arrives leaves the read pending for that session. The contract already names that state and tells an application to handle a `isPending` that does not end.
+
+### The design, and what was rejected
+
+Chosen: **`fetchReadCap` stops converting a failed download into `false`.** `downloadReadCap` right below it already distinguishes resolving from rejecting and documents why; the collapse was one `catch` destroying that distinction one line later. Removing the `catch` leaves `boolean` honestly meaning "a cap was obtained", and gives all three live call sites the one thing each of them wanted. Plus the `useShapeQuery` barrier above, which is where the published empty success actually comes from.
+
+Rejected, with the deciding reason for each:
+
+- **A three-valued result (`held` / `absent` / `unknown`), each caller deciding.** Rejected on the enumeration: all three live callers want the same thing - fail - so the vocabulary would buy nothing, and `fetchReadCap` has no upstream counterpart, so a richer outcome set than the engine's ("a read rejects or it does not") would be invented vocabulary an application learns and unlearns.
+- **Fixing only `fetchReadCap` and leaving `useShapeQuery` alone.** Rejected: `useShapeQuery` never calls `fetchReadCap`, so this would leave the published reactive read answering `isSuccess` with `data: []` for a document it cannot read - the exact headline defect.
+- **Making the capability filter refuse instead of drop.** Rejected: under `did:ng:i` dropping is exactly right (the broker delivers only what your keys open), and by the time the filter runs the engine has already answered. The question belongs at the ASK, not at the result.
+- **Refusing only the unreachable graphs and reading the rest.** Rejected: see partial scopes above.
+- **Adding no open barrier to `useShapeQuery`, only the refusal.** Rejected: an unsynced named document then still reads `isSuccess` with `data: []`, which is the same lie for a document that is not empty. Every other read path in this library crosses that barrier; this one stopped because T01.d removed the scope TRANSLATION that produced the document set, and the caller now names documents directly, so the barrier has a subject again.
+
+## Result
+
+Status: done, and SPLIT. `1.0.0-dev.9`, MAJOR. What this task delivers is a real, verified, PARTIAL improvement: a failure no longer reads as an absence at four call sites and on the reachability half of the reactive read, and the one half that is still incomplete - "has this document arrived" - is documented as incomplete rather than promised. The registry defect underneath it is `.tasks/todo/T01.m-one-answer-to-whether-a-document-is-open.md`, which carries both proved failures as acceptance tests. Seven rounds, six independent adversarial reviews; round 7 is the split and changed no code.
+
+### What each call site does now when the cap cannot be obtained
+
+- **`ensureRepoOpen`** (`open-repo.ts:209`) - propagates. The open has not happened, and the read that follows must not proceed as though it had. It used to decline silently and let the anchored read blame the reader for holding no cap.
+- **`docs.sparqlQuery`** (`docs.ts:155`) - rejects with the true reason instead of `assertMayReach`'s "you do not hold this document's cap", which is a different event calling for a different action.
+- **`documentInboxAddress`** (`branch-registers.ts:317`) - propagates, and so does its own address read, whose `catch` was swallowing breakdowns into `undefined`. `undefined` now means only "no inbox".
+- **`fetchReadCaps`** (`public-store.ts:277`) - DELETED. Zero callers, grep-verified, not in `src/index.ts`; an unowned per-document tolerance over a call that now rejects.
+- **`useShapeQuery`** - crosses the barrier on every document `scope.graphs` NAMES before opening the query: public-store fetch, refusal out loud, sync barrier. Any of them failing publishes `isError`.
+
+### The design, and what was rejected
+
+`fetchReadCap` stops converting a rejected download into `false`. `downloadReadCap` already distinguishes the two and documents why; one `catch` destroyed it a line later. `boolean` now honestly means "a cap was obtained". Rejected: a three-valued result (all three live callers want the same thing - fail - and the engine has no such vocabulary); fixing only `fetchReadCap` (`useShapeQuery` never calls it, so the headline defect would have survived); making the capability filter refuse instead of drop (under `did:ng:i` dropping is exactly right, and by then the engine has already answered - the question belongs at the ASK); partial answers for a multi-document scope (a short list is the same lie as an empty one); the refusal without the open (an unsynced named document would still read `isSuccess` with `data: []`, for a document that is not empty).
+
+### How "genuinely empty" stayed a success
+
+Every row of the enumeration's "must not change" list is covered by a test that passes both with and without the change: `use-shape-query.test.ts` (m) a named, reachable document holding nothing of the shape is `isSuccess` with `data: []`; (h) `graphs: []`; (p) `graphs: ""`; (j) the whole dataset filtered down to the holder's own; (o) the INERT case; `document-inbox-surfaces-failure.test.ts` third test, a document nobody opened an inbox on answering `[]` on both reads and refusing the deposit with "has no inbox"; `public-store.test.ts`, a document exposing no cap still answering `false` and still asked only once.
+
+The four tests that DO discriminate were verified non-vacuous by temporarily removing the change: (l) and (n) on the barrier, and both inbox failure tests. (q) caught a real leak when the generation check was removed.
+
+### What broke, and what it was really asserting
+
+Four tests in `public-store.test.ts`, all of them `expect(await fetchReadCap(unreachable)).toBe(false)`. What they were asserting was the MEMO's arithmetic - "a failure is not remembered, an absence is" - which is why every `asksAbout` count in that file is unchanged. The value they asserted alongside it was the collapse itself. They now assert a rejection, which is strictly stronger, plus one new test that the rejection names the document and keeps the broker's own words on `cause`.
+
+Nothing else broke. The reason is worth recording: the three live `fetchReadCap` callers that read a STORE or an INBOX already hold that cap (`fileOwnStructure` / `holdOwnCap` file it at connection), so `fetchReadCap` answers from the registry and never reaches the network. The blast radius is much narrower than four call sites suggest - it is a third party naming a document it does not hold.
+
+### CORRECTED after the adversarial review (round 1 was REFUTED)
+
+Two findings, both reproduced here before anything was changed, both diagnoses verified independently.
+
+**Finding 1, blocking - a refused named scope was TERMINAL.** Reproduced as `use-shape-query.test.ts` (r): a named document whose cap arrives AFTER the subscribe stayed `{isError: true, data: []}` for ever. Diagnosis confirmed by reading: the keyring handler is `if (query !== null) publish(query, generation)`, and the barrier aborts BEFORE any query is created, so the one channel that makes a late cap converge went straight past the state that needed it most. It broke a guarantee this package publishes and that `read-filter.ts`, `use-shape-query.ts` and `inbox.ts` all restate - a document shared with you while you watch becomes readable with no call from the application. **Trading a silent empty answer for a stuck error is worse than the defect**, and the ordinary sequence (a page subscribing while its keyring is still being restored) hits it.
+
+Fix, round 2: the keyring signal RE-OPENS a scope the barrier refused, gated on `namedDocumentsReachable()`. **That gate was itself wrong and round 3 refuted it - see below.**
+
+**Finding 2 - the INERT claim was false.** Reproduced by reading and pinned as (u): `ensureRepoOpen` runs whatever the registry is enforcing, so the inert case gained a real `doc_subscribe` and a barrier wait. The open is right and stays; what was wrong was calling it "unchanged". The measured COST was real though: the barrier was SERIAL, so N documents that never push a `State` cost N bounded fallbacks - 8s each in production. Now parallel, so the wait is the slowest rather than the sum, with the refusals still read in scope order afterwards. Pinned by (t) - which, as round 5 found, was at the same time asserting the WRONG outcome for those timed-out barriers, and is corrected there.
+
+**And the thing that let both through: the e2e never walked this path.** Confirmed - both `useShapeQuery` journeys read `{graphs: "did:ng:i"}`, so `43 passed / 43` was never evidence for the barrier, and reporting it as such was the real failure of round 1. Four live checks added over a NAMED scope: the owner reads her own document (the barrier does not break a live named read); a holder of nothing is `isError` with the refusal's own message and `dataLen: 0`, never an empty success; a PUBLIC document opens for that same holder from a bare reference, through the barrier's own fetch; and a cap landing for ANOTHER document leaves the refused scope refused. That fourth one measures the OUTCOME only - it does not separate "no re-open was attempted" from "one was attempted and refused again"; the targeting itself is measured by the notification count in `use-shape-query.test.ts` (s). Saying which of the two a green check proves is the whole lesson of the round that shipped this barrier with no named-scope coverage.
+
+**What the e2e still does NOT prove, stated plainly.** The POSITIVE recovery - the cap for the refused document itself arriving - is proven at unit level only (test r, non-vacuous). Driving it live needs a second actor delivering through `inbox.share`, and on one page that means switching the current identity while the observable is subscribed, which would re-open the refused scope under the OTHER identity. That is a pre-existing property of this observable (`publish` has always read the keyring of whoever is connected), it cannot arise in an application (one identity per page load, no call takes an identifier), and the repo has already ruled that such montages belong in the applicative suite - `capsShareCap` was moved there for exactly this reason. Left as a named follow-up rather than encoded here as if it were the library's behaviour.
+
+### CORRECTED AGAIN - round 2's repair was REFUTED, three findings, all reproduced here first
+
+**Finding 1, blocking and STRUCTURAL - the gate was circular.** `namedDocumentsReachable()` tested `mayReach`, i.e. the cap is HELD. For a named document in a PUBLIC store the only channel that can ever file that cap is `fetchReadCap` - the very call that had failed and set the flag. The gate waited on an answer that only the action it gated could produce, so that whole class was unrecoverable however many caps arrived. Reproduced as `use-shape-query.test.ts` (v): the broker hiccups on the `exposedReadCap` read, the fetch rejects, the broker heals, an ordinary cap arrival follows, and the view never re-asks.
+
+**The readiness question, answered rather than patched.** There are exactly two ways this barrier can refuse, and the memo already tells them apart. The store could not be ASKED: a failure is deliberately not memoised (an earlier fix in this repo), so a re-attempt genuinely re-asks the network - which IS the repair for this class, not a cost to avoid. Or the store ANSWERED and there is no cap to be had: an absence is memoised, so a re-attempt asks nobody, re-runs the barrier against what is already known, and republishes the same refusal for the price of one snapshot - and it stops the day the cap arrives from elsewhere, which is the only thing that repairs THAT class. So the right signal is not a cleverer predicate, it is **attempting again**: cheap for the class it cannot help, correct for the class it can, self-limiting because the moment an attempt succeeds there is a query again. `namedDocumentsReachable()` is DELETED. **CORRECTED: the claim that this made the module smaller than round 2 left it was FALSE** - measured, `use-shape-query.ts` went 534 -> 563 lines and 203 -> 204 non-comment across that round, and is **727 lines** now (`wc -l`). It has grown at every round. One predicate left; the reasoning that had to be written down beside the code grew more than it. Pinned by (v) and, for the cost, by (s), which now asserts both halves (the re-attempt ran, and it spent no round-trip) so it cannot pass vacuously.
+
+**Finding 2 - the re-open performed an access under the wrong identity, and my "pre-existing" defence was wrong in kind.** The reviewer is right: re-publishing RE-FILTERS an existing query, while a re-open NEWLY ISSUES a subscribe and a public-store fetch for a document that subscriber named. That is a new action taken on behalf of whoever happens to be connected, not an old one resurfacing, and the end state was `{isSuccess: true, data: []}` for a document the subscriber cannot read - this task's own defect, through the repair's door. Fixed by binding the refusal to a holder: `refusedFor` records WHOSE barrier failed, and a re-attempt is made only while that holder is still the connected one. Pinned by (w), which fails without the binding.
+
+**CORRECTED: "an application cannot change identity mid-session" was FALSE.** `ensureIdentity` does return the already-settled identity, which is what I checked - but that is not the only path. `shared-wallet/access-gate.ts:386` calls `adoptCurrentUser(normalized)` when a REVIVED barrier is confirmed, reached through the published `init()`, with a comment saying in as many words that the value may well not be the one that left. I checked one call site and generalised from it. The identity CAN change under a live page, which is the second reason the holder comparison had to go.
+
+**Finding 3 - the determinism claim was false.** `Promise.all` short-circuits on the first rejection to ARRIVE, and a fetch that rejects does not wait for the sync barrier, so it overtakes a refusal on a document named before it. I chose to fix the BEHAVIOUR rather than the claim: `Promise.allSettled` plus a walk in scope order, so the document reported is the first one the caller named that failed, whatever it failed of, and the parallelism is kept. Pinned by (x), which fails on `Promise.all`.
+
+**The fourth e2e check was removed, not repaired.** "A cap landing for ANOTHER document leaves a refused scope refused" passed with the whole re-attempt machinery deleted - the outcome is a standing refusal either way. A check that cannot fail for any regression of the thing it guards reads as coverage and is worse than none. Its properties are measured in the unit suite by (v), (s) and (w).
+
+### The decision to KEEP the barrier rather than take the escape hatch
+
+Taken deliberately, at the second offer. Removing it would restore, on a published read, a silent `isSuccess` with `data: []` for a document the caller cannot reach - the defect this task exists for, now proven live rather than argued. The escape hatch's own premise is "a stuck error is worse than a silent empty"; after these three repairs there is no stuck error left to weigh against it. Every class that can refuse is re-attempted on the only readiness signal this library has, and the one class that is not - the identity changed under the observable - cannot arise in an application and is answered honestly rather than by acting in someone else's name. The repairs are also subtractive: a circular predicate deleted, a short-circuit replaced by an ordered walk, a flag given the one extra fact it was missing. What remains is a scope refused in a session whose keyring never moves again, which stays `isError` until `refetch()` - the published meaning of `isError` on this surface, and what it already meant for every other failure it carries.
+
+### ROUND 4 - refuted again, and the recovery changed SHAPE rather than gaining another flag
+
+Three defects and two false claims, all reproduced here before anything was touched.
+
+**Finding 1, blocking: the recovery was EDGE-TRIGGERED, so the edge that caused a refusal was the one it could not see.** `refusedFor` was only set after the async barrier, so an `onChange` firing WHILE the barrier crossed found no query and no record and did nothing - and that same change is what made the walk refuse. Reproduced as (y): inert at subscribe, so the barrier skips the public-store ask entirely; the connect burst files the holder's first cap mid-barrier; the walk then refuses; no keyring event is left to come. `refetch()` answers at once, so the error was for nothing.
+
+**This is the shape that had to change, not the flag.** Rounds 2 and 3 both built recovery as "record that we refused, then react to a later event", and both records were the fault - one gated on a condition that could not become true, one written after the window in which the deciding event arrives. So the recovery stopped depending on edges:
+
+- **the decision is a LEVEL.** Which named documents the holder may reach is re-read on every publication ({@link publish} calls `namedRefusal()`), never carried from the barrier. A cap arriving turns `isError` into the document through the channel that already existed, and nothing is remembered, so there is no event to miss. This is also what makes the holder question moot: a query opened while somebody else was connected cannot come back to this subscriber as a success it is not entitled to, so the comparison that Finding 2 breaks is not needed at all.
+- **an attempt that RACED a change notices, instead of waiting.** `open()` samples `CapRegistry.version()` synchronously before the barrier and compares after it fails; a mismatch means it decided on stale ground, so it makes another attempt itself. It terminates: an attempt repeats only because the keyring moved, moves are finite, and the moves an attempt causes itself are the caps it files - at most one per named document, after which that document is held and asks nothing (`file()` does not notify when the value is unchanged, and `markInPublicStore` does not notify at all - both checked).
+
+`CapRegistry.version()` is the one new primitive: a counter bumped where `notify` is, with a note saying why a listener alone is not enough.
+
+**Finding 2, major: the holder comparison broke the ordinary sign-in.** `holderKey()` is `""` while nobody is connected, so a refusal taken before the identity settles - which is where components mount - never matched again once it did. Reproduced as (z). The comparison is GONE, replaced by the publish-time check above.
+
+**Finding 3: "costs one snapshot" held only for the absence class.** Over a FAILED fetch, each unrelated arrival re-asks the broker - that is the repair for that class and it stays - but it also published a fresh snapshot carrying a fresh `Error` for an unchanged state, which contradicts the stability this surface documents. FIXED rather than documented away: `setUnknown` compares by message and keeps the standing snapshot, so subscribers see no update while nothing has changed. Reproduced and pinned by (aa), which asserts snapshot IDENTITY.
+
+**A defect of my own, found by measuring rather than by review.** The round-4 change made the unit suite intermittently fail - two 5s timeouts in `cold-read-for-document`, about one run in four, where round 3 was stable 4/4. Traced by instrumenting the open registry rather than guessed: `resetOpenedRepos()` abandons in-flight opens WITHOUT settling them, so a caller awaiting one waits out the full 8s fallback on a subscription that has been torn down, then proceeds with its sync state cleared - and `"unknown"` is the LAX reading (`index-deposit.noRowsMeansAbsent` accepts it as a definitive absence). A latent failure-as-absence bug in this task's own family, which the re-attempts made fire. Fixed: a reset now ENDS the opens it abandons and marks them `"timed-out"`, the reading that refuses to call nothing an absence. Pinned by a new test in `open-repo.test.ts`; six full-suite runs are green at the usual 2.4s.
+
+Two fixtures were also racing themselves and are corrected, with the reason written beside them: `use-shape-query.test.ts`'s fake minted into `did:ng:o:doc<n>`, the same namespace as `wallet-fake.ts`, so two fakes aliased each other's repos in the process-global open registry - the lesson `wallet-fake` already carries at its own scale, one scope wider; and the INERT test asserted `isEnforcing() === false` and then subscribed, while signing in arms the registry a tick later, so it was pinning the schedule. It now runs with nobody signed in, which is inert for the whole test.
+
+### ROUND 5 - two defects, neither about recovery
+
+The recovery design survived this pass and was not reopened. Both findings reproduced here before anything was changed.
+
+**Finding 1, blocking: the barrier checked that a document may be REACHED and never that it ARRIVED.** `reachNamedDocuments` awaited `ensureRepoOpen` and then asked `assertMayReach`, which is the CAPABILITY question; it never consulted the sync state that open had just produced. So a document whose subscribe succeeded and whose first `State` never came published `isSuccess` with `data: []` - the original defect, in the exact case the barrier was added to close. Reproduced as (bb), and test (t) was PINNING it: it waited for `isSuccess` after three timed-out barriers and asserted the three titles. (t) is corrected, and that is not a weakened assertion - the old one was wrong, and the commit says so.
+
+The fix sits where the rest of the decision already sits: `publish` calls `namedDocumentsArrived()` on every publication, so the question is re-asked at the level rather than remembered from the barrier. The enumeration of the three values, written before the condition, is above under "Round 5". The short form: `"synced"` is authority (zero rows MEANS zero objects - the line that has held through five passes), `"timed-out"` and `"syncing"` are not, and **`"unknown"` PASSES deliberately** because it means "no `State` semantics on this `ng`" and treating it as not-synced is exactly the inert regression rounds 1 and 3 shipped.
+
+**`isPending`, not `isError`**, of the two the contract allows. Nothing failed: the subscribe succeeded, the query opened, no read threw - what is missing is the authority to call the document empty, and `isPending` is this surface's word for a question still open while `isError` has meant "something threw" for five passes. It also needs no machinery of its own: `publish` re-reads the level, so a `State` that lands later and brings data republishes through the ORM's own change signal.
+
+**That last sentence was not true when I first wrote it, and I found it by re-reading my own claim rather than by review.** A late `State` was DISCARDED - `onState` returned early once the bounded fallback had settled the open - so `"timed-out"` stood for ever on a repo that had since synced, and the reader consulting it could never learn better. The fallback means "this open stopped waiting", never "the barrier will not be crossed": the subscription is never dropped, so the `State` still lands. `onState` now records `"synced"` before the settled check. `"timed-out"` -> `"synced"` is the only transition this adds and it goes from less authority to more; the two readers of that value (`index-deposit.noRowsMeansAbsent` and the new arrival check) both want it that way. Pinned by (dd), which fails if the recording moves back below the check.
+
+Stated rather than hidden: a document whose `State` never arrives leaves that read pending for the session, and so does one whose late `State` brings no data - nothing republishes then, because there is no change to signal. The contract already tells applications to handle a `isPending` that does not end.
+
+**A GAP IN MY OWN SUITE, found by mutation rather than by review.** Inverting the condition to treat `"unknown"` as not-arrived - the precise regression the blast-radius note warned about - passed every test. Nothing in the file exercised an `ng` WITHOUT `doc_subscribe`, which is the only way `"unknown"` is reached, and it is what `wallet-fake` does by default and what any consumer lacking the member does. Closed by (cc), which now fails on that inversion.
+
+**Finding 2, major, and a regression from my own round-4 fix.** Settling an abandoned open made its continuation run just after `resetOpenedRepos()` had cleared the maps, so it wrote a stale `opened` entry into the fresh registry - and every later `ensureRepoOpen` for that nuri short-circuited on it. The repo was never subscribed in the new session and a read over it answered as though it had been. Before round 4 that line ran only when the 8s fallback fired, so a re-open inside the window did re-subscribe; ending the open promptly was right, but it moved the write into the window where it does damage. Fixed with a registry epoch: a reset bumps it, and a continuation whose epoch no longer matches writes nothing. A reset now INVALIDATES what it abandons as well as ending it. Pinned by a new `open-repo.test.ts` case that fails without the epoch check.
+
+**`getSyncState`: decided, not left dangling.** It stays INTERNAL, and `knowledge_what-a-failed-read-answers-upstream` no longer offers it - that pointer was at a symbol no caller can import. The reason for not exporting: it has no counterpart upstream at any level, so publishing it would hand an application one more polyfill-era symbol to unlearn, on a surface that is busy removing exactly those; and the distinction it carries is now folded into `useShapeQuery`'s own states, which is where a caller needs it. The leaf now also states the consequence plainly instead of papering over it: a caller using the anchored `docs.sparqlQuery` directly gets zero rows for an unsynced document and has no published way to tell that from an empty one - the same collapse upstream has.
+
+### ROUND 6 - the registry was what lied, and it now has one meaning
+
+Three findings, one defect under three faces: **state recorded as true that is not, with no way to correct itself.** Two of the three were in `open-repo.ts`. Five rounds had gone into the caller; the bookkeeper was the problem, and the repair is there.
+
+**The invariant, established and written into the module header.** `held` is the ONE record of openness - *this session holds a live bootstrap subscription to this document*. Beside it stood `opened`, meaning "we once called `doc_subscribe` and stopped waiting", and that looser meaning is what lied three ways. `opened` is DELETED; two records of one fact can disagree, and this pair did. What else relied on the looser meaning, checked rather than assumed: `opened` had exactly one reader (`openRepoUnguarded`'s own short-circuit), `held` one (the reset's teardown), and `getSyncState` two outside the module (`index-deposit.noRowsMeansAbsent` and `useShapeQuery`) - both of which the change moves toward the safe reading.
+
+The three consequences, now true by construction:
+- **a subscribe the broker REFUSED records nothing.** `subscribe.ts` reports a failed establish through `onSetupFailed` precisely so a caller can retry; `open-repo` never passed it, waited out the 8s fallback, and then recorded the repo as open - so `refetch()` issued zero new subscribes and the read had no exit at all. The channel is wired, the failure marks `"timed-out"`, and nothing is recorded. (Finding 3.)
+- **a reset DOWNGRADES the sync state of every document it takes a subscription from**, instead of clearing it. Clearing left them reading `"unknown"`, which is deliberately authoritative because on an `ng` with no `doc_subscribe` there is no barrier to have missed - so a read correctly withheld came back claiming success against a query the new session never re-subscribed. (Finding 1.)
+- **`"unknown"` now means one thing only**: no barrier was ever expected here. Never "we forgot".
+
+**Finding 2, the one that was in the caller.** When a named document has not arrived, `publish` now PUBLISHES "the question is still open" rather than returning and leaving whatever snapshot stood. Returning left a refusal that had already been LIFTED on display, so an application read "you do not hold this document's cap" about a document it now holds - a false reason, and `isError` where round 5 decided the answer is `isPending`.
+
+**FALSIFIED BY THIS PASS, and corrected:** the guarantee published last round at `contract_polyfill-surface.md:196` ("a named document that has never synced now stays PENDING") was not delivered - Finding 1 bypassed it. It is now delivered and pinned by (ee). I had filed that bypass as pre-existing, which was wrong: the BYPASS was new, because before round 5 nothing consulted that state. This is the second time this task shipped contract text ahead of the behaviour, and the lesson is recorded rather than explained away: the guarantee and the test that pins it land in the same commit from here.
+
+**One caller-visible consequence, published rather than left implicit:** an in-page re-login returns a named scope to PENDING until its documents are confirmed under the new session, `refetch()` being what confirms them. It is the only case where a read that had answered stops answering, and it does not arise on an ordinary page load.
+
+**Two fixtures carried the old meaning and are corrected with the reason beside them.** This file's fake broker restarted its id counter inside every `makeFake`, so two tests minted the same nuri and aliased each other in the process-global registry - invisible while a reset cleared sync state, immediate once it downgraded it; the counter is now monotonic, which is `wallet-fake`'s own recorded lesson at this file's scale. And the cold-read suite asserted `"unknown"` for a note this page never opened; `"timed-out"` is now what "this page has not confirmed it" says, and the test notes that this particular value is a harness artefact (`reloadPage` resets inside one process, where a browser reload would start with an empty module).
+
+**On the hard stop, and I am answering it rather than waiting to be asked.** I judged this round CONTAINED and did not split: the fix is one invariant in one module with four readers, all enumerated above. If a further pass finds this family again I would take the split myself, because the evidence would then be that the registry needs its own reviews rather than that this one needs another patch.
+
+> **CORRECTED after the sixth pass, and this sentence used to carry two false claims.** It said the fix "made the caller smaller rather than larger - no sixth condition was added, one was removed". Measured: `packages/polyfill/src/surface/use-shape-query.ts` went **664 -> 727 lines** across that commit, and `git show 6b2b8ab --numstat` reports **34 insertions / 8 deletions** on it - `setNotYetAnswered` ADDS a three-term condition rather than removing one. The caller grew. See the note at the end of this Result on why this kept happening.
+
+### ROUND 7 - the task is SPLIT, and that is the outcome
+
+The sixth pass refuted the round-6 repair and found the family we had both pre-committed to splitting on. It is split, and the follow-up is `.tasks/todo/T01.m-one-answer-to-whether-a-document-is-open.md`, written by the coordinator and carrying both proved failures as its acceptance tests. **No registry code was touched in this round**; what follows is the honest accounting.
+
+**What the sixth pass proved, and it falsifies round 6's central claim.** I wrote that `held` is "the ONE record of openness". It is not - there are three, and the one nobody counted is `fanOuts` in `subscribe.ts`. `configure()`, which is PUBLISHED, calls `resetDocSubscriptions()` and clears every fan-out listener including the bootstrap one, without telling `open-repo`; so `held` keeps a dead entry, `syncState` keeps `"synced"`, and the short-circuit skips the re-open for ever - measured as `doc_subscribe calls = 0` and `{isPending: false, isSuccess: true, data: []}`, unrecoverable even through `refetch()`. And `held.set()` runs synchronously before `establish` has reached `doc_subscribe` at all, so a broker rejecting after the bounded fallback still leaves the repo recorded as held. **`held` still means "we asked"** - the exact looser meaning I deleted `opened` for. I replaced one of two disagreeing records; there were three.
+
+**What this task delivers, and every part of it survived six independent reviews:**
+
+- the four call sites - `docs.sparqlQuery`, `ensureRepoOpen`'s propagation, `documentInboxAddress`, and `fetchReadCap` no longer collapsing a rejection into `false`;
+- the `fetchReadCaps` deletion;
+- `knowledge_what-a-failed-read-answers-upstream`;
+- the empty-is-success guards, never once faulted;
+- the e2e named-scope coverage, run live by two independent reviewers;
+- **the barrier's REACHABILITY half**, kept deliberately: a holder of nothing gets `isError` with `dataLen: 0`, and a public document opens from a bare reference, both verified against a live broker twice. Removing it would restore a silent empty success universally, which is worse than a partial guarantee honestly stated;
+- **the barrier's ARRIVAL half, honestly qualified rather than withdrawn.** It holds inside one ordinary session and is pinned by (bb), (t), (ee), (ff) and (cc). It does not hold after a second `configure(...)`, nor when a broker refuses a subscription late.
+
+**The contract is brought down to that.** `## Guarantees` now says the arrival half holds "within one session" and sends the reader to `## Non-guarantees`, where both situations are named with their cause - more than one record of "is this document open" - and pointed at `T01.m`. The same qualification is in the knowledge leaf. **No version bump**: no published behaviour changed in this round, only the accuracy of its description.
+
+**Why no `bug_` leaf for this.** The task's own instruction was not to open one for what it repairs; this is what it does NOT repair, and it is now a task with acceptance tests, which is the stronger record. A leaf would duplicate `T01.m` and drift from it.
+
+### Gate
+
+- `bun test` -> `449 pass / 0 fail`, `Ran 449 tests across 40 files` (baseline `421 pass / 0 fail`, measured before any change; +28 new tests, none deleted or skipped). **Run six times on the delivered state: green every time, 3.18-3.34s.** Two tests were REWRITTEN rather than weakened, each because the design under them changed and the old assertion had become a statement about something that is no longer true: (s) asserted the targeting predicate round 3 proved circular, and now asserts that a re-ask is made for the class it can repair and not for the one it cannot, each half guarding the other against vacuity; (w) asserted that no query is opened under another identity, a rule that left two classes terminal, and now asserts the stronger invariant that replaced it - no snapshot ever claims success for a document the CURRENT holder cannot reach.
+- **Mutation-tested, fifteen ways.** Round 6: removing the reset downgrade kills (ee), the abandoned-open test and the cold-read assertion; ignoring `onSetupFailed` kills the refused-subscribe test; restoring a second record of openness kills the refused-subscribe test; making `publish` return instead of publishing pending kills (ff). Round 5: removing the arrival check kills (bb) and (t); inverting it to refuse `"unknown"` kills (cc); moving the late-`State` recording back below the settled check kills (dd); removing the registry-epoch invalidation kills the new `open-repo` case. Earlier rounds: Removing the raced-edge re-attempt kills (y); removing the publish-time refusal kills (w); removing the snapshot-stability guard kills (aa) and (k); removing the re-attempt entirely kills (r)(s)(v)(w)(z); `Promise.all` in place of `allSettled` kills (x). Round 2's circular gate kills (s)(t)(v) and round 3's holder rule kills (w)(z), so the suite now discriminates against both previously-shipped designs. Removing the abandoned-open settle kills the new `open-repo` test.
+- `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 (warnings pre-existing; the new leaf carries none)
+- polyfill e2e, run at HEAD: `Polyfill e2e summary: 46 passed, 0 failed, 46 total - batch 3.5 min, slowest cold sync 30s`, re-run on the delivered state. **Two reviewers have now run it independently and confirmed both the count and what it does and does not prove.** Earlier in this task every count reported for it was mine alone.** 43 was the count before this task; three named-scope checks were added and a fourth removed as non-discriminating. NOTE: the broker login is flaky and independent of this work - three of thirteen runs in this session died with `[e2e broker login] gave up after 45.0s - the wallet-list screen never changed`, at a different step each time, on the login UI before any library code runs. Every such run was re-run to a clean result.
+
+**What the e2e PROVES**, and it is the whole of it: against the real broker, a named scope reads for the holder who owns the document; a holder of nothing is refused out loud with `dataLen: 0` rather than told the document is empty; and a public document opens for that same holder from nothing but its reference, through the barrier's own fetch. **What it does NOT prove**: anything about the re-attempt. Every recovery path - the public class repaired by re-asking, the cost of a doomed re-attempt, and the holder a re-attempt is made as - is measured only in the unit suite, against the `CapRegistry`, which is where that mechanism lives and which the e2e's own header says the broker does not implement. Driving the positive recovery live needs a second actor delivering through `inbox.share`, and belongs in the applicative suite.
+
+### The contract
+
+`1.0.0-dev.9`, MAJOR, per the leaf's own `## Change policy` ("an existing call narrows: ... it reports a state you did not have to handle before"). `packages/polyfill/package.json` bumped. Two NON-guarantees corrected because the change makes them false: "Neither shape read fetches a public store's key for you" (now `useShape` only, plus `did:ng:i`), and "a shape query the engine refuses never finishes loading" (the commonest way in is closed for a NAMED scope). Two out-of-leaf documents carried the same now-false claim and were corrected in one sentence each: `docs/api-contract.md:262` and `docs/readcap-and-nuri-model.md:367`. `emulated-verifier/read-filter.ts`'s header said both shape reads ask nothing - corrected, with the note that refusing at the ASK and filtering the RESULT remain two different questions.
+
+**A rights movement, stated as the grid requires.** `useShapeQuery` now fetches a public store's cap for a document named in `graphs`, which files that cap in the connected holder's ring. That is a GAIN on that call. It grants nothing new overall: it is exactly the reachability `docs.sparqlQuery` anchored on the same document already gave, and `exposeReadCap` is called only for `scope === "public"` (VERIFIED in T01.f). No document becomes readable that was not already readable by naming it. Said in `## Non-guarantees`.
+
+`knowledge_what-a-failed-read-answers-upstream` records the durable fact: two observable outcomes only, the two collisions ("does not exist" vs "not known to me"; "unsynced" vs "genuinely empty"), no capability check on the read path, and the three rules that follow - including that the unsynced/empty collision is closed by the sync barrier and never by an error.
+
+`docs/internal-contract.md` section 6 only: line numbers, the `ensurePhysicalRepoOpen` export this module has never had (it is `shared-wallet/physical.ts:134`), the deleted `ensureReposOpen`, the missing `openRepoUnguarded`, and `ensureRepoOpen`'s second parameter. A dated note says the rest of that document's drift was left alone deliberately.
+
+### The two bug leaves: NEITHER is closed
+
+- `bug_a-lost-inbox-watch-is-never-retried` - **not closed.** It asks for a recovery signal that does not depend on the identity performing a capability-bearing act. Nothing here adds one. This work arguably makes it more visible (a failed open reports a truer reason), which is not the same as retrying.
+- `bug_an-empty-inbox-list-can-mean-a-failure` - **not closed.** Its mechanism is `resolveAccount` yielding nothing RATHER THAN raising, inside `enumerateMyInboxes`, which then reports a list that is complete and empty. That path was not touched: `readInboxCapPairs` already rethrows what it catches, and `record?.docPrivate` returning `undefined` still answers `[]` with no shortfall. No test proves otherwise, so the leaf stays.
+
+### Surprises
+
+- **VERIFIED: `fetchReadCaps` was dead.** Zero callers anywhere in `src`, `test` or `e2e`, and absent from `src/index.ts`. Its last caller went with `readUnion` in `1.0.0-dev.8`.
+- **VERIFIED: `useShapeQuery`'s empty success does not come from `fetchReadCap` at all.** That call site does not exist on this path - T01.d removed it with the scope translation. It comes from the capability filter emptying a named document's objects, and from a named-but-unsynced document answering nothing. Tests (l) and (n) fail without the barrier; the task's three-layer chain describes the ANCHORED path, which is a different (and already loud) one.
+- **VERIFIED: the blast radius is narrow.** Six of the eight `ensureRepoOpen` callers hold the cap they are about to use, so they never ask the network. That is why only four tests broke.
+- **VERIFIED: `g === ""` in `namedDocuments` is unreachable** - `isNuri("")` is false. Kept as documentation of the SDK's own alias, said so in the comment and the commit. Test (p) is therefore a behaviour guard, not a discriminating test, and is labelled as one.
+- **VERIFIED, and it was under-reported in round 1: the barrier's cost.** A named scope spends one public-store fetch and one sync barrier per document per session. The opens now run TOGETHER, so the wait is the slowest rather than the sum; the serial form cost N bounded fallbacks, 8s each in production, which an adversarial review measured. Stated in the contract.
+- **The round-1 Result contained two claims this review falsified**, both corrected above: that the INERT case was unchanged (the open is new), and that the e2e was evidence for the barrier (it never walked a named scope). Both were overstatements of what had actually been checked, and the second is the one that mattered - a green suite reported as proof of a path it does not exercise.
+
+### Follow-ups, reported and not fixed
+
+- `packages/polyfill/src/shared-wallet/account-registry.ts:78` imports `documentInboxAddress` and never uses it - a dead import. `tsconfig.base.json` sets no `noUnusedLocals`, so nothing flags it.
+- Every e2e run logs, at connection: `connect failed: docs.sparqlQuery: refused - the connected user does not hold this document's cap ... at readStoreCaps <- restoreOwnCaps <- restoreAndDrain`. That is `assertMayReach`'s own pre-existing message (this work would have produced a different one), so `restoreOwnCaps` is being refused one of the connected user's OWN store documents at connect, and the failure is logged rather than raised.
+- The e2e broker login fails intermittently at 45s on the wallet-list screen, before any library code runs - 2 of 8 runs in this session.
+- A two-actor journey for "a document is shared with someone while they are watching, and their named `useShapeQuery` converges" belongs in the applicative suite (`e2e/notebook.ts`), beside the journey that already checks "after Alice shares it, the same reference opens it". It is the live form of unit test (r).
+- Pre-existing and out of scope, surfaced while tracing the arrival check: an in-page session change (`resetOpenedRepos`) clears every document's sync state, so a named scope that was authoritative reads `"unknown"` afterwards and keeps publishing successes against a query the new session never re-subscribed. The observable does not react to a session change at all - which predates this work and is unchanged by it, since before the arrival check nothing consulted that state.
+- This observable re-PUBLISHES under whoever is connected at that instant rather than under the identity that subscribed. That part is genuinely pre-existing and out of scope - `publish` has always read the keyring of the current holder. The RE-ATTEMPT no longer does: it is bound to the holder that was refused (`refusedFor`), because issuing a subscribe and a fetch is a new access rather than a re-filtering, and the two must not be lumped together - round 2's Result did lump them, and that was wrong.
+- `docs/internal-contract.md:7` still names `surface/watch-shape.ts`, `surface/read-model.ts` and a `storeRegistry` namespace listing three removed symbols. Out of this task's boundary.
+- `knowledge_what-a-failed-read-answers-upstream` cites `213338f6`, the checkout T01.h found to be three ORM releases behind. The facts it cites are engine-side rather than ORM-side, but T01.k owns reconciling what a citation's version means.
+- The in-page session change and the identity-following publication, both listed above, are inside `T01.m`'s territory now rather than loose follow-ups.
+
+### The reporting fault this task had, recorded because it is a pattern and not an oversight
+
+Three times I asserted that a change had simplified or shrunk something, and all three were contradicted by measurement: "the module is smaller than round 2 left it" (534 -> 563), "the caller came out smaller" (664 -> 727), "no sixth condition was added, one was removed" (`--numstat`: 34 insertions, 8 deletions, and `setNotYetAnswered` adds a three-term condition). Two of them were relayed onward before anyone measured them. The common shape: I wrote the claim from the INTENT of the change - a predicate deleted, a record unified - while the file was growing around it, and the sentence read as a fact.
+
+The rule I am holding from here, and it is mechanical rather than a resolution to be careful: **a structural claim - smaller, simpler, a condition removed, a mechanism deleted - carries the `wc -l` or `git show --numstat` that supports it, in the same sentence. If the number cannot be pasted, the claim is not written.** Every structural claim in this Result now carries its measurement.
+

.tasks/done/T01.k-a-citation-must-say-which-version-it-describes.md

@@ -0,0 +1,126 @@
+---
+id: T01.k
+title: A provenance citation must say which version it describes
+parent: T01
+depends_on: [T01.n]
+created: 2026-09-21
+claimed_by: worker-T01.k
+claimed_at: 2026-09-24
+blocked: false
+---
+
+## Description
+
+The provenance mechanism cites a source tree that is THREE RELEASES BEHIND what this repo compiles against, and nothing in an annotation says so. A citation therefore proves "this was true at orm alpha.18", while a reader takes it for "this is true of what we build against".
+
+### The established facts - VERIFIED, do not re-derive
+
+Scanning every remote branch of `/home/sylvain/projects/nextgraph/nextgraph-rs`:
+
+| source | `@ng-org/orm` version |
+|---|---|
+| `upstream/main` (the real upstream) | `0.1.2-alpha.18` |
+| `origin/main` (a fork) | `0.1.2-alpha.15` |
+| local checkout HEAD `213338f6` | `0.1.2-alpha.18` |
+| what this repo compiles against | `0.1.2-alpha.21` |
+
+So the local checkout is ALREADY at the newest source that exists anywhere reachable. alpha.19, 20 and 21 are published to npm from source that is in no branch of that repository. **There is nothing to re-anchor to, and updating the checkout is not the answer.** Do not spend time looking for a newer tree; that question is closed.
+
+`grep -rho "ref=[^ ]*" packages/polyfill/src/ | grep -cE "engine/|sdk/"` counts 96 citations into that tree.
+
+### The second-order trap, which has already fired
+
+A claim about alpha.21 REFUTED by reading the pinned tree is refuted against alpha.18 - which is not the same statement. This happened during T01.h: the agent first wrote that alpha.21's `where`/`orderBy`/`pageSize` "became reachable", then retracted it because the pinned engine still has `start_orm` as `json!({})` behind a TODO. The retraction may be right, but the EVIDENCE does not support it at the strength claimed, because the pinned engine is not alpha.21. **Re-examine that specific correction** in `.project/concepts/app-contract/knowledge_what-the-orm-writes-and-deletes-upstream.md` and state what can honestly be said about it. A true citation attached to a claim it does not support is the exact failure `.project/rules/nextgraph/surface-mirrors-the-sdk.md` names.
+
+### What to establish - the design is yours
+
+The question is where the version belongs, and the obvious economy is worth weighing before anything else: **the version is a property of the CHECKOUT, not of each citation.** 96 annotations do not each need to carry it; one place that says "citations into `engine/` and `sdk/` are anchored at `213338f6` = orm alpha.18, while the build is alpha.21" may carry the whole fact. Weigh that against the alternative, do not assume it.
+
+Then decide what the mechanism should ENFORCE, if anything. `packages/polyfill/test/provenance.test.ts` already checks that a `ref` resolves when the sibling checkout is present, and deliberately does NOT check that a claim is true. Adding a version check is a real option; so is deciding that this is doctrine, not a test. Read `.project/rules/nextgraph/no-divergence-from-nextgraph.md` for the taxonomy before proposing anything, and remember `announced-not-written` already exists for "the target is stated but the tree carries nothing" - part of this gap may be the same shape.
+
+**Do NOT mass-rewrite 96 annotations** unless you have established that the fact cannot be carried in one place. A 96-site sweep is a large, risky, low-information change, and this repo's doctrine is explicitly that a good repair usually leaves a leaf SHORTER.
+
+**Where a citation genuinely describes something that alpha.21 changed**, that is a real finding: record it. But establish it from the published package's own shipped types (`node_modules/@ng-org/orm`), not by guessing - and say plainly when the shipped artifact cannot settle the question, which it often will not since it carries types, not behaviour.
+
+### Verification
+
+**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 deleted or skipped test, no weakened assertion.
+
+**An adversarial review is part of this task.** Angles: a citation that still claims more than its anchor supports; a version statement that is itself already stale; and whether whatever is added would survive the checkout moving. A finding counts only with a concrete scenario.
+
+## Progress
+
+## Result
+
+Status: done
+
+### 1. Where the version now lives, and why not on each citation
+
+**In one place: the `ANCHOR` in `packages/polyfill/test/provenance.test.ts`, beside the resolver that opens the checkout.** Annotations touched: **0 of 94**. (The task file says 96; the same grep it prescribes returns **94** today, so the figure had drifted by 2 - VERIFIED, flagged here rather than silently reused.)
+
+The economy holds, and it is stronger than "one fact stated 94 times". What a reader needs is not a version but the **gap**, and a gap has two ends. A per-citation version would record only the near end, would be wrong at all 94 sites at once the day the checkout moves, and would still leave the far end - the installed releases - unstated. The anchor records four rows, `(package, cited, built)`, and **three tests** check them:
+
+| check | scope | behaviour when it cannot ask |
+|---|---|---|
+| the checkout declares the cited versions | 4 rows | passes empty-handed, like `deadCitations` |
+| every workspace manifest pins the built versions | discovered from `packages/*`, `examples/*` | never absent |
+| `packages/polyfill/node_modules` resolves the built versions | 4 rows | never absent |
+
+Each was **mutation-tested**: falsifying `cited` -> `"@ng-org/orm - the checkout declares 0.1.2-alpha.18, the anchor says 0.1.2-alpha.19"`; falsifying `built` -> two manifest lines plus the installed-tree line; renaming a row to a package nothing pins -> `"the anchor names it, no workspace manifest pins it"`. With `NEXTGRAPH_RS=/nonexistent-checkout` the suite is `10 pass / 0 fail`. So it survives the checkout moving, by going red with the repair named.
+
+A source-side pointer sits in `src/index.ts`'s provenance block (no numbers - numbers live in one place), and the doctrine sits in `.project/rules/nextgraph/no-divergence-from-nextgraph.md`.
+
+### 2. What the mechanism enforces, and what it deliberately does not
+
+It enforces that **the gap statement is still true at both ends** - the same class of check the file already made (a citation still *resolves*), never the class it refuses (a claim is *true*).
+
+**It is NOT a new `kind`.** The taxonomy classifies what evidence ONE symbol has; how old ALL the evidence is belongs to the tree. `announced-not-written` is a different shape: there the tree carries nothing, here it carries an older something. A kind would have pushed a checkout-wide property onto 94 per-symbol labels.
+
+It does not check the commit hash. `213338f6` is recorded as a `git show` pointer and explicitly labelled *not* the enforced identity: a checkout at another commit declaring the same releases describes the same code, and going red for a local commit is the red that teaches people to skip the suite.
+
+### 3. `where` / `orderBy` / `pageSize` - what can honestly be said
+
+**The retraction is refuted, and the original claim was closer to right than the retraction.** All VERIFIED, each from the artifact that can answer it:
+
+- Level 3: `@ng-org/orm@0.1.2-alpha.21`, `dist/connector/RdfOrmSubscription.js` calls `ng.orm_start_graph(options.graphs, options.subjects, shapeType, session.session_id, options, this.onBackendMessage)` - the config **is sent**, at index 4.
+- Level 2: `@ng-org/web@0.1.2-alpha.14`, `dist/index.d.ts` declares `orm_start_graph(graph_scope, subject_scope, shapeType, session_id, config, callback)` - **six** parameters, the config **is accepted**. The pinned tree's `sdk/js/lib-wasm/src/lib.rs` declares **five**, no config slot, which *proves by arity* that the pinned tree is older than the binding in this build. A claim about alpha.21 cannot be refuted there.
+- Level 1, at `213338f6`: `OrmConfig` (`engine/net/src/orm.rs`) declares `where_`, `order_by`, `select`, `page_size`, `max_active_pages`; `from_json` parses all five and refuses a `pageSize > 0` without an `orderBy`; and every field is **consumed** - `schema_shape_to_sparql` emits `FILTER` (`|lt`/`|gt`), `ORDER BY`, `LIMIT`, `OFFSET`, and `initialize.rs` drives the paging window and page eviction. The `json!({})` is at the **entry point only**: `start_orm` takes no config argument, `request_processor.rs` calls it with three, and `from_json`'s own TODO names the missing hop - *"Use json in libwasm context"* - which is exactly the binding parameter the shipped binding now has.
+
+So *"the richness is expressible at level 3 and discarded at level 1"* / *"no caller can reach any of it"* was **false at the pinned commit too**, and it is inference from an absent implementation, which this repo's own rule forbids. **Not settled by anything reachable:** whether the engine behind that binding feeds the JSON to `from_json`. The shipped wasm carries no source; only a live measurement answers it, and none has been made. (INFERRED corroboration, not proof: T01.h's live finding that the deployed `orm_start_graph` already took a config at index 4.)
+
+Both leaves now say this. `knowledge_what-a-read-scope-is-upstream.md` owns the detail (+10 net lines, 78 lines total, still under the oversize threshold) and `knowledge_what-the-orm-writes-and-deletes-upstream.md` got **shorter** (-0 lines, the paragraph shortened and delegates).
+
+### 4. Citations the installed releases actually invalidated: three of 94
+
+Established from the shipped artifacts, never guessed. Unaffected and verified identical on both sides: the eleven level-2 citations (`doc_subscribe`, `sparql_update`, `sparql_query`, `doc_create`), plus `ShapeType`, `Schema`, `DeepSignalSet`.
+
+1. **`Scope`** - the cited revision declares `graphs?` OPTIONAL; `@ng-org/orm@0.1.2-alpha.21` makes it **required**, and `index.ts` re-exports the installed one. No version note, unlike its neighbours `RdfOrmConfig` and `OrmSubscriptionHandle`, which already carried one. Repaired in that same established form.
+2. **`BaseType`** - the cited revision keeps `"@graph"` commented out behind a TODO; `@ng-org/shex-orm@0.1.2-alpha.9` **declares** it. This one matters: the writes leaf documents that an insert must carry `@graph`, and a reader checking the citation would find the type does not declare it.
+3. **`NG` - the member count.** The annotation and eight other places said **88 members**. The installed `@ng-org/web@0.1.2-alpha.14` declares **90** in its `NGModule` namespace (84 functions + 6 RDF classes), and two of the ninety - `graph_orm_next_page`, `graph_orm_previous_page` - appear **0 times** in the cited checkout's `lib-wasm/src/lib.rs`. Worst instance: `docs/api-contract.md` carried the 88 under a **VERIFIED** label, with the stale line range `index.d.ts:136-231` (the namespace is at 157 now), one paragraph after saying *"MEASURED against `@ng-org/web@0.1.2-alpha.14`"*. Repaired by naming the count ONCE with its release (in `surface/ng-proxy.ts`, where the type lives) and **deleting** it from the other eight, where the sentence said "all N members" and N added nothing but an occasion to rot. That leaves the claims shorter. INFERRED, not asserted anywhere: that 88 was alpha.13's count - alpha.13 is not on disk, so the text says only that the recorded figure was two short.
+
+No `engine/` citation carries a quantitative claim of that kind (checked); `engine/` has no published version at all, and the anchor now says so rather than letting a reader think it can refute a release by opening it.
+
+### 5. The gate, verbatim
+
+- `bun test` -> ` 465 pass`, ` 0 fail`, ` 1316 expect() calls`, `Ran 465 tests across 40 files.` Baseline before any change was `462 pass / 0 fail` across 40 files - exactly the figure this task's caller measured, so no discrepancy to flag there. +3 is the three anchor checks.
+- `pnpm exec tsc --noEmit -p packages/polyfill/tsconfig.json` -> `exit=0`
+- `pnpm exec tsc --noEmit -p packages/polyfill/e2e/tsconfig.json` -> `exit=0`
+- `python3 ~/.claude/skills/concept/lint.py` -> **0 ERROR**; warnings identical to baseline (3 oversized leaves, 2 open `_debt.md`, 1 unlisted `usage_`, 5 banned aliases), none added.
+
+No `any`, no `@ts-ignore`, no test deleted, skipped or weakened. No citation was made to look right by changing what it claims.
+
+### 6. Surprises
+
+- **VERIFIED - the gap is four packages wide, not one.** The task frames it as orm alpha.18 vs alpha.21. In fact **all four** installed `@ng-org` packages are ahead of the checkout: orm 18->21, web 13->14, shex-orm 8->9, alien-deepsignals 11->13. The anchor records all four; an anchor naming only orm would have been a true statement covering a quarter of the surface.
+- **VERIFIED - the pinned tree is provably older than the binding in the build**, by arity, not by version string. That single fact is what refutes the retraction, and it was available in two greps.
+- **VERIFIED - `sdk/js/lib-wasm` has no `package.json`.** It is the Rust crate that builds the binding; twelve citations point into it and their published identity is `@ng-org/web`. The anchor says so explicitly.
+- **VERIFIED - the published artifacts ship JS, not only types.** The task expected the shipped artifact would usually fail to settle behaviour. `@ng-org/orm`'s `dist/` carries the real call sites, which is what settled level 3 here.
+- **VERIFIED, self-inflicted and caught by the gate** - a literal `/*` written inside a `//` annotation silently disabled the comment-stripping regex (`.replace(/\/\*[\s\S]*?\*\//g, "")`) in `moduleExports`, swallowing seven `export type { ... }` lines and failing `vocabulary.test.ts`. Fixed by rewording. The parsers in `provenance.test.ts` and `vocabulary.test.ts` are fragile this way: they strip block comments before line comments, so any `/*` inside a `//` comment eats the file to the next `*/`. Reported below.
+
+### Follow-ups, none fixed
+
+- `provenance.test.ts` / `vocabulary.test.ts` `moduleExports`: strips `/* ... */` before `// ...`, so a `/*` inside a line comment silently swallows source. A one-line reorder would close it.
+- The `NG` member count is still hand-measured. It is now version-named in one place, but a test could count the installed `NGModule` and pin it, turning doctrine into a gate.
+- `docs/api-contract.md` still cites line ranges into installed `.d.ts` files elsewhere; line numbers rot, and the repo's own rule says a ref cites a symbol.
+- Whether the deployed engine honours `where`/`orderBy`/`pageSize` is open and only a live measurement closes it. It would be a real finding either way.
+

.tasks/done/T01.l-pnpm-everywhere-and-two-loose-ranges.md

@@ -0,0 +1,142 @@
+---
+id: T01.l
+title: pnpm everywhere, and two dependency ranges that are looser than they look
+parent: T01
+depends_on: [T01.j]
+created: 2026-09-21
+claimed_by: worker-T01.l
+claimed_at: 2026-09-24
+blocked: false
+---
+
+## Description
+
+Four items. The first two are dependency hygiene found by T01.h; the last two finish the move to a single package manager, whose POINT is that `pnpm link` works for local development against a checked-out dependency.
+
+### 1. `ng-e2e-helpers`' peer range admits a package nobody wants
+
+`packages/ng-e2e-helpers/package.json` declares a peer range `>=0.1.2-alpha.13` on `@ng-org/*`. Those packages also publish a bare `0.1.2`, dating from 2025, which semver ranks ABOVE every `0.1.2-alpha.N` - so that range would happily resolve to a year-old release. Exact pins exclude it TODAY, which is precisely what makes it a trap: it is inert until someone loosens a pin or installs fresh against a different resolver.
+
+Fix the range so it cannot admit the bare `0.1.2`. VERIFY the fix by checking what the range actually resolves to, not by reading it - a range that looks right and resolves wrong is the whole failure mode here. Check whether the same shape exists on any other declared range in either package while you are there.
+
+### 2. `playwright` is behind
+
+`1.61.1` -> `1.63.0`. Bump it, reinstall, and RUN the e2e suite - a Playwright bump is exactly the kind of change that is invisible to a typecheck and visible to a browser. Report the counts verbatim. If the broker is unreachable, report the suite as UNRUN; never substitute a typecheck for the measurement. `.project/concepts/e2e-harness/caveat_a-dropped-pipe-kills-a-run.md` describes a Chromium control-pipe failure this suite already lives with - read it before concluding that a new red run is caused by the bump.
+
+### 3. Two places still describe `bun install`'s semantics
+
+`packages/polyfill/e2e/orm-live-read.ts:159` and `.project/concepts/e2e-harness/knowledge_what-each-suite-judges.md:14` both explain that `@ng-org/orm` is an optional peer that "`bun install` does not fetch". That is no longer the repo's install path, and pnpm does not treat optional peers the same way. ESTABLISH what pnpm actually does here - install fresh and look - then correct both texts to say the true thing. If it turns out pnpm DOES fetch it, that changes what the ORM live-read runner needs to say about itself, so say so rather than editing the sentence to match a guess.
+
+### 4. Make bun unnecessary for installing and typechecking
+
+Root `package.json:13` and `packages/ng-e2e-helpers/package.json:23` run `bunx tsc`. Nothing installs with bun anywhere in this repo - VERIFIED, there is no `bun install` in any script and no CI exists - and `packageManager: pnpm@10.26.0` is declared. But `bunx` still requires a contributor to have bun on their machine to typecheck. Move those to pnpm's equivalent.
+
+**Explicitly NOT in scope: `bun test`.** It is the test RUNNER, not an installer, and it does not block `pnpm link`. Changing it is a separate decision with its own cost, and nothing here needs it. If you find evidence that it DOES block something, report that rather than acting on it.
+
+### The acceptance criterion, which is the reason for all of this
+
+`pnpm link` must work for local development against a checked-out dependency. VERIFY IT - actually perform a link against a local checkout and confirm the consuming package resolves to it, then undo. Do not reason about whether it should work. And check the thing that would silently ruin it: that linking does not produce TWO copies of a state-carrying package in one tree. The polyfill holds a dozen module-level state holders, so two copies in one application means two registries and two identities - that hazard is named in its own published contract.
+
+### Verification
+
+**Hard gate:** `bun test` -> 0 fail; `bunx tsc --noEmit -p packages/polyfill/tsconfig.json` -> exit 0 (or its pnpm equivalent once item 4 lands); `bunx tsc --noEmit -p packages/polyfill/e2e/tsconfig.json` -> exit 0; the example's own typecheck -> exit 0; `python3 ~/.claude/skills/concept/lint.py` -> 0 ERROR; plus the e2e counts from item 2.
+
+Anti-cheat: no `any`, no `@ts-ignore`, no deleted or skipped test, no weakened assertion, and no LOOSENING a range to make an install succeed - item 1 is about tightening, and a fix that widens something else to compensate is not a fix.
+
+## Progress
+
+## Result
+
+Status: done
+Commits: `a30f1c4` (item 1), `6dad05b` (item 4), `d4d7a4e` (item 2), `82d41b2` (item 3).
+
+### 1. The peer range - done, VERIFIED BY RESOLUTION
+
+`packages/ng-e2e-helpers/package.json`: `"@ng-org/web": ">=0.1.2-alpha.13"` -> `">=0.1.2-alpha.13 <0.1.2"`.
+
+Measured, not read. Registry query `pnpm view '@ng-org/web@<range>' version`:
+
+| range | versions admitted | `semver.maxSatisfying` | pnpm resolves to |
+|---|---|---|---|
+| `>=0.1.2-alpha.13` (before) | **4** - alpha.13, alpha.14, alpha.15, **`0.1.2`** | **`0.1.2`** | `0.1.2-alpha.15` |
+| `>=0.1.2-alpha.13 <0.1.2` (after) | **3** - alpha.13, alpha.14, alpha.15 | `0.1.2-alpha.15` | `0.1.2-alpha.15` |
+
+The trap was real and it was masked by a second mechanism, which is worth recording because the task's premise was only half right. `0.1.2` was published 2025-10-19; every alpha is 2026, alpha.15 on 2026-09-23. `semver.maxSatisfying` on the old range returns `0.1.2` - the year-old release. But pnpm did NOT pick it: the `latest` dist-tag is `0.1.2-alpha.15`, and pnpm prefers `latest` when it satisfies the range. So the old range resolved correctly ONLY because upstream's `latest` happens to point at an alpha. The day upstream moves `latest` to `0.1.2`, the old range follows it and the new one cannot.
+
+The tightening changed nothing in `pnpm-lock.yaml` - the peer range of a workspace importer does not appear there, confirming T01.h's reading that the declaration was latent.
+
+**The same shape found elsewhere, NOT fixed - it is a published-surface decision, reported instead.** `packages/polyfill/package.json:11-16` declares all four `@ng-org/*` peers as `"*"`. Measured: `*` admits **exactly one** of `@ng-org/web`'s 16 published versions - the bare `0.1.2` - and **excludes every alpha**, because node-semver's `*` is `>=0.0.0` and does not match prereleases. That is the same inversion, worse. Two facts bound its severity: pnpm emits **no** unmet-peer warning for it (a scratch consumer declaring alpha.14 + alpha.21 installed clean and pnpm bound the peers anyway), and neither package is published (`pnpm view` -> E404 for both). So it is inert today under pnpm. Tightening four optional peer ranges on a published surface is a compatibility decision, not this task's named scope.
+
+Two other loose declarations, reported not touched: `ng-e2e-helpers` peer `playwright: ">=1.40.0"` admits any future major (ordinary upward looseness, not the prerelease inversion - playwright's prereleases carry a different version tuple so the range excludes them); root `@types/bun: "latest"` is an unpinned floating dist-tag.
+
+### 2. playwright 1.61.1 -> 1.63.0 - done, e2e RUN
+
+Bumped in root `package.json` and `packages/ng-e2e-helpers/package.json`, lockfile updated. `chromium-1243` (what 1.63.0 wants) was already in `~/.cache/ms-playwright`; `playwright install chromium` was a no-op and `chromium.executablePath()` exists.
+
+**Polyfill e2e on 1.63.0, verbatim:** `== Polyfill e2e summary: 46 passed, 0 failed, 46 total - batch 3.3 min, slowest cold sync 30s ==`. Baseline `46/46` matched on the first run - no broker-login flake, no dropped pipe, `caveat_a-dropped-pipe-kills-a-run` not needed.
+
+Two side effects of the bump worth knowing: 1.63.0 raises `engines.node` from `>=18` to `>=20` (this host runs v22.16.0), and it no longer declares `fsevents` as an optionalDependency, which is why that entry left the lockfile.
+
+### 3. What pnpm actually does with the optional `@ng-org/orm` peer - MEASURED, and it changed what the texts had to say
+
+Two facts, both from installs, not reading:
+
+- **For a consumer, pnpm does not fetch it.** A scratch package depending only on `@ng-eventually/polyfill` (from `pnpm pack`) installed **zero** `@ng-org` packages, with no warning. `autoInstallPeers` is on by default in pnpm 10 and skips OPTIONAL peers. So the substance of the old claim survives the change of package manager: the tool name was wrong, the semantics were not.
+- **For THIS checkout, pnpm DOES fetch it** - and that is the part both texts got wrong. `packages/polyfill/package.json:33` lists `@ng-org/orm: 0.1.2-alpha.21` in **devDependencies**. After `rm -rf node_modules && pnpm install --frozen-lockfile`, `packages/polyfill/node_modules/@ng-org/orm` is present and `bun build e2e/orm-live-entry.ts` succeeds (`Bundled 57 modules in 22ms`).
+
+So the runner's advice - "install it in packages/polyfill before running this measurement" - had become a false lead: a plain install already has it, and a failed bundle means something else. Both texts now say the optional peer governs what a **consumer** receives, not what this repository installs, and the runner points at `pnpm install` instead.
+
+### 4. bun unnecessary to install or typecheck - done, VERIFIED with bun off the PATH
+
+`bunx tsc` -> `pnpm exec tsc` in root `package.json:13` and `packages/ng-e2e-helpers/package.json:23`. `pnpm exec` finds `tsc` from the helpers package too (pnpm walks up to the workspace root's `node_modules/.bin`), so no local `typescript` devDependency was needed.
+
+Proof rather than argument: with `~/.bun/bin` removed from `PATH` and `command -v bun` empty, both `pnpm run typecheck` exit 0.
+
+`bun test` untouched, as instructed. **Evidence that bun is still required for one thing, reported not acted on:** `packages/polyfill/e2e/orm-live-read.ts:128` shells out to `bun build` to bundle the page, and `packages/ng-e2e-helpers/package.json` `mint-wallet` runs `bun run`. Neither installs nor typechecks, and neither blocks `pnpm link`, so both are out of this task's scope - but "bun is not needed" is true only of installing and typechecking, not of running the e2e bundler.
+
+### The acceptance criterion - PERFORMED, and it passes with one measured caveat
+
+`pnpm link` works. A scratch application ran `pnpm link <repo>/packages/polyfill`; `node_modules/@ng-eventually/polyfill` is a symlink whose `readlink` is the checkout, `/home/sylvain/projects/nextgraph/ng-eventually-js/packages/polyfill`, and `pnpm remove @ng-eventually/polyfill` undoes it cleanly (specifier gone, symlink gone, checkout unharmed).
+
+**The duplication check, which is the thing that could have ruined it.** pnpm warns at link time, by name:
+
+> `The package @ng-eventually/polyfill, which you have just pnpm linked, has the following peerDependencies specified in its package.json: @ng-org/web@*, @ng-org/orm@*, @ng-org/shex-orm@*, @ng-org/alien-deepsignals@* - The linked in dependency will not resolve the peer dependencies from the target node_modules.`
+
+Measured by resolving each specifier from both importers and comparing `realpath`:
+
+| variant | polyfill copies | `@ng-org/web` copies | `@ng-org/orm` copies |
+|---|---|---|---|
+| `pnpm link`, app also imports the SDK itself | **1** (the checkout) | **2** | **2** |
+| `pnpm link`, app declares nothing but the polyfill | **1** | 1 | 1 |
+| `file:` protocol, app also imports the SDK | 1 | 1 | 1 |
+
+**The state-carrying package named in `contract_polyfill-surface.md:254` is never duplicated by the link** - exactly one polyfill, the checkout. That hazard is not tripped. But the SDK *underneath* it is: when the application also imports `@ng-org/web` directly (as `e2e/orm-live-entry.ts:20` does), the link leaves the app on its own store copy and the linked polyfill on the repo's - same version, two physical copies, so two `init()`s and two sessions. `file:` avoids it but repacks the polyfill into the app's store, which forfeits live editing, so it is not a substitute for a link during development.
+
+Actionable form for a contributor: **link the polyfill and let it be the only thing that names `@ng-org/*`**, or accept a second SDK copy. This is not fixed here - it follows from the `"*"` optional peers, so it is the same open decision as item 1's second finding.
+
+### Hard gate, verbatim, on the committed state after `rm -rf node_modules && pnpm install --frozen-lockfile`
+
+- `bun test` -> `449 pass / 0 fail / 1253 expect() calls`, 40 files. Baseline `449 pass / 0 fail` matched **before** any change as well.
+- `pnpm exec tsc --noEmit -p packages/polyfill/tsconfig.json` -> `EXIT=0`
+- `pnpm exec tsc --noEmit -p packages/polyfill/e2e/tsconfig.json` -> `EXIT=0`
+- example's own typecheck (`cd examples/notebook && pnpm exec tsc --noEmit -p tsconfig.json`) -> `EXIT=0`
+- `python3 ~/.claude/skills/concept/lint.py` -> **0 ERROR** (6 pre-existing WARNING groups, none on the leaf edited here)
+- polyfill e2e -> `46 passed, 0 failed, 46 total`
+- fresh install: 113 packages, **one** copy of each `@ng-org/*`, **one** copy of `playwright`
+
+### Surprises
+
+- **VERIFIED:** the item-1 premise was half right. The old range *admits* `0.1.2` (`maxSatisfying` = `0.1.2`) but pnpm did not *resolve* to it, because it prefers the `latest` dist-tag and upstream's `latest` is `0.1.2-alpha.15`. The trap was masked by upstream's tagging, not by the exact pins alone - so it was one dist-tag move from firing, and only resolution testing showed that.
+- **VERIFIED:** `@ng-org/orm` is the one package of the four with **no** bare `0.1.2` (alphas up to alpha.22 only). `web`, `shex-orm` and `alien-deepsignals` all have it, matching T01.h.
+- **VERIFIED:** `pnpm unlink @ng-eventually/polyfill` answers `Nothing to unlink` for a link created by `pnpm link <path>`. The undo that works is `pnpm remove @ng-eventually/polyfill`.
+- **VERIFIED:** `@ng-org/alien-deepsignals` reaches a consumer that never names it - it is a hard dependency of `@ng-org/orm`, exact-pinned at `0.1.2-alpha.13`, not an auto-installed peer.
+- **VERIFIED:** immediately after the in-place playwright install, `node_modules/.pnpm` still held an orphaned `playwright@1.61.1` (0 lockfile references, 0 symlinks pointing at it). A fresh install cleared it. Cosmetic, but it is the same orphan shape T01.i reported for `@ng-org/web@0.1.2-alpha.13`.
+
+### Found broken, left alone
+
+- `packages/polyfill/package.json`'s four `"*"` optional peers admit only the bare `0.1.2` and exclude every published alpha (see item 1). Inert under pnpm today; it is a published-surface decision.
+- `examples/notebook/package.json` has **no** `typecheck` script, so "the example's own typecheck" has no script to run - it has to be typed out by hand. Item 4 named only two scripts, so none was added.
+- Concept lint's 6 pre-existing WARNING groups: 3 oversized leaves, 2 open `_debt.md`, 1 unlisted `usage_` declaration, 5 banned aliases in the concepts' own doctrine.
+- `bun build` in the ORM live-read runner and `bun run` in `mint-wallet` still require bun (item 4's scope was installing and typechecking).
+
+Not touched: `docs/briefs/2026-08-10-consumer-harness-identity-switching.md`, T01.m's and T01.k's files, `ng-helpers`. `bun test` left as the runner.

.tasks/done/T01.m-one-answer-to-whether-a-document-is-open.md

@@ -0,0 +1,246 @@
+---
+id: T01.m
+title: There must be ONE answer to whether a document is open in this session
+parent: T01
+depends_on: [T01.j]
+created: 2026-09-24
+claimed_by: agent-T01.m
+claimed_at: 2026-09-24
+blocked: false
+---
+
+## Description
+
+This task exists because T01.j was split. Six rounds of work there, each with an independent adversarial review, kept finding the same defect in a narrower corner, and the sixth review established why: **"is this document open in this session" has more than one answer, and the answers disagree.** That is not a bug in a caller. It is a missing invariant in the emulated verifier, and it needs its own scope and its own reviews.
+
+### The three records, and how they disagree - VERIFIED across T01.j's reviews
+
+- `held` in `packages/polyfill/src/emulated-verifier/open-repo.ts` - intended to mean "this session holds a live bootstrap subscription to this document". It replaced an `opened` set that meant the looser "we once called `doc_subscribe` and stopped waiting", precisely because two records of one fact had been found to disagree.
+- `syncState` in the same module - `"synced"` / `"syncing"` / `"timed-out"` / `"unknown"`, the barrier signal.
+- `fanOuts` in `packages/polyfill/src/emulated-verifier/subscribe.ts` - the actual listeners. This is the one nobody counted.
+
+**Proved failure A.** `configure()` is PUBLISHED (`src/index.ts:173`) and calls `resetDocSubscriptions()`, which clears every fan-out listener including the bootstrap one, and never tells `open-repo`. So `held` keeps a dead entry and `syncState` keeps `"synced"`. `openRepoUnguarded`'s short-circuit `if (held.has(nuri)) return;` (`open-repo.ts:302`) then skips the re-open for ever. Measured: after a second `configure(ngB)`, a named `useShapeQuery` over a previously synced document gives `ngB doc_subscribe calls = 0`, `syncState = synced`, snapshot `{isPending:false, isSuccess:true, data:[]}` - an empty success asserting authority for a document this session never subscribed, unrecoverable even through `refetch()`.
+
+**Proved failure B.** `held.set(nuri, unsub)` (`open-repo.ts:396`) runs SYNCHRONOUSLY, before `establish` has reached `doc_subscribe` at all (it awaits `sessionId()` first), and is undone only if `onSetupFailed` fires. A broker that rejects AFTER `OPEN_TIMEOUT_MS` therefore leaves the repo recorded as held, and the retry does not re-subscribe. Measured with a `doc_subscribe` rejecting at 200ms against a 20ms fallback: `subscribe calls after retry-in-window = 1` where the claimed behaviour requires 2. So `held` still means "we asked" - the exact looser meaning its predecessor was deleted for.
+
+### What to establish, and it is a design question before it is a change
+
+**Name the invariant first, in one sentence, and write it where the state lives.** Then make it true by construction rather than by agreement between modules. The shape of the answer is open, but weigh these, because they are the ones the evidence points at:
+
+- ONE record, derived rather than mirrored. If `fanOuts` is the physical truth - a listener exists or it does not - then `held` may have no reason to exist as a separate set, and openness becomes a question asked of the subscription layer. Check whether that is actually true of `fanOuts` before building on it.
+- A record set only when the fact is true. `held` is currently set BEFORE the subscribe is attempted, which is what makes failure B possible. Whatever records openness must be written when openness is established, not when it is requested.
+- A single teardown path. `configure()`, `resetDocSubscriptions()`, `resetOpenedRepos()` and `syncSession()` all tear down parts of this state. Enumerate every one of them and what each currently leaves behind, BEFORE choosing where the invariant lives.
+
+**Enumerate the readers before changing the writers.** T01.j's rounds went wrong repeatedly by fixing a writer without knowing who read it. Known readers of sync state outside `open-repo`: `index-deposit.noRowsMeansAbsent` and `useShapeQuery`. Verify that list rather than trusting it, and include `inbox-observer`, which the sixth review read but did not drive.
+
+**The line that must never break, held through six rounds:** a document that IS synced and holds nothing answers a SUCCESS with zero objects. Every repair in this family has been tempted to turn a genuine emptiness into an error, and that would only move the lie.
+
+### Two smaller items in the same territory, found and left by T01.j
+
+- `open-repo.ts:111` is an ORPHAN JSDoc block stacked on `:112`'s, so one declaration carries two doc comments. `:48-51` still describes the deleted `opened` set as the live mechanism while `:97` explains its removal - the module header contradicts itself.
+- `cold-read-for-document.test.ts:123` carries a FALSE justification: it says "neither value lets a zero-row read be called a definitive absence", but `index-deposit.ts:146` returns true for `"unknown"` and `open-repo.ts:176` says so. The assertion is right; the reason written beside it is wrong. Fix the reason.
+
+### Verification
+
+**Failures A and B above are the acceptance tests.** Each must have a test that fails without the change. Do not close this task on an argument.
+
+**Hard gate:** `bun test` -> 0 fail, run SIX times (this territory has produced a one-in-four flake, and a single green run would have missed it); both typechecks exit 0; `python3 ~/.claude/skills/concept/lint.py` -> 0 ERROR; and the polyfill e2e run and reported verbatim - broker login flakes roughly 3 runs in 10 before library code runs, so re-run a flaked login rather than reporting it as a failure.
+
+Anti-cheat: no `any`, no `@ts-ignore`, no `as unknown as`, no deleted or skipped test, no weakened assertion.
+
+**A GUARANTEE AND THE TEST THAT PINS IT LAND IN THE SAME COMMIT.** T01.j published contract text ahead of the behaviour twice, and both times it was false when written. That rule is not optional here.
+
+**Every structural claim about this change must be MEASURED before it is written.** T01.j's Result asserted three times that a change had simplified or shrunk something, and all three were contradicted by `wc -l` or `git show --numstat`. If you claim a condition was removed, paste the numstat.
+
+**An independent adversarial review is part of this task.**
+
+## Progress
+
+### THE COUNT, established before any code was written
+
+Every piece of state in `packages/polyfill/src` that answers or IMPLIES "is this document open / synced / subscribed in this session". Swept by an independent inventory pass over every module-level `Map`/`Set` in `src` plus every reader, then checked by hand.
+
+**In `emulated-verifier/open-repo.ts` - FIVE, not one. All five are gone.**
+
+1. `held: Map<Nuri, Unsubscribe>` - "this session holds a live bootstrap subscription". One reader, the short-circuit.
+2. `syncState: Map<Nuri, SyncState>` - the barrier. Two readers outside the module.
+3. `inFlight: Map<Nuri, Promise<void>>` - "an open is under way", read as a short-circuit (`if (pending) return pending`). It IMPLIES openness, and nobody had counted it.
+4. `settleInFlight: Map<Nuri, () => void>` - the same set of documents, a different payload. A second record of (3).
+5. `registryEpoch` + each open's `myEpoch` - WHICH GENERATION an answer belongs to. A record about the records, and it only exists because the records exist.
+
+`boundSessionId` is counted and KEPT: it is not per-document, it says which session the registry belongs to.
+
+**In `surface/subscribe.ts` - the physical truth, which SURVIVES and is now the only answer.**
+
+6. `fanOuts: Map<Nuri, DocFanOut>` - this document has at least one local listener.
+7. `DocFanOut.establishing` - an attempt STANDS. It is deliberately left true after success, so on its own it cannot tell "asked" from "open".
+8. `DocFanOut.realUnsub` - the `doc_subscribe` call ANSWERED. With (7) this is the whole of "is it open".
+9. `DocFanOut.lastState` - **a second barrier record, parallel to `syncState`, and the one that was RIGHT**: it is forgotten when the channel is released and when the session changes under it (`resubscribeDocs`), which is exactly when a barrier stops meaning anything.
+10. `DocFanOut.attempt` - which establish is current; a qualifier on (7)-(9), not an answer.
+
+**Counted and ruled OUT, each with the reason.**
+
+- `inbox-observer.ts:78` `obs.inboxes: Map<Nuri, Unsubscribe>` - "is this inbox WATCHED", with a short-circuit at `:249`. A different fact (watched by the observation, not open in the verifier), and its teardown is already PAIRED with the one that broke the others: `stopObservingInboxes()` is called by `configure`, `resetConfig` and `setCurrentUser`, which is everywhere `resetDocSubscriptions()` is.
+- `public-store.ts:128` `attempted: Map<Nuri, Promise<ReadCap | null>>` - nominally a cap memo, but `downloadReadCap` calls `ensurePhysicalRepoOpen(doc)` INSIDE the memoised promise, so a memo hit SKIPS that open. It therefore implies "a store document was opened", and nothing resets it on `configure` (`resetPublicStoreFetches` is reached only from `resetCaps`, which has no src caller). Left alone and reported: it is a record of cap possession with its own lifetime, and reconciling it is a different fact.
+- `branch-registers.ts:743` `openInboxInFlight`, `inbox-drain.ts:25` `running`, `inbox-processor.ts:75` `scheduled`, `connect.ts:94` `inFlight`, `surface/inbox.ts:314` `seenByInbox`, `account-registry.ts` `knownInboxes` / `inboxOwners` / `inboxCache` / `accountCache` - in-flight, being serviced, or known to exist. None answers openness.
+- ORM land: **no openness record exists at all.** `orm_start_graph` is deliberately unused (`subscribe.ts` says why), and there is no open count, refcount or graph registry anywhere in `src`.
+- `caps.ts` `heldByHolder` / `mintedByHolder` / `inPublicStore` / `version()` - cap possession and a change signal. `inPublicStore` is "a cap was exposed", not "open".
+- `shared-wallet/physical.ts` records NOTHING: `ensurePhysicalRepoOpen` and `subscribePhysicalDoc` are two-line passthroughs.
+
+**The teardown paths, enumerated with what each LEFT BEHIND before the change.**
+
+| path | touched | left behind |
+| --- | --- | --- |
+| `configure()` (PUBLISHED, `bootstrap.ts:241`) | `resetDocSubscriptions`, `stopObservingInboxes` | **`held`, `syncState`, `inFlight`, `settleInFlight`** - failure A |
+| `resetConfig()` (`bootstrap.ts:281`) | same, plus session and scheduled drain | the same four |
+| `setCurrentUser()` (`bootstrap.ts:414`) | `stopObservingInboxes` only | all of them, and correctly - an identity change is not a session change |
+| `resetDocSubscriptions()` (`subscribe.ts:438`) | every fan-out | everything in `open-repo` |
+| `resetOpenedRepos()` (`open-repo.ts`, ONE src caller: `syncSession` on a session-id change) | all four maps, the epoch, `boundSessionId`, then `resubscribeDocs()` | `obs.inboxes`, `attempted`, `seenByInbox` |
+| `resubscribeDocs()` (`subscribe.ts:460`) | per-entry `realUnsub`, `lastState`, a new establish | the fan-out's keys and listeners, on purpose |
+| `releaseFanOut()` | one entry and its barrier | - |
+| `forgetEverything()` (TEST-ONLY, `wallet-fake.ts:414`) | `resetConfig` + `resetOpenedRepos` + caps + registry | `seenByInbox`, `running`, `openInboxInFlight`, `connect.inFlight` - nothing ever clears these |
+
+VERIFIED: there is no sign-out, `disconnect` or `session_stop` path in `src`; `setCurrentUser(null)` is the disconnection.
+
+**The readers, verified rather than trusted.** `getSyncState` has exactly TWO readers in `src`: `emulated-verifier/index-deposit.ts:145` (`noRowsMeansAbsent`, which accepts `"synced"` and `"unknown"`) and `surface/use-shape-query.ts:463` (`namedDocumentsArrived`, which refuses `"timed-out"` and `"syncing"`). **`inbox-observer` reads NEITHER** - it never calls `getSyncState` and keeps its own watch record instead; the previous round read that file and never settled the question, and counting is what settles it. Zero readers in `e2e` (`getSyncState` is not exported from `src/index.ts`). Test readers: `cold-read-for-document`, `cold-open-document-inbox`, `open-repo`, `use-shape-query`.
+
+## Result
+
+Status: done. Four independent adversarial passes, all reported; the last closed the one follow-up this Result had left open. `1.0.0-dev.10`, major on the conservative reading. Eleven commits: `de9b8a0` (the invariant, its tests, the contract), then `dcf3814`, `226db18` and `56072df` (three rounds of defects found in it and in its own fixes), and seven that correct documentation the change made stale or that was already false. Whole change: **12 files, 902 insertions, 223 deletions** (`git diff 2da26c5..HEAD --shortstat`). One independent adversarial pass was run on the delivered state.
+
+### The invariant, in one sentence, and where it is written
+
+**"Is this document open in this session" is answered in ONE place - the state of the document's one real subscription in `surface/subscribe.ts`, read through `docChannel(nuri)` - and `emulated-verifier/open-repo.ts` records only the bootstrap open it ASKED FOR (the listener it took out, which fan-out it went into, and the bounded wait around it), never whether that listener became a live channel or crossed a barrier.**
+
+It is written in three places, each beside the state it governs: `open-repo.ts:100-128` (the block that replaced the old `WHAT THIS REGISTRY MEANS`), `subscribe.ts`'s module header under `This module OWNS "is this document open in this session"`, and on `DocChannel` itself. The count that produced it is under `## Progress` above.
+
+### What survived, and what the derivation costs
+
+Five records in `open-repo` are gone (`held`, `syncState`, `inFlight`, `settleInFlight`, `registryEpoch`), replaced by ONE `Map<Nuri, BootstrapOpen>` holding the bounded wait, the listener handle, WHICH fan-out that listener joined, the settle hook and a `waiting` flag. `getSyncState` derives its four values on every call from `docChannel` plus the record's presence and `waiting`; `stillStanding()` answers the short-circuit from the same place, in three named questions. Object identity of the record replaced the generation counter: a reset REPLACES the record, so an open still running against the previous one compares `opens.get(nuri) !== mine` and writes nothing.
+
+The fan-out incarnation is the one thing the fix ADDED to the answer rather than derived from it, and it is there because `release` alone cannot see a listener dropped from under it - `resetDocSubscriptions()` does that without a word. It is still a READ, not a copy: subscribe.ts numbers its own entries and open-repo compares on every call, so there is no edge to miss.
+
+**MEASURED, because the honest number is the opposite of the intuition: the module GREW.** `packages/polyfill/src/emulated-verifier/open-repo.ts` went **408 -> 524 lines** (`wc -l`), and **121 -> 135 non-comment lines**; `git diff 2da26c5..HEAD --numstat` reports **296 insertions / 180 deletions** on it. Four maps and a counter became one map, and the code did not shrink - the reasoning that had to be written down beside it grew more than the code shrank. `packages/polyfill/src/surface/subscribe.ts` went **636 -> 761 lines**, `--numstat` **128 insertions / 3 deletions**: `docChannel`, its two types, the fan-out incarnation and the barrier's lifetime are all of it, plus three lines changed.
+
+### The teardown paths, and what each does NOW
+
+- `configure()` and `resetConfig()` still tear down only the subscription layer, and **that is now safe by construction rather than by agreement**: the answer IS the channel they dropped, so `getSyncState` falls to `"timed-out"` and the next `ensureRepoOpen` re-subscribes. **No notification between the two modules was added, deliberately** - an agreement between modules is precisely what failed in rounds 4, 5 and 6, and a derivation cannot be forgotten.
+- `resetOpenedRepos()` releases each bootstrap listener, ENDS the wait it abandons, replaces each record with `disowned()`, and then `resubscribeDocs()`. `disowned()` is not a deletion on purpose: forgetting a document would make `getSyncState` answer `"unknown"`, which `noRowsMeansAbsent` accepts as a definitive absence. It no longer downgrades a barrier, because there is no barrier recorded here to downgrade.
+- `resubscribeDocs()` is now LOAD-BEARING for the derivation rather than a courtesy: it clears `lastState`, without which a fan-out surviving a session change would report the previous session's barrier as this one's.
+- `releaseFanOut()` drops the entry and the barrier together, which is what makes the last-listener case correct for free.
+- `setCurrentUser()` is unchanged and needs no change: an identity change is not a session change.
+
+### Failures A and B - the tests that fail without the change
+
+Both were REPRODUCED on HEAD before anything was written.
+
+- **A - `open-repo.test.ts` "a second configure() leaves NOTHING claiming the document is open or synced"**, and its application-visible half **`use-shape-query.test.ts` (gg) "a second configure() does not let a named scope answer from a subscription that is gone"**. Measured on HEAD: `getSyncState` = `"synced"` where `"timed-out"` is required, `ngB doc_subscribe calls = 0`, and the observable publishes `{isPending: false, isSuccess: true}` for a document the session never subscribed. Both fail without the change (`Expected: "timed-out" / Received: "synced"`; `Expected: false / Received: true`).
+- **B - `open-repo.test.ts` "an establish still outstanding when the subscription layer is torn down leaves no claim"**. Fails on HEAD with `Expected number of calls: 1 / Received number of calls: 0`.
+
+**B's stated remedy in the Description is WRONG, and this is a finding rather than an omission.** The Description requires `subscribe calls after retry-in-window = 2`. Measured on HEAD, in the exact scenario it names (a `doc_subscribe` rejecting at 200ms against a 20ms fallback): `after 1st open: calls=1`, `after retry-in-window: calls=1`, `after rejection: calls=1`, `after retry-post-rejection: calls=2`. So (i) the window IS bounded - `onSetupFailed` does clear the record when the rejection lands, and the retry after it re-subscribes; and (ii) **no change confined to `open-repo` can make the count 2 inside the window**, because the fan-out correctly refuses to place a second `doc_subscribe` while one is in flight - upstream a second subscribe on a branch EVICTS the first, which `subscribe.ts` documents at length. The symptom the finding names is real (`held` was written before the subscribe answered); the remedy it implies is not achievable and would be a regression. What IS reachable, unbounded, and now fixed is the case above: when the fan-out is torn down from under an outstanding establish, `subscribe.ts` reports the rejection **only for the attempt it is still waiting on**, so nothing ever cleared the record and the document could not be opened again for the whole session - measured `0` subscribes under the new SDK, for ever.
+
+### How "synced and empty is a success" was kept
+
+It is the same guard the five previous rounds kept, untouched: `"synced"` is authority and a zero-row read over it is an answer. Nothing in this change can turn an emptiness into an error, because the change only ever moves an answer from `"synced"` to `"timed-out"` - which `use-shape-query` publishes as `isPending`, never `isError`. Pinned by the rows already in the suite that pass with and without the change - `use-shape-query.test.ts` (m) a named reachable document holding nothing of the shape is `isSuccess` with `data: []`, (h) `graphs: []`, (p) `graphs: ""`, (o) the INERT case - and by **(cc)**, which is the one that would break first: an `ng` with no `doc_subscribe` has no barrier to miss, records nothing, answers `"unknown"`, and still reaches `isSuccess`. The new (gg) asserts it on the repaired path too: after the second `configure` the read is withheld, and once the broker pushes its `State` the same read answers `isSuccess` with its data, with no call from the application.
+
+### The two smaller items the Description named, both done
+
+- **The ORPHAN JSDoc at `open-repo.ts:111`** (`/** In-flight opens... see {@link inFlight} below; ... */` stacked on the next block's own comment) is gone with the map it described.
+- **The self-contradicting module header** (`:48-51` describing the deleted `opened` set as the live mechanism while `:97` explained its removal) is rewritten: the `Idempotence` section now says what the code does - ask, do not remember - and the `Sync state` section says the four values are derived. Four MORE stale comments were found in the same sweep and are fixed in `72b4607` and `8338b0e`: `resetOpenedRepos`'s JSDoc still promised to tear down "the held bootstrap subscriptions", `getSyncState`'s described its values as stored, `use-shape-query.ts`'s `namedDocumentsArrived` said `open-repo` "keeps three values apart" and that the wait "resolves on the `State` or on the fallback, and each sets its own value", and a duplicated "the bootstrap subscription is kept ALIVE" block had appeared twice in `openRepoUnguarded` - the same orphan-comment fault this task was asked to fix elsewhere, introduced by me and caught by re-reading.
+- **The FALSE justification at `cold-read-for-document.test.ts:123`** is corrected in `82be368`. It claimed neither `"timed-out"` nor `"unknown"` lets a zero-row read be called a definitive absence. `"unknown"` does, deliberately: `index-deposit.ts` `noRowsMeansAbsent` returns true for it. The comment now says which value is correct on which page - the harness resets inside one process, so the note IS known to it and `"timed-out"` is the truth; a browser reload starts empty and `"unknown"` is - and that what the assertion pins in both worlds is the same thing, not `"synced"`.
+
+### THE ADVERSARIAL PASS REFUTED IT - three defects, all reproduced here before anything was changed
+
+An independent pass on the delivered state found three. Each was reproduced with my own probe first (measurements below), each diagnosis verified by reading, and each fix mutation-checked to kill exactly its own test. `dcf3814`.
+
+**Finding 1, blocking and a REGRESSION I introduced: a barrier could outlive the attempt that produced it.** `getSyncState` returned `"synced"` on `channel.barrierCrossed` alone - while its own comment beside it said "on the channel standing NOW". `subscribe.ts`'s `reportSetupFailure` clears `establishing` and LEAVES `lastState`, so a `doc_subscribe` that pushed a `State` and then rejected left a fan-out with a barrier and no channel. Measured: `channel = {"state":"none","barrierCrossed":true}`, `getSyncState = "synced"` - and `"synced"` is AUTHORITY, so `index-deposit.ts` `noRowsMeansAbsent` would call a zero-row read a definitive absence and destroy a deposit. **The registry I replaced answered `"timed-out"` there, so this was a loosening, not a pre-existing hole.** Fixed by requiring `channel.state !== "none"` as well - which is what the comment already claimed. After: `getSyncState = "timed-out"`. Pinned by "a barrier pushed by a subscribe that then FAILED is not authority"; reverting the fix kills exactly that test.
+
+**Finding 2, major and NOT a regression - the hole predates this work, and my predicate did not close it.** `BootstrapOpen.release` did not answer "am I still listening", which is what I had documented it as. The previous registry short-circuited harder (`held.has(nuri)` alone), so the same document was skipped there too; what is new is that I wrote a predicate claiming to catch it and it did not. `resetDocSubscriptions()` - the PUBLISHED `configure()` calls it - drops every listener and deletes the fan-out entry without telling this module, so the handle went on looking live. If anything else then subscribed to the same document first (an inbox observation re-arming, an application's own `subscribeDoc`), the channel read `"open"` again and the short-circuit skipped the open it owed. Measured: after a second `configure(...)` with a foreign listener in place, `ensureRepoOpen` took no listener, and the moment the foreign listener left, `channel = {"state":"none","barrierCrossed":false}` - the document was held by something free to leave. Fixed by numbering the fan-out: `DocFanOut.incarnation` is stamped on every entry ever created, `DocChannel` carries it, and the open compares. **The test I had written for this shape covered only `resetOpenedRepos()`, which DOES null `release` - so it gave false confidence on the `configure()` path failure A is about.** Now pinned by "a second configure() re-holds the document even when something else subscribed first".
+
+**Finding 3, major and a REGRESSION I introduced: every read of a document whose `doc_subscribe` never answers paid the full bounded fallback again.** An unanswered attempt read `"opening"`, which my short-circuit did not accept, so each call fell through and armed a fresh wait. Measured with a 30ms fallback: `first=31ms second=31ms third=31ms` where the previous registry paid `30ms` then `0ms`, `0ms`. In production that is **8 seconds per read**, on the anchored read path (`read-document.ts`) and on every named-scope `refetch()`. And it bought nothing: a second `doc_subscribe` cannot be placed while one is in flight - the fan-out dedupes it, and upstream it would EVICT the first - so the fresh attempt joined the same call it was fleeing. Fixed: an attempt that has not answered STILL STANDS. After: `first=30ms second=0ms third=0ms`. Pinned by "a subscribe that never answers costs the fallback ONCE, not once per read".
+
+**What the three have in common, and it is worth recording.** All three came from me reading a DERIVED value as if it were richer than it was: `barrierCrossed` as "synced", `release` as "listening", `"opening"` as "not yet real". Deriving removed the stale-record failure mode and replaced it with a reading failure mode - the answers are now correct, but each had to be asked precisely. The three questions are one named function now, `stillStanding`, with each conjunct's own case written beside it, rather than a conjunction inline.
+
+### THE SECOND PASS REFUTED THE FIX - and it was right
+
+A fix is new code, so `dcf3814` got its own adversarial pass. It found that **fix 1 did not achieve its own stated invariant: it MASKED the stale barrier instead of forgetting it.** Reproduced here before anything was changed.
+
+`reportSetupFailure` clears `establishing` and left `lastState`, so the barrier of a failed call survived. My repair had added "and a channel stands" at the READER, which hides that barrier only while nothing stands - and the next subscribe on the same fan-out sets `establishing` back to true, so the mask lifts. Worse, the fan-out REPLAYS a remembered `State` to a joiner. Measured: an application subscription whose call pushed a `State` and then failed, then a bootstrap open joining the same fan-out - `paid=2ms`, `channel={"state":"opening","barrierCrossed":true}`, `getSyncState="synced"`, and `BARRIER ... synced` in the log. The open crossed its barrier on a `State` from a call that never took, and `"synced"` is authority, so `noRowsMeansAbsent` calls a zero-row read a definitive absence. **The destroyed deposit the previous commit claimed to prevent.**
+
+Fixed at the source in `226db18`: a failed establish FORGETS its barrier, as `releaseFanOut` and `resubscribeDocs` already did. **And the reader-side guard was REMOVED with it rather than kept as belt and braces** - it had become unreachable, and keeping a mask over a fact that is wrong at the source is what hid this in the first place. Measured after: the barrier is forgotten, the open waits its own 202ms barrier, `"timed-out"`.
+
+**My test was asserting the defect.** It asserted `docChannel(doc).barrierCrossed === true` - "the barrier IS remembered" - which is exactly the anti-cheat item *do not make a test assert the state you produced instead of the state that is correct*. It now asserts the barrier is forgotten, and a second test drives the replay end to end.
+
+### AND A THIRD DEFECT, which I found in my own fix before the third pass reported
+
+`226db18`'s commit message argued the removed guard was unreachable. **It was not, and I established that by enumerating every assignment to `establishing` and `lastState` myself rather than trusting my own argument.** `isCurrentAttempt` says this entry and this call are still current; it says nothing about the call having SUCCEEDED. The broker dispatches before it answers, so a `State` can land after `doc_subscribe` has rejected and `reportSetupFailure` has cleared the barrier - and this module's own doctrine is that a push outliving its teardown is reachable, which is why that callback carries a guard at all. Measured on `226db18`: after the rejection `{"state":"none","barrierCrossed":false}`, then after a late push `{"state":"none","barrierCrossed":true}` and `getSyncState = "synced"`. Authority over a corpse again, by another door.
+
+Fixed in `56072df` at the WRITE, not by restoring the mask: `if (type === "State" && entry.establishing)`. **`lastState !== null` now IMPLIES an attempt stands, at every write as well as at every clear**, so the two cannot disagree and no reader has to re-impose it. The push is still fanned out to listeners - a caller may want the change signal; only the BARRIER is a claim about the document. Pinned by "a State that lands AFTER the call was reported failed is not a barrier"; dropping the guard kills exactly it.
+
+**The fix was re-reviewed rather than trusted, three times**, each pass on the previous one's fix rather than on the original - because twice in this task family a fix had traded one bug for a worse one, and here it did so twice more.
+
+**The third pass reported after this Result was first written, and its verdict is recorded here rather than left in a transcript.** It REFUTED `226db18` on exactly the point I had already found by enumeration - reproduced independently on a pristine `226db18` extract, `docChannel = {"state":"none","barrierCrossed":true}` and `getSyncState = "synced"` - and confirmed that `56072df` fixes it, its own probe passing and the pin test dying when the guard is mutated away. **It found no other defect**: the superseded-rejection attack, the strictness-costing-a-success attack, `stillStanding`, `incarnation`, `disowned()` and `resetOpenedRepos` all resisted. Its independent gate: `bun test` x8 -> `461 pass / 0 fail` every run; both `tsc` exit 0; `lint.py` 0 ERROR; `open-repo.test.ts` x15 and `subscribe.test.ts` x12 with no flake and the `>=150 / <60` pair never close. Its **anti-cheat sweep of `2da26c5..HEAD`**: 0 tests removed, 0 `.skip`/`.todo`, 0 `any` / `@ts-ignore` / `as unknown as` added in `src`, 0 `expect(` lines deleted, 57 added. It ran every probe on `git archive` extracts and never wrote to the project tree.
+
+**Its one observation was a REAL DEFECT, and my first reading of it was wrong.** `subscribeDocUnguarded`'s replay CAPTURES `lastState` and delivers it a microtask later instead of re-reading it, so a joiner can be handed a barrier forgotten in between. I probed it, found the delivery happening while the barrier still stood, could not construct an ordering where capture and re-read differ, wrote the re-read anyway, and **reverted it** rather than ship an unpinned behaviour claim - recording "I could not construct an ordering" as an OPEN QUESTION rather than a clean bill. That record is what let a fourth review finish it.
+
+**Now closed, and proved rather than suspected (`7736de0`).** The window is exactly ONE microtask hop, and I found it by measuring instead of reasoning: the call pushes its `State`, then rejects, and a second `subscribeDoc` on the same NURI lands after the rejection is dispatched and before `reportSetupFailure`'s continuation does. Swept hops 0 to 6 - at **0** the clear has not happened yet, at **1** `DELIVERED A FORGOTTEN BARRIER`, at **2 and above** `lastState` is already null so no replay is queued at all and the joiner opens a fresh attempt. One hop is the whole window, which is why my earlier three-hop fake could never show it. `isCurrentAttempt` does not cover it either: that failure does not bump `attempt`, so the entry and the attempt are both still current. The test fails on the unfixed code with `[true]` - a joiner handed a barrier already forgotten - and passes with the re-read; mutating the re-read back to a capture kills exactly it.
+
+**SEVERITY: diagnostic, and scoped as such.** `getSyncState` reads the record and not the push, so it still answers `"timed-out"` and no read gains authority - no application ever saw a wrong answer. What the stale delivery broke is `open-repo`'s bootstrap wait, which crossed its barrier on it and logged `BARRIER <nuri> synced` for a barrier that no longer existed. That trace line is the one this codebase uses to tell a genuine absence from a not-yet-synced read, which is the subject this whole task family exists for.
+
+### Mutation-tested, eleven ways
+
+Killed: **M1** removing the channel half of the short-circuit kills all three new acceptance tests; **M2** removing the listener half kills the new "a reset leaves the document to be HELD again" test (it was UNPINNED until that test was written - the mutation passed the whole suite first time round); **M3** deleting a disowned record instead of replacing it kills (ee), the abandoned-open test and the cold-read assertion; **M4** letting `docChannel` call an unanswered establish `"open"` kills the new `docChannel` test (also unpinned until it was written); **M5** answering `"unknown"` for a channel that is gone kills five tests; **M7** reading the barrier off the channel state instead of `lastState` kills eight; **M8** restoring `realUnsub = null` for a non-function answer kills the new no-cancel-function test.
+
+Killed by the adversarial round's own three: **R1** restoring `"synced"` on `barrierCrossed` alone kills "a barrier pushed by a subscribe that then FAILED is not authority"; **R2** dropping the incarnation comparison kills "a second configure() re-holds the document even when something else subscribed first"; **R3** requiring `state === "open"` rather than `!== "none"` kills "a subscribe that never answers costs the fallback ONCE". And **M1'** - `stillStanding` asking nothing of the channel, i.e. a record of openness again - kills FOUR: (gg) and all three `configure` tests. **M5'** and **M3'** re-run against the revised code kill six and three respectively.
+
+**Survived, and reported rather than explained away: M6** - making `onSetupFailed` keep its listener instead of releasing it passes all 456 tests. It is hygiene, not an invariant line: with `establishing` already false the channel reads `"none"` either way, so nothing lies and the retry works. Kept because "a refused open holds nothing" is the behaviour round 6 established, and said here to be unpinned rather than claimed to be proven.
+
+### Gate, verbatim
+
+- `bun test` -> `462 pass / 0 fail`, `Ran 462 tests across 40 files.` **Run SIX times on the final state with the tree quiescent, and six more after each of the three adversarial fixes - green every time**, 3.6-4.2s. Counting the runs taken while hunting the episode below, more than forty consecutive green runs.
+
+  **One episode of red, reported because a single green run would have hidden it and because I cannot fully account for it.** Three runs taken WHILE the second adversarial agent was concurrently mutating and restoring the same source files came back `458 pass / 1 fail`, `459 / 0`, `458 / 1`. I could not name the failing test: the filter I used on those three runs printed totals only, which is a measurement mistake of mine. Every run since - 24 of them, with the tree quiescent - is green, and the mutation-copy race is the explanation that fits the timing. It is NOT established, so it is written down rather than dismissed. The one test with a timing assertion was hardened anyway (`4348381`): the margin it measured was 35ms and is now 140ms, and the mutation that must kill it still kills it. Baseline measured before any change: `449 pass / 0 fail`. **+13 tests, none deleted, none skipped.** Two assertions were REWRITTEN, each because it was asserting something false: `cold-read-for-document.test.ts`'s justification comment, and my own `barrierCrossed === true`, which asserted the defect the round-2 pass then found. Neither is a weakening - the old text was wrong, and the commits say so.
+- `pnpm exec tsc --noEmit -p packages/polyfill/tsconfig.json` -> `src tsc exit=0`
+- `pnpm exec tsc --noEmit -p packages/polyfill/e2e/tsconfig.json` -> `e2e tsc exit=0`
+- `python3 ~/.claude/skills/concept/lint.py` -> **0 ERROR** (warnings pre-existing: three oversized leaves, two open `_debt.md`, one unlisted `usage_`, five banned aliases)
+- polyfill e2e (`bun run e2e/run.ts` from `packages/polyfill`), run SIX times - once per state that changed real behaviour, because each adversarial fix did. Baseline `46 passed / 46`.
+  - after `de9b8a0`: `Polyfill e2e summary: 46 passed, 0 failed, 46 total - batch 3.4 min, slowest cold sync 30s`, exit 0.
+  - after the documentation commits: `46 passed, 0 failed, 46 total - batch 3.3 min`, exit 0.
+  - after `dcf3814`: `46 passed, 0 failed, 46 total - batch 3.4 min, slowest cold sync 30s`, exit 0.
+  - after `226db18`: `46 passed, 0 failed, 46 total - batch 3.4 min, slowest cold sync 30s`, exit 0, zero `[FAIL]` lines.
+  - after `56072df`, FIRST attempt: **`45 passed, 1 failed, 46 total - batch 3.6 min`**. The failure is the documented broker-login flake, verbatim: `[FAIL] resolving the same identifier after a faithful reconnect returns the SAME account docs (no fork) - threw: [e2e broker login] gave up after 45.0s - the wallet-list screen never changed and no application frame ever appeared`, with the harness's own trace showing it stuck on `wallet-list` waiting for an application frame. That is the login UI, before any library code runs. Reported rather than swallowed.
+  - after `56072df`, re-run: `Polyfill e2e summary: 46 passed, 0 failed, 46 total - batch 3.3 min, slowest cold sync 29s`, exit 0, zero `[FAIL]` lines.
+  - **NOT re-run after `7736de0`**, and said rather than implied: the fourth reviewer ran it clean at that head (`46 passed, 0 failed, 46 total`, first attempt), and the change is below the surface the e2e exercises - it alters which `State` a late JOINER is replayed, and no journey has a second subscriber racing a refused establish.
+
+  It does not exercise this change: `getSyncState` is not exported from `src/index.ts` and no journey performs a second `configure(...)`. What it proves is that nothing regressed on the paths it does walk, including the named-scope checks T01.j added.
+
+### The contract, and both non-guarantees are closed
+
+`1.0.0-dev.10` in `packages/polyfill/package.json`. **The guarantee and the tests that pin it are in the same commit** (`de9b8a0`), which is the rule T01.j broke twice.
+
+- `## Guarantees` line 196: `**within one session**` and the sentence sending the reader to the two holes are GONE, replaced by "Since `1.0.0-dev.10` that half carries no qualification" with both situations named as closed. Pinned by (gg) and the two `open-repo` acceptance tests.
+- `## Non-guarantees`: the whole three-paragraph block (`The "has it arrived" half ... is NOT reliable across two situations`) is DELETED. **Non-guarantee 1, after a second `configure(...)`** - closed, pinned by `open-repo.test.ts` "a second configure() leaves NOTHING claiming the document is open or synced" and by (gg). **Non-guarantee 2, a subscription the broker refuses late** - closed, pinned by `open-repo.test.ts` "an establish still outstanding when the subscription layer is torn down leaves no claim" and by the pre-existing "a subscribe the broker REFUSED is not recorded as open, so it can be retried", which still passes.
+- **AN OVER-CLAIM OF MY OWN, caught by re-reading my own contract text against the code rather than by review, and corrected in `8fe8c05`.** I had written that in BOTH situations a named scope now publishes `isPending` where it published `isSuccess`. Verified: that is true of the second `configure(...)` only. On a late refusal `onSetupFailed` already set `"timed-out"`, so the read was already WITHHELD - what changes there is the EXIT, the retry re-subscribing instead of being blocked for the session. The two are now stated per situation in the guarantee, in the withdrawn non-guarantee and in the knowledge leaf. This is the third round of this task family in which a contract sentence was truer of one case than of the case it was written about, so it is recorded rather than quietly fixed.
+- `## Change policy`: a `1.0.0-dev.10` entry, the dev.9 bullet's "This half is partial" qualification replaced by "Complete since `1.0.0-dev.10`", and the three "what exists today" version strings moved to dev.10. **Why major, said plainly in the leaf rather than assumed**: no state is added to the caller's vocabulary (`isPending` was already published and already had to be handled), but an interface branching on `isSuccess` is handed a different value in those two situations. Major is the conservative reading and the leaf says it is the conservative reading.
+- `knowledge_what-a-failed-read-answers-upstream.md`: the paragraph that named the two defects and pointed at T01.m now records them as closed, with the mechanism.
+- `docs/internal-contract.md` section 6: six stale line numbers corrected, and a dated note that nothing in the module STORES openness or the barrier any more.
+
+### Surprises
+
+- **VERIFIED: the task file's path for the third record is wrong.** It says `packages/polyfill/src/emulated-verifier/subscribe.ts`; the file is `packages/polyfill/src/surface/subscribe.ts`. Harmless, but it is the file nobody counted, so the wrong path is worth naming.
+- **VERIFIED: there were FIVE records in `open-repo`, not two.** `inFlight` and `settleInFlight` both imply openness and `inFlight` is read as a short-circuit; `registryEpoch` is a record about the records. The task named two. Counting first is what found them, and folding them into one record is what let the epoch counter go.
+- **VERIFIED: `lastState` was already the RIGHT barrier record**, and `syncState` was its broken copy. `lastState` is forgotten when the channel is released and when the session changes under it, which is exactly when a barrier stops meaning anything. Round 5 spent a careful write-ordering fix (recording `"synced"` above the already-settled check) on a problem that does not exist once the barrier is read off the fan-out: a late `State` sets `lastState` unconditionally. Test (dd) still passes and still asserts the behaviour, but the mutation it was written against no longer exists.
+- **VERIFIED: `realUnsub` was a partial record of "the call answered".** It was `null` when `doc_subscribe` resolved to a non-function, which would have made `docChannel` answer `"opening"` for the rest of the session over a perfectly open document, and every `ensureRepoOpen` would then take a fresh listener and wait the barrier again. It now installs a no-op, which costs exactly what `null` cost (`releaseFanOut` returned early on `null` rather than cancelling). Pinned by a new test; no fake in the suite exercised it.
+- **VERIFIED: `inbox-observer` reads no sync state at all.** The Description asked for it to be included in the reader list; it keeps its own "is this inbox watched" record and never asks about openness. Its teardown is already paired with `resetDocSubscriptions` through `stopObservingInboxes`, which `configure`, `resetConfig` and `setCurrentUser` all call.
+- **A defect of my own, found by the suite rather than by review.** The first `resetOpenedRepos` cleared `waiting` BEFORE calling `settle`, so `stopWaiting` short-circuited and every abandoned open hung to its full fallback: 8 failures, all timeouts, in five files. The line now carries the reason beside it.
+- INFERRED, not fixed: a `doc_subscribe` whose promise NEVER settles leaves the fan-out `establishing` for ever, so `ng.doc_subscribe` stays at 1 and the document cannot be re-opened - measured `calls=1` after a retry on HEAD and unchanged by this work, because the block is in the subscription layer and bounding an establish there means placing a second subscribe on a branch that already has one. `getSyncState` answers `"timed-out"` throughout, so nothing lies; the document is simply unrecoverable. Follow-up below.
+
+### Follow-ups, reported and not fixed
+
+- A `doc_subscribe` that never settles blocks re-establishment for the session (above). Fixing it means letting the bootstrap open's bounded fallback ABANDON the establish in `subscribe.ts`, which takes on the inverted-service-order bet that module already documents for `resubscribeDocs`. Worth its own task.
+- `public-store.ts:128`'s `attempted` memo calls `ensurePhysicalRepoOpen` INSIDE the memoised promise, so a memo hit skips that open - and nothing resets the memo on `configure()`, because `resetPublicStoreFetches` is reached only from `resetCaps`, which has no caller in `src`. After a second `configure(...)` a store document can therefore stay unopened while its cap answer is served from the memo. Not a wrong answer about openness (the derivation covers that), but a stale skip.
+- `forgetEverything()` (test-only) never clears `surface/inbox.ts:314` `seenByInbox`, `inbox-drain.ts:25` `running`, `branch-registers.ts:743` `openInboxInFlight` or `connect.ts:94` `inFlight`. Cross-test leakage waiting to happen.
+- Two `@provenance` lines I added carry an em dash, because `docs/api-contract.md:23` documents the em dash as that annotation's note separator. Two other lines in the diff carry a pre-existing `->` arrow I did not introduce. Everything else I authored is ASCII.
+- `.project/concepts/app-contract/_debt.md` now carries six markers, one of them from this work (`surface/subscribe.ts`, and the contract review it asks for was done). Consolidating the file is its own chore.
+- `docs/internal-contract.md:7` still names `surface/watch-shape.ts`, `surface/read-model.ts` and a `storeRegistry` namespace listing three removed symbols. Pre-existing, outside section 6, left alone as that document's own note says.
+

.tasks/done/T01.n-a-peer-range-that-excludes-what-we-need.md

@@ -0,0 +1,98 @@
+---
+id: T01.n
+title: The polyfill's peer ranges exclude exactly the versions it needs
+parent: T01
+depends_on: [T01.m]
+created: 2026-09-24
+claimed_by: worker-T01.n
+claimed_at: 2026-09-24T12:39:21Z
+blocked: false
+---
+
+## Description
+
+Two loose ends from T01.l, the first of which is a published-surface defect waiting for the first publish.
+
+### 1. Four peer ranges that admit nothing usable
+
+`packages/polyfill/package.json` declares all four `@ng-org/*` peers as `"*"`. In semver, `*` matches NO pre-release version. MEASURED by T01.l against the registry: of the 16 published versions, that range admits ONLY the bare `0.1.2` (dated 2025) and EXCLUDES every `0.1.2-alpha.N` - which is precisely what this package is built against and needs.
+
+It is inert today only because the polyfill itself is not published (a registry query for it returns E404), so no consumer has ever resolved these peers. It is certain to surface at the first publish, as an unsatisfiable or wrongly-satisfied peer for every application installing this package.
+
+Fix the four ranges so they admit the alphas this package actually works with and exclude the stale bare `0.1.2`. T01.l's tightening of `ng-e2e-helpers` to `>=0.1.2-alpha.13 <0.1.2` is the shape that was measured to work - decide whether the same bound is right here, given the polyfill is built against orm alpha.21 rather than web alpha.14.
+
+**VERIFY BY RESOLUTION, NOT BY READING.** This is the whole lesson of T01.l: the range it was sent to fix had a real defect, but the stated failure mode was wrong, and only a resolution test showed which part was true. Query the registry, compute what the range admits before and after, and paste both counts. A range that looks right and resolves wrong is the entire failure mode here.
+
+**Check `peerDependenciesMeta` at the same time.** All four are declared optional; confirm that is still the intent for each, since T01.l MEASURED that a consumer receives none of them under pnpm while this checkout gets the ORM through a devDependency.
+
+### 2. The example has no `typecheck` script
+
+`examples/notebook` typechecks correctly when invoked directly, but carries no `typecheck` script, so nothing in the repo runs it and its green state depends on someone remembering the command. Add the script. Do not build tooling around it.
+
+### Verification
+
+**Hard gate:** `bun test` -> 0 fail (baseline `449 pass / 0 fail`, measured); `pnpm exec tsc --noEmit -p packages/polyfill/tsconfig.json` -> exit 0; `pnpm exec tsc --noEmit -p packages/polyfill/e2e/tsconfig.json` -> exit 0; the example's typecheck via its new script -> exit 0; `python3 ~/.claude/skills/concept/lint.py` -> 0 ERROR.
+
+A fresh `rm -rf node_modules && CI=true pnpm install --no-frozen-lockfile` must end with ONE copy of each `@ng-org` package - verify what each resolves to rather than trusting a silent install. Two copies of a package holding module-level state means two registries and two identities, which is this package's own named hazard.
+
+Anti-cheat: no widening a range to silence a warning, and no `any`, `@ts-ignore`, deleted or skipped test.
+
+Every quantitative claim carries the number that supports it in the same sentence.
+
+## Progress
+
+## Result
+
+Status: done
+Commits: `3aa3fb2` (item 1, peer ranges), `f417841` (item 2, example typecheck script).
+
+### 1. The four peer ranges - VERIFIED BY RESOLUTION, per-package floor
+
+Method: registry version lists pulled from `registry.npmjs.org` (public npm, confirmed as the active registry via `pnpm config get registry`), admitted-set and `maxSatisfying` computed with the real node-semver engine (`pnpm dlx semver -r '<range>' <versions>`), not by reading the range.
+
+| package | published versions | BEFORE `"*"` admits | BEFORE maxSatisfying | AFTER range | AFTER admits | AFTER maxSatisfying |
+|---|---|---|---|---|---|---|
+| `@ng-org/web` | 16 | 1 (`0.1.2`) | `0.1.2` | `>=0.1.2-alpha.14 <0.1.2` | 2 (`alpha.14`, `alpha.15`) | `0.1.2-alpha.15` |
+| `@ng-org/orm` | 22 | **0** (no bare `0.1.2` exists) | none | `>=0.1.2-alpha.21 <0.1.2` | 2 (`alpha.21`, `alpha.22`) | `0.1.2-alpha.22` |
+| `@ng-org/shex-orm` | 11 | 1 (`0.1.2`) | `0.1.2` | `>=0.1.2-alpha.9 <0.1.2` | 2 (`alpha.9`, `alpha.10`) | `0.1.2-alpha.10` |
+| `@ng-org/alien-deepsignals` | 15 | 1 (`0.1.2`) | `0.1.2` | `>=0.1.2-alpha.13 <0.1.2` | 2 (`alpha.13`, `alpha.14`) | `0.1.2-alpha.14` |
+
+VERIFIED: `orm`'s BEFORE case is worse than the other three - `"*"` was not "wrongly satisfied", it was **unsatisfiable** (0 of 22 versions admitted), because `orm` has never published a bare `0.1.2` at all - every one of its 22 releases is a prerelease.
+
+**Floor choice, per package, not copied from `ng-e2e-helpers`.** `ng-e2e-helpers`'s floor (`alpha.13` on `web`) predates its own current devDependency pin (`alpha.14`) - it is a historical artifact, not a re-derivable rule. Instead the floor used here is each package's own current `devDependencies` pin in `packages/polyfill/package.json` (web `alpha.14`, orm `alpha.21`, shex-orm `alpha.9`, alien-deepsignals `alpha.13`) - the one version each package is actually built and tested against today, VERIFIED against the manifest (not trusted from the task prompt). Upper bound `<0.1.2` applied uniformly, including to `orm`, as a precaution against a future stable release repeating the same-shape inversion the other three already exhibit.
+
+### 2. `peerDependenciesMeta` - optional:true is correct for all four, VERIFIED by source inspection
+
+`grep` of `packages/polyfill/src` shows every `@ng-org/*` reference is `import type` only (index.ts:143,145,150,156,158; model/types.ts:8,12,13; surface/orm.ts:73-74; surface/use-shape-query.ts:185-186; surface/ng-proxy.ts:7) - zero runtime imports. The real functions (`ng`, `getObjects`, `insertObject`, `RdfOrmSubscription.getOrCreate`, `initNg`) are injected by the consuming app via `bootstrap.ts`, not imported by the polyfill. The polyfill's own runtime never needs these packages present; only its published `.d.ts` needs their types at the consumer's compile time - exactly what an optional peer expresses. `examples/notebook/package.json` confirms the pattern in practice: it declares `@ng-org/orm` and `@ng-org/web` itself, and the polyfill supplies none of them (T01.l's own measurement, unchanged here).
+
+### 3. Example's typecheck script
+
+`examples/notebook/package.json` scripts: `"typecheck": "pnpm exec tsc --noEmit -p tsconfig.json"` (mirrors `packages/ng-e2e-helpers`'s script). No tooling built around it, as instructed.
+
+### 4. Fresh-install duplication check - ONE copy of each, VERIFIED
+
+`rm -rf node_modules packages/*/node_modules examples/*/node_modules && CI=true pnpm install --no-frozen-lockfile` -> "Lockfile is up to date, resolution step is skipped", "Scope: all 4 workspace projects", `Packages: +113`.
+
+`node_modules/.pnpm` holds exactly one store entry per package: `@ng-org+web@0.1.2-alpha.14`, `@ng-org+orm@0.1.2-alpha.21`, `@ng-org+shex-orm@0.1.2-alpha.9_typescript@5.9.3`, `@ng-org+alien-deepsignals@0.1.2-alpha.13`. Resolving `@ng-org/*` by `readlink -f` from all three consuming projects (`packages/polyfill`, `packages/ng-e2e-helpers`, `examples/notebook`) lands on the exact same realpath per package - confirmed for all combinations present (web from all three, orm from polyfill and the example). No second copy anywhere.
+
+### Hard gate, verbatim, measured after the fresh install above
+
+- `bun test` -> `462 pass`, `0 fail`, `1313 expect() calls`, `Ran 462 tests across 40 files.`
+- `pnpm exec tsc --noEmit -p packages/polyfill/tsconfig.json` -> exit `0`
+- `pnpm exec tsc --noEmit -p packages/polyfill/e2e/tsconfig.json` -> exit `0`
+- `cd examples/notebook && pnpm run typecheck` -> exit `0`
+- `python3 ~/.claude/skills/concept/lint.py` -> `0 ERROR` (4 pre-existing WARNING groups: 3 oversized leaves, 2 open `_debt.md`, 1 unlisted `usage_`, 5 banned-alias hits - none introduced by this task)
+
+### Surprises
+
+- **VERIFIED, contradicts this task file's own Description:** the Description above states baseline `449 pass / 0 fail`, but the orchestrator's live instruction and my own measurement (both before and after the change, on this checkout) show `462 pass / 0 fail`. The file's own text is stale relative to the branch's current state - flagging rather than silently using either number without support.
+- **VERIFIED:** `@ng-org/orm`'s `"*"` was not merely "admits the wrong one" like the other three - it admitted **zero** versions, a strictly worse defect than the one the task description generalizes from.
+- **INFERRED, not re-verified in this task:** `ng-e2e-helpers`'s own floor (`alpha.13` vs its devDependency pin `alpha.14`) looks like the same kind of staleness this task fixed for the polyfill. Left untouched - it belongs to a package this task was not asked to touch, and re-opening it was not requested.
+- pnpm-workspace.yaml now lists `examples/*` (fresh install reports "all 4 workspace projects"), where T01.h/T01.l had reported `examples/notebook` outside pnpm's scope. Already fixed by an earlier task; not something this task touched.
+
+### Found broken, left alone (out of scope)
+
+- Concept lint's 4 pre-existing WARNING groups (see gate line above) - unrelated to this task's files.
+- Doc-debt auto-log `.project/concepts/app-contract/_debt.md` gained one entry from a repo hook on editing `examples/notebook/package.json`; recorded automatically, not authored content, left as the hook produced it.
+
+Not touched: `ng-helpers` (not read, only its published contract/usage), `docs/briefs/2026-08-10-consumer-harness-identity-switching.md`, T01.k, T01.g.

.tasks/done/T01.o-the-read-filter-is-bypassed-by-plain-properties.md

@@ -0,0 +1,315 @@
+---
+id: T01.o
+title: The read filter is bypassed by plain properties, and no fake shows it
+parent: T01
+depends_on: []
+created: 2026-09-24
+claimed_by: worker-T01.o
+claimed_at: 2026-09-24
+blocked: false
+---
+
+## Description
+
+**A rights leak on the published surface.** The capability filter around the published `useShape` is bypassed by the SDK version this repo actually builds against, and every gate stays green because no fake anywhere returns the shape the SDK ships. Found by T01.g, the closing review.
+
+### The leak - VERIFIED from primary sources on both sides, do not re-derive
+
+`packages/polyfill/src/emulated-verifier/read-filter.ts` does `const v = Reflect.get(target, prop, target); if (typeof v !== "function") return v;` - a non-function member is returned RAW, on the recorded ground that "a plain property carries no items".
+
+That ground is true of the CITED tree (alpha.18, where `useShape` returns a bare `DeepSignalSet`) and FALSE of the INSTALLED `@ng-org/orm@0.1.2-alpha.21`. Its shipped `dist/frontendAdapters/react/useShape.d.ts` returns `UseShapeResult`, whose members include three PLAIN PROPERTIES that each carry the items: `data: SUBSCRIPTION_DATA | undefined`, `promise: Promise<SUBSCRIPTION_DATA>`, and `subscription: RdfOrmSubscriptionFor<...>`. Its own doc comment states that `data` IS the value returned by `RdfOrmSubscription.signalObject`.
+
+Measured by T01.g with bob as holder and `isEnforcing() === true`: the alpha.18 shape iterates to `["bob-own"]`, while alpha.21's `.data`, `.subscription.signalObject` and `await .promise` each yield `["bob-own", "alice-private"]`, and nothing throws. That falsifies `contract_polyfill-surface.md:256` ("anything else throws").
+
+### THE ASYMMETRY IS THE FAULT, and the code already argues against itself
+
+For an unknown FUNCTION member the same file refuses rather than forwards, with the reason written beside it: forwarding is a silent leak, and this view's one job is that it cannot show more than the holder may read. That reasoning was never applied to non-function members. Naming the asymmetry is not the same as prescribing the repair - weigh what the right policy is, including what refusing `data` would cost a legitimate caller, and say what you rejected.
+
+**Do NOT fix this by filtering three member names.** `data`, `promise` and `subscription` are alpha.21's shape; a name list is what breaks silently at alpha.22, and breaking silently on an SDK bump is exactly how this defect arrived. Whatever you build must be safe for a shape nobody has seen yet.
+
+**The line that must hold:** a legitimate caller still gets its own data, through whichever member the SDK offers. A repair that makes the published `useShape` unusable has traded a leak for a break.
+
+### Why it was invisible, which must be fixed in the same task
+
+`packages/polyfill/e2e/orm-live-entry.ts:101-109` - the only live gate for the published `useShape` - injects a HAND-WRITTEN `sub.signalObject` substitute. So no fake in this repository returns the shape the SDK actually ships, and the leak cannot fail a test. Fixing the filter without fixing this leaves the next SDK shape change just as invisible.
+
+Build a fake that returns the SHIPPED shape - read it from `node_modules/@ng-org/orm/dist/frontendAdapters/react/useShape.d.ts`, which is the artifact that settles it - and make it the one the gates use. A test that would not have caught this defect is not coverage.
+
+### Two documentation faults that ride with it
+
+- `contract_polyfill-surface.md` instructs injecting "the REAL @ng-org/orm useShape" (see `docs/api-contract.md:50`), but `@ng-org/orm`'s `.` export maps to `dist/core.d.ts`, which exports NO `useShape` - it lives at `/react`, or as `reactUseShape` from `/all`. The instruction does not resolve. CONFIRMED by T01.g.
+- Four present-tense claims that the SDK's `useShape` returns a bare `DeepSignalSet` are false of alpha.21, and TWO are load-bearing provenance grounds: `use-shape-query.ts:284`'s `announced-not-written` premise, and `:193`'s `ShapeQuery kind=invention level=none ref=none`, justified as "no upstream type carries load state" when `UseShapeResult.isLoading` does. This is the `readUnion` failure mode again - a citation that resolves, attached to a claim that is false - and `provenance.test.ts` cannot see it by construction.
+
+### Verification
+
+**The leak's own test comes first and must fail on baseline.** Bob holding no capability for alice's document must not reach her items through ANY member of the returned object. Name the test.
+
+**Hard gate:** `bun test` -> 0 fail, baseline `465 pass / 0 fail` which the orchestrator measured; `pnpm exec tsc --noEmit -p packages/polyfill/tsconfig.json` -> exit 0; the e2e tsconfig -> exit 0; `python3 ~/.claude/skills/concept/lint.py` -> 0 ERROR; and the polyfill e2e run and reported verbatim, since the injected fake changes. Broker login flakes roughly 3 runs in 10 before library code runs - re-run a flaked login.
+
+Anti-cheat: no `any`, no `@ts-ignore`, no `as unknown as`, no deleted or skipped test, no weakened assertion. And specific to this one: no widening `UseShapeLike` to make a shape typecheck - `src/model/types.ts:83` is already `(...args:any[]) => any`, which is why both typechecks stayed at 0 while the leak was open, and that is a finding in itself worth addressing.
+
+**A guarantee and the test that pins it land in the same commit.** The contract's claim at `:256` is currently false; it becomes true or it changes, in the same commit as its test.
+
+**An independent adversarial review runs on this afterwards.** Rights defects get one whatever the gate says.
+
+## Progress
+
+### The enumeration, done before the code
+
+Read from the artifact that settles it: the INSTALLED `@ng-org/orm@0.1.2-alpha.21`, at
+`node_modules/.pnpm/@ng-org+orm@0.1.2-alpha.21/node_modules/@ng-org/orm/dist/frontendAdapters/react/useShape.{d.ts,js}`.
+The `.d.ts` declares `UseShapeResult_` with SIX members, wrapped by `WithMaybePagination`, which makes `nextPage` and
+`previousPage` optional when the config asks for no `pageSize`. The shipped `.js` returns exactly those six keys. Both
+were read; they agree.
+
+| member | declared type | does it carry items? | what the filtered view must answer |
+|---|---|---|---|
+| `data` | `SUBSCRIPTION_DATA \| undefined` - a `DeepSignalSet<T>` with no `orderBy`, a `DeepSignal<ReadOnlyArray<T>>` with one | **YES, directly.** Its own doc comment: "This object is the value returned by `RdfOrmSubscription.signalObject`" | a read-filtered VIEW of that collection. `undefined` is a primitive and passes untouched |
+| `promise` | `CONF extends undefined ? undefined : Promise<SUBSCRIPTION_DATA>` | **YES, on resolve** - the same collection | a promise that resolves to the read-filtered view of what it resolved to |
+| `subscription` | `CONF extends undefined ? undefined : RdfOrmSubscriptionFor<ST, CONF, T>` | **YES, three ways**: `signalObject`, `readyPromise`, and `addChangeListener`'s `{adds, updates, removes}` of raw items | **REFUSE, loudly.** This surface already says `RdfOrmSubscription` is not published and that reaching it "defeats everything above"; handing it back through `useShape` publishes it by another door |
+| `isLoading` | `boolean` | no | pass through - a primitive cannot reach an item |
+| `nextPage` | `(() => void) \| undefined` (optional without `pageSize`) | no - returns `void`, it loads more rows into the RAW collection, which is only ever seen filtered | forward, bound to the target, like `add`/`delete`/`clear` |
+| `previousPage` | `(() => void) \| undefined` (optional without `maxActivePages`) | no - same | forward, bound to the target |
+| **anything a later version adds** | unseen | unknowable | decided by TYPE, not by name: a primitive passes, a function comes back as a function that throws when called, an object throws on read |
+
+Two members of the COLLECTION had to be enumerated with it, because `data` is not always a Set:
+
+| member | carries items? | answer |
+|---|---|---|
+| `length` (array-like `data`, i.e. an `orderBy` config) | a COUNT of them - showing the unfiltered count shows MORE than the holder may read | filtered, beside `size`, and each only when the target itself has it |
+| `"0"`, `"1"`, ... (array-like `data`) | **YES** - a raw item | refused by the type rule (an item is an object). Left refused rather than projected: safe, loud, and making the ordered form ergonomic is a wider job than this task |
+
+### The two-layer shape that falls out
+
+The published `useShape` was wrapping an ENVELOPE in a filter written for a COLLECTION. So the envelope's own members
+were read through `Reflect.get` and, being non-functions, returned raw. Under alpha.21 that view is ALSO unusable for
+its owner - `[...view]` and `.size` throw, because an envelope is not iterable. There are two objects to filter, so
+there are two views, and `surface/use-shape.ts` applies the envelope one.
+
+
+## Result
+
+Status: REFUTED once, repaired, and back for a fresh adversary. First pass was four commits on `caps-p1a-and-virtual-user-boundary`, `3a89411` `e16fd6a` `e86e249` `b1b099b`. Whole change: **20 files, 1117 insertions, 247 deletions** (`git diff 5993a8c --shortstat`). The published surface is `1.0.0-dev.11`, a major, with the change-policy entry written beside the guarantee it changes.
+
+### The enumeration's conclusion
+
+Written into `## Progress` BEFORE the code, off the installed package's `.d.ts` and the `.js` beside it (they agree). Six members, and the answer differs by what each carries, not by what it is called. `data`, `promise`, `subscription` carry the items; `isLoading`, `nextPage`, `previousPage` do not. Two members of the COLLECTION had to be enumerated with them, because `data` is a `DeepSignalSet` only when no `orderBy` is asked for.
+
+### The policy, and what was rejected
+
+**Decide by the TYPE of the value, not by the name of the member.** A primitive holds no reference, so it cannot reach an item and passes; an object or a function can, so it refuses unless this file has a filtered form of it. Nothing in the code names `isLoading` - it passes because it is a boolean, which is the proof the rule is name-independent.
+
+Rejected, with the deciding reason each time:
+- **Filtering the three names.** Ruled out by the task and correct to rule out: it is a list that goes stale on the next bump, which is exactly how this defect arrived.
+- **Keeping ONE view and teaching it the envelope.** A `UseShapeResult` and a `DeepSignalSet` have nothing in common - the collection view threw on `[...result]` and `.size` because an envelope is not iterable. One object cannot be both, so there are two views and `surface/use-shape.ts` applies the envelope one.
+- **Wrapping `subscription` rather than refusing it.** It reaches the items three ways (`signalObject`, `readyPromise`, `addChangeListener`'s raw arrays) and this surface already says `RdfOrmSubscription` is not published, because one wallet hosts every identity. Wrapping it would publish it by another door and make a second surface to keep honest.
+- **Returning `undefined` for a refused member instead of throwing.** Silent is what this file exists not to be.
+
+### Safe for a shape nobody has seen
+
+A member a later `@ng-org/orm` adds is already decided: if it carries items it is an object or a function, and both refuse. `test/use-shape.test.ts` pins it with a hook returning `alpha.21`'s six members PLUS three nobody has declared - `rows` (the collection), `sample()` (a function yielding an item) and `totalCount` (a number). The first throws at the read, the second at the call, the third passes.
+
+### Both directions proved
+
+**The stranger blocked** - `no member of the result reaches a document this identity holds no cap for`: bob reads `data`, `data.size`, `await promise` and gets only his own, `subscription` throws, and the raw collection is asserted to hold BOTH so it is the filter that removed one. Plus `the item-yielding members of data are filtered too`. **5 of the 7 first-written tests FAIL on baseline** (measured by stashing `src/` alone), including both rights tests.
+
+**The owner served** - `the holder reads their own items through every member the SDK offers`: alice reads `data`, `data.size`, `await promise`, `isLoading`, and both page commands forward. And against the DEPLOYED broker: `e2e/orm-live-read.ts`, `5 passed, 0 failed`, the live read ready in 11ms through `data` and `.delete()` on it removing the triples from the document.
+
+### The new fake
+
+`packages/polyfill/test/use-shape-fake.ts`, shared by `bun test` and BOTH e2e entries, returns the shipped envelope: `data` a `Set` or an ordered ARRAY per `SubscriptionData<T, CONF>`, `promise` resolving to it, `subscription` carrying the items three ways, `isLoading`, and the page commands present only under a paginated config. `e2e/orm-live-entry.ts` builds the same object out of the real `getOrCreate`, expression for expression with the shipped adapter minus React's two pieces, and calls the SDK's own `normalizeConf` rather than restating it.
+
+### `UseShapeLike`
+
+Narrowed to `<T extends BaseType>(shapeType: ShapeType<T>, conf: RdfOrmConfig<T> | string | undefined) => ShapeResult`, with `ShapeResult` restated in `model/types.ts` because `UseShapeResult` is exported from NO subpath of the package (`.` is `core`, `/react` the hook alone, `/all` the config types alone - VERIFIED). A compile-time assertion in `test/use-shape.test.ts` pins that the SDK's own `reactUseShape` is assignable with no cast. Stated plainly rather than overclaimed: **this does not by itself prevent a leak** - the defect was runtime proxy behaviour - what it removes is the `any` that let every piece of prose in the repo say the hook returns a bare `DeepSignalSet` with nothing able to contradict it.
+
+### The contract at `:256`
+
+**True now**, and rewritten to say what is filtered, what is refused, and how an unseen member is decided. `1.0.0-dev.11` in `packages/polyfill/package.json`, and the guarantee and its test are in the same commit (`3a89411`).
+
+### The adversary re-run on the fix, which found three more holes
+
+Per `adversarial-findings-need-verification`, measured rather than reasoned. `Object.getOwnPropertyDescriptor` reads a property WITHOUT the `get` trap: `(result, "data")` returned the RAW collection and `(result, "subscription")` the handle `get` refuses - a second door into the same room, and the same hole existed on the collection view for the dunder hatch. And the array form says how many items it holds in four places (`length`, `Object.keys`, `in`, each index's descriptor) of which only `length` was filtered, so the count came back out through the other three and the descriptors handed back the items. All four traps now call ONE `read` function. Fixed in `e86e249`, with the regression pinned in both suites.
+
+### The gate, verbatim
+
+```
+475 pass / 0 fail / 1367 expect() calls   (bun test; baseline 465 pass / 0 fail, verified)
+src  exit=0    (pnpm exec tsc --noEmit -p packages/polyfill/tsconfig.json)
+e2e  exit=0    (pnpm exec tsc --noEmit -p packages/polyfill/e2e/tsconfig.json)
+0 ERROR        (python3 ~/.claude/skills/concept/lint.py; the same 11 pre-existing WARNINGs)
+
+== Polyfill e2e summary: 47 passed, 0 failed, 47 total - batch 3.4 min, slowest cold sync 31s ==
+   (46 declared before this task; the extra row is "the read-filtered view refuses the
+    ORM's own subscription handle". Run three times, 47/47 each time, no login flake.)
+
+== ORM live-read summary: 5 passed, 0 failed, 5 declared - run 0.6 min ==
+   (run twice; `useShape` ready in 11ms both times, the delete reaching the document)
+```
+
+Anti-cheat: no `any`, no `@ts-ignore`, no `as unknown as`, no widened type, no test deleted, skipped or weakened. Checked on the added lines with `git diff 5993a8c | grep "^+"`: the only `any` occurrences are two comments QUOTING the old `UseShapeLike`.
+
+### Surprises
+
+- **The shipped hook's `isLoading` contradicts its own documentation.** `useShape.d.ts` says "`true` when no data is available yet"; `useShape.js` computes `isLoading: !ormSubscription ? false : ormSubscription.isReady`, which is `true` once it IS ready. VERIFIED on both artifacts. Upstream's, not ours; reproduced as written in `e2e/orm-live-entry.ts` and flagged there, because a fake that quietly corrects the target measures something nobody ships.
+- **`UseShapeResult` is exported from NO subpath of `@ng-org/orm`.** `.` is `core.d.ts`, `/react` re-exports the hook alone, `/all` re-exports `OrderByConfig`/`RdfOrmConfig`/`SubscriptionData`/`WhereConfig` only. VERIFIED on the manifest and the three `.d.ts`. The type is restated in `model/types.ts` for that reason.
+- **The provenance gate forced a citation choice.** `ShapeResult` cannot cite `UseShapeResult`: the cited `nextgraph-rs` revision carries only `useShape` in that file, and `provenance.test.ts` checks that a citation RESOLVES there. It cites `useShape` with the version gap named in the note, which is what `OrmSubscriptionHandle` already does for the `OrmSubscription`/`RdfOrmSubscription` rename.
+- **`1.0.0-dev.11` is a major and the entry says why**, including the sentence a consumer needs most: if they were reading `.data`, they were reading unfiltered.
+
+### Follow-ups, out of scope
+
+- T01.p item 1 gets easier: the published `useShape` now returns `ShapeResult`, which is NOT published from `index.ts`. Either publish it or decide the return type stays unnameable, and `DeepSignalSet` is still exported with no published signature using it.
+- `e2e/polyfill-entry.ts` and `test/wallet-fake.ts` still inject `(() => {}) as unknown as UseShapeLike` at the call sites that never read a shape. Pre-existing, harmless, and now inconsistent with the one real fake.
+- The collection view answers `has` as a filtering FUNCTION even on the array form, where the target has no such method. Not a leak (it filters), a shape it grows.
+
+---
+
+## Round 2 - the review refuted the first delivery, and it was right
+
+**FINDING 1 was a real rights leak and it is closed.** `Set.prototype.add` returns `this`, so the three mutations - forwarded BOUND TO THE TARGET - handed the unfiltered collection back as `add`'s return value. Every way IN was filtered and the way OUT gave the whole set away, through the FIRST member the ORM's own documentation example uses (`expenses.add({...})`).
+
+Verified before changing anything, by running it rather than reading it:
+
+```
+Set.add returns this: true            DeepSignalSet.add returns === the deepSignal proxy: true
+Set.delete returns: boolean           DeepSignalSet.delete returns: boolean true
+Set.clear returns: undefined          DeepSignalSet.clear returns: undefined
+```
+
+So one of the three was unsafe in the way the reviewer said, and the other two were safe in their RETURN and unsafe in their REACH - which the reviewer's own repro had shown (`delete(aliceItem)` returned `true` and removed it). The rule is therefore one sentence covering all three: **a mutation reaches the collection underneath, but neither hands back nor acts past what the view shows.**
+
+- `add` hands back the VIEW, so chaining lands on the filtered collection.
+- `delete` acts only on an item the view shows - the same question `has` already declines to answer, and the two used to disagree.
+- `clear` empties the view, not the collection every identity shares.
+
+Writing still reaches the document: `e2e/orm-live-read.ts` `5 passed, 0 failed` against the deployed broker, with `.delete()` removing the triples.
+
+**The reviewer's own repro, replayed through the published call**: `add returns the raw collection : false`, and what it hands back holds only bob's items.
+
+**THE PATTERN, taken seriously.** Five leaks, one cause: a WRITTEN JUSTIFICATION ABOUT A RETURN VALUE NOBODY EXECUTED. So the first thing done here was to run the return values, and the second was to run a SWEEP of every handled member on both proxies asking "does this hand back the target?". It found one more, on the other proxy: a page command of the ENVELOPE that returned the collection handed it back RAW. `nextPage` is declared `() => void` and yields nothing today, so it is not a live defect - it is the same unexecuted ground on the other side, and it is now closed with a test that pins the RULE. Three copies of that reasoning are now ONE function, `handBack`.
+
+**THE THREE MINORS, all fixed:**
+- The array form answered `keys`/`entries`/`forEach` with SET semantics. It now yields indices, `[index, item]`, and the index as `forEach`'s second argument. Owner-path output, no leak.
+- **The shared fake was more correct than the target** - `isLoading: !loaded` against the shipped `ormSubscription.isReady`. That re-creates the exact blindness this task removes, and the reviewer is right that it is worse than minor in kind. The fake now reproduces the shipped expression, the file says the inversion is upstream's, and the test asserts the inverted value on purpose. The contract carries it as a non-guarantee telling a consumer to branch on `data === undefined` instead.
+- Ten stale `as unknown as UseShapeLike`, not two. All ten take the shared fake, with no cast.
+
+**The contract was FALSE and is now true, verified by running it.** Every clause of `:263` has a test that fails if the clause is false; the two newest were demonstrated failing against the pre-fix code before the fix was written. "mutations pass through" is gone, replaced by what the mutations actually do.
+
+### Round 2 gate, verbatim
+
+```
+480 pass / 0 fail / 1393 expect() calls, six consecutive runs   (baseline 465 pass / 0 fail)
+src  exit=0      e2e  exit=0      concept lint: 0 ERROR
+== Polyfill e2e summary: 47 passed, 0 failed, 47 total ==
+== ORM live-read summary: 5 passed, 0 failed, 5 declared - run 0.6 min ==
+```
+
+### What round 2 did NOT re-open
+
+The twenty-five access routes the review found closed were left alone, and the sweep re-confirmed that no member of the collection view hands back the target.
+
+### Still open, named rather than fixed
+
+`delete` and `clear` now act only on what the view shows. That is a WRITE-side narrowing justified by the read boundary, and it is the one place this task went beyond the finding: it was done because `has` already refuses the same question, so the view was contradicting itself. A fresh adversary should weigh whether a holder losing the ability to clear a collection they cannot fully see is the right trade.
+
+---
+
+## Round 3 - one leak, three outages, and a correction I owe on my own reporting
+
+**FIRST, A CORRECTION TO ROUND 2's REPORT.** I called the e2e gate green on the SUMMARY LINE and never captured the process's exit code. Sometimes it is `1`: the runner prints its clean summary and then HANGS in teardown until its own 25-minute wall clock aborts it (`[e2e deadline] ... This is a HANG, not a verdict`). **Intermittent, and pre-existing - not mine.** Counted over every run recorded here, the abort follows a clean summary in **3 of 7**, and one of the three is `scratchpad/e2e-run1.log`, written at 14:33 on 2026-09-24 against `46 passed` and predating this task's starting commit `5993a8c` (17:50). The CHECKS are the verdict and they pass in all seven. Reported rather than fixed: it is the harness's teardown, outside this task.
+
+**F1, the leak, closed - and it settles the trade I had asked to have weighed.** `delete` and `clear` asked `keep`; `add` did not. That asymmetry made the sentence I had just published true by coincidence, because the ungated `add` MANUFACTURED the state the other two then handled partially: bob plants an object into ALICE's document, the view filters it straight back out so he never sees it again, the two-way binding commits it there, and `clear()` leaves it behind. Reproduced, then fixed, then re-run.
+
+The arbitration, adopted: **all three ask the same question.** What they ANSWER differs because the members differ, and that is not a residual asymmetry but the members' own contracts - `delete` has `false`, which is the Set contract's word for "it was not there" and is true of the view; `add` returns the collection whether or not it did anything, so it has no value meaning "that did not happen" and therefore THROWS.
+
+**F3/F4, the outage, closed.** Eighteen declared array members plus `includes` and the seven ES2025 set combinators were throwing for the holder whose data it was - a leak traded for an outage, which is not a repair. The view now serves **everything `@ng-org/alien-deepsignals` declares non-mutating**, computed over the readable items. The three key sets are restated (the package exports no subpath for them, and `src/` may not import an optional peer at runtime), and a test READS the shipped `dist/iteratorHelpers.js` and fails if the lists have parted company - so the restatement cannot drift silently. The misnamed `iteratorHelperKeys` comment is corrected by the same change.
+
+**F2, latent, closed.** The descriptor trap returned an ACCESSOR untouched, so its getter - which reads the target - was a door around the view. Not reachable on the shape that ships; reachable on the next one, which is the whole claim this file makes. Getter routed through the view, setter refused.
+
+**F5, closed on the view's own account, and the fake no longer diverges.** There were no `set`/`deleteProperty`/`defineProperty` traps, so against a plain ordered array `view[0] = x`, `delete view[0]` and `view.length = 0` all went through, the last defeating the gated `clear`. Production was protected BY THE TARGET, which is resting on a guarantee this view does not make about a shape it does not control. The view carries it now, proved at the unit level against a PLAIN array so that what refuses is unambiguously the view. And the fake builds the REAL collections - `deepSignal(new Set(...))` and `readOnlyArray(deepSignal([...]))` - so it is neither more correct than the target (last round) nor more permissive (this round).
+
+**MY OWN SWEEP OF THIS ROUND'S REPAIR found two more**, which is the discipline working rather than a surprise: `Object.setPrototypeOf(view, other)` replaced the REAL collection's prototype, after which iterating it throws for every identity - the `clear` problem in another key - and `Object.preventExtensions(view)` (what `Object.freeze` begins with) wrote to the target and would have stranded the index projection, which is only lawful while the target is extensible. Both trapped, both pinned.
+
+**The memo claim corrected**, not removed: it buys `result.data === result.data` within one call, and the cross-render stability it used to claim is unattainable because `useDeepSignal` replaces its root proxy on every relevant rerender.
+
+### Round 3 gate, verbatim
+
+```
+486 pass / 0 fail / 1450 expect() calls, six consecutive runs   (baseline 465 pass / 0 fail)
+src  exit=0      e2e  exit=0      concept lint: 0 ERROR
+== ORM live-read summary: 5 passed, 0 failed, 5 declared - run 0.6 min ==   (process exit 0)
+== Polyfill e2e summary: 47 passed, 0 failed, 47 total ==                   (process exit 0)
+```
+
+### Follow-up opened
+
+`e2e/run.ts` INTERMITTENTLY fails to exit after printing its verdict - 3 runs in 7 here, one of them predating this task - and is then killed by its own 25-minute deadline, exiting 1 on a batch whose every check passed. Pre-existing and outside this task, but it makes the exit code an unreliable CI signal, and it is the kind of flake that gets read as a failure of whatever changed last.
+
+---
+
+## Round 4 - the principle was wrong, and the suite was pinning the leak
+
+Three findings, all confirmed by running them before anything was changed. Two of the three are mine rather than inherited, and both are the shape this batch has been chasing: **a rule replaced by a list, and a fix applied to one of two places.**
+
+**F1 - the type-based policy was FALSE, and this is the one that needed a new answer rather than a new name.** "A primitive cannot reach an item, so it passes" - but a COUNT is a primitive that DESCRIBES the items. The file already knew it, because `size` and `length` were computed by an explicit two-name list, which is the forbidden name list reappearing as the fallback the moment the principle failed. Measured: a holder who may read 1 of 3 read `count` and `totalCount` as 3.
+
+**And the suite asserted that as correct** - `expect(result.totalCount).toBe(7)` for a holder of one item, six lines above a test whose own comment calls an unfiltered count the defect. A suite that asserts both would have kept the leak green for ever. That test is rewritten and now asserts the refusal.
+
+**The honest answer, stated plainly because the previous one pretended otherwise: it CANNOT be done by type.** A number is a number, and nothing observable about a getter says whether its 7 counts items or echoes a page size. So the default inverts: **what this file has DECIDED it serves; everything else refuses, primitive or not.** That is safe for an unseen shape BY CONSTRUCTION, which a passing default never was. The prohibition worth keeping was on a list that lets unknowns THROUGH - that breaks silently on a bump; one that refuses them breaks loudly, which is the property that matters. Two carve-outs, neither an SDK spelling: a member the target does not carry answers `undefined` (nothing is behind it), and the LANGUAGE's own primitive protocol keys, closed by the specification rather than by any package. *(The second was UNSOUND as reasoned - the specification closes the keys, not the values behind them - and is gone in round 5 below; the first stands, with what it discloses now stated exactly.)* `isLoading` is now DECIDED and served with its reason, rather than passing because it happened to be a boolean.
+
+**F2 - the envelope had two traps to the collection's nine.** `delete result.data`, `result.isLoading = x`, `setPrototypeOf` and `preventExtensions` all reached the SDK's own object - and the last two are the pair round 3 found and trapped, on one view of two. The five write traps now live in ONE object spread into both, so one cannot be repaired without the other.
+
+**F3 - the write gate was vacuous for an object naming no document.** `keep` answers `true` when `@graph` is absent, which is right for a READ (nothing to check) and meaningless for a WRITE: the object landed in the collection every identity shares. Only upstream's "@graph is missing" stopped it - the borrowed target guarantee this file removed for `set`/`deleteProperty` one round earlier and left standing here. A write must now NAME a document and the holder must hold it.
+
+**Minor - `copyWithin`** is the one member upstream's own list mislabels as non-mutating. *(This sentence continued "and its own `readOnlyArray` throws on reading it" - FALSE, and reasoned rather than run; corrected in round 5 below, where the measurement shows it runs and destroys an element.)* Serving it over the snapshot made it succeed and discard in silence, so it is no longer served; the parse gate checks for exactly that one exception and nothing more.
+
+**My own sweep of this round's repair** found nothing further: every count route on both views answers the READABLE count (1 of 3, never 3) - `size`, `Object.keys`, `Reflect.ownKeys`, `JSON.stringify`, spread, `toArray`, `Array.from`, the four combinators, `reduce` - and all four write routes refuse on both views with both targets intact.
+
+### Round 4 gate, with EXIT CODES rather than summary lines
+
+```
+bun test, six consecutive runs, exit=0 each:  489 pass / 0 fail / 1465 expect() calls
+                                              (baseline 465 pass / 0 fail)
+src  tsc exit=0      e2e tsc exit=0      concept lint exit=0, 0 ERROR
+orm-live-read exit=0:   5 passed, 0 failed, 5 declared
+polyfill e2e  exit=0:  47 passed, 0 failed, 47 total - 0 FAIL rows, no hang abort
+```
+
+Status: **done**. Five adversarial rounds; the rights boundary closed after four, the record and the gate after five. What the whole task is worth remembering for is one sentence: **every leak in this family, and both remaining faults in the record, came from a justification about a value that nobody executed.** `rule_justify-a-return-value-by-running-it` was written in this batch and its first real application was to its own neighbour, which it failed - so the rule is right and it needs a habit behind it, not a second statement.
+
+---
+
+## Round 5 - the record and the gate, not the boundary
+
+The rights position on the shipped shapes is closed, confirmed independently across ~40 routes on both views with both live suites green on their EXIT CODES. The five findings were about whether the record tells the truth about the code and whether the gate can fail. Both were wrong in my favour, which is the worst direction. Each was reproduced before anything changed.
+
+**F2 - MY RECORDED GROUND WAS FALSE, and it was reasoned rather than run.** I had written - in the code, the contract, a test comment and this Result - that upstream's `readOnlyArray` throws on reading `copyWithin`, so refusing it merely matched the target. Measured against the installed package:
+
+```
+ro.copyWithin                 -> function        (no throw on the read)
+ro.copyWithin(0, 1)           -> ["B","C","C"]   from ["A","B","C"]: the first element
+                                                 is DESTROYED
+ro.push / splice / sort / reverse / fill / shift  -> THROW on the READ
+```
+
+`readOnlyArray` refuses every mutator it knows about, and `copyWithin` escapes for exactly the reason it is named in this file: it sits in the same mislabelled list the refusal is built from. **Refusing it is STRICTER than the target, not equal to it** - a deliberate divergence, now recorded as one with the measurement beside it in all four places. This is the first thing `rule_justify-a-return-value-by-running-it` should have caught, and its first application was to its own neighbour.
+
+**F4 - the file still documented the rule this round DELETED.** Two headers described the type-based default ("a count, a flag passes untouched", "nothing below names `isLoading`") while the code names `isLoading` a few lines on, and the contract carried both policies at once. Both headers now state the current rule and record the two defaults that were tried and failed, since each read as obviously sound when written; the contract bullet states one policy.
+
+**F3 - the gate could not fail.** Proved by running the experiment: a verbatim copy with `{copyWithin, slice}` as the exception set and `slice` dropped from the served list gave `1 pass / 0 fail`. It asserted filtered comparisons, which any number of exceptions satisfies. It now asserts a PARTITION - upstream's effective set equals the union, the three parts are disjoint, the exception set is exactly the one member named - and reads the SYMBOL entries the string-only regex could not see. **Verified red in three directions**: dropping a served member (2 fail), smuggling a second exception (2 fail), adding a phantom helper (1 fail).
+
+**F1 - the ECMAScript carve-out was unsound as reasoned.** The specification closes the KEY set, not the values behind it, so a `Symbol.toStringTag` implemented as a getter returning `Set(${size})` published the unfiltered count through a key this file had called harmless. The carve-out is gone: both keys are DECIDED, with values the view computes from the shape it wraps, answered only when the target carries one. Measured on the hostile case - `[object Set]` where the raw count is 2 and the readable count 1. The existence oracle is not defended but STATED: the view discloses whether the target carries a key, which is the SDK's published shape rather than the holder's data, and it is not a count channel - measured, on every shipped shape no key's presence depends on the items.
+
+**F5 - `reduce` branched on the accumulator's VALUE instead of on arity.** An explicit `reduce(fn, undefined)` was read as the one-argument form: an owner with no readable items got a TypeError where a Set or Array answers `undefined`, and with one item got that item back without `fn` running. Both measured against the native behaviour they must match, both fixed, both pinned.
+
+**The two sentences that were unsafe advice.** The contract said "Log `data`" and `use-shape.ts` advertised that the spread reads through the view. Neither survives: a console is the HOST's - `console.log(result)` prints every identity's items from behind the proxy and no trap can prevent it - and the envelope's spread THROWS. The contract now says not to inspect what a shape read hands you when several identities share a page, and says why that is not a hole a version can close.
+
+### Round 5 gate, with EXIT CODES
+
+```
+bun test, six consecutive runs, exit=0 each:  491 pass / 0 fail / 1479 expect() calls
+                                              (baseline 465 pass / 0 fail)
+src tsc exit=0      e2e tsc exit=0      concept lint exit=0, 0 ERROR
+orm-live-read exit=0:  5 passed, 0 failed, 5 declared
+```
+

.tasks/done/T01.p-four-minor-surface-faults.md

@@ -0,0 +1,275 @@
+---
+id: T01.p
+title: Four minor faults on the published surface
+parent: T01
+depends_on: [T01.o]
+created: 2026-09-24
+claimed_by: T01p-agent
+claimed_at: 2026-09-24T18:50:06Z
+blocked: false
+---
+
+## Description
+
+The four minor findings of T01.g, all CONFIRMED there. None is a rights or correctness defect; each is a published-surface or annotation inaccuracy. Verify each still stands before changing it - T01.o may have moved some.
+
+1. `Schema` and `DeepSignalSet` are published with no published signature using them, against the rule stated at `packages/polyfill/src/index.ts:78` (the same `ReadCap`/`InboxScope` rule, so this is a recurrence). Either a published signature uses them or they are unpublished.
+2. Seven symbols annotated `kind=invention level=none ref=none` sit ABOVE the polyfill-era divider, under the heading that promises a target counterpart for every symbol (`index.ts:45`, `:111-123`). Either the annotation is wrong or they are on the wrong side of the divider.
+3. `docChangeType` is published but absent from the concept contract's `## Surface`, and nothing pins that block against the actual exports. Add it, and consider whether the block should be pinned by a test the way the deletion list already is.
+4. `account-registry.ts:971` annotates `storeRegistry.resolveScopeGraph`, unpublished since `1.0.0-dev.5`. A provenance annotation on an unpublished symbol claims a surface that does not exist.
+
+**Hard gate:** `bun test` -> 0 fail; both typechecks exit 0; `python3 ~/.claude/skills/concept/lint.py` -> 0 ERROR. Anti-cheat as usual. Any symbol you unpublish is a MAJOR by the contract's own change policy - follow it rather than deciding the level yourself.
+
+## Progress
+
+Items 1, 3 and 4 verified, fixed and committed. Item 2 investigated in full; the
+coordinator confirmed the split and asked for the two determinable sub-findings (the
+five `EventuallyConfig` field types, and `ShapeQuery`'s kind) to be applied, with the
+third (`ShapeObservable`) left for the owner - see the "Item 2 - resolution" addendum
+below. All four items are now closed for this task; the one open item is `ShapeObservable`,
+explicitly the owner's.
+
+Commits made (chronological): `fix!:` unpublish Schema/DeepSignalSet + version bump to
+`1.0.0-dev.12` (item 1); `docs:` add docChangeType to the concept contract's Surface and
+pin the block with a new test (item 3); `fix:` drop the stray provenance annotation on
+`resolveScopeGraph` (item 4); `fix:` move the five `EventuallyConfig` field types below
+the divider + version bump to `1.0.0-dev.13` (item 2, part A); `fix:` re-kind `ShapeQuery`
+to `announced-not-written` (item 2, part B).
+
+## Result
+
+**Status: done.** `ShapeObservable`'s divider placement is named below as the owner's
+open item - not a blocker on this task, per the coordinator's instruction.
+
+### Item 1 - Schema / DeepSignalSet (DONE)
+
+VERIFIED by grep across `src`, `test`, `e2e`, `examples`: neither is used as an actual
+TypeScript type anywhere in this repo outside the re-export itself (`DeepSignalSet` only
+appears inside prose/JSDoc). Unpublished both from `packages/polyfill/src/index.ts`
+(removed the `export type` lines and their `@provenance` annotations), following the
+exact precedent already set for `ReadCap`/`InboxScope` - except neither has an internal
+use to stay DEFINED for, so they are simply gone rather than moved to `model/types.ts`.
+
+Checked the sibling task's note about `ShapeResult`: VERIFIED that `useShape` now
+declares a literal `ShapeResult` return type (changed today, replacing `any`), but
+`ShapeResult` staying unpublished is an EXISTING, DOCUMENTED, deliberate pattern (its own
+comment in `model/types.ts:81-99` says "Same discipline as {@link OrmSubscriptionHandle}"
+- a published call returning an unpublished, package-invented result type, matching the
+contract's own `## Surface` entry `useShape(...): ShapeResult`). This does not violate
+the rule at `index.ts:78` (which is one-directional: a published TYPE needs a published
+signature using it - not the reverse). Concluded this does NOT belong in item 1; no
+change made.
+
+This is a MAJOR (published symbol removed). Version bumped `1.0.0-dev.11` ->
+`1.0.0-dev.12` in `packages/polyfill/package.json`, a new dated entry added to the
+concept contract's `## Change policy`, and `docs/api-contract.md` updated (the "Today"
+code block in §4, the §14 ruling with a new paragraph matching the ReadCap/InboxScope
+one, and the appendix's `direct:` inventory line) - in the SAME commit as the code
+change.
+
+### Item 2 - seven `invention/none/none` symbols above the divider (BLOCKED, not changed)
+
+VERIFIED the exact seven, by grepping every `kind=invention level=none ref=none`
+annotation in `src` and checking which are published above the `POLYFILL-ERA` divider in
+`index.ts`: `NgLike`, `UseShapeLike`, `OrmSubscriptionLike`, `GetObjectsLike`,
+`InsertObjectLike` (all in `model/types.ts`, all typing fields of `EventuallyConfig`) and
+`ShapeQuery`, `ShapeObservable` (both in `surface/use-shape-query.ts`, the return shape of
+`useShapeQuery`).
+
+They do NOT all resolve the same way:
+
+- **The five `EventuallyConfig` field types.** Each one's own comment says it "exists
+  only to describe what `configure` receives" - and `configure`/`EventuallyConfig` are
+  themselves already, unambiguously, on the deletion list (`knowledge_what-an-app-deletes-
+  at-migration.md`: "Deleted... today that is `configure` and its config type"). Their
+  `invention/none/none` annotation is honest (no kind in the closed set fits better).
+  INFERRED, with strong textual support: these five belong BELOW the divider, beside
+  `EventuallyConfig` - but moving them is the exact action the task names as requiring a
+  decision, so left untouched.
+- **`ShapeQuery`.** VERIFIED: its declared shape - `{ data, isPending, isSuccess,
+  isError, error }` - is the LITERAL shape `.project/rules/nextgraph/surface-mirrors-the-
+  sdk.md` records as NextGraph developers' announced direction for `useShapeQuery`
+  (the same document `useShapeQuery` itself cites with `kind=announced-not-written`). The
+  word "ShapeQuery" appears in that record. Its `invention/none/none` annotation looks
+  like the wrong kind - `announced-not-written`, citing the same record, would be
+  consistent and would keep it above the divider with no relocation. Not applied: still a
+  change to a load-bearing annotation on a currently-blocked item, held for the same
+  decision.
+- **`ShapeObservable`.** VERIFIED: the word "ShapeObservable" does NOT appear anywhere in
+  the announcement record, and VERIFIED in `examples/notebook/app.ts:192-217` that this
+  package's `useShapeQuery` is called as a plain factory (not a React hook) returning an
+  object the caller manually `.subscribe()`s and `.getSnapshot()`s - i.e. the
+  getSnapshot/subscribe/refetch wrapper is this package's OWN framework-agnostic
+  composition, not something NextGraph announced. Its `invention/none/none` annotation is
+  therefore honest. Whether this wrapper is deleted at migration (if the real,
+  eventually-shipped `useShapeQuery` is itself a plain hook returning the snapshot
+  directly, the way `useShape` does) or survives (if the real one needs the same kind of
+  wrapper) cannot be determined from anything in this repo - this is the irreducible
+  design question.
+
+No code or annotation changed for item 2 at this point in the session (see "Item 2 -
+resolution" below for what the coordinator then asked to be applied).
+
+### Item 2 - resolution (PART A and B DONE; PART C left to the owner)
+
+The coordinator reviewed the analysis above, agreed the split was right, and asked for
+Parts A and B to be applied since they are determinable from this repo, with Part C
+(`ShapeObservable`) left untouched for the owner.
+
+**Part A - the five `EventuallyConfig` field types (DONE).** Verified the precondition
+before moving anything, as instructed: grepped `index.ts` for `export { configure }` and
+`export type { EventuallyConfig }` - both sit BELOW the `POLYFILL-ERA` divider (lines 174-
+175 at the time of checking), i.e. already, unambiguously, on the deletion list. Since the
+precondition held, moved `NgLike`, `UseShapeLike`, `OrmSubscriptionLike`, `GetObjectsLike`
+and `InsertObjectLike` out of the SDK-SHAPED `export type { Nuri, NuriLike, PrincipalId,
+... }` grouping and into a new `export type { ... } from "./model/types";` placed right
+after `EventuallyConfig`'s own export, with prose explaining the move on both sides of the
+divider. No signature changed - same five names, same five shapes, still exported from
+`index.ts` - only which section of the entry documents them.
+
+This is a **PATCH** by the concept contract's own `## Change policy`: nothing under
+`## Surface` or `## Guarantees` changed (neither contract document ever separately listed
+these five as standalone entries - both already only show them as `EventuallyConfig`'s
+field types, correctly tied to bootstrap), so none of the three `major` triggers (removed,
+renamed, narrowed/reshaped) applies, and "a symbol added" doesn't fit either - this is
+"changes neither the published surface nor anything above `## Guarantees`" verbatim.
+Version bumped `1.0.0-dev.12` -> `1.0.0-dev.13` in `packages/polyfill/package.json`, a
+dated `patch` entry added to the concept contract's `## Change policy`, and
+`docs/api-contract.md` §14 updated (code block split in two, plus a paragraph) - all in
+the same commit as the code move.
+
+**Part B - `ShapeQuery`'s kind (DONE - the record exists).** Checked the precondition the
+coordinator named: `.project/rules/nextgraph/surface-mirrors-the-sdk.md` already carries
+the record `useShapeQuery` itself cites (`kind=announced-not-written ... announced-by=
+nextgraph-developers@2026-09-16`), and that same document's prose states the announced
+shape verbatim as `{ data, isPending, isSuccess, isError, error }` - identical, field for
+field, to `ShapeQuery`'s own declared interface - and literally contains the word
+`ShapeQuery` (checked with the same word-boundary rule `test/provenance.test.ts`'s
+`deadCitations` uses). The record exists, so the kind was re-annotated: `ShapeQuery` now
+carries `kind=announced-not-written level=3 ref=.project/rules/nextgraph/surface-mirrors-
+the-sdk.md:ShapeQuery announced-by=nextgraph-developers@2026-09-16`, citing the identical
+statement `useShapeQuery` cites. `ref` points at the `.md` in this working copy, never a
+source file, per the rule. No version bump: this changes a provenance comment only -
+invisible to a consumer, no change under `## Surface` or `## Guarantees`, and `ShapeQuery`'s
+divider position (above it) was already correct and stays put.
+
+**Part C - `ShapeObservable` (LEFT UNTOUCHED, as instructed).** Not moved, not re-kinded,
+not weakened. It remains `kind=invention level=none ref=none`, above the divider, exactly
+as found - the coordinator is putting its migration fate to the owner.
+
+Verified after both parts: `test/provenance.test.ts`'s well-formedness and citation checks
+pass on the new `ShapeQuery` annotation, and the `announced-not-written` malformation
+tests (which exercise the exact form `useShapeQuery` uses) still pass unchanged since they
+test against a literal fixture, not the source tree.
+
+### Item 3 - docChangeType absent from the concept contract's Surface (DONE, and pinned)
+
+VERIFIED: `docChangeType` (lowercase, the function) is exported from `index.ts` but was
+absent from `.project/concepts/app-contract/polyfill-surface/contract_polyfill-
+surface.md`'s `## Surface` block. Also VERIFIED that `docs/api-contract.md` (a separate,
+still-actively-maintained document at the repo root, distinct from the concept contract -
+see Surprises) already had it correctly, and is pinned by three existing tests in
+`test/vocabulary.test.ts`; the concept contract had NO such test.
+
+Added the `docChangeType` signature to the concept contract's Surface block, and added a
+new test, `"every 'export' shown in the concept contract's Surface block is actually
+exported"`, reusing the same `publishedNames()`/`isNamespaceMember()` helpers the
+existing `docs/api-contract.md` check uses. VERIFIED the new test actually catches drift:
+temporarily removed `docChangeType` from `index.ts`'s export list, re-ran the suite, saw
+it fail naming exactly `docChangeType`, then restored the file and confirmed green again
+(diff checked against the original afterward - clean revert).
+
+### Item 4 - stray provenance annotation on resolveScopeGraph (DONE)
+
+VERIFIED: `resolveScopeGraph` is not re-exported by `surface/placement.ts` (which backs
+the published `storeRegistry` namespace), so `storeRegistry.resolveScopeGraph` names
+nothing a consumer can reach - confirmed unpublished since `1.0.0-dev.5` per
+`surface/placement.ts`'s own comment. VERIFIED its two siblings, `resolveWriteGraph` and
+`listMyEntityDocs` (same file, same unpublished status), carry NO `@provenance`
+annotation at all - the established convention for internal/unpublished helpers. Removed
+the stray `@provenance storeRegistry.resolveScopeGraph ...` line to match; left the JSDoc
+comment above it untouched (still an accurate internal note). No test previously caught
+this because `test/provenance.test.ts` only checks that every PUBLISHED symbol has an
+annotation, never the reverse (an annotation naming something that isn't published) -
+this is a real, un-pinned gap in that test file, left as a follow-up (see below).
+
+### Gate (all measured on the final committed state, after item 2 parts A and B)
+
+- `bun test` -> **exit 0**, `492 pass / 0 fail` (matches the coordinator's own measured
+  baseline of `492 pass / 0 fail` exactly - item 3's new pinning test is the +1 over the
+  original `491 pass / 0 fail`, and items 2A/2B added no test and changed none).
+- `pnpm exec tsc --noEmit -p packages/polyfill/tsconfig.json` -> **exit 0**.
+- `pnpm exec tsc --noEmit -p packages/polyfill/e2e/tsconfig.json` -> **exit 0**.
+- Example typecheck (`pnpm run typecheck` in `examples/notebook`) -> **exit 0**.
+- `python3 ~/.claude/skills/concept/lint.py` -> **exit 0**, `0 ERROR` (5 pre-existing
+  WARNING categories, none new).
+- e2e harness: NOT run. Nothing changed anywhere in this task (items 1, 3, 4, 2A, 2B) is
+  exercised by it: type-only exports, an annotation moved or re-kinded, doc text, one new
+  `bun:test` unit test, one dead annotation line removed.
+
+### Unused imports in account-registry.ts (confirmed, not touched)
+
+Confirmed the coordinator's reading exactly: `publishInboxAddress`, `readInboxCapsFor`,
+`ownsDocument`, `documentInboxAddress`, `subscribePhysicalDoc`, `hasReadCap` and
+`mustNotAttempt` are each imported into `packages/polyfill/src/shared-wallet/account-
+registry.ts` and appear NOWHERE else in that file as executable code - six have exactly 1
+occurrence (the import line itself) and `ownsDocument` has 2, the second being a JSDoc
+mention ("a caller that genuinely prefers to carry on catches it itself, and one does:
+`ownsDocument`, ..."), not a call. VERIFIED `noUnusedLocals` and `noUnusedParameters` are
+absent from both `packages/polyfill/tsconfig.json` and the `tsconfig.base.json` it
+extends, so both default to `false` - that is why `tsc` passes despite this. Pre-existing
+(this task's item 4 commit removed exactly one line, the `@provenance` annotation on
+`resolveScopeGraph`, confirmed by its own diff). Left untouched, as instructed - recorded
+as a follow-up only.
+
+### Surprises
+
+- **VERIFIED, corrected before acting on it:** `docs/api-contract.md` genuinely exists at
+  the repo root and is actively maintained (last touched today by the sibling task, T01.o)
+  - I initially looked only under `packages/polyfill/docs/` (which holds a different file,
+  `polyfill-reference.md`) and briefly concluded the file referenced by `index.ts`'s header
+  comment and by `test/vocabulary.test.ts` was missing/stale. It is not. Two contract
+  documents exist side by side: `docs/api-contract.md` (detailed, symbol-by-symbol, pinned
+  by three tests) and the concept contract (terser, what a consumer's `usage_` leaf pulls
+  against, now pinned by one more test after item 3).
+- **INFERRED, not verified, out of scope:** the two documents' dual maintenance is itself
+  a standing cost (item 3 is exactly this: one drifted, one didn't) - not something this
+  task was scoped to resolve.
+
+### Owner's open item
+
+- **`ShapeObservable`'s migration fate** (`packages/polyfill/src/surface/use-shape-
+  query.ts:218`). Still `kind=invention level=none ref=none`, still above the
+  `POLYFILL-ERA` divider, untouched by this task. VERIFIED it is this package's own
+  framework-agnostic getSnapshot/subscribe/refetch composition (`examples/notebook/
+  app.ts:192-217` calls `useShapeQuery` as a plain factory and manually
+  `.subscribe()`s/`.getSnapshot()`s it, not as a React hook), and VERIFIED the word
+  "ShapeObservable" does not appear anywhere in `.project/rules/nextgraph/surface-mirrors-
+  the-sdk.md`, so the `announced-not-written` route Part B used for `ShapeQuery` is not
+  available for it - honestly claiming it would require a record nobody has written. Its
+  divider placement depends on whether NextGraph's eventually-shipped `useShapeQuery`
+  needs the same wrapper or returns the snapshot directly (the way `useShape` does), which
+  is not knowable from anything in this repo. The coordinator is putting this to the
+  owner directly.
+
+### Follow-ups (not fixed, out of scope)
+
+- `test/provenance.test.ts` has no test for the direction item 4 exposed: an
+  `@provenance` annotation naming a symbol that is not actually published. Only the
+  reverse (every published symbol has an annotation) is pinned.
+- Several `docs/api-contract.md` / `index.ts` header comments cite line numbers (e.g.
+  "index.ts:48-49", "index.ts:45, :111-123") rather than symbols, which the project's own
+  citation discipline discourages (line numbers rot); pre-existing, not introduced here,
+  and not mechanically checked.
+- `.project/concepts/app-contract/polyfill-surface/contract_polyfill-surface.md` is
+  flagged by the concept linter as an oversized leaf (75 KB / 256 lines) - pre-existing,
+  a WARNING not an ERROR, unrelated to this task's changes beyond the lines added across
+  this session.
+- Seven imports in `packages/polyfill/src/shared-wallet/account-registry.ts` are unused
+  in code (`publishInboxAddress`, `readInboxCapsFor`, `ownsDocument`,
+  `documentInboxAddress`, `subscribePhysicalDoc`, `hasReadCap`, `mustNotAttempt`) -
+  confirmed above, pre-existing, `tsc` passes only because `noUnusedLocals` is off.
+- `docs/api-contract.md` §1's shown `EventuallyConfig` interface is itself stale (it
+  includes a `pointerGuard` field and omits `getObjects`/`insertObject`, neither matching
+  the real interface) - noticed while reading that section for Part A, pre-existing,
+  out of scope for this task.

AGENTS.md

@@ -1,3 +1,7 @@
 ## Project vocabulary (always loaded)
 
 @.project/VOCABULARY.md
+
+## Rules
+
+@.project/rules/INDEX.md

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

bun.lock

@@ -1,297 +0,0 @@
-{
-  "lockfileVersion": 1,
-  "configVersion": 1,
-  "workspaces": {
-    "": {
-      "name": "ng-eventually",
-      "devDependencies": {
-        "@types/bun": "latest",
-        "playwright": "^1.61.1",
-        "typescript": "^5.6.0",
-      },
-    },
-    "examples/notebook": {
-      "name": "@ng-eventually/example-notebook",
-      "dependencies": {
-        "@ng-eventually/polyfill": "workspace:*",
-        "@ng-org/web": "0.1.2-alpha.13",
-      },
-    },
-    "packages/ng-e2e-helpers": {
-      "name": "ng-e2e-helpers",
-      "version": "0.0.0",
-      "devDependencies": {
-        "@ng-org/web": "0.1.2-alpha.13",
-        "playwright": "^1.61.1",
-      },
-      "peerDependencies": {
-        "@ng-org/web": ">=0.1.2-alpha.13",
-        "playwright": ">=1.40.0",
-      },
-    },
-    "packages/polyfill": {
-      "name": "@ng-eventually/polyfill",
-      "version": "0.0.0",
-      "devDependencies": {
-        "@ng-org/alien-deepsignals": "0.1.2-alpha.11",
-        "@ng-org/shex-orm": "0.1.2-alpha.8",
-        "@ng-org/web": "0.1.2-alpha.13",
-      },
-      "peerDependencies": {
-        "@ng-org/alien-deepsignals": "*",
-        "@ng-org/orm": "*",
-        "@ng-org/shex-orm": "*",
-        "@ng-org/web": "*",
-      },
-      "optionalPeers": [
-        "@ng-org/alien-deepsignals",
-        "@ng-org/orm",
-        "@ng-org/shex-orm",
-        "@ng-org/web",
-      ],
-    },
-  },
-  "packages": {
-    "@ldo/traverser-shexj": ["@ldo/traverser-shexj@1.0.0-alpha.28", "", { "dependencies": { "@ldo/type-traverser": "1.0.0-alpha.28" } }, "sha512-N06+LOWhv6//unPRLbFMd56MqPf5lO2ihZgle9hNLmxt6QJmNrZM3oXzHCL3TfDu4OT1/NUZp3kj2HmztQIZkg=="],
-
-    "@ldo/type-traverser": ["@ldo/type-traverser@1.0.0-alpha.28", "", { "dependencies": { "uuid": "8.3.2" } }, "sha512-pGMIVxLzoLjYVhADuVhg6r5ZDNleXZ9DcyIvLXo1/ADEocLnysg/Xjk9D/7l/Rw3WtDJrTFOOtBv8OnH+VPgKA=="],
-
-    "@ng-eventually/example-notebook": ["@ng-eventually/example-notebook@workspace:examples/notebook"],
-
-    "@ng-eventually/polyfill": ["@ng-eventually/polyfill@workspace:packages/polyfill"],
-
-    "@ng-org/alien-deepsignals": ["@ng-org/alien-deepsignals@0.1.2-alpha.11", "", { "dependencies": { "alien-signals": "2.0.8" } }, "sha512-nPgqOrheAda/pW5FHgSb45SrSZWuyMyEVqO683ijEsVPpD105bngfh92PPfcRoRnFzGSoKXa3CfuqUHi2+qVIQ=="],
-
-    "@ng-org/shex-orm": ["@ng-org/shex-orm@0.1.2-alpha.8", "", { "dependencies": { "@ldo/traverser-shexj": "1.0.0-alpha.28", "@ldo/type-traverser": "1.0.0-alpha.28", "@shexjs/parser": "1.0.0-alpha.28", "commander": "14.0.3", "dts-dom": "3.6.0", "ejs": "3.1.10", "fs-extra": "10.1.0", "jsonld2graphobject": "0.0.5", "loading-cli": "1.1.2", "prettier": "3.9.5" }, "peerDependencies": { "typescript": "5.9.3" }, "bin": { "rdf-orm": "dist/cli.js" } }, "sha512-jogxiLfUtI3WkuF5O3PPwRBRWylpapk/JlvElGUqZnEavXXlEMmEGbK3VwqMUsbp1pweNA0sEKIFLIk3Lzt2Gg=="],
-
-    "@ng-org/web": ["@ng-org/web@0.1.2-alpha.13", "", { "dependencies": { "async-proxy": "0.4.1" } }, "sha512-/xO0c+3NTphnws5Do2LDqgZWmAf+aNnYdChJKdU0dnp1U1iVSgi/y3yb8AYryf0v9sooj0aYJxt08B6DpirFMQ=="],
-
-    "@rdfjs/types": ["@rdfjs/types@1.1.2", "", { "dependencies": { "@types/node": "26.1.1" } }, "sha512-wqpOJK1QCbmsGNtyzYnojPU8gRDPid2JO0Q0kMtb4j65xhCK880cnKAfEOwC+dX85VJcCByQx5zOwyyfCjDJsg=="],
-
-    "@shexjs/parser": ["@shexjs/parser@1.0.0-alpha.28", "", { "dependencies": { "@shexjs/util": "1.0.0-alpha.28", "@ts-jison/parser": "0.4.1-alpha.1" } }, "sha512-eeVeHq/2JG9X+3h7y+7EmuBSWWl2EMj/EQBLk5CTRx4W4hWDdjWczsY8RWwKjkIzLwUS1+G0aiAI1u5LHCZ2Rw=="],
-
-    "@shexjs/term": ["@shexjs/term@1.0.0-alpha.27", "", { "dependencies": { "@types/shexj": "2.1.7", "rdf-data-factory": "1.1.3", "relativize-url": "0.1.0" } }, "sha512-+D7P7pglRPTZC2RkwaQuq+cgBZImx+61JZtcN77uEJVqcGaIscQK5hScsKhAPIo16/I+4jhIUCEFojXqw6otpg=="],
-
-    "@shexjs/util": ["@shexjs/util@1.0.0-alpha.28", "", { "dependencies": { "@shexjs/term": "1.0.0-alpha.27", "@shexjs/visitor": "1.0.0-alpha.27", "@types/shexj": "2.1.7", "hierarchy-closure": "1.2.2", "sync-request": "6.1.0" } }, "sha512-L8pBokTU/5eNRJPkC8R9SIgPw6/JDh/bHKdV5TZzf8/FkOMNJwKIy6UDHXM1I8FJ+c8u2gOOHp2MA+7b+md+0A=="],
-
-    "@shexjs/visitor": ["@shexjs/visitor@1.0.0-alpha.27", "", {}, "sha512-9s67A+f0ZZNw/SNxqoi1483CqUca8dbnHM6WDWsRH4+eXlQpQqwOZDxA8uKEaWeX4VcDrDwzWpr0WvK6EyDWIQ=="],
-
-    "@ts-jison/common": ["@ts-jison/common@0.4.1-alpha.1", "", {}, "sha512-SDbHzq+UMD+V3ciKVBHwCEgVqSeyQPTCjOsd/ZNTGySUVg4x3EauR9ZcEfdVFAsYRR38XWgDI+spq5LDY46KvQ=="],
-
-    "@ts-jison/lexer": ["@ts-jison/lexer@0.4.1-alpha.1", "", { "dependencies": { "@ts-jison/common": "0.4.1-alpha.1" } }, "sha512-5C1Wr+wixAzn2MOFtgy7KbT6N6j9mhmbjAtyvOqZKsikKtNOQj22MM5HxT+ooRexG2NbtxnDSXYdhHR1Lg58ow=="],
-
-    "@ts-jison/parser": ["@ts-jison/parser@0.4.1-alpha.1", "", { "dependencies": { "@ts-jison/common": "0.4.1-alpha.1", "@ts-jison/lexer": "0.4.1-alpha.1" } }, "sha512-xNj+qOez/7dju44LlYiTlCjxMzW5oek9EckUAElfln/GBK9vgMSk0swWcnacMr0TYbGjUQuXvL2wEgmDf5WajQ=="],
-
-    "@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
-
-    "@types/concat-stream": ["@types/concat-stream@1.6.1", "", { "dependencies": { "@types/node": "8.10.66" } }, "sha512-eHE4cQPoj6ngxBZMvVf6Hw7Mh4jMW4U9lpGmS5GBPB9RYxlFg+CHaVN7ErNY4W9XfLIEn20b4VDYaIrbq0q4uA=="],
-
-    "@types/form-data": ["@types/form-data@0.0.33", "", { "dependencies": { "@types/node": "8.10.66" } }, "sha512-8BSvG1kGm83cyJITQMZSulnl6QV8jqAGreJsc5tPu1Jq0vTSOiY/k24Wx82JRpWwZSqrala6sd5rWi6aNXvqcw=="],
-
-    "@types/http-link-header": ["@types/http-link-header@1.0.7", "", { "dependencies": { "@types/node": "18.19.130" } }, "sha512-snm5oLckop0K3cTDAiBnZDy6ncx9DJ3mCRDvs42C884MbVYPP74Tiq2hFsSDRTyjK6RyDYDIulPiW23ge+g5Lw=="],
-
-    "@types/jsonld": ["@types/jsonld@1.5.15", "", {}, "sha512-PlAFPZjL+AuGYmwlqwKEL0IMP8M8RexH0NIPGfCVWSQ041H2rR/8OlyZSD7KsCVoN8vCfWdtWDBxX8yBVP+xow=="],
-
-    "@types/node": ["@types/node@26.1.1", "", { "dependencies": { "undici-types": "8.3.0" } }, "sha512-nxAkRSVkN1Y0JC1W8ky/fTfkGsMmcrRsbx+3XoZE+rMOX71kLYTV7fLXpqud1GpbpP5TuffXFqfX7fH2GgZREw=="],
-
-    "@types/qs": ["@types/qs@6.15.1", "", {}, "sha512-GZHUBZR9hckSUhrxmp1nG6NwdpM9fCunJwyThLW1X3AyHgd9IlHb6VANpQQqDr2o/qQp6McZ3y/IA2rVzKzSbw=="],
-
-    "@types/shexj": ["@types/shexj@2.1.7", "", {}, "sha512-pu/0vIZxFTMPVjTlo5MJKFkBL/EbAuFhtCXpmBB7ZdUiyNpc6pt8GxfyRPqdf6q2SsWu71a/vbhvGK2IZN2Eug=="],
-
-    "alien-signals": ["alien-signals@2.0.8", "", {}, "sha512-844G1VLkk0Pe2SJjY0J8vp8ADI73IM4KliNu2OGlYzWpO28NexEUvjHTcFjFX3VXoiUtwTbHxLNI9ImkcoBqzA=="],
-
-    "asap": ["asap@2.0.6", "", {}, "sha512-BSHWgDSAiKs50o2Re8ppvp3seVHXSRM44cdSsT9FfNEUUZLOGWVCsiWaRPWM1Znn+mqZ1OfVZ3z3DWEzSp7hRA=="],
-
-    "async": ["async@3.2.6", "", {}, "sha512-htCUDlxyyCLMgaM3xXg0C0LW2xqfuQ6p05pCEIsXuyQ+a1koYKTuBMzRNwmybfLgvJDMd0r1LTn4+E0Ti6C2AA=="],
-
-    "async-proxy": ["async-proxy@0.4.1", "", { "dependencies": { "object-path-operator": "3.0.0" } }, "sha512-4e+zNtoGL4+cnqib8v169CnKcRfAsAubp2EsjBhAA5jyW7jjI3t36rVvuqLwmhtliwf8JvSnxinE4ecQN+DK4w=="],
-
-    "asynckit": ["asynckit@0.4.0", "", {}, "sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q=="],
-
-    "balanced-match": ["balanced-match@1.0.2", "", {}, "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw=="],
-
-    "brace-expansion": ["brace-expansion@2.1.2", "", { "dependencies": { "balanced-match": "1.0.2" } }, "sha512-w5JZcKgdhDOgOwm8H+KgbosopHMuGcl6qbulwjtz3SM7I7P3yW1eAjzMPLrIE+NQ9vjgANKHWeMHnrT0OXW1oA=="],
-
-    "buffer-from": ["buffer-from@1.1.2", "", {}, "sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ=="],
-
-    "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "26.1.1" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
-
-    "call-bind-apply-helpers": ["call-bind-apply-helpers@1.0.2", "", { "dependencies": { "es-errors": "1.3.0", "function-bind": "1.1.2" } }, "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ=="],
-
-    "call-bound": ["call-bound@1.0.4", "", { "dependencies": { "call-bind-apply-helpers": "1.0.2", "get-intrinsic": "1.3.0" } }, "sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg=="],
-
-    "caseless": ["caseless@0.12.0", "", {}, "sha512-4tYFyifaFfGacoiObjJegolkwSU4xQNGbVgUiNYVUxbQ2x2lUsFvY4hVgVzGiIe6WLOPqycWXA40l+PWsxthUw=="],
-
-    "colors-cli": ["colors-cli@1.0.33", "", { "bin": { "colors": "bin/colors" } }, "sha512-PWGsmoJFdOB0t+BeHgmtuoRZUQucOLl5ii81NBzOOGVxlgE04muFNHlR5j8i8MKbOPELBl3243AI6lGBTj5ICQ=="],
-
-    "combined-stream": ["combined-stream@1.0.8", "", { "dependencies": { "delayed-stream": "1.0.0" } }, "sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg=="],
-
-    "commander": ["commander@14.0.3", "", {}, "sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw=="],
-
-    "concat-stream": ["concat-stream@1.6.2", "", { "dependencies": { "buffer-from": "1.1.2", "inherits": "2.0.4", "readable-stream": "2.3.8", "typedarray": "0.0.6" } }, "sha512-27HBghJxjiZtIk3Ycvn/4kbJk/1uZuJFfuPEns6LaEvpvG1f0hTea8lilrouyo9mVc2GWdcEZ8OLoGmSADlrCw=="],
-
-    "core-util-is": ["core-util-is@1.0.3", "", {}, "sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ=="],
-
-    "cross-fetch": ["cross-fetch@3.2.0", "", { "dependencies": { "node-fetch": "2.7.0" } }, "sha512-Q+xVJLoGOeIMXZmbUK4HYk+69cQH6LudR0Vu/pRm2YlU/hDV9CiS0gKUMaWY5f2NeUH9C1nV3bsTlCo0FsTV1Q=="],
-
-    "delayed-stream": ["delayed-stream@1.0.0", "", {}, "sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ=="],
-
-    "dts-dom": ["dts-dom@3.6.0", "", {}, "sha512-on5jxTgt+A6r0Zyyz6ZRHXaAO7J1VPnOd6+AmvI1vH440AlAZZNc5rUHzgPuTjGlrVr1rOWQYNl7ZJK6rDohbw=="],
-
-    "dunder-proto": ["dunder-proto@1.0.1", "", { "dependencies": { "call-bind-apply-helpers": "1.0.2", "es-errors": "1.3.0", "gopd": "1.2.0" } }, "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A=="],
-
-    "ejs": ["ejs@3.1.10", "", { "dependencies": { "jake": "10.9.4" }, "bin": { "ejs": "bin/cli.js" } }, "sha512-UeJmFfOrAQS8OJWPZ4qtgHyWExa088/MtK5UEyoJGFH67cDEXkZSviOiKRCZ4Xij0zxI3JECgYs3oKx+AizQBA=="],
-
-    "es-define-property": ["es-define-property@1.0.1", "", {}, "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g=="],
-
-    "es-errors": ["es-errors@1.3.0", "", {}, "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw=="],
-
-    "es-object-atoms": ["es-object-atoms@1.1.2", "", { "dependencies": { "es-errors": "1.3.0" } }, "sha512-HWcBoN6NileqtSydK2FqHbS/LoDd2pqrnQHLyJzBj4kOp/ky2MWMN694xOfkK8/SnUsW2DH7EfyVlydKCsm1Zw=="],
-
-    "es-set-tostringtag": ["es-set-tostringtag@2.1.0", "", { "dependencies": { "es-errors": "1.3.0", "get-intrinsic": "1.3.0", "has-tostringtag": "1.0.2", "hasown": "2.0.4" } }, "sha512-j6vWzfrGVfyXxge+O0x5sh6cvxAog0a/4Rdd2K36zCMV5eJ+/+tOAngRO8cODMNWbVRdVlmGZQL2YS3yR8bIUA=="],
-
-    "filelist": ["filelist@1.0.6", "", { "dependencies": { "minimatch": "5.1.9" } }, "sha512-5giy2PkLYY1cP39p17Ech+2xlpTRL9HLspOfEgm0L6CwBXBTgsK5ou0JtzYuepxkaQ/tvhCFIJ5uXo0OrM2DxA=="],
-
-    "form-data": ["form-data@2.5.6", "", { "dependencies": { "asynckit": "0.4.0", "combined-stream": "1.0.8", "es-set-tostringtag": "2.1.0", "hasown": "2.0.4", "mime-types": "2.1.35", "safe-buffer": "5.2.1" } }, "sha512-Ogz/E85h9tlfJzpI6TuFpGcHZFhLrb9Gw8wq9v40CxSCPnv7ahKr6Xgtkn0KYCDQJ8DNn5VoMO8EXr9V5PadyA=="],
-
-    "fs-extra": ["fs-extra@10.1.0", "", { "dependencies": { "graceful-fs": "4.2.11", "jsonfile": "6.2.1", "universalify": "2.0.1" } }, "sha512-oRXApq54ETRj4eMiFzGnHWGy+zo5raudjuxN0b8H7s/RU2oW0Wvsx9O0ACRN/kRq9E8Vu/ReskGB5o3ji+FzHQ=="],
-
-    "fsevents": ["fsevents@2.3.2", "", { "os": "darwin" }, "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA=="],
-
-    "function-bind": ["function-bind@1.1.2", "", {}, "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA=="],
-
-    "get-intrinsic": ["get-intrinsic@1.3.0", "", { "dependencies": { "call-bind-apply-helpers": "1.0.2", "es-define-property": "1.0.1", "es-errors": "1.3.0", "es-object-atoms": "1.1.2", "function-bind": "1.1.2", "get-proto": "1.0.1", "gopd": "1.2.0", "has-symbols": "1.1.0", "hasown": "2.0.4", "math-intrinsics": "1.1.0" } }, "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ=="],
-
-    "get-port": ["get-port@3.2.0", "", {}, "sha512-x5UJKlgeUiNT8nyo/AcnwLnZuZNcSjSw0kogRB+Whd1fjjFq4B1hySFxSFWWSn4mIBzg3sRNUDFYc4g5gjPoLg=="],
-
-    "get-proto": ["get-proto@1.0.1", "", { "dependencies": { "dunder-proto": "1.0.1", "es-object-atoms": "1.1.2" } }, "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g=="],
-
-    "gopd": ["gopd@1.2.0", "", {}, "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg=="],
-
-    "graceful-fs": ["graceful-fs@4.2.11", "", {}, "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ=="],
-
-    "has-symbols": ["has-symbols@1.1.0", "", {}, "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ=="],
-
-    "has-tostringtag": ["has-tostringtag@1.0.2", "", { "dependencies": { "has-symbols": "1.1.0" } }, "sha512-NqADB8VjPFLM2V0VvHUewwwsw0ZWBaIdgo+ieHtK3hasLz4qeCRjYcqfB6AQrBggRKppKF8L52/VqdVsO47Dlw=="],
-
-    "hasown": ["hasown@2.0.4", "", { "dependencies": { "function-bind": "1.1.2" } }, "sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A=="],
-
-    "hierarchy-closure": ["hierarchy-closure@1.2.2", "", {}, "sha512-ZqZvsA6HyMqrmm49D3llYA8x8hqdyDDEkaTXcqwyO+fGQlzxoeXws/5ze11M40s4EoTw7GFxdTKIwj5YDOicLQ=="],
-
-    "http-basic": ["http-basic@8.1.3", "", { "dependencies": { "caseless": "0.12.0", "concat-stream": "1.6.2", "http-response-object": "3.0.2", "parse-cache-control": "1.0.1" } }, "sha512-/EcDMwJZh3mABI2NhGfHOGOeOZITqfkEO4p/xK+l3NpyncIHUQBoMvCSF/b5GqvKtySC2srL/GGG3+EtlqlmCw=="],
-
-    "http-link-header": ["http-link-header@1.1.4", "", {}, "sha512-xT3GPW6/ZbGuw4UvwHqErSCEjNUlwbQJuZn9/q5U4WEKfp2kENVCAlousG1zLxHeaQ/ffOHUNpWamvkbBW0eNw=="],
-
-    "http-response-object": ["http-response-object@3.0.2", "", { "dependencies": { "@types/node": "10.17.60" } }, "sha512-bqX0XTF6fnXSQcEJ2Iuyr75yVakyjIDCqroJQ/aHfSdlM743Cwqoi2nDYMzLGWUcuTWGWy8AAvOKXTfiv6q9RA=="],
-
-    "inherits": ["inherits@2.0.4", "", {}, "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="],
-
-    "isarray": ["isarray@1.0.0", "", {}, "sha512-VLghIWNM6ELQzo7zwmcg0NmTVyWKYjvIeM83yjp0wRDTmUnrM678fQbcKBo6n2CJEF0szoG//ytg+TKla89ALQ=="],
-
-    "jake": ["jake@10.9.4", "", { "dependencies": { "async": "3.2.6", "filelist": "1.0.6", "picocolors": "1.1.1" }, "bin": { "jake": "bin/cli.js" } }, "sha512-wpHYzhxiVQL+IV05BLE2Xn34zW1S223hvjtqk0+gsPrwd/8JNLXJgZZM/iPFsYc1xyphF+6M6EvdE5E9MBGkDA=="],
-
-    "jsonfile": ["jsonfile@6.2.1", "", { "dependencies": { "universalify": "2.0.1" }, "optionalDependencies": { "graceful-fs": "4.2.11" } }, "sha512-zwOTdL3rFQ/lRdBnntKVOX6k5cKJwEc1HdilT71BWEu7J41gXIB2MRp+vxduPSwZJPWBxEzv4yH1wYLJGUHX4Q=="],
-
-    "jsonld-context-parser": ["jsonld-context-parser@2.4.0", "", { "dependencies": { "@types/http-link-header": "1.0.7", "@types/node": "18.19.130", "cross-fetch": "3.2.0", "http-link-header": "1.1.4", "relative-to-absolute-iri": "1.0.8" }, "bin": { "jsonld-context-parse": "bin/jsonld-context-parse.js" } }, "sha512-ZYOfvh525SdPd9ReYY58dxB3E2RUEU4DJ6ZibO8AitcowPeBH4L5rCAitE2om5G1P+HMEgYEYEr4EZKbVN4tpA=="],
-
-    "jsonld2graphobject": ["jsonld2graphobject@0.0.5", "", { "dependencies": { "@rdfjs/types": "1.1.2", "@types/jsonld": "1.5.15", "jsonld-context-parser": "2.4.0", "uuid": "8.3.2" } }, "sha512-5BqfXOq96+OBjjiJNG8gQH66pYt6hW88z2SJxdvFJo4XNoVMvqAcUz+JSm/KEWS5NLRnebApEzFrYP3HUiUmYw=="],
-
-    "loading-cli": ["loading-cli@1.1.2", "", { "dependencies": { "colors-cli": "1.0.33" } }, "sha512-M1ntfXHpdGoQxfaqKBOQPwSrTr9EIoTgj664Q9UVSbSnJvAFdribo+Ij//1jvACgrGHaTvfKoD9PG3NOxGj44g=="],
-
-    "math-intrinsics": ["math-intrinsics@1.1.0", "", {}, "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g=="],
-
-    "mime-db": ["mime-db@1.52.0", "", {}, "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg=="],
-
-    "mime-types": ["mime-types@2.1.35", "", { "dependencies": { "mime-db": "1.52.0" } }, "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw=="],
-
-    "minimatch": ["minimatch@5.1.9", "", { "dependencies": { "brace-expansion": "2.1.2" } }, "sha512-7o1wEA2RyMP7Iu7GNba9vc0RWWGACJOCZBJX2GJWip0ikV+wcOsgVuY9uE8CPiyQhkGFSlhuSkZPavN7u1c2Fw=="],
-
-    "ng-e2e-helpers": ["ng-e2e-helpers@workspace:packages/ng-e2e-helpers"],
-
-    "node-fetch": ["node-fetch@2.7.0", "", { "dependencies": { "whatwg-url": "5.0.0" } }, "sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A=="],
-
-    "object-inspect": ["object-inspect@1.13.4", "", {}, "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew=="],
-
-    "object-path-operator": ["object-path-operator@3.0.0", "", {}, "sha512-Z7dlPUeXqRU/lLfGerP24dPC66n7ehyXaTM81k71EFlsaaEjOHkf4/uq1WGicfGfiO7snYShneE1YZZUkyRiLQ=="],
-
-    "parse-cache-control": ["parse-cache-control@1.0.1", "", {}, "sha512-60zvsJReQPX5/QP0Kzfd/VrpjScIQ7SHBW6bFCYfEP+fp0Eppr1SHhIO5nd1PjZtvclzSzES9D/p5nFJurwfWg=="],
-
-    "picocolors": ["picocolors@1.1.1", "", {}, "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA=="],
-
-    "playwright": ["playwright@1.61.1", "", { "dependencies": { "playwright-core": "1.61.1" }, "optionalDependencies": { "fsevents": "2.3.2" }, "bin": { "playwright": "cli.js" } }, "sha512-DWnY5o3YbLWK4GovuAVwpqL+1VwGNdUGrRr++8j8PtQQzvAVZUIMjKQ90fY689sEJZJBbZVw1rXaOKSTitkzPQ=="],
-
-    "playwright-core": ["playwright-core@1.61.1", "", { "bin": { "playwright-core": "cli.js" } }, "sha512-h7Qlt6m4REp25qvIdvbDtVmD4LqVXfpRxhORv9L0jzETM05p4fuPJ3dKyuSXQxDSbXnmS79HAgi9589lGSpLkg=="],
-
-    "prettier": ["prettier@3.9.5", "", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-/FVl766LpUfB5vXgCYOYa0MeV/441Ia99AeICQIQFTY/Nw0roZwULcXpku5i1/m5kt/baz+s4Zogspd839HSMg=="],
-
-    "process-nextick-args": ["process-nextick-args@2.0.1", "", {}, "sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag=="],
-
-    "promise": ["promise@8.3.0", "", { "dependencies": { "asap": "2.0.6" } }, "sha512-rZPNPKTOYVNEEKFaq1HqTgOwZD+4/YHS5ukLzQCypkj+OkYx7iv0mA91lJlpPPZ8vMau3IIGj5Qlwrx+8iiSmg=="],
-
-    "qs": ["qs@6.15.3", "", { "dependencies": { "es-define-property": "1.0.1", "side-channel": "1.1.1" } }, "sha512-O9gl3zCl5h5blw1KGUzQKhA5oUXSl8rwUIM5o0S3nCXMliSvy5Dzx7/DJcI+SwgICv+IneSZwhBh1oSyEHA71A=="],
-
-    "rdf-data-factory": ["rdf-data-factory@1.1.3", "", { "dependencies": { "@rdfjs/types": "1.1.2" } }, "sha512-ny6CI7m2bq4lfQQmDYvcb2l1F9KtGwz9chipX4oWu2aAtVoXjb7k3d8J1EsgAsEbMXnBipB/iuRen5H2fwRWWQ=="],
-
-    "readable-stream": ["readable-stream@2.3.8", "", { "dependencies": { "core-util-is": "1.0.3", "inherits": "2.0.4", "isarray": "1.0.0", "process-nextick-args": "2.0.1", "safe-buffer": "5.1.2", "string_decoder": "1.1.1", "util-deprecate": "1.0.2" } }, "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA=="],
-
-    "relative-to-absolute-iri": ["relative-to-absolute-iri@1.0.8", "", {}, "sha512-U1TmhrhCmXKkDL9mI8gBbF5TN6TKcuv28k5+H3gMCAjoz0TyyHAICHlaGDZsTEBSu2Y3HhDKc8e6X9n33qeIqA=="],
-
-    "relativize-url": ["relativize-url@0.1.0", "", {}, "sha512-YXet4a9wQP96Ru9MQSfoRUzsCaeboLPXj+rVG1ulH4t54zqFHiNmW6FPl7V2dTxk9uHlW3yb9+1jWO44AdWisw=="],
-
-    "safe-buffer": ["safe-buffer@5.2.1", "", {}, "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ=="],
-
-    "side-channel": ["side-channel@1.1.1", "", { "dependencies": { "es-errors": "1.3.0", "object-inspect": "1.13.4", "side-channel-list": "1.0.1", "side-channel-map": "1.0.1", "side-channel-weakmap": "1.0.2" } }, "sha512-6x6dK6zJdpTzF4sQeNYxwtvBzf6Eg4GtlesS94HOvTudUeyK2WXAaIfmDgsyslYrRBeFIlsi54AYsFGUuhmvrQ=="],
-
-    "side-channel-list": ["side-channel-list@1.0.1", "", { "dependencies": { "es-errors": "1.3.0", "object-inspect": "1.13.4" } }, "sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w=="],
-
-    "side-channel-map": ["side-channel-map@1.0.1", "", { "dependencies": { "call-bound": "1.0.4", "es-errors": "1.3.0", "get-intrinsic": "1.3.0", "object-inspect": "1.13.4" } }, "sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA=="],
-
-    "side-channel-weakmap": ["side-channel-weakmap@1.0.2", "", { "dependencies": { "call-bound": "1.0.4", "es-errors": "1.3.0", "get-intrinsic": "1.3.0", "object-inspect": "1.13.4", "side-channel-map": "1.0.1" } }, "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A=="],
-
-    "string_decoder": ["string_decoder@1.1.1", "", { "dependencies": { "safe-buffer": "5.1.2" } }, "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg=="],
-
-    "sync-request": ["sync-request@6.1.0", "", { "dependencies": { "http-response-object": "3.0.2", "sync-rpc": "1.3.7", "then-request": "6.0.2" } }, "sha512-8fjNkrNlNCrVc/av+Jn+xxqfCjYaBoHqCsDz6mt030UMxJGr+GSfCV1dQt2gRtlL63+VPidwDVLr7V2OcTSdRw=="],
-
-    "sync-rpc": ["sync-rpc@1.3.7", "", { "dependencies": { "get-port": "3.2.0" } }, "sha512-YHciI7TUxL8EPqz/bg01sZfwuzQA0odao1wf1Ywdtw7j5vl30aQ6s+bLRTvgPPgzr94cg+WMm6Bxi/P7BJOxgw=="],
-
-    "then-request": ["then-request@6.0.2", "", { "dependencies": { "@types/concat-stream": "1.6.1", "@types/form-data": "0.0.33", "@types/node": "8.10.66", "@types/qs": "6.15.1", "caseless": "0.12.0", "concat-stream": "1.6.2", "form-data": "2.5.6", "http-basic": "8.1.3", "http-response-object": "3.0.2", "promise": "8.3.0", "qs": "6.15.3" } }, "sha512-3ZBiG7JvP3wbDzA9iNY5zJQcHL4jn/0BWtXIkagfz7QgOL/LqjCEOBQuJNZfu0XYnv5JhKh+cDxCPM4ILrqruA=="],
-
-    "tr46": ["tr46@0.0.3", "", {}, "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw=="],
-
-    "typedarray": ["typedarray@0.0.6", "", {}, "sha512-/aCDEGatGvZ2BIk+HmLf4ifCJFwvKFNb9/JeZPMulfgFracn9QFcAf5GO8B/mweUjSoblS5In0cWhqpfs/5PQA=="],
-
-    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
-
-    "undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="],
-
-    "universalify": ["universalify@2.0.1", "", {}, "sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw=="],
-
-    "util-deprecate": ["util-deprecate@1.0.2", "", {}, "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw=="],
-
-    "uuid": ["uuid@8.3.2", "", { "bin": { "uuid": "dist/bin/uuid" } }, "sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg=="],
-
-    "webidl-conversions": ["webidl-conversions@3.0.1", "", {}, "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ=="],
-
-    "whatwg-url": ["whatwg-url@5.0.0", "", { "dependencies": { "tr46": "0.0.3", "webidl-conversions": "3.0.1" } }, "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw=="],
-
-    "@types/concat-stream/@types/node": ["@types/node@8.10.66", "", {}, "sha512-tktOkFUA4kXx2hhhrB8bIFb5TbwzS4uOhKEmwiD+NoiL0qtP2OQ9mFldbgD4dV1djrlBYP6eBuQZiWjuHUpqFw=="],
-
-    "@types/form-data/@types/node": ["@types/node@8.10.66", "", {}, "sha512-tktOkFUA4kXx2hhhrB8bIFb5TbwzS4uOhKEmwiD+NoiL0qtP2OQ9mFldbgD4dV1djrlBYP6eBuQZiWjuHUpqFw=="],
-
-    "@types/http-link-header/@types/node": ["@types/node@18.19.130", "", { "dependencies": { "undici-types": "5.26.5" } }, "sha512-GRaXQx6jGfL8sKfaIDD6OupbIHBr9jv7Jnaml9tB7l4v068PAOXqfcujMMo5PhbIs6ggR1XODELqahT2R8v0fg=="],
-
-    "http-response-object/@types/node": ["@types/node@10.17.60", "", {}, "sha512-F0KIgDJfy2nA3zMLmWGKxcH2ZVEtCZXHHdOQs2gSaQ27+lNeEfGxzkIw90aXswATX7AZ33tahPbzy6KAfUreVw=="],
-
-    "jsonld-context-parser/@types/node": ["@types/node@18.19.130", "", { "dependencies": { "undici-types": "5.26.5" } }, "sha512-GRaXQx6jGfL8sKfaIDD6OupbIHBr9jv7Jnaml9tB7l4v068PAOXqfcujMMo5PhbIs6ggR1XODELqahT2R8v0fg=="],
-
-    "readable-stream/safe-buffer": ["safe-buffer@5.1.2", "", {}, "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g=="],
-
-    "string_decoder/safe-buffer": ["safe-buffer@5.1.2", "", {}, "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g=="],
-
-    "then-request/@types/node": ["@types/node@8.10.66", "", {}, "sha512-tktOkFUA4kXx2hhhrB8bIFb5TbwzS4uOhKEmwiD+NoiL0qtP2OQ9mFldbgD4dV1djrlBYP6eBuQZiWjuHUpqFw=="],
-
-    "@types/http-link-header/@types/node/undici-types": ["undici-types@5.26.5", "", {}, "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA=="],
-
-    "jsonld-context-parser/@types/node/undici-types": ["undici-types@5.26.5", "", {}, "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA=="],
-  }
-}

docs/api-contract.md

@@ -1,6 +1,6 @@
 # API contract — what `@ng-eventually/polyfill` exposes today, and what the future SDK should expose per subject
 
-> **Updated 2026-08-03, after the source layout was reorganised by migration fate** (`docs/source-layout-by-fate.md`). Paths, and three names, changed under this document: `readModel` became the directly-exported `readUnion`; `accounts` / `AccountRecord` / `AccountStorage` became `virtualUsers` / `VirtualUserRecord` / `VirtualUserStorage` (module `shared-wallet/virtual-users.ts`); `store-registry-api.ts` became `surface/placement.ts`. Two modules were created and are covered here: `emulated-verifier/branch-registers.ts` (the four durable registers, split out of the shim) and `shared-wallet/bootstrap.ts` (the injection store, split out of the `/polyfill` entry). The subject-by-subject rulings below are unaffected — what moved is where the code lives, not what it promises.
+> **Updated 2026-08-03, after the source layout was reorganised by migration fate** (`docs/source-layout-by-fate.md`). Paths, and three names, changed under this document: `readModel` became the directly-exported `readUnion` (itself removed in `1.0.0-dev.8` — see § 6); `accounts` / `AccountRecord` / `AccountStorage` became `virtualUsers` / `VirtualUserRecord` / `VirtualUserStorage` (module `shared-wallet/virtual-users.ts`); `store-registry-api.ts` became `surface/placement.ts`. Two modules were created and are covered here: `emulated-verifier/branch-registers.ts` (the four durable registers, split out of the shim) and `shared-wallet/bootstrap.ts` (the injection store, split out of the `/polyfill` entry). The subject-by-subject rulings below are unaffected — what moved is where the code lives, not what it promises.
 
 **Scope: the APP-FACING contract only.** Everything reachable from the published entry point, and nothing else. The library's internal modules — the shim machinery, the read paths, the boundary guards — are held to the same standard (as close as possible to what NextGraph does or plans) but have their own document, `docs/internal-contract.md`: a consumer never reads that one, a maintainer does. This split was made on 2026-08-03, together with the export change described in § 15.
 
@@ -47,7 +47,11 @@ The prose labels above map onto the annotation's closed `kind` set, and where th
 // shared-wallet/bootstrap.ts
 export interface EventuallyConfig {
   ng: NgLike;                                    // the REAL @ng-org/web ng
-  useShape: UseShapeLike;                        // the REAL @ng-org/orm useShape
+  useShape: UseShapeLike;                        // the REAL React hook: `@ng-org/orm/react`'s
+                                                 // default export, or `reactUseShape` from
+                                                 // `@ng-org/orm/all`. NOT on the main entry:
+                                                 // `.` resolves to `core`, which has no `useShape`.
+  ormSubscription?: OrmSubscriptionLike;         // the REAL @ng-org/orm RdfOrmSubscription.getOrCreate
   pointerGuard?: { attempts?: number; baseMs?: number; maxStepMs?: number };
   sharedWallet?: SharedWalletConfig;             // the gate's, § 2bis
   debugAccessLog?: boolean;
@@ -75,7 +79,9 @@ export function configure(c: EventuallyConfig): void;
 
 Both remain substitutable through `configureStoreRegistry` (`shared-wallet/bootstrap.ts`), which the published entry does not re-export: the unit suites have no browser and the e2e harness holds a session the broker handed it directly, and neither is an application.
 
-So an application's whole bootstrap is `configure({ ng, useShape, init, sharedWallet })` plus `await ensureIdentity()` — and the second of those keeps its call site after migration.
+**One field ARRIVED in `1.0.0-dev.6`: `ormSubscription`.** `useShapeQuery` reads through the SDK's own shape query now (§ 5), and the SDK is injected here rather than imported — so the query has to arrive the same way the `ng` and the `useShape` beside it do. Pass `RdfOrmSubscription.getOrCreate` as it stands; it is assignable to `OrmSubscriptionLike` with no wrapper. It is OPTIONAL because an application that never calls `useShapeQuery` has nothing to give, and `useShapeQuery` without it publishes `isError` naming the field rather than an empty set.
+
+So an application's whole bootstrap is `configure({ ng, useShape, ormSubscription, init, sharedWallet })` plus `await ensureIdentity()` — and the second of those keeps its call site after migration.
 
 ### Target
 
@@ -91,13 +97,14 @@ So an application's whole bootstrap is `configure({ ng, useShape, init, sharedWa
 // lifecycle.ts:11 — settles the identity, wraps the callback, then forwards to the real
 // @ng-org/web init injected at configure()
 export function init(...args: any[]): any;
-// lifecycle.ts:18 — forwards to the real @ng-org/orm initNg injected at configure()
+// lifecycle.ts:18 - forwards to the real @ng-org/orm initNg injected at configure(),
+// with the `ng` in position 0 replaced by this package's wrapped one
 export function initNg(...args: any[]): any;
 ```
 
 ### Target
 
-**PASSTHROUGH, VERIFIED at both levels — with one argument touched, deliberately.** `init`'s callback in position 0 is wrapped since 2026-08-12: the wrapper reads the event, keeps the session it carries (§ 1), and calls the caller's callback with that same event, unchanged. Everything else — the remaining arguments, the return value, what the callback observes — passes straight through, so an application's call site is what it would write against the real SDK. This is the only place the capture can sit: it is the only one that knows both what the caller asked and what the SDK will answer, and the alternative was every consumer re-implementing it (which is what it replaces). The real signatures forwarded to are:
+**PASSTHROUGH, VERIFIED at both levels - with one argument touched in each, deliberately.** `init`'s callback in position 0 is wrapped since 2026-08-12: the wrapper reads the event, keeps the session it carries (§ 1), and calls the caller's callback with that same event, unchanged. Everything else - the remaining arguments, the return value, what the callback observes - passes straight through, so an application's call site is what it would write against the real SDK. This is the only place the capture can sit: it is the only one that knows both what the caller asked and what the SDK will answer, and the alternative was every consumer re-implementing it (which is what it replaces). The real signatures forwarded to are:
 
 ```ts
 // level 2 — @ng-org/web: index.d.ts:108, source sdk/js/web/src/index.ts:51
@@ -117,7 +124,9 @@ export declare type Session = {
 };
 ```
 
-Divergence: none in behaviour (pure forwarding), but the wrapper erases the parameter types. A consumer typing calls against the wrapper learns nothing it must unlearn — it just gets no compile-time help the real SDK would give.
+`initNg`'s argument in position 0 is substituted since `1.0.0-dev.7`, and it is the same kind of move for the same reason. That argument is what the ORM reaches the engine through afterwards - every subscription, every `insertObject`, every batched patch awaits the promise this call resolves - and an ORM write leaves by `ng.graph_orm_update`, which is where the emulated write guard now sits (§ 3). Handing the caller's raw SDK object over leaves that guard on a door nothing knocks on, and "pass the package's `ng` here" would be an ordering rule in prose: unenforceable, silent when missed, and in fact missed by both consumers in this repository. What is substituted is the package's own `ng` - the same object the entry publishes, forwarding every member to the very object `configure()` received - so the ORM now reaches the engine through exactly what the application does.
+
+Divergence: none in behaviour (pure forwarding), but the wrappers erase the parameter types. A consumer typing calls against them learns nothing it must unlearn - it just gets no compile-time help the real SDK would give.
 
 ---
 
@@ -163,16 +172,21 @@ export const ng: NG;
 export type { NG } from "@ng-org/web";
 ```
 
-`ng` is a `Proxy` (`ng-proxy.ts:26`) forwarding every property to the injected real `ng`, overriding exactly one thing: `sparql_update` (the emulated write-cap guard, rejecting a write when a write policy governs the anchored document and the current user lacks the cap). `session_start` is intercepted but is a pure passthrough today, with a TODO for shared-wallet credentials. (`login` was named here until 2026-08-14 but has not existed since 2026-08-03: `@ng-org/web` exposes no such method, and the proxy was FABRICATING it.)
+`ng` is a `Proxy` (`ng-proxy.ts`) forwarding every property to the injected real `ng`, overriding two things: `sparql_update` (the emulated write-cap guard, rejecting a write when a write policy governs the anchored document and the current user lacks the cap) and, since `1.0.0-dev.7`, `graph_orm_update` (the ORM's own write door, guarded by OWNERSHIP). `session_start` is intercepted but is a pure passthrough today, with a TODO for shared-wallet credentials. (`login` was named here until 2026-08-14 but has not existed since 2026-08-03: `@ng-org/web` exposes no such method, and the proxy was FABRICATING it.)
+
+There is exactly one instance of that proxy for the whole package (`wrappedNg()`), because two things now hold it: the entry publishes it, and `initNg` hands it to the ORM (§ 2).
+
+**The passthrough itself was broken until `1.0.0-dev.7`, for every one of its members, and nothing noticed.** It read `Reflect.get(ng, prop).bind(ng)`. `@ng-org/web`'s `ng` is ITSELF a Proxy - an "async proxy" whose `get` trap answers EVERY key with a fresh path-carrying callable and whose reflection traps throw (`dist/ngweb.js`, the `l(e = [])` factory) - so `.bind` never reached `Function.prototype.bind`: it was just another key, calling the result posted a remote request named after the MEMBER carrying the bind arguments, and what came back was a **Promise**. A caller therefore got the SDK's own `<member> is not a function`. Two things hid it: this library's internals never go through this proxy (they call the injected `ng` directly), and every fake in the suite is a plain object, on which `bind` behaves. It surfaced the moment `initNg` handed the ORM this object - `orm_start_graph` was not a function, the ORM catches that and only `console.error`s it, so a shape read stayed `isPending` for ever, which is the failure mode § 5 describes. MEASURED against `@ng-org/web@0.1.2-alpha.14`. The member is now FORWARDED (`Reflect.apply(real, ng, args)`), which gives a plain object the receiver it needs and lets the async proxy use the path it already carries; `test/ng-proxy.test.ts` pins it against a stand-in shaped like the real one.
 
 ### Target
 
-**PASSTHROUGH (level 2, VERIFIED).** `export declare const ng: NG` with `NG = typeof NGModule`, **88** exported members (`index.d.ts:136-231`; the namespace body is `:140-231`). The surface is identical by construction — the proxy adds no member and removes none — **and identical at the type level too since 2026-08-14**, when the published `ng` stopped being declared `Record<string, any>` and took `NG`, upstream's own type. That escape hatch silently dropped all 88 signatures: an application got no completion, and a misspelt member typechecked.
+**PASSTHROUGH (level 2, VERIFIED).** `export declare const ng: NG` with `NG = typeof NGModule`, **90** exported members in `@ng-org/web@0.1.2-alpha.14` - 84 functions and 6 RDF classes, counted in the `NGModule` namespace of the installed `index.d.ts`. The count is named with its release because it MOVES with one: this document recorded **88**, two short, and two of the ninety - `graph_orm_next_page` and `graph_orm_previous_page` - appear nowhere in the cited checkout's `sdk/js/lib-wasm/src/lib.rs`, the tree declaring the previous release `@ng-org/web@0.1.2-alpha.13`. The figure was never re-measured after the build moved. The surface is identical by construction — the proxy adds no member and removes none — **and identical at the type level too since 2026-08-14**, when the published `ng` stopped being declared `Record<string, any>` and took `NG`, upstream's own type. That escape hatch silently dropped every signature: an application got no completion, and a misspelt member typechecked.
 
 The overrides:
 
 - `session_start(wallet_name: string, user_id: any): Promise<any>` (`index.d.ts:276`) — target signature unchanged; only the emulated credential injection disappears.
-- `sparql_update(session_id: any, sparql: string, nuri: any): Promise<any>` (`index.d.ts:297`) — target signature unchanged. The native enforcement the guard stands in for is the engine's permission model (`verify_perm`, `engine/repo/src/commit.rs:897`), which today is **called only from tests** (its enclosing `Commit::verify` has no runtime caller — see `docs/nextgraph-current-state.md` § *Author-signature verification*). That absence says nothing about the target: write permissions are the engine's declared model, so the guard's *behaviour* (a refused write) is target-shaped even though its *mechanism* (a JS-side check) is emulation. Known limit, documented in `README.md`: the guard fires only on this proxy, and the lib's own writers call the injected `ng` directly, so it is best-effort until cap-enforcement.
+- `graph_orm_update(subscription_id: any, diff: any, session_id: any): Promise<void>` (`index.d.ts:104`) - target signature unchanged. **This is the door an ORM write actually uses**, and until `1.0.0-dev.7` nothing here guarded it: a mutation of a live signal object (`set.add(...)`, `set.delete(...)`, assigning a property) never passes through `sparql_update` at all, it is batched into patches and sent through this member. So the `sparql_update` guard saw no ORM add and no ORM delete - reachable from the published surface, since `useShape` forwards `add`/`delete`/`clear` to the underlying set and `useShapeQuery`'s `data` items ARE that set's objects. The guard reads the document out of each patch's `path`, whose first segment is the synthetic id `<graph>|<subject>` the ORM itself minted, and asks `assertMayWrite` - OWNERSHIP, the same predicate `docs.sparqlUpdate` asks, not the decorative write-cap list the `sparql_update` branch consults. A patch naming no NextGraph reference passes: the emulation cannot say whose document that is, and upstream does not have to guess because `verify_permission` fires on the commit itself.
+- `sparql_update(session_id: any, sparql: string, nuri: any): Promise<any>` (`index.d.ts:297`) - target signature unchanged. It is deliberately left on the decorative write-cap list rather than moved to `assertMayWrite`: this library's own REGISTERS are written through this member, and a store document is not owned in the authorship sense, so arming it here would refuse every register write (`emulated-verifier/register-write.ts`). The native enforcement the guard stands in for is the engine's permission model (`verify_perm`, `engine/repo/src/commit.rs:897`), which today is **called only from tests** (its enclosing `Commit::verify` has no runtime caller - see `docs/nextgraph-current-state.md` § *Author-signature verification*). That absence says nothing about the target: write permissions are the engine's declared model, so the guard's *behaviour* (a refused write) is target-shaped even though its *mechanism* (a JS-side check) is emulation. Known limit, documented in `README.md`: the guard fires only on this proxy, and the lib's own writers call the injected `ng` directly, so it is best-effort until cap-enforcement.
 
 ---
 
@@ -181,18 +195,20 @@ The overrides:
 ### Today — `@ng-eventually/polyfill`
 
 ```ts
-// use-shape.ts:12
-export function useShape(shapeType: unknown, scope: unknown): unknown;
+// use-shape.ts
+export function useShape<T extends BaseType>(
+  shapeType: ShapeType<T>,
+  conf: RdfOrmConfig<T> | string | undefined,
+): ShapeResult;            // { data, promise, subscription, isLoading, nextPage?, previousPage? }
 // type re-exports, index.ts:48-49
-export type { ShapeType, BaseType, Schema } from "@ng-org/shex-orm";
-export type { DeepSignalSet } from "@ng-org/alien-deepsignals";
+export type { ShapeType, BaseType } from "@ng-org/shex-orm";
 ```
 
-Behaviour: forwards to the injected real `useShape`; once any emulated cap exists (`caps.isEnforcing()`), the returned set is wrapped in a read-filtered view keeping only items whose document cap the current holder has.
+Behaviour: forwards to the injected real hook; once any emulated cap exists (`caps.isEnforcing()`), the RESULT OBJECT is wrapped in a read-filtered view. `data` and `promise` yield only items whose document cap the current holder has, `subscription` is refused (it is the ORM's own handle, which this surface does not publish), `isLoading` and the two page commands pass through, and any other member is refused unless what is behind it is a plain scalar - the rule is the value's type, so a member a later release adds is decided before anyone has seen it.
 
 ### Target
 
-**PASSTHROUGH (level 3, VERIFIED), with a signature the wrapper widens.** The real hook:
+**PASSTHROUGH (level 3, VERIFIED).** The real hook, as the CITED revision writes it:
 
 ```ts
 // level 3 — @ng-org/orm/react: sdk/js/orm/src/frontendAdapters/react/useShape.ts:86-124
@@ -201,6 +217,15 @@ const useShape = <T extends BaseType>(
     scope: Scope | string | undefined
 ) => DeepSignalSet<T>;
 
+// and as the BUILD ships it (`dist/frontendAdapters/react/useShape.d.ts`), which is the
+// shape the wrapper mirrors: the collection moved inside a result object, and the second
+// parameter widened from a bare `Scope` to the config. The gap between the two columns is
+// the one the provenance anchor records.
+const useShape = <ST extends ShapeType<T>, const CONF extends RdfOrmConfig<T>, T extends BaseType>(
+    shape: ST,
+    conf: CONF | string | undefined
+) => UseShapeResult<ST, CONF, T>;   // { data, promise, subscription, isLoading, nextPage, previousPage }
+
 // its Scope — sdk/js/orm/src/types.ts:25-38 (NOT this lib's Scope, see § 12)
 // *(Corrected 2026-08-16: this said `sdk/js/orm/src/model/types.ts`, a path that does not
 // exist in the clone. The type is at `sdk/js/orm/src/types.ts:25`. A citation nobody can
@@ -218,33 +243,41 @@ Divergence to note: the wrapper types everything `unknown`, losing the generic `
 
 ---
 
-## 5. Reactive typed reads with load state — `watchShape`
+## 5. Reactive typed reads with load state — `useShapeQuery`
 
 ### Today — `@ng-eventually/polyfill`
 
 ```ts
-// watch-shape.ts:73
-export interface ShapeQuery<T = UnionSubject> {
+// use-shape-query.ts — ShapeQuery
+export interface ShapeQuery<T extends BaseType = BaseType> {
   data: T[];
   isPending: boolean;
   isSuccess: boolean;
   isError: boolean;
   error: unknown;
 }
-// watch-shape.ts:90
-export interface ShapeObservable<T = UnionSubject> {
+// use-shape-query.ts — ShapeObservable
+export interface ShapeObservable<T extends BaseType = BaseType> {
   getSnapshot(): ShapeQuery<T>;
   subscribe(onChange: () => void): () => void;
   refetch(): void;
 }
-// watch-shape.ts:166
-export function watchShape<T = UnionSubject>(
-  shapeType: unknown,
+// use-shape-query.ts — useShapeQuery. Both parameters are the SDK's own:
+// `ShapeType` (`sdk/js/shex-orm/src/types.ts`) and `Scope` (`sdk/js/orm/src/types.ts`),
+// both re-exported by the entry. `Scope` is NOT a store scope.
+export function useShapeQuery<T extends BaseType = BaseType>(
+  shapeType: ShapeType<T>,
   scope: Scope,
 ): ShapeObservable<T>;
 ```
 
-**A scope that did not answer is `isError`, never `isSuccess` with `data: []` — since 2026-08-17.** Step 1 of the pipeline asks `listMyEntityDocs` which documents are mine in this scope. That failure used to be caught and logged, and the empty set flowed on: a barrier over zero documents is trivially reached, so the surface published `{ data: [], isPending: false, isSuccess: true }` — byte for byte the synced-but-empty snapshot, which means the one distinction this module exists for was the one it destroyed. An application rendered "you have created nothing" for "the store did not answer". `listMyEntityDocs` had stopped handing out that reading the day before (see § 12); catching it here put it straight back one floor up. It now travels the LOAD-STATE channel, which is where "this is not an answer" already lives on this surface, and which an application must already read to tell pending from empty — so the third state costs it no new vocabulary.
+**What it reads THROUGH, since `1.0.0-dev.6`: the SDK's own shape query.** `RdfOrmSubscription.getOrCreate(shapeType, scope)`, injected at `configure` as `ormSubscription` (§ 1). Four steps went with the change and they were one mechanism: resolving the logical scope to a document set (`listMyEntityDocs`), opening those documents through `ensureReposOpen` for a sync barrier, an anchored read over each, and filtering the result by the shape's `@type` IRI. All four existed because the parameter had to be TRANSLATED; once it is upstream's own `Scope`, the question goes to the thing that answers it, and `graphs` / `subjects` / `did:ng:i` are read by the engine literally. It does NOT delegate to the SDK's `useShape` - that is React's hook, callable only from a render, and its result carries two states where this one publishes three: `isLoading` has no value for a read that will never answer, and there is no error state beside it. What is taken from the SDK is the QUERY; the observable, the snapshot and the state tracking stay here, and so does the capability filter (`emulated-verifier/read-filter.ts`, applied per `@graph` on what comes back, exactly where § 4 applies it).
+
+**Consequences a caller sees.** `data` items are now the SHAPE's own objects — `@id`, `@graph` and the shape's readable predicates — where they were the property bags the then-published `readUnion` returned; `shapeType` is typed `ShapeType<T>` instead of `unknown`, so `T` follows the shape and the snapshot is typed without a cast; and the read no longer opens a document of its own, so a public-store document whose cap has not been fetched by some other read does not appear until it has been (the same limit § 4 carries, and the same `CapRegistry.onChange` recovery). *(Corrected 2026-09-21, `1.0.0-dev.9`: that last clause now holds only for `graphs: "did:ng:i"`. A document NAMED in `scope.graphs` is put through the same public-store fetch and sync barrier `docs.sparqlQuery` applies to its anchor, before the query opens - and is refused out loud rather than silently emptied when its cap cannot be obtained.)*
+
+**The name and the scope, since `1.0.0-dev.5`.** It was `watchShape(shapeType, "public" | "protected" | "private")`. `watchShape` has ZERO occurrences in `nextgraph-rs` and spends `watch`, a verb the ORM already spends on signal observation; the target's own name is `useShapeQuery`, announced by NextGraph's developers and on record in `.project/rules/nextgraph/surface-mirrors-the-sdk.md`, which is what the symbol's `announced-not-written` annotation cites. The three literals were this package's own and named the scope of a READ, which the SDK answers on two axes instead: `graphs` (one document's graph per entry, `did:ng:i` or `""` for the whole dataset, `[]` or `undefined` for no objects at all) and `subjects`. Nothing is translated any more: the `Scope` object a caller writes is the object the SDK receives.
+
+**"There is nothing" and "I could not find out" are still two different answers — and the second one moved.** Until `1.0.0-dev.6` the failure this surface had to keep apart was its own first step: `listMyEntityDocs` not answering, caught and logged, the empty set flowing on, and `{ data: [], isPending: false, isSuccess: true }` published — byte for byte the synced-but-empty snapshot, so an application rendered "you have created nothing" for "the store did not answer". That step is gone with the pipeline. What can fail now is opening the shape query, and that is what `isError` carries: a shape the ORM cannot subscribe, or a `configure()` that was never given the query. A start the ENGINE refuses does NOT reach `isError`, and that is upstream's doing rather than a choice made here — `orm_start_graph` is awaited inside a `catch` that only logs, and the readiness promise is built with `resolve` alone — so such a read stays `isPending` for ever. The distinction holds either way (an application is never told "there is nothing" for "nobody answered"), but an interface that only handles `isError` will show a spinner where it used to show an error. `isError` stays published because this package enriches the SDK in its announced direction rather than stopping at what it exposes today; the day the ORM reports a failed start, that is where it lands.
 
 **`data` survives an error rather than emptying.** A one-shot call rejects and is done; an observable has already handed a list to a subscriber that rendered it, and cannot un-emit. Collapsing `data` to `[]` on failure would put the empty answer back in the one field a view actually paints, for exactly the case that must never read as empty — so `data` keeps the last read that ANSWERED, `isSuccess` stays false so that array is never offered as a reply to the question that just failed, and the subscriber is notified so a view gating on the load state can say so. Before any answer there is nothing to keep and `data` is `[]`, published under `isError` and never under `isSuccess`.
 
@@ -259,37 +292,43 @@ get readyPromise(): Promise<void>;   // resolves when the subscription is synced
 public close(): void;
 ```
 
-So the constraint on the bet: the target can already answer "synced?" (`readyPromise`), and `useShape` today returns "an empty set, if still loading" (its own doc comment, `useShape.ts:29-31`) — indistinguishable from synced-empty. `watchShape` surfaces the distinction with a TanStack-`useQuery`-minimal vocabulary (`isPending`/`isSuccess`/`isError`), which is a **shape of this library's choosing**. If the future hook exposes load state under different names, the consumer's binding code changes; the underlying distinction it teaches (pending ≠ empty) is target-expressible and safe to learn.
+So the constraint on the bet: the target can already answer "synced?" (`readyPromise`), and `useShape` today returns "an empty set, if still loading" (its own doc comment, `useShape.ts:29-31`) — indistinguishable from synced-empty. `useShapeQuery` surfaces the distinction with a TanStack-`useQuery`-minimal vocabulary (`isPending`/`isSuccess`/`isError`). That is **not** a shape of this library's choosing any more: NextGraph's developers have stated it is the direction, and the statement is on record in `.project/rules/nextgraph/surface-mirrors-the-sdk.md` with its date — which is what the symbol's `announced-not-written` annotation cites. Deviating toward an announced target is alignment; the distinction it teaches (pending is not empty) is target-expressible either way.
 
-**But `readyPromise` answers two of those three questions, not three — VERIFIED 2026-08-17, and it bears on `isError` specifically.** It is constructed with `resolve` alone (`new Promise<void>((resolve) => { this.resolveReady = resolve; })`, `GraphOrmSubscription.ts` constructor), nothing anywhere rejects it, and `resolveReady()` is called on one path only — the arrival of initial data. The subscription that fails does not settle it: `orm_start_graph` is awaited inside a `try` whose `catch` is `console.error(e)`, so the promise stays pending forever and every `await this.readyPromise_` behind it hangs. Upstream's "I could not find out" IS its "still pending". So `isPending` and `isSuccess` map onto something real at level 3, while `isError` has **no counterpart at any level** — it is this library's third state, and the reason it exists is that swallowing a failed read into a plausible-looking result is the shape that took this project a week to close everywhere else. A consumer should keep reading it; if the future hook ships without one, the failure is the pending that never ends, which is a worse thing to have to render, not a reason to have learned less.
+**But `readyPromise` answers two of those three questions, not three — VERIFIED 2026-08-17, and it bears on `isError` specifically.** It is constructed with `resolve` alone (`new Promise<void>((resolve) => { this.resolveReady = resolve; })`, `GraphOrmSubscription.ts` constructor), nothing anywhere rejects it, and `resolveReady()` is called on one path only — the arrival of initial data. The subscription that fails does not settle it: `orm_start_graph` is awaited inside a `try` whose `catch` is `console.error(e)`, so the promise stays pending forever and every `await this.readyPromise_` behind it hangs. **Re-verified 2026-10-01 against what SHIPS**, not only against the cited checkout: in the installed `@ng-org/orm@0.1.2-alpha.21` that file is `dist/connector/RdfOrmSubscription.js`, and all three facts hold there unchanged. That is the artifact the published contract now cites, because it is the one an application runs. Upstream's "I could not find out" IS its "still pending". So `isPending` and `isSuccess` map onto something real at level 3, while `isError` has **no counterpart at any level** — it is this library's third state, and the reason it exists is that swallowing a failed read into a plausible-looking result is the shape that took this project a week to close everywhere else. A consumer should keep reading it; if the future hook ships without one, the failure is the pending that never ends, which is a worse thing to have to render, not a reason to have learned less.
 
 ---
 
-## 6. One-shot listing — the read-model
+## 6. One-shot reading by name — the anchored query, and nothing above it
 
 ### Today — `@ng-eventually/polyfill`
 
 ```ts
-// read-model.ts:60
-export interface UnionSubject {
-  subject: string;   // the subject IRI as the document carries it — any IRI, not a Nuri
-  graph: Nuri;       // the document reference the caller passed, unchanged
-  props: Record<string, string[]>;
-}
-// read-model.ts:166
-export async function readUnion(docs: Nuri[]): Promise<UnionSubject[]>;
+// docs.ts — the SDK's own primitive, and the whole of what this package offers here
+export async function sparqlQuery(
+  sessionId: string | number,
+  query: string,
+  base?: string,
+  anchorLike?: NuriLike,
+): Promise<unknown>;
 ```
 
-Behaviour: one anchored `sparql_query` per doc (default-graph body, no `GRAPH` wrapper), parallel, per-doc failure tolerance, cap filter applied inside, machinery subjects dropped.
+**`readUnion` and `UnionSubject` were published here until `1.0.0-dev.8`, and are gone.** `readUnion(docs)` issued one anchored `sparql_query` per document, in parallel, tolerated a per-document failure by swallowing it, applied the capability filter inside and dropped machinery subjects. Every one of those beyond the first is a POLICY, and none of them has a counterpart at any level: it was N calls plus a batch policy, and its annotation cited `sparql_query` — a citation that is exact attached to a claim that is false. **A composition cannot be aligned on a single function.**
 
-**Grouping is per (document, subject), and subjects come back as written.** A document holding several subjects yields several entries — one each, properties never merged across subjects; the same subject IRI seen in two documents stays two entries, told apart by `graph`. This matches level 3, where an object carries `@id` and `@graph` as two distinct read-only properties and the ORM fabricates an `@id` when the writer leaves it empty (`sdk/js/orm/src/connector/GraphOrmSubscription.ts`, `":q:"`) — several objects per graph is the provided case, and `@id` is what distinguishes them inside a `@graph`. Only `graph` is a `Nuri`; `subject` is typed `string` because an RDF subject may be any IRI. One document per business entity remains the recommended placement (a key is per repo, so isolating an entity needs a repo of its own), but that is a recommendation about writing — the read reports what is there rather than making the other arrangement invisible.
+What replaces it is what was underneath: `docs.sparqlQuery(sessionId, query, undefined, doc)`, once per document you want. Reading several is that call in a loop, and the two policies come back to the caller, where upstream leaves them:
+
+- **a failure is a failure.** The anchored query REJECTS for a document the verifier does not hold (`resolve_target_for_sparql` → `NgError::RepoNotFound`, `engine/verifier/src/request_processor.rs`), and this package refuses it earlier still for a document you hold no capability for. Whether one unreadable document ends your batch is now your decision, written at your call site rather than assumed by a primitive.
+- **shaping is yours.** The grouping into per-(document, subject) property bags was `UnionSubject`, a polyfill type with nothing upstream behind it. A SELECT's rows come back as rows; a caller that wants objects should use `getObjects` (§ 6bis) or `useShapeQuery` (§ 5), which are the SDK's own typed reads.
+- **the reserved prefix is yours to ignore.** `readUnion` dropped subjects under `urn:ng-eventually:` for you. A raw anchored read does not — see `## Guarantees` in the published contract, which now says so.
+
+**Several subjects in one document is the PROVIDED case, whichever read is used.** Level 3 carries `@id` and `@graph` as two distinct read-only properties and fabricates an `@id` when the writer leaves it empty (`sdk/js/orm/src/connector/GraphOrmSubscription.ts`, `":q:"`), so a read must report subjects as written and never fold a document into one bag. One document per business entity remains the recommended placement (a key is per repo, so isolating an entity needs a repo of its own), but that is a recommendation about writing.
 
 ### Target
 
-Two verified counterparts, one per level; neither returns `UnionSubject` — that grouping is lib-invented:
+Two verified counterparts, one per level:
 
 ```ts
-// level 2, VERIFIED — the primitive readUnion composes: index.d.ts:295, source sdk/js/lib-wasm/src/lib.rs:352 (nodejs) / :555 (web)
+// level 2, VERIFIED — the primitive, published here as `docs.sparqlQuery`: index.d.ts:295,
+// source sdk/js/lib-wasm/src/lib.rs:352 (nodejs) / :555 (web)
 declare function sparql_query(session_id: any, sparql: string, base: any, nuri: any): Promise<any>;
 
 // level 3, VERIFIED — the one-shot typed read: sdk/js/orm/src/connector/getObjects.ts:23
@@ -299,7 +338,51 @@ export async function getObjects<T extends BaseType>(
 ); // returns a deep-cloned Set of matching objects
 ```
 
-The anchored-read mechanics are level-1 VERIFIED: an anchor restricts the query to that repo's graph as default graph (`resolve_target_for_sparql`, `engine/verifier/src/request_processor.rs:256-285`), an anchorless query unions every named graph in the session store (same function, `UserSite → None` → `set_default_graph_as_union`). At migration `readUnion` survives as composition (the anchored per-doc read is native); a consumer that wants typed results should be on `useShape`/`getObjects`, not on `UnionSubject` — the property-bag shape is a polyfill artifact, kept generic precisely so the consumer maps it into its own types and can drop it later.
+The anchored-read mechanics are level-1 VERIFIED: an anchor restricts the query to that repo's graph as default graph (`resolve_target_for_sparql`, `engine/verifier/src/request_processor.rs:256-285`), an anchorless query unions every named graph in the session store (same function, `UserSite → None` → `set_default_graph_as_union`). Reading several documents must therefore stay N ANCHORED queries: replacing them with one anchorless query is a silent widening of what a read can reach, and on a shared wallet it is O(wallet size).
+
+---
+
+## 6bis. The ORM's one-shot read and subscription-free write - `getObjects` / `insertObject`
+
+### Today — `@ng-eventually/polyfill`
+
+```ts
+// orm.ts - the SDK's own read, with the capability filter on what comes back
+export async function getObjects<T extends BaseType>(
+  shapeType: ShapeType<T>,
+  config: Omit<RdfOrmConfig<T>, "pageSize" | "maxActivePages">,
+): Promise<T[] | Set<T>>;
+// orm.ts - the SDK's own write, with the ownership guard before it
+export async function insertObject<T extends BaseType>(shapeType: ShapeType<T>, object: T): Promise<T>;
+```
+
+**PASSTHROUGH (level 3, VERIFIED)** - both at upstream's own name, parameters and return, forwarding to the real functions injected at `configure()` (`getObjects`, `insertObject`; § 1). Published since `1.0.0-dev.7`; before that an application had to import them straight from `@ng-org/orm`, which is the problem rather than an inconvenience - an unwrapped ORM read returns EVERY identity's data out of the shared wallet with nothing signalling it, and an unwrapped ORM write reaches any document at all.
+
+**What each wrapper adds, and where the target does the same thing.** A READ is filtered on what comes back: `emulated-verifier/read-filter.ts` keeps only items whose document - their `@graph` - the current holder holds a cap for, applied per document, exactly where § 4 and § 5 apply it. The filter keeps the collection's shape, so a `Set` in is a `Set` out and an `orderBy`ed array stays an array; before the first cap is issued the emulation is not in force and everything passes through. A WRITE is NOT filtered, and the asymmetry is upstream's: a write is bounded by write capability (`verify_permission`, reachable only from `Commit::verify`, so it fires on commits and never on reads) and nothing is hidden from the writer. So `insertObject` takes the same pair of guards `docs.sparqlUpdate` takes - `assertMayReach` then `assertMayWrite` - BEFORE the call, on the `@graph` the object carries. An object naming no document is forwarded untouched and the ORM's own refusal is heard (it throws without a `@graph`, because upstream the insert subscribes to no document and has no other way to know where the write lands).
+
+**What comes back from `getObjects` is DETACHED** - `structuredClone` of the raw signal object - so mutating an item of it reaches nothing, and deleting an item of it removes nothing and reports nothing. Removal is a mutation of the LIVE set a subscription holds (§ 4), which leaves through `graph_orm_update` and is guarded there (§ 3).
+
+**What is deliberately NOT published from this family**, each for a reason a reader can check:
+
+- **`RdfOrmSubscription`** - an application never holds a subscription: it hands the shape query to `configure` and reads `useShapeQuery`'s snapshot back (§ 5, § 14). And `getOrCreate` POOLS on a key built from the shape and the scope alone - no identity in it - so a second virtual user asking the same question is handed the FIRST one's live instance. What makes that safe here is the filter this package applies on the way out; publishing the handle would hand out the instance instead.
+- **`DiscreteOrmSubscription`** - a JSON-CRDT document. Its items carry no `@graph`, so the read filter has nothing to read, and its writes leave through `discrete_orm_update`, a third channel nothing here guards. Publishing it would open a surface and a hole in the same gesture.
+- **`ngSession`** - a module-level PROMISE resolving to the SDK handle plus the SESSION. One physical session hosts every virtual identity here, so handing it out hands every identity the same one (§ 1, § 13). Wrapping a resolved value would also force a RUNTIME `@ng-org/orm` import into this package, which is what the injection discipline exists to avoid.
+- **`getRaw`** - it returns the object BEHIND a signal, the same escape hatch the read filter refuses on a dunder key (`__raw__`): the unfiltered collection, every identity's items in it. There is no filtered form of it.
+- **`watch` / `effect`** - `@ng-org/alien-deepsignals`' reactivity primitives, re-exported by the ORM's entry. They carry no document and grant nothing, so there is nothing to wrap.
+- **`removeObject`** - **NOT YET RULED ON, and it is the one gap in this section.** It exists in the published `@ng-org/orm@0.1.2-alpha.21` (`removeObject(graphNuri, subjectIri)`, a `DELETE WHERE` on that subject, stated to have the same effect as `delete()` on a subscription object) and it does NOT exist at the `nextgraph-rs` revision this repository reads (`213338f`): no file, no symbol. So nothing in the source can be cited for it, and the project's own rule refuses a claim inferred from what an npm package happens to expose. It is left unpublished until the source carries it; an application removes an object by mutating the live set, which is the path § 4 publishes and § 3 guards.
+
+### Target
+
+```ts
+// level 3, VERIFIED - sdk/js/orm/src/connector/getObjects.ts:getObjects
+export async function getObjects<T extends BaseType>(shapeType: ShapeType<T>, scope: Scope | string);
+// level 3, VERIFIED - sdk/js/orm/src/connector/insertObject.ts:insertObject
+export async function insertObject<T extends BaseType>(shapeType: ShapeType<T>, object: T);
+```
+
+**One difference between the cited revision and the published package, and the published one is what is mirrored here.** `getObjects`'s second parameter was `Scope | string` at `213338f`; `@ng-org/orm@0.1.2-alpha.21` widened it to the config `RdfOrmConfig` declares, minus the two pagination fields a one-shot read has no use for - a `Scope` plus `where` and `orderBy`. The wrapper takes the wider one, because that is what a consumer's TypeScript actually checks against and because narrowing it back to `Scope` would reject a `where` the SDK accepts. Both return types are inferred upstream rather than annotated; the published declaration says `Promise<T[] | Set<T>>` for the first and `Promise<T>` for the second.
+
+At migration both wrappers disappear and the imports resolve to these two functions: same names, same arguments, same returns. What goes with them is the filtering and the guard, which the broker and the verifier then do.
 
 ---
 
@@ -554,13 +637,16 @@ The escaping helpers were published until the surface was narrowed. Their remova
 
 ## 12. Scope resolution, per-entity documents, and the store registry
 
-### Today — `@ng-eventually/polyfill` (namespace `storeRegistry`) — plus `Scope` from `types.ts`
+### Today — `@ng-eventually/polyfill` (namespace `storeRegistry`)
 
 > **Narrowed twice.** 2026-08-03 the entry stopped re-exporting the whole `store-registry` module and kept an app-facing slice (`src/surface/placement.ts`). 2026-08-05 that slice lost its two inbox-ADDRESS functions as well: an application deposits with `inbox.postToDocument(doc, …)` and shares with `inbox.share(doc, toUser)` — always naming a document or a person, never an address, because upstream an address is resolved from a profile and never handled by a caller. **Five functions remain published**, listed first below; everything after them is kept for the record and is covered by `docs/internal-contract.md`.
 
 ```ts
-// types.ts:38 — NB: NOT the ORM's Scope (a graphs/subjects filter); this is the store scope
-export type Scope = "public" | "protected" | "private";
+// `Scope` (this package's, `"public" | "protected" | "private"`) was published here until
+// `1.0.0-dev.5`. It is now `StoreType`, DEFINED in `types.ts` and published nowhere: an
+// application names a store by the reference one of the three accessors below hands it.
+// The three strings are upstream's own (`doc_create`'s `store_type`), but the name `Scope`
+// was covering two questions at once — see § 5 for the other one.
 
 // store-registry.ts:90,234
 // VirtualUserRecord is INTERNAL (shape kept here for the ruling below).
@@ -584,14 +670,28 @@ interface RegistrySession {
 // identity to every placement call was a gesture with no successor — and it forced an
 // application to KNOW its identity, which it could only do by reading the access gate's
 // private storage key. `ensureIdentity()` returns it now; these take it from the session.
-export async function createEntityDoc(scope: Scope): Promise<Nuri>;
-export async function listMyEntityDocs(scope: Scope): Promise<Nuri[]>;
-export async function resolveScopeGraph(scope: Scope): Promise<Nuri>;
-export async function resolveWriteGraph(scope: Scope): Promise<Nuri>;
+// A store is named by its REFERENCE, since `1.0.0-dev.5`. Upstream the session hands the
+// application its three store ids (`Session.private_store_id | protected_store_id |
+// public_store_id`) and `doc_create` takes one of them, the private store when none is
+// given — so these three accessors answer what the session answers, and `createEntityDoc`
+// takes one of them exactly where `doc_create` takes its store.
+export async function privateStore(): Promise<Nuri>;
+export async function protectedStore(): Promise<Nuri>;
+export async function publicStore(): Promise<Nuri>;
+export async function createEntityDoc(store?: NuriLike): Promise<Nuri>;
 export async function openDocumentInbox(doc: NuriLike): Promise<Nuri>;
 
+// UNPUBLISHED in `1.0.0-dev.5`, each for its own reason:
+//   listMyEntityDocs  — no counterpart at any level (no `doc_list`, nothing in the
+//                       binding). Listing what one created is an ordinary query over the
+//                       store's `ldp:contains`. Still internal: the read path calls it.
+//   resolveScopeGraph — it handed out a value whose stated use was a READ scope, and a
+//                       store's graph holds containment triples and nothing else, so
+//                       upstream that query matches nothing and says so with an empty set.
+//   resolveWriteGraph — it returned the very reference the three accessors return.
+
 // NOT published — internal, kept here because the target rulings below still cover them.
-//   userStoreDoc, userInbox, documentInboxAddress, isOwnInbox, myInboxes,
+//   userInbox, documentInboxAddress, isOwnInbox, myInboxes,
 //   addLink, readLinks, resolveAccount, ensureAccount, reservedAccount,
 //   resetRegistryCache, and the VirtualUserRecord type.
 // `RegistrySession` joined them on 2026-08-12: it was published for ONE reason — a consumer
@@ -609,7 +709,7 @@ export async function openDocumentInbox(doc: NuriLike): Promise<Nuri>;
 
 - **`createEntityDoc(id, scope)` → level 2, VERIFIED direction.** Target: `doc_create(session_id, crdt, class_name, destination, store_repo)` aimed at the identity's real per-scope store (see § 7 for the store-targeting nuance — the nodejs SDK already takes `store_type`/`store_repo` strings). The two writes the lib performs by hand are **native side effects** of `doc_create` upstream: the `ldp:contains` listing on the store's Main branch and the `AddRepo { read_cap }` on its Store branch (`engine/verifier/src/request_processor.rs:697-710`). The `id` parameter is already gone from the published call (2026-08-10); expect `createEntityDoc(scope)` to become `doc_create(sid, …, storeOf(scope))` with no listing/cap bookkeeping.
 - **`listMyEntityDocs(id, scope)` → level 1/2, VERIFIED mechanism.** Upstream the listing is the store's `ldp:contains` graph (written at `request_processor.rs:706-708`), readable with an anchored `sparql_query` on the store; the caps come back by replaying the Store branch (`AddRepo::verify` → `load_repo_from_read_cap`). The function's shape (give me my per-scope doc NURIs) survives; its implementation becomes one native read.
-- **`userStoreDoc(id, scope)` / `resolveScopeGraph(scope)` / `resolveWriteGraph(id, scope)` → level 2, VERIFIED.** The target answers these from the session: `did:ng:` + `session.private_store_id | protected_store_id | public_store_id` (`Session`, `sdk/js/web/src/index.ts:Session`, installed `index.d.ts:265-273`). The store IS the container; the per-scope index document disappears.
+- **`resolveScopeGraph(scope)` / `resolveWriteGraph(id, scope)` → level 2, VERIFIED.** (`userStoreDoc` stood beside them and was REMOVED in `1.0.0-dev.6`: it handed out the scope-index document so a reactive reader could follow it, and `useShapeQuery` reading through the SDK's shape query left it with no caller.) The target answers these from the session: `did:ng:` + `session.private_store_id | protected_store_id | public_store_id` (`Session`, `sdk/js/web/src/index.ts:Session`, installed `index.d.ts:265-273`). The store IS the container; the per-scope index document disappears.
 - **`userInbox(id)` → level 1, VERIFIED counterpart with a different granularity.** Upstream a user's inboxes are their public and protected STORE repos' inboxes — the only two `AddInboxCap` commits in the engine (`engine/verifier/src/site.rs:128,149`). An identity-level "my inbox" therefore maps to a store inbox; the resolution moves into the lib/SDK and the consumer's act (deposit to an address, process my own) is unchanged.
 - **`openDocumentInbox(doc)` / `documentInboxAddress(doc)` → level 1, VERIFIED support, no exerciser.** Every `Repo` carries `inbox: Option<PrivKey>` (`engine/repo/src/repo.rs:126`); `AddInboxCapV0` is keyed by `repo_id` with no is-store restriction (`engine/repo/src/types.rs:1973`; applied at `engine/verifier/src/verifier.rs:1920-1928`); but no code path creates one for a plain document (`doc_create` → `new_repo_default` → `Store::create_repo_default` → `create_repo_with_keys`, which builds the `Repo` with `inbox: None` — `engine/verifier/src/verifier.rs:3004`, `engine/repo/src/store.rs:264,284,691`) and no level-2/3 API exposes any of it. So: the *capability* is engine-verified; the *functions* are invented surface; and the **address publication is a real, deliberate divergence** (upstream transmits addresses, never publishes them — § 9), with the ownership guard compensating our design, not mirroring an upstream rule.
 - **`addLink(cap)` / `readLinks()` → annotated `declared-not-wired` (level 1).** The emulated `AddLink { read_cap }` register (`engine/repo/src/types.rs:AddLinkV0` — *"so that a user can share with all its device a new Link they received"*, external repos only). **Verified 2026-08-16, and this is the load-bearing fact:** the type is DEFINED, its `CommitVerifier::verify` is a no-op `Ok(())` (`engine/verifier/src/commits/mod.rs`), and **nothing in the engine constructs one** — the only other occurrences are the `CommitBodyV0::AddLink` enum variant and two match arms classifying body kinds. Its sibling `AddRepoV0` *is* constructed (`Verifier::send_add_repo_to_store`), which is why the Store-branch register next door is annotated `aligned` and this one is not. A maintainer read that absence and concluded the function was this library's own invention; it is not — an absent implementation says nothing about the target. Upstream this filing happens inside the verifier when it processes the inbox; the future SDK most likely never exposes these as calls, so consumers should not code against them (§ 15).
@@ -661,12 +761,19 @@ declare function user_disconnect(user_id: string): Promise<void>;
 `@ng-eventually/polyfill` re-exports, type-only (erased at build, `src/index.ts`):
 
 ```ts
-export type { ShapeType, BaseType, Schema } from "@ng-org/shex-orm";
-export type { DeepSignalSet } from "@ng-org/alien-deepsignals";
+export type { ShapeType, BaseType } from "@ng-org/shex-orm";
+export type { Scope } from "@ng-org/orm";
+export type { RdfOrmConfig } from "@ng-org/orm/all";
 export type { NG } from "@ng-org/web";
 ```
 
-**PASSTHROUGH (levels 2/3, VERIFIED)** — `ShapeType`/`BaseType` at `@ng-org/shex-orm` `dist/types.d.ts:5,12` (installed 0.1.2-alpha.8); `NG` at `index.d.ts:136`. At migration these imports point at the same packages directly; nothing changes for the consumer.
+**PASSTHROUGH (levels 2/3, VERIFIED)** - `ShapeType`/`BaseType` at `@ng-org/shex-orm` `dist/types.d.ts:5,12`; `NG` at `index.d.ts:136`. At migration these imports point at the same packages directly; nothing changes for the consumer.
+
+A type is erased at build, so re-exporting one adds no runtime `@ng-org` import and opens no path around the emulation - which is why the rule that nothing of the SDK is published as it stands is about VALUES, and these are the exception it does not reach.
+
+`RdfOrmConfig` comes from the SDK's `/all` subpath rather than its main entry, and that is upstream's packaging rather than a choice here: the config type `getObjects` declares is not exported beside the function that takes it (§ 6bis). Restating it locally is how a type drifts, so it is re-exported from where the SDK puts it.
+
+**`Schema` (`@ng-org/shex-orm`) and `DeepSignalSet` (`@ng-org/alien-deepsignals`) were re-exported here until `1.0.0-dev.12` (2026-09-24), and are UNPUBLISHED now, for the same rule this section states: a type is published only when a published signature uses it. Neither was. `DeepSignalSet` is named only in prose describing what `useShape`'s result envelope carries (§ 4) - never as an actual type anywhere in this package - and `Schema` was named nowhere at all beyond this re-export. This is a MAJOR (a published symbol removed); see the concept contract's `## Change policy` (`.project/concepts/app-contract/polyfill-surface/contract_polyfill-surface.md`) and the appendix below.**
 
 ### The library's own model types — published by NAME since 2026-08-10
 
@@ -675,10 +782,19 @@ The entry used to say `export * from "./model/types"`, a blanket re-export publi
 > **A type is published only if a PUBLISHED SIGNATURE uses it.**
 
 ```ts
-export type { Nuri, NuriLike, Scope, PrincipalId, NgLike, UseShapeLike } from "./model/types";
+export type { Nuri, NuriLike, PrincipalId } from "./model/types";
+// ... elsewhere in the entry, in the POLYFILL-ERA block beside EventuallyConfig
+// (moved there in 1.0.0-dev.13 - see below):
+export type {
+  NgLike, UseShapeLike, OrmSubscriptionLike, GetObjectsLike, InsertObjectLike,
+} from "./model/types";
 ```
 
-Each one's warrant: `Nuri` is what every reference-returning call returns and `NuriLike` what every entry accepts (§ 10, § 11); `Scope` types `storeRegistry.*` and `watchShape` (§ 12, § 5); `PrincipalId` is `ensureIdentity`'s return and a field of `Deposit`, `PostOptions` and `EventuallyConfig` (§ 2bis, § 9, § 1); `NgLike` and `UseShapeLike` type the two injected objects in `EventuallyConfig` (§ 1).
+Each one's warrant: `Nuri` is what every reference-returning call returns and `NuriLike` what every entry accepts (§ 10, § 11); `Scope` left this list in `1.0.0-dev.5` - the read takes the SDK's own `Scope`, re-exported from `@ng-org/orm`, and a store is named by its reference (§ 5, § 12); `PrincipalId` is `ensureIdentity`'s return and a field of `Deposit`, `PostOptions` and `EventuallyConfig` (§ 2bis, § 9, § 1); `NgLike`, `UseShapeLike`, `OrmSubscriptionLike`, `GetObjectsLike` and `InsertObjectLike` type the five injected members of `EventuallyConfig` (§ 1), the last two since `1.0.0-dev.7` (§ 6bis). `OrmSubscriptionHandle` - what the last of them RETURNS - is deliberately not published: an application hands the shape query in and reads the snapshot back, and publishing the handle would offer a path around the capability filter and the shared-wallet identity boundary.
+
+**These five moved out of this list in `1.0.0-dev.13` (2026-09-28), into the entry's POLYFILL-ERA block beside `EventuallyConfig` - a PATCH, not a removal: same five names, same five shapes, still exported from this one entry.** Each was already annotated `kind=invention level=none ref=none` (honestly - none has a target counterpart at any level), which had always sat oddly under the entry's SDK-SHAPED heading ("a target counterpart for every symbol"). All five exist only to describe what `configure` receives, and `configure` / `EventuallyConfig` were already on the deletion list (§ 1: "NO COUNTERPART, by design... `configure` / `configureStoreRegistry` are deleted"). The move corrects which list tells a consumer their fate at migration; it changes nothing under `## Surface` or `## Guarantees` in the concept contract, so it is a patch by that leaf's own `## Change policy`.
+
+**`ShapeObservable` moved the same way in `1.0.0-dev.14` (2026-10-01) - a PATCH again: same name, same shape, still exported.** It is annotated `kind=invention level=none ref=none` (no upstream observable exists; the record behind `ShapeQuery` describes a snapshot shape, not an observable), so it sat wrongly under the SDK-SHAPED heading. `ShapeQuery` stays there: its record exists and states `{ data, isPending, isSuccess, isError, error }` field for field. The type stays exported because applications write it down (`examples/notebook/app.ts`, `e2e/polyfill-entry.ts`). It is not a framework adapter: it carries the capability filter (`getSnapshot()` returns a filtered view) and the capability-arrival re-publish (a `getCaps().onChange` subscription owned by the observable's own lifecycle). A capability arrives mid-session only because the wallet is shared; in the target an identity holds its own wallet and capabilities from the start, so there is nothing to filter and no arrival to re-publish on. It therefore dies exactly when the shared wallet dies - a COUPLED migration, not an independent symbol removal - and a TanStack-shaped hook returning a snapshot has nowhere to hang such a subscription, because the target does not need one. `refetch()` lives on it and is the only published way out of a read stuck pending; the recorded announcement lists five fields and `refetch` is not among them, so it goes with NO RECORDED COUNTERPART. That is a statement about the record, not about TanStack Query (whose `useQuery` does return a `refetch`) nor about NextGraph's intentions.
 
 Two types the blanket export published are now internal, each because **nothing published names it**:
 
@@ -705,12 +821,12 @@ Exported, but not SDK surface. Coding against these builds knowledge that migrat
 
 ### Places the current surface teaches something to unlearn
 
-- ~~**The SDK entry is not as pure as its header claims.**~~ **FIXED 2026-08-03.** The header claimed the entry "exposes ONLY what `@ng-org/web` / `@ng-org/orm` expose" while also shipping `virtualUsers` and the whole `store-registry` module. Both are gone from it, and the header now states what the entry actually promises: *every symbol here has a target-SDK counterpart, verified or assumed, listed in this document*. It still exports `docs`, `readUnion`, `watchShape`, `subscribeDoc(s)`, the SPARQL helpers and the NURI guards — justified inventions, documented per subject above — so the promise is no longer "@ng-org surface only", which was never true, but "nothing here is machinery".
+- ~~**The SDK entry is not as pure as its header claims.**~~ **FIXED 2026-08-03.** The header claimed the entry "exposes ONLY what `@ng-org/web` / `@ng-org/orm` expose" while also shipping `virtualUsers` and the whole `store-registry` module. Both are gone from it, and the header now states what the entry actually promises: *every symbol here has a target-SDK counterpart, verified or assumed, listed in this document*. It still exports `docs`, `useShapeQuery`, `subscribeDoc(s)`, the SPARQL helpers and the NURI guards — justified inventions, documented per subject above — so the promise is no longer "@ng-org surface only", which was never true, but "nothing here is machinery".
 - ~~**`share` is importable from both entries.**~~ **FIXED 2026-08-07** with the entry merge: there is one entry and one `share`, under `inbox`.
 - **One entry means the import line no longer says what disappears.** Until 2026-08-07 a second import path (`/polyfill`) WAS the deletion list. It is now the `POLYFILL-ERA` block in `src/index.ts`, this appendix's note above, and the per-subject rulings in this document. That is a documentation-carried signal where it used to be a mechanical one — the appendix is pinned by a test, the grouping is not.
 - **`inbox.read` as a mailbox** — enumerating raw deposits is emulation detail (§ 9); the durable contract is deposit-and-it-gets-applied. An app building UI on the deposit list should expect that surface to change shape entirely.
-- **`watchShape`'s "planned `useShape` upgrade"** — stated in the module header with no provenance in this repo or the clone (§ 5). The load-state *distinction* is safe; the claim that NextGraph plans this exact hook shape is an assumption and must not be cited as an announced API.
-- **`UnionSubject` property bags** — polyfill read-model shape, not a target type; map them into app types at the boundary (which `watchShape`'s design already assumes).
+- ~~**`watchShape`'s "planned `useShape` upgrade"**~~ **ANSWERED in `1.0.0-dev.5`.** The claim was in the module header with no provenance anywhere. It has one now, and it is the strongest kind available to something the target has not written: NextGraph's developers stated the direction, the statement is written down in `.project/rules/nextgraph/surface-mirrors-the-sdk.md` with who said it and when, and the symbol carries `kind=announced-not-written` citing that record. The name went with it — `useShapeQuery`, not `watchShape` (§ 5).
+- ~~**`UnionSubject` property bags**~~ — REMOVED in `1.0.0-dev.8`, with `readUnion`. Nothing of the read model is published any more: an application reads one document with `docs.sparqlQuery` and shapes the rows itself, or reads by shape and gets the SDK's own objects.
 - **The sync-returning `subscribeDoc` unsubscribe** vs the target's promise-resolved one (§ 8) — a deliberate, documented ergonomic delta; an adapter is one line at migration, but it is a delta.
 
 ---
@@ -722,10 +838,10 @@ Exported, but not SDK surface. Coding against these builds knowledge that migrat
 ### `@ng-eventually/polyfill` — `src/index.ts` (the only entry since 2026-08-07)
 
 ```text
-direct: BaseType, DeepSignalSet, DocChange, DocChangeType, EventuallyConfig, NG, NgLike, Nuri, NuriLike, PrincipalId, Schema, Scope, ShapeObservable, ShapeQuery, ShapeType, SharedWalletConfig, UnionSubject, Unsubscribe, UseShapeLike, configure, docChangeType, ensureIdentity, init, initNg, ng, readUnion, subscribeDoc, subscribeDocs, useShape, watchShape
+direct: BaseType, DocChange, DocChangeType, EventuallyConfig, GetObjectsLike, InsertObjectLike, NG, NgLike, Nuri, NuriLike, OrmSubscriptionLike, PrincipalId, RdfOrmConfig, Scope, ShapeObservable, ShapeQuery, ShapeType, SharedWalletConfig, Unsubscribe, UseShapeLike, configure, docChangeType, ensureIdentity, getObjects, init, initNg, insertObject, ng, subscribeDoc, subscribeDocs, useShape, useShapeQuery
 docs: docCreate, sparqlQuery, sparqlUpdate
 inbox: Deposit, PostOptions, post, postToDocument, processInbox, read, readForDocument, readSynced, readSyncedForDocument, share, watch
-storeRegistry: createEntityDoc, listMyEntityDocs, openDocumentInbox, resolveScopeGraph, resolveWriteGraph
+storeRegistry: createEntityDoc, openDocumentInbox, privateStore, protectedStore, publicStore
 ```
 
 **Of these, exactly ONE is polyfill-era with no target counterpart** — `configure` (plus

docs/internal-contract.md

@@ -1,10 +1,10 @@
 # Internal contract — what `@ng-eventually/polyfill` keeps off its surface, and what NextGraph does or would do about each subject
 
-> **Updated 2026-08-03, after the source layout was reorganised by migration fate** (`docs/source-layout-by-fate.md`). Paths, and three names, changed under this document: `readModel` became the directly-exported `readUnion`; `accounts` / `AccountRecord` / `AccountStorage` became `virtualUsers` / `VirtualUserRecord` / `VirtualUserStorage` (module `shared-wallet/virtual-users.ts`); `store-registry-api.ts` became `surface/placement.ts`. Two modules were created and are covered here: `emulated-verifier/branch-registers.ts` (the four durable registers, split out of the shim) and `shared-wallet/bootstrap.ts` (the injection store, split out of the `/polyfill` entry). The subject-by-subject rulings below are unaffected — what moved is where the code lives, not what it promises.
+> **Updated 2026-08-03, after the source layout was reorganised by migration fate** (`docs/source-layout-by-fate.md`). Paths, and three names, changed under this document: `readModel` became the directly-exported `readUnion` (itself removed in `1.0.0-dev.8`); `accounts` / `AccountRecord` / `AccountStorage` became `virtualUsers` / `VirtualUserRecord` / `VirtualUserStorage` (module `shared-wallet/virtual-users.ts`); `store-registry-api.ts` became `surface/placement.ts`. Two modules were created and are covered here: `emulated-verifier/branch-registers.ts` (the four durable registers, split out of the shim) and `shared-wallet/bootstrap.ts` (the injection store, split out of the `/polyfill` entry). The subject-by-subject rulings below are unaffected — what moved is where the code lives, not what it promises.
 
 **Scope.** The complement of [`docs/api-contract.md`](./api-contract.md): every module export under `packages/polyfill/src/` that is NOT reachable from the published entry point (`package.json` maps exactly `.` → `src/index.ts`). A consumer never reads this document; a maintainer does. The internal code is held to the same standard as the surface — as close as possible to what NextGraph does or plans — so every subject below carries the same target-side analysis. Written 2026-08-04, verified against the `nextgraph-rs` clone (HEAD `213338f6`) and the installed `@ng-org/web@0.1.2-alpha.13` declarations (`node_modules/.bun/@ng-org+web@0.1.2-alpha.13/node_modules/@ng-org/web/dist/index.d.ts`, hereafter `index.d.ts`).
 
-**How the boundary was computed — mechanically, from the `export` statements.** `index.ts` re-exports wholesale (`export *` / `export * as ns`) from `types.ts`, `inbox.ts`, `docs.ts`, `surface/read-model.ts`, and by name everything `surface/use-shape.ts`, `surface/watch-shape.ts`, `lifecycle.ts`, `sparql.ts` export, and `subscribeDoc`/`subscribeDocs`/`docChangeType` (+ types) from `subscribe.ts`; its `storeRegistry` namespace is the **`surface/placement.ts` slice only** (`createEntityDoc`, `listMyEntityDocs`, `resolveScopeGraph`, `resolveWriteGraph`, `openDocumentInbox`). `model/nuri.ts` is now internal in full — the guards `isNuri`/`hasReadCap` stopped being published when the entries became permissive-in (`NuriLike` validated at the door). *(The second entry, `polyfill.ts`, was merged into `index.ts` on 2026-08-07, and the polyfill-era block was then cut to ONE published call, `configure`. `configureStoreRegistry`, `setCurrentUser` and `connectedUser` became internal the same day — folded, replaced by the gate, and awaited inside it respectively; the machinery accessors and test resets are internal too. All four are inventoried below.)* Everything else that carries `export` in a `src/` module is internal and inventoried here. Eight modules are internal in their entirety: `shared-wallet/access-log.ts`, `emulated-verifier/machinery.ts`, `surface/ng-proxy.ts`, `emulated-verifier/open-repo.ts`, `shared-wallet/outbox-log.ts`, `shared-wallet/physical.ts`, `emulated-verifier/reach.ts`, `emulated-verifier/read-filter.ts`. Four are internal in part: `nuri.ts`, `emulated-verifier/connect.ts`, `subscribe.ts`, `shared-wallet/account-registry.ts`.
+**How the boundary was computed — mechanically, from the `export` statements.** `index.ts` re-exports wholesale (`export *` / `export * as ns`) from `types.ts`, `inbox.ts`, `docs.ts`, `surface/read-model.ts` (removed in `1.0.0-dev.8`, see below), and by name everything `surface/use-shape.ts`, `surface/watch-shape.ts`, `lifecycle.ts`, `sparql.ts` export, and `subscribeDoc`/`subscribeDocs`/`docChangeType` (+ types) from `subscribe.ts`; its `storeRegistry` namespace is the **`surface/placement.ts` slice only** (`createEntityDoc`, `listMyEntityDocs`, `resolveScopeGraph`, `resolveWriteGraph`, `openDocumentInbox`). `model/nuri.ts` is now internal in full — the guards `isNuri`/`hasReadCap` stopped being published when the entries became permissive-in (`NuriLike` validated at the door). *(The second entry, `polyfill.ts`, was merged into `index.ts` on 2026-08-07, and the polyfill-era block was then cut to ONE published call, `configure`. `configureStoreRegistry`, `setCurrentUser` and `connectedUser` became internal the same day — folded, replaced by the gate, and awaited inside it respectively; the machinery accessors and test resets are internal too. All four are inventoried below.)* Everything else that carries `export` in a `src/` module is internal and inventoried here. Nine modules are internal in their entirety: `shared-wallet/access-log.ts`, `emulated-verifier/machinery.ts`, `surface/ng-proxy.ts`, `emulated-verifier/open-repo.ts`, `shared-wallet/outbox-log.ts`, `shared-wallet/physical.ts`, `emulated-verifier/reach.ts`, `emulated-verifier/read-filter.ts`, and — since `1.0.0-dev.8`, when `readUnion` and `UnionSubject` left the entry — `surface/read-document.ts` (the former `surface/read-model.ts`). Four are internal in part: `nuri.ts`, `emulated-verifier/connect.ts`, `subscribe.ts`, `shared-wallet/account-registry.ts`.
 
 **Labels** are those of `docs/api-contract.md`: **PASSTHROUGH (level 3/2, VERIFIED)**, **LEVEL-1 SHAPE (model VERIFIED, JS surface ASSUMED)**, **ASSUMPTION**, **NO COUNTERPART**. Level numbers per `README.md` § *The three references*: 3 = JS ORM, 2 = wasm binding (`@ng-org/web`), 1 = Rust engine. One label recurs here that the surface contract rarely needs: **NO COUNTERPART, shared-wallet machinery** — the code below the emulation's floor, which the target has no image of because the target has no shared wallet. Per the design principle, an absent implementation is never treated as evidence about the future.
 
@@ -13,15 +13,17 @@
 ## 1. The wrapped `ng` factory — `surface/ng-proxy.ts`
 
 ```ts
-// ng-proxy.ts:10
-export function makeNg(): Record<string, any>;
+export function makeNg(): NG;
+export function wrappedNg(): NG;   // the memoised one - THE instance, since 1.0.0-dev.7
 ```
 
-Builds the published `ng` Proxy (consumed once, `index.ts:61`): forwards every property to the injected real `ng`, overriding `login`/`session_start` (passthrough with a shared-wallet-credentials TODO) and `sparql_update` (the emulated write-cap guard).
+Builds the `ng` Proxy: forwards every property to the injected real `ng`, overriding `session_start` (passthrough with a shared-wallet-credentials TODO), `sparql_update` (the emulated write-cap guard) and, since `1.0.0-dev.7`, `graph_orm_update` (the ORM's own write door - ownership, `assertMayWrite`).
 
 - The factory itself is **NO COUNTERPART, by design** — the target has no "wrap the SDK" step; at migration `ng` IS `@ng-org/web`'s and `makeNg` is deleted.
-- The `sparql_update` guard stands in for the engine's write-permission model (`verify_perm` inside `Commit::verify`, `engine/repo/src/commit.rs:892-899`) — same analysis as `docs/api-contract.md` § 3.
-- **Defect — the `login` arm fabricates a member (see Findings F1).** `@ng-org/web` has no `login`: none among the exports of `index.d.ts` (re-verified), and no `fn login` in `sdk/js/lib-wasm/src/lib.rs`. The proxy nevertheless returns a function for `prop === "login"` (`ng-proxy.ts:16-22`), so `typeof ng.login === "function"` on the wrapper while the real SDK yields `undefined` — the one place the proxy adds a member, contradicting its own header and the surface contract's "adds no member and removes none" (§ 3). Calling it throws at runtime (`ng[prop]` is undefined). **ASSUMPTION with no provenance** — no target layer names a `login`.
+- `wrappedNg()` exists because the proxy now has **two** holders: `index.ts` publishes it, and `surface/lifecycle.ts` hands it to the ORM through `initNg`, so the two must be the same object. It keeps no state (every property is answered from `getConfig()` at access time), so it survives a re-`configure()` and needs no reset.
+- The `sparql_update` guard stands in for the engine's write-permission model (`verify_perm` inside `Commit::verify`, `engine/repo/src/commit.rs:892-899`) - same analysis as `docs/api-contract.md` § 3. It is deliberately left on the decorative write-cap list rather than on `assertMayWrite`: the library's own REGISTERS are written through this member (`emulated-verifier/register-write.ts`), and a store document is not owned in the authorship sense, so arming it there would refuse every register write. `graph_orm_update` has no such traffic, which is why the live predicate sits on it.
+- ~~**Defect - the `login` arm fabricates a member (Findings F1).**~~ **FIXED 2026-08-03**, and this bullet had outlived it: `@ng-org/web` has no `login` - none among the exports of `index.d.ts`, no `fn login` in `sdk/js/lib-wasm/src/lib.rs` - and the arm that returned a function for `prop === "login"` was the one place the proxy added a member, against its own header and the surface contract's "adds no member and removes none" (§ 3). It is gone from `ng-proxy.ts`; the note stays as the record of what the proxy must never do again.
+- **Defect - the passthrough could not survive the real `ng` (FIXED `1.0.0-dev.7`).** It was `Reflect.get(ng, prop).bind(ng)`, and `@ng-org/web`'s `ng` is itself a Proxy whose `get` trap answers every key - `bind` included - with a path-carrying callable returning a Promise. So the published `ng` handed back a promise for every member and a caller got `<member> is not a function`. Invisible because the library's own internals bypass this proxy and every fake in the suite is a plain object. Now `Reflect.apply(real, ng, args)`; the stand-in in `test/ng-proxy.test.ts` is shaped like the real proxy, which is what makes the test one.
 - Disappears at migration (the whole module).
 
 ## 2. NURI internals — the unexported slice of `nuri.ts`, plus the minting point
@@ -93,27 +95,35 @@ export function subscribePhysicalDoc(nuri: Nuri, onChange: (r: DocChange, type:
 ## 6. Bootstrap repo opening — `emulated-verifier/open-repo.ts`
 
 ```ts
-// open-repo.ts:75
+// open-repo.ts:98
 export type SyncState = "syncing" | "synced" | "timed-out";
-// open-repo.ts:104 — TEST-ONLY
+// open-repo.ts:197 - TEST-ONLY
 export function setOpenTimeoutForTests(ms: number): void;
-// open-repo.ts:110
+// open-repo.ts:204
 export function resetOpenedRepos(): void;
-// open-repo.ts:135
+// open-repo.ts:252 - DERIVED, nothing stores it
 export function getSyncState(nuri: Nuri): SyncState | "unknown";
-// open-repo.ts:167
-export async function ensureRepoOpen(nuri: Nuri): Promise<void>;
-// open-repo.ts:184
-export async function ensurePhysicalRepoOpen(nuri: Nuri): Promise<void>;
-// open-repo.ts:259
-export async function ensureReposOpen(nuris: Nuri[]): Promise<void>;
+// open-repo.ts:315
+export async function ensureRepoOpen(nuri: Nuri, holderKey?: string): Promise<void>;
+// open-repo.ts:339 - the unguarded core, for ONE importer (`shared-wallet/physical.ts`)
+export async function openRepoUnguarded(nuri: Nuri): Promise<void>;
 ```
 
-Heals the cold-start defect of the anchored read path: on a fresh session a not-yet-open repo reads empty, so before an anchored read the repo is opened by subscribing (`subscribePhysicalDoc`) and awaiting the first `State` push — the sync barrier — with a bounded timeout. The subscription is held for the session; per-nuri `SyncState` keeps `synced` and `timed-out` apart.
+> Corrected 2026-09-21 (`1.0.0-dev.9`), for this module only. The listing above used to name
+> an `ensurePhysicalRepoOpen` export that this module has never had - it lives in
+> `shared-wallet/physical.ts:134`, the machinery's door - and an `ensureReposOpen(nuris)`
+> batch that was deleted as dead code. It also missed `openRepoUnguarded` and
+> `ensureRepoOpen`'s second parameter. The rest of this document carries drift of the same
+> age and was deliberately left alone.
+
+Heals the cold-start defect of the anchored read path: on a fresh session a not-yet-open repo reads empty, so before an anchored read the repo is opened by subscribing (`subscribePhysicalDoc`) and awaiting the first `State` push — the sync barrier — with a bounded timeout. The subscription is held for the session; `SyncState` keeps `synced` and `timed-out` apart.
+
+> Corrected 2026-09-24 (`1.0.0-dev.10`), for this module only: the line numbers above, and the fact that nothing here STORES openness or the barrier any more. This module kept a set of live bootstrap subscriptions and a per-nuri sync-state map, and both outlived the subscription they described - `surface/subscribe.ts` drops its listeners without a word, which `configure()` makes it do. There is one answer now, `surface/subscribe.ts`'s `docChannel(nuri)`, and `getSyncState` derives from it on every call; what this module records is the bootstrap listener it took out, which answers "am I still listening" and nothing more.
 
 - The opening mechanism is **level 2, VERIFIED as a composition**: `doc_subscribe` exists (`sdk/js/lib-wasm/src/lib.rs:1908`), and the push variants `TabInfo`/`State`/`Patch` are the engine's `AppResponseV0` (`engine/net/src/app_protocol.rs:1354-1358`). The ORDER (TabInfo first, then the initial State) and "first State = presence guaranteed, absence definitive" are **empirical, pinned by the in-repo e2e CONTRACT-3 probe — an ASSUMPTION about ordering as far as upstream is concerned**: no upstream statement fixes the push order, so a future reordering upstream would silently break the barrier. Bound: the e2e probe fails loudly if the order changes.
 - "Hold a live subscription to keep the repo open" — **ASSUMPTION** (nothing upstream documents subscription lifetime as what retains a repo in `self.repos`); observed to work, bounded by the same probe.
-- **Defect — the header's mechanism claim is contradicted at the source (see Findings F2).** `open-repo.ts:10-12` says an anchored `sparql_query` on a repo absent from `self.repos` "silently returns 0 rows (never a `RepoNotFound`)". Verified upstream: absence from `self.repos` yields `Err(NgError::RepoNotFound)` (`request_processor.rs:264,269`), the ReadQuery arm converts it into `AppResponse::error` (`:1293-1296`), and the web binding REJECTS the JS promise with it (`sdk/js/lib-wasm/src/lib.rs:606`). The observed 0-rows-no-error behaviour has two candidate explanations that the source does support: a persistent verifier reloads every known repo into `self.repos` at `Verifier::load` (`engine/verifier/src/verifier.rs:535-560`) so the repo is present-but-unsynced (a genuine 0-row read), and/or the lib's own per-doc tolerance (`readUserStore`, `surface/read-model.ts` per-doc catch) converts a rejection into an empty result. The healed symptom is real and the fix correct; the stated mechanism is not established, and a maintainer reasoning from it would mispredict behaviour whenever the verifier is not persistent.
+- **`ensureRepoOpen` THROWS when the public store could not be asked** (`1.0.0-dev.9`). It calls `emulated-verifier/public-store.ts`'s `fetchReadCap` first - a document in a public store hands its key to whoever asks, so the question has to be put before the boundary decides - and that call used to answer `false` for a download that had REJECTED, which is the same value a document exposing no key answers with. The open then declined silently and the anchored read that followed refused the reader for holding no key: a true statement, made out of an outage, and the wrong one to act on. The rejection now reaches the caller. The open itself still never throws (a `doc_subscribe` that never pushes is bounded by the fallback timeout), and `holderKey` skips the fetch entirely, so the processor's door is unaffected.
+- **Defect, SINCE REPAIRED in the code — the header's mechanism claim was contradicted at the source (see Findings F2).** The header was corrected on 2026-08-03 and now states the mechanism below itself; what follows is kept as the record of what was wrong and how it was established. `open-repo.ts:10-12` says an anchored `sparql_query` on a repo absent from `self.repos` "silently returns 0 rows (never a `RepoNotFound`)". Verified upstream: absence from `self.repos` yields `Err(NgError::RepoNotFound)` (`request_processor.rs:264,269`), the ReadQuery arm converts it into `AppResponse::error` (`:1293-1296`), and the web binding REJECTS the JS promise with it (`sdk/js/lib-wasm/src/lib.rs:606`). The observed 0-rows-no-error behaviour has two candidate explanations that the source does support: a persistent verifier reloads every known repo into `self.repos` at `Verifier::load` (`engine/verifier/src/verifier.rs:535-560`) so the repo is present-but-unsynced (a genuine 0-row read), and/or the lib's own per-doc tolerance (`readUserStore`, and the `surface/read-model.ts` per-doc catch until `1.0.0-dev.8` removed it) converts a rejection into an empty result. The healed symptom is real and the fix correct; the stated mechanism is not established, and a maintainer reasoning from it would mispredict behaviour whenever the verifier is not persistent.
 - `SyncState` and `getSyncState` are lib-invented vocabulary — **NO COUNTERPART** (upstream has no consumer-facing "sync state of a repo" API at any level; `OrmSubscription.readyPromise`, `sdk/js/orm/src/connector/GraphOrmSubscription.ts:260`, is the closest level-3 signal, per-subscription not per-repo).
 - At migration the whole module becomes "open the store by cap at bootstrap" (native) and is removed with the shim.
 
@@ -169,11 +179,11 @@ export async function ensureAccount(id: string): Promise<VirtualUserRecord>;
 ### 9b. Scope-index resolution
 
 ```ts
-// store-registry.ts:1079
-export async function userStoreDoc(id: string, scope: Scope): Promise<Nuri>;
+// REMOVED in `1.0.0-dev.6`
+// export async function userStoreDoc(id: string, scope: Scope): Promise<Nuri>;
 ```
 
-The scope-INDEX document of one account (what `watchShape` subscribes to for container changes). Same resolution as the published `resolveWriteGraph`, without doubling as a write target.
+The scope-INDEX document of one account, which the reactive shape read subscribed to for container changes. That read goes through the SDK's own shape query since `1.0.0-dev.6`, which follows the data rather than a container this package maintains, so the function lost its only caller and went with it. The ruling below is kept for the record, because the question it answers is the one the target closes.
 
 - **Level 2, VERIFIED counterpart with the indirection removed**: in the target the container IS the store, and its id is on the session (`Session.private_store_id | protected_store_id | public_store_id`, `index.d.ts:264-272`); the listing a subscriber watches is the store's `ldp:contains` graph, written natively by `doc_create` (`request_processor.rs:706-708`). The function's question survives; the per-account parameter and the index-document indirection disappear.
 
@@ -249,7 +259,7 @@ export function inspectOutbox(): void;
 
 **F3 — incomplete citation in `subscribe.ts`.** `subscribe.ts:31` cites the ORM fan-out abort as "`initialize.rs:125-128`" with no path. The file is `engine/verifier/src/orm/graph/initialize.rs`; lines 125-128 are the graph loop calling `self.open_for_target(&nuri.target, true).await?` — verified, the `?` propagates `RepoNotFound` and aborts the whole subscription. Substance correct; the bare filename is unfindable without this note.
 
-**F4 — `docs/api-contract.md` lags the `surface/placement.ts` split.** Its § 12 and appendix still list `resolveAccount`, `ensureAccount`, `userStoreDoc`, `isOwnInbox`, `myInboxes`, `addLink`, `readLinks`, `reservedAccount`, `resetRegistryCache` as the SDK entry's `storeRegistry` namespace, and § 13/§ 15 place `virtualUsers.*` on the SDK entry — since the split (`index.ts` routes through `surface/placement.ts`) those are internal. That file is being edited concurrently; noted here, deliberately not fixed by this document.
+**F4 — `docs/api-contract.md` lags the `surface/placement.ts` split.** Its § 12 and appendix still list `resolveAccount`, `ensureAccount`, `isOwnInbox`, `myInboxes`, `addLink`, `readLinks`, `reservedAccount`, `resetRegistryCache` as the SDK entry's `storeRegistry` namespace, and § 13/§ 15 place `virtualUsers.*` on the SDK entry — since the split (`index.ts` routes through `surface/placement.ts`) those are internal. That file is being edited concurrently; noted here, deliberately not fixed by this document.
 
 **F5 — `reservedAccount`'s collision guarantee is asserted about code the lib does not own.** `store-registry.ts:200-206` states the injected `normalizeId` "strips a leading `@`, trims, and lowercases, so a NUL prefix is unreachable" — that describes ONE consumer's normalizer, not a contract; the lib's own default is `id.trim()` (`shared-wallet/bootstrap.ts`), which passes U+0000 through. The reserved namespace is disjoint only if every consumer's normalizer keeps it so. Either document the requirement on `StoreRegistryDeps.normalizeId`, or reject NUL-prefixed raw ids at `accountKey`.
 
@@ -264,8 +274,8 @@ export function inspectOutbox(): void;
 
 ## Appendix — full internal export inventory (for diffing)
 
-Fully internal modules: `shared-wallet/access-log.ts` (`AccessOp`, `setAccessLog`, `enabled`, `activeIdentity`, `accessLogPrefix`, `logStage`, `shortNuri`, `logAccess`); `emulated-verifier/machinery.ts` (`MACHINERY_NS`, `isMachinerySubject`); `surface/ng-proxy.ts` (`makeNg`); `emulated-verifier/open-repo.ts` (`SyncState`, `setOpenTimeoutForTests`, `resetOpenedRepos`, `getSyncState`, `ensureRepoOpen`, `ensurePhysicalRepoOpen`, `ensureReposOpen`); `shared-wallet/outbox-log.ts` (`inspectOutbox`); `shared-wallet/physical.ts` (`physicalCreate`, `physicalQuery`, `physicalUpdate`); `emulated-verifier/reach.ts` (`declareInfrastructure`, `isInfrastructure`, `resetInfrastructure`, `mayReach`, `assertMayReach`, `mustNotAttempt`); `emulated-verifier/read-filter.ts` (`filterReadable`, `makeReadFilteredView`).
+Fully internal modules: `shared-wallet/access-log.ts` (`AccessOp`, `setAccessLog`, `enabled`, `activeIdentity`, `accessLogPrefix`, `logStage`, `shortNuri`, `logAccess`); `emulated-verifier/machinery.ts` (`MACHINERY_NS`, `isMachinerySubject`); `surface/ng-proxy.ts` (`makeNg`, `wrappedNg`); `emulated-verifier/open-repo.ts` (`SyncState`, `setOpenTimeoutForTests`, `resetOpenedRepos`, `getSyncState`, `ensureRepoOpen`, `ensurePhysicalRepoOpen`, `ensureReposOpen`); `shared-wallet/outbox-log.ts` (`inspectOutbox`); `shared-wallet/physical.ts` (`physicalCreate`, `physicalQuery`, `physicalUpdate`); `emulated-verifier/reach.ts` (`declareInfrastructure`, `isInfrastructure`, `resetInfrastructure`, `mayReach`, `assertMayReach`, `mustNotAttempt`); `emulated-verifier/read-filter.ts` (`filterReadable`, `makeReadFilteredView`).
 
-Internal slices of partially-published modules: `model/nuri.ts` (`targetOf`, `parseNuri`) and `emulated-verifier/caps.ts` (`mintCap`); `emulated-verifier/connect.ts` (`startConnect`); `subscribe.ts` (`subscribePhysicalDoc`); `shared-wallet/account-registry.ts` (`reservedAccount`, `resetRegistryCache`, `resolveAccount`, `ensureAccount`, `userStoreDoc`, `isOwnInbox`, `myInboxes`, `addLink`, `readLinks`).
+Internal slices of partially-published modules: `model/nuri.ts` (`targetOf`, `parseNuri`) and `emulated-verifier/caps.ts` (`mintCap`); `emulated-verifier/connect.ts` (`startConnect`); `subscribe.ts` (`subscribePhysicalDoc`); `shared-wallet/account-registry.ts` (`reservedAccount`, `resetRegistryCache`, `resolveAccount`, `ensureAccount`, `isOwnInbox`, `myInboxes`, `addLink`, `readLinks`).
 
-Modules with no internal exports (everything they export is published): `types.ts`, `docs.ts`, `inbox.ts`, `surface/read-model.ts`, `shared-wallet/virtualUsers.ts`, `emulated-verifier/caps.ts`, `sparql.ts`, `lifecycle.ts`, `surface/use-shape.ts`, `surface/watch-shape.ts`, `surface/placement.ts`, and the entry point.
+Modules with no internal exports (everything they export is published): `types.ts`, `docs.ts`, `inbox.ts`, `shared-wallet/virtualUsers.ts`, `emulated-verifier/caps.ts`, `sparql.ts`, `lifecycle.ts`, `surface/use-shape.ts`, `surface/watch-shape.ts`, `surface/placement.ts`, and the entry point.

docs/migration-guide.md

@@ -37,7 +37,7 @@ this step swaps the *emulated* key for the real one, not the model:
 - `caps.markInPublicStore` and the whole of `emulated-verifier/public-store.ts` disappear: which store a document sits in stops being a fact we record, and serving a public store's repos becomes the broker's job (`expose_outer`, the ReadCap downloaded from the outer overlay — `PublicRepoLinkV0`, `engine/net/src/types.rs:5098`). Nothing an application calls changes: it circulates bare references now, and will still.
 - `assertMayWrite` goes with it — refusing a write on a cap the public store served is a stand-in for the write cap this emulation does not have.
 - The read filter (`emulated-verifier/read-filter.ts`) and the possession gate in
-  `read-model.readUnion` are then dead code — the broker only delivers documents
+  the anchored per-document read are then dead code — the broker only delivers documents
   whose cap the wallet holds. Remove them.
 - The write guard (`surface/ng-proxy.ts` `sparql_update` override) is a separate axis and
   is decorative today (every internal writer bypasses the proxy); it belongs to the

docs/nextgraph-current-state.md

@@ -301,8 +301,8 @@ from JS today a repo becomes queryable ONLY by being `doc_create`d in this sessi
 
 **Consequence for this lib's mono-wallet polyfill:** every account's documents are
 `doc_create`d in the one shared wallet within the same session, so they are all
-already in `self.repos`. `surface/read-model.ts` reads the bounded, by-need set of docs
-with one anchored `sparql_query` per doc (`SELECT ?s ?p ?o WHERE { ?s ?p ?o }`,
+already in `self.repos`. `surface/read-document.ts` reads one document
+with one anchored `sparql_query` (`SELECT ?s ?p ?o WHERE { ?s ?p ?o }`,
 anchor = the doc NURI): the anchor resolves that same-session repo directly (no
 separate open needed) and restricts the query to its graph, so it is O(1) per doc,
 independent of the store's size. An absent repo throws `RepoNotFound` on its own
@@ -768,7 +768,7 @@ anchored `sparql_query` against a document written in an earlier session comes b
 reader of the polyfill and healed identically in each (`ensureRepoOpen` before the read,
 `packages/polyfill/src/emulated-verifier/open-repo.ts`): the user's own documents,
 the user's store (`shared-wallet/account-registry.ts` `readUserStore`), the by-need doc batch
-(`surface/read-model.ts` `readUnion`), and the store-root pointer read (`shared-wallet/account-registry.ts`
+(`surface/read-document.ts` `readDocumentSubjects`), and the store-root pointer read (`shared-wallet/account-registry.ts`
 `resolvePointer`). The heal is `doc_subscribe(nuri)` → await the first `State` (the sync
 barrier) → THEN the anchored read, and it is verified to return the data.
 

docs/read-model.md

@@ -104,7 +104,7 @@ There is no reactive union query. So reactivity is assembled:
 - keep a lightweight reactive subscription — `doc_subscribe`, or the ORM on an
   already-opened single store (never a per-entity fan-out) — on the synced docs;
 - on its change signal, re-run the bounded set of per-doc anchored
-  `sparql_query`s (`readUnion`) — never an anchorless union-scan.
+  `sparql_query`s — never an anchorless union-scan.
 
 Keep the reactive ORM strictly to already-opened single stores; it is a change
 *signal* source here, not the list source.
@@ -165,7 +165,7 @@ Step (4) has a nuance worth recording, and it is exactly why the read path uses
 graph — so an explicit `GRAPH ?g` body spans every opened graph independently of
 the anchor. The anchor's "one repo" restriction is observable only for a body that
 reads the **default graph** (no `GRAPH` wrapper). That is precisely why the per-doc
-read in `surface/read-model.ts` uses the anchored default-graph body
+read in `surface/read-document.ts` uses the anchored default-graph body
 `SELECT ?s ?p ?o WHERE { ?s ?p ?o }`: the anchor makes that one repo the default
 graph, so the read is bounded to it — O(1) per doc, independent of wallet size —
 and never iterates the other named graphs. (A repo absent from `self.repos` throws
@@ -185,21 +185,24 @@ sync an unknown repo.)
 > is per-doc anchored, preserved above), **not** a **constant** `GRAPH <D>` write,
 > which lands in D's repo. Re-run that harness to re-verify against a newer broker.
 
-## Implementation — `surface/read-model.ts`
+## Implementation — one anchored query per document, and nothing above it
 
-`readUnion(docs)` implements this: for each requested doc NURI (the
-bounded by-need set), run — in parallel, tolerant per-doc (a doc that fails is
-skipped, never aborting the batch like the ORM fan-out would) — one anchored
+For each doc NURI in the by-need set, run one anchored
 `SELECT ?s ?p ?o WHERE { ?s ?p ?o }` with `anchor = docNuri`. The anchor restricts
 the query to that doc's graph (default graph), so it returns only that doc's
 triples, O(1) per doc, independent of wallet size. There is no anchorless
-union-scan. Each entity's subject IRI is its own document NURI, so the subject is
-the anchor doc NURI; the result is grouped per subject (keeping the `UnionSubject[]`
-shape: `subject`, `graph`, `props`). A ReadCap gate drops any doc the current user
-may not read (defence-in-depth). The consumer application maps the result to its
-types (e.g. its own `readEntities`). Reactivity = the consumer application re-calls
-`readUnion` on its change signal (no reactive union query exists).
+union-scan. Subjects come back as the document carries them: an entity written under
+the document's own NURI reads back under it, and a document carrying several subjects
+yields several. A ReadCap gate refuses any doc the current user may not read, at the
+door of `docs.sparqlQuery`. Reactivity = the caller re-runs the reads on its change
+signal (no reactive union query exists).
 
-> The name `readUnion` / `UnionSubject` is historical (it once ran a union query).
-> The read is now per-doc anchored, bounded to the read-set — the "union" is only
-> the logical concatenation of the per-doc results, never an anchorless graph scan.
+> **`readUnion` / `UnionSubject` were published for this until `1.0.0-dev.8`, and are
+> gone.** They were the loop above, plus policies of this package's own: a document that
+> failed was swallowed into an empty answer, one whose key the reader did not hold was
+> dropped rather than refused, and the rows were grouped into property bags. Nothing at
+> any level of NextGraph answers that composition, and upstream an anchored query on a
+> repo the verifier does not hold REJECTS — so "skip it and carry on" is a habit a caller
+> would have had to unlearn. The loop, and what a failure inside it means, now belong to
+> whoever writes it. The name was historical too: the read has been per-doc anchored
+> throughout, and the "union" was only the logical concatenation of the results.

docs/readcap-and-nuri-model.md

@@ -359,12 +359,12 @@ The consequence for anything this library exposes: **a call either hands over th
 
 ### Where this library stands, act by act
 
-- **Transmit the reference** — covered, with no dedicated call: every reference the surface returns is bare (`createEntityDoc`, `docCreate`, `listMyEntityDocs`, `UnionSubject.subject`/`.graph`). An application cites what it already holds. Faithful.
+- **Transmit the reference** — covered, with no dedicated call: every reference the surface returns is bare (`createEntityDoc`, `docCreate`). An application cites what it already holds. Faithful.
 - **Transmit the reference and the key** — `inbox.share(doc, toUser)`. Names the document and the person; the key is looked up and sealed into a deposit, and the recipient applies it by connecting, with nothing to call. Faithful in shape. One recorded divergence: the deposit always goes to the recipient's PROTECTED inbox, where upstream the choice follows the profile the person was reached by (`engine/verifier/src/inbox_processor.rs:787`).
 
 **And the property that makes the first act worth anything — a public store SERVES its documents' caps.** `PublicRepoLinkV0` (`engine/net/src/types.rs:5098-5124`) carries `repo`, `public_store` and `peers` and no `read_cap`, and its own comment says why: *"The latest ReadCap of the branch (or main branch) will be **downloaded from the outerOverlay**, if the peer brokers listed below allow it. […] This link is durable, because the public site are **served differently by brokers**."* The key is not something a sender hands over; it is something the network gives to whoever asks, because the broker pinned the outer overlay (`expose_outer`, `engine/broker/src/server_storage/core/overlay.rs:103-133`).
 
-That is emulated, since 2026-08-06, in `emulated-verifier/public-store.ts` — and emulated **without touching the guard**. Possession remains the one criterion: a public document is readable not because `mayReach` makes an exception, but because its cap is *obtainable* — the library asks, files what it gets, and from there the ordinary path applies. Every read door asks first (`readUnion`, `docs.sparqlQuery`, `ensureRepoOpen`, `documentInboxAddress`).
+That is emulated, since 2026-08-06, in `emulated-verifier/public-store.ts` — and emulated **without touching the guard**. Possession remains the one criterion: a public document is readable not because `mayReach` makes an exception, but because its cap is *obtainable* — the library asks, files what it gets, and from there the ordinary path applies. Every read door asks first (`docs.sparqlQuery`, `ensureRepoOpen`, `documentInboxAddress`, and since `1.0.0-dev.9` `useShapeQuery` for every document its scope NAMES). A door that could not ASK says so: the fetch rejects rather than answering "this document exposes no cap", because a reader told the second would stop looking.
 
 Where the emulation shows its seams, stated rather than hidden:
 

docs/simulation.md

@@ -135,7 +135,7 @@ public/protected/private stores — on top of one shared wallet.
   user, and the only listing there is: the cross-account fan-out
   (`listEntityDocs` / `resolveReadGraphs` / `allAccounts` / `loadShim`) was
   **removed on 2026-07-30**, being cross-user enumeration by construction. The real read path is
-  `readUnion(docs)`, which reads the by-need doc set with one per-doc
+  one anchored `docs.sparqlQuery` per document, which reads the by-need doc set with one per-doc
   anchored `sparql_query`, never an anchorless union-scan of the physical
   wallet (see [`read-model.md`](./read-model.md)). The consumer application resolves
   the by-need doc set from the current wallet's own scope index and
@@ -528,7 +528,7 @@ redundant so a lapse in either is caught by the other:
   / `sparqlUpdate` / `subscribeDoc`): nothing reaches `ng` unless the connected user
   possesses that document's cap. It fires on a request that should never have been
   made, and makes it fail loudly rather than succeed quietly.
-- **Rule 2, do not even attempt** (`mustNotAttempt`, at the callers — `readUnion`
+- **Rule 2, do not even attempt** (`mustNotAttempt`, at the callers — `ensureRepoOpen`
   filters before opening or reading, `ensureRepoOpen` returns): a reader holding no
   cap does not issue the operation at all. Upstream you cannot even *address* a repo
   you have no cap for, so asking is not "a read that will be refused" — it is a read

docs/source-layout-by-fate.md

@@ -77,7 +77,7 @@ The 25 current modules, with the two splits' offspring shown where a module divi
 | `surface/use-shape.ts` | `surface/use-shape.ts` | Level-3 passthrough + the read-filter view imported from `emulated-verifier/` — mixture-by-import, already in the right shape. |
 | `surface/watch-shape.ts` | `surface/watch-shape.ts` | Surface composition over `emulated-verifier/` and the placement calls; its "planned `useShape` upgrade" header claim remains an ASSUMPTION with no provenance (`docs/api-contract.md` § 5) — a layout cannot fix that (§ 6). |
 | `subscribe.ts` | `surface/subscribe.ts`, minus `subscribePhysicalDoc` → `shared-wallet/physical.ts` | The guarded `subscribeDoc`/`subscribeDocs` and `docChangeType` are surface (level 2, `doc_subscribe`, `sdk/js/lib-wasm/src/lib.rs:1908`). The physical door moves to the machinery module (§ 4); the unguarded core is exported under its `Unguarded` name for that one importer. |
-| `surface/read-model.ts` | `surface/read-model.ts` — stays whole | The anchored-read mechanics are level-1-verified and survive as composition (`docs/api-contract.md` § 6). Its possession gate and machinery filter mirror native behaviour (§ 4 ruling) and arrive via named `emulated-verifier/` imports. |
+| `surface/read-model.ts` | `surface/read-document.ts` — INTERNAL since `1.0.0-dev.8` | The anchored-read mechanics are level-1-verified and the anchored query itself is published as `docs.sparqlQuery` (`docs/api-contract.md` § 6). What this module keeps is the one-document read the index arm needs: the cold-start open, and the grouping of a SELECT's rows. The batch above it (`readUnion`) was removed with its `UnionSubject`. |
 | `inbox.ts` | **split**: `surface/inbox.ts` (post, `postToDocument`, `shareCap`) + `emulated-verifier/inbox-processing.ts` (`read`/`materialize`/`readSynced`/`processInbox`/`watch`, `assertOwnInbox`, the deposit RDF vocabulary) | § 4 ruling. `surface/inbox.ts` re-exports the processing functions with a header saying exactly what `docs/api-contract.md` § 9 says — that enumerating deposits is emulation detail — so the published `inbox.*` namespace is unchanged and the warning sits at the one place the two halves meet. |
 | `surface/placement.ts` | dissolved into `surface/placement.ts` | The hand-built slice becomes a real module: the app-facing placement/addressing calls (`createEntityDoc`, `listMyEntityDocs`, `resolveScopeGraph`, `resolveWriteGraph`, `userInbox`, `openDocumentInbox`, `documentInboxAddress`), composed from the two lower layers. Its existence today is the strongest in-repo evidence for the whole reorganisation: it does by hand what the folder boundary does structurally. |
 | `shared-wallet/account-registry.ts` | **split three ways**: `surface/placement.ts` + `emulated-verifier/branch-registers.ts` + `shared-wallet/account-registry.ts` | The sharpest case — 1377 lines spanning all three fates. `branch-registers.ts` takes the durable compartments: the Store-branch cap register (`holdOwnCap`/`readStoreCaps` — emulating `AddRepo { read_cap }`, level 1, `engine/repo/src/types.rs:1890-1899`), the User-branch Link register (`addLink`/`readLinks` — `AddLink { read_cap }`, `types.rs:1939-1948`), the inbox-cap records (`AddInboxCapV0`, `types.rs:1969-1981`) and the Header-branch address records. `account-registry.ts` takes the pointer→doc-shim indirection, `resolveAccount`/`ensureAccount`, `reservedAccount`, the cache, `VirtualUserRecord`/`RegistrySession` — NO COUNTERPART, the shim proper. `placement.ts` (surface) keeps the app-facing calls listed above plus `userStoreDoc`/`isOwnInbox`/`myInboxes` staying internal on the register side per their contract entries. |
@@ -106,7 +106,7 @@ Fate labels exist per *export* in the two contracts; a module is mixed when its
 - **Signal B — guarded/unguarded twin exports:** the `*Physical*` / `*Unguarded` pairs. Hits: `subscribe.ts:104/118`, `open-repo.ts:167/184`.
 - **Signal C — act vs stand-in-processing under one namespace:** exports of the same module carrying different fate labels in the contracts. Hits: `inbox.ts` (§ 9: sender acts are target-shaped; deposit enumeration is emulation detail), `shared-wallet/account-registry.ts` (§ 12: labels range from level-2 VERIFIED to NO COUNTERPART), `types.ts` (model types vs injection types, § 1 vs § 10), `nuri.ts` (guards vs `mintCap`, internal contract § 2), `polyfill.ts` (entry vs config store).
 
-Full mixed list: `docs.ts`, `surface/read-model.ts`, `inbox.ts`, `subscribe.ts`, `emulated-verifier/open-repo.ts`, `shared-wallet/account-registry.ts`, `nuri.ts`, `types.ts`, `polyfill.ts`, `surface/ng-proxy.ts`, `emulated-verifier/caps.ts`, `emulated-verifier/connect.ts`. (`surface/use-shape.ts` and `surface/watch-shape.ts` cross fates only through imports — already the desired end state.)
+Full mixed list: `docs.ts`, `surface/read-document.ts`, `inbox.ts`, `subscribe.ts`, `emulated-verifier/open-repo.ts`, `shared-wallet/account-registry.ts`, `nuri.ts`, `types.ts`, `polyfill.ts`, `surface/ng-proxy.ts`, `emulated-verifier/caps.ts`, `emulated-verifier/connect.ts`. (`surface/use-shape.ts` and `surface/watch-shape.ts` cross fates only through imports — already the desired end state.)
 
 ### The criterion
 
@@ -115,7 +115,7 @@ Full mixed list: `docs.ts`, `surface/read-model.ts`, `inbox.ts`, `subscribe.ts`,
 ### Rulings
 
 - **`docs.ts` — KEEP WHOLE.** The cap filing inside `docCreate` mirrors the target's own `doc_create`, which commits `AddRepo` to the Store branch and `ldp:contains` to the Main branch *in the same native call* (level 1, `engine/verifier/src/request_processor.rs:697-710`, re-verified). Splitting the mint into a separate caller-visible step would create a two-step creation surface the target does not have — the split itself would be the divergence. Same for the reach guard: the refusal is native (`RepoNotFound`). The fix is visibility, not surgery: both effects become named imports from `emulated-verifier/`.
-- **`surface/read-model.ts` — KEEP WHOLE.** Its possession gate mirrors native non-delivery, and its machinery-subject drop mirrors the structural invisibility of non-content branches (`BranchCrdt::None`, `types.rs:1420`, level 1). Both are the target's own composition of "read a document".
+- **`surface/read-model.ts` — KEEP WHOLE** (now `surface/read-document.ts`, and no longer published). Its machinery-subject drop mirrors the structural invisibility of non-content branches (`BranchCrdt::None`, `types.rs:1420`, level 1). Its possession gate is no longer its own: the refusal lives at `docs.sparqlQuery`, where it has always been, which is also why removing the batch above it lost nothing.
 - **`inbox.ts` — SPLIT.** Different fates (api-contract § 9: the acts are target-shaped level-1 inventions; the deposit-list surface "may never have this shape") *and* different callers (apps post/share/watch; `emulated-verifier/connect.ts` processes). The deposit RDF vocabulary — pure emulation transport (upstream a deposit is a sealed message, `InboxMsgBody`, `engine/net/src/types.rs:4265`, level 1, carrying no target document) — lives once, on the emulated side.
 - **`subscribe.ts` / `emulated-verifier/open-repo.ts` — SPLIT the physical doors out** (criterion's corollary): different caller (machinery only), different fate (the guarded/unguarded pair collapses to one call when the wallet is the boundary). They regroup in `shared-wallet/physical.ts`.
 - **`shared-wallet/account-registry.ts` — SPLIT three ways** (§ 3). It is the module the flat layout hides most: signal C fires on nearly every export group, and the repo already voted for the split by hand-building `surface/placement.ts`.

examples/notebook/README.md

@@ -8,7 +8,7 @@ It exists for two reasons, and the second is the one that matters.
 
 **It is what the applicative e2e suite drives** (`packages/polyfill/e2e/notebook.ts`, `bun run test:e2e:app`). The other suite talks to a bag of methods on `window.__sdk`, which proves the functions run but never that an application can be written with them — and that gap shipped a real defect once: a document's inbox was green in tests and unusable in practice, because the harness handed an address across an identity boundary through a variable, something no application can do. Here each identity is its own browser page, and the only values that cross between them are the ones that cross in life: a note's reference, copied off one screen, and an identifier typed into a field.
 
-It has already paid for itself: writing it surfaced that `UnionSubject` returned `string` where the values are always document references (so a consumer had to cast whatever it had just read before passing it back), and that the access gate normalized what a user typed but not what the URL carried.
+It has already paid for itself: writing it surfaced that the then-published `readUnion`'s property bags returned `string` where the values are always document references (so a consumer had to cast whatever it had just read before passing it back), and that the access gate normalized what a user typed but not what the URL carried.
 
 ## What it exercises
 

examples/notebook/app.ts

@@ -19,7 +19,7 @@
  * ── The domain is deliberately thin ───────────────────────────────────────
  * Notes. Each user writes their own, may publish one, may hand a reader the key to a
  * private one, and may leave a message on someone else's note. That is enough to
- * exercise placement by scope, capability possession, directed sharing, per-document
+ * exercise placement by store, capability possession, directed sharing, per-document
  * inboxes and reactive reads — without inventing a product.
  *
  * ── Plain DOM, on purpose ─────────────────────────────────────────────────
@@ -34,20 +34,29 @@ import {
   ensureIdentity,
   inbox,
   init,
-  readUnion,
   storeRegistry,
   subscribeDoc,
+  initNg as initNgSignals,
+  useShapeQuery,
   type Nuri,
-  type Scope,
+  type ShapeObservable,
+  type ShapeType,
+  type BaseType,
   // Polyfill-era — ONE call, and it is the whole of what goes away.
   configure,
 } from "@ng-eventually/polyfill";
 import { ng as realNg, init as realInit } from "@ng-org/web";
+// The SDK's shape query, which `useShapeQuery` reads through since `1.0.0-dev.6`, and
+// the call that hands the ORM its session. Both are handed to `configure` below, the
+// same way the `ng` is: this package never imports the SDK itself.
+import { initNg as ormInitNg, RdfOrmSubscription } from "@ng-org/orm";
 
 // --- the domain, such as it is ---------------------------------------------
 
 const TITLE = "urn:notebook:title";
 const BODY = "urn:notebook:body";
+const NOTE = "urn:notebook:Note";
+const RDF_TYPE = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type";
 
 interface Note {
   doc: Nuri;
@@ -55,6 +64,61 @@ interface Note {
   body: string;
 }
 
+/**
+ * Which store a note goes in, as the interface offers it - and the only thing that word
+ * still decides.
+ *
+ * A store is chosen when a note is CREATED, and it is named by its reference: the library
+ * hands out one per store and `createEntityDoc` takes it, exactly where `doc_create` takes
+ * its store. There is no matching question on the way back - **a read cannot be scoped by
+ * store**, upstream or here, so the list below is every note this identity holds, whatever
+ * shelf it was written to. That is not a shortcoming of this example; it is what the
+ * target can express.
+ */
+function shelf(name: string): Promise<Nuri> {
+  return name === "public"
+    ? storeRegistry.publicStore()
+    : name === "protected"
+      ? storeRegistry.protectedStore()
+      : storeRegistry.privateStore();
+}
+
+/** The shape of a note: a subject carrying `rdf:type urn:notebook:Note`. */
+const NoteShape = {
+  shape: "urn:notebook:NoteShape",
+  schema: {
+    "urn:notebook:NoteShape": {
+      iri: "urn:notebook:NoteShape",
+      predicates: [
+        {
+          iri: RDF_TYPE,
+          readablePredicate: "type",
+          minCardinality: 1,
+          maxCardinality: 1,
+          dataTypes: [{ literals: [NOTE], valType: "iri" }],
+        },
+        // The two fields a note actually carries. A shape declares what comes BACK as
+        // well as what matches: a predicate the shape does not name is not projected onto
+        // the object, so leaving these out would return notes with no title and no body.
+        {
+          iri: TITLE,
+          readablePredicate: "title",
+          minCardinality: 1,
+          maxCardinality: 1,
+          dataTypes: [{ valType: "string" }],
+        },
+        {
+          iri: BODY,
+          readablePredicate: "body",
+          minCardinality: 1,
+          maxCardinality: 1,
+          dataTypes: [{ valType: "string" }],
+        },
+      ],
+    },
+  },
+} satisfies ShapeType<BaseType>;
+
 // --- bootstrap: ONE polyfill-era call --------------------------------------
 //
 // Everything else an application calls is SDK surface, preserved at migration. This one
@@ -63,8 +127,10 @@ interface Note {
 
 configure({
   ng: realNg,
-  useShape: (() => {}) as never, // this example reads through `readUnion`, not the ORM
+  useShape: (() => {}) as never, // this app reads through `useShapeQuery`, never the hook
+  ormSubscription: RdfOrmSubscription.getOrCreate,
   init: realInit,
+  initNg: ormInitNg,
   sharedWallet: {
     fileUrl: "/shared-wallet.ngw",
     password: (globalThis as { __NOTEBOOK_WALLET_PASSWORD__?: string }).__NOTEBOOK_WALLET_PASSWORD__ ?? "",
@@ -84,33 +150,78 @@ configure({
 // is only what this app itself reads.
 const sessionReady = new Promise<{ session_id: string }>((resolve) => {
   init((event: { status: string; session?: { session_id: string } }) => {
-    if (event.status === "loggedin" && event.session) resolve(event.session);
+    if (event.status === "loggedin" && event.session) {
+      // The ORM reaches the SDK through a module-level promise of its own; nothing it
+      // opens starts before this. Through the library's `initNg`, which is the SDK-shaped
+      // call and survives migration.
+      initNgSignals(realNg, event.session);
+      resolve(event.session);
+    }
   }, true, []);
 });
 
 // --- the acts ---------------------------------------------------------------
 
-/** Write a new note in `scope`. The document is created, then filled. */
-async function writeNote(scope: Scope, title: string, body: string): Promise<Nuri> {
-  const doc = await storeRegistry.createEntityDoc(scope);
+/** Write a new note on `shelfName`'s shelf. The document is created, then filled. */
+async function writeNote(shelfName: string, title: string, body: string): Promise<Nuri> {
+  const doc = await storeRegistry.createEntityDoc(await shelf(shelfName));
   const s = await sessionReady;
+  // The type triple is what makes the note findable afterwards: the reactive read asks
+  // for a SHAPE, and a shape is pinned on `rdf:type`. Nothing indexes it for us.
   await docs.sparqlUpdate(
     s.session_id,
-    `INSERT DATA { <${doc}> <${TITLE}> "${escape(title)}" ; <${BODY}> "${escape(body)}" }`,
+    `INSERT DATA { <${doc}> <${RDF_TYPE}> <${NOTE}> ; <${TITLE}> "${escape(title)}" ; <${BODY}> "${escape(body)}" }`,
     doc,
   );
   return doc;
 }
 
-/** My notes in `scope`, read the way the library intends: list, then read. */
-async function myNotes(scope: Scope): Promise<Note[]> {
-  const docsOfScope = await storeRegistry.listMyEntityDocs(scope);
-  const subjects = await readUnion(docsOfScope);
-  return subjects.map((s) => ({
-    doc: s.graph,
-    title: s.props[TITLE]?.[0] ?? "(sans titre)",
-    body: s.props[BODY]?.[0] ?? "",
-  }));
+/**
+ * My notes, read the way the library offers them: ONE reactive query over everything this
+ * identity holds, shaped as a note.
+ *
+ * `did:ng:i` is the scope that means the whole local dataset - the caller's own documents
+ * are what it can reach. The application does not list its documents and then read them:
+ * there is no call to list them with, and there is no question "what is in this store" to
+ * ask. It names a SHAPE, and what it holds of that shape comes back.
+ */
+let notes: ShapeObservable | null = null;
+
+function noteQuery(): ShapeObservable {
+  if (!notes) {
+    notes = useShapeQuery(NoteShape, { graphs: "did:ng:i" });
+    // One subscription for the life of the page: a note that arrives - written here, or
+    // shared by somebody else - re-renders the list with no call from this code.
+    notes.subscribe(() => renderNotes());
+  }
+  return notes;
+}
+
+/** Wait until the query has ANSWERED - pending is not an answer, and neither is a failure
+ *  read as an empty list. */
+function answered(q: ShapeObservable): Promise<void> {
+  return new Promise((resolve) => {
+    let off: (() => void) | null = null;
+    const look = (): void => {
+      if (q.getSnapshot().isPending) return;
+      off?.();
+      resolve();
+    };
+    off = q.subscribe(look);
+    look();
+  });
+}
+
+function currentNotes(): Note[] {
+  return noteQuery()
+    .getSnapshot()
+    .data.map((s) => ({
+      // The read hands back the SHAPE's own objects now, not property bags: `@graph` is
+      // the document a note lives in, and each field is the predicate's readable name.
+      doc: s["@graph"] as Nuri,
+      title: typeof s.title === "string" ? s.title : "(sans titre)",
+      body: typeof s.body === "string" ? s.body : "",
+    }));
 }
 
 /**
@@ -127,12 +238,30 @@ async function myNotes(scope: Scope): Promise<Note[]> {
  * to change when the real SDK takes that same string.
  */
 async function readSharedNote(reference: string): Promise<Note | null> {
-  const [note] = await readUnion([reference]);
-  if (!note) return null;
+  const s = await sessionReady;
+  // ONE anchored query, naming the note. The anchor scopes the read to that document's
+  // own graph, so the body carries no `GRAPH <...>` wrapper; the library asks the public
+  // store for the key on the way in, which is what makes a bare reference enough.
+  //
+  // This was `readUnion([reference])` until `1.0.0-dev.8`. What an application composes
+  // itself now is the projection below - the SELECT and the grouping - because the
+  // primitive that did it was a batch nothing upstream answers.
+  const result = await docs.sparqlQuery(
+    s.session_id,
+    "SELECT ?s ?p ?o WHERE { ?s ?p ?o }",
+    undefined,
+    reference,
+  );
+  const rows =
+    (result as { results?: { bindings?: Array<Record<string, { value: string }>> } })
+      .results?.bindings ?? [];
+  const values = (predicate: string): string[] =>
+    rows.filter((r) => r["p"]?.value === predicate).map((r) => r["o"]!.value);
+  if (rows.length === 0) return null;
   return {
-    doc: note.graph,
-    title: note.props[TITLE]?.[0] ?? "(sans titre)",
-    body: note.props[BODY]?.[0] ?? "",
+    doc: reference as Nuri,
+    title: values(TITLE)[0] ?? "(sans titre)",
+    body: values(BODY)[0] ?? "",
   };
 }
 
@@ -201,9 +330,20 @@ const el = (id: string): HTMLElement => document.getElementById(id)!;
 const val = (id: string): string => (el(id) as HTMLInputElement).value.trim();
 
 async function refresh(): Promise<void> {
-  const scope = (el("scope") as HTMLSelectElement).value as Scope;
-  const notes = await myNotes(scope);
-  el("notes").innerHTML = notes
+  const q = noteQuery();
+  q.refetch();
+  await answered(q);
+  renderNotes();
+  // What `ensureIdentity()` returns is an OPAQUE identifier, not a display name: the SDK
+  // publishes none. So it is shown verbatim and marked as an identifier — never parsed,
+  // never split, never dressed up as a person's name.
+  const idTag = document.createElement("code");
+  idTag.textContent = identity;
+  el("who").replaceChildren("id ", idTag);
+}
+
+function renderNotes(): void {
+  el("notes").innerHTML = currentNotes()
     .map(
       (n) => `<li data-doc="${n.doc}">
         <b class="t">${n.title}</b> — <span class="b">${n.body}</span>
@@ -214,20 +354,15 @@ async function refresh(): Promise<void> {
       </li>`,
     )
     .join("");
-  // What `ensureIdentity()` returns is an OPAQUE identifier, not a display name: the SDK
-  // publishes none. So it is shown verbatim and marked as an identifier — never parsed,
-  // never split, never dressed up as a person's name.
-  const idTag = document.createElement("code");
-  idTag.textContent = identity;
-  el("who").replaceChildren("id ", idTag);
 }
 
 function wire(): void {
-  // Changing the scope changes which notes are listed — without this the list keeps
-  // showing the previous scope's notes, which reads as "my note disappeared".
+  // The shelf chooses where the NEXT note is written, and nothing else: a read cannot be
+  // scoped by store, so the list below always shows every note this identity holds.
+  // Re-rendering on a change is still worth it — a note shared in the meantime shows up.
   el("scope").addEventListener("change", () => void refresh());
   el("write").addEventListener("click", async () => {
-    await writeNote((el("scope") as HTMLSelectElement).value as Scope, val("title"), val("body"));
+    await writeNote((el("scope") as HTMLSelectElement).value, val("title"), val("body"));
     await refresh();
   });
   el("openRef").addEventListener("click", async () => {

examples/notebook/package.json

@@ -5,6 +5,10 @@
   "description": "A minimal application written against @ng-eventually/polyfill \u2014 the library's usage example, and what the e2e suite drives.",
   "dependencies": {
     "@ng-eventually/polyfill": "workspace:*",
-    "@ng-org/web": "0.1.2-alpha.13"
+    "@ng-org/orm": "0.1.2-alpha.21",
+    "@ng-org/web": "0.1.2-alpha.14"
+  },
+  "scripts": {
+    "typecheck": "pnpm exec tsc --noEmit -p tsconfig.json"
   }
 }

package.json

@@ -2,6 +2,7 @@
   "name": "ng-eventually",
   "private": true,
   "type": "module",
+  "packageManager": "pnpm@10.26.0",
   "description": "Generic polyfill layer over the NextGraph JS SDK — makes a single broker behave like the (not-yet-shipped) multi-user NextGraph: emulated capabilities and inbox. Drop-in SDK-shaped client; remove at migration. (A global-index curator package is deferred — see README.)",
   "workspaces": [
     "packages/*",
@@ -9,11 +10,11 @@
   ],
   "scripts": {
     "test": "bun test",
-    "typecheck": "bunx tsc --noEmit -p packages/polyfill/tsconfig.json"
+    "typecheck": "pnpm exec tsc --noEmit -p packages/polyfill/tsconfig.json"
   },
   "devDependencies": {
     "@types/bun": "latest",
-    "playwright": "^1.61.1",
+    "playwright": "^1.63.0",
     "typescript": "^5.6.0"
   }
 }

packages/ng-e2e-helpers/package.json

@@ -13,14 +13,14 @@
   },
   "peerDependencies": {
     "playwright": ">=1.40.0",
-    "@ng-org/web": ">=0.1.2-alpha.13"
+    "@ng-org/web": ">=0.1.2-alpha.13 <0.1.2"
   },
   "devDependencies": {
-    "@ng-org/web": "0.1.2-alpha.13",
-    "playwright": "^1.61.1"
+    "@ng-org/web": "0.1.2-alpha.14",
+    "playwright": "^1.63.0"
   },
   "scripts": {
-    "typecheck": "bunx tsc --noEmit -p tsconfig.json",
+    "typecheck": "pnpm exec tsc --noEmit -p tsconfig.json",
     "mint-wallet": "bun run bin/mint-wallet.ts"
   }
 }

packages/polyfill/README.md

@@ -1,7 +1,8 @@
 # @ng-eventually/polyfill
 
 One entry point. Most of what it publishes has the same signature as the future SDK —
-`ng`, `useShape`, `watchShape`, `docs`, `inbox`, `storeRegistry`, `readUnion` (+ types) —
+`ng`, `useShape`, `useShapeQuery`, `getObjects`, `insertObject`, `docs`, `inbox`,
+`storeRegistry` (+ types) -
 and is a drop-in for `@ng-org/web` / `@ng-org/orm`: as NextGraph matures it resolves to
 the real SDK (build alias removed) with no code change.
 
@@ -27,16 +28,34 @@ Per-symbol, with the target signature and an epistemic label on every claim:
 ```ts
 import {
   // SDK-shaped — the real SDK replaces these in place.
-  ensureIdentity, storeRegistry, inbox, readUnion, docs,
+  ensureIdentity, storeRegistry, inbox, docs,
   // Polyfill-era — one call, and it is the whole of what goes away.
   configure,
 } from "@ng-eventually/polyfill";
 
-configure({ ng: realNg, useShape: realUseShape, getSession, sharedWallet });
+configure({
+  ng: realNg, useShape: realUseShape, ormSubscription, getObjects, insertObject,
+  initNg, sharedWallet,
+});
 await ensureIdentity();              // who I am (returned), connection work awaited
-const doc = await storeRegistry.createEntityDoc("protected");
+// A store is named by its reference — `doc_create` takes one, and the session is where
+// upstream gets it. Omit it and the document goes to the private store, as upstream does.
+const doc = await storeRegistry.createEntityDoc(await storeRegistry.protectedStore());
 await docs.sparqlUpdate(sid, `INSERT DATA { … }`, doc);
-const subjects = await readUnion(await storeRegistry.listMyEntityDocs("protected"));
+// Reading is by SHAPE, over the SDK's own scope. `did:ng:i` is the whole local dataset;
+// naming documents in `graphs` reads exactly those. There is no "list my documents" call
+// and no way to scope a read by store — neither exists upstream.
+// It reads through the SDK's own shape query (`RdfOrmSubscription.getOrCreate`, passed to
+// `configure` as `ormSubscription`), and hands back the shape's own objects: `@graph`,
+// `@id` and one field per predicate the shape DECLARES.
+const query = useShapeQuery(NoteShape, { graphs: "did:ng:i" });
+// The ORM's one-shot read and its subscription-free write, at the SDK's own names and
+// signatures. Import them from HERE, never from `@ng-org/orm`: one wallet hosts every
+// identity, so the unwrapped read returns everybody's objects and the unwrapped write
+// reaches anybody's document. Wrapped, the read comes back filtered by what you hold and
+// the write is refused unless you own the document its `@graph` names.
+const notes = await getObjects(NoteShape, { graphs: "did:ng:i" });
+await insertObject(NoteShape, { "@id": "", "@graph": doc, title: "a note" });
 ```
 
 ## Principle — the polyfill compensates, it never extends
@@ -72,7 +91,7 @@ which the e2e suite drives.
 ## How a document is reached — the three acts, and no others
 
 ```ts
-import { storeRegistry, inbox, readUnion } from "@ng-eventually/polyfill";
+import { storeRegistry, inbox, docs } from "@ng-eventually/polyfill";
 
 // 1. CREATE — you hold its cap, with nothing to declare. No identity parameter: a
 //    session belongs to one user, exactly as the target's own `doc_create` assumes.
@@ -90,7 +109,11 @@ await inbox.share(doc, "bob");
 //    it and opens nothing.
 const publicDoc = await storeRegistry.createEntityDoc("public");
 // …put `publicDoc` in a QR code, a message, another document. Nothing else to do.
-await readUnion([publicDoc]);   // a stranger holding only this reads it
+// A stranger holding only that reference reads it with ONE anchored query — the anchor
+// scopes the read to that document's own graph, and the key is fetched from the public
+// store on the way in. `readUnion([publicDoc])` did this until `1.0.0-dev.8`; it was
+// this call in a loop, so the loop is yours now and the call is unchanged.
+await docs.sparqlQuery(sessionId, "SELECT ?s ?p ?o WHERE { ?s ?p ?o }", undefined, publicDoc);
 ```
 
 **The invariant behind all three: you never derive a cap from a bare reference.** You
@@ -120,5 +143,6 @@ runtime checks stay regardless — a JavaScript caller never meets the compiler.
 
 ```ts
 const saved = localStorage.getItem("doc");        // string | null
-if (saved) await readUnion([saved]);              // ✓ validated at the door
+// ✓ validated at the door — `anchor` is a `NuriLike`, so nothing to narrow here
+if (saved) await docs.sparqlQuery(sessionId, "SELECT ?s ?p ?o WHERE { ?s ?p ?o }", undefined, saved);
 ```

packages/polyfill/docs/polyfill-reference.md

@@ -85,21 +85,29 @@ change** to any document in scope.
 ```ts
 useShape<T extends BaseType>(
   shape: ShapeType<T>,
-  scope: Scope | string | undefined,
-): DeepSignalSet<T>
+  conf: RdfOrmConfig<T> | string | undefined,
+): ShapeResult   // { data, promise, subscription, isLoading, nextPage?, previousPage? }
 ```
 
 - `shape` — the ORM shape type (generated from a SHEX shape). Names the entity type
   and the properties to materialize.
-- `scope` — where to read: a `{ graphs, subjects }` scope object or a NURI string.
+- `conf` — where to read and how: the ORM's `RdfOrmConfig` (a `{ graphs, subjects }`
+  scope plus `where`, `orderBy`, `pageSize`, `maxActivePages`) or a NURI string.
   **Not to be confused with this library's `Scope`** (`types.ts`), which is the
   literal union `public | protected | private` naming a store. Same word, two
   meanings: the ORM's is a read target, ours is a placement.
-  `undefined` yields an empty read.
-- **Returns** a `DeepSignalSet<T>` — a **live reactive set**. Iterate it like a set;
-  the component re-renders whenever the set changes.
+  `undefined` yields an empty read, with `data`, `promise` and `subscription` all
+  `undefined` and `isLoading` false.
+- **Returns** the ORM's own result object, read-filtered. Read the objects off
+  **`data`** — a **live reactive set** (an ordered array once `orderBy` is asked for),
+  which the component re-renders on — or `await promise` for the same collection once
+  it has arrived. `isLoading` says whether the initial payload is still outstanding.
+  `subscription` is REFUSED here: it is the ORM's own handle, which reads and writes
+  with no capability filter at all, and this library does not hand it on.
 
-Verified surface in `nextgraph-rs`:
+Verified surface in `nextgraph-rs` — the CITED revision, which returns the collection
+itself; the BUILD returns it inside a result object, which is the signature above and the
+gap the provenance anchor records:
 `sdk/js/orm/src/frontendAdapters/react/useShape.ts` (`useShape`, line 86) →
 `OrmSubscription` (`sdk/js/orm/src/connector/GraphOrmSubscription.ts`), which calls
 `ng.orm_start_graph(...)` with a callback, applies the initial materialized objects
@@ -116,8 +124,8 @@ alongside the React one (`sdk/js/orm/src/frontendAdapters/{vue,svelte}/`).
 
 1. **An initial value.** On subscribe, the ORM materializes the current objects in
    scope and delivers them first (`AppResponseV0::GraphOrmInitial`,
-   `engine/verifier/src/orm/graph/initialize.rs:113`). The hook returns them as the
-   initial `DeepSignalSet`.
+   `engine/verifier/src/orm/graph/initialize.rs:113`). The hook publishes them as
+   `data`, the initial `DeepSignalSet`.
 2. **A stream of updates.** On every subsequent commit affecting the scope — local or
    remote — the ORM pushes a patch (`AppResponseV0::GraphOrmUpdate`), the connector
    applies it to the `DeepSignalSet`, and the component re-renders. No refetch, no
@@ -163,17 +171,23 @@ computes a result and returns once (`sparql_query`,
 
 In `@ng-eventually/polyfill` the one-shot read is exposed as:
 
+- **`getObjects(shapeType, config)`** - the ORM's own one-shot read, by SHAPE, over the
+  same `Scope` axes `useShapeQuery` takes plus `where` and `orderBy`
+  ([`../src/surface/orm.ts`](../src/surface/orm.ts)). This is the typed one, and the one
+  to reach for first. What comes back is DETACHED - a clone - so mutating or deleting an
+  item of it reaches nothing; and it is filtered by what you hold, so another identity's
+  objects are not in it. Import it from here and never from `@ng-org/orm`: one wallet
+  hosts every identity, and the unwrapped call returns everybody's objects.
 - **`docs.sparqlQuery(sid, query, base?, anchor?)`** — a raw anchored SPARQL query
   ([`../src/surface/docs.ts`](../src/surface/docs.ts)). `anchor` = the document NURI to read; the
   anchor restricts the query to that one repo's graph.
-- **`readUnion(docs)`** — read a **bounded, by-need set** of document NURIs,
-  each with its own anchored query, grouped per subject
-  ([`../src/surface/read-model.ts`](../src/surface/read-model.ts)). This is the polyfill's listing
-  primitive (see [§ Current emulation status](#current-emulation-status) and
-  [`read-model.md`](../../../docs/read-model.md)).
+  `readUnion(docs)` sat above this until `1.0.0-dev.8` and is **gone**: it was this call
+  once per document plus a batch policy nothing upstream answers. Reading a bounded set
+  of documents is this call in a loop, and what one unreadable document does to the rest
+  is decided at the call site (see [`read-model.md`](../../../docs/read-model.md)).
 
 One-shot reads do not re-render on change. To stay live over a one-shot read you must
-re-run it on a change **signal** (e.g. re-call `readUnion` when a `doc_subscribe`
+re-run it on a change **signal** (e.g. re-run the anchored query when a `doc_subscribe`
 fires) — a manual assembly that exists only because of the emulation gap below; the
 finished contract is `useShape`.
 
@@ -188,10 +202,22 @@ document model, so briefly:
   ([`../src/surface/docs.ts`](../src/surface/docs.ts)) — mirrors `ng.doc_create`. **One document = one
   repo** (`did:ng:o:<RepoID>`); there is no separate `Document` type.
 - **Write into it:** `docs.sparqlUpdate(sid, query, anchor)` — a SPARQL
-  `INSERT/DELETE` scoped to the anchor document's graph. Or, at the ORM layer, the ORM
-  update primitives (`graph_orm_update`). A write is a **commit** on the document's
+  `INSERT/DELETE` scoped to the anchor document's graph. Or, at the ORM layer,
+  `insertObject(shapeType, object)` for one typed object with its `@graph` set
+  ([`../src/surface/orm.ts`](../src/surface/orm.ts)), or a mutation of the live set a
+  shape query handed back - `set.add(...)`, `set.delete(...)`, assigning a property - which
+  the ORM batches into `graph_orm_update`. A write is a **commit** on the document's
   branch — which is exactly what every `useShape` subscriber over that document is
   pushed.
+- **Remove an object:** delete it from the LIVE set (`set.delete(item)`, the item the set
+  is holding - reached by iterating it, by `.first()` or by `.getBy(graph, subject)`).
+  There is no `deleteObject` and no document deletion at any level; what the engine
+  removes is the SHAPE's declared predicates on that subject, not the subject and not the
+  document. Deleting an item of a `getObjects` result removes nothing: that result is a
+  clone.
+- **Only the owner writes.** Holding a document's read key never grants a write -
+  `insertObject` and the ORM's `graph_orm_update` are both refused otherwise, before the
+  write is attempted.
 - **Writes target one document**, never "the union": a SPARQL update must name one
   document's graph (`resolve_target_for_sparql(update=true)` returns `InvalidTarget`
   for the union, `engine/verifier/src/request_processor.rs:275`).
@@ -284,11 +310,11 @@ from the reactive contract:
    `engine/verifier/src/request_processor.rs` `resolve_target` →
    `self.repos.get(...).ok_or(RepoNotFound)`; see
    [`nextgraph-current-state.md`](../../../docs/nextgraph-current-state.md) § *The ORM
-   fan-out hang*). So the lib reads entity lists with **`readUnion`** — a
-   bounded set of one-shot anchored `sparql_query`s
-   ([`read-model.md`](../../../docs/read-model.md)) — and reassembles reactivity by
-   **re-querying on a change signal** (a lightweight `doc_subscribe` / single-store ORM
-   used only as a *signal* source, then re-run `readUnion`). `useShape` remains valid
+   fan-out hang*). So the lib reads entity lists as **one anchored `sparql_query` per
+   document** ([`read-model.md`](../../../docs/read-model.md)) — and reassembles
+   reactivity by **re-querying on a change signal** (a lightweight `doc_subscribe` /
+   single-store ORM used only as a *signal* source, then re-run the reads). `useShape`
+   remains valid
    for a **single already-opened document**; it is the per-entity **fan-out** that is
    unfit today.
 
@@ -314,8 +340,8 @@ from the reactive contract:
    `sparqlUpdate` on a doc it is itself subscribed to (`subscribeDoc` /
    `ng.doc_subscribe`), the subscription callback appears NOT to fire for its OWN
    local commit in the same session — so the reactive re-read chain
-   ([`../src/surface/watch-shape.ts`](../src/surface/watch-shape.ts) `watchShape` → `reread` →
-   [`../src/surface/read-model.ts`](../src/surface/read-model.ts) `readUnion`) never runs, and
+   ([`../src/surface/use-shape-query.ts`](../src/surface/use-shape-query.ts) `useShapeQuery` → `reread` →
+   the anchored per-document read) never runs, and
    consumers keep the STALE value until the next connection delivers a fresh
    initial `State`. **Remote** commits DO push correctly (verified: cross-browser
    reactive update works). A code review verified the consumer wiring is correct,

packages/polyfill/e2e/notebook.ts

@@ -561,8 +561,12 @@ async function signIn(ctx: BrowserContext, appUrl: string, id: string): Promise<
 // ── the acts, expressed as the application expresses them ───────────────────
 
 /**
- * Show the notes of `scope` — the list is per-scope, so acting on a note means looking at
- * the right shelf first.
+ * Choose a shelf, and wait for the list to settle.
+ *
+ * The shelf decides where the NEXT note is written and nothing else: since `1.0.0-dev.5`
+ * a read cannot be scoped by store — the SDK has no way to say it and neither has this
+ * package — so the application lists every note its identity holds, whatever shelf it went
+ * to. Selecting one still re-renders, which is what the wait below is for.
  *
  * The wait is not decoration: the application's `change` handler runs `void refresh()`,
  * un-awaited, so reading `textContent` straight after `selectOption` reads the PREVIOUS

packages/polyfill/e2e/orm-live-entry.ts

@@ -0,0 +1,338 @@
+/**
+ * The page for the LIVE ORM measurement - what `e2e/run.ts` still does not measure.
+ *
+ * The 42-check harness injects the REAL `RdfOrmSubscription.getOrCreate` since
+ * `1.0.0-dev.6` (that is what `useShapeQuery` reads through), so a live ORM read is no
+ * longer unreachable from there. What stays here is the PUBLISHED `useShape` half: the
+ * collection an application reads off `data`, and a `.delete()` on it reaching the
+ * document. That is a different surface from the snapshot `useShapeQuery` publishes, and
+ * it has no other measurement.
+ *
+ * ── What the framework adapter contributes, and why it is not here ─────────
+ * Upstream's `useShape` is React's (`sdk/js/orm/src/frontendAdapters/react/useShape.ts`):
+ * it calls `OrmSubscription.getOrCreate(shape, scope)`, hands `signalObject` to
+ * `useDeepSignal`, and closes the subscription on unmount. The broker sees the first of
+ * those three and nothing else — `useDeepSignal` is re-render bookkeeping. So the hook
+ * injected below builds the SAME result object the shipped adapter builds, out of the same
+ * `getOrCreate(...)`, which is what a React render reaches the broker with, without a React
+ * tree to mount. What it must NOT do is return a substitute for that object: it did until
+ * 2026-09-24, and that is the reason a capability filter which handed three of that
+ * object's members back unfiltered could not fail anything here.
+ */
+
+import { ng as realNg, init as realInit } from "@ng-org/web";
+import { initNg as ormInitNg, normalizeConf, RdfOrmSubscription, type Scope as OrmScope } from "@ng-org/orm";
+import type { RdfOrmConfig } from "@ng-org/orm/all";
+import { configure, docs, init, useShape as libUseShape } from "@ng-eventually/polyfill";
+import type { BaseType, Nuri, ShapeType } from "@ng-eventually/polyfill";
+import { adoptCurrentUser, configureStoreRegistry } from "../src/shared-wallet/bootstrap";
+// The result envelope the published `useShape` hands back. Internal path, like every
+// other piece of machinery this page reaches for: an application never writes it down.
+import type { ShapeResult } from "../src/model/types";
+
+// ── the shape under measurement ─────────────────────────────────────────────
+
+/**
+ * The smallest shape that can be matched at all, written by hand rather than generated.
+ *
+ * `rdf-orm build` turns a `.shex` file into exactly this object — `{ schema, shape }`
+ * (`sdk/js/shex-orm/src/types.ts:ShapeType`) — and the generator is not what is under
+ * measurement here. Two predicates, both `minCardinality: 1`, because that is what
+ * `engine/verifier/src/orm/graph/query.rs:schema_shape_to_sparql` turns into required
+ * triple patterns: a shape with none of them would match every subject in the document.
+ */
+const LIVE_SHAPE = {
+  shape: "did:ng:z:E2ELiveShape",
+  schema: {
+    "did:ng:z:E2ELiveShape": {
+      iri: "did:ng:z:E2ELiveShape",
+      predicates: [
+        {
+          iri: "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
+          readablePredicate: "@type",
+          dataTypes: [{ valType: "iri", literals: ["did:ng:z:E2ELive"] }],
+          minCardinality: 1,
+          maxCardinality: 1,
+        },
+        {
+          iri: "did:ng:z:liveMark",
+          readablePredicate: "liveMark",
+          dataTypes: [{ valType: "string" }],
+          minCardinality: 1,
+          maxCardinality: 1,
+        },
+      ],
+    },
+  },
+} satisfies ShapeType<BaseType>;
+
+const TYPE_IRI = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type";
+
+// ── the broker session ──────────────────────────────────────────────────────
+
+interface BrokerSession {
+  session_id: string;
+  private_store_id: string;
+  protected_store_id: string;
+  public_store_id: string;
+  [k: string]: unknown;
+}
+
+let session: BrokerSession | null = null;
+let sessionResolve!: (s: BrokerSession) => void;
+const sessionReady = new Promise<BrokerSession>((r) => (sessionResolve = r));
+
+/**
+ * The injected hook — the real ORM's broker-facing half.
+ *
+ * It keeps the subscription aside so the probe can await `readyPromise`, which is the ORM's
+ * own answer to "did the initial payload arrive": it resolves on that path and on no other
+ * (`sdk/js/orm/src/connector/GraphOrmSubscription.ts:handleInitialResponse`), so a start
+ * the broker refused leaves it pending for ever — the silence this measurement is here to
+ * break.
+ */
+/**
+ * The handle this page keeps, DERIVED from `getOrCreate` rather than written by hand.
+ *
+ * `RdfOrmSubscription` (renamed from `OrmSubscription` in `@ng-org/orm@0.1.2-alpha.21`)
+ * now takes its config as a type parameter and `getOrCreate` returns a narrowed
+ * `RdfOrmSubscriptionFor<...>` - the paging methods are `Omit`ted when no `pageSize` is
+ * asked for. Naming the class directly would restate that narrowing and get it wrong the
+ * next time it moves; `ReturnType` asks the package what it actually hands back.
+ */
+type LiveSubscription = ReturnType<
+  typeof RdfOrmSubscription.getOrCreate<
+    ShapeType<BaseType>,
+    BaseType,
+    ReturnType<typeof normalizeConf<BaseType>>
+  >
+>;
+
+let liveSubscription: LiveSubscription | null = null;
+
+/**
+ * The injected hook, returning the SHIPPED shape rather than a substitute for it.
+ *
+ * Until 2026-09-24 this returned `sub.signalObject` - a bare collection, which is what the
+ * hook returned three releases ago and is NOT what the installed one returns. That is why
+ * the capability filter could hand three members of the real result back unfiltered and
+ * still pass every gate in this repository: no fake anywhere returned the shape the SDK
+ * ships, so no test could fail on it.
+ *
+ * What it returns now is the envelope the installed
+ * `dist/frontendAdapters/react/useShape.js` builds, expression for expression, minus the
+ * two pieces that are React's and only React's: `useDeepSignal` (re-render bookkeeping
+ * over the same `signalObject`) and the `useState` that flips once `readyPromise` resolves
+ * - here the subscription's own `isReady` answers the same question. `isLoading` is
+ * upstream's own expression and is reproduced as written, including the fact that it
+ * CONTRADICTS its own documentation, which says `true` while no data is available yet: a
+ * fake that quietly fixed the target would be measuring something nobody ships.
+ *
+ * The two page commands are `undefined`, which is what the shipped hook sets them to
+ * outside a paginated mode - this read asks for no `orderBy`, so there is no page to turn.
+ */
+function realOrmUseShape(
+  shapeType: ShapeType<BaseType>,
+  conf: RdfOrmConfig<BaseType> | string | undefined,
+): ShapeResult {
+  // Upstream: an undefined config opens nothing, and the three members that would carry
+  // the data are `undefined` with `isLoading` false.
+  if (conf === undefined) {
+    liveSubscription = null;
+    return {
+      data: undefined,
+      isLoading: false,
+      promise: undefined,
+      subscription: undefined,
+      nextPage: undefined,
+      previousPage: undefined,
+    };
+  }
+  // `normalizeConf` is the SDK's OWN, imported rather than restated: it is the line the
+  // shipped hook runs before `getOrCreate`, and a hand-written stand-in for it is the
+  // class of substitute this whole file exists to stop making.
+  const sub = RdfOrmSubscription.getOrCreate(shapeType, normalizeConf(conf));
+  liveSubscription = sub;
+  return {
+    data: sub.isReady ? sub.signalObject : undefined,
+    isLoading: sub.isReady,
+    promise: sub.readyPromise,
+    subscription: sub,
+    nextPage: undefined,
+    previousPage: undefined,
+  };
+}
+
+configure({
+  ng: realNg,
+  useShape: realOrmUseShape,
+  init: realInit,
+  sharedWallet: { fileUrl: "/harness-not-used.ngw", password: "harness" },
+});
+adoptCurrentUser("e2e-orm-live");
+configureStoreRegistry({
+  getSession: async () => {
+    const s = session ?? (await sessionReady);
+    return {
+      sessionId: s.session_id,
+      privateStoreId: s.private_store_id,
+      protectedStoreId: s.protected_store_id,
+      publicStoreId: s.public_store_id,
+    };
+  },
+  normalizeId: (id: string) => id.trim().replace(/^@/, "").toLowerCase(),
+  pointerGuard: { attempts: 8, baseMs: 150, maxStepMs: 2000 },
+});
+
+// ── the probe ───────────────────────────────────────────────────────────────
+
+const state: { status: string; error?: string } = { status: "connecting" };
+
+interface LiveProbe {
+  doc: Nuri;
+  subject: string;
+  startError: string | null;
+  readyMs: number | null;
+  deleteError: string | null;
+}
+let probe: LiveProbe | null = null;
+
+/**
+ * The collection the published `useShape` hands back RIGHT NOW, by calling it again.
+ *
+ * Calling again is what a React render does, and it is what the result envelope requires:
+ * `data` is `undefined` until the initial payload has arrived, and the envelope captured
+ * at the first call cannot learn that it has - which is why the shipped hook re-runs on a
+ * `useState` flip. `getOrCreate` pools on the shape and the scope, so asking again is the
+ * same subscription and costs nothing.
+ *
+ * This is also the one place this page reads the published surface the way an application
+ * does: through `data`, the member the SDK's own example destructures first.
+ */
+function liveView(): Set<BaseType> | undefined {
+  if (probe === null) return undefined;
+  const data = libUseShape(LIVE_SHAPE, { graphs: [probe.doc] }).data;
+  return data === undefined ? undefined : (data as Set<BaseType>);
+}
+
+/** Count the triples the document still holds for the seeded subject. */
+async function seededTripleCount(doc: Nuri, subject: string): Promise<number> {
+  const s = await sessionReady;
+  const res = await docs.sparqlQuery(
+    s.session_id,
+    `SELECT ?p ?o WHERE { <${subject}> ?p ?o }`,
+    undefined,
+    doc,
+  );
+  const rows = Array.isArray(res)
+    ? res
+    : ((res as { results?: { bindings?: unknown[] } })?.results?.bindings ?? []);
+  return rows.length;
+}
+
+(window as unknown as { __sdk: Record<string, unknown> }).__sdk = {
+  status: () => state.status,
+  error: () => state.error ?? null,
+
+  /**
+   * Seed a document with one shape-matching object, then open the live read through the
+   * PUBLISHED `useShape`.
+   *
+   * The subject IRI follows the ORM's own generator
+   * (`GraphOrmSubscription.ts:signalObjectPropGenerator`): the document NURI's first 53
+   * characters, then `:q:`, then a name. Nothing requires that form of a hand-written
+   * SPARQL insert, and using it removes one way for this measurement to differ from what
+   * the ORM itself would have written.
+   */
+  async liveStart() {
+    const s = await sessionReady;
+    const doc = (await docs.docCreate(
+      s.session_id,
+      "Graph",
+      "data:graph",
+      "store",
+      undefined,
+    )) as Nuri;
+    const subject = `${doc.substring(0, 53)}:q:e2eLiveRead`;
+    await docs.sparqlUpdate(
+      s.session_id,
+      `INSERT DATA { <${subject}> <${TYPE_IRI}> <did:ng:z:E2ELive> ; <did:ng:z:liveMark> "measured" }`,
+      doc,
+    );
+    const seeded = await seededTripleCount(doc, subject);
+
+    // The ORM reaches the SDK through its own module-level promise, resolved once.
+    ormInitNg(realNg, s as unknown as Parameters<typeof ormInitNg>[1]);
+
+    let startError: string | null = null;
+    const t0 = Date.now();
+    try {
+      libUseShape(LIVE_SHAPE, { graphs: [doc] });
+    } catch (e) {
+      startError = e instanceof Error ? e.message : String(e);
+      probe = { doc, subject, startError, readyMs: null, deleteError: null };
+      return { doc, subject, seeded, startError };
+    }
+    probe = { doc, subject, startError: null, readyMs: null, deleteError: null };
+    // Un-awaited on purpose: a refused start never resolves this, and the runner's own
+    // bound is what turns that silence into a verdict.
+    void liveSubscription?.readyPromise.then(() => {
+      if (probe) probe.readyMs = Date.now() - t0;
+    });
+    return { doc, subject, seeded, startError: null };
+  },
+
+  /** How many objects the published `useShape` view holds right now. */
+  liveCount: () => liveView()?.size ?? -1,
+  /** Milliseconds from the `useShape` call to `readyPromise`, or null while it is pending. */
+  liveReadyMs: () => probe?.readyMs ?? null,
+  liveItems: () =>
+    [...(liveView() ?? [])].map((i) => ({
+      id: i["@id"] as string,
+      graph: i["@graph"] as string,
+      mark: i.liveMark as string,
+    })),
+
+  /**
+   * Delete the seeded object through the set the hook returned — the gesture the consuming
+   * application reports as the shape for removal.
+   */
+  liveDelete() {
+    if (!probe) return { deleted: false, error: "no probe" };
+    const view = liveView();
+    if (view === undefined) return { deleted: false, error: "no data yet" };
+    const item = [...view][0];
+    if (item === undefined) return { deleted: false, error: "view is empty" };
+    try {
+      const deleted = view.delete(item);
+      return { deleted, error: null };
+    } catch (e) {
+      const error = e instanceof Error ? e.message : String(e);
+      probe.deleteError = error;
+      return { deleted: false, error };
+    }
+  },
+
+  /** The document's own answer: how many triples the seeded subject still has. */
+  async liveSeededTriples() {
+    if (!probe) return -1;
+    return seededTripleCount(probe.doc, probe.subject);
+  },
+};
+
+(async () => {
+  try {
+    await init(
+      (event: { session: BrokerSession }) => {
+        session = event.session;
+        state.status = "connected";
+        sessionResolve(session);
+      },
+      true,
+      [],
+    );
+  } catch (e) {
+    state.status = "error";
+    state.error = e instanceof Error ? e.message : String(e);
+  }
+})();

packages/polyfill/e2e/orm-live-read.ts

@@ -0,0 +1,266 @@
+/**
+ * Does a live `useShape` read reach the DEPLOYED broker, and does deleting from the set it
+ * publishes on `data` reach the document?
+ *
+ * Standalone, and deliberately outside `e2e/run.ts`: what it measures is the PUBLISHED
+ * `useShape` - the collection an application reads off the `data` member of what the ORM
+ * hook hands it, and a `.delete()` on that collection reaching the document. `e2e/run.ts` exercises the other shape read,
+ * `useShapeQuery`, which since `1.0.0-dev.6` reads through the SDK's shape query too. Two
+ * surfaces, two runs.
+ *
+ * Run: `bun run e2e/orm-live-read.ts` from `packages/polyfill`.
+ *
+ * -- What it decides ----------------------------------------
+ * The verdict is readable in one number: does `readyPromise` settle. It does on one path
+ * only — the arrival of an initial payload from the engine
+ * (`GraphOrmSubscription.ts:handleInitialResponse`) — so a refused start leaves it pending
+ * for ever, which is exactly why the failure is silent and why a bound, not an await, is
+ * what turns it into a report. Nothing here infers a verdict from a version string.
+ *
+ * -- What it found, and the row that went with the answer ----------------
+ * On 2026-09-16 the read did not start: the engine answered `Deserialization error of
+ * config`, and a sixth row of this run established WHERE that `config` sits - position 4,
+ * before the callback, where the five-argument client of the day landed its callback. The
+ * deployment was AHEAD of the pinned client packages, not behind them.
+ *
+ * Updating them answered it: `@ng-org/web@0.1.2-alpha.14` declares six arguments with
+ * `config` at index 4 and `@ng-org/orm@0.1.2-alpha.21` sends six to match, and the run
+ * measured `6 passed, 0 failed` with the read ready in 16ms and the delete reaching the
+ * document. The characterisation row was retired with the question it answered: there is
+ * nothing left for it to find out, and a row that always prints the same sentence teaches
+ * whoever reads this report to skip it.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { execSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import {
+  armSuiteDeadline,
+  closeContext,
+  closeQuietly,
+  launchWatchedContext,
+  newPage,
+  serveOnEphemeralPort,
+  setupBrokerPage,
+  within,
+  type BrowserContext,
+  type Frame,
+  type Page,
+} from "ng-e2e-helpers";
+import { WALLET, mintBatchWallet } from "./harness-page";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ENTRY = path.resolve(__dirname, "orm-live-entry.ts");
+const BUNDLE_OUT = path.resolve(__dirname, ".dist", "orm-live-entry.js");
+
+// ── bounds ──────────────────────────────────────────────────────────────────
+
+/** `bun build` is a local bundle; a minute is already ten times what it takes. */
+const BUILD_MS = 60_000;
+/**
+ * The whole measurement. Five checks against one fresh wallet, where the expensive parts
+ * are the broker login and one document creation — the 42-check suite pays both and
+ * measures 3.4 min in total, so eight minutes here is the point past which this has
+ * stopped being a measurement of anything.
+ */
+const SUITE_DEADLINE_MS = 8 * 60 * 1000;
+/** One `__sdk` bridge call. `frame.evaluate()` has no deadline of its own. */
+const BRIDGE_MS = 2 * 60 * 1000;
+/**
+ * How long a live read may take to deliver its initial payload.
+ *
+ * NOT yet computed from a measured latency of this path, and it cannot be while the start
+ * is refused: nothing has ever settled here to measure. It is sized against the duration
+ * the step before it is allowed — the broker login, bounded at 45s in `ng-e2e-helpers` and
+ * measured at a few seconds — so a read that has not answered in 60s has not answered
+ * because it was slow. The first run that settles prints `ready in Nms`; set this to a
+ * generous multiple of that figure then, and say so here.
+ */
+const READY_MS = 60_000;
+/**
+ * How long the delete may take to reach the document. Same status, and the write it waits
+ * on is the one `e2e/run.ts` measures elsewhere at a second or two against this broker.
+ */
+const DELETE_MS = 30_000;
+
+// ── what this run reports ───────────────────────────────────────────────────
+
+/**
+ * Every check, declared here so the run's total is known BEFORE the browser launches — the
+ * convention `e2e/notebook.ts` states at length: a run that dies in its setup still has a
+ * total to be compared against, so a difference between two runs is always a real one.
+ */
+const CHECKS: readonly string[] = [
+  "the document accepted the seed (two triples for one subject)",
+  "the live read STARTS: `useShape` answers and the subscription reports ready",
+  "the initial payload carries the seeded object, with its `@id` and `@graph`",
+  "`.delete()` on that set is accepted",
+  "the deletion reached the DOCUMENT: the seeded subject's triples are gone",
+];
+
+type Check = { name: string; ok: boolean; detail?: string };
+const results: Check[] = [];
+function check(name: string, ok: boolean, detail?: string): void {
+  results.push({ name, ok, detail });
+  console.log(`  [${ok ? "PASS" : "FAIL"}] ${name}${detail ? " — " + detail : ""}`);
+}
+/** The bridge as the browser side of `frame.evaluate` sees it — no `any`, and no import
+ *  the serialized callback could not carry across. */
+type Bridge = Record<string, (...a: unknown[]) => unknown>;
+declare global {
+  interface Window {
+    __sdk?: Bridge;
+  }
+}
+
+function sdk<T>(frame: Frame, method: string, ...args: unknown[]): Promise<T> {
+  return within(`__sdk.${method}() in the broker iframe`, BRIDGE_MS, () =>
+    frame.evaluate(
+      ([m, a]) => window.__sdk![m as string]!(...(a as unknown[])),
+      [method, args] as const,
+    ),
+  ) as Promise<T>;
+}
+
+function buildBundle(): void {
+  fs.mkdirSync(path.dirname(BUNDLE_OUT), { recursive: true });
+  execSync(`bun build ${ENTRY} --outfile ${BUNDLE_OUT} --bundle --format=esm`, {
+    stdio: "pipe",
+    cwd: path.resolve(__dirname, ".."),
+    timeout: BUILD_MS,
+  });
+}
+
+function serve(): Promise<{ url: string; close: () => void }> {
+  const bundle = fs.readFileSync(BUNDLE_OUT, "utf-8");
+  const html = `<!DOCTYPE html><html><head><meta charset="utf-8"><title>ng-eventually ORM live read</title></head><body><div id="root"></div><script type="module" src="/orm-live-entry.js"></script></body></html>`;
+  return serveOnEphemeralPort((req, res) => {
+    if (req.url === "/orm-live-entry.js") {
+      res.writeHead(200, { "Content-Type": "application/javascript; charset=utf-8" });
+      res.end(bundle);
+    } else {
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      res.end(html);
+    }
+  });
+}
+
+async function main(): Promise<void> {
+  armSuiteDeadline("the ORM live-read measurement", SUITE_DEADLINE_MS);
+  const started = Date.now();
+
+  console.log("[orm-live] building the page bundle...");
+  try {
+    buildBundle();
+  } catch (e) {
+    console.error(
+      "[orm-live] the bundle did not build. `@ng-org/orm` is an OPTIONAL PEER of this " +
+        "package, so an application that does not name it gets nothing - but THIS " +
+        "checkout declares it in packages/polyfill devDependencies, and `pnpm install` " +
+        "does fetch that. So the ORM is not missing by design here: run `pnpm install` " +
+        "at the repository root. NOTHING was measured, so nothing is concluded.",
+    );
+    console.error(String((e as { stderr?: Buffer })?.stderr ?? e));
+    process.exit(1);
+  }
+
+  console.log("[orm-live] minting this run's wallet...");
+  const wallet = await mintBatchWallet("the ORM live-read measurement (e2e/orm-live-read.ts)");
+  const { url, close: closeServer } = await serve();
+  console.log(`[orm-live] page served at ${url}`);
+
+  let ctx: BrowserContext | null = null;
+  let page: Page | null = null;
+  try {
+    ctx = await launchWatchedContext("orm-live", wallet.dir);
+    page = await newPage("the ORM live-read page", ctx);
+    page.on("pageerror", (e) => console.error("[iframe error]", e.message));
+    page.on("console", (m) => {
+      if (m.type() === "error") console.error("[iframe console]", m.text());
+    });
+
+    const frame = await setupBrokerPage(page, url, WALLET.password);
+    await frame.waitForFunction(() => window.__sdk !== undefined, { timeout: 30_000 });
+    await frame.waitForFunction(() => window.__sdk!.status!() === "connected", {
+      timeout: 60_000,
+    });
+
+    const start = await sdk<{
+      doc: string;
+      subject: string;
+      seeded: number;
+      startError: string | null;
+    }>(frame, "liveStart");
+    check(CHECKS[0]!, start.seeded === 2, `doc=${start.doc} triples=${start.seeded}`);
+
+    // The verdict. A refused start never settles `readyPromise`, so this wait IS the
+    // measurement — and the bound is what turns "for ever" into a reported failure.
+    let readyMs: number | null = null;
+    try {
+      await frame.waitForFunction(() => window.__sdk!.liveReadyMs!() !== null, {
+        timeout: READY_MS,
+      });
+      readyMs = await sdk<number | null>(frame, "liveReadyMs");
+    } catch {
+      readyMs = null;
+    }
+    check(
+      CHECKS[1]!,
+      start.startError === null && readyMs !== null,
+      start.startError !== null
+        ? `useShape threw: ${start.startError}`
+        : readyMs === null
+          ? `readyPromise still pending after ${READY_MS / 1000}s — the engine refused the ` +
+            "start; the next row says what it expected instead"
+          : `ready in ${readyMs}ms`,
+    );
+
+    const items = await sdk<Array<{ id: string; graph: string; mark: string }>>(frame, "liveItems");
+    const seen = items[0];
+    check(
+      CHECKS[2]!,
+      items.length === 1 && seen?.id === start.subject && seen?.graph === start.doc,
+      `items=${JSON.stringify(items)}`,
+    );
+
+    const del = await sdk<{ deleted: boolean; error: string | null }>(frame, "liveDelete");
+    check(CHECKS[3]!, del.deleted === true && del.error === null, `deleted=${del.deleted} error=${del.error}`);
+
+    let remaining = await sdk<number>(frame, "liveSeededTriples");
+    try {
+      await within("the deletion reaching the document", DELETE_MS, async () => {
+        const deadline = Date.now() + DELETE_MS;
+        while (remaining > 0 && Date.now() < deadline) {
+          await page!.waitForTimeout(1000);
+          remaining = await sdk<number>(frame, "liveSeededTriples");
+        }
+      });
+    } catch {
+      /* the count below is the verdict either way */
+    }
+    check(CHECKS[4]!, remaining === 0, `triples left for the seeded subject: ${remaining}`);
+
+  } finally {
+    if (page) await closeQuietly("the ORM live-read page", () => page!.close());
+    if (ctx) await closeContext("orm-live", ctx);
+    closeServer();
+    wallet.discard();
+  }
+
+  const passed = results.filter((r) => r.ok).length;
+  const failed = results.length - passed;
+  console.log(
+    `\n══ ORM live-read summary: ${passed} passed, ${failed} failed, ${CHECKS.length} declared ` +
+      `— run ${((Date.now() - started) / 60000).toFixed(1)} min ══`,
+  );
+  if (failed > 0 || results.length !== CHECKS.length) {
+    for (const r of results.filter((x) => !x.ok)) console.log(`  - ${r.name}: ${r.detail ?? ""}`);
+    process.exit(1);
+  }
+}
+
+main().catch((e) => {
+  console.error("[orm-live] fatal:", e);
+  process.exit(1);
+});

packages/polyfill/e2e/polyfill-entry.ts

@@ -15,22 +15,30 @@
  */
 
 import { ng as realNg, init as realInit } from "@ng-org/web";
+// The REAL ORM. `useShapeQuery` reads through the SDK's own shape query since
+// `1.0.0-dev.6`, so the harness has to hand it one: a fake Set-like is enough for the
+// read FILTER (which is pure) and says nothing about a read that reaches the broker.
+// `initNg` is what resolves the ORM's own session promise; nothing starts before it.
+import { initNg as ormInitNg, RdfOrmSubscription } from "@ng-org/orm";
 import {
   configure,
   docs,
   init,
   subscribeDoc,
   subscribeDocs,
-  readUnion,
   inbox,
   storeRegistry,
   useShape as libUseShape,
-  watchShape,
+  useShapeQuery,
+  initNg,
 } from "@ng-eventually/polyfill";
 // The harness tests the LIBRARY, so it legitimately reaches machinery a consumer
 // application must not — but through the internal path, never the published entry.
 // `storeRegistry` above is the app-facing slice; these are the shim internals.
 import * as registryInternals from "../src/shared-wallet/account-registry";
+// The shared `useShape` fake, the same one `bun test` injects. Type-only imports
+// inside it, so nothing of `bun:test` reaches this bundle.
+import { makeUseShapeHook } from "../test/use-shape-fake";
 // The harness plays SEVERAL identities on one page — something no application does, and
 // the reason `setCurrentUser` / `configureStoreRegistry` are no longer published. It
 // reaches them by their internal path, like the rest of its machinery.
@@ -48,7 +56,62 @@ import { ensureIdentity } from "@ng-eventually/polyfill";
 // The harness narrows for its OWN assertions; a consumer never has to (the entries take
 // plain strings and validate inside). Internal path, like the rest of its machinery.
 import { isNuri } from "../src/model/nuri";
-import type { Nuri, ShapeObservable, ShapeQuery } from "@ng-eventually/polyfill";
+
+/**
+ * The published reference of one of the connected identity's three stores.
+ *
+ * Placement stopped being spelled as a word on the published surface in `1.0.0-dev.5`:
+ * an application names a store by what `privateStore()`, `protectedStore()` or
+ * `publicStore()` hands it. The journeys below still walk the three, so this is the step
+ * from one to the other - through the published calls.
+ */
+/** The whole local dataset - upstream's own marker, what `""` normalises to. */
+const EVERYTHING = { graphs: "did:ng:i" };
+
+/**
+ * The shape the two `useShapeQuery` journeys read - built here rather than inline, since
+ * both of them need the same one and it is now handed to the SDK.
+ *
+ * Two predicates, both `minCardinality: 1`, because that is what
+ * `engine/verifier/src/orm/graph/query.rs:schema_shape_to_sparql` turns into REQUIRED
+ * triple patterns: a shape constraining nothing would match every subject in the dataset.
+ * The title is the second one, and it is what proves the real data landed rather than an
+ * empty object of the right type.
+ */
+function wsShape(cls: string) {
+  return {
+    shape: "urn:e2e:ws:Shape",
+    schema: {
+      "urn:e2e:ws:Shape": {
+        iri: "urn:e2e:ws:Shape",
+        predicates: [
+          {
+            iri: "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
+            readablePredicate: "type",
+            maxCardinality: 1,
+            minCardinality: 1,
+            dataTypes: [{ literals: [cls], valType: "iri" }],
+          },
+          {
+            iri: "urn:e2e:ws:title",
+            readablePredicate: "title",
+            maxCardinality: 1,
+            minCardinality: 1,
+            dataTypes: [{ valType: "string" }],
+          },
+        ],
+      },
+    },
+  } satisfies ShapeType<BaseType>;
+}
+
+const storeOfType = (t: "public" | "protected" | "private"): Promise<Nuri> =>
+  t === "public"
+    ? storeRegistry.publicStore()
+    : t === "protected"
+      ? storeRegistry.protectedStore()
+      : storeRegistry.privateStore();
+import type { BaseType, Nuri, ShapeObservable, ShapeQuery, ShapeType } from "@ng-eventually/polyfill";
 
 const { IdentityStore } = virtualUsers;
 
@@ -69,6 +132,52 @@ function asAnchor(s?: string): Nuri | undefined {
   return s === undefined ? undefined : asNuri(s);
 }
 
+/** The reserved prefix: triples whose SUBJECT falls under it are this package's own
+ *  machinery, not the document's data. `readUnion` dropped them for the caller; an
+ *  application composing its own read drops them itself, and the contract says so. */
+const RESERVED_SUBJECT_PREFIX = "urn:ng-eventually:";
+
+/**
+ * Read ONE document with the published anchored query and group its rows per subject -
+ * what an application composes since `readUnion` was removed in `1.0.0-dev.8`.
+ *
+ * It THROWS, exactly like `docs.sparqlQuery` under it: a document that cannot be read is
+ * a failure, never an empty answer. Every caller below that wants to carry on past one
+ * says so with a `catch` of its own, which is where upstream leaves that decision too.
+ */
+async function readOneDocument(
+  sessionId: string,
+  docLike: string,
+): Promise<Array<{ subject: string; graph: Nuri; props: Record<string, string[]> }>> {
+  const doc = asNuri(docLike);
+  // Anchored -> default graph = this repo, so the body carries no `GRAPH <...>` wrapper.
+  const res: unknown = await docs.sparqlQuery(
+    sessionId,
+    "SELECT ?s ?p ?o WHERE { ?s ?p ?o }",
+    undefined,
+    doc,
+  );
+  const rows = Array.isArray(res)
+    ? (res as Array<Record<string, { value: string } | undefined>>)
+    : ((res as { results?: { bindings?: Array<Record<string, { value: string } | undefined>> } })
+        .results?.bindings ?? []);
+  const bySubject = new Map<string, { subject: string; graph: Nuri; props: Record<string, string[]> }>();
+  for (const row of rows) {
+    const subject = row["s"]?.value;
+    const p = row["p"]?.value;
+    const o = row["o"]?.value;
+    if (subject === undefined || !p || o === undefined) continue;
+    if (subject.startsWith(RESERVED_SUBJECT_PREFIX)) continue;
+    let entry = bySubject.get(subject);
+    if (!entry) {
+      entry = { subject, graph: doc, props: {} };
+      bySubject.set(subject, entry);
+    }
+    (entry.props[p] ??= []).push(o);
+  }
+  return [...bySubject.values()];
+}
+
 // ── The broker session, resolved once the iframe connects ──────────────────
 interface BrokerSession {
   session_id: string;
@@ -82,27 +191,24 @@ let session: BrokerSession | null = null;
 let sessionResolve!: (s: BrokerSession) => void;
 const sessionReady = new Promise<BrokerSession>((r) => (sessionResolve = r));
 
-// A minimal in-memory Set-like, so the lib's read-filtered `useShape` view can be
-// exercised WITHOUT the real ORM (`@ng-org/orm` is not installed here, and the
-// read-filter is pure — it wraps whatever Set-like the injected useShape returns).
-// The injected useShape receives `(shapeType, scope)`; we ignore both and return
-// the items array captured by the test through window.__sdk.caps.seedSet().
-let injectedSetItems: any[] = [];
-function fakeUseShape(_shape: unknown, _scope: unknown): any {
-  const items = () => injectedSetItems;
-  return {
-    get size() { return items().length; },
-    [Symbol.iterator]() { return items()[Symbol.iterator](); },
-    forEach(cb: (v: unknown) => void) { items().forEach(cb); },
-    add(item: any) { injectedSetItems.push(item); },
-  };
-}
+// The injected `useShape`, so the lib's read-filtered view can be exercised WITHOUT a
+// React tree. It is `test/use-shape-fake.ts` - the ONE fake in this repository that
+// returns the shape `@ng-org/orm`'s hook really ships, read off the installed package's
+// own `.d.ts`. This page used to carry a hand-written Set-like of its own, which is
+// exactly why the capability filter could hand three members of that envelope back raw
+// and still pass every gate: no fake anywhere said what the hook returns.
+const shapeHook = makeUseShapeHook();
 
 // ── Inject the real SDK + polyfill settings (the consumer bootstrap) ────────
 configure({
   ng: realNg,
-  useShape: fakeUseShape,
+  useShape: shapeHook.hook,
+  // The SDK's own shape query, passed as it stands - no wrapper, no cast. This is what
+  // `useShapeQuery` reads through, so the journeys below run against the REAL broker
+  // rather than against anything this page composed.
+  ormSubscription: RdfOrmSubscription.getOrCreate,
   init: realInit,
+  initNg: ormInitNg,
   // The harness already holds an open wallet (the suite imports it itself), so it never
   // needs the gate's assisted import. These values exist only so the gate has something
   // to render when the access-gate steps exercise it — they are never used to import.
@@ -369,13 +475,16 @@ const identity = new IdentityStore(
     };
   },
 
-  // ── read-model ───────────────────────────────────────────────────────────
+  // ── the anchored document read ───────────────────────────────────────────
   /**
-   * Create N docs, write a marker triple into each (anchored default graph), then
-   * readUnion over them → one subject per doc. Optionally inject a bad NURI to
-   * prove per-doc tolerance (the bad one is skipped, the batch survives).
+   * Create N docs, write a marker triple into each (anchored default graph), then read
+   * them ONE BY ONE with the published anchored query. Optionally inject a bad NURI, to
+   * show where the tolerance lives now: at THIS call site, as a visible `catch`, not
+   * inside a primitive. `readUnion` used to swallow it and answer with the rest, which
+   * is a policy upstream does not have - an anchored query on a repo the verifier does
+   * not know REJECTS (`resolve_target_for_sparql` -> `NgError::RepoNotFound`).
    */
-  async readUnionOverDocs(n: number, includeBad: boolean) {
+  async readDocsOneByOne(n: number, includeBad: boolean) {
     const s = await sessionReady;
     const docNuris: Nuri[] = [];
     for (let i = 0; i < n; i++) {
@@ -388,7 +497,7 @@ const identity = new IdentityStore(
       docNuris.push(d);
     }
     // Two SUBJECTS in the LAST document, so the probe can tell "one entry per document"
-    // from "one entry per subject". Until 2026-08-10 `readUnion` folded every triple of a
+    // from "one entry per subject". Until 2026-08-10 the read folded every triple of a
     // document into one bag keyed by the document, and this step stayed green throughout
     // because it only ever counted entries and never looked at what they were.
     if (n > 0) {
@@ -399,22 +508,36 @@ const identity = new IdentityStore(
       );
     }
     const toRead: Nuri[] = includeBad ? [...docNuris, "did:ng:o:definitely-not-a-real-doc-xyz"] : docNuris;
-    const subjects = await readUnion(toRead);
+    const subjects: Array<{ subject: string; graph: Nuri; props: Record<string, string[]> }> = [];
+    const skipped: string[] = [];
+    for (const d of toRead) {
+      try {
+        subjects.push(...(await readOneDocument(s.session_id, d)));
+      } catch {
+        // THIS harness chooses to carry on. Another caller may choose not to - that is
+        // the point of the decision living here.
+        skipped.push(d);
+      }
+    }
     return {
       docNuris,
       subjectCount: subjects.length,
       // What each entry actually IS — the assertion the count could not make.
       subjectIris: subjects.map((x) => x.subject),
       graphs: subjects.map((x) => x.graph),
+      skipped,
       subjects,
     };
   },
   /**
-   * readUnion possession gate: create a doc as owner O (whose keyring gets its
-   * cap), then read it as a DIFFERENT identity, which holds nothing → dropped.
-   * The stranger has the document's NURI in hand throughout: naming is not reading.
+   * The possession gate on the anchored read: create a doc as owner O (whose keyring
+   * gets its cap), then read it as a DIFFERENT identity, which holds nothing. The
+   * stranger has the document's NURI in hand throughout: naming is not reading.
+   *
+   * The stranger is now REFUSED rather than handed an empty list - `readUnion` dropped
+   * an unreachable document from its batch, and there is no batch to drop it from.
    */
-  async readUnionCapGate() {
+  async anchoredReadCapGate() {
     const s = await sessionReady;
     resetCaps();
     const doc = await docs.docCreate(s.session_id, "Graph", "data:graph", "store", undefined);
@@ -422,12 +545,18 @@ const identity = new IdentityStore(
     setCurrentUser("owner-O");
     getCaps().open(doc, "protected");
     setCurrentUser("someone-else");
-    const asStranger = await readUnion([doc]);
+    let strangerRefused = false;
+    let strangerCount = -1;
+    try {
+      strangerCount = (await readOneDocument(s.session_id, doc)).length;
+    } catch {
+      strangerRefused = true;
+    }
     setCurrentUser("owner-O");
-    const asOwner = await readUnion([doc]);
+    const asOwner = await readOneDocument(s.session_id, doc);
     resetCaps();
     setCurrentUser(null);
-    return { strangerCount: asStranger.length, ownerCount: asOwner.length };
+    return { strangerRefused, strangerCount, ownerCount: asOwner.length };
   },
 
   // ── reactivity (doc_subscribe) ───────────────────────────────────────────
@@ -575,16 +704,16 @@ const identity = new IdentityStore(
     // and the caps of what you create are filed under the identity you were acting
     // as. Creating B's document while connected as A is not a thing the model has.
     setCurrentUser(idA);
-    const dA1 = await storeRegistry.createEntityDoc("public");
-    const dA2 = await storeRegistry.createEntityDoc("public");
+    const dA1 = await storeRegistry.createEntityDoc(await storeRegistry.publicStore());
+    const dA2 = await storeRegistry.createEntityDoc(await storeRegistry.publicStore());
     setCurrentUser(idB);
-    const dB1 = await storeRegistry.createEntityDoc("public");
+    const dB1 = await storeRegistry.createEntityDoc(await storeRegistry.publicStore());
     // listMyEntityDocs(A) → only A's docs (poll: the index append can lag).
     setCurrentUser(idA);
     let listA: string[] = [];
     for (let i = 0; i < 12; i++) {
       registryInternals.resetRegistryCache();
-      listA = await storeRegistry.listMyEntityDocs("public");
+      listA = await registryInternals.listMyEntityDocs(idA, "public");
       if (listA.includes(dA1) && listA.includes(dA2)) break;
       await new Promise((r) => setTimeout(r, 1000));
     }
@@ -616,7 +745,7 @@ const identity = new IdentityStore(
     // document is filed under nobody and the very session that created it is
     // refused the write below.
     setCurrentUser(id);
-    const entityNuri = await storeRegistry.createEntityDoc(scope);
+    const entityNuri = await storeRegistry.createEntityDoc(await storeOfType(scope));
     const marker = "recon-" + Date.now();
     await docs.sparqlUpdate(
       s.session_id,
@@ -629,7 +758,7 @@ const identity = new IdentityStore(
     let listed: string[] = [];
     for (let i = 0; i < 15; i++) {
       registryInternals.resetRegistryCache();
-      listed = await storeRegistry.listMyEntityDocs(scope);
+      listed = await registryInternals.listMyEntityDocs(id, scope);
       if (listed.includes(entityNuri)) break;
       await new Promise((r) => setTimeout(r, 1000));
     }
@@ -638,9 +767,9 @@ const identity = new IdentityStore(
   /**
    * RECONNECTION read (phase 2, run in a FRESH session over the SAME wallet). First a
    * DIAGNOSTIC raw anchored read with NO open (rawRowCount), then re-resolve the
-   * account's entity docs of `scope` (listMyEntityDocs → readUserStore) and readUnion
-   * them, purely from the persistent wallet — nothing from phase 1's session state
-   * carries over. The SDK's open-before-read heal (open-repo.ts) opens each repo via
+   * account's entity docs of `scope` (listMyEntityDocs → readUserStore) and read each
+   * with its own anchored query, purely from the persistent wallet — nothing from
+   * phase 1's session state carries over. The SDK's open-before-read heal (open-repo.ts) opens each repo via
    * doc_subscribe before the anchored reads. NB: on the SDK/broker version tested here
    * the broker-login bootstrap already opens the user's repos, so rawRowCount is
    * non-zero even without the heal — this is a reconnection REGRESSION guard, not a
@@ -655,11 +784,11 @@ const identity = new IdentityStore(
     await connectedUser();
 
     registryInternals.resetRegistryCache();
-    const listed = await storeRegistry.listMyEntityDocs(scope);
+    const listed = await registryInternals.listMyEntityDocs(id, scope);
     // DIAGNOSTIC: a RAW anchored read of the entity doc with NO open — reports how
     // many rows the bare anchored query resolves for a not-yet-opened repo (the
     // premise: 0 until opened). Uses the low-level docs primitive directly, bypassing
-    // readUnion's open step.
+    // `readOneDocument`'s open step.
     //
     // Placed AFTER `listMyEntityDocs`, which is what restores the caps of the user's
     // own documents from the Store branch. Before it, the boundary refuses the read
@@ -672,7 +801,18 @@ const identity = new IdentityStore(
     } catch (e: any) {
       rawRowCount = -2; // threw (e.g. RepoNotFound / InvalidNuri)
     }
-    const subjects = await readUnion(listed.length ? listed : [asNuri(entityNuri)]);
+    // One anchored read per listed document, and the tolerance is HERE, visibly: a
+    // reconnect probe that lost one document to a broker hiccup still reports what the
+    // others held, because THIS caller decided so. The primitive rejects.
+    const subjects: Array<{ subject: string; graph: Nuri; props: Record<string, string[]> }> = [];
+    const unread: string[] = [];
+    for (const d of listed.length ? listed : [asNuri(entityNuri)]) {
+      try {
+        subjects.push(...(await readOneDocument(s.session_id, d)));
+      } catch {
+        unread.push(d);
+      }
+    }
     const markers: string[] = [];
     for (const subj of subjects) {
       for (const vals of Object.values(subj.props)) {
@@ -685,6 +825,7 @@ const identity = new IdentityStore(
       listedCount: listed.length,
       foundEntity: listed.includes(asNuri(entityNuri)),
       subjectCount: subjects.length,
+      unread,
       markerPresent: markers.includes(marker),
       markers,
     };
@@ -703,10 +844,14 @@ const identity = new IdentityStore(
     const rec = await registryInternals.ensureAccount(id);
     return { docPublic: rec.docPublic, docProtected: rec.docProtected, docPrivate: rec.docPrivate };
   },
+  // `resolveScopeGraph` stopped being published in `1.0.0-dev.5` — a store's graph holds
+  // its containment triples and nothing else, so the value it handed out matched nothing
+  // as a read scope upstream. The probe keeps measuring the mapping, at its internal path:
+  // a harness may do that, an application may not.
   async scopeResolvers() {
-    const priv = await storeRegistry.resolveScopeGraph("private");
-    const prot = await storeRegistry.resolveScopeGraph("protected");
-    const pub = await storeRegistry.resolveScopeGraph("public");
+    const priv = await registryInternals.resolveScopeGraph("private");
+    const prot = await registryInternals.resolveScopeGraph("protected");
+    const pub = await registryInternals.resolveScopeGraph("public");
     return { priv, prot, pub };
   },
 
@@ -771,27 +916,27 @@ const identity = new IdentityStore(
     }
   },
 
-  // ── watchShape (reactive useQuery-shaped read) ───────────────────────────
-  // A minimal SHEX-ish ShapeType pinning rdf:type to an e2e class IRI. watchShape
-  // reads only `.shape`/`.schema[...].predicates[rdf:type].dataTypes[].literals`
-  // to know which @type to keep — generic, no application domain.
+  // ── useShapeQuery (reactive useQuery-shaped read) ────────────────────────
+  // The shape is `wsShape(cls)` above: a hand-written `ShapeType`, two required
+  // predicates, generic and with no application domain. The read goes through the
+  // SDK's own shape query now, so these two journeys measure the REAL broker.
   _wsProbes: {} as Record<
     string,
     { obs: ShapeObservable; initial: ShapeQuery; unsub: () => void }
   >,
   /**
    * REAL-BROKER cycle proof. Under a fresh identity, create ONE protected entity
-   * document carrying an rdf:type=<e2e class> triple, then open a `watchShape` over
-   * (that class shape, "protected"). Capture the FIRST snapshot right after subscribe
+   * document carrying an rdf:type=<e2e class> triple, then open a `useShapeQuery` over
+   * (that class shape, the whole dataset). Capture the FIRST snapshot right after subscribe
    * (must be isPending) so the caller can then wait event-driven for isSuccess with
    * the seeded datum present. Returns the handle + the initial snapshot + the seed
    * doc/type so the runner can assert the data landed.
    */
-  async watchShapeSeedAndSubscribe(handle: string, cls: string) {
+  async useShapeQuerySeedAndSubscribe(handle: string, cls: string) {
     registryInternals.resetRegistryCache();
     const id = "@ws-" + handle;
     setCurrentUser(id);
-    const doc = await storeRegistry.createEntityDoc("protected");
+    const doc = await storeRegistry.createEntityDoc(await storeRegistry.protectedStore());
     const s = await sessionReady;
     // Seed the entity doc with the shape's type + a title (anchored default graph).
     await docs.sparqlUpdate(
@@ -802,40 +947,24 @@ const identity = new IdentityStore(
     // Wait until this session sees the index append (data persisted on the broker).
     for (let i = 0; i < 15; i++) {
       registryInternals.resetRegistryCache();
-      const listed = await storeRegistry.listMyEntityDocs("protected");
+      const listed = await registryInternals.listMyEntityDocs(id, "protected");
       if (listed.includes(doc)) break;
       await new Promise((r) => setTimeout(r, 1000));
     }
-    const shape = {
-      shape: "urn:e2e:ws:Shape",
-      schema: {
-        "urn:e2e:ws:Shape": {
-          iri: "urn:e2e:ws:Shape",
-          predicates: [
-            {
-              iri: "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
-              readablePredicate: "type",
-              maxCardinality: 1,
-              minCardinality: 1,
-              dataTypes: [{ literals: [cls], valType: "iri" }],
-            },
-          ],
-        },
-      },
-    };
-    const obs = watchShape(shape, "protected") as ShapeObservable;
+    const shape = wsShape(cls);
+    const obs = useShapeQuery(shape, EVERYTHING) as ShapeObservable;
     const unsub = obs.subscribe(() => {});
     // First snapshot immediately after subscribe — the barrier is not yet crossed
     // (docs opening via doc_subscribe), so this MUST be pending.
     const initial = obs.getSnapshot();
     (window as any).__sdk._wsProbes[handle] = { obs, initial, unsub };
-    // NB: leave the current user SET for the probe's lifetime — watchShape resolves
+    // NB: leave the current user SET for the probe's lifetime — useShapeQuery resolves
     // the scope from getCurrentUser() on every (reactive) refresh, exactly as the app
-    // keeps a stable identity. watchShapeStop clears it.
+    // keeps a stable identity. useShapeQueryStop clears it.
     return { doc, cls, initial: { isPending: initial.isPending, isSuccess: initial.isSuccess, dataLen: initial.data.length } };
   },
-  /** Current snapshot of a watchShape probe (event-driven poll target). */
-  watchShapeSnapshot(handle: string) {
+  /** Current snapshot of a useShapeQuery probe (event-driven poll target). */
+  useShapeQuerySnapshot(handle: string) {
     const rec = (window as any).__sdk._wsProbes[handle];
     if (!rec) return null;
     const snap: ShapeQuery = rec.obs.getSnapshot();
@@ -844,46 +973,99 @@ const identity = new IdentityStore(
       isSuccess: snap.isSuccess,
       isError: snap.isError,
       dataLen: snap.data.length,
-      // The seeded title, if the datum is present (proves the real data landed).
-      titles: snap.data.flatMap((d: any) => d.props?.["urn:e2e:ws:title"] ?? []),
+      // The seeded title, if the datum is present (proves the real data landed). It is the
+      // shape's own readable predicate now, not a property bag: the objects come from the
+      // ORM.
+      titles: snap.data.map((d) => d.title).filter((v) => typeof v === "string"),
     };
   },
-  watchShapeStop(handle: string) {
+  useShapeQueryStop(handle: string) {
     const rec = (window as any).__sdk._wsProbes[handle];
     if (rec) rec.unsub();
     setCurrentUser(null);
   },
   /**
-   * EMPTY-scope proof: a brand-new identity with NO entity docs of `scope`. watchShape
-   * must reach isSuccess with data:[] (synced-but-empty), NOT stay pending. Returns
-   * the handle; poll watchShapeSnapshot for the transition.
+   * NAMED-SCOPE seed. Under a fresh identity, create TWO entity documents carrying the
+   * shape's type - one PROTECTED, one PUBLIC - and seed each with a distinguishable
+   * title. Returns the owner and both references, which is all any of the three named
+   * subscriptions below is given.
+   *
+   * Why this exists at all: until `1.0.0-dev.9` every `useShapeQuery` journey in this
+   * suite read `{ graphs: "did:ng:i" }`, so the scope axis that NAMES a document was
+   * measured nowhere against the real broker - and the barrier that names introduced
+   * shipped with no live coverage. A suite that is green on a path it never walks is
+   * worse than one that is red.
    */
-  watchShapeEmptyStart(handle: string, cls: string) {
+  async useShapeQueryNamedSeed(cls: string) {
     registryInternals.resetRegistryCache();
-    const id = "@ws-empty-" + handle;
-    setCurrentUser(id);
-    const shape = {
-      shape: "urn:e2e:ws:Shape",
-      schema: {
-        "urn:e2e:ws:Shape": {
-          iri: "urn:e2e:ws:Shape",
-          predicates: [
-            {
-              iri: "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
-              readablePredicate: "type",
-              maxCardinality: 1,
-              minCardinality: 1,
-              dataTypes: [{ literals: [cls], valType: "iri" }],
-            },
-          ],
-        },
-      },
-    };
-    const obs = watchShape(shape, "protected") as ShapeObservable;
+    const owner = "@wsn-" + Date.now();
+    setCurrentUser(owner);
+    const s = await sessionReady;
+    const prot = await storeRegistry.createEntityDoc(await storeRegistry.protectedStore());
+    await docs.sparqlUpdate(
+      s.session_id,
+      `INSERT DATA { <${prot}> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <${cls}> ; <urn:e2e:ws:title> "named-protected" }`,
+      prot,
+    );
+    // PUBLIC, so its ReadCap is exposed on its Header branch at creation - the one
+    // channel by which a bare reference alone opens a document, and the acquisition the
+    // barrier now performs on this call.
+    const pub = await storeRegistry.createEntityDoc(await storeRegistry.publicStore());
+    await docs.sparqlUpdate(
+      s.session_id,
+      `INSERT DATA { <${pub}> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <${cls}> ; <urn:e2e:ws:title> "named-public" }`,
+      pub,
+    );
+    setCurrentUser(null);
+    return { owner, prot, pub };
+  },
+  /**
+   * Subscribe a NAMED scope under `who` - the owner, or somebody holding nothing.
+   *
+   * The identity is set here and left set for the probe's lifetime, like the two
+   * journeys above: `useShapeQuery` asks the keyring about whoever is connected on every
+   * read, exactly as an application with one stable identity per page does.
+   * `useShapeQuerySnapshot` and `useShapeQueryStop` serve this probe too.
+   */
+  useShapeQueryNamedSubscribe(handle: string, who: string, doc: string, cls: string) {
+    registryInternals.resetRegistryCache();
+    setCurrentUser(who);
+    const obs = useShapeQuery(wsShape(cls), { graphs: [doc] }) as ShapeObservable;
     const unsub = obs.subscribe(() => {});
     const initial = obs.getSnapshot();
     (window as any).__sdk._wsProbes[handle] = { obs, initial, unsub };
-    // Keep the identity set for the probe's lifetime (watchShapeStop clears it): a
+    return {
+      initial: {
+        isPending: initial.isPending,
+        isSuccess: initial.isSuccess,
+        isError: initial.isError,
+      },
+    };
+  },
+  /** The error message a named scope published, so the runner can tell the refusal from
+   *  any other failure rather than accepting `isError` as such. */
+  useShapeQueryError(handle: string) {
+    const rec = (window as any).__sdk._wsProbes[handle];
+    if (!rec) return null;
+    const snap: ShapeQuery = rec.obs.getSnapshot();
+    return snap.error === undefined ? null : String((snap.error as Error)?.message ?? snap.error);
+  },
+
+  /**
+   * EMPTY-scope proof: a brand-new identity with NO entity docs at all. `useShapeQuery`
+   * must reach isSuccess with data:[] (synced-but-empty), NOT stay pending. Returns
+   * the handle; poll useShapeQuerySnapshot for the transition.
+   */
+  useShapeQueryEmptyStart(handle: string, cls: string) {
+    registryInternals.resetRegistryCache();
+    const id = "@ws-empty-" + handle;
+    setCurrentUser(id);
+    const shape = wsShape(cls);
+    const obs = useShapeQuery(shape, EVERYTHING) as ShapeObservable;
+    const unsub = obs.subscribe(() => {});
+    const initial = obs.getSnapshot();
+    (window as any).__sdk._wsProbes[handle] = { obs, initial, unsub };
+    // Keep the identity set for the probe's lifetime (useShapeQueryStop clears it): a
     // faithful "empty scope for a real identity", not "no identity at all".
     return { initial: { isPending: initial.isPending, isSuccess: initial.isSuccess } };
   },
@@ -896,26 +1078,44 @@ const identity = new IdentityStore(
   // cap-surface is KEY POSSESSION — you read what your keyring holds, nothing else.
   capsReadFilter() {
     resetCaps();
-    injectedSetItems = [
+    shapeHook.items.length = 0;
+    shapeHook.items.push(
       { "@graph": "did:ng:o:protdoc", "@id": "1", v: "protected-item" },
       { "@graph": "did:ng:o:pubdoc", "@id": "2", v: "public-item" },
       { "@graph": "did:ng:o:unheld", "@id": "3", v: "unheld-item" },
-    ];
+    );
+    // What the hook hands back is the SDK's result envelope, so the items are read off
+    // `data` - the member its own example destructures first, and one of the three that
+    // used to come back unfiltered.
+    const read = (): string[] =>
+      [
+        ...(libUseShape(wsShape("urn:e2e:caps:Item"), EVERYTHING).data as Iterable<
+          { v: string }
+        >),
+      ].map((i) => i.v);
     setCurrentUser("owner-O");
     getCaps().open("did:ng:o:protdoc", "protected");
     const link = getCaps().open("did:ng:o:pubdoc", "public");
-    const ownerView = [...(libUseShape(null, null) as Iterable<any>)].map((i) => i.v);
+    const ownerView = read();
     // A stranger holds nothing, and this VIEW asks nobody: it is pure possession, with
     // no round-trip to spend (see `read-filter.ts`). That a public store would serve
     // the cap is proven on the read paths, not here.
     setCurrentUser("stranger");
-    const strangerView = [...(libUseShape(null, null) as Iterable<any>)].map((i) => i.v);
+    const strangerView = read();
+    // and the SDK's own handle is refused outright, whoever asks: it reads and writes
+    // with no capability filter at all.
+    let subscriptionRefused: string | null = null;
+    try {
+      void libUseShape(wsShape("urn:e2e:caps:Item"), EVERYTHING).subscription;
+    } catch (e) {
+      subscriptionRefused = e instanceof Error ? e.message : String(e);
+    }
     getCaps().learn(link);
-    const strangerWithLinkView = [...(libUseShape(null, null) as Iterable<any>)].map((i) => i.v);
+    const strangerWithLinkView = read();
     resetCaps();
-    injectedSetItems = [];
+    shapeHook.items.length = 0;
     setCurrentUser(null);
-    return { ownerView, strangerView, strangerWithLinkView };
+    return { ownerView, strangerView, strangerWithLinkView, subscriptionRefused };
   },
   // MOVED to the applicative suite, `e2e/notebook.ts` (2026-08-07):
   //   - `documentInboxDeposit` → "Bob leaves a message on Alice's note, and only Alice
@@ -1083,6 +1283,18 @@ const identity = new IdentityStore(
       (event: { session: BrokerSession }) => {
         session = event.session;
         state.status = "connected";
+        // The ORM reaches the SDK through a module-level promise of its own, resolved
+        // once. Nothing it opens starts before this, so it goes here rather than beside
+        // the first read - through the PACKAGE's `initNg`, which is the call an
+        // application makes.
+        //
+        // Since `1.0.0-dev.7` that call SUBSTITUTES the package's wrapped `ng` for the
+        // one passed here, so the two `useShapeQuery` journeys below are now the proof
+        // that `orm_start_graph` survives the wrapper - and they are the only thing that
+        // is. A consumer wiring exactly this path got `orm_start_graph is not a function`
+        // and a read pending for ever, while this suite stayed green precisely because
+        // the ORM had been handed the raw SDK object here instead.
+        initNg(realNg, session);
         sessionResolve(session);
       },
       true,

packages/polyfill/e2e/run.ts

@@ -259,13 +259,13 @@ async function main(): Promise<void> {
       );
     });
 
-    // ── read-model ──────────────────────────────────────────────────────────
-    console.log("\n── read-model ──");
-    await step("readUnion returns one entry per SUBJECT, with the subject it was written under", async () => {
+    // ── the anchored document read ──────────────────────────────────────────
+    console.log("\n── the anchored document read ──");
+    await step("an anchored read returns one entry per SUBJECT, with the subject it was written under", async () => {
       // 3 documents, and the last carries TWO subjects → 4 entries, not 3. Counting alone
       // could not distinguish grouping-by-document from grouping-by-subject, which is why
-      // this step stayed green while `readUnion` conflated them (fixed 2026-08-10).
-      const r = await sdk<any>(frame, "readUnionOverDocs", 3, false);
+      // this step stayed green while the read conflated them (fixed 2026-08-10).
+      const r = await sdk<any>(frame, "readDocsOneByOne", 3, false);
       const iris: string[] = r.subjectIris ?? [];
       check(
         "one entry per subject, not per document",
@@ -283,14 +283,26 @@ async function main(): Promise<void> {
         JSON.stringify(r.graphs),
       );
     });
-    await step("readUnion per-doc tolerance (bad NURI skipped)", async () => {
-      const r = await sdk<any>(frame, "readUnionOverDocs", 2, true);
-      // 2 documents, the last carrying two subjects → 3 entries.
-      check("bad NURI does not abort the batch", r.subjectCount === 3, `entries=${r.subjectCount}/3 (+1 bad NURI)`);
+    await step("a document that cannot be read REJECTS, and the caller decides to carry on", async () => {
+      const r = await sdk<any>(frame, "readDocsOneByOne", 2, true);
+      // 2 documents, the last carrying two subjects → 3 entries. The bad NURI did not
+      // reduce that, and it is named in `skipped` — the tolerance is the harness's own
+      // `catch`, not a policy hidden in a primitive (`readUnion` carried one until
+      // `1.0.0-dev.8`; upstream an unknown repo rejects, so there was nothing to align it on).
+      check("the readable documents still answer", r.subjectCount === 3, `entries=${r.subjectCount}/3 (+1 bad NURI)`);
+      check(
+        "the unreadable one is REPORTED as skipped, not silently absent",
+        (r.skipped ?? []).length === 1,
+        `skipped=${JSON.stringify(r.skipped)}`,
+      );
     });
-    await step("readUnion cap gate", async () => {
-      const r = await sdk<any>(frame, "readUnionCapGate");
-      check("cap gate drops doc for stranger, keeps for owner", r.strangerCount === 0 && r.ownerCount === 1, `stranger=${r.strangerCount} owner=${r.ownerCount}`);
+    await step("anchored read cap gate", async () => {
+      const r = await sdk<any>(frame, "anchoredReadCapGate");
+      check(
+        "cap gate REFUSES the stranger, and the owner reads",
+        r.strangerRefused === true && r.ownerCount === 1,
+        `strangerRefused=${r.strangerRefused} strangerCount=${r.strangerCount} owner=${r.ownerCount}`,
+      );
     });
 
     // ── reactivity (doc_subscribe) ──────────────────────────────────────────
@@ -386,45 +398,135 @@ async function main(): Promise<void> {
       check("scope resolvers return NURIs (private distinct from protected/public)", !!r.priv && !!r.prot && !!r.pub && r.priv !== r.prot, `priv=${r.priv?.slice(0,16)}… prot=${r.prot?.slice(0,16)}…`);
     });
 
-    // ── watchShape (reactive useQuery-shaped read) ──────────────────────────
-    // The real cycle: first subscription reads isPending (barrier not yet crossed),
-    // then after the broker sync it reaches isSuccess with the seeded datum present.
-    // A separate empty scope reaches isSuccess with data:[] (synced-but-empty — the
-    // distinction useShape's upgrade will make native, surfaced here from getSyncState).
-    console.log("\n── watchShape (reactive useQuery-shaped read) ──");
-    await step("watchShape: first subscribe isPending → isSuccess with data present", async () => {
+    // ── useShapeQuery (reactive useQuery-shaped read) ───────────────────────
+    // The real cycle, through the SDK's own shape query since `1.0.0-dev.6`: the first
+    // subscription reads isPending (the ORM's initial payload has not arrived), then the
+    // broker answers and it reaches isSuccess with the seeded datum present. A separate
+    // identity with nothing of that shape reaches isSuccess with data:[] - which over
+    // `did:ng:i` is the CAPABILITY FILTER doing the bounding, since the engine adds nothing
+    // to narrow the whole dataset by what the reader may open.
+    console.log("\n── useShapeQuery (reactive useQuery-shaped read) ──");
+    await step("useShapeQuery: first subscribe isPending → isSuccess with data present", async () => {
       const h = "cyc" + Date.now();
       const CLS = "urn:e2e:ws:Event";
-      const seed = await sdk<any>(frame, "watchShapeSeedAndSubscribe", h, CLS);
-      check("first snapshot after subscribe is isPending (barrier not crossed)", seed.initial.isPending === true && seed.initial.isSuccess === false, `initial=${JSON.stringify(seed.initial)}`);
+      const seed = await sdk<any>(frame, "useShapeQuerySeedAndSubscribe", h, CLS);
+      check("first snapshot after subscribe is isPending (no initial payload yet)", seed.initial.isPending === true && seed.initial.isSuccess === false, `initial=${JSON.stringify(seed.initial)}`);
       // Event-driven: wait for the barrier to cross + the datum to land.
       await frame.waitForFunction(
         (hh) => {
-          const s = (window as any).__sdk.watchShapeSnapshot(hh as string);
+          const s = (window as any).__sdk.useShapeQuerySnapshot(hh as string);
           return s && s.isSuccess && s.dataLen >= 1;
         },
         h,
         { timeout: 30000 },
       );
-      const snap = await sdkGet<any>(frame, "watchShapeSnapshot", h);
+      const snap = await sdkGet<any>(frame, "useShapeQuerySnapshot", h);
       check("reaches isSuccess with the seeded datum (titles include 'seeded')", snap.isSuccess && !snap.isPending && !snap.isError && snap.dataLen >= 1 && snap.titles.includes("seeded"), `snap=${JSON.stringify(snap)}`);
-      await sdk(frame, "watchShapeStop", h);
+      await sdk(frame, "useShapeQueryStop", h);
     });
-    await step("watchShape: empty scope reaches isSuccess with data:[]", async () => {
+    await step("useShapeQuery: empty scope reaches isSuccess with data:[]", async () => {
       const h = "empty" + Date.now();
       const CLS = "urn:e2e:ws:Event";
-      await sdk<any>(frame, "watchShapeEmptyStart", h, CLS);
+      await sdk<any>(frame, "useShapeQueryEmptyStart", h, CLS);
       await frame.waitForFunction(
         (hh) => {
-          const s = (window as any).__sdk.watchShapeSnapshot(hh as string);
+          const s = (window as any).__sdk.useShapeQuerySnapshot(hh as string);
           return s && s.isSuccess;
         },
         h,
         { timeout: 30000 },
       );
-      const snap = await sdkGet<any>(frame, "watchShapeSnapshot", h);
-      check("empty scope: isSuccess, data:[] (synced-but-empty, not stuck pending)", snap.isSuccess && !snap.isPending && !snap.isError && snap.dataLen === 0, `snap=${JSON.stringify(snap)}`);
-      await sdk(frame, "watchShapeStop", h);
+      const snap = await sdkGet<any>(frame, "useShapeQuerySnapshot", h);
+      check("nothing of that shape: isSuccess, data:[] (answered-and-empty, not stuck pending)", snap.isSuccess && !snap.isPending && !snap.isError && snap.dataLen === 0, `snap=${JSON.stringify(snap)}`);
+      await sdk(frame, "useShapeQueryStop", h);
+    });
+
+    // The NAMED half of the scope axis, which this suite did not walk until
+    // `1.0.0-dev.9` - both journeys above read `{ graphs: "did:ng:i" }`, so the barrier
+    // that `useShapeQuery` now crosses for every document a scope NAMES had no live
+    // coverage at all. Three readings of the same two documents, one per outcome: the
+    // owner reads hers, somebody holding nothing is REFUSED rather than told the
+    // document is empty, and the same somebody opens the PUBLIC one from nothing but its
+    // reference - which is the barrier's own fetch reaching this broker.
+    await step("useShapeQuery: a NAMED scope reads, refuses, and opens a public document from a bare reference", async () => {
+      const CLS = "urn:e2e:ws:Event";
+      const seed = await sdk<any>(frame, "useShapeQueryNamedSeed", CLS);
+      const stranger = "@wsn-stranger-" + Date.now();
+
+      const own = "named-own" + Date.now();
+      await sdk<any>(frame, "useShapeQueryNamedSubscribe", own, seed.owner, seed.prot, CLS);
+      await frame.waitForFunction(
+        (hh) => {
+          const s = (window as any).__sdk.useShapeQuerySnapshot(hh as string);
+          return s && (s.isSuccess || s.isError);
+        },
+        own,
+        { timeout: 30000 },
+      );
+      const ownSnap = await sdkGet<any>(frame, "useShapeQuerySnapshot", own);
+      check(
+        "the owner naming her own document reads it (the barrier does not break a live named read)",
+        ownSnap.isSuccess && !ownSnap.isError && ownSnap.titles.includes("named-protected"),
+        `snap=${JSON.stringify(ownSnap)}`,
+      );
+      await sdk(frame, "useShapeQueryStop", own);
+
+      const refused = "named-refused" + Date.now();
+      await sdk<any>(frame, "useShapeQueryNamedSubscribe", refused, stranger, seed.prot, CLS);
+      await frame.waitForFunction(
+        (hh) => {
+          const s = (window as any).__sdk.useShapeQuerySnapshot(hh as string);
+          return s && (s.isSuccess || s.isError);
+        },
+        refused,
+        { timeout: 30000 },
+      );
+      const refusedSnap = await sdkGet<any>(frame, "useShapeQuerySnapshot", refused);
+      const refusedWhy = await sdkGet<any>(frame, "useShapeQueryError", refused);
+      // The whole point of the change: NOT `isSuccess` with `data: []`, which is what
+      // this same call published before `1.0.0-dev.9` - the capability filter emptied
+      // the result and the snapshot said the document holds nothing of that shape.
+      check(
+        "a named document the holder cannot reach is isError, never an empty success",
+        refusedSnap.isError && !refusedSnap.isSuccess && refusedSnap.dataLen === 0 &&
+          typeof refusedWhy === "string" && refusedWhy.includes("does not hold this document"),
+        `snap=${JSON.stringify(refusedSnap)} why=${String(refusedWhy).slice(0, 80)}`,
+      );
+      // Left OPEN on purpose for the last reading below: a refused scope standing while
+      // a cap for some OTHER document lands is exactly what the keyring signal must not
+      // act on. (`useShapeQueryStop` would also clear the identity, which is why it is
+      // not called here - the next subscribe is the SAME holder.)
+
+      const publicRef = "named-public" + Date.now();
+      await sdk<any>(frame, "useShapeQueryNamedSubscribe", publicRef, stranger, seed.pub, CLS);
+      await frame.waitForFunction(
+        (hh) => {
+          const s = (window as any).__sdk.useShapeQuerySnapshot(hh as string);
+          return s && (s.isSuccess || s.isError);
+        },
+        publicRef,
+        { timeout: 30000 },
+      );
+      const publicSnap = await sdkGet<any>(frame, "useShapeQuerySnapshot", publicRef);
+      // The acquisition the barrier newly performs on this call: the same identity that
+      // was just refused the protected document opens the public one holding nothing but
+      // its reference, because the barrier asks the public store and this broker answers.
+      check(
+        "a public document named by a holder of nothing opens, through the barrier's own fetch",
+        publicSnap.isSuccess && !publicSnap.isError && publicSnap.titles.includes("named-public"),
+        `snap=${JSON.stringify(publicSnap)}`,
+      );
+
+      // A fourth check stood here until 2026-09-21: "a cap landing for ANOTHER document
+      // leaves a refused scope refused". It was REMOVED rather than repaired, because it
+      // passed with the whole re-attempt machinery deleted - the outcome is a standing
+      // refusal either way, so nothing it could observe told the two apart. A check that
+      // cannot fail for any regression of the thing it guards is worse than no check: it
+      // reads as coverage. The re-attempt is measured in `test/use-shape-query.test.ts`
+      // - (v) for the class repaired by re-asking the network, (s) for the one that is
+      // not and for what a doomed re-attempt costs, (w) for the holder it is made as.
+      await sdk(frame, "useShapeQueryStop", refused);
+      await sdk(frame, "useShapeQueryStop", publicRef);
     });
 
     // ── caps / read-filter (in-memory cap model) ────────────────────────────
@@ -446,6 +548,16 @@ async function main(): Promise<void> {
         ownerReadsHeld && ownerMissesUnheld && strangerReadsNothing && linkOpensPublic,
         `owner=${JSON.stringify(r.ownerView)} stranger=${JSON.stringify(r.strangerView)} withCap=${JSON.stringify(r.strangerWithLinkView)}`,
       );
+      // The three views above are read off `data`, one of the three members of the SDK's
+      // result envelope that carry the items. The fourth way in is the ORM's own handle,
+      // which reads and writes with no capability filter at all, so it is refused rather
+      // than handed on, and that refusal is checked here rather than assumed.
+      check(
+        "the read-filtered view refuses the ORM's own subscription handle",
+        typeof r.subscriptionRefused === "string" &&
+          r.subscriptionRefused.includes("RdfOrmSubscription"),
+        `subscription=${JSON.stringify(r.subscriptionRefused)}`,
+      );
     });
     // MOVED to the applicative suite (`e2e/notebook.ts`, "Alice's protected note stays
     // shut until she gives Bob the key"): sharing is a journey, and it is worth more
@@ -542,7 +654,7 @@ async function main(): Promise<void> {
     // session must relist + re-read its OWN persisted markers, POLLING for the sync —
     // the wait IS the normal path. NB the observed cost is dominated by broker READ
     // latency, not pure sync-lag: ONE reconnectRead cycle (open-repo heal awaits the
-    // initial-state push per repo + anti-fork retry budget + anchored readUnion, all
+    // initial-state push per repo + anti-fork retry budget + the anchored reads, all
     // round-tripping the real broker) measures ~90-105s. So the poll deadline is a
     // generous MULTI-cycle bound (120s past post-connect) rather than a tight 30s — a
     // single slow cycle must not be mistaken for a sync failure. We report the observed

packages/polyfill/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ng-eventually/polyfill",
-  "version": "1.0.0-dev.3",
+  "version": "1.0.0-dev.16",
   "type": "module",
   "description": "Polyfill of the NextGraph JS SDK over @ng-org/web + @ng-org/orm, with emulated capabilities and inbox. Drop-in; remove at migration.",
   "main": "./src/index.ts",
@@ -9,10 +9,10 @@
     ".": "./src/index.ts"
   },
   "peerDependencies": {
-    "@ng-org/web": "*",
-    "@ng-org/orm": "*",
-    "@ng-org/shex-orm": "*",
-    "@ng-org/alien-deepsignals": "*"
+    "@ng-org/web": ">=0.1.2-alpha.14 <0.1.2",
+    "@ng-org/orm": ">=0.1.2-alpha.21 <0.1.2",
+    "@ng-org/shex-orm": ">=0.1.2-alpha.9 <0.1.2",
+    "@ng-org/alien-deepsignals": ">=0.1.2-alpha.13 <0.1.2"
   },
   "peerDependenciesMeta": {
     "@ng-org/web": {
@@ -29,9 +29,11 @@
     }
   },
   "devDependencies": {
-    "@ng-org/web": "0.1.2-alpha.13",
-    "@ng-org/shex-orm": "0.1.2-alpha.8",
-    "@ng-org/alien-deepsignals": "0.1.2-alpha.11"
+    "@ng-org/alien-deepsignals": "0.1.2-alpha.13",
+    "@ng-org/orm": "0.1.2-alpha.21",
+    "@ng-org/shex-orm": "0.1.2-alpha.9",
+    "@ng-org/web": "0.1.2-alpha.14",
+    "ng-e2e-helpers": "workspace:*"
   },
   "scripts": {
     "test": "bun test",

packages/polyfill/src/emulated-verifier/branch-registers.ts

@@ -61,7 +61,7 @@ import {
   recordInbox,
   type VirtualUserRecord,
 } from "../shared-wallet/account-registry";
-import type { InboxScope, Nuri, NuriLike, PrincipalId, ReadCap, Scope } from "../model/types";
+import type { InboxScope, Nuri, NuriLike, PrincipalId, ReadCap, StoreType } from "../model/types";
 
 /**
  * Does `nuri` belong to the CURRENT wallet as one of its inboxes? The predicate the
@@ -102,7 +102,7 @@ export async function isOwnInbox(nuri: Nuri): Promise<boolean> {
  * the consumer spells the identity.
  */
 // @provenance holdOwnCap kind=aligned level=1 ref=engine/repo/src/types.rs:AddRepoV0 — the cap of a document you created, filed on the store's Store branch. WIRED upstream — `send_add_repo_to_store` constructs it
-export function holdOwnCap(id: string, scope: Scope, doc: Nuri, cap: ReadCap): void {
+export function holdOwnCap(id: string, scope: StoreType, doc: Nuri, cap: ReadCap): void {
   const holder = getCurrentUser();
   if (holder === null || accountKey(holder) !== accountKey(id)) return;
   const caps = getCaps();
@@ -232,7 +232,8 @@ export async function readStoreCaps(storeDoc: Nuri): Promise<ReadCap[]> {
  * store it was created in ({@link holdOwnCap}) — and until 2026-08-16 exactly one path
  * read it back: `listMyEntityDocs`. So a creator that reloaded the page and went straight
  * to the document it had just made, without listing that scope first, held nothing for it:
- * the read was refused, the batch read (`readUnion`) dropped it silently, and the write
+ * the read was refused, the batch read of the day (`readUnion`, removed in `1.0.0-dev.8`)
+ * dropped it silently, and the write
  * was refused. Its own document, denied to its own author, on the first refresh.
  *
  * Restoring what a user HOLDS is already what connecting means here — that is what the
@@ -301,6 +302,14 @@ export async function restoreOwnCaps(holderKey: string): Promise<void> {
  *
  * **Never creates.** Asking where to deposit must not bring an inbox into existence —
  * only its owner opens one, and only on its own document.
+ *
+ * **`undefined` is an ANSWER, and only an answer** (`1.0.0-dev.9`). It means the document
+ * carries no address - nobody opened an inbox on it - or that it is not this holder's to
+ * see one on. It no longer means "the read did not happen": both routes by which a
+ * breakdown used to arrive here as `undefined` now reject. That mattered because two
+ * published calls turn this value into a statement an application acts on:
+ * `inbox.postToDocument` says "its owner never opened one", and `inbox.readForDocument`
+ * says zero deposits - for a document whose inbox is full.
  */
 // @provenance documentInboxAddress kind=divergent level=1 ref=engine/net/src/types.rs:ContactDetails — the deposit-side half of the same divergence: upstream you are TOLD an address, you never read one off a document
 export async function documentInboxAddress(doc: Nuri): Promise<Nuri | undefined> {
@@ -312,7 +321,9 @@ export async function documentInboxAddress(doc: Nuri): Promise<Nuri | undefined>
   // …but ask the (emulated) network first: a document in a public store serves its cap
   // to whoever asks (public-store.ts), and "where do I deposit for this public
   // document" is exactly the question a third party arrives with, holding nothing but
-  // the reference.
+  // the reference. Its rejection is NOT caught: "the store could not be asked" is not
+  // "this document has no inbox", and the whole value of the answer below is that the
+  // two are told apart.
   await fetchReadCap(doc);
   if (mustNotAttempt(doc)) return undefined;
   const s = await session();
@@ -329,10 +340,17 @@ export async function documentInboxAddress(doc: Nuri): Promise<Nuri | undefined>
       if (a && isNuri(a)) return a;
     }
   } catch (error) {
-    // Unreadable document (no cap) or not synced → no address to give. Refusing to
-    // read is the boundary doing its job, not an error to propagate here.
+    // **Propagates a failed read** (`1.0.0-dev.9`). This used to answer `undefined`, on
+    // the ground that "refusing to read is the boundary doing its job" - but the boundary
+    // has already had its say at `mustNotAttempt` above, which returned before reaching
+    // here. What this catch could still meet is a breakdown: a repo that would not open,
+    // a broker that did not answer, a query that rejected. Answering `undefined` for that
+    // told the caller the document has no inbox, which is the failure-as-absence this
+    // path has paid for before. A caller that genuinely prefers to carry on catches it.
     console.error(accessLogPrefix() + " documentInboxAddress failed:", error);
+    throw error;
   }
+  // No address on the Header branch: nobody opened an inbox on this document. An answer.
   return undefined;
 }
 
@@ -579,8 +597,11 @@ export async function enumerateMyInboxes(): Promise<InboxEnumeration> {
  * upstream an inbox is consumed, and processing a message *applies* it. Applying a
  * Link means writing it here.
  *
- * Idempotent — re-applying the same Link is a no-op, so re-processing an inbox
- * (a second tab, a reconnect) costs nothing.
+ * Idempotent — filing the same Link twice is a no-op. Kept after deposits became consumed
+ * (2026-08-26), because the case it answers was never the replay: the SAME cap legitimately
+ * arrives as two distinct deposits when a document is shared twice or a key is rotated, and
+ * both are consumed and both applied. Without it that user's User branch carries the same
+ * `ng:link` twice.
  *
  * `forHolder` names WHOSE User branch this lands on when it is not the connected
  * identity's — the emulated inbox processor
@@ -598,17 +619,24 @@ export async function addLink(cap: ReadCap, forHolder?: PrincipalId): Promise<vo
   if (!store) return;
   if ((await readLinks(forHolder)).includes(cap)) return;
   const s = await session();
-  try {
-    await registerUpdate(
-      s.sessionId,
-      `INSERT DATA { <${USER_BRANCH_SUBJECT}> <${P.link}> "${escapeLiteral(cap)}" }`,
-      store,
-      "addLink",
-      holderRing(forHolder),
-    );
-  } catch (error) {
-    console.error(accessLogPrefix() + " addLink failed:", error);
-  }
+  // PROPAGATES since 2026-08-26. It used to catch and log, which was survivable only while
+  // nothing was consumed: the deposit stayed, and the next connection filed the cap again.
+  // Now the deposit is popped BEFORE this runs, so a swallowed failure is a cap lost for
+  // good — and worse, `applyLink` went on returning `true`, so the drain's trace counted a
+  // Link it had not filed.
+  //
+  // Its ONE caller does NOT catch, deliberately: most of what happens above this line
+  // (`ensureAccount`, `readLinks`, `session`) is deposit-INDEPENDENT infrastructure that
+  // fails for the whole queue at once, so catching per deposit meant popping and destroying
+  // every remaining one while reporting each. The throw travels to the drain, which reports
+  // the deposit it lost, reports the inbox, and stops — preserving everything not yet taken.
+  await registerUpdate(
+    s.sessionId,
+    `INSERT DATA { <${USER_BRANCH_SUBJECT}> <${P.link}> "${escapeLiteral(cap)}" }`,
+    store,
+    "addLink",
+    holderRing(forHolder),
+  );
 }
 
 /**

packages/polyfill/src/emulated-verifier/caps.ts

@@ -62,7 +62,7 @@
  */
 
 import { CAP_SEGMENT, hasReadCap, targetOf } from "../model/nuri";
-import type { Nuri, PrincipalId, ReadCap, Scope } from "../model/types";
+import type { Nuri, PrincipalId, ReadCap, StoreType } from "../model/types";
 
 /**
  * The stand-in cap value, and the minting point — moved here from `model/nuri.ts`
@@ -330,7 +330,7 @@ export class CapRegistry {
    * Deliberately does NOT touch write caps: those are decorative until cap-enforcement, and
    * arming their guard here would be enforcement this batch does not do.
    */
-  open(nuri: Nuri, scope: Scope): ReadCap {
+  open(nuri: Nuri, scope: StoreType): ReadCap {
     // `file`, NOT `mint` — and the difference is a hole that was open for one commit.
     //
     // Every caller of this method files a STRUCTURAL document: one of the holder's three
@@ -376,7 +376,29 @@ export class CapRegistry {
     };
   }
 
+  /**
+   * How many times this registry has CHANGED - a monotonic counter, bumped wherever
+   * {@link notify} is.
+   *
+   * It exists because a listener is an EDGE and some readers need the LEVEL. A reader
+   * that starts an asynchronous piece of work whose outcome depends on what is held can
+   * sample this before and compare after: a change that landed while the work was in
+   * flight fired its listener when there was nothing yet to act on, so the edge is gone
+   * and only this comparison can recover it. `surface/use-shape-query.ts` is that reader,
+   * and it was stuck exactly there through two rounds of review.
+   *
+   * Cheap, and deliberately not a timestamp: what a caller needs is "did anything move
+   * between these two points", never when or what.
+   */
+  version(): number {
+    return this.changes;
+  }
+
+  /** Bumped on every {@link notify} - see {@link version}. */
+  private changes = 0;
+
   private notify(): void {
+    this.changes += 1;
     for (const l of this.listeners) {
       try {
         l();

packages/polyfill/src/emulated-verifier/connect.ts

@@ -43,7 +43,7 @@
  * code. Making it async would push the wait onto the app, which is exactly the
  * obligation this removes. So the work runs in the background and announces itself
  * through the registry's change signal (`CapRegistry.onChange`), which is what
- * `watchShape` already listens to — a view that was empty for want of a cap
+ * `useShapeQuery` already listens to - a view that was empty for want of a cap
  * re-reads when the cap lands. {@link connectedUser} is there for a caller that
  * genuinely needs to await it (tests, an app that wants a deterministic start).
  *
@@ -82,8 +82,8 @@ import type { Nuri } from "../model/types";
 function reportUndrained(inbox: Nuri, error: unknown): void {
   console.error(
     accessLogPrefix() +
-      " connected, but this queue could not be drained — a share deposited in it is not " +
-      "applied yet, and connecting again will try it again: " +
+      " connected, but this queue could not be drained — whatever it had already taken out " +
+      "is consumed and gone; what is still in it waits for the next attempt: " +
       shortNuri(inbox) +
       ":",
     error,
@@ -120,12 +120,19 @@ const inFlight = new Map<string, Promise<void>>();
  * ── Why a queue is NOT the connection, corrected 2026-08-16 ───────────────
  * This said "there is no third category here" and rejected on an undrained inbox too. The
  * reasoning was that an unapplied share and a lost restore look the same to a person. What
- * it missed is what happens NEXT: an inbox is not consumed by failing, so a queue that
- * cannot be applied is still on the list at the following connection, and the one after
+ * it missed is what happens NEXT. At the time nothing was ever consumed, so a queue that
+ * could not be applied was still on the list at the following connection, and the one after
  * that. One unapplicable item therefore did not delay a share — it **locked the person out
  * of the application, permanently**, and got worse rather than better with time. Reported
  * live by a consuming application, three sign-ins out of three.
  *
+ * Consuming (2026-08-26) removes that particular ratchet — a deposit whose arm fails is now
+ * gone, so it cannot deny the same session twice — but it does NOT restore the old rule.
+ * Rejecting here would still be wrong, and now for a worse reason: the item is already
+ * consumed by the time its arm fails, so denying the session would trade a permanent
+ * lockout for a permanent lockout AND a lost deposit. Applying one item stays data, and
+ * data is reported, never a refusal to connect.
+ *
  * That is strictly worse than the silence the 2026-08-13 shape replaced, and it collapsed
  * a distinction that has to stay open: **failing to REACH the queues** (the session cannot
  * proceed at all — reject, unchanged) against **failing to apply what is in one** (data,
@@ -135,8 +142,11 @@ const inFlight = new Map<string, Promise<void>>();
  * restore step is a plain `await` and still rejects, so a broker that cannot answer fails
  * the connection there, before any queue is reached. Only the per-inbox drain is caught.
  *
- * Not silence: {@link reportUndrained} is loud and ungated, and the caps a share carries
- * are not lost — the deposit stays in the queue, so the next connection applies it.
+ * Not silence: {@link reportUndrained} is loud and ungated. What it no longer promises,
+ * since deposits became consumed on 2026-08-26, is that nothing was lost: the deposit the
+ * drain was applying when it fell over is GONE, and only what is still queued reaches the
+ * next connection. The message says exactly that, and so does the test
+ * `an I/O failure while filing a Link STOPS the drain, so the rest of the queue survives`.
  *
  * Not fixed with a retry, a timeout or a flag on purpose: deciding *what to do* about a
  * broker that cannot answer belongs to the caller, and it can only decide if it is told.
@@ -223,6 +233,12 @@ export async function connectedUser(): Promise<void> {
         // is abandoning, which this function has always called "not a failure", and
         // reporting it would put a broker-looking error in the log every time a page
         // switches user. The loop is about to return for the same reason.
+        //
+        // This guard cannot tell an abandonment from a genuine failure that happened to
+        // coincide with a user switch, and it does not have to: since 2026-08-26 a deposit
+        // that was consumed and not applied is reported by `inbox-consume.deliverDeposits`
+        // BEFORE the error is thrown, so what this drops is the duplicate, never the only
+        // notice of a loss. Dropping it here was silent for exactly one day.
         if (!stillConnected()) return;
         reportUndrained(inbox, error);
       }

packages/polyfill/src/emulated-verifier/inbox-consume.ts

@@ -0,0 +1,212 @@
+/**
+ * Consuming an inbox — the ONE act that retires a deposit, and the ONE loop that performs it.
+ *
+ * ── Upstream pops, and the order is not an accident ───────────────────────
+ * Read at all three of its sites, because the order is the whole contract:
+ *
+ *   1. the broker REMOVES the message from the queue — `ClientEvent::InboxPopRequest` →
+ *      `inbox_pop_for_user` → `take_first_msg` → `MSGS.take_first_value`, which is
+ *      `get_first_key_value` followed by `del` (`engine/repo/src/kcv_storage.rs:557`,
+ *      `engine/storage-rocksdb/src/kcv_storage.rs:239-243`). The removal happens in the
+ *      STORE, before anything has looked at the content;
+ *   2. only then is it delivered (`ClientMessageContentV0::InboxReceive { from_queue: true }`,
+ *      `engine/net/src/actors/client/client_event.rs:68`);
+ *   3. the verifier applies it, and a failure is LOGGED AND SWALLOWED —
+ *      `log_err!("Error during process_inbox {e}")` — never re-enqueued. It then asks for
+ *      the next one (`engine/verifier/src/verifier.rs:1680-1715`).
+ *
+ * So: **remove, then apply, then log whatever went wrong, then move on.** A deposit is
+ * delivered exactly once whether or not its arm succeeded, and an arm that throws loses it
+ * — upstream that message left the store before the arm ever ran. Removing FIRST is
+ * therefore not a risk this module takes, it is the behaviour it reproduces; and it makes
+ * the reverse mistake impossible, since a removal that fails stops the apply instead of
+ * letting an applied deposit stay in the queue.
+ *
+ * ── Why a deliverability question exists here and not upstream ────────────
+ * Upstream an inbox holds nothing but typed messages, and WHO may pop one is settled by
+ * reader registration rather than by content: `inbox_pop_for_user(user)` pops only from
+ * inboxes that user is a registered reader of, so a message is never popped by anybody but
+ * its own recipient. Here an inbox holds a MIX — this package's deposits and a consumer's
+ * own payloads, which `surface/inbox.ts` hands back untouched — so "may this be popped
+ * now?" has to be asked of the content. That is `inbox-dispatch.claimsDeposit`, and it is
+ * asked BEFORE the removal for the same reason the broker checks registration before
+ * `take_first_msg`: what is not deliverable to this consumer was never popped for it.
+ *
+ * ── One removal, and it is here ───────────────────────────────────────────
+ * Both triggers this package drains from — the owner's own session (`inbox.processInbox`)
+ * and the deferred stand-in for an absent owner (`inbox.processForOwner`, scheduled by
+ * `emulated-verifier/inbox-processor.ts`) — call {@link deliverDeposits} and nothing else.
+ * Neither carries a copy of the removal: the triggers differ in WHO drains and WHEN, never
+ * in what consuming means. `grep -rn "DELETE" packages/polyfill/src/` shows the only
+ * deposit removal in the package is {@link removeDeposit} below.
+ */
+
+import { registerUpdate } from "./register-write";
+import { applyDeposit, claims, claimsDeposit } from "./inbox-dispatch";
+import type { Applying } from "./inbox-dispatch";
+import { getStoreRegistryDeps } from "../shared-wallet/bootstrap";
+import { accessLogPrefix, logStage, shortNuri } from "../shared-wallet/access-log";
+
+/**
+ * One deposit as it is STORED: the RDF subject `inbox.post` minted for it, and what it
+ * carries. The subject is the removal key — `post` gives every deposit a fresh unique
+ * subject, so naming it retires that deposit and no other, where a `ts` could collide.
+ *
+ * Deliberately NOT the published {@link import("../surface/inbox").Deposit}: a subject is
+ * emulation detail (upstream a queued message has no address of its own, it has a
+ * position), so it stays inside the package and an application never learns it.
+ */
+export interface StoredDeposit {
+  /** The RDF subject the deposit lives under, in its inbox document's default graph. */
+  readonly subject: string;
+  /** What the deposit carries — handed to the dispatch as-is. */
+  readonly payload: unknown;
+}
+
+/**
+ * Retire ONE deposit from its inbox. **The only removal in this package.**
+ *
+ * `DELETE WHERE { <subject> ?p ?o }` — every triple of that one deposit, whichever
+ * predicates it happens to carry (`from` is optional). Two established forms are combined
+ * here, and neither half is invented:
+ *
+ *   - `DELETE WHERE` with a VARIABLE predicate (`<s> ?p ?o`) is the shape verified against
+ *     the real broker for removing a whole subject
+ *     (`docs/decisions/sparql-delete-for-orm-objects.md`);
+ *   - it is ANCHORED with no `GRAPH <…>` wrapper, like every other register write in this
+ *     package (`public-store.exposeReadCap`, `branch-registers.publishInboxAddress`). That
+ *     is not a shortcut, it is where the data IS: `inbox.post` writes the anchored DEFAULT
+ *     graph and `DEPOSITS_QUERY` reads it, so a `GRAPH`-wrapped delete would name a graph
+ *     the deposits were never written to. The decision above shows the wrapped form because
+ *     its subject is an ORM object in a named graph; the anchor plays that role here.
+ *
+ * A `;`-joined compound update is exercised nowhere in this library, so this stays one
+ * statement.
+ *
+ * Through `registerUpdate`, and that is deliberate: retiring a deposit is the verifier's
+ * own bookkeeping, not an application write — upstream it happens inside the broker's
+ * store, and no application makes it. That door skips the OWNERSHIP guard, which a drain
+ * running for an absent owner could not pass, and keeps `assertMayReach` against the named
+ * ring: whoever consumes must hold the inbox's cap, and `processForOwner` names the
+ * owner's ring exactly as it does for every other step it takes.
+ *
+ * A failure PROPAGATES. Nothing is applied for a deposit that could not be retired — the
+ * caller's loop stops and its drain reports itself where drains report — because applying
+ * one that stayed in the queue is the replay this module exists to end.
+ */
+// @provenance removeDeposit kind=aligned level=1 ref=engine/broker/src/server_storage/core/inbox.rs:take_first_msg — upstream the store REMOVES the message as it hands it over (`MSGS.take_first_value` = `get_first_key_value` + `del`); here the queue is RDF in a document, so the same act is a DELETE of the deposit's own subject
+async function removeDeposit(stored: StoredDeposit, ctx: Applying): Promise<void> {
+  const { sessionId } = await getStoreRegistryDeps().getSession();
+  await registerUpdate(
+    sessionId,
+    `DELETE WHERE { <${stored.subject}> ?p ?o }`,
+    ctx.inbox,
+    "inboxConsume",
+    ctx.ring,
+  );
+}
+
+/**
+ * Deliver every deposit in `stored` to the dispatch, consuming each as it goes. Answers
+ * how many produced an EFFECT — which is what a drain traces, and all any caller wants.
+ *
+ * The loop both triggers share, so that "what consuming means" cannot come to differ
+ * between the owner's own drain and the deferred one. Per deposit, in this order:
+ *
+ *   1. **claimed?** — a payload no arm answers for is not popped at all, and the loop
+ *      moves on leaving it in the inbox. That covers a consumer's own data (not a message,
+ *      so nothing is reported) and a deposit whose arm belongs to the owner's own session
+ *      while a stranger's is running (see `inbox-dispatch.claimsDeposit`);
+ *   2. **remove** — the pop, before anything is applied, as upstream;
+ *   3. **apply** — the `match`, one arm per declared type. A refusal inside an arm is
+ *      reported on the log stream and the deposit is already gone, which is upstream's
+ *      `log_err!` + move on, and the end of the re-report-forever loop this package had.
+ *
+ * Sequential rather than parallel, for the reason every drain in this package is: an arm
+ * writes what it applies (`branch-registers.addLink`, on the owner's User branch), so two
+ * in flight over one queue interleave their reads and writes.
+ */
+// @provenance deliverDeposits kind=aligned level=1 ref=engine/verifier/src/verifier.rs:inbox — upstream's pop-apply-log-next loop, over a queue that is a document here rather than a column family
+export async function deliverDeposits(
+  stored: readonly StoredDeposit[],
+  ctx: Applying,
+): Promise<number> {
+  let applied = 0;
+  for (const deposit of stored) {
+    // The holder can move between two arms as easily as during the read that found these.
+    // Stopping leaves every deposit not yet reached in the queue for its owner — which is
+    // the whole reason this is asked BEFORE the pop rather than after it.
+    if (!holderStillStands(ctx)) {
+      logStage(
+        "ABANDONED " + shortNuri(ctx.inbox) + " — the identity changed while it was being " +
+          "processed; its remaining deposits stay for their owner",
+      );
+      return applied;
+    }
+    if (!claimsDeposit(deposit.payload, ctx)) continue;
+    // No subject, no pop. `?d` is bound by the deposits query, so this should be
+    // unreachable — but `depositsFrom` defaults it to "" rather than dropping the row, and
+    // an empty subject would issue `DELETE WHERE { <> ?p ?o }`: a malformed statement whose
+    // effect on a real broker nobody has established. Refusing to APPLY as well is the
+    // load-bearing half — applying without retiring is precisely the replay this module
+    // exists to end, and it would repeat at every drain for as long as the row sat there.
+    if (deposit.subject === "") {
+      console.error(
+        accessLogPrefix() + " a deposit in " + shortNuri(ctx.inbox) + " carries no subject, " +
+          "so it cannot be retired — refusing to apply it rather than applying it again at " +
+          "every drain. Nothing was consumed and nothing was written.",
+      );
+      continue;
+    }
+    await removeDeposit(deposit, ctx);
+    // Popping is an AWAIT, and the arm below reads AMBIENT state — so the identity can move
+    // across exactly this gap, between the decision to deliver and the delivery itself.
+    // Re-asked rather than assumed: applying now would file this deposit for whoever holds
+    // the page instead of for its owner, which is the mis-filing the whole `Applying`
+    // context exists to prevent.
+    //
+    // BOTH guards, and that matters: `processInbox` names its owner as a constant
+    // (`ownerHoldsTheSession: () => true`) because it only ever runs in that owner's own
+    // session, so the claim check alone cannot see the move — only `stillTheHolder` can.
+    // Checking one and not the other left this hole open, which is how it was missed.
+    //
+    // Reported ungated and then ABANDONED: the deposit is gone and cannot be got back, and
+    // whatever is behind it in the queue belongs to a session that is no longer here.
+    if (!holderStillStands(ctx) || !claims(deposit.payload, ctx)) {
+      console.error(
+        accessLogPrefix() + " a deposit in " + shortNuri(ctx.inbox) + " was consumed but not " +
+          "applied: the identity changed while it was being taken out of the queue, and " +
+          "applying it now would file it for the wrong holder. It cannot be recovered; what " +
+          "is still queued stays for its owner.",
+      );
+      return applied;
+    }
+    // The arm's own I/O failure is REPORTED HERE, at the source, and only then allowed to
+    // travel. It must stop the drain — everything not yet popped has to survive — but a
+    // throw is at the mercy of whoever catches it, and one caller legitimately swallows:
+    // `connect.connectedUser` drops the error when the identity has moved, because an
+    // ownership refusal there is abandoning and not a failure. That guard cannot tell the
+    // two apart, so an arm that failed WHILE the page switched user destroyed a deposit and
+    // printed nothing at all. Reporting before rethrowing closes that without touching a
+    // policy that is right for its own case: the loss is announced by the only code that
+    // knows a deposit was consumed.
+    try {
+      if (await applyDeposit(deposit.payload, ctx)) applied += 1;
+    } catch (error) {
+      console.error(
+        accessLogPrefix() + " a deposit in " + shortNuri(ctx.inbox) + " was consumed and " +
+          "could not be applied — it cannot be recovered; what is still queued stays for " +
+          "the next attempt:",
+        error,
+      );
+      throw error;
+    }
+  }
+  return applied;
+}
+
+/** Is the identity this drain was authorised for still the one holding the page? A drain
+ *  that NAMED its holder rather than resolving it has nothing to lose and always stands. */
+function holderStillStands(ctx: Applying): boolean {
+  return ctx.stillTheHolder === undefined || ctx.stillTheHolder();
+}

packages/polyfill/src/emulated-verifier/inbox-dispatch.ts

@@ -85,15 +85,39 @@ export interface Applying {
   /**
    * Whether {@link owner} is ALSO the identity holding the session.
    *
-   * It decides what an arm may do, and the line is not arbitrary. A drain running under
+   * It decides what is DELIVERED, and the line is not arbitrary. A drain running under
    * SOMEONE ELSE's session (the deferred stand-in for an absent owner,
    * `emulated-verifier/inbox-processor.ts`) usurps the owner's identity, and it does so
    * for the verifier's own bookkeeping only — a register write on the owner's User
    * branch. Writing APPLICATION data into the owner's documents from a stranger's page is
-   * a different act, and this package does not take it: the deposit is not consumed, so
-   * it stays for the owner's own next connection, which is the real path.
+   * a different act, and this package does not take it.
+   *
+   * Since 2026-08-26 it also decides what is CONSUMED, and the two must stay the same
+   * decision: what a stranger's drain declines to apply, it must not pop either, or the
+   * owner would lose a deposit to a session that was never going to apply it. So this is
+   * read by {@link claimsDeposit}, before the removal, and not by the arm afterwards.
+   *
+   * A PREDICATE rather than a value, because it is asked once per deposit: a drain runs
+   * across many awaits and the owner can arrive or leave inside it. A drain that captured
+   * it once would keep treating every later deposit as the owner's long after he stopped
+   * holding the page.
    */
-  readonly ownerHoldsTheSession: boolean;
+  readonly ownerHoldsTheSession: () => boolean;
+  /**
+   * Is {@link owner} STILL the identity this drain was authorised for? Consulted before
+   * each deposit, never once for the run.
+   *
+   * Only a drain that resolved its holder from the ambient session needs it —
+   * `inbox.processInbox`, whose guard ran at entry while its arms read and write many
+   * awaits later, so the identity can move mid-run and its remaining deposits must be left
+   * for whoever owns them. It matters more now than it did: a deposit reached after the
+   * switch would be POPPED under the wrong identity, not merely mis-filed.
+   *
+   * Omitted by a drain that NAMED its holder instead of resolving it
+   * (`inbox.processForOwner`, which runs under a stranger's session on purpose and would
+   * abandon every run if it asked). Absent means "nothing can invalidate this run".
+   */
+  readonly stillTheHolder?: () => boolean;
 }
 
 /**
@@ -132,21 +156,84 @@ export function linkPayload(cap: ReadCap): { kind: string; cap: ReadCap } {
  * item is reported and denies nobody their session, nor the OTHER deposits their turn. A
  * genuine I/O failure is a different thing and still propagates — the caller reports the
  * whole inbox and moves to the next one.
+ *
+ * **The deposit is already gone when this runs**, and the wording says so. It was popped
+ * before the arm was entered (`inbox-consume.deliverDeposits`), exactly as upstream logs
+ * `Error during process_inbox` for a message the broker took out of the queue before
+ * delivering it. So this is reported ONCE, not at every push and every connection for as
+ * long as the deposit sits there — which is what it used to promise, in these words.
  */
 function report(ctx: Applying, why: string): void {
   console.error(
     accessLogPrefix() + " could not apply a deposit in " + shortNuri(ctx.inbox) +
-      " — it stays in it and the next attempt will try again: " + why,
+      " — it has been consumed and will not be retried: " + why,
   );
 }
 
+/**
+ * May this deposit be POPPED for the consumer described by `ctx`? Asked before anything is
+ * removed, and the reason it has to exist is a divergence, not a preference.
+ *
+ * Upstream nothing asks it: an inbox holds only typed messages, and WHO may take one is
+ * settled by reader registration rather than content — `inbox_pop_for_user(user)` walks
+ * only the inboxes that user reads, so a message is never popped by anyone but its
+ * recipient. Here one inbox holds a MIX, so the same question has to be put to the payload.
+ *
+ * Two answers are "no", and neither is a failure:
+ *
+ *   - **a consumer's own payload.** It declares no kind of this package's, so no arm claims
+ *     it, and nothing is reported: it is not an unapplied message, it is not a message. It
+ *     is also the thing `inbox.read` and `inbox.watch` hand back, so consuming it would
+ *     take from an application the data it deposited for itself.
+ *   - **an arm that belongs to the owner's OWN session, while a stranger's is running.**
+ *     The deferred stand-in usurps an absent owner's identity for the verifier's own
+ *     bookkeeping only; writing application data into that owner's documents is an act it
+ *     does not take (see {@link Applying.ownerHoldsTheSession}). Upstream such a pop simply
+ *     never happens — only the recipient pops. So the deposit is left in the queue for the
+ *     owner's next connection, which is the real path, and is NOT consumed by a drain that
+ *     was never going to apply it. Getting this wrong is the one way consuming could lose
+ *     data outright: a stranger's timer would retire a reference the owner never indexed.
+ *
+ * The trace lives here rather than in the arm, because this is now where the decision is.
+ */
+// @provenance claimsDeposit kind=divergent level=1 ref=engine/broker/src/server_broker.rs:inbox_pop_for_user — upstream deliverability is reader REGISTRATION and the content is never consulted; here an inbox mixes this package's deposits with a consumer's own, so it is read off the payload
+export function claimsDeposit(payload: unknown, ctx: Applying): boolean {
+  const claimed = claims(payload, ctx);
+  if (!claimed && kindOf(payload) === REFERENCE_KIND) {
+    logStage(
+      "WAITING " + shortNuri(ctx.inbox) + " — a reference deposit is applied by its own " +
+        "owner's session; it stays for " + ctx.owner,
+    );
+  }
+  return claimed;
+}
+
+/**
+ * The same question with NO trace — for the re-ask that follows the pop.
+ *
+ * Separate because the trace is only true the FIRST time. Asked again after the deposit has
+ * been removed, {@link claimsDeposit} announced "it stays for <owner>" about something that
+ * had just been destroyed, one line above the report saying so. A predicate that logs is
+ * fine where it is asked once; this one is asked twice, and only the first ask is a wait.
+ */
+export function claims(payload: unknown, ctx: Applying): boolean {
+  const kind = kindOf(payload);
+  if (kind === null) return false;
+  if (kind === REFERENCE_KIND && !ctx.ownerHoldsTheSession()) return false;
+  return true;
+}
+
 /**
  * Apply ONE deposit for the owner of its inbox. Answers whether it produced an effect —
  * which is what a drain counts, and all any caller has ever needed from it.
  *
- * Nothing is consumed here, by any arm: an inbox stays re-readable, so every abandon and
- * every refusal above is harmless — what was not applied is still there for the next push
- * or the next connection.
+ * **Called only for a deposit already consumed**, and only through
+ * `inbox-consume.deliverDeposits`, which asked {@link claimsDeposit} first and popped it
+ * second. Every arm below therefore runs on a deposit that has left its inbox: a refusal
+ * is final and is reported once, and there is no next attempt to leave anything for. The
+ * arm that must NOT run under a stranger's session is not guarded here — it is not
+ * delivered here at all, which is the only way a refusal and a non-delivery stay
+ * distinguishable now that one of them destroys.
  */
 // @provenance applyDeposit kind=aligned level=1 ref=engine/verifier/src/inbox_processor.rs:process_inbox — the same `match` over the declared content, one arm per variant, `NotImplemented` for the rest
 export async function applyDeposit(payload: unknown, ctx: Applying): Promise<boolean> {
@@ -190,6 +277,21 @@ async function applyLink(payload: unknown, ctx: Applying): Promise<boolean> {
     return false;
   }
   getCaps().learnFor(ctx.ring, cap);
+  // PROPAGATES, deliberately, and this arm is where that was got wrong twice in one day.
+  // `addLink` used to swallow, so a cap that was never filed was reported as applied. The
+  // first correction caught the throw HERE and reported per deposit — which was worse: most
+  // of what `addLink` does before its write (`ensureAccount`, `readLinks`, `session`) is
+  // deposit-INDEPENDENT infrastructure that fails for the whole queue at once, so catching
+  // it meant popping and destroying every remaining deposit one by one while reporting each.
+  //
+  // A genuine I/O failure is not an unapplicable item: it stops the drain, the caller
+  // reports the whole inbox, and everything not yet popped is preserved for the next
+  // attempt. That is the rule stated beside {@link report}, and BOTH arms follow it — but
+  // the reference arm only since its `unreadable` outcome was split out of `refused` on the
+  // same day. It had been the opposite: the batch read of the day swallowed a failed read and
+  // answers `[]`, so an outage arrived as an ordinary refusal and the drain walked the
+  // whole queue destroying it. Correcting one arm and leaving the other is precisely how
+  // that survived a round of review.
   await addLink(cap, ctx.owner);
   return true;
 }
@@ -197,20 +299,14 @@ async function applyLink(payload: unknown, ctx: Applying): Promise<boolean> {
 /**
  * The **reference** arm: resolve it and look — see `index-deposit.ts` for the whole of it.
  *
- * Only in the owner's OWN session, for the reason {@link Applying.ownerHoldsTheSession}
- * gives: an entry is application data in the owner's document, and a drain running under a
- * stranger's session writes the verifier's registers and nothing else. Left waiting is not
- * left silent, and it is not a failure either — the deposit is not consumed, so the owner's
- * next connection applies it, which is the path this package documents.
+ * Only ever entered in the owner's OWN session, and {@link claimsDeposit} is what makes
+ * that true: under a stranger's session this deposit is not delivered, so it is not popped
+ * either and it waits for its owner. The test used to stand HERE and return `false`, which
+ * was harmless while nothing was consumed and would now retire a reference nobody applied.
+ * That is why deliverability had to become a question asked before the pop rather than a
+ * branch inside the arm.
  */
 async function applyReference(reference: Nuri, ctx: Applying): Promise<boolean> {
-  if (!ctx.ownerHoldsTheSession) {
-    logStage(
-      "WAITING " + shortNuri(ctx.inbox) + " — a reference deposit is applied by its own " +
-        "owner's session; it stays for " + ctx.owner,
-    );
-    return false;
-  }
   const application = await applyIndexDeposit(reference, ctx.inbox);
   switch (application.outcome) {
     case "applied":
@@ -222,14 +318,33 @@ async function applyReference(reference: Nuri, ctx: Applying): Promise<boolean>
     case "unchanged":
       return false;
     case "skipped":
-      // A property of the OBJECT, not a failure: it resolved, and there is nothing to
-      // index it by. Traced, not reported — see `index-deposit.ts`.
-      logStage(
-        "NOT INDEXED " + shortNuri(application.object) + " — " + application.reason,
+      // A property of the OBJECT rather than a failure — it resolved, and there is nothing
+      // to index it by. It was TRACED and not reported while deposits were re-read for
+      // ever: an object that carried nothing for the field yet would be indexed by a later
+      // drain once it did. Consumption ends that, so the deposit is discarded here and now,
+      // and a discard may not be gated behind `debugAccessLog` — a diagnostic may be
+      // opt-in, something the caller can no longer recover may not.
+      report(
+        ctx,
+        "a reference to " + shortNuri(application.object) + " was discarded — " +
+          application.reason,
       );
       return false;
     case "refused":
+      // DETERMINISTIC: a misconfigured index, an inbox that is not a document's. Trying
+      // again changes nothing, so this is an unapplicable item — reported, and the deposits
+      // behind it keep their turn.
       report(ctx, application.why);
       return false;
+    case "unreadable":
+      // The read established NOTHING — it threw, or it answered nothing from a repo whose
+      // sync this session never confirmed (`index-deposit.noRowsMeansAbsent`). THROWS, so
+      // the drain stops and everything still queued survives — the same rule the Link arm
+      // follows. Treating this as an ordinary refusal let a single outage walk the whole
+      // queue, popping and destroying every reference while reporting each as absent.
+      // `inbox-consume.deliverDeposits` reports the deposit this one cost before letting
+      // the throw travel. An object that is genuinely absent is `refused`, not this: it
+      // costs its own deposit and the queue behind it carries on.
+      throw new Error(application.why);
   }
 }

packages/polyfill/src/emulated-verifier/inbox-drain.ts

@@ -37,13 +37,18 @@ const running = new Map<Nuri, Promise<void>>();
  * `inbox.watch` use — and it is NOT gated by the access-log flag: a diagnostic may be
  * opt-in, a failure may not.
  *
- * One failed item denies nothing, here as at connection: the inbox is not consumed by
- * failing, the deposit stays in it, and the next push or the next connection applies it.
+ * One failed item denies nothing, here as at connection. What it no longer promises is a
+ * RETRY: since 2026-08-26 a deposit is popped before its arm runs
+ * (`emulated-verifier/inbox-consume.ts`), so whatever had already been delivered when this
+ * drain fell over is gone, exactly as upstream loses a message the broker took out of the
+ * queue. What is still QUEUED is untouched and the next push or connection reaches it —
+ * which is a different sentence, and the wording says so rather than promising the old one.
  */
 function reportFailure(inbox: Nuri, error: unknown): void {
   console.error(
-    accessLogPrefix() + " could not apply what is in this inbox — its deposits stay in it " +
-      "and the next attempt will try again: " + shortNuri(inbox) + ":",
+    accessLogPrefix() + " could not finish draining this inbox — whatever it had already " +
+      "taken is consumed; what is still queued waits for the next attempt: " +
+      shortNuri(inbox) + ":",
     error,
   );
 }

packages/polyfill/src/emulated-verifier/inbox-observer.ts

@@ -36,7 +36,7 @@
  *   - the REGISTER — an inbox opened mid-session appends an `AddInboxCap` record to the
  *     User branch of the private store (`branch-registers.openDocumentInbox`), so a push on
  *     that document re-enumerates `myInboxes()`;
- *   - WHAT THIS IDENTITY HOLDS (`CapRegistry.onChange`) — the same signal `watchShape`
+ *   - WHAT THIS IDENTITY HOLDS (`CapRegistry.onChange`) - the same signal `useShapeQuery`
  *     re-reads on. It answers the case the register cannot: an identity that connects
  *     before it has an account at all. Provisioning is lazy here, so a person's FIRST visit
  *     connects with no stores, no private store to follow and no inbox to watch; the
@@ -187,9 +187,12 @@ async function applyWhatArrived(obs: Observation, inbox: Nuri): Promise<void> {
       // is not theirs. (Landing after it, the run ABANDONS quietly instead and returns; both
       // leave the deposit where it is.) Abandoning is what this package has always called
       // "not a failure", and reporting it would put a broker-looking error in the log every
-      // time a page switches user. Nothing is lost: an inbox is not consumed by being
-      // abandoned, so the deposit is still there for its owner's next connection. Same rule,
-      // same words, as the drain loop in `connect.connectedUser`.
+      // time a page switches user. Nothing is lost: abandoning happens BEFORE the deposit it
+      // stopped at is taken out of the queue (`emulated-verifier/inbox-consume.ts` asks
+      // whether the holder still stands, then pops), so that deposit and every one behind it
+      // are still there for its owner's next connection. What had already been popped was
+      // applied for the holder that was authorised at the time. Same rule, same words, as the
+      // drain loop in `connect.connectedUser`.
       if (!current(obs)) return;
       throw error;
     }
@@ -388,7 +391,9 @@ async function enumerate(obs: Observation): Promise<void> {
  *
  * It never rejects. Failing to WATCH is reported where failures go and denies nobody their
  * session — the same rule the drain loop above it follows, and for the same reason: what
- * has not been applied stays in its queue for the next attempt.
+ * has not been DELIVERED stays in its queue for the next attempt. (Delivered, not applied:
+ * since 2026-08-26 a deposit is popped before its arm runs, so one whose arm then failed is
+ * gone — see `emulated-verifier/inbox-consume.ts`. Failing to WATCH takes nothing out.)
  */
 // @provenance startObservingInboxes kind=aligned level=1 ref=engine/verifier/src/verifier.rs:inbox — upstream a connected verifier is handed each inbox message as it arrives and applies it; here the arrival signal is a document push, and the set of inboxes is the User branch's `AddInboxCap` records
 export async function startObservingInboxes(): Promise<void> {

packages/polyfill/src/emulated-verifier/inbox-processor.ts

@@ -19,8 +19,11 @@
  * seconds later. Alice deposits into Bob's inbox; twenty seconds later this package drains
  * Bob's inbox, while the connected session is still Alice's. When Bob IS connected in this
  * page, the observation has already applied it long before the window closes and the timer
- * finds nothing left to do — harmless (draining is idempotent) and not worth a special
- * case: the two answer different questions, and only this one answers the absent owner.
+ * finds an EMPTY queue — since 2026-08-26 that is literally true rather than merely
+ * harmless: the observation CONSUMED the deposit, so there is nothing left to see, where
+ * before the timer re-read it and relied on every arm being idempotent. Not worth a special
+ * case either way: the two answer different questions, and only this one answers the absent
+ * owner.
  *
  * ── That is identity usurpation, and it is deliberate ─────────────────────
  * It is only possible because one shared wallet holds every virtual identity, and it is

packages/polyfill/src/emulated-verifier/index-deposit.ts

@@ -24,11 +24,22 @@
  * fields and corrupt each other's entries.
  *
  * ── AN INDEX ONLY EVER GROWS ──────────────────────────────────────────────
- * Nothing here removes an entry, and nothing here can express a removal. That is what
- * makes the failure story trivial: since the only write is an addition, a read that comes
- * back empty — object gone, unreadable, or the broker silent — can only ever mean "not
- * added this time", and a later deposit adds it. Nothing has to tell an absence from a
- * failure, so nothing can get that wrong. The price, stated plainly because someone will
+ * Nothing here removes an entry, and nothing here can express a removal, so the only write
+ * is an addition and curation stays convergent whatever order references arrive in.
+ *
+ * That used to make the failure story trivial too: a read coming back empty — object gone,
+ * unreadable, or the broker silent — meant "not added this time" whichever it was, so
+ * nothing had to tell an absence from a failure. **That is no longer true, and it is the
+ * sharpest consequence of consuming.** An absence is deterministic and costs its own deposit;
+ * a silent broker is transient and must stop the drain, or one outage walks the queue and
+ * destroys every reference in it. An anchored read answers `[]` for both, so this module
+ * passes it an `onUnreadable` reporter and asks which one happened.
+ *
+ * What it no longer means, since deposits became consumed on 2026-08-26, is "and a later
+ * drain adds it". THIS deposit is gone once it has been looked at, so a broker that was
+ * silent for the one second the reference was examined costs that reference permanently.
+ * The recourse is a NEW deposit, which someone has to make; nothing retries on its own.
+ * Every such case is reported ungated, so it is at least never silent. The price, stated plainly because someone will
  * need it: an entry cannot be taken out of an index, by anyone, including its owner.
  *
  * Harmless is not the same as invisible: every reference that could not be resolved is
@@ -43,12 +54,14 @@
  * acted on.
  */
 
-import { readUnion } from "../surface/read-model";
+import { readDocumentSubjects } from "../surface/read-document";
 import { sparqlUpdate } from "../surface/docs";
 import { readInboxCapPairs } from "./branch-registers";
+import { getSyncState } from "./open-repo";
+import { mustNotAttempt } from "./reach";
 import { session } from "../shared-wallet/account-registry";
 import { assertNuri, escapeLiteral } from "../surface/sparql";
-import type { UnionSubject } from "../surface/read-model";
+import type { DocumentSubject } from "../surface/read-document";
 import type { Nuri } from "../model/types";
 
 /**
@@ -70,14 +83,74 @@ export type IndexApplication =
   | { readonly outcome: "unchanged"; readonly object: Nuri }
   /** Resolved, and deliberately not added — a property of the OBJECT, not a failure. */
   | { readonly outcome: "skipped"; readonly object: Nuri; readonly reason: string }
-  /** Nothing was written, and something is wrong enough to say out loud. */
-  | { readonly outcome: "refused"; readonly why: string };
+  /** Nothing was written, and something is wrong enough to say out loud. A DETERMINISTIC
+   *  refusal — a misconfigured index, an inbox that is not a document's. Trying again
+   *  changes nothing, so the drain reports it and moves on. */
+  | { readonly outcome: "refused"; readonly why: string }
+  /**
+   * The read did NOT establish anything — it threw, or it returned nothing from a repo
+   * whose sync this session never confirmed. Not an absence, and not a refusal: THROWS, so
+   * the drain stops and everything still queued survives the outage.
+   *
+   * Its own outcome since 2026-08-26, and the reason is consumption. While deposits were
+   * re-read for ever the ambiguity was free: absent or unreadable, the answer was "not
+   * added this time" and a later drain settled it. Once the deposit is popped before the
+   * arm runs, the two need opposite handling, and picking either one wholesale is wrong in
+   * a way that was measured: treating every empty read as a FAILURE let one dead reference
+   * stall every deposit behind it (a stranger can deposit, so that starves an index);
+   * treating every empty read as an ABSENCE let one cold start destroy the whole queue.
+   * {@link noRowsMeansAbsent} tells them apart instead of choosing.
+   */
+  | { readonly outcome: "unreadable"; readonly why: string };
+
+/**
+ * Did a read that came back with NO ROWS actually establish that the document is empty?
+ *
+ * This is the question consumption forced, and it has three sources of "no rows", only one
+ * of which is an absence:
+ *
+ *   - the read THREW. Transient. Not an absence. Its callers return before reaching this
+ *     function at all, which is why `readFailed` below can only be false today; the
+ *     parameter stays because the answer for a failed read is part of the question this
+ *     function exists to answer, and hiding it in the call order would lose it.
+ *   - the document COULD NOT BE REACHED, because this holder holds no cap for it. Since
+ *     `1.0.0-dev.8` that arrives as a THROW from `docs.sparqlQuery` rather than as a
+ *     silently dropped document, so the previous bullet catches it - but the reasoning
+ *     is the same one and worth keeping: it looked deterministic and is not. For a
+ *     stranger's PUBLIC document - the reference arm's central case - possession is
+ *     acquired by a network fetch that swallows every error and MEMOISES the failure
+ *     (`public-store.ts`). One outage on that fetch therefore presents as "no cap", and
+ *     it stays that way for the session, so classing it as an absence destroyed the
+ *     deposit AND every re-deposit after it. Not an absence.
+ *   - the repo is PRESENT BUT UNSYNCED — and this is the one that cost round 6. A fresh
+ *     session over a persistent wallet has not received the repo's commits, so the anchored
+ *     query legitimately matches nothing and **raises no error at all**. Classing that as an
+ *     absence let a cold start destroy an entire reference queue, silently, while reporting
+ *     each one as "the object is absent".
+ *
+ * So an absence has to be EARNED, and only one shape earns it: a query was actually issued,
+ * it did not fail, and the repo's sync is confirmed. `open-repo` keeps `synced` and
+ * `timed-out` apart for exactly this and says so in those words — `synced` means a 0-row
+ * read MEANS it. `unknown` is the unit-fake path (no `doc_subscribe`, so no `State`
+ * semantics) where the read is direct and trustworthy.
+ *
+ * The cost of the strict answer is LATENCY, never loss: a reference this holder truly can
+ * never read stops one drain, is already popped, and the next attempt resumes past it. The
+ * cost of the lax answer was destroyed deposits that no re-deposit could recover. That
+ * asymmetry is the whole rule — when in doubt, do not call it an absence.
+ */
+function noRowsMeansAbsent(doc: Nuri, readFailed: boolean): boolean {
+  if (readFailed) return false;
+  if (mustNotAttempt(doc)) return false;
+  const sync = getSyncState(doc);
+  return sync === "synced" || sync === "unknown";
+}
 
 /**
  * The values a subject carries for a predicate.
  *
- * OWN properties only. `props` arrives as a plain object literal (`readUnion` builds
- * `const props: Record<string, string[]> = {}`), so it inherits from `Object.prototype`:
+ * OWN properties only. `props` arrives as a plain object literal (`readDocumentSubjects`
+ * builds `props: {}`), so it inherits from `Object.prototype`:
  * an index declaring `constructor`, `toString` or `valueOf` as its field would otherwise
  * find a FUNCTION where a list of values belongs, and spreading it throws. The non-string
  * filter is the same caution — this data crossed a process boundary, and a value that is
@@ -88,7 +161,7 @@ export type IndexApplication =
  * came back has the shape the type promises.
  */
 export function valuesOf(
-  subject: UnionSubject | undefined,
+  subject: DocumentSubject | undefined,
   predicate: string,
 ): readonly string[] {
   const props = subject?.props;
@@ -100,7 +173,7 @@ export function valuesOf(
 
 /** Every field the document declares for itself — zero, one, or (wrongly) several. */
 export function declaredFields(
-  subjects: readonly UnionSubject[],
+  subjects: readonly DocumentSubject[],
   index: Nuri,
 ): readonly string[] {
   return valuesOf(
@@ -119,7 +192,7 @@ export function declaredFields(
  * ABSENT, so the index could SHRINK through nothing but additions.
  */
 export function indexedObjects(
-  subjects: readonly UnionSubject[],
+  subjects: readonly DocumentSubject[],
   index: Nuri,
 ): ReadonlySet<string> {
   const out = new Set<string>();
@@ -150,10 +223,13 @@ async function documentAddressedBy(inbox: Nuri): Promise<Nuri | null> {
  * document declares it indexes by, whether the reference is already in, what the
  * referenced object says for the field — and only then writes ONE entry.
  *
- * Never removes anything and never rewrites an entry, so re-applying the same deposit —
- * which happens on every drain, because deposits are not consumed — lands on the same
- * result. Curation is convergent, and its outcome does not depend on the order references
- * arrive in.
+ * Never removes anything and never rewrites an entry, so the same reference arriving TWICE
+ * lands on the same result. That is still needed now that deposits are consumed, and the
+ * reason has simply changed: not a drain replaying one deposit, but two DISTINCT deposits
+ * naming the same object — a re-share, a retry by an application, two depositors who both
+ * point at it. Upstream keeps the same check for the same reason, with a queue that pops
+ * (`ContactAlreadyExists`, `engine/verifier/src/inbox_processor.rs`), which is the proof it
+ * was never a replay compensation. Curation stays convergent and order-independent.
  */
 // @provenance applyIndexDeposit kind=invention level=none ref=none — nothing upstream turns a deposited reference into an index entry; the whole arm is this library's own
 export async function applyIndexDeposit(
@@ -173,7 +249,28 @@ export async function applyIndexDeposit(
     return { outcome: "skipped", object: reference, reason: "self-reference" };
   }
 
-  const subjects = await readUnion([index]);
+  // A FAILED read and an EMPTY one demand opposite handling now that deposits are
+  // consumed - see the `unreadable` outcome - so they are never allowed to arrive as the
+  // same value. `readDocumentSubjects` throws where it used to hand the error to a
+  // callback and answer `[]`, which is the same distinction made by the language instead
+  // of by a convention. Tracked as a BOOLEAN, not as the error value: `throw null` and
+  // `throw undefined` are legal, and a sentinel comparison against `null` made exactly
+  // those failures invisible.
+  let indexReadFailed = false;
+  let indexError: unknown;
+  let subjects: readonly DocumentSubject[] = [];
+  try {
+    subjects = await readDocumentSubjects(index, "indexRead");
+  } catch (error) {
+    indexReadFailed = true;
+    indexError = error;
+  }
+  if (indexReadFailed) {
+    return {
+      outcome: "unreadable",
+      why: `${index}: the index itself could not be read: ${String(indexError)}`,
+    };
+  }
   const declared = declaredFields(subjects, index);
   if (declared.length > 1) {
     // Ambiguity refuses to curate and leaves READING alone. Picking one would silently
@@ -193,35 +290,63 @@ export async function applyIndexDeposit(
   const field = declared[0];
   if (field === undefined) {
     return {
-      outcome: "refused",
-      why:
-        `${index} declares no index field (${INDEX_FIELD}) — either it is not an index, or ` +
-        "it could not be read: an unreadable document and an empty one are the same empty " +
-        "result here. Nothing was written. Retry before concluding it is malformed.",
+      outcome: noRowsMeansAbsent(index, indexReadFailed) ? "refused" : "unreadable",
+      why: noRowsMeansAbsent(index, indexReadFailed)
+        ? `${index} declares no index field (${INDEX_FIELD}) — it read cleanly and says ` +
+          "nothing, so either it is not an index or it was never configured as one. " +
+          "Nothing was written, and nothing here will write until it declares one."
+        : `${index} declares no index field (${INDEX_FIELD}), but its repo is not synced ` +
+          "in this session, so an empty read proves nothing about it. Nothing was written, " +
+          "and this is NOT a claim that it is misconfigured.",
     };
   }
 
   if (indexedObjects(subjects, index).has(reference)) {
     // Already there. Nothing is re-read and nothing is rewritten — an entry, once made,
-    // is never touched again.
+    // is never touched again. Reached by a SECOND deposit naming the same object, not by a
+    // replay of the first: that one was consumed when it was applied.
     return { outcome: "unchanged", object: reference };
   }
 
-  let resolved: readonly UnionSubject[];
+  let resolved: readonly DocumentSubject[] = [];
+  let referenceReadFailed = false;
+  let referenceError: unknown;
   try {
-    resolved = await readUnion([reference]);
+    resolved = await readDocumentSubjects(reference, "indexReference");
   } catch (error) {
-    return { outcome: "refused", why: `${reference}: ${String(error)}` };
+    referenceReadFailed = true;
+    referenceError = error;
   }
+  // The read did not answer - a broker outage, or a reference this holder cannot reach at
+  // all, which `docs.sparqlQuery` now refuses out loud instead of leaving as an empty
+  // answer. Stop the drain either way: everything still queued has to survive an outage,
+  // and this deposit is already gone.
+  if (referenceReadFailed) {
+    return {
+      outcome: "unreadable",
+      why: `${reference}: could not be read: ${String(referenceError)}`,
+    };
+  }
+  // A clean read that found NOTHING — the object is genuinely absent or holds no triples.
+  // Deterministic: trying again changes nothing, so this is an unapplicable item and the
+  // deposits behind it keep their turn. Distinguishing this from the case above is the whole
+  // point of `onUnreadable`: for one day they were the same answer, and treating both as
+  // failures let a single dead reference stall every deposit behind it — which, since anyone
+  // may deposit, is a way to starve someone else's index.
   if (resolved.length === 0) {
-    // ABSENT, unreadable, or the read failed — and this layer does not tell them apart,
-    // because nothing it does depends on the answer: an index only ever grows, so every
-    // reading leads to the same act, do not add and say so.
+    if (!noRowsMeansAbsent(reference, referenceReadFailed)) {
+      return {
+        outcome: "unreadable",
+        why:
+          `${reference}: the read came back empty, but its repo is not synced in this ` +
+          "session — that proves nothing about the object, so it is not treated as absent",
+      };
+    }
     return {
       outcome: "refused",
       why:
-        `${reference}: the read came back empty — the object is absent, unreadable, or the ` +
-        "read failed; they are not distinguished here, and a later deposit adds it",
+        `${reference}: read cleanly from a synced repo and found nothing — the object is ` +
+        "absent",
     };
   }
 

packages/polyfill/src/emulated-verifier/open-repo.ts

@@ -2,7 +2,7 @@
  * open-repo — cold-start repo opening for the ANCHORED read path (polyfill-era).
  *
  * ── The cold-start defect this heals ──────────────────────────────────────
- * The anchored read path (`surface/read-model.ts` `readDoc`,
+ * The anchored read path (`surface/read-document.ts` `readDocumentSubjects`,
  * `shared-wallet/account-registry.ts` `readUserStore`) assumes the target repo is
  * already usable by the verifier — true within the session that CREATED the doc
  * (every `doc_create` opens it), but FALSE on a FRESH session over the same
@@ -19,9 +19,10 @@
  * the verifier: on a persistent profile `Verifier::load` repopulates `self.repos` from
  * user storage at construction (`engine/verifier/src/verifier.rs:535-560`), so the repo
  * is PRESENT but unsynced and the anchored query legitimately matches nothing; and this
- * library's own `readDoc` catches every error and returns `[]`
- * (`surface/read-model.ts:122`), so anything that did throw would reach the caller as
- * emptiness anyway. The fix below is right; the diagnosis written beside it was not.
+ * library's own per-document read caught every error and returned `[]`
+ * (`surface/read-model.ts`'s `readDoc`, until `1.0.0-dev.8` removed it along with the
+ * batch it served), so anything that did throw reached the caller as emptiness anyway.
+ * It no longer does: `surface/read-document.ts` lets the rejection through. The fix below is right; the diagnosis written beside it was not.
  *
  * The circularity that made this self-inflicted: `doc_subscribe` WOULD open the
  * repo, but the reactive layer only subscribes AFTER the listing produced NURIs —
@@ -44,26 +45,31 @@
  * later establishes for change signals.
  *
  * ── Idempotence / perf (once per session, no polling) ─────────────────────
- * The registry opens each repo at most ONCE per session: `opened` records completed
- * opens (a hit skips everything), `inFlight` de-dupes concurrent opens of the same
- * repo. A brand-new page / module instance starts with an empty registry; and when
- * the injected session id CHANGES within the same page (an in-page re-login /
- * `session_stop`+`session_start`, whose new verifier has an empty `self.repos`) the
- * registry auto-resets (`syncSession`) so repos are re-opened against the new session
- * rather than wrongly skipped as "already open". No polling: we wait on the first
- * `State` push, with a bounded fallback timeout so a missing push can't hang.
+ * A repo is opened once per session, and what makes that safe is ASKING rather than
+ * remembering: {@link opens} records the bootstrap listener this module took out, and
+ * {@link docChannel} says whether the subscription behind it stands. A caller skips the work
+ * only when both hold - see the invariant below, and `openRepoUnguarded`, where the two
+ * halves are named. Concurrent callers join one wait ({@link BootstrapOpen.done}). A
+ * brand-new page / module instance starts empty; and when the injected session id CHANGES
+ * within the same page (an in-page re-login / `session_stop`+`session_start`, whose new
+ * verifier has an empty `self.repos`) the registry auto-resets (`syncSession`) so repos are
+ * re-opened against the new session rather than wrongly skipped as "already open". No
+ * polling: we wait on the first `State` push, with a bounded fallback timeout so a missing
+ * push can't hang.
  *
- * ── Sync state (per-nuri, lib-internal) ───────────────────────────────────
- * Each nuri carries an explicit sync state, readable via {@link getSyncState}:
- *   `"syncing"`   — subscribed, no `State` yet (barrier not reached);
- *   `"synced"`    — first `State` received (barrier reached — the TRUTH signal);
- *   `"timed-out"` — the bounded fallback fired with NO `State` (open proceeded so
- *                   the read is never blocked, but this is NOT `"synced"`: a future
- *                   "ready" signal must not mistake a timeout for a real barrier);
- *   `"unknown"`   — never requested (or the fake-ng no-op path: no `State` semantics).
- * This distinction is the point — `"synced"` and `"timed-out"` are kept apart so a
- * later reactive readiness layer can trust `"synced"` and treat `"timed-out"` as
- * "opened best-effort, sync unconfirmed".
+ * ── Sync state (per-nuri, lib-internal, DERIVED) ──────────────────────────
+ * {@link getSyncState} computes a nuri's barrier state; nothing stores it:
+ *   `"syncing"`   - this module is inside its bounded wait, no `State` yet;
+ *   `"synced"`    - a `State` has arrived on the channel standing NOW (barrier reached,
+ *                   the TRUTH signal: a zero-row read over it MEANS zero);
+ *   `"timed-out"` - opened here, and no barrier to show for it: the wait gave up, the
+ *                   subscribe was refused, or the channel was taken away. The read is never
+ *                   blocked, but this is NOT `"synced"` - a readiness signal must not
+ *                   mistake either for a real barrier;
+ *   `"unknown"`   - never opened here (or the fake-ng no-op path: no `State` semantics).
+ * `"synced"` and `"timed-out"` are kept apart for that reason, and `"unknown"` is the one
+ * value that is deliberately treated as authoritative, because where there are no `State`
+ * semantics there is no barrier to have missed.
  *
  * ── Migration ─────────────────────────────────────────────────────────────
  * At the real multi-store migration this becomes "open the user's store repo by
@@ -74,33 +80,150 @@
 import { mustNotAttempt } from "./reach";
 import { fetchReadCap } from "./public-store";
 import { getConfig, getStoreRegistryDeps } from "../shared-wallet/bootstrap";
-import { resubscribeDocs, subscribeDocUnguarded, type Unsubscribe } from "../surface/subscribe";
-import { logStage, shortNuri } from "../shared-wallet/access-log";
+import { docChannel, resubscribeDocs, subscribeDocUnguarded, type Unsubscribe } from "../surface/subscribe";
+import { accessLogPrefix, logStage, shortNuri } from "../shared-wallet/access-log";
 import type { Nuri } from "../model/types";
 
 /**
- * The per-nuri bootstrap sync state (lib-internal). See the module header:
- *   - `"syncing"`   subscribed, first `State` not yet received;
- *   - `"synced"`    first `State` received — the real sync barrier (CONTRACT 3);
- *   - `"timed-out"` fallback fired without a `State` — open proceeded, sync UNconfirmed;
- * `"unknown"` (from {@link getSyncState}) means "never requested / no `State` semantics".
+ * The per-nuri bootstrap sync state (lib-internal), DERIVED on every read by
+ * {@link getSyncState} - nothing stores it. See the module header:
+ *   - `"syncing"`   inside the bounded wait, first `State` not yet received;
+ *   - `"synced"`    a `State` arrived on the channel standing NOW - the real sync barrier
+ *                   (CONTRACT 3);
+ *   - `"timed-out"` opened here with no barrier to show for it - the wait gave up, the
+ *                   subscribe was refused, or the channel was taken away. Sync UNconfirmed;
+ * `"unknown"` (from {@link getSyncState}) means "never opened here / no `State` semantics".
  */
 // @provenance SyncState kind=aligned level=1 ref=engine/net/src/app_protocol.rs:AppResponseV0 — the first `State` push IS the barrier; `timed-out` names the bounded fallback and is deliberately not `synced`
 export type SyncState = "syncing" | "synced" | "timed-out";
 
-/** Repos whose bootstrap open has completed (first `State` received OR timed out). */
-const opened = new Set<Nuri>();
-/** In-flight opens, so concurrent `ensureRepoOpen(nuri)` share one subscription. */
-const inFlight = new Map<Nuri, Promise<void>>();
-/** Live bootstrap subscriptions, kept for the session (this is what holds repos open). */
-const held = new Map<Nuri, Unsubscribe>();
-/** Explicit per-nuri sync state — the barrier signal, distinct from `opened`.
- *  `synced` and `timed-out` are NOT merged (see module header). */
-const syncState = new Map<Nuri, SyncState>();
-/** The session id the current `opened`/`held` entries belong to. A change means a
+/*
+ * THE INVARIANT, and it is the thing that went wrong six rounds running.
+ *
+ * **"Is this document open in this session" is answered in ONE place - the state of the
+ * document's one real subscription (`surface/subscribe.ts`, {@link docChannel}) - and this
+ * module records only the bootstrap open it ASKED FOR: the listener it took out and the
+ * bounded wait around it, never whether that listener became a live channel or crossed a
+ * barrier.** So no answer here can outlive the channel it describes, because none is kept.
+ *
+ * What that replaces, and why each had to go rather than be repaired:
+ *   - a `held` set of "live bootstrap subscriptions". It was written the moment
+ *     `subscribeDocUnguarded` returned, which is BEFORE the `doc_subscribe` behind it has
+ *     been placed - so it meant "we asked", the looser meaning an `opened` set had been
+ *     deleted for one round earlier. And `resetDocSubscriptions` (which PUBLISHED
+ *     `configure()` calls) drops every listener without a word, so it also survived the
+ *     teardown of the very subscription it named.
+ *   - a `syncState` map of barrier states. Same fate, one step worse: it kept saying
+ *     `"synced"` for a document whose channel had gone, and `"synced"` is AUTHORITY - a
+ *     zero-row read over it is a definitive absence. A read that had been correctly
+ *     withheld came back a success, for a document this session had never subscribed.
+ *
+ * Both facts live in the fan-out already and are forgotten there at exactly the right
+ * moments, which is what makes asking better than remembering: a channel released, a
+ * session changed under it, an establish refused.
+ *
+ * {@link getSyncState}'s four values are therefore DERIVED, and `"unknown"` still means one
+ * thing only: no barrier was ever expected here (never requested, or an `ng` with no
+ * `doc_subscribe` and so no `State` semantics). It never means "we forgot".
+ */
+/**
+ * The bootstrap open this module ASKED FOR - never a record of whether it succeeded.
+ *
+ * One per document, and its presence is the whole of what this module knows: *`open-repo`
+ * has opened this document in this session*. Everything else about it is a question for
+ * {@link docChannel}.
+ */
+interface BootstrapOpen {
+  /**
+   * The bounded wait this open exposes to its callers, resolved on the first `State`, on the
+   * fallback, on a refused subscribe, or by a reset. Concurrent callers join it rather than
+   * opening a second time - which is what an `inFlight` map used to do.
+   */
+  done: Promise<void>;
+  /**
+   * Release the bootstrap listener this open took out. `null` once it has been released -
+   * by a refused subscribe, or by {@link resetOpenedRepos} - and that is ALL it says: it
+   * answers "am I still listening", never "is this document open". The second question needs
+   * {@link docChannel} as well, because a listener can be dropped from under this module
+   * (`resetDocSubscriptions`) and nothing here would be told.
+   */
+  release: Unsubscribe | null;
+  /**
+   * WHICH fan-out {@link release}'s listener was added to (`surface/subscribe.ts`,
+   * {@link DocChannel.incarnation}).
+   *
+   * `release` alone does NOT answer "am I still listening", and believing it did was a defect of
+   * this repair's first draft: `resetDocSubscriptions()` - which the PUBLISHED `configure()`
+   * calls - drops every listener and deletes the entry, and nothing here is told. Held a
+   * non-null `release` against a fan-out somebody else had since created, this module skipped an
+   * open it owed and the document was left held by a listener free to leave.
+   */
+  incarnation: number;
+  /**
+   * How to END the wait from outside it - {@link resetOpenedRepos}, the only caller; `null`
+   * once the wait is over. An open normally settles on the first `State` or on its own
+   * bounded fallback, and both of those live inside the subscription; a reset tears that
+   * subscription down, so without this the open is left with nothing that can ever finish it
+   * but a timer whose whole purpose has gone.
+   */
+  settle: (() => void) | null;
+  /** Inside the bounded wait: no `State` yet, and the fallback has not fired. */
+  waiting: boolean;
+}
+/** Every document this module has opened in this session. See {@link BootstrapOpen}. */
+const opens = new Map<Nuri, BootstrapOpen>();
+/**
+ * A document this module opened and no longer holds anything for - what a reset leaves
+ * behind. It is deliberately NOT a deletion: forgetting it entirely would make
+ * {@link getSyncState} answer `"unknown"`, which means "no barrier was ever expected here"
+ * and is therefore read as authoritative. A document whose subscription a reset took away is
+ * the opposite of that.
+ *
+ * It is also the generation guard. A reset REPLACES the record rather than mutating it, so
+ * an open still running against the previous one compares `opens.get(nuri) !== mine` and
+ * writes nothing - object identity doing what a counter used to.
+ */
+function disowned(): BootstrapOpen {
+  return { done: Promise.resolve(), release: null, incarnation: 0, settle: null, waiting: false };
+}
+/** The session id the current {@link opens} entries belong to. A change means a
  *  new verifier session (fresh `self.repos`) → the registry must be invalidated. */
 let boundSessionId: string | number | null = null;
 
+/**
+ * Is this module's own bootstrap open still STANDING for `nuri` - so that a caller asking for an
+ * open has nothing to do?
+ *
+ * Three questions, and each catches a case the others cannot. Every one of them is asked of the
+ * thing that owns the answer rather than remembered here, which is the whole of this module's
+ * invariant.
+ *
+ *   - **do I hold a listener at all?** `release` is nulled by a refused subscribe and by
+ *     {@link resetOpenedRepos}. Without this a document whose subscription a reset took away
+ *     would never be re-held for the new session.
+ *   - **is that listener still in the fan-out that stands NOW?** `resetDocSubscriptions()` drops
+ *     every listener and deletes the entry without telling anybody, so `release` goes on looking
+ *     live; if something else has since subscribed to the same document, the channel is `"open"`
+ *     and the two questions above both pass while this module holds nothing. The document is then
+ *     kept open only by a listener that is free to leave.
+ *   - **does an attempt stand behind it?** A fan-out whose establish was REFUSED keeps its
+ *     listeners and stands for nothing; the next caller must subscribe again.
+ *
+ * An attempt that has not ANSWERED yet (`"opening"`) counts as standing, deliberately. A second
+ * `doc_subscribe` cannot be placed while one is in flight - the fan-out dedupes it, and upstream
+ * it would EVICT the first - so a fresh attempt here buys nothing and costs the caller the whole
+ * bounded fallback again, 8s in production, on every read of a document whose subscribe never
+ * answers. Asking live is what makes that safe: the moment the attempt stops standing this
+ * returns false, where a RECORD of openness written at the same moment would have stood for the
+ * session.
+ */
+function stillStanding(nuri: Nuri, open: BootstrapOpen | undefined): boolean {
+  if (open === undefined || open.release === null) return false;
+  const channel = docChannel(nuri);
+  if (channel.incarnation !== open.incarnation) return false;
+  return channel.state !== "none";
+}
+
 /**
  * Max wait (ms) for the initial-state push before proceeding with the read anyway.
  * The push normally lands quickly once the repo loads; the timeout only guards the
@@ -120,46 +243,86 @@ export function setOpenTimeoutForTests(ms: number): void {
   OPEN_TIMEOUT_MS = ms;
 }
 
-/** Reset the open registry (mainly for tests / a switched wallet). Tears down the
- *  held bootstrap subscriptions so a subsequent open re-subscribes cleanly. */
+/** Reset the open registry (mainly for tests / a switched wallet). Releases the bootstrap
+ *  listeners so a subsequent open takes out a new subscription, and DISOWNS the documents it
+ *  takes them from rather than forgetting them - see {@link disowned}. */
 // @provenance resetOpenedRepos kind=invention level=none ref=none — per-session bookkeeping reset; upstream the verifier owns `self.repos` and nothing resets it from outside
 export function resetOpenedRepos(): void {
-  for (const unsub of held.values()) {
+  for (const [nuri, open] of [...opens]) {
+    // Let the bootstrap listener go first: it is what held the repo open for the session
+    // that is ending, and a document nobody else follows is simply released.
     try {
-      unsub();
+      open.release?.();
     } catch {
       /* ignore */
     }
+    // END the open this reset abandons: a caller is already awaiting it, and the `State` it
+    // was waiting for cannot arrive now that the subscription has been torn down. It used to
+    // wait out the full fallback - eight seconds of a read going nowhere. Taken before the
+    // record is replaced, and called after, so the waiter's continuation finds the record
+    // already gone and writes nothing.
+    const settle = open.settle;
+    open.settle = null;
+    // DISOWNED rather than forgotten - see {@link disowned}. The barrier needs no downgrading
+    // of its own any more: it was never recorded here, and the fan-out forgets it on exactly
+    // these events.
+    opens.set(nuri, disowned());
+    // The wait's own end, not a shortcut past it: clearing `waiting` here instead would make
+    // this call a no-op and leave the caller hanging on a subscription that no longer exists -
+    // the eight-second read the abandoned-open fix exists to prevent.
+    settle?.();
   }
-  opened.clear();
-  inFlight.clear();
-  held.clear();
-  syncState.clear();
   boundSessionId = null;
   OPEN_TIMEOUT_MS = 8000;
-  // Whatever ELSE was still subscribed to a document — a `watchShape` following a scope,
-  // an inbox observation — belongs to the session that just went away too. One real
+  // Whatever ELSE was still subscribed to a document - an inbox observation, an
+  // application's own `subscribeDoc` - belongs to the session that just went away too. One real
   // subscription now serves all of them (`surface/subscribe.ts`), so dropping the bootstrap
   // ones above no longer closes those channels; they are re-opened against the new session,
   // with their barrier forgotten. Without this a bootstrap open would join a surviving
   // fan-out, be handed the PREVIOUS session's `State`, and call a repo the new session has
-  // never synced "synced". After the held teardown, so a document nobody else follows is
-  // simply released.
+  // never synced "synced". After the listeners above are released, so a document nobody else
+  // follows is simply released.
   resubscribeDocs();
 }
 
 /**
  * The bootstrap sync state of `nuri` (lib-internal accessor; NOT a reactive
- * app-facing hook — that is a later phase). Returns `"unknown"` if the repo was
- * never opened via {@link ensureRepoOpen} (or was opened on the fake-ng no-op
- * path, which has no `State` semantics). Otherwise `"syncing"` (subscribed, no
- * `State` yet), `"synced"` (first `State` received — the barrier), or
- * `"timed-out"` (fallback fired without a `State`). `"synced"` and `"timed-out"`
- * are deliberately distinct — a later readiness signal must not confuse them.
+ * app-facing hook - that is a later phase). **DERIVED on every call, never stored**: from the
+ * document's one real subscription ({@link docChannel}) and this module's record of having
+ * opened it. Returns `"unknown"` if the repo was never opened via {@link ensureRepoOpen} (or
+ * was opened on the fake-ng no-op path, which has no `State` semantics); `"synced"` once a
+ * `State` has arrived on the channel standing NOW - the barrier; `"syncing"` while the open is
+ * inside its bounded wait; and `"timed-out"` when it was opened here with no barrier to show
+ * for it, whether the fallback fired, the subscribe was refused, or the channel was taken
+ * away. `"synced"` and `"timed-out"` are deliberately distinct - a readiness signal must not
+ * confuse them - and deriving both is what stops either outliving its subscription.
  */
 // @provenance getSyncState kind=aligned level=1 ref=engine/net/src/app_protocol.rs:AppResponseV0 — reports whether the first `State` arrived; upstream this is not observable from JS
 export function getSyncState(nuri: Nuri): SyncState | "unknown" {
-  return syncState.get(nuri) ?? "unknown";
+  const channel = docChannel(nuri);
+  // The first `State` on the channel standing NOW. {@link docChannel} guarantees both halves -
+  // it does not report a barrier while no channel stands - so this asks the one question, and
+  // that is deliberate: a first draft of this repair re-imposed the second half HERE instead,
+  // which only MASKED a stale barrier rather than forgetting it. The next subscribe on the same
+  // fan-out brought it straight back, was replayed it, crossed its own barrier in 2ms on a
+  // `State` from a call that had FAILED, and answered `"synced"` - which is AUTHORITY, so
+  // `index-deposit.ts` `noRowsMeansAbsent` called a zero-row read a definitive absence and the
+  // deposit was destroyed. A guard at the reader cannot fix a fact that is wrong at the source.
+  //
+  // Asked of the fan-out rather than remembered, because that is the one record of it: a barrier
+  // is forgotten when its attempt fails, when its channel is released and when its session
+  // changes. Answered even for a document this module never opened - an application's own
+  // subscription crosses the same barrier, and `"synced"` is then simply true.
+  if (channel.barrierCrossed) return "synced";
+  const open = opens.get(nuri);
+  // Never opened here, or opened on the no-`doc_subscribe` path, which records nothing
+  // because there is no barrier to have missed.
+  if (open === undefined) return "unknown";
+  // Opened here, and no channel stands: the subscribe was refused, or a reset took it away,
+  // or `resetDocSubscriptions` dropped it from under us. Opened best-effort, sync UNconfirmed -
+  // never `"unknown"`, which is the reading that lets a zero-row read be called an absence.
+  if (channel.state === "none") return "timed-out";
+  return open.waiting ? "syncing" : "timed-out";
 }
 
 /**
@@ -187,8 +350,16 @@ async function syncSession(): Promise<void> {
  * `"synced"`). Idempotent: a repo already opened (or in flight) is not re-opened.
  *
  * Tolerant by construction: if the injected `ng` exposes no `doc_subscribe` (e.g.
- * the fake `ng` in the unit suite), this is a no-op — the read proceeds unchanged.
- * Never throws; a failed open just leaves the read to behave as it did before.
+ * the fake `ng` in the unit suite), this is a no-op - the read proceeds unchanged. The
+ * open itself never throws: a `doc_subscribe` that never pushes a `State` is bounded by
+ * the fallback timeout and leaves the read to behave as it did before.
+ *
+ * **It DOES throw when the public store could not be asked** (`1.0.0-dev.9`). That is the
+ * one step here that can fail to ANSWER, and until then it answered `false` - "this
+ * document exposes no cap" - so the open declined silently and the anchored read that
+ * followed refused the reader for holding no cap, which was true but was not the reason.
+ * A caller that means to carry on regardless says so with a `catch` of its own; none does
+ * today, because every one of them is about to read the document.
  *
  * `holderKey` names WHOSE possession decides, when it is not the connected identity's —
  * the emulated inbox processor opening an inbox repo for its owner during someone else's
@@ -204,7 +375,10 @@ export async function ensureRepoOpen(nuri: Nuri, holderKey?: string): Promise<vo
   // the outer overlay (`PublicRepoLinkV0`, `engine/net/src/types.rs:5098`). So ASK
   // before deciding whether we may touch it, or the answer would be "no" purely for
   // want of asking, and a bare reference to a public document would never suffice.
-  // Memoised and inert once the cap is held (see public-store.ts).
+  // Memoised and inert once the cap is held (see public-store.ts). REJECTS when the
+  // store could not be asked at all, which is deliberately not the same event as "this
+  // document exposes no cap": the open has not happened and the caller must not read as
+  // though it had.
   if (holderKey === undefined) await fetchReadCap(nuri);
   // RULE 2 — do not even attempt. Opening a repo IS an access: it subscribes and
   // pulls its state. A user that holds no cap for it has no business asking.
@@ -222,76 +396,129 @@ export async function ensureRepoOpen(nuri: Nuri, holderKey?: string): Promise<vo
 export async function openRepoUnguarded(nuri: Nuri): Promise<void> {
   // Drop the registry if the session changed (in-page re-login → fresh verifier).
   await syncSession();
-  if (opened.has(nuri)) return;
-  const pending = inFlight.get(nuri);
-  if (pending) return pending;
+  const standing = opens.get(nuri);
+  // A caller arriving while the bounded wait is still running JOINS it, and waits on the same
+  // barrier rather than stepping past it.
+  if (standing?.waiting === true) return standing.done;
+  // A caller arriving when this module's bootstrap open still STANDS has nothing to do - three
+  // questions, all asked live, enumerated on {@link stillStanding}.
+  if (stillStanding(nuri, standing)) return;
 
   // No reactive primitive on the injected ng (fake-ng unit suite): nothing to open,
   // no `State` to await → preserve the old immediate-resolve behaviour so `bun test`
-  // does not regress. No sync state is recorded (getSyncState → "unknown"): the fake
-  // path has no barrier semantics, and claiming "synced" here would be a lie.
+  // does not regress. No record is kept (getSyncState → "unknown"): the fake
+  // path has no barrier semantics, and claiming a barrier here would be a lie.
   const ng = getConfig().ng as { doc_subscribe?: unknown };
   if (typeof ng.doc_subscribe !== "function") {
-    opened.add(nuri);
+    // Nothing to open and nothing to record: there is no subscription to hold, so this
+    // document must stay out of `opens` or it would claim one - and `"unknown"` is exactly
+    // right here, the one place that MEANS "no barrier was ever expected".
     return;
   }
 
-  // Subscribed, first `State` not yet seen.
-  syncState.set(nuri, "syncing");
   // Barrier clock: how long the subscribe→first-State (or fallback) round-trip
   // took, surfaced on the BARRIER trace line below — the most important line in
   // the whole low-level data-path trace: it distinguishes a genuine absence
   // (`synced` → a 0-row read means it) from a not-yet-synced read (`timed-out`).
   const barrierStartedAt = Date.now();
+  // Published BEFORE the subscribe, so a concurrent caller joins this wait instead of opening
+  // a second time - and carrying nothing but the wait, because at this instant nothing is
+  // true yet. What the previous registry put here was a claim of openness.
+  const mine: BootstrapOpen = { done: Promise.resolve(), release: null, incarnation: 0, settle: null, waiting: true };
+  opens.set(nuri, mine);
 
-  const p = (async () => {
+  mine.done = (async () => {
     await new Promise<void>((resolve) => {
-      let settled = false;
-      // Resolve on the first `State` (the sync BARRIER), marking the nuri "synced".
+      // Stop waiting, once. Handed to `resetOpenedRepos` as well, so an open this session
+      // abandons can be ended rather than left hanging on a subscription that no longer
+      // exists.
+      const stopWaiting = (): void => {
+        if (!mine.waiting) return;
+        mine.waiting = false;
+        mine.settle = null;
+        resolve();
+      };
+      mine.settle = stopWaiting;
+      // The first `State` IS the barrier, WHENEVER it arrives - and it is the FAN-OUT that
+      // records it, not this module, so a `State` landing long after this wait gave up still
+      // counts and still turns `getSyncState` to `"synced"`. That used to need a write placed
+      // carefully above the already-settled check; there is nothing to place now.
       const onState = (): void => {
-        if (settled) return;
-        settled = true;
-        syncState.set(nuri, "synced");
-        logStage("BARRIER " + shortNuri(nuri) + " synced (" + (Date.now() - barrierStartedAt) + "ms)");
-        resolve();
+        if (mine.waiting) {
+          logStage("BARRIER " + shortNuri(nuri) + " synced (" + (Date.now() - barrierStartedAt) + "ms)");
+        }
+        stopWaiting();
       };
-      // Bounded fallback: proceed WITHOUT a `State`, but mark "timed-out" — NOT
-      // "synced". A genuinely-absent doc reads 0 rows anyway (same as before, never
-      // a hang); the distinct state keeps a future "ready" signal from lying.
+      // Bounded fallback: proceed WITHOUT a `State`. A genuinely-absent doc reads 0 rows
+      // anyway (same as before, never a hang); giving up the WAIT is not crossing the
+      // barrier, and `getSyncState` says so because the fan-out has no `State` to show.
       const onTimeout = (): void => {
-        if (settled) return;
-        settled = true;
-        syncState.set(nuri, "timed-out");
-        logStage("BARRIER " + shortNuri(nuri) + " timed-out (" + (Date.now() - barrierStartedAt) + "ms)");
-        resolve();
+        if (mine.waiting) {
+          logStage("BARRIER " + shortNuri(nuri) + " timed-out (" + (Date.now() - barrierStartedAt) + "ms)");
+        }
+        stopWaiting();
       };
-      // The bootstrap subscription is kept ALIVE for the session — holding it open
-      // is the whole point. We wait for the FIRST `State` event specifically (the
-      // barrier), NOT any push: the platform pushes `TabInfo` before `State`, and
-      // resolving on `TabInfo` would return before the real sync barrier.
-      // Unguarded on purpose: the caller already decided. `ensureRepoOpen` applied
-      // rule 2 above; `ensurePhysicalRepoOpen` is the machinery's door and is not
-      // subject to the boundary at all (see physical.ts).
-      const unsub = subscribeDocUnguarded(nuri, (_r, type) => {
-        if (type === "State") onState();
-      });
-      held.set(nuri, unsub);
+      // A failed establish is REPORTED, and `subscribe.ts` offers this channel precisely
+      // so that a caller can retry. Let the listener go, so the next caller opens a NEW
+      // subscription rather than joining a fan-out that is not going to push. There is no
+      // barrier state to correct: none was ever written here, and the fan-out has no `State`
+      // to show for a call that failed.
+      //
+      // NOT a substitute for the channel question above, and that is the lesson of this
+      // task: `subscribe.ts` reports a failure only for the attempt it is still WAITING ON,
+      // so a rejection arriving after `resetDocSubscriptions` released the fan-out is logged
+      // and nothing else. When the record was a claim of openness, that claim then stood for
+      // the whole session and no retry could ever get past it.
+      const onSetupFailed = (error: unknown): void => {
+        if (opens.get(nuri) !== mine) return;
+        console.error(accessLogPrefix() + " ensureRepoOpen: subscribe failed for " + shortNuri(nuri) + ":", error);
+        const listening = mine.release;
+        mine.release = null;
+        mine.incarnation = 0;
+        try {
+          listening?.();
+        } catch {
+          /* ignore */
+        }
+        stopWaiting();
+      };
+      // The bootstrap subscription is kept ALIVE for the session - holding it open is the
+      // whole point. It is a LISTENER on the document's one real subscription, which is why
+      // it says nothing about whether that subscription EXISTS: that is {@link docChannel}'s
+      // answer, and the two together are what `openRepoUnguarded` asks above.
+      //
+      // We wait for the FIRST `State` event specifically (the barrier), NOT any push: the
+      // platform pushes `TabInfo` before `State`, and resolving on `TabInfo` would return
+      // before the real sync barrier. Unguarded on purpose - the caller already decided:
+      // `ensureRepoOpen` applied rule 2, and `ensurePhysicalRepoOpen` is the machinery's door
+      // and is not subject to the boundary at all (see physical.ts).
+      mine.release = subscribeDocUnguarded(
+        nuri,
+        (_r, type) => {
+          if (type === "State") onState();
+        },
+        onSetupFailed,
+      );
+      // WHICH fan-out that listener went into, so this open can later tell whether it is still
+      // in the one that stands. Read straight back rather than assumed: the call above either
+      // joined an existing fan-out or created one.
+      mine.incarnation = docChannel(nuri).incarnation;
+      // A record this open REPLACED still holds a listener, and its wait is over - so nothing
+      // will ever release it. Done after the new listener has joined, so the fan-out keeps its
+      // entry and its establish, and this does not turn into a second `doc_subscribe` on a
+      // branch that already has one (which upstream would EVICT the first).
+      if (standing !== undefined && standing.release !== null) {
+        const superseded = standing.release;
+        standing.release = null;
+        standing.incarnation = 0;
+        try {
+          superseded();
+        } catch {
+          /* ignore */
+        }
+      }
       setTimeout(onTimeout, OPEN_TIMEOUT_MS);
     });
-    opened.add(nuri);
-    inFlight.delete(nuri);
   })();
-  inFlight.set(nuri, p);
-  return p;
-}
-
-/**
- * Open a SET of repos before an anchored batch read, in parallel, each tolerant
- * ({@link ensureRepoOpen} never throws). Empty / falsy entries are ignored.
- */
-// @provenance ensureReposOpen kind=aligned level=2 ref=sdk/js/lib-wasm/src/lib.rs:doc_subscribe — the batch form, with per-doc isolation
-export async function ensureReposOpen(nuris: Nuri[]): Promise<void> {
-  const unique = [...new Set(nuris.filter(Boolean))];
-  if (unique.length === 0) return;
-  await Promise.all(unique.map((n) => ensureRepoOpen(n)));
+  return mine.done;
 }

packages/polyfill/src/emulated-verifier/public-store.ts

@@ -102,10 +102,28 @@ import type { Nuri, ReadCap } from "../model/types";
  * The round-trip is what is worth saving, not the filing. So the memo holds the value and
  * the caller files it for whoever is connected, every time.
  *
- * A scope never changes here (a document is created in a store and stays there), so a
- * cached `null` cannot go stale for a document that existed when it was taken. It CAN for
- * one created afterwards in the same page — {@link resetPublicStoreFetches} is the way
- * out, and a session or wallet reset calls it.
+ * ── What may be memoised is an ANSWER — never a failure ───────────────────
+ * Two values are filed here, and each is safe to keep for its OWN reason:
+ *   - a **cap** — the document served it, and nothing withdraws it within a session;
+ *   - **`null`** — the document's Header branch was READ and carries no exposed cap: an
+ *     ESTABLISHED absence. Safe because a scope never changes here (a document is created
+ *     in a store and stays there), so that answer cannot go stale for a document that
+ *     existed when it was taken.
+ * A fetch that THREW is neither of those. The broker was not asked, or could not answer,
+ * and "no answer" is not "no cap" — so it is dropped from the map the moment it rejects
+ * and the next caller asks again. {@link downloadReadCap} is what keeps the two apart.
+ *
+ * That separation repairs a defect that stood until 2026-09-15: the download caught its
+ * own errors and returned the same `null` as a real absence, so ONE transient outage
+ * recorded "no capability" for that document for the rest of the session. Deposits being
+ * consumed, a deposit on that document was then retired before its arm could read
+ * anything — and every re-deposit sent to repair it met the same memoised `null` and was
+ * destroyed too. The justification above was written when `null` meant absence and
+ * ONLY absence; it was left standing when the `catch` gave the value a second meaning it
+ * never covered. It is now stated per value, so it cannot silently widen again.
+ *
+ * A cached absence CAN still go stale for a document created afterwards in the same page —
+ * {@link resetPublicStoreFetches} is the way out, and a session or wallet reset calls it.
  */
 const attempted = new Map<Nuri, Promise<ReadCap | null>>();
 
@@ -163,8 +181,21 @@ export async function exposeReadCap(doc: Nuri, cap: ReadCap): Promise<void> {
  * Nothing is asked when the cap is already held: a document you can read needs no
  * fetching, and skipping it keeps the ordinary path free of physical reads.
  *
- * Never throws — a document that is not in a public store simply answers nothing, which
- * is not an error but the normal case.
+ * **Two outcomes only, and a THIRD that is not an outcome.** `false` means the network
+ * answered and the document exposes no cap - an absence, and the normal case. `true` means
+ * a cap was obtained and filed. A download that REJECTED is neither: it REJECTS here too.
+ *
+ * It used to answer `false` for that as well, which is the defect this function was the
+ * head of. `false` then meant "no cap" to three call sites at once, and each of them
+ * turned a breakdown into a statement about the document: {@link ensureRepoOpen} declined
+ * to open and let the read that followed blame the reader for holding no cap, and
+ * `documentInboxAddress` answered "this document has no inbox", which an application reads
+ * as zero deposits. `downloadReadCap` below produces the distinction deliberately and says
+ * why; collapsing it one line later destroyed it. A failure must not read as an absence.
+ *
+ * The memo keeps the same asymmetry it always did, and it is now the same asymmetry: an
+ * absence is remembered, a failure is not (see the note on {@link attempted}), so the next
+ * caller asks the network again instead of replaying a rejection.
  */
 // @provenance fetchReadCap kind=declared-not-wired level=1 ref=engine/net/src/types.rs:PublicRepoLinkV0 — the type DECLARES the cap is downloaded from the outer overlay if the brokers allow; it is constructed nowhere, both `PinRepo` constructors hard-code `expose_outer: false`, and `ExtTopicSyncReq` is `unimplemented!()`
 export async function fetchReadCap(docLike: Nuri): Promise<boolean> {
@@ -179,8 +210,44 @@ export async function fetchReadCap(docLike: Nuri): Promise<boolean> {
   if (pending === undefined) {
     pending = downloadReadCap(doc);
     attempted.set(doc, pending);
+    // A failure is not an answer, so it must not be filed as one: drop the memo the
+    // moment the download rejects, and the next caller reaches the broker again. The
+    // report stays even though the rejection now reaches the caller: this handler runs
+    // once per download however many callers shared it, and it runs at all when every one
+    // of them has given up, which is the only trace left in that case.
+    // Attached HERE — once per download, before anybody awaits — so the eviction and the
+    // report each happen exactly once however many callers share this one in-flight
+    // fetch, and happen at all even if every one of them has already given up. The
+    // identity check is what keeps it from evicting a LATER attempt: by the time a
+    // rejection lands, the map may already hold a fresh promise for this document.
+    const started = pending;
+    void started.catch((error: unknown) => {
+      if (attempted.get(doc) === started) attempted.delete(doc);
+      console.error(accessLogPrefix() + " fetchReadCap failed:", error);
+    });
+  }
+  let cap: ReadCap | null;
+  try {
+    cap = await pending;
+  } catch (error) {
+    // The download REJECTED: the repo would not open, the broker did not answer, the read
+    // threw. Whether this document may be read is UNKNOWN, and that is not what `false`
+    // says. Rethrown rather than returned so the caller's read fails instead of continuing
+    // on a document it never obtained anything for - upstream's observable is that a read
+    // rejects or it does not, and this is the side of it that was missing.
+    //
+    // Wrapped so the reason survives the trip: the message a caller would otherwise meet
+    // is `assertMayReach`'s "you do not hold this document's cap", which is a different
+    // event calling for a different action (give up, rather than retry). The original is
+    // on `cause`, and the handler attached where the download started has already logged
+    // it and dropped the memo, so the next caller asks the network again.
+    throw new Error(
+      "[ng-eventually] fetchReadCap: the public store could not be asked for this " +
+        "document's read cap, so whether it may be read is UNKNOWN - this is not " +
+        `"the document exposes no cap". ${JSON.stringify(doc)}`,
+      { cause: error },
+    );
   }
-  const cap = await pending;
   if (cap === null) return false;
   // Filed for whoever is connected NOW, on every call — the memo spares the round-trip,
   // not the filing. See the note on {@link attempted}.
@@ -189,44 +256,46 @@ export async function fetchReadCap(docLike: Nuri): Promise<boolean> {
   return true;
 }
 
-/** The fetch itself, through the machinery's door. Returns the cap, or `null` when the
- *  document is not in a public store — which is the normal case, not an error. */
+/**
+ * The fetch itself, through the machinery's door. **Two outcomes, deliberately not one** —
+ * telling them apart is this function's whole shape:
+ *
+ * - it **resolves** — the Header branch was READ. With the cap when the document exposes
+ *   one; with `null` when it does not, which is the normal case and not an error. Either
+ *   way the network answered, so the value is an answer and {@link attempted} may keep it.
+ * - it **rejects** — the question could not be put at all: the repo would not open, the
+ *   broker did not answer, the read threw. That is "no answer", not "no cap", and
+ *   {@link fetchReadCap} keeps it out of the memo for exactly that reason.
+ *
+ * So nothing is caught here. It used to be, and the two collapsed into the same `null`.
+ */
 async function downloadReadCap(doc: Nuri): Promise<ReadCap | null> {
   const s = await session();
-  try {
-    // The repo has to be in the session before an anchored read resolves it — the
-    // cold-start heal, through the PHYSICAL door: this is the emulated broker serving
-    // an outer overlay, and it does not ask who is asking (see `open-repo.ts`).
-    await ensurePhysicalRepoOpen(doc);
-    const res = await physicalQuery(
-      s.sessionId,
-      `SELECT ?c WHERE { <${HEADER_BRANCH_SUBJECT}> <${P.exposedReadCap}> ?c }`,
-      undefined,
-      doc,
-      "fetchReadCap",
-    );
-    for (const row of readBindings(res)) {
-      const cap = bindingValue(row, "c");
-      // `targetOf` guards the one confusion that would matter: a cap exposed on
-      // document A must not file a cap for document B. A document only ever speaks
-      // for itself.
-      if (cap && hasReadCap(cap) && targetOf(cap) === doc) return cap;
-    }
-  } catch (error) {
-    // Not in a public store, not synced, or no such document — all of them mean the
-    // same thing to the caller: no cap was obtained.
-    console.error(accessLogPrefix() + " fetchReadCap failed:", error);
+  // The repo has to be in the session before an anchored read resolves it — the
+  // cold-start heal, through the PHYSICAL door: this is the emulated broker serving
+  // an outer overlay, and it does not ask who is asking (see `open-repo.ts`).
+  await ensurePhysicalRepoOpen(doc);
+  const res = await physicalQuery(
+    s.sessionId,
+    `SELECT ?c WHERE { <${HEADER_BRANCH_SUBJECT}> <${P.exposedReadCap}> ?c }`,
+    undefined,
+    doc,
+    "fetchReadCap",
+  );
+  for (const row of readBindings(res)) {
+    const cap = bindingValue(row, "c");
+    // `targetOf` guards the one confusion that would matter: a cap exposed on
+    // document A must not file a cap for document B. A document only ever speaks
+    // for itself.
+    if (cap && hasReadCap(cap) && targetOf(cap) === doc) return cap;
   }
   return null;
 }
 
-/**
- * Ask for a SET of documents' caps, in parallel — what a batch read does before it
- * decides which documents it may touch. Each fetch is independent and tolerant.
- */
-// @provenance fetchReadCaps kind=declared-not-wired level=1 ref=engine/net/src/types.rs:PublicRepoLinkV0 — the batch form of the same unwired mechanism
-export async function fetchReadCaps(docs: Nuri[]): Promise<void> {
-  const unique = [...new Set(docs.filter(Boolean))];
-  if (unique.length === 0) return;
-  await Promise.all(unique.map((d) => fetchReadCap(d)));
-}
+// `fetchReadCaps(docs)` was REMOVED in `1.0.0-dev.9`. It was the batch form - a
+// `Promise.all` over the singular, described as "independent and tolerant" - and it had
+// ZERO callers, the last one having gone with `readUnion` in `1.0.0-dev.8`. Keeping it
+// would have left an unowned tolerance policy standing over a call that now rejects:
+// "each fetch is independent" is exactly the skip-and-carry-on this line of work has
+// removed twice. Whoever needs several caps asks for each, at the call site that knows
+// what a missing one costs it. Internal throughout, so nothing published moves.

packages/polyfill/src/emulated-verifier/reach.ts

@@ -165,7 +165,7 @@ export async function assertMayWrite(nuri: Nuri, op: string): Promise<void> {
 }
 
 /**
- * **Rule 2 — do not even attempt**, at the CALLERS (`read-model`, `open-repo`,
+ * **Rule 2 — do not even attempt**, at the CALLERS (`open-repo`,
  * `subscribe`'s callers…).
  *
  * A reader that does not hold a document's cap must not issue the operation at all.

packages/polyfill/src/emulated-verifier/read-filter.ts

@@ -16,12 +16,24 @@
  * ── What this filter cannot do, and where that shows ──────────────────────
  * It is SYNCHRONOUS and decides from what the holder holds at that instant. A document
  * in a PUBLIC store hands its cap to whoever asks (`public-store.ts`), but asking is a
- * round-trip — so this view drops such a document until some read path has asked.
- * Every path this library owns does ask (`readUnion`, `docs.sparqlQuery`,
- * `ensureRepoOpen`, `documentInboxAddress`), which covers `watchShape`; what it does
- * not cover is `useShape`, whose signature is the real ORM's and has no await to
- * spend. An application reaching a public document through `useShape` alone, having
- * read it nowhere first, sees nothing. A polyfill-era limit, removed with the module.
+ * round-trip - so this filter drops such a document until some read path has asked.
+ * The paths that DO ask are the ones this library still reads with (the anchored
+ * document read, `docs.sparqlQuery`, `ensureRepoOpen`, `documentInboxAddress`) and,
+ * since `1.0.0-dev.9`, `useShapeQuery` for every document its scope NAMES - it crosses
+ * the same barrier on each before the query opens, so a named public document is held
+ * by the time this filter sees its objects.
+ *
+ * `useShape` still asks nothing - its signature is the real ORM's and has no await to
+ * spend - and neither read asks anything under `did:ng:i`, where the scope names no
+ * document to ask about and this filter is the whole of the answer. An application
+ * reaching a public document through one of those alone, having read it nowhere first,
+ * sees nothing until it does - and a cap that lands later makes both re-publish, since
+ * each follows `CapRegistry.onChange`. A polyfill-era limit, removed with the module.
+ *
+ * Note what the barrier does NOT make redundant here. Under `did:ng:i` this filter is
+ * the only thing standing between the caller and every identity's objects, and even on
+ * a named scope it keeps the answer honest per `@graph` for whatever else the engine
+ * returned. Refusing at the ASK and filtering the RESULT are two different questions.
  *
  * Note there is no `user` parameter anywhere below, and that is the point: reading
  * is key possession, so the only question askable is "do I hold this document's
@@ -61,6 +73,262 @@ export function filterReadable<T>(items: Iterable<T>, caps: CapRegistry): T[] {
   return out;
 }
 
+/**
+ * Is this value a primitive? Used where the question really is "can this hold a reference",
+ * never as a licence to pass a member through - see {@link answerUndecidedMember}.
+ *
+ * `null` is a primitive in the model and `typeof null` is `"object"`, so it is named.
+ */
+function cannotReachAnItem(v: unknown): boolean {
+  return v === null || (typeof v !== "object" && typeof v !== "function");
+}
+
+/**
+ * WHAT THIS VIEW DISCLOSES BESIDE THE ITEMS, said exactly rather than claimed away.
+ *
+ * A member the target does not carry answers `undefined` (see {@link answerUndecidedMember}),
+ * so a caller can tell a key the SDK has from one it does not: `view.by_a` refuses where
+ * `view.by_zzz` answers. That is deliberate, not an oversight - refusing a member nobody
+ * ships would refuse a question nobody asked - and it discloses the SDK's PUBLISHED SHAPE,
+ * which is in the package, not the holder's data.
+ *
+ * It is not a count channel either, and that is MEASURED rather than assumed: on every
+ * shape that ships, no key's PRESENCE depends on the items. `Object.keys(deepSignal(new
+ * Set(...)))` is empty whatever the set holds, and the array form's own keys are its
+ * indices, which this view projects onto the readable ones. If a future collection grew a
+ * key per item, that presence would become a count and this note is where to come back to.
+ */
+
+/** What a refused member says. One wording for both shapes of refusal, so that a report of
+ *  either is greppable as the same event. */
+function refusalOf(prop: string | symbol, where: string): Error {
+  return new Error(
+    `[ng-eventually] read filter: \`${String(prop)}\` is not filtered, so reading it ` +
+      "would return items this identity may not read. Add it to " +
+      `\`emulated-verifier/read-filter.ts\` (${where}), filtered \u2014 do not bypass the view.`,
+  );
+}
+
+/** What a WRITE across the boundary says. Worded like `emulated-verifier/reach.ts`, which
+ *  refuses the same thing on the paths that still go through `sparql_update` - the ORM's
+ *  own writes do not, which is why this view is the only door on this one. */
+function writeRefusalOf(item: unknown): Error {
+  const doc = docOf(item);
+  return new Error(
+    doc === null
+      ? "[ng-eventually] read filter: refused - this object names no document in `@graph`, " +
+        "so there is no document that owns it and nothing to check a cap against: it would " +
+        "land in the collection every identity shares. Set `@graph` to a document you hold."
+      : "[ng-eventually] read filter: refused - this identity does not hold the cap of the " +
+        "document this object names, so writing it there is a write into a document it " +
+        `cannot read. Naming a document does not grant access to it. ${JSON.stringify(doc)}`,
+  );
+}
+
+/**
+ * The answer for a member this file has NOT DECIDED: refuse it, whatever its type.
+ *
+ * ── Why the type-based default was wrong, and what replaces it ────────────
+ * It used to be "a primitive cannot reach an item, so it passes". That is false, and the
+ * file already knew it: a COUNT is a primitive that describes the items, which is why
+ * `size` and `length` are computed rather than forwarded. Anything spelled otherwise went
+ * straight through - measured 2026-09-24, a holder who may read one of three items read
+ * `totalCount` as 3 - and `@ng-org/orm` already ships `pageSize`, `maxActivePages` and
+ * `nextPage`, so a total-count member is an ordinary next bump rather than a hypothesis.
+ *
+ * There is NO TYPE-LEVEL TEST that separates a primitive which is a value from one derived
+ * from the collection: a number is a number, and nothing observable about a getter says
+ * whether its 7 counts items or echoes a page size. Said plainly because the previous
+ * answer pretended otherwise - and because the repair is not another name in a list.
+ *
+ * So the default inverts. **What this file has decided, it serves; everything else it
+ * refuses**, primitive or not. That is safe for a shape nobody has seen BY CONSTRUCTION,
+ * which a passing default never was: what the next version adds refuses, loudly, naming
+ * itself. The prohibition worth keeping is on a list that lets unknowns THROUGH - that one
+ * breaks silently on a bump, which is how this whole defect arrived.
+ *
+ * One thing is not a refusal: a member the target does NOT CARRY answers `undefined`,
+ * because the SDK offers no such member and there is nothing behind it to derive anything
+ * from. What that discloses, and what it does not, is set out above.
+ *
+ * Note what is NOT here any more. A carve-out used to forward the target's own value for
+ * `Symbol.toStringTag` and `Symbol.isConcatSpreadable`, on the ground that the ECMAScript
+ * specification closes that key set. It closes the KEYS; it says nothing about the VALUES,
+ * so a tag implemented as a getter returning `Set(${size})` would have published the
+ * unfiltered count through a key this file had called harmless. Those two are DECIDED in
+ * the collection view now, with values the view computes from the shape it wraps.
+ *
+ * A function is refused AT THE CALL rather than at the read, which is not politeness: a
+ * function value is read by things that never call it - a logger, a devtools inspection, a
+ * `typeof` guard - and refusing those would be refusing a question nobody asked.
+ */
+function answerUndecidedMember(target: object, prop: string | symbol, where: string): unknown {
+  if (!(prop in target)) return undefined;
+  const v = Reflect.get(target, prop, target);
+  if (typeof v === "function") {
+    return () => {
+      throw refusalOf(prop, where);
+    };
+  }
+  throw refusalOf(prop, where);
+}
+
+/** `"0"`, `"12"` - an array index, in the canonical form a property key takes. */
+const INDEX = /^(0|[1-9][0-9]*)$/;
+
+/**
+ * The traps that stop a WRITE reaching the object underneath, written ONCE and spread into
+ * both views.
+ *
+ * Written once because the last three defects in this file were all one shape: a rule
+ * applied in one of two places. These five were added to the collection view and not to the
+ * envelope, so on the result object `delete result.data` succeeded, `result.isLoading = x`
+ * wrote to the SDK's own object, and `Object.setPrototypeOf` / `Object.preventExtensions`
+ * reached it too - the very pair the round before had found and trapped, on one view of
+ * two. A spread object cannot be added to one and forgotten on the other.
+ *
+ * Nothing legitimate is lost on either: a caller mutates an ITEM (handed out whole, and
+ * only when readable) or calls a member; writing to the view's own properties is not a
+ * gesture the SDK or this surface offers.
+ */
+const writeTraps: Pick<
+  ProxyHandler<object>,
+  "set" | "deleteProperty" | "defineProperty" | "setPrototypeOf" | "preventExtensions"
+> = {
+  set(_target, prop) {
+    throw refusalOf(prop, "a write to the view itself");
+  },
+  deleteProperty(_target, prop) {
+    throw refusalOf(prop, "a write to the view itself");
+  },
+  defineProperty(_target, prop) {
+    throw refusalOf(prop, "a write to the view itself");
+  },
+  // The two that reach the target without naming a property: `setPrototypeOf` replaced the
+  // real collection's prototype, after which iterating it throws for EVERY identity, and
+  // `preventExtensions` - what `Object.freeze` begins with - both writes to the target and
+  // strands the index projection, which is only lawful while the target is extensible.
+  setPrototypeOf() {
+    throw refusalOf("the prototype", "a write to the view itself");
+  },
+  preventExtensions() {
+    throw refusalOf("extensibility", "a write to the view itself");
+  },
+};
+
+/**
+ * The members `@ng-org/alien-deepsignals` declares NON-MUTATING, restated.
+ *
+ * Restated rather than imported, and not by preference: the package's `exports` map has no
+ * subpath for `iteratorHelpers`, so the three sets are unreachable from outside it - and a
+ * runtime `@ng-org` import has no business in `src/` anyway, where every `@ng-org` package
+ * is an OPTIONAL peer dependency. What keeps a restatement from drifting is a gate, not
+ * care: `test/read-filter.test.ts` reads the shipped `dist/iteratorHelpers.js` and fails if
+ * these lists and upstream's have parted company.
+ *
+ * Why they are here at all: every one of them is a READ over the collection, so every one
+ * of them is this view's business. Refusing them - which is what an unlisted member gets -
+ * took 18 declared members of an ordered result away from the holder whose data it is.
+ * `Symbol.toString` appears in upstream's own lists and is not a symbol at all
+ * (`Symbol.prototype.toString`); it is left out here rather than copied, since it can never
+ * be a property key.
+ */
+export const ITERATOR_HELPERS: ReadonlySet<string> = new Set([
+  "drop", "every", "filter", "find", "flatMap", "forEach", "includes", "map", "reduce",
+  "some", "take", "toArray",
+]);
+/** Upstream's array-only additions; the full set is these plus {@link ITERATOR_HELPERS}. */
+export const NON_MUTATING_ARRAY_ONLY: ReadonlySet<string> = new Set([
+  "at", "concat", "entries", "findIndex", "findLast", "findLastIndex", "flat", "indexOf",
+  "join", "keys", "lastIndexOf", "reduceRight", "toLocaleString", "toReversed", "toSorted",
+  "toSpliced", "slice", "values", "with",
+]);
+
+/**
+ * The ONE member upstream lists as non-mutating that is not: `Array.prototype.copyWithin`
+ * WRITES.
+ *
+ * ── What was recorded here, and what is actually true ─────────────────────
+ * This note used to say upstream's own `readOnlyArray` throws on reading `copyWithin`, so
+ * that refusing it merely matched the target. That was reasoned, not run, and it is FALSE.
+ * Measured against the installed package:
+ *
+ *     ro.copyWithin            -> function          (no throw on the read)
+ *     ro.copyWithin(0, 1)      -> ["B","C","C"]     (from ["A","B","C"] - the first
+ *                                                    element is DESTROYED)
+ *     ro.push / splice / sort / reverse / fill / shift
+ *                              -> THROWS on the READ:
+ *                                 "Readonly arrays do not expose non-mutating..."
+ *
+ * So `readOnlyArray` refuses every mutator it knows about - and `copyWithin` escapes that
+ * refusal for exactly the reason it is named here: it sits in the same mislabelled list the
+ * refusal is built from. Upstream's list and upstream's guard agree with each other and are
+ * both wrong.
+ *
+ * Refusing it is therefore MORE protective than the target, not equal to it: a deliberate
+ * divergence, recorded as one. The alternative is worse - serving it over the snapshot made
+ * it succeed and discard in silence, which teaches a caller that a write worked. Named here
+ * rather than dropped quietly, because the parse gate in `test/read-filter.test.ts` pins
+ * this exception by identity and cardinality.
+ */
+export const UPSTREAM_MISLABELLED_AS_NON_MUTATING: ReadonlySet<string> = new Set(["copyWithin"]);
+/** Upstream's set-only additions - the ES2025 combinators, which need a real `Set` to run
+ *  on, plus the pair spellings handled explicitly below. */
+export const NON_MUTATING_SET_ONLY: ReadonlySet<string> = new Set([
+  "difference", "entries", "has", "intersection", "isDisjointFrom", "isSubsetOf",
+  "isSupersetOf", "keys", "symmetricDifference", "union", "values",
+]);
+
+/**
+ * The descriptor of a member, filtered the same way reading it is.
+ *
+ * `Object.getOwnPropertyDescriptor` and everything built on it - `Object.keys`,
+ * `Object.entries`, a spread, `JSON.stringify`, a console inspection - read a property
+ * WITHOUT going through the `get` trap. A view that filtered `get` alone therefore handed
+ * the raw value straight back to whoever asked for the descriptor instead: measured
+ * 2026-09-24 on the first fix of this file, where `getOwnPropertyDescriptor(result, "data")`
+ * returned the unfiltered collection and `...(result, "subscription")` the ORM handle that
+ * `get` refuses. A second door into the same room, opened by a trap nobody wrote.
+ *
+ * So the descriptor is answered by REREADING through the view: `read` is the very function
+ * the `get` trap calls, passed in, so the two cannot drift apart. A member `get` refuses
+ * throws here too, at the same place and with the same message.
+ */
+function filteredDescriptor(
+  target: object,
+  prop: string | symbol,
+  read: () => unknown,
+): PropertyDescriptor | undefined {
+  const d = Reflect.getOwnPropertyDescriptor(target, prop);
+  if (d === undefined) return undefined;
+  // AN ACCESSOR. It carries no value of its own, and that is exactly why handing it back
+  // untouched was a door around the view: the getter behind it reads the TARGET. Measured
+  // 2026-09-24 on an envelope whose `data` is a getter - `v.data` came back filtered and
+  // `Object.getOwnPropertyDescriptor(v, "data").get()` came back raw. Not reachable on the
+  // shape that ships, where all six members report data descriptors or none; reachable on
+  // the next one, which is the whole claim this file makes. The getter is re-pointed at
+  // the view's own read, and a setter is refused: this view makes no promise about writes.
+  if (!("value" in d)) {
+    if (d.configurable !== true) throw refusalOf(prop, "its descriptor");
+    const routed: PropertyDescriptor = { ...d };
+    if (typeof d.get === "function") routed.get = (): unknown => read();
+    if (typeof d.set === "function") {
+      routed.set = (): never => {
+        throw refusalOf(prop, "its descriptor");
+      };
+    }
+    return routed;
+  }
+  const value = read();
+  if (Object.is(d.value, value)) return d;
+  // A property that is neither configurable nor writable cannot be REPORTED with another
+  // value without breaking the invariants a proxy is held to, and reporting the target's
+  // would be the leak. Nothing on either shape this file wraps is one - a result object's
+  // members and an array's indices are both - so this is a guard, not a path.
+  if (d.configurable !== true && d.writable !== true) throw refusalOf(prop, "its descriptor");
+  return { ...d, value };
+}
+
 /**
  * A read-filtered VIEW over a reactive set (a `DeepSignalSet`, or any Set-like).
  *
@@ -83,99 +351,490 @@ export function filterReadable<T>(items: Iterable<T>, caps: CapRegistry): T[] {
  * hits it exactly what to do: add the member here, filtered. A boundary whose unknown
  * cases leak is not a boundary.
  *
- * Everything that is not a function passes through untouched (`size` is handled above):
- * a plain property carries no items.
+ * ── And `get` is not the only door ────────────────────────────────────────
+ * Four traps answer the same question and all four have to give the same answer:
+ * `get`, `getOwnPropertyDescriptor` (which `Object.keys`, a spread, `JSON.stringify` and
+ * any console inspection go through, WITHOUT touching `get`) and, on the array form,
+ * `has` and `ownKeys`. Each of them was forwarding to the target while `get` filtered.
+ * `get` and `getOwnPropertyDescriptor` are wired to one `read` function below rather than
+ * to two copies of the rule; `has` and `ownKeys` answer positions rather than values, so
+ * they do not go through `read` but project from the same `kept` set it reads - which is
+ * what makes the four agree. Not one funnel, then, but one SOURCE: a boundary made of
+ * parallel switch statements is a boundary that drifts, and so is a header that claims a
+ * funnel it does not have.
+ *
+ * ── The default: DECIDED, or refused ─────────────────────────────────────
+ * Every member this file serves is named below. Anything else refuses, whatever its type.
+ * That is the whole rule, and {@link answerUndecidedMember} is where it lives.
+ *
+ * Two earlier defaults are gone, and both are worth knowing because each read as obviously
+ * sound when it was written:
+ *   1. "a plain property carries no items" - true of the object that happened to be wrapped
+ *      then, and false the moment the wrapped object changed, when three plain properties
+ *      each carried every identity's items ({@link makeReadFilteredShapeResult});
+ *   2. "a primitive cannot reach an item, so it passes" - false because a COUNT is a
+ *      primitive that DESCRIBES the items. The file already contradicted itself on this:
+ *      `size` and `length` were computed, so a third spelling of the same number went
+ *      through raw.
+ *
+ * There is no type-level test that separates a primitive which is a value from one derived
+ * from the collection - a number is a number - so the default cannot be a type at all. What
+ * makes the current one safe for a shape nobody has seen is not that it classifies
+ * correctly, but that it refuses: a member the next version adds says so, loudly, naming
+ * itself.
  */
 // @provenance makeReadFilteredView kind=aligned level=1 ref=engine/verifier/src/verifier.rs:load_repo_from_read_cap — the same filter as a live view over a reactive set; removed at migration
 export function makeReadFilteredView<S extends object>(set: S, caps: CapRegistry): S {
   const keep = (item: unknown): boolean => readable(item, caps);
+  /**
+   * May this identity WRITE this object into the collection?
+   *
+   * NOT {@link readable}, and the difference is the whole of the finding it answers. On the
+   * READ side an item with no `@graph` is kept, because it names no document and so there
+   * is no cap to ask about. On the WRITE side that reading makes the gate VACUOUS: an
+   * object carrying no `@graph` named no document, so it passed, landed in the collection
+   * every identity shares and became visible to all of them. The only thing stopping the
+   * plant was UPSTREAM raising "The object's @graph is missing and could not be inferred"
+   * - a guarantee borrowed from the target, which is exactly what this file removed for
+   * `set`/`deleteProperty` one round earlier and then left standing here.
+   *
+   * So a write must NAME a document and the holder must hold it.
+   */
+  const writable = (item: unknown): boolean => {
+    const doc = docOf(item);
+    return doc !== null && caps.capFor(doc) !== undefined;
+  };
   /** The readable items, as a plain array — what every handled member works from. */
   const kept = (target: object): unknown[] => {
     const out: unknown[] = [];
     for (const item of target as Iterable<unknown>) if (keep(item)) out.push(item);
     return out;
   };
-  return new Proxy(set, {
-    get(target, prop, receiver) {
-      if (prop === Symbol.iterator) return function* () { yield* kept(target); };
-      if (prop === "size") return kept(target).length;
-      // A Set yields the item for both halves of a `[key, value]` pair; `DeepSignalSet`
-      // follows the same shape, so `keys`/`values`/`entries` are the Set contract.
-      if (prop === "values" || prop === "keys") return () => kept(target)[Symbol.iterator]();
-      if (prop === "entries") return () => kept(target).map((i) => [i, i] as const)[Symbol.iterator]();
-      if (prop === "forEach") {
-        return (cb: (v: unknown, v2: unknown, s: unknown) => void) => {
-          for (const item of kept(target)) cb(item, item, receiver);
-        };
-      }
-      // `has(item)` is filtered, not forwarded: the caller already holds the item, so the
-      // answer discloses nothing new — but upstream an unreadable item is never delivered
-      // at all, so "yes it is in there" would be an answer the target cannot give.
-      if (prop === "has") return (item: unknown) => keep(item) && (target as Set<unknown>).has(item);
-      // The reactive-set extras: they iterate, so they must iterate the filtered items.
-      // The list is `iteratorHelperKeys` from `@ng-org/alien-deepsignals` — an earlier
-      // pass whitelisted half of it and threw on the rest, so a holder's calls on their
-      // OWN data crashed (`toArray`, `reduce`, `first`…). Filtering is the answer for all
-      // of them; refusing is only for what is not on this list.
-      if (prop === "map") return (fn: (v: unknown, i: number) => unknown) => kept(target).map(fn);
-      if (prop === "filter") return (fn: (v: unknown, i: number) => boolean) => kept(target).filter(fn);
-      if (prop === "find") return (fn: (v: unknown, i: number) => boolean) => kept(target).find(fn);
-      if (prop === "some") return (fn: (v: unknown, i: number) => boolean) => kept(target).some(fn);
-      if (prop === "every") return (fn: (v: unknown, i: number) => boolean) => kept(target).every(fn);
-      if (prop === "toArray") return () => kept(target);
-      if (prop === "first") return () => kept(target)[0];
-      if (prop === "take") return (n: number) => kept(target).slice(0, n);
-      if (prop === "drop") return (n: number) => kept(target).slice(n);
-      if (prop === "flatMap") return (fn: (v: unknown, i: number) => unknown) => kept(target).flatMap(fn as never);
-      if (prop === "reduce") {
-        return (fn: (acc: unknown, v: unknown, i: number) => unknown, init?: unknown) =>
-          init === undefined
-            ? kept(target).reduce(fn as never)
-            : kept(target).reduce(fn as never, init);
-      }
-      if (prop === "getById" || prop === "getBy") {
-        const inner = Reflect.get(target, prop, target) as ((...a: unknown[]) => unknown) | undefined;
-        if (typeof inner !== "function") return inner;
-        return (...args: unknown[]) => {
-          const item = inner.apply(target, args);
-          return keep(item) ? item : undefined;
-        };
-      }
+  /**
+   * Is the collection ARRAY-shaped? An `orderBy` config makes upstream's `signalObject` a
+   * `DeepSignal<ReadOnlyArray>` instead of a `DeepSignalSet`, and an array is addressed by
+   * INDEX and counts itself with `length`. Decided from the target once, so the view never
+   * grows a member the collection it wraps does not have.
+   *
+   * MEASURED against the real `@ng-org/alien-deepsignals` rather than assumed, because the
+   * collection is itself a proxy and what it answers for a key it does not carry is its
+   * business: `deepSignal(new Set(...)).length` is `undefined` and its `Object.keys` is
+   * empty, while `deepSignal([...]).length` is a number. So the set form never enters this
+   * branch, and the set form is also the one with no key naming an item to project.
+   */
+  const arrayLike = typeof (set as { length?: unknown }).length === "number";
+  /** The index a key names, or `null` when it names no position in this collection. */
+  const indexOf = (prop: string | symbol): number | null =>
+    arrayLike && typeof prop === "string" && INDEX.test(prop) ? Number(prop) : null;
 
-      // MUTATIONS forward untouched. They take an item and return void or a boolean, so
-      // they yield nothing to leak — and the view must not break writes or the underlying
-      // reactivity. (Caught by `test/read-filter.test.ts` when the blanket refusal below
-      // was first written: refusing everything unknown also refused `add`.)
-      if (prop === "add" || prop === "delete" || prop === "clear") {
-        const fn = Reflect.get(target, prop, target);
-        return typeof fn === "function" ? fn.bind(target) : fn;
-      }
+  /**
+   * The view itself, held in a box because it does not exist yet when the traps below are
+   * written. It is assigned on the line after the proxy is built, and a trap only runs on
+   * a property access, so nothing can read it before.
+   *
+   * It is needed because a member may hand the COLLECTION back - `Set.prototype.add`
+   * returns `this` so calls chain, and the real `DeepSignalSet` does the same (both
+   * measured). Handing that back is handing over every identity's items, so what goes
+   * back is the view. Never `receiver`: the descriptor trap reads a member with no
+   * receiver of its own, and a member reached that way must not be answered differently.
+   */
+  const self: { view: S | null } = { view: null };
+  const viewOf = (prop: string | symbol): S => {
+    // Unreachable in practice; refusing is the safe direction if it ever is not.
+    if (self.view === null) throw refusalOf(prop, "the collection view");
+    return self.view;
+  };
 
-      // RAW ESCAPE HATCHES. `DeepSignalSet` exposes the underlying collection on
-      // dunder keys (`__raw__`, `__meta__` — `RAW_KEY` in `@ng-org/alien-deepsignals`),
-      // and the header used to claim "a plain property carries no items". It does here:
-      // `view.__raw__` handed back the unfiltered Set, every identity's items in it.
-      // Found by re-running the adversary on the fix (2026-08-07). Any dunder key is
-      // refused, because that is the convention the escape hatches follow.
-      if (typeof prop === "string" && prop.startsWith("__")) {
-        throw new Error(
-          `[ng-eventually] read filter: \`${prop}\` reaches past the view to the raw ` +
-            "collection, which holds every identity's items. There is no filtered form of it.",
-        );
-      }
+  /**
+   * Serve a member upstream declares non-mutating, over the READABLE items.
+   *
+   * The source is a fresh `Array` - the shape every iterator helper works on - or a fresh
+   * `Set`, which the ES2025 combinators need. Either way it is built from `kept`, so it
+   * holds nothing the holder may not read and nothing it returns can reach past the view.
+   */
+  const served = (target: object, prop: string, asSet: boolean): unknown => {
+    const items = kept(target);
+    const source: object = asSet ? new Set(items) : items;
+    const fn = Reflect.get(source, prop, source);
+    if (typeof fn !== "function") return fn;
+    return (...args: unknown[]): unknown => {
+      const out = (fn as (...a: unknown[]) => unknown).apply(source, args);
+      // A member that hands its own receiver back (`copyWithin`) hands back the snapshot;
+      // the view is what a caller should keep hold of.
+      return out === source ? viewOf(prop) : out;
+    };
+  };
 
-      const v = Reflect.get(target, prop, target);
-      if (typeof v !== "function") return v;
-      // UNKNOWN function member: refuse rather than forward. See the header — forwarding
-      // is a silent leak, and this view's one job is that it cannot show more than the
-      // holder may read.
-      return () => {
-        throw new Error(
-          `[ng-eventually] read filter: \`${String(prop)}\` is not filtered, so calling it ` +
-            "would return items this identity may not read. Add it to " +
-            "`emulated-verifier/read-filter.ts`, filtered — do not bypass the view.",
-        );
+  /**
+   * What a MUTATION may hand back - the same question this file asks of any other member,
+   * asked of a RESULT rather than of a property. Written once and called from each of
+   * them, because the defect it answers was three copies of a reasoned-about return value:
+   * the collection becomes the view, a scalar passes, and anything else refuses rather
+   * than being guessed at.
+   */
+  const handBack = (out: unknown, target: object, prop: string | symbol): unknown => {
+    if (out === target) return viewOf(prop);
+    if (cannotReachAnItem(out)) return out;
+    throw refusalOf(prop, "the collection view");
+  };
+
+  /** What the view answers for one member. The `get` trap and the descriptor trap BOTH
+   *  call this, so neither can answer what the other refuses. */
+  const read = (target: object, prop: string | symbol): unknown => {
+    if (prop === Symbol.iterator) return function* () { yield* kept(target); };
+    // HOW THE LANGUAGE NAMES THIS VIEW. Computed from the shape wrapped, never forwarded:
+    // the specification closes the KEY, not the value, so a tag implemented as a getter
+    // returning `Set(${size})` would have published the unfiltered count. Answered only
+    // when the target carries one, so the view grows no member the collection lacks -
+    // measured, a `DeepSignalSet` carries the constant "Set" and a `readOnlyArray` none.
+    if (prop === Symbol.toStringTag && prop in target) return arrayLike ? "Array" : "Set";
+    if (prop === Symbol.isConcatSpreadable && prop in target) return arrayLike;
+    // Upstream lists it beside `Symbol.iterator`. Answered only when the target carries
+    // one, so the view never grows an iteration the collection does not have.
+    if (prop === Symbol.asyncIterator && prop in target) {
+      return async function* () { yield* kept(target); };
+    }
+    // HOW MANY, under both spellings. `data` is a `DeepSignalSet` for an unordered read
+    // and an array-like `DeepSignal<ReadOnlyArray>` once the config asks for an
+    // `orderBy`, and `length` is a number - so it used to pass as a primitive and
+    // publish the UNFILTERED count, which is showing more than the holder may read.
+    // Each is answered only when the target carries it, so the view keeps the shape of
+    // what it wraps instead of growing a member the collection does not have.
+    if ((prop === "size" || prop === "length") && prop in target) return kept(target).length;
+    // AN INDEX, on the array form. It names a position in the readable items, not in the
+    // collection underneath: the two differ by exactly what this view removed.
+    {
+      const i = indexOf(prop);
+      if (i !== null) return kept(target)[i];
+    }
+    // WHAT A POSITION IS, and it is not the same question on the two shapes. A Set yields
+    // the item for both halves of a `[key, value]` pair and hands `forEach` the item
+    // twice; an array yields INDICES from `keys()`, `[index, item]` from `entries()`, and
+    // hands `forEach` the index second. Answering an ordered result with the Set contract
+    // gave the caller the wrong output on their own data - no leak, just wrong.
+    if (prop === "values") return () => kept(target)[Symbol.iterator]();
+    if (prop === "keys") {
+      return () =>
+        (arrayLike ? kept(target).map((_, i) => i) : kept(target))[Symbol.iterator]();
+    }
+    if (prop === "entries") {
+      return () =>
+        kept(target)
+          .map((item, i) => (arrayLike ? ([i, item] as const) : ([item, item] as const)))
+          [Symbol.iterator]();
+    }
+    if (prop === "forEach") {
+      return (cb: (v: unknown, v2: unknown, s: unknown) => void) => {
+        const items = kept(target);
+        for (let i = 0; i < items.length; i++) {
+          cb(items[i], arrayLike ? i : items[i], viewOf(prop));
+        }
       };
+    }
+    // `has(item)` is filtered, not forwarded: the caller already holds the item, so the
+    // answer discloses nothing new — but upstream an unreadable item is never delivered
+    // at all, so "yes it is in there" would be an answer the target cannot give.
+    if (prop === "has") return (item: unknown) => keep(item) && (target as Set<unknown>).has(item);
+    // The reactive-set extras, named here because each is computed from the filtered
+    // items rather than delegated. They are part of upstream's `iteratorFnKeys` - the
+    // comment used to call that set `iteratorHelperKeys`, which is not its name and not
+    // the list it held: `includes` and `Symbol.asyncIterator` are in it and were missing
+    // here, so `data.includes(ownItem)` answered nothing on either shape. The rest of the
+    // declared surface is served generically further down.
+    if (prop === "map") return (fn: (v: unknown, i: number) => unknown) => kept(target).map(fn);
+    if (prop === "filter") return (fn: (v: unknown, i: number) => boolean) => kept(target).filter(fn);
+    if (prop === "find") return (fn: (v: unknown, i: number) => boolean) => kept(target).find(fn);
+    if (prop === "some") return (fn: (v: unknown, i: number) => boolean) => kept(target).some(fn);
+    if (prop === "every") return (fn: (v: unknown, i: number) => boolean) => kept(target).every(fn);
+    if (prop === "toArray") return () => kept(target);
+    if (prop === "first") return () => kept(target)[0];
+    if (prop === "take") return (n: number) => kept(target).slice(0, n);
+    if (prop === "drop") return (n: number) => kept(target).slice(n);
+    if (prop === "flatMap") return (fn: (v: unknown, i: number) => unknown) => kept(target).flatMap(fn as never);
+    if (prop === "reduce") {
+      // On ARITY, not on `init === undefined`. Branching on the value made an EXPLICIT
+      // `reduce(fn, undefined)` look like the one-argument form: an owner with no readable
+      // items got "reduce of empty array with no initial value" where a Set or an Array
+      // answers `undefined`, and with one item got that item back without `fn` ever being
+      // called. Measured on both counts.
+      return function (this: unknown, ...args: unknown[]): unknown {
+        const fn = args[0] as never;
+        return args.length > 1
+          ? kept(target).reduce(fn, args[1])
+          : kept(target).reduce(fn);
+      };
+    }
+    if (prop === "getById" || prop === "getBy") {
+      const inner = Reflect.get(target, prop, target) as ((...a: unknown[]) => unknown) | undefined;
+      if (typeof inner !== "function") return inner;
+      return (...args: unknown[]) => {
+        const item = inner.apply(target, args);
+        return keep(item) ? item : undefined;
+      };
+    }
+
+    // MUTATIONS reach the collection underneath - the view must not break writes or the
+    // reactivity they drive - but under one rule, which the three of them used to break in
+    // three different ways: a mutation may not reach past what the view shows, and may not
+    // hand back what the view hides.
+    //
+    // ALL THREE ARE GATED, on the same question asked of the item, and that is the
+    // arbitration rather than an accident. `delete` and `clear` ask `keep` - may the
+    // holder READ this item - while `add` asks the stricter `writable`, because planting
+    // an item means naming a document the holder HOLDS, which reading one does not.
+    // `delete` and `clear` were gated first and `add` was not, which made the rule above
+    // true by coincidence: the ungated `add` MANUFACTURED the very state the other two
+    // then handled partially - a holder can plant an item into a document it cannot read,
+    // never see it again, and watch `clear()` leave it behind. Gating two of three is the
+    // asymmetry, not a half-measure, so all three ask the same question. What they answer
+    // with differs because the members differ: `delete` has `false`, which is the Set
+    // contract's own word for "it was not there" and is true of the view; `add` has no
+    // such value - it returns the collection whether or not it did anything - so it
+    // THROWS rather than reporting a write that did not happen.
+    //
+    // They were forwarded bound to the target until 2026-09-24, on the written ground that
+    // "they take an item and return void or a boolean, so they yield nothing to leak". RUN
+    // rather than reasoned about, that ground is false: `Set.prototype.add` returns THIS so
+    // calls can be chained, so `view.add(x)` handed back the unfiltered collection - and
+    // `add` is the first member the SDK's own example reaches for. `delete` really does
+    // return a boolean and `clear` really does return undefined (both measured), but they
+    // ACTED past the view: `delete` removed an item `has` refuses to even confirm, and
+    // `clear` emptied the collection every identity shares.
+    if (prop === "add") {
+      const fn = Reflect.get(target, prop, target);
+      if (typeof fn !== "function") return fn;
+      // `add` chains, so its result is the collection and must become the view.
+      return (...args: unknown[]): unknown => {
+        if (!writable(args[0])) throw writeRefusalOf(args[0]);
+        return handBack((fn as (...a: unknown[]) => unknown).apply(target, args), target, prop);
+      };
+    }
+    if (prop === "delete") {
+      const fn = Reflect.get(target, prop, target);
+      if (typeof fn !== "function") return fn;
+      // The same question `has` already refuses to answer, with a worse consequence. The
+      // two disagreed: `has(item)` said no while `delete(item)` removed it.
+      return (item: unknown): unknown =>
+        keep(item) ? handBack((fn as (i: unknown) => unknown).call(target, item), target, prop) : false;
+    }
+    if (prop === "clear") {
+      const del = Reflect.get(target, "delete", target);
+      if (typeof del !== "function") return Reflect.get(target, prop, target);
+      // Emptying the view empties THE VIEW. `clear()` on the target empties the collection
+      // every identity shares, which destroys what the holder is not even allowed to see.
+      return (): void => {
+        for (const item of kept(target)) (del as (i: unknown) => unknown).call(target, item);
+      };
+    }
+
+    // RAW ESCAPE HATCHES. `DeepSignalSet` exposes the underlying collection on
+    // dunder keys (`__raw__`, `__meta__` — `RAW_KEY` in `@ng-org/alien-deepsignals`),
+    // and the header used to claim "a plain property carries no items". It does here:
+    // `view.__raw__` handed back the unfiltered Set, every identity's items in it.
+    // Found by re-running the adversary on the fix (2026-08-07). Any dunder key is
+    // refused, because that is the convention the escape hatches follow.
+    if (typeof prop === "string" && prop.startsWith("__")) {
+      throw new Error(
+        `[ng-eventually] read filter: \`${prop}\` reaches past the view to the raw ` +
+          "collection, which holds every identity's items. There is no filtered form of it.",
+      );
+    }
+
+    // EVERY OTHER MEMBER UPSTREAM DECLARES NON-MUTATING, served over the readable items.
+    //
+    // The named handlers above exist for the members whose meaning DIFFERS between the two
+    // shapes, or which this view has to compute itself. The rest are ordinary reads, and
+    // refusing them cost the owner 18 declared members of an ordered result - `at`,
+    // `slice`, `join`, `toSorted`, `indexOf` - all throwing on data that is entirely
+    // theirs - plus `includes` and the seven ES2025 combinators on the set form. A leak
+    // traded for an outage is not a repair.
+    //
+    // They run against a FRESH collection built from `kept`, never against the target, so
+    // there is nothing for them to reach: everything in it has already been filtered, and
+    // whatever they return is drawn from it.
+    if (typeof prop === "string") {
+      if (arrayLike && (NON_MUTATING_ARRAY_ONLY.has(prop) || ITERATOR_HELPERS.has(prop))) {
+        return served(target, prop, false);
+      }
+      if (!arrayLike && NON_MUTATING_SET_ONLY.has(prop)) return served(target, prop, true);
+      if (!arrayLike && ITERATOR_HELPERS.has(prop)) return served(target, prop, false);
+    }
+
+    // ANY OTHER MEMBER, function or not: refuse rather than forward, unless the value
+    // behind it cannot reach an item at all. See the header — forwarding is a silent
+    // leak, and this view's one job is that it cannot show more than the holder may read.
+    return answerUndecidedMember(target, prop, "the collection view");
+  };
+
+  const proxy = new Proxy(set, {
+    get: (target, prop) => read(target, prop),
+    getOwnPropertyDescriptor(target, prop) {
+      // An index past what may be read names no position of this view, and saying so is
+      // what keeps `has`, `ownKeys` and the descriptor telling one story.
+      const i = indexOf(prop);
+      if (i !== null && i >= kept(target).length) return undefined;
+      return filteredDescriptor(target, prop, () => read(target, prop));
+    },
+    has(target, prop) {
+      const i = indexOf(prop);
+      return i === null ? Reflect.has(target, prop) : i < kept(target).length;
+    },
+    // A WRITE to the collection itself, refused on this view's own account rather than
+    // because the ordered collection upstream happens to refuse some of them too.
+    ...writeTraps,
+    ownKeys(target) {
+      // A Set holds its items internally and owns no key naming one, so there is nothing
+      // to project: `Object.keys` on it is already empty (measured). An array owns one key
+      // per position, and forwarding those published HOW MANY items the collection holds
+      // while `length` said how many may be read - the two disagreed by the leak.
+      if (!arrayLike) return Reflect.ownKeys(target);
+      const keys: Array<string | symbol> = [];
+      for (let i = 0; i < kept(target).length; i++) keys.push(String(i));
+      // Everything that is not a position passes through, so a key the target cannot hide
+      // - an array's own `length` - is never dropped.
+      for (const k of Reflect.ownKeys(target)) if (indexOf(k) === null) keys.push(k);
+      return keys;
     },
   }) as S;
+  self.view = proxy;
+  return proxy;
+}
+
+/**
+ * One filtered view per underlying collection, so that reading `.data` twice hands back the
+ * SAME reference WITHIN one call.
+ *
+ * It does not survive a re-render, and the note here used to claim it did: the shipped hook
+ * wraps `signalObject` in `useDeepSignal`, whose root proxy is "replaced on every relevant
+ * rerender" by its own documentation, so the key this memo is built on is a different
+ * object each time and a dependency array sees a new value regardless. What it does buy is
+ * real and smaller - `result.data === result.data` - and that is what it now says.
+ *
+ * Keyed weakly on the collection the SDK handed us, and rebuilt if the registry it was
+ * filtered against is no longer the one in force, so a view can never answer from a keyring
+ * that has been replaced.
+ */
+const filteredCollections = new WeakMap<object, { caps: CapRegistry; view: object }>();
+
+/** The read-filtered view of one item-carrying value, memoized. */
+function filteredCollection(value: object, caps: CapRegistry): object {
+  const known = filteredCollections.get(value);
+  if (known !== undefined && known.caps === caps) return known.view;
+  const view = makeReadFilteredView(value, caps);
+  filteredCollections.set(value, { caps, view });
+  return view;
+}
+
+/** Same, for the promise that resolves to one: the filtering happens on what it resolves to. */
+const filteredPromises = new WeakMap<object, { caps: CapRegistry; view: Promise<unknown> }>();
+
+function filteredPromise(value: PromiseLike<unknown>, caps: CapRegistry): Promise<unknown> {
+  const known = filteredPromises.get(value as object);
+  if (known !== undefined && known.caps === caps) return known.view;
+  const view = Promise.resolve(value).then((d) =>
+    cannotReachAnItem(d) ? d : filteredCollection(d as object, caps),
+  );
+  filteredPromises.set(value as object, { caps, view });
+  return view;
+}
+
+/**
+ * A read-filtered VIEW over the RESULT the SDK's `useShape` hands back - the envelope, not
+ * the collection inside it.
+ *
+ * ── Why there are two views and not one ───────────────────────────────────
+ * `@ng-org/orm@0.1.2-alpha.21`'s React `useShape` returns a `UseShapeResult`, an object
+ * whose members are of two different kinds: some carry the items, some are the request's
+ * own state. Until 2026-09-24 this package wrapped that envelope in
+ * {@link makeReadFilteredView}, which is written for a collection - so `[...result]` and
+ * `.size` threw (an envelope is not iterable), while `.data`, `.promise` and
+ * `.subscription` were each returned RAW and each handed back every identity's items. One
+ * object cannot be both, so there are two views and this is the one `surface/use-shape.ts`
+ * applies.
+ *
+ * ── What each member answers ──────────────────────────────────────────────
+ * The three that carry the items are named and filtered; the two that command a page are
+ * named and forwarded, because they return `void` and load rows into a collection that is
+ * only ever seen through the filter; `isLoading` is named and served, because it describes
+ * the REQUEST rather than the items. All six of `alpha.21`'s members are therefore decided
+ * here, and a seventh that a later version adds refuses until someone decides it - which is
+ * the point, and the reason this list is not the "name list" the earlier type-based default
+ * was written to avoid. That default passed unknowns; this one refuses them.
+ *
+ * `subscription` is REFUSED rather than wrapped, and the reason is this surface's own: it
+ * is the SDK's `RdfOrmSubscription`, which this package deliberately does not publish
+ * because one wallet hosts every identity here, so an unwrapped read through it returns
+ * every identity's objects. It reaches the items three separate ways - `signalObject`,
+ * `readyPromise`, and the raw `{adds, updates, removes}` handed to `addChangeListener` -
+ * and a wrapper of it would be a second published surface to keep honest. Refusing is
+ * loud, and what it refuses is the one member the contract already says is not published.
+ */
+// @provenance makeReadFilteredShapeResult kind=aligned level=3 ref=sdk/js/orm/src/frontendAdapters/react/useShape.ts:useShape - the same capability filter, over the result envelope that hook returns rather than over the collection inside it; removed at migration
+export function makeReadFilteredShapeResult<R extends object>(result: R, caps: CapRegistry): R {
+  /** What the view answers for one member. The `get` trap and the descriptor trap BOTH
+   *  call this, so neither can answer what the other refuses - `data` used to come back
+   *  RAW through `Object.getOwnPropertyDescriptor`, and so did the handle `get` throws on. */
+  const read = (target: object, prop: string | symbol): unknown => {
+    // THE ITEMS, under the three names alpha.21 offers them. Each is filtered rather
+    // than refused: a holder reading their own data through whichever member the SDK
+    // gives them is exactly what this view exists to keep working.
+    if (prop === "data") {
+      const d = Reflect.get(target, prop, target);
+      return cannotReachAnItem(d) ? d : filteredCollection(d as object, caps);
+    }
+    if (prop === "promise") {
+      const p = Reflect.get(target, prop, target);
+      return cannotReachAnItem(p) ? p : filteredPromise(p as PromiseLike<unknown>, caps);
+    }
+    if (prop === "subscription") {
+      const s = Reflect.get(target, prop, target);
+      // `undefined` when the caller passed no config: nothing was opened, so there is
+      // nothing to refuse, and answering the SDK's own value keeps that case honest.
+      if (cannotReachAnItem(s)) return s;
+      throw new Error(
+        "[ng-eventually] read filter: `subscription` hands back NextGraph's own " +
+          "`RdfOrmSubscription`, which reads and writes with no capability filter at all " +
+          "- one wallet hosts every identity here, so it would return every identity's " +
+          "objects. This package does not publish it. Read through `data`, `promise`, or " +
+          "`useShapeQuery`.",
+      );
+    }
+    // THE REQUEST'S OWN STATE. Decided rather than left to a default, which is the whole
+    // repair: it is a boolean and it used to pass because it is a primitive, on a rule
+    // that also passed `totalCount`. It is served because it describes the REQUEST - has
+    // the payload arrived - and not the items, so it says nothing about what was filtered
+    // out. (Its VALUE is upstream's own inversion; see `ShapeResult.isLoading`.)
+    if (prop === "isLoading") return Reflect.get(target, prop, target);
+
+    // THE PAGE COMMANDS. They forward: what they load lands in the raw collection, which
+    // is only ever read back through the filter above.
+    //
+    // Their RESULT is held to the same rule as everything else here, and that is the
+    // lesson of the collection view rather than a worry about this one. `nextPage` is
+    // declared `() => void` and the shipped hook assigns the subscription's own, so today
+    // it yields nothing - but "it returns void" was the written, unexecuted ground on
+    // which `add` was forwarded, and `Set.prototype.add` returns the collection. A page
+    // command that ever hands something back gets the same answer as any other member:
+    // a scalar passes, anything that could reach an item refuses.
+    if (prop === "nextPage" || prop === "previousPage") {
+      const fn = Reflect.get(target, prop, target);
+      if (typeof fn !== "function") return fn;
+      return (...args: unknown[]): unknown => {
+        const out = (fn as (...a: unknown[]) => unknown).apply(target, args);
+        if (cannotReachAnItem(out)) return out;
+        throw refusalOf(prop, "the result envelope");
+      };
+    }
+    return answerUndecidedMember(target, prop, "the result envelope");
+  };
+
+  return new Proxy(result, {
+    get: (target, prop) => read(target, prop),
+    getOwnPropertyDescriptor: (target, prop) =>
+      filteredDescriptor(target, prop, () => read(target, prop)),
+    // The SAME write traps as the collection view, from the same object. This view had two
+    // traps to the other's nine, so the SDK's own result could be deleted from, written to
+    // and re-prototyped through it.
+    ...writeTraps,
+  }) as R;
 }

packages/polyfill/src/index.ts

@@ -47,16 +47,33 @@
 //
 // 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>
+//   // @provenance <name> kind=<kind> level=<1|2|3|none> ref=<path:symbol|none> [announced-by=<who>@<date>] — <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),
+// `@ng-org/web`, 3 JS ORM); `ref` cites a SYMBOL, never a line number — in `nextgraph-rs`
+// for every kind that cites the target, and in THIS working copy for the one kind that
+// has no upstream file to cite. `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), `announced-not-written` (upstream's
+// developers have STATED this direction and nothing in the tree carries it yet),
+// `reserved-name` (upstream has declared a NAME with no shape behind it),
 // `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 `ref` names a path and a symbol, never a VERSION - the version is a property of the
+// checkout every citation resolves against, so it is recorded once, in the `ANCHOR` of
+// `test/provenance.test.ts`, and checked at both ends there. Read it before letting a
+// citation settle anything about a release: the tree is BEHIND the packages this repo
+// builds against, so a claim about a shipped version cannot be refuted by opening it.
+//
+// `announced-not-written` is the STRONGEST kind available to a symbol with no counterpart
+// in the tree - deviating TOWARD what the target has announced is alignment, and calling
+// it `invention` tells a later reader the shape is ours to change when it is not. Being
+// the strongest, it is the hardest to assert: it carries `announced-by=<who>@<date>` and
+// its `ref` is the `.md` in this working copy where the statement is on record. An
+// announcement nobody wrote down is hearsay, so the test refuses it.
 
 // 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
@@ -67,39 +84,80 @@
 // value it has no call to obtain — and for `ReadCap`, the one value the model says a
 // caller must never be handed on request. They stay DEFINED in `model/types.ts`, where
 // the library uses them; they stop being surface. `docs/api-contract.md` § 10, § 14.
-// Each one, and the signature that earns it its place:
+//
+// The same rule caught a second, later recurrence (2026-09-24): the SDK type re-exports
+// below carried `Schema` (from `@ng-org/shex-orm`) and `DeepSignalSet` (from
+// `@ng-org/alien-deepsignals`), neither used by a published signature — `DeepSignalSet`
+// is named only in prose describing what `useShape`'s result envelope carries, never as
+// an actual type anywhere in this package. Unlike `ReadCap` / `InboxScope`, neither has
+// an internal use to stay DEFINED for: they are simply gone, not moved.
+//
+// `NgLike`, `UseShapeLike`, `OrmSubscriptionLike`, `GetObjectsLike` and `InsertObjectLike`
+// left THIS section on 2026-09-28, for a third reason again the opposite of the first two:
+// each is honestly `kind=invention level=none ref=none` - no counterpart answers, at any
+// level - and this section's own heading promises one for every symbol it lists. All five
+// exist only to describe what `configure` receives (they type `EventuallyConfig`'s
+// fields), and `configure` / `EventuallyConfig` are already below, on the deletion list:
+// they go with it. The move changes no signature - same names, same shapes, still
+// exported from this one entry - it only corrects which of the two lists tells a consumer
+// their fate at migration. See them beside `EventuallyConfig` below.
+// Each one still SDK-shaped, and the signature that earns it its place:
 //   Nuri          every reference the surface RETURNS
 //   NuriLike      every reference the surface ACCEPTS
-//   Scope         `storeRegistry.*`, `watchShape`
 //   PrincipalId   `ensureIdentity`, `inbox.Deposit`/`PostOptions`, `EventuallyConfig`
-//   NgLike        `EventuallyConfig.ng`
-//   UseShapeLike  `EventuallyConfig.useShape`
-export type { Nuri, NuriLike, Scope, PrincipalId, NgLike, UseShapeLike } from "./model/types";
+//   RdfOrmConfig  `getObjects`
+//
+// `Scope` left this list in `1.0.0-dev.5`, and it is the only one that left because the
+// TYPE was wrong rather than unreachable. It was `"public" | "protected" | "private"` -
+// our own three strings under a name the SDK also uses, for a different thing: upstream
+// a `Scope` is `{ graphs, subjects }` and scopes a READ, while those three strings are
+// `doc_create`'s `store_type` and place a WRITE. One name over two questions. The read
+// takes the SDK's `Scope` now (re-exported below, from the SDK itself), and a store is
+// named by its reference. The three strings stay DEFINED in `model/types.ts` as
+// `StoreType`, where the library's own modules still tell the three apart.
+export type { Nuri, NuriLike, PrincipalId } from "./model/types";
 export { useShape } from "./surface/use-shape";
-export { watchShape } from "./surface/watch-shape";
-export type { ShapeQuery, ShapeObservable } from "./surface/watch-shape";
+export { useShapeQuery } from "./surface/use-shape-query";
+export type { ShapeQuery } from "./surface/use-shape-query";
+// `ShapeObservable` is exported from the POLYFILL-ERA block below, beside `configure`:
+// it is `kind=invention level=none ref=none` and carries shared-wallet emulation.
+// The ORM's one-shot read and its subscription-free write - WRAPPED, at upstream's own
+// names and signatures, never re-exported. `surface/orm.ts` says what each wrapper adds,
+// and which neighbours of theirs in `@ng-org/orm`'s entry are deliberately not here
+// (`RdfOrmSubscription`, `DiscreteOrmSubscription`, `ngSession`, `getRaw`).
+export { getObjects, insertObject } from "./surface/orm";
 export { init, initNg } from "./surface/lifecycle";
 export * as inbox from "./surface/inbox";
 export * as docs from "./surface/docs";
 export { subscribeDoc, subscribeDocs, docChangeType } from "./surface/subscribe";
 export type { DocChange, DocChangeType, Unsubscribe } from "./surface/subscribe";
-// `readUnion` is exposed as a function, not under a `readModel` namespace: "model" is
-// neither the target's vocabulary nor neutral glue, and the namespace bought nothing —
-// it held one published function. Renamed 2026-08-03 by the vocabulary check.
-export { readUnion } from "./surface/read-model";
-export type { UnionSubject } from "./surface/read-model";
+// `readUnion` and `UnionSubject` were published here until `1.0.0-dev.8`. They are gone,
+// and nothing replaces them: a `document read` over several documents was N anchored
+// queries plus a batch policy, which no level of the target answers - so its provenance
+// cited `sparql_query`, a citation that is exact attached to a claim that is false. A
+// composition cannot be aligned on a single function. Reading one document by name is
+// `docs.sparqlQuery(sessionId, query, undefined, doc)`, which IS upstream's own primitive
+// and is published beside this line; reading several is that call, once per document.
 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
+// @provenance BaseType kind=passthrough level=3 ref=sdk/js/shex-orm/src/types.ts:BaseType - the cited revision keeps `"@graph"` commented out behind a TODO; the published `@ng-org/shex-orm@0.1.2-alpha.9` declares it, and it is the published one that is re-exported here
+export type { ShapeType, BaseType } from "@ng-org/shex-orm";
+// The scope `useShapeQuery` takes, re-exported from the SDK rather than restated here:
+// restating it is how a type drifts, and the two axes it filters on (`graphs`,
+// `subjects`) are upstream's to change.
+// @provenance Scope kind=passthrough level=3 ref=sdk/js/orm/src/types.ts:Scope - the cited revision declares `graphs?` OPTIONAL; the published `@ng-org/orm@0.1.2-alpha.21` makes it required, and it is the published one that is re-exported here
+export type { Scope } from "@ng-org/orm";
+// What `getObjects` takes: a `Scope` plus `where` and `orderBy`. It is re-exported from
+// the SDK's `/all` subpath because that is where the SDK puts it - the type the function
+// DECLARES is not exported beside the function, which is upstream's packaging and not a
+// choice here. Restating it would be how it drifts.
+// @provenance RdfOrmConfig kind=passthrough level=3 ref=sdk/js/orm/src/utilTypes.ts:OrmConfig - the published `@ng-org/orm@0.1.2-alpha.21` renames it `RdfOrmConfig` and re-parameterises it on the shape's type rather than its `ShapeType`, which the cited revision has not yet done
+export type { RdfOrmConfig } from "@ng-org/orm/all";
+// @provenance NG kind=passthrough level=2 ref=sdk/js/web/src/index.ts:NG — every member forwarded; the proxy adds none and removes none. The count lives once, with the release it belongs to, in `surface/ng-proxy.ts`
 export type { NG } from "@ng-org/web";
 
 // ── POLYFILL-ERA — THE DELETION LIST ────────────────────────────────────────
@@ -117,6 +175,54 @@ export type { NG } from "@ng-org/web";
  */
 export { configure } from "./shared-wallet/bootstrap";
 export type { EventuallyConfig } from "./shared-wallet/bootstrap";
+// The five field types of `EventuallyConfig` above, moved down beside it on 2026-09-28 -
+// they used to sit in the SDK-SHAPED section, which was wrong: each is honestly `kind=
+// invention level=none ref=none`, and each exists only to describe what `configure`
+// receives. They go with `configure` at migration; nothing here survives it.
+//   NgLike               `EventuallyConfig.ng`
+//   UseShapeLike         `EventuallyConfig.useShape`
+//   OrmSubscriptionLike  `EventuallyConfig.ormSubscription`
+//   GetObjectsLike       `EventuallyConfig.getObjects`
+//   InsertObjectLike     `EventuallyConfig.insertObject`
+//
+// `OrmSubscriptionHandle` - what `OrmSubscriptionLike` RETURNS - is deliberately NOT
+// here either. An application hands the shape query in and reads the snapshot back; it
+// never holds a subscription, and publishing the handle would offer a path around the
+// capability filter and the shared-wallet identity boundary. It stays defined in
+// `model/types.ts`.
+export type {
+  NgLike,
+  UseShapeLike,
+  OrmSubscriptionLike,
+  GetObjectsLike,
+  InsertObjectLike,
+} from "./model/types";
+// `ShapeObservable` - what `useShapeQuery` returns - moved down here on 2026-10-01. It is
+// `kind=invention level=none ref=none` (no upstream observable exists; the record behind
+// `ShapeQuery` describes a SNAPSHOT shape, not an observable), so it never belonged under
+// the SDK-SHAPED heading. It stays EXPORTED: applications genuinely write the type down
+// (`examples/notebook/app.ts` holds one in a variable, returns it and takes it as a
+// parameter; `e2e/polyfill-entry.ts` annotates it). Only the documenting section changes.
+//
+// It is NOT a framework adapter. It carries two pieces of shared-wallet emulation:
+//   - the CAPABILITY FILTER - `getSnapshot()` returns a view filtered by the capabilities
+//     held (`use-shape-query.ts`, `filterReadable` under `caps.isEnforcing()`);
+//   - the CAPABILITY-ARRIVAL RE-PUBLISH - a `getCaps().onChange(...)` subscription owned
+//     by the observable's own lifecycle and released with it.
+// A capability arrives MID-SESSION only because the wallet is shared. In the target an
+// identity holds its own wallet and its capabilities from the start: nothing to filter,
+// no arrival to re-publish on. So `ShapeObservable` dies exactly WHEN THE SHARED WALLET
+// DIES - a COUPLED migration with the shared wallet, not an independent symbol removal.
+// Deleting the type and "using the hook" is not a step that stands alone.
+//
+// The announced form cannot carry what ours carries: a TanStack-shaped hook returning a
+// snapshot has nowhere to hang a capability-arrival subscription, because the target
+// does not need one.
+//
+// `refetch()` lives on it, and is the ONLY published way out of a read stuck pending.
+// The recorded announcement lists five fields, `{ data, isPending, isSuccess, isError,
+// error }`, and `refetch` is not among them: it goes with NO RECORDED COUNTERPART.
+export type { ShapeObservable } from "./surface/use-shape-query";
 // `RegistrySession` went with `getSession` (2026-08-12): it was published for exactly one
 // reason — an application typed the session thunk it injected with it — and a published
 // type whose signature is gone is a promise about the target that nothing keeps. Upstream a
@@ -158,14 +264,14 @@ export type { SharedWalletConfig } from "./shared-wallet/access-gate";
 
 import type { NG } from "@ng-org/web";
 
-import { makeNg } from "./surface/ng-proxy";
+import { wrappedNg } from "./surface/ng-proxy";
 
 /**
  * SDK-identical `ng` (wrapped). Drop-in replacement for `@ng-org/web`'s `ng`.
  *
  * Declared `NG` — upstream's own type for its `ng` (`index.d.ts:NG`). It was published as
  * `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.
+ * it forwards to: an application got no completion and no check on any of its 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();
+export const ng: NG = wrappedNg();

packages/polyfill/src/model/types.ts

@@ -2,6 +2,16 @@
  * Generic, NextGraph-shaped types. ZERO application domain.
  */
 
+// The SDK's own types, imported as TYPES (erased at build, so this module stays free of
+// any runtime `@ng-org` import). They describe what `configure` RECEIVES; nothing here
+// re-exports them.
+import type { Scope } from "@ng-org/orm";
+// `RdfOrmConfig` lives on the SDK's `/all` subpath rather than on its main entry - the
+// config type `getObjects` DECLARES is not exported beside the function that takes it.
+// Imported as a TYPE, so nothing of that subpath reaches the build.
+import type { RdfOrmConfig } from "@ng-org/orm/all";
+import type { BaseType, ShapeType } from "@ng-org/shex-orm";
+
 /**
  * A NextGraph URI (document / store / inbox) in its **cap-less** form — it NAMES
  * and locates, it does not grant the right to read: `did:ng:o:{doc}:v:{overlay}`.
@@ -35,10 +45,23 @@ export type Nuri = `did:ng:${string}`;
 // @provenance ReadCap kind=aligned level=1 ref=engine/repo/src/types.rs:readcap_nuri — the `r:` segment and its one-opaque-segment encoding are upstream's; the key material is a stand-in constant
 export type ReadCap = `did:ng:${string}:r:${string}`;
 
-/** NextGraph-native store scopes. The *mapping* of entities to scopes is the
- *  consumer's concern; this layer only knows the three scopes exist. */
-// @provenance Scope kind=aligned level=1 ref=engine/repo/src/types.rs:from_type_and_repo — upstream's store types; `group` is omitted here and `dialog` is `unimplemented!()` upstream
-export type Scope = "public" | "protected" | "private";
+/**
+ * Which of a session's three stores a document is placed in. **Defined here, not
+ * published** - the standing `ReadCap` and {@link InboxScope} already have, and for
+ * the same reason: no published signature takes it. It was published as `Scope` until
+ * `1.0.0-dev.5`, where one name covered the scope of a READ and the placement of a
+ * write. The SDK's own `Scope` is an object filtering on `graphs` and `subjects`, and
+ * the two were never the same question.
+ *
+ * The three strings are upstream's own: `doc_create` takes a `store_type` of exactly
+ * `"public" | "protected" | "private"` (plus `"group"`, omitted here, and `"dialog"`,
+ * which is `unimplemented!()` upstream) and pairs it with a store id to build a
+ * `StoreRepo`. An application names a store by its REFERENCE
+ * (`storeRegistry.privateStore()` and its two neighbours); this type is how the
+ * library's own modules tell the three apart once one has been resolved.
+ */
+// @provenance StoreType kind=aligned level=1 ref=engine/repo/src/types.rs:from_type_and_repo — upstream's store types, the strings `doc_create`'s `store_type` accepts; `group` is omitted here and `dialog` is `unimplemented!()` upstream
+export type StoreType = "public" | "protected" | "private";
 
 /** The current identity id. Target: the wallet user (`session.user`). Polyfill:
  *  a chosen id, because everyone shares one wallet. */
@@ -55,12 +78,154 @@ export type PrincipalId = string;
 // @provenance NgLike kind=invention level=none ref=none — nothing upstream is injected; the type exists only to describe what `configure` receives
 export type NgLike = Record<string, any>;
 
-/** Loose shape of `@ng-org/orm`'s `useShape` (a generic hook). */
-// @provenance UseShapeLike kind=invention level=none ref=none — same, for the injected `useShape`
-export type UseShapeLike = (...args: any[]) => any;
+/**
+ * What the SDK's `useShape` hands back - the members this package reads off the result
+ * envelope, and not one more. Same discipline as {@link OrmSubscriptionHandle}.
+ *
+ * NOT published: an application never writes this type down, it reads the value. What is
+ * published is the call that returns one.
+ *
+ * `@ng-org/orm@0.1.2-alpha.21` calls it `UseShapeResult` and declares it in
+ * `dist/frontendAdapters/react/useShape.d.ts` - which no subpath of the package EXPORTS
+ * (`.` is `core.d.ts`, `/react` re-exports the hook alone, `/all` re-exports the config
+ * types alone), so it cannot be imported and is restated here. The three item-carrying
+ * members are `unknown` on purpose: each is read through the capability filter, never off
+ * this type, and narrowing them here would make the real hook unassignable to
+ * {@link UseShapeLike} for a difference no reader of this package can act on.
+ *
+ * The two page commands are OPTIONAL because upstream `WithMaybePagination` `Omit`s them
+ * unless the config asks for a `pageSize`, and the shipped hook sets them to `undefined`
+ * outside a paginated mode.
+ */
+// @provenance ShapeResult kind=aligned level=3 ref=sdk/js/orm/src/frontendAdapters/react/useShape.ts:useShape - the result type of the cited hook, restated because the package exports it from no subpath; the cited revision returns a bare `DeepSignalSet` and the build returns this envelope around one, which is the gap the anchor records
+export interface ShapeResult {
+  /** The requested objects once loaded, `undefined` while they are not. A `DeepSignalSet`
+   *  for an unordered read, an array-like `DeepSignal<ReadOnlyArray>` once the config asks
+   *  for an `orderBy`. Upstream: "the value returned by `RdfOrmSubscription.signalObject`". */
+  readonly data: unknown;
+  /** Resolves to the same data once it has arrived; `undefined` when the config was. */
+  readonly promise: unknown;
+  /** The `RdfOrmSubscription` underneath. This package refuses to hand it on - see
+   *  `emulated-verifier/read-filter.ts` - and declares it here because refusing a member
+   *  requires knowing it is there. */
+  readonly subscription: unknown;
+  /**
+   * What the SDK's declaration calls "`true` when no data is available yet" - and what the
+   * SHIPPED hook computes as `ormSubscription.isReady`, which is the inverse. Both were
+   * read; they disagree, the disagreement is upstream's, and nothing here corrects it:
+   * this package forwards the value it is handed. Read `data === undefined` instead.
+   */
+  readonly isLoading: boolean;
+  /** Load the next page. Present only under a paginated config. */
+  readonly nextPage?: (() => void) | undefined;
+  /** Load the previous page. Present only under `maxActivePages`. */
+  readonly previousPage?: (() => void) | undefined;
+}
 
 /**
- * The scopes that can carry an inbox. NOT `Scope`: upstream only the public and
+ * Shape of `@ng-org/orm`'s React `useShape`, the hook an application injects at
+ * {@link configure}.
+ *
+ * It was `(...args: any[]) => any` until 2026-09-24, and that is not a detail: an `any`
+ * return means no declaration anywhere in this package said what the injected hook hands
+ * back, so the prose said "a bare `DeepSignalSet`" - true of `alpha.18`, false of the
+ * `alpha.21` this package builds against - and nothing could contradict it. The type now
+ * says it, and the real `reactUseShape` is assignable to it with no wrapper and no cast
+ * (pinned by `test/use-shape.test.ts`).
+ */
+// @provenance UseShapeLike kind=invention level=none ref=none - nothing upstream is injected; the type exists only to describe what `configure` receives, here for the ORM's React hook
+export type UseShapeLike = <T extends BaseType>(
+  shapeType: ShapeType<T>,
+  conf: RdfOrmConfig<T> | string | undefined,
+) => ShapeResult;
+
+/**
+ * The shape query in force, as `surface/use-shape-query.ts` reads it - the four members
+ * of `RdfOrmSubscription` this package touches, and not one more.
+ *
+ * NOT published: an application never holds one. It hands {@link OrmSubscriptionLike}
+ * to `configure` and reads the snapshot back; what the query itself offers is the SDK's
+ * business, and re-publishing it here would hand a caller a path around the capability
+ * filter and the shared-wallet identity boundary.
+ *
+ * `signalObject` is typed `Iterable<unknown>` rather than by the shape: upstream it is a
+ * `DeepSignalSet<T>` whose items are `DeepSignal<T>`, and narrowing it here would make
+ * the real `getOrCreate` unassignable to the injection for a difference no reader of
+ * this package can act on. The items are typed where the shape says what they are.
+ */
+// @provenance OrmSubscriptionHandle kind=aligned level=3 ref=sdk/js/orm/src/connector/GraphOrmSubscription.ts:OrmSubscription - the members this package reads: the readiness promise, the signal object, the change listeners and `close`; the published `@ng-org/orm@0.1.2-alpha.21` renames the class `RdfOrmSubscription`, which the cited revision has not yet done
+export interface OrmSubscriptionHandle {
+  /** Resolves when the initial payload has arrived, and on no other path - which is
+   *  what tells "not ready yet" from "ready and empty". Never rejects upstream today. */
+  readonly readyPromise: Promise<unknown>;
+  /** The live objects matching the shape and scope. A set (or an ordered array) that
+   *  the engine's patches keep up to date. */
+  readonly signalObject: Iterable<unknown>;
+  /** Notified when root objects are added, updated or removed. */
+  addChangeListener(
+    listener: (changes: { adds: unknown[]; updates: unknown[]; removes: unknown[] }) => void,
+  ): void;
+  removeChangeListener(
+    listener: (changes: { adds: unknown[]; updates: unknown[]; removes: unknown[] }) => void,
+  ): void;
+  /** Stop the subscription. Pooled upstream, so re-opening it shortly after is cheap. */
+  close(): void;
+}
+
+/**
+ * Loose shape of `@ng-org/orm`'s `RdfOrmSubscription.getOrCreate` - the SDK's shape
+ * query, reached WITHOUT a framework adapter.
+ *
+ * An application injects the real one (`ormSubscription: RdfOrmSubscription.getOrCreate`);
+ * it is assignable to this as it stands, with no wrapper and no cast. `useShape` is not a
+ * substitute: it is React's hook, so it can only be called from a render, and what it
+ * returns carries the ORM's own two states and not the three `ShapeQuery` publishes - an
+ * `isLoading` that does not tell a refused read from a pending one, and no error state at
+ * all.
+ */
+// @provenance OrmSubscriptionLike kind=invention level=none ref=none - nothing upstream is injected; the type exists only to describe what `configure` receives, here for the ORM's own `getOrCreate`
+export type OrmSubscriptionLike = <T extends BaseType>(
+  shapeType: ShapeType<T>,
+  scope: Scope,
+) => OrmSubscriptionHandle;
+
+/**
+ * Loose shape of `@ng-org/orm`'s `getObjects` - the SDK's ONE-SHOT read, the counterpart
+ * of the two-way subscription {@link OrmSubscriptionLike} opens.
+ *
+ * The parameters are upstream's own, passed through rather than restated: a
+ * {@link ShapeType} and the config `RdfOrmConfig` declares minus its two pagination
+ * fields, which `getObjects` `Omit`s because a one-shot read has no pages. The return is
+ * upstream's too - an ARRAY when the config asks for an `orderBy`, a `Set` otherwise -
+ * and it is DETACHED: `structuredClone` of the raw signal object, so mutating an item of
+ * it reaches nothing.
+ *
+ * An application injects the real one (`getObjects: getObjects`, from `@ng-org/orm`); it
+ * is assignable to this as it stands, with no wrapper and no cast.
+ */
+// @provenance GetObjectsLike kind=invention level=none ref=none - nothing upstream is injected; the type exists only to describe what `configure` receives, here for the ORM's own one-shot read
+export type GetObjectsLike = <T extends BaseType>(
+  shapeType: ShapeType<T>,
+  config: Omit<RdfOrmConfig<T>, "pageSize" | "maxActivePages">,
+) => Promise<T[] | Set<T>>;
+
+/**
+ * Loose shape of `@ng-org/orm`'s `insertObject` - the SDK's write that needs no
+ * subscription of its own.
+ *
+ * Upstream it opens a subscription scoped to NO document (`{ graphs: [] }`), adds the
+ * object to that set and closes it, so the object must carry its `@graph`: the write has
+ * no other way of knowing which document it lands in. It returns the object it inserted,
+ * with a generated `@id` where one was left empty.
+ */
+// @provenance InsertObjectLike kind=invention level=none ref=none - same, for the ORM's own subscription-free write
+export type InsertObjectLike = <T extends BaseType>(
+  shapeType: ShapeType<T>,
+  object: T,
+) => Promise<T>;
+
+/**
+ * The stores that can carry an inbox. NOT `StoreType`: upstream only the public and
  * protected store repos get one — `new_store_default` attaches an inbox solely
  * `if !private` (`engine/verifier/src/verifier.rs:2994`), and the engine's only two
  * `AddInboxCap` commits are for those two (`engine/verifier/src/site.rs:127-152`).
@@ -86,4 +251,4 @@ export type UseShapeLike = (...args: any[]) => any;
 export type NuriLike = Nuri | string;
 
 // @provenance InboxScope kind=aligned level=1 ref=engine/verifier/src/verifier.rs:new_store_default — an inbox is attached only `if !private`, so the private scope cannot carry one
-export type InboxScope = Extract<Scope, "public" | "protected">;
+export type InboxScope = Extract<StoreType, "public" | "protected">;

packages/polyfill/src/shared-wallet/account-registry.ts

@@ -85,7 +85,7 @@ import { hasReadCap, isNuri } from "../model/nuri";
 import { mintCap } from "../emulated-verifier/caps";
 import { mustNotAttempt } from "../emulated-verifier/reach";
 import { accessLogPrefix, logStage, shortNuri } from "./access-log";
-import type { InboxScope, Nuri, Scope } from "../model/types";
+import type { InboxScope, Nuri, StoreType } from "../model/types";
 
 // --- sharedWalletShim model ----------------------------------------------
 
@@ -166,7 +166,7 @@ export const STORE_BRANCH_SUBJECT = `${SHIM}:storeBranch`;
 /**
  * Fixed subject of the **Header branch** emulation, inside an ENTITY document — the
  * first compartment we put in a document the consumer also reads, hence the filter in
- * `read-model.ts` (every `${SHIM}:` subject is machinery and never surfaces as data).
+ * `read-document.ts` (every `${SHIM}:` subject is machinery, and the internal read drops it).
  *
  * It carries what must be readable by *whoever can read the document*, as opposed to
  * what belongs to its owner alone. Today that is one thing: the ADDRESS of the
@@ -404,8 +404,8 @@ function recordFromRows(
   // The ONE place the `""`-for-corrupt case is absorbed. `VirtualUserRecord` promises
   // real NURIs; a shim missing a scope document yields `""` here, exactly as it
   // always has, and the cast records that this is a KNOWN gap rather than a proven
-  // invariant. Callers already test for the empty value (e.g. `watchShape` skips a
-  // falsy container). Rejecting such a record outright would be the right fix and is
+  // invariant. Callers already test for the empty value (`listMyEntityDocs` reads
+  // nothing out of a falsy container). Rejecting such a record outright would be the right fix and is
   // a behaviour change — its own lot, not this one.
   return {
     id: id || fallbackId,
@@ -703,8 +703,8 @@ async function writeRecord(doc: Nuri, record: VirtualUserRecord): Promise<void>
  *
  * ── Why this is load-bearing (concurrent-provision de-dup) ──────────────────
  * On a fresh page over the persistent wallet, SEVERAL independent callers hit
- * `ensureAccount(A)` near-simultaneously (watchShape public/protected, the container
- * subscriptions, the app's owned-events effect). With the barrier-authoritative
+ * `ensureAccount(A)` near-simultaneously (a listing per store, an inbox enumeration, the
+ * app's own effects). With the barrier-authoritative
  * resolveAccount a fresh page NO LONGER mistakes sync-lag for absence — but if the
  * account is GENUINELY new, N concurrent callers would still each see 0 and each
  * provision a set of scope docs (an in-session fork). De-duping concurrent provisions
@@ -918,7 +918,7 @@ export async function isKnownInbox(nuri: Nuri): Promise<boolean> {
 }
 
 /** The index document NURI of an account for a scope (the store-container). */
-export function storeOf(record: VirtualUserRecord, scope: Scope): Nuri {
+export function storeOf(record: VirtualUserRecord, scope: StoreType): Nuri {
   return scope === "public"
     ? record.docPublic
     : scope === "protected"
@@ -931,7 +931,7 @@ export function storeOf(record: VirtualUserRecord, scope: Scope): Nuri {
  * per-scope index document, for entities that need no per-entity document / no
  * inbox). For per-entity scopes use {@link createEntityDoc} instead.
  */
-export async function resolveWriteGraph(id: string, scope: Scope): Promise<Nuri> {
+export async function resolveWriteGraph(id: string, scope: StoreType): Promise<Nuri> {
   const record = await ensureAccount(id);
   return storeOf(record, scope);
 }
@@ -952,7 +952,7 @@ export async function resolveWriteGraph(id: string, scope: Scope): Promise<Nuri>
 
 /** The native store NURI backing `scope`, resolved from the injected session.
  *  Requires `protectedStoreId` on the session for the non-private scopes. */
-async function scopeStoreNuri(scope: Scope): Promise<Nuri> {
+async function scopeStoreNuri(scope: StoreType): Promise<Nuri> {
   const s = await session();
   if (scope === "private") return `did:ng:${s.privateStoreId}`;
   // public + protected → the protected native store (see note above). Falls
@@ -968,8 +968,7 @@ async function scopeStoreNuri(scope: Scope): Promise<Nuri> {
  * store-id and builds no NURI. Use the returned value as both the read scope
  * (`useShape(shape, nuri)`) and the `@graph` write target.
  */
-// @provenance storeRegistry.resolveScopeGraph kind=aligned level=2 ref=sdk/js/web/src/index.ts:Session — `did:ng:` + `private_store_id | protected_store_id | public_store_id`, straight off the session
-export async function resolveScopeGraph(scope: Scope): Promise<Nuri> {
+export async function resolveScopeGraph(scope: StoreType): Promise<Nuri> {
   return scopeStoreNuri(scope);
 }
 
@@ -1037,7 +1036,7 @@ const inboxCache = new Map<string, Nuri>();
  * says anything about inboxes — `@ng-org/web` has no method containing "inbox" and the
  * session exposes none — so the engine's model is what decides, and it says two.
  *
- * **The private store has none**, hence {@link InboxScope} rather than `Scope`: asking
+ * **The private store has none**, hence {@link InboxScope} rather than `StoreType`: asking
  * for a private inbox is not a lookup that returns nothing, it is a question the model
  * has no meaning for.
  *
@@ -1140,7 +1139,7 @@ export async function userInbox(id: string, scope: InboxScope): Promise<Nuri> {
  * it does not carry its key. The key goes to what the creator holds (see
  * {@link holdOwnCap}), which is where you look it up.
  */
-export async function createEntityDoc(id: string, scope: Scope): Promise<Nuri> {
+export async function createEntityDoc(id: string, scope: StoreType): Promise<Nuri> {
   const record = await ensureAccount(id);
   const indexDoc = storeOf(record, scope);
   const entityNuri = await createDoc();
@@ -1165,7 +1164,7 @@ export async function createEntityDoc(id: string, scope: Scope): Promise<Nuri> {
       s.sessionId,
       // NO explicit `GRAPH <…>` wrapper: write the anchored DEFAULT graph (the
       // `indexDoc` anchor scopes it) — the CANONICAL, always-safe shape the anchored
-      // default-graph read queries (readUserStore below, same as read-model.ts).
+      // default-graph read queries (readUserStore below, same as read-document.ts).
       // entityNuri is a NURI stored as a literal → escapeLiteral.
       `INSERT DATA { <${MAIN_BRANCH_SUBJECT}> <${P.contains}> "${escapeLiteral(entityNuri)}" }`,
       indexDoc,
@@ -1263,20 +1262,13 @@ export async function readUserStore(indexDoc: Nuri): Promise<Nuri[]> {
   return out;
 }
 
-/**
- * The scope-INDEX document NURI of ONE account (`id`) for `scope` — the
- * store-container document that LISTS the account's per-entity document NURIs
- * (what {@link listMyEntityDocs} reads). Exposed so a reactive reader
- * ({@link watchShape}) can SUBSCRIBE to this index document and re-resolve the
- * entity-doc set when the index changes (a new entity created appends a NURI
- * here). Idempotent via `ensureAccount`'s cache. At migration this becomes the
- * user's real per-scope store NURI (the container the store itself provides).
- */
-// @provenance userStoreDoc kind=aligned level=2 ref=sdk/js/web/src/index.ts:Session — the per-scope index document stands in for the store the session names directly
-export async function userStoreDoc(id: string, scope: Scope): Promise<Nuri> {
-  const record = await ensureAccount(id);
-  return storeOf(record, scope);
-}
+// `userStoreDoc(id, scope)` was REMOVED in `1.0.0-dev.6`. It handed out the scope-INDEX
+// document so that a reactive reader could SUBSCRIBE to it and re-resolve its document set
+// when the index changed - and the reactive reader was the only thing that ever wanted it.
+// `useShapeQuery` now reads through the SDK's own shape query, which follows the data
+// rather than a container this package maintains, so the last caller went with the
+// pipeline. `storeOf(await ensureAccount(id), scope)` is the two-line body, for whoever
+// needs the value again.
 
 /**
  * The entity-document NURIs of `scope` belonging to ONE account (`id`) —
@@ -1300,7 +1292,7 @@ export async function userStoreDoc(id: string, scope: Scope): Promise<Nuri> {
  * Nothing to list is NOT a failure and stays silent: a store that answers with zero
  * documents means this account created none, which is a fact.
  */
-export async function listMyEntityDocs(id: string, scope: Scope): Promise<Nuri[]> {
+export async function listMyEntityDocs(id: string, scope: StoreType): Promise<Nuri[]> {
   const record = await ensureAccount(id);
   const store = storeOf(record, scope);
   const docs = await readUserStore(store);

packages/polyfill/src/shared-wallet/bootstrap.ts

@@ -15,7 +15,17 @@
  * The entry now only re-exports; the internals import this module instead.
  */
 
-import type { NgLike, UseShapeLike, Nuri, NuriLike, PrincipalId, ReadCap } from "../model/types";
+import type {
+  NgLike,
+  UseShapeLike,
+  OrmSubscriptionLike,
+  GetObjectsLike,
+  InsertObjectLike,
+  Nuri,
+  NuriLike,
+  PrincipalId,
+  ReadCap,
+} from "../model/types";
 import type { SharedWalletConfig } from "./access-gate";
 import { toNuri } from "../model/nuri";
 import type { RegistrySession } from "./account-registry";
@@ -113,6 +123,36 @@ export interface EventuallyConfig {
   ng: NgLike;
   /** The REAL `@ng-org/orm` `useShape`. */
   useShape: UseShapeLike;
+  /**
+   * The REAL `@ng-org/orm` `RdfOrmSubscription.getOrCreate` - the SDK's shape query,
+   * which is what {@link ../surface/use-shape-query}.useShapeQuery reads through since
+   * `1.0.0-dev.6`. Pass it as it stands: `ormSubscription: RdfOrmSubscription.getOrCreate`.
+   *
+   * OPTIONAL, and that is a scope decision rather than a soft one: an application that
+   * never calls `useShapeQuery` has nothing to inject here, and every suite of this
+   * package that exercises another surface would otherwise carry a stub for a call it
+   * does not make. What is NOT optional is the consequence - `useShapeQuery` without it
+   * publishes `isError` naming this field, never an empty set, because "nobody answered"
+   * reported as "there is nothing" is the one failure that surface exists to prevent.
+   */
+  ormSubscription?: OrmSubscriptionLike;
+  /**
+   * The REAL `@ng-org/orm` `getObjects` - the SDK's one-shot read, which
+   * {@link ../surface/orm}.getObjects wraps with the capability filter. Pass it as it
+   * stands: `getObjects`.
+   *
+   * OPTIONAL for the same scope reason as {@link ormSubscription}: an application that
+   * never calls it has nothing to inject, and every suite exercising another surface would
+   * otherwise carry a stub for a call it does not make. Absent, the wrapper throws naming
+   * this field rather than answering with an empty result.
+   */
+  getObjects?: GetObjectsLike;
+  /**
+   * The REAL `@ng-org/orm` `insertObject` - the SDK's subscription-free write, which
+   * {@link ../surface/orm}.insertObject wraps with the write guard. Pass it as it stands:
+   * `insertObject`. Optional, and absent the wrapper throws naming this field.
+   */
+  insertObject?: InsertObjectLike;
   /**
    * POINTER micro-guard budget — see {@link StoreRegistryDeps.pointerGuard}. Left unset
    * → a single read, which keeps the synchronous unit fakes fast.
@@ -275,7 +315,7 @@ export function configureStoreRegistry(deps: StoreRegistryDeps): void {
   // Fire the outbox inspection (Volet 3 of the low-level data-path trace) once,
   // on the FIRST successful `getSession()` resolution — the most reliable
   // "a session is established" signal available: every low-level reader/writer
-  // (store-registry, open-repo, read-model, subscribe, inbox) reaches its
+  // (store-registry, open-repo, read-document, subscribe, inbox) reaches its
   // session through this SAME injected `getSession`, so wrapping it HERE catches
   // the first success from whichever caller happens to run first, instead of
   // tying the probe to one particular call site. Only on SUCCESS (an error
@@ -384,7 +424,7 @@ export function getCurrentUser(): PrincipalId | null {
 }
 
 /** The emulated cap registry — what the current identity holds, plus the emulated
- *  public store. The read filter and the read-model consult it. */
+ *  public store. The read filter and the document read consult it. */
 export function getCaps(): CapRegistry {
   return caps;
 }
@@ -414,7 +454,7 @@ export function hasCap(nuri: NuriLike): boolean {
  */
 export function resetCaps(): void {
   // Clear IN PLACE rather than rebuilding: whoever subscribed to the registry's
-  // change signal (`watchShape`) stays subscribed to the live instance instead of
+  // change signal (`useShapeQuery`) stays subscribed to the live instance instead of
   // silently holding a listener on an orphaned one.
   caps.clear();
   // …and forget which documents were already asked about, or the emulated public-store

packages/polyfill/src/surface/docs.ts

@@ -24,7 +24,7 @@ import type { Nuri, NuriLike } from "../model/types";
 // through `sparqlQuery`, every write through `sparqlUpdate` (+ container creation
 // through `docCreate`) — each ultimately calling the real injected `ng` here. The
 // access log is therefore instrumented HERE so no access path escapes it. Callers
-// pass a semantic `label` (readDoc|readUnion|listMyEntityDocs|writeEntity|deposit
+// pass a semantic `label` (readDocument|listMyEntityDocs|writeEntity|deposit
 // |…); it is a lib-internal probe param, NOT forwarded to the real `ng` (the docs
 // primitives forward the exact SDK signature — see test/docs.test.ts). When the
 // log is OFF (default) the extra param is inert and costs one boolean read.
@@ -151,6 +151,11 @@ export async function sparqlQuery(
   // public store gives its cap to whoever asks, and this is a door an application can
   // reach with nothing but a bare reference. Inert once the cap is held, memoised
   // otherwise — see public-store.ts.
+  //
+  // It REJECTS when the store could not be asked, and that rejection is deliberately not
+  // caught here. The refusal below would otherwise take its place and report the wrong
+  // event: "you do not hold this document's cap" for "nobody answered". Both stop the
+  // read; only one of them tells the reader to try again.
   if (anchor !== undefined) {
     await fetchReadCap(anchor);
     assertMayReach(anchor, "docs.sparqlQuery");

packages/polyfill/src/surface/inbox.ts

@@ -39,11 +39,12 @@ import {
   traceProcessed,
 } from "../emulated-verifier/inbox-processor";
 import {
-  applyDeposit,
   capOfPayload,
   kindOf,
   linkPayload,
 } from "../emulated-verifier/inbox-dispatch";
+import { deliverDeposits } from "../emulated-verifier/inbox-consume";
+import type { StoredDeposit } from "../emulated-verifier/inbox-consume";
 import {
   accountKey,
   inboxOwner,
@@ -142,9 +143,14 @@ function summarizePayload(payload: unknown): string {
  * Shared by the two readers of an inbox — its owner ({@link read}) and the emulated
  * processor draining it for that owner ({@link processForOwner}) — so the two cannot
  * come to disagree about what a deposit looks like.
+ *
+ * `?d`, the deposit's own subject, is selected because CONSUMING one names it: `post`
+ * mints a fresh unique subject per deposit, so it is the key that retires that deposit and
+ * no other, where a `ts` two deposits could share is not. It never reaches an application
+ * — `depositsFrom` keeps it beside the {@link Deposit} rather than in it.
  */
 const DEPOSITS_QUERY = `
-    SELECT ?payload ?ts ?from WHERE {
+    SELECT ?d ?payload ?ts ?from WHERE {
       ?d a <${P.type}> ;
          <${P.payload}> ?payload ;
          <${P.ts}> ?ts .
@@ -206,7 +212,7 @@ export async function post(targetInboxLike: NuriLike, opts: PostOptions): Promis
 
   // NO explicit `GRAPH <…>` wrapper — write the anchored DEFAULT graph:
   // `sparqlUpdate(sid, update, targetInbox)` scopes the write to that repo's
-  // default graph (same shape as read-model.ts readDoc/readUnion). This is the
+  // default graph (same shape as `read-document.ts`'s anchored read). This is the
   // CANONICAL, always-safe shape and the one the anchored default-graph read
   // queries. (Not a round-trip necessity on the current broker: the e2e harness
   // `packages/polyfill/e2e/` verified that an anchored `GRAPH <plainNuri>` write
@@ -305,18 +311,30 @@ export async function postToDocument(docLike: NuriLike, opts: PostOptions): Prom
  * user's store. Reading the raw deposits a second time would mean re-parsing them, so
  * what the read already decoded is what the pass works from.
  */
-const seenByInbox = new Map<Nuri, unknown[]>();
-function declaredIn(inbox: Nuri): unknown[] {
+const seenByInbox = new Map<Nuri, StoredHere[]>();
+function declaredIn(inbox: Nuri): StoredHere[] {
   return seenByInbox.get(inbox) ?? [];
 }
 
 
+/**
+ * A deposit as it is STORED — its subject and what an application would see of it. The
+ * subject is what {@link processInbox} and {@link processForOwner} hand to the consuming
+ * primitive; it is emulation detail and stays inside this package.
+ */
+interface StoredHere extends StoredDeposit {
+  readonly deposit: Deposit;
+}
+
 /**
  * The deposits a raw SELECT result carries, sorted by `ts` ascending — the one place the
  * stored shape is turned back into {@link Deposit}s, for both readers of an inbox.
+ *
+ * Each keeps the subject it was read under, because a drain has to be able to RETIRE the
+ * deposit it just applied and a `ts` does not identify one.
  */
-function depositsFrom(result: unknown): Deposit[] {
-  const deposits: Deposit[] = [];
+function depositsFrom(result: unknown): StoredHere[] {
+  const stored: StoredHere[] = [];
   for (const row of readBindings(result)) {
     const rawPayload = row.payload?.value ?? "null";
     let payload: unknown;
@@ -328,10 +346,14 @@ function depositsFrom(result: unknown): Deposit[] {
     const tsRaw = row.ts?.value ?? "0";
     const ts = Number.parseInt(tsRaw, 10) || 0;
     const fromValue = row.from?.value;
-    deposits.push({ from: fromValue ? fromValue : null, payload, ts });
+    stored.push({
+      subject: row.d?.value ?? "",
+      payload,
+      deposit: { from: fromValue ? fromValue : null, payload, ts },
+    });
   }
-  deposits.sort((a, b) => a.ts - b.ts);
-  return deposits;
+  stored.sort((a, b) => a.deposit.ts - b.deposit.ts);
+  return stored;
 }
 
 // What a deposit DECLARES itself to be, and what each declaration means, live in
@@ -539,26 +561,35 @@ export async function read(targetInboxLike: NuriLike): Promise<Deposit[]> {
   // registry's change signal, which is what makes a view that was empty for want of a cap
   // re-read instead of staying stale.
   const delivered: Deposit[] = [];
-  const declared: unknown[] = [];
+  const declared: StoredHere[] = [];
   // The ownership guard ran at entry; the filing happens several awaits later, and filing
   // resolves WHO is holding at that moment. So an application switching identity in the
   // gap could have this inbox's caps land in the NEW holder's ring. A hazard read off the
   // code, not a leak anyone reproduced — see `caps.holderKey`.
   //
   // Abandoning is the faithful answer: upstream an inbox is processed by ITS owner's
-  // verifier, and switching user is another session. Nothing is lost — an inbox is not
-  // consumed by reading, so the next connection under the right identity files them.
+  // verifier, and switching user is another session. Nothing is lost, and READING is still
+  // what leaves it that way: this pass only HOLDS caps in memory, and a deposit is retired
+  // by the applying pass alone (`emulated-verifier/inbox-consume.ts`), which this one
+  // never reaches. So an abandoned read leaves the queue exactly as it found it.
   const stillOwner = getCurrentUser() === owner;
   for (const d of deposits) {
-    if (kindOf(d.payload) !== null) declared.push(d.payload);
+    if (kindOf(d.payload) !== null) declared.push(d);
     const cap = capOfPayload(d.payload);
     if (cap) {
       if (stillOwner) getCaps().learnFor(ownerKey, cap);
       continue;
     }
-    delivered.push(d);
+    delivered.push(d.deposit);
   }
-  if (declared.length > 0) seenByInbox.set(targetInbox, declared);
+  // UNCONDITIONAL since 2026-08-26, and the empty case is the whole point: this used to be
+  // written only when something was declared, so a read that found nothing left the PREVIOUS
+  // read's list standing. Harmless while nothing was consumed — the arms are idempotent — but
+  // once deposits are popped it means a later `processInbox` works from a list of deposits
+  // that are already gone, re-popping and RE-APPLYING them. That refutes "delivered exactly
+  // once" outright, and the path is real: `processForOwner` drains through `readForHolder`
+  // and never touches this map, so the owner's own next pass inherits a stale one.
+  seenByInbox.set(targetInbox, declared);
   // Domain-level diagnostic (on top of docs.ts's generic access-path READ log
   // of raw triple-rows): how many DEPOSITS were found, and the decoded data of
   // each — the exact visibility needed to trace materialization at the owner
@@ -688,9 +719,11 @@ export async function readSyncedForDocument(docLike: NuriLike): Promise<Deposit[
  *
  * So the holder the guard authorised is the one the filing is checked against, and a switch
  * ABANDONS — the same answer {@link read} gives for its own half of this window, and the
- * same one `connect.connectedUser` gives for a drain it started. Nothing is lost: an inbox
- * is not consumed by being read, so the deposit is still there for its owner's next
- * connection or its next push. Filing it FOR the absent owner instead would be a write on
+ * same one `connect.connectedUser` gives for a drain it started. What that saves is
+ * everything NOT yet reached: reading consumes nothing, so those deposits are still there
+ * for the owner's next connection or next push. The one being applied when the identity
+ * moved is not among them — it was popped first, and `inbox-consume.deliverDeposits`
+ * reports it ungated rather than pretending it waits. Filing it FOR the absent owner instead would be a write on
  * somebody else's store from a published call — which is the deferred processor's
  * deliberate, unpublished privilege (`emulated-verifier/inbox-processor.ts`), not this one's.
  */
@@ -710,24 +743,21 @@ export async function processInbox(targetInboxLike: NuriLike): Promise<Deposit[]
   // precisely the mis-filing the capture exists to prevent, and it must not have a value.
   if (holder === null) return deposits;
   const ring = accountKey(holder);
-  for (const payload of declared) {
-    // Re-checked per item, not once: an arm reads and writes, so the identity can move
-    // between two of them just as easily as during the read.
-    if (getCurrentUser() !== holder) {
-      logStage(
-        "ABANDONED " + shortNuri(targetInbox) + " — the identity changed while it was being " +
-          "processed; its deposits stay for their owner",
-      );
-      return deposits;
-    }
-    // The `match`, one arm per declared type — `emulated-verifier/inbox-dispatch.ts`.
-    await applyDeposit(payload, {
-      owner: holder,
-      ring,
-      inbox: targetInbox,
-      ownerHoldsTheSession: true,
-    });
-  }
+  // Consume-and-apply, through the ONE primitive both triggers share
+  // (`emulated-verifier/inbox-consume.ts`). Each deposit is popped before its arm runs and
+  // is not seen again — this pass no longer relies on being safe to repeat.
+  //
+  // The identity is re-checked per item there as it was here, and for the same reason: an
+  // arm reads and writes, so the holder can move between two of them just as easily as
+  // during the read. Abandoning now leaves only the deposits NOT yet reached; the ones
+  // already popped were applied for the holder that was authorised at the time.
+  await deliverDeposits(declared, {
+    owner: holder,
+    ring,
+    inbox: targetInbox,
+    ownerHoldsTheSession: () => true,
+    stillTheHolder: () => getCurrentUser() === holder,
+  });
   return deposits;
 }
 
@@ -787,7 +817,7 @@ async function processForOwner(targetInbox: Nuri): Promise<void> {
   // still refused by `readForHolder` below.
   //
   // ONE visible consequence, and it is deliberate: filing a cap fires the registry's change
-  // signal, which is global rather than per-holder, so a `watchShape` open in the connected
+  // signal, which is global rather than per-holder, so a `useShapeQuery` open in the connected
   // session re-reads. It re-reads the SAME data — the connected identity gains nothing —
   // and the signal cannot be suppressed for the other case this same path serves: an owner
   // draining an inbox on their own document, where re-reading is exactly the contract
@@ -800,20 +830,25 @@ async function processForOwner(targetInbox: Nuri): Promise<void> {
   const deposits = depositsFrom(
     await readForHolder(sid, DEPOSITS_QUERY, targetInbox, ownerRing, "inboxProcess"),
   );
-  let applied = 0;
-  for (const deposit of deposits) {
-    // The SAME `match` the owner's own session runs, with the holder named instead of
-    // resolved — and told whether the owner is the one holding the page, because an arm
-    // that would write application data into the owner's documents must not run from a
-    // stranger's session (`emulated-verifier/inbox-dispatch.ts`).
-    const done = await applyDeposit(deposit.payload, {
-      owner: ownerId,
-      ring: ownerRing,
-      inbox: targetInbox,
-      ownerHoldsTheSession: getCurrentUser() === ownerId,
-    });
-    if (done) applied += 1;
-  }
+  // The SAME consume-and-apply the owner's own session runs, with the holder named instead
+  // of resolved — and told whether the owner is the one holding the page, because an arm
+  // that would write application data into the owner's documents must not run from a
+  // stranger's session, and what such an arm declines must not be consumed either
+  // (`emulated-verifier/inbox-dispatch.claimsDeposit`).
+  //
+  // ONE primitive, not a copy of it: a trigger decides WHO drains and WHEN, never what
+  // consuming means. `emulated-verifier/inbox-consume.ts` holds the only removal.
+  const applied = await deliverDeposits(deposits, {
+    owner: ownerId,
+    ring: ownerRing,
+    inbox: targetInbox,
+    // Asked PER DEPOSIT, not snapshotted once for the run — the identity can arrive or
+    // leave between two arms, and this decides both what an arm may do and what may be
+    // popped. Hoisting it out of the loop (briefly, on 2026-08-26) meant a drain that
+    // started while the owner happened to be connected went on treating every later
+    // deposit as his, applying application data under whoever held the page by then.
+    ownerHoldsTheSession: () => getCurrentUser() === ownerId,
+  });
   traceProcessed(targetInbox, ownerRing, applied);
 }
 

packages/polyfill/src/surface/lifecycle.ts

@@ -23,6 +23,7 @@
 import { getConfig, rememberHandOver } from "../shared-wallet/bootstrap";
 import { settleIdentity } from "../shared-wallet/access-gate";
 import { captureSession, expectSession } from "../shared-wallet/session";
+import { wrappedNg } from "./ng-proxy";
 
 /**
  * Forwards to the real `@ng-org/web` `init`, once the identifier is in the address bar.
@@ -90,10 +91,33 @@ export function init(...args: any[]): any {
   return settleIdentity().then(delegate);
 }
 
-/** Forwards to the real `@ng-org/orm` `initNg` (ORM signals). */
-// @provenance initNg kind=passthrough level=3 ref=sdk/js/orm/src/core.ts:initNg — upstream's own exported name for `initNgSignals`
+/**
+ * Forwards to the real `@ng-org/orm` `initNg` (ORM signals) - with the `ng` in position 0
+ * replaced by this package's own wrapped one.
+ *
+ * -- Why the substitution, and why it is invisible to the caller ------------
+ * `initNg(ngImpl, session)` is how the ORM is told which `ng` to reach the engine
+ * through: it resolves a module-level promise every subscription, every `insertObject`
+ * and every batched patch awaits afterwards. So whatever is handed over HERE is the `ng`
+ * every ORM write leaves by - and an ORM write leaves by `ng.graph_orm_update`, which is
+ * where this package's write guard sits (`ng-proxy.ts`). Handing over the caller's raw
+ * SDK object leaves that guard on a door nothing knocks on.
+ *
+ * It is the same argument `init`'s callback wrapping above rests on, and it lands the same
+ * way: the invariant is carried by COMPOSITION rather than by an instruction a caller gets
+ * to get wrong once. "Pass the package's `ng` to `initNg`" would be an ordering rule in
+ * prose, unenforceable and silent when missed - and it WAS missed, by both consumers in
+ * this repository, which is how the hole was found.
+ *
+ * Nothing is taken from the caller: `wrappedNg()` forwards every one of its members to
+ * the very object `configure()` received, and it is the same object `ng` publishes, so the
+ * ORM now reaches the engine through exactly what the application does. The remaining
+ * arguments and the return value pass straight through.
+ */
+// @provenance initNg kind=passthrough level=3 ref=sdk/js/orm/src/core.ts:initNg - upstream's own exported name for `initNgSignals`; the arguments and the return pass through, and the `ng` in position 0 is replaced by this package's wrapped one so the ORM's writes meet the emulated write guard
 export function initNg(...args: any[]): any {
   const f = getConfig().initNg;
   if (!f) throw new Error("[ng-eventually] initNg() not injected — pass it to configure()");
-  return f(...args);
+  const [, ...rest] = args;
+  return f(wrappedNg(), ...rest);
 }

packages/polyfill/src/surface/ng-proxy.ts

@@ -7,13 +7,50 @@
 import type { NG } from "@ng-org/web";
 
 import { getConfig, getCaps, getCurrentUser } from "../shared-wallet/bootstrap";
+import { assertMayWrite } from "../emulated-verifier/reach";
+import { isNuri } from "../model/nuri";
 import type { Nuri } from "../model/types";
 
 /**
- * Typed `NG` — upstream's own type for `ng` (`NG = typeof NGModule`, 88 exported members,
- * installed `index.d.ts:136-231`). The proxy adds no member and removes none, so this is
- * the honest declaration; it used to be `Record<string, any>`, which silently dropped all
- * 88 signatures and let any misspelt member typecheck.
+ * The documents a batch of ORM patches writes into.
+ *
+ * Every patch the ORM sends carries a `path` whose FIRST segment is the synthetic id of
+ * the root object it touches - `<graph>|<subject>` - whether the patch adds a root
+ * object, removes one, or updates a property several levels down
+ * (`RdfOrmSubscription.deepPatchesToWasm` joins the path, and
+ * `signalObjectPropGenerator` is what minted that id). So the document is readable from
+ * the path alone, and it is the only thing in the batch this guard needs.
+ *
+ * A patch whose path names no NextGraph reference is left out rather than refused. The
+ * emulation cannot say whose document such a write lands in - and upstream does not have
+ * to guess, because `verify_permission` fires on the commit itself. Inventing a refusal
+ * the target does not have would be the divergence, not the passthrough.
+ */
+function graphsWrittenBy(patches: unknown): Nuri[] {
+  const out: Nuri[] = [];
+  if (!Array.isArray(patches)) return out;
+  for (const patch of patches) {
+    const path = (patch as Record<string, unknown> | null)?.["path"];
+    if (typeof path !== "string") continue;
+    const graph = path.replace(/^\//, "").split("|")[0];
+    if (graph !== undefined && isNuri(graph) && !out.includes(graph)) out.push(graph);
+  }
+  return out;
+}
+
+/**
+ * Typed `NG` - upstream's own type for `ng`. `NG = typeof NGModule`, the `NGModule`
+ * namespace of the installed `@ng-org/web`, which at `0.1.2-alpha.14` declares 90 members:
+ * 84 functions and 6 RDF classes. The proxy adds no member and removes none, so this is
+ * the honest declaration; it used to be `Record<string, any>`, which silently dropped
+ * every signature and let any misspelt member typecheck.
+ *
+ * The count is named with its RELEASE because it moves with one, and this one had stopped
+ * matching: the figure recorded here was two short, and two of the ninety -
+ * `graph_orm_next_page` and `graph_orm_previous_page` - appear nowhere in the cited
+ * checkout's `sdk/js/lib-wasm/src/lib.rs`, the tree that declares the PREVIOUS release
+ * `@ng-org/web@0.1.2-alpha.13`. A count with no release beside it is a claim nobody can
+ * re-check against anything, so it drifts in silence - which is what happened.
  *
  * The empty object is only the Proxy's TARGET: every property is answered by the `get`
  * trap below, never by the target, so there is nothing to put in it. Typing the target is
@@ -71,13 +108,79 @@ export function makeNg(): NG {
           };
         }
 
+        // graph_orm_update -> the SAME write guard, on the door the ORM actually uses.
+        //
+        // An ORM write never passes through `sparql_update`: a mutation of a live signal
+        // object (`set.add(...)`, `set.delete(...)`, assigning a property) is batched by the
+        // subscription and sent as PATCHES through this member instead. So the override
+        // above saw no ORM add and no ORM delete at all - a rights hole that an
+        // application reaches from the published surface, since `useShape` forwards
+        // `add`/`delete`/`clear` to the underlying set and `useShapeQuery`'s `data` items
+        // ARE that set's objects. It is closed here rather than at each of those
+        // surfaces, because here is where every one of them converges.
+        //
+        // The predicate is OWNERSHIP (`assertMayWrite`), not the write-cap list the
+        // `sparql_update` branch above consults: that list is decorative - `grantWrite`
+        // has no production caller, so it never fires - and a guard that never fires
+        // closes nothing. `sparql_update` is deliberately left on it all the same: this
+        // library's own REGISTERS are written through that member, and a store document
+        // is not owned in the authorship sense, so arming it there would refuse every
+        // register write (`emulated-verifier/register-write.ts`, and the note on
+        // `assertMayWrite`). The ORM's patches never carry a register.
+        //
+        // args = (subscription_id, patches, session_id).
+        if (prop === "graph_orm_update") {
+          return async (...args: unknown[]): Promise<unknown> => {
+            for (const graph of graphsWrittenBy(args[1])) {
+              await assertMayWrite(graph, "ng.graph_orm_update");
+            }
+            return ng[prop]!(...args);
+          };
+        }
+
         // TODO(anticipated API): a sealed inbox deposit + capability operations — expose
         // here with their anticipated signatures, emulated for now.
       }
 
       // Everything else: passthrough to the real SDK, unchanged.
+      //
+      // FORWARDED, never BOUND, and the difference is not a style choice. `@ng-org/web`'s
+      // `ng` is ITSELF a Proxy - an "async proxy" whose `get` trap answers EVERY key with
+      // a fresh path-carrying callable, and whose reflection traps throw outright
+      // (`dist/ngweb.js`, the `l(e = [])` factory). So `real.bind(ng)` never reaches
+      // `Function.prototype.bind`: `bind` is just another key, the trap hands back a
+      // callable for the path `<member>.bind`, calling it posts a remote request named
+      // after the MEMBER with the bind arguments, and what comes back is a PROMISE.
+      //
+      // The published `ng` therefore answered every member with a promise instead of a
+      // function, and a caller got the SDK's own `<member> is not a function`. What made
+      // it invisible for months is that this library's internals never go through this
+      // proxy - they call the injected `ng` directly - and every fake in the suite is a
+      // plain object, on which `bind` behaves. It surfaced the moment the ORM was handed
+      // this object (`surface/lifecycle.ts`): `orm_start_graph` was not a function, the
+      // ORM catches that and only logs it, so a shape read simply stayed pending for
+      // ever. MEASURED against the installed `@ng-org/web@0.1.2-alpha.14`.
+      //
+      // `Reflect.apply` is the passthrough that holds for both: it invokes the member
+      // with the real `ng` as receiver, which a plain object needs and which the async
+      // proxy ignores in favour of the path it already carries.
       const real = Reflect.get(ng, prop);
-      return typeof real === "function" ? real.bind(ng) : real;
+      if (typeof real !== "function") return real;
+      return (...args: unknown[]): unknown => Reflect.apply(real, ng, args);
     },
   });
 }
+
+/**
+ * THE wrapped `ng` - one object for the whole package.
+ *
+ * `index.ts` publishes it and `surface/lifecycle.ts` hands it to the ORM, and those two
+ * have to be the SAME object: a second proxy would behave identically today, and would be
+ * a second place to notice the day one of them gains an override. It holds no state of its
+ * own - every property is answered from `getConfig()` at access time - so it survives a
+ * re-`configure()` and needs no reset.
+ */
+let wrapped: NG | null = null;
+export function wrappedNg(): NG {
+  return (wrapped ??= makeNg());
+}

packages/polyfill/src/surface/orm.ts

@@ -0,0 +1,171 @@
+/**
+ * The ORM family this package offers an application - the SDK's one-shot read and its
+ * subscription-free write, each WRAPPED at the same name and the same signature.
+ *
+ * -- Why wrapped, and never re-exported ------------------------------------
+ * `export { getObjects } from "@ng-org/orm"` would compile and would look like the most
+ * faithful thing available. It is the opposite: it hands the caller a path straight to
+ * the SDK that SHORT-CIRCUITS the emulation - the capability filter, and above all the
+ * shared-wallet identity boundary, which is the whole of what this package protects. One
+ * wallet hosts every identity here, so an unwrapped ORM read returns EVERY identity's
+ * data with nothing signalling it. Everything offered from this family is therefore
+ * wrapped; a symbol that cannot be wrapped meaningfully is not published at all.
+ *
+ * -- What each wrapper adds, and where the target does the same thing ------
+ * A READ is filtered on what comes back. `emulated-verifier/read-filter.ts` keeps only
+ * items whose document - their `@graph` - the current holder holds a cap for, which is
+ * the emulation of what the broker bounds at delivery, applied per document, exactly
+ * where `surface/use-shape.ts` and `surface/use-shape-query.ts` apply it.
+ *
+ * A WRITE is NOT filtered, and the asymmetry is upstream's rather than ours: a write is
+ * bounded by write capability - `verify_permission`, reachable only from `Commit::verify`,
+ * so it fires on commits and never on reads - and nothing is hidden from the writer. So
+ * `insertObject` takes a GUARD BEFORE the write (`emulated-verifier/reach.ts`), the same
+ * pair `docs.sparqlUpdate` takes, and never a filter over what it returns.
+ *
+ * -- The second door the guard needs, and where it is ----------------------
+ * These two wrappers guard the calls an application MAKES. They do not, and cannot, guard
+ * a mutation of a live signal object - `set.add(...)`, `set.delete(...)` on what a shape
+ * query handed back - because that write is made by the ORM itself, batched into
+ * `ng.graph_orm_update`. That door is guarded where every other `ng` call is, in
+ * `surface/ng-proxy.ts`, and `surface/lifecycle.ts` is what makes sure the ORM is holding
+ * the wrapped `ng` when it knocks on it.
+ *
+ * -- What is deliberately NOT published from this family -------------------
+ * `@ng-org/orm`'s entry also exports `RdfOrmSubscription`, `DiscreteOrmSubscription`,
+ * `ngSession`, and `getRaw` / `watch` / `effect` re-exported from
+ * `@ng-org/alien-deepsignals`. None of them is published here, and each for a reason a
+ * later reader can check rather than a preference:
+ *
+ *   - `RdfOrmSubscription` - an application never holds a subscription: it hands the
+ *     shape query to `configure` and reads `useShapeQuery`'s snapshot back (see the note
+ *     on `OrmSubscriptionHandle` in `model/types.ts`). And `getOrCreate` POOLS on a key
+ *     built from the shape and the scope alone - no identity in it - so a second virtual
+ *     user asking the same question is handed the FIRST one's live instance. What makes
+ *     that safe here is the filter this package applies on the way out; publishing the
+ *     handle would hand out the instance instead.
+ *   - `DiscreteOrmSubscription` - a JSON-CRDT document. Its items carry no `@graph`, so
+ *     the read filter has nothing to read, and its writes leave through
+ *     `discrete_orm_update`, a third channel nothing here guards. Nothing in this package
+ *     reads or writes a discrete document; publishing it would open a surface and a hole
+ *     in the same gesture.
+ *   - `ngSession` - a module-level PROMISE, not a function, and what it resolves to is
+ *     the SDK handle plus the SESSION. Here one physical session hosts every virtual
+ *     identity, so handing it out hands every identity the same one; the contract already
+ *     says the session is the package's. Wrapping a resolved value would also force a
+ *     RUNTIME `@ng-org/orm` import into this module, which is the one thing the injection
+ *     discipline exists to avoid.
+ *   - `getRaw` - it returns the object BEHIND a signal, which is the same escape hatch
+ *     `read-filter.ts` refuses on a dunder key (`__raw__`): it hands back the unfiltered
+ *     collection, every identity's items in it. There is no filtered form of it.
+ *   - `watch` / `effect` - `@ng-org/alien-deepsignals`' reactivity primitives, not the
+ *     ORM's. They carry no document and grant nothing, so there is nothing to wrap; an
+ *     application that wants them declares that package.
+ */
+
+import { getCaps, getConfig } from "../shared-wallet/bootstrap";
+import { filterReadable } from "../emulated-verifier/read-filter";
+import { assertMayReach, assertMayWrite } from "../emulated-verifier/reach";
+import { isNuri } from "../model/nuri";
+import type { GetObjectsLike, InsertObjectLike, Nuri } from "../model/types";
+// The SDK's own types, imported as TYPES (erased at build, so no runtime `@ng-org`
+// import is added here). The provenance of what is PUBLISHED is recorded in `index.ts`.
+import type { RdfOrmConfig } from "@ng-org/orm/all";
+import type { BaseType, ShapeType } from "@ng-org/shex-orm";
+
+/**
+ * The injected real function, or the error that says it was never handed over.
+ *
+ * Upstream an application imports the ORM; here it hands it to `configure`, like the
+ * `ng`, the `useShape` and the shape query beside it. Absent, there is nothing to call
+ * through to - and that has to be said out loud, naming the field to pass, rather than
+ * answered with an empty result.
+ */
+function injected<K extends "getObjects" | "insertObject">(
+  name: K,
+): NonNullable<ReturnType<typeof getConfig>[K]> {
+  const f = getConfig()[name];
+  if (!f) {
+    throw new Error(
+      `[ng-eventually] ${name}: not injected. Pass \`${name}\` (from \`@ng-org/orm\`) to ` +
+        "configure() - this package wraps the SDK's own call and has none of its own to " +
+        "fall back on.",
+    );
+  }
+  return f;
+}
+
+/**
+ * The document an ORM object declares it lives in, or `null` when it names none.
+ *
+ * `@graph` is an untyped value on a property bag (`BaseType extends Record<string, any>`),
+ * so it is NARROWED here rather than cast - the same door `read-filter.ts` reads items
+ * through, and for the same reason: anything that is not a NextGraph reference names no
+ * document.
+ */
+function graphOf(object: unknown): Nuri | null {
+  const g = (object as Record<string, unknown> | null)?.["@graph"];
+  return typeof g === "string" && isNuri(g) ? g : null;
+}
+
+/**
+ * Read objects of one shape in one scope, ONCE - the SDK's own call, with the read
+ * filter applied to what comes back.
+ *
+ * Both parameters are upstream's, passed through untouched: the {@link ShapeType} and the
+ * config it declares minus the two pagination fields a one-shot read has no use for. What
+ * comes back is upstream's too, and DETACHED - a `structuredClone` of the raw signal
+ * object - so an ARRAY when the config asks for an `orderBy` and a `Set` otherwise, and
+ * mutating an item of it reaches nothing. Deleting an item of it removes nothing either,
+ * and reports nothing: removal is a mutation of the LIVE set a subscription holds.
+ *
+ * The filter keeps the shape of the collection it was given: a `Set` in is a `Set` out.
+ * Before the first cap is issued the emulation is not in force and everything passes
+ * through, exactly as in `surface/use-shape.ts`.
+ */
+// @provenance getObjects kind=passthrough level=3 ref=sdk/js/orm/src/connector/getObjects.ts:getObjects - forwards to the injected real function; the read-filtered result emulates the subset the broker will deliver. The cited revision takes `scope: Scope | string`; the published `@ng-org/orm@0.1.2-alpha.21` widened that parameter to the config below, which is what a consumer compiles against and therefore what is mirrored here
+export async function getObjects<T extends BaseType>(
+  shapeType: ShapeType<T>,
+  config: Omit<RdfOrmConfig<T>, "pageSize" | "maxActivePages">,
+): Promise<T[] | Set<T>> {
+  const read = injected("getObjects") as GetObjectsLike;
+  const objects = await read(shapeType, config);
+  const caps = getCaps();
+  // No cap issued yet -> the emulation is not in force and the result passes through.
+  if (!caps.isEnforcing()) return objects;
+  const kept = filterReadable(objects, caps);
+  return Array.isArray(objects) ? kept : new Set(kept);
+}
+
+/**
+ * Insert one ORM-typed object, without opening a subscription for it - the SDK's own
+ * call, behind the write guard.
+ *
+ * The object must carry its `@graph`: upstream the insert subscribes to NO document, so
+ * that field is the only thing that says where the write lands, and an object without one
+ * makes the ORM throw. It is also what this guard reads, which is why the two agree
+ * without either of them being bent to the other.
+ *
+ * Two questions are asked, and they are not the same one - the pair `docs.sparqlUpdate`
+ * asks. Reaching is POSSESSION of the document's read cap. Writing is OWNERSHIP: upstream
+ * the right to write is membership of the repo, and how you came by the read key bears on
+ * it not at all - a public store serves its read cap to whoever asks, and a cap deposited
+ * in your inbox is one someone gave you. Neither makes you a writer.
+ *
+ * The refusal happens BEFORE the call, so an unauthorized write is not attempted rather
+ * than attempted and caught. An object naming no document is forwarded untouched: there
+ * is nothing here to judge, and the ORM's own refusal is the one that should be heard.
+ */
+// @provenance insertObject kind=passthrough level=3 ref=sdk/js/orm/src/connector/insertObject.ts:insertObject - forwards to the injected real function; the guard before it emulates the write capability the target checks on the commit
+export async function insertObject<T extends BaseType>(
+  shapeType: ShapeType<T>,
+  object: T,
+): Promise<T> {
+  const write = injected("insertObject") as InsertObjectLike;
+  const graph = graphOf(object);
+  if (graph !== null) {
+    assertMayReach(graph, "insertObject");
+    await assertMayWrite(graph, "insertObject");
+  }
+  return write(shapeType, object);
+}

packages/polyfill/src/surface/placement.ts

@@ -41,11 +41,12 @@
 
 import {
   createEntityDoc as registryCreateEntityDoc,
-  listMyEntityDocs as registryListMyEntityDocs,
-  resolveWriteGraph as registryResolveWriteGraph,
+  ensureAccount,
+  storeOf,
 } from "../shared-wallet/account-registry";
 import { getCurrentUser } from "../shared-wallet/bootstrap";
-import type { Nuri, Scope } from "../model/types";
+import { toNuri } from "../model/nuri";
+import type { Nuri, NuriLike, StoreType } from "../model/types";
 
 /** WHO is acting. Absent means the application has not signed in yet — a caller error,
  *  and one worth naming rather than turning into an empty result. */
@@ -60,26 +61,92 @@ function connectedIdentity(op: string): string {
   return id;
 }
 
-/** Create a document for ONE entity in `scope`, and record it in that scope's store. */
-// @provenance storeRegistry.createEntityDoc kind=aligned level=2 ref=sdk/js/lib-wasm/src/lib.rs:doc_create — upstream `doc_create` performs the `ldp:contains` listing and the `AddRepo { read_cap }` natively; here they are two explicit writes
-export async function createEntityDoc(scope: Scope): Promise<Nuri> {
-  return registryCreateEntityDoc(connectedIdentity("createEntityDoc"), scope);
+/*
+ * How an application names a STORE, and why by reference rather than by a word.
+ *
+ * Until `1.0.0-dev.5` every call here took `Scope` - the three strings `"public" |
+ * "protected" | "private"` - and that type also named the scope of a READ. The two are
+ * not one question: the SDK's `Scope` is `{ graphs, subjects }` and filters documents
+ * and subjects, while a store is chosen when a document is CREATED. Upstream the two
+ * gestures are separate too, and the creation one takes a store the caller already
+ * holds: `doc_create(session_id, crdt, class_name, destination, store_repo)`, with the
+ * private store when `store_repo` is left undefined, and the three store ids handed to
+ * the application on the session itself (`Session.private_store_id`,
+ * `protected_store_id`, `public_store_id`).
+ *
+ * So the three accessors below answer what the session answers upstream - one reference
+ * per store - and `createEntityDoc` takes one of them, exactly where `doc_create` takes
+ * its store. Nothing published spells a store as a word any more, and nothing has to be
+ * unlearned: at migration these three read the session's own fields and the reference
+ * becomes the real store's.
+ */
+
+/** Resolve one of the connected identity's three stores to its reference. */
+async function storeReference(op: string, type: StoreType): Promise<Nuri> {
+  return storeOf(await ensureAccount(connectedIdentity(op)), type);
 }
 
-/** The entity documents this user owns in `scope` — with their caps recovered. */
-// @provenance storeRegistry.listMyEntityDocs kind=aligned level=1 ref=engine/verifier/src/request_processor.rs:doc_create — reads back the `ldp:contains` listing that `doc_create` writes on the store's Main branch
-export async function listMyEntityDocs(scope: Scope): Promise<Nuri[]> {
-  return registryListMyEntityDocs(connectedIdentity("listMyEntityDocs"), scope);
+/** The connected identity's PRIVATE store — where a document goes when none is named. */
+// @provenance storeRegistry.privateStore kind=aligned level=2 ref=sdk/js/web/src/index.ts:Session — upstream the session carries `private_store_id`; here the per-store index document stands in for the store the session names directly
+export async function privateStore(): Promise<Nuri> {
+  return storeReference("privateStore", "private");
 }
 
-/** The NURI where GROUPED entities of `scope` are written (no per-entity document). */
-// @provenance storeRegistry.resolveWriteGraph kind=aligned level=2 ref=sdk/js/web/src/index.ts:Session — a scope resolves to the session's own store id; upstream the store IS the container and the per-scope index document disappears
-export async function resolveWriteGraph(scope: Scope): Promise<Nuri> {
-  return registryResolveWriteGraph(connectedIdentity("resolveWriteGraph"), scope);
+/** The connected identity's PROTECTED store. */
+// @provenance storeRegistry.protectedStore kind=aligned level=2 ref=sdk/js/web/src/index.ts:Session — upstream the session carries `protected_store_id`; here the per-store index document stands in for the store the session names directly
+export async function protectedStore(): Promise<Nuri> {
+  return storeReference("protectedStore", "protected");
 }
 
-/** The NURI to use as a READ scope for `scope` (what `useShape` is pointed at). */
-export { resolveScopeGraph } from "../shared-wallet/account-registry";
+/** The connected identity's PUBLIC store — a document placed here serves its read key
+ *  to whoever asks for it. */
+// @provenance storeRegistry.publicStore kind=aligned level=2 ref=sdk/js/web/src/index.ts:Session — upstream the session carries `public_store_id`; here the per-store index document stands in for the store the session names directly
+export async function publicStore(): Promise<Nuri> {
+  return storeReference("publicStore", "public");
+}
+
+/**
+ * Create a document for ONE entity in `store`, and record it there.
+ *
+ * `store` is one of {@link privateStore}, {@link protectedStore}, {@link publicStore};
+ * omitting it places the document in the private store, which is what `doc_create` does
+ * when its `store_repo` is left undefined.
+ */
+// @provenance storeRegistry.createEntityDoc kind=aligned level=2 ref=sdk/js/lib-wasm/src/lib.rs:doc_create — the same trailing store slot, private store when omitted; upstream `doc_create` performs the `ldp:contains` listing and the `AddRepo { read_cap }` natively, here they are two explicit writes
+export async function createEntityDoc(store?: NuriLike): Promise<Nuri> {
+  const id = connectedIdentity("createEntityDoc");
+  const record = await ensureAccount(id);
+  if (store === undefined) return registryCreateEntityDoc(id, "private");
+  const named = toNuri(store, "storeRegistry.createEntityDoc");
+  for (const type of ["private", "protected", "public"] as const) {
+    if (storeOf(record, type) === named) return registryCreateEntityDoc(id, type);
+  }
+  // A reference that is not one of this identity's three stores. Upstream a store you
+  // are not a member of refuses the creation; here it would silently land in whichever
+  // store the fallback picked, which is the "recommendation enforced by the code"
+  // failure the doctrine names. Say it instead.
+  throw new Error(
+    `[ng-eventually] storeRegistry.createEntityDoc: ${named} is not one of this ` +
+      "identity's stores. Pass `privateStore()`, `protectedStore()` or `publicStore()`, " +
+      "or nothing at all for the private store.",
+  );
+}
+
+// `listMyEntityDocs`, `resolveScopeGraph` and `resolveWriteGraph` STOPPED being published
+// in `1.0.0-dev.5`, and each for its own reason.
+//
+//   - `listMyEntityDocs` has no counterpart at any level: there is no `doc_list`, no
+//     `list_docs`, nothing in the binding. Listing what one created is an ordinary query
+//     over the store's `ldp:contains` — the same shape the anchored document read is, sugar over
+//     something already expressible. It stays reachable at `../shared-wallet/account-registry`
+//     for this library's own read path, which still calls it until that path queries the
+//     store itself.
+//   - `resolveScopeGraph` handed out a value whose stated use was a READ scope, and a
+//     store's graph holds its containment triples and nothing else: pointed at a shape
+//     query upstream it matches nothing and says so with an empty set, silently. See
+//     `.project/concepts/app-contract/knowledge_what-a-read-scope-is-upstream.md`.
+//   - `resolveWriteGraph` returned the very reference the three accessors above return.
+//     One value, one published name.
 
 export { openDocumentInbox } from "../emulated-verifier/branch-registers";
 

packages/polyfill/src/surface/read-document.ts

@@ -0,0 +1,141 @@
+/**
+ * read-document - read ONE document with an anchored SPARQL query, and group the rows
+ * it returns per subject. Library-internal: nothing here is published.
+ *
+ * -- What this replaced, and why the batch went ----------------------------
+ * Until `1.0.0-dev.8` this library published `readUnion(docs)`: the same anchored read,
+ * issued once per document, in parallel, with a batch policy of its own (a failing
+ * document was swallowed into an empty result unless the caller passed a callback to be
+ * told). Nothing upstream has a counterpart for that - it was N calls plus a policy -
+ * and its provenance annotation cited `sparql_query`, a citation that is exact attached
+ * to a claim that is false. **A composition cannot be aligned on a single function.**
+ *
+ * Every caller in production passed ONE document. So the batch is gone, and what is left
+ * is the thing upstream really does have: one anchored `sparql_query`. There is no
+ * swallow left to explain either - this throws, and the caller decides, which is the
+ * only honest answer once "one document failed" and "the read failed" are the same
+ * event.
+ *
+ * -- Why ANCHORED, and never anchorless -----------------------------------
+ * An anchored `sparql_query(sid, "SELECT ?s ?p ?o WHERE { ?s ?p ?o }", base, doc)` is
+ * restricted to the anchor repo's graph: `resolve_target_for_sparql(Repo)` ->
+ * `Some(repo_graph_name)`, which becomes the query's DEFAULT graph. A body with no
+ * `GRAPH` wrapper reads only that default graph, so only that document's triples - O(1)
+ * in the document's own size, independent of how many other graphs the local store holds.
+ *
+ * The footgun this avoids: an anchorless query (`anchor` undefined -> `UserSite` ->
+ * `set_default_graph_as_union`) spans EVERY named graph in the session store. On a shared
+ * wallet that accumulates across runs, that is O(wallet size) - the observed ~90s
+ * timeouts. Replacing several anchored reads with one anchorless query would also be a
+ * silent WIDENING of what a read can reach, so it is not an optimisation available here.
+ *
+ * NB (verified, `docs/read-model.md` probe step 4): an explicit `GRAPH ?g { ... }` body
+ * iterates the named graphs regardless of the default graph, so an anchor does not bound
+ * such a body. This read therefore uses a default-graph body - no `GRAPH` wrapper - so
+ * the anchor's one-repo restriction actually applies.
+ *
+ * -- The open in front of it is the EMULATION, not the query --------------
+ * On a fresh session over the same persistent wallet the target repo is present but
+ * UNSYNCED, and an anchored query against it legitimately matches nothing - no error,
+ * just zero rows. So {@link ensureRepoOpen} runs first and awaits the sync barrier, which
+ * is also where a document in a PUBLIC store hands over its `ReadCap`. That step is
+ * `polyfill-era` machinery: it is what one shared wallet costs, it is annotated where it
+ * lives (`emulated-verifier/open-repo.ts`), and it goes at migration with the shim.
+ *
+ * Calling it here rather than leaving it to the caller is deliberate and load-bearing:
+ * `emulated-verifier/index-deposit.ts` decides "absent" versus "unreadable" from
+ * {@link getSyncState}, and a read that never opened the repo would leave that state
+ * `unknown` - which that arm reads as "a zero-row answer MEANS it". Skipping the open
+ * would therefore turn a cold start into a destroyed deposit queue, silently. It is the
+ * failure that path has paid for twice; the barrier is not an optimisation to move.
+ */
+
+import { sparqlQuery } from "./docs";
+import { ensureRepoOpen } from "../emulated-verifier/open-repo";
+import { isMachinerySubject } from "../emulated-verifier/machinery";
+import { session } from "../shared-wallet/account-registry";
+import type { Nuri } from "../model/types";
+
+/**
+ * One subject read from a document, with its properties (predicate -> values).
+ *
+ * `subject` is typed `string`, not `Nuri`: a subject is an ordinary RDF subject and may
+ * be ANY IRI. An application that writes its entity under the document's own reference
+ * gets a reference back here, but that is its convention, not this type's promise - a
+ * document may hold several subjects under IRIs of its writer's choosing, and each comes
+ * back as written.
+ */
+export interface DocumentSubject {
+  /** The subject IRI (`?s`), exactly as the document carries it. */
+  subject: string;
+  /** predicate IRI -> the list of object values (literals or IRIs) for it. */
+  props: Record<string, string[]>;
+}
+
+/** Tolerant extraction of SPARQL SELECT bindings across the shapes `ng` can return. */
+function bindings(
+  result: unknown,
+): Array<Record<string, { value: string } | undefined>> {
+  if (!result) return [];
+  if (Array.isArray(result))
+    return result as Array<Record<string, { value: string }>>;
+  const anyRes = result as {
+    results?: { bindings?: Array<Record<string, { value: string }>> };
+  };
+  return anyRes.results?.bindings ?? [];
+}
+
+/**
+ * Read `doc`'s triples with one anchored query and return them grouped per subject.
+ *
+ * **Throws** on anything that stops the read: a reference this holder may not reach
+ * (`docs.sparqlQuery` refuses it), a broker that does not answer, a query that rejects.
+ * That is the whole point of having no batch any more - there is no other document for a
+ * failure to be tolerated in favour of, so "it failed" reaches the caller as a failure
+ * rather than as an empty answer. A document that is genuinely empty, or whose repo has
+ * not synced, returns `[]` WITHOUT throwing - and telling those two apart is the
+ * caller's job ({@link getSyncState} is what answers it).
+ *
+ * A document holding SEVERAL subjects yields several entries - one per distinct subject,
+ * carrying that subject as written. Properties of different subjects are never merged.
+ * Placing one business entity per document stays the recommended practice (a key is per
+ * repo, so isolation needs a repo per entity), but that is a recommendation about
+ * WRITING: the read reports what is there, and does not get to enforce it by making the
+ * other arrangement invisible.
+ *
+ * The library's own compartments live as reserved SUBJECTS inside the very documents a
+ * consumer reads (the Header branch carrying a document's inbox address is the first).
+ * They are machinery, not the entity's properties, and are dropped here - once, for
+ * every compartment present and future.
+ */
+// @provenance readDocumentSubjects kind=invention level=none ref=none - the anchored query it issues is `docs.sparqlQuery`, aligned and annotated THERE; what is added here has no upstream counterpart at any level: the cold-start open a shared wallet forces, and the grouping of a SELECT's rows into per-subject property bags. Internal, and named as ours so a later reader knows it is ours to change
+export async function readDocumentSubjects(
+  doc: Nuri,
+  label = "readDocument",
+): Promise<DocumentSubject[]> {
+  // The cold-start open, and the public store's chance to hand over its key, BEFORE the
+  // anchored read - see the module header for why this cannot move to the caller.
+  await ensureRepoOpen(doc);
+  const { sessionId } = await session();
+  // Anchored to `doc` -> default graph = this repo. No `GRAPH ?g` wrapper, so the
+  // anchor's one-repo restriction applies.
+  const rows = bindings(
+    await sparqlQuery(sessionId, "SELECT ?s ?p ?o WHERE { ?s ?p ?o }", undefined, doc, label),
+  );
+
+  const bySubject = new Map<string, DocumentSubject>();
+  for (const row of rows) {
+    const s = row.s?.value;
+    if (isMachinerySubject(s)) continue;
+    const p = row.p?.value;
+    const o = row.o?.value;
+    if (s === undefined || !p || o === undefined) continue;
+    let entry = bySubject.get(s);
+    if (!entry) {
+      entry = { subject: s, props: {} };
+      bySubject.set(s, entry);
+    }
+    (entry.props[p] ??= []).push(o);
+  }
+  return [...bySubject.values()];
+}

packages/polyfill/src/surface/read-model.ts

@@ -1,246 +0,0 @@
-/**
- * read-model — the listing primitive of the polyfill: read a bounded, by-need set
- * of documents, each with its own anchored `sparql_query`, and return the triples
- * grouped per subject. This is the mechanism documented in docs/read-model.md.
- *
- * ── Why per-doc anchored, rather than an anchorless union-scan ─────────────
- * An anchored `sparql_query(sid, "SELECT ?s ?p ?o WHERE { ?s ?p ?o }", base, doc)`
- * is restricted to the anchor repo's graph: `resolve_target_for_sparql(Repo)` →
- * `Some(repo_graph_name)`, which becomes the query's default graph. A body with no
- * `GRAPH` wrapper reads only that default graph → only that doc's triples, O(1) per
- * doc, independent of how many other graphs the local store holds.
- *
- * The footgun this avoids: an anchorless query (`anchor` undefined → `UserSite` →
- * `set_default_graph_as_union`) spans EVERY named graph currently in the session
- * store. On a shared / bloated wallet that accumulates across runs, that is
- * O(wallet size) → the observed ~90s timeouts. So the read path never union-scans
- * all graphs — it reads exactly the bounded by-need set, one anchored query per doc.
- *
- * NB (verified, docs/read-model.md § probe step 4): an explicit `GRAPH ?g { … }`
- * body iterates the named graphs regardless of the default graph, so an anchor does
- * not bound such a body. The per-doc read therefore uses a default-graph body (no
- * `GRAPH` wrapper) so the anchor's one-repo restriction actually applies.
- *
- * ── Why not the reactive ORM fan-out ──────────────────────────────────────
- * `useShape({ graphs: […manyDocs] })` drives `orm_start_graph` over a fan-out of
- * per-entity graphs; a freshly-created / not-yet-synced doc in that fan-out makes
- * `RepoNotFound` abort the whole subscription → the readyPromise never resolves →
- * the ~75s hang (docs/nextgraph-current-state.md § The ORM fan-out hang). Listing
- * is instead a set of one-shot anchored `sparql_query`s. There is no reactive
- * union query, so reactivity is assembled by re-querying on a change signal.
- *
- * ── Generic by construction ───────────────────────────────────────────────
- * No application domain here: the consumer passes the doc NURIs to read (from
- * the discovery index for public events, or its own scope docs for my-entities)
- * and interprets the returned per-subject property bags. All NextGraph I/O routes
- * through the T01.a `docs` primitives (the real injected `ng`), so this module
- * imports no `@ng-org` package.
- *
- * At the real multi-store migration the per-doc anchored read is unchanged (native
- * SPARQL, anchored to one repo); only bringing a repo into the session (open by cap)
- * changes — the anchored query already resolves a same-session repo directly.
- */
-
-import { docCreate, sparqlUpdate, sparqlQuery } from "./docs";
-import { getCaps, getStoreRegistryDeps } from "../shared-wallet/bootstrap";
-import { mustNotAttempt } from "../emulated-verifier/reach";
-import { ensureReposOpen } from "../emulated-verifier/open-repo";
-import { assertNuri } from "./sparql";
-import { toNuri } from "../model/nuri";
-import { isMachinerySubject } from "../emulated-verifier/machinery";
-import type { Nuri, NuriLike } from "../model/types";
-
-// Keep the primitives referenced so tree-shaking never drops the import used by
-// the (side-effecting) open step below; `docCreate`/`sparqlUpdate` are not used
-// here but the module intentionally depends only on the docs primitive surface.
-void docCreate;
-void sparqlUpdate;
-
-/** One subject read from a doc, with its properties (predicate → values). */
-// @provenance UnionSubject kind=invention level=none ref=none — no upstream type groups triples per (document, subject); a polyfill property bag, to be mapped into app types at the boundary
-export interface UnionSubject {
-  /**
-   * The subject IRI (`?s`), exactly as the document carries it.
-   *
-   * Typed `string`, not `Nuri`: a subject is an ordinary RDF subject and may be ANY
-   * IRI. An application that writes its entity under the document's own NURI gets a
-   * NURI back here, but that is its convention, not this type's promise — a document
-   * may hold several subjects under IRIs of the consumer's choosing, and each comes
-   * back as written.
-   *
-   * The need that once made this `Nuri` is real and is met by {@link graph}: a
-   * consumer must be able to pass back what it just read without a cast —
-   * `shareNote(note.doc)`, `leaveMessage(note.doc)` — and a cast at that boundary
-   * would re-open exactly the confusion the template literal types exist to close.
-   * `graph` is the document reference, so that is the field to carry around.
-   */
-  subject: string;
-  /**
-   * The document this subject was read from — the reference the caller passed to
-   * {@link readUnion}, unchanged. This is the anchor, it identifies the document
-   * stably, and it is what goes back into any call of this surface.
-   */
-  graph: Nuri;
-  /** predicate IRI → the list of object values (literals or IRIs) for it. */
-  props: Record<string, string[]>;
-}
-
-/** Tolerant extraction of SPARQL SELECT bindings across possible shapes. */
-function bindings(
-  result: unknown,
-): Array<Record<string, { value: string } | undefined>> {
-  if (!result) return [];
-  if (Array.isArray(result))
-    return result as Array<Record<string, { value: string }>>;
-  const anyRes = result as {
-    results?: { bindings?: Array<Record<string, { value: string }>> };
-  };
-  return anyRes.results?.bindings ?? [];
-}
-
-async function sessionId(): Promise<string | number> {
-  return (await getStoreRegistryDeps().getSession()).sessionId;
-}
-
-/**
- * Read one doc with an anchored default-graph query, tolerant per-doc.
- *
- * The anchor (`doc` NURI) restricts the query to that repo's graph as the default
- * graph (`resolve_target_for_sparql(Repo)` → `Some(repo_graph_name)`); a body with
- * no `GRAPH` wrapper reads exactly that default graph → only this doc's triples.
- * This is O(1) in the doc's own size and independent of the rest of the (possibly
- * bloated / shared) session store — it never iterates other graphs.
- *
- * COLD-START (fresh session, same persistent wallet): the repo is NOT in
- * `self.repos` until something opens it, and an anchored query against an unopened
- * repo silently returns 0 rows (never `RepoNotFound`). {@link readUnion} therefore
- * opens the batch's repos ({@link ensureReposOpen}) BEFORE this read runs, so the
- * anchored query resolves a same-session repo directly. A genuinely-absent repo
- * still yields `[]` (in isolation, never aborting the others). Returns the doc's
- * rows, or `[]` on failure.
- *
- * At the real multi-store migration this becomes a real sync: opening a per-user
- * store repo by cap is a native broker fetch (`verifier.rs:1423` `OpenRepo` TODO).
- */
-async function readDoc(
-  sid: string | number,
-  doc: Nuri,
-): Promise<Array<Record<string, { value: string } | undefined>>> {
-  try {
-    const nuri = assertNuri(doc);
-    // Anchored to `nuri` → default graph = this repo. No `GRAPH ?g` wrapper, so
-    // the anchor's one-repo restriction applies (an explicit `GRAPH ?g` body would
-    // iterate all named graphs regardless of the anchor — see docs § probe step 4).
-    const res = await sparqlQuery(
-      sid,
-      "SELECT ?s ?p ?o WHERE { ?s ?p ?o }",
-      undefined,
-      nuri,
-      "readDoc",
-    );
-    return bindings(res);
-  } catch (error) {
-    console.error("[read-model] read failed for", doc, error);
-    return [];
-  }
-}
-
-/**
- * Read a BOUNDED, by-need set of docs — each with its OWN anchored query — and
- * return the triples grouped per subject. `docs` are the NURIs to read (the
- * consumer resolves them by need — index for public, own scope docs for mine).
- * Docs that fail are skipped (see {@link readDoc}); a failing doc never aborts the
- * batch.
- *
- * A document holding SEVERAL subjects yields several entries — one per distinct
- * subject, carrying that subject as written, all sharing the document as their
- * `graph`. Properties of different subjects are never merged. Placing one business
- * entity per document stays the recommended practice (a key is per repo, so
- * isolation needs a repo per entity), but it is a recommendation about writing: the
- * read reports what is there.
- *
- * Never an anchorless union-scan over all graphs (which is O(wallet size) and wrong
- * on a shared / bloated wallet — the footgun this path exists to avoid). Each doc is
- * read with an anchored default-graph query, O(1) per doc, independent of wallet
- * size — a non-empty wallet no longer matters. Reads run in parallel via `Promise.all`.
- */
-// @provenance readUnion kind=aligned level=2 ref=sdk/js/lib-wasm/src/lib.rs:sparql_query — one anchored query per document — upstream's own anchoring (`resolve_target_for_sparql`), composed client-side
-export async function readUnion(docsLike: NuriLike[]): Promise<UnionSubject[]> {
-  const sid = await sessionId();
-  // Drop the empties BEFORE validating, not after: this call has always tolerated a
-  // list with holes in it — a scope index can carry a blank entry, and a caller
-  // building a list from optional values should not have to compact it. Validating
-  // first turned that tolerance into a throw, which took down a whole reconnect run.
-  // Empty is absence, and absence is not a malformed reference.
-  const unique = [...new Set(docsLike.filter(Boolean))].map((d) => toNuri(d, "readUnion"));
-  if (unique.length === 0) return [];
-
-  // COLD-START heal (polyfill-era): on a fresh session over a persistent wallet the
-  // target repos are not yet in `self.repos`, so an anchored read would return 0
-  // rows. Open/subscribe each repo ONCE (idempotent, per session) and await its
-  // initial-state push before the anchored reads. No-op once opened / when the
-  // injected `ng` has no `doc_subscribe` (unit fake). See open-repo.ts.
-  //
-  // Called on the WHOLE set, before the boundary is consulted, because opening is also
-  // where a document in a PUBLIC store hands over its cap (see public-store.ts): a
-  // document filtered out first would never get the chance to answer. `ensureRepoOpen`
-  // still refuses to open what this user may not touch — it asks, it does not enter.
-  await ensureReposOpen(unique);
-
-  // RULE 2 — do not even attempt. Drop the documents whose cap this user does not
-  // hold before reading anything: upstream you cannot address a repo you have no cap
-  // for, so asking about one is not "a read that will be refused", it is a read that
-  // has no meaning. (The passage points enforce rule 1 regardless — see reach.ts — so
-  // a lapse here is caught, not exploited.)
-  const reachable = unique.filter((d) => !mustNotAttempt(d));
-
-  // One anchored query per doc, in parallel, tolerant (a bad doc yields []).
-  const perDoc = await Promise.all(
-    reachable.map(async (d) => ({ doc: assertNuri(d), rows: await readDoc(sid, d) })),
-  );
-
-  // Possession gate, kept as defence in depth behind rule 2 above: `reachable`
-  // already excluded these, so this loop should never drop anything. The read is
-  // anchored per document, so the unit of possession is the document: the cap key is
-  // the doc NURI, whatever subjects that document turns out to carry.
-  const caps = getCaps();
-
-  // Keyed by (document, subject) — an entry is one subject INSIDE one graph, which is
-  // the identity upstream gives an object too: the ORM carries `@id` and `@graph` as
-  // two distinct read-only properties, and fabricates an `@id` when the writer leaves
-  // it empty (`sdk/js/orm/src/connector/GraphOrmSubscription.ts`). Several objects per
-  // graph is therefore the PROVIDED case, and `@id` is what tells them apart within a
-  // `@graph`. Two documents carrying the same subject IRI stay two entries: they are
-  // two objects, distinguished by their graph.
-  //
-  // Placing one business entity per document remains the recommended practice — a key
-  // is per repo, so isolating an entity requires a repo of its own. That is a
-  // recommendation about WRITING, and the read does not get to enforce it by making
-  // the other arrangement invisible.
-  const bySubject = new Map<string, UnionSubject>();
-  for (const { doc, rows } of perDoc) {
-    if (caps.isEnforcing() && caps.capFor(doc) === undefined) continue;
-    // Anchored to `doc`, so every row belongs to `doc` — hence `graph` is the caller's
-    // reference to it. The subject comes back exactly as the document carries it.
-    for (const row of rows) {
-      // The polyfill's own compartments live as reserved SUBJECTS inside the very
-      // documents the consumer reads (the Header branch carrying a document's inbox
-      // address is the first). They are machinery, not this entity's properties —
-      // drop them here, once, for every compartment present and future.
-      const s = row.s?.value;
-      if (isMachinerySubject(s)) continue;
-      const p = row.p?.value;
-      const o = row.o?.value;
-      if (s === undefined || !p || o === undefined) continue;
-      // NUL cannot appear in an IRI, so the pair never collides with either half.
-      const key = `${doc}\u0000${s}`;
-      let entry = bySubject.get(key);
-      if (!entry) {
-        entry = { subject: s, graph: doc, props: {} };
-        bySubject.set(key, entry);
-      }
-      (entry.props[p] ??= []).push(o);
-    }
-  }
-  return [...bySubject.values()];
-}

packages/polyfill/src/surface/subscribe.ts

@@ -46,10 +46,11 @@
  * nothing logs, the stale unsubscribe still "works".
  *
  * That made every internal subscriber a hazard to every other one. `ensureRepoOpen`
- * holds a bootstrap subscription per document for the whole session, `watchShape`
- * subscribes to the documents of a scope, `inbox.watch` to an inbox — so opening a
- * repo killed the watch on it, and the app-visible result was a view that never
- * re-read and an inbox that never notified. Both were reported as "the layer does not
+ * holds a bootstrap subscription per document for the whole session, the reactive shape
+ * read of the day subscribed to the documents of a scope (a pipeline retired in
+ * `1.0.0-dev.6`), `inbox.watch` to an inbox - so opening a repo killed the watch on it,
+ * and the app-visible result was a view that never re-read and an inbox that never
+ * notified. Both were reported as "the layer does not
  * notify of its own actions", which is NOT what happens: a same-session write DOES
  * push (verified the same day — `Patch@69ms` on the writer's own `sparqlUpdate`,
  * `e2e/reactivity-doc-subscribe.ts`). The push arrived; there was no longer anybody
@@ -62,6 +63,14 @@
  * fire, and `inbox.watch`'s "fires once immediately" would silently stop being true.
  * The real subscription is torn down when the LAST listener leaves.
  *
+ * ── This module OWNS "is this document open in this session" ───────────────
+ * Because the subscription is the only thing that makes a document open, the fan-out is the
+ * only honest answer to whether one is - and {@link docChannel} is how the rest of the
+ * package asks. Nobody keeps a copy: `emulated-verifier/open-repo.ts` kept two (a set of
+ * live bootstrap subscriptions, and a per-document barrier state), and both outlived the
+ * channel they described the moment `resetDocSubscriptions` dropped it, which is how a
+ * document with no subscription at all came to report itself synced.
+ *
  * ── What SHARING one subscription must not cost a caller ───────────────────
  * Three things a per-caller `doc_subscribe` gave for free, and that the fan-out has to give
  * back deliberately — each of them was lost when it was introduced on 2026-08-17:
@@ -85,7 +94,7 @@ import type { Nuri, NuriLike } from "../model/types";
  * A push from the platform to a document subscriber. Loosely typed: the raw
  * serialized `AppResponse` (`{ V0: { State | Patch | TabInfo | ... } }`). The
  * consumer typically ignores the payload and uses the push purely as a
- * change SIGNAL (re-query on change — the read-model pattern), so this stays
+ * change SIGNAL (re-query on change — the read model in `docs/read-model.md`), so this stays
  * permissive rather than modelling every AppResponse variant.
  */
 // @provenance DocChange kind=aligned level=1 ref=engine/net/src/app_protocol.rs:AppResponseV0 — the raw serialized response, left `unknown` rather than modelling every variant
@@ -200,6 +209,18 @@ interface DocFanOut {
    * Its own `doc_subscribe` would have pushed one; the fan-out owes it the same.
    */
   lastState: { resp: DocChange; type: DocChangeType } | null;
+  /**
+   * WHICH fan-out this is for this NURI - a new number for every entry ever created, so a
+   * caller holding a listener can tell whether the entry it joined is still the one in the map.
+   *
+   * It exists because {@link resetDocSubscriptions} drops every listener WITHOUT telling the
+   * callers who took them out, and a caller cannot see that from its own unsubscribe function:
+   * `emulated-verifier/open-repo.ts` held a listener handle that went on reading as "I am still
+   * listening" after the entry it belonged to had been deleted, and skipped an open it owed. The
+   * entry OBJECT already answers this inside the module ({@link isCurrentAttempt}); a number is
+   * what can leave it.
+   */
+  readonly incarnation: number;
 }
 
 /**
@@ -213,6 +234,82 @@ interface DocFanOut {
  */
 const fanOuts = new Map<Nuri, DocFanOut>();
 
+/** How many fan-outs have ever been created - see {@link DocFanOut.incarnation}. */
+let fanOutsEverCreated = 0;
+
+/**
+ * What the one real subscription for a document IS, right now.
+ *
+ *   - `"none"`     nothing stands: no listener holds this document, or the establish that
+ *                  was standing FAILED and the next joiner will make its own;
+ *   - `"opening"`  an establish is in flight - the call has been made and has not answered,
+ *                  so there is no channel yet and there may never be one;
+ *   - `"open"`     the `doc_subscribe` call ANSWERED and this fan-out is still the one
+ *                  waiting on it: pushes arrive here.
+ */
+// @provenance DocChannelState kind=invention level=none ref=none — names the states of this module's own fan-out; upstream a caller holds its own subscription and has nothing to ask
+export type DocChannelState = "none" | "opening" | "open";
+
+/**
+ * THE answer to "is this document open in this session", and the only one.
+ *
+ * Read it, never copy it. `emulated-verifier/open-repo.ts` used to keep records of its own
+ * - a set of live bootstrap subscriptions and a per-document barrier state - and both
+ * survived a teardown of the fan-out they described: `resetDocSubscriptions` drops every
+ * listener without a word to anybody, so a document whose channel had gone was still
+ * recorded as open and as SYNCED, nothing re-subscribed it, and a zero-row read over it
+ * answered a success. Three records of one fact, and they disagreed. There is one now, it
+ * is this one, and it cannot outlive the channel it describes because it IS the channel.
+ */
+export interface DocChannel {
+  /** Whether a channel stands, and how far it got. */
+  readonly state: DocChannelState;
+  /**
+   * Has a `State` push arrived on the channel standing NOW?
+   *
+   * The first `State` is the sync barrier (CONTRACT 3): past it, presence is guaranteed and
+   * absence definitive, so a zero-row read MEANS zero. It is {@link DocFanOut.lastState}
+   * that says so - the one the fan-out replays to a late joiner - which is exactly the right
+   * record, because it is forgotten on the two events that invalidate a barrier: the
+   * channel being released, and the session changing under it ({@link resubscribeDocs}).
+   */
+  readonly barrierCrossed: boolean;
+  /**
+   * WHICH fan-out is standing for this document, or `0` when none is.
+   *
+   * A caller that took a listener out compares this with what it saw then: a different number
+   * means its listener was dropped from under it and the entry replaced, which
+   * {@link resetDocSubscriptions} does without a word. See {@link DocFanOut.incarnation}.
+   */
+  readonly incarnation: number;
+}
+
+/**
+ * The state of `nuri`'s one real subscription - see {@link DocChannel}.
+ *
+ * Internal. Exported for `emulated-verifier/open-repo.ts`, which asks it instead of
+ * remembering the answer, and for nobody else; neither entry point re-exports it.
+ */
+// @provenance docChannel kind=invention level=none ref=none — a question about this module's own fan-out, which exists because a branch upstream holds a single subscriber; there is nothing to align it with
+export function docChannel(nuri: Nuri): DocChannel {
+  const entry = fanOuts.get(nuri);
+  if (!entry) return { state: "none", barrierCrossed: false, incarnation: 0 };
+  // `establishing` says an attempt STANDS (it is left true once one has succeeded, see
+  // {@link DocFanOut.establishing}); `realUnsub` says that attempt's call has answered. The
+  // two together are the only thing that separates "asked" from "open" - and recording the
+  // first as if it were the second is the defect this accessor exists to make impossible.
+  const state: DocChannelState = !entry.establishing ? "none" : entry.realUnsub !== null ? "open" : "opening";
+  // `lastState` alone, and deliberately NOT `&& state !== "none"`. Every path that stops an
+  // attempt standing forgets the barrier with it - {@link releaseFanOut}, {@link resubscribeDocs}
+  // and, since this was found the hard way, {@link reportSetupFailure} - so the two can no longer
+  // disagree, and a guard here would be unreachable. It would also be a MASK: the first repair of
+  // that defect put exactly this condition in the reader instead of forgetting the barrier at the
+  // source, and it hid the fault while the fan-out went on replaying a dead `State` to the next
+  // joiner. A fact that is wrong at the source has to be fixed at the source; a reader that
+  // papers over it only moves the lie.
+  return { state, barrierCrossed: entry.lastState !== null, incarnation: entry.incarnation };
+}
+
 /** Hand one push to one listener, isolating a throwing handler from the others. */
 function deliver(nuri: Nuri, listener: DocListener, resp: DocChange, type: DocChangeType): void {
   try {
@@ -294,6 +391,15 @@ function reportSetupFailure(nuri: Nuri, entry: DocFanOut, error: unknown, attemp
   console.error("[subscribe] doc_subscribe failed for", nuri, error);
   if (!isCurrentAttempt(nuri, entry, attempt)) return;
   entry.establishing = false;
+  // A BARRIER BELONGS TO THE ATTEMPT THAT PRODUCED IT, and this one failed. The push may well
+  // have arrived - the callback is driven locally while the call's own answer travels the RPC -
+  // but the call did not take, so there is no subscription behind that `State` and nothing will
+  // follow it. Left here, the fan-out replayed it to the next joiner: a bootstrap open crossed
+  // its barrier in 2ms on a `State` from a call that had FAILED, logged `BARRIER ... synced`,
+  // and `getSyncState` answered `"synced"` - which is authority, so a zero-row read over the
+  // document became a definitive absence and a deposit was destroyed. {@link releaseFanOut}
+  // and {@link resubscribeDocs} both forget it for the same reason; this path did not.
+  entry.lastState = null;
   for (const listener of [...entry.listeners]) {
     const tell = listener.onSetupFailed;
     if (tell === null || !entry.listeners.has(listener)) continue;
@@ -407,8 +513,20 @@ async function establish(
       // this fan-out's listeners nor its barrier are this call's to touch any more.
       if (!isCurrentAttempt(nuri, entry, attempt)) return;
       const type = docChangeType(resp);
-      // Remember the barrier for whoever joins next; a later `State` replaces it.
-      if (type === "State") entry.lastState = { resp, type };
+      // Remember the barrier for whoever joins next; a later `State` replaces it - but ONLY
+      // while this attempt still stands. `isCurrentAttempt` above says this entry and this
+      // call are still the ones, and says nothing about whether the call SUCCEEDED: a broker
+      // dispatches before it answers, so a `State` can land after the call has already been
+      // reported as failed, and this module's own doctrine is that a push outliving its
+      // teardown is reachable (see the header, and the guard on this very callback). Recording
+      // it then re-created the dead barrier {@link reportSetupFailure} had just forgotten, with
+      // no channel behind it - and `getSyncState` answers `"synced"` to that, which is AUTHORITY.
+      //
+      // With this, `lastState !== null` IMPLIES an attempt stands, at every write as well as at
+      // every clear, so the two cannot disagree and no reader has to re-impose it. The push is
+      // still fanned out below: a listener may want the change signal, and only the BARRIER is
+      // a claim about the document.
+      if (type === "State" && entry.establishing) entry.lastState = { resp, type };
       fanOut(nuri, entry, resp, type);
     })) as (() => void) | undefined;
     if (!isCurrentAttempt(nuri, entry, attempt)) {
@@ -419,7 +537,14 @@ async function establish(
       if (typeof unsub === "function") unsub();
       return;
     }
-    entry.realUnsub = typeof unsub === "function" ? unsub : null;
+    // A function is what upstream resolves to, and it is the cancel. When the injected SDK
+    // hands back something else there is nothing to cancel WITH - but the call has still
+    // ANSWERED, and that is what {@link docChannel} reads off this field. Left `null`, the
+    // channel would read `"opening"` for the rest of the session and every `ensureRepoOpen`
+    // would take out a fresh bootstrap listener over a document that is perfectly open. A
+    // no-op costs exactly what `null` cost before: {@link releaseFanOut} returned early on
+    // `null` rather than cancelling, so nothing is lost by calling nothing instead.
+    entry.realUnsub = typeof unsub === "function" ? unsub : (): void => {};
   } catch (error) {
     reportSetupFailure(nuri, entry, error, attempt);
   }
@@ -453,7 +578,7 @@ export function resetDocSubscriptions(): void {
  * synced. Zero rows, "synced", no error: the silent staleness this module exists to remove.
  *
  * So the barrier is forgotten and the channel re-opened, rather than the listeners dropped:
- * a `watchShape` that was following a document keeps following it across the change.
+ * an `inbox.watch` that was following a document keeps following it across the change.
  */
 // @provenance resubscribeDocs kind=invention level=none ref=none — per-session bookkeeping, like `resetOpenedRepos`; upstream a session's subscriptions die with it and nothing carries them over
 export function resubscribeDocs(): void {
@@ -560,6 +685,7 @@ export function subscribeDocUnguarded(
       establishing: false,
       attempt: 0,
       lastState: null,
+      incarnation: ++fanOutsEverCreated,
     };
     fanOuts.set(nuri, entry);
   }
@@ -571,11 +697,24 @@ export function subscribeDocUnguarded(
   // Joining a document somebody else already opened: hand this listener the `State` its
   // own `doc_subscribe` would have pushed it. Asynchronously, like the real push, so a
   // caller that sets itself up after this call still sees it.
+  //
+  // RE-READ inside the microtask, never captured out here, because the barrier can be forgotten
+  // in between: the establish can reject in that gap and {@link reportSetupFailure} disowns its
+  // `State` with it. One microtask hop is the whole window - measured, not reasoned - and this
+  // is the last path that could hand out a barrier after it had been forgotten. `isCurrentAttempt`
+  // does not cover it: that failure does not bump `attempt`, so the entry and the attempt are
+  // both still the current ones.
+  //
+  // Diagnostic rather than an authority leak: `getSyncState` reads the record and not the push,
+  // so it still answers `"timed-out"`. What the stale delivery broke is the bootstrap wait in
+  // `emulated-verifier/open-repo.ts`, which crossed its barrier on it and logged
+  // `BARRIER <nuri> synced` for a barrier that no longer existed - and that trace line is the one
+  // this codebase uses to tell a genuine absence from a not-yet-synced read.
   if (joined.lastState) {
-    const { resp, type } = joined.lastState;
     queueMicrotask(() => {
-      if (fanOuts.get(nuri) === joined && joined.listeners.has(listener)) {
-        deliver(nuri, listener, resp, type);
+      const standing = joined.lastState;
+      if (standing && fanOuts.get(nuri) === joined && joined.listeners.has(listener)) {
+        deliver(nuri, listener, standing.resp, standing.type);
       }
     });
   }

packages/polyfill/src/surface/use-shape-query.ts

@@ -0,0 +1,732 @@
+/**
+ * use-shape-query - a REACTIVE, TanStack-`useQuery`-shaped read over one SHEX shape in
+ * one SDK `Scope`. This is the surface the consuming app binds with
+ * `useSyncExternalStore` - the polyfill deliberately exposes an OBSERVABLE, never a
+ * React hook (the lib has NO React dependency, same constraint as `subscribe.ts`).
+ *
+ * -- The name, and the one difference from the SDK that is deliberate -------
+ * It was `watchShape` until `1.0.0-dev.5`. That name has ZERO occurrences upstream, and
+ * it spent `watch`, a verb the ORM has already spent on signal observation
+ * (`watch as watchDeepSignal`). The target's own name is `useShapeQuery`, and what it
+ * returns is the snapshot below rather than the two states today's `useShape` hands back -
+ * announced by NextGraph's developers and on record in
+ * `.project/rules/nextgraph/surface-mirrors-the-sdk.md`, which is what the annotation on
+ * the function cites. Deviating TOWARD an announced target is alignment; the rest of the
+ * surface is what will catch up:
+ *   `ShapeQuery<T> = { data: T[]; isPending; isSuccess; isError; error }`.
+ * `data` is ALWAYS an array (never `undefined`), so a synced-but-empty scope reads
+ * `{ data: [], isPending: false, isSuccess: true }` - the key distinction - while a
+ * scope still syncing reads `{ data: [], isPending: true, isSuccess: false }`.
+ *
+ * -- What it reads THROUGH, since `1.0.0-dev.6` ----------------------------
+ * The SDK's own shape query - `RdfOrmSubscription.getOrCreate(shapeType, scope)` - and
+ * nothing of this library's own. Four steps went with the change, and they were one
+ * mechanism: a logical scope resolved to a document set (`listMyEntityDocs`), those
+ * documents opened through `ensureReposOpen` for a sync barrier, one anchored read over
+ * each of them, and a filter of the result by the shape's `@type` IRI. All four existed
+ * because the parameter had to be TRANSLATED; once the parameter is upstream's own `Scope`, the
+ * question goes straight to the thing that answers it. `graphs`, `subjects` and the
+ * whole-dataset marker `did:ng:i` are now read by the engine, literally, and this module
+ * does not interpret them at all - so the three readings are upstream's, not ours.
+ *
+ * It does NOT delegate to the SDK's `useShape`: that is React's hook, callable only from a
+ * render, and what it hands back carries two states where this surface publishes three. Its
+ * `isLoading` says whether the initial payload has arrived and has no value for "it never
+ * will" - a refused read and a slow one are the same answer there - and there is no error
+ * state to carry one. What is taken from the SDK is the QUERY; the observable, the snapshot
+ * and the state tracking stay here.
+ *
+ * -- What stays ours, and why ----------------------------------------------
+ *   1. **The three states.** `readyPromise` is the ORM's own answer to "has the initial
+ *      payload arrived" - it resolves on that path and on no other - so it is what tells
+ *      `isPending` from a genuinely empty `isSuccess`. The React adapter one floor up
+ *      drops that distinction (an empty set "if still loading"); this does not.
+ *   2. **The capability filter.** `emulated-verifier/read-filter.ts` keeps only items
+ *      whose document (`@graph`) the current holder holds a cap for - the emulation of
+ *      what the broker will bound at delivery, applied per document on what comes back,
+ *      exactly where `surface/use-shape.ts` applies it. Before the first cap is issued
+ *      the registry is not enforcing and everything passes through.
+ *   3. **The keyring signal.** A cap that arrives asynchronously (an inbox delivery
+ *      absorbed by `inbox.watch`) makes items readable that were not, so
+ *      `CapRegistry.onChange` re-publishes. Without it a view stays stale until an
+ *      unrelated change happens to fire.
+ *
+ * -- Reactivity WITHOUT polling (no `setInterval`) --------------------------
+ * Two push sources, both of them signals: the subscription's own
+ * `addChangeListener` (root objects added, updated or removed - the engine's patches
+ * reaching the signal object), and the keyring above. No document subscription of this
+ * library's is opened here any more: the ORM holds the one that matters.
+ *
+ * -- `isError` is wired to what CAN fail, and says so ----------------------
+ * One thing on this path throws, and it throws at the call: opening the shape query -
+ * a shape the ORM cannot canonicalise, or a `configure()` that was never given the
+ * query to open. That is what `isError` carries.
+ *
+ * What it does NOT carry, recorded rather than assumed: a start the ENGINE refuses.
+ * `RdfOrmSubscription` awaits its session and calls `orm_start_graph` inside a
+ * `try { ... } catch (e) { console.error(e) }`, and its readiness promise is built with
+ * `resolve` alone - nothing rejects it, and `resolveReady` runs on one path only, the
+ * arrival of initial data. So upstream's *"I could not find out"* IS its *"still
+ * pending"*, and a refused read reads here as `isPending` for ever, never as
+ * `isSuccess` with `data: []`. The distinction this surface exists for therefore holds
+ * - an application is never told "there is nothing" for "nobody answered" - but the
+ * third state is narrower than it was while the pipeline was ours. `isError` stays
+ * because this package's job is to ENRICH the SDK in its announced direction, not to be
+ * bounded by what it exposes today; the day the ORM surfaces a failed start, this is
+ * where it lands.
+ *
+ * -- A named document is REACHED before the query opens, since `1.0.0-dev.9` --------
+ * `scope.graphs` does not only narrow a search: each entry NAMES a document, and naming
+ * one is the same act `docs.sparqlQuery`'s anchor is. So each named document is put
+ * through the same two steps that call makes - the (emulated) public store is asked for
+ * its cap, and the document is refused out loud if the cap is not held - plus the
+ * cold-start open every other read path in this library crosses (`ensureRepoOpen`).
+ *
+ * What it repairs is this surface's own version of the failure it exists against. A named
+ * document whose cap the holder does not hold used to reach the engine, come back, and be
+ * emptied by the capability filter below, publishing `isSuccess` with `data: []` - "this
+ * document holds nothing of that shape" for "you cannot read this document", while the
+ * anchored read of the SAME document refuses. A named document this session has never
+ * synced published the same snapshot for a document that is not empty. Both are now
+ * `isError`, which is what `isError` has always meant here: the current answer is UNKNOWN.
+ *
+ * **What is deliberately NOT guarded, and each is an answer rather than a failure:**
+ *   - `graphs: "did:ng:i"` or `""` - the whole local dataset. The application named no
+ *     document, so there is no cap question to ask; the capability filter is the right
+ *     and only answer, exactly as the broker delivering only what your keys open is.
+ *   - `graphs: []` - no objects, by the SDK's own definition. `isSuccess` with `data: []`.
+ *   - a named document held and synced that holds nothing of the shape - `isSuccess` with
+ *     `data: []`, which is the distinction this whole surface exists to publish.
+ *   - the INERT case: before the first cap is issued nothing is enforcing, the public
+ *     store is not asked at all, and `assertMayReach` passes for everything.
+ *
+ * A scope naming SEVERAL documents fails as a whole when one of them cannot be reached,
+ * rather than answering the others. A short list is the same lie as an empty one, and it
+ * is the tolerance `readUnion` was removed for in `1.0.0-dev.8`.
+ *
+ * The barrier is why the open below is asynchronous: it prolongs `isPending`, and nothing
+ * else about the states moves.
+ *
+ * -- A refusal that could not be re-tried would be worse than the defect ------------
+ * The first version of this barrier was TERMINAL, and an adversarial pass found it. The
+ * keyring signal below is written as `if (query !== null) publish(...)` because until the
+ * barrier existed there was only ever one reason to have no query - nothing had been
+ * tried yet - and a cap arriving could only ever change what an OPEN query was allowed to
+ * show. The barrier added a second reason: it aborts BEFORE the query is created, so the
+ * one channel that makes a late cap converge went straight past the state that needed it
+ * most. A page subscribing while its keyring was still being restored, or a document
+ * shared with someone while they watched, published `isError` and stayed there for the
+ * life of the view. Trading a silent empty answer for a stuck error is not a stricter
+ * surface, it is a worse one - and it broke a guarantee this package publishes, which
+ * `emulated-verifier/read-filter.ts` and `surface/inbox.ts` both restate.
+ *
+ * So the signal re-ATTEMPTS a refused scope. Two things make that sound, and both were
+ * arrived at by getting them wrong first:
+ *
+ *   - **the decision is a LEVEL, not a memory.** Which documents the holder may reach is
+ *     re-read on every publication ({@link publish}), never carried over from the barrier.
+ *     So a cap arriving turns a refusal into the document through the channel that
+ *     already existed, and a query opened while somebody else was connected cannot come
+ *     back to this subscriber as a success it is not entitled to. Nothing is remembered,
+ *     so there is no event to miss.
+ *   - **an attempt that RACED a change notices, rather than waiting.** A keyring change
+ *     landing while the barrier is crossing fires its listener when there is no query to
+ *     re-publish and no refusal on record - and that same change is often what makes the
+ *     walk refuse. The edge is simply gone. So the attempt samples `CapRegistry.version()`
+ *     before it starts and compares after it fails; a mismatch means it decided on stale
+ *     ground and it makes another attempt itself.
+ *
+ * This is the third shape this recovery has had, and the first two failed the same way -
+ * each recorded that it had refused and then waited for a later event. Round 2 gated the
+ * record on a condition that could not become true; round 3 set the record after the
+ * window in which the deciding event arrives. An edge that is missed is not recoverable
+ * by construction, which is why the answer here is to stop depending on edges.
+ *
+ * -- Why there is no cleverer gate than "attempt again" ----------------------------
+ * The obvious one is to re-open only once the refusal has been lifted - "does the holder
+ * hold every named document's cap now". It was written that way first, and it is CIRCULAR
+ * for a whole class: for a document in a public store the only channel that can ever file
+ * that cap is `fetchReadCap`, the very call the gate was there to withhold. A scope
+ * refused because the store could not be ASKED then waited on an answer that only the
+ * action it gated could produce, and no number of cap arrivals ever released it. A second
+ * adversarial pass proved it with the broker healing and ten caps landing afterwards.
+ *
+ * Attempting is the cheaper question anyway, because the two ways to be refused are
+ * repaired by opposite things and the memo already tells them apart:
+ *
+ *   - **the store could not be asked.** A failure is deliberately NOT memoised
+ *     (`public-store.ts`), so a re-attempt genuinely re-asks the network - which is the
+ *     whole repair for this class, not a cost to avoid.
+ *   - **the store answered and there is no cap to be had.** An absence IS memoised, so a
+ *     re-attempt asks nobody: it re-runs the barrier against what is already known and
+ *     republishes the same refusal. It costs one snapshot, and it stops the day the cap
+ *     arrives from somewhere else, which is the only thing that can repair this class.
+ *
+ * It is self-limiting either way: the moment an attempt succeeds there is a query again,
+ * and this branch is never reached. What it is NOT is a timer - nothing here polls, and
+ * a scope refused in a session where the keyring never moves again stays `isError` until
+ * the caller's own `refetch()`, which is what `isError` has always meant on this surface.
+ *
+ * -- An observable cannot un-emit: `data` survives an error -----------------
+ * A one-shot call rejects and is done. An observable has already handed a list to a
+ * subscriber that rendered it, so its failure snapshot has to say something about
+ * that list - and collapsing it to `[]` would hand out, in `data`, exactly the empty
+ * answer this fix removes. So `data` KEEPS the last read that actually answered, and
+ * `isError` says the current answer is unknown. `isSuccess` is false throughout: the
+ * array is a memory, not a reply to the question just asked.
+ */
+
+import { getCaps, getConfig } from "../shared-wallet/bootstrap";
+import { filterReadable } from "../emulated-verifier/read-filter";
+import { ensureRepoOpen, getSyncState } from "../emulated-verifier/open-repo";
+import { assertMayReach } from "../emulated-verifier/reach";
+import { isNuri } from "../model/nuri";
+import type { Nuri, OrmSubscriptionHandle, OrmSubscriptionLike } from "../model/types";
+// The SDK's own types, imported as TYPES (erased at build, so no runtime `@ng-org`
+// import is added here). The provenance of what is PUBLISHED is recorded in `index.ts`.
+import type { Scope } from "@ng-org/orm";
+import type { BaseType, ShapeType } from "@ng-org/shex-orm";
+
+/**
+ * A minimal TanStack-`useQuery`-shaped read snapshot. `data` is ALWAYS an array
+ * (never `undefined`), and its items are the SHAPE's own objects - what the ORM
+ * returns, carrying `@id`, `@graph` and the shape's readable predicates.
+ */
+// @provenance ShapeQuery kind=announced-not-written level=3 ref=.project/rules/nextgraph/surface-mirrors-the-sdk.md:ShapeQuery announced-by=nextgraph-developers@2026-09-16 - the announced direction for `useShapeQuery` (see that symbol's own annotation) is exactly this shape, `{ data, isPending, isSuccess, isError, error }`; nothing in the tree carries `isError` yet - the React hook's result carries a load state (`isLoading`) beside its data, so pending-vs-ready has a counterpart, but a refused `orm_start_graph` is only `console.error`'d and `readyPromise` is built with `resolve` alone, so a failed read is an eternal pending at every level today
+export interface ShapeQuery<T extends BaseType = BaseType> {
+  /** The objects of the requested shape/scope. Empty array when none (never undefined).
+   *  When `isError`, this is the last read that ANSWERED - kept, not cleared, because an
+   *  observable cannot un-emit and `[]` here would be the false "you have nothing" the
+   *  error state exists to prevent. Read it as a memory then, not as a reply. */
+  data: T[];
+  /** True until the shape query's initial payload has arrived (`readyPromise`).
+   *  Mutually exclusive with `isSuccess`. */
+  isPending: boolean;
+  /** True once the initial payload has arrived. A ready-but-EMPTY scope is `isSuccess`
+   *  with `data: []` - the distinction this surface exists for. */
+  isSuccess: boolean;
+  /** True ONLY when opening the shape query threw: the shape could not be subscribed, or
+   *  `configure()` was never given the query to open it with. It means the current answer
+   *  is UNKNOWN - never that the scope is empty. Mutually exclusive with both `isPending`
+   *  and `isSuccess`. See the module header for the failure it does NOT cover. */
+  isError: boolean;
+  /** The caught error when `isError`, else `undefined`. */
+  error: unknown;
+}
+
+/** The observable a caller binds with `useSyncExternalStore` (phase B). */
+// @provenance ShapeObservable kind=invention level=none ref=none - no upstream observable exists; the ORM exposes a React hook and a subscription class, neither of which a caller subscribes to with `getSnapshot`/`subscribe`
+export interface ShapeObservable<T extends BaseType = BaseType> {
+  /** The current snapshot. STABLE across calls until it actually changes (so
+   *  `useSyncExternalStore` does not loop): the same reference is returned until a
+   *  state transition produces a new one. */
+  getSnapshot(): ShapeQuery<T>;
+  /** Register a change listener; returns an unsubscribe. The last listener's
+   *  unsubscribe closes the underlying shape query. */
+  subscribe(onChange: () => void): () => void;
+  /** Ask again, now: close the shape query in force and open a fresh one. Idempotent
+   *  w.r.t. subscribers, and it never polls - the ORM pools a subscription it has just
+   *  closed, so asking again over an answering broker costs nothing and answers at
+   *  once. The snapshot is NOT reset: whatever was rendered stays until the new
+   *  subscription answers or fails. */
+  refetch(): void;
+}
+
+/**
+ * The whole local dataset, as the SDK spells it. `normalizeScope` maps `""` onto this
+ * very string (`@ng-org/orm`'s `types.ts`), so both forms are the same marker and neither
+ * names a document.
+ */
+const WHOLE_DATASET = "did:ng:i";
+
+/**
+ * The DOCUMENTS a scope NAMES - the only entries a capability question can be asked
+ * about.
+ *
+ * Flattened the way the SDK flattens `graphs` (a bare string is one entry), then reduced
+ * to what identifies a document: the whole-dataset marker is dropped because it names
+ * none, and so is anything that is not a NextGraph reference - an ordinary IRI names no
+ * repo this library could hold a cap for, and the engine is left to match it or not.
+ * Deduplicated, so a scope repeating a document opens it once.
+ *
+ * `""` is named beside the marker although `isNuri` would drop it anyway. It is the SDK's
+ * own alias for `did:ng:i`, and a reader should be able to see that here rather than have
+ * to work out that a guard two files away happens to exclude it.
+ */
+function namedDocuments(scope: Scope): Nuri[] {
+  const out: Nuri[] = [];
+  for (const g of [scope.graphs].flat()) {
+    if (typeof g !== "string" || g === "" || g === WHOLE_DATASET) continue;
+    if (isNuri(g) && !out.includes(g)) out.push(g);
+  }
+  return out;
+}
+
+/**
+ * Are these two failures the same one, for the purpose of deciding whether a subscriber
+ * has anything new to look at?
+ *
+ * By MESSAGE, because every attempt builds its own `Error` object and identity would
+ * therefore always answer "different". A message is what an application shows and what a
+ * maintainer greps for, so two failures that read alike are alike here.
+ */
+function sameFailure(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  return a instanceof Error && b instanceof Error && a.message === b.message;
+}
+
+/**
+ * Create a reactive, `useQuery`-shaped observable over one SHEX `shapeType` in one
+ * `scope` - the SDK's own `{ graphs, subjects }`, passed through untouched. See the
+ * module header for what is read underneath and what each state means. The returned
+ * observable is inert until its first {@link ShapeObservable.subscribe} (or
+ * {@link ShapeObservable.refetch}) - that is what opens the shape query; before then
+ * `getSnapshot` reports the initial pending snapshot.
+ */
+// @provenance useShapeQuery kind=announced-not-written level=3 ref=.project/rules/nextgraph/surface-mirrors-the-sdk.md:useShapeQuery announced-by=nextgraph-developers@2026-09-16 - the SDK ships `useShape`, whose result carries data and a load state and no failure; the announced direction is a `useShapeQuery` returning a TanStack-shaped snapshot
+export function useShapeQuery<T extends BaseType = BaseType>(
+  shapeType: ShapeType<T>,
+  scope: Scope,
+): ShapeObservable<T> {
+  // The current, STABLE snapshot (same reference until a transition rebuilds it).
+  let snapshot: ShapeQuery<T> = {
+    data: [],
+    isPending: true,
+    isSuccess: false,
+    isError: false,
+    error: undefined,
+  };
+
+  const listeners = new Set<() => void>();
+  let started = false;
+  /** The shape query in force, or `null` between a teardown and the next open. */
+  let query: OrmSubscriptionHandle | null = null;
+  /** The change listener registered on {@link query}, so it can be taken off again. */
+  let onQueryChange: (() => void) | null = null;
+  /** Unsubscribe from the held-caps change signal (see the subscription in `start`). */
+  let capsUnsub: (() => void) | null = null;
+  /**
+   * Which open owns the question. A `refetch` supersedes the previous subscription, and
+   * a teardown supersedes all of them - so every callback checks it is still the current
+   * one before publishing. A stale answer is dropped, never merged.
+   */
+  let generation = 0;
+  /** Has the CURRENT generation's initial payload arrived? Gates every publication:
+   *  a change signal that beats `readyPromise` must not be read as an answer. */
+  let ready = false;
+  /**
+   * Is the BARRIER what left this observable without a query - rather than the shape
+   * query failing to open, or nothing having been tried yet?
+   *
+   * Only the first is worth attempting again: a `configure` with no `ormSubscription` is
+   * not repaired by a cap arriving, and retrying it on every keyring change would churn
+   * for a misconfiguration no amount of retrying repairs.
+   *
+   * It records no HOLDER, and an earlier version did. Keying the retry on "the same
+   * holder that was refused" looks like the way to stop a re-attempt acting for somebody
+   * who never asked, and it is a trap twice over: the anonymous ring is a holder like any
+   * other, so a refusal taken before the identity settles - which is where components
+   * mount - never matched again once it did; and an identity CAN change under a live page
+   * (`shared-wallet/access-gate.ts` adopts the identifier a revived barrier confirms), so
+   * the rule left that case terminal too. What actually has to hold is that no snapshot
+   * ever claims success for a document the CURRENT holder cannot reach, and that is
+   * enforced where it belongs, on every publication - see {@link publish}.
+   */
+  let barrierRefused = false;
+
+  function emit(): void {
+    for (const l of listeners) {
+      try {
+        l();
+      } catch (error) {
+        console.error("[use-shape-query] listener threw", error);
+      }
+    }
+  }
+
+  function setSnapshot(next: ShapeQuery<T>): void {
+    snapshot = next;
+    emit();
+  }
+
+  /**
+   * Publish "the current answer is UNKNOWN" - the one snapshot every failure on this
+   * path produces.
+   *
+   * `data` carries the LAST READ THAT ANSWERED rather than `[]`. A subscriber has
+   * already rendered that list and an observable cannot un-emit it; clearing it would
+   * put the empty answer back - in the field an application actually renders, and for
+   * the very case that must never read as empty. `isSuccess` stays false, so the array
+   * is never offered as a reply to the question that just failed, and a subscriber that
+   * gates on `isSuccess` shows nothing new while one that renders `data` keeps what it
+   * had. Before the first answer there is nothing to keep and `data` is `[]` - the
+   * initial value, published under `isError`, never under `isSuccess`.
+   */
+  function setUnknown(error: unknown): void {
+    // A standing failure that has not changed is not news. This surface documents its
+    // snapshot as STABLE until it actually changes, and a re-attempt that lands on the
+    // same refusal changes nothing an application renders - so handing out a fresh object
+    // carrying a fresh `Error` would break that promise and re-render every bound view
+    // for nothing. Measured: eight unrelated cap arrivals over a failing fetch produced
+    // eight notifications and eight distinct `Error`s for one unchanged state.
+    //
+    // Compared by MESSAGE rather than by identity, because each attempt builds its own
+    // `Error`. A failure that says something different IS news and is published.
+    if (snapshot.isError && sameFailure(snapshot.error, error)) return;
+    setSnapshot({
+      data: snapshot.data,
+      isPending: false,
+      isSuccess: false,
+      isError: true,
+      error,
+    });
+  }
+
+  /**
+   * Publish "the question is still open" - no authority yet, and nothing to say about the
+   * data either way.
+   *
+   * `data` is carried over for the same reason {@link setUnknown} carries it: an observable
+   * cannot un-emit a list a subscriber has already rendered. Before the first answer there
+   * is nothing to carry and it stays `[]`. Idempotent, so a document that keeps failing to
+   * sync does not wake every bound view on each attempt.
+   */
+  function setNotYetAnswered(): void {
+    if (snapshot.isPending && !snapshot.isSuccess && !snapshot.isError) return;
+    setSnapshot({
+      data: snapshot.data,
+      isPending: true,
+      isSuccess: false,
+      isError: false,
+      error: undefined,
+    });
+  }
+
+  /**
+   * The readable items of the live subscription, as a plain array.
+   *
+   * The ONE cast in this module, and it sits where the injected SDK meets the shape's
+   * promise: the subscription is typed by what `configure` received (`unknown` items,
+   * because the injection is a loose shape), while `shapeType` is what says they are
+   * `T`. Filtering happens first and on the raw items - the filter reads `@graph` and
+   * nothing else, so it needs no type at all.
+   */
+  function readable(handle: OrmSubscriptionHandle): T[] {
+    const caps = getCaps();
+    const items = [...handle.signalObject];
+    // No cap issued yet -> the emulation is not in force and the set passes through,
+    // exactly as `surface/use-shape.ts` does. See `emulated-verifier/read-filter.ts`.
+    const kept = caps.isEnforcing() ? filterReadable(items, caps) : items;
+    return kept as T[];
+  }
+
+  /**
+   * The refusal standing against the CURRENT holder for the first document the scope
+   * NAMES that it cannot reach, or `null` when it reaches all of them.
+   *
+   * It goes through `assertMayReach` and catches, rather than deciding again: the refusal
+   * is worded in exactly one place and a second wording here would drift from it. Scope
+   * order, like the barrier.
+   */
+  function namedRefusal(): unknown {
+    for (const doc of namedDocuments(scope)) {
+      try {
+        assertMayReach(doc, "useShapeQuery");
+      } catch (error) {
+        return error;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Has every document the scope NAMES actually ARRIVED - not merely "may this holder
+   * reach it", which is a different question and the only one this module used to ask?
+   *
+   * `emulated-verifier/open-repo.ts` DERIVES four values for exactly this reader - since
+   * `1.0.0-dev.10` nothing stores them, they are read off the document's one real
+   * subscription - and which of them counts as an answer is the whole of the decision:
+   *
+   *   - `"synced"` - a `State` has arrived on the channel standing NOW. THE truth signal:
+   *     zero rows means zero objects, and that is the success this surface exists to publish.
+   *     Read off the channel rather than remembered, so it cannot survive that channel's
+   *     teardown - which is what used to let a second `configure(...)` answer a success for a
+   *     document nothing was subscribed to.
+   *   - `"timed-out"` - opened, and no barrier to show for it: the bounded fallback fired, the
+   *     subscribe was refused, or the channel was taken away. Sync unconfirmed. The document
+   *     may hold anything and this read has no standing to call it empty.
+   *   - `"syncing"` - the open is still inside its bounded wait; refused for the same reason,
+   *     and if it is ever seen here the barrier demonstrably was not crossed.
+   *   - `"unknown"` - "never opened there, or the fake-ng no-op path: no `State` semantics".
+   *     **Passes, deliberately.** There is no barrier to have missed where there are no
+   *     barrier semantics, and an `ng` without `doc_subscribe` is the whole unit suite and
+   *     every early path. Treating it as not-synced is the inert regression this line of
+   *     work has already shipped twice.
+   */
+  function namedDocumentsArrived(): boolean {
+    for (const doc of namedDocuments(scope)) {
+      const state = getSyncState(doc);
+      if (state === "timed-out" || state === "syncing") return false;
+    }
+    return true;
+  }
+
+  /**
+   * Publish what the subscription holds right now. Only ever called on a READY
+   * generation, so this snapshot is always an answer.
+   *
+   * **The named documents are re-checked HERE, every time, and that is what makes the
+   * refusal self-healing.** The barrier decides once, before the query opens; this
+   * decides on each publication, against what the holder holds at that instant - so a cap
+   * arriving turns `isError` into the document through the channel that already existed,
+   * and a query opened while somebody else was connected can never come back to this
+   * subscriber as `isSuccess` holding nothing. A level, not an edge: there is no event to
+   * miss, because nothing is remembered.
+   *
+   * The capability FILTER below still applies on top, and the two are not the same
+   * question: the filter bounds what a scope may show per `@graph`, this refuses a scope
+   * the caller NAMED and cannot read. Under `did:ng:i` nothing is named and the filter is
+   * the whole of the answer, exactly as before.
+   */
+  function publish(handle: OrmSubscriptionHandle, gen: number): void {
+    if (gen !== generation || !ready) return;
+    const refusal = namedRefusal();
+    if (refusal !== null) {
+      setUnknown(refusal);
+      return;
+    }
+    // NOT AUTHORITATIVE YET, so say the question is still open rather than say "empty". A
+    // named document whose sync barrier was never crossed may hold anything, and
+    // publishing the ORM's view of it as `isSuccess` is the original defect in the one case
+    // the barrier was added to close.
+    //
+    // It PUBLISHES pending rather than returning. Returning left whatever snapshot was
+    // standing, and that was wrong in the case that matters: a refusal that has since been
+    // LIFTED stayed on display, so an application was handed `isError` reading "you do not
+    // hold this document's cap" about a document it now holds. Whatever the state was, it
+    // is not the answer to the question just asked.
+    if (!namedDocumentsArrived()) {
+      setNotYetAnswered();
+      return;
+    }
+    setSnapshot({
+      data: readable(handle),
+      isPending: false,
+      isSuccess: true,
+      isError: false,
+      error: undefined,
+    });
+  }
+
+  /**
+   * The SDK's shape query, or the error that says it was never injected.
+   *
+   * Upstream an application imports the ORM; here it hands it to `configure`, like the
+   * `ng` and the `useShape` beside it. Absent, there is nothing to read through - and
+   * that has to be said out loud rather than answered with an empty set, which is the
+   * one reading this surface must never produce.
+   */
+  function shapeQuery(): OrmSubscriptionLike {
+    const injected = getConfig().ormSubscription;
+    if (!injected) {
+      throw new Error(
+        "[ng-eventually] useShapeQuery: no shape query was injected. Pass " +
+          "`ormSubscription: RdfOrmSubscription.getOrCreate` (from `@ng-org/orm`) to " +
+          "configure() - this package reads through the SDK's own shape query and has " +
+          "no read of its own to fall back on.",
+      );
+    }
+    return injected;
+  }
+
+  /** Take the current subscription down: stop listening, close it, forget it. Leaves
+   *  the snapshot and the subscribers alone - this is not an answer, it is plumbing. */
+  function closeQuery(): void {
+    if (query === null) return;
+    const handle = query;
+    query = null;
+    ready = false;
+    if (onQueryChange) {
+      try {
+        handle.removeChangeListener(onQueryChange);
+      } catch {
+        /* ignore */
+      }
+      onQueryChange = null;
+    }
+    try {
+      handle.close();
+    } catch {
+      /* ignore */
+    }
+  }
+
+  /**
+   * Cross the barrier on every document the scope NAMES, before the query opens - the
+   * same two steps `docs.sparqlQuery` takes on its anchor, in the same order.
+   *
+   * `ensureRepoOpen` asks the (emulated) public store for the document's cap, and opens
+   * and syncs the repo when it may be touched; it declines SILENTLY when it may not,
+   * which is right for a caller that has another way to find out. This one has none, so
+   * `assertMayReach` says it out loud immediately after - without that, an unheld
+   * document would simply produce no objects and read as a document holding none.
+   *
+   * The opens run TOGETHER, and every outcome is then read in SCOPE ORDER, so the
+   * document reported is the first one the caller named that failed - whatever it failed
+   * of. Two earlier shapes were wrong about this and the difference is not cosmetic, it
+   * is which document the error names:
+   *
+   *   - one at a time: correct order, unacceptable cost. Each open waits on the sync
+   *     barrier, bounded by `OPEN_TIMEOUT_MS` (8s) for a document that never pushes a
+   *     `State`, so a scope naming N of them paid N timeouts before answering anything.
+   *   - `Promise.all`: right cost, wrong order. It SHORT-CIRCUITS on the first rejection
+   *     to arrive, which is a race - a fetch that rejects does not wait for the sync
+   *     barrier, so it overtakes a refusal on a document named before it, and the error
+   *     named the wrong document while a comment beside it claimed otherwise.
+   *
+   * `allSettled` has neither fault: nothing is discarded, nothing rejects early, and no
+   * rejection escapes as an unhandled one. The opens that succeeded are memoised per
+   * session exactly as they would have been, so a re-subscribe costs a map hit.
+   */
+  async function reachNamedDocuments(): Promise<void> {
+    const docs = namedDocuments(scope);
+    if (docs.length === 0) return;
+    const outcomes = await Promise.allSettled(docs.map((doc) => ensureRepoOpen(doc)));
+    for (const [i, doc] of docs.entries()) {
+      const outcome = outcomes[i];
+      if (outcome && outcome.status === "rejected") throw outcome.reason;
+      assertMayReach(doc, "useShapeQuery");
+    }
+  }
+
+  /**
+   * Open a shape query for `(shapeType, scope)` and wire its two signals.
+   *
+   * Supersedes whatever was open: the previous generation's callbacks are dropped on
+   * arrival rather than raced, so a slow answer can never clobber a newer question. The
+   * barrier above runs first, which is why the body is asynchronous - every step past an
+   * `await` re-checks that it is still the current generation before touching anything,
+   * so a `refetch` or a teardown during the barrier leaves no query behind.
+   */
+  function open(): void {
+    closeQuery();
+    const gen = ++generation;
+    barrierRefused = false;
+    // Sampled SYNCHRONOUSLY, before anything is awaited: what the keyring looked like when
+    // this attempt decided to trust it. See the comparison in the catch below.
+    const keyringAtStart = getCaps().version();
+    void (async () => {
+      try {
+        await reachNamedDocuments();
+      } catch (error) {
+        if (gen !== generation) return;
+        // THE EDGE THAT WOULD OTHERWISE BE MISSED, and it is the one that matters most: a
+        // keyring change landing WHILE the barrier was crossing fired its listener at a
+        // moment when there was no query to re-publish and no refusal on record yet, so
+        // the listener did nothing - and that same change is what made the walk refuse.
+        // Waiting for another event would be waiting for one that may never come; this
+        // attempt simply notices it raced and makes another, which re-samples.
+        //
+        // It terminates: an attempt is repeated only because the keyring moved, moves are
+        // finite events, and the moves an attempt causes itself are the caps it files -
+        // at most one per named document, after which that document is held and asks
+        // nothing.
+        if (getCaps().version() !== keyringAtStart) {
+          open();
+          return;
+        }
+        barrierRefused = true;
+        setUnknown(error);
+        return;
+      }
+      // Superseded while the barrier was crossing: drop this open rather than leaving a
+      // subscription nothing will ever close.
+      if (gen !== generation) return;
+      let handle: OrmSubscriptionHandle;
+      try {
+        handle = shapeQuery()(shapeType, scope);
+      } catch (error) {
+        setUnknown(error);
+        return;
+      }
+      query = handle;
+      const onChange = (): void => publish(handle, gen);
+      onQueryChange = onChange;
+      handle.addChangeListener(onChange);
+      handle.readyPromise.then(
+        () => {
+          if (gen !== generation) return;
+          ready = true;
+          publish(handle, gen);
+        },
+        (error: unknown) => {
+          // Nothing upstream rejects this promise today (see the module header); the
+          // rejection path is wired all the same, because a state nobody handles is how
+          // a failure becomes silence the day the ORM starts reporting one.
+          if (gen !== generation) return;
+          setUnknown(error);
+        },
+      );
+    })();
+  }
+
+  function start(): void {
+    if (started) return;
+    started = true;
+    // A cap that arrives ASYNCHRONOUSLY (an inbox deposit absorbed by the
+    // consumer's `inbox.watch`) makes items readable that were not. Without
+    // this the view would stay stale until some unrelated push happened to fire -
+    // so re-publish whenever the keyring changes. This is the delivery channel key
+    // ROTATION uses too, which is why keeping an access needs no subscription
+    // obligation on the consumer's side.
+    capsUnsub = getCaps().onChange(() => {
+      if (query !== null) {
+        publish(query, generation);
+        return;
+      }
+      // No query in force. Since `1.0.0-dev.9` there is a second way to be here, and it
+      // is the one this signal exists for: the BARRIER refused the scope, so the query
+      // was never created and there is nothing for `publish` to re-filter. A view left
+      // like that would be TERMINAL - the very case this channel was added to prevent,
+      // arriving by a door that did not exist when the channel was written.
+      //
+      // So ATTEMPT AGAIN. There is deliberately no further test of whether the refusal
+      // has been lifted, and none of who is asking: see the module header for why the
+      // obvious gate is circular, why an attempt is the cheaper question anyway, and why
+      // the holder belongs in {@link publish} rather than here.
+      if (barrierRefused) open();
+    });
+    open();
+  }
+
+  return {
+    getSnapshot(): ShapeQuery<T> {
+      return snapshot;
+    },
+    subscribe(onChange: () => void): () => void {
+      listeners.add(onChange);
+      start();
+      return () => {
+        listeners.delete(onChange);
+        if (listeners.size === 0) {
+          // Last listener gone -> close the shape query. A later subscribe opens a
+          // fresh one; the ORM pools what it has just closed, so that is cheap.
+          generation += 1;
+          closeQuery();
+          if (capsUnsub) {
+            capsUnsub();
+            capsUnsub = null;
+          }
+          started = false;
+        }
+      };
+    },
+    refetch(): void {
+      if (!started) {
+        start();
+        return;
+      }
+      open();
+    },
+  };
+}

packages/polyfill/src/surface/use-shape.ts

@@ -1,18 +1,40 @@
 /**
- * Wrapped `useShape`: same signature as `@ng-org/orm`. Once the cap emulation is
- * in force, the returned set is a read-filtered VIEW (only items in documents the
- * current holder has the ReadCap of); before the first cap is issued it passes the
- * real set through unchanged. At migration the filtering disappears — the broker
- * only delivers documents whose cap the wallet holds.
+ * Wrapped `useShape`: the same call the SDK's React hook offers, and the same two
+ * arguments. Once the cap emulation is in force, what comes back is a read-filtered VIEW
+ * over the RESULT ENVELOPE the hook returns - `data` and `promise` carry only items in
+ * documents the current holder has the `ReadCap` of, `subscription` is refused, and the
+ * page commands and the load state pass through. A member's DESCRIPTOR answers what reading
+ * it answers, so what is built on that call reads through the view rather than round it -
+ * which for the envelope means a SPREAD of the result THROWS on `subscription` rather than
+ * copying it out. What no trap reaches is the HOST's own introspection: `console.log` and a
+ * devtools inspector read the object behind the proxy and print every identity's items
+ * (measured on Bun/JSC). The contract says so; there is nothing here to fix. Before the first cap is issued the real
+ * result passes through unchanged. At migration the filtering disappears: the broker only
+ * delivers documents whose cap the wallet holds.
+ *
+ * ── What changed on 2026-09-24, and why it was invisible ──────────────────
+ * This wrapped the result in the COLLECTION view (`makeReadFilteredView`), which is
+ * written for a `DeepSignalSet`. That was right while the hook returned one - `alpha.18` -
+ * and wrong the moment `@ng-org/orm@0.1.2-alpha.21` started returning a `UseShapeResult`
+ * around it. Against that shape the collection view threw on `[...result]` and `.size`
+ * (an envelope is not iterable) and returned `data`, `promise` and `subscription` RAW,
+ * each of them every identity's items. Nothing failed, because no fake in this repository
+ * returned the shape the SDK ships.
  */
 
+import type { BaseType, ShapeType } from "@ng-org/shex-orm";
+import type { RdfOrmConfig } from "@ng-org/orm/all";
 import { getConfig, getCaps } from "../shared-wallet/bootstrap";
-import { makeReadFilteredView } from "../emulated-verifier/read-filter";
+import { makeReadFilteredShapeResult } from "../emulated-verifier/read-filter";
+import type { ShapeResult } from "../model/types";
 
-// @provenance useShape kind=passthrough level=3 ref=sdk/js/orm/src/frontendAdapters/react/useShape.ts:useShape — forwards to the injected real hook; the read-filtered view emulates cryptographic isolation and the generic `T` is widened to `unknown`
-export function useShape(shapeType: unknown, scope: unknown): unknown {
-  const set = getConfig().useShape(shapeType, scope) as object;
+// @provenance useShape kind=passthrough level=3 ref=sdk/js/orm/src/frontendAdapters/react/useShape.ts:useShape - forwards to the injected real hook, with its two arguments; the read-filtered view over the result envelope emulates cryptographic isolation
+export function useShape<T extends BaseType>(
+  shapeType: ShapeType<T>,
+  conf: RdfOrmConfig<T> | string | undefined,
+): ShapeResult {
+  const result = getConfig().useShape(shapeType, conf);
   const caps = getCaps();
-  if (!caps.isEnforcing()) return set; // no cap issued yet → passthrough
-  return makeReadFilteredView(set, caps);
+  if (!caps.isEnforcing()) return result; // no cap issued yet → passthrough
+  return makeReadFilteredShapeResult(result, caps);
 }

packages/polyfill/src/surface/watch-shape.ts

@@ -1,457 +0,0 @@
-/**
- * watch-shape — a REACTIVE, TanStack-`useQuery`-shaped read over one SHEX shape in
- * one logical scope. This is the surface the consuming app will bind (phase B) with
- * `useSyncExternalStore` — the polyfill deliberately exposes an OBSERVABLE, never a
- * React hook (the lib has NO React dependency, same constraint as `subscribe.ts`).
- *
- * ── Why an observable, and why this exact shape ────────────────────────────
- * It anticipates NextGraph's planned `useShape(shape, scope)` upgrade, which will
- * natively distinguish "sync in progress" from "synced but empty". That distinction
- * ALREADY exists lib-internally (`open-repo.ts` `getSyncState`: syncing / synced /
- * timed-out); `watchShape` merely SURFACES it as a `useQuery`-minimal snapshot:
- *   `ShapeQuery<T> = { data: T[]; isPending; isSuccess; isError; error }`.
- * `data` is ALWAYS an array (never `undefined`), so a synced-but-empty scope reads
- * `{ data: [], isPending: false, isSuccess: true }` — the key distinction — while a
- * scope still syncing reads `{ data: [], isPending: true, isSuccess: false }`.
- *
- * ── What the observable OWNS (the whole read pipeline) ─────────────────────
- *   1. Resolve the logical scope → the doc set: the CURRENT wallet's own per-entity
- *      documents for that scope (`storeRegistry.listMyEntityDocs`), and nothing
- *      else. There is no "everything public" to fold in — **you cannot discover,
- *      you can only follow links** (see docs/readcap-and-nuri-model.md §4ter-bis),
- *      and a link reaches you through an inbox or through a document you already
- *      hold. A document whose cap you were given is read by NAMING it
- *      (`readUnion`), not by turning up in a scope you never put it in.
- *   2. Open the docs (`ensureReposOpen`) — this AWAITS the sync BARRIER (first
- *      `State` per doc, `getSyncState` → `synced`, or `timed-out` on the bounded
- *      fallback). `isPending` holds until the barrier is reached for the current
- *      doc set AND the first `readUnion` has rendered.
- *   3. `readUnion(docs)` — the read-model (cap filter already applied inside; we do
- *      NOT double-filter), then FILTER the union by the requested shape's `@type`
- *      (a `readUnion` union spans multiple types; each `watchShape` yields only the
- *      subjects of its shape). Non-domain: the type IRI is read from the SHEX
- *      ShapeType, not from any application concept.
- *
- * ── Reactivity WITHOUT polling (no `setInterval`) ──────────────────────────
- * Reactivity is push-only (rule no-broker-polling). It has TWO sources: document
- * pushes, and the KEYRING — a cap that arrives asynchronously (an inbox delivery
- * absorbed by the consumer's `inbox.watch`) makes documents readable that were not,
- * so `CapRegistry.onChange` re-reads. Without that, a view stays stale until an
- * unrelated push happens to fire. On the document side, `subscribeDoc` on every doc
- * in the current set re-runs `readUnion` on any push. The set is DYNAMIC (creating an
- * entity appends a NURI to the scope-index doc), so we ALSO subscribe to the
- * scope-index document: a push there re-RESOLVES the scope and re-keys the
- * subscribed set. Subscriptions are idempotent — an already-followed
- * doc is not re-subscribed. Everything reuses `subscribe.ts` / `open-repo.ts`; no
- * parallel channel.
- *
- * ── timed-out → isSuccess (best-effort), NOT isError ───────────────────────
- * A doc whose barrier fell back to `timed-out` still counts as "barrier reached"
- * (`isSuccess`): a slow-but-empty wallet must read as empty-success, not error.
- * `isError` fires ONLY on a real thrown exception in the pipeline.
- *
- * ── A scope that did not answer is NOT an empty scope ──────────────────────
- * The pipeline's first step ASKS a question — which documents are mine in this scope
- * — and until 2026-08-17 a failure to answer it was logged and treated as "none":
- * the empty set flowed on, the barrier over zero docs is trivially reached, and the
- * surface published `{ data: [], isSuccess: true }`. That snapshot is BYTE-FOR-BYTE
- * the synced-but-empty one this module exists to distinguish, so the one distinction
- * it publishes was the one it destroyed — an application rendered "you have nothing"
- * for "the store did not answer". `listMyEntityDocs` stopped handing out that reading
- * one layer down (`90712e0`); catching it here put it straight back.
- *
- * A resolution failure now travels the LOAD-STATE channel, which is where "this is
- * not an answer" already lives on this surface: `isError` with the thrown `error`,
- * and never `isSuccess`. The channel is the honest place because it is the one an
- * application already has to read to tell pending from empty — the same three-way
- * question, and the third state costs it no new vocabulary.
- *
- * ── An observable cannot un-emit: `data` survives an error ─────────────────
- * A one-shot call rejects and is done. An observable has already handed a list to a
- * subscriber that rendered it, so its failure snapshot has to say something about
- * that list — and collapsing it to `[]` would hand out, in `data`, exactly the empty
- * answer this fix removes. So `data` KEEPS the last read that actually answered, and
- * `isError` says the current answer is unknown. `isSuccess` is false throughout: the
- * array is a memory, not a reply to the question just asked.
- */
-
-import { getCaps, getCurrentUser } from "../shared-wallet/bootstrap";
-import { ensureReposOpen, getSyncState } from "../emulated-verifier/open-repo";
-import { readUnion, type UnionSubject } from "./read-model";
-import { subscribeDoc, type Unsubscribe } from "./subscribe";
-import { listMyEntityDocs, userStoreDoc } from "../shared-wallet/account-registry";
-import type { Nuri, Scope } from "../model/types";
-
-/**
- * The RDF `type` predicate IRI. A SHEX shape pins its class via a triple
- * constraint on this predicate; we filter the read union by it.
- */
-const RDF_TYPE = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type";
-
-/**
- * A minimal TanStack-`useQuery`-shaped read snapshot. `data` is ALWAYS an array
- * (never `undefined`). Defaults `T` to {@link UnionSubject} — `watchShape` yields
- * the generic per-subject property bags of the read-model (NO application domain);
- * the app maps them to its own entity types in phase B.
- */
-// @provenance ShapeQuery kind=invention level=none ref=none — no upstream type carries load state; `OrmSubscription.readyPromise` expresses pending-vs-ready and nothing else (built with `resolve` alone, and `orm_start_graph` failing is only logged — a failed read is an eternal pending), so `isError` has no counterpart at any level
-export interface ShapeQuery<T = UnionSubject> {
-  /** The subjects of the requested shape/scope. Empty array when none (never undefined).
-   *  When `isError`, this is the last read that ANSWERED — kept, not cleared, because an
-   *  observable cannot un-emit and `[]` here would be the false "you have nothing" the
-   *  error state exists to prevent. Read it as a memory then, not as a reply. */
-  data: T[];
-  /** True while the sync barrier for the current doc set is not yet reached OR the
-   *  first `readUnion` has not rendered. Mutually exclusive with `isSuccess`. */
-  isPending: boolean;
-  /** True once the barrier is reached (all docs `synced` OR `timed-out`) AND the
-   *  first `readUnion` has rendered. A synced-but-EMPTY scope is `isSuccess` with
-   *  `data: []` — the distinction this surface exists for. */
-  isSuccess: boolean;
-  /** True ONLY on a real thrown exception in the read pipeline (never for `timed-out`):
-   *  the scope could not be resolved, or the union could not be read. It means the
-   *  current answer is UNKNOWN — never that the scope is empty. Mutually exclusive with
-   *  both `isPending` and `isSuccess`. */
-  isError: boolean;
-  /** The caught error when `isError`, else `undefined`. */
-  error: unknown;
-}
-
-/** The observable a caller binds with `useSyncExternalStore` (phase B). */
-// @provenance ShapeObservable kind=invention level=none ref=none — no upstream observable exists; the ORM exposes a hook returning a DeepSignalSet and nothing else
-export interface ShapeObservable<T = UnionSubject> {
-  /** The current snapshot. STABLE across calls until it actually changes (so
-   *  `useSyncExternalStore` does not loop): the same reference is returned until a
-   *  state transition produces a new one. */
-  getSnapshot(): ShapeQuery<T>;
-  /** Register a change listener; returns an unsubscribe. The last listener's
-   *  unsubscribe tears down the underlying doc subscriptions. */
-  subscribe(onChange: () => void): () => void;
-  /** Force a re-resolve + re-read now (e.g. an imperative refresh). Idempotent
-   *  w.r.t. subscriptions; never polls. */
-  refetch(): void;
-}
-
-/**
- * Derive the class IRI(s) a SHEX {@link ShapeType} pins on `rdf:type`, if any.
- * A generated shape constrains its subject's type via a triple constraint on the
- * `rdf:type` predicate whose `literals` carry the class IRI(s). Returns the set of
- * those IRIs, or `null` when the shape pins NO type (then no type-filter is applied
- * and every subject in the doc set flows through). Purely structural — reads only
- * the SHEX schema, no application domain.
- */
-function shapeTypeIris(shapeType: unknown): Set<string> | null {
-  try {
-    const st = shapeType as {
-      shape?: string;
-      schema?: Record<string, { predicates?: Array<{ iri?: string; dataTypes?: Array<{ literals?: unknown[] }> }> }>;
-    };
-    const shape = st?.shape && st.schema ? st.schema[st.shape] : undefined;
-    const preds = shape?.predicates ?? [];
-    const iris = new Set<string>();
-    for (const p of preds) {
-      if (p?.iri !== RDF_TYPE) continue;
-      for (const dt of p.dataTypes ?? []) {
-        for (const lit of dt.literals ?? []) {
-          if (typeof lit === "string") iris.add(lit);
-        }
-      }
-    }
-    return iris.size > 0 ? iris : null;
-  } catch {
-    return null;
-  }
-}
-
-/** Whether a subject satisfies the shape's `@type` constraint (or the shape pins none). */
-function matchesShape(subject: UnionSubject, typeIris: Set<string> | null): boolean {
-  if (!typeIris) return true; // shape pins no rdf:type → accept every subject
-  const types = subject.props[RDF_TYPE] ?? [];
-  return types.some((t) => typeIris.has(t));
-}
-
-/**
- * Whether the sync BARRIER is reached for the whole doc set. Called only AFTER
- * `ensureReposOpen(docs)` has resolved, so each doc has been requested; the only
- * state that still holds the barrier open is `syncing` (subscribed, first `State`
- * not yet received). `synced` and `timed-out` both count as reached (`timed-out` is
- * best-effort, not an error). `unknown` means the injected `ng` has no
- * `doc_subscribe` (the fake/no-op open path, which has NO barrier semantics) — after
- * a completed open it can only mean that path, so it counts as reached (opened,
- * nothing to wait on). An EMPTY doc set is trivially past the barrier.
- */
-function barrierReached(docs: Nuri[]): boolean {
-  for (const d of docs) {
-    if (getSyncState(d) === "syncing") return false;
-  }
-  return true;
-}
-
-/**
- * Create a reactive, `useQuery`-shaped observable over one SHEX `shapeType` in one
- * logical `scope` (`'public' | 'protected' | 'private'`). See the module header for
- * the full pipeline. The returned observable is inert until its first
- * {@link ShapeObservable.subscribe} (or {@link ShapeObservable.refetch}) — that is
- * what kicks off resolution, opening and the first read; before then `getSnapshot`
- * reports the initial pending snapshot.
- */
-// @provenance watchShape kind=invention level=none ref=none — nothing upstream distinguishes syncing from synced-empty at the hook, and nothing anywhere expresses the third state it now publishes: a failed `orm_start_graph` leaves `readyPromise` unsettled forever, so upstream's "could not find out" IS its "still pending"; the header's 'planned useShape upgrade' has NO upstream provenance
-export function watchShape<T = UnionSubject>(
-  shapeType: unknown,
-  scope: Scope,
-): ShapeObservable<T> {
-  const typeIris = shapeTypeIris(shapeType);
-
-  // The current, STABLE snapshot (same reference until a transition rebuilds it).
-  let snapshot: ShapeQuery<UnionSubject> = {
-    data: [],
-    isPending: true,
-    isSuccess: false,
-    isError: false,
-    error: undefined,
-  };
-
-  const listeners = new Set<() => void>();
-  let started = false;
-  // The docs currently subscribed for change signals, keyed by NURI → unsubscribe.
-  // Idempotent: a doc already here is not re-subscribed. Excludes the container
-  // (scope-index / discovery-index) subscriptions, held separately.
-  const docSubs = new Map<Nuri, Unsubscribe>();
-  // Container subscriptions (scope-index doc; discovery-index doc for `public`) —
-  // a push here means the doc SET may have changed → re-resolve.
-  const containerSubs = new Map<Nuri, Unsubscribe>();
-  // Unsubscribe from the held-caps change signal (see the subscription in `start`).
-  let capsUnsub: (() => void) | null = null;
-  // True while `resolveDocs` runs. Folding a repo link files a cap, which fires the
-  // held-caps signal; the resolution in progress already accounts for it, so the
-  // signal is ignored during that window instead of restarting the cycle.
-  let resolving = false;
-  // Monotonic token so a slow in-flight refresh cannot clobber a newer one.
-  let refreshToken = 0;
-
-  function emit(): void {
-    for (const l of listeners) {
-      try {
-        l();
-      } catch (error) {
-        console.error("[watch-shape] listener threw", error);
-      }
-    }
-  }
-
-  function setSnapshot(next: ShapeQuery<UnionSubject>): void {
-    snapshot = next;
-    emit();
-  }
-
-  /**
-   * Publish "the current answer is UNKNOWN" — the one snapshot every failure in the
-   * pipeline produces, wherever it was thrown.
-   *
-   * `data` carries the LAST READ THAT ANSWERED rather than `[]`. A subscriber has
-   * already rendered that list and an observable cannot un-emit it; clearing it would
-   * put the empty answer back — in the field an application actually renders, and for
-   * the very case that must never read as empty. `isSuccess` stays false, so the array
-   * is never offered as a reply to the question that just failed, and a subscriber that
-   * gates on `isSuccess` shows nothing new while one that renders `data` keeps what it
-   * had. Before the first answer there is nothing to keep and `data` is `[]` — the
-   * initial value, published under `isError`, never under `isSuccess`.
-   */
-  function setUnknown(error: unknown): void {
-    setSnapshot({
-      data: snapshot.data,
-      isPending: false,
-      isSuccess: false,
-      isError: true,
-      error,
-    });
-  }
-
-  /** Resolve the logical scope → the current doc set: the CURRENT wallet's own
-   *  entity documents for that scope, and nothing else.
-   *
-   *  It PROPAGATES, and that is the whole point: the set it returns is what the rest
-   *  of the pipeline calls "the scope", so a swallowed failure here does not degrade
-   *  the answer, it INVENTS one — zero documents, a barrier trivially reached over
-   *  them, and `isSuccess` published over a store nobody read. Nothing downstream can
-   *  tell that set apart from a scope that is genuinely empty, because it IS the same
-   *  set. The caller's error state exists for this.
-   *
-   *  There is no "everything public" to fold in. You cannot discover; you can only
-   *  follow links, and a link reaches you through an inbox or through a document
-   *  you already hold — never through a shared index. A document someone gave you
-   *  the cap for is read by naming it (`readUnion`), not by appearing in
-   *  a scope you did not put it in. */
-  async function resolveDocs(): Promise<Nuri[]> {
-    const user = getCurrentUser();
-    const set = new Set<Nuri>();
-    resolving = true;
-    try {
-      if (user) {
-        for (const d of await listMyEntityDocs(user, scope)) set.add(d);
-      }
-    } finally {
-      resolving = false;
-    }
-    return [...set];
-  }
-
-  /** Subscribe to the CONTAINER document (the scope index) so a change to the doc
-   *  SET re-resolves. Idempotent per NURI.
-   *
-   *  This one SWALLOWS, deliberately and unlike `resolveDocs` next door. It resolves
-   *  no data and publishes no snapshot — it wires a change signal — so its failure
-   *  cannot dress an unread store up as an empty one. And the answer is not lost with
-   *  it: `resolveDocs` runs immediately after over the SAME account, so a store that
-   *  cannot be reached surfaces there, as an error, one line later. What is lost is
-   *  reactivity to a later change of the SET, which is a different (and much quieter)
-   *  problem than the one this module was fixed for. */
-  async function ensureContainerSubs(): Promise<void> {
-    const containers: Nuri[] = [];
-    const user = getCurrentUser();
-    if (user) {
-      try {
-        containers.push(await userStoreDoc(user, scope));
-      } catch (error) {
-        console.error("[watch-shape] userStoreDoc failed", error);
-      }
-    }
-    for (const c of containers) {
-      if (!c || containerSubs.has(c)) continue;
-      // A push on a container doc means the set may have changed → full re-resolve.
-      containerSubs.set(c, subscribeDoc(c, () => void refresh()));
-    }
-  }
-
-  /** Re-key the per-doc change subscriptions to exactly `docs` (idempotent adds,
-   *  prune removed). A push on any of these re-reads (data-only, no re-resolve). */
-  function syncDocSubs(docs: Nuri[]): void {
-    const wanted = new Set(docs.filter(Boolean));
-    for (const [nuri, unsub] of docSubs) {
-      if (!wanted.has(nuri)) {
-        try {
-          unsub();
-        } catch {
-          /* ignore */
-        }
-        docSubs.delete(nuri);
-      }
-    }
-    for (const nuri of wanted) {
-      if (docSubs.has(nuri)) continue;
-      docSubs.set(nuri, subscribeDoc(nuri, () => void reread()));
-    }
-  }
-
-  /** Read (union + shape filter) the CURRENT doc set and publish a snapshot.
-   *  Derives isPending/isSuccess from the barrier + whether the read rendered. */
-  async function readAndPublish(docs: Nuri[], token: number): Promise<void> {
-    let subjects: UnionSubject[];
-    try {
-      subjects = await readUnion(docs);
-    } catch (error) {
-      if (token !== refreshToken) return;
-      setUnknown(error);
-      return;
-    }
-    if (token !== refreshToken) return; // superseded by a newer refresh/reread
-    const data = subjects.filter((s) => matchesShape(s, typeIris));
-    const past = barrierReached(docs);
-    setSnapshot({
-      data,
-      isPending: !past,
-      isSuccess: past,
-      isError: false,
-      error: undefined,
-    });
-  }
-
-  /** Full cycle: resolve the scope, (re)establish container subs, open the docs
-   *  (await the barrier), sync per-doc subs, then read + publish.
-   *
-   *  This catch is the surface's ONE answer to "the pipeline could not answer" —
-   *  scope resolution included, since `resolveDocs` propagates. It is reached only
-   *  when the cycle is still the current one; a superseded cycle's failure is
-   *  dropped, because a newer cycle owns the question by then. */
-  async function refresh(): Promise<void> {
-    const token = ++refreshToken;
-    try {
-      await ensureContainerSubs();
-      const docs = await resolveDocs();
-      if (token !== refreshToken) return;
-      syncDocSubs(docs);
-      // Open/await the barrier (first State per doc, or timed-out). No-op once open.
-      await ensureReposOpen(docs);
-      if (token !== refreshToken) return;
-      await readAndPublish(docs, token);
-    } catch (error) {
-      if (token !== refreshToken) return;
-      setUnknown(error);
-    }
-  }
-
-  /** A push on an already-open doc: re-read the CURRENT set only (no re-resolve,
-   *  the set is unchanged). Reuses the docs we are subscribed to. */
-  async function reread(): Promise<void> {
-    const token = ++refreshToken;
-    const docs = [...docSubs.keys()];
-    await readAndPublish(docs, token);
-  }
-
-  function start(): void {
-    if (started) return;
-    started = true;
-    // A cap that arrives ASYNCHRONOUSLY (an inbox deposit absorbed by the
-    // consumer's `inbox.watch`) makes documents readable that were not. Without
-    // this the view would stay stale until some unrelated push happened to fire —
-    // so re-read whenever they change. This is the delivery channel key
-    // ROTATION uses too, which is why keeping an access needs no subscription
-    // obligation on the consumer's side.
-    capsUnsub = getCaps().onChange(() => {
-      if (!resolving) void refresh();
-    });
-    void refresh();
-  }
-
-  return {
-    getSnapshot(): ShapeQuery<T> {
-      return snapshot as unknown as ShapeQuery<T>;
-    },
-    subscribe(onChange: () => void): () => void {
-      listeners.add(onChange);
-      start();
-      return () => {
-        listeners.delete(onChange);
-        if (listeners.size === 0) {
-          // Last listener gone → tear down the underlying subscriptions. A later
-          // subscribe restarts a fresh cycle.
-          for (const u of docSubs.values()) {
-            try {
-              u();
-            } catch {
-              /* ignore */
-            }
-          }
-          for (const u of containerSubs.values()) {
-            try {
-              u();
-            } catch {
-              /* ignore */
-            }
-          }
-          docSubs.clear();
-          containerSubs.clear();
-          if (capsUnsub) {
-            capsUnsub();
-            capsUnsub = null;
-          }
-          started = false;
-        }
-      };
-    },
-    refetch(): void {
-      start();
-      void refresh();
-    },
-  };
-}

packages/polyfill/test/app-surface.test.ts

@@ -15,7 +15,11 @@ import {
   resetStoreRegistry,
   setCurrentUser,
 } from "../src/shared-wallet/bootstrap";
-import { createEntityDoc as registryCreateEntityDoc, resetRegistryCache } from "../src/shared-wallet/account-registry";
+import {
+  createEntityDoc as registryCreateEntityDoc,
+  listMyEntityDocs as registryListMyEntityDocs,
+  resetRegistryCache,
+} from "../src/shared-wallet/account-registry";
 import { share } from "../src/surface/inbox";
 
 const SHIM = "urn:ng-eventually:shim";
@@ -126,18 +130,30 @@ test("ensureIdentity returns the identity it settled", async () => {
 test("a placement call before signing in names the mistake", async () => {
   inject();
   setCurrentUser(null);
-  await expect(storeRegistry.createEntityDoc("protected")).rejects.toThrow(/ensureIdentity/i);
-  await expect(storeRegistry.listMyEntityDocs("protected")).rejects.toThrow(/no identity/i);
+  await expect(storeRegistry.createEntityDoc()).rejects.toThrow(/ensureIdentity/i);
+  await expect(storeRegistry.protectedStore()).rejects.toThrow(/no identity/i);
 });
 
 test("placement acts as the connected user, with nothing passed", async () => {
   inject();
   setCurrentUser("alice");
-  const doc = await storeRegistry.createEntityDoc("protected");
-  expect(await storeRegistry.listMyEntityDocs("protected")).toContain(doc);
+  const doc = await storeRegistry.createEntityDoc(await storeRegistry.protectedStore());
+  expect(await registryListMyEntityDocs("alice", "protected")).toContain(doc);
 
   setCurrentUser("bob");
-  expect(await storeRegistry.listMyEntityDocs("protected")).not.toContain(doc);
+  expect(await registryListMyEntityDocs("bob", "protected")).not.toContain(doc);
+});
+
+// A store reference that is not one of the connected identity's three is a caller error,
+// and silence here would be the worst answer available: the document would be created,
+// successfully, somewhere its author did not ask for — and only a later listing that comes
+// back short would say so.
+test("createEntityDoc refuses a store that is not one of this identity's", async () => {
+  inject();
+  setCurrentUser("alice");
+  const hers = await storeRegistry.protectedStore();
+  setCurrentUser("bob");
+  await expect(storeRegistry.createEntityDoc(hers)).rejects.toThrow(/not one of this identity/i);
 });
 
 // ── sharing names someone who exists ───────────────────────────────────────
@@ -145,7 +161,7 @@ test("placement acts as the connected user, with nothing passed", async () => {
 test("share refuses a recipient nobody has signed in as, instead of creating them", async () => {
   inject();
   setCurrentUser("alice");
-  const doc = await storeRegistry.createEntityDoc("protected");
+  const doc = await storeRegistry.createEntityDoc(await storeRegistry.protectedStore());
   // "bpb" is a typo for "bob". It used to mint that name's three stores and an inbox,
   // and the cap landed where nobody will ever look — with no error at all.
   await expect(share(doc, "bpb")).rejects.toThrow(/no such recipient/i);
@@ -157,7 +173,7 @@ test("share refuses a recipient nobody has signed in as, instead of creating the
 test("a failed lookup surfaces as a failure, not as 'no such recipient'", async () => {
   const { quads } = inject();
   setCurrentUser("alice");
-  const doc = await storeRegistry.createEntityDoc("protected");
+  const doc = await storeRegistry.createEntityDoc(await storeRegistry.protectedStore());
   setCurrentUser("bob");
   await registryCreateEntityDoc("bob", "private"); // bob genuinely exists
   setCurrentUser("alice");
@@ -178,7 +194,7 @@ test("a failed lookup surfaces as a failure, not as 'no such recipient'", async
 test("createEntityDoc reports a half-written document instead of returning its reference", async () => {
   inject(/shim:contains/); // the LISTING write fails
   setCurrentUser("alice");
-  await expect(storeRegistry.createEntityDoc("protected")).rejects.toThrow(/not listed in its store/i);
+  await expect(storeRegistry.createEntityDoc(await storeRegistry.protectedStore())).rejects.toThrow(/not listed in its store/i);
 });
 
 // Both writes are attempted before the failure is raised — the cap must land even when
@@ -187,14 +203,14 @@ test("createEntityDoc reports a half-written document instead of returning its r
 test("a failed listing does not cost the document its key", async () => {
   const { quads } = inject(/shim:contains/);
   setCurrentUser("alice");
-  await storeRegistry.createEntityDoc("protected").catch(() => {});
+  await storeRegistry.createEntityDoc(await storeRegistry.protectedStore()).catch(() => {});
   expect(quads.some((q) => q.p === `${SHIM}:readCap`)).toBe(true);
 });
 
 test("a failed key write is reported too, and names that half", async () => {
   inject(/shim:readCap/);
   setCurrentUser("alice");
-  await expect(storeRegistry.createEntityDoc("protected")).rejects.toThrow(/key is not recorded/i);
+  await expect(storeRegistry.createEntityDoc(await storeRegistry.protectedStore())).rejects.toThrow(/key is not recorded/i);
 });
 
 // The third write a PUBLIC creation makes, and the one that was still silent: exposing the
@@ -206,6 +222,6 @@ test("a failed key write is reported too, and names that half", async () => {
 test("a public document whose cap could not be exposed is reported, not returned", async () => {
   inject(/shim:exposedReadCap/);
   setCurrentUser("alice");
-  await expect(storeRegistry.createEntityDoc("public")).rejects.toThrow(/broker refused/i);
+  await expect(storeRegistry.createEntityDoc(await storeRegistry.publicStore())).rejects.toThrow(/broker refused/i);
 });
 

packages/polyfill/test/cold-open-document-inbox.test.ts

@@ -37,6 +37,7 @@ import { test, expect, describe, afterAll, beforeEach } from "bun:test";
 import { docs, storeRegistry } from "../src/index";
 import { adoptCurrentUser } from "../src/shared-wallet/bootstrap";
 import { getSyncState } from "../src/emulated-verifier/open-repo";
+import { listMyEntityDocs } from "../src/shared-wallet/account-registry";
 import { bootPage, forgetEverything, reloadPage, signIn, SESSION, type Quad } from "./wallet-fake";
 import type { Nuri, PrincipalId } from "../src/model/types";
 
@@ -59,7 +60,7 @@ function settledButNotConnected(id: PrincipalId): void {
 async function aNoteOpenedForMessages(quads: Quad[]): Promise<Nuri> {
   bootPage(quads, COLD);
   await signIn("alice");
-  const note = await storeRegistry.createEntityDoc("public");
+  const note = await storeRegistry.createEntityDoc(await storeRegistry.publicStore());
   await docs.sparqlUpdate(
     SESSION.sessionId,
     `INSERT DATA { <${note}> <${TITLE}> "Courses" }`,
@@ -92,9 +93,14 @@ function herPrivateStore(quads: Quad[]): Nuri {
   return record.o as Nuri;
 }
 
-/** Alice's note, found the way her application finds it: by listing her own store. */
+/** Alice's note, found by listing her own store.
+ *
+ *  That listing is the LIBRARY's own path now, not an application's: `listMyEntityDocs`
+ *  stopped being published in `1.0.0-dev.5` (no counterpart at any level upstream), so
+ *  this reaches it where it lives. What is under test is unchanged - the cold store still
+ *  has to answer, and it still has to refile the caps while it does. */
 async function myNote(): Promise<Nuri> {
-  const mine = await storeRegistry.listMyEntityDocs("public");
+  const mine = await listMyEntityDocs("alice", "public");
   const note = mine[0];
   if (!note) throw new Error("the note Alice wrote is not in her store");
   return note;
@@ -154,7 +160,7 @@ describe("opening my note for messages again, on a page that has just loaded", (
     const quads: Quad[] = [];
     bootPage(quads, COLD);
     await signIn("alice");
-    const bare = await storeRegistry.createEntityDoc("public");
+    const bare = await storeRegistry.createEntityDoc(await storeRegistry.publicStore());
     await docs.sparqlUpdate(
       SESSION.sessionId,
       `INSERT DATA { <${bare}> <${TITLE}> "Vierge" }`,

packages/polyfill/test/cold-read-for-document.test.ts

@@ -29,6 +29,7 @@
 import { test, expect, describe, afterAll, beforeEach } from "bun:test";
 import { docs, inbox as inboxSurface, storeRegistry } from "../src/index";
 import { getSyncState } from "../src/emulated-verifier/open-repo";
+import { listMyEntityDocs } from "../src/shared-wallet/account-registry";
 import { bootPage, forgetEverything, reloadPage, signIn, SESSION, type Quad } from "./wallet-fake";
 import type { Nuri } from "../src/model/types";
 
@@ -47,7 +48,7 @@ const COLD = { unsyncedUntilSubscribed: true } as const;
 async function aNoteWithAMessageOnIt(quads: Quad[]): Promise<Nuri> {
   bootPage(quads, COLD);
   await signIn("alice");
-  const note = await storeRegistry.createEntityDoc("public");
+  const note = await storeRegistry.createEntityDoc(await storeRegistry.publicStore());
   await docs.sparqlUpdate(
     SESSION.sessionId,
     `INSERT DATA { <${note}> <${TITLE}> "Courses" }`,
@@ -75,9 +76,14 @@ function inboxOnTheNote(quads: Quad[], note: Nuri): Nuri {
   return record.o.split(" ")[1] as Nuri;
 }
 
-/** Alice's note, found the way her application finds it: by listing her own store. */
+/** Alice's note, found by listing her own store.
+ *
+ *  That listing is the LIBRARY's own path now, not an application's: `listMyEntityDocs`
+ *  stopped being published in `1.0.0-dev.5` (no counterpart at any level upstream), so
+ *  this reaches it where it lives. What is under test is unchanged - the cold store still
+ *  has to answer, and it still has to refile the caps while it does. */
 async function myNote(): Promise<Nuri> {
-  const mine = await storeRegistry.listMyEntityDocs("public");
+  const mine = await listMyEntityDocs("alice", "public");
   const note = mine[0];
   if (!note) throw new Error("the note Alice wrote is not in her store");
   return note;
@@ -107,8 +113,24 @@ describe("reading the messages left on my note, on a page that has just loaded",
     // Not a failure anyone can see: the message is on the broker, Alice owns the inbox,
     // and the call returns a perfectly ordinary empty list.
     expect(await inboxSurface.readForDocument(note)).toEqual([]);
-    // …because nothing ever brought the NOTE into view. The address lives on it.
-    expect(getSyncState(note)).toBe("unknown");
+    // ...because nothing on THIS page ever brought the NOTE into view. The address lives
+    // on it.
+    //
+    // `"timed-out"`, not `"unknown"`, since 2026-09-24: a reset DISOWNS the documents it takes
+    // subscriptions away from rather than forgetting them, so `"unknown"` keeps its one
+    // meaning - "no barrier was ever expected here".
+    //
+    // CORRECTED 2026-09-24, and the reason that used to stand here was FALSE. It said neither
+    // value lets a zero-row read be called a definitive absence: `unknown` does, and
+    // deliberately - `emulated-verifier/index-deposit.ts` `noRowsMeansAbsent` returns true for
+    // it, because where there are no `State` semantics there is no barrier to have missed. The
+    // two values are not interchangeable, and which one is correct depends on the page. This
+    // particular one is a harness artefact: `reloadPage` resets the registry inside ONE process,
+    // so the note is still known to it from the first page, and `"timed-out"` - "opened here,
+    // and no barrier to show for it" - is the exact truth. A browser reload starts with an empty
+    // module, where nothing was ever opened and `"unknown"` is the exact truth instead. What
+    // this line pins in both worlds is the same thing: not `"synced"`.
+    expect(getSyncState(note)).toBe("timed-out");
   });
 
   test("the synced document-addressed read answers the message, over that same state", async () => {
@@ -141,7 +163,7 @@ describe("reading the messages left on my note, on a page that has just loaded",
     const quads: Quad[] = [];
     bootPage(quads, COLD);
     await signIn("alice");
-    const bare = await storeRegistry.createEntityDoc("public");
+    const bare = await storeRegistry.createEntityDoc(await storeRegistry.publicStore());
 
     reloadPage(quads, COLD);
     await signIn("alice");

packages/polyfill/test/connection-surfaces-failure.test.ts

@@ -137,6 +137,19 @@ function makeFakeNg(faults: Faults) {
     const query = a[1] as string;
     const anchor = a[2] as string | undefined;
     if (!anchor) return undefined;
+    // Retiring a DEPOSIT: every triple of one subject, whatever predicates it carries
+    // (`emulated-verifier/inbox-consume.removeDeposit`). Modelled rather than ignored — a
+    // fake that let this delete fall through would leave every deposit in place, and a
+    // suite asserting convergence would pass on a queue that never shrinks.
+    const delDeposit = query.match(/^\s*DELETE\s+WHERE\s*\{\s*<([^>]+)>\s+\?\w+\s+\?\w+\s*\}/);
+    if (delDeposit) {
+      const subject = delDeposit[1]!;
+      for (let i = quads.length - 1; i >= 0; i--) {
+        const q = quads[i]!;
+        if (q.s === subject) quads.splice(i, 1);
+      }
+      return undefined;
+    }
     // `INSERT DATA { GRAPH <g> { … } }` — the shape the store-ROOT pointer write uses;
     // everything else writes the anchored default graph.
     const gm = query.match(/GRAPH\s+<([^>]+)>\s*\{([\s\S]*)\}/);
@@ -204,6 +217,8 @@ function makeFakeNg(faults: Faults) {
       for (const q of quads) {
         if (q.g !== anchor) continue;
         const rec = bySubject.get(q.s) ?? {};
+        // The deposit's own subject — the key a drain names to retire it.
+        rec.d = q.s;
         if (q.p === `${INBOX}:payload`) rec.payload = q.o;
         if (q.p === `${INBOX}:ts`) rec.ts = q.o;
         if (q.p === `${INBOX}:from`) rec.from = q.o;
@@ -215,6 +230,7 @@ function makeFakeNg(faults: Faults) {
             .filter((r) => r.payload !== undefined && r.ts !== undefined)
             .map((r) => {
               const row: Record<string, { value: string }> = {
+                d: { value: r.d! },
                 payload: { value: r.payload! },
                 ts: { value: r.ts! },
               };

packages/polyfill/test/continuous-inbox-observation.test.ts

@@ -151,9 +151,9 @@ async function whileWatchingTheLog(body: () => Promise<void>): Promise<string[]>
  */
 async function bobSharesWithAlice(): Promise<{ doc: Nuri; inTransit: Quad[] }> {
   await signIn("alice");
-  await storeRegistry.createEntityDoc("protected"); // her first visit — now she exists
+  await storeRegistry.createEntityDoc(await storeRegistry.protectedStore()); // her first visit — now she exists
   await signIn("bob");
-  const doc = await storeRegistry.createEntityDoc("protected");
+  const doc = await storeRegistry.createEntityDoc(await storeRegistry.protectedStore());
   await inboxSurface.share(doc, "alice");
   // Test-side inspection only — the address is read off the wallet to say WHICH document
   // is in transit, and is never handed to an actor.
@@ -217,7 +217,7 @@ describe("an inbox opened in the middle of a session", () => {
     await signIn("alice");
     // The note and its inbox come into existence AFTER connecting, so nothing the
     // connection enumerated could have included them.
-    const note = await storeRegistry.createEntityDoc("public");
+    const note = await storeRegistry.createEntityDoc(await storeRegistry.publicStore());
     await storeRegistry.openDocumentInbox(note);
     await converge();
 
@@ -237,7 +237,7 @@ describe("an inbox opened in the middle of a session", () => {
 
   test("the messages left on it are readable, on the document its owner named", async () => {
     await signIn("alice");
-    const note = await storeRegistry.createEntityDoc("public");
+    const note = await storeRegistry.createEntityDoc(await storeRegistry.publicStore());
     await storeRegistry.openDocumentInbox(note);
     await converge();
 
@@ -325,7 +325,8 @@ describe("switching identity", () => {
     fake._deliver(inTransit);
     await converge();
 
-    // An inbox is not consumed by being ignored: connecting again drains what was left.
+    // An inbox is not consumed by being IGNORED — only by being applied. Alice never
+    // drained this one, so connecting again finds the deposit still queued.
     await signIn("alice");
     await converge();
 
@@ -348,15 +349,17 @@ describe("a deposit that cannot be applied", () => {
       await converge();
     });
 
-    expect(reported.filter((l) => /could not apply what is in this inbox/.test(l)).length)
+    expect(reported.filter((l) => /could not finish draining this inbox/.test(l)).length)
       .toBeGreaterThan(0);
     // Prefixed by the connected identity, like every other polyfill-layer line.
-    expect(reported.find((l) => /could not apply what is in this inbox/.test(l)))
+    expect(reported.find((l) => /could not finish draining this inbox/.test(l)))
       .toContain("[alice][polyfill]");
     expect(getCaps().capForHolder("alice", first.doc)).toBeUndefined();
 
     // The broker recovers. The observation is still running — one unapplicable item denies
-    // nothing — and the deposit that failed was never consumed, so both land now.
+    // nothing — and this deposit was never consumed, which since 2026-08-26 is a claim worth
+    // being precise about: what failed here is the READ, before anything could be taken out
+    // of the queue. A deposit that had been popped and whose ARM then failed would be gone.
     fake._failReadsOn.delete(aliceInbox);
     fake._deliver(second.inTransit);
     await converge();
@@ -408,7 +411,7 @@ describe("a deposit that cannot be applied", () => {
     // subscribes again as if it had never been attempted, and the initial push of that new
     // subscription finds the deposit still waiting.
     refusing = false;
-    await storeRegistry.createEntityDoc("protected");
+    await storeRegistry.createEntityDoc(await storeRegistry.protectedStore());
     await converge();
     expect(getCaps().capForHolder("alice", doc)).toBeDefined();
     expect(await documentsGivenTo("alice")).toContain(doc);
@@ -510,7 +513,7 @@ describe("listing the inboxes when one of the two registers cannot be read", ()
     await signIn("alice");
     // A document inbox: a record on the User branch of the private store, which is the
     // register the broker is about to stop answering for.
-    const note = await storeRegistry.createEntityDoc("public");
+    const note = await storeRegistry.createEntityDoc(await storeRegistry.publicStore());
     await storeRegistry.openDocumentInbox(note);
     await converge();
     const store = (await resolveAccount("alice"))?.docPrivate;
@@ -571,7 +574,7 @@ describe("listing the inboxes when one of the two registers cannot be read", ()
 
   test("still REJECTS for the caller that cannot use a partial list", async () => {
     await signIn("alice");
-    await storeRegistry.openDocumentInbox(await storeRegistry.createEntityDoc("public"));
+    await storeRegistry.openDocumentInbox(await storeRegistry.createEntityDoc(await storeRegistry.publicStore()));
     await converge();
     const store = (await resolveAccount("alice"))?.docPrivate;
     if (store === undefined) throw new Error("the fixture did not give Alice a private store");
@@ -594,12 +597,12 @@ describe("listing the inboxes when one of the two registers cannot be read", ()
  */
 async function bobSharesTwiceWithAlice(): Promise<Quad[][]> {
   await signIn("alice");
-  await storeRegistry.createEntityDoc("protected"); // her first visit — now she exists
+  await storeRegistry.createEntityDoc(await storeRegistry.protectedStore()); // her first visit — now she exists
   await signIn("bob");
   const aliceInbox = await userInbox("alice", "protected");
   const batches: Quad[][] = [];
   for (let round = 0; round < 2; round += 1) {
-    const doc = await storeRegistry.createEntityDoc("protected");
+    const doc = await storeRegistry.createEntityDoc(await storeRegistry.protectedStore());
     await inboxSurface.share(doc, "alice");
     batches.push(heldByTheBroker(aliceInbox));
   }
@@ -677,7 +680,7 @@ describe("a register that stays unreadable", () => {
       // the observation look again (`CapRegistry.onChange`).
       fake._failReadsOn.delete(shim);
       fake._failReadsOn.add(store);
-      await storeRegistry.createEntityDoc("protected");
+      await storeRegistry.createEntityDoc(await storeRegistry.protectedStore());
       await converge();
     });
     fake._failReadsOn.delete(store);