footprintjs 9.19.1 → 9.21.0

package/CLAUDE.md

@@ -34,6 +34,8 @@ Entry points: `footprintjs` (public API) · `/recorders` (factories) · `/trace`
 
 **Retry (9.15.0):** `StageNode.retry` is a POLICY on a stage, not a kind — no new node type, no `computeNodeType` edit. The loop lives in `FlowchartTraverser.executeStage` (:720), so linear/streaming/pausable/decider/selector/fork-child/subflow-inner all get it from one implementation. A failed non-final attempt calls `StageContext.discardStaged()` (buffer + stateView + _stageWrites/_stageReads + _provenanceReads + _untrackedSources); the final attempt is today's law untouched. PauseSignal and abort are NEVER retried. One runtimeStageId + one CommitBundle per stage regardless of attempts; retries do not consume `maxIterations`.
 
+**Declared tags (9.21.0):** `StageNode.tags?: readonly string[]` is a NAME on a stage, declared at build time — POLICY-like (the retry precedent): no node type, no `computeNodeType` edit, no type-union site, and both prefixer twins spread `{ ...node }` so it rides subflow prefixing untouched. ONE landing site `FlowChartBuilder.ts · applyTags` (twin of `applyRetryPolicy`) serves the `.tag(...names)` cursor modifier and every `options.tags` site; refuses empty/non-string/`~`/duplicate/double-declare at build. Stamp: `FlowchartTraverser.executeNodeStep` sets `context.tags = node.tags` beside `runtimeStageId` (unconditionally — a re-used context must not keep a prior node's names); `StageContext.commit` spreads `tagsFragment()` beside `untrackedSourcesFragment()` on BOTH commit paths and RELEASES it, so a double-commit path (fork child fan-out repeat, mount exit) records it once — absent when empty (`CommitBundle.tags?`; pinned byte-identical to 9.20.0 by test/lib/engine/scenario/declared-tags-byte-identity.test.ts). NOT inherited by createNext/createChild; the one synthetic node that would lose it is `FlowChartExecutor.resume`'s `innerResumeChain` (copies `pausedNode.tags` on both re-entries). The spec carries `tags` as-is (Map advertises the vocabulary; `RuntimeStructureManager.stageNodeToStructure` copies it for run-time-resolved nodes). Reader: `time-travel/tagStops.ts` = `filterStops(commitStops(...), any-of over log[stop.commitIdx].tags, meta = the array)`, exported from `/trace`. Never a runtime `$tag()` — a value would ride past every redaction point. Design: docs/design/2026-09-declared-tags.md.
+
 **Event order (code-verified; older docs had 3/4 swapped):** onStageStart → onRead/onWrite (live, PRE-commit) → **onStageEnd (StageRunner.ts:81) → onCommit (StageContext.ts:587)** → FlowRecorder onDecision/onFork/onSelected/onSubflowEntry → onStageExecuted (uniform, with stageType). Error path: commit STILL happens (FlowchartTraverser.ts:1088) before onError+rethrow — a failing stage's writes land. `interrupt()` rides the ERROR path's shape, not the pausable one: the stage function threw, so onStageEnd does NOT fire (the `addPausableFunction` pause DOES fire it — there the function returned normally).
 
 ## Extension points
@@ -63,7 +65,7 @@ run: executor.run (FlowChartExecutor.ts:1455): re-entrancy guard → fresh runId
 per stage: executeNodeStep stamps runtimeStageId (:818) → StageRunner.run: scopeFactory → onStageStart → stage fn (writes stage into TransactionBuffer via StageContext.setObject; onWrite fires live) → onStageEnd → traverser calls context.commit() (:1094) → onCommit → onStageExecuted (narrative flushes buffered ops here).
 decider: DeciderHandler.prepareDispatch (:89) — runs stage, **commits BEFORE branch resolution** (:124), matches branchId, fires onDecision(+evidence) → onStageExecuted('decider') → flat hop with InvokerStamp.
 loop: Phase 6 sees isLoopRef → ContinuationResolver.resolveTarget (:107): id-map lookup, iteration guard (max 1000), onLoop → hop; zero stack, state carries forward (never rewound).
-end: onRunEnd (throw → onRunFailed; pause → neither) → deferred terminalFlush → getSnapshot() = {sharedState (LIVE view; dev-mode frozen clone), initialState (the fold base), commitLog (detached+frozen), executionTree, subflowResults (dual-keyed), recorders}.
+end: onRunEnd (throw → onRunFailed; pause → neither) → deferred terminalFlush → getSnapshot() = {sharedState (LIVE view; dev-mode frozen clone), initialState (the fold base), commitLog (detached+frozen), executionTree, subflowResults (dual-keyed; `globalContext` = the subflow's LIVE heap, or under `redact: true` its own nested mirror — 9.20.0, `servedSubflowResults`), recorders}.
 
 ## Backtracking
 Seven mechanisms, no state rollback anywhere: **M1** TransactionBuffer staging + net-change commit — commit-on-error by design, explicitly NOT rollback (TransactionBuffer.ts:13-18; error path commits then rethrows). **M2** Pause/Resume checkpointing — the only resume-from-prior-point; TWO raise shapes, ONE checkpoint: `addPausableFunction` (resume runs `resumeFn`) and `interrupt(scope, payload)` (resume RE-RUNS THE STAGE FUNCTION FROM ITS TOP — stages are atomic; the answer returns out of the `interrupt()` call via a WeakMap keyed by the scope), discriminated by `checkpoint.pausedBy`; checkpoint is one detached structuredClone; resume rebuilds the cursor from pausedStageId+subflowPath and only overrides the LEAF subflow root (2+-deep pause re-executes outer pre-mount stages). **M3** commit-log replay (EventLog.materialise, commitValueAt — required under delta mode). **M4** loopTo re-entry — forward execution over accumulated state, bounded by maxIterations + dynamicNextHops. **M5** causalChain backward slicing (read-only analysis; honesty flags for untracked reads; `edgeAttribution: 'per-write'` refines edges via `TraceEntry.readKeys` when the writeProvenance dial recorded them — worklist, subset-of-ceiling safe). **M6 (query layer)** slice/ — variable-first triage: sliceForKey + append-fold element provenance + the ONLY safe serializations (sliceToJSON/formatSlice — never JSON.stringify a slice root). **M7 (read-time cursor)** time-travel/ — `timeTravel(snapshot)` walks stops over the finished log with `stateAt()` folding M3's replay at each one (base = `RuntimeSnapshot.initialState`, which now travels with the log); it is a READER, never a second live cursor, and `drill(mount)` opens a separate cursor over a subflow's own isolated log. 9.18.0: `timeTravel([paused, resumed])` chains a cross-executor M2 resume into ONE axis — the resumed leg's `initialState` (= the state at the pause) restarts the fold, commit indices stay run-local (`Stop.sourceIdx` names the leg), and the chain is refused unless the never-reset execution counter is monotonic across legs. Deep dive + step tables: [.claude/rules/backtracking.md](.claude/rules/backtracking.md).

package/dist/esm/lib/builder/FlowChartBuilder.d.ts

@@ -38,10 +38,12 @@ export declare class DeciderList<TOut = any, TScope = any> {
     addFunctionBranch(id: string, name: string, fn?: StageFunction<TOut, TScope>, description?: string, 
     /** `{ loopTo }` declares this branch loops back to an already-declared
      *  stage — the loop is SOURCED FROM THIS BRANCH (not the decider).
-     *  `{ retry }` gives THIS BRANCH's stage a declarative retry policy. */
+     *  `{ retry }` gives THIS BRANCH's stage a declarative retry policy;
+     *  `{ tags }` puts declared tags on it (see `FlowChartBuilder.tag`). */
     options?: {
         readonly loopTo?: string;
         readonly retry?: RetryPolicy;
+        readonly tags?: readonly string[];
     }): DeciderList<TOut, TScope>;
     /**
      * Add a pausable stage as a decider branch.
@@ -56,10 +58,11 @@ export declare class DeciderList<TOut = any, TScope = any> {
      *  stage — the loop is SOURCED FROM THIS BRANCH (not the decider).
      *  `{ retry }` gives THIS BRANCH's `execute` half a retry policy (the
      *  `resume` half runs without it — a different function, a different
-     *  contract). */
+     *  contract); `{ tags }` puts declared tags on it. */
     options?: {
         readonly loopTo?: string;
         readonly retry?: RetryPolicy;
+        readonly tags?: readonly string[];
     }): DeciderList<TOut, TScope>;
     addSubFlowChartBranch(id: string, subflow: FlowChart<any, any>, mountName?: string, options?: SubflowMountOptions): DeciderList<TOut, TScope>;
     addLazySubFlowChartBranch(id: string, resolver: () => FlowChart<any, any>, mountName?: string, options?: SubflowMountOptions): DeciderList<TOut, TScope>;
@@ -116,9 +119,11 @@ export declare class SelectorFnList<TOut = any, TScope = any> {
     private readonly branchDescInfo;
     constructor(builder: FlowChartBuilder<TOut, TScope>, curNode: StageNode<TOut, TScope>, curSpec: SerializedPipelineStructure, parentDescriptionParts?: string[], parentStageDescriptions?: Map<string, string>, reservedStepNumber?: number, selectorDescription?: string);
     addFunctionBranch(id: string, name: string, fn?: StageFunction<TOut, TScope>, description?: string, 
-    /** `{ retry }` gives THIS BRANCH's stage a declarative retry policy. */
+    /** `{ retry }` gives THIS BRANCH's stage a declarative retry policy;
+     *  `{ tags }` puts declared tags on it (see `FlowChartBuilder.tag`). */
     options?: {
         readonly retry?: RetryPolicy;
+        readonly tags?: readonly string[];
     }): SelectorFnList<TOut, TScope>;
     /**
      * Add a pausable stage as a selector branch.
@@ -130,9 +135,10 @@ export declare class SelectorFnList<TOut = any, TScope = any> {
     addPausableFunctionBranch(id: string, name: string, handler: PausableHandler<TScope>, description?: string, 
     /** `{ retry }` gives THIS BRANCH's `execute` half a retry policy (the
      *  `resume` half runs without it — a different function, a different
-     *  contract). */
+     *  contract); `{ tags }` puts declared tags on it. */
     options?: {
         readonly retry?: RetryPolicy;
+        readonly tags?: readonly string[];
     }): SelectorFnList<TOut, TScope>;
     addSubFlowChartBranch(id: string, subflow: FlowChart<any, any>, mountName?: string, options?: SubflowMountOptions): SelectorFnList<TOut, TScope>;
     addLazySubFlowChartBranch(id: string, resolver: () => FlowChart<any, any>, mountName?: string, options?: SubflowMountOptions): SelectorFnList<TOut, TScope>;
@@ -295,6 +301,7 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
     }): this;
     start(name: string, fn: StageFunction<TOut, TScope> | PausableHandler<TScope>, id: string, description?: string, options?: {
         retry?: RetryPolicy;
+        tags?: readonly string[];
     }): this;
     /**
      * Start a chart whose ROOT stage IS a selector — it runs first (reading
@@ -311,6 +318,7 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
     startSelector(name: string, fn: StageFunction<any, TScope>, id: string, description?: string, options?: {
         failFast?: boolean;
         retry?: RetryPolicy;
+        tags?: readonly string[];
     }): SelectorFnList<TOut, TScope>;
     addFunction(name: string, fn: StageFunction<TOut, TScope>, id: string, description?: string): this;
     addStreamingFunction(name: string, fn: StageFunction<TOut, TScope>, id: string, streamId?: string, description?: string): this;
@@ -420,17 +428,20 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
     addDeciderFunction(name: string, fn: StageFunction<any, TScope>, id: string, description?: string, 
     /** `{ retry }` gives the DECIDER STAGE a retry policy. Declared here rather
      *  than via `.retry()` because this method returns a `DeciderList`, where a
-     *  chained modifier could mean the decider OR the branch just added. */
+     *  chained modifier could mean the decider OR the branch just added;
+     *  `{ tags }` likewise. */
     options?: {
         retry?: RetryPolicy;
+        tags?: readonly string[];
     }): DeciderList<TOut, TScope>;
     addSelectorFunction(name: string, fn: StageFunction<any, TScope>, id: string, description?: string, 
     /** `{ retry }` gives the SELECTOR STAGE a retry policy — same reasoning as
      *  `addDeciderFunction`: this method returns a sub-builder, so a chained
-     *  `.retry()` would be ambiguous. */
+     *  `.retry()` would be ambiguous; `{ tags }` likewise. */
     options?: {
         failFast?: boolean;
         retry?: RetryPolicy;
+        tags?: readonly string[];
     }): SelectorFnList<TOut, TScope>;
     addListOfFunction(children: SimplifiedParallelSpec<TOut, TScope>[], options?: {
         failFast?: boolean;
@@ -522,6 +533,56 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
      * `retry` option instead.
      */
     retry(policy: RetryPolicy): this;
+    /**
+     * Put NAMES on the stage you JUST added. The first commit bundle of each
+     * execution of that stage carries them (`CommitBundle.tags` — the bundle
+     * `commitStops` keys on), and the built spec advertises them
+     * (`SerializedPipelineStructure.tags`).
+     *
+     * ## Why declare it instead of deriving it from ids
+     *
+     * A reader that wants "the LLM turns" of a stored recording had to classify
+     * stages from their ids — a switch over `runtimeStageId` that parses `#` and
+     * `/`, lives in the consumer, and silently goes stale when a stage is
+     * renamed. Declared here, the name travels WITH the commit: a recording from
+     * any chart carries its own milestones, and `tagStops` (footprintjs/trace)
+     * scrubs them with no id conventions at all.
+     *
+     * ## What a tag is, and is not
+     *
+     * A tag is a NAME declared at build time — never a value. There is no
+     * run-time `$tag()`: a runtime string could carry data (`'user:' + email`)
+     * past every redaction point. Data-dependent marks are a keep rule over
+     * the fold at read time, or telemetry via `$emit`. Free strings: footprintjs
+     * owns no vocabulary; a consumer declares its own (`'milestone:<kind>'`).
+     *
+     * Stamped ONCE per execution of the stage: retry attempts share one stamp,
+     * a failed stage keeps its tag (the error path commits before it rethrows),
+     * a stage that `interrupt()`s and is resumed is two tagged stops on a chain
+     * because it ran twice, and an EMPTY commit is a tagged stop too. A subflow
+     * mount or a parallel-for-each stage can be tagged; the tag lands on the
+     * bundle that records its result.
+     *
+     * @example
+     * ```ts
+     * flowChart<State>('Seed', seedFn, 'seed')
+     *   .addFunction('Call model', callFn, 'call-llm')
+     *   .tag('milestone:llm-turn')
+     *   .addFunction('Route', routeFn, 'route')
+     *   .tag('milestone:decision', 'audit')
+     * ```
+     *
+     * Applies to the CURRENT cursor — the stage added by the immediately
+     * preceding `start()` / `addFunction()` / `addStreamingFunction()` /
+     * `addPausableFunction()` / `addSubFlowChartNext()` / `addParallelForEach()`.
+     * Where the cursor would be ambiguous (a decider, selector, branch, or fork
+     * child), declare the tags in that method's own `tags` option instead.
+     *
+     * Refused at build time: an empty name, a non-string, the reserved
+     * branch-segment marker `~` inside a name, a name declared twice, and a
+     * second declaration on the same stage.
+     */
+    tag(...names: readonly string[]): this;
     loopTo(stageId: string): this;
     onStream(handler: StreamTokenHandler): this;
     onStreamStart(handler: StreamLifecycleHandler): this;