@noy-db/hub 0.3.0-pre.9 → 0.4.0-pre.0

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

@@ -0,0 +1,68 @@
+/**
+ * Commit-time changeset invariants for ordinary transactions.
+ *
+ * Today the only set-level invariant hook is `amendment.invariant`, which
+ * fires solely inside `db.transaction({ amendment: true }, …)` and requires
+ * an admin/owner role plus a registered guard. That is the right shape for
+ * the WORM-override path, but normal application transactions also need
+ * cross-record invariants that hold on every commit — e.g. niwat's
+ * `assertR1` ("every payment is 100% receipted").
+ *
+ * `withTransactions({ invariants: [...] })` registers such invariants. Each
+ * one names a `scope` (a collection) and a `check(changes, ctx)` callback
+ * that receives the commit's change-set for that collection.
+ *
+ * ## Semantics
+ *
+ * - **`scope`** is a collection name. An invariant fires only when the
+ *   committed transaction wrote at least one record in that collection.
+ * - **When** — at commit, AFTER Phase 2 has executed all staged ops (so
+ *   `after` reflects the written record), and after the amendment commit
+ *   phase. It runs for BOTH ordinary and amendment transactions — an
+ *   amendment is still a commit and is still subject to these invariants.
+ * - **`changes`** — one `{ before, after }` pair per touched id (deduped to
+ *   the last write per id, preserving write order). `before` is the
+ *   plaintext prior record (captured in Phase 1 before the overwrite),
+ *   `null` for an insert. `after` is the written record, `null` for a
+ *   delete.
+ * - **Throw → revert.** A throw reverts every executed op (via the shared
+ *   `revertExecuted` unwind) and is surfaced as `InvariantError` (an
+ *   `InvariantError` thrown by the check passes through unwrapped).
+ *
+ * ```ts
+ * createNoydb({ txStrategy: withTransactions({
+ *   invariants: [{
+ *     scope: 'payments',
+ *     check(changes) {
+ *       for (const { after } of changes) {
+ *         const p = after as Payment | null
+ *         if (p && p.receiptAmount !== p.amount) {
+ *           throw new InvariantError('R1: payment not fully receipted')
+ *         }
+ *       }
+ *     },
+ *   }],
+ * }) })
+ * ```
+ */
+import type { GuardChange, GuardContext } from '../../with-audit/guards/types.js';
+/**
+ * A commit-time set-level invariant for ordinary (and amendment)
+ * transactions. See module docs for full semantics.
+ */
+export interface TransactionInvariant {
+    /**
+     * The collection this invariant watches. The `check` fires only when the
+     * committed transaction wrote at least one record in this collection.
+     */
+    readonly scope: string;
+    /**
+     * Validate the change-set for {@link scope}. `changes` carries one
+     * `{ before, after }` pair per touched id (deduped to last-write,
+     * write-order preserved); `before` is the plaintext prior record (null
+     * on insert), `after` is the written record (null on delete). Throw to
+     * revert the whole transaction — the throw is surfaced as
+     * `InvariantError`.
+     */
+    check: (changes: ReadonlyArray<GuardChange<unknown>>, ctx: GuardContext<unknown>) => Promise<void> | void;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Strategy seam for the optional multi-record transaction service.
+ * `runTransaction` is only reachable through `withTransactions()`
+ * exported from `@noy-db/hub/tx`. Consumers who don't use
+ * `db.transaction(fn)` ship none of the ~288 LOC.
+ *
+ * @internal
+ */
+import type { Noydb } from '../../kernel/noydb.js';
+import type { TxContext, AmendmentTxOptions } from './transaction.js';
+import type { DryRunResult } from './dry-run.js';
+import type { TransactionInvariant } from './invariants.js';
+/**
+ * @internal
+ */
+export interface TxStrategy {
+    runTransaction<T>(db: Noydb, fn: (tx: TxContext) => Promise<T> | T, options?: AmendmentTxOptions, txInvariants?: ReadonlyArray<TransactionInvariant>): Promise<T>;
+    runDryRun(db: Noydb, fn: (tx: TxContext) => unknown): Promise<DryRunResult>;
+}
+/**
+ * @internal
+ */
+export declare const NO_TX: TxStrategy;

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

@@ -0,0 +1,212 @@
+/**
+ * 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.
+ *
+ * Delegates the reverse/best-effort/raw-revert shape to the shared
+ * `bestEffortRevert` helper (`kernel/best-effort-revert.ts`); the cache
+ * invalidation below rides along as that helper's per-leg `compensate`
+ * callback, gated on `db` exactly as before.
+ *
+ * @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';