@noy-db/hub 0.7.0 → 0.8.0-pre.0

package/dist/kernel/errors.d.ts

@@ -37,7 +37,8 @@
  *       │    ├─ IndexWriteFailureError            — index side-car put/delete failed post-main
  *       │    ├─ UniqueConstraintError             — duplicate value on unique index
  *       │    ├─ UnsupportedIndexOptionError       — unique+lazy or unique+crdt at registration
- *       │    └─ FieldNotQueryableError            — field's Via posture is queryable: 'none'
+ *       │    ├─ FieldNotQueryableError            — field's Via posture is queryable: 'none'
+ *       │    └─ CollectionNotHydratedError        — sync terminal used on a never-loaded collection
  *       ├─ i18n / Dictionary errors
  *       │    ├─ ReservedCollectionNameError
  *       │    ├─ DictKeyMissingError
@@ -136,32 +137,74 @@ export declare class DecryptionError extends NoydbError {
     constructor(message?: string);
 }
 /**
- * Thrown when GCM tag verification fails, indicating the ciphertext was
- * modified after encryption.
- *
- * AES-256-GCM is authenticated encryption — the tag over the ciphertext
- * is checked on every decrypt. If any byte was flipped (accidental
- * corruption or deliberate tampering), decryption throws this error.
- * Treat it as a security alert: the stored bytes are not what NOYDB wrote.
- */
+ * **Means exactly: "AEAD failed under this key."** Nothing more (lanna-db #4,
+ * 2026-09-03). AES-256-GCM authenticates the ciphertext on every decrypt; if
+ * the tag does not verify under the DEK the caller supplied, the enclave
+ * throws this. Only the enclave throws it *for* an AEAD failure — everywhere
+ * else in hub that names this class is either passing one through or
+ * attaching evidence it holds (see {@link reason}).
+ *
+ * What it does NOT mean on its own: "someone modified the bytes". Four
+ * situations all present as an AEAD failure — the bytes were altered; the
+ * caller holds no key for this collection and a fabricated one was tried; the
+ * body is identity-bound to another vault; the body was sealed under a format
+ * this build does not read. The first is the security alert; the other three
+ * are evidence a caller can hold BEFORE decrypting, and when it does it says
+ * so in `reason`. **With `reason` absent, treat this as the alert it has
+ * always been.** Hub's own tier-fallback code (`with-shape/blobs`) branches
+ * on this class as "not ours at this tier — try the next", which is the
+ * correct reading of "did not open under this key".
+ *
+ * A key derived from a user credential (recovery code, password, share set)
+ * that fails to open a blob is a wrong KEY, and surfaces as
+ * {@link InvalidKeyError}, never this class — `wrapped-deks.ts` translates.
+ */
+/** See {@link TamperedError.reason}. */
+export type TamperedReason = 'unbound-legacy-format' | 'key-absent' | 'generation-mismatch' | 'foreign-stamp';
 export declare class TamperedError extends NoydbError {
     /**
-     * Why the tag check failed, when the enclave could tell (#1103).
+     * Evidence the thrower held BEFORE decrypting, when it held any. Additive
+     * (#1103 pattern): the throw and the class are unchanged, so
+     * `catch (e) { if (e instanceof TamperedError) … }` keeps working; callers
+     * that want to tell a migration or a missing grant from a breach read this.
      *
-     * `'unbound-legacy-format'` — the body opens under an EMPTY AAD, so it was
-     * sealed before identity binding (#1041) and this is a format transition, not
-     * an attack. Positive evidence, not a guess: producing a body that decrypts
-     * under this DEK requires the DEK, which an untrusted store does not hold.
+     * - `'unbound-legacy-format'` — the body opens under an EMPTY AAD, so it was
+     *   sealed before identity binding (#1041): a format transition, not an
+     *   attack. Positive evidence: producing a body that decrypts under this DEK
+     *   requires the DEK, which an untrusted store does not hold. (#1103)
+     * - `'key-absent'` — this keyring holds no DEK for a collection that already
+     *   has records, and the DEK cannot be back-filled (wrapping needs the
+     *   grantee's secret, which the vault never stores). Thrown by the DEK
+     *   resolver instead of minting a key that would decrypt nothing and
+     *   resurface as a bare AEAD failure — the #1288 misdiagnosis. Reserved
+     *   collections (`_periods`, …) take this path; user collections throw
+     *   `NoAccessError` (#1004/#1010).
+     * - `'generation-mismatch'` — reserved for "the artefact was sealed at a
+     *   generation this reader cannot compute". **Not emitted by this build**:
+     *   hub reads no generation stamp off any envelope — `NOYDB_ENVELOPE_GENERATION`
+     *   is an exported constant, and the stamp a bundle carries is manifest data
+     *   a reader never branches on (ADR 0003). The one generation fact hub can
+     *   establish from the bytes — "opens under an empty AAD" — is already
+     *   `'unbound-legacy-format'`. Absence of a stamp never reads as
+     *   generation 1 (`docs/ENVELOPE-GENERATION.md`).
+     * - `'foreign-stamp'` — reserved for "this vault's DEK was asked to open a
+     *   body identity-bound to ANOTHER vault". **Not emitted by this build**:
+     *   nothing in hub can tell that apart from another vault's compartment
+     *   merely being present, which in a multi-vault bundle is normal
+     *   (klum `extractCrossVaultPartition`).
      *
-     * Absent — no benign explanation was found. Treat as the security alert this
-     * error has always been.
+     * Both reserved values are declared so consumers can type against them; a
+     * build that starts emitting either will say so in its CHANGELOG.
      *
-     * The field is additive and the throw is unchanged, so
-     * `catch (e) { if (e instanceof TamperedError) … }` keeps working; callers
-     * that want to tell a migration from a breach can now read this.
+     * Absent — no evidence; the security alert.
+     *
+     * ⚠️ `reason` is hub's IN-PROCESS report and may be branched on. A
+     * generation or origin stamp read out of an untrusted manifest may NOT — it
+     * is store-supplied data, not evidence (klum ADR 0003). If you are holding
+     * a stamp and not this error, you are holding a claim.
      */
-    readonly reason?: 'unbound-legacy-format';
-    constructor(message?: string, reason?: 'unbound-legacy-format');
+    readonly reason?: TamperedReason;
+    constructor(message?: string, reason?: TamperedReason);
 }
 /**
  * Thrown when key unwrapping fails, typically because the secret is wrong
@@ -589,7 +632,36 @@ export declare class PeriodClosedError extends NoydbError {
     readonly periodName: string;
     readonly endDate: string;
     readonly recordTs: string;
-    constructor(periodName: string, endDate: string, recordTs: string);
+    /**
+     * #1455 — the business-date field the guard compared, when the period
+     * declares one. Absent on the envelope-`_ts` (no `dateField`) path.
+     * Structured so a consumer can render the refusal without parsing
+     * `recordTs`'s composed `"incoming[cycle]=2026-06"` form.
+     */
+    readonly dateField: string | undefined;
+    /** #1455 — which side of the write tripped the seal. */
+    readonly side: 'existing' | 'incoming' | undefined;
+    constructor(periodName: string, endDate: string, recordTs: string, detail?: {
+        dateField?: string;
+        side?: 'existing' | 'incoming';
+    });
+}
+/**
+ * Thrown when the `_periods` hash chain does not verify on load (#1454): a
+ * period record's `priorPeriodHash` / `priorPeriodName` no longer resolve to
+ * the stored predecessor in its timeline — an interior close was rewritten or
+ * deleted under the engine. The write guard refuses to evaluate against a set
+ * it cannot trust, so every period-governed write fails with this until the
+ * store is repaired from a trusted copy.
+ *
+ * The chain cannot see a rewrite of the NEWEST record in a timeline (nothing
+ * hashes it yet); the public-API refusal in `vault.collection()` is what closes
+ * that path.
+ */
+export declare class PeriodChainError extends NoydbError {
+    readonly periodName: string;
+    readonly partition: readonly (string | number)[] | undefined;
+    constructor(periodName: string, why: string, partition?: readonly (string | number)[]);
 }
 /**
  * Thrown when a `put()` or `delete()` is rejected by a guard's `check`
@@ -658,7 +730,7 @@ export declare class AmendmentForbiddenError extends NoydbError {
  * envelope ciphertext is still in the store, the keyring file is
  * still listed at `_keyring/*`, and anyone with direct store read
  * access can count keyrings without going through the hub. See
- * `https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/user-envelope.md` → "Directory visibility".
+ * `https://github.com/noy-db/docs/blob/main/content/docs/services/user-envelope.md` → "Directory visibility".
  */
 export declare class DirectoryDisabledError extends NoydbError {
     readonly vault: string;
@@ -933,6 +1005,22 @@ export declare class NotFoundError extends NoydbError {
 export declare class ValidationError extends NoydbError {
     constructor(message?: string);
 }
+/**
+ * Thrown when a `where(field, 'matches', …)` operand is refused (#1357).
+ *
+ * Three distinct refusals, all loud and all at the `where()` call site:
+ *   - the operand is neither a `RegExp` nor a LIKE string,
+ *   - the pattern trips the ReDoS budget (source length, group nesting,
+ *     quantifier count, or a quantified group that itself quantifies),
+ *   - the RegExp carries a `g`/`y` flag, which makes `test()` stateful
+ *     across records and would silently drop rows.
+ *
+ * Deliberately a REFUSAL, never a rewrite: a sanitiser that "fixes" a
+ * user pattern changes which rows come back without saying so.
+ */
+export declare class UnsafePatternError extends NoydbError {
+    constructor(message: string);
+}
 /**
  * Thrown when a Standard Schema v1 validator rejects a record on
  * `put()` (input validation) or on read (output validation). Carries
@@ -1011,7 +1099,41 @@ export declare class GroupCardinalityError extends NoydbError {
     readonly cardinality: number;
     /** The cap that was exceeded. */
     readonly maxGroups: number;
-    constructor(field: string, cardinality: number, maxGroups: number);
+    constructor(field: string, cardinality: number, maxGroups: number, 
+    /**
+     * Which surface refused (#1340). `'query'` — the eager `.groupBy()`, whose
+     * ceiling is a fixed constant. `'scan'` — the streaming
+     * `scan().groupBy(key, { maxGroups })`, whose ceiling is a DECLARED budget,
+     * so its message names the option that raises it. The two differ only in
+     * the advice; the code, the fields and the class are one.
+     */
+    surface?: 'query' | 'scan');
+}
+/**
+ * Thrown by `.traverse()` / `ancestorsOf()` / `descendantsOf()` when a cycle
+ * is reached AND the caller opted into `{ onCycle: 'throw' }` (#1352).
+ *
+ * The default is `'stop'` — the walk simply does not re-enter a node already
+ * on the current path, which is what keeps a circular parent chain from
+ * hanging the tab. `'throw'` exists for the other legitimate reading: a
+ * self-referencing hierarchy that is SUPPOSED to be acyclic, where a cycle is
+ * a data-integrity finding the consumer wants surfaced rather than silently
+ * pruned.
+ *
+ * `cycle` is the offending walk closed back on itself — the path from the
+ * seed to the node that would have been re-entered, with that node repeated
+ * as the final element, so `cycle[0]` and `cycle.at(-1)` name the same
+ * record only for a cycle that reaches all the way back to the seed.
+ */
+export declare class TraversalCycleError extends NoydbError {
+    /** The declared self-ref field being traversed. */
+    readonly field: string;
+    /** The path that closed on itself, with the re-entered id repeated last. */
+    readonly cycle: readonly string[];
+    constructor(opts: {
+        field: string;
+        cycle: readonly string[];
+    });
 }
 /**
  * Thrown in lazy mode when a `.query()` / `.where()` / `.orderBy()` clause
@@ -1030,10 +1152,24 @@ export declare class IndexRequiredError extends NoydbError {
     readonly collection: string;
     readonly touchedFields: readonly string[];
     readonly missingFields: readonly string[];
+    /**
+     * Why the index could not serve the query, when it is NOT "a field is
+     * unindexed" (#1407).
+     *
+     * ⚠️ The default message names missing fields, and that sentence is FALSE
+     * for a refusal on an indexed field — a `where(f,'==',null)` in lazy mode is
+     * refused because the persisted index never holds nullish values, not
+     * because `f` lacks an index. Telling that caller to "declare an index on
+     * each field" sends them to fix something that is already correct, which is
+     * the same defect #1430 fixed in `WeakSecretError`: advice describing rules
+     * that do not apply here.
+     */
+    readonly reason: string | undefined;
     constructor(args: {
         collection: string;
         touchedFields: readonly string[];
         missingFields: readonly string[];
+        reason?: string;
     });
 }
 /**
@@ -1062,16 +1198,17 @@ export declare class UniqueConstraintError extends NoydbError {
  * Thrown at collection registration when an index option is declared that
  * is incompatible with the collection's operating mode.
  *
- * Currently covers two cases:
- * - `unique: true` on a lazy-mode (`prefetch: false`) collection — lazy mode
- *   does not pre-load all records, so an in-memory uniqueness map cannot be
- *   maintained reliably.
- * - `unique: true` on a CRDT collection (`crdt: 'lww-map' | 'rga' | 'yjs'`) —
- *   CRDT put() short-circuits the unique-constraint check, so enforcement would
- *   silently not fire.
- *
- * Both cases are caught eagerly at `vault.collection()` time so the developer
- * sees the incompatibility immediately rather than shipping silently-ignored
+ * ⚠️ **Nothing throws this today (#1358).** It used to cover three cases —
+ * `unique: true` on a lazy-mode (`prefetch: false`), CRDT, or tiered
+ * collection — because those write paths bypassed enforcement. Lazy and
+ * tiered now enforce for real, and CRDT reports detected duplicates on the
+ * `unique:violation` event instead of refusing the declaration (see
+ * `with-lookup/indexing/unique-constraints.ts`). The class is retained: it is
+ * part of the published surface, and it is the right shape for the next index
+ * option that a mode genuinely cannot honour.
+ *
+ * Any future case belongs at `vault.collection()` time so the developer sees
+ * the incompatibility immediately rather than shipping silently-ignored
  * constraints.
  *
  * The `option` field names the incompatible option (`'unique'`) so catch blocks
@@ -1138,10 +1275,58 @@ export declare class PersistedIndexCompensationError extends NoydbError {
  * Payload:
  * - `field` — the refused field name
  */
