footprintjs 4.12.2 → 4.13.0

package/dist/types/index.d.ts

@@ -45,10 +45,33 @@ export { MetricRecorder } from './lib/scope/index.js';
 export { DebugRecorder } from './lib/scope/index.js';
 /** @category Observe — Operation */
 export { RecorderOperation } from './lib/recorder/index.js';
+/** @category Observe — Combined (both data-flow and control-flow) */
+export type { CombinedRecorder } from './lib/recorder/index.js';
+/** @category Observe — Combined (both data-flow and control-flow) */
+export { hasEmitRecorderMethods, hasFlowRecorderMethods, hasRecorderMethods, isFlowEvent, } from './lib/recorder/index.js';
+/**
+ * @category Observe — Emit (user-authored structured events)
+ *
+ * Third observer channel (alongside `Recorder` and `FlowRecorder`). Consumer
+ * code calls `scope.$emit(name, payload)` from inside a stage; every attached
+ * `EmitRecorder.onEmit(event)` fires synchronously with stage-context
+ * enrichment. Pass-through — no buffering, zero allocation when no recorder
+ * is attached.
+ */
+export type { EmitEvent, EmitRecorder } from './lib/recorder/index.js';
 /** @category Observe — Flow */
 export type { FlowBreakEvent, FlowDecisionEvent, FlowErrorEvent, FlowForkEvent, FlowLoopEvent, FlowNextEvent, FlowRecorder, FlowSelectedEvent, FlowStageEvent, FlowSubflowEvent, FlowSubflowRegisteredEvent, TraversalContext, } from './lib/engine/index.js';
 /** @category Observe — Flow */
 export type { CombinedNarrativeEntry } from './lib/engine/index.js';
+/**
+ * @category Observe — Flow
+ *
+ * `NarrativeFormatter` — pluggable formatter that converts event context
+ * objects into the text lines of the narrative. Prefer this name in new
+ * code; `NarrativeRenderer` is a deprecated alias that will be removed in
+ * the next major release.
+ */
+export type { NarrativeFormatter, NarrativeRenderer } from './lib/engine/index.js';
 /** @category Observe — Flow */
 export { NarrativeFlowRecorder } from './lib/engine/index.js';
 /** @category Observe — Flow */
@@ -98,7 +121,18 @@ export { InputValidationError, validateAgainstSchema, validateOrThrow } from './
 export type { StructuredErrorInfo } from './lib/engine/index.js';
 /** @category Error Utilities */
 export { extractErrorInfo, formatErrorInfo } from './lib/engine/index.js';
-/** @category Dev Tools */
-export { disableDevMode, enableDevMode } from './lib/scope/detectCircular.js';
+/**
+ * @category Dev Tools
+ *
+ * Global dev-mode flag. Call `enableDevMode()` at application startup to
+ * turn on developer-only diagnostics across the library — circular-reference
+ * detection in scope writes, warnings when a recorder has no observer
+ * methods, suspicious-predicate warnings in decide/select, structural
+ * checks in `getSubtreeSnapshot`, and any future dev-only diagnostic.
+ *
+ * Production leaves it OFF by default (zero overhead). See the JSDoc on
+ * `enableDevMode` for the full list and usage example.
+ */
+export { disableDevMode, enableDevMode, isDevMode } from './lib/scope/detectCircular.js';
 /** @category Dev Tools */
 export { defineScopeFromZod } from './lib/scope/index.js';

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

@@ -74,12 +74,9 @@ export type StageNode<TOut = any, TScope = any> = {
      * to distinguish runtime graph field from the JSON-safe spec field).
      */
     isLoopRef?: boolean;
