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

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;
+}

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

@@ -0,0 +1,83 @@
+/**
+ * The encrypted subject index.
+ *
+ * GDPR crypto-shred needs to answer "which records belong to data subject
+ * X?" portably (the index must travel with the vault/bundle) WITHOUT leaking
+ * subject-equivalence to the store. The rejected alternative — an unencrypted
+ * subject tag in envelope metadata — would let anyone with store access see
+ * which records share a subject. Instead we keep a reserved `_subject_index`
+ * collection, encrypted under its OWN DEK (`getDEK('_subject_index')`):
+ *
+ *   - record id  = `HMAC-SHA256(indexDEK, subjectId)` (M-2). A bare
+ *     `sha256Hex(subjectId)` would be offline-computable: an attacker with
+ *     store access and a candidate list (emails / customer ids are low-entropy)
+ *     could dictionary the hash to confirm "subject X is present here." Keying
+ *     the id with the vault-only index DEK removes that capability — without the
+ *     DEK the id cannot be derived. (Legacy entries written before M-2 used the
+ *     bare sha256 id; the read/remove paths dual-look-up both forms.)
+ *   - record body = AES-GCM(JSON `{ r: [{ collection, id }], p }`) under the
+ *     index DEK, where `p` pads the plaintext to a bucketed length so the
+ *     ciphertext `_data` length does not leak the approximate record count.
+ *     Legacy bodies were a bare `[{ collection, id }]` array; reads accept both.
+ *
+ * ## Concurrency (RISK #3 — known v1 limitation)
+ *
+ * `addSubjectRef` / `removeSubjectRef` are read-modify-write with no CAS. The
+ * design assumes a SINGLE WRITER (the noy-db single-process write model). Two
+ * concurrent writers racing on the SAME subject can lose an entry (last-write
+ * wins on the ref list). This is documented, not fixed in v1:
+ * `rebuildSubjectIndex` performs a full scan to recover a correct index from
+ * the canonical records, so a lost ref is recoverable. A CAS-backed index is
+ * deferred to a later slice.
+ *
+ * @module
+ */
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+import type { NoydbStore, EncryptedEnvelope } from '../../kernel/types.js';
+/** Reserved collection holding the encrypted subject → records index. */
+export declare const SUBJECT_INDEX_COLLECTION = "_subject_index";
+/** A single record reference held in a subject's index entry. */
+export interface SubjectRef {
+    readonly collection: string;
+    readonly id: string;
+}
+type GetDEK = (collectionName: string) => Promise<EnclaveKey>;
+/**
+ * Add a `{ collection, id }` ref to a subject's index entry (idempotent —
+ * a duplicate ref is not appended). Read-modify-write; see the concurrency
+ * note in the module docstring.
+ */
+export declare function addSubjectRef(adapter: NoydbStore, vault: string, getDEK: GetDEK, encrypted: boolean, subjectId: string, ref: SubjectRef): Promise<void>;
+/**
+ * Remove a `{ collection, id }` ref from a subject's index entry. When the
+ * last ref is removed the (now empty) entry is deleted so the store holds no
+ * residual key for an erased subject.
+ */
+export declare function removeSubjectRef(adapter: NoydbStore, vault: string, getDEK: GetDEK, encrypted: boolean, subjectId: string, ref: SubjectRef): Promise<void>;
+/**
+ * Look up every record ref for a subject. Returns `[]` when none exist. Unions
+ * the keyed (M-2) and legacy sha256 entries (dual-lookup), deduplicated, so a
+ * subject indexed before M-2 is still fully found.
+ */
+export declare function lookupSubject(adapter: NoydbStore, vault: string, getDEK: GetDEK, encrypted: boolean, subjectId: string): Promise<SubjectRef[]>;
+/**
+ * Rebuild the entire subject index from the canonical records (the recovery
+ * path for the documented read-modify-write race). Scans each declared
+ * collection, reads `record[subjectField]` (dotted path), and rewrites the
+ * index from scratch. Tombstoned (already-shredded) records contribute no
+ * ref — their body is gone, so they cannot be re-indexed.
+ *
+ * `decodeRecord` decrypts an envelope to a plain object (or returns null for
+ * a tombstone / unreadable record); supplied by the caller so this module
+ * stays free of Collection internals.
+ */
+export declare function rebuildSubjectIndex(adapter: NoydbStore, vault: string, getDEK: GetDEK, encrypted: boolean, subjects: Readonly<Record<string, string>>, decodeRecord: (collection: string, id: string, env: EncryptedEnvelope) => Promise<Record<string, unknown> | null>): Promise<number>;
+/**
+ * Coerce a read subject-field value to a stable string id. Primitives use
+ * their natural string form; objects/arrays are JSON-stringified so structural
+ * subjects still get a deterministic key (avoids the `[object Object]` trap).
+ */
+export declare function coerceSubjectId(value: unknown): string;
+/** Read a (possibly dotted) field path from a plain record. */
+export declare function readDottedPath(record: Record<string, unknown>, field: string): unknown;
+export {};

