footprintjs 9.31.0 → 9.33.0

package/AGENTS.md

@@ -2,34 +2,26 @@
 
 This is the footprint.js library — the flowchart pattern for backend code. Self-explainable systems that AI can reason about.
 
+> Every TypeScript block in this file is type-checked (strict) and run against the built package (footprintjs 9.32.0); the `// …` lines under a `console.log` are that run's real output.
+
 ## Core Principle
 
-**Collect during traversal, never post-process.** All data collection (narrative, metrics, manifest, identity) happens as side effects of the single DFS traversal pass. Never walk the tree again after execution.
+**Collect during traversal, never post-process.** All data collection (narrative, metrics, manifest, topology, in/out boundaries) happens as side effects of the single DFS traversal pass. Never walk the tree again after execution.
 
 ## Architecture — Library of Libraries
 
-```
-src/lib/
-├── capture/   → Value-capture/retention primitives (RetentionPolicy 'full'|'summary'|'off', read/write summary markers) — shared by the readTracking (#14) + writeTracking (#13c-A) dials; RFC-001 builds on it; also the shared leaves `invokeHook`, `circular`, `summarizeValue` (`lib/devMode.ts`, the dev-mode flag, sits beside it)
-├── memory/    → Transactional state (SharedMemory, StageContext, TransactionBuffer, EventLog)
-├── schema/    → Validation abstraction (Zod optional, duck-typed detection)
-├── builder/   → Fluent DSL (FlowChartBuilder, flowChart(), DeciderList, SelectorFnList)
-├── scope/     → Per-stage facades + recorders + providers
-├── reactive/  → TypedScope<T> deep Proxy (typed property access, $-methods, cycle-safe)
-├── decide/    → decide()/select() decision evidence capture (filter + function)
-├── recorder/  → CompositeRecorder, KeyedStore<T>, SequenceStore<T>, BoundaryStateStore<TState>, composition primitives
-├── pause/     → Pause/Resume (PauseSignal, FlowchartCheckpoint, PausableHandler)
-├── engine/    → DFS traversal + narrative + 13 handlers
-├── runner/    → High-level executor (FlowChartExecutor)
-└── contract/  → I/O schema + OpenAPI generation
-```
+`package.json` `exports` has six doors — import from the one that owns the symbol:
 
-Layering is enforced, not described: a file imports only its own layer or below. The table is `scripts/layering.config.cjs` — leaves (`capture/`, `schema/`, `pause/`, `lib/devMode.ts`) < `memory/` < `recorder/` · `scope/` · `reactive/` · `decide/` < `engine/` < `builder/` · `runner/` · `contract/` · `detach/` — checked by lint (`import/no-restricted-paths` zones + `import/no-cycle`) and `npm run check:layering` (value-level cycles + upward runtime edges). Three edges are named on purpose: builder → `runner/RunnableChart.ts`, engine → `reactive/handles.ts`, scope → `detach/spawn.ts`.
+| Import | What it is for |
+|---|---|
+| `footprintjs` | The main door: `flowChart`, `FlowChartExecutor`, `decide` / `select`, `narrative`, the built-in recorder classes, `interrupt`, and the public types |
+| `footprintjs/recorders` | Recorder factories — `narrative()`, `metrics()`, `debug()`, `manifest()`, `adaptive()`, `milestone()`, `windowed()` — and `CompositeRecorder` |
+| `footprintjs/trace` | Execution tracing: runtimeStageId helpers, commit-log queries (`findCommit`, `findLastWriter`, `causalChain`, `sliceForKey`, `stateAt`, `timeTravel`), the storage primitives (`KeyedStore`, `SequenceStore`, `BoundaryStateStore`), `topologyRecorder()` / `inOutRecorder()`, `HONESTY_CODES` |
+| `footprintjs/advanced` | Engine internals (`SharedMemory`, `StageContext`, `FlowchartTraverser`, `ScopeFacade`, scope providers, `SCOPE_METHOD_NAMES`, `ArrayMergeMode`) plus a small hand-picked slice of the trace helpers (`findCommit`, `findCommits`, `findLastWriter`, `parseRuntimeStageId`, `buildRuntimeStageId`) — not all of `trace` |
+| `footprintjs/detach` | Fire-and-forget child charts and their drivers |
+| `footprintjs/zod` | Opt-in zod bridge (`defineScopeFromZod`, …) — the core never imports zod |
 
-Three entry points:
-- `import { ... } from 'footprintjs'` — public API
-- `import { ... } from 'footprintjs/trace'` — execution tracing: runtimeStageId, commitLog queries, storage primitives (KeyedStore, SequenceStore, BoundaryStateStore)
-- `import { ... } from 'footprintjs/advanced'` — engine internals (also re-exports trace)
+The module map (one line per `src/lib/` directory) and the layering rule — a file imports only its own layer or below — live in one place each, so this file keeps no copy that can drift: `CLAUDE.md` ("Module map" and "The fence", shipped with the package) and the layer table in `scripts/layering.config.cjs`, enforced by lint (`import/no-restricted-paths` zones + `import/no-cycle`) and `npm run check:layering` (value-level cycles + upward runtime edges).
 
 ## Key API
 
