@osovv/vv-opencode 1.4.2 → 1.4.3-rc.1

package/dist/plugins/workflow/persistence.js

@@ -1,22 +1,29 @@
 // FILE: src/plugins/workflow/persistence.ts
-// VERSION: 0.3.0
+// VERSION: 0.4.0
 // START_MODULE_CONTRACT
 //   PURPOSE: Hydrate and snapshot work-item workflow state from/to per-session JSON
 //     files under $XDG_DATA_HOME/vvoc/workflow/<sessionId>/workflow-state.json.
 //   SCOPE: Read/write WorkItemStoreData (nextId, records, keyIndexBySession,
-//     planRuns) as serializable JSON. Version 2 snapshots additionally persist
-//     delegated attempts, decisions, acceptances, rework history, and registered
-//     plan runs with checkpoint generations through an atomic temporary-file
-//     replacement, including failed attempts carrying bounded host failure
-//     evidence. Version 1 files hydrate conservatively as legacy records with
-//     an empty plan-run registry and never synthesize acceptance or approval.
+//     planRuns, executions, messageClaims) as serializable JSON. Version 4
+//     snapshots additionally persist the common execution registry and
+//     session-wide root-message claims. Version 3 snapshots persist
+//     delegated and checkpoint recovery histories with replay-protected
+//     authorization references, recovery-aware attempt and generation budgets,
+//     and report_rejected attempts carrying bounded rejected-report evidence
+//     through an atomic temporary-file replacement. Version 2 files hydrate
+//     conservatively with empty recovery histories and unchanged budgets;
+//     version 1 files hydrate as legacy records with an empty plan-run
+//     registry. Existing native plan runs materialize a compatibility
+//     execution registry entry without inventing authority. Neither ever
+//     synthesizes acceptance, approval, or recovery.
 //     Strict validation rejects malformed or contradictory new state instead of
 //     silently restarting a run. A checked loader distinguishes missing, valid,
 //     and invalid state and surfaces I/O failures.
 //   DEPENDS: [node:fs, node:fs/promises, node:path, src/lib/vvoc-paths.ts,
+//     src/lib/workflow-contract.ts,
 //     src/plugins/workflow/checkpoints.ts (types), src/plugins/workflow/delegated.ts,
-//     src/plugins/workflow/state.ts]
-//   LINKS: M-WORKFLOW-PERSISTENCE, M-CONFIG-LAYERS, M-WORKFLOW-STATE, M-WORKFLOW-DELEGATED, M-WORKFLOW-CHECKPOINTS, V-M-WORKFLOW-PERSISTENCE
+//     src/plugins/workflow/execution.ts, src/plugins/workflow/state.ts]
+//   LINKS: M-WORKFLOW-PERSISTENCE, M-CONFIG-LAYERS, M-WORKFLOW-STATE, M-WORKFLOW-DELEGATED, M-WORKFLOW-CHECKPOINTS, M-WORKFLOW-EXECUTION, M-WORKFLOW-CONTRACT, V-M-WORKFLOW-PERSISTENCE
 //   ROLE: RUNTIME
 //   MAP_MODE: EXPORTS
 // END_MODULE_CONTRACT
@@ -25,6 +32,7 @@
 //   PERSISTED_WORKFLOW_STATE_VERSION - Current persisted snapshot version.
 //   PersistedWorkflowState - JSON-serializable shape of a per-session workflow state.
 //   SerializedDelegatedPlanRun - JSON form of one registered plan run.
+//   SerializedWorkflowExecution - JSON form of one common execution registry entry.
 //   HydratedWorkflowStateResult - Missing/valid/invalid triage returned by the checked loader.
 //   SnapshotWorkflowStateResult - Write outcome returned by the checked snapshot path.
 //   getWorkflowSessionDir - Resolve per-session directory path.
@@ -36,16 +44,20 @@
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [direct fix inFlightAttempt after failed worker launch - Version 2 validation accepts failed delegated attempts with bounded failure evidence and rejects contradictory failed/completed/in-flight attempt payloads.]
+//   LAST_CHANGE: [C-WORKFLOW-PLAN-INDEPENDENCE - Version 4 persists the common execution registry and session-wide message claims while explicitly migrating v1/v2/v3 without clearing recovery, rejected-report, or stopped-generation history.]
 // END_CHANGE_SUMMARY
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { join } from "node:path";
 import { getGlobalVvocDataDir } from "../../lib/vvoc-paths.js";
