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

package/dist/with-audit/tiers/index.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Hierarchical access — the collection-level tier operations
+ * (`putAtTier` / `getAtTier` / `listAtTier` / `elevate` / `demote`).
+ *
+ * A collection opted into `{ tiers: [...] }` stamps `_tier: N` on each envelope
+ * and encrypts its body under the tier-N DEK. These helpers are the read/write
+ * surface for that scheme: write at a tier, read with tier-aware visibility
+ * (invisibility vs. ghost), and move a record up (`elevate`) or down (`demote`)
+ * the tier ladder by re-wrapping its body key.
+ *
+ * Each function takes a small {@link TiersContext} (the exact `this.*` the
+ * moving methods touched) instead of `this`, mirroring the `record-keys/`
+ * siblings. Behaviour is byte-identical to the inline code it replaced.
+ *
+ * The crux is `cekCache`: `elevate`/`demote`/`getAtTier` write the SAME `Lru`
+ * reference `Collection` owns (never a copy) so a per-record CEK re-wrap stays
+ * synchronous with the cache the kernel's write/read path also mutates. The
+ * cross-tier event sink stays collection-resident and is reached via the
+ * `emitCrossTierEvent` callback.
+ *
+ * Internal service — not exported as a `@noy-db/hub/*` subpath.
+ */
+export { withTiers } from './active.js';
+export { NO_TIERS, type TiersStrategy } from './strategy.js';
+export { TiersNotEnabledError } from '../../kernel/errors.js';
+import { type RecordCodec, type EnclaveKey, type SealedShredSlot } from '../../kernel/enclave/index.js';
+import type { UnlockedKeyring } from '../../with-party/team/keyring.js';
+import type { Lru } from '../../kernel/cache/index.js';
+import { type NoydbStore, type EncryptedEnvelope, type GhostRecord, type TierMode, type CrossTierAccessEvent } from '../../kernel/types.js';
+/** Everything the moving tier methods touched on `this.*`, as a flat context. */
+export interface TiersContext<T> {
+    /** Collection name — the crypto AAD scope and tier-DEK key prefix. */
+    readonly name: string;
+    /** Vault namespace the records live under. */
+    readonly vault: string;
+    /** The ciphertext store. */
+    readonly adapter: NoydbStore;
+    /** The caller's unlocked keyring (tier-DEK holdings + role + userId). */
+    readonly keyring: UnlockedKeyring;
+    /** The record codec — decrypts a tier-0 envelope to T. */
+    readonly codec: RecordCodec<T>;
+    /**
+     * The collection's per-record CEK cache (SHARED reference, not a copy).
+     * `elevate`/`demote`/`getAtTier` re-wrap a record's CEK and `set` it here so
+     * the move stays synchronous with the cache the kernel's read/write path
+     * owns. `null` → no caching.
+     */
+    readonly cekCache: Lru<string, EnclaveKey> | null;
+    /** Emit `_source`/`_sourceTs` provenance fields when a source is supplied. */
+    readonly provenance: boolean;
+    /** Declared tiers, or null when the feature is off. */
+    readonly tiers: ReadonlySet<number> | null;
+    /** Above-tier read visibility mode (`'invisibility'` | `'ghost'`). */
+    readonly tierMode: TierMode;
+    /** Resolve a tier DEK by its `dekKey(name, tier)`. */
+    getDEK(key: string): Promise<EnclaveKey>;
+    /** Fire a cross-tier access event (sink stays collection-resident). */
+    emitCrossTierEvent(event: CrossTierAccessEvent): void;
+}
+export declare function assertTiersEnabled<T>(ctx: TiersContext<T>): void;
+export declare function assertDeclaredTier<T>(ctx: TiersContext<T>, tier: number): void;
+/**
+ * tier-aware put. Encrypts the record with the collection's tier-N DEK and
+ * stamps `_tier: N` on the envelope. The caller's keyring must hold the tier-N
+ * DEK (directly, by delegation, or by virtue of being the grantor); otherwise
+ * throws `TierNotGrantedError`.
+ *
+ * accepts an optional `elevation` context. When present, the emitted cross-tier
+ * event is stamped with `authorization: 'elevation'`, the elevation's reason,
+ * and the caller's pre-elevation tier. `vault.elevate(...).collection().put`
+ * threads this through; direct `putAtTier` calls leave it undefined and fall
+ * back to the inherent-write event shape.
+ */
+export declare function putAtTier<T>(ctx: TiersContext<T>, id: string, record: T, tier: number, opts?: {
+    elevation?: {
+        reason: string;
+        fromTier: number;
+    };
+    source?: string;
+    sourceTs?: string;
+}): Promise<void>;
+/**
+ * tier-aware get. When the stored record is at a tier the caller cannot
+ * decrypt:
+ *   - `'invisibility'` mode (default) → returns `null`.
+ *   - `'ghost'` mode → returns a `GhostRecord` placeholder with the tier and
+ *     the record id (the record exists but contents are withheld).
+ *
+ * Fully-cleared reads return the plaintext record and fire a cross-tier event
+ * when `_tier > 0`.
+ */
+export declare function getAtTier<T>(ctx: TiersContext<T>, id: string): Promise<T | GhostRecord | null>;
+/**
+ * list ids grouped by the caller's readability. Returns only ids whose tier the
+ * caller can read. Above-tier ids are omitted in `'invisibility'` mode and
+ * included (with tier metadata) in `'ghost'` mode.
+ */
+export declare function listAtTier<T>(ctx: TiersContext<T>): Promise<Array<{
+    id: string;
+    tier: number;
+    readable: boolean;
+}>>;
+/**
+ * elevate a record to a higher tier. Re-encrypts with the target tier's DEK.
+ * The caller must hold DEKs for both the current tier (to decrypt) and the
+ * target tier (to re-encrypt). Stamps `_elevatedBy` with the caller id so
+ * `demote()` can check the reverse operation.
+ */
+export declare function elevate<T>(ctx: TiersContext<T>, id: string, toTier: number): Promise<void>;
+/**
+ * demote a record to a lower tier. Allowed only for the user who performed the
+ * last elevation or an owner.
+ */
+export declare function demote<T>(ctx: TiersContext<T>, id: string, toTier: number): Promise<void>;
+/**
+ * Classify a live envelope's `_sealed` slots for crypto-shred completeness
+ * (#M-1). Thin delegate to {@link RecordCodec.classifySealedShred}; surfaced
+ * here because `vault.ts` forget() reaches in via `collection._classifySealedShred`.
+ */
+export declare function classifySealedShred<T>(ctx: TiersContext<T>, live: EncryptedEnvelope): Promise<{
+    readonly slots: readonly SealedShredSlot[];
+}>;

