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

package/dist/with-fork/snapshots/noydb-facade.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Noydb-side snapshot facade.
+ *
+ * Holds the on-demand checkpoint (`snapshot`), listing (`listSnapshots`),
+ * restore (`restoreSnapshot`), the automatic-snapshot cadence wiring
+ * (`initCadence`), the dirty-vault set, and the cadence scheduler;
+ * `Noydb.close()` calls {@link stop}. Every `Noydb` dependency arrives via
+ * {@link NoydbSnapshotsDeps}.
+ *
+ * Internal service — reached through `noydb.snapshot(...)` etc.
+ */
+import { NO_SNAPSHOTS, type SnapshotStrategy, type SnapshotMeta } from './strategy.js';
+import type { Vault } from '../../kernel/vault.js';
+import type { WriteHook, Unsubscribe } from '../../port/with/write-hooks.js';
+/** Everything the moving snapshot methods touched on the Noydb instance's `this.*`. */
+export interface NoydbSnapshotsDeps {
+    /** Resolved snapshot strategy (NO_SNAPSHOTS when not configured). */
+    readonly strategy: SnapshotStrategy;
+    /** Acting user id, used as the snapshot `by`. */
+    readonly user: string;
+    /** Whether the owning instance has been closed. */
+    isClosed(): boolean;
+    /** Resolve an open vault from the instance's vault cache. */
+    getVault(name: string): Vault | undefined;
+    /** Subscribe to post-write events (cadence dirty-marking). */
+    onAfterWrite(handler: WriteHook): Unsubscribe;
+}
+export declare class NoydbSnapshots {
+    private readonly deps;
+    private scheduler;
+    private readonly dirtyVaults;
+    constructor(deps: NoydbSnapshotsDeps);
+    /**
+     * Take an on-demand checkpoint of the given vault.
+     * Requires `snapshotStrategy: withSnapshots({ store })` in `createNoydb`.
+     * @throws ValidationError when the vault is not open
+     */
+    snapshot(vault: string, opts?: {
+        label?: string;
+        note?: string;
+    }): Promise<SnapshotMeta>;
+    /**
+     * Wire the automatic-snapshot cadence when a non-manual `snapshotPolicy` is
+     * configured. Subscribes to `onAfterWrite` to mark the written vault dirty and
+     * nudge the scheduler; the scheduler fires `autoSnapshot()` per dirty vault.
+     * No-op for `mode:'manual'` or no policy.
+     */
+    private initCadence;
+    /**
+     * List all snapshots for the given vault, newest first.
+     * Reads only the sidecar index — does not download snapshot bytes.
+     */
+    listSnapshots(vault: string): Promise<SnapshotMeta[]>;
+    /**
+     * Restore the vault to a previously snapshotted state.
+     * Runs `verifyBackupIntegrity()` automatically on restore.
+     * @throws SnapshotNotFoundError when `version` doesn't exist in the store
+     * @throws ValidationError when the vault is not open
+     */
+    restoreSnapshot(vault: string, version: string): Promise<void>;
+    /** Stop the cadence scheduler (called from `Noydb.close()`). */
+    stop(): void;
+}
+export { NO_SNAPSHOTS };

package/dist/with-fork/snapshots/policy.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Cadence policy for automatic snapshots. Borrows the vocabulary of the sync
+ * `SyncPolicy` (debounce / interval / minInterval / onUnload) but is a separate,
+ * snapshot-specific shape — automatic snapshots write the single rolling
+ * `<vault>__auto` key, never the immutable on-demand pool.
+ *
+ * Default mode is `'manual'`: no timers, snapshots stay on-demand.
+ */
+export type SnapshotMode = 'manual' | 'debounce' | 'interval';
+export interface SnapshotPolicy {
+    /** Trigger mode. Default `'manual'` — no automatic snapshots. */
+    readonly mode?: SnapshotMode;
+    /** Idle delay (ms) after a write before an auto-snapshot fires. `mode:'debounce'`. Default 30_000. */
+    readonly debounceMs?: number;
+    /** Fixed interval (ms). `mode:'interval'`. Default 300_000. */
+    readonly intervalMs?: number;
+    /** Hard floor (ms) between auto-snapshots regardless of mode. Default 0. */
+    readonly minIntervalMs?: number;
+    /** Flush a pending auto-snapshot on tab-hide / process exit. Default true for non-manual modes. */
+    readonly onUnload?: boolean;
+    /** Label applied to each auto-snapshot. Default `'auto'`. */
+    readonly label?: string;
+}

