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

package/dist/with-lookup/search/persisted-index-store.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Persisted backend for the L1 lexical index (L1.5). Crypto-free: the
+ * collection injects load/save/remove + a fingerprint provider. In-memory while
+ * live (L1 behavior); persists an opaque snapshot via a debounced flush, and
+ * validates a loaded blob against a {count,maxVersion} fingerprint so a stale
+ * blob is never used — only rebuilt.
+ *
+ * #725: a debounced save (encrypt + adapter.put) racing a purge (removePersisted,
+ * called by elevate's tier purge and forget's erasure) is guarded by an epoch counter
+ * — see the `epoch` field doc for the mechanism and why it also closes the issue's
+ * variant (b) for free. Residual gap, structurally unavoidable without a durable
+ * write-ahead log: a process CRASH strictly between a stale save's `adapter.put`
+ * landing and its compensating `remove()` running (or between the compensating
+ * remove landing and `pendingCompensation` being persisted somewhere durable — it is
+ * in-memory only) leaves the resurrected blob at rest until the next natural
+ * rebuild-persist. This is on par with the gate-before-put optimization's own crash
+ * residual (a crash between `isStale()` returning false and the put landing) — both
+ * are eliminated only by making the purge and the save's commit point transactional
+ * with the store, which is out of scope for an in-memory debounce layer over an
+ * arbitrary opaque-blob backend.
+ */
+import { InvertedIndex, type IndexDoc } from './inverted-index.js';
+import type { IndexStore } from './index-store.js';
+export interface Fingerprint {
+    readonly count: number;
+    readonly maxVersion: number;
+}
+export interface PersistedIndexCallbacks {
+    load(): Promise<{
+        json: string;
+        fingerprint: Fingerprint;
+    } | null>;
+    /** `isStale()` reflects whether a purge (removePersisted) has landed since this
+     *  save's epoch was captured — check it AFTER any async encrypt step and BEFORE
+     *  the actual adapter.put, skipping the write when true (#725 review: shrinks the
+     *  at-rest window for purge-beats-encrypt orderings to zero). Belt-and-suspenders:
+     *  PersistedIndexStore's own post-save epoch check (persist(), below) is the
+     *  backstop that catches every other ordering, including a purge landing during
+     *  the put itself. */
+    save(json: string, fp: Fingerprint, isStale: () => boolean): Promise<void>;
+    remove(): Promise<void>;
+    currentFingerprint(): Fingerprint;
+    debounceMs?: number;
+}
+export declare class PersistedIndexStore implements IndexStore {
+    private readonly cb;
+    private index;
+    private timer;
+    private lastBuild;
+    private readonly debounceMs;
+    /**
+     * Bumped by every purge (removePersisted). A save() captured under a since-stale
+     * epoch undoes its own effect once it settles, however it interleaves with the
+     * purge's own delete — a delete can never be overtaken by a save that was
+     * scheduled before it (#725).
+     *
+     * Subsumes the issue's variant (b) (a stale, pre-purge in-memory index getting
+     * paired with a live, post-purge fingerprint and TRUSTED by a cold load, defeating
+     * the fingerprint backstop) for free — no separate handling needed: removePersisted()
+     * always resets `index` to undefined in the SAME synchronous step that bumps the
+     * epoch (below), and the only two paths that can repopulate `index` (ensureBuilt's
+     * cold rebuild, rebuildAndPersist's rebuild) do so strictly from `lastBuild()`, which
+     * the collection wires to read its LIVE cache at call time — not a frozen snapshot.
+     * Cache eviction (the collection dropping the purged/forgotten record) always
+     * precedes removePersisted() in both the elevate and forget call paths (#721's
+     * syncCache eviction / forget's tombstone write both land before syncSearch /
+     * _purgeSearchIndex runs). So any rebuild that executes strictly after
+     * removePersisted() — the only way `index` becomes defined again post-purge —
+     * necessarily observes the post-purge cache, and any rebuild that predates
+     * removePersisted() has its `index` wiped by it. There is no ordering in which a
+     * stale (pre-purge) index survives to be skip-rebuilt and persisted under a
+     * matching live fingerprint. Regression-pinned in
+     * `search-persisted-index-store.test.ts` ("variant (b) is subsumed...").
+     */
+    private epoch;
+    /**
+     * Set when a compensating/purging remove() (`compensate()` undoing a stale
+     * save, or `removePersisted()`'s own purge, #764) fails. Unlike the routine
+     * best-effort swallow on the debounced flush path (markDirty's timer
+     * .catch(), below — safe there because the fingerprint backstop forces a
+     * rebuild on the next cold load), a failed removal leaves a resurrected or
+     * un-purged blob at rest whose fingerprint can still match the live cache —
+     * a cold load would TRUST it, not rebuild past it. So this is never silently
+     * dropped: every subsequent store entrypoint (ensureBuilt, rebuildAndPersist,
+     * removePersisted) retries the remove first and refuses to proceed past it
+     * until it succeeds (#725 review), and the raw adapter error is wrapped in
+     * {@link PersistedIndexCompensationError} (#764) so a caller can catch a
+     * stuck removal deliberately instead of an indistinguishable adapter error.
+     * A crash between a landed put and its compensating remove (before this
+     * flag or a retry can run) is a residual gap — see the class doc.
+     */
+    private pendingCompensation;
+    constructor(cb: PersistedIndexCallbacks);
+    get built(): boolean;
+    ensureBuilt(build: () => ReadonlyArray<IndexDoc>): Promise<InvertedIndex>;
+    markDirty(): void;
+    /** Force an immediate persist (cancels any pending debounce). */
+    flush(): Promise<void>;
+    /** Delete the persisted blob and drop the in-memory index (forget/erasure/tier
+     *  move). A failed purge is wrapped in {@link PersistedIndexCompensationError}
+     *  (#764) and left sticky (`pendingCompensation`) so the next store entrypoint
+     *  retries it — never silently dropped, same posture #725 established for a
+     *  stale save's own compensating remove. */
+    removePersisted(): Promise<void>;
+    /** Rebuild using the last known build thunk, then persist. */
+    private rebuildAndPersist;
+    /** Persist the current index, then undo it if a purge (removePersisted) landed
+     *  while the save was in flight — a delete can never be overtaken by a save
+     *  that was scheduled before it (#725). A failed undo does not silently vanish:
+     *  see `pendingCompensation`. */
+    private persist;
+    /** Undo a stale save. Failure is sticky, not swallowed: see `pendingCompensation`.
+     *  Wraps the raw adapter error in {@link PersistedIndexCompensationError} (#764) so
+     *  a caller (e.g. the tier ops' `syncTierSearch`) can catch a stuck compensation
+     *  deliberately instead of treating it as an indistinguishable adapter failure. */
+    private compensate;
+    /** Retries a sticky compensation before any store entrypoint proceeds. Failure
+     *  re-wraps the raw adapter error the same way `compensate()` does (#764) — the
+     *  flag stays set (untouched here) so the NEXT entrypoint retries again. */
+    private retryPendingCompensation;
+}