package/dist/with-audit/guards/executor.d.ts

@@ -0,0 +1,26 @@
+import type { GuardStrategy, GuardContext, GuardChange } from './types.js';
+/**
+ * Pure functions that execute the work declared by a `GuardStrategy`.
+ * Stateless — `GuardRegistry` decides when to call these.
+ *
+ * @internal
+ */
+export declare const GuardExecutor: {
+    /**
+     * Compare existing vs incoming for each `frozenFields.fields` entry
+     * when `frozenFields.when(existing)` is true. Throws
+     * `FieldFrozenError` listing every changed frozen field.
+     *
+     * @param skipFields — field names that are schema-owned computed fields.
+     *   These are excluded from the comparison because `incoming` carries the
+     *   raw user input (computed fields not yet evaluated), so comparing
+     *   `existing[field]` vs `incoming[field]` would always look like a
+     *   change even when the computed result is unchanged.
+     */
+    checkFrozenFields<T extends Record<string, unknown>>(guard: GuardStrategy<T>, id: string, existing: T | null, incoming: T, skipFields?: ReadonlySet<string>): Promise<void>;
+    /**
+     * Run a single guard's invariant over its slice of the change-set.
+     * Any throw is converted to `InvariantError` unless it already is one.
+     */
+    runInvariant<T extends Record<string, unknown>>(guard: GuardStrategy<T>, changes: ReadonlyArray<GuardChange<T>>, ctx: GuardContext<T>): Promise<void>;
+};