package/dist/with-audit/tiers/strategy.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Tiers capability strategy — the five on-demand collection-level tier
+ * operations the `Collection` routes through. The active engine
+ * ({@link withTiers}) dynamically imports the tier cores (keeping them out of
+ * the floor bundle); {@link NO_TIERS} throws. Collection always builds its
+ * per-call {@link TiersContext} and delegates here, so an un-opted-in caller
+ * hits `NO_TIERS`'s throw.
+ * @internal
+ */
+import type { GhostRecord } from '../../kernel/types.js';
+import type { TiersContext } from './index.js';
+export interface TiersStrategy {
+    putAtTier<T>(ctx: TiersContext<T>, id: string, record: T, tier: number, opts?: {
+        elevation?: {
+            reason: string;
+            fromTier: number;
+        };
+        source?: string;
+        sourceTs?: string;
+    }): Promise<void>;
+    getAtTier<T>(ctx: TiersContext<T>, id: string): Promise<T | GhostRecord | null>;
+    listAtTier<T>(ctx: TiersContext<T>): Promise<Array<{
+        id: string;
+        tier: number;
+        readable: boolean;
+    }>>;
+    elevate<T>(ctx: TiersContext<T>, id: string, toTier: number): Promise<void>;
+    demote<T>(ctx: TiersContext<T>, id: string, toTier: number): Promise<void>;
+}
+/**
+ * No-op stub — the floor default. Every capability method throws
+ * {@link TiersNotEnabledError}; opt in with `tiersStrategy: withTiers()` in
+ * createNoydb. @internal
+ */
+export declare const NO_TIERS: TiersStrategy;

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

