@cassiomc1/forgeloop 1.2.4 → 1.5.0

package/src/core/task-lock.js

@@ -1,9 +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);
@@ -22,6 +26,61 @@ export async function readLockInfo(target, taskId) {
   }
 }
 
+/**
+ * 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);
+  if (!Number.isFinite(heartbeat)) return { status: "UNKNOWN", stale: false };
+  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);
+}
+
+/**
+ * PID values can be reused. Pairing the PID with the process start epoch gives
+ * a portable, serializable ownership token without a daemon or platform-only
+ * process inspector. Consumers must still treat remote owners as unknown.
+ */
+export function currentProcessStartToken(now = Date.now(), uptimeSeconds = process.uptime()) {
+  return `${process.pid}:${Math.max(0, Math.floor(now - (uptimeSeconds * 1000)))}`;
+}
+
 export const CLAIMS_LOCK_REL_PATH = ".forgeloop/.claims.lock";
 
 export async function readProjectClaimsLockInfo(target) {
@@ -40,34 +99,118 @@ 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);
 
   await mkdir(path.dirname(fullPath), { recursive: true });
 
+  const acquiredAt = new Date().toISOString();
   const lockData = {
     lockId: randomUUID(),
     scope: "claims-reservation",
     operation,
     pid: process.pid,
-    acquiredAt: new Date().toISOString(),
+    hostname: os.hostname(),
+    processStartToken: currentProcessStartToken(),
+    ownerInstanceId: randomUUID(),
+    acquiredAt,
+    heartbeatAt: acquiredAt,
+    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 {
@@ -123,12 +266,18 @@ export async function acquireTaskLock(target, taskId, operation = "mutation") {
 
   await mkdir(path.dirname(fullPath), { recursive: true });
 
+  const acquiredAt = new Date().toISOString();
   const lockData = {
     lockId: randomUUID(),
     taskId,
     operation,
     pid: process.pid,
-    acquiredAt: new Date().toISOString(),
+    hostname: os.hostname(),
+    processStartToken: currentProcessStartToken(),
+    ownerInstanceId: randomUUID(),
+    acquiredAt,
+    heartbeatAt: acquiredAt,
+    leaseMs: 300000,
   };
 
   let fileHandle;
@@ -179,7 +328,7 @@ export async function acquireTaskLock(target, taskId, operation = "mutation") {
   }
 }
 
-export async function forceUnlockTask(target, taskId) {
+export async function forceUnlockTask(target, taskId, { staleOnly = false } = {}) {
   const relativePath = taskLockPath(taskId);
   await assertSafePath(target, relativePath);
   const fullPath = ensureWithin(target, relativePath);
@@ -189,8 +338,89 @@ export async function forceUnlockTask(target, taskId) {
   }
 
   const existing = await readLockInfo(target, taskId);
+  const classification = classifyLockStaleness(existing);
+  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 };
+  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) {

package/src/core/task-migration.js

@@ -1,6 +1,6 @@
 import { cp, mkdir, rename, rm } from "node:fs/promises";
 import path from "node:path";
-import { ensureWithin, fileExists } from "./filesystem.js";
+import { ensureWithin, fileExists, writeFileAtomic } from "./filesystem.js";
 import { getPackageRoot } from "./templates.js";
 import {
   LEGACY_TASK_ARTIFACT_PATHS,
@@ -308,6 +308,23 @@ export async function migrateLegacyLayout(
     assertMigrationSnapshotsEqual(sourceSnapshot, finalSnapshot, "published namespace");
     await readTaskDescriptor(target, canonicalTaskId, packageRoot);
 
+    const migrationReceipt = {
+      schemaVersion: 1,
+      protocolVersion: 1,
+      kind: "LEGACY_TASK_MIGRATION",
+      taskId: canonicalTaskId,
+      taskKey,
+      migratedAt: new Date().toISOString(),
+      source: sourceSnapshot,
+      destination: finalSnapshot,
+      cleanupStatus: "PENDING",
+    };
+    await writeFileAtomic(
+      ensureWithin(target, `${finalDirRel}/migration-receipt.json`),
+      `${JSON.stringify(migrationReceipt, null, 2)}\n`,
+    );
+    migratedArtifacts.push("migration-receipt.json");
+
     // Test hook for cleanup failure testing
     if (typeof beforeLegacyCleanupForTest === "function") {
       await beforeLegacyCleanupForTest({ finalDirAbs, finalDirRel, target });
@@ -323,6 +340,12 @@ export async function migrateLegacyLayout(
           await removeLegacyArtifact(target, item.path);
         }
       }
+      migrationReceipt.cleanupStatus = "COMPLETED";
+      migrationReceipt.cleanedAt = new Date().toISOString();
+      await writeFileAtomic(
+        ensureWithin(target, `${finalDirRel}/migration-receipt.json`),
+        `${JSON.stringify(migrationReceipt, null, 2)}\n`,
+      );
     } catch (cleanupErr) {
       const error = new Error(
         `Migration published successfully to ${finalDirRel}, but legacy cleanup failed: ${cleanupErr.message}. Manual cleanup required.`,

package/src/core/task-paths.js

@@ -1,6 +1,7 @@
 import { assertTaskId, taskStorageKey } from "./task-identity.js";
 
 export const TASK_STATE_ROOT = ".forgeloop/task-state";
+export const TASK_LOCK_ROOT = ".forgeloop/locks";
 export const SESSIONS_ROOT = ".forgeloop/sessions";
 
 export const TASK_ARTIFACT_FILES = Object.freeze({
@@ -14,8 +15,8 @@ export const TASK_ARTIFACT_FILES = Object.freeze({
   events: "events.ndjson",
   gates: "gates",
   executions: "executions",
-  lock: ".lock",
   policySnapshot: "policy-snapshot.json",
+  recovery: "recovery.json",
 });
 
 export const POLICY_ROOT = ".forgeloop/policy";
@@ -74,7 +75,8 @@ export function taskExecutionPath(taskId, executionId) {
 }
 
 export function taskLockPath(taskId) {
-  return taskArtifactPath(taskId, "lock");
+  assertTaskId(taskId);
+  return `${TASK_LOCK_ROOT}/${taskStorageKey(taskId)}.lock`;
 }
 
 export function sessionArtifactPath(sessionId) {
@@ -99,7 +101,8 @@ 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}`,
+    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;
+}