@noy-db/hub 0.3.0-pre.8 → 0.3.0

package/dist/with-cargo/extract-partition.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Partition extraction. Walks the FK closure, re-encrypts
+ * the selected records under fresh per-collection DEKs, seals those DEKs
+ * under a one-time transfer key, and serializes an unowned
+ * `extracted-partition` bundle.
+ *
+ * @module
+ */
+import type { Vault } from '../kernel/vault.js';
+import type { EncryptedEnvelope } from '../kernel/types.js';
+import { type EnclaveKey } from '../kernel/enclave/index.js';
+import { type WalkClosureOptions, type DanglingRefNotice } from './walk-closure.js';
+import { type TransferSealPayload } from '../with-pod/bundle.js';
+/** Re-keyed collections snapshot + the fresh DEKs used. */
+export interface ReKeyResult {
+    readonly collections: Record<string, Record<string, EncryptedEnvelope>>;
+    readonly deks: Map<string, EnclaveKey>;
+}
+/**
+ * Re-encrypt every record in `closure` under a fresh per-collection DEK.
+ * Reads raw source envelopes, decrypts under the source DEK, re-encrypts
+ * under the new DEK. Plaintext-pipeline: requires an unlocked vault.
+ */
+export declare function reKeyClosure(vault: Vault, closure: Map<string, Set<string>>, fieldProjection?: Record<string, readonly string[]>): Promise<ReKeyResult>;
+/**
+ * Re-key the persisted JSON Schemas (`_schemas/<collection>`) for the
+ * closure collections under the destination DEKs. Returns a
+ * `{ collection: envelope }` map for the carried collections that actually
+ * have a schema; collections without one are omitted.
+ */
+export declare function reKeySchemas(vault: Vault, closure: Map<string, Set<string>>, destDeks: Map<string, EnclaveKey>, fieldProjection?: Record<string, readonly string[]>): Promise<Record<string, EncryptedEnvelope>>;
+export interface ReKeyLedgerResult {
+    /** { paddedIndex: re-encrypted entry envelope } for backup._internal._ledger. */
+    readonly entries: Record<string, EncryptedEnvelope>;
+    /** Recomputed ledgerHead for the carried chain (index -1 when empty). */
+    readonly head: {
+        hash: string;
+        index: number;
+        ts: string;
+    };
+}
+/**
+ * Build the carried `_ledger` chain for an extracted partition.
+ * Filters source entries to the closure, RE-CHAINS them (fresh index + prevHash),
+ * and re-encrypts under `ledgerDek`. The `payloadHash` is recomputed against the
+ * re-keyed envelope ONLY for the latest `put` per (collection,id) — the entry
+ * `verifyBackupIntegrity` cross-checks; earlier puts + deletes keep their source
+ * `payloadHash` verbatim (recomputing an intermediate put would assert a false
+ * hash for an older version). Amendments + out-of-closure entries are dropped;
+ * `_ledger_deltas`/`_history` are deferred to slice 2.
+ */
+export declare function reKeyLedger(vault: Vault, closure: Map<string, Set<string>>, reKeyedCollections: Record<string, Record<string, EncryptedEnvelope>>, ledgerDek: EnclaveKey): Promise<ReKeyLedgerResult>;
+/** Carried blob internals + the fresh transfer `_blob` DEK (present only when
+ * the closure references at least one chunk-based blob). */
+export interface ReKeyBlobsResult {
+    /** `_blob_slots_<C>` / `_blob_versions_<C>` / `_blob_index` / `_blob_chunks`
+     * envelopes for the bundle's `_internal` map. */
+    readonly internal: Record<string, Record<string, EncryptedEnvelope>>;
+    /** Fresh transfer `_blob` DEK — seal it so owner-creation wraps it under the
+     * recipient KEK. Undefined when no blob travels (source keyring untouched). */
+    readonly blobDek?: EnclaveKey;
+}
+/**
+ * Carry the FK-closed slice's blobs — HARDENED key handling (no master-key leak).
+ *
+ * The source vault's shared `_blob` DEK decrypts (or unwraps the content CEK of)
+ * EVERY blob in the source. Sealing it into the transfer would hand the recipient
+ * a key to blobs far outside their slice. Instead we mint a **fresh transfer
+ * `_blob` DEK** and arrange every carried blob into per-blob-CEK mode under it:
+ *
+ *  - **erasable blob** (`_cek` present): unwrap the per-blob content CEK under the
+ *    SOURCE `_blob` DEK, re-wrap it under the FRESH transfer DEK. Chunks travel
+ *    **verbatim** (still ciphertext under that same content CEK — passthrough).
+ *  - **legacy blob** (no `_cek`, chunks under the shared `_blob` DEK): promote it
+ *    IN-BUNDLE — mint a fresh content CEK, decrypt each chunk under the source
+ *    `_blob` DEK and re-encrypt under the content CEK (same AAD, so the eTag-bound
+ *    integrity holds), then wrap the content CEK under the transfer DEK. The
+ *    SOURCE is never mutated (non-destructive), and the bundle never holds
+ *    plaintext blob bytes (zero-knowledge preserved).
+ *
+ * **eTag identity is preserved** (not re-HMAC'd). eTags are HMAC-keyed off the
+ * `_blob` DEK, but they are stored as OPAQUE keys (`_blob_index/<eTag>`,
+ * `_blob_chunks/<eTag>_<i>`) and never recomputed on read — only on a `put()`
+ * for dedup. Keeping them verbatim keeps every slot/version/index/chunk key and
+ * the chunk AAD coherent with zero chunk-key churn. The only consequence: a
+ * future `put()` of identical bytes in the adopted vault computes a different
+ * eTag (HMAC under the fresh DEK) and will NOT dedup against the carried blob —
+ * an accepted, documented trade for hardened key isolation.
+ *
+ * Slots/versions are re-keyed under their parent collection's destination DEK
+ * (honoring `fieldProjection` — projected-out blob fields' slots never travel);
+ * `BlobObject.refCount` is recomputed from carried references only.
+ *
+ * `external` slots reference an unencrypted shared-bucket object that is not in
+ * the bundle — their slot metadata travels (so the catalog entry survives) but
+ * the bytes do not (a documented v1 limitation; their eTag is `''`).
+ */
+export declare function reKeyBlobs(vault: Vault, closure: Map<string, Set<string>>, destDeks: Map<string, EnclaveKey>, fieldProjection?: Record<string, readonly string[]>): Promise<ReKeyBlobsResult>;
+/** A minted transfer key (raw 32 bytes) + the seal carrying the DEK set. */
+export interface SealResult {
+    readonly seal: TransferSealPayload;
+    readonly transferKey: Uint8Array;
+}
+/**
+ * Mint a random 32-byte transfer key, export each DEK to raw bytes, and
+ * AES-256-GCM-seal the `{ collection: base64(rawDEK) }` map under the
+ * transfer key. The transfer key is returned to the caller out-of-band;
+ * only the sealed bytes travel in the bundle. Layout: iv(12) ‖ ct ‖ tag.
+ */
+export declare function sealDeks(deks: Map<string, EnclaveKey>): Promise<SealResult>;
+export interface ExtractPartitionResult {
+    readonly bundleBytes: Uint8Array;
+    /** Raw 32-byte transfer key — deliver out-of-band; required to adopt. */
+    readonly transferKey: Uint8Array;
+    readonly sealId: string;
+    /**
+     * #759: outbound FK edges whose referenced parent was excluded from the
+     * partition (missing, or tier-elevated and therefore invisible). The
+     * child record still carries its FK value; the parent did not travel —
+     * callers should surface this to the operator rather than assume
+     * referential completeness.
+     */
+    readonly danglingRefs: ReadonlyArray<DanglingRefNotice>;
+}
+/**
+ * Extract a re-keyed, transfer-sealed partition. Owner-only
+ * (invariant 5): producing a standalone re-keyed vault is an
+ * ownership operation. Non-destructive on the source.
+ */
+export type ExtractPartitionOptions = WalkClosureOptions & {
+    readonly compression?: 'auto' | 'brotli' | 'gzip' | 'none';
+    readonly carrySchemas?: boolean;
+    readonly carryLedger?: boolean;
+    /**
+     * FR-7 structural field projection: per-collection allow-list of fields
+     * to keep. Non-listed fields are dropped from each record BEFORE
+     * re-encryption (so they never travel in the bundle); `id` is always
+     * preserved. A projected collection's persisted schema is NOT carried.
+     * Absent/empty → un-projected behavior (byte-identical to today).
+     */
+    readonly fieldProjection?: Record<string, readonly string[]>;
+};
+/**
+ * Public extract-partition entry — gated behind `cargoStrategy: withCargo()`
+ * (S4). Routes through the source vault's cargo strategy so an un-opted-in
+ * caller hits `NO_CARGO`'s throw; `withCargo()` dynamically imports and runs
+ * {@link extractPartitionCore} (the crypto engine, kept out of the floor).
+ */
+export declare function extractPartition(vault: Vault, opts: ExtractPartitionOptions): Promise<ExtractPartitionResult>;
+/**
+ * The extract-partition crypto engine — reached only when `withCargo()` is
+ * opted in (via the lazy `with-cargo/active.ts` chunk). Body unchanged from the
+ * hardened implementation; only the public gate wraps it.
+ */
+export declare function extractPartitionCore(vault: Vault, opts: ExtractPartitionOptions): Promise<ExtractPartitionResult>;