@@ -0,0 +1,11 @@
+/**
+ * Enable the cargo (partition extraction) capability.
+ * Pass to `createNoydb({ cargoStrategy: withCargo() })` to make the source-side
+ * `extractPartition(vault, ...)` free function live. The extraction crypto
+ * engine is dynamically imported here, so it stays out of the floor bundle
+ * until opted in. The recipient-side `adoptPartition` /
+ * `decryptExtractedPartition` free functions — and `diffVault` (shared
+ * import/merge infra) — are ungated and unaffected.
+ */
+import type { CargoStrategy } from './strategy.js';
+export declare function withCargo(): CargoStrategy;

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

@@ -0,0 +1,81 @@
+/**
+ * Partition adoption. Recipient side: verify an extracted bundle,
+ * validate the transfer key, import the re-keyed collections into a
+ * destination store, and record an `_meta/adoption` marker. The bundle
+ * stays UNOWNED after adoption — `createOwnerOnAdoptedPartition`
+ * mints the owner; the transfer seal is then destroyed.
+ *
+ * @module
+ */
+import { type EnclaveKey } from '../kernel/enclave/index.js';
+import type { NoydbStore } from '../kernel/types.js';
+import type { SealingKeyProvider } from '../with-party/team/managed-passphrase.js';
+import type { ShamirRecoveryProvider } from '../with-party/team/shamir-recovery-provider.js';
+import type { RecoveryEnrollmentInput } from '../with-party/team/rotate-recover.js';
+import type { TransferSealPayload } from '../with-pod/bundle.js';
+/**
+ * Reverse of `sealDeks`. Imports the transfer key, decrypts the
+ * sealed `{ collection: base64(rawDEK) }` map (layout iv(12)‖ct‖tag), and
+ * re-imports each DEK as an AES-GCM key. Throws `TransferSealError` on a
+ * wrong key (AES-GCM auth-tag failure) or malformed payload.
+ */
+export declare function unsealDeks(seal: TransferSealPayload, transferKey: Uint8Array): Promise<Map<string, EnclaveKey>>;
+export interface AdoptPartitionOptions {
+    readonly transferKey: Uint8Array;
+    readonly destinationStore: NoydbStore;
+    readonly vaultName: string;
+}
+export interface AdoptPartitionResult {
+    readonly vaultName: string;
+    readonly needsOwner: true;
+    readonly sealId: string;
+}
+export declare function adoptPartition(bundleBytes: Uint8Array, opts: AdoptPartitionOptions): Promise<AdoptPartitionResult>;
+export interface CreateOwnerResult {
+    readonly vaultName: string;
+    readonly userId: string;
+}
+/** Standard-mode owner: recipient supplies the passphrase. */
+export interface CreateOwnerStandardOptions {
+    readonly userId: string;
+    readonly passphrase: string;
+    readonly transferKey: Uint8Array;
+}
+/**
+ * Managed-mode owner: the passphrase is minted + sealed under
+ * a `SealingKeyProvider` (e.g. an `at-*` OS keychain) so the partition
+ * auto-unlocks on the recipient's device. Managed mode mandates a strong
+ * (Shamir) recovery profile at creation, which needs the
+ * `shamirRecovery` provider injected.
+ */
+export interface CreateOwnerManagedOptions {
+    readonly userId: string;
+    readonly passphraseMode: 'managed';
+    readonly sealingKey: SealingKeyProvider;
+    readonly recovery: ReadonlyArray<RecoveryEnrollmentInput>;
+    readonly shamirRecovery: ShamirRecoveryProvider;
+    readonly transferKey: Uint8Array;
+}
+export type CreateOwnerOptions = CreateOwnerStandardOptions | CreateOwnerManagedOptions;
+/**
+ * Mint the first owner keyring on an adopted-but-unowned partition,
+ * then destroy the transfer seal.
+ *
+ * Standard mode: the recipient supplies a passphrase. Managed mode: the
+ * passphrase is minted + sealed under a `SealingKeyProvider` and a strong
+ * (Shamir) recovery profile is enrolled — orchestrated via the existing
+ * `openVaultAndEnrollRecovery` ceremony.
+ *
+ * Either way, reuses `createOwnerKeyring` to derive the KEK + write the base
+ * keyring, then wraps the partition's DEKs (recovered from the seal) under that
+ * KEK and re-persists the merged keyring file.
+ *
+ * Idempotent under retry: the seal is destroyed LAST (Stage D), after the
+ * keyring (Stage A), the ledger transition (Stage B), and — in managed mode —
+ * strong-recovery enrollment (Stage C). A failure in the fallible enrollment
+ * step leaves the seal intact, and re-running with the same `userId` +
+ * `transferKey` resumes from the first incomplete stage. (Multi-profile recovery
+ * arrays may re-enroll an already-enrolled profile on retry; managed mode's
+ * mandated single Shamir profile does not.)
+ */
+export declare function createOwnerOnAdoptedPartition(store: NoydbStore, vaultName: string, opts: CreateOwnerOptions): Promise<CreateOwnerResult>;

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

