footprintjs 4.12.2 → 4.13.0

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

@@ -0,0 +1,173 @@
+/**
+ * CombinedRecorder — a single observer that can hook into MULTIPLE event
+ * streams (currently: scope data-flow + control-flow). One object, one `id`,
+ * one consistent view of the execution.
+ *
+ * ## Why this exists
+ *
+ * Before `CombinedRecorder`, a consumer who wanted to observe both streams
+ * had to:
+ *   1. Implement both `Recorder` (8 methods) and `FlowRecorder` (12 methods)
+ *      fully — stubbing every event they didn't care about.
+ *   2. Remember to call BOTH `attachRecorder(r)` AND `attachFlowRecorder(r)`.
+ *      Forgetting the second call silently dropped half their events — no
+ *      warning, no runtime error.
+ *   3. Re-implement coordination logic (buffering, ordering) themselves.
+ *
+ * `CombinedRecorder` collapses that into a single type and a single attach
+ * call (`executor.attachCombinedRecorder(r)`), with the library handling the
+ * routing internally. Consumers implement only the events they care about
+ * (`Partial<...>`) and the attach method duck-types at runtime to dispatch
+ * to the relevant channels.
+ *
+ * ## Forward compatibility
+ *
+ * When a third observer type is added (e.g. an `OperationRecorder`), the
+ * `CombinedRecorder` type gains an `& Partial<OperationRecorder>` clause and
+ * `attachCombinedRecorder` gains one more runtime branch in its dispatch.
+ * Consumers writing a `CombinedRecorder` today are NOT affected — their
+ * code keeps compiling and attaching correctly, because every new layer is
+ * optional.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * import type { CombinedRecorder } from 'footprintjs';
+ *
+ * const audit: CombinedRecorder = {
+ *   id: 'audit',
+ *   onWrite: (e) => logWrite(e.key, e.value),        // Recorder method
+ *   onDecision: (e) => logDecision(e.chosen),        // FlowRecorder method
+ * };
+ *
+ * executor.attachCombinedRecorder(audit);
+ * // ^ internally: detects both sets of methods, routes to both channels.
+ * ```
+ *
+ * ## Contract with existing APIs
+ *
+ * - `attachRecorder(r)` and `attachFlowRecorder(r)` remain unchanged.
+ *   Consumers who want only ONE channel keep using them — explicit is good.
+ * - `attachCombinedRecorder(r)` is the ONLY way to guarantee an object is
+ *   hooked into every stream it has methods for, without maintaining two
+ *   attach calls at the call site.
+ * - Idempotency by `id` is preserved across channels: re-attaching with the
+ *   same `id` replaces the previous instance on BOTH channels, not just one.
+ */
+import type { FlowErrorEvent, FlowPauseEvent, FlowRecorder, FlowResumeEvent } from '../engine/narrative/types.js';
+import type { ErrorEvent, PauseEvent, Recorder, ResumeEvent } from '../scope/types.js';
+import type { EmitRecorder } from './EmitRecorder.js';
+/**
+ * Method names that appear on BOTH `Recorder` and `FlowRecorder` but with
+ * different event payload types. For these, a `CombinedRecorder` declares
+ * ONE handler that receives the union of both payloads — consumers
+ * discriminate on `traversalContext`, which only control-flow events carry.
+ */
+type SharedLifecycleOverlap = 'onError' | 'onPause' | 'onResume';
+/** Lifecycle hooks (not event-specific) that both interfaces share identically. */
+type SharedLifecycle = 'id' | 'clear' | 'toSnapshot';
+/**
+ * A recorder that MAY observe any combination of supported event streams.
+ *
+ * Today's streams:
+ *   - Scope data-flow (`Recorder`: onRead/onWrite/onCommit/onStageStart/…)
+ *   - Control-flow (`FlowRecorder`: onDecision/onSubflowEntry/onLoop/…)
+ *
+ * All event handlers are optional — implement only what you care about.
+ * `id` is required so the library can deduplicate re-attaches.
+ *
+ * ## Shared method names (onError / onPause / onResume)
+ *
+ * Both `Recorder` and `FlowRecorder` declare these with DIFFERENT payload
+ * shapes. In a combined recorder, each such handler is called by BOTH
+ * channels with its own variant. The parameter type is a union — consumers
+ * can either handle both variants uniformly, or discriminate (control-flow
+ * variants carry a `traversalContext` field that data-flow variants lack).
+ *
+ * ## Forward compatibility
+ *
+ * When a third observer type ships (e.g. `OperationRecorder`), the type
+ * gains another `& Partial<…>` clause. Because every clause is `Partial`,
+ * existing `CombinedRecorder` implementations remain type-valid.
+ */
+export type CombinedRecorder = Partial<Omit<Recorder, SharedLifecycleOverlap | SharedLifecycle>> & Partial<Omit<FlowRecorder, SharedLifecycleOverlap | SharedLifecycle>> & Partial<Omit<EmitRecorder, SharedLifecycle>> & {
+    readonly id: string;
+    clear?(): void;
+    toSnapshot?(): {
+        name: string;
+        description?: string;
+        preferredOperation?: 'translate' | 'accumulate' | 'aggregate';
+        data: unknown;
+    };
+    onError?(event: ErrorEvent | FlowErrorEvent): void;
+    onPause?(event: PauseEvent | FlowPauseEvent): void;
+    onResume?(event: ResumeEvent | FlowResumeEvent): void;
+};
+/**
+ * Discriminator for the union payload types on `CombinedRecorder`'s shared
+ * methods (`onError`, `onPause`, `onResume`). Returns `true` if the event
+ * was emitted from the control-flow channel (FlowRecorder).
+ *
+ * ## How it discriminates
+ *
+ * Scope-channel events extend `RecorderContext`, which carries `pipelineId`.
+ * Flow-channel events do not carry `pipelineId` (they carry an optional
+ * `traversalContext` instead, but that field is optional and cannot be
+ * relied on as a positive signal). We detect the flow variant by the
+ * ABSENCE of `pipelineId` — this is schema-stable as long as scope events
+ * continue to extend `RecorderContext`.
+ *
+ * @example
+ * ```ts
+ * onError: (e) => {
+ *   if (isFlowEvent(e)) {
+ *     // Narrowed to FlowErrorEvent: has stageName, message, structuredError
+ *   } else {
+ *     // Narrowed to ErrorEvent: has error, operation, key?
+ *   }
+ * }
+ * ```
+ */
+export declare function isFlowEvent<T>(event: T): event is Exclude<T, {
+    pipelineId: string;
+}>;
+/**
+ * True iff the recorder implements at least one data-flow event method.
+ * Used by `executor.attachCombinedRecorder` to decide whether to hook into
+ * the scope data-flow channel.
+ *
+ * ## Detection rule
+ *
+ * Accepts both object-literal recorders (own-property handlers) AND class
+ * instances (handlers declared on the class prototype). Rejects handlers
+ * inherited from `Object.prototype` — that's always accidental or
+ * malicious pollution, never a legitimate recorder.
+ *
+ * ## Lifecycle exclusions
+ *
+ * `clear` and `toSnapshot` are NOT counted as event methods — a recorder
+ * that only implements those has nothing to observe and would be a no-op
+ * on either channel.
+ *
+ * ## Return type
+ *
+ * Returns plain `boolean` (not a type predicate). The full `Recorder`
+ * interface has payload types that diverge from `CombinedRecorder`'s union
+ * variants for shared methods, so a narrowing predicate would be unsound.
+ * Callers that need to treat the recorder as a `Recorder` do so explicitly
+ * at the attach site — the cast is the contract that each channel passes
+ * its own payload variant.
+ */
+export declare function hasRecorderMethods(r: CombinedRecorder): boolean;
+/**
+ * True iff the recorder implements at least one control-flow event method.
+ * See `hasRecorderMethods`.
+ */
+export declare function hasFlowRecorderMethods(r: CombinedRecorder): boolean;
+/**
+ * True iff the recorder implements at least one emit-channel event method.
+ * See `hasRecorderMethods` for the ownership-detection rules (own or
+ * class-prototype methods count; `Object.prototype` pollution does not).
+ */
+export declare function hasEmitRecorderMethods(r: CombinedRecorder): boolean;
+export {};

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

