docs: l'engagement de la couche d'indexation, et ses deux déclarations

Le dépôt gagne sa doctrine et ses contrats, dans le régime bidirectionnel.

Il publie son engagement — ce qu'un consommateur peut attendre de l'indexation —
et déclare ce qu'il consomme lui-même, du polyfill et de ng-e2e-helpers. Les
deux déclarations sont écrites depuis les appels réels, pas depuis ce que la
surface offre : un usage non déclaré est la faute du consommateur en cas de
rupture, et une surface offerte mais non déclarée reste librement modifiable.

Version 1.0.0, pas 0.1.0 : sous semver, 0.x ne promet rien du tout, donc le
majeur ne porte son signal qu'à partir de 1. Ce dépôt étant sur main, c'est une
version pleine et non une pré-version.

.gitignore

@@ -4,3 +4,8 @@ dist/
 .DS_Store
 bun.lockb
 bun.lock
+e2e/.dist/
+*.ngw
+
+# Per-developer contract access map — canonical identities are committed, local paths are not
+.project/contracts.local.yaml

.project/VOCABULARY.md

@@ -0,0 +1,11 @@
+<!-- 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
+  «indexing»
+   `index`     an ordinary public document that holds one entry per indexed object, plus its own field declaration    (never: catalogue, registry, listing)
+   `deposit`   a bare object reference left in an index document's inbox — open to anyone, and never an instruction   (never: message, submission, request)
+   `curate`    the owner resolving the references deposited on its index and adding what it can                       (never: process, ingest, sync)
+   `entry`     what an index holds for one indexed object — its NURI and its value for the index's field              (never: row, record, item)
+```

.project/concepts/indexing/_overview.md

@@ -0,0 +1,42 @@
+---
+type: overview
+summary: An index is an ordinary public document that only ever grows — what this repo publishes to applications, and what it consumes from NextGraph
+triggers:
+  keywords: [index, indexing, curate, curation, deposit, depositor, entry, descriptor, reference, only-grows]
+  paths:
+    - "src/**"
+    - "test/**"
+    - "e2e/**"
+    - "README.md"
+vocabulary:
+  - term: index
+    gloss: an ordinary public document that holds one entry per indexed object, plus its own field declaration
+    not: [catalogue, registry, listing]
+  - term: deposit
+    gloss: a bare object reference left in an index document's inbox — open to anyone, and never an instruction
+    not: [message, submission, request]
+  - term: curate
+    gloss: the owner resolving the references deposited on its index and adding what it can
+    not: [process, ingest, sync]
+  - term: entry
+    gloss: what an index holds for one indexed object — its NURI and its value for the index's field
+    not: [row, record, item]
+---
+
+# indexing — an index built on top of NextGraph, and the boundaries around it
+
+NextGraph has no indexing concept and will not grow one, so this is a construction **above** it, in its own repository, and the dependency runs one way only: this repo depends on `@ng-eventually/polyfill`, and the polyfill must never learn anything about indexing.
+
+An index is an **ordinary document** in its creator's public store. What makes it an index is that an application references its NURI in its own source. Anyone may hand it a reference by depositing into its inbox; its owner resolves those references itself and adds what it finds. **An index only ever grows** — no removal was ever built, and none is planned.
+
+## Roles at the repository boundary
+
+This repo is a **provider** of `indexing-layer`, which the Festipod application consumes, and a **consumer** of two engagements published by `ng-eventually-js`: `polyfill-surface` and `ng-e2e-helpers`. Each pair lives in its own interface folder: the engagement is pulled and never hand-edited, our declaration beside it is ours to keep current.
+
+Frictions are the main path for telling a provider what we need. They go in our `usage_` leaf, the signal goes out of band, and the entry is pruned once the engagement absorbs it.
+
+## Read first
+
+- `indexing-layer/contract_indexing-layer` — what an application may rely on from `@ng-helpers/indexing`.
+- `polyfill-surface/usage_ng-helpers` — the exact polyfill entries this layer stands on, and what it had to build for want of them.
+- `ng-e2e-helpers/usage_ng-helpers` — what our end-to-end suite calls, and the peer-dependency constraint it must respect.

.project/concepts/indexing/indexing-layer/contract_indexing-layer.md

@@ -0,0 +1,146 @@
+---
+type: contract
+summary: The API @ng-helpers/indexing exposes to an application — creating an index, depositing references into it, curating it, and reading it back
+---
+
+# contract_indexing-layer — `@ng-helpers/indexing`
+
+## Scope
+
+This package builds an **index** on top of NextGraph: an ordinary public document that holds one entry per indexed object, keyed by that object's NURI and carrying its value for a single declared field.
+
+It covers creating an index, handing an index a reference to an object (open to anyone), the owner resolving those references and adding what it can, and reading the entries back in order.
+
+It does not cover NextGraph itself — documents, identity, sharing, inboxes, transport — all of which reach it through a port you supply. It does not cover search, filtering, pagination, or querying by anything but the index's own field. It **never removes anything**, from anywhere, and that is a property of the engagement rather than a missing feature.
+
+### Deployment requirements
+
+An application using this package must:
+
+- have a NextGraph session already open under the identity it wants to act as, and build the port from it — `polyfillPort({ sessionId })`, where `sessionId` is what `@ng-eventually/polyfill`'s own `init(…)` hands its callback;
+- reach a broker, since every operation here is a document read, a document write, or an inbox deposit;
+- **hardcode the index's NURI in its own source.** Nothing marks a document as an index; the reference is what makes it one, and it is the only way anyone reaches it.
+
+One handle is one identity: the port carries a session and no call takes an identifier. Two users mean two handles.
+
+## Surface
+
+Full typed shape: the package's `types` entry, `@ng-helpers/indexing`. The load-bearing signatures:
+
+```ts
+// ── wiring: one handle, one identity ─────────────────────────────────────────
+export function polyfillPort(options: PolyfillPortOptions): NextGraphPort;
+export interface PolyfillPortOptions { readonly sessionId: string | number }
+export function indexing(port: NextGraphPort): Indexing;
+
+// ── addressing (re-exported so you import them from here) ────────────────────
+export type Nuri = `did:ng:${string}`;
+export type NuriLike = Nuri | string;
+export type { PrincipalId, UnionSubject, NextGraphPort, IncomingDeposit, ObjectResolution };
+
+// ── everything this package does ─────────────────────────────────────────────
+export interface Indexing {
+  /** Creates an index in THIS identity's public store and opens its inbox. Any user may.
+   *  `field` is the predicate an indexed object must carry, declared once and for good;
+   *  an empty or blank one throws. Returns the NURI to hardcode. */
+  createIndex(field: string): Promise<Nuri>;
+  /** Deposits a bare reference into the index's inbox. Open to ANYONE. Nothing lands in
+   *  the index until its owner curates. Throws if the index has no inbox. */
+  refer(index: NuriLike, object: NuriLike): Promise<void>;
+  /** OWNER only — resolves the references received and adds what it can. */
+  curate(index: NuriLike): Promise<CurationReport>;
+  /** The entries, ordered by value. Sugar over `readUnion([index])`. */
+  read(index: NuriLike): Promise<IndexEntry[]>;
+}
+
+// ── what an index holds ──────────────────────────────────────────────────────
+export interface IndexEntry { readonly object: Nuri; readonly value: string }
+export interface IndexDescriptor { readonly field: string }
+
+// ── what curating reports ────────────────────────────────────────────────────
+export type CurationOutcome =
+  | { readonly result: "indexed"; readonly object: Nuri; readonly value: string }
+  | { readonly result: "unchanged"; readonly object: Nuri }
+  | { readonly result: "skipped"; readonly object: Nuri; readonly reason: SkipReason }
+  | { readonly result: "unresolved"; readonly object: Nuri; readonly reason: string }
+  | { readonly result: "foreign"; readonly reason: string };
+export type SkipReason = "no-field" | "several-values" | "self-reference";
+export interface CurationReport {
+  readonly index: Nuri;
+  readonly outcomes: readonly CurationOutcome[];   // one per deposit, in deposit order
+}
+
+// ── what travels from a depositor to a curator ───────────────────────────────
+export type IndexDeposit = Nuri;                   // the reference IS the whole payload
+export function decodeReference(payload: unknown): Nuri | null;   // untrusted input
+
+// ── the IRIs, for a reader going straight to `readUnion` ─────────────────────
+export const INDEX_FIELD: string;   // on the index's own subject: the field it indexes by
+export const ENTRY_VALUE: string;   // on an entry: that object's value for the field
+```
+
+## Guarantees
+
+**An index is an ordinary public document, and nothing marks it as one.** It lives in its creator's public store, so any reader opens it from the reference alone; its creator owns it, and any user may create one.
+
+**The field is declared once, inside the document, and cannot be changed.** `createIndex` refuses an empty or blank field at the door, because nothing here deletes and an index created on a useless field is useless for good. Declaring it in the document rather than in an application's source is what stops two applications curating the same index on two different fields.
+
+**`createIndex` opens the index's inbox itself.** Only the owner can, and creation is the one moment the owner is present, so it is not left to a later call to remember.
+
+**Depositing is open to anyone; writing is the owner's alone.** `refer` is a deposit into the index document's inbox — not a write — so a stranger can contribute to an index they do not own. `curate` reads that inbox and writes the document, and both are refused to anyone but the owner. The deposit is a **bare reference**: it carries no operation, no index reference (the inbox address already identifies the index), and no copy of the indexed value. What the object itself says is what goes in.
+
+**An index ONLY EVER GROWS.** There is no call that removes an entry, for anyone including the owner, and none is planned. This package cannot express a removal at all. The only answer to "this entry must go" is a fresh index.
+
+**Curation is convergent and order-independent.** Deposits are never consumed, so every run sees every deposit again; re-applying one re-resolves the reference and lands on the same result. An already-indexed object is skipped outright as `unchanged`. Nothing depends on the order references arrived in.
+
+**A reference that does not resolve costs nothing and is reported.** It comes back as `unresolved`, nothing is written for it, and nothing already in the index is touched — a later deposit adds it. Every unresolved reference appears in `CurationReport.outcomes`: harmless is not the same as invisible.
+
+**Reading is per-entry tolerant.** `read` returns entries ordered by value, ties broken on the object NURI, so two readers of the same index always see the same order. Values are compared **as strings** — an index whose field holds ISO-8601 dates therefore comes out in chronological order. A subject that is not a NURI is skipped, never thrown on, and only own properties are read: one stray triple cannot make every real entry unreadable.
+
+**An entry carrying several values keeps the smallest, deterministically** — which two curation runs racing each other can produce. The entry stays visible and every reader agrees on it.
+
+**`read` refuses a document that declares no field at all**, rather than answering "an empty index". An unreadable document and an empty one arrive as the same empty result, so an empty answer would be a failure wearing the shape of a fact. Retry before concluding the document is malformed.
+
+**An index declaring SEVERAL fields refuses to CURATE, loudly and permanently — and stays readable.** Picking one would leave a single list ordered by two different properties, because entries already written are never re-read. Existing entries stay visible and correct; nothing new is added. The refusal cannot be undone, and it says so instead of suggesting a retry.
+
+**Reading needs nothing from this package.** An application that knows the NURI can call the polyfill's `readUnion([index])` and get the entries as subjects — one per indexed object, keyed by its NURI — plus the index's own subject declaring its field, which `read` drops. `INDEX_FIELD` and `ENTRY_VALUE` are published for exactly that reader.
+
+**Every inbox payload is untrusted.** Anyone may deposit anything; `decodeReference` returns `null` for everything that is not a reference, and such a payload is reported as `foreign` rather than crashing curation.
+
+## Non-guarantees
+
+**No removal, at any level, ever.** Not an oversight and not "not yet": it was deliberately never built. Do not design around a future delete.
+
+**No refresh.** An already-indexed object is never re-read, so an object whose field value changes later keeps its original value in the index, indefinitely.
+
+**No private data.** Indexing is limited to objects the curator can open itself. An object the index's owner cannot read is simply `unresolved`.
+
+**`unresolved` does not tell you why.** Gone, unreadable, and "the read failed" arrive identically and are deliberately not distinguished. Never read it as "the object does not exist".
+
+**The narrow behaviours are open questions, not promises.** An object carrying nothing for the field is `skipped: "no-field"`; one carrying several values is `skipped: "several-values"`; a raced entry keeps the smallest value. Each is implemented in its narrowest form and reported rather than generalised, and each may change.
+
+**No stable error text.** What a throw or an `unresolved` reason reads is for a human reading a report. Do not parse it or branch on it.
+
+**No timing and no delivery promise.** A deposit is not in the index until the owner curates, and nothing here schedules curation. There is no notification, no queue depth, and no ordering between a deposit and a read.
+
+**The report grows with the inbox.** Since deposits are never retired, `CurationReport.outcomes` has one entry per deposit ever made, not per change.
+
+**No cross-broker reach.** A NURI resolves for users of the same broker.
+
+**No depositor authentication or rate limit.** Anyone may deposit any number of payloads into any index's inbox.
+
+## Change policy
+
+**Semver, and majors are the normal case.** This layer sits on a polyfill that is itself converging on a NextGraph that does not ship yet, and several of its own behaviours are declared above as open questions. Settling one of them narrows this surface — 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, or reports a state you did not have to handle before. Settling an open question counts, and so does adding a `CurationOutcome` variant or a `SkipReason` — an exhaustive `switch` in your code stops being exhaustive. 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 read helper, a new optional option.
+- **patch** — a fix that changes neither the exported surface nor anything above under `## Guarantees`, including the text of a throw, 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.
+
+`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. This engagement is cut on `main`, so `1.0.0` is what you pin, and your `usage_` leaf anchors `against:` on that exact string — `against: @ng-helpers/indexing@1.0.0`. Had you pinned a pre-release, `against:` would carry that string, pre-release suffix included.
+
+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.

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

@@ -0,0 +1,49 @@
+---
+type: usage
+summary: What this repo's end-to-end suite calls from ng-e2e-helpers, the peer-dependency constraint it must respect, and the gaps it fills itself
+against: ng-e2e-helpers@1.0.0-dev.1
+---
+
+# 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 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 our application and the name its runs mint, and nothing else.
+
+## 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`.
+
+**Constants** — `BROKER_ROUND_TRIP_MS`, `NEW_PAGE_MS`.
+
+Everything else the engagement offers is NOT consumed here: the screen inventory and its types, `completeBrokerLogin`, `emptyProfileContext`, `importWalletFile`, `exportWalletBytes`/`exportWalletFile`, `mintWalletBytes`, `mintWalletProfileKeepingContext`, `createWalletInContext`, `newRunProfile`, `isAlive`, `browserLost`, `lossDeclared`, `enclosingBound`, `frameTrouble`, the exported error classes, and the remaining `*_MS` constants. It is safely evolvable as far as this suite is concerned.
+
+## 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 it 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, and a version skew can no longer express itself as a type error in code that is correct.
+
+**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.
+
+**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.
+
+## Frictions
+
+**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 it. 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. Two consumers writing the same three-line helper is the tell that the pair belongs on the engagement.

