footprintjs 9.9.0 → 9.10.0

package/dist/esm/lib/capture/envelope.d.ts

@@ -0,0 +1,169 @@
+/**
+ * capture/envelope.ts — RFC-001 Block 1: capture envelopes + payload summarizer.
+ *
+ * Pattern:  Point-in-time capture. An observer event is snapshotted into a
+ *           self-contained, immutable envelope at the moment it happens, so
+ *           DELIVERY can be deferred (RFC-001 "one beat behind") without the
+ *           payload drifting under later engine mutations.
+ * Role:     The capture tier of the deferred-observer pipeline
+ *           (`src/lib/observer-queue/`). Pure module — ZERO engine imports
+ *           (only `capture/` internals); the engine wiring is RFC-001
+ *           Blocks 6–10.
+ *
+ * Capture policies (RFC-001 §5):
+ *   - `'summary'` — bounded, reference-free summarization via
+ *     {@link summarizePayload}. Built on the SAME classification path as the
+ *     retention markers in `summarize.ts` (#14 / #13c-A), extended with
+ *     bounded structural descent. Structured-clone-safe by construction.
+ *   - `'clone'`   — `structuredClone` at capture time (the capture-tier
+ *     spelling of retention `'full'` — see the mapping notes in
+ *     `policies.ts`). If the payload is not clonable (functions, symbols,
+ *     live handles), capture DEGRADES to `'summary'` and reports through the
+ *     `warn` hook — a capture must never throw into the producer.
+ *   - `'ref'`     — pass-through of the live reference. The CALLER asserts
+ *     immutability for the delivery window (safe e.g. for committed-state
+ *     reads, proven immutable-after-swap in #13/#13b). Exempt from the
+ *     clone-safety guarantee — see the dev-warn seam below.
+ *
+ * Dev-warn seam (resolves the isDevMode-would-be-an-engine-import problem):
+ *   This module must not import `scope/detectCircular` (engine territory).
+ *   Instead, `capture()` accepts {@link CaptureHooks} with an optional
+ *   `warn` callback and invokes it on every `'ref'` capture and every
+ *   `'clone'` degradation. The WIRING layer (Block 6) binds `warn` to an
+ *   `isDevMode()`-gated, deduplicated console warner; the pure module stays
+ *   engine-free and silent by default (no hooks ⇒ no warning, zero cost).
+ *
+ * Summarizer bounds (documented contract, exported as constants):
+ *   - depth   ≤ {@link PAYLOAD_SUMMARY_MAX_DEPTH}   (3) — deeper structure
+ *     collapses to a classified leaf with `depthClipped: true`.
+ *   - breadth ≤ {@link PAYLOAD_SUMMARY_MAX_ENTRIES} (16) per object/array —
+ *     the remainder is dropped and flagged `truncated: true` (the honest
+ *     `size` still reports the real count).
+ *   - total   ≤ {@link PAYLOAD_SUMMARY_MAX_NODES}   (128) summary nodes per
+ *     payload — a global budget so wide×deep payloads stay O(1)-bounded.
+ *   - string previews ≤ `SUMMARY_PREVIEW_LENGTH` (80) chars.
+ *   Cycles are detected (ancestor set) and flagged `circular: true`;
+ *   throwing getters yield a `'unreadable'` leaf; symbol-keyed properties
+ *   are ignored (same as JSON / `Object.keys`); `Map`/`Set` are leaves with
+ *   their REAL entry count (no descent — matches `summarize.ts`).
+ */
+import { type SummaryValueType } from './summarize.js';
+/** Which observer channel produced a captured event (RFC-001 §5). */
+export type CaptureChannel = 'scope' | 'flow' | 'emit';
+/**
+ * How an event payload is materialized into the envelope (RFC-001 §5).
+ * See the module header for the full per-policy contract.
+ */
+export type CapturePolicy = 'summary' | 'clone' | 'ref';
+/**
+ * A captured observer event — self-contained and immutable (shallow-frozen
+ * at creation). `seq` is the arrival stamp assigned at capture under the
+ * single JS thread: it totally orders events ACROSS all three channels, is
+ * monotonic, and is gap-detectable (a dropped event leaves a visible hole
+ * in the delivered `seq` sequence — honest loss accounting).
+ */
+export interface CaptureEnvelope {
+    /** Arrival stamp — total order across channels; gaps reveal drops. */
+    readonly seq: number;
+    /** Producing observer channel. */
+    readonly channel: CaptureChannel;
+    /** Producing hook name — `'onWrite'`, `'onStageExecuted'`, `'onEmit'`, ... */
+    readonly method: string;
+    /** The execution step that produced the event (`stageId#executionIndex`). */
+    readonly runtimeStageId: string;
+    /** The run that produced the event (Convention 4 per-run scoping). */
+    readonly runId: string;
+    /**
+     * Per {@link CapturePolicy} — NEVER a live engine reference under
+     * `'summary'` / `'clone'`; under `'ref'` the caller asserted immutability.
+     */
+    readonly payload: unknown;
+    /** Capture wall-clock (ms epoch by default; injectable via hooks.now). */
+    readonly capturedAt: number;
+}
+/** The raw event description handed to {@link capture}. */
+export interface CaptureRequest {
+    /** Arrival stamp — assigned by the merged queue's counter (Block 3). */
+    readonly seq: number;
+    readonly channel: CaptureChannel;
+    readonly method: string;
+    readonly runtimeStageId: string;
+    readonly runId: string;
+    /** The LIVE payload — `capture()` materializes it per policy. */
+    readonly payload: unknown;
+}
+/**
+ * Engine-free seams injected by the wiring layer (Block 6). The pure module
+ * never imports dev-mode or clock infrastructure.
+ */
+export interface CaptureHooks {
+    /**
+     * Diagnostic sink — invoked on every `'ref'` capture (caller-asserted
+     * immutability) and every `'clone'` → `'summary'` degradation. Block 6
+     * binds this to an `isDevMode()`-gated, deduplicated warner.
+     */
+    readonly warn?: (message: string) => void;
+    /** Clock for `capturedAt` — defaults to `Date.now`. Injectable for tests. */
+    readonly now?: () => number;
+}
+/** Max nesting depth a payload summary descends before clipping. */
+export declare const PAYLOAD_SUMMARY_MAX_DEPTH = 3;
+/** Max entries summarized per object/array level before truncating. */
+export declare const PAYLOAD_SUMMARY_MAX_ENTRIES = 16;
+/** Global per-payload budget of summary nodes (wide×deep hard bound). */
+export declare const PAYLOAD_SUMMARY_MAX_NODES = 128;
+/**
+ * Leaf classification for a summary node — the `summarize.ts` family plus
+ * `'unreadable'` for properties whose getter threw during capture.
+ */
+export type PayloadSummaryType = SummaryValueType | 'unreadable';
+/**
+ * One node of a payload summary tree. Every field is a primitive, a plain
+ * object, or a plain array — structured-clone-safe by construction.
+ */
+export interface PayloadSummaryNode {
+    /** Classification — same rules as the retention markers (one code path). */
+    readonly type: PayloadSummaryType;
+    /** Honest size proxy: string length, array length, or key/entry count. */
+    readonly size?: number;
+    /** First `SUMMARY_PREVIEW_LENGTH` chars — primitives/strings only. */
+    readonly preview?: string;
+    /** Summarized own enumerable string-keyed properties (objects). */
+    readonly fields?: Readonly<Record<string, PayloadSummaryNode>>;
+    /** Summarized leading items (arrays). */
+    readonly items?: readonly PayloadSummaryNode[];
+    /** Entries were omitted here (breadth cap or node budget). */
+    readonly truncated?: boolean;
+    /** This value is an ancestor of itself — descent stopped. */
+    readonly circular?: true;
+    /** {@link PAYLOAD_SUMMARY_MAX_DEPTH} reached — children not descended. */
+    readonly depthClipped?: true;
+}
+/**
+ * Root of a payload summary — branded so consumers (and tests) can detect
+ * that a payload was summarized rather than cloned. Sibling of the
+ * `__readSummary` / `__writeSummary` retention markers.
+ */
+export interface PayloadSummary extends PayloadSummaryNode {
+    /** Discriminant — `'summary'`-policy envelope payloads carry this. */
+    readonly __payloadSummary: true;
+}
+/**
+ * Produce a bounded, reference-free, structured-clone-safe summary of an
+ * arbitrary payload. Never throws; never holds a reference into the source
+ * value (every node is a fresh object whose fields are primitives). Bounds
+ * are documented in the module header.
+ */
+export declare function summarizePayload(payload: unknown): PayloadSummary;
+/**
+ * Capture one observer event into an immutable {@link CaptureEnvelope}.
+ *
+ * Guarantees:
+ *   - Never throws into the producer (`'clone'` degradation, summarizer
+ *     never-throws contract).
+ *   - The returned envelope is shallow-frozen — `seq`/`channel`/... cannot
+ *     be reassigned. Under `'summary'`/`'clone'` the payload holds no live
+ *     reference into the source; under `'ref'` it intentionally does.
+ *   - Default policy is `'summary'` (cheapest safe tier).
+ */
+export declare function capture(request: CaptureRequest, policy?: CapturePolicy, hooks?: CaptureHooks): CaptureEnvelope;

