@basein/runner 0.3.21 → 0.3.23

package/dist/replay/plan.d.ts

@@ -20,7 +20,6 @@
  *      step to know its reach, so it can choose between the proxy, a recorded
  *      output, and skipping.
  */
-import { type FlatEntry } from "./flatten.js";
 import type { ReplayMode } from "./coverage.js";
 import type { HandoverStopReason } from "./handover.js";
 import type { ExecutionStage, FallbackKind, ParamsSchema, SerializedScenario, SerializedScenarioStep } from "./types.js";
@@ -130,16 +129,12 @@ export interface DriveOptions {
 /**
  * Supplies a step's recorded output when its tool cannot run here (§8.1).
  *
- * It takes the *entry*, not the step: a step inside a called segment takes its
- * recorded output from that segment's own recording, within its own range
- * (segmented.md R-CALL-31).
- *
  * `leftOut`, when there, is told of every step a test left out (the service's
  * autocorrect.md AC5): one that was in the recording made its call there, and
  * its output is passed over, so the next step of its tool takes its own.
  */
-export type RecordedOutputFor = ((entry: FlatEntry) => Promise<string | undefined>) & {
-    leftOut?: (entry: FlatEntry) => void;
+export type RecordedOutputFor = ((step: SerializedScenarioStep) => Promise<string | undefined>) & {
+    leftOut?: (step: SerializedScenarioStep) => void;
 };
 /**
  * What one step did, told to the caller as it happens.
@@ -154,12 +149,6 @@ export type RecordedOutputFor = ((entry: FlatEntry) => Promise<string | undefine
  */
 export interface StepInfo {
     step: SerializedScenarioStep;
-    /**
-     * The flat entry this step ran as: which scenario owns it, which frame it
-     * ran in, and where it sits in the flat order (segmented.md R-CALL-13).
-     * Absent only where a caller builds a StepInfo by hand.
-     */
-    entry?: FlatEntry;
     input: Record<string, unknown>;
     /**
      * What the step's output logic was given: the tool's answer, or for
@@ -170,7 +159,7 @@ export interface StepInfo {
     /**
      * `not_taken`: the step's test said this request does not need it, and it
      * was left out on purpose (the service's autocorrect.md AC5). No call, no
-     * output logic; a sub-task's call row left out whole is one such verdict.
+     * output logic.
      */
     outcome: "executed" | "recorded" | "skipped" | "failed" | "not_taken";
     /** Which part of the step broke. Only set for `failed`. */
@@ -220,19 +209,18 @@ export interface ComposeResult {
     /** Where, and why, the run stopped short of its end, when it did. */
     stopped?: PlanStop;
     /**
-     * The flat position the walk ended at. At or past the plan's `stepCount`
-     * when it reached the end of the planned steps — past it when a test left
-     * out a sub-task that reaches beyond a parked step.
+     * The position the walk ended at. At the plan's `stepCount` when it reached
+     * the end of the planned steps.
      */
     endedAt: number;
 }
 /** Where, and why, a run stopped short of the chain's end (fallbk.md). */
 export interface PlanStop {
     kind: FallbackKind;
-    /** The owning scenario's own `stepIndex` of the step it stopped at. */
+    /** The scenario's own `stepIndex` of the step it stopped at. */
     stepIndex: number;
-    /** Its position in the flat list, which is what the caller indexes by. */
-    flatIndex?: number;
+    /** Its position in the chain, which is what the caller indexes by. */
+    position?: number;
     stage?: ExecutionStage;
     error?: string;
     /**
@@ -243,21 +231,14 @@ export interface PlanStop {
     reason?: HandoverStopReason;
     /** For `other_branch`: the test in words — what the steps from here are for (AC5). */
     whenText?: string | null;
-    /**
-     * For `result_map`: the sub-task whose results could not go back to its
-     * caller, after its last step was left out by its test (AC5).
-     */
-    subTask?: string | null;
 }
 /**
- * What a step's test decided at one flat position (the service's
- * autocorrect.md AC5).
+ * What a step's test decided at one position (the service's autocorrect.md
+ * AC5).
  *
  *  - `run`: no test, or its test said yes.
- *  - `skip`: this request does not need it — the step, or the whole sub-task
- *    whose call row's test said no. The walk goes on at `until`. `leave` says
- *    the step left out was the last of an entered sub-task, so the sub-task's
- *    results still go back to its caller.
+ *  - `skip`: this request does not need the step. The walk goes on with the
+ *    next one.
  *  - `stop`: the test said `hand_over` (this request is the other half), or
  *    could not answer. `info` is the step's verdict when there is one to give.
  */
@@ -265,11 +246,9 @@ export type Gate = {
     kind: "run";
 } | {
     kind: "skip";
-    until: number;
     info: StepInfo;
-    entry: FlatEntry;
+    step: SerializedScenarioStep;
     text: string | null;
-    tools: string[];
 } | {
     kind: "stop";
     stop: PlanStop;
@@ -277,21 +256,11 @@ export type Gate = {
 };
 /** A step left out by its test, as the steer note and the bundle name it. */
 export interface LeftOut {
-    /** The owning scenario's own `stepIndex` — the caller's for a sub-task. */
+    /** The scenario's own `stepIndex`. */
     stepIndex: number;
-    /** Its flat position. */
-    flatIndex: number;
-    /**
-     * The flat position after it: past every step of a sub-task left out
-     * whole, `flatIndex + 1` for one step.
-     */
-    until: number;
+    /** Its position in the chain. */
+    position: number;
     toolName: string;
-    /**
-     * Every tool the steps left out call — the sub-task's, for a sub-task left
-     * out whole — so a call the model makes to any of them is known for one.
-     */
-    tools: string[];
     text: string | null;
 }
 export interface PlanOptions {
@@ -306,7 +275,7 @@ export interface PlanOptions {
      * What a *target* takes when the parameters settle without the derivation.
      * `null` (the default) is the rule: a target is never guessed. `samples` is
      * `bir replay`'s own contract — an operator named the scenario by id, so a
-     * recorded sample stands in (R-CALL-37).
+     * recorded sample stands in.
      */
     fallbackTargets?: "null" | "samples";
     mode: ReplayMode;
@@ -318,18 +287,11 @@ export interface PlanOptions {
      */
     stopAt?: number;
     /**
-     * The plan is a sub-task inside the agent's own task (segmented.md R-OUT-13):
-     * it was armed by intent, not by the prompt, so its directive and its bundles
-     * tell the agent to continue its task rather than to stop calling tools.
+     * The plan is a sub-task inside the agent's own task: it was armed mid-task
+     * by intent, not by the prompt, so its directive and its bundles tell the
+     * agent to continue its task rather than to stop calling tools.
      */
     subTask?: boolean;
-    /**
-     * The flattened chain: the steps that will really run, each with the frame it
-     * runs in (segmented.md 10.6). A chain with no calls flattens to one frame
-     * and behaves exactly as it did before calls existed, which is why this is
-     * optional — a caller that does not flatten gets that same single frame.
-     */
-    entries?: FlatEntry[];
 }
 export declare class ScenarioReplayPlan {
     readonly scenarioId: string;
@@ -337,8 +299,8 @@ export declare class ScenarioReplayPlan {
     readonly mode: ReplayMode;
     readonly intent: string;
     private readonly scenario;
-    /** The flat list this plan walks. One entry per step that will really run. */
-    private readonly entries;
+    /** The chain this plan walks. */
+    private readonly steps;
     private paramsPromise;
     /** The values a step worked out in the recording ({@link FROM_STEP_MARK}). */
     private readonly fromStep;
@@ -361,65 +323,11 @@ export declare class ScenarioReplayPlan {
     private readyPromise?;
     /** Exclusive end of the planned steps. Equal to the chain length unless a step is parked. */
     private readonly stopAt;
-    /** This plan is a sub-task inside the agent's own task (segmented.md R-OUT-13). */
+    /** This plan is a sub-task inside the agent's own task: it was armed mid-task by intent. */
     readonly subTask: boolean;
-    /**
-     * Where each called frame begins and ends, its callees' entries included:
-     * where it is entered, its test decided and it is left, and where a
-     * sub-task its test leaves out ends (AC5).
-     */
-    private readonly edges;
-    /** Each entry's flat position. */
-    private readonly positions;
-    /** Every frame of the flat list, by id. */
-    private readonly frames;
-    /** The plan's own walk: what its cursor has entered and decided (AC5). */
+    /** The plan's own walk: what its cursor has decided (AC5). */
     private readonly walk;
     constructor(opts: PlanOptions);
-    private frameById;
-    /** The called frames that begin at flat position `flatIndex`, outermost first. */
-    private framesStartingAt;
-    /** The caller's own frame — the one at depth 0. */
-    private rootFrame;
-    /** The parameters one entry's logic runs with (segmented.md R-CALL-29). */
-    private paramsFor;
-    /** The accumulated values one entry's logic runs with. */
-    private respFor;
-    /**
-     * Entering a called frame: build the segment's parameters from the caller's
-     * state (R-CALL-29).
-     *
-     * The recipe is the dry run's, exactly (9.8 step 10): the mapping's output,
-     * plus the segment's own recorded sample for every *setting* the mapping left
-     * out. A mapping that omits a setting therefore cannot pass the service's
-     * check and then run `undefined` here.
-     */
-    private enterFramesAt;
-    private enterFrame;
-    /**
-     * Leave every called frame that ends at `flatIndex` and that `walk`
-     * entered, innermost first: a sub-task whose chain ends with a call is left
-     * after its callee has handed it its results.
-     */
-    private leaveFramesAt;
-    /**
-     * After a skip that ends at flat position `last`: leave every entered
-     * sub-task that ends there — its results still go back to its caller. A
-     * result mapping that throws ends the walk: its verdict is filed on the
-     * call row, in the caller's chain, and the stop says the step at `last` was
-     * left out, not run (`result_map`). Rethrown instead when `rethrow`.
-     */
-    private leaveAfterSkip;
-    /**
-     * The call row that opened `frame`, as a step of its caller's chain: where
-     * a sub-task's test and its result mapping are filed (R-CALL-13).
-     */
-    private callRowOf;
-    /**
-     * Leaving a called frame: hand what the segment emitted back to its caller
-     * (R-CALL-29). `out` is the frame's own accumulated `respParams`.
-     */
-    private leaveFrame;
     /**
      * Await the derivation, then apply `paramsLogic` — once, however many callers
      * race here. A rejected derivation settles on the fallback values
@@ -461,24 +369,12 @@ export declare class ScenarioReplayPlan {
     get currentStepIndex(): number;
     /** Steps this plan will run — the chain up to the first known-bad step. */
     get stepCount(): number;
-    /** Every step this plan could run, planned or not. */
+    /** Every step in the scenario's chain, planned or not. */
     get totalSteps(): number;
     /** True when the plan ends in front of a known-bad step (fallbk.md D3). */
     stopsEarly(): boolean;
     /** The known-bad step the plan stops in front of, if any. */
     stopStep(): SerializedScenarioStep | undefined;
-    /** The entry the plan stops in front of, with the frame that owns it. */
-    stopEntry(): FlatEntry | undefined;
-    /**
-     * The flat position of the chain's decision stop (the service's
-     * segmentsbreakdown.md SB-18), or -1 when it has none. The steps from there
-     * on are the half the recording took, whatever stops the plan first.
-     */
-    decisionIndex(): number;
-    /** Every entry in order — for the report, and for the owning scenario ids. */
-    allEntries(): readonly FlatEntry[];
-    /** The entry awaiting execution, or undefined when the plan is done. */
-    currentEntry(): FlatEntry | undefined;
     /** The parameters in force. Empty until {@link ready} resolves. */
     get parameters(): Readonly<Record<string, unknown>>;
     /**
@@ -508,7 +404,7 @@ export declare class ScenarioReplayPlan {
     expectedTool(): string | undefined;
     /** True once every planned step has been applied — the plan should be retired. */
     isDone(): boolean;
-    /** Every step in order — for the directive, and for coverage reporting. */
+    /** Every step in order — for the directive, the report and coverage reporting. */
     allSteps(): readonly SerializedScenarioStep[];
     /**
      * True when `toolName` is one of this scenario's own tools.
@@ -536,21 +432,16 @@ export declare class ScenarioReplayPlan {
     private inputOf;
     /** Whether the plan's cursor rests in front of the step it is parked before. */
     atStop(): boolean;
-    /**
-     * The test an entry runs under, in words, when it has one: its own, or that
-     * of a sub-task beginning at it — one whose chain begins with a call begins
-     * at its callee's first step.
-     */
-    onlyWhen(entry: FlatEntry): {
+    /** The test a step runs under, in words, when it has one. */
+    onlyWhen(step: SerializedScenarioStep): {
         text: string | null;
     } | undefined;
     /**
-     * The tool names of the steps from flat position `from` to the end (or to
-     * `until`, not included), each that runs only under a test marked so — for a
-     * hand-over note's "remaining planned steps", which must not read as steps
-     * this request needs.
+     * The tool names of the steps from position `from` to the end, each that
+     * runs only under a test marked so — for a hand-over note's "remaining
+     * planned steps", which must not read as steps this request needs.
      */
-    remainingFrom(from: number, until?: number): string[];
+    remainingFrom(from: number): string[];
     /** The steps the plan's own cursor has left out so far, in order (AC5). */
     leftOut(): readonly LeftOut[];
     /** Whether any planned step runs only under a test. */
@@ -558,22 +449,16 @@ export declare class ScenarioReplayPlan {
     /** One test, answered — or the reason it could not be. Never throws. */
     private answer;
     /**
-     * What the tests decide at flat position `flatIndex` for `walk`. Enters the
-     * position's frame when its own test needs the frame's parameters, and
-     * nothing else changes: the caller moves its cursor.
+     * What the step's test decides at `position` for `walk`. Nothing changes:
+     * the caller moves its cursor.
      */
     private gate;
-    /**
-     * A sub-task's test, decided in its caller's scope at flat position
-     * `flatIndex`, where the sub-task begins. Undefined when it says yes.
-     */
-    private decideCall;
     /** What a skip the gate decided leaves out, as the notes name it. */
     private leftOutOf;
     /**
-     * Tell a recorded-output source of the steps one skip left out — every step
-     * of a sub-task left out whole — so its queues pass over the outputs of the
-     * ones that were in the recording ({@link RecordedOutputFor}).
+     * Tell a recorded-output source of a step a test left out, so its queues
+     * pass over that step's output when it was in the recording
+     * ({@link RecordedOutputFor}).
      */
     private passOver;
     /**
@@ -581,12 +466,8 @@ export declare class ScenarioReplayPlan {
      * deciding each test as its step comes due (AC5). Stops at a step that will
      * run, at the end, or at a test that stops the plan — which it returns, with
      * the steps it left out. The observer is told each verdict as it is made.
-     * A sub-task whose results cannot go back after its last step was left out
-     * stops the plan too (`result_map`), its verdict filed on the call row.
      */
-    settleTests(onStep?: StepObserver, opts?: {
-        rethrow?: boolean;
-    }): {
+    settleTests(onStep?: StepObserver): {
         stop?: PlanStop;
         left: LeftOut[];
     };
@@ -605,12 +486,11 @@ export declare class ScenarioReplayPlan {
      * The arguments each planned step will run with, where they are known before
      * any step runs — for the steer directive (see {@link steeringDirective}).
      *
-     * Known means: the parameters are settled, the step is the caller's own
-     * (a called segment's parameters are only built when it is entered), and
-     * its input logic neither reads nor passes on anything an earlier step
-     * accumulates — or it is the step at the cursor, whose accumulation is
-     * already final. Everything else is undefined, and the directive leaves
-     * those steps' arguments to the system.
+     * Known means: the parameters are settled, and the step's input logic
+     * neither reads nor passes on anything an earlier step accumulates — or it
+     * is the step at the cursor, whose accumulation is already final.
+     * Everything else is undefined, and the directive leaves those steps'
+     * arguments to the system.
      *
      * A look-ahead only: every body runs on copies, under a short limit, and a
      * body that throws or runs long just leaves its step without arguments —