@@ -0,0 +1,135 @@
+/**
+ * EmitRecorder — the third observer channel, alongside `Recorder`
+ * (scope data-flow) and `FlowRecorder` (control-flow).
+ *
+ * ## Why this exists
+ *
+ * The first two channels capture what the LIBRARY knows about — scope
+ * reads/writes fired by `setValue`, and control-flow events fired by the
+ * traverser. But **user-emitted structured events** — things a stage
+ * function wants to surface for observability (LLM tokens, billing metrics,
+ * auth decisions, domain milestones) — have nowhere to go today. They land
+ * in unobserved `DiagnosticCollector` side bags that no recorder watches.
+ *
+ * This channel closes that gap. Consumer calls `scope.$emit(name, payload)`
+ * from inside a stage; the library enriches the event with stage context
+ * and dispatches it synchronously to every attached `EmitRecorder`.
+ *
+ * ## Design properties
+ *
+ * - **Pass-through, not buffered.** Zero allocation when no recorder is
+ *   attached. Events delivered synchronously, in-order, at call time.
+ *   Same semantics as `onRead`/`onWrite` already use.
+ * - **Library-agnostic vocabulary.** Event names are consumer-chosen strings.
+ *   Convention: hierarchical dotted names, e.g. `'agentfootprint.llm.tokens'`,
+ *   `'myapp.billing.spend'`. Library enforces no registry.
+ * - **Auto-enriched context.** Every event carries `stageName`,
+ *   `runtimeStageId`, `subflowPath`, `pipelineId`, `timestamp`. Consumers
+ *   never need to thread execution context through their emit payloads.
+ * - **Redaction-aware.** `RedactionPolicy.emitPatterns` matches event names
+ *   before dispatch — matched events have their payload replaced with
+ *   `'[REDACTED]'` so secrets can't leak via emit.
+ *
+ * ## Relationship to existing channels
+ *
+ * | Channel         | Fires when                         | Built-in consumers     |
+ * |-----------------|------------------------------------|------------------------|
+ * | `Recorder`      | scope read/write/commit            | DebugRecorder, MetricRecorder |
+ * | `FlowRecorder`  | traversal transitions              | NarrativeFlowRecorder, etc. |
+ * | `EmitRecorder`  | consumer calls `scope.$emit(...)`  | (none ships today; Phase 3.X adds MemoryEmitRecorder) |
+ *
+ * `CombinedRecorder` (from `./CombinedRecorder.ts`) intersects all three
+ * via `Partial<...>`. A consumer can write ONE object implementing any
+ * combination; `executor.attachCombinedRecorder(r)` duck-types and routes
+ * to the right channel(s).
+ *
+ * @example
+ * ```typescript
+ * const tokenMeter: EmitRecorder = {
+ *   id: 'token-meter',
+ *   onEmit(event) {
+ *     if (event.name === 'agentfootprint.llm.tokens') {
+ *       this.total += (event.payload as { input: number; output: number }).input;
+ *     }
+ *   },
+ *   total: 0,
+ * } as any;
+ *
+ * executor.attachEmitRecorder(tokenMeter);
+ * ```
+ */
+import type { RecorderOperation } from './RecorderOperation.js';
+/**
+ * Event delivered to `EmitRecorder.onEmit`.
+ *
+ * Name + payload are consumer-supplied via `scope.$emit(name, payload)`.
+ * Everything else is library-enriched at dispatch time from the current
+ * stage's execution context.
+ */
+export interface EmitEvent {
+    /**
+     * Consumer-supplied event name. Convention: hierarchical dotted namespace
+     * (e.g. `'agentfootprint.llm.tokens'`, `'myapp.billing.spend'`). Keeps
+     * vocabularies collision-free across libraries/apps without requiring a
+     * central registry.
+     */
+    readonly name: string;
+    /**
+     * Consumer-supplied payload. Shape is up to the consumer and their
+     * convention; library treats it as opaque and passes through unchanged
+     * (modulo redaction — see `RedactionPolicy.emitPatterns`).
+     *
+     * When redacted, replaced with the string `'[REDACTED]'`.
+     */
+    readonly payload: unknown;
+    /** Name of the stage that emitted this event. */
+    readonly stageName: string;
+    /**
+     * Unique per-execution-step identifier — the same value recorder events
+     * and commit-log entries carry. See `runtimeStageId.ts` for format.
+     */
+    readonly runtimeStageId: string;
+    /**
+     * Subflow path from the outermost parent down to the subflow that emitted
+     * this event. Empty array when the emit came from the root flowchart.
+     * Matches the convention used by `FlowPauseEvent.subflowPath`,
+     * `FlowchartCheckpoint.subflowPath`, etc.
+     */
+    readonly subflowPath: readonly string[];
+    /** Pipeline/run identifier (matches `RecorderContext.pipelineId`). */
+    readonly pipelineId: string;
+    /** Emission timestamp in milliseconds since epoch (`Date.now()`). */
+    readonly timestamp: number;
+}
+/**
+ * Pluggable observer for consumer-emitted structured events.
+ *
+ * All methods are optional; implement only what you care about. Recorders
+ * are invoked synchronously in attachment order. If a recorder throws, the
+ * error is caught and isolated — other recorders continue to receive the
+ * event and the emitting stage is unaffected.
+ */
+export interface EmitRecorder {
+    /**
+     * Stable identifier for idempotent attach/detach. Re-attaching with the
+     * same id replaces the previous registration on the executor.
+     */
+    readonly id: string;
+    /** Called for every `scope.$emit(name, payload)` call in any stage. */
+    onEmit?(event: EmitEvent): void;
+    /**
+     * Optional: reset recorder-internal state between runs. Called by the
+     * executor before each `run()`.
+     */
+    clear?(): void;
+    /**
+     * Optional: expose collected data for inclusion in
+     * `executor.getSnapshot().recorders`.
+     */
+    toSnapshot?(): {
+        name: string;
+        description?: string;
+        preferredOperation?: RecorderOperation;
+        data: unknown;
+    };
+}

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

