@cassiomc1/forgeloop 1.1.1 → 1.2.2

package/src/core/diagnosis.js

@@ -0,0 +1,171 @@
+import { appendProtocolEvent, validateEventLedger } from "./events.js";
+import { readWorkState, writeWorkState } from "./work-state.js";
+import {
+  DIAGNOSIS_INFORMATION_GAIN,
+  assertDiagnosisDetails,
+  classifyDiagnosisInformationGain,
+  createDiagnosisDetails,
+  currentCycleDiagnosis,
+  diagnosisEventsForTask,
+  diagnosisFingerprint,
+  normalizeDiagnosisText,
+} from "./diagnosis-model.js";
+
+export {
+  DIAGNOSIS_INFORMATION_GAIN,
+  assertDiagnosisDetails,
+  classifyDiagnosisInformationGain,
+  createDiagnosisDetails,
+  currentCycleDiagnosis,
+  diagnosisEventsForTask,
+  diagnosisFingerprint,
+  normalizeDiagnosisText,
+};
+
+export async function recordDiagnosis({
+  target,
+  packageRoot,
+  hypothesis,
+  failureClass,
+  evidenceRefs,
+  settledBy,
+  nextSafeAction,
+  taskId = null,
+  statePath = null,
+  eventsPath = null,
+}) {
+  const state = await readWorkState(target, { packageRoot, taskId, statePath });
+  if (!state) {
+    const error = new Error("Work state not found");
+    error.code = "E_STATE_MISSING";
+    throw error;
+  }
+  if (state.phase !== "DIAGNOSING") {
+    const error = new Error(`Recording a diagnosis requires phase DIAGNOSING, currently ${state.phase}`);
+    error.code = "E_PHASE_PREREQUISITE_MISSING";
+    throw error;
+  }
+  if (typeof state.verificationCycle !== "number" || state.verificationCycle < 1) {
+    const error = new Error("Active verification cycle must be an integer >= 1");
+    error.code = "E_DIAGNOSIS_INVALID";
+    throw error;
+  }
+
+  const ledger = await validateEventLedger(target, packageRoot, { taskId: taskId ?? null, eventsPath });
+  if (!ledger.valid) {
+    const first = ledger.errors[0];
+    const error = new Error(first.message);
+    error.code = first.code;
+    throw error;
+  }
+
+  const verificationStarted = ledger.events.some(
+    (e) => e.taskId === state.taskId && e.event === "VERIFICATION_STARTED",
+  );
+  if (!verificationStarted) {
+    const error = new Error("No VERIFICATION_STARTED event found for active cycle");
+    error.code = "E_PHASE_CHRONOLOGY_INVALID";
+    throw error;
+  }
+
+  const currentCycleChecks = (state.checks ?? []).filter(
+    (c) => c.details?.verificationCycle === state.verificationCycle,
+  );
+
+  const cleanRefs = (evidenceRefs ?? []).map((r) => String(r).trim()).filter(Boolean);
+  if (cleanRefs.length === 0) {
+    const error = new Error("record-diagnosis requires at least one evidenceRef");
+    error.code = "E_DIAGNOSIS_EVIDENCE_INVALID";
+    throw error;
+  }
+
+  const matchedChecks = [];
+  for (const ref of cleanRefs) {
+    const check = currentCycleChecks.find((c) => (c.id === ref || c.checkId === ref));
+    if (!check) {
+      const error = new Error(`Evidence reference "${ref}" does not match any check from verification cycle ${state.verificationCycle}`);
+      error.code = "E_DIAGNOSIS_EVIDENCE_INVALID";
+      throw error;
+    }
+    matchedChecks.push(check);
+  }
+
+  const hasFailedOrBlocked = matchedChecks.some((c) => c.status === "failed" || c.status === "blocked");
+  if (!hasFailedOrBlocked) {
+    const error = new Error("Diagnosis evidenceRefs must include at least one failed or blocked check from the current cycle");
+    error.code = "E_DIAGNOSIS_EVIDENCE_INVALID";
+    throw error;
+  }
+
+  const existingEvent = currentCycleDiagnosis(
+    ledger.events,
+    state.taskId,
+    state.verificationCycle,
+  );
+
+  const requestedFingerprint = diagnosisFingerprint({
+    failureClass,
+    hypothesis,
+    evidenceRefs: cleanRefs,
+  });
+
+  if (existingEvent?.details?.diagnosisFingerprint === requestedFingerprint) {
+    const updatedState = {
+      ...state,
+      diagnosedHypothesis: existingEvent.details.hypothesis,
+      lastUpdated: new Date().toISOString(),
+    };
+    await writeWorkState(target, updatedState, {
+      packageRoot,
+      taskId: taskId ?? null,
+      statePath,
+    });
+    return {
+      event: existingEvent,
+      state: updatedState,
+      diagnosis: existingEvent.details,
+      idempotent: true,
+    };
+  }
+
+  const taskDiagnosisEvents = diagnosisEventsForTask(ledger.events, state.taskId);
+  const previousEvent = taskDiagnosisEvents.at(-1) ?? null;
+  const previousDetails = previousEvent?.details ?? null;
+
+  const details = createDiagnosisDetails(
+    {
+      verificationCycle: state.verificationCycle,
+      failureClass,
+      hypothesis,
+      evidenceRefs: cleanRefs,
+      settledBy,
+      nextSafeAction,
+    },
+    previousDetails,
+  );
+
+  const event = await appendProtocolEvent(
+    target,
+    {
+      taskId: state.taskId,
+      event: "DIAGNOSIS_RECORDED",
+      details,
+    },
+    packageRoot,
+    { taskId: taskId ?? null, eventsPath },
+  );
+
+  const updatedState = {
+    ...state,
+    diagnosedHypothesis: hypothesis.trim(),
+    lastUpdated: new Date().toISOString(),
+  };
+  await writeWorkState(target, updatedState, { packageRoot, taskId: taskId ?? null, statePath });
+
+  return {
+    event,
+    state: updatedState,
+    diagnosis: details,
+    idempotent: false,
+  };
+}

