@agentswf/engine 0.1.0-beta.4 → 0.1.0

package/src/run-commands.ts

@@ -1,98 +1,34 @@
+// What the commands that read runs say of one: its state, span and cost, and the commands that go
+// on from it.
 import { resolve } from "node:path";
-import type { AttemptRecord, RunLogLine } from "@agentswf/contract/records";
-import { maskCredentials } from "@agentswf/harness";
-import { continueCommand, shellWord } from "./attempt-view";
+import type { RunLogLine } from "@agentswf/contract/records";
+import { runEstimate, unknownOps } from "./accounting/spent";
+import { continueCommand } from "./attempt-view";
+import { command, type Out, placeFlags, type ReadPlace, shellLine } from "./command-line";
+import { NO_JSON, readFailureCode, refusalLine } from "./refusals";
 import type { RunCommand } from "./run-command";
 import { type Cursor, encodeCursor } from "./run-read";
 import { RunNotFound, type RunStatus } from "./run-state";
+import { clockTime } from "./run-text";
 import { runRootOf } from "./runs";
+import { readSpent } from "./spend";
 
-/** What `awf runs` and `awf logs` share: where they look, and how they say a run. */
-
-/** Where the commands that read runs look, and the options their suggested commands repeat. */
-export type ReadPlace = { shellCwd: string; runRoot: string; repeat: string[] };
-
-export type Out = { stdout(text: string): void; stderr(text: string): void };
-
-/** `--cwd`, `--run-root` and `--json`, taken out of `argv`; the rest is left for the command. */
-export function parsePlace(
-  argv: readonly string[],
-  shellCwd: string,
-): { place: ReadPlace; json: boolean; rest: string[] } {
-  let cwd = shellCwd;
-  let runRoot: string | undefined;
-  let json = false;
-  const repeat: string[] = [];
-  const rest: string[] = [];
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index]!;
-    // What follows is the command's own, a message's text included.
-    if (arg === "--") {
-      rest.push(...argv.slice(index));
-      break;
-    }
-    if (arg === "--json") json = true;
-    else if (arg === "--cwd" || arg === "--run-root") {
-      const value = argv[index + 1];
-      if (!value || value.startsWith("--")) throw new Error(`${arg} needs a directory`);
-      index += 1;
-      if (arg === "--cwd") cwd = resolve(shellCwd, value);
-      else runRoot = resolve(shellCwd, value);
-      repeat.push(arg, value);
-    } else rest.push(arg);
-  }
-  return { place: { shellCwd, runRoot: runRoot ?? runRootOf(cwd), repeat }, json, rest };
-}
-
-/** A suggested command, with the place repeated. */
-export function command(place: ReadPlace, ...words: string[]): string[] {
-  const [first, second, ...rest] = words;
-  return [first!, second!, ...rest.slice(0, 1), ...place.repeat, ...rest.slice(1)];
-}
-
-/** A field whose name says it holds a credential, whatever its value looks like. */
-const SECRET_NAME =
-  /password|passwd|passphrase|passcode|secret|token|credential|cookie|bearer|authorization|(?:api|access|private|session|ssh|signing|encryption)[_-]?key|^(?:pwd|pass|pin|auth)$/i;
-
-/**
- * Every string in `value` masked, and everything under a credential's name hidden: a run's text,
- * errors and fields are its workflow's, its agents' and its tools'. Past `limit`, a string is cut.
- */
-export function masked(value: unknown, limit = Number.POSITIVE_INFINITY, hidden = false): unknown {
-  if (typeof value === "string") {
-    if (hidden) return "***";
-    const shown = maskCredentials(value);
-    return shown.length > limit ? `${shown.slice(0, limit - 1)}…` : shown;
-  }
-  if (hidden && value !== null && typeof value !== "object") return "***";
-  if (Array.isArray(value)) return value.map((each) => masked(each, limit, hidden));
-  if (value && typeof value === "object") {
-    return Object.fromEntries(
-      Object.entries(value).map(([key, each]) => [
-        key,
-        masked(each, limit, hidden || SECRET_NAME.test(key)),
-      ]),
-    );
-  }
-  return value;
-}
-
-/**
- * Text a run wrote, as one masked line of about `limit` characters, so it can never pass for a
- * line of its own or fill a page. `@{handle} --full` prints it whole.
- */
-export function said(text: string, limit = 120): string {
-  const line = maskCredentials(text).replace(/\s*[\r\n]+\s*/g, " ⏎ ");
-  return line.length > limit ? `${line.slice(0, limit - 1)}…` : line;
-}
-
-/** A suggested command as text to paste into a shell. */
-export function shellLine(words: readonly string[]): string {
-  return words.map(shellWord).join(" ");
-}
+/** The longest `--wait` the commands that read runs take. */
+export const MAX_WAIT_SECONDS = 300;
+/** How often they read a run while they wait. */
+export const POLL_MS = 1_000;
 
 /** Says a run that is not there, and exits 1; anything else is the run's files, exit 3. */
