footprintjs 0.2.3 → 0.4.0

package/README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <h1 align="center">FootPrint</h1>
   <p align="center">
-    <strong>Turn your whiteboard flowchart into running code &mdash; with automatic causal traces.</strong>
+    <strong>The flowchart pattern for backend code &mdash; self-explainable systems that AI can reason about.</strong>
   </p>
 </p>
 
@@ -15,7 +15,9 @@
 
 <br>
 
-FootPrint is a runtime for building **flowchart pipelines** where each node is just a function. It produces **causal traces** as a byproduct of execution &mdash; so any LLM can explain what happened and why, without reconstructing from logs.
+**MVC is a pattern for structuring backends. FootPrint is a different pattern &mdash; the flowchart pattern &mdash; where your business logic is organized as a graph of functions with transactional state.** The code becomes self-explainable: AI can read the structure, trace every decision, and explain what happened without reconstructing from logs.
+
+> FootPrint is **not** a workflow engine, pipeline builder, or orchestrator. It's a code pattern &mdash; like how React changed how we build UIs, FootPrint changes how we structure backend logic to be AI-native.
 
 ```bash
 npm install footprintjs
@@ -49,18 +51,26 @@ console.log(executor.getNarrative());
 
 > **[Try it in the browser](https://footprintjs.github.io/footprint-playground/)** &mdash; no install needed
 >
-> **[Browse 20+ examples](https://github.com/footprintjs/footPrint-samples)** &mdash; features, flowchart patterns, and a full loan underwriting demo
+> **[Browse 25+ examples](https://github.com/footprintjs/footPrint-samples)** &mdash; features, flowchart patterns, flow recorder strategies, and a full loan underwriting demo
 
 ---
 
-## Why FootPrint?
+## Why a new pattern?
+
+**MVC** separates concerns into Model, View, Controller. It works, but the code is opaque to AI &mdash; an LLM can't trace why a request produced a specific result without parsing scattered logs.
+
+**The flowchart pattern** structures the same logic as a graph of named functions with managed state. This gives you two things MVC can't:
 
-| | Without FootPrint | With FootPrint |
+1. **Self-describing code** &mdash; The structure auto-generates tool descriptions for LLM agents. No hand-written descriptions that drift from reality.
+2. **Self-explaining execution** &mdash; Every run produces a causal trace showing what happened and why. An LLM reads the trace and explains decisions accurately &mdash; no hallucination.
+
+| | MVC / Traditional | Flowchart Pattern (FootPrint) |
 |---|---|---|
-| **LLM explains a decision** | Reconstruct from scattered logs; expensive, slow, hallucination-prone | Read the causal trace; cheap model, fewer tokens, zero hallucination |
-| **Tool descriptions** | Write and maintain them by hand | Auto-generated from the flowchart structure |
-| **Debugging** | `console.log` + guesswork | Time-travel replay to any stage |
+| **Code structure** | Controllers with implicit flow | Explicit graph of named functions |
+| **LLM explains a decision** | Reconstruct from scattered logs | Read the causal trace directly |
+| **Tool descriptions for agents** | Write and maintain by hand | Auto-generated from the graph |
 | **State management** | Global/manual, race-prone | Transactional scope with atomic commits |
+| **Debugging** | `console.log` + guesswork | Time-travel replay to any stage |
 
 ### Example: Loan rejection
 
@@ -104,7 +114,7 @@ That answer came from the trace &mdash; not from the LLM's imagination.
 
 ## The code that produced it
 
-No one wrote those trace sentences. Stage functions just read and write scope &mdash; the narrative builds itself:
+This is regular backend code &mdash; just structured as a flowchart instead of a controller. No one wrote those trace sentences. The functions just read and write scope; the pattern produces the narrative automatically:
 
 ```typescript
 import {
@@ -189,15 +199,17 @@ await executor.run();
 const narrative = executor.getNarrative();  // ← the trace above
 ```
 
-`enableNarrative()` auto-instruments every scope. The executor captures stage transitions, decisions, reads, and writes &mdash; then merges them into the combined trace. No descriptions were written by hand.
+The functions are ordinary TypeScript &mdash; no decorators, no special annotations. The flowchart pattern captures stage transitions, decisions, reads, and writes automatically. That's the difference from MVC: in MVC, this trace doesn't exist. In the flowchart pattern, it's a byproduct of the structure.
 
 ---
 
-## Two narratives, both auto-generated
+## What makes it self-explainable
+
+The flowchart pattern produces two AI-readable outputs automatically &mdash; no extra code needed:
 
-### Build-time: tool description for LLM tool selection
+### Build-time: tool description for LLM agents
 
-When you call `.build()`, FootPrint auto-generates `chart.description` &mdash; a structural summary of what the pipeline does:
+When you call `.build()`, the structure auto-generates `chart.description` &mdash; a complete description of what the code does:
 
 ```
 FlowChart: ReceiveApplication
@@ -244,19 +256,19 @@ const tools = [
 
 ### Runtime: causal trace for LLM explanation
 
-After `.run()`, the combined narrative shows what the code *actually did* &mdash; every value read, every value written, every decision made. This is the trace shown at the top of this page. Ship it alongside the result so any follow-up LLM call can explain what happened and why.
+After `.run()`, the trace shows what the code *actually did* &mdash; every value read, every value written, every decision made. Ship it alongside the result so any LLM can explain what happened and why.
 
-**Build-time tells the LLM which tool to use. Runtime tells the LLM what the tool did.**
+**Build-time tells the LLM what the code does. Runtime tells the LLM what the code did.** That's what makes it self-explainable &mdash; the pattern produces both automatically.
 
 ---
 
-## How it works
+## How the pattern works
 
-FootPrint has three moving parts:
+The flowchart pattern has three parts &mdash; the same way MVC has Model, View, Controller:
 
-1. **Scope** &mdash; Transactional state shared across stages. Writes are buffered and committed atomically. Recorders observe every read/write without modifying behavior.
-2. **Builder** &mdash; Fluent API that compiles your flowchart into a traversable node tree.
-3. **Engine** &mdash; DFS traversal that executes stages, manages state, and generates narrative.
+1. **Builder** &mdash; Define your business logic as a graph of named functions. Like how a controller defines routes, but the structure is an explicit flowchart.
+2. **Scope** &mdash; Transactional state shared across stages. Writes are buffered and committed atomically. This replaces scattered state management.
+3. **Engine** &mdash; Executes the graph and auto-generates the causal trace. You write functions; the pattern produces the explanation.
 
 ```
 ┌─────────────────────┐      ┌─────────────────────┐      ┌─────────────────────┐
@@ -273,229 +285,91 @@ FootPrint has three moving parts:
 
 ---
 
-## Patterns
+## Documentation
 
-### Linear
+| Guide | What it covers |
+|-------|---------------|
+| **[Patterns](docs/guides/patterns.md)** | All 7 flowchart patterns with diagrams |
+| **[Scope](docs/guides/scope.md)** | Typed, raw, and Zod scope; recorders; protection |
+| **[Execution Control](docs/guides/execution.md)** | breakFn, cancellation, timeout, fail-fast, loops |
+| **[Error Handling](docs/guides/error-handling.md)** | Commit-on-error, debug recorder, post-mortem |
+| **[Flow Recorders](docs/guides/flow-recorders.md)** | Pluggable observers for control flow narrative — 7 built-in strategies |
+| **[Contracts](docs/guides/contracts.md)** | defineContract, OpenAPI 3.1, Zod vs JSON Schema |
+| **[Internals](docs/internals/)** | Architecture deep-dives for each library |
 
-```typescript
-import { flowChart } from 'footprintjs';
+---
 
-flowChart('A', fnA)
-  .addFunction('B', fnB)
-  .addFunction('C', fnC)
-  .build();
-```
+## Patterns
 
-### Parallel (Fork)
+Seven composition patterns &mdash; linear, parallel, conditional, multi-select, subflow, streaming, and loops:
 
 ```typescript
+// Linear: A → B → C
+flowChart('A', fnA).addFunction('B', fnB).addFunction('C', fnC).build();
+
+// Parallel fork
 flowChart('Fetch', fetchFn)
   .addListOfFunction([
     { id: 'html', name: 'ParseHTML', fn: parseHTML },
     { id: 'css',  name: 'ParseCSS',  fn: parseCSS },
-    { id: 'js',   name: 'ParseJS',   fn: parseJS },
   ])
   .addFunction('Merge', mergeFn)
   .build();
-```
-
-### Conditional (Decider)
 
-A decider reads from scope and returns the ID of exactly one branch to execute:
-
-```typescript
+// Conditional branching (decider)
 flowChart('Classify', classifyFn)
-  .addDeciderFunction('Route', (scope) => {
-    const type = scope.getValue('fulfillmentType');
-    return type === 'digital' ? 'digital' : 'physical';
-  })
+  .addDeciderFunction('Route', routeFn)
     .addFunctionBranch('digital', 'DigitalDelivery', digitalFn)
     .addFunctionBranch('physical', 'ShipPackage', shipFn)
     .setDefault('physical')
     .end()
   .build();
-```
-
-### Subflow Composition
-
-Mount entire flowcharts as nodes in a larger workflow:
-
-```typescript
-const faqFlow = flowChart('FAQ_Entry', faqEntryFn)
-  .addFunction('FAQ_Answer', faqAnswerFn)
-  .build();
-
-const ragFlow = flowChart('RAG_Entry', ragEntryFn)
-  .addFunction('RAG_Retrieve', ragRetrieveFn)
-  .addFunction('RAG_Answer', ragAnswerFn)
-  .build();
 
-const mainChart = flowChart('Router', routerFn)
+// Subflow composition
+flowChart('Router', routerFn)
   .addSubFlowChart('faq', faqFlow, 'FAQ Handler')
   .addSubFlowChart('rag', ragFlow, 'RAG Handler')
-  .addFunction('Aggregate', aggregateFn)
   .build();
-```
 
-### Streaming (LLM)
-
-```typescript
-const chart = flowChart('PreparePrompt', prepareFn)
-  .addStreamingFunction('AskLLM', 'llm-stream', askLLMFn)
-  .onStream((streamId, token) => process.stdout.write(token))
-  .onStreamEnd((streamId, fullText) => console.log('\nDone:', fullText))
-  .addFunction('ProcessResponse', processFn)
-  .build();
-```
-
-### Execution Control
-
-Every stage receives `(scope, breakFn)`. Three levels of control:
-
-```typescript
-// 1. breakFn() — Graceful stop: complete this stage, skip remaining stages
-const validateInput = async (scope: ScopeFacade, breakFn: () => void) => {
-  const amount = scope.getValue('loanAmount') as number;
-  if (amount > 50_000) {
-    scope.setValue('rejection', 'Exceeds maximum loan amount');
-    breakFn();  // stage output is returned, no error — pipeline just stops
-  }
-};
-
-// 2. throw — Hard abort: stop immediately, propagate error to caller
-const callExternalAPI = async (scope: ScopeFacade) => {
-  const response = await fetch(scope.getValue('apiUrl') as string);
-  if (response.status === 403) {
-    throw new Error('Access denied — cannot continue');  // executor.run() rejects
-  }
-};
-
-// 3. AbortSignal — External cancellation (see Cancellation & Timeout section)
-await executor.run({ timeoutMs: 30_000 });
-```
-
-| Mechanism | Trigger | Stage completes? | Returns |
-|-----------|---------|-----------------|---------|
-| `breakFn()` | Inside stage | Yes | Stage output (no error) |
-| `throw` | Inside stage | No | Error propagates |
-| `AbortSignal` | Outside pipeline | Races async | Error propagates |
-
-### Loops
-
-```typescript
+// Loops
 flowChart('Init', initFn)
-  .addFunction('AskLLM', askFn, 'ask-llm')
-  .addFunction('ParseResponse', parseFn)
-  .addDeciderFunction('HasToolCalls', deciderFn)
-    .addFunctionBranch('yes', 'ExecuteTools', toolsFn)
-    .addFunctionBranch('no', 'Finalize', finalizeFn)
+  .addFunction('Retry', retryFn, 'retry')
+  .addDeciderFunction('Check', checkFn)
+    .addFunctionBranch('again', 'Process', processFn)
+    .addFunctionBranch('done', 'Finish', finishFn)
     .end()
-  .loopTo('ask-llm')  // loop back until no more tool calls
+  .loopTo('retry')
   .build();
 ```
 
+**[Full patterns guide &rarr;](docs/guides/patterns.md)** &mdash; all seven patterns with diagrams and composition examples
+
 ---
 
 ## Scope
 
-Each stage receives a **scope** &mdash; a transactional interface to shared state. Writes are buffered and committed atomically after each stage. Recorders can observe every operation.
-
-### Typed Scope (Recommended)
-
-Extend `ScopeFacade` with domain-specific getters for type-safe reads:
+Each stage receives a **scope** &mdash; a transactional interface to shared state:
 
 ```typescript
-import { ScopeFacade } from 'footprintjs';
-
+// Typed scope (recommended)
 class LoanScope extends ScopeFacade {
-  get creditScore(): number {
-    return this.getValue('creditScore') as number;
-  }
-  get riskTier(): string {
-    return this.getValue('riskTier') as string;
-  }
-  get dtiStatus(): string {
-    return this.getValue('dtiStatus') as string;
-  }
+  get creditScore(): number { return this.getValue('creditScore') as number; }
 }
 
-const scopeFactory = (ctx: any, stageName: string) => new LoanScope(ctx, stageName);
-
-// In stage functions:
-const assessRisk = async (scope: LoanScope) => {
-  if (scope.creditScore < 600 || scope.dtiStatus === 'excessive') {
-    scope.setValue('riskTier', 'high');  // writes go through setValue
-  }
-};
-```
-
-> **Why `getValue`/`setValue` instead of direct properties?** Scope protection blocks `scope.foo = bar` &mdash; those writes bypass transactional buffering and recorder hooks. Typed getters give you clean reads; `setValue` gives you tracked writes.
-
-### Raw Scope (Low-level)
-
-```typescript
-scope.setValue('total', 79.98);              // overwrite
-scope.updateValue('config', { retries: 3 }); // deep merge
-const total = scope.getValue('total');       // read
-```
-
-### Validated Scope (Zod)
-
-```typescript
-import { z } from 'zod';
-import { defineScopeFromZod } from 'footprintjs';
-
-const schema = z.object({
+// Validated scope (Zod)
+const scopeFactory = defineScopeFromZod(z.object({
   creditScore: z.number(),
   riskTier: z.string().optional(),
-});
+}));
 
-const scopeFactory = defineScopeFromZod(schema);
-// Proxy-based: validates writes against the schema at runtime
+// Raw scope
+scope.setValue('total', 79.98);
+scope.updateValue('config', { retries: 3 });
 ```
 
----
-
-## Observability
-
-### Recorders
-
-Recorders observe scope operations without modifying them. Attach multiple for different concerns:
-
-```typescript
-import {
-  ScopeFacade, DebugRecorder, MetricRecorder,
-} from 'footprintjs';
-
-const scopeFactory = (ctx: any, stageName: string) => {
-  const scope = new ScopeFacade(ctx, stageName);
-  scope.attachRecorder(new DebugRecorder({ verbosity: 'verbose' }));
-  scope.attachRecorder(new MetricRecorder());
-  return scope;
-};
-```
-
-> **Note:** `NarrativeRecorder` is attached automatically when narrative is enabled via `setEnableNarrative()` or `executor.enableNarrative()`. You only need to attach it manually if you need custom options.
-
-Error isolation is built in: if a recorder throws, the error is routed to `onError` hooks of other recorders, and the scope operation continues normally.
-
-### Custom Recorders
-
-Implement any subset of six hooks: `onRead`, `onWrite`, `onCommit`, `onError`, `onStageStart`, `onStageEnd`.
-
-```typescript
-import { Recorder, WriteEvent } from 'footprintjs';
-
-class AuditRecorder implements Recorder {
-  readonly id = 'audit';
-  private writes: Array<{ stage: string; key: string; value: unknown }> = [];
+Pluggable recorders observe every operation: `DebugRecorder`, `MetricRecorder`, `NarrativeRecorder`, or bring your own.
 
-  onWrite(event: WriteEvent) {
-    this.writes.push({ stage: event.stageName, key: event.key, value: event.value });
-  }
-  getWrites() { return [...this.writes]; }
-}
-```
+**[Full scope guide &rarr;](docs/guides/scope.md)** &mdash; typed/raw/Zod scope, recorders, protection, provider system
 
 ---
 
@@ -513,95 +387,30 @@ class AuditRecorder implements Recorder {
 | **Composable Subflows** | Mount entire flowcharts as nodes in larger workflows |
 | **Streaming** | Built-in streaming stages for LLM token emission |
 | **Pluggable Recorders** | DebugRecorder, MetricRecorder, NarrativeRecorder &mdash; or bring your own |
+| **Flow Recorders** | 7 narrative strategies for loop summarization &mdash; Windowed, Silent, Adaptive, Progressive, Milestone, RLE, Separate &mdash; or build custom ([examples](https://github.com/footprintjs/footPrint-samples/tree/main/examples/flow-recorders)) |
 
 ---
 
-## Cancellation & Timeout
-
-For LLM pipelines where API calls can hang, `FlowChartExecutor.run()` supports cooperative cancellation:
-
-```typescript
-// Timeout: auto-abort after 30 seconds
-const result = await executor.run({ timeoutMs: 30_000 });
-
-// AbortSignal: cancel from outside
-const controller = new AbortController();
-setTimeout(() => controller.abort(), 10_000);  // cancel after 10s
-const result = await executor.run({ signal: controller.signal });
-```
-
-The signal is checked before each stage starts and raced against async stage functions. Aborted executions throw with the signal's reason.
-
-## Fail-Fast Forks
-
-By default, parallel children run to completion even if some fail (errors captured as `{ isError: true }`). For cases where you want immediate failure:
-
-```typescript
-flowChart('Fetch', fetchFn)
-  .addListOfFunction([
-    { id: 'api1', name: 'CallAPI1', fn: api1Fn },
-    { id: 'api2', name: 'CallAPI2', fn: api2Fn },
-  ], { failFast: true })  // first child error rejects the whole fork
-  .build();
-```
-
-## Design: Error Handling
-
-FootPrint's error handling is designed around one principle: **the trace must capture everything that happened, including failures**.
-
-### Who is responsible for what
-
-| Layer | Responsibility |
-|-------|---------------|
-| **Stage function** | Business logic. Throws errors when invariants break. |
-| **Engine** | Infrastructure. Catches errors, commits the trace, records error metadata, then re-throws. |
-| **Consumer** | Wraps `executor.run()` in try/catch. Inspects `getSnapshot()` after failure for debugging. |
-
-### Commit-on-error: why it matters
+## Execution Control & Error Handling
 
-When a stage throws, the engine calls `context.commit()` *before* re-throwing. This means:
+Three levels of control: `breakFn()` (graceful stop), `throw` (hard abort), `AbortSignal` (external cancellation):
 
 ```typescript
-const executor = new FlowChartExecutor(chart, scopeFactory);
-try {
-  await executor.run();
-} catch (error) {
-  // The snapshot captures everything up to the failure point
-  const snapshot = executor.getSnapshot();
-  // commitLog has entries for every stage that ran (including the one that failed)
-  // executionTree shows scope writes, error metadata, and flow decisions
-  // An LLM can use this to explain WHY the error happened
-}
-```
-
-Without commit-on-error, a failed stage's partial writes would be lost. The trace would end at the last successful stage, hiding the context of the failure. Commit-on-error gives consumers complete visibility:
-
-- **Scope writes** made before the throw are preserved
-- **Error metadata** (`stageExecutionError`) is recorded in the execution tree
-- **Narrative** includes the error event (`"An error occurred at validate: ..."`)
-- **Commit log** has an entry for the failed stage's state
-
-### Error narrative in practice
-
-A validation pipeline fails. The trace tells the story:
+// Graceful stop — complete this stage, skip remaining
+const validate = async (scope: ScopeFacade, breakFn: () => void) => {
+  if (scope.getValue('amount') > 50_000) { breakFn(); }
+};
 
-```
-Stage 1: The process began with FetchData.
-  Step 1: Write rawPayload = {name: "Bob", age: -5}
-Stage 2: Next, it moved on to Validate.
-  Step 1: Read rawPayload = {name: "Bob", age: -5}
-  An error occurred at Validate: Validation failed: age must be positive.
+// Timeout / external cancellation
+await executor.run({ timeoutMs: 30_000 });
+await executor.run({ signal: controller.signal });
 ```
 
-An LLM reading this trace can immediately explain: *"The validation failed because the age field was -5, which was provided in the raw payload from FetchData. Age must be a positive number."* No log reconstruction needed.
+When a stage throws, the engine commits the trace *before* re-throwing &mdash; so `getSnapshot()` captures everything up to the failure point, including partial writes and error metadata.
 
-### What consumers can do
+**[Execution control guide &rarr;](docs/guides/execution.md)** &mdash; breakFn, cancellation, timeout, fail-fast forks, loops
 
-- **Retry with modifications**: Inspect the snapshot, fix inputs, re-run
-- **Partial results**: Fork children that succeed still return results (default mode)
-- **Fail-fast**: Opt into `failFast: true` when any child error should abort the whole fork
-- **Timeout/cancel**: Use `timeoutMs` or `AbortSignal` for external cancellation
-- **Post-mortem**: Feed the narrative + snapshot to an LLM for root-cause analysis
+**[Error handling guide &rarr;](docs/guides/error-handling.md)** &mdash; commit-on-error, debug recorder, error narrative, post-mortem
 
 ---
 
@@ -634,6 +443,8 @@ An LLM reading this trace can immediately explain: *"The validation failed becau
 | `run(options?)` | Execute the flowchart. Options: `{ signal?, timeoutMs? }` |
 | `getNarrative()` | Combined narrative (flow + data) with ScopeFacade; flow-only otherwise |
 | `getFlowNarrative()` | Flow-only narrative sentences |
+| `attachFlowRecorder(recorder)` | Attach a FlowRecorder for pluggable narrative control |
+| `detachFlowRecorder(id)` | Detach a FlowRecorder by id |
 | `getNarrativeEntries()` | Structured `CombinedNarrativeEntry[]` for programmatic use |
 | `getSnapshot()` | Full execution tree + state |
 | `getExtractedResults()` | Extractor results map |
@@ -645,14 +456,18 @@ An LLM reading this trace can immediately explain: *"The validation failed becau
 
 ## How FootPrint Compares
 
-| Aspect | async/await | FootPrint | Temporal / Step Functions |
-|--------|-------------|-----------|--------------------------|
-| **Control Flow** | Implicit in code | Explicit flowchart | External orchestrator |
-| **State** | Manual/global | Scoped & transactional | Durable storage |
+FootPrint is a **code pattern**, not an orchestrator. It runs in your process, not as a separate service.
+
+| Aspect | MVC / async-await | FootPrint (flowchart pattern) | Temporal / Step Functions |
+|--------|-------------------|-------------------------------|--------------------------|
+| **What it is** | Code pattern | Code pattern | External orchestrator |
+| **Runs where** | In your process | In your process | Separate service |
+| **Control flow** | Implicit in code | Explicit graph of functions | External state machine |
+| **State** | Manual / global | Transactional scope | Durable storage |
+| **AI explains decisions** | Parse logs (hallucination-prone) | Read the causal trace (accurate) | Parse event history |
+| **Tool descriptions** | Write by hand | Auto-generated from structure | Write by hand |
 | **Debugging** | Stack traces | Time-travel replay | Event history |
-| **LLM Narrative** | None | Automatic from operations | None |
-| **Tool Descriptions** | Manual | Auto-generated from structure | Manual |
-| **Complexity** | Low | Medium | High |
+| **Complexity** | Low | Low-medium | High |
 
 ---
 
@@ -681,9 +496,31 @@ Measured on Node v22, Apple Silicon. Run `npm run bench` to reproduce.
 
 ---
 
+## Contract & OpenAPI
+
+Define I/O schemas (Zod or raw JSON Schema) and auto-generate OpenAPI 3.1 specs:
+
+```typescript
+import { flowChart, defineContract } from 'footprintjs';
+import { z } from 'zod';
+
+const contract = defineContract(chart, {
+  inputSchema: z.object({ applicantName: z.string(), creditScore: z.number() }),
+  outputSchema: z.object({ decision: z.enum(['approved', 'rejected']) }),
+});
+
+const spec = contract.toOpenAPI({ version: '1.0.0', basePath: '/api' });
+```
+
+Zod is an **optional peer dependency** &mdash; zero bundle impact if not used.
+
+**[Full contracts guide &rarr;](docs/guides/contracts.md)** &mdash; defineContract, OpenAPI generation, Zod vs JSON Schema, builder-level schemas
+
+---
+
 ## Architecture
 
-FootPrint is five independent libraries, each usable standalone:
+FootPrint is the reference implementation of the flowchart pattern &mdash; six independent libraries, each usable standalone:
 
 ```
 src/lib/
@@ -691,9 +528,12 @@ src/lib/
 ├── builder/   Fluent flowchart DSL (FlowChartBuilder, DeciderList, SelectorFnList)
 ├── scope/     Scope facades, recorders, protection, Zod integration
 ├── engine/    DFS traversal, handlers, narrative generators
-└── runner/    Execution convenience (FlowChartExecutor, ExecutionRuntime)
+├── runner/    Execution convenience (FlowChartExecutor, ExecutionRuntime)
+└── contract/  I/O schemas, Zod→JSON Schema, OpenAPI 3.1 generation
 ```
 
+**[Architecture deep-dives &rarr;](docs/internals/)** &mdash; each library has its own README with primitives, design decisions, and dependency graphs
+
 ---
 
 ## License

package/dist/esm/index.js

@@ -24,4 +24,16 @@ export { NarrativeRecorder } from './lib/scope';
 // Zod-based scope definitions
 export { defineScopeFromZod } from './lib/scope';
 export { CombinedNarrativeBuilder } from './lib/engine';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7Ozs7OztHQVNHO0FBT0gsT0FBTyxFQUFFLFNBQVMsRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLGVBQWUsQ0FBQztBQUU1RCwrRUFBK0U7QUFDL0UsdUNBQXVDO0FBQ3ZDLCtFQUErRTtBQUUvRSxPQUFPLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSxjQUFjLENBQUM7QUFFakQsK0VBQStFO0FBQy9FLDBDQUEwQztBQUMxQywrRUFBK0U7QUFFL0UsT0FBTyxFQUFFLFdBQVcsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQUUxQyxZQUFZO0FBQ1osT0FBTyxFQUFFLGNBQWMsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQUM3QyxPQUFPLEVBQUUsYUFBYSxFQUFFLE1BQU0sYUFBYSxDQUFDO0FBQzVDLE9BQU8sRUFBRSxpQkFBaUIsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQUtoRCw4QkFBOEI7QUFDOUIsT0FBTyxFQUFFLGtCQUFrQixFQUFFLE1BQU0sYUFBYSxDQUFDO0FBT2pELE9BQU8sRUFBRSx3QkFBd0IsRUFBRSxNQUFNLGNBQWMsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8qKlxuICogRm9vdFByaW50IOKAlCBQdWJsaWMgQVBJXG4gKlxuICogQ29ubmVjdGVkIGNhdXNhbCB0cmFjZSBsaWJyYXJ5IGZvciBMTE0gcGlwZWxpbmVzLlxuICogQnVpbGRzIGZsb3djaGFydHMsIGV4ZWN1dGVzIHRoZW0gdmlhIERGUyB0cmF2ZXJzYWwsIGFuZCBjYXB0dXJlc1xuICogZXZlcnkgc3RhZ2UncyBjb250ZXh0IChzdGF0ZSwgZGVjaXNpb25zLCBlcnJvcnMpIGluIGFuIGF1ZGl0YWJsZSB0cmFjZS5cbiAqXG4gKiBGb3IgYWR2YW5jZWQvaW50ZXJuYWwgQVBJcyAobWVtb3J5IHByaW1pdGl2ZXMsIGVuZ2luZSBoYW5kbGVycywgcHJvdmlkZXJzKSxcbiAqIGltcG9ydCBmcm9tICdmb290cHJpbnQvYWR2YW5jZWQnLlxuICovXG5cbi8vID09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT1cbi8vIEJ1aWxkZXIg4oCUIEZsb3djaGFydCBjb25zdHJ1Y3Rpb25cbi8vID09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT1cblxuZXhwb3J0IHR5cGUgeyBGbG93Q2hhcnQsIFBpcGVsaW5lU3RhZ2VGdW5jdGlvbiBhcyBTdGFnZUhhbmRsZXIsIFN0cmVhbUhhbmRsZXJzIH0gZnJvbSAnLi9saWIvYnVpbGRlcic7XG5leHBvcnQgeyBmbG93Q2hhcnQsIEZsb3dDaGFydEJ1aWxkZXIgfSBmcm9tICcuL2xpYi9idWlsZGVyJztcblxuLy8gPT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PVxuLy8gUnVubmVyIOKAlCBFeGVjdXRpb24gY29udmVuaWVuY2UgbGF5ZXJcbi8vID09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT1cblxuZXhwb3J0IHsgRmxvd0NoYXJ0RXhlY3V0b3IgfSBmcm9tICcuL2xpYi9ydW5uZXInO1xuXG4vLyA9PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09XG4vLyBTY29wZSDigJQgUGVyLXN0YWdlIGZhY2FkZXMgYW5kIHJlY29yZGVyc1xuLy8gPT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PVxuXG5leHBvcnQgeyBTY29wZUZhY2FkZSB9IGZyb20gJy4vbGliL3Njb3BlJztcblxuLy8gUmVjb3JkZXJzXG5leHBvcnQgeyBNZXRyaWNSZWNvcmRlciB9IGZyb20gJy4vbGliL3Njb3BlJztcbmV4cG9ydCB7IERlYnVnUmVjb3JkZXIgfSBmcm9tICcuL2xpYi9zY29wZSc7XG5leHBvcnQgeyBOYXJyYXRpdmVSZWNvcmRlciB9IGZyb20gJy4vbGliL3Njb3BlJztcblxuLy8gUmVjb3JkZXIgaW50ZXJmYWNlIGFuZCBjb3JlIGV2ZW50IHR5cGVzIChuZWVkZWQgdG8gaW1wbGVtZW50IGN1c3RvbSBSZWNvcmRlcilcbmV4cG9ydCB0eXBlIHsgQ29tbWl0RXZlbnQsIEVycm9yRXZlbnQsIFJlYWRFdmVudCwgUmVjb3JkZXIsIFdyaXRlRXZlbnQgfSBmcm9tICcuL2xpYi9zY29wZSc7XG5cbi8vIFpvZC1iYXNlZCBzY29wZSBkZWZpbml0aW9uc1xuZXhwb3J0IHsgZGVmaW5lU2NvcGVGcm9tWm9kIH0gZnJvbSAnLi9saWIvc2NvcGUnO1xuXG4vLyA9PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09XG4vLyBFbmdpbmUg4oCUIE5hcnJhdGl2ZSAoY29tbW9ubHkgdXNlZClcbi8vID09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT1cblxuZXhwb3J0IHR5cGUgeyBDb21iaW5lZE5hcnJhdGl2ZUVudHJ5IH0gZnJvbSAnLi9saWIvZW5naW5lJztcbmV4cG9ydCB7IENvbWJpbmVkTmFycmF0aXZlQnVpbGRlciB9IGZyb20gJy4vbGliL2VuZ2luZSc7XG5cbi8vID09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT1cbi8vIE1lbW9yeSDigJQgU2NvcGVGYWN0b3J5IHR5cGUgKG5lZWRlZCBmb3IgRmxvd0NoYXJ0RXhlY3V0b3IgY29uc3RydWN0b3IpXG4vLyA9PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09XG5cbmV4cG9ydCB0eXBlIHsgUnVuT3B0aW9ucyB9IGZyb20gJy4vbGliL2VuZ2luZSc7XG5leHBvcnQgdHlwZSB7IFNjb3BlRmFjdG9yeSB9IGZyb20gJy4vbGliL21lbW9yeSc7XG4iXX0=
+export { NarrativeFlowRecorder } from './lib/engine';
+// Built-in FlowRecorder strategies (tree-shakeable — import only what you use)
+export { AdaptiveNarrativeFlowRecorder } from './lib/engine';
+export { MilestoneNarrativeFlowRecorder } from './lib/engine';
+export { ProgressiveNarrativeFlowRecorder } from './lib/engine';
+export { RLENarrativeFlowRecorder } from './lib/engine';
+export { SeparateNarrativeFlowRecorder } from './lib/engine';
+export { SilentNarrativeFlowRecorder } from './lib/engine';
+export { WindowedNarrativeFlowRecorder } from './lib/engine';
+export { defineContract } from './lib/contract';
+export { normalizeSchema, zodToJsonSchema } from './lib/contract';
+export { generateOpenAPI } from './lib/contract';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7Ozs7OztHQVNHO0FBT0gsT0FBTyxFQUFFLFNBQVMsRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLGVBQWUsQ0FBQztBQUU1RCwrRUFBK0U7QUFDL0UsdUNBQXVDO0FBQ3ZDLCtFQUErRTtBQUUvRSxPQUFPLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSxjQUFjLENBQUM7QUFFakQsK0VBQStFO0FBQy9FLDBDQUEwQztBQUMxQywrRUFBK0U7QUFFL0UsT0FBTyxFQUFFLFdBQVcsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQUUxQyxZQUFZO0FBQ1osT0FBTyxFQUFFLGNBQWMsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQUM3QyxPQUFPLEVBQUUsYUFBYSxFQUFFLE1BQU0sYUFBYSxDQUFDO0FBQzVDLE9BQU8sRUFBRSxpQkFBaUIsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQUtoRCw4QkFBOEI7QUFDOUIsT0FBTyxFQUFFLGtCQUFrQixFQUFFLE1BQU0sYUFBYSxDQUFDO0FBT2pELE9BQU8sRUFBRSx3QkFBd0IsRUFBRSxNQUFNLGNBQWMsQ0FBQztBQUl4RCxPQUFPLEVBQUUscUJBQXFCLEVBQUUsTUFBTSxjQUFjLENBQUM7QUFFckQsK0VBQStFO0FBQy9FLE9BQU8sRUFBRSw2QkFBNkIsRUFBRSxNQUFNLGNBQWMsQ0FBQztBQUM3RCxPQUFPLEVBQUUsOEJBQThCLEVBQUUsTUFBTSxjQUFjLENBQUM7QUFDOUQsT0FBTyxFQUFFLGdDQUFnQyxFQUFFLE1BQU0sY0FBYyxDQUFDO0FBQ2hFLE9BQU8sRUFBRSx3QkFBd0IsRUFBRSxNQUFNLGNBQWMsQ0FBQztBQUN4RCxPQUFPLEVBQUUsNkJBQTZCLEVBQUUsTUFBTSxjQUFjLENBQUM7QUFDN0QsT0FBTyxFQUFFLDJCQUEyQixFQUFFLE1BQU0sY0FBYyxDQUFDO0FBQzNELE9BQU8sRUFBRSw2QkFBNkIsRUFBRSxNQUFNLGNBQWMsQ0FBQztBQW9CN0QsT0FBTyxFQUFFLGNBQWMsRUFBRSxNQUFNLGdCQUFnQixDQUFDO0FBQ2hELE9BQU8sRUFBRSxlQUFlLEVBQUUsZUFBZSxFQUFFLE1BQU0sZ0JBQWdCLENBQUM7QUFDbEUsT0FBTyxFQUFFLGVBQWUsRUFBRSxNQUFNLGdCQUFnQixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLyoqXG4gKiBGb290UHJpbnQg4oCUIFB1YmxpYyBBUElcbiAqXG4gKiBDb25uZWN0ZWQgY2F1c2FsIHRyYWNlIGxpYnJhcnkgZm9yIExMTSBwaXBlbGluZXMuXG4gKiBCdWlsZHMgZmxvd2NoYXJ0cywgZXhlY3V0ZXMgdGhlbSB2aWEgREZTIHRyYXZlcnNhbCwgYW5kIGNhcHR1cmVzXG4gKiBldmVyeSBzdGFnZSdzIGNvbnRleHQgKHN0YXRlLCBkZWNpc2lvbnMsIGVycm9ycykgaW4gYW4gYXVkaXRhYmxlIHRyYWNlLlxuICpcbiAqIEZvciBhZHZhbmNlZC9pbnRlcm5hbCBBUElzIChtZW1vcnkgcHJpbWl0aXZlcywgZW5naW5lIGhhbmRsZXJzLCBwcm92aWRlcnMpLFxuICogaW1wb3J0IGZyb20gJ2Zvb3RwcmludC9hZHZhbmNlZCcuXG4gKi9cblxuLy8gPT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PVxuLy8gQnVpbGRlciDigJQgRmxvd2NoYXJ0IGNvbnN0cnVjdGlvblxuLy8gPT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PVxuXG5leHBvcnQgdHlwZSB7IEZsb3dDaGFydCwgUGlwZWxpbmVTdGFnZUZ1bmN0aW9uIGFzIFN0YWdlSGFuZGxlciwgU3RyZWFtSGFuZGxlcnMgfSBmcm9tICcuL2xpYi9idWlsZGVyJztcbmV4cG9ydCB7IGZsb3dDaGFydCwgRmxvd0NoYXJ0QnVpbGRlciB9IGZyb20gJy4vbGliL2J1aWxkZXInO1xuXG4vLyA9PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09XG4vLyBSdW5uZXIg4oCUIEV4ZWN1dGlvbiBjb252ZW5pZW5jZSBsYXllclxuLy8gPT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PVxuXG5leHBvcnQgeyBGbG93Q2hhcnRFeGVjdXRvciB9IGZyb20gJy4vbGliL3J1bm5lcic7XG5cbi8vID09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT1cbi8vIFNjb3BlIOKAlCBQZXItc3RhZ2UgZmFjYWRlcyBhbmQgcmVjb3JkZXJzXG4vLyA9PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09XG5cbmV4cG9ydCB7IFNjb3BlRmFjYWRlIH0gZnJvbSAnLi9saWIvc2NvcGUnO1xuXG4vLyBSZWNvcmRlcnNcbmV4cG9ydCB7IE1ldHJpY1JlY29yZGVyIH0gZnJvbSAnLi9saWIvc2NvcGUnO1xuZXhwb3J0IHsgRGVidWdSZWNvcmRlciB9IGZyb20gJy4vbGliL3Njb3BlJztcbmV4cG9ydCB7IE5hcnJhdGl2ZVJlY29yZGVyIH0gZnJvbSAnLi9saWIvc2NvcGUnO1xuXG4vLyBSZWNvcmRlciBpbnRlcmZhY2UgYW5kIGNvcmUgZXZlbnQgdHlwZXMgKG5lZWRlZCB0byBpbXBsZW1lbnQgY3VzdG9tIFJlY29yZGVyKVxuZXhwb3J0IHR5cGUgeyBDb21taXRFdmVudCwgRXJyb3JFdmVudCwgUmVhZEV2ZW50LCBSZWNvcmRlciwgV3JpdGVFdmVudCB9IGZyb20gJy4vbGliL3Njb3BlJztcblxuLy8gWm9kLWJhc2VkIHNjb3BlIGRlZmluaXRpb25zXG5leHBvcnQgeyBkZWZpbmVTY29wZUZyb21ab2QgfSBmcm9tICcuL2xpYi9zY29wZSc7XG5cbi8vID09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT1cbi8vIEVuZ2luZSDigJQgTmFycmF0aXZlIChjb21tb25seSB1c2VkKVxuLy8gPT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PVxuXG5leHBvcnQgdHlwZSB7IENvbWJpbmVkTmFycmF0aXZlRW50cnkgfSBmcm9tICcuL2xpYi9lbmdpbmUnO1xuZXhwb3J0IHsgQ29tYmluZWROYXJyYXRpdmVCdWlsZGVyIH0gZnJvbSAnLi9saWIvZW5naW5lJztcblxuLy8gRmxvd1JlY29yZGVyIOKAlCBQbHVnZ2FibGUgb2JzZXJ2ZXIgZm9yIGNvbnRyb2wgZmxvdyBldmVudHMgKG1pcnJvcnMgc2NvcGUgUmVjb3JkZXIpXG5leHBvcnQgdHlwZSB7IEZsb3dMb29wRXZlbnQsIEZsb3dSZWNvcmRlciB9IGZyb20gJy4vbGliL2VuZ2luZSc7XG5leHBvcnQgeyBOYXJyYXRpdmVGbG93UmVjb3JkZXIgfSBmcm9tICcuL2xpYi9lbmdpbmUnO1xuXG4vLyBCdWlsdC1pbiBGbG93UmVjb3JkZXIgc3RyYXRlZ2llcyAodHJlZS1zaGFrZWFibGUg4oCUIGltcG9ydCBvbmx5IHdoYXQgeW91IHVzZSlcbmV4cG9ydCB7IEFkYXB0aXZlTmFycmF0aXZlRmxvd1JlY29yZGVyIH0gZnJvbSAnLi9saWIvZW5naW5lJztcbmV4cG9ydCB7IE1pbGVzdG9uZU5hcnJhdGl2ZUZsb3dSZWNvcmRlciB9IGZyb20gJy4vbGliL2VuZ2luZSc7XG5leHBvcnQgeyBQcm9ncmVzc2l2ZU5hcnJhdGl2ZUZsb3dSZWNvcmRlciB9IGZyb20gJy4vbGliL2VuZ2luZSc7XG5leHBvcnQgeyBSTEVOYXJyYXRpdmVGbG93UmVjb3JkZXIgfSBmcm9tICcuL2xpYi9lbmdpbmUnO1xuZXhwb3J0IHsgU2VwYXJhdGVOYXJyYXRpdmVGbG93UmVjb3JkZXIgfSBmcm9tICcuL2xpYi9lbmdpbmUnO1xuZXhwb3J0IHsgU2lsZW50TmFycmF0aXZlRmxvd1JlY29yZGVyIH0gZnJvbSAnLi9saWIvZW5naW5lJztcbmV4cG9ydCB7IFdpbmRvd2VkTmFycmF0aXZlRmxvd1JlY29yZGVyIH0gZnJvbSAnLi9saWIvZW5naW5lJztcblxuLy8gPT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PVxuLy8gTWVtb3J5IOKAlCBTY29wZUZhY3RvcnkgdHlwZSAobmVlZGVkIGZvciBGbG93Q2hhcnRFeGVjdXRvciBjb25zdHJ1Y3Rvcilcbi8vID09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT1cblxuZXhwb3J0IHR5cGUgeyBSdW5PcHRpb25zIH0gZnJvbSAnLi9saWIvZW5naW5lJztcbmV4cG9ydCB0eXBlIHsgU2NvcGVGYWN0b3J5IH0gZnJvbSAnLi9saWIvbWVtb3J5JztcblxuLy8gPT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PVxuLy8gQ29udHJhY3Qg4oCUIEkvTyBib3VuZGFyeSwgc2NoZW1hcywgYW5kIE9wZW5BUEkgZ2VuZXJhdGlvblxuLy8gPT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PVxuXG5leHBvcnQgdHlwZSB7XG4gIEZsb3dDaGFydENvbnRyYWN0LFxuICBGbG93Q2hhcnRDb250cmFjdE9wdGlvbnMsXG4gIEpzb25TY2hlbWEsXG4gIE9wZW5BUElPcHRpb25zLFxuICBPcGVuQVBJU3BlYyxcbn0gZnJvbSAnLi9saWIvY29udHJhY3QnO1xuZXhwb3J0IHsgZGVmaW5lQ29udHJhY3QgfSBmcm9tICcuL2xpYi9jb250cmFjdCc7XG5leHBvcnQgeyBub3JtYWxpemVTY2hlbWEsIHpvZFRvSnNvblNjaGVtYSB9IGZyb20gJy4vbGliL2NvbnRyYWN0JztcbmV4cG9ydCB7IGdlbmVyYXRlT3BlbkFQSSB9IGZyb20gJy4vbGliL2NvbnRyYWN0JztcbiJdfQ==