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

package/dist/with-cargo/walk-closure.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Transitive-closure FK walker. Computes the set of
+ * (collection, id) tuples reachable from seed predicates, so a
+ * partition extraction ships a referentially-complete subset.
+ *
+ * Two-phase, plaintext, read-only (runs inside the unlocked vault
+ * session — see foundation §13.4 / spec invariant 7):
+ *   1. INBOUND expansion: from selected records, pull every record
+ *      that references them (children travel with parents), to a
+ *      fixed point.
+ *   2. OUTBOUND completion: pull every parent the selected set
+ *      references (no dangling FKs), transitively, WITHOUT
+ *      re-expanding inbound from those parents (bounds the closure).
+ *
+ * The FK graph is auto-derived from the vault's existing RefRegistry
+ * (the `ref('target')` declarations on collections) — no hand-written
+ * edge list.
+ *
+ * @module
+ */
+import type { Vault } from '../kernel/vault.js';
+/** Seed predicate per collection. Records that return true become roots. */
+export interface WalkClosureOptions {
+    readonly seeds: Record<string, (record: Record<string, unknown>) => boolean | Promise<boolean>>;
+    /** Max fixed-point iterations before throwing. Default 16. */
+    readonly maxDepth?: number;
+}
+export interface ClosureResult {
+    /** collection → set of record ids that travel together. */
+    readonly closure: Map<string, Set<string>>;
+    readonly graph: {
+        /** Fixed-point iterations the walk needed to converge. */
+        readonly depth: number;
+        /** True if an edge pointed back to an already-selected node. */
+        readonly cyclesDetected: boolean;
+    };
+}
+export declare function walkClosure(vault: Vault, opts: WalkClosureOptions): Promise<ClosureResult>;

package/dist/with-commit/crdt/active.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Active CRDT strategy factory. Calling `withCrdt()` returns a
+ * `CrdtStrategy` whose methods delegate to the real LWW-Map / RGA /
+ * merge / snapshot helpers in `./crdt.ts`. Only reachable through
+ * the `@noy-db/hub/crdt` subpath.
+ */
+import type { CrdtStrategy } from './strategy.js';
+/**
+ * Build the default CRDT strategy. Pass into
+ * `createNoydb({ crdtStrategy: withCrdt() })` to enable collections
+ * declared with `crdt: 'lww-map' | 'rga' | 'yjs'`.
+ *
+ * @example
+ * ```ts
+ * import { createNoydb } from '@noy-db/hub'
+ * import { withCrdt } from '@noy-db/hub/crdt'
+ *
+ * const db = await createNoydb({
+ *   store, user, secret,
+ *   crdtStrategy: withCrdt(),
+ * })
+ * const notes = vault.collection('notes', { crdt: 'lww-map' })
+ * ```
+ */
+export declare function withCrdt(): CrdtStrategy;

package/dist/with-commit/crdt/crdt.d.ts

