@tacuchi/agent-workflow-cli 25.6.1 → 25.8.0

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

@@ -26,6 +26,8 @@ import { canonicalJson, semanticDigest } from "../../application/semantic-operat
 import { isEffectClass, touchesTheWorld } from "../capability/effects.js";
 import { AttemptLedger } from "../capability/protocol.js";
 import { normalizeObligations, validateDecisionNote } from "../decision-note.js";
+import { expandJourney, journeyOfFlow, } from "./authority.js";
+import { V11_JOURNEY_BASE } from "./journey-baseline.js";
 import { assuranceForRoute, isAssuranceStatus, isRouteDisposition, } from "./route.js";
 /**
  * The version this CLI WRITES. Every state it persists carries it.
@@ -38,17 +40,50 @@ import { assuranceForRoute, isAssuranceStatus, isRouteDisposition, } from "./rou
  * 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 = 11;
+export const FLOW_RUN_STATE_VERSION = 13;
+/**
+ * The versions this CLI CONTINUES without adoption, newest first.
+ *
+ * v12 added the `aligned`, `restarted` and `annulled` trace kinds and `journey_base`, whose truthful value
+ * for a v11 run is the journey 25.6.1 walked. So a v11 run keeps walking after
+ * an upgrade: {@link upgradeContinuable} re-stamps it without touching the
+ * cursor, the answers or the attempts. Every later version joins this set with its own
+ * upgrade step, which is what keeps "v11 or later survives an update" true
+ * without an exception per release.
+ *
+ * v13 added `reentries` and the `reentry_iteration` of attempts, observations and
+ * events. All three are absent on a run that never re-entered, which is every
+ * v12 run, so its upgrade step only re-stamps the version.
+ * It also added each batch's `base` and `credit`, a reseated run's `inherited_bases`
+ * and the `route-refused` trace kind. A v12 run has none of them either, and a
+ * batch without `base` is read as the one that was in flight when the CLI updated.
+ */
+export const FLOW_RUN_STATE_CONTINUABLE = [FLOW_RUN_STATE_VERSION, 12, 11];
 /**
  * The versions this CLI READS, newest first.
  *
- * 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.
+ * Versions 10 to 7 remain readable for status and recovery evidence only. They
+ * are NOT continuable execution state: continuing an old cursor by merely
+ * changing `version` would invent a batch boundary the old run never declared,
+ * so their way out is `aw flow restart`.
  */