package/dist/with-fork/snapshots/scheduler.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Owns timers + unload hooks for the automatic snapshot cadence. Distinct from
+ * the sync `SyncScheduler` (whose push/pull/dirty-count shape doesn't map to
+ * snapshots) — it borrows only the policy vocabulary. Delegates the actual
+ * snapshot work to `callbacks.fire()`.
+ */
+import type { SnapshotPolicy } from './policy.js';
+export interface SnapshotSchedulerCallbacks {
+    /** Fire one auto-snapshot cycle (per dirty vault). Swallows its own per-vault errors. */
+    fire(): Promise<void>;
+    /** Number of vaults with pending writes since the last fire. */
+    pendingCount(): number;
+}
+export declare class SnapshotScheduler {
+    private readonly policy;
+    private readonly callbacks;
+    private debounceTimer;
+    private intervalTimer;
+    private lastFireTime;
+    private firing;
+    private started;
+    private readonly boundVisibility;
+    private readonly boundUnload;
+    constructor(policy: SnapshotPolicy, callbacks: SnapshotSchedulerCallbacks);
+    start(): void;
+    stop(): void;
+    notifyChange(): void;
+    private resetDebounce;
+    private execFire;
+    private handleVisibility;
+    private handleUnload;
+    private flush;
+    private shouldRegisterUnload;
+}

package/dist/with-fork/snapshots/strategy.d.ts

@@ -0,0 +1,48 @@
+import type { SnapshotPolicy } from './policy.js';
+export interface SnapshotMeta {
+    readonly version: string;
+    readonly label?: string;
+    readonly note?: string;
+    readonly exportedAt: string;
+    readonly exportedBy: string;
+    readonly size: number;
+    /**
+     * `'verified'` — bundle was produced by `writePod(vault, {})`, which embeds
+     * ledgerHead metadata; `vault.load()` runs `verifyBackupIntegrity()` on restore.
+     * `'legacy-unverifiable'` — reserved for v2 import paths that read pre-existing bundles
+     * lacking a ledgerHead; not produced by the current engine.
+     */
+    readonly integrity: 'verified' | 'legacy-unverifiable';
+    /** `true` for the rolling auto-snapshot; absent on on-demand checkpoints. */
+    readonly auto?: true;
+}
+export interface RetentionPolicy {
+    readonly keepLast?: number;
+    readonly maxAgeDays?: number;
+    readonly prune?: boolean;
+}
+/** @internal */
+export interface SnapshotIndex {
+    snapshots: SnapshotMeta[];
+    nextCounter: number;
+    /** Single rolling auto-snapshot slot, separate from the immutable `snapshots` pool. */
+    auto?: SnapshotMeta;
+}
+/** @internal */
+export interface SnapshotStrategy {
+    snapshot(vault: unknown, by: string, opts?: {
+        label?: string;
+        note?: string;
+    }): Promise<SnapshotMeta>;
+    listSnapshots(vaultId: string): Promise<SnapshotMeta[]>;
+    restoreSnapshot(vault: unknown, version: string): Promise<void>;
+    /** Rolling auto-snapshot to the fixed `<vault>__auto` key. */
+    autoSnapshot(vault: unknown, by: string, opts?: {
+        label?: string;
+        note?: string;
+    }): Promise<SnapshotMeta>;
+    /** Configured cadence policy. Undefined or `mode:'manual'` ⇒ no scheduler is wired. */
+    readonly policy?: SnapshotPolicy;
+}
+/** No-op stub. @internal */
+export declare const NO_SNAPSHOTS: SnapshotStrategy;