@@ -0,0 +1,42 @@
+/**
+ * CRDT state types, merge logic, and build helpers.
+ * per-collection CRDT mode: 'lww-map' | 'rga' | 'yjs'
+ *
+ * The encrypted envelope wraps the CRDT state (not the resolved snapshot).
+ * Adapters only ever see ciphertext. `collection.get(id)` returns the
+ * resolved snapshot; `collection.getRaw(id)` returns the full CRDT state.
+ */
+import type { CrdtState, LwwMapState, RgaState } from '../../kernel/types.js';
+export type { CrdtMode, CrdtState, LwwMapState, RgaState, YjsState } from '../../kernel/types.js';
+/**
+ * Resolve a CRDT state into the end-user record snapshot.
+ *
+ * - `lww-map` → `Record<string, unknown>` (field values extracted from registers)
+ * - `rga`     → `unknown[]` (non-tombstoned items in insertion order)
+ * - `yjs`     → `string` (base64 update blob; use @noy-db/yjs for a Y.Doc)
+ */
+export declare function resolveCrdtSnapshot(state: CrdtState): unknown;
+/**
+ * Merge two CRDT states produced by concurrent writes.
+ * Called by the collection-level conflict resolver registered with SyncEngine.
+ *
+ * For `yjs`: core cannot merge Yjs without importing the `yjs` package.
+ * The caller must handle that case by falling back to the higher-`_v` envelope.
+ */
+export declare function mergeCrdtStates(a: CrdtState, b: CrdtState): CrdtState;
+/**
+ * Build (or update) an lww-map state from a new record.
+ *
+ * All fields in the new record win at timestamp `now`.
+ * Fields present in the existing state but absent from the new record
+ * are preserved (they were written by another device).
+ */
+export declare function buildLwwMapState(record: Record<string, unknown>, existing: LwwMapState | undefined, now: string): LwwMapState;
+/**
+ * Build (or update) an RGA state from a new array.
+ *
+ * Existing items are matched to new elements by deep-equality of their `v`.
+ * Unmatched existing items are tombstoned. New elements that have no existing
+ * match get a fresh NID via `generateNid()`.
+ */
+export declare function buildRgaState(arr: unknown[], existing: RgaState | undefined, generateNid: () => string): RgaState;

package/dist/with-commit/crdt/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @noy-db/hub/crdt — opt-in CRDT (conflict-free replicated data type)
+ * service.
+ *
+ * @category capability
+ *
+ * Collaborative-editing primitives: LWW-Map, RGA (sequence CRDT), and
+ * a Yjs bridge state shape. Enabled per-collection via
+ * `collection(name, { crdt: 'lww-map' | 'rga' | 'yjs' })`. Apps that
+ * stick to plain record-level last-write-wins can omit this subpath
+ * and save ~221 LOC of state / merge / snapshot helpers.
+ */
+export { withCrdt } from './active.js';
+export type { CrdtStrategy } from './strategy.js';
+export { resolveCrdtSnapshot, mergeCrdtStates, buildLwwMapState, buildRgaState, } from './crdt.js';
+export type { CrdtMode, CrdtState, LwwMapState, RgaState, YjsState, } from './crdt.js';

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

@@ -0,0 +1,25 @@
+/**
+ * Strategy seam between core Collection and the optional CRDT
+ * service. Core imports `CrdtStrategy` as a TYPE-ONLY symbol and
+ * `NO_CRDT` as a minimal runtime stub.
+ *
+ * The state-construction / merge / snapshot-resolution helpers —
+ * `buildLwwMapState`, `buildRgaState`, `mergeCrdtStates`,
+ * `resolveCrdtSnapshot` — are only reachable from `withCrdt()` in
+ * `./active.ts`, which is only exported through the `@noy-db/hub/crdt`
+ * subpath. Consumers without CRDT mode configured never pull the
+ * ~221 LOC into their bundle.
+ *
+ * @internal
+ */
+import type { CrdtStrategy } from '../../kernel/types.js';
+export type { CrdtStrategy } from '../../kernel/types.js';
+/**
+ * No-CRDT stub. Every method throws with a pointer at the subpath.
+ * If a Collection declares `crdt: '...'` without this strategy wired,
+ * the first put/sync-merge/read that hits the CRDT path surfaces the
+ * error immediately.
+ *
+ * @internal
+ */
+export declare const NO_CRDT: CrdtStrategy;