+/**
+ * #1458 — a query-tier extension method was called without its subpath.
+ *
+ * The DSL ships in four groups. `@noy-db/hub/query` carries **Find** and is
+ * always present; **Live**, **Reduce** and **Relate** arrive by side-effect
+ * import (`import '@noy-db/hub/query/relate'`), which patches the missing
+ * methods onto `Query.prototype` and — through the `declare module` block
+ * that ships with each subpath — onto the `Query` TYPE.
+ *
+ * ⭐ **The compile error is the primary signal; this is the backstop.** With
+ * the types wired that way, calling `.join()` without the import does not
+ * typecheck, which is where a TypeScript consumer meets the problem. This
+ * error is what a JavaScript consumer, or a call that reached the method
+ * through a cast, gets instead of `TypeError: q.join is not a function` —
+ * a message that names neither what is missing nor how to get it.
+ *
+ * ⚠️ It is deliberately NOT a lazy loader. Fetching the chunk here would
+ * defer the cost rather than remove it, and a first `.join()` offline would
+ * fail on a network fetch — the opposite of what an offline-first store
+ * promises. The one line of import is the price of the byte saving.
+ */
+export declare class QueryExtensionMissingError extends NoydbError {
+    /** The method that was called, e.g. `'join'`. */
+    readonly method: string;
+    /** The subpath whose import supplies it, e.g. `'@noy-db/hub/query/relate'`. */
+    readonly subpath: string;
+    constructor(method: string, subpath: string);
+}
 export declare class FieldNotQueryableError extends NoydbError {
     readonly field: string;
     constructor(field: string);
 }
