@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

package/src/core/preflight-consistency.js

@@ -1,7 +1,7 @@
 import { ARTIFACT_PATHS } from "./artifacts.js";
 import { readContract } from "./contract.js";
 import { readPersistedRoute } from "./route-artifact.js";
-import { appendProtocolEvent, validateEventLedger } from "./events.js";
+import { appendProtocolEvent, validateEventLedger, withEventLedgerAudit } from "./events.js";
 import { readWorkState } from "./work-state.js";
 import { assertStateIdentity } from "./completion-relationships.js";
 import { ensureResumableState, synchronizePreflightState } from "./resumability.js";
@@ -14,6 +14,7 @@ import {
   validatePersistedPreflight,
 } from "./preflight-model.js";
 
+import { ledgerEventsOfTypes, ledgerTypeSummary } from "./ledger-event-collection.js";
 import { taskArtifactPath } from "./task-paths.js";
 
 async function readOptionalIdentityArtifact(readArtifact, invalidCode, artifactPath) {
@@ -80,6 +81,18 @@ function sameReadyPreflightEvent(event, result) {
     && sameStringSet(event.details?.satisfiedGates, result.satisfiedGates);
 }
 
+function latestContractRevisionSeq(events) {
+  return ledgerTypeSummary(events, "CONTRACT_REVISED").latest?.seq ?? 0;
+}
+
+function hasCurrentRevisionGate(events, taskId, gate) {
+  const revisionSeq = latestContractRevisionSeq(events);
+  for (const event of ledgerEventsOfTypes(events, ["GATE_SATISFIED"])) {
+    if (event.taskId === taskId && event.details?.gate === gate && event.seq > revisionSeq) return true;
+  }
+  return false;
+}
+
 export async function validateReadyProtocolConsistency({
   target,
   packageRoot,
@@ -90,70 +103,80 @@ export async function validateReadyProtocolConsistency({
 } = {}) {
   if (persisted?.status !== "READY") return [];
   const result = current ?? await evaluateCurrentPreflight({ target, packageRoot, taskId });
-  const errors = [...validatePersistedPreflight(persisted, result)];
+  return withEventLedgerAudit(target, packageRoot, { taskId }, async ledger => {
+    const errors = [...validatePersistedPreflight(persisted, result)];
 
-  const stateRel = taskId ? taskArtifactPath(taskId, "state") : ARTIFACT_PATHS.state;
-  const eventsRel = taskId ? taskArtifactPath(taskId, "events") : ARTIFACT_PATHS.events;
-  const preflightRel = taskId ? taskArtifactPath(taskId, "preflight") : ARTIFACT_PATHS.preflight;
-  const contractRel = taskId ? taskArtifactPath(taskId, "contract") : ARTIFACT_PATHS.contract;
-  const routeRel = taskId ? taskArtifactPath(taskId, "route") : ARTIFACT_PATHS.route;
-  const gatesRel = taskId ? taskArtifactPath(taskId, "gates") : ARTIFACT_PATHS.gates;
+    const stateRel = taskId ? taskArtifactPath(taskId, "state") : ARTIFACT_PATHS.state;
+    const eventsRel = taskId ? taskArtifactPath(taskId, "events") : ARTIFACT_PATHS.events;
+    const preflightRel = taskId ? taskArtifactPath(taskId, "preflight") : ARTIFACT_PATHS.preflight;
+    const contractRel = taskId ? taskArtifactPath(taskId, "contract") : ARTIFACT_PATHS.contract;
+    const routeRel = taskId ? taskArtifactPath(taskId, "route") : ARTIFACT_PATHS.route;
+    const gatesRel = taskId ? taskArtifactPath(taskId, "gates") : ARTIFACT_PATHS.gates;
 
-  let state = null;
-  try {
-    state = await readWorkState(target, { packageRoot, taskId });
-  } catch (error) {
-    errors.push(issue("E_STATE_INVALID", error.message, [stateRel]));
-  }
-  if (!state) {
-    errors.push(issue(
-      "E_STATE_MISSING_AFTER_PREFLIGHT_READY",
-      "A persisted READY preflight must have a resumable work-state checkpoint",
-      [preflightRel, stateRel],
-    ));
-  } else {
-    if (state.taskId !== persisted.taskId) {
-      errors.push(issue("E_STATE_TASK_MISMATCH", "The resumable checkpoint does not belong to the READY preflight task", [stateRel, preflightRel]));
+    let state = null;
+    try {
+      state = await readWorkState(target, { packageRoot, taskId });
+    } catch (error) {
+      errors.push(issue("E_STATE_INVALID", error.message, [stateRel]));
     }
-    if (state.contractFingerprint !== result.fingerprints.contract) {
-      errors.push(issue("E_CONTRACT_STALE", "The resumable checkpoint does not match the READY contract fingerprint", [stateRel, contractRel]));
+    if (!state) {
+      errors.push(issue(
+        "E_STATE_MISSING_AFTER_PREFLIGHT_READY",
+        "A persisted READY preflight must have a resumable work-state checkpoint",
+        [preflightRel, stateRel],
+      ));
+    } else {
+      if (state.taskId !== persisted.taskId) {
+        errors.push(issue("E_STATE_TASK_MISMATCH", "The resumable checkpoint does not belong to the READY preflight task", [stateRel, preflightRel]));
+      }
+      if (state.contractFingerprint !== result.fingerprints.contract) {
+        errors.push(issue("E_CONTRACT_STALE", "The resumable checkpoint does not match the READY contract fingerprint", [stateRel, contractRel]));
+      }
+      if (state.routeFingerprint !== result.fingerprints.routing) {
+        errors.push(issue("E_ROUTE_STALE", "The resumable checkpoint does not match the READY routing fingerprint", [stateRel, routeRel]));
+      }
+      if (JSON.stringify(state.selectedGuides) !== JSON.stringify(result.routing.guides)) {
+        errors.push(issue("E_ROUTE_GUIDE_MISMATCH", "The resumable checkpoint guides do not match the READY routing result", [stateRel, routeRel]));
+      }
+      if (!sameStringSet(state.requiredGates ?? [], persisted.requiredGates)
+        || !sameStringSet(state.satisfiedGates ?? [], persisted.satisfiedGates)) {
+        errors.push(issue("E_PREFLIGHT_GATES_STALE", "The resumable checkpoint gate sets do not match the READY preflight", [stateRel, preflightRel, gatesRel]));
+      }
     }
-    if (state.routeFingerprint !== result.fingerprints.routing) {
-      errors.push(issue("E_ROUTE_STALE", "The resumable checkpoint does not match the READY routing fingerprint", [stateRel, routeRel]));
+
+    if (!ledger.valid) {
+      errors.push(...ledger.errors.map((error) => issue(error.code ?? "E_EVENT_INVALID", error.message, [eventsRel])));
     }
-    if (JSON.stringify(state.selectedGuides) !== JSON.stringify(result.routing.guides)) {
-      errors.push(issue("E_ROUTE_GUIDE_MISMATCH", "The resumable checkpoint guides do not match the READY routing result", [stateRel, routeRel]));
+    const events = ledger.events ?? [];
+    const requiredEvents = ["CONTRACT_VALIDATED", "ROUTE_VALIDATED"];
+    const observedEvents = new Set();
+    for (const event of ledgerEventsOfTypes(events, requiredEvents)) {
+      if (event.taskId === persisted.taskId) observedEvents.add(event.event);
     }
-    if (!sameStringSet(state.requiredGates ?? [], persisted.requiredGates)
-      || !sameStringSet(state.satisfiedGates ?? [], persisted.satisfiedGates)) {
-      errors.push(issue("E_PREFLIGHT_GATES_STALE", "The resumable checkpoint gate sets do not match the READY preflight", [stateRel, preflightRel, gatesRel]));
+    for (const requiredEvent of requiredEvents) {
+      if (!observedEvents.has(requiredEvent)) {
+        errors.push(issue("E_PREFLIGHT_EVENT_MISSING", `READY preflight is missing lifecycle event: ${requiredEvent}`, [eventsRel, preflightRel]));
+      }
     }
-  }
-
-  const ledger = await validateEventLedger(target, packageRoot, { taskId });
-  if (!ledger.valid) {
-    errors.push(...ledger.errors.map((error) => issue(error.code ?? "E_EVENT_INVALID", error.message, [eventsRel])));
-  }
-  const events = ledger.events ?? [];
-  for (const requiredEvent of ["CONTRACT_VALIDATED", "ROUTE_VALIDATED"]) {
-    if (!events.some((event) => event.event === requiredEvent && event.taskId === persisted.taskId)) {
-      errors.push(issue("E_PREFLIGHT_EVENT_MISSING", `READY preflight is missing lifecycle event: ${requiredEvent}`, [eventsRel, preflightRel]));
+    for (const gate of persisted.satisfiedGates ?? []) {
+      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`]));
+      }
     }
-  }
-  for (const gate of persisted.satisfiedGates ?? []) {
-    if (!events.some((event) => event.event === "GATE_SATISFIED"
-      && event.taskId === persisted.taskId
-      && event.details?.gate === gate)) {
-      errors.push(issue("E_PREFLIGHT_GATE_EVENT_MISSING", `READY preflight is missing lifecycle gate event: ${gate}`, [eventsRel, `${gatesRel}/${gate}.json`]));
+    let readyCount = 0;
+    let readyMatches = false;
+    for (const event of ledgerEventsOfTypes(events, ["PREFLIGHT_READY"])) {
+      if (event.taskId !== persisted.taskId) continue;
+      readyCount++;
+      if (sameReadyPreflightEvent(event, result)) readyMatches = true;
     }
-  }
-  const readyEvents = events.filter((event) => event.event === "PREFLIGHT_READY" && event.taskId === persisted.taskId);
-  if (readyEvents.length === 0) {
-    errors.push(issue("E_PREFLIGHT_READY_EVENT_MISSING", "Persisted READY preflight is missing the matching PREFLIGHT_READY lifecycle event", [preflightRel, eventsRel]));
-  } else if (!readyEvents.some((event) => sameReadyPreflightEvent(event, result))) {
-    errors.push(issue("E_PREFLIGHT_READY_EVENT_MISMATCH", "PREFLIGHT_READY lifecycle details do not match the persisted READY preflight", [preflightRel, eventsRel]));
-  }
-  return sortIssues(errors);
+    if (readyCount === 0) {
+      errors.push(issue("E_PREFLIGHT_READY_EVENT_MISSING", "Persisted READY preflight is missing the matching PREFLIGHT_READY lifecycle event", [preflightRel, eventsRel]));
+    } else if (!readyMatches) {
+      errors.push(issue("E_PREFLIGHT_READY_EVENT_MISMATCH", "PREFLIGHT_READY lifecycle details do not match the persisted READY preflight", [preflightRel, eventsRel]));
+    }
+    return sortIssues(errors);
+  });
 }
 
 function sameBlockedPreflightEvent(event, result) {
@@ -189,9 +212,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 +243,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 +251,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);
@@ -39,7 +41,7 @@ export async function optionalConfig(target, packageRoot, errors) {
 
 export async function loadContract(target, packageRoot, errors, options = {}) {
   try {
-    return await readContract(target, packageRoot, options);
+    return await (options.readers?.readContract ?? readContract)(target, packageRoot, options);
   } catch (error) {
     const path = options.contractPath ?? (options.taskId ? taskArtifactPath(options.taskId, "contract") : ARTIFACT_PATHS.contract);
     errors.push(issue(error.code === "ARTIFACT_MISSING" ? "E_CONTRACT_MISSING" : "E_CONTRACT_INVALID", error.message, [path]));
@@ -49,7 +51,7 @@ export async function loadContract(target, packageRoot, errors, options = {}) {
 
 export async function loadRoute(target, packageRoot, errors, options = {}) {
   try {
-    return await readPersistedRoute(target, packageRoot, options);
+    return await (options.readers?.readRoute ?? readPersistedRoute)(target, packageRoot, options);
   } catch (error) {
     const path = options.routePath ?? (options.taskId ? taskArtifactPath(options.taskId, "route") : ARTIFACT_PATHS.route);
     const code = error.code === "ARTIFACT_MISSING"
@@ -62,21 +64,43 @@ 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]));
   }
   return registry;
 }
 
+async function readGateEvents(target, packageRoot, taskId, options) {
+  let events = [];
+  if (taskId) {
+    try {
+      events = await (options.readers?.readEvents ?? readEvents)(target, packageRoot, { taskId });
+    } catch {
+      events = [];
+    }
+  }
+  return events;
+}
+
 export async function inspectGates(target, contract, route, packageRoot, errors, config = {}, options = {}) {
   if (!route) return { required: [], satisfied: [], records: {} };
   const guideGates = await requiredGatesForGuides(route.value.guides, packageRoot);
@@ -84,13 +108,17 @@ export async function inspectGates(target, contract, route, packageRoot, errors,
   const satisfied = [];
   const records = {};
   const taskId = options.taskId ?? null;
+  const events = await readGateEvents(target, packageRoot, taskId, options);
+  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`;
     try {
-      artifact = await readGateIfPresent(target, gate, packageRoot, { ...options, taskId });
+      artifact = await (options.readers?.readGate ?? readGateIfPresent)(target, gate, packageRoot, { ...options, taskId });
     } catch (error) {
-      errors.push(issue(error.code === "ARTIFACT_MISSING" ? "E_GATE_UNVERIFIED" : "E_GATE_INVALID", error.message, [defaultGateRel], { gate }));
+      const code = error.code === "E_STORAGE_PAYLOAD_MISMATCH" && error.taskIdentityMismatch ? "E_GATE_TASK_MISMATCH"
+        : error.code === "ARTIFACT_MISSING" ? "E_GATE_UNVERIFIED" : "E_GATE_INVALID";
+      errors.push(issue(code, error.message, [defaultGateRel], { gate }));
       continue;
     }
     if (!artifact) {
@@ -111,6 +139,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 };

package/src/core/preflight-model.js

@@ -31,7 +31,12 @@ export function sameStringSet(left, right) {
     && [...leftSet].every((value) => rightSet.has(value));
 }
 
-export function validatePersistedPreflight(persisted, current) {
+export function validatePersistedPreflight(persisted, current, readError = null) {
+  if (readError?.taskIdentityMismatch) return [issue("E_PREFLIGHT_TASK_MISMATCH", "Persisted preflight does not belong to the current task", [ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.contract])];
+  return validatePersistedPreflightPayload(persisted, current);
+}
+
+function validatePersistedPreflightPayload(persisted, current) {
   const errors = [];
   if (persisted?.status !== "READY") {
     if (Array.isArray(persisted?.errors) && persisted.errors.length > 0) {

package/src/core/preflight.js

@@ -1,4 +1,5 @@
 import { ARTIFACT_PATHS, writeJsonArtifact } from "./artifacts.js";
+import { withTaskTransaction } from "./transaction.js";
 import { readContract } from "./contract.js";
 import { assertRouteInvariants } from "./router.js";
 import { validateProfileSources } from "./profile.js";
@@ -35,13 +36,17 @@ const PREVIEW_DECISION_MAX_LENGTH = 240;
 
 export { validatePersistedPreflight } from "./preflight-model.js";
 
-export async function evaluatePreflight({ target, packageRoot, strict = false, taskId = null, contractPath = null, routePath = null, statePath = null } = {}) {
+function preflightArtifactPath(explicitPath, taskId, kind) {
+  return explicitPath ?? (taskId ? taskArtifactPath(taskId, kind) : ARTIFACT_PATHS[kind]);
+}
+
+export async function evaluatePreflight({ target, packageRoot, strict = false, taskId = null, contractPath = null, routePath = null, statePath = null, readers = null } = {}) {
   const errors = [];
   const profile = await readProfile(target);
   const profileProvenance = await validateProfileSources(target, packageRoot);
   errors.push(...(profileProvenance.errors ?? []));
-  const contract = await loadContract(target, packageRoot, errors, { taskId, contractPath });
-  const route = await loadRoute(target, packageRoot, errors, { taskId, routePath });
+  const contract = await loadContract(target, packageRoot, errors, { taskId, contractPath, readers });
+  const route = await loadRoute(target, packageRoot, errors, { taskId, routePath, readers });
   const config = await optionalConfig(target, packageRoot, errors);
   if (config.structuralQuality !== undefined) {
     try {
@@ -59,9 +64,9 @@ export async function evaluatePreflight({ target, packageRoot, strict = false, t
     errors.push(issue("E_PROFILE_UNVERIFIED", "Strict preflight requires a verified project profile", [PROFILE_PATH]));
   }
 
-  const contractRelPath = contractPath ?? (taskId ? taskArtifactPath(taskId, "contract") : ARTIFACT_PATHS.contract);
-  const routeRelPath = routePath ?? (taskId ? taskArtifactPath(taskId, "route") : ARTIFACT_PATHS.route);
-  const stateRelPath = statePath ?? (taskId ? taskArtifactPath(taskId, "state") : ARTIFACT_PATHS.state);
+  const contractRelPath = preflightArtifactPath(contractPath, taskId, "contract");
+  const routeRelPath = preflightArtifactPath(routePath, taskId, "route");
+  const stateRelPath = preflightArtifactPath(statePath, taskId, "state");
 
   const unresolvedDecisions = contract?.value?.unresolvedDecisions ?? [];
   if (unresolvedDecisions.length > 0) {
@@ -88,11 +93,11 @@ export async function evaluatePreflight({ target, packageRoot, strict = false, t
   }
 
   const sources = await loadSources(target, contract, packageRoot, errors);
-  const gates = await inspectGates(target, contract, route, packageRoot, errors, config, { taskId });
+  const gates = await inspectGates(target, contract, route, packageRoot, errors, config, { taskId, readers });
 
   let state = null;
   try {
-    state = await readWorkState(target, { packageRoot, taskId, statePath });
+    state = await (readers?.readState ?? readWorkState)(target, { packageRoot, taskId, statePath });
   } catch (error) {
     errors.push(issue("E_STATE_INVALID", error.message, [stateRelPath]));
   }
@@ -135,7 +140,7 @@ export async function evaluatePreflight({ target, packageRoot, strict = false, t
     reasonCodes: [],
     next: config.structuralQuality?.mode === "gate" ? "CAPTURE_STRUCTURAL_QUALITY_BASELINE" : null,
   };
-  if (effectiveTaskId !== "unknown") {
+  if (effectiveTaskId !== "unknown" && (!readers || structuralQuality.mode !== "off")) {
     try {
       const { projectStructuralQualityStatus } = await import("./structural-quality/service.js");
       structuralQuality = await projectStructuralQualityStatus({ target, packageRoot, taskId: effectiveTaskId });
@@ -183,7 +188,19 @@ export async function validateReadyProtocolConsistency(options = {}) {
   });
 }
 
-export async function runPreflight({
+export async function runPreflight(options = {}) {
+  if (options.persist === false) return runPreflightInTransaction(options);
+  let taskId = options.taskId;
+  if (!taskId) {
+    const { target, packageRoot, strict, contractPath, routePath, statePath } = options;
+    const result = await evaluatePreflight({ target, packageRoot, strict, contractPath, routePath, statePath });
+    if (result.taskId !== "unknown") taskId = result.taskId;
+  }
+  if (!taskId) return runPreflightInTransaction(options);
+  return withTaskTransaction({ target: options.target, taskId, packageRoot: options.packageRoot, operation: "preflight" }, () => runPreflightInTransaction({ ...options, taskId }));
+}
+
+async function runPreflightInTransaction({
   target,
   packageRoot,
   strict = false,
@@ -198,7 +215,7 @@ export async function runPreflight({
   let result = await evaluatePreflight({ target, packageRoot, strict, taskId, contractPath, routePath, statePath });
   if (!persist) return result;
 
-  let ledger = await assertPreflightPersistenceSafety(target, packageRoot, { taskId, eventsPath });
+  let ledger = await assertPreflightPersistenceSafety(target, packageRoot, { taskId, contractPath, routePath, statePath, eventsPath });
   assertPreflightResultPersistenceSafety(result);
   assertExistingReadyLifecycleCompatibility(ledger, result);
 
@@ -224,7 +241,7 @@ export async function runPreflight({
       result = await evaluatePreflight({ target, packageRoot, strict, taskId, contractPath, routePath, statePath });
       assertPreflightResultPersistenceSafety(result);
       assertExistingReadyLifecycleCompatibility(ledger, result);
-      ledger = await assertPreflightPersistenceSafety(target, packageRoot, { taskId, eventsPath });
+      ledger = await assertPreflightPersistenceSafety(target, packageRoot, { taskId, contractPath, routePath, statePath, eventsPath });
     }
   }
 

package/src/core/progress.js

@@ -1,8 +1,8 @@
-import { diagnosisEventsForTask } from "./diagnosis-model.js";
+import { isLedgerEventCollection, ledgerEventsOfTypes } from "./ledger-event-collection.js";
+import { latestDiagnosisForTask } from "./diagnosis-model.js";
 import { resolveCurrentCycleDiagnostic } from "./diagnostic-projection.js";
 import {
-  buildInformationGainProjection,
-  evaluateStructuredDiagnosticStall,
+  summarizeInformationGain,
 } from "./information-gain-projection.js";
 
 export const PROGRESS_STATUS = Object.freeze({
@@ -27,6 +27,17 @@ export function diagnosisRequirements(diagnosis, checksById) {
   )].sort();
 }
 
+function progressTaskEvents(events, taskId) {
+  if (Array.isArray(events)) return events.filter(event => !taskId || event.taskId === taskId);
+  return isLedgerEventCollection(events) ? events : [];
+}
+
+function* progressVerificationEvents(events, taskId) {
+  for (const event of ledgerEventsOfTypes(events, ["VERIFICATION_RECORDED"])) {
+    if (!taskId || event.taskId === taskId) yield event;
+  }
+}
+
 export function evaluateProgress({ state, events = [] } = {}) {
   const signals = [];
   let status = PROGRESS_STATUS.ADVANCING;
@@ -35,10 +46,10 @@ export function evaluateProgress({ state, events = [] } = {}) {
     return { status, signals };
   }
 
-  const taskEvents = Array.isArray(events) ? events.filter((e) => !state.taskId || e.taskId === state.taskId) : [];
-  const diagEvents = diagnosisEventsForTask(taskEvents, state.taskId);
+  const taskEvents = progressTaskEvents(events, state.taskId);
+  const latestLegacy = latestDiagnosisForTask(taskEvents, state.taskId);
   const resolvedDiagnostic = resolveCurrentCycleDiagnostic(taskEvents, state.taskId, state.verificationCycle ?? null);
-  const latestDiag = resolvedDiagnostic?.details ?? diagEvents.at(-1)?.details ?? null;
+  const latestDiag = resolvedDiagnostic?.details ?? latestLegacy?.details ?? null;
 
   let latestGainClassification = latestDiag?.informationGain ?? null;
   let structuredStall = null;
@@ -49,8 +60,8 @@ export function evaluateProgress({ state, events = [] } = {}) {
       )];
     }
     // Canonical structured-stall truth; compatibility classification is presentation only.
-    structuredStall = evaluateStructuredDiagnosticStall(
-      buildInformationGainProjection(taskEvents, state.taskId),
+    structuredStall = summarizeInformationGain(
+      taskEvents, state.taskId,
       { verificationCycle: state.verificationCycle ?? null },
     );
     latestDiag.effectiveInformationGain = !(structuredStall.stalled);
@@ -63,7 +74,7 @@ export function evaluateProgress({ state, events = [] } = {}) {
     if (check.id) checksById.set(check.id, check);
     if (check.checkId) checksById.set(check.checkId, check);
   }
-  for (const event of taskEvents) {
+  for (const event of progressVerificationEvents(taskEvents, state.taskId)) {
     if (event.event === "VERIFICATION_RECORDED" && event.details) {
       if (event.details.id) checksById.set(event.details.id, event.details);
       if (event.details.checkId) checksById.set(event.details.checkId, event.details);
@@ -108,7 +119,7 @@ export function evaluateProgress({ state, events = [] } = {}) {
   }
 
   // Also extract from VERIFICATION_RECORDED events
-  for (const event of taskEvents) {
+  for (const event of progressVerificationEvents(taskEvents, state.taskId)) {
     if (event.event === "VERIFICATION_RECORDED") {
       const details = event.details ?? {};
       if (details.status === "failed" || details.status === "blocked") {

package/src/core/protocol-info.js

@@ -4,6 +4,10 @@ import { PUBLIC_ERROR_REGISTRY } from "./error-codes.js";
 import { GUIDE_REGISTRY } from "./guide-registry.js";
 import { PROTOCOL_VERSION, WORK_PHASES, WORK_TRANSITIONS } from "./protocol.js";
 import { VERIFICATION_ISOLATION_MODES } from "./verification-execution.js";
+import { PROVIDER_KINDS } from "../providers/capabilities.js";
+import { DECISION_DEFAULT_POLICY, DECISION_ENGINE_ID, PINNED_JEV_MODEL } from "./decision/constants.js";
+
+import { getStorageCapabilities } from "../storage/capabilities.js";
 
 export const SCHEMA_COMPATIBILITY_POLICY = Object.freeze({
   protocolVersion: PROTOCOL_VERSION,
@@ -36,6 +40,43 @@ export function protocolInfo({ packageVersion = null } = {}) {
     writesSchemaVersions: schemaVersions,
     compatibility: SCHEMA_COMPATIBILITY_POLICY,
     features: {
+      operationalStorage: getStorageCapabilities(),
+      semanticDecisionPlane: {
+        version: 1,
+        supported: true,
+        requiredForNewSemanticDecisions: true,
+        engine: DECISION_ENGINE_ID,
+        model: PINNED_JEV_MODEL,
+        policyVersion: DECISION_DEFAULT_POLICY.policyVersion,
+        authority: "SEMANTIC_DECISION",
+        evidenceAuthority: "NONE",
+        lifecycleAuthority: false,
+        completionAuthority: false,
+        ownershipAuthority: false,
+        installationAuthority: false,
+        commands: ["decision-status", "decision-show", "context-plan", "model-route", "semantic-plan", "test-inventory", "test-utility", "test-prune-plan", "test-prune-probe"],
+        resource: "task/decisions",
+        contextPlanResource: "task/context-plan",
+        modelRouteResource: "task/model-route",
+        testUtilityResource: "task/test-utility",
+        testPruneResource: "task/test-utility",
+        offlineInspection: true,
+        completePerformsLiveRequest: false,
+        modelRouting: {
+          version: 1,
+          tiers: ["NONE", "FAST", "STANDARD", "PRIMARY"],
+          deterministicFloor: true,
+          advisoryEscalationOnly: true,
+          vendorSelection: false,
+        },
+        semanticPlanning: {
+          version: 1,
+          questionSets: ["intake-v1", "contract-v1", "route-v1", "context-v1", "model-route-v1", "failure-v1", "diagnosis-v1", "review-v1", "task-overlap-v1", "test-utility-v1", "test-prune-v1"],
+          authority: "SEMANTIC_DECISION",
+          evidenceAuthority: "NONE",
+          lifecycleAuthority: false,
+        },
+      },
       taskClaimRecovery: {
         version: 1,
         durableRecoveryState: true,
@@ -153,6 +194,18 @@ export function protocolInfo({ packageVersion = null } = {}) {
         commands: ["next", "task-show"],
         preservesDefaultOutput: true,
       },
+      auditUx: {
+        version: 1,
+        supported: true,
+        readOnly: true,
+        resource: "task/audit-view",
+        timeline: true,
+        lifecycleAuthority: false,
+        evidenceAuthority: false,
+        completionAuthority: false,
+        mutationAuthority: false,
+        externalExecution: false,
+      },
       usageTelemetry: {
         version: 1,
         supported: true,
@@ -205,6 +258,21 @@ export function protocolInfo({ packageVersion = null } = {}) {
         evidenceAuthority: false,
         executable: false,
       },
+      providerExtensions: {
+        version: 1,
+        supported: true,
+        providerNeutral: true,
+        maturity: "experimental",
+        publicRegistryApi: false,
+        packageSubpathExported: false,
+        autoInstall: false,
+        lifecycleAuthority: false,
+        completionAuthority: false,
+        evidenceAuthority: false,
+        providerKinds: [...PROVIDER_KINDS],
+        resultBoundary: "STRICT_JSON_SNAPSHOT",
+        cancellation: "COOPERATIVE_ABORT_SIGNAL",
+      },
       responsibilityConstraints: {
         version: 1,
         supported: true,