package/dist/esm/lib/capture/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * capture/ — Shared value-capture / retention primitives (zero deps, leaf
+ * module — `memory/` imports it, never the reverse).
+ *
+ * One home for "what do we keep about a tracked operation's value?":
+ *   - `RetentionPolicy` — the `'full' | 'summary' | 'off'` family behind the
+ *     #14 `readTracking` and #13c-A `writeTracking` dials.
+ *   - `summarizeReadValue` / `summarizeWriteValue` — the parameterized
+ *     summary-marker builders sharing one classification path.
+ *
+ * RFC-001 (deferred observer delivery) builds its capture tier on this
+ * module — see the mapping notes in `policies.ts`.
+ */
+export type { RetentionPolicy } from './policies.js';
+export type { ReadSummaryMarker, SummaryValueType, WriteSummaryMarker } from './summarize.js';
+export { READ_PREVIEW_LENGTH, summarizeReadValue, summarizeWriteValue, SUMMARY_PREVIEW_LENGTH } from './summarize.js';

package/dist/esm/lib/capture/policies.d.ts

@@ -0,0 +1,42 @@
+/**
+ * policies.ts — The retention policy family shared by every snapshot-tracking
+ * dial (#14 `readTracking`, #13c-A `writeTracking`).
+ *
+ * RETENTION answers "what does the engine KEEP in its own snapshot state
+ * (`StageSnapshot.stageReads` / `stageWrites`, and therefore the commit
+ * observer's mutations payload) after the moment of the operation?" It is
+ * distinct from DELIVERY — what an observer receives at event time
+ * (`ScopeRecorder.onRead`/`onWrite` always deliver the live value, in every
+ * retention mode).
+ *
+ * ── RFC-001 (deferred observer delivery) mapping ──────────────────────────
+ * RFC-001's capture tier uses the vocabulary `'clone' | 'summary' | 'ref'`.
+ * When its Block 1 lands it builds on THIS module:
+ *
+ *   - RFC capture `'clone'`   ≈ retention `'full'` (alias at the module
+ *     boundary — same semantics: structuredClone at capture time).
+ *   - RFC capture `'summary'` ≈ retention `'summary'` (same marker shapes —
+ *     see `summarize.ts`).
+ *   - RFC capture `'ref'` is DELIVERY-tier only and is NOT implemented here
+ *     — reserved. Retention must never hold live references into engine
+ *     state: retained entries outlive the stage (the execution tree keeps
+ *     them for the whole run), while a `'ref'` is only safe within the
+ *     immutability window of the captured value. Holding one in retention
+ *     would either pin state generations (the #18 leak) or expose
+ *     later-mutated values as if they were point-in-time captures.
+ */
+/**
+ * How a tracked operation's value is retained in the per-stage snapshot view.
+ *
+ * - `'full'` — `structuredClone` the value at the moment of the operation
+ *   (the historical default for both dials; point-in-time, detached copy).
+ * - `'summary'` — retain a cheap marker (type + size proxy + short preview)
+ *   instead of the value. O(1)-ish per operation; no value clone.
+ * - `'off'` — retain nothing. The operation itself is unaffected (reads
+ *   still return values, writes still commit); only the snapshot bookkeeping
+ *   is skipped.
+ *
+ * `ReadTrackingMode` (#14) and `WriteTrackingMode` (#13c-A) are public
+ * aliases of this type — see `memory/types.ts`.
+ */
+export type RetentionPolicy = 'full' | 'summary' | 'off';