-export const FLOW_RUN_STATE_READABLE = [FLOW_RUN_STATE_VERSION, 10, 9, 8, 7];
+export const FLOW_RUN_STATE_READABLE = [
+    ...FLOW_RUN_STATE_CONTINUABLE,
+    10,
+    9,
+    8,
+    7,
+];
+/**
+ * One upgrade step per continuable version, keyed by the version it upgrades FROM.
+ *
+ * A step may only add what the next version introduced with a truthful default;
+ * the cursor, the answers, the approvals and the attempts pass through untouched.
+ */
+const CONTINUABLE_UPGRADES = {
+    11: (state) => ({ ...state, version: 12, journey_base: [...V11_JOURNEY_BASE[state.flow]] }),
+    12: (state) => ({ ...state, version: 13 }),
+};
 /** The CLI-owned run state inside the session folder. Machine-local, dotted. */
 export const FLOW_RUN_STATE_FILE = ".flow-run.json";
 /**
@@ -84,12 +119,47 @@ export function attemptsAt(state, transition) {
 }
 /** 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);
+    return attemptCounterKeyForIteration(transition, iterationOf(state, transition));
 }
-/** Stable counter key for a historical attempt whose batch iteration is recorded on the row. */
+/** Stable counter key for a historical attempt whose iteration is recorded on the row. */
 export function attemptCounterKeyForIteration(transition, iteration) {
-    return iteration === undefined ? transition : `${transition}@batch-${iteration}`;
+    const batch = iteration.batch_iteration === undefined ? "" : `@batch-${iteration.batch_iteration}`;
+    const reentry = iteration.reentry_iteration === undefined ? "" : `@reentry-${iteration.reentry_iteration}`;
+    return `${transition}${batch}${reentry}`;
+}
+/**
+ * The iteration of `transition` where the run stands: its batch copy and its
+ * reentry copy. Spread it into any record keyed per boundary.
+ */
+export function iterationOf(state, transition) {
+    const batch = currentBatchIteration(state, transition);
+    const reentry = currentReentryIteration(state, transition);
+    return {
+        ...(batch === null ? {} : { batch_iteration: batch }),
+        ...(reentry === null ? {} : { reentry_iteration: reentry }),
+    };
+}
+/** Whether a persisted record belongs to this iteration of its boundary. */
+export function sameIteration(record, iteration) {
+    return (record.batch_iteration === iteration.batch_iteration &&
+        record.reentry_iteration === iteration.reentry_iteration);
+}
+/**
+ * Which reentry inserted the row of `transition` the cursor is on, or `null` on
+ * the row's own place. Read at the cursor and backwards from it, so it answers
+ * the same before the row is applied and right after.
+ */
+export function currentReentryIteration(state, transition) {
+    if ((state.reentries ?? []).length === 0)
+        return null;
+    const { rows, copies } = expandJourney(state);
+    for (let index = Math.min(state.applied.length, rows.length - 1); index >= 0; index -= 1) {
+        if (rows[index]?.id !== transition)
+            continue;
+        const copy = copies[index] ?? 0;
+        return copy === 0 ? null : copy;
+    }
+    return null;
 }
 /**
  * The three numbers and the difference between them, computed once.
@@ -100,11 +170,8 @@ export function attemptCounterKeyForIteration(transition, iteration) {
  * 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 iteration = iterationOf(state, transition);
+    const rows = state.attempts.filter((attempt) => attempt.transition === transition && sameIteration(attempt, iteration));
     const key = attemptCounterKey(state, transition);
     const floor = state.attempt_floor?.[key] ?? 0;
     const granted = state.attempt_grants?.[key] ?? 0;
@@ -289,11 +356,10 @@ export function applyAttemptReconciliation(state, reconciliation) {
         grants[key] = repair.after;
         next = sealRunState({ ...withoutSeal(next), attempt_grants: grants });
     }
-    const iteration = currentBatchIteration(next, reconciliation.transition);
     return withEvent(next, {
         kind: "reconciled",
         transition: reconciliation.transition,
-        ...(iteration === null ? {} : { batch_iteration: iteration }),
+        ...iterationOf(next, reconciliation.transition),
         operation: "flow.attempt-reconciliation",
         repairs: reconciliation.repairs,
     });
@@ -323,11 +389,8 @@ function unanswerableAt(state) {
     return null;
 }
 export function recoveryBlockedAt(state, 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 iteration = iterationOf(state, transition);
+    const trace = state.events.filter((event) => event.transition === transition && sameIteration(event, iteration));
     const material = [...trace].reverse().find(declaresMaterialEffect);
     if (material !== undefined)
         return { reason: "materialized", event: material };
@@ -348,8 +411,13 @@ export function recoveryBlockedAt(state, transition) {
 function declaresMaterialEffect(event) {
     // A reconciliation moved the run's own counters and nothing else: it can no
     // more block a recovery than reading the file could.
-    if (event.kind === "reconciled")
+    if (event.kind === "reconciled" ||
+        event.kind === "aligned" ||
+        event.kind === "route-refused" ||
+        event.kind === "restarted" ||
+        event.kind === "annulled") {
         return false;
+    }
     if (event.kind !== "failed")
         return touchesTheWorld(event.effects);
     if (event.effects === undefined)
@@ -405,6 +473,7 @@ export function newRunState(flow, session) {
         flow,
         session,
         scope: null,
+        journey_base: journeyOfFlow(flow).map((decision) => decision.id),
         applied: [],
         skipped: [],
         boundary: null,
@@ -525,32 +594,43 @@ export function grantAttempts(state, transition, attempts) {
     granted[key] = (granted[key] ?? 0) + attempts;
     return sealRunState({ ...withoutSeal(state), attempt_grants: granted });
 }
+/** Whether this exhausted boundary already spent the one re-run the CLI gives it. */
+export function exhaustedRerunSpent(state, transition) {
+    return (state.exhausted_reruns ?? []).includes(attemptCounterKey(state, transition));
+}
+/** Record that the CLI's one re-run of this exhausted boundary came back refused. */
+export function withExhaustedRerunSpent(state, transition) {
+    if (exhaustedRerunSpent(state, transition))
+        return state;
+    return sealRunState({
+        ...withoutSeal(state),
+        exhausted_reruns: [...(state.exhausted_reruns ?? []), attemptCounterKey(state, transition)],
+    });
+}
 /**
- * Explicitly adopt a readable legacy state into v10.
- *
- * 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".
+ * Forget a spent re-run: `aw flow recover` gives the boundary a fresh budget,
+ * and a later exhaustion is a new episode that is owed its own re-run.
  */