package/dist/with-commit/history/active.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Active history strategy — `withHistory()` returns the real
+ * implementation that wires per-record snapshots, the hash-chained
+ * audit ledger, JSON-patch deltas, and time-machine reads into the
+ * core write/read paths.
+ *
+ * Consumers opt in by:
+ *
+ * ```ts
+ * import { createNoydb } from '@noy-db/hub'
+ * import { withHistory } from '@noy-db/hub/history'
+ *
+ * const db = await createNoydb({
+ *   store: ...,
+ *   user: ...,
+ *   historyStrategy: withHistory(),
+ * })
+ * ```
+ *
+ * The factory is a thin wrapper that delegates to the existing
+ * `history.ts`, `diff.ts`, `ledger/store.ts`, `ledger/patch.ts`, and
+ * `time-machine.ts` modules. Splitting the import chain through this
+ * file is what lets `tsup` tree-shake the heavy modules out of the
+ * default `@noy-db/hub` bundle when no `withHistory()` import is
+ * present in the consumer.
+ *
+ * @public
+ */
+import type { HistoryStrategy } from './strategy.js';
+/**
+ * Build the active history strategy. Today the factory takes no
+ * options; per-collection retention tuning still flows through
+ * `HistoryConfig` on `Vault.collection()` / `vault.openVault()`.
+ *
+ * Future option slots (kept off the LTS surface for now):
+ *   - global maxVersions cap
+ *   - global beforeDate prune cadence
+ *   - ledger encryption toggle (today inferred from vault.encrypted)
+ */
+export declare function withHistory(): HistoryStrategy;

package/dist/with-commit/history/diff.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Zero-dependency JSON diff.
+ * Produces a flat list of changes between two plain objects.
+ */
+export type ChangeType = 'added' | 'removed' | 'changed';
+export interface DiffEntry {
+    /** Dot-separated path to the changed field (e.g. "address.city"). */
+    readonly path: string;
+    /** Type of change. */
+    readonly type: ChangeType;
+    /** Previous value (undefined for 'added'). */
+    readonly from?: unknown;
+    /** New value (undefined for 'removed'). */
+    readonly to?: unknown;
+}
+/**
+ * Compute differences between two objects.
+ * Returns an array of DiffEntry describing each changed field.
+ * Returns empty array if objects are identical.
+ */
+export declare function diff(oldObj: unknown, newObj: unknown, basePath?: string): DiffEntry[];
+/** Format a diff as a human-readable string. */
+export declare function formatDiff(changes: DiffEntry[]): string;

package/dist/with-commit/history/history.d.ts

@@ -0,0 +1,27 @@
+import type { NoydbStore, EncryptedEnvelope, HistoryOptions, PruneOptions } from '../../kernel/types.js';
+/** Save a history entry (a complete encrypted envelope snapshot). */
+export declare function saveHistory(adapter: NoydbStore, vault: string, collection: string, recordId: string, envelope: EncryptedEnvelope): Promise<void>;
+/** Get history entries for a record, sorted newest-first. */
+export declare function getHistory(adapter: NoydbStore, vault: string, collection: string, recordId: string, options?: HistoryOptions): Promise<EncryptedEnvelope[]>;
+/** Get a specific version's envelope from history. */
+export declare function getVersionEnvelope(adapter: NoydbStore, vault: string, collection: string, recordId: string, version: number): Promise<EncryptedEnvelope | null>;
+/** Prune history entries. Returns the number of entries deleted. */
+export declare function pruneHistory(adapter: NoydbStore, vault: string, collection: string, recordId: string | undefined, options: PruneOptions): Promise<number>;
+/** Clear all history for a vault, optionally scoped to a collection or record. */
+export declare function clearHistory(adapter: NoydbStore, vault: string, collection?: string, recordId?: string): Promise<number>;
+/**
+ * Crypto-shred every `_history` version of a record. Each non-tombstone
+ * history envelope is OVERWRITTEN in place with a tombstone
+ * `{ _noydb, _v, _ts: now, _by: actor, _iv: '', _data: '' }` — dropping
+ * `_iv`/`_data`/`_cek`/`_det`, so the prior ciphertext (and the wrapped CEK
+ * that could decrypt it) is gone everywhere this store reaches. The version
+ * counter (`_v`) is preserved so the audit trail still shows "N versions
+ * existed and were erased."
+ *
+ * Overwrite — NOT delete — so the history key itself survives as proof the
+ * version existed. Already-tombstoned versions (re-run / idempotent forget)
+ * are left untouched and not counted.
+ *
+ * Returns the number of history versions newly tombstoned.
+ */
+export declare function tombstoneHistory(adapter: NoydbStore, vault: string, collection: string, recordId: string, actor: string, encrypted: boolean): Promise<number>;