package/dist/esm/lib/capture/summarize.d.ts

@@ -0,0 +1,65 @@
+/**
+ * summarize.ts — Cheap value summarization for `'summary'` retention.
+ *
+ * Extracted from `StageContext` (#14's `summarizeReadValue`) into a shared,
+ * brand-parameterized helper so both snapshot-tracking dials (#14
+ * `readTracking`, #13c-A `writeTracking`) — and later RFC-001's deferred
+ * observer capture tier — produce identical summaries from ONE code path.
+ *
+ * Deliberately avoids every O(value) operation: no clone, no serialization.
+ * See {@link ReadSummaryMarker} for the honest-cost contract.
+ */
+/** Max characters captured in a summary marker's `preview`. */
+export declare const SUMMARY_PREVIEW_LENGTH = 80;
+/**
+ * Compat alias for {@link SUMMARY_PREVIEW_LENGTH} — the name shipped with
+ * #14, kept so existing import paths (`memory/types`, the memory barrel)
+ * stay valid. Same constant; reads and writes share one preview cap.
+ */
+export declare const READ_PREVIEW_LENGTH = 80;
+/** `typeof` result, refined to 'array' / 'null' for objects. */
+export type SummaryValueType = 'string' | 'number' | 'boolean' | 'bigint' | 'symbol' | 'function' | 'object' | 'array' | 'null';
+/** Brand-free summary fields shared by both marker shapes. */
+interface ValueSummary {
+    /** `typeof` result, refined to 'array' / 'null' for objects. */
+    type: SummaryValueType;
+    /** Size proxy: string length, array length, or object key count. */
+    size?: number;
+    /** First {@link SUMMARY_PREVIEW_LENGTH} chars — primitives and strings only. */
+    preview?: string;
+}
+/**
+ * Marker recorded in `StageSnapshot.stageReads` under `readTracking: 'summary'`.
+ *
+ * Honest cost note: `size` is a cheap proxy (string length / array length /
+ * object key count), NOT a serialized byte count — computing real byte size
+ * would require an O(value) serialization, which is exactly the cost the
+ * summary mode removes. `preview` is only produced for primitives and strings
+ * (first {@link SUMMARY_PREVIEW_LENGTH} characters); objects and arrays carry
+ * no preview for the same reason.
+ */
+export interface ReadSummaryMarker extends ValueSummary {
+    /** Discriminant — lets snapshot consumers detect marker entries. */
+    __readSummary: true;
+}
+/**
+ * Marker recorded in `StageSnapshot.stageWrites` (and the commit observer's
+ * mutations payload) under `writeTracking: 'summary'` (#13c-A). Same fields
+ * and cost contract as {@link ReadSummaryMarker}; distinct brand so consumers
+ * can tell which dial produced an entry.
+ */
+export interface WriteSummaryMarker extends ValueSummary {
+    /** Discriminant — lets snapshot consumers detect marker entries. */
+    __writeSummary: true;
+}
+/**
+ * Summarize a tracked READ for `readTracking: 'summary'` (#14). Byte-identical
+ * output to the pre-extraction `StageContext`-local implementation.
+ */
+export declare function summarizeReadValue(value: unknown): ReadSummaryMarker;
+/**
+ * Summarize a tracked WRITE for `writeTracking: 'summary'` (#13c-A). Sibling
+ * of {@link summarizeReadValue} — same classification, distinct brand.
+ */
+export declare function summarizeWriteValue(value: unknown): WriteSummaryMarker;
+export {};

