footprintjs 4.16.0 → 4.17.2

package/dist/types/lib/detach/runChild.d.ts

@@ -0,0 +1,41 @@
+/**
+ * detach/runChild.ts — The "how do I actually run a child flowchart?" hook.
+ *
+ * Pattern:  Strategy (GoF). Drivers are decoupled from the FlowChartExecutor
+ *           — each driver is created with a `ChildRunner` it calls to
+ *           materialize the work. Default implementation imports the
+ *           executor lazily so drivers can be picked up by tree-shakers
+ *           that don't pull the runner module into the bundle.
+ * Role:     Glue between drivers and the engine. Without this seam, every
+ *           driver would have to import `FlowChartExecutor` directly,
+ *           creating circular import risk and bundle bloat.
+ *
+ * Why a separate module (not inlined in each driver):
+ *   - DRY — every driver shares the same "instantiate executor, run, return
+ *     result" sequence
+ *   - Allows test code to swap the runner via factory injection without
+ *     having to rebuild the whole driver
+ *   - Future-proofs for the case where we want to inject env/recorders
+ *     into the child (the runner is the natural place to do that)
+ */
+import type { FlowChart } from '../builder/types.js';
+/**
+ * Function the driver calls to actually execute the child flowchart.
+ * Returns a Promise resolving to the chart's terminal value (whatever
+ * `FlowChartExecutor.run()` resolves with), or rejects on failure.
+ *
+ * Drivers wrap this in their own try/catch so the rejection routes to
+ * `handle._markFailed()` instead of escaping into the parent context
+ * (passive-recorder rule).
+ */
+export type ChildRunner = (child: FlowChart, input: unknown) => Promise<unknown>;
+/**
+ * Default runner — instantiates a fresh `FlowChartExecutor` for each
+ * child and awaits its run. Returns the executor's traversal result.
+ *
+ * Lazy-imports `FlowChartExecutor` so drivers that consumers create with
+ * their own runner don't pull the engine into their bundle.
+ *
+ * Uses dynamic import — see https://v8.dev/features/dynamic-import.
+ */
+export declare const defaultRunChild: ChildRunner;

package/dist/types/lib/detach/spawn.d.ts

@@ -0,0 +1,64 @@
+/**
+ * detach/spawn.ts — One-call detach primitive used by both scope and
+ * executor surfaces.
+ *
+ * Pattern:  Facade (GoF). Hides driver invocation + refId minting +
+ *           registry registration behind two named functions
+ *           (`detachAndJoinLater`, `detachAndForget`). Same helper is
+ *           called from `scope.$detachAndJoinLater(...)` and from
+ *           `executor.detachAndJoinLater(...)` — single source of truth.
+ *
+ * Why a separate module:
+ *   - Avoids duplicating the "validate driver, mint refId, call schedule"
+ *     sequence in both scope and executor entry points
+ *   - Keeps the scope/executor files free of driver knowledge — they
+ *     just call this and forward the result
+ *
+ * refId scheme:
+ *   - When the caller is a stage (scope path): refId = `${runtimeStageId}:detach:${counter}`
+ *     — the runtimeStageId prefix lets diagnostics correlate the handle
+ *     back to the source stage
+ *   - When the caller is bare executor (executor path):
+ *     refId = `__executor__:detach:${counter}` — uniform "no source stage"
+ *     marker
+ *   - Counter is module-private + monotonic for the process lifetime —
+ *     safe across re-entrant detach calls
+ */
+import type { FlowChart } from '../builder/types.js';
+import type { DetachDriver, DetachHandle } from './types.js';
+/** Reset the counter for tests — never call from production code. */
+export declare function _resetSpawnCounterForTests(): void;
+/**
+ * Schedule `child` on the given driver, with the consumer's `input`,
+ * and return the resulting `DetachHandle`. Callers can `wait()` on it,
+ * read its `.status` property, or just hold the reference for later.
+ *
+ * **Joinable variant** — the caller wants to be able to await the result
+ * (or check its status). The `forget` variant simply discards the handle.
+ *
+ * @param driver - The driver implementation to use. Required (no
+ *   library-default — passing it explicitly avoids global state and
+ *   keeps the engine free of driver imports).
+ * @param child - The child flowchart to run.
+ * @param input - The input to hand to the child's run() call.
+ * @param sourcePrefix - Refix prefix for the minted refId; pass the
+ *   parent's `runtimeStageId` from a stage caller, or `'__executor__'`
+ *   from a bare-executor caller.
+ */
+export declare function detachAndJoinLater(driver: DetachDriver, child: FlowChart, input: unknown, sourcePrefix: string): DetachHandle;
+/**
+ * Same as `detachAndJoinLater` but discards the handle. Use when the
+ * caller doesn't care about the result and doesn't need to await — e.g.,
+ * fire-and-forget telemetry exports.
+ *
+ * The handle still exists internally (driver creates it, registry holds
+ * it briefly) — but the caller cannot reference it. This is intentional:
+ * having no handle reference is what gives "forget" its semantic — there
+ * is no chance of the caller accidentally awaiting it.
+ *
+ * Errors raised by the child are STILL routed to the handle's failed
+ * state (the driver does that). They just go unobserved unless something
+ * else (a recorder, logging) is wired to surface them. See the docs in
+ * T7 for recommended observability patterns for "forget" detach.
+ */
+export declare function detachAndForget(driver: DetachDriver, child: FlowChart, input: unknown, sourcePrefix: string): void;