package/dist/with-commit/history/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `@noy-db/hub/history` — subpath export for record-history / diff /
+ * ledger-based audit trail + point-in-time primitives.
+ *
+ * Solo apps that don't track versioning, don't need a hash-chained
+ * audit log, and don't restore to earlier points in time can exclude
+ * this entire surface. Bundle savings ~1,880 LOC.
+ *
+ * The strategy seam is `withHistory()` — pass the returned
+ * strategy to `createNoydb({ historyStrategy: ... })`. Without it,
+ * the core `NO_HISTORY` stub no-ops snapshots/prune/clear and throws
+ * on read APIs (`history`, `getVersion`, `diff`, `vault.at`,
+ * `vault.ledger`).
+ *
+ * Named re-exports (not `export *`) so tsup keeps the barrel
+ * populated even with `sideEffects: false`.
+ */
+export { withHistory } from './active.js';
+export type { HistoryStrategy } from './strategy.js';
+export { saveHistory, getHistory, getVersionEnvelope, pruneHistory, clearHistory, } from './history.js';
+export { diff, formatDiff } from './diff.js';
+export type { ChangeType, DiffEntry } from './diff.js';
+export { LedgerStore, LEDGER_COLLECTION, LEDGER_DELTAS_COLLECTION, envelopePayloadHash, } from './ledger/store.js';
+export type { AppendInput, VerifyResult } from './ledger/store.js';
+export { canonicalJson, sha256Hex, hashEntry, paddedIndex, parseIndex, } from './ledger/entry.js';
+export type { LedgerEntry } from './ledger/entry.js';
+export { computePatch, applyPatch } from './ledger/patch.js';
+export type { JsonPatch, JsonPatchOp } from './ledger/patch.js';
+export { VaultInstant, CollectionInstant } from './time-machine.js';
+export type { VaultEngine } from './time-machine.js';

package/dist/with-commit/history/ledger/constants.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Ledger storage constants — pinned in their own leaf module so
+ * always-on core code (vault.ts, dictionary.ts) can import them
+ * without dragging the `LedgerStore` class into the bundle.
+ *
+ * `splitting: true` in tsup is not enough on its own: when a
+ * source file exports both pure constants and a heavyweight class,
+ * the bundler keeps the entire chunk reachable from any importer.
+ * Extracting the constants lets the floor scenario import them
+ * without paying for the class.
+ *
+ * @internal
+ */
+/** The internal collection name used for ledger entry storage. */
+export declare const LEDGER_COLLECTION = "_ledger";
+/**
+ * The internal collection name used for delta payload storage.
+ *
+ * Deltas live in a sibling collection (not inside `_ledger`) for two
+ * reasons:
+ *
+ *   1. **Listing efficiency.** `ledger.loadAllEntries()` calls
+ *      `adapter.list(_ledger)` which would otherwise return every
+ *      delta key alongside every entry key. Splitting them keeps the
+ *      list small (one key per ledger entry) and the delta reads
+ *      keyed by the entry's index.
+ *
+ *   2. **Prune-friendliness.** A future `pruneHistory()` will delete
+ *      old deltas while keeping the ledger chain intact (folding old
+ *      deltas into a base snapshot). Separating the storage makes
+ *      that deletion a targeted operation on one collection instead
+ *      of a filter across a mixed list.
+ *
+ * Both collections share the same ledger DEK — one DEK, two
+ * internal collections, same zero-knowledge guarantees.
+ */
+export declare const LEDGER_DELTAS_COLLECTION = "_ledger_deltas";