package/dist/with-cargo/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * **@noy-db/hub/cargo** — the orchestration seam klum binds. Canonical
+ * successor to `/kernel` (the published `/kernel` subpath alias has been
+ * retired — coordinated removal, consumers migrated).
+ *
+ * `cargo` is the layer of services + interfaces required to **manage pods** —
+ * the multi-vault management plane klum-db binds: custody, deed, diff,
+ * distributed query, addressing, and change-observation. It consolidates the
+ * runtime floor formerly published as `/kernel` plus the orchestration delta.
+ *
+ * See docs/superpowers/specs/2026-07-01-noydb-architecture-lexicon.md.
+ *
+ * @packageDocumentation
+ */
+export * from '../legacy/kernel.js';
+export { CustodyApi } from '../with-party/custody/index.js';
+export type { GrantCustodianOptions } from '../with-party/custody/index.js';
+export { liberateVault } from '../with-party/custody/liberate.js';
+export type { LiberateOptions, LiberateResult } from '../with-party/custody/liberate.js';
+export { createDeedOwner, loadDeedMarker, isDeedVault } from '../with-party/team/deed.js';
+export type { DeedMarker } from '../with-party/team/deed.js';
+export type { SealingKeyProvider } from '../with-party/team/managed-passphrase.js';
+export { diffVault } from './vault-diff.js';
+export { STATE_VAULT_NAME } from '../kernel/constants.js';
+export { withCargo } from './active.js';
+export { NO_CARGO } from './strategy.js';
+export type { CargoStrategy } from './strategy.js';
+export { CargoNotEnabledError } from '../kernel/errors.js';
+export type { WriteHook } from '../port/with/write-hooks.js';
+export type { WriteQueue } from '../kernel/write-queue.js';
+export type { WriteConflict } from '../kernel/types.js';
+export type { AccessibleVault } from '../kernel/types.js';
+export type { Unsubscribe } from '../kernel/types.js';

