footprintjs 9.40.0 → 9.41.0

package/dist/esm/lib/runner/FlowChartExecutor.d.ts

@@ -14,6 +14,11 @@
  *   // 2-param form (accepts a ScopeFactory directly, for backward compatibility):
  *   const executor = new FlowChartExecutor(chart, myFactory);
  *
+ *
+ * The executor composes four modules, one job each (F9): `attach.ts` (who
+ * observes a run), `resume.ts` (plan and announce a re-entry), `checkpoint.ts`
+ * (the pause checkpoint), `snapshot.ts` (what `getSnapshot()` serves). What
+ * stays here is the per-run state and the run lifecycle that threads it.
  *   const result = await executor.run({ input: data, env: { traceId: 'req-123' } });
  */
 import type { FlowChart } from '../builder/types.js';
@@ -21,123 +26,39 @@ import type { CombinedNarrativeRecorderOptions } from '../engine/narrative/Combi
 import type { CombinedNarrativeEntry } from '../engine/narrative/narrativeTypes.js';
 import type { ManifestEntry } from '../engine/narrative/recorders/ManifestFlowRecorder.js';
 import type { FlowRecorder } from '../engine/narrative/types.js';
-import { type ExecutorResult, type RunOptions, type ScopeFactory, type SerializedPipelineStructure, type StageNode, type StreamHandlers, type SubflowResult } from '../engine/types.js';
-import type { RunDials } from '../memory/runPolicy.js';
+import { type ExecutorResult, type RunOptions, type ScopeFactory, type SerializedPipelineStructure, type StageNode, type SubflowResult } from '../engine/types.js';
 import type { CommitValuesMode, ReadTrackingMode, WriteTrackingMode } from '../memory/types.js';
 import type { FlowchartCheckpoint } from '../pause/types.js';
 import type { CombinedRecorder } from '../recorder/CombinedRecorder.js';
 import type { EmitRecorder } from '../recorder/EmitRecorder.js';
-import type { ScopeProtectionMode } from '../scope/protection/types.js';
 import type { RedactionPolicy, RedactionReport, ScopeRecorder } from '../scope/types.js';
-import { type AttachRecorderOptions, type ObserverDrainResult } from './DeferredObserverTier.js';
+import type { AttachRecorderOptions, ObserverDrainResult } from './DeferredObserverTier.js';
 import { type RuntimeSnapshot } from './ExecutionRuntime.js';