-    /** Inline subflow definition for dynamic subflow attachment.
-     *  When `root` is omitted, the subflow is structural-only:
-     *  the engine attaches `buildTimeStructure` for visualization
-     *  without executing any subflow stages (pre-executed subflow pattern). */
+    /** Inline subflow definition for dynamic subflow attachment. */
     subflowDef?: {
-        root?: StageNode;
+        root: StageNode;
         stageMap?: Map<string, StageFunction<TOut, TScope>>;
         buildTimeStructure?: unknown;
         subflows?: Record<string, {
@@ -104,8 +101,7 @@ export type StageNode<TOut = any, TScope = any> = {
  * Uses duck-typing: must have `name` (string) AND at least one continuation
  * property (non-empty children, next, nextNodeSelector, or isSubflowRoot).
  *
- * `isSubflowRoot` counts as continuation because subflow execution (or
- * structural annotation for pre-executed subflows) is a form of continuation.
+ * `isSubflowRoot` counts as continuation because subflow execution is a form of continuation.
  *
  * Safely handles proxy objects (e.g., Zod scope) that may throw on property access.
  */

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

@@ -16,6 +16,7 @@ import type { StageContext } from '../../memory/StageContext.js';
 import type { StageNode } from '../graph/StageNode.js';
 import type { TraversalContext } from '../narrative/types.js';
 import type { HandlerDeps, SubflowResult, SubflowTraverserFactory } from '../types.js';
+import type { BreakFlag } from './types.js';
 export declare class SubflowExecutor<TOut = any, TScope = any> {
     private deps;
     private traverserFactory;
@@ -29,7 +30,5 @@ export declare class SubflowExecutor<TOut = any, TScope = any> {
      * 4. Applies output mapping to write results back to parent scope
      * 5. Stores execution data for debugging/visualization
      */
-    executeSubflow(node: StageNode<TOut, TScope>, parentContext: StageContext, breakFlag: {
-        shouldBreak: boolean;
-    }, branchPath: string | undefined, subflowResultsMap: Map<string, SubflowResult>, parentTraversalContext?: TraversalContext): Promise<any>;
+    executeSubflow(node: StageNode<TOut, TScope>, parentContext: StageContext, breakFlag: BreakFlag, branchPath: string | undefined, subflowResultsMap: Map<string, SubflowResult>, parentTraversalContext?: TraversalContext): Promise<any>;
 }

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

@@ -8,10 +8,26 @@
 import type { StageContext } from '../../memory/StageContext.js';
 import type { StageNode } from '../graph/StageNode.js';
 import type { StageFunction } from '../types.js';
-/** Recursive node execution — avoids circular dep with FlowchartTraverser. */
-export type ExecuteNodeFn<TOut = any, TScope = any> = (node: StageNode<TOut, TScope>, context: StageContext, breakFlag: {
+/**
+ * Traverser break flag — mutable struct passed through the traversal recursion.
+ *
+ * `shouldBreak` flips when any stage calls `scope.$break()`. The traverser
+ * checks this before scheduling the next node; when set, the stack unwinds
+ * cleanly without running subsequent stages.
+ *
+ * `reason` is the optional string argument passed to `$break(reason)`. It
+ * travels alongside `shouldBreak` so downstream code (FlowRecorder onBreak
+ * events, subflow-propagation to parent scope) can surface the reason.
+ *
+ * Adding fields here is backward compatible — existing callers only read
+ * `shouldBreak`, and `reason` is optional.
+ */
+export interface BreakFlag {
     shouldBreak: boolean;
-}, branchPath?: string) => Promise<any>;
+    reason?: string;
+}
+/** Recursive node execution — avoids circular dep with FlowchartTraverser. */
+export type ExecuteNodeFn<TOut = any, TScope = any> = (node: StageNode<TOut, TScope>, context: StageContext, breakFlag: BreakFlag, branchPath?: string) => Promise<any>;
 /** Run a stage function with commit + extractor. */
 export type RunStageFn<TOut = any, TScope = any> = (node: StageNode<TOut, TScope>, stageFunc: StageFunction<TOut, TScope>, context: StageContext, breakFn: () => void) => Promise<TOut>;
 /** Call the traversal extractor after stage execution. */

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

@@ -9,7 +9,7 @@ export { FlowchartTraverser } from './traversal/FlowchartTraverser.js';
 export { isStageNodeReturn } from './graph/StageNode.js';
 export * from './types.js';
 export * from './handlers/index.js';
-export type { CombinedNarrativeEntry, CombinedNarrativeOptions } from './narrative/narrativeTypes.js';
+export type { CombinedNarrativeEntry, CombinedNarrativeOptions, EmitRenderContext, NarrativeFormatter, NarrativeRenderer, } from './narrative/narrativeTypes.js';
 export { NullControlFlowNarrativeGenerator } from './narrative/NullControlFlowNarrativeGenerator.js';
 export type { IControlFlowNarrative } from './narrative/types.js';
 export { FlowRecorderDispatcher } from './narrative/FlowRecorderDispatcher.js';

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

@@ -2,8 +2,8 @@
  * CombinedNarrativeRecorder — Inline narrative builder that merges flow + data during traversal.
  *
  * Extends SequenceRecorder<CombinedNarrativeEntry> for dual-indexed storage (ordered sequence
- * + O(1) per-step lookup by runtimeStageId). Implements BOTH FlowRecorder (control-flow events)
- * and Recorder (scope data events).
+ * + O(1) per-step lookup by runtimeStageId). Implements `CombinedRecorder` — the library's
+ * first-class abstraction for observers that span both data-flow and control-flow streams.
  *
  * Event ordering guarantees this works:
  *   1. Scope events (onRead, onWrite) fire DURING stage execution
@@ -13,10 +13,12 @@
  * So we buffer scope ops per-stage, then when the flow event arrives,
  * emit the stage entry + flush the buffered ops in one pass.
  */
+import type { CombinedRecorder } from '../../recorder/CombinedRecorder.js';
+import type { EmitEvent } from '../../recorder/EmitRecorder.js';
 import { SequenceRecorder } from '../../recorder/SequenceRecorder.js';
-import type { ReadEvent, Recorder, WriteEvent } from '../../scope/types.js';
+import type { ErrorEvent, PauseEvent, ReadEvent, ResumeEvent, WriteEvent } from '../../scope/types.js';
 import type { CombinedNarrativeEntry, NarrativeRenderer } from './narrativeTypes.js';
-import type { FlowBreakEvent, FlowDecisionEvent, FlowErrorEvent, FlowForkEvent, FlowLoopEvent, FlowPauseEvent, FlowRecorder, FlowResumeEvent, FlowSelectedEvent, FlowStageEvent, FlowSubflowEvent } from './types.js';
+import type { FlowBreakEvent, FlowDecisionEvent, FlowErrorEvent, FlowForkEvent, FlowLoopEvent, FlowPauseEvent, FlowResumeEvent, FlowSelectedEvent, FlowStageEvent, FlowSubflowEvent } from './types.js';
 export interface CombinedNarrativeRecorderOptions {
     includeStepNumbers?: boolean;
     includeValues?: boolean;
@@ -28,7 +30,19 @@ export interface CombinedNarrativeRecorderOptions {
      *  fall back to the default English renderer. See NarrativeRenderer docs. */
     renderer?: NarrativeRenderer;
 }
-export declare class CombinedNarrativeRecorder extends SequenceRecorder<CombinedNarrativeEntry> implements FlowRecorder, Recorder {
+/**
+ * Implements `CombinedRecorder` — the library's first-class abstraction for
+ * observers that span both data-flow (`Recorder`) and control-flow
+ * (`FlowRecorder`) streams. One `id`, routed to both channels via
+ * `executor.attachCombinedRecorder(...)` (or equivalently via
+ * `executor.enableNarrative(...)` which auto-creates an instance).
+ *
+ * For shared-method-name events (`onError`, `onPause`, `onResume`) the
+ * handler accepts the union payload type; we discriminate via `isFlowEvent`.
+ * Scope variants of these events are deliberately ignored here — the
+ * narrative only surfaces control-flow lifecycle events.
+ */
+export declare class CombinedNarrativeRecorder extends SequenceRecorder<CombinedNarrativeEntry> implements CombinedRecorder {
     readonly id: string;
     /**
      * Pending scope ops keyed by runtimeStageId. Flushed in onStageExecuted/onDecision.
@@ -62,18 +76,25 @@ export declare class CombinedNarrativeRecorder extends SequenceRecorder<Combined
     onSubflowExit(event: FlowSubflowEvent): void;
     onLoop(event: FlowLoopEvent): void;
     onBreak(event: FlowBreakEvent): void;
-    onPause(event: FlowPauseEvent | {
-        stageName?: string;
-        stageId?: string;
-    }): void;
-    onResume(event: FlowResumeEvent | {
-        stageName?: string;
-        stageId?: string;
-    }): void;
-    onError(event: FlowErrorEvent | {
-        stageName?: string;
-        message?: string;
-    }): void;
+    onPause(event: PauseEvent | FlowPauseEvent): void;
+    onResume(event: ResumeEvent | FlowResumeEvent): void;
+    onError(event: ErrorEvent | FlowErrorEvent): void;
+    /**
+     * Receive a consumer-emitted event from `scope.$emit(name, payload)`.
+     *
+     * Buffered alongside `onRead`/`onWrite` per-stage so that the final
+     * narrative preserves ordering:
+     *
+     *   1. stage header (emitted by `onStageExecuted` / `onDecision`)
+     *   2. buffered ops for that stage — in call order — flushed right after
+     *
+     * Without buffering, emit events would fire BEFORE the stage header
+     * (which only lands at `onStageExecuted`), producing out-of-order
+     * narrative entries. Flush happens in `flushOps` which routes `emit`-
+     * typed buffered ops through `renderEmit` instead of `renderOp`.
+     */
+    onEmit(event: EmitEvent): void;
+    private defaultRenderEmit;
     /** Returns formatted narrative lines (same output as CombinedNarrativeBuilder.build). */
     getNarrative(indent?: string): string[];
     /**

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

@@ -30,7 +30,7 @@ export declare class FlowRecorderDispatcher implements IControlFlowNarrative {
     onSubflowExit(subflowName: string, subflowId?: string, traversalContext?: TraversalContext, outputState?: Record<string, unknown>): void;
     onSubflowRegistered(subflowId: string, name: string, description?: string, specStructure?: unknown): void;
     onLoop(targetStage: string, iteration: number, description?: string, traversalContext?: TraversalContext): void;
-    onBreak(stageName: string, traversalContext?: TraversalContext): void;
+    onBreak(stageName: string, traversalContext?: TraversalContext, reason?: string, propagatedFromSubflow?: string): void;
     onError(stageName: string, errorMessage: string, error: unknown, traversalContext?: TraversalContext): void;
     onPause(stageName: string, stageId: string, pauseData: unknown, subflowPath: readonly string[], traversalContext?: TraversalContext): void;
     onResume(stageName: string, stageId: string, hasInput: boolean, traversalContext?: TraversalContext): void;

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

@@ -1,6 +1,6 @@
 export type { CombinedNarrativeRecorderOptions } from './CombinedNarrativeRecorder.js';
 export { CombinedNarrativeRecorder } from './CombinedNarrativeRecorder.js';
-export type { BreakRenderContext, CombinedNarrativeEntry, CombinedNarrativeOptions, DecisionRenderContext, ErrorRenderContext, ForkRenderContext, LoopRenderContext, NarrativeRenderer, OpRenderContext, SelectedRenderContext, StageRenderContext, SubflowRenderContext, } from './narrativeTypes.js';
+export type { BreakRenderContext, CombinedNarrativeEntry, CombinedNarrativeOptions, DecisionRenderContext, EmitRenderContext, ErrorRenderContext, ForkRenderContext, LoopRenderContext, NarrativeFormatter, NarrativeRenderer, OpRenderContext, SelectedRenderContext, StageRenderContext, SubflowRenderContext, } from './narrativeTypes.js';
 export { NullControlFlowNarrativeGenerator } from './NullControlFlowNarrativeGenerator.js';
 export type { IControlFlowNarrative } from './types.js';
 export { FlowRecorderDispatcher } from './FlowRecorderDispatcher.js';

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

@@ -6,7 +6,7 @@
  * Use CombinedNarrativeRecorder (auto-attached by setEnableNarrative()) instead.
  */
 export interface CombinedNarrativeEntry {
-    type: 'stage' | 'step' | 'condition' | 'fork' | 'selector' | 'subflow' | 'loop' | 'break' | 'error' | 'pause' | 'resume';
+    type: 'stage' | 'step' | 'condition' | 'fork' | 'selector' | 'subflow' | 'loop' | 'break' | 'error' | 'pause' | 'resume' | 'emit';
     text: string;
     depth: number;
     stageName?: string;
@@ -102,11 +102,42 @@ export interface ErrorRenderContext {
     validationIssues?: string;
 }
 /**
- * Pluggable renderer for customizing narrative output.
+ * Context passed to `NarrativeFormatter.renderEmit` — fires for every
+ * consumer-emitted event (`scope.$emit(name, payload)`). Carries the full
+ * `EmitEvent` shape so formatters can render name + payload with full
+ * context.
+ */
+export interface EmitRenderContext {
+    name: string;
+    payload: unknown;
+    stageName: string;
+    runtimeStageId: string;
+    subflowPath: readonly string[];
+    pipelineId: string;
+    timestamp: number;
+    /** Summary string — the library's default truncated payload preview. */
+    payloadSummary: string;
+}
+/**
+ * Pluggable formatter for narrative output. Turns structured event context
+ * objects into the text lines that make up the narrative array.
+ *
+ * ## Why "Formatter", not "Renderer"
+ *
+ * In web terminology "renderer" usually means "turn data into a visible UI"
+ * (pixels, DOM, HTML). This interface does something smaller: it converts
+ * event context into a text string. That is more accurately called a
+ * *formatter* — hence the new name. The legacy alias `NarrativeRenderer`
+ * is preserved for backward compatibility and marked `@deprecated`; it will
+ * be removed in the next major release.
+ *
+ * ## Behaviour
  *
  * Each method is optional — unimplemented methods fall back to the default
- * English renderer. Return null from renderOp to exclude an entry entirely.
+ * English formatter. Return `null` from `renderOp` to exclude that entry
+ * from the narrative entirely.
  *
+ * @example
  * ```typescript
  * const rec = narrative({
  *   renderer: {
@@ -118,10 +149,21 @@ export interface ErrorRenderContext {
  * });
  * ```
  */
-export interface NarrativeRenderer {
+export interface NarrativeFormatter {
     renderStage?(ctx: StageRenderContext): string;
-    /** Return null to exclude the op from the narrative. */
-    renderOp?(ctx: OpRenderContext): string | null;
+    /**
+     * Format an op (scope read/write, or subflow-input key) into a narrative line.
+     *
+     *   - `string`    → use as the narrative line
+     *   - `null`      → deliberately exclude this entry from the narrative
+     *   - `undefined` → this formatter does not handle this op; fall back to
+     *                   the library's default template
+     *
+     * The `undefined` return lets a domain-aware formatter handle only the
+     * keys it knows about and leave the rest to the library default — without
+     * having to re-implement the whole default inline.
+     */
+    renderOp?(ctx: OpRenderContext): string | null | undefined;
     renderDecision?(ctx: DecisionRenderContext): string;
     renderFork?(ctx: ForkRenderContext): string;
     renderSelected?(ctx: SelectedRenderContext): string;
@@ -129,4 +171,26 @@ export interface NarrativeRenderer {
     renderLoop?(ctx: LoopRenderContext): string;
     renderBreak?(ctx: BreakRenderContext): string;
     renderError?(ctx: ErrorRenderContext): string;
+    /**
+     * Format a consumer-emitted event (from `scope.$emit(name, payload)`)
+     * into a narrative line.
+     *
+     *   - `string`    → use as the narrative line
+     *   - `null`      → deliberately exclude this entry
+     *   - `undefined` → this formatter does not handle this emit; fall back
+     *                   to the library's default template
+     *
+     * Typical pattern: switch on `ctx.name` (or a prefix of it) and return a
+     * domain-specific text line for the event types you care about; return
+     * `undefined` for everything else so the default template handles it.
+     */
+    renderEmit?(ctx: EmitRenderContext): string | null | undefined;
 }
+/**
+ * @deprecated Renamed to `NarrativeFormatter` for clarity — this interface
+ * formats event context into text lines, not "render to UI". Legacy alias
+ * kept for backward compatibility; will be removed in the next major
+ * release. Migrate by replacing `NarrativeRenderer` with
+ * `NarrativeFormatter` at imports — no behavioural change.
+ */
+export type NarrativeRenderer = NarrativeFormatter;

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

@@ -32,8 +32,16 @@ export interface IControlFlowNarrative {
     onSubflowRegistered(subflowId: string, name: string, description?: string, specStructure?: unknown): void;
     /** Called on loop iteration (back-edge traversal). */
     onLoop(targetStage: string, iteration: number, description?: string, traversalContext?: TraversalContext): void;
-    /** Called when a stage triggers break (early termination). */
-    onBreak(stageName: string, traversalContext?: TraversalContext): void;
+    /**
+     * Called when a stage triggers break (early termination).
+     *
+     * @param reason - Optional string passed to `scope.$break(reason)`.
+     * @param propagatedFromSubflow - When set, this break was raised on the
+     *   parent because an inner subflow (this id) broke with `propagateBreak`
+     *   enabled. Used by recorders to distinguish originating vs propagated
+     *   breaks and render them accordingly.
+     */
+    onBreak(stageName: string, traversalContext?: TraversalContext, reason?: string, propagatedFromSubflow?: string): void;
     /** Called when a stage throws an error. Raw error is extracted into structured details. */
     onError(stageName: string, errorMessage: string, error: unknown, traversalContext?: TraversalContext): void;
     /** Called when a pausable stage pauses execution. */
@@ -146,6 +154,20 @@ export interface FlowLoopEvent {
 export interface FlowBreakEvent {
     stageName: string;
     traversalContext?: TraversalContext;
+    /**
+     * Optional free-form reason supplied by `scope.$break(reason)`. Absent
+     * when the stage invoked `$break()` without an argument. Propagates when
+     * a subflow is mounted with `propagateBreak: true` — the outer break
+     * event carries the inner break's reason too.
+     */
+    reason?: string;
+    /**
+     * When true, this break event was raised on the PARENT because an inner
+     * subflow's break propagated up (via `SubflowMountOptions.propagateBreak`).
+     * The originating inner break fires its own `onBreak` event separately
+     * — this flag lets recorders distinguish the two.
+     */
+    propagatedFromSubflow?: string;
 }
 /** Event passed to FlowRecorder.onError. */
 export interface FlowErrorEvent {

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

@@ -135,7 +135,25 @@ export declare class FlowchartTraverser<TOut = any, TScope = any> {
      */
     private createSubflowTraverserFactory;
     private createDeps;
+    /**
+     * Holds the top-level break flag for the duration of `execute()`. Kept as
+     * a field (not a local) so `getBreakState()` can surface the final state
+     * for callers like `SubflowExecutor` that implement `propagateBreak`.
+     */
+    private _topBreakFlag;
     execute(branchPath?: string): Promise<TraversalResult>;
+    /**
+     * Break state captured at the top-level of the most recent `execute()`.
+     * `shouldBreak` is true when a stage called `scope.$break(reason)`; the
+     * optional `reason` carries the string passed to `$break`.
+     *
+     * Used by `SubflowExecutor` to propagate an inner subflow's break up to
+     * the parent traverser when the mount sets `propagateBreak: true`.
+     */
+    getBreakState(): {
+        shouldBreak: boolean;
+        reason?: string;
+    };
     getRuntimeStructure(): SerializedPipelineStructure | undefined;
     getSnapshot(): {
         sharedState: Record<string, unknown>;

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

@@ -89,6 +89,57 @@ export interface SubflowMountOptions<TParentScope = any, TSubflowInput = any, TS
      * @default ArrayMergeMode.Concat
      */
     arrayMerge?: ArrayMergeMode;
+    /**
+     * When `true`, an inner `scope.$break(reason)` call inside this subflow
+     * propagates up to the parent — i.e., the parent's `breakFlag` is set
+     * after the subflow exits, terminating the parent's outer loop too.
+     *
+     * **Default: `false`** (current behaviour — inner break stops only the
+     * subflow; parent continues).
+     *
+     * ## When to use
+     *
+     * Set `propagateBreak: true` on subflow mounts that represent
+     * **terminal** branches — "if this subflow fires, the outer loop is
+     * done". Examples:
+     *
+     * - A human-review runner that takes over from an agent's tool-calling
+     *   loop and produces the final response.
+     * - A safety-gate subflow that halts the outer workflow when a policy
+     *   violation is detected.
+     * - An error-recovery subflow that restores state and then terminates.
+     *
+     * ## Semantics
+     *
+     * 1. Inside the subflow, a stage calls `scope.$break(reason)`.
+     * 2. The subflow's own execution stops (normal `$break` behaviour).
+     * 3. `SubflowExecutor` inspects the subflow's exit state. If
+     *    `propagateBreak === true` AND the inner break fired, it forwards
+     *    the break (and its reason) to the parent's `breakFlag`.
+     * 4. The parent traverser sees `shouldBreak` on its next step and exits.
+     * 5. A `FlowRecorder.onBreak` event fires at the parent-mount level with
+     *    `propagatedFromSubflow` = the subflow's id and the inner reason.
+     *
+     * ## Parallel/fan-out
+     *
+     * Follows the existing library rule in `ChildrenExecutor`: the parent
+     * breaks only when **every** child of a fork broke. A single
+     * `propagateBreak: true` subflow contributing its break to the count
+     * does not on its own terminate the parent fan-out.
+     *
+     * ## outputMapper still runs
+     *
+     * The subflow's `outputMapper` (if supplied) ALWAYS runs before the
+     * break propagates, so the subflow's partial state is still written to
+     * the parent scope. This is intentional — the typical use case is an
+     * "escalation" subflow whose output IS the final answer that needs to
+     * land in the parent scope before the outer loop terminates. If you
+     * want to suppress output mapping on break, check the break state
+     * inside your `outputMapper` and return `{}` early.
+     *
+     * @default false
+     */
+    propagateBreak?: boolean;
 }
 export interface SubflowResult {
     subflowId: string;
@@ -131,6 +182,21 @@ export interface SubflowTraverserHandle<TOut = any, TScope = any> {
     execute(): Promise<TraversalResult>;
     /** Collect nested subflow results (from subflows mounted inside this subflow). */
     getSubflowResults(): Map<string, SubflowResult>;
+    /**
+     * Final break state of the subflow after `execute()` returns.
+     *
+     *   - `shouldBreak: true`  → a stage inside the subflow called
+     *     `scope.$break(reason)`, stopping the subflow's own traversal.
+     *   - `reason`             → the optional string passed to `$break`.
+     *
+     * Used by `SubflowExecutor` to implement `SubflowMountOptions.propagateBreak`:
+     * if the mount opts in AND the subflow broke, the parent's break flag is
+     * forwarded.
+     */
+    getBreakState(): {
+        shouldBreak: boolean;
+        reason?: string;
+    };
 }
 /**
  * IExecutionRuntime — Interface for the runtime environment.

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

@@ -30,6 +30,7 @@ export interface ReactiveTarget {
     addErrorInfo(key: string, value: unknown): void;
     addMetric(name: string, value: unknown): void;
     addEval(name: string, value: unknown): void;
+    emitEvent(name: string, payload?: unknown): void;
 }
 export interface ScopeMethods {
     $getValue(key: string): unknown;
@@ -83,13 +84,70 @@ export interface ScopeMethods {
      * when element types are known: `(arr as string[]).push(x)`.
      */
     $batchArray(key: string, fn: (arr: unknown[]) => void): void;
-    $break(): void;
+    /**
+     * Fire a structured event to every attached recorder implementing
+     * `onEmit`. The primary primitive for consumer-authored observability
+     * events (LLM tokens, billing metrics, domain milestones, etc.) that
+     * shouldn't live in scope state.
+     *
+     * Synchronous, pass-through — delivered to recorders immediately, in
+     * call order. Zero-allocation when no recorders are attached.
+     *
+     * ## Naming convention
+     *
+     * Use hierarchical dotted names: `'<namespace>.<category>.<event>'`.
+     * Examples:
+     *   - `'agentfootprint.llm.tokens'`
+     *   - `'myapp.billing.spend'`
+     *   - `'auth.check.denied'`
+     *
+     * The library stays vocabulary-agnostic — no central registry, no
+     * reserved prefixes. Namespace prefixes prevent collisions across
+     * libraries and apps naturally.
+     *
+     * ## Redaction
+     *
+     * If `RedactionPolicy.emitPatterns` matches the name, the payload is
+     * replaced with `'[REDACTED]'` before dispatch. No recorder ever sees
+     * the raw value for redacted event names.
+     *
+     * @param name - Consumer-chosen event identifier (see naming convention).
+     * @param payload - Structured data to attach. Shape is up to the
+     *   consumer; library treats it as opaque.
+     *
+     * @example
+     * ```typescript
+     * scope.$emit('agentfootprint.llm.tokens', { input: 100, output: 50 });
+     * scope.$emit('myapp.decision', { branch: 'approved', confidence: 0.92 });
+     * ```
+     */
+    $emit(name: string, payload?: unknown): void;
+    /**
+     * Stop the current execution context.
+     *
+     * - **In a top-level chart:** the traverser exits cleanly after this stage
+     *   completes.
+     * - **Inside a subflow:** by default, only the subflow's own execution
+     *   stops; control returns to the parent as normal. If the subflow is
+     *   mounted with `propagateBreak: true`, the break signal (and its
+     *   optional reason) propagates up to the parent scope, terminating the
+     *   outer loop too. See `SubflowMountOptions.propagateBreak`.
+     *
+     * @param reason - Optional free-form string describing why the break
+     *   happened. Propagates to `FlowBreakEvent.reason` so recorders and
+     *   custom narratives can surface it. Defaults to undefined.
+     */
+    $break(reason?: string): void;
     $toRaw(): ReactiveTarget;
 }
 export type TypedScope<T extends object = Record<string, unknown>> = T & ScopeMethods;
 export interface ReactiveOptions {
-    /** Pipeline break function -- injected by StageRunner after scope creation. */
-    breakPipeline?: () => void;
+    /**
+     * Pipeline break function — injected by StageRunner after scope creation.
+     * Accepts an optional reason string that propagates to `FlowBreakEvent`
+     * and (when `propagateBreak` is set on a mount) up to the parent scope.
+     */
+    breakPipeline?: (reason?: string) => void;
 }
 export declare const SCOPE_METHOD_NAMES: Set<string>;
 export declare const BREAK_SETTER: unique symbol;