package/src/core/error-codes.js

@@ -30,6 +30,24 @@ export const E_TASK_LAYOUT_LEGACY = "E_TASK_LAYOUT_LEGACY";
 export const E_TASK_MIGRATION_INVALID = "E_TASK_MIGRATION_INVALID";
 export const E_TASK_MIGRATION_IDENTITY_MISMATCH = "E_TASK_MIGRATION_IDENTITY_MISMATCH";
 
+export const E_DIAGNOSIS_REQUIRED = "E_DIAGNOSIS_REQUIRED";
+export const E_DIAGNOSIS_INVALID = "E_DIAGNOSIS_INVALID";
+export const E_DIAGNOSIS_EVIDENCE_INVALID = "E_DIAGNOSIS_EVIDENCE_INVALID";
+export const E_DIAGNOSIS_CYCLE_MISMATCH = "E_DIAGNOSIS_CYCLE_MISMATCH";
+export const E_DIAGNOSIS_NO_NEW_INFORMATION = "E_DIAGNOSIS_NO_NEW_INFORMATION";
+export const E_PROGRESS_STALLED = "E_PROGRESS_STALLED";
+export const E_DECISION_CRITERION_INVALID = "E_DECISION_CRITERION_INVALID";
+export const E_DECISION_NOT_UNRESOLVED = "E_DECISION_NOT_UNRESOLVED";
+
+export const E_RECONCILE_NOT_STALE = "E_RECONCILE_NOT_STALE";
+export const E_RECONCILE_PHASE_INVALID = "E_RECONCILE_PHASE_INVALID";
+export const E_RECONCILE_UNSUPPORTED_DRIFT = "E_RECONCILE_UNSUPPORTED_DRIFT";
+export const E_RECONCILE_LEDGER_INVALID = "E_RECONCILE_LEDGER_INVALID";
+export const E_RECONCILE_REQUIREMENT_UNKNOWN = "E_RECONCILE_REQUIREMENT_UNKNOWN";
+export const E_RECONCILE_EVIDENCE_FAILED = "E_RECONCILE_EVIDENCE_FAILED";
+export const E_REPOSITORY_CHANGED = "E_REPOSITORY_CHANGED";
+export const E_STATE_REVALIDATION_REQUIRED = "E_STATE_REVALIDATION_REQUIRED";
+
 /**
  * Public, stable ForgeLoop error and reason codes documented for users and harnesses.
  */