-/**
- * Options object for `FlowChartExecutor` — preferred over positional params.
- *
- * ```typescript
- * const ex = new FlowChartExecutor(chart, {
- *   scopeFactory: myFactory,
- *   defaultValuesForContext: { ... },
- * });
- * ```
- *
- * **Sync note for maintainers:** Every field added here must also appear in the
- * `flowChartArgs` private field type and in the constructor's options-resolution
- * block (the `else if` branch that reads from `opts`). Missing any one of the
- * three causes silent omission — the option is accepted but never applied.
- * The observability DIALS are the exception: they come from `RunDials`
- * (memory/runPolicy.ts) and travel as one `dials` field, so a new dial is
- * added there and nowhere here.
- *
- * **TScope inference note:** When using the options-object form with a custom scope,
- * TypeScript cannot infer `TScope` through the options object. Pass the type
- * explicitly: `new FlowChartExecutor<TOut, MyScope>(chart, { scopeFactory })`.
- */
-export interface FlowChartExecutorOptions<TScope = any> extends RunDials {
-    /** Custom scope factory. Defaults to TypedScope or ScopeFacade auto-detection. */
-    scopeFactory?: ScopeFactory<TScope>;
-    /**
-     * Default values pre-populated into the shared context before **each** stage
-     * (re-applied every stage, acting as baseline defaults).
-     */
-    defaultValuesForContext?: unknown;
-    /**
-     * Initial context values merged into the shared context **once** at startup
-     * (applied before the first stage, not repeated on subsequent stages).
-     * Distinct from `defaultValuesForContext`, which is re-applied every stage.
-     */
-    initialContext?: unknown;
-    /** Read-only input accessible via `scope.getArgs()` — never tracked or written. */
-    readOnlyContext?: unknown;
-    /**
-     * Custom error classifier for throttling detection. Return `true` if a fork
-     * child's error represents a rate-limit or backpressure condition; the
-     * executor then fires `FlowRecorder.onThrottled` for that child (9.39.0 —
-     * an EVENT, not a state key: the `monitor.isThrottled` write it replaced
-     * never landed). The child's failure is otherwise handled as before.
-     * Defaults to no throttling classification.
-     */
-    throttlingErrorChecker?: (error: unknown) => boolean;
-    /** Handlers for streaming stage lifecycle events (see `addStreamingFunction`). */
-    streamHandlers?: StreamHandlers;
-    /** Scope protection mode for TypedScope direct-assignment detection. */
-    scopeProtectionMode?: ScopeProtectionMode;
-}
+import { type FlowChartExecutorOptions } from './options.js';
 export declare class FlowChartExecutor<TOut = any, TScope = any> {
     private traverser;
-    /** Shared execution counter — survives pause/resume. Reset on fresh run(). */
+    /** Shared execution counter and per-stage visit counts (loopIteration) — shared BY
+     *  REFERENCE with every traverser of the run; survive pause/resume, reset on run(). */
     private _executionCounter;
-    /** Shared per-run visit counts (by stageId) driving TraversalContext.loopIteration.
-     *  Twin of _executionCounter: survives pause/resume, reset on fresh run(). */
     private _visitCounts;
-    /** Per-`run()` identifier — generated fresh per run + per resume. Threaded
-     *  through every TraversalContext so recorders can scope state to a single
-     *  run. See `runId.ts`. */
+    /** Fresh per run() and per resume() — stamped on every TraversalContext (`runId.ts`). */
     private _currentRunId;
-    private narrativeEnabled;
-    private narrativeOptions?;
-    private combinedRecorder;
-    private flowRecorders;
-    private scopeRecorders;
-    /**
-     * RFC-001 deferred-observer wiring — created LAZILY on the first
-     * `delivery: 'deferred'` attach. `undefined` for every executor that never
-     * opts in: zero allocation, zero per-event cost, byte-identical behavior
-     * (the emit fast-path precedent).
-     */
-    private deferredTier?;
+    /** Who observes the run — narrative, inline lists, deferred tier (`attach.ts`). */
+    private readonly observers;
     private redactionPolicy;
-    /**
-     * The run's ONE redaction rule (`memory/redaction.ts`): built fresh per
-     * `createTraverser` (per-call marks reset per run and per resume, as the
-     * shared set always did), installed on the runtime root so every context
-     * retains under it, and read by every `ScopeFacade` through its context.
-     */
+    /** The run's ONE redaction rule (`memory/redaction.ts`), built fresh per leg. */
     private redactionRule;
     private lastCheckpoint;
     /**
-     * `true` once `run()` (or a previous `resume()`) has executed on
-     * this instance. `resume()` branches on it:
-     *
-     *   • true  → reuse the constructor-time runtime (same-executor
-     *             continuity: execution tree, recorders, narrative
-     *             accumulate across pause/resume cycles)
-     *   • false → seed a fresh runtime from `checkpoint.sharedState`
-     *             (cross-executor / cross-process resume: new instance
-     *             reconstructed from a serialized checkpoint)
-     *
-     * Without this flag, fresh executors silently discarded the
-     * checkpoint's sharedState and resume handlers couldn't read pre-pause
-     * scope. See `test/lib/pause/cross-executor-resume.test.ts`.
+     * `true` once run() (or a resume) executed here. `resume()` branches on it:
+     * true → reuse the runtime (execution tree, recorders, narrative accumulate);
+     * false → seed a fresh runtime from `checkpoint.sharedState` (cross-executor
+     * resume). See `test/lib/pause/cross-executor-resume.test.ts`.
      */
     private _hasRunBefore;
     /**
-     * Re-entrancy guard. `run()` and `resume()` mutate per-run instance state
-     * (traverser, runId, execution counter, checkpoint) and clear attached
-     * recorders — a second concurrent entry on the SAME executor would
-     * interleave runIds and cross-contaminate recorder/narrative state, and
-     * `getCheckpoint()` would return whichever run paused last. One executor =
-     * one in-flight execution; create an executor per concurrent run.
+     * Re-entrancy guard: run()/resume() mutate per-run state (traverser, runId,
+     * counters, checkpoint, recorders) — one executor = one in-flight execution.
      * See docs/guides/execution-model.md.
      */
     private _isExecuting;
@@ -166,28 +87,11 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * Must be called before run().
      */
     setRedactionPolicy(policy: RedactionPolicy): void;
-    /**
-     * Set the read-tracking policy for `StageSnapshot.stageReads` (#14).
-     * Must be called before run(). Equivalent to the `readTracking`
-     * constructor option — see {@link FlowChartExecutorOptions.readTracking}
-     * for the mode semantics ('full' default / 'summary' / 'off').
-     */
+    /** The `readTracking` dial (see {@link FlowChartExecutorOptions.readTracking}). Call before run(). */
     setReadTracking(mode: ReadTrackingMode): void;
-    /**
-     * Set the write-tracking policy for `StageSnapshot.stageWrites` (#13c-A).
-     * Must be called before run(). Equivalent to the `writeTracking`
-     * constructor option — see {@link FlowChartExecutorOptions.writeTracking}
-     * for the mode semantics ('full' default / 'summary' / 'off'), the
-     * onCommit-payload consequence, and the redaction-precedence rule.
-     */
+    /** The `writeTracking` dial (see {@link FlowChartExecutorOptions.writeTracking}). Call before run(). */
     setWriteTracking(mode: WriteTrackingMode): void;
-    /**
-     * Set the commit-values encoding policy for the commit log (#13c-B).
-     * Must be called before run(). Equivalent to the `commitValues`
-     * constructor option — see {@link FlowChartExecutorOptions.commitValues}
-     * for the mode semantics ('full' default / 'delta'), the verb-qualified
-     * `overwrite` consequence, and the `commitValueAt` migration helper.
-     */
+    /** The `commitValues` dial (see {@link FlowChartExecutorOptions.commitValues}). Call before run(). */
     setCommitValues(mode: CommitValuesMode): void;
     /**
      * Returns a compliance-friendly report of all redaction activity from the
@@ -198,12 +102,9 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * Returns the checkpoint from the most recent paused execution, or `undefined`
      * if the last run completed without pausing.
      *
-     * The checkpoint is JSON-serializable — store it in Redis, Postgres, localStorage, etc.
-     *
-     * It is fully DETACHED from engine state: every field was deep-copied at
-     * pause time (see `buildPauseCheckpoint`). Holding, mutating, or persisting
-     * it cannot affect the executor, and a later same-executor resume cannot
-     * mutate a checkpoint you already stored.
+     * JSON-serializable (store it in Redis, Postgres, localStorage…) and fully
+     * DETACHED from engine state (`checkpoint.ts`): mutating or persisting it
+     * cannot affect the executor, nor a later resume a checkpoint you stored.
      *
      * @example
      * ```typescript
@@ -226,38 +127,23 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      *
      * Returns 0 before any run; after, returns the cumulative commit
      * count across the executor's lifetime (including resumes).
-     *
-     * IMPLEMENTATION NOTE: this returns `runtime.executionHistory.length`,
-     * which is the same value as `getSnapshot().commitLog.length`. The
-     * naming asymmetry is historical — the underlying `EventLog` field
-     * is named `executionHistory` but stores the `CommitBundle[]` that
-     * `commitLog` exposes. They always report the same LENGTH (verified by the
-     * "matches commitLog.length" integration test); since 9.17.0 the snapshot
-     * serves a detached frozen COPY of the array, not the live one.
+     * Always equals `getSnapshot().commitLog.length` (the log is the
+     * `EventLog`'s `executionHistory`; the snapshot serves a frozen copy).
      */
     getCommitCount(): number;
     /**
      * Resume a paused flowchart from a checkpoint.
      *
-     * Restores the scope state, calls the paused stage's `resumeFn` with the
-     * provided input (or, for an `interrupt()` pause, re-runs the stage with the
-     * answer), then continues with whatever ran after that stage on the run —
-     * its own `next`, or the continuation of the decider, selector or fork that
-     * dispatched it, at every level of the pause path — and from there walks the
-     * chart as built. When parallel siblings paused in the same fan-out
-     * (`checkpoint.pendingPauses`), the run pauses again with the next sibling's
-     * question once this one's branch is done; the fan-out's join runs after the
-     * last answer. See `ResumeEntry` (`footprintjs/advanced`).
+     * Restores the scope state, runs the paused stage's `resumeFn` with the input
+     * (an `interrupt()` pause re-runs the stage with the answer), then continues
+     * with whatever ran after that stage on the run — its `next`, or its
+     * dispatcher's continuation, at every level of the pause path. Parallel
+     * siblings that paused together (`checkpoint.pendingPauses`) are asked in
+     * turn; the join runs after the last answer. See `ResumeEntry`.
      *
-     * The checkpoint can come from `getCheckpoint()` on a previous run, or from
-     * a serialized checkpoint stored in Redis/Postgres/localStorage.
-     *
-     * **Recorder/narrative state depends on the resume mode.** Resuming on the SAME
-     * executor that ran preserves and accumulates narrative/metrics/debug across the
-     * pause/resume cycle (preserveRecorders). Resuming on a FRESH executor
-     * (reconstructed from a stored checkpoint) starts with empty recorder state —
-     * collect what you need before discarding the paused executor. A fresh `runId`
-     * is generated either way.
+     * The checkpoint comes from `getCheckpoint()` or from storage. On the SAME
+     * executor, narrative/recorder state accumulates across the pause; on a
+     * FRESH executor it starts empty. A fresh `runId` either way.
      *
      * @example
      * ```typescript
@@ -273,139 +159,37 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      */
     resume(checkpoint: FlowchartCheckpoint, resumeInput?: unknown, options?: Pick<RunOptions, 'signal' | 'env' | 'maxDepth' | 'maxIterations'>): Promise<ExecutorResult>;
     /**
-     * Build a fully DETACHED checkpoint from a caught PauseSignal.
-     *
-     * Every field is deep-copied via one `structuredClone` of the assembled
-     * checkpoint, because the raw pieces alias live engine state:
-     *
-     *   - `sharedState` IS `SharedMemory`'s current generation — never edited,
-     *     but (copy-on-write, 9.29.0) every later generation shares its
-     *     unchanged subtrees, so a checkpoint that aliased it would alias the
-     *     resumed run's state too.
-     *   - `executionTree` nodes are fresh, but their `logs`/`errors`/`metrics`/
-     *     `evals`/`stageReads`/`flowMessages` fields reference live
-     *     `DiagnosticCollector` bags that keep accumulating on same-executor
-     *     resume.
-     *   - `subflowStates` values are shallow copies whose NESTED objects alias
-     *     subflow memory, and they get seeded back into live runtimes on resume.
-     *   - `subflowResults` values stay referenced by the traverser's results map.
-     *
-     * The checkpoint is persisted by contract ("store in Redis/Postgres") — it
-     * must never share structure with the engine. Pause is not a hot path; the
-     * clone cost is irrelevant.
-     *
-     * The JSON-safe checkpoint contract (no functions, no class instances)
-     * governs CONSUMER-owned data — but the executionTree's diagnostic bags
-     * accept ANY value at write time without cloning ($debug/$error/$metric/
-     * $eval store raw references), so a contract-compliant run can still carry
-     * a non-cloneable diagnostic. Observability side-bags never abort traversal
-     * anywhere else in the library, so they must not abort the pause either:
-     * on clone failure we sanitize the diagnostic bags (non-cloneable values
-     * become '[non-serializable: …]' markers — the live engine bags are never
-     * touched) and retry. If the retry STILL fails, the violation is in
-     * consumer-owned data (realistically `pauseData` — a function can never
-     * reach shared state in the first place: TransactionBuffer clones every
-     * written value at write time, so the offending write already rejected)
-     * and we throw a DESCRIPTIVE contract error naming the offending
-     * checkpoint field(s). A naked DataCloneError never escapes.
-     *
-     * Subflow scope capture (`subflowStates`) survives ONLY on the signal — the
-     * nested runtimes are GC'd as the stack unwinds. Promoting it onto the
-     * checkpoint here lets cross-executor resume restore pre-pause subflow
-     * scope (e.g. an Agent's `scope.history`). Empty `{}` for root-level pauses.
-     */
-    private buildPauseCheckpoint;
-    /**
-     * Find a StageNode in the compiled graph by ID.
-     * Handles subflow paths by drilling into registered subflows.
+     * The settle of a leg that threw: flush the deferred tier (the OUTERMOST
+     * handler — a pause re-throws through subflow traversers without exit
+     * events, so per-traverser hooks would miss it), then turn a pause into a
+     * detached checkpoint (`checkpoint.ts`) and a `PausedResult`; anything else
+     * is rethrown.
      */
-    private findNodeInGraph;
-    /** DFS search for a node by ID in the StageNode graph. Cycle-safe via visited set. */
-    private dfsFind;
+    private pausedOrThrow;
+    /** The re-entrancy guard: one executor = one in-flight execution. */
+    private assertIdle;
     /**
-     * Attach a scope ScopeRecorder to observe data operations (reads, writes, commits).
-     * Automatically attached to every ScopeFacade created during traversal.
-     * Must be called before run().
-     *
-     * **Idempotent by ID:** If a recorder with the same `id` is already attached,
-     * it is replaced (not duplicated). This prevents double-counting when both
-     * a framework and the user attach the same recorder type.
-     *
-     * Built-in recorders use auto-increment IDs (`metrics-1`, `debug-1`, ...) by
-     * default, so multiple instances with different configs coexist. To override
-     * a framework-attached recorder, pass the same well-known ID.
+     * Attach a ScopeRecorder to observe data operations (reads, writes, commits)
+     * on every stage scope. Call before run(). **Idempotent by `id`** (replaced,
+     * never duplicated). `{ delivery: 'deferred' }` moves it off the hot path —
+     * delivered at the next microtask checkpoint; re-attaching an id on the
+     * other tier SWAPS tiers (`docs/guides/observers-deferred.md`).
      *
      * @example
      * ```typescript
-     * // Multiple recorders with different configs — each gets a unique ID
      * executor.attachScopeRecorder(new MetricRecorder());
-     * executor.attachScopeRecorder(new DebugRecorder({ verbosity: 'minimal' }));
-     *
-     * // Override a framework-attached recorder by passing its well-known ID
-     * executor.attachScopeRecorder(new MetricRecorder('metrics'));
-     *
-     * // Attaching twice with same ID replaces (no double-counting)
-     * executor.attachScopeRecorder(new MetricRecorder('my-metrics'));
-     * executor.attachScopeRecorder(new MetricRecorder('my-metrics')); // replaces previous
+     * executor.attachScopeRecorder(new MetricRecorder('my-metrics')); // replaces same id
      * ```
-     *
-     * **Delivery tier (RFC-001):** pass `{ delivery: 'deferred' }` to take the
-     * recorder out of the engine's hot path — events are captured into a
-     * bounded queue and delivered at the next microtask checkpoint ("one beat
-     * behind"). Omitting `delivery` keeps the historical synchronous call,
-     * byte-identical to previous releases. Re-attaching the same `id` with a
-     * different tier SWAPS tiers cleanly — never double delivery. See
-     * `docs/guides/observers-deferred.md`.
      */
     attachScopeRecorder(recorder: ScopeRecorder, options?: AttachRecorderOptions): void;
-    /**
-     * Lazily create the executor's ONE deferred-observer tier (one merged
-     * queue, total event order across all three channels). The FIRST deferred
-     * attach's options configure the dispatcher; later differing options are
-     * dev-warned and ignored (see `AttachRecorderOptions`).
-     */
-    private ensureDeferredTier;
-    /**
-     * Detach a child flowchart on the given driver and return a `DetachHandle`
-     * the caller can `wait()` on (Promise) or read `.status` from (sync).
-     *
-     * The driver is a REQUIRED first argument — there is no library-default,
-     * to keep the engine free of driver imports and to make the choice of
-     * scheduling algorithm explicit at the call site.
-     *
-     * @example
-     * ```typescript
-     * import { microtaskBatchDriver } from 'footprintjs/detach';
-     *
-     * const exec = new FlowChartExecutor(parentChart);
-     * const handle = exec.detachAndJoinLater(microtaskBatchDriver, telemetryChart, { event: 'x' });
-     * await handle.wait(); // optional
-     * ```
-     */
-    detachAndJoinLater(driver: import('../detach/types.js').DetachDriver, child: import('../builder/types.js').FlowChart, input?: unknown): import('../detach/types.js').DetachHandle;
-    /**
-     * Detach a child flowchart on the given driver and DISCARD the handle.
-     * Use for telemetry exports / fire-and-forget side effects where the
-     * caller doesn't care about the result.
-     *
-     * Errors raised by the child still land on the (discarded) handle — they
-     * go silent unless surfaced through a recorder. For observable detach,
-     * prefer `detachAndJoinLater` and surface failures via `.wait().catch()`.
-     */
-    detachAndForget(driver: import('../detach/types.js').DetachDriver, child: import('../builder/types.js').FlowChart, input?: unknown): void;
     /** Detach all scope Recorders with the given ID — both delivery tiers. */
     detachScopeRecorder(id: string): void;
     /** Returns a defensive copy of attached scope Recorders (both tiers). */
     getScopeRecorders(): ScopeRecorder[];
     /**
-     * Attach a FlowRecorder to observe control flow events.
-     * Automatically enables narrative if not already enabled.
-     * Must be called before run() — recorders are passed to the traverser at creation time.
-     *
-     * **Idempotent by ID:** replaces existing recorder with same `id`.
-     *
-     * **Delivery tier (RFC-001):** pass `{ delivery: 'deferred' }` for
-     * next-checkpoint delivery off the hot path — see `attachScopeRecorder`.
+     * Attach a FlowRecorder to observe control flow events. Automatically
+     * enables narrative. Must be called before run(). Idempotent by `id`;
+     * `{ delivery: 'deferred' }` as for `attachScopeRecorder`.
      */
     attachFlowRecorder(recorder: FlowRecorder, options?: AttachRecorderOptions): void;
     /** Detach all FlowRecorders with the given ID — both delivery tiers. */
@@ -413,39 +197,11 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
     /** Returns a defensive copy of attached FlowRecorders (both tiers). */
     getFlowRecorders(): FlowRecorder[];
     /**
-     * Attach a recorder that may observe multiple event streams (scope
-     * data-flow, control-flow, or both). Detects at runtime which streams the
-     * recorder has methods for and routes it to the correct internal channels.
-     *
-     * Preferred over calling `attachScopeRecorder` and `attachFlowRecorder`
-     * separately, because forgetting one of the two is a silent foot-gun —
-     * half your events never fire and there is no runtime warning. With
-     * `attachCombinedRecorder` the library guarantees the recorder's declared
-     * methods all fire, and adds no overhead versus two explicit calls.
-     *
-     * ## Idempotency
-     *
-     * Idempotent by `id` across ALL channels — re-attaching with the same `id`
-     * replaces the previous instance everywhere it was registered. Mixing
-     * `attachCombinedRecorder(x)` with a prior `attachScopeRecorder(y)` or
-     * `attachFlowRecorder(y)` that share `x.id === y.id` is also safe: the
-     * combined attach replaces the single-channel registration on whichever
-     * channel(s) `x` has methods for. No duplicate firings occur.
-     *
-     * ## Narrative activation
-     *
-     * If the recorder has any control-flow methods, `enableNarrative()` is
-     * called as a side effect (the narrative subsystem is required to emit
-     * control-flow events). Data-flow-only recorders do NOT activate the
-     * narrative.
-     *
-     * ## Detection rule
-     *
-     * Only **own** event methods count (see `hasRecorderMethods`). Methods
-     * inherited via the prototype chain are ignored — this protects against
-     * accidental `Object.prototype` pollution attaching handlers you never
-     * declared. A recorder that provides only `clear`/`toSnapshot` is a
-     * no-op and emits a dev-mode warning to surface the likely mistake.
+     * Attach a recorder to every channel (scope, flow, emit) it has OWN `on*`
+     * methods for — preferred over single-channel calls, where forgetting one
+     * silently loses events. Idempotent by `id` across all channels; a flow
+     * method enables the narrative; `delivery` comes from the options or the
+     * recorder's own field.
      *
      * @example
      * ```typescript
@@ -458,24 +214,11 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * ```
      */
     attachCombinedRecorder(recorder: CombinedRecorder, options?: AttachRecorderOptions): void;
-    /**
-     * Detach a combined recorder from all channels it was attached to.
-     * Safe to call if the recorder was only on one channel or never attached.
-     */
+    /** Detach a combined recorder from every channel it was attached to (safe if never attached). */
     detachCombinedRecorder(id: string): void;
     /**
-     * Attach an `EmitRecorder` — an observer for consumer-emitted structured
-     * events fired via `scope.$emit(name, payload)`.
-     *
-     * Internally, emit recorders share the scope-recorder channel because
-     * emit events fire from inside `ScopeFacade` during stage execution,
-     * same timing as `onRead`/`onWrite`. This method is a convenience that
-     * delegates to `attachScopeRecorder` — consumers can also use
-     * `attachScopeRecorder` directly for a recorder that implements BOTH
-     * `onWrite` and `onEmit`. Either approach places the recorder on the
-     * same underlying list, so `onEmit` fires exactly once per event.
-     *
-     * **Idempotent by `id`:** replaces existing recorder with same `id`.
+     * Attach an `EmitRecorder` for `scope.$emit(name, payload)` events. It rides
+     * the scope list, so `onEmit` fires exactly once per event. Idempotent by `id`.
      *
      * @example
      * ```typescript
@@ -490,25 +233,34 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
     attachEmitRecorder(recorder: EmitRecorder, options?: AttachRecorderOptions): void;
     /** Detach an `EmitRecorder` by id. Safe to call if never attached. */
     detachEmitRecorder(id: string): void;
+    /** Returns a defensive copy of attached recorders (both tiers) that implement `onEmit`. */
+    getEmitRecorders(): EmitRecorder[];
     /**
-     * Returns a defensive copy of attached recorders (both delivery tiers)
-     * filtered to those that implement `onEmit`. Useful for inspection during
-     * testing.
+     * Detach a child flowchart on the given driver and return a `DetachHandle`
+     * the caller can `wait()` on (Promise) or read `.status` from (sync). The
+     * driver is REQUIRED — there is no library default.
+     *
+     * @example
+     * ```typescript
+     * import { microtaskBatchDriver } from 'footprintjs/detach';
+     *
+     * const exec = new FlowChartExecutor(parentChart);
+     * const handle = exec.detachAndJoinLater(microtaskBatchDriver, telemetryChart, { event: 'x' });
+     * await handle.wait(); // optional
+     * ```
      */
-    getEmitRecorders(): EmitRecorder[];
+    detachAndJoinLater(driver: import('../detach/types.js').DetachDriver, child: import('../builder/types.js').FlowChart, input?: unknown): import('../detach/types.js').DetachHandle;
     /**
-     * Returns structured narrative entries — the single public narrative API.
-     * Each entry has a type (stage, step, condition, fork, etc.), text, and
-     * depth. Consumers render however they want; call `.map(e => e.text)`
-     * if a flat `string[]` is needed locally.
+     * Detach a child flowchart on the given driver and DISCARD the handle — for
+     * fire-and-forget side effects. A child's error lands on the discarded handle;
+     * for observable detach prefer `detachAndJoinLater` + `.wait().catch()`.
      */
-    getNarrativeEntries(): CombinedNarrativeEntry[];
+    detachAndForget(driver: import('../detach/types.js').DetachDriver, child: import('../builder/types.js').FlowChart, input?: unknown): void;
     /**
-     * Returns the combined FlowRecorders list. When narrative is enabled,
-     * includes the CombinedNarrativeRecorder (which builds merged flow+data
-     * entries inline). Plus any user-attached recorders.
+     * Structured narrative entries (type, text, depth) — the one public narrative
+     * API; `.map(e => e.text)` for a flat `string[]`.
      */
-    private buildFlowRecordersList;
+    getNarrativeEntries(): CombinedNarrativeEntry[];
     /**
      * Execute the chart. Resolves when the run finishes — or pauses, if a
      * pausable stage returned data (check `isPaused()` afterward).
@@ -528,13 +280,10 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      */
     run(options?: RunOptions): Promise<ExecutorResult>;
     /**
-     * Flush the deferred-observer backlog, then await async listener
-     * completions under a deadline (RFC-001 Block 8 — the serverless /
-     * graceful-shutdown pattern: call before the process freezes or exits so
-     * "one beat behind" work is not lost). Resolves immediately with zeros
-     * when no deferred observer was ever attached. `pending === 0` means a
-     * full drain; a non-zero `pending` reports continuations (plus any queued
-     * events) still outstanding at the deadline — honest, never silent.
+     * Flush the deferred-observer backlog, then await async listener completions
+     * under a deadline — call before a serverless process freezes or exits.
+     * Zeros when no deferred observer was attached; `pending > 0` reports what
+     * was still outstanding at the deadline.
      */
     drainObservers(opts?: {
         timeoutMs?: number;
@@ -542,50 +291,17 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
     /**
      * Returns the runtime snapshot.
      *
-     * @param options.redact  When `true`, `sharedState` comes from the parallel
-     *   redacted mirror (if maintained — see `setRedactionPolicy`). This is
-     *   the safe view for exporting traces externally (paste into a viewer,
-     *   share with support). When no redaction policy is configured the
-     *   redacted mirror is not maintained, so this flag is a no-op —
-     *   `sharedState` is the raw working memory either way. Default `false`.
-     *
-     *   The commit log is already redacted at write-time regardless of this
-     *   flag, and the execution tree carries only structural metadata.
-     *   `subflowResults[*].treeContext.globalContext` follows the flag too
-     *   (9.20.0): under `redact: true` it is each subflow's own redacted
-     *   mirror; plain, the subflow's live heap.
+     * @param options.redact  `true` serves `sharedState` (and each subflow's
+     *   `globalContext`) from the redacted mirror — the safe view to export. A
+     *   no-op without a redaction policy. The commit log is redacted at write
+     *   time regardless. Default `false`.
      *
      * **Treat `sharedState` as READ-ONLY.** In production it is a live view of
-     * the engine's working memory (zero copy cost) — mutating it corrupts
-     * engine state. In dev mode (`enableDevMode()`) it is a deep-frozen CLONE,
-     * so any consumer mutation throws loudly instead of corrupting silently.
+     * engine memory; in dev mode a deep-frozen clone, so a mutation throws.
      */
     getSnapshot(options?: {
         redact?: boolean;
     }): RuntimeSnapshot;
-    /**
-     * Collect `toSnapshot()` bundles from every attached recorder — ONE entry
-     * per recorder id, across all channels and both delivery tiers.
-     *
-     * The dedupe is load-bearing, not tidiness. A recorder that implements a
-     * shared-name hook (`onError` / `onPause` / `onResume` — declared on BOTH
-     * the scope and flow interfaces) is legitimately registered on BOTH inline
-     * lists by `attachCombinedRecorder`, and that is by design: each channel
-     * calls the hook with its own payload variant. `MetricRecorder.onPause` is
-     * the everyday case. Walking the lists without a shared `seen` set turned
-     * that into a DUPLICATED snapshot entry (same id twice), which breaks every
-     * consumer that indexes `snapshot.recorders` by id.
-     *
-     * Ordering is scope list → flow list → deferred tier, and the FIRST bundle
-     * for an id wins. A recorder with no `toSnapshot` never claims an id, so it
-     * cannot shadow a same-id recorder that does have one.
-     *
-     * The row is REBUILT field by field by the one copier (`recorder/snapshot.ts
-     * · copyBundle`, shared with `CompositeRecorder`) rather than spread, so a
-     * recorder cannot smuggle an `id` of its own choosing into the snapshot (the
-     * id is the executor's, and consumers index by it).
-     */
-    private collectRecorderSnapshots;
     /** @internal */
     getRuntime(): import("../engine/types.js").IExecutionRuntime;
     /** @internal */