@@ -49,10 +41,12 @@ interface LoanState {
 const chart = flowChart<LoanState>('Intake', async (scope) => {
   scope.creditTier = 'A';                    // typed write
   scope.amount = 50000;                       // typed write
-  scope.customer.address.zip = '90210';       // deep write (updateValue)
+  scope.customer = { name: 'Ana', address: { zip: '10001' } };
+  scope.tags = [];
+  scope.customer.address.zip = '90210';       // deep write (recorded as an update of `customer`)
   scope.tags.push('vip');                     // array copy-on-write (single push)
-  scope.$batchArray('tags', (arr) => {        // O(1) batch: 1 clone + 1 commit
-    arr.push('vip', 'premium', 'verified');
+  scope.$batchArray('tags', (arr) => {        // batch: one clone + one commit however many mutations
+    arr.push('premium', 'verified');
   });
   scope.approved = true;                      // optional field
 
@@ -61,28 +55,82 @@ const chart = flowChart<LoanState>('Intake', async (scope) => {
   scope.$metric('latency', 42);
   const args = scope.$getArgs<{ requestId: string }>();
   const env = scope.$getEnv();
-  scope.$break();                             // stop pipeline
+  console.log(args.requestId, env.traceId);
+  // req-123 trace-1
+  scope.$break();                             // stop the run
 }, 'intake')
   .build();
 
 const executor = new FlowChartExecutor(chart);
-await executor.run({ input: { requestId: 'req-123' } });
+executor.enableNarrative();
+await executor.run({ input: { requestId: 'req-123' }, env: { traceId: 'trace-1' } });
+
+console.log(JSON.stringify(executor.getSnapshot().sharedState));
+// {"creditTier":"A","amount":50000,"customer":{"name":"Ana","address":{"zip":"90210"}},"tags":["vip","premium","verified"],"approved":true}
+// the batch is ONE write; the single push before it is another
+console.log(JSON.stringify(executor.getNarrativeEntries().filter((e) => e.text.includes('Write tags')).map((e) => e.text)));
+// ["Step 4: Write tags = []","Step 8: Write tags = (1 item)","Step 10: Write tags = (3 items)"]
 ```
 
 ### decide() / select() — Decision Evidence Capture
 
 ```typescript
-import { decide, select } from 'footprintjs';
+import { flowChart, FlowChartExecutor, decide } from 'footprintjs';
+
+interface RiskState {
+  creditScore: number;
+  dti: number;
+}
+
+const chart = flowChart<RiskState>('Intake', (scope) => {
+    scope.creditScore = 750;
+    scope.dti = 0.35;
+  }, 'intake')
+  // Inside a decider function — auto-captures which values led to the decision
+  .addDeciderFunction('ClassifyRisk', (scope) => {
+    return decide(scope, [
+      { when: { creditScore: { gt: 700 }, dti: { lt: 0.43 } }, then: 'approved', label: 'Good credit' },
+      { when: (s) => s.creditScore > 600, then: 'manual-review', label: 'Marginal' },
+    ], 'rejected');
+  }, 'classify-risk')
+    .addFunctionBranch('approved', 'Approve', () => {})
+    .addFunctionBranch('manual-review', 'Review', () => {})
+    .addFunctionBranch('rejected', 'Reject', () => {})
+    .end()
+  .build();
+
+const executor = new FlowChartExecutor(chart);
+executor.enableNarrative();
+await executor.run();
+console.log(executor.getNarrativeEntries().find((e) => e.type === 'condition')?.text);
+// [Condition]: It evaluated Rule 0 "Good credit": creditScore 750 gt 700 ✓, dti 0.35 lt 0.43 ✓, and chose Approve.
+```
+
+Filter operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `notIn`. `decide()` returns `{ branch, evidence }`; the narrative names the chosen branch by its **name** (`Approve`), the evidence by its **id** (`approved`).
 
-// Inside a decider function — auto-captures which values led to the decision
-.addDeciderFunction('ClassifyRisk', (scope) => {
-  return decide(scope, [
-    { when: { creditScore: { gt: 700 }, dti: { lt: 0.43 } }, then: 'approved', label: 'Good credit' },
-    { when: (s) => s.creditScore > 600, then: 'manual-review', label: 'Marginal' },
-  ], 'rejected');
-}, 'classify-risk')
+`select()` is the multi-pick twin — every matching rule picks its branch (not first-match), and the picked branches run in parallel:
+
+```typescript
+import { flowChart, FlowChartExecutor, select } from 'footprintjs';
+
+const chart = flowChart<{ glucose: number; bmi: number }>('Intake', (scope) => {
+    scope.glucose = 120;
+    scope.bmi = 31;
+  }, 'intake')
+  .addSelectorFunction('Screen', (scope) => select(scope, [
+      { when: { glucose: { gt: 100 } }, then: 'diabetes', label: 'High glucose' },
+      { when: { bmi: { gt: 30 } }, then: 'obesity', label: 'High BMI' },
+    ]), 'screen')
+    .addFunctionBranch('diabetes', 'DiabetesPath', () => {})
+    .addFunctionBranch('obesity', 'ObesityPath', () => {})
+    .end()
+  .build();
 
-// Narrative: "It evaluated Rule 0 'Good credit': creditScore 750 gt 700, and chose approved."
+const executor = new FlowChartExecutor(chart);
+executor.enableNarrative();
+await executor.run();
+console.log(executor.getNarrativeEntries().find((e) => e.type === 'fork')?.text);
+// [Parallel]: Forking into 2 parallel paths: DiabetesPath, ObesityPath.
 ```
 
 **Naming the default branch.** The default is chosen by no rule, so no
@@ -92,132 +140,264 @@ string; the label lands on `DecisionEvidence.defaultLabel` and is recorded on
 every decision, not just the runs that fell through.
 
 ```typescript
-decide(scope, rules, { branch: 'rejected', label: 'No rule fired — application rejected' });
-// bare string still works, byte-identical: decide(scope, rules, 'rejected')
+import { flowChart, FlowChartExecutor, decide } from 'footprintjs';
+
+for (const creditScore of [750, 100]) {
+  const chart = flowChart<{ creditScore: number }>('Intake', (scope) => { scope.creditScore = creditScore; }, 'intake')
+    .addDeciderFunction('ClassifyRisk', (scope) => decide(scope, [
+        { when: { creditScore: { gt: 700 } }, then: 'approved', label: 'Good credit' },
+      ], { branch: 'rejected', label: 'No rule fired — application rejected' }), 'classify-risk')
+      .addFunctionBranch('approved', 'Approve', () => {})
+      .addFunctionBranch('rejected', 'Reject', () => {})
+      .end()
+    .build();
+  const executor = new FlowChartExecutor(chart);
+  executor.attachFlowRecorder({
+    id: 'evidence',
+    onDecision: (e) => console.log(e.evidence?.chosen, '|', e.evidence?.defaultLabel),
+  });
+  await executor.run();
+}
+// approved | No rule fired — application rejected
+// rejected | No rule fired — application rejected
+// a bare string default still works: decide(scope, rules, 'rejected') — the evidence then has no `defaultLabel` key
 ```
 
 ### Builder
 
 ```typescript
-import { flowChart, FlowChartBuilder } from 'footprintjs';
+import { flowChart } from 'footprintjs';
 
-const chart = flowChart('Stage1', fn1, 'stage-1', undefined, 'Description')
-  .addFunction('Stage2', fn2, 'stage-2', 'Description')
-  .addDeciderFunction('Decide', deciderFn, 'decide', 'Route based on risk')
-    .addFunctionBranch('high', 'Reject', rejectFn)
-    .addFunctionBranch('low', 'Approve', approveFn)
+const chart = flowChart('Stage1', () => {}, 'stage-1', { description: 'Description' })
+  .addFunction('Stage2', () => {}, 'stage-2', 'Description')
+  .addDeciderFunction('Decide', () => 'high', 'decide', 'Route based on risk')
+    .addFunctionBranch('high', 'Reject', () => {})
+    .addFunctionBranch('low', 'Approve', () => {})
     .setDefault('high')
     .end()
   .build();
 ```
 
-Methods: `start()`, `addFunction()`, `addStreamingFunction()`, `addDeciderFunction()`, `addSelectorFunction()`, `addListOfFunction()`, `addPausableFunction()`, `addSubFlowChart()`, `addSubFlowChartNext()`, `loopTo()`, `contract()`, `build()`, `toSpec()`, `toMermaid()`
+The first stage is `flowChart(name, fn, id, { description?, structureRecorders? })`; every later stage is `.addFunction(name, fn, id, description?)`.
+
+Methods (not exhaustive): `start()`, `addFunction()`, `addStreamingFunction()`, `addDeciderFunction()`, `addSelectorFunction()`, `addListOfFunction()`, `addParallelForEach()`, `addPausableFunction()`, `addSubFlowChart()`, `addSubFlowChartNext()`, `addLazySubFlowChart()`, `addDetachAndForget()`, `addDetachAndJoinLater()`, `retry()`, `tag()`, `loopTo()`, `contract()`, `attachStructureRecorder()`, `build()`, `toSpec()`, `toMermaid()`. `toOpenAPI()` and `toMCPTool()` are on the built chart.
 
 ### ScopeFacade (Internal — use TypedScope for new code)
 
+`ScopeFacade` (from `footprintjs/advanced`) is the engine's own scope; `TypedScope` wraps it. A stage only receives a `ScopeFacade` when you supply a custom `scopeFactory`. In a TypedScope stage the same operations are `scope.$getValue(key)` / `scope.$setValue(key, value)` / `scope.$getArgs()` / `scope.$getEnv()` — plain `scope.getValue` does not exist there.
+
 ```typescript
-scope.getValue('key')              // tracked read
-scope.setValue('key', value)        // tracked write
-scope.getArgs<T>()                 // frozen readonly input (NOT tracked)
-scope.getEnv()                     // frozen execution environment (NOT tracked)
+import { flowChart, FlowChartExecutor } from 'footprintjs';
+import { ScopeFacade } from 'footprintjs/advanced';
+
+// TypedScope stage: dynamic keys go through the $ methods
+const typed = flowChart<Record<string, unknown>>('Typed', (scope) => {
+  scope.$setValue('dyn', 41);
+  scope.$setValue('dyn', (scope.$getValue('dyn') as number) + 1);
+}, 'typed').build();
+const typedRun = new FlowChartExecutor(typed);
+await typedRun.run();
+console.log(JSON.stringify(typedRun.getSnapshot().sharedState));
+// {"dyn":42}
+
+// ScopeFacade stage: getValue / setValue / getArgs / getEnv
+const facade = flowChart<any>('Facade', (scope: any) => {
+  const s = scope as ScopeFacade;
+  s.setValue('key', { v: 1 });
+  console.log(JSON.stringify([s.getValue('key'), s.getArgs(), s.getEnv()]));
+}, 'facade').build();
+const facadeRun = new FlowChartExecutor(facade, {
+  scopeFactory: (ctx, stageName, readOnly, env) => new ScopeFacade(ctx, stageName, readOnly, env),
+});
+await facadeRun.run({ input: { requestId: 'req-9' }, env: { traceId: 'trace-9' } });
+// [{"v":1},{"requestId":"req-9"},{"traceId":"trace-9"}]
 ```
 
 **Three access tiers:**
-- `getValue`/`setValue` — mutable shared state, tracked in narrative
-- `getArgs()` — frozen business input from `run({ input })`, NOT tracked
-- `getEnv()` — frozen infrastructure context from `run({ env })`, NOT tracked. Returns `ExecutionEnv { signal?, timeoutMs?, traceId? }`. Auto-inherited by subflows. Closed type.
+- `scope.amount = 50000` (ScopeFacade: `getValue`/`setValue`) — mutable shared state, tracked in the narrative
+- `$getArgs()` (ScopeFacade: `getArgs()`) — frozen business input from `run({ input })`, NOT tracked. Its keys are read-only for the run: a stage that writes a state key with the same name throws `Cannot write to readonly input key "requestId"`. A subflow's `inputMapper` result is its input and follows the same rule
+- `$getEnv()` (ScopeFacade: `getEnv()`) — frozen infrastructure context from `run({ env })`, NOT tracked. Returns `ExecutionEnv { signal?, timeoutMs?, traceId? }`. Auto-inherited by subflows. Closed type
 
 ### Executor
 
 ```typescript
-const executor = new FlowChartExecutor(chart);
-// With options (preferred over positional params):
-const executor = new FlowChartExecutor(chart, { scopeFactory: myFactory });
-await executor.run({ input: data, env: { traceId: 'req-123' } });
-
-executor.attachScopeRecorder(recorder) // plug scope observer
-executor.getNarrativeEntries()           // combined flow + data narrative
-executor.getNarrativeEntries()    // structured entries with type/depth/stageName/stageId
-executor.getNarrativeEntries()       // flow-only (no data ops)
-executor.getSnapshot()            // full memory state (includes recorder snapshots)
-executor.attachFlowRecorder(r)    // plug flow observer
-executor.setRedactionPolicy({})   // PII protection
-
-// Pause/Resume — human-in-the-loop
-executor.isPaused()               // true if last run paused
-executor.getCheckpoint()          // JSON-safe checkpoint (store in Redis/Postgres/etc.)
-executor.resume(checkpoint, input) // continue from checkpoint with human's answer
+import { flowChart, FlowChartExecutor, MetricRecorder, NarrativeFlowRecorder } from 'footprintjs';
+
+const chart = flowChart<{ n: number }>('One', (scope) => { scope.n = scope.$getArgs<{ x: number }>().x; }, 'one')
+  .addFunction('Two', (scope) => { scope.n = scope.n + 1; }, 'two')
+  .build();
+
+// With options (preferred over positional params): scopeFactory, readTracking, writeTracking, commitValues, …
+const executor = new FlowChartExecutor(chart, { readTracking: 'full' });
+executor.enableNarrative();                                // before run() — the narrative is off by default
+executor.attachScopeRecorder(new MetricRecorder());        // plug scope observer
+executor.attachFlowRecorder(new NarrativeFlowRecorder());  // plug flow observer
+executor.setRedactionPolicy({ keys: ['secret'] });         // PII protection
+
+await executor.run({ input: { x: 1 }, env: { traceId: 'req-123' } });
+
+// CombinedNarrativeEntry[] — combined flow + data narrative
+console.log(executor.getNarrativeEntries().length);
+// 5
+// flow-only (no data ops): drop the read/write steps
+console.log(JSON.stringify(executor.getNarrativeEntries().filter((e) => e.type !== 'step').map((e) => e.text)));
+// ["Stage 1: The process began with One.","Stage 2: Next, it moved on to Two."]
+// full memory state (includes recorder snapshots)
+console.log(JSON.stringify(Object.keys(executor.getSnapshot())));
+// ["sharedState","executionTree","initialState","commitLog","commitValues","writeProvenance","runId","recorders"]
+
+// Pause/Resume — human-in-the-loop (next section)
+// executor.isPaused()                // true if last run paused
+// executor.getCheckpoint()           // JSON-safe checkpoint (store in Redis/Postgres/etc.)
+// executor.resume(checkpoint, input) // continue from checkpoint with human's answer
 ```
 
+`getNarrativeEntries()` returns entries (`type`, `text`, `depth`, `stageName`, `stageId`, …), not strings: `.map((e) => e.text)` for plain lines. One executor runs one execution at a time — create one per concurrent run.
+
 ### Pause/Resume (Human-in-the-Loop)
 
 ```typescript
 import { flowChart, FlowChartExecutor } from 'footprintjs';
 import type { PausableHandler } from 'footprintjs';
 
+interface MyState {
+  amount: number;
+  approved?: boolean;
+  done?: boolean;
+}
+
 const handler: PausableHandler<MyState> = {
   execute: async (scope) => {
     // Return data = pause. Return nothing = continue.
     return { question: `Approve $${scope.amount}?` };
   },
   resume: async (scope, input) => {
-    scope.approved = input.approved;
+    scope.approved = (input as { approved: boolean }).approved;
   },
 };
 
 // Pausable root stage (single-stage subflows):
-const chart = flowChart<MyState>('Approve', handler, 'approve').build();
+const single = flowChart<MyState>('Approve', handler, 'approve').build();
 
 // Or chained after other stages:
-const chart2 = flowChart<MyState>('Seed', seedFn, 'seed')
+const chart = flowChart<MyState>('Seed', (scope) => { scope.amount = 500; }, 'seed')
   .addPausableFunction('Approve', handler, 'approve')
-  .addFunction('Process', processFn, 'process')
+  .addFunction('Process', (scope) => { scope.done = scope.approved === true; }, 'process')
   .build();
 
 const executor = new FlowChartExecutor(chart);
+executor.enableNarrative();
 await executor.run();
+console.log(executor.isPaused());
+// true
 
 if (executor.isPaused()) {
-  const checkpoint = executor.getCheckpoint(); // JSON-safe, store anywhere
+  const checkpoint = executor.getCheckpoint()!; // JSON-safe, store anywhere
+  console.log(checkpoint.pausedStageId, JSON.stringify(checkpoint.pauseData));
+  // approve {"question":"Approve $500?"}
+  const stored = JSON.stringify(checkpoint);
   // Later (hours, different server):
-  await executor.resume(checkpoint, { approved: true });
+  await executor.resume(JSON.parse(stored), { approved: true });
 }
+console.log(executor.isPaused(), JSON.stringify(executor.getSnapshot().sharedState));
+// false {"amount":500,"approved":true,"done":true}
+console.log(executor.getNarrativeEntries().filter((e) => e.type === 'pause' || e.type === 'resume').map((e) => e.text));
+// [
+//   'Execution paused at Approve.',
+//   'Execution resumed at Approve with input.'
+// ]
+void single;
 ```
 
 - `execute` returns data → pauses. Returns void → continues normally (conditional pause).
-- Checkpoint is JSON-serializable — no functions, no class instances.
-- `resume()` reuses the execution runtime — narrative, metrics, execution tree all accumulate.
-- A resume re-enters ONCE, then the run is the chart as built: a `loopTo` back to the paused stage runs that stage again (it pauses again — a re-ask), a loop reaches its head even from inside a subflow, and the next pass through a subflow mount is a fresh entry (its inputMapper runs). A pause several subflows deep does not re-run the outer subflows' earlier stages, and a subflow mounted as a decider/selector branch or a fork child hands back to its parent's continuation (the decider's `next`, the fork's join). (Since 9.28.0.)
+- Checkpoint is JSON-serializable — no functions, no class instances. A fresh executor resumes it too (`new FlowChartExecutor(chart).resume(JSON.parse(stored), input)`).
+- `resume()` on the SAME executor reuses its runtime — narrative, metrics, execution tree all accumulate; a fresh executor seeds a new runtime from `checkpoint.sharedState`.
+- A resume re-enters ONCE, then the run is the chart as built: a `loopTo` back to the paused stage runs that stage again (it pauses again — a re-ask), and the next pass through a subflow mount is a fresh entry (its inputMapper runs). A pause several subflows deep does not re-run the outer subflows' earlier stages, and a subflow mounted as a decider/selector branch or a fork child hands back to its parent's continuation (the decider's `next`, the fork's join). (Since 9.28.0.)
 - Two parallel siblings that pause in one fan-out are asked IN TURN: the checkpoint asks the first and carries the others in `checkpoint.pendingPauses`; each resume answers one; the join runs after the last. (Since 9.28.0.)
-- Not resumable yet: a pause inside a LAZY subflow or an `addParallelForEach` branch — `resume()` refuses it. A subflow id mounted twice in one chart — `resume()` refuses a pause inside it (give each mount its own id).
-- `FlowRecorder.onPause`/`onResume` and `Recorder.onPause`/`onResume` fire on both observer systems.
+- Not resumable yet: a pause inside a LAZY subflow or an `addParallelForEach` branch — `resume()` rejects (`Cannot resume: stage 'lz/sf-ask' not found in flowchart`). A subflow id mounted twice in one chart — `resume()` refuses a pause inside it (give each mount its own id).
+- `FlowRecorder.onPause`/`onResume` and `ScopeRecorder.onPause`/`onResume` fire on both observer systems.
 
 ### ComposableRunner & Snapshot Navigation
 
+`ComposableRunner<TIn, TOut>` is the interface for a runner that exposes its internal chart so a parent can mount it as a subflow: `toFlowChart()` and `run(input, options?)`.
+
 ```typescript
+import { flowChart, FlowChartExecutor, getSubtreeSnapshot, listSubflowPaths } from 'footprintjs';
 import type { ComposableRunner } from 'footprintjs';
-import { getSubtreeSnapshot, listSubflowPaths } from 'footprintjs';
 
-const subtree = getSubtreeSnapshot(snapshot, 'sf-payment');
-listSubflowPaths(snapshot); // ['sf-payment', 'sf-outer/sf-inner']
+class Doubler implements ComposableRunner<number, number> {
+  toFlowChart() {
+    return flowChart<{ out?: number }>('Double', (scope) => { scope.out = scope.$getArgs<{ n: number }>().n * 2; }, 'double').build();
+  }
+  async run(input: number): Promise<number> {
+    const executor = new FlowChartExecutor(this.toFlowChart());
+    await executor.run({ input: { n: input } });
+    return (executor.getSnapshot().sharedState as { out: number }).out;
+  }
+}
+
+const outer = flowChart<{ out?: number }>('Outer', () => {}, 'outer')
+  .addSubFlowChartNext('sf-doubler', new Doubler().toFlowChart(), 'Doubler', {
+    inputMapper: () => ({ n: 21 }),
+    outputMapper: (sub: { out?: number }) => ({ out: sub.out }),
+  })
+  .build();
+const root = flowChart<{ out?: number }>('Root', () => {}, 'root')
+  .addSubFlowChartNext('sf-outer', outer, 'OuterMount', { outputMapper: (sub: { out?: number }) => ({ out: sub.out }) })
+  .build();
+
+const executor = new FlowChartExecutor(root);
+await executor.run();
+const snapshot = executor.getSnapshot();
+
+console.log(await new Doubler().run(4));
+// 8
+console.log(listSubflowPaths(snapshot));
+// [ 'sf-outer/sf-doubler', 'sf-outer' ]
+const subtree = getSubtreeSnapshot(snapshot, 'sf-outer/sf-doubler');
+console.log(Object.keys(subtree ?? {}), JSON.stringify(subtree?.sharedState));
+// [
+//   'subflowId',
+//   'executionTree',
+//   'sharedState',
+//   'history',
+//   'initialState',
+//   'narrativeEntries'
+// ] {"n":21,"out":42}
 ```
 
 ## Observer Channels
 
-Four pluggable observer channels — three fire at runtime (Scope, Flow, Emit) and one fires at build time (Structure). All share `{ id, hooks } -> dispatcher -> error isolation -> attach/detach`. A recorder is routed to channels by runtime duck-typing of its `on*` methods. Intentionally NOT unified into one interface — each channel has a distinct invariant set.
+Four pluggable observer channels — three fire at runtime (Scope, Flow, Emit) and one fires at build time (Structure). The runtime channels share `{ id, hooks } -> dispatcher -> error isolation -> attach/detach` (the Structure channel has `attachStructureRecorder` only). `attachCombinedRecorder(r)` routes a recorder to channels by runtime duck-typing of its `on*` methods. Intentionally NOT unified into one interface — each channel has a distinct invariant set.
 
 **Recorder ID contract:**
-- `attachRecorder` is **idempotent by ID** — same ID replaces, different IDs coexist. Prevents accidental double-counting.
+- `attachScopeRecorder` / `attachFlowRecorder` / `attachEmitRecorder` / `attachCombinedRecorder` are **idempotent by ID** — same ID replaces, different IDs coexist. Prevents accidental double-counting.
 - Built-in recorders use auto-increment default IDs (`metrics-1`, `debug-1`, ...) so multiple instances with different configs coexist naturally.
 - Frameworks that auto-attach recorders should use a well-known ID (e.g., `new MetricRecorder('metrics')`) so the consumer can override it by passing the same ID, or add a second instance with `new MetricRecorder()` (gets unique ID).
 
-**Scope Recorder** (data ops — fires DURING stage execution):
-- `onRead`, `onWrite`, `onCommit`, `onError`, `onStageStart`, `onStageEnd`
+```typescript
+import { flowChart, FlowChartExecutor, MetricRecorder, DebugRecorder } from 'footprintjs';
+
+console.log(new MetricRecorder().id, new MetricRecorder().id, new MetricRecorder('metrics').id, new DebugRecorder({ id: 'dbg' }).id);
+// metrics-1 metrics-2 metrics dbg
+
+const executor = new FlowChartExecutor(flowChart<{ a: number }>('One', (scope) => { scope.a = 1; }, 'one').build());
+let first = 0;
+let second = 0;
+executor.attachScopeRecorder({ id: 'same', onWrite: () => { first++; } });
+executor.attachScopeRecorder({ id: 'same', onWrite: () => { second++; } }); // same id: replaces the first
+await executor.run();
+console.log(first, second);
+// 0 1
+```
+
+**Scope Recorder** (data ops — `onStageStart` → `onRead`/`onWrite` DURING the stage function → `onStageEnd` → `onCommit`):
+- `onStageStart`, `onRead`, `onWrite`, `onStageEnd`, `onCommit`, `onError`, `onPause`, `onResume`
 - Built-in: `MetricRecorder`, `DebugRecorder`
 
-**FlowRecorder** (control flow — fires AFTER stage execution):
-- `onStageExecuted` (universal "did this stage run", carries `stageType: 'linear' | 'decider' | 'fork' | 'selector' | 'subflow-mount'`), `onNext`, `onDecision`, `onFork`, `onSelected`, `onSubflowEntry/Exit`, `onSubflowRegistered`, `onLoop`, `onBreak`, `onError`, `onPause`/`onResume`, `onRunStart`/`onRunEnd`, `onRunFailed`
-- All events carry `traversalContext: TraversalContext` (includes per-run `runId`)
+**FlowRecorder** (control flow — fires AFTER the stage's commit):
+- `onStageExecuted` (universal "did this stage run", carries `stageType: 'linear' | 'decider' | 'fork' | 'selector' | 'subflow-mount'`), `onNext`, `onDecision`, `onFork`, `onSelected`, `onSubflowEntry/Exit`, `onSubflowRegistered`, `onLoop`, `onBreak`, `onStageRetry`, `onError`, `onPause`/`onResume`, `onRunStart`/`onRunEnd`, `onRunFailed`
+- Events carry an optional `traversalContext: TraversalContext` (includes per-run `runId`)
 - `onDecision`/`onSelected` carry optional `evidence` from decide()/select()
 - Built-in: 9 strategies (Narrative, Adaptive, Windowed, RLE, Milestone, Progressive, Separate, Manifest, Silent)
 
@@ -225,76 +405,154 @@ Four pluggable observer channels — three fire at runtime (Scope, Flow, Emit) a
 - `onEmit(EmitEvent)` — see the "Emit Channel" section below.
 
 **Structure Recorder** (build-time chart shape — fires SYNCHRONOUSLY during builder operations, NOT runtime):
-- `onStageAdded`, `onEdgeAdded`, `onLoopEdgeAdded`, `onDeciderComplete`, `onSubflowMounted`
-- Attach via options bag — `flowChart('seed', fn, 'seed', { structureRecorders: [rec] })` — or fluent `.attachStructureRecorder(rec)`. MOUNT-ONLY: a builder's recorder sees only that builder's events; subflow internals arrive via the mount event's `subflowSpec` (walk with `walkSubflowSpec` from `footprintjs/trace`). Exported from the main `footprintjs` barrel.
+- `onStageAdded`, `onStageTagged`, `onEdgeAdded`, `onLoopEdgeAdded`, `onDeciderComplete`, `onSubflowMounted`
+- Attach via options bag — `flowChart('seed', fn, 'seed', { structureRecorders: [rec] })` — or fluent `.attachStructureRecorder(rec)`. MOUNT-ONLY: a builder's recorder sees only that builder's events; subflow internals arrive via the mount event's `subflowSpec` (walk with `walkSubflowSpec` from `footprintjs/trace`). The types are exported from the main `footprintjs` barrel.
+
+```typescript
+import { flowChart } from 'footprintjs';
+import type { StructureRecorder, StructureSubflowMountedEvent } from 'footprintjs';
+import { walkSubflowSpec } from 'footprintjs/trace';
+
+const events: string[] = [];
+let mounted: StructureSubflowMountedEvent | undefined;
+const recorder: StructureRecorder = {
+  id: 'structure',
+  onStageAdded: (e) => { events.push(`stage ${e.spec.id}`); },
+  onEdgeAdded: (e) => { events.push(`edge ${e.from} -> ${e.to} (${e.kind})`); },
+  onSubflowMounted: (e) => { events.push(`mounted ${e.subflowId}`); mounted = e; },
+};
+
+const sub = flowChart<object>('SubA', () => {}, 'sub-a').addFunction('SubB', () => {}, 'sub-b').build();
+flowChart<object>('Seed', () => {}, 'seed', { structureRecorders: [recorder] })
+  .addSubFlowChartNext('sf', sub, 'Sub')
+  .build();
+
+console.log(events); // the subflow's own stages (sub-a, sub-b) are NOT reported here
+// [ 'stage seed', 'stage sf', 'edge seed -> sf (next)', 'mounted sf' ]
+for (const item of walkSubflowSpec(mounted!.subflowSpec!, mounted!.subflowPath ?? mounted!.subflowId)) {
+  console.log(item.kind);
+}
+// subflow-start
+// stage
+// edge
+// stage
+```
 
-**CombinedNarrativeRecorder** implements the Scope + Flow + Emit interfaces. Attached via `chart.recorder(narrative())` (fluent) or `executor.attachCombinedRecorder(narrative())` / `executor.enableNarrative()` at runtime.
+**CombinedNarrativeRecorder** implements the Scope + Flow + Emit interfaces. `executor.enableNarrative()` installs it (read it with `executor.getNarrativeEntries()`); `chart.recorder(narrative())` attaches a `narrative()` instance for a one-shot run, and `executor.attachCombinedRecorder(narrative())` works too — read either back from the instance (`recorder.getEntries()`); the executor's own `getNarrativeEntries()` belongs to `enableNarrative()`. It is not exported as a class.
 
 ## Event Ordering
 
 ```
-0. FlowRecorder.onRunStart      — once per executor.run(), carries the run input
-1. Recorder.onStageStart        — stage begins
-2. Recorder.onRead/onWrite      — DURING execution (buffered per-stage)
-3. Recorder.onCommit            — transaction flush
-4. Recorder.onStageEnd          — stage completes
-5. FlowRecorder.onStageExecuted — universal "stage ran" (stageType discriminator); CombinedNarrativeRecorder flushes buffered ops for LINEAR stages here
-6. FlowRecorder.onNext/onDecision/onFork/onSelected — control flow continues (non-linear onStageExecuted fires AFTER its specialized event)
-7. FlowRecorder.onRunEnd (clean) or onRunFailed (error) — once per run, closes the boundary symmetrically
+0. FlowRecorder.onRunStart       — once per executor.run(), before any stage; event.payload = the run input
+   Per stage, ScopeRecorder events:
+1. Recorder.onStageStart         — stage begins
+2. Recorder.onRead/onWrite       — DURING execution, before the commit
+3. Recorder.onStageEnd           — the stage function returned
+4. Recorder.onCommit             — transaction flush
+   Then FlowRecorder events, by stage kind:
+5. linear stage    onStageExecuted → onNext
+   decider         onDecision → onStageExecuted
+   selector        onSelected → onStageExecuted → onFork
+   fork parent     onStageExecuted → onFork → onStageExecuted (stageType 'fork')
+   subflow mount   onNext → onSubflowEntry → onStageExecuted (stageType 'subflow-mount')
+                   → the subflow's own stages → onSubflowExit
+6. FlowRecorder.onRunEnd (clean; event.payload = the chart's return value) or onRunFailed (error; event.structuredError) — once per run, closes the boundary symmetrically
 ```
 
+`CombinedNarrativeRecorder` flushes a stage's buffered reads and writes when that stage's flow event arrives: `onStageExecuted` for LINEAR stages, `onDecision` / `onSelected` / `onFork` / `onSubflowEntry` for the others.
+
 ## Execution Tracing (`footprintjs/trace`)
 
 Every stage execution gets a unique `runtimeStageId` — the universal key that links recorder events, commit log entries, and execution tree nodes.
 
 **When to use:** Debugging (which stage set a value to something unexpected?), audit trails (trace every write to its source stage), custom recorders (correlate events with specific execution steps), quality trace backtracking (walk backwards to find where data quality dropped).
 
-**Format:** `[subflowPath/]stageId#executionIndex`
+**Format:** `[subflowPath/]stageId#executionIndex` — the index starts at 0 and counts every stage execution across the run (a loop revisits the same stageId with a higher index):
 
 ```
-seed#0                              — root stage
-call-llm#5                          — 5th execution step
-sf-tools/execute-tool-calls#8       — subflow stage
-call-llm#9                          — same stageId, different execution (loop)
+seed#0                              — root stage, the first execution
+tick#6                              — the seventh execution
+sf-outer/sf-inner/inner-end#5       — a stage inside a nested subflow
+tick#9                              — same stageId, different execution (loop)
 ```
 
-**The commitLog:** An ordered array of `CommitBundle` — one per stage commit, recording what each stage wrote to shared state. Get it from `executor.getSnapshot().commitLog`.
+**The commitLog:** An ordered array of `CommitBundle` — one per stage commit, recording what each stage wrote to shared state. Get it from `executor.getSnapshot().commitLog`. A subflow mount appears twice in the root log under one runtimeStageId; the subflow's own stage commits are in its subtree history (`getSubtreeSnapshot(snapshot, path).history`).
 
 ```typescript
-import { parseRuntimeStageId, findLastWriter, findCommit } from 'footprintjs/trace';
+import { flowChart, FlowChartExecutor, decide, getSubtreeSnapshot } from 'footprintjs';
+import { parseRuntimeStageId, buildRuntimeStageId, splitStageId, findLastWriter, findCommit, findCommits, isCommitBundle } from 'footprintjs/trace';
 
-// Parse a runtimeStageId into components
-parseRuntimeStageId('sf-tools/execute-tool-calls#8');
-// → { stageId: 'execute-tool-calls', executionIndex: 8, subflowPath: 'sf-tools' }
+const inner = flowChart<{ v: number; t?: number; out?: number }>('InnerStart', (scope) => { scope.t = scope.v + 1; }, 'inner-start')
+  .addFunction('InnerEnd', (scope) => { scope.out = (scope.t ?? 0) * 2; }, 'inner-end')
+  .build();
+const outer = flowChart<{ n: number; w?: number; out?: number }>('OuterStart', (scope) => { scope.w = scope.n; }, 'outer-start')
+  .addSubFlowChartNext('sf-inner', inner, 'Inner', {
+    inputMapper: (parent: { w?: number }) => ({ v: parent.w }),
+    outputMapper: (sub: { out?: number }) => ({ out: sub.out }),
+  })
+  .build();
+const chart = flowChart<{ n: number; count: number }>('Seed', (scope) => { scope.n = 1; scope.count = 0; }, 'seed')
+  .addSubFlowChartNext('sf-outer', outer, 'Outer', {
+    inputMapper: (parent: { n: number }) => ({ n: parent.n }),
+    outputMapper: (sub: { out?: number }) => ({ out: sub.out }),
+  })
+  .addFunction('Tick', (scope) => { scope.count = scope.count + 1; }, 'tick')
+  .addDeciderFunction('Route', (scope) => decide(scope, [
+      { when: { count: { lt: 2 } }, then: 'again', label: 'under 2' },
+    ], 'done'), 'route')
+    .addFunctionBranch('again', 'Again', () => {})
+    .loopTo('tick')
+    .addFunctionBranch('done', 'Done', () => {})
+    .end()
+  .build();
+
+const executor = new FlowChartExecutor(chart);
+await executor.run();
 
 // Get the commit log after execution
 const snapshot = executor.getSnapshot();
 const commitLog = snapshot.commitLog; // CommitBundle[]
+console.log(commitLog.map((bundle) => bundle.runtimeStageId).join(' '));
+// seed#0 sf-outer#1 sf-outer#1 tick#6 route#7 again#8 tick#9 route#10 done#11
+
+// A subflow's own stage commits live in its subtree history, not in the root log
+const innerHistory = (getSubtreeSnapshot(snapshot, 'sf-outer/sf-inner')?.history ?? []).filter(isCommitBundle);
+console.log(innerHistory.map((bundle) => bundle.runtimeStageId).join(' '));
+//  sf-outer/sf-inner/inner-start#4 sf-outer/sf-inner/inner-end#5
+
+// Parse a runtimeStageId into components
+console.log(JSON.stringify(parseRuntimeStageId(innerHistory[1].runtimeStageId)));
+// {"stageId":"inner-start","executionIndex":4,"subflowPath":"sf-outer/sf-inner"}
+console.log(buildRuntimeStageId('inner-end', 5, 'sf-outer/sf-inner'), JSON.stringify(splitStageId('sf-outer/sf-inner/inner-end')));
+// sf-outer/sf-inner/inner-end#5 {"localStageId":"inner-end","subflowPath":"sf-outer/sf-inner"}
 
-// Backtrack: who last wrote 'systemPrompt' before commitLog array index 8?
+// Backtrack: who last wrote 'count' before commitLog array index 6?
 // beforeIdx is the CommitBundle.idx (array position), NOT the executionIndex from runtimeStageId.
-const writer = findLastWriter(commitLog, 'systemPrompt', 8);
-// → CommitBundle | undefined (has .stage, .stageId, .runtimeStageId, .trace, .overwrite, .updates)
+const writer = findLastWriter(commitLog, 'count', 6);
+console.log(writer?.runtimeStageId, writer?.idx, JSON.stringify(writer?.trace));
+// tick#6 3 [{"path":"count","verb":"set"}]
+// → CommitBundle | undefined (has .idx, .stage, .stageId, .runtimeStageId, .trace, .overwrite, .updates, .redactedPaths)
 
 // Find by stageId: use findCommit when you know the stage.
 // Use findLastWriter when you know the key but not which stage wrote it.
-const llmCommit = findCommit(commitLog, 'call-llm', 'adapterRawResponse');
+console.log(findCommit(commitLog, 'tick', 'count')?.runtimeStageId, findCommits(commitLog, 'tick').map((bundle) => bundle.runtimeStageId));
+// tick#6 [ 'tick#6', 'tick#9' ]
 ```
 
-**Exports from `footprintjs/trace`:**
+**Exports from `footprintjs/trace`** (the door has many more — causal chains, slices, time travel, honesty codes, `ControlDepRecorder`, `QualityRecorder`; see `src/lib/slice/README.md` and `src/lib/time-travel/README.md`):
 
 | Export | Returns | Use |
 |--------|---------|-----|
 | `buildRuntimeStageId(stageId, idx, subflowPath?)` | `string` | Construct an ID from components |
-| `parseRuntimeStageId(id)` | `{ stageId, executionIndex, subflowPath }` | Decompose an ID |
-| `findCommit(commitLog, stageId, key?)` | `CommitBundle \| undefined` | Find first commit by stageId |
+| `parseRuntimeStageId(id)` | `{ stageId, executionIndex, subflowPath }` (`subflowPath` is `undefined` at top level) | Decompose an ID |
+| `findCommit(commitLog, stageId, key?)` | `CommitBundle \| undefined` | Find the first commit by stageId (that wrote `key`, if given) |
 | `findCommits(commitLog, stageId)` | `CommitBundle[]` | Find all commits by stageId |
 | `findLastWriter(commitLog, key, beforeIdx?)` | `CommitBundle \| undefined` | Search backwards for who wrote a key |
 | `splitStageId(prefixedId)` | `{ localStageId, subflowPath }` | Decompose a bare prefixed id (`spec.id`, `CommitBundle.stageId`) |
 | `walkSubflowSpec(spec, subflowPath, opts?)` | `Generator<WalkerItem>` | Walk a subflow spec from `StructureSubflowMountedEvent.subflowSpec` |
-| `KeyedStore<T>` | class (v5 primary) | Storage shelf for 1:1 Map keyed by runtimeStageId (`set`/`get`/`aggregate`/`accumulate`/`filterByKeys`) |
-| `SequenceStore<T>` | class (v5 primary) | Storage shelf for 1:N ordered entries (`push`/`getByKey`/`getEntryRanges()` for O(1) time-travel/`getEntriesUpTo`) |
-| `BoundaryStateStore<TState>` | class (v5 primary) | Storage shelf for transient bracket-scoped state — live state DURING a `[start, stop]` interval; clears on stop. O(1) reads via `get` / `hasActive` / `activeCount`; lifecycle via `start` / `update` / `stop`. |
+| `KeyedStore<T>` | class (since 5.0.0) | Storage shelf for 1:1 Map keyed by runtimeStageId (`set`/`get`/`aggregate`/`accumulate`/`filterByKeys`) |
+| `SequenceStore<T>` | class (since 5.0.0) | Storage shelf for 1:N ordered entries (`push`/`getByKey`/`getEntryRanges()` for O(1) time-travel/`getEntriesUpTo`) |
+| `BoundaryStateStore<TState>` | class (since 5.0.0) | Storage shelf for transient bracket-scoped state — live state DURING a `[start, stop]` interval; clears on stop. O(1) reads via `get` / `hasActive` / `activeCount`; lifecycle via `start` / `update` / `stop`. |
 | `KeyedRecorder<T>` / `SequenceRecorder<T>` / `BoundaryStateTracker<TState>` | abstract bases — **REMOVED in 7.0.0** | Gone — no inheritance path remains. Superseded by the `*Store` classes above: own a store as a field and implement the channel interface yourself. |
 | `CommitRangeIndex<TLabel>` | class | Interval index over commit indices (`open`/`close`/`enclosing`/`overlapping`) |
 | `topologyRecorder()` / `TopologyRecorder` | factory / class | Live composition graph for streaming consumers (subflow nodes + control-flow edges) |
@@ -302,7 +560,7 @@ const llmCommit = findCommit(commitLog, 'call-llm', 'adapterRawResponse');
 
 ### TopologyRecorder — Composition Graph for Streaming Consumers
 
-**One-liner:** reconstructs a live, queryable mini-flowchart of what your run actually traced, built from the 3 primitive recorder channels during traversal.
+**One-liner:** reconstructs a live, queryable mini-flowchart of what your run actually traced, built from FlowRecorder events (`onSubflowEntry`/`onSubflowExit`, `onFork`, `onDecision`, `onLoop`) during traversal.
 
 **Mental model:**
 
@@ -310,22 +568,21 @@ const llmCommit = findCommit(commitLog, 'call-llm', 'adapterRawResponse');
 flowChart() builder      →  STATIC flowchart (design-time definition)
                                        │
                                        ▼ executor runs it
-                         Traversal emits events on 3 channels:
-                            Recorder · FlowRecorder · EmitRecorder
+                         Traversal emits FlowRecorder events
                                        │
                                        ▼ TopologyRecorder listens
                          DYNAMIC flowchart (runtime shape):
                             Nodes = composition points
                                (subflow / fork-branch / decision-branch)
                             Edges = transitions
-                               (next / fork / decision / loop)
+                               (next / fork-branch / decision-branch / loop-iteration)
                             Queryable any moment — during or after run
 ```
 
 **What it IS:**
-- Live composition graph derived from 3 primitive channels
+- Live composition graph derived from flow events
 - Each node = one composition-significant moment (subflow entered, fork child, decision chosen)
-- Each edge = a control-flow transition, timestamped with `runtimeStageId`
+- Each edge = a control-flow transition, stamped with the `runtimeStageId` it happened at (`edge.at`)
 - Works identically during or after a run
 
 **What it ISN'T:**
@@ -338,17 +595,62 @@ flowChart() builder      →  STATIC flowchart (design-time definition)
 Fills the gap between "post-run snapshot (full tree available)" and "live event stream (only point observations)." Attach once; query `getTopology()` anytime during or after a run.
 
 ```typescript
+import { flowChart, FlowChartExecutor, decide } from 'footprintjs';
 import { topologyRecorder } from 'footprintjs/trace';
 
+const agent = flowChart<{ count: number }>('Start', (scope) => { scope.count = 0; }, 'start')
+  .addFunction('Tick', (scope) => { scope.count = scope.count + 1; }, 'tick')
+  .addDeciderFunction('Check', (scope) => decide(scope, [
+      { when: { count: { lt: 2 } }, then: 'again', label: 'under 2' },
+    ], 'done'), 'check')
+    .addFunctionBranch('again', 'Again', () => {})
+    .loopTo('tick')
+    .addFunctionBranch('done', 'Done', () => {})
+    .end()
+  .build();
+const fanOut = flowChart<object>('Host', () => {}, 'host')
+  .addListOfFunction([
+    { id: 'x', name: 'X', fn: () => {} },
+    { id: 'y', name: 'Y', fn: () => {} },
+  ])
+  .build();
+const chart = flowChart<object>('Seed', () => {}, 'seed')
+  .addSubFlowChartNext('sf-agent', agent, 'Agent')
+  .addSubFlowChartNext('sf-fanout', fanOut, 'FanOut')
+  .build();
+
+const executor = new FlowChartExecutor(chart);
 const topo = topologyRecorder();
 executor.attachCombinedRecorder(topo); // auto-routes to FlowRecorder channel
 
-await executor.run({ input });
+await executor.run();
 
 const { nodes, edges, activeNodeId, rootId } = topo.getTopology();
-topo.getSubflowNodes();          // agent-centric view
-topo.getByKind('fork-branch');   // all parallel branches
-topo.getParallelSiblings(id);    // siblings of a parallel branch
+console.log(nodes.map((node) => `${node.kind} ${node.id}`));
+// [
+//   'subflow sf-agent',
+//   'decision-branch decision-sf-agent/check#4-sf-agent/Again',
+//   'decision-branch decision-sf-agent/check#7-sf-agent/Done',
+//   'subflow sf-fanout',
+//   'fork-branch fork-sf-fanout/host#10-0-sf-fanout/X',
+//   'fork-branch fork-sf-fanout/host#10-1-sf-fanout/Y'
+// ]
+console.log(edges.map((edge) => `${edge.kind}: ${edge.from} -> ${edge.to}`));
+// [
+//   'decision-branch: sf-agent -> decision-sf-agent/check#4-sf-agent/Again',
+//   'loop-iteration: sf-agent -> sf-agent',
+//   'decision-branch: sf-agent -> decision-sf-agent/check#7-sf-agent/Done',
+//   'next: sf-agent -> sf-fanout',
+//   'fork-branch: sf-fanout -> fork-sf-fanout/host#10-0-sf-fanout/X',
+//   'fork-branch: sf-fanout -> fork-sf-fanout/host#10-1-sf-fanout/Y'
+// ]
+console.log(activeNodeId, rootId);
+// null sf-agent
+console.log(topo.getSubflowNodes().map((node) => node.id));   // agent-centric view
+// [ 'sf-agent', 'sf-fanout' ]
+console.log(topo.getByKind('fork-branch').map((node) => node.name));   // all parallel branches
+// [ 'sf-fanout/X', 'sf-fanout/Y' ]
+// topo.getParallelSiblings(id) — siblings of a parallel branch; topo.getChildren(id) — direct children
 ```
 
 **Three node kinds — complete composition coverage:**
@@ -359,16 +661,16 @@ topo.getParallelSiblings(id);    // siblings of a parallel branch
 | `fork-branch` | `onFork` (synthesized one per child) | One branch of a parallel split — works for plain stages AND subflows |
 | `decision-branch` | `onDecision` (synthesized for chosen) | The chosen branch of a conditional |
 
-When a fork-branch or decision-branch target is also a subflow, the subsequent `onSubflowEntry` creates a subflow CHILD of the synthetic node. Layered shape preserves both "who branched" and "what the branch ran."
+When a fork-branch or decision-branch target is also a subflow, the subsequent `onSubflowEntry` creates a subflow CHILD of the synthetic node (verified for a fork/decider at the top level of a run; inside another subflow the branch names carry the subflow path prefix and the subflow node attaches to the enclosing subflow instead). Layered shape preserves both "who branched" and "what the branch ran."
 
-**Edges:** one per control-flow transition. `edge.kind ∈ 'next' | 'fork-branch' | 'decision-branch' | 'loop-iteration'`. Each carries `at: runtimeStageId` for time correlation.
+**Edges:** `edge.kind ∈ 'next' | 'fork-branch' | 'decision-branch' | 'loop-iteration'`. Each carries `at: runtimeStageId` for time correlation. Fork, decision and loop edges are recorded only while a subflow is active — a fork or decision at the top level of the run still creates its nodes, but no edge — and a `loopTo` outside any subflow adds nothing.
 
 **Correlation rules:**
 - `onFork({ parent, children })` → N `fork-branch` nodes synthesized up-front; subsequent matching `onSubflowEntry` nests under the right fork-branch
 - `onDecision({ chosen })` → `decision-branch` node synthesized up-front; matching `onSubflowEntry` nests under it
-- Pending correlation clears on `onSubflowExit` so state doesn't leak across scopes
+- A pending decision clears on `onSubflowExit` so it can't match an unrelated subflow later; pending fork-sibling entries survive scope exits (a sibling's inner subflow may exit before the next sibling enters) and clear on the next `onFork` or on a match
 - `onLoop` → self-edge on the currently-active subflow (synthetic nodes don't participate)
-- Re-entry of same `subflowId` (loop body) disambiguates via `id#n` suffix
+- Re-entry of same `subflowId` (loop body) disambiguates via `id#n` suffix (`sf-body`, `sf-body#1`)
 
 **What it does NOT track:** plain sequential stages. Use `MetricRecorder` / `StageContext` for per-stage data. Topology is a graph of control-flow branching, not a full execution tree.
 
@@ -399,7 +701,7 @@ Each chart execution → 2 boundaries:
 - **Root** — `onRunStart` / `onRunEnd` fire ONCE per `executor.run()`. `subflowId: '__root__'`, `depth: 0`, `isRoot: true`.
 - **Subflow** — `onSubflowEntry` / `onSubflowExit` fire once per mounted subflow. Nested under root in the path tree (`['__root__', 'sf-x']`, depth 1+).
 
-Loop re-entry produces distinct pairs because the parent stage's executionIndex increments.
+Loop re-entry produces distinct pairs because the parent stage's executionIndex increments (`sf-body#2`, `sf-body#7`).
 
 **What it IS:**
 - composes `SequenceStore<InOutEntry>` — flat ordered list + per-`runtimeStageId` index
@@ -413,18 +715,33 @@ Loop re-entry produces distinct pairs because the parent stage's executionIndex
 - Not agent-specific — domain libraries (e.g. agentfootprint) compose it; footprintjs owns it
 
 ```typescript
+import { flowChart, FlowChartExecutor } from 'footprintjs';
 import { inOutRecorder, ROOT_SUBFLOW_ID } from 'footprintjs/trace';
 
+const sub = flowChart<{ q: number; r?: number }>('Double', (scope) => { scope.r = scope.q * 2; }, 'double').build();
+const chart = flowChart<{ n: number; out?: number }>('Seed', (scope) => { scope.n = 21; }, 'seed')
+  .addSubFlowChartNext('sf-double', sub, 'Doubler', {
+    inputMapper: (parent: { n: number }) => ({ q: parent.n }),
+    outputMapper: (out: { r?: number }) => ({ out: out.r }),
+  })
+  .build();
+
+const executor = new FlowChartExecutor(chart);
 const inOut = inOutRecorder();
 executor.attachCombinedRecorder(inOut);
 
-await executor.run({ input });
-
-inOut.getSteps();                    // entry boundaries (timeline; root is first step)
-inOut.getBoundary(runtimeStageId);   // { entry, exit } pair for one execution
-inOut.getRootBoundary();             // { entry, exit } for the top-level run
-inOut.getBoundaries();               // flat list (entry+exit interleaved)
-inOut.getEntryRanges();              // O(1) per-step range index for time-travel
+await executor.run({ input: { start: true } });
+
+console.log(inOut.getSteps().map((step) => step.runtimeStageId), ROOT_SUBFLOW_ID); // entry boundaries (timeline; root is first step)
+// [ '__root__#0', 'sf-double#1' ] __root__
+const { entry, exit } = inOut.getBoundary('sf-double#1')!;    // { entry, exit } pair for one execution
+console.log(JSON.stringify(entry?.payload), JSON.stringify(exit?.payload));
+// {"q":21} {"q":21,"r":42}
+const rootBoundary = inOut.getRootBoundary();                  // { entry, exit } for the top-level run
+console.log(JSON.stringify(rootBoundary?.entry?.payload), rootBoundary?.exit?.payload);
+// {"start":true} undefined
+// inOut.getBoundaries()   — flat list (entry+exit interleaved)
+// inOut.getEntryRanges()  — O(1) per-step range index for time-travel
 ```
 
 **`InOutEntry` shape:**
@@ -442,7 +759,7 @@ inOut.getEntryRanges();              // O(1) per-step range index for time-trave
 | `payload` | `entry`: `inputMapper` result (subflow) or `run({input})` (root); `exit`: shared state at exit (subflow) or chart return value (root) |
 | `isRoot` | True only for the synthetic root pair from `onRunStart` / `onRunEnd` |
 
-**Pause semantics:** when a stage pauses inside a subflow, the engine re-throws without firing `onSubflowExit` (or `onRunEnd`). The chart has an `entry` with no matching `exit` until resume completes. `getBoundary()` returns `{ entry, exit: undefined }` in that case.
+**Pause semantics:** when a stage pauses inside a subflow, the engine re-throws without firing `onSubflowExit` (or `onRunEnd`). The chart has an `entry` with no matching `exit`: `getBoundary()` returns `{ entry, exit: undefined }`. Resuming on the same executor appends a second root pair and a fresh pair for the re-entered subflow (new runtimeStageId) — the first leg's dangling `entry` stays as recorded.
 
 **Engine events:** `FlowRecorder.onRunStart(event)` and `onRunEnd(event)` carry `event.payload` (the run's input or output). Fire ONCE per top-level `executor.run()` — not for subflow traversers (those fire `onSubflowEntry`/`onSubflowExit` instead). Available on the `IControlFlowNarrative` interface and the `FlowRecorderDispatcher`.
 
@@ -450,7 +767,7 @@ inOut.getEntryRanges();              // O(1) per-step range index for time-trave
 
 Example: [examples/runtime-features/flow-recorder/07-inout.ts](examples/runtime-features/flow-recorder/07-inout.ts)
 
-**Three recorder STORAGE PRIMITIVES (v5 primary API)** — "one purpose per recorder": a store is storage ONLY. You own one as a field and implement the channel interface (`ScopeRecorder` / `FlowRecorder` / `EmitRecorder` / `CombinedRecorder`) yourself, delegating storage to the store. The abstract base classes (`KeyedRecorder` / `SequenceRecorder` / `BoundaryStateTracker`) were REMOVED in 7.0.0 — composition is the only model. Choose a store by data shape and durability:
+**Three recorder STORAGE PRIMITIVES (since 5.0.0)** — "one purpose per recorder": a store is storage ONLY. You own one as a field and implement the channel interface (`ScopeRecorder` / `FlowRecorder` / `EmitRecorder` / `CombinedRecorder`) yourself, delegating storage to the store. The abstract base classes (`KeyedRecorder` / `SequenceRecorder` / `BoundaryStateTracker`) were REMOVED in 7.0.0 — composition is the only model. Choose a store by data shape and durability:
 
 | Store | Relationship | Time scope | Use When |
 |------------|-------------|------------|----------|
@@ -459,14 +776,18 @@ Example: [examples/runtime-features/flow-recorder/07-inout.ts](examples/runtime-
 | `BoundaryStateStore<TState>` | Map\<key, TState\> active bracket | transient — clears on stop | Live state DURING a `[start, stop]` bracket (LLM stream partial, tool args streaming) |
 
 ```typescript
+import { flowChart, FlowChartExecutor } from 'footprintjs';
+import type { FlowRecorder, EmitRecorder, EmitEvent, FlowStageEvent, FlowDecisionEvent } from 'footprintjs';
 import { KeyedStore, SequenceStore, BoundaryStateStore } from 'footprintjs/trace';
-import type { FlowRecorder, EmitRecorder } from 'footprintjs';
 
 // KeyedStore: one entry per step. Own the store; implement the channel.
 class TokenRecorder implements FlowRecorder {
   readonly id = 'tokens';
   private store = new KeyedStore<{ tokens: number }>();
-  onStageExecuted(e) { this.store.set(e.traversalContext.runtimeStageId, { tokens: 0 }); }
+  onStageExecuted(e: FlowStageEvent) {
+    const rid = e.traversalContext?.runtimeStageId;
+    if (rid) this.store.set(rid, { tokens: 10 });
+  }
   byStep(rid: string) { return this.store.get(rid); }                       // Translate: per-step value
   total() { return this.store.aggregate((sum, e) => sum + e.tokens, 0); }   // Aggregate: grand total
   upTo(keys: ReadonlySet<string>) {                                          // Accumulate: up to slider
@@ -478,7 +799,9 @@ class TokenRecorder implements FlowRecorder {
 class AuditRecorder implements FlowRecorder {
   readonly id = 'audit';
   private store = new SequenceStore<{ runtimeStageId: string; type: string }>();
-  onDecision(e) { this.store.push({ runtimeStageId: e.traversalContext?.runtimeStageId, type: 'decision' }); }
+  onDecision(e: FlowDecisionEvent) {
+    this.store.push({ runtimeStageId: e.traversalContext?.runtimeStageId ?? '', type: 'decision' });
+  }
   forStep(rid: string) { return this.store.getByKey(rid); }                  // Translate: per-step entries
   upTo(keys: ReadonlySet<string>) { return this.store.getEntriesUpTo(keys); } // Progressive: up to slider
   ranges() { return this.store.getEntryRanges(); }                           // Range index: O(1) slider sync
@@ -488,9 +811,10 @@ class AuditRecorder implements FlowRecorder {
 class LiveLLMTracker implements EmitRecorder {
   readonly id = 'live-llm';
   private store = new BoundaryStateStore<{ partial: string; tokens: number }>();
-  onEmit(e) {
+  onEmit(e: EmitEvent) {
+    const payload = e.payload as { content?: string };
     if (e.name === 'llm.start') this.store.start(e.runtimeStageId, { partial: '', tokens: 0 });
-    if (e.name === 'llm.token') this.store.update(e.runtimeStageId, s => ({ partial: s.partial + e.payload.content, tokens: s.tokens + 1 }));
+    if (e.name === 'llm.token') this.store.update(e.runtimeStageId, (s) => ({ partial: s.partial + (payload.content ?? ''), tokens: s.tokens + 1 }));
     if (e.name === 'llm.end')   this.store.stop(e.runtimeStageId);
   }
   isInFlight() { return this.store.hasActive; }                              // O(1) — live read
@@ -498,33 +822,81 @@ class LiveLLMTracker implements EmitRecorder {
   concurrent() { return this.store.activeCount; }                            // O(1) — how many concurrent boundaries
 }
 // Lifecycle: call store.clear() between runs; dev-mode warns on leaked-stop bugs.
+
+const tokens = new TokenRecorder();
+const audit = new AuditRecorder();
+const live = new LiveLLMTracker();
+
+const chart = flowChart<object>('Ask', (scope) => {
+    scope.$emit('llm.start', {});
+    scope.$emit('llm.token', { content: 'Hel' });
+    scope.$emit('llm.token', { content: 'lo' });
+    console.log(live.isInFlight(), live.concurrent(), live.getPartial('ask#0')); // mid-bracket
+    scope.$emit('llm.end', {});
+  }, 'ask')
+  .addDeciderFunction('Check', () => 'ok', 'check')
+    .addFunctionBranch('ok', 'Ok', () => {})
+    .end()
+  .build();
+
+const executor = new FlowChartExecutor(chart);
+executor.attachFlowRecorder(tokens);
+executor.attachFlowRecorder(audit);
+executor.attachEmitRecorder(live);
+await executor.run();
+
+console.log(tokens.total(), tokens.byStep('ask#0'), tokens.upTo(new Set(['ask#0'])));
+console.log(live.isInFlight(), live.concurrent(), JSON.stringify(audit.forStep('check#1')), audit.ranges().size);
+// true 1 Hello
+// 30 { tokens: 10 } 10
+// false 0 [{"runtimeStageId":"check#1","type":"decision"}] 1
 ```
 
 **`getEntryRanges()`** returns a precomputed `Map<runtimeStageId, {firstIdx, endIdx}>` maintained during `push()`. Use for O(1) per-step range lookups during time-travel scrubbing. Same shape as `buildEntryRangeIndex()` in `footprint-explainable-ui`.
 
-**`CombinedNarrativeEntry.direction`** — subflow entries carry `direction: 'entry' | 'exit'`. Use for programmatic subflow boundary detection instead of text scanning (which breaks with custom `NarrativeRenderer`).
+**`CombinedNarrativeEntry.direction`** — subflow entries carry `direction: 'entry' | 'exit'` (and `subflowId`). Use for programmatic subflow boundary detection instead of text scanning (which breaks with a custom `NarrativeFormatter`; `NarrativeRenderer` is its deprecated alias).
 
-**`footprint-explainable-ui` narrative utilities** — for consumers building custom shells without `ExplainableShell`:
+**`footprint-explainable-ui` narrative utilities** (read from that package's source, 0.38.0) — for consumers building custom shells without `ExplainableShell`:
 - `buildEntryRangeIndex(entries)` — build range index from flat array (when no recorder access)
 - `computeRevealedEntryCount(entries, snapshots, idx, rangeIndex?)` — slider position → entry count
 - `extractSubflowNarrative(entries, subflowId)` — three-tier subflow entry extraction
 
-**How runtimeStageId is generated:** A counter starts at 0 and increments by 1 for each stage execution across the entire run, including subflow stages. Subflow child traversers share the parent counter so indices are globally unique. Stages inside subflows have stageIds already prefixed by the builder (e.g., `sf-tools/execute-tool-calls`), so `buildRuntimeStageId` just appends `#index`.
+**How runtimeStageId is generated:** A counter starts at 0 and increments by 1 for each stage execution across the entire run, including subflow stages. Subflow child traversers share the parent counter so indices are globally unique. Stages inside subflows have stageIds already prefixed by the builder (e.g., `sf-tools/execute-tool-calls`), so the engine's `buildRuntimeStageId(prefixedId, idx)` just appends `#index`.
 
 ## Dev Mode
 
-One global flag (`enableDevMode()` / `disableDevMode()` / `isDevMode()`) controls every developer-only diagnostic across the library. OFF by default — production pays zero overhead.
+One global flag (`enableDevMode()` / `disableDevMode()` / `isDevMode()`) controls every developer-only diagnostic across the library. OFF by default — the diagnostics below run only when it is on.
+
+```typescript
+import { flowChart, FlowChartExecutor, enableDevMode, disableDevMode, isDevMode } from 'footprintjs';
+
+console.log(isDevMode());
+// false
+enableDevMode(); // in a real app: if (process.env.NODE_ENV !== 'production') enableDevMode();
+
+const warnings: string[] = [];
+console.warn = (message: string) => { warnings.push(message.split(' — ')[0]); };
 
-```ts
-import { enableDevMode } from 'footprintjs';
-if (process.env.NODE_ENV !== 'production') enableDevMode();
+const executor = new FlowChartExecutor(flowChart<{ n: number }>('Seed', (scope) => { scope.n = 1; }, 'seed').build());
+executor.attachCombinedRecorder({ id: 'empty' }); // no on* handler: warns
+await executor.run();
+console.log(warnings);
+// [
+//   "[footprintjs] attachCombinedRecorder: recorder 'empty' has no observer event methods"
+// ]
+console.log(Object.isFrozen(executor.getSnapshot().sharedState)); // dev mode: a deep-frozen clone, not the live state
+// true
+disableDevMode();
 ```
 
-Gated diagnostics:
-- **Circular-ref detection** in `ScopeFacade.setValue()` — O(n) WeakSet traversal per write
+Gated diagnostics (not exhaustive; each is gated on `isDevMode()` in the source):
+- **Circular-ref detection** in scope writes (`ScopeFacade.setValue()`) — O(n) WeakSet traversal per write
 - **Empty-recorder warning** in `attachCombinedRecorder(r)` — catches `r` with no `on*` handler
-- **Suspicious predicates** in `decide()` / `select()`
+- **`decide()` / `select()` rules** that throw while evaluating, or filter ops that are not one of `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `notIn` (the rule counts as not matched)
 - **Snapshot integrity** in `getSubtreeSnapshot()`
+- **Recorder hook errors** — a recorder hook that throws is isolated and, in dev mode, warned about; it does not abort the run — except `onResume`, which the executor calls unguarded (a throw rejects `resume()`), and, in dev mode, a hook that throws a value that cannot be stringified (a null-prototype object rejects `run()`).
+- **`getSnapshot().sharedState`** becomes a deep-frozen clone, so a mutation throws instead of corrupting engine state
+- **A subflow id mounted twice** — warned at build time (a pause inside it could not be resumed)
 
 Convention: when adding a new dev-only check, gate on `isDevMode()` (from `lib/devMode.ts`). Do NOT use `process.env.NODE_ENV` inline — consumers control dev tooling centrally via `enableDevMode()`/`disableDevMode()`, and inline env checks break that contract.
 
@@ -534,48 +906,119 @@ Convention: when adding a new dev-only check, gate on `isDevMode()` (from `lib/d
 
 By default, an inner subflow's `$break` stops ONLY the subflow; the parent continues. Opt into propagation via `SubflowMountOptions.propagateBreak: true`:
 
-```ts
-builder.addSubFlowChartNext('sf-escalate', escalateChart, 'Escalate', {
-  inputMapper: ..., outputMapper: ...,
-  propagateBreak: true,  // ← inner $break → parent $break, with reason
-});
+```typescript
+import { flowChart, FlowChartExecutor } from 'footprintjs';
+
+const escalateChart = flowChart<{ partial?: string; later?: boolean }>('Escalate', (scope) => {
+    scope.partial = 'from-subflow';
+    scope.$break('policy violation');
+  }, 'escalate')
+  .addFunction('NeverRuns', (scope) => { scope.later = true; }, 'never-runs')
+  .build();
+
+for (const propagateBreak of [false, true]) {
+  const chart = flowChart<{ seed?: boolean; got?: string; after?: boolean }>('Seed', (scope) => { scope.seed = true; }, 'seed')
+    .addSubFlowChartNext('sf-escalate', escalateChart, 'Escalate', {
+      outputMapper: (sub: { partial?: string }) => ({ got: sub.partial }),
+      propagateBreak,                // ← inner $break → parent $break, with reason
+    })
+    .addFunction('After', (scope) => { scope.after = true; }, 'after')
+    .build();
+  const executor = new FlowChartExecutor(chart);
+  const breaks: string[] = [];
+  executor.attachFlowRecorder({
+    id: 'breaks',
+    onBreak: (e) => { breaks.push(`${e.stageName}: ${e.reason}${e.propagatedFromSubflow ? ` (from ${e.propagatedFromSubflow})` : ''}`); },
+  });
+  await executor.run();
+  console.log(propagateBreak, JSON.stringify(executor.getSnapshot().sharedState), breaks);
+}
+// false {"seed":true,"got":"from-subflow","after":true} [ 'sf-escalate/Escalate: policy violation' ]
+// true {"seed":true,"got":"from-subflow"} [
+//   'sf-escalate/Escalate: policy violation',
+//   'Escalate: policy violation (from sf-escalate)'
+// ]
 ```
 
 Semantics:
 - **Linear chain:** inner `$break(reason)` → parent's `breakFlag` flips → next parent stage does NOT run → `FlowBreakEvent` fires at parent-mount level with `propagatedFromSubflow` + reason.
-- **Nested chain:** propagates through every hop that opted in. Reason survives.
-- **outputMapper still runs** before propagation — subflow's partial state lands in parent before the break. Escape hatch: early-return `{}` from outputMapper when the break state is set.
-- **Parallel/fan-out:** existing ChildrenExecutor rule applies — parent breaks only when ALL fork children broke. `propagateBreak: true` on a single child contributes to that count; doesn't terminate the fork alone.
+- **Nested chain:** propagates through every hop that opted in (a hop that did not opt in stops the propagation there). Reason survives.
+- **outputMapper still runs** before propagation — subflow's partial state lands in parent before the break (`got` above). Escape hatch: early-return `{}` from outputMapper when the break state is set.
+- **Parallel/fan-out:** a `$break` in a fork child stops that child; the parent continues after the fork even when EVERY child broke (the "all children broke" rule in `ChildrenExecutor` is not wired in 9.32.0). `propagateBreak: true` does not change that.
 
 Example: [examples/runtime-features/break/04-subflow-propagate.ts](examples/runtime-features/break/04-subflow-propagate.ts).
 
 ## Emit Channel (Phase 3)
 
-Third observer channel alongside `Recorder` (data-flow) and `FlowRecorder` (control-flow). Consumer stage code emits structured events; `EmitRecorder.onEmit(event)` fires synchronously with auto-enriched context.
+Third observer channel alongside `ScopeRecorder` (data-flow) and `FlowRecorder` (control-flow). Consumer stage code emits structured events; `EmitRecorder.onEmit(event)` fires synchronously with auto-enriched context.
 
-```ts
+```typescript
+import { flowChart, FlowChartExecutor } from 'footprintjs';
 import type { EmitRecorder, EmitEvent } from 'footprintjs';
 
-// Inside a stage:
-scope.$emit('myapp.llm.tokens', { input: 100, output: 50 });
-
-// Recorder observes:
+const tallies: unknown[] = [];
 const rec: EmitRecorder = {
   id: 'token-meter',
-  onEmit: (e) => { if (e.name === 'myapp.llm.tokens') tally(e.payload); },
+  onEmit: (e) => { if (e.name === 'myapp.llm.tokens') tallies.push(e.payload); },
 };
-executor.attachEmitRecorder(rec);
+
+const sub = flowChart<object>('SubStage', (scope) => { scope.$emit('myapp.sub.event', { in: 'sub' }); }, 'sub-stage').build();
+const chart = flowChart<object>('Meter', (scope) => {
+    // Inside a stage:
+    scope.$emit('myapp.llm.tokens', { input: 100, output: 50 });
+    scope.$emit('myapp.auth.check', { secret: 'x' });   // matched by emitPatterns below
+    scope.$debug('k', 1); scope.$error('e', 2); scope.$metric('m', 3); scope.$eval('ev', 4); scope.$log('hello');
+  }, 'meter')
+  .addSubFlowChartNext('sf', sub, 'Sub')
+  .build();
+
+const executor = new FlowChartExecutor(chart);
+executor.enableNarrative({
+  renderer: {
+    renderEmit: (ctx) => (ctx.name === 'myapp.llm.tokens' ? `Tokens: ${JSON.stringify(ctx.payload)}` : undefined),
+  },
+});
+executor.setRedactionPolicy({ emitPatterns: [/\.auth\./] });
+executor.attachEmitRecorder(rec); // Recorder observes
+const seen: EmitEvent[] = [];
+executor.attachEmitRecorder({ id: 'all', onEmit: (e) => { seen.push(e); } });
+await executor.run();
+
+console.log(JSON.stringify(tallies));
+// [{"input":100,"output":50}]
+console.log(seen.map((e) => e.name));
+// [
+//   'myapp.llm.tokens',
+//   'myapp.auth.check',
+//   'log.debug.k',
+//   'log.error.e',
+//   'metric.m',
+//   'eval.ev',
+//   'log.debug.messages',
+//   'myapp.sub.event'
+// ]
+const { timestamp, ...enriched } = seen[seen.length - 1];
+console.log(JSON.stringify(enriched), typeof timestamp);
+// {"name":"myapp.sub.event","payload":{"in":"sub"},"stageName":"sf/SubStage","runtimeStageId":"sf/sub-stage#2","subflowPath":["sf"],"pipelineId":""} number
+console.log(JSON.stringify(seen[1].payload));
+// "[REDACTED]"
+console.log(executor.getNarrativeEntries().filter((e) => e.type === 'emit').map((e) => e.text).slice(0, 3));
+// [
+//   'Tokens: {"input":100,"output":50}',
+//   '[emit] myapp.auth.check: "[REDACTED]"',
+//   '[emit] log.debug.k: {key, value, level}'
+// ]
 ```
 
 ### Semantics
-- **Pass-through.** Delivered synchronously, in call order. Zero allocation when no recorder attached (fast-path in `ScopeFacade.emitEvent`).
-- **Auto-enriched.** Events carry `stageName`, `runtimeStageId`, `subflowPath`, `pipelineId`, `timestamp` — parsed from `runtimeStageId` for subflow context.
+- **Pass-through.** Delivered synchronously, in call order. `ScopeFacade.emitEvent` returns immediately when no recorder is attached.
+- **Auto-enriched.** Events carry `stageName`, `runtimeStageId`, `subflowPath`, `pipelineId`, `timestamp` — in a subflow, the stage name and runtimeStageId carry the path prefix and `subflowPath` lists it.
 - **Error-isolated.** A throwing `onEmit` doesn't propagate; errors route to `onError` on other recorders.
 - **Redactable.** `RedactionPolicy.emitPatterns: RegExp[]` matches `event.name`; matched payloads become `'[REDACTED]'` before dispatch.
 - **Buffered in narrative.** `CombinedNarrativeRecorder.onEmit` buffers alongside reads/writes; flushed in `flushOps` so emit entries appear AFTER the stage header in ordered narrative.
 
 ### Naming convention
-Hierarchical dotted names — `<namespace>.<category>.<event>`. Examples:
+Hierarchical dotted names — `<namespace>.<category>.<event>` (a convention: any name is accepted). Examples:
 - `'agentfootprint.llm.tokens'`, `'agentfootprint.llm.request'`
 - `'myapp.billing.spend'`, `'myapp.auth.check'`
 
@@ -587,12 +1030,13 @@ $debug(key, value)    → emits 'log.debug.${key}'
 $error(key, value)    → emits 'log.error.${key}'
 $metric(name, value)  → emits 'metric.${name}'
 $eval (name, value)   → emits 'eval.${name}'
+$log(value)           → emits 'log.debug.messages'
 ```
 
-This closes the long-standing gap where `$metric` / `$debug` went to side bags no recorder observed. Backward-compat: the side bags still populate for consumers that inspect snapshots directly.
+So `$metric` / `$debug` are observable by recorders in real time; the side bags still populate for consumers that inspect snapshots directly.
 
 ### Customizing narrative rendering
-`NarrativeFormatter.renderEmit?(ctx)` hook renders an emit event into a narrative line. Return `string` to use, `null` to exclude, `undefined` to fall back to the default `[emit] name: payloadSummary`.
+`NarrativeFormatter.renderEmit?(ctx)` hook (passed as `enableNarrative({ renderer })`) renders an emit event into a narrative line. Return `string` to use, `null` to exclude, `undefined` to fall back to the default `[emit] name: payloadSummary` (above: the first line is the custom one, the rest are defaults).
 
 Example: [examples/runtime-features/emit/01-custom-events.ts](examples/runtime-features/emit/01-custom-events.ts).
 
@@ -600,9 +1044,11 @@ Example: [examples/runtime-features/emit/01-custom-events.ts](examples/runtime-f
 
 A `CombinedRecorder` is an observer that hooks into multiple event streams (scope data-flow, control-flow, AND emit — all three channels). One object, one `id`, one `attachCombinedRecorder()` call — the library routes to the right channels via runtime method-shape detection.
 
-```ts
+```typescript
+import { flowChart, FlowChartExecutor, isFlowEvent } from 'footprintjs';
 import type { CombinedRecorder } from 'footprintjs';
-import { isFlowEvent } from 'footprintjs';
+
+const log = (...parts: unknown[]) => console.log(...parts);
 
 const audit: CombinedRecorder = {
   id: 'audit',
@@ -615,31 +1061,61 @@ const audit: CombinedRecorder = {
   },
 };
 
+const chart = flowChart<{ n: number }>('Seed', (scope) => { scope.n = 1; }, 'seed')
+  .addFunction('Boom', () => { throw new Error('kaput'); }, 'boom')
+  .build();
+
+const executor = new FlowChartExecutor(chart);
 executor.attachCombinedRecorder(audit);
+await executor.run().catch(() => undefined);
+// scope write n
+// flow error in Boom
 ```
 
-Built on `CombinedRecorder`: `CombinedNarrativeRecorder` (the `executor.enableNarrative()` default). Consumers implement ONLY the events they care about — `Partial<Recorder> & Partial<FlowRecorder>` under the hood.
+Built on `CombinedRecorder`: `CombinedNarrativeRecorder` (the `executor.enableNarrative()` default). Consumers implement ONLY the events they care about — `Partial<ScopeRecorder> & Partial<FlowRecorder> & Partial<EmitRecorder>` under the hood.
 
-**Detection rule:** only OWN event-method properties count (prototype methods are ignored for security — prevents accidental `Object.prototype` pollution from attaching handlers).
+**Detection rule:** a handler counts when it is an OWN property OR a method on the recorder's class prototype chain — class instances work. Only handlers inherited from `Object.prototype` are ignored (prevents accidental `Object.prototype` pollution from attaching handlers).
 
 ## Anti-Patterns
 
-- Never post-process the tree — use recorders
-- Don't use `getValue()`/`setValue()` in TypedScope stages — use typed property access
-- Don't use `$`-prefixed state keys (e.g., `$break`) — they collide with ScopeMethods
-- Don't use deprecated `CombinedNarrativeBuilder` — use `CombinedNarrativeRecorder`
-- Don't extract shared base for Recorder/FlowRecorder — two instances = coincidence
+- Never post-process the tree — use recorders (or the `footprintjs/trace` queries over the recorded log)
+- Don't use `getValue()`/`setValue()` for keys you know in TypedScope stages — use typed property access (`$getValue`/`$setValue` are for dynamic keys; plain `scope.getValue` does not exist there)
+- Don't give a state key the name of a `$` method (`scope.$break = 1` throws "conflicts with a reserved TypedScope method") — the reserved names are `SCOPE_METHOD_NAMES` in `footprintjs/advanced`; avoid `$`-prefixed state keys altogether
+- Don't write a state key that is also a `run({ input })` key — input keys are read-only for the run
+- `CombinedNarrativeBuilder` is gone (removed in v1.0) — the narrative comes from `CombinedNarrativeRecorder` via `executor.enableNarrative()` or the `narrative()` factory
+- Don't extract a shared base for scope and flow recorders — built-ins compose a store (`KeyedStore` / `SequenceStore`) as a field
 - Don't use `getArgs()` for tracked data — use typed scope properties
 - Don't put infrastructure data in `getArgs()` — use `getEnv()` via `run({ env })`
-- Don't manually create `CombinedNarrativeRecorder` — `executor.recorder(narrative())` handles it
-- Don't return full arrays from `outputMapper` without `arrayMerge: ArrayMergeMode.Replace` — default `applyOutputMapping` **concatenates** arrays (`[...parent, ...subflow]`). Either return only the **delta** (new items), or set `arrayMerge: ArrayMergeMode.Replace` on `SubflowMountOptions` to overwrite instead of concatenate. Scalars are always replaced regardless.
+- Don't hand-roll a recorder to get the narrative — `executor.enableNarrative()` (or `chart.recorder(narrative())`) is the whole setup, and it is off until called
+- Don't end a loop with `return` — `.loopTo(id)` is unconditional; exit through a decider branch or `scope.$break()`
+- Don't return full arrays from `outputMapper` without `arrayMerge: ArrayMergeMode.Replace` — default `applyOutputMapping` **concatenates** arrays (`[...parent, ...subflow]`). Either return only the **delta** (new items), or set `arrayMerge: ArrayMergeMode.Replace` on `SubflowMountOptions` to overwrite instead of concatenate. Scalars are always replaced regardless. `ArrayMergeMode` is exported from `footprintjs/advanced` (not the main door).
+
+```typescript
+import { flowChart, FlowChartExecutor } from 'footprintjs';
+import { ArrayMergeMode } from 'footprintjs/advanced';
+
+const sub = flowChart<{ items?: string[] }>('Sub', (scope) => { scope.items = ['a', 'b']; }, 'sub').build();
+for (const arrayMerge of [ArrayMergeMode.Concat, ArrayMergeMode.Replace]) {
+  const chart = flowChart<{ items: string[] }>('Seed', (scope) => { scope.items = ['a']; }, 'seed')
+    .addSubFlowChartNext('sf', sub, 'Sub', { outputMapper: (out: { items?: string[] }) => ({ items: out.items }), arrayMerge })
+    .build();
+  const executor = new FlowChartExecutor(chart);
+  await executor.run();
+  console.log(arrayMerge, JSON.stringify(executor.getSnapshot().sharedState.items));
+}
+// concat ["a","a","b"]
+// replace ["a","b"]
+```
 
 ## Build & Test
 
 ```bash
-npm run build    # tsc (CJS) + tsc -p tsconfig.esm.json (ESM)
-npm test         # full suite
-npm run test:unit
+npm run build           # tsc (CJS) + tsc -p tsconfig.esm.json (ESM) + scripts/postbuild-esm.mjs
+npm test                # full suite (vitest)
+npm run test:examples   # type-check examples/
+npm run lint
+npm run check:layering  # the layering rule, from scripts/layering.config.cjs
+npm run check:doc-snippets
 ```
 
 Dual output: CommonJS (`dist/`) + ESM (`dist/esm/`) + types (`dist/types/`)