package/dist/with-cargo/strategy.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Cargo capability strategy (FR-6/FR-7) — the source-side, owner-level
+ * partition operation that requires a live {@link Vault}: extracting a re-keyed
+ * transfer-sealed partition ({@link extractPartitionCore}). The active engine
+ * ({@link withCargo}) dynamically imports that engine (keeping the extraction
+ * crypto out of the floor bundle); {@link NO_CARGO} throws.
+ *
+ * The public free function `extractPartition` (which takes a `Vault`) delegates
+ * here via `vault.cargoStrategy`, so an un-opted-in caller hits `NO_CARGO`'s
+ * throw.
+ *
+ * Carve-out (mirrors `openSealedRecord` / `liberateVault`): the recipient-side
+ * free functions `adoptPartition` and `decryptExtractedPartition` operate on
+ * raw bundle bytes + a destination store — they carry NO source instance to
+ * gate against, so they stay ungated host-side tooling. `diffVault` is likewise
+ * ungated: it's shared import/merge infrastructure the `as-*` exporters call
+ * internally, not a gated cargo capability.
+ * @internal
+ */
+import type { Vault } from '../kernel/vault.js';
+import type { ExtractPartitionResult, ExtractPartitionOptions } from './extract-partition.js';
+export interface CargoStrategy {
+    extractPartition(vault: Vault, opts: ExtractPartitionOptions): Promise<ExtractPartitionResult>;
+}
+/**
+ * No-op stub — the floor default. The source-side cargo op throws
+ * {@link CargoNotEnabledError}; opt in with `cargoStrategy: withCargo()` in
+ * createNoydb. @internal
+ */
+export declare const NO_CARGO: CargoStrategy;

