@cassiomc1/forgeloop 0.1.2 → 0.1.3

package/src/core/phase.js

@@ -1,11 +1,15 @@
-import { ARTIFACT_PATHS } from "./artifacts.js";
-import { readJsonArtifact } from "./artifacts.js";
+import { ARTIFACT_PATHS, canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
 import { readContract } from "./contract.js";
-import { appendProtocolEvent, validateEventLedger } from "./events.js";
+import { appendProtocolEvent, LIFECYCLE_MILESTONES, validateEventLedger } from "./events.js";
 import { readPersistedRoute } from "./route-artifact.js";
 import { assertWorkPhase, isValidTransition } from "./protocol.js";
 import { readWorkState, writeWorkState } from "./work-state.js";
 import { evaluateCompletion } from "./completion.js";
+import { evaluatePreflight, validatePersistedPreflight } from "./preflight.js";
+import { requiredEvidenceForTarget } from "./completion-artifacts.js";
+import { assertCompletionRelationships, assertStateIdentity } from "./completion-relationships.js";
+import { createReceipt, validateReceipt } from "./receipt.js";
+import { assertExecutionPrerequisites, hasExecutionStarted } from "./execution-prerequisites.js";
 
 function phaseError(code, message, artifacts = []) {
   const error = new Error(message);
@@ -24,6 +28,72 @@ const PHASE_EVENTS = Object.freeze({
   COMPLETE: "COMPLETION_VALIDATED",
 });
 
+const LATE_PHASES = new Set([
+  "EXECUTING",
+  "VERIFYING",
+  "DIAGNOSING",
+  "CORRECTING",
+  "REVIEWING",
+  "COMPLETE",
+]);
+
+async function assertPersistedStateIdentity(target, state, toPhase, packageRoot) {
+  const requireContract = LATE_PHASES.has(state.phase)
+    || ["CONTRACT_READY", "ROUTED", "EXECUTING"].includes(toPhase);
+  const requireRoute = LATE_PHASES.has(state.phase)
+    || ["ROUTED", "EXECUTING"].includes(toPhase);
+  let contract = null;
+  let route = null;
+  try {
+    contract = await readContract(target, packageRoot);
+  } catch (error) {
+    if (error.code === "ARTIFACT_MISSING" && !requireContract) {
+      contract = null;
+    } else {
+      throw phaseError(
+        requireContract ? "E_PHASE_PREREQUISITE_MISSING" : error.code ?? "E_CONTRACT_INVALID",
+        `${requireContract ? `Phase ${toPhase} requires current contract` : "Unable to validate current contract"}: ${error.message}`,
+        [ARTIFACT_PATHS.contract],
+      );
+    }
+  }
+  try {
+    route = await readPersistedRoute(target, packageRoot);
+  } catch (error) {
+    if (error.code === "ARTIFACT_MISSING" && !requireRoute) {
+      route = null;
+    } else {
+      throw phaseError(
+        requireRoute ? "E_PHASE_PREREQUISITE_MISSING" : error.code ?? "E_ROUTE_INVALID",
+        `${requireRoute ? `Phase ${toPhase} requires persisted route` : "Unable to validate persisted route"}: ${error.message}`,
+        [ARTIFACT_PATHS.route],
+      );
+    }
+  }
+  if (!contract && !route) return;
+  try {
+    assertStateIdentity({ contract, route, state });
+  } catch (error) {
+    throw phaseError(
+      error.code,
+      error.message,
+      error.artifacts,
+    );
+  }
+}
+
+function reconcileImplementationStep(state, toPhase) {
+  if (state.phase !== "EXECUTING" || toPhase !== "VERIFYING") return state;
+  if (!state.pendingSteps.includes("implementation")) return state;
+  return {
+    ...state,
+    completedSteps: state.completedSteps.includes("implementation")
+      ? [...state.completedSteps]
+      : [...state.completedSteps, "implementation"],
+    pendingSteps: state.pendingSteps.filter((step) => step !== "implementation"),
+  };
+}
+
 async function assertPhasePrerequisites(target, state, toPhase, packageRoot) {
   if (toPhase === "CONTRACT_READY" || toPhase === "ROUTED" || toPhase === "EXECUTING") {
     try {
@@ -39,21 +109,11 @@ async function assertPhasePrerequisites(target, state, toPhase, packageRoot) {
       throw phaseError("E_PHASE_PREREQUISITE_MISSING", `Phase ${toPhase} requires ${ARTIFACT_PATHS.route}: ${error.message}`, [ARTIFACT_PATHS.route]);
     }
   }
-  if (toPhase === "EXECUTING") {
-    let preflight;
+  if (hasExecutionStarted(toPhase)) {
     try {
-      preflight = await readJsonArtifact(target, ARTIFACT_PATHS.preflight, "preflight", packageRoot);
+      await assertExecutionPrerequisites({ target, state, packageRoot });
     } catch (error) {
-      throw phaseError("E_PHASE_PREREQUISITE_MISSING", `EXECUTING requires READY ${ARTIFACT_PATHS.preflight}: ${error.message}`, [ARTIFACT_PATHS.preflight]);
-    }
-    if (preflight.value.status !== "READY") {
-      throw phaseError("E_PREFLIGHT_NOT_READY", "EXECUTING requires a READY preflight", [ARTIFACT_PATHS.preflight]);
-    }
-    const ledger = await validateEventLedger(target, packageRoot);
-    for (const requiredEvent of ["CONTRACT_VALIDATED", "ROUTE_VALIDATED", "PREFLIGHT_READY"]) {
-      if (!ledger.events.some((event) => event.event === requiredEvent)) {
-        throw phaseError("E_PHASE_CHRONOLOGY_INVALID", `EXECUTING requires a ${requiredEvent} protocol event`, [ARTIFACT_PATHS.events]);
-      }
+      throw phaseError(error.code, error.message, error.artifacts);
     }
   }
   if (toPhase === "COMPLETE" && state.verificationEvidence.length === 0) {
@@ -72,17 +132,81 @@ export async function advanceWorkState(target, toPhase, { packageRoot, now = new
   const state = await readWorkState(target, packageRoot);
   if (!state) throw phaseError("E_PHASE_PREREQUISITE_MISSING", "Cannot advance without work state", [ARTIFACT_PATHS.state]);
   await assertPhasePrerequisites(target, state, toPhase, packageRoot);
+  await assertPersistedStateIdentity(target, state, toPhase, packageRoot);
   if (!isValidTransition(state.phase, toPhase)) {
     throw phaseError("E_PHASE_TRANSITION_INVALID", `Invalid work-state transition: ${state.phase} -> ${toPhase}`);
   }
+  const ledger = await validateEventLedger(target, packageRoot);
+  if (!ledger.valid) {
+    const first = ledger.errors[0];
+    throw phaseError(first.code, first.message, [ARTIFACT_PATHS.events]);
+  }
+  if (ledger.events.some((event) => event.taskId !== state.taskId)) {
+    throw phaseError(
+      "E_PHASE_CHRONOLOGY_INVALID",
+      "Cannot advance work state with lifecycle events from a different task",
+      [ARTIFACT_PATHS.events, ARTIFACT_PATHS.state],
+    );
+  }
+  const eventType = PHASE_EVENTS[toPhase];
+  if (eventType && ledger.events.some((event) => event.taskId === state.taskId && event.event === eventType)) {
+    throw phaseError("E_PHASE_CHRONOLOGY_INVALID", `Lifecycle milestone already exists: ${eventType}`, [ARTIFACT_PATHS.events]);
+  }
+  const milestoneIndex = LIFECYCLE_MILESTONES.indexOf(eventType);
+  if (milestoneIndex >= 0) {
+    const lastMilestone = ledger.events.reduce((last, event) => Math.max(last, LIFECYCLE_MILESTONES.indexOf(event.event)), -1);
+    if (lastMilestone !== milestoneIndex - 1) {
+      throw phaseError("E_PHASE_CHRONOLOGY_INVALID", `Phase ${toPhase} cannot append ${eventType} after the current lifecycle ledger`, [ARTIFACT_PATHS.events]);
+    }
+  }
+  const reconciled = reconcileImplementationStep(state, toPhase);
   const next = {
-    ...state,
+    ...reconciled,
     previousPhase: state.phase,
     phase: toPhase,
     lastUpdated: now,
   };
+  let nextReceipt = null;
+  try {
+    const receipt = await readJsonArtifact(target, ARTIFACT_PATHS.receipt, "execution-receipt", packageRoot);
+    const contract = await readContract(target, packageRoot);
+    const route = await readPersistedRoute(target, packageRoot);
+    const preflight = await evaluatePreflight({ target, packageRoot });
+    const requiredEvidence = await requiredEvidenceForTarget({
+      target,
+      contract,
+      route,
+      packageRoot,
+      additionalEvidence: preflight.policy?.requiredEvidence ?? [],
+    });
+    await validateReceipt(receipt.value, packageRoot);
+    assertCompletionRelationships({
+      contract,
+      route,
+      state,
+      receipt: receipt.value,
+      requiredEvidence,
+      requireRequiredChecks: false,
+    });
+    nextReceipt = await createReceipt({
+      ...receipt.value,
+      stateFingerprint: canonicalFingerprint(next),
+    }, packageRoot);
+    assertCompletionRelationships({
+      contract,
+      route,
+      state: next,
+      receipt: nextReceipt,
+      requiredEvidence,
+      requireRequiredChecks: false,
+    });
+  } catch (error) {
+    if (error.code !== "ARTIFACT_MISSING") throw error;
+  }
   await writeWorkState(target, next, { packageRoot });
-  const eventType = PHASE_EVENTS[toPhase];
+  if (nextReceipt) {
+    await writeJsonArtifact(target, ARTIFACT_PATHS.receipt, nextReceipt, "execution-receipt", packageRoot);
+  }
   if (eventType) await appendProtocolEvent(target, { taskId: state.taskId, event: eventType, at: now }, packageRoot);
   return next;
 }

package/src/core/preflight.js

@@ -5,12 +5,13 @@ import { requiredGatesForGuides } from "./guide-metadata.js";
 import { assertRouteInvariants } from "./router.js";
 import { assertSourceProvenance } from "./sources.js";
 import { readPersistedRoute } from "./route-artifact.js";
-import { appendProtocolEvent } from "./events.js";
+import { appendProtocolEvent, LIFECYCLE_MILESTONES, validateEventLedger } from "./events.js";
 import { readWorkState } from "./work-state.js";
 import { readConfig } from "./config.js";
 import { assertSafePath, ensureWithin, fileExists, readBytes } from "./filesystem.js";
 import { sha256 } from "./manifest.js";
 import { validateProfileSources } from "./profile.js";
+import { assertStateIdentity } from "./completion-relationships.js";
 
 const PREVIEW_DECISION_LIMIT = 10;
 const PREVIEW_DECISION_MAX_LENGTH = 240;
@@ -29,6 +30,66 @@ function sortIssues(errors) {
     || left.message.localeCompare(right.message));
 }
 
+function preflightError(code, message, artifacts = []) {
+  const error = new Error(message);
+  error.code = code;
+  error.artifacts = artifacts;
+  return error;
+}
+
+function sameStringSet(left, right) {
+  if (!Array.isArray(left) || !Array.isArray(right)) return false;
+  const leftSet = new Set(left);
+  const rightSet = new Set(right);
+  return leftSet.size === left.length
+    && rightSet.size === right.length
+    && leftSet.size === rightSet.size
+    && [...leftSet].every((value) => rightSet.has(value));
+}
+
+export function validatePersistedPreflight(persisted, current) {
+  const errors = [];
+  if (persisted?.status !== "READY") {
+    errors.push(issue("E_PREFLIGHT_NOT_READY", "A persisted READY preflight is required", [ARTIFACT_PATHS.preflight]));
+    return errors;
+  }
+  if (current?.status !== "READY") {
+    errors.push(issue("E_PREFLIGHT_NOT_READY", "The current preflight evaluation is not READY", [ARTIFACT_PATHS.preflight]));
+  }
+  if (persisted.taskId !== current?.taskId) {
+    errors.push(issue(
+      "E_PREFLIGHT_TASK_MISMATCH",
+      "Persisted preflight does not belong to the current task",
+      [ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.contract],
+    ));
+  }
+  if (persisted.fingerprints?.contract !== current?.fingerprints?.contract
+    || persisted.contract?.fingerprint !== current?.contract?.fingerprint) {
+    errors.push(issue(
+      "E_PREFLIGHT_CONTRACT_STALE",
+      "Persisted preflight does not match the current contract fingerprint",
+      [ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.contract],
+    ));
+  }
+  if (persisted.fingerprints?.routing !== current?.fingerprints?.routing
+    || persisted.routing?.fingerprint !== current?.routing?.fingerprint) {
+    errors.push(issue(
+      "E_PREFLIGHT_ROUTE_STALE",
+      "Persisted preflight does not match the current routing fingerprint",
+      [ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.route],
+    ));
+  }
+  if (!sameStringSet(persisted.requiredGates, current?.requiredGates)
+    || !sameStringSet(persisted.satisfiedGates, current?.satisfiedGates)) {
+    errors.push(issue(
+      "E_PREFLIGHT_GATES_STALE",
+      "Persisted preflight gate sets do not match the current evaluation",
+      [ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.gates],
+    ));
+  }
+  return sortIssues(errors);
+}
+
 async function readProfile(target) {
   const relativePath = "PROJECT_PROFILE.md";
   await assertSafePath(target, relativePath);
@@ -219,11 +280,112 @@ export async function evaluatePreflight({ target, packageRoot, strict = false }
   };
 }
 
+async function readOptionalIdentityArtifact(readArtifact, invalidCode, artifactPath) {
+  try {
+    return await readArtifact();
+  } catch (error) {
+    if (error.code === "ARTIFACT_MISSING") return null;
+    throw preflightError(invalidCode, error.message, [artifactPath]);
+  }
+}
+
+async function assertPreflightPersistenceSafety(target, packageRoot, taskId) {
+  let state;
+  try {
+    state = await readWorkState(target, packageRoot);
+  } catch (error) {
+    throw preflightError("E_STATE_INVALID", error.message, [ARTIFACT_PATHS.state]);
+  }
+  const contract = await readOptionalIdentityArtifact(
+    () => readContract(target, packageRoot),
+    "E_CONTRACT_INVALID",
+    ARTIFACT_PATHS.contract,
+  );
+  const route = await readOptionalIdentityArtifact(
+    () => readPersistedRoute(target, packageRoot),
+    "E_ROUTE_INVALID",
+    ARTIFACT_PATHS.route,
+  );
+  if (state) {
+    if (contract || route) assertStateIdentity({ contract, route, state });
+  }
+
+  if (taskId === "unknown") return null;
+  const ledger = await validateEventLedger(target, packageRoot);
+  if (!ledger.valid) {
+    const first = ledger.errors[0];
+    throw preflightError(first.code, first.message, [ARTIFACT_PATHS.events]);
+  }
+  if (ledger.events.some((event) => event.taskId !== taskId)) {
+    throw preflightError(
+      "E_PHASE_CHRONOLOGY_INVALID",
+      "Preflight cannot append events to a ledger owned by a different task",
+      [ARTIFACT_PATHS.events, ARTIFACT_PATHS.contract],
+    );
+  }
+  return ledger;
+}
+
+const PREFLIGHT_IDENTITY_BARRIER_CODES = new Set([
+  "E_CONTRACT_STALE",
+  "E_GATE_TASK_MISMATCH",
+  "E_ROUTE_STALE",
+  "E_STATE_TASK_MISMATCH",
+  "E_ROUTE_GUIDE_MISMATCH",
+]);
+
+function assertPreflightResultPersistenceSafety(result) {
+  const identityError = result.errors.find((error) => PREFLIGHT_IDENTITY_BARRIER_CODES.has(error.code));
+  if (identityError) {
+    throw preflightError(identityError.code, identityError.message, identityError.artifacts);
+  }
+}
+
+function sameReadyPreflightEvent(event, result) {
+  return event.fingerprint === result.fingerprints.contract
+    && event.details?.routingFingerprint === result.fingerprints.routing
+    && sameStringSet(event.details?.requiredGates, result.requiredGates)
+    && sameStringSet(event.details?.satisfiedGates, result.satisfiedGates);
+}
+
+function planReadyPreflightLifecycleWrite(ledger, result) {
+  if (!ledger) return { appendEvents: false };
+  const existing = ledger.events.find((event) => event.event === "PREFLIGHT_READY");
+  if (existing) {
+    if (sameReadyPreflightEvent(existing, result)) return { appendEvents: false };
+    throw preflightError(
+      "E_PHASE_CHRONOLOGY_INVALID",
+      "PREFLIGHT_READY already exists with different READY preflight details; repair the contract, route, or gate lifecycle before refreshing preflight",
+      [ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.events, ARTIFACT_PATHS.contract, ARTIFACT_PATHS.route, ARTIFACT_PATHS.gates],
+    );
+  }
+  const lastMilestone = ledger.events.reduce(
+    (last, event) => Math.max(last, LIFECYCLE_MILESTONES.indexOf(event.event)),
+    -1,
+  );
+  const routeMilestone = LIFECYCLE_MILESTONES.indexOf("ROUTE_VALIDATED");
+  const preflightMilestone = LIFECYCLE_MILESTONES.indexOf("PREFLIGHT_READY");
+  if (lastMilestone < routeMilestone) return { appendEvents: false };
+  if (lastMilestone !== preflightMilestone - 1) {
+    throw preflightError(
+      "E_PHASE_CHRONOLOGY_INVALID",
+      "PREFLIGHT_READY cannot be appended after the current lifecycle ledger",
+      [ARTIFACT_PATHS.events],
+    );
+  }
+  return { appendEvents: true };
+}
+
 export async function runPreflight({ target, packageRoot, strict = false, persist = true } = {}) {
   const result = await evaluatePreflight({ target, packageRoot, strict });
   if (persist) {
+    const ledger = await assertPreflightPersistenceSafety(target, packageRoot, result.taskId);
+    assertPreflightResultPersistenceSafety(result);
+    const lifecycleWrite = result.status === "READY"
+      ? planReadyPreflightLifecycleWrite(ledger, result)
+      : { appendEvents: true };
     await writeJsonArtifact(target, ARTIFACT_PATHS.preflight, result, "preflight", packageRoot);
-    if (result.taskId !== "unknown") {
+    if (result.taskId !== "unknown" && lifecycleWrite.appendEvents) {
       for (const gate of result.satisfiedGates) {
         await appendProtocolEvent(target, {
           taskId: result.taskId,
@@ -238,6 +400,7 @@ export async function runPreflight({ target, packageRoot, strict = false, persis
         details: {
           requiredGates: result.requiredGates,
           satisfiedGates: result.satisfiedGates,
+          routingFingerprint: result.fingerprints.routing,
         },
       }, packageRoot);
     }