trantor 0.18.49 → 0.18.50

package/lib/duty-nudges.mjs

@@ -32,17 +32,15 @@ export function dutyEscalations(messages) {
 export function readDutyNudgeState(path) {
   try {
     const parsed = JSON.parse(readFileSync(path, "utf8"));
-    return parsed?.nudged instanceof Object && !Array.isArray(parsed.nudged)
-      ? parsed
-      : { version: 1, nudged: {} };
+    if (!(parsed?.nudged instanceof Object) || Array.isArray(parsed.nudged)) throw new Error("invalid nudged state");
+    if (!(parsed.planned instanceof Object) || Array.isArray(parsed.planned)) parsed.planned = {};
+    return parsed;
   } catch {
-    return { version: 1, nudged: {} };
+    return { version: 1, nudged: {}, planned: {} };
   }
 }
 
-export function planDutyNudges(messages, statePath) {
-  const state = readDutyNudgeState(statePath);
-  const items = dutyEscalations(messages).filter(item => !state.nudged[item.id]);
+function buildPlan(items, owner = "") {
   const targets = [];
   for (const item of items) {
     let target = targets.find(candidate => candidate.recipient === item.recipient);
@@ -52,7 +50,37 @@ export function planDutyNudges(messages, statePath) {
     }
     if (!target.ids.includes(item.id)) target.ids.push(item.id);
   }
-  return { items, targets };
+  return { items, targets, owner };
+}
+
+export function planDutyNudges(messages, statePath) {
+  const state = readDutyNudgeState(statePath);
+  const items = dutyEscalations(messages).filter(item => !state.nudged[item.id] && !state.planned[item.id]);
+  return buildPlan(items);
+}
+
+function processAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+export async function claimDutyNudges({ messages, statePath, owner, pid = process.pid, now = Date.now() }) {
+  let plan = buildPlan([], owner);
+  await withStateLock(statePath, state => {
+    for (const [id, claim] of Object.entries(state.planned)) {
+      if (now - Number(claim?.plannedAt || 0) > 30 * 60 * 1000 || !processAlive(Number(claim?.pid || 0))) {
+        delete state.planned[id];
+      }
+    }
+    const items = dutyEscalations(messages).filter(item => !state.nudged[item.id] && !state.planned[item.id]);
+    plan = buildPlan(items, owner);
+    for (const item of items) {
+      state.planned[item.id] = {
+        owner, pid, recipient: item.recipient, project: item.project, plannedAt: now,
+      };
+    }
+  });
+  return plan;
 }
 
 export function dutyNudgeDirective(plan) {
@@ -93,7 +121,8 @@ export function observedDutyNudgeIds(transcriptDir, sinceMs) {
         for (const use of uses) {
           const input = use.input || {};
           const text = String(input.message || input.content || "");
-          if (!text.startsWith("Trantor delivery nudge from the duty seat:")) continue;
+          if (!text.startsWith("Trantor delivery nudge from the duty seat:")
+            || !text.endsWith("This nudge carries no message content; the signed bus messages are the source of truth.")) continue;
           for (const id of idsIn(text)) ids.add(id);
         }
       }
@@ -106,7 +135,7 @@ function writeDutyNudgeState(path, state) {
   const entries = Object.entries(state.nudged)
     .sort((a, b) => Number(b[1]?.nudgedAt || 0) - Number(a[1]?.nudgedAt || 0))
     .slice(0, 5000);
-  const next = { version: 1, nudged: Object.fromEntries(entries) };
+  const next = { version: 1, nudged: Object.fromEntries(entries), planned: state.planned || {} };
   const temporary = `${path}.${process.pid}.tmp`;
   writeFileSync(temporary, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
   renameSync(temporary, path);
@@ -136,6 +165,7 @@ export async function recordDutyNudges({ plan, observedIds, statePath, now = Dat
   await withStateLock(statePath, state => {
     for (const item of nudged) {
       state.nudged[item.id] = { recipient: item.recipient, project: item.project, nudgedAt: now };
+      delete state.planned[item.id];
     }
   });
   return nudged;
@@ -148,5 +178,13 @@ export async function auditDutyNudges({ plan, observedIds, statePath, reportFail
     ids: target.ids.filter(id => !observedIds.has(id)),
   })).filter(target => target.ids.length);
   for (const target of missing) await reportFailure(target);
+  if (missing.length) {
+    const missingIds = new Set(missing.flatMap(target => target.ids));
+    await withStateLock(statePath, state => {
+      for (const id of missingIds) {
+        if (state.planned[id]?.owner === plan.owner) delete state.planned[id];
+      }
+    });
+  }
   return { missing, nudged };
 }

package/lib/state/apply.mjs

@@ -0,0 +1,170 @@
+/* oxlint-disable anti-slop/no-runtime-typeof -- SAFETY: ctx carries harness facts from the driver and set() merges model-supplied values; both are decoded here at the boundary rather than trusted. */
+// Trantor State — apply (TDD §4.2, stages 4-5). Validate, then apply to a CLONE, then the runtime
+// pass. Pure: `ctx` carries the clock and the harness facts, so this function is a function of its
+// arguments and nothing else.
+//
+// One apply point per turn is the whole crash-safety argument (§4.4): a turn killed mid-flight has
+// never partially applied a patch, because the patch is applied to a clone that is only returned
+// when every op passed.
+import { CAPS, LISTS, COMPACTING_LISTS, RUNTIME_EXT_KEYS, cloneState } from "./schema.mjs";
+import { validateTurn } from "./validate.mjs";
+
+/** Deep-merge one level, the `set` semantics of §3.2: null deletes an optional key. */
+function setField(state, field, value) {
+  const [root, sub] = String(field).split(".");
+  if (sub === undefined) {
+    if (value === null && root === "ext") { state.ext = {}; return; }
+    state[root] = value;
+    return;
+  }
+  if (value === null) { delete state[root][sub]; return; }
+  const cur = state[root][sub];
+  const mergeable = typeof cur === "object" && cur !== null && !Array.isArray(cur)
+    && typeof value === "object" && value !== null && !Array.isArray(value);
+  state[root][sub] = mergeable ? { ...cur, ...value } : value;
+}
+
+/** Keep `notes` under CAPS.NOTES by evicting whole lines from the FRONT — the tail is the recent
+ *  half, and a mid-string elision is #6528, the failure this whole schema exists to prevent. */
+function capNotes(notes) {
+  if (Buffer.byteLength(notes, "utf8") <= CAPS.NOTES) return notes;
+  const lines = notes.split("\n");
+  while (lines.length > 1 && Buffer.byteLength(lines.join("\n"), "utf8") > CAPS.NOTES) lines.shift();
+  let out = lines.join("\n");
+  while (out.length && Buffer.byteLength(out, "utf8") > CAPS.NOTES) out = out.slice(1);
+  return out;
+}
+
+/**
+ * The five-stage pipeline. `turn` is the TurnResult `{ patch, action }` — §4.8's driver snippet
+ * calls this slot `patch`, which is the same object under a shorter name.
+ *
+ * ctx: { now, by, verify, files, gate_attempted, gate }
+ *   - `verify` and `files` are harness facts from a gate that actually ran, never testimony.
+ *   - `gate_attempted` splits NEEDS_GATE from UNVERIFIED_DONE (§4.8).
+ *   - `gate` is the memo record runGate returned, written to ext._gate here so it lands through
+ *     the single apply point rather than as a side effect somewhere else.
+ *
+ * @returns {{ ok: true, state: object, promoted: object[] }
+ *          | { ok: false, code: string, at: string, message: string }}
+ */
+export function applyTurn(state, turn, ctx = {}) {
+  const v = validateTurn(state, turn, ctx);
+  if (!v.ok) return v;
+
+  // ---- stage 4: apply, in order, on a structural clone ----
+  const next = cloneState(state);
+  for (const op of v.ops) {
+    if (op.set) { setField(next, op.set.field, op.set.value); continue; }
+    if (op.add) { next[op.add.list].push(op.add.item); continue; }
+    if (op.remove) {
+      next[op.remove.list] = next[op.remove.list].filter(i => i.id !== op.remove.id);
+      continue;
+    }
+    const { id, from, to } = op.move;
+    const at = next[from].findIndex(i => i.id === id);
+    const [item] = next[from].splice(at, 1);
+    next[to].push(item);
+  }
+
+  // ---- stage 5: the runtime pass. Not model-visible, not model-writable. ----
+
+  // `verify` is REWRITTEN wholesale, never merged: it describes the gate that ran THIS turn, or
+  // nothing. That is what makes "evidence at the current rev" enforceable without a rev stamp on
+  // every field (§4.2).
+  next.verify = ctx.verify && typeof ctx.verify === "object" ? { ...ctx.verify } : {};
+
+  // Harness file facts: tier 1 sets `touched` from git, the gate sets `verified` + `hash`, and
+  // tier 1 EXPIRES a credit whose bytes have moved (R12). Setting evidence is the gate's
+  // privilege; expiring it belongs to the only thing that runs every turn.
+  for (const [path, fact] of Object.entries(ctx.files || {})) {
+    const cur = next.files[path] || { touched: false, verified: false };
+    const merged = { ...cur };
+    if (fact.touched !== undefined) merged.touched = fact.touched;
+    if (fact.verified !== undefined) merged.verified = fact.verified;
+    if (fact.blast_radius !== undefined) merged.blast_radius = fact.blast_radius;
+    if (fact.hash !== undefined) merged.hash = fact.hash;
+    if (merged.verified === false) delete merged.hash;
+    next.files[path] = merged;
+  }
+
+  if (ctx.gate && typeof ctx.gate === "object") next.ext._gate = { ...ctx.gate };
+  if (ctx.promoted !== undefined) next.ext._promoted = ctx.promoted;
+
+  // ---- compaction: history compacts, working lists never reach here (they were rejected) ----
+  for (const list of COMPACTING_LISTS) {
+    if (next[list].length > CAPS.LIST) {
+      const overflow = next[list].length - CAPS.LIST;
+      next[list] = next[list].slice(overflow);
+      if (list === "done") next.done_count += overflow;
+    }
+  }
+  next.done_count = Math.max(next.done_count, 0);
+  const paths = Object.keys(next.files);
+  if (paths.length > CAPS.FILES) {
+    // Drop the least interesting first: untouched and uncredited paths carry no evidence.
+    const rank = (p) => (next.files[p].verified ? 2 : next.files[p].touched ? 1 : 0);
+    const doomed = paths.sort((a, b) => rank(a) - rank(b)).slice(0, paths.length - CAPS.FILES);
+    for (const p of doomed) delete next.files[p];
+    next.files_count += doomed.length;
+  }
+
+  // ---- cap enforcement on content ----
+  next.task = next.task.slice(0, CAPS.TASK);
+  next.notes = capNotes(next.notes);
+  const extKeys = Object.keys(next.ext).filter(k => !RUNTIME_EXT_KEYS.includes(k));
+  for (const k of extKeys.slice(CAPS.EXT_KEYS)) delete next.ext[k];
+  let extBytes = Buffer.byteLength(JSON.stringify(
+    Object.fromEntries(Object.entries(next.ext).filter(([k]) => !RUNTIME_EXT_KEYS.includes(k))),
+  ), "utf8");
+  for (const k of extKeys.slice(0, CAPS.EXT_KEYS).reverse()) {
+    if (extBytes <= CAPS.EXT_BYTES) break;
+    extBytes -= Buffer.byteLength(JSON.stringify({ [k]: next.ext[k] }), "utf8");
+    delete next.ext[k];
+  }
+
+  next.cursor = {
+    turn: state.cursor.turn + 1,
+    ts: Number.isInteger(ctx.now) ? ctx.now : state.cursor.ts,
+    by: typeof ctx.by === "string" ? ctx.by : state.cursor.by,
+  };
+  next.rev = state.rev + 1;
+
+  return { ok: true, state: next, promoted: promotionPlan(state, next) };
+}
+
+/**
+ * The delta the board is allowed to see (TDD §4.7): what shipped, what is blocking, what the
+ * evidence says. `in_flight`/`next` are scratch and promote nothing — that churn is #6669's
+ * lesson. The promoter (P3) composes these into at most one card note per turn.
+ * @returns {{ kind: string, text: string }[]}
+ */
+export function promotionPlan(before, after) {
+  const out = [];
+  const wasDone = new Set(before.done.map(i => i.id));
+  for (const item of after.done) {
+    if (wasDone.has(item.id)) continue;
+    const ev = item.paths?.length ? ` (${item.paths.join(", ")})` : "";
+    out.push({ kind: "done", text: `${item.text}${ev}` });
+  }
+  const wasBlocked = new Map(before.blockers.map(i => [i.id, i]));
+  for (const item of after.blockers) {
+    if (!wasBlocked.has(item.id)) out.push({ kind: "blocker_added", text: item.text });
+  }
+  const nowBlocked = new Set(after.blockers.map(i => i.id));
+  for (const item of before.blockers) {
+    if (!nowBlocked.has(item.id)) out.push({ kind: "blocker_cleared", text: item.text });
+  }
+  for (const field of ["built", "tested", "observed"]) {
+    if (after.verify[field] === true && before.verify[field] !== true) {
+      const cmd = after.verify.cmd ? ` — ${after.verify.cmd}` : "";
+      out.push({ kind: "verify", text: `${field}${cmd}` });
+    }
+  }
+  return out;
+}
+
+/** Every id currently in the state, for the "arrays change only by id" property. */
+export function allIds(state) {
+  return LISTS.flatMap(l => state[l].map(i => i.id));
+}

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/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);
+}