-import { normalizeDeclaredScopePath } from "../../lib/spec-lint.js";
-import { DELEGATED_BASE_ATTEMPTS, DELEGATED_EVIDENCE_MAX_CHARS, DELEGATED_EVIDENCE_MAX_REFS, DELEGATED_RATIONALE_MAX_CHARS, } from "./delegated.js";
+import { normalizeDeclaredScopePath } from "../../lib/workflow-contract.js";
+import { ensureNativeExecutions } from "./execution.js";
+import { DELEGATED_BASE_ATTEMPTS, DELEGATED_EVIDENCE_MAX_CHARS, DELEGATED_EVIDENCE_MAX_REFS, DELEGATED_RATIONALE_MAX_CHARS, DELEGATED_RECOVERY_CODE_MAX_CHARS, delegatedRecoveryGrantCount, } from "./delegated.js";
+import { MAX_CHECKPOINT_REVIEW_ATTEMPTS, checkpointRecoveryGrantCount } from "./checkpoints.js";
 // START_BLOCK_SERIALIZATION_TYPES
-export const PERSISTED_WORKFLOW_STATE_VERSION = 2;
+export const PERSISTED_WORKFLOW_STATE_VERSION = 4;
+/** Version at which delegated/checkpoint recovery histories and report rejections were introduced. */
+const RECOVERY_STATE_VERSION = 3;
 // END_BLOCK_SERIALIZATION_TYPES
 const VALID_STATES = new Set([
     "open",
@@ -63,7 +75,7 @@ const DELEGATED_RESULT_STATUSES = new Set([
     "NEEDS_CONTEXT",
     "BLOCKED",
 ]);
-const CHECKPOINT_OUTCOMES = new Set(["passed", "failed", "stale"]);
+const CHECKPOINT_OUTCOMES = new Set(["passed", "failed", "stale", "stopped"]);
 const LAST_OUTCOMES = new Set([
     "passed",
     "failed",
@@ -71,6 +83,17 @@ const LAST_OUTCOMES = new Set([
     "stopped",
     "incomplete",
 ]);
+const RECOVERY_KINDS = new Set([
+    "resume",
+    "autonomous_grant",
+    "user_grant",
+    "advance_grant",
+]);
+const TERMINAL_ATTEMPT_STATUSES = new Set([
+    "completed",
+    "failed",
+    "report_rejected",
+]);
 function isWorkItemMode(value) {
     return value === "implementation" || value === "review_only" || value === "delegated";
 }
@@ -167,7 +190,7 @@ function validateBoundedEvidence(value, label, errors) {
     return true;
 }
 /** Validate the delegated-mode record extension; returns every contradiction found. */
-function validateDelegatedState(record, sessionId, errors) {
+function validateDelegatedState(record, sessionId, version, errors) {
     const delegated = record.delegated;
     if (!delegated || typeof delegated !== "object") {
         errors.push(`${record.workItemId}: delegated records require a delegated state object`);
@@ -199,7 +222,8 @@ function validateDelegatedState(record, sessionId, errors) {
             inFlight += 1;
             if (attempt.resultStatus !== undefined ||
                 attempt.completedAt !== undefined ||
-                attempt.failureExcerpt !== undefined) {
+                attempt.failureExcerpt !== undefined ||
+                attempt.reportRejection !== undefined) {
                 errors.push(`${record.workItemId}: in-flight attempt ${attempt.attempt} must not carry a result`);
             }
         }
@@ -210,22 +234,43 @@ function validateDelegatedState(record, sessionId, errors) {
             if (typeof attempt.completedAt !== "string") {
                 errors.push(`${record.workItemId}: completed attempt ${attempt.attempt} requires completedAt`);
             }
-            if (attempt.failureExcerpt !== undefined) {
-                errors.push(`${record.workItemId}: completed attempt ${attempt.attempt} must not carry a failure excerpt`);
+            if (attempt.failureExcerpt !== undefined || attempt.reportRejection !== undefined) {
+                errors.push(`${record.workItemId}: completed attempt ${attempt.attempt} must not carry failure or rejection evidence`);
             }
         }
         else if (attempt.status === "failed") {
             if (typeof attempt.completedAt !== "string") {
                 errors.push(`${record.workItemId}: failed attempt ${attempt.attempt} requires completedAt`);
             }
-            if (attempt.resultStatus !== undefined) {
-                errors.push(`${record.workItemId}: failed attempt ${attempt.attempt} must not carry a resultStatus`);
+            if (attempt.resultStatus !== undefined || attempt.reportRejection !== undefined) {
+                errors.push(`${record.workItemId}: failed attempt ${attempt.attempt} must not carry a result or rejection`);
             }
             if (attempt.failureExcerpt === undefined ||
                 !isWorkflowResultExcerpt(attempt.failureExcerpt)) {
                 errors.push(`${record.workItemId}: failed attempt ${attempt.attempt} requires a bounded failure excerpt`);
             }
         }
+        else if (attempt.status === "report_rejected") {
+            if (version < RECOVERY_STATE_VERSION) {
+                errors.push(`${record.workItemId}: report_rejected attempts require persisted version ${RECOVERY_STATE_VERSION}`);
+            }
+            if (typeof attempt.completedAt !== "string") {
+                errors.push(`${record.workItemId}: report_rejected attempt ${attempt.attempt} requires completedAt`);
+            }
+            if (attempt.resultStatus !== undefined || attempt.failureExcerpt !== undefined) {
+                errors.push(`${record.workItemId}: report_rejected attempt ${attempt.attempt} must not carry a synthesized result`);
+            }
+            const rejection = attempt.reportRejection;
+            if (!rejection ||
+                typeof rejection !== "object" ||
+                typeof rejection.protocolErrorCode !== "string" ||
+                rejection.protocolErrorCode.trim() === "" ||
+                rejection.protocolErrorCode.length > DELEGATED_RECOVERY_CODE_MAX_CHARS ||
+                typeof rejection.rejectedAt !== "string" ||
+                !isWorkflowResultExcerpt(rejection.excerpt)) {
+                errors.push(`${record.workItemId}: report_rejected attempt ${attempt.attempt} requires a bounded rejection record`);
+            }
+        }
         else {
             errors.push(`${record.workItemId}: attempt ${attempt.attempt} has invalid status ${attempt.status}`);
         }
@@ -240,8 +285,63 @@ function validateDelegatedState(record, sessionId, errors) {
     if (delegated.reworkHistory.some((rework) => !rework.reworkId || !rework.authorizedByCheckpoint)) {
         errors.push(`${record.workItemId}: rework history entries require ids and checkpoint authorization`);
     }
-    if (attempts.length > DELEGATED_BASE_ATTEMPTS + delegated.reworkHistory.length) {
-        errors.push(`${record.workItemId}: attempts exceed the base budget plus authorized rework grants`);
+    const recoveryHistory = delegated.recoveryHistory;
+    if (!Array.isArray(recoveryHistory)) {
+        if (version >= RECOVERY_STATE_VERSION) {
+            errors.push(`${record.workItemId}: version 3 delegated records require a recovery history`);
+        }
+    }
+    else if (recoveryHistory.length > 0 && version < RECOVERY_STATE_VERSION) {
+        errors.push(`${record.workItemId}: recovery history requires persisted version ${RECOVERY_STATE_VERSION}`);
+    }
+    else {
+        const recoveryIds = new Set();
+        const userMessageIds = new Set();
+        let autonomousGrants = 0;
+        for (const recovery of recoveryHistory) {
+            if (!recovery.recoveryId || recoveryIds.has(recovery.recoveryId)) {
+                errors.push(`${record.workItemId}: recovery entries require unique non-empty recoveryId values`);
+            }
+            recoveryIds.add(recovery.recoveryId ?? "");
+            if (!RECOVERY_KINDS.has(recovery.kind)) {
+                errors.push(`${record.workItemId}: recovery ${recovery.recoveryId} has an invalid kind`);
+            }
+            if (recovery.kind === "autonomous_grant") {
+                autonomousGrants += 1;
+            }
+            if (recovery.kind === "user_grant") {
+                if (typeof recovery.userMessageId !== "string" || recovery.userMessageId === "") {
+                    errors.push(`${record.workItemId}: user-grant recovery ${recovery.recoveryId} requires its authorizing message id`);
+                }
+                else if (userMessageIds.has(recovery.userMessageId)) {
+                    errors.push(`${record.workItemId}: message ${recovery.userMessageId} authorized more than one recovery unit`);
+                }
+                else {
+                    userMessageIds.add(recovery.userMessageId);
+                }
+            }
+            else if (recovery.userMessageId !== undefined) {
+                errors.push(`${record.workItemId}: non-user recovery ${recovery.recoveryId} must not persist an authorization reference`);
+            }
+            if (!Number.isInteger(recovery.targetAttempt) ||
+                recovery.targetAttempt < 1 ||
+                recovery.targetAttempt > attempts.length ||
+                !TERMINAL_ATTEMPT_STATUSES.has(attempts[recovery.targetAttempt - 1]?.status ?? "")) {
+                errors.push(`${record.workItemId}: recovery ${recovery.recoveryId} targets a non-terminal attempt`);
+            }
+            validateDelegatedText(recovery.diagnosis, DELEGATED_RATIONALE_MAX_CHARS, `${record.workItemId}: recovery ${recovery.recoveryId} diagnosis`, errors);
+            validateDelegatedText(recovery.changedCondition, DELEGATED_RATIONALE_MAX_CHARS, `${record.workItemId}: recovery ${recovery.recoveryId} changedCondition`, errors);
+            validateBoundedEvidence(recovery.verification, `${record.workItemId}: recovery ${recovery.recoveryId} verification`, errors);
+        }
+        if (autonomousGrants > 1) {
+            errors.push(`${record.workItemId}: at most one autonomous recovery grant may be recorded per item`);
+        }
+    }
+    if (attempts.length >
+        DELEGATED_BASE_ATTEMPTS +
+            delegated.reworkHistory.length +
+            delegatedRecoveryGrantCount(delegated.recoveryHistory ?? [])) {
+        errors.push(`${record.workItemId}: attempts exceed the base budget plus authorized rework and recovery grants`);
     }
     const decisions = delegated.decisions;
     if (!Array.isArray(decisions)) {
@@ -310,7 +410,7 @@ function validateDelegatedState(record, sessionId, errors) {
         errors.push(`${record.workItemId}: record session mismatch`);
     }
 }
-function isWorkItemRecord(value, sessionId, errors) {
+function isWorkItemRecord(value, sessionId, version, errors) {
     if (!value || typeof value !== "object")
         return false;
     const record = value;
@@ -333,7 +433,7 @@ function isWorkItemRecord(value, sessionId, errors) {
         return false;
     if (record.mode === "delegated") {
         const recordErrors = [];
-        validateDelegatedState(record, sessionId, recordErrors);
+        validateDelegatedState(record, sessionId, version, recordErrors);
         errors.push(...recordErrors);
         return recordErrors.length === 0;
     }
@@ -347,7 +447,7 @@ function isWorkItemRecord(value, sessionId, errors) {
     }
     return true;
 }
-function validatePlanRun(run, recordsById, sessionId, errors) {
+function validatePlanRun(run, recordsById, sessionId, version, errors) {
     if (!run || typeof run !== "object") {
         errors.push("plan run entries must be objects");
         return false;
@@ -429,10 +529,68 @@ function validatePlanRun(run, recordsById, sessionId, errors) {
             if (!CHECKPOINT_OUTCOMES.has(entry.outcome)) {
                 errors.push(`checkpoint ${checkpoint.checkpointId} history has invalid outcome ${entry.outcome}`);
             }
+            if (entry.outcome === "stopped" && version < RECOVERY_STATE_VERSION) {
+                errors.push(`checkpoint ${checkpoint.checkpointId} stopped history requires persisted version ${RECOVERY_STATE_VERSION}`);
+            }
             if (typeof entry.generation !== "number" || typeof entry.fingerprint !== "string") {
                 errors.push(`checkpoint ${checkpoint.checkpointId} history entry is malformed`);
             }
         }
+        const recoveryHistory = checkpoint.recoveryHistory;
+        if (!Array.isArray(recoveryHistory)) {
+            if (version >= RECOVERY_STATE_VERSION) {
+                errors.push(`checkpoint ${checkpoint.checkpointId} requires a recovery history at persisted version ${RECOVERY_STATE_VERSION}`);
+            }
+        }
+        else if (recoveryHistory.length > 0 && version < RECOVERY_STATE_VERSION) {
+            errors.push(`checkpoint ${checkpoint.checkpointId} recovery history requires persisted version ${RECOVERY_STATE_VERSION}`);
+        }
+        else {
+            const recoveryIds = new Set();
+            const userMessageIds = new Set();
+            let autonomousGrants = 0;
+            for (const recovery of recoveryHistory) {
+                if (!recovery.recoveryId || recoveryIds.has(recovery.recoveryId)) {
+                    errors.push(`checkpoint ${checkpoint.checkpointId} recovery entries require unique non-empty recoveryId values`);
+                }
+                recoveryIds.add(recovery.recoveryId ?? "");
+                if (!RECOVERY_KINDS.has(recovery.kind)) {
+                    errors.push(`checkpoint ${checkpoint.checkpointId} recovery ${recovery.recoveryId} has an invalid kind`);
+                }
+                if (recovery.kind === "autonomous_grant") {
+                    autonomousGrants += 1;
+                }
+                if (recovery.kind === "user_grant") {
+                    if (typeof recovery.userMessageId !== "string" || recovery.userMessageId === "") {
+                        errors.push(`checkpoint ${checkpoint.checkpointId} user-grant recovery ${recovery.recoveryId} requires its authorizing message id`);
+                    }
+                    else if (userMessageIds.has(recovery.userMessageId)) {
+                        errors.push(`checkpoint ${checkpoint.checkpointId} message ${recovery.userMessageId} authorized more than one recovery unit`);
+                    }
+                    else {
+                        userMessageIds.add(recovery.userMessageId);
+                    }
+                }
+                else if (recovery.userMessageId !== undefined) {
+                    errors.push(`checkpoint ${checkpoint.checkpointId} non-user recovery ${recovery.recoveryId} must not persist an authorization reference`);
+                }
+                if (!Number.isInteger(recovery.targetGeneration) ||
+                    recovery.targetGeneration < 1 ||
+                    recovery.targetGeneration > checkpoint.attempts) {
+                    errors.push(`checkpoint ${checkpoint.checkpointId} recovery ${recovery.recoveryId} targets an unknown generation`);
+                }
+                validateDelegatedText(recovery.diagnosis, DELEGATED_RATIONALE_MAX_CHARS, `checkpoint ${checkpoint.checkpointId} recovery ${recovery.recoveryId} diagnosis`, errors);
+                validateDelegatedText(recovery.changedCondition, DELEGATED_RATIONALE_MAX_CHARS, `checkpoint ${checkpoint.checkpointId} recovery ${recovery.recoveryId} changedCondition`, errors);
+                validateBoundedEvidence(recovery.verification, `checkpoint ${checkpoint.checkpointId} recovery ${recovery.recoveryId} verification`, errors);
+            }
+            if (autonomousGrants > 1) {
+                errors.push(`checkpoint ${checkpoint.checkpointId} has more than one autonomous recovery grant`);
+            }
+            if (checkpoint.attempts >
+                MAX_CHECKPOINT_REVIEW_ATTEMPTS + checkpointRecoveryGrantCount(recoveryHistory)) {
+                errors.push(`checkpoint ${checkpoint.checkpointId} generations exceed the ordinary budget plus recovery grants`);
+            }
+        }
         const review = checkpoint.currentReview;
         if (checkpoint.status === "in_review") {
             if (!review ||
@@ -458,7 +616,7 @@ function validatePlanRun(run, recordsById, sessionId, errors) {
             errors.push(`checkpoint ${checkpoint.checkpointId} passed without a passing history entry`);
         }
         if (checkpoint.status === "failed" &&
-            !["failed", "stale"].includes(history[history.length - 1]?.outcome ?? "")) {
+            !["failed", "stale", "stopped"].includes(history[history.length - 1]?.outcome ?? "")) {
             errors.push(`checkpoint ${checkpoint.checkpointId} failed without a failing history entry`);
         }
         if (checkpoint.attempts !== history.length + (checkpoint.status === "in_review" ? 1 : 0)) {
@@ -481,6 +639,181 @@ function serializePlanRun(run) {
         checkpoints: [...run.checkpoints.values()],
     };
 }
+// START_BLOCK_EXECUTION_SERIALIZATION
+function serializeWorkflowExecution(execution) {
+    return {
+        ...execution,
+        tasks: [...execution.tasks.entries()],
+        checkpoints: [...execution.checkpoints.entries()],
+    };
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+function validateWorkflowExecution(candidate, sessionId, errors) {
+    const before = errors.length;
+    if (!isNonEmptyString(candidate.runId))
+        errors.push("execution requires a runId");
+    if (candidate.sessionId !== sessionId) {
+        errors.push(`execution ${candidate.runId} belongs to another session`);
+    }
+    if (!isNonEmptyString(candidate.workspaceRoot)) {
+        errors.push(`execution ${candidate.runId} requires a workspaceRoot`);
+    }
+    if (!isNonEmptyString(candidate.executionKey)) {
+        errors.push(`execution ${candidate.runId} requires an executionKey`);
+    }
+    if (!isNonEmptyString(candidate.goal)) {
+        errors.push(`execution ${candidate.runId} requires a goal`);
+    }
+    if (candidate.state !== "preparing" &&
+        candidate.state !== "active" &&
+        candidate.state !== "sealed") {
+        errors.push(`execution ${candidate.runId} has invalid state ${String(candidate.state)}`);
+    }
+    if (!Number.isInteger(candidate.revision) || candidate.revision < 1) {
+        errors.push(`execution ${candidate.runId} requires a positive revision`);
+    }
+    if (!candidate.source || typeof candidate.source !== "object") {
+        errors.push(`execution ${candidate.runId} requires a source`);
+    }
+    else if (candidate.source.kind !== "native-package" &&
+        candidate.source.kind !== "provided-plan" &&
+        candidate.source.kind !== "conversation-scoped") {
+        errors.push(`execution ${candidate.runId} has an invalid source kind`);
+    }
+    if (!candidate.boundary ||
+        !Array.isArray(candidate.boundary.files) ||
+        !Array.isArray(candidate.boundary.directories)) {
+        errors.push(`execution ${candidate.runId} requires a boundary with files and directories`);
+    }
+    if (!Array.isArray(candidate.tasks) || candidate.tasks.length === 0) {
+        errors.push(`execution ${candidate.runId} requires at least one task binding`);
+    }
+    else {
+        const ids = new Set();
+        for (const [taskId, binding] of candidate.tasks) {
+            if (ids.has(taskId))
+                errors.push(`execution ${candidate.runId} repeats task ${taskId}`);
+            ids.add(taskId);
+            if (!binding || binding.taskId !== taskId) {
+                errors.push(`execution ${candidate.runId} task ${taskId} binding mismatch`);
+            }
+        }
+    }
+    if (!Array.isArray(candidate.checkpoints)) {
+        errors.push(`execution ${candidate.runId} requires a checkpoints array`);
+    }
+    if (!Array.isArray(candidate.lineage)) {
+        errors.push(`execution ${candidate.runId} requires a lineage array`);
+    }
+    if (!Array.isArray(candidate.authority) || !Array.isArray(candidate.stageApprovals)) {
+        errors.push(`execution ${candidate.runId} requires authority and stageApprovals arrays`);
+    }
+    if (!Array.isArray(candidate.reserveDebits)) {
+        errors.push(`execution ${candidate.runId} requires a reserveDebits array`);
+    }
+    // Deep authority/debit/approval consistency: cross-record totals, exact
+    // bindings, and replay-unique identities within one execution.
+    const authorityIds = new Set();
+    let grantedUnits = 0;
+    for (const authority of candidate.authority) {
+        if (!authority || typeof authority !== "object") {
+            errors.push(`execution ${candidate.runId} has a malformed authority record`);
+            continue;
+        }
+        const authorityId = authority.authorityId;
+        if (!isNonEmptyString(authorityId) || authorityIds.has(authorityId)) {
+            errors.push(`execution ${candidate.runId} requires unique authority ids`);
+            continue;
+        }
+        authorityIds.add(authorityId);
+        if (authority.runId !== candidate.runId) {
+            errors.push(`authority ${authorityId} does not belong to execution ${candidate.runId}`);
+        }
+        if (!isNonEmptyString(authority.grantedByMessageId)) {
+            errors.push(`authority ${authorityId} lacks its granting message identity`);
+        }
+        if (!Number.isInteger(authority.initialUnits) || authority.initialUnits < 1) {
+            errors.push(`authority ${authorityId} requires a positive initial reserve`);
+        }
+        else {
+            grantedUnits += authority.initialUnits;
+        }
+        if (!Array.isArray(authority.extensions) || !Array.isArray(authority.revocations)) {
+            errors.push(`authority ${authorityId} requires extension and revocation arrays`);
+        }
+        else {
+            for (const extension of authority.extensions) {
+                if (!Number.isInteger(extension.units) || extension.units < 1) {
+                    errors.push(`authority ${authorityId} has an invalid extension`);
+                }
+                else {
+                    grantedUnits += extension.units;
+                }
+            }
+        }
+    }
+    const debitIds = new Set();
+    let consumedUnits = 0;
+    for (const debit of candidate.reserveDebits) {
+        if (!debit || typeof debit !== "object") {
+            errors.push(`execution ${candidate.runId} has a malformed reserve debit`);
+            continue;
+        }
+        const recoveryId = debit.recoveryId;
+        if (!isNonEmptyString(recoveryId) || debitIds.has(recoveryId)) {
+            errors.push(`execution ${candidate.runId} requires unique reserve debit ids`);
+            continue;
+        }
+        debitIds.add(recoveryId);
+        if (!authorityIds.has(debit.authorityId)) {
+            errors.push(`reserve debit ${recoveryId} references an unknown authority`);
+        }
+        if (!Number.isInteger(debit.units) || debit.units < 1) {
+            errors.push(`reserve debit ${recoveryId} requires a positive unit count`);
+        }
+        else {
+            consumedUnits += debit.units;
+        }
+    }
+    if (consumedUnits > grantedUnits) {
+        errors.push(`execution ${candidate.runId} consumed more reserve units than were granted`);
+    }
+    const approvalIds = new Set();
+    for (const approval of candidate.stageApprovals) {
+        if (!approval || typeof approval !== "object") {
+            errors.push(`execution ${candidate.runId} has a malformed stage approval`);
+            continue;
+        }
+        if (!isNonEmptyString(approval.approvalId) || approvalIds.has(approval.approvalId)) {
+            errors.push(`execution ${candidate.runId} requires unique stage approval ids`);
+            continue;
+        }
+        approvalIds.add(approval.approvalId);
+        if (!authorityIds.has(approval.authorityId)) {
+            errors.push(`stage approval ${approval.approvalId} references an unknown authority`);
+        }
+    }
+    if (Array.isArray(candidate.checkpoints)) {
+        for (const [checkpointId, binding] of candidate.checkpoints) {
+            if (!binding || typeof binding !== "object") {
+                errors.push(`execution ${candidate.runId} checkpoint ${checkpointId} is malformed`);
+                continue;
+            }
+            if (binding.status === "passed") {
+                if (!Number.isInteger(binding.attempts) || binding.attempts < 1) {
+                    errors.push(`passed checkpoint ${checkpointId} requires a completed generation`);
+                }
+                if (!Number.isInteger(binding.passedRevision) || binding.passedRevision < 1) {
+                    errors.push(`passed checkpoint ${checkpointId} requires a passing revision`);
+                }
+            }
+        }
+    }
+    return errors.length === before;
+}
+// END_BLOCK_EXECUTION_SERIALIZATION
 /**
  * Resolve the per-session workflow data directory.
  * Path: $XDG_DATA_HOME/vvoc/workflow/<sessionId>/
@@ -526,7 +859,10 @@ export function hydrateWorkflowStateChecked(sessionId) {
             errors: [`workflow state is not valid JSON: ${error.message}`],
         };
     }
-    if (parsed.version !== 1 && parsed.version !== PERSISTED_WORKFLOW_STATE_VERSION) {
+    if (parsed.version !== 1 &&
+        parsed.version !== 2 &&
+        parsed.version !== RECOVERY_STATE_VERSION &&
+        parsed.version !== PERSISTED_WORKFLOW_STATE_VERSION) {
         return {
             status: "invalid",
             errors: [`unsupported persisted version ${String(parsed.version)}`],
@@ -535,11 +871,12 @@ export function hydrateWorkflowStateChecked(sessionId) {
     if (!Array.isArray(parsed.records)) {
         return { status: "invalid", errors: ["persisted records must be an array"] };
     }
+    const version = parsed.version;
     const errors = [];
     const records = new Map();
     for (const record of parsed.records) {
         const recordErrors = [];
-        if (!isWorkItemRecord(record, sessionId, recordErrors)) {
+        if (!isWorkItemRecord(record, sessionId, version, recordErrors)) {
             errors.push(...(recordErrors.length > 0
                 ? recordErrors
                 : [
@@ -547,6 +884,12 @@ export function hydrateWorkflowStateChecked(sessionId) {
                 ]));
             continue;
         }
+        // Versions 1 and 2 never carried recovery histories: hydrate them
+        // conservatively with empty histories rather than inferring grants, so
+        // their original budgets stay unchanged.
+        if (record.mode === "delegated" && record.delegated && version < RECOVERY_STATE_VERSION) {
+            record.delegated = { ...record.delegated, recoveryHistory: [] };
+        }
         records.set(`${sessionId}::${record.workItemId}`, record);
     }
     const keyIndex = new Map();
@@ -556,37 +899,76 @@ export function hydrateWorkflowStateChecked(sessionId) {
     const keyIndexBySession = new Map();
     keyIndexBySession.set(sessionId, keyIndex);
     const planRuns = new Map();
-    if (parsed.version === PERSISTED_WORKFLOW_STATE_VERSION) {
+    if (version >= 2) {
         if (!Array.isArray(parsed.planRuns)) {
             return { status: "invalid", errors: ["version 2 state requires a planRuns array"] };
         }
         const recordsByBareId = new Map([...records.values()].map((record) => [record.workItemId, record]));
         for (const serialized of parsed.planRuns) {
             const runErrors = [];
-            if (!validatePlanRun(serialized, recordsByBareId, sessionId, runErrors)) {
+            if (!validatePlanRun(serialized, recordsByBareId, sessionId, version, runErrors)) {
                 errors.push(...runErrors);
                 continue;
             }
             const run = {
                 ...serialized,
                 tasks: new Map(serialized.tasks.map((task) => [task.taskId, task])),
-                checkpoints: new Map(serialized.checkpoints.map((checkpoint) => [checkpoint.checkpointId, checkpoint])),
+                checkpoints: new Map(serialized.checkpoints.map((checkpoint) => {
+                    const hydrated = version < RECOVERY_STATE_VERSION
+                        ? { ...checkpoint, recoveryHistory: checkpoint.recoveryHistory ?? [] }
+                        : checkpoint;
+                    return [hydrated.checkpointId, hydrated];
+                })),
             };
             planRuns.set(run.runId, run);
         }
     }
+    const executions = new Map();
+    const messageClaims = new Map();
+    if (version >= PERSISTED_WORKFLOW_STATE_VERSION) {
+        if (!Array.isArray(parsed.executions)) {
+            return { status: "invalid", errors: ["version 4 state requires an executions array"] };
+        }
+        for (const serialized of parsed.executions) {
+            const executionErrors = [];
+            if (!validateWorkflowExecution(serialized, sessionId, executionErrors)) {
+                errors.push(...executionErrors);
+                continue;
+            }
+            executions.set(serialized.runId, {
+                ...serialized,
+                tasks: new Map(serialized.tasks),
+                checkpoints: new Map(serialized.checkpoints),
+            });
+        }
+        for (const claim of parsed.messageClaims ?? []) {
+            if (!isNonEmptyString(claim?.messageId) || !isNonEmptyString(claim?.runId)) {
+                errors.push("message claims require messageId and runId");
+                continue;
+            }
+            if (messageClaims.has(claim.messageId)) {
+                errors.push(`message ${claim.messageId} is claimed more than once`);
+                continue;
+            }
+            messageClaims.set(claim.messageId, claim);
+        }
+    }
     if (errors.length > 0) {
         return { status: "invalid", errors };
     }
-    return {
-        status: "valid",
-        data: {
-            nextId: typeof parsed.nextId === "number" ? parsed.nextId : records.size + 1,
-            records,
-            keyIndexBySession,
-            planRuns,
-        },
+    const data = {
+        nextId: typeof parsed.nextId === "number" ? parsed.nextId : records.size + 1,
+        records,
+        keyIndexBySession,
+        planRuns,
+        executions,
+        messageClaims,
     };
+    // Materialize compatibility registry entries for existing native plan runs
+    // that predate the common registry; this never invents authority or alters
+    // native counters.
+    ensureNativeExecutions(data);
+    return { status: "valid", data };
 }
 // START_CONTRACT: hydrateWorkflowState
 //   PURPOSE: Legacy nullable hydrate kept for compatibility with existing callers.
@@ -631,16 +1013,31 @@ export function snapshotWorkflowStateChecked(sessionId, data) {
                 planRuns.push(serializePlanRun(run));
             }
         }
+        const executions = [];
+        const sessionRunIds = new Set();
+        for (const execution of data.executions.values()) {
+            if (execution.sessionId === sessionId) {
+                executions.push(serializeWorkflowExecution(execution));
+                sessionRunIds.add(execution.runId);
+            }
+        }
+        const messageClaims = [];
+        for (const claim of data.messageClaims.values()) {
+            if (sessionRunIds.has(claim.runId))
+                messageClaims.push(claim);
+        }
         const persisted = {
-            // Version 2 carries delegated attempts, decisions, and plan runs;
-            // PERSISTED_WORKFLOW_STATE_VERSION mirrors this literal for hydration.
-            version: 2,
+            // Version 4 adds the common execution registry and session-wide message
+            // claims on top of version 3's recovery histories and report rejections.
+            version: PERSISTED_WORKFLOW_STATE_VERSION,
             updatedAt: new Date().toISOString(),
             sessionId,
             nextId: data.nextId,
             records,
             keyIndex,
             planRuns,
+            executions,
+            messageClaims,
         };
         const targetPath = getWorkflowStatePath(sessionId);
         const temporaryPath = `${targetPath}.tmp-${process.pid}-${Date.now()}`;