+/**
+ * #1414 — thrown when a synchronous query terminal is USED on a collection
+ * that has never been loaded. The collection's eager cache is empty because
+ * nothing has read it yet, not because the collection is empty: those are
+ * different facts, and only one of them is safe to act on.
+ *
+ * The terminal itself does not throw — it returns a pending result so that the
+ * AWAITED form (`await collection.query().toArray()`, which is what every
+ * async guard `check` does) transparently hydrates and answers correctly. The
+ * error is raised the moment that value is used synchronously: indexed,
+ * iterated, compared, coerced, or read for a property.
+ *
+ * Fix a caller by awaiting the terminal, or by `await collection.list()` /
+ * `await collection.get(id)` before the synchronous read.
+ */
+export declare class CollectionNotHydratedError extends NoydbError {
+    readonly collection: string;
+    readonly terminal: string;
+    constructor(collection: string, terminal: string, label?: string);
+}
 /**
  * Thrown by `readPod()` when the body bytes don't match
  * the integrity hash declared in the bundle header — i.e. someone
@@ -1677,12 +1862,18 @@ export declare class JoinTooLargeError extends NoydbError {
     readonly leftRows: number;
     readonly rightRows: number;
     readonly maxRows: number;
-    readonly side: 'left' | 'right';
+    /**
+     * Which count tripped the ceiling. `'output'` is #1339's addition: a
+     * declared non-equi `.joinOn()` is many-to-many, so it can exceed the
+     * ceiling with both SIDES comfortably under it — the produced row count is
+     * the only thing standing between a theta join and a hang.
+     */
+    readonly side: 'left' | 'right' | 'output';
     constructor(opts: {
         leftRows: number;
         rightRows: number;
         maxRows: number;
-        side: 'left' | 'right';
+        side: 'left' | 'right' | 'output';
         message: string;
     });
 }

