@tacuchi/agent-workflow-cli 22.4.2 → 24.0.0

package/dist/domain/flow/run-state.js

@@ -24,6 +24,8 @@
 import { WORKLINE_FLOWS } from "../../application/capability/compose.js";
 import { canonicalJson, semanticDigest } from "../../application/semantic-operation/protocol.js";
 import { isEffectClass, touchesTheWorld } from "../capability/effects.js";
+import { AttemptLedger } from "../capability/protocol.js";
+import { validateDecisionNote } from "../decision-note.js";
 /**
  * The version this CLI WRITES. Every state it persists carries it.
  *
@@ -35,21 +37,17 @@ import { isEffectClass, touchesTheWorld } from "../capability/effects.js";
  * turning the cap off in silence while somebody alternates CLI versions over one
  * run. Failing with a cause is the requirement; failing silently is the defect.
  */
-export const FLOW_RUN_STATE_VERSION = 9;
+export const FLOW_RUN_STATE_VERSION = 10;
 /**
  * The versions this CLI READS, newest first.
  *
- * Three, and none of the older two is a migration: every field versions 8 and 9
- * added is OPTIONAL and its absence is the conservative reading — no floor
- * beyond the ledger, nothing forgiven, no degradation declared, nothing owed
- * recorded. So a run written before them is read exactly as it always was, keeps
- * walking, and is re-stamped current by its first write. Refusing it instead
- * would strand runs that were mid-journey when the CLI was upgraded, which is
- * the compatibility the spec demands; inventing values for the missing fields
- * would be the fabrication the version gate exists to refuse. Neither happens
- * here.
- */
-export const FLOW_RUN_STATE_READABLE = [FLOW_RUN_STATE_VERSION, 8, 7];
+ * Versions 9, 8 and 7 remain readable for status, recovery evidence and an
+ * explicit adoption. They are NOT writable execution state: v10 records batches
+ * and their append-only iteration trace, so continuing an old cursor by merely
+ * changing `version` would invent a batch boundary the old run never declared.
+ * An active legacy run must be adopted explicitly before any mutation.
+ */
+export const FLOW_RUN_STATE_READABLE = [FLOW_RUN_STATE_VERSION, 9, 8, 7];
 /** The CLI-owned run state inside the session folder. Machine-local, dotted. */
 export const FLOW_RUN_STATE_FILE = ".flow-run.json";
 /**
@@ -81,13 +79,116 @@ export const MAX_BOUNDARY_ATTEMPTS = 3;
  * as a reason to refuse a run that was walking fine.
  */
 export function attemptsAt(state, transition) {
-    const spent = state.attempts.filter((attempt) => attempt.transition === transition).length;
-    const floor = state.attempt_floor?.[transition] ?? 0;
-    const granted = state.attempt_grants?.[transition] ?? 0;
-    return Math.max(0, Math.max(spent, floor) - granted);
+    return spendAt(state, transition).spent;
+}
+/** The monotone-counter key for one boundary, scoped when that boundary repeats in a batch. */
+export function attemptCounterKey(state, transition) {
+    const iteration = currentBatchIteration(state, transition);
+    return attemptCounterKeyForIteration(transition, iteration ?? undefined);
+}
+/** Stable counter key for a historical attempt whose batch iteration is recorded on the row. */
+export function attemptCounterKeyForIteration(transition, iteration) {
+    return iteration === undefined ? transition : `${transition}@batch-${iteration}`;
+}
+/**
+ * The three numbers and the difference between them, computed once.
+ *
+ * Kept apart from {@link attemptAccountingAt} so the cap check stays what it was
+ * — three lookups and a subtraction — while the richer reading built on top does
+ * not restate the arithmetic. Two copies of this formula is exactly how the
+ * directive and the recovery guard would end up disagreeing about the same run.
+ */
+function spendAt(state, transition) {
+    const iteration = currentBatchIteration(state, transition);
+    const rows = state.attempts.filter((attempt) => attempt.transition === transition &&
+        (iteration === null
+            ? attempt.batch_iteration === undefined
+            : attempt.batch_iteration === iteration));
+    const key = attemptCounterKey(state, transition);
+    const floor = state.attempt_floor?.[key] ?? 0;
+    const granted = state.attempt_grants?.[key] ?? 0;
+    return { rows, floor, granted, spent: Math.max(0, Math.max(rows.length, floor) - granted) };
+}
+/**
+ * The whole accounting of one transition, conflicts named and answerability read.
+ *
+ * The one reading the engine, the directive and the recovery guard share.
+ */
+export function attemptAccountingAt(state, transition) {
+    const { rows, floor: read, granted, spent } = spendAt(state, transition);
+    // The floor the FILE will hold, not the one this invocation happened to read.
+    // `raiseCounters` lifts it to at least the row count on every write, so the
+    // pre-raise value left the directive reporting a floor one write behind itself
+    // — and a projection that disagrees with the state it describes is the very
+    // thing this reading exists to stop. It cannot mask a real divergence: a
+    // counter that runs AHEAD of the rows stays ahead of this maximum.
+    const floor = Math.max(read, rows.length);
+    const ordinals = rows.map((attempt) => attempt.attempt);
+    const conflicts = [];
+    if (floor > rows.length) {
+        conflicts.push({
+            between: [
+                { name: "attempt_floor", value: floor },
+                { name: "attempts", value: rows.length },
+            ],
+            cause: "el contador monótono declara más intentos que las filas persistidas: o se restauró una copia anterior del ledger, o una escritura murió entre el contador y el estado",
+        });
+    }
+    if (granted > Math.max(rows.length, floor)) {
+        conflicts.push({
+            between: [
+                { name: "attempt_grants", value: granted },
+                { name: "attempts", value: Math.max(rows.length, floor) },
+            ],
+            cause: "se perdonan más intentos de los que esta transición llegó a registrar",
+        });
+    }
+    const highest = ordinals.length === 0 ? 0 : Math.max(...ordinals);
+    if (highest !== rows.length) {
+        conflicts.push({
+            between: [
+                { name: "attempts[].attempt", value: highest },
+                { name: "attempts", value: rows.length },
+            ],
+            cause: "el ordinal más alto que las filas declaran no coincide con cuántas filas hay: la cadena tiene un hueco, un número repetido, o se reinició bajo otro sello",
+        });
+    }
+    return {
+        transition,
+        rows: rows.length,
+        floor,
+        granted,
+        spent,
+        available: Math.max(0, MAX_BOUNDARY_ATTEMPTS - spent),
+        ordinals,
+        conflicts,
+        unanswerable: unanswerableAt(state),
+    };
+}
+/**
+ * The refusal a submit would hit replaying this run's own history, or `null`.
+ *
+ * The ledger validates ordinals keyed by the boundary SEAL rather than by
+ * transition, so the question cannot be asked about one transition in isolation:
+ * it is asked the way `submit` asks it, by replaying every row the run persisted.
+ * A failed replay is not a prediction — it is the same failure the next submit
+ * returns, produced before anybody pays an attempt to discover it.
+ */
+function unanswerableAt(state) {
+    const ledger = new AttemptLedger();
+    for (const past of state.attempts) {
+        const replay = ledger.record(past);
+        if (!replay.ok)
+            return replay.failure;
+    }
+    return null;
 }
 export function recoveryBlockedAt(state, transition) {
-    const trace = state.events.filter((event) => event.transition === transition);
+    const iteration = currentBatchIteration(state, transition);
+    const trace = state.events.filter((event) => event.transition === transition &&
+        (iteration === null
+            ? event.batch_iteration === undefined
+            : event.batch_iteration === iteration));
     const material = [...trace].reverse().find(declaresMaterialEffect);
     if (material !== undefined)
         return { reason: "materialized", event: material };
@@ -134,6 +235,19 @@ export function positionDigest(state) {
     const { attempts: _spent, attempt_floor: _floor, attempt_grants: _granted, digest: _seal, ...position } = state;
     return semanticDigest(position);
 }
+/** The bounded lifecycle of one repeatable plan-execution batch. */
+export const PLAN_EXEC_BATCH_STAGES = [
+    "inferred",
+    "isolated",
+    "implementing",
+    "deviation",
+    "validating",
+    "reviewing",
+    "closed",
+    "committing",
+    "integrating",
+    "done",
+];
 /** The state minus its own seal — exactly what {@link sealRunState} digests. */
 function withoutSeal(state) {
     const { digest: _seal, ...rest } = state;
@@ -158,6 +272,12 @@ export function newRunState(flow, session) {
         proposal: null,
         effects: { planned: [], approved: [], applied: [] },
         attempts: [],
+        batches: [],
+        batch_trace: [],
+        batch_loop: { pending: true, iteration: 1 },
+        handoff: null,
+        selected_choice: null,
+        decision_preparation: null,
     });
 }
 /**
@@ -223,25 +343,257 @@ export function degradeTransition(state, decisionId, cause) {
  * were forgiven, which only ever grows; the effective count is the difference.
  * See {@link attemptsAt}.
  */