@@ -1,5 +1,8 @@
+export type { CombinedRecorder } from './CombinedRecorder.js';
+export { hasEmitRecorderMethods, hasFlowRecorderMethods, hasRecorderMethods, isFlowEvent } from './CombinedRecorder.js';
 export type { CompositeSnapshot } from './CompositeRecorder.js';
 export { CompositeRecorder } from './CompositeRecorder.js';
+export type { EmitEvent, EmitRecorder } from './EmitRecorder.js';
 export { KeyedRecorder } from './KeyedRecorder.js';
 export { RecorderOperation } from './RecorderOperation.js';
 export { SequenceRecorder } from './SequenceRecorder.js';

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

@@ -22,6 +22,8 @@ import type { ManifestEntry } from '../engine/narrative/recorders/ManifestFlowRe
 import type { FlowRecorder } from '../engine/narrative/types.js';
 import { type ExecutorResult, type ExtractorError, type FlowChart, type RunOptions, type ScopeFactory, type SerializedPipelineStructure, type StageNode, type StreamHandlers, type SubflowResult } from '../engine/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 { Recorder, RedactionPolicy, RedactionReport } from '../scope/types.js';
 import { type RuntimeSnapshot } from './ExecutionRuntime.js';
@@ -216,6 +218,89 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
     detachFlowRecorder(id: string): void;
     /** Returns a defensive copy of attached FlowRecorders. */
     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 `attachRecorder` 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 `attachRecorder(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.
+     *
+     * @example
+     * ```typescript
+     * const audit: CombinedRecorder = {
+     *   id: 'audit',
+     *   onWrite: (e) => log('scope write', e.key),
+     *   onDecision: (e) => log('routed to', e.chosen),
+     * };
+     * executor.attachCombinedRecorder(audit);
+     * ```
+     */
+    attachCombinedRecorder(recorder: CombinedRecorder): 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.
+     */
+    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 `attachRecorder` — consumers can also use
+     * `attachRecorder` 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`.
+     *
+     * @example
+     * ```typescript
+     * executor.attachEmitRecorder({
+     *   id: 'token-meter',
+     *   onEmit: (e) => {
+     *     if (e.name === 'agentfootprint.llm.tokens') trackTokens(e.payload);
+     *   },
+     * });
+     * ```
+     */
+    attachEmitRecorder(recorder: EmitRecorder): void;
+    /** Detach an `EmitRecorder` by id. Safe to call if never attached. */
+    detachEmitRecorder(id: string): void;
+    /**
+     * Returns a defensive copy of attached recorders filtered to those that
+     * implement `onEmit`. Useful for inspection during testing.
+     */
+    getEmitRecorders(): EmitRecorder[];
     /**
      * Returns the execution narrative.
      *

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

@@ -18,6 +18,12 @@ import { StageContext } from '../memory/StageContext.js';
 import type { CommitEvent, Recorder, RedactionPolicy, RedactionReport } from './types.js';
 export declare class ScopeFacade {
     static readonly BRAND: unique symbol;
+    /**
+     * Shared sentinel returned by `_getSubflowPath()` for root-level stages
+     * (no subflow nesting). Avoids per-call allocation of a fresh
+     * `Object.freeze([])` on every `emitEvent` in the common no-subflow case.
+     */
+    private static readonly _EMPTY_SUBFLOW_PATH;
     protected _stageContext: StageContext;
     protected _stageName: string;
     protected readonly _readOnlyValues?: unknown;