package/dist/with-formula/computed/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Computed scalar fields — schema-owned derived values evaluated on
+ * write and materialized onto the record.
+ *
+ * A `computed` map declares pure, synchronous functions keyed by field
+ * path. {@link evalComputedFields} runs them in declaration order — each
+ * function sees the record with all prior computed fields already
+ * injected, so a later field can read an earlier one (`total` reads
+ * `netAmount`). The result is stored like any field: queryable,
+ * indexable, and `aggregate(sum())`-able (exactly, when the field is also
+ * a `money()` field).
+ *
+ * Computed evaluation is the FIRST stage of the write pipeline (before
+ * schema validation), so the user need not supply computed fields and the
+ * schema validates the computed result. Cross-record / async derivation
+ * is out of scope here — see the validation service.
+ */
+import { NoydbError } from '../../kernel/errors.js';
+export type ComputedFn<T = Record<string, unknown>> = (record: T) => unknown;
+/**
+ * #638 Task 7 — the extended per-field entry: `deps` (source field names, feeds
+ * `ViaGraph` for taint propagation) and `mode` (`'materialized' | 'virtual'`,
+ * default `'materialized'`) alongside `fn`. Lets `computed: { field: {...} }`
+ * declare the same `{deps, mode}` shape `via(computed(fn, {...}))` composes —
+ * absorbs the old `computedDeps` sibling option (#638 Task 2, retired here).
+ */
+export interface ComputedFieldEntry<T = Record<string, unknown>> {
+    readonly fn: ComputedFn<T>;
+    readonly deps?: readonly string[];
+    readonly mode?: 'materialized' | 'virtual';
+}
+/** The plain `Record<string, ComputedFn>` sugar keeps working unchanged (materialized,
+ *  no deps); a field may alternatively carry the extended `ComputedFieldEntry` shape. */
+export type ComputedFields<T = Record<string, unknown>> = Record<string, ComputedFn<T> | ComputedFieldEntry<T>>;
+/** Raised when a computed function throws during a write. */
+export declare class ComputedFieldError extends NoydbError {
+    readonly field: string;
+    readonly id: string;
+    readonly cause: unknown;
+    constructor(field: string, id: string, cause: unknown);
+}
+/**
+ * Evaluate every computed field in declaration order, injecting each
+ * result into a shallow clone. A computed field overwrites any
+ * user-supplied value of the same name — the field is schema-owned.
+ * Returns the new record; the input is not mutated.
+ */
+export declare function evalComputedFields<T extends Record<string, unknown>>(record: T, computed: ComputedFields, id: string): T;