package/dist/esm/lib/contract/defineContract.d.ts

@@ -0,0 +1,18 @@
+/**
+ * contract/defineContract.ts — Factory for creating a FlowChartContract.
+ *
+ * Wraps a compiled FlowChart with I/O schemas and an output mapper,
+ * using the same pattern as SubflowMountOptions (inputMapper/outputMapper).
+ *
+ * Usage:
+ *   const contract = defineContract(chart, {
+ *     inputSchema: z.object({ name: z.string() }),
+ *     outputSchema: z.object({ greeting: z.string() }),
+ *     outputMapper: (scope) => ({ greeting: scope.message as string }),
+ *   });
+ *
+ *   const openapi = contract.toOpenAPI();
+ */
+import type { FlowChart } from '../builder/types.js';
+import type { FlowChartContract, FlowChartContractOptions } from './types.js';
+export declare function defineContract<TInput = unknown, TOutput = unknown>(chart: FlowChart, options: FlowChartContractOptions<TInput, TOutput>): FlowChartContract<TInput, TOutput>;

package/dist/esm/lib/contract/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * contract/ — FlowChart I/O contract and OpenAPI generation layer.
+ *
+ * Standalone library: wraps a compiled FlowChart with input/output schemas
+ * and generates OpenAPI 3.1 specs. Uses the same inputMapper/outputMapper
+ * pattern as subflow mounting.
+ *
+ * Zero runtime deps on Zod — Zod schemas detected via duck-typing and
+ * converted to JSON Schema at contract creation time.
+ */
+export { defineContract } from './defineContract.js';
+export { normalizeSchema, zodToJsonSchema } from './schema.js';
+export { generateOpenAPI } from './openapi.js';
+export type { FlowChartContract, FlowChartContractOptions, JsonSchema, OpenAPIOptions, OpenAPISpec, SchemaInput, } from './types.js';