package/dist/kernel/generation-map.d.ts

@@ -0,0 +1,48 @@
+/**
+ * A `Map` that stamps every mutation with a globally unique, monotonic tick
+ * (#1417).
+ *
+ * The eager collection cache is written at ELEVEN sites — `put`, `delete`,
+ * hydration, sync cut-over, the lookup write-through, and more. Anything that
+ * memoizes a derived view of that cache (a sorted keyset page order; a
+ * decorated row set) needs to know when the cache moved, and hand-bumping a
+ * counter at eleven call sites is a stale-read waiting to happen: miss one and
+ * a reader serves rows from before a write, which is strictly worse than the
+ * cost the memo was there to avoid.
+ *
+ * ⛔ So the counter lives in the container, not at the call sites. Every
+ * mutation route into a `Map` is `set` / `delete` / `clear`; overriding those
+ * three makes the invariant STRUCTURAL — a new write site cannot forget,
+ * because there is nothing for it to remember.
+ *
+ * ⭐ THE TICK IS GLOBAL, NOT PER-INSTANCE, and that is load-bearing. A memo
+ * keyed on `<vault>/<collection>` + a per-instance count collides across two
+ * collections that share a name — a second vault, a torn-down and rebuilt
+ * instance, a test suite reusing `V/rows` — because both count from zero. A
+ * process-wide tick makes every stamp unique, so identity + generation is a
+ * sound memo key without the memo having to know about instance lifetimes.
+ * (Measured, by a test that reused a collection name and got another
+ * collection's page order back.)
+ *
+ * `set` bumps even when the value is identical: a redundant invalidation costs
+ * one recompute, a missed one costs correctness.
+ *
+ * @module
+ */
+export declare class GenerationMap<K, V> extends Map<K, V> {
+    /**
+     * ⚠️ NOT a `#private` field, and not readonly-initialised, deliberately.
+     * `Map`'s constructor calls `this.set()` for each entry of an iterable
+     * argument — which runs BEFORE this class's fields are installed. A
+     * `#private` field throws `TypeError` on touch at that point; a declared
+     * property is merely `undefined`, and assigning to it is safe. The
+     * initializer below then runs and resets it to 0, which is the correct
+     * resting state for a freshly built map.
+     */
+    private gen;
+    /** Mutation stamp. Equal across two reads means nothing changed between them. */
+    get generation(): number;
+    set(key: K, value: V): this;
+    delete(key: K): boolean;
+    clear(): void;
+}

