trantor 0.18.49 → 0.18.51

package/lib/state/migrate.mjs

@@ -0,0 +1,126 @@
+/* oxlint-disable anti-slop/no-runtime-typeof -- SAFETY: migration reads objects written by an OLDER schema version off disk — the type of any field is exactly what cannot be assumed, which is why a mismatch is salvaged into notes instead of coerced. */
+// Trantor State — migration (TDD §4.3). A field the newer schema does not know is never dropped:
+// it is appended to `notes` as `migrated:<path>=<json>`. That is #6528 generalised, and it is the
+// single rule that makes the whole scheme safe to version.
+import { CAPS, CURRENT_VERSION, ERR, KNOWN_FIELDS, emptyState, stateError } from "./schema.mjs";
+
+/** Append `migrated:` lines to notes, oldest evicted first when the cap bites. */
+function noteMigrated(state, lines) {
+  if (!lines.length) return state;
+  const joined = [state.notes, ...lines].filter(Boolean).join("\n");
+  // Truncate to fit CAPS.NOTES by dropping from the front — the newest migrated line is the one
+  // most likely to matter, and a mid-line elision is exactly the bug this rule exists to prevent.
+  const all = joined.split("\n");
+  while (all.length > 1 && Buffer.byteLength(all.join("\n"), "utf8") > CAPS.NOTES) all.shift();
+  state.notes = all.join("\n").slice(-CAPS.NOTES);
+  return state;
+}
+
+/**
+ * Sweep every key the v3 schema does not define into `notes`. Returns the swept state.
+ */
+function absorbUnknown(state) {
+  const lines = [];
+  for (const key of Object.keys(state)) {
+    if (KNOWN_FIELDS.includes(key)) continue;
+    lines.push(`migrated:${key}=${JSON.stringify(state[key])}`);
+    delete state[key];
+  }
+  return noteMigrated(state, lines);
+}
+
+/** v2 → v3: `rev`, the two compaction counters and FileFact.hash are new; everything else carries
+ *  over by name. Unknown v2 keys go to notes rather than being dropped. */
+function up2to3(v2) {
+  const out = { ...emptyState(0) };
+  // A value of the wrong TYPE is not silently coerced to a default — that is field loss wearing a
+  // helpful face, and zero-field-loss means zero. It keeps the default and the original value goes
+  // to notes, exactly like an unknown key.
+  const salvaged = [];
+  const carry = (key, value, typeOk) => {
+    if (value === undefined) return false;
+    if (typeOk) return true;
+    salvaged.push(`migrated:${key}=${JSON.stringify(value)}`);
+    return false;
+  };
+  if (carry("card", v2.card, Number.isInteger(v2.card))) out.card = v2.card;
+  for (const key of ["task", "notes"]) {
+    if (carry(key, v2[key], typeof v2[key] === "string")) out[key] = v2[key];
+  }
+  for (const list of ["done", "in_flight", "next", "blockers"]) {
+    if (Array.isArray(v2[list])) {
+      out[list] = v2[list]
+        .filter(i => i && typeof i.id === "string" && typeof i.text === "string")
+        .map(i => (Array.isArray(i.paths) ? { id: i.id, text: i.text, paths: i.paths } : { id: i.id, text: i.text }));
+    }
+  }
+  if (v2.files && typeof v2.files === "object") {
+    for (const [p, f] of Object.entries(v2.files)) {
+      if (!f || typeof f !== "object") continue;
+      out.files[p] = { touched: f.touched === true, verified: f.verified === true };
+      if (Number.isInteger(f.blast_radius)) out.files[p].blast_radius = f.blast_radius;
+    }
+  }
+  if (v2.verify && typeof v2.verify === "object") out.verify = { ...v2.verify };
+  if (v2.ext && typeof v2.ext === "object") out.ext = { ...v2.ext };
+  if (v2.cursor && typeof v2.cursor === "object") {
+    for (const [k, isOk] of [["turn", Number.isInteger(v2.cursor.turn)], ["ts", Number.isInteger(v2.cursor.ts)], ["by", typeof v2.cursor.by === "string"]]) {
+      if (carry(`cursor.${k}`, v2.cursor[k], isOk)) out.cursor[k] = v2.cursor[k];
+    }
+  }
+  if (carry("done_count", v2.done_count, Number.isInteger(v2.done_count))) out.done_count = v2.done_count;
+  if (carry("files_count", v2.files_count, Number.isInteger(v2.files_count))) out.files_count = v2.files_count;
+
+  // Carry the unknowns across BEFORE absorbing, so they are swept from the v3 object and land in
+  // notes rather than vanishing with the v2 shell.
+  const carried = { ...out };
+  for (const key of Object.keys(v2)) {
+    if (KNOWN_FIELDS.includes(key) || key === "schema_version") continue;
+    carried[key] = v2[key];
+  }
+  return noteMigrated(absorbUnknown(carried), salvaged);
+}
+
+/** Applied in sequence on read until schema_version matches CURRENT. */
+export const MIGRATIONS = { 2: up2to3 };
+
+/**
+ * Migrate an object of any known version up to v3.
+ * An unmigratable object returns MIGRATE_FAILED; the STORE (P1) is what keeps the original file
+ * untouched under `.v<n>.json` rather than half-upgrading it — this function only reports.
+ * @returns {{ ok: true, state: object, migrated: boolean } | { ok: false, code: string, at: string, message: string }}
+ */
+export function migrate(obj) {
+  if (typeof obj !== "object" || obj === null || Array.isArray(obj)) {
+    return { ok: false, code: ERR.MIGRATE_FAILED, at: "state", message: "state must be an object" };
+  }
+  let cur = structuredClone(obj);
+  let steps = 0;
+  const from = cur.schema_version;
+  if (!Number.isInteger(from) || from < 1 || from > CURRENT_VERSION) {
+    return {
+      ok: false, code: ERR.MIGRATE_FAILED, at: "schema_version",
+      message: `no migration path from schema_version ${JSON.stringify(from)} to ${CURRENT_VERSION}`,
+    };
+  }
+  while (cur.schema_version !== CURRENT_VERSION) {
+    const step = MIGRATIONS[cur.schema_version];
+    if (!step) {
+      return {
+        ok: false, code: ERR.MIGRATE_FAILED, at: `v${cur.schema_version}`,
+        message: `no migration registered for schema_version ${cur.schema_version}`,
+      };
+    }
+    cur = step(cur);
+    cur.schema_version = CURRENT_VERSION;
+    if (++steps > CURRENT_VERSION) {
+      return { ok: false, code: ERR.MIGRATE_FAILED, at: "migrate", message: "migration did not converge" };
+    }
+  }
+  if (steps === 0) cur = absorbUnknown(cur);
+  const why = stateError(cur);
+  if (why) {
+    return { ok: false, code: ERR.MIGRATE_FAILED, at: "state", message: `migrated object is not schema-valid: ${why}` };
+  }
+  return { ok: true, state: cur, migrated: steps > 0 };
+}