@@ -160,8 +178,257 @@ export const PUBLIC_ERROR_CODES = Object.freeze({
     meaning: "Modified paths in repository exceed the declared task write claims.",
     safeResolution: "Update write claims with forgeloop task-scope or revert out-of-scope modifications.",
   }),
+  E_RECONCILE_NOT_STALE: Object.freeze({
+    code: "E_RECONCILE_NOT_STALE",
+    category: "lifecycle",
+    classification: "PUBLIC_STABLE",
+    meaning: "reconcile-closure was invoked for a work-state checkpoint that is already fresh.",
+    safeResolution: "No reconciliation is required; continue the normal lifecycle.",
+  }),
+  E_RECONCILE_PHASE_INVALID: Object.freeze({
+    code: "E_RECONCILE_PHASE_INVALID",
+    category: "lifecycle",
+    classification: "PUBLIC_STABLE",
+    meaning: "reconcile-closure was invoked for a task that is not EXECUTING.",
+    safeResolution: "reconcile-closure supports EXECUTING tasks whose objective is already satisfied.",
+  }),
+  E_RECONCILE_UNSUPPORTED_DRIFT: Object.freeze({
+    code: "E_RECONCILE_UNSUPPORTED_DRIFT",
+    category: "freshness",
+    classification: "PUBLIC_STABLE",
+    meaning: "Work-state drift includes kinds other than REPOSITORY_CHANGED (contract or required-artifact drift).",
+    safeResolution: "Resolve contract or artifact drift through their dedicated recovery surfaces; reconcile-closure only refreshes repository fingerprint drift.",
+  }),
+  E_RECONCILE_LEDGER_INVALID: Object.freeze({
+    code: "E_RECONCILE_LEDGER_INVALID",
+    category: "integrity",
+    classification: "PUBLIC_STABLE",
+    meaning: "The append-only event ledger is not valid, so reconciliation cannot be recorded.",
+    safeResolution: "Inspect the ledger errors and repair before reconciling.",
+  }),
+  E_RECONCILE_REQUIREMENT_UNKNOWN: Object.freeze({
+    code: "E_RECONCILE_REQUIREMENT_UNKNOWN",
+    category: "verification",
+    classification: "PUBLIC_STABLE",
+    meaning: "The supplied check id and requirement text do not exactly match a contract verification item of type VERIFICATION.",
+    safeResolution: "Supply the exact id and requirement text of an existing contract verification item.",
+  }),
+  E_RECONCILE_EVIDENCE_FAILED: Object.freeze({
+    code: "E_RECONCILE_EVIDENCE_FAILED",
+    category: "verification",
+    classification: "PUBLIC_STABLE",
+    meaning: "The executed objective-satisfaction evidence command did not pass.",
+    safeResolution: "Inspect the execution artifact; reconciliation is refused until evidence passes in the current repository.",
+  }),
+  E_REPOSITORY_CHANGED: Object.freeze({
+    code: "E_REPOSITORY_CHANGED",
+    category: "freshness",
+    classification: "PUBLIC_STABLE",
+    meaning: "The repository fingerprint (branch or HEAD) moved after the work-state checkpoint was recorded.",
+    safeResolution: "If the task objective is already satisfied in the current repository, run forgeloop reconcile-closure; otherwise resume from a checkpoint that matches the current repository.",
+  }),
+  E_STATE_REVALIDATION_REQUIRED: Object.freeze({
+    code: "E_STATE_REVALIDATION_REQUIRED",
+    category: "freshness",
+    classification: "PUBLIC_STABLE",
+    meaning: "The work-state checkpoint must be revalidated before the lifecycle can continue.",
+    safeResolution: "Run forgeloop reconcile-closure for externally satisfied EXECUTING tasks, or inspect the freshness reasons for other drift.",
+  }),
+  E_DIAGNOSIS_REQUIRED: Object.freeze({
+    code: "E_DIAGNOSIS_REQUIRED",
+    category: "diagnosis",
+    classification: "PUBLIC_STABLE",
+    meaning: "Current correction cycle has no append-only diagnosis record.",
+    safeResolution: "Run forgeloop record-diagnosis with current failed evidence before correcting.",
+  }),
+  E_DIAGNOSIS_INVALID: Object.freeze({
+    code: "E_DIAGNOSIS_INVALID",
+    category: "diagnosis",
+    classification: "PUBLIC_STABLE",
+    meaning: "Diagnosis record details or parameters are malformed.",
+    safeResolution: "Provide valid failureClass, hypothesis, evidenceRefs, settledBy, and nextSafeAction.",
+  }),
+  E_DIAGNOSIS_EVIDENCE_INVALID: Object.freeze({
+    code: "E_DIAGNOSIS_EVIDENCE_INVALID",
+    category: "diagnosis",
+    classification: "PUBLIC_STABLE",
+    meaning: "Referenced diagnosis evidence is missing or has no failed checks in the current cycle.",
+    safeResolution: "Reference at least one failed or blocked check ID from the active verification cycle.",
+  }),
+  E_DIAGNOSIS_CYCLE_MISMATCH: Object.freeze({
+    code: "E_DIAGNOSIS_CYCLE_MISMATCH",
+    category: "diagnosis",
+    classification: "PUBLIC_STABLE",
+    meaning: "Diagnosis verification cycle does not match the active work state verification cycle.",
+    safeResolution: "Record diagnosis for the current active verification cycle.",
+  }),
+  E_DIAGNOSIS_NO_NEW_INFORMATION: Object.freeze({
+    code: "E_DIAGNOSIS_NO_NEW_INFORMATION",
+    category: "diagnosis",
+    classification: "PUBLIC_STABLE",
+    meaning: "The proposed retry repeats the previous hypothesis with the same evidence.",
+    safeResolution: "Change the hypothesis, collect independent evidence, or change strategy.",
+  }),
+  E_PROGRESS_STALLED: Object.freeze({
+    code: "E_PROGRESS_STALLED",
+    category: "progress",
+    classification: "PUBLIC_STABLE",
+    meaning: "Persisted correction history shows no new diagnostic information.",
+    safeResolution: "Use an independent check, revisit assumptions, or record a materially different diagnosis.",
+  }),
+  E_DECISION_CRITERION_INVALID: Object.freeze({
+    code: "E_DECISION_CRITERION_INVALID",
+    category: "contract",
+    classification: "PUBLIC_STABLE",
+    meaning: "Decision settlement criterion details or parameters are malformed.",
+    safeResolution: "Provide non-empty decision text and settledBy criterion.",
+  }),
+  E_DECISION_NOT_UNRESOLVED: Object.freeze({
+    code: "E_DECISION_NOT_UNRESOLVED",
+    category: "contract",
+    classification: "PUBLIC_STABLE",
+    meaning: "A settlement criterion referenced a decision not present in current unresolvedDecisions.",
+    safeResolution: "Use the exact current unresolved decision text or update the contract first.",
+  }),
+  E_CHECK_INERT: Object.freeze({
+    code: "E_CHECK_INERT",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "An enabled check has no effective scope or target files.",
+    safeResolution: "Provide an applicable target scope, configure matching files, or mark the rule unsupported.",
+  }),
+  E_CHECK_MUTATION_NOT_DETECTED: Object.freeze({
+    code: "E_CHECK_MUTATION_NOT_DETECTED",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "A blocking rule checker failed to detect an intentional mutation fixture.",
+    safeResolution: "Fix checker logic to properly identify target violations.",
+  }),
+  E_POLICY_DRIFT: Object.freeze({
+    code: "E_POLICY_DRIFT",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "Active policy lock does not match the policy snapshot captured at task activation.",
+    safeResolution: "Re-verify affected checks or restore original policy.",
+  }),
+  E_POLICY_WEAKENING: Object.freeze({
+    code: "E_POLICY_WEAKENING",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "Policy rules were weakened during task execution without explicit authority.",
+    safeResolution: "Restore the original policy configuration.",
+  }),
+  E_POLICY_LOCK_INVALID: Object.freeze({
+    code: "E_POLICY_LOCK_INVALID",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "Policy lockfile is missing, malformed, or corrupt.",
+    safeResolution: "Run forgeloop policy-status or regenerate policy.lock.",
+  }),
+  E_NEW_POLICY_VIOLATION: Object.freeze({
+    code: "E_NEW_POLICY_VIOLATION",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "New executable policy violation detected that is not present in brownfield baseline.",
+    safeResolution: "Fix the violation before completing the task.",
+  }),
+  E_BASELINE_EXPANSION: Object.freeze({
+    code: "E_BASELINE_EXPANSION",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "Attempted unauthorized addition of new violations to brownfield baseline.",
+    safeResolution: "Resolve new violations rather than expanding the baseline.",
+  }),
+  E_POLICY_PROOF_STALE: Object.freeze({
+    code: "E_POLICY_PROOF_STALE",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "Mutation verification proof is stale due to checker or fixture modifications.",
+    safeResolution: "Re-run forgeloop rule-verify to refresh mutation proof.",
+  }),
+  E_CHECK_MUTATION_EXECUTION_ERROR: Object.freeze({
+    code: "E_CHECK_MUTATION_EXECUTION_ERROR",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "A policy checker threw an unhandled exception while evaluating its mutation fixture.",
+    safeResolution: "Repair the checker execution path and rerun rule verification.",
+  }),
+  E_POLICY_EVALUATION_FAILED: Object.freeze({
+    code: "E_POLICY_EVALUATION_FAILED",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "Policy evaluation threw an unexpected error during execution.",
+    safeResolution: "Inspect policy configuration and checker adapters for unhandled errors.",
+  }),
+  E_POLICY_INVALID: Object.freeze({
+    code: "E_POLICY_INVALID",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "Policy artifact is malformed, corrupt, or schema-invalid.",
+    safeResolution: "Validate and repair rules.json, baseline.json, or discovery.json against schema.",
+  }),
+  E_POLICY_SNAPSHOT_WRITE_FAILED: Object.freeze({
+    code: "E_POLICY_SNAPSHOT_WRITE_FAILED",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "Failed to persist task policy snapshot during preflight.",
+    safeResolution: "Ensure the target task directory is writable and repair filesystem permissions.",
+  }),
+  E_POLICY_LOCK_MISMATCH: Object.freeze({
+    code: "E_POLICY_LOCK_MISMATCH",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "Persisted policy lock digest does not match current effective policy state.",
+    safeResolution: "Re-evaluate effective rules and update policy.lock or restore modified rules.",
+  }),
+  E_POLICY_DRIFT_UNKNOWN: Object.freeze({
+    code: "E_POLICY_DRIFT_UNKNOWN",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "Task policy drift was detected but baseline snapshot details are unavailable.",
+    safeResolution: "Re-verify the task under the current policy state.",
+  }),
+  E_BASELINE_RECORD_DURING_ACTIVE_TASK: Object.freeze({
+    code: "E_BASELINE_RECORD_DURING_ACTIVE_TASK",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "Cannot re-record baseline during an active task with policy snapshot.",
+    safeResolution: "Resolve new violations or use monotonic baseline --update.",
+  }),
+  E_POLICY_INITIALIZATION_FAILED: Object.freeze({
+    code: "E_POLICY_INITIALIZATION_FAILED",
+    category: "policy",
+    classification: "PUBLIC_STABLE",
+    meaning: "Executable policy bootstrap could not complete during initialization.",
+    safeResolution: "Repair the reported filesystem/schema error and rerun `forgeloop init`. Initialization is restartable while no committed manifest exists.",
+  }),
+  E_INIT_KIT_CONFLICT: Object.freeze({
+    code: "E_INIT_KIT_CONFLICT",
+    category: "project-maintenance",
+    classification: "PUBLIC_STABLE",
+    meaning: "A canonical ForgeLoop kit destination already exists with content that does not match the shipped canonical template.",
+    safeResolution: "Inspect the conflicting `.forgeloop/kit/...` file. If it is stale or partial ForgeLoop output, remove or restore it and rerun `forgeloop init`. Do not overwrite unknown content automatically.",
+  }),
 });
 
