@basein/runner 0.2.11 → 0.3.0

package/dist/replay/safety.d.ts

@@ -0,0 +1,72 @@
+/**
+ * safety — values a plan must not template, unattended, into a command.
+ *
+ * A plan's parameters are read from the turn, and the turn includes the last
+ * few tool results (segmented.md R-PARAM-2): a web page the agent fetched, an
+ * email, a file it read. Those values then flow through LLM-written
+ * `toolInputLogic` — typically plain concatenation, `"… WHERE region = '" +
+ * parameters.region + "'"` — into calls that nobody approves one by one: a
+ * steered step is answered `allow`, and a direct step runs through the proxy
+ * with no prompt at all. A page that says `EMEA'; DROP TABLE orders; --` or
+ * `x; curl … | sh` in the right place would be executed on the user's database
+ * or shell by the replay, not by anything the user asked for.
+ *
+ * The runner cannot know how a body quotes. It can refuse to guess: when a plan
+ * has a step whose input is a command — a shell, an editor that writes files,
+ * an MCP tool named for SQL or execution — every value derived for *this* turn
+ * must be plain text, free of the characters that end a quoted string or start
+ * a new command. A value equal to its recorded sample is the user's own and
+ * passes. Anything else stops the plan, and the agent does the task itself, in
+ * the open, where the user's own permission rules apply. A false positive
+ * costs one replay; a false negative runs someone else's command.
+ *
+ * Quoting is not the only way in. A body that templates a value *unquoted* —
+ * `"… WHERE user_id = " + parameters.userId`, `"find . -name " +
+ * parameters.pattern`, `"ssh " + parameters.host` — is broken open by plain
+ * text: `1 OR 1=1`, `x -exec rm -rf {} +`, `-oProxyCommand=…`. So a value for a
+ * command also keeps the *shape* of its recorded sample: a number stays a
+ * number and a boolean a boolean; nothing starts with `-` (an option, not a
+ * value); and whitespace, a glob, a brace or a parenthesis the sample did not
+ * have is not let in. Where the sample itself had spaces — a name like `EMEA
+ * West`, which the recorded body must have quoted to work at all — the value
+ * may too, but not together with boolean SQL (`OR`/`AND`/`UNION`), a `+`, or a
+ * word that starts with `-`.
+ *
+ * A plan whose only sink is a file edit is held to less: no line break, no
+ * NUL. A file is not a shell, and a quote or a backslash — every Windows path —
+ * is text there.
+ */
+import type { FlatEntry } from "./flatten.js";
+import type { ParamsSchema } from "./types.js";
+/**
+ * How a step consumes its input, strictest first: `command` is run by a shell
+ * or a database, `write` is only written into a file.
+ */
+export type SinkKind = "command" | "write";
+/** Whether this tool's input is run by a shell. */
+export declare function isShellTool(toolName: string | null | undefined): boolean;
+/** How this tool consumes its input, or undefined when it is neither run nor written. */
+export declare function sinkOf(toolName: string | null | undefined): SinkKind | undefined;
+/** Whether this tool's input is run or written: a shell, a file edit, a query. */
+export declare function isCommandSink(toolName: string | null | undefined): boolean;
+/** The strictest sink among the planned steps, or undefined when there is none. */
+export declare function sinkOfPlan(entries: readonly FlatEntry[]): SinkKind | undefined;
+/** Whether any planned step runs its input through a shell. */
+export declare function hasShellStep(entries: readonly FlatEntry[]): boolean;
+/** Whether any planned step's input is run or written. */
+export declare function hasCommandSink(entries: readonly FlatEntry[]): boolean;
+/**
+ * The first value derived for this turn that is not safe to template into a
+ * command, or undefined when every one is.
+ *
+ * `derived` is the derivation's own answer, *before* `paramsLogic`: the
+ * scenario's logic may well build a quoted SQL string on purpose, and that is
+ * the recorded chain's doing, not the turn's.
+ */
+export declare function unsafeParameter(derived: Readonly<Record<string, unknown>>, schema: ParamsSchema | null | undefined, 
+/** The plan's strictest sink ({@link sinkOfPlan}); `command` when omitted. */
+sink?: SinkKind): {
+    key: string;
+    value: string;
+} | undefined;
+//# sourceMappingURL=safety.d.ts.map