package/lib/state/promote.mjs

@@ -0,0 +1,122 @@
+/* oxlint-disable anti-slop/no-runtime-typeof -- SAFETY: promote is the seam between the pure plan
+ * and a live hub. State, promotions and the hub response all arrive from outside this module, so
+ * the few typeof/Number.isInteger guards below ARE the boundary decode — the same justification the
+ * other lib/state modules carry — not a substitute for one. */
+// Trantor State P3 — the promoter (TDD §4.7). Turns the delta a turn produced (applyTurn's
+// `promoted` plan) into AT MOST ONE /task/update `note`, deduped by content hash, and advances the
+// runtime-owned ext._promoted ONLY after the hub answers 2xx — never when the plan is computed.
+//
+// The line this file exists to hold: the card is the shared record, state is private working
+// memory, and promotion is one-directional (state → card note). It never moves a card's STATUS —
+// that is the seat's relay_task_move, one owner — and it never promotes scratch (in_flight, next,
+// the notes tail, cursor, files, done_count, ext): those churn every turn and flooding the log is
+// #6669's lesson. Empty deltas are skipped entirely. A failed POST is non-fatal and never rolls
+// back state; it leaves the hash where it was, so the next turn re-sends the same content, which
+// the content hash makes harmless if the POST in fact landed and only the response was lost.
+import { createHash } from "node:crypto";
+import { signedPost } from "../../hooks/lib/api.mjs";
+
+/** CARDLOG-CONTRACT: a card-log note text is ≤ 2000 chars. The hub caps it; we never exceed it. */
+export const PROMOTE_NOTE_CAP = 2000;
+
+/** Human label per Promotion kind — the kind names from the pure plan, unchanged. */
+export const PROMOTE_LABELS = {
+  done: "done",
+  blocker_added: "blocked",
+  blocker_cleared: "unblocked",
+  verify: "verify",
+};
+
+/** One note line per promotion, `<label>: <text>`. Malformed rows are skipped, never rendered. */
+export function noteLines(promotions) {
+  if (!Array.isArray(promotions)) return [];
+  const out = [];
+  for (const p of promotions) {
+    if (!p || typeof p.kind !== "string" || typeof p.text !== "string") continue;
+    out.push(`${PROMOTE_LABELS[p.kind] || p.kind}: ${p.text}`);
+  }
+  return out;
+}
+
+/** Compose the plan into one note ≤ PROMOTE_NOTE_CAP. Deterministic — the same delta always
+ *  renders the same note, which is what makes content-hash dedupe meaningful.
+ *  @returns {string} "" when the delta is empty, else the note */
+export function composeNote(promotions, cap = PROMOTE_NOTE_CAP) {
+  const lines = noteLines(promotions);
+  if (!lines.length) return "";
+  const note = lines.join("\n");
+  if (note.length <= cap) return note;
+  // Over the cap: keep the head (done lines lead — they are the record of what shipped), drop the
+  // tail, and say so. A hard mid-line slice is #6528; whole-line elision is not.
+  const kept = [];
+  let len = 0;
+  for (const line of lines) {
+    const add = line.length + (kept.length ? 1 : 0);
+    if (len + add <= cap) { kept.push(line); len += add; continue; }
+    if (!kept.length) return `${line.slice(0, Math.max(0, cap - 1))}…`;
+    break;
+  }
+  let out = kept.join("\n");
+  const dropped = lines.length - kept.length;
+  if (dropped > 0) {
+    const marker = `\n… (+${dropped} more)`;
+    out = out.length + marker.length <= cap ? out + marker : out.slice(0, cap - marker.length) + marker;
+  }
+  return out.length <= cap ? out : out.slice(0, cap);
+}
+
+/** sha256 hex of the note — the content identity. A re-run of the same delta yields the same hash. */
+export function noteHash(note) {
+  return createHash("sha256").update(String(note ?? ""), "utf8").digest("hex");
+}
+
+/**
+ * Promote one turn's delta to the card. Pure over its inputs except for the one POST; `post` is
+ * injectable so the ordering contract is testable without a hub (defaults to the house client).
+ *
+ * @param {object} state        WorkingState — reads state.card and state.ext._promoted only
+ * @param {object[]} promotions the plan applyTurn returned (its `promoted` field)
+ * @param {{ by?: string, project?: string, post?: Function, timeoutMs?: number }} [opts]
+ *   by = session id (defaults to state.cursor.by); post(payload, opts) -> {ok,status,json}
+ * @returns {Promise<{ok:boolean, sent:boolean, skipped?:string, note:string, hash:string,
+ *   state:object, status?:number, error?:string}>} — `state` is the input untouched on failure and
+ *   a clone with ext._promoted = hash on 2xx; the caller persists it at its leisure.
+ */
+export async function promote(state, promotions, { by, project, post, timeoutMs } = {}) {
+  if (!state || !Number.isInteger(state?.card)) {
+    return {
+      ok: false, sent: false, note: "", hash: "",
+      state: state ?? null, error: "promote needs a state whose card is an integer",
+    };
+  }
+  const note = composeNote(promotions);
+  if (!note) return { ok: true, sent: false, skipped: "empty", note, hash: "", state };
+  const hash = noteHash(note);
+  const last = state.ext && typeof state.ext === "object" && state.ext._promoted !== undefined
+    ? state.ext._promoted : undefined;
+  if (typeof last === "string" && last === hash) {
+    return { ok: true, sent: false, skipped: "duplicate", note, hash, state };
+  }
+
+  const session = String(by || (state.cursor && typeof state.cursor === "object" && state.cursor.by) || "").slice(0, 120);
+  const payload = { id: state.card, by: session, note };
+  if (project) payload.project = project;
+
+  const send = post
+    || ((pl, o) => signedPost("/task/update", pl, { project: o?.project, session: o?.session, timeoutMs: o?.timeoutMs }));
+  let res;
+  try { res = await send(payload, { project, session, timeoutMs }); }
+  catch { res = null; }
+
+  const status = res && Number.isInteger(res.status) ? res.status : 0;
+  const confirmed = !!res && res.ok === true && status >= 200 && status < 300;
+  if (!confirmed) {
+    const error = res && res.json && typeof res.json === "object" && typeof res.json.error === "string"
+      ? res.json.error : (res ? `hub answered ${status}` : "post threw");
+    return { ok: false, sent: false, note, hash, status, error, state };
+  }
+
+  const ext = state.ext && typeof state.ext === "object" ? { ...state.ext } : {};
+  const advanced = { ...state, ext: { ...ext, _promoted: hash } };
+  return { ok: true, sent: true, skipped: undefined, note, hash, status, state: advanced };
+}