package/dist/with-cargo/vault-diff.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Vault-level diff orchestrator.
+ *
+ * Compares a live `Vault`'s plaintext state against a candidate state
+ * (another vault, a plain `{ collection: records[] }` map, or a vault
+ * dump JSON) and returns a structured `VaultDiff` plan listing the
+ * records that would be added, modified, or deleted to bring the live
+ * vault into the candidate's shape.
+ *
+ * Builds on two existing record-level helpers:
+ *
+ *   1. `diff(a, b)` from `./history/diff.ts` — emits dot-pathed
+ *      `DiffEntry[]` with `type: 'added' | 'removed' | 'changed'` for
+ *      each changed field of two records. Used here for the
+ *      `fieldDiffs` of every `modified` entry, and (with empty result)
+ *      as the default deep-equal check.
+ *
+ *   2. `Vault.exportStream()` from `./vault.ts` — the canonical
+ *      decrypt-and-stream-records iterator. Used to walk both sides
+ *      when the candidate is itself a `Vault`. ACL-scoped: collections
+ *      the caller can't read silently drop out, the same way every
+ *      other plaintext-emitting export pipeline filters them.
+ *
+ * The new orchestration is the **vault-level** enumeration: bucket
+ * each record id into added (only in candidate), deleted (only in
+ * vault), or modified (in both with field changes); leave the
+ * field-level granularity to the existing `diff()`.
+ *
+ * Use cases:
+ *
+ *   - Import preview (`@noy-db/as-*` `fromString` returns a plan
+ *     whose body is a `VaultDiff`).
+ *   - Backup verification ("does this `.noydb` bundle from yesterday
+ *     match the current vault?").
+ *   - Two-vault reconciliation ("what's different between Office A
+ *     and Office B before we sync?").
+ *   - Test assertions (golden-file testing with one-liner
+ *     `expect(plan.summary).toEqual(...)`).
+ *
+ * @module
+ */
+import type { Vault } from '../kernel/vault.js';
+import { type DiffEntry as FieldDiffEntry } from '../with-commit/history/diff.js';
+/** Per-record entry shape — added and deleted records carry only the record value. */
+export interface VaultDiffEntry<T = unknown> {
+    readonly collection: string;
+    readonly id: string;
+    readonly record: T;
+    /**
+     * Unencrypted envelope metadata for the RECEIVER-side record.
+     * Populated only when `diffVault` is called with `{includeMetadata: true}`.
+     * Default: `undefined` (zero extra reads, no behavior change).
+     *
+     * Populated for `modified` (the CURRENT receiver state, before the candidate
+     * is applied) and `deleted` (the receiver envelope of the record being
+     * removed). `added` entries have no receiver envelope at diff time, so their
+     * `metadata` is always absent.
+     */
+    readonly metadata?: {
+        readonly version: number;
+        readonly timestamp: string;
+        readonly by?: string;
+        readonly source?: string;
+        readonly sourceTs?: string;
+    };
+}
+/** Modified records carry both halves of the diff plus the field-level breakdown. */
+export interface VaultDiffModifiedEntry<T = unknown> extends VaultDiffEntry<T> {
+    /** The record as it stands in the live vault. */
+    readonly before: T;
+    /** Top-level keys whose values differ between `before` and `record`. */
+    readonly fieldsChanged: readonly string[];
+    /**
+     * Field-level diff entries from `diff(before, record)`. Reuses the
+     * existing per-record diff helper so consumers can render git-style
+     * `path: from → to` rows without re-walking the records.
+     */
+    readonly fieldDiffs: readonly FieldDiffEntry[];
+}
+export interface VaultDiff<T = unknown> {
+    readonly added: readonly VaultDiffEntry<T>[];
+    readonly modified: readonly VaultDiffModifiedEntry<T>[];
+    readonly deleted: readonly VaultDiffEntry<T>[];
+    /** Only populated when `options.includeUnchanged: true`. */
+    readonly unchanged: readonly VaultDiffEntry<T>[] | undefined;
+    readonly summary: {
+        readonly add: number;
+        readonly modify: number;
+        readonly delete: number;
+        readonly total: number;
+    };
+    /**
+     * Format the diff as a human-readable string.
+     *
+     *   - `'count'`   — one line, just the numbers (`12 added · 3 modified · 0 deleted`)
+     *   - `'one-line'` — count plus a single overview line
+     *   - `'full'`    — count + one row per added/modified/deleted record (default)
+     */
+    format(opts?: {
+        detail?: 'count' | 'one-line' | 'full';
+    }): string;
+}
+export interface DiffOptions {
+    /** Restrict the diff to a subset of collections. */
+    readonly collections?: readonly string[];
+    /** Field on each record that carries its id. Defaults to `'id'`. */
+    readonly idKey?: string;
+    /** Override the default deep-equal check for "modified vs unchanged". */
+    readonly compareFn?: (a: unknown, b: unknown) => boolean;
+    /** If true, include unchanged records in the diff (off by default to save memory). */
+    readonly includeUnchanged?: boolean;
+    /**
+     * When `true`, each entry in `added`, `modified`, and `deleted` will carry a
+     * `metadata` field with the RECEIVER-side envelope metadata
+     * (`version`, `timestamp`, `by?`, `source?`, `sourceTs?`).
+     *
+     * Off by default — no extra adapter reads, no behavior change for existing callers.
+     */
+    readonly includeMetadata?: boolean;
+}
+/**
+ * Candidate state to diff the vault against:
+ *
+ *   - A `Vault` instance — both sides are walked via `exportStream()`.
+ *   - A `Record<collection, records[]>` map — same shape `as-json.toObject()`
+ *     produces. Useful for diffing parsed file content against the live vault.
+ *   - A `VaultDump` (output of `vault.dump()`) — a JSON string carrying the
+ *     full vault state. Parsed and reduced to the map shape above.
+ */
+export type DiffCandidate<T = unknown> = Vault | Record<string, readonly T[]> | string;
+/**
+ * Compute the diff between a live vault and a candidate state.
+ *
+ * Ungated shared import/merge infrastructure: the `as-*` exporters call this
+ * internally from their `fromString`/import merge logic, so it is always
+ * available (not behind `withCargo()`). Only `extractPartition` is a gated
+ * cargo capability.
+ *
+ * Returns a fully buffered `VaultDiff` — no streaming. Memory cost is
+ * O(n + m) in the row count of vault + candidate. For documented
+ * 1K-50K-record vaults this is fine; a streaming variant lands as a
+ * follow-up if a > 100K-record consumer arrives.
+ */
+export declare function diffVault<T = unknown>(vault: Vault, candidate: DiffCandidate<T>, options?: DiffOptions): Promise<VaultDiff<T>>;

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

@@ -0,0 +1,67 @@
+/**
+ * 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 VISIBLE parent the selected set
+ *      references, transitively, WITHOUT re-expanding inbound from those
+ *      parents (bounds the closure). A tier-elevated (or missing) parent is
+ *      excluded rather than admitted — see `danglingRefs` on the result.
+ *
+ * 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;
+}
+/**
+ * #759: an outbound FK edge whose referenced parent was excluded from the
+ * closure — either because it doesn't exist, or because it is tier-elevated
+ * and therefore invisible (same "elevated ≡ missing" semantics as root
+ * selection / inbound expansion). The child keeps its FK value; the parent
+ * does not travel. Callers (extract-partition) surface this as a residue
+ * notice rather than silently dropping it.
+ */
+export interface DanglingRefNotice {
+    /** Collection of the child record that holds the dangling FK. */
+    readonly collection: string;
+    /** Id of the child record. */
+    readonly id: string;
+    /** FK field on the child that references the missing/elevated parent. */
+    readonly field: string;
+    /** Target collection the FK points at. */
+    readonly target: string;
+    /** Id of the missing/elevated parent. */
+    readonly targetId: string;
+    /**
+     * #772: distinguishes an intentional tier boundary (`'elevated'` — the
+     * parent exists but is above the caller's readable tier) from a genuine
+     * data-integrity gap (`'missing'` — no envelope for `targetId` at all).
+     */
+    readonly reason: 'missing' | 'elevated';
+}
+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;
+    };
+    /** #759: outbound FK edges whose parent was excluded (missing or elevated). */
+    readonly danglingRefs: ReadonlyArray<DanglingRefNotice>;
+}
+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;