package/dist/with-commit/history/ledger/entry.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Ledger entry shape + canonical JSON + sha256 helpers.
+ *
+ * This file holds the PURE primitives used by the hash-chained ledger:
+ * the entry type, the deterministic (sort-stable) JSON encoder, and
+ * the sha256 hasher that produces `prevHash` and `ledger.head()`.
+ *
+ * Everything here is validator-free and side-effect free — the only
+ * runtime dep is Web Crypto's `subtle.digest` for the sha256 call,
+ * which we already use for every other hashing operation in the core.
+ *
+ * The hash chain property works like this:
+ *
+ *   hash(entry[i])       = sha256(canonicalJSON(entry[i]))
+ *   entry[i+1].prevHash  = hash(entry[i])
+ *
+ * Any modification to `entry[i]` (field values, field order, whitespace)
+ * produces a different `hash(entry[i])`, which means `entry[i+1]`'s
+ * stored `prevHash` no longer matches the recomputed hash, which means
+ * `verify()` returns `{ ok: false, divergedAt: i + 1 }`. The chain is
+ * append-only and tamper-evident without external anchoring.
+ */
+export interface LedgerEntry {
+    /**
+     * Zero-based sequential position of this entry in the chain. The
+     * canonical adapter key is this number zero-padded to 10 digits
+     * (`"0000000001"`) so lexicographic ordering matches numeric order.
+     */
+    readonly index: number;
+    /**
+     * Hex-encoded sha256 of the canonical JSON of the PREVIOUS entry.
+     * The genesis entry (index 0) has `prevHash === ''` — the first
+     * entry in a fresh vault has nothing to point back to.
+     */
+    readonly prevHash: string;
+    /**
+     * Which kind of mutation this entry records. only supports
+     * data operations (`put`, `delete`, `amendment`). Access-control
+     * operations (`grant`, `revoke`, `rotate`) will be added in a
+     * follow-up once the keyring write path is instrumented — that's
+     * tracked in the epic issue.
+     *
+     * `'amendment'` is the multi-record audit entry written by the
+     * guards service when an admin/owner uses `withTransactions(...)`
+     * to repair a constraint-violating state. See `amendment` field
+     * below for the structured payload.
+     *
+     * `'lifecycle'` records a non-data audit event (e.g. partition
+     * handover) — `collection`/`id` are empty and the event detail
+     * lives in `reason` (e.g. `'partition-handed-over:<sealId>'`). Like
+     * `amendment`, it carries no data envelope, so `verifyBackupIntegrity`
+     * skips it in the data cross-check (it still participates in the
+     * tamper-evident chain).
+     *
+     * `'forget'` is the single summary entry written by `vault.forget()`
+     * (GDPR crypto-shred). `collection`/`id` are empty and `version`
+     * is 0 — a forget is not scoped to one record. `payloadHash` carries
+     * `sha256Hex(subjectId)` so the ledger PROVES "subject X existed and
+     * was erased on date D" without retaining the subject id or any
+     * plaintext; `reason` holds a JSON summary of the shred counts. Like
+     * `amendment`/`lifecycle` it carries no data envelope and is skipped
+     * by the reconstruct walker (it still participates in the chain, so
+     * `verify()` passes after a shred).
+     */
+    readonly op: 'put' | 'delete' | 'amendment' | 'lifecycle' | 'migration' | 'forget';
+    /** The collection the mutation targeted. */
+    readonly collection: string;
+    /** The record id the mutation targeted. */
+    readonly id: string;
+    /**
+     * The record version AFTER this mutation. For `put` this is the
+     * newly assigned version; for `delete` this is the version that
+     * was deleted (the last version visible to reads).
+     */
+    readonly version: number;
+    /** ISO timestamp of the mutation. */
+    readonly ts: string;
+    /** User id of the actor who performed the mutation. */
+    readonly actor: string;
+    /**
+     * Hex-encoded sha256 over the encrypted envelope's `_data` field, plus its
+     * sealed-field ciphertext map (`_sealed`) when the record carries one —
+     * so the ledger attests to both the open body and every sealed
+     * value. A record with no `_sealed` hashes `_data` alone.
+     * For `put`, this is the hash of the new ciphertext. For `delete`,
+     * it's the hash of the last visible ciphertext at deletion time, or the empty
+     * string if nothing was there to delete. Hashing the ciphertext (not the
+     * plaintext) preserves zero-knowledge — see the file docstring. The exact
+     * recipe lives in `envelopePayloadHash` (`hash.ts`).
+     */
+    readonly payloadHash: string;
+    /**
+     * Optional human-readable tag describing why this mutation happened.
+     * Threaded through `collection.put(_, _, { reason })`. Common
+     * values include `'import:csv'`, `'import:json'`, `'import:xlsx'` from
+     * `as-*` ImportPlan.apply(), but consumers can use any string for
+     * domain-specific audit filtering. Auto-strip via `canonicalJson` —
+     * absent on the wire, never serialized as `null`.
+     *
+     * Audit consumers filter: `entries.filter(e => e.reason?.startsWith('import:'))`.
+     */
+    readonly reason?: string;
+    /**
+     * Optional hex-encoded sha256 of the encrypted JSON Patch delta
+     * blob stored alongside this entry in `_ledger_deltas/`. Present
+     * only for `put` operations that had a previous version — the
+     * genesis put of a new record, and every `delete`, leave this
+     * field undefined.
+     *
+     * The delta payload itself lives in a sibling internal collection
+     * (`_ledger_deltas/<paddedIndex>`) and is encrypted with the
+     * ledger DEK. Callers use `ledger.loadDelta(index)` to decrypt and
+     * deserialize it when reconstructing a historical version.
+     *
+     * Why optional instead of always-present: the first put of a
+     * record has no previous version to diff against, so storing an
+     * empty patch would be noise. For deletes there's no "next" state
+     * to describe with a delta. Both cases set this field to undefined.
+     *
+     * Note: the canonical-JSON hasher treats `undefined` as invalid
+     * (it's one of the guard rails), so on the wire this field is
+     * either `{ deltaHash: '<hex>' }` or absent from the JSON
+     * entirely — never `{ deltaHash: undefined }`.
+     */
+    readonly deltaHash?: string;
+    /**
+     * Present only when `op === 'amendment'`. Records the human reason,
+     * the role of the actor, the (collection, id, vBefore, vAfter) tuple
+     * for every record touched, and which guard invariants passed.
+     *
+     * See docs/superpowers/specs/2026-05-18-guards-design.md.
+     */
+    readonly amendment?: {
+        readonly reason: string;
+        readonly role: 'admin' | 'owner';
+        readonly changes: ReadonlyArray<{
+            readonly collection: string;
+            readonly id: string;
+            readonly vBefore: number;
+            readonly vAfter: number;
+        }>;
+        readonly invariantsPassed: ReadonlyArray<string>;
+    };
+}
+/**
+ * Canonical (sort-stable) JSON encoder.
+ *
+ * This function is the load-bearing primitive of the hash chain:
+ * `sha256(canonicalJSON(entry))` must produce the same hex string
+ * every time, on every machine, for the same logical entry — otherwise
+ * `verify()` would return `{ ok: false }` on cross-platform reads.
+ *
+ * JavaScript's `JSON.stringify` is almost canonical, but NOT quite:
+ * it preserves the insertion order of object keys, which means
+ * `{a:1,b:2}` and `{b:2,a:1}` serialize differently. We fix this by
+ * recursively walking objects and sorting their keys before
+ * concatenation.
+ *
+ * Arrays keep their original order (reordering them would change
+ * semantics). Numbers, strings, booleans, and `null` use the default
+ * JSON encoding. `undefined` and functions are rejected — ledger
+ * entries are plain data, and silently dropping `undefined` would
+ * break the "same input → same hash" property if a caller forgot to
+ * omit a field.
+ *
+ * Performance: one pass per nesting level; O(n log n) for key sorting
+ * at each object. Entries are small (< 1 KB) so this is negligible
+ * compared to the sha256 call.
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * Compute a hex-encoded sha256 of a string via Web Crypto's subtle API.
+ *
+ * We use hex (not base64) for hashes because hex is case-insensitive,
+ * fixed-length (64 chars), and easier to compare visually in debug
+ * output. Base64 would save a few bytes in storage but every encrypted
+ * ledger entry is already much larger than the hash itself.
+ */
+export declare function sha256Hex(input: string): Promise<string>;
+/**
+ * Compute the canonical hash of a ledger entry. Short wrapper around
+ * `canonicalJson` + `sha256Hex`; callers use this instead of composing
+ * the two functions every time, so any future change to the hashing
+ * pipeline (e.g., adding a domain-separation prefix) lives in one place.
+ */
+export declare function hashEntry(entry: LedgerEntry): Promise<string>;
+/**
+ * Pad an index to the canonical 10-digit form used as the adapter key.
+ * Ten digits is enough for ~10 billion ledger entries per vault
+ * — far beyond any realistic use case, but cheap enough that the extra
+ * digits don't hurt storage.
+ */
+export declare function paddedIndex(index: number): string;
+/** Parse a padded adapter key back into a number. Returns NaN on malformed input. */
+export declare function parseIndex(key: string): number;