+export const E_CHECK_INERT = "E_CHECK_INERT";
+export const E_CHECK_MUTATION_NOT_DETECTED = "E_CHECK_MUTATION_NOT_DETECTED";
+export const E_POLICY_DRIFT = "E_POLICY_DRIFT";
+export const E_POLICY_WEAKENING = "E_POLICY_WEAKENING";
+export const E_POLICY_LOCK_INVALID = "E_POLICY_LOCK_INVALID";
+export const E_NEW_POLICY_VIOLATION = "E_NEW_POLICY_VIOLATION";
+export const E_BASELINE_EXPANSION = "E_BASELINE_EXPANSION";
+export const E_POLICY_PROOF_STALE = "E_POLICY_PROOF_STALE";
+export const E_CHECK_MUTATION_EXECUTION_ERROR = "E_CHECK_MUTATION_EXECUTION_ERROR";
+export const E_POLICY_EVALUATION_FAILED = "E_POLICY_EVALUATION_FAILED";
+export const E_POLICY_INVALID = "E_POLICY_INVALID";
+export const E_POLICY_SNAPSHOT_WRITE_FAILED = "E_POLICY_SNAPSHOT_WRITE_FAILED";
+export const E_POLICY_LOCK_MISMATCH = "E_POLICY_LOCK_MISMATCH";
+export const E_POLICY_DRIFT_UNKNOWN = "E_POLICY_DRIFT_UNKNOWN";
+export const E_BASELINE_RECORD_DURING_ACTIVE_TASK = "E_BASELINE_RECORD_DURING_ACTIVE_TASK";
+export const E_POLICY_INITIALIZATION_FAILED = "E_POLICY_INITIALIZATION_FAILED";
+export const E_INIT_KIT_CONFLICT = "E_INIT_KIT_CONFLICT";
+
 export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
   ...FAILURE_CODES,
   E_VERIFICATION_TOOL_UNAVAILABLE,
