agentfootprint 2.14.5 → 3.1.0

package/dist/types/cache/CacheGateDecider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CacheGateDecider.d.ts","sourceRoot":"","sources":["../../../src/cache/CacheGateDecider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAU,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAE3E;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;CACxD;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC;;;GAGG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,EACxC,UAAU,GAAE,MAA2B,EACvC,SAAS,GAAE,MAA8B,GACxC,OAAO,CAQT;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,eAAe,GAAG,YAAY,CAAC;AAE7D;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,CAAC,cAAc,CAAC,GAAG,cAAc,CAsBjF;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,UAAU,CAAC;IAChB,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,YAAY,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;CAC/C,CAAC,GACD,IAAI,CAQN"}
+{"version":3,"file":"CacheGateDecider.d.ts","sourceRoot":"","sources":["../../../src/cache/CacheGateDecider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAU,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAE3E;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;CACxD;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC;;;GAGG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,EACxC,UAAU,GAAE,MAA2B,EACvC,SAAS,GAAE,MAA8B,GACxC,OAAO,CAQT;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,eAAe,GAAG,YAAY,CAAC;AAE7D;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,CAAC,cAAc,CAAC,GAAG,cAAc,CAsBjF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,UAAU,CAAC;IAChB,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,YAAY,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;CAC/C,CAAC,GACD,IAAI,CASN"}

package/dist/types/cache/cacheRecorder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cacheRecorder.d.ts","sourceRoot":"","sources":["../../../src/cache/cacheRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,UAAU,YAAY;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,YAAY,CAAC;IAChD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;CACxC;AAED,UAAU,kBAAkB;IAC1B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,8BAA8B,EAAE,MAAM,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IAC3D;;;;OAIG;IACH,MAAM,IAAI,kBAAkB,CAAC;IAC7B;;;OAGG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,mBAAmB,CA8FrF"}
+{"version":3,"file":"cacheRecorder.d.ts","sourceRoot":"","sources":["../../../src/cache/cacheRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAKpD,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,UAAU,YAAY;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,YAAY,CAAC;IAChD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;CACxC;AAED,UAAU,kBAAkB;IAC1B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,8BAA8B,EAAE,MAAM,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IAC3D;;;;OAIG;IACH,MAAM,IAAI,kBAAkB,CAAC;IAC7B;;;OAGG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,mBAAmB,CAqGrF"}

package/dist/types/conventions.d.ts

@@ -15,6 +15,10 @@ export declare const SUBFLOW_IDS: {
     /** Injection Engine subflow. Evaluates every Injection's trigger
      *  and writes activeInjections[] for the slot subflows to consume. */
     readonly INJECTION_ENGINE: "sf-injection-engine";
+    /** Inner subflow inside LLMCall that wraps the invocation
+     *  (seed + slots + call-llm + optional thinking + extract-final).
+     *  Mounted by LLMCall's outer `client` chart. */
+    readonly LLM_CALL: "sf-llm-call";
     /** System-prompt slot subflow. Observed by ContextRecorder. */
     readonly SYSTEM_PROMPT: "sf-system-prompt";
     /** Messages slot subflow. */
@@ -33,8 +37,18 @@ export declare const SUBFLOW_IDS: {
      *  decider returns `'final'` as a routing value AND the same string
      *  becomes the subflow's id. */
     readonly FINAL: "final";
+    /** Cache subflow (v2.14). Wraps the whole per-turn cache machinery —
+     *  decide markers → CacheGate decider → apply/skip — as ONE collapsible
+     *  boundary in the chart. Provider-independent decision layer; the
+     *  attached provider's CacheStrategy turns markers into wire format.
+     *  UpdateSkillHistory stays OUTSIDE (in the main loop) so the rolling
+     *  skillHistory window persists across iterations without round-tripping
+     *  through this subflow. */
+    readonly CACHE: "sf-cache";
     /** Cache decision subflow (v2.6). Walks activeInjections, emits
-     *  agnostic CacheMarker[]. Provider-independent. */
+     *  agnostic CacheMarker[]. Provider-independent. Standalone building
+     *  block; the agent now uses the `decideCacheMarkers` stage inside
+     *  `sf-cache` instead of mounting this directly. */
     readonly CACHE_DECISION: "sf-cache-decision";
     /** Thinking-normalization mount (v2.14). Wraps the consumer's
      *  ThinkingHandler.normalize() in a real footprintjs subflow so it
@@ -48,7 +62,24 @@ export type SubflowId = (typeof SUBFLOW_IDS)[keyof typeof SUBFLOW_IDS];
 /** Stage IDs — plain function stages that builders mount. */
 export declare const STAGE_IDS: {
     readonly SEED: "seed";
+    /** Context-assembly selector stage. Runs AFTER InjectionEngine and
+     *  fans the 3 slot subflows (system-prompt / messages / tools) out in
+     *  PARALLEL (selector picks all 3 every iteration; failFast so a
+     *  required slot's throw aborts the turn). They converge before
+     *  CacheDecision. Shared by buildAgentChart + buildDynamicAgentChart;
+     *  the flat viz proof chart uses the same id as its root selector. */
+    readonly CONTEXT: "context";
+    /** Outer "client" stage in LLMCall's wrapped chart. Receives args on
+     *  the first visit, $break()s on the second (post-loop) visit with
+     *  the LLM answer as TraversalResult. This is the lens-friendly
+     *  affordance — the User pill maps to this stage. */
+    readonly CLIENT: "client";
     readonly CALL_LLM: "call-llm";
+    /** Final-response extraction stage that runs after CallLLM (and
+     *  optional sf-thinking). For LLMCall this is mostly symmetric with
+     *  Agent's `sf-final` branch — gives lens a "Final" node and a
+     *  clear commit boundary marking "we have the answer." */
+    readonly EXTRACT_FINAL: "extract-final";
     readonly FINAL: "final";
     readonly FORMAT_MERGE: "format-merge";
     readonly MERGE_LLM: "merge-llm";
@@ -74,10 +105,79 @@ export type StageId = (typeof STAGE_IDS)[keyof typeof STAGE_IDS];
 export declare function isSlotSubflow(id: string): id is typeof SUBFLOW_IDS.SYSTEM_PROMPT | typeof SUBFLOW_IDS.MESSAGES | typeof SUBFLOW_IDS.TOOLS;
 /** Map a slot subflow id to its ContextSlot type. Undefined for non-slot ids. */
 export declare function slotFromSubflowId(id: string): ContextSlot | undefined;
+/**
+ * Resolve the context slot a scope write belongs to FROM THE WRITE'S OWN
+ * `runtimeStageId` — not from a "currently-open slot" stack.
+ *
+ * Why: once the 3 slot subflows run in PARALLEL (selector fan-out), their
+ * entry/write/exit events INTERLEAVE — a stack top is unreliable, so a write
+ * inside `sf-messages` could be attributed to (or dropped against)
+ * `sf-tools`. The write's `runtimeStageId` (`[subflowPath/]stageId#index`)
+ * always encodes which slot subflow enclosed it; we scan the path segments
+ * innermost-first for a slot id. Matches the sequential result exactly
+ * (the write is still inside its own slot), so it is behavior-preserving.
+ */
+export declare function slotFromRuntimeStageId(runtimeStageId: string): ContextSlot | undefined;
 /** True when an id is any of the library's known subflow IDs. */
 export declare function isKnownSubflow(id: string): id is SubflowId;
 /** True when an id is any of the library's known stage IDs. */
 export declare function isKnownStage(id: string): id is StageId;
+/**
+ * Semantic role of a stage, used by renderers to decide visual emphasis.
+ *
+ * The agent's chart mixes a handful of stages users actually care about
+ * (the HEROES — what context was built, what the model decided, what it did)
+ * with mechanism stages (PLUMBING). This is the ONE place that says which is
+ * which; renderers stay generic and style purely off this role (e.g. heroes
+ * prominent, plumbing muted). Keeping it here — the semantic owner — avoids
+ * the "name-based filter list duplicated across renderers" anti-pattern.
+ *
+ * - `hero-slot`   — a context slot (system-prompt / messages / tools)
+ * - `hero-llm`    — the LLM invocation
+ * - `hero-action` — tool execution (the agent's actions)
+ * - `plumbing`    — mechanism (injection engine, cache, route, thinking, …)
+ * - `boundary`    — neutral chart boundaries (Initialize root, Final) +
+ *                   anything unrecognised (rendered normally, never muted)
+ */
+export type StageRole = 'hero-slot' | 'hero-llm' | 'hero-action' | 'plumbing' | 'boundary';
+/**
+ * Classify a stage id into its {@link StageRole}. Accepts a path-qualified id
+ * (`sf-llm-call/call-llm`) — only the LOCAL segment matters, so it works at
+ * any nesting depth. Built entirely from the id constants above, so adding a
+ * stage to the chart only requires listing it here.
+ */
+export declare function stageRole(id: string): StageRole;
+/**
+ * A {@link Milestone}'s kind — the domain vocabulary for "meaningful step you'd
+ * scrub to" in the agent's run.
+ */
+export type MilestoneKind = 'iteration' | 'slot' | 'llm-turn' | 'tool-call' | 'decision';
+/**
+ * A time-travel milestone: a domain-declared scrub stop. Conceptually each
+ * milestone marks the boundary of a COLLECTION of commits (the commits that
+ * belong to that step) — so the Lens slider can step stage-by-stage
+ * (iteration → llm-turn → tool-call → …) instead of stopping only on
+ * structural subflow boundaries. The renderer iterates whatever the domain
+ * classifies; it never hardcodes agent vocabulary.
+ */
+export interface Milestone {
+    readonly kind: MilestoneKind;
+    /** Human-readable base label ("LLM turn"); the renderer may add an ordinal. */
+    readonly label: string;
+}
+/**
+ * Classify a stage id into a {@link Milestone}, or `null` when the stage is NOT
+ * a milestone boundary (its commits fold into the surrounding milestone's
+ * collection). This is the DOMAIN's declaration of which steps are scrub-worthy;
+ * the Lens consumes it to build the time-travel slider (see
+ * agentfootprint-lens `cursorPositionsAtDrill`).
+ *
+ * Mirrors {@link stageRole}: accepts a runtimeStageId (`call-llm#17`), a
+ * path-qualified id (`sf-llm-call/call-llm`), or a bare local id — only the
+ * LOCAL stage segment matters, so it works at any nesting depth and for both
+ * commit ids and subflow-group ids.
+ */
+export declare function milestoneFor(id: string): Milestone | null;
 /**
  * Scope-key convention for context injections.
  *

package/dist/types/conventions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conventions.d.ts","sourceRoot":"","sources":["../../src/conventions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,gEAAgE;AAChE,eAAO,MAAM,WAAW;IACtB;0EACsE;;IAEtE,+DAA+D;;IAE/D,6BAA6B;;IAE7B,0BAA0B;;IAE1B,2CAA2C;;IAE3C,uDAAuD;;IAEvD,kCAAkC;;IAElC;;;;oCAIgC;;IAEhC;wDACoD;;IAEpD;;;;;iCAK6B;;CAErB,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAEvE,6DAA6D;AAC7D,eAAO,MAAM,SAAS;;;;;;;IAOpB;wCACoC;;IAEpC;gEAC4D;;IAE5D;4EACwE;;IAExE;kEAC8D;;IAE9D;8CAC0C;;CAElC,CAAC;AAEX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAIjE,wEAAwE;AACxE,wBAAgB,aAAa,CAC3B,EAAE,EAAE,MAAM,GACT,EAAE,IAAI,OAAO,WAAW,CAAC,aAAa,GAAG,OAAO,WAAW,CAAC,QAAQ,GAAG,OAAO,WAAW,CAAC,KAAK,CAIjG;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAgBrE;AAED,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,EAAE,IAAI,SAAS,CAE1D;AAED,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,EAAE,IAAI,OAAO,CAEtD;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc;;;;CAIjB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAEhF,6CAA6C;AAC7C,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,eAAe,GAAG,UAAU,GAAG,OAAO,GAAG,YAAY,CAS9F;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,YAAY,CAE/D"}
+{"version":3,"file":"conventions.d.ts","sourceRoot":"","sources":["../../src/conventions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,gEAAgE;AAChE,eAAO,MAAM,WAAW;IACtB;0EACsE;;IAEtE;;qDAEiD;;IAEjD,+DAA+D;;IAE/D,6BAA6B;;IAE7B,0BAA0B;;IAE1B,2CAA2C;;IAE3C,uDAAuD;;IAEvD,kCAAkC;;IAElC;;;;oCAIgC;;IAEhC;;;;;;gCAM4B;;IAE5B;;;wDAGoD;;IAEpD;;;;;iCAK6B;;CAErB,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAEvE,6DAA6D;AAC7D,eAAO,MAAM,SAAS;;IAEpB;;;;;0EAKsE;;IAEtE;;;yDAGqD;;;IAGrD;;;8DAG0D;;;;;;IAM1D;wCACoC;;IAEpC;gEAC4D;;IAE5D;4EACwE;;IAExE;kEAC8D;;IAE9D;8CAC0C;;CAElC,CAAC;AAEX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAIjE,wEAAwE;AACxE,wBAAgB,aAAa,CAC3B,EAAE,EAAE,MAAM,GACT,EAAE,IAAI,OAAO,WAAW,CAAC,aAAa,GAAG,OAAO,WAAW,CAAC,QAAQ,GAAG,OAAO,WAAW,CAAC,KAAK,CAIjG;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAgBrE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,cAAc,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAStF;AAED,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,EAAE,IAAI,SAAS,CAE1D;AAED,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,EAAE,IAAI,OAAO,CAEtD;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,aAAa,GAAG,UAAU,GAAG,UAAU,CAAC;AA6B3F;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAY/C;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,MAAM,GAAG,UAAU,GAAG,WAAW,GAAG,UAAU,CAAC;AAEzF;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAiCzD;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc;;;;CAIjB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAEhF,6CAA6C;AAC7C,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,eAAe,GAAG,UAAU,GAAG,OAAO,GAAG,YAAY,CAS9F;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,YAAY,CAE/D"}

package/dist/types/core/Agent.d.ts

@@ -13,7 +13,7 @@
  *            agentfootprint.stream.tool_start / tool_end
  *            agentfootprint.context.* (via ContextRecorder)
  */
-import { type CombinedNarrativeEntry, type FlowChart, type FlowchartCheckpoint, type RunOptions, type RuntimeSnapshot } from 'footprintjs';
+import { type CombinedNarrativeEntry, type FlowchartCheckpoint, type RunOptions, type RuntimeSnapshot } from 'footprintjs';
 import type { CachePolicy, CacheStrategy } from '../cache/types.js';
 import type { ReliabilityConfig } from '../reliability/types.js';
 import { type RunnerPauseOutcome } from './pause.js';
@@ -81,21 +81,6 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
     readonly commentaryTemplates: Readonly<Record<string, string>>;
     readonly thinkingTemplates: Readonly<Record<string, string>>;
     private currentRunContext;
-    /**
-     * Reference to the most recent executor. Set on every `createExecutor()`
-     * call (i.e., every `run()` and `resume()`); read by `getLastSnapshot()`
-     * / `getLastNarrativeEntries()` so post-run UIs (Lens Trace tab,
-     * ExplainableShell) can pull execution state without intercepting the
-     * call. `undefined` until the first run.
-     */
-    private lastExecutor?;
-    /**
-     * Reference to the FlowChart compiled for the most recent run. Cached
-     * here rather than recomputed via `buildChart()` so `getSpec()` returns
-     * the SAME spec the executor traced — important when the spec is used
-     * to reconcile `getLastSnapshot()` for ExplainableShell.
-     */
-    private lastFlowChart?;
     /**
      * Memory subsystems registered via `.memory()`. Each definition mounts
      * its `read` subflow before the InjectionEngine on every turn; per-id
@@ -152,13 +137,28 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      * wire format. Undefined = no thinking activation (default behavior).
      */
     private readonly thinkingBudget?;
+    /** Threaded to footprintjs `flowChart()` so every node the Agent
+     *  builder creates is observed by these recorders at build time. Set
+     *  from `opts.structureRecorders`; undefined when consumer didn't
+     *  attach any. */
+    private readonly structureRecorders?;
+    /** Per-COMPOSITION translator (L1b). Set from `opts.groupTranslator`;
+     *  undefined when consumer didn't attach one. */
+    private readonly agentGroupTranslator?;
+    /** ReAct chart shape — 'flat' (default, bare call-llm stage) or
+     *  'subflow' (LLM turn wrapped in sf-llm-call). Set from
+     *  `opts.reactStructure`. */
+    private readonly reactStructure;
+    /** ReAct loop SEMANTICS — 'dynamic' (default, re-engineer all slots each
+     *  turn, loop→InjectionEngine) or 'classic' (engineer context once,
+     *  loop→Messages only). Set from `opts.reactMode`. See AgentOptions. */
+    private readonly reactMode;
     constructor(opts: AgentOptions, systemPromptValue: string, registry: readonly ToolRegistryEntry[], voice: {
         readonly appName: string;
         readonly commentaryTemplates: Readonly<Record<string, string>>;
         readonly thinkingTemplates: Readonly<Record<string, string>>;
     }, injections?: readonly Injection[], memories?: readonly MemoryDefinition[], outputSchemaParser?: OutputSchemaParser<unknown>, toolProvider?: ToolProvider, systemPromptCachePolicy?: CachePolicy, cachingDisabled?: boolean, cacheStrategy?: CacheStrategy, outputFallbackCfg?: ResolvedOutputFallback<unknown>, reliabilityConfig?: ReliabilityConfig, thinkingHandlerValue?: ThinkingHandler | null, thinkingBudgetValue?: number);
     static create(opts: AgentOptions): AgentBuilder;
-    toFlowChart(): FlowChart;
     /**
      * Cache policy for the base system prompt. Read by the CacheDecision
      * subflow (v2.6 Phase 4) to know how to treat the SystemPrompt slot's
@@ -192,7 +192,17 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      * `getLastSnapshot()` traced, otherwise the Trace view's stage tree
      * desyncs from the snapshot's runtime tree.
      */
-    getSpec(): FlowChart;
+    protected getGroupTranslator(): import('./translator.js').GroupTranslator | undefined;
+    /** Agent has no nested-runner members (tools are function executors,
+     *  not Runner instances). Slot ids + tool names live in `extra` so
+     *  Lens can render an Agent card with slot rows + a tool list without
+     *  inspecting `buildTimeStructure`.
+     *
+     *  Memories are NOT included as members — they're an internal
+     *  mechanism, not a composition-level concept. Consumers who need
+     *  memory visibility should listen for `agentfootprint.memory.*`
+     *  events at runtime. */
+    protected buildUIGroupMetadata(): import('./translator.js').GroupMetadata;
     /**
      * Parse + validate a raw agent answer against the agent's
      * `outputSchema` parser. Throws `OutputSchemaError` on JSON parse

package/dist/types/core/Agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../../src/core/Agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../../src/core/Agent.ts"],"names":[],"mappings":"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"}

package/dist/types/core/LLMCall.d.ts

@@ -1,17 +1,45 @@
 /**
- * LLMCall — the leaf primitive for a single LLM invocation (no tools, no loop).
+ * LLMCall — the leaf primitive for a single LLM invocation (no tools).
  *
  * Pattern: Builder (GoF) → produces a Runner backed by a footprintjs FlowChart.
- * Role:    Layer-5 primitive (core/). Uses the 3-slot model internally:
- *            Seed → sf-system-prompt → sf-messages → sf-tools → call-llm
- *          Slot subflows write convention-keyed injections observed by
- *          ContextRecorder. The call-llm stage typedEmits stream.llm_start
- *          and stream.llm_end observed by StreamRecorder.
- * Emits:   Through its internally-attached recorders:
- *            agentfootprint.stream.llm_start / llm_end
- *            agentfootprint.context.injected / slot_composed
+ *
+ * Chart shape — outer client wrapper around an inner llm-subflow:
+ *
+ *     Client → sf-llm-call → loopTo(client)
+ *
+ *   Outer `Client` stage:
+ *     - First visit: receives args, writes userMessage to scope.
+ *     - Second visit (after the loop completes): $break()s with
+ *       scope.answer as the chart's TraversalResult.
+ *
+ *   Inner `sf-llm-call` subflow (drill-down view):
+ *     Initialize → sf-system-prompt → sf-messages → call-llm
+ *          → [sf-thinking if handler]  → extract-final
+ *
+ *   NO `sf-tools` slot — LLMCall has no tools by design (that's Agent's
+ *   territory). Atomic LLMCall's lens chart is a clean 3-node top-level
+ *   view (Client + LLM + loop edge) that drills into the real flowchart
+ *   below.
+ *
+ *   Loop semantics: LLMCall is one-shot. The loop fires once; the
+ *   second Client visit immediately breaks. The shape is identical to
+ *   chat-mode (future): swap `$break()` for `pause()` and the same
+ *   chart supports multi-turn conversation.
+ *
+ * Slot subflows write convention-keyed injections observed by
+ * ContextRecorder. The call-llm stage typedEmits stream.llm_start
+ * and stream.llm_end observed by StreamRecorder. When a
+ * `ThinkingHandler` resolves for the provider, `sf-thinking` mounts
+ * automatically (auto-wired by provider.name — same convention Agent
+ * uses).
+ *
+ * Emits (through internally-attached recorders):
+ *     agentfootprint.stream.llm_start / llm_end
+ *     agentfootprint.context.injected / slot_composed
+ *     agentfootprint.stream.thinking_end (when sf-thinking mounted)
  */
-import { type FlowChart, type FlowchartCheckpoint, type RunOptions } from 'footprintjs';
+import { type FlowchartCheckpoint, type RunOptions, type StructureRecorder } from 'footprintjs';
+import type { GroupMetadata, GroupTranslator } from './translator.js';
 import type { RunnerPauseOutcome } from './pause.js';
 import type { LLMProvider, PricingTable } from '../adapters/types.js';
 import { RunnerBase } from './RunnerBase.js';
@@ -40,6 +68,24 @@ export interface LLMCallOptions {
      * — consumers choose whether to abort by listening to the event.
      */
     readonly costBudget?: number;
+    /**
+     * Optional build-time recorders threaded into footprintjs's
+     * `flowChart()` factory. Each recorder observes per-node build
+     * events (`onStageAdded` / `onSubflowMounted` / etc.) for this
+     * LLMCall's internal chart (Initialize + slot mounts + CallLLM). When
+     * omitted, no build-time observation is wired up.
+     */
+    readonly structureRecorders?: readonly StructureRecorder[];
+    /**
+     * Optional per-COMPOSITION translator (UI-agnostic). See
+     * `core/translator.ts`. When attached, `runner.getUIGroup()` invokes
+     * it with the LLMCall's `GroupMetadata` (kind `'LLMCall'`, id, name,
+     * empty `members[]`, plus `extra.slots` with the three slot ids —
+     * `system-prompt`, `messages`, `tools` — so Lens can render the slot
+     * cards inside an LLMCall card without inspecting `buildTimeStructure`).
+     * Returns `undefined` when omitted.
+     */
+    readonly groupTranslator?: GroupTranslator;
 }
 export interface LLMCallInput {
     readonly message: string;
@@ -55,10 +101,26 @@ export declare class LLMCall extends RunnerBase<LLMCallInput, LLMCallOutput> {
     private readonly systemPromptValue;
     private readonly pricingTable?;
     private readonly costBudget?;
+    private readonly structureRecorders?;
+    private readonly groupTranslator?;
+    /** Auto-resolved from provider.name at construction time (same
+     *  convention Agent uses — see findThinkingHandler). When undefined,
+     *  sf-thinking is NOT mounted and the chart has zero thinking
+     *  overhead (build-time conditional mount). */
+    private readonly thinkingHandler?;
     private currentRunContext;
     constructor(opts: LLMCallOptions, systemPromptValue: string);
     static create(opts: LLMCallOptions): LLMCallBuilder;
-    toFlowChart(): FlowChart;
+    protected getGroupTranslator(): GroupTranslator | undefined;
+    /** LLMCall has no nested-runner members (slots are subflows of
+     *  the LLMCall's own chart, not Runner instances). The slot ids
+     *  are surfaced via `extra` so Lens can render the slot cards
+     *  inside an LLMCall card without inspecting `buildTimeStructure`.
+     *
+     *  TWO slots only — LLMCall does not have tools (that's Agent's
+     *  affordance). Atomic LLMCall renders as a clean 2-pill card in
+     *  collapsed (top-level) view. */
+    protected buildUIGroupMetadata(): GroupMetadata;
     run(input: LLMCallInput, options?: RunOptions): Promise<LLMCallOutput | RunnerPauseOutcome>;
     resume(checkpoint: FlowchartCheckpoint, input?: unknown, options?: RunOptions): Promise<LLMCallOutput | RunnerPauseOutcome>;
     private createExecutor;

package/dist/types/core/LLMCall.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LLMCall.d.ts","sourceRoot":"","sources":["../../../src/core/LLMCall.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,mBAAmB,EACxB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAWrD,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEtE,OAAO,EAAE,UAAU,EAAa,MAAM,iBAAiB,CAAC;AAKxD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC;AAmBnC,qBAAa,OAAQ,SAAQ,UAAU,CAAC,YAAY,EAAE,aAAa,CAAC;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAe;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;IAGrC,OAAO,CAAC,iBAAiB,CAIvB;gBAEU,IAAI,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM;IAa3D,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc;IAInD,WAAW,IAAI,SAAS;IAIlB,GAAG,CACP,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,aAAa,GAAG,kBAAkB,CAAC;IASxC,MAAM,CACV,UAAU,EAAE,mBAAmB,EAC/B,KAAK,CAAC,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,aAAa,GAAG,kBAAkB,CAAC;IAO9C,OAAO,CAAC,cAAc;IA8BtB,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,UAAU;CA+HnB;AAED;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;IACtC,OAAO,CAAC,iBAAiB,CAAM;gBAEnB,IAAI,EAAE,cAAc;IAIhC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK5B,KAAK,IAAI,OAAO;CAGjB"}
+{"version":3,"file":"LLMCall.d.ts","sourceRoot":"","sources":["../../../src/core/LLMCall.ts"],"names":[],"mappings":"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"}

package/dist/types/core/RunnerBase.d.ts

@@ -22,13 +22,145 @@ export declare abstract class RunnerBase<TIn = unknown, TOut = unknown> implemen
     protected readonly dispatcher: EventDispatcher;
     protected readonly attachedRecorders: CombinedRecorder[];
     /**
-     * Build the footprintjs FlowChart for this runner. Subclass supplies
-     * its specific structure (slot subflows, callLLM stage, routing, etc.).
+     * The most recently used FlowChartExecutor — set by subclasses in
+     * `run()` so consumers can read the canonical structural snapshot
+     * via `getLastSnapshot()`. Single source of structural truth: this
+     * is footprintjs's snapshot, NOT a domain re-derivation.
      */
-    abstract toFlowChart(): FlowChart;
+    protected lastExecutor: FlowChartExecutor | undefined;
+    /**
+     * Cached footprintjs FlowChart, built ONCE at construction time via
+     * `initChart()`. Subsequent `getSpec()` calls return this same
+     * object — reference-stable across all consumers (Lens spec memos,
+     * footprintjs's OpenAPI/MCP caches, recorder-side correlation).
+     *
+     * Set via `initChart(builder)`, called from the subclass constructor
+     * AFTER all instance fields are populated. Read via `getSpec()`.
+     *
+     * Why eager construction: the `StructureRecorder` contract is
+     * "fires once per node at build time" — lazy construction would
+     * fire each recorder every `getSpec()` / `run()` call (2N invocations
+     * per run instead of N), break reference equality, and trigger
+     * `_mergeStageMap` false-positive collisions on second build.
+     * See `RunnerBase.initChart` for details.
+     *
+     * Visibility note: `private` (not `protected`) so subclasses cannot
+     * bypass the `initChart()` double-init guard by writing the field
+     * directly. All legitimate access goes through `getSpec()` and
+     * `initChart()`.
+     */
+    private chart;
+    /**
+     * Returns the footprintjs snapshot from the most recent run (or
+     * undefined if no run has completed). The snapshot is the CANONICAL
+     * STRUCTURE: nodes, edges, executionTree, runtimeStageId, commitLog.
+     *
+     * Domain consumers (Lens, Trace, dashboards) read this for shape
+     * and join their own per-stage payload by `runtimeStageId`. They
+     * MUST NOT re-derive structure from typed events — that's the
+     * design footprintjs's CLAUDE.md Convention 1 explicitly forbids.
+     *
+     * Returns `undefined` before the first `run()` completes. After,
+     * always returns the snapshot of the most recent run (including
+     * across multi-turn reuse of the same runner instance).
+     */
+    getLastSnapshot(): ReturnType<FlowChartExecutor['getSnapshot']> | undefined;
+    /**
+     * Alias for `getLastSnapshot()` that mirrors `FlowChartExecutor.getSnapshot()`
+     * so consumers (lens, playground, ExplainableShell) can read the live or
+     * just-completed snapshot through the same method name they'd use on a
+     * footprintjs executor — without having to know whether they're holding
+     * an agentfootprint Runner or a raw executor.
+     *
+     * During an active run, returns the live snapshot (commit log + execution
+     * tree built incrementally as stages execute). Between runs, returns the
+     * last completed run's snapshot. Undefined before any run has started.
+     */
+    getSnapshot(): ReturnType<FlowChartExecutor['getSnapshot']> | undefined;
+    /**
+     * Return the footprintjs FlowChart for this runner — the canonical
+     * design-time blueprint. STABLE REFERENCE across calls (`getSpec()
+     * === getSpec()`). Set once at construction via `initChart()`.
+     *
+     * Pairs with the run-time getters (`getLastSnapshot`,
+     * `getCommitCount`) and matches `ExplainableShell.spec` +
+     * `specToReactFlow(spec, ...)` consumer conventions.
+     *
+     * DO NOT OVERRIDE in subclasses — the reference-identity contract
+     * (Lens / OpenAPI / MCP caches memo on this returning the same
+     * object) depends on the inherited body returning `this.chart`
+     * directly. To customise build behaviour, override `buildChart()`
+     * instead; this getter must remain a thin cache-read.
+     */
+    getSpec(): FlowChart;
+    /**
+     * Cached `getUIGroup()` output. Computed lazily on first read so the
+     * subclass constructor doesn't need to run the translator before all
+     * its members exist (e.g., Parallel builds its branches list mid-
+     * construction). After first invocation, subsequent calls return the
+     * same reference — reference-stable, matches the `getSpec()` contract.
+     *
+     * `null` (not `undefined`) is the explicit "computed; result was
+     * undefined" marker so we can distinguish from "not yet computed."
+     * Consumers see `undefined` when no translator was attached.
+     */
+    private uiGroupCache;
+    /**
+     * Return the consumer-shaped UI group for this composition — produced
+     * by invoking the consumer's `groupTranslator` (if attached) with this
+     * runner's `GroupMetadata`. Returns `undefined` when no translator was
+     * attached.
+     *
+     * STABLE REFERENCE across calls. Computed on first access and cached;
+     * subsequent calls return the same value. Pairs with `getSpec()` —
+     * library shape on one side, consumer-shaped UI on the other.
+     *
+     * Subclasses MUST override `buildUIGroupMetadata()` (the next hook) to
+     * supply the `GroupMetadata` for their composition kind. This method
+     * (the public surface) is `final`-by-convention — do not override.
+     */
+    getUIGroup<T = unknown>(): T | undefined;
+    /**
+     * Subclass hook — returns the consumer's translator if one was
+     * provided at construction time. Default: no translator (returns
+     * undefined). Each composition overrides to surface its own
+     * `opts.groupTranslator`.
+     */
+    protected getGroupTranslator(): import('./translator.js').GroupTranslator | undefined;
+    /**
+     * Translate this runner's group metadata with a CALLER-SUPPLIED
+     * translator that overrides the runner's own default. Used by
+     * parent compositions to apply per-method translator overrides.
+     * See the `Runner.getUIGroupWith` JSDoc for the contract.
+     */
+    getUIGroupWith<T = unknown>(override: import('./translator.js').GroupTranslator): T | undefined;
+    /**
+     * Subclass hook — returns the `GroupMetadata` for this composition.
+     * Default: undefined, meaning "no group translation for this runner
+     * kind." Compositions override to supply their members + kind. Called
+     * AT MOST ONCE per runner (result is cached by `getUIGroup()`).
+     */
+    protected buildUIGroupMetadata(): import('./translator.js').GroupMetadata | undefined;
+    /**
+     * Build + cache the runner's `FlowChart` exactly once. Called by the
+     * subclass constructor AFTER all instance fields are set, so the
+     * builder lambda can close over them safely.
+     *
+     * Throws if called twice on the same instance — the chart is meant
+     * to be immutable post-construction. Each `run()` reuses the same
+     * chart in a fresh `FlowChartExecutor`.
+     *
+     * Implementation invariant (per footprintjs inventor review):
+     * each attached `StructureRecorder` fires exactly N times per
+     * construction (N = node count). Two `getSpec()` calls return the
+     * same `FlowChart` object reference. `_mergeStageMap` collision
+     * guards never see false-positives because each child runner's
+     * stage functions are created once and reused.
+     */
+    protected initChart(builder: () => FlowChart): void;
     /**
      * Execute the runner. Subclass may override for specialized input
-     * mapping, but default invokes toFlowChart() + FlowChartExecutor.
+     * mapping, but default invokes getSpec() + FlowChartExecutor.
      */
     abstract run(input: TIn, options?: RunOptions): Promise<TOut | RunnerPauseOutcome>;
     /**

package/dist/types/core/RunnerBase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RunnerBase.d.ts","sourceRoot":"","sources":["../../../src/core/RunnerBase.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,SAAS,EACT,iBAAiB,EACjB,mBAAmB,EACnB,UAAU,EACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,oBAAoB,EACrB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAGV,uBAAuB,EACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAgBpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAI3D;;GAEG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED,8BAAsB,UAAU,CAAC,GAAG,GAAG,OAAO,EAAE,IAAI,GAAG,OAAO,CAAE,YAAW,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC;IAC1F,SAAS,CAAC,QAAQ,CAAC,UAAU,kBAAyB;IACtD,SAAS,CAAC,QAAQ,CAAC,iBAAiB,EAAE,gBAAgB,EAAE,CAAM;IAI9D;;;OAGG;IACH,QAAQ,CAAC,WAAW,IAAI,SAAS;IAEjC;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,GAAG,kBAAkB,CAAC;IAElF;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CACb,UAAU,EAAE,mBAAmB,EAC/B,KAAK,CAAC,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,IAAI,GAAG,kBAAkB,CAAC;IAIrC;;;;;;;;OAQG;IACH,SAAS,CAAC,WAAW,CACnB,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,EAAE,OAAO,GACd,kBAAkB,GAAG,SAAS;IAiBjC;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAuBxB;;;OAGG;IACH,SAAS,CAAC,eAAe,CAAC,UAAU,EAAE,mBAAmB,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAsBhF,EAAE,CAAC,CAAC,SAAS,uBAAuB,EAClC,IAAI,EAAE,CAAC,EACP,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,OAAO,CAAC,EAAE,aAAa,GACtB,WAAW;IACd,EAAE,CAAC,IAAI,EAAE,oBAAoB,EAAE,QAAQ,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,WAAW;IAkBhG,GAAG,CAAC,CAAC,SAAS,uBAAuB,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI;IACjF,GAAG,CAAC,IAAI,EAAE,oBAAoB,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAUjE,IAAI,CAAC,CAAC,SAAS,uBAAuB,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,WAAW;IACzF,IAAI,CAAC,IAAI,EAAE,oBAAoB,EAAE,QAAQ,EAAE,gBAAgB,GAAG,WAAW;IAYzE,MAAM,CAAC,QAAQ,EAAE,gBAAgB,GAAG,WAAW;IAU/C,QAAQ,CAAC,MAAM,EAAE,eAAe,CAe9B;IAIF;;;;;;;OAOG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAa1D;;;OAGG;IACH,SAAS,CAAC,WAAW,IAAI,SAAS;IAYlC;;;OAGG;IACH,SAAS,CAAC,eAAe,IAAI,SAAS,MAAM,EAAE;IAI9C;;;;OAIG;IACH,SAAS,CAAC,aAAa,IAAI,eAAe;CAG3C"}
+{"version":3,"file":"RunnerBase.d.ts","sourceRoot":"","sources":["../../../src/core/RunnerBase.ts"],"names":[],"mappings":"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"}