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

package/dist/kernel/types.d.ts

@@ -656,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>;
@@ -1159,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;
@@ -1322,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;
 }
@@ -1331,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;
@@ -1348,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
@@ -1415,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
@@ -1451,6 +1732,29 @@ 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
@@ -1487,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`
@@ -1524,6 +1860,8 @@ 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;
     /**
@@ -1615,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`.
      *
@@ -1673,6 +2013,19 @@ export interface NoydbEventMap {
     '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;
@@ -1857,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;

package/dist/kernel/vault.d.ts

@@ -1,7 +1,7 @@
 import type { OpenCollectionOptions } from '../port/with/collection-options.js';
 import type { StrategyBag } from '../port/with/strategies.js';
 import type { NoydbFormat, ImportPlan, FormatExportOptions, FormatImportOptions } from '../port/with/formats-strategy.js';
-import type { NoydbStore, EncryptedEnvelope, HistoryConfig, ExportStreamOptions, ExportChunk, CollectionConflictResolver, CrossTierAccessEvent, Role, VaultUserApi, CollectionShape, SensitiveOf, IndexedOf, MoneyOf } from './types.js';
+import type { NoydbStore, EncryptedEnvelope, SyncRejection, LoadPodOptions, LoadPodResult, RestoreToOptions, RestoreToResult, HistoryConfig, ExportStreamOptions, ExportChunk, CollectionConflictResolver, CrossTierAccessEvent, Role, VaultUserApi, CollectionShape, SensitiveOf, IndexedOf, MoneyOf } from './types.js';
 import type { Noydb } from './noydb.js';
 import type { IssueDelegationOptions, DelegationToken } from '../with-party/team/delegation.js';
 import { Collection } from './collection.js';
@@ -69,7 +69,7 @@ export declare class Vault {
     private keyring;
     private readonly encrypted;
     private readonly emitter;
-    private readonly onDirty;
+    private onDirty;
     private readonly onRegisterConflictResolver;
     private readonly syncAdapter;
     private readonly getPurgeableTargets;
@@ -140,6 +140,7 @@ export declare class Vault {
      *  `load()` after the on-disk keyring file has been replaced. Provided by Noydb at openVault()
      *  time; `undefined` in tests that construct Vault directly (load() then skips the refresh). */
     private readonly reloadKeyring;
+    private readonly onRestore;
     private readonly collectionCache;
     private satelliteRegistry;
     /** Vault-level schema cutover fence/controller. */
@@ -239,7 +240,7 @@ export declare class Vault {
     /** — currently-active elevation, or null. One per vault. */
     private activeElevation;
     /**
-     * Optional translator callback threaded from `Noydb.invokeTranslator`.
+     * Optional translator callback threaded from `Noydb._invokeTranslator`.
      * Present only when `plaintextTranslator` was configured on `createNoydb()`.
      */
     private readonly translateText;
@@ -253,6 +254,8 @@ export declare class Vault {
         onDirty?: OnDirtyCallback | undefined;
         historyConfig?: HistoryConfig | undefined;
         reloadKeyring?: (() => Promise<UnlockedKeyring>) | undefined;
+        /** core#71 — reset the vault's sync engines after a restore (`load()`). */
+        onRestore?: (() => Promise<void>) | undefined;
         /** Vault-default locale. */
         locale?: string | undefined;
         /** Translator callback from Noydb. */
@@ -373,6 +376,17 @@ export declare class Vault {
      *  its already-warmed `LookupHandle._syncCache` (membership/altIndex/snapshot reads never see a
      *  stale verdict for a pulled vocabulary edit) and collect the touch into any open graph batch
      *  (the sync-apply wave-reachability seam Task 5's ref edges will use). No-op if never warmed. */
+    /** core#74 — admission of a sync-applied record: the collection's own gates and hooks judge it. Reserved names are never gated. @internal */
+    _admitRemote(collection: string, id: string, envelope: EncryptedEnvelope, origin?: 'sync-apply' | 'push-recheck'): Promise<{
+        admitted: true;
+    } | {
+        admitted: false;
+        reason: string;
+    }>;
+    /** @internal core#107 — seal a refusal under the refused record's own collection DEK. `null`: no DEK here. */
+    _sealRejection(collection: string, id: string, rejection: SyncRejection, version: number): Promise<EncryptedEnvelope | null>;
+    /** @internal core#107 — open a replicated refusal. `null` when this device holds no DEK for it. */
+    _openRejection(collection: string, id: string, envelope: EncryptedEnvelope): Promise<SyncRejection | null>;
     _invalidateSyncApplied(collection: string, id: string, action: 'put' | 'delete'): Promise<void>;
     /** @internal #650 Task 4 (#647) — declared reserved-lookup collection names, for `SyncEngine.pull()`'s explicit prefix registry. */
     _reservedLookupCollectionNames(): readonly string[];
@@ -1152,7 +1166,7 @@ export declare class Vault {
      * collection.
      */
     delegate(opts: IssueDelegationOptions): Promise<DelegationToken>;
-    /** Merge live delegations into the keyring — core#56's read half. Explicit, not automatic; cross-user delegation does not work yet. Both reasons: `with-party/team/delegation.ts`. */
+    /** Merge live delegations addressed to this user into the keyring — core#56's read half, cross-user since core#65. Explicit, never automatic: `with-party/team/delegation.ts` says why. */
     refreshDelegations(now?: Date): Promise<DelegationToken[]>;
     /**
      * revoke an issued delegation by id. Safe to call even
@@ -1391,6 +1405,8 @@ export declare class Vault {
      * collection-cache clear, ledger-store reset) that `load()` performs on this
      * Vault's private state.
      */
+    /** core#90 — the first `attachSyncTarget()` on a vault opened without one: from here every write is dirty-tracked. Cached collection handles are rebuilt (as after `load()`); re-acquire handles obtained before the attach. */
+    _enableSync(onDirty: OnDirtyCallback): void;
     /** core#82 — sync pulled a newer copy of THIS user's keyring file: reload it in place, rebuild the DEK resolver, drop cached collections. */
     _reloadKeyringAfterSync(): Promise<void>;
     private backupContext;
@@ -1416,7 +1432,25 @@ export declare class Vault {
      * with a console warning and skip the integrity check entirely
      * — there's no chain to verify against.
      */
-    load(backupJson: string): Promise<void>;
+    /**
+     * core#76 — restore this vault to its state at `timestamp`, as FORWARD
+     * WRITES. Every record whose state at T differs from its state now is put
+     * back at T's value; every record that exists now and did not exist at T is
+     * deleted.
+     *
+     * ⭐ The writes go through `Collection.put`/`.delete`, so guards, periods,
+     * history and the ledger all see them. The restore is therefore an audited,
+     * reversible event that replicates through ordinary sync — no pod, and none
+     * of the state-replacement machinery core#71/#72 exists to make safe.
+     *
+     * `{ dryRun: true }` returns the same report having written nothing.
+     *
+     * ⚠️ Bounded by history retention, and ⛔ blobs are not restored — see the
+     * module header on `with-commit/history/restore-to.ts`, which states both
+     * limits and why the blob one is not reported rather than reported empty.
+     */
+    restoreTo(timestamp: string | Date, options?: RestoreToOptions): Promise<RestoreToResult>;
+    load(backupJson: string, options?: LoadPodOptions): Promise<LoadPodResult>;
     /**
      * End-to-end backup integrity check. Runs both:
      *

package/dist/{ledger-MSJGWKGW.js → ledger-MZ25UFT2.js}

@@ -3,7 +3,7 @@ import {
   LedgerStore,
   applyPatch,
   computePatch
-} from "./chunk-L2F3CFCH.js";
+} from "./chunk-ONZ3B5EW.js";
 import {
   LEDGER_COLLECTION,
   LEDGER_DELTAS_COLLECTION
@@ -15,15 +15,15 @@ import {
   paddedIndex,
   parseIndex,
   sha256Hex
-} from "./chunk-2WJKJZSO.js";
-import "./chunk-4J3MNVVX.js";
-import "./chunk-ZBUAX4EF.js";
-import "./chunk-SPPOUJLN.js";
+} from "./chunk-QHG7GQKM.js";
+import "./chunk-WRLWEYHY.js";
+import "./chunk-ZD7WFMV2.js";
+import "./chunk-RRTQAQ3N.js";
 import "./chunk-NH2UOV3B.js";
-import "./chunk-OM3SEDI4.js";
-import "./chunk-PUBI455O.js";
-import "./chunk-2ELOCEXE.js";
-import "./chunk-VSUQI5Q6.js";
+import "./chunk-ZF6JECDT.js";
+import "./chunk-THQ3BHLM.js";
+import "./chunk-XX4R7TUB.js";
+import "./chunk-IKPQ2GGB.js";
 export {
   LEDGER_COLLECTION,
   LEDGER_DELTAS_COLLECTION,
@@ -37,4 +37,4 @@ export {
   parseIndex,
   sha256Hex
 };
-//# sourceMappingURL=ledger-MSJGWKGW.js.map
+//# sourceMappingURL=ledger-MZ25UFT2.js.map

package/dist/liberate-OJIP2ZFX.js

@@ -0,0 +1,25 @@
+import {
+  liberateVault
+} from "./chunk-LUCQY3OM.js";
+import "./chunk-R2ZULFXU.js";
+import "./chunk-KN4LUMH6.js";
+import "./chunk-NTVKHQ3L.js";
+import "./chunk-XPW7T2GN.js";
+import "./chunk-DMIEKD24.js";
+import "./chunk-GMKGGY7V.js";
+import "./chunk-V7AKGAXY.js";
+import "./chunk-QT5ITL25.js";
+import "./chunk-NXQEOC3X.js";
+import "./chunk-2LBS62AC.js";
+import "./chunk-WRLWEYHY.js";
+import "./chunk-ZD7WFMV2.js";
+import "./chunk-RRTQAQ3N.js";
+import "./chunk-NH2UOV3B.js";
+import "./chunk-ZF6JECDT.js";
+import "./chunk-THQ3BHLM.js";
+import "./chunk-XX4R7TUB.js";
+import "./chunk-IKPQ2GGB.js";
+export {
+  liberateVault
+};
+//# sourceMappingURL=liberate-OJIP2ZFX.js.map