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

---

type: contract summary: The API @ng-helpers/indexing exposes to an application — creating an index, depositing references into it, reading it back; curating is not on it: it is what an index's inbox being processed does

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 one a reference to an object (open to anyone), and reading the entries back in order. Resolving those references and adding what can be added is covered too, but never as a call: it is what happens when the index's inbox is processed.

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, anywhere — an engagement, not 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;
• await indexing(port) once at startup and keep what it produces. That handle is one identity's and is also that identity's connection: awaiting it is what curates, dropping it is what stops;
• reach a broker, since every operation here is a document read, a document write or an inbox deposit;
• supply @ng-eventually/polyfill itself. This package declares it a peer: the application names it among its own dependencies, and that copy must be the one its own code calls — that package requires exactly one instance of itself in an application, for reasons its own contract states;
• hardcode the index's NURI in its own source, and be the creator's own application if the index is ever to fill. One requirement, not two: nothing marks a document as an index, so the reference an application carries is the only way anyone reaches it, and its creator's connections are the only thing that curates it. An index nobody hardcodes is unreachable; one whose creator never comes back stays as it was, however many references it is handed.

One handle is one identity: the port carries a session, no call takes an identifier, and two users mean two handles.

Obtaining it. Not published to npm or any other host, and not built output: the entry point is TypeScript source, so whatever builds the application compiles it. @ng-eventually/polyfill arrives the same way. What this contract fixes is the version you pin and what you must provide alongside it.

Surface

Full typed shape: the package's types entry, @ng-helpers/indexing. The load-bearing signatures:

// ── wiring: one handle, one identity, and that identity's connection ─────────
export function polyfillPort(options: PolyfillPortOptions): NextGraphPort;
export interface PolyfillPortOptions { readonly sessionId: string | number }
/** Produces this identity's handle — and before resolving, goes through the inbox of
 *  every index it owns, leaving each watched for as long as the handle lives. */
export function indexing(port: NextGraphPort): Promise<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 };

// ── the three acts an application performs ───────────────────────────────────
export interface Indexing {
  /** Produces a new index in THIS identity's public store, its inbox open, and the NURI
   *  to hardcode. Any user may. `field` is the predicate an indexed object must carry,
   *  declared once and for good; an empty or blank one throws. */
  createIndex(field: string): Promise<Nuri>;
  /** Deposits a bare reference into the index's inbox. Open to ANYONE. Produces nothing:
   *  no receipt, and no inbox address is ever handed out. Throws if there is no inbox. */
  refer(index: NuriLike, object: NuriLike): Promise<void>;
  /** Produces the entries, ordered by value. Refuses a document that declares no index
   *  field rather than producing an empty list. Sugar over `readUnion([index])`. */
  read(index: NuriLike): Promise<IndexEntry[]>;
}

// ── what an index holds, and what travels from a depositor to a curator ──────
export interface IndexEntry { readonly object: Nuri; readonly value: string }
export interface IndexDescriptor { readonly field: string }
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.

What becomes of what was created: the index is curated at its creator's next connection, and on each deposit while the creator is connected. Awaiting indexing(port) is that connection — it goes through the inbox of every index the identity owns, backlog and all, and leaves each watched, so a deposit made from then on is applied as it lands. There is nothing to call, schedule or configure, and no way to aim curating at one index. Only the owner could anyway: nobody else reads that inbox, and nobody else writes that document.

The field is declared once, inside the document, and cannot be changed. createIndex refuses an empty or blank one at the door: nothing here deletes, so an index created on a useless field is useless for good. Declaring it in the document rather than in an application's source stops two applications curating one index on two fields.

createIndex opens the index's inbox itself, and brings the new index under observation. Only the owner can open one, and creation is the one moment the owner is present; and since the search at connection ran before this document existed, what was just created is added to what the session watches.

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. The deposit is a bare reference: no operation, no index reference (the inbox address identifies the index), no copy of the indexed value. What the object itself says is what goes in.

A BET, named as one. That a document can have an inbox is aligned with NextGraph: a repository takes an inbox capability, at most one, driven by a real commit upstream. What a deposit carries, and what processing one does, are ours. Upstream's inbox content type declares Link, Patch and four others as bare names with no payload at all — reserved words, not shapes — and the only two kinds carrying data are unrelated to indexing; that set is closed, with no trait, table of handlers or hook. An index deposit therefore has a shape NextGraph has not defined. When upstream defines those variants, this layer moves with them, and a major is how you hear about it.

An index ONLY EVER GROWS. No call removes an entry, for anyone including the owner, and none is planned: this package cannot express a removal at all, and it was deliberately never built rather than left for later. Do not design around a future delete — the only answer to "this entry must go" is a fresh index.

Curating is convergent and order-independent. Deposits are never retired, so every run reads every deposit ever made to that index — linear in its history — and re-applying one lands on the same result; an already-indexed object is passed over. Neither the order references arrived in nor the number of notifications a burst produced changes anything: runs on one index never overlap, and an arrival during a run earns exactly one more run after it.

