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

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';

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

@@ -0,0 +1,417 @@
+/**
+ * Accounting-period closure + opening.
+ *
+ * A closed period seals every record whose envelope `_ts` is at or
+ * before the period's `endDate`: further writes (`put` / `delete`)
+ * against such records throw {@link PeriodClosedError}. The period
+ * itself is stored as a record in the reserved `_periods` collection
+ * and written through the normal ledger-instrumented path, so every
+ * closure appends a tamper-evident entry to the vault's hash chain.
+ *
+ * ## Closure model
+ *
+ * ```
+ * vault.closePeriod({ name: 'FY2026-Q1', endDate: '2026-03-31' })
+ *   └─► PeriodRecord written to _periods/<name>
+ *         ├─ priorPeriodName / priorPeriodHash — chain to last close
+ *         ├─ closedAt / closedBy — provenance
+ *         └─ normal ledger append fires (LedgerStore.append)
+ * ```
+ *
+ * Enforcement (`assertTsWritable`) is vault-local: the Vault caches
+ * the list of closed periods on first read and consults that cache in
+ * the `Collection.put` / `.delete` path via the `periodGuard` hook.
+ *
+ * ## Opening model
+ *
+ * ```
+ * vault.openPeriod({
+ *   name: 'FY2026-Q2',
+ *   startDate: '2026-04-01',
+ *   fromPeriod: 'FY2026-Q1',
+ *   carryForward: async (priorView) => Record<string, Record<string, unknown>>,
+ * })
+ * ```
+ *
+ * `carryForward` receives a read-only `VaultInstant` anchored at the
+ * prior period's `endDate` (built via `vault.at(endDate)`) so the
+ * callback can compute closing aggregates from the sealed state. The
+ * returned `{ [collectionName]: { [id]: record } }` map is written
+ * before the new `PeriodRecord` lands — opening balances materialise
+ * as normal records with fresh timestamps that fall outside every
+ * closed period.
+ *
+ * ## Freeze
+ *
+ * ```
+ * vault.freezePeriod('FY2026-Q1')
+ *   └─► physically purges delete markers whose write-time falls inside
+ *       the closed period's window (via the #589 `_purgeDeleteMarkers`
+ *       seam), then records the fact:
+ *         ├─ PeriodFreezeRecord written to _period_freezes/<name>
+ *         └─ normal ledger append fires (LedgerStore.append)
+ * ```
+ *
+ * The chained `_periods/<name>` record is never mutated — `frozenAt` /
+ * `frozenBy` / `purgedMarkerCount` are merged onto the returned
+ * `PeriodRecord` at read time from the companion, so a tamper with the
+ * freeze can never break the inter-period hash chain. Freezing is
+ * terminal (a closed period, once frozen, stays frozen) and idempotent
+ * (a second call is a no-op that returns the same merged record without
+ * re-purging or re-appending a ledger entry). Freeze does NOT purge
+ * forget-tombstones (GDPR crypto-shred erasure evidence), `_history`
+ * versions, or live records — the delete-markers-only seam leaves all
+ * three untouched by construction.
+ *
+ * Freeze purges the LOCAL adapter only. On a synced vault, markers already
+ * pushed to sync targets survive there, and a later pull re-imports them
+ * (benign — they still read deleted, but the space isn't reclaimed). A
+ * re-imported marker keeps its original `_ts` (inside the already-frozen
+ * period's window), so — like any late-booked delete — it is reclaimed by
+ * the NEXT period's freeze, whose window covers it; freeze stays terminal
+ * and does NOT re-purge an already-frozen period (#611). Sweeping the sync
+ * targets themselves is a cross-target-purge concern deferred to the
+ * cold-archival spec. Purging re-opens the #589 resurrection window for a
+ * peer offline since before the cutoff, which is why the closed period is
+ * the operator-asserted safe-point that gates the call.
+ *
+ * A period whose purge window has not fully elapsed cannot be frozen —
+ * `freezePeriod` throws rather than purge markers for deletes that may not
+ * have converged yet (#610).
+ *
+ * ## Archive
+ *
+ * ```
+ * vault.archivePeriod('FY2026-Q1')
+ *   └─► relocates the closed period's in-window records (those with
+ *       `_ts < periodExclusiveUpperBound(endDate)`) from the hot store to
+ *       the configured cold tier (routeStore's `cold` route), then records:
+ *         ├─ PeriodArchiveRecord written to _period_archives/<name>
+ *         └─ a ledger entry attributed to _period_archives
+ * ```
+ *
+ * Archival is NON-DESTRUCTIVE: routeStore reads fall through to the cold
+ * tier on a hot miss, so an archived record still reads normally. It is
+ * therefore gated only on `closed` (not `frozen`) — it does not re-open the
+ * #589 resurrection window and needs no convergence safe-point. Freeze
+ * (purge markers) and archive (relocate records) are independent and compose
+ * in either order. Like freeze, archival keeps the chained `_periods/<name>`
+ * record byte-immutable (state lives in the companion) and is idempotent.
+ *
+ * Bounds by write-time `_ts`, NOT business date: the store tier sees only
+ * encrypted envelopes. A record with an in-period business date but a later
+ * `_ts` (late-booked) archives at the NEXT period's archive — the same rule
+ * freeze uses for late-booked delete markers. Requires a `routeStore` with a
+ * cold route (`age: { cold }`); throws otherwise.
+ *
+ * Read cost: with `withLazy()` (per-id reads) archived records are truly
+ * cold — fetched from cold only on access. In the default hydrated mode,
+ * `loadAll` merges the cold store, so archived records still load into RAM
+ * on vault open (hot-tier STORAGE is reclaimed; RAM is not). Summaries
+ * (`_`-prefixed) always stay hot.
+ *
+ * ## Target-purge
+ *
+ * ```
+ * vault.purgePeriodTargets('FY2026-Q1')
+ *   └─► sweeps delete markers (`_ts < periodExclusiveUpperBound(endDate)`) off
+ *       the vault's PUSH-ONLY sync targets (backup/archive roles), then records:
+ *         ├─ PeriodTargetPurgeRecord written to _period_target_purges/<name>
+ *         └─ a ledger entry attributed to _period_target_purges
+ * ```
+ *
+ * Extends freeze's local marker purge to the vault's own remote sinks.
+ * `sync-peer` (bidirectional) targets are SKIPPED: purging a marker there
+ * re-opens the #589 resurrection window for a client offline before the
+ * cutoff, an assertion no single vault can verify. Backup/archive targets are
+ * push-only — never pulled from into convergence — so sweeping their markers
+ * is safe. Requires the period be frozen first (closed → frozen →
+ * target-purged) so the local safe-point is already established. Idempotent
+ * once run; a vault with no push-only targets writes no companion and is
+ * re-runnable (so a target added later is still swept). Single-vault only —
+ * fleet-wide purge across sovereign vaults is klum's concern over
+ * `@noy-db/hub/cargo`.
+ *
+ * ## Not covered
+ *
+ * - Partial re-opening of a closed period. If an auditor needs to
+ *   make a correction inside a sealed period, the sanctioned path is
+ *   a compensating entry in the NEW period, not an unlock of the
+ *   old one.
+ * - Automatic period rollover. `closePeriod` / `openPeriod` are
+ *   deliberately explicit operator calls so the caller decides when
+ *   the boundary lands.
+ *
+ * @module
+ */
+import type { NoydbStore, EncryptedEnvelope } from '../../kernel/types.js';
+import type { LedgerStore } from '../../with-commit/history/ledger/index.js';
+/** The reserved collection name holding closed-period metadata. */
+export declare const PERIODS_COLLECTION = "_periods";
+/** Sibling of {@link PERIODS_COLLECTION} holding freeze companions (#604). */
+export declare const PERIOD_FREEZES_COLLECTION = "_period_freezes";
+/** Sibling of {@link PERIODS_COLLECTION} holding archive companions (#613). */
+export declare const PERIOD_ARCHIVES_COLLECTION = "_period_archives";
+/** Sibling of {@link PERIODS_COLLECTION} holding target-purge companions (#615). */
+export declare const PERIOD_TARGET_PURGES_COLLECTION = "_period_target_purges";
+/**
+ * Companion record recording that a closed period was frozen (its delete
+ * markers physically purged). Stored in {@link PERIOD_FREEZES_COLLECTION},
+ * keyed by period name — kept OFF the hash-chained `_periods/<name>` record so
+ * freeze never alters the inter-period chain.
+ */
+export interface PeriodFreezeRecord {
+    readonly period: string;
+    readonly frozenAt: string;
+    readonly frozenBy: string;
+    readonly purgedMarkerCount: number;
+}
+/**
+ * Companion record noting that a closed period was cold-archived (its
+ * in-window records physically relocated hot → cold). Stored in
+ * {@link PERIOD_ARCHIVES_COLLECTION}, keyed by period name — kept OFF the
+ * hash-chained `_periods/<name>` record so archive never alters the chain.
+ */
+export interface PeriodArchiveRecord {
+    readonly period: string;
+    readonly archivedAt: string;
+    readonly archivedBy: string;
+    readonly archivedRecordCount: number;
+}
+/** Per-target count of delete markers purged off one push-only sync target (#615). */
+export interface TargetPurgeCount {
+    readonly label?: string;
+    readonly role: 'backup' | 'archive';
+    readonly purgedCount: number;
+}
+/**
+ * Companion record noting that a closed+frozen period's delete markers were
+ * swept off the vault's push-only sync targets (#615). Stored in
+ * {@link PERIOD_TARGET_PURGES_COLLECTION}, keyed by period name — kept OFF the
+ * hash-chained `_periods/<name>` record so target-purge never alters the chain.
+ */
+export interface PeriodTargetPurgeRecord {
+    readonly period: string;
+    readonly purgedAt: string;
+    readonly purgedBy: string;
+    readonly targets: readonly TargetPurgeCount[];
+}
+/**
+ * Exclusive upper bound for a period's delete-marker purge window (#604).
+ * Markers carry no business date (empty body), only write-time `_ts`, so freeze
+ * purges markers with `_ts < bound`, `bound` being the instant just after the
+ * period's inclusive `endDate`: a date-only `endDate` seals through end-of-day
+ * → next midnight; a full-timestamp `endDate` seals through that instant → +1ms.
+ */
+export declare function periodExclusiveUpperBound(endDate: string): string;
+/**
+ * Stored record for one closed or opened accounting period. One entry
+ * per period, keyed by `name` in the reserved `_periods` collection.
+ *
+ * The hash chain between periods is computed at read time by
+ * `loadPeriods()` — each record carries the name + hash of its
+ * predecessor so a tamper with any period's record breaks the chain
+ * into the next one, the same way the ledger's `prevHash` works.
+ */
+export interface PeriodRecord {
+    /** Human-readable name (e.g., `'FY2026-Q1'`). Unique per vault. */
+    readonly name: string;
+    /**
+     * Role discriminator. A period is `'closed'` from the moment its
+     * `closedAt` is recorded; `'opened'` marks a period whose opening
+     * entries have been carried forward via {@link openPeriod}. Many
+     * workflows will produce one opened period per closed period (the
+     * opened one is the SUCCESSOR — its `startDate` equals the prior
+     * `endDate + 1 day`).
+     */
+    readonly kind: 'closed' | 'opened';
+    /** ISO date — inclusive upper bound for records belonging to this period. */
+    readonly endDate: string;
+    /** ISO date — lower bound (present on opened periods only). */
+    readonly startDate?: string;
+    /**
+     * Record field carrying the business date (e.g. `'date'` on an
+     * invoice, `'paidAt'` on a payment). The guard compares
+     * `record[dateField]` against `endDate` — NOT the envelope `_ts`.
+     * Accounting entries booked late (business date `2026-01-15`,
+     * write-time `2026-04-22`) still get sealed when Q1 closes at
+     * `2026-03-31` because the comparison uses the business date.
+     *
+     * Optional for backwards compat. When absent, the guard falls back
+     * to envelope `_ts` — that's a write-time seal, appropriate for
+     * content that doesn't carry a logical business date (e.g. system
+     * settings) but almost never right for accounting ledgers.
+     */
+    readonly dateField?: string;
+    /** ISO timestamp recorded at `closePeriod()` / `openPeriod()` call time. */
+    readonly closedAt: string;
+    /** userId of the keyring that invoked the close/open. */
+    readonly closedBy: string;
+    /** Name of the prior period this one chains to, if any. */
+    readonly priorPeriodName?: string;
+    /** sha256(canonicalJson(priorPeriod)) — empty for the first period. */
+    readonly priorPeriodHash: string;
+    /**
+     * Opened periods only — the names of the collections whose
+     * carry-forward aggregates were written by {@link openPeriod}.
+     * Recorded for auditability so a future `verifyPeriodChain()` can
+     * cross-check the opening balances against the closing snapshot.
+     */
+    readonly openingCollections?: readonly string[];
+    /** #604 return-only — merged from the `_period_freezes/<name>` companion on
+     *  read; NEVER written into the stored `_periods/<name>` record (would break
+     *  the hash chain). Absent = not yet frozen. */
+    readonly frozenAt?: string;
+    readonly frozenBy?: string;
+    readonly purgedMarkerCount?: number;
+    /** #613 return-only — merged from the `_period_archives/<name>` companion on
+     *  read; NEVER written into the stored `_periods/<name>` record. Absent = not
+     *  yet archived. */
+    readonly archivedAt?: string;
+    readonly archivedBy?: string;
+    readonly archivedRecordCount?: number;
+    /** #615 return-only — merged from the `_period_target_purges/<name>` companion
+     *  on read; NEVER written into the stored `_periods/<name>` record. Absent =
+     *  target-purge not yet run (or the vault has no push-only targets). */
+    readonly targetsPurgedAt?: string;
+    readonly targetsPurgedBy?: string;
+    readonly targetsPurged?: readonly TargetPurgeCount[];
+}
+/** Options for `vault.closePeriod()`. */
+export interface ClosePeriodOptions {
+    /** Human-readable name. Must not collide with an existing period. */
+    readonly name: string;
+    /**
+     * Inclusive upper cutoff. A record is sealed when its
+     * `record[dateField]` (or, if absent, the envelope `_ts`) is at or
+     * before this ISO timestamp.
+     */
+    readonly endDate: string;
+    /**
+     * Record field carrying the business date used for period
+     * membership. Recommended for accounting workflows — e.g. an
+     * invoice booked late (write-time after close) is still sealed
+     * when its `invoice.date` falls inside the closed period.
+     *
+     * Omit to use envelope `_ts` (write-time seal). This fallback
+     * rarely matches real-world accounting semantics; prefer passing
+     * an explicit `dateField`.
+     */
+    readonly dateField?: string;
+}
+/** Options for `vault.openPeriod()`. */
+export interface OpenPeriodOptions<TCollections = Record<string, Record<string, unknown>>> {
+    /** Human-readable name for the new period. Must be unique. */
+    readonly name: string;
+    /** ISO lower bound of the new period (usually prior `endDate + 1 day`). */
+    readonly startDate: string;
+    /**
+     * Name of the prior CLOSED period this one chains from. The prior
+     * period's record is verified to exist and to be `kind: 'closed'`;
+     * its `endDate` is made available to the `carryForward` callback.
+     */
+    readonly fromPeriod: string;
+    /**
+     * Receives a read-only facade over the vault's CURRENT state,
+     * plus the prior period's `endDate`. Accounting semantics: after
+     * a period closes, records with `record[dateField] <= endDate`
+     * are frozen — current state equals closing state, so a caller
+     * can compute closing balances by querying the live collection
+     * with a `where('date', '<=', priorEndDate)` filter.
+     *
+     * Returns opening-balance records keyed by collection name.
+     * Example:
+     *
+     * ```ts
+     * carryForward: async (ctx) => {
+     *   const closing = await ctx.collection<Journal>('journal')
+     *     .query().where('date', '<=', ctx.priorEndDate).toArray()
+     *   const opening: Record<string, Journal> = {}
+     *   for (const entry of closing) {
+     *     opening[`OB-${entry.id}`] = { ...entry, date: '2026-04-01' }
+     *   }
+     *   return { journal: opening }
+     * }
+     * ```
+     */
+    readonly carryForward: (ctx: CarryForwardContext) => Promise<TCollections> | TCollections;
+}
+/**
+ * Context passed to `OpenPeriodOptions.carryForward`. Exposes a
+ * read-only subset of the live vault (`collection(name).get/list`)
+ * plus the prior period's `endDate` so business-date filters can
+ * be built by the caller.
+ *
+ * Writes go via the return value, not via the facade — the
+ * `collection()` here is deliberately restricted to reads.
+ */
+export interface CarryForwardContext {
+    /** The prior period's `endDate` — the boundary of the closing snapshot. */
+    readonly priorEndDate: string;
+    /** Read-only collection facade over current vault state. */
+    collection<T = unknown>(name: string): ReadOnlyCollection<T>;
+}
+/** Minimum read surface exposed to `carryForward`. */
+export interface ReadOnlyCollection<T> {
+    get(id: string): Promise<T | null>;
+    list(): Promise<T[]>;
+}
+/**
+ * Load every period record currently stored on the adapter.
+ * Decrypting is the caller's responsibility (we return plain records
+ * so the vault can use its own `_periods` DEK).
+ *
+ * @internal — called by Vault methods that need the closed-period
+ * cache. Not part of the public API surface.
+ */
+export declare function loadPeriods(adapter: NoydbStore, vault: string, decrypt: (envelope: EncryptedEnvelope) => Promise<PeriodRecord>): Promise<PeriodRecord[]>;
+/**
+ * Given the current ordered period list, pick the last entry that
+ * belongs to the hash chain — used as the `priorPeriodHash` anchor
+ * for the next closure/opening.
+ *
+ * @internal
+ */
+export declare function chainAnchor(records: readonly PeriodRecord[]): Promise<{
+    priorPeriodName?: string;
+    priorPeriodHash: string;
+}>;
+/**
+ * Throw `PeriodClosedError` if the record being touched falls within
+ * any closed period.
+ *
+ * Three signals, evaluated per period:
+ *
+ *  1. If the period declares a `dateField`, the guard reads
+ *     `record[dateField]` on BOTH the existing (prior) record AND the
+ *     incoming (new) record. Either comparing `<= endDate` triggers
+ *     the error — callers cannot slide a record into a closed period
+ *     by editing its date field.
+ *  2. If the period has no `dateField`, the guard falls back to the
+ *     envelope `_ts` of the existing record. Fresh inserts (no
+ *     existing envelope) pass.
+ *  3. For a delete, only the existing side is checked.
+ *
+ * @internal
+ */
+export declare function assertTsWritable(existing: {
+    ts: string | null;
+    record: Record<string, unknown> | null;
+} | null, incomingRecord: Record<string, unknown> | null, closedPeriods: readonly PeriodRecord[]): void;
+/**
+ * Sanity-check a proposed period name + endDate against existing
+ * records. Shared by closePeriod / openPeriod so the two pathways
+ * produce identical diagnostics.
+ *
+ * @internal
+ */
+export declare function validatePeriodName(name: string, existing: readonly PeriodRecord[]): void;
+/**
+ * Wire a reserved-collection ledger append for a period record. The
+ * period itself is stored via the adapter as an encrypted envelope;
+ * the ledger entry is a normal `put` with the period's payloadHash,
+ * so period closures inherit the chain's tamper-evidence.
+ *
+ * @internal
+ */
+export declare function appendPeriodLedgerEntry(ledger: LedgerStore | null, actor: string, envelope: EncryptedEnvelope, name: string, collection?: string): Promise<void>;