@@ -190,8 +457,33 @@ export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
   E_TASK_SCOPE_DIRTY,
   E_TASK_SCOPE_FROZEN,
   E_TASK_CHANGE_OUTSIDE_SCOPE,
+  E_RECONCILE_NOT_STALE,
+  E_RECONCILE_PHASE_INVALID,
+  E_RECONCILE_UNSUPPORTED_DRIFT,
+  E_RECONCILE_LEDGER_INVALID,
+  E_RECONCILE_REQUIREMENT_UNKNOWN,
+  E_RECONCILE_EVIDENCE_FAILED,
+  E_REPOSITORY_CHANGED,
+  E_STATE_REVALIDATION_REQUIRED,
   E_TASK_CHANGE_ATTRIBUTION_UNAVAILABLE,
   E_TASK_LAYOUT_LEGACY,
   E_TASK_MIGRATION_INVALID,
   E_TASK_MIGRATION_IDENTITY_MISMATCH,
+  E_CHECK_INERT,
+  E_CHECK_MUTATION_NOT_DETECTED,
+  E_POLICY_DRIFT,
+  E_POLICY_WEAKENING,
+  E_POLICY_LOCK_INVALID,
+  E_NEW_POLICY_VIOLATION,
+  E_BASELINE_EXPANSION,
+  E_POLICY_PROOF_STALE,
+  E_CHECK_MUTATION_EXECUTION_ERROR,
+  E_POLICY_EVALUATION_FAILED,
+  E_POLICY_INVALID,
+  E_POLICY_SNAPSHOT_WRITE_FAILED,
+  E_POLICY_LOCK_MISMATCH,
+  E_POLICY_DRIFT_UNKNOWN,
+  E_BASELINE_RECORD_DURING_ACTIVE_TASK,
+  E_POLICY_INITIALIZATION_FAILED,
+  E_INIT_KIT_CONFLICT,
 ]));

