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

package/dist/kernel/query/relate/traverse.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Query DSL `.traverse()` — bounded breadth-first walk over ONE declared,
+ * self-referencing `ref()` field (#1352).
+ *
+ * Org charts, bills of materials, account hierarchies, parent/child clients:
+ * every one of them is a collection whose records point at other records in
+ * the SAME collection, and every one of them otherwise needs the consumer to
+ * hand-roll recursion in userland.
+ *
+ * Scope — and the scope is the design, not a limitation to be lifted later:
+ *
+ *   - **Declared refs only.** The field must carry a `ref()` whose target is
+ *     the collection being queried. This is not a general graph engine; an
+ *     undeclared field, or a ref pointing at a different collection, is
+ *     refused at plan time with an actionable error.
+ *   - **`direction: 'up'`** follows the FK — one `lookupById` per hop, O(1).
+ *     **`direction: 'down'`** answers "who points at me", which no forward
+ *     index can serve, so it builds the reverse-FK index #1289 introduced
+ *     (`bucketByRefKey` in `join.ts`) ONCE per call and probes it per node.
+ *   - **`maxDepth` is required.** Not defaulted. An unbounded walk over a
+ *     large collection is a denial of service against the consumer's own UI,
+ *     and a silent default would truncate a result set without saying so —
+ *     the caller must state the bound they can afford.
+ *   - **A node is emitted once**, at the shallowest depth it is reached at.
+ *     That settles the diamond (two seeds converging on one ancestor → one
+ *     row) and it is the same set that makes cycles terminate.
+ *
+ * **Cost.** Nothing here decrypts. `collection.query()` is eager-mode only
+ * and reads the vault's already-decrypted in-memory cache, so the AES-GCM
+ * cost was paid once at `openVault()` prefetch: a depth-5 traversal is
+ * `depth × frontier` Map lookups and zero `crypto.subtle` calls. The one
+ * non-constant cost is `down`'s single O(n) pass to build the reverse index.
+ * The architectural invariant is untouched — no filter, sort or hop is
+ * pushed to the store, which holds ciphertext and never runs a query.
+ */
+/** Which way a traversal walks the declared self-ref. */
+export type TraverseDirection = 'up' | 'down';
+/**
+ * What a traversal does when it reaches a node already on the current path.
+ *
+ * `'stop'` (the default) prunes that branch and finishes the walk — a
+ * circular parent chain produces a finite result instead of hanging.
+ * `'throw'` raises {@link TraversalCycleError}, for hierarchies that are
+ * supposed to be acyclic and where a cycle is a finding, not a shape.
+ */
+export type CyclePolicy = 'stop' | 'throw';
+/** Options for {@link runTraversal}. `maxDepth` is deliberately required. */
+export interface TraverseOptions {
+    readonly direction: TraverseDirection;
+    /**
+     * Maximum number of hops from a seed. `0` returns the seeds alone. Must be
+     * a non-negative integer — there is no default, on purpose.
+     */
+    readonly maxDepth: number;
+    /** Cycle behaviour. Defaults to `'stop'`. */
+    readonly onCycle?: CyclePolicy;
+}
+/**
+ * One row of a traversal result.
+ *
+ * Deliberately NOT flattened into the record. Stamping `depth` / `path` onto
+ * the record would collide with a real field on exactly the collections this
+ * feature exists for — an org chart with its own `depth` column is not a
+ * hypothetical — and the loser of that collision would be silent.
+ *
+ * `path` is the ids from the seed to this node, BOTH INCLUSIVE, so
+ * `path.length === depth + 1` and `path.at(-1) === id` always. A seed has
+ * `depth: 0` and `path: [id]`.
+ */
+export interface TraversalRow<T> {
+    /** This node's record id. */
+    readonly id: string;
+    /** The record itself, decoded exactly as `toArray()` would decode it. */
+    readonly record: T;
+    /** Hops from the seed. `0` for a seed. */
+    readonly depth: number;
+    /** Seed-to-node ids, inclusive at both ends. */
+    readonly path: readonly string[];
+}
+/** The slice of a query source a traversal needs. */
+export interface TraverseSource {
+    snapshot(): readonly unknown[];
+    lookupById?(id: string): unknown;
+    snapshotEntries?(): readonly {
+        readonly id: string;
+        readonly record: unknown;
+    }[];
+}
+/**
+ * Bounded BFS from `seeds`.
+ *
+ * `seeds` are ids, not records — a seed that names no existing record is
+ * skipped, not thrown on, for the same reason a dangling ref terminates a
+ * branch quietly: a traversal reports the graph it found, and a missing node
+ * is an absence, not a failure of the walk.
+ *
+ * The two guards are separate on purpose:
+ *
+ *   - `path.includes(next)` is a CYCLE — the walk would re-enter a node it is
+ *     standing on. Checked first, so `onCycle: 'throw'` reports a genuine
+ *     ring rather than the next case.
+ *   - `emitted.has(next)` is a DIAMOND — the node was already reached by
+ *     another branch, at a depth no greater than this one (BFS), so re-
+ *     emitting it would duplicate the row and re-walk its whole subtree.
+ *
+ * Collapsing them into one visited-set would make a diamond indistinguishable
+ * from a cycle, which is precisely the distinction `onCycle` sells.
+ */
+export declare function runTraversal(source: TraverseSource, field: string, seeds: readonly string[], opts: TraverseOptions): TraversalRow<unknown>[];

package/dist/kernel/query/scan-builder.d.ts

@@ -43,26 +43,33 @@
  * ```
  *
  * Note that each aggregation pays a full scan — there's no shared
- * iteration across the two. Multi-way aggregation in a single pass
- * is out of scope; consumers who need it should build a compound spec
- * and run a single `.aggregate({ openN, paidN })` at the DSL level.
+ * iteration across the two. When the specs are known together, pass
+ * them as an ARRAY (#1340): `.aggregate([specA, specB])` steps every
+ * spec's state from the same yielded record, so N specs cost one
+ * pass, not N.
  *
  * **Out of scope for (tracked separately):**
  *   - `scan().aggregate().live()` — unbounded scan + change-stream
- *     reconciliation is a design problem, not just a code one
- *   - `scan().groupBy().aggregate()` — high-cardinality grouping on
- *     huge collections would re-introduce the O(groups) memory
- *     problem that aggregate fixes
+ *     reconciliation is a design problem, not just a code one, and
+ *     #1340 deliberately left it out
  *   - Parallel scan across pages — race-safe page cursor contracts
  *     are not in the adapter API yet
  *   - `scan().join(...)` — tracked under  (streaming join)
  */
 import type { QueryField } from '../types.js';
-import type { ReducerBuilder } from '../../with-lookup/reduce/reducers.js';
 import type { Clause, Operator } from './predicate.js';
 import type { ReduceSpec, ReduceResult } from '../../with-lookup/reduce/reduction.js';
-import type { JoinContext, JoinLeg } from './join.js';
+import type { JoinContext, JoinLeg } from './relate/join.js';
+import type { ScanJoinResolver } from './relate/scan-methods.js';
 import type { ViaPipeline } from '../via/pipeline.js';
+/**
+ * Result of the multi-spec `.aggregate([specA, specB, …])` form (#1340) — a
+ * tuple positionally matching the specs, each element the shape that spec's
+ * own single-spec `.aggregate()` would have returned.
+ */
+export type MultiReduceResult<Specs extends readonly ReduceSpec[]> = {
+    -readonly [K in keyof Specs]: ReduceResult<Specs[K]>;
+};
 /**
  * Page provider — the Collection-shaped hook the builder calls to
  * walk cursors forward. Kept as a structural interface so tests can
@@ -122,6 +129,8 @@ export declare class ScanBuilder<T, S extends keyof T = never, M extends keyof T
      * the scan stream carries no locale context, mirroring `Query.toArray()`.
      */
     private readonly via;
+    protected buildJoinResolvers: () => ScanJoinResolver[];
+    protected applyOneJoinStreaming: (record: unknown, resolver: ScanJoinResolver) => unknown;
     constructor(pageProvider: ScanPageProvider<T>, pageSize?: number, clauses?: readonly Clause[], joins?: readonly JoinLeg[], joinContext?: JoinContext, via?: ViaPipeline);
     /**
      * Decode this scan's Via-covered fields on a record (e.g. money: stored
@@ -155,174 +164,7 @@ export declare class ScanBuilder<T, S extends keyof T = never, M extends keyof T
      * possible.
      */
     filter(fn: (record: T) => boolean): ScanBuilder<T, S, M>;
-    /**
-     * Resolve a `ref()`-declared foreign key per record as the scan
-     * stream flows, attaching the right-side record (or null) under
-     * `opts.as`. — streaming joins over `scan()`.
-     *
-     * ```ts
-     * for await (const inv of invoices.scan().join('clientId', { as: 'client' })) {
-     *   await processInvoice(inv) // inv.client is attached
-     * }
-     *
-     * // Or terminate with .aggregate() for streaming joined aggregation
-     * const { total } = await invoices.scan()
-     *   .where('status', '==', 'open')
-     *   .join('clientId', { as: 'client' })
-     *   .aggregate({ total: sum('amount') })
-     * ```
-     *
-     * **The key difference from eager `.join()`:** the LEFT
-     * side streams page-by-page from the adapter and is never
-     * materialized. Memory ceiling on the left is O(pageSize), not
-     * O(rowCount). This is what makes streaming joins suitable for
-     * collections that exceed the eager join's 50_000-row ceiling.
-     *
-     * **Right-side strategy** is auto-selected per leg:
-     *   - **Indexed** — right source exposes `lookupById`, so each
-     *     left row costs O(1). This is the common path for
-     *     Collection right sides, which back `lookupById` with a Map
-     *     lookup over the in-memory cache. The right collection must
-     *     be in eager mode (the same constraint as eager join's
-     *     `querySourceForJoin` from ).
-     *   - **Hash** — right source has only `snapshot()`. Build a
-     *     `Map<id, record>` once at iteration start, probe per left
-     *     row. Same correctness, same per-row cost as the indexed
-     *     path; the difference is the upfront cost of materializing
-     *     the right side once.
-     *
-     * Both strategies hold the right side in memory for the duration
-     * of the iteration. The "streaming" property applies to the LEFT
-     * side only — true left-and-right streaming joins (where neither
-     * side fits in memory) require a sort-merge join planner that's
-     * out of scope for.
-     *
-     * **Ref-mode semantics** match eager `.join()` exactly:
-     *   - `strict`  → throws `DanglingReferenceError` mid-stream
-     *     when a left record points at a non-existent right id.
-     *     The throw aborts the async iterator — consumers should
-     *     wrap the `for await` in try/catch if they want to recover.
-     *   - `warn`    → attaches `null` and emits a one-shot warning
-     *     per unique dangling pair (deduped via the same warn
-     *     channel as eager join).
-     *   - `cascade` → attaches `null` silently. A delete-time mode;
-     *     dangling refs at read time are mid-flight or pre-existing
-     *     orphans, not a DSL error.
-     *
-     * Left records with null/undefined FK values attach `null`
-     * regardless of mode — same "no reference at all" policy as
-     * eager join and write-time `enforceRefsOnPut`.
-     *
-     * **Multi-FK chaining** is supported via repeated `.join()`
-     * calls: each leg resolves an independent ref. Each leg
-     * independently picks its right-side strategy and applies its
-     * own ref mode.
-     *
-     * **Joins are NOT applied** to a `.aggregate()` terminal that
-     * doesn't reference joined fields — wait, that's not quite
-     * right. The streaming path actually DOES apply joins before
-     * `.aggregate()` because the join attaches a field that the
-     * spec might reference. Unlike `Query.aggregate()` (which skips
-     * joins entirely as a projection-only short-circuit), the
-     * streaming aggregation can't know whether the spec touches a
-     * joined field, so it always applies joins. Consumers who want
-     * unjoined streaming aggregation should leave `.join()` off the
-     * chain — the chain is composable for a reason.
-     *
-     *  constraint #1 — every JoinLeg carries `partitionScope:
-     * 'all'` plumbed through but never read by. Same seam as
-     * eager join.
-     */
-    join<As extends string, R = unknown>(field: QueryField<T, S>, opts: {
-        as: As;
-    }): ScanBuilder<T & Record<As, R | null>, S, M>;
-    /**
-     * Iterate the scan as an async iterable. Walks the page
-     * provider's cursors forward until exhaustion, applying every
-     * clause per record — only matching records are yielded.
-     *
-     * Backward-compatible with the previous async-generator `scan()`
-     * return type for `for await … of` consumers.
-     */
     [Symbol.asyncIterator](): AsyncIterator<T>;
-    /**
-     * Per-leg right-side resolution state. Built once at iteration
-     * start and reused for every left record. Two strategies:
-     *
-     *   - `lookupById`: present when the right source exposes the
-     *     hook directly (typical Collection right side). Per-row
-     *     cost is O(1).
-     *   - `hashByPrimaryKey`: built from `snapshot()` when no
-     *     lookupById. Per-row cost is O(1) after the upfront O(N)
-     *     materialization. Same as eager join's hash strategy.
-     *
-     * `warnedKeys` is the per-leg dedup set for ref-mode 'warn'. We
-     * key on `field→target:refId` so the same dangling pair only
-     * warns once per iteration. The dedup is per-iteration, not
-     * per-process — a long-running scan that re-iterates would warn
-     * again, which is the desired behavior (the data may have
-     * changed between iterations).
-     */
-    private buildJoinResolvers;
-    /**
-     * Resolve a single join leg for one left record and return the
-     * left record with the joined field attached under
-     * `leg.as`. Pure function over `(left, resolver)`; never
-     * mutates the input.
-     *
-     * Ref-mode dispatch matches eager `applyJoins` from :
-     *   - null/undefined FK → attach null silently (always allowed)
-     *   - dangling FK + strict → throw `DanglingReferenceError`
-     *   - dangling FK + warn → attach null, warn-once per pair
-     *   - dangling FK + cascade → attach null silently
-     */
-    private applyOneJoinStreaming;
-    /**
-     * Reduce the scan stream through a named set of reducers and
-     * return the final aggregated shape.
-     *
-     * Memory is O(reducers): one mutable state slot per spec key.
-     * Records flow through the pipeline one at a time via
-     * `for await` and are discarded after their `step()` is applied
-     * — never collected into an array. This is the distinguishing
-     * property from `Query.aggregate()`, which materializes the full
-     * match set first.
-     *
-     * Reuses the same reducer protocol as `Query.aggregate()`,
-     * so `count()`, `sum(field)`, `avg(field)`, `min(field)`,
-     * `max(field)` all work unchanged. The `{ seed }` parameter
-     * plumbing from  constraint #2 is honored transparently — the
-     * factories ignore it in and the scan executor never
-     * touches the per-reducer state construction.
-     *
-     * **Returns a Promise**, unlike `Query.aggregate().run()` which
-     * is synchronous. The scan is inherently async because it walks
-     * adapter pages, so the terminal has to be too. Consumers
-     * destructure with await:
-     *
-     * ```ts
-     * const { total, n } = await invoices.scan()
-     *   .where('year', '==', 2025)
-     *   .aggregate({ total: sum('amount'), n: count() })
-     * ```
-     *
-     * **No `.live()` in.** `scan().aggregate().live()` would
-     * require reconciling an unbounded streaming iteration with a
-     * change-stream subscription — a design problem, not just a code
-     * one. Consumers with huge collections and live needs should
-     * narrow with `.where()` enough to fit in the 50k `query()`
-     * limit and use `query().aggregate().live()` instead.
-     *
-     * Consults the Via pipeline's posture before reducing (#629 Task 8 review
-     * fix wave 1): a reducer over a field whose posture is `queryable: 'none'`
-     * throws `FieldNotQueryableError` here, metadata-only — via
-     * `ViaPipeline.refuseUnqueryableReducers`, NOT the full `wrapReducers`
-     * (which would also activate money's exact-reducer rewrite, a path this
-     * method has never run and must not start running as a side effect of
-     * this gate).
-     */
-    aggregate<Spec extends ReduceSpec>(spec: Spec): Promise<ReduceResult<Spec>>;
-    aggregate<Spec extends ReduceSpec>(build: (b: ReducerBuilder<T, S, M>) => Spec): Promise<ReduceResult<Spec>>;
     /**
      * Evaluate the clause list against a single record. Linear in
      * the clause count; short-circuits on first false. Clauses on a
@@ -332,3 +174,64 @@ export declare class ScanBuilder<T, S extends keyof T = never, M extends keyof T
      */
     private recordMatches;
 }
+/**
+ * ── Grouped streaming reduction over a `scan()` — `#1340` ──────────────────
+ *
+ * `scan().groupBy(key, { maxGroups }).aggregate(spec)` folds an unbounded,
+ * page-by-page scan into one row per group. The distinguishing property
+ * against the eager `Query.groupBy()` path is WHAT IS HELD:
+ *
+ *   - eager (`groupAndReduce` in `with-lookup/reduce/groupby.ts`) partitions
+ *     the matched records into `Map<key, records[]>` and reduces each bucket
+ *     afterwards — O(matched records) memory;
+ *   - this one holds **one reducer state per group and no records at all** —
+ *     O(groups × state), with the left side still streaming at O(pageSize).
+ *
+ * So the two cannot share an implementation, and this deliberately does
+ * NOT use `groupAndReduce`: reusing it would mean collecting the stream,
+ * which is the exact thing `scan()` exists to avoid. What IS shared is every
+ * piece that decides SEMANTICS — the group-key canonicalisation (so `null`
+ * and `undefined` bucket apart here exactly as they do there), the reducer
+ * protocol, `ViaPipeline.wrapReducers` (money stays BigInt-exact),
+ * `bindDistinctReducers` (`countDistinct` dedups on the canonical index key),
+ * and `projectDateTruncKeys` (a derived calendar key is stamped onto a
+ * shallow copy of the row before bucketing, same as `Query.groupBy()`).
+ *
+ * ## The memory budget IS the feature
+ *
+ * `maxGroups` defaults to `GROUPBY_MAX_CARDINALITY` (100_000) — the same
+ * ceiling the eager path enforces — and is refused the moment the group that
+ * would exceed it is first seen, mid-stream, before its state is allocated.
+ * ⛔ It never truncates: a truncated rollup is a WRONG ANSWER that looks like
+ * a right one, and the whole point of declaring a budget is to learn that the
+ * grouping does not fit. The refusal names the option and the observed count.
+ *
+ * ⚠️ **Per-group state is NOT constant.** `count`/`sum`/`avg`/`min`/`max` are
+ * O(1) per group, but `median`/`percentile` (exact) hold every sampled value
+ * — O(n) per group — `mode` holds one entry per distinct value, and
+ * `countDistinct` one per distinct value. A grouped scan with an exact
+ * `median` is therefore O(matched records) overall no matter what `maxGroups`
+ * says, since the values live in the group states. Pair it with
+ * `{ approx: true }` (the t-digest, bounded per group) when the scan is
+ * genuinely unbounded — that is what makes `maxGroups` a real ceiling rather
+ * than an accounting fiction.
+ *
+ * ## Post-group `having` / `orderBy` / `limit` (#1336) are NOT on this path
+ *
+ * Those live on `GroupedReduction`, which is built around a SYNCHRONOUS
+ * `executeRecords()` closure and the eager pipeline; a scan has neither.
+ * Rather than grow a second, subtly different implementation of the same
+ * three operations, this terminal returns the row array — bounded by
+ * `maxGroups` and already in memory — and the caller filters, sorts and
+ * slices it. See the report on #1340; if a consumer wants the chainable
+ * shape, the honest fix is to lift the post-group stage out of
+ * `GroupedReduction` and share it, not to copy it here.
+ *
+ * ⚠️ Lives in THIS file rather than its own `scan-groupby.ts` for one
+ * mechanical reason: `check-architecture`'s `port-layering` ratchet
+ * grandfathers `scan-builder.ts`'s two `with-lookup/reduce/*` imports per
+ * specifier, and a NEW kernel file may not statically import a `with-*`
+ * service at all. Splitting it out means either a dynamic import on the
+ * reducer protocol or a new grandfather entry; neither is worth it for a
+ * class that only exists to terminate `ScanBuilder.groupBy()`.
+ */

package/dist/kernel/query/sort-key.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The ORDERED KEY — one encoding of "what does it mean for two stored values
+ * to be comparable, and in what order".
+ *
+ * ⭐ This lives in the kernel, not in `with-lookup/indexing/`, because it is
+ * the machine-readable half of a KERNEL rule: `predicate.ts`'s `isComparable`
+ * refuses to order two values of different runtime types, and every structure
+ * that claims to answer a range or an equality faster than the linear scan
+ * must reproduce that refusal exactly or it will serve rows the scan would
+ * not. #1344's `SortedIndex`, #1345's `CompoundIndex` and #1339's declared
+ * joins all key on this, so there is ONE definition to disagree with rather
+ * than three.
+ *
+ * `with-lookup/indexing/sorted-indexes.ts` re-exports the whole of this
+ * module, so its existing importers are unchanged; the direction of the
+ * dependency is the point — an opt-in service may reach into the kernel
+ * spine, and `check-architecture.mjs`'s `port-layering` ratchet is what stops
+ * the reverse.
+ *
+ * Two properties are load-bearing and belong to the scan, not to any index:
+ *
+ *  - **Kind-partitioned.** The numeric `kind` IS the sort rank, so a `string`
+ *    probe can never reach `number` entries.
+ *  - **No order-defined type, no key.** Booleans, objects, arrays, `NaN` and
+ *    nullish values produce `undefined` and are absent from every structure
+ *    built on this — which is why a caller that removed clauses from a plan
+ *    must compare an index's size against the snapshot size before trusting
+ *    it to cover the collection.
+ */
+/**
+ * Order-defined key kinds. The numeric value IS the sort rank, so entries
+ * of different kinds never interleave and a probe only ever compares
+ * against its own kind.
+ */
+export type KeyKind = 0 | 1 | 2;
+export declare const KIND_NUMBER: KeyKind;
+export declare const KIND_STRING: KeyKind;
+export declare const KIND_DATE: KeyKind;
+export interface SortKey {
+    readonly kind: KeyKind;
+    /** `number` for {@link KIND_NUMBER} and {@link KIND_DATE}, `string` otherwise. */
+    readonly key: number | string;
+}
+/** Total order over {@link SortKey}: by kind first, then within the kind. */
+export declare function compareKeys(a: SortKey, b: SortKey): number;
+/**
+ * Map a raw (or canonicalized) value onto its ordered key, or `undefined`
+ * when the value has no order-defined runtime type — mirroring
+ * `predicate.ts`'s `isComparable`, which refuses to order booleans,
+ * objects and arrays.
+ */
+export declare function toSortKey(value: unknown, canonicalKey: string | undefined): SortKey | undefined;

package/dist/kernel/tx-write-gate.d.ts

@@ -0,0 +1,77 @@
+/**
+ * #1420 — the in-flight-write gate.
+ *
+ * ## The defect this closes
+ *
+ * `runTransaction`'s commit opens with a **pre-flight**: it re-reads every
+ * touched envelope and enforces the caller's `expectedVersion`. That check is
+ * only as honest as the read, and the read could not see a plain
+ * `Collection.put()` that had *started* but not yet reached the store. Such a
+ * put is invisible to the pre-flight, so:
+ *
+ *   - it lands after the pre-flight and the transaction overwrites it from a
+ *     stale snapshot (both writers report success, one write vanishes); or
+ *   - it lands after the transaction's own write and clobbers it from a stale
+ *     base (two writes, one version bump).
+ *
+ * Neither raised an error on either side, and the loss was **store-capability
+ * dependent** — `to-memory` declares `txAtomic` and takes the atomic commit
+ * path, `to-browser-idb` does not and takes the per-op replay — so an app
+ * tested on a memory store could ship lossy on IndexedDB.
+ *
+ * ## The remedy: make the pre-flight's read honest
+ *
+ * Every logical `Collection.put()` / `.delete()` registers itself here for the
+ * span of its read-modify-write, keyed by `(vault, collection, id)`. A commit
+ * **drains** the writes already in flight on the keys it is about to touch,
+ * BEFORE its pre-flight reads. The in-flight case then behaves exactly like
+ * the fully-awaited one the pre-flight already handled correctly: the read
+ * sees the new version and a mismatched `expectedVersion` refuses with
+ * `ConflictError`. No silent loss, and no new refusal for writes that were
+ * never in conflict.
+ *
+ * ## Why this is deadlock-free
+ *
+ * The wait is strictly one-directional and one-deep. A registered write never
+ * waits on anything from this module — only a commit does, and only on writes
+ * registered *before* it started draining ({@link drainKeyedWrites} takes a
+ * snapshot and does not loop to a fixed point). So there is no cycle to close,
+ * and the drain terminates as soon as the pre-existing writes settle,
+ * whichever way they settle. A commit's own Phase-2 writes register *after*
+ * the drain has returned, so a commit never waits on itself.
+ *
+ * ## Scope, deliberately
+ *
+ * Keyed on the STORE object, not the `Noydb` instance — two hub instances over
+ * one store are the same race, and this keeps the always-on kernel files
+ * (`noydb.ts`) untouched. Same-process only: it is a JS-object registry, and
+ * makes no claim about a second tab or a second process. That is the same
+ * boundary the reported defect has.
+ *
+ * ⛔ This does NOT serialize transaction against transaction. Two concurrent
+ * commits touching one key can still interleave — a distinct case from the
+ * reported one, and one whose fix (a commit barrier) has to solve reentrancy
+ * for the commit's own replay writes first. Do not extend this module into
+ * that without measuring the reentrancy path.
+ *
+ * @internal
+ */
+/** The shared `(vault, collection, id)` key shape. @internal */
+export declare function writeGateKey(vault: string, collection: string, id: string): string;
+/**
+ * Run one logical write registered against `(vault, collection, id)` so a
+ * concurrent commit can drain it. Returns / throws exactly what `fn` does —
+ * registration is invisible to the caller.
+ *
+ * @internal
+ */
+export declare function trackKeyedWrite<R>(store: object, vault: string, collection: string, id: string, fn: () => Promise<R>): Promise<R>;
+/**
+ * Wait for every write already in flight on `keys` to settle. Snapshot-based
+ * and single-pass — see the deadlock note in the module doc. A no-op (and no
+ * microtask) when nothing is in flight, which is the overwhelmingly common
+ * case for a commit.
+ *
+ * @internal
+ */
+export declare function drainKeyedWrites(store: object, keys: Iterable<string>): Promise<void>;

package/dist/kernel/types.d.ts

@@ -30,6 +30,7 @@ import type { ArchiveStrategy } from '../with-fork/archive/index.js';
 import type { IndexingStrategy } from '../with-lookup/indexing/strategy.js';
 import type { ReduceStrategy } from '../with-lookup/reduce/strategy.js';
 import type { ConsentStrategy } from '../with-audit/consent/strategy.js';
+import type { CoverageEvent, CoverageStrategy } from '../port/with/coverage-strategy.js';
 import type { PeriodsStrategy } from '../with-audit/periods/strategy.js';
 import type { ShadowStrategy } from '../with-fork/shadow/strategy.js';
 import type { TransactionsStrategy } from '../with-commit/tx/strategy.js';
@@ -404,6 +405,7 @@ export type IndexFieldName<T, S extends keyof T = never, Q extends keyof T & str
 export type IndexDefFor<F extends string> = F | {
     readonly fields: readonly F[];
     readonly unique?: boolean;
+    readonly kind?: 'hash' | 'sorted';
 } | readonly F[];
 /**
  * The type of the `sensitive` collection option, conditional on whether the
@@ -849,7 +851,7 @@ export type RecoveryEnrollment = {
  * (LUKS pattern). Adding or removing a slot is a constant-time keyring
  * write — no DEK re-keying required.
  *
- * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/session-tiers.md → Tier 2 — Authenticate (multi-slot)
+ * @see https://github.com/noy-db/docs/blob/main/content/docs/services/session-tiers.md → Tier 2 — Authenticate (multi-slot)
  */
 /**
  * Shared fields across all authenticator slot variants. The variant
@@ -1528,6 +1530,14 @@ export interface ChangeEvent {
     readonly collection: string;
     readonly id: string;
     readonly action: 'put' | 'delete';
+    /**
+     * True when this change was produced by APPLYING another tab's or process's
+     * signal rather than by a write here (#1362). Two consumers read it:
+     * `ChangeBroadcast` never re-posts one (echo suppression), and the query
+     * source hands the live query NO delta for one — a remote address is not a
+     * trustworthy delta, so the live query re-runs instead of patching.
+     */
+    readonly remote?: boolean;
 }
 export interface NoydbEventMap {
     'change': ChangeEvent;
@@ -1585,6 +1595,16 @@ export interface NoydbEventMap {
      * index mirror may have drifted. Operators reconcile via
      * `collection.reconcileIndex(field)`.
      */
+    /**
+     * A principal's estimated COVERAGE of a `bulk: 'sensitive'` collection
+     * crossed a declared threshold (`withCoverage()`, #1363). Fires at most once
+     * per threshold per `(principal, vault, collection)`.
+     *
+     * ⛔ A SIGNAL, never a refusal — the read it reports has already been
+     * served, and no refusal path exists by design (#1251 §3: a refusal at a
+     * boundary is a threshold the reader can binary-search).
+     */
+    'coverage:threshold': CoverageEvent;
     'index:write-partial': {
         vault: string;
         collection: string;
@@ -1592,6 +1612,37 @@ export interface NoydbEventMap {
         action: 'put' | 'delete';
         error: Error;
     };
+    /**
+     * #1358 — a `unique` index collision that was DETECTED rather than
+     * prevented. Emitted only by a CRDT collection, which is the one mode where
+     * prevention is not available: two replicas that are offline from each
+     * other can both accept the same value, and no local check can see the
+     * other's write. So the write is never refused, BOTH records are kept (as
+     * CRDT convergence requires), and the collision is reported here — when it
+     * is created, and again when a later session first sees the two records
+     * together (the merge point).
+     *
+     * The guarantee a consumer may rely on is therefore: uniqueness within what
+     * this writer could see at write time, plus detection when the replicas
+     * meet. Nothing stronger.
+     *
+     * `error` is a `UniqueConstraintError` (`kernel/errors.ts`) carrying the
+     * same `collection` / `recordId` / `fields` / `conflictingId` as the
+     * duplicate `put()` would have thrown on a non-CRDT collection — so a
+     * handler can treat it with the code it already has for that error.
+     * Eager, lazy and tiered collections PREVENT instead and never emit this.
+     */
+    'unique:violation': {
+        vault: string;
+        collection: string;
+        /** The record that arrived second (locally — replicas need not agree on order). */
+        id: string;
+        /** The constrained field tuple; more than one field means a compound unique. */
+        fields: readonly string[];
+        /** The record already holding the value. Both are still readable. */
+        conflictingId: string;
+        error: Error;
+    };
     /**
      * emitted by `Collection.ensurePersistedIndexesLoaded()`
      * once per field on first lazy-mode query when
@@ -2493,6 +2544,23 @@ export interface NoydbOptions {
      * @internal
      */
     readonly consentStrategy?: ConsentStrategy;
+    /**
+     * tree-shake seam — optional read-coverage SENSOR. Pass `withCoverage()`
+     * from `@noy-db/hub/coverage` to account how much of a `bulk: 'sensitive'`
+     * collection each principal has ever decrypted, and to emit
+     * `'coverage:threshold'` when a declared coverage threshold is crossed.
+     *
+     * ⛔⛔ TELEMETRY, NOT A CONTROL. Against an insider holding the device and
+     * local keys it prevents nothing — they hold the DEK. It makes bulk
+     * extraction visible early, attributable and loud. The remediation is key
+     * custody (tiers, per-collection DEKs). It never refuses a read.
+     *
+     * When omitted, `NO_COVERAGE` resolves no observer at all: the decrypt path
+     * holds `undefined` and the sensor's code never reaches the bundle.
+     *
+     * @internal
+     */
+    readonly coverageStrategy?: CoverageStrategy;
     /**
      * tree-shake seam — optional periods strategy. Pass
      * `withPeriods()` from `@noy-db/hub/periods` to enable
@@ -2839,7 +2907,7 @@ export interface NoydbOptions {
      *     takes an {@link EchoSecretParts} struct instead of a plain
      *     string (spec design-history/2026-08-02-echo-secret-design.md, #940).
      *
-     * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/session-tiers.md → Managed-secret mode
+     * @see https://github.com/noy-db/docs/blob/main/content/docs/services/session-tiers.md → Managed-secret mode
      */
     readonly secretMode?: 'standard' | 'echo' | 'managed';
     /**
@@ -2984,7 +3052,7 @@ export interface NoydbOptions {
      */
     readonly onInvalidKey?: 'error' | 'reset';
     /**
-     * Enable the cover service (`https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/public-envelope.md`).
+     * Enable the cover service (`https://github.com/noy-db/docs/blob/main/content/docs/services/public-envelope.md`).
      * Pass `true` for the default schema (every standard field, 256 KB
      * icon cap, 200-char text cap), or a `CoverSchema` to narrow what
      * the owner can set. Off by default — vaults written by hubs