-export function atCurrentVersion(state) {
-    if (state.version === FLOW_RUN_STATE_VERSION)
+export function withoutExhaustedRerun(state, transition) {
+    if (!exhaustedRerunSpent(state, transition))
         return state;
+    const key = attemptCounterKey(state, transition);
     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,
-        route_proposal: null,
-        route_decisions: null,
-        assurance: "verified",
+        exhausted_reruns: (state.exhausted_reruns ?? []).filter((spent) => spent !== key),
     });
 }
+/**
+ * The one exit from a run the CLI cannot continue: archive it inside the session
+ * and adopt a new one. Named in every refusal whose state it resolves.
+ */
+export function restartInvocation(session) {
+    return `aw flow restart --session ${session}`;
+}
+/** The action of every refusal over a registry this CLI cannot use as it is. */
+function unusableRemedy(session) {
+    return `corré '${restartInvocation(session)}': archiva el registro dentro de la sesión, re-adopta su flow y lo deja en la traza — o restaurá una copia íntegra del archivo`;
+}
 /** Keep the sealed preview the person is choosing over; no cursor moves here. */
 export function withRouteProposal(state, proposal) {
     return sealRunState({
@@ -568,9 +648,68 @@ export function withRouteDecisions(state, decisions) {
         assurance: assuranceForRoute(decisions, state.applied),
     });
 }
-/** Whether a parsed state needs the explicit adoption boundary before mutation. */
+/** Whether a parsed state is outside the continuable set and cannot be mutated. */
 export function legacyRunNeedsAdoption(state) {
-    return state.version !== FLOW_RUN_STATE_VERSION;
+    return !FLOW_RUN_STATE_CONTINUABLE.includes(state.version);
+}
+/**
+ * Walk a continuable state up to the version this CLI writes, one step at a time.
+ *
+ * Re-sealed once at the end: the file on disk was already verified against its
+ * own seal, and the upgraded state is persisted by the next write, never here.
+ * A legacy state comes back unchanged — reading one must never re-stamp it.
+ */
+export function upgradeContinuable(state) {
+    if (legacyRunNeedsAdoption(state) || state.version === FLOW_RUN_STATE_VERSION)
+        return state;
+    let current = state;
+    while (current.version !== FLOW_RUN_STATE_VERSION) {
+        const step = CONTINUABLE_UPGRADES[current.version];
+        if (step === undefined)
+            return state;
+        current = step(current);
+    }
+    return sealRunState(withoutSeal(current));
+}
+/** Record a reentry of the journey, after every one already recorded. */
+export function withReentry(state, reentry) {
+    return sealRunState({
+        ...withoutSeal(state),
+        reentries: [...(state.reentries ?? []), reentry],
+    });
+}
+/**
+ * Take back the last reentry, for the close that recorded its intention and then
+ * could not happen. The field goes back to absent when it empties, so the run
+ * serializes the bytes it had before the intention.
+ */
+export function withoutLastReentry(state) {
+    const { reentries: _all, ...rest } = withoutSeal(state);
+    const kept = (state.reentries ?? []).slice(0, -1);
+    return sealRunState(kept.length === 0 ? rest : { ...rest, reentries: kept });
+}
+/** Seal the base of one batch; a batch that already has one keeps it. */
+export function withPlanExecBatchBase(state, batchId, base) {
+    const batches = state.batches ?? [];
+    const target = batches.find((batch) => batch.id === batchId);
+    // A re-run of the acquisition on the same batch must not move its base: the
+    // batch would then be compared against its own half-done work.
+    if (target === undefined || target.base !== undefined)
+        return state;
+    return sealRunState({
+        ...withoutSeal(state),
+        batches: batches.map((batch) => (batch.id === batchId ? { ...batch, base } : batch)),
+    });
+}
+/** Record the proofs that credited one batch. */
+export function withPlanExecBatchCredit(state, batchId, credit) {
+    const batches = state.batches ?? [];
+    if (!batches.some((batch) => batch.id === batchId))
+        return state;
+    return sealRunState({
+        ...withoutSeal(state),
+        batches: batches.map((batch) => (batch.id === batchId ? { ...batch, credit } : batch)),
+    });
 }
 /** Record one inferred or declared batch, refusing duplicate ids at the caller's boundary. */
 export function withPlanExecBatch(state, batch) {
@@ -892,7 +1031,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 &&
+        sameIteration(last, event) &&
         last.code === event.code &&
         last.message === event.message);
 }
