footprintjs 9.9.0 → 9.10.0

package/README.md

@@ -5,6 +5,8 @@
   </p>
 </p>
 
+<p align="center"><sub>Part of the <a href="https://footprintjs.github.io/"><b>footprintjs ecosystem</b></a> &mdash; the self-explaining stack.</sub></p>
+
 <p align="center">
   <a href="https://github.com/footprintjs/footPrint/actions"><img src="https://github.com/footprintjs/footPrint/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <!-- coverage-badge --><img src="https://img.shields.io/badge/coverage-93%25-brightgreen.svg" alt="coverage: 93%"><!-- /coverage-badge -->
@@ -65,7 +67,7 @@ Stage 4: Next step: Generate rejection.
   Step 1: Write decision = "REJECTED — below-average credit; DTI exceeds 43%; Self-employed < 2yr"
 ```
 
-The LLM backtracks: `riskTier="high"` &larr; `dtiStatus="excessive"` &larr; `dtiRatio=0.6` &larr; `app.monthlyDebts=2100`. Every variable links to its cause:
+The LLM backtracks through the trace, reading `&larr;` as *caused-by* &mdash; each value links to the write that produced it: `riskTier="high"` &larr; `riskFactors` &larr; `creditScore=580`, `dti=0.6`. Every variable links to its cause:
 
 > **LLM:** "Your application was rejected because your debt-to-income ratio of 60% exceeds the 43% maximum, your credit score of 580 falls in the 'fair' tier, and your self-employment tenure of 1 year is below the 2-year minimum."
 
@@ -107,23 +109,22 @@ const chart = flowChart<State>('FetchUser', async (scope) => {
     .end()
   .build();
 
-// 3. Run — state + self-generated trace included
-const result = await chart.recorder(narrative()).run();
-
-console.log(result.state.lane);     // "VIP express"
-console.log(result.narrative);
-// [
-//   "Stage 1: The process began with FetchUser.",
-//   "  Step 1: Write user = {name, tier}",
-//   "Stage 2: Next, it moved on to ApplyDiscount.",
-//   "  Step 1: Read user = {name, tier}",
-//   "  Step 2: Write discount = 0.2",
-//   "Stage 3: Next step: Route by discount tier.",
-//   "  Step 1: Read discount = 0.2",
-//   "[Condition]: It evaluated Rule 0 \"High discount\": discount 0.2 gt 0.1 ✓, and chose VIPCheckout.",
-//   "Stage 4: Next, it moved on to VIPCheckout.",
-//   "  Step 1: Write lane = \"VIP express\"",
-// ]
+// 3. Run — capture the narrative recorder so you can read the trace back
+const trace = narrative();
+const result = await chart.recorder(trace).run();
+
+console.log(result.state.lane);                          // "VIP express"
+console.log(trace.getEntries().map((e) => e.text).join('\n'));
+// Stage 1: The process began with FetchUser.
+//   Step 1: Write user = {name, tier}
+// Stage 2: Next, it moved on to ApplyDiscount.
+//   Step 1: Read user = {name, tier}
+//   Step 2: Write discount = 0.2
+// Stage 3: Next step: Route by discount tier.
+//   Step 1: Read discount = 0.2
+// [Condition]: It evaluated Rule 0 "High discount": discount 0.2 gt 0.1 ✓, and chose VIPCheckout.
+// Stage 4: Next, it moved on to VIPCheckout.
+//   Step 1: Write lane = "VIP express"
 ```
 
 > **[Try it in the browser](https://footprintjs.github.io/footprint-playground/)** &mdash; no install needed
@@ -132,13 +133,29 @@ console.log(result.narrative);
 
 ---
 
+## Vocabulary
+
+If you know agent or backend systems, you already know these &mdash; here's footprint's name for each:
+
+| footprint term | = the thing you already know |
+|---|---|
+| **scope** | the run's shared **state** (an agent's working memory) &mdash; but every read/write is tracked |
+| **stage** | a **step** / node in the flowchart |
+| **decider** / **selector** | a **router** (picks one branch) / **parallel fan-out** (picks many) |
+| **subflow** | a nested flowchart you compose like a **function** |
+| **recorder** | an **observer** &mdash; called on each read, write, and decision |
+| **narrative** | the execution **trace** rendered as plain-English sentences (the LLM-readable form) |
+| **commit log** | the ordered record of **what each step wrote** &mdash; powers time-travel replay |
+
+---
+
 ## Try With Your LLM
 
 Expose any flowchart as an MCP tool in one line &mdash; the description, input schema, and step list are auto-generated from the graph.
 
 ```typescript
 const tool = chart.toMCPTool();
-// { name: 'assesscredit', description: '1. AssessCredit\n2. ...', inputSchema: { ... } }
+// { name: 'AssessCredit', description: 'FlowChart: AssessCredit\nSteps:\n1. AssessCredit\n2. ...', inputSchema: { type: 'object', properties: {} } }
 
 // Register with any MCP server or pass directly to the Anthropic SDK:
 const anthropicTool = { name: tool.name, description: tool.description, input_schema: tool.inputSchema };
@@ -161,7 +178,7 @@ The LLM calls the tool, gets back the decision and causal trace, and explains th
 | **7 Patterns** | Linear, parallel fork, conditional, multi-select, subflow, streaming, loops |
 | **Transactional State** | Per-stage staged commits, safe merges, time-travel replay |
 | **PII Redaction** | Per-key or declarative `RedactionPolicy` with audit trail |
-| **Flow Recorders** | 8 narrative strategies for loop compression |
+| **Flow Recorders** | 7 loop-compression strategies (+ a subflow Manifest recorder) |
 | **Combined Recorders** | Single-hook observers that span data-flow + control-flow &mdash; `executor.attachCombinedRecorder(r)` |
 | **Deferred observers** *(new in 9.6)* | `attach*Recorder(rec, { delivery: 'deferred' })` &mdash; observers run "one beat behind" on a bounded queue instead of inside the engine hot path. Honest backpressure (`drop-oldest`/`sample`/`block`), terminal flush at run resolve/reject/pause, `snapshot.observerStats`. [Guide →](./docs/guides/observers-deferred.md) |
 | **Contracts** | I/O schemas (Zod/JSON Schema) + OpenAPI 3.1 + MCP tool generation |
@@ -276,4 +293,18 @@ Full model + FAQ: [Deferred observers guide](./docs/guides/observers-deferred.md
 
 ---
 
+## The footprintjs ecosystem
+
+The self-explaining stack — from backend pipelines to AI agents. → **[overview](https://footprintjs.github.io/)**
+
+| Project | Role |
+|---|---|
+| **footprintjs** ← you are here | the flowchart pattern (core engine) |
+| [agentfootprint](https://footprintjs.github.io/agentfootprint/) | build self-explaining AI agents |
+| [Explainable UI](https://footprintjs.github.io/explainable-ui/) | visualize a footprintjs run |
+| [Lens](https://github.com/footprintjs/agentfootprint-lens) | debug an agentfootprint run |
+| [Thinking UI](https://footprintjs.github.io/agentThinkingUI/) | replay an agent run for non-devs |
+
+---
+
 [MIT](./LICENSE) &copy; [Sanjay Krishna Anbalagan](https://github.com/sanjay1909)

package/dist/esm/advanced.d.ts

@@ -0,0 +1,52 @@
+/**
+ * footprintjs/advanced — Low-level internals for custom execution engines and testing.
+ *
+ * Most users never need this. Use `footprintjs` (main) instead.
+ * This entry point exposes `SharedMemory`, `StageContext`, `FlowchartTraverser`,
+ * and other primitives that power the engine.
+ *
+ * ```ts
+ * import { SharedMemory, StageContext } from 'footprintjs/advanced';
+ * ```
+ *
+ * @module advanced
+ */
+/**
+ * FootPrint — Advanced / Internal API
+ *
+ * These exports are for advanced use cases, testing, and building
+ * custom execution engines. Most users should use the main 'footprint' entry point.
+ *
+ * Import via: import { ... } from 'footprint/advanced'
+ */
+export type { CommitBundle, FlowControlType, FlowMessage, MemoryPatch, ReadSummaryMarker, ReadTrackingMode, RetentionPolicy, StageSnapshot, TraceEntry, UntrackedSource, WriteSummaryMarker, WriteTrackingMode, } from './lib/memory/index.js';
+export { SharedMemory } from './lib/memory/index.js';
+export { StageContext } from './lib/memory/index.js';
+export { EventLog } from './lib/memory/index.js';
+export { TransactionBuffer } from './lib/memory/index.js';
+export { DiagnosticCollector } from './lib/memory/index.js';
+export { applySmartMerge, deepSmartMerge, getNestedValue, getRunAndGlobalPaths, normalisePath, redactPatch, setNestedValue, updateNestedValue, updateValue, } from './lib/memory/index.js';
+export type { ExecOptions, FlowChartOptions, FlowChartSpec, ILogger, ScopeProtectionMode, SerializedPipelineStructure, SimplifiedParallelSpec, StageFn, StageNode, StreamCallback, StreamLifecycleHandler, StreamTokenHandler, SubflowMountOptions, SubflowRef, } from './lib/builder/index.js';
+export { ArrayMergeMode, DeciderList, SelectorFnList, specToStageNode } from './lib/builder/index.js';
+export { createTypedScopeFactory } from './lib/builder/typedFlowChart.js';
+export type { ProviderResolver, ResolveOptions, ScopeProvider, StageContextLike, StrictMode, } from './lib/scope/index.js';
+export { createErrorMessage, createProtectedScope, ScopeFacade } from './lib/scope/index.js';
+export { attachScopeMethods, isSubclassOfScopeFacade, looksLikeClassCtor, looksLikeFactory, makeClassProvider, makeFactoryProvider, registerScopeResolver, resolveScopeProvider, toScopeFactory, } from './lib/scope/index.js';
+export type { AggregatedMetrics, DebugEntry, DebugRecorderOptions, DebugVerbosity, RecorderContext, StageEvent, StageMetrics, } from './lib/scope/index.js';
+export type { RuntimeSnapshot } from './lib/runner/index.js';
+export { ExecutionRuntime } from './lib/runner/index.js';
+export type { ReactiveOptions, ReactiveTarget } from './lib/reactive/index.js';
+export { BREAK_SETTER, buildNestedPatch, createArrayProxy, joinPath, SCOPE_METHOD_NAMES, shouldWrapWithProxy, } from './lib/reactive/index.js';
+export type { TraverserOptions } from './lib/engine/index.js';
+export type { Decider } from './lib/engine/index.js';
+export { FlowchartTraverser } from './lib/engine/index.js';
+export { isStageNodeReturn } from './lib/engine/index.js';
+export type { IControlFlowNarrative } from './lib/engine/index.js';
+export type { CombinedNarrativeEntry, CombinedNarrativeOptions } from './lib/engine/index.js';
+export type { BranchResult, BranchResults, SerializedPipelineStructure as EngineSerializedPipelineStructure, HandlerDeps, IExecutionRuntime, NodeResultType, RuntimeStructureMetadata, ScopeFactory, SerializedPipelineNode, StageFunction, SubflowResult, TraversalResult, } from './lib/engine/index.js';
+export { NullControlFlowNarrativeGenerator } from './lib/engine/index.js';
+export type { ExecuteNodeFn, RunStageFn } from './lib/engine/index.js';
+export { applyOutputMapping, ChildrenExecutor, computeNodeType, ContinuationResolver, createSubflowHandlerDeps, DeciderHandler, DEFAULT_MAX_ITERATIONS, extractParentScopeValues, getInitialScopeValues, NodeResolver, RuntimeStructureManager, seedSubflowGlobalStore, SelectorHandler, StageRunner, SubflowExecutor, } from './lib/engine/index.js';
+export type { ExecutionCounter } from './lib/engine/runtimeStageId.js';
+export { buildRuntimeStageId, createExecutionCounter, parseRuntimeStageId } from './lib/engine/runtimeStageId.js';
+export { findCommit, findCommits, findLastWriter } from './lib/memory/commitLogUtils.js';

package/dist/esm/detach.d.ts

@@ -0,0 +1,59 @@
+/**
+ * footprintjs/detach — Fire-and-forget child flowchart execution.
+ *
+ * A library of scheduling drivers that lets you detach work from the
+ * parent stage's hot path. The parent stage returns immediately; the
+ * child runs on whichever driver you pick (microtask, immediate, plus
+ * setImmediate / setTimeout / sendBeacon / worker-thread in v4.17.1+).
+ *
+ * Two shapes:
+ *
+ *   - `detachAndJoinLater(driver, child, input)` — returns a `DetachHandle`
+ *     you can `wait()` on (Promise) or read `.status` from (sync).
+ *   - `detachAndForget(driver, child, input)` — discards the handle.
+ *     Use for fire-and-forget telemetry where the caller never needs to
+ *     know how the child finished.
+ *
+ * Two entry points:
+ *
+ *   - `scope.$detachAndJoinLater(driver, child, input)` — from inside a
+ *     stage. refIds are minted from the calling stage's runtimeStageId
+ *     for diagnostic correlation.
+ *   - `executor.detachAndJoinLater(driver, child, input)` — from outside
+ *     any chart (consumer code). refIds use the synthetic `__executor__`
+ *     prefix.
+ *
+ * @example
+ * ```typescript
+ * import { microtaskBatchDriver } from 'footprintjs/detach';
+ * import { flowChart, FlowChartExecutor } from 'footprintjs';
+ *
+ * const telemetry = flowChart('telemetry', async (scope) => {
+ *   await fetch('/log', { method: 'POST', body: JSON.stringify(scope.$getArgs()) });
+ * }, 'telemetry').build();
+ *
+ * const main = flowChart('process', async (scope) => {
+ *   scope.result = await heavyWork();
+ *   // Fire telemetry without blocking the parent.
+ *   scope.$detachAndForget(microtaskBatchDriver, telemetry, { event: 'processed' });
+ * }, 'process').build();
+ *
+ * await new FlowChartExecutor(main).run();
+ * ```
+ */
+export type { DetachDriver, DetachHandle, DetachPollResult, DetachWaitResult, DriverCapabilities, } from './lib/detach/types.js';
+export { createImmediateDriver, immediateDriver } from './lib/detach/drivers/immediate.js';
+export { createMicrotaskBatchDriver, microtaskBatchDriver } from './lib/detach/drivers/microtaskBatch.js';
+export type { SendBeaconDriverOptions } from './lib/detach/drivers/sendBeacon.js';
+export { createSendBeaconDriver } from './lib/detach/drivers/sendBeacon.js';
+export { createSetImmediateDriver, setImmediateDriver } from './lib/detach/drivers/setImmediate.js';
+export type { SetTimeoutDriverOptions } from './lib/detach/drivers/setTimeout.js';
+export { createSetTimeoutDriver, setTimeoutDriver } from './lib/detach/drivers/setTimeout.js';
+export type { WorkerThreadDriverOptions } from './lib/detach/drivers/workerThread.js';
+export { createWorkerThreadDriver } from './lib/detach/drivers/workerThread.js';
+export { asImpl, createHandle, HandleImpl } from './lib/detach/handle.js';
+export type { ChildRunner } from './lib/detach/runChild.js';
+export { defaultRunChild } from './lib/detach/runChild.js';
+export { size as detachedCount, ids as listDetachedIds, lookup as lookupDetachedHandle, } from './lib/detach/registry.js';
+export type { FlushOptions, FlushResult } from './lib/detach/flush.js';
+export { flushAllDetached } from './lib/detach/flush.js';

package/dist/esm/index.d.ts

@@ -0,0 +1,202 @@
+/**
+ * FootPrint — Public API (v3)
+ *
+ * The flowchart pattern for backend code.
+ * Build → Run → Observe.
+ *
+ * **Three import paths:**
+ * ```ts
+ * import { flowChart, decide, narrative } from 'footprintjs';           // main — start here
+ * import { metrics, debug, manifest }     from 'footprintjs/recorders'; // recorder factories
+ * import { SharedMemory, StageContext }   from 'footprintjs/advanced';  // internals
+ * ```
+ *
+ * @module
+ */
+/** @category Quick Start */
+export type { FlowChart, StageFunction as StageHandler, StreamHandlers } from './lib/builder/index.js';
+/** @category Quick Start */
+export { flowChart, FlowChartBuilder, flowChartSelector } from './lib/builder/index.js';
+/** @category Quick Start — build-time observer (twin of FlowRecorder) */
+export type { StructureDeciderCompleteEvent, StructureEdgeAddedEvent, StructureEdgeKind, StructureLoopEdgeAddedEvent, StructureRecorder, StructureStageAddedEvent, StructureSubflowMountedEvent, } from './lib/builder/index.js';
+/** @category Quick Start */
+export type { TypedStageFunction } from './lib/builder/typedFlowChart.js';
+/** @category Quick Start */
+export type { ScopeMethods, TypedScope } from './lib/reactive/index.js';
+/** @category Quick Start */
+export { narrative } from './recorders.js';
+/** @category Decision Branching */
+export type { DecideRule, DecisionEvidence, DecisionResult, FilterOps, RuleEvidence, SelectionEvidence, SelectionResult, WhenClause, WhereFilter, } from './lib/decide/index.js';
+/** @category Decision Branching */
+export { decide, select } from './lib/decide/index.js';
+/** @category Run */
+export type { RunResult } from './lib/runner/index.js';
+/** @category Run */
+export type { FlowChartExecutorOptions } from './lib/runner/index.js';
+/** @category Run */
+export { FlowChartExecutor } from './lib/runner/index.js';
+/** @category Run */
+export { RunContext } from './lib/runner/index.js';
+/** @category Run */
+export type { ChartOpenAPIOptions, MCPToolDescription, RunnableFlowChart } from './lib/runner/RunnableChart.js';
+/** @category Observe — Data */
+export type { CommitEvent, ErrorEvent, ReadEvent, RedactionPolicy, RedactionReport, ScopeRecorder, StageEvent, WriteEvent, } from './lib/scope/index.js';
+/** @category Observe — Data */
+export { MetricRecorder } from './lib/scope/index.js';
+/** @category Observe — Data */
+export { DebugRecorder } from './lib/scope/index.js';
+/** @category Observe — Operation */
+export { RecorderOperation } from './lib/recorder/index.js';
+/**
+ * @category Observe — Delivery tier (RFC-001 deferred observers)
+ *
+ * Every `attach*Recorder` call accepts an options bag:
+ * `executor.attachScopeRecorder(rec, { delivery: 'deferred' })` takes the
+ * recorder OUT of the engine's hot path — events are captured into one
+ * bounded, totally-ordered queue and delivered at the next microtask
+ * checkpoint ("one beat behind"). Omit `delivery` for the historical
+ * synchronous call (byte-identical to previous releases). Accounting
+ * surfaces on `snapshot.observerStats`; `executor.drainObservers()` settles
+ * async listeners before shutdown. See `docs/guides/observers-deferred.md`.
+ */
+export type { AttachRecorderOptions, ObserverDelivery, ObserverDrainResult, ObserverStats, } from './lib/runner/index.js';
+/**
+ * @category Observe — Delivery tier (RFC-001 deferred observers)
+ *
+ * `CapturePolicy` — how a deferred event's payload is materialized at
+ * capture time (`'summary'` default / `'clone'` / `'ref'`). `OverflowPolicy`
+ * — what a saturated queue does (`'drop-oldest'` default / `'sample'` /
+ * `'block'`). `DispatcherStats` / `ListenerStats` — the accounting shapes
+ * embedded in `ObserverStats`. Types only — the observer-queue module
+ * itself is internal; consumers use the attach options.
+ */
+export type { CapturePolicy, DispatcherStats, ListenerStats, OverflowPolicy } from './lib/observer-queue/index.js';
+/** @category Observe — Combined (both data-flow and control-flow) */
+export type { CombinedRecorder } from './lib/recorder/index.js';
+/** @category Observe — Combined (both data-flow and control-flow) */
+export { hasEmitRecorderMethods, hasFlowRecorderMethods, hasRecorderMethods, isFlowEvent, } from './lib/recorder/index.js';
+/**
+ * @category Observe — Emit (user-authored structured events)
+ *
+ * Third observer channel (alongside `ScopeRecorder` and `FlowRecorder`). Consumer
+ * code calls `scope.$emit(name, payload)` from inside a stage; every attached
+ * `EmitRecorder.onEmit(event)` fires synchronously with stage-context
+ * enrichment. Pass-through — no buffering, zero allocation when no recorder
+ * is attached.
+ */
+export type { EmitEvent, EmitRecorder } from './lib/recorder/index.js';
+/** @category Observe — Flow */
+export type { FlowBreakEvent, FlowDecisionEvent, FlowErrorEvent, FlowForkEvent, FlowLoopEvent, FlowNextEvent, FlowRecorder, FlowRunEvent, FlowRunFailedEvent, FlowSelectedEvent, FlowStageEvent, FlowSubflowEvent, FlowSubflowRegisteredEvent, TraversalContext, } from './lib/engine/index.js';
+/** @category Observe — Flow */
+export type { CombinedNarrativeEntry } from './lib/engine/index.js';
+/**
+ * @category Observe — Flow
+ *
+ * `NarrativeFormatter` — pluggable formatter that converts event context
+ * objects into the text lines of the narrative. Prefer this name in new
+ * code; `NarrativeRenderer` is a deprecated alias that will be removed in
+ * the next major release.
+ */
+export type { NarrativeFormatter, NarrativeRenderer } from './lib/engine/index.js';
+/** @category Observe — Flow */
+export { NarrativeFlowRecorder } from './lib/engine/index.js';
+/** @category Observe — Flow */
+export type { ManifestEntry } from './lib/engine/index.js';
+/** @category Observe — Flow */
+export { ManifestFlowRecorder } from './lib/engine/index.js';
+/** @category Observe — Flow */
+export { AdaptiveNarrativeFlowRecorder } from './lib/engine/index.js';
+/** @category Observe — Flow */
+export { MilestoneNarrativeFlowRecorder } from './lib/engine/index.js';
+/** @category Observe — Flow */
+export { ProgressiveNarrativeFlowRecorder } from './lib/engine/index.js';
+/** @category Observe — Flow */
+export { RLENarrativeFlowRecorder } from './lib/engine/index.js';
+/** @category Observe — Flow */
+export { SeparateNarrativeFlowRecorder } from './lib/engine/index.js';
+/** @category Observe — Flow */
+export { SilentNarrativeFlowRecorder } from './lib/engine/index.js';
+/** @category Observe — Flow */
+export { WindowedNarrativeFlowRecorder } from './lib/engine/index.js';
+/** @category Self-Describing */
+export type { FlowChartContract, FlowChartContractOptions, JsonSchema, OpenAPIOptions, OpenAPISpec, } from './lib/contract/index.js';
+/** @category Snapshot & Composition */
+export type { ComposableRunner } from './lib/runner/index.js';
+/** @category Snapshot & Composition */
+export type { RecorderSnapshot, RuntimeSnapshot, SubtreeSnapshot } from './lib/runner/index.js';
+/** @category Snapshot & Composition */
+export { getSubtreeSnapshot, listSubflowPaths } from './lib/runner/index.js';
+/** @category ScopeRecorder */
+export { CompositeRecorder } from './lib/recorder/index.js';
+/** @category Pause/Resume */
+/** @category Pause/Resume */
+export type { FlowchartCheckpoint, PausableHandler } from './lib/pause/index.js';
+/** @category ScopeRecorder */
+export type { CompositeSnapshot } from './lib/recorder/index.js';
+/** @category Configuration */
+export type { ExecutionEnv, ExecutorResult, PausedResult, RunOptions } from './lib/engine/index.js';
+/** @category Configuration */
+export type { ScopeFactory } from './lib/engine/index.js';
+/**
+ * @category Configuration
+ *
+ * Read-tracking policy for `StageSnapshot.stageReads` (#14):
+ * `'full'` (default — per-read value clone, historical behavior) /
+ * `'summary'` (cheap `ReadSummaryMarker` per read) / `'off'` (no tracking,
+ * zero per-read clone). Pass as `new FlowChartExecutor(chart, { readTracking })`
+ * or call `executor.setReadTracking(mode)` before `run()`.
+ */
+export type { ReadSummaryMarker, ReadTrackingMode } from './lib/memory/index.js';
+/**
+ * @category Configuration
+ *
+ * Write-tracking policy for `StageSnapshot.stageWrites` (#13c-A) — the
+ * sibling of `ReadTrackingMode`; both alias the shared `RetentionPolicy`
+ * family from `lib/capture`. `'full'` (default — per-write value clone,
+ * historical behavior) / `'summary'` (cheap `WriteSummaryMarker` per write)
+ * / `'off'` (no tracking; `stageWrites` absent and the `onCommit` mutations
+ * payload is empty — writes themselves still commit, and the commit log is
+ * unaffected). Pass as `new FlowChartExecutor(chart, { writeTracking })` or
+ * call `executor.setWriteTracking(mode)` before `run()`.
+ */
+export type { RetentionPolicy, WriteSummaryMarker, WriteTrackingMode } from './lib/memory/index.js';
+/**
+ * @category Configuration
+ *
+ * Commit-values encoding for the COMMIT LOG (#13c-B) — the third dial of
+ * the family, and the only LOSSLESS one (it changes the log's encoding,
+ * never its information). `'full'` (default — every surviving `set` stores
+ * the full final value, byte-identical to history) / `'delta'` (array
+ * net-changes that are "base plus a tail" commit as an `append` verb
+ * storing only the tail; `deleteValue()` commits as a real `delete` verb;
+ * one trace entry per surviving path). Replay reconstructs every step's
+ * full state exactly. Consumers reading `bundle.overwrite[key]` as the full
+ * value must use `commitValueAt` from `footprintjs/trace`. Pass as
+ * `new FlowChartExecutor(chart, { commitValues })` or call
+ * `executor.setCommitValues(mode)` before `run()`; the active mode is the
+ * snapshot discriminant `getSnapshot().commitValues`.
+ */
+export type { CommitValuesMode } from './lib/memory/index.js';
+/** @category Contract & Validation */
+export type { SchemaKind, ValidationIssue, ValidationResult } from './lib/schema/index.js';
+/** @category Contract & Validation */
+export { detectSchema, isValidatable, isZod } from './lib/schema/index.js';
+/** @category Contract & Validation */
+export { InputValidationError, validateAgainstSchema, validateOrThrow } from './lib/schema/index.js';
+/** @category Error Utilities */
+export type { StructuredErrorInfo } from './lib/engine/index.js';
+/** @category Error Utilities */
+export { extractErrorInfo, formatErrorInfo } from './lib/engine/index.js';
+/**
+ * @category Dev Tools
+ *
+ * Global dev-mode flag. Call `enableDevMode()` at application startup to
+ * turn on developer-only diagnostics across the library — circular-reference
+ * detection in scope writes, warnings when a recorder has no observer
+ * methods, suspicious-predicate warnings in decide/select, structural
+ * checks in `getSubtreeSnapshot`, and any future dev-only diagnostic.
+ *
+ * Production leaves it OFF by default (zero overhead). See the JSDoc on
+ * `enableDevMode` for the full list and usage example.
+ */
+export { disableDevMode, enableDevMode, isDevMode } from './lib/scope/detectCircular.js';