package/dist/types/lib/detach/types.d.ts

@@ -0,0 +1,200 @@
+/**
+ * detach/types.ts — Type definitions for the fire-and-forget primitive.
+ *
+ * Pattern:  Strategy + Bridge (GoF). Same shape as cache strategies in
+ *           agentfootprint v2.6 — ONE interface, N concrete drivers,
+ *           consumer picks via explicit import.
+ * Role:     Foundation. Every other detach file imports from here.
+ *           This is the lockable contract; downstream files implement it.
+ *
+ * Two sibling concepts:
+ *
+ *   1. `DetachDriver` — the algorithm that decides WHEN/HOW the work runs.
+ *      Six built-in algorithms ship as algorithm-named exports
+ *      (`microtaskBatchDriver`, `setImmediateDriver`, `sendBeaconDriver`,
+ *      `setTimeoutDriver`, `immediateDriver`, `workerThreadDriver`).
+ *      Consumers can implement their own (BYOS — bring your own driver).
+ *
+ *   2. `DetachHandle` — the consumer-facing handle returned by
+ *      `detachAndJoinLater`. Exposes status as PROPERTIES (sync read)
+ *      and `wait()` (Promise — opt-in async join). Style 2 from the
+ *      panel review: properties for sync, single method for async.
+ *
+ * Naming policy (locked from naming review):
+ *   - Public API uses simple verbs / properties (product-engineer friendly)
+ *   - Internal class names CAN use CS terms (Scheduler, Continuation, etc.)
+ *   - Drivers are algorithm-named (semantic at the algorithm level)
+ *
+ * Locked design decisions (panel review captured in
+ * `docs/inspiration/detach-primitive.md`):
+ *   - Sync hot path; async only at flush boundaries
+ *   - Errors → commitLog + typed event, NEVER thrown to parent
+ *   - Scope isolation between parent and detached child
+ *   - Lifecycle tied to executor disposal
+ *   - Type-level rejection of `outputMapper` on detach options
+ */
+import type { FlowChart } from '../builder/types.js';
+/**
+ * Snapshot of a detached handle's state. Returned by `handle.poll()`
+ * (when added in a follow-up; v1 exposes properties directly on
+ * `DetachHandle`).
+ */
+export interface DetachPollResult {
+    readonly status: DetachHandle['status'];
+    /** Present iff status === 'done'. */
+    readonly result?: unknown;
+    /** Present iff status === 'failed'. */
+    readonly error?: Error;
+}
+/**
+ * Result delivered when the handle's `wait()` Promise resolves
+ * successfully (status reached 'done'). Rejection delivers the
+ * native `Error` directly — no wrapping shape.
+ */
+export interface DetachWaitResult {
+    readonly result: unknown;
+}
+/**
+ * Handle returned by `chart.detachAndJoinLater(...)` and
+ * `executor.detachAndJoinLater(...)`. Exposes status as PROPERTIES so
+ * sync access is property-read (cheap, no allocation). The single
+ * method `wait()` returns a Promise for opt-in async join.
+ *
+ * The handle is **not** Promise-shaped (no `.then()`) — that would
+ * make it accidentally awaitable, defeating the fire-and-forget
+ * semantics. To await, the consumer must call `.wait()` explicitly.
+ *
+ * Lifecycle:
+ *
+ *   queued  → driver received the work, hasn't started it
+ *   running → driver started the work
+ *   done    → terminal: result available
+ *   failed  → terminal: error available
+ *
+ * `done` and `failed` are TERMINAL — once reached, status never
+ * changes again.
+ */
+export interface DetachHandle {
+    /** Stable id assigned at detach time. Used as the lookup key in
+     *  `detachRegistry` and as the scope-storage key prefix. */
+    readonly id: string;
+    /** Current state. Read directly for sync access. */
+    readonly status: 'queued' | 'running' | 'done' | 'failed';
+    /** The work's result. Present iff `status === 'done'`. Reading
+     *  before terminal returns `undefined`. */
+    readonly result?: unknown;
+    /** The work's error. Present iff `status === 'failed'`. Reading
+     *  before terminal returns `undefined`. */
+    readonly error?: Error;
+    /**
+     * Opt-in async join. Returns a Promise that:
+     *   - resolves with `{ result }` when status becomes 'done'
+     *   - rejects with the captured `Error` when status becomes 'failed'
+     *   - resolves/rejects IMMEDIATELY if status is already terminal
+     *   - returns the SAME cached Promise on repeated calls (no
+     *     re-running, no duplicated I/O)
+     *
+     * Calling `wait()` does NOT change the handle's lifecycle — it's
+     * passive observation. If never called, the work still completes;
+     * the handle just goes uncollected (parent execution unaffected).
+     *
+     * Use when:
+     *   - You actually need the result and want to await it
+     *   - Coordinating multiple handles via Promise.all / Promise.race
+     *   - Backpressure ("don't fire more than N in flight")
+     *
+     * Don't use when:
+     *   - Pure fire-and-forget (use `detachAndForget` — no handle returned)
+     *   - You just want to check status (read `handle.status` directly)
+     */
+    wait(): Promise<DetachWaitResult>;
+}
+/**
+ * Capabilities a driver declares. Drives the runtime decision of
+ * "is this driver appropriate for the current environment?" Consumers
+ * inspect at construction; the framework doesn't enforce.
+ *
+ * All capabilities are optional flags — false / undefined means "not
+ * supported / no claim." A driver that supports everything sets all
+ * to true.
+ */
+export interface DriverCapabilities {
+    /** Driver works in browser environments (window, document, etc.). */
+    readonly browserSafe?: boolean;
+    /** Driver works in Node.js environments. */
+    readonly nodeSafe?: boolean;
+    /** Driver works in edge runtimes (Cloudflare Workers, Deno Deploy,
+     *  Bun edge, etc. — restricted environments). */
+    readonly edgeSafe?: boolean;
+    /** Work survives page-unload / process-exit. e.g.,
+     *  `sendBeaconDriver` schedules via `navigator.sendBeacon` which
+     *  ships even on tab close. */
+    readonly survivesUnload?: boolean;
+    /** Work runs on a separate OS thread (no event-loop block).
+     *  e.g., `workerThreadDriver`. */
+    readonly cpuIsolated?: boolean;
+}
+/**
+ * A driver is the WHEN/HOW of the detach. Maps `(child, input, refId)`
+ * to a `DetachHandle` whose lifecycle the driver owns.
+ *
+ * Drivers are themselves footprintjs primitives — internally they may
+ * be a single function or a multi-stage flowChart. Either way, the
+ * interface they expose to consumers is `schedule(...)`.
+ *
+ * Drivers MUST:
+ *   - Return synchronously (the agent loop never blocks on schedule)
+ *   - Not throw — errors during scheduling route through the handle
+ *     (`handle.status = 'failed'`, `handle.error = ...`)
+ *   - Honor the passive-recorder rule: the parent's `detach*` call
+ *     never waits for the driver's deferred work to complete
+ *
+ * Drivers MAY:
+ *   - Implement `validate()` for one-time configuration checks at
+ *     registration / use time (e.g., assert `navigator.sendBeacon` exists)
+ *   - Build their internal pipeline as a footprintjs flowChart for
+ *     observability — driver implementation detail, not consumer-facing
+ *
+ * @example Built-in
+ *   import { microtaskBatchDriver } from 'footprintjs/detach';
+ *   const handle = driver.schedule(child, input, refId);
+ *
+ * @example Custom (BYOS)
+ *   const lambdaExtensionDriver: DetachDriver = {
+ *     name: 'lambda-extension',
+ *     capabilities: { nodeSafe: true, survivesUnload: true },
+ *     schedule(child, input, refId) {
+ *       sharedBuffer.push({ refId, child, input });
+ *       return createHandle(refId, 'queued');
+ *     },
+ *   };
+ */
+export interface DetachDriver {
+    /** Stable name for diagnostics + registry lookup. Conventionally
+     *  algorithm-named (e.g. `'microtask-batch'`, `'send-beacon'`). */
+    readonly name: string;
+    /** What this driver supports. Used by consumers to pick the right
+     *  driver for their environment. */
+    readonly capabilities: DriverCapabilities;
+    /**
+     * Hand the work to the driver's scheduling mechanism. MUST return
+     * synchronously with a fresh `DetachHandle`. The actual work may
+     * run later (next microtask / setImmediate / browser-beacon-flush /
+     * worker-thread / etc.) on the driver's chosen mechanism.
+     */
+    schedule(child: FlowChart, input: unknown, refId: string): DetachHandle;
+    /**
+     * Optional one-time validation hook. Called at first use (or
+     * registration time, depending on driver) — drivers throw if their
+     * configuration is invalid (missing peer dep, unreachable endpoint,
+     * wrong API key shape, etc.).
+     *
+     * Example: `sendBeaconDriver.validate()` checks
+     * `typeof navigator?.sendBeacon === 'function'` and throws with a
+     * helpful message if absent (e.g., in Node).
+     *
+     * Per the New Relic panel review: early-fail-with-useful-message
+     * beats silent zero-emission.
+     */
+    validate?(): void;
+}

