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

package/dist/with-audit/attestation/signer.d.ts

@@ -0,0 +1,33 @@
+import type { NoydbStore } from '../../kernel/types.js';
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+export declare const ATTESTATIONS_COLLECTION = "_attestations";
+export declare const SIGNER_RECORD_ID = "_signer";
+export declare const REVOKED_RECORD_ID = "_revoked";
+export interface DocSigner {
+    readonly keyId: string;
+    readonly publicKeyB64: string;
+    readonly privateKeyPkcs8B64: string;
+}
+/**
+ * Pure read: return the firm's persisted document-signing keypair, or `null`
+ * if none has been minted yet. Never writes — callers that must NOT mint
+ * (e.g. an ungated public-key getter) use this instead of `loadOrCreateSigner`.
+ *
+ * Stored as an encrypted record `_attestations/_signer` under the
+ * `_attestations` collection DEK (resolved via `getDEK`, which is
+ * AES-KW-wrapped under the owner KEK + persisted by the keyring). The KEK
+ * itself is AES-KW-only and cannot AES-GCM-encrypt these bytes — hence
+ * storage under a normal collection DEK.
+ */
+export declare function loadSigner(store: NoydbStore, vault: string, getDEK: (collection: string) => Promise<EnclaveKey>): Promise<DocSigner | null>;
+/**
+ * Lazily mint (or load) the firm's Ed25519 document-signing keypair.
+ *
+ * On a concurrent first-mint, two callers can both read `null` and both mint
+ * distinct keypairs. The `put(…, expectedVersion: 0)` ("must not already
+ * exist") lets exactly one win; the loser catches `ConflictError`, re-reads,
+ * and returns the winner's signer — converging on a single keypair rather than
+ * clobbering it or surfacing a raw conflict. (All real stores treat a missing
+ * record + `ev: 0` as a no-conflict write, so the catch fires on lost-race only.)
+ */
+export declare function loadOrCreateSigner(store: NoydbStore, vault: string, getDEK: (collection: string) => Promise<EnclaveKey>): Promise<DocSigner>;

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

@@ -0,0 +1,44 @@
+import type { NoydbStore } from '../../kernel/types.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+import type { RevocationList } from '@noy-db/attestation';
+import type { IssueContext, IssueArgs, IssueResult } from './issue.js';
+import type { RevokeContext } from './revoke.js';
+/**
+ * Deps the signing-public-key lookup needs. Unlike issue/revoke there is no
+ * per-call context object for it, so the vault facade assembles this at call
+ * time (reading `role` fresh).
+ */
+export interface SignerLookupDeps {
+    readonly adapter: NoydbStore;
+    readonly vault: string;
+    /** The invoking keyring's role, read fresh by the caller per call. */
+    readonly role: string;
+    /** Per-collection DEK resolver (bound `vault.getDEK`). */
+    readonly getDEK: (collection: string) => Promise<EnclaveKey>;
+}
+/**
+ * Attestation capability strategy — the six on-demand methods the vault's
+ * attestation delegators route through. The active engine ({@link withAttestation})
+ * dynamically imports the issue/revoke/signer cores (keeping them out of the floor
+ * bundle); {@link NO_ATTESTATION} throws. The vault-side {@link VaultAttestation}
+ * facade holds the per-collection field-schema registry and builds the per-call
+ * contexts, then delegates here.
+ * @internal
+ */
+export interface AttestationStrategy {
+    issueAttestation(ctx: IssueContext, args: IssueArgs): Promise<IssueResult>;
+    getDocumentSigningPublicKey(deps: SignerLookupDeps): Promise<{
+        keyId: string;
+        publicKeyB64: string;
+    }>;
+    revokeAttestation(ctx: RevokeContext, docId: string): Promise<void>;
+    unrevokeAttestation(ctx: RevokeContext, docId: string): Promise<void>;
+    getRevokedDocIds(ctx: RevokeContext): Promise<string[]>;
+    publishRevocationList(ctx: RevokeContext): Promise<RevocationList>;
+}
+/**
+ * No-op stub — the floor default. Every capability method throws
+ * {@link AttestationNotEnabledError}; opt in with
+ * `attestationStrategy: withAttestation()` in createNoydb. @internal
+ */
+export declare const NO_ATTESTATION: AttestationStrategy;

