footprintjs 4.0.1 → 4.0.3

package/dist/lib/runner/index.js

@@ -10,4 +10,4 @@ Object.defineProperty(exports, "getSubtreeSnapshot", { enumerable: true, get: fu
 Object.defineProperty(exports, "listSubflowPaths", { enumerable: true, get: function () { return getSubtreeSnapshot_js_1.listSubflowPaths; } });
 var RunContext_js_1 = require("./RunContext.js");
 Object.defineProperty(exports, "RunContext", { enumerable: true, get: function () { return RunContext_js_1.RunContext; } });
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvbGliL3J1bm5lci9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFHQSw2REFBeUQ7QUFBaEQsdUhBQUEsZ0JBQWdCLE9BQUE7QUFFekIsK0RBQTJEO0FBQWxELHlIQUFBLGlCQUFpQixPQUFBO0FBRTFCLGlFQUErRTtBQUF0RSwySEFBQSxrQkFBa0IsT0FBQTtBQUFFLHlIQUFBLGdCQUFnQixPQUFBO0FBRTdDLGlEQUE2QztBQUFwQywyR0FBQSxVQUFVLE9BQUEiLCJzb3VyY2VzQ29udGVudCI6WyIvKiBpc3RhbmJ1bCBpZ25vcmUgZmlsZSAqL1xuZXhwb3J0IHR5cGUgeyBDb21wb3NhYmxlUnVubmVyIH0gZnJvbSAnLi9Db21wb3NhYmxlUnVubmVyLmpzJztcbmV4cG9ydCB0eXBlIHsgTmFycmF0aXZlRW50cnksIFJlY29yZGVyU25hcHNob3QsIFJ1bnRpbWVTbmFwc2hvdCB9IGZyb20gJy4vRXhlY3V0aW9uUnVudGltZS5qcyc7XG5leHBvcnQgeyBFeGVjdXRpb25SdW50aW1lIH0gZnJvbSAnLi9FeGVjdXRpb25SdW50aW1lLmpzJztcbmV4cG9ydCB0eXBlIHsgRmxvd0NoYXJ0RXhlY3V0b3JPcHRpb25zIH0gZnJvbSAnLi9GbG93Q2hhcnRFeGVjdXRvci5qcyc7XG5leHBvcnQgeyBGbG93Q2hhcnRFeGVjdXRvciB9IGZyb20gJy4vRmxvd0NoYXJ0RXhlY3V0b3IuanMnO1xuZXhwb3J0IHR5cGUgeyBTdWJ0cmVlU25hcHNob3QgfSBmcm9tICcuL2dldFN1YnRyZWVTbmFwc2hvdC5qcyc7XG5leHBvcnQgeyBnZXRTdWJ0cmVlU25hcHNob3QsIGxpc3RTdWJmbG93UGF0aHMgfSBmcm9tICcuL2dldFN1YnRyZWVTbmFwc2hvdC5qcyc7XG5leHBvcnQgdHlwZSB7IFJ1blJlc3VsdCB9IGZyb20gJy4vUnVuQ29udGV4dC5qcyc7XG5leHBvcnQgeyBSdW5Db250ZXh0IH0gZnJvbSAnLi9SdW5Db250ZXh0LmpzJztcbmV4cG9ydCB0eXBlIHsgUnVubmFibGVGbG93Q2hhcnQgfSBmcm9tICcuL1J1bm5hYmxlQ2hhcnQuanMnO1xuIl19
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvbGliL3J1bm5lci9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFHQSw2REFBeUQ7QUFBaEQsdUhBQUEsZ0JBQWdCLE9BQUE7QUFFekIsK0RBQTJEO0FBQWxELHlIQUFBLGlCQUFpQixPQUFBO0FBRTFCLGlFQUErRTtBQUF0RSwySEFBQSxrQkFBa0IsT0FBQTtBQUFFLHlIQUFBLGdCQUFnQixPQUFBO0FBRTdDLGlEQUE2QztBQUFwQywyR0FBQSxVQUFVLE9BQUEiLCJzb3VyY2VzQ29udGVudCI6WyIvKiBpc3RhbmJ1bCBpZ25vcmUgZmlsZSAqL1xuZXhwb3J0IHR5cGUgeyBDb21wb3NhYmxlUnVubmVyIH0gZnJvbSAnLi9Db21wb3NhYmxlUnVubmVyLmpzJztcbmV4cG9ydCB0eXBlIHsgUmVjb3JkZXJTbmFwc2hvdCwgUnVudGltZVNuYXBzaG90IH0gZnJvbSAnLi9FeGVjdXRpb25SdW50aW1lLmpzJztcbmV4cG9ydCB7IEV4ZWN1dGlvblJ1bnRpbWUgfSBmcm9tICcuL0V4ZWN1dGlvblJ1bnRpbWUuanMnO1xuZXhwb3J0IHR5cGUgeyBGbG93Q2hhcnRFeGVjdXRvck9wdGlvbnMgfSBmcm9tICcuL0Zsb3dDaGFydEV4ZWN1dG9yLmpzJztcbmV4cG9ydCB7IEZsb3dDaGFydEV4ZWN1dG9yIH0gZnJvbSAnLi9GbG93Q2hhcnRFeGVjdXRvci5qcyc7XG5leHBvcnQgdHlwZSB7IFN1YnRyZWVTbmFwc2hvdCB9IGZyb20gJy4vZ2V0U3VidHJlZVNuYXBzaG90LmpzJztcbmV4cG9ydCB7IGdldFN1YnRyZWVTbmFwc2hvdCwgbGlzdFN1YmZsb3dQYXRocyB9IGZyb20gJy4vZ2V0U3VidHJlZVNuYXBzaG90LmpzJztcbmV4cG9ydCB0eXBlIHsgUnVuUmVzdWx0IH0gZnJvbSAnLi9SdW5Db250ZXh0LmpzJztcbmV4cG9ydCB7IFJ1bkNvbnRleHQgfSBmcm9tICcuL1J1bkNvbnRleHQuanMnO1xuZXhwb3J0IHR5cGUgeyBSdW5uYWJsZUZsb3dDaGFydCB9IGZyb20gJy4vUnVubmFibGVDaGFydC5qcyc7XG4iXX0=

package/dist/types/advanced.d.ts

@@ -34,7 +34,7 @@ export { createErrorMessage, createProtectedScope, ScopeFacade } from './lib/sco
 export { attachScopeMethods, isSubclassOfScopeFacade, looksLikeClassCtor, looksLikeFactory, makeClassProvider, makeFactoryProvider, registerScopeResolver, resolveScopeProvider, toScopeFactory, } from './lib/scope/index.js';
 export type { AggregatedMetrics, DebugEntry, DebugRecorderOptions, DebugVerbosity, DefineScopeOptions, RecorderContext, StageEvent, StageMetrics, } from './lib/scope/index.js';
 export { createScopeProxyFromZod, defineScopeSchema, isScopeSchema, ZodScopeResolver } from './lib/scope/index.js';
-export type { NarrativeEntry, RuntimeSnapshot } from './lib/runner/index.js';
+export type { RuntimeSnapshot } from './lib/runner/index.js';
 export { ExecutionRuntime } from './lib/runner/index.js';
 export type { ReactiveOptions, ReactiveTarget } from './lib/reactive/index.js';
 export { BREAK_SETTER, buildNestedPatch, createArrayProxy, joinPath, SCOPE_METHOD_NAMES, shouldWrapWithProxy, } from './lib/reactive/index.js';

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

@@ -19,7 +19,7 @@ export type { ScopeProtectionMode };
 export interface SerializedPipelineStructure {
     name: string;
     id: string;
-    type: 'stage' | 'decider' | 'selector' | 'fork' | 'streaming' | 'subflow';
+    type: 'stage' | 'decider' | 'selector' | 'fork' | 'streaming' | 'subflow' | 'loop';
     /** Semantic icon hint for visualization (e.g., "llm", "tool", "rag", "agent", "start") */
     icon?: string;
     description?: string;
@@ -47,12 +47,14 @@ export interface SerializedPipelineStructure {
     iterationCount?: number;
     /** True when this subflow uses lazy resolution (deferred until execution). */
     isLazy?: boolean;
+    /** True when this node is a back-edge reference created by loopTo() — not an executable stage. */
+    isLoopReference?: boolean;
 }
 export interface FlowChartSpec {
     name: string;
     id: string;
     /** Node type — matches `SerializedPipelineStructure.type` for visualization alignment. */
-    type?: 'stage' | 'decider' | 'selector' | 'fork' | 'streaming' | 'subflow';
+    type?: 'stage' | 'decider' | 'selector' | 'fork' | 'streaming' | 'subflow' | 'loop';
     /** Semantic icon hint for visualization (e.g., "llm", "tool", "rag", "agent", "start") */
     icon?: string;
     description?: string;
@@ -69,6 +71,8 @@ export interface FlowChartSpec {
     isSubflowRoot?: boolean;
     subflowId?: string;
     subflowName?: string;
+    /** True when this node is a back-edge reference created by loopTo() — not an executable stage. */
+    isLoopReference?: boolean;
 }
 /** Metadata provided to the build-time extractor for each node. */
 export type BuildTimeNodeMetadata = FlowChartSpec;

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

@@ -55,7 +55,11 @@ export type StageNode<TOut = any, TScope = any> = {
     subflowMountOptions?: SubflowMountOptions;
     /** When true, parallel children use fail-fast semantics (reject on first error) */
     failFast?: boolean;
-    /** True if this node is a back-edge reference created by loopTo() */
+    /**
+     * True if this node is a back-edge reference created by loopTo() — not an executable stage.
+     * Serialization equivalent: `SerializedPipelineStructure.isLoopReference` (different name
+     * 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:

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

@@ -13,7 +13,7 @@ import type { SerializedPipelineStructure } from '../types.js';
  * Compute the node type from node properties.
  * Shared by RuntimeStructureManager (serialization) and ExtractorRunner (metadata).
  */
-export declare function computeNodeType(node: StageNode): 'stage' | 'decider' | 'selector' | 'fork' | 'streaming' | 'subflow';
+export declare function computeNodeType(node: StageNode): 'stage' | 'decider' | 'selector' | 'fork' | 'streaming' | 'subflow' | 'loop';
 export declare class RuntimeStructureManager {
     private runtimePipelineStructure?;
     private structureNodeMap;

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

@@ -24,16 +24,14 @@ export declare class CombinedNarrativeRecorder implements FlowRecorder, Recorder
     readonly id: string;
     private entries;
     /**
-     * Pending scope ops keyed by stageId (stable identifier). Populated at buffer time
-     * using the stageName→stageId mapping; falls back to stageName when stageId is unknown.
-     * Keying by stageId prevents ops from merging when two stages share the same name.
+     * Pending scope ops keyed by stageName. Flushed in onStageExecuted/onDecision.
+     *
+     * Name collisions (two stages with the same name, different IDs) are prevented by
+     * the event ordering contract: scope events (onRead/onWrite) for stage N are always
+     * flushed by onStageExecuted for stage N before stage N+1's scope events begin.
+     * So the key is always uniquely bound to the currently-executing stage.
      */
     private pendingOps;
-    /**
-     * Maps stageName → stageId as we learn them from onStageExecuted/onDecision.
-     * Allows bufferOp() to use stageId as the key while scope events only carry stageName.
-     */
-    private stageNameToId;
     /** Per-subflow stage counters. Key '' = root flow. */
     private stageCounters;
     /** Per-subflow first-stage flags. Key '' = root flow. */

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

@@ -154,7 +154,7 @@ export interface RunOptions {
 }
 export type { FlowControlType, FlowMessage };
 export interface RuntimeStructureMetadata {
-    type: 'stage' | 'decider' | 'selector' | 'fork' | 'streaming' | 'subflow';
+    type: 'stage' | 'decider' | 'selector' | 'fork' | 'streaming' | 'subflow' | 'loop';
     subflowId?: string;
     isSubflowRoot?: boolean;
     subflowName?: string;

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

@@ -46,6 +46,29 @@ export interface ScopeMethods {
     $attachRecorder(recorder: Recorder): void;
     $detachRecorder(recorderId: string): void;
     $getRecorders(): Recorder[];
+    /**
+     * Batch-mutate an array key in a single clone+write cycle.
+     *
+     * Every `scope.items.push(x)` clones the entire array and commits it — O(N) per call.
+     * For N mutations on an M-length array that is O(N×M). Use `$batchArray` to clone once,
+     * apply all mutations inside `fn`, then commit once — O(M) total.
+     *
+     * ```typescript
+     * // Before: 1000 clones × growing array = O(N²)
+     * for (let i = 0; i < 1000; i++) scope.items.push(i);
+     *
+     * // After: 1 clone + 1 commit = O(N)
+     * scope.$batchArray('items', (arr) => {
+     *   for (let i = 0; i < 1000; i++) arr.push(i);
+     * });
+     * ```
+     *
+     * `fn` receives a plain (non-proxy) mutable copy of the current array. Mutations
+     * inside `fn` are NOT tracked individually — only the final committed array appears
+     * in the narrative as a single write. If the key does not exist or is not an array,
+     * `fn` receives an empty array and the result is committed as the new value.
+     */
+    $batchArray(key: string, fn: (arr: unknown[]) => void): void;
     $break(): void;
     $toRaw(): ReactiveTarget;
 }

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

@@ -12,14 +12,7 @@
 import { EventLog } from '../memory/EventLog.js';
 import { SharedMemory } from '../memory/SharedMemory.js';
 import { StageContext } from '../memory/StageContext.js';
-import type { CommitBundle, FlowMessage, StageSnapshot } from '../memory/types.js';
-export interface NarrativeEntry {
-    stageId: string;
-    stageName: string;
-    stageMessages: string[];
-    flowMessage?: FlowMessage;
-    timeIndex: number;
-}
+import type { CommitBundle, StageSnapshot } from '../memory/types.js';
 /** Snapshot of a single recorder's collected data. */
 export interface RecorderSnapshot {
     id: string;
@@ -43,6 +36,4 @@ export declare class ExecutionRuntime {
     getPipelines(): string[];
     setRootObject(path: string[], key: string, value: unknown): void;
     getSnapshot(): RuntimeSnapshot;
-    getFullNarrative(): NarrativeEntry[];
-    private walkContextTree;
 }

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

@@ -45,7 +45,13 @@ import { type RuntimeSnapshot } from './ExecutionRuntime.js';
 export interface FlowChartExecutorOptions<TScope = any> {
     /** Custom scope factory. Defaults to TypedScope or ScopeFacade auto-detection. */
     scopeFactory?: ScopeFactory<TScope>;
-    /** Whether to enrich snapshots with scope state (enables `getSnapshot()`). */
+    /**
+     * Attach a per-stage scope snapshot to each extractor result. When `true`, the
+     * extraction callback receives the full shared state at the point that stage
+     * committed — useful for debugging multi-stage state transitions. Defaults to
+     * `false` (no scope snapshot attached). Can also be set on the chart via
+     * `flowChart(...).enrichSnapshots(true)`.
+     */
     enrichSnapshots?: boolean;
     /**
      * Default values pre-populated into the shared context before **each** stage

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

@@ -1,5 +1,5 @@
 export type { ComposableRunner } from './ComposableRunner.js';
-export type { NarrativeEntry, RecorderSnapshot, RuntimeSnapshot } from './ExecutionRuntime.js';
+export type { RecorderSnapshot, RuntimeSnapshot } from './ExecutionRuntime.js';
 export { ExecutionRuntime } from './ExecutionRuntime.js';
 export type { FlowChartExecutorOptions } from './FlowChartExecutor.js';
 export { FlowChartExecutor } from './FlowChartExecutor.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "footprintjs",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "description": "Explainable backend flows — automatic causal traces, decision evidence, and MCP tool generation for AI agents",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",

package/dist/esm/lib/engine/narrative/CombinedNarrativeBuilder.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiQ29tYmluZWROYXJyYXRpdmVCdWlsZGVyLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vLi4vLi4vc3JjL2xpYi9lbmdpbmUvbmFycmF0aXZlL0NvbWJpbmVkTmFycmF0aXZlQnVpbGRlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIiwic291cmNlc0NvbnRlbnQiOlsiLyoqXG4gKiBAZGVwcmVjYXRlZCBVc2UgYG5hcnJhdGl2ZVR5cGVzLnRzYCBpbnN0ZWFkLiBUaGlzIGZpbGUgaXMga2VwdCBmb3IgaW50ZXJuYWxcbiAqIGJhY2t3YXJkIGNvbXBhdGliaWxpdHkgYW5kIHdpbGwgYmUgcmVtb3ZlZCBpbiBhIGZ1dHVyZSB2ZXJzaW9uLlxuICovXG5leHBvcnQgdHlwZSB7IENvbWJpbmVkTmFycmF0aXZlRW50cnksIENvbWJpbmVkTmFycmF0aXZlT3B0aW9ucyB9IGZyb20gJy4vbmFycmF0aXZlVHlwZXMuanMnO1xuIl19

package/dist/lib/engine/narrative/CombinedNarrativeBuilder.js

@@ -1,3 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiQ29tYmluZWROYXJyYXRpdmVCdWlsZGVyLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vLi4vc3JjL2xpYi9lbmdpbmUvbmFycmF0aXZlL0NvbWJpbmVkTmFycmF0aXZlQnVpbGRlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIiwic291cmNlc0NvbnRlbnQiOlsiLyoqXG4gKiBAZGVwcmVjYXRlZCBVc2UgYG5hcnJhdGl2ZVR5cGVzLnRzYCBpbnN0ZWFkLiBUaGlzIGZpbGUgaXMga2VwdCBmb3IgaW50ZXJuYWxcbiAqIGJhY2t3YXJkIGNvbXBhdGliaWxpdHkgYW5kIHdpbGwgYmUgcmVtb3ZlZCBpbiBhIGZ1dHVyZSB2ZXJzaW9uLlxuICovXG5leHBvcnQgdHlwZSB7IENvbWJpbmVkTmFycmF0aXZlRW50cnksIENvbWJpbmVkTmFycmF0aXZlT3B0aW9ucyB9IGZyb20gJy4vbmFycmF0aXZlVHlwZXMuanMnO1xuIl19

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

@@ -1,5 +0,0 @@
-/**
- * @deprecated Use `narrativeTypes.ts` instead. This file is kept for internal
- * backward compatibility and will be removed in a future version.
- */
-export type { CombinedNarrativeEntry, CombinedNarrativeOptions } from './narrativeTypes.js';