package/dist/esm/lib/contract/openapi.d.ts

@@ -0,0 +1,18 @@
+/**
+ * contract/openapi.ts — OpenAPI 3.1 spec generator.
+ *
+ * Generates an OpenAPI spec from a FlowChartContract by combining:
+ * - chart.description → operation description (built incrementally during FlowChartBuilder.build())
+ * - inputSchema → requestBody
+ * - outputSchema → response
+ *
+ * chart.description is assembled by FlowChartBuilder as each stage is added —
+ * no post-processing walk of buildTimeStructure is needed or performed here.
+ */
+import type { FlowChartContract, OpenAPIOptions, OpenAPISpec } from './types.js';
+/**
+ * Generates an OpenAPI 3.1 spec from a FlowChartContract.
+ * Uses `chart.description` which FlowChartBuilder assembles at build time —
+ * no post-processing walk of buildTimeStructure is performed here.
+ */
+export declare function generateOpenAPI(contract: FlowChartContract, options?: OpenAPIOptions): OpenAPISpec;

package/dist/esm/lib/contract/schema.d.ts

@@ -0,0 +1,13 @@
+/**
+ * contract/schema.ts — Schema normalization utilities.
+ *
+ * Converts Zod schemas or raw JSON Schema objects into a normalized
+ * JsonSchema format. Detection delegated to schema/detect.ts (single source of truth).
+ *
+ * Standalone: no dependency on Zod at import time.
+ * Compatible with Zod v4 internals.
+ */
+import type { JsonSchema, SchemaInput } from './types.js';
+/** Convert a Zod schema object to JSON Schema. */
+export declare function zodToJsonSchema(zodSchema: Record<string, unknown>): JsonSchema;
+export declare function normalizeSchema(input: SchemaInput): JsonSchema;

package/dist/esm/lib/contract/types.d.ts