.project/concepts/indexing/polyfill-surface/usage_ng-helpers.md

@@ -0,0 +1,51 @@
+---
+type: usage
+summary: The seven polyfill entries the indexing layer stands on, the constraints it holds itself to, and what it had to build for want of a published helper
+against: "@ng-eventually/polyfill@1.0.0-dev.1"
+---
+
+# usage_ng-helpers — `@ng-helpers/indexing` on `polyfill-surface`
+
+The consumer is the indexing layer: an index is an ordinary public document, contributions reach it through its inbox, and its owner curates it. NextGraph has no indexing concept, so nothing of what a deposit *means* belongs upstream — the polyfill's inbox stays generic and carries opaque payloads, and this layer decides what they say.
+
+The whole runtime dependency passes through **one file**, the adapter that builds our `NextGraphPort`. Everything else in the package is written against that port, so a change to the engagement breaks exactly one file and nothing else. The types are imported type-only, so they are literally the published ones rather than a copy that can drift.
+
+## Consumed surface
+
+**Placement** — `storeRegistry.createEntityDoc("public")`, for the index document itself; `storeRegistry.openDocumentInbox(doc)`, called once at creation.
+
+**Reading** — `readUnion([doc])` and the type `UnionSubject`. Used both for the index document and for resolving a deposited reference.
+
+**Writing** — `docs.sparqlUpdate(sessionId, update, anchor)`, with the document named ONCE as the anchor so the statement carries no `GRAPH <…>` wrapper. It is the only write this package makes, and it is always an `INSERT DATA` of literal triples.
+
+**Inbox** — `inbox.postToDocument(doc, { payload })` for depositing, `inbox.readForDocument(doc)` for the owner draining it, and the shape of `Deposit` (`from` / `payload` / `ts`), which our `IncomingDeposit` mirrors.
+
+**Types** — `Nuri`, `NuriLike`, `PrincipalId`, `UnionSubject`.
+
+**Bootstrap, in the end-to-end application only** — `configure`, this package's `init` (for the `sessionId` its callback delivers), and `ensureIdentity`.
+
+Everything else on the engagement is offered and NOT consumed: `watchShape`, `useShape`, `subscribeDoc`/`subscribeDocs`, `docs.docCreate`, `docs.sparqlQuery`, `storeRegistry.listMyEntityDocs`/`resolveScopeGraph`/`resolveWriteGraph`, `inbox.share`/`post`/`read`/`readSynced`/`readSyncedForDocument`/`processInbox`/`watch`, `ng`, `initNg`. It is safely evolvable as far as this layer is concerned.
+
+## Constraints
+
+**One port is one identity.** The polyfill's 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 our multi-actor tests honest: a depositor obtains the index NURI the way an application does, never through a shared variable.
+
+**`sessionId` is relayed, never converted.** We carry it at the engagement's own `string | number` and hand it back untouched.
+
+**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`. Our own tests execute that SPARQL against an engine that refuses anything else, so a removal is unrunnable rather than merely undetected. This constrains what we ask of the engagement: we need exactly one write primitive and no more.
+
+**The inbox is opened at creation, from one place.** The engagement disclaims coalescing `openDocumentInbox` across pages, so we never open an index's inbox anywhere but in `createIndex`, under its owner, at the moment the document is created.
+
+**Every payload out of an inbox is untrusted input.** Anyone may deposit anything, so nothing read from a deposit reaches a query before being checked; a non-reference is reported, never thrown on.
+
+**An empty read is never treated as "empty".** Nothing in this layer reads `[]` from `readUnion` as "a valid index that happens to hold nothing" — the descriptor check refuses a document declaring no field, and that refusal aborts curation before a single write.
+
+## Frictions
+
+**The engagement does not say what `readUnion` does with a document it cannot read.** It says what it returns for a document it can, and it says 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. We assume the worst (swallowed, therefore indistinguishable from empty) and code defensively around it. A sentence in `## Guarantees` settling this would replace a guess we are carrying in every read path.
+
+**No published NURI type guard.** `## Guarantees` states plainly that no type guard is published, so this layer carries its own — and it needs one, because a NURI arrives here from an untrusted inbox deposit and must be checked before it can be written between angle brackets. The check we wrote is a guess at what the engagement considers a valid `Nuri`, and a wrong guess is either a rejected legitimate reference or an injected one.
+
+**No published escaping helpers.** The engagement lists no `escapeIri`/`escapeLiteral`, and we compose SPARQL against `docs.sparqlUpdate` — so this package carries its own escaping rather than reach into the provider's internals. That is a security-relevant duplication of something the provider certainly already has: two implementations of the same rule, one of which is not the one the provider tests.
+
+**No published way to write triples above the raw SPARQL primitive.** `docs.sparqlUpdate` is the level we had to align on, which is why the two frictions above exist at all. A published "add these triples to this document" would remove the query composition, the escaping and the NURI validation from this layer in one move.

