@cassiomc1/forgeloop 1.12.0 → 1.14.0

package/src/core/phase.js

@@ -5,6 +5,7 @@ import {
   LIFECYCLE_MILESTONES,
   validateEventLedger,
   validateStateLedgerCoherence,
+  isRevisionEpochPlanRepeat,
 } from "./events.js";
 import { readPersistedRoute } from "./route-artifact.js";
 import { assertWorkPhase, isValidTransition } from "./protocol.js";
@@ -13,7 +14,7 @@ import { authorizeCompletionRecoveryOrRebind } from "./completion-recovery-rebin
 import { evaluateCompletion, runComplete as persistCompletion } from "./completion.js";
 import { evaluatePreflight } from "./preflight.js";
 import { requiredEvidenceForTarget } from "./completion-artifacts.js";
-import { assertCompletionRelationships, assertStateIdentity } from "./completion-relationships.js";
+import { assertCompletionRelationships, assertStateIdentity, stateIdentityErrors } from "./completion-relationships.js";
 import { createReceipt, validateReceipt } from "./receipt.js";
 import { assertExecutionPrerequisites, hasExecutionStarted } from "./execution-prerequisites.js";
 import { taskArtifactPath } from "./task-paths.js";
@@ -27,6 +28,13 @@ import {
   evaluateStructuredDiagnosticStall,
 } from "./information-gain-projection.js";
 import { assertStructuralQualityExecutionReady } from "./structural-quality/service.js";
