@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

package/src/core/reflection.js

@@ -1,7 +1,9 @@
+import { ledgerEventsOfTypes } from "./ledger-event-collection.js";
+import { ledgerRelationMap, ledgerRelationSet, ledgerGroupedSet } from "./ledger-relations.js";
 import { buildTaskTrace } from "./trace.js";
 import { readEvents } from "./events.js";
 import { findTaskById } from "./task-discovery.js";
-import { projectHypothesisStates } from "./hypothesis-projection.js";
+import { projectHypothesisStates, summarizeOpenHypotheses } from "./hypothesis-projection.js";
 import {
   buildInformationGainProjection,
   evaluateStructuredDiagnosticStall,
@@ -64,11 +66,9 @@ export function evaluateInterventionEffectiveness(trace, surfacesByCycle) {
 }
 
 function failedRequirementSurfacesFromEvents(events = [], state = null) {
-  const byCycle = new Map();
+  const byCycle = ledgerGroupedSet();
   const record = (cycle, requirement) => {
-    if (!requirement) return;
-    if (!byCycle.has(cycle)) byCycle.set(cycle, new Set());
-    byCycle.get(cycle).add(requirement);
+    if (requirement) byCycle.add(cycle, requirement);
   };
   for (const event of events) {
     if (event.event !== "VERIFICATION_RECORDED") continue;
@@ -95,88 +95,83 @@ function signatureSetsByCycle(trace) {
   return byCycle;
 }
 
-export function deriveDiagnosticContext(events = [], state = null) {
-  const cycle = state?.verificationCycle ?? null;
-  const taskEvents = events.filter((event) => !state?.taskId || event.taskId === state.taskId);
-
-  // Canonical failure-signature hashes for the active verification cycle.
-  const activeFailureSignatures = [...new Set(
-    taskEvents
-      .filter((event) => event.event === "VERIFICATION_RECORDED"
-        && ["failed", "blocked"].includes(event.details?.status)
-        && (cycle === null || event.details?.verificationCycle === cycle))
-      .map((event) => {
-        const d = event.details;
-        return computeFailureSignature({
-          requirement: d.requirement ?? d.id ?? d.checkId,
-          status: d.status,
-          exitCode: Number.isInteger(d.exitCode) ? d.exitCode : null,
-          failureToken: typeof d.failureToken === "string" && d.failureToken
-            ? d.failureToken
-            : (typeof d.details?.failureToken === "string" ? d.details.failureToken : null),
-        });
-      }),
-  )].sort();
-
-  const activeFailedRequirements = [...new Set(
-    [
-      ...taskEvents
-        .filter((event) => event.event === "VERIFICATION_RECORDED"
-          && ["failed", "blocked"].includes(event.details?.status)
-          && (cycle === null || event.details?.verificationCycle === cycle))
-        .map((event) => event.details?.requirement ?? event.details?.id ?? event.details?.checkId),
-      ...((state?.checks ?? []))
-        .filter((check) => ["failed", "blocked"].includes(check.status)
-          && (cycle === null || check.details?.verificationCycle === cycle))
-        .map((check) => check.requirement ?? check.id ?? check.checkId),
-    ].filter(Boolean),
-  )].sort();
+function* contextEvents(events, types, taskId) {
+  for (const event of ledgerEventsOfTypes(events, types)) if (!taskId || event.taskId === taskId) yield event;
+}
 
-  const projection = projectHypothesisStates(taskEvents);
-  const openHypotheses = [...projection.openHypotheses].sort();
+function contextFailureSignature(details) {
+  return computeFailureSignature({ requirement: details.requirement ?? details.id ?? details.checkId,
+    status: details.status, exitCode: Number.isInteger(details.exitCode) ? details.exitCode : null,
+    failureToken: typeof details.failureToken === "string" && details.failureToken
+      ? details.failureToken : (typeof details.details?.failureToken === "string" ? details.details.failureToken : null) });
+}
 
-  const interventions = taskEvents.filter((event) => event.event === "INTERVENTION_RECORDED");
-  const latestIntervention = interventions.at(-1)?.details?.intervention?.id ?? null;
+function activeFailure(details, cycle, observedCycle) {
+  return ["failed", "blocked"].includes(details?.status) && (cycle === null || observedCycle === cycle);
+}
 
-  // doNotRepeat requires semantic repetition AND at least two completed
-  // post-intervention verification cycles AND unchanged failure surface.
-  const surfacesByCycle = failedRequirementSurfacesFromEvents(taskEvents, state);
-  const completedCycles = [...new Set(
-    taskEvents.filter((event) => event.event === "VERIFICATION_STARTED")
-      .map((event) => event.details?.verificationCycle)
-      .filter(Number.isInteger),
-  )].sort((a, b) => a - b);
+function activeContextFailures(events, state, cycle) {
+  const signatures = new Set();
+  const requirements = new Set();
+  for (const event of contextEvents(events, ["VERIFICATION_RECORDED"], state?.taskId)) {
+    const details = event.details;
+    if (!activeFailure(details, cycle, details?.verificationCycle)) continue;
+    signatures.add(contextFailureSignature(details));
+    const requirement = details.requirement ?? details.id ?? details.checkId;
+    if (requirement) requirements.add(requirement);
+  }
+  for (const check of state?.checks ?? []) {
+    if (!activeFailure(check, cycle, check.details?.verificationCycle)) continue;
+    const requirement = check.requirement ?? check.id ?? check.checkId;
+    if (requirement) requirements.add(requirement);
+  }
+  return { activeFailureSignatures: [...signatures].sort(), activeFailedRequirements: [...requirements].sort() };
+}
 
-  const fingerprintGroups = new Map();
-  for (const event of interventions) {
+function contextInterventions(events, taskId) {
+  const groups = ledgerRelationMap();
+  const lastCycles = ledgerRelationMap();
+  const invalidCycles = ledgerRelationSet();
+  let latestIntervention = null;
+  for (const event of contextEvents(events, ["INTERVENTION_RECORDED"], taskId)) {
+    latestIntervention = event.details?.intervention?.id ?? null;
     const fingerprint = event.details?.interventionSemanticFingerprint;
     if (!fingerprint) continue;
-    if (!fingerprintGroups.has(fingerprint)) fingerprintGroups.set(fingerprint, []);
-    fingerprintGroups.get(fingerprint).push(event);
+    groups.set(fingerprint, (groups.get(fingerprint) ?? 0) + 1);
+    const cycle = Number(event.details?.verificationCycle ?? 1);
+    if (!Number.isFinite(cycle)) invalidCycles.add(fingerprint);
+    else lastCycles.set(fingerprint, Math.max(lastCycles.get(fingerprint) ?? -Infinity, cycle));
   }
+  return { groups, lastCycles, invalidCycles, latestIntervention };
+}
 
+export function deriveDiagnosticContext(events = [], state = null) {
+  const cycle = state?.verificationCycle ?? null;
+  const failures = activeContextFailures(events, state, cycle);
+  const openHypotheses = summarizeOpenHypotheses(events, state?.taskId).sort();
+  const relevant = { *[Symbol.iterator]() {
+    yield* contextEvents(events, ["VERIFICATION_RECORDED"], state?.taskId);
+  } };
+  const surfacesByCycle = failedRequirementSurfacesFromEvents(relevant, state);
+  const cycles = new Set();
+  for (const event of contextEvents(events, ["VERIFICATION_STARTED"], state?.taskId)) {
+    if (Number.isInteger(event.details?.verificationCycle)) cycles.add(event.details.verificationCycle);
+  }
+  const completedCycles = [...cycles].sort((a, b) => a - b);
+  const { groups, lastCycles, invalidCycles, latestIntervention } = contextInterventions(events, state?.taskId);
   const doNotRepeat = [];
-  for (const [fingerprint, group] of fingerprintGroups.entries()) {
-    if (group.length < 2) continue;
-    const lastInterventionCycle = Math.max(...group.map((event) => event.details?.verificationCycle ?? 1));
-    const postCycles = completedCycles.filter((completed) => completed > lastInterventionCycle);
-    if (postCycles.length < 2) continue;
-    const firstSurface = [...(surfacesByCycle.get(lastInterventionCycle) ?? [])].sort();
-    const latestSurface = [...(surfacesByCycle.get(postCycles.at(-1)) ?? [])].sort();
-    if (JSON.stringify(firstSurface) === JSON.stringify(latestSurface)) {
-      doNotRepeat.push(fingerprint);
-    }
+  for (const [fingerprint, countOfInterventions] of groups) {
+    if (countOfInterventions < 2 || invalidCycles.has(fingerprint)) continue;
+    const lastCycle = lastCycles.get(fingerprint);
+    let count = 0;
+    let latestCycle = null;
+    for (const completed of completedCycles) if (completed > lastCycle) { count++; latestCycle = completed; }
+    if (count < 2) continue;
+    const firstSurface = [...(surfacesByCycle.values(lastCycle))].sort();
+    const latestSurface = [...(surfacesByCycle.values(latestCycle))].sort();
+    if (JSON.stringify(firstSurface) === JSON.stringify(latestSurface)) doNotRepeat.push(fingerprint);
   }
-  doNotRepeat.sort();
-
-  return {
-    activeFailureSignatures,
-    activeFailedRequirements,
-    openHypotheses,
-    latestIntervention,
-    nextExperiment: null,
-    doNotRepeat,
-  };
+  return { ...failures, openHypotheses, latestIntervention, nextExperiment: null, doNotRepeat: doNotRepeat.sort() };
 }
 
 export async function buildTaskReflection({ target, packageRoot, taskId = null } = {}) {

package/src/core/responsibility.js

@@ -10,7 +10,9 @@ import { resolveTaskClaimState } from "./task-claim-state.js";
 import { normalizeWriteClaims } from "./task-scope.js";
 import { taskResponsibilityPath } from "./task-paths.js";
 import { ensureWithin, fileExists } from "./filesystem.js";
-import { appendProtocolEvent } from "./events.js";
+import { getOperationalStore, operationalArtifactExists } from "../storage/operational-context.js";
+import { withNativeReadScope } from "./native-storage.js";
+import { appendProtocolEvent, withEventLedgerAudit } from "./events.js";
 import { withTaskTransaction } from "./transaction.js";
 import { assertTaskMutationAllowed } from "./task-claim-state.js";
 import { assertWorkspaceBinding } from "./workspace-binding.js";
@@ -118,17 +120,19 @@ export async function validateResponsibilityContract(value, packageRoot = getPac
 }
 
 export async function readResponsibility(target, { taskId, packageRoot = getPackageRoot() } = {}) {
-  const relativePath = taskResponsibilityPath(taskId);
-  if (!(await fileExists(ensureWithin(target, relativePath)))) return null;
-  try {
-    const artifact = await readJsonArtifact(target, relativePath, "responsibility", packageRoot);
-    const value = await validateResponsibilityContract(artifact.value, packageRoot);
-    if (value.taskId !== taskId) throw responsibilityError("E_RESPONSIBILITY_INVALID", "Responsibility taskId does not match its task namespace", [relativePath]);
-    return { ...artifact, value };
-  } catch (error) {
-    if (error.code === "E_RESPONSIBILITY_INVALID") throw error;
-    throw responsibilityError("E_RESPONSIBILITY_INVALID", `Responsibility contract is invalid: ${error.message}`, [relativePath]);
-  }
+  return withNativeReadScope(target, async () => {
+    const relativePath = taskResponsibilityPath(taskId);
+    if (!(operationalArtifactExists(target, relativePath) ?? await fileExists(ensureWithin(target, relativePath)))) return null;
+    try {
+      const artifact = await readJsonArtifact(target, relativePath, "responsibility", packageRoot);
+      const value = await validateResponsibilityContract(artifact.value, packageRoot);
+      if (value.taskId !== taskId) throw responsibilityError("E_RESPONSIBILITY_INVALID", "Responsibility taskId does not match its task namespace", [relativePath]);
+      return { ...artifact, value };
+    } catch (error) {
+      if (error.code === "E_RESPONSIBILITY_INVALID") throw error;
+      throw responsibilityError("E_RESPONSIBILITY_INVALID", `Responsibility contract is invalid: ${error.message}`, [relativePath]);
+    }
+  });
 }
 
 async function currentResponsibilityInputs(target, { taskId, packageRoot }) {
@@ -173,6 +177,14 @@ export function validateResponsibilityChecks(responsibility, state) {
 }
 
 export async function resolveResponsibilityStatus(target, { taskId, packageRoot = getPackageRoot() } = {}) {
+  const read = () => resolveLoadedResponsibilityStatus(target, { taskId, packageRoot });
+  return withNativeReadScope(target, () => {
+    if (getOperationalStore(target)) return withEventLedgerAudit(target, packageRoot, { taskId }, read);
+    return read();
+  });
+}
+
+async function resolveLoadedResponsibilityStatus(target, { taskId, packageRoot }) {
   const artifact = await readResponsibility(target, { taskId, packageRoot });
   if (!artifact) return { status: "NOT_APPLICABLE", taskId, path: taskResponsibilityPath(taskId), responsibility: null, errors: [] };
   let inputs;
@@ -245,7 +257,7 @@ export async function setResponsibilityContract(target, options = {}) {
   return withTaskTransaction({ target, taskId, packageRoot, operation: "responsibility-set", recordCommitEvent: true }, async () => {
     await assertTaskMutationAllowed(target, { taskId, packageRoot });
     await assertWorkspaceBinding(target, { taskId, packageRoot, operation: "responsibility-set" });
-    if (await fileExists(ensureWithin(target, relativePath))) {
+    if (operationalArtifactExists(target, relativePath) ?? await fileExists(ensureWithin(target, relativePath))) {
       throw responsibilityError("E_RESPONSIBILITY_INVALID", "Responsibility contract is immutable during a pass", [relativePath]);
     }
     const state = await readWorkState(target, { packageRoot, taskId });

package/src/core/resumability.js

@@ -4,6 +4,12 @@ import { createWorkState, initializeWorkState, readWorkState, mutateWorkState }
 
 const DEFAULT_PENDING_STEPS = ["planning", "implementation", "verification"];
 
+const CURRENT_ROUTE_CHECKPOINT_PHASES = new Set(["ROUTED"]);
+
+export function routeCheckpointMustMatchCurrentRoute(phase) {
+  return CURRENT_ROUTE_CHECKPOINT_PHASES.has(phase);
+}
+
 /**
  * Resume phase derived from the highest lifecycle milestone already recorded in
  * a validated ledger. Recreating a checkpoint at ROUTED for a task whose ledger
@@ -16,9 +22,88 @@ const RESUME_PHASE_BY_MILESTONE = Object.freeze({
   EXECUTION_STARTED: "EXECUTING",
   VERIFICATION_STARTED: "VERIFYING",
   VERIFICATION_RECORDED: "VERIFYING",
+  REVIEW_STARTED: "REVIEWING",
+});
+
+const RESUME_STEPS_BY_PHASE = Object.freeze({
+  CONTRACT_READY: {
+    completedSteps: ["contract"],
+    pendingSteps: ["route", ...DEFAULT_PENDING_STEPS],
+  },
+  ROUTED: {
+    completedSteps: ["contract", "route"],
+    pendingSteps: [...DEFAULT_PENDING_STEPS],
+  },
+  PLANNED: {
+    completedSteps: ["contract", "route", "planning"],
+    pendingSteps: [...DEFAULT_PENDING_STEPS.filter((step) => step !== "planning")],
+  },
+  EXECUTING: {
+    completedSteps: ["contract", "route", "planning", "implementation"],
+    pendingSteps: ["verification"],
+  },
+  VERIFYING: {
+    completedSteps: ["contract", "route", "planning", "implementation"],
+    pendingSteps: ["verification"],
+  },
+  REVIEWING: {
+    completedSteps: ["contract", "route", "planning", "implementation", "verification"],
+    pendingSteps: [],
+  },
 });
 
-async function deriveResumePhaseFromLedger(target, packageRoot, taskId) {
+function cycleEvents(events) {
+  const CYCLE_EVENT_NAMES = new Set([
+    "VERIFICATION_STARTED",
+    "VERIFICATION_RECORDED",
+    "DIAGNOSIS_RECORDED",
+    "DIAGNOSTIC_CASE_RECORDED",
+  ]);
+  const cycles = events
+    .filter((event) => CYCLE_EVENT_NAMES.has(event.event))
+    .map((event) => event.details?.verificationCycle)
+    .filter((cycle) => Number.isInteger(cycle) && cycle >= 1);
+  return cycles.at(-1);
+}
+
+/**
+ * Canonical reconstruction projection: for a resumed phase derived from a
+ * validated ledger, returns the single source of truth for completedSteps and
+ * pendingSteps. Unknown phases fall back to the ROUTED projection, matching the
+ * historical default resume checkpoint.
+ */
+export function resumeStepsForPhase(phase) {
+  return RESUME_STEPS_BY_PHASE[phase] ?? RESUME_STEPS_BY_PHASE.ROUTED;
+}
+
+/**
+ * Canonical verification cycle derived from the ledger when history proves
+ * verification has started; undefined when the ledger has no cycle metadata.
+ */
+export function resumeVerificationCycleForPhase(events) {
+  return cycleEvents(events);
+}
+
+/**
+ * Canonical work-state identity fields for reconstruction from a validated
+ * ledger: resumed phase, completedSteps, pendingSteps, and verificationCycle.
+ * This is the one projection shared by ensureResumableState and
+ * contract-create reconstruction so later phases cannot be reconstructed with
+ * contradictory steps.
+ */
+export function buildResumableWorkStateFields({ events, resumedPhase }) {
+  const steps = resumeStepsForPhase(resumedPhase);
+  return {
+    phase: resumedPhase,
+    completedSteps: [...steps.completedSteps],
+    pendingSteps: [...steps.pendingSteps],
+    ...(events && events.length > 0 && cycleEvents(events) !== undefined
+      ? { verificationCycle: cycleEvents(events) }
+      : {}),
+  };
+}
+
+export async function deriveResumePhaseFromLedger(target, packageRoot, taskId) {
   let ledger;
   try {
     ledger = await validateEventLedger(target, packageRoot, { taskId });
@@ -32,71 +117,37 @@ async function deriveResumePhaseFromLedger(target, packageRoot, taskId) {
   let derived = null;
   for (const event of scoped) {
     const phase = positions[event.event];
-    if (!phase) continue;
-    if (!derived) {
-      derived = phase;
-      continue;
-    }
-    if (phase === "VERIFYING") derived = "VERIFYING";
+    if (phase) derived = phase;
   }
   return derived;
 }
 
-function deriveVerificationCycleFromLedger(events) {
-  const cycleEvents = new Set([
-    "VERIFICATION_STARTED",
-    "VERIFICATION_RECORDED",
-    "DIAGNOSIS_RECORDED",
-    "DIAGNOSTIC_CASE_RECORDED",
-  ]);
-  const cycles = events
-    .filter((event) => cycleEvents.has(event.event))
-    .map((event) => event.details?.verificationCycle)
-    .filter((cycle) => Number.isInteger(cycle) && cycle >= 1);
-  return cycles.at(-1);
-}
-
-function resumeSteps(phase) {
-  if (phase === "EXECUTING" || phase === "VERIFYING") {
-    return {
-      completedSteps: ["contract", "route", "planning", "implementation"],
-      pendingSteps: ["verification"],
-    };
-  }
-  return {
-    completedSteps: ["contract", "route"],
-    pendingSteps: [...DEFAULT_PENDING_STEPS],
-  };
-}
-
 export async function ensureResumableState({ target, packageRoot, contract, route, taskId, statePath }) {
   if (!contract || !route) return null;
   const existing = await readWorkState(target, { packageRoot, taskId, statePath });
   if (existing) return existing;
 
   const resumedPhase = await deriveResumePhaseFromLedger(target, packageRoot, taskId) ?? "ROUTED";
-  let verificationCycle;
+  let events = [];
   try {
     const ledger = await validateEventLedger(target, packageRoot, { taskId });
     if (ledger.valid) {
-      verificationCycle = deriveVerificationCycleFromLedger(
-        (ledger.events ?? []).filter((event) => !taskId || event.taskId === taskId),
-      );
+      events = (ledger.events ?? []).filter((event) => !taskId || event.taskId === taskId);
     }
   } catch {
-    verificationCycle = undefined;
+    events = [];
   }
-  const steps = resumeSteps(resumedPhase);
+  const projection = buildResumableWorkStateFields({ events, resumedPhase });
   const state = createWorkState({
     taskId: contract.value.taskId,
     contractFingerprint: contract.fingerprint,
     routeFingerprint: route.fingerprint,
     repositoryFingerprint: await currentRepositoryFingerprint(target),
-    phase: resumedPhase,
+    phase: projection.phase,
     selectedGuides: route.value.guides,
-    completedSteps: steps.completedSteps,
-    pendingSteps: steps.pendingSteps,
-    ...(verificationCycle !== undefined ? { verificationCycle } : {}),
+    completedSteps: projection.completedSteps,
+    pendingSteps: projection.pendingSteps,
+    ...(projection.verificationCycle !== undefined ? { verificationCycle: projection.verificationCycle } : {}),
     checks: [],
     failures: [],
     blockers: [],
@@ -105,6 +156,65 @@ export async function ensureResumableState({ target, packageRoot, contract, rout
   return initializeWorkState(target, state, { packageRoot, taskId, statePath });
 }
 
+function routeSyncError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function sameStringList(left, right) {
+  const a = [...(left ?? [])].sort();
+  const b = [...(right ?? [])].sort();
+  return a.length === b.length && a.every((value, index) => value === b[index]);
+}
+
+/**
+ * Rebinds an existing ROUTED checkpoint to an already-persisted route.
+ *
+ * Only the route-bound identity fields are updated; contract, repository,
+ * steps, checks, evidence, and phase are preserved. Same-identity reruns are
+ * a no-op. Every other situation fails closed.
+ */
+export async function synchronizePersistedRouteState({ target, packageRoot, taskId, route, contract = null, statePath } = {}) {
+  if (!route || !route.value || typeof route.fingerprint !== "string") {
+    throw routeSyncError("E_ROUTE_STALE", "A persisted route artifact is required to synchronize checkpoint identity");
+  }
+  const state = await readWorkState(target, { packageRoot, taskId, statePath });
+  if (!state) return null;
+  if (state.phase !== "ROUTED") {
+    throw routeSyncError(
+      "E_ROUTE_PHASE_UNSUPPORTED",
+      `Route checkpoint synchronization supports phase ROUTED, found ${state.phase}`,
+    );
+  }
+  if (taskId && state.taskId !== taskId) {
+    throw routeSyncError("E_ROUTE_STALE", "Work state does not belong to the current route task");
+  }
+  if (contract && state.contractFingerprint !== contract.fingerprint) {
+    // Contract evolution with regenerated routing is a pre-existing flow whose
+    // stale checkpoint is recovered through the sanctioned clear-state and
+    // preflight recreation path. Never rebind route identity across a contract
+    // boundary here; leave the checkpoint untouched.
+    return state;
+  }
+  if (route.value.contractFingerprint !== undefined && state.contractFingerprint !== route.value.contractFingerprint) {
+    return state;
+  }
+  if (state.routeFingerprint === route.fingerprint && sameStringList(state.selectedGuides, route.value.guides)) {
+    return state;
+  }
+  return mutateWorkState(target, {
+    expectedRevision: state.revision ?? 0,
+    packageRoot,
+    taskId,
+    statePath,
+  }, () => ({
+    ...state,
+    routeFingerprint: route.fingerprint,
+    selectedGuides: [...route.value.guides],
+  }));
+}
+
 export async function synchronizePreflightState({
   target,
   packageRoot,

package/src/core/route-artifact.js

@@ -1,17 +1,27 @@
 import { assertRouteInvariants } from "./router.js";
 import { ARTIFACT_PATHS, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
 import { readContract } from "./contract.js";
-import { ensureResumableState } from "./resumability.js";
+import { ensureResumableState, synchronizePersistedRouteState } from "./resumability.js";
+import { readWorkState } from "./work-state.js";
 import { taskArtifactPath } from "./task-paths.js";
+import { getTaskTransaction, withTaskTransaction } from "./transaction.js";
+
+
 
 export async function persistRoute(target, route, packageRoot, options = {}) {
+  if (!options.taskId) return persistRouteInTransaction(target, route, packageRoot, options);
+  return withTaskTransaction({ target, taskId: options.taskId, packageRoot, operation: "route" }, () => persistRouteInTransaction(target, route, packageRoot, options));
+}
+
+async function persistRouteInTransaction(target, route, packageRoot, options) {
   assertRouteInvariants(route);
-  const { contractFingerprint, ...writeOptions } = options;
+  const { contractFingerprint: suppliedFingerprint, ...writeOptions } = options;
+  let contractFingerprint = suppliedFingerprint;
   let contractArtifact = null;
-  if (contractFingerprint === undefined) {
+  if (contractFingerprint === undefined || !options.taskId) {
     try {
       contractArtifact = await readContract(target, packageRoot, options);
-      contractFingerprint = contractArtifact.fingerprint;
+      if (contractFingerprint === undefined) contractFingerprint = contractArtifact.fingerprint;
     } catch (error) {
       if (error.code !== "ARTIFACT_MISSING") throw error;
     }
@@ -21,6 +31,17 @@ export async function persistRoute(target, route, packageRoot, options = {}) {
     : { ...route, contractFingerprint };
   assertRouteInvariants(value);
   const taskId = options.taskId ?? contractArtifact?.value?.taskId ?? null;
+  if (taskId && !(await getTaskTransaction(target))) {
+    return withTaskTransaction({ target, taskId, packageRoot, operation: "route" }, () => persistRouteInTransaction(target, route, packageRoot, { ...options, taskId }));
+  }
+  let existingState = null;
+  if (taskId) {
+    try {
+      existingState = await readWorkState(target, { packageRoot, taskId });
+    } catch {
+      existingState = null;
+    }
+  }
   const relPath = options.routePath ?? options.routeFile ?? options.relativePath ?? (taskId ? taskArtifactPath(taskId, "route") : ARTIFACT_PATHS.route);
   const artifact = await writeJsonArtifact(
     target,
@@ -33,6 +54,9 @@ export async function persistRoute(target, route, packageRoot, options = {}) {
   if (contractArtifact && contractArtifact.fingerprint === artifact.value.contractFingerprint) {
     await ensureResumableState({ target, packageRoot, contract: contractArtifact, route: artifact, taskId });
   }
+  if (existingState?.phase === "ROUTED") {
+    await synchronizePersistedRouteState({ target, packageRoot, taskId, route: artifact, contract: contractArtifact });
+  }
   return artifact;
 }
 

package/src/core/router.js

@@ -313,6 +313,64 @@ function reasonForSignal(prefix, signal) {
   return `${prefix}_${signal.toUpperCase().replaceAll("-", "_")}`;
 }
 
+const SECURITY_TRUST_BOUNDARY_RISKS = Object.freeze([
+  "untrusted-input", "personal-data", "secrets", "external-service", "publication",
+]);
+
+// Canonical deterministic safety floor. These are the route reason codes the
+// router assigns when a trust-boundary signal selects the security guide. The
+// semantic exclusion policy reads protection from this same source, so a
+// mandatory safety guide can never drift out of protection (for example the
+// previously missing external-service boundary).
+const MANDATORY_SAFETY_REASONS = Object.freeze(new Set([
+  "SURFACE_AUTH",
+  ...SECURITY_TRUST_BOUNDARY_RISKS.map((risk) => reasonForSignal("RISK", risk)),
+]));
+
+export function isMandatorySafetyReason(reason) {
+  return MANDATORY_SAFETY_REASONS.has(reason);
+}
+
+export function isMandatorySafetyGuide(guide, reasons) {
+  return guide === "security"
+    && Array.isArray(reasons)
+    && reasons.some((reason) => isMandatorySafetyReason(reason));
+}
+
+function applySemanticGuideRecommendation(selected, excluded, recommendation) {
+  const guideDecision = recommendation?.guideRelevance
+    ?? (recommendation?.rankedIds || recommendation?.excludedIds ? recommendation : null);
+  if (!guideDecision) return;
+  const excludedIds = new Set(Array.isArray(guideDecision.excludedIds) ? guideDecision.excludedIds : []);
+  const confidenceById = guideDecision.confidenceById ?? {};
+  for (const guide of [...selected.keys()]) {
+    const reasons = selected.get(guide);
+    if (isMandatorySafetyGuide(guide, reasons)) {
+      if (!reasons.includes("MANDATORY_SAFETY_GUIDE")) reasons.push("MANDATORY_SAFETY_GUIDE");
+      continue;
+    }
+    if (!excludedIds.has(guide)) {
+      if (!reasons.includes("JEV_RELEVANT")) reasons.push("JEV_RELEVANT");
+      continue;
+    }
+    if ((confidenceById[guide] ?? 0) < 0.75) {
+      if (!reasons.includes("JEV_LOW_CONFIDENCE_RETAINED")) reasons.push("JEV_LOW_CONFIDENCE_RETAINED");
+      continue;
+    }
+    selected.delete(guide);
+    excluded[guide] = ["JEV_EXCLUDED"];
+  }
+  const ranked = Array.isArray(guideDecision.rankedIds) ? guideDecision.rankedIds : [];
+  const order = new Map(ranked.map((guide, index) => [guide, index]));
+  const entries = [...selected.entries()].sort((left, right) => {
+    const leftRank = order.has(left[0]) ? order.get(left[0]) : ranked.length + [...selected.keys()].indexOf(left[0]);
+    const rightRank = order.has(right[0]) ? order.get(right[0]) : ranked.length + [...selected.keys()].indexOf(right[0]);
+    return leftRank - rightRank;
+  });
+  selected.clear();
+  for (const [guide, reasons] of entries) selected.set(guide, reasons);
+}
+
 function normalizeArray(value, name, allowed) {
   if (value === undefined) return [];
   if (!Array.isArray(value)) throw new RouteInputError(`${name} must be an array`);
@@ -440,7 +498,7 @@ export function evaluateRoute(input = {}, profileOptions = {}) {
   }
 
   for (const risk of normalized.risks) {
-    if (["untrusted-input", "personal-data", "secrets", "external-service", "publication"].includes(risk)) {
+    if (SECURITY_TRUST_BOUNDARY_RISKS.includes(risk)) {
       add("security", reasonForSignal("RISK", risk));
     }
     if (["critical-path", "performance"].includes(risk)) {
@@ -481,12 +539,19 @@ export function evaluateRoute(input = {}, profileOptions = {}) {
     excluded[guide] = [exclusionReasonForGuide(guide, projectEvidence, normalized.workType)];
   }
 
+  applySemanticGuideRecommendation(
+    selected,
+    excluded,
+    profileOptions.semanticRecommendation ?? null,
+  );
+
   const guides = [...selected.keys()];
   const result = {
     schemaVersion: ROUTING_SCHEMA_VERSION,
     protocolVersion: PROTOCOL_VERSION,
     input: normalized,
     primary: Object.prototype.hasOwnProperty.call(PRIMARY_GUIDES, normalized.workType)
+      && guides.includes(PRIMARY_GUIDES[normalized.workType])
       ? PRIMARY_GUIDES[normalized.workType]
       : guides[0] ?? null,
     guides,
@@ -499,6 +564,7 @@ export function evaluateRoute(input = {}, profileOptions = {}) {
       configuredProfile: profileOptions.configuredProfile ?? input.configuredProfile ?? "auto",
       requestedProfile: profileOptions.requestedProfile
         ?? (Object.prototype.hasOwnProperty.call(input, "executionProfile") ? input.executionProfile : null),
+      semanticRecommendation: profileOptions.semanticRecommendation ?? null,
     }),
   };
   return assertRouteInvariants(result);