-export function failed(error: unknown, place: ReadPlace, out: Out, message: string): number {
+export function failed(
+  error: unknown,
+  place: ReadPlace,
+  out: Out,
+  message: string,
+  json: { json: boolean; v: number } = NO_JSON,
+): number {
+  // The error's own code; else a file that couldn't be read, exit 3's, or a failure of awf's.
+  const code = readFailureCode(error);
+  if (json.json) out.stdout(refusalLine(json.v, code, message));
   if (error instanceof RunNotFound) {
     out.stderr(`${error.message}; runs here: ${shellLine(command(place, "awf", "runs"))}`);
     return 1;
@@ -114,16 +50,6 @@ export function startedLine(
   return `awf: ${ref} started · watch: ${shellLine(["awf", "logs", ref, ...placeFlags(run)])}`;
 }
 
-/** The flags that find this run again from another command: the folder or run root given. */
-export function placeFlags(
-  run: Pick<RunCommand, "cwd" | "cwdGiven" | "runRoot" | "runRootGiven">,
-): string[] {
-  return [
-    ...(run.cwdGiven ? ["--cwd", run.cwd] : []),
-    ...(run.runRootGiven ? ["--run-root", run.runRoot] : []),
-  ];
-}
-
 /** `awf logs` from `cursor`: with `--wait` unless the page stopped short of the newest. */
 export function nextLogs(
   status: RunStatus,
@@ -137,7 +63,7 @@ export function nextLogs(
     ...filters,
     "--after",
     encodeCursor(cursor),
-    ...(wait ? ["--wait", "90"] : []),
+    ...(wait ? ["--wait", "90s"] : []),
   ];
 }
 
@@ -205,22 +131,24 @@ export function span(
   return { started, ...(ended === undefined ? {} : { ended }), ms: (ended ?? now) - started };
 }
 
-/** At list prices, over the attempts that kept one: never what was billed. */
-export function estimateOf(attempts: readonly AttemptRecord[]): number | undefined {
-  const known = attempts.flatMap((each) =>
-    each.accounting?.totals.estimate === undefined ? [] : [each.accounting.totals.estimate],
+/**
+ * At list prices, today's, over the run's agent operations that recorded their spend, never what
+ * was billed; and how many operations' usage isn't known, which makes it a floor.
+ */
+export async function estimateOf(
+  status: RunStatus,
+): Promise<{ estimate?: number; unknown: number }> {
+  const spent = await readSpent(status.run.dir, status.attempts, { decisions: false }).catch(
+    () => undefined,
   );
-  return known.length > 0 ? known.reduce((total, each) => total + each, 0) : undefined;
-}
-
-/** `$6.10`; `<$0.01` for less, and nothing for none. */
-export function money(estimate: number | undefined): string[] {
-  if (!estimate) return [];
-  return [estimate < 0.005 ? "<$0.01" : `$${estimate.toFixed(2)}`];
-}
-
-export function clockTime(at: number | string): string {
-  const date = new Date(at);
-  const two = (n: number) => String(n).padStart(2, "0");
-  return `${two(date.getHours())}:${two(date.getMinutes())}:${two(date.getSeconds())}`;
+  if (!spent) return { unknown: 0 };
+  const estimate = runEstimate(spent);
+  // A running attempt's operations are read as it ends: not yet unknown.
+  const live = status.state === "running" ? status.attempts.at(-1)?.attempt : undefined;
+  return {
+    ...(estimate === undefined ? {} : { estimate }),
+    unknown: unknownOps(
+      spent.map((each) => (each.attempt === live ? { ...each, unsettled: 0 } : each)),
+    ),
+  };
 }

package/src/run-event-log.ts

@@ -41,7 +41,7 @@ export class RunEventLog {
     if (this.#closed) return;
     this.#writes.push(
       appendEvent(this.options.runDir, record).catch((error) =>
-        this.options.failed(`awf: a turn was not recorded in turns.jsonl: ${messageOf(error)}`),
+        this.options.failed(`awf: a turn was not recorded in log.jsonl: ${messageOf(error)}`),
       ),
     );
   }

package/src/run-lines.ts

@@ -0,0 +1,159 @@
+import { open, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { type RunLine, type RunView, readRun } from "@agentswf/contract/records";
+import { messageOf } from "./errors";
+import { isCode, syncDir } from "./files";
+import { queued } from "./jsonl";
+import { unendedTurns } from "./run-policy/waits";
+import { RunUnreachable } from "./run-unreachable";
+import { crashedEnd } from "./turn-ends";
+
+/** `run.jsonl`, what the run settled; resolved, as it keys the append queue. */
+export function runLinesFile(runDir: string): string {
+  return resolve(runDir, "run.jsonl");
+}
+
+/** Appends one attempt's lines to `run.jsonl`, in call order, each whole and synced. */
+export type RunLines = {
+  readonly attempt: number;
+  append(line: RunLine): Promise<void>;
+};
+
+/** Attempt `attempt`'s writer: made only by its claim, so nothing appends before the fence. */
+function runLines(runDir: string, attempt: number): RunLines {
+  const path = runLinesFile(runDir);
+  return {
+    attempt,
+    append(line) {
+      if (line.attempt !== attempt) {
+        return Promise.reject(
+          new Error(`attempt ${attempt} cannot append a line of attempt ${line.attempt}`),
+        );
+      }
+      return queued(path, () => appendSynced(path, `${JSON.stringify(line)}\n`));
+    },
+  };
+}
+
+/**
+ * The claim on `run.jsonl`: cuts a line a crash left torn, so it never merges with the next, then
+ * appends `claimed`, the fence after which a line of an earlier attempt is ignored, then ends each
+ * turn an earlier attempt began and never ended, failed, before any wait can look. Called once the
+ * previous attempt's process is gone.
+ */
+export async function claimRunLines(
+  runDir: string,
+  attempt: number,
+  at: string,
+): Promise<RunLines> {
+  const path = runLinesFile(runDir);
+  await queued(path, () => cutTorn(path));
+  // `run.jsonl` may be new here: its entry in the folder is made durable with the claim.
+  await syncDir(runDir);
+  const lines = runLines(runDir, attempt);
+  await lines.append({ kind: "claimed", attempt, at });
+  for (const turn of unendedTurns((await readRunLines(runDir)).lines))
+    await lines.append(crashedEnd(turn, attempt, at));
+  return lines;
+}
+
+/**
+ * `run.jsonl`'s complete lines, checked, and their reading. Text after the last newline is a line
+ * still being written or one a crash tore, which the next claim cuts: it is not read.
+ */
+export async function readRunLines(runDir: string): Promise<{ lines: RunLine[]; view: RunView }> {
+  const path = runLinesFile(runDir);
+  const text = await readFile(path, "utf8").catch((error) => {
+    if (isCode(error, "ENOENT")) return "";
+    throw error;
+  });
+  const complete = text.slice(0, text.lastIndexOf("\n") + 1).split("\n");
+  complete.pop();
+  const parsed = complete.map((line, index) => {
+    try {
+      return JSON.parse(line) as unknown;
+    } catch {
+      throw new RunUnreachable(`run.jsonl line ${index + 1}: not JSON`);
+    }
+  });
+  let view: RunView;
+  try {
+    view = readRun(parsed);
+  } catch (error) {
+    // A line of no kind this awf knows: the run's record can't be read, as a line not JSON.
+    throw new RunUnreachable(messageOf(error));
+  }
+  return { lines: parsed as RunLine[], view };
+}
+
+/**
+ * One `O_APPEND` write, then fsync; Bun's fsync on macOS is not `F_FULLFSYNC` (story 041, Q5). A
+ * write that fails part way is cut, so the next line isn't glued to its half.
+ */
+async function appendSynced(path: string, text: string): Promise<void> {
+  const handle = await open(path, "a", 0o600);
+  try {
+    const { size } = await handle.stat();
+    const bytes = new TextEncoder().encode(text);
+    let written = 0;
+    try {
+      while (written < bytes.byteLength) {
+        const { bytesWritten } = await handle.write(bytes, written, bytes.byteLength - written);
+        if (bytesWritten === 0) throw new Error("append made no progress");
+        written += bytesWritten;
+      }
+    } catch (error) {
+      // Only when the file ends with this write's bytes: a stale writer never cuts another's line.
+      const now = await handle.stat().catch(() => undefined);
+      if (written > 0 && now?.size === size + written) {
+        await handle.truncate(size).catch(() => undefined);
+      }
+      throw error;
+    }
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+/** Truncates `path` to its last newline, creating it when absent. */
+async function cutTorn(path: string): Promise<void> {
+  const handle = await open(path, "a+", 0o600);
+  try {
+    const { size } = await handle.stat();
+    const end = await afterLastNewline(handle, size);
+    if (end < size) {
+      await handle.truncate(end);
+      await handle.sync();
+    }
+  } finally {
+    await handle.close();
+  }
+}
+
+type Reader = {
+  read(
+    buffer: Uint8Array,
+    offset: number,
+    length: number,
+    position: number,
+  ): Promise<{
+    bytesRead: number;
+  }>;
+};
+
+/** The offset just past the last newline before `size`, read backwards; 0 when there is none. */
+async function afterLastNewline(handle: Reader, size: number): Promise<number> {
+  const chunk = new Uint8Array(64 * 1024);
+  let end = size;
+  while (end > 0) {
+    const start = Math.max(0, end - chunk.byteLength);
+    const length = end - start;
+    const { bytesRead } = await handle.read(chunk, 0, length, start);
+    if (bytesRead !== length) throw new Error("run.jsonl changed while it was claimed");
+    const newline = chunk.subarray(0, length).lastIndexOf(10);
+    if (newline !== -1) return start + newline + 1;
+    end = start;
+  }
+  return 0;
+}

package/src/run-lock.ts

@@ -5,7 +5,8 @@ import { probeProcess, processStart, sameStart } from "./runs";
 
 /**
  * `{root}/{workflow}/{run id}.lock`: the lock on a run, beside its run's folder so it exists before
- * the run does. Every append to the run's mailbox, and each decision made from it, holds it.
+ * the run does. Every sender's append to `in.jsonl` holds it, and so does a wait's last look before
+ * it parks.
  */
 export function runLockFile(runRoot: string, workflow: string, runId: string): string {
   return join(runRoot, workflow, `${runId}.lock`);
@@ -79,6 +80,61 @@ async function claim(file: string): Promise<Holder> {
   }
 }
 
+/**
+ * `{root}/{workflow}/{run id}.open`: held by `awf open --no-fork` for as long as the session it
+ * opened is open, so no attempt starts and no second one opens it (story 042). Claimed as the
+ * run's lock is, but never waited for.
+ */
+export function runOpenFile(runRoot: string, workflow: string, runId: string): string {
+  return join(runRoot, workflow, `${runId}.open`);
+}
+
+/** Who holds a claim: its process, by pid and start. */
+export type ClaimHolder = Holder;
+
+/**
+ * Claims `file` once, without waiting: this process's holding, or the live process that holds it.
+ * A holder whose process is gone is taken over.
+ */
+export async function claimNow(file: string): Promise<{ held: Holder } | { heldBy: Holder }> {
+  const started = ownStart();
+  if (started === undefined) throw new Error(`no start time for this process (${process.pid})`);
+  const mine: Holder = { pid: process.pid, processStart: started, at: new Date().toISOString() };
+  await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+  for (let tries = 0; tries < 5; tries += 1) {
+    if (await linkNew(file, mine)) return { held: mine };
+    const holder = await readHolder(file);
+    if (holder === "gone") continue;
+    if (holder && !gone(holder)) return { heldBy: holder };
+    await takeOver(file, holder);
+  }
+  throw new Error(`${file} changed hands as it was claimed; try again`);
+}
+
+/** Lets go of `file`, if `held` still holds it. */
+export async function releaseClaim(file: string, held: Holder): Promise<void> {
+  if (JSON.stringify(await readHolder(file)) === JSON.stringify(held))
+    await unlink(file).catch(() => undefined);
+}
+
+/**
+ * The live process holding `file`, read without taking it; none for a holder that is gone. A
+ * holder `ps` can't be asked about counts as live, as in `gone`: what it holds back waits for a
+ * later look, never runs beside it.
+ */
+export async function liveHolder(file: string): Promise<Holder | undefined> {
+  const holder = await readHolder(file);
+  return holder !== "gone" && holder !== undefined && !gone(holder) ? holder : undefined;
+}
+
+/**
+ * Whether a live process holds the lock, read without taking it. A holder whose process is gone,
+ * a sender killed mid-launch, holds nothing; nor does a torn file, which `claim` takes over.
+ */
+export async function lockHeld(file: string): Promise<boolean> {
+  return (await liveHolder(file)) !== undefined;
+}
+
 /**
  * Whether a holder's process is gone. Where `ps` can't be asked, it is taken as alive: taking a
  * live holder's lock over would let two writers in.

package/src/{stage-plan.ts → run-policy/stage-plan.ts}

@@ -1,27 +1,32 @@
-import type { StageNeed, StageRecord } from "@agentswf/contract/records";
+import type { StageLine, StageNeed } from "@agentswf/contract/records";
 import { type JsonSchema, type SchemaError, validate } from "@agentswf/contract/schema";
 import type { JsonValue } from "@agentswf/contract/workflow";
 
 /**
  * What a continue does with a stage it enters: until its start point, each is reused from its
- * record, provided, or stops the attempt; from the start point on, every stage runs. The start
- * point is `--from-stage`, or else the first stage entered with no succeeded record. Before a
- * `--from-stage`, a stage whose record can't be reused takes its value from `--values`, one that
- * returns nothing is passed, and one with nothing recorded needs a value. Pure: the records, the values, the result and the version come
- * in, a decision goes out.
+ * line, provided, or stops the attempt; from the start point on, every stage runs. The start
+ * point is `--from-stage`, or else the first stage entered with no succeeded line. Before a
+ * `--from-stage`, a stage whose line can't be reused takes its value from `--values`, one that
+ * returns nothing is passed, and one with nothing recorded needs a value. Pure: the line the run's
+ * reuse gives, the values, the result and the version come in, a decision goes out.
  */
 type StagePlanDecision =
-  | { kind: "reuse"; record: StageRecord; value: JsonValue | undefined }
+  | { kind: "reuse"; line: StageLine; value: JsonValue | undefined }
   /** A value given, checked by the stage's result; undefined for a stage that returns nothing. */
   | { kind: "provide"; value: JsonValue | undefined }
-  /** `start` on the stage that is the start point, when the records it outdates are moved. */
+  /** `start` on the stage that is the start point. */
   | { kind: "run"; start: boolean }
   | { kind: "stop"; reason: string }
   /** Nothing recorded, and no value given that fits: `--values` lets the attempt go on. */
   | { kind: "need"; reason: string; need: StageNeed };
 
 export type StagePlanState = {
-  records: ReadonlyMap<string, StageRecord>;
+  /** The stage's line as `StageReuse` gives it: its latest, unless a redo outdated it. */
+  line?: StageLine;
+  /** The `meta.version` of the attempt that wrote `line`. */
+  lineVersion?: string;
+  /** The stages the run has a line for. */
+  recorded: readonly string[];
   fromStage?: string;
   /** `--values`: each stage's value, to start at `fromStage`. */
   values?: ReadonlyMap<string, JsonValue>;
@@ -44,20 +49,20 @@ export function planStage(
 ): StagePlanDecision {
   if (state.started) return { kind: "run", start: false };
   if (stage === state.fromStage) return { kind: "run", start: true };
-  const record = state.records.get(stage);
-  const succeeded = record?.outcome === "succeeded" ? record : undefined;
+  const { line } = state;
+  const succeeded = line?.outcome === "succeeded" ? line : undefined;
   const stale = succeeded && unreusable(state, succeeded, result);
   if (succeeded && stale === undefined) {
-    return { kind: "reuse", record: succeeded, value: succeeded.value };
+    return { kind: "reuse", line: succeeded, value: succeeded.value };
   }
   if (state.fromStage === undefined) {
     return stale === undefined ? { kind: "run", start: true } : { kind: "stop", reason: stale };
   }
-  // A record there that failed or went stale is redone from its stage, as on any continue, unless
-  // a value given replaces it.
-  const redo = record && {
+  // A line there that failed or went stale is redone from its stage, as on any continue, unless a
+  // value given replaces it.
+  const redo = line && {
     kind: "stop" as const,
-    reason: stale ?? `${stage} did not succeed in attempt ${record.attempt}`,
+    reason: stale ?? `${stage} did not succeed in attempt ${line.attempt}`,
   };
   if (result === undefined) return redo ?? { kind: "provide", value: undefined };
   const need = { stage, schema: result };
@@ -78,38 +83,37 @@ export function planStage(
 }
 
 /**
- * Why a succeeded record can't be reused, as a stop says it, or undefined when it can: another
- * major version recorded it, or its value no longer fits the stage's `result`.
+ * Why a succeeded line can't be reused, as a stop says it, or undefined when it can: another major
+ * version wrote it, or its value no longer fits the stage's `result`.
  */
 function unreusable(
   state: StagePlanState,
-  record: StageRecord,
+  line: StageLine,
   result: JsonSchema | undefined,
 ): string | undefined {
-  const { stage } = record;
-  const recorded = majorOf(record.workflowVersion);
+  const recorded = majorOf(state.lineVersion);
   const now = majorOf(state.workflowVersion);
   if (recorded !== undefined && now !== undefined && recorded !== now) {
-    return `${stage} was recorded by ${record.workflowVersion}; this is ${state.workflowVersion}`;
+    return `${line.name} was recorded by ${state.lineVersion}; this is ${state.workflowVersion}`;
   }
-  return misfitOf(record, result);
+  return misfitOf(line, result);
 }
 
-/** Why a succeeded record's value no longer fits the stage's `result`; undefined when it does. */
-function misfitOf(record: StageRecord, result: JsonSchema | undefined): string | undefined {
-  const { stage } = record;
+/** Why a succeeded line's value no longer fits the stage's `result`; undefined when it does. */
+function misfitOf(line: StageLine, result: JsonSchema | undefined): string | undefined {
+  const stage = line.name;
   if (result === undefined) {
-    return record.value === undefined
+    return line.value === undefined
       ? undefined
-      : `${stage}'s record holds a value, and the stage no longer has a result`;
+      : `${stage}'s line holds a value, and the stage no longer has a result`;
   }
-  if (record.value === undefined) {
-    return `${stage}'s record holds no value, and the stage's result now expects one`;
+  if (line.value === undefined) {
+    return `${stage}'s line holds no value, and the stage's result now expects one`;
   }
-  const errors = validate(result, record.value);
+  const errors = validate(result, line.value);
   return errors.length === 0
     ? undefined
-    : problems(`${stage}'s record no longer fits its result schema:`, errors);
+    : problems(`${stage}'s line no longer fits its result schema:`, errors);
 }
 
 /** A value's problems under what they are problems of, a line each. */
@@ -119,13 +123,13 @@ function problems(heading: string, errors: readonly SchemaError[]): string {
 
 /** Recorded stages this attempt hasn't reached, which a rename in the code would leave behind. */
 function unreached(state: StagePlanState, stage: string): string {
-  const others = [...state.records.keys()].filter(
+  const others = state.recorded.filter(
     (name) => name !== stage && name !== state.fromStage && !state.entered.includes(name),
   );
   return others.length > 0 ? ` (recorded and not reached: ${others.join(", ")})` : "";
 }
 
-/** What must match for a record to be reused: the major, or `0.{minor}`, as semver has it. */
+/** What must match for a line to be reused: the major, or `0.{minor}`, as semver has it. */
 function majorOf(version: string | undefined): string | undefined {
   if (version === undefined) return undefined;
   const [major, minor] = version.split(".");
@@ -133,18 +137,18 @@ function majorOf(version: string | undefined): string | undefined {
 }
 
 /**
- * In a run of a workflow with `events`, a stage runs once ever: a succeeded record is reused
- * wherever and however often its name is entered, whatever version of the code recorded it, as
- * long as its value still fits the stage's `result`. One that doesn't fit stops the attempt; a
- * failed record, or none, runs.
+ * In a run of a workflow with `events`, a stage runs once ever: a succeeded line is reused wherever
+ * and however often its name is entered, whatever version of the code wrote it, as long as its
+ * value still fits the stage's `result`. One that doesn't fit stops the attempt; a failed line, or
+ * none, runs.
  */
 export function planStageByContent(
-  record: StageRecord | undefined,
+  line: StageLine | undefined,
   result: JsonSchema | undefined,
 ): Extract<StagePlanDecision, { kind: "reuse" | "stop" }> | { kind: "run" } {
-  if (record?.outcome !== "succeeded") return { kind: "run" };
-  const misfit = misfitOf(record, result);
+  if (line?.outcome !== "succeeded") return { kind: "run" };
+  const misfit = misfitOf(line, result);
   return misfit === undefined
-    ? { kind: "reuse", record, value: record.value }
+    ? { kind: "reuse", line, value: line.value }
     : { kind: "stop", reason: misfit };
 }