.project/contracts.yaml

@@ -0,0 +1,35 @@
+# 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 BOTH a provider and a consumer, and the two faces are isolated at document
+# level: `indexing-layer` never mentions what we consume, and our `usage_` leaves never
+# mention what we promise. What backs a published guarantee is internal doctrine.
+#
+#   PROVIDES  indexing-layer  (concepts/indexing/indexing-layer/)
+#             consumer: the Festipod application, in its own repo. It has not declared a
+#             usage leaf, and we do not author one on its behalf — an interface with no
+#             declared consumer simply runs in the one-document mode.
+#
+#   CONSUMES  polyfill-surface and ng-e2e-helpers, both published by `ng-eventually-js`.
+#             We pull each engagement and author the `usage_ng-helpers.md` beside it.
+#
+# `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/`
+  indexing-layer: concepts/indexing/indexing-layer/contract_indexing-layer.md
+
+consume:
+  - contract: polyfill-surface
+    type: git
+    pullFrom: git@gitea.reconnexion.apps.gueraud.net:Reconnexion/ng-eventually.git/.project/concepts/app-contract/polyfill-surface/contract_polyfill-surface.md
+    ref: caps-p1a-and-virtual-user-boundary
+    into: concepts/indexing/polyfill-surface/
+
+  - contract: ng-e2e-helpers
+    type: git
+    pullFrom: git@gitea.reconnexion.apps.gueraud.net:Reconnexion/ng-eventually.git/.project/concepts/e2e-harness/ng-e2e-helpers/contract_ng-e2e-helpers.md
+    ref: caps-p1a-and-virtual-user-boundary
+    into: concepts/indexing/ng-e2e-helpers/

AGENTS.md

@@ -0,0 +1,3 @@
+## Project vocabulary (always loaded)
+
+@.project/VOCABULARY.md

e2e/bridge.ts

@@ -0,0 +1,84 @@
+/**
+ * The contract between the application page and the suite that drives it.
+ *
+ * It is declared ONCE and imported by both sides — `indexing-app.ts` implements it,
+ * `run.ts` calls it — so a method that changes shape breaks the typecheck instead of
+ * failing at run time inside a browser, where the only symptom would be `undefined is
+ * not a function` three minutes into a broker crossing.
+ *
+ * Everything crossing `frame.evaluate` must be structured-cloneable, which is why every
+ * member below takes and returns plain strings, numbers and object literals. A `Nuri` is
+ * a template-literal string type upstream (`did:ng:${string}`), so it crosses as itself;
+ * it is declared `string` here because a value that has been through structured clone
+ * carries no proof of its shape, and pretending otherwise is how an unvalidated string
+ * ends up typed as a reference.
+ */
+
+import type { CurationReport, IndexEntry, UnionSubject } from "../src/index";
+
+/** What the leak probe observed — see `run.ts`'s last journey. */
+export interface BrokenInboxOutcome {
+  /** The message `createIndex` rejected with, or `null` if it did not reject. */
+  readonly rejected: string | null;
+  /** What `createIndex` returned, on the impossible branch where it did not reject. */
+  readonly returned: string | null;
+  /** The documents that appeared in this identity's public store despite the failure. */
+  readonly appeared: readonly string[];
+}
+
+/**
+ * The acts this application can perform — and ONLY acts an application can perform.
+ *
+ * There is no back door onto the library's internals here. The one method that is not
+ * something an application does (`createIndexWithBrokenInbox`) injects a failure and is
+ * named for it, because the alternative — leaving the question unanswered — is worse
+ * than a probe that says what it is.
+ */
+export interface IndexingBridge {
+  /** `connecting` → `ready`, or `failed`. */
+  status(): string;
+  /** Why the boot failed, or `null`. */
+  error(): string | null;
+  /** Who this page signed in as. */
+  whoami(): string;
+  /**
+   * The index this deployment was BUILT to contribute to, read off its own configuration.
+   *
+   * An index is an ordinary document; what makes it an index is that an application
+   * references its NURI in its own source (`src/indexing.ts`). This page is configured
+   * through its URL rather than through a compiled-in constant, which is the same thing
+   * one build step earlier — and it is how the reference reaches a SECOND identity
+   * without the suite handing it over through a variable no application would have.
+   */
+  configuredIndex(): string | null;
+
+  /** Create an index in this identity's public store, indexing by `field`. */
+  createIndex(field: string): Promise<string>;
+  /** Publish a public document carrying one value for one predicate. */
+  publishObject(predicate: string, value: string): Promise<string>;
+  /** Hand the CONFIGURED index a reference to an object. Anyone may. */
+  referConfigured(object: string): Promise<void>;
+  /** Hand a NAMED index a reference — used where no identity boundary is crossed. */
+  referTo(index: string, object: string): Promise<void>;
+  /** Resolve the references this index received and add what can be added. Owner only. */
+  curate(index: string): Promise<CurationReport>;
+  /** The index's entries, ordered by value. */
+  read(index: string): Promise<IndexEntry[]>;
+
+  /** What a document literally holds, straight off `readUnion` — the write-form probe. */
+  readRaw(doc: string): Promise<UnionSubject[]>;
+  /** This identity's public documents. How an owner discovers a document it did not keep. */
+  listPublicDocs(): Promise<string[]>;
+
+  /**
+   * `createIndex` with its inbox step made to fail — everything else real, against the
+   * real broker. Answers whether a half-created index is left behind.
+   */
+  createIndexWithBrokenInbox(field: string): Promise<BrokenInboxOutcome>;
+}
+
+declare global {
+  interface Window {
+    __indexing: IndexingBridge;
+  }
+}