package/src/core/events.js

@@ -12,6 +12,9 @@ import { isRecoverableCompletionEvidenceCode } from "./completion-recovery.js";
 
 import { taskArtifactPath } from "./task-paths.js";
 
+import { assertDiagnosisDetails } from "./diagnosis-model.js";
+import { assertDecisionCriterionDetails } from "./settlement-model.js";
+
 const EVENT_SCHEMA_VERSION = 1;
 export const LIFECYCLE_MILESTONES = Object.freeze([
   "CONTRACT_VALIDATED",
@@ -37,6 +40,42 @@ const REPEATABLE_MILESTONES = new Set([
   "TERMINAL_RESULT_RECORDED",
 ]);
 
+export function validateKnownEventDetails(event) {
+  if (!event || typeof event !== "object") return;
+  switch (event.event) {
+    case "DIAGNOSIS_RECORDED":
+      assertDiagnosisDetails(event.details);
+      return;
+    case "DECISION_CRITERION_RECORDED":
+      assertDecisionCriterionDetails(event.details);
+      return;
+    case "CHECKPOINT_RECONCILED":
+      assertReconcileClosureDetails(event.details);
+      return;
+    default:
+      return;
+  }
+}
+
+function assertReconcileClosureDetails(details) {
+  if (!details || typeof details !== "object" || Array.isArray(details)) {
+    throw protocolError("E_EVENT_INVALID", "CHECKPOINT_RECONCILED requires structured details");
+  }
+  for (const key of ["checkId", "command", "executionId"]) {
+    if (typeof details[key] !== "string") {
+      throw protocolError("E_EVENT_INVALID", `CHECKPOINT_RECONCILED details.${key} must be a string`);
+    }
+  }
+  for (const key of ["previousBranch", "currentBranch", "previousHead", "currentHead"]) {
+    if (typeof details[key] !== "string" && details[key] !== null) {
+      throw protocolError("E_EVENT_INVALID", `CHECKPOINT_RECONCILED details.${key} must be a string or null`);
+    }
+  }
+  if (typeof details.exitCode !== "number" || !Number.isInteger(details.exitCode) || details.exitCode < 0) {
+    throw protocolError("E_EVENT_INVALID", "CHECKPOINT_RECONCILED details.exitCode must be a non-negative integer");
+  }
+}
+
 function eventHash(event) {
   const { hash, ...body } = event;
   return canonicalFingerprint(body);
@@ -64,8 +103,9 @@ export async function readEvents(target, packageRoot, options = {}) {
       event = JSON.parse(line);
       assertJsonLimits(event, `${relPath}[${index}]`);
       assertSchema(event, schema, `${relPath}[${index}]`);
+      validateKnownEventDetails(event);
     } catch (error) {
-      throw protocolError("E_EVENT_INVALID", `${relPath} line ${index + 1}: ${error.message}`, [relPath]);
+      throw protocolError(error.code ?? "E_EVENT_INVALID", `${relPath} line ${index + 1}: ${error.message}`, [relPath]);
     }
     return event;
   });
@@ -88,6 +128,7 @@ export async function appendProtocolEvent(target, input, packageRoot, options =
     previousHash: previous?.hash ?? null,
     ...(input.details ? { details: structuredClone(input.details) } : {}),
   };
+  validateKnownEventDetails(event);
   assertSecretFree(event);
   const schema = await readSchema("event", packageRoot);
   assertSchema(event, schema, relPath);
@@ -125,6 +166,11 @@ export async function validateEventLedger(target, packageRoot, options = {}) {
     if (event.hash !== eventHash(event)) {
       errors.push({ code: "E_LEDGER_HASH_INVALID", message: `event ${event.seq} hash does not match its content` });
     }
+    try {
+      validateKnownEventDetails(event);
+    } catch (err) {
+      errors.push({ code: err.code ?? "E_EVENT_INVALID", message: `event ${event.seq} (${event.event}): ${err.message}` });
+    }
     const milestoneIndex = LIFECYCLE_MILESTONES.indexOf(event.event);
     if (milestoneIndex >= 0) {
       const count = (milestoneCounts.get(event.event) ?? 0) + 1;