@noy-db/hub 0.3.0-pre.1 → 0.3.0-pre.11

package/dist/with-commit/tx/transaction.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Multi-record atomic transactions.
+ *
+ * Lets an application stage writes across two or more collections (or
+ * vaults) and commit them all-or-nothing.
+ *
+ * ```ts
+ * await db.transaction(async (tx) => {
+ *   const inv = tx.vault('acme').collection<Invoice>('invoices')
+ *   const pay = tx.vault('acme').collection<Payment>('payments')
+ *   await inv.put(invoiceId, { ...invoice, status: 'paid' })
+ *   await pay.put(paymentId, { invoiceId, amount, paidAt })
+ * })
+ * // If the body throws before returning: nothing persisted.
+ * // If the body returns: all puts committed; any CAS mismatch rolls
+ * // the batch back and surfaces as ConflictError.
+ * ```
+ *
+ * ## Atomicity semantics
+ *
+ * Ops are buffered during the body. On body-return the hub:
+ *
+ * 1. **Pre-flight** — re-reads every touched envelope and enforces
+ *    any caller-supplied `expectedVersion`. A mismatch throws
+ *    `ConflictError` with *no* writes performed.
+ * 2. **Execute** — calls `Collection.put()` / `.delete()` for each
+ *    staged op in declaration order. History snapshots, ledger
+ *    appends, and change events fire as normal per op.
+ * 3. **Unwind on failure** — if step 2 throws mid-batch, each
+ *    already-committed op is reverted via the raw store (restoring
+ *    the captured prior envelope, or deleting if none existed). The
+ *    ledger is NOT rewritten — audit history preserves the partial
+ *    commit and the revert.
+ *
+ * **Crash window.** Steps 2–3 are not a storage-layer transaction —
+ * if the process dies between two executed ops, the on-disk state is
+ * partial. True all-or-nothing atomicity requires a store that
+ * implements `NoydbStore.tx()` (DynamoDB `TransactWriteItems`,
+ * IndexedDB `readwrite` transaction, …). This executor declares
+ * that future integration point via the `tx?()` method + the
+ * `StoreCapabilities.txAtomic` bit, but does not yet delegate
+ * to it — the cascade into `Fork · Stores` tracks the per-adapter
+ * wire-up.
+ *
+ * ## Not covered
+ *
+ * - Cross-sync-peer atomicity. Transactions commit against the
+ *   primary store only; the sync engine pushes on its normal
+ *   schedule. For cross-peer two-phase commit use `SyncTransaction`
+ * via `db.transaction(vaultName)`.
+ * - Read-your-writes within the body. `tx.collection().get(id)`
+ *   returns the most-recently-staged value for that id when one
+ *   exists; if no staged op has touched the id, it reads the current
+ *   committed state. Version numbers returned by `get` reflect the
+ *   pre-transaction state (staged puts have no version yet).
+ *
+ * @module
+ */
+import type { Noydb } from '../../kernel/noydb.js';
+import type { Vault } from '../../kernel/vault.js';
+import type { Collection } from '../../kernel/collection.js';
+import type { EncryptedEnvelope } from '../../kernel/types.js';
+import type { TransactionInvariant } from './invariants.js';
+/** One op buffered inside a running `TxContext`. @internal */
+export interface StagedOp {
+    type: 'put' | 'delete';
+    vaultName: string;
+    collectionName: string;
+    id: string;
+    record?: unknown;
+    expectedVersion?: number;
+    /**
+     * Optional human-readable tag forwarded to the resulting ledger
+     * entry's `reason` field. Set by callers via
+     * `tx.vault(v).collection(c).put(id, record, { reason })`.
+     */
+    reason?: string;
+}
+/**
+ * One executed op (main staged op or recursive side-effect like a
+ * derivation output) paired with the envelope captured before the write.
+ * `revertExecuted` walks this array in reverse on rollback.
+ * @internal
+ */
+export interface ExecutedOp {
+    op: StagedOp;
+    priorEnvelope: EncryptedEnvelope | null;
+}
+/**
+ * Options accepted by `db.transaction({ amendment, reason }, fn)`.
+ * Only the amendment variant uses these — a plain `db.transaction(fn)`
+ * never sees this shape.
+ */
+export interface AmendmentTxOptions {
+    /** Opt into amendment mode. Required to be `true`. */
+    readonly amendment: true;
+    /** Human-readable rationale recorded in the ledger entry. Required. */
+    readonly reason: string;
+}
+/**
+ * Transaction handle passed to the user's body. Use
+ * `tx.vault(name).collection<T>(name)` to get a per-collection
+ * facade; its `put`/`delete`/`get` calls stage ops against the tx.
+ */
+export declare class TxContext {
+    /** Stable id for this transaction; shared by all writes it performs. */
+    readonly txId: string;
+    /** @internal */
+    readonly _ops: StagedOp[];
+    /**
+     * @internal — write log built up in Phase 2. Each entry records the
+     * envelope captured BEFORE the write so a mid-batch failure can
+     * restore prior state via `revertExecuted`. Side-effect writes (e.g.
+     * recursive derivation outputs fired inside `Collection.put`) are
+     * appended here in execution order so they roll back alongside the
+     * main staged ops.
+     */
+    readonly _executed: ExecutedOp[];
+    /** @internal */
+    readonly _db: Noydb;
+    /**
+     * @internal — true when this TxContext was opened in amendment
+     * mode. Toggles the lazy-`beginAmendment` + role-check path on first
+     * `tx.vault(name)` and unlocks the post-Phase-2 invariant + audit run.
+     */
+    readonly _amendment: boolean;
+    /** @internal — vaults that have already had `beginAmendment` called. */
+    readonly _amendmentVaults: Map<string, Vault>;
+    /** @internal */
+    constructor(db: Noydb, amendment?: boolean);
+    /** Scope subsequent `collection()` calls to the named vault. */
+    vault(name: string): TxVault;
+}
+/** Per-vault facade inside a running transaction. */
+export declare class TxVault {
+    /** @internal */
+    readonly _ctx: TxContext;
+    /** @internal */
+    readonly _vault: Vault;
+    /** @internal */
+    constructor(ctx: TxContext, vault: Vault);
+    /** Scope subsequent op calls to the named collection. */
+    collection<T>(name: string): TxCollection<T>;
+}
+/** Per-collection facade inside a running transaction. */
+export declare class TxCollection<T> {
+    /** @internal */
+    readonly _ctx: TxContext;
+    /** @internal */
+    readonly _vault: Vault;
+    /** @internal */
+    readonly _coll: Collection<T>;
+    /** @internal */
+    readonly _name: string;
+    /** @internal */
+    constructor(ctx: TxContext, vault: Vault, coll: Collection<T>, name: string);
+    /**
+     * Read the current committed value, or the most-recently-staged
+     * value from the same transaction if one exists.
+     */
+    get(id: string): Promise<T | null>;
+    /**
+     * Stage a put. Does not write until the transaction body returns.
+     * Supply `{ expectedVersion }` to enforce optimistic concurrency
+     * during the commit pre-flight.
+     */
+    put(id: string, record: T, options?: {
+        expectedVersion?: number;
+        reason?: string;
+    }): void;
+    /**
+     * Stage a delete. Does not write until the transaction body returns.
+     * Supply `{ expectedVersion }` to enforce optimistic concurrency
+     * during the commit pre-flight.
+     */
+    delete(id: string, options?: {
+        expectedVersion?: number;
+    }): void;
+}
+/**
+ * Commit plan: pre-flight check + execution + revert plan.
+ *
+ * @internal — driven by `withTransactions()` (via `tx/active.ts`) for
+ * user-facing `db.transaction(...)` calls and by the `amendment` path
+ * in `noydb.ts`. `Collection.putManyAtomic` runs its own Phase 2 loop
+ * but shares the `_activeTxContext` mechanism (and the `revertExecuted`
+ * helper) so nested side-effect derivation writes get registered for
+ * revert alongside the bulk-put source ops.
+ */
+export declare function runTransaction<T>(db: Noydb, fn: (tx: TxContext) => Promise<T> | T, options?: AmendmentTxOptions, txInvariants?: ReadonlyArray<TransactionInvariant>): Promise<T>;
+/**
+ * Phase 3 helper — restore captured prior envelopes via the raw store
+ * to avoid re-firing Collection-level side effects (we don't want a
+ * cascade of change events undoing themselves). The ledger is left
+ * as-is: each committed op appended an entry; the revert is
+ * deliberately NOT recorded as a compensating entry because the
+ * caller-facing contract is "atomic or not at all," not "every write
+ * visible in the audit trail." Auditors who need the intermediate
+ * state can still reconstruct it by walking the ledger through the
+ * failed-tx timestamp.
+ *
+ * @internal — shared between `runTransaction` and
+ * `Collection.putManyAtomic`. Both register source ops + nested
+ * derivation side-effect ops onto `_executed`; this helper unwinds the
+ * combined list in reverse on rollback.
+ */
+export declare function revertExecuted(executed: ReadonlyArray<ExecutedOp>, store: Noydb['_store'], db?: Noydb): Promise<void>;