+/**
+ * Relabel the attempt chain so the ledger accepts it again — losing no row.
+ *
+ * The ledger validates ordinals per boundary SEAL: contiguous from 1, each row
+ * linked to the digest of the one before it. A run whose chain was broken by an
+ * older build of this very CLI — the recovery that rewound `attempts` and then
+ * appended a duplicate — stays readable and keeps every fact worth keeping, but
+ * every future submit dies on the replay. Renumbering is the smallest repair that
+ * makes it answerable: the rows, their digests and their seals all survive in the
+ * order they happened, and only the LABELS are made consistent with that order.
+ *
+ * It is not a way around the cap, which is the reason it is safe to do at all:
+ * the monotone floor and the grants are untouched here, so what the boundary has
+ * already spent is exactly what it spent before. And it is not a repair of a
+ * TAMPERED ledger either — the seal is verified before anything gets this far.
+ */
+export function normalizeAttemptChain(state) {
+    const ordinal = new Map();
+    const previous = new Map();
+    const attempts = state.attempts.map((row) => {
+        const next = (ordinal.get(row.invocation_id) ?? 0) + 1;
+        ordinal.set(row.invocation_id, next);
+        const parent = next === 1 ? null : (previous.get(row.invocation_id) ?? null);
+        previous.set(row.invocation_id, row.request_digest);
+        return { ...row, attempt: next, parent_request_digest: parent };
+    });
+    return sealRunState({ ...withoutSeal(state), attempts });
+}
 export function grantAttempts(state, transition, attempts) {
     const granted = { ...(state.attempt_grants ?? {}) };
-    granted[transition] = (granted[transition] ?? 0) + attempts;
+    const key = attemptCounterKey(state, transition);
+    granted[key] = (granted[key] ?? 0) + attempts;
     return sealRunState({ ...withoutSeal(state), attempt_grants: granted });
 }
 /**
- * Stamp a state read from an older readable version with the current one.
+ * Explicitly adopt a readable legacy state into v10.
  *
- * Applied on the way OUT of the reader, so the run walks — and is written back —
- * as one format from the first read onwards, and the version stops being a fact
- * that varies per file within one workspace. Nothing else is touched: the older
- * versions this build reads differ from the current one only by fields whose
- * absence is already the conservative reading, so there is nothing to fill in
- * and nothing is filled in. Re-sealed because the version is inside the seal.
+ * This function is intentionally NOT called by the reader. Calling it is the
+ * durable act of adoption after the caller has named the flow and accepted that
+ * no pre-v10 batch is being reconstructed. Empty batch arrays mean exactly
+ * "legacy history preserved; no v10 batch claimed", never "the old run had no
+ * batches".
  */
 export function atCurrentVersion(state) {
     if (state.version === FLOW_RUN_STATE_VERSION)
         return state;
-    return sealRunState({ ...withoutSeal(state), version: FLOW_RUN_STATE_VERSION });
+    return sealRunState({
+        ...withoutSeal(state),
+        version: FLOW_RUN_STATE_VERSION,
+        batches: [],
+        batch_trace: [],
+        batch_loop: { pending: true, iteration: 1 },
+        handoff: null,
+        selected_choice: null,
+        decision_preparation: null,
+    });
+}
+/** Whether a parsed state needs the explicit adoption boundary before mutation. */
+export function legacyRunNeedsAdoption(state) {
+    return state.version !== FLOW_RUN_STATE_VERSION;
+}
+/** Record one inferred or declared batch, refusing duplicate ids at the caller's boundary. */
+export function withPlanExecBatch(state, batch) {
+    const batches = state.batches ?? [];
+    if (batches.some((current) => current.id === batch.id))
+        return state;
+    const trace = state.batch_trace ?? [];
+    return sealRunState({
+        ...withoutSeal(state),
+        batches: [...batches, batch],
+        batch_trace: [
+            ...trace,
+            {
+                sequence: trace.length + 1,
+                batch_id: batch.id,
+                iteration: batch.iteration,
+                stage: "inferred",
+                transition: "plan-exec.batch-inference",
+                kind: "entered",
+            },
+        ],
+    });
+}
+/** Advance one batch phase and append the evidence row in the same sealed state. */
+export function withPlanExecBatchStage(state, batchId, stage, transition, kind = "completed") {
+    const batches = state.batches ?? [];
+    const index = batches.findIndex((batch) => batch.id === batchId);
+    if (index < 0)
+        return state;
+    const current = batches[index];
+    if (current === undefined)
+        return state;
+    const nextBatches = [...batches];
+    nextBatches[index] = { ...current, stage };
+    const trace = state.batch_trace ?? [];
+    const entry = {
+        sequence: trace.length + 1,
+        batch_id: current.id,
+        iteration: current.iteration,
+        stage,
+        transition,
+        kind,
+    };
+    return sealRunState({
+        ...withoutSeal(state),
+        batches: nextBatches,
+        batch_trace: [...trace, entry],
+    });
+}
+/**
+ * Record the lifecycle evidence a real PLAN-exec boundary just crossed.
+ *
+ * The batch itself is sealed at `batch-inference`, before implementation. Later
+ * transitions do not re-infer it; they only append the stage that the cursor
+ * actually reached. The small mapping lives beside the state shape so CLI walks,
+ * submitted execution results and internal actions cannot drift into three
+ * different notions of "the current batch".
+ */
+const PLAN_EXEC_BATCH_STAGE_BY_TRANSITION = {
+    "plan-exec.batch-isolation": "isolated",
+    "plan-exec.implementation": "implementing",
+    "plan-exec.deviation-recognition": "deviation",
+    "plan-exec.validation-execution": "validating",
+    "plan-exec.review-findings": "reviewing",
+    // These only occur after the final batch publication. They therefore extend
+    // the last closed batch's trace instead of fabricating a new one for Git/done.
+    "plan-exec.final-validation": "validating",
+    "plan-exec.commit-execution": "committing",
+    "plan-exec.unit-integration": "integrating",
+    "plan-exec.plan-done": "done",
+};
+const PLAN_EXEC_TERMINAL_BATCH_TRANSITIONS = new Set([
+    "plan-exec.final-validation",
+    "plan-exec.commit-execution",
+    "plan-exec.unit-integration",
+    "plan-exec.plan-done",
+]);
+/** Append the stage for a crossed batch boundary, if that boundary owns one. */
+export function withPlanExecBatchStageForTransition(state, transition) {
+    if (state.flow !== "plan-exec")
+        return state;
+    const stage = PLAN_EXEC_BATCH_STAGE_BY_TRANSITION[transition];
+    if (stage === undefined)
+        return state;
+    const reverse = [...(state.batches ?? [])].reverse();
+    const current = PLAN_EXEC_TERMINAL_BATCH_TRANSITIONS.has(transition)
+        ? reverse.find((batch) => batch.published_plan_digest !== undefined)
+        : reverse.find((batch) => batch.published_plan_digest === undefined);
+    if (current === undefined)
+        return state;
+    const last = state.batch_trace?.at(-1);
+    if (current.stage === stage && last?.batch_id === current.id && last.transition === transition) {
+        return state;
+    }
+    return withPlanExecBatchStage(state, current.id, stage, transition, "completed");
+}
+/**
+ * Seal whether the just-published batch opens another iteration.
+ *
+ * The final document bytes, not an agent assertion, decide this field.  Keeping
+ * it in the same state publication as the `closed` trace makes a crash recover
+ * to one exact cursor shape.
+ */
+export function withPlanExecBatchLoop(state, loop) {
+    const current = state.batch_loop;
+    if (current?.pending === loop.pending && current?.iteration === loop.iteration)
+        return state;
+    return sealRunState({ ...withoutSeal(state), batch_loop: loop });
+}
+/**
+ * The iteration identity for a transition in the repeatable PLAN-exec segment.
+ *
+ * Prefix/tail rows deliberately return `null`: they run once per flow and keep
+ * their historical retry/observation identity.  The loop field is absent on an
+ * older v10 state, in which case preserving its old unscoped accounting is safer
+ * than pretending we know which historical batch it belonged to.
+ */
+export function currentBatchIteration(state, transition) {
+    if (state.flow !== "plan-exec" || !PLAN_EXEC_BATCH_LOOP_TRANSITIONS.has(transition))
+        return null;
+    const loop = state.batch_loop;
+    return loop?.pending === true && loop.iteration !== null ? loop.iteration : null;
+}
+/** The rows that repeat between batch closures; kept local to the state contract. */
+export const PLAN_EXEC_BATCH_LOOP_TRANSITIONS = new Set([
+    "plan-exec.batch-eligibility-signal",
+    "plan-exec.batch-inference",
+    "plan-exec.batch-isolation",
+    "plan-exec.design-precondition",
+    "plan-exec.unit-acquisition",
+    "plan-exec.branch-precondition",
+    "plan-exec.implementation",
+    "plan-exec.deviation-recognition",
+    "plan-exec.deviation-eligibility",
+    "plan-exec.deviation-gate",
+    "plan-exec.escalation-package",
+    "plan-exec.validation-execution",
+    "plan-exec.deferred-check",
+    "plan-exec.review-findings",
+    "plan-exec.batch-close",
+]);
+/** Seal the plan bytes the batch publication actually produced. */
+export function withPlanExecBatchPublication(state, batchId, publishedPlanDigest) {
+    const batches = state.batches ?? [];
+    const index = batches.findIndex((batch) => batch.id === batchId);
+    if (index < 0)
+        return state;
+    const current = batches[index];
+    if (current === undefined)
+        return state;
+    const next = [...batches];
+    const publication = current.publication === undefined
+        ? {}
+        : {
+            publication: {
+                ...current.publication,
+                after_plan_digest: publishedPlanDigest,
+                status: "applied",
+            },
+        };
+    next[index] = {
+        ...current,
+        published_plan_digest: publishedPlanDigest,
+        ...publication,
+    };
+    return sealRunState({ ...withoutSeal(state), batches: next });
+}
+/** Seal the exact before/after pair before the plan document is touched. */
+export function withPlanExecBatchPublicationPrepared(state, batchId, publication) {
+    const batches = state.batches ?? [];
+    const index = batches.findIndex((batch) => batch.id === batchId);
+    if (index < 0)
+        return state;
+    const current = batches[index];
+    if (current === undefined)
+        return state;
+    const next = [...batches];
+    next[index] = { ...current, publication: { ...publication, status: "prepared" } };
+    return sealRunState({ ...withoutSeal(state), batches: next });
+}
+/** Persist a selected handoff; the advancement engine then refuses to continue this run. */
+export function withHandoff(state, handoff) {
+    return sealRunState({ ...withoutSeal(state), handoff });
+}
+/** Persist the gate's executable consequence before the run leaves that boundary. */
+export function withSelectedChoice(state, selected) {
+    return sealRunState({ ...withoutSeal(state), selected_choice: selected });
+}
+/** Persist or clear the exact decision view offered at the human gate. */
+export function withDecisionPreparation(state, preparation) {
+    return sealRunState({ ...withoutSeal(state), decision_preparation: preparation });
 }
 /**
  * Reconcile the state with the monotone counter that lives outside its seal.
@@ -329,6 +681,7 @@ export function restatesLastEvent(state, event) {
     if (last === undefined || last.kind !== "failed" || event.kind !== "failed")
         return false;
     return (last.transition === event.transition &&
+        last.batch_iteration === event.batch_iteration &&
         last.code === event.code &&
         last.message === event.message);
 }
@@ -348,7 +701,9 @@ export function restatesLastEvent(state, event) {
  * into a retry counter, which is what the attempt history is for.
  */
 export function withObservation(state, observation) {
-    const repeated = state.observations.some((past) => past.transition === observation.transition && sameSignals(past.signals, observation.signals));
+    const repeated = state.observations.some((past) => past.transition === observation.transition &&
+        past.batch_iteration === observation.batch_iteration &&
+        sameSignals(past.signals, observation.signals));
     if (repeated)
         return state;
     return sealRunState({
@@ -552,6 +907,20 @@ function checkShape(parsed) {
  * digest matches.
  */
 function checkRecordShape(parsed, invalid) {
+    const common = checkCommonRecordShape(parsed, invalid);
+    if (common !== null)
+        return common;
+    if (parsed.version === FLOW_RUN_STATE_VERSION) {
+        const v10 = checkV10RecordShape(parsed, invalid);
+        if (v10 !== null)
+            return v10;
+    }
+    if (typeof parsed.digest !== "string")
+        return invalid("no trae su sello");
+    return null;
+}
+/** Record fields shared by every readable flow-run version, in refusal order. */
+function checkCommonRecordShape(parsed, invalid) {
     if (!isPendingAction(parsed.pending_action)) {
         return invalid("declara una acción pendiente sin transición o sin sello");
     }
@@ -583,8 +952,28 @@ function checkRecordShape(parsed, invalid) {
     if (!isCounterMap(parsed.attempt_floor) || !isCounterMap(parsed.attempt_grants)) {
         return invalid("trae una contabilidad de intentos que no es un contador por transición");
     }
-    if (typeof parsed.digest !== "string")
-        return invalid("no trae su sello");
+    return null;
+}
+/** Fields added by v10 that have no truthful default on a persisted run. */
+function checkV10RecordShape(parsed, invalid) {
+    if (!isPlanExecBatchArray(parsed.batches)) {
+        return invalid("no trae batches v10 con fases, tareas y sello de plan");
+    }
+    if (!isPlanExecBatchTraceArray(parsed.batch_trace, parsed.batches)) {
+        return invalid("trae una traza de batches que no es append-only ni corresponde a sus iteraciones");
+    }
+    if (!isPlanExecBatchLoop(parsed.batch_loop)) {
+        return invalid("declara un ciclo de batches sin su próxima iteración sellada");
+    }
+    if (!isHandoff(parsed.handoff)) {
+        return invalid("declara una entrega de flow sin destino, comando o sello de paquete");
+    }
+    if (!isSelectedChoice(parsed.selected_choice)) {
+        return invalid("declara una consecuencia elegida sin frontera, etiqueta o ruta válida");
+    }
+    if (!isDecisionPreparation(parsed.decision_preparation)) {
+        return invalid("declara una vista de decisión sin nota, preview o linaje sellados");
+    }
     return null;
 }
 function refuse(code, message, action) {
@@ -633,6 +1022,212 @@ function isScope(value) {
         return false;
     return value.sources.every((alias) => alias.trim().length > 0);
 }
+function isPlanExecBatchArray(value) {
+    if (!Array.isArray(value))
+        return false;
+    const ids = new Set();
+    const iterations = new Set();
+    return value.every((entry) => {
+        if (!isRecord(entry))
+            return false;
+        if (typeof entry.id !== "string" ||
+            entry.id.trim().length === 0 ||
+            ids.has(entry.id) ||
+            typeof entry.iteration !== "number" ||
+            !Number.isInteger(entry.iteration) ||
+            entry.iteration < 1 ||
+            iterations.has(entry.iteration) ||
+            (entry.mode !== "continuous" && entry.mode !== "isolated") ||
+            !Array.isArray(entry.phases) ||
+            entry.phases.length === 0 ||
+            !entry.phases.every((phase) => typeof phase === "number" && Number.isInteger(phase) && phase > 0) ||
+            !isStringArray(entry.tasks) ||
+            entry.tasks.length === 0 ||
+            new Set(entry.tasks).size !== entry.tasks.length ||
+            typeof entry.plan_digest !== "string" ||
+            entry.plan_digest.length === 0 ||
+            (entry.published_plan_digest !== undefined &&
+                (typeof entry.published_plan_digest !== "string" ||
+                    entry.published_plan_digest.length === 0)) ||
+            !isPlanExecBatchPublication(entry.publication) ||
+            (entry.publication !== undefined &&
+                entry.publication.status === "applied" &&
+                entry.published_plan_digest !== entry.publication.after_plan_digest) ||
+            !PLAN_EXEC_BATCH_STAGES.includes(entry.stage)) {
+            return false;
+        }
+        ids.add(entry.id);
+        iterations.add(entry.iteration);
+        return true;
+    });
+}
+function isPlanExecBatchPublication(value) {
+    if (value === undefined)
+        return true;
+    return (isRecord(value) &&
+        typeof value.plan === "string" &&
+        value.plan.trim().length > 0 &&
+        typeof value.before_plan_digest === "string" &&
+        value.before_plan_digest.length > 0 &&
+        typeof value.after_plan_digest === "string" &&
+        value.after_plan_digest.length > 0 &&
+        typeof value.transition === "string" &&
+        value.transition.length > 0 &&
+        (value.status === "prepared" || value.status === "applied"));
+}
+/** Absent is only the compatibility reading of a v10 file written before the loop cursor. */
+function isPlanExecBatchLoop(value) {
+    if (value === undefined)
+        return true;
+    if (!isRecord(value) || typeof value.pending !== "boolean")
+        return false;
+    if (value.pending)
+        return Number.isInteger(value.iteration) && value.iteration >= 1;
+    return value.iteration === null;
+}
+function isPlanExecBatchTraceArray(value, batches) {
+    if (!Array.isArray(value) || !Array.isArray(batches))
+        return false;
+    const byId = new Map(batches.map((batch) => [batch.id, batch.iteration]));
+    return value.every((entry, index) => {
+        if (!isRecord(entry))
+            return false;
+        return (entry.sequence === index + 1 &&
+            typeof entry.batch_id === "string" &&
+            byId.get(entry.batch_id) === entry.iteration &&
+            typeof entry.iteration === "number" &&
+            Number.isInteger(entry.iteration) &&
+            typeof entry.transition === "string" &&
+            entry.transition.length > 0 &&
+            PLAN_EXEC_BATCH_STAGES.includes(entry.stage) &&
+            (entry.kind === "entered" || entry.kind === "completed" || entry.kind === "blocked"));
+    });
+}
+function isHandoff(value) {
+    if (value === null)
+        return true;
+    if (!isRecord(value))
+        return false;
+    return ((value.destination === "plan-refine" ||
+        value.destination === "spec-refine" ||
+        value.destination === "spec-new") &&
+        typeof value.command === "string" &&
+        value.command.trim().length > 0 &&
+        isEscalationPackage(value.package) &&
+        typeof value.package_digest === "string" &&
+        value.package_digest === semanticDigest(value.package));
+}
+function isEscalationPackage(value) {
+    return (isRecord(value) &&
+        (value.plan === null || (typeof value.plan === "string" && value.plan.trim().length > 0)) &&
+        isObservationArray(value.observations) &&
+        isRecord(value.decisions) &&
+        isJsonValue(value.decisions) &&
+        typeof value.selection === "string" &&
+        value.selection.trim().length > 0);
+}
+function isJsonValue(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJsonValue);
+    return isRecord(value) && Object.values(value).every(isJsonValue);
+}
+function isSelectedChoice(value) {
+    if (value === null)
+        return true;
+    if (!isRecord(value) || typeof value.transition !== "string" || typeof value.label !== "string") {
+        return false;
+    }
+    if (!isRecord(value.outcome))
+        return false;
+    return (value.outcome.kind === "register-decision" ||
+        (value.outcome.kind === "handoff" &&
+            (value.outcome.destination === "plan-refine" ||
+                value.outcome.destination === "spec-refine" ||
+                value.outcome.destination === "spec-new")));
+}
+/** A v10 file written before preview persistence may omit this field. */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: each discriminant validates one durable preparation variant.
+function isDecisionPreparation(value) {
+    if (value === undefined || value === null)
+        return true;
+    if (!isRecord(value) || typeof value.kind !== "string")
+        return false;
+    if (value.kind === "settled")
+        return typeof value.decision === "string" && value.decision.trim().length > 0;
+    if (value.kind === "reused") {
+        return (typeof value.note === "string" &&
+            value.note.trim().length > 0 &&
+            typeof value.decision === "string" &&
+            value.decision.trim().length > 0 &&
+            typeof value.resume_point === "string" &&
+            value.resume_point.trim().length > 0);
+    }
+    if (value.kind !== "prepared" || !isRecord(value.baseline))
+        return false;
+    const baseline = value.baseline;
+    if (typeof baseline.path !== "string" ||
+        baseline.path.trim().length === 0 ||
+        typeof baseline.number !== "string" ||
+        baseline.number.trim().length === 0 ||
+        typeof baseline.digest !== "string" ||
+        baseline.digest.trim().length === 0 ||
+        !isStringArray(baseline.criteria) ||
+        typeof value.index_path !== "string" ||
+        value.index_path.trim().length === 0) {
+        return false;
+    }
+    const checkedBaseline = {
+        path: baseline.path,
+        number: baseline.number,
+        digest: baseline.digest,
+    };
+    const note = validateDecisionNote(value.note);
+    if (!note.ok || note.value === null)
+        return false;
+    if (note.value.lineage.spec.path !== checkedBaseline.path ||
+        note.value.lineage.spec.number !== checkedBaseline.number ||
+        note.value.lineage.spec.digest !== checkedBaseline.digest) {
+        return false;
+    }
+    return isDecisionPreview(value.preview, checkedBaseline);
+}
+function isDecisionPreview(value, baseline) {
+    if (!isRecord(value) ||
+        !isRecord(value.baseline) ||
+        !isRecord(value.impact) ||
+        !isRecord(value.evidence)) {
+        return false;
+    }
+    const previewBaseline = value.baseline;
+    if (previewBaseline.path !== baseline.path ||
+        previewBaseline.number !== baseline.number ||
+        previewBaseline.digest !== baseline.digest ||
+        !Array.isArray(value.effective_change) ||
+        !isStringArray(value.consumers) ||
+        !isStringArray(value.obligations) ||
+        typeof value.resume_point !== "string" ||
+        value.resume_point.trim().length === 0 ||
+        !isStringArray(value.evidence.preserved) ||
+        !isStringArray(value.evidence.invalidated) ||
+        typeof value.impact.scope !== "string" ||
+        (value.impact.scope !== "functional" && value.impact.scope !== "plan-only") ||
+        !Number.isInteger(value.impact.assertions) ||
+        !Number.isInteger(value.impact.consumers) ||
+        !isRecord(value.effects) ||
+        !isEffectClassArray(value.effects.classes) ||
+        !Array.isArray(value.effects.entries) ||
+        !isProposal(value.proposal)) {
+        return false;
+    }
+    return value.effects.entries.every((entry) => isRecord(entry) &&
+        typeof entry.path === "string" &&
+        Number.isInteger(entry.bytes) &&
+        typeof entry.overwrite === "boolean");
+}
 function isProposal(value) {
     if (value === null)
         return true;
@@ -694,8 +1289,12 @@ function isEventArray(value) {
     return value.every((entry) => {
         if (!isRecord(entry))
             return false;
-        if (typeof entry.transition !== "string" || typeof entry.operation !== "string")
+        if (typeof entry.transition !== "string" ||
+            typeof entry.operation !== "string" ||
+            (entry.batch_iteration !== undefined &&
+                (!Number.isInteger(entry.batch_iteration) || entry.batch_iteration < 1))) {
             return false;
+        }
         if (entry.kind === "executed") {
             return (typeof entry.summary === "string" &&
                 typeof entry.output_digest === "string" &&
@@ -716,7 +1315,11 @@ function isEventArray(value) {
 function isObservationArray(value) {
     if (!Array.isArray(value))
         return false;
-    return value.every((entry) => isRecord(entry) && typeof entry.transition === "string" && isStringArray(entry.signals));
+    return value.every((entry) => isRecord(entry) &&
+        typeof entry.transition === "string" &&
+        isStringArray(entry.signals) &&
+        (entry.batch_iteration === undefined ||
+            (Number.isInteger(entry.batch_iteration) && entry.batch_iteration >= 1)));
 }
 /**
  * The two optional fields are checked as ABSENT-or-well-formed, never defaulted.
@@ -752,6 +1355,8 @@ function isAttemptArray(value) {
         Number.isInteger(entry.attempt) &&
         typeof entry.request_digest === "string" &&
         typeof entry.transition === "string" &&
+        (entry.batch_iteration === undefined ||
+            (Number.isInteger(entry.batch_iteration) && entry.batch_iteration >= 1)) &&
         (entry.parent_request_digest === null || typeof entry.parent_request_digest === "string"));
 }
 //# sourceMappingURL=run-state.js.map