package/lib/state/schema.mjs

@@ -0,0 +1,216 @@
+/* oxlint-disable anti-slop/no-runtime-typeof -- SAFETY: this file IS the I/O boundary decoder. A WorkingState is JSON read off disk and a TurnResult is untrusted model output; stateError/itemError/isAction are the parse step that establishes the contract every other module then relies on, so the typeof checks here are the boundary, not a substitute for one. */
+// Trantor State — the wire contract (TDD §3). One place for the shapes, the caps, the write
+// matrix and the evidence marker; validate.mjs and apply.mjs hold behaviour, this file holds
+// facts. Nothing here reads the disk or the clock.
+//
+// The whole package is dark at P0: nothing in the running product imports it yet.
+
+/** @typedef {{ id: string, text: string, paths?: string[] }} Item   // id <= CAPS.ID, text <= CAPS.ITEM */
+/** @typedef {{ touched: boolean, verified: boolean, hash?: string, blast_radius?: number }} FileFact
+ *  // every field harness-written; `hash` = the path's blob sha when the gate credited it (TDD §4.2) */
+
+/** @typedef {{
+ *   schema_version: 3,
+ *   card: number,
+ *   task: string,
+ *   done: Item[], in_flight: Item[], next: Item[], blockers: Item[],
+ *   done_count: number, files_count: number,
+ *   files: Record<string, FileFact>,
+ *   verify: { built?: boolean, tested?: boolean, observed?: boolean, cmd?: string, exit?: number },
+ *   notes: string,
+ *   ext: Record<string, unknown>,
+ *   cursor: { turn: number, ts: number, by: string },
+ *   rev: number
+ * }} WorkingState */
+
+/** @typedef {{ tool: string, input: object } | { done: true } | { ask: string } | { continue: true }} Action */
+/** @typedef {{ patch: Op[], action: Action }} TurnResult */
+/** @typedef {{ set: { field: string, value: unknown } }
+ *          | { add: { list: ListName, item: Item } }
+ *          | { remove: { list: ListName, id: string } }
+ *          | { move: { id: string, from: ListName, to: ListName } }} Op */
+
+/** @typedef {{ kind: "done"|"blocker_added"|"blocker_cleared"|"verify", text: string }} Promotion */
+
+export const CURRENT_VERSION = 3;
+
+/** Caps — one table, one place (TDD §3.1). A driver that wants a cap imports this. */
+export const CAPS = {
+  ID: 32,           // chars per item id — ids render into the prompt and key every array op
+  ITEM: 240,        // chars per item PROSE, after the evidence marker is extracted
+  ITEM_PATHS: 8,    // evidence paths per item
+  PATH: 400,        // chars per files key
+  NOTES: 2048,      // bytes of the notes tail
+  LIST: 40,         // items per list; `done` overflow compacts into done_count, the
+                    // working lists reject instead (TDD §3.1)
+  FILES: 200,       // paths; overflow compacts into files_count
+  EXT_KEYS: 8, EXT_BYTES: 4096,
+  TAIL_TOKENS: 2000, OBS_TOKENS: 4000,
+  TASK: 400,
+};
+
+/** The four lists a patch may address. */
+export const LISTS = ["done", "in_flight", "next", "blockers"];
+
+/** Append-only history: overflow COMPACTS into a `_count`. Everything else in LISTS is a working
+ *  list, where overflow is a CAP rejection — dropping the oldest blocker silently is the worst
+ *  thing this object could do (TDD §3.1). */
+export const COMPACTING_LISTS = ["done"];
+
+/**
+ * The evidence marker, made structural (TDD §3). A model writes it inline —
+ *   "wire the promoter @lib/state/promote.mjs,test/state/test-promote.mjs"
+ * — and the validator extracts it into `paths` BEFORE any cap is applied. This regex lives here
+ * and nowhere else; a second copy is how the two halves drift apart.
+ */
+export const EVIDENCE_MARKER = /\s+@((?:[\w./-]+)(?:,[\w./-]+)*)\s*$/;
+
+/** Rejection codes the pure core returns (TDD §3.3). `STALE` is deliberately absent: it is the
+ *  CAS outcome of the store's commit(), which no branch in here can produce. */
+export const ERR = {
+  SCHEMA: "SCHEMA",
+  READONLY_FIELD: "READONLY_FIELD",
+  CAP: "CAP",
+  UNKNOWN_LIST: "UNKNOWN_LIST",
+  UNKNOWN_FIELD: "UNKNOWN_FIELD",
+  DUP_ID: "DUP_ID",
+  NO_SUCH_ID: "NO_SUCH_ID",
+  UNVERIFIED_DONE: "UNVERIFIED_DONE",
+  NEEDS_GATE: "NEEDS_GATE",
+  BAD_ACTION: "BAD_ACTION",
+  MIGRATE_FAILED: "MIGRATE_FAILED",
+};
+
+/** Malformed OUTPUT — the seat failed to speak the grammar. These count against the §7.3 invalid-
+ *  patch budget and the circuit breaker. */
+export const MALFORMED_CODES = [
+  ERR.SCHEMA, ERR.BAD_ACTION, ERR.READONLY_FIELD, ERR.CAP,
+  ERR.UNKNOWN_FIELD, ERR.UNKNOWN_LIST, ERR.DUP_ID, ERR.NO_SUCH_ID,
+];
+
+/** Well-formed patch, wrong CODE — the system working. Never counted against the budget, or the
+ *  breaker trips on the healthiest seat there is: one writing perfect patches against a failing
+ *  test (TDD §7.3). */
+export const EVIDENCE_CODES = [ERR.UNVERIFIED_DONE, ERR.NEEDS_GATE];
+
+/** Every field a `set` op may write. Anything else that IS a schema field is READONLY_FIELD;
+ *  anything the schema does not define at all is UNKNOWN_FIELD (TDD §4.2 stage 3). */
+export const SETTABLE_FIELDS = ["task", "notes", "ext"];
+
+/** Harness/runtime fields, never model-writable (TDD §2 / §4.2 write matrix). `files` is listed
+ *  whole because every FileFact field — touched, verified, hash, blast_radius — is harness-written:
+ *  git is ground truth for the first, the gate for the rest. */
+export const READONLY_FIELDS = [
+  "verify", "files", "card", "schema_version", "cursor", "done_count", "files_count", "rev",
+];
+
+/** Runtime-owned `ext` keys (TDD §4.7, §4.8). Model-unwritable like the rest of the matrix. */
+export const RUNTIME_EXT_KEYS = ["_gate", "_promoted"];
+
+/** Every field name the v3 schema defines. A `set` naming anything outside this is UNKNOWN_FIELD:
+ *  an unknown field quietly accepted is the write matrix ceasing to be enforceable, because
+ *  tomorrow's real field arrives as today's typo. */
+export const KNOWN_FIELDS = [
+  "schema_version", "card", "task", ...LISTS, "done_count", "files_count",
+  "files", "verify", "notes", "ext", "cursor", "rev",
+];
+
+/** A blank, schema-valid v3 state. */
+export function emptyState(card = 0, by = "") {
+  return {
+    schema_version: CURRENT_VERSION,
+    card,
+    task: "",
+    done: [], in_flight: [], next: [], blockers: [],
+    done_count: 0, files_count: 0,
+    files: {},
+    verify: {},
+    notes: "",
+    ext: {},
+    cursor: { turn: 0, ts: 0, by },
+    rev: 0,
+  };
+}
+
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const isStr = (v) => typeof v === "string";
+const isInt = (v) => typeof v === "number" && Number.isInteger(v);
+
+/** Shape-check one Item. Returns an error string, or "" when it is well-formed. */
+export function itemError(item) {
+  if (!isObj(item)) return "item must be an object";
+  if (!isStr(item.id) || !item.id) return "item.id must be a non-empty string";
+  if (!isStr(item.text)) return "item.text must be a string";
+  if (item.paths !== undefined) {
+    if (!Array.isArray(item.paths) || !item.paths.every(isStr)) return "item.paths must be string[]";
+  }
+  for (const k of Object.keys(item)) {
+    if (!["id", "text", "paths"].includes(k)) return `item has unknown key "${k}"`;
+  }
+  return "";
+}
+
+/**
+ * Shape-check a whole WorkingState. This is what "re-validates against the schema" means in the
+ * Phase-0 property test, so it is deliberately total: it never throws, it returns the first
+ * problem it finds as a string, and "" means valid.
+ */
+export function stateError(s) {
+  if (!isObj(s)) return "state must be an object";
+  if (s.schema_version !== CURRENT_VERSION) return `schema_version must be ${CURRENT_VERSION}`;
+  if (!isInt(s.card)) return "card must be an integer";
+  if (!isStr(s.task)) return "task must be a string";
+  if (s.task.length > CAPS.TASK) return "task exceeds CAPS.TASK";
+  for (const list of LISTS) {
+    if (!Array.isArray(s[list])) return `${list} must be an array`;
+    if (s[list].length > CAPS.LIST) return `${list} exceeds CAPS.LIST`;
+    for (const item of s[list]) {
+      const e = itemError(item);
+      if (e) return `${list}: ${e}`;
+      if (item.id.length > CAPS.ID) return `${list}: item.id exceeds CAPS.ID`;
+      if (item.text.length > CAPS.ITEM) return `${list}: item.text exceeds CAPS.ITEM`;
+      if (item.paths && item.paths.length > CAPS.ITEM_PATHS) return `${list}: item.paths exceeds CAPS.ITEM_PATHS`;
+    }
+  }
+  if (!isInt(s.done_count) || s.done_count < 0) return "done_count must be a non-negative integer";
+  if (!isInt(s.files_count) || s.files_count < 0) return "files_count must be a non-negative integer";
+  if (!isObj(s.files)) return "files must be an object";
+  if (Object.keys(s.files).length > CAPS.FILES) return "files exceeds CAPS.FILES";
+  for (const [p, f] of Object.entries(s.files)) {
+    if (p.length > CAPS.PATH) return `files["${p}"] key exceeds CAPS.PATH`;
+    if (!isObj(f)) return `files["${p}"] must be an object`;
+    if (typeof f.touched !== "boolean") return `files["${p}"].touched must be a boolean`;
+    if (typeof f.verified !== "boolean") return `files["${p}"].verified must be a boolean`;
+    if (f.hash !== undefined && !isStr(f.hash)) return `files["${p}"].hash must be a string`;
+    if (f.blast_radius !== undefined && !isInt(f.blast_radius)) return `files["${p}"].blast_radius must be an integer`;
+  }
+  if (!isObj(s.verify)) return "verify must be an object";
+  if (!isStr(s.notes)) return "notes must be a string";
+  if (Buffer.byteLength(s.notes, "utf8") > CAPS.NOTES) return "notes exceeds CAPS.NOTES";
+  if (!isObj(s.ext)) return "ext must be an object";
+  if (Object.keys(s.ext).filter(k => !RUNTIME_EXT_KEYS.includes(k)).length > CAPS.EXT_KEYS) return "ext exceeds CAPS.EXT_KEYS";
+  if (!isObj(s.cursor)) return "cursor must be an object";
+  if (!isInt(s.cursor.turn)) return "cursor.turn must be an integer";
+  if (!isInt(s.cursor.ts)) return "cursor.ts must be an integer";
+  if (!isStr(s.cursor.by)) return "cursor.by must be a string";
+  if (!isInt(s.rev) || s.rev < 0) return "rev must be a non-negative integer";
+  for (const k of Object.keys(s)) {
+    if (!KNOWN_FIELDS.includes(k)) return `state has unknown key "${k}"`;
+  }
+  return "";
+}
+
+/** The one Action shape check. Missing or unrecognised → BAD_ACTION at the caller (TDD §4.2). */
+export function isAction(a) {
+  if (!isObj(a)) return false;
+  if (a.done === true) return Object.keys(a).length === 1;
+  if (a.continue === true) return Object.keys(a).length === 1;
+  if (isStr(a.ask)) return Object.keys(a).length === 1;
+  if (isStr(a.tool)) return isObj(a.input) && Object.keys(a).length === 2;
+  return false;
+}
+
+/** Structural clone, so an aborted patch can never leave a half-applied state behind. */
+export function cloneState(s) {
+  return structuredClone(s);
+}