e2e/harness-page.ts

@@ -0,0 +1,86 @@
+/**
+ * What is SPECIFIC to this repository in the end-to-end setup: the page that carries the
+ * application, and the name of the wallet its runs mint.
+ *
+ * Everything generic — the wallet lifecycle, the broker crossing, per-run profiles,
+ * bounds, the report shape, the recognition of the known browser failure modes — lives in
+ * `ng-e2e-helpers` and is used, never reimplemented. That package knows nothing about
+ * this one and must keep knowing nothing about it: it talks about NextGraph itself, so it
+ * outlives both the polyfill and this indexing layer.
+ */
+
+import { execSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  mintWalletProfile,
+  serveOnEphemeralPort,
+  type RunProfile,
+  type WalletCredentials,
+} from "ng-e2e-helpers";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * The throwaway credentials each run mints its own wallet with.
+ *
+ * A NAME, not an identity that survives: every run gets a profile of its own and mints
+ * this wallet into it, so two runs sharing the name share nothing else — which is what
+ * lets this suite run beside another repository's at the same time, against the same
+ * broker, without a lock. The password sits here in the clear because it opens a wallet
+ * that exists for the length of one run and is deleted with the profile holding it.
+ */
+export const WALLET: WalletCredentials = {
+  name: "ng-helpers-e2e",
+  password: "ng-helpers-e2e",
+};
+
+/** This run's physical user, in a profile of its own. */
+export function mintRunWallet(suite: string): Promise<RunProfile> {
+  return mintWalletProfile(suite, WALLET);
+}
+
+/** `bun build` is a local bundle; a minute is already many times what it takes. */
+const BUILD_MS = 60_000;
+
+const ENTRY = path.resolve(here, "indexing-app.ts");
+const BUNDLE_OUT = path.resolve(here, ".dist", "indexing-app.js");
+
+export function buildApp(): void {
+  fs.mkdirSync(path.dirname(BUNDLE_OUT), { recursive: true });
+  execSync(`bun build ${ENTRY} --outfile ${BUNDLE_OUT} --bundle --format=esm`, {
+    stdio: "pipe",
+    cwd: path.resolve(here, ".."),
+    timeout: BUILD_MS,
+  });
+}
+
+/**
+ * Serve the application the way a deployment would.
+ *
+ * An unknown path 404s rather than answering with the page: a catch-all makes a request
+ * for a file nobody serves look like a perfectly good download, and hides exactly the
+ * kind of mistake a served asset can carry.
+ */
+export function serveApp(): Promise<{ url: string; close: () => void }> {
+  const bundle = fs.readFileSync(BUNDLE_OUT, "utf-8");
+  const html =
+    `<!DOCTYPE html><html lang="en"><head><meta charset="utf-8">` +
+    `<title>ng-helpers indexing — e2e</title></head><body>` +
+    `<script type="module" src="/indexing-app.js"></script></body></html>`;
+  return serveOnEphemeralPort((req, res) => {
+    const route = (req.url ?? "/").split("?")[0];
+    if (route === "/indexing-app.js") {
+      res.writeHead(200, { "Content-Type": "application/javascript; charset=utf-8" });
+      res.end(bundle);
+    } else if (route === "/" || route === "/index.html") {
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      res.end(html);
+    } else {
+      res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end("not served");
+    }
+  });
+}

e2e/indexing-app.ts

