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

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

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

@@ -0,0 +1,82 @@
+/**
+ * `transitionGuard` — declarative state-machine sugar over the guard
+ * service.
+ *
+ * Any record with a lifecycle field (invoice `status`, order state,
+ * ticket workflow, subscription phase) needs transition validation: a
+ * write may only move the field along a declared arc. That is expressible
+ * with a hand-rolled `withGuard({ check })`, but every consumer
+ * re-implements the same graph lookup + error. `transitionGuard`
+ * generates exactly that guard from a state graph, reusing the guard
+ * machinery wholesale — `check` rejection, the ledgered `amendment`
+ * override, and composition with `periods`/`history`.
+ *
+ * It generalizes {@link immutableGuard}: WORM is the special case "every
+ * state has no outgoing arcs", i.e. `transitions` mapping each state to `[]`.
+ *
+ * ```ts
+ * createNoydb({ guardStrategies: [
+ *   transitionGuard<Sale>({
+ *     collection: 'sales', field: 'status',
+ *     transitions: {                          // absence of an arc = forbidden
+ *       draft: ['to_verify', 'cancelled'],
+ *       to_verify: ['proforma', 'draft', 'cancelled'],
+ *       proforma: ['invoiced', 'cancelled'],
+ *       invoiced: ['paid'], paid: [], cancelled: [],
+ *     },
+ *     initial: ['draft', 'to_verify'],        // allowed status on insert
+ *   }),
+ * ] })
+ * ```
+ *
+ * Semantics:
+ * - **Insert** (`ctx.existing === null`): `incoming[field]` must be in
+ *   `initial`. When `initial` is omitted, any value is allowed on insert.
+ * - **Update**: the arc `(existing[field] → incoming[field])` must be
+ *   listed in `transitions[from]`, else `IllegalTransitionError`. A
+ *   same-value write (`from === to`) is allowed when `allowIdempotent`
+ *   (default `true`) — so writes that touch other fields without moving
+ *   state pass.
+ * - **Override**: inside an `amendment` transaction by an authorized role
+ *   the check is skipped and the change is ledgered (mirrors every guard).
+ *
+ * The status graph is caller-supplied data — no UI, no domain logic.
+ */
+import type { GuardStrategyHandle, GuardContext, GuardChange } from './types.js';
+export interface TransitionGuardConfig<T extends Record<string, unknown>> {
+    /** The collection whose state field is governed. */
+    collection: string;
+    /** The state field on the record (e.g. `'status'`). */
+    field: keyof T & string;
+    /**
+     * The transition graph: each state maps to the states it may move to.
+     * A state absent from the map (or mapped to `[]`) is terminal — no
+     * outgoing arc, so any non-idempotent write from it is rejected.
+     */
+    transitions: Readonly<Record<string, readonly string[]>>;
+    /**
+     * States allowed as the initial value on insert (`existing === null`).
+     * Omit to allow any value on insert.
+     */
+    initial?: readonly string[];
+    /**
+     * Allow a same-value write (`from === to`) on update. Default `true` —
+     * lets a put that changes other fields, but not the state, through.
+     */
+    allowIdempotent?: 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. When omitted the amendment is unconditionally allowed (the
+     * amendment itself is the sanctioned, ledgered override) — the
+     * backward-compatible default. Mirrors {@link immutableGuard}.
+     */
+    amendmentInvariant?: (changes: ReadonlyArray<GuardChange<T>>, ctx: GuardContext<T>) => Promise<void> | void;
+}
+/**
+ * Build a state-machine transition guard. Pass the returned handle to
+ * `createNoydb({ guardStrategies: [...] })`.
+ */
+export declare function transitionGuard<T extends Record<string, unknown>>(config: TransitionGuardConfig<T>): GuardStrategyHandle<T>;

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