package/dist/types/lib/engine/traversal/FlowchartTraverser.d.ts

@@ -18,7 +18,6 @@
  * Break semantics: If a stage calls breakFn(), commit and STOP.
  * Patch model: Stage writes into local patch; commitPatch() after return or throw.
  */
-/// <reference types="node" />
 import type { ScopeProtectionMode } from '../../scope/protection/types.js';
 import { FlowRecorderDispatcher } from '../narrative/FlowRecorderDispatcher.js';
 import type { FlowRecorder, IControlFlowNarrative } from '../narrative/types.js';

package/dist/types/lib/engine/types.d.ts

@@ -4,7 +4,6 @@
  * Centralizes type definitions to avoid circular dependencies.
  * Every handler receives HandlerDeps (the DI bag) instead of importing the traverser.
  */
-/// <reference types="node" />
 import type { StageContext } from '../memory/StageContext.js';
 import type { FlowControlType, FlowMessage } from '../memory/types.js';
 import type { ScopeProtectionMode } from '../scope/protection/types.js';

package/dist/types/lib/reactive/types.d.ts

@@ -31,6 +31,8 @@ export interface ReactiveTarget {
     addMetric(name: string, value: unknown): void;
     addEval(name: string, value: unknown): void;
     emitEvent(name: string, payload?: unknown): void;
+    detachAndJoinLater(driver: import('../detach/types.js').DetachDriver, child: import('../builder/types.js').FlowChart, input?: unknown): import('../detach/types.js').DetachHandle;
+    detachAndForget(driver: import('../detach/types.js').DetachDriver, child: import('../builder/types.js').FlowChart, input?: unknown): void;
 }
 export interface ScopeMethods {
     $getValue(key: string): unknown;
@@ -122,6 +124,8 @@ export interface ScopeMethods {
      * ```
      */
     $emit(name: string, payload?: unknown): void;
+    $detachAndJoinLater(driver: import('../detach/types.js').DetachDriver, child: import('../builder/types.js').FlowChart, input?: unknown): import('../detach/types.js').DetachHandle;
+    $detachAndForget(driver: import('../detach/types.js').DetachDriver, child: import('../builder/types.js').FlowChart, input?: unknown): void;
     /**
      * Stop the current execution context.
      *

package/dist/types/lib/recorder/BoundaryStateTracker.d.ts

@@ -0,0 +1,215 @@
+/**
+ * BoundaryStateTracker<TState> — third storage primitive on the recorder
+ * shelf, alongside `SequenceRecorder<T>` and `KeyedRecorder<T>`.
+ *
+ * **Mental model — observers vs. bookkeepers:**
+ *
+ *   `Recorder` / `FlowRecorder` / `EmitRecorder` / `CombinedRecorder`
+ *     are OBSERVER interfaces — they describe how a recorder hears
+ *     events from the executor.
+ *
+ *   `SequenceRecorder<T>` / `KeyedRecorder<T>` / `BoundaryStateTracker<TState>`
+ *     are STORAGE primitives — three different bookkeeping shelves with
+ *     different durability and indexing properties. A real recorder
+ *     class typically picks ONE observer interface AND ONE storage
+ *     shelf, combining them via `extends + implements`.
+ *
+ * **What this primitive answers:** "At any moment during the run, what
+ * is the LIVE transient state of every currently-active boundary?"
+ *
+ * A "boundary" is a matched event pair `[start, stop]` bracketing an
+ * interval — for example, `(llm_start, llm_end)` for an LLM call,
+ * `(tool_start, tool_end)` for tool execution, `(turn_start, turn_end)`
+ * for an agent turn. Between the brackets, intermediate events evolve
+ * the boundary's state (token chunks accumulating into a partial
+ * answer, args streaming in, etc.). On `stop`, the state clears.
+ *
+ * Algorithmically this is the **DFS bracket-sequence pattern** —
+ * stack-frame state during a graph-traversal interval. Same shape used
+ * by Tarjan's SCC algorithm, tree decomposition, and push-down
+ * automata. The `active` map is the open-brackets stack at any moment.
+ *
+ * **Comparison with the other storage primitives:**
+ *
+ * | Primitive                       | Stores                               | Time scope          | Memory      |
+ * |---------------------------------|--------------------------------------|---------------------|-------------|
+ * | `SequenceRecorder<T>`           | append-only ordered + keyed entries  | durable across run  | O(N events) |
+ * | `KeyedRecorder<T>`              | 1:1 entry per `runtimeStageId`       | durable across run  | O(N steps)  |
+ * | `BoundaryStateTracker<TState>`  | transient bracket-scoped state       | live; clears on stop | O(K active) |
+ *
+ * **When to pick which:**
+ *
+ *   - "I need to keep a permanent log of every event for time-travel"
+ *      → `SequenceRecorder<T>`
+ *   - "I want one durable record per stage execution (e.g., metrics)"
+ *      → `KeyedRecorder<T>`
+ *   - "I need to know what's happening RIGHT NOW inside an in-flight
+ *     boundary (e.g., partial LLM stream, partial tool args)"
+ *      → `BoundaryStateTracker<TState>` (this class)
+ *
+ * **What this is NOT for:**
+ *
+ *   - Time-travel queries ("what was the state at past slider step N?")
+ *     — transient state clears on stop. For time-travel, snapshot the
+ *     state at each emit into a separate `SequenceRecorder<TState>`,
+ *     or wait for a future `BoundarySnapshotRecorder<TState>` primitive.
+ *
+ *   - Aggregations across the whole run (totals, counts) — those are
+ *     `SequenceRecorder.aggregate()` / `KeyedRecorder.aggregate()`.
+ *
+ *   - Stage-level concerns — those use `Recorder.onStageStart` /
+ *     `Recorder.onStageEnd`. This primitive operates at finer
+ *     granularity (events emitted DURING a stage execution).
+ *
+ * **Lifecycle contract — STRICT:**
+ *
+ *   Every `startBoundary(key, ...)` call MUST be paired with a
+ *   `stopBoundary(key)` call. Failure to wire the stop side produces a
+ *   memory leak: the active map grows without bound, and `getAllActive()`
+ *   returns stale entries that look in-flight but aren't. Common cause:
+ *   subclass wires `start` to one event handler and forgets to wire
+ *   `stop`. **Always wire both at the same time.**
+ *
+ *   Dev mode (`enableDevMode()`) detects leaks at `clear()` time —
+ *   warning includes the leaked keys so you can find the missing wiring.
+ *
+ * **Concurrency / nesting:**
+ *
+ *   - Concurrent boundaries (parallel branches with two LLM calls
+ *     active at once) work correctly: each is keyed independently in
+ *     the active map.
+ *   - Nested boundaries of DIFFERENT KINDS (Agent boundary contains
+ *     LLM boundary) require SEPARATE tracker instances — one per kind.
+ *     The base class tracks one boundary kind per instance.
+ *
+ * **Key convention:**
+ *
+ *   The `key: string` is whatever your subclass picks. Convention:
+ *   use `runtimeStageId` when the boundary maps 1:1 to a stage
+ *   execution — this gives free interop with `SequenceRecorder
+ *   .getEntriesForStep`, `KeyedRecorder.getByKey`, `findCommit` /
+ *   `findLastWriter`, and the rest of the trace ecosystem. Use a more
+ *   granular key (e.g., `toolCallId`) only when there are multiple
+ *   concurrent boundaries WITHIN one stage execution.
+ *
+ * @example Build a live LLM tracker (combining storage + observer):
+ *
+ * ```typescript
+ * import {
+ *   BoundaryStateTracker,
+ *   type CombinedRecorder,
+ *   type EmitEvent,
+ * } from 'footprintjs';
+ *
+ * interface LLMLiveState {
+ *   readonly partial: string;
+ *   readonly tokens: number;
+ * }
+ *
+ * class LiveLLMTracker
+ *   extends BoundaryStateTracker<LLMLiveState>   // STORAGE shelf
+ *   implements CombinedRecorder                   // OBSERVER interface
+ * {
+ *   readonly id = 'live-llm';
+ *
+ *   // Observer half — translate events into bracket mutations.
+ *   onEmit(event: EmitEvent): void {
+ *     if (event.name === 'agentfootprint.stream.llm_start') {
+ *       this.startBoundary(event.runtimeStageId, { partial: '', tokens: 0 });
+ *     } else if (event.name === 'agentfootprint.stream.llm_end') {
+ *       this.stopBoundary(event.runtimeStageId);
+ *     } else if (event.name === 'agentfootprint.stream.token') {
+ *       this.updateBoundary(event.runtimeStageId, (s) => ({
+ *         partial: s.partial + (event.payload as { content: string }).content,
+ *         tokens: s.tokens + 1,
+ *       }));
+ *     }
+ *   }
+ *
+ *   // Public read API — O(1) at any moment.
+ *   isInFlight(): boolean { return this.hasActive; }
+ *   getPartial(stageId: string): string {
+ *     return this.getActive(stageId)?.partial ?? '';
+ *   }
+ * }
+ *
+ * // Attached the same way as any other CombinedRecorder.
+ * const tracker = new LiveLLMTracker();
+ * executor.attachCombinedRecorder(tracker);
+ * await executor.run({ input });
+ *
+ * // Read live state at any time during or after the run.
+ * tracker.isInFlight();
+ * tracker.getPartial(rid);
+ * ```
+ */
+export declare abstract class BoundaryStateTracker<TState> {
+    /** Stable id — same idempotency contract as other recorders. */
+    abstract readonly id: string;
+    /** Open-brackets stack: key → current transient state. */
+    private readonly active;
+    /** Per-key count of `updateBoundary` calls that landed without a
+     *  matching active boundary. Drives rate-limited dev-mode warnings
+     *  so a stuck loop doesn't spam the console. */
+    private readonly missedUpdates;
+    /**
+     * Open a new boundary with initial transient state.
+     *
+     * If a boundary with the same `key` is already active, the prior
+     * state is overwritten (last-writer-wins). In dev mode, a warning
+     * is logged because re-starting an active key usually indicates a
+     * missed `stopBoundary` call upstream.
+     *
+     * @param key Boundary identifier — by convention, `runtimeStageId`
+     *            for 1:1-with-stage boundaries, or a more granular id
+     *            (e.g., `toolCallId`) when multiple concurrent boundaries
+     *            run within one stage execution.
+     * @param initial Initial state — typed by `TState`.
+     */
+    protected startBoundary(key: string, initial: TState): void;
+    /**
+     * Evolve the transient state of an active boundary using an updater
+     * function. Silent no-op if no boundary is active for `key`
+     * (defensive against out-of-order events). In dev mode, a rate-limited
+     * warning is logged on the 1st, 10th, and 100th missed update per key.
+     *
+     * @param key      Boundary identifier (must match a prior `startBoundary`).
+     * @param updater  Pure function: previous state → next state.
+     */
+    protected updateBoundary(key: string, updater: (prev: TState) => TState): void;
+    /**
+     * Close the boundary identified by `key` and return its FINAL
+     * transient state (for any cleanup the subclass wants — e.g., emit a
+     * snapshot to a SequenceRecorder for durable storage).
+     *
+     * @param key Boundary identifier.
+     * @returns The final state, or `undefined` if no boundary was active.
+     */
+    protected stopBoundary(key: string): TState | undefined;
+    /** Current transient state of ONE active boundary. `undefined` if no
+     *  boundary is active for `key`. */
+    getActive(key: string): TState | undefined;
+    /**
+     * All currently-active boundaries.
+     *
+     * **Type-only readonly:** the returned reference IS the internal Map.
+     * TypeScript prevents mutation through the `ReadonlyMap` type, but a
+     * runtime cast or non-TS consumer can mutate it and corrupt internal
+     * state. **Do not mutate.**
+     */
+    getAllActive(): ReadonlyMap<string, TState>;
+    /** True if any boundary is currently active. O(1). */
+    get hasActive(): boolean;
+    /** Number of currently-active boundaries. O(1). */
+    get activeCount(): number;
+    /**
+     * Reset all transient state. Called by executors before each `run()`
+     * so consumers get a clean slate per run — same lifecycle contract
+     * as `SequenceRecorder.clear()`.
+     *
+     * In dev mode, warns if any boundaries are still active when called
+     * — likely indicates a missed `stopBoundary` upstream. The leaked
+     * keys are listed (truncated to 10) so the wiring bug is findable.
+     */
+    clear(): void;
+}

package/dist/types/lib/recorder/index.d.ts

@@ -1,3 +1,4 @@
+export { BoundaryStateTracker } from './BoundaryStateTracker.js';
 export type { CombinedRecorder } from './CombinedRecorder.js';
 export { hasEmitRecorderMethods, hasFlowRecorderMethods, hasRecorderMethods, isFlowEvent } from './CombinedRecorder.js';
 export type { CompositeSnapshot } from './CompositeRecorder.js';

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

@@ -228,6 +228,34 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * ```
      */
     attachRecorder(recorder: Recorder): void;
+    /**
+     * 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. */
     detachRecorder(id: string): void;
     /** Returns a defensive copy of attached scope Recorders. */

package/dist/types/lib/scope/ScopeFacade.d.ts

@@ -100,6 +100,10 @@ export declare class ScopeFacade {
      * the method routes here via `createTypedScope`.
      */
     emitEvent(name: string, payload: unknown): void;
+    /** See `ScopeMethods.$detachAndJoinLater`. */
+    detachAndJoinLater(driver: import('../detach/types.js').DetachDriver, child: import('../builder/types.js').FlowChart, input?: unknown): import('../detach/types.js').DetachHandle;
+    /** See `ScopeMethods.$detachAndForget`. */
+    detachAndForget(driver: import('../detach/types.js').DetachDriver, child: import('../builder/types.js').FlowChart, input?: unknown): void;
     /**
      * Build the subflowPath (outer → inner) for event enrichment.
      *

package/dist/types/lib/scope/state/zod/utils/validateHelper.d.ts

@@ -6,7 +6,19 @@
 import { type ZodRecord, type ZodTypeAny } from 'zod';
 /** Check if the value is a Zod schema node. */
 export declare function isZodNode(x: unknown): x is ZodTypeAny;
-/** Peel wrappers; returns the underlying base Zod node (or null). */
+/** Peel wrappers; returns the underlying base Zod node (or null).
+ *
+ *  Wrapper-aware: only descends through fields that are KNOWN to hold
+ *  the inner schema for wrapper Zod types (Optional, Default, Nullable,
+ *  Effects/Pipeline). Notably, `_def.type` is treated as the inner
+ *  schema ONLY for v3 Effects/Pipeline — it is NOT the inner schema
+ *  for ZodArray (where `_def.type` holds the ELEMENT schema, which is
+ *  a separate concern from wrapper unwrapping).
+ *
+ *  Without this gate, `unwrap(z.array(z.string()))` would incorrectly
+ *  follow `_def.type` and return `ZodString`, breaking array detection
+ *  in `scopeFactory.analyze()`.
+ */
 export declare function unwrap(schema: ZodTypeAny | null | undefined): ZodTypeAny | null;
 /** Version-tolerant access to ZodRecord value schema. */
 export declare function getRecordValueType(rec: ZodRecord<any, any>): ZodTypeAny | null;

package/dist/types/trace.d.ts

@@ -27,6 +27,7 @@ export type { CausalChainOptions, CausalNode, KeysReadLookup } from './lib/memor
 export { causalChain, flattenCausalDAG, formatCausalChain } from './lib/memory/backtrack.js';
 export { KeyedRecorder } from './lib/recorder/KeyedRecorder.js';
 export { SequenceRecorder } from './lib/recorder/SequenceRecorder.js';
+export { BoundaryStateTracker } from './lib/recorder/BoundaryStateTracker.js';
 export type { Topology, TopologyEdge, TopologyIncomingKind, TopologyNode, TopologyRecorderOptions, } from './lib/recorder/TopologyRecorder.js';
 export { TopologyRecorder, topologyRecorder } from './lib/recorder/TopologyRecorder.js';
 export type { InOutEntry, InOutPhase, InOutRecorderOptions } from './lib/recorder/InOutRecorder.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "footprintjs",
-  "version": "4.16.0",
+  "version": "4.17.2",
   "description": "Explainable backend flows — automatic causal traces, decision evidence, and MCP tool generation for AI agents",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -88,6 +88,11 @@
       "types": "./dist/types/trace.d.ts",
       "import": "./dist/esm/trace.js",
       "require": "./dist/trace.js"
+    },
+    "./detach": {
+      "types": "./dist/types/detach.d.ts",
+      "import": "./dist/esm/detach.js",
+      "require": "./dist/detach.js"
     }
   },
   "lint-staged": {