package/dist/with-lookup/search/retrieve-types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Public option / result types for `collection.retrieve()` (L1). Kept in
+ * the search service so collection.ts holds only thin call-sites; re-exported
+ * from the search barrel and the hub root.
+ */
+import type { Query } from '../../kernel/query/builder.js';
+export interface RetrieveOptions<T = unknown> {
+    readonly limit?: number;
+    readonly match?: 'any' | 'all';
+    readonly prefix?: boolean;
+    readonly snippetWindow?: number;
+    readonly fields?: readonly string[];
+    readonly includeRecord?: boolean;
+    /** Retrieval strategy; defaults to 'lexical'. 'hybrid' fuses lexical+semantic (L3). */
+    readonly mode?: 'lexical' | 'semantic' | 'hybrid';
+    /** L2 — minimum cosine score for semantic hits (semantic mode only). */
+    readonly minScore?: number;
+    /** L3 — intersect hits with a structured query (retrieve ∩ where). Eager-mode only. */
+    readonly within?: Query<T>;
+}
+export interface RetrieveHit<T> {
+    readonly id: string;
+    readonly score: number;
+    readonly rank: number;
+    readonly field: string;
+    readonly snippet: string;
+    readonly locale?: string;
+    readonly record?: T;
+}

package/dist/with-lookup/search/scan.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Scan-mode full-text search — ranks **already-decrypted** records by
+ * BM25 against a tokenized query. Pure client-side: nothing is written to the
+ * store, so this adds **zero** leakage (unlike a store-usable blind index,
+ * which is a separate, gated opt-in).
+ *
+ * O(n) over the collection; intended for small/medium collections (the pilot's
+ * scale) where moving the existing userland scan into the DB is the win.
+ */
+import { type Tokenizer } from './tokenize.js';
+export interface SearchOptions {
+    /** Top-N by score (default: all matches). */
+    readonly limit?: number;
+    /** `'any'` (default) = OR of query terms; `'all'` = every term must match. */
+    readonly match?: 'any' | 'all';
+    /** Treat the LAST query term as a prefix (typeahead). */
+    readonly prefix?: boolean;
+}
+export interface SearchResult<T> {
+    readonly id: string;
+    readonly score: number;
+    readonly record: T;
+}
+export interface SearchEntry<T> {
+    readonly id: string;
+    readonly record: T;
+}
+export declare function searchScan<T>(entries: ReadonlyArray<SearchEntry<T>>, field: string, query: string, opts?: SearchOptions, tokenizer?: Tokenizer): SearchResult<T>[];

