Compare commits
2 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Sylvain Duchesne
|
c2f9ff4674 | ||
|
Sylvain Duchesne
|
ebaae15baf |
@@ -2,8 +2,6 @@ node_modules/
|
||||
dist/
|
||||
*.tsbuildinfo
|
||||
.DS_Store
|
||||
bun.lockb
|
||||
bun.lock
|
||||
e2e/.dist/
|
||||
*.ngw
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
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
|
||||
summary: What @ng-helpers/indexing engages to do — create an index, take a reference anyone deposits, and make it an entry once the index's creator connects; the index itself is an ordinary document anyone queries
|
||||
---
|
||||
|
||||
# contract_indexing-layer — `@ng-helpers/indexing`
|
||||
@@ -9,130 +9,127 @@ summary: The API @ng-helpers/indexing exposes to an application — creating an
|
||||
|
||||
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 covers creating an index and depositing a reference to an object into one (open to anyone). What becomes of that reference is covered too, but never as a call — see `## Guarantees`. Reading is not covered: the document is ordinary, and `## Surface` has the shape to query it.
|
||||
|
||||
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.
|
||||
It does not cover NextGraph itself — documents, identity, sharing, transport, all of which reach it through a port you supply — nor search, filtering, pagination, or querying by anything but the index's field.
|
||||
|
||||
### 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.
|
||||
- have a NextGraph session 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 — no call takes an identifier, so two users mean two handles — and it is also that identity's connection: awaiting it is what makes entries appear, dropping it is what stops them;
|
||||
- reach a broker — nothing here is answered locally;
|
||||
- **supply `@ng-eventually/polyfill` itself**, as 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;
|
||||
- **connect as an index's creator if that index is ever to fill.** Unconditional, whoever holds its reference: an index whose creator never returns 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.
|
||||
**Holding an index's reference.** An index is reached by its NURI, held however the application holds any other reference — per user, per context, or read out of a document it opens anyway. That reference is the only way anyone reaches it, and losing it loses the index. **Hardcoding it is what a single GLOBAL index needs, and only that case**; anything narrower is discovered.
|
||||
|
||||
**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.
|
||||
**Obtaining it.** Not published to npm and not built output: the entry point is TypeScript source, so whatever builds the application compiles it — and `@ng-eventually/polyfill` arrives the same way.
|
||||
|
||||
## Surface
|
||||
|
||||
Full typed shape: the package's `types` entry, `@ng-helpers/indexing`. The load-bearing signatures:
|
||||
Full typed shape: the package's `types` entry. The load-bearing signatures:
|
||||
|
||||
```ts
|
||||
// ── wiring: one handle, one identity, and that identity's connection ─────────
|
||||
// wiring
|
||||
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. */
|
||||
/** This identity's handle, and its connection: see `## Guarantees`. */
|
||||
export function indexing(port: NextGraphPort): Promise<Indexing>;
|
||||
|
||||
// ── addressing (re-exported so you import them from here) ────────────────────
|
||||
// addressing (import these from here)
|
||||
export type Nuri = `did:ng:${string}`;
|
||||
export type NuriLike = Nuri | string;
|
||||
export type { PrincipalId, UnionSubject, NextGraphPort, IncomingDeposit, ObjectResolution };
|
||||
export type { UnionSubject, NextGraphPort, IncomingDeposit, ObjectResolution };
|
||||
|
||||
// ── the three acts an application performs ───────────────────────────────────
|
||||
// the three acts
|
||||
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. */
|
||||
/** A new index in THIS identity's public store, and its NURI. Any user may. `field`
|
||||
* is the predicate an indexed object must carry; 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. */
|
||||
/** Deposits a bare reference to an object into the index. Open to ANYONE. Throws
|
||||
* when the document cannot take one, rather than losing it. */
|
||||
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])`. */
|
||||
/** Convenience: the entries, ordered by value, without the index's own subject.
|
||||
* Refuses a document declaring no field. NOT an engagement — see below. */
|
||||
read(index: NuriLike): Promise<IndexEntry[]>;
|
||||
}
|
||||
|
||||
// ── what an index holds, and what travels from a depositor to a curator ──────
|
||||
// what an index holds, and what a depositor sends
|
||||
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
|
||||
// the IRIs it is written with
|
||||
export const INDEX_FIELD: string; // "urn:ng-helpers:index:field"
|
||||
export const ENTRY_VALUE: string; // "urn:ng-helpers:index:value"
|
||||
```
|
||||
|
||||
**What an index document holds** — two shapes, and this layer writes nothing else:
|
||||
|
||||
- on the **index's own subject**, `INDEX_FIELD` carries the predicate an indexed object must carry, as a **literal**, not a URI;
|
||||
- on **each entry**, whose subject is the indexed object's own `did:ng:` NURI, `ENTRY_VALUE` carries that object's value for the field, as a literal. One subject may carry more than one, which two sessions racing each other produce.
|
||||
|
||||
That is everything reading takes: an anchored `SELECT ?object ?value WHERE { ?object <urn:ng-helpers:index:value> ?value }` returns the entries, for a stranger owning neither the index nor the objects exactly as for its creator; `readUnion([index])` returns the same subjects plus the index's own.
|
||||
|
||||
## 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.
|
||||
**A reference deposited into an index becomes an entry once the index's creator is connected.** Awaiting `indexing(port)` is that connection: across every index that identity owns, what was deposited while it was away becomes an entry then, and what arrives from that moment on becomes one as it lands. Nothing to call, schedule or configure, and no way to aim it at one index — that session serves all of them.
|
||||
|
||||
**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.
|
||||
**The field is declared once, inside the document, and cannot be changed.** `createIndex` refuses an empty or blank one at the door; an index created on a useless field is useless for good. A document that ends up declaring several — which nothing on this surface can do, only a direct write to it — stops gaining entries, loudly and permanently.
|
||||
|
||||
**`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.
|
||||
**A new index is ready the moment `createIndex` produces it** — deposit into it straight away; nothing to open or register.
|
||||
|
||||
**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.
|
||||
**Depositing is open to anyone; writing is the creator's alone.** `refer` is a deposit, so a stranger contributes to an index they could not write. What is deposited is a **bare reference** — no operation, no claim, no copy of the value: what the object itself says, when its entry is made, 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 creator: this package cannot express a removal at all. The answer to "this entry must go" is a fresh index.
|
||||
|
||||
**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.
|
||||
**The same references produce the same index, whatever order they arrived in.** One reference deposited a hundred times leaves one entry, and an object already indexed is passed over rather than read again. The cost: no deposit is ever retired, so the work behind an index is linear in its history.
|
||||
|
||||
**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 find its indexes, catch one up, or stay posted about one still hands you a working handle, and nothing deposited is lost: the next connection makes its entry. Such failures, and every reference that could not be resolved, are on this package's log stream.
|
||||
|
||||
**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.
|
||||
**Everything deposited is untrusted.** Anyone may deposit anything; `decodeReference` returns `null` for whatever is not a reference, and such a payload is passed over rather than stopping the rest.
|
||||
|
||||
## 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.
|
||||
**Reading is not an engagement.** `read` is sugar over the shape above; its ordering, its tie-breaks and what it makes of a subject carrying several values are free to change. The order an index comes out in is the caller's decision — if it matters, query the document and order the result.
|
||||
|
||||
**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.
|
||||
**Nothing tells you what became of a reference, or when.** No report, no callback, nothing to wait on, no ordering between a deposit and a read; while an index's creator stays away, a deposit waits as long as that lasts. A reference that could not be resolved is warned about on the log stream; an object carrying nothing for the field, one carrying several, a self-reference and a payload that is no reference are not reported at all. Reading the index is how you find out.
|
||||
|
||||
**No refresh.** An already-indexed object is never re-read, so one whose value changes later keeps its original indefinitely.
|
||||
**No refresh.** An already-indexed object is never read again, 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.
|
||||
**No private data.** Only objects the index's creator can open are indexed; one it 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.
|
||||
**A handle is one identity for its whole life, and nothing releases what it holds.** An application that changes identity within one page must build a new handle and drop the old one, which goes on listening 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.
|
||||
**Connecting reads this identity's whole public store** — a store read plus one read per document, every time a handle is built. An index whose read did not answer then is not found, silently; its entries are made at the next connection.
|
||||
|
||||
**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.
|
||||
**The narrow behaviours are open questions.** An object carrying nothing for the field is not added; one carrying several values is not added. Each may change.
|
||||
|
||||
**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.
|
||||
**No depositor authentication and no rate limit.** Anyone may deposit any number of payloads into any index.
|
||||
|
||||
**A BET, named as one — this layer's, not yours.** That a document can receive deposits at all is aligned with NextGraph; **what a deposit carries, and what receiving one does, are not** — upstream has defined no such shape and offers no hook to extend the one it has. When it does, this layer moves with it, under a `major`.
|
||||
|
||||
## 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.
|
||||
**Semver, and majors are the normal case.** This layer sits on a polyfill still converging on a NextGraph that does not ship yet; several behaviours above are open questions and one part is a bet, and settling any narrows this surface.
|
||||
|
||||
- **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.
|
||||
- **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 you must react to counts; one that only accepts more 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…`).
|
||||
**A tag says where it comes from.** A release cut on `main` carries a **full version** (`3.0.0`); work on a branch carries a **pre-release** of the version it heads for (`3.1.0-dev.3`), which sorts below it, and between two pre-releases nothing is promised. Nothing you pinned is ever withdrawn. The tag is bare — `v3.0.0`.
|
||||
|
||||
**`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.
|
||||
**`3.0.0` stops engaging on reading, and drops a re-export that never existed.** The guarantees describing what `read` does — ordering, the tie-break on NURI, a subject with several values, a leniently-read declaration — are gone, replaced by the storage shape under `## Surface`. `PrincipalId` leaves it too: listed as re-exported, never exported by `src/index.ts`. **Nothing to migrate and no call behaves differently** — `read` still orders exactly as before. A **major** under the rule above: the surface loses a symbol, and `## Guarantees` loses statements you may no longer rely on.
|
||||
|
||||
`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`.
|
||||
**`2.0.0` removed `Indexing.curate(index)` — and `CurationReport`, `CurationOutcome`, `SkipReason` with it — and made `indexing(port)` a promise.** **Migrating from `1.x`**: delete every call to `curate`, `await` the `indexing(port)` you already make, and where you read a `CurationReport` read the index instead. `2.0.1` was prose and one relaxed deployment requirement; nothing to migrate. `1.0.1` and `1.0.0` keep resolving.
|
||||
|
||||
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.
|
||||
Cut on `main`: pin `3.0.0`, and anchor your `usage_` leaf on `against: @ng-helpers/indexing@3.0.0`.
|
||||
|
||||
**No changelog file and no deprecation window: the sections above are the release note.** Diff `## Guarantees`, `## Non-guarantees` and `## Surface` between two pulls.
|
||||
|
||||
@@ -88,14 +88,18 @@ Deliberately not settled. Each is implemented in its narrowest form and reported
|
||||
|
||||
`@ng-eventually/polyfill`, declared as a **peer** dependency: an application using this package supplies it, so exactly one copy of it exists in that application. That is a requirement of the polyfill itself, which keeps its state in the package — two copies mean two subscription registries and two current identities, and nothing detects it.
|
||||
|
||||
For this repository's own tests and typecheck it is *also* a `devDependency` by local path (`file:../ng-eventually-js/packages/polyfill`), which expects that repository to sit beside this one. A dev dependency is not installed by a consumer, so this local path never reaches one. `ng-e2e-helpers` is a `devDependency` by local path on the same expectation.
|
||||
For this repository's own tests and typecheck it is *also* a `devDependency` by local path (`link:../ng-eventually-js/packages/polyfill`), which expects that repository to sit beside this one. A dev dependency is not installed by a consumer, so this local path never reaches one. `ng-e2e-helpers` is a `devDependency` by local path on the same expectation.
|
||||
|
||||
**`link:`, not `file:`, and pnpm makes that a real difference.** pnpm COPIES a `file:` directory into its virtual store, and a copy is cut off from the sibling checkout's own `node_modules` — the polyfill's optional peers (`@ng-org/shex-orm`, `@ng-org/alien-deepsignals`) stop resolving and the typecheck fails on them. `link:` symlinks the sibling package where it lives, so it keeps its own dependencies and an edit made there is the one this repository tests against.
|
||||
|
||||
## Running it
|
||||
|
||||
```sh
|
||||
npm install # or: pnpm install
|
||||
pnpm install
|
||||
bunx tsc --noEmit -p tsconfig.json
|
||||
bun test
|
||||
```
|
||||
|
||||
**`bun install` does not work in this repository** (checked with bun 1.3.9): bun resolves a mandatory peer dependency against the npm registry whatever local path provides it, and `@ng-eventually/polyfill` is published to no registry, so the install stops on `GET https://registry.npmjs.org/@ng-eventually%2fpolyfill - 404`. `npm install` and `pnpm install` both resolve it from the sibling checkout. `bun test` itself is unaffected — it is only the installer that cannot express this.
|
||||
**pnpm installs; bun runs.** `pnpm-lock.yaml` is the committed lockfile and `pnpm install` is the only install path — the same package manager the sibling `ng-eventually-js` uses. `bun` stays the test runner and `bunx tsc` the typechecker; neither reads a lockfile, so nothing about that changed.
|
||||
|
||||
**`bun install` does not work in this repository** (checked with bun 1.3.9): bun resolves a mandatory peer dependency against the npm registry whatever local path provides it, and `@ng-eventually/polyfill` is published to no registry, so the install stops on `GET https://registry.npmjs.org/@ng-eventually%2fpolyfill - 404`. That is why no `bun.lock` is kept here: bun cannot regenerate one, so the file that was here could only rot. `bun test` itself is unaffected — it is only the installer that cannot express this.
|
||||
|
||||
@@ -26,6 +26,24 @@ export interface BrokenInboxOutcome {
|
||||
readonly appeared: readonly string[];
|
||||
}
|
||||
|
||||
/**
|
||||
* What one anchored SPARQL SELECT answered — or how it failed.
|
||||
*
|
||||
* The three fields are kept apart deliberately. "Nothing came back" and "the call failed"
|
||||
* are different answers, and a shape that folded them together would let a failure read as
|
||||
* an empty index — the defect class this repository keeps finding. `raw` carries the answer
|
||||
* BEFORE anything here decodes it, so a decoder that is wrong about the result's shape
|
||||
* cannot pass its own blindness off as a query that returned nothing.
|
||||
*/
|
||||
export interface SelectOutcome {
|
||||
/** The message the query rejected with, or `null` when it returned. */
|
||||
readonly failed: string | null;
|
||||
/** Whatever came back, rendered as JSON — the answer before any decoding of it. */
|
||||
readonly raw: string;
|
||||
/** The SELECT's bindings, decoded to plain `variable → value` rows. */
|
||||
readonly rows: ReadonlyArray<Readonly<Record<string, string>>>;
|
||||
}
|
||||
|
||||
/**
|
||||
* The acts this application can perform — and ONLY acts an application can perform.
|
||||
*
|
||||
@@ -74,6 +92,15 @@ export interface IndexingBridge {
|
||||
|
||||
/** What a document literally holds, straight off `readUnion` — the write-form probe. */
|
||||
readRaw(doc: string): Promise<UnionSubject[]>;
|
||||
/**
|
||||
* Run a SPARQL SELECT anchored on a document, through `docs.sparqlQuery`.
|
||||
*
|
||||
* An index is claimed to be an ORDINARY document, which means an ordinary query must
|
||||
* reach it. Nothing in `src/` ever issues one — this layer composes SPARQL only to
|
||||
* write — so this is the one act here that no code of this package performs, and it is
|
||||
* on the bridge because the claim had never been measured against a broker.
|
||||
*/
|
||||
select(anchor: string, query: string): Promise<SelectOutcome>;
|
||||
/** This identity's public documents. How an owner discovers a document it did not keep. */
|
||||
listPublicDocs(): Promise<string[]>;
|
||||
|
||||
|
||||
+64
-6
@@ -2,7 +2,7 @@
|
||||
* 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 ──────────────────────
|
||||
* Why an application and not a bag of library calls
|
||||
* The 80 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
|
||||
@@ -15,7 +15,7 @@
|
||||
* 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 ─────────────────────────────────
|
||||
* 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
|
||||
@@ -25,6 +25,7 @@
|
||||
|
||||
import {
|
||||
configure,
|
||||
docs,
|
||||
ensureIdentity,
|
||||
init,
|
||||
readUnion,
|
||||
@@ -36,9 +37,9 @@ import { ng as realNg, init as realInit } from "@ng-org/web";
|
||||
|
||||
import { indexing, polyfillPort } from "../src/index";
|
||||
import type { IndexEntry, Indexing, NextGraphPort } from "../src/index";
|
||||
import type { BrokenInboxOutcome, IndexingBridge } from "./bridge";
|
||||
import type { BrokenInboxOutcome, IndexingBridge, SelectOutcome } from "./bridge";
|
||||
|
||||
// ── bootstrap: the one polyfill-era call, then the SDK-shaped ones ──────────
|
||||
// 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,
|
||||
@@ -64,7 +65,7 @@ const sessionReady = new Promise<{ session_id: string }>((resolve) => {
|
||||
);
|
||||
});
|
||||
|
||||
// ── this application's state ───────────────────────────────────────────────
|
||||
// this application's state
|
||||
|
||||
const state: { status: string; error: string | null; who: string } = {
|
||||
status: "connecting",
|
||||
@@ -134,7 +135,46 @@ async function publicDocsAfter(
|
||||
}
|
||||
}
|
||||
|
||||
// ── the acts ───────────────────────────────────────────────────────────────
|
||||
/**
|
||||
* How much of an answer a report carries. Bounded so a report stays one, generous enough
|
||||
* that the answer is readable rather than merely counted.
|
||||
*/
|
||||
const RAW_LIMIT = 2000;
|
||||
|
||||
/** Whatever came back, as JSON — `undefined` and a value that will not render included,
|
||||
* because both of those are answers too and a report that hides them is worth nothing. */
|
||||
function render(result: unknown): string {
|
||||
let text: string;
|
||||
try {
|
||||
text = JSON.stringify(result) ?? String(result);
|
||||
} catch (e: unknown) {
|
||||
text = `(did not render: ${String((e as Error)?.message ?? e)})`;
|
||||
}
|
||||
return text.length <= RAW_LIMIT ? text : `${text.slice(0, RAW_LIMIT)}…(${text.length} chars)`;
|
||||
}
|
||||
|
||||
/**
|
||||
* The SELECT's bindings, in the shape the SPARQL results JSON specifies — the same
|
||||
* `results.bindings` the polyfill itself reads out of this very call (`surface/inbox.ts`,
|
||||
* `surface/read-model.ts`). A binding whose term carries no string `value` is dropped
|
||||
* rather than guessed at; `raw` beside it is what keeps that honest.
|
||||
*/
|
||||
function rowsOf(result: unknown): Array<Record<string, string>> {
|
||||
if (result === null || typeof result !== "object") return [];
|
||||
const answered = result as {
|
||||
results?: { bindings?: ReadonlyArray<Record<string, { value?: unknown } | undefined>> };
|
||||
};
|
||||
const bindings = answered.results?.bindings ?? [];
|
||||
return bindings.map((binding) => {
|
||||
const row: Record<string, string> = {};
|
||||
for (const [variable, term] of Object.entries(binding)) {
|
||||
if (term !== undefined && typeof term.value === "string") row[variable] = term.value;
|
||||
}
|
||||
return row;
|
||||
});
|
||||
}
|
||||
|
||||
// the acts
|
||||
|
||||
const bridge: IndexingBridge = {
|
||||
status: () => state.status,
|
||||
@@ -185,6 +225,24 @@ const bridge: IndexingBridge = {
|
||||
return readUnion([doc]);
|
||||
},
|
||||
|
||||
/**
|
||||
* A SPARQL SELECT anchored on a document, through the polyfill's published `docs`.
|
||||
*
|
||||
* The session id is the one this application already holds — the same one every write
|
||||
* of this layer is made with. Nothing is caught and rethrown: a rejection is REPORTED,
|
||||
* because "the query failed" is a different answer from "the query found nothing" and
|
||||
* the whole point of this probe is to tell them apart.
|
||||
*/
|
||||
async select(anchor: string, query: string): Promise<SelectOutcome> {
|
||||
const session = await sessionReady;
|
||||
try {
|
||||
const result = await docs.sparqlQuery(session.session_id, query, undefined, anchor);
|
||||
return { failed: null, raw: render(result), rows: rowsOf(result) };
|
||||
} catch (e: unknown) {
|
||||
return { failed: String((e as Error)?.message ?? e), raw: "(the query rejected)", rows: [] };
|
||||
}
|
||||
},
|
||||
|
||||
async listPublicDocs(): Promise<string[]> {
|
||||
const docs: Nuri[] = await storeRegistry.listMyEntityDocs("public");
|
||||
return [...docs];
|
||||
|
||||
+129
-9
@@ -1,7 +1,7 @@
|
||||
/**
|
||||
* `@ng-helpers/indexing` against the REAL broker.
|
||||
*
|
||||
* ── What this suite is for ─────────────────────────────────────────────────
|
||||
* 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:
|
||||
@@ -19,7 +19,7 @@
|
||||
* 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 ─────────
|
||||
* 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
|
||||
@@ -28,7 +28,7 @@
|
||||
* never happen — and does not happen here — is an inbox address crossing the identity
|
||||
* boundary through a channel no deployment has.
|
||||
*
|
||||
* ── Reading a failure ──────────────────────────────────────────────────────
|
||||
* 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.
|
||||
@@ -72,7 +72,7 @@ type BrowserContext = Awaited<ReturnType<typeof launchWatchedContext>>;
|
||||
type Page = Awaited<ReturnType<typeof newPage>>;
|
||||
type Frame = Awaited<ReturnType<typeof setupBrokerPage>>;
|
||||
|
||||
// ── the domain this suite indexes by ───────────────────────────────────────
|
||||
// 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.
|
||||
@@ -80,7 +80,7 @@ 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 ─────────────────────────────────────────────────────────────────
|
||||
// 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
|
||||
@@ -100,7 +100,7 @@ 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 ─────────────────────────────────────────────────────────────
|
||||
// the report
|
||||
|
||||
let actors: BrowserContext | null = null;
|
||||
|
||||
@@ -138,7 +138,7 @@ const { check, journey, finish } = declareSuite({
|
||||
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",
|
||||
"connecting a second time changes nothing, and the index still holds one entry",
|
||||
],
|
||||
},
|
||||
{
|
||||
@@ -162,15 +162,49 @@ const { check, journey, finish } = declareSuite({
|
||||
"the index holds it as one entry, and its own descriptor is untouched",
|
||||
],
|
||||
},
|
||||
{
|
||||
name: "The index answers an ordinary SPARQL query",
|
||||
checks: [
|
||||
"readUnion returns both entries and the index's own declaration",
|
||||
"a SELECT for the entry predicate returns both entries, with their values",
|
||||
"a SELECT of the index's own subject returns the field it declares",
|
||||
"a stranger's SELECT returns the same entries",
|
||||
],
|
||||
},
|
||||
],
|
||||
});
|
||||
|
||||
/**
|
||||
* Two readings of the same entries — the same objects, carrying the same values.
|
||||
*
|
||||
* Compared as a WHOLE: a query that answered with a subset, or with a value that changed
|
||||
* shape crossing the round trip, is not the same answer as the document's own content.
|
||||
*/
|
||||
function sameEntries(a: ReadonlyMap<string, string>, b: ReadonlyMap<string, string>): boolean {
|
||||
if (a.size !== b.size) return false;
|
||||
for (const [object, value] of a) {
|
||||
if (b.get(object) !== value) return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
/** The `?object`/`?value` rows of an entries SELECT, as the entries they claim to be. */
|
||||
function entriesOf(rows: ReadonlyArray<Readonly<Record<string, string>>>): Map<string, string> {
|
||||
const found = new Map<string, string>();
|
||||
for (const row of rows) {
|
||||
const object = row["object"];
|
||||
const value = row["value"];
|
||||
if (object !== undefined && value !== undefined) found.set(object, value);
|
||||
}
|
||||
return found;
|
||||
}
|
||||
|
||||
/** 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 ───────────────────────────────────────────────────────────────
|
||||
// an actor
|
||||
|
||||
interface Actor {
|
||||
readonly id: string;
|
||||
@@ -250,7 +284,7 @@ function actorIsUp(id: string, actor: () => Actor | null): Prerequisite {
|
||||
return () => (actor() === null ? `${id} never signed in` : null);
|
||||
}
|
||||
|
||||
// ── the run ────────────────────────────────────────────────────────────────
|
||||
// the run
|
||||
|
||||
async function main(): Promise<void> {
|
||||
armSuiteDeadline("ng-helpers indexing e2e", SUITE_MS, () =>
|
||||
@@ -602,6 +636,92 @@ async function main(): Promise<void> {
|
||||
);
|
||||
},
|
||||
});
|
||||
|
||||
// AFTER the hostile journey, and read-only: by here the index holds SEVERAL entries,
|
||||
// which is the state the question is about — one entry cannot tell a query that
|
||||
// returns everything from one that returns the first thing it finds.
|
||||
//
|
||||
// WHAT IS BEING ASKED. This package documents one way of reading an index
|
||||
// (`readUnion`) and issues no query of its own, so "an index is an ordinary document
|
||||
// anyone queries normally" has never been anything but plausible. These four checks
|
||||
// are a measurement of that sentence, not a feature: an empty answer is a RESULT and
|
||||
// is reported as one, and a rejection is reported apart from it, because "the query
|
||||
// found nothing" and "the query failed" are the two answers this repository keeps
|
||||
// finding folded into one.
|
||||
await journey({
|
||||
name: "The index answers an ordinary SPARQL query",
|
||||
needs: [aliceIsUp, bobIsUp, indexExists],
|
||||
run: async () => {
|
||||
// The REFERENCE the queries below are judged against. "The SELECT came back with
|
||||
// the entries" is only a claim if something independent says what the entries
|
||||
// are — and it is what makes an empty answer below mean something instead of
|
||||
// being indistinguishable from an index that holds nothing.
|
||||
const raw = await step("Alice reading the index before querying it", BRIDGE_MS, () =>
|
||||
alice!.frame.evaluate((d) => window.__indexing.readRaw(d), index!),
|
||||
);
|
||||
const held = new Map<string, string>();
|
||||
for (const subject of raw) {
|
||||
const value = subject.props[ENTRY_VALUE] ?? [];
|
||||
if (value.length === 1 && value[0] !== undefined) held.set(subject.subject, value[0]);
|
||||
}
|
||||
const declares = (raw.find((s) => s.subject === index)?.props[INDEX_FIELD] ?? []).includes(
|
||||
PUBLISHED_AT,
|
||||
);
|
||||
check(
|
||||
"readUnion returns both entries and the index's own declaration",
|
||||
held.size === 2 && declares,
|
||||
`entries=${JSON.stringify([...held.keys()])} declares=${declares}`,
|
||||
);
|
||||
|
||||
// The shape a reader would write, with nothing of this package in it: the entry
|
||||
// predicate, and the anchored default graph the index document is.
|
||||
const entriesQuery = `SELECT ?object ?value WHERE { ?object <${ENTRY_VALUE}> ?value }`;
|
||||
const mine = await step("Alice querying the index for its entries", BRIDGE_MS, () =>
|
||||
alice!.frame.evaluate(
|
||||
([a, q]) => window.__indexing.select(a!, q!),
|
||||
[index!, entriesQuery],
|
||||
),
|
||||
);
|
||||
const answered = entriesOf(mine.rows);
|
||||
check(
|
||||
"a SELECT for the entry predicate returns both entries, with their values",
|
||||
mine.failed === null && sameEntries(held, answered),
|
||||
`failed=${mine.failed} rows=${mine.rows.length} ` +
|
||||
`objects=${JSON.stringify([...answered.keys()])} raw=${mine.raw}`,
|
||||
);
|
||||
|
||||
// The index document's OWN subject, which is the other half of what an index
|
||||
// holds — and the half a reader needs to know what the values mean.
|
||||
const fieldQuery = `SELECT ?field WHERE { <${index!}> <${INDEX_FIELD}> ?field }`;
|
||||
const declared = await step("Alice querying the index's declaration", BRIDGE_MS, () =>
|
||||
alice!.frame.evaluate(([a, q]) => window.__indexing.select(a!, q!), [index!, fieldQuery]),
|
||||
);
|
||||
check(
|
||||
"a SELECT of the index's own subject returns the field it declares",
|
||||
declared.failed === null &&
|
||||
declared.rows.length === 1 &&
|
||||
declared.rows[0]?.["field"] === PUBLISHED_AT,
|
||||
`failed=${declared.failed} rows=${declared.rows.length} raw=${declared.raw}`,
|
||||
);
|
||||
|
||||
// The reader who matters: an index exists to be read by people who own neither it
|
||||
// nor anything in it. `readUnion` already answers him (the journey above); whether
|
||||
// a query does is a separate question, and it is the one an application asks.
|
||||
const theirs = await step("Bob querying the index he does not own", BRIDGE_MS, () =>
|
||||
bob!.frame.evaluate(
|
||||
([a, q]) => window.__indexing.select(a!, q!),
|
||||
[index!, entriesQuery],
|
||||
),
|
||||
);
|
||||
const strangers = entriesOf(theirs.rows);
|
||||
check(
|
||||
"a stranger's SELECT returns the same entries",
|
||||
theirs.failed === null && sameEntries(held, strangers),
|
||||
`failed=${theirs.failed} rows=${theirs.rows.length} ` +
|
||||
`objects=${JSON.stringify([...strangers.keys()])} raw=${theirs.raw}`,
|
||||
);
|
||||
},
|
||||
});
|
||||
} finally {
|
||||
if (ctx !== null) await closeContext("actors", ctx);
|
||||
if (closeServer !== null) {
|
||||
|
||||
+4
-4
@@ -1,9 +1,9 @@
|
||||
{
|
||||
"name": "@ng-helpers/indexing",
|
||||
"version": "2.0.0",
|
||||
"version": "3.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; processing that inbox is what curates it, and that happens at its creator's connections.",
|
||||
"description": "An indexing layer built on top of NextGraph, via @ng-eventually/polyfill. An index is an ordinary public document; anyone may hand it a reference to an object, and that reference becomes an entry once the index's creator is connected.",
|
||||
"main": "./src/index.ts",
|
||||
"types": "./src/index.ts",
|
||||
"exports": {
|
||||
@@ -13,10 +13,10 @@
|
||||
"@ng-eventually/polyfill": "*"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@ng-eventually/polyfill": "file:../ng-eventually-js/packages/polyfill",
|
||||
"@ng-eventually/polyfill": "link:../ng-eventually-js/packages/polyfill",
|
||||
"@ng-org/web": "0.1.2-alpha.13",
|
||||
"@types/bun": "latest",
|
||||
"ng-e2e-helpers": "file:../ng-eventually-js/packages/ng-e2e-helpers",
|
||||
"ng-e2e-helpers": "link:../ng-eventually-js/packages/ng-e2e-helpers",
|
||||
"playwright": "1.61.1",
|
||||
"typescript": "^5.6.0"
|
||||
},
|
||||
|
||||
Generated
+110
@@ -0,0 +1,110 @@
|
||||
lockfileVersion: '9.0'
|
||||
|
||||
settings:
|
||||
autoInstallPeers: true
|
||||
excludeLinksFromLockfile: false
|
||||
|
||||
importers:
|
||||
|
||||
.:
|
||||
devDependencies:
|
||||
'@ng-eventually/polyfill':
|
||||
specifier: link:../ng-eventually-js/packages/polyfill
|
||||
version: link:../ng-eventually-js/packages/polyfill
|
||||
'@ng-org/web':
|
||||
specifier: 0.1.2-alpha.13
|
||||
version: 0.1.2-alpha.13
|
||||
'@types/bun':
|
||||
specifier: latest
|
||||
version: 1.3.14
|
||||
ng-e2e-helpers:
|
||||
specifier: link:../ng-eventually-js/packages/ng-e2e-helpers
|
||||
version: link:../ng-eventually-js/packages/ng-e2e-helpers
|
||||
playwright:
|
||||
specifier: 1.61.1
|
||||
version: 1.61.1
|
||||
typescript:
|
||||
specifier: ^5.6.0
|
||||
version: 5.9.3
|
||||
|
||||
packages:
|
||||
|
||||
'@ng-org/web@0.1.2-alpha.13':
|
||||
resolution: {integrity: sha512-/xO0c+3NTphnws5Do2LDqgZWmAf+aNnYdChJKdU0dnp1U1iVSgi/y3yb8AYryf0v9sooj0aYJxt08B6DpirFMQ==}
|
||||
|
||||
'@types/bun@1.3.14':
|
||||
resolution: {integrity: sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw==}
|
||||
|
||||
'@types/node@26.2.0':
|
||||
resolution: {integrity: sha512-5IviulTZeRNp2vAJ514cc/HUlY5nZ9fCbq9DMyC52BrhFZACo3nI0R7qBxhQmo/d27NFe96ur/b7Wwxklda+kg==}
|
||||
|
||||
async-proxy@0.4.1:
|
||||
resolution: {integrity: sha512-4e+zNtoGL4+cnqib8v169CnKcRfAsAubp2EsjBhAA5jyW7jjI3t36rVvuqLwmhtliwf8JvSnxinE4ecQN+DK4w==}
|
||||
|
||||
bun-types@1.3.14:
|
||||
resolution: {integrity: sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ==}
|
||||
|
||||
fsevents@2.3.2:
|
||||
resolution: {integrity: sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==}
|
||||
engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
|
||||
os: [darwin]
|
||||
|
||||
object-path-operator@3.0.0:
|
||||
resolution: {integrity: sha512-Z7dlPUeXqRU/lLfGerP24dPC66n7ehyXaTM81k71EFlsaaEjOHkf4/uq1WGicfGfiO7snYShneE1YZZUkyRiLQ==}
|
||||
|
||||
playwright-core@1.61.1:
|
||||
resolution: {integrity: sha512-h7Qlt6m4REp25qvIdvbDtVmD4LqVXfpRxhORv9L0jzETM05p4fuPJ3dKyuSXQxDSbXnmS79HAgi9589lGSpLkg==}
|
||||
engines: {node: '>=18'}
|
||||
hasBin: true
|
||||
|
||||
playwright@1.61.1:
|
||||
resolution: {integrity: sha512-DWnY5o3YbLWK4GovuAVwpqL+1VwGNdUGrRr++8j8PtQQzvAVZUIMjKQ90fY689sEJZJBbZVw1rXaOKSTitkzPQ==}
|
||||
engines: {node: '>=18'}
|
||||
hasBin: true
|
||||
|
||||
typescript@5.9.3:
|
||||
resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
|
||||
engines: {node: '>=14.17'}
|
||||
hasBin: true
|
||||
|
||||
undici-types@8.3.0:
|
||||
resolution: {integrity: sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ==}
|
||||
|
||||
snapshots:
|
||||
|
||||
'@ng-org/web@0.1.2-alpha.13':
|
||||
dependencies:
|
||||
async-proxy: 0.4.1
|
||||
|
||||
'@types/bun@1.3.14':
|
||||
dependencies:
|
||||
bun-types: 1.3.14
|
||||
|
||||
'@types/node@26.2.0':
|
||||
dependencies:
|
||||
undici-types: 8.3.0
|
||||
|
||||
async-proxy@0.4.1:
|
||||
dependencies:
|
||||
object-path-operator: 3.0.0
|
||||
|
||||
bun-types@1.3.14:
|
||||
dependencies:
|
||||
'@types/node': 26.2.0
|
||||
|
||||
fsevents@2.3.2:
|
||||
optional: true
|
||||
|
||||
object-path-operator@3.0.0: {}
|
||||
|
||||
playwright-core@1.61.1: {}
|
||||
|
||||
playwright@1.61.1:
|
||||
dependencies:
|
||||
playwright-core: 1.61.1
|
||||
optionalDependencies:
|
||||
fsevents: 2.3.2
|
||||
|
||||
typescript@5.9.3: {}
|
||||
|
||||
undici-types@8.3.0: {}
|
||||
@@ -62,6 +62,10 @@ export class FakeNextGraph {
|
||||
readonly #documents = new Map<string, StoredDocument>();
|
||||
/** Documents the broker currently cannot answer about. See `breakReadsOf`. */
|
||||
readonly #unreachable = new Map<string, string>();
|
||||
/** Inboxes the broker currently cannot READ. See `breakInboxReadsOf`. */
|
||||
readonly #inboxUnreadable = new Map<string, string>();
|
||||
/** Inboxes the broker currently refuses to WATCH. See `breakWatchingOf`. */
|
||||
readonly #inboxUnwatchable = new Map<string, string>();
|
||||
/** Every live watch, across every identity — a session watching its own inbox. */
|
||||
#watches: Watch[] = [];
|
||||
/** Notifications the broker has not handed over yet. See `deliverNotifications`. */
|
||||
@@ -132,6 +136,43 @@ export class FakeNextGraph {
|
||||
this.#unreachable.delete(asNuri(doc));
|
||||
}
|
||||
|
||||
/**
|
||||
* The broker serves the DOCUMENT but not its INBOX.
|
||||
*
|
||||
* Not a contrivance: upstream an inbox is a repo of its own, reached through an
|
||||
* address `openDocumentInbox` resolves and read with that repo's capability,
|
||||
* while the document itself is read by `readUnion`. Two repos, two reads — so
|
||||
* one answering while the other does not is what a partial failure looks like,
|
||||
* and it is the state that makes a catch-up fail on one index and no other.
|
||||
*/
|
||||
breakInboxReadsOf(doc: NuriLike, reason: string): void {
|
||||
this.#inboxUnreadable.set(asNuri(doc), reason);
|
||||
}
|
||||
|
||||
/** The inbox can be read again. */
|
||||
healInboxReadsOf(doc: NuriLike): void {
|
||||
this.#inboxUnreadable.delete(asNuri(doc));
|
||||
}
|
||||
|
||||
/**
|
||||
* The broker refuses to keep this session posted about that inbox, while
|
||||
* everything else about it still works.
|
||||
*
|
||||
* Watching is a live subscription, set up and held open for as long as the
|
||||
* session lasts; reading an inbox is one question and one answer. A subscription
|
||||
* can be refused where a read succeeds, which is the state that leaves an index
|
||||
* caught up but unwatched — deposits into it going unnoticed until the next
|
||||
* connection, exactly as the failure this models says.
|
||||
*/
|
||||
breakWatchingOf(doc: NuriLike, reason: string): void {
|
||||
this.#inboxUnwatchable.set(asNuri(doc), reason);
|
||||
}
|
||||
|
||||
/** The inbox can be watched again. */
|
||||
healWatchingOf(doc: NuriLike): void {
|
||||
this.#inboxUnwatchable.delete(asNuri(doc));
|
||||
}
|
||||
|
||||
/**
|
||||
* Hands over every inbox notification the broker was holding, and waits for the
|
||||
* sessions watching to finish with them — including notifications those very runs
|
||||
@@ -297,6 +338,12 @@ export class FakeNextGraph {
|
||||
"is reading it, and you may only READ your own",
|
||||
);
|
||||
}
|
||||
const unwatchable = this.#inboxUnwatchable.get(doc);
|
||||
// Refused AFTER the owner check: resolving the address is an owner-only act, so
|
||||
// a stranger is turned away before any subscription is ever attempted.
|
||||
if (unwatchable !== undefined) {
|
||||
throw new Error(`cannot watch the inbox of ${doc}: ${unwatchable}`);
|
||||
}
|
||||
// Watching resolves the inbox address, and the call that resolves one opens it
|
||||
// when there is none — the same idempotent call `openInbox` makes.
|
||||
stored.deposits ??= [];
|
||||
@@ -324,6 +371,10 @@ export class FakeNextGraph {
|
||||
"inbox, you may only READ your own",
|
||||
);
|
||||
}
|
||||
const unreadable = this.#inboxUnreadable.get(doc);
|
||||
if (unreadable !== undefined) {
|
||||
throw new Error(`cannot read the inbox of ${doc}: ${unreadable}`);
|
||||
}
|
||||
return [...stored.deposits].sort((a, b) => a.ts - b.ts);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -15,9 +15,15 @@ import { FakeNextGraph, publishObject } from "./fake-nextgraph";
|
||||
*
|
||||
* The case space is the creator's presence crossed with the deposit's timing:
|
||||
* away when it was made, connected when it was made, and connected on an index
|
||||
* that a previous session created. Plus the three that must NOT happen: a stranger
|
||||
* connecting curates nothing, a document that is no index is left alone, and a
|
||||
* session that could not look for its indexes is still a working handle.
|
||||
* that a previous session created. Plus the two that must NOT happen: a stranger
|
||||
* connecting curates nothing, and a document that is no index is left alone.
|
||||
*
|
||||
* And crossing all of it, the three ways connecting can FAIL — it cannot look for
|
||||
* its indexes, it cannot go through one, it cannot watch one. Each has its own test
|
||||
* below, because each is a failure wearing the shape of an absence: the session
|
||||
* carries on, the handle works, and an index quietly holds less than it should. The
|
||||
* engagement is that none of them denies anything and none of them loses a deposit,
|
||||
* which is only worth anything if it is exercised rather than asserted.
|
||||
*/
|
||||
|
||||
const PUBLISHED_AT = "http://schema.org/datePublished";
|
||||
@@ -38,6 +44,29 @@ async function aliceCreatesAnIndexAndLeaves(network: FakeNextGraph): Promise<Nur
|
||||
return hardcodedInAppSource(index);
|
||||
}
|
||||
|
||||
/**
|
||||
* Runs `body` with this package's log stream captured, and reports HOW MANY
|
||||
* failures it put there alongside whatever the body produced.
|
||||
*
|
||||
* The count, never the text: what a log line reads is for a human and nothing
|
||||
* promises it, so a test that pinned the words would pin the one thing that is
|
||||
* free to change. What is worth pinning is that a failure was reported AT ALL —
|
||||
* harmless is not the same as invisible, and the whole risk here is a failure
|
||||
* passing for an absence.
|
||||
*/
|
||||
async function capturingReports<T>(
|
||||
body: () => Promise<T>,
|
||||
): Promise<{ result: T; reports: number }> {
|
||||
const reported = mock((..._args: unknown[]) => {});
|
||||
const original = console.error;
|
||||
console.error = reported;
|
||||
try {
|
||||
return { result: await body(), reports: reported.mock.calls.length };
|
||||
} finally {
|
||||
console.error = original;
|
||||
}
|
||||
}
|
||||
|
||||
// --- the deposits that piled up while the creator was away ----------------
|
||||
|
||||
test("an index is curated at its creator's next connection, with nobody asking", async () => {
|
||||
@@ -198,6 +227,87 @@ test("a session that could not look for its indexes is still a working handle",
|
||||
expect(String(reported.mock.calls[0]?.[0])).toContain("public store could not be listed");
|
||||
});
|
||||
|
||||
test("an index whose catch-up failed is still a working handle, and loses no deposit", async () => {
|
||||
const network = new FakeNextGraph();
|
||||
const stalled = await aliceCreatesAnIndexAndLeaves(network);
|
||||
const healthy = await aliceCreatesAnIndexAndLeaves(network);
|
||||
|
||||
const bobPort = network.portFor("bob");
|
||||
const bob = await indexing(bobPort);
|
||||
const article = await publishObject(bobPort, PUBLISHED_AT, "2026-03-04");
|
||||
await bob.refer(stalled, article);
|
||||
await bob.refer(healthy, article);
|
||||
|
||||
// The broker answers about the document and not about its inbox. Two repos
|
||||
// upstream, read with two capabilities, so this is a partial failure and not a
|
||||
// contrived one — and it is what makes the catch-up fail on THIS index alone.
|
||||
network.breakInboxReadsOf(stalled, "broker unreachable");
|
||||
|
||||
const { result: alice, reports } = await capturingReports(() =>
|
||||
indexing(network.portFor("alice")),
|
||||
);
|
||||
|
||||
// Obtaining the handle RESOLVED — reaching this line at all is the assertion.
|
||||
// Reading the index it could not go through still works…
|
||||
expect(await alice.read(stalled)).toEqual([]);
|
||||
// …and so does depositing into it: neither ever depended on that work.
|
||||
await alice.refer(stalled, article);
|
||||
// The session is not poisoned either: the other index was caught up normally.
|
||||
expect(await alice.read(healthy)).toEqual([{ object: article, value: "2026-03-04" }]);
|
||||
expect(reports).toBe(1);
|
||||
|
||||
// And nothing was lost. The deposits never left the inbox, so the first
|
||||
// connection that can read it puts them in — which is the whole reason a failed
|
||||
// run is allowed to be this quiet.
|
||||
network.healInboxReadsOf(stalled);
|
||||
network.disconnect("alice");
|
||||
const back = await indexing(network.portFor("alice"));
|
||||
expect(await back.read(stalled)).toEqual([{ object: article, value: "2026-03-04" }]);
|
||||
});
|
||||
|
||||
test("an index that could not be watched is still caught up, and the rest still notices", async () => {
|
||||
const network = new FakeNextGraph();
|
||||
const unwatched = await aliceCreatesAnIndexAndLeaves(network);
|
||||
const watched = await aliceCreatesAnIndexAndLeaves(network);
|
||||
|
||||
const bobPort = network.portFor("bob");
|
||||
const bob = await indexing(bobPort);
|
||||
const waiting = await publishObject(bobPort, PUBLISHED_AT, "2026-01-01");
|
||||
await bob.refer(unwatched, waiting);
|
||||
|
||||
// The subscription is refused; reading that same inbox still works. A watch is
|
||||
// held open where a read is one question and one answer, so one can be turned
|
||||
// down while the other is served.
|
||||
network.breakWatchingOf(unwatched, "the broker refused the subscription");
|
||||
|
||||
const { result: alice, reports } = await capturingReports(() =>
|
||||
indexing(network.portFor("alice")),
|
||||
);
|
||||
|
||||
// The watch failed and the catch-up ran ANYWAY — the backlog is in. That is the
|
||||
// order the code goes to some trouble to hold: failing to watch must not cost
|
||||
// the deposits that were already waiting.
|
||||
expect(await alice.read(unwatched)).toEqual([{ object: waiting, value: "2026-01-01" }]);
|
||||
expect(reports).toBe(1);
|
||||
|
||||
// What the failure costs, exactly and no more: a deposit made from now on is not
|
||||
// NOTICED on that index…
|
||||
const late = await publishObject(bobPort, PUBLISHED_AT, "2026-02-02");
|
||||
await bob.refer(unwatched, late);
|
||||
await bob.refer(watched, late);
|
||||
await network.deliverNotifications();
|
||||
expect((await alice.read(unwatched)).map((e) => e.value)).toEqual(["2026-01-01"]);
|
||||
// …while every other index of the very same session goes on noticing its own.
|
||||
expect(await alice.read(watched)).toEqual([{ object: late, value: "2026-02-02" }]);
|
||||
|
||||
// "Until the next connection" is the whole of the damage, and the next
|
||||
// connection is where it ends.
|
||||
network.healWatchingOf(unwatched);
|
||||
network.disconnect("alice");
|
||||
const back = await indexing(network.portFor("alice"));
|
||||
expect((await back.read(unwatched)).map((e) => e.value)).toEqual(["2026-01-01", "2026-02-02"]);
|
||||
});
|
||||
|
||||
// --- the primitive that keeps a burst from piling up ----------------------
|
||||
|
||||
test("coalescing never runs twice at once, and grants exactly one more run", async () => {
|
||||
|
||||
@@ -154,6 +154,29 @@ test("an index declaring no field at all is still refused", async () => {
|
||||
await expect((await indexing(ownerPort)).read(ordinary)).rejects.toThrow(/declares no index field/);
|
||||
});
|
||||
|
||||
test("curating a document that declares no field refuses, and writes nothing", async () => {
|
||||
const network = new FakeNextGraph();
|
||||
const ownerPort = network.portFor("alice");
|
||||
const bobPort = network.portFor("bob");
|
||||
|
||||
// A document of Alice's with an inbox open and a reference waiting in it, and no
|
||||
// field declared. This is also the shape an INDEX arrives in when it could not be
|
||||
// read — the real `readUnion` turns a failed read into `[]` — so the two are one
|
||||
// case here, and the refusal has to hold for both.
|
||||
const noField = await ownerPort.createPublicDocument();
|
||||
await ownerPort.openInbox(noField);
|
||||
const article = await publishObject(bobPort, FIELD, "2026-01-01");
|
||||
await (await indexing(bobPort)).refer(noField, article);
|
||||
|
||||
await expect(curate(ownerPort, noField)).rejects.toThrow(/declares no index field/);
|
||||
|
||||
// It refused instead of curating on a field it does not have, and it refused
|
||||
// BEFORE writing: the document is still empty, so no entry was invented for it,
|
||||
// and the deposit is still in the inbox for a run that knows what to do with it.
|
||||
expect(await ownerPort.readDocument(noField)).toEqual([]);
|
||||
expect(await ownerPort.readDeposits(noField)).toHaveLength(1);
|
||||
});
|
||||
|
||||
test("a field that could never match an object is refused at creation", async () => {
|
||||
const owner = await indexing(new FakeNextGraph().portFor("alice"));
|
||||
// It cannot be corrected later — nothing here deletes — so it is refused now.
|
||||
|
||||
Reference in New Issue
Block a user