package/dist/with-commit/history/ledger/hash.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Envelope payload hash — pinned in its own leaf module so consumers
+ * (DictionaryHandle, the active history strategy) can import it
+ * without dragging in the `LedgerStore` class.
+ *
+ * see `constants.ts` for the broader rationale.
+ *
+ * @internal
+ */
+import type { EncryptedEnvelope } from '../../../kernel/types.js';
+/**
+ * Compute the `payloadHash` value for an encrypted envelope. Used by
+ * `LedgerStore.append` for both put (hash the new envelope) and
+ * delete (hash the previous envelope) paths, and by
+ * `DictionaryHandle` so its ledger entries match the same contract.
+ *
+ * Hashes the open `_data` ciphertext, plus the sealed-field ciphertext
+ * map (`_sealed`) when a record carries one — so the ledger attests to
+ * both the open body AND every sealed value … and the verify-digest
+ * ciphertext map (`_vdig`), each bound only when present — the `_vdig`
+ * binding is the temporal-rollback detector for the C1 splice class.
+ * `rotateRecordCek` rewrites `_vdig` with no ledger entry, the same
+ * pre-existing rotation property `_sealed`/`_cek` already have
+ * (`verifyBackupIntegrity` flags rotated records until re-anchored).
+ *
+ * Returns the empty string when there is no envelope (delete of a
+ * never-existed record). The empty string tolerated by the ledger
+ * entry's `payloadHash` field as the canonical "nothing here" value.
+ */
+export declare function envelopePayloadHash(envelope: EncryptedEnvelope | null): Promise<string>;

