@cassiomc1/forgeloop 0.1.2 → 0.1.3

package/src/core/completion.js

@@ -1,19 +1,24 @@
-import { ARTIFACT_PATHS, canonicalFingerprint, readJsonArtifact } from "./artifacts.js";
+import { ARTIFACT_PATHS, canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
 import { requiredEvidenceForTarget } from "./completion-artifacts.js";
-import { appendProtocolEvent, validateEventLedger } from "./events.js";
+import { appendProtocolEvent, LIFECYCLE_MILESTONES, validateEventLedger } from "./events.js";
 import { evaluatePreflight } from "./preflight.js";
 import { readContract } from "./contract.js";
 import { readPersistedRoute } from "./route-artifact.js";
 import { readWorkState, writeWorkState, classifyLoadedWorkState } from "./work-state.js";
-import { validateReceipt } from "./receipt.js";
-import { assertCheckList, requiredChecksSatisfied } from "./checks.js";
-import { assertCoverageList, coverageForRequirements } from "./coverage.js";
+import { createReceipt, validateReceipt } from "./receipt.js";
+import { completionRelationshipErrors } from "./completion-relationships.js";
 import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
+import { evaluateStartExecutionPrerequisites, hasExecutionStarted } from "./execution-prerequisites.js";
 
 function issue(code, message, artifacts = [], details = {}) {
   return { code, message, artifacts, ...details };
 }
 
+export function completionIdentityErrors({ contract, state, receipt } = {}) {
+  return completionRelationshipErrors({ contract, state, receipt })
+    .filter((error) => ["E_STATE_TASK_MISMATCH", "E_RECEIPT_TASK_MISMATCH"].includes(error.code));
+}
+
 function repairNext(error) {
   switch (error.code) {
     case "E_RECEIPT_MISSING":
@@ -94,7 +99,7 @@ async function validateLedger(target, taskId, state, errors, packageRoot) {
   }
   const ledger = await validateEventLedger(target, packageRoot);
   for (const error of ledger.errors) errors.push({ ...error, artifacts: [ARTIFACT_PATHS.events] });
-  const requiredEvents = ["CONTRACT_VALIDATED", "ROUTE_VALIDATED", "PREFLIGHT_READY", "EXECUTION_STARTED", "VERIFICATION_RECORDED"];
+  const requiredEvents = LIFECYCLE_MILESTONES.slice(0, state?.phase === "COMPLETE" ? undefined : -1);
   const observed = new Set(ledger.events.filter((event) => event.taskId === taskId).map((event) => event.event));
   for (const event of requiredEvents) {
     if (!observed.has(event)) {
@@ -104,8 +109,8 @@ async function validateLedger(target, taskId, state, errors, packageRoot) {
   if (ledger.events.some((event) => event.taskId !== taskId)) {
     errors.push(issue("E_PHASE_CHRONOLOGY_INVALID", "Protocol events must belong to the current task", [ARTIFACT_PATHS.events]));
   }
-  if (state?.phase === "COMPLETE" && !observed.has("COMPLETION_VALIDATED")) {
-    errors.push(issue("E_PHASE_CHRONOLOGY_INVALID", "COMPLETE state requires COMPLETION_VALIDATED", [ARTIFACT_PATHS.events]));
+  if (state?.phase !== "COMPLETE" && observed.has("COMPLETION_VALIDATED")) {
+    errors.push(issue("E_PHASE_CHRONOLOGY_INVALID", "COMPLETION_VALIDATED requires COMPLETE state", [ARTIFACT_PATHS.events]));
   }
   return ledger;
 }
@@ -150,6 +155,11 @@ export async function evaluateCompletion({ target, packageRoot, strict = false }
     errors,
   );
 
+  if (state && hasExecutionStarted(state.phase)) {
+    const prerequisites = await evaluateStartExecutionPrerequisites({ target, state, packageRoot });
+    errors.push(...prerequisites.errors);
+  }
+
   if (receipt) {
     try {
       await validateReceipt(receipt.value, packageRoot);
@@ -158,34 +168,12 @@ export async function evaluateCompletion({ target, packageRoot, strict = false }
     }
   }
 
-  if (contract && route && route.value.contractFingerprint !== undefined
-    && route.value.contractFingerprint !== contract.fingerprint) {
-    errors.push(issue("E_ROUTE_STALE", "Routing result does not match the current contract", [ARTIFACT_PATHS.route, ARTIFACT_PATHS.contract]));
-  }
-  if (contract && state && state.contractFingerprint !== contract.fingerprint) {
-    errors.push(issue("E_CONTRACT_STALE", "Work state does not match the current contract", [ARTIFACT_PATHS.state, ARTIFACT_PATHS.contract]));
-  }
-  if (route && state && JSON.stringify(route.value.guides) !== JSON.stringify(state.selectedGuides)) {
-    errors.push(issue("E_ROUTE_GUIDE_MISMATCH", "Work state guides do not match the persisted route", [ARTIFACT_PATHS.route, ARTIFACT_PATHS.state]));
-  }
-  if (route && receipt && JSON.stringify(route.value.guides) !== JSON.stringify(receipt.value.selectedGuides)) {
-    errors.push(issue("E_ROUTE_GUIDE_MISMATCH", "Receipt guides do not match the persisted route", [ARTIFACT_PATHS.route, ARTIFACT_PATHS.receipt]));
-  }
-  if (contract && receipt && receipt.value.contractFingerprint !== contract.fingerprint) {
-    errors.push(issue("E_RECEIPT_CONTRACT_MISMATCH", "Receipt does not match the current contract", [ARTIFACT_PATHS.contract, ARTIFACT_PATHS.receipt]));
-  }
-  if (route && receipt && receipt.value.routeFingerprint !== undefined && receipt.value.routeFingerprint !== route.fingerprint) {
-    errors.push(issue("E_RECEIPT_ROUTE_MISMATCH", "Receipt does not match the persisted route", [ARTIFACT_PATHS.route, ARTIFACT_PATHS.receipt]));
-  }
-  if (state && receipt && receipt.value.stateFingerprint !== undefined && receipt.value.stateFingerprint !== canonicalFingerprint(state)) {
-    errors.push(issue("E_RECEIPT_STATE_MISMATCH", "Receipt does not match the recorded work state", [ARTIFACT_PATHS.state, ARTIFACT_PATHS.receipt]));
-  }
   if (state && !["REVIEWING", "COMPLETE"].includes(state.phase)) {
     errors.push(issue("E_PHASE_PREREQUISITE_MISSING", `Completion requires REVIEWING or COMPLETE state, found ${state.phase}`, [ARTIFACT_PATHS.state]));
   }
 
   let coverage = [];
-  if (receipt && contract && route) {
+  if (contract && route) {
     const requiredEvidence = await requiredEvidenceForTarget({
       target,
       contract,
@@ -193,37 +181,15 @@ export async function evaluateCompletion({ target, packageRoot, strict = false }
       packageRoot,
       additionalEvidence: preflight?.policy?.requiredEvidence ?? [],
     });
-    coverage = receipt.value.evidenceCoverage
-      ? receipt.value.evidenceCoverage
-      : coverageForRequirements(requiredEvidence, receipt.value.checks);
-    try {
-      assertCoverageList(coverage);
-    } catch (error) {
-      errors.push(issue(error.code ?? "E_EVIDENCE_COVERAGE_PARTIAL", error.message, [ARTIFACT_PATHS.receipt]));
-    }
-    const byRequirement = new Map(coverage.map((item) => [item.requirement, item]));
-    for (const requirement of requiredEvidence) {
-      const item = byRequirement.get(requirement);
-      if (!item) {
-        errors.push(issue("E_EVIDENCE_REQUIRED", `Evidence coverage is missing: ${requirement}`, [ARTIFACT_PATHS.receipt], { requirement }));
-      } else if (item.status !== "COVERED") {
-        errors.push(issue(
-          item.status === "BLOCKED" ? "E_EVIDENCE_COVERAGE_PARTIAL" : "E_EVIDENCE_COVERAGE_PARTIAL",
-          `Evidence coverage is ${item.status}: ${requirement}`,
-          [ARTIFACT_PATHS.receipt],
-          { requirement, status: item.status },
-        ));
-      }
-    }
-    const structuredChecks = receipt.value.checks.filter((check) => check?.schemaVersion === 1 || check?.id !== undefined || check?.evidenceKind !== undefined);
-    if (structuredChecks.length > 0) {
-      try {
-        assertCheckList(structuredChecks, "receipt.checks");
-        errors.push(...requiredChecksSatisfied(structuredChecks, requiredEvidence));
-      } catch (error) {
-        errors.push(issue(error.code ?? "E_CHECK_INVALID", error.message, [ARTIFACT_PATHS.receipt]));
-      }
-    }
+    const relationshipErrors = completionRelationshipErrors({
+      contract,
+      route,
+      state,
+      receipt: receipt?.value,
+      requiredEvidence,
+    });
+    errors.push(...relationshipErrors);
+    coverage = receipt?.value?.evidenceCoverage ?? [];
   }
 
   const ledger = contract && state
@@ -283,7 +249,12 @@ export async function runComplete({ target, packageRoot, strict = false, persist
         publicationStatus: result.publicationStatus,
         lastUpdated: new Date().toISOString(),
       };
+      const nextReceipt = await createReceipt({
+        ...receipt.value,
+        stateFingerprint: canonicalFingerprint(next),
+      }, packageRoot);
       await writeWorkState(target, next, { packageRoot });
+      await writeJsonArtifact(target, ARTIFACT_PATHS.receipt, nextReceipt, "execution-receipt", packageRoot);
     }
     const contract = await readContract(target, packageRoot);
     const ledger = await validateEventLedger(target, packageRoot);

package/src/core/events.js

@@ -10,6 +10,16 @@ import { assertSecretFree } from "./receipt.js";
 import { PROTOCOL_VERSION } from "./protocol.js";
 
 const EVENT_SCHEMA_VERSION = 1;
+export const LIFECYCLE_MILESTONES = Object.freeze([
+  "CONTRACT_VALIDATED",
+  "ROUTE_VALIDATED",
+  "PREFLIGHT_READY",
+  "EXECUTION_STARTED",
+  "VERIFICATION_STARTED",
+  "VERIFICATION_RECORDED",
+  "COMPLETION_VALIDATED",
+]);
+const REPEATABLE_MILESTONES = new Set(["VERIFICATION_RECORDED"]);
 
 function eventHash(event) {
   const { hash, ...body } = event;
@@ -82,6 +92,8 @@ export async function validateEventLedger(target, packageRoot) {
   const errors = [];
   let taskId = null;
   const seen = new Set();
+  let lastMilestone = -1;
+  const milestoneCounts = new Map();
   for (const [index, event] of events.entries()) {
     if (event.seq !== index + 1) {
       errors.push({ code: "E_EVENT_INVALID", message: `event sequence must be ${index + 1}` });
@@ -94,6 +106,25 @@ export async function validateEventLedger(target, packageRoot) {
     if (event.hash !== eventHash(event)) {
       errors.push({ code: "E_LEDGER_HASH_INVALID", message: `event ${event.seq} hash does not match its content` });
     }
+    const milestoneIndex = LIFECYCLE_MILESTONES.indexOf(event.event);
+    if (milestoneIndex >= 0) {
+      const count = (milestoneCounts.get(event.event) ?? 0) + 1;
+      milestoneCounts.set(event.event, count);
+      if (count > 1 && !REPEATABLE_MILESTONES.has(event.event)) {
+        errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: `lifecycle milestone must not repeat: ${event.event}` });
+      }
+      if (milestoneIndex > lastMilestone + 1) {
+        errors.push({
+          code: "E_PHASE_CHRONOLOGY_INVALID",
+          message: `${event.event} is missing prerequisite milestone: ${LIFECYCLE_MILESTONES[lastMilestone + 1]}`,
+        });
+      } else if (milestoneIndex < lastMilestone) {
+        errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: `${event.event} is out of lifecycle order` });
+      } else if (milestoneIndex === lastMilestone && !REPEATABLE_MILESTONES.has(event.event)) {
+        errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: `lifecycle milestone must not repeat: ${event.event}` });
+      }
+      if (milestoneIndex > lastMilestone) lastMilestone = milestoneIndex;
+    }
     seen.add(event.event);
     if (event.event === "EXECUTION_STARTED" && !seen.has("ROUTE_VALIDATED")) {
       errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "execution started before route validation" });
@@ -116,6 +147,9 @@ export async function validateEventLedger(target, packageRoot) {
         }
       }
     }
+    if (event.event === "VERIFICATION_RECORDED" && !seen.has("VERIFICATION_STARTED")) {
+      errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "verification evidence recorded before verification started" });
+    }
     if (event.event === "COMPLETION_VALIDATED" && !seen.has("VERIFICATION_RECORDED")) {
       errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "completion validated before verification evidence" });
     }

package/src/core/execution-prerequisites.js

@@ -0,0 +1,200 @@
+import { ARTIFACT_PATHS, readJsonArtifact } from "./artifacts.js";
+import { readContract } from "./contract.js";
+import { validateEventLedger } from "./events.js";
+import { evaluatePreflight, validatePersistedPreflight } from "./preflight.js";
+import { readPersistedRoute } from "./route-artifact.js";
+import { stateIdentityErrors } from "./completion-relationships.js";
+import { classifyLoadedWorkState } from "./work-state.js";
+
+const START_EXECUTION_EVENTS = Object.freeze([
+  "CONTRACT_VALIDATED",
+  "ROUTE_VALIDATED",
+  "PREFLIGHT_READY",
+]);
+const POST_EXECUTION_PHASES = new Set([
+  "EXECUTING",
+  "VERIFYING",
+  "DIAGNOSING",
+  "CORRECTING",
+  "REVIEWING",
+  "COMPLETE",
+]);
+export const PREFLIGHT_ROUTE_IDENTITY_ERROR_MESSAGE = "PREFLIGHT_READY event routing fingerprint does not match the current READY preflight and route";
+export const PREFLIGHT_CONTRACT_IDENTITY_ERROR_MESSAGE = "PREFLIGHT_READY event contract fingerprint does not match the current READY preflight";
+
+export function hasExecutionStarted(phase) {
+  return POST_EXECUTION_PHASES.has(phase);
+}
+
+export function prerequisiteError(prerequisites) {
+  const first = prerequisites.errors[0];
+  if (!first) return null;
+  const error = new Error(first.message);
+  error.code = first.code;
+  error.artifacts = first.artifacts;
+  return error;
+}
+
+export async function assertExecutionPrerequisites(input = {}) {
+  const prerequisites = await evaluateStartExecutionPrerequisites(input);
+  const error = prerequisiteError(prerequisites);
+  if (error) throw error;
+  return prerequisites;
+}
+
+function issue(code, message, artifacts = []) {
+  return { code, message, artifacts };
+}
+
+function sameStringSet(left, right) {
+  if (!Array.isArray(left) || !Array.isArray(right)) return false;
+  return left.length === new Set(left).size
+    && right.length === new Set(right).size
+    && left.length === right.length
+    && left.every((value) => right.includes(value));
+}
+
+async function load(loadArtifact, code, message, artifacts, errors) {
+  try {
+    return await loadArtifact();
+  } catch (error) {
+    errors.push(issue(code, `${message}: ${error.message}`, artifacts));
+    return null;
+  }
+}
+
+function freshnessErrors(state, freshness) {
+  if (freshness.status !== "REVALIDATION_REQUIRED") return [];
+  return [issue(
+    "E_STATE_REVALIDATION_REQUIRED",
+    `EXECUTING requires a fresh work-state checkpoint: ${freshness.reasons.join(", ")}`,
+    [
+      ARTIFACT_PATHS.state,
+      ARTIFACT_PATHS.contract,
+      ...(state.requiredArtifacts?.map((artifact) => artifact.path) ?? []),
+    ],
+  )];
+}
+
+function prerequisiteLedgerErrors(ledger, taskId, preflight, route) {
+  const errors = (ledger.errors ?? []).map((error) => issue(
+    error.code ?? "E_PHASE_CHRONOLOGY_INVALID",
+    error.message,
+    [ARTIFACT_PATHS.events],
+  ));
+  const events = ledger.events ?? [];
+  if (events.some((event) => event.taskId !== taskId)) {
+    errors.push(issue(
+      "E_PHASE_CHRONOLOGY_INVALID",
+      "EXECUTING requires protocol prerequisite events to belong to the current task",
+      [ARTIFACT_PATHS.events, ARTIFACT_PATHS.state, ARTIFACT_PATHS.contract],
+    ));
+    return errors;
+  }
+  const currentEvents = events.filter((event) => event.taskId === taskId);
+  for (const requiredEvent of START_EXECUTION_EVENTS) {
+    if (!currentEvents.some((event) => event.event === requiredEvent)) {
+      errors.push(issue(
+        "E_PHASE_CHRONOLOGY_INVALID",
+        `EXECUTING requires a ${requiredEvent} protocol event`,
+        [ARTIFACT_PATHS.events],
+      ));
+    }
+  }
+  const preflightEvent = currentEvents.find((event) => event.event === "PREFLIGHT_READY");
+  if (preflightEvent && (!sameStringSet(preflightEvent.details?.requiredGates, preflight.requiredGates)
+    || !sameStringSet(preflightEvent.details?.satisfiedGates, preflight.satisfiedGates))) {
+    errors.push(issue(
+      "E_PHASE_CHRONOLOGY_INVALID",
+      "PREFLIGHT_READY event gate sets do not match the current READY preflight",
+      [ARTIFACT_PATHS.events, ARTIFACT_PATHS.preflight],
+    ));
+  }
+  if (preflightEvent && preflightEvent.fingerprint !== preflight.fingerprints.contract) {
+    errors.push(issue(
+      "E_PHASE_CHRONOLOGY_INVALID",
+      PREFLIGHT_CONTRACT_IDENTITY_ERROR_MESSAGE,
+      [ARTIFACT_PATHS.events, ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.contract],
+    ));
+  }
+  if (preflightEvent && (preflightEvent.details?.routingFingerprint !== preflight.fingerprints.routing
+    || preflightEvent.details?.routingFingerprint !== route.fingerprint)) {
+    errors.push(issue(
+      "E_PHASE_CHRONOLOGY_INVALID",
+      PREFLIGHT_ROUTE_IDENTITY_ERROR_MESSAGE,
+      [ARTIFACT_PATHS.events, ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.route],
+    ));
+  }
+  return errors;
+}
+
+export async function evaluateStartExecutionPrerequisites({ target, state, packageRoot } = {}) {
+  const errors = [];
+  const requiredArtifacts = [
+    ARTIFACT_PATHS.state,
+    ARTIFACT_PATHS.contract,
+    ARTIFACT_PATHS.route,
+    ARTIFACT_PATHS.preflight,
+    ARTIFACT_PATHS.events,
+  ];
+  if (!state) {
+    return {
+      errors: [issue("E_PHASE_PREREQUISITE_MISSING", "EXECUTING requires a work state", [ARTIFACT_PATHS.state])],
+      requiredArtifacts,
+    };
+  }
+
+  const contract = await load(
+    () => readContract(target, packageRoot),
+    "E_PHASE_PREREQUISITE_MISSING",
+    `EXECUTING requires ${ARTIFACT_PATHS.contract}`,
+    [ARTIFACT_PATHS.contract],
+    errors,
+  );
+  const route = await load(
+    () => readPersistedRoute(target, packageRoot),
+    "E_PHASE_PREREQUISITE_MISSING",
+    `EXECUTING requires ${ARTIFACT_PATHS.route}`,
+    [ARTIFACT_PATHS.route],
+    errors,
+  );
+  if (!contract || !route) return { errors, requiredArtifacts, contract, route };
+
+  if (state.routeFingerprint !== route.fingerprint) {
+    errors.push(issue(
+      "E_ROUTE_STALE",
+      "EXECUTING requires work state and route to match the current contract",
+      [ARTIFACT_PATHS.state, ARTIFACT_PATHS.route, ARTIFACT_PATHS.contract],
+    ));
+  }
+  errors.push(...stateIdentityErrors({ contract, route, state }));
+
+  const freshness = await classifyLoadedWorkState({
+    target,
+    state,
+    contractFile: ARTIFACT_PATHS.contract,
+  });
+  errors.push(...freshnessErrors(state, freshness));
+
+  const preflight = await evaluatePreflight({ target, packageRoot });
+  let persistedPreflight = null;
+  try {
+    persistedPreflight = await readJsonArtifact(target, ARTIFACT_PATHS.preflight, "preflight", packageRoot);
+  } catch {
+    // validatePersistedPreflight reports the stable, actionable preflight reason.
+  }
+  const persistedPreflightErrors = validatePersistedPreflight(persistedPreflight?.value, preflight);
+  if (!sameStringSet(state.requiredGates, preflight.requiredGates)
+    || !sameStringSet(state.satisfiedGates, preflight.satisfiedGates)) {
+    errors.push(issue(
+      "E_PREFLIGHT_GATES_STALE",
+      "Work state gate sets do not match the current preflight evaluation",
+      [ARTIFACT_PATHS.state, ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.gates],
+    ));
+  }
+
+  const ledger = await validateEventLedger(target, packageRoot);
+  errors.push(...prerequisiteLedgerErrors(ledger, contract.value.taskId, preflight, route));
+  errors.push(...persistedPreflightErrors);
+  return { errors, requiredArtifacts, contract, route, preflight, persistedPreflight, ledger };
+}