package/dist/with-formula/computed/lazy.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Lazy loader for the computed-fields engine (#553).
+ *
+ * The `computed` declaration on `collection({ … })` is the opt-in unit;
+ * the engine's only kernel consultation is the (async) write pipeline,
+ * so it loads on the first computed-declared put and stays out of the
+ * floor bundle otherwise. Cached after first load — mirrors the
+ * deferred-load pattern used for guards/derivations.
+ */
+import type * as ComputedModule from './index.js';
+type EvalComputedFieldsFn = typeof ComputedModule.evalComputedFields;
+export declare function loadEvalComputedFields(): Promise<EvalComputedFieldsFn>;
+export {};

package/dist/with-formula/derivations/executor.d.ts

@@ -0,0 +1,61 @@
+import type { DerivationContext, DerivationStrategy } from './types.js';
+export interface RunResult {
+    outputs: Record<string, OutputResult>;
+    failed: boolean;
+}
+/**
+ * Per-output result of a strategy invocation. Discriminated by
+ * `kind`:
+ *
+ * - `record` — the existing v1 shape: one value (or a "skipped"
+ *   marker if the output was optional and `derive` returned null).
+ * - `array` — a list of `(key, value)` entries.
+ *   The caller diffs these against the previously-emitted key set
+ *   (loaded from the fanout sidecar) to compute deletes + upserts.
+ */
+export type OutputResult = RecordOutputResult | ArrayOutputResult | FailedOutputResult;
+export interface RecordOutputResult {
+    kind: 'record';
+    value: Record<string, unknown>;
+    ok: true;
+    /**
+     * `true` when an optional output returned `null` /
+     * `undefined`. The caller deletes any previously-emitted output at
+     * the same id (mirrors "tombstone for derived data"); a never-emitted
+     * output is a silent no-op. `ok: true` because skipping is a
+     * successful outcome, not a failure.
+     */
+    skipped?: boolean;
+}
+export interface ArrayOutputResult {
+    kind: 'array';
+    ok: true;
+    /** One `(key, value)` per derived row. Empty array means "all prior outputs for this source go." */
+    entries: ReadonlyArray<{
+        readonly key: string;
+        readonly value: Record<string, unknown>;
+    }>;
+}
+export interface FailedOutputResult {
+    kind: 'failed';
+    ok: false;
+    error: Error;
+    /** Always empty on failure; present so consumers don't have to narrow. */
+    value: Record<string, unknown>;
+}
+/**
+ * Stateless functions that execute a derivation strategy. Persistence
+ * (encrypt + store.put) is the caller's job — typically
+ * `DerivationRegistry.onSourceWrite` which iterates run() results and
+ * writes each output via `Collection.put`.
+ */
+export declare const DerivationExecutor: {
+    /**
+     * Run `derive` once, validate output shape against the spec, stamp
+     * `_derivedFrom` onto every output. Returns per-output success or
+     * failure; throws only for shape mismatches (a contract violation).
+     */
+    run<TSource extends Record<string, unknown>, TOutputs extends Record<string, Record<string, unknown> | ReadonlyArray<Record<string, unknown>>>>(strategy: DerivationStrategy<TSource, TOutputs>, source: TSource & {
+        id: string;
+    }, sourceVersion: number, strategyHash: string, ctx: DerivationContext): Promise<RunResult>;
+};

package/dist/with-formula/derivations/fanout-sidecar.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Per-source-row fanout sidecar for `shape: 'array'` derivations.
+ *
+ * Each `(sourceCollection, sourceId, outputKey)` triple gets its own
+ * envelope at:
+ *
+ *     _meta/derivations-fanout/<sourceCollection>/<sourceId>/<outputKey>
+ *
+ * The envelope records the last-emitted derived row ids so the
+ * dispatcher can compute the diff on every source-row update in O(1):
+ * read prior keys, compute `toDelete = prev \ new`, write new, persist
+ * back.
+ *
+ * The body is encrypted (AES-GCM under the `_meta` collection DEK) when
+ * the vault is encrypted — the `keys[]` are derived-row ids produced by a
+ * user-supplied key extractor and can be content-bearing (SKU, tag, email),
+ * so a ciphertext-only store must not read them, the derivation graph, or
+ * `emittedAt`. Back-compat: sidecars written before this fix are plaintext
+ * (`_iv === ''`); `loadFanoutSidecar` dual-reads them.
+ *
+ * @module
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+type GetDEK = (collectionName: string) => Promise<EnclaveKey>;
+/** Magic-prefixed JSON payload at `_meta/<recordId>`. */
+export interface FanoutSidecar {
+    readonly _noydb_fanout: 1;
+    /** Source collection name. */
+    readonly source: string;
+    /** Source record id. */
+    readonly sourceId: string;
+    /** Strategy output key (the key in `strategy.outputs`). */
+    readonly outputKey: string;
+    /** Output collection name (audit / forensics). */
+    readonly outputCollection: string;
+    /** Derived-row ids last emitted for this (source, output) pair. */
+    readonly keys: ReadonlyArray<string>;
+    /** ISO timestamp of last dispatch. */
+    readonly emittedAt: string;
+}
+/**
+ * Read the sidecar; returns `undefined` only when it's legitimately absent
+ * (no envelope at that id) — the correct signal for callers to skip
+ * orphan-row reconciliation because there's nothing to reconcile against.
+ *
+ * A PRESENT envelope that fails to decrypt or parse is a data-integrity
+ * problem, not an absence, and is deliberately NOT caught here: swallowing
+ * it to `undefined` would look identical to "no sidecar" and make callers
+ * (the array-derivation dispatch in `vault.ts`/`collection.ts`) silently
+ * skip deleting stale derived rows on a shrink. Let `openEnvelopeJson`'s
+ * `DecryptionError`/`TamperedError` and `JSON.parse` failures propagate,
+ * matching the no-catch convention of sibling decrypt call-sites (e.g.
+ * `with-audit/consent/consent.ts`'s `decryptEntry`).
+ *
+ * Dual-reads for back-compat: an envelope with `_iv === ''` is a legacy
+ * plaintext sidecar (parse `_data` directly); otherwise the body was
+ * encrypted under the `_meta` DEK and is decrypted first.
+ */
+export declare function loadFanoutSidecar(store: NoydbStore, vault: string, source: string, sourceId: string, outputKey: string, getDEK: GetDEK, encrypted: boolean): Promise<FanoutSidecar | undefined>;
+/**
+ * Persist (insert/replace) the sidecar with a fresh key set. The body is
+ * encrypted under the `_meta` DEK when the vault is encrypted (the `keys[]`
+ * can be content-bearing); plaintext only in debug/unencrypted vaults.
+ */
+export declare function saveFanoutSidecar(store: NoydbStore, vault: string, payload: {
+    readonly source: string;
+    readonly sourceId: string;
+    readonly outputKey: string;
+    readonly outputCollection: string;
+    readonly keys: ReadonlyArray<string>;
+}, getDEK: GetDEK, encrypted: boolean): Promise<void>;
+/** Delete the sidecar (used on source-row delete cascade). */
+export declare function deleteFanoutSidecar(store: NoydbStore, vault: string, source: string, sourceId: string, outputKey: string): Promise<void>;
+export {};

package/dist/with-formula/derivations/index.d.ts

@@ -0,0 +1,6 @@
+export { withDerivation } from './with-derivation.js';
+export { withRollup } from './with-rollup.js';
+export { DerivationRegistry } from './registry.js';
+export { DerivationExecutor } from './executor.js';
+export type { DerivationStrategy, DerivationStrategyHandle, DerivedFromMeta, OutputSpec, RecordOutputSpec, ArrayOutputSpec, } from './types.js';
+export { DerivationCycleError, DerivationDepthError, DerivationOutputUnknownError, DerivationOutputShapeError, DerivationCapExceededError, } from '../../kernel/errors.js';

package/dist/with-formula/derivations/registry.d.ts

@@ -0,0 +1,67 @@
+import { ViaGraph, type FieldRef, type EdgeKind, type Grain } from '../../kernel/via/graph.js';
+import type { DerivationStrategy } from './types.js';
+interface RegisteredStrategy {
+    spec: DerivationStrategy<any, any>;
+    strategyHash: string;
+}
+/**
+ * Vault-internal registry of derivation strategies. Owned by `Vault`;
+ * not exported.
+ *
+ * @internal
+ */
+export declare class DerivationRegistry {
+    private readonly _bySource;
+    private readonly _byOutput;
+    register(spec: DerivationStrategy<any, any>): Promise<void>;
+    strategiesForSource(source: string): ReadonlyArray<RegisteredStrategy>;
+    strategiesProducingOutput(collection: string): ReadonlyArray<RegisteredStrategy>;
+    /**
+     * All registered strategies as a flat, deduplicated array.
+     * Each strategy is indexed once per source (not once per output key),
+     * so iterating `_bySource.values()` naturally yields each strategy
+     * exactly once per source — deduplication is handled by flattening
+     * the per-source arrays and collecting into a Set by identity.
+     *
+     * Used by `dumpSchema()` / `describeDerivations()` in the introspection
+     * walker to populate the derivations map.
+     */
+    all(): ReadonlyArray<RegisteredStrategy>;
+    /**
+     * Graph edges for #638 Task 2: one `'derivation'`/`'record'` edge per
+     * (non-self-write) output key — target = the output collection (a
+     * `WHOLE_RECORD` artifact node), sources = every collection that can
+     * trigger this strategy (`source`, `sources[]`, `triggerBy[].collection`,
+     * and — for a rollup — `rollup.from`), mirroring EXACTLY the trigger keys
+     * `register()` indexes under `_bySource`. The self-write reverse-denorm
+     * output (`output.collection === source` with `denorm` declared) is
+     * skipped — the SAME condition the old local DFS used; it is not a cycle
+     * (see the comment `validate()` used to carry, now on this skip).
+     * Rollups ADDITIONALLY get a dedicated `'rollup'`/`'aggregate'` edge
+     * targeting the real `rollup.field` on the parent (`source`) — the
+     * self-write output above only covers the cycle-DFS skip, not
+     * dispatch/taint (Tasks 3/4/6), which need the real field.
+     */
+    edges(): ReadonlyArray<{
+        readonly target: FieldRef;
+        readonly sources: readonly FieldRef[];
+        readonly kind: EdgeKind;
+        readonly grain: Grain;
+    }>;
+    /**
+     * Cycle detection, delegated to `ViaGraph.assertAcyclic()` (#638 Task 2 —
+     * retires the local DFS). Call after all `register()` calls complete (i.e.
+     * at vault open). Throws `DerivationCycleError` on the first cycle found —
+     * SAME class/timing as before; the message/path is byte-identical to the
+     * pre-#638 shape for a pure record-shape derivation cycle (the
+     * `WHOLE_RECORD` artifact suffix is stripped back to a bare collection
+     * name before re-throwing).
+     *
+     * `graph` is the caller's shared per-vault graph, ALREADY carrying this
+     * registry's `edges()` (the caller registers them — see `Vault._initDerivations`)
+     * — omit it (e.g. this registry's own unit tests) to validate this
+     * registry's edges in isolation against a throwaway graph.
+     */
+    validate(graph?: ViaGraph): void;
+}
+export {};

package/dist/with-formula/derivations/stale.d.ts

@@ -0,0 +1,39 @@
+import type { Collection } from '../../kernel/collection.js';
+import type { ReadOnlyVaultFacade } from '../../with-audit/guards/types.js';
+import type { TxContext } from '../../with-commit/tx/transaction.js';
+import type { DerivationRegistry } from './registry.js';
+import type { DerivationStrategy } from './types.js';
+/**
+ * Accessor shape passed through from the owning Vault. Provides the
+ * registry (used to look up strategies and as the WeakMap key) and a
+ * resolver from collection name to the live `Collection` instance.
+ * Same shape as `Collection.derivationSource` so callers can pass it
+ * through directly.
+ */
+export interface DerivationStaleAccessor {
+    registry(): DerivationRegistry;
+    getCollection(name: string): Collection<any>;
+    /**
+     * Read-only vault facade handed to `derive(source, ctx)` on the lazy
+     * resolve-on-read path. Same instance/shape as the eager path uses.
+     */
+    getReadOnlyFacade(): ReadOnlyVaultFacade;
+    /**
+     * Active multi-record TxContext or `null`. The lazy resolve-on-read
+     * path uses this to register tombstone deletes on `_executed` so a
+     * later rollback restores the prior emission. Mirrors the eager
+     * path's rollback tracking; the lazy `put` was historically
+     * unregistered but the tombstone delete (a NEW write path)
+     * matches the eager registration for symmetry.
+     */
+    getActiveTxContext(): TxContext | null;
+}
+/** Mark every output of (strategy, sourceId) as stale. */
+export declare function markStale(registry: DerivationRegistry, strategy: DerivationStrategy<any, any>, sourceId: string): Promise<void>;
+/**
+ * Called from `Collection.get` on lazy-mode output collections. If the
+ * id has a pending stale flag for any strategy producing this output
+ * collection, re-derive before returning the record. No-op when there
+ * is no pending work — keeps the read fast path negligible.
+ */
+export declare function resolveStaleOnRead(accessor: DerivationStaleAccessor, outputCollection: string, id: string): Promise<void>;

package/dist/with-formula/derivations/strategy-hash.d.ts

@@ -0,0 +1 @@
+export declare function computeStrategyHash(source: string, outputKeys: readonly string[], derive: (...args: any[]) => any, sources?: ReadonlyArray<string>): Promise<string>;