@@ -0,0 +1,105 @@
+/**
+ * contract/types.ts — Types for the FlowChart contract layer.
+ *
+ * Defines the I/O boundary for a flowchart: input schema, output schema,
+ * and output mapper. Uses the same pattern as SubflowMountOptions
+ * (inputMapper/outputMapper) but at the top-level flowchart boundary.
+ */
+import type { FlowChart } from '../builder/types.js';
+export type JsonSchema = {
+    type?: string | string[];
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    enum?: unknown[];
+    description?: string;
+    default?: unknown;
+    format?: string;
+    additionalProperties?: boolean | JsonSchema;
+    oneOf?: JsonSchema[];
+    anyOf?: JsonSchema[];
+    allOf?: JsonSchema[];
+    $ref?: string;
+    [key: string]: unknown;
+};
+/** Anything with a `def` (Zod v4) or `_def` (Zod v3) property is treated as a Zod schema. */
+export type SchemaInput = JsonSchema | {
+    def: unknown;
+    [key: string]: unknown;
+};
+export interface FlowChartContractOptions<_TInput = unknown, TOutput = unknown> {
+    /** Schema describing the input (readOnlyContext) shape. Zod or JSON Schema. */
+    inputSchema?: SchemaInput;
+    /** Schema describing the output shape. Zod or JSON Schema. */
+    outputSchema?: SchemaInput;
+    /** Maps the final scope state into the response shape. */
+    outputMapper?: (finalScope: Record<string, unknown>) => TOutput;
+}
+export interface FlowChartContract<_TInput = unknown, TOutput = unknown> {
+    /**
+     * Prototype-linked view of the original compiled FlowChart.
+     *
+     * Own properties (inputSchema, outputSchema, outputMapper) are shadowed here
+     * so that the contract's values take precedence over builder-set values.
+     * All other fields (root, stageMap, methods) are inherited via the prototype
+     * chain with zero copying. The original chart is never mutated.
+     *
+     * ⚠️ Do NOT use Object.keys(), spread ({...chart}), or JSON.stringify() on
+     * this object — it will only see own (shadowed) properties. Use named
+     * property access or chart.toSpec() instead.
+     */
+    chart: FlowChart;
+    /** JSON Schema for the input (normalized from Zod or raw). */
+    inputSchema?: JsonSchema;
+    /** JSON Schema for the output (normalized from Zod or raw). */
+    outputSchema?: JsonSchema;
+    /** Maps the final scope state into the response shape. */
+    outputMapper?: (finalScope: Record<string, unknown>) => TOutput;
+    /** Auto-generated OpenAPI spec. Description is read from `chart.description` (pre-built at build time). */
+    toOpenAPI(options?: OpenAPIOptions): OpenAPISpec;
+}
+export interface OpenAPIOptions {
+    /** API version string (default: "1.0.0"). */
+    version?: string;
+    /** Base path prefix (default: "/"). */
+    basePath?: string;
+    /** HTTP method for the execute endpoint (default: "post"). */
+    method?: string;
+}
+export interface OpenAPISpec {
+    openapi: '3.1.0';
+    info: {
+        title: string;
+        description: string;
+        version: string;
+    };
+    paths: Record<string, Record<string, OpenAPIOperation>>;
+    components?: {
+        schemas?: Record<string, JsonSchema>;
+    };
+}
+export interface OpenAPIOperation {
+    operationId: string;
+    summary: string;
+    description: string;
+    requestBody?: {
+        required: boolean;
+        content: {
+            'application/json': {
+                schema: JsonSchema | {
+                    $ref: string;
+                };
+            };
+        };
+    };
+    responses: Record<string, {
+        description: string;
+        content?: {
+            'application/json': {
+                schema: JsonSchema | {
+                    $ref: string;
+                };
+            };
+        };
+    }>;
+}

package/dist/esm/lib/decide/decide.d.ts

@@ -0,0 +1,47 @@
+/**
+ * decide/decide -- Core decide() and select() helper functions.
+ *
+ * decide() evaluates rules in order (first-match) and returns a DecisionResult.
+ * select() evaluates ALL rules and returns a SelectionResult with all matches.
+ *
+ * Each rule's `when` can be:
+ * - A function: (s) => s.creditScore > 700  (auto-captures reads via temp recorder)
+ * - A filter:   { creditScore: { gt: 700 } } (captures reads + operators + thresholds)
+ */
+import type { DecideRule, DecisionResult, SelectionResult } from './types.js';
+/**
+ * Evaluates rules in order (first-match). Returns a branded DecisionResult.
+ *
+ * @param scope - TypedScope or ScopeFacade
+ * @param rules - Array of DecideRule (function or filter when clauses)
+ * @param defaultBranch - Branch ID if no rule matches
+ *
+ * **Error behavior:** If a `when` function throws during evaluation, the rule is
+ * treated as non-matching (`matched: false`) and the error message is captured in
+ * `matchError` on that rule's `RuleEvidence` entry. Execution continues with
+ * subsequent rules; errors do not propagate to the caller.
+ *
+ * **Empty-filter behavior (anti-vacuous-truth):** a filter rule whose `when` is
+ * `{}` (no evaluable conditions) NEVER matches. This deliberately inverts the
+ * Prisma/SQL `where: {}` intuition ("match everything") — a rule that asserts
+ * nothing must not win a branch on vacuous truth. Use `defaultBranch` for the
+ * catch-all instead. Unknown filter operators also never match (dev mode warns).
+ */
+export declare function decide<S extends object>(scope: S, rules: DecideRule<S>[], defaultBranch: string): DecisionResult;
+/**
+ * Evaluates ALL rules (not first-match). Returns a branded SelectionResult.
+ *
+ * @param scope - TypedScope or ScopeFacade
+ * @param rules - Array of DecideRule (function or filter when clauses)
+ *
+ * **Error behavior:** If a `when` function throws during evaluation, the rule is
+ * treated as non-matching (`matched: false`) and the error message is captured in
+ * `matchError` on that rule's `RuleEvidence` entry. Evaluation continues with
+ * remaining rules; errors do not propagate to the caller.
+ *
+ * **Empty-filter behavior (anti-vacuous-truth):** a filter rule whose `when` is
+ * `{}` (no evaluable conditions) NEVER matches — same rule as `decide()`; an
+ * always-selected branch must be expressed explicitly, not via an empty filter.
+ * Unknown filter operators also never match (dev mode warns).
+ */
+export declare function select<S extends object>(scope: S, rules: DecideRule<S>[]): SelectionResult;