package/dist/with-audit/attestation/vault-facade.d.ts

@@ -0,0 +1,62 @@
+import type { NoydbStore } from '../../kernel/types.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+import type { AttestationFieldSchema, RevocationList } from '@noy-db/attestation';
+import type { AttestationStrategy } from './strategy.js';
+export { NO_ATTESTATION, type AttestationStrategy } from './strategy.js';
+/** Everything the moving attestation methods touched on the vault's `this.*`. */
+export interface VaultAttestationDeps {
+    /** The ciphertext store. */
+    readonly adapter: NoydbStore;
+    /** Vault namespace name. */
+    readonly vault: string;
+    /** Per-collection DEK resolver (bound `vault.getDEK`). */
+    readonly getDEK: (collection: string) => Promise<EnclaveKey>;
+    /** The invoking keyring's role (read fresh per call). */
+    role(): string;
+    /** Decrypt a collection record at `locale: 'raw'` (issue side reads the live record). */
+    getRawRecord(collection: string, id: string): Promise<Record<string, unknown> | null>;
+}
+export declare class VaultAttestation {
+    private readonly deps;
+    /**
+     * Opt-in capability gate. `NO_ATTESTATION` when
+     * `createNoydb({ attestationStrategy })` was omitted — every issue/revoke/
+     * signer call then throws `AttestationNotEnabledError`. The facade always
+     * exists (it holds the per-collection field-schema registry populated at
+     * `collection()` time); only the capability methods are gated.
+     */
+    private readonly strategy;
+    /**
+     * Per-collection attestation field-schema (issue side). Populated on
+     * `collection({ attestation })` via {@link register} and read by
+     * {@link issue}. Indexed by collection name.
+     */
+    private readonly registry;
+    constructor(deps: VaultAttestationDeps, 
+    /**
+     * Opt-in capability gate. `NO_ATTESTATION` when
+     * `createNoydb({ attestationStrategy })` was omitted — every issue/revoke/
+     * signer call then throws `AttestationNotEnabledError`. The facade always
+     * exists (it holds the per-collection field-schema registry populated at
+     * `collection()` time); only the capability methods are gated.
+     */
+    strategy: AttestationStrategy);
+    /** Register a collection's attestation field-schema (from `vault.collection`). */
+    register(collection: string, schema: AttestationFieldSchema): void;
+    issue(collectionName: string, id: string): Promise<{
+        docId: string;
+        qr: string;
+        keyId: string;
+        publicKeyB64: string;
+    }>;
+    getDocumentSigningPublicKey(): Promise<{
+        keyId: string;
+        publicKeyB64: string;
+    }>;
+    private makeIssueContext;
+    revoke(docId: string): Promise<void>;
+    unrevoke(docId: string): Promise<void>;
+    getRevokedDocIds(): Promise<string[]>;
+    publishRevocationList(): Promise<RevocationList>;
+    private makeRevokeContext;
+}

package/dist/with-audit/consent/active.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Active consent strategy. Calling `withConsent()` returns a
+ * `ConsentStrategy` that delegates to the real
+ * `writeConsentEntry` / `loadConsentEntries` functions. Only
+ * reachable through the `@noy-db/hub/consent` subpath.
+ */
+import type { ConsentStrategy } from './strategy.js';
+/**
+ * Build the default consent strategy. Pass into
+ * `createNoydb({ consentStrategy: withConsent() })` to enable
+ * per-operation audit writes into the reserved `_consent_audit`
+ * collection.
+ */
+export declare function withConsent(): ConsentStrategy;

