provident-storeroom 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,166 @@
-# Temporary Holding Version
+# `provident-storeroom` — the published Node ESM binding for the native Rust store
+
+**THE CLAIMED REALM IS `{ Node ESM }` AND NOTHING ELSE** (`A70`, `package.md §1.1`): a consumer `import`s
+this package as an ES module from a Node runtime whose ABI carries a Node-API addon. **Every other realm is
+UNCLAIMED and each owes its declared answer** (`package.md §2`: Node CJS, Electron `main`, Electron
+`preload`, Electron `renderer`, the browser, `worker_threads` and any IPC route). **No other realm is
+described here as supported.**
+
+**THE LICENCE OF RECORD IS `AGPL-3.0`** (`DD-43`). It is the repository's own `LICENSE` and no clause of
+this unit changes it. **AND THE LICENCE COPY TRAVELS WITH EVERY ARTEFACT, THIS PACKAGE'S OWN INCLUDED**:
+each of the SIX artefacts — this package and the five platform packages — carries a copy of the
+repository's own `LICENSE` as the licence TEXT travelling with it, copied BYTE-FOR-BYTE at the release's
+own assembly step (`docs/specs/storeroom-publish/contract.md §2.3` item 2; `distribution.md §4.2` item 1 and
+`§4.3` item 2; `PUB-DD-11`; `Q3-5`). **WHAT IS REFUSED IS A SECOND, DRIFTING COPY INSIDE THE TREE**: no
+`LICENSE` byte is written under `bindings/js/` (`§2.3` item 4; `distribution.md §4.3` item 1), so the copy
+is an ARTEFACT-LEVEL fact and not a crate-level file, and this package's `files` allowlist names it
+nowhere — the allowlist is the three entries `§2.1` item 1 fixes and NOTHING ELSE (`Q3-2`). **AND THE COPY
+IS NOT A FIFTH DECLARATION SITE** (`distribution.md §4.2` item 3): the four sites are AUTHORED
+DECLARATIONS ABOUT the licence, while a tarball's own copy is the licence's text travelling with an
+artefact — so the count of SITES stays four and the count of artefacts CARRYING A NOTICE is six.
+
+## The one entry
+
+```js
+import { storeCreate, read, readLiteral, write, delete as remove, rollback, listen, unlisten } from 'provident-storeroom';
+```
+
+**The `exports` map publishes EXACTLY ONE arms-bearing entry — the ESM one** (`package.md §1.3`, `DD-24`):
+there is no wildcard export, no deep import to the addon and no CJS arm. **The addon is reached INTERNALLY
+by the package's own `createRequire`-style step and is not an entry point**: a consumer that spells the
+addon's path directly is outside every clause of this contract.
+
+## The surface
+
+**The eight verbs of `surface.md §2` and NOTHING ELSE**, plus the one member of the object `storeCreate`
+returned:
+
+| The member | Its answer |
+| --- | --- |
+| `storeCreate(cfg)` | the package's own instance handle — `cfg` carries the store's three declared keys and no fourth |
+| `read(instance, address, tier?)` | a leaf's literal, a branch's assembled value, the empty address's whole register |
+| `readLiteral(instance, address, tier?)` | the same, narrowed to a leaf (`ReadTargetIsBranch` on a branch) |
+| `write(instance, address, tier, value)` | `{op, watched, triggered}` |
+| `delete(instance, address, tier?)` | `{address, tiers, triggered}` |
+| `rollback(instance, opId)` | `{opId, undoneOps, restoredTo}` |
+| `listen(instance, address)` | a fresh opaque handle |
+| `unlisten(instance, handle)` | `undefined` — and a no-op success for every value outside the domain |
+| `instance.register(handle, listener)` | `undefined`; a non-function listener or a handle this instance never minted throws a `TypeError` |
+
+**The failure form is ONE** (`surface.md §2.5`, `DD-12`): a THROWN plain object carrying exactly
+`{status, message}` — never an `Error` subclass, never a returned tagged union and never a `Promise`.
+**No `findAddress` is exposed** (`A63`), no `exists` verb exists and no release verb is declared (`A74`).
+
+## The two readings a caller will meet, and the reload rule
+
+**A handle MUST NOT be carried across a process reload.** Handle identity is this process's own: a prior
+session's token names no registration of this process, and `unlisten` over it is a no-op success while
+`register` over it is a `TypeError`.
+
+**Two file-behaviour readings.** A `delete` and a `rollback` perform no file I/O, so a consumer that deletes
+a `file`-tier version and then constructs a fresh instance over an equal `filePath` sees the removed version
+STAND AGAIN — that re-boot is the store's own declared boot and not a defect. And a `file`-tier `write` that
+fails answers `FileCommitFailed` after the store's own automatic journal rollback has run; the package
+compensates for nothing.
+
+## How the addon is resolved — three rungs, and the covered/uncovered answer
+
+**THE ENTRY RESOLVES ITS ARTEFACT IN THE DECLARED ORDER** (`docs/specs/storeroom-publish/resolution.md
+§2`; `docs/specs/storeroom-publish/contract.md §1.1`):
+
+1. **RUNG ONE — THE SCOPED PLATFORM PACKAGE FOR THIS RUNTIME'S KEY.** The entry `require`s THE ONE NAME
+   the closed key set declares for the `process.platform` × `process.arch` pair, and no other name. The
+   five declared names are
+
+   **`@auspicion/js-linux-x64-gnu`** · **`@auspicion/js-linux-arm64-gnu`** ·
+   **`@auspicion/js-darwin-x64`** · **`@auspicion/js-darwin-arm64`** ·
+   **`@auspicion/js-win32-x64-msvc`**
+
+   — five names, three of them carrying a toolchain suffix (`-gnu` twice, `-msvc` once) and two carrying
+   none. **The name is SELECTED from this table and is never built by concatenating tokens**, so no sixth
+   name is computed. These five are the registry's own per-target optional dependencies, and this
+   package's `optionalDependencies` pins each of them at this package's own version, exactly.
+
+2. **RUNG TWO — THE MODULE-RELATIVE ADDON.** Failing rung one, the entry `require`s
+   `build/Release/storeroom_js_binding.node` beside the entry module, constructed from the entry module's
+   own location and from no other source — no environment variable, no configuration key, no path
+   relative to the working directory and no search of a parent directory.
+
+3. **RUNG THREE — THE DECLARED ABSENT-ADDON FORM.** Failing rung two, the load path answers the single
+   failure form, and no instance is returned.
+
+**IN A PUBLISHED INSTALL, RUNG ONE IS THE RUNG THAT FIRES**, because rung two's path is the checkout's
+own and a `files`-restricted tarball does not carry it — **no binary ships IN THIS PACKAGE'S OWN TARBALL,
+at any key, on any target** (`§2.1` item 1; `Q3-2`). **AND THE FIVE PLATFORM ARTEFACTS EACH CARRY THEIR OWN
+TARGET'S BINARY**: each one's allowlist names the `.node` beside its manifest, which is what gives rung one
+a declared source to load at that key at all (`PAR-PUB-21`; `distribution.md §3.2` item 5). **RUNG TWO IS
+THE CHECKOUT-ONLY RUNG**: it is the in-place developer loop and every battery that exists today, and
+building it is a step of a checkout rather than of an install:
+
+```sh
+cargo build --release --manifest-path bindings/js/Cargo.toml --offline
+mkdir -p bindings/js/build/Release
+cp bindings/js/target/release/libstoreroom_js_binding.so bindings/js/build/Release/storeroom_js_binding.node
+```
+
+**No binary is ever committed** (`package.md §3.2`): `build/` and `target/` are ignored, and the artefacts
+are built and published, never stored in the tree. **The prebuild matrix is five targets** (`linux-x64`,
+`linux-arm64`, `darwin-x64`, `darwin-arm64`, `win32-x64`), built one runner per target by the release's own
+workflow, `/.github/workflows/publish.yml`. The Node-API version this addon is built against is the sibling
+crate's own build target and is not a JS-side floor of this package's own (`package.md §1.4`).
+
+**AND THE UNCOVERED-TARGET ANSWER IS A DECLARED LIMITATION, WITH ITS CONSEQUENCE STATED RATHER THAN
+DISCOVERED** (`docs/specs/storeroom-publish/contract.md §2.1` item 3; `docs/specs/storeroom-publish/
+distribution.md §2.2`; `PUB-DD-1`, `PUB-DD-2`):
+
+* **A CONSUMER WHOSE `process.platform` × `process.arch` PAIR IS NOT ONE OF THE FIVE COVERED KEYS GETS NO
+  BINARY.** Rung one is not attempted at all for that pair — no name exists for it — so the load path
+  falls to rung two, which a published install does not carry, and the uncovered consumer therefore meets
+  the declared absent-addon form.
+* **THEY GET NO BUILDABLE ROUTE FROM THE TARBALL EITHER: no `build.rs`, no `Cargo.toml`, no `src/**` and
+  no `postinstall` build-on-install step is shipped.** The store crate's source is deliberately outside
+  this package's allowlist, whose whole content is `index.mjs` · `README.md` · `index.d.ts`.
+* **THEIR ONLY ROUTE IS TO BUILD THE STORE CRATE FROM ITS SOURCE THEMSELVES.** This is a LIMITATION and
+  not a promise: no clause of this package claims that an uncovered consumer's route is supported, tested
+  or witnessed. **A covered consumer needs NO Rust toolchain; an uncovered consumer needs one.**
+* **AND THE DECLARED ANSWER TO A COVERED KEY WHOSE C LIBRARY DIFFERS FROM ITS ARTEFACT'S IS THE SAME
+  ONE**: the `os` and `cpu` fields carry an operating system and an architecture and cannot express a C
+  library, so no C library is read, detected or measured anywhere on this load path, and a state that
+  follows from that is a state the load path reaches rather than a key of its own.
+
+## Tests
+
+```sh
+cargo test  --manifest-path bindings/js/Cargo.toml --offline --no-fail-fast   # the sibling crate's Rust tests
+node --test bindings/js/test/*.test.mjs                                       # this package's JS tests
+```
+
+**AND THE ORDER IS A DECLARED STEP, NOT A CONVENIENCE: THE JS LEG RUNS ONLY AFTER THE ADDON IS BUILT**
+(`docs/specs/storeroom-js-proposal.md §17` · `A75`: *"the JS leg of the acceptance layer acquires A BUILD
+STEP (a `.node` must exist for those cells)"*). **The JS cells drive the package through its CLAIMED ESM
+ENTRY and never the `.node` addon directly** (`acceptance.md §4.1` item 1, `DD-18`), so the entry's own
+route — `JS -> facade -> core -> store` — is what they exercise, and that route needs the artefact the
+`Building the addon` section above produces:
+
+```sh
+# 1. THE BUILD STEP, AT THE REPOSITORY ROOT, BEFORE ANY JS CELL RUNS:
+cargo build --release --manifest-path bindings/js/Cargo.toml --offline
+mkdir -p bindings/js/build/Release
+cp bindings/js/target/release/libstoreroom_js_binding.so bindings/js/build/Release/storeroom_js_binding.node
+# 2. THE JS LEG, AFTER IT:
+node --test bindings/js/test/*.test.mjs
+```
+
+**THERE IS NO FALLBACK AND NO JS-SIDE STORE** (`A75`): an addon that is ABSENT or FAILS TO LOAD is a
+**DECLARED FAILURE** — `storeCreate` answers the single failure form
+`{status: 'FilePathUnreachable', message: <the store's own generated string at the addon's path>}` and NO
+instance is returned. **AND THE MESSAGE'S OWN STRING IS NOT A PLACEHOLDER** (`JS-3`, closed): it is the
+store's generator's rendering of THAT subject — `'/abs/path/to/build/Release/storeroom_js_binding.node' is
+not reachable at construction, the path must exist or the application must be able to write it` — reached
+through the addon's `errorMessage` where the artefact loaded far enough to carry the generator, and
+reproduced BYTE-FOR-BYTE from the generator's own clause (`src/error.rs`'s `FilePathUnreachable` arm) where
+the generator is the thing that failed to load. **A consumer that runs the JS cells without step 1 sees that
+failure and not a silently degraded run.** **The Rust leg needs no addon at all**: the conversion core is the
+crate's `rlib` half, so `cargo test --manifest-path bindings/js/Cargo.toml` is drivable with no Node runtime
+present (`package.md §4.1` item 3, `§4.5` item 7).
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/index.d.ts

