@noy-db/hub 0.3.0-pre.10 → 0.3.0-pre.11

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

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

@@ -0,0 +1,248 @@
+import type { ReadOnlyVaultFacade } from '../../with-audit/guards/types.js';
+/**
+ * Runtime context handed to `derive(source, ctx)`. Mirrors `GuardContext`'s
+ * narrow shape: read-only vault access, no write capability, no
+ * transaction handle. Determinism is the consumer's responsibility — the
+ * strategy hash includes `derive.toString()`, so the source string fixes
+ * the function's inputs; whatever sibling reads `derive` performs must
+ * yield the same outputs for the same source.
+ */
+export interface DerivationContext {
+    vault: ReadOnlyVaultFacade;
+}
+/**
+ * Metadata that travels inside the `_data` payload of a derived record.
+ * Lives in encrypted payload, not in the unencrypted envelope — the
+ * storage backend cannot infer the derivation graph from listing.
+ */
+export interface DerivedFromMeta {
+    /** Source collection name. */
+    readonly source: string;
+    /** Source record id. */
+    readonly sourceId: string;
+    /** `_v` of the source at derivation time. */
+    readonly sourceVersion: number;
+    /** ISO timestamp when this output was derived. */
+    readonly derivedAt: string;
+    /**
+     * SHA-256 of (source + outputs map keys + derive function source).
+     * Changes when the strategy changes → forces `vault.deriveAll` to
+     * recompute on next visit.
+     */
+    readonly strategyHash: string;
+}
+/** Record-shape output — one source row produces (optionally) one output row at the source's id. */
+export interface RecordOutputSpec {
+    shape: 'record';
+    collection: string;
+    /**
+     * When `true`, the `derive` function may return `null` (or
+     * `undefined`) for this output key. The executor interprets that as
+     * "no output for this invocation": a previously-emitted output at
+     * the same id is deleted (mirroring the empty-group / empty-aggregate
+     * semantics for empty groups); a never-emitted output is a silent
+     * no-op. When `false` (default), returning `null` throws
+     * `DerivationOutputShapeError` — same as v1.
+     */
+    optional?: boolean;
+    /**
+     * Field-level provenance for a **self-write** output — an output
+     * whose `collection` equals the strategy's `source`, used by
+     * reverse-denormalization (`triggerBy`) to patch a denormalized field
+     * back onto the source record.
+     *
+     * `denorm` names the ONLY top-level fields the derivation owns on that
+     * record. The engine merges just those fields from the `derive` return
+     * value onto the current stored record (`{ ...current, ...pick(out, denorm) }`)
+     * — the rest of the user's record is never clobbered by a stale snapshot.
+     * The whole-record `_derivedFrom` provenance tag is NOT applied (the
+     * record stays user-owned); the derivation only claims `denorm`.
+     *
+     * Cycle break is value-level: if the patch changes nothing, no write is
+     * issued — so the self-write that re-fires the source-path derivation
+     * terminates after one idempotent pass.
+     *
+     * REQUIRED when `collection === source` (validated at construction);
+     * ignored for outputs to a different collection.
+     */
+    denorm?: readonly string[];
+}
+/**
+ * Array-shape output — one source row produces a variable-length
+ * list of output rows, each with its own id (from the `key` extractor).
+ *
+ * On every source-row change, the dispatcher diffs the previously
+ * emitted key set against the new one: removed keys are deleted via
+ * `_internalDelete`, new and unchanged keys are upserted via
+ * `Collection.put`. Strict-mode rollback is preserved via the existing
+ * `_executed` tracking.
+ *
+ * Storage of the per-source-row key set lives at
+ * `_meta/derivations-fanout/<source>/<sourceId>/<outputKey>` as a
+ * plain JSON sidecar — keeps dispatch cost O(1) per source row.
+ *
+ * **Slice 1 limitation**: only `lifecycle: 'eager'` is supported.
+ * Registering an array-shape output with `lifecycle: 'lazy'` throws
+ * at `withDerivation` construction time.
+ */
+export interface ArrayOutputSpec {
+    shape: 'array';
+    collection: string;
+    /**
+     * Stable identity extractor for each derived row. Called on every
+     * row returned by `derive`. The string MUST be unique within a
+     * single invocation — duplicate keys throw
+     * `DerivationOutputShapeError`.
+     *
+     * Type is intentionally `(out: Record<string, unknown>) => string`
+     * (not generic) because OutputSpec is type-erased at the registry
+     * level. Strategy-level inference still produces typed `out`
+     * through the strategy's `outputs` map.
+     */
+    key: (output: Record<string, unknown>) => string;
+    /**
+     * Cap on derived rows per source-row invocation. Defaults to 64.
+     * Raise for carry-forward cases (e.g. monthly expansion of
+     * multi-year contracts). Exceeding the cap throws
+     * `DerivationCapExceededError` BEFORE any writes — partial fanout
+     * is never persisted.
+     */
+    maxFanout?: number;
+}
+/** Discriminated union — record + array. */
+export type OutputSpec = RecordOutputSpec | ArrayOutputSpec;
+/**
+ * Registration shape passed to `withDerivation()`.
+ *
+ * @typeParam TSource - the source record type
+ * @typeParam TOutputs - map of output-key → output record type. An output
+ *   value may be a single record, or — for `shape: 'array'` outputs — an
+ *   array of records (the fanout sidecar upserts/deletes each row).
+ */
+export interface DerivationStrategy<TSource extends Record<string, unknown>, TOutputs extends Record<string, Record<string, unknown> | ReadonlyArray<Record<string, unknown>>>> {
+    /** Source collection name. */
+    source: string;
+    /**
+     * Additional collections whose writes ALSO re-fire this derivation.
+     * By default only writes to the single declared
+     * `source` re-trigger a derivation; a `derive` that reads sibling
+     * collections via `ctx.vault` therefore goes stale when those
+     * siblings change. Declare those sibling collections here to wire
+     * them as extra triggers.
+     *
+     * **SAME-ID assumption (load-bearing):** when a write lands on one of
+     * these declared collections, the derivation re-fires with the
+     * PRIMARY `source` record read at the SAME id as the written record
+     * — NOT the written sibling record itself. If no primary `source`
+     * record exists at that id, the re-fire is a silent no-op (no throw,
+     * no output mutation). Model your collections so the sibling and the
+     * primary share an id (the common money/accounting case: an
+     * `allocations` row and its `payments`/`bills` keyed by the same id),
+     * or trigger off a collection you control the id-space of.
+     *
+     * Declared collections participate in cycle detection and are indexed
+     * in the registry's `_bySource` exactly like `source`, so a sibling
+     * that is also a derivation output forms a detectable cycle.
+     *
+     * Each entry must be a non-empty string and must not equal `source`
+     * (validated at `withDerivation()` construction time).
+     */
+    sources?: ReadonlyArray<string>;
+    /**
+     * Foreign-key-keyed triggers for reverse-denormalization. Unlike
+     * `sources[]` (which re-fires at the SAME id), a `triggerBy` entry fans a
+     * write to a PARENT collection OUT to every source record whose FK matches
+     * the written parent's id.
+     *
+     * `{ collection, on }`: a write to `collection` (the parent, e.g.
+     * `'buyers'`) re-fires this derivation once per source record where
+     * `source[on] === writtenParentId` (`on` is the FK field ON the source,
+     * e.g. `'buyerId'`). The matched source record — not the parent — is
+     * passed to `derive`.
+     *
+     * Typical use: keep a denormalized field on the source in sync with a
+     * parent change (a buyer rename → refresh `buyerName` on all their sales),
+     * via a self-write output (`collection === source`) declaring `denorm`.
+     *
+     * Fan-out runs through `ctx.vault.collection(source).query().where(on,'==',id)`,
+     * which uses the FK index when the source declares `withIndexing()` on
+     * `on` (O(children)) and otherwise scans (O(N) — fine for small child
+     * sets). Set `maxFanout` as a safety rail; exceeding it throws
+     * `DerivationCapExceededError` before any write. `triggerBy` collections
+     * participate in cycle detection like `source`/`sources`.
+     *
+     * Each `collection` must be non-empty and not equal `source`; `on` must
+     * be a non-empty field name (validated at construction).
+     */
+    triggerBy?: ReadonlyArray<{
+        collection: string;
+        on: string;
+        maxFanout?: number;
+    }>;
+    /**
+     * @internal — set by `withRollup()`. Marks this strategy as
+     * an aggregate-onto-parent rollup: a write OR delete of a `from` (child)
+     * record recomputes `compute(children where child[key] === parentId)` and
+     * patches it onto `source[field]` of the parent at `parentId` (= child[key]).
+     * `source` is the parent (`into`) collection; the synthetic self-write
+     * output carries `denorm: [field]`. Dispatch handles rollup specially (it
+     * does not run the executor). Eager-only in this slice.
+     */
+    rollup?: {
+        readonly from: string;
+        readonly key: string;
+        readonly field: string;
+        readonly compute: (children: any[]) => unknown;
+    };
+    /** v1: only deterministic derivations supported. */
+    deterministic: true;
+    /**
+     * Output declarations keyed by name. The `derive` function's return
+     * value must have the same keys.
+     */
+    outputs: {
+        [K in keyof TOutputs]: OutputSpec;
+    };
+    /**
+     * Pure function from source to outputs. Runs on plaintext, after DEK
+     * unwrap. Returns a map of named outputs. Each output is encrypted +
+     * stored via the existing `Collection.put` pipeline.
+     *
+     * `ctx.vault` is the same `ReadOnlyVaultFacade` guards see — fetch
+     * sibling records via `ctx.vault.collection<T>(name).get(id)` /
+     * `.list()` / `.query()`. The vault accessor is read-only; there is
+     * no path to a writer from `ctx`.
+     *
+     * **Per-output omission (runtime-supported):** returning `null` or
+     * `undefined` for an individual output key is handled at runtime via
+     * the `optional: true` flag on the output's `RecordOutputSpec` —
+     * the executor deletes any previously-emitted output at that id, or
+     * silently no-ops if none exists. For `shape: 'array'` outputs, null
+     * / undefined is treated as an empty array (clears all prior rows for
+     * that source). The *top-level* return must always be a `TOutputs`
+     * object; returning `null` for the whole result is not supported.
+     * (MV `unionSources` map drop-row is the analogous feature for
+     * materialized views.)
+     */
+    derive: (source: TSource, ctx: DerivationContext) => Promise<TOutputs> | TOutputs;
+    /**
+     * `'eager'` runs `derive` synchronously inside the source-write
+     * transaction. `'lazy'` marks outputs stale on source-change and
+     * derives on first read.
+     */
+    lifecycle: 'eager' | 'lazy' | {
+        mode: 'eager' | 'lazy';
+        maxDepth?: number;
+    };
+    /**
+     * `true` = any output failure rolls back the source write (only with
+     * `withTransactions`). `false` = isolate per-output failure, log,
+     * continue. Default `false`.
+     */
+    strict?: boolean;
+}
+/** Returned by `withDerivation()` and consumed by `createNoydb`. */
+export interface DerivationStrategyHandle {
+    readonly __noydb_strategy: 'derivation';
+    readonly spec: DerivationStrategy<any, any>;
+}

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