package/dist/with-lookup/search/segment.d.ts

@@ -0,0 +1,15 @@
+/**
+ * i18n word tokenizer for the L1 lexical index. Uses Intl.Segmenter
+ * (standard ECMAScript — hub-portable) to dictionary-segment Thai/Lao/Khmer/CJK,
+ * which the word-run `tokenize` cannot. Terms are matched in NFKC-lowercased form;
+ * offsets index the ORIGINAL text so snippets slice the user's text.
+ */
+import type { Tokenizer } from './tokenize.js';
+export interface Token {
+    readonly term: string;
+    readonly offset: number;
+}
+/** Word-like tokens with NFKC-lowercased terms + original-text char offsets. */
+export declare const segmentTokens: (text: string) => Token[];
+/** Term-only tokenizer (the public `Tokenizer` shape) — for queries. */
+export declare const segmentTokenizer: Tokenizer;

package/dist/with-lookup/search/serialize.d.ts

@@ -0,0 +1,4 @@
+/** (De)serialize an InvertedIndex to/from a JSON string for persistence (L1.5). */
+import { InvertedIndex } from './inverted-index.js';
+export declare function serializeIndex(idx: InvertedIndex): string;
+export declare function deserializeIndex(json: string): InvertedIndex;

package/dist/with-lookup/search/snippet.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Minimal-disclosure snippet: a char-window around a match offset (L1).
+ * Unicode-safe (operates on code points). `…` marks each truncated end.
+ */
+export declare function extractSnippet(text: string, offset: number, window?: number): string;

package/dist/with-lookup/search/strategy.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Search capability strategy — the on-demand collection-level retrieval
+ * operations the `Collection` routes through: scan-mode full-text `search`,
+ * unified `retrieve` (lexical | semantic | hybrid), raw-vector `similarTo`, and
+ * the lexical-index lifecycle (`warmIndex` / `flushIndex`). The active engine
+ * ({@link withSearch}) dynamically imports the search/retrieval facade (keeping
+ * it out of the floor bundle); {@link NO_SEARCH} throws.
+ *
+ * The embedding write-hook (`embedOnWrite`) is paired here too: opting into
+ * `withSearch()` enables both the query surface AND the put()-time vector
+ * compute — a vector that no gated `similarTo` / semantic `retrieve` could read
+ * is dead weight, so embedding compute is not separately gatable. `Collection`
+ * always assembles the per-call {@link SearchContext} and delegates here, so an
+ * un-opted-in caller hits `NO_SEARCH`'s throw.
+ * @internal
+ */
+import type { SearchContext } from './collection-facade.js';
+import type { SearchOptions, SearchResult } from './index.js';
+import type { RetrieveOptions, RetrieveHit } from './retrieve-types.js';
+export interface SearchStrategy {
+    search<T>(ctx: SearchContext<T>, field: string, query: string, opts?: SearchOptions): Promise<SearchResult<T>[]>;
+    retrieve<T>(ctx: SearchContext<T>, query: string, opts?: RetrieveOptions<T>): Promise<RetrieveHit<T>[]>;
+    similarTo<T>(ctx: SearchContext<T>, vector: Float32Array, opts?: {
+        k?: number;
+        minScore?: number;
+        includeRecord?: boolean;
+    }): Promise<RetrieveHit<T>[]>;
+    warmIndex<T>(ctx: SearchContext<T>): Promise<void>;
+    flushIndex<T>(ctx: SearchContext<T>): Promise<void>;
+    embedOnWrite<T>(ctx: SearchContext<T>, id: string, record: T, version: number): Promise<void>;
+    rebuildEmbeddings<T>(ctx: SearchContext<T>): Promise<{
+        rebuilt: number;
+        skipped: number;
+    }>;
+}
+/**
+ * No-op stub — the floor default. Every capability method (and the embedding
+ * write-hook) throws {@link SearchNotEnabledError}; opt in with
+ * `searchStrategy: withSearch()` in createNoydb. @internal
+ */
+export declare const NO_SEARCH: SearchStrategy;