package/dist/with-fork/archive/engine.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Record cold-storage archival engine.
+ *
+ * Archival relocates a sealed record's **encrypted envelope** from the
+ * primary store to a cold archive store — no re-encryption, the envelope
+ * is opaque ciphertext. Because relocation goes through low-level store
+ * ops (and the collection's `_internalDelete`), it bypasses guards (an
+ * issued/immutable record can still be archived) and never fires
+ * materialized-view dispatch (finalized aggregates over a sealed period
+ * don't recompute). The archive store's contents are themselves the
+ * archived-set index — `listArchived` lists it; `restore` relocates an
+ * envelope back to the primary store.
+ *
+ * A `legalHold` predicate blocks archival; `archiveWhen` (typically
+ * derived from the record's fiscal period / business date) selects
+ * eligible records.
+ */
+import type { NoydbStore, EncryptedEnvelope } from '../../kernel/types.js';
+export interface ArchivePolicy<T = unknown> {
+    /** Select records eligible for archival — typically a business-date / period test. */
+    readonly archiveWhen: (record: T) => boolean;
+    /** Block archival while true (litigation / audit hold). Fail-closed on throw. */
+    readonly legalHold?: (record: T) => boolean;
+}
+export interface ArchiveResult {
+    /** Records relocated to the archive store. */
+    readonly archived: number;
+    /** Records eligible by `archiveWhen` but retained by a `legalHold`. */
+    readonly held: number;
+    /** Records scanned across policy collections. */
+    readonly scanned: number;
+    readonly byCollection: Record<string, {
+        archived: number;
+        held: number;
+    }>;
+}
+export interface ArchiveRunOptions {
+    /** Stop after this many archivals. `undefined` = unbounded. */
+    readonly maxArchives?: number;
+    /** Preview without relocating. */
+    readonly dryRun?: boolean;
+}
+/**
+ * Everything the engine needs from the Vault, injected so the engine
+ * stays unit-testable without a live vault.
+ */
+export interface ArchiveContext {
+    readonly vaultId: string;
+    readonly archiveStore: NoydbStore;
+    /** Collections that declared an `archive` policy. */
+    collectionsWithPolicy(): readonly string[];
+    getPolicy(collection: string): ArchivePolicy | null;
+    listRecordIds(collection: string): Promise<readonly string[]>;
+    /** Decrypted record for policy evaluation, or null if unreadable. */
+    getRecord(collection: string, id: string): Promise<Record<string, unknown> | null>;
+    /** Raw encrypted envelope from the primary store. */
+    getEnvelope(collection: string, id: string): Promise<EncryptedEnvelope | null>;
+    /** Remove from the primary store + cache, bypassing guards/MV (`_internalDelete`). */
+    removeFromPrimary(collection: string, id: string): Promise<void>;
+    /** Write an envelope back to the primary store + refresh cache. */
+    restoreToPrimary(collection: string, id: string, env: EncryptedEnvelope): Promise<void>;
+}
+/** Sweep eligible records into the archive store. */
+export declare function runArchive(ctx: ArchiveContext, options?: ArchiveRunOptions): Promise<ArchiveResult>;
+/** Relocate one archived record back to the primary store. Returns false if not archived. */
+export declare function runRestore(ctx: ArchiveContext, collection: string, id: string): Promise<boolean>;
+/** List archived record ids for a collection (or all policy collections). */
+export declare function runListArchived(ctx: ArchiveContext, collection?: string): Promise<Array<{
+    collection: string;
+    id: string;
+}>>;

package/dist/with-fork/archive/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `@noy-db/hub` record cold-storage archival service.
+ *
+ * `withArchive({ store })` designates a cold {@link NoydbStore} as the
+ * archive target. Declare a per-collection `archive` policy, then call
+ * `vault.archive()` to relocate eligible sealed records there,
+ * `vault.restore(collection, id)` to pull one back, and
+ * `vault.listArchived()` to enumerate the cold set.
+ *
+ * @see ./engine for the relocation logic.
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+export interface WithArchiveOptions {
+    /** The cold store that holds archived record envelopes. */
+    store: NoydbStore;
+}
+export interface ArchiveStrategy {
+    readonly store: NoydbStore;
+}
+/** Enable record cold-storage archival against the given cold store. */
+export declare function withArchive(opts: WithArchiveOptions): ArchiveStrategy;
+export type { ArchivePolicy, ArchiveResult, ArchiveRunOptions, ArchiveContext, } from './engine.js';
+export { runArchive, runRestore, runListArchived } from './engine.js';

package/dist/with-fork/shadow/active.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Active shadow strategy — the only place `VaultFrame` is constructed.
+ * Only reachable through `@noy-db/hub/shadow`.
+ */
+import type { ShadowStrategy } from './strategy.js';
+export declare function withShadow(): ShadowStrategy;

package/dist/with-fork/shadow/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @noy-db/hub/shadow — opt-in vault-frame snapshot primitive.
+ *
+ * @category capability
+ *
+ * `VaultFrame` captures a point-in-time snapshot of a vault's
+ * decrypted records — useful for undo/redo UX, A/B comparisons, and
+ * tests that need a frozen view without a full `vault.dump()`.
+ * Consumers that don't use frames can omit this subpath and the
+ * ~129 LOC never reaches the bundle.
+ */
+export { withShadow } from './active.js';
+export type { ShadowStrategy } from './strategy.js';
+export { VaultFrame, CollectionFrame } from './vault-frame.js';

package/dist/with-fork/shadow/strategy.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Strategy seam for the optional VaultFrame snapshot primitive.
+ * Core imports `ShadowStrategy` as TYPE-ONLY and `NO_SHADOW` as a
+ * 4-line stub. `VaultFrame` is only constructed inside `withShadow()`
+ * — consumers who never import `@noy-db/hub/shadow` ship none of
+ * the ~129 LOC.
+ *
+ * @internal
+ */
+import type { VaultFrame } from './vault-frame.js';
+/**
+ * @internal
+ */
+export interface ShadowStrategy {
+    /**
+     * Build a `VaultFrame` bound to the given vault. The factory type
+     * is kept loose (`unknown`) to avoid a core → shadow type
+     * dependency — the consumer always calls this through
+     * `vault.frame()`, which returns `VaultFrame` at its surface.
+     */
+    buildFrame(vault: unknown): VaultFrame;
+}
+/**
+ * No-shadow stub.
+ *
+ * @internal
+ */
+export declare const NO_SHADOW: ShadowStrategy;

package/dist/with-fork/shadow/vault-frame.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Shadow vaults — `vault.frame()` returns a read-only view of the
+ * CURRENT vault state.
+ *
+ * Companion to {@link VaultInstant} from `history/time-machine.ts`:
+ *
+ * | Type | Reads from | Use case |
+ * |------|------------|----------|
+ * | `VaultInstant` | past snapshots (ledger + history) | "books on date X" |
+ * | `VaultFrame`   | live vault state                  | screen-share / demo / audit |
+ *
+ * ```ts
+ * const readonly = vault.frame()
+ * const invoices = await readonly.collection<Invoice>('invoices').list()
+ * await readonly.collection<Invoice>('invoices').put(...)
+ * // → throws ReadOnlyFrameError
+ * ```
+ *
+ * ## Contract
+ *
+ * Every write method on {@link CollectionFrame} throws
+ * {@link ReadOnlyFrameError}. Reads delegate to the underlying
+ * collection, so validation, locale handling, and caching all work
+ * exactly as they do on the live collection.
+ *
+ * ## Security note: behaviour-enforced, not cryptographically-enforced
+ *
+ * A VaultFrame rejects writes by contract in the JavaScript layer.
+ * It does NOT strip the DEKs from the underlying keyring — the same
+ * in-memory keys that decrypt records could, in principle, encrypt
+ * new writes via a hand-crafted adapter call. Cryptographic
+ * enforcement (keyring variants with the write half of each DEK
+ * removed) is hierarchical-access work. Use a VaultFrame to
+ * prevent *accidental* writes in a read-scoped flow — do not rely on
+ * it as a security boundary against a hostile caller sharing the
+ * same process.
+ *
+ * @module
+ */
+import type { Collection } from '../../kernel/collection.js';
+import type { Query } from '../../kernel/query/builder.js';
+import type { Vault } from '../../kernel/vault.js';
+import type { LocaleReadOptions } from '../../kernel/types.js';
+/**
+ * A read-only view of a vault's current state. Produced by
+ * `vault.frame()`. Cheap to construct; safe to throw away.
+ */
+export declare class VaultFrame {
+    private readonly vault;
+    constructor(vault: Vault);
+    /**
+     * Get a read-only view of one collection. The returned
+     * {@link CollectionFrame} delegates all reads to the underlying
+     * live collection — cache, locale handling, and validation all
+     * work identically to the live collection.
+     */
+    collection<T = unknown>(name: string): CollectionFrame<T>;
+    /** List all collection names visible in the underlying vault. */
+    collections(): Promise<string[]>;
+}
+/**
+ * Read-only collection view. All write methods throw
+ * {@link ReadOnlyFrameError}; all read methods delegate to the
+ * underlying live {@link Collection}.
+ */
+export declare class CollectionFrame<T = unknown> {
+    private readonly inner;
+    /** The underlying collection name. Captured at construction so
+     *  we don't need to peek into the private Collection state. */
+    readonly name: string;
+    constructor(inner: Collection<T>, 
+    /** The underlying collection name. Captured at construction so
+     *  we don't need to peek into the private Collection state. */
+    name: string);
+    get(id: string, locale?: LocaleReadOptions): Promise<T | null>;
+    list(locale?: LocaleReadOptions): Promise<T[]>;
+    /**
+     * Return the chainable query builder. Terminals like `.toArray()`,
+     * `.first()`, `.count()`, `.aggregate()` all work; the builder has
+     * no write surface of its own, so exposing it directly is safe.
+     */
+    query(): Query<T>;
+    query(predicate: (record: T) => boolean): T[];
+    /** History reads — allowed (history is read-only by nature). */
+    history(...args: Parameters<Collection<T>['history']>): ReturnType<Collection<T>['history']>;
+    getVersion(id: string, version: number): Promise<T | null>;
+    put(_id: string, _record: T): Promise<never>;
+    delete(_id: string): Promise<never>;
+    update(_id: string, _patch: Partial<T>): Promise<never>;
+    revert(_id: string, _version: number): Promise<never>;
+    putMany(_entries: ReadonlyArray<readonly [string, T]>): Promise<never>;
+    deleteMany(_ids: readonly string[]): Promise<never>;
+}

package/dist/with-fork/snapshots/active.d.ts

@@ -0,0 +1,20 @@
+import type { SnapshotStrategy, RetentionPolicy } from './strategy.js';
+import type { SnapshotPolicy } from './policy.js';
+import type { NoydbPodStore } from '../../kernel/types.js';
+export interface WithSnapshotsOptions {
+    /** Bundle store where snapshot blobs and the sidecar index are written. */
+    store: NoydbPodStore;
+    /**
+     * Declarative retention policy. Enforced eagerly after each on-demand `snapshot()`.
+     * Defaults to no retention (all on-demand snapshots kept forever). Never affects
+     * the rolling auto-snapshot.
+     */
+    retention?: RetentionPolicy;
+    /**
+     * Automatic-snapshot cadence. Default `mode:'manual'` ⇒ no timers; snapshots
+     * stay on-demand. Set `mode:'debounce'`/`'interval'` to enable auto-snapshots
+     * to the rolling `<vault>__auto` key.
+     */
+    snapshotPolicy?: SnapshotPolicy;
+}
+export declare function withSnapshots(opts: WithSnapshotsOptions): SnapshotStrategy;

package/dist/with-fork/snapshots/engine.d.ts

@@ -0,0 +1,36 @@
+import type { NoydbPodStore } from '../../kernel/types.js';
+import type { Vault } from '../../kernel/vault.js';
+import type { SnapshotMeta, RetentionPolicy, SnapshotIndex } from './strategy.js';
+export declare class SnapshotEngine {
+    private readonly store;
+    private readonly retention;
+    constructor(store: NoydbPodStore, retention: RetentionPolicy);
+    private indexKey;
+    private snapKey;
+    private autoKey;
+    private readIndex;
+    private writeIndex;
+    snapshot(vault: Vault, by: string, opts?: {
+        label?: string;
+        note?: string;
+    }): Promise<SnapshotMeta>;
+    /**
+     * Rolling auto-snapshot. Overwrites the single fixed `<vault>__auto` key and
+     * stores its meta in `index.auto`, separate from the immutable `snapshots`
+     * pool — retention never prunes it. Used by the cadence scheduler.
+     */
+    autoSnapshot(vault: Vault, by: string, opts?: {
+        label?: string;
+        note?: string;
+    }): Promise<SnapshotMeta>;
+    listSnapshots(vaultId: string): Promise<SnapshotMeta[]>;
+    restoreSnapshot(vault: Vault, version: string): Promise<void>;
+    /**
+     * Applies the configured retention policy to `index`, mutating `index.snapshots`
+     * in place and returning the blob keys that should be deleted from the store.
+     * Called by `snapshot()` before the index is written.
+     *
+     * @internal — public for direct testing only
+     */
+    applyRetention(index: SnapshotIndex): string[];
+}

package/dist/with-fork/snapshots/index.d.ts

@@ -0,0 +1,5 @@
+export { withSnapshots } from './active.js';
+export type { WithSnapshotsOptions } from './active.js';
+export type { SnapshotStrategy, SnapshotMeta, RetentionPolicy } from './strategy.js';
+export type { SnapshotPolicy, SnapshotMode } from './policy.js';
+export { SnapshotNotFoundError } from '../../kernel/errors.js';

package/dist/with-fork/snapshots/noydb-facade.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Noydb-side snapshot facade.
+ *
+ * Holds the on-demand checkpoint (`snapshot`), listing (`listSnapshots`),
+ * restore (`restoreSnapshot`), the automatic-snapshot cadence wiring
+ * (`initCadence`), the dirty-vault set, and the cadence scheduler;
+ * `Noydb.close()` calls {@link stop}. Every `Noydb` dependency arrives via
+ * {@link NoydbSnapshotsDeps}.
+ *
+ * Internal service — reached through `noydb.snapshot(...)` etc.
+ */
+import { NO_SNAPSHOTS, type SnapshotStrategy, type SnapshotMeta } from './strategy.js';
+import type { Vault } from '../../kernel/vault.js';
+import type { WriteHook, Unsubscribe } from '../../port/with/write-hooks.js';
+/** Everything the moving snapshot methods touched on the Noydb instance's `this.*`. */
+export interface NoydbSnapshotsDeps {
+    /** Resolved snapshot strategy (NO_SNAPSHOTS when not configured). */
+    readonly strategy: SnapshotStrategy;
+    /** Acting user id, used as the snapshot `by`. */
+    readonly user: string;
+    /** Whether the owning instance has been closed. */
+    isClosed(): boolean;
+    /** Resolve an open vault from the instance's vault cache. */
+    getVault(name: string): Vault | undefined;
+    /** Subscribe to post-write events (cadence dirty-marking). */
+    onAfterWrite(handler: WriteHook): Unsubscribe;
+}
+export declare class NoydbSnapshots {
+    private readonly deps;
+    private scheduler;
+    private readonly dirtyVaults;
+    constructor(deps: NoydbSnapshotsDeps);
+    /**
+     * Take an on-demand checkpoint of the given vault.
+     * Requires `snapshotStrategy: withSnapshots({ store })` in `createNoydb`.
+     * @throws ValidationError when the vault is not open
+     */
+    snapshot(vault: string, opts?: {
+        label?: string;
+        note?: string;
+    }): Promise<SnapshotMeta>;
+    /**
+     * Wire the automatic-snapshot cadence when a non-manual `snapshotPolicy` is
+     * configured. Subscribes to `onAfterWrite` to mark the written vault dirty and
+     * nudge the scheduler; the scheduler fires `autoSnapshot()` per dirty vault.
+     * No-op for `mode:'manual'` or no policy.
+     */
+    private initCadence;
+    /**
+     * List all snapshots for the given vault, newest first.
+     * Reads only the sidecar index — does not download snapshot bytes.
+     */
+    listSnapshots(vault: string): Promise<SnapshotMeta[]>;
+    /**
+     * Restore the vault to a previously snapshotted state.
+     * Runs `verifyBackupIntegrity()` automatically on restore.
+     * @throws SnapshotNotFoundError when `version` doesn't exist in the store
+     * @throws ValidationError when the vault is not open
+     */
+    restoreSnapshot(vault: string, version: string): Promise<void>;
+    /** Stop the cadence scheduler (called from `Noydb.close()`). */
+    stop(): void;
+}
+export { NO_SNAPSHOTS };

package/dist/with-fork/snapshots/policy.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Cadence policy for automatic snapshots. Borrows the vocabulary of the sync
+ * `SyncPolicy` (debounce / interval / minInterval / onUnload) but is a separate,
+ * snapshot-specific shape — automatic snapshots write the single rolling
+ * `<vault>__auto` key, never the immutable on-demand pool.
+ *
+ * Default mode is `'manual'`: no timers, snapshots stay on-demand.
+ */
+export type SnapshotMode = 'manual' | 'debounce' | 'interval';
+export interface SnapshotPolicy {
+    /** Trigger mode. Default `'manual'` — no automatic snapshots. */
+    readonly mode?: SnapshotMode;
+    /** Idle delay (ms) after a write before an auto-snapshot fires. `mode:'debounce'`. Default 30_000. */
+    readonly debounceMs?: number;
+    /** Fixed interval (ms). `mode:'interval'`. Default 300_000. */
+    readonly intervalMs?: number;
+    /** Hard floor (ms) between auto-snapshots regardless of mode. Default 0. */
+    readonly minIntervalMs?: number;
+    /** Flush a pending auto-snapshot on tab-hide / process exit. Default true for non-manual modes. */
+    readonly onUnload?: boolean;
+    /** Label applied to each auto-snapshot. Default `'auto'`. */
+    readonly label?: string;
+}

package/dist/with-fork/snapshots/scheduler.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Owns timers + unload hooks for the automatic snapshot cadence. Distinct from
+ * the sync `SyncScheduler` (whose push/pull/dirty-count shape doesn't map to
+ * snapshots) — it borrows only the policy vocabulary. Delegates the actual
+ * snapshot work to `callbacks.fire()`.
+ */
+import type { SnapshotPolicy } from './policy.js';
+export interface SnapshotSchedulerCallbacks {
+    /** Fire one auto-snapshot cycle (per dirty vault). Swallows its own per-vault errors. */
+    fire(): Promise<void>;
+    /** Number of vaults with pending writes since the last fire. */
+    pendingCount(): number;
+}
+export declare class SnapshotScheduler {
+    private readonly policy;
+    private readonly callbacks;
+    private debounceTimer;
+    private intervalTimer;
+    private lastFireTime;
+    private firing;
+    private started;
+    private readonly boundVisibility;
+    private readonly boundUnload;
+    constructor(policy: SnapshotPolicy, callbacks: SnapshotSchedulerCallbacks);
+    start(): void;
+    stop(): void;
+    notifyChange(): void;
+    private resetDebounce;
+    private execFire;
+    private handleVisibility;
+    private handleUnload;
+    private flush;
+    private shouldRegisterUnload;
+}