package/dist/with-commit/history/ledger/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Public surface of the ledger module.
+ *
+ * Consumers import these symbols via `@noy-db/core`:
+ *
+ * ```ts
+ * import { LedgerStore, canonicalJson, hashEntry } from '@noy-db/hub'
+ * import type { LedgerEntry, VerifyResult } from '@noy-db/hub'
+ * ```
+ *
+ * The LedgerStore class itself is exported so test code and advanced
+ * users can construct one directly, but the recommended entry point is
+ * `vault.ledger()` which takes care of wiring the DEK resolver
+ * and actor id from the active keyring.
+ */
+export { LedgerStore, LEDGER_COLLECTION, LEDGER_DELTAS_COLLECTION, envelopePayloadHash, type AppendInput, type VerifyResult, } from './store.js';
+export { canonicalJson, sha256Hex, hashEntry, paddedIndex, parseIndex, type LedgerEntry, } from './entry.js';
+export { computePatch, applyPatch } from './patch.js';
+export type { JsonPatch, JsonPatchOp } from './patch.js';

package/dist/with-commit/history/ledger/patch.d.ts

@@ -0,0 +1,99 @@
+/**
+ * RFC 6902 JSON Patch — compute + apply.
+ *
+ * This module is the "delta history" primitive: instead of
+ * snapshotting the full record on every put (the behavior),
+ * `Collection.put` computes a JSON Patch from the previous version to
+ * the new version and stores only the patch in the ledger. To
+ * reconstruct version N, we walk from the genesis snapshot forward
+ * applying patches. Storage scales with **edit size**, not record
+ * size — a 10 KB record edited 1000 times costs ~10 KB of deltas
+ * instead of ~10 MB of snapshots.
+ *
+ * ## Why hand-roll instead of using a library?
+ *
+ * RFC 6902 has good libraries (`fast-json-patch`, `rfc6902`) but every
+ * single one of them adds a runtime dependency to `@noy-db/core`. The
+ * "zero runtime dependencies" promise is one of the core's load-bearing
+ * features, and the patch surface we actually need is small enough
+ * (~150 LoC) that vendoring is the right call.
+ *
+ * What we implement:
+ *   - `add`     — insert a value at a path
+ *   - `remove`  — delete the value at a path
+ *   - `replace` — overwrite the value at a path
+ *
+ * What we deliberately skip (out of scope for the ledger use):
+ *   - `move` and `copy` — optimizations; the diff algorithm doesn't
+ *     emit them, so the apply path doesn't need them
+ *   - `test` — used for transactional patches; we already have
+ *     optimistic concurrency via `_v` at the envelope layer
+ *   - Sophisticated array diffing (LCS, edit distance) — we treat
+ *     arrays as atomic values and emit a single `replace` op when
+ *     they differ. The accounting domain has small arrays where this
+ *     is fine; if we ever need patch-level array diffing we can add
+ *     it without changing the storage format.
+ *
+ * ## Path encoding (RFC 6902 §3)
+ *
+ * Paths look like `/foo/bar/0`. Each path segment is either an object
+ * key or a numeric array index. Two characters need escaping inside
+ * keys: `~` becomes `~0` and `/` becomes `~1`. We implement both.
+ *
+ * Empty path (`""`) refers to the root document. Only `replace` makes
+ * sense at the root, and our diff function emits it as a top-level
+ * `replace` when `prev` and `next` differ in shape (object vs array,
+ * primitive vs object, etc.).
+ */
+/** A single JSON Patch operation. Subset of RFC 6902 — see file docstring. */
+export type JsonPatchOp = {
+    readonly op: 'add';
+    readonly path: string;
+    readonly value: unknown;
+} | {
+    readonly op: 'remove';
+    readonly path: string;
+} | {
+    readonly op: 'replace';
+    readonly path: string;
+    readonly value: unknown;
+};
+/** A complete JSON Patch document — an array of operations. */
+export type JsonPatch = readonly JsonPatchOp[];
+/**
+ * Compute a JSON Patch that, when applied to `prev`, produces `next`.
+ *
+ * The algorithm is a straightforward recursive object walk:
+ *
+ *   1. If both inputs are plain objects (and not arrays/null):
+ *      - For each key in `prev`, recurse if `next` has it, else emit `remove`
+ *      - For each key in `next` not in `prev`, emit `add`
+ *   2. If both inputs are arrays AND structurally equal, no-op.
+ *      Otherwise emit a single `replace` for the whole array.
+ *   3. If both inputs are deeply equal primitives, no-op.
+ *   4. Otherwise emit a `replace` at the current path.
+ *
+ * We do not minimize patches across move-like rearrangements — every
+ * generated patch is straightforward enough to apply by hand if you
+ * had to debug it.
+ */
+export declare function computePatch(prev: unknown, next: unknown): JsonPatch;
+/**
+ * Apply a JSON Patch to a base document and return the result.
+ *
+ * The base document is **not mutated** — every op clones the parent
+ * container before writing to it, so the caller's reference to `base`
+ * stays untouched. This costs an extra allocation per op but makes
+ * the apply pipeline reorderable and safe to interrupt.
+ *
+ * Throws on:
+ *   - Removing a path that doesn't exist
+ *   - Adding to a path whose parent doesn't exist
+ *   - A path component that doesn't match the document shape (e.g.,
+ *     trying to step into a primitive)
+ *
+ * Throwing is the right behavior for the ledger use case: a failed
+ * apply means the chain is corrupted, which should be loud rather
+ * than silently producing a wrong reconstruction.
+ */
+export declare function applyPatch<T = unknown>(base: T, patch: JsonPatch): T;