package/dist/kernel/memory-store.d.ts

@@ -1,17 +1,45 @@
 import type { NoydbStore } from './types.js';
+/** Options for {@link memoryStore}. */
+export interface MemoryStoreOptions {
+    /**
+     * Implement the OPTIONAL half of the store contract — `listVaults`,
+     * `ping`, `tx` — and declare `txAtomic`. Off by default: see the note on
+     * {@link memoryStore} for why the zero-config store must stay a bare core.
+     *
+     * Also switches the store clock to monotonic wall-clock milliseconds,
+     * which is what makes {@link MemoryStoreOptions.clockUncertaintyMs} an
+     * honest unit.
+     */
+    readonly full?: boolean;
+    /**
+     * Widen the interval `getStoreTime()` returns by ±this many milliseconds,
+     * to exercise the commit-wait path in deferred numbering. Default 0 (exact).
+     *
+     * Requires `full: true` — against the default's counter clock a millisecond
+     * epsilon is meaningless, so passing it alone is rejected rather than
+     * silently ignored.
+     */
+    readonly clockUncertaintyMs?: number;
+}
 /**
  * Built-in in-memory store — the kernel's zero-config default.
  *
  * Nested `Map`s: `vault → collection → id → envelope`. Non-persistent
- * (data is lost on process exit). A conformant 6-method {@link NoydbStore}
- * with CAS atomicity and a monotonic store clock — the kernel version of
- * `@noy-db/to-memory`'s core, so `createNoydb()` works with no store package.
+ * (data is lost on process exit). A conformant {@link NoydbStore} with CAS
+ * atomicity and a monotonic store clock, so `createNoydb()` works with no
+ * store package at all.
  *
  * Portable: imports only `types` + `errors` (no crypto primitive) — passes
  * the `stores-ciphertext-only` architecture guard.
  *
- * Implements the 6-method core only (no optional `listVaults`/`ping`/`tx`),
- * so `Noydb.listAccessibleVaults()` throws its documented capability error
- * rather than enumerating vaults under the default store.
+ * ## Why the default is a bare 6-method core
+ *
+ * Called with no options it implements the 6-method core ONLY, so
+ * `Noydb.listAccessibleVaults()` throws its documented capability error
+ * rather than enumerating vaults under a store the caller never chose. That
+ * omission is a decision, not a gap — do not "complete" it. `full: true` is
+ * how a caller opts into the optional half, and
+ * `__tests__/memory-store-full.test.ts` guards the default against exactly
+ * that well-meaning change.
  */