@@ -0,0 +1,257 @@
+// `provident-storeroom` — **THE AUTHORED TYPE DECLARATION OF THE PUBLISHED NODE ESM BINDING**
+// (`docs/specs/storeroom-publish/contract.md §2.4`; `docs/specs/storeroom-publish/distribution.md §5`;
+// `PUB-DD-3`; `Q3-4`).
+//
+// **THIS FILE IS HAND-AUTHORED AND NOT GENERATED** (`§2.4` item 1; `PUB-DD-21`): it carries no generation
+// banner, no build-time code generator produces it, and it is the file the package's own `types` field
+// reaches and the package's own `files` allowlist ships.
+//
+// **IT DECLARES THREE THINGS AND NOTHING ELSE** (`distribution.md §5.2`): (1) the EIGHT VERBS of the
+// claimed ESM entry, exactly as the sibling directory enumerates them and with NO ninth name; (2) the
+// instance's own member set, `{ register, on, off }` — three own members and nothing else; and (3) the
+// failure surface, a thrown plain object with exactly `{status, message}`.
+//
+// **AND THE RECORDS THOSE VERBS ANSWER WITH ARE DECLARED BESIDE THEM, WHICH IS STILL PART (1) AND NOT A
+// FOURTH THING**: `Address` · `Tier` · `TierSet` · `StoreConfig` · `BaseState` · `JournalOp` ·
+// `WriteRecord` · `DeleteRecord` · `RollbackRecord` · `Handle` · `Listener` are the SHAPES OF THE
+// ARGUMENTS AND OF THE ANSWERS, in `DD-39`'s own member spellings (the sibling directory's `contract.md
+// §0.2`), and a declaration that did not carry them would declare eight names and no surface. **None of
+// them is a STORE type**: no register, no anchor, no tier tree, no journal and no store verb is declared
+// here (`§5.2` item 4).
+//
+// **AND THE ONE THING THIS DECLARATION MUST NOT CARRY, STATED SO THE FINDING RULE IS CHECKABLE**
+// (`distribution.md §5.2` item 4): **it declares NO store type, NO store verb, NO `findAddress`, NO
+// release verb and NO constraint or repair seam** — each of those is a declaration the sibling directory
+// refuses, and a declaration file carrying one would declare a surface the package does not publish.
+
+/**
+ * A position in the register: the address a verb is called at, as a sequence of path segments.
+ *
+ * **A SEGMENT IS A `string` (a key) OR A NON-NEGATIVE INTEGER (an index)** — `PAR-JS-5`'s own domain, and the
+ * domain the shipped walk admits and the store's own records return. **`readonly string[]` WAS THE SHIPPED
+ * DECLARATION AND IS FALSE OF EVERY ADDRESS CARRYING AN INDEX**, so a consumer compiling the lawful
+ * `read(instance, ['key', 0])` met a type error on a correct call.
+ */
+export type Address = readonly (string | number)[];
+
+/**
+ * The tier a verb is called at: the store's own persistence tokens.
+ *
+ * **THE DOMAIN IS THE STORE'S THREE TOKENS — `'mem'` · `'file'` · `'temp'`** (`PAR-JS-6` · `PAR-JS-7` ·
+ * `PAR-JS-11`; the store's own tier row). **`'mem' | 'file'` WAS THE SHIPPED DECLARATION AND DROPPED
+ * `'temp'`**, mis-typing a lawful third token as a value outside the domain.
+ */
+export type Tier = 'mem' | 'file' | 'temp';
+
+/**
+ * **THE READER'S ARITY, DECLARED BECAUSE IT IS NOT THE WRITER'S** (`PAR-JS-6`; `crossing.md §1.3`'s
+ * `TierArg` row 2): on `read` and `readLiteral` a tier is ABSENT, ONE token, or an ARRAY of tokens read as an
+ * ANY-MATCH set. **On `write` and `delete` an array is outside the domain — the array spelling is the
+ * reader's arity — so those two verbs take the single token `Tier` alone** (`PAR-JS-7` · `PAR-JS-11`).
+ */
+export type TierSet = Tier | readonly Tier[];
+
+/** The configuration a store is constructed from — the store's three declared keys and no fourth. */
+export interface StoreConfig {
+  /** The journal's declared length: a positive integer (`PAR-JS-3`). */
+  readonly journalLength: number;
+  /**
+   * The listeners a construction adopts (`PAR-JS-4`): an array of `{ address, handle }` records, the EMPTY
+   * array included.
+   *
+   * **AND THE KEY IS REQUIRED, NOT OPTIONAL**: an ABSENT `listeners` is the ONE absence the construction
+   * does not admit and answers `AddressMalformed` for, so `listeners?` — the shipped spelling — invited a
+   * call that can never construct. **The ELEMENT SHAPE IS THE STORE'S TO REFUSE**: a member that is not an
+   * `{ address, handle }` record, or whose `handle` is not a plain non-empty `string`, is admitted here and
+   * refused by the store's own construction, because the package mints no second refusal for that position.
+   */
+  readonly listeners: readonly unknown[];
+  /** The file the file tier is backed by, where one is declared (`PAR-JS-2`; ABSENT is in domain). */
+  readonly filePath?: string;
+}
+
+/**
+ * **THE STORE'S OWN CLOSED SET OF FAILURE CODES, AS THE TYPE DECLARES IT — A UNION OVER A
+ * DECLARED-BUT-OPEN SET** (`contract.md §2.4` item 2; `distribution.md §5.3`; `PUB-DD-3`).
+ *
+ * **THE FIFTEEN MEMBERS BELOW ARE THE STORE'S OWN, and their membership is the STORE'S to close and
+ * never this package's**: this package MINTS NO MEMBER, WIDENS NO SET AND RENAMES NONE
+ * (`distribution.md §5.3` item 3).
+ *
+ * **AND AN UNKNOWN STATUS IS STILL TYPED — THE ESCAPE IS LOAD-BEARING, NOT A LOOSENESS.** The store's set
+ * has already moved from fourteen to fifteen members and the store's own park prices a sixteenth, so an
+ * immutably-enumerated union would mis-type a LAWFUL refusal the moment the store's set moves
+ * (`PUB-DD-3`'s refused alternative). The `(string & {})` arm is what keeps a member the store has added
+ * typeable in an installed `0.1.0`, and its absence would be a finding rather than a strictness.
+ */
+export type StoreStatus =
+  | 'AddressMalformed'
+  | 'AddressNotFound'
+  | 'LeafHasNoDownstream'
+  | 'TierNotFound'
+  | 'OutOfDomainTier'
+  | 'ParentAnchorMonotonicityViolation'
+  | 'ContainerKindConflict'
+  | 'ReadTargetIsBranch'
+  | 'WriteParentNotLink'
+  | 'JournalOpUnknown'
+  | 'RollbackCompacted'
+  | 'ConstructionArgumentMissing'
+  | 'FilePathUnreachable'
+  | 'ValueNotAdmitted'
+  | 'FileCommitFailed'
+  | (string & {});
+
+/**
+ * **THE SINGLE FAILURE SURFACE** (`contract.md §1.4`; `distribution.md §5.2` item 3): a THROWN plain
+ * object carrying exactly `{status, message}` — never an `Error` subclass, never a returned tagged union,
+ * never a `Promise` rejection and never a third member. **The status is carried VERBATIM from the store's
+ * own closed set and the message is the store's own generated string**; this package mints neither.
+ */
+export interface StoreRefusal {
+  readonly status: StoreStatus;
+  readonly message: string;
+}
+
+/** The opaque handle a listener registration is keyed by: the package's own value for one registration. */
+export type Handle = object;
+
+/** The caller's listener: any JS function, invoked with the triggering address as its ONE argument. */
+export type Listener = (address: Address) => void;
+
+/**
+ * **A BASE STATE — THE PRE- AND POST-STATE A JOURNAL OP CARRIES** (`DD-39`: *"`BaseState` → `{ present,
+ * value }`"*). **`present` is whether a version stood at the address, and `value` is that version's value
+ * where one did — `undefined` where none did**, because the record is the store's own and the package adds
+ * no member to it.
+ */
+export interface BaseState {
+  readonly present: boolean;
+  readonly value: unknown;
+}
+
+/**
+ * **THE STORE'S OWN JOURNAL OP, CROSSED MEMBER FOR MEMBER AND IN THE STORE'S OWN SPELLINGS** — `DD-39`'s
+ * eight declared names (`distribution.md §5.2` item 1; `P-PUB-7`): `{ opId, kind, address, tier, before,
+ * after, seq, compacted }`.
+ *
+ * **`opId` IS A `string`** — the store's own op-id domain is a non-empty string (`PAR-JS-9`), and the id a
+ * `write` returns is the id a `rollback` takes. **`kind` is the store's own token** (`'write'` and
+ * `'delete'` today) **and its membership is the STORE'S to close, so it is typed as `string` and this
+ * package mints no union over it.** **`tier` is one of the store's own three tokens, or `null` where the op
+ * carries none**; **`seq` is the journal's own sequence number and `compacted` the store's own flag**, each
+ * carried verbatim.
+ */
+export interface JournalOp {
+  readonly opId: string;
+  readonly kind: string;
+  readonly address: Address;
+  readonly tier: Tier | null;
+  readonly before: BaseState;
+  readonly after: BaseState;
+  readonly seq: number;
+  readonly compacted: boolean;
+}
+
+/**
+ * The record a `write` answers: fresh data on every call, never a view of the store's own state.
+ *
+ * **`op` IS THE STORE'S OWN JOURNAL RECORD AND NOT A NUMBER** (`DD-39`; `P-PUB-7`'s `S-TYPES`): **the shipped
+ * declaration read `op: number`, which is false of EVERY value the line returns**, and a consumer compiling
+ * `write(i, a, 'mem', v).op.opId` met a type error on a correct call.
+ */
+export interface WriteRecord {
+  readonly op: JournalOp;
+  readonly watched: readonly Address[];
+  readonly triggered: readonly Handle[];
+}
+
+/** The record a `delete` answers. */
+export interface DeleteRecord {
+  readonly address: Address;
+  readonly tiers: readonly Tier[];
+  readonly triggered: readonly Handle[];
+}
+
+/**
+ * The record a `rollback` answers (`DD-39`: *"`RollbackResult` → `{ opId, undoneOps, restoredTo }`"*).
+ *
+ * **ALL THREE MEMBERS WERE MISTYPED BY THE SHIPPED DECLARATION** (`opId: number`, `undoneOps: number`,
+ * `restoredTo: number`): **`opId` echoes the id the caller passed, and that id is a `string`** (`PAR-JS-9`'s
+ * own unit: *"the `JournalOp.opId` string"*); **`undoneOps` is the LIST of the ids the reversal undid — an
+ * ARRAY of those ids, not a count**; and **`restoredTo` is the base state the addressed subtree now stands
+ * at**, `{ present, value }`.
+ */
+export interface RollbackRecord {
+  readonly opId: string;
+  readonly undoneOps: readonly string[];
+  readonly restoredTo: BaseState;
+}
+
+/**
+ * **THE INSTANCE `storeCreate` RETURNS — `{ register, on, off }`, THREE OWN MEMBERS AND NOTHING ELSE**
+ * (`distribution.md §5.2` item 2). **The instance's own state is released with the instance and by nothing
+ * else: none of the three is a release verb.**
+ */
+export interface StoreInstance {
+  /** Register `listener` under the opaque `handle`, and answer `undefined`. */
+  register(handle: Handle, listener: Listener): void;
+  /** Register a listener at `address` and answer the fresh opaque handle it is keyed by. */
+  on(address: Address, listener: Listener): Handle;
+  /** Withdraw the store-side home entry the `handle` names, and answer `undefined`. */
+  off(handle: Handle): void;
+}
+
+/**
+ * Construct a store at `cfg` and answer its instance.
+ *
+ * **AN ADDON THAT IS ABSENT, THAT FAILS TO LOAD, OR WHOSE OWN `version` DOES NOT MATCH THIS PACKAGE'S
+ * VERSION IS A DECLARED REFUSAL AND NEVER A SILENT FALLBACK** (`docs/specs/storeroom-publish/
+ * resolution.md §2`, `§5`): **no instance is returned, no JavaScript store is substituted, and the
+ * thrown value is the one `StoreRefusal`.** The load path resolves the scoped platform package for this
+ * runtime first, this checkout's own module-relative addon second, and answers the declared absent form
+ * when neither yields a loadable artefact.
+ */
+export function storeCreate(cfg: StoreConfig): StoreInstance;
+
+/**
+ * Read a leaf's literal, a branch's assembled value, or the empty address's whole register.
+ *
+ * **`tier` IS THE READER'S ARITY** (`PAR-JS-6`): absent, ONE token, or an ARRAY of tokens read as an
+ * ANY-MATCH set — **so the shipped `tier?: Tier` refused, as a type error, a lawful call spelling a set**.
+ */
+export function read(instance: StoreInstance, address: Address, tier?: TierSet): unknown;
+
+/** The same read, narrowed to a leaf — a branch answers `ReadTargetIsBranch`; `tier` is `TierSet`. */
+export function readLiteral(instance: StoreInstance, address: Address, tier?: TierSet): unknown;
+
+/** Write `value` at `address` on `tier` — EXACTLY ONE token, never an array (`PAR-JS-7`). */
+export function write(instance: StoreInstance, address: Address, tier: Tier, value: unknown): WriteRecord;
+
+/**
+ * Remove the versions the address names, and answer the operation's record.
+ *
+ * **AND THE NAME IS `delete`, WHICH THIS DECLARATION CANNOT BIND AS AN IDENTIFIER**: `delete` is a RESERVED
+ * WORD, so the function is declared as `deleteOp` and EXPORTED under the name the entry publishes —
+ * `export { deleteOp as delete }` — exactly as `bindings/js/index.mjs` does on its own side.
+ * **`export function delete(…)`, WHICH THE SHIPPED FILE CARRIED, IS NOT A PARSEABLE DECLARATION AT ALL**, so
+ * a consumer's compiler read no surface from this file rather than a mis-typed one (`P-PUB-7`; `Q3-4`).
+ */
+declare function deleteOp(instance: StoreInstance, address: Address, tier?: Tier): DeleteRecord;
+export { deleteOp as delete };
+
+/**
+ * Roll the journal back to `opId`, and answer what the rollback restored.
+ *
+ * **`opId` IS A NON-EMPTY `string` AND NOT A NUMBER** (`PAR-JS-9`'s own unit: *"the `JournalOp.opId`
+ * string"*): the shipped `opId: number` both mis-declared the domain — a number is an OUTSIDE value the
+ * store answers `AddressMalformed` for — and made the ordinary call `rollback(i, w.op.opId)`, whose id is
+ * the string `write` returned, a type error.
+ */
+export function rollback(instance: StoreInstance, opId: string): RollbackRecord;
+
+/** Begin watching an address, and answer the fresh opaque handle it is keyed by. */
+export function listen(instance: StoreInstance, address: Address): Handle;
+
+/** Withdraw a watching, and answer `undefined` — a no-op success for every value outside the domain. */
+export function unlisten(instance: StoreInstance, handle: Handle): void;