@tacuchi/agent-workflow-cli 25.6.0 → 25.7.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 { 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,42 @@ 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 = 12;
+/**
+ * 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.
+ */
+export const FLOW_RUN_STATE_CONTINUABLE = [FLOW_RUN_STATE_VERSION, 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_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.
  */
-export const FLOW_RUN_STATE_READABLE = [FLOW_RUN_STATE_VERSION, 10, 9, 8, 7];
+const CONTINUABLE_UPGRADES = {
+    11: (state) => ({ ...state, version: 12, journey_base: [...V11_JOURNEY_BASE[state.flow]] }),
+};
 /** The CLI-owned run state inside the session folder. Machine-local, dotted. */
 export const FLOW_RUN_STATE_FILE = ".flow-run.json";
 /**
@@ -348,8 +375,12 @@ 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 === "restarted" ||
+        event.kind === "annulled") {
         return false;
+    }
     if (event.kind !== "failed")
         return touchesTheWorld(event.effects);
     if (event.effects === undefined)
@@ -405,6 +436,7 @@ export function newRunState(flow, session) {
         flow,
         session,
         scope: null,
+        journey_base: journeyOfFlow(flow).map((decision) => decision.id),
         applied: [],
         skipped: [],
         boundary: null,
@@ -525,32 +557,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 +611,28 @@ 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 one inferred or declared batch, refusing duplicate ids at the caller's boundary. */
 export function withPlanExecBatch(state, batch) {
@@ -1021,20 +1083,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 +1110,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 +1140,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 +1156,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 +1296,23 @@ 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 (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;
@@ -1599,7 +1777,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 +1813,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))
@@ -1682,24 +1866,35 @@ function isEvent(entry) {
         (!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" &&
-            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),
+    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))