@cassiomc1/forgeloop 1.3.0 → 1.6.0

package/src/core/task-lock.js

@@ -1,10 +1,13 @@
 import { randomUUID } from "node:crypto";
-import { mkdir, open, readFile, unlink } from "node:fs/promises";
+import { link, mkdir, open, readFile, rename, unlink } from "node:fs/promises";
 import path from "node:path";
 import os from "node:os";
 import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
 import { taskLockPath } from "./task-paths.js";
-import { E_TASK_LOCKED } from "./error-codes.js";
+import {
+  E_PROJECT_CLAIMS_LOCK_INCONSISTENT,
+  E_TASK_LOCKED,
+} from "./error-codes.js";
 
 export async function readLockInfo(target, taskId) {
   const relativePath = taskLockPath(taskId);
@@ -23,14 +26,50 @@ export async function readLockInfo(target, taskId) {
   }
 }
 
-export function classifyLockStaleness(lock, now = Date.now()) {
-  if (!lock || lock.corrupted) return { status: "UNKNOWN", stale: false };
+/**
+ * Structural identity requirements shared by every persisted lease lock.
+ * Incomplete identity is UNKNOWN and is never eligible for stale release;
+ * default lease values belong at creation time, never validation time.
+ */
+function hasLeaseIdentity(lock) {
+  return typeof lock.lockId === "string"
+    && lock.lockId !== ""
+    && typeof lock.ownerInstanceId === "string"
+    && lock.ownerInstanceId !== ""
+    && typeof lock.operation === "string"
+    && lock.operation !== ""
+    && Number.isInteger(lock.leaseMs)
+    && lock.leaseMs > 0;
+}
+
+export function isValidTaskLockIdentity(lock) {
+  return Boolean(lock)
+    && !lock.corrupted
+    && typeof lock.taskId === "string"
+    && lock.taskId !== ""
+    && hasLeaseIdentity(lock);
+}
+
+export function isValidProjectClaimsLockIdentity(lock) {
+  return Boolean(lock)
+    && !lock.corrupted
+    && lock.scope === "claims-reservation"
+    && hasLeaseIdentity(lock);
+}
+
+function classifyLeaseWindow(lock, now) {
   const heartbeat = Date.parse(lock.heartbeatAt ?? lock.acquiredAt);
-  const leaseMs = Number.isInteger(lock.leaseMs) && lock.leaseMs > 0 ? lock.leaseMs : 300000;
   if (!Number.isFinite(heartbeat)) return { status: "UNKNOWN", stale: false };
-  return now > heartbeat + leaseMs
-    ? { status: "STALE", stale: true, expiresAt: new Date(heartbeat + leaseMs).toISOString() }
-    : { status: "LIVE", stale: false, expiresAt: new Date(heartbeat + leaseMs).toISOString() };
+  return now > heartbeat + lock.leaseMs
+    ? { status: "STALE", stale: true, expiresAt: new Date(heartbeat + lock.leaseMs).toISOString() }
+    : { status: "LIVE", stale: false, expiresAt: new Date(heartbeat + lock.leaseMs).toISOString() };
+}
+
+export function classifyLockStaleness(lock, now = Date.now()) {
+  if (!lock) return { status: "NONE", stale: false };
+  if (lock.corrupted) return { status: "CORRUPT", stale: false };
+  if (!isValidTaskLockIdentity(lock)) return { status: "UNKNOWN", stale: false };
+  return classifyLeaseWindow(lock, now);
 }
 
 /**
@@ -60,6 +99,75 @@ export async function readProjectClaimsLockInfo(target) {
   }
 }
 
+export function classifyProjectClaimsLock(lock, now = Date.now()) {
+  if (!lock) return { status: "NONE", stale: false };
+  if (lock.corrupted) return { status: "CORRUPT", stale: false };
+  if (!isValidProjectClaimsLockIdentity(lock)) return { status: "UNKNOWN", stale: false };
+  return classifyLeaseWindow(lock, now);
+}
+
+function projectClaimsLockError(classification, lockInfo, reason = null) {
+  if (classification.status === "LIVE") {
+    const error = new Error(
+      `Project write claims reservation is locked by operation "${lockInfo?.operation ?? "unknown"}" (pid: ${lockInfo?.pid ?? "unknown"}, acquired: ${lockInfo?.acquiredAt ?? "unknown"}).`,
+    );
+    error.code = E_TASK_LOCKED;
+    error.lockInfo = lockInfo;
+    error.classification = classification;
+    return error;
+  }
+  const error = new Error(
+    `Project write claims lock ownership is ${classification.status}${reason ? ` (${reason})` : ""}; refusing unsafe claim mutation`,
+  );
+  error.code = E_PROJECT_CLAIMS_LOCK_INCONSISTENT;
+  error.lockInfo = lockInfo;
+  error.classification = classification;
+  if (reason) error.reason = reason;
+  return error;
+}
+
+export async function releaseStaleProjectClaimsLockIfUnchanged(target, expectedLock, { now = Date.now() } = {}) {
+  await assertSafePath(target, CLAIMS_LOCK_REL_PATH);
+  const fullPath = ensureWithin(target, CLAIMS_LOCK_REL_PATH);
+  const expectedClassification = classifyProjectClaimsLock(expectedLock, now);
+  if (expectedClassification.status !== "STALE") {
+    return { released: false, reason: "EXPECTED_LOCK_NOT_STALE", classification: expectedClassification };
+  }
+
+  const quarantinePath = `${fullPath}.releasing-${randomUUID()}`;
+  try {
+    await rename(fullPath, quarantinePath);
+  } catch (error) {
+    if (error.code === "ENOENT") return { released: false, reason: "LOCK_MISSING" };
+    throw error;
+  }
+
+  let observed;
+  try {
+    observed = JSON.parse(await readFile(quarantinePath, "utf8"));
+  } catch {
+    await restoreQuarantinedLock(quarantinePath, fullPath);
+    return { released: false, reason: "LOCK_CORRUPT", classification: { status: "CORRUPT", stale: false } };
+  }
+
+  const observedClassification = classifyProjectClaimsLock(observed, now);
+  if (!sameObservedLock(observed, expectedLock, { identityIsValid: isValidProjectClaimsLockIdentity })
+    || observedClassification.status !== "STALE") {
+    await restoreQuarantinedLock(quarantinePath, fullPath);
+    return {
+      released: false,
+      reason: sameObservedLock(observed, expectedLock, { identityIsValid: isValidProjectClaimsLockIdentity })
+        ? "LOCK_NOT_STALE"
+        : "LOCK_CHANGED",
+      currentLock: observed,
+      classification: observedClassification,
+    };
+  }
+
+  await unlink(quarantinePath);
+  return { released: true, previousLock: observed, classification: observedClassification };
+}
+
 export async function acquireProjectClaimsLock(target, operation = "claim-reservation") {
   await assertSafePath(target, CLAIMS_LOCK_REL_PATH);
   const fullPath = ensureWithin(target, CLAIMS_LOCK_REL_PATH);
@@ -80,20 +188,29 @@ export async function acquireProjectClaimsLock(target, operation = "claim-reserv
     leaseMs: 300000,
   };
 
-  let fileHandle;
-  try {
-    fileHandle = await open(fullPath, "wx");
-  } catch (error) {
-    if (error.code === "EEXIST") {
+  let fileHandle = null;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      fileHandle = await open(fullPath, "wx");
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
       const existing = await readProjectClaimsLockInfo(target);
-      const err = new Error(
-        `Project write claims reservation is locked by operation "${existing?.operation ?? "unknown"}" (pid: ${existing?.pid ?? "unknown"}, acquired: ${existing?.acquiredAt ?? "unknown"}).`,
-      );
-      err.code = E_TASK_LOCKED;
-      err.lockInfo = existing;
-      throw err;
+      const classification = classifyProjectClaimsLock(existing);
+      if (classification.status === "STALE" && attempt === 0) {
+        const released = await releaseStaleProjectClaimsLockIfUnchanged(target, existing);
+        if (released.released || released.reason === "LOCK_MISSING") continue;
+        throw projectClaimsLockError(
+          released.classification ?? { status: "UNKNOWN", stale: false },
+          released.currentLock ?? existing,
+          released.reason,
+        );
+      }
+      throw projectClaimsLockError(classification, existing);
     }
-    throw error;
+  }
+  if (!fileHandle) {
+    throw projectClaimsLockError({ status: "UNKNOWN", stale: false }, null, "ACQUISITION_RETRY_EXHAUSTED");
   }
 
   try {
@@ -222,13 +339,90 @@ export async function forceUnlockTask(target, taskId, { staleOnly = false } = {}
 
   const existing = await readLockInfo(target, taskId);
   const classification = classifyLockStaleness(existing);
-  if (staleOnly && !classification.stale) {
-    return { unlocked: false, previousLock: existing, classification };
+  if (staleOnly) {
+    if (!classification.stale) {
+      return { unlocked: false, previousLock: existing, classification };
+    }
+    const released = await releaseStaleTaskLockIfUnchanged(target, taskId, existing);
+    return {
+      unlocked: released.released,
+      previousLock: released.previousLock ?? existing,
+      classification: released.classification ?? classification,
+      ...(released.reason ? { reason: released.reason } : {}),
+    };
   }
   await unlink(fullPath);
   return { unlocked: true, previousLock: existing, classification };
 }
 
+function sameObservedLock(left, right, { identityIsValid = isValidTaskLockIdentity } = {}) {
+  if (!identityIsValid(left) || !identityIsValid(right)) return false;
+  return left.lockId === right.lockId
+    && left.heartbeatAt === right.heartbeatAt
+    && left.ownerInstanceId === right.ownerInstanceId;
+}
+
+function sameObservedTaskLock(left, right, taskId) {
+  return taskId !== null
+    && sameObservedLock(left, right)
+    && left.taskId === right.taskId
+    && right.taskId === taskId;
+}
+
+async function restoreQuarantinedLock(quarantinePath, fullPath) {
+  try {
+    await link(quarantinePath, fullPath);
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+  } finally {
+    try {
+      await unlink(quarantinePath);
+    } catch {
+      // ignore an already-consumed quarantine entry
+    }
+  }
+}
+
+export async function releaseStaleTaskLockIfUnchanged(target, taskId, expectedLock, { now = Date.now() } = {}) {
+  const relativePath = taskLockPath(taskId);
+  await assertSafePath(target, relativePath);
+  const fullPath = ensureWithin(target, relativePath);
+  const expectedClassification = classifyLockStaleness(expectedLock, now);
+  if (expectedClassification.status !== "STALE") {
+    return { released: false, reason: "EXPECTED_LOCK_NOT_STALE", classification: expectedClassification };
+  }
+
+  const quarantinePath = `${fullPath}.releasing-${randomUUID()}`;
+  try {
+    await rename(fullPath, quarantinePath);
+  } catch (error) {
+    if (error.code === "ENOENT") return { released: false, reason: "LOCK_MISSING" };
+    throw error;
+  }
+
+  let observed;
+  try {
+    observed = JSON.parse(await readFile(quarantinePath, "utf8"));
+  } catch {
+    await restoreQuarantinedLock(quarantinePath, fullPath);
+    return { released: false, reason: "LOCK_CORRUPT" };
+  }
+
+  const observedClassification = classifyLockStaleness(observed, now);
+  if (!sameObservedTaskLock(observed, expectedLock, taskId) || observedClassification.status !== "STALE") {
+    await restoreQuarantinedLock(quarantinePath, fullPath);
+    return {
+      released: false,
+      reason: sameObservedTaskLock(observed, expectedLock, taskId) ? "LOCK_NOT_STALE" : "LOCK_CHANGED",
+      currentLock: observed,
+      classification: observedClassification,
+    };
+  }
+
+  await unlink(quarantinePath);
+  return { released: true, previousLock: observed, classification: observedClassification };
+}
+
 export async function withTaskLock(target, taskId, operationOrCallback, callback) {
   let operation = operationOrCallback;
   let fn = callback;

package/src/core/task-paths.js

@@ -15,8 +15,11 @@ export const TASK_ARTIFACT_FILES = Object.freeze({
   events: "events.ndjson",
   gates: "gates",
   executions: "executions",
-  lock: ".lock",
+  actions: "actions",
+  approvals: "approvals",
+  evaluations: "evaluations",
   policySnapshot: "policy-snapshot.json",
+  recovery: "recovery.json",
 });
 
 export const POLICY_ROOT = ".forgeloop/policy";
@@ -32,6 +35,7 @@ export const PROJECT_ARTIFACT_PATHS = Object.freeze({
   policyBaseline: ".forgeloop/policy/baseline.json",
   policyLock: ".forgeloop/policy/policy.lock",
   policyDiscovery: ".forgeloop/policy/discovery.json",
+  capabilityPolicy: ".forgeloop/policy/capabilities.json",
 });
 
 export const LEGACY_TASK_ARTIFACT_PATHS = Object.freeze({
@@ -74,6 +78,27 @@ export function taskExecutionPath(taskId, executionId) {
   return `${taskDirectory(taskId)}/${TASK_ARTIFACT_FILES.executions}/${executionId}.json`;
 }
 
+export function taskActionPath(taskId, actionId) {
+  if (typeof actionId !== "string" || !/^action-[A-Za-z0-9_-]+$/.test(actionId)) {
+    throw new Error(`Invalid action ID: ${actionId}`);
+  }
+  return `${taskDirectory(taskId)}/${TASK_ARTIFACT_FILES.actions}/${actionId}.json`;
+}
+
+export function taskApprovalPath(taskId, approvalId) {
+  if (typeof approvalId !== "string" || !/^approval-[A-Za-z0-9_-]+$/.test(approvalId)) {
+    throw new Error(`Invalid approval ID: ${approvalId}`);
+  }
+  return `${taskDirectory(taskId)}/${TASK_ARTIFACT_FILES.approvals}/${approvalId}.json`;
+}
+
+export function taskEvaluationPath(taskId, evaluationId) {
+  if (typeof evaluationId !== "string" || !/^eval-[A-Za-z0-9_-]+$/.test(evaluationId)) {
+    throw new Error(`Invalid evaluation ID: ${evaluationId}`);
+  }
+  return `${taskDirectory(taskId)}/${TASK_ARTIFACT_FILES.evaluations}/${evaluationId}.json`;
+}
+
 export function taskLockPath(taskId) {
   assertTaskId(taskId);
   return `${TASK_LOCK_ROOT}/${taskStorageKey(taskId)}.lock`;
@@ -101,7 +126,11 @@ export function buildTaskArtifactPaths(taskId) {
     events: `${dir}/${TASK_ARTIFACT_FILES.events}`,
     gates: `${dir}/${TASK_ARTIFACT_FILES.gates}`,
     executions: `${dir}/${TASK_ARTIFACT_FILES.executions}`,
-    lock: `${dir}/${TASK_ARTIFACT_FILES.lock}`,
+    actions: `${dir}/${TASK_ARTIFACT_FILES.actions}`,
+    approvals: `${dir}/${TASK_ARTIFACT_FILES.approvals}`,
+    evaluations: `${dir}/${TASK_ARTIFACT_FILES.evaluations}`,
+    lock: taskLockPath(taskId),
     policySnapshot: `${dir}/${TASK_ARTIFACT_FILES.policySnapshot}`,
+    recovery: `${dir}/${TASK_ARTIFACT_FILES.recovery}`,
   });
 }

package/src/core/task-recovery-migration.js

@@ -0,0 +1,192 @@
+import { createHash } from "node:crypto";
+
+/**
+ * Canonical, limited, auditable repair path for one known historical defect:
+ * an `OPERATOR_RECOVERY_RECORDED` event written by an early adapter whose
+ * `details` carried only `{ classification, reasonCodes, authorization, note }`
+ * and none of the modern recovery identity fields (most notably `recoveryId`).
+ *
+ * Invariants:
+ * - The strict validator stays the default. An unmigrated legacy event keeps
+ *   the ledger invalid (fail closed, INCONSISTENT ownership).
+ * - Existing ledger events are never rewritten, removed, or edited. Repair
+ *   appends exactly one `LEGACY_RECOVERY_MIGRATION_RECORDED` event per legacy
+ *   event at the current ledger tail, binding it by taskId, seq, hash, and a
+ *   deterministic recoveryId.
+ * - Only the exact known legacy signature is eligible. Any other incomplete
+ *   recovery event (including a modern `TASK_RECOVERY_RECORDED` without
+ *   `recoveryId`) remains invalid. Ambiguity stays INCONSISTENT.
+ * - The migration event is the canonical recovery record for the repaired
+ *   state; it carries the complete modern recovery projection plus an
+ *   immutable binding to the historical source. The original legacy event
+ *   remains unchanged and independently recognizable as legacy evidence.
+ * - Migration authority is always CALLER_ACKNOWLEDGED from a fresh explicit
+ *   caller acknowledgement. Legacy authorization values are preserved only as
+ *   historical metadata and never grant current authority.
+ */
+
+export const LEGACY_RECOVERY_MIGRATION_EVENT = "LEGACY_RECOVERY_MIGRATION_RECORDED";
+export const LEGACY_RECOVERY_DEFECT = "OPERATOR_RECOVERY_RECORDED_WITHOUT_RECOVERY_ID";
+export const LEGACY_RECOVERY_MIGRATION_ID_DOMAIN = "forgeloop:legacy-recovery-migration:v1";
+export const MIGRATED_RECOVERY_CLASSIFICATION = "LEGACY_BOUNDARY_MIGRATED";
+
+const LEGACY_DETAIL_KEYS = Object.freeze([
+  "classification",
+  "reasonCodes",
+  "authorization",
+  "note",
+]);
+
+// Legacy migration v1 is caller-acknowledged only: the official repair
+// command has no host-grant path. Normal recovery authority semantics are
+// unaffected.
+const MIGRATION_AUTHORITY_KINDS = new Set(["CALLER_ACKNOWLEDGED"]);
+const HASH_PATTERN = /^[a-f0-9]{64}$/;
+const ISO_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;
+const SAFE_OBSERVED_CLASSIFICATIONS = new Set([
+  "ACTIVE", "RECOVERABLE", "STALE", "ABANDONED", "COMPLETE", "RECOVERED", "INCONSISTENT",
+]);
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+
+/**
+ * Recognizes ONLY the exact known legacy detail signature. Anything else —
+ * including a near miss with extra or missing keys — is not eligible for
+ * migration. Event-level validation additionally requires taskId, seq, and
+ * hash via {@link isLegacyRecoveryEventShape}.
+ */
+export function isLegacyRecoveryDetailsShape(details) {
+  if (!isPlainObject(details)) return false;
+  const keys = Object.keys(details);
+  if (!keys.every((key) => LEGACY_DETAIL_KEYS.includes(key))) return false;
+  if (details.classification !== "RECOVERABLE") return false;
+  if (details.authorization !== "OPERATOR_AUTHORIZED") return false;
+  if (!Array.isArray(details.reasonCodes)
+    || !details.reasonCodes.every((code) => isNonEmptyString(code))) return false;
+  return isNonEmptyString(details.note);
+}
+
+export function isLegacyRecoveryEventShape(event) {
+  if (event?.event !== "OPERATOR_RECOVERY_RECORDED") return false;
+  if (!isLegacyRecoveryDetailsShape(event.details)) return false;
+  if (!isNonEmptyString(event.taskId)) return false;
+  if (!Number.isInteger(event.seq) || event.seq < 1) return false;
+  return typeof event.hash === "string" && HASH_PATTERN.test(event.hash);
+}
+
+/**
+ * Deterministic canonical binding between a legacy recovery event and its
+ * official migration event. The value is formatted to satisfy the durable
+ * task-recovery artifact's recoveryId pattern (`recovery-…`).
+ */
+export function legacyRecoveryMigrationId({ taskId, seq, hash }) {
+  if (!isNonEmptyString(taskId) || !Number.isInteger(seq) || !isNonEmptyString(hash)) {
+    throw new Error("legacyRecoveryMigrationId requires taskId, seq, and hash");
+  }
+  const digest = createHash("sha256")
+    .update(`${LEGACY_RECOVERY_MIGRATION_ID_DOMAIN}:${taskId}:${seq}:${hash}`)
+    .digest("hex");
+  return `recovery-legacy-${digest}`;
+}
+
+const MIGRATED_RECOVERY_ID_PATTERN = /^recovery-legacy-[a-f0-9]{64}$/;
+
+function assertNonEmptyIsoTimestamp(value, field) {
+  if (!isNonEmptyString(value) || !ISO_TIMESTAMP_PATTERN.test(value)) {
+    throw protocolError(`legacy migration event details.${field} must be an ISO-8601 UTC timestamp`);
+  }
+}
+
+/**
+ * Strict details validation for appended migration events. Mirrors the
+ * assert* helpers in events.js; throws E_EVENT_INVALID on any deviation.
+ *
+ * Required shape:
+ * - immutable legacy binding: defect, legacyEventSeq, legacyEventHash,
+ *   legacyEventAt, legacyTaskId, legacyClassification, legacyAuthority,
+ *   legacyNote
+ * - complete modern recovery projection: recoveryId, classification
+ *   (always LEGACY_BOUNDARY_MIGRATED), reasonCodes, releasedClaims,
+ *   previousPhase, previousRevision, currentBranch, currentHead,
+ *   recoveredAt, repairObservedClassification,
+ *   repairObservedReasonCodes, authorityKind. Historical values
+ *   (legacyClassification, legacyAuthority, legacyEventAt) are metadata only.
+ */
+export function assertLegacyMigrationDetails(details) {
+  if (!isPlainObject(details)) {
+    throw protocolError("legacy migration event requires structured details");
+  }
+  for (const key of [
+    "recoveryId",
+    "defect",
+    "legacyEventType",
+    "legacyEventHash",
+    "legacyEventAt",
+    "legacyTaskId",
+    "legacyClassification",
+    "legacyAuthority",
+    "classification",
+    "previousPhase",
+    "repairObservedClassification",
+    "authorityKind",
+  ]) {
+    if (!isNonEmptyString(details[key])) {
+      throw protocolError(`legacy migration event details.${key} must be a non-empty string`);
+    }
+  }
+  assertNonEmptyIsoTimestamp(details.legacyEventAt, "legacyEventAt");
+  assertNonEmptyIsoTimestamp(details.recoveredAt, "recoveredAt");
+  if (!MIGRATED_RECOVERY_ID_PATTERN.test(details.recoveryId)) {
+    throw protocolError("legacy migration event details.recoveryId must be a deterministic recovery-legacy-<sha256> identifier");
+  }
+  if (!HASH_PATTERN.test(details.legacyEventHash)) {
+    throw protocolError("legacy migration event details.legacyEventHash must be a lowercase sha256 hex string");
+  }
+  if (details.defect !== LEGACY_RECOVERY_DEFECT) {
+    throw protocolError(`legacy migration event details.defect must be ${LEGACY_RECOVERY_DEFECT}`);
+  }
+  if (details.classification !== MIGRATED_RECOVERY_CLASSIFICATION) {
+    throw protocolError(`legacy migration event details.classification must be ${MIGRATED_RECOVERY_CLASSIFICATION}`);
+  }
+  if (!Number.isInteger(details.legacyEventSeq) || details.legacyEventSeq < 1) {
+    throw protocolError("legacy migration event details.legacyEventSeq must be a positive integer");
+  }
+  for (const key of ["currentBranch", "currentHead"]) {
+    if (details[key] !== null && !isNonEmptyString(details[key])) {
+      throw protocolError(`legacy migration event details.${key} must be a non-empty string or null`);
+    }
+  }
+  if (!MIGRATION_AUTHORITY_KINDS.has(details.authorityKind)) {
+    throw protocolError("legacy migration event details.authorityKind is invalid");
+  }
+  if (!SAFE_OBSERVED_CLASSIFICATIONS.has(details.repairObservedClassification)) {
+    throw protocolError("legacy migration event details.repairObservedClassification is invalid");
+  }
+  if (!Array.isArray(details.reasonCodes)
+    || !details.reasonCodes.every((code) => isNonEmptyString(code))) {
+    throw protocolError("legacy migration event details.reasonCodes must be an array of non-empty strings");
+  }
+  if (!Array.isArray(details.releasedClaims)
+    || !details.releasedClaims.every((claim) => isNonEmptyString(claim))) {
+    throw protocolError("legacy migration event details.releasedClaims must be an array of non-empty strings");
+  }
+  if (!Array.isArray(details.repairObservedReasonCodes)
+    || !details.repairObservedReasonCodes.every((code) => isNonEmptyString(code))) {
+    throw protocolError("legacy migration event details.repairObservedReasonCodes must be an array of non-empty strings");
+  }
+  if (!Number.isInteger(details.previousRevision) || details.previousRevision < 0) {
+    throw protocolError("legacy migration event details.previousRevision must be a non-negative integer");
+  }
+}
+
+function protocolError(message) {
+  const error = new Error(message);
+  error.code = "E_EVENT_INVALID";
+  return error;
+}