@@ -75,6 +81,40 @@ export declare class ScopeFacade {
     addErrorInfo(key: string, value: unknown): void;
     addMetric(metricName: string, value: unknown): void;
     addEval(metricName: string, value: unknown): void;
+    /**
+     * Fire a structured event to every attached recorder implementing
+     * `onEmit`. Synchronous, in-order, pass-through — no buffering.
+     *
+     * - **Fast-path**: zero allocation + zero cost when no recorders are
+     *   attached (early return on empty list).
+     * - **Enrichment**: library auto-adds `stageName`, `runtimeStageId`,
+     *   `subflowPath`, `pipelineId`, `timestamp` to the event.
+     * - **Redaction**: `RedactionPolicy.emitPatterns` regexes are matched
+     *   against `name` — matched events have their payload replaced with
+     *   `'[REDACTED]'` before dispatch.
+     * - **Error isolation**: a throwing `onEmit` does not propagate — it is
+     *   caught and routed to `onError` on remaining recorders, matching the
+     *   pattern used by other scope events.
+     *
+     * Consumers call this via the `scope.$emit(name, payload)` scope method;
+     * the method routes here via `createTypedScope`.
+     */
+    emitEvent(name: string, payload: unknown): void;
+    /**
+     * Build the subflowPath (outer → inner) for event enrichment.
+     *
+     * Parses from `runtimeStageId` which has the format
+     * `[subflowPath/]stageId#executionIndex` (see `lib/engine/runtimeStageId.ts`).
+     * Subflow isolation prevents walking the parent-chain across boundaries,
+     * so the runtimeStageId — globally unique, includes full path — is the
+     * canonical source of truth for the subflow hierarchy at emit time.
+     *
+     * Examples:
+     *   'seed#0'                 → []                    (root)
+     *   'sf-inner/inner#5'       → ['sf-inner']
+     *   'sf-a/sf-b/stage#3'      → ['sf-a', 'sf-b']      (nested)
+     */
+    private _getSubflowPath;
     /** Returns all state keys without firing onRead. Used by TypedScope ownKeys/has traps. */
     getStateKeys(): string[];
     /** Check key existence without firing onRead. Used by TypedScope has trap.

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

@@ -12,9 +12,36 @@
  * Only checks plain objects and arrays — class instances, Date, Map, etc. are skipped.
  */
 export declare function hasCircularReference(value: unknown, ancestors?: WeakSet<object>): boolean;
-/** Enable dev-mode circular reference detection. Call once at app startup. */
+/**
+ * Enable dev-mode diagnostics across the whole library.
+ *
+ * When on, the library performs developer-only checks (circular references,
+ * empty recorder detection, suspicious predicate shapes, etc.) and emits
+ * `console.warn` messages to help you catch mistakes early.
+ *
+ * Call once at application startup. See the module header for the full
+ * list of what dev-mode gates.
+ *
+ * @example
+ * ```ts
+ * import { enableDevMode } from 'footprintjs';
+ * if (process.env.NODE_ENV !== 'production') enableDevMode();
+ * ```
+ */
 export declare function enableDevMode(): void;
-/** Disable dev-mode detection (default). */
+/**
+ * Disable dev-mode diagnostics across the whole library (default state).
+ *
+ * All dev-only checks become no-ops. Safe to call in production paths —
+ * typically the default never needs to be re-asserted, but this is the
+ * documented way to turn the flag off if your code enabled it earlier.
+ */
 export declare function disableDevMode(): void;
-/** Returns whether dev-mode detection is enabled. */
+/**
+ * Returns whether dev-mode diagnostics are currently enabled.
+ *
+ * Library internals call this before running any dev-only check. Consumers
+ * rarely need to call it directly — prefer `enableDevMode()` at startup and
+ * let the library gate its own diagnostics internally.
+ */
 export declare function isDevMode(): boolean;

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

@@ -68,6 +68,18 @@ export interface RedactionPolicy {
     /** Field-level redaction within objects — key → array of fields to scrub.
      *  Supports dot-notation for nested paths (e.g. 'address.zip'). */
     fields?: Record<string, string[]>;
+    /**
+     * Regex patterns matched against `EmitEvent.name` for `scope.$emit(...)`
+     * calls. Any emit event whose name matches has its payload replaced with
+     * the string `'[REDACTED]'` before dispatch to recorders.
+     *
+     * Example:
+     * ```ts
+     * { emitPatterns: [/\.auth\./, /\.billing\./] }
+     * // Hides payloads of events like 'myapp.auth.check' and 'myapp.billing.spend'
+     * ```
+     */
+    emitPatterns?: RegExp[];
 }
 /**
  * Compliance-friendly report of what was redacted. Never includes values.
@@ -98,6 +110,15 @@ export interface Recorder {
     onStageEnd?(event: StageEvent): void;
     onPause?(event: PauseEvent): void;
     onResume?(event: ResumeEvent): void;
+    /**
+     * Fires for every `scope.$emit(name, payload)` call during a stage.
+     * Optional — implement only if you want to observe consumer-emitted
+     * structured events. See `EmitRecorder` for the focused interface
+     * (structurally compatible; this field is the same shape).
+     *
+     * @see EmitRecorder in `src/lib/recorder/EmitRecorder.ts`
+     */
+    onEmit?(event: import('../recorder/EmitRecorder.js').EmitEvent): void;
     /** Reset state before each executor.run() — prevents cross-run accumulation. */
     clear?(): void;
     /** Expose collected data for inclusion in executor.getSnapshot().recorders. */

package/dist/types/recorders.d.ts

@@ -25,12 +25,13 @@
  */
 import type { CombinedNarrativeRecorderOptions } from './lib/engine/narrative/CombinedNarrativeRecorder.js';
 import { CombinedNarrativeRecorder } from './lib/engine/narrative/CombinedNarrativeRecorder.js';
-import type { BreakRenderContext, CombinedNarrativeEntry, DecisionRenderContext, ErrorRenderContext, ForkRenderContext, LoopRenderContext, NarrativeRenderer, OpRenderContext, SelectedRenderContext, StageRenderContext, SubflowRenderContext } from './lib/engine/narrative/narrativeTypes.js';
+import type { BreakRenderContext, CombinedNarrativeEntry, DecisionRenderContext, EmitRenderContext, ErrorRenderContext, ForkRenderContext, LoopRenderContext, NarrativeFormatter, NarrativeRenderer, OpRenderContext, SelectedRenderContext, StageRenderContext, SubflowRenderContext } from './lib/engine/narrative/narrativeTypes.js';
 import { AdaptiveNarrativeFlowRecorder } from './lib/engine/narrative/recorders/AdaptiveNarrativeFlowRecorder.js';
 import type { ManifestEntry } from './lib/engine/narrative/recorders/ManifestFlowRecorder.js';
 import { ManifestFlowRecorder } from './lib/engine/narrative/recorders/ManifestFlowRecorder.js';
 import { MilestoneNarrativeFlowRecorder } from './lib/engine/narrative/recorders/MilestoneNarrativeFlowRecorder.js';
 import { WindowedNarrativeFlowRecorder } from './lib/engine/narrative/recorders/WindowedNarrativeFlowRecorder.js';
+import type { EmitEvent, EmitRecorder } from './lib/recorder/EmitRecorder.js';
 import type { DebugEntry, DebugRecorderOptions } from './lib/scope/recorders/DebugRecorder.js';
 import { DebugRecorder } from './lib/scope/recorders/DebugRecorder.js';
 import type { AggregatedMetrics, MetricRecorderOptions, StageMetrics } from './lib/scope/recorders/MetricRecorder.js';
@@ -59,7 +60,7 @@ export declare function manifest(): ManifestInstance;
 export declare function adaptive(): AdaptiveNarrativeFlowRecorder;
 export declare function milestone(): MilestoneNarrativeFlowRecorder;
 export declare function windowed(maxEntries?: number): WindowedNarrativeFlowRecorder;
-export type { BreakRenderContext, CombinedNarrativeRecorderOptions, DecisionRenderContext, ErrorRenderContext, ForkRenderContext, LoopRenderContext, NarrativeRenderer, OpRenderContext, SelectedRenderContext, StageRenderContext, SubflowRenderContext, };
+export type { BreakRenderContext, CombinedNarrativeRecorderOptions, DecisionRenderContext, EmitEvent, EmitRecorder, EmitRenderContext, ErrorRenderContext, ForkRenderContext, LoopRenderContext, NarrativeFormatter, NarrativeRenderer, OpRenderContext, SelectedRenderContext, StageRenderContext, SubflowRenderContext, };
 export type { AggregatedMetrics, MetricRecorderOptions, StageMetrics };
 export type { CompositeSnapshot } from './lib/recorder/index.js';
 export { CompositeRecorder } from './lib/recorder/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "footprintjs",
-  "version": "4.12.2",
+  "version": "4.13.0",
   "description": "Explainable backend flows — automatic causal traces, decision evidence, and MCP tool generation for AI agents",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -97,7 +97,6 @@
     ]
   },
   "sideEffects": false,
-  "dependencies": {},
   "peerDependencies": {
     "zod": "^3.0.0 || ^4.0.0"
   },