@@ -0,0 +1,221 @@
+/**
+ * The application the end-to-end suite drives — written the way a consumer of
+ * `@ng-helpers/indexing` writes one, and nothing more.
+ *
+ * ── Why an application and not a bag of library calls ──────────────────────
+ * The 69 unit tests in `test/` run against a fake this repository wrote. They prove the
+ * indexing RULES are consistent; they cannot prove that NextGraph does what the fake
+ * pretends, because the fake is the thing being asked. This page closes that gap by
+ * putting the real broker underneath: it imports `@ng-eventually/polyfill` for real,
+ * crosses the real broker, and calls `indexing(polyfillPort(...))` exactly as an
+ * application would.
+ *
+ * It reaches nothing private. Every import below is a published entry — of the polyfill
+ * (`configure`, `ensureIdentity`, `init`, `readUnion`, `storeRegistry`) or of this
+ * package (`indexing`, `polyfillPort`). If something here is awkward, it is awkward for
+ * every consumer, which is the second reason to write it this way.
+ *
+ * ── The one thing here no application does ─────────────────────────────────
+ * `createIndexWithBrokenInbox` injects a failure into the inbox step of `createIndex`.
+ * That is a probe, it is named for what it is, and it exists because the question it
+ * answers — does a failed `openInbox` leave a document behind? — cannot be reached from
+ * outside: nothing a caller controls makes a real `openDocumentInbox` fail on demand.
+ * Everything around the injection is real, including the broker and the document.
+ */
+
+import {
+  configure,
+  ensureIdentity,
+  init,
+  readUnion,
+  storeRegistry,
+  type Nuri,
+  type UnionSubject,
+} from "@ng-eventually/polyfill";
+import { ng as realNg, init as realInit } from "@ng-org/web";
+
+import { indexing, polyfillPort } from "../src/index";
+import type {
+  CurationReport,
+  IndexEntry,
+  Indexing,
+  NextGraphPort,
+} from "../src/index";
+import type { BrokenInboxOutcome, IndexingBridge } from "./bridge";
+
+// ── bootstrap: the one polyfill-era call, then the SDK-shaped ones ──────────
+//
+// `sharedWallet` is declared because the access gate wants somewhere to point when it
+// has to render, and never used: this suite always enters through the broker's redirect,
+// where the wallet is already open in the run's profile. Nothing is served at that path.
+configure({
+  ng: realNg,
+  useShape: () => undefined, // this application reads through `readUnion`, not the ORM
+  init: realInit,
+  sharedWallet: { fileUrl: "/wallet-never-served.ngw", password: "" },
+});
+
+// The library's `init`, not the injected one: it settles the identity BEFORE handing the
+// page to the broker, so the round-trip leaves with `?ng-id=` in the address it carries.
+// The callback is this application's own business — it keeps the session because
+// `polyfillPort` takes a session id, exactly as the real SDK's primitives do.
+const sessionReady = new Promise<{ session_id: string }>((resolve) => {
+  init(
+    (event: { status: string; session?: { session_id: string } }) => {
+      if (event.status === "loggedin" && event.session) resolve(event.session);
+    },
+    true,
+    [],
+  );
+});
+
+// ── this application's state ───────────────────────────────────────────────
+
+const state: { status: string; error: string | null; who: string } = {
+  status: "connecting",
+  error: null,
+  who: "",
+};
+
+let api: Indexing | null = null;
+let port: NextGraphPort | null = null;
+
+/** The index this deployment contributes to, read off its own configuration. */
+function configuredIndex(): string | null {
+  return new URLSearchParams(window.location.search).get("index");
+}
+
+async function boot(): Promise<void> {
+  // One await, and it covers everything: the identity settles, the connection work runs,
+  // and the identity comes back. The application keeps it only to show it.
+  state.who = await ensureIdentity();
+  const session = await sessionReady;
+  port = polyfillPort({ sessionId: session.session_id });
+  api = indexing(port);
+  state.status = "ready";
+}
+
+void boot().catch((e: unknown) => {
+  state.status = "failed";
+  state.error = String((e as Error)?.message ?? e);
+});
+
+/** The library, once the page is up. Throws with the boot's own reason if it is not. */
+function ready(): Indexing {
+  if (api === null) {
+    throw new Error(`[e2e] the application is not ready (${state.status}): ${state.error ?? "still connecting"}`);
+  }
+  return api;
+}
+
+function readyPort(): NextGraphPort {
+  if (port === null) {
+    throw new Error(`[e2e] the application is not ready (${state.status}): ${state.error ?? "still connecting"}`);
+  }
+  return port;
+}
+
+/**
+ * Wait for a document to appear in this identity's public store.
+ *
+ * A store listing is a read like any other, and a document written a moment ago is not
+ * owed to be in it instantly. Polling is therefore what an owner would actually do, and
+ * it is bounded: an empty answer at the end is evidence, not a hang.
+ */
+async function publicDocsAfter(
+  before: ReadonlySet<string>,
+  budgetMs: number,
+): Promise<readonly string[]> {
+  const deadline = Date.now() + budgetMs;
+  let appeared: readonly string[] = [];
+  for (;;) {
+    const now = await storeRegistry.listMyEntityDocs("public");
+    appeared = now.filter((d) => !before.has(d));
+    if (appeared.length > 0 || Date.now() >= deadline) return appeared;
+    await new Promise((r) => setTimeout(r, 500));
+  }
+}
+
+// ── the acts ───────────────────────────────────────────────────────────────
+
+const bridge: IndexingBridge = {
+  status: () => state.status,
+  error: () => state.error,
+  whoami: () => state.who,
+  configuredIndex,
+
+  async createIndex(field: string): Promise<string> {
+    return ready().createIndex(field);
+  },
+
+  /**
+   * Publish a public document carrying one value for one predicate.
+   *
+   * It goes through the SAME primitive the curator writes an entry with
+   * (`addLiteralProperty`), with the document as its own subject. That makes it the
+   * CONTROL for the write-form question: if this round-trips and an index entry does
+   * not, the difference is the foreign subject and nothing else.
+   */
+  async publishObject(predicate: string, value: string): Promise<string> {
+    const p = readyPort();
+    const doc = await p.createPublicDocument();
+    await p.addLiteralProperty(doc, doc, predicate, value);
+    return doc;
+  },
+
+  async referConfigured(object: string): Promise<void> {
+    const index = configuredIndex();
+    if (index === null) {
+      throw new Error("[e2e] this application was not configured with an index reference");
+    }
+    await ready().refer(index, object);
+  },
+
+  async referTo(index: string, object: string): Promise<void> {
+    await ready().refer(index, object);
+  },
+
+  async curate(index: string): Promise<CurationReport> {
+    return ready().curate(index);
+  },
+
+  async read(index: string): Promise<IndexEntry[]> {
+    return ready().read(index);
+  },
+
+  async readRaw(doc: string): Promise<UnionSubject[]> {
+    return readUnion([doc]);
+  },
+
+  async listPublicDocs(): Promise<string[]> {
+    const docs: Nuri[] = await storeRegistry.listMyEntityDocs("public");
+    return [...docs];
+  },
+
+  async createIndexWithBrokenInbox(field: string): Promise<BrokenInboxOutcome> {
+    const p = readyPort();
+    const before = new Set<string>(await storeRegistry.listMyEntityDocs("public"));
+
+    // Everything real except the inbox step. The failure is injected at the exact moment
+    // the question is about: after the document exists and carries its descriptor, before
+    // anyone can deposit into it.
+    const broken = indexing({
+      ...p,
+      openInbox: async (): Promise<void> => {
+        throw new Error("[e2e] injected: the inbox could not be opened");
+      },
+    });
+
+    let rejected: string | null = null;
+    let returned: string | null = null;
+    try {
+      returned = await broken.createIndex(field);
+    } catch (e: unknown) {
+      rejected = String((e as Error)?.message ?? e);
+    }
+
+    return { rejected, returned, appeared: await publicDocsAfter(before, 15_000) };
+  },
+};
+
+window.__indexing = bridge;

e2e/run.ts