package/dist/esm/lib/decide/evaluator.d.ts

@@ -0,0 +1,39 @@
+/**
+ * decide/evaluator -- Prisma-style filter evaluator for decision rules.
+ *
+ * Pure function. Takes a WhereFilter, a value getter, and a redaction checker.
+ * Evaluates each condition, records the result, returns matched/conditions.
+ *
+ * All keys in the filter are ANDed (all must match for the rule to match).
+ * Decoupled from ScopeFacade — receives callbacks, not scope.
+ */
+import type { FilterCondition, WhereFilter } from './types.js';
+/**
+ * Evaluates a Prisma-style filter against scope values.
+ *
+ * ## Empty filter → NO match (anti-vacuous-truth — inverts Prisma/SQL)
+ *
+ * A filter with no evaluable conditions (`{}`, or only denied/non-object
+ * keys) returns `matched: false`. This deliberately INVERTS the Prisma/SQL
+ * intuition where `where: {}` matches everything: in a decision rule, a rule
+ * that asserts nothing should never win a branch — "all zero conditions
+ * passed" is vacuous truth, and silently routing on it would fabricate
+ * decision evidence. Want a catch-all? Use the explicit `defaultBranch`
+ * argument of `decide()` instead of an empty `when`.
+ *
+ * ## Unknown operators → condition fails (+ dev-mode warning)
+ *
+ * An operator outside the supported set (`eq, ne, gt, gte, lt, lte, in,
+ * notIn`) records a failed condition — the rule can never spuriously match
+ * through a typo (`gte` misspelled `gle`). With dev mode enabled
+ * (`enableDevMode()`), a console warning names the unknown operator and key.
+ *
+ * @param getValueFn - Reads a value from scope by key (raw, for comparison)
+ * @param isRedactedFn - Checks if a key is redacted (for evidence display)
+ * @param filter - The WhereFilter to evaluate
+ * @returns { matched, conditions } — matched = all conditions passed
+ */
+export declare function evaluateFilter<T extends object>(getValueFn: (key: string) => unknown, isRedactedFn: (key: string) => boolean, filter: WhereFilter<T>): {
+    matched: boolean;
+    conditions: FilterCondition[];
+};

package/dist/esm/lib/decide/evidence.d.ts

@@ -0,0 +1,22 @@
+/**
+ * decide/evidence -- Lightweight temp recorder for auto-capturing reads
+ * during a when() function call.
+ *
+ * Attached to scope before calling when(scope), detached after.
+ * Captures ReadEvent key + summarized value + redaction flag.
+ * Uses summarizeValue() at capture time (no raw object references held).
+ */
+import type { ReadEvent, ScopeRecorder } from '../scope/types.js';
+import type { ReadInput } from './types.js';
+/**
+ * Minimal ScopeRecorder that captures reads for decision evidence.
+ * Attach before when(), detach after. Collect via getInputs().
+ */
+export declare class EvidenceCollector implements ScopeRecorder {
+    readonly id: string;
+    private inputs;
+    constructor();
+    onRead(event: ReadEvent): void;
+    /** Returns collected read inputs. */
+    getInputs(): ReadInput[];
+}

package/dist/esm/lib/decide/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * decide/ -- Decision reasoning capture for footprintjs.
+ *
+ * decide() and select() auto-capture evidence from decider/selector functions:
+ * - Function when: (s) => s.creditScore > 700  (auto-captures reads)
+ * - Filter when:  { creditScore: { gt: 700 } }  (captures reads + operators + thresholds)
+ */
+export type { DecideRule, DecisionEvidence, DecisionResult, FilterCondition, FilterOps, FilterRuleEvidence, FunctionRuleEvidence, ReadInput, RuleEvidence, SelectionEvidence, SelectionResult, WhenClause, WhereFilter, } from './types.js';
+export { DECISION_RESULT } from './types.js';
+export { decide, select } from './decide.js';
+export { evaluateFilter } from './evaluator.js';
+export { EvidenceCollector } from './evidence.js';