@noy-db/hub 0.8.0 → 0.9.0-pre.1

package/dist/kernel/types.d.ts

@@ -182,6 +182,29 @@ export type Permissions = Record<string, Permission>;
  * does not move. What changed is that every READER must now cope with absence
  * — which is the whole point, since the store contract at `@noy-db/hub/to` is
  * what an exclave's rows travel through.
+ *
+ * ⛔⛔ THERE ARE TWO KINDS OF BODY, AND CONFLATING THEM IS A REAL BUG. This
+ * cost a downstream package real time in 0.8.0, so it is written here rather
+ * than left to be rediscovered:
+ *
+ *   - **A SEALED body** — `_iv` is a real IV and `_data` is ciphertext. Ask
+ *     {@link hasSealedBody}, which tests `_iv`.
+ *   - **A PLAINTEXT body** — `_data` holds readable JSON and `_iv` is `''`.
+ *     Reserved collections (`_keyring`, `_meta`) and any collection opened
+ *     with `encrypt: false` are this shape, by a convention that predates the
+ *     widening.
+ *
+ * ⛔ So a record can HAVE a body while having NO SEALED body, and
+ * `hasSealedBody` returns **false** for it. Guarding a `_data` read with
+ * `hasSealedBody` therefore rejects every valid record on those collections —
+ * measured: it would reject every enrolled user of a password unlock. To ask
+ * "is there a body to read as text", test `_data` itself (`if (!env._data)`),
+ * which is exactly what the optional type is for.
+ *
+ * ⚠️ And `_iv === ''` is NOT a safe hand-rolled substitute for
+ * `hasSealedBody`. The comparison stays well-typed when `_iv` is absent and
+ * silently answers `false` — four sites inside hub were wrong that way before
+ * the widening landed.
  */
 export interface Envelope {
     readonly _noydb: typeof NOYDB_FORMAT_VERSION;
@@ -229,7 +252,7 @@ export interface Envelope {
      * value)`) without decrypting every record. Leaks equality as a known
      * side channel.
      */
-    readonly _det?: Record<string, string>;
+    readonly _det?: Record<string, DeterministicCipher>;
     /**
      * Structural group-encryption. Map of sensitive field name →
      * per-field sealed ciphertext in `iv:data` form (same shape as a `_det`
@@ -598,7 +621,7 @@ export interface CrossTierAccessEvent {
  * as `iv:data` (both base64, colon-separated) so a single string per
  * field keeps the envelope compact.
  */
-export type DeterministicCipher = string;
+type DeterministicCipher = string;
 /** All records across all collections for a compartment. */
 export type VaultSnapshot = Record<string, Record<string, EncryptedEnvelope>>;
 /**
@@ -633,7 +656,33 @@ export interface NoydbStore {
     capabilities?: StoreCapabilities;
     /** Get a single record. Returns null if not found. */
     get(vault: string, collection: string, id: string): Promise<EncryptedEnvelope | null>;
-    /** Put a record. Throws ConflictError if expectedVersion doesn't match. */
+    /**
+     * Put a record. Throws ConflictError if `expectedVersion` doesn't match.
+     *
+     * ⚠️ **In this tree the comparison happens only when the record EXISTS**
+     * (`memory-store.ts`, `to-file`, `to-browser-idb` all read-then-compare),
+     * so against a missing id the `expectedVersion` is not a failed comparison
+     * — it is no comparison at all, and the write lands.
+     *
+     * That makes `expectedVersion: 0` an exact "must not exist": hub never stores
+     * a version below 1, so the first create is let through and every later one
+     * mismatches.
+     *
+     * ⭐ **Every record store in the family already agrees**, censused by reading
+     * source on 2026-09-24 — the twelve read-then-compare adapters, plus
+     * `to-aws-dynamo`, whose native condition is explicitly
+     * `#v = :expected OR attribute_not_exists(pk)`, plus `to-aws-s3`, which
+     * special-cases `expectedVersion === 0` BY NAME into a real precondition and
+     * throws `ConflictError('Concurrent create: …')`. `to-cloudflare-r2` and
+     * `to-supabase` inherit it by delegation.
+     *
+     * ⛔ **It is still not a contract, and that is the open question.**
+     * `@noy-db/ports/to` asserts none of it — its three CAS cases all operate on
+     * a record that already exists — so this convergence is held by nothing, and
+     * a third-party adapter owes it nothing. Tracked as core#134. hub's keyring
+     * create path passes no `expectedVersion` at all, and moving it is gated on
+     * that assertion landing, not on the adapters.
+     */
     put(vault: string, collection: string, id: string, envelope: EncryptedEnvelope, expectedVersion?: number): Promise<void>;
     /** Delete a record. */
     delete(vault: string, collection: string, id: string): Promise<void>;
@@ -762,9 +811,9 @@ export interface NoydbStore {
      * hub also falls back when the staged batch isn't statically safe
      * to submit as one write set — see `canCommitAtomically`.
      *
-     * Native implementations today: `to-memory` (one synchronous burst of
-     * Map mutations) and the SQL-backed stores in the sibling `noy-db-to`
-     * repo. `to-dynamo` (`TransactWriteItems`) and `to-browser-idb` (one
+     * Native implementations today: hub's own `memoryStore({ full: true })` (one
+     * synchronous burst of Map mutations) and the SQL-backed stores in the
+     * sibling `noy-db-to` repo — `to-memory` among them, since it moved there. `to-dynamo` (`TransactWriteItems`) and `to-browser-idb` (one
      * `readwrite` transaction) CAN implement it but do not yet. File / S3
      * cannot implement it atomically and should omit the method.
      */
@@ -864,7 +913,7 @@ export type VaultPolicyOnDisk = Record<string, unknown>;
  *   `db.recoverSecret` against these throws
  *   {@link RecoveryProfileNotImplementedError}.
  */
-export type RecoveryEnrollment = {
+type RecoveryEnrollment = {
     readonly profile: 'paper';
     /** Number of single-use codes to print at enrollment. */
     readonly codes: number;
@@ -1136,6 +1185,125 @@ export interface KeyringFile {
      * using standard/managed mode, or written before this extension.
      */
     readonly echo?: KeyringEchoBlock;
+    /**
+     * core#96 — the member's INBOX KEY PAIR, minted by the grantor at grant /
+     * recovery time. `pub` is the SPKI public half, plaintext and bound into the
+     * roster tag (a store must not be able to swap it for its own); `priv` is the
+     * PKCS#8 private half sealed under the AES key in `deks[INBOX_KEY_ID]`, which
+     * only this member's KEK unwraps. It lets an owner/admin hand this member a
+     * DEK LATER, without the member's secret — see `inbox`.
+     *
+     * Absent on every keyring written before this existed: such a member can be
+     * re-granted (re-keyed) but not amended in place (`MemberInboxMissingError`).
+     */
+    readonly inbox_key?: {
+        readonly pub: string;
+        readonly priv: {
+            readonly iv: string;
+            readonly data: string;
+        };
+    };
+    /**
+     * core#96 — DEKs delivered to this member by `updateUser` and not yet
+     * drained: a random CEK RSA-OAEP-wrapped to `inbox_key.pub` (`cek`), and the
+     * exported DEK set AES-GCM-sealed under that CEK (`iv`/`data`). `slots` names
+     * the collections inside, plaintext, and is bound into the roster tag so the
+     * rotation scope of a later `revoke` cannot be hidden from it.
+     *
+     * Drained by the member's next tier-1 unlock (`loadKeyring`): the DEKs move
+     * into `deks` under the member's own KEK and the field is dropped. A member
+     * who unlocks only through a tier-2 slot sees them at their next tier-1
+     * open. A revoked admin who cached nothing but the file cannot open a box —
+     * the private half never left this member's keyring.
+     */
+    readonly inbox?: ReadonlyArray<KeyringInboxBox>;
+}
+/**
+ * core#96 / core#100 — one sealed delivery to a member: `slots` names the
+ * collections inside (plaintext, tag-bound as the union over all boxes), `cek`
+ * is a random key RSA-OAEP-wrapped to the member's inbox public half, and the
+ * exported DEK set is AES-GCM under it. Deliveries APPEND a box (`updateUser`,
+ * a rotation, a revoke); a caller can never open an earlier box (only the
+ * member's private half can), so nothing is re-sealed or merged. The drain
+ * opens the boxes in order — a later box wins a slot, so a rotation's new key
+ * overrides an earlier pending one.
+ */
+export interface KeyringInboxBox {
+    readonly slots: readonly string[];
+    readonly cek: string;
+    readonly iv: string;
+    readonly data: string;
+}
+/** core#76 — scope and mode for `vault.restoreTo(T)`. */
+export interface RestoreToOptions {
+    /**
+     * Restrict the restore to these collections. Omitted, every collection that
+     * is live now OR appears in history is considered — the union matters,
+     * because a collection dropped since T is absent from the live store and a
+     * restore that skipped it would decline to bring back exactly what was lost.
+     */
+    readonly collections?: readonly string[];
+    /**
+     * Compute the diff and write NOTHING. The result names every id that would
+     * be written or deleted, per collection, so an admin sees the blast radius
+     * before committing to it.
+     */
+    readonly dryRun?: boolean;
+}
+/** core#76 — what `restoreTo(T)` did, or (with `dryRun`) would do. */
+export interface RestoreToResult {
+    /** The target instant, as given. */
+    readonly restoredTo: string;
+    /** True when nothing was written. */
+    readonly dryRun: boolean;
+    /** Records put back to their state at T. */
+    readonly written: number;
+    /** Records that exist now and did not exist at T. */
+    readonly deleted: number;
+    /** Records already identical to their state at T. */
+    readonly unchanged: number;
+    /** Per collection, only where something happened. */
+    readonly collections: Readonly<Record<string, {
+        written: string[];
+        deleted: string[];
+        unchanged: number;
+    }>>;
+}
+/** core#77 — how `vault.load()` reconciles a pod against the current store. */
+export interface LoadPodOptions {
+    /**
+     * `'replace'` (default) is the historical behaviour: `saveAll` the data
+     * collections and rewrite the internal ones. Whole-vault replace,
+     * destructive on SQL adapters, and every envelope is written whether or not
+     * the store already holds it byte-identical.
+     *
+     * `'incremental'` writes only what DIFFERS — envelopes whose `(id, _v)` the
+     * store does not already have — and deletes ids the pod does not carry. ⭐
+     * The END STATE IS THE SAME; only the cost differs. In particular a restore
+     * still rewinds (core#111): ids absent from the pod are deleted, never left
+     * behind, so this is not a merge.
+     *
+     * ⛔ Valid only when the pod and the store are the same vault. A pod from
+     * another vault is refused, because "write only the differences" between
+     * unrelated vaults is not a restore, it is a silent union.
+     */
+    readonly mode?: 'replace' | 'incremental';
+}
+/** core#77 — what an incremental load did, per collection and in total. */
+export interface LoadPodResult {
+    readonly mode: 'replace' | 'incremental';
+    /** Envelopes written because the store lacked them at that version. */
+    readonly written: number;
+    /** Envelopes already present byte-for-version — the saving. */
+    readonly skipped: number;
+    /** Ids the store held and the pod does not carry. */
+    readonly deleted: number;
+    /** Per collection, only where something happened. */
+    readonly collections: Readonly<Record<string, {
+        written: number;
+        skipped: number;
+        deleted: number;
+    }>>;
 }
 export interface VaultBackup {
     readonly _noydb_backup: typeof NOYDB_BACKUP_VERSION;
@@ -1207,6 +1375,28 @@ export interface ExportStreamOptions {
      * (a full, all-locale backup; format packages apply their own locale strategy).
      */
     readonly resolveLabels?: string;
+    /**
+     * Export only these collections. Omitted (the default) exports every
+     * collection the caller can read.
+     *
+     * ⭐ This NARROWS THE READ — the excluded collections are neither fetched
+     * nor decrypted (core#45b). That is the whole point of the option living
+     * here rather than in a caller's filter: until 0.8 `vault.export`'s
+     * `collections` filtered the chunks AFTER `exportStream` had decrypted the
+     * entire vault, so a caller scoping an export to limit what a compromised
+     * process could observe got no such limit. The published JSDoc said so
+     * honestly; this makes the caveat false instead of merely known.
+     *
+     * ⚠️ A name that does not exist yields nothing rather than throwing — a
+     * caller exporting "these, if present" is an ordinary call, and refusing it
+     * would push a pre-check onto every caller.
+     *
+     * ⛔ Internal, underscore-prefixed collections stay unexportable even when
+     * named explicitly. The unscoped path gets that filter free from `loadAll`;
+     * the scoped path applies it itself, because a filter that depends on which
+     * route reached the data is a filter waiting to be lost.
+     */
+    readonly collections?: readonly string[];
 }
 /**
  * One chunk yielded by `Vault.exportStream()`.
@@ -1277,7 +1467,13 @@ export interface DirtyEntry {
     readonly vault: string;
     readonly collection: string;
     readonly id: string;
-    readonly action: 'put' | 'delete';
+    /**
+     * `rekey` (core#100): a DEK rotation re-encrypted this record IN PLACE — same
+     * `_v`, new bytes. Pushed with a CAS at the CURRENT version (a `put` expects
+     * `version - 1`), so a target still at that version takes the new ciphertext
+     * and one that moved on reports a conflict as usual.
+     */
+    readonly action: 'put' | 'delete' | 'rekey';
     readonly version: number;
     readonly timestamp: string;
 }
@@ -1286,6 +1482,32 @@ export interface SyncMetadata {
     readonly last_push: string | null;
     readonly last_pull: string | null;
     readonly dirty: DirtyEntry[];
+    /** core#72 — the target's restore epoch this device last adopted (`_sync/epoch` on the target). Absent before any restore. */
+    readonly epoch?: number;
+}
+/**
+ * core#72 — the record a restorer writes on the target at `_sync/epoch`:
+ * "the vault was REPLACED; merge nothing across this line, resync." Peers read
+ * it at the start of every pull; a newer epoch than the one they adopted parks
+ * their pre-epoch local edits and adopts the target wholesale.
+ */
+export interface SyncEpochRecord {
+    readonly epoch: number;
+    readonly at: string;
+    readonly by: string;
+    readonly replaced: number;
+    readonly tombstoned: number;
+}
+/** core#72 — what `db.replaceRemote(vault)` did. */
+export interface ReplaceRemoteResult {
+    /** The epoch now on the target. */
+    readonly epoch: number;
+    /** Local records written to the target unconditionally (re-versioned above the target's copy where needed). */
+    readonly replaced: number;
+    /** Ids the target held that the local vault does not: delete markers written, so every peer removes them. */
+    readonly tombstoned: number;
+    /** Reserved-collection records mirrored (keyrings, users, broker seeds). */
+    readonly reserved: number;
 }
 export interface Conflict {
     readonly vault: string;
@@ -1303,6 +1525,66 @@ export interface Conflict {
      */
     readonly resolve?: (winner: EncryptedEnvelope | null) => void;
 }
+/** core#74 — one record a pull applied. */
+export interface SyncApplied {
+    readonly collection: string;
+    readonly id: string;
+    readonly action: 'put' | 'delete';
+    /** The local copy this replaced, when there was one at a lower version: its version and its author (`_by`). */
+    readonly replaced?: {
+        readonly version: number;
+        readonly by?: string;
+    };
+}
+/** core#74 — one record a pull refused at admission. Emitted as `sync:rejected` and listed by `db.rejected(vault)`. */
+export interface SyncRejection {
+    readonly vault: string;
+    readonly collection: string;
+    readonly id: string;
+    /** The gate's or hook's message. */
+    readonly reason: string;
+    /** The refused envelope's version. */
+    readonly version: number;
+    /** The refused envelope's author, when it carries one. */
+    readonly by?: string;
+    /** ISO time of the refusal — when it was JUDGED, on the judging device. */
+    readonly at: string;
+    /**
+     * core#107 (pilot-1, witnessed) — ISO time the refused RECORD was written,
+     * from its envelope. Present when the envelope carries one.
+     *
+     * ⭐ Why both: an arbiter judges at PULL time, not at write time, so a
+     * record legitimately written and pushed while a period was open can be
+     * refused later when it re-closes. Under report-only that is harmless, but
+     * a notice saying only `at` reads as "your push was wrong". With `recordAt`
+     * a UI can say what actually happened — written then, refused now.
+     */
+    readonly recordAt?: string;
+    /**
+     * core#108 — which judgement refused it. Set on every path since core#107;
+     * ⚠️ absent only on a rejection parked by an older hub. `'sync-apply'` is a
+     * record that ARRIVED here and was turned away. `'push-recheck'`
+     * is this device's OWN record, refused on the way out: it is still in the
+     * local store and still dirty, so it pushes by itself as soon as it passes
+     * again. ⛔ `readmit()` is a sync-apply affordance — for a push-recheck
+     * parking there is nothing to re-apply, the record never left.
+     *
+     * core#107 — `'arbiter'` is a refusal made on ANOTHER device (the vault's
+     * configured arbiter) and replicated here, which is how the writer finds
+     * out at all. It is REPORT ONLY: the local record is untouched, never
+     * deleted or hidden, and `readmit()` is meaningless for it too — this
+     * device never refused anything.
+     */
+    readonly origin?: 'sync-apply' | 'push-recheck' | 'arbiter';
+}
+/** core#74 — what `db.rejected(vault)` returns: the parked envelopes and their two fates. */
+export interface SyncRejectedApi {
+    list(): Promise<readonly SyncRejection[]>;
+    /** Apply the parked envelope after all — bypassing the gate that refused it — and drop the parking record. */
+    readmit(collection: string, id: string): Promise<void>;
+    /** Drop the parking record; the local copy stays as it was. */
+    discard(collection: string, id: string): Promise<void>;
+}
 /**
  * #590: sync suppressed a live envelope because a crypto-shred tombstone is
  * terminal for its record id. Reported on push/pull results (`erasures`) and
@@ -1370,11 +1652,55 @@ export type CollectionConflictResolver = (id: string, local: EncryptedEnvelope,
 export interface PushOptions {
     /** Only push records belonging to these collections. Omit to push all dirty. */
     collections?: string[];
+    /**
+     * core#92 — "everything local is authoritative, send it": mark EVERY record
+     * in the local store dirty before pushing, so records that reached the store
+     * with no target present (written before `attachSyncTarget()`, or loaded
+     * from a pod — core#71's shape) are pushed. CAS still applies per record:
+     * a remote that already advanced a record resolves through the ordinary
+     * conflict path. Default `false`.
+     */
+    full?: boolean;
+    /**
+     * core#93 — bounded parallelism over the dirty entries: this many in-flight
+     * puts at once. Each record keeps its own CAS and conflict path; only the
+     * interleaving changes. Default `1` (serial, byte-for-byte the previous
+     * behaviour). A cloud store with ~45 ms per put goes from N×45 ms to
+     * roughly N×45/concurrency ms.
+     *
+     * ⚠️ **There is a ceiling, and it is the STORE's partition, not this pool.**
+     * Measured on `to-aws-dynamo` (noy-db/to#10, 300 records against a latency
+     * fake): 1-wide 14.1 s, 8-wide 1.79 s, 32-wide 0.48 s — linear, because
+     * nothing in the adapter serializes. That is not permission to go there
+     * against a real table. The single-table layout puts every record of a vault
+     * under ONE partition key — the vault name IS the whole partition key, which
+     * is the same decision that makes `loadAll()` a single Query — and a
+     * DynamoDB partition tops out at ~1000 write units per second, with an
+     * envelope over 1 KB costing more than one unit. 8-wide at ~45 ms is ~178
+     * writes/sec, comfortably under; raising the knob far past that meets
+     * per-partition throttling, not a connection-pool limit, so a bigger pool is
+     * not the fix. `8` is the number pilot-1 runs and the one to start from.
+     */
+    concurrency?: number;
 }
 /** Options for targeted pull operations. */
 export interface PullOptions {
     /** Only pull these collections. Omit to pull all. */
     collections?: string[];
+    /**
+     * core#81 — walk the remote page by page instead of `loadAll()`: memory is
+     * bounded by one page, and the total is known BEFORE the first record is
+     * applied (one `list()` per collection), so `sync:progress` is real from
+     * the start. Uses the store's `listPage` when it offers one, else
+     * `list` + `get` in batches.
+     *
+     * ⚠️ Scope, stated: the store contract cannot enumerate collections, so a
+     * paged pull walks the collections THIS keyring names (its DEK map) plus
+     * any `collections` filter — the ones the caller can open. A full pull
+     * also carries ciphertext for collections the caller holds no key for;
+     * paged mode cannot. Default `false`.
+     */
+    paged?: boolean;
     /**
      * Only pull records with `_ts` strictly after this ISO timestamp.
      * Stores that implement `listSince` use it directly; others fall back
@@ -1406,6 +1732,58 @@ export interface PushResult {
     readonly errors: Error[];
     /** #590: tombstone enforcements applied during this run (never resolver-visible). */
     readonly erasures?: ErasureEnforcement[];
+    /**
+     * core#96 — reserved-collection records mirrored by this run (`_keyring`,
+     * `_users`, `_broker*`, …): they travel outside the dirty log, so `pushed`
+     * / `pulled` never count them. Present when non-zero, so "did my new key
+     * get out" is observable. A local `_keyring` the target already supersedes
+     * is reported in `conflicts` (collection `_keyring`), never silently dropped.
+     */
+    readonly reserved?: number;
+    /**
+     * core#108 — this device's own dirty records, refused by its OWN gates when
+     * re-judged against current local state just before the push. They were
+     * WITHHELD: nothing left for them, the local copy is untouched, and they
+     * stay dirty so a later push carries them once the rule passes. Present
+     * when non-zero.
+     *
+     * ⛔ NOT AN ERROR, and a sync indicator must not render it as one (pilot-1,
+     * on the shipped behaviour). `pushed: 0` with `rejected` present means
+     * "N records waiting on a rule", not "N records failed": nothing was lost,
+     * nothing needs resubmitting, and the next push carries them by itself once
+     * the rule passes. The failure fates are `errors` and `conflicts`; this is
+     * a third thing and reads as a queue, not a fault.
+     */
+    readonly rejected?: SyncRejection[];
+}
+/**
+ * core#81 — a progress sample during a pull or push. Emitted as
+ * `sync:progress`, throttled (every 25 records or ~250 ms, whichever first),
+ * and mirrored on `SyncTargetStatus.inFlight` for a UI that polls. `total`
+ * is present once the engine knows it: for a pull, after the remote snapshot
+ * has been downloaded (progress then measures the APPLY phase, which is the
+ * long one on an indexed store); for a push, from the first sample (the
+ * dirty log is local). `bytes` approximates ciphertext payload size.
+ */
+export interface SyncProgress {
+    readonly direction: 'pull' | 'push';
+    readonly phase: 'reserved' | 'summaries' | 'records';
+    readonly records: number;
+    readonly bytes: number;
+    readonly total?: {
+        readonly records: number;
+        readonly bytes?: number;
+    };
+}
+/** core#82 — result of `db.realign(vault)`. */
+export interface RealignResult {
+    /** Local user-collection envelopes examined. */
+    readonly checked: number;
+    /** Envelopes that failed to authenticate locally and were replaced from the target. */
+    readonly replaced: number;
+    /** Envelopes that failed locally AND the target's copy failed or was absent — left as they were, listed in `errors`. */
+    readonly unrecoverable: number;
+    readonly errors: Error[];
 }
 export interface PullResult {
     readonly pulled: number;
@@ -1413,6 +1791,38 @@ export interface PullResult {
     readonly errors: Error[];
     /** #590: tombstone enforcements applied during this run (never resolver-visible). */
     readonly erasures?: ErasureEnforcement[];
+    /** core#96 — reserved-collection records mirrored (copied + deleted) by this run; see `PushResult.reserved`. */
+    readonly reserved?: number;
+    /**
+     * core#74 — every record this pull APPLIED, in order, with what it replaced
+     * when the local copy was superseded. This is the per-record visibility a
+     * count cannot give: an app can list what arrived, and a writer whose record
+     * was overwritten by a newer version from another device sees `replaced`
+     * — the "you lost" the conflict path never told it (same-id concurrent edits
+     * resolve to the LAST pusher, reported to that pusher only). Present when
+     * non-empty.
+     */
+    readonly applied?: readonly SyncApplied[];
+    /**
+     * core#74 — records this pull REFUSED at admission: a `beforePut` gate or a
+     * `db.onBeforeWrite` hook on this device threw for the incoming record (a
+     * write into a period closed here, say). Each is parked under
+     * `_sync_rejected` with the envelope intact; the local copy is untouched.
+     * `db.rejected(vault)` lists, readmits or discards them. Present when
+     * non-empty.
+     */
+    readonly rejected?: readonly SyncRejection[];
+    /** core#72 — the target's restore epoch, when the target carries one. */
+    readonly epoch?: number;
+    /**
+     * core#72 — this pull crossed a restore epoch: the target was REPLACED since
+     * this device last synced (`db.replaceRemote` on another device). Every
+     * local edit not yet pushed was parked under `_sync_rejected` (reason
+     * `restore-epoch`, listed by `db.rejected(vault)`), the dirty log was
+     * dropped, and the target's state was adopted wholesale — records the
+     * restore removed arrive as delete markers.
+     */
+    readonly resynced?: true;
     /**
      * #807: present on period-scoped pulls only — per-phase KPI counters
      * (`summaries` = the `_periods` navigation index + companions; `records`
@@ -1450,6 +1860,10 @@ export interface SyncStatus {
     readonly lastPush: string | null;
     /** As {@link SyncStatus.lastPush}, for pulls: last pull that had no errors. */
     readonly lastPull: string | null;
+    /** core#72 — the target's restore epoch this device has adopted, when any. */
+    readonly epoch?: number;
+    /** core#81 — the running sync's latest progress sample, or absent when idle. */
+    readonly inFlight?: SyncProgress;
     /**
      * Whether the **browser** reports network connectivity — driven solely by the
      * global `online`/`offline` events (#1034). It is NOT target reachability: an
@@ -1539,6 +1953,8 @@ export interface SyncTargetStatus {
     readonly lastPush: string | null;
     /** Last pull that completed with no errors, or `null`. */
     readonly lastPull: string | null;
+    /** core#72 — the target's restore epoch this device has adopted, when any. */
+    readonly epoch?: number;
     /**
      * Nothing queued for this target — `dirty === 0`.
      *
@@ -1549,6 +1965,8 @@ export interface SyncTargetStatus {
      * not pulled.
      */
     readonly caughtUp: boolean;
+    /** core#81 — the running sync's latest progress sample, or absent when nothing is in flight. */
+    readonly inFlight?: SyncProgress;
 }
 export interface SyncTargetInfo {
     readonly label: string | undefined;
@@ -1591,8 +2009,23 @@ export interface NoydbEventMap {
     };
     'sync:push': PushResult;
     'sync:pull': PullResult;
+    /** core#81 — emitted while a pull/push runs (throttled); `sync:push`/`sync:pull` stay the terminal events. */
+    'sync:progress': SyncProgress;
     'sync:erasure': ErasureEnforcement;
     'sync:conflict': Conflict;
+    /** core#74 — a pulled record refused by this device's admission gate; parked under `_sync_rejected`. */
+    'sync:rejected': SyncRejection;
+    /** core#72 — this device replaced a target: the epoch it wrote and the counts. */
+    'sync:replace': ReplaceRemoteResult & {
+        readonly vault: string;
+    };
+    /** core#72 — a pull crossed a restore epoch on the target; the local dirty log was parked and the target adopted. */
+    'sync:epoch': {
+        readonly vault: string;
+        readonly from: number | null;
+        readonly to: number;
+        readonly parked: number;
+    };
     'write:conflict': WriteConflict;
     'sync:online': void;
     'sync:offline': void;
@@ -1777,15 +2210,24 @@ export interface GrantOptions {
     readonly initialProfile?: unknown;
 }
 /**
- * Caller payload for `db.updateUser`. Mutate one or more
- * identity fields on an existing keyring without rotating any keys.
+ * Caller payload for `db.updateUser`: change what an EXISTING member may
+ * do, without holding their secret.
  *
  * `role`, `displayName`, and `permissions` live in the plaintext header
  * of `_keyring/<userId>` (the sync engine reads them without keys).
- * Mutating them is a JSON header swap — no DEK rewrap, no KEK
- * required, no authenticator slots touched. Tier-2 slots and recovery
- * enrollments survive unchanged. Last-write-wins through the existing
- * keyring put (same concurrency story as `db.grant` / `db.revoke`).
+ * The member's KEK, salt, authenticator slots and recovery enrollments
+ * are untouched. Last-write-wins through the existing keyring put (same
+ * concurrency story as `db.grant` / `db.revoke`).
+ *
+ * core#96 — a change that WIDENS access (a new collection, a wrap-all
+ * role) delivers the DEKs the member lacks through their keyring inbox
+ * (`KeyringFile.inbox`): sealed to the member's inbox key pair, drained at
+ * their next tier-1 unlock. A change that NARROWS access drops the DEKs
+ * and rotates those collections, exactly as a narrowing `grant` does
+ * (#1097). Before this existed, `updateUser` could name a collection the
+ * member had no key for — a permanently blind slot — and `grant` was the
+ * only widening path, which re-keys the member and needs their CURRENT
+ * secret. Use `grant` to create or re-key; use this to change access.
  *
  * Top-level fields are partial-merge: absent fields are not modified.
  * `null` on `displayName` clears the field (stored as the empty string;
@@ -3664,6 +4106,13 @@ export type ActiveTier = 1 | 2 | 3;
  * duplicated here (rather than imported) because the kernel spine may not
  * statically import a with-* service; see {@link PolicyCheckGateFn}.
  */
+/**
+ * `PolicyCheckGateContext` — PUBLISHED API, reachable from @noy-db/hub, @noy-db/hub/policy. Flagged as unused because
+ * nothing inside hub imports it from this module; a consumer does. Do not narrow
+ * or delete without a seam change (#55).
+ *
+ * @public
+ */
 export interface PolicyCheckGateContext {
     /** Tier the active session currently holds. */
     readonly activeTier: ActiveTier;

package/dist/kernel/validation.d.ts

@@ -135,16 +135,6 @@ export declare function assertStrongSecret(s: string, opts?: SecretPolicy & {
  * weak inputs visible in any UI that displays an entropy meter.
  */
 export declare function estimateEntropy(secret: string): number;
-/**
- * Internal compatibility shim. Older code paths used the throwing
- * `validateSecret(s)` directly; some still do via re-exports. Routes
- * to the new `assertStrongSecret` so the contract holds for both
- * shapes during the transition. New code should call
- * {@link assertStrongSecret} directly.
- *
- * @internal
- */
-export declare function legacyAssertSecret(s: string): void;
 /** Dedicated floors for the echo mode's three parts (spec resolved Q1/Q5). */
 export interface EchoSecretPolicy {
     /** Floor for the typed prompt — the brute-forceable-in-isolation part. */