@@ -0,0 +1,630 @@
+/**
+ * `@ng-helpers/indexing` against the REAL broker.
+ *
+ * ── What this suite is for ─────────────────────────────────────────────────
+ * The unit suite proves the indexing rules are consistent with a fake this repository
+ * wrote. It cannot prove NextGraph behaves the way that fake pretends, because the fake
+ * is the very thing in question. Two claims in particular had never met a broker:
+ *
+ *   1. **The write form.** An entry is a triple whose SUBJECT is another document — the
+ *      indexed object — written into the index document's anchored default graph. The
+ *      polyfill's own suites only ever write a document's own subject into itself, so
+ *      nothing had ever asked oxigraph whether a FOREIGN subject survives the round trip.
+ *      `publishObject` here writes the self-subject form with the same primitive, which
+ *      makes it the control: if one round-trips and the other does not, the difference is
+ *      the foreign subject and nothing else.
+ *
+ *   2. **A half-created index.** `createIndex` creates a document, writes its descriptor,
+ *      then opens its inbox. If the last step fails the caller gets an exception and no
+ *      reference — but the document exists. The last journey injects that failure and
+ *      asks the broker what was left behind.
+ *
+ * ── Two identities, and how the index reference reaches the second ─────────
+ * The whole point of an index is that STRANGERS contribute to it. So Bob must reach
+ * Alice's index — and he must reach it the way an application would, not through a
+ * variable in this file. An index is an ordinary document whose NURI an application
+ * references in its own source (`src/indexing.ts`), so Bob's page is CONFIGURED with it,
+ * through its URL: one build step earlier, that is a compiled-in constant. What must
+ * never happen — and does not happen here — is an inbox address crossing the identity
+ * boundary through a channel no deployment has.
+ *
+ * ── Reading a failure ──────────────────────────────────────────────────────
+ * A named deadline, or a message `ng-e2e-helpers` recognises as a browser or frame
+ * failure, is the HOST. A failed check carrying an unexpected value is this code. The
+ * report says which, and the run is repeated rather than anything being loosened.
+ */
+
+import {
+  BROKER_ROUND_TRIP_MS,
+  NEW_PAGE_MS,
+  armSuiteDeadline,
+  browserTrouble,
+  closeContext,
+  closeQuietly,
+  declareSuite,
+  firstLine,
+  launchWatchedContext,
+  measured,
+  newPage,
+  setupBrokerPage,
+  within,
+  type Prerequisite,
+  type RunProfile,
+} from "ng-e2e-helpers";
+
+import { ENTRY_VALUE, INDEX_FIELD } from "../src/index";
+import { WALLET, buildApp, mintRunWallet, serveApp } from "./harness-page";
+
+/**
+ * The browser types, taken from the helpers that RETURN them rather than imported from
+ * `playwright` directly.
+ *
+ * `ng-e2e-helpers` declares Playwright a PEER dependency — the consumer owns the version,
+ * because browser binaries have to match the driver. Its files reach this repository as
+ * symlinks, so TypeScript resolves its `playwright` from where those files really live,
+ * and importing the driver here as well produced two structurally different copies of
+ * `BrowserContext`: a context this file had opened could not be handed back to the helper
+ * that opens contexts. Derived, there is exactly one set of these types — whichever copy
+ * the helpers speak — and a version skew can no longer express itself as a type error in
+ * code that is correct.
+ */
+type BrowserContext = Awaited<ReturnType<typeof launchWatchedContext>>;
+type Page = Awaited<ReturnType<typeof newPage>>;
+type Frame = Awaited<ReturnType<typeof setupBrokerPage>>;
+
+// ── the domain this suite indexes by ───────────────────────────────────────
+//
+// A date, so the suite exercises the case the package is built around: an index "by a
+// date" is just an index whose field is a date predicate, and ISO-8601 sorts as a string.
+const PUBLISHED_AT = "urn:ng-helpers-e2e:published-at";
+/** A predicate an index does NOT curate on — for the object that carries nothing usable. */
+const UNRELATED = "urn:ng-helpers-e2e:unrelated";
+
+// ── bounds ─────────────────────────────────────────────────────────────────
+//
+// Sized to be generous rather than tight. A bound exists to turn a hang into a named
+// failure; sized to the median it would instead fail on a slow-but-healthy broker, which
+// is the one thing it must never do. The wall clocks of the three reported runs are the
+// measurement these should be re-sized from.
+
+/** The bridge appearing on the page — a bundle evaluating, no broker involved. */
+const BRIDGE_UP_MS = 60_000;
+/** `ensureIdentity` + the session: an identity settled and the connection work run. */
+const READY_MS = 180_000;
+/** One sign-in: a page, the broker round trip, and the application booting behind it. */
+const SIGN_IN_MS = NEW_PAGE_MS + BROKER_ROUND_TRIP_MS + READY_MS;
+/** One call across the bridge. The slowest here are curations, which round-trip per deposit. */
+const BRIDGE_MS = 4 * 60_000;
+/** One journey. The longest holds two sign-ins' worth of work behind it. */
+const JOURNEY_MS = 10 * 60_000;
+/** The whole run. A budget that cannot interrupt anything is not a budget. */
+const SUITE_MS = 30 * 60_000;
+
+// ── the report ─────────────────────────────────────────────────────────────
+
+let actors: BrowserContext | null = null;
+
+const { check, journey, finish } = declareSuite({
+  label: "ng-helpers indexing e2e",
+  journeyBound: JOURNEY_MS,
+  diagnose: async () => (actors === null ? null : browserTrouble("actors", actors)),
+  journeys: [
+    {
+      name: "Alice signs in and creates an index",
+      checks: [
+        "Alice signs in and the application knows who she is",
+        "creating an index answers with a document reference",
+        "the index document declares the field it indexes by",
+      ],
+    },
+    {
+      name: "Bob signs in configured with Alice's index, and publishes an object",
+      checks: [
+        "Bob signs in, configured with the index his application contributes to",
+        "Bob publishes a public object carrying the indexed field",
+        "Bob's object reads back carrying the value he wrote",
+      ],
+    },
+    {
+      name: "Bob hands the index a reference, and Alice curates it",
+      checks: [
+        "a stranger's deposit into the index's inbox is accepted",
+        "curation reports Bob's object as indexed",
+        "the indexed value was read off Bob's object, and never travelled in his deposit",
+        "the entry is stored under Bob's object's own reference as its subject",
+      ],
+    },
+    {
+      name: "The index reads back, for its owner and for a stranger",
+      checks: [
+        "Alice reads exactly one entry, and it is Bob's object",
+        "Bob, who does not own the index, reads the same entry",
+        "curating a second time changes nothing, and the index still holds one entry",
+      ],
+    },
+    {
+      name: "An object carrying nothing for the field is not indexed",
+      checks: [
+        "curation reports it skipped for want of the field, rather than indexed",
+        "the index still holds exactly one entry",
+      ],
+    },
+    {
+      name: "An index whose inbox cannot be opened leaves a document behind",
+      checks: [
+        "createIndex refuses when the inbox cannot be opened",
+        "a document was nevertheless created in the owner's public store",
+        "the leaked document carries a descriptor but accepts no deposit",
+      ],
+    },
+    {
+      name: "A hostile value crosses the round trip as one inert literal",
+      checks: [
+        "the object reads back the hostile value byte for byte",
+        "the index holds it as one entry, and its own descriptor is untouched",
+      ],
+    },
+  ],
+});
+
+/** A named step that is both measured and bounded — `evaluate` carries no timeout of its own. */
+function step<T>(what: string, ms: number, task: () => Promise<T>): Promise<T> {
+  return measured(what, ms, (bound) => within(what, bound, task));
+}
+
+// ── an actor ───────────────────────────────────────────────────────────────
+
+interface Actor {
+  readonly id: string;
+  readonly frame: Frame;
+  readonly page: Page;
+}
+
+/**
+ * Sign an actor in, and wait for its application to be up.
+ *
+ * `?ng-id=` is the one channel that survives the broker round trip (the access gate's
+ * resolution order). `index` rides the same query string when the actor's deployment is
+ * built to contribute to one.
+ */
+async function signIn(
+  ctx: BrowserContext,
+  appUrl: string,
+  id: string,
+  index: string | null,
+): Promise<Actor> {
+  const opened: { page: Page | null } = { page: null };
+  const query =
+    `?ng-id=${encodeURIComponent(id)}` +
+    (index === null ? "" : `&index=${encodeURIComponent(index)}`);
+  try {
+    return await measured(`${id}'s sign-in`, SIGN_IN_MS, (bound) =>
+      within(`${id} to sign in`, bound, async () => {
+        const page = await measured(`a page for ${id}`, NEW_PAGE_MS, () => newPage(id, ctx));
+        opened.page = page;
+        page.on("pageerror", (e) => console.error(`[${id} pageerror]`, e.message));
+        page.on("console", (m) => {
+          if (m.type() === "error") console.error(`[${id} console]`, m.text());
+        });
+        const frame = await measured(`${id}'s broker round trip`, BROKER_ROUND_TRIP_MS, () =>
+          setupBrokerPage(page, `${appUrl}/${query}`, WALLET.password),
+        );
+        await waitReady(id, frame);
+        return { id, frame, page };
+      }),
+    );
+  } catch (e) {
+    if (opened.page !== null) {
+      await closeQuietly(`${id}'s abandoned sign-in page`, () => opened.page!.close());
+    }
+    throw e;
+  }
+}
+
+/** Wait for the application to be up, and say why with ITS reason when it is not. */
+async function waitReady(id: string, frame: Frame): Promise<void> {
+  await step(`${id}'s application bundle`, BRIDGE_UP_MS, () =>
+    frame.waitForFunction(() => window.__indexing !== undefined, undefined, {
+      timeout: BRIDGE_UP_MS,
+    }),
+  );
+  await step(`${id}'s identity and session`, READY_MS, () =>
+    frame.waitForFunction(() => window.__indexing.status() !== "connecting", undefined, {
+      timeout: READY_MS,
+    }),
+  );
+  const status = await frame.evaluate(() => window.__indexing.status());
+  if (status !== "ready") {
+    const why = await frame.evaluate(() => window.__indexing.error());
+    throw new Error(`[e2e] ${id}'s application did not start (${status}): ${why ?? "no reason given"}`);
+  }
+}
+
+/**
+ * A journey cannot start without the actor it drives — reported as that, not discovered
+ * as a timeout on an innocent call.
+ *
+ * It takes a THUNK, not the actor: read eagerly, the value would be captured as it was
+ * before any sign-in happened, and every journey would report an actor that is standing
+ * right there as missing.
+ */
+function actorIsUp(id: string, actor: () => Actor | null): Prerequisite {
+  return () => (actor() === null ? `${id} never signed in` : null);
+}
+
+// ── the run ────────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  armSuiteDeadline("ng-helpers indexing e2e", SUITE_MS, () =>
+    finish("the suite exceeded its wall clock"),
+  );
+
+  console.log("[e2e] building the application...");
+  buildApp();
+
+  // This run's own physical user, in a directory of its own — so another repository's
+  // suite can drive the same broker at the same time without either noticing.
+  console.log("[e2e] minting this run's wallet...");
+  const wallet: RunProfile = await mintRunWallet("the indexing suite (e2e/run.ts)");
+
+  const stamp = Date.now().toString(36);
+  const ALICE = `alice-${stamp}`;
+  const BOB = `bob-${stamp}`;
+
+  let ctx: BrowserContext | null = null;
+  let closeServer: (() => void) | null = null;
+
+  try {
+    const served = await serveApp();
+    closeServer = served.close;
+    console.log(`[e2e] application served at ${served.url}`);
+
+    ctx = await launchWatchedContext("actors", wallet.dir);
+    actors = ctx;
+
+    let alice: Actor | null = null;
+    let bob: Actor | null = null;
+    let index: string | null = null;
+    let bobsObject: string | null = null;
+
+    const aliceIsUp = actorIsUp(ALICE, () => alice);
+    const bobIsUp = actorIsUp(BOB, () => bob);
+    const indexExists: Prerequisite = () =>
+      index === null ? "Alice never created an index" : null;
+
+    await journey({
+      name: "Alice signs in and creates an index",
+      run: async () => {
+        alice = await signIn(ctx!, served.url, ALICE, null);
+        const who = await alice.frame.evaluate(() => window.__indexing.whoami());
+        check("Alice signs in and the application knows who she is", who.length > 0, `who=${who}`);
+
+        index = await step("Alice creating an index", BRIDGE_MS, () =>
+          alice!.frame.evaluate((f) => window.__indexing.createIndex(f), PUBLISHED_AT),
+        );
+        check(
+          "creating an index answers with a document reference",
+          typeof index === "string" && index.startsWith("did:ng:"),
+          `index=${index}`,
+        );
+
+        // The descriptor's round trip — and the first thing the fake could have been
+        // lying about: the index document is found by an EXACT match on its own NURI as
+        // a subject, so a broker that returns a subject shaped differently breaks every
+        // read of every index.
+        const raw = await step("Alice reading the index document", BRIDGE_MS, () =>
+          alice!.frame.evaluate((d) => window.__indexing.readRaw(d), index!),
+        );
+        const self = raw.find((s) => s.subject === index);
+        const declared = self?.props[INDEX_FIELD] ?? [];
+        check(
+          "the index document declares the field it indexes by",
+          declared.length === 1 && declared[0] === PUBLISHED_AT && self?.graph === index,
+          `subjects=${raw.length} self=${self === undefined ? "(not found)" : "found"} ` +
+            `graph=${self?.graph} declared=${JSON.stringify(declared)}`,
+        );
+      },
+    });
+
+    await journey({
+      name: "Bob signs in configured with Alice's index, and publishes an object",
+      needs: [indexExists],
+      run: async () => {
+        bob = await signIn(ctx!, served.url, BOB, index);
+        const configured = await bob.frame.evaluate(() => window.__indexing.configuredIndex());
+        check(
+          "Bob signs in, configured with the index his application contributes to",
+          configured === index,
+          `configured=${configured}`,
+        );
+
+        bobsObject = await step("Bob publishing an object", BRIDGE_MS, () =>
+          bob!.frame.evaluate(
+            ([p, v]) => window.__indexing.publishObject(p!, v!),
+            [PUBLISHED_AT, "2026-08-17T09:00:00Z"],
+          ),
+        );
+        check(
+          "Bob publishes a public object carrying the indexed field",
+          typeof bobsObject === "string" && bobsObject.startsWith("did:ng:"),
+          `object=${bobsObject}`,
+        );
+
+        // The CONTROL for the write form: the same primitive, the document as its own
+        // subject. This is the shape the polyfill's own suites already exercise.
+        const raw = await step("Bob reading his own object", BRIDGE_MS, () =>
+          bob!.frame.evaluate((d) => window.__indexing.readRaw(d), bobsObject!),
+        );
+        const self = raw.find((s) => s.subject === bobsObject);
+        check(
+          "Bob's object reads back carrying the value he wrote",
+          (self?.props[PUBLISHED_AT] ?? []).includes("2026-08-17T09:00:00Z"),
+          `subjects=${raw.length} props=${JSON.stringify(self?.props ?? {})}`,
+        );
+      },
+    });
+
+    await journey({
+      name: "Bob hands the index a reference, and Alice curates it",
+      needs: [
+        aliceIsUp,
+        bobIsUp,
+        indexExists,
+        () => (bobsObject === null ? "Bob never published an object" : null),
+      ],
+      run: async () => {
+        // Bob names his OWN object, and the index he was configured with. Nothing about
+        // the value travels: the deposit is the reference and nothing else.
+        await step("Bob depositing a reference", BRIDGE_MS, () =>
+          bob!.frame.evaluate((o) => window.__indexing.referConfigured(o), bobsObject!),
+        );
+
+        const report = await step("Alice curating", BRIDGE_MS, () =>
+          alice!.frame.evaluate((i) => window.__indexing.curate(i), index!),
+        );
+        // The deposit is proven ARRIVED, by the only person who can see it. That the post
+        // did not throw is a weaker claim entirely — it says the call returned, not that
+        // anything crossed the identity boundary — and asserting it would be asserting a
+        // constant. Alice reads her own inbox; one outcome means one deposit reached it.
+        check(
+          "a stranger's deposit into the index's inbox is accepted",
+          report.outcomes.length === 1,
+          `from=${BOB} outcomes=${report.outcomes.length}`,
+        );
+        const forBob = report.outcomes.find(
+          (o) => "object" in o && o.object === bobsObject,
+        );
+        check(
+          "curation reports Bob's object as indexed",
+          forBob?.result === "indexed",
+          `outcomes=${JSON.stringify(report.outcomes)}`,
+        );
+        check(
+          "the indexed value was read off Bob's object, and never travelled in his deposit",
+          forBob?.result === "indexed" && forBob.value === "2026-08-17T09:00:00Z",
+          `value=${forBob !== undefined && "value" in forBob ? forBob.value : "(none)"}`,
+        );
+
+        // THE WRITE FORM, answered. An entry is a triple whose subject is another
+        // document, written into this one's anchored default graph. "The write did not
+        // throw" is not the same claim as "oxigraph stored it": this reads it back.
+        const raw = await step("Alice reading the index document back", BRIDGE_MS, () =>
+          alice!.frame.evaluate((d) => window.__indexing.readRaw(d), index!),
+        );
+        const entry = raw.find((s) => s.subject === bobsObject);
+        check(
+          "the entry is stored under Bob's object's own reference as its subject",
+          (entry?.props[ENTRY_VALUE] ?? []).includes("2026-08-17T09:00:00Z"),
+          `subjects=${JSON.stringify(raw.map((s) => s.subject))}`,
+        );
+      },
+    });
+
+    await journey({
+      name: "The index reads back, for its owner and for a stranger",
+      needs: [aliceIsUp, bobIsUp, indexExists],
+      run: async () => {
+        const mine = await step("Alice reading the index", BRIDGE_MS, () =>
+          alice!.frame.evaluate((i) => window.__indexing.read(i), index!),
+        );
+        check(
+          "Alice reads exactly one entry, and it is Bob's object",
+          mine.length === 1 && mine[0]?.object === bobsObject,
+          `entries=${JSON.stringify(mine)}`,
+        );
+
+        // A public index is read by whoever holds its reference — including someone who
+        // owns neither it nor anything in it. This is the act an application performs.
+        const theirs = await step("Bob reading the index he does not own", BRIDGE_MS, () =>
+          bob!.frame.evaluate((i) => window.__indexing.read(i), index!),
+        );
+        check(
+          "Bob, who does not own the index, reads the same entry",
+          theirs.length === 1 && theirs[0]?.object === bobsObject,
+          `entries=${JSON.stringify(theirs)}`,
+        );
+
+        // Deposits are never retired, so every run sees every deposit again. Convergence
+        // is what makes that affordable.
+        const again = await step("Alice curating a second time", BRIDGE_MS, () =>
+          alice!.frame.evaluate((i) => window.__indexing.curate(i), index!),
+        );
+        const still = await step("Alice reading the index again", BRIDGE_MS, () =>
+          alice!.frame.evaluate((i) => window.__indexing.read(i), index!),
+        );
+        check(
+          "curating a second time changes nothing, and the index still holds one entry",
+          again.outcomes.every((o) => o.result === "unchanged") && still.length === 1,
+          `outcomes=${JSON.stringify(again.outcomes)} entries=${still.length}`,
+        );
+      },
+    });
+
+    await journey({
+      name: "An object carrying nothing for the field is not indexed",
+      needs: [aliceIsUp, bobIsUp, indexExists],
+      run: async () => {
+        // PRESENT but carrying nothing for the field — which is a different answer from
+        // an object that cannot be read at all, and the reason this object carries a
+        // predicate rather than being empty: an empty document reads exactly like an
+        // unreadable one, and resolves as `unresolved`, not `skipped`.
+        const other = await step("Bob publishing an unrelated object", BRIDGE_MS, () =>
+          bob!.frame.evaluate(
+            ([p, v]) => window.__indexing.publishObject(p!, v!),
+            [UNRELATED, "nothing to index by"],
+          ),
+        );
+        await step("Bob depositing the unrelated reference", BRIDGE_MS, () =>
+          bob!.frame.evaluate((o) => window.__indexing.referConfigured(o), other),
+        );
+
+        const report = await step("Alice curating the unrelated reference", BRIDGE_MS, () =>
+          alice!.frame.evaluate((i) => window.__indexing.curate(i), index!),
+        );
+        const forOther = report.outcomes.find((o) => "object" in o && o.object === other);
+        check(
+          "curation reports it skipped for want of the field, rather than indexed",
+          forOther?.result === "skipped" && forOther.reason === "no-field",
+          `outcome=${JSON.stringify(forOther)}`,
+        );
+
+        const entries = await step("Alice reading the index once more", BRIDGE_MS, () =>
+          alice!.frame.evaluate((i) => window.__indexing.read(i), index!),
+        );
+        check(
+          "the index still holds exactly one entry",
+          entries.length === 1,
+          `entries=${JSON.stringify(entries)}`,
+        );
+      },
+    });
+
+    await journey({
+      name: "An index whose inbox cannot be opened leaves a document behind",
+      needs: [aliceIsUp],
+      run: async () => {
+        const outcome = await step("Alice creating an index whose inbox fails", BRIDGE_MS, () =>
+          alice!.frame.evaluate(
+            (f) => window.__indexing.createIndexWithBrokenInbox(f),
+            PUBLISHED_AT,
+          ),
+        );
+        check(
+          "createIndex refuses when the inbox cannot be opened",
+          outcome.rejected !== null && outcome.returned === null,
+          `rejected=${outcome.rejected} returned=${outcome.returned}`,
+        );
+        check(
+          "a document was nevertheless created in the owner's public store",
+          outcome.appeared.length === 1,
+          `appeared=${JSON.stringify(outcome.appeared)}`,
+        );
+
+        // What the leaked document IS: an index in every respect but the one that makes
+        // it usable. Alice found it in her own store — the only way anyone can, since
+        // `createIndex` threw its reference away.
+        const leaked = outcome.appeared[0];
+        if (leaked === undefined) {
+          check(
+            "the leaked document carries a descriptor but accepts no deposit",
+            false,
+            "no document appeared, so there was nothing to inspect",
+          );
+          return;
+        }
+        const raw = await step("Alice reading the leaked document", BRIDGE_MS, () =>
+          alice!.frame.evaluate((d) => window.__indexing.readRaw(d), leaked),
+        );
+        const declares = (raw.find((s) => s.subject === leaked)?.props[INDEX_FIELD] ?? []).includes(
+          PUBLISHED_AT,
+        );
+        const refused = await step("Alice trying to deposit into it", BRIDGE_MS, async () => {
+          try {
+            await alice!.frame.evaluate(
+              ([i, o]) => window.__indexing.referTo(i!, o!),
+              [leaked, bobsObject ?? leaked],
+            );
+            return null;
+          } catch (e) {
+            return firstLine(e);
+          }
+        });
+        check(
+          "the leaked document carries a descriptor but accepts no deposit",
+          declares && refused !== null,
+          `declares=${declares} deposit=${refused ?? "(accepted)"}`,
+        );
+      },
+    });
+
+    // LAST, deliberately: if the escaping below turned out not to hold, the damage would
+    // be to this index, and every check above has already been taken.
+    await journey({
+      name: "A hostile value crosses the round trip as one inert literal",
+      needs: [aliceIsUp, bobIsUp, indexExists],
+      run: async () => {
+        // `src/sparql.ts` carries this package's OWN escaping, because the polyfill
+        // publishes none. Until now it had only ever been judged by a fake whose SPARQL
+        // reader was written from the same assumptions — a pair that agrees with itself
+        // proves nothing about oxigraph. This value closes every construct the escaping
+        // is responsible for: the literal's own quote, a backslash, the whitespace
+        // escapes, and a complete injected UPDATE that would empty the index if the
+        // quote ever escaped its literal.
+        const hostile =
+          'a "quoted" part, a \\ backslash, a\nnewline, a\ttab, ' +
+          '" } ; DROP ALL ; INSERT DATA { <urn:ng-helpers-e2e:pwned> <urn:ng-helpers-e2e:pwned> "';
+
+        const object = await step("Bob publishing a hostile value", BRIDGE_MS, () =>
+          bob!.frame.evaluate(
+            ([p, v]) => window.__indexing.publishObject(p!, v!),
+            [PUBLISHED_AT, hostile],
+          ),
+        );
+        const raw = await step("Bob reading the hostile object", BRIDGE_MS, () =>
+          bob!.frame.evaluate((d) => window.__indexing.readRaw(d), object),
+        );
+        const stored = raw.find((s) => s.subject === object)?.props[PUBLISHED_AT] ?? [];
+        check(
+          "the object reads back the hostile value byte for byte",
+          stored.length === 1 && stored[0] === hostile,
+          `stored=${JSON.stringify(stored)}`,
+        );
+
+        await step("Bob depositing the hostile reference", BRIDGE_MS, () =>
+          bob!.frame.evaluate((o) => window.__indexing.referConfigured(o), object),
+        );
+        await step("Alice curating the hostile reference", BRIDGE_MS, () =>
+          alice!.frame.evaluate((i) => window.__indexing.curate(i), index!),
+        );
+
+        // Read the index document RAW: it must still declare its own field. An injected
+        // `DROP ALL` that had taken effect would show up exactly here, as a descriptor
+        // that is no longer there — and `read()` alone could not tell that apart from an
+        // ordinary failure.
+        const after = await step("Alice reading the index after the hostile entry", BRIDGE_MS, () =>
+          alice!.frame.evaluate((d) => window.__indexing.readRaw(d), index!),
+        );
+        const entry = after.find((s) => s.subject === object)?.props[ENTRY_VALUE] ?? [];
+        const descriptor = after.find((s) => s.subject === index)?.props[INDEX_FIELD] ?? [];
+        check(
+          "the index holds it as one entry, and its own descriptor is untouched",
+          entry.length === 1 && entry[0] === hostile && descriptor.includes(PUBLISHED_AT),
+          `entry=${JSON.stringify(entry)} descriptor=${JSON.stringify(descriptor)}`,
+        );
+      },
+    });
+  } finally {
+    if (ctx !== null) await closeContext("actors", ctx);
+    if (closeServer !== null) {
+      await closeQuietly("the application server", async () => closeServer!());
+    }
+    wallet.discard();
+  }
+
+  finish(null);
+}
+
+void main().catch((e: unknown) => {
+  console.error("[e2e] fatal:", (e as Error)?.stack ?? e);
+  finish(firstLine(e));
+});

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ng-helpers/indexing",
-  "version": "0.0.0",
+  "version": "1.0.0",
   "private": true,
   "type": "module",
   "description": "An indexing layer built on top of NextGraph, via @ng-eventually/polyfill. An index is an ordinary public document; contributions reach it through its inbox; its owner curates it.",
@@ -13,11 +13,15 @@
     "@ng-eventually/polyfill": "file:../ng-eventually-js/packages/polyfill"
   },
   "devDependencies": {
+    "@ng-org/web": "0.1.2-alpha.13",
     "@types/bun": "latest",
+    "ng-e2e-helpers": "file:../ng-eventually-js/packages/ng-e2e-helpers",
+    "playwright": "1.61.1",
     "typescript": "^5.6.0"
   },
   "scripts": {
     "test": "bun test",
+    "test:e2e": "bun run e2e/run.ts",
     "typecheck": "bunx tsc --noEmit -p tsconfig.json"
   }
 }

tsconfig.json

@@ -12,5 +12,5 @@
     "isolatedModules": true,
     "noEmit": true
   },
-  "include": ["src", "test"]
+  "include": ["src", "test", "e2e"]
 }