+import { getTaskTransaction, withTaskTransaction } from "./transaction.js";
+import {
+  CONTRACT_BOOTSTRAP_REPAIR_EVENT,
+  ROUTE_CHECKPOINT_BOUND_EVENT,
+  resolveCanonicalPostRepairCheckpointBinding,
+  sameCanonicalGuideList,
+} from "./contract-bootstrap-recovery.js";
 
 function phaseError(code, message, artifacts = []) {
   const error = new Error(message);
@@ -55,15 +63,13 @@ const LATE_PHASES = new Set([
   "COMPLETE",
 ]);
 
-async function assertPersistedStateIdentity(target, state, toPhase, packageRoot, options = {}) {
+async function readPhaseIdentityArtifacts(target, state, toPhase, packageRoot, options, paths) {
   const scopedTaskId = options.taskId ?? null;
   const requireContract = LATE_PHASES.has(state.phase)
     || ["CONTRACT_READY", "ROUTED", "EXECUTING"].includes(toPhase);
-  const requireRoute = LATE_PHASES.has(state.phase)
+  const requireRoute = state.phase === "ROUTED"
+    || LATE_PHASES.has(state.phase)
     || ["ROUTED", "EXECUTING"].includes(toPhase);
-  const contractRel = options.contractPath ?? (scopedTaskId ? taskArtifactPath(scopedTaskId, "contract") : ARTIFACT_PATHS.contract);
-  const routeRel = options.routePath ?? (scopedTaskId ? taskArtifactPath(scopedTaskId, "route") : ARTIFACT_PATHS.route);
-
   let contract = null;
   let route = null;
   try {
@@ -75,7 +81,7 @@ async function assertPersistedStateIdentity(target, state, toPhase, packageRoot,
       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}`,
-        [contractRel],
+        [paths.contractRel],
       );
     }
   }
@@ -88,11 +94,69 @@ async function assertPersistedStateIdentity(target, state, toPhase, packageRoot,
       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}`,
-        [routeRel],
+        [paths.routeRel],
       );
     }
   }
+  return { contract, route };
+}
+
+function assertRepairedCheckpointIdentity({ contract, route, state, events, contractRel, routeRel, stateRel }) {
+  const repairMarker = events.find((event) => event.event === CONTRACT_BOOTSTRAP_REPAIR_EVENT);
+  if (!repairMarker || state.phase === "ROUTED") return false;
+  const checkpoint = resolveCanonicalPostRepairCheckpointBinding(events, repairMarker);
+  if (!checkpoint) {
+    throw phaseError(
+      "E_PHASE_CHRONOLOGY_INVALID",
+      "Repaired late-phase state requires a canonical route checkpoint binding",
+      [contractRel, routeRel],
+    );
+  }
+  const identityErrors = [
+    ...stateIdentityErrors({ contract, state }),
+    ...stateIdentityErrors({ contract, route }),
+  ];
+  if (state.routeFingerprint !== checkpoint.routeFingerprint
+    || !sameCanonicalGuideList(state.selectedGuides, checkpoint.selectedGuides)) {
+    identityErrors.push({
+      code: "E_ROUTE_GUIDE_MISMATCH",
+      message: "Work state does not match the immutable route checkpoint identity",
+      artifacts: [routeRel, stateRel],
+    });
+  }
+  if (identityErrors.length > 0) {
+    const first = identityErrors[0];
+    throw phaseError(first.code, first.message, first.artifacts);
+  }
+  return true;
+}
+
+async function assertPersistedStateIdentity(target, state, toPhase, packageRoot, options = {}) {
+  const scopedTaskId = options.taskId ?? null;
+  const events = options.events ?? [];
+  const contractRel = options.contractPath ?? (scopedTaskId ? taskArtifactPath(scopedTaskId, "contract") : ARTIFACT_PATHS.contract);
+  const routeRel = options.routePath ?? (scopedTaskId ? taskArtifactPath(scopedTaskId, "route") : ARTIFACT_PATHS.route);
+  const stateRel = options.statePath ?? (scopedTaskId ? taskArtifactPath(scopedTaskId, "state") : ARTIFACT_PATHS.state);
+  const { contract, route } = await readPhaseIdentityArtifacts(
+    target,
+    state,
+    toPhase,
+    packageRoot,
+    options,
+    { contractRel, routeRel },
+  );
   if (!contract && !route) return;
+  if (toPhase !== "ROUTED" && assertRepairedCheckpointIdentity({
+    contract,
+    route,
+    state,
+    events,
+    contractRel,
+    routeRel,
+    stateRel,
+  })) {
+    return;
+  }
   try {
     assertStateIdentity({ contract, route, state });
   } catch (error) {
@@ -116,6 +180,11 @@ function reconcileImplementationStep(state, toPhase) {
   };
 }
 
+function isRevisionPlanRepeat(events, eventType) {
+  return eventType === "PLAN_RECORDED"
+    && isRevisionEpochPlanRepeat(events, events.length, { event: eventType });
+}
+
 async function assertPhasePrerequisites(target, state, toPhase, packageRoot, authorityContext, runtimeContext, options = {}) {
   const scopedTaskId = options.taskId ?? null;
   const contractRel = options.contractPath ?? (scopedTaskId ? taskArtifactPath(scopedTaskId, "contract") : ARTIFACT_PATHS.contract);
@@ -160,8 +229,39 @@ async function assertPhasePrerequisites(target, state, toPhase, packageRoot, aut
   }
 }
 
+async function appendRepairRouteCheckpoint({ target, packageRoot, taskId, state, events, stateRel, eventsRel }) {
+  const repairMarker = events.find((event) => event.event === CONTRACT_BOOTSTRAP_REPAIR_EVENT);
+  const checkpointAlreadyBound = events.some((event) => event.event === ROUTE_CHECKPOINT_BOUND_EVENT);
+  if (!repairMarker || state.phase !== "ROUTED" || checkpointAlreadyBound) return;
+  if (typeof state.routeFingerprint !== "string") {
+    throw phaseError("E_ROUTE_GUIDE_MISMATCH", "ROUTED state requires a route fingerprint before checkpoint binding", [stateRel, eventsRel]);
+  }
+  await appendProtocolEvent(target, {
+    taskId: state.taskId,
+    event: ROUTE_CHECKPOINT_BOUND_EVENT,
+    details: {
+      routeFingerprint: state.routeFingerprint,
+      contractFingerprint: state.contractFingerprint,
+      selectedGuides: [...state.selectedGuides].sort(),
+    },
+  }, packageRoot, { taskId, eventsPath: eventsRel });
+}
+
 export async function advanceWorkState(target, toPhase, options = {}) {
   const normalizedOptions = typeof options === "string" ? { packageRoot: options } : options;
+  if (!normalizedOptions.taskId || await getTaskTransaction(target)) {
+    return advanceWorkStateInternal(target, toPhase, normalizedOptions);
+  }
+  return withTaskTransaction({
+    target,
+    taskId: normalizedOptions.taskId,
+    operation: "advance",
+    packageRoot: normalizedOptions.packageRoot,
+    recordCommitEvent: true,
+  }, async () => advanceWorkStateInternal(target, toPhase, normalizedOptions));
+}
+
+async function advanceWorkStateInternal(target, toPhase, normalizedOptions) {
   const {
     packageRoot,
     now = new Date().toISOString(),
@@ -211,7 +311,6 @@ export async function advanceWorkState(target, toPhase, options = {}) {
   }
 
   await assertPhasePrerequisites(target, state, toPhase, packageRoot, authorityContext, runtimeContext, { taskId, statePath, contractPath, routePath, receiptPath, eventsPath });
-  await assertPersistedStateIdentity(target, state, toPhase, packageRoot, { taskId, contractPath, routePath });
 
   if (toPhase === "EXECUTING" && taskId) {
     // Multi-task checkout scope checks
@@ -259,6 +358,12 @@ export async function advanceWorkState(target, toPhase, options = {}) {
   if (coherenceErrors.length > 0) {
     throw phaseError(coherenceErrors[0].code, coherenceErrors[0].message, [stateRel, eventsRel]);
   }
+  await assertPersistedStateIdentity(target, state, toPhase, packageRoot, {
+    taskId,
+    contractPath,
+    routePath,
+    events: ledger.events,
+  });
   const eventType = PHASE_EVENTS[toPhase];
   const reenteringVerification = toPhase === "VERIFYING" && ["CORRECTING", "REVIEWING"].includes(state.phase);
   if (toPhase === "VERIFYING" && state.phase === "REVIEWING") {
@@ -338,11 +443,15 @@ export async function advanceWorkState(target, toPhase, options = {}) {
   }
   const repeatedReview = state.phase === "VERIFYING" && toPhase === "REVIEWING"
     && ledger.events.some((event) => event.taskId === state.taskId && event.event === "REVIEW_STARTED");
+  const revisionPlanRepeat = isRevisionPlanRepeat(ledger.events, eventType);
   if (eventType && !reenteringVerification && !repeatedReview
+    && !revisionPlanRepeat
     && ledger.events.some((event) => event.taskId === state.taskId && event.event === eventType)) {
     throw phaseError("E_PHASE_CHRONOLOGY_INVALID", `Lifecycle milestone already exists: ${eventType}`, [eventsRel]);
   }
-  const milestoneIndex = reenteringVerification || repeatedReview ? -1 : LIFECYCLE_MILESTONES.indexOf(eventType);
+  const milestoneIndex = reenteringVerification || repeatedReview || revisionPlanRepeat
+    ? -1
+    : 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) {
@@ -361,6 +470,15 @@ export async function advanceWorkState(target, toPhase, options = {}) {
   }
   if (reenteringVerification) delete next.lastCompletionAttempt;
   next.revision = (state.revision ?? 0) + 1;
+  await appendRepairRouteCheckpoint({
+    target,
+    packageRoot,
+    taskId,
+    state,
+    events: ledger.events,
+    stateRel,
+    eventsRel,
+  });
   let nextReceipt = null;
   try {
     const receipt = await readJsonArtifact(target, receiptRel, "execution-receipt", packageRoot);

package/src/core/php-project.js

@@ -0,0 +1,85 @@
+import { createLanguageProject, PHP_SOURCE_EXTENSIONS } from "./multi-language-project.js";
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function invalidComposer() {
+  return {
+    valid: false,
+    name: null,
+    type: null,
+    autoload: false,
+    requirements: [],
+  };
+}
+
+function hasValidComposerSections(value) {
+  const requirementFields = ["require", "require-dev", "replace", "provide", "conflict"];
+  if (requirementFields.some((field) => value[field] !== undefined && !isPlainObject(value[field]))) return false;
+  const autoload = value.autoload === undefined || isPlainObject(value.autoload);
+  const autoloadDev = value["autoload-dev"] === undefined || isPlainObject(value["autoload-dev"]);
+  return autoload && autoloadDev;
+}
+
+function composerStringField(value, field) {
+  if (value[field] === undefined) return null;
+  return typeof value[field] === "string" && value[field].trim() !== "" ? value[field] : undefined;
+}
+
+function hasComposerIdentity(value) {
+  return value.name !== undefined
+    || value.require !== undefined
+    || value.autoload !== undefined
+    || value["autoload-dev"] !== undefined;
+}
+
+function parseComposerValue(value) {
+  if (!isPlainObject(value) || !hasValidComposerSections(value)) return invalidComposer();
+  const name = composerStringField(value, "name");
+  const type = composerStringField(value, "type");
+  if (name === undefined || type === undefined || !hasComposerIdentity(value)) return invalidComposer();
+  const hasPhpIdentity = name !== null || value.require !== undefined || value.autoload !== undefined || value["autoload-dev"] !== undefined;
+  if (!hasPhpIdentity) return invalidComposer();
+  return {
+    valid: true,
+    name,
+    type,
+    autoload: value.autoload !== undefined || value["autoload-dev"] !== undefined,
+    requirements: Object.keys(value.require ?? {}).sort((left, right) => left.localeCompare(right)),
+  };
+}
+
+export function parseComposerJson(text) {
+  if (typeof text !== "string" || text.length > 1024 * 1024 || /\r(?!\n)/u.test(text)) return invalidComposer();
+  try {
+    return parseComposerValue(JSON.parse(text));
+  } catch {
+    return invalidComposer();
+  }
+}
+
+export function phpSourceLooksExecutable(text) {
+  return typeof text === "string" && /<\?(?:php(?:\s|$)|=)/iu.test(text);
+}
+
+export function inspectPhpProject({ projectRoot, manifestRelative, manifestText }) {
+  const parsed = parseComposerJson(manifestText);
+  const primary = parsed.valid;
+  const primarySignals = primary ? [`${manifestRelative}:composer`] : [];
+  const supportingSignals = [];
+  if (parsed.name) supportingSignals.push(`${manifestRelative}:name=${parsed.name}`);
+  if (parsed.type) supportingSignals.push(`${manifestRelative}:type=${parsed.type}`);
+  if (parsed.autoload) supportingSignals.push(`${manifestRelative}:autoload`);
+  for (const requirement of parsed.requirements) supportingSignals.push(`${manifestRelative}:require=${requirement}`);
+  return createLanguageProject({
+    kind: "php",
+    root: projectRoot,
+    manifest: manifestRelative,
+    frameworks: primary ? ["php"] : [],
+    primary,
+    primarySignals,
+    supportingSignals,
+    internal: { ...parsed, phpSourceExtensions: [...PHP_SOURCE_EXTENSIONS] },
+  });
+}

package/src/core/preflight-consistency.js

@@ -80,6 +80,18 @@ function sameReadyPreflightEvent(event, result) {
     && sameStringSet(event.details?.satisfiedGates, result.satisfiedGates);
 }
 
+function latestContractRevisionSeq(events) {
+  return events.findLast((event) => event.event === "CONTRACT_REVISED")?.seq ?? 0;
+}
+
+function hasCurrentRevisionGate(events, taskId, gate) {
+  const revisionSeq = latestContractRevisionSeq(events);
+  return events.some((event) => event.event === "GATE_SATISFIED"
+    && event.taskId === taskId
+    && event.details?.gate === gate
+    && event.seq > revisionSeq);
+}
+
 export async function validateReadyProtocolConsistency({
   target,
   packageRoot,
@@ -141,9 +153,7 @@ export async function validateReadyProtocolConsistency({
     }
   }
   for (const gate of persisted.satisfiedGates ?? []) {
-    if (!events.some((event) => event.event === "GATE_SATISFIED"
-      && event.taskId === persisted.taskId
-      && event.details?.gate === gate)) {
+    if (!hasCurrentRevisionGate(events, persisted.taskId, gate)) {
       errors.push(issue("E_PREFLIGHT_GATE_EVENT_MISSING", `READY preflight is missing lifecycle gate event: ${gate}`, [eventsRel, `${gatesRel}/${gate}.json`]));
     }
   }
@@ -189,9 +199,12 @@ export function assertExistingReadyLifecycleCompatibility(ledger, result) {
   const existingReady = events.findLast((event) => event.event === "PREFLIGHT_READY" && event.taskId === result.taskId);
   if (!existingReady) return;
   const latestOutcome = latestPreflightOutcomeEvent(events, result.taskId);
+  const revisedAfterReady = events.some((event) => event.event === "CONTRACT_REVISED"
+    && event.taskId === result.taskId
+    && event.seq > existingReady.seq);
   // A READY outcome superseded by a later BLOCKED outcome may be replaced by a
   // fresh READY with different details once the blocked preflight is resolved.
-  if (latestOutcome?.event === "PREFLIGHT_BLOCKED") return;
+  if (latestOutcome?.event === "PREFLIGHT_BLOCKED" || revisedAfterReady) return;
   if (!sameReadyPreflightEvent(existingReady, result)) {
     throw preflightError(
       "E_PHASE_CHRONOLOGY_INVALID",
@@ -217,9 +230,7 @@ export async function appendActivationEvents(target, packageRoot, ledger, result
     await append({ taskId: result.taskId, event: "ROUTE_VALIDATED", fingerprint: result.fingerprints.routing });
   }
   for (const gate of result.satisfiedGates) {
-    if (!events.some((event) => event.event === "GATE_SATISFIED"
-      && event.taskId === result.taskId
-      && event.details?.gate === gate)) {
+    if (!hasCurrentRevisionGate(events, result.taskId, gate)) {
       await append({ taskId: result.taskId, event: "GATE_SATISFIED", details: { gate } });
     }
   }
@@ -227,15 +238,18 @@ export async function appendActivationEvents(target, packageRoot, ledger, result
   const existingReady = events.findLast((event) => event.event === "PREFLIGHT_READY" && event.taskId === result.taskId);
   const latestOutcome = latestPreflightOutcomeEvent(events, result.taskId);
   const readySupersededByBlocked = existingReady && latestOutcome?.event === "PREFLIGHT_BLOCKED";
+  const readySupersededByContractRevision = existingReady && events.some((event) => event.event === "CONTRACT_REVISED"
+    && event.taskId === result.taskId
+    && event.seq > existingReady.seq);
   if (result.status === "READY") {
-    if (existingReady && !readySupersededByBlocked && !sameReadyPreflightEvent(existingReady, result)) {
+    if (existingReady && !readySupersededByBlocked && !readySupersededByContractRevision && !sameReadyPreflightEvent(existingReady, result)) {
       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],
       );
     }
-    if (!existingReady || readySupersededByBlocked) {
+    if (!existingReady || readySupersededByBlocked || readySupersededByContractRevision) {
       await append({
         taskId: result.taskId,
         event: "PREFLIGHT_READY",

package/src/core/preflight-loaders.js

@@ -2,13 +2,15 @@ import { ARTIFACT_PATHS, readJsonArtifact } from "./artifacts.js";
 import { readContract } from "./contract.js";
 import { readGateIfPresent, validateGateArtifacts } from "./gate-artifact.js";
 import { requiredGatesForGuides } from "./guide-metadata.js";
-import { assertSourceProvenance } from "./sources.js";
+import { assertContractPresetRefs, assertContractSourceProvenance, externalContractSourceRefs } from "./sources.js";
 import { readPersistedRoute } from "./route-artifact.js";
 import { ensureWithin, readBytes } from "./filesystem.js";
 import { sha256 } from "./manifest.js";
 import { findProfilePath } from "./profile.js";
 import { issue } from "./preflight-model.js";
 import { taskGatePath, taskArtifactPath } from "./task-paths.js";
+import { readEvents } from "./events.js";
+import { hasCurrentGateEvidence } from "./gate-provenance.js";
 
 export async function readProfile(target) {
   const relativePath = await findProfilePath(target);
@@ -62,15 +64,25 @@ export async function loadRoute(target, packageRoot, errors, options = {}) {
 
 export async function loadSources(target, contract, packageRoot, errors) {
   if (!contract?.value?.sourceRefs?.length) return null;
-  let registry;
+  const refs = contract.value.sourceRefs;
   try {
-    registry = (await readJsonArtifact(target, ARTIFACT_PATHS.sources, "source-registry", packageRoot)).value;
+    assertContractPresetRefs(refs);
   } catch (error) {
-    errors.push(issue(error.code === "ARTIFACT_MISSING" ? "E_PROFILE_SOURCE_MISSING" : "E_PROFILE_SOURCE_UNKNOWN", error.message, [ARTIFACT_PATHS.sources]));
+    errors.push(issue(error.code ?? "E_PROFILE_SOURCE_UNKNOWN", error.message, [ARTIFACT_PATHS.sources]));
     return null;
   }
+  const externalRefs = externalContractSourceRefs(refs);
+  let registry;
+  if (externalRefs.length > 0) {
+    try {
+      registry = (await readJsonArtifact(target, ARTIFACT_PATHS.sources, "source-registry", packageRoot)).value;
+    } catch (error) {
+      errors.push(issue(error.code === "ARTIFACT_MISSING" ? "E_PROFILE_SOURCE_MISSING" : "E_PROFILE_SOURCE_UNKNOWN", error.message, [ARTIFACT_PATHS.sources]));
+      return null;
+    }
+  }
   try {
-    assertSourceProvenance(registry, contract.value.sourceRefs);
+    assertContractSourceProvenance(registry, refs);
   } catch (error) {
     errors.push(issue(error.code ?? "E_PROFILE_SOURCE_UNKNOWN", error.message, [ARTIFACT_PATHS.sources]));
   }
@@ -84,6 +96,15 @@ export async function inspectGates(target, contract, route, packageRoot, errors,
   const satisfied = [];
   const records = {};
   const taskId = options.taskId ?? null;
+  let events = [];
+  if (taskId) {
+    try {
+      events = await readEvents(target, packageRoot, { taskId });
+    } catch {
+      events = [];
+    }
+  }
+  const latestContractRevisionSeq = events.findLast((event) => event.event === "CONTRACT_REVISED")?.seq ?? 0;
   for (const gate of required) {
     let artifact;
     const defaultGateRel = taskId ? taskGatePath(taskId, gate) : `${ARTIFACT_PATHS.gates}/${gate}.json`;
@@ -111,6 +132,17 @@ export async function inspectGates(target, contract, route, packageRoot, errors,
       errors.push(issue("E_GATE_STALE", `Gate ${gate} references stale artifacts`, [artifact.path], { gate, stale }));
       continue;
     }
+    const currentEpochSatisfied = latestContractRevisionSeq === 0
+      || hasCurrentGateEvidence(events, taskId, gate, latestContractRevisionSeq);
+    if (!currentEpochSatisfied) {
+      errors.push(issue(
+        "E_GATE_UNVERIFIED",
+        `Required gate ${gate} was satisfied before the current contract revision`,
+        [defaultGateRel],
+        { gate },
+      ));
+      continue;
+    }
     satisfied.push(gate);
   }
   return { required, satisfied: satisfied.sort(), records };