@@ -0,0 +1,19 @@
+/** One decrypted record from an extracted-partition compartment. */
+export interface DecryptedRecord {
+    readonly id: string;
+    readonly record: Record<string, unknown>;
+    /** Source envelope write timestamp (ISO) — for last-write-wins merges. */
+    readonly ts: string;
+    /** Source envelope version. */
+    readonly version: number;
+    /** Provenance source id (FR-5). Present only when the source collection had provenance:true and a source was supplied on put. */
+    readonly source?: string;
+    /** ISO-8601 timestamp the provenance source was recorded (FR-5). */
+    readonly sourceTs?: string;
+}
+/**
+ * Decrypt every record of an extracted-partition bundle to plaintext,
+ * grouped by collection. Throws if the bundle isn't an
+ * extracted-partition or the transfer key is wrong.
+ */
+export declare function decryptExtractedPartition(bundleBytes: Uint8Array, transferKey: Uint8Array): Promise<Record<string, DecryptedRecord[]>>;

package/dist/with-cargo/describe-extraction.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Partition-extraction dry-run. Read-only preview of what an
+ * `extractPartition` would move: record counts, byte totals, and the
+ * timestamp span per collection — computed from raw encrypted
+ * envelopes WITHOUT decrypting them. Writes nothing, mutates nothing.
+ *
+ * @module
+ */
+import type { Vault } from '../kernel/vault.js';
+import { type WalkClosureOptions } from './walk-closure.js';
+export interface ExtractionPreview {
+    readonly totalRecords: number;
+    /** Sum of serialized encrypted-envelope sizes (bytes). */
+    readonly totalBytes: number;
+    readonly byCollection: ReadonlyArray<{
+        readonly name: string;
+        readonly recordCount: number;
+        readonly bytes: number;
+        /** Earliest envelope `_ts` in this collection (lexicographic). */
+        readonly oldestTs?: string;
+        readonly newestTs?: string;
+    }>;
+    readonly graph: {
+        readonly depth: number;
+        readonly cyclesDetected: boolean;
+    };
+    /** Records the walk reached but whose envelope couldn't be read. */
+    readonly inaccessible: ReadonlyArray<{
+        readonly collection: string;
+        readonly id: string;
+    }>;
+}
+export declare function describeExtraction(vault: Vault, opts: WalkClosureOptions): Promise<ExtractionPreview>;

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

@@ -0,0 +1,147 @@
+/**
+ * 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 } 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;
+}
+/**
+ * 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>>;