@@ -0,0 +1,134 @@
+import type { Role } from '../../kernel/types.js';
+import type { Query } from '../../kernel/query/builder.js';
+/**
+ * Minimum read surface exposed to guard `check` functions. Intentionally
+ * narrow — guards can read other collections but never write.
+ *
+ * `query()` returns the same chainable builder used elsewhere. `Query<T>`
+ * has no write terminals (no `.update()` / `.delete()`) so exposing it
+ * here preserves the read-only contract while letting guards aggregate
+ * with `.where().aggregate()` / `.groupBy()` / `.join()` instead of
+ * decrypting every sibling row via `.list()`.
+ */
+export interface ReadOnlyVaultFacade {
+    collection<T = unknown>(name: string): {
+        get(id: string): Promise<T | null>;
+        list(): Promise<T[]>;
+        query(): Query<T>;
+    };
+}
+/**
+ * Runtime context passed to `check` and `invariant` callbacks.
+ * `existing` is the currently-persisted record (null for inserts).
+ */
+export interface GuardContext<T> {
+    existing: T | null;
+    vault: ReadOnlyVaultFacade;
+    userId: string;
+    role: Role;
+}
+/**
+ * One {before, after} pair handed to an `invariant` function. `before`
+ * is null for inserts; `after` reflects the proposed post-commit record.
+ */
+export interface GuardChange<T> {
+    before: T | null;
+    after: T;
+}
+/** @internal — output of {@link withGuard}. */
+export interface GuardStrategyHandle<T extends Record<string, unknown>> {
+    readonly __noydb_strategy: 'guard';
+    readonly spec: GuardStrategy<T>;
+}
+/**
+ * Existential erasure of `GuardStrategyHandle<T>` — used as the
+ * element type of `ReadonlyArray<>` fields where the per-handle T
+ * differs (e.g. `guardStrategies: [invoiceGuard, disbursementGuard]`).
+ *
+ * Background: `GuardStrategyHandle<T>` is INVARIANT in T because T
+ * appears in callback positions on the spec (`check(incoming: T, ctx)`,
+ * `invariant(changes: ReadonlyArray<GuardChange<T>>, ctx)`). So
+ * `Handle<Invoice>` is not assignable to `Handle<Record<string, unknown>>`.
+ * A bounded existential ("there exists some T satisfying the constraint
+ * such that this is a Handle<T>") is the right shape; TypeScript has
+ * no first-class existentials, so we fake it with a structurally narrow
+ * interface that ERASES T from both the discriminant and the spec.
+ *
+ * Consumers continue to construct typed handles via `withGuard<T>(...)`
+ * which returns `GuardStrategyHandle<T>`. Both `Handle<Invoice>` and
+ * `Handle<Disbursement>` structurally assign to `GuardStrategyHandleAny`,
+ * so an array of them is `GuardStrategyHandleAny[]`.
+ *
+ * Internal code that needs T re-narrows via the runtime discriminant
+ * (`__noydb_strategy === 'guard'`) plus per-handle type information
+ * carried by the registry.
+ *
+ * NOT exported from the public barrel — keeping this internal
+ * discourages consumers from constructing it directly. Used only as
+ * the array-element type on `Vault` / `NoydbOptions.guardStrategies`.
+ *
+ * @internal
+ */
+export interface GuardStrategyHandleAny {
+    readonly __noydb_strategy: 'guard';
+    readonly spec: GuardStrategy<any>;
+}
+/** Public registration shape. See `withGuard()`. */
+export interface GuardStrategy<T extends Record<string, unknown>> {
+    collection: string;
+    /**
+     * Fires on `Collection.put` (insert + update). The `incoming` argument
+     * is the record being written. Throw to cancel the put.
+     *
+     * Does NOT fire on `Collection.delete` — use {@link onDelete} for
+     * delete-time validation. Skipped during an amendment transaction
+     * (`db.transaction({ amendment: true })`) — admin/owner override.
+     */
+    check?: (incoming: T, ctx: GuardContext<T>) => Promise<void> | void;
+    /**
+     * Fires on user-initiated `Collection.delete` before the adapter
+     * delete and before the ledger append. The `existing` argument is
+     * the currently-persisted record. Throw to cancel the delete — no
+     * partial state, no tombstone ledger entry.
+     *
+     * Skipped during an amendment transaction (admin/owner override) —
+     * amendments are the unlock primitive. To make a delete TRULY
+     * unconditional (e.g. legal-document immutability rules), pair
+     * `onDelete` with an `amendment.invariant` that re-throws on any
+     * `before !== null && after === null` change:
+     *
+     * ```ts
+     * withGuard<Receipt>({
+     *   collection: 'receipts',
+     *   onDelete: () => { throw new RecordLockedError(...) },
+     *   amendment: {
+     *     roles: ['admin', 'owner'],
+     *     invariant: (changes) => {
+     *       for (const c of changes) {
+     *         if (c.before !== null && c.after === null) {
+     *           throw new RecordLockedError(...) // wrapped as InvariantError
+     *         }
+     *       }
+     *     },
+     *   },
+     * })
+     * ```
+     *
+     * Also skipped on system-internal deletes (derivation tombstones,
+     * MV refresh from Dim 14 v2) — those use `_internalDelete`
+     * which bypasses every user-facing delete hook. Housekeeping ops are
+     * NOT user-initiated and should not trip user invariants.
+     *
+     * Delete of an absent record is a no-op and does not consult any
+     * guard, matching the idempotent-delete contract.
+     */
+    onDelete?: (existing: T, ctx: GuardContext<T>) => Promise<void> | void;
+    frozenFields?: {
+        when: (existing: T) => boolean;
+        fields: ReadonlyArray<keyof T>;
+    };
+    amendment?: {
+        roles: ReadonlyArray<'admin' | 'owner'>;
+        invariant: (changes: ReadonlyArray<GuardChange<T>>, ctx: GuardContext<T>) => Promise<void> | void;
+    };
+}

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