package/dist/with-audit/consent/consent.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Consent boundaries — per-access audit log.
+ *
+ * ```ts
+ * const audit = await vault.withConsent(
+ *   { purpose: 'quarterly-review', consentHash: '7f3a...' },
+ *   async () => {
+ *     const invoices = await vault.collection<Invoice>('invoices').list()
+ *     return invoices
+ *   },
+ * )
+ *
+ * const log = await vault.consentAudit({ since: '2026-01-01T00:00:00Z' })
+ * // → entries: { actor, purpose, consentHash, ts, op, collection, id }
+ * ```
+ *
+ * ## Contract
+ *
+ * Every `get` / `put` / `delete` that happens inside a `withConsent`
+ * callback writes one entry to the reserved `_consent_audit`
+ * collection. Entries are encrypted with the vault's consent-audit
+ * DEK (separate from per-user-collection DEKs so access-log queries
+ * don't require unwrapping individual collection keys). Outside a
+ * `withConsent` scope, no entries are written — consent is
+ * opt-in by design (GDPR Art. 7: *demonstrable*, *specific*
+ * consent).
+ *
+ * ## Why store the hash, not the consent text?
+ *
+ * The `consentHash` is the sha256 of whatever consent receipt the
+ * actor presented (a signed GDPR banner click, a HIPAA authorisation
+ * PDF, an API-level `X-Consent-Hash` header). Storing only the hash:
+ *
+ *   1. Keeps the audit log small and indexable.
+ *   2. Preserves zero-knowledge at the adapter — adapters see
+ *      ciphertext envelopes of `{ actor, purpose, consentHash, ts,
+ *      op, collection, id }`, never the consent record itself.
+ *   3. Lets the regulator verify a presented consent doc matches
+ *      the logged hash at audit time without the system ever
+ *      possessing the doc.
+ *
+ * ## Concurrency
+ *
+ * The consent context lives on the {@link Vault} instance. Two
+ * concurrent `withConsent` calls on the same Vault would stomp each
+ * other — documented limitation; adopters needing per-flight scope
+ * should use separate Vault instances or an AsyncLocalStorage shim.
+ *
+ * @module
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+/** Reserved collection for consent-audit entries. */
+export declare const CONSENT_AUDIT_COLLECTION = "_consent_audit";
+/**
+ * The consent scope active for a block of work. Set via
+ * `vault.withConsent()`; observed by the collection's access hooks.
+ */
+export interface ConsentContext {
+    /**
+     * What this access is for. Used by the audit query (`consentAudit
+     * ({ purpose })`) and carried in the stored entry. Free-form; the
+     * regulator or compliance tooling decides the vocabulary.
+     */
+    readonly purpose: string;
+    /**
+     * Hex-encoded sha256 of whatever consent artefact the actor
+     * presented. Stored as-is in each entry.
+     */
+    readonly consentHash: string;
+}
+/**
+ * Access operation recorded in an audit entry.
+ *
+ * Union-widening checklist (I-2) — these three sites widen together or a
+ * downstream exhaustive switch breaks at its next in-range minor:
+ *   1. `ConsentOp` here (public, re-exported at `index.ts`).
+ *   2. `onAccess` op union on `kernel/collection-config.ts`.
+ *   3. classified ctx `onAccess` op union on `port/with/classified-strategy.ts`
+ *      (the `ClassifiedVerifyCtx` one — the `ClassifiedRevealCtx` one stays `'reveal'`-only).
+ */
+export type ConsentOp = 'get' | 'put' | 'delete' | 'reveal' | 'verify' | 'find';
+/** One consent-audit record, as decrypted for the caller. */
+export interface ConsentAuditEntry {
+    /** ULID — stable insertion-order key. */
+    readonly id: string;
+    readonly timestamp: string;
+    readonly actor: string;
+    readonly purpose: string;
+    readonly consentHash: string;
+    readonly op: ConsentOp;
+    readonly collection: string;
+    readonly recordId: string;
+}
+/** Filter passed to `vault.consentAudit()`. */
+export interface ConsentAuditFilter {
+    /** Only entries at or after this ISO timestamp. */
+    readonly since?: string;
+    /** Only entries at or before this ISO timestamp. */
+    readonly until?: string;
+    /** Match entries targeting this collection. */
+    readonly collection?: string;
+    /** Match entries written by this actor. */
+    readonly actor?: string;
+    /** Match entries with this purpose. */
+    readonly purpose?: string;
+}
+/**
+ * Write one audit entry. Called by Vault's onAccess hook when a
+ * consent context is active.
+ */
+export declare function writeConsentEntry(adapter: NoydbStore, vault: string, encrypted: boolean, entry: Omit<ConsentAuditEntry, 'id' | 'timestamp'>, getDEK: (collection: string) => Promise<EnclaveKey>): Promise<void>;
+/** Load + decrypt + filter all entries. */
+export declare function loadConsentEntries(adapter: NoydbStore, vault: string, encrypted: boolean, getDEK: (collection: string) => Promise<EnclaveKey>, filter?: ConsentAuditFilter): Promise<ConsentAuditEntry[]>;

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

@@ -0,0 +1,14 @@
+/**
+ * @noy-db/hub/consent — opt-in consent-audit service.
+ *
+ * @category capability
+ *
+ * Records per-operation consent entries into a reserved
+ * `_consent_audit` collection when a consent scope is active.
+ * Applications that don't need GDPR-style audit trails can omit this
+ * subpath and skip the ~194 LOC.
+ */
+export { withConsent } from './active.js';
+export type { ConsentStrategy } from './strategy.js';
+export { CONSENT_AUDIT_COLLECTION, writeConsentEntry, loadConsentEntries, } from './consent.js';
+export type { ConsentContext, ConsentOp, ConsentAuditEntry, ConsentAuditFilter, } from './consent.js';

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

@@ -0,0 +1,36 @@
+/**
+ * Strategy seam for the optional consent-audit service. Core
+ * imports `ConsentStrategy` as a TYPE-ONLY symbol and `NO_CONSENT`
+ * as a tiny runtime stub.
+ *
+ * `writeConsentEntry` / `loadConsentEntries` are only reachable from
+ * `withConsent()` in `./active.ts`, exported through
+ * `@noy-db/hub/consent`. Applications without a consent scope ship
+ * none of the ~194 LOC.
+ *
+ * @internal
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+import type { ConsentAuditEntry, ConsentAuditFilter } from './consent.js';
+/**
+ * @internal
+ */
+export interface ConsentStrategy {
+    /**
+     * Record one consent audit entry. No-op under NO_CONSENT.
+     */
+    write(adapter: NoydbStore, vault: string, encrypted: boolean, entry: Omit<ConsentAuditEntry, 'id' | 'timestamp'>, getDEK: (collectionName: string) => Promise<EnclaveKey>): Promise<void>;
+    /**
+     * Read filtered consent entries. Returns `[]` under NO_CONSENT.
+     */
+    read(adapter: NoydbStore, vault: string, encrypted: boolean, getDEK: (collectionName: string) => Promise<EnclaveKey>, filter?: ConsentAuditFilter): Promise<ConsentAuditEntry[]>;
+}
+/**
+ * No-consent stub. `write` is a no-op (returns a resolved promise);
+ * `read` returns `[]`. Consumers get a consistent API surface without
+ * pulling the consent module into the bundle.
+ *
+ * @internal
+ */
+export declare const NO_CONSENT: ConsentStrategy;

package/dist/with-audit/forget/active.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `withForgetCascade` — the active factory for GDPR right-to-erasure via
+ * per-record CEK crypto-shred. Mirrors the canonical
+ * `strategy.ts` (type + `NO_FORGET` sentinel) / `active.ts` (factory) split
+ * used by the other services.
+ *
+ * @module
+ */
+import type { SubjectDeclaration, ForgetStrategy } from './strategy.js';
+/**
+ * Declare GDPR crypto-shred for one or more collections.
+ *
+ * Each declared collection is forced to `perRecordKeys: true` (a shred can
+ * only guarantee erasure of a record whose body is keyed off a per-record
+ * CEK). On write, Noydb extracts `record[subjectField]` and maintains an
+ * encrypted `_subject_index` mapping `subject → [{collection, id}]`, so
+ * `vault.forget(subjectId)` can find every record for a subject and rewrite
+ * each to a tombstone (body + history permanently undecryptable) while the
+ * collection DEK and every other record stay intact.
+ *
+ * @example
+ * ```ts
+ * createNoydb({
+ *   secret, user,
+ *   forgetStrategy: withForgetCascade({ subjects: { invoices: 'buyerId' } }),
+ * })
+ * const result = await vault.forget('buyer-123')
+ * // → { subject, recordsShredded, historyVersionsShredded, collections, … }
+ * ```
+ */
+export declare function withForgetCascade(opts: SubjectDeclaration): ForgetStrategy;

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

@@ -0,0 +1,28 @@
+/**
+ * `@noy-db/hub/forget` — GDPR right-to-erasure via per-record CEK crypto-shred.
+ * Import `withForgetCascade` and pass it to `createNoydb`:
+ *
+ * ```ts
+ * import { createNoydb } from '@noy-db/hub'
+ * import { withForgetCascade } from '@noy-db/hub/forget'
+ *
+ * const db = createNoydb({
+ *   secret, user,
+ *   historyStrategy: withHistory(),               // ledger for the erasure proof
+ *   forgetStrategy: withForgetCascade({ subjects: { invoices: 'buyerId' } }),
+ * })
+ * const result = await db.vault('main').forget('buyer-123')
+ * ```
+ *
+ * The erasure flow (`vault.forget`), the subject-index maintenance hooks, and
+ * the tombstone rewrite live in core (`vault.ts` / `collection.ts`) because
+ * they touch the write path directly; this subpath only exposes the
+ * declaration factory + result types.
+ *
+ * @module
+ */
+export { withForgetCascade } from './active.js';
+export { NO_FORGET } from './strategy.js';
+export type { SubjectDeclaration, ForgetStrategy, ForgetResult, ScopedPurgeResidueNotice, } from './strategy.js';
+export type { SubjectRef } from './subject-index.js';
+export { SUBJECT_INDEX_COLLECTION } from './subject-index.js';

package/dist/with-audit/forget/purge-scope.d.ts

@@ -0,0 +1,54 @@
+/**
+ * #633 — scoped-purge partitioning for the opt-in `scopedPurge` forget-strategy
+ * knob (`strategy.ts`'s `SubjectDeclaration.scopedPurge`). Pure helpers only —
+ * no store I/O, no `Vault`/`Collection` imports — kept out of `kernel/vault.ts`
+ * (exact zero-slack `kernel-surface` ceiling) and free of any circular-import
+ * risk with the kernel spine.
+ *
+ * The two `forget()` purge sites (`_sealed_cek` listing, blob shred) stay
+ * UNCONDITIONAL by default (byte-identical to pre-#633 behavior); when
+ * `scopedPurge` is `true`, each site calls into this module to decide what to
+ * purge vs. what to leave in place + report as residue, keyed off a
+ * per-collection declaration signal the caller (vault.ts) resolves itself:
+ *   - sealed-CEK arm: `coll._via?.hasAtRestHooks === true` — the classified
+ *     via binding's at-rest hooks (the "richer" declaration; a bare
+ *     `sensitive` collection with NO classified binder does not count — it can
+ *     still call `sealRecordToHost()` ad hoc, which is exactly the
+ *     under-approximation #633 calls out).
+ *   - blob arm: `this.blobFieldsRegistry.has(ref.collection)` — a collection
+ *     can call `.blob(id)` regardless of this declaration (same
+ *     under-approximation), which is why the default stays unconditional.
+ *
+ * @module
+ */
+import type { ScopedPurgeResidueReason } from './strategy.js';
+/**
+ * Partitions an already-fetched vault-wide `_sealed_cek` key listing into
+ * keys to purge vs. a skipped count, for ONE ref's `<collection>/<id>/`
+ * prefix. No new store call — `keys` is the SAME listing the unconditional
+ * path already fetched. Default parity: when `scopedPurge` is false, or
+ * `declared` is true, every matching key is returned for purge and
+ * `skippedCount` is 0 — byte-identical to the unconditional behavior.
+ */
+export declare function partitionSealedCekKeys(keys: readonly string[], prefix: string, scopedPurge: boolean, declared: boolean): {
+    readonly toPurge: readonly string[];
+    readonly skippedCount: number;
+};
+/**
+ * True when the blob arm should skip `ref.collection` entirely — no
+ * `.blob(id).shredAllForRecord()` call AND no `_blob_slots_<collection>`
+ * residue-detection `list()` call either (the perf win: scoped mode never
+ * pays for a per-collection scan on a collection that never declared
+ * `blobFields`).
+ */
+export declare function shouldSkipBlobScan(scopedPurge: boolean, declared: boolean): boolean;
+/** Adds `count` (if positive) to `collection`'s running total in `map` — the
+ *  per-collection residue accumulator both purge sites share. */
+export declare function bumpResidueCount(map: Map<string, number>, collection: string, count: number): void;
+/** Flattens an accumulated per-collection count map into `ForgetResult.scopedPurgeResidue` notices
+ *  tagged with `reason`. Empty map → empty array (the unconditional-default case). */
+export declare function residueNoticesFromMap(map: ReadonlyMap<string, number>, reason: ScopedPurgeResidueReason): {
+    readonly reason: ScopedPurgeResidueReason;
+    readonly collection: string;
+    readonly count: number;
+}[];

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

@@ -0,0 +1,199 @@
+/**
+ * `withForgetCascade` — declaration surface for GDPR right-to-erasure via
+ * per-record CEK crypto-shred.
+ *
+ * This file holds only the *declaration* shape and the disabled sentinel.
+ * The actual erasure machinery lives in:
+ *   - `subject-index.ts` — the encrypted `_subject_index` reserved collection
+ *   - `vault.ts` `forget()` — the per-record tombstone + ledger flow
+ *   - `collection.ts` `_writeTombstone` — the envelope rewrite
+ *
+ * A `ForgetStrategy` declares which collections carry erasable subject data
+ * and the (dotted-path) field on each record that names the data subject.
+ * Declaring a collection here ALSO forces `perRecordKeys: true` for it (a
+ * shred can only erase a record whose body is keyed off a per-record CEK),
+ * so adopters opt into the CEK foundation transitively.
+ *
+ * @module
+ */
+import type { LedgerEntry } from '../../with-commit/history/ledger/entry.js';
+/**
+ * User-supplied declaration passed to {@link withForgetCascade}. Maps a
+ * collection name to the record field (dotted path supported, e.g.
+ * `'billing.buyerId'`) that identifies the data subject for erasure.
+ *
+ * ```ts
+ * withForgetCascade({ subjects: { invoices: 'buyerId', contacts: 'id' } })
+ * ```
+ */
+export interface SubjectDeclaration {
+    readonly subjects: Record<string, string>;
+    /**
+     * #633 — opt-in: gate the vault-level `_sealed_cek` and blob purges on
+     * per-collection via declarations instead of running them unconditionally
+     * for every forgotten ref. Default `false`/absent = today's unconditional
+     * behavior (byte-identical). See `purge-scope.ts` for the partition logic
+     * and the `scopedPurgeResidue` skip-reporting this enables.
+     *
+     * **Footgun:** a bare `sensitive: [...]` collection — no `classifiedFields`
+     * (no classified via binder compiled in) — counts as UNDECLARED for the
+     * sealed-CEK arm. Under `scopedPurge: true`, its `_sealed_cek` host-delivery
+     * envelopes are SKIPPED, not purged (reported via `scopedPurgeResidue`,
+     * reason `'skipped-undeclared-sealed-cek'`) even if that collection called
+     * `sealRecordToHost()` — the sealed CEK stays recoverable by that granted
+     * host until purged. Add a `classifiedFields` binding to close the gap, or
+     * leave `scopedPurge` off/false for the unconditional (always-purged) default.
+     * The declaration signal is session-local: a declared collection never opened
+     * (with its config) before `forget()` in this session counts as UNDECLARED —
+     * open it first, or its entries are skipped-and-reported.
+     */
+    readonly scopedPurge?: boolean;
+}
+/**
+ * Resolved forget strategy threaded through Noydb → every Vault. Carries
+ * the same `subjects` map the user declared. `NO_FORGET` (empty map) is the
+ * off-by-default sentinel; `vault.forget()` throws
+ * `ForgetStrategyNotConfiguredError` when the map is empty.
+ */
+export interface ForgetStrategy {
+    /** Collection → subject-field (dotted path). Empty under `NO_FORGET`. */
+    readonly subjects: Readonly<Record<string, string>>;
+    /** #633 — see {@link SubjectDeclaration.scopedPurge}. */
+    readonly scopedPurge?: boolean;
+}
+/**
+ * Disabled sentinel — no collections declare a subject field. `vault.forget()`
+ * refuses with `ForgetStrategyNotConfiguredError`; no write hooks register; no
+ * collection is forced into `perRecordKeys`. Non-adopters pay nothing.
+ */
+export declare const NO_FORGET: ForgetStrategy;
+/**
+ * The outcome of a `vault.forget(subjectId)` call.
+ *
+ * `unmigratedRecords` lists `collection:id` pairs that were tombstoned but
+ * whose body had NOT been migrated to a per-record CEK at shred time (legacy
+ * body still under the shared collection DEK). Those records are tombstoned
+ * (live envelope + history stripped) but their pre-shred ciphertext, if it
+ * leaked into a backup before migration, remains decryptable under the
+ * collection DEK — so erasure-completeness is NOT guaranteed for them. Run
+ * the per-record-CEK migration pass, then re-forget, to close the gap.
+ *
+ * Blob attachments: a shredded record's **erasable** blobs (on a
+ * `perRecordKeys` collection) are crypto-shredded inline — `blobsShredded`
+ * counts those taken to refCount 0 (BlobObject deleted → chunks permanently
+ * undecryptable), `blobsRetainedShared` counts those still referenced by
+ * another record (shared content legitimately persists for its other owner).
+ * `blobResidueCollections` now lists only collections with blobs that could
+ * NOT be crypto-shredded: **legacy** blobs (no per-blob `_cek`, chunks under
+ * the shared `_blob` DEK — migrate them), or a session without the blob
+ * service loaded. An all-erasable subject yields an empty residue list.
+ */
+export interface ForgetResult {
+    /** The subject id passed to `forget()`. Echoed for caller convenience. */
+    readonly subject: string;
+    /** Count of live records rewritten to a tombstone. */
+    readonly recordsShredded: number;
+    /** Count of `_history` envelopes tombstoned across all shredded records. */
+    readonly historyVersionsShredded: number;
+    /** Distinct collections that had at least one record shredded. */
+    readonly collections: readonly string[];
+    /** `collection:id` pairs shredded while still un-migrated (see type docs). */
+    readonly unmigratedRecords: readonly string[];
+    /** Count of erasable blobs crypto-shredded (refCount → 0, BlobObject deleted). */
+    readonly blobsShredded: number;
+    /** Count of erasable blobs retained because still referenced elsewhere (shared). */
+    readonly blobsRetainedShared: number;
+    /** Collections with blobs that could NOT be crypto-shredded — legacy (no `_cek`) or blobs disabled (see type docs). */
+    readonly blobResidueCollections: readonly string[];
+    /**
+     * Count of persisted `_idx/<field>/<recordId>` index side-cars hard-deleted
+     * across the shredded records. These live under the retained
+     * collection DEK, so crypto-shred alone would leave the indexed field VALUES
+     * readable — `forget()` must delete them.
+     */
+    readonly indexPostingsPurged: number;
+    /**
+     * `collection:id:field` entries whose persisted `_idx` side-car could NOT be
+     * deleted — index residue that still leaks the indexed value under the
+     * retained collection DEK. Non-empty means erasure is INCOMPLETE: retry, or
+     * purge the side-car out of band.
+     */
+    readonly indexResidue: readonly string[];
+    /**
+     * Count of `_sealed[field]` slots dropped from the live store across the
+     * shredded records. For slots written under `sensitive` +
+     * `perRecordKeys` (the current path), the key derives off the per-record CEK,
+     * so tombstoning the record — which drops `_cek` and `_sealed` — also
+     * crypto-shreds the value. A legacy slot (written before per-record CEKs) keys
+     * off the collection DEK instead, so dropping it removes it from the live store but a
+     * pre-forget backup remains recoverable by a DEK holder (same caveat `_data`
+     * carries); migrate by re-`put`ting before forgetting for full crypto-shred.
+     */
+    readonly sealedFieldsShredded: number;
+    /** Count of `_sealed_cek` host-delivery envelopes deleted (#H-1). A record sealed to an
+     * at-* host via sealRecordToHost persists its raw CEK there; forget() must destroy them. */
+    readonly sealedCekEnvelopesPurged: number;
+    /** `collection:id` whose `_sealed_cek` purge failed (residue — the host-recoverable CEK may survive). */
+    readonly sealedCekResidue: readonly string[];
+    /** `collection:id:field` sealed slots that were DEK-derived (legacy, written before per-record CEKs) and thus NOT crypto-shredded
+     * by dropping `_cek` — the collection DEK is retained, so synced/backup copies stay decryptable (#M-1). */
+    readonly sealedResidue: readonly string[];
+    /** Count of `_ledger_deltas` rows hard-deleted across the shredded records (#734) — the
+     * erasure twin of #729's elevate-side purge. Entry metadata (that the record was mutated,
+     * at which version/timestamp/actor) is retained; only the plaintext delta content is removed. */
+    readonly ledgerDeltasPurged: number;
+    /** `collection:id` refs whose `_ledger_deltas` purge failed — plaintext delta residue still
+     * readable under the retained ledger DEK. Non-empty means erasure is INCOMPLETE. */
+    readonly ledgerDeltaResidue: readonly string[];
+    /** The single `op:'forget'` ledger entry appended for this erasure. */
+    readonly ledgerEntry: LedgerEntry;
+    /** #622 — record-grain derived artifacts (MV rows, per-record derived copies) erased
+     *  because their source subject was forgotten. Overlay outputs are intentionally out of
+     *  scope here — an overlay is always sourced from an MV, never directly from a subject
+     *  collection, so the personal-data-bearing MV rows it reads are already erased above. */
+    readonly derivedRecordsErased: number;
+    /** #622 — aggregate-grain targets (rollups) recomputed without the forgotten contribution. */
+    readonly derivedAggregatesRecomputed: number;
+    /** #622 — `collection:id` derived writes SKIPPED because the target period is frozen
+     *  (recompute deferred; the aggregate retains the forgotten contribution — audited). */
+    readonly derivedResidueFrozen: readonly string[];
+    /** #650 Task 5 (#648) — referencing records tombstoned via a `'ref'` edge's `cascade` policy. */
+    readonly lookupReferencesCascaded: number;
+    /** #650 Task 5 (#648) — referencing fields cleared via a `'ref'` edge's `nullify` policy. */
+    readonly lookupReferencesNullified: number;
+    /** #650 Task 5 review (Important fix) — `'ref'` edges whose compare-key could NOT be resolved,
+     *  even from the LIVE pre-shred backing row — cascade/nullify propagation was SKIPPED for these.
+     *  Always empty in the ordinary case; non-empty means the skip is reported, never silent. */
+    readonly lookupReferencesResidue: readonly string[];
+    /** #633 — scoped-purge skip notices (opt-in `scopedPurge`, see {@link SubjectDeclaration}).
+     *  Always empty under the unconditional default. Non-empty means a `_sealed_cek` entry or a
+     *  blob scan was skipped for an undeclared collection — reported, never a silent skip. */
+    readonly scopedPurgeResidue: readonly ScopedPurgeResidueNotice[];
+    /** #776/#782/#785 — `collection:id` MV-output rows that survived erasure invalidation (eager
+     *  tombstone leg AND lazy/manual `invalidateMVAtRest`) despite belonging to the forgotten
+     *  subject, because the `_materializedFrom` ownership stamp could NOT be decoded (undecodable
+     *  under the collection's default DEK — e.g. elevated above tier 0 on a tiered output
+     *  collection; ownership unconfirmed — could be a plain user record on a same-collection
+     *  partition MV). Never erased, but surfaced here rather than silently skipped (the #724
+     *  posture). Non-empty means the row may still hold the forgotten/pre-elevation contribution,
+     *  decryptable by tier-holders. */
+    readonly derivedResidueUndecodable: readonly string[];
+    /** #782/#785 — `collection:id` MV-output rows that DID decode and stamp-match via
+     *  `_materializedFrom`, but whose erasure was declined by the #718 tier-elevation gate
+     *  (`_internalDelete` returned false). Ownership CONFIRMED here — a real silent survival,
+     *  not a stamp-mismatch skip — surfaced rather than dropped. Non-empty means a live,
+     *  tier-holder-decryptable copy of the forgotten contribution was deliberately retained. */
+    readonly derivedResidueDeclined: readonly string[];
+}
+/** #633 — the two `scopedPurgeResidue` skip reasons. Single source of truth: `purge-scope.ts`
+ *  (the port-internal partition helpers) imports this rather than redeclaring it. */
+export type ScopedPurgeResidueReason = 'skipped-undeclared-sealed-cek' | 'skipped-undeclared-blob-scan';
+/** #633 — one `ForgetResult.scopedPurgeResidue` entry: an undeclared collection's sealed-CEK
+ *  entries left unpurged, or its blob scan skipped entirely, under `scopedPurge`. `count` is the
+ *  number of `_sealed_cek` entries left in place (sealed-cek reason) or the number of refs whose
+ *  blob scan was skipped (blob-scan reason) — aggregated per collection across the whole call. */
+export interface ScopedPurgeResidueNotice {
+    readonly reason: ScopedPurgeResidueReason;
+    readonly collection: string;
+    readonly count: number;
+}