None of this can deny you anything. A session that could not read its public store, watch an index, or go through one still hands you a working handle: reading an index and depositing into one never depended on that work. Every such failure is on this package's log stream, and so is every reference that could not be resolved — harmless is not the same as invisible. Nothing is lost either way: the deposits stay in their inbox for the next notification or connection.

Reading is per-entry tolerant. read returns entries ordered by value, ties broken on the object NURI, so two readers always see the same order. Values are compared as strings — an index whose field holds ISO-8601 dates comes out in chronological order. A subject that is not a NURI is passed over rather than 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 runs racing each other can produce, and which keeps the entry visible with every reader agreeing on it.

The document's own declaration is read strictly for curating and leniently for reading. 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 it is malformed. An index declaring SEVERAL fields stops being curated, loudly and permanently, and stays readable: picking one would leave a single list ordered by two properties, since entries already written are never re-read. That cannot be undone — curate into a fresh index.

Reading needs nothing from this package. An application that knows the NURI can call the polyfill's readUnion([index]) and get one subject 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 that reader.

Every inbox payload is untrusted. Anyone may deposit anything; decodeReference returns null for whatever is not a reference, and such a payload is passed over rather than crashing the run.

Non-guarantees

Nothing reports curating to you. No report, no outcome list, no callback: an application that cannot ask for it has nowhere to receive the result. A reference that could not be resolved is warned about on the log stream; an object carrying nothing for the field, one carrying several values, a self-reference and a payload that is not a reference are not reported at all. Reading the index is how you find out.

No timing. A deposit is in the index once its creator's session has been through that inbox; nothing says how long that takes or lets you wait, and if the creator is not connected it waits for as long as that lasts. There is no queue depth and no ordering between a deposit and a read.

No refresh. An already-indexed object is never re-read, so one whose value changes later keeps its original indefinitely.

No private data. Only objects the curator can open itself are indexed; one the owner cannot read is not added.

A handle is one identity for its whole life, and nothing detaches the inboxes it watches. An application that changes identity within one page must build a new handle and drop the old one, which goes on watching under a session that holds nothing.

Connecting reads this identity's whole public store — a store read plus one read per document, every time a handle is built, because nothing marks a document as an index. An index whose read did not answer in that moment is not found, silently, and is curated at the next connection instead.

The narrow behaviours are open questions, not promises. An object carrying nothing for the field is not added; one carrying several values is not added; a raced entry keeps the smallest value. Each is implemented in its narrowest form rather than generalised, and each may change.

No stable error text. What a throw or a log line reads is for a human. Do not parse it or branch on it.

No cross-broker reach. A NURI resolves for users of one broker.

No depositor authentication or rate limit. Anyone may deposit any number of payloads into any inbox.

Change policy

Semver, and majors are the normal case. This layer sits on a polyfill itself converging on a NextGraph that does not ship yet, several of its behaviours are open questions above, and one part of it is a bet. Settling any of those narrows this surface, so the major number moves often — that frequency is the honest signal about this package, not an apology.

• major — an exported symbol is removed or renamed, or an existing call narrows: it throws where it returned, or reports a state you did not have to handle before. Settling an open question counts, and so does anything the bet forces. 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 under ## Guarantees, throw text included.

A tag says where it comes from. A release cut on main carries a full version (2.0.0); work on a branch carries a pre-release of the version it heads for (2.1.0-dev.3), which sorts below it by construction, and between two pre-releases of the same version nothing is promised. Nothing you pinned is ever withdrawn: a pre-release keeps resolving once the full version appears alongside it. The tag is bare — v2.0.0 — because this repository publishes exactly one engagement; should a second ever ship here, tags take the package name from then on (indexing/v…).

2.0.0 took the curating call off this surface, and made obtaining a handle asynchronous. Indexing.curate(index) is gone, and with it CurationReport, CurationOutcome and SkipReason, which nothing published produces any more; indexing(port) now returns a promise, because obtaining a handle is what goes through this identity's inboxes and a caller has to be able to await it. Both are removals under the rule above, hence the major. The reason is not tidiness: a published curate(index) asked every application to decide who owns an index and when curating runs, and neither is an application's decision — the owner is the only one who can, and "when" is "whenever a deposit arrives, or has been waiting". Migrating: delete every call to curate, and await the indexing(port) you already make. If you read CurationReport for what happened, read the index instead, and the log for what did not resolve.

1.0.1 and 1.0.0 keep resolving and neither is forced to upgrade, 1.0.0 having been uninstallable from anywhere but one working copy. This engagement is cut on main, so 2.0.0 is what you pin, and your usage_ leaf anchors against: on that exact string — against: @ng-helpers/indexing@2.0.0.

There is no changelog file and no deprecation window: the sections above are the release note. Diff this leaf between two pulls, ## Guarantees and ## Non-guarantees before ## Surface, because that is where a narrowing shows up first.