package/dist/with-lookup/search/tokenize.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Default text tokenizer for scan-mode search.
+ *
+ * NFKC-normalize → lowercase → split on Unicode letter/number runs. This is a
+ * word-boundary tokenizer: it does **not** segment scripts written without
+ * inter-word spaces (Thai, Lao, Khmer, CJK) — those collapse to one token per
+ * run. For such data, a dictionary/ICU segmenter is the right `tokenizer`
+ * (the engine takes one as a parameter); substring/`contains` matching is the
+ * pragmatic fallback until then.
+ */
+export type Tokenizer = (text: string) => string[];
+export declare const tokenize: Tokenizer;

package/dist/with-party/auth-introspection/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Authentication introspection.
+ *
+ * Three surfaces over the configured tier model and the actual
+ * per-user enrollment state:
+ *
+ * 1. **Vault-wide English summary** — {@link describeAuthConfig}.
+ * 2. **Vault-wide Mermaid diagram** — {@link diagramAuthConfig}.
+ * 3. **Per-user introspection** — {@link describeUserAuth}, gated by
+ *    the `view-user-auth` policy gate (off by default).
+ *
+ * The per-user surface is held to a strict allowlist — fields not on
+ * the allowlist are dropped, never rendered. The negative test in
+ * `auth-introspection.test.ts` exercises the allowlist by feeding a
+ * contrived keyring with fake "secret" fields and asserting that none
+ * of them appear in the output.
+ *
+ * @module
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+/** Vault-wide English summary of the configured authentication graph. */
+export declare function describeAuthConfig(store: NoydbStore, vault: string): Promise<string>;
+/**
+ * Render the vault's auth graph as Mermaid `flowchart TB` source. The
+ * caller pipes this through Mermaid (CLI or browser) to get an SVG.
+ */
+export declare function diagramAuthConfig(store: NoydbStore, vault: string): Promise<string>;
+/**
+ * Render the per-user enrollment summary. Returns an empty
+ * (non-throwing) string when the user has no keyring file — never
+ * confirms or denies the existence of the user from the document
+ * alone.
+ *
+ * Sanitization is strict: only the slot list, enrollment dates, and
+ * recovery-profile counts are rendered. WebAuthn cred ids, OIDC
+ * subject ids, password hashes, recovery codes, TOTP secrets — all
+ * dropped at the allowlist boundary, not redacted.
+ */
+export declare function describeUserAuth(store: NoydbStore, vault: string, userId: string): Promise<string>;
+/** Bulk variant for owner dashboards. */
+export declare function describeAllUsersAuth(store: NoydbStore, vault: string): Promise<Array<{
+    userId: string;
+    description: string;
+}>>;