@@ -913,7 +1052,7 @@ export function restatesLastEvent(state, event) {
  */
 export function withObservation(state, observation) {
     const repeated = state.observations.some((past) => past.transition === observation.transition &&
-        past.batch_iteration === observation.batch_iteration &&
+        sameIteration(past, observation) &&
         sameSignals(past.signals, observation.signals));
     if (repeated)
         return state;
@@ -1021,20 +1160,26 @@ function union(current, added) {
  *
  * Order matters: shape before version before seal. A file whose version is
  * unknown must not be judged by a digest rule that version may not even use.
+ *
+ * Every refusal names the command that works IN that state: `--adopt` only adopts
+ * a session with no registry at all, so an unreadable, tampered or too-old one
+ * leaves through `aw flow restart`, and one written by a newer CLI through
+ * updating this one. `session` names the run in those commands.
  */
-export function parseRunState(raw) {
+export function parseRunState(raw, session = "<código>") {
+    const restart = unusableRemedy(session);
     if (raw.trim().length === 0) {
-        return refuse("FLOW_RUN_INVALID", "el estado de corrida está vacío", "reconstruí la corrida con 'aw flow advance --adopt', o restaurá el archivo");
+        return refuse("FLOW_RUN_INVALID", "el estado de corrida está vacío", restart);
     }
     let parsed;
     try {
         parsed = JSON.parse(raw);
     }
     catch {
-        return refuse("FLOW_RUN_INVALID", "el estado de corrida no es JSON válido", "no se avanza sobre un estado ilegible: restauralo o re-adoptá la sesión con 'aw flow advance --adopt'");
+        return refuse("FLOW_RUN_INVALID", "el estado de corrida no es JSON válido", restart);
     }
     if (!isRecord(parsed)) {
-        return refuse("FLOW_RUN_INVALID", "el estado de corrida no es un objeto JSON", "restauralo o re-adoptá la sesión con 'aw flow advance --adopt'");
+        return refuse("FLOW_RUN_INVALID", "el estado de corrida no es un objeto JSON", restart);
     }
     if (!FLOW_RUN_STATE_READABLE.includes(parsed.version)) {
         // No silent migration, in either direction: a version outside the readable
@@ -1042,14 +1187,17 @@ export function parseRunState(raw) {
         // fabricate the very history this file exists to make trustworthy — or comes
         // from a build ahead of this one, whose fields this build would ignore.
         // Refusing with the cause is what keeps the second case from being silent.
-        return refuse("FLOW_RUN_VERSION_UNSUPPORTED", `versión de estado de corrida no soportada: ${String(parsed.version)}`, `esta versión del CLI lee ${FLOW_RUN_STATE_READABLE.join(" y ")} y escribe la ${FLOW_RUN_STATE_VERSION}: actualizá el CLI, o re-adoptá la sesión con 'aw flow advance --flow <flow> --adopt' (no hay migración automática)`);
+        const newer = typeof parsed.version === "number" && parsed.version > FLOW_RUN_STATE_VERSION;
+        return refuse("FLOW_RUN_VERSION_UNSUPPORTED", `versión de estado de corrida no soportada: ${String(parsed.version)} (este CLI lee de la ${FLOW_RUN_STATE_READABLE.at(-1)} a la ${FLOW_RUN_STATE_VERSION})`, newer
+            ? `la escribió un CLI más nuevo que este: actualizalo con 'aw self update' y seguí la corrida — reiniciarla descartaría lo que esa versión sí continúa`
+            : restart);
     }
-    const shape = checkShape(parsed);
+    const shape = checkShape(parsed, restart);
     if (shape !== null)
         return { ok: false, failure: shape };
     const state = parsed;
     if (semanticDigest(withoutSeal(state)) !== state.digest) {
-        return refuse("FLOW_RUN_TAMPERED", "el estado de corrida no coincide con su propio sello", "fue editado fuera del CLI: descartá el archivo y re-adoptá la sesión con 'aw flow advance --adopt'");
+        return refuse("FLOW_RUN_TAMPERED", "el estado de corrida no coincide con su propio sello: fue editado fuera del CLI", restart);
     }
     return { ok: true, state };
 }
@@ -1069,10 +1217,15 @@ export function checkAgainstJourney(state, journey) {
     for (const [index, applied] of state.applied.entries()) {
         if (ids[index] === applied)
             continue;
+        // The cause decides the repair, so it is named: a row this build no longer
+        // has was renamed or retired, one it has elsewhere was reordered.
+        const cause = ids.includes(applied)
+            ? "el recorrido instalado la tiene en otra posición"
+            : "el recorrido instalado ya no tiene esa frontera";
         return {
             code: "FLOW_RUN_AHEAD_OF_JOURNEY",
-            message: `el estado dice haber aplicado '${applied}' donde el recorrido tiene '${ids[index] ?? "(nada)"}'`,
-            action: "el estado no corresponde a este recorrido: revisá el flow de la corrida o re-adoptá la sesión",
+            message: `el estado dice haber aplicado '${applied}' donde el recorrido tiene '${ids[index] ?? "(nada)"}': ${cause}`,
+            action: unusableRemedy(state.session),
         };
     }
     const next = ids[state.applied.length] ?? null;
@@ -1080,16 +1233,111 @@ export function checkAgainstJourney(state, journey) {
         return {
             code: "FLOW_RUN_AHEAD_OF_JOURNEY",
             message: `la frontera vigente dice '${state.boundary}' y el recorrido sigue en '${next ?? "(nada)"}'`,
-            action: "recalculá la frontera avanzando de nuevo; no se responde sobre una frontera que el estado no sostiene",
+            action: unusableRemedy(state.session),
         };
     }
     return null;
 }
-function checkShape(parsed) {
+/** The trace operation that names an alignment, so status and tests read one spelling. */
+export const JOURNEY_ALIGNMENT_OPERATION = "flow.journey-alignment";
+const ALIGNMENT_REASON = "la versión instalada agregó esta frontera en un tramo que la corrida ya había recorrido: entra omitida, sin pedirse";
+/**
+ * Align a continuable run's cursor with the journey the installed build walks.
+ *
+ * The only difference this repairs is a boundary the installed build ADDED to
+ * the base journey the run recorded (`journey_base`) and that sits before the
+ * run's position. "Before the position" includes the rows ahead of the boundary
+ * the run is standing on: that boundary is the one it was answering, and a
+ * sealed or attempted action there must not be thrown away for a row nobody
+ * asked it about. A row added AFTER the boundary is left alone and asked when
+ * the run gets there.
+ *
+ * Every other difference comes back untouched, for {@link checkAgainstJourney}
+ * to refuse with its cause: a row the recorded base already had and the cursor
+ * lacks is a hole, not an addition; a reorder or a retirement moves an id that
+ * keys attempts, counters, trace and approvals.
+ *
+ * `base` is the installed REGISTRY journey; `journey` is what the run walks
+ * (plan-exec's expanded copies included). Pure: the aligned state is persisted
+ * by the run's next write, never by a read.
+ */
+export function alignToJourney(state, journey, base) {
+    const recorded = state.journey_base;
+    if (recorded === undefined || sameIds(recorded, base))
+        return state;
+    const addedIds = new Set(base.filter((id) => !recorded.includes(id)));
+    const ids = journey.map((decision) => decision.id);
+    const applied = [];
+    const added = [];
+    let cursor = 0;
+    // Everything from `cursor` up to the next occurrence of `target` must be rows
+    // the installed build added; only then are they inserted, in journey order.
+    const insertUntil = (target) => {
+        let next = cursor;
+        while (next < ids.length && ids[next] !== target) {
+            if (!addedIds.has(ids[next]))
+                return false;
+            next += 1;
+        }
+        if (next >= ids.length)
+            return false;
+        for (; cursor < next; cursor += 1) {
+            added.push({ transition: ids[cursor], position: applied.length });
+            applied.push(ids[cursor]);
+        }
+        return true;
+    };
+    for (const id of state.applied) {
+        if (ids[cursor] !== id && !insertUntil(id))
+            return state;
+        applied.push(id);
+        cursor += 1;
+    }
+    if (state.boundary !== null && ids[cursor] !== state.boundary && !insertUntil(state.boundary)) {
+        return state;
+    }
+    const events = added.map((row) => {
+        const iteration = segmentIterationAt(state.flow, applied, row.position);
+        return {
+            kind: "aligned",
+            transition: row.transition,
+            ...(iteration === null ? {} : { batch_iteration: iteration }),
+            operation: JOURNEY_ALIGNMENT_OPERATION,
+            position: row.position,
+            reason: ALIGNMENT_REASON,
+        };
+    });
+    return sealRunState({
+        ...withoutSeal(state),
+        journey_base: [...base],
+        applied,
+        skipped: [...state.skipped, ...added.map((row) => row.transition)],
+        events: [...state.events, ...events],
+    });
+}
+function sameIds(left, right) {
+    return left.length === right.length && left.every((id, index) => id === right[index]);
+}
+/**
+ * Which plan-exec batch copy a cursor position falls inside, or null outside one.
+ *
+ * Two copies of the same added row differ only by the batch they belong to, so
+ * the trace names it the way every other per-batch event does.
+ */
+function segmentIterationAt(flow, applied, position) {
+    if (flow !== "plan-exec")
+        return null;
+    const before = applied.slice(0, position);
+    const opened = before.lastIndexOf("plan-exec.batch-eligibility-signal");
+    if (opened < 0 || before.lastIndexOf("plan-exec.batch-close") > opened)
+        return null;
+    return before.filter((id) => id === "plan-exec.batch-eligibility-signal").length;
+}
+function checkShape(parsed, remedy) {
     const invalid = (why) => ({
         code: "FLOW_RUN_INVALID",
         message: `el estado de corrida ${why}`,
-        action: "restauralo o re-adoptá la sesión con 'aw flow advance --adopt'",
+        action: remedy,
     });
     if (!WORKLINE_FLOWS.includes(parsed.flow)) {
         return invalid(`declara un flow desconocido: ${String(parsed.flow)}`);
@@ -1125,16 +1373,26 @@ function checkRecordShape(parsed, invalid) {
     const common = checkCommonRecordShape(parsed, invalid);
     if (common !== null)
         return common;
-    if (parsed.version === FLOW_RUN_STATE_VERSION || parsed.version === 10) {
+    const version = parsed.version;
+    if (version >= 10) {
         const v10 = checkV10RecordShape(parsed, invalid);
         if (v10 !== null)
             return v10;
     }
-    if (parsed.version === FLOW_RUN_STATE_VERSION) {
+    if (version >= 11) {
         const v11 = checkV11RecordShape(parsed, invalid);
         if (v11 !== null)
             return v11;
     }
+    if (version >= 12 && !isStringArray(parsed.journey_base)) {
+        return invalid("no dice contra qué recorrido se escribió su cursor");
+    }
+    if (!isReentryArray(parsed.reentries)) {
+        return invalid("declara una reentrada sin tipo, frontera, ocurrencia u origen");
+    }
+    if (parsed.exhausted_reruns !== undefined && !isStringArray(parsed.exhausted_reruns)) {
+        return invalid("declara vueltas de fronteras agotadas que no son transiciones");
+    }
     if (typeof parsed.digest !== "string")
         return invalid("no trae su sello");
     return null;
@@ -1172,8 +1430,55 @@ function checkCommonRecordShape(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 (!isInheritedBaseArray(parsed.inherited_bases)) {
+        return invalid("hereda una base de batch sin sus fases o sin sus fuentes");
+    }
     return null;
 }
+function isInheritedBaseArray(value) {
+    if (value === undefined)
+        return true;
+    return (Array.isArray(value) &&
+        value.every((entry) => isRecord(entry) &&
+            Array.isArray(entry.phases) &&
+            entry.phases.length > 0 &&
+            entry.phases.every((phase) => Number.isInteger(phase) && phase > 0) &&
+            isSourceMap(entry.base, true) &&
+            entry.base !== undefined));
+}
+/**
+ * The bases a reseated run inherits from the archived registry, read tolerantly:
+ * the archive may be the very state that could not be continued, so anything
+ * that is not a well-formed batch base is left behind rather than trusted.
+ */
+export function inheritedBasesFrom(archived) {
+    if (archived === null)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(archived);
+    }
+    catch {
+        return [];
+    }
+    if (!isRecord(parsed) || !Array.isArray(parsed.batches))
+        return [];
+    const inherited = parsed.batches.flatMap((batch) => {
+        if (!isRecord(batch) || batch.base === undefined)
+            return [];
+        const candidate = { phases: batch.phases, base: batch.base };
+        return isInheritedBaseArray([candidate]) ? [candidate] : [];
+    });
+    const earlier = isInheritedBaseArray(parsed.inherited_bases)
+        ? (parsed.inherited_bases ?? [])
+        : [];
+    return [...earlier, ...inherited];
+}
+export function withInheritedBases(state, inherited) {
+    if (inherited.length === 0)
+        return state;
+    return sealRunState({ ...withoutSeal(state), inherited_bases: [...inherited] });
+}
 /** Fields added by v10 that have no truthful default on a persisted run. */
 function checkV10RecordShape(parsed, invalid) {
     if (!isPlanExecBatchArray(parsed.batches)) {
@@ -1262,7 +1567,7 @@ function isRouteProposal(value) {
             !isRouteDisposition(control.recommendation) ||
             !isRecord(control.alternatives) ||
             !isNonEmptyString(control.alternatives.apply) ||
-            !isNonEmptyString(control.alternatives.omit) ||
+            (control.alternatives.omit !== undefined && !isNonEmptyString(control.alternatives.omit)) ||
             !isNonEmptyString(control.alternatives.substitute) ||
             !isNonEmptyString(control.consequence) ||
             !isNonEmptyString(control.risk) ||
@@ -1364,7 +1669,9 @@ function isPlanExecBatchArray(value) {
             (entry.publication !== undefined &&
                 entry.publication.status === "applied" &&
                 entry.published_plan_digest !== entry.publication.after_plan_digest) ||
-            !PLAN_EXEC_BATCH_STAGES.includes(entry.stage)) {
+            !PLAN_EXEC_BATCH_STAGES.includes(entry.stage) ||
+            !isSourceMap(entry.base, true) ||
+            !isSourceMap(entry.credit, false)) {
             return false;
         }
         ids.add(entry.id);
@@ -1372,6 +1679,14 @@ function isPlanExecBatchArray(value) {
         return true;
     });
 }
+/** Absent, or a non-empty alias → digest map; `nullable` admits an unobserved source. */
+function isSourceMap(value, nullable) {
+    if (value === undefined)
+        return true;
+    if (!isRecord(value) || Object.keys(value).length === 0)
+        return false;
+    return Object.values(value).every((digest) => (nullable && digest === null) || (typeof digest === "string" && digest.length > 0));
+}
 function isPlanExecBatchPublication(value) {
     if (value === undefined)
         return true;
@@ -1599,7 +1914,8 @@ function isDecisionPreview(value, baseline) {
     return value.effects.entries.every((entry) => isRecord(entry) &&
         typeof entry.path === "string" &&
         Number.isInteger(entry.bytes) &&
-        typeof entry.overwrite === "boolean");
+        typeof entry.overwrite === "boolean" &&
+        isReservedMark(entry.reserved));
 }
 /**
  * The persisted preview's obligations, in EITHER form.
@@ -1634,7 +1950,12 @@ function isProposalArtifacts(value) {
     return value.every((entry) => isRecord(entry) &&
         typeof entry.path === "string" &&
         typeof entry.content === "string" &&
-        typeof entry.overwrite === "boolean");
+        typeof entry.overwrite === "boolean" &&
+        isReservedMark(entry.reserved));
+}
+/** The optional reservation mark: absent, or exactly `true`. */
+function isReservedMark(value) {
+    return value === undefined || value === true;
 }
 function isProposalBases(value) {
     if (!Array.isArray(value))
@@ -1678,28 +1999,38 @@ function isEvent(entry) {
         return false;
     if (typeof entry.transition !== "string" || typeof entry.operation !== "string")
         return false;
-    if (entry.batch_iteration !== undefined &&
-        (!Number.isInteger(entry.batch_iteration) || entry.batch_iteration < 1)) {
+    if (!isIterationRecord(entry))
         return false;
-    }
-    if (entry.kind === "executed") {
-        return (typeof entry.summary === "string" &&
-            typeof entry.output_digest === "string" &&
-            isEffectClassArray(entry.effects) &&
-            isStringArray(entry.evidence));
-    }
-    if (entry.kind === "reconciled")
-        return isRepairArray(entry.repairs);
-    if (entry.kind === "failed") {
-        return (typeof entry.code === "string" &&
-            typeof entry.message === "string" &&
-            typeof entry.recovery === "string" &&
-            // ABSENT-or-well-formed, never defaulted: a version 7 trace has no such
-            // field, and the guard that reads it treats its absence as the refusal.
-            (entry.effects === undefined || isEffectClassArray(entry.effects)));
-    }
-    return false;
+    return EVENT_BODIES.get(entry.kind)?.(entry) === true;
 }
+const nonEmpty = (value) => typeof value === "string" && value.trim().length > 0;
+/**
+ * What each trace kind demands beyond the common fields; an unknown kind has no
+ * entry. A Map, not an object: a kind spelled like an Object.prototype member
+ * must not find a function nobody declared.
+ */
+const EVENT_BODIES = new Map(Object.entries({
+    executed: (entry) => typeof entry.summary === "string" &&
+        typeof entry.output_digest === "string" &&
+        isEffectClassArray(entry.effects) &&
+        isStringArray(entry.evidence),
+    reconciled: (entry) => isRepairArray(entry.repairs),
+    restarted: (entry) => nonEmpty(entry.archive) && nonEmpty(entry.cause),
+    annulled: (entry) => isStringArray(entry.batches) &&
+        entry.batches.length > 0 &&
+        Array.isArray(entry.phases) &&
+        entry.phases.every((phase) => Number.isInteger(phase) && phase > 0) &&
+        isStringArray(entry.tasks) &&
+        nonEmpty(entry.digest),
+    aligned: (entry) => Number.isInteger(entry.position) && entry.position >= 0 && nonEmpty(entry.reason),
+    "route-refused": (entry) => isRouteDisposition(entry.disposition) && nonEmpty(entry.reason),
+    failed: (entry) => typeof entry.code === "string" &&
+        typeof entry.message === "string" &&
+        typeof entry.recovery === "string" &&
+        // ABSENT-or-well-formed, never defaulted: a version 7 trace has no such
+        // field, and the guard that reads it treats its absence as the refusal.
+        (entry.effects === undefined || isEffectClassArray(entry.effects)),
+}));
 /** A repair is well-formed when its rule is one of the three and its values are numbers. */
 function isRepairArray(value) {
     if (!Array.isArray(value))
@@ -1718,8 +2049,29 @@ function isObservationArray(value) {
     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)));
+        isIterationRecord(entry));
+}
+const REENTRY_KINDS = ["refine", "close", "reopen"];
+/** Absent, or reentries each with its kind, its boundary, its occurrence and its origin. */
+function isReentryArray(value) {
+    if (value === undefined)
+        return true;
+    if (!Array.isArray(value))
+        return false;
+    return value.every((entry) => isRecord(entry) &&
+        REENTRY_KINDS.includes(entry.kind) &&
+        nonEmpty(entry.transition) &&
+        Number.isInteger(entry.occurrence) &&
+        entry.occurrence >= 1 &&
+        // A redraft names where it re-enters; the other kinds repeat from their row.
+        (entry.kind === "refine"
+            ? nonEmpty(entry.from)
+            : entry.from === null || nonEmpty(entry.from)));
+}
+/** Both iteration fields, each absent or a positive integer. */
+function isIterationRecord(entry) {
+    const ordinal = (value) => value === undefined || (Number.isInteger(value) && value >= 1);
+    return ordinal(entry.batch_iteration) && ordinal(entry.reentry_iteration);
 }
 /**
  * The two optional fields are checked as ABSENT-or-well-formed, never defaulted.
@@ -1755,8 +2107,7 @@ 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)) &&
+        isIterationRecord(entry) &&
         (entry.parent_request_digest === null || typeof entry.parent_request_digest === "string"));
 }
 //# sourceMappingURL=run-state.js.map