Compare commits
236 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| dd315288d9 | |||
| ec3900077b | |||
| 751d8d26e6 | |||
| 00127ac09f | |||
| f5478643be | |||
| 4c1801f6ee | |||
| 0cebf6e29a | |||
| acdaf8b246 | |||
| e0dcf93035 | |||
| 8ce9857346 | |||
| f6ed264937 | |||
| 64d3184174 | |||
| dc1536e8a1 | |||
| 63973c27e0 | |||
| 2d2f96f74b | |||
| ae44e13859 | |||
| 7da4a0ef29 | |||
| 9e00a89fe8 | |||
| a88b4497d9 | |||
| 5c50ca67c0 | |||
| 97699c232e | |||
| a4ec2546bf | |||
| 7a37e44ac0 | |||
| e07453c205 | |||
| 6c492e7734 | |||
| eb956c880d | |||
| b778fcff02 | |||
| 84699c42b5 | |||
| 98e46effc2 | |||
| d4b392a119 | |||
| c5de1cea35 | |||
| 0e2b8ba394 | |||
| 71d94b2816 | |||
| b1b099b6c7 | |||
| e86e249a5a | |||
| e16fd6a707 | |||
| 3a8941159f | |||
| 5993a8c4a2 | |||
| a7f9f4e18a | |||
| 139d21843a | |||
| 7bcb52a5fd | |||
| 4e5b703949 | |||
| 50a77e5a95 | |||
| a0bedbf696 | |||
| f417841b6a | |||
| 3aa3fb2d9b | |||
| 1991696b27 | |||
| cf0618a2ee | |||
| 7736de0d68 | |||
| 6de87a9edd | |||
| c3e07d2ce4 | |||
| 56072df2af | |||
| 226db18054 | |||
| 434838110d | |||
| dcf3814446 | |||
| 2cf42a244b | |||
| 72b4607cbe | |||
| 8338b0efd7 | |||
| 8fe8c052da | |||
| 53dc7b9c6b | |||
| 82be3684fa | |||
| de9b8a0d67 | |||
| 2da26c5c4d | |||
| ab5980c257 | |||
| 82d41b296f | |||
| d4d7a4e5e7 | |||
| 6dad05b466 | |||
| a30f1c457d | |||
| 331dd78560 | |||
| 46ec95fe6c | |||
| 52ac4d974e | |||
| 4c8efbc10a | |||
| 0043a5775d | |||
| 6b2b8ab42a | |||
| 2571f8e738 | |||
| 2e5bc100b9 | |||
| 4af0be433d | |||
| 8c890411bb | |||
| f875047099 | |||
| aecb7cf2e8 | |||
| f36ed5c164 | |||
| aa38b37f33 | |||
| 534d8f91b7 | |||
| b0eec7b4dc | |||
| 75313f75a2 | |||
| 6cd96b0182 | |||
| 5cbcabecf2 | |||
| 6c1d281755 | |||
| ee82a4a5e4 | |||
| 2dc28966c7 | |||
| 51b6278bf6 | |||
| d62d23c686 | |||
| 55c918dd4b | |||
| 5d2899157f | |||
| 6b278b404e | |||
| 83575349d7 | |||
| ddb3d0552d | |||
| 7599004fc3 | |||
| 2588dae24e | |||
| 53673a9893 | |||
| 0a2b8b1fbf | |||
| 0c21adebf2 | |||
| 05a0f7b148 | |||
| d0ea043a5b | |||
| 2aac703784 | |||
| 77e78ec81d | |||
| a5e553e65b | |||
| d440639616 | |||
| 82769c4939 | |||
| 4a4e6af337 | |||
| d0ca5c5d41 | |||
| ee9319f89b | |||
| dd874bb9c4 | |||
| 1a4857cb75 | |||
| eb8a7163a2 | |||
| 820552d263 | |||
| 88ce8d17c5 | |||
| e5d73a670b | |||
| 817f9074c4 | |||
| f6a48a4507 | |||
| abfb619c76 | |||
| 3dfc231005 | |||
| 1b4fcb567e | |||
| 0e57f20ca4 | |||
| c61b181ed8 | |||
| 6a99585efc | |||
| c507e79f8a | |||
| fafac38907 | |||
| c7c6cb96ea | |||
| 7b35300723 | |||
| 6eaff0b985 | |||
| 33212a8b00 | |||
| 520c8c59a8 | |||
| 935cce4d7b | |||
| 6dfdf2f036 | |||
| 72bb72c0b7 | |||
| bf1e16e1f3 | |||
| 1957a8fe0c | |||
| a8d53010c2 | |||
| 76ae9ffbb7 | |||
| 90712e0ad0 | |||
| 43aadbeb45 | |||
| 6138d831da | |||
| 98ee511d3a | |||
| a33fb8a214 | |||
| f6d1734679 | |||
| b50591f5bd | |||
| 07dfe68473 | |||
| 9e7aeef269 | |||
| 0607843b81 | |||
| 1271d48e9f | |||
| cf3c7c7d8b | |||
| ed0f872f5d | |||
| 1ecf511e9d | |||
| f30685bdb9 | |||
| 7062364569 | |||
| 12eba6eea6 | |||
| e32b6d04fc | |||
| 0f1e493e93 | |||
| 8c8ade7a9e | |||
| 55714d0a23 | |||
| f77317c4d1 | |||
| dbd99738f0 | |||
| cc8a95d303 | |||
| 7a4d9b492f | |||
| 218c9ab6b3 | |||
| f5a3adc385 | |||
| c5b4703687 | |||
| 7c2e8d8f1f | |||
| 16e24f67f9 | |||
| 2726f4a26f | |||
| 3be8da2178 | |||
| 3547de202c | |||
| fc3c129bd3 | |||
| 9c487b59f3 | |||
| 737729c9ce | |||
| 49b046268e | |||
| 33b96fdc8d | |||
| 7076c0cca8 | |||
| f378c71739 | |||
| 0d9e2bbe97 | |||
| cdc09a1a1d | |||
| b7dc8ca2c3 | |||
| 30f6263db5 | |||
| 44a9b6ee04 | |||
| b5f05472d9 | |||
| 0b936d2119 | |||
| c5878c6126 | |||
| 0455a408b6 | |||
| b98fcaa77d | |||
| aa6bbc436e | |||
| 0eb25286c8 | |||
| 0832338201 | |||
| 32ef756b0b | |||
| 94173fd3d3 | |||
| cb56f91b5e | |||
| 3c981ffadb | |||
| 7672915bb9 | |||
| c8d02619b1 | |||
| da6ef4b8b8 | |||
| ebf866b1f2 | |||
| 54f8389e9e | |||
| d35e735c8b | |||
| 66a40fbb89 | |||
| c42236bc00 | |||
| 3257afe8c0 | |||
| b62bfe1e63 | |||
| 107f9d1633 | |||
| e01a8dbab1 | |||
| 36c0148750 | |||
| 0b37d17c2f | |||
| cd096de2b0 | |||
| 88914f50ae | |||
| d07b3642aa | |||
| e5779ca850 | |||
| 2406afec8b | |||
| 88efe4fea4 | |||
| 07312cd0a2 | |||
| 6a3bd9c3a9 | |||
| 1de9be9167 | |||
| 4f5c3ed03b | |||
| fba0128a7e | |||
| 5a7009bd75 | |||
| 8a382f29f8 | |||
| e24a20cc46 | |||
| 33751388fe | |||
| 88f396a7ac | |||
| 9d3e2d2bfe | |||
| ae9c32e271 | |||
| 6f0d0586e2 | |||
| 0d52c82ba9 | |||
| 518292498a | |||
| b2cb774124 | |||
| 8764daff4f | |||
| 60a9fd3ede | |||
| d7e0ee6a4b |
+5
-2
@@ -2,9 +2,12 @@ node_modules/
|
||||
dist/
|
||||
*.tsbuildinfo
|
||||
.DS_Store
|
||||
bun.lock
|
||||
bun.lockb
|
||||
|
||||
# SDK e2e real-broker harness — dedicated wallet profile + bundle (never committed)
|
||||
packages/client/e2e/.playwright-profile-lib/
|
||||
packages/client/e2e/.dist/
|
||||
packages/polyfill/e2e/.dist/
|
||||
*.ngw
|
||||
|
||||
# Per-developer contract access map — canonical identities are committed, local paths are not
|
||||
.project/contracts.local.yaml
|
||||
|
||||
@@ -0,0 +1,20 @@
|
||||
<!-- generated — edit .project/concepts/*/_overview.md vocabulary blocks, then run lint --fix; do not edit this file -->
|
||||
|
||||
## Project vocabulary — canonical terms: use VERBATIM in any language, marked `like this`
|
||||
|
||||
```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)
|
||||
`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)
|
||||
|
||||
«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)
|
||||
```
|
||||
@@ -0,0 +1,57 @@
|
||||
---
|
||||
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, 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"
|
||||
vocabulary:
|
||||
- term: reference
|
||||
gloss: a NURI that names a document and grants nothing — what an application circulates
|
||||
not: [link, lien, share-link]
|
||||
see: contract_polyfill-surface
|
||||
- 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]
|
||||
see: knowledge_what-an-app-deletes-at-migration
|
||||
---
|
||||
|
||||
# app-contract — the boundary between this library and the applications that use it
|
||||
|
||||
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 `.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.
|
||||
- `.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.
|
||||
@@ -0,0 +1,28 @@
|
||||
---
|
||||
type: bug
|
||||
severity: major
|
||||
summary: An inbox watch that failed to open is re-opened only by a narrow set of later events, so a session whose activity does not produce one stays unwatched and never converges
|
||||
opened: 2026-08-17
|
||||
last_checked: 2026-08-17
|
||||
---
|
||||
|
||||
# A lost inbox watch is never retried
|
||||
|
||||
While an identity is connected, every inbox it may read is watched, and a deposit is applied as it lands. When opening one of those watches **fails** — a broker hiccup at sign-in is enough — the failure is reported and the watch is dropped. It is then re-opened only by a later event, and the list of events that qualify is narrower than it looks:
|
||||
|
||||
- creating a document,
|
||||
- opening an inbox on one,
|
||||
- a `ReadCap` arriving through an inbox **still** being watched,
|
||||
- the first read of a document in a public store.
|
||||
|
||||
**An ordinary write does not qualify.** A `sparqlUpdate` on a document the identity already owns fires none of these. So it is not only a read-only session that stays blind — it is any session whose activity stays inside what it already holds.
|
||||
|
||||
There is deliberately no polling: the deferred inbox processing states that as a design choice, and a timer here would be the wrong repair. What is missing is a recovery signal that does not depend on the identity performing a capability-bearing act.
|
||||
|
||||
**The visible consequence.** A document is shared with the affected identity while it sits connected, and nothing arrives. No error is raised, and the application sees an empty result rather than a failure — the same shape as having been given nothing at all.
|
||||
|
||||
**Workaround today:** a fresh `ensureIdentity()` re-enters and re-establishes the watches.
|
||||
|
||||
**Verifying it:** drive an identity to a state where one inbox watch fails to open, let the broker recover, deposit for that identity, and observe that nothing converges while it stays connected. A reproduction existed as a scratchpad probe during the work that found this and did not survive the session; rebuilding it from this description is the honest cost of that.
|
||||
|
||||
Predates the continuous-observation work — the earlier behaviour processed inboxes only at connection, so the same hiccup produced the same silence by a shorter route.
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
type: bug
|
||||
severity: normal
|
||||
summary: When the account record cannot be resolved, the inbox enumeration reports a COMPLETE list holding zero inboxes, so a total failure is indistinguishable from an identity that legitimately has none
|
||||
opened: 2026-08-17
|
||||
last_checked: 2026-08-17
|
||||
---
|
||||
|
||||
# An empty inbox list can mean a failure
|
||||
|
||||
Enumerating the inboxes an identity may read reports, alongside the list, whether that list is **complete** or **short** — and a shortfall is logged so a lost watch is at least visible.
|
||||
|
||||
That signal has a hole. When resolving the account record yields nothing rather than raising, the enumeration reports a list that is **complete and empty**. Every inbox is missing, including the identity's own, and nothing distinguishes it from an identity that genuinely has none yet — which is a real and ordinary state, since a first-visit identity connects with no account.
|
||||
|
||||
So the worst outcome — watching nothing at all — is reported as the most benign one. This is the family this package has closed repeatedly: **a failure wearing the shape of an absence.**
|
||||
|
||||
The fix is not to make the enumeration throw. Reaching the registers is infrastructure and may fail; what is missing is that *resolving nothing* and *there being nothing* are the same answer here, and they are not the same event.
|
||||
|
||||
**Verifying it:** make the account resolution return nothing (rather than reject) and observe that the enumeration reports a complete list with no entries, and that no shortfall is logged.
|
||||
|
||||
Related, and distinct: [[bug_a-lost-inbox-watch-is-never-retried]] — that one is about a watch that failed to open; this one is about never learning there was a watch to open.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
type: knowledge
|
||||
summary: The two fates a published symbol can have, and why the deletion list is now carried by a block and a test rather than by an import path
|
||||
---
|
||||
|
||||
# What an application deletes at migration, and what it keeps
|
||||
|
||||
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`, `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.
|
||||
|
||||
**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.
|
||||
|
||||
## Why the deletion list is not an import path any more
|
||||
|
||||
There were two entries until 2026-08-07, `.` and `./polyfill`, and the second one carried a signal worth naming: *what you import from that path is exactly what you will delete*. That was a mechanical guarantee — the compiler produced the list.
|
||||
|
||||
Merging them lost it. Nothing at an import line now distinguishes `configure`, which goes away, from `docs`, which is replaced. Three things carry it instead, and it is worth knowing that only the last two are enforced:
|
||||
|
||||
- the **`POLYFILL-ERA` block** in the package's entry module, which is the deletion list, kept short by construction;
|
||||
- **`docs/api-contract.md`**, which rules on every symbol with an epistemic label (PASSTHROUGH / LEVEL-1 SHAPE / ASSUMPTION / NO COUNTERPART) and whose export inventory is pinned by a test — so it cannot go stale quietly, which a hand-kept list would;
|
||||
- the **names themselves**, each built from the target's own vocabulary or carrying a marker saying why it exists only here, pinned by the same test.
|
||||
|
||||
The trade was deliberate and it is a real reduction in enforcement: a documentary signal where a mechanical one used to be. To verify the pinning is doing its job, look for the vocabulary test beside the package's other tests — it compares the contract's inventory against the entry's real exports, in both directions, and it caught five drifted sections the day it was extended to the rulings.
|
||||
|
||||
## The direction of travel
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,47 @@
|
||||
---
|
||||
type: knowledge
|
||||
summary: What NextGraph actually offers around inboxes — a document may be given one, nothing above the engine exposes them, and most message variants are reserved names carrying nothing
|
||||
last_checked: 2026-08-17
|
||||
---
|
||||
|
||||
# What an inbox is upstream
|
||||
|
||||
Read at the source in `nextgraph-rs`. Every claim here points at a symbol rather than a line, so it stays verifiable by `git grep` after the code moves.
|
||||
|
||||
## A document may have an inbox, and must be given one
|
||||
|
||||
`Repo` upstream **is** a document — not a store. Its `inbox` field is an `Option<PrivKey>`: at most one inbox per document, and a document has none until something creates it. The creating act is an **`AddInboxCap` commit**, verified and applied like any other — see `update_inbox_cap_v0` in the verifier and the `CommitVerifier for AddInboxCap` impl.
|
||||
|
||||
The automatic creation inside `complete_site_store` is narrower than it looks: it gives an inbox to the site's **non-private stores** only. Reading that as *"only stores can have inboxes"* is a mistake this project has now made twice — the site path is one caller of a general capability, not the rule.
|
||||
|
||||
So an inbox on an ordinary document is **aligned with the target**, not an emulation of something absent.
|
||||
|
||||
## Nothing above the engine exposes any of it
|
||||
|
||||
Run the cascade for *"post, observe, or process an inbox message"* and every level above the engine is silent. The ORM has no occurrence of `inbox` at all; neither the web API nor the wasm binding exposes one — the binding's single mention is an unused import — and there is no generic `app_request` escape hatch, since every command carries its own dedicated wrapper.
|
||||
|
||||
Anything built here therefore aligns on the **engine's model**, because levels 2 and 3 answer nothing.
|
||||
|
||||
## Most message variants are reserved names, not shapes
|
||||
|
||||
`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 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
|
||||
|
||||
`process_inbox` is `pub(crate)`, its match ends in `NotImplemented`, and its only caller is `Verifier::inbox`. There is no trait, registry or hook: **nothing outside the engine can contribute a processor** for a message type.
|
||||
|
||||
Posting is no better wired. `AppRequestCommandV0::InboxPost` is declared with its constructor and has **no handler arm** — the identifier appears nowhere else in the tree.
|
||||
|
||||
## A message waits for its recipient, and there is no delegate
|
||||
|
||||
An inbox's readers are `UserId`s, and messages queue until that user comes online. The only *"someone else runs it"* notion upstream is `Headless(Credentials)` — a server-side verifier holding a **user's own** credentials, which is that user running elsewhere, not a service delegated over someone's inbox.
|
||||
|
||||
## What follows for us
|
||||
|
||||
The **container** is settled by the target: a document may be given an inbox, one at most. Build on that freely.
|
||||
|
||||
The **content** of a deposit and **who processes it, when** have no upstream answer — the variants that would carry them are empty, and the processor set admits nothing from outside. So these are ours to choose, and a choice here is a bet that must be named as one rather than presented as alignment.
|
||||
|
||||
The standing choice, deliberate and provisional: **a deposit is a reference to a document**. It is enough for what is built on it today, and it is expected to evolve — most plausibly toward whatever shape the target eventually gives its own variants.
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
type: knowledge
|
||||
summary: What NextGraph's own IRI vocabulary is, what this package writes instead, and why scaffolding triples and durable application data must not share a namespace
|
||||
last_checked: 2026-08-21
|
||||
---
|
||||
|
||||
# What an IRI says upstream, and what ours says
|
||||
|
||||
Read at the source in `nextgraph-rs` (`213338f6`). Every claim points at a symbol or a module rather than a line, so `git grep` settles any doubt after the code moves. Two questions are answered here and they are not the same one: *what does the target's vocabulary look like?* and *what does a triple this package writes promise about its own future?*
|
||||
|
||||
## Upstream defines exactly one namespace, and it is the engine's
|
||||
|
||||
`NG_ONTOLOGY = "did:ng:x:ng#"` (`engine/verifier/src/types.rs`) is the only vocabulary namespace anything upstream declares as a constant. Three terms sit beside it — `NG_ONTOLOGY_ABOUT` (`#a`), `NG_ONTOLOGY_TITLE` (`#n`), `NG_ONTOLOGY_CLASS` (`#c`) — a document's description, its title, its class.
|
||||
|
||||
Those three are **not the whole namespace**. The same `did:ng:x:ng#` carries engine protocol state, written as inline string literals rather than named constants: `ng:site` / `ng:protected` and their `_inbox` counterparts, which `import_contact_from_qrcode` writes into a contact document (`engine/verifier/src/request_processor.rs`), and `ng:social_query_id` / `ng:social_query_forwarder` / `ng:social_query_started` / `ng:social_query_sparql`, which the social-query machinery reads and writes (`engine/verifier/src/inbox_processor.rs`). So the namespace is engine-owned in a broader sense than "document metadata": it is where the engine keeps what it needs to keep.
|
||||
|
||||
Everything else that looks like a NextGraph vocabulary lives **only in test fixtures**: `did:ng:x:contact#…`, `did:ng:x:core#…` and `did:ng:x:contact:class#…` in `sdk/rust/src/tests/big_contact_schema.json`, `contact_data.sparql`, `orm_create_patches.rs`, `orm_creation.rs`. No engine code writes them. There is no registry, no parser, no stability promise behind any of them.
|
||||
|
||||
## `x` is not an address — vocabulary and addresses share a scheme and nothing keeps them apart
|
||||
|
||||
The NURI grammar knows `o v b c d a g h j k l n s t u` and the bare `did:ng:i` — the regexes in `engine/net/src/types.rs` and every constructor of `NuriV0` (`engine/net/src/app_protocol.rs`). Neither `x` nor `z` nor `ex` is among them: a vocabulary IRI is simply a string that starts like an address and matches no rule.
|
||||
|
||||
The fixtures make the point sharper. They also use `did:ng:k:contact:tag#…` and `did:ng:k:contact:phoneNumber#…` for controlled values — and `k` **is** in the grammar, as the key half of a `:j:…:k:…` or `:c:…:k:…` pair. The letter is already spent; the vocabulary form matches nothing anyway. Nobody arbitrated that collision because nobody had to: no registry exists to arbitrate it in.
|
||||
|
||||
## `did:ng:x:core#value` is not "a field's value"
|
||||
|
||||
It is the payload slot of a **reified value node**, and reading it as a generic field accessor gets the model backwards. The shape, verifiable in `sdk/rust/src/tests/contact_data.sparql`:
|
||||
|
||||
- the entity carries `did:ng:x:contact#email` → a **value node** (its own IRI);
|
||||
- the value node carries `did:ng:x:core#value` → the literal;
|
||||
- the value node also carries the qualifiers: `core#source` (where this value came from), `core#type` (an IRI such as `did:ng:k:contact:phoneNumber#home`), `core#hidden`, `core#selected`.
|
||||
|
||||
**The field name lives in the parent's predicate**, never in the value node. And the payload slot splits by RDF term kind rather than by field: `core#value` holds a literal, `core#valueDateTime` / `core#valueDate` a typed date, `core#valueIRI` an IRI. `:class#` (as in `did:ng:x:contact:class#SocialContact`) is a convention observed in exactly one vocabulary, the contact fixture.
|
||||
|
||||
## There is no extension convention, and nothing upstream filters or reserves
|
||||
|
||||
No reserved segment, no procedure to claim one, no prohibition — nowhere in the tree. What the examples do instead is either `PREFIX ex: <did:ng:z:>` (`sdk/js/orm/src/tests/shapes/shex/testShape.shex`, the shex under `sdk/js/examples/`, `sdk/rust/src/tests/video_schema.json`) or plain web ontologies — vcard, foaf, schema.org, which the engine itself uses for a contact's name and email. One example spells `did:ng:n:g:x:social:contact#` (`sdk/js/examples/react-ldo/src/.shapes/contact.shex` and the generated files beside it), an older form matching neither the fixtures nor the grammar: the scheme is **not self-consistent across the tree**.
|
||||
|
||||
**Nothing upstream filters or reserves a namespace.** The engine stores and returns arbitrary IRIs. The single prefix-sensitive path is in `engine/verifier/src/commits/transaction.rs`, which matches `NG_ONTOLOGY_ABOUT` / `NG_ONTOLOGY_TITLE` among a commit's inserts and removes only to push a tab-info update when a title or description changed — and only for updates whose `branch_type.is_header()`. The triples stay in the store and stay queryable; nothing is hidden from a reader. **Separation upstream is by BRANCH, not by prefix** — a header branch is a different CRDT with its own topic, which is why upstream needs no reserved prefix at all.
|
||||
|
||||
The `urn:` strings that appear upstream are unit-test fixtures and nothing else: `urn:g`, `urn:child:dg`, `urn:child:sg` inside `#[cfg(test)] mod tests` in `engine/verifier/src/orm/graph/utils.rs`, and `urn:test:…` under `sdk/rust/src/tests/`. They are not vocabulary and imply nothing.
|
||||
|
||||
## What this package writes
|
||||
|
||||
**`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 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.
|
||||
|
||||
**The index arm writes another package's namespace.** `urn:ng-helpers:index:field` and `urn:ng-helpers:index:value` (`packages/polyfill/src/emulated-verifier/index-deposit.ts`) are the IRIs `@ng-helpers/indexing` already writes, kept letter for letter because renaming them would orphan every index already written. It is odd for this package to write a namespace it does not own. Recorded here as an oddity; it is not this leaf's to fix.
|
||||
|
||||
## Two kinds of triple, two fates — the distinction this leaf exists for
|
||||
|
||||
**Scaffolding** is what this package writes to emulate what the engine will do: the branch compartments, the deposit envelope. It is transitory. It disappears at migration together with the read filter that hides it, and being invisible to a caller is exactly right for it. `urn:ng-eventually:` is its home.
|
||||
|
||||
**Durable application data** is what an application means: an index entry written into a public document, read by third parties, which must **survive** migration. It is deliberately *not* under `urn:ng-eventually:` — which is precisely why the index IRIs pass the read filter and reach the caller.
|
||||
|
||||
Naming them alike would say the wrong thing about both: it would promise the scaffolding a future it does not have, and it would put the durable data one widened filter away from disappearing. The test at every new IRI: **does this triple die at migration, or does it have to outlive it?** Scaffolding goes under `urn:ng-eventually:`; anything an application or a third party reads must not. This is the triple-level twin of [[knowledge_what-an-app-deletes-at-migration]] — there, the two fates of a published symbol; here, the two fates of a written triple.
|
||||
|
||||
## What is settled, and what is a bet
|
||||
|
||||
**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* (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 the no-divergence rule (`.project/rules/nextgraph/no-divergence-from-nextgraph.md`) names as the most dangerous kind of all.
|
||||
@@ -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`.
|
||||
@@ -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.
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
type: knowledge
|
||||
summary: Who does what along a deposit's path — the application deposits, this package DISPATCHES on what a deposit declares itself to be and applies it arm by arm, and upstream none of it is reachable yet
|
||||
last_checked: 2026-08-21
|
||||
---
|
||||
|
||||
# Who processes an inbox
|
||||
|
||||
[[knowledge_what-an-inbox-is-upstream]] settles what the target *offers*: a document may be given an inbox, nothing above the engine exposes one, and the processor set admits nothing from outside. It says nothing about who does the work **here**. That is this leaf.
|
||||
|
||||
The question is hard to answer out loud — *"does the polyfill process the inbox automatically?"* took one agent a long exchange to fail at — because **processing means a different thing at each layer**. Naming the actor first makes it easy. Everything below is read off the code; symbols are cited so `git grep` settles any doubt.
|
||||
|
||||
## The application
|
||||
|
||||
It **deposits** by naming a document (`inbox.postToDocument`) or a person (`inbox.share`), **reads its own** with `inbox.readForDocument` / `readSyncedForDocument`, and may **watch** one with `inbox.watch`.
|
||||
|
||||
What it never does: **process an inbox so that a `ReadCap` sent to it arrives**. `inbox.processInbox` is published, but no application has to call it — connecting drains, and every arrival afterwards is applied. It never resolves someone else's inbox address (the only published call that returns one is `storeRegistry.openDocumentInbox`, on a document it owns), and it has no way to reach, hurry or disable the deferred stand-in below.
|
||||
|
||||
## `@ng-eventually/polyfill`
|
||||
|
||||
**At connection** — `emulated-verifier/connect.ts`, `connectedUser`: restore every durable register, then `processInbox` on each inbox this identity holds, then start the continuous observation. Failing to apply one queue is reported and denies nobody their session; failing to *reach* the queues rejects.
|
||||
|
||||
**Continuously, while the identity is connected** — `emulated-verifier/inbox-observer.ts`, `startObservingInboxes`, whose only caller is `connectedUser`: one subscription per inbox, and every push runs `processInbox` on it. *Which* inboxes exist is itself subscribed to, on two channels that do not overlap: the **register** (the User branch of the private store, where `openDocumentInbox` appends its record — so an inbox opened mid-session is picked up) and **what this identity holds** (`CapRegistry.onChange` — which is what makes a person's *first* session watched at all, since provisioning is lazy and they connect owning nothing). Push-driven throughout; it never polls. It stops on identity change, on disconnection, and on `configure` / `resetConfig` (`stopObservingInboxes`, called only from `shared-wallet/bootstrap`). Every step re-checks its holder, so a run that outlives its identity abandons rather than file into the wrong ring.
|
||||
|
||||
### Applying is a DISPATCH — one arm per declared type
|
||||
|
||||
`emulated-verifier/inbox-dispatch.ts`, `applyDeposit`. It is a `switch` over what a deposit DECLARES itself to be (`kindOf`), and the shape is the target's own: `Verifier::process_inbox(msg, content)` is literally `match content { … }`, one arm per `InboxMsgContent` variant, ending `_ => Err(VerifierError::NotImplemented)` (`engine/verifier/src/inbox_processor.rs`).
|
||||
|
||||
**What an arm owes**, read off upstream's clearest arm (`InboxMsgContent::ContactDetails`): **validate** the envelope — a missing `from_inbox` is `InvalidInboxPost`, a hard failure and not a skip; **build** its addresses from the typed content; **read** the recipient's own store to see whether the thing is already there (a SPARQL `ASK`); **decide idempotently** — `ContactAlreadyExists` rather than a duplicate; and only then **write**. An arm is a real program, not a branch.
|
||||
|
||||
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. 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.)*
|
||||
|
||||
**A kind with no arm says so.** A payload declaring itself in this package's reserved `urn:ng-eventually:inbox:` namespace for a variant nothing here applies is REPORTED — upstream's `NotImplemented`, which is an answer. Until 2026-08-21 it was read, counted, and produced nothing at all: no effect and no reported failure, the "failure disguised as an absence" this package has closed repeatedly elsewhere.
|
||||
|
||||
**Consumer data is not a variant.** A payload that declares no kind of this package's is claimed by no arm and nothing is reported about it: it is not an unapplied message, it is not a message. That is why the RESERVED NAMESPACE is the discriminator and the mere presence of a `kind` field is not — `{ kind: "join" }` is a consumer's word for a consumer's message, and it stays one.
|
||||
|
||||
**What still reaches the caller.** Only a `ReadCap` is withheld: an application must never handle one. Everything else `read` found is returned unchanged, including the payloads an arm applies — a `reference` is public information, so withholding it would buy nothing. Two senses of *applied* stay apart: `read` learns a `ReadCap` **in memory, for this session**; only `processInbox` makes it **durable** and runs the dispatch. `inbox.watch` re-reads on every push, so it absorbs and files nothing.
|
||||
|
||||
**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. 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.
|
||||
|
||||
**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
|
||||
|
||||
The **broker** routes a sealed message by inbox key (`inboxes: PubKey → RepoId`, `engine/verifier/src/verifier.rs`) and queues it while the recipient is away. The **recipient's own verifier** applies it inline as it arrives — `LocalBrokerMessage::Inbox` → `session.verifier.inbox(&msg, from_queue)` in `sdk/rust/src/local_broker.rs`; `from_queue` distinguishes the backlog handed over at connection from the messages that follow, and **both go through the same door**, which is why the continuous regime above is the rule and the connection drain the special case.
|
||||
|
||||
And **none of it is reachable from JS**: the processor set is closed, the variants that would carry a payload carry nothing, and the post command has no handler arm — all in [[knowledge_what-an-inbox-is-upstream]]. Every actor above except the broker and that verifier is therefore ours, emulating one thing: a session applying its own inbox, continuously.
|
||||
@@ -0,0 +1,440 @@
|
||||
---
|
||||
type: contract
|
||||
summary: The API @ng-eventually/polyfill exposes to an application — signatures, guaranteed behaviour, and what it does not offer
|
||||
---
|
||||
|
||||
# contract_polyfill-surface — `@ng-eventually/polyfill`
|
||||
|
||||
## Scope
|
||||
|
||||
This package is a polyfill of NextGraph's SDK.
|
||||
|
||||
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.
|
||||
|
||||
**Obtaining it.** This package is not published to a public registry, and it is not distributed as built output: its published entry point is TypeScript source, so whatever builds the application is what compiles it, and a toolchain that accepts only JavaScript cannot consume it as it stands. By which channel the source reaches a given application is agreed with that application rather than fixed here; what this contract fixes is the version you pin and the rules below.
|
||||
|
||||
## Surface
|
||||
|
||||
Full typed shape: the package's `types` entry, `@ng-eventually/polyfill`. A type is published only when a published signature uses it. The load-bearing signatures:
|
||||
|
||||
```ts
|
||||
// ── bootstrap ────────────────────────────────────────────────────────────
|
||||
export function configure(c: EventuallyConfig): void;
|
||||
export interface EventuallyConfig {
|
||||
ng: NgLike; // the `ng` object from @ng-org/web
|
||||
// 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;
|
||||
initNg?: (...args: any[]) => any;
|
||||
}
|
||||
|
||||
// ── identity — one await before the application renders ──────────────────
|
||||
export async function ensureIdentity(): Promise<PrincipalId>; // returns who you are
|
||||
|
||||
// ── addressing ───────────────────────────────────────────────────────────
|
||||
export type Nuri = `did:ng:${string}`;
|
||||
export type NuriLike = Nuri | string;
|
||||
// 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
|
||||
privateStore(): Promise<Nuri>;
|
||||
protectedStore(): Promise<Nuri>;
|
||||
publicStore(): Promise<Nuri>;
|
||||
createEntityDoc(store?: NuriLike): Promise<Nuri>;
|
||||
openDocumentInbox(doc: NuriLike): Promise<Nuri>;
|
||||
};
|
||||
|
||||
// ── reading ──────────────────────────────────────────────────────────────
|
||||
// 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; // ask again now; never polls
|
||||
}
|
||||
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: {
|
||||
// `sessionId` is `string | number` — upstream's own declared type (`Session.session_id`).
|
||||
// It is RELAYED, never converted: the wasm side deserializes a `u64`, and stringifying it
|
||||
// fails for real (`Deserialization error of session_id JsValue("1")`).
|
||||
docCreate(sessionId: string | number, crdt: string, cls: string, dest: string, store?: unknown): Promise<Nuri>;
|
||||
sparqlQuery(sessionId: string | number, query: string, base?: string, anchor?: NuriLike, label?: string): Promise<unknown>;
|
||||
// Returns the commits the update produced, as upstream does (it typed this `void` until
|
||||
// 2026-08-14 while already relaying the value). A caller that ignores it is unaffected.
|
||||
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
|
||||
post(targetInbox: NuriLike, opts: PostOptions): Promise<void>;
|
||||
postToDocument(doc: NuriLike, opts: PostOptions): Promise<void>;
|
||||
read(targetInbox: NuriLike): Promise<Deposit[]>; // only your own
|
||||
readForDocument(doc: NuriLike): Promise<Deposit[]>;
|
||||
readSynced(targetInbox: NuriLike): Promise<Deposit[]>;
|
||||
readSyncedForDocument(doc: NuriLike): Promise<Deposit[]>;
|
||||
processInbox(targetInbox: NuriLike): Promise<Deposit[]>;
|
||||
watch(targetInbox: NuriLike, onDeposits: (d: Deposit[]) => void): () => void;
|
||||
// `materialize` (a second published name for `read`) was REMOVED on 2026-08-14 —
|
||||
// an alias with no call site, and no counterpart upstream. Use `read`.
|
||||
};
|
||||
export interface Deposit { from: PrincipalId | null; payload: unknown; ts: number }
|
||||
|
||||
// ── 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`), 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; // 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 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()`.
|
||||
|
||||
**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.
|
||||
|
||||
**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.
|
||||
|
||||
**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.
|
||||
|
||||
`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.
|
||||
|
||||
`inbox.post` refuses a target that is not an inbox; to reach a document's owner, use `inbox.postToDocument(doc, …)`. Anyone may deposit into an inbox; only its owner reads it.
|
||||
|
||||
**You never resolve an inbox address, on either side.** You deposit by naming a document (`inbox.postToDocument`), and you read what was left on your own by naming it too — `inbox.readForDocument(doc)` at any time, or `inbox.readSyncedForDocument(doc)` on a page that has just loaded. The second is the one to call when an empty answer has to MEAN empty: a session that has just loaded has synced neither the document nor its inbox, and an unsynced read of either comes back empty with no error — so the ungated form can answer `[]` for a document whose inbox holds messages. `readSyncedForDocument` waits for both before answering. `inbox.readSynced` is the same guarantee on an inbox you already hold the address of, which no application does: it takes an address, so nothing here hands you one.
|
||||
|
||||
`ensureIdentity()` settles the identity, completes the connection work it starts, and returns the identity. It takes no identifier, and no other call takes one.
|
||||
|
||||
It resolves **only once that work has actually completed**: if what was shared with you could not be restored, it throws instead of returning, and a rejected call must not be rendered past — the interface would show an empty account rather than an empty screen. A single queue that could not be drained is reported and does not reject: reaching your queues is infrastructure and must succeed, applying one deposit is data and must never cost you the session. So a resolved call means your own capabilities are restored; it does not promise that every deposit waiting for you has been applied, and those that were not stay in their queue.
|
||||
|
||||
`ensureIdentity()` mounts a full-screen barrier on every top-level load, and takes it down itself — past the broker round-trip it stays down, provided the identifier reached the other side. A person who comes back to the page from that round-trip finds the barrier live again, prefilled, and confirming it hands the page over a second time. The application's own page is never reloaded and nothing outside the barrier is touched.
|
||||
|
||||
**What decides which identity you get.** No call takes an identifier — not `configure`, not `init`, not `ensureIdentity` — so an application never chooses one, never keeps one, and never hands one over. It is settled once per page load, from the page itself, and the answer depends on which side of the broker round-trip is asking:
|
||||
|
||||
- **Before the round-trip, on your own top-level page — the barrier decides.** Whatever is already known fills the field, and the person may change it; the identity is the value they confirm. Confirming publishes that value into the address bar as `?ng-id=` and records it in this browser.
|
||||
- **After the round-trip, on the page the broker loads back — `?ng-id=` decides**, and the barrier stays down. The parameter also wins over anything the browser remembers, on either side: it is read first, and reading it replaces what was remembered. Arrive with neither — a URL that dropped the parameter, and a partition that remembers nothing — and the barrier asks on that side too.
|
||||
- **Failing both — whatever this browsing context last recorded.** This is the only path on which an identity is adopted with nobody confirming it. If the address bar lost `?ng-id=` while a *different* identifier was on record here, that different identity is adopted, and nothing is raised anywhere; if nothing was on record either, the barrier asks again on that side too.
|
||||
|
||||
**`?ng-id=` exists because it is the only thing that crosses.** Your page before the round-trip and your page after it sit in two separate storage partitions — nothing the browser remembers on one side is visible on the other, and the address bar is the sole channel between them. The package writes the parameter itself, without navigating. **An application that owns its URL must let it survive**: a router that drops query parameters it does not know, or a redirect that rebuilds the URL, sends the round-trip off without the identifier, and the consequence is the silent mis-identification above rather than an error. In a context that can neither write the address bar nor use storage, the barrier simply asks on both sides.
|
||||
|
||||
**Being remembered is a prefill, never a decision.** A top-level reload asks again every time, with the field already filled — one click, no typing. A remembered identifier is therefore not a signed-in state, and two tabs, two browsers or two devices do not share one: each keeps its own record, and only a URL carrying `?ng-id=` puts a second context under the same identity.
|
||||
|
||||
**The session is the package's, not yours.** You never build one, and no call takes one. Call this package's `init` (not the one you passed to `configure`): it captures the session the SDK delivers to `init`'s callback and keeps it, then calls your callback with that same event untouched — so an application that wants the `session_id` for the `docs` primitives reads it there, and one that does not may pass no callback at all. Identity normalisation is the package's too: `@Alice`, `alice ` and `ALICE` are one person.
|
||||
|
||||
Where a call must first find out whether something already exists — a document's record in its store, a user's inbox — it throws when it could not find out, instead of proceeding as though the answer were "nothing". So `createEntityDoc` throws if the document cannot be recorded in its store, and resolving an inbox throws rather than handing back a second one. **A rejection means "unknown", never "absent"** — retry it or surface it, but do not read it as an empty result.
|
||||
|
||||
**`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.** `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.
|
||||
|
||||
**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.
|
||||
|
||||
**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.
|
||||
|
||||
**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.
|
||||
|
||||
## Non-guarantees
|
||||
|
||||
**No display name.** `ensureIdentity()` returns an opaque identifier: do not parse it, split it, or render it as a readable name.
|
||||
|
||||
**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.
|
||||
|
||||
**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.
|
||||
|
||||
**Nothing per reader on a document in a public store.** No grant, no revocation, no audience list.
|
||||
|
||||
**No delegated writing.** A received key never grants a write, and no call adds a writer to a document.
|
||||
|
||||
**No mailbox model.** Do not build on the raw deposit list.
|
||||
|
||||
**No cross-broker reference.** A returned reference resolves for users of the same broker.
|
||||
|
||||
**`openDocumentInbox` does not coalesce across PAGES.** Two tabs — or two sessions of the same person — that open the same document's inbox in the same moment can each create one, and the document is left with two: its owner drains one while deposits arrive in the other. Nothing raises, nothing reports it, and neither page can detect it afterwards. It is not an oversight to be patched later: a branch MERGES records rather than refusing the second, so there is no "create only if absent" to build the guarantee on, and the address a depositor reads is a separate record from the one the owner resolves — so the two cannot even be made to agree on which of the pair won. Open a document's inbox from one place: the page that creates the document, or one call the rest of the interface waits on.
|
||||
|
||||
**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`, 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`, `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.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.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.
|
||||
|
||||
**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.
|
||||
@@ -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.
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
type: overview
|
||||
summary: What each end-to-end suite judges, the shortcut that kept two defects invisible, and the failure mode that is not ours to fix
|
||||
triggers:
|
||||
keywords: [e2e, harness, playwright, chromium, journey, suite, profile, broker page, notebook, wallet profile, ng-e2e-helpers]
|
||||
paths:
|
||||
- "packages/polyfill/e2e/**"
|
||||
- "packages/ng-e2e-helpers/**"
|
||||
vocabulary:
|
||||
- term: journey
|
||||
gloss: one named end-to-end story in the applicative suite, reported pass or fail as a whole
|
||||
not: [scenario, test case, spec]
|
||||
- term: batch
|
||||
gloss: one run of a suite, which mints its own physical user and discards the previous one
|
||||
not: [session, campaign]
|
||||
---
|
||||
|
||||
# e2e-harness — the suites, and what they can and cannot tell you
|
||||
|
||||
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.
|
||||
|
||||
The generic half of that machinery is a package of its own, `ng-e2e-helpers`, and this repo **publishes** it: a NextGraph application in any repository pulls `ng-e2e-helpers/contract_ng-e2e-helpers` and declares back what it consumes. Our own suites are one of those consumers, and declare it in the same folder — same pair, no boundary to cross.
|
||||
|
||||
## Read first
|
||||
|
||||
- `ng-e2e-helpers/contract_ng-e2e-helpers` — the engagement, written from the caller's point of view.
|
||||
- `ng-e2e-helpers/usage_polyfill-e2e` — what our own suites actually call, and where the fit still costs them code.
|
||||
- `knowledge_what-each-suite-judges` — which suite answers which question.
|
||||
- `rule_never-shortcut-the-sign-in` — the shortcut that hid a 404 and a regression at once.
|
||||
- `caveat_a-dropped-pipe-kills-a-run` — the failure mode that is not ours.
|
||||
@@ -0,0 +1,27 @@
|
||||
---
|
||||
type: caveat
|
||||
summary: Chromium's control pipe drops without Playwright emitting close or disconnected, so a run dies mid-flight — it looks like a product defect and is not one
|
||||
last_checked: 2026-08-11
|
||||
---
|
||||
|
||||
# A run can die from a dropped pipe, and it is not the product
|
||||
|
||||
Chromium's devtools pipe sometimes drops mid-run. It logs a terminated-pipe message and exits cleanly, and **Playwright emits neither `close` nor `disconnected`** — observed four times out of four. From the client's side the browser simply stops answering.
|
||||
|
||||
Before waits were bounded this was fatal in a specific way: the suite blocked in its own teardown, so it printed **neither its summary nor the failure already on its way out**. Hours went into diagnosing silence. Every wait is now bounded and names what it was waiting for, so a lost browser costs seconds and a report.
|
||||
|
||||
**How to recognize it.** The run dies without a coherent failure, or several unrelated interactions time out at once, or the summary is missing entirely. **Do not read a named deadline as a verdict on the transport.** A deadline says only that something did not happen in time; it never says why, and reaching for the environment is the comfortable answer because it absolves the code.
|
||||
|
||||
That reflex cost a full day here. Every actor sign-in was timing out, and it was blamed on the broker and on a churning host for hours. The real cause was one line of ours: the harness looked for the application frame with a substring match on the URL, and the broker's own login page carries the application address in its query string — so it matched the login page from the first instant, skipped the wallet click and the password as "already logged in", and handed back the wrong frame. What made it intermittent was a 2-second visibility probe on a button that painted in 1.0 to 1.6 seconds. All of it was readable in the code the whole time.
|
||||
|
||||
**It is not ours to fix.** It is not caused by how a child process is spawned, nor by a leftover holding the profile, nor by overlapping launches — all three were probed and ruled out. It looks like Playwright losing its file descriptors without telling its client. Worth reporting upstream.
|
||||
|
||||
## The host can be the cause too
|
||||
|
||||
A machine that reconfigures its network — a container in a crash-restart loop cycling its virtual interface, for instance — makes the applicative suite unreliable. The browser answers with a network-changed error, broker sockets fail, and every failure looks like a different product bug.
|
||||
|
||||
This has happened here: seven failures out of ten runs in one afternoon, all transport, none product. The check costs seconds — watch for repeated link events, and look for a container restarting.
|
||||
|
||||
But do not conclude the suite is unmeasurable: under that same churn it also ran green four times in a row. A red run under a moving network proves nothing, and neither does a green one. What decides is the SHAPE of the failure — a named deadline on a browser or broker operation points at the transport, a failed assertion carrying an unexpected value points at the code — and repetition: three consecutive green runs, or a failure that reproduces.
|
||||
|
||||
**The discipline that follows.** Read your own harness first, and only call it transport once you can name the mechanism. A suite that genuinely fails for transport reasons has measured nothing. Do not read it as a red baseline, do not chase it as a regression, and do not commit against it. Re-run it — and if the environment is known to be moving, say so alongside the result instead of letting a single run stand as the verdict.
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
type: knowledge
|
||||
summary: Which suite answers which question, what a batch costs, and why two runs must never overlap
|
||||
---
|
||||
|
||||
# What each suite judges
|
||||
|
||||
**The polyfill suite** exercises the published surface against the real broker: capabilities, reads, inboxes, reactivity. It is the one that judges whether the emulation behaves like the target.
|
||||
|
||||
**The applicative suite** drives the example application through a browser, as a person would — several identities, several pages, assertions on what is on screen rather than on what the library returns. It judges whether an application built on this package actually works, including the sign-in a person really performs.
|
||||
|
||||
**The reactivity suite** isolates document subscription.
|
||||
|
||||
**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
|
||||
|
||||
Every run mints its own physical user by driving the wallet application's real interface, then discards the previous one. That is deliberate — identities must not leak between runs — and it puts a floor under every run that no test filter can remove.
|
||||
|
||||
Consequence worth knowing before optimizing anything: the setup runs before any `journey`, so filtering journeys saves journey time only — the floor stays.
|
||||
|
||||
## Two runs may overlap — and that was not free
|
||||
|
||||
They once could not: the profile was a single shared directory, and a run starting while another was alive destroyed it, which then failed in a way that read as a product defect. Several measurements were lost to it.
|
||||
|
||||
Now each run gets its own profile directory and kills the browser holding it when it ends, so concurrent runs — including a consuming application's suite, from its own checkout — are independent by construction. A lock once guarded the shared directory; it treated the symptom, and removing the sharing removed the need. Prefer that shape whenever two runs contend: make the contended thing per-run rather than serialising access to it.
|
||||
|
||||
## A bound must be larger than the sum of what it encloses
|
||||
|
||||
An enclosing deadline shorter than its own steps can only ever fire first, so every failure underneath it reports the *enclosing* name and none of them can name a cause. The sign-in bound sat at 180 s over steps totalling 270 s, and for days every failure said the same four words while the real step stayed anonymous. Days went into looking for a cause the harness was structurally incapable of reporting.
|
||||
|
||||
So: compute an enclosing bound from its parts rather than picking a number, and size every leaf bound from a **measured** healthy duration recorded beside it. A bare figure teaches nothing and rots without anyone noticing; a figure with its measurement lets the next reader tell a generous bound from a tight one.
|
||||
|
||||
## What a run must report whatever happens
|
||||
|
||||
Declare the journeys and their checks before anything can fail, so a run reports the same number of rows every time. When the count itself moves with the failure — journeys dying and taking their unreported checks with them — two runs are no longer comparable, and a shrinking total reads like a smaller problem instead of a bigger one.
|
||||
|
||||
The related trap that made it self-perpetuating: discarding the profile was once conditioned on a marker written at the *end* of a batch, so a run killed before writing it left a profile the next run happily reused — and inherited its breakage. Discarding now keys on the profile itself.
|
||||
@@ -0,0 +1,166 @@
|
||||
---
|
||||
type: contract
|
||||
summary: The machinery ng-e2e-helpers offers a NextGraph application's end-to-end suite — wallets, the broker crossing, per-run profiles, bounds, and a bounded report
|
||||
---
|
||||
|
||||
# contract_ng-e2e-helpers — `ng-e2e-helpers`
|
||||
|
||||
## Scope
|
||||
|
||||
This package is the end-to-end testing machinery a NextGraph application needs to get a real person into itself: minting a wallet by driving the wallet application, crossing the broker, and coming back inside the iframe the application runs in — plus per-run browser profiles, bounds that turn a hang into a named failure, and a run report whose size does not depend on what failed.
|
||||
|
||||
It covers **only what is generic to NextGraph**. It knows nothing about any one application, and nothing about any compatibility layer: an application calling the NextGraph SDK directly is its intended consumer. What is specific to your repository — the page that carries your application, how you build your bundle, which journeys you run — is yours to write, and this package deliberately offers no place to put it.
|
||||
|
||||
It is not a test runner, not an assertion library, and not a fixture system. You keep your own runner and your own `main()`.
|
||||
|
||||
### Deployment requirements
|
||||
|
||||
`playwright` and `@ng-org/web` are **peer dependencies**, and you own both versions: browser binaries have to match the driver, and the SDK the export page opens a session with must be the one your application and your broker agree on. Import the browser types from the helpers that return them rather than from `playwright` directly — a second resolution of the driver produces a structurally different `BrowserContext`, and a context you opened then cannot be handed back to the helper that opens contexts.
|
||||
|
||||
A machine running this needs a real Chromium, network reach to the wallet application and to the broker, and a writable temporary directory for the per-run profiles.
|
||||
|
||||
## Surface
|
||||
|
||||
Full typed shape: the package's `types` entry, `ng-e2e-helpers`. It also ships one executable, `ng-mint-wallet`, for provisioning a deployment's wallet file outside any run. `BrowserContext`, `Frame`, and `Page` — every Playwright type this surface mentions, no more — are re-exported as types from the same entry point, so a consumer can type its own helper functions against these signatures without a second, independently-versioned import of `playwright`. The load-bearing signatures:
|
||||
|
||||
```ts
|
||||
// ── bounds: a hang becomes a named failure ───────────────────────────────────
|
||||
export function within<T>(what: string, ms: number, task: () => Promise<T>): Promise<T>;
|
||||
export class DeadlineExceeded extends Error {} // thrown by `within` — names `what`
|
||||
export class BrowserGone extends Error {} // the browser died; not the task's fault
|
||||
export function enclosingBound(steps: readonly number[], margin: number): number;
|
||||
export function closeQuietly(what: string, close: () => Promise<unknown>): Promise<void>;
|
||||
export function armSuiteDeadline(suite: string, ms: number, thenReport?: () => void): void;
|
||||
export function browserLost(reason: string): void; // declare it, once
|
||||
export function lossDeclared(): string | null; // has it been declared?
|
||||
export function firstLine(e: unknown): string;
|
||||
export const CLOSE_MS: number, CONTEXT_ACTION_MS: number, CONTEXT_NAVIGATION_MS: number;
|
||||
|
||||
// ── measurement: how a bound gets its number ─────────────────────────────────
|
||||
export function measured<T>(what: string, bound: number, task: (ms: number) => Promise<T>): Promise<T>;
|
||||
export function record(what: string, ms: number, ok: boolean, bound: number): void;
|
||||
export function timingsWanted(): boolean; // true under E2E_TIMINGS=1
|
||||
export function printTimings(): void;
|
||||
|
||||
// ── browser and profiles: one run owns its own ───────────────────────────────
|
||||
export interface RunProfile { readonly dir: string; readonly purpose: string; discard(): void }
|
||||
export function newRunProfile(purpose: string): RunProfile;
|
||||
export function isAlive(pid: number): boolean;
|
||||
export function launchWatchedContext(label: string, dir: string): Promise<BrowserContext>;
|
||||
export function closeContext(label: string, ctx: BrowserContext): Promise<void>;
|
||||
export function newPage(label: string, ctx: BrowserContext): Promise<Page>;
|
||||
export const LAUNCH_MS: number, NEW_PAGE_MS: number;
|
||||
|
||||
// ── the wallet: minted, carried, imported ────────────────────────────────────
|
||||
export interface WalletCredentials { readonly name: string; readonly password: string }
|
||||
export const DEFAULT_WALLET_NAME: string; // the password never has a default
|
||||
export function mintWalletProfile(purpose: string, c: WalletCredentials): Promise<RunProfile>;
|
||||
export function mintWalletProfileKeepingContext(
|
||||
purpose: string, c: WalletCredentials): Promise<{ ctx: BrowserContext; profile: RunProfile }>;
|
||||
export function mintWalletBytes(password: string, name?: string): Promise<Uint8Array>;
|
||||
export function createWalletInContext(ctx: BrowserContext, c: WalletCredentials): Promise<void>;
|
||||
export function emptyProfileContext(
|
||||
purpose: string): Promise<{ ctx: BrowserContext; profile: RunProfile }>;
|
||||
export function exportWalletBytes(ctx: BrowserContext, walletPassword: string): Promise<Uint8Array>;
|
||||
export function exportWalletFile(ctx: BrowserContext, ngwPath: string, pw: string): Promise<number>;
|
||||
export function importWalletFile(page: Page, ngwPath: string, password: string): Promise<void>;
|
||||
|
||||
// ── the broker crossing ──────────────────────────────────────────────────────
|
||||
export function setupBrokerPage(page: Page, appUrl: string, walletPassword: string): Promise<Frame>;
|
||||
export function completeBrokerLogin(page: Page, appUrl: string, pw: string): Promise<Frame>;
|
||||
export const BROKER_LOGIN_MS: number, BROKER_ROUND_TRIP_MS: number;
|
||||
export function brokerRedirectFor(appUrl: string): string;
|
||||
export const BROKER_SCREENS: readonly BrokerScreenSpec[]; // the screens, in test order
|
||||
export const WALLET_APP, WALLET_CREATION, WALLET_IMPORT; // the wallet application's own pages
|
||||
export type BrokerScreen = "choose-broker" | "login-offered" | "wallet-list"
|
||||
| "password" | "working" | "error";
|
||||
export type { BrokerScreenSpec, ScreenSignature, ScreenResponse, TextPattern };
|
||||
|
||||
// ── serving your application to the browser ──────────────────────────────────
|
||||
export function serveOnEphemeralPort(
|
||||
handler: (req: IncomingMessage, res: ServerResponse) => void,
|
||||
): Promise<{ url: string; close: () => void }>;
|
||||
|
||||
// ── failures that are not the application's ──────────────────────────────────
|
||||
export function browserTrouble(label: string, ctx: BrowserContext): Promise<string | null>;
|
||||
export function frameTrouble(id: string, page: Page, frame: Frame, marker: string): Promise<string | null>;
|
||||
export const BROWSER_PROBE_MS: number, FRAME_PROBE_MS: number;
|
||||
|
||||
// ── the report ───────────────────────────────────────────────────────────────
|
||||
export interface JourneyDeclaration { readonly name: string; readonly checks: readonly string[] }
|
||||
export type Prerequisite = () => Promise<string | null> | (string | null);
|
||||
export interface JourneySpec {
|
||||
readonly name: string; // must be a declared journey
|
||||
readonly needs?: readonly Prerequisite[]; // each answers null, or why it cannot start
|
||||
readonly run: () => Promise<void>;
|
||||
}
|
||||
export interface SuiteOptions {
|
||||
readonly label: string;
|
||||
readonly journeys: readonly JourneyDeclaration[];
|
||||
readonly journeyBound: number;
|
||||
readonly diagnose?: () => Promise<string | null>;
|
||||
}
|
||||
export interface SuiteReport {
|
||||
check(name: string, ok: boolean, detail?: string): void; // throws on an undeclared name
|
||||
journey(spec: JourneySpec): Promise<void>;
|
||||
finish(fatal: string | null): never; // prints, then leaves
|
||||
}
|
||||
export function declareSuite(options: SuiteOptions): SuiteReport;
|
||||
|
||||
// ── playwright types this surface mentions, re-exported so a second import isn't needed ─────
|
||||
export type { BrowserContext, Frame, Page };
|
||||
```
|
||||
|
||||
## Guarantees
|
||||
|
||||
**A bound names what it was waiting for.** `within(what, ms, task)` either settles the task or throws a `DeadlineExceeded` carrying `what` verbatim — never a bare timeout with no subject. `armSuiteDeadline` does the same for a whole run, and reports before leaving. `enclosingBound(steps, margin)` returns a number no smaller than the sum of the bounds it encloses, so an enclosure can never fire before the step that actually hung.
|
||||
|
||||
**A run owns its profile and discards it.** `newRunProfile` returns a directory belonging to this run alone; `discard()` kills whatever still holds it and removes it, is idempotent, and also runs when the process leaves — including when the run is killed. Two runs never share local state, so nothing a previous run left can make this one pass or fail.
|
||||
|
||||
**A minted wallet is new.** `mintWalletProfile`/`mintWalletBytes` walk the wallet application to create a wallet that did not exist a moment ago. `mintWalletBytes` keeps only the bytes and discards the profile it minted in; `mintWalletProfile` keeps the profile for the length of the run. The password is always a parameter and never has a default; the name defaults to `DEFAULT_WALLET_NAME` because nothing in NextGraph keys off it.
|
||||
|
||||
**The crossing dispatches on the screen it can see**, not on a fixed sequence: `setupBrokerPage` reads the page against `BROKER_SCREENS` in order, answers it, and returns the application's `Frame` once the crossing has completed. It identifies the application by ORIGIN. A terminal screen ends the crossing as a failure rather than an action.
|
||||
|
||||
**An empty-profile context starts with nothing local.** `emptyProfileContext` gives a context whose profile holds no wallet and no repo cache, which is the reconnection cold start: the wallet's repos are on the broker and not in this profile. `importWalletFile` then puts the wallet in — but not the repos' cache — so the next session over it still hits that cold start.
|
||||
|
||||
**A closed server is closed.** `serveOnEphemeralPort` tracks its open sockets and destroys them on `close()`, so a connection nobody hung up cannot be blamed on whatever goes wrong next.
|
||||
|
||||
**A known failure mode is named instead of the innocent operation.** `browserTrouble`/`frameTrouble` answer a string when the browser or the application frame is the actual cause, and `null` when they are not. `SuiteOptions.diagnose` puts that answer in FRONT of a journey's own reason, never in place of it. A frame that is attached, on the right URL, and empty is reported as trouble — that is the state a naive check misses.
|
||||
|
||||
**The report's size does not depend on what failed.** Journeys and their checks are declared up front to `declareSuite`; `check` throws on a name the journey did not declare, `journey` runs one journey bounded and isolated so it cannot change the report's shape, and `finish` reports every declared check the run did not get to before printing and exiting. A journey whose prerequisite is provably dead is reported as such instead of being driven.
|
||||
|
||||
**Errors are values where a caller can act on them.** `browserTrouble`/`frameTrouble`/`Prerequisite` answer `string | null`, never throw for the condition they detect. `DeadlineExceeded` and `BrowserGone` are exported classes, so `instanceof` is a supported way to tell a hang from a dead browser.
|
||||
|
||||
## Non-guarantees
|
||||
|
||||
**No assertion library, no runner, no fixtures.** `SuiteReport.check` records a boolean you computed; nothing here decides what is true.
|
||||
|
||||
**`finish` never returns** — it exits the process. Do not put cleanup after it; put it in the `discard()`/`closeQuietly` path.
|
||||
|
||||
**No message text is stable.** The strings from `browserTrouble`, `frameTrouble`, `DeadlineExceeded` and the report are for a human reading a run. Do not parse them, match on them, or branch on them.
|
||||
|
||||
**No timing promise.** Every exported `*_MS` constant is a bound sized from a measurement on one machine, not a service level: they change when the measurements change, and a run slower than one of them is a failed run, not a broken guarantee. `E2E_TIMINGS=1` reprints the measurements so you can resize your own.
|
||||
|
||||
**Nothing survives a run.** Profiles are discarded, and no artifact, cache, or wallet is carried from one run to the next. The one exception is a file you write yourself with `exportWalletFile` or `ng-mint-wallet`.
|
||||
|
||||
**No concurrency contract.** The suite machinery assumes one run per process. Two suites sharing a process share `armSuiteDeadline`, the timings table and the loss declaration.
|
||||
|
||||
**No wallet-application version pinning.** The crossing is driven against the wallet application as deployed at the broker you point it at. When that application changes its screens, `BROKER_SCREENS` is what has to be updated — a crossing that fails there is not necessarily your application's fault, and is not this package's promise to hold across upstream redesigns.
|
||||
|
||||
## Change policy
|
||||
|
||||
**Semver, and majors are the normal case.** This machinery tracks a NextGraph and a wallet application that are both still moving, so a screen inventory, a bound, or a call shape changes whenever they do — 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** — an exported symbol is removed or renamed, **or** an existing call narrows: it now throws where it returned, requires an argument that was optional, or returns something a caller must newly handle. A change to what a `SuiteReport` accepts (a check name, a journey shape) is a major, because your suite is written against it. 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: a new helper, a new screen in `BROKER_SCREENS`, a new optional field on `SuiteOptions`.
|
||||
- **patch** — a fix that changes neither the exported surface nor anything above under `## Guarantees` — including a re-sized `*_MS` constant, which is explicitly disclaimed above.
|
||||
|
||||
**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.
|
||||
|
||||
**Tags carry the package name**, because this repository publishes more than one engagement and their versions move independently: `ng-e2e-helpers/v1.0.0-dev.2` is this package, `polyfill/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. What exists today is `1.0.0-dev.2`, on a branch: pin that string exactly, and anchor your `usage_` leaf's `against:` on it — `against: ng-e2e-helpers@1.0.0-dev.2`, the string you pinned, never the version it is heading for.
|
||||
|
||||
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. Diff this leaf between two pulls — `## Guarantees` and `## Non-guarantees` before `## Surface`, because that is where a narrowing shows up first.
|
||||
@@ -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.
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
type: usage
|
||||
summary: What the polyfill's own end-to-end suites call from ng-e2e-helpers, under which constraints, and where the fit still costs them code
|
||||
against: ng-e2e-helpers@1.0.0-dev.2
|
||||
---
|
||||
|
||||
# usage_polyfill-e2e — the polyfill's end-to-end suites
|
||||
|
||||
The consumer is the end-to-end suite of `@ng-eventually/polyfill`: four entry points under that package's `e2e/` — a batch of SDK checks against the broker, an applicative suite driving the example application, a reactivity probe, and a cold-start reproduction — plus the page module they share.
|
||||
|
||||
This consumer lives in the same repository as the provider. That changes nothing about what is declared here: the engagement is what these suites are written against, and anything they call that is NOT listed below is theirs to fix if it moves.
|
||||
|
||||
## Consumed surface
|
||||
|
||||
**Bounds** — `within`, `armSuiteDeadline`, `closeQuietly`, `enclosingBound`, `firstLine`. `within` is the most-called entry of the whole package here: every bridge call into the application iframe goes through it.
|
||||
|
||||
**Measurement** — `measured`. Nothing reads `record`, `timingsWanted` or `printTimings` directly; the `E2E_TIMINGS=1` output is consumed as printed output, not as a call.
|
||||
|
||||
**Browser and profiles** — `launchWatchedContext`, `closeContext`, `newPage`, and the type `RunProfile`. `newRunProfile` and `isAlive` are never called: profiles are always obtained through a wallet call.
|
||||
|
||||
**Wallet** — `mintWalletProfile` (the batch wallet, minted once per run), `mintWalletProfileKeepingContext` (the cold-start reproduction, which needs the very first application session over a never-used wallet), `emptyProfileContext` + `importWalletFile` (the reconnection journey), `exportWalletBytes` (serving the wallet from the application's own bundle), and the type `WalletCredentials`.
|
||||
|
||||
**Broker crossing** — `setupBrokerPage` in all four suites, `completeBrokerLogin` in the applicative one.
|
||||
|
||||
**Serving** — `serveOnEphemeralPort`, for both the SDK page and the example application's bundle.
|
||||
|
||||
**Known failure modes** — `browserTrouble`, `frameTrouble`.
|
||||
|
||||
**Report** — `declareSuite` and the types `JourneyDeclaration`, `Prerequisite`. Used by the applicative suite only.
|
||||
|
||||
**Constants** — `BROKER_ROUND_TRIP_MS`, `NEW_PAGE_MS`, both as inputs to `enclosingBound` rather than as waits of their own.
|
||||
|
||||
Everything else the package exports is offered and NOT consumed here — the screen inventory (`BROKER_SCREENS`, `WALLET_APP`, `WALLET_CREATION`, `WALLET_IMPORT`, `brokerRedirectFor`, and the screen types), `createWalletInContext`, `exportWalletFile`, `mintWalletBytes`, `DEFAULT_WALLET_NAME`, `browserLost`, `lossDeclared`, the exported error classes, and the remaining `*_MS` constants. It is safely evolvable as far as these suites are concerned.
|
||||
|
||||
## Constraints
|
||||
|
||||
**The browser types come from the helpers.** `Frame`, `Page` and `BrowserContext` are taken from `ng-e2e-helpers`, which re-exports them, rather than from `playwright` directly — so these suites never depend on resolving the same copy of it, which is the position a consumer in another repository is in anyway.
|
||||
|
||||
**Every suite mints its own physical wallet, per run.** Nothing is carried between runs and no wallet is reused, so a run's result never depends on a previous one. The batch wallet's NAME is stable and its identity is not: two runs sharing the name share nothing else.
|
||||
|
||||
**The password is supplied, never defaulted.** These suites also read the barrier's displayed password back off its own screen and pass it to `importWalletFile`, which is the only way to prove that what the barrier shows is what opens the file. A defaulted password would make that check vacuous.
|
||||
|
||||
**An enclosing bound is at least the sum of what it encloses.** These suites compute every enclosure with `enclosingBound` rather than picking a round number, because an enclosure that fires first reports "the journey timed out" and never names the step that hung.
|
||||
|
||||
**A wait must not be entered unbounded.** Playwright's `frame.evaluate` waits forever, so no bridge call is made outside `within`.
|
||||
|
||||
## Frictions
|
||||
|
||||
**`frame.evaluate` has no bound, and three suites each wrote the same wrapper.** A `sdk(frame, method, …args)` helper — `within(…, BRIDGE_MS, () => frame.evaluate(…))` — is duplicated verbatim in three of the four entry points. The bound is the single most important one in each of them, and the package offers nothing to obtain it from. A bounded `evaluate` helper here would delete the duplication and stop each new suite re-deriving it.
|
||||
|
||||
**"Measured and bounded" is one intent and two calls.** Sizing a bound from its own measurement is the discipline this package prescribes, yet the applicative suite composes `measured(what, ms, (bound) => within(what, bound, task))` by hand — and the indexing layer's suite, in another repository, wrote the same line byte for byte. A helper that pairs them belongs on the engagement.
|
||||
|
||||
**`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.
|
||||
@@ -0,0 +1,24 @@
|
||||
---
|
||||
type: rule
|
||||
summary: An end-to-end journey must reach its starting state through the system, never by pre-seeding what the sign-in would have produced — the shortcut keeps whole features untested while staying green
|
||||
---
|
||||
|
||||
# Never hand a journey the state the sign-in would have produced
|
||||
|
||||
**Rule:** An end-to-end `journey` must arrive at its starting state **through the system**. Never pre-seed the identifier in the URL, never pre-import a wallet into the profile under test, never set the acting identity directly. If reaching a state through the system is awkward, that awkwardness is the finding — not a reason to skip it.
|
||||
|
||||
**Why.** Every applicative `journey` used to append the identifier to the application URL before loading it. The identity then resolved from the URL, the `barrier` never appeared, and the suite was green for months. It was green over:
|
||||
|
||||
- a download link pointing at a file **nobody served** — the barrier handed out a 404, and no test had ever clicked it. Worse, the test server answered every unknown path with the application's own HTML, so a missing file could not fail even in principle;
|
||||
- an ordering defect that made the barrier unreachable for any first-time user — the application handed the page to the broker before the barrier could appear, leaving a newcomer at a login page with no wallet and no way to get one;
|
||||
- and, later, a regression in sharing.
|
||||
|
||||
The first journey that actually walked a newcomer's path — empty profile, no wallet, real download, real import — found all of it immediately. The coverage hole and the defects protected each other: the shortcut existed because the real path was tedious, and the real path stayed broken because nothing walked it.
|
||||
|
||||
**How to apply.** The tell is mechanical: a `journey` that *writes* a value the system is supposed to produce. Ask *"by which call would a real person obtain this?"* — no answer means the feature is incomplete, not that the test needs help.
|
||||
|
||||
This is not a blanket ban on fixtures. Shared setup — building the application, minting the `batch` user, serving files — is legitimate and belongs before the journeys. What is banned is seeding **the specific state under test**: a journey about sign-in may not start signed in.
|
||||
|
||||
Journeys that legitimately need an already-signed-in actor may use the shared sign-in helper. That is exactly why at least one journey must not: without it, the helper's own path is the untested one.
|
||||
|
||||
Read alongside the global rules on covering the case space and on each actor obtaining its inputs through the system — same failure shape, and it has now produced real defects here twice.
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
type: overview
|
||||
summary: How a person gets from holding nothing to acting as an identity — the barrier, the broker hand-over, and the split between settling and connecting
|
||||
triggers:
|
||||
keywords: [sign-in, signin, identity, ensureIdentity, settleIdentity, barrier, gate, wallet, broker, redirect, ng-id, currentUser, session]
|
||||
paths:
|
||||
- "packages/polyfill/src/shared-wallet/**"
|
||||
- "packages/polyfill/src/surface/lifecycle.ts"
|
||||
- "packages/polyfill/src/emulated-verifier/connect.ts"
|
||||
vocabulary:
|
||||
- term: settle
|
||||
gloss: decide which identity is acting, from the URL, storage, or the barrier — needs no session
|
||||
not: [resolve identity, determine user, login]
|
||||
see: knowledge_settling-is-not-connecting
|
||||
- term: barrier
|
||||
gloss: the full-screen overlay this package mounts to hand out the wallet and take an identifier
|
||||
not: [modal, popup, login screen]
|
||||
---
|
||||
|
||||
# sign-in — getting a person from nothing to acting
|
||||
|
||||
This concept covers everything between "someone opens the application" and "an identity is acting with a live session": the `barrier` this package mounts, the wallet a newcomer must obtain, the broker redirect, and the two distinct acts — `settle` and connect — that were once conflated and must stay apart.
|
||||
|
||||
None of it is app-facing. An application awaits one call and renders; it must never learn that a broker, an iframe or a redirect exist. What it may rely on lives in `app-contract`; what follows is how that promise is kept.
|
||||
|
||||
The whole thing is scaffolding: upstream, a person opens **their** wallet, it contains **their** site, and `session_start` takes an id that came from the wallet. There is nothing to name and nothing to choose. This concept exists because one shared wallet hosts several identities.
|
||||
|
||||
## Read first
|
||||
|
||||
- `knowledge_how-a-user-gets-in` — the flow end to end, and which layer owns each step.
|
||||
- `knowledge_settling-is-not-connecting` — the split, and the cycle that forces it.
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
type: knowledge
|
||||
summary: The sign-in flow end to end, and which layer owns each step — in particular that the broker redirect belongs to @ng-org/web, not to this package
|
||||
---
|
||||
|
||||
# How a user gets in
|
||||
|
||||
## The steps, and who owns them
|
||||
|
||||
A newcomer holds nothing. To act they need a wallet imported once into the wallet application, and an identifier naming their virtual space. The `barrier` hands out the first three — the wallet file, its password, a link to the wallet application — and takes the fourth.
|
||||
|
||||
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 `.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.
|
||||
|
||||
## When the `barrier` shows, and why it is not a question of identity
|
||||
|
||||
**Top-level: always. Inside the broker iframe: never** — there the identifier arrives in the URL and the page stands aside.
|
||||
|
||||
The discriminator is the frame, not whether an identity is known, and the difference is not ergonomic. An identity is state we can observe; whether the person still has a wallet in this browser is state we cannot — it lives in another origin's storage. A screen that decides on the identity is therefore *guessing* at the state that matters, and when it guesses "already set up" while NextGraph's side is gone, it hides the only controls that could repair the situation.
|
||||
|
||||
What that costs is not a degraded experience but a dead end: sent to the broker without a wallet, the person lands on a static page carrying **no return path to the application**. The browser's Back button is the only way out, and it only helps if the `barrier` is there to catch them on arrival.
|
||||
|
||||
A known identifier therefore **prefills the field; it never skips the screen**. And nothing detects whether the wallet is already there: all steps are always shown, and whoever already has one ignores them. No checkbox, no "I already have it" — knowing whether you imported a wallet into this browser is not something a person can be asked.
|
||||
|
||||
Two facts, observed on the live sites, close the alternatives: clicking the wallet application's import control opens a file chooser **in place** — no navigation, no new tab; and our own page receives **no signal at all** when the import succeeds (no opener, no message, no storage or focus event, no reload). Detecting the return is impossible, not merely fragile.
|
||||
|
||||
## Why the identifier travels by URL
|
||||
|
||||
The flow runs in **two contexts with separate storage partitions** — the top-level page and the broker iframe — because browsers partition storage by top-level site. A value written top-level is not the value the iframe reads.
|
||||
|
||||
What crosses is the URL: the redirect embeds the full application URL, query included, and reloads it in the iframe. Hence the resolution order, which must not be "simplified":
|
||||
|
||||
1. the identifier in the URL — it wins whenever present, being the only thing that crosses;
|
||||
2. otherwise storage — same-partition convenience, and prefill on reload.
|
||||
|
||||
The parameter must therefore be written on **every** path that settles an identity, not only when the `barrier` asked. An identity coming from storage without the parameter being written is the silent failure: the iframe reads an empty identity, provisions a second virtual space, and the returning user lands somewhere empty with no error.
|
||||
|
||||
Writing to storage and writing to the address bar are two independent attempts, deliberately: a storage that refuses writes must not cost the round-trip its parameter.
|
||||
|
||||
## What survives migration
|
||||
|
||||
The `barrier` evaporates whole — handing out a shared wallet and naming a space exist only because the wallet is shared. The redirect does **not**: upstream's real multi-wallet flow has the same shape, and the barrier becomes the real per-user sign-in. The call site survives too, which is why the published call takes no identifier.
|
||||
@@ -0,0 +1,61 @@
|
||||
---
|
||||
type: knowledge
|
||||
summary: Deciding which identity acts needs no session; connecting does — conflating them deadlocks one way and silently breaks sharing the other
|
||||
---
|
||||
|
||||
# Settling is not connecting
|
||||
|
||||
Two acts of different nature hide behind "sign in":
|
||||
|
||||
- **`settle`** — decide which identity is acting, from the URL, from storage, or by asking at the `barrier`, then persist it. Pure DOM and storage. **No session required.**
|
||||
- **connect** — put back in that identity's hands everything it can already open: what it OWNS as well as what was shared with it, drain its queues, and then keep applying what arrives in them for as long as it stays connected. **Requires a live session.**
|
||||
|
||||
The wallet keeps those two in different places, and connecting once replayed only the second — so an application that reloaded and went straight to a document it had made itself was refused its own document. Whatever else changes here, connecting must replay **every** durable register, not the one that happens to be read on the path being tested.
|
||||
|
||||
They must stay apart, and the reason is not tidiness.
|
||||
|
||||
## Why they cannot be one call
|
||||
|
||||
`init()` starts the broker redirect as its first statement when the page is top-level, so anything the barrier needs to show must already be in place. The `barrier` must therefore appear **before** `init()`.
|
||||
|
||||
But an identity cannot connect before `init()` either: connecting needs the session, which arrives only through `init()`'s callback. Await the whole of sign-in before `init()` and it deadlocks; call it after and the `barrier` never appears.
|
||||
|
||||
The way out is that only *half* of it has that dependency. Settling is awaited by this package's `init()` wrapper before it delegates; connecting stays in the published call, awaited where a session exists.
|
||||
|
||||
**The invariant is carried by the composition from `init()` onwards** — which is why an application must call this package's `init`, not the one it injected: calling it settles the identity whether or not the published call has run.
|
||||
|
||||
It does **not** cover calling the published sign-in strictly first and awaiting it: the connection work it adds waits for a session only `init()` resolves, so it deadlocks in silence. Half an invariant carried by a mechanism, half still owed to the caller — and the half still owed fails silently, which is the worst kind.
|
||||
|
||||
## The failure this cost
|
||||
|
||||
Settling once reached the session, because recording who is acting also fired the connection. At the time the session was assembled by the application: it built a promise around `init()`'s callback and handed the package a thunk reading it. The application called `init()` *from inside the executor building that promise*, so the thunk could not answer by construction. It threw, the account lookup answered null, and the connection run abandoned **without restoring or draining** — having already registered itself as in flight. The published call then joined that dead run and resolved having done nothing.
|
||||
|
||||
Symptom: a document shared with someone did not open for them. No error, just unreadable content.
|
||||
|
||||
Nothing had changed in the connection logic. What changed was *when* the identity was recorded. Before the split, nothing recorded an identity during module evaluation: a session existed, the run was healthy, and joining it was harmless.
|
||||
|
||||
Hence the shape of the fix — recording who acts and starting to connect are separate operations, and the session-free half only records. The session is now the package's own — its `init()` wrapper captures the event — so no application can wire this wrong again. To validate: nothing reachable from settling asks for a session.
|
||||
|
||||
## The lesson worth keeping
|
||||
|
||||
A "session-free" half that calls something which fires a session lookup is not session-free. When splitting on a dependency, check what the *side effects* of each remaining call reach, not only what the call itself does.
|
||||
|
||||
## Failing to reach a queue is not failing to apply one item in it
|
||||
|
||||
Making connection failures surface was right — a restore that did not happen makes shared documents silently invisible, and resolving as though it had is the defect family this project keeps finding. But applied to *every* step alike, that rule locked people out.
|
||||
|
||||
A deposit that cannot be applied is not consumed by failing. So a single unusable item denied the session, and denied it again at every future connection: not a missing share, a person who can never sign in. Strictly worse than the silence it replaced.
|
||||
|
||||
The distinction to keep: **reaching** the queues, and the restore itself, are infrastructure — if they fail, the session genuinely cannot proceed, and rejecting is right. **Applying one item** is data — it must be reported loudly, the remaining queues must still be drained, and the session must still be granted.
|
||||
|
||||
The general shape, worth carrying to any similar rule: when a blanket "every failure surfaces" is imposed, ask which failures are *retried by simply trying again later* and which are *permanent for the actor*. The permanent ones must never gate something the actor cannot otherwise obtain.
|
||||
|
||||
## Connecting does not end when the drain does
|
||||
|
||||
The drain is the backlog; being connected is a regime. An identity that stays connected has its inboxes watched throughout, so a deposit made in front of it is applied as it arrives rather than waiting for a reload, and an inbox opened later in the session joins the watched set.
|
||||
|
||||
That third step runs whatever became of the two before it, and the failure it was added for says why. A restore that rejected used to skip it, leaving an identity connected — recording who acts is synchronous and had already taken effect — with nothing watching its inboxes for the rest of the session. One broker hiccup while signing in then cost that person every deposit made from then on, in silence, long after the broker had recovered. What the caller is told has not moved: reaching the queues still rejects. What changed is that being connected now *means* being watched, whatever the connection made of its own work.
|
||||
|
||||
The counterpart is that the watching belongs to one identity and dies with it. Recording a different identity — or none, which is a disconnection and not merely "no new work" — stops it, because every step of it resolves the current holder as it runs: left going, it would read the previous identity's registers under the new one and file the previous one's `ReadCap`s into the new one's hands. Whoever connects next starts their own.
|
||||
|
||||
There is deliberately no timer anywhere in this: the regime is push-driven, and its known cost — a watch that failed to open is re-opened only by a later event, so a session that only reads never gets it back — is stated to applications under the contract's non-guarantees rather than papered over with polling.
|
||||
@@ -0,0 +1,42 @@
|
||||
# Inter-repo contracts. `publish:` is this project's engagement toward its consumers —
|
||||
# listing a leaf here IS the act of publishing it; an unlisted `contract_` leaf is a draft.
|
||||
#
|
||||
# This project is a PROVIDER of two interfaces, each hosted in an interface folder inside
|
||||
# its owning concept, with one `usage_<consumer>.md` per consumer beside the engagement:
|
||||
#
|
||||
# polyfill-surface (concepts/app-contract/polyfill-surface/)
|
||||
# consumers: the Festipod application (its own repo), `ng-helpers`
|
||||
# ng-e2e-helpers (concepts/e2e-harness/ng-e2e-helpers/)
|
||||
# consumers: this repo's own polyfill e2e suites (same repo — declared in place,
|
||||
# nothing to pull), `ng-helpers`, any NextGraph application
|
||||
#
|
||||
# `consume:` here is the PROVIDER side of the pair: we pull each consumer's own declaration
|
||||
# back, so we can see what is actually relied on and read its Frictions. We consume no
|
||||
# engagement — the NextGraph clone this library aligns on is a read-only reference we verify
|
||||
# against, not a contract anyone stamps.
|
||||
#
|
||||
# `pullFrom:` values are CANONICAL remote identities, because this file travels with the
|
||||
# branch. Per-developer local access lives in `.project/contracts.local.yaml`, which is
|
||||
# gitignored and must never be committed.
|
||||
|
||||
publish:
|
||||
# paths are relative to `.project/`
|
||||
polyfill-surface: concepts/app-contract/polyfill-surface/contract_polyfill-surface.md
|
||||
ng-e2e-helpers: concepts/e2e-harness/ng-e2e-helpers/contract_ng-e2e-helpers.md
|
||||
|
||||
consume:
|
||||
# Festipod is NOT listed: it has not declared a usage leaf, and we do not author one for
|
||||
# a consumer whose repo is not ours. An interface with no declared consumer degrades to
|
||||
# the one-document mode, which is what `polyfill-surface` is for Festipod today.
|
||||
|
||||
- contract: ng-helpers-uses-polyfill-surface
|
||||
type: git
|
||||
pullFrom: git@gitea.reconnexion.apps.gueraud.net:Sylvain/ng-helpers.git/.project/concepts/indexing/polyfill-surface/usage_ng-helpers.md
|
||||
ref: main
|
||||
into: concepts/app-contract/polyfill-surface/
|
||||
|
||||
- contract: ng-helpers-uses-ng-e2e-helpers
|
||||
type: git
|
||||
pullFrom: git@gitea.reconnexion.apps.gueraud.net:Sylvain/ng-helpers.git/.project/concepts/indexing/ng-e2e-helpers/usage_ng-helpers.md
|
||||
ref: main
|
||||
into: concepts/e2e-harness/ng-e2e-helpers/
|
||||
@@ -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`
|
||||
@@ -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.
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
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
|
||||
|
||||
**Rule:** Never implement anything that diverges from NextGraph. At every choice — a published signature as much as an internal mechanism — the **first** question is *does the target do this?* Verified in `nextgraph-rs`, or stated by its author. If the target does it differently, we do it their way, whatever that costs. Only where the target answers nothing at all do we invent, and then deliberately, documented, and named as a bet.
|
||||
|
||||
"Known" is narrow: read at the source, or stated by its author. Never inferred from what an npm package happens to expose, and **never inferred from an absent implementation** — *"the engine does not do X"* says nothing about whether the target will.
|
||||
|
||||
**A definition is a fact; its being unwired is an absence.** The two arrive together and the absence is the louder one, which is how it wins arguments it should lose. A type the target has declared but nothing constructs yet is the *strongest* thing to align on — implementing it is not inventing, it is realising a shape the target wrote down. Read the declaration and let the silence around it say nothing.
|
||||
|
||||
That distinction has its own place in the taxonomy below, because collapsing it into "invention" makes us believe we are further from the target than we are — and then a later reader, seeing "our own idea", feels free to change it.
|
||||
|
||||
**The second question measures gravity, not permission:** *would an application coding against this have to unlearn it?* Use it to rank what to fix first, and to judge an unavoidable divergence. Never use it to authorise one.
|
||||
|
||||
**Why the order matters — it is the failure this rule was rewritten for.** `readUnion` folded every triple of a document into one bag keyed by the document, so two entities written under two subjects came back merged and one written under another subject came back relabelled, silently. Asked the second question first, the answer was ambiguous: *one entity per document* is good placement practice anyway, so what exactly would a caller unlearn? The reasoning stalled there for hours. Asked the first question, it took one look: level 1 returns real subjects, and level 3's ORM carries `@id` **and** `@graph` on every object and generates the former when omitted — several objects per graph is the designed case. Divergence, done, no debate about perception.
|
||||
|
||||
Earlier instances, all of the same shape: *"every document has a native inbox"*, written from general reasoning, false, and already an implementation; and a per-document inbox pointed at its owner's inbox to absorb a measured cost, emulating a many-to-one relation the target cannot express.
|
||||
|
||||
**The pressure to deviate never announces itself as one.** It arrives as a cost, a latency, an ergonomic wrinkle — all real, all legitimate. That disguise is what makes it dangerous. When shape and cost conflict: keep the shape and attack the cost elsewhere (the lever is usually *who* pays and *when*). If the cost is genuinely unsolvable, say so rather than bending the model quietly.
|
||||
|
||||
**How to apply.** The tells, each of which has produced a real hole here:
|
||||
|
||||
- **A recommendation enforced by the code.** Ours may guide placement; it may not make the other arrangement invisible. A read path that silently normalises what it did not expect is the signature.
|
||||
- **A symbol that makes the caller handle what the target will never hand it** — a document's key, an inbox address, a store id, its own identity.
|
||||
- **A named exception stops being one the moment it is published.** A door documented as *"only this internal caller uses it"* is a door any application can open; the note is not a mechanism. Move it out of the published surface instead.
|
||||
- **A symbol kept because it was already there is not a decision.** At every surface change, re-ask whether an application still needs each neighbouring symbol.
|
||||
|
||||
When a divergence is genuinely unavoidable it must be **deliberate, documented and invisible to the caller**. What is forbidden is the silent one, adopted because it was convenient.
|
||||
|
||||
## 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 `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 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.
|
||||
|
||||
The tell is mechanical: **open the declaration and look for a payload.** Several of `InboxMsgContent`'s variants — `Link`, `Patch`, `ServiceRequest`, `ExtRequest`, `RemoteQuery`, `DialogRequest` — are bare unit variants carrying nothing at all, while `ContactDetails` and `SocialQuery` carry data and have processors. Presenting the first group as *"the strongest thing to align on"* was an error made here, in the same breath as citing this rule; see [[knowledge_what-an-inbox-is-upstream]] for what those variants do and do not offer.
|
||||
|
||||
**Why this exists.** A maintainer read that `AddLinkV0` is defined upstream but constructed nowhere, and reported our implementation of it as our own invention — reasoning from the absence while quoting, in the same session, the rule against exactly that. The correct reading was `declared-not-wired`, which is the best alignment available. Prose said otherwise elsewhere too: `docs/api-contract.md` claimed `docs.*` was a 1:1 passthrough while two of its signatures diverged, and stated a member count that was simply wrong. Both errors are the same one — a claim about the target that nothing forced anyone to check.
|
||||
@@ -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.
|
||||
@@ -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
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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`.
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
```
|
||||
|
||||
@@ -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.
|
||||
@@ -0,0 +1,7 @@
|
||||
## Project vocabulary (always loaded)
|
||||
|
||||
@.project/VOCABULARY.md
|
||||
|
||||
## Rules
|
||||
|
||||
@.project/rules/INDEX.md
|
||||
@@ -29,11 +29,10 @@ Docs (this library's own engineering doctrine, under [`docs/`](./docs/)):
|
||||
behaviour on one shared wallet (shim, per-document ReadCaps, emulated inbox,
|
||||
write guard, the two axes, the double-proxy constraint).
|
||||
- [`docs/read-model.md`](./docs/read-model.md) — the read model the polyfill
|
||||
implements: events via the global index, everything else by following a shared
|
||||
graph; listing via a bounded set of per-doc anchored `sparql_query`s; reactivity
|
||||
via re-query on a change signal.
|
||||
implements: you follow links, you never enumerate; listing via a bounded set of
|
||||
per-doc anchored `sparql_query`s; reactivity via re-query on a change signal.
|
||||
- [`docs/decisions/`](./docs/decisions/) — current-SDK ADRs (private-store scope,
|
||||
SPARQL delete, shared-wallet identity, discovery mechanism).
|
||||
SPARQL delete, shared-wallet identity).
|
||||
- [`docs/fork-inbox-fallback.md`](./docs/fork-inbox-fallback.md) — the Rust-patch /
|
||||
self-host inbox path not taken (kept as a fallback).
|
||||
- [`docs/migration-guide.md`](./docs/migration-guide.md) — the checklist for when
|
||||
@@ -52,30 +51,25 @@ is needed), and how this lib emulates it today.
|
||||
|
||||
| Capability | What the consumer application does | Real NextGraph target | Current NextGraph status (why a workaround) | Current emulation |
|
||||
|---|---|---|---|---|
|
||||
| Multi-identity / per-identity wallet | Treats each identity id as its own wallet with its own documents | Each identity opens its own real wallet; native cross-wallet reads | Not-yet-implemented: the JS SDK exposes no cross-wallet read, so one session cannot read another identity's wallet | One shared wallet everyone opens; "identities" are virtual wallets — shim accounts keyed by an id, each mapped to its documents in `store-registry.ts` |
|
||||
| Multi-identity / per-identity wallet | Treats each identity id as its own wallet with its own documents | Each identity opens its own real wallet; native cross-wallet reads | Not-yet-implemented: the JS SDK exposes no cross-wallet read, so one session cannot read another identity's wallet | One shared wallet everyone opens; "identities" are virtual users — shim accounts keyed by an id, each mapped to its documents in `shared-wallet/account-registry.ts` |
|
||||
| Three native stores per identity | Places entities by scope `public` / `protected` / `private` | The identity's three real native stores hold the entity documents | Not-yet-implemented: `doc_create`/ORM can target only the private (and protected) native store today; a `public`/arbitrary `StoreRepo` is not JS-constructible | Three emulated scope-index documents per account — each "store" is an index doc listing its entity-doc NURIs; all physically live in the one shared private store, and scope is a logical label |
|
||||
| Per-document read isolation | Declares a document's read policy via `getCaps().open(doc, scope, owner)`, then issues directed read grants (`grantRead(doc, granteeId)`) | The broker/verifier delivers only documents the wallet holds a ReadCap for; accessing a document without the cap yields an empty result in a union read (a targeted read of an unheld repo errors with `RepoNotFound`) | Bug/gap for emulation purposes: there is no cap-introspection API — a client cannot ask "may this identity read this doc?", so the polyfill cannot mirror the broker's decision from NextGraph itself | An emulated `CapRegistry` (`caps.ts`, per-document read/write caps) + a read filter (`read-filter.ts`, a defence-in-depth view) that keep only documents the current identity may read; `canRead`/`governsRead` are emulation-only, with no NextGraph API behind them |
|
||||
| Directed read sharing | Owns the relationship concept ("who is connected to whom") itself, and for each relationship issues directed read grants on the owner's protected documents | A native per-document ReadCap issued to a specific identity — but note this target is itself not-yet-built in nextgraph-rs today, not merely unexposed in JS: `AccessGrantV0{grantee}` is unpersisted scaffolding and cap-send is `unimplemented!()`, so directing a grant to another identity has no working platform primitive yet | Not-yet-implemented: sending a cap to another identity is `unimplemented!()`, and no relationship/mutuality primitive exists — relationship is an application concept, not a platform one | The app selects the owner's protected documents via `getCaps().protectedDocsOf(owner)` and calls `grantRead(doc, granteeId)` per grantee; the lib records the per-document grant |
|
||||
| Inbox (registration notifications) | `inbox.post` / `read` / `watch` | A message is sealed to the recipient's key and queued in their inbox; the recipient's own verifier unseals and applies each queued message inline while processing the inbox | Not-yet-implemented: the sender-side seal-into-inbox call (`inbox_post_link`) is proposed/future, not exposed in the JS SDK | Deposits written as RDF into an inbox document via SPARQL; `read`/`watch` read the deposits back — an in-lib stand-in for the recipient's own inbox processing |
|
||||
| Discovery of all public events | `submitToIndex(ref)` / `readIndex()` | A real owned global document (owner undecided — a singleton-app path), fed via its native inbox, read as a materialized index | Not-yet-implemented / undecided: an identity's apps and services see only what it shares, so there is no global backend index yet | A global index document owned by a reserved special account (`@index`), fed via its inbox, read with dedup; a stable NURI every client resolves |
|
||||
| Per-document read isolation | Nothing to declare: creating a document records its cap on its store, and its creator holds it. Reading is `capFor(doc)` — you hold the key or you do not read | The broker/verifier delivers only documents the wallet holds a ReadCap for; accessing a document without the cap yields an empty result in a union read (a targeted read of an unheld repo errors with `RepoNotFound`) | The model itself is the point: reading is key possession, and there is no read-ACL to introspect — a client cannot ask "may this identity read this doc?" because that question does not exist upstream | Caps recorded per identity: `AddRepo` on the store's emulated Store branch for documents it creates, `AddLink` on its User branch for caps received; `emulated-verifier/caps.ts` caches them for the session. A read filter (`emulated-verifier/read-filter.ts`) plus the boundary (`emulated-verifier/reach.ts`) keep only documents whose cap is held. The cap value is the stand-in `OK` — enforcement is P1b |
|
||||
| Directed read sharing | Owns the relationship concept ("who is connected to whom") itself, and on acceptance shares one document's cap to the other's inbox (`shareCap(cap, theirInbox)`) | The cap sealed to the recipient's inbox key (`ContactDetails.read_cap`), opened by their own verifier while processing the inbox | Not-yet-implemented — a **gap, not a disagreement**: the field exists but the message construction is `unimplemented!()`, its only caller passes "without read_cap", and the receiver discards the cap. The shape is right; the implementation is absent | `shareCap` deposits the cap into the recipient's inbox document; the recipient's existing `inbox.watch` absorbs it into what they hold. No "receive" operation, and no principal is ever named to the registry |
|
||||
| Inbox (registration notifications) | `inbox.post` / `read` / `watch` | A message is sealed to the recipient's key and queued in their inbox; the recipient's own verifier unseals and applies each queued message inline while processing the inbox | Not reachable from JS: the verifier has no `InboxPost` arm, and no `inbox` method exists in `@ng-org/web`. (`inbox_post_link` is OUR proposed name from [`docs/fork-inbox-fallback.md`](docs/fork-inbox-fallback.md), not an announced NextGraph API — no such symbol exists in `nextgraph-rs`.) | Deposits written as RDF into an inbox document via SPARQL; `read`/`watch` read the deposits back — an in-lib stand-in for the recipient's own inbox processing |
|
||||
| ~~Discovery of all public events~~ **REMOVED 2026-07-30** | Circulates the link itself — into inboxes, or into a document the reader already holds | **There is no discovery.** You cannot discover, you can only follow links: publishing = place the data in your public store **and** circulate the link, seen only by those who received it (a foundation of local-first) | Not a gap to be filled — a global index is not a NextGraph shape, and it would pool data across wallets | Nothing. `discovery.ts` and its global index were removed: they emulated a capability the target will never have. See [`docs/readcap-and-nuri-model.md`](docs/readcap-and-nuri-model.md) §4ter-bis |
|
||||
| Reads / listing | Lists the documents it needs, by scope, and reads them | Native per-wallet reads over the real per-identity stores | Bug/perf: an anchorless union query spans every named graph in the session store, which on a shared / accumulating wallet is O(wallet size) and stalls | A bounded, by-need set of per-doc anchored `sparql_query`s (each anchored to one repo's default graph), independent of wallet size |
|
||||
| Reactivity | Lists update on change | Native reactive reads | Not-yet-implemented: there is no reactive union query across graphs | Re-query the bounded per-doc anchored set on a lightweight change signal (`doc_subscribe` / ORM on an already-opened single store) |
|
||||
| Writes | Writes an entity to its scope | Writes land in the entity's real store via native primitives | Not-yet-implemented: `doc_create` can target only the private/protected store today (`StoreRepo` not JS-constructible) | Per-entity documents via direct SPARQL (`docs.sparqlUpdate` on the real injected `ng`) |
|
||||
| Current identity | Sets the current identity id (established at wallet import) via the SDK's current-identity call | Opening one's own wallet at the broker gate establishes the session identity | Not-yet-implemented for the shared-wallet case: everyone shares one wallet, so the broker cannot distinguish identities | A relayed id (`accounts.ts` `IdentityStore` persists it); the read filter and inbox `from` read it |
|
||||
| Write-guard | Writes refused without the write cap | The broker/verifier enforces the write cap natively | Partial: the guard fires only on the public proxy, but the real write paths call the injected `ng` directly (the `DataCloneError` constraint), so it is best-effort today | A `sparql_update` override (`ng-proxy.ts`) checking the emulated write cap |
|
||||
| Current identity | Sets the current identity id (established at wallet import) via the SDK's current-identity call | Opening one's own wallet at the broker gate establishes the session identity | Not-yet-implemented for the shared-wallet case: everyone shares one wallet, so the broker cannot distinguish identities | A relayed id (`shared-wallet/virtualUsers.ts` `IdentityStore` persists it); the read filter and inbox `from` read it |
|
||||
| Write-guard | Writes refused without the write cap | The broker/verifier enforces the write cap natively — writing is repo membership (`verify_permission`, reachable only from `Commit::verify`) | Not-yet-implemented for delegation: this library emulates no `AddMember`/`AddPermission`, so only a document's OWNER writes — a repo's upstream state until someone is added | An ownership check at the write door (`emulated-verifier/reach.ts` `assertMayWrite`, reading authorship from the Store branch). The older write-cap proxy (`surface/ng-proxy.ts`) is **inert** — `grantWrite` has no production caller, so its policy set is always empty |
|
||||
|
||||
## Packages
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@ng-eventually/client` | The SDK-identical wrapper the app imports instead of `@ng-org/web` / `@ng-org/orm`. It adds the polyfills the broker/verifier will do natively (shared-wallet identity, capability enforcement, anticipated cap/inbox methods). As NextGraph matures, the app points back at the real SDK (build alias removed) and this package falls away. |
|
||||
| `@ng-eventually/polyfill` *(was `@ng-eventually/client` until 2026-08-07)* | The SDK-identical wrapper the app imports instead of `@ng-org/web` / `@ng-org/orm`. It adds the polyfills the broker/verifier will do natively (shared-wallet identity, capability enforcement, anticipated cap/inbox methods). As NextGraph matures, the app points back at the real SDK (build alias removed) and this package falls away. |
|
||||
|
||||
A global-index package is deferred. In NextGraph an identity's apps and services
|
||||
see only what it shares, so there is no multi-identity backend. A global index
|
||||
would come from a singleton app (a global document administered by the developer),
|
||||
which is not implemented and undecided; simpler paths may exist. So there is no
|
||||
second package for now — it will be introduced once the global-index mechanism is
|
||||
decided, and it will be separate from the client.
|
||||
A global-index package is deferred. Data common to all of an application's users comes from a **singleton app**: a document or store shared by all users and hardcoded in the app, write-owned by the developer and delegable — but never to all users, so user contributions reach it **through an inbox** (nothing in NextGraph is freely writable by everyone). That is the direction the NextGraph developer has named; it is **not implemented**, and several points are still open (what exactly is hardcoded, how delegation travels, who materializes the inbox). So there is no second package for now — it will be introduced once the mechanism exists, and it will be separate from the SDK wrapper. See [`docs/nextgraph-current-state.md`](docs/nextgraph-current-state.md) § Apps & services.
|
||||
|
||||
## Design principle
|
||||
|
||||
@@ -83,35 +77,120 @@ The application code is written as if the target NextGraph existed. All
|
||||
compensation lives here, beside the app. As NextGraph matures, this layer falls
|
||||
away; the app code (SDK-shaped) is unchanged.
|
||||
|
||||
**Both halves are binding, and the second is the one that gets traded away.** The
|
||||
SURFACE must be as close as possible to the future SDK — that much is obvious, it is
|
||||
what the consumer codes against. But the IMPLEMENTATION must be as close as possible to
|
||||
what NextGraph actually plans, and there is no exception to that. Where upstream's
|
||||
behaviour is known, it is a specification, not a reference: **when it is known, hold to
|
||||
it**. What "known" means here is narrow — read in `nextgraph-rs` or stated by the
|
||||
NextGraph developer, never inferred from what an npm package happens to expose, and
|
||||
never inferred from an absent implementation ("the engine has no X" says nothing about
|
||||
whether the target will).
|
||||
|
||||
The pressure to deviate never announces itself as a deviation. It shows up as a cost, a
|
||||
latency, an ergonomic wrinkle — a real one. Two instances, both caught only by asking
|
||||
the question:
|
||||
|
||||
- *Every document has a native inbox* was written into the docs from general
|
||||
reasoning. It is false, and it had already become an implementation.
|
||||
- A per-document inbox was made to point at **the owner's** inbox, to avoid a measured
|
||||
cost (9m37 → 21m30 on the consumer's suite). It emulates a many-to-one relation
|
||||
upstream cannot express: the verifier routes by `inboxes: PubKey → RepoId` and unseals
|
||||
with that one repo's key (`engine/verifier/src/verifier.rs:1677,1928`), and a message
|
||||
carries no target document because it needs none. Reverted. The cost was then solved
|
||||
without touching the shape — only documents meant to receive open an inbox.
|
||||
|
||||
The tell in both: an implementation choice that would make the consumer learn something
|
||||
it must **unlearn** at migration. That is the thing this library exists to prevent, so
|
||||
it outranks cost, latency and convenience. When the shape and the cost conflict, keep
|
||||
the shape and attack the cost elsewhere — and if it truly cannot be solved, say so
|
||||
rather than bend the model quietly.
|
||||
|
||||
### The three references, numbered bottom-up
|
||||
|
||||
"NextGraph" is not one layer, and conflating them is how a fact about one gets asserted
|
||||
about another. They are **stacked**, each built on the one below, so they are numbered
|
||||
from the bottom:
|
||||
|
||||
| # | Layer | Where |
|
||||
|---|---|---|
|
||||
| **3** | **JS SDK / ORM** | `@ng-org/orm`, `@ng-org/shex-orm` — source in `sdk/js/orm` (TypeScript) |
|
||||
| **2** | **wasm binding** | `@ng-org/web` — source in `sdk/js/lib-wasm` (77 exported methods) |
|
||||
| **1** | **Rust engine** | `engine/` — `repo`, `verifier`, `net`, `broker`, `wallet` |
|
||||
|
||||
**These are REFERENCES, not places we write code.** Every line this library ships lives
|
||||
in the polyfill; none of these three layers is ours to touch, and `nextgraph-rs` is a
|
||||
read-only source of truth. Saying "level 1" about a piece of our code means *"it is
|
||||
aligned on the engine's model"* — never *"it lives in the engine"*.
|
||||
|
||||
**Which reference to align on: take the HIGHEST one that answers, and go down only when
|
||||
it does not.**
|
||||
|
||||
- **Level 3 answers fully → do not implement it here.** Pass through. Compensation code
|
||||
that doubles a working SDK function is code to delete later, and it diverges meanwhile.
|
||||
- **Level 3 is absent or unsatisfactory → align on the level-2 call** that does the job.
|
||||
Ergonomics are lost, semantics are kept — and migrating later means moving up one
|
||||
step, not rewriting.
|
||||
- **Nothing at level 2 either → align on the level-1 MODEL**: cardinalities, addressing
|
||||
units, what a structure can and cannot express.
|
||||
|
||||
Level 1's facts are the hardest-won, but aligning there means **inventing a JS surface**,
|
||||
since none exists yet. So always **say which level a choice came from**. A level-3
|
||||
passthrough is a fact; a level-1 shape is a bet constrained by the engine. Presenting
|
||||
them alike is what manufactures false certainty — `inbox_post_link` was cited across
|
||||
eight files as a planned NextGraph API when it was only a name proposed in
|
||||
[`docs/fork-inbox-fallback.md`](./docs/fork-inbox-fallback.md).
|
||||
|
||||
Concretely for the inbox: level 3 has nothing, level 2 has **no `inbox` method at all**
|
||||
(and the verifier has no `InboxPost` arm), so `inbox.*` is aligned on level 1 — the
|
||||
engine's model (one inbox ↔ one repo, addressed by `(overlay, pubkey)`, no target
|
||||
document in the message) with a JS surface of our own making.
|
||||
|
||||
This cascade answers *"we need X — what do we align on?"*. It is **not** a checklist to
|
||||
run over what the target exposes: an unused binding method is not a debt, and "it was in
|
||||
the unused list" is not a reason to investigate it.
|
||||
|
||||
> **Do not confuse these levels with the other "three levels" in this repo.**
|
||||
> [`docs/readcap-and-nuri-model.md`](./docs/readcap-and-nuri-model.md) §4quinquies numbers
|
||||
> *where a cap is stored* (wallet root key → the Store/User branch registers → the local
|
||||
> in-memory cache). Same word, unrelated axis: these three are **layers of NextGraph to
|
||||
> align on**, those three are **places a key lives**. When it is not obvious from the
|
||||
> sentence, say "reference level" or "storage level".
|
||||
|
||||
- SDK-identical surface: the client wraps the real `ng` (a Proxy that forwards
|
||||
everything and overrides only what must be emulated) and `useShape`. The real
|
||||
SDK is injected via `configure()` (no hard import → build-alias safe and
|
||||
testable).
|
||||
- Authorization is emulated capabilities: documents carry grants; the client
|
||||
enforces them generically (read filter + write guard). The app declares a
|
||||
document's read policy and issues directed grants — the same acts it will
|
||||
document, shares one document's cap to an inbox — the same acts it will
|
||||
perform in the target. No policy is injected.
|
||||
- Inbox: the client `inbox` namespace deposits (`post`) and, in the shared-wallet
|
||||
emulation, reads the deposits back (`read` / `materialize` / `watch`) in place
|
||||
of the recipient's own inbox processing.
|
||||
- Tests of the polyfill (against a real broker) live in this repo, so a consuming
|
||||
app can test its features against a clean, mocked API.
|
||||
- Tests of the polyfill (against a real broker) live in this repo, in **two** suites,
|
||||
and the split is deliberate: `packages/polyfill/e2e/run.ts` (`test:e2e`) characterises the
|
||||
primitives and the platform contracts, while `packages/polyfill/e2e/notebook.ts`
|
||||
(`test:e2e:app`) drives the example application through the DOM, one browser page per
|
||||
identity. Only the second can tell whether an application is *writable* — a harness
|
||||
can pass a value between two identities through a variable, and an application cannot.
|
||||
A consuming app can test its own features against a clean, mocked API.
|
||||
|
||||
## Status
|
||||
|
||||
Implemented. The polyfill mechanisms are wired against a real broker, not stubbed:
|
||||
|
||||
- Shared-wallet shim — `store-registry.ts` (`(account, scope) → document NURI`,
|
||||
`createEntityDoc` / `listEntityDocs` + per-scope index, cross-device via the RDF
|
||||
- Shared-wallet shim — `shared-wallet/account-registry.ts` (`(account, scope) → document NURI`,
|
||||
`createEntityDoc` / `listMyEntityDocs` + per-user stores, cross-device via the RDF
|
||||
shim anchored in the private store).
|
||||
- Document / SPARQL primitive — `docs.ts`, calling the real injected `ng` directly
|
||||
(avoids the `@ng-org` double-proxy `DataCloneError`).
|
||||
- Emulated ReadCaps — `caps.ts` (`CapRegistry`, per-document, directed grants) +
|
||||
read filter `read-filter.ts` (reactive-set `Proxy` view), applied by
|
||||
`use-shape.ts` only when a policy is declared.
|
||||
- Write guard — `ng-proxy.ts` (`sparql_update` override, emulated write cap).
|
||||
- Emulated ReadCaps — `emulated-verifier/caps.ts` (`CapRegistry`, per-document, directed grants) +
|
||||
read filter `emulated-verifier/read-filter.ts` (reactive-set `Proxy` view), applied by
|
||||
`surface/use-shape.ts` only once a cap exists (`caps.isEnforcing()`).
|
||||
- Write guard — `surface/ng-proxy.ts` (`sparql_update` override, emulated write cap).
|
||||
- Inbox — `inbox.ts` (`post` / `read` / `materialize` / `watch`).
|
||||
- Identity — `accounts.ts` (`IdentityStore`, injected storage).
|
||||
- Identity — `shared-wallet/virtualUsers.ts` (`IdentityStore`, injected storage).
|
||||
- SPARQL hardening — `sparql.ts` (`escapeLiteral` / `escapeIri` / `assertNuri`).
|
||||
|
||||
The remaining `TODO` markers are narrow: the shared-wallet credential passthrough
|
||||
|
||||
@@ -0,0 +1,858 @@
|
||||
# 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` (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.
|
||||
|
||||
**Scope.** The real exported surface of `@ng-eventually/polyfill` (verified against the `export` statements in `packages/polyfill/src/index.ts` — `package.json` maps exactly one entry point, `.`), and, for each subject, the target signature the future NextGraph JS SDK is expected to expose. Written 2026-08-03, verified against the `nextgraph-rs` clone (HEAD `213338f6`, 2026-05-16) and the installed `@ng-org/web@0.1.2-alpha.13` type 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 to read the epistemic labels.** Every target-side claim carries one of:
|
||||
|
||||
- **PASSTHROUGH (level 3 / level 2, VERIFIED)** — the target function exists today; the lib forwards to it. Citation into `nextgraph-rs` or the installed `.d.ts`. Level numbers per `README.md` § *The three references*: 3 = JS ORM (`sdk/js/orm`), 2 = wasm binding / `@ng-org/web` (`sdk/js/lib-wasm`, `sdk/js/web`), 1 = Rust engine (`engine/`).
|
||||
- **LEVEL-1 SHAPE (model VERIFIED, JS surface ASSUMED)** — the engine's model constrains the shape and is cited, but **no JS surface exists at any level**, so the signature offered here is this library's invention. The future SDK's name and parameter order for it are unknown.
|
||||
- **ASSUMPTION** — nothing at any layer constrains this; the bet and what bounds it are stated.
|
||||
- **NO COUNTERPART** — the subject has no image in the target at any layer, usually because it is shared-wallet machinery that disappears at migration. That is a finding about the emulation, not a gap in the target.
|
||||
|
||||
Per the design principle (`README.md` § *Design principle*): an absent implementation is never treated as evidence about the future — "the engine does not do X" and "the SDK will not offer X" are kept apart throughout.
|
||||
|
||||
### The per-symbol annotations are the authority; this document is the reasoning
|
||||
|
||||
Since 2026-08-16 every published symbol — and every internal one that claims to mirror the target — carries its provenance **in the source, beside the declaration**, pinned by `packages/polyfill/test/provenance.test.ts`:
|
||||
|
||||
```text
|
||||
// @provenance <name> kind=<kind> level=<1|2|3|none> ref=<path:symbol|none> — <note>
|
||||
```
|
||||
|
||||
It exists because this document could not stop drifting from the code: it claimed a "1:1 passthrough" for `docs.*` that was false in two ways, and `emulated-verifier/branch-registers.readLinks` was classified as this library's own invention when it implements `AddLinkV0` — a type the engine **defines** and constructs nowhere. That second mistake is the one the annotations are designed against: *nothing constructs this upstream* is an **absence**, and an absence is not evidence that a thing is ours.
|
||||
|
||||
The `ref` cites a **symbol**, never a line number — three citations in this document had already rotted (§ 2, § 4, § 12 below).
|
||||
|
||||
The prose labels above map onto the annotation's closed `kind` set, and where they disagree **the annotation wins**:
|
||||
|
||||
| label here | annotation `kind` | |
|
||||
|---|---|---|
|
||||
| PASSTHROUGH | `passthrough` | only when the name and shape are upstream's OWN, so the call site survives migration untouched |
|
||||
| PASSTHROUGH | `aligned` | when the semantics are upstream's but the name or the ergonomics are ours (`docCreate` for `doc_create`, a `label` parameter that is not forwarded) — § 7, § 8 |
|
||||
| LEVEL-1 SHAPE | `aligned` / `declared-not-wired` | the two are NOT the same claim: `aligned` means the engine does this and we follow it; `declared-not-wired` means the engine **defines** the type and constructs it nowhere |
|
||||
| ASSUMPTION / NO COUNTERPART | `invention` | nothing at any level answers; `ref` is `none`, deliberately |
|
||||
| *(no prose label)* | `divergent` | upstream does this and we do it differently — the inbox-address publication, the re-readable deposit list |
|
||||
|
||||
---
|
||||
|
||||
## 1. Bootstrap and configuration
|
||||
|
||||
### Today — `@ng-eventually/polyfill`: **one call**
|
||||
|
||||
```ts
|
||||
// shared-wallet/bootstrap.ts
|
||||
export interface EventuallyConfig {
|
||||
ng: NgLike; // the REAL @ng-org/web ng
|
||||
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;
|
||||
init?: (...args: any[]) => any;
|
||||
initNg?: (...args: any[]) => any;
|
||||
}
|
||||
export function configure(c: EventuallyConfig): void;
|
||||
```
|
||||
|
||||
**The count is the contract here.** The agreed target was two polyfill-era calls, or one; it had drifted to four, and each extra one was a reason the LIBRARY has rather than a need an application has. Four became one on 2026-08-07:
|
||||
|
||||
| Was published | Where it went |
|
||||
|---|---|
|
||||
| `configureStoreRegistry` + `StoreRegistryDeps` | folded into `configure` — two bootstrap calls existed because the library has two internals, which is not a reason a caller should pay |
|
||||
| `setCurrentUser` | the access gate sets the identity (§ 2bis). An application naming its own identity is the gesture that INVERTS the model; it must not have a published call to reach for |
|
||||
| `connectedUser` | `ensureIdentity` awaits it. Upstream, opening the session IS the connection — no application awaits a second call |
|
||||
| `getConfig`, `getStoreRegistryDeps`, `resetConfig`, `resetStoreRegistry` | internal wiring and test resets, reached by their internal path (2026-08-07, with the entry merge) |
|
||||
|
||||
**And two FIELDS of that one call, on 2026-08-12.** The count was already one; what was left inside it still made an application build things the target never asks anyone to build:
|
||||
|
||||
| Was published | Where it went |
|
||||
|---|---|
|
||||
| `getSession` (and the `RegistrySession` type with it, § 12) | the package's. Upstream a session is **returned** — `init()`'s callback delivers `{ status: "loggedin", session }` (`@ng-org/web` `dist/ngweb.js:124`, VERIFIED) and `session_start` hands one back; nowhere does an application ASSEMBLE one out of `session_id` / `private_store_id` / …. Every consumer wrapped `init()` in a promise and wrote the same unwrapping thunk, with nothing to migrate it to. The lib's `init` wrapper captures the event on its way through (§ 2) and holds the session (`shared-wallet/session.ts`) |
|
||||
| `normalizeId` | the package's, as `normalizeIdentityId` — trim, strip a leading `@`, lowercase. The identities it keys are the shared wallet's own virtual users, so there was never a decision here for a consumer to make; and one rule in one place is what stops the barrier, the URL and storage keying onto three different spaces |
|
||||
|
||||
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.
|
||||
|
||||
**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
|
||||
|
||||
**NO COUNTERPART, by design.** The whole subject is the polyfill bootstrap: it exists to inject the real SDK without a hard import (build-alias safety). At migration the consumer initializes the real SDK directly, with the two calls in § 2, and `configure` / `configureStoreRegistry` are deleted (`docs/migration-guide.md` § 7). Nothing in the target takes an "injected `ng`".
|
||||
|
||||
---
|
||||
|
||||
## 2. Lifecycle
|
||||
|
||||
### Today — `@ng-eventually/polyfill`
|
||||
|
||||
```ts
|
||||
// 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(),
|
||||
// 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 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
|
||||
export declare const init: (callback: Function | null, singleton: boolean, access_requests: any) => Promise<void>;
|
||||
|
||||
// level 3 — @ng-org/orm: sdk/js/orm/src/connector/initNg.ts:51 (exported as initNg from core.ts)
|
||||
export function initNgSignals(ngImpl: NG, session: Session): void;
|
||||
|
||||
// level 2 — the Session initNg consumes: index.d.ts:265-273 (source sdk/js/web/src/index.ts:15-22)
|
||||
export declare type Session = {
|
||||
session_id: string | number;
|
||||
protected_store_id: string;
|
||||
private_store_id: string;
|
||||
public_store_id: string;
|
||||
ng: typeof NGModule;
|
||||
[key: string]: unknown;
|
||||
};
|
||||
```
|
||||
|
||||
`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.
|
||||
|
||||
---
|
||||
|
||||
## 2bis. The access gate — `ensureIdentity`
|
||||
|
||||
### Today — `@ng-eventually/polyfill`
|
||||
|
||||
```ts
|
||||
export async function ensureIdentity(): Promise<PrincipalId>; // shared-wallet/access-gate.ts
|
||||
export interface SharedWalletConfig { fileUrl: string; password: string; importUrl?: string }
|
||||
```
|
||||
|
||||
One call, before the application renders. It resolves the identity from the URL (`?ng-id=`), failing that from browser storage — and top-level it shows the barrier anyway, with whatever it found already in the field: download the shared wallet, here is its password, import it once, and name your space. Knowing who someone is says nothing about whether their browser still holds the wallet, and the barrier is the only place it is handed out. Past the broker round-trip, inside the iframe, a known identifier stands it down.
|
||||
|
||||
It takes no timeout and needs none: the session it waits for arrives through this package's `init` and nowhere else, so awaited before that call it throws, naming the call to make first (`shared-wallet/access-gate.ts`, `refuseAWaitNothingCanEnd`).
|
||||
|
||||
### Target
|
||||
|
||||
**NO COUNTERPART in substance, and a surviving CALL SITE — this section exists because those two are not the same thing.**
|
||||
|
||||
The substance is pure scaffolding. Every step it performs exists only because one wallet hosts several identities: upstream a user opens THEIR wallet, it contains THEIR site (`SensitiveWalletV0.personal_identity()`, `engine/wallet/src/types.rs:576-579`), and `session_start(wallet_name, user_id)` takes an id that came FROM the wallet. There is nothing to name and nothing to choose. The step that takes an identifier is the one that inverts the model, and it is the reason the whole gate is scaffolding.
|
||||
|
||||
The call site is a different matter. An application still has to wait for a session before it renders, and that will still be one awaited call at the same place. So the signature was designed to survive: **it takes no identifier and RETURNS one**, deliberately. Naming an identity is the part that disappears, so it must not be a parameter; but knowing which identity you are is something an application legitimately has upstream — it passes `user_id` to `session_start(wallet_name, user_id)` (`index.d.ts:276`), having got it from the wallet it opened. Here the gate chooses it, so the gate hands it back. Without that, the example application had to read the gate's own private storage key.
|
||||
|
||||
What a consumer must NOT conclude:
|
||||
|
||||
- that it may pass an identity in (it cannot — that is the point);
|
||||
- that the barrier is a product screen. It is a technical gate, rendered in plain DOM inside a shadow root so no application stylesheet reshapes it and its own leaks nowhere. It is deliberately not bound to a UI framework: a screen that is going away must not make every consumer adopt one.
|
||||
- that `SharedWalletConfig` describes a user setting. It describes what a DEPLOYMENT hands out, and it disappears with the gate. The library reads no environment variable, ever — the application resolves these values at its own build and passes them.
|
||||
|
||||
Why it lives here and not in the consumer application: the first consumer had ~300 lines of it — a gate component, a screen, a wallet module, an identity context, three BDD features. That is code an application would have to delete, and worse, code that teaches its authors a model NextGraph does not have (*"I name my identity"*).
|
||||
|
||||
---
|
||||
|
||||
## 3. The `ng` object
|
||||
|
||||
### Today — `@ng-eventually/polyfill`
|
||||
|
||||
```ts
|
||||
// index.ts:152
|
||||
export const ng: NG;
|
||||
// type re-export, index.ts:86
|
||||
export type { NG } from "@ng-org/web";
|
||||
```
|
||||
|
||||
`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`, **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.
|
||||
- `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.
|
||||
|
||||
---
|
||||
|
||||
## 4. Reactive typed reads — `useShape`
|
||||
|
||||
### Today — `@ng-eventually/polyfill`
|
||||
|
||||
```ts
|
||||
// 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 } from "@ng-org/shex-orm";
|
||||
```
|
||||
|
||||
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).** 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
|
||||
const useShape = <T extends BaseType>(
|
||||
shape: ShapeType<T>,
|
||||
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
|
||||
// follow reads as verified and is not — the reason the per-symbol annotations below cite a
|
||||
// SYMBOL rather than a line.)*
|
||||
export type Scope = {
|
||||
graphs?: string[] | string;
|
||||
subjects?: string[];
|
||||
};
|
||||
```
|
||||
|
||||
The read filter disappears at migration: in the target, isolation is cryptographic — a repo whose cap the wallet does not hold is never decrypted, a union read over it yields nothing, and a targeted read errors `RepoNotFound` (`engine/verifier/src/request_processor.rs:155,163` via `resolve_target`). VERIFIED at level 1; the *consumer-visible* result (you only see what you hold) is the same, which is the point of the emulation.
|
||||
|
||||
Divergence to note: the wrapper types everything `unknown`, losing the generic `T`. A consumer wanting typed sets today must cast; at migration the real generic signature gives it back. Nothing to unlearn, only ergonomics deferred.
|
||||
|
||||
---
|
||||
|
||||
## 5. Reactive typed reads with load state — `useShapeQuery`
|
||||
|
||||
### Today — `@ng-eventually/polyfill`
|
||||
|
||||
```ts
|
||||
// use-shape-query.ts — ShapeQuery
|
||||
export interface ShapeQuery<T extends BaseType = BaseType> {
|
||||
data: T[];
|
||||
isPending: boolean;
|
||||
isSuccess: boolean;
|
||||
isError: boolean;
|
||||
error: unknown;
|
||||
}
|
||||
// use-shape-query.ts — ShapeObservable
|
||||
export interface ShapeObservable<T extends BaseType = BaseType> {
|
||||
getSnapshot(): ShapeQuery<T>;
|
||||
subscribe(onChange: () => void): () => void;
|
||||
refetch(): void;
|
||||
}
|
||||
// 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>;
|
||||
```
|
||||
|
||||
**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`.
|
||||
|
||||
### Target
|
||||
|
||||
**Partly ASSUMPTION — flagged deliberately.** `surface/watch-shape.ts`'s header says it "anticipates NextGraph's planned `useShape(shape, scope)` upgrade, which will natively distinguish 'sync in progress' from 'synced but empty'". **No provenance for that plan exists in this repo's docs or in the `nextgraph-rs` clone** — treat the "planned upgrade" as an assumption, not a stated NextGraph direction. What IS verified at level 3 is that the distinction is *expressible* today, just not through the hook:
|
||||
|
||||
```ts
|
||||
// level 3, VERIFIED — sdk/js/orm/src/connector/GraphOrmSubscription.ts:228,260,274
|
||||
OrmSubscription.getOrCreate<T extends BaseType>(shape: ShapeType<T>, scope: NormalizedScope): OrmSubscription<T>;
|
||||
get readyPromise(): Promise<void>; // resolves when the subscription is synced — the native "no longer pending" signal
|
||||
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. `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. **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 reading by name — the anchored query, and nothing above it
|
||||
|
||||
### Today — `@ng-eventually/polyfill`
|
||||
|
||||
```ts
|
||||
// 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>;
|
||||
```
|
||||
|
||||
**`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.**
|
||||
|
||||
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:
|
||||
|
||||
```ts
|
||||
// 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
|
||||
export async function getObjects<T extends BaseType>(
|
||||
shapeType: ShapeType<T>,
|
||||
scope: Scope | string
|
||||
); // 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`). 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.
|
||||
|
||||
---
|
||||
|
||||
## 7. Raw document / SPARQL primitives — `docs.*`
|
||||
|
||||
### Today — `@ng-eventually/polyfill` (namespace `docs`)
|
||||
|
||||
```ts
|
||||
// docs.ts:53
|
||||
export async function docCreate(
|
||||
sessionId: string | number,
|
||||
crdt: string,
|
||||
cls: string,
|
||||
dest: string,
|
||||
store?: unknown,
|
||||
): Promise<Nuri>;
|
||||
// docs.ts:101
|
||||
export async function sparqlUpdate(
|
||||
sessionId: string | number,
|
||||
query: string,
|
||||
anchor?: Nuri,
|
||||
label = "sparqlUpdate",
|
||||
): Promise<unknown>;
|
||||
// docs.ts:146
|
||||
export async function sparqlQuery(
|
||||
sessionId: string | number,
|
||||
query: string,
|
||||
base?: string,
|
||||
anchor?: Nuri,
|
||||
label = "sparqlQuery",
|
||||
): Promise<unknown>;
|
||||
// docs.ts:113 — machinery, see § 15
|
||||
// NOT published since 2026-08-07 — moved to `emulated-verifier/register-write.ts`.
|
||||
// It skips the boundary by design ("the one write that legitimately crosses"), and a door
|
||||
// that skips a guard must not be one an application can open: holding nothing but a public
|
||||
// document's bare reference, one could rewrite the inbox address posted on it and divert
|
||||
// every deposit meant for its owner. Go through `inbox.post` / `inbox.share`.
|
||||
```
|
||||
|
||||
### Target
|
||||
|
||||
**Annotated `aligned` (level 2, VERIFIED) — not `passthrough`, and the distinction is the point.** These forward to the real methods with the same arguments in the same order, but the names are ours (`docCreate` for `doc_create`) and they take a trailing `label` (a lib-internal access-log tag) the real signatures have no room for. So the *semantics* survive migration and the *call site* does not — which is exactly what `aligned` says and what a blanket "PASSTHROUGH" hid. *(This entry said PASSTHROUGH until 2026-08-16; it had already been caught claiming a 1:1 mirror, false in two ways, both fixed rather than documented as deltas:)*
|
||||
|
||||
- **The session id is `string | number`, upstream's own declared type for it** (`Session.session_id`, `sdk/js/web/src/index.ts:16` and the installed `index.d.ts:266`) — it used to be narrowed to `string` here, which made the value the SDK hands an application impossible to pass back into this library. It is RELAYED, never converted: the wasm side deserializes a `u64` (`sdk/js/lib-wasm/src/lib.rs:352-358` `sparql_query`, `:452-457` `sparql_update`, `:1575` `doc_create`), and stringifying it fails that deserialization for real — observed as `Deserialization error of session_id JsValue("1")`.
|
||||
- **`sparqlUpdate` returns what the real method returns** — the commits the update produced (`lib.rs:481-483` serialises `AppResponseV0::Commits`; the installed `index.d.ts:297` types it `Promise<any>`). It was declared `Promise<void>` while already relaying the value at runtime, so the answer was thrown away for every caller. Typed `unknown` rather than `any`, exactly as `sparqlQuery` already renders the same upstream `Promise<any>`. A caller that ignores it is unaffected.
|
||||
|
||||
The real signatures forwarded to:
|
||||
|
||||
```ts
|
||||
// index.d.ts:60 — the installed web SDK's doc_create
|
||||
declare function doc_create(session_id: any, crdt: string, class_name: string, destination: string, store_repo: any): Promise<any>;
|
||||
// index.d.ts:297
|
||||
declare function sparql_update(session_id: any, sparql: string, nuri: any): Promise<any>;
|
||||
// index.d.ts:295
|
||||
declare function sparql_query(session_id: any, sparql: string, base: any, nuri: any): Promise<any>;
|
||||
```
|
||||
|
||||
`depositInto` has **NO COUNTERPART as a SPARQL write**: upstream a deposit is a sealed message, not an update into the recipient's graph (§ 9). It exists only because the emulated inbox is an RDF document — and it is no longer published (see the block above).
|
||||
|
||||
**Store targeting — finer than "not JS-constructible".** *(The other docs were corrected on 2026-08-03 to match this entry; they used to state the blanket form.)* Verified in the clone:
|
||||
|
||||
- The **web** wasm variant (`sdk/js/lib-wasm/src/lib.rs:1575`, `#[cfg(not(wasmpack_target = "nodejs"))]`) deserializes its 5th argument as `Option<StoreRepo>` via serde — so a value CAN be passed, but no JS helper exists to build the serde form, which keeps it out of practical reach. The published `.d.ts` documents this 5-arg form.
|
||||
- The **nodejs** variant (`lib.rs:1618`, 6 args) takes `store_type: Option<String>` + `store_repo: Option<String>` and builds the store via `StoreRepo::from_type_and_repo(store_type, repo_id_str)` with `store_type ∈ "public" | "protected" | "private" | "group"` (`sdk/rust/src/local_broker.rs:2969-2987`, `engine/repo/src/types.rs:819-828`).
|
||||
|
||||
So the target's direction for scope placement is **already visible in the source** (level 2, VERIFIED, nodejs SDK): name the store by type + repo id strings. The migration-guide's anticipated `getNativeStore(scope)`-style resolver should expect to produce exactly that pair (or the serde `StoreRepo` once a web helper lands) — not a new concept.
|
||||
|
||||
---
|
||||
|
||||
## 8. Per-document subscription — `subscribeDoc`
|
||||
|
||||
### Today — `@ng-eventually/polyfill`
|
||||
|
||||
```ts
|
||||
// subscribe.ts:47,60,79
|
||||
export type DocChange = unknown;
|
||||
export type DocChangeType = string | undefined;
|
||||
export type Unsubscribe = () => void;
|
||||
// subscribe.ts:69
|
||||
export function docChangeType(resp: DocChange): DocChangeType;
|
||||
// subscribe.ts:104
|
||||
export function subscribeDoc(
|
||||
nuri: Nuri,
|
||||
onChange: (r: DocChange, type: DocChangeType) => void,
|
||||
): Unsubscribe;
|
||||
// subscribe.ts:184
|
||||
export function subscribeDocs(
|
||||
nuris: Nuri[],
|
||||
onChange: (nuri: Nuri, r: DocChange, type: DocChangeType) => void,
|
||||
): Unsubscribe;
|
||||
```
|
||||
|
||||
### Target
|
||||
|
||||
**Annotated `aligned` (level 2, VERIFIED) — the deltas below are what makes it `aligned` rather than `passthrough`:**
|
||||
|
||||
```ts
|
||||
// index.d.ts:66, source sdk/js/lib-wasm/src/lib.rs:1908
|
||||
declare function doc_subscribe(repo_o: string, session_id: any, callback: Function): Promise<any>;
|
||||
```
|
||||
|
||||
- The real call is `async` and resolves to an unsubscribe function; the wrapper returns the unsubscribe **synchronously** and honours an early cancel when the promise settles. A consumer coding against the sync return will keep working against the real SDK only through an adapter — a small, known unlearn, traded for not forcing `await` on every subscription site.
|
||||
- The real callback receives one argument, the serialized `AppResponse` (`{ V0: { State | Patch | TabInfo | … } }`); the wrapper adds a second, pre-extracted `type`. `docChangeType` is a convenience over the verified payload shape (pinned by the e2e CONTRACT-3 probe), not an upstream API.
|
||||
- `subscribeDocs` has **NO COUNTERPART and needs none**: it is client-side composition (a set of `doc_subscribe` with per-doc error isolation). The upstream fan-out primitive that looks like it (`orm_start_graph(graph_scope, …)`, `index.d.ts:243`) aborts wholesale on one `RepoNotFound` (`sdk/js/orm` → `engine/verifier/src/request_processor.rs:53-66`) — the reason this composition exists.
|
||||
|
||||
---
|
||||
|
||||
## 9. Inbox — deposits, and cap delivery
|
||||
|
||||
### Today — `@ng-eventually/polyfill` (namespace `inbox`)
|
||||
|
||||
```ts
|
||||
export interface Deposit {
|
||||
from: PrincipalId | null;
|
||||
payload: unknown;
|
||||
ts: number;
|
||||
}
|
||||
export interface PostOptions {
|
||||
from?: PrincipalId | null;
|
||||
payload: unknown;
|
||||
ts?: number;
|
||||
}
|
||||
export async function post(targetInbox: NuriLike, opts: PostOptions): Promise<void>;
|
||||
export async function postToDocument(doc: NuriLike, opts: PostOptions): Promise<void>;
|
||||
export async function share(doc: NuriLike, toUser: string): Promise<void>;
|
||||
export async function read(targetInbox: NuriLike): Promise<Deposit[]>;
|
||||
export async function readForDocument(doc: NuriLike): Promise<Deposit[]>;
|
||||
// `materialize` — a second published name for `read` — was REMOVED on 2026-08-14. It was
|
||||
// an alias and nothing else: no call site, and upstream has no such member, so it was a
|
||||
// symbol an application could learn and would then have to unlearn. Use `read`.
|
||||
export async function readSynced(targetInbox: NuriLike): Promise<Deposit[]>;
|
||||
export async function readSyncedForDocument(doc: NuriLike): Promise<Deposit[]>;
|
||||
export async function processInbox(targetInbox: NuriLike): Promise<Deposit[]>;
|
||||
export function watch(
|
||||
targetInbox: NuriLike,
|
||||
onDeposits: (deposits: Deposit[]) => void,
|
||||
_opts?: { intervalMs?: number },
|
||||
): () => void;
|
||||
```
|
||||
|
||||
### Target
|
||||
|
||||
**LEVEL-1 SHAPE throughout — the model is VERIFIED, every JS signature here is this library's invention.** There is no inbox method in `@ng-org/web` (none in the 77 `index.d.ts` exports, re-verified), and the verifier's dispatch has no `InboxPost` arm (arms actually handled listed at `engine/verifier/src/request_processor.rs:53-1444`, re-verified). The engine model that constrains the shape:
|
||||
|
||||
- An inbox is a keypair on **exactly one repo**: `pub inbox: Option<PrivKey>` (`engine/repo/src/repo.rs:126`); routing is `inboxes: HashMap<PubKey, RepoId>` on the verifier (`engine/verifier/src/verifier.rs:105`, looked up at `:1677`, inserted at `:1928`).
|
||||
- A message is sealed to the inbox pubkey and carries **no target document** — `InboxMsgBody { to_overlay, to_inbox: PubKey, from_overlay: Option<OverlayId>, from_inbox: Option<PubKey>, … }` (`engine/net/src/types.rs:4265`). The address identifies the recipient repo; nothing else is needed. This is why `Deposit` has no document field and why `post` takes only the inbox NURI.
|
||||
- `from` optional upstream (`from_inbox: Option<PubKey>`) — the "identified if known, anonymous otherwise" behaviour `PostOptions.from` mirrors, including the `null`-means-anonymous case.
|
||||
- The recipient's own verifier unseals and **applies** queued messages when it processes its inbox (`engine/verifier/src/verifier.rs:1674-1690` → `process_inbox`); an inbox is a consumed queue, not a store you re-read.
|
||||
|
||||
Consequences per function:
|
||||
|
||||
- `post` / `postToDocument` — the sender-side act exists in the model (the broker routes `InboxPost` natively, `engine/net/src/server_broker.rs`); its JS surface does not. **The future SDK's name and signature are unknown** — `docs/nextgraph-current-state.md:187` records that nothing is announced. `postToDocument`'s resolution step (find the document's inbox address) rides on a **deliberate divergence**: this lib PUBLISHES the address on the document (Header-branch emulation), whereas upstream an address is only ever TRANSMITTED (`ContactDetails` carries `ng:site_inbox`/`ng:protected_inbox`, `engine/verifier/src/inbox_processor.rs:778-830`; the address→repo association lives in `inboxes: PubKey → RepoId`, a table of the **verifier** — one per user, `verifier.rs:105`). *(Corrected 2026-08-10: this said the table was "session-local, rebuilt empty". It is initialized empty (`verifier.rs:520,2820`) and then repopulated at every load — `Verifier::load` → `add_repo_without_saving` → `add_repo_`, `verifier.rs:534-566,2871,2887` — with the inbox private key persisted per repo, `user_storage/repo.rs:61,171,207,362`. The property that matters is that it is **per verifier**, not that it is ephemeral.)* Documented in `docs/briefs/2026-08-03-document-inbox-addressing.md`.
|
||||
- `share` — a **gap upstream, not a disagreement**, verified at both ends: `ContactDetails.read_cap: Option<ReadCap>` exists (`engine/net/src/types.rs:4233`) but building a message with it is `unimplemented!()` (`types.rs:3786`), its only caller passes `with_readcap: false`, and the receiving arm never reads the field (`inbox_processor.rs:778-830`). `InboxMsgContent::Link` is a **unit variant carrying nothing** (`types.rs:4252`) — do not read it as the delivery channel. The recipient-side filing the lib emulates is real: `AddLink { read_cap }` on the User branch (`engine/repo/src/types.rs:1939-1948`). The consumer's *act* (share one document's cap to one inbox) is target-shaped; only the transport is emulated.
|
||||
- `read` / `readSynced` / `readSyncedForDocument` / `processInbox` / `watch` — **stand-ins for the recipient's own verifier processing**, which has no consumer-facing JS surface upstream and may never have this list-of-deposits shape. A consumer should treat "my inbox gets processed when I connect, and applied caps just appear in what I hold" as the durable contract (that is what `connectedUser` automates, § 13); code that leans on enumerating raw deposits as a mailbox UI is coding against emulation detail it may have to unlearn. The consumer-payload case (`Deposit.payload` as app data) maps to `InboxMsgContent` variants upstream (`types.rs:4249-4260`), of which only `ContactDetails` and `SocialQuery` are more than unit variants today — arbitrary app payloads through the inbox are an **ASSUMPTION**, constrained by the model only in that messages are sealed, per-recipient, and applied by the recipient.
|
||||
- `readForDocument(doc)` — the owner's side of a document's inbox, named by the DOCUMENT. Same LEVEL-1 SHAPE ruling as `read`: it is the recipient's own processing, which has no consumer-facing JS surface upstream, and enumerating its deposits is emulation detail. It exists so an application never handles an inbox address. It is the WARM form (it delegates to `read`), so on a session that has just loaded it can answer `[]` for a document that has deposits.
|
||||
- `readSyncedForDocument(doc)` — added 2026-08-17, the intersection the surface was missing: `readSynced`'s barrier on `readForDocument`'s address. **What an application no longer does: resolve an inbox address itself.** It had to, because materializing deposits needs both halves and only one call carried each — and resolving an address is the exact gesture § *Guarantees* says an application never performs. The document-addressed path crosses TWO repos and a cold session loses the answer at either: the address is read off the DOCUMENT's Header branch, so an unsynced document reads as "no inbox"; the deposits are read off the INBOX, which is what `readSynced` gates. This gates both, document first. Same LEVEL-1 SHAPE ruling as `read` and the same fate — it adds no divergent ACT, it composes two published ones so the caller does not have to hold an address to reach them (`packages/polyfill/test/cold-read-for-document.test.ts` pins the pair: on one cold state, `readForDocument` answers empty and this answers the message).
|
||||
- `share(doc, toUser)` **refuses an unknown recipient** since 2026-08-10. It used to provision one: a mistyped name minted that name's stores and an inbox, and the cap landed where nobody looks. Upstream a deposit is sealed to an inbox pubkey that reached you through an inbound contact, so you cannot address a name you invented.
|
||||
- `watch`'s `_opts?: { intervalMs?: number }` is accepted and **ignored** (kept for signature compatibility with a removed polling watcher) — dead surface, see § 15.
|
||||
|
||||
---
|
||||
|
||||
> **Known divergence, low impact today — `inbox.share` always deposits on the recipient's PROTECTED inbox.** Upstream the choice follows the profile through which the person was reached (`a_or_b = if details.profile.is_public() { "site" } else { "protected" }`, `engine/verifier/src/inbox_processor.rs:787`). This library has no notion of "which profile I know this person by", so it picks one. It flattens a distinction the model makes; it will be wrong the day an application shares with someone met through a public profile. Recorded rather than fixed, because the fix needs a notion nothing here has established — note that the `Identity` enum that would name it is entirely commented out upstream (`engine/repo/src/types.rs:586-595`), so there is no profile model to read yet.
|
||||
|
||||
## 10. Capabilities — possession, not ACL
|
||||
|
||||
### Today
|
||||
|
||||
```ts
|
||||
// @ng-eventually/polyfill — model/types.ts. The published cap surface is now ONE type.
|
||||
export type Nuri = `did:ng:${string}`;
|
||||
export type NuriLike = Nuri | string;
|
||||
|
||||
// NOT published, each deliberately:
|
||||
// ReadCap — `did:ng:${string}:r:${string}`. Unpublished 2026-08-10, when
|
||||
// `export * from "./model/types"` became a named list. It remains the library's
|
||||
// internal type for a cap-bearing reference, but NO published signature takes or
|
||||
// returns one: within `surface/inbox.ts` only two private helpers use it
|
||||
// (`capsSeenIn`, `capOfPayload`), plus the emulated registers. Publishing it named
|
||||
// the one value the model says must never be handed over on request (§ 0 of
|
||||
// `readcap-and-nuri-model.md`) — while leaving no published call able to produce
|
||||
// one, since `linkTo` was removed and `mintCap` is unreachable (§ 11). A type whose
|
||||
// only possible use by a consumer is a cast is worse than no type. See § 14.
|
||||
// InboxScope — unpublished the same day, same rule: its only user is
|
||||
// `account-registry.userInbox(id, scope)`, which is not published (§ 12).
|
||||
// isNuri / hasReadCap — the type guards (`model/nuri.ts`). Unpublished since the
|
||||
// permissive-in change: every entry takes `NuriLike` and validates at the door, so
|
||||
// a consumer holding a plain string narrows nothing. Publishing a guard would
|
||||
// invite the cast it exists to prevent.
|
||||
// hasCap(doc) — removed 2026-08-06. It read like "may I read this?", and a
|
||||
// document in a public store answers `false` until something asks for its cap.
|
||||
// getCaps / CapRegistry / resetCaps — the emulation's engine room and its test reset.
|
||||
|
||||
// INTERNAL — `emulated-verifier/caps.ts` (class CapRegistry). Never published; listed for the maintainer.
|
||||
constructor(holder?: () => PrincipalId | null);
|
||||
mint(nuri: Nuri): ReadCap;
|
||||
learn(cap: ReadCap): void;
|
||||
capFor(nuri: Nuri): ReadCap | undefined;
|
||||
learnFromPublicStore(cap: ReadCap): void; // a cap the public store SERVED — read only
|
||||
isReadOnlyPublicCap(nuri: Nuri): boolean;
|
||||
markInPublicStore(nuri: Nuri): void;
|
||||
isInPublicStore(nuri: Nuri): boolean;
|
||||
open(nuri: Nuri, scope: Scope): ReadCap;
|
||||
isEnforcing(): boolean;
|
||||
onChange(listener: () => void): () => void;
|
||||
grantWrite(doc: Nuri, principal: PrincipalId): void; // decorative until cap-enforcement
|
||||
governsWrite(doc: Nuri): boolean; // decorative until cap-enforcement
|
||||
canWrite(doc: Nuri, principal: PrincipalId | null): boolean; // decorative until cap-enforcement
|
||||
hasWritePolicy(): boolean; // decorative until cap-enforcement
|
||||
clear(): void;
|
||||
```
|
||||
|
||||
### Target
|
||||
|
||||
**LEVEL-1 SHAPE.** There is no capability API at level 2 or 3 (no cap method in `index.d.ts`, none in the ORM), and there is **nothing to introspect upstream**: reading is key possession. The model, VERIFIED:
|
||||
|
||||
- A ReadCap is the serialized `ObjectRef` — `format!("r:{}", base64_url::encode(&ser))` (`BlockRef::readcap_nuri`, `engine/repo/src/types.rs:518-521`). **The `r:` segment and its encoding are upstream's**, reported by NextGraph's developer and verified in that function: id and key are serialized together into ONE opaque segment, unlike the `:k:` object/file/commit forms where they are two. The lib's `ReadCap` template-literal type uses that segment, with the stand-in constant `OK` in place of the key material.
|
||||
- **"cap-enforcement swaps the value, not the shape" is a BET, and this section stated it as a fact until 2026-08-10.** What the source establishes is narrower, in three readings: (a) `readcap_nuri()` is produced as a **field value**, never concatenated onto a NURI — every call site fills `AppTabBranchInfo.readcap: Option<String>` (`engine/net/src/app_protocol.rs:1334`; `engine/verifier/src/verifier.rs:278,320`; `rocksdb_user_storage.rs:162,172`); (b) **no upstream parser accepts a repo NURI carrying `:r:`** — `NuriV0::new_from` (`app_protocol.rs:643-737`) tries `did:ng:i`, `RE_REPO_O`, `RE_FILE_READ_CAP`, `RE_REPO` and `RE_BRANCH`, and none of the regexes at `engine/net/src/types.rs:48-80` has an `r:` form; (c) the slot the type *declares* for a repo read cap is a **field** — `NuriV0.access: Vec<NgAccessV0>` with `NgAccessV0::ReadCap(ReadCap)` (`app_protocol.rs:54-62,192`) — itself constructed nowhere today (only `NgAccessV0::Key`, `:622`). Per the design principle none of that says the target will *not* parse a cap-bearing repo NURI; it says nothing parses one yet, so "the shape survives, only the value changes" is an assumption and not a passthrough. If the cap turns out to belong in a field, cap-enforcement moves it there instead of swapping a substring — a change the surface absorbs, because the value is opaque and nothing published parses it (§ 11).
|
||||
- Caps live in two durable registers by origin: created documents → `AddRepo { read_cap }` on the store's Store branch (`engine/repo/src/types.rs:1890-1899`, committed by `doc_create` via `send_add_repo_to_store`, `engine/verifier/src/request_processor.rs:698`); received caps → `AddLink { read_cap }` on the private store's User branch (`types.rs:1939-1948`).
|
||||
- The one path that loads a repo from a cap is `pub(crate)` — `Verifier::load_repo_from_read_cap` (`engine/verifier/src/verifier.rs:2237`) — unexposed to JS.
|
||||
|
||||
`capFor(nuri)` asks the only question the model admits — "do I hold this document's key?" — and returning `undefined` is the whole possible answer. There is no "may principal P read D?" anywhere, and the future SDK cannot offer one without inventing an ACL the engine does not have. That absence is a **finding about the target's model**, not a missing feature: a consumer should never expect a cap-introspection API.
|
||||
|
||||
The `CapRegistry` class itself is machinery (the in-memory record of what the connected holder holds — upstream's local user storage). It is not published at all: the consumer surface is the ACTS (creating a document, `inbox.share`, processing one's inbox — and, for a document in a public store, simply reading it), never a lookup; see § 15.
|
||||
|
||||
---
|
||||
|
||||
## 11. NURI and SPARQL string utilities
|
||||
|
||||
### Today — nothing. The entry publishes **no** string utility and **no** type guard.
|
||||
|
||||
```ts
|
||||
// NOT published — internal, and each for a stated reason:
|
||||
// surface/sparql.ts escapeLiteral, escapeIri, assertNuri
|
||||
// model/nuri.ts isNuri, hasReadCap, targetOf, parseNuri, toNuri
|
||||
// emulated-verifier/caps.ts mintCap (it lived in `model/nuri.ts` until the source
|
||||
// layout was reorganised by migration fate; this list
|
||||
// still said so until 2026-08-10)
|
||||
```
|
||||
|
||||
Two decisions meet here, and both point the same way.
|
||||
|
||||
**No guard, because the doors validate.** Every public entry takes `NuriLike` (`Nuri | string`) and runs `toNuri` itself — permissive in, precise out. A consumer holding a string from storage, a URL or a form passes it straight in; publishing a guard would invite the cast the types exist to prevent, and would put validation in the caller's hands where the door already does it.
|
||||
|
||||
**No `mintCap`, ever.** Nothing on the surface may turn a bare reference into a cap — that is the model's central invariant (§ 0 of `readcap-and-nuri-model.md`), so the function that could is unreachable from outside.
|
||||
|
||||
The escaping helpers were published until the surface was narrowed. Their removal costs a consumer nothing it will miss: they are generic injection-safety utilities, and neither `@ng-org/web` nor the ORM exposes an equivalent (re-verified against `index.d.ts` and `sdk/js/orm/src` — the engine escapes ad hoc where it builds SPARQL, e.g. `update_header`, `engine/verifier/src/request_processor.rs:196-208`). An application that interpolates SPARQL writes its own two-line escaper, against this lib or the real SDK alike.
|
||||
|
||||
### Target
|
||||
|
||||
**NO COUNTERPART at any level, and none expected** — which is precisely why none of it is published: a symbol with no successor, on a surface that promises one, is the thing this document exists to catch.
|
||||
|
||||
---
|
||||
|
||||
## 12. Scope resolution, per-entity documents, and the store registry
|
||||
|
||||
### 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
|
||||
// `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).
|
||||
interface VirtualUserRecord {
|
||||
id: string;
|
||||
docPublic: Nuri;
|
||||
docProtected: Nuri;
|
||||
docPrivate: Nuri;
|
||||
}
|
||||
// RegistrySession is INTERNAL since 2026-08-12 (shape kept here for the ruling below).
|
||||
interface RegistrySession {
|
||||
sessionId: string | number; // relayed untouched — upstream's own type (§ 7)
|
||||
privateStoreId: string;
|
||||
protectedStoreId?: string;
|
||||
publicStoreId?: string;
|
||||
}
|
||||
|
||||
// PUBLISHED — the whole `storeRegistry` namespace, and nothing else.
|
||||
// NO identity parameter, since 2026-08-10: a session belongs to one user, and the
|
||||
// target's own `doc_create(session_id, …)` carries no user at all. Passing one's own
|
||||
// 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.
|
||||
// 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.
|
||||
// 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
|
||||
// typed the session thunk it injected with it — and that thunk is gone (§ 1). Upstream a
|
||||
// session is RETURNED, never assembled, so no application has a session shape to declare.
|
||||
```
|
||||
|
||||
**`listMyEntityDocs` answers a VERIFIED listing, or it rejects — since 2026-08-17.** It stands on two reads of the store document, and both propagate: the Main branch says which documents are in there, the Store branch says what opens each. Handing back the listing over a key read that never answered was tolerated until then, on the ground that the array was already in hand by that point — which is exactly what made it a half-truth rather than a shortcut, since nothing distinguishes a listing you can open from one you cannot. It is the same `Nuri[]`; the difference shows at the next read, empty, with the cause long gone. It is the ruling the connection path already runs on, applied to the last call that escaped it: **a rejection means "unknown", never "absent"**, and only "there was nothing to do" resolves quietly — so an empty array here means this account created no document in that scope, and never that the store went unread.
|
||||
|
||||
**`openDocumentInbox` coalesces concurrent asks — and one JS realm is the honest extent of it, since 2026-08-17.** The call reads the User branch to find out whether an inbox is already recorded and mints when the answer is no, with a dozen awaits between the two. Callers that arrive together therefore all read before any of them writes: each read ANSWERS, each answer is honestly "none", and each mints. Nothing fails, which is what sets this apart from the read-that-could-not-answer family swept through this document — no rejection-means-unknown ruling touches it, only coalescing does. Reported from an application: four simultaneous calls on one document registered three inboxes, after which the owner drained one while deposits arrived in another. Asks for the same `(holder, document)` now share one call.
|
||||
|
||||
**What that does NOT reach, and why it cannot be fixed here.** Two tabs share no in-flight map, so the durable fork survives — and it is not a matter of doing more work. Preventing it needs a conditional write ("record only if absent"), which no level of the target offers: a branch is an add-only CRDT, so two `AddInboxCap` records merge rather than one being refused. Reconciling it afterwards the way `canonicalDoc` reconciles a forked account pointer does not work either, because the two sides read different records — the owner resolves from `AddInboxCap` on its User branch, a depositor from the address published on the document's Header branch, and the latter is written DELETE-then-INSERT, so it is last-write-wins and need not name the same one. Making both sides agree would mean letting a document accumulate two addresses to pick a canonical one from, and that is a state the target model has no meaning for: `inboxes: PubKey → RepoId` is a function (`engine/verifier/src/verifier.rs:105`) and `repo.inbox` a single `Option<PrivKey>`. So the gap is stated in the app contract as a non-guarantee rather than papered over. At migration it closes on its own — upstream an inbox is a keypair created WITH the repo, not a document minted on demand, so there is no read-then-write to race.
|
||||
|
||||
### Target — split by what each piece maps to
|
||||
|
||||
- **`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.
|
||||
- **`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).
|
||||
- **`resolveAccount` / `ensureAccount` / `VirtualUserRecord` / `RegistrySession` / `reservedAccount` / `resetRegistryCache` → NO COUNTERPART.** The shared-wallet shim (accounts directory, pointer → doc-shim indirection) has no image in the target — the target has no central directory of identities (`docs/migration-guide.md` § 3). The whole group disappears with the shim.
|
||||
- **`isOwnInbox` / `myInboxes` → NO COUNTERPART as API.** Upstream the question "which inboxes may I read" is answered inside the verifier by the User branch's `AddInboxCap` records; nothing suggests a JS API for it. These exist for the emulated read guard and the connection drain.
|
||||
|
||||
---
|
||||
|
||||
## 13. Identity and connection
|
||||
|
||||
### Today
|
||||
|
||||
```ts
|
||||
// PUBLISHED: nothing. Identity is established by `ensureIdentity()` (§ 2bis) and the
|
||||
// connection is awaited inside it.
|
||||
//
|
||||
// NOT published, and each removal is a gesture an application no longer performs:
|
||||
// setCurrentUser (2026-08-07) naming one's own identity — the step that inverts the
|
||||
// model. The gate does it; the e2e harness, which plays
|
||||
// several identities on one page, reaches it internally.
|
||||
// connectedUser (2026-08-07) awaited inside `ensureIdentity`; upstream, opening the
|
||||
// session IS the connection.
|
||||
// getCurrentUser (2026-08-05) an application knows who it signed in.
|
||||
// IdentityStore, browserIdentityStore, VirtualUserStorage, ACCOUNT_STORAGE_KEY
|
||||
// (2026-08-05) persisting an identity is the application's job
|
||||
// upstream too; the gate persists what IT needs.
|
||||
```
|
||||
|
||||
### Target
|
||||
|
||||
**PASSTHROUGH-to-be at level 2, VERIFIED signatures.** In the target the identity is established by opening one's own wallet and starting a per-user session — there is no "set the current user" call because the session IS the user:
|
||||
|
||||
```ts
|
||||
// index.d.ts:276, 280, 313, 315
|
||||
declare function session_start(wallet_name: string, user_id: any): Promise<any>;
|
||||
declare function session_stop(user_id: string): Promise<void>;
|
||||
declare function user_connect(client_info: any, user_id: string, location?: string | null): Promise<any>;
|
||||
declare function user_disconnect(user_id: string): Promise<void>;
|
||||
```
|
||||
|
||||
- `IdentityStore` / `browserIdentityStore` (the persisted identity id) — **NO COUNTERPART**; they exist only because every virtual user shares one wallet, and they are no longer published at all. Removed at migration (`docs/migration-guide.md` § 5).
|
||||
- `setCurrentUser` — **NO COUNTERPART**; the relay of an identity the broker cannot see. Disappears with the shared wallet, and is no longer published: the gate is the only caller an application needs.
|
||||
- `connectedUser()` (internal since 2026-08-07) — the awaitable form of what the target does **automatically**: the recipient's verifier processes its inbox as messages arrive/at connection (`Verifier::inbox`, `engine/verifier/src/verifier.rs:1674`). VERIFIED at level 1 that no consumer call is needed upstream; the polyfill fires it from `setCurrentUser` for the same reason. A consumer should treat it as "await a deterministic start" (tests), not as an operation the future SDK will name.
|
||||
|
||||
---
|
||||
|
||||
## 14. Type re-exports
|
||||
|
||||
`@ng-eventually/polyfill` re-exports, type-only (erased at build, `src/index.ts`):
|
||||
|
||||
```ts
|
||||
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`; `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
|
||||
|
||||
The entry used to say `export * from "./model/types"`, a blanket re-export publishing eight types in one gesture. It now names them, under one rule:
|
||||
|
||||
> **A type is published only if a PUBLISHED SIGNATURE uses it.**
|
||||
|
||||
```ts
|
||||
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` 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**:
|
||||
|
||||
- **`ReadCap`** — no published signature takes or returns one. Its users are two private helpers of `surface/inbox.ts` (`capsSeenIn`, `capOfPayload`) and the emulated registers. Publishing it advertised a value a consumer has no published call to obtain, and deliberately so: `linkTo` was removed precisely for handing one out (§ 0 of `readcap-and-nuri-model.md`), and `mintCap` is unreachable from outside (§ 11). The only use a consumer could make of it is a cast — which is what the surface's permissive-in / precise-out design exists to make unnecessary.
|
||||
- **`InboxScope`** — used only by `account-registry.userInbox(id, scope)`, unpublished since 2026-08-05 (§ 12). An application never handles an inbox address, so it never names an inbox scope.
|
||||
|
||||
Both remain **defined** in `model/types.ts` and are used throughout the library; only their publication changed. Nothing about the target motivates either removal — this is a statement about *this* surface, and the same test that pins the appendix pins it.
|
||||
|
||||
---
|
||||
|
||||
## 15. Machinery on the surface — what a consumer should NOT code against
|
||||
|
||||
Exported, but not SDK surface. Coding against these builds knowledge that migration deletes:
|
||||
|
||||
- ~~**`docs.depositInto`**~~ **FIXED 2026-08-07.** It was published "only because `inbox.ts` lives in another module", with the note that a consumer must always go through `inbox.post`. That note is not a mechanism: an adversarial review drove through it — bare reference to a public document, rewrite its posted inbox address, divert its owner's deposits. It now lives in `emulated-verifier/register-write.ts`, which nothing exports.
|
||||
- **`getConfig` / `getStoreRegistryDeps`** — tagged `@internal` in source, exported for the lib's own wrappers.
|
||||
- **`resetConfig` / `resetStoreRegistry` / `resetCaps` / `storeRegistry.resetRegistryCache`** — test/reset machinery. In particular `resetCaps` wipes EVERY holder's caps, which no product flow should ever do.
|
||||
- **`getCaps()` and the `CapRegistry` class** — the registry is the emulation's engine room. The consumer surface is the acts that file caps: creating a document, `inbox.share` (grant), processing one's inbox, and reading a document a public store serves. `CapRegistry.grantWrite` / `governsWrite` / `canWrite` / `hasWritePolicy` are explicitly decorative until cap-enforcement — the guard they feed is bypassed by every internal writer.
|
||||
- ~~**`storeRegistry.reservedAccount`, `resolveAccount`, `ensureAccount`, `VirtualUserRecord`, `RegistrySession`**~~ — **RESOLVED 2026-08-03**: no longer exported. Shim internals, now in `docs/internal-contract.md`. The consumer's legitimate touchpoint is `configureStoreRegistry` (bootstrap) plus the scope/entity resolvers.
|
||||
- ~~**`storeRegistry.addLink` / `readLinks`**~~ — **RESOLVED 2026-08-03**: no longer exported. Consumers receive caps by processing their inbox (automated at connection); calling these directly baked in a register the verifier owns upstream.
|
||||
- ~~**`virtualUsers.*` on the SDK entry**~~ — **RESOLVED 2026-08-03**: moved to `/polyfill`, where its disappearance at migration is visible at the import line.
|
||||
- **`inbox.watch`'s `_opts?: { intervalMs?: number }`** — accepted and ignored (no polling exists). Dead compatibility surface; do not pass it.
|
||||
- **The `label` parameters** on `docs.sparqlUpdate` / `docs.sparqlQuery` — lib-internal access-log tags, never forwarded to `ng`. The real signatures have no such parameter.
|
||||
|
||||
### 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`, `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"**~~ **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.
|
||||
|
||||
---
|
||||
|
||||
## Appendix — full export inventory (for diffing)
|
||||
|
||||
*Generated from the `export` statements, and pinned by `packages/polyfill/test/vocabulary.test.ts` — if this list and the code disagree, that test fails. It went stale once, still listing `storeRegistry`'s shim internals after the entry had been narrowed, which is what a hand-maintained inventory does.*
|
||||
|
||||
### `@ng-eventually/polyfill` — `src/index.ts` (the only entry since 2026-08-07)
|
||||
|
||||
```text
|
||||
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, openDocumentInbox, privateStore, protectedStore, publicStore
|
||||
```
|
||||
|
||||
**Of these, exactly ONE is polyfill-era with no target counterpart** — `configure` (plus
|
||||
the type `EventuallyConfig`; `RegistrySession` left the surface on 2026-08-12 with the
|
||||
session thunk that was its only reason to be there). It is the deletion list, and
|
||||
`src/index.ts` groups it under a heading that says so. `ensureIdentity` is a second in
|
||||
substance — the shared-wallet gate — but its *call site* survives (§ 2bis).
|
||||
|
||||
Nine symbols published before 2026-08-07 are gone from the surface: `configureStoreRegistry`
|
||||
and `StoreRegistryDeps` (folded into `configure`), `setCurrentUser` and `connectedUser`
|
||||
(§ 1), `getConfig` / `getStoreRegistryDeps` (internal wiring), `resetConfig` /
|
||||
`resetStoreRegistry` / `resetCaps` (test resets), and the direct `share` re-export —
|
||||
`inbox.share` was always the same function, and publishing it twice blurred the boundary
|
||||
it was meant to mark.
|
||||
@@ -1,216 +1,145 @@
|
||||
# Brief — aligner l'émulation des caps sur le vrai modèle NextGraph
|
||||
# Brief — align the caps emulation with the real NextGraph model
|
||||
|
||||
**Brief (incubation) — 2026-07-20.** Voir la référence `docs/readcap-and-nuri-model.md`.
|
||||
**Brief (incubation) — 2026-07-20.** See the reference `docs/readcap-and-nuri-model.md`.
|
||||
|
||||
## Problème
|
||||
## Problem
|
||||
|
||||
`caps.ts` émule les droits de lecture comme une **ACL** (`Map<Nuri, Set<PrincipalId>>`,
|
||||
`grantRead(doc, grantee)`) — **l'inversion** du vrai modèle NextGraph (possession
|
||||
de clé). Conséquences : pas de notion de **référence cap-less**, grant/révocation
|
||||
**instantanés et totaux** (au lieu de scellage durable + re-key), et une API
|
||||
(`declareConnections`) que les consommateurs doivent **re-déclarer à chaque
|
||||
session**. Cet écart empêche de bâtir correctement des modèles qui reposent sur la
|
||||
vraie sémantique — notamment la **présence anonyme** (nommer/compter sans lire).
|
||||
`emulated-verifier/caps.ts` emulates read rights as an **ACL** (`Map<Nuri, Set<PrincipalId>>`, `grantRead(doc, grantee)`) — **the inversion** of the real NextGraph model (key possession). Consequences: no notion of a **cap-less reference**, grant/revocation **instantaneous and total** (instead of durable sealing + re-key), and an API (`declareConnections`) that consumers have to **re-declare every session**. This divergence makes it impossible to properly build models that rest on the real semantics — in particular **anonymous presence** (naming/counting without reading).
|
||||
|
||||
## Objectif : shape-fidelity, PAS sécurité
|
||||
## Objective: shape-fidelity, NOT security
|
||||
|
||||
Le polyfill **n'égale PAS** la sécurité de NextGraph fini, et n'essaie pas. Le
|
||||
wallet partagé + l'absence de crypto rendent l'émulation **volontairement
|
||||
non-sécurisée** (tout est en clair, tout marqueur est forgeable) — véhicule de
|
||||
dev/staging, pas un but. **Seul objectif** : exposer la **BONNE FORME** des
|
||||
primitives futures pour que les consommateurs (Festipod) soient codés contre le
|
||||
**modèle mental correct** et **n'aient pas à être réécrits** quand NextGraph sera fini.
|
||||
The polyfill does **NOT match** the security of finished NextGraph, and does not try to. The shared wallet plus the absence of crypto make the emulation **deliberately insecure** (everything is in plaintext, any marker is forgeable) — a dev/staging vehicle, not a goal. **Sole objective**: expose the **RIGHT SHAPE** of the future primitives so that consumers (Festipod) are coded against the **correct mental model** and **do not have to be rewritten** when NextGraph is finished.
|
||||
|
||||
Corollaire : **« pas de crypto » n'est pas un problème** ; ce qui compte est d'être
|
||||
**dans la même logique, avec RIGUEUR**. Une critique « un attaquant lit le clair /
|
||||
forge un marqueur » est **exacte mais hors-scope**. Ce qui est **inacceptable** =
|
||||
exposer la **mauvaise forme** (ex. une ACL là où le réel est possession de clé) →
|
||||
le consommateur code contre un modèle qui n'existera pas. **L'inversion ACL des
|
||||
ReadCaps EST ce manque de rigueur** — le défaut central à corriger.
|
||||
Corollary: **"no crypto" is not a problem**; what matters is being **in the same logic, with RIGOR**. A criticism of the form "an attacker reads the plaintext / forges a marker" is **correct but out of scope**. What is **unacceptable** = exposing the **wrong shape** (e.g. an ACL where the real thing is key possession) → the consumer codes against a model that will not exist. **The ACL inversion of ReadCaps IS that lack of rigor** — the central defect to fix.
|
||||
|
||||
## Mécanisme d'enforcement : simulation crypto LÉGÈRE (anti-ACL, anti-raccourci)
|
||||
## Enforcement mechanism: LIGHTWEIGHT crypto simulation (anti-ACL, anti-shortcut)
|
||||
|
||||
Pour que la forme soit **réellement** possession-de-clé (et pas une ACL déguisée),
|
||||
la donnée d'un doc est **stockée chiffrée** (chiffrement symétrique par-doc, même
|
||||
léger) et le **ReadCap = la clé**. Invariant (cf. `docs/vision.md`) :
|
||||
For the shape to be **really** key-possession (and not an ACL in disguise), a doc's data is **stored encrypted** (per-doc symmetric encryption, however lightweight) and the **ReadCap = the key**. Invariant (cf. `docs/vision.md`):
|
||||
|
||||
> un **`did` nu (sans ReadCap)** ne permet **PAS** de lire ; un **NURI avec
|
||||
> ReadCap** est **suffisant et requis**.
|
||||
> a **bare `did` (without a ReadCap)** does **NOT** allow reading; a **NURI with a ReadCap** is **sufficient and required**.
|
||||
|
||||
Ça **empêche les raccourcis** que l'adversaire a relevés (#4/#6 : lire le clair,
|
||||
`sparqlQuery`/`inbox.read` qui bypass le filtre) et **interdit** de retomber sur
|
||||
une ACL — c'est le cœur de « même logique, avec rigueur ».
|
||||
This **prevents the shortcuts** the adversary pointed out (#4/#6: reading the plaintext, `sparqlQuery`/`inbox.read` bypassing the filter) and **forbids** falling back on an ACL — that is the heart of "same logic, with rigor".
|
||||
|
||||
**Cible — PAS l'état actuel** : toutes les surfaces de lecture (`read-model`,
|
||||
`read-filter`, `sparqlQuery`, `inbox.read`) devront passer par le
|
||||
déchiffrement-avec-clé. **Aujourd'hui c'est FAUX** : `inbox.read` (`inbox.ts:198`)
|
||||
et `sparqlQuery` brut (`docs.ts:82`) **bypass** le filtre, et le seul garde
|
||||
(`caps.canRead`, `caps.ts:95`) est une **ACL set-membership** — l'inversion même
|
||||
que la vision interdit. **Fermer ces voies = le cœur de P1.**
|
||||
**Target — NOT the current state**: every surface that returns data will have to go through decryption-with-key. **Today this is FALSE, and far more broadly than this brief first stated** — mapping of 2026-07-27, VERIFIED: **only 4 sites consult the caps** (`use-shape`, `read-filter`, `read-model.readUnion`, `discovery.submitToIndex`). Everything else returns data with no guard:
|
||||
|
||||
1. **Deux formes de référence distinctes** : cap-less (nomme/localise sans lire —
|
||||
aligné sur le NURI sans `:k:`) vs cap-porteur (id + clé/token). Aujourd'hui
|
||||
absent.
|
||||
2. **Grant = livrer un cap-token à un destinataire** (émuler le scellage :
|
||||
le destinataire *reçoit* le token dans son inbox ; c'est la **possession** du
|
||||
token qui autorise la lecture — pas une ligne d'ACL vérifiée par principal).
|
||||
3. **Enforcement par possession** : les lecteurs (`read-filter`, `use-shape`) ne
|
||||
voient que ce dont ils **détiennent le token**, pas « ce dont ils sont dans le
|
||||
set de readers ».
|
||||
4. **Résoudre un cap-less** = nommer / prouver l'existence / compter, **sans**
|
||||
exposer le contenu (support de la présence anonyme).
|
||||
5. **Révocation = re-key** émulé : invalider l'ancien token, re-livrer un nouveau
|
||||
aux autorisés restants ; **non-rétroactif**.
|
||||
| Surface | State |
|
||||
|---|---|
|
||||
| `docs.sparqlQuery` / `sparqlUpdate` | **bypasses** — they call the injected `ng` **directly** (an accepted constraint, to avoid a double-Proxy `DataCloneError`). **The widest breach**: a session id + a NURI are enough to read everything. |
|
||||
| `inbox` (`read` / `readSynced` / `materialize` / `watch`) | **bypasses** — no cap consulted; the drops go to whoever asks for them |
|
||||
| `store-registry` (**zero** reference to caps in the whole file) | **bypasses** — the account→NURI root of trust is universally readable |
|
||||
| `discovery.readIndex` | **bypasses** on read (caps checked on write only) |
|
||||
| `subscribe`, `open-repo` | **bypass** — the subscription push carries the doc state with no check |
|
||||
| `watch-shape` | deliberately delegates to `readUnion` (does not re-filter) |
|
||||
|
||||
## ~~Périmètre élargi : le WriteCap (= membership)~~ — RETIRÉ (2026-07-21)
|
||||
**And the WRITE guard is already stillborn**: `ng-proxy` guards `sparql_update`, but `docs` bypasses the proxy **by design**, and **all** internal writers go through `docs`. So the guard only fires for an app calling `ng.sparql_update` on the exported `ng` — which Festipod does not do. `grantWrite` / `canWrite` are **decorative**. *(This finding reinforces §1 of the adversarial review: writing is not an axis "to be added", it is an axis we believed was covered and is not.)*
|
||||
|
||||
**Cette section était fausse et est conservée barrée comme garde-fou.** Elle
|
||||
importait une notion de *membership* lue dans l'**état courant** de `nextgraph-rs`
|
||||
(`AddMember`, `PermissionV0`, `member_pubkey`) et la promouvait en **forme cible**.
|
||||
Or (a) ces types sont un **échafaudage inerte** au runtime — `verify_sig` /
|
||||
`verify_perm` ne sont appelés que dans des tests unitaires, les `Repo` sont
|
||||
construits avec `members: HashMap::new()` ; et (b) le modèle cible **n'a pas de
|
||||
notion d'appartenance du tout** : uniquement des **clés et des URLs**, symétrique
|
||||
et asymétrique. Une forme en `member`/`role`/`permission` est donc exactement la
|
||||
**mauvaise forme** que ce brief existe pour empêcher.
|
||||
**This inventory IS the scope of P1b.** The only existing guard (`caps.canRead`) is moreover a **set-membership ACL** — the very inversion the vision forbids.
|
||||
|
||||
**La leçon de méthode, qui vaut plus que la section retirée** : lire l'état
|
||||
courant de NextGraph pour en **déduire** la forme cible est une erreur — l'état
|
||||
courant contient de l'inachevé qu'il ne faut pas figer dans le polyfill. Le source
|
||||
sert à vérifier un **mécanisme** existant, jamais à inférer une **intention**.
|
||||
1. **Two distinct reference shapes**: cap-less (names/locates without reading — aligned with the NURI without `:r:`) vs cap-bearing (id + key/token). Absent today.
|
||||
2. **Grant = delivering a cap-token to a recipient** (emulating the sealing: the recipient *receives* the token in their inbox; it is **possession** of the token that authorizes reading — not an ACL row checked per principal).
|
||||
3. **Enforcement by possession**: readers (`read-filter`, `use-shape`) only see what they **hold the token for**, not "what they are in the readers set for".
|
||||
4. **Resolving a cap-less** = naming / proving existence / counting, **without** exposing the content (support for anonymous presence).
|
||||
5. **Revocation = re-key** emulated: invalidate the old token, re-deliver a new one to the remaining authorized holders; **non-retroactive**.
|
||||
|
||||
Contenu erroné conservé ci-dessous à titre de trace :
|
||||
## ~~Widened scope: the WriteCap (= membership)~~ — DROPPED (2026-07-21)
|
||||
|
||||
**This section was wrong and is kept struck through as a guardrail.** It imported a notion of *membership* read from the **current state** of `nextgraph-rs` (`AddMember`, `PermissionV0`, `member_pubkey`) and promoted it into a **target shape**. But (a) those types are **inert scaffolding** at runtime — `verify_sig` / `verify_perm` are only called in unit tests, and `Repo`s are built with `members: HashMap::new()`; and (b) the target model **has no notion of membership at all**: only **keys and URLs**, symmetric and asymmetric. A shape in terms of `member`/`role`/`permission` is therefore exactly the **wrong shape** that this brief exists to prevent.
|
||||
|
||||
**The methodological lesson, which is worth more than the dropped section**: reading NextGraph's current state in order to **deduce** the target shape is a mistake — the current state contains unfinished work that must not be frozen into the polyfill. The source serves to verify an existing **mechanism**, never to infer an **intent**.
|
||||
|
||||
Erroneous content kept below as a record:
|
||||
|
||||
<details>
|
||||
<summary>Section retirée</summary>
|
||||
<summary>Dropped section</summary>
|
||||
|
||||
**Pourquoi c'est ici et pas ailleurs.** Le brief était d'abord centré ReadCap ; un
|
||||
constat adverse a montré qu'il **ne compose pas** avec son consommateur : le brief
|
||||
Festipod « inscriptions par Set » a besoin de **dédupliquer** les participations
|
||||
(un user = une participation par événement), et la seule base non-applicative
|
||||
disponible est la **signature d'auteur du commit** — donc un primitif d'**écriture**,
|
||||
pas de lecture. Un polyfill qui n'expose que la forme du ReadCap laisse le
|
||||
consommateur inventer sa propre dédup applicative → exactement la mauvaise forme.
|
||||
**Why this is here and not elsewhere.** The brief was at first ReadCap-centric; an adversarial finding showed that it **does not compose** with its consumer: the Festipod brief on "Set-based sign-ups" needs to **deduplicate** participations (one user = one participation per event), and the only non-application-level basis available is the commit's **author signature** — hence a **write** primitive, not a read one. A polyfill that only exposes the ReadCap shape leaves the consumer to invent its own application-level dedup → exactly the wrong shape.
|
||||
|
||||
**La forme réelle (VÉRIFIÉE, cf. `readcap-and-nuri-model.md` §1)** — et elle est
|
||||
**asymétrique** de la lecture, ce qui est le point le plus facile à rater :
|
||||
**The real shape (VERIFIED, cf. `readcap-and-nuri-model.md` §1)** — and it is **asymmetric** with reading, which is the easiest point to miss:
|
||||
|
||||
- **Lecture = possession d'une clé.** Pas d'ACL. Qui détient, lit.
|
||||
- **Écriture = membership + permissions** (`AddMember`, `AddPermission` sur le
|
||||
`RootBranch`). C'est **bel et bien une liste d'autorisation** — pas de la
|
||||
possession. Émuler l'écriture « par possession de token » serait aussi faux que
|
||||
l'ACL de lecture actuelle, en miroir.
|
||||
- **Les commits SONT signés** par un `UserId` (clé **technique**, distincte du
|
||||
profil) — donc un identifiant de dédup **existe** nativement, sans pseudonyme
|
||||
applicatif.
|
||||
- **Mais vérifier une signature exige d'être membre du repo** (accès au
|
||||
`member_pubkey`). Un tiers non-membre voit un commit signé sans pouvoir
|
||||
l'attribuer.
|
||||
- **Le dépôt d'inbox n'est PAS authentifié** (sealed box anonyme) : un `from`
|
||||
déclaré est du contenu, pas une preuve.
|
||||
- **Reading = possession of a key.** No ACL. Whoever holds, reads.
|
||||
- **Writing = membership + permissions** (`AddMember`, `AddPermission` on the `RootBranch`). It really **is an authorization list** — not possession. Emulating writing "by token possession" would be just as wrong as the current read ACL, in mirror image.
|
||||
- **Commits ARE signed** by a `UserId` (a **technical** key, distinct from the profile) — so a dedup identifier **exists** natively, with no application-level pseudonym.
|
||||
- **But verifying a signature requires being a member of the repo** (access to the `member_pubkey`). A non-member third party sees a signed commit without being able to attribute it.
|
||||
- **The inbox drop is NOT authenticated** (anonymous sealed box): a declared `from` is content, not proof.
|
||||
|
||||
**Ce que ça impose au polyfill.** Exposer `membership` comme primitif **distinct**
|
||||
de la possession de cap, avec au minimum : ajouter/retirer un membre d'un repo,
|
||||
lire la members map **quand on est membre**, et **vérifier l'auteur d'un commit**
|
||||
(→ un digest d'auteur, **par-overlay donc par-store**). C'est ce dernier point qui
|
||||
débloque la dédup côté Festipod.
|
||||
**What that imposes on the polyfill.** Expose `membership` as a primitive **distinct** from cap possession, with at minimum: adding/removing a member of a repo, reading the members map **when one is a member**, and **verifying the author of a commit** (→ an author digest, **per-overlay hence per-store**). It is this last point that unblocks the dedup on the Festipod side.
|
||||
|
||||
**La conséquence de forme, à documenter explicitement** (sinon le consommateur se
|
||||
trompe de modèle) : le digest d'auteur étant **par-store**, le choix du découpage
|
||||
en stores **est** le choix du niveau de corrélation. Un store **stable par-user**
|
||||
donne un identifiant traçable **cross-événement** ; un store **par-événement**
|
||||
donne un pseudonyme **local à l'événement** — dédup possible, corrélation
|
||||
impossible. Festipod a besoin du second. Le polyfill doit donc rendre ce découpage
|
||||
**exprimable**, pas le figer.
|
||||
**The shape consequence, to be documented explicitly** (otherwise the consumer picks the wrong model): the author digest being **per-store**, the choice of how stores are carved up **is** the choice of the correlation level. A **per-user stable** store gives an identifier traceable **across events**; a **per-event** store gives a pseudonym **local to the event** — dedup possible, correlation impossible. Festipod needs the second. So the polyfill must make this carving **expressible**, not freeze it.
|
||||
|
||||
**Reste ouvert** : « le créateur d'un événement peut-il être membre du store qui
|
||||
contient les participations, sans pour autant en détenir la clé de lecture ? » —
|
||||
c'est-à-dire membership (écriture/vérification) et possession (lecture)
|
||||
réellement **orthogonales**. Si NextGraph les couple, la dédup vérifiée et
|
||||
l'anonymat s'excluent, et c'est le brief Festipod qui doit trancher ce qu'il
|
||||
sacrifie. **À vérifier avant de façonner l'API.**
|
||||
**Still open**: "can the creator of an event be a member of the store that contains the participations, without holding its read key?" — that is, membership (writing/verification) and possession (reading) genuinely **orthogonal**. If NextGraph couples them, verified dedup and anonymity are mutually exclusive, and it is the Festipod brief that must settle what it sacrifices. **To be verified before shaping the API.**
|
||||
|
||||
</details>
|
||||
|
||||
*(Question devenue sans objet : il n'y a pas de membership. La dédup ne passe pas
|
||||
par une vérification de signature — voir le brief Festipod « inscriptions ».)*
|
||||
*(Question now moot: there is no membership. The dedup does not go through signature verification — see the Festipod brief on "sign-ups".)*
|
||||
|
||||
## Questions ouvertes
|
||||
## Open questions
|
||||
|
||||
- **TRANCHÉ (directive PO, 2026-07-21)** : on **simule la crypto** (donnée chiffrée
|
||||
par-doc, cap = clé). La « sémantique seule » (registre de tokens) est **écartée** —
|
||||
elle redevient une ACL et laisse lire le clair. Reste à trancher le **niveau** de
|
||||
simulation (chiffrement réel léger vs projection read-model masquée), **avant P1**.
|
||||
- Représentation NURI cap-less vs cap-porteur dans l'émulation (calquer `:k:`).
|
||||
- Faut-il permettre le **fetch keyless** (résoudre un cap-less en existence/compte
|
||||
sans le contenu) — dépend de ce que le vrai broker autorise (INFÉRÉ, non tracé).
|
||||
- Migration d'API : `declareConnections`/`grantRead` → `seal(cap, recipient)` +
|
||||
`inbox → caps reçus`. Casse les consommateurs (`declareConnections` app disparaît).
|
||||
- **SETTLED (PO directive, 2026-07-21)**: we **simulate the crypto** (per-doc encrypted data, cap = key). "Semantics only" (a token registry) is **discarded** — it turns back into an ACL and lets the plaintext be read. What remains to settle is the **level** of simulation (real lightweight encryption vs masked read-model projection), **before P1**.
|
||||
- NURI representation, cap-less vs cap-bearing, in the emulation (mirror `:r:`).
|
||||
- ~~Should **keyless fetch** be allowed (resolving a cap-less into existence/count without the content)~~ — **SETTLED, and negatively (2026-07-27)**: not constructible. Addressing itself presupposes the cap, so there is nothing to expose. See the corrected Q1 verdict below. Kept struck through rather than deleted: the hypothesis is intuitive and will otherwise be re-formed.
|
||||
- API migration: `declareConnections`/`grantRead` → `seal(cap, recipient)` + `inbox → received caps`. Breaks consumers (the app-side `declareConnections` disappears).
|
||||
|
||||
## P0 — Spike « keyless-resolve » (le verrou, AVANT tout P1)
|
||||
## P0 — "keyless-resolve" spike (the blocker, BEFORE any P1)
|
||||
|
||||
**Question porteuse** : un détenteur d'une **référence cap-less** (`did:ng:o:{id}:v:{overlay}`, sans `:k:`) peut-il, **sans jamais lire le contenu** :
|
||||
- **Q1 — Existence / fetch** : prouver/récupérer la présence des blocs (chiffrés) auprès du broker ? Ou le broker exige-t-il un ReadCap/membership pour servir les blocs ?
|
||||
- **Q2 — Suppression** : distinguer « existe » de « supprimé » ? *(Le point FRAGILE : NextGraph est append-only CRDT — une désinscription = un **commit tombstone** qu'il faudrait **lire** pour connaître → potentiellement **la clé est requise**. Or le **décrément au leave** en dépend.)*
|
||||
- **Q3 — Confidentialité** : la clé (`:k:`) reste-t-elle **requise** pour déchiffrer (le keyless ne donne jamais le contenu) ?
|
||||
**Load-bearing question**: can a holder of a **cap-less reference** (`did:ng:o:{id}:v:{overlay}`, without `:r:`), **without ever reading the content**:
|
||||
- **Q1 — Existence / fetch**: prove/retrieve the presence of the (encrypted) blocks from the broker? Or does the broker require a ReadCap/membership in order to serve the blocks?
|
||||
- **Q2 — Deletion**: distinguish "exists" from "deleted"? *(The FRAGILE point: NextGraph is an append-only CRDT — a withdrawal = a **tombstone commit** that one would have to **read** in order to know about → potentially **the key is required**. And the **decrement on leave** depends on it.)*
|
||||
- **Q3 — Confidentiality**: does the key remain **required** in order to decrypt (keyless never gives the content)?
|
||||
|
||||
**Pourquoi c'est le verrou** : tout le **compteur anonyme** (compter/valider des réfs cap-less sans lire) ET le **décrément au leave** en dépendent. **Si NON** → « compteur anonyme par réf cap-less » est **inconstruisible en cible** → Festipod ne doit **pas** coder cette forme (réécriture garantie). **Si OUI** → P1 expose `resolveCapLess(nuri) → {exists|deleted}` (jamais de contenu), et l'émulation la simule fidèlement.
|
||||
**Why this is the blocker**: the whole **anonymous counter** (counting/validating cap-less refs without reading) AND the **decrement on leave** depend on it. **If NO** → "anonymous counter via cap-less ref" is **not constructible in the target** → Festipod must **not** code that shape (guaranteed rewrite). **If YES** → P1 exposes `resolveCapLess(nuri) → {exists|deleted}` (never any content), and the emulation simulates it faithfully.
|
||||
|
||||
**Méthode** (bon marché, décisif) :
|
||||
1. **Tracer** dans `nextgraph-rs` le chemin d'**autorisation de fetch** du broker/verifier : qui sert les blocs (`BlocksGet`/`TopicSync`/`OverlaySync`) ? un cap/membership est-il vérifié, ou `id+overlay` suffit ? l'overlay *outer* est-il public ? une suppression est-elle observable sans clé ?
|
||||
2. *(Optionnel)* **test e2e décisif** (façon `e2e/reactivity-doc-subscribe.ts`) : B détient la réf cap-less, tente fetch/existence **sans** la clé, vérifie qu'il **n'accède pas** au contenu. Preuve empirique > source.
|
||||
3. *(Ou)* confirmer avec le dev NextGraph — le plus rapide.
|
||||
**Method** (cheap, decisive):
|
||||
1. **Trace** in `nextgraph-rs` the broker/verifier **fetch authorization** path: who serves the blocks (`BlocksGet`/`TopicSync`/`OverlaySync`)? is a cap/membership checked, or is `id+overlay` enough? is the *outer* overlay public? is a deletion observable without the key?
|
||||
2. *(Optional)* **decisive e2e test** (in the style of `e2e/reactivity-doc-subscribe.ts`): B holds the cap-less ref, attempts fetch/existence **without** the key, verifies that it **does not reach** the content. Empirical proof > source.
|
||||
3. *(Or)* confirm with the NextGraph dev — the fastest.
|
||||
|
||||
**Livrable** : YES/NO/PARTIAL par Q1/Q2/Q3 + le primitif exact (file:line) + la forme d'API à exposer (si OUI), ou le constat que le compteur change (si NON).
|
||||
**Décision gatée** : OUI → P1 ; NON → le brief inscriptions revoit le compteur (pas anonyme, ou autre primitif).
|
||||
**Deliverable**: YES/NO/PARTIAL per Q1/Q2/Q3 + the exact primitive (file:line) + the API shape to expose (if YES), or the finding that the counter changes (if NO).
|
||||
**Gated decision**: YES → P1; NO → the sign-ups brief revisits the counter (not anonymous, or another primitive).
|
||||
|
||||
### Verdict du spike (2026-07-21) — VÉRIFIÉ dans `nextgraph-rs`
|
||||
### Spike verdict (2026-07-21) — VERIFIED in `nextgraph-rs`
|
||||
|
||||
| | Réponse | Preuve |
|
||||
| | Answer | Evidence |
|
||||
|---|---|---|
|
||||
| **Q1 — existence/fetch sans cap** | **OUI, partiel** | Les lectures ne sont pas cap-gatées : `blocks_get.rs`, `blocks_exist.rs`, `topic_sync_req.rs` servent les blocs sans exiger ReadCap ni membership. **Seul garde : l'overlay**. Nuance non levée : overlay *inner* vs *outer* (`expose_outer`, défaut `false`) — **sonde en cours**. |
|
||||
| **Q2 — détecter une suppression sans clé** | **NON** | Broker append-only ; une suppression est un **commit tombstone chiffré** (`RemoveRepo`), no-op côté verifier. Sans clé on observe « une activité », jamais « une suppression ». |
|
||||
| **Q3 — confidentialité** | **OUI** | Blocs stockés en ciphertext ; la clé est `#[serde(skip)]` (`types.rs`), dérivée du `ReadCapSecret`. Le keyless ne donne **jamais** le contenu. |
|
||||
| **Q1 — existence/fetch without a cap** | **NO** *(corrected on 2026-07-27 — the initial "partial YES" verdict over-read the evidence)* | Read access control does indeed let you through (reads are not cap-gated) — **but addressing presupposes the cap**: no existence command at the SDK level; the only probe is internal to the crate, requires `BlockId`s **and** a loaded repo, and targets the **inner** overlay derived from the read secret. A cap-less reference has neither `BlockId` nor the required overlay. See `readcap-and-nuri-model.md`. |
|
||||
| **Q2 — detect a deletion without the key** | **NO** | Append-only broker; a deletion is an **encrypted tombstone commit** (`RemoveRepo`), a no-op on the verifier side. Without the key one observes "some activity", never "a deletion". |
|
||||
| **Q3 — confidentiality** | **YES** | Blocks stored as ciphertext; the key is `#[serde(skip)]` (`types.rs`), derived from the `ReadCapSecret`. Keyless **never** gives the content. |
|
||||
|
||||
**Ce que ça décide.**
|
||||
- **P1 est débloqué** : `resolveCapLess(nuri) → { exists }` est la bonne forme — mais **`{ exists | deleted }` ne l'est PAS**. Ne pas exposer d'état `deleted`, ce serait inventer une capacité que la cible n'aura jamais (précisément le mode d'échec que ce brief combat).
|
||||
- **Le retrait doit être un message, pas une observation.** Côté consommateur : un *nudge* explicite. Le polyfill n'a **rien** à émuler pour ça — juste à ne pas prétendre le contraire.
|
||||
- **Reste gaté** : la nuance d'overlay (Q1). Si un non-membre ne peut pas rejoindre l'overlay d'un store *protected* tiers, le fetch keyless est inatteignable **en pratique** malgré un chemin d'autorisation ouvert — et le compteur anonyme retombe sur du déclaratif.
|
||||
**What that decides.**
|
||||
- **P1 is unblocked**: `resolveCapLess(nuri) → { exists }` is the right shape — but **`{ exists | deleted }` is NOT**. Do not expose a `deleted` state; that would be inventing a capability the target will never have (precisely the failure mode this brief fights).
|
||||
- **Withdrawal has to be a message, not an observation.** On the consumer side: an explicit *nudge*. The polyfill has **nothing** to emulate for that — it just must not pretend otherwise.
|
||||
- **Settled by the Q1 correction**: the anonymous counter can**not** rest on an existence validation — that is not constructible. So it rests on something **declarative**, which is acceptable (outside the security scope) as long as the **exposed shape does not lie**: do not expose an existence primitive that the target will not offer.
|
||||
|
||||
## Esquisse de phases
|
||||
## P1a — the surface — **DONE (2026-07-28)**
|
||||
|
||||
- **P1** — distinction cap-less / cap-porteur dans les NURI + le read-model
|
||||
(résoudre un cap-less = nommer/compter/prouver l'existence, **pas** lire, **pas**
|
||||
de `deleted`). Inclut la **fermeture des bypass** (`inbox.read`, `sparqlQuery`)
|
||||
sans laquelle la distinction n'est pas tenue.
|
||||
- **P2** — remplacer l'ACL par un modèle de **possession de token** (grant = livrer
|
||||
à un destinataire ; enforcement = possession). *Requalifié par la revue adverse :
|
||||
le vrai contenu de P2 est **durabilité + cap-less + re-partage par le détenteur**,
|
||||
pas « inverser l'ACL » — sans crypto, inverser ne produit aucun delta observable.*
|
||||
- **P3** — révocation par re-key (invalidation + re-livraison, non-rétroactive).
|
||||
- **PW** — **WriteCap = membership** : primitif distinct (add/remove member,
|
||||
members map lisible par un membre, **vérification d'auteur de commit** → digest
|
||||
par-store), et découpage en stores **exprimable** par le consommateur.
|
||||
*Indépendant de P1–P3 ; **bloquant pour la dédup Festipod**, donc à ordonnancer
|
||||
tôt si c'est ce besoin-là qui presse.*
|
||||
- **P4** — adapter l'API consommateur + `migration-guide.md`. *La revue adverse
|
||||
requalifie ce lot : ce n'est pas un swap d'API mais une **re-architecture
|
||||
consommateur** (le grant se déplace vers l'acceptation de connexion et devient
|
||||
persistant ; `declareConnections` disparaît).*
|
||||
**Extracted into its own brief: [`2026-07-27-p1a-cap-surface.md`](2026-07-27-p1a-cap-surface.md), which records what landed where.**
|
||||
|
||||
## Revue adverse (2026-07-20) — à intégrer
|
||||
The ACL inversion — *the central defect this whole chantier exists to fix* — is gone: `emulated-verifier/caps.ts` is a keyring, sharing is a per-document delivery to an inbox, and a bare reference reads nothing. **P1b is now the blocker for any privacy claim**: the emulated key is derived (hence reproducible) and the bypass inventory below is untouched.
|
||||
|
||||
Un adversaire a réfuté le brief (6 constats). **À lire au filtre de l'Objectif ci-dessus** (forme, pas sécurité). Les critiques purement **sécurité** — contenu en clair lisible (#4), marqueurs forgeables — sont **ACCEPTÉES / hors-scope** : le polyfill ne cherche pas à les empêcher. Restent les vrais défauts de **FORME / rigueur** (à corriger), et une question de **modèle futur** (#5) :
|
||||
In two lines: a single new type (`ReadCap`), a keyring (`capFor`), a per-document share to an inbox (`shareCap`) — and nothing else. The branded types, `resolveCapLess`, `receivedCaps`, `refOf`, `parseNuri` and `PrincipalId` were **discarded** after a double adversarial review; the reasons are in that note.
|
||||
|
||||
1. **WriteCap oublié, et « possession » y est FAUX.** L'écriture est **membership/permissions** (`AddMember`) — une **liste d'autorisation**, pas de la possession de clé (réf §1) ; `ng-proxy.ts:28-48` garde chaque `sparql_update`. → garder une **piste WriteCap = membership** ; la **possession ne concerne QUE la lecture**.
|
||||
2. **P2 « possession sans crypto » = l'ACL renommée.** Sans crypto, « qui détient quel token » = `Map<doc, Set<holder>>` = le `readers` actuel : **aucun delta observable**. Les vrais deltas sont **durabilité + cap-less + re-partage par le détenteur** — c'est ÇA le contenu de P2, pas « inverser l'ACL ».
|
||||
3. **Révocation non-rétroactive INÉMULABLE** sans versioning : `read-model.ts:112-118` ne lit que l'état courant → « invalider l'ancien token » = retrait total = l'inverse du réel (l'ex-détenteur déchiffre les versions **antérieures**). → n'émuler que « plus de nouvelles lectures après re-key » + **documenter la non-rétroactivité comme non-émulable**.
|
||||
4. **cap-less « sans exposer le contenu » ILLUSOIRE dans l'émulation** : contenu en **clair** dans le wallet partagé ; `sparqlQuery`/`inbox.read` **bypass** le filtre ; `read-filter.ts:30-35` est tout-ou-rien. → l'anonymat cap-less exige soit du **vrai crypto**, soit une **projection read-model masquée** (compter sans lire). « Remplacement pas refonte » est **surévalué**.
|
||||
5. **Keyless-fetch = INFÉRÉ et load-bearing** : ajouter un **spike P0** qui le vérifie **avant** P1 (sinon le modèle — polyfill ET Festipod — est inconstruisible).
|
||||
6. **Migration ≠ swap d'API.** `declareConnections` se re-joue chaque session parce que la map est éphémère ; des scellages durables déplacent le grant à l'**acceptation de connexion** + persistent « déjà scellé » — pas d'analogue de `protectedDocsOf` + la boucle de re-dérivation. **Re-architecture consommateur.**
|
||||
7. *(Plausible)* livrer un cap par inbox async **ne re-déclenche pas** `watchShape` (souscrit aux docs de données, pas aux caps) → vues illisibles **périmées** jusqu'à un autre changement. → prévoir un signal de mutation de caps.
|
||||
This brief remains the **overall effort**: P0 verdicts, P1b scope, P2–P4 batches, and the adversarial reviews.
|
||||
|
||||
**Conséquence** : ajouter en tête **P0 (spike keyless-fetch)** et une **piste WriteCap distincte** ; requalifier P2 (le vrai contenu = durabilité + cap-less + re-partage, pas « inverser l'ACL ») ; acter que **sans crypto, la privacy de lecture n'est pas applicable** (choisir : vrai crypto vs projection masquée).
|
||||
## Phase sketch
|
||||
|
||||
Liens : `readcap-and-nuri-model.md`, `packages/client/src/caps.ts`. Côté consommateur,
|
||||
le brief Festipod « réaligner les inscriptions » dépend de ce chantier.
|
||||
- ~~**P1a** — **the surface**~~ **DONE 2026-07-28**: one new type (`ReadCap`), a keyring (`capFor`), per-document sharing to an inbox (`shareCap`). It was the only batch blocking Festipod, and it no longer does. See [`2026-07-27-p1a-cap-surface.md`](2026-07-27-p1a-cap-surface.md) for what landed where. *(An earlier draft listed `DocRef`/`DocCap` branded types, `resolveCapLess` and a durable `sealCapTo` here — all three were **dropped** after adversarial review; the note says why.)*
|
||||
- **P1b** — **the enforcement**: per-doc encryption (cap = key) and closing out the inventory of bypasses. Without it the shape is right but the isolation remains false — so nothing "anonymous" can be claimed. **Requalified 2026-07-30**: the bypass inventory below is really a **virtual user boundary** problem, and it is now specified on its own in [`2026-07-30-virtual-wallet-boundary.md`](2026-07-30-virtual-wallet-boundary.md). That lot precedes or absorbs this one — encrypting each document while any wallet can reach any document secures the windows with the door open.
|
||||
- **P2** — replace the ACL with a **token possession** model (grant = deliver to a recipient; enforcement = possession). *Requalified by the adversarial review: the real content of P2 is **durability + cap-less + re-sharing by the holder**, not "inverting the ACL" — without crypto, inverting produces no observable delta.*
|
||||
- **P3** — revocation by re-key (invalidation + re-delivery, non-retroactive).
|
||||
- ~~**PW** — WriteCap = membership~~ **DROPPED (2026-07-27)**. This batch rested on a notion of membership that **does not exist** in the model (everything is keys and URLs); see the struck-through section above. It was moreover justified by a need for **dedup via signature verification** that the consumer turns out not to have: its dedup rests on the overlay, which is store-scoped. *For the record, two facts verified along the way, not to be re-discovered*: author signature verification **is not called at runtime**; and the author digest is **not** keyed under the read secret — it is keyed by the **outer** overlay, which is public *(it is the commit's **content** that is encrypted, hence the fact that verifying still presupposes being able to read)*. Detail in `nextgraph-current-state.md`.
|
||||
- **P4** — adapt the consumer API + `migration-guide.md`. *The adversarial review requalifies this batch: it is not an API swap but a **consumer re-architecture** (the grant moves to connection acceptance and becomes persistent; `declareConnections` disappears).*
|
||||
|
||||
## Adversarial review (2026-07-20) — to be integrated
|
||||
|
||||
An adversary refuted the brief (7 findings — the 7th marked *(Plausible)*). **To be read through the filter of the Objective above** (shape, not security). The purely **security** criticisms — readable plaintext content (#4), forgeable markers — are **ACCEPTED / out of scope**: the polyfill does not seek to prevent them. What remains are the real **SHAPE / rigor** defects (to be fixed), and a question of **future model** (#5):
|
||||
|
||||
1. **WriteCap forgotten, and "possession" is FALSE there.** Writing is **membership/permissions** (`AddMember`) — an **authorization list**, not key possession (ref. §1); `ng-proxy.ts:28-48` guards every `sparql_update`. → keep a **WriteCap = membership track**; **possession concerns ONLY reading**.
|
||||
2. **P2 "possession without crypto" = the ACL renamed.** Without crypto, "who holds which token" = `Map<doc, Set<holder>>` = the current `readers`: **no observable delta**. The real deltas are **durability + cap-less + re-sharing by the holder** — THAT is the content of P2, not "inverting the ACL".
|
||||
3. **Non-retroactive revocation NOT EMULABLE** without versioning: `read-model.ts:112-118` only reads the current state → "invalidate the old token" = total removal = the inverse of the real thing (the former holder decrypts the **prior** versions). → emulate only "no new reads after re-key" + **document non-retroactivity as non-emulable**.
|
||||
4. **cap-less "without exposing the content" ILLUSORY in the emulation**: content in **plaintext** in the shared wallet; `sparqlQuery`/`inbox.read` **bypass** the filter; `read-filter.ts:30-35` is all-or-nothing. → cap-less anonymity requires either **real crypto** or a **masked read-model projection** (counting without reading). "Replacement not overhaul" is **overstated**.
|
||||
5. **Keyless-fetch = INFERRED and load-bearing**: add a **P0 spike** that verifies it **before** P1 (otherwise the model — polyfill AND Festipod — is not constructible).
|
||||
6. **Migration ≠ API swap.** `declareConnections` is replayed every session because the map is ephemeral; durable seals move the grant to **connection acceptance** + persist "already sealed" — no analogue of `protectedDocsOf` + the re-derivation loop. **Consumer re-architecture.**
|
||||
7. *(Plausible)* delivering a cap through the async inbox **does not re-trigger** `watchShape` (which subscribes to data docs, not to caps) → unreadable views left **stale** until another change. → plan for a cap-mutation signal.
|
||||
|
||||
**Consequence**: add **P0 (keyless-fetch spike)** up front and a **distinct WriteCap track**; requalify P2 (the real content = durability + cap-less + re-sharing, not "inverting the ACL"); record that **without crypto, read privacy is not applicable** (choose: real crypto vs masked projection).
|
||||
|
||||
Links: `readcap-and-nuri-model.md`, `packages/sdk/src/emulated-verifier/caps.ts`. On the consumer side, the Festipod brief "realign the sign-ups" depends on this effort.
|
||||
|
||||
@@ -0,0 +1,329 @@
|
||||
# Brief — P1a: the capability surface
|
||||
|
||||
**Status: IMPLEMENTED 2026-07-28, awaiting review.** Extracted from `2026-07-20-caps-emulation-alignment.md` (which remains the wider chantier: P0 findings, P1b enforcement, P2–P4, and the adversarial reviews). This file is the actionable lot; read it alone to implement.
|
||||
|
||||
The spec below is unchanged — read it first. Everything from here to *Why this lot exists* is the implementation report: what landed, the exact surface a consumer codes against, the decisions taken, and what is **not** verified.
|
||||
|
||||
---
|
||||
|
||||
# Implementation report (2026-07-28)
|
||||
|
||||
> **Superseded in places by later lots — read with [`2026-07-30-virtual-wallet-boundary.md`](2026-07-30-virtual-wallet-boundary.md).** This report was accurate on 2026-07-28 and is kept as written; four of its statements have since been overtaken, and a fifth was wrong when written:
|
||||
>
|
||||
> - *"ReadCaps are NOT persisted as caps anywhere. There is no key store"* — **no longer true.** Both durable registers are now emulated: `shim:readCap` on the store's Store branch (`AddRepo`) and `shim:link` on its User branch (`AddLink`). Caps are read back, not recomputed.
|
||||
> - *"Processing inboxes … Not started"* — **done** (`src/emulated-verifier/connect.ts`), at both levels, including per-document inboxes.
|
||||
> - *"`Nuri` and `ReadCap` are plain strings"* — **superseded the same week**: they are template literal types, so the confusion the runtime guard catches is now also a compile error. The *Typing* section below records the change; the earlier sentences were not rewritten.
|
||||
> - The `:k:` segment throughout — **a ReadCap is `r:`** (`BlockRef::readcap_nuri`, `engine/repo/src/types.rs:518-521`), reported by NextGraph's developer and verified. `:k:` belongs to objects, files and commits.
|
||||
> - *"That branch lists the store's documents… It is the owner's keyring. Upstream, the keyring is the wallet"* — **wrong when written**, and it is the sentence that produced a global in-memory "keyring". There is no keyring object; the wallet holds one root key per user. See [`../readcap-and-nuri-model.md`](../readcap-and-nuri-model.md) §4quater. The word *keyring* is left standing everywhere below because this report is kept as written; read it as *"what the holder holds"*, which is what the code now calls it.
|
||||
> - `fileOwnCaps` — **renamed and split.** Writing a created document's cap is `holdOwnCap`, reading them back is `readStoreCaps`, and a user's own structure (three stores + inbox) is `fileOwnStructure`. Searching the code for `fileOwnCaps` finds nothing.
|
||||
|
||||
|
||||
## What landed
|
||||
|
||||
| Spec | Where |
|
||||
|---|---|
|
||||
| `Nuri` / `ReadCap` (plain strings, `:r:` discriminant) | `packages/sdk/src/model/types.ts`, `src/model/nuri.ts` (internal parse/mint/derive) |
|
||||
| Keyring, one per identity — `capFor` | `src/emulated-verifier/caps.ts` (`CapRegistry`), surfaced as `capFor` in `src/polyfill.ts` |
|
||||
| Caps of my OWN documents (the emulated `AddRepo { read_cap }`) | `src/shared-wallet/account-registry.ts` `fileOwnCaps`, called from `createEntityDoc` and `listMyEntityDocs` |
|
||||
| `shareCap(cap, toInbox)` + reception with no dedicated operation | `src/surface/inbox.ts` (`shareCap`, and the inline absorption in `read`) |
|
||||
| `publishRepoLink` | `src/emulated-verifier/caps.ts`. *(The published-only guard it fed lived in `src/discovery.ts`, removed 2026-07-30 — see the boundary brief.)* |
|
||||
| Possession gate on reads | `src/surface/read-model.ts` (`readUnion`), `src/emulated-verifier/read-filter.ts`, `src/surface/use-shape.ts` |
|
||||
| Cap-mutation signal (a delivered cap re-triggers reads) | `CapRegistry.onChange` → `src/surface/watch-shape.ts` |
|
||||
| Acceptance test (§8) | `test/cross-user-access.test.ts` (see below); isolation end-to-end in `test/isolation-active.test.ts`. *Originally `test/watch-shape.test.ts` (e), on the discovery fold — dropped 2026-07-30 with `discovery.ts`; the property it proved is covered on the model's own terms by the cross-user scenario.* |
|
||||
| Cross-user scenario (§5 non-recursiveness) | `test/cross-user-access.test.ts` — see below |
|
||||
|
||||
### The cross-user scenario, as the PO specified it (`test/cross-user-access.test.ts`)
|
||||
|
||||
Alice owns a **protected** document holding a secret, and a **public** document that carries a **reference** to it — a bare NURI. Then:
|
||||
|
||||
- **Bob** holds the public document's link. He reads it, finds the reference, and can NAME Alice's protected document while reading nothing of it. Publication is **not recursive**.
|
||||
- **Charlie** holds the same link, plus the protected document's cap — delivered by Alice to his inbox. Same document, same reference, same path: he reads through it.
|
||||
- **The only difference between them is what their keyring holds.** Nobody was named to the registry; Alice addressed an inbox.
|
||||
- **Dynamic**: Bob is refused, Alice delivers the cap to *his* inbox, his client processes it — and the read that was empty yields the content. Filing the cap fires `CapRegistry.onChange`, so a reader wired to that signal (which is what `watchShape` does internally) re-reads on its own.
|
||||
|
||||
One property this makes explicit and that is worth confirming: **the bare NURI of a PUBLIC document is not enough either** — its repo link is. See *Publication travels as a link* below.
|
||||
|
||||
## The exact surface a consumer codes against
|
||||
|
||||
From `@ng-eventually/sdk/polyfill`:
|
||||
|
||||
```ts
|
||||
capFor(nuri: Nuri): ReadCap | undefined // the keyring lookup
|
||||
shareCap(cap: ReadCap, toInbox: Nuri): Promise<void>
|
||||
getCaps(): CapRegistry
|
||||
resetCaps(): void // tests / fresh wallet ONLY — never on identity change
|
||||
setCurrentUser(id: PrincipalId | null): void // selects WHICH keyring is consulted
|
||||
```
|
||||
|
||||
On `CapRegistry` (reached via `getCaps()`):
|
||||
|
||||
```ts
|
||||
open(nuri: Nuri, scope: Scope): ReadCap // "this document is mine, in this scope"
|
||||
mint(nuri: Nuri): ReadCap // …its protected/private half
|
||||
publishRepoLink(nuri: Nuri): ReadCap // …its public half — returns the SHAREABLE LINK
|
||||
learn(cap: ReadCap): void // file a cap I was given (throws on a bare reference)
|
||||
capFor(nuri: Nuri): ReadCap | undefined
|
||||
isPublished(nuri: Nuri): boolean
|
||||
isEnforcing(): boolean // false until the first cap exists
|
||||
onChange(listener: () => void): () => void // keyring mutations
|
||||
grantWrite / canWrite / governsWrite / hasWritePolicy // unchanged, decorative, P1b
|
||||
clear(): void
|
||||
```
|
||||
|
||||
Plus the narrowing guards, from the SDK-identical entry:
|
||||
|
||||
```ts
|
||||
isNuri(s: string): s is Nuri // an untrusted string → a Nuri
|
||||
hasReadCap(s: string): s is ReadCap // …→ a ReadCap; the ONLY such narrowing
|
||||
```
|
||||
|
||||
Types: `Nuri`, `ReadCap`, `Scope`, `PrincipalId` are all exported from the SDK-identical entry (`export * from "./types"`). `Scope` is a literal union, so `open(doc, "protected")` is compiler-checked. `capFor` returns `ReadCap | undefined`, so under `strict` the consumer is forced to handle "I hold nothing".
|
||||
|
||||
Every call accepting a `Nuri` also accepts the cap-bearing form and normalizes it (`targetOf`), so passing a cap where a NURI is expected is never a silent mismatch — and it type-checks, because `ReadCap` is assignable to `Nuri`.
|
||||
|
||||
## Typing — template literal types, not `string`, not branded types
|
||||
|
||||
**Amended on the PO's instruction (2026-07-30), after the first pass shipped both as `type X = string`.** The types are now:
|
||||
|
||||
```ts
|
||||
type Nuri = `did:ng:${string}`
|
||||
type ReadCap = `did:ng:${string}:r:${string}`
|
||||
```
|
||||
|
||||
Still **strings** — assignable to `string`, JSON-serializable, no wrapper object — so nothing has to be *un*-typed when the real SDK arrives and takes `nuri: String`. §1's two documented objections to branded types do not apply: there is nothing to un-type at migration, and the cost at the ORM/SPARQL boundaries was **measured at zero** (see below). What the template buys is the single asymmetry that matters: a `ReadCap` is freely usable wherever a `Nuri` is expected (a cap IS a NURI with the key inside — upstream's one `NuriV0`), while a bare `Nuri` where a `ReadCap` is required is a **compile error**.
|
||||
|
||||
This is the one place the implementation departs from the letter of §7 (*"the discrimination lives in what you can obtain, not in what the compiler permits"*). It was an explicit PO decision: the consumer app benefits from the distinction, and possession is still what actually decides — the compiler only stops the app from writing a call the model has no meaning for.
|
||||
|
||||
**Cost, measured on the whole repo**: typing both aliases produced 16 errors, all of them at genuine boundaries, and every one resolved by narrowing rather than casting:
|
||||
|
||||
| Boundary | Resolution |
|
||||
|---|---|
|
||||
| Broker (`docs.docCreate`, whose `ng` is `any`) | Validates with `isNuri` and throws — the declared `Promise<Nuri>` was an unchecked promise every typed NURI downstream rested on |
|
||||
| SPARQL (`store-registry` `canonicalDoc`, `readScopeIndex`) | Narrow with `isNuri`; a stored value that is not a reference is now discarded instead of flowing through as a "document NURI" |
|
||||
| ORM (`read-filter` `docOf`, an untyped `@graph`) | Narrow with `isNuri` |
|
||||
| Inbox payload | Free — it already tested `hasReadCap`, which is now a **type guard** (`s is ReadCap`) |
|
||||
| `assertNuri` | Made generic (`<T extends string>(nuri: T): T`) so the caller's type flows through instead of widening to `string` |
|
||||
| `nuri.ts` `targetOf` | **The one cast in the library**, in the primitive that defines the contract, so no caller needs one |
|
||||
| Playwright bridge (e2e) | An `asNuri` helper that throws — arguments cross the bridge as plain strings |
|
||||
|
||||
`isNuri` and `hasReadCap` are **exported from the SDK-identical entry**, so a consumer narrows its own strings (storage, URL, JSON, a form) the same way instead of casting.
|
||||
|
||||
**The runtime guards stay, and are not redundant**: a JavaScript consumer never meets the compiler, and a cap read back from storage and *cast* rather than narrowed reaches the library just the same. `CapRegistry.file` — the single door into any keyring — refuses a reference with no `:r:`, and `inbox.shareCap` does likewise. That guard was added during implementation after the trap was demonstrated: `learn(someBareNuri)` filed the bare reference under its own name, `capFor` returned it, and the document read — "naming is not reading" silently becoming "naming is reading".
|
||||
|
||||
*(An earlier version of this section flagged a gap around what a consumer put into a discovery `ref`. Moot since 2026-07-30: `discovery.ts` was removed — there is no discovery. Circulating a link is now an explicit act, `shareCap(link, inbox)`, whose argument is typed `ReadCap` and checked at runtime.)*
|
||||
|
||||
## How this articulates with the virtual users
|
||||
|
||||
This is the part worth reviewing closely, because P1a puts a NextGraph concept (the keyring = the wallet) on top of an emulation that already fakes wallets.
|
||||
|
||||
**Upstream, the keyring IS the wallet.** Here there is ONE physical user that everybody opens, and an "identity" is a *virtual* wallet: a shim account in `store-registry`, mapped to three scope-index documents. So the registry holds **one keyring per virtual user** — `Map<accountKey, Map<Nuri, ReadCap>>` — and `setCurrentUser(id)` selects which one is consulted. Switching identity switches keyrings structurally; there is nothing to reset and nothing is wiped.
|
||||
|
||||
**Where a virtual user's caps come from, and what makes them survive a reload:**
|
||||
|
||||
- *Its own documents* — the scope-index document of the (account × scope) plays the role of the store branch that carries `AddRepo { read_cap }` upstream. `createEntityDoc` files the cap on creation; `listMyEntityDocs` refiles them on any later session. Nothing is persisted as a key store: the emulated key is derived from the NURI, so listing the documents is enough to hold them again. **This is why a fresh page reads its own documents with nothing re-declared.**
|
||||
- *Documents shared with it* — the cap lives in the recipient's **inbox document**, which is persistent in the shared wallet. It re-enters the keyring when the consumer processes that inbox.
|
||||
|
||||
**Today, caps received are refiled only when the inbox is read** — which means the consumer's startup sequence has to do it. **The PO has ruled that this is wrong** (see *Follow-up* below): inbox processing belongs to the polyfill, on connection, not to the app.
|
||||
|
||||
**A defect found while writing this up, and fixed.** The keyring was keyed on the **raw** `currentUser`, while the shim keys accounts through the consumer-injected `normalizeId`. So `setCurrentUser("@Alice")` and `setCurrentUser("alice")` — ONE shim account, one set of documents — produced **two keyrings**, and the second one was empty: the identity stopped reading its own documents. The keyring now keys the same way the shim does, so one virtual user has exactly one keyring however its id is spelled. Locked by `test/isolation-active.test.ts` *one keyring per virtual WALLET, not per spelling of its id*.
|
||||
|
||||
**Still per-process, and that is correct**: the keyring is in memory, so two tabs have two keyrings. Each rebuilds itself the same way (scope index + inbox), which is exactly how a real wallet behaves on two devices.
|
||||
|
||||
## Where NURIs and ReadCaps are actually stored
|
||||
|
||||
Worth stating plainly, because "the keyring" is in memory and that sounds fragile until you see what backs it.
|
||||
|
||||
**NURIs are persisted, in RDF, in the shared wallet** — they always were:
|
||||
|
||||
| What | Where it lives | Written by |
|
||||
|---|---|---|
|
||||
| account → its 3 scope-index documents | the **doc-shim**, itself named by a write-once pointer triple in the private store-root | `store-registry.writeRecord` |
|
||||
| scope index → the NURIs of that scope's entity documents | the per-(account × scope) **index document**, as `shim:contains` literals | `store-registry.createEntityDoc` |
|
||||
| a document's own content, including any reference to another document | that **document's** graph | the consumer's write path |
|
||||
| an inbox deposit (payload, ts, from) | the **inbox document's** graph | `inbox.post` |
|
||||
|
||||
**ReadCaps are NOT persisted as caps anywhere.** There is no key store, no trousseau document, nothing on disk that says "this identity holds these keys". The keyring is a plain in-memory `Map<accountKey, Map<Nuri, ReadCap>>` inside `CapRegistry`, rebuilt from scratch on every page load out of two persisted sources:
|
||||
|
||||
- **my own documents** → `listMyEntityDocs` reads the store's document list (persisted NURIs) and re-mints each cap, whose value is the constant `OK`. So *knowing which documents are mine is knowing their caps*. Upstream the key really is stored, on the Store branch (`AddRepo { read_cap }`); emulating that storage rather than re-minting is a separate lot.
|
||||
- **documents shared with me** → the cap sits **inside an inbox deposit's JSON payload**, which IS persisted (it is an ordinary triple in the inbox document's graph). Processing the inbox re-files it. So a shared cap survives a reload because the *delivery* is durable, not because we stored a key — which is exactly the upstream shape, where the seal sits in the inbox until the verifier applies it.
|
||||
|
||||
Consequence to keep in view: **a cap is only as durable as its delivery**. That is why the PO's follow-up below (the polyfill processing inboxes on connection) matters more than it looks — until it lands, the durability of a shared cap depends on the app remembering to read its inbox.
|
||||
|
||||
Second consequence, on the emulated key being derived: anyone can compute any document's cap from its NURI. That is the P1a/P1b line, stated once more — possession is a **shape** here, not a protection.
|
||||
|
||||
## Publication travels as a link — a choice to confirm
|
||||
|
||||
§5 says a public item is read by "whoever has the URL", and §8 says a harvested **bare** reference must yield nothing. Both hold only if what circulates for a public document is its **repo link** (`publishRepoLink` → `did:ng:o:…:r:…`), not its bare NURI. That is what was implemented, and the cross-user test pins it: Bob holding only the public document's bare NURI reads nothing; holding its link, he reads it.
|
||||
|
||||
The alternative — making a published document readable from its bare NURI — was rejected because the "published" fact would then live **only in the local registry**: another tab, another process, another user would have no way to know a document was published, and the emulation would stop being portable. Carrying the fact **in the data** (the link) is what makes it work across processes, and it matches `RepoLinkV0` upstream.
|
||||
|
||||
This is the point where the emulation is furthest from the eventual target, where the public store may not encrypt at all and a bare NURI would suffice. Per §5 that is fine — *"if the public store does not behave as this principle describes, this library adapts, not the consumer"* — but it is a deliberate divergence and the PO should confirm it.
|
||||
|
||||
## A debt this lot created — the unguarded inbox — **CLOSED 2026-07-30**
|
||||
|
||||
`inbox.read` had no guard and **absorbs caps into the reader's keyring**, so `inbox.read(someoneElsesInbox)` pocketed the caps addressed to them and directed sharing was defeatable by anyone who knew an inbox NURI. The inbox was never guarded before either, but before P1a it carried nothing that granted access.
|
||||
|
||||
Fixed in step 2 of [`2026-07-30-virtual-wallet-boundary.md`](2026-07-30-virtual-wallet-boundary.md): an inbox now BELONGS to a virtual user (`storeRegistry.userInbox`), and only its owner may read it. Depositing into anyone's inbox stays open — that is the one legitimate cross-wallet act, and the only way a link crosses between wallets at all.
|
||||
|
||||
## Follow-up decided by the PO — to plan, NOT in this lot
|
||||
|
||||
**Processing inboxes is the polyfill's job, not the app's** (PO, 2026-07-30). As soon as the app connects a user/wallet, the polyfill must process that identity's inboxes itself — the consumer should never have to remember to do it for its shared documents to become readable.
|
||||
|
||||
And it is inboxes, plural, at **two levels**:
|
||||
|
||||
- the **user/wallet** inbox — where ReadCaps arrive;
|
||||
- the inbox of **every document the user owns**, so deposits land per document too. *(The justification originally given here — "a document has its own inbox upstream" — is **false**; see the correction in [`2026-07-30-virtual-wallet-boundary.md`](2026-07-30-virtual-wallet-boundary.md) step 7. The design decision stands on the consumer's need and on the record's per-`repo_id` shape, not on an upstream document inbox that does not exist.)*
|
||||
|
||||
What exists today and is reusable: `inbox.readSynced` (the cold, barrier-gated read meant exactly for "process the inbox at (re)connection"), the inline cap absorption in `inbox.read`, and `CapRegistry.onChange` to re-trigger the reads a late cap unblocks. What is missing is the **orchestration**: a connection hook that enumerates the identity's inboxes (wallet-level + one per owned document, via the scope indexes) and processes them, idempotently and without polling.
|
||||
|
||||
Not started. It changes the consumer contract in the right direction (one less obligation), so it should land before the consumer re-architecture settles.
|
||||
|
||||
## Decisions taken while implementing, none contradicting the spec
|
||||
|
||||
- **`open(nuri, scope)` was kept** (it is in neither the §6 table nor the removals) as the single "this document is mine, in this scope" act — `mint` for protected/private, `publishRepoLink` for public. It no longer touches write caps: arming that guard would be enforcement this batch does not do.
|
||||
- **`grantWrite` / `canWrite` were left exactly as they were** (an authorization list, decorative, guard bypassed by every internal writer) and now have to be called explicitly — `open` used to set them as a side effect. They belong to P1b.
|
||||
- **`shareCap` is implemented in `inbox.ts`** and re-exported from `/polyfill`, so it is reachable both as `inbox.shareCap` (SDK-identical entry, via `export * as inbox`) and from the polyfill surface. Deliberate: sharing a cap **is** an inbox deposit upstream, and at migration this call becomes the native sealed deposit — a real SDK method, whatever it ends up being called (`inbox_post_link` was our own proposed name, not an announced API) — so hiding it from the SDK entry would have been the less faithful choice. §7's boundary holds where it matters: the registry, `capFor` and `CapRegistry` stay on the polyfill side, and every signature is a plain string.
|
||||
- **The stand-in key is the constant `OK`** (`nuri.ts`; it was a derived FNV-1a digest until the PO simplified it on 2026-07-30). The only question the emulation answers is *do I hold this cap or not*, so the value says that and nothing more — a digest merely looked like a key. Possession is a shape here, not a protection; P1b replaces the constant with a real key.
|
||||
- **`resetCaps()` clears in place** rather than rebuilding the registry, so a `watchShape` subscribed to the change signal does not end up holding a listener on an orphaned instance.
|
||||
- **The scope-index feed is holder-scoped** (`fileOwnCaps` compares through the shim key): the cross-account fan-out `listEntityDocs` files nothing, because other accounts' caps are emphatically not ours to hold.
|
||||
|
||||
## Verification status
|
||||
|
||||
- **Unit suite green — 146 tests**, typecheck clean on `src`, `test` and the e2e harness.
|
||||
- The typing was verified from a **consumer's** point of view, not just the library's: a synthetic app compiled against the entry points shows the two real mistakes (`shareCap(bareNuri, …)` and passing a raw `string` from storage) as compile errors, while every correct path — `capFor(doc)` → `shareCap(cap, inbox)`, and narrowing with the exported guards — needs no cast.
|
||||
- The acceptance test was **mutation-checked**: reverting both gardes (the discovery fold and the `readUnion` possession gate) makes `watch-shape.test.ts` (e) fail with the bare-referenced document reappearing. The test has teeth.
|
||||
- **The e2e ran against the live broker (`nextgraph.eu`) on 2026-08-03 — 39 passed, 0 failed.** The first run was 22/8, and the eight refusals were not test noise: they exposed a **real hole in the surface**. `docs.docCreate` filed no cap for the creator, so a consumer could create a document through the public primitive and then be refused reading or writing it. Upstream that cannot happen — `doc_create` commits `AddRepo { read_cap }` to the store's Store branch, so the creator holds it from the first instant. Fixed at `packages/sdk/src/surface/docs.ts:73`, and deliberately NOT replicated in `shared-wallet/physical.ts`: the shim's own documents belong to no user, and `store-registry` files their caps where it knows whose they are. The remaining failures were the harness acting as a second identity without establishing it (`createEntityDoc(id, …)` with someone else connected) or reading an arbitrary document as an inbox; both are now `setCurrentUser` + `userInbox`, which is what a consumer must do too.
|
||||
- **An e2e run against a persistent wallet must use a FRESH identity per run.** The second run was green and the third was not, on unchanged code: moving the inbox tests onto `userInbox(id)` made the inbox *stable for its owner* — which is the point of an inbox — so a fixed id accumulates every past run's deposits and `deposits.length === 2` drifts to 4. Green-then-red on identical code is the tell. The disposable thing is the **user**, not the inbox: `run.ts` now stamps `@inbox-user-`/`@watcher-`/`@friend-` with `Date.now()`, as it already did for `@alice-`. Any future step that resolves a durable per-user document (inbox, stores, Links) inherits this constraint.
|
||||
- **The cap registry is process-wide and `bun test` shares modules across files**, so suites that read without declaring caps now reset explicitly (`read-model.test.ts`, `watch-shape.test.ts`). Worth knowing before adding a suite.
|
||||
|
||||
## Documentation state
|
||||
|
||||
The permanent documentation was updated in the same pass (root `README.md`, `packages/sdk/README.md`, `docs/simulation.md`, `docs/migration-guide.md` §1 + the assumed `declareConnections` break, `docs/read-model.md`, `docs/readcap-and-nuri-model.md` §5, `docs/nextgraph-current-state.md`, `packages/sdk/docs/sdk-reference.md`). **If the review changes the surface, those are the files to re-align** — they describe the code as it stands now, not a validated state.
|
||||
|
||||
---
|
||||
|
||||
Written 2026-07-27, after two adversarial reviews and three corrections from the PO. Background: `../vision.md` (why this library exists), `../readcap-and-nuri-model.md` (the target model, verified against `nextgraph-rs`).
|
||||
|
||||
## Why this lot exists
|
||||
|
||||
`emulated-verifier/caps.ts` currently models read rights as an **ACL** — a `Map<doc, Set<principal>>` plus `grantRead(doc, grantee)`. That is the **exact inversion** of the real model, where reading is **key possession**: whoever holds the key reads, and there is no authorization list anywhere.
|
||||
|
||||
This is not a security problem — the library is deliberately insecure and that is accepted (see `../vision.md`). It is a **shape** problem, and shape is the only thing this library exists to get right. A consumer coded against an ACL is coded against a model that will never exist, and will have to be rewritten.
|
||||
|
||||
## Scope: shape only, not enforcement
|
||||
|
||||
- **P1a (this brief)** — the surface consumers see.
|
||||
- **P1b (separate)** — per-doc encryption and closing the read paths that bypass the guard.
|
||||
|
||||
Only P1a blocks the consumer, because the consumer must be written as if NextGraph were finished. P1b can follow.
|
||||
|
||||
> **After P1a the shape is right and the isolation is still fake.** Nothing may be claimed as "anonymous" or "private" until P1b lands. Say so in the README if it helps.
|
||||
|
||||
## Guiding constraint: stay close to NextGraph's concepts
|
||||
|
||||
Stated by the PO, and it is the acceptance criterion for the design as much as for the code:
|
||||
|
||||
> Stay as close as possible to NextGraph's concepts — and to its SDK's — to keep development simple and to keep the number of notions someone must discover small when they already know NextGraph and open this library.
|
||||
|
||||
Every invented name is **vocabulary debt**: the reader has to carry a translation table in their head. The first draft of this spec introduced eight new notions; adversarial review reduced it to two. Hold that line.
|
||||
|
||||
## The design
|
||||
|
||||
### 1. Types — one new name
|
||||
|
||||
A NURI is **one object**, with or without the key inside — upstream, `NuriV0 { target, access }`, where a cap-less NURI simply has an empty `access`. `did:ng:` is the **URI scheme prefix**, present on inboxes, branches and overlays alike; it does not mean "without cap". The discriminant is the **`:r:` segment** *(the spec said `:k:`; corrected 2026-07-30 on a report from NextGraph's developer — `:k:` belongs to objects/files/commits, a ReadCap is `r:{base64url(serde_bare(ObjectRef))}`, `repo/types.rs:518`)*.
|
||||
|
||||
```ts
|
||||
type Nuri = string // did:ng:o:{doc}:v:{overlay} — names, does not read
|
||||
type ReadCap = string // …:r:{cap} — names AND reads
|
||||
```
|
||||
|
||||
`Nuri` **keeps its current meaning** in this package (~90 call sites, untouched): the cap-less form. `ReadCap` is the upstream name — do not invent another.
|
||||
|
||||
A parsed form `{ target, readCap? }` — a 1:1 mirror of `NuriV0 { target, access }` — may be used **inside** the library. It must not surface in the SDK-identical entry's signatures.
|
||||
|
||||
**Do not use branded types.** They were in the first draft and were dropped deliberately: the real SDK takes `nuri: String` and enforces at **runtime, through cryptography**. A compile-time guarantee is a concept NextGraph does not have, and a consumer who typed everything would have to *un-type* it when the real SDK arrives — the opposite of the goal. The cost was also measured: branded types force a cast at every ORM and SPARQL boundary.
|
||||
|
||||
### 2. The keyring — where caps come from
|
||||
|
||||
`doc_create` returns a **cap-less** NURI. So a rule like "no function ever goes from a bare reference to a cap" is wrong: it would leave a document's own creator unable to obtain that document's cap.
|
||||
|
||||
The real mechanism: on every document creation, an `AddRepo { read_cap }` is committed to a **branch of the store** (the store is itself a repo, with typed branches — "branch" here has nothing to do with git). That branch lists the store's documents, each with its read key. **It is the owner's keyring.** Upstream, the keyring is the **wallet**.
|
||||
|
||||
```ts
|
||||
capFor(nuri: Nuri): ReadCap | undefined
|
||||
```
|
||||
|
||||
The invariant, correctly stated:
|
||||
|
||||
> **You do not derive a cap from a bare reference. You look it up in your keyring — or you were given it.**
|
||||
|
||||
`capFor` absorbs `canRead(doc)` (`capFor(n) !== undefined`) and drops its ACL verb.
|
||||
|
||||
**The keyring is not the sharing mechanism.** Handing over a store cap would give away everything the store contains, present and future. That is not the gesture (see §3). This confusion is easy and expensive — it was made once already during design.
|
||||
|
||||
### 3. Sharing — one document, to one or more recipients
|
||||
|
||||
**The unit of sharing is the document**, consistent with the consumer's own doctrine ("the document is the unit of sharing and of rights").
|
||||
|
||||
```ts
|
||||
shareCap(cap: ReadCap, toInbox: Nuri): Promise<void>
|
||||
```
|
||||
|
||||
Recipients are addressed as **inboxes** — which `inbox.post(targetInbox: Nuri)` already does in this package. There is no `PrincipalId` here: that notion exists nowhere upstream, and the first draft removed `principal` from `canRead` (calling it the ACL inversion) only to reintroduce it here.
|
||||
|
||||
**Caps received need no dedicated operation.** They arrive as inbox deposits of kind `cap`, consumed by the **existing** `inbox.watch`. This also fixes a known gap: a cap delivered asynchronously now triggers a re-read naturally, instead of leaving stale views.
|
||||
|
||||
> **Upstream status: this is a GAP, not a disagreement.** The field exists (`ContactDetails.read_cap`, commented "*if user wants to share the content of profile*") but the message construction is `unimplemented!()`, its only caller passes "without read_cap", and the receiver **discards** the cap. The shape is right; the implementation is absent. We emulate it meanwhile — filed as `orm-tests/INBOX/2026-07-27-inbox-cap-delivery-not-implemented.md`, including what to remove from this library once upstream lands it.
|
||||
|
||||
### 4. Key rotation — automatic redelivery, not loss of access
|
||||
|
||||
When a key is rotated, the new one is **sent to the inbox** of users who keep access, and that inbox is **processed automatically** as soon as one of the user's clients connects.
|
||||
|
||||
So access is not lost, it is **deferred** until the next connection — consistent with local-first. Consequences for the surface:
|
||||
|
||||
- **No subscription obligation to expose.** The consumer implements nothing to "keep" an access.
|
||||
- Redelivery uses **the same channel** as the initial delivery, so §3 covers both with no special case.
|
||||
- **Revocation** stays what it is: stop redelivering, non-retroactive.
|
||||
|
||||
> An earlier draft said the opposite ("whoever does not stay subscribed loses access"). That came from an upstream comment describing the **current state**, read as if it gave the **intention**. It does not. Source verifies a mechanism; it never states a direction.
|
||||
|
||||
### 5. Public content — readable by URL, and NOT recursive
|
||||
|
||||
> **An item in the public store is public: whoever has the URL reads the content.** But **not recursively** — public content may *reference* private content, and the reference does not grant access to what it references.
|
||||
|
||||
This is a **second mechanism** alongside key possession, not an exception to it. The non-recursiveness is what carries the value: it allows a public object that **points at** private identity without disclosing it — exactly the pattern the consumer needs.
|
||||
|
||||
*Implementation detail the shape must not depend on*: NextGraph is moving toward **not encrypting** public store content (data still signed). And if the public store does not behave as this principle describes, **this library adapts** — not the consumer.
|
||||
|
||||
### 6. What disappears or is renamed
|
||||
|
||||
| Today | Becomes |
|
||||
|---|---|
|
||||
| `grantRead(doc, grantee)` | `shareCap(cap, toInbox)` |
|
||||
| `canRead(doc, principal)` | absorbed by `capFor(nuri)` — the `principal` parameter **was** the ACL inversion |
|
||||
| `protectedDocsOf(owner)` | **removed** — the re-derivation loop disappears |
|
||||
| `makePublic(doc)` | `publishRepoLink` — the shareable link has an upstream name (`RepoLinkV0`) |
|
||||
| `grantWrite` / `canWrite` | deferred to P1b — currently **decorative** (the guard never fires) |
|
||||
| `resetCaps()` on identity change | **switch** keyrings, do **not** wipe |
|
||||
| `PrincipalId` in the cap surface | **removed** — recipients are inboxes |
|
||||
|
||||
`resetCaps()` is the trap that can make this lot look finished while it is not: if switching identity still wipes, durability is a lie and the per-session re-declaration comes back under another name.
|
||||
|
||||
### 7. Boundary: SDK-identical entry vs `/polyfill`
|
||||
|
||||
Caps live under `/polyfill` today; `index.ts` is the SDK-identical entry. Keep it that way, and keep `index.ts` signatures on plain strings — that **is** what the real SDK does. The discrimination lives in what you can **obtain** (the keyring), not in what the compiler permits.
|
||||
|
||||
### 8. Acceptance test — no cryptography required
|
||||
|
||||
`watch-shape` currently harvests **every** `did:ng:` string it finds in a discovery reference and folds those documents into the **read** set. A bare reference therefore grants **full read** today — the semantics exactly inverted.
|
||||
|
||||
After P1a: a harvested bare reference yields **nothing**, for want of a cap in the keyring — which is what real NextGraph does. The test holds without a line of encryption, which is what makes the P1a/P1b split honest rather than cosmetic.
|
||||
|
||||
## Consumer impact
|
||||
|
||||
`declareConnections` **disappears**. This is not an API swap: today it re-declares every grant on every session because the ACL is in-memory. With delivered caps, the grant moves to the moment a connection is **accepted**, and persists. Plan for consumer re-architecture, and update `../migration-guide.md`.
|
||||
|
||||
## What this lot does NOT do
|
||||
|
||||
Closing the read paths that bypass the guard — `docs.sparqlQuery`/`sparqlUpdate`, the whole inbox, `store-registry`, `discovery.readIndex`, `subscribe`, `open-repo`. Only four sites consult caps today. That inventory is P1b's scope and is listed in `2026-07-20-caps-emulation-alignment.md`.
|
||||
@@ -0,0 +1,116 @@
|
||||
# Brief — align on NextGraph's own model: users, stores, branches
|
||||
|
||||
> ## REFUTED by adversarial review, 2026-07-30 — do not implement as written
|
||||
>
|
||||
> Seven defects, four of them factual errors about NextGraph. The three that break the plan outright:
|
||||
>
|
||||
> 1. **D4 rests on a false premise.** There IS a register for received caps: `AddLink { read_cap }` on the **User branch** of the private store — *"so that a user can share with all its device a new Link they received… Only external repos are accepted"* (`engine/repo/src/types.rs:1934-1950`, verifier arm `commits/mod.rs:681`). It is wallet-resident and **cross-device** — the exact opposite of D4's per-browser localStorage. Corrected in [`../readcap-and-nuri-model.md`](../readcap-and-nuri-model.md) §4quinquies.
|
||||
> 2. **D2's rejection of the named graph is factually wrong.** A `GRAPH <…:v:…:b:…>` quad IS resolved to that branch and committed on **its own** topic (`engine/verifier/src/commits/transaction.rs:386-434`); the verifier does exactly this in `update_header`. An unknown branch id errors rather than silently landing on Main. And a branch **is** a valid SPARQL-update target: `TargetBranchV0::is_valid_for_sparql_update` returns true for `BranchId` (`engine/net/src/app_protocol.rs:77-82`) — the fact table's claim to the contrary was wrong twice over.
|
||||
> 3. **The Store branch holds no triples at all.** `BranchCrdt::None`, *"used by Overlay, Store and User BranchTypes"* (`engine/repo/src/types.rs:1420`). It is a stream of service commits (`AddRepo`/`RemoveRepo`), not a graph — so all three D2 candidates were RDF inventions dressed as fidelity.
|
||||
>
|
||||
> And four more, all confirmed:
|
||||
>
|
||||
> 4. **D4 would delete a working recovery path.** Inbox deposits are never removed (`packages/sdk/src/surface/inbox.ts`), so a second device/tab recovers its caps by re-reading. localStorage-without-re-reading loses them permanently, and contradicts P1a's delivered doctrine that per-process rebuild "is correct".
|
||||
> 5. **D3 is false outside entity documents.** `capFor(scopeIndexDoc)` and `capFor(userInbox)` are undefined before *and after* `listMyEntityDocs` — their caps can only ever be derived. Yet the boundary brief requires them reachable. Upstream that root comes from the wallet plus `AddSignerCap` on the User branch — a level the fact table omitted entirely.
|
||||
> 6. **`doc_create` writes four times, not two** (+ the class quad on the Header branch, + `AddSignerCap` on the User branch).
|
||||
> 7. **Ordering defect: D2 before the boundary guard opens cap harvesting.** Once caps are triples in `scopeIndexDoc(bob,…)`, and both `scopeIndexDoc` and `docs.sparqlQuery` are exported, `setCurrentUser("mallory")` reads Bob's caps. Today `mintCap` is unexported, so a NURI yields nothing. **The guard must land before the caps become triples.**
|
||||
>
|
||||
> Also flagged: "store" already means the *native* store in this codebase (`RegistrySession.privateStoreId`), so D1's `privateStore`/`storeDoc` collide head-on; "the keyring notion disappears" contradicts `readcap-and-nuri-model.md` §4quater, which calls the Store branch the owner's keyring; upstream `ldp#contains` takes an **IRI** object while the polyfill writes a **literal**, so D1 is not "nothing behavioural".
|
||||
>
|
||||
> Rewrite required. The verified facts are being folded back into `readcap-and-nuri-model.md` first; the plan is re-derived from there, not from this text.
|
||||
|
||||
**Status: REFUTED 2026-07-30 — superseded, kept as the record of what was wrong. Original header follows.**
|
||||
|
||||
**Status: plan, not started. 2026-07-30.** Companion to [`2026-07-30-virtual-wallet-boundary.md`](2026-07-30-virtual-wallet-boundary.md) (whose steps 3–4 are still pending) and to the caps chantier. This lot is about saying — and storing — what NextGraph says and stores, instead of a parallel vocabulary of our own.
|
||||
|
||||
## Why this lot exists
|
||||
|
||||
Two PO corrections, 2026-07-30:
|
||||
|
||||
> If NextGraph stores the key next to the document, then that is what we do. Without encryption we simply store a stand-in value. Stay as close as possible to how NextGraph works.
|
||||
|
||||
> I don't like the name "scope container". Let's keep NextGraph's names. We adapt for the polyfill when we need to, but there too we must stay as close as possible.
|
||||
|
||||
And the vocabulary correction underneath both:
|
||||
|
||||
> In the NextGraph code "wallet" is called "user", because a wallet is only a keyring. Virtual user → **virtual user**; physical user → **physical user**.
|
||||
|
||||
The library currently invents three things NextGraph does not have — a *keyring*, a *scope index*, a *virtual user* — and recomputes a key NextGraph stores. Each invention is a translation table a reader must carry, and each is a place where the consumer learns a model that will not exist.
|
||||
|
||||
## Verified facts this plan rests on
|
||||
|
||||
All read in `nextgraph-rs` (`git 213338f6`) on 2026-07-30, recorded in full in [`../readcap-and-nuri-model.md`](../readcap-and-nuri-model.md) §4quinquies. The load-bearing ones:
|
||||
|
||||
| Fact | Source |
|
||||
|---|---|
|
||||
| A wallet holds SEVERAL users: `SensitiveWalletV0.sites: HashMap<String, SiteV0>` | `engine/wallet/src/types.rs:434,457` |
|
||||
| A user (site) owns the three stores; `UserId = PubKey` | `engine/verifier/src/site.rs:23`; `engine/repo/src/types.rs:453` |
|
||||
| The wallet holds ONE root key per user — the private store's read cap | `site.rs:52` (`get_individual_site_private_store_read_cap`) |
|
||||
| `doc_create` writes TWICE: `AddRepo { read_cap }` on the **Store branch**, and `ldp:contains` on the **Main branch** | `engine/verifier/src/request_processor.rs:697-710`; `verifier.rs:2172-2199` |
|
||||
| Replaying the Store branch is what reloads the repos with their keys | `engine/verifier/src/commits/mod.rs:644-664` |
|
||||
| A branch is a NAMED GRAPH `did:ng:o:{repo}:v:{overlay}:b:{branch}`, with its own pub/sub topic and CRDT | `engine/net/src/app_protocol.rs:267-273`; `engine/repo/src/types.rs:1478-1501` |
|
||||
| Anchoring on a document targets its **Main** branch | `request_processor.rs:161-168` |
|
||||
| SPARQL cannot be anchored on a branch — every other target is `unimplemented!()` | `request_processor.rs:283` |
|
||||
| A `Store` branch exists only on a real store, created on a path `doc_create` does not take | `engine/repo/src/store.rs:425-440` |
|
||||
| A received cap has NO register: `ContactDetails.read_cap` is never read by the receiver | `engine/verifier/src/inbox_processor.rs:778-847` |
|
||||
| Durability of a received cap comes from OPENING the repo, which persists its `read_cap` in local user storage | `engine/verifier/src/user_storage/repo.rs:109,219,248,359`; `verifier.rs:542-544` |
|
||||
|
||||
**Not verified, and therefore not relied on anywhere below**: whether a `GRAPH <…:b:…>` write from the JS SDK round-trips through a real broker. It is assumed BROKEN and avoided.
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1 — Vocabulary follows NextGraph
|
||||
|
||||
| Ours today | Becomes | Why |
|
||||
|---|---|---|
|
||||
| virtual user | **virtual user** | a wallet is a keyring; what owns three stores is a user (site) |
|
||||
| physical user | **physical user** | NextGraph sees exactly one user; our identities are virtual ones |
|
||||
| keyring (`CapRegistry`) | *(the notion disappears — see D3)* | there is no keyring object in NextGraph, and the wallet does NOT hold every key |
|
||||
| scope index / scope container (`scopeIndexDoc`, `readScopeIndex`, `indexDocOf`, `INDEX_SUBJECT`) | **store** (`storeDoc`, `readStore`, …) | the thing that lists a user's documents IS a store |
|
||||
| `shim:contains` | `ldp:contains` | NextGraph's own predicate for exactly this |
|
||||
|
||||
`docPublic` / `docProtected` / `docPrivate` on `VirtualUserRecord` already read as stores; keep them, or rename to `publicStore` / `protectedStore` / `privateStore` for symmetry.
|
||||
|
||||
### D2 — Emulate the Store branch as a distinct SUBJECT, not a distinct graph or document
|
||||
|
||||
The store document gains, beside its `ldp:contains` list, the read cap of each document it lists — the emulation of `AddRepo { read_cap }` on the Store branch.
|
||||
|
||||
Three candidate shapes were considered:
|
||||
|
||||
- **A distinct named graph** (`GRAPH <…:b:store>`) — **rejected**. No branch would exist behind it; the content would be committed on the anchor's Main branch while claiming to live elsewhere. It misrepresents the structure, and its sync behaviour against a real broker is unverified (see above).
|
||||
- **A separate document per branch** — structurally closest (a document is what the JS SDK gives us that most resembles a branch: own topic, own sync, independently addressable), but it doubles the documents per store and adds an indirection to resolve them, to imitate a second pub/sub flow the polyfill will not use.
|
||||
- **A distinct subject in the same document** — **chosen**. It buys what actually matters: the key stored *next to* the document, separate from the list, read rather than recomputed. It does not buy a second event flow, which the polyfill cannot reproduce anyway.
|
||||
|
||||
*The honest cost of this choice*: our two "branches" share one commit stream and one topic, where NextGraph has two. Anything that comes to depend on them being separately subscribable will have to move to the separate-document shape.
|
||||
|
||||
### D3 — Deriving becomes minting, and `CapRegistry` stops being a keyring
|
||||
|
||||
Today `fileOwnCaps` **re-derives** each cap from its NURI, which only works because the emulated key is a function of the NURI. After D2 the cap is **read from the store document**. Derivation survives only inside `nuri.ts` as how a stand-in value is *minted at creation* — the single function P1b replaces with a real key.
|
||||
|
||||
The in-memory `CapRegistry` then stops being "the keyring" and becomes what it actually mirrors: **the verifier's local user storage** (fact table, last row) — the per-user cache of every opened repo and its read cap.
|
||||
|
||||
### D4 — Received caps: persist as local user storage, not as a document
|
||||
|
||||
Verified: there is no received-caps register upstream, and inventing one would expose a shape the target does not have. What upstream does is persist the `read_cap` of every **opened** repo in local user storage.
|
||||
|
||||
So the emulation is a **local, per-virtual-user store** — the same nature as `shared-wallet/virtualUsers.ts`'s existing `IdentityStore` (localStorage). This ends "re-read the inbox every session to recover caps", which the PO identified as the wrong model: an inbox is a queue you consume, not a store you re-read.
|
||||
|
||||
*Open*: whether to do D4 in this lot or after the boundary lot. It is the piece with the most design risk, and it is not needed for D1–D3 to be correct.
|
||||
|
||||
## Plan
|
||||
|
||||
1. **D1 vocabulary**, mechanically and in one pass — code, tests, docs. Nothing behavioural. Doing it first stops every later diff from being written in two vocabularies.
|
||||
2. **D2 + D3**: the store document carries each listed document's cap; `fileOwnCaps` reads it instead of re-deriving; `mintCap` keeps minting at creation only. Round-trip test: create → drop all in-memory state → re-list → the cap comes back **read, not recomputed** (assert by minting a *different* stand-in value in the test and checking the stored one wins).
|
||||
3. **D4** local per-user persistence of opened caps, replacing inbox re-reading.
|
||||
4. Then resume the boundary lot's steps 3–4 (guard at the four passage points; remove the cross-account fan-out), which are written in the new vocabulary.
|
||||
|
||||
## What this breaks
|
||||
|
||||
`storeRegistry`'s exported names change (`scopeIndexDoc`, `listEntityDocs`, `VirtualUserRecord` fields). `shim:contains` becomes `ldp:contains`, so **existing dev wallets stop resolving their documents** — acceptable for dev data, and consistent with how the pointer/doc-shim migration was handled before, but it must be stated rather than discovered.
|
||||
|
||||
## Risks I want challenged
|
||||
|
||||
- D2's "distinct subject" may be too weak a reading of "stay close to NextGraph" — the separate-document shape is defensible and I may be under-weighting it.
|
||||
- D3 assumes reading the stored cap is always possible where deriving was — i.e. that every path reaching `fileOwnCaps` has the store document at hand.
|
||||
- D4 introduces browser-local state to a library that currently keeps everything in the shared wallet; that may be a bigger departure than it looks.
|
||||
- The vocabulary change touches the boundary brief and the P1a brief, which are mid-flight.
|
||||
@@ -0,0 +1,199 @@
|
||||
# Brief — the virtual user boundary
|
||||
|
||||
**Status: specified 2026-07-30; all seven steps done** (four planned, three added as the work uncovered them). Sits alongside `2026-07-20-caps-emulation-alignment.md` (the wider caps chantier) and `2026-07-27-p1a-cap-surface.md` (the surface, implemented). This lot is about something more fundamental than either: **what a virtual user is allowed to reach.**
|
||||
|
||||
## Why this lot exists
|
||||
|
||||
A virtual user must **simulate the boundary of the future single-user wallet**. Today it does not: it is a grouping fiction — a shim account listing three index documents — and nothing enforces it. Every access function reaches any document of any identity, given a session id and a NURI.
|
||||
|
||||
Stated by the PO on 2026-07-30, on discovering the state:
|
||||
|
||||
> A virtual user must simulate the boundary of the future mono-user wallet. So the access functions must all be restricted to the virtual user currently "connected" (`setCurrentUser`). No cross-wallet access may be permitted, otherwise we are building on a fundamentally wrong model.
|
||||
|
||||
This is the same failure mode the whole caps chantier exists to prevent, one level down. P1a fixed the *shape* of reading (possession, not an ACL). It left the *reach* unbounded — and a consumer coded against an unbounded reach is coded against a world that will never exist, exactly like one coded against an ACL.
|
||||
|
||||
## The rule
|
||||
|
||||
> **The only reads/writes not confined to a virtual user are those that make multi-wallet operation possible at all** (e.g. the index of virtual users). — PO, 2026-07-30
|
||||
|
||||
And its sharpened form, which decides the hard cases:
|
||||
|
||||
> **Nothing common — only indexing mechanisms to make the virtual users work.** — PO, 2026-07-30
|
||||
|
||||
So an exemption must be *plumbing*, never *pooled user data*. The test: **does removing it stop the virtual users from functioning, or does it merely stop users from seeing each other's content?** Only the first justifies living outside a wallet. The shim passes (remove it and no wallet is resolvable); a shared index of user announcements does not (remove it and every wallet still works — you simply have to be given links).
|
||||
|
||||
Everything else is confined. The exemption list is short, explicitly named, and each entry has to justify itself against those two sentences — an exemption that merely *helps* is not an exemption.
|
||||
|
||||
## The premise that collapsed: there is no discovery
|
||||
|
||||
Recorded here because it removes a whole module rather than guarding it (PO, 2026-07-30 — see [`../readcap-and-nuri-model.md`](../readcap-and-nuri-model.md) §4ter-bis, where the principle is documented in full):
|
||||
|
||||
> **You cannot discover. You can only follow links.** NextGraph is local-first: publishing is *place the data in your public store* **and** *circulate the link* — into inboxes, or into somewhere already reachable by the people concerned. It is seen only by those who received the link. Private distribution is the same act plus the ReadCap.
|
||||
|
||||
`discovery.ts` therefore fails on **both** counts: it emulates a global-list capability the target will never have, and it is pooled user data across wallets. It is not a boundary to guard, it is a module to remove — with `watchShape('public')`'s discovery fold, `INDEX_ACCOUNT`, and the `submitToIndex` guard along with it.
|
||||
|
||||
What replaces it is not a mechanism but the model itself: a link reaches you through an **inbox**, or through a document you already hold. Which makes the inbox the bootstrap of the entire reachability graph — the reason its guard (below) and its automatic processing matter more than they first appear.
|
||||
|
||||
*Consequence for P1a's acceptance test, resolved*: `test/watch-shape.test.ts` (e) proved "a harvested bare reference reads nothing, the repo link reads the document" **on the discovery fold**. The property is independent of discovery and survives — `test/cross-user-access.test.ts` already proves it on the model's own terms (Bob follows a reference found in a document he holds), so (e) was dropped rather than re-based.
|
||||
|
||||
## The good news: the boundary already exists
|
||||
|
||||
**The keyring is the boundary.** A document is legitimately reachable when `capFor(doc)` answers — either because this wallet created it (its scope index refiles the cap, the emulated `AddRepo { read_cap }`) or because someone delivered the cap to it. No new notion is needed; the guard is written. What is missing is applying it.
|
||||
|
||||
And the surface to guard is small. Everything in the library reaches NextGraph through **four functions in two modules**:
|
||||
|
||||
- `docs.docCreate`, `docs.sparqlUpdate`, `docs.sparqlQuery`
|
||||
- `subscribe`'s `ng.doc_subscribe`
|
||||
|
||||
Nothing else touches `ng`. (`open-repo` only tests whether `doc_subscribe` exists; `ng-proxy` is the app-facing proxy.)
|
||||
|
||||
## What is confined, and what is exempt
|
||||
|
||||
**Exempt — each one passes the rule:**
|
||||
|
||||
| Exemption | Why it makes multi-wallet operation possible |
|
||||
|---|---|
|
||||
| The store-root **pointer** + the **doc-shim**, to resolve THE CURRENT account | This is the index of virtual users. Without it no virtual user is resolvable at all. **Resolution only** — enumerating every account is not covered (see below). |
|
||||
| The **reserved accounts** (the inbox anchor; `@index` is gone with `discovery.ts`) | They host infrastructure documents; they are not anybody's wallet. |
|
||||
| **Depositing** into another wallet's inbox (write-only) | Without a cross-wallet write channel there is no sharing, hence no useful multi-wallet — and it carries no pooled data: a deposit is addressed to one wallet, not shared between them. This IS the NextGraph model: an inbox deposit is anonymous and sealed, and grants the depositor nothing in return. |
|
||||
|
||||
~~Reading a discovery index~~ — **withdrawn 2026-07-30**, on both counts: it emulates a capability that does not exist, and it is pooled user data. See *The premise that collapsed* above.
|
||||
|
||||
**Confined — none of these passes the rule:**
|
||||
|
||||
| Path | Today | Becomes |
|
||||
|---|---|---|
|
||||
| `docs.sparqlQuery` / `sparqlUpdate` (**exported from the SDK entry**) | any document, any wallet | guarded on the anchor: the cap must be held |
|
||||
| `inbox.read` / `readSynced` / `watch` | **any inbox, including someone else's** | only inboxes belonging to the current wallet |
|
||||
| `subscribeDoc` | any document | only documents whose cap is held |
|
||||
| `storeRegistry.listEntityDocs` / `resolveReadGraphs` | fan-out over every account | **removed** — cross-wallet enumeration, and its former justification (feeding discovery) is gone too |
|
||||
| `storeRegistry.allAccounts` / `loadShim` | enumerates every virtual user | **removed**, or reduced to the reserved-account resolution that infrastructure needs |
|
||||
| `storeRegistry.ensureAccount(id)` | any id | the current identity, plus the reserved accounts |
|
||||
| `readUnion` | ✅ already guarded (P1a) | unchanged |
|
||||
|
||||
## The breach P1a opened, and which this lot must close first
|
||||
|
||||
`inbox.read` has no guard, and since P1a it **absorbs caps into the reader's keyring**. So:
|
||||
|
||||
```ts
|
||||
setCurrentUser("mallory");
|
||||
await inbox.read(bobsInbox); // mallory pockets the caps addressed to Bob
|
||||
```
|
||||
|
||||
Directed sharing is therefore defeatable by anyone who knows an inbox NURI. Strictly speaking this is not a regression — the inbox was never guarded — but before P1a it carried nothing that granted access, and now it does. **This is the first thing to fix**, and it is arguably P1a's own debt rather than this lot's.
|
||||
|
||||
Closing it needs a notion that does not exist yet: **"my inbox"**. Today an inbox is an arbitrary NURI supplied by the caller. Which is the same brick as the PO's other instruction, so they should land together:
|
||||
|
||||
> Processing inboxes is the polyfill's job, not the app's — as soon as the app connects a user/wallet, at **two levels**: the wallet inbox (where ReadCaps arrive) and the inbox of **every document the user owns**.
|
||||
|
||||
## Design notes for the implementation
|
||||
|
||||
**Scaffolding in the keyring, not in the exemption list.** The current account's three scope-index documents belong to its wallet, so they should be *in its keyring* rather than exempted. That keeps the exemption list down to what genuinely serves multi-wallet operation (the shim, the reserved accounts). Only the pointer and the doc-shim stay outside.
|
||||
|
||||
**Exemptions are named, never inferred.** A NURI is exempt because it is *the* shim document or *a* reserved account's document, resolved as such — never because it "looks like infrastructure". An inferred exemption is a hole.
|
||||
|
||||
**Write-only really means write-only.** Depositing into another wallet's inbox must not make that inbox readable, subscribable, or listable as a side effect. This is the one asymmetric permission in the model and it needs its own test.
|
||||
|
||||
**The guard belongs to a function, not to a position.** One named predicate ("may the current wallet reach this document?"), called at each of the four passage points — not four inline checks that drift apart.
|
||||
|
||||
## Hardening is the polyfill's responsibility, not a negotiation with the consumer
|
||||
|
||||
Stated by the PO on 2026-07-30, closing the question "what does the app actually use?":
|
||||
|
||||
> We do not need to know what the app uses: the polyfill must harden **everything it exposes**. That is its responsibility. **Nothing may allow its own mechanisms to be bypassed** — the virtual user in particular.
|
||||
|
||||
This settles how the lot proceeds, and it generalizes past it. A surface that lets a caller go around the wallet boundary does not merely risk misuse: it **teaches a model that will not exist**, which is the one thing this library exists to prevent. So an exposed function that can bypass a mechanism the polyfill provides is a defect *whether or not anyone calls it that way*, and "the consumer might depend on it" is not an argument for keeping it — if the consumer depends on it, the consumer depends on something the target will refuse.
|
||||
|
||||
Applies to every exported surface, including ones added later: **if it is exposed, it is guarded**.
|
||||
|
||||
## What this breaks
|
||||
|
||||
`docs.*` is exported from the SDK-identical entry and can reach any document; the cross-account fan-out enumerates every wallet; `discovery.*` disappears entirely. The consumer will have to change where it relied on any of them. That is the point, not a side effect: each one is the API starting to tell the truth about a boundary that will exist. Update `../migration-guide.md` accordingly.
|
||||
|
||||
## Order of work
|
||||
|
||||
1. ~~**Remove `discovery.***~~ — **DONE 2026-07-30.** `src/discovery.ts` and `test/discovery.test.ts` deleted; `INDEX_ACCOUNT`, `watchShape`'s public-scope fold and its discovery-index container subscription, `nurisFromRef`, the `submitToIndex` guard, and the e2e discovery block all removed. P1a's acceptance test did not need re-basing: `test/cross-user-access.test.ts` already proves the same property (a bare reference reads nothing, the link reads the document) on the model's own terms — following a link — so `watch-shape.test.ts` (e), which proved it on the discovery fold, was dropped. Docs realigned: the ADR is marked superseded, `read-model.md` now describes ONE regime (follow, never enumerate), and the root README's capability row records the removal.
|
||||
2. ~~**"My inbox" + the inbox read guard**~~ — **DONE 2026-07-30.** `storeRegistry.userInbox(id)` gives every virtual user its own inbox document, created on first sight and recorded in the doc-shim under its own predicate (`shim:docInbox`), read by its OWN query so an account record written before this existed still resolves — the fixed account SELECT did not grow a fourth required field. `isOwnInbox(nuri)` is the predicate; `inbox.read` / `readSynced` (hence `watch`, which reads through it) refuse an inbox that is not the connected wallet's, and refuse outright when no identity is set. **Depositing stays open** — `post` / `shareCap` are untouched, because that is the one legitimate cross-wallet act. The shared `resolveInboxAnchor` (a reserved account's document, an inbox COMMON to every wallet) was removed: it was unused by the library and violated *nothing common*. Locked by `test/isolation-active.test.ts` *an inbox may be DEPOSITED into by anyone, and READ only by its owner*, which walks the exact breach — Alice deposits, cannot read back; Mallory knowing the NURI absorbs nothing; anonymous is refused; Bob reads his own and only then does the cap land.
|
||||
|
||||
*Not done, and deliberately*: per-DOCUMENT inboxes. ~~Upstream every document has one~~ — **false, corrected 2026-08-03**: no document has an inbox upstream, and neither does the private store (see step 7's correction). Here only the wallet does. **The PO has ruled they must come** (2026-07-30) — *"it can come in a second step, but it must come"* — so this is a commitment, not an option. The guard predicate (`isOwnInbox`) is where they plug in: it answers "is this inbox mine?", which extends to "…one of my documents' inboxes" without changing a single caller.
|
||||
|
||||
### Two defects this step surfaced — the first still open, the second closed by steps 5–6
|
||||
|
||||
**`userInbox(id)` is a directory, and directories do not exist.** It resolves ANY wallet's inbox from its identity id, and it is exported (`storeRegistry.*` is re-exported from the SDK entry). But you cannot look someone up in NextGraph — you cannot discover, you can only follow links. Their inbox NURI reaches you because *they gave it to you*, not because you resolved it from a name. Resolving **my own** inbox is legitimate plumbing; resolving **anyone's** is the same shape as the discovery index just removed. Fix: the public surface becomes "my inbox" (no argument), and reaching someone else's requires a NURI you were given. Resolution-by-id stays internal, for the shim and the tests.
|
||||
|
||||
**The keyring is not stored anywhere, and the shape is wrong — fix it now, not at P1b.** It is an in-memory `Map<accountKey, Map<Nuri, ReadCap>>`, rebuilt from scratch each session. Nothing persists a cap *as a cap*. PO directive, 2026-07-30:
|
||||
|
||||
> If NextGraph stores the key next to the document, then that is what we do. Without encryption we simply store a stand-in value. Stay as close as possible to how NextGraph works.
|
||||
|
||||
So this is not a P1b concern, it is a **shape** concern — the one thing this library exists to get right — and the stand-in key is stored exactly where the real one will be. Two storage sites, mirroring upstream:
|
||||
|
||||
- **My own documents** → the cap goes **beside the NURI in the scope container**, which is the emulation of `AddRepo { read_cap }` on a branch of the store. Today the container stores only `shim:contains <nuri>` and the cap is **re-derived** from that NURI; it gains a `shim:readCap` beside it. Deriving then stops being how a cap is *recovered* and becomes merely how the stand-in value is *minted* — the single function P1b replaces.
|
||||
- **Caps I received** → into the emulation of `AddLink { read_cap }` on the **User branch** of the private store. Verified 2026-07-30 (see [`../readcap-and-nuri-model.md`](../readcap-and-nuri-model.md) §4quinquies): that register exists, it is explicitly for **external repos**, and its stated purpose is to *"share with all its device a new Link they received"* — wallet-resident and cross-device. So a received cap belongs **inside the virtual user**, like everything else. *(Two earlier versions of this note were wrong and are recorded in [`2026-07-30-users-stores-branches.md`](2026-07-30-users-stores-branches.md): the first blamed key derivation and proposed a "keyring document"; the second concluded no register existed at all and proposed browser-local storage — which would have put library data OUTSIDE even the physical user. Both were refuted; `AddLink` is the answer.)*
|
||||
3. ~~**The guard at the four passage points**~~ — **DONE 2026-07-30.** `src/emulated-verifier/reach.ts` holds the boundary as **two rules on one criterion — possession — implemented in two places** (PO directive):
|
||||
|
||||
- **Rule 1, authorization**, at the passage points (`assertMayReach`, called from `docs.sparqlQuery` / `sparqlUpdate`): nothing reaches `ng` unless the connected user possesses the document's cap.
|
||||
- **Rule 2, do not even attempt**, at the callers (`mustNotAttempt`, applied in `read-model.readUnion`, which now filters BEFORE opening or reading): a reader that holds no cap does not issue the operation at all. Upstream you cannot even address a repo you have no cap for, so asking about one is not "a read that will be refused" — it is a read with no meaning.
|
||||
|
||||
The redundancy is the point, and a test pins it: a caller that forgets rule 2 is still refused by rule 1, so a bookkeeping lapse fails loudly instead of succeeding quietly.
|
||||
|
||||
**Possession decides, never the shape of the reference in hand.** A caller legitimately manipulates a bare NURI while holding its cap elsewhere — references travel bare through content and indexes, the cap sits in what the user holds. `targetOf` first, so both forms answer alike. (An earlier reading of the directive checked the string for `:r:` instead; corrected on the PO's clarification.)
|
||||
|
||||
Exemptions are **declared**, never inferred from a NURI's shape (`declareInfrastructure`, called by the store-registry for the store-root pointer and the doc-shim — the index of virtual users, the only thing that passes the "remove it and no user resolves at all" test). A user also reaches its own three stores and its own inbox, or the boundary would lock it out of itself.
|
||||
|
||||
Not done: `subscribeDoc` is not yet guarded — it interacts with `ensureRepoOpen`, which opens documents before their cap is known on some cold-start paths. Left for step 4 with the barrier tests in view.
|
||||
4. ~~**Remove the cross-account fan-out**~~ — **DONE 2026-07-30.** `listEntityDocs`, `resolveReadGraphs`, `allAccounts`, `loadShim` and the full-shim cache are gone. Nothing in the library used them any more once `discovery` was removed; only their own tests did. `subscribeDoc` is now guarded too (rule 1) — a subscription IS an access, since the push carries the document's state, so leaving it open would have been a door beside the gate.
|
||||
|
||||
### Machinery vs virtual user: two APIs, and only one is the app's
|
||||
|
||||
The PO's framing, which replaced the exemption list entirely:
|
||||
|
||||
> Clearly distinguish what is polyfill machinery (and therefore the PHYSICAL user) from what is a virtual user's operation. Use different functions, probably grouped in different namespaces — because one API is exposed to the app and the other must never be.
|
||||
|
||||
`src/shared-wallet/physical.ts` now holds `physicalCreate` / `physicalQuery` / `physicalUpdate`, with `ensurePhysicalRepoOpen` and `subscribePhysicalDoc` as their open/subscribe counterparts. They are unguarded, and **never exported from the package** — a test asserts it, because a regression there is silent and total.
|
||||
|
||||
The dividing line:
|
||||
|
||||
> Does this operate on the **index of virtual users** (the shim), or on the **content of one virtual user**? The first is machinery; everything else is the user's, and is confined.
|
||||
|
||||
So the store-root pointer, the doc-shim and the account records go through the machinery; a virtual user's stores, its inbox and its documents go through the guarded `docs.*`, even though the library is what calls them on the user's behalf.
|
||||
|
||||
**This is strictly stronger than the exemption list it replaces.** `declareInfrastructure` is deleted. The machinery no longer calls the guarded primitive and gets waved through — it calls a different primitive that was never guarded. There is no list to widen, to get wrong, or to infer from a NURI's shape, and the boundary now has no `if` in it that could be talked into saying yes.
|
||||
|
||||
5. ~~**The Link, and inbox processing on connection**~~ — **DONE 2026-07-30**, after the four steps above.
|
||||
|
||||
**The Link.** Giving access is a `Link` deposited into the recipient's inbox — upstream's word at all three stages (`InboxMsgContent::Link` for the message, `AddLink { read_cap }` for the filing, `RemoveLink` for the withdrawal). `shareCap` deposits one; the deposit kind is `…:inbox:link`.
|
||||
|
||||
**Applying it durably.** `storeRegistry.addLink` / `readLinks` emulate `AddLink` on the **User branch of the private store** — a distinct subject (`shim:userBranch`) in the private store document, kept separate from the `ldp:contains` listing exactly as upstream keeps the User branch separate from Main. Idempotent, so re-processing costs nothing.
|
||||
|
||||
**The split that matters**: `inbox.read` KEEPS a Link (in the session's keyring) but does not FILE it — reading a queue must not write to a user's store. `inbox.processInbox` *applies*: it reads, then files. That is what an inbox is upstream — **a queue you consume, not a store you re-read**.
|
||||
|
||||
**On connection.** `setCurrentUser` fires `connect.connectedUser()`: restore the already-applied Links from the User branch, then drain the inbox. Restore-first means a reconnecting user reads its shared documents immediately, without waiting on the queue. Fire-and-forget, because the setter is synchronous and every consumer calls it from synchronous code — the work announces itself through `CapRegistry.onChange`, which `watchShape` already listens to. `connectedUser()` is exported for a caller that needs to await it.
|
||||
|
||||
**Two things it deliberately does NOT do.** It does not **provision**: connecting an identity that does not exist creates nothing (`resolveAccount`, not `ensureAccount`) — otherwise connecting would mint a user's stores and caps as a background side effect, arming the whole emulation at a moment nothing controls. And it does not drain **per-document** inboxes, which do not exist yet.
|
||||
|
||||
Proven by `test/cross-user-access.test.ts`: a cap shared to Bob survives **with his inbox emptied** and every in-memory cap dropped — restored from the User branch, not from the queue.
|
||||
|
||||
*Cost noted*: `setCurrentUser` now has observable asynchronous effects (it reads, and it logs). Three log-assertion tests had to await `connectedUser()` before counting lines. That is the honest price of moving the obligation off the app, and it is worth naming rather than discovering.
|
||||
|
||||
6. ~~**The Store branch**~~ — **DONE 2026-08-03.** A document's cap is now STORED when it is created — `shim:readCap` on a `storeBranch` subject of the store document, the emulated `AddRepo { read_cap }` — and READ back by `listMyEntityDocs`, never recomputed. That closes the asymmetry left by the Link work, where received caps were filed durably while created ones were re-minted.
|
||||
|
||||
Two things this pinned down, both of which would have cost more later:
|
||||
|
||||
- **The listing and the keys stay separate**, as Main and Store branches are upstream: `contains` on one subject, `readCap` on another, written as two statements because upstream they are two commits.
|
||||
- **Creation mints the cap exactly once.** It used to mint twice — once to write, once to hold — which agreed only because the stand-in value is a constant. With P1b's real key those would be two different keys, and a creator would hold one that does not open its own document. A test pins it, and another proves the cap is read rather than recomputed by corrupting the stored value and checking the corruption wins.
|
||||
|
||||
Honest about the emulation: upstream the Store branch carries **no triples at all** (`BranchCrdt::None`). Representing it as RDF is ours; what is faithful is the storage beside the document and the separation from the listing.
|
||||
|
||||
7. ~~**Per-document inboxes**~~ — **DONE 2026-08-03.** Upstream a repo carries `inbox: Option<PrivKey>` (`engine/repo/src/repo.rs:126`): an inbox is a keypair on the document whose PRIVATE half the owner holds, recorded with `AddInboxCap { repo_id, overlay, priv_key }` on the **User branch** — the same branch as `AddLink`, and with the same stated purpose (*"so that a user can share with all its device"*). So "which inboxes may I read" has exactly one answer, and it is the one place to look.
|
||||
|
||||
*(Renamed and split on 2026-08-03 — `documentInbox` became `openDocumentInbox` (own the inbox) + `documentInboxAddress` (find where to deposit). Conflating the two made per-document inboxes unusable by anyone but their owner; see [`2026-08-03-document-inbox-addressing.md`](2026-08-03-document-inbox-addressing.md).)*
|
||||
|
||||
`storeRegistry.openDocumentInbox(doc)` resolves — creating on first ask — the inbox of a document this user owns, recording the pair on its User branch. **Lazy**: minting an inbox document for every entity up front would double every `createEntityDoc` for inboxes most documents never receive anything in. `myInboxes()` enumerates both levels, `isOwnInbox` answers from the same record, and `connect.connectedUser` drains them all in one call.
|
||||
|
||||
The asymmetry holds at both levels, and a test walks it: **anyone deposits** into a document's inbox (that is how a third party reaches its owner at all), **only the owner reads** it.
|
||||
|
||||
**Correction 2026-08-03, twice.** *First:* the paragraph above overstated the upstream fact — an adversarial doc review caught it. *Then the correction itself overshot*, calling the step an ANTICIPATION: the engine **supports** an inbox on any repo (`inbox` is a field of every `Repo`, `AddInboxCapV0` is keyed by `repo_id`, and `update_inbox_cap_v0` applies it with no `is_store` check — `engine/verifier/src/verifier.rs:1920`). What no code path does is CREATE one for a document. Verified: `new_store_default` attaches an inbox only `if !private` (`engine/verifier/src/verifier.rs:2994`), and `doc_create` goes through `new_repo_default`, which leaves `inbox: None` (`engine/repo/src/repo.rs:574`). The **only** two `AddInboxCap` commits in the engine are for the public and protected STORE repos (`engine/verifier/src/site.rs:128,149`). So today **no document is GIVEN an inbox, and neither is the private store** — which says nothing about what may have one. The step stands as delivered, and it is aligned on the engine's model rather than betting past it.
|
||||
|
||||
## Relation to P1b
|
||||
|
||||
P1b (per-document encryption, closing the read paths that bypass the guard) largely **becomes** this lot, better framed. Encrypting each document while leaving the wallet boundary open would be securing the windows with the door open — and conversely, once every access is confined to the connected wallet, "the emulated key is derivable" stops being the load-bearing weakness. This lot should therefore precede P1b, or absorb it.
|
||||
@@ -0,0 +1,64 @@
|
||||
# Brief — a document's inbox has to be addressable by anyone holding the document
|
||||
|
||||
**Raised 2026-08-03, from the consumer side (Festipod), after an attempt to solve it in the app proved it does not belong there.**
|
||||
|
||||
> ## IMPLEMENTED 2026-08-03 — shape 2 (the library publishes), with the cost objection taken as binding
|
||||
>
|
||||
> `storeRegistry.documentInboxAddress(doc)` answers *"where do I deposit for this document"* for **any holder**, and `inbox.post` into it. The address is published **at creation**, in a compartment the library owns — so it never enters a consumer shape.
|
||||
>
|
||||
> **On the cost — and the wrong answer that was tried first.** The measured regression (9m37 → 21m30) came from creating a second **DOCUMENT** per document. The first fix pointed every document's published address at the owner's **own** inbox: no second document, cost amortized. **It was reverted the same day**, because it emulates a relation upstream cannot express — the verifier routes an incoming message by `inboxes: PubKey → RepoId` and unseals it with THAT repo's private half (`engine/verifier/src/verifier.rs:1677,1928`), and `InboxMsgBody` carries no target document (`engine/net/src/types.rs:4265`) because the address already identifies it. Many documents behind one inbox would have forced consumers to tag deposits with their document — a habit to unlearn at migration, which is precisely what this library exists to prevent.
|
||||
>
|
||||
> **The cost, actually answered:** only documents meant to RECEIVE open an inbox, and their owner is who knows. `createEntityDoc` publishes nothing; an app calls `openDocumentInbox(doc)` for the documents that need one (in the consumer's case: events, not every entity). Cost becomes proportional to the need, with the shape intact.
|
||||
>
|
||||
> Shape 1 of this brief (derivation) was **not available**: our inbox is a document, and a derived NURI would name a repo `doc_create` never created — upstream can derive because an inbox there is a keypair on the repo, not a document.
|
||||
>
|
||||
> **`inbox.postToDocument(doc, { payload })`** is the one call an app makes: it names the DOCUMENT, never an inbox, and **throws** when the document has no inbox rather than returning quietly — a deposit that vanishes without an error is the bug this whole path exists to close. There is deliberately **no target-document field on a deposit**, for the reason above.
|
||||
>
|
||||
> **Where the address lives.** On the document's emulated **Header branch** (`urn:ng-eventually:shim:headerBranch`), beside the content rather than in it — the same subject-as-compartment shape already used for the Store and User branches. `read-model` now drops every subject under the reserved `urn:ng-eventually:` namespace (`src/emulated-verifier/machinery.ts`), so the address cannot surface as one of the entity's properties. That filter is by SUBJECT, so it covers every emulated compartment present and future.
|
||||
>
|
||||
> **The open question, answered.** *"Is 'a document has an inbox addressable by any holder' upstream, or this library's invention?"* — **upstream, as a capability**; ours only as a JS surface. The engine lets any repo have an inbox: `inbox: Option<PrivKey>` is a field of every `Repo` (`engine/repo/src/repo.rs:126`), `AddInboxCapV0` is keyed by `repo_id` (`engine/repo/src/types.rs:1973`), and `update_inbox_cap_v0` applies it with **no `is_store` check** (`engine/verifier/src/verifier.rs:1920`), at any time (User-branch commit, `commit.rs:1043-1050`, whose type documents the update case). What no code path does is CREATE one for a document: `new_store_default` attaches one only `if !private` (`verifier.rs:2994`), `doc_create` leaves `inbox: None` (`repo.rs:574`), and the engine's only two `AddInboxCap` commits are for the public and protected STORE repos (`site.rs:128,149`). "Does not" is not "cannot" — an earlier version of this note called the feature an anticipation on exactly that confusion. The half-split is upstream's too — a depositor seals with the inbox PUBLIC key (`engine/net/src/types.rs:4299`) and only the owner holds the private half — which is why an address is public by nature and belongs on the document, not on the owner's User branch.
|
||||
>
|
||||
> **Also fixed, and it was the root of the reported symptom.** `openDocumentInbox` (formerly `documentInbox`) called by a non-owner used to mint a parallel inbox and record it for the caller — no error, deposits lost. It now refuses, on OWNERSHIP (read from the Store branches), not on cap possession: a cap can be received, and a recipient must not be able to redirect the owner's deposits to itself.
|
||||
|
||||
## The problem, in one sentence
|
||||
|
||||
`documentInbox(doc)` answers *"which inbox do **I** know for this document?"* — and mints a fresh one when the answer is none. So a third party never reaches the owner's inbox: they get one of their own, which the owner never reads, and their deposit vanishes without an error.
|
||||
|
||||
## Why that breaks the consumer
|
||||
|
||||
Festipod's central act is signing up to **someone else's** event. The participant deposits into the event's inbox; the owner drains it at their next connection and materializes the count. With addressing scoped to the caller, only the owner can deposit into their own event — every other sign-up is silently lost.
|
||||
|
||||
The same wall stands in front of the directory document the app needs to rebuild discovery: creators must deposit a reference into a document they do not own.
|
||||
|
||||
## What was tried in the app, and why it was wrong
|
||||
|
||||
The consumer published the address on the document itself: resolve `documentInbox(eventDoc)` once at creation, write the NURI into the public event, and have participants read it from there instead of deriving it.
|
||||
|
||||
It works. It is still the wrong place, for three reasons — and the third is the one that settles it.
|
||||
|
||||
- **It puts infrastructure in the domain.** The `Event` shape starts carrying a technical address, and the domain model encodes a temporary state of the library.
|
||||
- **It costs.** `documentInbox` *creates a document*. Publishing the address at creation takes every event creation from one document to two — and document creation is a round-trip that does not overlap. Measured on the test suite: the `@data` run went from **9m37 to 21m30**, with sign-up scenarios timing out on their setup step (4 failures out of 7 on a **fresh** profile, so not test-wallet bloat). That cost belongs to whoever can amortize or defer it. The app can do neither, because it does not own the mechanism.
|
||||
- **The library already claims this job.** The commit that introduced per-document inboxes says: *"Inboxes belong to someone — the user's own, plus one per document — and connecting a user drains them all; that is the library's job, not the app's."* Draining was taken as the library's job. Addressing was left to the caller. Those two halves belong together.
|
||||
|
||||
The consumer's own doctrine says the same thing from the other side: when something does not work, the question is never how to work around it in the app, but what the library has to compensate. The app-side change has been reverted.
|
||||
|
||||
## What is being asked
|
||||
|
||||
**Given a document, any holder of that document should be able to name the inbox its owner reads** — without owning it, and without being handed the address out of band.
|
||||
|
||||
How is the library's call. Two shapes come to mind, neither prescriptive:
|
||||
|
||||
- Make the address **derivable** from the document, so `documentInbox(doc)` returns the same NURI for everyone, and only the owner can *read* it — the read guard already enforces that, and it is where the asymmetry belongs.
|
||||
- Or have the library **publish** the address itself, at document creation, somewhere it controls — so it stays out of the consumer's shapes and the library keeps the freedom to make it lazy.
|
||||
|
||||
The second keeps the current create-time cost unless it is deferred; the first has none, and matches how the rest of the model works — an overlay is derived, a keyring is looked up, nothing is handed over out of band.
|
||||
|
||||
## Open question worth settling first
|
||||
|
||||
Is *"a document has an inbox addressable by any holder"* part of NextGraph's target model, or an invention of this library?
|
||||
|
||||
If it is upstream, this is emulation to align. If it is the library's own, it is a design decision to take deliberately — and the answer decides whether the note about it belongs in the shared NextGraph inbox as a gap, or here.
|
||||
|
||||
## Consumer state meanwhile
|
||||
|
||||
Sign-ups across identities do not converge, and the app does not pretend otherwise. Nothing in Festipod works around it.
|
||||
@@ -0,0 +1,76 @@
|
||||
# What a consumer's tests need from the contract, and cannot find in it
|
||||
|
||||
Raised by the first consumer (Festipod) on 2026-08-10, while migrating onto `@ng-eventually/sdk` against `contract_sdk-surface` @ `30f6263`. Three findings.
|
||||
|
||||
## 1. The contract does not say how an identity comes to be established
|
||||
|
||||
The first version of this brief asked for a test entry exposing identity switching, on the strength of the API contract's remark that *"the e2e harness plays several identities on one page and reaches it by its internal path, which is what a harness is allowed to do and an application is not"* — true of this library's own harness, and unreachable for a consumer's, since `packages/sdk/package.json` maps exactly one entry and the resolver refuses a deep import (verified: `Cannot find module '@ng-eventually/sdk/src/shared-wallet/access-gate'`).
|
||||
|
||||
**That request is withdrawn**, and the reason is worth recording because it is the library's own argument turned around. The consumer decided that its tests take no shortcut through the SDK and validate the application's behaviour rather than the SDK's. Under that rule, "two identities on one page" is not a capability to restore: it is not something a user does, it exists only because one wallet hosts several identities, and a test that used it would be testing the emulation. Multi-user behaviour gets tested the way it is lived — several browser contexts, each signing in as itself. So the surface is right as it stands, and the library should not add a testing entry on this consumer's account.
|
||||
|
||||
**A larger claim was drafted here and is retracted before it could mislead.** It said the contract offers no way to determine which identity comes up, and that a consumer therefore has no reproducible test isolation. That is wrong: `EventuallyConfig` publishes both `sharedWallet` and `currentUser`, so bootstrap is exactly where a caller says which wallet to open and, when it must, which identity to come up as. The consumer had simply not wired those two fields yet — its own migration was incomplete, and the library's error message said so precisely (*"no shared wallet configured. Pass `sharedWallet` to `configure()`"*). A good error message did the work the brief was trying to do.
|
||||
|
||||
What remains is small and is prose, not surface. `## Guarantees` describes `ensureIdentity()` as *"the whole of signing in… it resolves who you are"* without ever connecting that sentence to the two `EventuallyConfig` fields that determine the answer. The `## Surface` block carries them as bare lines in a config interface, where nothing marks them as the inputs to the one call a consumer must get right before anything renders. Naming that link — *these fields are what `ensureIdentity()` resolves from* — would have saved a wrong diagnosis here, and it is one sentence.
|
||||
|
||||
## 2. `watchShape`'s published signature contradicts its own types
|
||||
|
||||
`## Surface` publishes:
|
||||
|
||||
```ts
|
||||
export function watchShape(query: ShapeQuery): ShapeObservable;
|
||||
```
|
||||
|
||||
`ShapeQuery` is the **result** type (`{ data, isPending, isSuccess, isError, error }`, per `docs/api-contract.md` § 5), so as written the call takes its own return value. The signature the consumer has always called, and the one § 5 documents, is `watchShape<T>(shapeType, scope)` — two positional arguments. One of the two documents is wrong; the contract is the one consumers read.
|
||||
|
||||
## 3. There is no synced read for the per-document form
|
||||
|
||||
The inbox surface publishes `readSynced(targetInbox)` and `readForDocument(doc)`, but not their intersection. The consumer's materialization path depends on the **synced** guarantee specifically (`read` and `readSynced` differ by contract), and it addresses by document. Today it must therefore resolve an address itself to get the synced form — which is the exact gesture § *Guarantees* says an application never performs (*"an application never handles a key or an inbox address"*).
|
||||
|
||||
Either `readForDocument` carries the synced guarantee, or a `readSyncedForDocument(doc)` completes the pair. As it stands the document-addressed path is strictly weaker than the address-addressed one, and the contract does not say that is intentional.
|
||||
|
||||
## 4. Identity was taken out of the application's hands, but three published calls still demand one
|
||||
|
||||
This is the finding that actually cost the migration, and it is one incoherence seen from two sides.
|
||||
|
||||
`ensureIdentity()` returns `void`, and nothing else answers *"who am I"* — `getCurrentUser` was removed on the sound argument that an application knows who it signed in. Under the previous surface that was true: the application named the identity, so it held the value. It no longer names it, and the gate that resolves it hands nothing back. So the premise the removal rested on has quietly stopped holding.
|
||||
|
||||
Meanwhile `storeRegistry.createEntityDoc(id, scope)`, `listMyEntityDocs(id, scope)` and `resolveWriteGraph(id, scope)` all take a mandatory `id: string`, and **the contract never says what it is**. Two readings were open. **The library has now answered, by refusing — and the answer is measured, not argued.**
|
||||
|
||||
The consumer bet on the harmless reading (`id` = a collection key inside the already-connected identity, which `listMy…` suggests) and routed all its call sites through one constant, because the other reading offered it no legal move at all. Running the broker-backed suite settles it in one line. Each scenario opens as its own identity — verified, the access log shows `test-…-2`, `-3`, `-4`, `-5`, `-6`, `-7` — and every one of them fails on **the same document**:
|
||||
|
||||
```
|
||||
[test-…-2][polyfill] createEntityDoc cap append failed:
|
||||
[ng-eventually] createEntityDoc:addRepo: refused — the connected user does not hold
|
||||
this document's cap. Naming a document does not grant access to it.
|
||||
"did:ng:o:TFYUlJQnOkYUlC4T9XtGOBoz70opW_IO21VJ_ouF_Y0A:v:…"
|
||||
```
|
||||
|
||||
The first identity creates that document and owns it; every later identity names the same one and is refused. So **`id` is per-identity**, and a constant collapses every user onto one owner's document.
|
||||
|
||||
Two things follow, and the second is the blocker.
|
||||
|
||||
**The good news, worth saying plainly: the guarantee held.** The failure mode feared here was a silent merge — every user's documents in one collection, no error, isolation quietly gone. That is not what happened. *"Writing is ownership"* refused loudly and named the reason, and a consumer's wrong guess became a red test instead of a data leak. This is the surface doing exactly what it promises.
|
||||
|
||||
**The blocker: the three calls require the connected identity, and no published call returns it.** `ensureIdentity()` resolves it and returns `void`; `getCurrentUser` was removed on the argument that an application knows who it signed in — which was true while the application named the identity and stopped being true the moment it no longer does. So the consumer must pass a value it has no way to obtain. It currently works only where a deployment plants one (its test environment, through `configure({ currentUser })`); a real deployment plants nothing, and there the application is stuck.
|
||||
|
||||
The pair has to close, either way round: the three calls stop taking an `id` (the session IS the identity — what the API contract already predicts for the target), or the surface answers *"who am I"* again. Right now it does neither, and this is no longer a documentation nicety — it is the one thing standing between a consumer and a working multi-user deployment.
|
||||
|
||||
## 6. The barrier is the library's, and nothing can test that a first-time device gets in
|
||||
|
||||
The consumer has now deleted its own access screen and relies on the barrier `ensureIdentity()` shows — which is right, and is what the library asked for when it absorbed ~300 lines of gate from this same application.
|
||||
|
||||
Its one end-to-end check of a first-time device — a real browser with an empty profile, offered the wallet file and its password, importing it, and coming back signed in — drove that deleted screen's own DOM, so it went with the screen. The consumer still needs that coverage: a first-time device getting in is the single most consequential path a real user takes, and it is currently covered by nothing.
|
||||
|
||||
**The consumer is not asking for testids, and is rebuilding the check on its own side.** An end-to-end test should interact the way a person does — visible text and roles — rather than reach for identifiers planted inside someone else's component, so driving your barrier that way needs nothing published and is the more honest test besides.
|
||||
|
||||
**One question, because it decides whether that is possible at all**: is the barrier reachable by ordinary browser automation? A screen rendered inside a **shadow root**, or in its own iframe, is invisible to a locator that searches the light DOM, and no amount of "test it like a user" gets past that. If it is isolated, then either the isolation needs a documented way through for automation, or the flow is yours to cover and the contract should say so plainly — because right now each side can reasonably assume the other has it.
|
||||
|
||||
**Unrelated signature seen in the same run, reported without diagnosis** (78 occurrences, none fatal — the scenarios fail on the cap refusal above, not on this): `call_sdk Deserialization error of config Error: invalid type: JsValue(Function), expected any valid JSON value`. It appears only once `sharedWallet` is configured and `ensureIdentity()` actually opens a wallet — it was absent from every earlier run. The consumer passes `sharedWallet` as three plain strings, per `## Surface`, so whatever crosses that boundary as a function does not come from its call site.
|
||||
|
||||
A second, smaller consequence of the same hole: the consumer's `currentUserId` now has to be read out of its own profile document, so it is empty until that read lands, where it used to be available synchronously and invariant. An action taken in that window is silently dropped instead of written.
|
||||
|
||||
## 5. "Permissive in" is stated as a guarantee but is not uniform
|
||||
|
||||
`## Guarantees` opens with *"Every entry accepts `NuriLike` and validates at the door"*, and makes a point of it: a value read from storage, a URL or a form goes straight in, no guard to call, no cast to write. The signature block does not honour it uniformly — `storeRegistry.openDocumentInbox(doc: Nuri)` takes the precise type where its own deposit-side counterpart `inbox.readForDocument(doc: NuriLike)` takes the permissive one. Verified by the consumer's typechecker, not read from your source.
|
||||
|
||||
Either the guarantee is narrower than stated (say which entries it covers), or `openDocumentInbox` should widen. As written, a consumer that trusts the sentence gets a type error at exactly one call site and has no way to tell whether that is the rule or the exception.
|
||||
@@ -1,8 +1,29 @@
|
||||
# ADR — Discovery mechanism (inbox-fed index, fan-out)
|
||||
|
||||
**Date:** 2026-06-16 · **Status:** mechanism accepted; target owner undecided.
|
||||
> ## SUPERSEDED — 2026-07-30. The premise does not hold.
|
||||
>
|
||||
> **There is no discovery in NextGraph. You cannot discover; you can only follow links** (PO, 2026-07-30 — the principle is documented in [`../readcap-and-nuri-model.md`](../readcap-and-nuri-model.md) §4ter-bis). Publishing is two acts: place the data in your public store, **and** circulate the link — into inboxes, or into somewhere already reachable by the people concerned. It is seen only by those who received the link. This is a foundation of local-first, not a gap to be filled.
|
||||
>
|
||||
> A global index therefore fails on **two independent counts**:
|
||||
>
|
||||
> 1. it emulates a capability the target will never have — teaching consumers a model that does not exist, which is the one failure mode this library exists to prevent;
|
||||
> 2. it is **data common to several users/wallets**, and nothing may be common — only indexing mechanisms that make the virtual users work (the shim qualifies; a shared index of user announcements does not).
|
||||
>
|
||||
> This ADR already recorded the first half of that verdict — *"a dedicated service with its own wallet sharing a freely-readable index is not a NextGraph shape"*, resting on a singleton-app path *"not implemented, uncertain"*. That reservation is now the conclusion.
|
||||
>
|
||||
> **Amended 2026-08-03 — the singleton-app half must be re-put, not cited as closed.** The NextGraph developer has since named the singleton app as *the* way an application holds data common to all its users: a document or store shared by all users, hardcoded in the app, write-owned by the developer and delegable — never delegated to all users, so user contributions arrive **through an inbox**. Still unimplemented, but no longer uncertain in direction. This does **not** reinstate discovery — the "you cannot discover, you can only follow links" verdict stands on its own footing, and count 2 above is about pooling users' data across wallets, not about an app's own data. What is void is treating "the singleton path is uncertain" as a settled argument. See [`../nextgraph-current-state.md`](../nextgraph-current-state.md) § Apps & services.
|
||||
>
|
||||
> **`discovery.ts` and its tests were removed on 2026-07-30**, along with `watchShape`'s public-scope fold and `INDEX_ACCOUNT`. See [`../briefs/2026-07-30-virtual-wallet-boundary.md`](../briefs/2026-07-30-virtual-wallet-boundary.md).
|
||||
>
|
||||
> One factual error below is worth naming so it is not carried into a future design: *"a native inbox (a primitive present on every document)"* is **false**. No document has an inbox upstream — only the public and protected STORE repos do (`engine/verifier/src/site.rs:128,149`; `doc_create` leaves `inbox: None`, `engine/repo/src/repo.rs:574`). See [`../nextgraph-current-state.md`](../nextgraph-current-state.md) § Inbox.
|
||||
>
|
||||
> What survives, and is worth keeping from the text below: the **3-stage frame** (`discovery → synchronization → query`) is still exactly right, with stage 1 re-read as *"a link reached you"* rather than *"you consulted an index"*. You still cannot query what you have not synchronized, and you still do not synchronize what nobody gave you. The **inbox** is what feeds stage 1 — which makes it the bootstrap of the whole reachability graph, not a side feature.
|
||||
>
|
||||
> Kept in full below as a record of what was built and why, and of the reasoning that has to be re-read through the correction above.
|
||||
|
||||
**Date:** 2026-06-16 · **Status:** SUPERSEDED 2026-07-30 (see the block above). *Originally: mechanism accepted; target owner undecided.*
|
||||
Ported here for the discovery mechanism it defines — the piece this lib
|
||||
realizes (`inbox.ts` post/materialize/watch; `store-registry.ts` fan-out). The
|
||||
realizes (`inbox.ts` post/materialize/watch; `shared-wallet/account-registry.ts` fan-out). The
|
||||
product intent (what a consumer application *should* surface) is the consumer
|
||||
application's concern, not this lib's; only the mechanism is recorded here.
|
||||
|
||||
@@ -63,7 +84,7 @@ later. This is why a global-index package is a deferred separate package in this
|
||||
## Polyfill reality — the fan-out drift is now RESOLVED (special-account index)
|
||||
|
||||
The shared-wallet polyfill originally shipped a cross-account fan-out over
|
||||
every account's public documents (`store-registry.ts` `listEntityDocs('public')`
|
||||
every account's public documents (`shared-wallet/account-registry.ts` `listEntityDocs('public')`
|
||||
/ `resolveReadGraphs`) — one account saw another's public entity without any
|
||||
relationship to its creator. This ADR classified that per-account fan-out as a drift
|
||||
to be replaced by the single global index.
|
||||
|
||||
@@ -9,7 +9,8 @@ the shim opens repos. Original context: the consuming app.
|
||||
> **protected** store (`did:ng:${protected_store_id}`), verified to open without
|
||||
> `RepoNotFound`. **The central insight of this ADR still holds** and now applies
|
||||
> to **both** stores: you must open the repo via the store's NURI
|
||||
> (`orm_start_graph`) or you get `RepoNotFound`.
|
||||
> or you get `RepoNotFound`. *(How it is opened has since changed — see the note
|
||||
> under Decision.)*
|
||||
|
||||
## Context
|
||||
|
||||
@@ -39,10 +40,17 @@ entity to reuse) → falls back to `doc_create` and the same `RepoNotFound`.
|
||||
## Decision
|
||||
|
||||
**Option B**: use the store NURI as both the `useShape` scope AND the write
|
||||
`@graph`, exactly like `expense-tracker-rdf`. This is why this lib's shim opens a
|
||||
store repo via `orm_start_graph` before writing, and why **`did:ng:i` must never
|
||||
be used as a scope** (it breaks writes with `RepoNotFound`). See the
|
||||
`orm_start_graph` scope rule in [`../simulation.md`](../simulation.md).
|
||||
`@graph`, exactly like `expense-tracker-rdf`. This is why this lib's shim opens the
|
||||
store repo before writing, and why **`did:ng:i` must never be used as a scope** (it
|
||||
breaks writes with `RepoNotFound`). See the scope rule in
|
||||
[`../simulation.md`](../simulation.md).
|
||||
|
||||
*The decision stands; the mechanism named in it has been replaced.* Opening was
|
||||
`orm_start_graph` when this was written. It is now `ensureRepoOpen` — `doc_subscribe`
|
||||
plus a wait for the first `State` (`packages/polyfill/src/emulated-verifier/open-repo.ts:167`) — after
|
||||
`orm_start_graph` was found to hang on a fan-out (`subscribe.ts:28,181`). What must be
|
||||
read here is the invariant *"open the repo, by its store NURI, before writing"*, not the
|
||||
call that used to implement it.
|
||||
|
||||
## Consequences
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
**Date:** 2026-06-15 · **Status:** Accepted (frozen). The rationale behind how
|
||||
the consumer application presents identity selection as a perceived login, and why
|
||||
the lib's identity store (`accounts.ts`) must never touch NextGraph. The lib itself
|
||||
the lib's identity store (`shared-wallet/virtualUsers.ts`) must never touch NextGraph. The lib itself
|
||||
no longer frames this as a login: it receives an identity id, set at wallet-import
|
||||
time; the perceived-login UX lives entirely in the consumer application.
|
||||
|
||||
@@ -63,8 +63,8 @@ barrier becomes the real per-user login — the flow shape does not change.
|
||||
|
||||
## How this lib realizes it
|
||||
|
||||
`accounts.ts` is an `IdentityStore`: `set(id)` / `clear()` / `get()` only read/write
|
||||
the identity id in an injected `AccountStorage`; they never call NG. The id is set at
|
||||
`shared-wallet/virtualUsers.ts` is an `IdentityStore`: `set(id)` / `clear()` / `get()` only read/write
|
||||
the identity id in an injected `VirtualUserStorage`; they never call NG. The id is set at
|
||||
wallet-import time and relayed via the lib's current-identity call; the perceived
|
||||
login is the consumer application's. See the identity store in
|
||||
[`../simulation.md`](../simulation.md).
|
||||
|
||||
@@ -0,0 +1,84 @@
|
||||
# Document links — what travels when an application shares a document
|
||||
|
||||
**Established 2026-08-06**, by direct reading of the `nextgraph-rs` clone (HEAD `213338f6`, 2026-05-16), the installed `@ng-org/web@0.1.2-alpha.13` declarations, and this repo's docs. Layer numbers per `README.md` § *The three references* (1 = engine, 2 = wasm binding / Rust SDK, 3 = ORM). `file:line` references are dated — navigate by symbol when they drift. Epistemic labels follow `docs/api-contract.md`.
|
||||
|
||||
**The question.** Alice writes a note; she wants Bob to open it. Bob is not necessarily known to her, and the sharing may cross a channel NextGraph knows nothing about — an email, a printed QR code, a web page. Does the model contain a value that travels, and if so, what does an application legitimately hold and pass around?
|
||||
|
||||
**The verdict.** Yes — and it is not a side feature: circulating a link is the model's only distribution mechanism ("you cannot discover, you can only follow links" — PO, 2026-07-30, `docs/readcap-and-nuri-model.md` §4ter-bis). The engine declares a complete link family (`NgLink`) whose doc comments describe out-of-band circulation as the normal case, and even names a durable "PermaLink" governed by a permission. But **nothing constructs any of it yet**, the repo-level *string* form an application would put in an email does not exist at any layer, and the value differs by scope: a link to a protected document carries the key, a link to a public document carries none.
|
||||
|
||||
---
|
||||
|
||||
## 1. Does a real application need this?
|
||||
|
||||
Yes, and not as a convenience. The two candidate paths in the framing collapse into one gesture at the model level: *publishing is two acts — place the data, then circulate the link* (§4ter-bis), and the inbox is merely one channel for that circulation ("post it into inboxes, **or** put it somewhere already reachable by the people concerned"). Directed delivery (path 1) is the same Link payload sealed to a known recipient's inbox; the email/QR case (path 2) is the same payload over a channel the recipient's identity never touches. Since there is no discovery — no index, no registry, nothing to find — a document that never has a link circulated for it has **no audience at all**. An application that lets users share anything therefore handles links; the only question is what the value is.
|
||||
|
||||
## 2. What the model actually offers
|
||||
|
||||
### Exists and is exercised
|
||||
|
||||
- **A self-contained share-URL for objects, commits and files.** Grammar: `did:ng[:o:{repo}]:v:{overlay}(:[cj]:{id}:k:{key})+[:s:{id}:k:{key}]:l:{locator}` (`RE_OBJECTS`, `engine/net/src/types.rs:63-65`); parser `NuriV0::new_for_readcaps` (`engine/net/src/app_protocol.rs:493-548`); one caller, `ngcli get` (`bin/ngcli/src/main.rs:430-460`), which connects **anonymously** to the broker named in the URL's `:l:` locator, fetches blocks with `ExtObjectGetV0`, and decrypts locally with the keys carried in the URL. Level 1 + CLI, working end to end: a stranger holding only the string reads the content. It addresses *frozen* content (objects, files, a commit) — not a live document.
|
||||
- **Shareable values at level 2 — for profiles and wallets, not documents.** `get_qrcode_for_profile(session_id, _public, size)` and its receiving half `import_contact_from_qrcode` (`index.d.ts:96,106`), payload `NgQRCodeProfileSharingV0 { inbox, profile, name, email }` (`engine/net/src/types.rs:5227-5233`); `wallet_export_get_qrcode` (`index.d.ts:332`; `sdk/rust/src/local_broker.rs:2074`, with textcode and rendezvous variants). Precedent that "a value crosses an out-of-band channel" is SDK-real — no document instance of it exists.
|
||||
- **NURIs are URL-shaped and the app opens them.** The app layer routes `/did:ng:*` to a `NURI` component (`app/ui-common/src/App.svelte:66`); the component is absent from this clone (app mid-rebuild), and its historical version (git `077ba626`, old `ng-app/src/routes/NURI.svelte`) deep-links only documents the **connected user already holds**. An in-app precedent for "a document reference is a URL", not for stranger-opening.
|
||||
|
||||
### Exists, unexercised — the declared model
|
||||
|
||||
- **The link family.** `NgLinkV0 = Repo | PublicRepo | Branch | Object` (`engine/net/src/types.rs:5206-5217`). `RepoLinkV0 { id, read_cap, overlay, peers }` (`:5062-5079`), whose comment states the flow: *"In most cases, the link is shared and then the recipient opens it and subscribes soon afterward"* (`:5059`). `PublicRepoLinkV0 { repo, branch?, heads, snapshot?, public_store, peers }` — **no `read_cap` field** (`:5105-5127`). `ReadBranchLinkV0` (`:5142`), `ObjectLinkV0` (`:5176`). **Zero constructors and zero consumers in the entire workspace** (grep over `engine/`, `sdk/`, `bin/`, `app/`): the family is a declared model, not a feature.
|
||||
- **The NURI type has exactly a link's slots — the string grammar does not.** `NuriV0 { target, overlay, access: Vec<NgAccessV0>, locator: Option<Locator> }` (`engine/net/src/app_protocol.rs:181-195`); `NgAccessV0::ReadCap(ReadCap)` (`:55`) has **zero consumers anywhere**. The `r:` segment (a repo-level ReadCap, `BlockRef::readcap_nuri`, `engine/repo/src/types.rs:518-521`) is *produced* for display (`engine/verifier/src/verifier.rs:278,320`) and **parsed by nothing**; `NuriV0::new_from` (`app_protocol.rs:643-737`) accepts only cap-less forms plus the file/commit `:k:` forms. The only parsed cap+locator grammar is the object form above.
|
||||
- **The recipient's mechanics exist and work — short of the external case.** `Verifier::load_repo_from_read_cap` (`engine/verifier/src/verifier.rs:2237`, `pub(crate)`) is exercised for the user's own stores and the `AddRepo` replay (`engine/verifier/src/commits/mod.rs:660`); the one call site that would open an **external** repo from a received cap is commented out (`engine/verifier/src/inbox_processor.rs:469-481`, social-query forwarder). The durable filing register for a received link exists: `AddLink { read_cap }` on the User branch, *"so that a user can share with all its device a new Link they received"*, external repos only (`engine/repo/src/types.rs:1934-1950`).
|
||||
- **Serving the public store to strangers is broker-plumbed and client-disabled.** `PinRepoV0.expose_outer` exists through the broker's storage (`engine/net/src/types.rs:3123`; `engine/broker/src/server_storage/core/overlay.rs:103-127`), but the client hard-codes `expose_outer: false` in both `PinRepo` constructors (`engine/net/src/actors/client/pin_repo.rs:51,79`), and `ExtTopicSyncReq` — the anonymous branch-sync a `PublicRepoLink` needs — is declared and `unimplemented!()` (`engine/net/src/types.rs:4523,4533`). Only `ExtObjectGet` and `WalletGetExport` are servable ext requests today.
|
||||
- **Durable links are named, not built.** `PermaCap` is a TODO (`engine/repo/src/types.rs:578`), and `PermissionV0::PermaShare` — *"can create and answer to PermaCap (PermaLink)"* — already reserves the governance of creating one (`:1761`).
|
||||
|
||||
### Does not exist
|
||||
|
||||
- No function at level 2 or 3 produces or accepts a document link (all 77 `index.d.ts` exports checked; `sdk/rust/src/local_broker.rs` has only the wallet QR/textcode/rendezvous trio). `doc_fetch_repo_subscribe` (`index.d.ts:64`, `sdk/js/lib-wasm/src/lib.rs:1900`) opens documents the session **already holds** — an unknown repo errors `RepoNotFound` (`engine/verifier/src/request_processor.rs:155,163`) — it is not a stranger-open.
|
||||
- No string serialization of `NgLink`, and no repo-level cap-bearing NURI that any parser accepts. Per the design principle, none of these absences says anything about the future SDK; the declared types above say a great deal.
|
||||
|
||||
### What the receiving side actually needs — a reference alone is NOT enough
|
||||
|
||||
A bare `did:ng:o:{id}`, or even `o:{id}:v:{overlay}`, gives a stranger nothing: no locator → no broker to ask; no cap → nothing decrypts, and addressing itself presupposes the cap (the outer overlay is never registered, and there is no existence probe — `docs/readcap-and-nuri-model.md` §4bis, the refuted-hypothesis block). What a stranger needs to resolve **and join** is precisely `RepoLinkV0`'s field list — id + read_cap + overlay + peers — or, public, `PublicRepoLinkV0`'s find-and-join set. The `peers`/locator half is not decoration; it is the join, and it is why the polyfill's single-broker world makes locators invisible today.
|
||||
|
||||
## 3. Public vs protected — the distinction is in the model
|
||||
|
||||
The two link structures differ on exactly one thing: **the key**. `RepoLinkV0` carries `read_cap`; `PublicRepoLinkV0` carries none — *"The latest ReadCap of the branch … will be downloaded from the outerOverlay, if the peer brokers listed below allow it"*, and *"This link is durable, because the public site are served differently by brokers"* (`engine/net/src/types.rs:5100-5104`). Public-ness is therefore a property of the **store and of how brokers serve it** (outer-overlay exposure), not a capability that circulates. This matches the official docs' store table (docs-intent, transcribed in `docs/nextgraph-current-state.md:44-58`): Public read = *"Everyone, no capability"*, *"equivalent to your website … without the need for special permissions"*; Protected = *"share … but they will need a special link and permission"*.
|
||||
|
||||
Two nuances against over-reading:
|
||||
|
||||
- It is not that no key *exists*. Today every branch — public included — has its ReadCap and its content is encrypted; the public link merely does not **carry** the key, because any holder of the link may fetch the current one from the outer overlay. The stated direction of not encrypting public-store content at all is PO-confirmed but explicitly not to be depended on by any surface (§4ter).
|
||||
- The durability asymmetry follows from what the value contains: a public link *names* and stays valid across cap refresh; a protected link *carries* and goes stale when the cap is rotated (§4 below).
|
||||
|
||||
What follows for a public document, and is easy to get wrong: **there is nothing per-reader**. No grant, no per-reader revocation, no audience list — the only lever is coarse (unpublish/re-key the store's serving). An application UI that enumerates or revokes "the readers of my public document" is built on nothing.
|
||||
|
||||
### The polyfill's public emulation, read against this
|
||||
|
||||
**Rewritten 2026-08-06**, when the emulation changed. It used to refuse a cap-less reference for every scope, which was over-strict in the safe direction but left an application unable to express *"circulate widely, the reference is enough"* — the one act the model makes cheap. `emulated-verifier/public-store.ts` now emulates the declared mechanism: a document in a public store exposes its ReadCap, and any reader's first door fetches it. Possession still decides everything; what changed is that for a public document the cap is **obtainable** instead of having to be handed over.
|
||||
|
||||
**This aligns on a DECLARED model, not on current behaviour, and the difference is worth stating.** What is read in source: `PublicRepoLinkV0` carries no `read_cap` and its comment says *"The latest ReadCap of the branch will be downloaded from the outerOverlay, if the peer brokers listed below allow it […] the public site are served differently by brokers"* (`engine/net/src/types.rs:5098-5124`); the broker's `expose_outer` plumbing exists (`engine/broker/src/server_storage/core/overlay.rs:103-133`). What is *not* wired today, per the inventory above: the client hard-codes `expose_outer: false` in both `PinRepo` constructors, and `ExtTopicSyncReq` — the anonymous branch-sync such a link needs — is `unimplemented!()`. So the emulation follows the model the engine declares, in a place the engine does not yet serve. That is the intended posture for this library (an absent implementation says nothing about what the target will do), and it is a bet, named here as one.
|
||||
|
||||
Three things that remain true and must stay visible wherever the public emulation is documented:
|
||||
|
||||
1. **Per-reader semantics for public documents** must not be inferred from the cap-per-holder bookkeeping — upstream has none. No grant, no per-reader revocation, no audience list.
|
||||
2. The `:r:` segment inside anything naming a *public* document is emulation detail: upstream's public link carries no key material, because the key is fetched. Harmless as long as the value stays opaque to the consumer — which is the contract to enforce.
|
||||
3. **Reading is not writing.** The cap a public store serves grants reading only; `caps.learnFromPublicStore` files it apart and `docs.sparqlUpdate` refuses a write on it. Upstream a public store never makes a repo world-writable — writing needs the write cap, and `verify_permission` fires on WRITE only.
|
||||
|
||||
The surface consequence: the *act* — obtain a link, circulate it — is the same for both scopes upstream (`NgLinkV0` is one enum over both), so one producing function covering both is target-shaped; what differs is the semantics attached to the **value** (durability, revocability, the absence of per-reader anything), and that belongs in documentation, not in a second function.
|
||||
|
||||
## 4. Durability — what an application may store
|
||||
|
||||
- **Protected links go stale by design.** *"Those capabilities are not durable: They can be refreshed … and previously shared Caps will become obsolete/revoked"* (`engine/net/src/types.rs:5055-5058`). Rotation re-delivers the new cap **to the inboxes of those who keep access, at the rotating party's choice** (PO DIRECTION, `docs/readcap-and-nuri-model.md` §3) — never through the stored link. So a protected link in an email opened months later may no longer open; an application must treat open-from-link as fallible and fall back to a person-channel re-request. The declared future answer for stored-unopened links is `PermaCap`/PermaLink — a TODO (`engine/repo/src/types.rs:578,1761`).
|
||||
- **Public links are durable** by construction (`:5103`): they carry nothing that rotation invalidates.
|
||||
- **The polyfill emulates no revocation** (readcap doc §5, P3), so nothing goes stale today; consumers must not read permanence into that.
|
||||
|
||||
## 5. Recommendation for the polyfill
|
||||
|
||||
**SUPERSEDED on its first point, 2026-08-06 — `linkTo` was REMOVED, and the removal stands.** This section used to open: *"The surface already exists: `linkTo(doc: NuriLike): ReadCap` … `inbox.share(doc, toUser)` for directed delivery. **Keep `linkTo` — the act is the right one**"*. What that recommendation missed is the single thing § 0 of `docs/readcap-and-nuri-model.md` exists to hold: a call that returns a document's **key** where a caller asked for its **reference** converts *"whoever has the reference AND the key reads"* into *"whoever has the reference reads"* — for that document and for every document it mentions — so confidentiality can no longer be composed inside anything one circulates. The *act* (circulate a value that opens a document) may still be right; making it the answer to "give me the link to my document" was not. The reasoning is recorded where the function was, in the `No linkTo here` block of `packages/polyfill/src/surface/placement.ts`.
|
||||
|
||||
What an application does instead, today: it names a document with the bare reference it already holds — every published call returns one — and grants access with `inbox.share(doc, toUser)` (`packages/polyfill/src/surface/inbox.ts`). The four points below are kept and re-read against that: 1 and 4 stand as written for **any** future link-producing surface; 2 is void with the function; 3 is unchanged and still open.
|
||||
|
||||
1. **Label any such call LEVEL-1 SHAPE in `docs/api-contract.md`.** What supports it: the `NgLink` family and its stated sharing flow, the `PermaShare` permission, the exercised object-URL and profile-QR precedents, and the PO doctrine that circulation is the only distribution. The model's own stated flows are unusable without *some* produce-a-link affordance, which is as much confidence as an unbuilt feature allows. What cannot be promised: the SDK's name for it, sync vs async (upstream link-building needs overlay + peers from the session, so async is plausible — same adapter-sized delta class as `subscribeDoc`'s sync unsubscribe), and whether the value is a NURI string or a structured link. Therefore: **the returned value is opaque**; a consumer that stores it, transmits it, and hands it back unmodified learns nothing to unlearn; a consumer that parses it does.
|
||||
2. ~~**Fix the comment-vs-code mismatch in `linkTo`.**~~ **VOID — the function is gone.** The observation it rested on survives and is worth keeping: `RepoLinkV0`-with-key IS the protected-document link, and circulating it out-of-band is the documented normal case (`:5059`), so a protected link carrying its key is not in itself a violation — with the § 4 durability caveat. What made `linkTo` wrong was not that the value carried a key; it was that a caller got one **by asking for a reference**. Handing over a key must be its own act, which is what `inbox.share` is.
|
||||
3. **The recipient verb is missing.** Nothing exported ingests an out-of-band link: `learn` is reached only by inbox processing and the connection drain (`packages/polyfill/src/surface/inbox.ts:410`, `packages/polyfill/src/emulated-verifier/connect.ts:68`), and `getCaps()` is documented machinery (api-contract §15). The model names the recipient act precisely — open the link: load the repo from its read cap, file `AddLink` durably on the User branch, subscribe (`:5059`; `engine/repo/src/types.rs:1934-1950`; `verifier.rs:2237`). Suggested surface, same epistemic label as point 1: `openLink(link: string): Promise<Nuri>` — files the cap in the emulated registers and returns the cap-less target for use in reads. Without it, path 2 has a producer and no consumer, and the multi-actor test where Bob *obtains* the document through calls (never through a shared variable) cannot be written — the exact failure mode `rules/engineering/multi-actor-tests-obtain-not-receive.md` records.
|
||||
4. **Do not add**: link options (expiry, audience, revoke-this-link), per-reader introspection for public documents, or any API that parses or inspects a link's insides — nothing upstream supports any of them, and each teaches a lever the model does not have.
|
||||
|
||||
## 6. The question for the NextGraph developer
|
||||
|
||||
What will an application hold and pass around to share **one document** out-of-band (email, QR) — a NURI string with `r:`/`l:` segments, a serialized `NgLink`, something else — and which SDK calls will produce it and open it? And for a *public* document, is the intended value the key-less `PublicRepoLink` form, i.e. should applications treat public sharing as never involving a per-reader capability?
|
||||
@@ -1,57 +1,57 @@
|
||||
# Perte d'écriture lors d'une mort de socket (`SerializationError`)
|
||||
# Write loss on socket death (`SerializationError`)
|
||||
|
||||
**Post-mortem — 2026-07-14 · Statut : OUVERT (non traité).**
|
||||
**Post-mortem — 2026-07-14 · Status: OPEN (not addressed).**
|
||||
|
||||
Une entité écrite juste avant une période d'inactivité peut être **perdue silencieusement** : l'écriture n'atteint jamais durablement le broker, et l'entité est absente à la reconnexion. Le **compte / l'identité survit** (pas de fork). Observé en conditions réelles (Festipod, Firefox) lors d'une pause après login/création.
|
||||
An entity written just before a period of inactivity can be **silently lost**: it is absent on reconnection. *(Whether the write never durably reached the broker, or reached it and is not read back on a cold reconnection, is **not settled** — see Epistemic caveat below. The wording here deliberately states only the observed symptom.)* The **account / identity survives** (no fork). Observed in real conditions (Festipod, Firefox) during a pause after login/creation.
|
||||
|
||||
## Symptôme
|
||||
## Symptom
|
||||
|
||||
1. L'utilisateur se connecte, l'app crée une entité (un événement Festipod).
|
||||
2. Une période d'inactivité suit (idle, onglet en arrière-plan…).
|
||||
3. Le socket broker meurt spontanément avec `SOCKET IS CLOSED Some(Left(SerializationError))`.
|
||||
4. À la reconnexion, l'entité créée a disparu ; l'app relit son propre scope **vide**.
|
||||
1. The user logs in, the app creates an entity (a Festipod event).
|
||||
2. A period of inactivity follows (idle, tab in the background…).
|
||||
3. The broker socket dies spontaneously with `SOCKET IS CLOSED Some(Left(SerializationError))`.
|
||||
4. On reconnection, the created entity has disappeared; the app reads back its own scope **empty**.
|
||||
|
||||
## Preuves (VÉRIFIÉ — logs Firefox en direct, verbatim)
|
||||
## Evidence (VERIFIED — live Firefox logs, verbatim)
|
||||
|
||||
```
|
||||
… REPLAY TOPIC NOT FOUND <topic> IN OVERLAY <overlay>
|
||||
… NEED REPLAY true
|
||||
… SENDING EVENTS FROM OUTBOX RETURNED: Err(TopicNotFound)
|
||||
[user1][polyfill] resolveAccount(user1) → 1 record ← le compte SURVIT (pas de fork)
|
||||
[user1][polyfill] readScopeIndex(…) → 0 entities ← mais le scope est VIDE
|
||||
[user1][polyfill] resolveAccount(user1) → 1 record ← the account SURVIVES (no fork)
|
||||
[user1][polyfill] readScopeIndex(…) → 0 entities ← but the scope is EMPTY
|
||||
… set reçu: 0 objets Event (public)
|
||||
… SOCKET IS CLOSED Some(Left(SerializationError)) [51, 3, 223, …]
|
||||
```
|
||||
|
||||
Lecture (**mécanisme plausible, non tranché**) : l'écriture a été poussée dans l'**outbox** local, mais le socket est mort avant qu'elle ne soit **flushée durablement** dans le topic broker ; à la reconnexion, le replay de l'outbox échoue (`Err(TopicNotFound)`) parce que le topic n'a **jamais été créé côté broker** → l'événement est abandonné. Le compte, lui, avait déjà été résolu durablement (`resolveAccount → 1 record`) : il n'est ni perdu ni forké.
|
||||
Interpretation (**plausible mechanism, not settled**): the write was pushed into the local **outbox**, but the socket died before it was **durably flushed** into the broker topic; on reconnection, the outbox replay fails (`Err(TopicNotFound)`) because the topic was **never created on the broker side** → the event is abandoned. The account, for its part, had already been durably resolved (`resolveAccount → 1 record`): it is neither lost nor forked.
|
||||
|
||||
> **Réserve épistémique.** Les preuves établissent le *symptôme* (perte + `Err(TopicNotFound)` + `readScopeIndex → 0`). Le *mécanisme* exact n'est pas tranché entre **(i) perte à l'écriture** (l'écriture n'atteint jamais durablement le broker) et **(ii) échec de réhydratation à froid** (l'écriture *est* sur le broker mais une session fraîche ne rouvre pas le scope propre). Le `Err(TopicNotFound)` sur le replay outbox penche pour **(i) dans ce cas Firefox**. Voir la repro @data ci-dessous, qui expose un symptôme voisin mais **ne tranche pas** (i) vs (ii).
|
||||
> **Epistemic caveat.** The evidence establishes the *symptom* (loss + `Err(TopicNotFound)` + the scope read returning 0 — logged above as `readScopeIndex`, since renamed `readUserStore`). The exact *mechanism* is not settled between **(i) loss at write time** (the write never durably reaches the broker) and **(ii) cold-rehydration failure** (the write *is* on the broker but a fresh session does not reopen its own scope). The `Err(TopicNotFound)` on the outbox replay leans toward **(i) in this Firefox case**. See the @data repro below, which exhibits a neighboring symptom but **does not settle** (i) vs (ii).
|
||||
|
||||
## Chaîne causale (TRACÉ — lecture du core NextGraph, à re-vérifier)
|
||||
## Causal chain (TRACED — reading of the NextGraph core, to be re-verified)
|
||||
|
||||
- La `SerializationError` ferme le socket. Le core émet la déconnexion : `broker.rs` → `LocalBrokerMessage::Disconnected` → `disconnections_sender.send(...)` (≈ `broker.rs:1051`, à re-vérifier — numéro volatil, se repérer par le symbole).
|
||||
- Cette déconnexion est **poussée** aux abonnés via `disconnections_subscribe(cb)` (flux PUSH).
|
||||
- **La reconnexion NextGraph est un `// TODO` non implémenté** (≈ `broker.rs:1051-1076`) : rien ne rétablit le socket ni ne re-flushe l'outbox.
|
||||
- `user_connect` renvoie un **instantané** `{ server_id, server_ip, error, since }` au moment de l'appel — pas un flux, inutilisable pour détecter une chute ultérieure.
|
||||
- **Aucune API de confirmation de durabilité d'écriture** : un appelant ne peut pas `await` la garantie qu'une écriture a atteint le broker.
|
||||
- The `SerializationError` closes the socket. The core emits the disconnection in **two** places, and they are not the same file: `engine/net/src/broker.rs:1074` sends `LocalBrokerMessage::Disconnected`, which the SDK turns into `disconnections_sender.send(...)` at `sdk/rust/src/local_broker.rs:648`. Navigate by symbol — the line numbers are volatile, and the earlier note in this file put the `send` in `broker.rs`, which it never was.
|
||||
- This disconnection is **pushed** to subscribers via `disconnections_subscribe(cb)` (PUSH stream).
|
||||
- **NextGraph reconnection is an unimplemented `// TODO`** (≈ `broker.rs:1051-1076`): nothing re-establishes the socket nor re-flushes the outbox.
|
||||
- `user_connect` returns a **snapshot** `{ server_id, server_ip, error, since }` at call time — not a stream, unusable for detecting a later drop.
|
||||
- **No write-durability confirmation API**: a caller cannot `await` the guarantee that a write has reached the broker.
|
||||
|
||||
## Ce que le SDK expose mais ne consomme pas
|
||||
## What the SDK exposes but does not consume
|
||||
|
||||
`disconnections_subscribe` **se déclenche** sur cette panne — mais ni le polyfill (`@ng-eventually/client`) ni l'app consommateur ne s'y abonnent. Le signal existe, personne ne l'écoute ; côté app, aucun mécanisme ne re-tente ni n'avertit l'utilisateur.
|
||||
`disconnections_subscribe` **does fire** on this failure — but neither the polyfill (`@ng-eventually/polyfill`) nor the consumer app subscribes to it. The signal exists, nobody listens to it; on the app side, no mechanism retries or warns the user.
|
||||
|
||||
## Portée & non-reproduit
|
||||
## Scope & not reproduced
|
||||
|
||||
- **Observé Firefox uniquement** à ce jour. Un test manuel sur un autre navigateur n'a pas déclenché la `SerializationError` ni ses conséquences.
|
||||
- **Reproduction @data (Chromium, broker réel) — 2026-07-14, décisive.** Le test de reconnexion @data existant (`reconnexion-meme-identite`) était **faux-vert** : il relisait les repos de A depuis l'**IndexedDB local** du profil persistant, jamais depuis le broker. Un lecteur **réellement à froid** (contexte non-persistant `freshBrowser`, **même** wallet/compte A, aucun état local — seedé du wallet capturé avant l'événement) lit **0** événement de A (`BARRIER timed-out (8000ms)`, `CONNECTION ESTABLISHED`). Signature **différente** du cas Firefox (pas de mort de socket ; l'`OUTBOX empty` est celui du lecteur, trivialement vide) et **ne tranche pas** (i) vs (ii) — un barrier vide est compatible avec les deux. Établi en revanche : **@data n'a jamais vérifié la durabilité broker des lectures propres de A**, et la réhydratation à froid depuis le broker échoue. Repro : `src/modules/event/features/reconnexion-froide-sans-local.feature` (Festipod).
|
||||
- **Pour trancher (i) vs (ii)** : vérifier indépendamment que l'écriture de A atteint le broker — p.ex. un lecteur *chaud* / une seconde identité lit le doc public de l'événement (le scénario d'isolation deux-identités). S'il le voit → l'écriture est durable → le 0 du lecteur à froid est un **(ii)** (réhydratation). Sinon → **(i)**.
|
||||
- **Observed on Firefox only** to date. A manual test on another browser did not trigger the `SerializationError` nor its consequences.
|
||||
- **@data reproduction (Chromium, real broker) — 2026-07-14, decisive.** The existing @data reconnection test (`reconnexion-meme-identite`) was a **false green**: it read A's repos back from the persistent profile's **local IndexedDB**, never from the broker. A **genuinely cold** reader (non-persistent `freshBrowser` context, the **same** wallet/account A, no local state — seeded from the wallet captured before the event) reads **0** events from A (`BARRIER timed-out (8000ms)`, `CONNECTION ESTABLISHED`). A **different** signature from the Firefox case (no socket death; the `OUTBOX empty` is the reader's, trivially empty) and it **does not settle** (i) vs (ii) — an empty barrier is compatible with both. Established on the other hand: **@data has never verified the broker durability of A's own reads**, and cold rehydration from the broker fails. Repro: `src/modules/event/features/reconnexion-froide-sans-local.feature` (Festipod).
|
||||
- **To settle (i) vs (ii)**: independently verify that A's write reaches the broker — e.g. a *warm* reader / a second identity reads the event's public doc (the two-identity isolation scenario). If it sees it → the write is durable → the cold reader's 0 is a **(ii)** (rehydration). Otherwise → **(i)**.
|
||||
|
||||
## Pistes de correction (non arbitré)
|
||||
## Fix leads (not arbitrated)
|
||||
|
||||
1. **Core** — corriger la `SerializationError` **et** implémenter le TODO de reconnexion (rétablir le socket + re-flusher l'outbox).
|
||||
2. **SDK / polyfill** — consommer `disconnections_subscribe` → reconnexion + re-flush outbox comme mitigation, indépendamment du core.
|
||||
3. **API de durabilité** — exposer une confirmation qu'une écriture a atteint le broker, pour que l'appelant puisse l'`await`.
|
||||
1. **Core** — fix the `SerializationError` **and** implement the reconnection TODO (re-establish the socket + re-flush the outbox).
|
||||
2. **SDK / polyfill** — consume `disconnections_subscribe` → reconnection + outbox re-flush as a mitigation, independently of the core.
|
||||
3. **Durability API** — expose a confirmation that a write has reached the broker, so that the caller can `await` it.
|
||||
|
||||
## Liens
|
||||
## Links
|
||||
|
||||
- `docs/nextgraph-current-state.md` — état courant du core (déconnexion / reconnexion à cross-référencer ici).
|
||||
- Impact produit + caveat côté consommateur : concept Festipod `data-layer` → `caveat_write-durability-across-disconnect`.
|
||||
- `docs/nextgraph-current-state.md` — current state of the core (disconnection / reconnection to be cross-referenced here).
|
||||
- Product impact + consumer-side caveat: Festipod concept `data-layer` → `caveat_write-durability-across-disconnect`.
|
||||
|
||||
@@ -0,0 +1,281 @@
|
||||
# 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` (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` (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.
|
||||
|
||||
---
|
||||
|
||||
## 1. The wrapped `ng` factory — `surface/ng-proxy.ts`
|
||||
|
||||
```ts
|
||||
export function makeNg(): NG;
|
||||
export function wrappedNg(): NG; // the memoised one - THE instance, since 1.0.0-dev.7
|
||||
```
|
||||
|
||||
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.
|
||||
- `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
|
||||
|
||||
```ts
|
||||
// model/nuri.ts
|
||||
export function targetOf(nuri: Nuri): Nuri;
|
||||
export function parseNuri(nuri: Nuri): { target: Nuri; readCap?: ReadCap };
|
||||
// emulated-verifier/caps.ts — NOT `model/nuri.ts`; it moved when the source layout was
|
||||
// reorganised by migration fate, and this block said `nuri.ts` until 2026-08-10.
|
||||
export function mintCap(nuri: Nuri): ReadCap;
|
||||
```
|
||||
|
||||
`targetOf` strips a `:r:` cap segment to the naming form; `parseNuri` is the parsed pair; `mintCap` builds the cap-bearing form with the stand-in value `OK` (`STAND_IN_CAP`). Kept off the surface deliberately: nothing published turns a bare reference into a cap.
|
||||
|
||||
- `targetOf` / `parseNuri` — **LEVEL-1 SHAPE, model VERIFIED**: they transcribe upstream's one-type-with-optional-access NURI, on the **two** fields this library uses. Not a "1:1 mirror" of `NuriV0`, as this line claimed until 2026-08-10: that type has TEN fields — `identity, target, entire_store, objects, signature, branch, overlay, access, topic, locator` (`engine/net/src/app_protocol.rs:181-194`) — of which `parseNuri` carries `target` and the cap half of `access`. The other eight have no counterpart here (the missing `locator` is a stated gap, `docs/readcap-and-nuri-model.md` § 4sexies). The ReadCap encoding they discriminate on is `r:{base64url(serde_bare(ObjectRef))}` (`BlockRef::readcap_nuri`, `engine/repo/src/types.rs:518-521`), distinct from the `:k:` object/commit forms (`object_nuri`/`commit_nuri`, `types.rs:510-514`). No JS surface parses NURIs at level 2 or 3 — the real SDK takes plain strings — so these helpers never surface in signatures and survive only as internals.
|
||||
- `mintCap` — **NO COUNTERPART as an operation, and that is the point**: upstream a ReadCap is produced by the engine when a repo is created, never derived from a bare reference by a caller. `mintCap` exists solely because the emulation needs a cap VALUE at creation time and cap-enforcement has not yet supplied real key material; the constant `OK` pretends nothing (`STAND_IN_CAP`, `emulated-verifier/caps.ts`). It has exactly two call sites (`shared-wallet/account-registry.ts` `createEntityDoc`; `emulated-verifier/caps.ts` internals) — the minting points of the emulation. With cap-enforcement the constant becomes a real key; at migration the function is deleted (the engine mints).
|
||||
|
||||
## 3. The reach boundary — `emulated-verifier/reach.ts`
|
||||
|
||||
```ts
|
||||
// reach.ts:66
|
||||
export function declareInfrastructure(nuri: Nuri): void;
|
||||
// reach.ts:71
|
||||
export function isInfrastructure(nuri: Nuri): boolean;
|
||||
// reach.ts:76
|
||||
export function resetInfrastructure(): void;
|
||||
// reach.ts:93
|
||||
export function mayReach(nuri: Nuri): boolean;
|
||||
// reach.ts:110
|
||||
export function assertMayReach(nuri: Nuri, op: string): void;
|
||||
// reach.ts:131
|
||||
export function mustNotAttempt(nuri: Nuri): boolean;
|
||||
```
|
||||
|
||||
The single predicate deciding whether the CONNECTED virtual user may touch a document at all: cap possession, or explicitly-declared infrastructure (the store-root and doc-shim). `assertMayReach` guards the passage points (rule 1, throw on refusal); `mustNotAttempt` guards the callers (rule 2, do not even issue the operation). Inert until the first cap exists (`caps.isEnforcing()`).
|
||||
|
||||
- **NO COUNTERPART, shared-wallet machinery — the emulated stand-in for the wallet boundary itself.** In the target the boundary is cryptographic, not a predicate: a repo whose cap the wallet does not hold is never decrypted, a targeted read of it errors `RepoNotFound` (`resolve_target_for_sparql`, `engine/verifier/src/request_processor.rs:264,269`), and the only path that loads a repo from a cap is `pub(crate)` (`Verifier::load_repo_from_read_cap`, `engine/verifier/src/verifier.rs:2237`). The two-rules split (refuse at the gate AND do not attempt) is redundancy this lib chose; upstream only "cannot" exists — there is nothing to refuse because the request cannot be formed.
|
||||
- The infrastructure exemption (`declareInfrastructure`, registered by `shared-wallet/account-registry.ts` for the store-root and doc-shim only) has **no image in the target**: there is no shim to exempt. Registration-not-pattern-matching is a lib-internal safety choice.
|
||||
- Everything here disappears at migration; the durable lesson it protects (naming a document does not grant access) is the target's own model.
|
||||
|
||||
## 4. The physical user's primitives — `shared-wallet/physical.ts`
|
||||
|
||||
```ts
|
||||
// physical.ts:54
|
||||
export async function physicalCreate(sessionId: string, crdt = "Graph", cls = "data:graph", dest = "store", store?: unknown): Promise<Nuri>;
|
||||
// physical.ts:80
|
||||
export async function physicalQuery(sessionId: string, query: string, base: string | undefined, anchor: Nuri, label = "physicalQuery"): Promise<unknown>;
|
||||
// physical.ts:94
|
||||
export async function physicalUpdate(sessionId: string, query: string, anchor: Nuri, label = "physicalUpdate"): Promise<void>;
|
||||
```
|
||||
|
||||
The unguarded counterparts of `docs.docCreate` / `sparqlQuery` / `sparqlUpdate`, callable only by the library's own machinery on the shim's documents (store-root pointer, doc-shim, provisioning). Separated as FUNCTIONS rather than as an exemption list so machinery never gets "waved through" a guard (module header, `physical.ts:19-27`).
|
||||
|
||||
- As wire calls: **PASSTHROUGH (level 2, VERIFIED)** — the same `doc_create` / `sparql_query` / `sparql_update` the published `docs.*` forwards to (`index.d.ts:60,295,297`; sources `sdk/js/lib-wasm/src/lib.rs:1575` web / `:1618` nodejs, `:352`/`:555`), minus the lib-internal `label`.
|
||||
- As a CONCEPT: **NO COUNTERPART, shared-wallet machinery.** The physical/virtual user split exists only because one wallet hosts many identities; the target has exactly one user per wallet and no privileged "machinery caller". The module disappears with the shim.
|
||||
|
||||
## 5. Physical subscription — the unexported slice of `subscribe.ts`
|
||||
|
||||
```ts
|
||||
// subscribe.ts:118
|
||||
export function subscribePhysicalDoc(nuri: Nuri, onChange: (r: DocChange, type: DocChangeType) => void): Unsubscribe;
|
||||
```
|
||||
|
||||
`subscribeDoc` minus the reach guard — the machinery's door to `doc_subscribe`, used by `emulated-verifier/open-repo.ts` to hold shim repos open. Same wire behaviour as the published `subscribeDoc` (analysed in `docs/api-contract.md` § 8, target `doc_subscribe`, `index.d.ts:66`, `sdk/js/lib-wasm/src/lib.rs:1908`).
|
||||
|
||||
- **NO COUNTERPART, shared-wallet machinery** — the guarded/unguarded pair collapses to one call when the wallet is the boundary. Disappears with `shared-wallet/physical.ts`.
|
||||
|
||||
## 6. Bootstrap repo opening — `emulated-verifier/open-repo.ts`
|
||||
|
||||
```ts
|
||||
// open-repo.ts:98
|
||||
export type SyncState = "syncing" | "synced" | "timed-out";
|
||||
// open-repo.ts:197 - TEST-ONLY
|
||||
export function setOpenTimeoutForTests(ms: number): void;
|
||||
// open-repo.ts:204
|
||||
export function resetOpenedRepos(): void;
|
||||
// open-repo.ts:252 - DERIVED, nothing stores it
|
||||
export function getSyncState(nuri: Nuri): SyncState | "unknown";
|
||||
// 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>;
|
||||
```
|
||||
|
||||
> 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.
|
||||
- **`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.
|
||||
|
||||
## 7. The read filter — `emulated-verifier/read-filter.ts`
|
||||
|
||||
```ts
|
||||
// read-filter.ts:47
|
||||
export function filterReadable<T>(items: Iterable<T>, caps: CapRegistry): T[];
|
||||
// read-filter.ts:60
|
||||
export function makeReadFilteredView<S extends object>(set: S, caps: CapRegistry): S;
|
||||
```
|
||||
|
||||
The polyfill of capability-based read access: a Proxy view over the reactive set keeping only items whose `@graph` document the current holder holds; applied by `surface/use-shape.ts` once `caps.isEnforcing()`.
|
||||
|
||||
- **NO COUNTERPART, by design — it stands in for cryptographic non-delivery.** In the target the broker/verifier simply never yields what the wallet holds no cap for (targeted read errors, `request_processor.rs:264,269`; union read yields nothing for undecrypted repos — the § 4 analysis of `docs/api-contract.md`). There is no post-hoc filter to migrate to; the module is deleted.
|
||||
- The `@graph` key it filters on is **level 3, VERIFIED**: the ORM annotates every object with its graph NURI (`sdk/js/orm/src/frontendAdapters/react/useShape.ts:41`, `sdk/js/orm/src/model/types.ts:19`). Items with no `@graph` are kept — a lib policy choice (they name no document), not an upstream rule.
|
||||
- Access unit = the DOCUMENT, not the item — faithful to the model (a ReadCap opens a repo, `types.rs:518-521`), and the reason the filter is all-or-nothing per document.
|
||||
|
||||
## 8. Connection trigger — the unexported slice of `emulated-verifier/connect.ts`
|
||||
|
||||
```ts
|
||||
// connect.ts:91
|
||||
export function startConnect(): void;
|
||||
```
|
||||
|
||||
Fire-and-forget wrapper over `connectedUser()` (internal since 2026-08-07, awaited inside `ensureIdentity`) (restore Links, then drain every inbox), called by `setCurrentUser` so inbox processing is the library's job, not the app's.
|
||||
|
||||
- **LEVEL-1 SHAPE for the timing, VERIFIED**: upstream the recipient's verifier processes inbox messages as they arrive, with no consumer call (`Verifier::inbox` → `process_inbox`, `engine/verifier/src/verifier.rs:1674-1690`); firing on connection is the emulation's equivalent moment. The restore-before-drain order is a lib choice; upstream "restore" does not exist as a step (applied caps are already in the User branch replay).
|
||||
- `startConnect` itself disappears at migration; the automatic-processing behaviour it fabricates is native.
|
||||
|
||||
## 9. The shim registry — the unexported slice of `shared-wallet/account-registry.ts`
|
||||
|
||||
The sharpest boundary case: `surface/placement.ts` publishes the 7 app-facing calls; the 9 exports below stay internal (importable by the lib's modules, unit tests and the e2e harness, not by an application through the package entries). The type `RegistrySession` is published by the entry (a consumer types its injected `getSession` with it) and covered by the surface contract; `VirtualUserRecord` is internal.
|
||||
|
||||
### 9a. Account shim — provision, resolve, reserved names, cache
|
||||
|
||||
```ts
|
||||
// store-registry.ts:213
|
||||
export function reservedAccount(name: string): string;
|
||||
// store-registry.ts:278
|
||||
export function resetRegistryCache(): void;
|
||||
// store-registry.ts:542
|
||||
export async function resolveAccount(id: string): Promise<VirtualUserRecord | null>;
|
||||
// store-registry.ts:631
|
||||
export async function ensureAccount(id: string): Promise<VirtualUserRecord>;
|
||||
```
|
||||
|
||||
`resolveAccount` — barrier-authoritative O(1) lookup of one account's record in the doc-shim; `ensureAccount` — resolve-or-provision (creates the three scope docs on first sight, concurrency-deduped); `reservedAccount` — NUL-prefixed sentinel namespace for lib-internal accounts; `resetRegistryCache` — test/wallet-switch reset.
|
||||
|
||||
- **NO COUNTERPART, shared-wallet machinery — the whole group.** The target has no directory of identities to resolve or provision: a user's site (three stores + their inboxes) is created once at wallet creation (`engine/verifier/src/site.rs` — the site-creation flow committing the stores and the two store-inbox `AddInboxCap`s at `:128,149`), and "which user" is the session. `ensureAccount`'s provision-on-first-sight has no target analogue and is exactly what `connectedUser` refuses to trigger (`connect.ts:60-65`). All of it disappears with the shim (`docs/migration-guide.md` § 3).
|
||||
- `reservedAccount`'s collision-safety rests on an **ASSUMPTION about a consumer-injected function**: the comment (`store-registry.ts:200-206`) asserts the injected `normalizeId` can never produce a U+0000-prefixed key, but `normalizeId` is injected by the consumer and the lib's own default is a bare `trim()` (`shared-wallet/bootstrap.ts`), which does not strip U+0000. Bound: a consumer id would have to begin with a literal NUL to collide — implausible from any UI, but the property is the consumer's to keep, not the lib's (see Findings F5).
|
||||
|
||||
### 9b. Scope-index resolution
|
||||
|
||||
```ts
|
||||
// REMOVED in `1.0.0-dev.6`
|
||||
// export async function userStoreDoc(id: string, scope: Scope): Promise<Nuri>;
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
### 9c. Inbox ownership predicates
|
||||
|
||||
```ts
|
||||
// store-registry.ts:837
|
||||
export async function isOwnInbox(nuri: Nuri): Promise<boolean>;
|
||||
// store-registry.ts:1286
|
||||
export async function myInboxes(): Promise<Nuri[]>;
|
||||
```
|
||||
|
||||
`isOwnInbox` — the read guard's question (may the current identity READ this inbox); `myInboxes` — the drain list for `connectedUser` (own wallet inbox + one per document this user opened an inbox on).
|
||||
|
||||
- **LEVEL-1 SHAPE for the underlying record, VERIFIED; NO COUNTERPART as API.** Upstream "which inboxes may I read" is answered inside the verifier by the User branch's `AddInboxCap` records (`AddInboxCapV0 { repo_id, overlay, priv_key }`, `engine/repo/src/types.rs:1969-1981`, applied at `verifier.rs:1916-1932`) and consulted implicitly when a message arrives (`verifier.rs:1674-1690`); nothing suggests a JS API for the question at any level. Both functions exist only because the emulation must ANSWER it in JS (the read guard, the drain); they disappear with the emulated inbox read side.
|
||||
|
||||
### 9d. The durable Link register
|
||||
|
||||
```ts
|
||||
// store-registry.ts:1307
|
||||
export async function addLink(cap: ReadCap): Promise<void>;
|
||||
// store-registry.ts:1331
|
||||
export async function readLinks(): Promise<ReadCap[]>;
|
||||
```
|
||||
|
||||
File / read back a received cap on the emulated User branch of the private store — what makes a received cap durable across sessions.
|
||||
|
||||
- **LEVEL-1 SHAPE, model VERIFIED; no JS surface anywhere.** The record emulated is `AddLink { read_cap }` on the User branch — *"so that a user can share with all its device a new Link they received"*, external repos only (`engine/repo/src/types.rs:1934-1950`). Upstream the filing happens inside the verifier while processing the inbox; the future SDK most likely never exposes these as calls (the surface contract's § 12 finding, restated here because these are now internal-only: the one caller is `emulated-verifier/connect.ts` / `inbox.ts`, which is exactly where upstream's verifier sits).
|
||||
- At migration both are deleted; the verifier files and replays.
|
||||
|
||||
## 10. The machinery namespace — `emulated-verifier/machinery.ts`
|
||||
|
||||
```ts
|
||||
// machinery.ts:32
|
||||
export const MACHINERY_NS = "urn:ng-eventually:";
|
||||
// machinery.ts:40
|
||||
export function isMachinerySubject(subject: string | undefined): boolean;
|
||||
```
|
||||
|
||||
The URN prefix every triple the lib writes for itself lives under, and the one predicate read paths use to keep machinery out of consumer data.
|
||||
|
||||
- **NO COUNTERPART, by design — the seam where the emulation pays for having no branches.** Upstream the separation is structural: a compartment is a different BRANCH with its own CRDT and topic (`BranchType`, `engine/repo/src/types.rs:1536-1551`; the Store/User/Overlay branches carry no triples at all, `BranchCrdt::None`, `types.rs:1420`), so machinery cannot appear in a content read and no subject filter exists to write. The namespace, the filter, and the four `shim:*` compartment subjects it protects all disappear at migration.
|
||||
|
||||
## 11. Diagnostics — `shared-wallet/access-log.ts` and `shared-wallet/outbox-log.ts`
|
||||
|
||||
```ts
|
||||
// access-log.ts:25,45,50,63,76,87,99,116
|
||||
export type AccessOp = "READ" | "WRITE";
|
||||
export function setAccessLog(on: boolean): void;
|
||||
export function enabled(): boolean;
|
||||
export function activeIdentity(): string;
|
||||
export function accessLogPrefix(): string;
|
||||
export function logStage(line: string): void;
|
||||
export function shortNuri(nuri: string): string;
|
||||
export function logAccess(op: AccessOp, nuri: string, label: string, extra?: string): void;
|
||||
|
||||
// outbox-log.ts:62
|
||||
export function inspectOutbox(): void;
|
||||
```
|
||||
|
||||
`shared-wallet/access-log.ts` — the off-by-default per-identity access trace for the shared-wallet isolation leak (toggled by `configure({ debugAccessLog })` or `NG_EVENTUALLY_ACCESS_LOG=1`). `shared-wallet/outbox-log.ts` — a read-only count of the real SDK's offline write outbox at session bootstrap, warning when non-empty.
|
||||
|
||||
- `shared-wallet/access-log.ts` — **NO COUNTERPART, shared-wallet machinery**: the leak it makes visible cannot exist in the target (isolation is per-wallet), and the "active identity" it prefixes is the relayed virtual id that disappears with `setCurrentUser`. Deleted at migration.
|
||||
- `shared-wallet/outbox-log.ts` — **NO COUNTERPART as API, but every fact it relies on is level-2 VERIFIED** in the clone: the outbox is persisted through `JsStorageConfig` (`sdk/rust/src/local_broker.rs:89-100`), keyed `ng_peer_last_seq@<peerId>` (`:119,141`) and `ng_outboxes@<peerId>@start` / `@<idx>` with zero-padded `{:05}` indexes (`:163-213`, pad at `:183,210`); the real `outbox_read_function` DRAINS on read (`session_del` per key plus the start key, `:218-224`) — which is why the probe only counts and never touches; and the storage callbacks land in browser `sessionStorage` (`sdk/js/api-web/main.ts:47,57,66`), whose access-denied error string is the one `convert_error` handles (`main.ts:18-22`). The probe reads a private persistence format of the injected SDK — acknowledged in its header as out-of-contract, hence count-only. Deleted with the rest of the trace instrumentation at migration.
|
||||
|
||||
---
|
||||
|
||||
## Findings — defects and migration risks
|
||||
|
||||
**F1 — `surface/ng-proxy.ts` fabricates a `login` member the real SDK does not have.** `ng-proxy.ts:16-22` intercepts `prop === "login"`, but `@ng-org/web` exports no `login` (none in `index.d.ts`, re-verified against the full `declare function` list; no `fn login` in `sdk/js/lib-wasm/src/lib.rs`). On the wrapper `ng.login` is a function; on the real SDK it is `undefined`; calling it throws. This contradicts the module's own "surface stays identical" header and `docs/api-contract.md` § 3's "the proxy adds no member and removes none". No target layer names a `login` — the arm is an unprovenanced assumption. Cheap fix: drop the `login` case (keep `session_start`), or gate it on `typeof ng.login === "function"`.
|
||||
|
||||
**F2 — `emulated-verifier/open-repo.ts`'s stated mechanism is contradicted at the source.** The header (`open-repo.ts:10-12`) asserts an anchored `sparql_query` on a repo absent from `self.repos` "silently returns 0 rows (never a `RepoNotFound`)". Upstream, absence from `self.repos` errors `RepoNotFound` (`engine/verifier/src/request_processor.rs:264,269`), the ReadQuery arm wraps it as `AppResponse::error` (`:1293-1296`), and the web binding rejects the JS promise (`sdk/js/lib-wasm/src/lib.rs:606`). The observed behaviour is real but its cause is one (or both) of: the repo WAS in `self.repos` (a persistent verifier reloads all known repos at `Verifier::load`, `engine/verifier/src/verifier.rs:535-560`) and read 0 rows because unsynced; or the lib's own catch-and-continue layers absorbed the rejection. The fix (open before reading) is correct either way; the diagnosis in the header should not be relied on, and mispredicts non-persistent-verifier behaviour.
|
||||
|
||||
**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`, `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`.
|
||||
|
||||
**Migration-risk flags (shapes that will not travel):**
|
||||
|
||||
- **The `(document, inbox)` pair is persisted as a space-joined string literal** (`"${doc} ${inbox}"`, written `store-registry.ts:1174`, parsed by `split(" ")` at `:1268`). Upstream the record is the typed `AddInboxCapV0 { repo_id, overlay, priv_key }` (`engine/repo/src/types.rs:1969-1981`). Internal-only and replaced wholesale at migration, but it is the one shim record with an ad hoc micro-format a future reader must know to parse.
|
||||
- **`isOwnInbox` / `myInboxes`** encode questions the target answers only inside the verifier (§ 9c) — any new internal caller added to them deepens a dependency that has no successor API; keep callers to the read guard and the connection drain.
|
||||
- **The sync barrier is empirical** (§ 6): "TabInfo before the first State" and "held subscription keeps the repo open" are pinned by the in-repo e2e probe, not by any upstream statement. If upstream changes push ordering or repo retention, `emulated-verifier/open-repo.ts` is the module that breaks first; the probe is the tripwire.
|
||||
- **`ensureAccount`'s provision-on-first-sight** (§ 9a) is a behaviour with no target image; `emulated-verifier/connect.ts` already refuses to trigger it. Any future internal path that provisions as a side effect of resolving would be teaching the emulation something the target contradicts (creation is an explicit act at wallet/site creation, `engine/verifier/src/site.rs`).
|
||||
|
||||
---
|
||||
|
||||
## 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`, `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`, `isOwnInbox`, `myInboxes`, `addLink`, `readLinks`).
|
||||
|
||||
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.
|
||||
+58
-23
@@ -14,13 +14,37 @@ has no clear target image, that is a drift signal (see
|
||||
## Checklist
|
||||
|
||||
### 1. Emulated ReadCaps → real capabilities
|
||||
Translate the per-document `CapRegistry` (`caps.ts`) into real NextGraph caps: the
|
||||
broker/verifier enforces them, and `useShape` already returns only authorized
|
||||
documents. The directed `grantRead(doc, granteeId)` maps to a native per-document
|
||||
ReadCap issued to that identity. The read filter (`read-filter.ts`) and the write
|
||||
guard (`ng-proxy.ts` `sparql_update` override) are then dead code — remove them. The
|
||||
access unit is already the document (`@graph`), matching the native per-repo cap
|
||||
model, so this is a data step, not a reshape.
|
||||
The shape is already the target's (the cap-surface work): a `ReadCap` is the document's key, a
|
||||
each identity holds a set of caps, and there is no read-ACL anywhere. So
|
||||
this step swaps the *emulated* key for the real one, not the model:
|
||||
|
||||
- `emulated-verifier/caps.ts`'s per-identity record becomes the verifier's own local user storage —
|
||||
it was always the cache, not the register. The two durable registers we emulate
|
||||
(`readCap` on the store's Store branch, `link` on its User branch) become the real
|
||||
`AddRepo` / `AddLink` commits. Remove the emulation; the wallet and the branches
|
||||
already hold them.
|
||||
- the stand-in cap value — the constant `OK` (`STAND_IN_CAP`,
|
||||
`emulated-verifier/caps.ts`) — becomes the real
|
||||
`r:{base64url(serde_bare(ObjectRef))}`. It is **one function** (`mintCap`, in that
|
||||
same module since the source layout was reorganised — this said `nuri.ts` until
|
||||
2026-08-10), because
|
||||
every path now READS a stored cap instead of recomputing one. `hasReadCap` /
|
||||
`targetOf` stay meaningful: the `r:` discriminant is upstream grammar, not ours.
|
||||
- `inbox.share(doc, toUser)` becomes the native sealed delivery (whatever the SDK ends up naming it — see the note below
|
||||
and `ContactDetails.read_cap`), and `inbox.read`'s inline absorption becomes the
|
||||
recipient's own verifier applying queued messages. **The consumer's call does not
|
||||
change.**
|
||||
- `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
|
||||
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
|
||||
cap-enforcement batch, not here.
|
||||
|
||||
The access unit is already the document (`@graph`), matching the native per-repo cap
|
||||
model, so this is a key-material step, not a reshape.
|
||||
|
||||
### 2. Place documents in real native stores
|
||||
Today `docCreate(..., undefined)` writes every document into the shared wallet's
|
||||
@@ -28,7 +52,7 @@ private store, and the `public|protected|private` scope is a logical label
|
||||
in the shim (see the two-axes section in [`simulation.md`](./simulation.md)).
|
||||
|
||||
- `doc_create` cannot target a non-private native store today — verified:
|
||||
`StoreRepo` is not JS-constructible from the SDK, so there is no way to pass
|
||||
`StoreRepo` is not constructible from the WEB build of the SDK, so there is no way to pass
|
||||
a public/protected store as the create destination (`docCreate`'s trailing
|
||||
`store` arg is left `undefined` → private store). The private store works only
|
||||
because it opens without `RepoNotFound`.
|
||||
@@ -36,10 +60,10 @@ in the shim (see the two-axes section in [`simulation.md`](./simulation.md)).
|
||||
`getNativeStore(scope)`-style resolver returning the real store to pass as the
|
||||
`docCreate` destination, so the logical scope label becomes a real store
|
||||
placement. (No such helper exists yet — it is blocked on the SDK gap above.)
|
||||
- At that point `store-registry.ts` maps `(account, scope)` to the user's real
|
||||
- At that point `shared-wallet/account-registry.ts` maps `(account, scope)` to the user's real
|
||||
store NURI instead of a document in the shared wallet; the per-scope index
|
||||
document (the store-container emulation) is replaced by the store itself. The
|
||||
surface facing the consumer application (`createEntityDoc`, `listEntityDocs`,
|
||||
surface facing the consumer application (`createEntityDoc`, `listMyEntityDocs`,
|
||||
resolvers) is designed to survive that swap unchanged.
|
||||
|
||||
### 3. Drop the resolver / shim
|
||||
@@ -47,42 +71,53 @@ The `sharedWalletShim` (account → 3 scope-document NURIs, held in a subscribab
|
||||
doc-shim reached via a write-once pointer in the store-root — see
|
||||
[`nextgraph-current-state.md`](./nextgraph-current-state.md) § *The pointer → doc-shim
|
||||
indirection*) has no target equivalent — the target has no central directory. Remove
|
||||
it entirely: `store-registry.ts`, `configureStoreRegistry`, the pointer + doc-shim
|
||||
it entirely: `shared-wallet/account-registry.ts`, `configureStoreRegistry`, the pointer + doc-shim
|
||||
resolution, and the `pointerGuard` dep. Cross-wallet reads replace the fan-out;
|
||||
per-user wallets replace the shared one.
|
||||
|
||||
### 4. Real inbox → drop the in-lib read emulation
|
||||
Replace the emulated `inbox.ts` deposit (`docs.sparqlUpdate` into a shared-wallet
|
||||
document) with the native `inbox_post_link` (proposed/future). On the read side the
|
||||
document) with the native sealed deposit, once one is exposed to JS. **Its name and shape are NOT known**: no inbox method exists in `@ng-org/web`, the verifier has no `InboxPost` arm, and `inbox_post_link` is OUR proposed name (`fork-inbox-fallback.md`), not an announced API. On the read side the
|
||||
recipient's own verifier unseals each queued sealed message and applies it inline
|
||||
when it processes its inbox — there is no separate curator to build; the in-lib read
|
||||
emulation simply goes away (see the deferred global-index note in the top-level
|
||||
README and [`decisions/discovery-model.md`](./decisions/discovery-model.md)). The
|
||||
single global index replaces the cross-account fan-out.
|
||||
emulation simply goes away. *(There is no global index to replace the cross-account fan-out: both were removed on 2026-07-30 — you cannot discover in NextGraph, you follow links.)*
|
||||
|
||||
### 5. Retire the identity store → real per-user login
|
||||
Remove `accounts.ts` (the `IdentityStore` that persists the identity id in
|
||||
Remove `shared-wallet/virtualUsers.ts` (the `IdentityStore` that persists the identity id in
|
||||
`localStorage`) and the app-level "Connexion" screen. The technical broker gate
|
||||
becomes the real per-user login
|
||||
(see [`decisions/shared-wallet-login-flow.md`](./decisions/shared-wallet-login-flow.md)).
|
||||
The flow shape ("broker redirect → app") does not change.
|
||||
|
||||
### 6. Drop the isolation scaffold
|
||||
`isolation.ts` (application-visibility scaffold) disappears against a
|
||||
different piece of infra than the caps: real per-account wallets, and the
|
||||
relationship concept the consumer application owns. Distinct axis from ReadCaps —
|
||||
remove independently.
|
||||
### 6. ~~Drop the isolation scaffold~~ — already gone
|
||||
`isolation.ts` (the old application-visibility filter) was deleted from the library;
|
||||
nothing remains to remove at migration. Kept as a numbered step so the following
|
||||
numbers stay stable across references.
|
||||
|
||||
### 7. Remove the build alias — the client becomes the real SDK
|
||||
The consumer application imports `@ng-org/web` / `@ng-org/orm` resolved to this lib
|
||||
via a build alias during the polyfill period. Removing the alias makes those imports
|
||||
resolve to the real SDK — the `ng`/`useShape`/`inbox` surface is SDK-identical, so
|
||||
no consumer code changes. The one non-SDK call — `configure(...)` /
|
||||
`@ng-eventually/client/polyfill` — is deleted. The lib itself disappears.
|
||||
the POLYFILL-ERA block of `@ng-eventually/polyfill` — is deleted. The lib itself disappears.
|
||||
|
||||
## The one break already taken: `declareConnections`
|
||||
|
||||
The cap-surface work broke the consumer once, deliberately and early, so that migration would not.
|
||||
The old surface was an ACL held in memory, which forced the consumer to re-declare
|
||||
every grant on every session (`declareConnections`). That call **disappears**: with
|
||||
delivered caps the grant moves to the moment a connection is *accepted* — one
|
||||
`inbox.share(doc, toUser)` per document shared — and it persists, because
|
||||
the delivery lives in the recipient's inbox rather than in a map that empties at
|
||||
reload. There is no analogue of `protectedDocsOf` + the re-derivation loop.
|
||||
|
||||
This is a consumer **re-architecture**, not an API swap, and it is the price of
|
||||
being coded against a model that will exist. Nothing else about the migration below
|
||||
touches consumer code.
|
||||
|
||||
## What does not change
|
||||
|
||||
The consumer application's code. Shapes, screens, the *acts* of granting
|
||||
The consumer application's code. Shapes, screens, the *acts* of sharing
|
||||
access, entity→scope mapping, the relationship graph — all injected, all untouched.
|
||||
Migration is entirely inside this library plus removing the alias + the bootstrap
|
||||
call. That asymmetry — a mature SDK face outward, all compensation inward — is the
|
||||
|
||||
+370
-45
@@ -1,6 +1,6 @@
|
||||
# Current-state NextGraph — what the SDK/broker do and do NOT expose
|
||||
|
||||
**Owner:** this library. `@ng-eventually/client` exists because the *current*
|
||||
**Owner:** this library. `@ng-eventually/polyfill` exists because the *current*
|
||||
NextGraph JS SDK is immature. This file is the authoritative reference on what
|
||||
today's SDK/broker actually give us — the ground truth every polyfill in this
|
||||
lib compensates for. Read [`simulation.md`](./simulation.md) for how we emulate
|
||||
@@ -22,14 +22,24 @@ Where the ground truth lives, so future re-verification is cheap:
|
||||
dispatch (the truth on what is actually *processed*).
|
||||
- `engine/net/src/types.rs` — inbox types (`InboxPost`, `InboxMsg`, `InboxMsgContent`).
|
||||
- `engine/verifier/src/inbox_processor.rs` — inbox message handling.
|
||||
- `engine/verifier/src/verifier.rs:1423` — the `OpenRepo` TODO (cross-wallet read).
|
||||
- `engine/verifier/src/verifier.rs:2237` — `load_repo_from_read_cap`, the one path that
|
||||
brings a repo in FROM a cap (`pub(crate)`, see § *Capability / ReadCap granularity*).
|
||||
- `engine/verifier/src/verifier.rs:1423` — the `OpenRepo` TODO. It is **not** about
|
||||
loading an unheld repo: it sits inside `open_branch_`, past
|
||||
`self.repos.get_mut(repo_id).ok_or(RepoNotFound)?` (`:1331`), so the repo is already
|
||||
held by the time that line runs. What is missing is the broker-side `OpenRepo`
|
||||
request, worked around with a pin.
|
||||
- `engine/repo/src/types.rs` — `RootBranchV0.store: StoreOverlay` (repo → its store).
|
||||
|
||||
## The 5 store types
|
||||
|
||||
Every wallet has the **3 default stores** out of the box (session fields
|
||||
`private_store_id`, `protected_store_id`, `public_store_id`). Group and Dialog
|
||||
are created on demand.
|
||||
The **3 default stores** belong to a **user**, not to the wallet. A wallet holds
|
||||
`sites: HashMap<String, SiteV0>` (`engine/wallet/src/types.rs:456`), and it is `SiteV0`
|
||||
that carries `public` / `protected` / `private` (`engine/verifier/src/site.rs:31-37`) —
|
||||
one wallet can hold several, which is exactly why "wallet" is the wrong unit to reason
|
||||
in (see `docs/readcap-and-nuri-model.md` §4quinquies, *Nomenclature first*). A session exposes the three as
|
||||
`private_store_id`, `protected_store_id`, `public_store_id` — those are the connected
|
||||
USER's. Group and Dialog are created on demand.
|
||||
|
||||
| Store | Read | Write | Creation |
|
||||
|---|---|---|---|
|
||||
@@ -76,15 +86,17 @@ users/quorum (write/permissions), **not** read-cap possession. (Repos of a
|
||||
> Consequence for this lib's emulation (see [`simulation.md`](./simulation.md)):
|
||||
> the read access unit is the repo = each item's `@graph` — a per-document
|
||||
> filter, never per-store and never per-item. This is exactly what
|
||||
> `caps.ts` (`CapRegistry`) and `read-filter.ts` model: no store-level
|
||||
> `emulated-verifier/caps.ts` (`CapRegistry`) and `emulated-verifier/read-filter.ts` model: no store-level
|
||||
> inheritance, purely per-document caps. In a mono-store layout (all items in one
|
||||
> repo) the filter is therefore all-or-nothing on that document — which *is* the
|
||||
> native behaviour, and why fine-grained isolation requires one document per
|
||||
> entity. Read isolation is cryptographic in the target: with no cap for a repo, a
|
||||
> union / reactive read returns empty (the repo is never decrypted), while a
|
||||
> targeted read of an unheld repo returns `RepoNotFound`. There is no
|
||||
> cap-introspection API — the polyfill's `canRead` / `governsRead` are
|
||||
> emulation-only, with no NextGraph API behind them.
|
||||
> cap-introspection API, and there is nothing to introspect: reading is key
|
||||
> possession, so the polyfill asks the only question the model admits —
|
||||
> `capFor(doc)`, "do I hold it?". Its *implementation* is emulation-only; its shape
|
||||
> is the target's.
|
||||
|
||||
### Store ↔ document confusion (recurring)
|
||||
|
||||
@@ -96,17 +108,78 @@ stores.
|
||||
|
||||
## Capability sharing / NURI
|
||||
|
||||
**What a NURI transports, and the two acts that cover every use of it, are in
|
||||
[`readcap-and-nuri-model.md`](./readcap-and-nuri-model.md) §4sexies** — including why a
|
||||
key-less reference is the ordinary case rather than a degenerate one, and why nothing is
|
||||
checked at access time. The analysis of what exists vs what is merely declared is in
|
||||
[`document-links.md`](./document-links.md).
|
||||
|
||||
Sharing transmits a **NURI** embedding the crypto capability (read and/or write).
|
||||
No central ACL: holding the NURI *is* the right. *"adding permissions can be done
|
||||
offline"*; *"removing permissions … requires a SyncSignature"* (synchronous).
|
||||
|
||||
## Inbox
|
||||
|
||||
Every document has a native inbox. A non-editor can deposit a link (DID
|
||||
cap) into it without being invited as an editor; the owner moderates. NURI:
|
||||
`did:ng:d:<inbox_id>`. Content: the `InboxMsgContent` enum (`ContactDetails`,
|
||||
**Only two repos have an inbox today: a user's public and protected STORES.** Not
|
||||
documents, and not the private store. `new_store_default` attaches one solely `if
|
||||
!private` (`engine/verifier/src/verifier.rs:2994`), and `doc_create` goes through
|
||||
`new_repo_default` (`verifier.rs:3004`, called at `request_processor.rs:689`) →
|
||||
`Store::create_repo_default` (`engine/repo/src/store.rs:264`) →
|
||||
`create_repo_with_keys` (`store.rs:284`), which builds the `Repo` with `inbox: None`
|
||||
(`store.rs:691`). The only
|
||||
`AddInboxCap` commits in the whole engine are the two in `engine/verifier/src/site.rs:128,149`
|
||||
— one for the public store repo, one for the protected one.
|
||||
|
||||
*(Citation corrected 2026-08-10. This pointed at `engine/repo/src/repo.rs:574`, which is
|
||||
inside `Repo::new_with_member` (`repo.rs:543`) — a constructor no production path
|
||||
reaches: its callers are `Repo::new_with_perms`, gated `#[cfg(any(test, feature =
|
||||
"testing"))]` (`repo.rs:186-192`), and `#[cfg(test)]` blocks in `branch.rs:387,490` and
|
||||
`commit.rs:1659,1849,1919`. The claim itself was right; it was being proved by a test
|
||||
fixture.)*
|
||||
|
||||
**But the engine SUPPORTS an inbox on any repo — "does not" and "cannot" are different
|
||||
statements.** `inbox: Option<PrivKey>` is a field of EVERY `Repo`
|
||||
(`engine/repo/src/repo.rs:126`), not of a store structure. `AddInboxCapV0` is keyed by
|
||||
`repo_id` (`engine/repo/src/types.rs:1973`) — *"Repo the Inbox is opened for"*. And
|
||||
`update_inbox_cap_v0` applies it via `self.repos.get_mut(repo_id)` with **no `is_store`
|
||||
check of any kind** (`engine/verifier/src/verifier.rs:1920`). It is generic by
|
||||
construction, and available at any time: `AddInboxCap` is a User-branch commit
|
||||
(`engine/repo/src/commit.rs:1043-1050`) whose type documents the late case — *"DEPS to
|
||||
the previous AddInboxCap commit(s) if it is an update"*.
|
||||
|
||||
So a per-document inbox is **not an anticipation**: it is an engine capability that no
|
||||
code path exercises automatically and that no level-2 or level-3 API exposes. This lib
|
||||
implements it aligned on the engine's model.
|
||||
|
||||
**An inbox address is TRANSMITTED, never published — and nothing in the engine says who
|
||||
may open one.** Two facts that decide more than they look:
|
||||
|
||||
- `inboxes: HashMap<PubKey, RepoId>` is a field of the **Verifier**
|
||||
(`engine/verifier/src/verifier.rs:105`), rebuilt empty on each construction (`:520`,
|
||||
`:2820`). The inbox → repo association is **local to a session**, not a published
|
||||
fact. A depositor learns a pubkey because it was **sent** to them — in a
|
||||
`ContactDetails` message (`contact.inbox`) or through a profile QR code; the reply
|
||||
path reads its own `repo.inbox` to include it (`request_processor.rs:736-750`).
|
||||
- There is therefore **no engine guard on who opens an inbox for a repo**.
|
||||
`AddInboxCap` lands on the committer's OWN User branch, so anyone may write one naming
|
||||
anyone's repo. It simply reaches nobody: no one was told that pubkey means that
|
||||
document.
|
||||
|
||||
*Consequence for this lib, and it is a real divergence:* we **publish** the address on
|
||||
the document (its Header branch) because that is the only way a third party can find it
|
||||
in an emulation with no message channel. That creates a vector the engine does not have
|
||||
— whoever can write the document can redirect its deposits — so `openDocumentInbox`
|
||||
guards on ownership. That guard compensates OUR design; it does not mirror an upstream
|
||||
rule. Do not cite it as one.
|
||||
|
||||
A non-editor can deposit into an inbox without being invited as an editor; the owner
|
||||
moderates. NURI: `did:ng:d:<inbox_id>`. Content: the `InboxMsgContent` enum (`ContactDetails`,
|
||||
`DialogRequest`, `Link`, `Patch`, `ServiceRequest`, `ExtRequest`,
|
||||
`RemoteQuery`, `SocialQuery`…). Messages are sealed (`crypto_box::seal`) to
|
||||
`RemoteQuery`, `SocialQuery`…, `engine/net/src/types.rs:4249-4261`). Note what `Link`
|
||||
is: a **unit variant, carrying nothing** — not a link, not a cap, just a discriminant.
|
||||
Reading it as "the inbox can deliver a read capability" is the trap this file exists to
|
||||
prevent; see the *Consequence for this lib* below, which says the same thing from the
|
||||
other end. Messages are sealed (`crypto_box::seal`) to
|
||||
the inbox pubkey, so only the owner decrypts. The `from` field is optional, so an
|
||||
anonymous sender is possible. This is the "identified if known, anonymous
|
||||
otherwise" behaviour native to the protocol.
|
||||
@@ -123,8 +196,11 @@ it processes its inbox — there is no separate curator or materialization servi
|
||||
`QrCodeProfile(Import)`, `Header`, `Create`, `FilePut`). Sending an `InboxPost`
|
||||
triggers nothing.
|
||||
- Building an `InboxPost` requires crypto sealing on the Rust side; no wasm
|
||||
helper exposes it. A high-level `inbox_post_link` is a proposed/future API, not
|
||||
yet present.
|
||||
helper exposes it, and **no `inbox` method exists in `@ng-org/web` at all**.
|
||||
*(`inbox_post_link`, named across this repo's docs, is OUR proposed name from
|
||||
[`fork-inbox-fallback.md`](./fork-inbox-fallback.md) — grep `nextgraph-rs` and it
|
||||
is nowhere. Nothing is announced about the eventual JS surface for inboxes: its
|
||||
name and shape are unknown, not merely unimplemented.)*
|
||||
- Inbox deposit is only triggered internally by `QrCodeProfileImport`
|
||||
(`post_to_inbox(new_contact_details)`) and `social_query_start` (contact
|
||||
propagation via inbox).
|
||||
@@ -137,6 +213,32 @@ A related exposed primitive: `social_query_start` (a federated query via inbox u
|
||||
`degree` hops) exists but is limited to contacts — it does not cover an anonymous
|
||||
notification to a non-connected host.
|
||||
|
||||
### Delivering a ReadCap through the inbox — the field exists, the path does NOT — VERIFIED
|
||||
|
||||
The `ContactDetails` inbox message carries `read_cap: Option<ReadCap>`, commented
|
||||
*"optional readcap on the profile, if user wants to share the content of profile"*
|
||||
(`engine/net/src/types.rs`). Nothing behind that field is implemented:
|
||||
|
||||
- **Building it panics.** `InboxPost::new_contact_details(…, with_readcap: bool, …)`
|
||||
(`engine/net/src/types.rs`) fills `read_cap` with `unimplemented!()` when
|
||||
`with_readcap` is true, and `None` otherwise. Asking for a cap in the message is a
|
||||
panic, not a feature.
|
||||
- **Nobody asks for one.** Its ONLY caller is the `QrCodeProfileImport` path in
|
||||
`engine/verifier/src/request_processor.rs`
|
||||
(`post_to_inbox(InboxPost::new_contact_details(…))`), which passes `with_readcap =
|
||||
false`. No message ever carries a cap.
|
||||
- **The receiver discards it.** The `InboxMsgContent::ContactDetails(details)` arm of
|
||||
`engine/verifier/src/inbox_processor.rs` reads `details.profile`, `details.name` and
|
||||
`details.email` to build a `social:contact` document — it **never reads
|
||||
`details.read_cap`**. Even a hand-crafted message carrying a cap would be dropped.
|
||||
|
||||
**Consequence for this lib:** there is no native channel to HAND a key to somebody. The
|
||||
inbox transports an identity/profile pointer, not a read capability. Combined with
|
||||
§ *The inbox is not usable from the JS SDK* (no `InboxPost` arm in the request processor
|
||||
at all), cap delivery must be emulated end to end: the polyfill's emulated inbox and its
|
||||
`CapRegistry` are not a shortcut around an existing mechanism, they stand in for a
|
||||
mechanism that does not exist.
|
||||
|
||||
## The query capability — ONE local store, named graphs, union queries
|
||||
|
||||
The single fact that makes read-time *listing* possible on the shared wallet, and
|
||||
@@ -199,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`. `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
|
||||
@@ -213,7 +315,8 @@ with the whole wallet, which is why the read path is per-doc anchored: the ancho
|
||||
read makes a non-empty wallet irrelevant. At the real multi-store
|
||||
migration this is unchanged (the anchored read is native); only bringing a repo into
|
||||
the session changes: opening a real per-user store repo by cap becomes a native
|
||||
broker sync (the `OpenRepo` TODO at `verifier.rs:1423`). Opening still requires the
|
||||
broker sync, through `load_repo_from_read_cap` (`verifier.rs:2237`) — not through the
|
||||
`OpenRepo` TODO at `:1423`, which concerns a repo already held. Opening still requires the
|
||||
repo's NURI + ReadCap — there is no store-level read inheritance (see
|
||||
§ Capability / ReadCap granularity).
|
||||
|
||||
@@ -230,11 +333,26 @@ has both**:
|
||||
- **Subscribable with a sync BARRIER.** `doc_subscribe(nuri)` delivers `TabInfo` then
|
||||
an initial **`State`** (`verifier.rs:470`/`:476`); that first `State` is the sync
|
||||
barrier — **after it, presence is guaranteed and absence is definitive** (pinned
|
||||
empirically by CONTRACT 3 in `packages/client/e2e/`). But this barrier exists only
|
||||
empirically by CONTRACT 3 in `packages/polyfill/e2e/`). But this barrier exists only
|
||||
for a repo `doc_subscribe` can open, i.e. a `did:ng:o:<RepoID>` repo. A **store-root
|
||||
has no first-`State` barrier**: an anchored read on it can return 0 rows during
|
||||
sync-lag with no signal distinguishing "still syncing" from "genuinely empty".
|
||||
|
||||
> **`doc_fetch_repo_subscribe` / `doc_fetch_private_subscribe` are NOT alternatives to
|
||||
> `doc_subscribe`** — checked 2026-08-03, because they look like ready-made
|
||||
> "open a repo" calls and they are not. Neither performs any I/O: each **builds an
|
||||
> `AppRequest` and returns it serialized** (`sdk/js/lib-wasm/src/lib.rs:1890`, `:1900`),
|
||||
> with no `session_id` and no callback. `doc_subscribe` builds the *same* request
|
||||
> (`AppRequest::doc_fetch_repo_subscribe`, `engine/net/src/app_protocol.rs:930` →
|
||||
> `Fetch(Subscribe)`), then adds the session id and runs it through
|
||||
> `app_request_stream_` (`lib.rs:1921-1923`). They exist for a caller that wants to
|
||||
> construct the request and dispatch it itself. So `ensureRepoOpen`'s
|
||||
> `doc_subscribe` + wait-for-first-`State` is not duplicating an available call — using
|
||||
> them instead would mean re-implementing what `doc_subscribe` already does. The
|
||||
> difference in `doc_fetch_private_subscribe` is only its target
|
||||
> (`NuriV0::new_private_store_target()`, the private store-root), which changes nothing
|
||||
> about the barrier: a store-root still has none.
|
||||
|
||||
These two are **mutually exclusive**: the guessable target (store-root) is not
|
||||
barrier-authoritative, and the barrier-authoritative target (`o:` repo) is not
|
||||
guessable. **Consequence:** you cannot build a lookup table that is BOTH reachable
|
||||
@@ -244,14 +362,14 @@ account map fell into (see next section).
|
||||
|
||||
### The pointer → doc-shim indirection (how the polyfill shim resolves accounts)
|
||||
|
||||
`store-registry.ts` keeps a map `identifier → {docPublic, docProtected, docPrivate}`
|
||||
`shared-wallet/account-registry.ts` keeps a map `identifier → {docPublic, docProtected, docPrivate}`
|
||||
(the "shim", the account→document trust root). It must be reachable by a fresh
|
||||
reconnecting session (findable) AND authoritative on a cold read (so a fresh page
|
||||
does not mistake sync-lag for "account absent" and PROVISION a fork). Since no single
|
||||
document is both (previous section), the shim uses an **indirection**:
|
||||
|
||||
1. **doc-shim** — a `doc_create`d graph document (`did:ng:o:...`, hence a first-`State`
|
||||
barrier). **All `AccountRecord`s live inside it.** Because it is subscribable, an
|
||||
barrier). **All `VirtualUserRecord`s live inside it.** Because it is subscribable, an
|
||||
anchored read behind its `ensureRepoOpen` barrier is **authoritative**: a cold 0
|
||||
means the account is genuinely absent.
|
||||
2. **pointer** — a single well-known, **write-once** triple in the store-root graph,
|
||||
@@ -327,10 +445,16 @@ Listing must go through a one-shot union `sparql_query` instead — see
|
||||
installed version) **does NOT expose**: Group/Dialog store creation; capability
|
||||
sharing (a NURI with rights); permission manipulation; inbox deposit/read.
|
||||
|
||||
Available JS methods: `doc_create`, `doc_subscribe`, `sparql_query`,
|
||||
The JS methods this lib USES: `doc_create`, `doc_subscribe`, `sparql_query`,
|
||||
`sparql_update`, `orm_start_graph`, `orm_start_discrete`, `graph_orm_update`,
|
||||
`discrete_orm_update`, `file_get`, `app_request_stream`. The docs announce *"An
|
||||
API will be provided for permission manipulation"* (no date).
|
||||
`discrete_orm_update`, `file_get`, `app_request_stream`. That is a working subset,
|
||||
**not** the surface: `NGModule` exports **77** (`@ng-org/web@0.1.2-alpha.13`,
|
||||
`dist/index.d.ts:140-268`), including `app_request`, `session_stop`,
|
||||
`disconnections_subscribe`, `social_query_start`, `upload_start`/`upload_chunk`/
|
||||
`upload_done`, and the whole `wallet_*` family. Read "not in the list above" as "we do
|
||||
not call it", never as "it does not exist" — several sections of this very file discuss
|
||||
methods absent from that subset. The docs announce *"An API will be provided for
|
||||
permission manipulation"* (no date).
|
||||
|
||||
## Integration & deployment model
|
||||
|
||||
@@ -406,30 +530,37 @@ methods: `doc_subscribe`, `orm_start_graph`, `orm_start_discrete`, `file_get`,
|
||||
(`pnpm webfilebuild`). First boot is **interactive** (admin-wallet invitation
|
||||
link). Official Dockerfiles are **broken**.
|
||||
|
||||
## Apps & services: mono-user, no global data
|
||||
## Apps & services: shared app data goes through a hardcoded app store (section rewritten 2026-08-03)
|
||||
|
||||
NextGraph's app/service execution model — important because it **invalidates**
|
||||
the idea of "a service with its own wallet sharing global data".
|
||||
NextGraph's app/service execution model, and the answer to "can an application hold data common to all its users".
|
||||
|
||||
- **Apps AND services are mono-user.** They see only **what the user makes
|
||||
available** to them. There is **no global data** natively, and no central
|
||||
service holding shared data.
|
||||
- **Local settings document.** Every app — even a singleton — and every service
|
||||
has a **settings document** the user configures it through.
|
||||
- **Multi-instance apps.** A **non-singleton** app can be **instantiated several
|
||||
times** (e.g. a text editor, once per open file).
|
||||
- **Singleton apps.** Also **mono-user**, but **bound to a particular user (the
|
||||
developer)**. A singleton app **can hold a global document**, administered by
|
||||
that user.
|
||||
> **Provenance — two layers, do not mix them.** What the **engine** contains is verified below and is vocabulary only. What the **model will be** was stated by the NextGraph developer on 2026-08-03 and is **not implemented**: treat it as the target's declared direction, not as something the clone can confirm. Per [`../README.md`](../README.md)'s design principle, never infer the target's shape from the source's current state — an absent implementation says nothing about the intended one. The previous version of this section drew exactly that inference and concluded the opposite of what the developer states; it has been replaced.
|
||||
|
||||
**Consequence for a "global document" (e.g. a discovery index):** the only path
|
||||
glimpsed is a singleton app whose global document is administered by the
|
||||
developer-user — though this is not implemented and not guaranteed (simpler
|
||||
paths may exist; to explore later). The model that does exist is this
|
||||
singleton-app one; a dedicated service with its own wallet sharing a
|
||||
freely-readable index is not a NextGraph shape (a service is mono-user, no global
|
||||
data). This is why a global-index package is deferred in this lib (see the top-level
|
||||
README).
|
||||
**What the engine actually has — types, no behaviour (verified 2026-08-03):**
|
||||
|
||||
- `AppManifestV0` (`engine/wallet/src/permissions.rs:113`) carries `nuri`, `origin` (webapps), `singleton: bool`, `access_requests`, `installs` (Viewer / Editor / ReadService / WriteService / Model, keyed by PrimaryClass), `dependencies`, and presentation fields.
|
||||
- The JS surface exists: `init(callback, singleton, access_requests)` (`sdk/js/web/src/index.ts:51`) relays `singleton` to the wallet origin by `postMessage`. Every example passes `true`.
|
||||
- **Nothing consumes it.** The `permissions` module is declared by `engine/wallet/src/lib.rs:19` and imported by no other crate; `AppManifest` is constructed nowhere; no code reads `singleton`; the surrounding `AccessRequest` / `AccessGrant` machinery is in the same state. There is no app runtime, no app store, no global-document type.
|
||||
- The field's doc comment reads `/// cannot create Documents?` — with the question mark, in the source. It is an open design note, and the developer's statement below settles it the other way. Do not treat it as the semantics.
|
||||
- **A second, published gloss of the same flag disagrees with that doc comment, and it is the one that matches the developer's statement.** `sdk/js/web/README.md:90,108` annotates the argument as *"will your app create many docs in the system, or should it be launched as a unique instance"* — i.e. `singleton` is about **instance multiplicity**, not about being forbidden to create documents. That is consistent with "a singleton app can also manage ordinary per-user documents" below, and it is the reading to carry. Both README examples pass `true`.
|
||||
- Unrelated homonyms, so a grep does not mislead: singleton *commits* (`engine/repo/`), the broker singleton (`engine/net/src/broker.rs`), Oxigraph's `empty_singleton` (SPARQL optimiser).
|
||||
|
||||
**The declared model (NextGraph developer, 2026-08-03 — not implemented):**
|
||||
|
||||
- A singleton app can **also** manage ordinary per-user documents, i.e. cover what a non-singleton app does. When both modes are needed, declaring one app as singleton is enough — there is no need for two apps.
|
||||
- Centralized data for an application takes the form of a **document, or a store, shared by all its users and hardcoded in the app**.
|
||||
- The **app's developer holds the write rights** on the app's documents and stores, and can **delegate** them.
|
||||
- Delegation is **never to all users**. User contributions reach app-owned data **through an inbox** — this is NextGraph's general model, in which nothing is freely writable by everyone.
|
||||
|
||||
**Reading of the last point, since it decides the shape of any index:** an app-owned index is not a place users write to. It is a document they can read (its NURI being hardcoded) and **deposit into**, with an authority derived from the developer materializing the deposits — the same deposit-then-materialize shape the inbox already imposes elsewhere, moved up to the app level.
|
||||
|
||||
**Open questions to put to the developer before designing on this:**
|
||||
|
||||
- What exactly is hardcoded — the store's or document's NURI, and does that carry the read capability?
|
||||
- How is write delegation transmitted, and is it revocable?
|
||||
- Who processes the app store's inbox: an instance running with the developer's rights, a service, something else? A deposit nobody materializes is not an index.
|
||||
|
||||
**Bearing on [`decisions/discovery-model.md`](decisions/discovery-model.md):** that ADR's superseding block leans in part on the singleton-app path being "not implemented, uncertain". The path is still not implemented, but it is no longer uncertain in direction — the developer names it as *the* way to hold data common to all users. That does not reinstate discovery: the "you cannot discover, you can only follow links" verdict rests on its own footing (the PO, 2026-07-30). It does mean the *singleton-app* half of that reasoning must be re-put rather than cited as closed.
|
||||
|
||||
## Third-party wallet auto-import constraint
|
||||
|
||||
@@ -471,6 +602,117 @@ redirect afterwards. This lib's identity store sidesteps all of it — the ident
|
||||
id is set at wallet-import time and relayed to the lib, without a separate login;
|
||||
see the identity store in [`simulation.md`](./simulation.md).
|
||||
|
||||
## Authorship, existence, outer overlay, `Ext` (section added 2026-07-27)
|
||||
|
||||
Four capability facts about the current core, verified in `nextgraph-rs`. They bear on
|
||||
what can be BUILT on top (can we deliver a key? can we tell whether a document exists?
|
||||
can we attribute a write?) — they are not a security assessment. Each carries its
|
||||
epistemic status; do not upgrade an INFERRED item without new evidence.
|
||||
|
||||
### Author-signature verification is never called at runtime — VERIFIED
|
||||
|
||||
`Commit::verify` (`engine/repo/src/commit.rs`) chains `verify_sig` → `verify_perm` →
|
||||
`verify_full_object_refs_of_branch_at_commit`. Its only callers in the whole tree are
|
||||
inside `#[cfg(test)] mod test` blocks (`engine/repo/src/commit.rs`,
|
||||
`engine/repo/src/branch.rs`); `verify_sig` and `verify_perm` have no other caller. The
|
||||
verifier's commit path calls a **different** `verify`:
|
||||
`CommitBodyV0::<Body>::verify(commit, self, branch_id, repo_id, store)` in
|
||||
`engine/verifier/src/verifier.rs` — the `CommitVerifier` trait, which APPLIES a body
|
||||
(mutating verifier state); it is not a signature check.
|
||||
|
||||
Even if it were called it could not succeed. `verify_sig` resolves the author through
|
||||
`Repo::member_pubkey` → `Repo.members`, and every `Repo` the verifier builds at runtime
|
||||
sets `members: HashMap::new()` — `engine/verifier/src/user_storage/repo.rs` (with a
|
||||
literal `//TODO: members`) and `engine/verifier/src/commits/mod.rs`. Only
|
||||
`Repo::new_with_member` ever populates a member, and it is called only from tests. An
|
||||
empty table makes `member_pubkey` return `NotFound` →
|
||||
`CommitVerifyError::PermissionDenied`.
|
||||
|
||||
Reading authorship at all presupposes the read cap (VERIFIED): the author field is not a
|
||||
UserId but `CommitContent::author_digest(user, overlay)`, a BLAKE3 keyed hash, and the
|
||||
commit content sits in blocks ChaCha20-encrypted under `Object::convergence_key(store)`
|
||||
(`engine/repo/src/object.rs`), whose key material is the store id **plus the
|
||||
store-overlay-branch ReadCapSecret**. No read cap → the author field is not even
|
||||
visible. *Nuance, VERIFIED:* the digest's own hashing key derives from
|
||||
`overlay_id_for_read_purpose`, which for Public/Protected/Private/Group stores is
|
||||
`OverlayId::outer(store_id)` — public. What is secret is the commit content, not the
|
||||
hash key.
|
||||
|
||||
**Consequence for this lib:** "who wrote this triple" is unanswerable today — neither
|
||||
cryptographically (nothing verifies) nor by identity (the digest is opaque without a
|
||||
member table). Any authorship or provenance the polyfill needs must be carried in the
|
||||
DATA it writes and re-read from there; an "authored by X" claim in the emulation has no
|
||||
core check behind it.
|
||||
|
||||
### No existence probe at SDK level — addressing presupposes the cap — VERIFIED
|
||||
|
||||
`AppRequestCommandV0` (`engine/net/src/app_protocol.rs`) contains no existence command:
|
||||
`Fetch`, `Pin`, `UnPin`, `Delete`, `Create`, `FileGet`, `FilePut`, `Header`, `InboxPost`,
|
||||
`SocialQueryStart`, `SocialQueryCancel`, `QrCodeProfile`, `QrCodeProfileImport`,
|
||||
`OrmStartGraph`, `OrmStartDiscrete`, `OrmGraphUpdate`, `OrmDiscreteUpdate`, `OrmStop`.
|
||||
Nothing answers *"does document D exist?"*.
|
||||
|
||||
The single probe in the tree is internal and cannot answer it either:
|
||||
`Verifier::has_blocks` (`engine/verifier/src/verifier.rs`) sends
|
||||
`BlocksExist { blocks, overlay }`. It is `pub(crate)` (never reaches JS); it takes
|
||||
**`BlockId`s** — content addresses you only hold if you already read the object; it takes
|
||||
a **`&Repo` already loaded**; and it targets
|
||||
`repo.store.overlay_for_read_on_client_protocol()` = the **inner** overlay
|
||||
(`Store::inner_overlay` → `overlay_id_for_write_purpose(store_overlay_branch_readcap.key)`,
|
||||
`engine/repo/src/store.rs`), derived from the read-cap secret.
|
||||
|
||||
**Consequence for this lib:** you cannot prove — nor disprove — the existence of a
|
||||
document whose key you do not hold. **Addressing presupposes the cap.** Every "is it
|
||||
there?" question therefore collapses into "can I read it?", which is why absence is only
|
||||
ever established behind a sync barrier (see § *Findable-without-lookup vs subscribable*)
|
||||
and never by probing.
|
||||
|
||||
### `expose_outer` is hard-coded to `false` — VERIFIED
|
||||
|
||||
Both constructors of `PinRepo` — `PinRepo::for_branch` and `PinRepo::from_repo`
|
||||
(`engine/net/src/actors/client/pin_repo.rs`) — set `expose_outer: false`, and they are
|
||||
the only two `PinRepoV0` constructions in the tree. No parameter carries the flag up:
|
||||
`expose_outer` appears nowhere under `sdk/`. The broker side is fully wired
|
||||
(`RepoInfo.expose_outer: HashSet<UserId>` in `engine/broker/src/server_broker.rs`, the
|
||||
`if expose_outer` branch in `rocksdb_server_storage.rs`, the outer-overlay registration
|
||||
in `server_storage/core/overlay.rs`), and the `PinRepo` responder even validates the flag
|
||||
(refusing `expose_outer` from a peer that publishes no topic) — but no client ever sets
|
||||
it.
|
||||
|
||||
**Consequence for this lib:** a store's **outer** overlay is never registered broker-side,
|
||||
so there is no anonymous / capability-free read surface to build on. Everything is reached
|
||||
through the inner overlay, i.e. through a read cap — the same cap-first addressing as
|
||||
above. The "public store readable by everyone without permission" promise in the official
|
||||
docs has no client-side switch today.
|
||||
|
||||
### The `Ext` protocol serves blocks with no control — VERIFIED
|
||||
|
||||
The `ExtObjectGetV0` responder (`engine/net/src/actors/ext/get.rs`) builds
|
||||
`Store::new_from_overlay_id(&req.overlay, …)` from the OverlayId the **requester
|
||||
declares**, then returns `Object::load_without_header(obj_id, None, &store)` blocks for
|
||||
each requested id. No authentication, no verification that the requester belongs to that
|
||||
overlay. The guards that were planned exist but are dead:
|
||||
|
||||
- `Authorization::ExtMessage` is matched in `Broker::authorize`
|
||||
(`engine/net/src/broker.rs`) and returns `AccessDenied` — but **no caller ever passes
|
||||
it**; the only `authorize` call sites pass `Discover`, `Admin` or `Client`. The
|
||||
server-side `StartProtocol::Ext` arm in `engine/net/src/connection.rs` goes straight to
|
||||
`StepReply::Responder`, never through `authorize`.
|
||||
- the config flag whose comment reads *"are ExtRequest allowed on the server? this
|
||||
requires the core to be ON."* — `allow_read` in `engine/net/src/types.rs` — is declared
|
||||
and defaulted to `false`, and **read nowhere**.
|
||||
- `ExtRequestContentV0::get_actor` handles `WalletGetExport` and `ExtObjectGet` and falls
|
||||
through to `_ => unimplemented!()` for `ExtTopicSyncReq` — a **panic reachable from an
|
||||
anonymous peer**. (The commented-out `// Self::ExtTopicSyncReq(a) => a.get_actor(),` on
|
||||
that arm and the `// TODO inbox requests` in the enum are *direction hints*, labelled as
|
||||
such — not current behaviour.)
|
||||
|
||||
**Consequence for this lib:** `Ext` is not a usable read path in either direction. Blocks
|
||||
come back **encrypted**, and naming them requires ObjectIds you only have once you can
|
||||
already read — so it grants no capability we could build on, and confirms the shape of
|
||||
everything above: confidentiality lives entirely in the keys, and holding no key means
|
||||
holding no partial access, just none.
|
||||
|
||||
## Known open issues (section added 2026-07-18)
|
||||
|
||||
Live limitations observed against the current core/SDK, each with its epistemic
|
||||
@@ -515,5 +757,88 @@ chain never runs and consumers keep a stale value until the next connection
|
||||
delivers a fresh initial `State`. REMOTE commits DO push correctly (verified:
|
||||
cross-browser reactive update works). Verdict pending a live instrumented run.
|
||||
Full write-up (suspect link, instrumentation, planned polyfill-side fix):
|
||||
[`../packages/client/docs/sdk-reference.md`](../packages/client/docs/sdk-reference.md)
|
||||
[`../packages/polyfill/docs/polyfill-reference.md`](../packages/polyfill/docs/polyfill-reference.md)
|
||||
§ *Current emulation status*.
|
||||
|
||||
### Cold-start anchored read returns 0 rows instead of an error — symptom VERIFIED, mechanism INFERRED, healed polyfill-side
|
||||
|
||||
On a FRESH session over the SAME persistent wallet (reconnect, new page, re-login), an
|
||||
anchored `sparql_query` against a document written in an earlier session comes back with
|
||||
**0 rows and no error** — persisted documents read as empty. Observed on every anchored
|
||||
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-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.
|
||||
|
||||
The circularity that made it self-inflicted (VERIFIED by the fix working): `doc_subscribe`
|
||||
WOULD open the repo, but the reactive layer only subscribes AFTER a listing produced
|
||||
NURIs, and the listing is itself an anchored read of a not-yet-open index repo → 0 rows →
|
||||
nothing to subscribe → nothing ever opens.
|
||||
|
||||
**Mechanism INFERRED, not established.** `resolve_target_for_sparql(Repo(id))`
|
||||
(`engine/verifier/src/request_processor.rs`) does
|
||||
`self.repos.get(repo_id).ok_or(RepoNotFound)`, so a repo genuinely absent from
|
||||
`self.repos` should ERROR, not return 0 rows. The most plausible reading of the silent 0
|
||||
is that the repo IS in `self.repos` (loaded from local user storage at bootstrap) while
|
||||
its named graph in `graph_dataset` is not yet populated — commits not applied/synced yet
|
||||
— so the query legitimately matches nothing. Not traced end to end; the tension with the
|
||||
`RepoNotFound` path described in § *A repo is only queryable once OPENED/synced into the
|
||||
store* is unresolved.
|
||||
|
||||
**Consequence for this lib:** a cold anchored read is NOT authoritative on its own — 0
|
||||
rows does not mean absent. This is what imposes the open-then-read discipline on every
|
||||
cold reader, and it is why the account trust root had to move behind a first-`State`
|
||||
barrier (see § *The pointer → doc-shim indirection*).
|
||||
|
||||
### Account fork on concurrent provision — symptom VERIFIED, guarded polyfill-side, residue persists in wallets
|
||||
|
||||
On a fresh page, several independent callers hit `ensureAccount(A)` near-simultaneously
|
||||
(the public and protected `watchShape`, container subscriptions, the app's owned-events
|
||||
effect). When the account is genuinely new, each caller sees 0 and each provisions its
|
||||
own set of three scope documents — an **in-session account fork**. The persisted residue
|
||||
is a single account subject carrying MULTIPLE values for one scope predicate (observed:
|
||||
five `shim:docPublic`), after which a writer and a later reader can resolve DIFFERENT
|
||||
scope docs and the reader's anchored read returns 0.
|
||||
|
||||
Two polyfill-side guards, both in `packages/polyfill/src/shared-wallet/account-registry.ts`: `ensureInFlight`
|
||||
(a bounded promise map keyed by account, so concurrent `ensureAccount` calls share ONE
|
||||
resolve-or-provision) prevents new forks; `canonicalDoc` (pick the lexicographically
|
||||
smallest NURI among all distinct values for a scope predicate — NURIs are
|
||||
content-addressed, so the order is total and session-independent) makes resolution
|
||||
deterministic on wallets that already carry fork residue. The earlier account-level
|
||||
`provisionRetry` / `resolveAccountReliably` loop is gone, replaced by the doc-shim
|
||||
barrier.
|
||||
|
||||
**Consequence for this lib:** the underlying enabler is core-side — there is no atomic
|
||||
create-if-absent, and no existence probe to settle "does this account already exist?"
|
||||
(see § *No existence probe at SDK level*), so provisioning is a read-then-create race the
|
||||
polyfill has to serialize itself. The guards are mitigation, not a fix: a wallet already
|
||||
corrupted stays corrupted, and only `canonicalDoc` keeps it readable.
|
||||
|
||||
### Outbox replay aborts on an unknown topic (`REPLAY TOPIC NOT FOUND`) — VERIFIED in core, already documented as an incident
|
||||
|
||||
`Verifier::send_outbox` (`engine/verifier/src/verifier.rs`) walks the queued events and,
|
||||
for each, looks up `self.topics.get(&(overlay, topic_id))`. On a miss it logs
|
||||
`REPLAY TOPIC NOT FOUND <topic> IN OVERLAY <overlay>` and sets `need_replay`, calls
|
||||
`load_from_credentials_and_outbox(&events_to_replay)`, then in the send loop does
|
||||
`self.topics.get(…).ok_or(NgError::TopicNotFound)?` — the `?` **aborts the whole outbox
|
||||
flush**, so the remaining queued events are not sent. There is no per-event isolation and
|
||||
no signal to the caller.
|
||||
|
||||
Already covered — **not duplicated here**: this is the core-side mechanism behind the
|
||||
symptom described in § *Write loss on socket death (`SerializationError`)* above, whose
|
||||
full post-mortem (logs, causal chain, the unarbitrated (i)/(ii) reserve) is
|
||||
[`incidents/2026-07-14-write-loss-on-disconnect.md`](./incidents/2026-07-14-write-loss-on-disconnect.md).
|
||||
The spontaneous socket death (`SOCKET IS CLOSED Some(Left(SerializationError))`) is
|
||||
likewise covered there and in that section — the only fact added here is the abort
|
||||
semantics of the replay path itself (VERIFIED by reading `send_outbox`).
|
||||
|
||||
**Consequence for this lib:** a queued write can be dropped without any observable error,
|
||||
and one unknown topic can take the rest of the queue with it. The polyfill's own
|
||||
`shared-wallet/outbox-log.ts` does not record anything: it exports a single `inspectOutbox()` that
|
||||
READS the SDK's own `sessionStorage` outbox and logs how many peers still have queued
|
||||
writes. It observes the symptom; it holds nothing it could replay, and no
|
||||
write-durability confirmation exists to await — so "the write returned" is not "the write
|
||||
is durable".
|
||||
|
||||
+44
-41
@@ -5,7 +5,7 @@ shared wallet. This is a design decision, grounded entirely in the query
|
||||
capability documented in
|
||||
[`nextgraph-current-state.md`](./nextgraph-current-state.md) § *The query
|
||||
capability*. The consumer application never sees any of this: it asks
|
||||
`@ng-eventually/client` for its lists by need and trusts the answer — the whole
|
||||
`@ng-eventually/polyfill` for its lists by need and trusts the answer — the whole
|
||||
read mechanism lives here, in the polyfill.
|
||||
|
||||
> The rule in one line: read each by-need doc with its own anchored
|
||||
@@ -37,31 +37,29 @@ The governing constraints (all verified in `nextgraph-rs`, cited there):
|
||||
- No reactive union query, and the reactive ORM hangs if handed a per-entity
|
||||
/ unsynced graph fan-out (`RepoNotFound` aborts `orm_start_graph`).
|
||||
|
||||
## Two read regimes — enumerate vs follow
|
||||
## One read regime — follow, never enumerate
|
||||
|
||||
There is **no cross-wallet read** in current NextGraph, so nothing is globally
|
||||
enumerable "for free". The polyfill splits every list into one of two regimes:
|
||||
There is **no cross-wallet read** in current NextGraph, and there is no discovery
|
||||
either: **you cannot discover, you can only follow links**
|
||||
([`readcap-and-nuri-model.md`](./readcap-and-nuri-model.md) §4ter-bis). Nothing is
|
||||
globally enumerable, and nothing is meant to be.
|
||||
|
||||
### Events (all public) = the global index — the one enumeration hack
|
||||
> An earlier version of this document described a second regime — "all public
|
||||
> events, enumerated through a global index" — presented as the one justified
|
||||
> "hack". It was removed on 2026-07-30 along with `discovery.ts`: a global index
|
||||
> emulates a capability the target will never have, and it pools data across
|
||||
> wallets. A public document is reached because someone circulated its link, never
|
||||
> because it was listed.
|
||||
|
||||
Public events are the only thing enumerated across accounts, via the emulated
|
||||
discovery index (`discovery.readIndex`, see
|
||||
[`simulation.md`](./simulation.md) § *Emulated discovery index*). This is the one
|
||||
"hack", and it is justified precisely because P2P has no cross-wallet read: without
|
||||
a shared index a client could never learn that another account's public event-doc
|
||||
exists. `readIndex` yields the event-doc NURIs to open/sync; those repos
|
||||
then enter the local union and become union-queryable.
|
||||
|
||||
### Everything else = follow a graph, never enumerate across accounts
|
||||
### Everything = follow a graph, never enumerate across accounts
|
||||
|
||||
My participations / my profile, protected data an owner has granted me, my
|
||||
notifications — none of these is enumerated across accounts. Each is reached by
|
||||
notifications — none of these is enumerated across virtualUsers. Each is reached by
|
||||
what is already reachable to me:
|
||||
|
||||
- my own docs (always in `self.repos`);
|
||||
- docs an owner has granted me via a directed per-document read grant
|
||||
(`grantRead(doc, granteeId)` — see the per-document ReadCap in
|
||||
[`simulation.md`](./simulation.md));
|
||||
- my own docs (always in `self.repos`, and whose caps I hold);
|
||||
- docs whose cap an owner has delivered to my inbox (`inbox.share` — see the
|
||||
per-document ReadCap in [`simulation.md`](./simulation.md));
|
||||
- my inbox (deposits addressed to me).
|
||||
|
||||
The rule of thumb: access is not discovery. You only union-query over graphs you
|
||||
@@ -71,14 +69,16 @@ Accessing a document without read rights yields an empty result: a reactive / un
|
||||
read never decrypts a repo you hold no cap for, so it simply returns nothing (this
|
||||
matches NextGraph's union read). A targeted read of a repo you do not hold diverges
|
||||
in one way — it raises `RepoNotFound` rather than returning empty — and the read
|
||||
path tolerates that per-doc (a doc that throws is skipped). The cap-introspection
|
||||
used here (`canRead` / `governsRead`) is emulation-only; there is no NextGraph API
|
||||
behind it, so it has no migration target.
|
||||
path tolerates that per-doc (a doc that throws is skipped). The held-caps lookup used
|
||||
here (`capFor`) is emulation-only in its *implementation*; its shape is the target's
|
||||
(possession), so what disappears at migration is the lookup, not the model. Note
|
||||
there is deliberately no "may identity X read doc D?" call: the real model cannot
|
||||
answer that either.
|
||||
|
||||
## Listing = a bounded set of per-doc anchored reads (never a union-scan, never the ORM fan-out)
|
||||
|
||||
To produce a list, take the bounded, by-need set of doc NURIs (the index-yielded
|
||||
event NURIs, my own docs, the NURIs an owner has granted me) and read each one with its
|
||||
To produce a list, take the bounded, by-need set of doc NURIs (my own docs, and the
|
||||
NURIs whose cap someone delivered to me) and read each one with its
|
||||
own anchored `sparql_query` (`SELECT ?s ?p ?o WHERE { ?s ?p ?o }`, anchor = that
|
||||
doc NURI, in parallel and tolerant per-doc). The anchor restricts the query to that
|
||||
one repo's graph, so each read is O(1) in the doc's own size and independent of how
|
||||
@@ -104,14 +104,14 @@ 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 (`readModel.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.
|
||||
|
||||
## The boundary with the consumer application
|
||||
|
||||
The consumer application asks the SDK for its lists by need and trusts the returned
|
||||
The consumer application asks the polyfill for its lists by need and trusts the returned
|
||||
set. It never constructs a NURI, never picks the union-vs-anchor mode, never touches
|
||||
the ORM. The domain-shaped list helpers (e.g. "my meeting points", "events") live in
|
||||
the consumer application, not the lib; the lib exposes the generic by-need read.
|
||||
@@ -165,14 +165,14 @@ 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 `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
|
||||
`RepoNotFound` and is skipped per-doc, see the VERIFIED note above — the read cannot
|
||||
sync an unknown repo.)
|
||||
|
||||
> **Re-confirmed by the standing e2e harness (`packages/client/e2e/`, broker
|
||||
> **Re-confirmed by the standing e2e harness (`packages/polyfill/e2e/`, broker
|
||||
> `@ng-org/web 0.1.2-alpha.13`).** The `docRoundTrip` check measures all three shapes
|
||||
> anchored to a doc D: (a) a no-GRAPH default-graph write round-trips; (b) an explicit
|
||||
> `INSERT DATA { GRAPH <D> {…} }` — a **constant** plain NURI — **also** round-trips
|
||||
@@ -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 — `read-model.ts`
|
||||
## Implementation — one anchored query per document, and nothing above it
|
||||
|
||||
`readModel.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.
|
||||
|
||||
+368
-142
@@ -1,181 +1,407 @@
|
||||
# Modèle ReadCap & NURI de NextGraph — et l'émulation caps du polyfill
|
||||
# NextGraph's ReadCap & NURI model — and the polyfill's caps emulation
|
||||
|
||||
**Établi 2026-07-20**, VÉRIFIÉ par lecture directe du cœur Rust `nextgraph-rs`
|
||||
(sauf points marqués INFÉRÉ). Les `file:line` sont datés — les numéros de ligne
|
||||
sont volatils, se repérer par symbole/regex.
|
||||
**Established 2026-07-20**, VERIFIED by direct reading of the `nextgraph-rs` Rust core (except for points marked INFERRED). The `file:line` references are dated — line numbers are volatile, navigate by symbol/regex.
|
||||
|
||||
But : donner la vérité-terrain du modèle de droits d'accès NextGraph, pour
|
||||
aligner l'émulation `caps.ts` du polyfill (aujourd'hui une ACL — l'inverse du
|
||||
modèle réel). C'est la base de l'item « aligner ReadCap/WriteCap avec NextGraph ».
|
||||
Purpose: to give the ground truth of NextGraph's access-rights model, in order to align the polyfill's `emulated-verifier/caps.ts` emulation (an ACL until the cap-surface work — the inverse of the real model; realigned 2026-07-28, see §5). This is the basis for the item "align ReadCap/WriteCap with NextGraph".
|
||||
|
||||
> ## How to use this document — verify, never infer
|
||||
>
|
||||
> **NextGraph works very differently from what general knowledge of distributed systems suggests.** Assert nothing about it that is not, at minimum, in this repository's docs — and preferably read in `nextgraph-rs` itself, with a `file:line`. Reasoning by analogy with git, with ACL systems, with pub/sub brokers, or with "how this normally works" produces confident, wrong statements. Every correction recorded below started that way.
|
||||
>
|
||||
> **Write down everything you learn about NextGraph, as you learn it** (PO, 2026-07-30) — at least everything that helps move forward or that corrects a direction. Not at the end of an investigation, not only in the brief that happened to need it: a fact read in `nextgraph-rs` and left in a conversation is a fact the next agent will re-derive, and will get wrong.
|
||||
>
|
||||
> It does not all have to land in this file. This is where the **access model** accumulates (caps, NURIs, stores, branches, who can read what); platform behaviour and SDK gaps belong in [`nextgraph-current-state.md`](./nextgraph-current-state.md), and how the polyfill fakes something belongs in [`simulation.md`](./simulation.md). What matters is that it is written down somewhere durable and findable, with a `file:line` — not which file.
|
||||
>
|
||||
> Three traps in particular, all of which have already caught an agent more than once:
|
||||
>
|
||||
> - **A comment describing the CURRENT state is not the intent.** §3's DIRECTION block exists because `RepoLinkV0`'s comment was read as the target model. It is not.
|
||||
> - **A word you recognise probably does not mean what you think.** `branch` is not git's. `wallet` is only a keyring — what we call a virtual user is a **user** (a *site*). Check the type before using the word.
|
||||
> - **The access rule is "whoever has the reference AND the key reads" — never "whoever has the reference reads".** An agent forgets this with remarkable consistency, because client-server reflexes supply a missing half: somewhere a server checks. Here nobody checks (§0 below). Getting it wrong does not fail — it silently grants. Every time you hand out a value, ask which of the two you just handed.
|
||||
> - **NextGraph's naming ALWAYS wins over any rule of ours — including the one that follows.** Where upstream has a word for something, that is the word, full stop. `publisher` is a case in point: it appears 126 times in the engine (`as_publisher`, `publisher_advert`) for a **pub/sub role on a topic**, and it must be used, unchanged, whenever that is what is meant.
|
||||
> - **What is banned is OUR loose "publish a document"**, which has no upstream referent and covers three different acts: *placing a document in a public store*, *making it findable*, and (in this emulation only) *handing out a key*. Every design discussion that used it drifted between them. NextGraph knows only the first — a document IS IN a public store, and brokers serve it accordingly. Say which act you mean. If you catch yourself writing "publish a document", you have not yet decided which one. This never licenses renaming something upstream calls `publisher`.
|
||||
> - **"I looked and it is not there" is not a finding.** §4quinquies once stated that no register existed for received caps, after checking one code path. `AddLink` had been sitting next to `AddRepo` in the same file the whole time. Absence needs at least as much evidence as presence — and an implementation *cache* (like local user storage) is never the model: it is what the model fills.
|
||||
|
||||
---
|
||||
|
||||
## 1. Un ReadCap = possession d'une clé, PAS une ACL par-identité
|
||||
## 0. The security model, and why an agent keeps losing it
|
||||
|
||||
Un **ReadCap est fondamentalement une clé cryptographique que l'on détient**, pas
|
||||
une entrée d'ACL liée à un wallet. « Qui détient la clé peut lire. »
|
||||
**This is the one thing to hold on to.** Every design mistake this file records — a cap minted where a reference sufficed, a link that granted what it was meant to merely name, an "is it allowed?" call that cannot exist — comes from letting go of it.
|
||||
|
||||
- Structure : `ReadCap = ObjectRef = BlockRef { id: BlockId, key: SymKey }`
|
||||
(`engine/repo/src/types.rs:461, 463-471, 557, 565`).
|
||||
- `id: BlockId` = digest **BLAKE3** (adresse de l'objet chiffré).
|
||||
- `key: SymKey = ChaCha20Key([u8;32])` = la **clé de déchiffrement**.
|
||||
Détenir le couple → le broker sert les blocs chiffrés par `id`, on déchiffre
|
||||
**localement** avec `key`.
|
||||
- Granularité : par commit/objet l'`ObjectRef` **est** le cap ; pour une branche
|
||||
→ commit de définition ; pour un repo → RootBranch ; pour un store → cap du
|
||||
repo racine (`types.rs:559-565`). `ReadCapSecret` = la moitié clé (`:567-570`).
|
||||
- **Il n'y a PAS de read-ACL.** L'appartenance/permissions d'un repo
|
||||
(`RootBranch`, `AddMember`, `AddPermission`) gouvernent l'**écriture/admin**,
|
||||
pas la lecture. La lecture n'est gardée que par la possession de la clé.
|
||||
### The rule
|
||||
|
||||
## 2. Accorder la lecture = sceller la clé au destinataire
|
||||
> A document is readable by whoever holds **the reference AND the key**. Not by whoever holds the reference.
|
||||
|
||||
« Grant » = livrer le cap **scellé** (`crypto_box seal`, chiffrement à clé
|
||||
publique anonyme) à la **pubkey d'inbox** du destinataire — seul lui l'ouvre avec
|
||||
sa clé privée.
|
||||
There is no third party in that sentence. No server, no ACL, no check at access time: the engine verifies a permission on WRITE only (`verify_permission` → `PermissionDenied` in `Commit::verify`), never on read. Content is encrypted; the key IS the right. That is what local-first means here — there is nobody to ask, so possession is the whole mechanism.
|
||||
|
||||
- Message d'inbox scellé : `InboxMsgBody.msg` = `crypto_box::seal(... to_inbox ...)`,
|
||||
ouvert avec la clé secrète d'inbox (`engine/net/src/types.rs:4272, 4299, 4319`).
|
||||
- Le payload peut porter un cap : `ContactDetails.read_cap: Option<ReadCap>`
|
||||
(« if user wants to share the content of profile ») (`net/types.rs:4232-4233`)
|
||||
→ **grant dirigé** (scellé à un destinataire).
|
||||
- Variante **non-dirigée** : `RepoLinkV0.read_cap` = un lien partageable que
|
||||
**quiconque le reçoit** peut ouvrir (`net/types.rs:5061-5078`).
|
||||
### Why this is easy to lose
|
||||
|
||||
Le « ciblage wallet » vit donc dans **l'enveloppe de scellage**, pas dans le cap :
|
||||
le cap reste `{id, clé}`, possession-based.
|
||||
Client-server reflexes supply the missing half without asking. In that world a link is an identifier, harmless on its own, and access is decided elsewhere — so handing out a URL feels safe, and "may Bob read this?" is a question with an answer. Both instincts are wrong here, and neither announces itself: code written on them **does not fail**, it silently grants. There is no error to notice, no test that goes red on its own.
|
||||
|
||||
## 3. Révocation = re-key (grossier, non-rétroactif)
|
||||
### What the rule buys — composable confidentiality
|
||||
|
||||
On ne « reprend » pas une clé livrée. Révoquer = **re-chiffrer** avec une nouvelle
|
||||
clé et ne la re-sceller qu'aux autorisés restants.
|
||||
Because a reference grants nothing, **a reference is not recursive**: a widely-circulated document may point at a restricted one. The reference says *it exists*; the key says *who reads it*.
|
||||
|
||||
- « Capabilities are not durable: they can be refreshed by members and previously
|
||||
shared Caps become obsolete/revoked… if [a member] doesn't subscribe, they lose
|
||||
access after the refresh » (`net/types.rs:5055-5058`).
|
||||
- Mécanisme : `RootCapRefresh` / `BranchCapRefresh` (`repo/src/commit.rs:616,630`;
|
||||
perms `types.rs:1748-1749`).
|
||||
- Conséquences : **grossier** (échelle repo/branche), **non-rétroactif** (ce qui a
|
||||
été lu avant reste connu de l'ex-détenteur ; il ne déchiffre que les versions
|
||||
**antérieures** au refresh).
|
||||
- Livraison **durable** d'un cap = `PermaCap` — encore **TODO** (`repo/types.rs:578`).
|
||||
That is what lets confidentiality be composed inside one document:
|
||||
|
||||
## 4. Grammaire NURI : cap-less vs cap-porteur (le segment `:k:`)
|
||||
- a public summary pointing at restricted chapters,
|
||||
- a public event pointing at its participant list,
|
||||
- a profile pointing at data reserved for a circle.
|
||||
|
||||
Le discriminant est le segment **`:k:{clé}`** : présent = cap-porteur ; **absent =
|
||||
cap-less** (nomme/localise **sans** donner le droit de lire). C'est de **première
|
||||
classe** dans le type : `NuriV0.target` (des ids) et `access`/`objects` (le cap)
|
||||
sont des **champs séparés** — un NURI d'id parse avec `access: vec![]`
|
||||
(`engine/net/src/app_protocol.rs:53-62, 99-118, 181-195, 659-677`).
|
||||
The author circulates one document and still decides, per referenced document, who gets the key. **Remove non-recursiveness and this whole construction collapses**: everything a circulated document mentions becomes readable by all its readers, and no level of confidentiality can exist inside a document one shares.
|
||||
|
||||
**Cap-less** (id + overlay éventuel, pas de clé) — formatters `app_protocol.rs`,
|
||||
regexes `net/types.rs` :
|
||||
`test/cross-user-access.test.ts` is this property's test, and it is the suite's centrepiece: Alice's document in a public store REFERENCES her protected one; Bob follows the reference, names the target, reads nothing of it. It writes the reference **bare** — which is exactly what an application must do.
|
||||
|
||||
### The failure mode to watch for
|
||||
|
||||
Any call that returns a key where a reference was asked for. It looks like a convenience ("give me the link to my document"), it type-checks, the tests stay green — and it converts "whoever has the reference and the key" into "whoever has the reference", for that document and every document it mentions. `linkTo` (added and removed 2026-08-06) was exactly this.
|
||||
|
||||
---
|
||||
|
||||
## 1. A ReadCap = possession of a key, NOT a per-identity ACL
|
||||
|
||||
A **ReadCap is fundamentally a cryptographic key that one holds**, not an ACL entry tied to a wallet. "Whoever holds the key can read."
|
||||
|
||||
- Structure: `ReadCap = ObjectRef = BlockRef { id: BlockId, key: SymKey }` (`engine/repo/src/types.rs:461, 463-471, 557, 565`).
|
||||
- `id: BlockId` = **BLAKE3** digest (address of the encrypted object).
|
||||
- `key: SymKey = ChaCha20Key([u8;32])` = the **decryption key**.
|
||||
Holding the pair → the broker serves the encrypted blocks by `id`, and one decrypts **locally** with `key`.
|
||||
- Granularity: per commit/object the `ObjectRef` **is** the cap; for a branch → its defining commit; for a repo → RootBranch; for a store → the root repo's cap (`types.rs:559-565`). `ReadCapSecret` = the key half (`:567-570`).
|
||||
- **There is NO read-ACL.** A repo's membership/permissions (`RootBranch`, `AddMember`, `AddPermission`) govern **writing/admin**, not reading. Reading is guarded only by key possession.
|
||||
|
||||
## 2. Granting read access = sealing the key to the recipient
|
||||
|
||||
"Grant" = delivering the cap **sealed** (`crypto_box seal`, anonymous public-key encryption) to the recipient's **inbox pubkey** — only they can open it with their private key.
|
||||
|
||||
- Sealed inbox message: `InboxMsgBody.msg` = `crypto_box::seal(... to_inbox ...)`, opened with the inbox secret key (`engine/net/src/types.rs:4272, 4299, 4319`).
|
||||
- The payload can carry a cap: `ContactDetails.read_cap: Option<ReadCap>` ("if user wants to share the content of profile") (`net/types.rs:4232-4233`) → **directed grant** (sealed to one recipient).
|
||||
- **Undirected** variant: `RepoLinkV0.read_cap` = a shareable link that **whoever receives it** can open (`net/types.rs:5061-5078`).
|
||||
|
||||
So "wallet targeting" lives in the **sealing envelope**, not in the cap: the cap remains `{id, key}`, possession-based.
|
||||
|
||||
> **Current state (2026-07-27) — the path is a GAP, not a disagreement.** The `ContactDetails.read_cap` field exists, but the construction of the message is `unimplemented!()` (its only caller passes "without read_cap") and the receiver **discards** the cap it would receive. The *shape* is therefore the right one; the implementation is not there. The polyfill emulates it in the meantime — filed in the bug-inbox.
|
||||
|
||||
## 3. Revocation = re-key (coarse, non-retroactive)
|
||||
|
||||
A delivered key is not "taken back". To revoke = **re-encrypt** with a new key and re-seal it only to the remaining authorized holders.
|
||||
|
||||
- "Capabilities are not durable: they can be refreshed by members and previously shared Caps become obsolete/revoked… if [a member] doesn't subscribe, they lose access after the refresh" (`net/types.rs:5055-5058`).
|
||||
- Mechanism: `RootCapRefresh` / `BranchCapRefresh` (`engine/verifier/src/commits/mod.rs:616,630` — both no-op `Ok(())` stubs today; perms `types.rs:1748-1749`).
|
||||
- Consequences: **coarse** (repo/branch scale), **non-retroactive** (what was read before remains known to the former holder; they only decrypt the versions **prior to** the refresh).
|
||||
- **Durable** delivery of a cap = `PermaCap` — still **TODO** (`repo/types.rs:578`).
|
||||
|
||||
### DIRECTION — rotation does NOT cause access to be lost (confirmed by the PO, 2026-07-27)
|
||||
|
||||
**Do not read the comment above as the intent.** "*if they don't subscribe, they lose access after the refresh*" describes **the current state**, not the target. What NextGraph is aiming for:
|
||||
|
||||
> When a key is rotated, the new one is **sent to the inbox** of the users who retain the access right. That inbox is **processed automatically** as soon as one of the user's clients connects.
|
||||
|
||||
So access is **not lost**, it is **deferred** until the next connection — consistent with local-first. Shape consequences: **no subscription obligation** to expose to the consumer; a re-delivery takes **the same channel** as the initial delivery, so the sharing mechanism covers both with no special case. **Revocation** remains "stop re-delivering", non-retroactive.
|
||||
|
||||
## 4. NURI grammar: cap-less vs cap-bearing (the `r:` segment)
|
||||
|
||||
**Clearing up the confusion first**: `did:ng:` is **not** a "cap-less" marker, it is the **URI scheme prefix** — present everywhere (inbox `did:ng:d:…`, branch `did:ng:b:…`, overlay `did:ng:v:…`, document `did:ng:o:…`). A NURI **is** a `did:ng:…`. So there is no "the did" on one side and "the NURI" on the other: it is **a single object**, with or without the key inside it — a single type upstream, `NuriV0 { target, access }`, where a cap-less NURI simply has an empty `access`.
|
||||
|
||||
The discriminant is the **`r:` segment** (see the correction below — this document said `:k:` until 2026-07-30): present = cap-bearing; **absent = cap-less** (names/locates **without** granting the right to read). This is **first-class** in the type: `NuriV0.target` (ids) and `access`/`objects` (the cap) are **separate fields** — an id-only NURI parses with `access: vec![]` (`engine/net/src/app_protocol.rs:53-62, 99-118, 181-195, 659-677`).
|
||||
|
||||
**Cap-less** (id + optional overlay, no key) — formatters in `app_protocol.rs`, regexes in `net/types.rs`:
|
||||
- `did:ng:o:{repo_id}` (`:315`, `RE_REPO_O` types.rs:52)
|
||||
- `did:ng:o:{repo_id}:v:{overlay_id}` (`:263`, `RE_REPO` types.rs:55)
|
||||
- `did:ng:o:{repo_id}:v:{overlay_id}:b:{branch_id}` (`RE_BRANCH` types.rs:58)
|
||||
- `did:ng:o:{repo_id}:c:{commit_id}` (`:355`)
|
||||
- `did:ng:b:{branch}` / `h:{topic}` / `v:{overlay}` / `d:{inbox}` (`:327,323,319,359`)
|
||||
|
||||
**Cap-porteur** (embarque la clé) :
|
||||
- `did:ng:j:{id}:k:{clé}` — read cap d'objet/fichier (`repo/types.rs:511`,
|
||||
`RE_FILE_READ_CAP` types.rs:49)
|
||||
- `did:ng:o:{repo}:c:{commit}:k:{clé}` (`RE_COMMIT` types.rs:73)
|
||||
- liste `RE_OBJECTS` `…:[cj]:{id}:k:{clé}…:l:{locator}` (types.rs:64)
|
||||
**Cap-bearing — and `:k:` is NOT the ReadCap segment.** CORRECTED 2026-07-30, on a report from NextGraph's developer, verified in the source. There are **two different encodings**, and confusing them was an error in this document:
|
||||
|
||||
Le segment `:v:` est l'**overlay**, qui a sa propre section ci-dessous — c'est le
|
||||
point le plus lourd de conséquences pour les modèles de présence anonyme.
|
||||
|
||||
## 4bis. L'overlay est l'espace réseau d'un STORE — jamais d'un document
|
||||
|
||||
**L'overlay est l'unité d'adressage réseau d'un store.** Chez le broker, les blocs
|
||||
sont rangés sous une clé `(overlay, block_id)`, et les pairs se synchronisent
|
||||
*dans* un overlay. Deux formes par store :
|
||||
|
||||
| | Dérivation | Qui peut le calculer |
|
||||
| Segment | Shape | What it is |
|
||||
|---|---|---|
|
||||
| **outer** | `OverlayId::outer(store_id)` = BLAKE3 **public** | tout le monde (le store_id suffit) |
|
||||
| **inner** | `OverlayId::inner(store_id, readcap_secret)` = BLAKE3 **keyed** | seulement qui détient la clé de lecture du store |
|
||||
| `:k:` | `{id}:k:{key}` — id and key as **two segments** | an **object / file / commit** ref: `j:{id}:k:{key}` (`repo/types.rs:510`), `c:{id}:k:{key}` (`:514`) |
|
||||
| `r:` | `r:{base64url(serde_bare(ObjectRef))}` — id and key **serialized together into one** | a **ReadCap** — `BlockRef::readcap_nuri()` (`repo/types.rs:518-521`) |
|
||||
|
||||
Cohérent avec le reste du modèle : pas de rôle ni de liste, seulement « détiens-tu
|
||||
la clé qui permet de dériver cet identifiant ». `outer` = le nom public du store,
|
||||
`inner` = son nom privé.
|
||||
```rust
|
||||
pub fn readcap_nuri(&self) -> String {
|
||||
let ser = serde_bare::to_vec(self).unwrap();
|
||||
format!("r:{}", base64_url::encode(&ser))
|
||||
}
|
||||
```
|
||||
|
||||
**Le `:v:` d'un NURI de DOCUMENT porte l'overlay de son STORE** (VÉRIFIÉ, chaîne
|
||||
lue de bout en bout) : `NuriV0::repo_graph_name(repo_id, overlay_id)` formate
|
||||
`o:{repo_id}:v:{overlay_id}` ; dans `doc_create` la valeur injectée est
|
||||
`store.outer_overlay()` — le store **contenant**, jamais le `repo_id`. Un `Repo` ne
|
||||
porte **aucun** champ overlay (seulement `store: Arc<Store>`) ; c'est `Store` qui
|
||||
porte `overlay_id`. **Contre-preuve mécanique** : dans `Store`, `get`/`put`/`del`/`has`
|
||||
passent tous `&self.overlay_id` au block storage — tous les documents d'un store
|
||||
partagent le namespace de blocs, donc un overlay par-document est structurellement
|
||||
impossible.
|
||||
Used to surface a branch's / root branch's read cap (`engine/verifier/src/verifier.rs:278,320`; `rocksdb_user_storage.rs:162,172`).
|
||||
|
||||
### La conséquence à connaître : le `:v:` est un pseudonyme stable
|
||||
So a ReadCap is **not** "a NURI with `:k:{key}` appended". It is an opaque `r:` segment carrying the whole `ObjectRef { id, key }`. Note also that **no regex matches a cap-bearing repo NURI**: `RE_REPO_O` (`did:ng:o:{id}`) and `RE_REPO` (`…:v:{overlay}`) are both cap-less, and `RE_COMMIT`/`RE_FILE_READ_CAP` are about commits and files, not repos (`net/types.rs:48-73`).
|
||||
|
||||
**Tous les documents d'une même personne dans son store protected portent le MÊME
|
||||
`:v:`** = `outer(protected_store_id)`. Donc une référence cap-less — précisément
|
||||
celle qu'on utilise pour « nommer sans donner à lire » — **expose l'appartenance
|
||||
au store**, c'est-à-dire un **identifiant pseudonyme stable et permanent de la
|
||||
personne**. Le store_id lui-même ne fuit pas (BLAKE3 non inversible), donc ça ne
|
||||
dit pas *qui* ; mais c'est un **handle constant**, le même partout et pour
|
||||
toujours, corrélable par quiconque collecte des références cap-less.
|
||||
The `:k:` forms, for completeness:
|
||||
- `did:ng:j:{id}:k:{key}` — object/file read cap (`RE_FILE_READ_CAP` types.rs:48)
|
||||
- `did:ng:o:{repo}:c:{commit}:k:{key}` (`RE_COMMIT` types.rs:72)
|
||||
- list `RE_OBJECTS` `…:[cj]:{id}:k:{key}…:l:{locator}` (types.rs:63)
|
||||
|
||||
**Le couplage qui en résulte, et qui contraint tout modèle de présence anonyme** :
|
||||
ce même `:v:` est *simultanément* (a) ce qui permet de **dédupliquer** des
|
||||
références sans les lire — deux références de même `:v:` viennent de la même
|
||||
personne — et (b) ce qui permet de **tracer** cette personne d'un contexte à
|
||||
l'autre. **C'est le même bit d'information.** On ne peut pas obtenir la dédup sans
|
||||
concéder le traçage, ni supprimer le traçage sans perdre la dédup — sauf à changer
|
||||
le découpage en stores, ce qui déplace le curseur mais ne supprime pas l'arbitrage.
|
||||
The `:v:` segment is the **overlay**, which has its own section below — it is the point with the heaviest consequences for anonymous-presence models.
|
||||
|
||||
*Nuances.* Le `:v:` du NURI est l'overlay **outer**, alors que le trafic
|
||||
client↔broker et le stockage local utilisent l'**inner** — valeur différente, mais
|
||||
tirée du store elle aussi, donc la propriété tient dans les deux cas. Un store
|
||||
`Dialog` renvoie un `Inner`, toujours store-scopé.
|
||||
## 4bis. The overlay is the network space of a STORE — never of a document
|
||||
|
||||
INFÉRÉ : un détenteur **sans clé** peut vraisemblablement **récupérer les blocs
|
||||
chiffrés** (avec l'overlay, toujours cap-less) → vérifier l'**existence** d'un doc
|
||||
sans lire son **contenu**. Le chemin d'autorisation de fetch broker pour un
|
||||
détenteur sans clé n'a **pas** été tracé — à confirmer avant de s'en servir.
|
||||
**The overlay is a store's unit of network addressing.** At the broker, blocks are filed under a `(overlay, block_id)` key, and peers synchronize *within* an overlay. Two forms per store:
|
||||
|
||||
## 5. Ce que le polyfill émule (caps.ts) — et où ça diverge
|
||||
|
||||
`packages/client/src/caps.ts` modélise `readers: Map<Nuri, Set<PrincipalId>>` +
|
||||
`grantRead(doc, grantee)` (`:29-30, 41-42`) — **une ACL de principals par
|
||||
document, soit l'INVERSION exacte du modèle réel** (clé). Divergences :
|
||||
|
||||
| | Réel NextGraph | Émulation caps.ts |
|
||||
| | Derivation | Who can compute it |
|
||||
|---|---|---|
|
||||
| Nature | possession de **clé** | **ACL** (set de principals) |
|
||||
| Grant | sceller la clé (crypto_box) à l'inbox | ajouter un principal au set |
|
||||
| Durabilité | **durable** (clé livrée une fois) | **éphémère** (Map vide à chaque session → re-déclarée) |
|
||||
| Révocation | **re-key** grossier, non-rétroactif | retrait du set : **instantané et total** |
|
||||
| Granularité | repo / branche / commit / objet | **un cap par doc-NURI** |
|
||||
| Réf. sans droit | **NURI cap-less** (sans `:k:`) | pas de notion (l'ACL dit qui peut) |
|
||||
| **outer** | `OverlayId::outer(store_id)` = **public** BLAKE3 | everyone (the store_id is enough) |
|
||||
| **inner** | `OverlayId::inner(store_id, readcap_secret)` = **keyed** BLAKE3 | only whoever holds the store's read key |
|
||||
|
||||
**Face app** : `declareConnections` (côté consommateur) qui re-déclare « mes
|
||||
connexions lisent mes entités protected » **à chaque session** est un **artefact
|
||||
de cette ACL éphémère** — sans objet dans le modèle réel (les scellages y sont
|
||||
durables ; on scelle par-doc au partage, pas par-session).
|
||||
Consistent with the rest of the model: no role and no list, only "do you hold the key that lets you derive this identifier". `outer` = the store's public name, `inner` = its private name.
|
||||
|
||||
## 6. Implications pour les consommateurs (ex. Festipod)
|
||||
**The `:v:` of a DOCUMENT NURI carries the overlay of its STORE** (VERIFIED, chain read end to end): `NuriV0::repo_graph_name(repo_id, overlay_id)` formats `o:{repo_id}:v:{overlay_id}`; in `doc_create` the value injected is `store.outer_overlay()` — the **containing** store, never the `repo_id`. A `Repo` carries **no** overlay field (only `store: Arc<Store>`); it is `Store` that carries `overlay_id`. **Mechanical counter-proof**: in `Store`, `get`/`put`/`del`/`has` all pass `&self.overlay_id` to the block storage — every document of a store shares the same block namespace, so a per-document overlay is structurally impossible.
|
||||
|
||||
- « **scope protected = mon réseau peut lire** » n'est **pas** une ACL vérifiée
|
||||
par le broker : c'est « j'ai **scellé ma read key** à chacune de mes
|
||||
connexions ». Le modèle mental « scope = ACL » est faux au niveau NextGraph.
|
||||
- **Références anonymes possibles** : mettre un **NURI cap-less** dans une
|
||||
collection tierce laisse le tiers **nommer/compter** sans **lire l'identité** ;
|
||||
sceller le cap-porteur séparément aux seuls autorisés. (Base d'un modèle de
|
||||
présence « participation auto-possédée + Set curé cap-less + cap scellé aux
|
||||
connexions ».)
|
||||
- **Alignement à faire** : quand les vraies opérations de cap seront disponibles,
|
||||
remplacer l'ACL émulée par du scellage de clé durable par-doc, et
|
||||
`declareConnections`-comme-ACL-ré-déclarée disparaît.
|
||||
### The consequence to know about: the `:v:` is a stable pseudonym
|
||||
|
||||
## Réserves / lacunes
|
||||
**All of one person's documents in their protected store carry the SAME `:v:`** = `outer(protected_store_id)`. So a cap-less reference — precisely the one used to "name without granting read" — **exposes store membership**, that is to say a **stable and permanent pseudonymous identifier of the person**. The store_id itself does not leak (BLAKE3 is not invertible), so it does not say *who*; but it is a **constant handle**, the same everywhere and forever, correlatable by anyone who collects cap-less references.
|
||||
|
||||
- `file:line` datés (2026-07) — re-vérifier par symbole ; le core bouge.
|
||||
- INFÉRÉ : fetch broker keyless (existence sans clé) — non tracé au runtime.
|
||||
- Non tracé : exécution complète de `RootCapRefresh` côté verifier
|
||||
(`verifier/src/commits/mod.rs:616`), stockage wallet de `private_store_read_cap`
|
||||
(`repo/types.rs:945,976`).
|
||||
**The coupling that results, and that constrains any anonymous-presence model**: that same `:v:` is *simultaneously* (a) what makes it possible to **deduplicate** references without reading them — two references with the same `:v:` come from the same person — and (b) what makes it possible to **track** that person from one context to another. **It is the same bit of information.** You cannot get the dedup without conceding the tracking, nor remove the tracking without losing the dedup — short of changing how the stores are carved up, which moves the cursor but does not remove the trade-off.
|
||||
|
||||
*Nuances.* The NURI's `:v:` is the **outer** overlay, whereas client↔broker traffic and local storage use the **inner** one — a different value, but derived from the store as well, so the property holds in both cases. A `Dialog` store returns an `Inner`, still store-scoped.
|
||||
|
||||
**CORRECTED on 2026-07-27 — this hypothesis was FALSE.** We had inferred, then believed we had verified, that a holder **without a key** could fetch the encrypted blocks and therefore prove a document's **existence**. An adversarial review showed that the reasoning stopped at *access control* without looking at **addressing**:
|
||||
|
||||
- There is **no existence command at the SDK level**.
|
||||
- The only probe (`BlocksExist`) is **internal to the crate**, requires `BlockId`s **and** an already **loaded** repo, and addresses the **inner** overlay — which is derived from the **read secret**.
|
||||
- A cap-less reference carries a RepoId and the **outer** overlay: no `BlockId` to probe. And the outer is never registered anyway (`expose_outer` hard-coded to `false`, with no SDK parameter).
|
||||
- The primitive a non-member can reach (`ExtObjectGet`) requires the **ObjectIds**, which one only holds once one can already read. *(Corrected 2026-08-10 — this line used to say "the ObjectIds **and their keys**", and to call `ExtObjectGet` the **only** such primitive. Both are wrong at the source: `ExtObjectGetV0 { overlay, ids: Vec<ObjectId>, include_files }` has **no key field** at all (`engine/net/src/types.rs:4492-4501`), and `ExtRequestContentV0` has **three** variants — `WalletGetExport`, `ExtObjectGet`, `ExtTopicSyncReq` (`:4520-4526`), the last of which falls into `unimplemented!()` (`:4533`). The conclusion is unchanged and rests on addressing, not on keys: blocks come back **encrypted**, and naming them needs ObjectIds a non-holder does not have — the formulation `docs/nextgraph-current-state.md` § "The `Ext` protocol serves blocks with no control" already carried.)*
|
||||
|
||||
> **Addressing itself presupposes the cap.** Proving a document's existence without holding its key is not constructible today, and nothing indicates that it is planned.
|
||||
|
||||
Transferable lesson: verifying that an access guard **lets you through** does not prove that an operation is reachable — you still have to be able to **name** what you are asking for.
|
||||
|
||||
## 4ter. The public store: readable by URL, and NOT recursive
|
||||
|
||||
Target principle (confirmed by the PO, 2026-07-27):
|
||||
|
||||
> **An element of the public store is public: whoever has the URL reads the content.**
|
||||
> But **not recursively** — public content can *reference* private content, and the reference does **not** give access to the referenced.
|
||||
|
||||
This is a **second mechanism**, alongside key possession (§1) — not a breach of it. And it is the **non-recursiveness** that carries the value: it allows a public object that **points** to private identity, without divulging it. That is exactly the pattern an anonymous-presence model needs.
|
||||
|
||||
*Implementation detail, NOT to be carried by the shape*: NextGraph is moving toward **not encrypting** the content of the public store (the data remaining **signed**). A surface must not depend on it. And if the public store does not behave the way this principle describes, it is **the polyfill** that adapts, not the consumer.
|
||||
|
||||
## 4ter-bis. THERE IS NO DISCOVERY — you only ever follow links
|
||||
|
||||
**Stated by the PO, 2026-07-30, as one of NextGraph's foundations.** It bears on more design decisions than any other point in this document, and it is the easiest to violate without noticing, so it is stated before anything is built on top of it:
|
||||
|
||||
> **You cannot discover. You can only follow links.**
|
||||
|
||||
NextGraph is **local-first**. There is no global index, no registry, no crawler, no "list everything public" — and nothing of the kind is planned. Nothing exists *to be found*; things exist *to be reached*, and reaching them means someone handed you the way in.
|
||||
|
||||
So **publishing is two acts, never one**:
|
||||
|
||||
1. **Place** the data in your public store — that makes it readable *by whoever reaches it*, not visible;
|
||||
2. **Circulate the link** — post it into inboxes, or put it somewhere already reachable by the people concerned (a document they already hold).
|
||||
|
||||
And it is seen **only by those who received the information**, i.e. the link. There is no audience beyond the people you reached, and no way to enumerate one. Private distribution is the same act, plus the ReadCap: place, then circulate — the cap being what turns "reached" into "readable".
|
||||
|
||||
**The consequences, which are not obvious:**
|
||||
|
||||
- **A "global list of everything public" is not constructible**, and a surface that offers one exposes a capability the target will never have — precisely the failure mode this whole chantier exists to prevent. Whatever such a surface is emulated on, it teaches the consumer a model that does not exist.
|
||||
- **Reachability is a graph, not a directory.** The only way in is a link somebody gave you: in an inbox, or inside a document you already hold. Which is why the inbox is not a side feature — it is *the* bootstrap of the whole graph, the only channel through which a link crosses from one wallet to another.
|
||||
- **This is what makes §4ter operational.** "Whoever has the URL reads the content" is not a weaker form of public: the URL *is* the access. Having it means someone gave it to you.
|
||||
- **An audience cannot be counted, only addressed.** No primitive answers "who can see this"; you know who you sent it to.
|
||||
|
||||
### And the second reason, which stands on its own: nothing is COMMON
|
||||
|
||||
Even setting discovery aside, a global index is **data shared between users/wallets**, and that is not acceptable in an emulation whose whole job is to simulate the boundary of a single-user wallet (PO, 2026-07-30):
|
||||
|
||||
> Nothing common — only **indexing mechanisms to make the virtual users work**.
|
||||
|
||||
The distinction is the operative one, and it is sharp:
|
||||
|
||||
| | Verdict | Why |
|
||||
|---|---|---|
|
||||
| The **shim** (pointer → doc-shim → account → its scope documents) | **acceptable** | pure plumbing: it holds no user data, only the table that makes a virtual user resolvable at all. Remove it and no wallet exists. |
|
||||
| A **discovery index** (announcements deposited by users, read by everyone) | **not acceptable** | it is application data pooled across wallets. Remove it and every wallet still works — you simply have to be given links, which is the model. |
|
||||
|
||||
The test to apply to anything shared: *does removing it stop the virtual users from functioning, or does it merely stop users from seeing each other's content?* Only the first justifies existing outside a wallet.
|
||||
|
||||
*Impact on this library, RESOLVED 2026-07-30 — the module was removed*: `discovery.ts` (a global index owned by a reserved `@index` account, `submitToIndex` / `readIndex` / `watchIndex`) emulates exactly the capability described above as non-existent, **and** holds pooled user data, and `watchShape('public')` folds it into its read set. The ADR that specified it ([`decisions/discovery-model.md`](decisions/discovery-model.md)) already recorded that a freely-readable global index "is not a NextGraph shape" and rested on a singleton-app path that is "not implemented, uncertain". That reservation is now a verdict on both counts. See [`briefs/2026-07-30-virtual-wallet-boundary.md`](briefs/2026-07-30-virtual-wallet-boundary.md).
|
||||
|
||||
## 4quater. Where an owner gets the caps for THEIR OWN documents — the Store branch
|
||||
|
||||
**There is no "keyring" object in NextGraph, and this section used to say there was.** It read *"the store branch **is** the owner's keyring… upstream of that, the keyring is the wallet"*, which is wrong twice: the wallet holds **one** key per user (the private store's read cap, §4quinquies level 1), not every key; and the caps of one's own documents live on a **Store branch**, per store, not in any single trousseau. An agent built a global in-memory "keyring" on that sentence. Corrected 2026-07-30 on the PO's instruction — *use the Store branch logic, not an invented keyring*.
|
||||
|
||||
What is actually true:
|
||||
|
||||
On every document creation, an `AddRepo { read_cap }` is committed to the store's **Store branch** — the store being itself a repo with **typed** branches (the word "branch" has nothing to do with git: it is a compartment with a defined role, its own pub/sub topic, and here `BranchCrdt::None` — service commits, not triples). That branch lists **the store's documents, each with its read cap**, and replaying it is what reloads them (`AddRepo::verify` → `load_repo_from_read_cap`, `engine/verifier/src/commits/mod.rs:644-664`).
|
||||
|
||||
So the answer to *"how does an owner find the cap of a document they created?"* is: **it is on the Store branch of the store that document lives in** — one such branch per store, reached from the root key the wallet does hold.
|
||||
|
||||
**This is NOT the sharing mechanism.** An easy and costly confusion: concluding "we share at the store level" is wrong — delivering a store's cap would give access to **all** of its content, present and future. **The unit of sharing is the document** (§2), and a cap received for someone else's document goes somewhere else entirely (`AddLink` on the User branch, §4quinquies).
|
||||
|
||||
*(VERIFIED for the `AddRepo { read_cap }` mechanism and for `BranchType::Store` / `BranchCrdt::None`; the full enumeration of branch types is in `engine/repo/src/types.rs:1536-1551`.)*
|
||||
|
||||
## 4quinquies. WHERE the caps actually live — three levels, and one of them does not exist yet
|
||||
|
||||
**VERIFIED 2026-07-30** by reading `nextgraph-rs` (`git 213338f6`), answering "where does a received cap get stored?".
|
||||
|
||||
### Nomenclature first — `wallet` in the source is NOT what we call a wallet
|
||||
|
||||
A **wallet is only a keyring**. What we have been calling a "virtual user" is, upstream, a **user** (a *site*): `SensitiveWalletV0.sites: HashMap<String, SiteV0>` (`engine/wallet/src/types.rs:434,457`) — one wallet holds SEVERAL sites. `SiteV0` (`engine/verifier/src/site.rs:23`) is what owns the three stores (`public`, `protected`, `private`), and `UserId = PubKey` (`engine/repo/src/types.rs:453`). **Our vocabulary must follow: virtual user → user.**
|
||||
|
||||
### The three levels
|
||||
|
||||
**1. The wallet (keyring) holds ONE root key per user.** `SiteV0.site_type = SiteType::Individual((priv_key, read_cap))`, read back by `get_individual_site_private_store_read_cap` (`site.rs:52`) — the read cap of the **private store**, and nothing else. Everything else is reached *from* it. Following links applied to your own data.
|
||||
|
||||
**2. The store's own branch carries `AddRepo { read_cap }` — one per document.** `doc_create` performs **four distinct writes**; the two that matter here (`engine/verifier/src/request_processor.rs:697-710`):
|
||||
|
||||
- `send_add_repo_to_store` → a commit `AddRepo { read_cap }` on the **Store branch** of the store (`verifier.rs:2172-2199`) — *the key*;
|
||||
- `INSERT DATA { <store> ldp:contains <doc> }` on the store's **main branch** — *the listing*.
|
||||
|
||||
*(The other two: the class quad on the **Header** branch, `request_processor.rs:719-728`; and `AddSignerCap` on the private store's **User** branch, `verifier.rs:3022-3040`.)*
|
||||
|
||||
**The key and the list are separate, deliberately.** Replaying the Store branch is what reloads the repos with their keys: `AddRepo::verify` calls `load_repo_from_read_cap` then `add_doc` (`engine/verifier/src/commits/mod.rs:644-664`). Our `shim:contains` emulates `ldp:contains` and `shim:readCap` (on a `storeBranch` subject) emulates `AddRepo` — so a created document's cap is stored beside it and read back, not recomputed.
|
||||
|
||||
> **The Store branch holds NO triples.** Its CRDT is `BranchCrdt::None` — *"used by Overlay, Store and User BranchTypes"* (`engine/repo/src/types.rs:1420`; `store.rs:426`). It is a stream of **service commits** (`AddRepo` / `RemoveRepo`), not a graph. Any RDF we use to emulate it is our invention, and should be labelled as such rather than presented as "the same thing".
|
||||
|
||||
**3. Local user storage persists the read cap of EVERY opened repo.** `user_storage/repo.rs` stores `READ_CAP` as a property per repo (`:109,:219,:248,:359`), and a persistent verifier reloads from it at startup (`verifier.rs:542-544`). This is a **local store (RocksDB / IndexedDB), not a NextGraph document** — the verifier's own cache, per user.
|
||||
|
||||
### Giving access is a **Link** — one word, three places, all already named
|
||||
|
||||
**VERIFIED 2026-07-30, state column corrected 2026-08-10.** The delivery message, the register and the record all exist upstream under the same word, which is what a shape being real looks like. What none of them is, is *implemented* — the table said so of three rows, and re-reading the source refuted it:
|
||||
|
||||
| Step | Upstream | State |
|
||||
|---|---|---|
|
||||
| The message deposited in the recipient's inbox | `InboxMsgContent::Link` (`engine/net/src/types.rs:4249-4261`) | **declared, payload-less** — a variant with no fields, i.e. specified and not implemented |
|
||||
| Where the recipient files it on processing | `AddLink { read_cap }` on the **User branch** of the private store (`engine/repo/src/types.rs:1934-1950`) | **declared, stubbed** — the verifier arm is a no-op `Ok(())` (`engine/verifier/src/commits/mod.rs:681-693`), and nothing in the workspace constructs one |
|
||||
| Withdrawing it | `RemoveLink`, ORset (`engine/repo/src/types.rs:1952`) | **declared, stubbed** — the same no-op `Ok(())` arm (`commits/mod.rs:695-707`) |
|
||||
| What circulates | `RepoLinkV0 { read_cap, … }` (`engine/net/src/types.rs:5062-5078`) | **declared only** — zero constructors and zero consumers in the workspace (only the `RepoLink` wrapper and its two accessors, `:5082-5097`) |
|
||||
|
||||
**What makes "stub" the right word rather than a quibble**: the neighbouring arm in the same file does real work. `CommitVerifier for AddRepo` calls `load_repo_from_read_cap` then `add_doc` (`commits/mod.rs:644-664`); `AddLink` and `RemoveLink`, twenty lines below, return `Ok(())` with `#[allow(unused_variables)]` on every parameter. Same trait, same file, opposite states — so "there is a verifier arm" cannot be read as "the register works".
|
||||
|
||||
So: **deposit a Link into the recipient's inbox; on connection the recipient processes the inbox and files it with `AddLink` on their User branch.** That is the whole gesture, and every piece of it has a **name** — which is not the same as having a behaviour. Per this document's own rule, none of that says what the target will do; it says the gesture is fully specified and none of it runs.
|
||||
|
||||
Two consequences worth stating, because both are easy to get wrong:
|
||||
|
||||
- **What travels is a cap-BEARING reference.** A bare NURI in a Link grants nothing — it names a document the recipient still cannot open. `AddLink` carries a `read_cap`, not a `RepoId`.
|
||||
- **`ContactDetails` is a different gesture.** It shares a *profile* (with an optional `read_cap` on it), not an arbitrary document. Do not route document sharing through it.
|
||||
|
||||
### A cap received from someone else: the **User branch**, via `AddLink`
|
||||
|
||||
**CORRECTED 2026-07-30 after adversarial review — an earlier version of this section claimed there was no register at all. That was wrong, and it was the kind of wrong this document exists to prevent: concluding "it does not exist" from having looked in one place.**
|
||||
|
||||
There IS a register, and it is a fourth commit type next to `AddRepo`:
|
||||
|
||||
```rust
|
||||
/// Adds a link into the user branch, so that a user can share with all its device a new Link they received.
|
||||
/// The repo's `store` field should not match with any store of the user. Only external repos are accepted here.
|
||||
pub struct AddLinkV0 { pub read_cap: ReadCap, /* … */ }
|
||||
```
|
||||
|
||||
`engine/repo/src/types.rs:1934-1950`, with `RemoveLink` as its ORset counterpart (`:1952`) and a verifier arm — a no-op `Ok(())` one — at `engine/verifier/src/commits/mod.rs:681-693`. So:
|
||||
|
||||
- it lives on the **User branch** — created only on the **private store** (`engine/repo/src/store.rs:448-452`; the public/protected stores get an `Overlay` branch instead), which also carries `AddInboxCap { repo_id, overlay, priv_key }` — *"so that a user can share with all its device"* (`engine/repo/src/types.rs:1969-1981`). So the User branch answers two questions with one mechanism: **which caps I received**, and **which inboxes I may read**;
|
||||
- it is explicitly for **external repos** — someone else's documents, exactly the received-cap case;
|
||||
- and its stated purpose is to **share the link with all of the user's devices**. It is wallet-resident and cross-device, not a local cache.
|
||||
|
||||
**Level 3 (local user storage) is therefore a cache, not the register.** The register — the durable, cross-device record — is level 2': `AddLink` on the User branch of the private store.
|
||||
|
||||
**But "the register exists, only the delivery is missing" is FALSE, and this section said it until 2026-08-10.** Both ends are declared and stubbed, as the table above now records: nothing constructs an `AddLink` commit anywhere in the workspace, and the arm that would apply one returns `Ok(())`. So the corrected statement is: `AddLink` on the User branch is **where a received cap belongs in the model** — a placement the source states unambiguously and this library aligns on — and no part of the gesture runs today, neither the road nor the destination. Per the design principle that gap says nothing about the target; it forbids only calling the register "implemented".
|
||||
|
||||
The delivery half, in detail:
|
||||
|
||||
- `InboxMsgContent::ContactDetails` processing (`engine/verifier/src/inbox_processor.rs:778-847`) creates a contact document holding the profile, inbox, name and email — and **never reads `details.read_cap`**. Confirmed on sight: the receiver discards it. So no cap reaches the User branch today.
|
||||
- `RepoLinkV0` states the intended flow (`engine/net/src/types.rs:5055-5061`): *"the link is shared and then the recipient opens it and subscribes soon afterward"*. **The key IS kept**: opening the repo persists its `read_cap` in local user storage, so the next session decrypts fine. What is not durable is the key's **validity** — a `RootCapRefresh` (§3) mints a new one, and receiving it depends on **the rotating party choosing to send it to you** (§3's DIRECTION block), not on any subscription state.
|
||||
|
||||
> **Do not write "only a subscriber receives the new key".** That reads the `RepoLinkV0` comment as intent, which §3 already forbids. **Subscribing is a purely LOCAL act** — automatic pull of changes — and the other party records nothing about it; there is no subscriber list to send to. Who gets a rotated key is the rotating party's decision, delivered to an inbox.
|
||||
- `PermaCap` — still a **TODO** (`engine/repo/src/types.rs:578`) — covers exactly the gap that leaves: a link *"stored on disk and kept there unopened for a long period"*, i.e. never loaded, therefore never subscribed, therefore missing every refresh.
|
||||
|
||||
> **So there are TWO registers, by origin**: `AddRepo` on the **Store** branch for the documents a user creates in that store, and `AddLink` on the **User** branch of the private store for caps received for someone else's documents. (`AddRepo` runs; `AddLink` is declared and stubbed — see the table above. The *split by origin* is the model's, whatever each half's state.) Local user storage caches both. Opening a repo persists its cap locally, but that is the cache filling — not the durable record.
|
||||
|
||||
*Consequence for this library*: **both durable registers are now emulated** (2026-07-30) — `AddRepo` as a `shim:readCap` record on a distinct subject of the store document (`storeBranch`), `AddLink` as `shim:link` on another (`userBranch`) — and the in-memory `CapRegistry` is what it always was, level 3: the cache. Caps are READ back from those records, never recomputed. What stays an invention is representing branches as RDF subjects at all: upstream both branches carry `BranchCrdt::None` and hold service commits, not triples. What is faithful is that the key sits beside the document, and that the listing (`contains`, the Main branch) is separate from the keys.
|
||||
|
||||
## 4sexies. What a NURI TRANSPORTS — and the TWO acts that cover every use of it
|
||||
|
||||
**VERIFIED 2026-08-06** by reading `nextgraph-rs`, after a design discussion kept stalling on an assumed split between "a NURI" and "a link". There is no such split, and getting that wrong is what made this library ship a `linkTo` that was wrong three ways at once.
|
||||
|
||||
### A NURI and a Link are one thing in two shapes
|
||||
|
||||
`NuriV0` (`engine/net/src/app_protocol.rs:181-194`) carries exactly what a link carries:
|
||||
|
||||
```rust
|
||||
NuriV0 { identity, target, entire_store, objects, signature,
|
||||
branch, overlay, access: Vec<NgAccessV0>, topic, locator: Option<Locator> }
|
||||
```
|
||||
|
||||
`NgLinkV0 = Repo | PublicRepo | Branch | Object` (`engine/net/src/types.rs:5206-5211`) is the structured form of the same information; the NURI is its URI form. So "should we hand out a NURI or a link?" is not a question — they are the same thing, and the real question is **what one puts in the `access` and `locator` slots**.
|
||||
|
||||
*Caveat, and it matters for anything printed on paper:* the **type** has all the slots, the **string grammar does not expose them all**. A self-contained share URL exists for objects, commits and files (`…:v:{overlay}(:[cj]:{id}:k:{key})+:l:{locator}`); the repo case is not exercised. See [`document-links.md`](./document-links.md).
|
||||
|
||||
### `access` is a LIST of access forms, not a key flag
|
||||
|
||||
```rust
|
||||
NgAccessV0 = ReadCap(ReadCap) | Token(Digest) | ExtRequest(Vec<u8>)
|
||||
| Key(BlockKey) | Inbox(PrivKey) | Topic(PrivKey)
|
||||
```
|
||||
|
||||
(`app_protocol.rs:54-62`.) An **empty** `access` is therefore a legitimate, meaningful state: the reference NAMES its target and grants nothing. That is not a degenerate link — see below, it is the common case.
|
||||
|
||||
### There are TWO acts, and they cover everything
|
||||
|
||||
An earlier version of this section listed four "needs" (name, let read, let find, join). That was wrong: it confused what an act DOES with what its result depends on. A sender does exactly two things, and every use case is one of them:
|
||||
|
||||
| Act | What is transmitted | What the recipient can do |
|
||||
|---|---|---|
|
||||
| **Transmit the reference** | `target` (+ `overlay`/`locator`), `access` EMPTY | Name the document. **And read it, if it sits in a public store** — same value transmitted, different outcome, decided by where the document is and not by what was sent. |
|
||||
| **Transmit the reference AND the key** | the above + `ReadCap` in `access` | Read it. Irreversible: nothing is checked later, and there is no revoking a key already handed out (only rotation, which also cuts off legitimate recipients — `PermaShare`/PermaCap, `engine/repo/src/types.rs:1761`, is the reserved answer, unimplemented). |
|
||||
|
||||
"Let someone find a public document" is therefore not a third act: it is the first one, applied to a document that happens to be in a public store. And "join" is not an act at all — the `locator` is about the reference being COMPLETE enough to be resolved by a stranger (no locator → no broker to ask → nothing opens, key or no key). It belongs to the recipient's side.
|
||||
|
||||
The consequence for anything this library exposes: **a call either hands over the key or it does not**, and that must be the caller's explicit intent — never a side effect of asking for a reference.
|
||||
|
||||
### Three confusions worth naming, because each one was made here
|
||||
|
||||
**"No key" does not mean "public".** A key-less reference to a PROTECTED document withholds access deliberately — the recipient can name it, not read it. A `PublicRepoLinkV0` (`types.rs:5105-5127`) carries no `read_cap` for an unrelated reason: the content is served publicly, so there is nothing to hand over. Same shape, opposite situations.
|
||||
|
||||
**Naming is not reading, and it is the DEFAULT act.** This is what `test/cross-user-access.test.ts` proves: Alice has a document in a public store that REFERENCES her protected one; Bob follows the public link, finds the reference, and can name the protected document while reading nothing of it. Publication is not recursive. Withholding the key is the ordinary, reversible gesture; including it is the exceptional, irreversible one.
|
||||
|
||||
**Nothing is checked at access time.** Reading IS possession — the engine verifies a permission on WRITE only (`verify_permission` → `PermissionDenied` in `Commit::verify`), never on read. So a reference cannot be "neutral about rights, resolved later": what you put in it IS the grant. There is no revoking a link you have circulated, only rotating the key (and `RepoLinkV0`'s own comment says shared caps go stale on refresh — `PermaShare` / PermaCap, `engine/repo/src/types.rs:1761`, is the reserved answer to that, unimplemented).
|
||||
|
||||
### Where this library stands, act by act
|
||||
|
||||
- **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 (`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:
|
||||
|
||||
- Upstream nothing is WRITTEN to make a repo public — the store is public and the broker serves it. Here one broker serves every virtual user identically, so the cap is recorded on the document's Header branch and read back through the machinery's unguarded door. Fetching, not enumerating: a reader asks the document it already names.
|
||||
- A reader therefore learns a document is public by asking THAT document. One it has never heard of stays invisible, where upstream a broker would serve it just the same. That limits discovery, not access.
|
||||
- The cap a public store serves is a READ grant, and this emulation says so: `caps.learnFromPublicStore` files it apart, and `docs.sparqlUpdate` refuses a write on it (`assertMayWrite`). Without that, a bare reference would buy a write, which upstream it never does — writing needs the write cap, and no store hands that out.
|
||||
- `useShape` cannot ask (its signature is the real ORM's, with no await to spend), so a public document reached through it alone, read nowhere first, is filtered out. Recorded in `emulated-verifier/read-filter.ts`.
|
||||
- **No `locator` anywhere**, and the emulation's topology is why it does not show. Upstream a reference must be complete enough for a stranger to resolve — without a `locator` there is no broker to ask, and nothing opens, key or no key (`NuriV0.locator`, `engine/net/src/app_protocol.rs:181-194`). Here every virtual user is on the same broker, so the question never arises and no reference this library produces carries one. An application must not conclude that a bare reference travels anywhere: **it travels between users of one deployment**. The day two deployments have to exchange one, the locator is what will be missing, and nothing in the emulation will have prepared it.
|
||||
|
||||
One thing a consumer must not conclude from the emulation: that a public document has anything per-reader. Upstream there is no grant, no revoke and no audience on it — there is nothing to build a UI around.
|
||||
|
||||
## 5. What the polyfill emulates (caps.ts) — and where it still diverges
|
||||
|
||||
**Realigned 2026-07-28 (the cap-surface batch).** `packages/polyfill/src/emulated-verifier/caps.ts` used to model `readers: Map<Nuri, Set<PrincipalId>>` + `grantRead(doc, grantee)` — a per-document **ACL of principals**, the exact INVERSION of the real model. It now records, **per identity**, the caps that identity holds (`Map<Nuri, ReadCap>`) — whose only question is `capFor(nuri)` — and `nuri.ts` carries the cap-less / cap-bearing distinction on the `r:` segment. The durable registers are emulated in `shared-wallet/account-registry.ts` (`readCap` on the Store branch, `link` on the User branch); this in-memory record is their cache.
|
||||
|
||||
| | Real NextGraph | caps.ts emulation (post-cap-surface) |
|
||||
|---|---|---|
|
||||
| Nature | possession of a **key** | possession of a **key** — recorded per identity, indexed by the cap-less NURI |
|
||||
| Grant | seal the key (crypto_box) to the inbox | `inbox.share(doc, toUser)` → an inbox deposit, absorbed inline on read |
|
||||
| Durability | **durable** (key delivered once) | durable **in shape**: creation and re-listing refile own caps from the scope index (the emulated `AddRepo` branch); a delivered cap persists in the recipient's inbox document |
|
||||
| Revocation | coarse **re-key**, non-retroactive | **not emulated** (P3). Nothing pretends to revoke |
|
||||
| Granularity | repo / branch / commit / object | **one cap per doc-NURI** |
|
||||
| Ref. without rights | **cap-less NURI** (no `r:` segment) | same — `Nuri` names, `ReadCap` names and reads |
|
||||
| Public store | the broker serves the outer overlay; the ReadCap is **downloaded** from it | `public-store.ts` — the cap is exposed on the document and fetched through the machinery's door, then held like any other. Filed apart (`learnFromPublicStore`) so it grants reading and **not** writing |
|
||||
|
||||
**The divergence that REMAINS**: the stand-in cap value is the constant `OK` rather than a secret. The read paths that once consulted no cap at all are now confined to the connected virtual user (`emulated-verifier/reach.ts`, 2026-07-30) — `docs.sparqlQuery`/`sparqlUpdate` and `subscribeDoc` are guarded, the inbox is read only by its owner, and the shim's own machinery moved to unguarded primitives that are never exported. So what is left for **cap-enforcement** is per-document encryption: replacing one constant with a real key. Until then, nothing may be claimed "anonymous" or "private".
|
||||
|
||||
**App-facing**: `declareConnections` (on the consumer side), which re-declared "my connections read my protected entities" **every session**, was an artifact of the ephemeral ACL — **it disappears**. The grant moves to the moment a connection is accepted (`inbox.share` once, per document), which is a consumer **re-architecture**, not an API swap.
|
||||
|
||||
## 6. Implications for consumers (e.g. Festipod)
|
||||
|
||||
- "**protected scope = my network can read**" is **not** an ACL checked by the broker: it is "I have **sealed my read key** to each of my connections". The "scope = ACL" mental model is wrong at the NextGraph level.
|
||||
- **Anonymous references are possible**: putting a **cap-less NURI** in a third party's collection lets that third party **name/count** without **reading the identity**; the cap-bearing one is sealed separately to the authorized parties only. (Basis for a presence model of the form "self-owned participation + curated cap-less Set + cap sealed to the connections".)
|
||||
- **Alignment DONE for the surface (cap-surface, 2026-07-28)**: the emulated ACL is gone, replaced by per-identity cap possession + per-document delivery to an inbox; `declareConnections`-as-a-re-declared-ACL has disappeared. What remains for the real cap operations is swapping the stand-in key value (`OK`) for the real one and closing the bypasses (cap-enforcement) — a key-material step, not a reshape. See `migration-guide.md` §1.
|
||||
|
||||
## Caveats / gaps
|
||||
|
||||
- `file:line` references are dated (2026-07) — re-verify by symbol; the core moves.
|
||||
- ~~INFERRED: keyless broker fetch (existence without a key)~~ — **RESOLVED and REFUTED, 2026-07-27**: not constructible. See the CORRECTED block in §4bis. Kept struck through because the hypothesis is intuitive and will otherwise be re-formed.
|
||||
- Not traced: the full execution of `RootCapRefresh` on the verifier side (`verifier/src/commits/mod.rs:616`), wallet storage of `private_store_read_cap` (`repo/types.rs:945,976`).
|
||||
|
||||
+328
-191
@@ -11,7 +11,7 @@
|
||||
> file for *how* each emulation works; read those two for *what is fake* and *what
|
||||
> replaces it*.
|
||||
|
||||
The consumer application writes against `@ng-eventually/client` as if NextGraph
|
||||
The consumer application writes against `@ng-eventually/polyfill` as if NextGraph
|
||||
already shipped per-entity documents in public/protected/private stores, capabilities
|
||||
and inboxes. It hasn't (see [`nextgraph-current-state.md`](./nextgraph-current-state.md)).
|
||||
This file is the lib's own engineering doctrine on how it fabricates that mature
|
||||
@@ -32,34 +32,45 @@ application fiction the lib maintains. On top of that one wallet the lib rebuild
|
||||
by emulation, the per-user stores + capabilities + inbox the consumer application
|
||||
codes against.
|
||||
|
||||
## Physical wallet vs virtual wallet — never enumerate the physical one
|
||||
## Physical user vs virtual user — never enumerate the physical one
|
||||
|
||||
**Nomenclature (aligned on NextGraph, 2026-07-30).** A **wallet** upstream is only a
|
||||
**keyring**; what owns three stores is a **user** (a *site*), and one wallet holds
|
||||
several of them (`SensitiveWalletV0.sites`, `engine/wallet/src/types.rs:434,457`).
|
||||
So this document says *user*, not *wallet*, for the thing an identity is — the two
|
||||
words meant the opposite of each other here until this was corrected.
|
||||
|
||||
Because the emulation runs on ONE shared wallet, distinguish two levels:
|
||||
|
||||
- **Physical wallet** — the real NextGraph wallet everyone opens. Its local store
|
||||
holds every account's documents plus the lib's own internals (the shim index,
|
||||
the inbox docs, the discovery index) as named graphs. It accumulates without
|
||||
bound across sessions/runs. Listing or scanning "all documents" of the physical
|
||||
wallet is meaningless and O(size) — it mixes every user's data with lib internals,
|
||||
and it is exactly what a `sparql_query` with no anchor (`GRAPH ?g { … }`) does
|
||||
(it spans every synced graph). The physical wallet is a substrate,
|
||||
not something to enumerate.
|
||||
- **The physical user** — the single NextGraph user everybody's session opens. Its
|
||||
stores hold every account's documents plus the library's own internals (the
|
||||
pointer, the doc-shim, the inbox documents) as named graphs, accumulating without
|
||||
bound across sessions and runs. Listing or scanning "all documents" at this level
|
||||
is meaningless and O(size): it mixes every virtual user's data with library
|
||||
internals, and it is exactly what an anchorless `sparql_query` (`GRAPH ?g { … }`)
|
||||
does. The physical user is a substrate, not something to enumerate.
|
||||
|
||||
- **Virtual wallet** — the lib's emulation of one user's wallet: the set of
|
||||
documents the shim attributes to that account (its per-scope index in
|
||||
`store-registry.ts`). This is what "the user owns". Over a *virtual* wallet,
|
||||
"list my documents" is meaningful and bounded (only that account's docs).
|
||||
- **A virtual user** — the library's emulation of one identity: the documents the
|
||||
shim attributes to that account (its three store documents in
|
||||
`shared-wallet/account-registry.ts`). This is what "the user owns", and over it "list my
|
||||
documents" is meaningful and bounded.
|
||||
|
||||
**Consequence for reads (see `read-model.md`):** to list a user's entities you
|
||||
enumerate the *virtual* wallet — the account's scope index (bounded, O(my docs)),
|
||||
not the physical union — then read those specific documents with a per-doc anchored
|
||||
`sparql_query`. A non-empty / bloated physical wallet then costs nothing, because the
|
||||
physical union is never scanned. Discovery (all public events) is the one bounded
|
||||
enumeration hack and goes through the discovery index, not a physical scan.
|
||||
**Which API you use follows that line, and it is enforced** (see `shared-wallet/physical.ts`):
|
||||
machinery operating on the *index of virtual users* — the store-root pointer, the
|
||||
doc-shim, the account records — goes through unguarded primitives that are never
|
||||
exported from the package. Everything touching a virtual user's own content goes
|
||||
through the guarded `docs.*`, even when the library is what calls it. One API is the
|
||||
app's; the other must never be.
|
||||
|
||||
At migration each virtual wallet becomes a real per-user wallet; the physical/virtual
|
||||
distinction — and the "never enumerate the physical wallet" rule — dissolves into
|
||||
native per-wallet reads.
|
||||
**Consequence for reads (see `read-model.md`):** to list an identity's entities you
|
||||
enumerate the *virtual* user — that account's store document, bounded to its own
|
||||
documents — never the physical union. A bloated shared wallet then costs nothing,
|
||||
and nothing is enumerated across users at all: you read your own documents and the
|
||||
ones whose cap you were given.
|
||||
|
||||
At migration each virtual user becomes a real user with its own wallet; the
|
||||
physical/virtual distinction, the "never enumerate the physical one" rule, and
|
||||
`shared-wallet/physical.ts` all dissolve into native per-user reads.
|
||||
|
||||
## Two axes, never conflate them (store ≠ document)
|
||||
|
||||
@@ -75,7 +86,7 @@ terminology historically fused:
|
||||
|
||||
`docCreate(sessionId, "Graph", "data:graph", "store", undefined)` targets the shared
|
||||
wallet's private store. The trailing `store` arg left `undefined` targets the
|
||||
private store (this is what `store-registry.ts`'s `createDoc()` does). So every
|
||||
private store (this is what `shared-wallet/account-registry.ts`'s `createDoc()` does). So every
|
||||
document the shim creates physically lives in one store (private), and the
|
||||
`public|protected|private` scope is a logical label tracked in RDF by the
|
||||
shim — not a NextGraph store. Therefore what a consumer application's "multi-store"
|
||||
@@ -84,12 +95,12 @@ multi-store. Do not read `Scope` (`types.ts`) as a physical store — it is the
|
||||
logical label the registry attaches.
|
||||
|
||||
> Why `undefined` and not a real store? Because `doc_create` **cannot target a
|
||||
> non-private native store** today: `StoreRepo` is not JS-constructible (verified
|
||||
> non-private native store** today from the WEB build: `StoreRepo` is not constructible there (verified
|
||||
> — see the parked `getNativeStore` note in
|
||||
> [`migration-guide.md`](./migration-guide.md)). The private store is reachable
|
||||
> because it opens without `RepoNotFound`.
|
||||
|
||||
## The shared-wallet shim (`store-registry.ts`)
|
||||
## The shared-wallet shim (`shared-wallet/account-registry.ts`)
|
||||
|
||||
Emulates the target infrastructure — where each user owns their own
|
||||
public/protected/private stores — on top of one shared wallet.
|
||||
@@ -114,41 +125,40 @@ public/protected/private stores — on top of one shared wallet.
|
||||
account→document trust root, which is why every untrusted value that reaches its
|
||||
SPARQL is escaped (see SPARQL hardening below). It makes identity resolution
|
||||
cross-device: another device opening the same wallet reads the same pointer → the
|
||||
same doc-shim → the same accounts.
|
||||
same doc-shim → the same virtualUsers.
|
||||
- **Per-entity documents + per-scope index.** `createEntityDoc(id, scope)`
|
||||
makes a dedicated document for one entity (mirrors the target, where each entity
|
||||
is its own document/repo with a future inbox) and appends its NURI to the
|
||||
account's scope index document — the index doc plays the role of the future
|
||||
store-container (it lists the entity-document NURIs "in" that scope).
|
||||
`listEntityDocs(scope)` unions the contained NURIs across all accounts. This is a
|
||||
fallback / test-only path, not the read path: enumerating every account and
|
||||
handing the NURIs to `useShape({ graphs })` opens/syncs other accounts' possibly-
|
||||
unsynced docs and hangs (the ORM fan-out — see
|
||||
[`read-model.md`](./read-model.md)). The real read path is
|
||||
`readModel.readUnion(docs)`, which reads the by-need doc set with one per-doc
|
||||
`listMyEntityDocs(id, scope)` reads back ONE user's documents — bounded to that
|
||||
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
|
||||
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 discovery index (public events) and
|
||||
the by-need doc set from the current wallet's own scope index and
|
||||
`listMyEntityDocs(id, scope)` (its own account, bounded — no cross-account fan-out).
|
||||
- **Generic by construction.** The registry knows only the three native scopes,
|
||||
zero application entity kind. The consumer application maps its entities to a scope
|
||||
and injects the session + identity-id normalization via `configureStoreRegistry({
|
||||
getSession, normalizeId })` (`polyfill.ts`).
|
||||
and injects the session + identity-id normalization through `configure({
|
||||
getSession, normalizeId })` (`shared-wallet/bootstrap.ts`, published by the entry).
|
||||
|
||||
The `store≠document` two axes materialize here directly: the registry moves along
|
||||
axis B (more documents = more isolation), never axis A (it always writes into the
|
||||
one private store via `docCreate(..., undefined)`).
|
||||
|
||||
### A virtual wallet's structure — the three emulated stores
|
||||
### A virtual user's structure — the three emulated stores
|
||||
|
||||
A *virtual wallet* = one account in the shim, keyed by its virtual-wallet id
|
||||
(the technical identifier the consumer application sets when the physical wallet is
|
||||
opened; it identifies *which* virtual wallet, and is an id rather than a
|
||||
A *virtual user* = one account in the shim, keyed by its virtual-wallet id
|
||||
(the technical identifier the consumer application sets when the physical user is
|
||||
opened; it identifies *which* virtual user, and is an id rather than a
|
||||
human-friendly handle). Its structure mirrors the target "1 user = 1 wallet with 3
|
||||
native stores":
|
||||
|
||||
```
|
||||
Virtual wallet (id)
|
||||
Virtual user (id)
|
||||
├── public store = docPublic index → [ entity doc NURI, entity doc NURI, … ]
|
||||
├── protected store = docProtected index → [ record doc NURI, record doc NURI, … ]
|
||||
└── private store = docPrivate index → [ record doc NURI, … ]
|
||||
@@ -156,28 +166,28 @@ Virtual wallet (id)
|
||||
|
||||
So the 3 native stores (public/protected/private) are present, but emulated: each
|
||||
"store" is an index document
|
||||
(`AccountRecord.{docPublic,docProtected,docPrivate}`) that lists the NURIs of the
|
||||
(`VirtualUserRecord.{docPublic,docProtected,docPrivate}`) that lists the NURIs of the
|
||||
per-entity documents in that scope. It is not a physical native store.
|
||||
|
||||
Everything is physical in one place: the 3 index documents, every per-entity
|
||||
document, and the shim anchor itself all live in the shared physical wallet's
|
||||
document, and the shim anchor itself all live in the shared physical user's
|
||||
private store (`docCreate(..., undefined)`). The 3-store structure is the per-account
|
||||
logical layer the lib maintains on top.
|
||||
|
||||
```
|
||||
Physical wallet (shared, one) → private_store (physical) holds everything:
|
||||
Physical user (shared, one) → private_store (physical) holds everything:
|
||||
• the shim anchor: virtual-wallet-id → { docPublic, docProtected, docPrivate }
|
||||
• every account's 3 scope-index docs + all per-entity docs + inbox + discovery index
|
||||
• every account's 3 scope-index docs + all per-entity docs + inboxes
|
||||
```
|
||||
|
||||
At migration each virtual wallet's 3 index documents become the user's 3 **real**
|
||||
At migration each virtual user's 3 index documents become the user's 3 **real**
|
||||
native stores, the entity documents move into them physically, and the
|
||||
virtual/physical distinction dissolves (see [`migration-guide.md`](./migration-guide.md)).
|
||||
|
||||
### SDK-shaped scope resolvers — the consumer application holds no store-id
|
||||
|
||||
The consumer application must never construct a `did:ng:${store_id}` NURI itself:
|
||||
physical placement is the lib's job (the whole point of the SDK boundary). Two
|
||||
physical placement is the lib's job (the whole point of the polyfill boundary). Two
|
||||
resolvers turn a logical scope into an opaque graph NURI without exposing any
|
||||
store-id:
|
||||
|
||||
@@ -190,21 +200,45 @@ store-id:
|
||||
blocker, [`migration-guide.md`](./migration-guide.md)). At migration each scope
|
||||
resolves to the user's real per-scope store — the change is in this function,
|
||||
and the consumer application is unchanged.
|
||||
- **`resolveInboxAnchor()`** — the anchor where emulated inbox deposits land: a
|
||||
dedicated inbox document (a reserved account's public scope document, from
|
||||
`docCreate` — a real repo NURI, stable across clients), not the shared
|
||||
wallet's private-store root. Why dedicated: the shim (the account→document trust
|
||||
root) lives in the private-store graph and is scanned on every `loadShim`;
|
||||
routing every inbox deposit into that same graph bloats it without bound
|
||||
(thousands of deposit triples across sessions), turning `loadShim` into a
|
||||
multi-second full-graph scan. A separate inbox document keeps the shim graph
|
||||
small and the deposits isolated. At migration it becomes the host's native
|
||||
inbox NURI.
|
||||
- **`userInbox(id)` / `openDocumentInbox(doc)`** — an inbox BELONGS to someone. The
|
||||
first is a user's own inbox (where Links arrive), the second a DEDICATED inbox for
|
||||
one of its documents, opened on demand by its **owner only** (ownership read from the
|
||||
Store branches — a received cap is not ownership, and a recipient must not be able to
|
||||
redirect the owner's deposits to itself). Both are dedicated documents (real repo
|
||||
NURIs from `docCreate`), never the private-store root: routing deposits into the shim
|
||||
graph would bloat the account→document trust root without bound. `myInboxes()`
|
||||
enumerates both levels — what `emulated-verifier/connect.ts` drains at connection — and `isOwnInbox`
|
||||
answers from the same record. *(The former `resolveInboxAnchor`, a single inbox COMMON
|
||||
to every user, was removed on 2026-07-30: nothing may be common but the mechanisms
|
||||
that make the virtual users work.)*
|
||||
- **`documentInboxAddress(doc)` — the DEPOSIT side, and the one a third party uses.**
|
||||
Reading an inbox and finding where to deposit into it are opposite acts with opposite
|
||||
audiences, and conflating them is what made per-document inboxes unusable at first:
|
||||
resolution answered *"which inbox do I know for this document"*, so a depositor got
|
||||
one of their own and their deposit vanished silently
|
||||
([`briefs/2026-08-03-document-inbox-addressing.md`](./briefs/2026-08-03-document-inbox-addressing.md)).
|
||||
A document that has an inbox carries its address on its emulated **Header branch** —
|
||||
a reserved subject inside the document, so any holder of the document reads it, and
|
||||
`read-model` filters the whole `urn:ng-eventually:` namespace out of consumer data
|
||||
(`src/emulated-verifier/machinery.ts`). This mirrors upstream's split: a depositor seals with the inbox
|
||||
PUBLIC key and needs nothing else, only the owner holds the private half.
|
||||
**One inbox belongs to one document** — never several documents behind one inbox, a
|
||||
relation upstream cannot express (the verifier routes by `inboxes: PubKey → RepoId`
|
||||
and unseals with that repo's key, `engine/verifier/src/verifier.rs:1677,1928`), which
|
||||
is also why a deposit carries no target document: the address identifies it. A fresh
|
||||
document therefore has NO inbox and `documentInboxAddress` returns `undefined` — its
|
||||
owner opens one when the document is meant to receive, which is what keeps the cost
|
||||
proportional. At migration the address becomes the repo's native inbox pubkey and the
|
||||
resolution moves; the consumer-facing act is unchanged.
|
||||
- **`inbox.postToDocument(doc, { payload })`** — the one call an app makes to reach a
|
||||
document's owner: it names the DOCUMENT, never an inbox. **Throws** when the document
|
||||
has no inbox, rather than returning quietly: a deposit that vanishes without an error
|
||||
is the exact bug this path shipped with.
|
||||
|
||||
Both resolve the native store ids from the injected session
|
||||
(`RegistrySession.protectedStoreId` / `publicStoreId`, alongside the existing
|
||||
`privateStoreId` anchor). The consumer application hands the whole session to the
|
||||
lib at the one injection point (`configureStoreRegistry({ getSession })`) — that is
|
||||
lib at the one injection point (`configure({ getSession })`) — that is
|
||||
wiring, not placement logic; everything else in the consumer application speaks only
|
||||
in scopes. If the session omits `protectedStoreId`, the non-private scopes fall back
|
||||
to the private store rather than emit a broken NURI.
|
||||
@@ -231,7 +265,7 @@ is preserved in [`decisions/private-store-nuri-scope.md`](./decisions/private-st
|
||||
|
||||
A validated hard constraint, not a style choice: `docs.ts` calls the real
|
||||
injected `ng` (`getConfig().ng`) directly, never the public `ng` proxy
|
||||
(`makeNg` in `ng-proxy.ts`).
|
||||
(`makeNg` in `surface/ng-proxy.ts`).
|
||||
|
||||
`@ng-org/web`'s `ng` is already an iframe-RPC proxy (postMessage marshaling,
|
||||
see [`nextgraph-current-state.md`](./nextgraph-current-state.md) § integration).
|
||||
@@ -249,87 +283,154 @@ verified: routing the shim's `doc_create`/SPARQL through the public proxy turned
|
||||
`docs.ts` therefore imports **no** `@ng-org` package and must **not** import from
|
||||
`./ng-proxy`.
|
||||
|
||||
## Emulated ReadCap — per document (`caps.ts` + `read-filter.ts`)
|
||||
## Emulated ReadCap — per document (`emulated-verifier/caps.ts` + `emulated-verifier/read-filter.ts`)
|
||||
|
||||
In the target the broker only delivers documents the wallet holds a ReadCap
|
||||
for, so `useShape` already returns an authorized subset. Here (single shared
|
||||
wallet, everything readable) the lib reproduces that with a read-filtered view:
|
||||
|
||||
- **`CapRegistry` (`caps.ts`)** models ReadCaps as faithfully as a data layer
|
||||
can. The access unit is the document = repo NURI (an item's `@graph`),
|
||||
never the item — because in `nextgraph-rs` a store is just a container repo
|
||||
and holding its cap does not grant the repos it references (no store-level read
|
||||
inheritance; verified). So the registry is purely per-document:
|
||||
`grantRead(doc, granteeId)` issues a directed read grant to one identity,
|
||||
alongside `grantWrite` / `makePublic` / `open(doc, scope, owner)` /
|
||||
`canRead` / `canWrite` / `governsRead` / `hasReadPolicy`, plus the read-only
|
||||
accessor `protectedDocsOf(owner)` the consumer application uses to pick which
|
||||
protected docs to grant. The consumer application performs the *acts* of granting
|
||||
(create-public, grant a specific doc to a specific identity…) exactly as it
|
||||
will in the target; the lib injects no policy.
|
||||
- **`read-filter.ts`** — `makeReadFilteredView` wraps the reactive set in a
|
||||
`Proxy`: iteration / `size` / `forEach` are filtered by
|
||||
`caps.canRead(item['@graph'], user)`; everything else (`add`, `delete`, `has`,
|
||||
`getById`…) forwards to the target, preserving writes and reactivity. An item
|
||||
with no `@graph`, or in a document under no cap policy, is kept (the filter only
|
||||
restricts documents that *declare* a cap — no regression on ungoverned data).
|
||||
`filterReadable` is the pure variant.
|
||||
- **`useShape` (`use-shape.ts`)** applies the view only if
|
||||
`caps.hasReadPolicy()` — otherwise it passes the real set through unchanged
|
||||
(no regression when the consumer application declares no caps).
|
||||
- **`CapRegistry` (`emulated-verifier/caps.ts`)** models a ReadCap as what it is: **the document's
|
||||
key**. The access unit is the document = repo NURI (an item's `@graph`), never
|
||||
the item — because in `nextgraph-rs` a store is just a container repo and holding
|
||||
its cap does not grant the repos it references (no store-level read inheritance;
|
||||
verified). The registry records, **per identity**, the caps it holds — `Map<Nuri, ReadCap>`
|
||||
— and answers exactly one question: `capFor(nuri)`, *do I hold this document's
|
||||
cap?* There is deliberately **no** "may principal P read document D": that is an
|
||||
ACL question, and the real model cannot answer it either.
|
||||
- **`nuri.ts`** carries the cap-less / cap-bearing distinction, which upstream is
|
||||
one object (`NuriV0 { target, access }`) discriminated by the `:r:{cap}` segment.
|
||||
`Nuri` names, `ReadCap` names *and* reads. Both are plain strings — the real SDK
|
||||
takes `nuri: String` and enforces at runtime through cryptography, so a branded
|
||||
type would be a concept NextGraph does not have. The stand-in key value is the
|
||||
constant `OK` (see the module header): the only question the emulation answers is
|
||||
*do I hold this cap or not*, so the value says exactly that and pretends nothing
|
||||
more. Cap-enforcement, not cap-surface, is the batch that turns the shape into a protection.
|
||||
- **`emulated-verifier/read-filter.ts`** — `makeReadFilteredView` wraps the reactive set in a
|
||||
`Proxy`: iteration / `size` / `forEach` keep only items whose `@graph` the
|
||||
current holder holds; everything else (`add`, `delete`, `has`, `getById`…) forwards to
|
||||
the target, preserving writes and reactivity. An item with no `@graph` is kept (it
|
||||
names no document, so there is no cap to hold). `filterReadable` is the pure
|
||||
variant. Note the absence of a `user` parameter — that absence *is* the model.
|
||||
- **`useShape` (`surface/use-shape.ts`)** applies the view only once a cap exists at all
|
||||
(`caps.isEnforcing()`) — before that it passes the real set through unchanged (no
|
||||
regression for a consumer that never touches caps). Once ANY cap is issued the
|
||||
regime is possession for **every** holder, including one who holds nothing:
|
||||
that is the isolation.
|
||||
|
||||
In a mono-store layout (every item in one repo) this is all-or-nothing on that
|
||||
document — exactly the native behaviour, and why fine-grained isolation requires
|
||||
one document per entity (axis B).
|
||||
|
||||
### Making the ReadCap active — current identity + directed grants
|
||||
### Where caps come from — stored, never derived
|
||||
|
||||
The filter only discriminates once the consumer application (a) tells the SDK who is
|
||||
reading and (b) declares the access policy on the documents. Both are plain SDK
|
||||
calls; the consumer application never touches the registry internals:
|
||||
`doc_create` returns a **cap-less** NURI, so "no function ever goes from a bare
|
||||
reference to a cap" cannot be the whole rule — it would lock a document's own creator
|
||||
out of it. The real mechanism: creating a document commits `AddRepo { read_cap }` to
|
||||
the store's **Store branch**, separately from the `ldp:contains` listing on its Main
|
||||
branch. That is where an owner finds the caps of what it created; a cap RECEIVED for
|
||||
someone else's document goes elsewhere, on the **User branch** (`AddLink`). The wallet
|
||||
itself holds one key per user — the private store's read cap — from which the rest is
|
||||
reached. Hence the invariant:
|
||||
|
||||
- **`setCurrentUser(id)` (`polyfill.ts`)** — the SDK's "current identity" call.
|
||||
`useShape`'s filtered view reads it lazily, so the delivered subset always
|
||||
reflects the identity in effect at read time. Until it is set, the filter has no
|
||||
principal and (per `canRead(doc, null)`) only public documents pass — which is
|
||||
why isolation stays dormant until the consumer application makes this call.
|
||||
- **`getCaps().open(doc, scope, owner)`** — declares a document's policy when the
|
||||
consumer application creates it: `public` → world-readable; `protected`/`private`
|
||||
→ owner reads, owner holds the write cap. `open` also remembers `(scope, owner)`
|
||||
per document so `protectedDocsOf(owner)` can later enumerate the protected ones.
|
||||
- **`grantRead(doc, granteeId)` (`caps.ts`, exposed via `getCaps()`)** — the one
|
||||
relationship-shaped sharing act the lib exposes: a directed per-document read
|
||||
grant issued to a specific identity. Public docs stay world-readable; private
|
||||
docs stay owner-only; a protected doc becomes readable by `granteeId` once the
|
||||
owner grants it. The consumer application passes a document NURI and a grantee id
|
||||
— no store id.
|
||||
> **You do not derive a cap from a bare reference. You look it up in what you hold —
|
||||
> or you were given it.**
|
||||
|
||||
The relationship concept — who is "connected" to whom, and therefore which of
|
||||
their protected docs to grant — is owned by the consumer application, not the lib.
|
||||
A connection or friendship is not a NextGraph primitive; the only platform-mappable
|
||||
primitive is the directed per-document read grant above. So the consumer application
|
||||
decides a relationship exists and, for each protected doc it wants to share, calls
|
||||
`grantRead(doc, granteeId)` — typically iterating `protectedDocsOf(owner)` to pick
|
||||
the owner's protected docs. The intended target of such a directed grant is a native
|
||||
per-document ReadCap issued to that identity — but that target is itself
|
||||
scaffolding-only in nextgraph-rs today, not merely unexposed in JS: `AccessGrantV0
|
||||
{grantee}` is unpersisted and cap-send is `unimplemented!()`, so directing a grant
|
||||
to another identity is not-yet-built at the platform level. There is no bilateral
|
||||
capability exchange to mirror, only (eventually) individual directed grants.
|
||||
Three ways a cap arrives, and there are no others:
|
||||
|
||||
The result is the target's discrimination reproduced end-to-end: private →
|
||||
owner; protected → owner + whoever the owner has directly granted; public → all.
|
||||
Proven in `test/isolation-active.test.ts`: an unconnected principal is denied a
|
||||
protected document, granted it after the owner issues a directed `grantRead`, and
|
||||
reads the public document throughout.
|
||||
- **Creation.** `createEntityDoc(id, scope)` writes the cap on the store's emulated
|
||||
Store branch (`shim:readCap`) and the creator holds it. The consumer declares
|
||||
nothing, and the cap is minted exactly ONCE — the stored value is the held value,
|
||||
which is what keeps this correct when cap-enforcement makes the key real.
|
||||
- **Re-listing.** `listMyEntityDocs(id, scope)` READS those records back. It does not
|
||||
recompute anything: that is the whole reason for storing them, and it is what lets
|
||||
a **fresh session** read its own documents again with nothing re-declared — the
|
||||
durability the old in-memory ACL faked and lost every reload.
|
||||
- **Delivery.** `inbox.share(doc, toUser)` deposits one document's cap into one
|
||||
recipient's inbox; `inbox.read` applies it inline, exactly as the recipient's own
|
||||
verifier applies queued messages upstream. **Receiving needs no operation** — a
|
||||
consumer already watching its inbox gets them, and the resulting change
|
||||
re-triggers the reads that were empty for want of that cap.
|
||||
|
||||
This discrimination is only observable because each entity is its own document
|
||||
(the consumer application creates per-entity docs via `createEntityDoc` and `open`s
|
||||
each) — in a mono-store layout the per-document ReadCap is all-or-nothing.
|
||||
**The caps a holder holds are not the sharing mechanism.** Handing over a *store* cap would give
|
||||
away everything the store contains, present and future. The unit of sharing is the
|
||||
document; the Store branch is a private index.
|
||||
|
||||
Switching identity **switches** records — it never wipes one. If it wiped,
|
||||
durability would be a lie and per-session re-declaration would come back under
|
||||
another name.
|
||||
|
||||
### Sharing, publication, and the recipient
|
||||
|
||||
- **`setCurrentUser(id)` (`shared-wallet/bootstrap.ts`, INTERNAL since 2026-08-07 — `ensureIdentity` is what an application calls)** — the SDK's "current identity" call.
|
||||
It selects *whose* caps are consulted, lazily, so the delivered subset always
|
||||
reflects the identity in effect at read time.
|
||||
- **`inbox.share(doc, toUser)`** — the one sharing act the lib exposes. Recipients
|
||||
are addressed as **inboxes**, which `inbox.post(targetInbox)` already does here;
|
||||
there is no `PrincipalId` in this surface, because that notion exists nowhere
|
||||
upstream. Reaching several recipients means calling it once per inbox, which is
|
||||
what the real model does too (each delivery is sealed to one recipient).
|
||||
- **A document created in the `public` scope** needs no sharing act at all. The store
|
||||
serves its ReadCap to whoever asks (`emulated-verifier/public-store.ts`, emulating
|
||||
*"the latest ReadCap will be downloaded from the outerOverlay"* — `PublicRepoLinkV0`,
|
||||
`engine/net/src/types.rs:5098`), so what an application circulates is the **bare
|
||||
reference**, exactly as it will after migration. Never recursive: a public document
|
||||
may reference private ones, and the reference grants nothing on what it references —
|
||||
which is what lets a public object point at a private identity without disclosing it.
|
||||
And never a write right: what the store serves is a read cap.
|
||||
|
||||
Upstream, directed delivery is a **gap, not a disagreement**: `ContactDetails.read_cap`
|
||||
exists, but the message construction is `unimplemented!()`, its only caller passes
|
||||
"without read_cap", and the receiver discards the cap. The shape is right; the
|
||||
implementation is absent, so this lib emulates it meanwhile.
|
||||
|
||||
**Key rotation needs nothing on this surface.** A rotated key is re-sent to the
|
||||
inbox of whoever keeps access, and that inbox is processed automatically at the next
|
||||
connection — so access is not lost, it is *deferred*, consistent with local-first.
|
||||
Same channel as the initial delivery, so there is **no subscription obligation** to
|
||||
expose and no special case to write. Revocation stays what it is: stop re-delivering,
|
||||
non-retroactive.
|
||||
|
||||
The relationship concept — who is "connected" to whom, and therefore whose documents
|
||||
to share — is owned by the consumer application, not the lib. A connection or
|
||||
friendship is not a NextGraph primitive; the only platform-mappable primitive is the
|
||||
per-document cap delivery above.
|
||||
|
||||
The result is the target's discrimination reproduced end-to-end: you read the
|
||||
documents whose caps you hold, and nothing else. Proven in
|
||||
`test/isolation-active.test.ts` (a document nobody shared is unreadable; a share to
|
||||
one inbox reveals it there and only there; a bare reference reads nothing while the
|
||||
repo link opens the published document; a returning identity keeps its caps) and in
|
||||
`test/cross-user-access.test.ts`, the acceptance test below.
|
||||
|
||||
This discrimination is only observable because each entity is its own document (the
|
||||
consumer application creates per-entity docs via `createEntityDoc`) — in a mono-store
|
||||
layout the per-document ReadCap is all-or-nothing.
|
||||
|
||||
### The acceptance test — no cryptography required
|
||||
|
||||
Alice owns a protected document holding a secret and a public one that carries a
|
||||
**reference** to it. Bob, holding the public document's link, reads it, finds the
|
||||
reference, and can NAME the protected document while reading nothing of it —
|
||||
publication is **not recursive**. Charlie, holding the same link plus the protected
|
||||
document's cap (delivered to his inbox), reads through the very same reference. The
|
||||
only difference between them is each of them holds; nobody was named to any
|
||||
registry. And dynamically: the cap lands in Bob's inbox, his client processes it, and
|
||||
the read that was empty yields the content — the held-caps signal re-running it.
|
||||
|
||||
That is what real NextGraph does, and it holds **without a line of encryption** —
|
||||
which is what makes the cap-surface (shape) / cap-enforcement (enforcement) split honest rather than
|
||||
cosmetic. Proven in `test/cross-user-access.test.ts`.
|
||||
|
||||
> **After the cap-surface batch the shape is right and the isolation is still fake.** The stand-in key
|
||||
> is a constant, and several read paths (`docs.sparqlQuery`/`sparqlUpdate`, the whole
|
||||
> inbox, `store-registry`, `subscribe`, `open-repo`) consult no cap at all — worse,
|
||||
> any wallet can reach any document. That is the subject of
|
||||
> [`briefs/2026-07-30-virtual-wallet-boundary.md`](./briefs/2026-07-30-virtual-wallet-boundary.md).
|
||||
> Nothing may be claimed "anonymous" or "private" until it lands.
|
||||
|
||||
### Write-guard coverage (honest scope)
|
||||
|
||||
The emulated write guard (`ng-proxy.ts`, `sparql_update` override) enforces the
|
||||
The emulated write guard (`surface/ng-proxy.ts`, `sparql_update` override) enforces the
|
||||
per-document write cap on the public `ng` proxy only. In practice the
|
||||
consumer application's write paths (`docs.sparqlUpdate`, ORM `ngSet`) call the real
|
||||
injected `ng` directly — never the public proxy — for the validated `DataCloneError`
|
||||
@@ -341,17 +442,17 @@ natively at migration); the read side is what makes isolation observably active.
|
||||
|
||||
### The per-document ReadCap is the isolation path (item-level filter retired)
|
||||
|
||||
Isolation is enforced by the per-document ReadCap (`caps.ts` + `read-filter.ts`)
|
||||
alone: the access unit is the document (`@graph` = repo), and grants are explicit
|
||||
(`open` / `grantRead` / `makePublic`) — for `protected`, the owner issues a directed
|
||||
`grantRead(doc, granteeId)` per identity it wants to share with. Because the consumer
|
||||
application now writes one document per entity (`createEntityDoc` + `open` per entity),
|
||||
the per-document cap discriminates at entity granularity — the target's behaviour.
|
||||
Isolation is enforced by the per-document ReadCap (`emulated-verifier/caps.ts` + `emulated-verifier/read-filter.ts`)
|
||||
alone: the access unit is the document (`@graph` = repo), and the only acts are
|
||||
possession-shaped (`createEntityDoc` files a cap, `inbox.share` delivers one, a public
|
||||
store serves one to whoever asks). Because the consumer application writes
|
||||
one document per entity, the per-document cap discriminates at entity granularity —
|
||||
the target's behaviour.
|
||||
|
||||
The old item-level application-visibility filter (`isolation.ts`
|
||||
The old item-level application-visibility filter (the since-deleted `isolation.ts`
|
||||
`applyIsolation`, a `Set`-of-records filter keyed on owner+scope) is retired
|
||||
from the consumer path: the application carries no access logic — it declares its
|
||||
identity and issues directed grants, and trusts the SDK. Its matrix functions are
|
||||
identity and shares caps, and trusts the polyfill. Its matrix functions are
|
||||
dead scaffolding kept for reference and removed at migration. There is no longer a
|
||||
second, coexisting app-layer filter to reconcile — the single axis is the
|
||||
per-document cap, exactly as in the target.
|
||||
@@ -365,7 +466,7 @@ fork the broker ([`fork-inbox-fallback.md`](./fork-inbox-fallback.md)), the lib
|
||||
emulates the inbox on the shared wallet:
|
||||
|
||||
- **Target vs polyfill.** In the target, `post` seals a reference into the owner's
|
||||
native inbox (`inbox_post_link(...)`, a proposed/future API) and the recipient's
|
||||
native inbox — through a JS call that **does not exist and is not announced** — and the recipient's
|
||||
own verifier unseals each queued message and applies it inline when it processes
|
||||
its inbox — there is no separate curator or materialization process. Here,
|
||||
everything is readable, so the lib emulates the read side in-lib.
|
||||
@@ -388,71 +489,107 @@ emulates the inbox on the shared wallet:
|
||||
polls `read` and fires when the deposit count changes (the polyfill has no
|
||||
reactive inbox subscription). Fires once immediately; returns an unsubscribe.
|
||||
|
||||
### An inbox BELONGS to a virtual user (2026-07-30)
|
||||
|
||||
`storeRegistry.userInbox(id)` resolves — creating on first sight — the inbox
|
||||
document of one virtual user, recorded in the doc-shim under `shim:docInbox` and
|
||||
read by its own query (so an account written before this existed still resolves).
|
||||
The asymmetry that matters:
|
||||
|
||||
- **Depositing into anyone's inbox is open.** It is the ONLY way a link crosses
|
||||
from one wallet to another, and since you cannot discover, it is the bootstrap of
|
||||
the whole reachability graph. A deposit grants the depositor nothing in return —
|
||||
upstream it is an anonymous sealed box.
|
||||
- **Reading an inbox is confined to its owner** (`isOwnInbox`, enforced in `read` /
|
||||
`readSynced`, hence in `watch`). Since the cap-surface batch routes ReadCaps through deposits, an
|
||||
unguarded read let anyone who knew an inbox NURI collect the caps addressed to its
|
||||
owner — defeating directed sharing. Anonymous owns no inbox and reads none.
|
||||
|
||||
At migration this guard disappears into cryptography: an inbox is sealed to its
|
||||
owner's key.
|
||||
|
||||
The module knows no domain — the consumer application supplies the inbox document
|
||||
NURI and interprets `payload`. At migration `post` becomes the native
|
||||
`inbox_post_link` (proposed/future) and the read side is served by the recipient's
|
||||
own verifier unsealing queued messages inline (see the deferred global-index note in
|
||||
the top-level README and [`decisions/discovery-model.md`](./decisions/discovery-model.md)).
|
||||
NURI and interprets `payload`. At migration `post` becomes the native sealed
|
||||
deposit — **whose JS name and signature are not known**, since none is exposed or
|
||||
announced — and the read side is served by the recipient's own verifier unsealing
|
||||
queued messages inline.
|
||||
The inbox + watcher is the one deposit/read mechanism a consumer reuses for its own
|
||||
purposes — e.g. a registration/deposit in one consumer app and submission to a
|
||||
discovery index — same `post` API, same watcher.
|
||||
purposes — a registration/deposit, a cap delivery (`inbox.share`), a link handed to
|
||||
someone — same `post` API, same watcher.
|
||||
|
||||
## Emulated discovery index + special account (`discovery.ts`)
|
||||
## The virtual user boundary (`emulated-verifier/reach.ts` + `shared-wallet/physical.ts`)
|
||||
|
||||
Discovery is a surface on top of the inbox, not a new primitive. Access is not the
|
||||
same as discovery: a public entity is world-readable *with its NURI*; the discovery
|
||||
index is how a client learns that NURI exists without holding a relationship
|
||||
to its creator (see [`decisions/discovery-model.md`](./decisions/discovery-model.md)).
|
||||
The model is: one global index = an owned document (public read), fed via
|
||||
its inbox. Nobody writes the index directly — a creator deposits a reference into
|
||||
the index's inbox, and the index is built up from those deposits. That build-up
|
||||
step is the natural dedup / moderation point.
|
||||
Every access function is confined to the user currently connected: no cross-user
|
||||
access, so the consumer is coded against a reach that will actually exist.
|
||||
**Two rules, one criterion — possession — implemented in two places**, deliberately
|
||||
redundant so a lapse in either is caught by the other:
|
||||
|
||||
- **The special account (polyfill owner).** "Who owns the global index" is
|
||||
undecided in the target (NextGraph is mono-user with no global data — a
|
||||
singleton app is the only glimpsed path). So the polyfill parks ownership on a
|
||||
reserved special account in the shim — `INDEX_ACCOUNT = reservedAccount("index")`.
|
||||
This is NOT the key `"index"` / `"@index"`: `reservedAccount` mints a
|
||||
sentinel-prefixed key in the shim's reserved namespace (e.g. `" reserved:index"`)
|
||||
that `normalizeId` can never produce, so no user id — not even one typed as
|
||||
"index" or "@index", which normalizes to the disjoint key "index" — can collide
|
||||
with or hijack the index account (asserted in `discovery.test.ts`). It is a
|
||||
normal shim account (so its 3 scope documents are created on first sight like
|
||||
any other), but never a real user; it only hosts the index document. Its
|
||||
`public` scope document is the index document, and its inbox receives the
|
||||
deposits — a stable NURI: every client opening the same shared wallet
|
||||
resolves the same account, hence the same document, so all clients read/write one
|
||||
shared index.
|
||||
- **`submitToIndex(ref, opts?)`** — the SDK act "make this discoverable".
|
||||
Deposits `ref` into the index document's inbox via `inbox.post`. `from` follows
|
||||
the inbox convention (bound to the current identity; anonymous when `null`).
|
||||
`ref` is opaque here — the consumer application serializes whatever locates the
|
||||
entity (e.g. an entity document NURI + discovery metadata). Public-only guard: when
|
||||
`opts.doc` names the document being surfaced, a document under a non-public
|
||||
(protected/private) read policy is refused (`caps.governsRead(doc) &&
|
||||
!caps.canRead(doc, null)`) — the global index is world-readable, so admitting a
|
||||
governed doc's NURI would leak it past its scope. Proven in
|
||||
`test/discovery.test.ts` case (d).
|
||||
- **`readIndex()`** — the emulated read side. Reads every submission, dedups by
|
||||
serialized `ref` (the moderation point: a duplicate submission surfaces
|
||||
once), returns entries sorted by `ts`. `watchIndex(onEntries, opts?)` is the
|
||||
emulated watcher (polls `readIndex`).
|
||||
- **Rule 1, authorization** (`assertMayReach`, at the passage points `docs.sparqlQuery`
|
||||
/ `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 — `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
|
||||
with no meaning.
|
||||
|
||||
This replaces the cross-account fan-out (`store-registry.ts`
|
||||
`listEntityDocs('public')` / `resolveReadGraphs`) as the app-facing discovery
|
||||
path: the consumer application submits public entities to the index and reads the
|
||||
index, instead of fanning out over every account's public documents. The fan-out
|
||||
survives only as an internal lib fallback — kept for the per-scope listing it also
|
||||
powers (e.g. `resolveReadGraphs`), never the app's discovery route.
|
||||
**Possession decides, never the shape of the reference in hand.** A caller
|
||||
legitimately holds a bare NURI while possessing its cap elsewhere — references travel
|
||||
bare through content and stores, the cap sits in what the user holds.
|
||||
|
||||
`discovery.ts` knows no application domain — the consumer application defines the
|
||||
`ref` shape and its meaning. At migration the special account disappears:
|
||||
ownership moves to the decided global-index owner, `submitToIndex` becomes the
|
||||
native `inbox_post_link` (proposed/future) on the index's inbox, and `readIndex`
|
||||
queries the real index document. The consumer surface (`submitToIndex` / `readIndex`)
|
||||
is designed to survive that swap unchanged.
|
||||
The exception is **depositing** into another user's inbox (`register-write.depositInto`, internal): a
|
||||
named primitive rather than a flag, because it is a different act — you hold no cap,
|
||||
you cannot read back, and you get nothing in return. It is the only channel by which
|
||||
a link crosses between users, hence the bootstrap of the whole reachability graph.
|
||||
|
||||
## Emulated write guard (`ng-proxy.ts`)
|
||||
The machinery lives in `shared-wallet/physical.ts` (see *Physical user vs virtual user* above):
|
||||
unguarded primitives, never exported from the package, used only for the index of
|
||||
virtual users. Separating the FUNCTIONS is what replaced an earlier exemption list —
|
||||
the machinery does not get waved through the guard, it calls something the guard
|
||||
never saw.
|
||||
|
||||
## Connecting a user (`emulated-verifier/connect.ts`)
|
||||
|
||||
Processing inboxes is the **library's** job, not the app's: a consumer must never
|
||||
have to remember to drain a queue for documents shared with it to become readable —
|
||||
forgetting would look like "the share did not work" rather than "nobody consumed the
|
||||
queue". So `setCurrentUser` fires `connectedUser()`, which does two things in order:
|
||||
|
||||
1. **Restore** — read back the caps this user already applied (`readLinks`, the
|
||||
emulated `AddLink` records on its User branch) into what it holds. Durable state,
|
||||
one read, no inbox involved.
|
||||
2. **Drain** — process every inbox it may read (`myInboxes`: its own, plus one per
|
||||
document it opened an inbox on), filing any new Link durably.
|
||||
|
||||
Restore-first is what lets a reconnecting user read its shared documents immediately
|
||||
instead of waiting on a queue round-trip.
|
||||
|
||||
**Fire-and-forget, deliberately.** The setter is synchronous and every consumer calls
|
||||
it from synchronous code; making it async would push the wait back onto the app,
|
||||
which is the obligation this removes. The work announces itself through
|
||||
`CapRegistry.onChange` — which `watchShape` already listens to — so a view that was
|
||||
empty for want of a cap re-reads when the cap lands. `connectedUser()` is exported
|
||||
for a caller that needs to await it (tests, a deterministic startup).
|
||||
|
||||
**It does not provision.** Connecting an identity that does not exist creates
|
||||
nothing (`resolveAccount`, not `ensureAccount`): otherwise connecting would mint a
|
||||
user's stores and their caps as a background side effect, arming the whole emulation
|
||||
at a moment nothing controls.
|
||||
|
||||
*Cost worth knowing*: `setCurrentUser` therefore has observable asynchronous effects
|
||||
— it reads, and it logs. Tests asserting on log output must await `connectedUser()`
|
||||
first.
|
||||
|
||||
## ~~Emulated discovery index + special account~~ — REMOVED 2026-07-30
|
||||
|
||||
**There is no discovery in NextGraph. You cannot discover; you can only follow links** (see [`readcap-and-nuri-model.md`](./readcap-and-nuri-model.md) §4ter-bis). Publishing is two acts — place the data in your public store, **and** circulate its link (into an inbox, or into a document the reader already holds) — and it is seen only by those who received the link.
|
||||
|
||||
`discovery.ts` (a global index owned by a reserved `@index` account, `submitToIndex` / `readIndex` / `watchIndex`), its tests, and `watchShape`'s public-scope fold were **removed**. The module failed on two independent counts: it emulated a capability the target will never have — teaching consumers a model that does not exist — and it was **data common to several wallets**, where nothing may be common but the indexing mechanisms that make the virtual users work.
|
||||
|
||||
The ADR that specified it ([`decisions/discovery-model.md`](./decisions/discovery-model.md)) is marked superseded, and keeps the part that survives: the `discovery → synchronization → query` frame still holds, with stage 1 re-read as *"a link reached you"* rather than *"you consulted an index"*. Which makes the **inbox** the bootstrap of the whole reachability graph — see [`briefs/2026-07-30-virtual-wallet-boundary.md`](./briefs/2026-07-30-virtual-wallet-boundary.md).
|
||||
|
||||
## Emulated write guard (`surface/ng-proxy.ts`)
|
||||
|
||||
The public `ng` proxy overrides `sparql_update` to enforce an emulated write
|
||||
cap: a write is refused unless the current user holds the target document's
|
||||
@@ -461,7 +598,7 @@ specific document (the `anchor` arg) is governed by it — ungoverned docs (the
|
||||
mono-store default, no cap declared) flow through unchanged. This mirrors the target
|
||||
broker/verifier, which refuses a write without the document's write cap.
|
||||
|
||||
## Identity store (`accounts.ts`)
|
||||
## Identity store (`shared-wallet/virtualUsers.ts`)
|
||||
|
||||
The real NextGraph login (redirect to the broker, opening the single shared
|
||||
wallet) is perceived as a technical access barrier (see the login
|
||||
@@ -479,7 +616,7 @@ identity id the consumer application relays to it:
|
||||
open underneath. The real logout lives elsewhere (hidden in the consumer
|
||||
application's settings/debug), because it forces a new redirect.
|
||||
- Framework-agnostic: no React, no DOM beyond an optional injected
|
||||
`AccountStorage` (a `window.localStorage`, a test fake, or `null` for SSR). The
|
||||
`VirtualUserStorage` (a `window.localStorage`, a test fake, or `null` for SSR). The
|
||||
React `Context`/`Provider` stays in the consumer application. `normalizeId`
|
||||
(case-insensitive, optional leading `@` stripped, trimmed) is the pure
|
||||
normalizer, reusable as the shim key normalizer.
|
||||
@@ -502,5 +639,5 @@ document trust root):
|
||||
(`did:ng:...`): validates and throws on IRI-breaking chars rather than emitting
|
||||
a malformed/injected query.
|
||||
|
||||
These are re-exported from `@ng-eventually/client` so the consumer application
|
||||
These are re-exported from `@ng-eventually/polyfill` so the consumer application
|
||||
reuses the same escaping when it builds SPARQL.
|
||||
|
||||
@@ -0,0 +1,167 @@
|
||||
# Source layout by migration fate — analysis and recommendation
|
||||
|
||||
**Status: ADOPTED.** The layout this document recommends is the one in the tree — `model/`, `surface/`, `emulated-verifier/`, `shared-wallet/`. Read the rest as the reasoning that produced it, not as a proposal. *(Two things have moved under it since: the package became `packages/polyfill` / `@ng-eventually/polyfill` on 2026-08-10 — it was `packages/client` / `@ng-eventually/client`, kept here as a search keyword — and `emulated-verifier/public-store.ts` was added on 2026-08-06. Paths below point at where the files are now.)*
|
||||
|
||||
Written 2026-08-04, when nothing had yet been moved, from the source of `src/` (25 modules), the two contracts (`docs/api-contract.md`, `docs/internal-contract.md`) used as the export-level inventory, and the read-only `nextgraph-rs` clone (HEAD `213338f6`); the upstream facts this analysis leans on were re-verified at the source and are cited with layer numbers per `README.md` § *The three references* (1 = engine, 2 = wasm binding, 3 = JS ORM).
|
||||
|
||||
**The question.** Today all 25 modules sit flat in `src/`, named mechanically. Three different fates coexist undistinguished: modules whose *shape* the consumer keeps (the surface the real SDK replaces), modules standing in for what the engine/verifier will do natively, and modules that exist only because the emulation runs on one shared wallet. The bet under evaluation: if the folder structure mirrors the target's own structure, divergence gets harder to commit and easier to spot.
|
||||
|
||||
---
|
||||
|
||||
## 1. Is layout-by-future-layer the right axis?
|
||||
|
||||
**Yes on the axis, no on the literal reading — and with a bounded claim about what it buys.**
|
||||
|
||||
### 1a. The bet as literally stated is a category error
|
||||
|
||||
"Mirror the target's own structure" cannot mean mirroring `nextgraph-rs`'s tree (`engine/`, `sdk/js/lib-wasm`, `sdk/js/orm`). Every line this library ships lives in the polyfill; the three references are layers we *align on*, never places we write (`README.md` § *The three references*: "REFERENCES, not places we write code"). A folder named `engine/` or `verifier/` inside `src/` would claim residency in a layer we only read — the exact conflation the README warns produces false certainty. The right axis is the target's **stack as seen from the polyfill** — what each piece of our code stands in for, and therefore what happens to it at migration — not the target's repo tree.
|
||||
|
||||
### 1b. The three fates are real, but they are not three piles of equal nature
|
||||
|
||||
The two that evaporate at migration differ in the only way that matters for divergence:
|
||||
|
||||
- **Stand-ins for native behaviour** (cap possession and filing, the reach boundary, read filtering, inbox processing, branch registers, repo opening) have a **model to diverge from** — the engine's, level 1. This is where the dangerous failure lives: an emulation that drifts from the model teaches the consumer something to unlearn. Both incidents in `README.md` § *Design principle* happened here.
|
||||
- **Shared-wallet compensation** (the account directory, the physical user, the identity relay, the diagnostics) has **nothing to align on** — NO COUNTERPART at any layer. It cannot diverge from a model; its only law is invisibility from the surface. Its failure mode is *leaking*, not drifting.
|
||||
|
||||
And a fourth group the three-fate framing misses: the **target's model vocabulary** (the NURI grammar, the type guards, the branded types) — level-1-verified transcription that every layer consumes and that survives migration as knowledge rather than as code to delete.
|
||||
|
||||
### 1c. Alternatives, honestly
|
||||
|
||||
- **By feature** (`inbox/`, `caps/`, `read/`…): optimises "find everything about X", which the api-contract's by-subject sections already do better — and it actively hides the fate axis: `inbox.ts` would stay one folder while its sender half is target-shaped surface and its reader half is emulation detail a consumer must not code against (`docs/api-contract.md` § 9). Rejected: it organises along the axis that is already served and flattens the one that is not.
|
||||
- **By dependency direction** (layered, low → high): the import graph refuses it. `docs.ts` (surface) calls `getCaps().mint` (emulation) because upstream `doc_create` itself commits `AddRepo` (level 1, `engine/verifier/src/request_processor.rs:698`, re-verified); `emulated-verifier/connect.ts` (verifier stand-in) calls `resolveAccount` (shim) because the emulation runs on the shim. These cross-fate imports are *target-faithful*, not accidents — a layout that forbids them would force artificial inversions or be violated on day one. Rejected: it encodes a property the semantics do not have.
|
||||
- **Flat with naming conventions only** (`surface-docs.ts`, `shim-physical.ts`…): carries the same information at the same churn — a rename churns every importer exactly as a move does — with weaker affordances: no per-folder contract note, no one-glance grouping, and no folder-granular entry rule to grep or lint. Prefixes also rot silently in a way a misplaced file in a four-folder tree does not. Rejected as strictly dominated: same cost, less structure.
|
||||
- **Do nothing — rely on the contracts:** the serious alternative. The contracts are finer-grained than any layout (per-claim epistemic labels, not per-module), and they were verified at the source. But they are read *after* the fact; the incident that motivates this analysis happened in a module whose own header states the right doctrine. A layout is confronted *during* the edit: a new module must be placed, and placing it forces the "which fate?" question at the moment the docs.ts-style mistake is made. Layout and contracts are complementary instruments — the layout is the cheap always-on prompt, the contracts remain the enforcement.
|
||||
|
||||
### 1d. What the layout actually buys — bounded claims
|
||||
|
||||
1. **The placement question fires at creation time.** A new module cannot be added without answering "surface, native stand-in, shared-wallet, or model?" — the question whose non-asking is the root of the flat layout's failure.
|
||||
2. **The entry rule becomes folder-granular and mechanical.** Today `index.ts`'s purity is maintained per-symbol (the hand-built `surface/placement.ts` slice). With folders the rule is "`index.ts` re-exports only from `surface/` and `model/`" — one grep, lintable in CI, reviewable at a glance.
|
||||
3. **Cross-fate imports become visible seams.** `import { … } from "../emulated-verifier/…"` inside `surface/docs.ts` is a reviewable event in a diff; the same call inside a flat sibling import is invisible. The seam does not *prevent* the docs.ts incident class — it makes it show up in review.
|
||||
4. **The contracts map onto the tree.** `docs/api-contract.md` ≈ `surface/` + `model/`; `docs/internal-contract.md` ≈ `emulated-verifier/` + `shared-wallet/`. Drift between doc and code becomes a folder-membership diff instead of an inventory audit.
|
||||
5. **It generalises a pattern this repo already proved.** `surface/placement.ts` (a hand-maintained surface slice), `shared-wallet/physical.ts` (privilege as *separate functions*, not exemption flags), and the 2026-08-03 entry-header fix are all the same idea implemented piecemeal at module granularity. The layout is the same discipline promoted to the tree.
|
||||
|
||||
**Verdict on the bet:** "easier to spot" — substantially yes (points 2–4). "Harder to commit" — only mildly: nothing in a folder tree stops a determined or oblivious edit, and the decisive question (*is this behaviour the target's?*) is answered by reading `nextgraph-rs`, not by any layout (§ 6). Worth doing, with the expectations of § 1d and the costs of § 5.
|
||||
|
||||
---
|
||||
|
||||
## 2. The recommended layout
|
||||
|
||||
Both entry files stay at `src/` root, so `package.json`'s `exports` map is untouched and the consumer application sees no change. *(The two doors were merged into one on 2026-08-07 — the `exports` map is now just `.`, and the polyfill-era symbols sit in a marked block of `index.ts`.)*
|
||||
|
||||
| Folder | What the name asserts | Alignment reference | Fate at migration |
|
||||
|---|---|---|---|
|
||||
| `src/` root (`index.ts`, `polyfill.ts`) | The two published doors, nothing else. `index.ts` may re-export only from `surface/` and `model/`; `polyfill.ts` may re-export by name from anywhere — it is the polyfill-era door and its imports *are* the list of what dies. *(Merged 2026-08-07: one door, `index.ts`, with the polyfill-era symbols in a marked block. The rule survives as a block boundary instead of a file boundary.)* | — | The SDK-shaped half is replaced by the real SDK via the build alias; the polyfill-era block is deleted. |
|
||||
| `model/` | The target's addressing model, transcribed: pure vocabulary (types, NURI grammar, guards). No I/O, no state, no minting. Importable by every layer. | Level 1, verified (`NuriV0`, `readcap_nuri` — `engine/repo/src/types.rs:518-521`) | Survives as knowledge; the guards stay useful against the real SDK (which takes plain strings). |
|
||||
| `surface/` | App-facing, and every symbol has a target counterpart — verified or a documented bet — in `docs/api-contract.md`. A consumer coding against this folder learns nothing to unlearn. | Levels 3/2 where they answer, level-1 shape where they do not (per subject, in the contract) | Deleted when the alias flips; the consumer's code is unchanged. |
|
||||
| `emulated-verifier/` | Stand-ins for what the engine/verifier/broker do natively: possession, filing, boundary, non-delivery, inbox processing, branch registers, repo opening. Aligned on the level-1 model; each module names its native counterpart mechanism. **This is the folder where divergence from the model is possible, and its main risk.** | Level 1 (the model is the specification) | Deleted — the native side takes over. |
|
||||
| `shared-wallet/` | Exists only because one wallet hosts every identity. NO COUNTERPART at any layer — nothing to align on; the only law is invisibility from `surface/` and from the consumer. | None (nothing upstream has an image of this) | Evaporates entirely, replaced by nothing. |
|
||||
|
||||
On the name `emulated-verifier/`: every module in it has its native counterpart running *in the verifier* (cap state and Store/User-branch replay, `Verifier::load_repo_from_read_cap` `engine/verifier/src/verifier.rs:2237`, level 1; non-delivery, `resolve_target_for_sparql` → `RepoNotFound` `engine/verifier/src/request_processor.rs:264,269`, level 1, re-verified; inbox processing, `Verifier::inbox` `verifier.rs:1674-1690`, level 1; session repos, `self.repos`). The `emulated-` prefix is load-bearing: it says *stands in for*, never *is* — the residency confusion § 1a rules out.
|
||||
|
||||
---
|
||||
|
||||
## 3. Module-by-module assignment
|
||||
|
||||
The 25 current modules, with the two splits' offspring shown where a module divides (§ 4 gives the criterion and the rulings). "Stays whole" means the file moves as-is.
|
||||
|
||||
| Current module | Destination | What the placement asserts / notes |
|
||||
|---|---|---|
|
||||
| `index.ts` | `src/index.ts` (unchanged path) | The SDK-entry manifest. New rule made checkable: imports only from `surface/` and `model/`. |
|
||||
| `polyfill.ts` | `src/polyfill.ts` (path unchanged) + **new** `shared-wallet/bootstrap.ts` | Split: the entry keeps the re-exports; the config store (`configure`, `getConfig`, `registryDeps`, the current-user relay, the `CapRegistry` singleton wiring) moves to `shared-wallet/bootstrap.ts` — it is the injection machinery with NO COUNTERPART by design (`docs/api-contract.md` § 1). Side effect: removes the current entry↔internal import cycles (`polyfill.ts:16` ↔ `connect.ts:37`; `polyfill.ts:228` ↔ `inbox.ts:32`). |
|
||||
| `types.ts` | `model/types.ts`, minus `NgLike` / `UseShapeLike` → `shared-wallet/bootstrap.ts` | `Nuri`/`ReadCap`/`Scope` are level-1-verified vocabulary; `PrincipalId` stays with a note (target: the wallet user; polyfill: a relayed id). `NgLike`/`UseShapeLike` describe the *injection*, not the target — they belong to the bootstrap. See § 5 for the published-type wrinkle this creates. |
|
||||
| `nuri.ts` | `model/nuri.ts`, minus `mintCap` → `emulated-verifier/` | The guards and `targetOf`/`parseNuri` are the model transcription. `mintCap` is the emulation's minting point — upstream only the engine mints, at repo creation (level 1, `BlockRef::readcap_nuri`, `engine/repo/src/types.rs:518-521`) — and its presence in the model module contradicts the module's own header ("nothing on the surface turns a bare reference into a cap"). Cap-enforcement swaps its constant; migration deletes it. |
|
||||
| `sparql.ts` | `surface/sparql.ts` | Published, generic injection-safety utilities with NO COUNTERPART and none expected (`docs/api-contract.md` § 11) — the one surface family that survives *any* migration unchanged. Placed with the surface because it is published and documented there; the folder note must carry this exception. |
|
||||
| `docs.ts` | `surface/docs.ts` — stays whole | Level-2 passthroughs whose in-body cap filing and reach guard *mirror the target's own composition* (§ 4 ruling). The mint and the guard become named imports from `emulated-verifier/` — the visible seam. |
|
||||
| `lifecycle.ts` | `surface/lifecycle.ts` | Pure forwarding to the injected level-2/3 calls (`docs/api-contract.md` § 2). |
|
||||
| `surface/ng-proxy.ts` | `surface/ng-proxy.ts` — stays whole | Builds the published `ng`; its two overrides compose `emulated-verifier/` predicates (the write guard stands in for `verify_perm` inside `Commit::verify`, level 1, `engine/repo/src/commit.rs:892-899`, re-verified — noting `verify` has no runtime caller today, which says nothing about the target). The `login` arm is finding F1 of the internal contract: an unprovenanced fabricated member — its fix is deletion, not relocation. |
|
||||
| `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-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. |
|
||||
| `emulated-verifier/caps.ts` | `emulated-verifier/caps.ts` — stays whole (+ receives `mintCap`) | The in-memory record of what the connected holder holds — the verifier's cap state. The per-holder `heldByHolder` keying is its one shared-wallet dimension (one wallet, many holders); it stays, isolated behind the injected `holder()` and noted: at migration there is exactly one holder and the map collapses. |
|
||||
| `emulated-verifier/reach.ts` | `emulated-verifier/reach.ts` | The emulated wallet boundary: stands in for "a repo you hold no cap for cannot even be addressed" (level 1, `resolve_target_for_sparql` → `RepoNotFound`, `request_processor.rs:264,269`, re-verified). The two-rules redundancy is a lib choice, documented. |
|
||||
| `emulated-verifier/read-filter.ts` | `emulated-verifier/read-filter.ts` | Stands in for cryptographic non-delivery (same level-1 citations); deleted at migration with nothing to migrate to. |
|
||||
| `emulated-verifier/connect.ts` | `emulated-verifier/connect.ts` — stays whole | The recipient-verifier moment (`Verifier::inbox` → `process_inbox`, level 1, `verifier.rs:1674-1690`). Its import of `resolveAccount` (shared-wallet) is a deliberate cross-fate *check* — connecting must not provision — and stays visible at the import line. |
|
||||
| `emulated-verifier/open-repo.ts` | `emulated-verifier/open-repo.ts`, minus `ensurePhysicalRepoOpen` → `shared-wallet/physical.ts` | Stands in for the verifier bringing repos into `self.repos` (native at migration: open by cap at bootstrap). Flag kept from the internal contract: this module is a *current-state heal*, not a model emulation — its barrier ("TabInfo then first State") is empirical, pinned only by the e2e CONTRACT-3 probe, and its header's mechanism claim is finding F2 (contradicted at the source). The folder cannot fix either (§ 6). |
|
||||
| `emulated-verifier/machinery.ts` | `emulated-verifier/machinery.ts` | The subject filter fabricates what is structurally impossible upstream: a content read cannot see Store/User/Header compartments because they are separate branches with no triples (level 1, `BranchCrdt::None`, `engine/repo/src/types.rs:1420`, re-verified). It sits beside `branch-registers.ts`, whose compartments it hides; note that `MACHINERY_NS` also covers the account-shim's vocabulary. |
|
||||
| `shared-wallet/physical.ts` | `shared-wallet/physical.ts` — grows into the complete privileged door | The quintessential shared-wallet module. It absorbs `subscribePhysicalDoc` and `ensurePhysicalRepoOpen`, so **one module is the machinery's entire unguarded API** — completing its own doctrine ("separate functions, never exemptions", `physical.ts:19-27`) at the tree level. Cost: the two unguarded cores get exported (under `Unguarded` names) from their mechanism modules; acceptable because neither entry ever re-exports them. |
|
||||
| `shared-wallet/virtualUsers.ts` | `shared-wallet/virtualUsers.ts` | Identity persistence for the shared wallet; NO COUNTERPART (`docs/api-contract.md` § 13); already correctly published via `/polyfill` only. |
|
||||
| `shared-wallet/access-log.ts` | `shared-wallet/access-log.ts` | Diagnoses the shared-wallet isolation leak; the identity it prefixes is the relayed virtual id. Deleted at migration. |
|
||||
| `shared-wallet/outbox-log.ts` | `shared-wallet/outbox-log.ts` | Polyfill-era trace probe over the injected SDK's private persistence (level-2 facts verified in the internal contract § 11). Deleted at migration. |
|
||||
|
||||
Resulting tree: 2 entry files + `model/` (2) + `surface/` (10) + `emulated-verifier/` (8) + `shared-wallet/` (6).
|
||||
|
||||
---
|
||||
|
||||
## 4. The mixed modules — mechanical detection, one criterion, and rulings
|
||||
|
||||
### Detection method
|
||||
|
||||
Fate labels exist per *export* in the two contracts; a module is mixed when its exports (or its internal effects) span fates. Three code signals find the internal effects mechanically, without trusting headers:
|
||||
|
||||
- **Signal A — wire call × emulation-state write:** the module calls the injected `ng` (`getConfig().ng`) *and* mutates emulation state (`getCaps().mint/learn/open`, `addLink`, `declareInfrastructure`). Grep hits: `docs.ts:73` (mint), `inbox.ts:385` (learn), `store-registry.ts:875,893-895,903,1169,1371` (learn/open), `connect.ts:67` (learn).
|
||||
- **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-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
|
||||
|
||||
**Split when the halves have different fates AND different callers. Keep whole when the mixture reproduces a composition the target itself performs atomically — and then express the emulated half as a named import from the other folder, so the seam is on the import line.** Corollary: an unguarded twin of a guarded operation always lives with the machinery that calls it, never beside its guarded sibling.
|
||||
|
||||
### 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** (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`.
|
||||
- **`nuri.ts` — SPLIT `mintCap` out.** Different fate (model vocabulary survives; the minting point is deleted when the engine mints) and the module's own stated invariant argues for it.
|
||||
- **`types.ts` — SPLIT the injection types out** (small; see § 5 for the published-type consequence, which must be decided, not slipped).
|
||||
- **`polyfill.ts` — SPLIT entry from config store.** Different fates (a published door vs internal state) and it removes real import cycles.
|
||||
- **`surface/ng-proxy.ts` — KEEP WHOLE.** 59 lines; the overrides *are* "what the native side takes over" and already compose `emulated-verifier/` predicates; the proxy artifact itself is the published surface. F1 (the fabricated `login` member) is fixed by deletion wherever the file lives.
|
||||
- **`emulated-verifier/caps.ts` — KEEP WHOLE.** The per-holder keying is shared-wallet-flavoured, but splitting holder-resolution from the possession model would fragment one coherent level-1 model for no boundary gain; the injected `holder()` already isolates the dimension that collapses at migration.
|
||||
- **`emulated-verifier/connect.ts` — KEEP WHOLE.** Its shim import is a deliberate cross-fate check (must-not-provision), which is exactly what the seam should show.
|
||||
|
||||
---
|
||||
|
||||
## 5. Cost and risk
|
||||
|
||||
**What does not change: the published surface.** Both entries keep their `src/` paths *(they were merged into one on 2026-08-07, and `package.json`'s `exports` map now maps only `.`)*; the `inbox.*` and `storeRegistry.*` namespaces are re-assembled at the entry with identical contents. A consumer application importing the entry sees nothing — with one deliberate exception below.
|
||||
|
||||
**Import churn — the inventory:**
|
||||
|
||||
- All 23 non-entry `src/` modules import each other relatively; every moved file churns its importers' paths (mechanical, type-checked).
|
||||
- 19 of 19 unit-test files deep-import `../src/*` — 66 static import lines (heaviest: `store-registry` ×16, `polyfill` ×14) **plus 3 dynamic `await import("../src/…")` sites** (`test/isolation-active.test.ts:359`, `test/reach.test.ts:201-202`) that a naive static-import codemod will miss and that fail only at runtime.
|
||||
- The e2e harness deep-imports twice (`e2e/polyfill-entry.ts:41-42`: `../src/store-registry`, `../src/accounts`); its package-name imports resolve through the exports map and are immune. `e2e/tsconfig.json` includes `"."` only — path-agnostic.
|
||||
- Decision to make alongside: whether `test/` mirrors the new folders (keeps the module↔spec correspondence at more churn) or stays flat.
|
||||
|
||||
**Silent-breakage candidates — the ones tests may not catch:**
|
||||
|
||||
1. **Module-evaluation order.** `polyfill.ts` is today both entry and config store and sits inside import cycles (`polyfill ↔ connect`, `polyfill ↔ inbox`) that work through ES-module hoisting; the `CapRegistry` singleton is constructed at module scope (`polyfill.ts:97`). Re-cutting the graph changes which module evaluates first; a cycle that works today can break — or, worse, *change initialization order without breaking*. Mitigation: extract `shared-wallet/bootstrap.ts` as its own first step with the full unit + e2e suite run before any other move (baseline discipline), since the e2e suite is what actually exercises load order against a real broker.
|
||||
2. **`export * from "./types"`.** After the types split, `NgLike`/`UseShapeLike` silently vanish from the `.` entry's type surface — erased types, so nothing in this repo's runtime tests notices; only the consumer's typecheck would. This is a real (if arguably desirable) published-surface change and must be an explicit decision: either re-export them deliberately from `/polyfill` (where `EventuallyConfig`, which references them, already lives) with a documented deprecation on `.`, or accept the narrowing and record it in the api-contract.
|
||||
3. **The contracts' citations — the largest single cost.** `docs/api-contract.md` and `docs/internal-contract.md` (plus several briefs) carry hundreds of `file:line` references into `src/`; every moved or split module stales them wholesale. These two documents are the library's enforcement instrument — letting their citations rot would undercut the very discipline the reorganisation serves. A citation-refresh pass over both contracts is part of the change, not a follow-up.
|
||||
4. **`git blame` archaeology.** Moves (and especially the three-way `store-registry` split) break naive blame; `--follow` works per-file but split hunks lose lineage. One-time tax; worth staging the splits as move-then-edit commits so content moves stay detectable.
|
||||
|
||||
**Staging that contains the risk:** (1) extract `shared-wallet/bootstrap.ts`, full suite green; (2) pure moves into the four folders, no content edits, full suite green; (3) the splits (`inbox`, `store-registry`, `nuri`, `types`), one per commit, each behind its baseline; (4) the citation-refresh pass on both contracts. Each stage leaves the published surface byte-identical (stage-3 exception 2 above being the one flagged decision).
|
||||
|
||||
---
|
||||
|
||||
## 6. What the layout will NOT fix
|
||||
|
||||
Being specific, because overclaiming here would recreate the false-certainty problem the layout is meant to reduce:
|
||||
|
||||
- **It cannot decide whether a behaviour is the target's.** The decisive act remains reading `nextgraph-rs`. Both README § *Design principle* incidents would have type-checked and folder-checked: "every document has a native inbox" was a *belief* error, and the owner-inbox pointer was a *model* error inside code that belongs exactly where it was. A correctly named folder holds wrong code without complaint.
|
||||
- **It cannot fix wrong claims inside correctly placed modules.** Finding F2 (`emulated-verifier/open-repo.ts`'s header asserts a silent-0-rows mechanism the source contradicts — upstream errors `RepoNotFound`, `request_processor.rs:264,269`, level 1) and `surface/watch-shape.ts`'s unprovenanced "planned upgrade" survive any tree untouched. Header claims are policed by source-verification passes, not placement.
|
||||
- **It is coarser than the epistemic labels.** PASSTHROUGH vs LEVEL-1 SHAPE vs ASSUMPTION vary per *claim* within one module (`inbox.post`'s act is level-1-shaped, its transport is pure emulation, arbitrary payloads are an ASSUMPTION — all in one function's orbit). A folder carries one label; the contracts remain the finer instrument and the layout must not be read as replacing them.
|
||||
- **It cannot stop in-module shape drift.** `Deposit` growing a target-document field — the exact divergence class of the reverted owner-inbox episode, since upstream a message carries no document (`InboxMsgBody`, `engine/net/src/types.rs:4265`, level 1) — is one line in a correctly placed file.
|
||||
- **It does not police the empirical bets.** The sync barrier's push ordering and "a held subscription keeps the repo open" are pinned by the e2e CONTRACT-3 probe alone; no layout substitutes for that tripwire.
|
||||
- **It does not remove dead or decorative surface** (`inbox.watch`'s ignored `intervalMs`, the decorative write caps) — inventory work, already tracked in the contracts.
|
||||
- **A wrong placement is worse than no placement.** Folders assert; a mis-filed module borrows the folder's authority (a shim-flavoured helper landing in `surface/` would *look* migration-safe). The contracts' per-subject verification remains the check on the layout — never the reverse.
|
||||
|
||||
---
|
||||
|
||||
*Cross-references: `README.md` § Design principle and § The three references (the doctrine this layout serializes into the tree); `docs/api-contract.md` (the would-be `surface/`+`model/` inventory); `docs/internal-contract.md` (the would-be `emulated-verifier/`+`shared-wallet/` inventory, findings F1–F5).*
|
||||
+21
-48
@@ -1,61 +1,34 @@
|
||||
# Vision & principes du polyfill `@ng-eventually/client`
|
||||
# Vision & principles of `@ng-eventually/polyfill`
|
||||
|
||||
## Raison d'être
|
||||
## Purpose
|
||||
|
||||
Un **stand-in fidèle en FORME** des primitives futures de NextGraph. Objectif
|
||||
**unique** : que les consommateurs (Festipod) soient **codés contre le modèle
|
||||
mental CORRECT** — celui de NextGraph fini — et **n'aient RIEN à réécrire** quand
|
||||
NextGraph fournira les vraies primitives.
|
||||
A **stand-in faithful in SHAPE** to NextGraph's future primitives. **Single** objective: that consumers (Festipod) be **coded against the CORRECT mental model** — the one of finished NextGraph — and have **NOTHING to rewrite** when NextGraph provides the real primitives.
|
||||
|
||||
## Ce que le polyfill n'est PAS
|
||||
## What the polyfill is NOT
|
||||
|
||||
Une couche de **sécurité**. Le **wallet partagé** (tout le monde partage les mêmes
|
||||
clés) + l'absence de vraie crypto rendent l'émulation **infiniment moins
|
||||
sécurisée** qu'un wallet-par-utilisateur — c'est un **véhicule de dev/staging**,
|
||||
pas un but. **L'insécurité est ACCEPTÉE.** Un attaquant qui contourne l'émulation
|
||||
n'est pas notre problème.
|
||||
A **security** layer. The **shared wallet** (everyone shares the same keys) plus the absence of real crypto make the emulation **infinitely less secure** than a wallet-per-user — it is a **dev/staging vehicle**, not a goal. **Insecurity is ACCEPTED.** An attacker who bypasses the emulation is not our problem.
|
||||
|
||||
## Le seul critère : shape-fidelity, avec RIGUEUR
|
||||
## The only criterion: shape-fidelity, with RIGOR
|
||||
|
||||
Les **surfaces exposées** doivent matcher **exactement la FORME** des primitives
|
||||
futures, **même là où l'enforcement est simulé**. Le **mode d'échec à éviter** :
|
||||
exposer la **mauvaise forme** → le consommateur code contre un modèle qui
|
||||
n'existera pas → réécriture. L'inversion **ACL** des ReadCaps était exactement ce
|
||||
défaut (une ACL là où le réel est **possession de clé**) — un manque de rigueur.
|
||||
The **exposed surfaces** must match the **exact SHAPE** of the future primitives, **even where enforcement is simulated**. The **failure mode to avoid**: exposing the **wrong shape** → the consumer codes against a model that will not exist → rewrite. The **ACL** inversion of ReadCaps was exactly that defect (an ACL where the real thing is **key possession**) — a lack of rigor.
|
||||
|
||||
## Simuler la crypto pour EMPÊCHER les raccourcis
|
||||
## Simulating crypto to PREVENT shortcuts
|
||||
|
||||
Sans un minimum de simulation crypto, des raccourcis préjudiciables sont pris (on
|
||||
lit le clair, on retombe sur des ACLs). Le polyfill **simule** donc le mécanisme
|
||||
final, assez pour tenir cet **invariant** :
|
||||
Without a minimum of crypto simulation, damaging shortcuts get taken (reading the plaintext, falling back on ACLs). The polyfill therefore **simulates** the final mechanism, enough to hold this **invariant**:
|
||||
|
||||
> **Un `did` (id nu, SANS ReadCap) et un NURI (AVEC ReadCap) sont traités
|
||||
> VRAIMENT différemment : le premier ne permet PAS de lire la donnée ; le second
|
||||
> est SUFFISANT et REQUIS.**
|
||||
> **A `did` (bare id, WITHOUT a ReadCap) and a NURI (WITH a ReadCap) are treated GENUINELY differently: the former does NOT allow reading the data; the latter is SUFFICIENT and REQUIRED.**
|
||||
|
||||
Concrètement : la donnée d'un document est **stockée chiffrée** (chiffrement
|
||||
symétrique par-doc, même léger) ; le **ReadCap = la clé** ; sans elle, **impossible
|
||||
de déchiffrer/lire**. Pas d'ACL, pas de clair accessible « à côté ». Obtenir la
|
||||
lecture = **détenir la clé**, exactement comme en cible.
|
||||
Concretely, **in the target**: a document's data is **stored encrypted** (per-doc symmetric encryption, however lightweight); the **ReadCap = the key**; without it, **decrypting/reading is impossible**. No ACL, no plaintext accessible "on the side". Obtaining read access = **holding the key**, exactly as in the target model.
|
||||
|
||||
## Conséquences de forme (à respecter partout)
|
||||
> **Not yet true here, and saying so matters.** The shape is in place — possession decides, every access is confined to the connected virtual user, caps are stored and read back — but the cap value is the constant `OK` and nothing is encrypted. Per-document encryption is the **cap-enforcement** work, and it is one function (`mintCap`, in `emulated-verifier/caps.ts` — this said `nuri.ts` until 2026-08-10). Until it lands, nothing this library does may be described as anonymous or private.
|
||||
|
||||
- **Tout est clés et URLs.** Il n'y a **pas** de notion d'appartenance, de rôle ni
|
||||
de liste d'autorisation dans le modèle : uniquement de la cryptographie
|
||||
symétrique et asymétrique, des URIs, et qui détient quelle clé. Toute forme
|
||||
exposée qui ressemble à une ACL, un `member`, un `role` ou une `permission` est
|
||||
une **mauvaise forme**, quel que soit l'échafaudage qu'on peut lire par ailleurs
|
||||
dans l'état courant de NextGraph.
|
||||
- **Lecture = possession de la clé de lecture** (ReadCap = `{id, clé}`). Un id nu
|
||||
(un `did` sans ReadCap) ne lit pas.
|
||||
- **Écriture = possession de la clé d'écriture** — une clé **distincte** de celle
|
||||
de lecture, donc un axe distinct, mais **de la possession elle aussi**.
|
||||
- **Partage d'un cap = le sceller à un destinataire** (livraison **durable**, au
|
||||
moment du partage — PAS une ACL re-déclarée à chaque session).
|
||||
- **Révocation = re-key** (nouvelle clé ; les anciens détenteurs gardent l'ancien
|
||||
état). Non-rétroactif.
|
||||
- **Référence cap-less** (nommer/pointer sans lire) **distincte** de la référence
|
||||
cap-porteuse.
|
||||
## Shape consequences (to respect everywhere)
|
||||
|
||||
Voir `readcap-and-nuri-model.md` (le vrai modèle, vérifié dans `nextgraph-rs`) et
|
||||
`briefs/2026-07-20-caps-emulation-alignment.md` (le chantier d'alignement).
|
||||
- **Everything is keys and URLs.** There is **no** notion of membership, role, or authorization list in the model: only symmetric and asymmetric cryptography, URIs, and who holds which key. Any exposed shape that looks like an ACL, a `member`, a `role`, or a `permission` is a **wrong shape**, whatever scaffolding one may otherwise read in the current state of NextGraph.
|
||||
- **Reading = possession of the read key** (ReadCap = `{id, key}`). A bare id (a `did` without a ReadCap) does not read.
|
||||
- **Writing = possession of the write key** — a key **distinct** from the read key, hence a distinct axis, but **possession too**.
|
||||
- **Sharing a cap = sealing it to a recipient** (**durable** delivery, at share time — NOT an ACL re-declared every session).
|
||||
- **Revocation = re-key** (new key; former holders keep the old state). Non-retroactive.
|
||||
- **Cap-less reference** (naming/pointing without reading) **distinct** from the cap-bearing reference.
|
||||
|
||||
See `readcap-and-nuri-model.md` (the real model, verified in `nextgraph-rs`) and `briefs/2026-07-20-caps-emulation-alignment.md` (the alignment effort).
|
||||
|
||||
@@ -0,0 +1,30 @@
|
||||
# Notebook — the library's example application
|
||||
|
||||
A minimal application written against `@ng-eventually/polyfill`, in plain DOM.
|
||||
|
||||
It exists for two reasons, and the second is the one that matters.
|
||||
|
||||
**It shows how to use the library.** Every call in `app.ts` is what a real consumer writes. There is no test scaffolding, no privileged import, no reaching into the library's internals — it resolves `@ng-eventually/polyfill` as an external consumer does. If something reads awkwardly here, it reads awkwardly for everyone.
|
||||
|
||||
**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 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
|
||||
|
||||
Signing in, writing notes by scope, listing one's own, reading a note from its bare reference, handing a reader the key to a protected note, opening a note for messages, leaving a message on someone else's note, and reacting to changes.
|
||||
|
||||
The four journeys the suite runs, and what each proves:
|
||||
|
||||
| Journey | What it proves |
|
||||
|---|---|
|
||||
| Bob reads Alice's PUBLIC note from its reference alone | A public store serves its notes' keys — a bare reference is enough, and no key ever crosses |
|
||||
| Alice's PROTECTED note stays shut until she shares it | The same gesture, the opposite outcome, decided by where the note sits and not by what was sent |
|
||||
| Bob leaves a message on Alice's note, and only Alice reads it | A depositor FINDS the address from the note itself; depositing grants no reading |
|
||||
| Each actor's list holds their own notes | The boundary, seen from the only place that matters: the screen |
|
||||
|
||||
It has also found three defects of its own, each one the harness could not see. The first turned out to be a LIBRARY defect rather than an application one: the connection work had to be awaited at sign-in, or a note just shared with you read as unreadable — so `ensureIdentity` now awaits it, and `connectedUser` left the published surface. The other two were the application's: a stale answer stayed on screen beside a fresh question, and changing the scope did not refresh the list.
|
||||
|
||||
## Running it
|
||||
|
||||
`cd packages/polyfill && bun run test:e2e:app` builds it, serves it, and drives it against the real broker. To open it by hand you need a wallet: serve the folder with a bundled `app.js` and a `/shared-wallet.ngw`, and set `__NOTEBOOK_WALLET_PASSWORD__`.
|
||||
@@ -0,0 +1,409 @@
|
||||
/**
|
||||
* Notebook — a minimal application written against `@ng-eventually/polyfill`.
|
||||
*
|
||||
* It exists for two reasons, and the second is the one that matters:
|
||||
*
|
||||
* 1. **It shows how to use the library.** Every call here is what a real consumer
|
||||
* writes; there is no test scaffolding, no privileged import, no reaching into the
|
||||
* library's internals. If something is awkward here, it is awkward for everyone.
|
||||
*
|
||||
* 2. **It is what the applicative e2e suite drives** (`packages/polyfill/e2e/notebook.ts`).
|
||||
* The other suite talks to a bag of methods on `window.__sdk`, which proves the
|
||||
* functions run but never that an application could be written with them — and that
|
||||
* gap shipped a real defect: a document's inbox was green in tests and unusable in
|
||||
* practice, because the harness handed the address across an identity boundary
|
||||
* through a variable. No application can do that. This app can only do what an
|
||||
* application can do, so a test that passes here means the surface is usable, not
|
||||
* merely callable.
|
||||
*
|
||||
* ── 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 store, capability possession, directed sharing, per-document
|
||||
* inboxes and reactive reads — without inventing a product.
|
||||
*
|
||||
* ── Plain DOM, on purpose ─────────────────────────────────────────────────
|
||||
* The library imposes no framework, so its example must not adopt one: a consumer
|
||||
* reading this should see the SDK calls, not a component tree. The UI here is the
|
||||
* shortest thing that makes each act reachable.
|
||||
*/
|
||||
|
||||
import {
|
||||
// SDK-shaped — these survive migration, the real SDK replaces them in place.
|
||||
docs,
|
||||
ensureIdentity,
|
||||
inbox,
|
||||
init,
|
||||
storeRegistry,
|
||||
subscribeDoc,
|
||||
initNg as initNgSignals,
|
||||
useShapeQuery,
|
||||
type Nuri,
|
||||
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;
|
||||
title: string;
|
||||
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
|
||||
// is the scaffolding, and at migration it goes: the app imports the real SDK, and the
|
||||
// identity comes from the wallet instead of a barrier.
|
||||
|
||||
configure({
|
||||
ng: realNg,
|
||||
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__ ?? "",
|
||||
},
|
||||
});
|
||||
|
||||
// The library's `init`, not the injected one — and this line is SDK-shaped, kept at
|
||||
// migration. It settles the identity before handing the page to the broker, so the
|
||||
// round-trip leaves with the identifier in the URL it carries. `realInit` called here
|
||||
// would navigate away first, and the barrier would never show.
|
||||
//
|
||||
// The callback is this application's own business, and only its own: it keeps the session
|
||||
// because the SPARQL primitives below take a `session_id`, exactly as the real SDK's do.
|
||||
// It used to ALSO hand the library a thunk unwrapping this event into a session shape —
|
||||
// plumbing every consumer wrote identically, and this one wrote wrong twice. The library
|
||||
// catches the same event on its way through `init` now (2026-08-12), so what is left here
|
||||
// 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) {
|
||||
// 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 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}> <${RDF_TYPE}> <${NOTE}> ; <${TITLE}> "${escape(title)}" ; <${BODY}> "${escape(body)}" }`,
|
||||
doc,
|
||||
);
|
||||
return doc;
|
||||
}
|
||||
|
||||
/**
|
||||
* 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 : "",
|
||||
}));
|
||||
}
|
||||
|
||||
/**
|
||||
* Read someone else's note from its REFERENCE.
|
||||
*
|
||||
* A reference is what circulates — you do not discover a note, someone gives you its
|
||||
* reference (a message, a URL, a QR code). It carries no key, and that is the point:
|
||||
* if the note is in a PUBLIC store the store hands its key to whoever asks, so the
|
||||
* reference is enough; if it is protected, the reference names the note and opens
|
||||
* nothing, until its owner shares it (see `shareNote`).
|
||||
*
|
||||
* It arrives as a plain string, from a field or a URL, and goes straight in: the
|
||||
* library validates it. Nothing to narrow, nothing to cast, and nothing that will have
|
||||
* to change when the real SDK takes that same string.
|
||||
*/
|
||||
async function readSharedNote(reference: string): Promise<Note | 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: reference as Nuri,
|
||||
title: values(TITLE)[0] ?? "(sans titre)",
|
||||
body: values(BODY)[0] ?? "",
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Hand a reader access to one of my notes.
|
||||
*
|
||||
* Names the NOTE and the PERSON — the two things this app has. Neither the key nor the
|
||||
* recipient's inbox appears: an application will handle neither once this is native
|
||||
* (upstream the verifier fills `ContactDetails.read_cap` itself), so it handles neither
|
||||
* now. Refuses if the note is not mine to share.
|
||||
*/
|
||||
async function shareNote(doc: Nuri, withUser: string): Promise<void> {
|
||||
await inbox.share(doc, withUser);
|
||||
}
|
||||
|
||||
/** Open a note for messages — only its owner can, and only they will read them. */
|
||||
async function openNoteForMessages(doc: Nuri): Promise<void> {
|
||||
await storeRegistry.openDocumentInbox(doc);
|
||||
}
|
||||
|
||||
/** Leave a message on someone else's note. One call, naming the NOTE. */
|
||||
async function leaveMessage(doc: Nuri, text: string): Promise<void> {
|
||||
await inbox.postToDocument(doc, { payload: { text } });
|
||||
}
|
||||
|
||||
/** The messages left on one of my notes — named by the note, like leaving one. */
|
||||
async function messagesOn(doc: Nuri): Promise<string[]> {
|
||||
const deposits = await inbox.readForDocument(doc);
|
||||
return deposits.map((d) => String((d.payload as { text?: string })?.text ?? ""));
|
||||
}
|
||||
|
||||
/** Re-render whenever a note changes — locally or from a peer. */
|
||||
function watchNote(doc: Nuri, onChange: () => void): () => void {
|
||||
return subscribeDoc(doc, onChange);
|
||||
}
|
||||
|
||||
// --- identity ---------------------------------------------------------------
|
||||
|
||||
let identity = "";
|
||||
|
||||
/**
|
||||
* Sign in, and learn who you are.
|
||||
*
|
||||
* One await, and it covers everything: the library settles the identity, waits for the
|
||||
* connection work it fires (restoring what others shared with you, draining your
|
||||
* inboxes), and **returns the identity**. The application keeps it only to display it —
|
||||
* no call takes it, because a session belongs to one user and the target's own
|
||||
* `doc_create` carries no user at all.
|
||||
*
|
||||
* This used to read the library's private storage key to find out who it was, which is a
|
||||
* boundary no consumer should be able to see. Writing this application is what made that
|
||||
* visible.
|
||||
*/
|
||||
async function signIn(): Promise<void> {
|
||||
identity = await ensureIdentity();
|
||||
await sessionReady;
|
||||
}
|
||||
|
||||
function escape(s: string): string {
|
||||
return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
|
||||
}
|
||||
|
||||
// --- the thinnest UI that makes each act reachable --------------------------
|
||||
|
||||
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 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>
|
||||
<button class="share" data-doc="${n.doc}">partager</button>
|
||||
<button class="open" data-doc="${n.doc}">ouvrir aux messages</button>
|
||||
<button class="msgs" data-doc="${n.doc}">messages</button>
|
||||
<div><code class="ref" data-testid="ref">${n.doc}</code></div>
|
||||
</li>`,
|
||||
)
|
||||
.join("");
|
||||
}
|
||||
|
||||
function wire(): void {
|
||||
// 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, val("title"), val("body"));
|
||||
await refresh();
|
||||
});
|
||||
el("openRef").addEventListener("click", async () => {
|
||||
el("shared").textContent = ""; // never show a previous answer beside a new question
|
||||
const note = await readSharedNote(val("reference"));
|
||||
el("shared").textContent = note ? `${note.title} — ${note.body}` : "(illisible)";
|
||||
});
|
||||
el("leave").addEventListener("click", async () => {
|
||||
el("left").textContent = "";
|
||||
await leaveMessage(val("onNote") as Nuri, val("message"));
|
||||
el("left").textContent = "déposé";
|
||||
});
|
||||
el("notes").addEventListener("click", async (e) => {
|
||||
const target = e.target as HTMLElement;
|
||||
const doc = target.dataset.doc as Nuri | undefined;
|
||||
if (!doc) return;
|
||||
el("shareResult").textContent = "";
|
||||
el("messages").textContent = "";
|
||||
if (target.classList.contains("share")) {
|
||||
await shareNote(doc, val("shareWith"));
|
||||
el("shareResult").textContent = "partagé";
|
||||
} else if (target.classList.contains("open")) {
|
||||
await openNoteForMessages(doc);
|
||||
el("shareResult").textContent = "ouverte aux messages";
|
||||
} else if (target.classList.contains("msgs")) {
|
||||
el("messages").textContent = (await messagesOn(doc)).join(" | ") || "(aucun)";
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
async function main(): Promise<void> {
|
||||
wire();
|
||||
await signIn();
|
||||
await refresh();
|
||||
}
|
||||
|
||||
void main();
|
||||
|
||||
// The e2e suite drives this app through the DOM. It exposes nothing else: a test that
|
||||
// needed a back door would be testing something an application cannot do. `watchNote`
|
||||
// is here because reactivity has no visible surface in this UI yet — not as an escape
|
||||
// hatch, and it takes no identity: switching user means reloading with another `?ng-id=`,
|
||||
// exactly as switching upstream means opening another wallet.
|
||||
(globalThis as { __notebook?: unknown }).__notebook = { watchNote };
|
||||
@@ -0,0 +1,59 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="fr">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>Notebook — exemple ng-eventually</title>
|
||||
<style>
|
||||
body { font: 15px/1.5 system-ui, sans-serif; max-width: 640px; margin: 24px auto; padding: 0 16px; color: #222; }
|
||||
fieldset { border: 1px solid #ddd; border-radius: 8px; margin: 0 0 16px; }
|
||||
legend { padding: 0 6px; color: #666; font-size: 13px; }
|
||||
input, select, button { font: inherit; padding: 6px 8px; }
|
||||
input { border: 1px solid #bbb; border-radius: 5px; }
|
||||
button { cursor: pointer; border: 1px solid #bbb; border-radius: 5px; background: #f6f6f6; }
|
||||
ul { list-style: none; padding: 0; }
|
||||
li { padding: 6px 0; border-bottom: 1px solid #eee; }
|
||||
code.ref { font-size: 11px; color: #888; user-select: all; }
|
||||
.out { color: #555; font-size: 13px; min-height: 1.2em; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<p>Connecté : <b id="who" data-testid="who"></b></p>
|
||||
|
||||
<fieldset>
|
||||
<legend>Écrire une note</legend>
|
||||
<input id="title" data-testid="title" placeholder="titre" />
|
||||
<input id="body" data-testid="body" placeholder="contenu" />
|
||||
<select id="scope" data-testid="scope">
|
||||
<option value="protected">protégée</option>
|
||||
<option value="public">publique</option>
|
||||
<option value="private">privée</option>
|
||||
</select>
|
||||
<button id="write" data-testid="write">écrire</button>
|
||||
</fieldset>
|
||||
|
||||
<fieldset>
|
||||
<legend>Mes notes</legend>
|
||||
<input id="shareWith" data-testid="share-with" placeholder="partager avec (identifiant)" />
|
||||
<ul id="notes" data-testid="notes"></ul>
|
||||
<p class="out" id="shareResult" data-testid="share-result"></p>
|
||||
<p class="out" id="messages" data-testid="messages"></p>
|
||||
</fieldset>
|
||||
|
||||
<fieldset>
|
||||
<legend>Ouvrir une note reçue</legend>
|
||||
<input id="reference" data-testid="reference" placeholder="référence de la note" size="46" />
|
||||
<button id="openRef" data-testid="open-reference">ouvrir</button>
|
||||
<p class="out" id="shared" data-testid="shared"></p>
|
||||
</fieldset>
|
||||
|
||||
<fieldset>
|
||||
<legend>Laisser un message sur la note d'un autre</legend>
|
||||
<input id="onNote" data-testid="on-note" placeholder="note visée" size="46" />
|
||||
<input id="message" data-testid="message" placeholder="message" />
|
||||
<button id="leave" data-testid="leave">déposer</button>
|
||||
<p class="out" id="left" data-testid="left"></p>
|
||||
</fieldset>
|
||||
|
||||
<script type="module" src="/app.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"name": "@ng-eventually/example-notebook",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"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/orm": "0.1.2-alpha.21",
|
||||
"@ng-org/web": "0.1.2-alpha.14"
|
||||
},
|
||||
"scripts": {
|
||||
"typecheck": "pnpm exec tsc --noEmit -p tsconfig.json"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,21 @@
|
||||
{
|
||||
"extends": "../../tsconfig.base.json",
|
||||
"compilerOptions": {
|
||||
"types": [
|
||||
"bun"
|
||||
],
|
||||
"noEmit": true,
|
||||
"lib": [
|
||||
"ESNext",
|
||||
"DOM"
|
||||
],
|
||||
"paths": {
|
||||
"@ng-eventually/polyfill": [
|
||||
"../../packages/polyfill/src/index.ts"
|
||||
]
|
||||
}
|
||||
},
|
||||
"include": [
|
||||
"."
|
||||
]
|
||||
}
|
||||
+7
-3
@@ -2,15 +2,19 @@
|
||||
"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/*"],
|
||||
"workspaces": [
|
||||
"packages/*",
|
||||
"examples/*"
|
||||
],
|
||||
"scripts": {
|
||||
"test": "bun test",
|
||||
"typecheck": "bunx tsc --noEmit -p packages/client/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"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,48 +0,0 @@
|
||||
# @ng-eventually/client
|
||||
|
||||
Two entry points — the data-plane is SDK-identical, the polyfill bootstrap is
|
||||
separate:
|
||||
|
||||
| Import | Surface |
|
||||
|---|---|
|
||||
| `@ng-eventually/client` | The same signature as the SDK — `ng`, `useShape`, `inbox` (+ types). 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. |
|
||||
| `@ng-eventually/client/polyfill` | The only non-SDK surface — `configure`, `setCurrentUser`, and capability helpers (`getCaps`, `grantRead`, `canRead`/`canWrite`). It falls away as NextGraph matures. |
|
||||
|
||||
```ts
|
||||
// bootstrap (the only non-SDK call) — inject the real SDK
|
||||
import { configure } from "@ng-eventually/client/polyfill";
|
||||
configure({ ng: realNg, useShape: realUseShape, sharedWallet, currentUser });
|
||||
|
||||
// from here on, a pure SDK surface:
|
||||
import { ng, useShape, inbox } from "@ng-eventually/client";
|
||||
await ng.doc_create(/* … */);
|
||||
const set = useShape(MyShape, scope); // filtered to what the identity may read
|
||||
await inbox.post(targetInbox, ref); // deposit (anticipated SDK API)
|
||||
```
|
||||
|
||||
## Principle — the polyfill compensates, it never extends
|
||||
|
||||
**The polyfill's ONLY reason to exist is to bridge a NextGraph implementation gap
|
||||
or a bug.** Every non-SDK surface must map to a capability NextGraph will provide
|
||||
natively, and must fall away at that point. The polyfill MUST NOT add functionality
|
||||
of its own — no bespoke features, no observability/tooling, no convenience API that
|
||||
isn't strictly "NextGraph will do this natively later." The test for any proposed
|
||||
addition: *does it compensate a real, exhibited NextGraph gap or bug?* If not, it
|
||||
does not belong here — build it in the consumer application, not in the polyfill.
|
||||
Corollary: a compensation whose gap is not actually exhibited on the target broker
|
||||
is dead weight, not defensive code — it should be removed, not kept "just in case."
|
||||
|
||||
What the polyfill adds on top of the real SDK (each emulated for now, native as
|
||||
NextGraph matures):
|
||||
- Shared-wallet identity (one wallet for everyone; the current identity id is
|
||||
relayed to the SDK).
|
||||
- Capability enforcement — a read filter + write guard over emulated grants
|
||||
attached to documents; the app declares a document's read policy and issues
|
||||
directed read grants.
|
||||
- Anticipated methods (inbox `post`, capability ops) with their future-SDK shapes,
|
||||
emulated for now.
|
||||
|
||||
Generic: no application domain. The consumer application injects its shapes and
|
||||
performs the acts of granting access. The relationship concept ("who is connected
|
||||
to whom") is the consumer application's own — the client exposes only directed
|
||||
per-document read grants.
|
||||
@@ -1,309 +0,0 @@
|
||||
/**
|
||||
* Real-broker plumbing for the SDK e2e harness — a DEDICATED test wallet for
|
||||
* `@ng-eventually/client`, fully separate from any consumer app's profile.
|
||||
*
|
||||
* Adapted from the Festipod app's `src/shared/support/hooks.ts` (the reference
|
||||
* real-broker Playwright flow): headless wallet CREATION on nextgraph.eu, broker
|
||||
* redirect via nextgraph.net, iframe handling. Here it authenticates a wallet
|
||||
* created FOR THIS LIB (distinct name + distinct profile dir), and loads the
|
||||
* minimal SDK page (sdk-entry.ts) inside the broker iframe.
|
||||
*/
|
||||
|
||||
import { chromium, type BrowserContext, type Page, type Frame } from "playwright";
|
||||
import { execSync } from "node:child_process";
|
||||
import * as http from "node:http";
|
||||
import * as fs from "node:fs";
|
||||
import * as os from "node:os";
|
||||
import * as path from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
|
||||
// ── Dedicated, gitignored profile + wallet (NOT the app's .playwright-profile) ──
|
||||
export const PROFILE_DIR = path.resolve(__dirname, ".playwright-profile-lib");
|
||||
const WALLET_READY_MARKER = path.join(PROFILE_DIR, ".wallet-ready");
|
||||
export const WALLET_NAME = "ng-eventually-e2e";
|
||||
export const WALLET_PASSWORD = "ng-eventually-e2e";
|
||||
|
||||
const ENTRY = path.resolve(__dirname, "sdk-entry.ts");
|
||||
const BUNDLE_OUT = path.resolve(__dirname, ".dist", "sdk-entry.js");
|
||||
|
||||
const LAUNCH_ARGS = [
|
||||
"--disable-features=PrivateNetworkAccessRespectPreflightResults,BlockInsecurePrivateNetworkRequests,PrivateNetworkAccessForWorkers,PrivateNetworkAccessForNavigations",
|
||||
"--allow-insecure-localhost",
|
||||
"--disable-web-security",
|
||||
];
|
||||
|
||||
function resolveChromePath(): string | undefined {
|
||||
const p = chromium
|
||||
.executablePath()
|
||||
.replace("chrome-headless-shell", "chrome")
|
||||
.replace("chromium_headless_shell", "chromium");
|
||||
return p.includes("headless") ? undefined : p;
|
||||
}
|
||||
|
||||
export 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, ".."),
|
||||
});
|
||||
}
|
||||
|
||||
export function serveHarness(): 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 sdk e2e</title></head><body><div id="root"></div><script type="module" src="/sdk-entry.js"></script></body></html>`;
|
||||
const server = http.createServer((req, res) => {
|
||||
if (req.url === "/sdk-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);
|
||||
}
|
||||
});
|
||||
return new Promise((resolve) => {
|
||||
server.listen(0, "127.0.0.1", () => {
|
||||
const port = (server.address() as { port: number }).port;
|
||||
resolve({ url: `http://127.0.0.1:${port}`, close: () => server.close() });
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Create the dedicated lib wallet once (headless UI flow on nextgraph.eu),
|
||||
* persisted in PROFILE_DIR. Mirrors Festipod's ensureAuth but with the lib's own
|
||||
* wallet name + profile. Idempotent via the ready marker.
|
||||
*/
|
||||
export async function ensureWallet(): Promise<void> {
|
||||
if (fs.existsSync(WALLET_READY_MARKER)) {
|
||||
console.log("[e2e] dedicated lib wallet present — skipping creation");
|
||||
return;
|
||||
}
|
||||
console.log("[e2e] creating dedicated lib wallet on nextgraph.eu...");
|
||||
fs.mkdirSync(PROFILE_DIR, { recursive: true });
|
||||
const ctx = await chromium.launchPersistentContext(PROFILE_DIR, {
|
||||
headless: true,
|
||||
executablePath: resolveChromePath(),
|
||||
args: LAUNCH_ARGS,
|
||||
});
|
||||
const page = ctx.pages()[0] || (await ctx.newPage());
|
||||
page.on("pageerror", () => {});
|
||||
try {
|
||||
await page.goto("https://nextgraph.eu/", { waitUntil: "domcontentloaded", timeout: 30000 });
|
||||
const createButton = page.getByText("Create Wallet", { exact: true });
|
||||
await createButton.waitFor({ state: "visible", timeout: 15000 });
|
||||
await createButton.click();
|
||||
|
||||
await page.waitForURL("**/account*", { timeout: 15000 }).catch(() => {});
|
||||
const acceptButton = page.getByText("I accept", { exact: true });
|
||||
await acceptButton.waitFor({ state: "visible", timeout: 15000 });
|
||||
await acceptButton.click();
|
||||
|
||||
const usernameInput = page.locator("#username-input");
|
||||
await usernameInput.waitFor({ state: "visible", timeout: 30000 });
|
||||
await usernameInput.fill(WALLET_NAME);
|
||||
const passwordInput = page.locator("#password-input");
|
||||
await passwordInput.waitFor({ state: "visible", timeout: 5000 });
|
||||
await passwordInput.fill(WALLET_PASSWORD);
|
||||
|
||||
const submitButton = page.getByText("create my wallet", { exact: false });
|
||||
await submitButton.waitFor({ state: "visible", timeout: 5000 });
|
||||
await submitButton.click();
|
||||
|
||||
await page.waitForURL("**/#/wallet/login", { timeout: 30000 });
|
||||
await page.waitForTimeout(2000);
|
||||
|
||||
// First login → bootstrap the verifier repos from the broker.
|
||||
const walletLink = page.getByText("Click here to login with your wallet");
|
||||
if (await walletLink.isVisible({ timeout: 5000 }).catch(() => false)) {
|
||||
await walletLink.click();
|
||||
await page.waitForTimeout(1000);
|
||||
}
|
||||
const loginPassword = page.locator('input[type="password"]');
|
||||
await loginPassword.waitFor({ state: "visible", timeout: 10000 });
|
||||
await loginPassword.fill(WALLET_PASSWORD);
|
||||
await loginPassword.press("Enter");
|
||||
await page.waitForTimeout(10000);
|
||||
console.log("[e2e] dedicated lib wallet created + bootstrapped");
|
||||
} finally {
|
||||
await ctx.close();
|
||||
}
|
||||
fs.writeFileSync(WALLET_READY_MARKER, new Date().toISOString());
|
||||
}
|
||||
|
||||
export async function launchWalletContext(): Promise<BrowserContext> {
|
||||
return chromium.launchPersistentContext(PROFILE_DIR, {
|
||||
headless: true,
|
||||
executablePath: resolveChromePath(),
|
||||
args: LAUNCH_ARGS,
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a BRAND-NEW wallet in a BRAND-NEW profile dir and RETURN the launched
|
||||
* context, without a `.wallet-ready` marker and WITHOUT tearing the context down.
|
||||
* Unlike {@link ensureWallet} (which reuses one persistent dedicated wallet across
|
||||
* runs — so it is always "hot"), this mints a genuinely FRESH wallet each call so
|
||||
* the cold-start (private-store repo not yet in `self.repos`) can be exercised.
|
||||
*
|
||||
* Same headless nextgraph.eu creation + first-login-bootstrap flow as ensureWallet,
|
||||
* but the context stays OPEN and is returned (with its dir) so the caller can then
|
||||
* open the SDK page in the SAME profile — i.e. the very first app session over a
|
||||
* wallet that has never run the app. Caller cleans up ctx + dir.
|
||||
*/
|
||||
export async function createFreshWalletContext(): Promise<{
|
||||
ctx: BrowserContext;
|
||||
dir: string;
|
||||
name: string;
|
||||
}> {
|
||||
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "ng-eventually-fresh-"));
|
||||
const name = "ng-fresh-" + Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
|
||||
const ctx = await chromium.launchPersistentContext(dir, {
|
||||
headless: true,
|
||||
executablePath: resolveChromePath(),
|
||||
args: LAUNCH_ARGS,
|
||||
});
|
||||
const page = ctx.pages()[0] || (await ctx.newPage());
|
||||
page.on("pageerror", () => {});
|
||||
await page.goto("https://nextgraph.eu/", { waitUntil: "domcontentloaded", timeout: 30000 });
|
||||
const createButton = page.getByText("Create Wallet", { exact: true });
|
||||
await createButton.waitFor({ state: "visible", timeout: 15000 });
|
||||
await createButton.click();
|
||||
|
||||
await page.waitForURL("**/account*", { timeout: 15000 }).catch(() => {});
|
||||
const acceptButton = page.getByText("I accept", { exact: true });
|
||||
await acceptButton.waitFor({ state: "visible", timeout: 15000 });
|
||||
await acceptButton.click();
|
||||
|
||||
const usernameInput = page.locator("#username-input");
|
||||
await usernameInput.waitFor({ state: "visible", timeout: 30000 });
|
||||
await usernameInput.fill(name);
|
||||
const passwordInput = page.locator("#password-input");
|
||||
await passwordInput.waitFor({ state: "visible", timeout: 5000 });
|
||||
await passwordInput.fill(WALLET_PASSWORD);
|
||||
|
||||
const submitButton = page.getByText("create my wallet", { exact: false });
|
||||
await submitButton.waitFor({ state: "visible", timeout: 5000 });
|
||||
await submitButton.click();
|
||||
|
||||
await page.waitForURL("**/#/wallet/login", { timeout: 30000 });
|
||||
await page.waitForTimeout(2000);
|
||||
|
||||
// First login → bootstrap the verifier repos from the broker (this is what a
|
||||
// brand-new wallet does on its very first unlock).
|
||||
const walletLink = page.getByText("Click here to login with your wallet");
|
||||
if (await walletLink.isVisible({ timeout: 5000 }).catch(() => false)) {
|
||||
await walletLink.click();
|
||||
await page.waitForTimeout(1000);
|
||||
}
|
||||
const loginPassword = page.locator('input[type="password"]');
|
||||
await loginPassword.waitFor({ state: "visible", timeout: 10000 });
|
||||
await loginPassword.fill(WALLET_PASSWORD);
|
||||
await loginPassword.press("Enter");
|
||||
await page.waitForTimeout(10000);
|
||||
await page.close().catch(() => {});
|
||||
return { ctx, dir, name };
|
||||
}
|
||||
|
||||
/**
|
||||
* Launch a persistent context on a FRESH, EMPTY profile dir (its own userDataDir).
|
||||
* Empty local storage ⇒ empty verifier repo cache ⇒ the reconnection cold-start:
|
||||
* the same wallet's repos are on the broker but NOT in this profile's IndexedDB, so
|
||||
* a session over it starts with an empty `self.repos`. Caller must import the wallet
|
||||
* (see {@link importWalletViaFile}) before opening the SDK page. Returns the context
|
||||
* and the dir so the caller can clean it up.
|
||||
*/
|
||||
export async function launchCleanProfileContext(): Promise<{ ctx: BrowserContext; dir: string }> {
|
||||
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "ng-eventually-clean-"));
|
||||
const ctx = await chromium.launchPersistentContext(dir, {
|
||||
headless: true,
|
||||
executablePath: resolveChromePath(),
|
||||
args: LAUNCH_ARGS,
|
||||
});
|
||||
return { ctx, dir };
|
||||
}
|
||||
|
||||
/**
|
||||
* Import a `.ngw` wallet FILE into the current (clean) profile via the standalone
|
||||
* nextgraph.eu "Import a Wallet File" flow, then unlock it with the password. After
|
||||
* this the profile holds the wallet — but NOT the repos' local cache — so the next
|
||||
* SDK session over it hits the broker-only cold-start. Adapted from the Festipod
|
||||
* app's `importWalletViaFile` (the proven real-broker wallet-file import).
|
||||
*/
|
||||
export async function importWalletViaFile(page: Page, ngwPath: string): Promise<void> {
|
||||
await page.goto("https://nextgraph.eu/#/wallet/login", { waitUntil: "domcontentloaded" });
|
||||
// Let the SPA render + attach the file input (uploading too early → EncryptionError).
|
||||
await page.waitForTimeout(3000);
|
||||
await page.locator('input[type=file]').waitFor({ state: "attached", timeout: 15000 });
|
||||
await page.setInputFiles('input[type=file]', ngwPath);
|
||||
const passwordInput = page.locator('input[type=password]').first();
|
||||
await passwordInput.waitFor({ state: "visible", timeout: 15000 });
|
||||
await passwordInput.fill(WALLET_PASSWORD);
|
||||
await passwordInput.press("Enter");
|
||||
const confirm = page.getByRole("button", { name: /Confirm/i });
|
||||
if (await confirm.isVisible({ timeout: 2000 }).catch(() => false)) await confirm.click().catch(() => {});
|
||||
await page.waitForTimeout(8000); // unlock + verifier bootstrap from the broker
|
||||
}
|
||||
|
||||
/**
|
||||
* Navigate through the broker (nextgraph.net redirect) to load `appUrl` in the
|
||||
* broker iframe; unlock the dedicated wallet if a login is shown; return the app
|
||||
* iframe Frame. Adapted from Festipod setupBrokerPage + completeBrokerLogin.
|
||||
*/
|
||||
export async function setupBrokerPage(page: Page, appUrl: string): Promise<Frame> {
|
||||
const brokerRedirect = `https://nextgraph.net/redir/#/?o=${encodeURIComponent(appUrl)}`;
|
||||
await page.goto(brokerRedirect, { waitUntil: "domcontentloaded" });
|
||||
|
||||
const loginButton = page.getByText("Login", { exact: true });
|
||||
if (await loginButton.isVisible({ timeout: 2000 }).catch(() => false)) {
|
||||
await loginButton.click();
|
||||
await page.waitForURL("**/wallet/login", { timeout: 5000 }).catch(() => {});
|
||||
}
|
||||
|
||||
const hasAppFrame = () => page.frames().some((f) => f.url().includes("127.0.0.1"));
|
||||
const walletLink = page.getByText("Click here to login with your wallet", { exact: false });
|
||||
const loginDeadline = Date.now() + 25000;
|
||||
while (Date.now() < loginDeadline && !hasAppFrame() && !(await walletLink.isVisible().catch(() => false))) {
|
||||
await page.waitForTimeout(500);
|
||||
}
|
||||
|
||||
if (!hasAppFrame() && (await walletLink.isVisible().catch(() => false))) {
|
||||
await walletLink.click();
|
||||
await page.waitForTimeout(1000);
|
||||
const passwordInput = page.locator('input[type="password"]');
|
||||
if (await passwordInput.isVisible({ timeout: 8000 }).catch(() => false)) {
|
||||
await passwordInput.fill(WALLET_PASSWORD);
|
||||
await passwordInput.press("Enter");
|
||||
await page.waitForTimeout(3000);
|
||||
}
|
||||
}
|
||||
|
||||
let appFrame: Frame | null = null;
|
||||
const deadline = Date.now() + 30000;
|
||||
while (Date.now() < deadline) {
|
||||
for (const f of page.frames()) {
|
||||
if (f.url().startsWith(appUrl) || f.url().includes("127.0.0.1")) {
|
||||
appFrame = f;
|
||||
break;
|
||||
}
|
||||
}
|
||||
if (appFrame) break;
|
||||
for (const iframe of await page.locator("iframe").all()) {
|
||||
const src = await iframe.getAttribute("src");
|
||||
if (src && src.includes("127.0.0.1")) {
|
||||
const el = await iframe.elementHandle();
|
||||
appFrame = (await el?.contentFrame()) ?? null;
|
||||
if (appFrame) break;
|
||||
}
|
||||
}
|
||||
if (appFrame) break;
|
||||
await page.waitForTimeout(500);
|
||||
}
|
||||
|
||||
if (!appFrame) {
|
||||
const frames = page.frames().map((f) => f.url());
|
||||
throw new Error(`SDK iframe not found after 30s. Frames: ${JSON.stringify(frames)}`);
|
||||
}
|
||||
return appFrame;
|
||||
}
|
||||
@@ -1,34 +0,0 @@
|
||||
{
|
||||
"name": "@ng-eventually/client",
|
||||
"version": "0.0.0",
|
||||
"type": "module",
|
||||
"description": "SDK-identical client wrapper over @ng-org/web + @ng-org/orm with emulated capabilities and inbox. Drop-in; remove at migration.",
|
||||
"main": "./src/index.ts",
|
||||
"types": "./src/index.ts",
|
||||
"exports": {
|
||||
".": "./src/index.ts",
|
||||
"./polyfill": "./src/polyfill.ts"
|
||||
},
|
||||
"peerDependencies": {
|
||||
"@ng-org/web": "*",
|
||||
"@ng-org/orm": "*",
|
||||
"@ng-org/shex-orm": "*",
|
||||
"@ng-org/alien-deepsignals": "*"
|
||||
},
|
||||
"peerDependenciesMeta": {
|
||||
"@ng-org/web": { "optional": true },
|
||||
"@ng-org/orm": { "optional": true },
|
||||
"@ng-org/shex-orm": { "optional": true },
|
||||
"@ng-org/alien-deepsignals": { "optional": true }
|
||||
},
|
||||
"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"
|
||||
},
|
||||
"scripts": {
|
||||
"test": "bun test",
|
||||
"test:e2e": "bun run e2e/run.ts",
|
||||
"test:e2e:reactivity": "bun run e2e/reactivity-doc-subscribe.ts"
|
||||
}
|
||||
}
|
||||
@@ -1,134 +0,0 @@
|
||||
/**
|
||||
* Capability emulation — generic, with no domain rules. It models NextGraph
|
||||
* ReadCaps (and write caps) as a data layer can.
|
||||
*
|
||||
* In NextGraph a ReadCap is possession of a document's (repo's) read key: the
|
||||
* broker only delivers documents the wallet holds a cap for. The access unit is
|
||||
* therefore the document = repo, identified here by its NURI — the `@graph` an
|
||||
* item lives in, rather than the item. (A store is just a container repo, and
|
||||
* holding a store's cap does not grant the repos it references — each document
|
||||
* carries its own cap — so this registry is purely per-document, with no
|
||||
* store-level inheritance.)
|
||||
*
|
||||
* Sharing here is DIRECTED: a grant issues one grantee the read cap of one
|
||||
* document (`grantRead(doc, granteeId)`). Whether two identities are "connected"
|
||||
* — and therefore whether such a grant should be issued — is an application
|
||||
* concept the consumer owns; this layer only records the resulting per-document
|
||||
* grants. At migration this whole layer disappears: the broker/verifier enforces
|
||||
* the real caps and `useShape` returns only authorized documents.
|
||||
*/
|
||||
|
||||
import type { Nuri, PrincipalId, Scope } from "./types";
|
||||
|
||||
/**
|
||||
* Who holds the read/write cap of each document. The consumer populates it via
|
||||
* cap operations (make-public, directed grant…) exactly as it will in the
|
||||
* target; this layer enforces possession generically, with no policy of its own.
|
||||
*/
|
||||
export class CapRegistry {
|
||||
/** doc NURI → principals holding its READ cap. */
|
||||
private readers = new Map<Nuri, Set<PrincipalId>>();
|
||||
/** doc NURI → principals holding its WRITE cap. */
|
||||
private writers = new Map<Nuri, Set<PrincipalId>>();
|
||||
/** doc NURIs readable by everyone (public_store repos — no cap needed). */
|
||||
private publicDocs = new Set<Nuri>();
|
||||
/** doc NURI → its declared (scope, owner), as recorded at {@link open}. Lets
|
||||
* the consumer re-derive which documents are `protected` and who owns them
|
||||
* (see {@link protectedDocsOf}) so it can issue directed grants, without
|
||||
* re-supplying that per-document — it already declared it at open. */
|
||||
private policy = new Map<Nuri, { scope: Scope; owner: PrincipalId }>();
|
||||
|
||||
/** Grant `grantee` the READ cap of document `doc` — a directed grant. */
|
||||
grantRead(doc: Nuri, grantee: PrincipalId): void {
|
||||
add(this.readers, doc, grantee);
|
||||
}
|
||||
|
||||
/** Grant `principal` the WRITE cap of document `doc`. */
|
||||
grantWrite(doc: Nuri, principal: PrincipalId): void {
|
||||
add(this.writers, doc, principal);
|
||||
}
|
||||
|
||||
/** Mark `doc` public (readable without a cap — a public_store repo). */
|
||||
makePublic(doc: Nuri): void {
|
||||
this.publicDocs.add(doc);
|
||||
}
|
||||
|
||||
/**
|
||||
* Apply the caps a creator attaches to a fresh document, by scope. Public →
|
||||
* world-readable; protected/private → only the owner reads. The owner always
|
||||
* holds the write cap. Further sharing is a separate explicit grant.
|
||||
*/
|
||||
open(doc: Nuri, scope: Scope, owner: PrincipalId): void {
|
||||
if (scope === "public") this.makePublic(doc);
|
||||
else this.grantRead(doc, owner);
|
||||
this.grantWrite(doc, owner);
|
||||
this.policy.set(doc, { scope, owner });
|
||||
}
|
||||
|
||||
/**
|
||||
* The `protected` documents owned by `owner`, as recorded at {@link open}. The
|
||||
* consumer uses this to issue directed read grants: it decides who may read an
|
||||
* owner's protected documents (its own relationship concept) and calls
|
||||
* {@link grantRead} on each of these documents for each such reader. Public
|
||||
* documents are already world-readable and private documents stay owner-only,
|
||||
* so only the protected ones are surfaced here.
|
||||
*
|
||||
* This mirrors a native cap operation: in the target, sharing a protected repo
|
||||
* with another identity issues that identity the repo's ReadCap. Here the
|
||||
* consumer selects the documents via this accessor and grants the emulated read
|
||||
* cap on the same unit.
|
||||
*/
|
||||
protectedDocsOf(owner: PrincipalId): Nuri[] {
|
||||
const out: Nuri[] = [];
|
||||
for (const [doc, { scope, owner: o }] of this.policy) {
|
||||
if (scope === "protected" && o === owner) out.push(doc);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
/** Is `doc` under any READ-cap policy? (Undeclared docs are not enforced.) */
|
||||
governsRead(doc: Nuri): boolean {
|
||||
return this.publicDocs.has(doc) || this.readers.has(doc);
|
||||
}
|
||||
|
||||
/** Does `principal` hold a READ cap for `doc` (or is `doc` public)? */
|
||||
canRead(doc: Nuri, principal: PrincipalId | null): boolean {
|
||||
if (this.publicDocs.has(doc)) return true;
|
||||
if (principal === null) return false;
|
||||
return this.readers.get(doc)?.has(principal) ?? false;
|
||||
}
|
||||
|
||||
/** Is `doc` under any WRITE-cap policy? */
|
||||
governsWrite(doc: Nuri): boolean {
|
||||
return this.writers.has(doc);
|
||||
}
|
||||
|
||||
/** Does `principal` hold a WRITE cap for `doc`? */
|
||||
canWrite(doc: Nuri, principal: PrincipalId | null): boolean {
|
||||
if (principal === null) return false;
|
||||
return this.writers.get(doc)?.has(principal) ?? false;
|
||||
}
|
||||
|
||||
/** No READ policy declared → the read filter stays inert (passthrough). */
|
||||
hasReadPolicy(): boolean {
|
||||
return this.readers.size > 0 || this.publicDocs.size > 0;
|
||||
}
|
||||
|
||||
/** No WRITE policy declared → the write guard stays inert (passthrough). */
|
||||
hasWritePolicy(): boolean {
|
||||
return this.writers.size > 0;
|
||||
}
|
||||
|
||||
clear(): void {
|
||||
this.readers.clear();
|
||||
this.writers.clear();
|
||||
this.publicDocs.clear();
|
||||
this.policy.clear();
|
||||
}
|
||||
}
|
||||
|
||||
function add(m: Map<Nuri, Set<PrincipalId>>, doc: Nuri, principal: PrincipalId): void {
|
||||
let s = m.get(doc);
|
||||
if (!s) m.set(doc, (s = new Set()));
|
||||
s.add(principal);
|
||||
}
|
||||
@@ -1,236 +0,0 @@
|
||||
/**
|
||||
* discovery — a GENERIC discovery-index surface, reusing the ONE deposit +
|
||||
* materialization mechanism (`inbox.ts`). GENERIC by construction: this module
|
||||
* knows no application domain (no event, no meeting-point). The consumer submits
|
||||
* an opaque reference and interprets the entries it reads back.
|
||||
*
|
||||
* ── The mechanism (see docs/decisions/discovery-model.md) ─────────────────
|
||||
* Access and discovery are separate concerns. A public entity is world-readable
|
||||
* with its NURI; the discovery index is how a client learns that NURI exists
|
||||
* without holding a grant to read its creator's other documents. There is one
|
||||
* global index — an owned document (public read), fed via its own inbox. A
|
||||
* creator deposits a reference into the index's inbox; reading the index folds
|
||||
* those deposits into entries, deduplicating identical references along the way.
|
||||
*
|
||||
* ── The special account (polyfill owner) ──────────────────────────────────
|
||||
* Ownership of a truly global index is undecided in the real platform, where an
|
||||
* identity's apps and services see only what that identity shares. The polyfill
|
||||
* therefore parks ownership on a reserved special account in the shim
|
||||
* ({@link INDEX_ACCOUNT}). Its `public` scope document is the index document;
|
||||
* deposits land in that document's inbox (a stable NURI: every client opening the
|
||||
* same shared wallet resolves the same account, so the same document). This is
|
||||
* the app-facing discovery path, in place of a cross-account fan-out
|
||||
* (`store-registry.ts` `listEntityDocs`), which survives only as an internal
|
||||
* fallback (see {@link readIndex}).
|
||||
*
|
||||
* ── Real target vs this emulation ─────────────────────────────────────────
|
||||
* The intended real shape is: `submitToIndex` seals a reference into the index
|
||||
* document's own inbox (a future `inbox_post_link`), and reading the index is a
|
||||
* query on the materialized index document. Here, everything runs in-lib on the
|
||||
* shared wallet (deposit via `inbox.post`, fold via `inbox.read`). Against real
|
||||
* NextGraph the special account gives way to the decided global-index owner and
|
||||
* `readIndex` points at that document; the consumer surface (`submitToIndex` /
|
||||
* `readIndex`) is designed to survive that change unchanged.
|
||||
*
|
||||
* All NextGraph I/O routes through `inbox.ts` (which routes through the `docs`
|
||||
* primitives, the real injected `ng`), so this module imports no `@ng-org`
|
||||
* package.
|
||||
*/
|
||||
|
||||
import * as inbox from "./inbox";
|
||||
import { subscribeDoc } from "./subscribe";
|
||||
import { ensureRepoOpen } from "./open-repo";
|
||||
import { ensureAccount, reservedAccount } from "./store-registry";
|
||||
import { getCaps } from "./polyfill";
|
||||
import type { Nuri, PrincipalId } from "./types";
|
||||
|
||||
/**
|
||||
* The reserved special account that owns the global discovery index in the
|
||||
* polyfill. It hosts the index document but is never a real identity. It lives in
|
||||
* the registry's reserved namespace ({@link reservedAccount}), whose key
|
||||
* `normalizeId` can never produce, so an id of "index"/"@index" cannot hijack it
|
||||
* (it normalizes to "index", a disjoint key). Removed against real NextGraph
|
||||
* (see file header).
|
||||
*/
|
||||
export const INDEX_ACCOUNT = reservedAccount("index");
|
||||
|
||||
/** One entry as materialized from the discovery index. */
|
||||
export interface IndexEntry {
|
||||
/** The reference submitted by a creator (opaque — the consumer interprets it). */
|
||||
ref: unknown;
|
||||
/** The submitter, if identified; `null` when the submission was anonymous. */
|
||||
from: PrincipalId | null;
|
||||
/** Submission timestamp (ms epoch). */
|
||||
ts: number;
|
||||
}
|
||||
|
||||
/** Options for {@link submitToIndex}. */
|
||||
export interface SubmitOptions {
|
||||
/**
|
||||
* Who is submitting. Omit for the current identity, or pass `null` for an
|
||||
* anonymous submission. `from` is bound to the current identity by the inbox
|
||||
* (naming another identity is rejected as a spoof — see {@link inbox.post}).
|
||||
*/
|
||||
from?: PrincipalId | null;
|
||||
/**
|
||||
* The NURI of the document being made discoverable. When given, the index
|
||||
* admits only a public document: one under a non-public (protected/private)
|
||||
* read policy is refused, so the world-readable index never exposes a governed
|
||||
* document's NURI. Omit it only for a ref with no addressable document (rare);
|
||||
* a governed document passes it so the guard can fire.
|
||||
*/
|
||||
doc?: Nuri;
|
||||
/** Optional deposit timestamp (ms epoch). Omitted → `Date.now()`. Passing it
|
||||
* keeps tests deterministic. */
|
||||
ts?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve the NURI of the index document — the stable inbox where discovery
|
||||
* submissions land. The special account owns this document (its `public` scope
|
||||
* document, a real repo NURI from `docCreate`); deposits go into that document's
|
||||
* inbox exactly as host-registration deposits go into a host inbox. Because the
|
||||
* special account lives in the shim (persisted in the shared wallet's private
|
||||
* store), EVERY client opening the same wallet resolves the same account → the
|
||||
* same document NURI → ONE shared index for all clients. Distinct from
|
||||
* host-registration inboxes because it is a distinct document NURI.
|
||||
*/
|
||||
async function indexInboxNuri(): Promise<Nuri> {
|
||||
// Ensure the special account exists (idempotent) so its scope documents are
|
||||
// created and stably resolvable across clients.
|
||||
const record = await ensureAccount(INDEX_ACCOUNT);
|
||||
return record.docPublic;
|
||||
}
|
||||
|
||||
/**
|
||||
* The NURI of the global discovery-index document (the inbox where submissions
|
||||
* land). Exposed so a reactive reader ({@link watchShape}) that folds discovery
|
||||
* into the public read-set can SUBSCRIBE to this document and re-resolve when a
|
||||
* new public entity is announced. This is exactly {@link watchIndex}'s subscribe
|
||||
* anchor. Removed against real NextGraph along with the special account.
|
||||
*/
|
||||
export async function indexDocNuri(): Promise<Nuri> {
|
||||
return indexInboxNuri();
|
||||
}
|
||||
|
||||
/**
|
||||
* Submit a reference to the global discovery index — the SDK act "make this
|
||||
* discoverable". Deposits `ref` into the index document's inbox via
|
||||
* {@link inbox.post}; reading the index ({@link readIndex}) folds it into an
|
||||
* entry. `ref` is opaque here (the consumer serializes whatever a client needs to
|
||||
* later locate the entity — e.g. an entity document NURI plus discovery metadata).
|
||||
* `from` follows the inbox convention (anonymous when `null`).
|
||||
*
|
||||
* When `opts.doc` names the document being surfaced, a document under a
|
||||
* non-public read policy (protected/private) is refused: the global index is
|
||||
* world-readable, so admitting a governed document's NURI would expose it past
|
||||
* its scope.
|
||||
*/
|
||||
export async function submitToIndex(ref: unknown, opts?: SubmitOptions): Promise<void> {
|
||||
const doc = opts?.doc;
|
||||
if (doc !== undefined) {
|
||||
const caps = getCaps();
|
||||
// A governed doc is submittable ONLY if it is public (anonymous may read it).
|
||||
if (caps.governsRead(doc) && !caps.canRead(doc, null)) {
|
||||
throw new Error(
|
||||
"[ng-eventually] submitToIndex: only PUBLIC documents may be submitted to " +
|
||||
"the discovery index — a protected/private document must not be surfaced.",
|
||||
);
|
||||
}
|
||||
}
|
||||
const target = await indexInboxNuri();
|
||||
await inbox.post(target, {
|
||||
payload: ref,
|
||||
...(opts && "from" in opts ? { from: opts.from } : {}),
|
||||
...(opts?.ts !== undefined ? { ts: opts.ts } : {}),
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Read the global discovery index. Reads every submission from the index inbox,
|
||||
* deduplicates by serialized `ref` (a duplicate submission surfaces once — the
|
||||
* discovery model's moderation point), and returns the entries sorted by `ts`
|
||||
* ascending. Against real NextGraph this becomes a query on the materialized
|
||||
* index document.
|
||||
*/
|
||||
export async function readIndex(): Promise<IndexEntry[]> {
|
||||
const target = await indexInboxNuri();
|
||||
// COLD-START heal (polyfill-era): on a FRESH session over a persistent wallet the
|
||||
// discovery-index inbox repo is not yet in the verifier's `self.repos`, so the
|
||||
// anchored `inbox.read` below would resolve an unopened repo and silently return 0
|
||||
// deposits — the same self-inflicted cold-read gap `readScopeIndex`/`readUnion`
|
||||
// heal. This is what made the PUBLIC read's discovery fold come back empty on a
|
||||
// reconnect, so a fresh page's home stayed empty for tens of seconds while the doc
|
||||
// slowly synced by other means. Open/subscribe the index repo ONCE and await its
|
||||
// first `State` (the sync barrier) before the anchored read. Idempotent per session;
|
||||
// no-op with the unit fake ng (no `doc_subscribe`). This is done HERE (a cold direct
|
||||
// reader) rather than inside `inbox.read`, because `inbox.watch` already holds the
|
||||
// repo open via its own subscription and must not spawn a second bootstrap open. See
|
||||
// open-repo.ts.
|
||||
await ensureRepoOpen(target);
|
||||
const deposits = await inbox.read(target);
|
||||
const seen = new Set<string>();
|
||||
const entries: IndexEntry[] = [];
|
||||
for (const d of deposits) {
|
||||
// Dedup on the serialized reference — the materialization moderation point.
|
||||
const key = JSON.stringify(d.payload ?? null);
|
||||
if (seen.has(key)) continue;
|
||||
seen.add(key);
|
||||
entries.push({ ref: d.payload, from: d.from, ts: d.ts });
|
||||
}
|
||||
return entries;
|
||||
}
|
||||
|
||||
/**
|
||||
* Watch the discovery index — **event-driven, not polled**. Subscribes to the
|
||||
* index document via {@link subscribeDoc} (the platform's `doc_subscribe` push):
|
||||
* `onEntries` fires once on the initial state push and again on every subsequent
|
||||
* change to the index document — a local submission OR a broker-synced remote one.
|
||||
* Returns an unsubscribe. (Deduplication is applied on each read.)
|
||||
*
|
||||
* The `intervalMs` option is accepted for signature compatibility but IGNORED:
|
||||
* there is no polling. The index is a single document, so this is immune to the
|
||||
* ORM fan-out hang (see {@link subscribeDoc}).
|
||||
*/
|
||||
export function watchIndex(
|
||||
onEntries: (entries: IndexEntry[]) => void,
|
||||
_opts?: { intervalMs?: number },
|
||||
): () => void {
|
||||
let stopped = false;
|
||||
let lastCount = -1;
|
||||
let unsubscribe: (() => void) | null = null;
|
||||
|
||||
const refresh = async (): Promise<void> => {
|
||||
if (stopped) return;
|
||||
try {
|
||||
const entries = await readIndex();
|
||||
if (!stopped && entries.length !== lastCount) {
|
||||
lastCount = entries.length;
|
||||
onEntries(entries);
|
||||
}
|
||||
} catch (error) {
|
||||
console.error("[discovery] watchIndex read failed:", error);
|
||||
}
|
||||
};
|
||||
|
||||
// The index document NURI is resolved async (ensureAccount); subscribe once it
|
||||
// is known. The initial State push fires the first read (onEntries fires once),
|
||||
// each later Patch a re-read.
|
||||
void (async () => {
|
||||
try {
|
||||
const anchor = await indexInboxNuri();
|
||||
if (stopped) return;
|
||||
unsubscribe = subscribeDoc(anchor, () => void refresh());
|
||||
} catch (error) {
|
||||
console.error("[discovery] watchIndex subscribe failed:", error);
|
||||
}
|
||||
})();
|
||||
|
||||
return () => {
|
||||
stopped = true;
|
||||
if (unsubscribe) {
|
||||
unsubscribe();
|
||||
unsubscribe = null;
|
||||
}
|
||||
};
|
||||
}
|
||||
@@ -1,103 +0,0 @@
|
||||
/**
|
||||
* Low-level document + SPARQL primitives.
|
||||
*
|
||||
* These call the real injected `ng` (`getConfig().ng`) directly — never the
|
||||
* public `ng` proxy (`makeNg`). This is a validated hard constraint, not a style
|
||||
* choice: the public `ng` is a JS `Proxy` over `@ng-org/web`'s iframe-RPC proxy,
|
||||
* and layering our Proxy on top breaks `doc_create`'s `postMessage` marshaling
|
||||
* with **`DataCloneError: function ... could not be cloned`** — the footgun this
|
||||
* rule exists to prevent. Reaching the real `ng` held in the config avoids the
|
||||
* double-proxy. Do not import from `./ng-proxy`.
|
||||
*
|
||||
* Signatures mirror the real `@ng-org/web` `ng` surface (verified against the
|
||||
* app's storeRegistry usage), so this is a drop-in for those raw calls.
|
||||
*/
|
||||
|
||||
import { getConfig } from "./polyfill";
|
||||
import { logAccess, enabled as accessLogEnabled } from "./access-log";
|
||||
import type { Nuri } from "./types";
|
||||
|
||||
// The low common point for ALL document access: every read in the SDK routes
|
||||
// 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
|
||||
// |…); 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.
|
||||
|
||||
/** Count rows in a raw SPARQL SELECT result, tolerant of the possible shapes. */
|
||||
function rowCount(result: unknown): number {
|
||||
if (!result) return 0;
|
||||
if (Array.isArray(result)) return result.length;
|
||||
const anyRes = result as { results?: { bindings?: unknown[] } };
|
||||
return anyRes.results?.bindings?.length ?? 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Create one document → its NURI.
|
||||
*
|
||||
* Mirrors `ng.doc_create(session_id, crdt, cls, dest, store_repo?)`. For a graph
|
||||
* document in the (shared) private store: `docCreate(sid, "Graph", "data:graph",
|
||||
* "store")` (store_repo left undefined → private store).
|
||||
*/
|
||||
export async function docCreate(
|
||||
sessionId: string,
|
||||
crdt: string,
|
||||
cls: string,
|
||||
dest: string,
|
||||
store?: unknown,
|
||||
): Promise<Nuri> {
|
||||
const { ng } = getConfig();
|
||||
const nuri = await ng.doc_create(sessionId, crdt, cls, dest, store);
|
||||
// A container creation is a WRITE; the NURI only exists after the call.
|
||||
logAccess("WRITE", nuri, "docCreate");
|
||||
return nuri;
|
||||
}
|
||||
|
||||
/**
|
||||
* Run a SPARQL UPDATE (INSERT/DELETE DATA, etc.).
|
||||
*
|
||||
* Mirrors `ng.sparql_update(session_id, query, anchor?)`, where `anchor` is the
|
||||
* document NURI the update is scoped/base'd to (optional).
|
||||
*/
|
||||
export async function sparqlUpdate(
|
||||
sessionId: string,
|
||||
query: string,
|
||||
anchor?: Nuri,
|
||||
label = "sparqlUpdate",
|
||||
): Promise<void> {
|
||||
const { ng } = getConfig();
|
||||
// `label` is a lib-internal access-log tag, NOT forwarded to `ng`.
|
||||
logAccess("WRITE", anchor ?? "(no anchor)", label);
|
||||
return ng.sparql_update(sessionId, query, anchor);
|
||||
}
|
||||
|
||||
/**
|
||||
* Run a SPARQL SELECT/CONSTRUCT/ASK query → the raw SDK result.
|
||||
*
|
||||
* Mirrors `ng.sparql_query(session_id, query, base?, anchor?)`. `base` is the
|
||||
* query base IRI (usually `undefined`); `anchor` is the document NURI to query.
|
||||
*/
|
||||
export async function sparqlQuery(
|
||||
sessionId: string,
|
||||
query: string,
|
||||
base?: string,
|
||||
anchor?: Nuri,
|
||||
label = "sparqlQuery",
|
||||
): Promise<unknown> {
|
||||
const { ng } = getConfig();
|
||||
// `label` is a lib-internal access-log tag, NOT forwarded to `ng`.
|
||||
const result = await ng.sparql_query(sessionId, query, base, anchor);
|
||||
// Log AFTER the read so the row count (a strong leak signal: a doc rendering
|
||||
// rows under an identity that should see nothing) can be appended. Skip the
|
||||
// rowCount work entirely when the log is off.
|
||||
if (accessLogEnabled()) {
|
||||
// `rows` here are raw RDF triple bindings (the SPARQL `?s ?p ?o` result), NOT
|
||||
// domain objects — one document's entity is spread across several triple rows.
|
||||
// Spell that out so the log isn't mistaken for an object count (the app-level
|
||||
// object/shape count is logged separately by useShapeQuery → dataStats).
|
||||
logAccess("READ", anchor ?? "(no anchor)", label, " → " + rowCount(result) + " triple-rows");
|
||||
}
|
||||
return result;
|
||||
}
|
||||
@@ -1,349 +0,0 @@
|
||||
/**
|
||||
* Inbox — a generic deposit + read/materialize mechanism the consumer reuses for
|
||||
* its own purposes (same `inbox.post` API, same watcher — see the discovery-model
|
||||
* decision). The mechanism itself knows no application domain: the consumer
|
||||
* supplies the inbox document NURI and interprets the `payload`. (An example
|
||||
* consumer mapping, purely illustrative: a consumer might use one inbox for a
|
||||
* registration deposit and another for submitting a reference to an index.)
|
||||
*
|
||||
* ── Real target vs this emulation ─────────────────────────────────────────
|
||||
* In real NextGraph, a message is sealed to the recipient's key and queued into
|
||||
* their inbox; the recipient's own verifier unseals each queued message and
|
||||
* applies it inline as it processes the inbox — there is no separate curator
|
||||
* process. A future `inbox_post_link` is the intended way to seal a link into an
|
||||
* inbox from the sender side; it is not exposed yet.
|
||||
*
|
||||
* Here, on one shared wallet where everything is readable, both sides run in-lib:
|
||||
* - `post` appends a deposit `{ from, payload, ts }` as RDF into the inbox
|
||||
* document (in the shared wallet) via the `docs.sparqlUpdate` primitive;
|
||||
* - `read` / `watch` read the deposits back via `docs.sparqlQuery` and expose
|
||||
* them. This in-lib read stands in for the recipient's own inbox processing
|
||||
* until the sealed-inbox path (`inbox_post_link`) is available.
|
||||
*
|
||||
* All NextGraph I/O routes through the `docs` primitives (the real injected `ng`,
|
||||
* never `makeNg`), so this module imports no `@ng-org` package.
|
||||
*/
|
||||
|
||||
import { sparqlUpdate, sparqlQuery } from "./docs";
|
||||
import { subscribeDoc } from "./subscribe";
|
||||
import { ensureRepoOpen } from "./open-repo";
|
||||
import { getCurrentUser, getStoreRegistryDeps } from "./polyfill";
|
||||
import { escapeLiteral } from "./sparql";
|
||||
import {
|
||||
accessLogPrefix,
|
||||
enabled as accessLogEnabled,
|
||||
logAccess,
|
||||
logStage,
|
||||
shortNuri,
|
||||
} from "./access-log";
|
||||
import type { Nuri, PrincipalId } from "./types";
|
||||
|
||||
// --- deposit model --------------------------------------------------------
|
||||
|
||||
/** One deposit as materialized from an inbox document. */
|
||||
export interface Deposit {
|
||||
/** The sender, if identified; `null` when the deposit was anonymous. */
|
||||
from: PrincipalId | null;
|
||||
/** The consumer-defined payload (opaque here — JSON-serialized in storage). */
|
||||
payload: unknown;
|
||||
/** Deposit timestamp (ms epoch). Caller may pass one for determinism. */
|
||||
ts: number;
|
||||
}
|
||||
|
||||
/** Options for {@link post}. `from` and `ts` are both optional. */
|
||||
export interface PostOptions {
|
||||
/**
|
||||
* Who is depositing. Omit (or pass `null`) for an ANONYMOUS deposit; pass a
|
||||
* principal id to identify the sender. Defaults to the current polyfill user
|
||||
* ({@link getCurrentUser}) when the property is entirely absent, so callers
|
||||
* that want anonymity must pass `from: null` explicitly.
|
||||
*/
|
||||
from?: PrincipalId | null;
|
||||
/** The payload to deposit (interpreted only by the consumer). */
|
||||
payload: unknown;
|
||||
/** Optional deposit timestamp (ms epoch). Omitted → `Date.now()`. Passing it
|
||||
* keeps tests deterministic. */
|
||||
ts?: number;
|
||||
}
|
||||
|
||||
const SHIM = "urn:ng-eventually:inbox";
|
||||
const P = {
|
||||
type: `${SHIM}:Deposit`,
|
||||
from: `${SHIM}:from`,
|
||||
payload: `${SHIM}:payload`,
|
||||
ts: `${SHIM}:ts`,
|
||||
} as const;
|
||||
|
||||
// --- session access (shared with the storeRegistry) -----------------------
|
||||
|
||||
/** The inbox documents live in the shared wallet, so we reuse the registry's
|
||||
* injected session provider for the sessionId. Disappears at migration. */
|
||||
async function sessionId(): Promise<string> {
|
||||
return (await getStoreRegistryDeps().getSession()).sessionId;
|
||||
}
|
||||
|
||||
// --- diagnostic logging helper ---------------------------------------------
|
||||
|
||||
/**
|
||||
* Best-effort, length-capped JSON rendering of a deposit payload for the
|
||||
* inbox diagnostic log (see {@link enabled}/{@link logAccess}). This module
|
||||
* stays domain-agnostic (see module header) — it never interprets payload
|
||||
* fields, it only dumps them verbatim so the consumer's own shape (e.g. a
|
||||
* Festipod participation: `{ participantId, eventId, … }`) is visible in the
|
||||
* log without this module knowing that shape. Capped so one oversized payload
|
||||
* can't blow up a log line; a payload that fails to stringify (e.g. a
|
||||
* circular structure a caller mistakenly passed) falls back to `String()`.
|
||||
*/
|
||||
function summarizePayload(payload: unknown): string {
|
||||
let s: string;
|
||||
try {
|
||||
s = JSON.stringify(payload) ?? String(payload);
|
||||
} catch {
|
||||
s = String(payload);
|
||||
}
|
||||
return s.length > 200 ? s.slice(0, 200) + "…" : s;
|
||||
}
|
||||
|
||||
// --- SPARQL result helpers ------------------------------------------------
|
||||
|
||||
/** Tolerant extraction of SPARQL SELECT bindings across possible shapes. */
|
||||
function readBindings(result: unknown): Array<Record<string, { value: string }>> {
|
||||
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 ?? [];
|
||||
}
|
||||
|
||||
// --- deposit (client side) ------------------------------------------------
|
||||
|
||||
/**
|
||||
* Deposit a payload into `targetInbox`.
|
||||
*
|
||||
* Appends `{ from, payload, ts }` into the inbox document via `docs.sparqlUpdate`
|
||||
* (the real injected `ng`). Each deposit is a fresh RDF subject in the inbox
|
||||
* graph, so concurrent deposits don't collide.
|
||||
*
|
||||
* `from` is bound to the current identity — it is authenticated, not
|
||||
* caller-supplied. Omit it to stamp the current identity; pass `null` to deposit
|
||||
* anonymously (a legitimate choice — identified if known, anonymous otherwise).
|
||||
* A `from` naming another identity is rejected as a spoof: in the target the
|
||||
* broker seals the sender from the wallet's own key, so a client cannot forge
|
||||
* another's identity. This check is redundant once the seal enforces it, but
|
||||
* until then it closes the spoof the shared wallet would otherwise allow.
|
||||
*/
|
||||
export async function post(targetInbox: Nuri, opts: PostOptions): Promise<void> {
|
||||
const current = getCurrentUser();
|
||||
let from: PrincipalId | null;
|
||||
if (opts.from === undefined) {
|
||||
from = current; // default: stamp the current identity
|
||||
} else if (opts.from === null) {
|
||||
from = null; // explicit anonymous deposit
|
||||
} else if (opts.from === current) {
|
||||
from = opts.from; // identifying as self — allowed
|
||||
} else {
|
||||
throw new Error(
|
||||
"[ng-eventually] inbox.post: `from` must be the current identity or null " +
|
||||
"(anonymous) — depositing as another principal is a spoof.",
|
||||
);
|
||||
}
|
||||
const ts = opts.ts ?? Date.now();
|
||||
const sid = await sessionId();
|
||||
|
||||
// A unique subject per deposit (in the inbox graph) — no collisions.
|
||||
const subject = `${SHIM}:deposit:${ts}:${Math.random().toString(36).slice(2)}`;
|
||||
const payloadLiteral = escapeLiteral(JSON.stringify(opts.payload ?? null));
|
||||
const fromTriple =
|
||||
from == null ? "" : ` ;\n <${P.from}> "${escapeLiteral(from)}"`;
|
||||
|
||||
// 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
|
||||
// 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/client/e2e/` verified that an anchored `GRAPH <plainNuri>` write
|
||||
// ALSO round-trips here — it resolves to the same repo graph, no phantom graph.
|
||||
// The no-GRAPH form is kept as a simplicity/safety convention; re-verify with
|
||||
// that harness if the broker version changes.)
|
||||
const update = `
|
||||
INSERT DATA {
|
||||
<${subject}> a <${P.type}> ;
|
||||
<${P.payload}> "${payloadLiteral}" ;
|
||||
<${P.ts}> "${ts}"${fromTriple} .
|
||||
}`;
|
||||
await sparqlUpdate(sid, update, targetInbox, "deposit");
|
||||
// Domain-level diagnostic (on top of docs.ts's generic access-path WRITE log):
|
||||
// who deposited WHAT into which inbox — the decoded payload, not just the
|
||||
// triple-write. Gated by the same access-log flag; skip the JSON work when off.
|
||||
if (accessLogEnabled()) {
|
||||
logAccess(
|
||||
"WRITE",
|
||||
targetInbox,
|
||||
"inbox deposit",
|
||||
" from=" + (from ?? "anonymous") + " payload=" + summarizePayload(opts.payload ?? null),
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// --- read --------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Read every deposit currently in `targetInbox`, sorted by `ts` ascending. In
|
||||
* real NextGraph the recipient's own verifier applies queued messages inline as
|
||||
* it processes the inbox; here this read stands in for that until the
|
||||
* sealed-inbox path is available. The consumer interprets each deposit's
|
||||
* `payload`.
|
||||
*/
|
||||
export async function read(targetInbox: Nuri): Promise<Deposit[]> {
|
||||
const sid = await sessionId();
|
||||
// NOTE: cold-start repo opening is done by the COLD DIRECT readers that need it
|
||||
// (e.g. `discovery.readIndex` → `ensureInboxRepoOpen`), NOT here — `inbox.watch`
|
||||
// already holds the repo open via its own `subscribeDoc`, so opening a second
|
||||
// bootstrap subscription from inside a watch's re-read would be redundant and can
|
||||
// race the watch's own initial-`State` delivery. Keeping `read` a pure anchored
|
||||
// read leaves both callers correct: the watch path stays event-driven, and the
|
||||
// cold direct-read path opens the repo explicitly before calling `read`.
|
||||
// NO explicit `GRAPH <…>` clause — read the anchored DEFAULT graph (see the
|
||||
// note in `post`). The anchor (`targetInbox`) scopes the query to that repo's
|
||||
// default graph, exactly where `post` writes.
|
||||
const query = `
|
||||
SELECT ?payload ?ts ?from WHERE {
|
||||
?d a <${P.type}> ;
|
||||
<${P.payload}> ?payload ;
|
||||
<${P.ts}> ?ts .
|
||||
OPTIONAL { ?d <${P.from}> ?from }
|
||||
}`;
|
||||
const result = await sparqlQuery(sid, query, undefined, targetInbox, "inboxRead");
|
||||
const deposits: Deposit[] = [];
|
||||
for (const row of readBindings(result)) {
|
||||
const rawPayload = row.payload?.value ?? "null";
|
||||
let payload: unknown;
|
||||
try {
|
||||
payload = JSON.parse(rawPayload);
|
||||
} catch {
|
||||
payload = rawPayload; // tolerate a non-JSON literal
|
||||
}
|
||||
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 });
|
||||
}
|
||||
deposits.sort((a, b) => a.ts - b.ts);
|
||||
// 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
|
||||
// side. Gated by the same access-log flag; skip the JSON work when off.
|
||||
if (accessLogEnabled()) {
|
||||
logAccess(
|
||||
"READ",
|
||||
targetInbox,
|
||||
"inbox materialize",
|
||||
" → " + deposits.length + " message(s)",
|
||||
);
|
||||
for (const d of deposits) {
|
||||
logAccess(
|
||||
"READ",
|
||||
targetInbox,
|
||||
"inbox message",
|
||||
" ts=" + d.ts + " from=" + (d.from ?? "anonymous") + " payload=" + summarizePayload(d.payload),
|
||||
);
|
||||
}
|
||||
}
|
||||
return deposits;
|
||||
}
|
||||
|
||||
/** Alias for {@link read} — the name that reads as "process the inbox now". */
|
||||
export const materialize = read;
|
||||
|
||||
/**
|
||||
* COLD, BARRIER-GATED read of `targetInbox` — the reliable "process the inbox at
|
||||
* (re)connection" read. Opens/subscribes the inbox repo and AWAITS its first
|
||||
* `State` (the deterministic sync barrier — after it, presence is guaranteed and
|
||||
* absence definitive, {@link ensureRepoOpen}) BEFORE the anchored {@link read}.
|
||||
*
|
||||
* Why this over a plain {@link read}: on a FRESH session over the persistent
|
||||
* wallet (a (re)connection / new page), the inbox repo is not yet in the verifier's
|
||||
* `self.repos`, so a plain anchored `read` resolves an unopened repo and silently
|
||||
* returns 0 deposits — even for a deposit a remote session already synced to the
|
||||
* broker. Gating on the sync barrier makes the read see the synced deposits. This
|
||||
* is the SAME cold-read heal `discovery.readIndex` applies to the index inbox.
|
||||
*
|
||||
* NOT for the `watch` path: {@link watch} already holds the repo open via its own
|
||||
* `subscribeDoc`, so opening a second bootstrap subscription from inside a watch
|
||||
* re-read would be redundant and could race the watch's own initial-`State`
|
||||
* delivery. Use this from a COLD reader (materialize-at-connection), like
|
||||
* `discovery.readIndex` does. Idempotent per session (no polling); a no-op open on
|
||||
* the unit fake-ng path (no `doc_subscribe`) so `bun test` is unaffected.
|
||||
*/
|
||||
export async function readSynced(targetInbox: Nuri): Promise<Deposit[]> {
|
||||
// Marks the cold, connection-triggered entry point in the trace — the BARRIER
|
||||
// line (open-repo.ts) and the "inbox materialize"/"inbox message" lines below
|
||||
// (from the read() this wraps) follow right after, so a live session shows
|
||||
// the whole owner-reconnect sequence together.
|
||||
logStage("READSYNCED " + shortNuri(targetInbox) + " (cold, barrier-gated)");
|
||||
await ensureRepoOpen(targetInbox);
|
||||
return read(targetInbox);
|
||||
}
|
||||
|
||||
/**
|
||||
* Subscription over an inbox — **event-driven, not polled**. Subscribes to the
|
||||
* inbox document via {@link subscribeDoc} (the platform's `doc_subscribe` push):
|
||||
* `onDeposits` fires once on the initial state push and again on every subsequent
|
||||
* change to the inbox document — a local deposit OR a broker-synced remote one.
|
||||
* Returns an unsubscribe function.
|
||||
*
|
||||
* On each push it re-reads the full deposit list ({@link read}) and invokes
|
||||
* `onDeposits` only when the deposit count changed (grew), keeping the same
|
||||
* "fires on change" contract the polling watcher had — same callback signature
|
||||
* and same behaviour, just event-driven instead of `setInterval`.
|
||||
*
|
||||
* The `intervalMs` option is accepted for signature compatibility but IGNORED:
|
||||
* there is no polling. (The inbox document is a single doc, so this is immune to
|
||||
* the ORM fan-out hang — see {@link subscribeDoc}.)
|
||||
*/
|
||||
export function watch(
|
||||
targetInbox: Nuri,
|
||||
onDeposits: (deposits: Deposit[]) => void,
|
||||
_opts?: { intervalMs?: number },
|
||||
): () => void {
|
||||
let stopped = false;
|
||||
let lastCount = -1;
|
||||
|
||||
// Re-read on every push; fire onDeposits only when the set changed (grew).
|
||||
const refresh = async (): Promise<void> => {
|
||||
if (stopped) return;
|
||||
try {
|
||||
const deposits = await read(targetInbox);
|
||||
const changed = deposits.length !== lastCount;
|
||||
// Owner-side processing decision: did this push actually grow the
|
||||
// deposit set (→ onDeposits fires, the polyfill's stand-in for
|
||||
// materialization) or was it a no-op push (→ skipped)? This is the
|
||||
// exact line to check for the "must reconnect an extra time" symptom:
|
||||
// a push whose read still sees the OLD count means the barrier/read
|
||||
// raced the write, not that watch itself failed to fire.
|
||||
if (accessLogEnabled()) {
|
||||
logAccess(
|
||||
"READ",
|
||||
targetInbox,
|
||||
"inbox watch",
|
||||
" → " + deposits.length + " message(s)" + (changed ? " (materializing)" : " (unchanged, skip)"),
|
||||
);
|
||||
}
|
||||
if (!stopped && changed) {
|
||||
lastCount = deposits.length;
|
||||
onDeposits(deposits);
|
||||
}
|
||||
} catch (error) {
|
||||
console.error(accessLogPrefix() + " watch read failed:", error);
|
||||
}
|
||||
};
|
||||
|
||||
// Subscribe to the inbox document: the initial State push fires the first read
|
||||
// (so onDeposits fires once immediately, as before), each later Patch a re-read.
|
||||
const unsubscribe = subscribeDoc(targetInbox, () => void refresh());
|
||||
return () => {
|
||||
stopped = true;
|
||||
unsubscribe();
|
||||
};
|
||||
}
|
||||
@@ -1,48 +0,0 @@
|
||||
/**
|
||||
* @ng-eventually/client — **SDK-identical** surface.
|
||||
*
|
||||
* This entry exposes ONLY what `@ng-org/web` / `@ng-org/orm` expose (current +
|
||||
* anticipated: `inbox`). Import `ng` / `useShape` from here instead of the SDK
|
||||
* during the polyfill period; at migration the build alias is removed and these
|
||||
* resolve to the real SDK with **no code change**.
|
||||
*
|
||||
* The one non-SDK piece — the polyfill bootstrap (`configure`, capability
|
||||
* helpers, current user) — lives at `@ng-eventually/client/polyfill`, and is the
|
||||
* only thing removed at migration.
|
||||
*/
|
||||
|
||||
export * from "./types";
|
||||
export { useShape } from "./use-shape";
|
||||
export { watchShape } from "./watch-shape";
|
||||
export type { ShapeQuery, ShapeObservable } from "./watch-shape";
|
||||
export { init, initNg } from "./lifecycle";
|
||||
export * as inbox from "./inbox";
|
||||
export * as discovery from "./discovery";
|
||||
export type { IndexEntry, SubmitOptions } from "./discovery";
|
||||
export * as docs from "./docs";
|
||||
export { subscribeDoc, subscribeDocs, docChangeType } from "./subscribe";
|
||||
export type { DocChange, DocChangeType, Unsubscribe } from "./subscribe";
|
||||
export * as readModel from "./read-model";
|
||||
export type { UnionSubject } from "./read-model";
|
||||
export * as storeRegistry from "./store-registry";
|
||||
export type { AccountRecord, RegistrySession } from "./store-registry";
|
||||
export * as accounts from "./accounts";
|
||||
export type { AccountStorage } from "./accounts";
|
||||
|
||||
// SPARQL injection-safety helpers — so the app can reuse the same escaping /
|
||||
// validation when it builds SPARQL by interpolation. `escapeLiteral` for string
|
||||
// literals, `escapeIri` to embed untrusted values in an IRI, `assertNuri` to
|
||||
// validate trusted-shaped NURIs before embedding them in an IRI.
|
||||
export { escapeLiteral, escapeIri, assertNuri } from "./sparql";
|
||||
|
||||
// SDK type re-exports — so the app imports these from @ng-eventually/client 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).
|
||||
export type { ShapeType, BaseType, Schema } from "@ng-org/shex-orm";
|
||||
export type { DeepSignalSet } from "@ng-org/alien-deepsignals";
|
||||
export type { NG } from "@ng-org/web";
|
||||
|
||||
import { makeNg } from "./ng-proxy";
|
||||
|
||||
/** SDK-identical `ng` (wrapped). Drop-in replacement for `@ng-org/web`'s `ng`. */
|
||||
export const ng: Record<string, any> = makeNg();
|
||||
@@ -1,22 +0,0 @@
|
||||
/**
|
||||
* Lifecycle re-exports — SDK-shaped forwarders so the app imports `init` /
|
||||
* `initNg` from `@ng-eventually/client` rather than from `@ng-org/*`. They
|
||||
* delegate to the REAL functions injected at `configure()`. Passthrough today;
|
||||
* a hook point later (e.g. opening the shared wallet on `init`).
|
||||
*/
|
||||
|
||||
import { getConfig } from "./polyfill";
|
||||
|
||||
/** Forwards to the real `@ng-org/web` `init`. */
|
||||
export function init(...args: any[]): any {
|
||||
const f = getConfig().init;
|
||||
if (!f) throw new Error("[ng-eventually] init() not injected — pass it to configure()");
|
||||
return f(...args);
|
||||
}
|
||||
|
||||
/** Forwards to the real `@ng-org/orm` `initNg` (ORM signals). */
|
||||
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);
|
||||
}
|
||||
@@ -1,59 +0,0 @@
|
||||
/**
|
||||
* The wrapped `ng`: a Proxy that forwards every method to the real SDK and
|
||||
* overrides only what the broker/verifier will do natively at migration. The
|
||||
* surface stays identical to `@ng-org/web`'s `ng`.
|
||||
*/
|
||||
|
||||
import { getConfig, getCaps, getCurrentUser } from "./polyfill";
|
||||
import type { Nuri } from "./types";
|
||||
|
||||
export function makeNg(): Record<string, any> {
|
||||
return new Proxy({} as Record<string, any>, {
|
||||
get(_target, prop: string) {
|
||||
const { ng } = getConfig();
|
||||
|
||||
// login / session_start → open the SHARED wallet invisibly.
|
||||
if (prop === "login" || prop === "session_start") {
|
||||
return (...args: any[]) => {
|
||||
// TODO(polyfill): supply shared-wallet credentials so no wallet UI
|
||||
// is shown. For now, passthrough.
|
||||
return ng[prop]!(...args);
|
||||
};
|
||||
}
|
||||
|
||||
// sparql_update → write guard (emulated write-cap check).
|
||||
// Mirrors the target broker/verifier: a write is refused unless the wallet
|
||||
// holds the document's WRITE cap. Emulated per-document via CapRegistry.
|
||||
// args = (session_id, query, anchor?) — `anchor` is the target doc NURI.
|
||||
if (prop === "sparql_update") {
|
||||
return (...args: any[]) => {
|
||||
const anchor = args[2] as Nuri | undefined;
|
||||
const caps = getCaps();
|
||||
// Passthrough (no regression) unless a WRITE policy exists AND this
|
||||
// specific document is governed by it. Ungoverned docs (mono-store
|
||||
// default, no cap declared) flow through exactly as before.
|
||||
if (
|
||||
typeof anchor === "string" &&
|
||||
caps.hasWritePolicy() &&
|
||||
caps.governsWrite(anchor) &&
|
||||
!caps.canWrite(anchor, getCurrentUser())
|
||||
) {
|
||||
return Promise.reject(
|
||||
new Error(
|
||||
`[ng-eventually] write denied: current user lacks the write cap for ${anchor}`,
|
||||
),
|
||||
);
|
||||
}
|
||||
return ng.sparql_update!(...args);
|
||||
};
|
||||
}
|
||||
|
||||
// TODO(anticipated API): inbox_post_link + capability operations — expose
|
||||
// here with their anticipated signatures, emulated for now.
|
||||
|
||||
// Everything else: passthrough to the real SDK, unchanged.
|
||||
const real = ng[prop];
|
||||
return typeof real === "function" ? real.bind(ng) : real;
|
||||
},
|
||||
});
|
||||
}
|
||||
@@ -1,238 +0,0 @@
|
||||
/**
|
||||
* open-repo — cold-start repo opening for the ANCHORED read path (polyfill-era).
|
||||
*
|
||||
* ── The cold-start defect this heals ──────────────────────────────────────
|
||||
* The anchored read path (`read-model.ts` `readDoc`, `store-registry.ts`
|
||||
* `readScopeIndex`) assumes the target repo is already in the verifier's
|
||||
* `self.repos` — true within the session that CREATED the doc (every `doc_create`
|
||||
* opens it), but FALSE on a FRESH session over the same persistent wallet
|
||||
* (reconnection / new page / re-login). On that fresh session nothing has opened
|
||||
* the user's scope-index or entity repos yet, so an anchored `sparql_query`
|
||||
* resolves a repo absent from `self.repos` and silently returns 0 rows (never a
|
||||
* `RepoNotFound`) — persisted documents read as empty.
|
||||
*
|
||||
* The circularity that made this self-inflicted: `doc_subscribe` WOULD open the
|
||||
* repo, but the reactive layer only subscribes AFTER the listing produced NURIs —
|
||||
* and the listing (`readScopeIndex`) is itself an anchored read of a not-yet-open
|
||||
* index repo → 0 rows → nothing to subscribe → nothing ever opens. Verified fix
|
||||
* (adversarial pass): on a fresh session, `doc_subscribe(<docNuri>)` THEN the
|
||||
* anchored re-read returns the data. So we OPEN the repo before the anchored read.
|
||||
*
|
||||
* ── How we open ───────────────────────────────────────────────────────────
|
||||
* We reuse the existing per-document primitive {@link subscribeDoc} (the typed
|
||||
* wrapper over the platform's `doc_subscribe`) — NOT a parallel channel. On
|
||||
* subscribe the platform pushes `TabInfo` FIRST (~1-3ms) and then the initial
|
||||
* `State` (~2-3ms); the FIRST `State` is the sync BARRIER — after it, presence is
|
||||
* guaranteed and absence definitive (pinned empirically by CONTRACT 3 in `e2e/`).
|
||||
* So we await that first `State` specifically (identified via the `type` argument
|
||||
* {@link DocChangeType} `subscribeDoc` now surfaces), NOT the first push of any
|
||||
* kind — resolving on `TabInfo` would return before the real barrier. The
|
||||
* subscription is kept ALIVE for the whole session (that is what keeps the repo
|
||||
* open) — it is a bootstrap open, distinct from any reactive subscription a caller
|
||||
* 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.
|
||||
*
|
||||
* ── 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".
|
||||
*
|
||||
* ── Migration ─────────────────────────────────────────────────────────────
|
||||
* At the real multi-store migration this becomes "open the user's store repo by
|
||||
* cap" (a native broker fetch) done once at bootstrap; the anchored read then
|
||||
* resolves a same-session repo directly. Polyfill-era, removed with the shim.
|
||||
*/
|
||||
|
||||
import { getConfig, getStoreRegistryDeps } from "./polyfill";
|
||||
import { subscribeDoc, type Unsubscribe } from "./subscribe";
|
||||
import { logStage, shortNuri } from "./access-log";
|
||||
import type { Nuri } from "./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".
|
||||
*/
|
||||
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
|
||||
* new verifier session (fresh `self.repos`) → the registry must be invalidated. */
|
||||
let boundSessionId: string | number | null = null;
|
||||
|
||||
/**
|
||||
* 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
|
||||
* pathological case (a doc that never pushes), so a read is never blocked forever —
|
||||
* it just proceeds (and yields 0 rows, exactly as before, for a genuinely-absent doc).
|
||||
*/
|
||||
let OPEN_TIMEOUT_MS = 8000;
|
||||
|
||||
/**
|
||||
* Override the bootstrap-open fallback timeout (ms). TEST-ONLY: the timed-out
|
||||
* branch (a doc that never pushes a `State`) is otherwise only reachable after the
|
||||
* 8s production wait, too slow for a unit test. Production never calls this — the
|
||||
* default stands. `resetOpenedRepos` restores the default.
|
||||
*/
|
||||
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. */
|
||||
export function resetOpenedRepos(): void {
|
||||
for (const unsub of held.values()) {
|
||||
try {
|
||||
unsub();
|
||||
} catch {
|
||||
/* ignore */
|
||||
}
|
||||
}
|
||||
opened.clear();
|
||||
inFlight.clear();
|
||||
held.clear();
|
||||
syncState.clear();
|
||||
boundSessionId = null;
|
||||
OPEN_TIMEOUT_MS = 8000;
|
||||
}
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*/
|
||||
export function getSyncState(nuri: Nuri): SyncState | "unknown" {
|
||||
return syncState.get(nuri) ?? "unknown";
|
||||
}
|
||||
|
||||
/**
|
||||
* Invalidate the registry if the active session id changed since it was populated.
|
||||
* A new session id means a new verifier with an EMPTY `self.repos`, so entries from
|
||||
* the previous session must NOT suppress re-opening under the new one. Tolerant: if
|
||||
* the session can't be resolved, keep the current registry (best effort).
|
||||
*/
|
||||
async function syncSession(): Promise<void> {
|
||||
let sid: string | number | null = null;
|
||||
try {
|
||||
sid = (await getStoreRegistryDeps().getSession()).sessionId;
|
||||
} catch {
|
||||
return; // no session deps wired (unit fake path) — nothing to invalidate against
|
||||
}
|
||||
if (boundSessionId !== null && boundSessionId !== sid) resetOpenedRepos();
|
||||
boundSessionId = sid;
|
||||
}
|
||||
|
||||
/**
|
||||
* Ensure `nuri`'s repo is OPEN in the current session before an anchored read,
|
||||
* so the cold-start (fresh session, same persistent wallet) resolves it instead
|
||||
* of returning 0 rows. Opens via {@link subscribeDoc} and awaits the first `State`
|
||||
* push — the sync barrier (bounded fallback marks the nuri `"timed-out"`, not
|
||||
* `"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.
|
||||
*/
|
||||
export async function ensureRepoOpen(nuri: Nuri): Promise<void> {
|
||||
if (!nuri) return;
|
||||
// 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;
|
||||
|
||||
// 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.
|
||||
const ng = getConfig().ng as { doc_subscribe?: unknown };
|
||||
if (typeof ng.doc_subscribe !== "function") {
|
||||
opened.add(nuri);
|
||||
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();
|
||||
|
||||
const p = (async () => {
|
||||
await new Promise<void>((resolve) => {
|
||||
let settled = false;
|
||||
// Resolve on the first `State` (the sync BARRIER), marking the nuri "synced".
|
||||
const onState = (): void => {
|
||||
if (settled) return;
|
||||
settled = true;
|
||||
syncState.set(nuri, "synced");
|
||||
logStage("BARRIER " + shortNuri(nuri) + " synced (" + (Date.now() - barrierStartedAt) + "ms)");
|
||||
resolve();
|
||||
};
|
||||
// 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.
|
||||
const onTimeout = (): void => {
|
||||
if (settled) return;
|
||||
settled = true;
|
||||
syncState.set(nuri, "timed-out");
|
||||
logStage("BARRIER " + shortNuri(nuri) + " timed-out (" + (Date.now() - barrierStartedAt) + "ms)");
|
||||
resolve();
|
||||
};
|
||||
// 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.
|
||||
const unsub = subscribeDoc(nuri, (_r, type) => {
|
||||
if (type === "State") onState();
|
||||
});
|
||||
held.set(nuri, unsub);
|
||||
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.
|
||||
*/
|
||||
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)));
|
||||
}
|
||||
@@ -1,171 +0,0 @@
|
||||
/**
|
||||
* The polyfill bootstrap — the ONLY non-SDK surface of the client.
|
||||
*
|
||||
* It injects the REAL SDK and the polyfill settings; afterwards the SDK-shaped
|
||||
* exports (`ng`, `useShape`, `inbox`) behave as drop-ins. This is exposed at the
|
||||
* subpath `@ng-eventually/client/polyfill` so the main entry
|
||||
* (`@ng-eventually/client`) stays a **pure, SDK-identical** surface. Everything
|
||||
* here is removed at migration.
|
||||
*/
|
||||
|
||||
import type { NgLike, UseShapeLike, PrincipalId } from "./types";
|
||||
import type { RegistrySession } from "./store-registry";
|
||||
import { CapRegistry } from "./caps";
|
||||
import { setAccessLog } from "./access-log";
|
||||
import { inspectOutbox } from "./outbox-log";
|
||||
|
||||
/**
|
||||
* Consumer-injected dependencies of the storeRegistry (polyfill-era). The
|
||||
* registry itself is generic (it knows only native scopes); the consumer wires
|
||||
* up how to reach the shared-wallet session and how to normalize an identity id
|
||||
* used as the shim key. Removed at migration along with the whole shim.
|
||||
*/
|
||||
export interface StoreRegistryDeps {
|
||||
/** Resolve the current shared-wallet session (id + private-store anchor). */
|
||||
getSession: () => Promise<RegistrySession>;
|
||||
/** Normalize an identity id for shim keying. Default: trim (identity-ish). */
|
||||
normalizeId?: (id: string) => string;
|
||||
/**
|
||||
* POINTER micro-guard budget. The account records now live in a subscribable
|
||||
* doc-shim (`did:ng:o:...`) reached through a well-known write-once POINTER triple
|
||||
* in the store-root graph. The doc-shim read is barrier-AUTHORITATIVE, so accounts
|
||||
* need NO retry (this replaces the deleted account-level `provisionRetry`). The
|
||||
* ONLY residual sync-lag window is the store-root pointer read itself — one
|
||||
* write-once triple. This bounded guard re-reads JUST that pointer a few times if a
|
||||
* fresh cold read misses it; it can never provision or fork an account (worst case:
|
||||
* a couple extra reads before an existing pointer is seen). Enable it where the REAL
|
||||
* broker is used (app + e2e). Left UNSET (the default) → `attempts: 1` = single
|
||||
* read, keeping the synchronous unit fakes fast and unchanged.
|
||||
*/
|
||||
pointerGuard?: { attempts?: number; baseMs?: number; maxStepMs?: number };
|
||||
}
|
||||
|
||||
export interface EventuallyConfig {
|
||||
/** The REAL `@ng-org/web` `ng` (injected to avoid a hard import / alias loop). */
|
||||
ng: NgLike;
|
||||
/** The REAL `@ng-org/orm` `useShape`. */
|
||||
useShape: UseShapeLike;
|
||||
/** Shared-wallet credentials — polyfill only (one wallet for everyone). */
|
||||
sharedWallet?: { name: string; secret: string };
|
||||
/** Initial current user; may also be set later via {@link setCurrentUser}. */
|
||||
currentUser?: PrincipalId;
|
||||
/**
|
||||
* Turn on the OFF-by-default document access log (see {@link ./access-log}):
|
||||
* every real read/write is printed, prefixed by the active identity, to
|
||||
* diagnose the shared-wallet isolation leak. Also enablable without a code
|
||||
* change via the env var `NG_EVENTUALLY_ACCESS_LOG=1`. Default: false.
|
||||
*/
|
||||
debugAccessLog?: boolean;
|
||||
/** REAL `@ng-org/web` `init` (lifecycle) — forwarded by the lib's `init()`. */
|
||||
init?: (...args: any[]) => any;
|
||||
/** REAL `@ng-org/orm` `initNg` (ORM signals) — forwarded by the lib's `initNg()`. */
|
||||
initNg?: (...args: any[]) => any;
|
||||
}
|
||||
|
||||
let cfg: EventuallyConfig | null = null;
|
||||
let currentUser: PrincipalId | null = null;
|
||||
/** Required fields of StoreRegistryDeps after defaults are applied. `pointerGuard`
|
||||
* defaults to `{ attempts: 1 }` (single read) when the consumer leaves it unset. */
|
||||
type ResolvedRegistryDeps = Required<
|
||||
Pick<StoreRegistryDeps, "getSession" | "normalizeId" | "pointerGuard">
|
||||
>;
|
||||
let registryDeps: ResolvedRegistryDeps | null = null;
|
||||
/** The emulated ReadCap/WriteCap registry. Empty until the app declares caps;
|
||||
* while it has no read policy the read filter passes through (no regression). */
|
||||
let caps = new CapRegistry();
|
||||
|
||||
export function configure(c: EventuallyConfig): void {
|
||||
cfg = c;
|
||||
currentUser = c.currentUser ?? null;
|
||||
setAccessLog(c.debugAccessLog ?? false);
|
||||
}
|
||||
|
||||
/** @internal — used by the SDK-shaped wrappers to reach the injected real SDK. */
|
||||
export function getConfig(): EventuallyConfig {
|
||||
if (!cfg) throw new Error("[ng-eventually] configure() must be called before use");
|
||||
return cfg;
|
||||
}
|
||||
|
||||
/** Reset the injected config back to un-configured (mainly for tests, so a
|
||||
* suite that calls configure() can restore the not-configured guard state). */
|
||||
export function resetConfig(): void {
|
||||
cfg = null;
|
||||
currentUser = null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Wire the storeRegistry's consumer-injected dependencies (session + identity-id
|
||||
* normalization). Must be called before any storeRegistry.* use. Separate from
|
||||
* {@link configure} because it's storeRegistry-specific and, like the shim,
|
||||
* disappears at migration.
|
||||
*/
|
||||
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
|
||||
// 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
|
||||
// propagates untouched, exactly as before) and only ONCE per
|
||||
// `configureStoreRegistry()` call (a fresh session config → a fresh check).
|
||||
let outboxInspected = false;
|
||||
const getSession = async (): Promise<RegistrySession> => {
|
||||
const session = await deps.getSession();
|
||||
if (!outboxInspected) {
|
||||
outboxInspected = true;
|
||||
inspectOutbox();
|
||||
}
|
||||
return session;
|
||||
};
|
||||
registryDeps = {
|
||||
getSession,
|
||||
normalizeId: deps.normalizeId ?? ((id: string) => id.trim()),
|
||||
// Default: single read (no re-read). Only the real-broker consumers (app + e2e)
|
||||
// opt into the bounded pointer micro-guard; unit fakes stay synchronous.
|
||||
pointerGuard: deps.pointerGuard ?? { attempts: 1 },
|
||||
};
|
||||
}
|
||||
|
||||
/** @internal — used by the storeRegistry to reach its injected dependencies. */
|
||||
export function getStoreRegistryDeps(): ResolvedRegistryDeps {
|
||||
if (!registryDeps) {
|
||||
throw new Error("[ng-eventually] configureStoreRegistry() must be called before use");
|
||||
}
|
||||
return registryDeps;
|
||||
}
|
||||
|
||||
/** Reset storeRegistry deps (mainly for tests). */
|
||||
export function resetStoreRegistry(): void {
|
||||
registryDeps = null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Set the current identity id — who the SDK is reading/writing as. In the target
|
||||
* this is the wallet user established at wallet-import time; here the consumer
|
||||
* relays that id through this call so the read filter and the inbox `from` know
|
||||
* who is acting. Passing `null` clears it (no identity yet, e.g. during startup).
|
||||
*/
|
||||
export function setCurrentUser(id: PrincipalId | null): void {
|
||||
currentUser = id;
|
||||
}
|
||||
|
||||
export function getCurrentUser(): PrincipalId | null {
|
||||
return currentUser;
|
||||
}
|
||||
|
||||
/** The emulated cap registry — the app opens a document's read policy and issues
|
||||
* directed read grants on it (as it will via real cap operations in the target).
|
||||
* The read filter consults it. */
|
||||
export function getCaps(): CapRegistry {
|
||||
return caps;
|
||||
}
|
||||
|
||||
/** Reset all emulated caps (mainly for tests / fresh sessions). */
|
||||
export function resetCaps(): void {
|
||||
caps = new CapRegistry();
|
||||
}
|
||||
|
||||
// Cap surface — polyfill-era (caps are emulated now; native at migration).
|
||||
// Re-exported here so the whole polyfill API lives under /polyfill.
|
||||
export { CapRegistry } from "./caps";
|
||||
@@ -1,82 +0,0 @@
|
||||
/**
|
||||
* Read filter — the polyfill of capability-based read access.
|
||||
*
|
||||
* In the target, the broker only delivers documents the user holds a **ReadCap**
|
||||
* for, so `useShape` already returns an authorized subset. Here (single shared
|
||||
* wallet, everything readable) we reproduce that with a read-filtered VIEW over
|
||||
* the reactive set: it keeps only items whose **document** (its `@graph` = the
|
||||
* repo it lives in) the current user may read, per the {@link CapRegistry}.
|
||||
*
|
||||
* Faithful to NextGraph: the access unit is the DOCUMENT, not the item. In a
|
||||
* mono-store layout (every item in one repo) the filter is therefore all-or-
|
||||
* nothing on that document — which is exactly the native behavior, and why
|
||||
* fine-grained isolation requires one document per entity. Removed at migration.
|
||||
*/
|
||||
|
||||
import type { CapRegistry } from "./caps";
|
||||
import type { PrincipalId } from "./types";
|
||||
|
||||
/** The document (repo NURI) an item lives in — its `@graph`. */
|
||||
function docOf(item: unknown): string | null {
|
||||
const g = (item as Record<string, unknown> | null)?.["@graph"];
|
||||
return typeof g === "string" ? g : null;
|
||||
}
|
||||
|
||||
/**
|
||||
* May `user` read this item? An item with no `@graph`, or in a document under no
|
||||
* cap policy, is KEPT (the filter only restricts documents that DECLARE a cap —
|
||||
* mirrors the prior behavior and keeps ungoverned data flowing).
|
||||
*/
|
||||
function readable(item: unknown, caps: CapRegistry, user: PrincipalId | null): boolean {
|
||||
const doc = docOf(item);
|
||||
if (doc === null) return true;
|
||||
if (!caps.governsRead(doc)) return true;
|
||||
return caps.canRead(doc, user);
|
||||
}
|
||||
|
||||
/** Pure: keep only the items the user may read. */
|
||||
export function filterReadable<T>(
|
||||
items: Iterable<T>,
|
||||
caps: CapRegistry,
|
||||
user: PrincipalId | null,
|
||||
): T[] {
|
||||
const out: T[] = [];
|
||||
for (const item of items) if (readable(item, caps, user)) out.push(item);
|
||||
return out;
|
||||
}
|
||||
|
||||
/**
|
||||
* A read-filtered VIEW over a reactive set (a `DeepSignalSet`, or any Set-like).
|
||||
* Iteration / `size` / `forEach` yield only readable items; everything else
|
||||
* (`add`, `delete`, `has`, `getById`, …) forwards to the target, so writes and
|
||||
* the underlying reactivity are preserved. The current user is read lazily (via
|
||||
* `getUser`) so the view reflects the user in effect at read time.
|
||||
*/
|
||||
export function makeReadFilteredView<S extends object>(
|
||||
set: S,
|
||||
caps: CapRegistry,
|
||||
getUser: () => PrincipalId | null,
|
||||
): S {
|
||||
const keep = (item: unknown): boolean => readable(item, caps, getUser());
|
||||
return new Proxy(set, {
|
||||
get(target, prop, receiver) {
|
||||
if (prop === Symbol.iterator) {
|
||||
return function* () {
|
||||
for (const item of target as Iterable<unknown>) if (keep(item)) yield item;
|
||||
};
|
||||
}
|
||||
if (prop === "size") {
|
||||
let n = 0;
|
||||
for (const item of target as Iterable<unknown>) if (keep(item)) n++;
|
||||
return n;
|
||||
}
|
||||
if (prop === "forEach") {
|
||||
return (cb: (v: unknown, v2: unknown, s: unknown) => void) => {
|
||||
for (const item of target as Iterable<unknown>) if (keep(item)) cb(item, item, receiver);
|
||||
};
|
||||
}
|
||||
const v = Reflect.get(target, prop, target);
|
||||
return typeof v === "function" ? v.bind(target) : v;
|
||||
},
|
||||
}) as S;
|
||||
}
|
||||
@@ -1,182 +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, getCurrentUser, getStoreRegistryDeps } from "./polyfill";
|
||||
import { ensureReposOpen } from "./open-repo";
|
||||
import { assertNuri } from "./sparql";
|
||||
import type { Nuri } from "./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). */
|
||||
export interface UnionSubject {
|
||||
/** The subject IRI (`?s`) — in the polyfill, the doc's own NURI. */
|
||||
subject: string;
|
||||
/** The graph (doc NURI) the subject was read from. */
|
||||
graph: string;
|
||||
/** 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> {
|
||||
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,
|
||||
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.
|
||||
*
|
||||
* 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`.
|
||||
*/
|
||||
export async function readUnion(docs: Nuri[]): Promise<UnionSubject[]> {
|
||||
const sid = await sessionId();
|
||||
const unique = [...new Set(docs.filter(Boolean))];
|
||||
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.
|
||||
await ensureReposOpen(unique);
|
||||
|
||||
// One anchored query per doc, in parallel, tolerant (a bad doc yields []).
|
||||
const perDoc = await Promise.all(
|
||||
unique.map(async (d) => ({ doc: assertNuri(d), rows: await readDoc(sid, d) })),
|
||||
);
|
||||
|
||||
// Cap gate (defence-in-depth). A doc whose read policy the current user may not
|
||||
// satisfy is dropped. Isolation holds both by construction (the app only resolves
|
||||
// docs it is entitled to) and by filter here. Generic: the lib owns the cap
|
||||
// registry; a doc under no policy (`!governsRead`) flows through unchanged. In this
|
||||
// polyfill each subject IRI is its own document NURI, so the cap key is the doc NURI.
|
||||
const caps = getCaps();
|
||||
const user = getCurrentUser();
|
||||
|
||||
const bySubject = new Map<string, UnionSubject>();
|
||||
for (const { doc, rows } of perDoc) {
|
||||
if (caps.governsRead(doc) && !caps.canRead(doc, user)) continue;
|
||||
// Anchored to `doc`, so every row belongs to `doc`; the subject is the doc NURI
|
||||
// (writeEntity invariant). Pin subject/graph to the doc NURI (the anchor), which
|
||||
// is stable regardless of the repo_graph_name overlay suffix the store carries.
|
||||
for (const row of rows) {
|
||||
const p = row.p?.value;
|
||||
const o = row.o?.value;
|
||||
if (!p || o === undefined) continue;
|
||||
let entry = bySubject.get(doc);
|
||||
if (!entry) {
|
||||
entry = { subject: doc, graph: doc, props: {} };
|
||||
bySubject.set(doc, entry);
|
||||
}
|
||||
(entry.props[p] ??= []).push(o);
|
||||
}
|
||||
}
|
||||
return [...bySubject.values()];
|
||||
}
|
||||
@@ -1,839 +0,0 @@
|
||||
/**
|
||||
* storeRegistry — resolves (account, scope) → document NURI.
|
||||
*
|
||||
* Stopgap / polyfill-era. Emulates the target infrastructure — where each
|
||||
* user owns their own public/protected/private stores — on top of one shared
|
||||
* wallet. It creates one document per (account × scope) inside that shared
|
||||
* wallet (via the `docs.docCreate` primitive), so the `scope`
|
||||
* (`public|protected|private`) is a logical attribute tracked here, not a
|
||||
* physical NextGraph store. Isolation is enforced by the app layer + the
|
||||
* emulated cap registry, not by crypto.
|
||||
*
|
||||
* The mapping (account → its 3 document NURIs) is the **sharedWalletShim**. It
|
||||
* is persisted as RDF, but NOT in the store-root graph anymore — see the
|
||||
* indirection below. That makes login cross-device: another device opening the
|
||||
* same wallet reads the same shim and finds the same accounts.
|
||||
*
|
||||
* ── The indirection: pointer (store-root) → doc-shim (subscribable) ─────────
|
||||
* On the real NextGraph platform "findable-without-lookup" and "subscribable"
|
||||
* are DISJOINT (verified at the source, see docs/nextgraph-current-state.md
|
||||
* § *Findable vs subscribable*):
|
||||
* - the ONLY NURI a fresh session can name WITHOUT a lookup is the store-root
|
||||
* `did:ng:${privateStoreId}` — but a store-root has NO first-`State` sync
|
||||
* BARRIER, so a cold "0 rows" on it is AMBIGUOUS (could be sync-lag, could
|
||||
* be truly empty);
|
||||
* - the ONLY thing that DOES have a first-`State` barrier is a `did:ng:o:<RepoID>`
|
||||
* doc from `doc_create` — but its RepoID is RANDOM, so a fresh session
|
||||
* cannot GUESS it; it must be looked up.
|
||||
* So a purely-barrier shim resolution is impossible: you cannot have a doc that
|
||||
* is both guessable and authoritative on a cold read. The indirection bridges
|
||||
* this: a well-known, write-ONCE **pointer** triple in the store-root names a
|
||||
* **doc-shim** (`did:ng:o:...`) that holds all account records and IS
|
||||
* subscribable. Resolution reads the pointer (a single oldest write-once triple,
|
||||
* near-always synced), then opens the doc-shim through its `ensureRepoOpen`
|
||||
* BARRIER and reads the account AUTHORITATIVELY (0 = genuinely absent).
|
||||
*
|
||||
* A pointer FORK (two devices writing the pointer before either synced) is
|
||||
* reconciled to a canonical doc-shim (lexicographically-smallest NURI) so every
|
||||
* device converges on the SAME doc-shim. This is why the OLD account-level retry
|
||||
* (`resolveAccountReliably` / `provisionRetry`) is GONE: the account read is now
|
||||
* barrier-authoritative, so it never needs to be retried to distinguish sync-lag
|
||||
* from absence. A micro-guard remains ONLY on the pointer read (one write-once
|
||||
* triple) — see resolvePointer.
|
||||
*
|
||||
* ── Generic by construction ──────────────────────────────────────────────
|
||||
* This module knows only the three native scopes; it knows no application
|
||||
* entity kind. The consumer maps its entities to a scope and calls
|
||||
* `createEntityDoc(scope)` / `listEntityDocs(scope)` with the resulting native
|
||||
* scope. No application domain here.
|
||||
*
|
||||
* ── What disappears at migration ─────────────────────────────────────────
|
||||
* At the real multi-store migration the shim vanishes entirely: `(account,
|
||||
* scope)` maps to the user's REAL store NURI instead of a document in the
|
||||
* shared wallet, `docCreate` targets the real per-user store, and the
|
||||
* per-scope index document (the store-container emulation) is replaced by the
|
||||
* store itself. The consumer-facing surface (`createEntityDoc`,
|
||||
* `listEntityDocs`, resolvers) is designed to survive that swap unchanged.
|
||||
*
|
||||
* All NextGraph I/O routes through the T01.a `docs` primitive (real injected
|
||||
* `ng`), so this module imports **no** `@ng-org` package.
|
||||
*/
|
||||
|
||||
import { docCreate, sparqlUpdate, sparqlQuery } from "./docs";
|
||||
import { getStoreRegistryDeps } from "./polyfill";
|
||||
import { ensureRepoOpen } from "./open-repo";
|
||||
import { escapeLiteral, escapeIri, assertNuri } from "./sparql";
|
||||
import { accessLogPrefix, logStage, shortNuri } from "./access-log";
|
||||
import type { Nuri, Scope } from "./types";
|
||||
|
||||
// --- sharedWalletShim model ----------------------------------------------
|
||||
|
||||
/** One account's three scope-document NURIs, as recorded in the shim. */
|
||||
export interface AccountRecord {
|
||||
id: string;
|
||||
docPublic: Nuri;
|
||||
docProtected: Nuri;
|
||||
docPrivate: Nuri;
|
||||
}
|
||||
|
||||
const SHIM = "urn:ng-eventually:shim";
|
||||
const P = {
|
||||
type: `${SHIM}:Account`,
|
||||
id: `${SHIM}:id`,
|
||||
docPublic: `${SHIM}:docPublic`,
|
||||
docProtected: `${SHIM}:docProtected`,
|
||||
docPrivate: `${SHIM}:docPrivate`,
|
||||
contains: `${SHIM}:contains`, // scope-index → entity document NURI
|
||||
} as const;
|
||||
// Fixed subject of the per-(account×scope) index document. The index doc plays
|
||||
// the role of the future store-container: it lists the NURIs of the entity
|
||||
// documents (one per entity) that live "in" that scope.
|
||||
const INDEX_SUBJECT = `${SHIM}:index`;
|
||||
|
||||
// --- pointer (store-root → doc-shim indirection) --------------------------
|
||||
//
|
||||
// The pointer is a SINGLE well-known triple written ONCE into the store-root
|
||||
// graph on the very first login, then IMMUTABLE. Its object is the NURI of the
|
||||
// doc-shim (a `did:ng:o:...` repo) where all AccountRecords actually live. The
|
||||
// store-root is NOT subscribable (no first-`State` barrier), but the pointer is
|
||||
// the OLDEST triple in that graph and is write-once, so it is near-always synced
|
||||
// on a cold read — and even a transient miss is bounded by a small guard
|
||||
// (resolvePointer), NOT by an account-level retry.
|
||||
const POINTER_SUBJECT = `${SHIM}:root`;
|
||||
const POINTER_PRED = `${SHIM}:shimDoc`;
|
||||
|
||||
function accountSubject(id: string): string {
|
||||
// The id is UNTRUSTED and lands in an IRI position. Percent-encode it
|
||||
// (escapeIri) so no `>` / `"` / whitespace / control char can break out of
|
||||
// the `<...>` and inject triples into the shim graph (the account→doc trust
|
||||
// root). accountKey() runs first so the subject stays stable per shim key.
|
||||
return `${SHIM}:account:${escapeIri(accountKey(id))}`;
|
||||
}
|
||||
|
||||
// --- reserved accounts -----------------------------------------------------
|
||||
//
|
||||
// Some accounts are internal to the lib (e.g. the discovery index owner) and
|
||||
// must NOT collide with any user-chosen id. A reserved account is created
|
||||
// via {@link reservedAccount}, which marks the name with a sentinel PREFIX that
|
||||
// `normalizeId` (consumer-injected) can never produce: it strips a leading
|
||||
// `@`, trims, and lowercases, so a NUL prefix is unreachable. Reserved
|
||||
// keys therefore live in a disjoint namespace from every normalized id —
|
||||
// a real user named "index"/"@index" can never resolve to the reserved
|
||||
// `reservedAccount("index")` account.
|
||||
const RESERVED_PREFIX = "\u0000reserved:";
|
||||
|
||||
/**
|
||||
* Wrap an internal account name so it occupies a key that no user input can
|
||||
* produce (see {@link RESERVED_PREFIX}). Pass the result to {@link ensureAccount}
|
||||
* (and the other registry calls) instead of a bare id.
|
||||
*/
|
||||
export function reservedAccount(name: string): string {
|
||||
return `${RESERVED_PREFIX}${name}`;
|
||||
}
|
||||
|
||||
/** Whether a name is a reserved-account sentinel (from {@link reservedAccount}). */
|
||||
function isReserved(id: string): boolean {
|
||||
return id.startsWith(RESERVED_PREFIX);
|
||||
}
|
||||
|
||||
/**
|
||||
* The shim/cache key for an account. Reserved accounts bypass `normalizeId`
|
||||
* entirely and key on their sentinel-prefixed name, so they cannot collide with
|
||||
* a normalized id; everyone else normalizes as usual.
|
||||
*/
|
||||
function accountKey(id: string): string {
|
||||
return isReserved(id) ? id : normalize(id);
|
||||
}
|
||||
|
||||
// --- session / normalization access (injected by the consumer) ------------
|
||||
|
||||
/** Minimal session shape the registry needs — provided by the consumer. */
|
||||
export interface RegistrySession {
|
||||
sessionId: string;
|
||||
/** The shared wallet's private store id — the pointer anchor. */
|
||||
privateStoreId: string;
|
||||
/** The shared wallet's protected store id (native store). Optional: only the
|
||||
* scope resolvers need it; the shim only needs the private anchor. */
|
||||
protectedStoreId?: string;
|
||||
/** The shared wallet's public store id (native store). Optional. */
|
||||
publicStoreId?: string;
|
||||
}
|
||||
|
||||
function normalize(id: string): string {
|
||||
return getStoreRegistryDeps().normalizeId(id);
|
||||
}
|
||||
|
||||
async function session(): Promise<RegistrySession> {
|
||||
return getStoreRegistryDeps().getSession();
|
||||
}
|
||||
|
||||
/** The pointer lives in the shared wallet's private STORE-ROOT graph (the only
|
||||
* always-known-without-lookup anchor). NOT subscribable — hence the pointer is
|
||||
* a write-once triple, and the actual account records live in the doc-shim it
|
||||
* names (see rootNuri vs the doc-shim). */
|
||||
async function rootNuri(): Promise<Nuri> {
|
||||
const s = await session();
|
||||
return `did:ng:${s.privateStoreId}`;
|
||||
}
|
||||
|
||||
// --- cache ----------------------------------------------------------------
|
||||
|
||||
// In-memory cache of the FULL shim (all accounts), keyed by account key. Set
|
||||
// only once loadShim() has read every account — used by the all-accounts paths.
|
||||
let cache: Map<string, AccountRecord> | null = null;
|
||||
|
||||
// Per-account cache, keyed by account key. Populated by the TARGETED resolver
|
||||
// (resolveAccount) and by loadShim(). Independent of `cache` so a single
|
||||
// targeted resolve never forces a full shim scan. Both are cleared together.
|
||||
const accountCache = new Map<string, AccountRecord>();
|
||||
|
||||
// The resolved doc-shim NURI for the current session (cached: the pointer read +
|
||||
// barrier open happen once, then every account read reuses this doc). Cleared on
|
||||
// resetRegistryCache / wallet switch.
|
||||
let shimDocNuri: Nuri | null = null;
|
||||
// De-dupe concurrent pointer-resolutions so a fresh page firing many parallel
|
||||
// ensureAccount/resolveAccount calls opens the doc-shim exactly once.
|
||||
let shimDocInFlight: Promise<Nuri> | null = null;
|
||||
|
||||
/** Reset cache (e.g. after switching the shared wallet). Mostly for tests. */
|
||||
export function resetRegistryCache(): void {
|
||||
cache = null;
|
||||
accountCache.clear();
|
||||
shimDocNuri = null;
|
||||
shimDocInFlight = null;
|
||||
}
|
||||
|
||||
// --- SPARQL result helpers ------------------------------------------------
|
||||
|
||||
/** Tolerant extraction of SPARQL SELECT bindings across possible shapes. */
|
||||
function readBindings(result: unknown): Array<Record<string, { value: string }>> {
|
||||
if (!result) return [];
|
||||
const anyRes = result as {
|
||||
results?: { bindings?: Array<Record<string, { value: string }>> };
|
||||
};
|
||||
if (Array.isArray(result)) return result as Array<Record<string, { value: string }>>;
|
||||
if (anyRes.results?.bindings) return anyRes.results.bindings;
|
||||
return [];
|
||||
}
|
||||
|
||||
function bindingValue(row: Record<string, { value: string }>, key: string): string {
|
||||
return row[key]?.value ?? "";
|
||||
}
|
||||
|
||||
/**
|
||||
* DETERMINISTIC resolution of an account's scope docs from a set of SPARQL
|
||||
* bindings (all bindings for ONE account subject).
|
||||
*
|
||||
* ── Why this is load-bearing (residual fork residue) ───────────────────────
|
||||
* A corrupted shim can carry the SAME account subject with MULTIPLE values for a
|
||||
* scope predicate (e.g. 5 `shim:docPublic`) — the residue of past account FORKS
|
||||
* (each stray provision appended another doc NURI). A query then returns several
|
||||
* bindings (the cross-product of the duplicate values). Picking `rows[0]` is
|
||||
* NON-DETERMINISTIC (binding order is not stable across sessions), so the session
|
||||
* that WROTE an entity into one docPublic and a later fresh page that RESOLVED a
|
||||
* DIFFERENT docPublic would disagree → the anchored `readScopeIndex` returns 0 →
|
||||
* the home reads empty. When both happen to pick the same doc, it "works".
|
||||
*
|
||||
* The fix: for each scope field, collect EVERY distinct value across the bindings
|
||||
* and choose the SAME one every time — the lexicographically-smallest NURI. NURIs
|
||||
* are content-addressed and stable, so lexicographic order is a total, stable,
|
||||
* session-independent order: writer and reader converge on the SAME canonical doc
|
||||
* even on a wallet already corrupted by duplicates. (No creation timestamp is
|
||||
* recorded in the shim, so lexicographic-min is the available deterministic key.)
|
||||
*
|
||||
* With the barrier-authoritative doc-shim read, account FORKS no longer occur (a
|
||||
* fresh page reads the doc-shim through its first-`State` barrier, so a cold 0 is
|
||||
* definitive and never triggers a fork-provision). `canonicalDoc` is RETAINED to
|
||||
* stay robust against the residue of PAST forks already persisted in a wallet, and
|
||||
* to reconcile a benign pointer fork the same content-addressed way.
|
||||
*/
|
||||
function canonicalDoc(rows: Array<Record<string, { value: string }>>, key: string): Nuri {
|
||||
let chosen = "";
|
||||
const distinct = new Set<string>();
|
||||
for (const row of rows) {
|
||||
const v = bindingValue(row, key);
|
||||
if (!v) continue;
|
||||
distinct.add(v);
|
||||
if (chosen === "" || v < chosen) chosen = v;
|
||||
}
|
||||
// Stage trace: which doc got picked, and out of how many DISTINCT candidate
|
||||
// values — >1 flags residual fork residue (see the module doc above) even
|
||||
// when resolution still converges correctly on the canonical (smallest) one.
|
||||
logStage(
|
||||
"canonicalDoc(" + key + ") → " + (chosen ? shortNuri(chosen) : "none") +
|
||||
" (" + distinct.size + (distinct.size === 1 ? " candidate)" : " candidates)"),
|
||||
);
|
||||
return chosen;
|
||||
}
|
||||
|
||||
/** Build an AccountRecord by picking the canonical (lexicographically-smallest)
|
||||
* doc NURI per scope across all bindings for one account. See {@link canonicalDoc}. */
|
||||
function recordFromRows(
|
||||
rows: Array<Record<string, { value: string }>>,
|
||||
fallbackId: string,
|
||||
): AccountRecord {
|
||||
let id = "";
|
||||
for (const row of rows) {
|
||||
const v = bindingValue(row, "id");
|
||||
if (v) { id = v; break; }
|
||||
}
|
||||
return {
|
||||
id: id || fallbackId,
|
||||
docPublic: canonicalDoc(rows, "docPublic"),
|
||||
docProtected: canonicalDoc(rows, "docProtected"),
|
||||
docPrivate: canonicalDoc(rows, "docPrivate"),
|
||||
};
|
||||
}
|
||||
|
||||
// --- pointer resolution + doc-shim bootstrap ------------------------------
|
||||
|
||||
const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
|
||||
|
||||
/**
|
||||
* Read the pointer(s) from the store-root graph → the canonical doc-shim NURI, or
|
||||
* `""` if no pointer exists yet.
|
||||
*
|
||||
* The store-root is NOT subscribable, so this read has no first-`State` barrier:
|
||||
* a cold 0 is ambiguous. But the pointer is ONE write-once triple (the OLDEST in
|
||||
* that graph), so it is near-always synced. The ONLY residual guard is a small
|
||||
* bounded re-read here (NOT an account retry): a handful of quick re-reads of that
|
||||
* single triple. It is bounded, benign, and — crucially — it can never re-provision
|
||||
* an account or fork data; the worst it can do is take a couple extra reads to see a
|
||||
* pointer that is still landing. The account records themselves are read
|
||||
* authoritatively through the doc-shim barrier, never through this guard.
|
||||
*
|
||||
* If MULTIPLE pointers exist (a pointer fork: two devices each wrote a pointer to
|
||||
* their own freshly-created doc-shim before either synced), reconcile to the
|
||||
* canonical (lexicographically-smallest) doc-shim NURI — content-addressed and
|
||||
* stable, so every device converges on the SAME doc-shim.
|
||||
*/
|
||||
async function resolvePointer(): Promise<Nuri> {
|
||||
const s = await session();
|
||||
const root = await rootNuri();
|
||||
// COLD-START heal: open the store-root repo before the anchored read, so a fresh
|
||||
// wallet whose store-root isn't yet in `self.repos` resolves instead of throwing
|
||||
// `RepoNotFound`. Idempotent; a no-op with the unit fake ng. The store-root has no
|
||||
// barrier, so this open cannot make the read authoritative — the guard below does.
|
||||
await ensureRepoOpen(root);
|
||||
const query = `
|
||||
SELECT ?shimDoc WHERE {
|
||||
GRAPH <${assertNuri(root)}> {
|
||||
<${POINTER_SUBJECT}> <${POINTER_PRED}> ?shimDoc .
|
||||
}
|
||||
}`;
|
||||
|
||||
// Micro-guard (POINTER only): a small bounded re-read to bridge the store-root
|
||||
// sync-lag window on the ONE write-once pointer triple. Bounded, and it can only
|
||||
// ever DELAY seeing an existing pointer — never provision, never fork. Uses the
|
||||
// injected pointerGuard budget (defaults to a single read when unset, so unit
|
||||
// fakes stay synchronous). NB this is NOT the deleted account-level provisionRetry.
|
||||
const budget = getStoreRegistryDeps().pointerGuard;
|
||||
const attempts = Math.max(1, budget.attempts ?? 1);
|
||||
const baseMs = budget.baseMs ?? 150;
|
||||
const maxStepMs = budget.maxStepMs ?? 2000;
|
||||
|
||||
let step = baseMs;
|
||||
for (let i = 0; i < attempts; i++) {
|
||||
try {
|
||||
const result = await sparqlQuery(s.sessionId, query, undefined, root, "resolvePointer");
|
||||
const doc = canonicalDoc(readBindings(result), "shimDoc");
|
||||
if (doc) {
|
||||
logStage("resolvePointer → 1 target: " + shortNuri(doc));
|
||||
return doc;
|
||||
}
|
||||
} catch (error) {
|
||||
console.error(accessLogPrefix() + " resolvePointer failed:", error);
|
||||
}
|
||||
if (i < attempts - 1) {
|
||||
await sleep(step);
|
||||
step = Math.min(step * 2, maxStepMs);
|
||||
}
|
||||
}
|
||||
logStage("resolvePointer → 0 targets");
|
||||
return "";
|
||||
}
|
||||
|
||||
/** Write the pointer (store-root → doc-shim), once, at first login. Idempotent in
|
||||
* practice (only called when no pointer was found); a concurrent double-write is
|
||||
* reconciled by canonicalDoc on read. */
|
||||
async function writePointer(doc: Nuri): Promise<void> {
|
||||
const s = await session();
|
||||
const root = await rootNuri();
|
||||
await ensureRepoOpen(root);
|
||||
const update = `
|
||||
INSERT DATA {
|
||||
GRAPH <${assertNuri(root)}> {
|
||||
<${POINTER_SUBJECT}> <${POINTER_PRED}> <${assertNuri(doc)}> .
|
||||
}
|
||||
}`;
|
||||
try {
|
||||
await sparqlUpdate(s.sessionId, update, root, "writePointer");
|
||||
} catch (error) {
|
||||
console.error(accessLogPrefix() + " writePointer failed:", error);
|
||||
}
|
||||
}
|
||||
|
||||
/** Create one graph document in the shared wallet's private store (→ a NURI). */
|
||||
async function createDoc(): Promise<Nuri> {
|
||||
const s = await session();
|
||||
// crdt="Graph" (RDF/SPARQL/ORM), class="data:graph", destination="store",
|
||||
// store_repo=undefined → shared wallet's private store.
|
||||
return docCreate(s.sessionId, "Graph", "data:graph", "store", undefined);
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve (or on first login, create) the doc-shim NURI for this session — the
|
||||
* `did:ng:o:...` repo that holds every AccountRecord and IS subscribable.
|
||||
*
|
||||
* Steps (cached; runs at most once per session, concurrent callers share one):
|
||||
* 1. Read the pointer from the store-root (resolvePointer). If present → that is
|
||||
* the doc-shim; open it through its first-`State` BARRIER so subsequent account
|
||||
* reads are AUTHORITATIVE.
|
||||
* 2. No pointer → FIRST login:
|
||||
* a. create a fresh doc-shim (`doc_create`), which bootstraps the repo into the
|
||||
* session (`self.repos`) — so it is already open/synced in-session;
|
||||
* b. publish the pointer (store-root → the new doc-shim), once;
|
||||
* c. open it (barrier — trivially satisfied for a just-created in-session repo).
|
||||
* The BARRIER matters on RECONNECT (step 1, reading an EXISTING remote doc-shim);
|
||||
* on first-login creation it is a no-op, so the pointer is published first.
|
||||
*/
|
||||
async function resolveShimDoc(): Promise<Nuri> {
|
||||
if (shimDocNuri) return shimDocNuri;
|
||||
if (shimDocInFlight) return shimDocInFlight;
|
||||
|
||||
const p = (async (): Promise<Nuri> => {
|
||||
const existing = await resolvePointer();
|
||||
if (existing) {
|
||||
// Open the doc-shim through its first-`State` barrier BEFORE any account read,
|
||||
// so a cold 0 on the doc-shim is authoritative (genuinely absent), not sync-lag.
|
||||
await ensureRepoOpen(existing);
|
||||
shimDocNuri = existing;
|
||||
logStage("resolveShimDoc → " + shortNuri(existing));
|
||||
return existing;
|
||||
}
|
||||
|
||||
// FIRST login (no pointer): create the doc-shim (bootstrapped in-session), publish
|
||||
// the pointer, then open (no-op barrier for a just-created repo).
|
||||
const doc = await createDoc();
|
||||
await writePointer(doc);
|
||||
await ensureRepoOpen(doc);
|
||||
shimDocNuri = doc;
|
||||
logStage("resolveShimDoc → " + shortNuri(doc));
|
||||
return doc;
|
||||
})();
|
||||
|
||||
shimDocInFlight = p;
|
||||
try {
|
||||
return await p;
|
||||
} finally {
|
||||
shimDocInFlight = null;
|
||||
}
|
||||
}
|
||||
|
||||
// --- shim load / account bootstrap ----------------------------------------
|
||||
|
||||
/** Load all accounts from the shim (the doc-shim) into the cache. */
|
||||
export async function loadShim(): Promise<Map<string, AccountRecord>> {
|
||||
if (cache) return cache;
|
||||
const s = await session();
|
||||
const doc = await resolveShimDoc();
|
||||
const query = `
|
||||
SELECT ?id ?docPublic ?docProtected ?docPrivate WHERE {
|
||||
?acc a <${P.type}> ;
|
||||
<${P.id}> ?id ;
|
||||
<${P.docPublic}> ?docPublic ;
|
||||
<${P.docProtected}> ?docProtected ;
|
||||
<${P.docPrivate}> ?docPrivate .
|
||||
}`;
|
||||
const map = new Map<string, AccountRecord>();
|
||||
// The doc-shim is opened (first-`State` barrier) by resolveShimDoc, so this read is
|
||||
// authoritative.
|
||||
await ensureRepoOpen(doc);
|
||||
try {
|
||||
const result = await sparqlQuery(s.sessionId, query, undefined, doc, "loadShim");
|
||||
// Group ALL bindings by account key first, then pick the CANONICAL doc per
|
||||
// scope (see recordFromRows / canonicalDoc). A single account subject may carry
|
||||
// duplicate scope-doc values (fork residue) → several bindings; grouping +
|
||||
// canonical selection makes loadShim resolve the SAME doc the targeted
|
||||
// resolveAccount does, so full-scan and hot-path readers never disagree.
|
||||
const byKey = new Map<string, Array<Record<string, { value: string }>>>();
|
||||
for (const row of readBindings(result)) {
|
||||
const id = bindingValue(row, "id");
|
||||
if (!id) continue;
|
||||
const key = accountKey(id);
|
||||
const bucket = byKey.get(key) ?? [];
|
||||
bucket.push(row);
|
||||
byKey.set(key, bucket);
|
||||
}
|
||||
for (const [key, rows] of byKey) {
|
||||
const record = recordFromRows(rows, rows[0] ? bindingValue(rows[0], "id") : key);
|
||||
map.set(key, record);
|
||||
// Feed the per-account cache too, so a subsequent targeted resolve is free.
|
||||
accountCache.set(key, record);
|
||||
}
|
||||
} catch (error) {
|
||||
console.error(accessLogPrefix() + " loadShim failed:", error);
|
||||
}
|
||||
cache = map;
|
||||
return map;
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve ONE account by its shim key with a BOUNDED query — O(1), independent
|
||||
* of the number of accounts in the shim. This is the HOT-PATH lookup: it hits
|
||||
* the account record at its known subject (`accountSubject(id)`) directly in the
|
||||
* doc-shim, instead of scanning EVERY account like {@link loadShim}. Returns the
|
||||
* account's record or `null` if it does not exist yet.
|
||||
*
|
||||
* ── Barrier-AUTHORITATIVE (the reconnection fix) ────────────────────────────
|
||||
* The read targets the DOC-SHIM (`did:ng:o:...`), which resolveShimDoc opened
|
||||
* through its first-`State` barrier. So a cold 0 rows here is DEFINITIVE ("account
|
||||
* genuinely absent"), not ambiguous sync-lag — no account-level retry is needed or
|
||||
* used. This is what replaced the old `resolveAccountReliably` / `provisionRetry`
|
||||
* loop: the store-root ambiguity that forced the retry is gone once the read moves
|
||||
* behind the doc-shim barrier.
|
||||
*
|
||||
* Cached per account (in `accountCache`); a hit skips the query entirely, so
|
||||
* repeated resolves of the same account are free. `resetRegistryCache` clears it.
|
||||
*/
|
||||
export async function resolveAccount(id: string): Promise<AccountRecord | null> {
|
||||
const key = accountKey(id);
|
||||
const cached = accountCache.get(key);
|
||||
if (cached) return cached;
|
||||
|
||||
const s = await session();
|
||||
const doc = await resolveShimDoc();
|
||||
// `subj` is already IRI-safe (accountSubject → escapeIri). The read is anchored to
|
||||
// the doc-shim's default graph (opened through its barrier by resolveShimDoc), so
|
||||
// it is authoritative. The query is bounded to this one subject.
|
||||
const subj = accountSubject(id);
|
||||
const query = `
|
||||
SELECT ?id ?docPublic ?docProtected ?docPrivate WHERE {
|
||||
<${subj}> a <${P.type}> ;
|
||||
<${P.id}> ?id ;
|
||||
<${P.docPublic}> ?docPublic ;
|
||||
<${P.docProtected}> ?docProtected ;
|
||||
<${P.docPrivate}> ?docPrivate .
|
||||
}`;
|
||||
try {
|
||||
const result = await sparqlQuery(s.sessionId, query, undefined, doc, "resolveAccount");
|
||||
const rows = readBindings(result);
|
||||
if (rows.length === 0) {
|
||||
logStage("resolveAccount(" + key + ") → null");
|
||||
return null;
|
||||
}
|
||||
// DETERMINISTIC: a corrupted shim may return SEVERAL bindings for this one
|
||||
// account subject (duplicate scope-doc values from past forks). Pick the
|
||||
// canonical (lexicographically-smallest) doc per scope so writer and reader
|
||||
// always resolve the SAME docPublic (robustness against PAST fork residue).
|
||||
const record = recordFromRows(rows, id);
|
||||
accountCache.set(key, record);
|
||||
logStage("resolveAccount(" + key + ") → 1 record");
|
||||
return record;
|
||||
} catch (error) {
|
||||
console.error(accessLogPrefix() + " resolveAccount failed:", error);
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/** All known accounts (from the shim). */
|
||||
export async function allAccounts(): Promise<AccountRecord[]> {
|
||||
return [...(await loadShim()).values()];
|
||||
}
|
||||
|
||||
/** Persist one AccountRecord into the doc-shim (anchored default-graph write, the
|
||||
* canonical always-safe shape — same convention as createEntityDoc). */
|
||||
async function writeRecord(doc: Nuri, record: AccountRecord): Promise<void> {
|
||||
const s = await session();
|
||||
const subj = `${SHIM}:account:${escapeIri(accountKey(record.id))}`;
|
||||
// `subj` is IRI-safe (escapeIri). `id` is UNTRUSTED text in a LITERAL position →
|
||||
// escapeLiteral. The doc NURIs come from `ng` but are stored as literals here, so
|
||||
// they are escaped as literals too (defence in depth). NO explicit `GRAPH <…>`
|
||||
// wrapper: write the anchored DEFAULT graph (the `doc` anchor scopes it) — the
|
||||
// canonical, always-safe shape the anchored default-graph read queries match.
|
||||
const update = `
|
||||
INSERT DATA {
|
||||
<${subj}> a <${P.type}> ;
|
||||
<${P.id}> "${escapeLiteral(record.id)}" ;
|
||||
<${P.docPublic}> "${escapeLiteral(record.docPublic)}" ;
|
||||
<${P.docProtected}> "${escapeLiteral(record.docProtected)}" ;
|
||||
<${P.docPrivate}> "${escapeLiteral(record.docPrivate)}" .
|
||||
}`;
|
||||
try {
|
||||
await sparqlUpdate(s.sessionId, update, doc, "writeRecord");
|
||||
} catch (error) {
|
||||
console.error(accessLogPrefix() + " writeRecord persist failed:", error);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* In-flight `ensureAccount` promises, keyed by account key — so CONCURRENT
|
||||
* `ensureAccount(id)` calls for the SAME account share ONE resolve-or-provision.
|
||||
*
|
||||
* ── 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
|
||||
* 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
|
||||
* collapses those N into ONE: the first caller resolves-or-provisions; every
|
||||
* concurrent caller awaits the SAME promise and gets the SAME record. Not polling: a
|
||||
* bounded in-memory promise map (mirrors open-repo.ts `inFlight`), cleared the instant
|
||||
* it settles.
|
||||
*/
|
||||
const ensureInFlight = new Map<string, Promise<AccountRecord>>();
|
||||
|
||||
/**
|
||||
* Ensure an account exists in the shim, creating its 3 scope documents on
|
||||
* first sight. Idempotent — returns the existing record if already present.
|
||||
* Concurrency-safe: concurrent calls for the same account share one provision
|
||||
* (see {@link ensureInFlight}) so a fresh page never FORKS the account.
|
||||
*/
|
||||
export async function ensureAccount(id: string): Promise<AccountRecord> {
|
||||
const key = accountKey(id);
|
||||
// A completed provision/resolve is cached → no query, no fork risk.
|
||||
const cached = accountCache.get(key);
|
||||
if (cached) return cached;
|
||||
// A concurrent provision for the SAME account is already running → await it,
|
||||
// instead of racing a second (forking) provision. This is the anti-fork guard.
|
||||
const pending = ensureInFlight.get(key);
|
||||
if (pending) return pending;
|
||||
|
||||
const p = (async (): Promise<AccountRecord> => {
|
||||
// HOT PATH: targeted O(1) lookup — does THIS account already exist? — instead
|
||||
// of a full-shim scan (loadShim). Off the read/write hot path entirely.
|
||||
//
|
||||
// Barrier-AUTHORITATIVE: resolveAccount reads the doc-shim behind its first-`State`
|
||||
// barrier (opened by resolveShimDoc), so a 0 here means the account is GENUINELY
|
||||
// absent — not sync-lag. No account-level retry: the store-root ambiguity that
|
||||
// forced the old provisionRetry loop is gone once the read moves behind the barrier.
|
||||
const existing = await resolveAccount(id);
|
||||
if (existing) return existing;
|
||||
|
||||
const doc = await resolveShimDoc();
|
||||
const [docPublic, docProtected, docPrivate] = await Promise.all([
|
||||
createDoc(),
|
||||
createDoc(),
|
||||
createDoc(),
|
||||
]);
|
||||
const record: AccountRecord = { id, docPublic, docProtected, docPrivate };
|
||||
// Persist the record INTO the doc-shim (not the store-root anymore).
|
||||
await writeRecord(doc, record);
|
||||
// Feed the per-account cache, and the full-shim cache if it is already loaded
|
||||
// (so allAccounts / the fan-out see the freshly-created account too).
|
||||
accountCache.set(key, record);
|
||||
cache?.set(key, record);
|
||||
return record;
|
||||
})();
|
||||
|
||||
ensureInFlight.set(key, p);
|
||||
try {
|
||||
return await p;
|
||||
} finally {
|
||||
ensureInFlight.delete(key);
|
||||
}
|
||||
}
|
||||
|
||||
// --- resolvers ------------------------------------------------------------
|
||||
|
||||
/** The index document NURI of an account for a scope (the store-container). */
|
||||
function indexDocOf(record: AccountRecord, scope: Scope): Nuri {
|
||||
return scope === "public"
|
||||
? record.docPublic
|
||||
: scope === "protected"
|
||||
? record.docProtected
|
||||
: record.docPrivate;
|
||||
}
|
||||
|
||||
/**
|
||||
* NURI of the document where `id` writes GROUPED entities of `scope` (a single
|
||||
* 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> {
|
||||
const record = await ensureAccount(id);
|
||||
return indexDocOf(record, scope);
|
||||
}
|
||||
|
||||
/** NURIs of every account's document for `scope` (read fan-out). */
|
||||
export async function resolveReadGraphs(scope: Scope): Promise<Nuri[]> {
|
||||
const accounts = await allAccounts();
|
||||
return accounts.map((a) => indexDocOf(a, scope));
|
||||
}
|
||||
|
||||
// --- SDK-shaped scope resolvers (no store-id ever leaves the lib) ----------
|
||||
//
|
||||
// The consumer asks by SCOPE ("give me the graph to write/read entities of
|
||||
// scope X", "give me the inbox anchor") and NEVER constructs a `did:ng:${…}`
|
||||
// store NURI itself. The lib owns the physical placement — which is the whole
|
||||
// point of the SDK boundary. In THIS polyfill the placement is the shared
|
||||
// wallet's native stores (Axis A, per the two-axes doctrine in
|
||||
// docs/simulation.md): a scope maps to a native store NURI resolved from the
|
||||
// injected session. `public` currently co-locates with `protected` because
|
||||
// `doc_create`/ORM cannot target a non-private/protected native store today
|
||||
// (the SDK blocker recorded in migration-guide.md); at migration each scope
|
||||
// resolves to the user's REAL per-scope store and this mapping changes here,
|
||||
// in the lib, with no consumer change.
|
||||
|
||||
/** 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> {
|
||||
const s = await session();
|
||||
if (scope === "private") return `did:ng:${s.privateStoreId}`;
|
||||
// public + protected → the protected native store (see note above). Falls
|
||||
// back to the private store if the session didn't carry a protected id.
|
||||
const store = s.protectedStoreId ?? s.privateStoreId;
|
||||
return `did:ng:${store}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* The graph NURI where the current session WRITES entities of `scope`, and
|
||||
* whose repo `useShape` must subscribe to read them back. SDK-shaped: the
|
||||
* consumer passes a logical scope and gets an opaque graph NURI — it holds no
|
||||
* store-id and builds no NURI. Use the returned value as both the read scope
|
||||
* (`useShape(shape, nuri)`) and the `@graph` write target.
|
||||
*/
|
||||
export async function resolveScopeGraph(scope: Scope): Promise<Nuri> {
|
||||
return scopeStoreNuri(scope);
|
||||
}
|
||||
|
||||
/**
|
||||
* The reserved account that OWNS the shared registration-inbox document. Like the
|
||||
* discovery index's special account, it lives in the reserved namespace (no user
|
||||
* can produce this key) and only HOSTS a document — its `public` scope document is
|
||||
* the inbox anchor. Disappears at migration (native per-document inboxes).
|
||||
*/
|
||||
const INBOX_ANCHOR_ACCOUNT = reservedAccount("inbox");
|
||||
|
||||
/**
|
||||
* The inbox anchor NURI for the current session (where emulated inbox deposits
|
||||
* physically land). SDK-shaped: the consumer never resolves a store itself.
|
||||
*
|
||||
* This is a DEDICATED inbox DOCUMENT (a reserved account's public scope document —
|
||||
* a real repo NURI from `docCreate`, stable across clients via the shim), NOT the
|
||||
* shared wallet's private-store root. Reason (perf + hygiene): the shim (the
|
||||
* account→document trust root) is scanned on every `loadShim`; routing every inbox
|
||||
* deposit into that SAME graph bloats it without bound (thousands of deposit triples
|
||||
* across sessions). A separate inbox document keeps the shim graph small and the
|
||||
* deposits isolated. At migration this becomes the host's native per-document inbox
|
||||
* and the resolution moves here.
|
||||
*/
|
||||
export async function resolveInboxAnchor(): Promise<Nuri> {
|
||||
const record = await ensureAccount(INBOX_ANCHOR_ACCOUNT);
|
||||
return record.docPublic;
|
||||
}
|
||||
|
||||
// --- per-entity documents + per-scope index -------------------------------
|
||||
|
||||
/**
|
||||
* Create a dedicated document for ONE entity — mirrors the target, where each
|
||||
* such entity is its own document/repo (addressable, future inbox). The new
|
||||
* document's NURI is appended to the account's scope index document (the
|
||||
* store-container). Returns the entity document NURI (use it as `@graph`).
|
||||
*/
|
||||
export async function createEntityDoc(id: string, scope: Scope): Promise<Nuri> {
|
||||
const record = await ensureAccount(id);
|
||||
const indexDoc = indexDocOf(record, scope);
|
||||
const entityNuri = await createDoc();
|
||||
const s = await session();
|
||||
try {
|
||||
await sparqlUpdate(
|
||||
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 (readScopeIndex below, same as
|
||||
// read-model.ts). Not a round-trip necessity on the current broker: the e2e
|
||||
// harness (`packages/client/e2e/`) verified an anchored `GRAPH <plainNuri>`
|
||||
// write ALSO round-trips here (same repo graph, no phantom graph); no-GRAPH
|
||||
// is kept as a simplicity/safety convention. entityNuri is a NURI stored as
|
||||
// a literal → escapeLiteral.
|
||||
`INSERT DATA { <${INDEX_SUBJECT}> <${P.contains}> "${escapeLiteral(entityNuri)}" }`,
|
||||
indexDoc,
|
||||
"createEntityDoc",
|
||||
);
|
||||
} catch (error) {
|
||||
console.error(accessLogPrefix() + " createEntityDoc index append failed:", error);
|
||||
}
|
||||
return entityNuri;
|
||||
}
|
||||
|
||||
/** Read the entity-document NURIs contained in ONE scope index document. */
|
||||
async function readScopeIndex(indexDoc: Nuri): Promise<Nuri[]> {
|
||||
const s = await session();
|
||||
const out: Nuri[] = [];
|
||||
// COLD-START heal (polyfill-era): on a fresh session over a persistent wallet the
|
||||
// scope-index repo (public OR protected — the protected one carries participations
|
||||
// and is the one that most often reads empty) is not yet in `self.repos`, so this
|
||||
// anchored read would return 0 NURIs → nothing gets listed → nothing gets
|
||||
// subscribed (the self-inflicted circularity). Open/subscribe the index repo ONCE
|
||||
// before reading it. Idempotent per session; no-op with the unit fake ng. See
|
||||
// open-repo.ts.
|
||||
await ensureRepoOpen(indexDoc);
|
||||
try {
|
||||
const res = await sparqlQuery(
|
||||
s.sessionId,
|
||||
// NO explicit `GRAPH <…>` clause — read the anchored DEFAULT graph (see
|
||||
// the note in createEntityDoc). The `indexDoc` anchor scopes the query.
|
||||
`SELECT ?e WHERE { <${INDEX_SUBJECT}> <${P.contains}> ?e }`,
|
||||
undefined,
|
||||
indexDoc,
|
||||
"readScopeIndex",
|
||||
);
|
||||
for (const row of readBindings(res)) {
|
||||
const v = bindingValue(row, "e");
|
||||
if (v) out.push(v);
|
||||
}
|
||||
} catch (error) {
|
||||
console.error(accessLogPrefix() + " readScopeIndex failed:", error);
|
||||
}
|
||||
logStage("readScopeIndex(" + shortNuri(indexDoc) + ") → " + out.length + " entities");
|
||||
return out;
|
||||
}
|
||||
|
||||
/**
|
||||
* Every entity document NURI of `scope`, across all accounts — the read
|
||||
* fan-out for per-entity scopes. Reads each account's scope index document and
|
||||
* unions the contained NURIs. Use as `useShape(shape, { graphs })`.
|
||||
*
|
||||
* NOTE (read-by-need): this ALL-ACCOUNTS fan-out contradicts the read-by-need
|
||||
* model (docs/read-model.md) — it opens/syncs other accounts' possibly-unsynced
|
||||
* docs, which HANGS. Prefer {@link listMyEntityDocs} (my own account's scope
|
||||
* docs) for "my entities", and the discovery index for "all public events".
|
||||
* Retained for callers that legitimately need every account (tests).
|
||||
*/
|
||||
export async function listEntityDocs(scope: Scope): Promise<Nuri[]> {
|
||||
const accounts = await allAccounts();
|
||||
const out: Nuri[] = [];
|
||||
for (const a of accounts) {
|
||||
out.push(...(await readScopeIndex(indexDocOf(a, scope))));
|
||||
}
|
||||
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).
|
||||
*/
|
||||
export async function scopeIndexDoc(id: string, scope: Scope): Promise<Nuri> {
|
||||
const record = await ensureAccount(id);
|
||||
return indexDocOf(record, scope);
|
||||
}
|
||||
|
||||
/**
|
||||
* The entity-document NURIs of `scope` belonging to ONE account (`id`) —
|
||||
* the read-by-need path for one account's own entities. Bounded to a SINGLE
|
||||
* account: it resolves only that account's scope index doc (via `ensureAccount`)
|
||||
* and reads the contained NURIs — NO cross-account fan-out, so it never touches
|
||||
* another account's unsynced docs. This is the helper a consumer application uses
|
||||
* for its own my-entities path, instead of the all-accounts `listEntityDocs`.
|
||||
*/
|
||||
export async function listMyEntityDocs(id: string, scope: Scope): Promise<Nuri[]> {
|
||||
const record = await ensureAccount(id);
|
||||
return readScopeIndex(indexDocOf(record, scope));
|
||||
}
|
||||
@@ -1,187 +0,0 @@
|
||||
/**
|
||||
* Reactive single-document subscription — the polyfill's typed wrapper over the
|
||||
* platform's `doc_subscribe` primitive. This is the canonical NextGraph reactive
|
||||
* read at the document granularity: subscribe once, get the initial state pushed,
|
||||
* then a push on every subsequent commit to that document — whether the write was
|
||||
* local (this session) or a broker-synced remote change. NO POLLING.
|
||||
*
|
||||
* ── Why call the REAL injected `ng` directly (never `makeNg`) ──────────────
|
||||
* Same hard constraint as `docs.ts`: the public `ng` is a JS `Proxy` over
|
||||
* `@ng-org/web`'s iframe-RPC proxy. `doc_subscribe` is a STREAMED method — the
|
||||
* `@ng-org/web` RPC strips the callback (by positional index) BEFORE it posts to
|
||||
* the iframe and drives it locally via a `MessageChannel` port (the function is
|
||||
* never structured-cloned, so no `DataCloneError`). Layering our own Proxy on top
|
||||
* risks re-wrapping that surface; reaching the real `ng` held in the config avoids
|
||||
* the double-proxy exactly as the raw `docs` primitives do. Do not import from
|
||||
* `./ng-proxy`.
|
||||
*
|
||||
* ── The primitive shape (verified against nextgraph-rs) ────────────────────
|
||||
* `ng.doc_subscribe(repo_o: string, session_id, callback)`
|
||||
* (`sdk/js/lib-wasm/src/lib.rs:1907`) is **per-document** — one repo NURI, one
|
||||
* callback. It is `async`, resolving to a JS **unsubscribe function**. The
|
||||
* callback is invoked `callback(appResponse)` with a serialized `AppResponse`:
|
||||
* `{ V0: { State | Patch | TabInfo | ... } }`. It pushes an initial `State`
|
||||
* (plus a `TabInfo`) on subscribe, then a `Patch` per verified commit on the
|
||||
* branch. Returning `true` from the callback also cancels; we cancel by calling
|
||||
* the returned unsubscribe fn.
|
||||
*
|
||||
* ── Why per-document, never `orm_start_graph(graphs:[…])` ──────────────────
|
||||
* A single not-yet-synced repo in an ORM graph fan-out makes `RepoNotFound` abort
|
||||
* the WHOLE subscription (`initialize.rs:125-128`), so the readyPromise never
|
||||
* resolves → the ~75s hang. `doc_subscribe` is per-branch/per-doc and has no
|
||||
* fan-out: an absent doc breaks only its own subscription. {@link subscribeDocs}
|
||||
* builds a set of these with per-doc error isolation to preserve that property.
|
||||
*/
|
||||
|
||||
import { getConfig, getStoreRegistryDeps } from "./polyfill";
|
||||
import type { Nuri } from "./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
|
||||
* permissive rather than modelling every AppResponse variant.
|
||||
*/
|
||||
export type DocChange = unknown;
|
||||
|
||||
/**
|
||||
* The discriminant of a {@link DocChange} — the single variant key of the raw
|
||||
* `AppResponse` payload (`{ V0: { State | Patch | TabInfo | … } }`). It is NOT a
|
||||
* closed enum: the platform may push other variants, so this is a bare `string`
|
||||
* (e.g. `"State"`, `"Patch"`, `"TabInfo"`), or `undefined` when the shape can't
|
||||
* be read. Verified against the CONTRACT-3 e2e probe (`e2e/sdk-entry.ts`): the
|
||||
* variant is `Object.keys(resp.V0)[0]`. Exposed so a caller that needs the SYNC
|
||||
* BARRIER (the first `State`, per CONTRACT 3) can distinguish it from the earlier
|
||||
* `TabInfo`/`Patch` pushes — see `open-repo.ts`. Most callers ignore it and use
|
||||
* any push as a plain change signal.
|
||||
*/
|
||||
export type DocChangeType = string | undefined;
|
||||
|
||||
/**
|
||||
* Extract the variant key from a raw {@link DocChange}. Reads `resp.V0` (case-
|
||||
* tolerant to `v0`) and returns its first key — the AppResponse variant name
|
||||
* (`"State"` / `"Patch"` / `"TabInfo"` / …). Returns `undefined` if the payload
|
||||
* is not a recognisable `{ V0: { <Variant>: … } }` object. Inspects the variant
|
||||
* proplerly (no `any`-cast to force it) so a `State` push is identifiable.
|
||||
*/
|
||||
export function docChangeType(resp: DocChange): DocChangeType {
|
||||
if (!resp || typeof resp !== "object") return undefined;
|
||||
const outer = resp as { V0?: unknown; v0?: unknown };
|
||||
const v0 = outer.V0 ?? outer.v0;
|
||||
if (!v0 || typeof v0 !== "object") return undefined;
|
||||
const keys = Object.keys(v0 as Record<string, unknown>);
|
||||
return keys.length > 0 ? keys[0] : undefined;
|
||||
}
|
||||
|
||||
/** An unsubscribe function — idempotent (calling it twice is a no-op). */
|
||||
export type Unsubscribe = () => void;
|
||||
|
||||
async function sessionId(): Promise<string> {
|
||||
return (await getStoreRegistryDeps().getSession()).sessionId;
|
||||
}
|
||||
|
||||
/**
|
||||
* Subscribe to ONE document. `onChange` fires on the initial state push and on
|
||||
* every subsequent change to that doc (local write OR broker-synced remote
|
||||
* change). Returns an unsubscribe function.
|
||||
*
|
||||
* The wrapper is synchronous-returning (an unsubscribe fn) even though the
|
||||
* underlying `ng.doc_subscribe` is async: the real unsubscribe is captured when
|
||||
* the promise resolves; if the caller unsubscribes before setup completes, the
|
||||
* cancellation is honoured as soon as the real unsubscribe is available (and no
|
||||
* further `onChange` fires after unsubscribe).
|
||||
*
|
||||
* `onChange` receives the raw payload AND its variant type ({@link docChangeType},
|
||||
* e.g. `"State"`). The type is a NON-BREAKING second argument: existing callers
|
||||
* that ignore it (the change-signal pattern — `discovery.ts`, `inbox.ts`) are
|
||||
* unaffected; a caller that needs the sync barrier (`open-repo.ts`) reads it to
|
||||
* act only on the first `State`.
|
||||
*
|
||||
* Calls the REAL injected `ng.doc_subscribe` directly (never `makeNg`).
|
||||
*/
|
||||
export function subscribeDoc(
|
||||
nuri: Nuri,
|
||||
onChange: (r: DocChange, type: DocChangeType) => void,
|
||||
): Unsubscribe {
|
||||
const { ng } = getConfig();
|
||||
let stopped = false;
|
||||
let realUnsub: (() => void) | null = null;
|
||||
|
||||
const cb = (resp: DocChange): void => {
|
||||
if (stopped) return;
|
||||
try {
|
||||
onChange(resp, docChangeType(resp));
|
||||
} catch (error) {
|
||||
console.error("[subscribe] onChange handler threw for", nuri, error);
|
||||
}
|
||||
};
|
||||
|
||||
// Kick off the async subscription. Errors are isolated to this doc (they never
|
||||
// reject a shared batch — see subscribeDocs). If setup fails, this doc simply
|
||||
// never fires; the caller's unsubscribe stays a safe no-op.
|
||||
void (async () => {
|
||||
try {
|
||||
const sid = await sessionId();
|
||||
const unsub = (await ng.doc_subscribe(nuri, sid, cb)) as (() => void) | undefined;
|
||||
if (stopped) {
|
||||
// Unsubscribed before setup resolved — cancel immediately.
|
||||
if (typeof unsub === "function") unsub();
|
||||
return;
|
||||
}
|
||||
realUnsub = typeof unsub === "function" ? unsub : null;
|
||||
} catch (error) {
|
||||
console.error("[subscribe] doc_subscribe failed for", nuri, error);
|
||||
}
|
||||
})();
|
||||
|
||||
return () => {
|
||||
if (stopped) return;
|
||||
stopped = true;
|
||||
if (realUnsub) {
|
||||
try {
|
||||
realUnsub();
|
||||
} catch (error) {
|
||||
console.error("[subscribe] unsubscribe failed for", nuri, error);
|
||||
}
|
||||
realUnsub = null;
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Subscribe to a SET of documents, one {@link subscribeDoc} per NURI, with
|
||||
* PER-DOC error isolation. `onChange(nuri, r)` fires for whichever doc changed.
|
||||
* Returns a single unsubscribe that tears down all of them.
|
||||
*
|
||||
* The per-doc isolation is the point: a bad / not-yet-synced doc breaks only its
|
||||
* own subscription and NEVER aborts the others (this is precisely what avoids the
|
||||
* ORM fan-out hang — do NOT replace this with `orm_start_graph(graphs:[…])`). The
|
||||
* set is deduplicated; an empty set returns a no-op unsubscribe.
|
||||
*/
|
||||
export function subscribeDocs(
|
||||
nuris: Nuri[],
|
||||
onChange: (nuri: Nuri, r: DocChange, type: DocChangeType) => void,
|
||||
): Unsubscribe {
|
||||
const unique = [...new Set(nuris.filter(Boolean))];
|
||||
const unsubs = unique.map((nuri) => {
|
||||
// Each subscription is independent: subscribeDoc already isolates its own
|
||||
// async setup failure (logged, never thrown), so one bad doc cannot abort the
|
||||
// construction of the others here.
|
||||
try {
|
||||
return subscribeDoc(nuri, (r, type) => onChange(nuri, r, type));
|
||||
} catch (error) {
|
||||
console.error("[subscribe] subscribeDocs: failed to subscribe", nuri, error);
|
||||
return () => {};
|
||||
}
|
||||
});
|
||||
return () => {
|
||||
for (const u of unsubs) {
|
||||
try {
|
||||
u();
|
||||
} catch (error) {
|
||||
console.error("[subscribe] subscribeDocs: unsubscribe failed", error);
|
||||
}
|
||||
}
|
||||
};
|
||||
}
|
||||
@@ -1,26 +0,0 @@
|
||||
/**
|
||||
* Generic, NextGraph-shaped types. ZERO application domain.
|
||||
*/
|
||||
|
||||
/** A NextGraph URI (document / store / inbox). */
|
||||
export type Nuri = string;
|
||||
|
||||
/** NextGraph-native store scopes. The *mapping* of entities to scopes is the
|
||||
* consumer's concern; this layer only knows the three scopes exist. */
|
||||
export type Scope = "public" | "protected" | "private";
|
||||
|
||||
/** The current identity id. Target: the wallet user (`session.user`). Polyfill:
|
||||
* a chosen id, because everyone shares one wallet. */
|
||||
export type PrincipalId = string;
|
||||
|
||||
/**
|
||||
* Loose shape of the real `@ng-org/web` `ng` object that we wrap. Injected by
|
||||
* the consumer at {@link configure} — we never hard-import the SDK, which keeps
|
||||
* the build-alias safe (the app's `@ng-org/web` import can resolve to us) and
|
||||
* makes the wrapper testable with a fake. Permissive on purpose: the real `ng`
|
||||
* carries non-function members too, so we accept any property bag.
|
||||
*/
|
||||
export type NgLike = Record<string, any>;
|
||||
|
||||
/** Loose shape of `@ng-org/orm`'s `useShape` (a generic hook). */
|
||||
export type UseShapeLike = (...args: any[]) => any;
|
||||
@@ -1,17 +0,0 @@
|
||||
/**
|
||||
* Wrapped `useShape`: same signature as `@ng-org/orm`. When a read-cap policy is
|
||||
* declared, the returned set is a read-filtered VIEW (only items in documents the
|
||||
* current user holds a ReadCap for); otherwise it passes the real set through
|
||||
* unchanged. At migration the filtering disappears — the broker only delivers
|
||||
* authorized documents.
|
||||
*/
|
||||
|
||||
import { getConfig, getCurrentUser, getCaps } from "./polyfill";
|
||||
import { makeReadFilteredView } from "./read-filter";
|
||||
|
||||
export function useShape(shapeType: unknown, scope: unknown): unknown {
|
||||
const set = getConfig().useShape(shapeType, scope) as object;
|
||||
const caps = getCaps();
|
||||
if (!caps.hasReadPolicy()) return set; // no policy configured → passthrough
|
||||
return makeReadFilteredView(set, caps, getCurrentUser);
|
||||
}
|
||||
@@ -1,384 +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 identity's per-entity
|
||||
* docs for that scope (`storeRegistry.listMyEntityDocs`), PLUS — for `public`
|
||||
* only — the discovery index folded in (`discovery.readIndex`), so the app
|
||||
* never orchestrates discovery to read. Faithful to the future
|
||||
* `useShape(shape, 'public')`.
|
||||
* 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): `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; announcing a public entity appends
|
||||
* to the discovery index), so we ALSO subscribe to the scope-index document (and,
|
||||
* for `public`, the discovery-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.
|
||||
*/
|
||||
|
||||
import { getCurrentUser } from "./polyfill";
|
||||
import { ensureReposOpen, getSyncState } from "./open-repo";
|
||||
import { readUnion, type UnionSubject } from "./read-model";
|
||||
import { subscribeDoc, type Unsubscribe } from "./subscribe";
|
||||
import { listMyEntityDocs, scopeIndexDoc } from "./store-registry";
|
||||
import { readIndex, indexDocNuri } from "./discovery";
|
||||
import type { Nuri, Scope } from "./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.
|
||||
*/
|
||||
export interface ShapeQuery<T = UnionSubject> {
|
||||
/** The subjects of the requested shape/scope. Empty array when none (never undefined). */
|
||||
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`). */
|
||||
isError: boolean;
|
||||
/** The caught error when `isError`, else `undefined`. */
|
||||
error: unknown;
|
||||
}
|
||||
|
||||
/** The observable a caller binds with `useSyncExternalStore` (phase B). */
|
||||
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.
|
||||
*/
|
||||
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>();
|
||||
// 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();
|
||||
}
|
||||
|
||||
/** Extract candidate document NURIs from an opaque discovery `ref` — every
|
||||
* string, recursively, that looks like a NextGraph doc NURI (`did:ng:`). Generic:
|
||||
* the app puts the entity doc NURI inside the ref it submits; we fold those docs
|
||||
* into the read-set so the app need not orchestrate discovery. Non-NURI refs
|
||||
* contribute nothing (and readUnion+shape-filter drop anything irrelevant). */
|
||||
function nurisFromRef(ref: unknown, out: Set<Nuri>): void {
|
||||
if (typeof ref === "string") {
|
||||
if (ref.startsWith("did:ng:")) out.add(ref);
|
||||
return;
|
||||
}
|
||||
if (Array.isArray(ref)) {
|
||||
for (const v of ref) nurisFromRef(v, out);
|
||||
return;
|
||||
}
|
||||
if (ref && typeof ref === "object") {
|
||||
for (const v of Object.values(ref)) nurisFromRef(v, out);
|
||||
}
|
||||
}
|
||||
|
||||
/** Resolve the logical scope → the current doc set (my entity docs + discovery
|
||||
* fold for `public`). Tolerant: a resolution failure yields whatever resolved. */
|
||||
async function resolveDocs(): Promise<Nuri[]> {
|
||||
const user = getCurrentUser();
|
||||
const set = new Set<Nuri>();
|
||||
if (user) {
|
||||
try {
|
||||
for (const d of await listMyEntityDocs(user, scope)) set.add(d);
|
||||
} catch (error) {
|
||||
console.error("[watch-shape] listMyEntityDocs failed", error);
|
||||
}
|
||||
}
|
||||
if (scope === "public") {
|
||||
try {
|
||||
for (const e of await readIndex()) nurisFromRef(e.ref, set);
|
||||
} catch (error) {
|
||||
console.error("[watch-shape] discovery readIndex failed", error);
|
||||
}
|
||||
}
|
||||
return [...set];
|
||||
}
|
||||
|
||||
/** Subscribe to the CONTAINER documents (scope-index; discovery-index for public)
|
||||
* so a change to the doc SET re-resolves. Idempotent per NURI. */
|
||||
async function ensureContainerSubs(): Promise<void> {
|
||||
const containers: Nuri[] = [];
|
||||
const user = getCurrentUser();
|
||||
if (user) {
|
||||
try {
|
||||
containers.push(await scopeIndexDoc(user, scope));
|
||||
} catch (error) {
|
||||
console.error("[watch-shape] scopeIndexDoc failed", error);
|
||||
}
|
||||
}
|
||||
if (scope === "public") {
|
||||
try {
|
||||
containers.push(await indexDocNuri());
|
||||
} catch (error) {
|
||||
console.error("[watch-shape] indexDocNuri 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;
|
||||
setSnapshot({ data: [], isPending: false, isSuccess: false, isError: true, 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. */
|
||||
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;
|
||||
setSnapshot({ data: [], isPending: false, isSuccess: false, isError: true, 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;
|
||||
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();
|
||||
started = false;
|
||||
}
|
||||
};
|
||||
},
|
||||
refetch(): void {
|
||||
start();
|
||||
void refresh();
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -1,83 +0,0 @@
|
||||
import { test, expect } from "bun:test";
|
||||
import { CapRegistry } from "../src/caps";
|
||||
|
||||
test("public documents are readable by anyone, even anonymous", () => {
|
||||
const caps = new CapRegistry();
|
||||
caps.open("did:ng:o:pub", "public", "alice");
|
||||
expect(caps.canRead("did:ng:o:pub", null)).toBe(true);
|
||||
expect(caps.canRead("did:ng:o:pub", "bob")).toBe(true);
|
||||
});
|
||||
|
||||
test("protected documents: owner + explicitly granted principals only", () => {
|
||||
const caps = new CapRegistry();
|
||||
caps.open("did:ng:o:prot", "protected", "alice");
|
||||
expect(caps.canRead("did:ng:o:prot", "alice")).toBe(true);
|
||||
expect(caps.canRead("did:ng:o:prot", "bob")).toBe(false);
|
||||
caps.grantRead("did:ng:o:prot", "bob"); // a directed grant issues bob the read cap
|
||||
expect(caps.canRead("did:ng:o:prot", "bob")).toBe(true);
|
||||
});
|
||||
|
||||
test("private documents: owner only", () => {
|
||||
const caps = new CapRegistry();
|
||||
caps.open("did:ng:o:priv", "private", "alice");
|
||||
expect(caps.canRead("did:ng:o:priv", "alice")).toBe(true);
|
||||
expect(caps.canRead("did:ng:o:priv", "bob")).toBe(false);
|
||||
expect(caps.canRead("did:ng:o:priv", null)).toBe(false);
|
||||
});
|
||||
|
||||
test("protectedDocsOf surfaces an owner's protected documents for directed grants", () => {
|
||||
const caps = new CapRegistry();
|
||||
caps.open("did:ng:o:prot1", "protected", "alice");
|
||||
caps.open("did:ng:o:prot2", "protected", "alice");
|
||||
caps.open("did:ng:o:pub", "public", "alice"); // not protected → excluded
|
||||
caps.open("did:ng:o:priv", "private", "alice"); // not protected → excluded
|
||||
caps.open("did:ng:o:bob", "protected", "bob"); // other owner → excluded
|
||||
expect(caps.protectedDocsOf("alice").sort()).toEqual([
|
||||
"did:ng:o:prot1",
|
||||
"did:ng:o:prot2",
|
||||
]);
|
||||
expect(caps.protectedDocsOf("bob")).toEqual(["did:ng:o:bob"]);
|
||||
expect(caps.protectedDocsOf("carol")).toEqual([]);
|
||||
// A directed grant on one of them makes the reader read that doc only.
|
||||
caps.grantRead("did:ng:o:prot1", "carol");
|
||||
expect(caps.canRead("did:ng:o:prot1", "carol")).toBe(true);
|
||||
expect(caps.canRead("did:ng:o:prot2", "carol")).toBe(false);
|
||||
});
|
||||
|
||||
test("write is restricted to write-cap holders; the creator always holds it", () => {
|
||||
const caps = new CapRegistry();
|
||||
caps.open("did:ng:o:pub", "public", "alice");
|
||||
expect(caps.canWrite("did:ng:o:pub", "alice")).toBe(true);
|
||||
expect(caps.canWrite("did:ng:o:pub", "bob")).toBe(false);
|
||||
expect(caps.canWrite("did:ng:o:pub", null)).toBe(false);
|
||||
});
|
||||
|
||||
test("holding a document's cap does NOT grant another document (no inheritance)", () => {
|
||||
const caps = new CapRegistry();
|
||||
caps.grantRead("did:ng:o:doc1", "alice");
|
||||
expect(caps.canRead("did:ng:o:doc1", "alice")).toBe(true);
|
||||
expect(caps.canRead("did:ng:o:doc2", "alice")).toBe(false); // separate repo, separate cap
|
||||
});
|
||||
|
||||
test("governsRead / hasReadPolicy distinguish governed from ungoverned documents", () => {
|
||||
const caps = new CapRegistry();
|
||||
expect(caps.hasReadPolicy()).toBe(false);
|
||||
caps.grantRead("did:ng:o:doc1", "alice");
|
||||
expect(caps.hasReadPolicy()).toBe(true);
|
||||
expect(caps.governsRead("did:ng:o:doc1")).toBe(true);
|
||||
expect(caps.governsRead("did:ng:o:unknown")).toBe(false); // not declared → not enforced
|
||||
});
|
||||
|
||||
test("governsWrite / hasWritePolicy distinguish governed from ungoverned documents", () => {
|
||||
const caps = new CapRegistry();
|
||||
expect(caps.hasWritePolicy()).toBe(false);
|
||||
caps.open("did:ng:o:doc1", "private", "alice"); // owner gets the write cap
|
||||
expect(caps.hasWritePolicy()).toBe(true);
|
||||
expect(caps.governsWrite("did:ng:o:doc1")).toBe(true);
|
||||
expect(caps.governsWrite("did:ng:o:unknown")).toBe(false); // not declared → not enforced
|
||||
// A public doc grants read to all but its write cap is still owner-only.
|
||||
const pub = new CapRegistry();
|
||||
pub.open("did:ng:o:pub", "public", "alice");
|
||||
expect(pub.hasWritePolicy()).toBe(true);
|
||||
expect(pub.governsWrite("did:ng:o:pub")).toBe(true);
|
||||
});
|
||||
@@ -1,333 +0,0 @@
|
||||
import { test, expect, mock, beforeEach, afterAll } from "bun:test";
|
||||
import { submitToIndex, readIndex, watchIndex, INDEX_ACCOUNT } from "../src/discovery";
|
||||
import type { IndexEntry } from "../src/discovery";
|
||||
import {
|
||||
configure,
|
||||
configureStoreRegistry,
|
||||
resetStoreRegistry,
|
||||
resetConfig,
|
||||
setCurrentUser,
|
||||
getCaps,
|
||||
resetCaps,
|
||||
} from "../src/polyfill";
|
||||
import { resetRegistryCache, ensureAccount } from "../src/store-registry";
|
||||
import type { RegistrySession } from "../src/store-registry";
|
||||
|
||||
// discovery.ts submits to / reads from a global index owned by a RESERVED
|
||||
// SPECIAL ACCOUNT (@index) in the shim. This suite injects one fake `ng` that
|
||||
// emulates BOTH the shim SPARQL (ensureAccount('@index') → doc_create ×3 +
|
||||
// shim INSERT/SELECT) AND the inbox SPARQL (deposit INSERT + read SELECT), over
|
||||
// a single in-memory quad store. Restore un-configured state at the end.
|
||||
afterAll(() => {
|
||||
resetConfig();
|
||||
resetStoreRegistry();
|
||||
setCurrentUser(null);
|
||||
resetCaps();
|
||||
});
|
||||
|
||||
test("throws a clear error when configureStoreRegistry() was not called", async () => {
|
||||
resetStoreRegistry();
|
||||
resetRegistryCache();
|
||||
await expect(submitToIndex({ ref: 1 })).rejects.toThrow(
|
||||
/configureStoreRegistry\(\) must be called before use/,
|
||||
);
|
||||
});
|
||||
|
||||
interface Quad { g: string; s: string; p: string; o: string }
|
||||
|
||||
const SHIM = "urn:ng-eventually:shim";
|
||||
const INBOX = "urn:ng-eventually:inbox";
|
||||
|
||||
/** Reverse of the lib's escapeLiteral: single left-to-right pass over `\x`. */
|
||||
function unescapeLiteral(s: string): string {
|
||||
let out = "";
|
||||
for (let i = 0; i < s.length; i++) {
|
||||
if (s[i] === "\\" && i + 1 < s.length) {
|
||||
const next = s[++i];
|
||||
out += next === "n" ? "\n" : next === "r" ? "\r" : next === "t" ? "\t" : next;
|
||||
} else {
|
||||
out += s[i];
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
// A stateful fake `ng` serving BOTH the shim and the inbox SPARQL.
|
||||
function makeFakeNg() {
|
||||
const quads: Quad[] = [];
|
||||
let docCounter = 0;
|
||||
|
||||
// Reactive subscriptions (see inbox.test.ts): doc_subscribe registers a
|
||||
// callback per anchor + fires an initial push; sparql_update pushes a Patch to
|
||||
// that anchor's subscribers, so discovery.watchIndex (now event-driven) works
|
||||
// without a timer.
|
||||
const subs = new Map<string, Set<(r: unknown) => void>>();
|
||||
const doc_subscribe = mock(async (nuri: string, _sid: unknown, cb: (r: unknown) => void) => {
|
||||
let set = subs.get(nuri);
|
||||
if (!set) {
|
||||
set = new Set();
|
||||
subs.set(nuri, set);
|
||||
}
|
||||
set.add(cb);
|
||||
queueMicrotask(() => cb({ V0: { State: { doc: nuri } } }));
|
||||
return () => set!.delete(cb);
|
||||
});
|
||||
const pushTo = (anchor: string): void => {
|
||||
for (const cb of subs.get(anchor) ?? []) cb({ V0: { Patch: { doc: anchor } } });
|
||||
};
|
||||
|
||||
const doc_create = mock(async (..._a: unknown[]) => `did:ng:o:doc${++docCounter}`);
|
||||
|
||||
const sparql_update = mock(async (...a: unknown[]) => {
|
||||
const query = a[1] as string;
|
||||
const anchor = a[2] as string | undefined;
|
||||
// TWO shapes coexist: the shim account write STILL uses `GRAPH <${priv}>`
|
||||
// (the private-store repo's graph name equals the plain store NURI → it
|
||||
// round-trips; key by that GRAPH IRI). The inbox deposit write has NO
|
||||
// explicit GRAPH — the real broker keys it by the ANCHORED repo's default
|
||||
// graph (repo_graph_name(id, overlay)); key it by the ANCHOR arg (a[2]).
|
||||
const gm = query.match(/GRAPH <([^>]+)>\s*\{([\s\S]*)\}/);
|
||||
let g: string;
|
||||
let body: string;
|
||||
if (gm) {
|
||||
g = gm[1]!;
|
||||
body = gm[2]!;
|
||||
} else {
|
||||
if (!anchor) return undefined;
|
||||
g = anchor;
|
||||
body = query.replace(/^\s*INSERT DATA\s*\{/, "").replace(/\}\s*$/, "");
|
||||
}
|
||||
const sm = body.match(/<([^>]+)>/);
|
||||
if (!sm) return undefined;
|
||||
const s = sm[1]!;
|
||||
const after = body.slice(body.indexOf(sm[0]) + sm[0].length);
|
||||
const pairRe = /(?:a|<([^>]+)>)\s+(?:"((?:[^"\\]|\\.)*)"|<([^>]+)>)/g;
|
||||
let m: RegExpExecArray | null;
|
||||
while ((m = pairRe.exec(after)) !== null) {
|
||||
// `a` → an rdf:type marker; the two type IRIs the modules use differ, so
|
||||
// pick by which body we're in (deposit vs account) — harmless if wrong,
|
||||
// the SELECT filters by the real predicates below.
|
||||
const isDeposit = query.includes(`${INBOX}:Deposit`);
|
||||
const p = m[1] ?? (isDeposit ? `${INBOX}:Deposit` : `${SHIM}:Account`);
|
||||
const o = m[2] !== undefined ? unescapeLiteral(m[2]) : (m[3] ?? "");
|
||||
quads.push({ g, s, p, o });
|
||||
}
|
||||
pushTo(g); // local-push to the written graph's subscribers
|
||||
return undefined;
|
||||
});
|
||||
|
||||
const sparql_query = mock(async (...a: unknown[]) => {
|
||||
const query = a[1] as string;
|
||||
const anchor = a[3] as string | undefined;
|
||||
// Pointer SELECT: `<shim:root> <shim:shimDoc> ?shimDoc` in the store-root graph.
|
||||
if (query.includes(`<${SHIM}:shimDoc>`)) {
|
||||
const bindings = quads
|
||||
.filter((q) => q.g === anchor && q.p === `${SHIM}:shimDoc`)
|
||||
.map((q) => ({ shimDoc: { value: q.o } }));
|
||||
return { results: { bindings } };
|
||||
}
|
||||
// Shim account SELECT (anchored to the doc-shim, no GRAPH wrapper). Two shapes:
|
||||
// the full scan (`?acc a <Account>`) and the TARGETED bounded resolve (`<subj> a
|
||||
// <Account>`) — honour that subject filter so the bounded query is O(1)/exact.
|
||||
if (query.includes(`<${SHIM}:id>`)) {
|
||||
const subjM = query.match(new RegExp(`<([^>]+)>\\s+a\\s+<${SHIM}:Account>`));
|
||||
const onlySubject = subjM ? subjM[1]! : null;
|
||||
const bySubject = new Map<string, Record<string, string>>();
|
||||
for (const q of quads) {
|
||||
if (q.g !== anchor) continue;
|
||||
if (onlySubject !== null && q.s !== onlySubject) continue;
|
||||
const rec = bySubject.get(q.s) ?? {};
|
||||
if (q.p === `${SHIM}:id`) rec.id = q.o;
|
||||
if (q.p === `${SHIM}:docPublic`) rec.docPublic = q.o;
|
||||
if (q.p === `${SHIM}:docProtected`) rec.docProtected = q.o;
|
||||
if (q.p === `${SHIM}:docPrivate`) rec.docPrivate = q.o;
|
||||
bySubject.set(q.s, rec);
|
||||
}
|
||||
const bindings = [...bySubject.values()]
|
||||
.filter((r) => r.id)
|
||||
.map((r) => ({
|
||||
id: { value: r.id! },
|
||||
docPublic: { value: r.docPublic ?? "" },
|
||||
docProtected: { value: r.docProtected ?? "" },
|
||||
docPrivate: { value: r.docPrivate ?? "" },
|
||||
}));
|
||||
return { results: { bindings } };
|
||||
}
|
||||
// Inbox deposit SELECT (?payload ?ts ?from).
|
||||
if (query.includes(`<${INBOX}:payload>`)) {
|
||||
const bySubject = new Map<string, Record<string, string>>();
|
||||
for (const q of quads) {
|
||||
if (q.g !== anchor) continue;
|
||||
if (q.p === `${INBOX}:Deposit`) {
|
||||
if (!bySubject.has(q.s)) bySubject.set(q.s, {});
|
||||
continue;
|
||||
}
|
||||
const rec = bySubject.get(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;
|
||||
bySubject.set(q.s, rec);
|
||||
}
|
||||
const bindings = [...bySubject.values()]
|
||||
.filter((r) => r.payload !== undefined && r.ts !== undefined)
|
||||
.map((r) => {
|
||||
const row: Record<string, { value: string }> = {
|
||||
payload: { value: r.payload! },
|
||||
ts: { value: r.ts! },
|
||||
};
|
||||
if (r.from !== undefined) row.from = { value: r.from };
|
||||
return row;
|
||||
});
|
||||
return { results: { bindings } };
|
||||
}
|
||||
// Entity-index SELECT (shim contains) — unused here.
|
||||
return { results: { bindings: [] } };
|
||||
});
|
||||
|
||||
return { doc_create, doc_subscribe, sparql_update, sparql_query, _quads: quads };
|
||||
}
|
||||
|
||||
const SESSION: RegistrySession = { sessionId: "sid-1", privateStoreId: "PRIV" };
|
||||
|
||||
function inject() {
|
||||
const ng = makeFakeNg();
|
||||
configure({ ng: ng as any, useShape: (() => {}) as any });
|
||||
configureStoreRegistry({
|
||||
getSession: async () => SESSION,
|
||||
normalizeId: (u) => u.trim().replace(/^@+/, "").toLowerCase(),
|
||||
});
|
||||
resetRegistryCache();
|
||||
setCurrentUser(null);
|
||||
return ng;
|
||||
}
|
||||
|
||||
let fake: ReturnType<typeof makeFakeNg>;
|
||||
beforeEach(() => {
|
||||
fake = inject();
|
||||
});
|
||||
|
||||
test("submitToIndex creates the @index special account on first sight (3 docs)", async () => {
|
||||
await submitToIndex({ nuri: "did:ng:o:event1", title: "Concert" });
|
||||
// ensureAccount('@index') created its 3 scope docs + 1 doc-shim (first login).
|
||||
expect(fake.doc_create).toHaveBeenCalledTimes(4);
|
||||
// The deposit landed in the @index public document (its inbox).
|
||||
const depositCall = fake.sparql_update.mock.calls.find((c) =>
|
||||
(c[1] as string).includes(`${INBOX}:Deposit`),
|
||||
)!;
|
||||
expect(depositCall, "a deposit INSERT was issued").not.toBeUndefined();
|
||||
expect(depositCall[2]).toMatch(/^did:ng:o:doc/); // the index document NURI
|
||||
});
|
||||
|
||||
test("submit → read round-trips the reference as an index entry", async () => {
|
||||
setCurrentUser("alice"); // `from` is bound to the current identity
|
||||
const ref = { nuri: "did:ng:o:event1", title: "Concert au parc" };
|
||||
await submitToIndex(ref, { from: "alice", ts: 100 });
|
||||
const entries = await readIndex();
|
||||
expect(entries).toHaveLength(1);
|
||||
expect(entries[0]).toEqual({ ref, from: "alice", ts: 100 } as IndexEntry);
|
||||
});
|
||||
|
||||
test("a reference submitted by A is discovered by a NON-connected reader via the index", async () => {
|
||||
// A submits (identified). No connection is ever declared. A separate reader
|
||||
// materializes the SAME index (same special account → same document) and sees
|
||||
// the reference — discovery is via the index, not any direct fan-out/link.
|
||||
setCurrentUser("alice");
|
||||
const ref = { nuri: "did:ng:o:evA", title: "Public event by A" };
|
||||
await submitToIndex(ref, { ts: 100 });
|
||||
|
||||
// Reader B: a fresh cache, never connected to A, reads the index.
|
||||
resetRegistryCache();
|
||||
setCurrentUser("bob");
|
||||
const entries = await readIndex();
|
||||
const refs = entries.map((e) => e.ref);
|
||||
expect(refs).toContainEqual(ref);
|
||||
expect(entries.find((e) => JSON.stringify(e.ref) === JSON.stringify(ref))!.from).toBe("alice");
|
||||
});
|
||||
|
||||
test("readIndex deduplicates identical references (materialization moderation point)", async () => {
|
||||
const ref = { nuri: "did:ng:o:dup", title: "Twice" };
|
||||
// Anonymous submissions (dedup keys on the ref, not the submitter).
|
||||
await submitToIndex(ref, { from: null, ts: 100 });
|
||||
await submitToIndex(ref, { from: null, ts: 200 }); // duplicate reference
|
||||
const entries = await readIndex();
|
||||
expect(entries).toHaveLength(1); // surfaced once
|
||||
});
|
||||
|
||||
test("from: null makes an anonymous submission", async () => {
|
||||
await submitToIndex({ nuri: "did:ng:o:anon" }, { from: null, ts: 100 });
|
||||
const entries = await readIndex();
|
||||
expect(entries[0]!.from).toBeNull();
|
||||
});
|
||||
|
||||
// (d) PUBLIC-ONLY: a protected/private document must NOT be submittable to the
|
||||
// world-readable discovery index; a public (or ungoverned) document is fine.
|
||||
test("(d) submitToIndex refuses a PROTECTED/PRIVATE document (public-only)", async () => {
|
||||
resetCaps();
|
||||
// A PROTECTED and a PRIVATE governed document, and a PUBLIC one.
|
||||
getCaps().open("did:ng:o:prot", "protected", "alice");
|
||||
getCaps().open("did:ng:o:priv", "private", "alice");
|
||||
getCaps().open("did:ng:o:pub", "public", "alice");
|
||||
|
||||
// Submitting the protected doc's NURI is REJECTED.
|
||||
await expect(
|
||||
submitToIndex({ nuri: "did:ng:o:prot" }, { from: null, doc: "did:ng:o:prot" }),
|
||||
).rejects.toThrow(/PUBLIC|public-only|protected\/private/i);
|
||||
// Private too.
|
||||
await expect(
|
||||
submitToIndex({ nuri: "did:ng:o:priv" }, { from: null, doc: "did:ng:o:priv" }),
|
||||
).rejects.toThrow(/PUBLIC|public-only|protected\/private/i);
|
||||
// The PUBLIC document passes.
|
||||
await submitToIndex({ nuri: "did:ng:o:pub" }, { from: null, doc: "did:ng:o:pub", ts: 1 });
|
||||
const entries = await readIndex();
|
||||
expect(entries.map((e) => (e.ref as { nuri: string }).nuri)).toEqual(["did:ng:o:pub"]);
|
||||
resetCaps();
|
||||
});
|
||||
|
||||
test("INDEX_ACCOUNT lives in the reserved namespace (no typed id can equal it)", () => {
|
||||
// The index account occupies a key no consumer input can produce: it is prefixed
|
||||
// with a NUL control char, which a user cannot type into an id field and
|
||||
// which no `normalizeId` output (a typeable value) contains. So it is
|
||||
// disjoint from the keys "index" / "@index" a hostile user would submit.
|
||||
expect(INDEX_ACCOUNT.startsWith("\u0000")).toBe(true); // unreachable-by-typing sentinel
|
||||
expect(INDEX_ACCOUNT).not.toBe("index");
|
||||
expect(INDEX_ACCOUNT).not.toBe("@index");
|
||||
});
|
||||
|
||||
test("a user named 'index'/'@index' does NOT resolve to the index account's document", async () => {
|
||||
// The discovery index lives on INDEX_ACCOUNT. A hostile (or unlucky) user who
|
||||
// registers as "index" or "@index" normalizes to key "index" — which must be
|
||||
// a DISJOINT key from the reserved index account, so they get their own
|
||||
// documents and cannot hijack / read-write the global index document.
|
||||
const indexRecord = await ensureAccount(INDEX_ACCOUNT);
|
||||
|
||||
// A real user "index" — same normalized form as "@index".
|
||||
const userIndex = await ensureAccount("index");
|
||||
expect(userIndex.docPublic).not.toBe(indexRecord.docPublic);
|
||||
expect(userIndex.docProtected).not.toBe(indexRecord.docProtected);
|
||||
expect(userIndex.docPrivate).not.toBe(indexRecord.docPrivate);
|
||||
|
||||
// "@index" must land on the SAME account as "index" (both normalize to
|
||||
// "index") — and still NOT on the reserved index account.
|
||||
const userAtIndex = await ensureAccount("@index");
|
||||
expect(userAtIndex.docPublic).toBe(userIndex.docPublic);
|
||||
expect(userAtIndex.docPublic).not.toBe(indexRecord.docPublic);
|
||||
});
|
||||
|
||||
test("watchIndex fires immediately then when a submission arrives", async () => {
|
||||
const seen: IndexEntry[][] = [];
|
||||
const stop = watchIndex((e) => seen.push(e), { intervalMs: 5 });
|
||||
await new Promise((r) => setTimeout(r, 20));
|
||||
expect(seen.length).toBeGreaterThanOrEqual(1);
|
||||
expect(seen[seen.length - 1]).toEqual([]);
|
||||
|
||||
await submitToIndex({ nuri: "did:ng:o:watched" }, { from: null, ts: 1 });
|
||||
await new Promise((r) => setTimeout(r, 20));
|
||||
const last = seen[seen.length - 1]!;
|
||||
expect(last.map((e) => (e.ref as any).nuri)).toContain("did:ng:o:watched");
|
||||
|
||||
stop();
|
||||
const countAfterStop = seen.length;
|
||||
await submitToIndex({ nuri: "did:ng:o:after" }, { from: null, ts: 2 });
|
||||
await new Promise((r) => setTimeout(r, 20));
|
||||
expect(seen.length).toBe(countAfterStop);
|
||||
});
|
||||
@@ -1,128 +0,0 @@
|
||||
/**
|
||||
* ReadCap ACTIVE — end-to-end proof that the emulated SDK enforces per-DOCUMENT
|
||||
* isolation, driven by per-entity documents + DIRECTED read grants.
|
||||
*
|
||||
* Mirrors what the app does: create an entity document through the REAL registry
|
||||
* (`createEntityDoc`), declare its cap policy via `getCaps().open(doc, scope,
|
||||
* owner)`, set the current identity, and — when the app decides two identities
|
||||
* are related — issue a DIRECTED read grant on each of the owner's protected
|
||||
* documents (`getCaps().grantRead(doc, granteeId)`). Whether identities are
|
||||
* "connected" is the application's own concept: this test plays that role
|
||||
* directly. The read filter then discriminates:
|
||||
* (a) an ungranted principal is denied a PROTECTED doc; granted once the owner
|
||||
* issues a directed grant; PUBLIC readable throughout — via the ACTIVE
|
||||
* ReadCap.
|
||||
* (b) no grant → no protected read (a reader cannot grant itself).
|
||||
*/
|
||||
import { test, expect, mock, afterAll } from "bun:test";
|
||||
import { createEntityDoc, resetRegistryCache } from "../src/store-registry";
|
||||
import type { RegistrySession } from "../src/store-registry";
|
||||
import {
|
||||
configure,
|
||||
configureStoreRegistry,
|
||||
resetStoreRegistry,
|
||||
resetConfig,
|
||||
getCaps,
|
||||
resetCaps,
|
||||
setCurrentUser,
|
||||
} from "../src/polyfill";
|
||||
import { filterReadable } from "../src/read-filter";
|
||||
|
||||
afterAll(() => {
|
||||
resetConfig();
|
||||
resetStoreRegistry();
|
||||
resetCaps();
|
||||
setCurrentUser(null);
|
||||
});
|
||||
|
||||
const SESSION: RegistrySession = { sessionId: "sid", privateStoreId: "PRIV" };
|
||||
|
||||
function inject() {
|
||||
let n = 0;
|
||||
const ng = {
|
||||
doc_create: mock(async () => `did:ng:o:doc${++n}`),
|
||||
sparql_update: mock(async () => undefined),
|
||||
sparql_query: mock(async () => ({ results: { bindings: [] } })),
|
||||
};
|
||||
configure({ ng: ng as any, useShape: (() => {}) as any });
|
||||
// Synchronous fake store → no sync lag; disable the anti-fork retry backoff.
|
||||
configureStoreRegistry({ getSession: async () => SESSION, normalizeId: (id) => id.trim() });
|
||||
resetRegistryCache();
|
||||
resetCaps();
|
||||
setCurrentUser(null);
|
||||
return ng;
|
||||
}
|
||||
|
||||
/** The app's relationship concept, played inline: grant `reader` the read cap of
|
||||
* every protected document owned by `owner`. */
|
||||
function grantOwnerProtectedTo(owner: string, reader: string) {
|
||||
for (const doc of getCaps().protectedDocsOf(owner)) getCaps().grantRead(doc, reader);
|
||||
}
|
||||
|
||||
test("ReadCap active: a private entity doc created via the real registry is hidden from another principal", async () => {
|
||||
inject();
|
||||
|
||||
const aliceDoc = await createEntityDoc("alice", "private");
|
||||
getCaps().open(aliceDoc, "private", "alice");
|
||||
|
||||
const bobDoc = await createEntityDoc("bob", "public");
|
||||
getCaps().open(bobDoc, "public", "bob");
|
||||
|
||||
const items = [
|
||||
{ "@graph": aliceDoc, "@id": "a1", label: "alice-private" },
|
||||
{ "@graph": bobDoc, "@id": "b1", label: "bob-public" },
|
||||
];
|
||||
|
||||
expect(filterReadable(items, getCaps(), "bob").map((i) => i["@id"])).toEqual(["b1"]);
|
||||
expect(filterReadable(items, getCaps(), "alice").map((i) => i["@id"]).sort()).toEqual(["a1", "b1"]);
|
||||
expect(filterReadable(items, getCaps(), null).map((i) => i["@id"])).toEqual(["b1"]);
|
||||
expect(getCaps().hasReadPolicy()).toBe(true);
|
||||
});
|
||||
|
||||
// (a) protected hidden while ungranted → revealed after a DIRECTED grant; public
|
||||
// readable regardless — all through the ACTIVE ReadCap.
|
||||
test("(a) PROTECTED doc: hidden ungranted, revealed after a DIRECTED grant, PUBLIC always readable", async () => {
|
||||
inject();
|
||||
|
||||
const aliceProtected = await createEntityDoc("alice", "protected");
|
||||
getCaps().open(aliceProtected, "protected", "alice");
|
||||
const alicePublic = await createEntityDoc("alice", "public");
|
||||
getCaps().open(alicePublic, "public", "alice");
|
||||
|
||||
const items = [
|
||||
{ "@graph": aliceProtected, "@id": "p1" },
|
||||
{ "@graph": alicePublic, "@id": "u1" },
|
||||
];
|
||||
const view = (u: string) => filterReadable(items, getCaps(), u).map((i) => i["@id"]).sort();
|
||||
|
||||
// BEFORE any grant: bob sees only the public item.
|
||||
expect(view("bob")).toEqual(["u1"]);
|
||||
expect(view("alice")).toEqual(["p1", "u1"]);
|
||||
|
||||
// The app decides alice↔bob are related and grants bob the read cap of alice's
|
||||
// protected documents.
|
||||
grantOwnerProtectedTo("alice", "bob");
|
||||
|
||||
expect(view("bob")).toEqual(["p1", "u1"]);
|
||||
// A third, ungranted principal still sees only the public one.
|
||||
expect(view("carol")).toEqual(["u1"]);
|
||||
});
|
||||
|
||||
// (b) An identity gets no protected read until the OWNER issues the grant — a
|
||||
// reader cannot grant itself.
|
||||
test("(b) no directed grant → no protected read", async () => {
|
||||
inject();
|
||||
|
||||
const aliceProtected = await createEntityDoc("alice", "protected");
|
||||
getCaps().open(aliceProtected, "protected", "alice");
|
||||
const items = [{ "@graph": aliceProtected, "@id": "p1" }];
|
||||
const view = (u: string) => filterReadable(items, getCaps(), u).map((i) => i["@id"]);
|
||||
|
||||
// mallory holds no grant on alice's protected doc → denied.
|
||||
expect(view("mallory")).toEqual([]);
|
||||
|
||||
// Granting bob (a different, legitimate reader) leaves mallory denied.
|
||||
grantOwnerProtectedTo("alice", "bob");
|
||||
expect(view("mallory")).toEqual([]);
|
||||
expect(view("bob")).toEqual(["p1"]);
|
||||
});
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user