package/dist/with-audit/guards/immutable-guard.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `immutableGuard` — declarative WORM / append-only sugar over the guard
+ * service.
+ *
+ * Issued fiscal documents (invoices, DDTs) must be immutable after issue.
+ * That is expressible today with a hand-rolled `withGuard` (block on
+ * `check`/`onDelete`, allow an admin `amendment`), but the boilerplate is
+ * repetitive and easy to get subtly wrong. `immutableGuard` generates
+ * exactly that guard from a declarative config, reusing the guard
+ * machinery wholesale — `check`/`onDelete` rejection, the ledgered
+ * `amendment` override, and composition with `periods`/`history`.
+ *
+ * ```ts
+ * createNoydb({ guardStrategies: [
+ *   immutableGuard({
+ *     collection: 'invoices',
+ *     after: (r) => r.status === 'issued',   // immutable once issued
+ *   }),
+ * ] })
+ * ```
+ *
+ * A record is mutable until `after(record)` holds; from then on, updates
+ * and deletes throw `RecordLockedError` unless performed inside an
+ * `amendment` transaction by an authorized role (the override is
+ * ledgered by the guard amendment mechanism). `appendOnly: true` is
+ * shorthand for `after: () => true` — immutable from creation.
+ */
+import type { GuardStrategyHandle, GuardContext, GuardChange } from './types.js';
+export interface ImmutableGuardConfig<T extends Record<string, unknown>> {
+    /** The collection to make WORM. */
+    collection: string;
+    /**
+     * A record becomes immutable once this predicate holds. Evaluated on
+     * the *existing* (already-persisted) record, so the write that first
+     * makes it true is still allowed; subsequent writes are blocked.
+     * Mutually exclusive with `appendOnly`.
+     */
+    after?: (record: T) => boolean;
+    /** Shorthand for `after: () => true` — immutable from creation. */
+    appendOnly?: boolean;
+    /** Roles permitted to override via an amendment transaction. Default `['admin', 'owner']`. */
+    amendmentRoles?: ReadonlyArray<'admin' | 'owner'>;
+    /**
+     * Optional set-level invariant run over the amendment change-set after
+     * the writes execute. Signature matches `GuardStrategy.amendment.invariant`
+     * exactly: it receives every {before, after} pair touching this
+     * collection in the amendment plus the guard context; throwing reverts
+     * the whole amendment and surfaces as `InvariantError`.
+     *
+     * Use this to keep a constraint inviolable EVEN under amendment — e.g.
+     * forbid deleting an issued document by re-throwing on any
+     * `before !== null && after === null` change, or assert a cross-record
+     * sum is preserved. When omitted the amendment is unconditionally
+     * allowed (the amendment itself is the sanctioned, ledgered override) —
+     * this is the backward-compatible default.
+     */
+    amendmentInvariant?: (changes: ReadonlyArray<GuardChange<T>>, ctx: GuardContext<T>) => Promise<void> | void;
+}
+/**
+ * Build an immutability guard. Pass the returned handle to
+ * `createNoydb({ guardStrategies: [...] })`.
+ */
+export declare function immutableGuard<T extends Record<string, unknown>>(config: ImmutableGuardConfig<T>): GuardStrategyHandle<T>;

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

@@ -0,0 +1,10 @@
+export { withGuard } from './with-guard.js';
+export { immutableGuard } from './immutable-guard.js';
+export type { ImmutableGuardConfig } from './immutable-guard.js';
+export { transitionGuard } from './transition-guard.js';
+export type { TransitionGuardConfig } from './transition-guard.js';
+export { GuardRegistry } from './registry.js';
+export { GuardExecutor } from './executor.js';
+export { ReadOnlyVaultFacade } from './read-only-facade.js';
+export type { GuardStrategy, GuardStrategyHandle, GuardContext, GuardChange, } from './types.js';
+export { RecordLockedError, FieldFrozenError, IllegalTransitionError, InvariantError, AmendmentForbiddenError, } from '../../kernel/errors.js';

package/dist/with-audit/guards/read-only-facade.d.ts

@@ -0,0 +1,31 @@
+import type { Vault } from '../../kernel/vault.js';
+import type { Query } from '../../kernel/query/builder.js';
+import type { Layer } from '../../via/i18n/policy.js';
+import type { ReadOnlyVaultFacade as ReadOnlyVaultFacadeContract } from './types.js';
+/**
+ * Minimal read-only wrapper over a `Vault`. Used as `ctx.vault` inside
+ * guard / derivation callbacks so they can fetch related records without
+ * acquiring any write capability.
+ *
+ * The `layer` tags every `get`/`list` read with the resolution layer it
+ * belongs to. A guard-seeded facade reads at `'guard'`, a
+ * derivation-seeded one at `'derivation'`, so i18nText / dictKey fields
+ * resolve under that layer's `onMissing` policy instead of the `'read'`
+ * policy — e.g. a guard read can `substitute` a missing locale (lenient
+ * default) while the same field `throw`s on an ordinary app read.
+ *
+ * `query()` is left untagged: the query/aggregate pipeline reads raw
+ * `{locale}` maps (no resolution call site), so a layer tag there would be
+ * inert. Routing `mv`/`join` resolution through the pipeline is tracked
+ * separately.
+ */
+export declare class ReadOnlyVaultFacade implements ReadOnlyVaultFacadeContract {
+    private readonly _vault;
+    private readonly _layer;
+    constructor(vault: Vault, layer?: Layer);
+    collection<T = unknown>(name: string): {
+        get(id: string): Promise<T | null>;
+        list(): Promise<T[]>;
+        query(): Query<T>;
+    };
+}

