@basein/runner 0.2.0 → 0.2.2

package/dist/replay/coverage.js

@@ -34,11 +34,11 @@ export function reachOf(toolName, wrapped, allow) {
 export function modeFor(steps, wrapped, allow) {
     if (steps.length === 0)
         return "none";
-    return steps.every((s) => reachOf(s.toolName, wrapped, allow) === "direct") ? "direct" : "steer";
+    return steps.every((s) => reachOf(s.toolName ?? "", wrapped, allow) === "direct") ? "direct" : "steer";
 }
 /** Per-step reach, in step order — what `plan.armed` logs and `bir doctor` shows. */
 export function coverageOf(steps, wrapped, allow) {
-    return steps.map((s) => reachOf(s.toolName, wrapped, allow));
+    return steps.map((s) => reachOf(s.toolName ?? "", wrapped, allow));
 }
 /**
  * Parse `BIR_REPLAY_ALLOW_SERVERS`. Unset (or empty) means *every wrapped

package/dist/replay/derive.d.ts

@@ -10,11 +10,20 @@
  * most sessions never arm. This is ~40 lines of `fetch` and it keeps the package
  * at zero runtime dependencies.
  *
- * NO KEY IS A SUPPORTED CONFIGURATION. Without `ANTHROPIC_API_KEY` the extraction
- * is skipped entirely and every parameter takes the value it had in the recorded
- * run — a plain replay of the recorded parameters, at zero cost. For a scenario
- * whose parameters rarely change that is a complete, free replay; for one that
- * keys off the prompt, it is why you want the key.
+ * NO KEY IS THE ORDINARY CONFIGURATION (segmented.md R-PARAM-5). Without
+ * `ANTHROPIC_API_KEY` the reading is done by the **service**, over one authorized
+ * POST to `/scenarios/:id/derive`, under the key it already uses to calculate
+ * scenarios and to ask its live question. That is the path nearly every session
+ * takes: the people this runs for are inside Claude Code on a subscription and
+ * have no API key to give it.
+ *
+ * A key here is an override, not a requirement. It keeps the reading on this
+ * machine — the prompt never reaches the service — which is what an in-house
+ * deployment wants, and it is one round trip faster.
+ *
+ * NEITHER is still supported and still means the same thing it always did:
+ * settings take their recorded samples and a scenario with a target declines,
+ * because a target is never guessed.
  *
  * The prompt and the parsing tolerances mirror RRepeat's
  * `deriveParametersFromScenarioPayload` exactly, so the two produce the same
@@ -23,12 +32,38 @@
  */
 import type { ParamsSchema } from "./types.js";
 export declare const DEFAULT_DERIVE_MODEL = "claude-haiku-4-5-20251001";
-export interface DeriveOptions {
+/** The call the agent was about to make when a plan armed mid-task. */
+export interface LiveCall {
+    toolName: string;
+    /** Redacted and capped, exactly as the probe sent it. */
+    toolInput: string;
+}
+/** What a turn can tell derivation beyond its prompt (segmented.md R-PARAM-2). */
+export interface DeriveContext {
+    liveCall?: LiveCall;
+    recentResults?: string[];
+}
+/**
+ * The service, which derives when this runner has no key of its own
+ * (R-PARAM-5). All three fields or none: a session that is not signed in has
+ * nowhere to ask.
+ */
+export interface DeriveService {
+    /** `BIR_AUTH_URL`, the same base the recorder reports to. */
+    baseUrl: string;
+    /** A live access token. Read late — the recorder refreshes it mid-session. */
+    token: string;
+    /** Whose parameters to read. The service takes the schema from its own row. */
+    scenarioId: string;
+}
+export interface DeriveOptions extends DeriveContext {
     prompt: string;
     intent: string;
     paramsObject: ParamsSchema | null;
-    /** Absent → sample values, at zero cost. */
+    /** An override that keeps the reading on this machine. Absent → the service. */
     apiKey?: string;
+    /** Used when there is no `apiKey`. Absent too → recorded samples. */
+    service?: DeriveService;
     model?: string;
     signal?: AbortSignal;
     /** Injected by tests. Defaults to global `fetch`. */
@@ -39,15 +74,27 @@ export interface DeriveResult {
     costUsd: number;
     /** False when the values came from the recorded samples rather than the model. */
     derived: boolean;
+    /** Who read the turn. For the audit line, and for nothing else. */
+    via?: "key" | "service" | "samples";
+    /** Why nothing was derived, when the service said. */
+    reason?: string;
     model?: string;
     inputTokens?: number;
     outputTokens?: number;
+    /**
+     * Targets that came back `null` (segmented.md R-PARAM-3). Non-empty means the
+     * plan must not run: the turn does not say what this task is to act on.
+     */
+    missing: string[];
+    /** Settings filled from their recorded sample (R-PARAM-2). */
+    sampled: string[];
 }
 /**
  * First balanced `{…}` in a text blob. Models wrap JSON in prose and fences more
  * often than they emit it bare, and a failed parse here costs a whole replay.
  */
 export declare function extractJsonObject(text: string): string | undefined;
+export declare function buildExtractionPrompt(prompt: string, intent: string, schema: ParamsSchema, ctx?: DeriveContext): string;
 /**
  * Derive the scenario's parameters from `prompt`. Never throws: every failure
  * path resolves with the recorded sample values, because a replay with stale

package/dist/replay/derive.js

@@ -10,11 +10,20 @@
  * most sessions never arm. This is ~40 lines of `fetch` and it keeps the package
  * at zero runtime dependencies.
  *
- * NO KEY IS A SUPPORTED CONFIGURATION. Without `ANTHROPIC_API_KEY` the extraction
- * is skipped entirely and every parameter takes the value it had in the recorded
- * run — a plain replay of the recorded parameters, at zero cost. For a scenario
- * whose parameters rarely change that is a complete, free replay; for one that
- * keys off the prompt, it is why you want the key.
+ * NO KEY IS THE ORDINARY CONFIGURATION (segmented.md R-PARAM-5). Without
+ * `ANTHROPIC_API_KEY` the reading is done by the **service**, over one authorized
+ * POST to `/scenarios/:id/derive`, under the key it already uses to calculate
+ * scenarios and to ask its live question. That is the path nearly every session
+ * takes: the people this runs for are inside Claude Code on a subscription and
+ * have no API key to give it.
+ *
+ * A key here is an override, not a requirement. It keeps the reading on this
+ * machine — the prompt never reaches the service — which is what an in-house
+ * deployment wants, and it is one round trip faster.
+ *
+ * NEITHER is still supported and still means the same thing it always did:
+ * settings take their recorded samples and a scenario with a target declines,
+ * because a target is never guessed.
  *
  * The prompt and the parsing tolerances mirror RRepeat's
  * `deriveParametersFromScenarioPayload` exactly, so the two produce the same
@@ -32,6 +41,10 @@ function sampleValues(schema) {
         out[key] = schema[key].sampleValue;
     return out;
 }
+/** A parameter with no kind reads as a target (segmented.md R-PARAM-3). */
+function isTarget(schema, key) {
+    return schema[key]?.kind !== "setting";
+}
 /**
  * First balanced `{…}` in a text blob. Models wrap JSON in prose and fences more
  * often than they emit it bare, and a failed parse here costs a whole replay.
@@ -66,24 +79,40 @@ export function extractJsonObject(text) {
     }
     return undefined;
 }
-function buildExtractionPrompt(prompt, intent, schema) {
+export function buildExtractionPrompt(prompt, intent, schema, ctx = {}) {
+    // Each parameter wears its kind, because the last rule below treats the two
+    // differently and the model cannot tell them apart from the name alone
+    // (segmented.md R-PARAM-2).
     const descriptions = Object.keys(schema)
         .map((key) => {
         const { description, sampleValue } = schema[key];
-        return `- ${key}: ${description} (sample: ${JSON.stringify(sampleValue)})`;
+        const kind = isTarget(schema, key) ? "target" : "setting";
+        return `- ${key} (${kind}): ${description} (sample: ${JSON.stringify(sampleValue)})`;
     })
         .join("\n");
+    // The call the agent was about to make is the most specific thing the turn
+    // says about a target — more specific than the prompt, which may not mention
+    // it at all (R-PARAM-8).
+    const live = ctx.liveCall
+        ? `\nThe agent was about to call ${ctx.liveCall.toolName} with ${ctx.liveCall.toolInput}.\n`
+        : "";
+    const results = (ctx.recentResults ?? []).filter((r) => r.trim().length > 0);
+    const recent = results.length > 0
+        ? `\nRecent tool results from this task, oldest first:\n${results
+            .map((r) => `\`\`\`\n${r}\n\`\`\``)
+            .join("\n")}\n`
+        : "";
     return `You are extracting parameter values from a user prompt to execute a pre-defined scenario.
 
 Scenario intent: ${intent}
-
+${live}
 Parameters needed (with sample values from past runs):
 ${descriptions}
 
 User prompt:
 ${prompt}
-
-Extract the parameter values from the user prompt. If a value is not explicitly mentioned, infer a reasonable default from the sample values above.
+${recent}
+Extract the parameter values. A setting you cannot find takes its sample value. A target you cannot find in the prompt, the reasoning, the call or the results is null — never invent it and never copy the sample.
 
 Respond ONLY with a valid JSON object mapping each parameter name to its value. No markdown fences, no prose.
 Example: { "directory": "src/utils", "pattern": "*.ts" }`;
@@ -98,10 +127,25 @@ export async function deriveParameters(opts) {
     const schema = opts.paramsObject ?? {};
     const keys = Object.keys(schema);
     if (keys.length === 0)
-        return { params: {}, costUsd: 0, derived: false };
+        return { params: {}, costUsd: 0, derived: false, missing: [], sampled: [] };
     const apiKey = opts.apiKey ?? process.env.ANTHROPIC_API_KEY;
+    // No key of our own is the ordinary case: the service reads the turn instead,
+    // under the key it already spends on this account (R-PARAM-5).
+    if (!apiKey && opts.service)
+        return deriveViaService(opts, opts.service, schema, keys);
+    // No key and nowhere to ask — an unauthenticated session, or a deployment that
+    // turned service derivation off. `derived: false` is how the caller tells this
+    // apart from a real extraction: it declines any scenario that has a target and
+    // arms an all-settings one on its recorded values.
     if (!apiKey)
-        return { params: sampleValues(schema), costUsd: 0, derived: false };
+        return {
+            params: sampleValues(schema),
+            costUsd: 0,
+            derived: false,
+            via: "samples",
+            missing: [],
+            sampled: keys,
+        };
     const model = opts.model ?? process.env.BIR_DERIVE_MODEL ?? DEFAULT_DERIVE_MODEL;
     const doFetch = opts.fetchImpl ?? fetch;
     const res = await doFetch(ANTHROPIC_URL, {
@@ -115,7 +159,13 @@ export async function deriveParameters(opts) {
             model,
             max_tokens: 2024,
             messages: [
-                { role: "user", content: buildExtractionPrompt(opts.prompt, opts.intent, schema) },
+                {
+                    role: "user",
+                    content: buildExtractionPrompt(opts.prompt, opts.intent, schema, {
+                        liveCall: opts.liveCall,
+                        recentResults: opts.recentResults,
+                    }),
+                },
             ],
         }),
         signal: opts.signal,
@@ -155,12 +205,119 @@ export async function deriveParameters(opts) {
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
         throw new Error("derive returned a non-object");
     }
-    // A missing or null key falls back to its recorded sample, so a partial
-    // extraction still yields a runnable parameter set.
+    // A setting nobody stated takes its recorded sample — that is what a setting
+    // is. A target nobody stated stays null and is named in `missing`, and the
+    // caller declines the plan (segmented.md R-PARAM-2, R-PARAM-3). Copying the
+    // sample here is exactly the guess the design forbids: it is how a replay
+    // ends up querying last quarter's region because this prompt named no region.
+    const missing = [];
+    const sampled = [];
     for (const key of keys) {
-        if (parsed[key] === null || parsed[key] === undefined)
+        if (parsed[key] !== null && parsed[key] !== undefined)
+            continue;
+        if (isTarget(schema, key)) {
+            parsed[key] = null;
+            missing.push(key);
+        }
+        else {
             parsed[key] = schema[key].sampleValue;
+            sampled.push(key);
+        }
+    }
+    return {
+        params: parsed,
+        costUsd,
+        derived: true,
+        via: "key",
+        model,
+        inputTokens,
+        outputTokens,
+        missing,
+        sampled,
+    };
+}
+/**
+ * Ask the service to read the turn (segmented.md R-PARAM-5).
+ *
+ * One authorized POST. The body carries the turn — the prompt, and whatever else
+ * this turn has said about its target — and never the schema: the service reads
+ * that from the scenario row it owns, so a stale copy here cannot change what is
+ * asked for.
+ *
+ * Never throws, and never worse than no key. A service that is off, out of
+ * budget, too slow or simply down answers `derived: false`, and so does every
+ * failure on this side, which is precisely the keyless behaviour this replaced:
+ * settings stand on their samples, and a target does not run.
+ */
+async function deriveViaService(opts, service, schema, keys) {
+    const samples = (reason) => ({
+        params: sampleValues(schema),
+        costUsd: 0,
+        derived: false,
+        via: "service",
+        reason,
+        missing: [],
+        sampled: keys,
+    });
+    const doFetch = opts.fetchImpl ?? fetch;
+    const url = `${service.baseUrl.replace(/\/+$/, "")}/scenarios/${service.scenarioId}/derive`;
+    let body;
+    try {
+        const res = await doFetch(url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${service.token}`,
+            },
+            body: JSON.stringify({
+                prompt: opts.prompt,
+                liveCall: opts.liveCall,
+                recentResults: opts.recentResults,
+            }),
+            signal: opts.signal,
+        });
+        if (!res.ok)
+            return samples(`service HTTP ${res.status}`);
+        body = (await res.json());
+    }
+    catch (err) {
+        return samples(err instanceof Error ? err.message : String(err));
+    }
+    if (!body || typeof body !== "object")
+        return samples("service sent no answer");
+    if (body.derived !== true)
+        return samples(`service: ${body.reason ?? "declined"}`);
+    // Normalised again on this side, over *our* copy of the schema. The service
+    // answers in the same shape, but the plan runs on these values and the gate
+    // reads this `missing`: an older or newer service must not be able to leave a
+    // target unaccounted for.
+    const params = { ...(body.params ?? {}) };
+    const missing = [];
+    const sampled = [];
+    for (const key of keys) {
+        const value = params[key];
+        if (value !== null && value !== undefined)
+            continue;
+        if (isTarget(schema, key)) {
+            params[key] = null;
+            missing.push(key);
+        }
+        else {
+            params[key] = schema[key].sampleValue;
+            sampled.push(key);
+        }
     }
-    return { params: parsed, costUsd, derived: true, model, inputTokens, outputTokens };
+    return {
+        params,
+        // What the service spent on this turn, reported back on the execution so a
+        // replay's cost stays the whole truth about it (R-MONEY-2). The account is
+        // not billed for it; the service books it on its own ledger as well.
+        costUsd: typeof body.costUsd === "number" ? body.costUsd : 0,
+        derived: true,
+        via: "service",
+        model: body.model,
+        missing,
+        sampled,
+    };
 }
 //# sourceMappingURL=derive.js.map

package/dist/replay/flatten.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Flattening calls into frames (segmented.md 10.6).
+ *
+ * A chain may hold a **call**: one row that says "here the agent does this
+ * sub-task", answered by a recorded scenario the service inlines into the
+ * payload. Running it is not a second plan. It is one plan over one flat list
+ * of steps, in which some steps belong to another scenario and run with *its*
+ * parameters, *its* intent and *its* accumulated values.
+ *
+ * That is what a **frame** is: the scope one stretch of steps runs in. Frame 0
+ * is the caller's own. Entering a called frame evaluates the call's
+ * `paramMapLogic` to build the segment's parameters; leaving it evaluates
+ * `resultMapLogic` and merges the result back into the caller's `respParams`
+ * (R-CALL-29).
+ *
+ * Everything downstream reads the flat list rather than the chain: the gates
+ * judge the steps that will really run (R-CALL-30), recorded outputs come from
+ * the right recording and range (R-CALL-31), and a failure is reported on the
+ * scenario that owns the step (R-CALL-13).
+ *
+ * The flattener itself decides nothing about *which* segment answers a call —
+ * the service did that long before this payload was built. It only lays out
+ * what it was served, and stops in front of anything it cannot run.
+ */
+import type { SerializedScenario, SerializedScenarioStep, CallUnusable } from "./types.js";
+import type { ParamsSchema } from "./types.js";
+/** The scope one stretch of steps runs in. Frame 0 is the caller's own. */
+export interface Frame {
+    id: number;
+    /** 0 for the caller, 1 for a segment it calls, 2 for one that segment calls. */
+    depth: number;
+    scenarioId: string;
+    runId: string;
+    /** The recorded range the frame's outputs come from. Null means the whole run. */
+    stepFrom: number | null;
+    stepTo: number | null;
+    /** The intent the frame's step logic runs with (R-INTENT-12). */
+    intent: string;
+    parent?: Frame;
+    /** The caller's chain `stepIndex` of the call row that opened this frame. */
+    callerStepIndex?: number;
+    callIntent?: string;
+    paramMapLogic?: string;
+    resultMapLogic?: string;
+    segmentId?: string;
+    /** The inlined segment's `chainRevision` as served (R-CALL-13). */
+    chainRevision?: number;
+    /** The segment's own parameters, for the settings a mapping omits (R-CALL-21). */
+    paramsObject?: ParamsSchema | null;
+    /** Filled by the plan when the frame is entered. */
+    parameters?: Record<string, unknown>;
+    respParams: Record<string, unknown>;
+}
+/** One step that will really run, with the frame it runs in. */
+export interface FlatEntry {
+    scenarioId: string;
+    runId: string;
+    stepFrom: number | null;
+    stepTo: number | null;
+    /** The owning scenario's own `scenario_steps.step_index`, not a flat position. */
+    stepIndex: number;
+    /** Always a tool row: a call row becomes a frame, or a stop. */
+    step: SerializedScenarioStep;
+    frame: Frame;
+    depth: number;
+    /** First / last entry of its frame — where the two mapping bodies run. */
+    first: boolean;
+    last: boolean;
+}
+/** Why the flat list stops short, and which call row said so. */
+export interface FlatStop {
+    kind: "unusable";
+    reason: CallUnusable;
+    /** The scenario whose chain holds the call row. */
+    scenarioId: string;
+    /** That call row's own `stepIndex`. */
+    stepIndex: number;
+    segmentId?: string | null;
+    callIntent?: string | null;
+}
+export interface FlatChain {
+    entries: FlatEntry[];
+    /** Flat position the plan stops in front of. Undefined means the whole chain. */
+    stopAt?: number;
+    stopReason?: FlatStop;
+}
+/**
+ * Mirrors the service's `SEGMENT_MAX_DEPTH`. A constant, not a setting: one
+ * call row holds one answer, which is only correct because a call inside a
+ * level-two segment is never answered (R-CALL-12).
+ */
+export declare const MAX_CALL_DEPTH = 2;
+/**
+ * Lay a served chain out as one flat list of steps, with a frame per call.
+ *
+ * Stops at the first call it cannot run. The stop is *clamped* to the start of
+ * the outermost called frame that contains it: a plan must never run half a
+ * sub-task and leave its `resultMapLogic` unevaluated, because the caller's
+ * later steps read what that body returns (R-CALL-30).
+ */
+export declare function flattenChain(scenario: SerializedScenario, opts?: {
+    maxDepth?: number;
+    /** The range a segment armed on its own covers (its own recording). */
+    range?: {
+        stepFrom: number;
+        stepTo: number;
+    } | null;
+}): FlatChain;
+/**
+ * Move a stop back to the start of the outermost called frame it falls in
+ * (R-CALL-30, 10.6 step 3).
+ *
+ * Used for the known-bad-step gate, which judges entries: a parked step in the
+ * middle of a sub-task stops the plan in front of the *sub-task*, not in front
+ * of the step, because stopping inside it would skip the body that hands its
+ * results back.
+ */
+export declare function clampToFrameStart(entries: readonly FlatEntry[], index: number): number;
+/**
+ * One frame per chain, for a payload with no calls in it and for the callers
+ * that build a plan by hand (tests, `bir replay`). Byte for byte the old
+ * behaviour: one frame, one scenario, one range.
+ */
+export declare function flatEntriesOf(scenario: SerializedScenario): FlatEntry[];
+//# sourceMappingURL=flatten.d.ts.map

package/dist/replay/flatten.js

@@ -0,0 +1,182 @@
+/**
+ * Flattening calls into frames (segmented.md 10.6).
+ *
+ * A chain may hold a **call**: one row that says "here the agent does this
+ * sub-task", answered by a recorded scenario the service inlines into the
+ * payload. Running it is not a second plan. It is one plan over one flat list
+ * of steps, in which some steps belong to another scenario and run with *its*
+ * parameters, *its* intent and *its* accumulated values.
+ *
+ * That is what a **frame** is: the scope one stretch of steps runs in. Frame 0
+ * is the caller's own. Entering a called frame evaluates the call's
+ * `paramMapLogic` to build the segment's parameters; leaving it evaluates
+ * `resultMapLogic` and merges the result back into the caller's `respParams`
+ * (R-CALL-29).
+ *
+ * Everything downstream reads the flat list rather than the chain: the gates
+ * judge the steps that will really run (R-CALL-30), recorded outputs come from
+ * the right recording and range (R-CALL-31), and a failure is reported on the
+ * scenario that owns the step (R-CALL-13).
+ *
+ * The flattener itself decides nothing about *which* segment answers a call —
+ * the service did that long before this payload was built. It only lays out
+ * what it was served, and stops in front of anything it cannot run.
+ */
+/**
+ * Mirrors the service's `SEGMENT_MAX_DEPTH`. A constant, not a setting: one
+ * call row holds one answer, which is only correct because a call inside a
+ * level-two segment is never answered (R-CALL-12).
+ */
+export const MAX_CALL_DEPTH = 2;
+/**
+ * Lay a served chain out as one flat list of steps, with a frame per call.
+ *
+ * Stops at the first call it cannot run. The stop is *clamped* to the start of
+ * the outermost called frame that contains it: a plan must never run half a
+ * sub-task and leave its `resultMapLogic` unevaluated, because the caller's
+ * later steps read what that body returns (R-CALL-30).
+ */
+export function flattenChain(scenario, opts = {}) {
+    const maxDepth = opts.maxDepth ?? MAX_CALL_DEPTH;
+    const entries = [];
+    let frameId = 0;
+    let stopAt;
+    let stopReason;
+    const root = {
+        id: frameId++,
+        depth: 0,
+        scenarioId: scenario.id,
+        runId: scenario.runId,
+        stepFrom: opts.range?.stepFrom ?? null,
+        stepTo: opts.range?.stepTo ?? null,
+        intent: scenario.intent ?? "",
+        respParams: {},
+    };
+    /** The entry a frame's steps start at, for the clamp. */
+    const frameStart = new Map();
+    const walk = (steps, frame, stack) => {
+        for (const step of steps) {
+            if (stopAt !== undefined)
+                return;
+            if (step.kind !== "segment") {
+                entries.push({
+                    scenarioId: frame.scenarioId,
+                    runId: frame.runId,
+                    stepFrom: frame.stepFrom,
+                    stepTo: frame.stepTo,
+                    stepIndex: step.stepIndex,
+                    step,
+                    frame,
+                    depth: frame.depth,
+                    first: false,
+                    last: false,
+                });
+                continue;
+            }
+            // A call the service already marked unrunnable, a third level, or a
+            // segment already on this stack (which would be a cycle): all the same
+            // thing to a plan — it stops here and the agent takes over (R-CALL-29).
+            const cycles = !!step.segment && stack.includes(step.segment.id);
+            const tooDeep = frame.depth + 1 > maxDepth;
+            const reason = step.unusable
+                ? step.unusable
+                : !step.segment || cycles || tooDeep
+                    ? "depth"
+                    : undefined;
+            if (reason) {
+                // The clamp: a stop inside a called frame moves back to the first entry
+                // of the outermost called frame containing it, so the caller never runs
+                // part of a sub-task (R-CALL-30).
+                let outermost = frame;
+                while (outermost && outermost.depth > 1)
+                    outermost = outermost.parent;
+                stopAt =
+                    frame.depth > 0 && outermost
+                        ? (frameStart.get(outermost.id) ?? entries.length)
+                        : entries.length;
+                stopReason = {
+                    kind: "unusable",
+                    reason,
+                    scenarioId: frame.scenarioId,
+                    stepIndex: step.stepIndex,
+                    segmentId: step.segmentId ?? step.segment?.id ?? null,
+                    callIntent: step.callIntent ?? null,
+                };
+                return;
+            }
+            const segment = step.segment;
+            const child = {
+                id: frameId++,
+                depth: frame.depth + 1,
+                scenarioId: segment.id,
+                runId: segment.runId,
+                stepFrom: segment.stepFrom,
+                stepTo: segment.stepTo,
+                intent: segment.intent ?? "",
+                parent: frame,
+                callerStepIndex: step.stepIndex,
+                callIntent: step.callIntent ?? undefined,
+                paramMapLogic: step.paramMapLogic ?? undefined,
+                resultMapLogic: step.resultMapLogic ?? undefined,
+                segmentId: segment.id,
+                chainRevision: segment.chainRevision,
+                paramsObject: segment.paramsObject ?? null,
+                respParams: {},
+            };
+            frameStart.set(child.id, entries.length);
+            walk(segment.steps ?? [], child, [...stack, segment.id]);
+        }
+    };
+    frameStart.set(root.id, 0);
+    walk(scenario.steps ?? [], root, [scenario.id]);
+    // `first` / `last` per frame, marked once the whole list is known: they are
+    // where the two mapping bodies run. A frame's entries are not necessarily
+    // contiguous — a call sitting in the middle of a chain interleaves its
+    // callee's entries with its own — so these are the frame's first and last
+    // entries overall, never the edges of a run of them.
+    const firstOf = new Map();
+    const lastOf = new Map();
+    entries.forEach((entry, index) => {
+        if (!firstOf.has(entry.frame.id))
+            firstOf.set(entry.frame.id, index);
+        lastOf.set(entry.frame.id, index);
+    });
+    entries.forEach((entry, index) => {
+        entry.first = firstOf.get(entry.frame.id) === index;
+        entry.last = lastOf.get(entry.frame.id) === index;
+    });
+    return { entries, stopAt, stopReason };
+}
+/**
+ * Move a stop back to the start of the outermost called frame it falls in
+ * (R-CALL-30, 10.6 step 3).
+ *
+ * Used for the known-bad-step gate, which judges entries: a parked step in the
+ * middle of a sub-task stops the plan in front of the *sub-task*, not in front
+ * of the step, because stopping inside it would skip the body that hands its
+ * results back.
+ */
+export function clampToFrameStart(entries, index) {
+    const at = entries[index];
+    if (!at || at.depth === 0)
+        return index;
+    let outermost = at.frame;
+    while (outermost && outermost.depth > 1)
+        outermost = outermost.parent;
+    if (!outermost)
+        return index;
+    for (let i = 0; i < entries.length; i += 1) {
+        if (entries[i].frame.id === outermost.id)
+            return i;
+    }
+    return index;
+}
+/**
+ * One frame per chain, for a payload with no calls in it and for the callers
+ * that build a plan by hand (tests, `bir replay`). Byte for byte the old
+ * behaviour: one frame, one scenario, one range.
+ */
+export function flatEntriesOf(scenario) {
+    return flattenChain(scenario).entries;
+}
+//# sourceMappingURL=flatten.js.map