package/dist/replay/safety.js

@@ -0,0 +1,303 @@
+/**
+ * safety — values a plan must not template, unattended, into a command.
+ *
+ * A plan's parameters are read from the turn, and the turn includes the last
+ * few tool results (segmented.md R-PARAM-2): a web page the agent fetched, an
+ * email, a file it read. Those values then flow through LLM-written
+ * `toolInputLogic` — typically plain concatenation, `"… WHERE region = '" +
+ * parameters.region + "'"` — into calls that nobody approves one by one: a
+ * steered step is answered `allow`, and a direct step runs through the proxy
+ * with no prompt at all. A page that says `EMEA'; DROP TABLE orders; --` or
+ * `x; curl … | sh` in the right place would be executed on the user's database
+ * or shell by the replay, not by anything the user asked for.
+ *
+ * The runner cannot know how a body quotes. It can refuse to guess: when a plan
+ * has a step whose input is a command — a shell, an editor that writes files,
+ * an MCP tool named for SQL or execution — every value derived for *this* turn
+ * must be plain text, free of the characters that end a quoted string or start
+ * a new command. A value equal to its recorded sample is the user's own and
+ * passes. Anything else stops the plan, and the agent does the task itself, in
+ * the open, where the user's own permission rules apply. A false positive
+ * costs one replay; a false negative runs someone else's command.
+ *
+ * Quoting is not the only way in. A body that templates a value *unquoted* —
+ * `"… WHERE user_id = " + parameters.userId`, `"find . -name " +
+ * parameters.pattern`, `"ssh " + parameters.host` — is broken open by plain
+ * text: `1 OR 1=1`, `x -exec rm -rf {} +`, `-oProxyCommand=…`. So a value for a
+ * command also keeps the *shape* of its recorded sample: a number stays a
+ * number and a boolean a boolean; nothing starts with `-` (an option, not a
+ * value); and whitespace, a glob, a brace or a parenthesis the sample did not
+ * have is not let in. Where the sample itself had spaces — a name like `EMEA
+ * West`, which the recorded body must have quoted to work at all — the value
+ * may too, but not together with boolean SQL (`OR`/`AND`/`UNION`), a `+`, or a
+ * word that starts with `-`.
+ *
+ * A plan whose only sink is a file edit is held to less: no line break, no
+ * NUL. A file is not a shell, and a quote or a backslash — every Windows path —
+ * is text there.
+ */
+import { parseQualifiedName } from "../control/correlation.js";
+/** Built-ins whose input is run by a shell. */
+const SHELL_BUILTINS = new Set(["Bash", "PowerShell"]);
+/** Built-ins whose input is written into a file. */
+const WRITE_BUILTINS = new Set(["Edit", "MultiEdit", "Write", "NotebookEdit"]);
+/**
+ * An MCP tool whose name says its input is run: a shell, a query, a script.
+ * Matched against the name split into words ({@link nameWords}), so
+ * `run_command`, `run-command` and `runCommand` are the same tool — and against
+ * the server's name as well as the tool's, because `mcp__shell__run` says it
+ * with the server.
+ */
+const MCP_SHELL_WORD = /(?:^|[_.-])(?:shell|bash|sh|zsh|ssh|exec|execute|command|cmd|terminal|powershell|pwsh)(?:$|[_.-])/i;
+const MCP_COMMAND_WORD = /(?:^|[_.-])(?:sql|tsql|query|exec|execute|shell|bash|sh|zsh|ssh|command|cmd|script|eval|terminal|psql|mysql|mssql|sqlite|duckdb|postgres|postgresql|powershell|pwsh)(?:$|[_.-])/i;
+/**
+ * A tool or server name as delimited words: camelCase, PascalCase and acronym
+ * runs are split with `_`, so `executeSql` reads as `execute_Sql`, `runSQL` as
+ * `run_SQL` and `SQLQuery` as `SQL_Query`. Without this every camelCase server —
+ * a common naming convention — slipped past the guard.
+ */
+function nameWords(name) {
+    return name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2");
+}
+/** Whether an MCP tool's own name, or its server's, matches `words`. */
+function mcpNameSays(toolName, words) {
+    const mcp = parseQualifiedName(toolName);
+    if (!mcp)
+        return false;
+    return words.test(nameWords(mcp.toolName)) || words.test(nameWords(mcp.serverName));
+}
+/**
+ * Characters and sequences that end a quoted string or begin another command
+ * in a POSIX shell, PowerShell or SQL. Deliberately wide: an apostrophe in a
+ * name is legitimate text and still stops the plan, because the runner cannot
+ * see whether the body quotes it.
+ */
+const UNSAFE = /[`$;&|<>\\"'\r\n\u0000]|--|\/\*/;
+/**
+ * What a value written into a file must not carry: a line break or a NUL,
+ * which is how a value meant for one line or one path becomes another.
+ *
+ * Deliberately narrower than {@link UNSAFE}. A file is not parsed by a shell,
+ * so a quote or a backslash is text there — every Windows path has one — and
+ * checking for them caught none of the actual risk (hostile file *content*)
+ * while handing over every replay that edits `C:\Users\…` or a name with an
+ * apostrophe, at the cost of a denied call and a model round trip each time.
+ */
+const WRITE_UNSAFE = /[\r\n\u0000]/;
+/** Whether this tool's input is run by a shell. */
+export function isShellTool(toolName) {
+    const name = toolName ?? "";
+    if (SHELL_BUILTINS.has(name))
+        return true;
+    return mcpNameSays(name, MCP_SHELL_WORD);
+}
+/** How this tool consumes its input, or undefined when it is neither run nor written. */
+export function sinkOf(toolName) {
+    const name = toolName ?? "";
+    if (SHELL_BUILTINS.has(name))
+        return "command";
+    if (WRITE_BUILTINS.has(name))
+        return "write";
+    return mcpNameSays(name, MCP_COMMAND_WORD) ? "command" : undefined;
+}
+/** Whether this tool's input is run or written: a shell, a file edit, a query. */
+export function isCommandSink(toolName) {
+    return sinkOf(toolName) !== undefined;
+}
+/** The strictest sink among the planned steps, or undefined when there is none. */
+export function sinkOfPlan(entries) {
+    let found;
+    for (const e of entries) {
+        const sink = sinkOf(e.step.toolName);
+        if (sink === "command")
+            return sink;
+        found ??= sink;
+    }
+    return found;
+}
+/** Whether any planned step runs its input through a shell. */
+export function hasShellStep(entries) {
+    return entries.some((e) => isShellTool(e.step.toolName));
+}
+/** Whether any planned step's input is run or written. */
+export function hasCommandSink(entries) {
+    return entries.some((e) => isCommandSink(e.step.toolName));
+}
+/**
+ * The first value derived for this turn that is not safe to template into a
+ * command, or undefined when every one is.
+ *
+ * `derived` is the derivation's own answer, *before* `paramsLogic`: the
+ * scenario's logic may well build a quoted SQL string on purpose, and that is
+ * the recorded chain's doing, not the turn's.
+ */
+export function unsafeParameter(derived, schema, 
+/** The plan's strictest sink ({@link sinkOfPlan}); `command` when omitted. */
+sink = "command") {
+    const unsafe = sink === "write" ? WRITE_UNSAFE : UNSAFE;
+    for (const [key, value] of Object.entries(derived)) {
+        if (value === null || value === undefined)
+            continue;
+        const sample = schema?.[key]?.sampleValue;
+        // The recorded sample is the user's own value from their own run.
+        if (sameValue(value, sample))
+            continue;
+        const bad = firstUnsafeString(value, 0, unsafe);
+        if (bad !== undefined)
+            return { key, value: bad };
+        // A file is not parsed, so only a command is held to its sample's shape.
+        if (sink === "command") {
+            const off = offShape(value, sample);
+            if (off !== undefined)
+                return { key, value: off };
+        }
+    }
+    return undefined;
+}
+/** A number as text: what a numeric sample's value may be when it arrives as a string. */
+const NUMERIC = /^-?\d+(?:\.\d+)?$/;
+/** Boolean text, for a boolean sample's value that arrives as a string. */
+const BOOLEAN_TEXT = /^(?:true|false)$/i;
+/**
+ * Characters that change what an *unquoted* value is to a shell or a
+ * database — a word break, a glob, a brace expansion (`{-rf,/}` is two
+ * arguments), a sub-expression. Let in only when the sample had them.
+ */
+const SHAPE_CHARS = ["\\s", "*", "?", "[", "]", "{", "}", "(", ")"];
+const SHAPE_TESTS = SHAPE_CHARS.map((char) => ({
+    char,
+    re: char === "\\s" ? /\s/ : new RegExp(`\\${char}`),
+}));
+/** Boolean SQL: what turns `WHERE id = <value>` into every row. */
+const SQL_BOOLEAN_WORD = /\b(?:or|and|union)\b/gi;
+/**
+ * Where a value derived for a `command` sink leaves its recorded sample's
+ * shape (see the file comment), as the text to report; undefined when it
+ * keeps it.
+ */
+function offShape(value, sample) {
+    // A number stays a number: `1 OR 1=1` is not a user id.
+    if (typeof sample === "number") {
+        if (typeof value === "number")
+            return Number.isFinite(value) ? undefined : String(value);
+        if (typeof value !== "string" || !NUMERIC.test(value))
+            return display(value);
+        return undefined;
+    }
+    if (typeof sample === "boolean") {
+        if (typeof value === "boolean")
+            return undefined;
+        if (typeof value === "string" && BOOLEAN_TEXT.test(value))
+            return undefined;
+        return display(value);
+    }
+    const shape = sampleText(sample);
+    return firstOffShapeString(value, 0, shape);
+}
+/** Every string a sample holds — values and keys — for its shape. */
+function sampleText(sample) {
+    const out = [];
+    const walk = (v, depth) => {
+        if (typeof v === "string")
+            out.push(v);
+        else if (typeof v === "number" || typeof v === "boolean")
+            out.push(String(v));
+        else if (v && typeof v === "object" && depth <= 8) {
+            if (!Array.isArray(v))
+                out.push(...Object.keys(v));
+            for (const item of Array.isArray(v) ? v : Object.values(v)) {
+                walk(item, depth + 1);
+            }
+        }
+    };
+    walk(sample, 0);
+    // NUL never matches `\s`, and is a word boundary: joined, the parts neither
+    // gain whitespace nor merge into a word.
+    return out.join("\u0000");
+}
+function firstOffShapeString(value, depth, shape) {
+    if (typeof value === "string")
+        return offShapeText(value, shape) ? value : undefined;
+    if (depth > 8 || value === null || typeof value !== "object")
+        return undefined;
+    const items = Array.isArray(value) ? value : Object.values(value);
+    for (const item of items) {
+        const bad = firstOffShapeString(item, depth + 1, shape);
+        if (bad !== undefined)
+            return bad;
+    }
+    if (!Array.isArray(value)) {
+        for (const k of Object.keys(value)) {
+            if (offShapeText(k, shape))
+                return k;
+        }
+    }
+    return undefined;
+}
+/** Whether one string breaks the sample's shape (see the file comment). */
+function offShapeText(text, shape) {
+    // An option, not a value: `-oProxyCommand=…`, `--upload-pack=…`, `-exec`.
+    if (text.trimStart().startsWith("-"))
+        return true;
+    for (const { re } of SHAPE_TESTS) {
+        if (re.test(text) && !re.test(shape))
+            return true;
+    }
+    if (/\s/.test(text)) {
+        // Words the sample had spaces for — but not a new option among them,
+        if (/(?:^|\s)-/.test(text))
+            return true;
+        // a `+` (`-exec … {} +`),
+        if (text.includes("+") && !shape.includes("+"))
+            return true;
+        // or boolean SQL the sample did not say itself.
+        const had = new Set((shape.match(SQL_BOOLEAN_WORD) ?? []).map((w) => w.toLowerCase()));
+        for (const word of text.match(SQL_BOOLEAN_WORD) ?? []) {
+            if (!had.has(word.toLowerCase()))
+                return true;
+        }
+    }
+    return false;
+}
+/** A value as text for the audit line. */
+function display(value) {
+    if (typeof value === "string")
+        return value;
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function firstUnsafeString(value, depth, unsafe) {
+    if (typeof value === "string")
+        return unsafe.test(value) ? value : undefined;
+    if (depth > 8 || value === null || typeof value !== "object")
+        return undefined;
+    const items = Array.isArray(value) ? value : Object.values(value);
+    for (const item of items) {
+        const bad = firstUnsafeString(item, depth + 1, unsafe);
+        if (bad !== undefined)
+            return bad;
+    }
+    // A key is text too, and an object's keys reach a body just as its values do.
+    if (!Array.isArray(value)) {
+        for (const k of Object.keys(value)) {
+            if (unsafe.test(k))
+                return k;
+        }
+    }
+    return undefined;
+}
+function sameValue(a, b) {
+    if (a === b)
+        return true;
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=safety.js.map

package/dist/replay/source-run.d.ts

@@ -27,6 +27,16 @@
  * (segmented.md R-CALL-31). So the rows are cached per run id, and the cursors
  * are kept per frame — a segment called twice in one chain replays from the
  * start of its range both times, as two separate replays of it would.
+ *
+ * OFF BY DEFAULT NOW. A recorded output shown to the model as a step's result
+ * is last week's answer standing in for a call that did not happen here — and
+ * for a write ("INSERT 0 1", "file updated") that is a lie the model repeats to
+ * the user. A plan therefore stops at a step that cannot run and hands the rest
+ * over (plan.ts). `BIR_REPLAY_RECORDED_OUTPUTS=1` brings the stand-in back for
+ * steps that could not be *sent* at all — a built-in, a server with no proxy
+ * here — never for one that was sent and failed or did not answer; `bir replay`
+ * keeps it on, because its operator reads a per-step trace. Nothing else asks
+ * for these rows.
  */
 import type { FlatEntry } from "./flatten.js";
 export interface SourceRunOptions {

package/dist/replay/source-run.js

@@ -27,8 +27,19 @@
  * (segmented.md R-CALL-31). So the rows are cached per run id, and the cursors
  * are kept per frame — a segment called twice in one chain replays from the
  * start of its range both times, as two separate replays of it would.
+ *
+ * OFF BY DEFAULT NOW. A recorded output shown to the model as a step's result
+ * is last week's answer standing in for a call that did not happen here — and
+ * for a write ("INSERT 0 1", "file updated") that is a lie the model repeats to
+ * the user. A plan therefore stops at a step that cannot run and hands the rest
+ * over (plan.ts). `BIR_REPLAY_RECORDED_OUTPUTS=1` brings the stand-in back for
+ * steps that could not be *sent* at all — a built-in, a server with no proxy
+ * here — never for one that was sent and failed or did not answer; `bir replay`
+ * keeps it on, because its operator reads a per-step trace. Nothing else asks
+ * for these rows.
  */
 import { logDetail, logLine, errText } from "../util/log.js";
+import { isUnhealthyStatus, serviceHealth, serviceTimeoutMs, timeoutSignal, } from "../util/service-health.js";
 export class SourceRunCache {
     opts;
     /** run id → every recorded output of that run, in order. */
@@ -82,47 +93,71 @@ export class SourceRunCache {
         return pending;
     }
     async fetchRun(runId) {
+        // Waited on inside a step of a replay the user is watching, so it obeys the
+        // same breaker as every other service wait (util/service-health.ts): while
+        // the service is cooling down this is not attempted at all, and the step
+        // simply has no recorded output — for this plan, like any failed fetch.
+        if (!serviceHealth.canWait())
+            throw new Error("the service is not answering right now");
+        // The token is read here, at use, never kept: the recorder refreshes it as
+        // a session outlives it, and a copy taken at arming goes stale.
+        const token = this.opts.token();
+        if (!token)
+            throw new Error("not signed in");
         const doFetch = this.opts.fetchImpl ?? fetch;
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), this.opts.timeoutMs ?? 10_000);
-        timer.unref?.();
+        const startedAt = Date.now();
+        let res;
         try {
-            const res = await doFetch(`${this.opts.baseUrl.replace(/\/+$/, "")}/recordings/runs/${runId}`, {
-                headers: { authorization: `Bearer ${this.opts.token()}` },
-                signal: controller.signal,
+            res = await doFetch(`${this.opts.baseUrl.replace(/\/+$/, "")}/recordings/runs/${runId}`, {
+                headers: { authorization: `Bearer ${token}` },
+                signal: timeoutSignal(this.opts.timeoutMs ?? serviceTimeoutMs()),
             });
-            if (!res.ok)
-                throw new Error(`HTTP ${res.status}`);
-            const body = (await res.json());
-            const outputs = [];
-            // A `tool_response` belongs to the `tool_selected` before it, and it is
-            // *that* row's position the range is cut on: a response row may sit just
-            // outside a range whose call sits inside it.
-            const lastCall = new Map();
-            for (const row of body.steps ?? []) {
-                if (!row.tool_name)
-                    continue;
-                if (row.type === "tool_selected") {
-                    lastCall.set(row.tool_name, row.step_index ?? -1);
-                    continue;
-                }
-                if (row.type !== "tool_response")
-                    continue;
-                outputs.push({
-                    toolName: row.tool_name,
-                    output: row.tool_output ?? "{}",
-                    position: lastCall.get(row.tool_name) ?? row.step_index ?? -1,
-                });
+        }
+        catch (err) {
+            serviceHealth.fail(`source run: ${errText(err)}`);
+            throw err;
+        }
+        if (!res.ok) {
+            if (isUnhealthyStatus(res.status))
+                serviceHealth.fail(`source run: HTTP ${res.status}`);
+            else
+                serviceOk(startedAt);
+            throw new Error(`HTTP ${res.status}`);
+        }
+        let body;
+        try {
+            body = (await res.json());
+        }
+        catch (err) {
+            serviceHealth.fail("source run: the answer was not JSON");
+            throw err;
+        }
+        serviceOk(startedAt);
+        const outputs = [];
+        // A `tool_response` belongs to the `tool_selected` before it, and it is
+        // *that* row's position the range is cut on: a response row may sit just
+        // outside a range whose call sits inside it.
+        const lastCall = new Map();
+        for (const row of body.steps ?? []) {
+            if (!row.tool_name)
+                continue;
+            if (row.type === "tool_selected") {
+                lastCall.set(row.tool_name, row.step_index ?? -1);
+                continue;
             }
-            this.runs.set(runId, outputs);
-            logDetail("replay.source_run_loaded", {
-                run: runId,
-                outputs: outputs.length,
+            if (row.type !== "tool_response")
+                continue;
+            outputs.push({
+                toolName: row.tool_name,
+                output: row.tool_output ?? "{}",
+                position: lastCall.get(row.tool_name) ?? row.step_index ?? -1,
             });
         }
-        finally {
-            clearTimeout(timer);
-        }
+        this.runs.set(runId, outputs);
+        logDetail("replay.source_run_loaded", {
+            run: runId,
+            outputs: outputs.length,
+        });
     }
 }
 /**
@@ -130,4 +165,14 @@ export class SourceRunCache {
  * recording. Kept so nothing outside has to change its import.
  */
 export { SourceRunCache as SourceRunOutputs };
+/**
+ * Report a service answer to the breaker with the time its request started:
+ * an answer to a request sent before a hot path gave up on the service does
+ * not end the cool-down that give-up began (util/service-health.ts). A
+ * breaker that takes no start time reads it as a plain `ok()`.
+ */
+function serviceOk(startedAt) {
+    const ok = serviceHealth.ok.bind(serviceHealth);
+    ok(startedAt);
+}
 //# sourceMappingURL=source-run.js.map

package/dist/replay/targets.d.ts

@@ -38,6 +38,17 @@
  * Only frame 0 is judged here. A called segment runs on the parameters its
  * call's `paramMapLogic` builds, not on these, so that body is scanned as a
  * consumer and the segment's own steps are not (R-CALL-29).
+ *
+ * WHEN IN DOUBT, IT BLOCKS. This reads source text, not a parse tree, so it can
+ * only prove "safe" for the shapes it recognises: `parameters.key`,
+ * `parameters?.key` and `parameters["key"]`. Any other use of `parameters` —
+ * destructured (`const { region } = parameters`), passed whole
+ * (`Object.entries(parameters)`), aliased (`const p = parameters`), read with a
+ * computed key — could reach any target, so every missing target blocks. A
+ * false "blocks" costs one replay; a false "safe" runs a query on `null` and
+ * tells the user there are no orders. `paramsLogic` is judged the same way and
+ * more strictly still, because it runs before any step and can rename a target
+ * the steps then read under another name.
  */
 import type { FlatEntry } from "./flatten.js";
 import type { ParamsSchema } from "./types.js";
@@ -47,6 +58,9 @@ import type { ParamsSchema } from "./types.js";
  * Empty means every target the turn left unnamed is one the chain finds for
  * itself. `missing` is returned unchanged whenever the schema or the plan is
  * missing, so a caller that knows less than this one is never made to guess.
+ *
+ * `paramsLogic` is the scenario's own, when it has one: it runs on these
+ * parameters before step 0, and what it returns is what every step reads.
  */
-export declare function blockingTargets(missing: readonly string[], schema: ParamsSchema | null | undefined, planned: readonly FlatEntry[]): string[];
+export declare function blockingTargets(missing: readonly string[], schema: ParamsSchema | null | undefined, planned: readonly FlatEntry[], paramsLogic?: string | null): string[];
 //# sourceMappingURL=targets.d.ts.map

package/dist/replay/targets.js

@@ -38,6 +38,17 @@
  * Only frame 0 is judged here. A called segment runs on the parameters its
  * call's `paramMapLogic` builds, not on these, so that body is scanned as a
  * consumer and the segment's own steps are not (R-CALL-29).
+ *
+ * WHEN IN DOUBT, IT BLOCKS. This reads source text, not a parse tree, so it can
+ * only prove "safe" for the shapes it recognises: `parameters.key`,
+ * `parameters?.key` and `parameters["key"]`. Any other use of `parameters` —
+ * destructured (`const { region } = parameters`), passed whole
+ * (`Object.entries(parameters)`), aliased (`const p = parameters`), read with a
+ * computed key — could reach any target, so every missing target blocks. A
+ * false "blocks" costs one replay; a false "safe" runs a query on `null` and
+ * tells the user there are no orders. `paramsLogic` is judged the same way and
+ * more strictly still, because it runs before any step and can rename a target
+ * the steps then read under another name.
  */
 /**
  * The subset of `missing` this plan must decline on.
@@ -45,8 +56,11 @@
  * Empty means every target the turn left unnamed is one the chain finds for
  * itself. `missing` is returned unchanged whenever the schema or the plan is
  * missing, so a caller that knows less than this one is never made to guess.
+ *
+ * `paramsLogic` is the scenario's own, when it has one: it runs on these
+ * parameters before step 0, and what it returns is what every step reads.
  */
-export function blockingTargets(missing, schema, planned) {
+export function blockingTargets(missing, schema, planned, paramsLogic) {
     if (missing.length === 0)
         return [];
     if (!schema || planned.length === 0)
@@ -56,7 +70,48 @@ export function blockingTargets(missing, schema, planned) {
     // anything, but it is also not a shape worth reasoning about — keep it strict.
     if (bodies.length === 0)
         return [...missing];
-    return missing.filter((key) => bodies.some((body) => readsOutright(body, key) || carriesLiteral(body, schema[key]?.sampleValue)));
+    // A body that uses `parameters` in a shape this file cannot follow may read
+    // any of them.
+    if (bodies.some(readsWhole))
+        return [...missing];
+    // `paramsLogic` passes a missing target on under whatever name it likes
+    // (`return { r: parameters.region }`), and the steps then read `parameters.r`
+    // — which no scan of the steps connects to `region`. So there, any mention
+    // of a missing target is a read, `??` or not: a fallback in paramsLogic is a
+    // default someone typed, which is exactly a guessed target.
+    const logic = paramsLogic?.trim() ? paramsLogic : undefined;
+    if (logic && readsWhole(withoutSpread(logic)))
+        return [...missing];
+    return missing.filter((key) => (logic !== undefined &&
+        (mentions(logic, key) || carriesLiteral(logic, schema[key]?.sampleValue))) ||
+        bodies.some((body) => readsOutright(body, key) || carriesLiteral(body, schema[key]?.sampleValue)));
+}
+/**
+ * `parameters` used in any shape other than `parameters.key`,
+ * `parameters?.key`, `parameters["key"]` or `parameters?.["key"]` — spread,
+ * destructured, passed or aliased.
+ *
+ * A member access *of something else* (`respParams.parameters`,
+ * `x?.parameters`) is not the argument and does not count; a spread
+ * (`...parameters`) is and does. A mention inside a string or a comment counts
+ * too — this reads text — and that errs in the safe direction.
+ */
+function readsWhole(body) {
+    return BARE_PARAMETERS.test(body);
+}
+const BARE_PARAMETERS = /(?<![\w$])(?<!(?<!\.)\.)parameters\b(?!\s*(?:\?\.\s*[A-Za-z_$]|\?\.\s*\[\s*["'`]|\.\s*[A-Za-z_$]|\[\s*["'`]))/;
+/**
+ * `paramsLogic` with its spreads of `parameters` removed. `{ ...parameters,
+ * extra: … }` hands every key on unchanged, which the step scan then judges;
+ * what the rest of the body does with `parameters` is still read.
+ */
+function withoutSpread(body) {
+    return body.replace(/\.\.\.\s*parameters\b(?!\s*(?:\?\.|\.|\[))/g, "{}");
+}
+/** Whether `body` refers to `parameters.<key>` in any recognised form, fallback or not. */
+function mentions(body, key) {
+    const pattern = referencePattern(key);
+    return pattern.test(body);
 }
 /**
  * Every logic body that runs with the caller's own `parameters`.
@@ -87,10 +142,13 @@ function callerBodies(planned) {
     }
     return bodies;
 }
-/** `parameters.key`, `parameters["key"]`, `parameters['key']` — all three forms. */
+/**
+ * `parameters.key`, `parameters["key"]`, `parameters['key']`, and each of them
+ * through optional chaining (`parameters?.key`, `parameters?.["key"]`).
+ */
 function referencePattern(key) {
     const k = escapeRegExp(key);
-    return new RegExp(`parameters\\s*(?:\\.\\s*${k}\\b|\\[\\s*["']${k}["']\\s*\\])`, "g");
+    return new RegExp(`parameters\\s*(?:\\?\\.\\s*${k}\\b|\\.\\s*${k}\\b|(?:\\?\\.)?\\s*\\[\\s*["'\`]${k}["'\`]\\s*\\])`, "g");
 }
 /**
  * Whether `body` reads `key` other than as a fallback.