package/dist/with-audit/guards/registry.d.ts

@@ -0,0 +1,83 @@
+import type { GuardStrategy, GuardContext, GuardChange } from './types.js';
+/**
+ * Per-record metadata attached to every entry in an amendment's
+ * change-set. Carried in a parallel map alongside `_amendmentChanges`
+ * so the public {@link GuardChange} shape (`{ before, after }`) stays
+ * clean for invariant authors — the audit ledger reads this side
+ * structure to produce the `{ collection, id, vBefore, vAfter }`
+ * tuples for the amendment entry.
+ *
+ * @internal
+ */
+export interface AmendmentChangeMeta {
+    readonly id: string;
+    readonly vBefore: number;
+    readonly vAfter: number;
+}
+/**
+ * Vault-internal singleton that holds the guard graph and dispatches
+ * per-collection guard execution. Owned by `Vault`; not exported.
+ *
+ * @internal
+ */
+type AnyGuard = GuardStrategy<Record<string, unknown>>;
+type AnyChange = GuardChange<Record<string, unknown>>;
+export declare class GuardRegistry {
+    private readonly _byCollection;
+    private _amendmentChanges;
+    private _amendmentMeta;
+    /** Register a guard. Multiple guards per collection are allowed. */
+    register<T extends Record<string, unknown>>(spec: GuardStrategy<T>): void;
+    /** All guards registered against `collection` in registration order. */
+    guardsFor(collection: string): ReadonlyArray<AnyGuard>;
+    /** Per-collection guard counts, for introspection. */
+    summary(): {
+        collection: string;
+        count: number;
+    }[];
+    /**
+     * Run every guard's `check` for this collection. First throw wins —
+     * remaining guards are not invoked. Guards without a `check` skip.
+     */
+    runChecks<T>(collection: string, incoming: T, ctx: GuardContext<T>): Promise<void>;
+    /**
+     * Run every guard's `onDelete` for this collection. First throw wins —
+     * remaining guards are not invoked. Guards without an `onDelete` skip.
+     * Mirrors {@link runChecks} but for the delete path.
+     */
+    runOnDelete<T>(collection: string, existing: T, ctx: GuardContext<T>): Promise<void>;
+    /** True if any guard for `collection` declares an `amendment` block. */
+    hasAmendment(collection: string): boolean;
+    /** Open a new amendment change-collection window. */
+    beginAmendment(): void;
+    /** True iff we're currently inside an amendment transaction. */
+    isAmendmentActive(): boolean;
+    /**
+     * Record a {before, after} pair for the active amendment. `vBefore`
+     * and `vAfter` are stored in a parallel meta structure so the public
+     * {@link GuardChange} shape handed to invariant callbacks stays
+     * `{ before, after }` only — the audit ledger reads version metadata
+     * via {@link consumeMeta}.
+     */
+    collectChange<T>(collection: string, id: string, before: T | null, after: T, vBefore?: number, vAfter?: number): void;
+    /**
+     * Drain the change-set and close the amendment window. The caller
+     * (transaction commit) feeds these to each affected guard's invariant.
+     */
+    consumeChanges(): ReadonlyMap<string, ReadonlyArray<AnyChange>>;
+    /**
+     * Drain the parallel id/version metadata captured during the
+     * amendment. Returned as a flat list with `collection` denormalised
+     * so the audit ledger can emit one `{ collection, id, vBefore,
+     * vAfter }` tuple per record. Must be called AFTER
+     * {@link consumeChanges} (or independently) — calling it closes the
+     * meta window in the same way.
+     */
+    consumeMeta(): ReadonlyArray<{
+        collection: string;
+        id: string;
+        vBefore: number;
+        vAfter: number;
+    }>;
+}
+export {};