package/dist/with-party/broker/active.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Enable the credential-broker capability (#479, spec §5).
+ *
+ * Pass to `createNoydb({ brokerStrategy: withBroker(config) })` to make
+ * `vault.broker()` live. Each method dynamic-imports the seed lifecycle
+ * engine (`./seed.js`) — mirroring `via/classified/active.ts`'s per-method
+ * dynamic-import seam — so `with-party/broker/seed.ts` (the heavy module:
+ * the CAS enrol, quiesce-then-swap rotate, and the challenge/response round
+ * trip) is reachable only through the `@noy-db/hub/broker` subpath and
+ * never enters the single-user floor bundle.
+ *
+ * The single-flight, per-vault-per-profile refresh cache (H-6/I6) lives
+ * HERE, in this factory's closure — shared across every `credentialSource(profile)`
+ * call for this one broker instance (in turn shared across every vault of a
+ * `createNoydb()` instance — `vault.broker()` passes the SAME `BrokerStrategy`
+ * for all of them), so `rotate()` can quiesce it (await any in-flight
+ * round-trip, then drop it) before the seed swap. The cache key is
+ * `${vault}\0${profile}` — keyed by vault FIRST, or two vaults sharing this
+ * one strategy would collide and hand vault-B a cached credential minted
+ * (and STS-scoped) for vault-A.
+ */
+import type { BrokerStrategy, BrokerConfig } from '../../port/with/broker-strategy.js';
+export declare function withBroker(config: BrokerConfig): BrokerStrategy;

package/dist/with-party/broker/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `@noy-db/hub/broker` — subpath export for the credential-broker capability
+ * (#479, credential-broker spec). Apps that never call `vault.broker()` can
+ * exclude this subpath entirely: the floor default `NO_BROKER` throws, and
+ * this module's real engine (`with-party/broker/{seed,active}.ts`) is only
+ * ever reached through `withBroker()`'s dynamic imports, so it never enters
+ * a floor bundle.
+ *
+ * Also re-exports the host-side helpers (`issueChallenge`, `verifyBrokerProof`)
+ * from the enclave barrel, so a Lambda/Worker implementing the reference
+ * broker host can import just this one subpath and get everything it
+ * needs, `crypto.subtle`-only.
+ */
+export { withBroker } from './active.js';
+export { NO_BROKER, type BrokerStrategy, type BrokerCtx, type BrokerConfig, type CredentialBrokerHandle, } from '../../port/with/broker-strategy.js';
+export { BrokerNotEnabledError, BrokerEnrolmentError, BrokerProofError } from '../../kernel/errors.js';
+import { verifyBrokerProof } from '../../kernel/enclave/index.js';
+import type { IssuedChallenge, VerifyBrokerProofArgs } from '../../kernel/enclave/index.js';
+/**
+ * {@link issueChallengeRaw} (the enclave's mechanical primitive) with a
+ * `[10s, 60s]` TTL clamp applied, so a reference host built on this barrel
+ * gets a safe challenge TTL without having to know the bounds itself.
+ */
+export declare function issueChallenge(opts?: {
+    ttlMs?: number;
+}): IssuedChallenge;
+export { verifyBrokerProof };
+export type { VerifyBrokerProofArgs };

package/dist/with-party/broker/seed.d.ts

@@ -0,0 +1,77 @@
+/**
+ * `_broker` reserved-collection seed lifecycle (#479, credential-broker
+ * spec §2/§3). Modeled on `with-party/team/sync-credentials.ts`: a
+ * `_`-prefixed reserved collection, record id = `brokerId`, encrypted under
+ * the collection's own DEK, `requireAdminAccess` role gate (owner/admin
+ * only — custodian intentionally excluded, same rationale as
+ * `_sync_credentials`: this is transport-auth material, not the
+ * custodian's operational scope).
+ *
+ * Three operations, each a free function taking a {@link BrokerSeedCtx}
+ * (the {@link BrokerCtx} threaded through `with-party/broker/active.ts`,
+ * augmented there with the `config` its closure was built with):
+ *
+ *  - {@link enrollSeed} — two-phase commit (I9): create-if-absent CAS the
+ *    seed (I4), then register its derived proof key with the broker host,
+ *    then (only on a 2xx) mark the record `registered: true`. A seed
+ *    persisted whose `/enroll` POST failed stays `registered: false` so a
+ *    later `credentialSource()` fails fast instead of degrading into an
+ *    opaque `BrokerProofError` (I9/V23).
+ *  - {@link rotateSeed} — quiesce-then-swap (I5): mint a fresh seed,
+ *    register-new-first, THEN overwrite the local record — closing the
+ *    torn-proof window a naive local-overwrite-then-register order would
+ *    open. The single-flight cache quiesce itself (await in-flight, bump
+ *    epoch) is the caller's job (`with-party/broker/active.ts`) since the
+ *    cache lives in that closure, not here.
+ *  - {@link mintStoreCredentials} — the challenge/response round trip
+ *    (`/challenge` then `/credentials`) that produces one `StoreCredentials`
+ *    value; the single-flight cache wrapping it lives in `active.ts`.
+ *
+ * First-seed creation calls `ensureCollectionDEK`, which throws
+ * (`ValidationError`) when the keyring's KEK is `null` (PIN quick-resume /
+ * session-restore) — this module intercepts that and re-surfaces it as
+ * {@link BrokerEnrolmentError} (R-B8/I3): *enrol* needs the KEK; *use* of an
+ * already-enrolled seed needs only the DEK.
+ *
+ * @module
+ */
+import type { StoreCredentials } from '../../kernel/types.js';
+import type { BrokerSeedCtx } from '../../port/with/broker-strategy.js';
+/** The `_broker/<brokerId>` record payload (spec §3). */
+export interface BrokerSeedRecord {
+    readonly brokerId: string;
+    /** base64(32 random bytes). */
+    readonly seed: string;
+    readonly endpoint: string;
+    readonly createdAt: string;
+    /** `true` only once `/enroll` has returned a 2xx for this seed (I9). */
+    readonly registered: boolean;
+}
+/**
+ * Enrol (idempotent, two-phase commit — I9): create-if-absent the `_broker`
+ * seed (I4), derive+register its proof key with the broker host, and only
+ * on a 2xx mark the record `registered: true`. Requires owner/admin role
+ * and (for first-seed creation only) the KEK.
+ */
+export declare function enrollSeed(ctx: BrokerSeedCtx): Promise<void>;
+/**
+ * Rotate (quiesce-then-swap — I5): mint a fresh seed, register its proof
+ * key with the broker host FIRST, then overwrite the local `_broker`
+ * record. The broker host is expected to accept both the old and new
+ * registration for a short grace window, so an in-flight proof computed
+ * under the old key (from before rotation started) still verifies. Cache
+ * quiescing (awaiting any in-flight round-trip, bumping the refresh-cache
+ * epoch) is the caller's job — `with-party/broker/active.ts` — since the
+ * cache lives in that closure, not here.
+ */
+export declare function rotateSeed(ctx: BrokerSeedCtx): Promise<void>;
+/**
+ * The challenge/response round trip: `POST /challenge`, derive+sign the
+ * proof from the decrypted seed, `POST /credentials`. One network round
+ * trip per call — the single-flight/cache wrapping lives in `active.ts`.
+ *
+ * Fails fast with {@link BrokerEnrolmentError} if the seed hasn't completed
+ * enrolment yet (`registered !== true` — I9/V23), never degrading into an
+ * opaque {@link BrokerProofError}.
+ */
+export declare function mintStoreCredentials(ctx: BrokerSeedCtx, profile?: string): Promise<StoreCredentials>;

package/dist/with-party/custody/active.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Enable the sovereign-custody (FR-6) capability.
+ * Pass to `createNoydb({ custodyStrategy: withCustody() })` to make
+ * `db.grantCustodian` / `db.revokeCustodian` (and the `vault.custody.*` facade
+ * that delegates to them) plus `vault.custody.liberate()` live. The heavy
+ * `liberateVault` ceremony is dynamically imported here, so it is reached only
+ * via opt-in; grant/revoke run the host's own gate + keyring engine.
+ */
+import type { CustodyStrategy } from './strategy.js';
+export declare function withCustody(): CustodyStrategy;

package/dist/with-party/custody/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Public `vault.custody.*` API surface (FR-6).
+ *
+ * The custody namespace is the vault-instance face of the FR-6 sovereign-custody
+ * model — it mirrors `vault.user.*` exactly: a thin delegation shell with NO
+ * business logic. The Vault constructs one `CustodyApi` per session, injecting
+ * closures that bind the vault name / keyring into the genuinely-core
+ * implementations (`Noydb.grantCustodian` / `Noydb.revokeCustodian` and the
+ * `liberateVault` ceremony). Each method just forwards to its injected callback.
+ *
+ * Three operations:
+ *  - `grantCustodian(opts)` — owner-only: mint a `custodian` who operates the
+ *    vault fully but can never grant / rotate / sever / extract.
+ *  - `revokeCustodian(opts)` — owner-only: remove a custodian.
+ *  - `liberate(opts)` — custodian-only: audited claim of ownership over a
+ *    sealed-owner (Deed) vault (mints a DISTINCT new owner; ledger-audited).
+ *
+ * Provisioning a Deed (`createDeedOwner`) is deliberately NOT on this class: it
+ * is a store-level operation that mints the vault's first owner, so there is no
+ * vault instance (and thus no custody namespace) yet — it stays the exported
+ * `team/deed.ts` function.
+ *
+ * @see docs/superpowers/specs/2026-06-17-fr6-deed-custodian-liberate-design.md
+ * @module
+ */
+import type { GrantOptions, RevokeOptions, FactorProofBundle } from '../../kernel/types.js';
+import type { LiberateOptions, LiberateResult } from './liberate.js';
+/** Options for `vault.custody.grantCustodian` — a grant with the role fixed to `custodian`. */
+export type GrantCustodianOptions = Omit<GrantOptions, 'role'>;
+export { withCustody } from './active.js';
+export { NO_CUSTODY, type CustodyStrategy, type CustodyHost } from './strategy.js';
+export { CustodyNotEnabledError } from '../../kernel/errors.js';
+/**
+ * Implementation behind `vault.custody`. Constructed once per Vault. Holds the
+ * injected, vault-bound implementations in closure; every method delegates with
+ * no added logic (the owner-only / custodian-only / gate checks all live in the
+ * injected implementations — `Noydb.grantCustodian` etc. and `liberateVault`).
+ */
+export declare class CustodyApi {
+    /** Bound `Noydb.grantCustodian(this.name, ...)` — owner-only, gated. */
+    private readonly _grantCustodian;
+    /** Bound `Noydb.revokeCustodian(this.name, ...)` — owner-only, gated. */
+    private readonly _revokeCustodian;
+    /** Bound `liberateVault(this, ...)` — custodian-only audited ownership claim. */
+    private readonly _liberate;
+    constructor(
+    /** Bound `Noydb.grantCustodian(this.name, ...)` — owner-only, gated. */
+    _grantCustodian: (options: GrantCustodianOptions, factors?: FactorProofBundle) => Promise<void>, 
+    /** Bound `Noydb.revokeCustodian(this.name, ...)` — owner-only, gated. */
+    _revokeCustodian: (options: RevokeOptions, factors?: FactorProofBundle) => Promise<void>, 
+    /** Bound `liberateVault(this, ...)` — custodian-only audited ownership claim. */
+    _liberate: (opts: LiberateOptions) => Promise<LiberateResult>);
+    /**
+     * Owner-only: grant the FR-6 `custodian` role. The custodian operates every
+     * collection (rw + access) but is provably unable to grant / revoke / rotate /
+     * extract-and-sever. Defended in depth (gate + owner-only role check) inside
+     * the injected `Noydb.grantCustodian`.
+     */
+    grantCustodian(options: GrantCustodianOptions, factors?: FactorProofBundle): Promise<void>;
+    /** Owner-only: revoke a custodian. */
+    revokeCustodian(options: RevokeOptions, factors?: FactorProofBundle): Promise<void>;
+    /**
+     * Custodian-only: the audited claim of ownership over a sealed-owner (Deed)
+     * vault. Mints a DISTINCT new owner re-wrapping the incumbent DEKs under a
+     * fresh KEK (the latent owner is never impersonated), ledger-audited. See
+     * {@link liberateVault}.
+     */
+    liberate(opts: LiberateOptions): Promise<LiberateResult>;
+}

package/dist/with-party/custody/liberate.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `liberateVault` — the audited claim of ownership over a
+ * sealed-owner (Deed) vault. The inverse of withdrawal.
+ *
+ * A **Deed** vault's owner credential is sealed under a non-firm provider, so
+ * the firm-side **custodian** (which holds every collection DEK and operates
+ * the vault fully) can never reach `KEK_owner`. Liberation is the ONLY route
+ * by which a custodian assumes ownership, and it is deliberately a manual,
+ * audited ceremony:
+ *
+ *   1. gate `'liberate-vault'` (fail-closed)
+ *   2. caller MUST be the `custodian` (the de-facto authority holding the DEKs)
+ *   3. freeze a PRE-liberation EVIDENCE snapshot (hash-pinned in the ledger) —
+ *      but PRESERVE the live data for the new owner (see the freeze decision
+ *      below)
+ *   4. mint a NEW owner keyring re-wrapping the incumbent DEKs under the new
+ *      owner's KEK
+ *   5. lifecycle ledger `liberation-claimed:<newOwnerId>:<legalBasis>`
+ *   6. stamp the `_meta/deed` marker with `liberatedAt`
+ *
+ * ## Security: the inalienability floor
+ *
+ * Liberation **mints a new owner from the custodian's DEKs** — it does NOT
+ * unseal the original sealed owner. The old sealed-owner credential is left
+ * untouched and ORPHANED (its `_keyring/<id>` file remains, its KEK is still
+ * sealed under the non-firm provider), never impersonated. The new owner is a
+ * DISTINCT principal under a fresh KEK derived from `newOwnerPassphrase`. This
+ * preserves the inalienability floor: the act of claiming ownership is itself
+ * auditable and produces a different principal, rather than silently assuming
+ * the latent owner's identity.
+ *
+ * ## Freeze decision: snapshot-only, not freeze-and-delete
+ *
+ * `freezeAndDeleteClosure` (withdraw-accessible.ts) writes a hash-pinned
+ * snapshot and THEN delete-closures the live records — correct for a
+ * destructive withdrawal, WRONG for liberation. Liberation transfers
+ * operational continuity; it must leave the live data intact for the new
+ * owner. We therefore call the snapshot-only core `freezeSnapshotOnly`
+ * (factored out of that module; the freeze-AND-delete withdrawal path is
+ * unchanged) to pin the evidence snapshot while preserving the records.
+ *
+ * @module
+ */
+import type { Vault } from '../../kernel/vault.js';
+import type { FactorProofBundle } from '../../kernel/types.js';
+import type { FrozenSnapshotRef } from '../../with-audit/portability/withdraw-accessible.js';
+export interface LiberateOptions {
+    /** The id of the new owner principal the custodian mints by claiming ownership. */
+    readonly newOwnerId: string;
+    /** The passphrase that derives the new owner's KEK (the DEKs are re-wrapped under it). */
+    readonly newOwnerPassphrase: string;
+    /** Legal/contractual basis recorded in the audit (e.g. 'contractual-handover'). */
+    readonly legalBasis: string;
+    readonly factors?: FactorProofBundle;
+}
+export interface LiberateResult {
+    /** The hash-pinned pre-liberation evidence snapshot. */
+    readonly snapshot: FrozenSnapshotRef;
+}
+/**
+ * Audited claim of ownership over a sealed-owner vault by its custodian. See
+ * the module doc for the full ceremony + security rationale.
+ */
+export declare function liberateVault(vault: Vault, opts: LiberateOptions): Promise<LiberateResult>;

package/dist/with-party/custody/strategy.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Sovereign-custody (FR-6) capability strategy — the three on-demand
+ * operations the custody surface routes through: minting a custodian
+ * (`grantCustodian`), removing one (`revokeCustodian`), and the audited
+ * ownership-claim ceremony (`liberate`). The active engine ({@link withCustody})
+ * runs the grant/revoke impls the host exposes and dynamically imports the
+ * heavy `liberateVault` ceremony (keeping it out of the floor bundle);
+ * {@link NO_CUSTODY} throws.
+ *
+ * `Noydb.grantCustodian` / `Noydb.revokeCustodian` delegate here (passing
+ * themselves as the {@link CustodyHost}), and `vault.custody.liberate` delegates
+ * here with its {@link Vault}. An un-opted-in caller hits `NO_CUSTODY`'s throw.
+ *
+ * Note: the lower-level `liberateVault` FREE FUNCTION (exported from
+ * `custody/liberate.ts`) stays ungated — it has no `createNoydb` instance to
+ * gate against (the same carve-out as the `openSealedRecord` host opener). Only
+ * the instance surfaces (`db.grantCustodian` / `db.revokeCustodian` /
+ * `vault.custody.*`) are the capability.
+ * @internal
+ */
+import type { GrantOptions, RevokeOptions, FactorProofBundle, NoydbStore } from '../../kernel/types.js';
+import type { Vault } from '../../kernel/vault.js';
+import type { UnlockedKeyring } from '../team/keyring.js';
+import type { GrantCustodianOptions } from './index.js';
+import type { LiberateOptions, LiberateResult } from './liberate.js';
+/**
+ * The grant/revoke engine the strategy runs when opted in — implemented by
+ * `Noydb` (`_grantCustodianImpl` / `_revokeCustodianImpl` hold the gate +
+ * keyring logic; the public `grantCustodian` / `revokeCustodian` route through
+ * the strategy). Since the #267 team split the keyring grant/revoke engines
+ * are passed IN by `withCustody()` (statically linked there, not in the
+ * kernel) so the single-user floor never carries them.
+ */
+export interface CustodyHost {
+    _grantCustodianImpl(engine: (adapter: NoydbStore, vault: string, callerKeyring: UnlockedKeyring, options: GrantOptions) => Promise<void>, vault: string, options: GrantCustodianOptions, factors?: FactorProofBundle): Promise<void>;
+    _revokeCustodianImpl(engine: (adapter: NoydbStore, vault: string, callerKeyring: UnlockedKeyring, options: RevokeOptions) => Promise<void>, vault: string, options: RevokeOptions, factors?: FactorProofBundle): Promise<void>;
+}
+export interface CustodyStrategy {
+    grantCustodian(host: CustodyHost, vault: string, options: GrantCustodianOptions, factors?: FactorProofBundle): Promise<void>;
+    revokeCustodian(host: CustodyHost, vault: string, options: RevokeOptions, factors?: FactorProofBundle): Promise<void>;
+    liberate(vault: Vault, opts: LiberateOptions): Promise<LiberateResult>;
+}
+/**
+ * No-op stub — the floor default. Every custody operation throws
+ * {@link CustodyNotEnabledError}; opt in with `custodyStrategy: withCustody()`
+ * in createNoydb. @internal
+ */
+export declare const NO_CUSTODY: CustodyStrategy;