-export declare function memoryStore(): NoydbStore;
+export declare function memoryStore(options?: MemoryStoreOptions): NoydbStore;

package/dist/kernel/noydb.d.ts

@@ -620,6 +620,11 @@ export declare class Noydb {
     enableTabCoordination(opts?: TabCoordinationOptions): {
         dispose: () => void;
     };
+    /** @internal #1362 — `ChangeBroadcastHost`: re-read one broadcast address through THIS
+     *  instance's own keyring. No-op for a vault this instance has not opened. */
+    _applyRemoteSignal(vaultName: string, collectionName: string, id: string): Promise<void>;
+    /** @internal #1362 — `ChangeBroadcastHost`: store backend name, for the default channel name. */
+    get _storeName(): string | undefined;
     private disableTabCoordination;
     get tabRole(): TabRole;
     activeTabs(): TabPresence[];
@@ -713,7 +718,7 @@ export declare class Noydb {
      * keyring file at `_keyring/<userId>` and the envelope ciphertext at
      * `_users/<keyringId>` remain observable to anyone with direct store
      * read access — only the hub-level enumeration is gated. See
-     * `https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/user-envelope.md` → "Directory visibility".
+     * `https://github.com/noy-db/docs/blob/main/content/docs/services/user-envelope.md` → "Directory visibility".
      */
     setDirectoryEnabled(vault: string, enabled: boolean): Promise<void>;
     /**

package/dist/kernel/present-cache.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Per-record memo for the Via `present()` pass (#1419).
+ *
+ * `list()` and `get()` run the full presentation pipeline — money decode plus
+ * its `<field>Formatted`/`<field>Number` siblings, i18n resolution, dictKey
+ * labels, `computed({ mode: 'virtual' })` projection — on every call. Nothing
+ * is decrypted the second time, so a warm `list()` of 10k rows was pure
+ * re-decoration: measured 294 ms (28.5 us/row) against a 5.5 ms full predicate
+ * scan of the same snapshot. `list()` is the read most consumers reach for (a
+ * store mirror re-listing after each write, an export, a guard doing
+ * list-and-filter), so each of them paid the whole collection per call.
+ *
+ * ## Why a WeakMap on the record, and not a generation stamp
+ *
+ * Presentation is a pure function of (record, locale, fallback, layer). Keying
+ * on the RECORD OBJECT means an unrelated write does not throw away the other
+ * 9,999 rows' decorations — which is exactly the reported workload, where a
+ * mirror re-lists after every single put. A generation stamp (#1417's keyset
+ * memo) is the right tool for a whole-collection derivative like a sort order;
+ * it is the wrong one here, because it would invalidate everything on any
+ * write and leave the reported case paying full price.
+ *
+ * Invalidation is then structural rather than maintained: `put` writes a FRESH
+ * record object into the cache, so the previous object — and its entry here —
+ * becomes unreachable and is collected. There is no stale window and nothing
+ * to remember to clear.
+ *
+ * ⚠️ THE ASSUMPTION, STATED SO IT CAN BE CHECKED: a record object in the
+ * collection cache is never mutated in place. This memo is exactly as sound as
+ * that assumption — and no less sound than what already ships, because
+ * `query().toArray()` hands out those same cache objects directly, so an
+ * in-place mutation is already a defect that would corrupt query results
+ * before it corrupted anything here. If in-place mutation is ever introduced,
+ * it breaks the query path first and this second.
+ *
+ * ⭐ Entries hold a PROMISE, not a value, so two concurrent reads of the same
+ * row at the same locale share one presentation pass instead of racing to do
+ * it twice.
+ *
+ * @module
+ */
+/**
+ * A key that is equal only when the presentation provably is.
+ *
+ * `fallback` is a locale code or an ordered chain, so it is joined rather than
+ * stringified — `['th','any']` and `'th,any'` are different requests and must
+ * not share an entry. A space separates the parts, because no locale code,
+ * layer name or fallback chain contains one.
+ */
+export declare function presentVariantKey(locale: string | undefined, layer: string, fallback: string | readonly string[] | undefined): string;
+/**
+ * Return the memoized presentation of `record` for `variant`, computing it
+ * once via `compute`.
+ *
+ * A rejected `compute` is NOT retained: a transient failure must not become a
+ * permanent one for the life of the record.
+ */
+export declare function memoizePresent<T>(record: object, variant: string, compute: () => Promise<T>): Promise<T>;

package/dist/kernel/query/all.d.ts

@@ -0,0 +1,7 @@
+import { Query as FindQuery, executePlan as findExecutePlan } from './builder.js';
+import { ScanBuilder as FindScanBuilder } from './scan-builder.js';
+export declare const Query: typeof FindQuery;
+export declare const ScanBuilder: typeof FindScanBuilder;
+export declare const executePlan: typeof findExecutePlan;
+export type Query<T, S extends keyof T = never, Q extends keyof T & string = never, M extends keyof T & string = never> = FindQuery<T, S, Q, M>;
+export type ScanBuilder<T, S extends keyof T = never, M extends keyof T & string = never> = FindScanBuilder<T, S, M>;