agentfootprint 2.14.5 → 3.0.0

package/dist/esm/core-flow/Loop.js

@@ -30,6 +30,10 @@ export class Loop extends RunnerBase {
     maxIterations;
     maxWallclockMs;
     until;
+    opts;
+    /** Per-method translator override on `.repeat()`, when set. Applies
+     *  to the body member's `uiGroup`. */
+    bodyTranslator;
     currentRunContext = {
         runStartMs: 0,
         runId: 'pending',
@@ -37,21 +41,55 @@ export class Loop extends RunnerBase {
     };
     constructor(opts, body, config) {
         super();
+        this.opts = opts;
         this.name = opts.name ?? 'Loop';
         this.id = opts.id ?? 'loop';
         this.body = body;
         this.maxIterations = clampIterations(config.maxIterations);
         this.maxWallclockMs = config.maxWallclockMs;
         this.until = config.until;
+        this.bodyTranslator = config.bodyTranslator;
+        // Eager chart construction — see `RunnerBase.initChart` JSDoc.
+        this.initChart(() => this.buildChart());
     }
     static create(opts = {}) {
         return new LoopBuilder(opts);
     }
-    toFlowChart() {
-        return this.buildChart();
+    // `getSpec()` inherited from RunnerBase — returns the cached chart.
+    // ─── UI group translation (L1b) ───────────────────────────────
+    getGroupTranslator() {
+        return this.opts.groupTranslator;
+    }
+    /** Loop has a single body member + iteration budgets in `extra`.
+     *  Per-method override (L1c) takes precedence over the body
+     *  runner's own translator. */
+    buildUIGroupMetadata() {
+        const members = [
+            {
+                memberId: 'body',
+                runner: this.body,
+                uiGroup: this.bodyTranslator !== undefined
+                    ? this.body.getUIGroupWith(this.bodyTranslator)
+                    : this.body.getUIGroup(),
+            },
+        ];
+        return {
+            kind: 'Loop',
+            id: this.id,
+            name: this.name,
+            members,
+            extra: {
+                maxIterations: this.maxIterations,
+                ...(this.maxWallclockMs !== undefined && {
+                    maxWallclockMs: this.maxWallclockMs,
+                }),
+                hasUntilGuard: this.until !== undefined,
+            },
+        };
     }
     async run(input, options) {
         const executor = this.createExecutor();
+        this.lastExecutor = executor;
         const result = await executor.run({
             input: { message: input.message },
             ...(options ?? {}),
@@ -70,8 +108,8 @@ export class Loop extends RunnerBase {
             runId: makeRunId(),
             compositionPath: [`Loop:${this.id}`],
         };
-        const chart = this.buildChart();
-        const executor = new FlowChartExecutor(chart);
+        // Reuse the cached chart built at constructor time.
+        const executor = new FlowChartExecutor(this.getSpec());
         const dispatcher = this.getDispatcher();
         const getRunCtx = () => this.currentRunContext;
         executor.attachCombinedRecorder(new ContextRecorder({ dispatcher, getRunContext: getRunCtx }));
@@ -171,9 +209,14 @@ export class Loop extends RunnerBase {
         };
         // Root description prefix `Loop:` is the taxonomy marker — see
         // FlowchartRecorder.mapTopologyToSteps for the consumer side.
-        return flowChart('Seed', seed, 'seed', undefined, 'Loop: iterated body')
+        return flowChart('Seed', seed, 'seed', {
+            ...(this.opts.structureRecorders !== undefined && {
+                structureRecorders: [...this.opts.structureRecorders],
+            }),
+            description: 'Loop: iterated body',
+        })
             .addFunction('IterationStart', iterationStart, 'iteration-start', 'Loop iteration marker')
-            .addSubFlowChartNext('body', body.toFlowChart(), 'body', {
+            .addSubFlowChartNext('body', body.getSpec(), 'body', {
             inputMapper: (parent) => ({ message: parent.current ?? '' }),
             // Body's string return becomes next iteration's input via `current`.
             outputMapper: (sfOutput) => ({
@@ -185,18 +228,10 @@ export class Loop extends RunnerBase {
             .build();
     }
 }
-/**
- * Fluent builder. Reads as natural English:
- *   Loop.create().repeat(runner).times(10).forAtMost(30_000).until(fn).build()
- *   →  "Loop: repeat runner, up to 10 times, for at most 30 seconds, until fn."
- *
- * Enforces a body runner is supplied before .build(). Default budget is
- * 10 iterations (hard ceiling 500). Any of .times / .forAtMost / .until
- * can fire to exit the loop.
- */
 export class LoopBuilder {
     opts;
     _body;
+    _bodyTranslator;
     _maxIterations;
     _maxWallclockMs;
     _until;
@@ -206,12 +241,19 @@ export class LoopBuilder {
     /**
      * The runner that executes each iteration. Required.
      * Each iteration's output string becomes the next iteration's input `{ message }`.
+     *
+     * Optional second arg `opts.groupTranslator` overrides the body
+     * runner's own translator for THIS loop only — only its
+     * `member.uiGroup` flips to the override's output.
      */
-    repeat(runner) {
+    repeat(runner, opts) {
         if (this._body !== undefined) {
             throw new Error('Loop.repeat(): already set');
         }
         this._body = runner;
+        if (opts?.groupTranslator !== undefined) {
+            this._bodyTranslator = opts.groupTranslator;
+        }
         return this;
     }
     /**
@@ -247,6 +289,7 @@ export class LoopBuilder {
             maxIterations,
             ...(this._maxWallclockMs !== undefined && { maxWallclockMs: this._maxWallclockMs }),
             ...(this._until !== undefined && { until: this._until }),
+            ...(this._bodyTranslator !== undefined && { bodyTranslator: this._bodyTranslator }),
         });
     }
 }

package/dist/esm/core-flow/Loop.js.map

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

package/dist/esm/core-flow/Parallel.js

@@ -10,7 +10,7 @@
  *          composition.fork_start / branch_complete / merge_end
  *          (via compositionRecorder).
  */
-import { FlowChartExecutor, flowChart, } from 'footprintjs';
+import { FlowChartExecutor, flowChart, isFlowEvent, } from 'footprintjs';
 import { RunnerBase, makeRunId } from '../core/RunnerBase.js';
 import { ContextRecorder } from '../recorders/core/ContextRecorder.js';
 import { streamRecorder } from '../recorders/core/StreamRecorder.js';
@@ -22,13 +22,29 @@ export class Parallel extends RunnerBase {
     id;
     branches;
     merge;
+    opts;
     currentRunContext = {
         runStartMs: 0,
         runId: 'pending',
         compositionPath: [],
     };
+    /**
+     * Per-branch first-error messages captured during the current run.
+     *
+     * Filled by an internal CombinedRecorder attached in `createExecutor()`
+     * that observes footprintjs `FlowErrorEvent`s. Errors are keyed by the
+     * branch id (the first segment of `traversalContext.subflowPath`); only
+     * the first error per branch is kept so the surface mirrors the wrapper
+     * `try/catch` semantics that preceded the v0.x architectural refactor.
+     *
+     * Read by the Merge stage to populate strict-mode error messages and
+     * tolerant-mode `BranchOutcome.error` strings. Cleared at the start of
+     * every `run()` / `resume()`.
+     */
+    branchErrors = new Map();
     constructor(opts, branches, merge) {
         super();
+        this.opts = opts;
         this.name = opts.name ?? 'Parallel';
         this.id = opts.id ?? 'parallel';
         if (branches.length < 2) {
@@ -36,15 +52,53 @@ export class Parallel extends RunnerBase {
         }
         this.branches = branches;
         this.merge = merge;
+        // Eager chart construction — see `RunnerBase.initChart` JSDoc.
+        // Safe: the merge stage's closure captures `this.branchErrors`
+        // (an instance field initialized at declaration time, line 130),
+        // which is set BEFORE the constructor body runs.
+        this.initChart(() => this.buildChart());
     }
     static create(opts = {}) {
         return new ParallelBuilder(opts);
     }
-    toFlowChart() {
-        return this.buildChart();
+    // `getSpec()` inherited from RunnerBase — returns the cached chart.
+    // ─── UI group translation (L1b) ───────────────────────────────
+    getGroupTranslator() {
+        return this.opts.groupTranslator;
+    }
+    /**
+     * Build the Parallel's `GroupMetadata` — kind `'Parallel'`, with one
+     * `GroupMember` per branch. Each member exposes its `runner` plus
+     * the runner's own `getUIGroup()` output (when the consumer
+     * threaded the same translator through that branch's construction).
+     */
+    buildUIGroupMetadata() {
+        const members = this.branches.map((b) => ({
+            memberId: b.id,
+            runner: b.runner,
+            // Per-method override (L1c) takes precedence over the branch
+            // runner's own constructor-level translator. When present, the
+            // override runs against the branch runner's own GroupMetadata
+            // and its output becomes `member.uiGroup`. When absent, fall
+            // back to `branch.runner.getUIGroup()` which applies the
+            // runner's own translator (if any).
+            uiGroup: b.groupTranslator !== undefined
+                ? b.runner.getUIGroupWith(b.groupTranslator)
+                : b.runner.getUIGroup(),
+        }));
+        return {
+            kind: 'Parallel',
+            id: this.id,
+            name: this.name,
+            members,
+            extra: {
+                mergeStrategy: this.merge.kind,
+            },
+        };
     }
     async run(input, options) {
         const executor = this.createExecutor();
+        this.lastExecutor = executor;
         const result = await executor.run({
             input: { message: input.message },
             ...(options ?? {}),
@@ -63,18 +117,71 @@ export class Parallel extends RunnerBase {
             runId: makeRunId(),
             compositionPath: [`Parallel:${this.id}`],
         };
-        const chart = this.buildChart();
-        const executor = new FlowChartExecutor(chart);
+        // Reset per-run branch-error capture. Fork children now mount the
+        // branch runner's own chart (no try/catch wrapper); errors are
+        // captured via FlowRecorder.onError correlation by subflow path.
+        this.branchErrors.clear();
+        // Reuse the cached chart built at constructor time.
+        const executor = new FlowChartExecutor(this.getSpec());
         const dispatcher = this.getDispatcher();
         const getRunCtx = () => this.currentRunContext;
         executor.attachCombinedRecorder(new ContextRecorder({ dispatcher, getRunContext: getRunCtx }));
         executor.attachCombinedRecorder(streamRecorder({ dispatcher, getRunContext: getRunCtx }));
         executor.attachCombinedRecorder(agentRecorder({ dispatcher, getRunContext: getRunCtx }));
         executor.attachCombinedRecorder(compositionRecorder({ dispatcher, getRunContext: getRunCtx }));
+        executor.attachCombinedRecorder(this.makeBranchErrorRecorder());
         for (const r of this.attachedRecorders)
             executor.attachCombinedRecorder(r);
         return executor;
     }
+    /**
+     * Build the internal recorder that captures first-error-per-branch.
+     *
+     * footprintjs's `SubflowExecutor` swallows subflow errors into
+     * `parentContext.debug.addError(...)` and skips the `outputMapper`,
+     * so the failed branch's error message never lands in parent scope.
+     * To preserve the per-branch error surface the wrapper-based design
+     * provided, we observe `FlowRecorder.onError` and correlate by the
+     * first segment of `traversalContext.subflowPath`.
+     *
+     * Only the FIRST error per branch is kept. Errors fired outside any
+     * branch (e.g., a Merge-stage error) are ignored.
+     */
+    makeBranchErrorRecorder() {
+        const branchIds = new Set(this.branches.map((b) => b.id));
+        return {
+            id: 'parallel-branch-errors',
+            onError: (event) => {
+                if (!isFlowEvent(event))
+                    return;
+                const ctx = event.traversalContext;
+                if (!ctx)
+                    return;
+                // The branch id is the first segment of the engine-prefixed
+                // `stageId` (e.g. `bad/call-llm` → branch `bad`). `subflowPath`
+                // is sometimes empty for first-level subflows, and `subflowId`
+                // can be deeper than the branch when LLMCall/Agent mount their
+                // own internal subflows. The stageId prefix is the canonical
+                // origin path.
+                const stageId = ctx.stageId ?? '';
+                const slash = stageId.indexOf('/');
+                const branchId = slash >= 0 ? stageId.slice(0, slash) : undefined;
+                if (branchId === undefined || !branchIds.has(branchId))
+                    return;
+                if (!this.branchErrors.has(branchId)) {
+                    // Strip the leading "Error: " that `error.toString()` adds
+                    // for standard `Error` instances so the captured message
+                    // matches the original `throw new Error(msg)` reason exactly
+                    // (consumers expect the bare message). Non-Error throws
+                    // never carry this prefix, so the strip is a no-op there.
+                    const m = event.message.startsWith('Error: ')
+                        ? event.message.slice('Error: '.length)
+                        : event.message;
+                    this.branchErrors.set(branchId, m);
+                }
+            },
+        };
+    }
     finalizeResult(executor, result) {
         const paused = this.detectPause(executor, result);
         if (paused)
@@ -107,36 +214,67 @@ export class Parallel extends RunnerBase {
         };
         // Root description prefix `Parallel:` is the taxonomy marker — see
         // FlowchartRecorder.mapTopologyToSteps for the consumer side.
-        let builder = flowChart('Seed', seed, 'seed', undefined, `Parallel: ${branches.length}-way fanout`);
-        // Fork children — each branch is wrapped in a chart that runs the
-        // branch runner in try/catch. The wrapper always succeeds (no error
-        // propagates up), so the outputMapper always fires and records a
-        // typed `BranchOutcome` for the Merge stage to inspect.
+        // The 4th arg threads the consumer's `structureRecorders` (when set)
+        // into footprintjs's builder so every node in this chart is observed
+        // by them at construction time.
+        let builder = flowChart('Seed', seed, 'seed', {
+            ...(this.opts.structureRecorders !== undefined && {
+                structureRecorders: [...this.opts.structureRecorders],
+            }),
+            description: `Parallel: ${branches.length}-way fanout`,
+        });
+        // Fork children — each branch is mounted as a proper subflow via
+        // footprintjs's native fork mode. Multiple `addSubFlowChart` calls
+        // on the same builder cursor produce a fork node (`type: 'fork'`);
+        // `ChildrenExecutor` runs them concurrently via `Promise.allSettled`.
         //
-        // Strict mode (default): Merge throws on any branch failure. Tolerant
-        // mode: Merge passes the full outcomes map to the consumer's merge fn.
+        // The branch's OWN chart (its `getSpec()`) is mounted directly — no
+        // wrapper. This preserves the parent's `runtimeStageId` address
+        // space across branch internals: every LLM call, tool execution,
+        // and commit inside a branch appears in the parent executor's
+        // commitLog with a globally-unique id. Recorder events flow
+        // naturally — no `scope.$emit` forwarding needed.
+        //
+        // Error handling: a failing branch's `outputMapper` does NOT fire
+        // (footprintjs convention: `subflowError` skips output mapping).
+        // The branch id is absent from `branchResults`. The merge stage
+        // detects this via `branches.map(b => b.id) \ keys(branchResults)`
+        // and either throws (strict mode) or synthesizes `BranchOutcome`
+        // entries for the tolerant `outcomes-fn` merge.
         for (const branch of branches) {
-            builder = builder.addSubFlowChart(branch.id, buildBranchWrapperChart(branch), branch.name, {
+            builder = builder.addSubFlowChart(branch.id, branch.runner.getSpec(), branch.name, {
                 inputMapper: (parent) => ({ message: parent.userMessage ?? '' }),
-                // The wrapper's terminal stage returns a BranchOutcome. Stash it
-                // under the branch id; shallow-merge across siblings produces
-                // the full outcomes map.
                 outputMapper: (sfOutput) => ({
-                    branchOutcomes: {
-                        [branch.id]: sfOutput,
+                    branchResults: {
+                        [branch.id]: typeof sfOutput === 'string' ? sfOutput : '',
                     },
                 }),
             });
         }
         // Merge stage — runs after all fork children complete (join point).
+        // Closes over `this.branchErrors` (populated by the internal
+        // `parallel-branch-errors` recorder) so per-branch error messages
+        // survive subflow boundary swallowing in footprintjs.
+        const branchErrors = this.branchErrors;
         const mergeStage = async (scope) => {
-            const outcomes = scope.branchOutcomes ?? {};
-            const failures = Object.entries(outcomes).filter(([, o]) => !o.ok);
+            const results = scope.branchResults ?? {};
+            // Detect failures by absence: any expected branch id missing
+            // from `branchResults` is a branch whose `outputMapper` didn't
+            // fire — i.e., one whose subflow errored. The specific error
+            // message comes from the recorder-captured `branchErrors` map.
+            //
+            // Caveat: footprintjs does NOT fire `FlowRecorder.onError` for
+            // errors thrown INSIDE `applyOutputMapping` (those are caught
+            // separately in `SubflowExecutor` and routed to
+            // `parentContext.addError('outputMapperError', ...)`). A branch
+            // whose subflow completed cleanly but whose outputMapper threw
+            // will therefore show up here as a missing id with no entry in
+            // `branchErrors` — strict-mode aggregation prints `unknown
+            // error` for it and tolerant-mode synthesizes the same string.
+            // This is a known gap; see `core-flow/README.md` Decision 8.
+            const failedIds = branches.map((b) => b.id).filter((id) => !(id in results));
             const isTolerant = merge.kind === 'outcomes-fn';
-            if (failures.length > 0 && !isTolerant) {
-                const details = failures
-                    .map(([id, o]) => `  ${id}: ${o.error}`)
-                    .join('\n');
+            if (failedIds.length > 0 && !isTolerant) {
                 typedEmit(scope, 'agentfootprint.composition.exit', {
                     kind: 'Parallel',
                     id: compositionId,
@@ -144,34 +282,64 @@ export class Parallel extends RunnerBase {
                     status: 'err',
                     durationMs: Date.now() - this.currentRunContext.runStartMs,
                 });
-                throw new Error(`Parallel '${compositionId}': ${failures.length} branch(es) failed:\n${details}\n` +
+                const details = failedIds
+                    .map((id) => `  ${id}: ${branchErrors.get(id) ?? 'unknown error'}`)
+                    .join('\n');
+                throw new Error(`Parallel '${compositionId}': ${failedIds.length} branch(es) failed:\n${details}\n` +
                     `(use .mergeOutcomesWithFn() for tolerant-mode partial-failure handling)`);
             }
+            // Run the merge strategy. Wrap in try/catch so that a merge-stage
+            // failure (e.g., merge LLM throws) still produces a
+            // `composition.exit` event with `status: 'err'` — without this the
+            // event stream would have a `composition.enter` without a matching
+            // `composition.exit`, breaking dashboards that pair the two.
             let merged;
-            if (merge.kind === 'fn') {
-                const results = {};
-                for (const [id, o] of Object.entries(outcomes)) {
-                    if (o.ok)
-                        results[id] = o.value;
+            try {
+                if (merge.kind === 'fn') {
+                    merged = merge.fn(results);
                 }
-                merged = merge.fn(results);
-            }
-            else if (merge.kind === 'llm') {
-                const results = {};
-                for (const [id, o] of Object.entries(outcomes)) {
-                    if (o.ok)
-                        results[id] = o.value;
+                else if (merge.kind === 'llm') {
+                    merged = await mergeWithLLM(scope, merge.opts, results);
+                }
+                else {
+                    // Tolerant-mode: synthesize BranchOutcome map for the consumer.
+                    const outcomes = {};
+                    for (const b of branches) {
+                        if (b.id in results) {
+                            outcomes[b.id] = { ok: true, value: results[b.id] };
+                        }
+                        else {
+                            outcomes[b.id] = {
+                                ok: false,
+                                error: branchErrors.get(b.id) ?? 'unknown error',
+                            };
+                        }
+                    }
+                    merged = merge.fn(outcomes);
                 }
-                merged = await mergeWithLLM(scope, merge.opts, results);
             }
-            else {
-                merged = merge.fn(outcomes);
+            catch (err) {
+                typedEmit(scope, 'agentfootprint.composition.exit', {
+                    kind: 'Parallel',
+                    id: compositionId,
+                    name: compositionName,
+                    status: 'err',
+                    durationMs: Date.now() - this.currentRunContext.runStartMs,
+                });
+                throw err;
             }
+            const succeededCount = Object.keys(results).length;
             typedEmit(scope, 'agentfootprint.composition.merge_end', {
                 parentId: compositionId,
-                strategy: merge.kind === 'outcomes-fn' ? 'fn' : merge.kind,
+                // Emit the merge.kind verbatim so consumers can distinguish
+                // tolerant (`outcomes-fn`) from strict (`fn` / `llm`).
+                strategy: merge.kind,
                 resultSummary: truncate(merged, 80),
-                mergedBranchCount: branches.length,
+                // Number of branches that actually contributed a result to the
+                // merge. Equals `totalBranchCount` on full success; smaller in
+                // tolerant-mode runs where some branches failed.
+                mergedBranchCount: succeededCount,
+                totalBranchCount: branches.length,
             });
             typedEmit(scope, 'agentfootprint.composition.exit', {
                 kind: 'Parallel',
@@ -186,54 +354,6 @@ export class Parallel extends RunnerBase {
         return builder.build();
     }
 }
-/**
- * Build a wrapper chart that runs a branch Runner in a try/catch and
- * emits its events to the Parallel's dispatcher. The chart's terminal
- * stage returns a `BranchOutcome` — never throws up to the traverser.
- *
- * Event forwarding: the branch runner has its own EventDispatcher. We
- * subscribe to the wildcard `'*'` during run() and re-dispatch each
- * event on Parallel's dispatcher so consumers who attach listeners at
- * the Parallel level see the branch's llm/context/agent events.
- */
-function buildBranchWrapperChart(branch) {
-    const runBranch = async (scope) => {
-        const args = scope.$getArgs();
-        // Forward every branch-runner event via `scope.$emit` so it flows
-        // through footprintjs's emit channel. That channel reaches every
-        // EmitBridge attached to the CURRENT executor — including bridges
-        // belonging to outer compositions when this Parallel is nested
-        // (e.g., `Loop(Parallel(...))`). Forwarding directly to the
-        // Parallel's own dispatcher would be invisible to outer layers.
-        const unsubscribe = branch.runner.on('*', (e) => {
-            // `e.payload` is the typed payload union for the specific event;
-            // $emit accepts `unknown`, so no cast is needed — let it pass
-            // through structurally.
-            scope.$emit(e.type, e.payload);
-        });
-        try {
-            const result = await branch.runner.run({ message: args.message ?? '' });
-            if (typeof result === 'string') {
-                return { ok: true, value: result };
-            }
-            // Paused outcome: surface as "ok" with empty value — pauses from
-            // nested runners aren't failures, but Parallel doesn't yet propagate
-            // them through the merge. Consumers who need pause-inside-Parallel
-            // should set up nested pause handling at their own layer.
-            return { ok: true, value: '' };
-        }
-        catch (err) {
-            return {
-                ok: false,
-                error: err instanceof Error ? err.message : String(err),
-            };
-        }
-        finally {
-            unsubscribe();
-        }
-    };
-    return flowChart('RunBranch', runBranch, 'run-branch', undefined, `Parallel branch '${branch.id}' — catches failures`).build();
-}
 /** Fluent builder. Requires at least 2 branches + one merge strategy. */
 export class ParallelBuilder {
     opts;
@@ -243,13 +363,40 @@ export class ParallelBuilder {
     constructor(opts) {
         this.opts = opts;
     }
-    /** Add a branch. All branches run concurrently with the same input. */
-    branch(id, runner, name) {
+    /**
+     * Add a branch. All branches run concurrently with the same input.
+     *
+     * Third arg accepts EITHER a legacy bare `name` string (back-compat
+     * with pre-L1c callers) OR a `ParallelBranchOptions` bag containing
+     * `name` and/or a per-method `groupTranslator` override. The
+     * override applies ONLY to this branch's `member.uiGroup` and does
+     * not affect any other branch or the runner's own translator.
+     */
+    branch(id, runner, nameOrOpts) {
         if (this.seenIds.has(id)) {
             throw new Error(`Parallel.branch(): duplicate branch id '${id}'`);
         }
+        // Branch errors are correlated back to the originating branch by the
+        // first `/`-separated segment of footprintjs's engine-prefixed
+        // `traversalContext.stageId` (e.g., `legal/call-llm` → branch
+        // `legal`). A branch id containing `/` would silently shadow that
+        // mapping and drop the error message into 'unknown error' fallback.
+        if (id.includes('/')) {
+            throw new Error(`Parallel.branch(): id '${id}' must not contain '/' — it collides with footprintjs's subflow-path separator used for per-branch error correlation`);
+        }
         this.seenIds.add(id);
-        this.branches.push({ id, runner, name: name ?? id });
+        const opts = typeof nameOrOpts === 'string'
+            ? ({ name: nameOrOpts })
+            : nameOrOpts ?? {};
+        const entry = {
+            id,
+            runner,
+            name: opts.name ?? id,
+            ...(opts.groupTranslator !== undefined && {
+                groupTranslator: opts.groupTranslator,
+            }),
+        };
+        this.branches.push(entry);
         return this;
     }
     /**