@@ -0,0 +1,10 @@
+import type { DerivationStrategy, DerivationStrategyHandle } from './types.js';
+/**
+ * Register a deterministic derivation: one source collection → one or
+ * more typed outputs, computed by the user's `derive` function on
+ * plaintext after DEK unwrap. Outputs are encrypted with the same DEK
+ * as the source and written via the standard `Collection.put` path.
+ *
+ * See docs/superpowers/specs/2026-05-01-dim14-derivation-v1-design.md.
+ */
+export declare function withDerivation<TSource extends Record<string, unknown>, TOutputs extends Record<string, Record<string, unknown> | ReadonlyArray<Record<string, unknown>>>>(spec: DerivationStrategy<TSource, TOutputs>): DerivationStrategyHandle;

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

@@ -0,0 +1,34 @@
+import type { DerivationStrategyHandle } from './types.js';
+/**
+ * `withRollup` — aggregate many child records onto a single field of their
+ * parent. The reverse of a join: instead of reading children
+ * on demand, the parent carries a maintained summary.
+ *
+ * ```ts
+ * withRollup<Sale, Buyer>({
+ *   from: 'sales',          // child collection (the trigger)
+ *   key: 'buyerId',         // FK on the child → parent id
+ *   into: 'buyers',         // parent collection
+ *   field: 'revenueByYear', // field on the parent to maintain
+ *   compute: (sales) => groupSumByYear(sales, 'total'),
+ * })
+ * ```
+ *
+ * On every write OR delete of a `from` record, the parent at id `child[key]`
+ * is recomputed: `compute(allChildren where child[key] === parentId)` is
+ * patched onto `parent[field]`. A parent write also recomputes its own
+ * aggregate (so a parent created after its children still fills in). Only the
+ * `field` is touched — the rest of the parent record is never clobbered — and
+ * a value-equality guard suppresses no-op writes. The aggregate is gap-free
+ * with respect to child inserts, updates, and deletes.
+ *
+ * Desugars to a `withDerivation` strategy carrying a `rollup` marker; dispatch
+ * handles it without invoking the executor. Eager-only in this slice.
+ */
+export declare function withRollup<TChild extends Record<string, unknown> = Record<string, unknown>, TParent extends Record<string, unknown> = Record<string, unknown>>(config: {
+    from: string;
+    key: keyof TChild & string;
+    into: string;
+    field: keyof TParent & string;
+    compute: (children: TChild[]) => unknown;
+}): DerivationStrategyHandle;