@@ -0,0 +1,15 @@
+import type { GuardStrategy, GuardStrategyHandle } from './types.js';
+/**
+ * Register a guard for a collection. Guards run on every `put()` /
+ * `delete()` for the named collection (after permissions, before
+ * encryption) and may:
+ *
+ *   - `check` — block writes by throwing (typically `RecordLockedError`)
+ *   - `frozenFields` — freeze specific fields once a condition is true
+ *   - `amendment` — declare an authorized-override path with invariant
+ *
+ * Pass the returned handle to `createNoydb({ strategies: [...] })`.
+ *
+ * @see docs/superpowers/specs/2026-05-18-guards-design.md
+ */
+export declare function withGuard<T extends Record<string, unknown>>(strategy: GuardStrategy<T>): GuardStrategyHandle<T>;

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

@@ -0,0 +1,11 @@
+/**
+ * Active periods strategy factory. Only reachable through the
+ * `@noy-db/hub/periods` subpath.
+ */
+import type { PeriodsStrategy } from './strategy.js';
+/**
+ * Build the default periods strategy. Pass into
+ * `createNoydb({ periodsStrategy: withPeriods() })` to enable
+ * `vault.closePeriod()` / `vault.openPeriod()` / write-guards.
+ */
+export declare function withPeriods(): PeriodsStrategy;

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

@@ -0,0 +1,18 @@
+/**
+ * Accounting-period subpath barrel.
+ *
+ * Public entry points live on `Vault`:
+ *
+ *   - `vault.closePeriod({ name, endDate })`
+ *   - `vault.openPeriod({ name, startDate, fromPeriod, carryForward })`
+ *   - `vault.listPeriods()`
+ *   - `vault.getPeriod(name)`
+ *
+ * These types support user-defined wrappers and tests; the internal
+ * helpers (`loadPeriods`, `assertTsWritable`, …) are exported so the
+ * Vault can call them without TypeScript barrel gymnastics.
+ */
+export { withPeriods } from './active.js';
+export type { PeriodsStrategy } from './strategy.js';
+export { PERIODS_COLLECTION, PERIOD_FREEZES_COLLECTION, PERIOD_ARCHIVES_COLLECTION, PERIOD_TARGET_PURGES_COLLECTION, periodExclusiveUpperBound, loadPeriods, chainAnchor, assertTsWritable, validatePeriodName, appendPeriodLedgerEntry, } from './periods.js';
+export type { PeriodRecord, PeriodFreezeRecord, PeriodArchiveRecord, PeriodTargetPurgeRecord, TargetPurgeCount, ClosePeriodOptions, OpenPeriodOptions, CarryForwardContext, ReadOnlyCollection, } from './periods.js';