@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

package/src/core/handoff.js

@@ -1,5 +1,7 @@
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
 import { randomUUID } from "node:crypto";
 import { readdir } from "node:fs/promises";
+import { listOperationalArtifactNames, operationalArtifactExists } from "../storage/operational-context.js";
 
 import { canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
 import { assertPortableContextSafe, normalizePortableText } from "./portable-context.js";
@@ -165,14 +167,19 @@ export async function validateCanonicalHandoff(target, handoff, {
   return validateHandoffDigest(handoff);
 }
 
-export async function writeCanonicalHandoff(target, handoff, {
+export async function writeCanonicalHandoff(target, handoff, options = {}) {
+  return withTaskTransaction({ target, taskId: options.taskId ?? handoff?.taskId, packageRoot: options.packageRoot, operation: "handoff-create" }, () => writeCanonicalHandoffInTransaction(target, handoff, options));
+}
+
+async function writeCanonicalHandoffInTransaction(target, handoff, {
   packageRoot = getPackageRoot(),
   taskId = handoff?.taskId,
 } = {}) {
   await validateCanonicalHandoff(target, handoff, { taskId, packageRoot });
   const relativePath = taskHandoffPath(taskId, handoff.handoffId);
-  await assertSafePath(target, relativePath);
-  if (await fileExists(ensureWithin(target, relativePath))) {
+  const operationalExists = operationalArtifactExists(target, relativePath);
+  if (operationalExists === null) await assertSafePath(target, relativePath);
+  if (operationalExists ?? await fileExists(ensureWithin(target, relativePath))) {
     throw handoffError("E_HANDOFF_INVALID", "An existing handoff cannot be overwritten", [relativePath]);
   }
   const artifact = await writeJsonArtifact(target, relativePath, handoff, "handoff-envelope", packageRoot, { taskId, operation: "handoff-create" });
@@ -219,17 +226,22 @@ export async function readCanonicalHandoff(target, {
 }
 
 export async function listCanonicalHandoffs(target, { taskId, packageRoot = getPackageRoot() } = {}) {
-  const directory = taskHandoffDirectory(taskId);
-  if (!(await fileExists(ensureWithin(target, directory)))) return [];
-  const entries = await readdir(ensureWithin(target, directory), { withFileTypes: true });
-  const handoffs = [];
-  for (const entry of entries) {
-    if (!entry.isFile() || !/^handoff-[A-Za-z0-9_-]+\.json$/u.test(entry.name)) continue;
-    const handoffId = entry.name.slice(0, -5);
-    const artifact = await readCanonicalHandoff(target, { taskId, handoffId, packageRoot });
-    handoffs.push(artifact.value);
-  }
-  return handoffs.sort((left, right) => left.createdAt.localeCompare(right.createdAt) || left.handoffId.localeCompare(right.handoffId));
+  return withProjectReadSnapshot(target, async () => {
+    const directory = taskHandoffDirectory(taskId);
+    let names = listOperationalArtifactNames(target, taskId, "handoffs");
+    if (names === null) {
+      if (!(await fileExists(ensureWithin(target, directory)))) return [];
+      names = (await readdir(ensureWithin(target, directory), { withFileTypes: true })).filter(entry => entry.isFile()).map(entry => entry.name);
+    }
+    const handoffs = [];
+    for (const name of names) {
+      if (!/^handoff-[A-Za-z0-9_-]+\.json$/u.test(name)) continue;
+      const handoffId = name.slice(0, -5);
+      const artifact = await readCanonicalHandoff(target, { taskId, handoffId, packageRoot });
+      handoffs.push(artifact.value);
+    }
+    return handoffs.sort((left, right) => left.createdAt.localeCompare(right.createdAt) || left.handoffId.localeCompare(right.handoffId));
+  });
 }
 
 export async function resolveLatestHandoff(target, { taskId, packageRoot = getPackageRoot() } = {}) {

package/src/core/history.js

@@ -10,46 +10,50 @@ export const HISTORY_FILTER_OPTIONS = Object.freeze([
   "limit",
 ]);
 
+function historyEventProjection(filters) {
+  const predicates = [];
+  for (const key of ["type", "phase"]) {
+    if (!filters[key]) continue;
+    const values = String(filters[key]).split(",").map(value => value.trim()).filter(Boolean);
+    if (values.length) predicates.push(event => values.includes(event[key])
+      || (key === "type" && values.includes(event.category)));
+  }
+  if (filters.failures) predicates.push(event => event.category === "verification"
+    && ["failed", "blocked"].includes(String(event.data?.status ?? "")));
+  if (filters.checks) predicates.push(event => event.category === "verification");
+  for (const key of ["since", "until"]) {
+    if (!filters[key]) continue;
+    const bound = Date.parse(filters[key]);
+    if (!Number.isNaN(bound)) predicates.push(event => event.timestamp
+      && (key === "since" ? Date.parse(event.timestamp) >= bound : Date.parse(event.timestamp) <= bound));
+  }
+  const limit = Number.isInteger(filters.limit) && filters.limit >= 0 ? filters.limit : null;
+  const events = [];
+  let matched = 0;
+  let cursor = 0;
+  return {
+    add(event) {
+      if (!predicates.every(predicate => predicate(event))) return;
+      matched += 1;
+      if (limit === 0) return;
+      if (limit === null || events.length < limit) events.push(event);
+      else { events[cursor] = event; cursor = (cursor + 1) % limit; }
+    },
+    result: () => cursor === 0 ? events : events.slice(cursor).concat(events.slice(0, cursor)),
+    get omittedEvents() { return matched - events.length; },
+  };
+}
+
 export async function buildTaskHistory({
   target,
   packageRoot,
   taskId = null,
   filters = {},
 } = {}) {
-  const trace = await buildTaskTrace({ target, packageRoot, taskId });
-  let events = [...trace.events];
-
-  if (filters.type) {
-    const types = String(filters.type).split(",").map((value) => value.trim()).filter(Boolean);
-    if (types.length > 0) {
-      events = events.filter((event) => types.includes(event.type) || types.includes(event.category));
-    }
-  }
-  if (filters.phase) {
-    const phases = String(filters.phase).split(",").map((value) => value.trim()).filter(Boolean);
-    if (phases.length > 0) events = events.filter((event) => phases.includes(event.phase));
-  }
-  if (filters.failures) {
-    events = events.filter((event) => event.category === "verification"
-      && ["failed", "blocked"].includes(String(event.data?.status ?? "")));
-  }
-  if (filters.checks) {
-    events = events.filter((event) => event.category === "verification");
-  }
-  if (filters.since) {
-    const since = Date.parse(filters.since);
-    if (!Number.isNaN(since)) events = events.filter((event) => event.timestamp && Date.parse(event.timestamp) >= since);
-  }
-  if (filters.until) {
-    const until = Date.parse(filters.until);
-    if (!Number.isNaN(until)) events = events.filter((event) => event.timestamp && Date.parse(event.timestamp) <= until);
-  }
-
-  let omittedEvents = 0;
-  if (Number.isInteger(filters.limit) && filters.limit >= 0 && events.length > filters.limit) {
-    omittedEvents = events.length - filters.limit;
-    events = events.slice(-filters.limit);
-  }
+  const projection = historyEventProjection(filters);
+  const trace = await buildTaskTrace({ target, packageRoot, taskId }, projection);
+  const events = trace.events;
+  const omittedEvents = projection.omittedEvents;
 
   const checkAttempts = trace.checks.reduce(
     (total, check) => total + check.attemptCount,
@@ -67,7 +71,7 @@ export async function buildTaskHistory({
     snapshot: trace.snapshot,
     summary: {
       eventCount: events.length,
-      totalEventCount: trace.events.length,
+      totalEventCount: trace.totalEventCount,
       checkAttemptCount: checkAttempts,
       failedAttemptCount: failedAttempts,
       diagnosticCaseCount: trace.diagnostics.cases.length,

package/src/core/hypothesis-projection.js

@@ -1,3 +1,5 @@
+import { isLedgerEventCollection, ledgerEventsOfTypes } from "./ledger-event-collection.js";
+import { ledgerRelationMap } from "./ledger-relations.js";
 import { DISPOSITION_TRANSITIONS } from "./diagnostic-model.js";
 
 const TERMINAL_STATUSES = Object.freeze(["FALSIFIED", "SUPERSEDED", "UNRESOLVED"]);
@@ -83,3 +85,33 @@ export function getOpenHypotheses(projection) {
 export function getHypothesisState(projection, id) {
   return projection?.hypotheses.find((hypothesis) => hypothesis.id === id) ?? null;
 }
+
+
+/** Internal context needs current IDs, not every historical disposition payload. */
+export function summarizeOpenHypotheses(events, taskId = null) {
+  if (Array.isArray(events)) return projectHypothesisStates(events.filter(event => !taskId || event.taskId === taskId)).openHypotheses;
+  if (!isLedgerEventCollection(events)) throw new TypeError("Hypothesis context requires a ledger collection");
+  let previous = -Infinity;
+  for (const event of events) {
+    if (!Number.isFinite(event.seq) || event.seq < previous) {
+      return projectHypothesisStates([...events].filter(candidate => !taskId || candidate.taskId === taskId)).openHypotheses;
+    }
+    previous = event.seq;
+  }
+  const statuses = ledgerRelationMap();
+  const ensure = id => { if (!statuses.has(id)) statuses.set(id, "OPEN"); };
+  for (const event of ledgerEventsOfTypes(events, ["DIAGNOSTIC_CASE_RECORDED", "DIAGNOSIS_RECORDED", "HYPOTHESIS_DISPOSITION_RECORDED"])) {
+    if (taskId && event.taskId !== taskId) continue;
+    const details = event.details ?? {};
+    if (event.event === "DIAGNOSTIC_CASE_RECORDED") {
+      for (const hypothesis of details.hypotheses ?? []) if (hypothesis?.id) ensure(hypothesis.id);
+    } else if (event.event === "DIAGNOSIS_RECORDED") ensure(HYPOTHESIS_LEGACY_ID);
+    else if (details.hypothesisRef && details.status) {
+      ensure(details.hypothesisRef);
+      if (canTransition(statuses.get(details.hypothesisRef), details.status)) statuses.set(details.hypothesisRef, details.status);
+    }
+  }
+  const open = [];
+  for (const [id, status] of statuses) if (status === "OPEN") open.push(id);
+  return open.sort();
+}

package/src/core/information-gain-projection.js

@@ -1,5 +1,6 @@
-import { diagnosticEventsForTask } from "./diagnostic-projection.js";
-import { normalizeDiagnosticSnapshot, computeInformationGain } from "./information-gain.js";
+import { ledgerRelationSet, ledgerGroupedSet } from "./ledger-relations.js";
+import { isLedgerEventCollection, ledgerEventsOfTypes } from "./ledger-event-collection.js";
+import { normalizeDiagnosticSnapshot, compareDiagnosticCycles, classifyGain, isEffectiveGain } from "./information-gain.js";
 import { computeFailureSignature } from "./failure-signature.js";
 
 function snapshotFor(event) {
@@ -19,23 +20,43 @@ const sameSortedSet = (a, b) =>
 //   current diagnostic sequence inclusive.
 // Events inside an interval belong to the *current* cycle's knowledge state;
 // they are never attributed retroactively to the earlier diagnosis.
-function intervalEvents(taskEvents, fromExclusive, toInclusive) {
-  return taskEvents.filter((event) =>
-    event.seq > fromExclusive && event.seq <= toInclusive);
+function* intervalEvents(taskEvents, fromExclusive, toInclusive) {
+  for (const event of taskEvents) if (event.seq > fromExclusive && event.seq <= toInclusive) yield event;
+}
+
+function orderedTaskEvents(events, taskId) {
+  const belongs = event => !taskId || !event.taskId || event.taskId === taskId;
+  if (!Array.isArray(events) && isLedgerEventCollection(events)) {
+    let previous = -Infinity;
+    let ordered = true;
+    for (const event of events) {
+      if (!Number.isFinite(event.seq) || event.seq < previous) { ordered = false; break; }
+      previous = event.seq;
+    }
+    if (ordered) return { *[Symbol.iterator]() { for (const event of ledgerEventsOfTypes(events, ["DIAGNOSTIC_CASE_RECORDED", "DIAGNOSIS_RECORDED", "VERIFICATION_STARTED", "VERIFICATION_RECORDED", "INTERVENTION_RECORDED", "HYPOTHESIS_DISPOSITION_RECORDED"])) if (belongs(event)) yield event; } };
+  }
+  return [...(events ?? [])].filter(belongs).sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));
+}
+
+function eliminatedHypothesis(previousDiagnostic, diagnostic) {
+  if (previousDiagnostic?.event !== "DIAGNOSTIC_CASE_RECORDED" || diagnostic.event !== "DIAGNOSTIC_CASE_RECORDED") return false;
+  const previous = previousDiagnostic.details?.hypotheses ?? [];
+  const current = diagnostic.details?.hypotheses ?? [];
+  const statements = new Set(current.map(hypothesis => `${hypothesis.statement}`.trim().toLowerCase()));
+  return previous.some(hypothesis => !current.some(candidate => candidate.id === hypothesis.id)
+    && !statements.has(`${hypothesis.statement}`.trim().toLowerCase()));
 }
 
 function failureStateByCycle(taskEvents) {
-  const surfaces = new Map();
-  const signatures = new Map();
+  const surfaces = ledgerGroupedSet();
+  const signatures = ledgerGroupedSet();
   const record = (cycle, details) => {
     if (!Number.isInteger(cycle)) cycle = Number(cycle) || 1;
-    if (!surfaces.has(cycle)) surfaces.set(cycle, new Set());
-    if (!signatures.has(cycle)) signatures.set(cycle, new Set());
     const requirement = details.requirement ?? details.id ?? details.checkId;
     if (!requirement) return;
     if (details.status === "failed" || details.status === "blocked") {
-      surfaces.get(cycle).add(requirement);
-      signatures.get(cycle).add(computeFailureSignature({
+      surfaces.add(cycle, requirement);
+      signatures.add(cycle, computeFailureSignature({
         requirement,
         status: details.status,
         exitCode: Number.isInteger(details.exitCode) ? details.exitCode : null,
@@ -44,13 +65,6 @@ function failureStateByCycle(taskEvents) {
     }
   };
   for (const event of taskEvents) {
-    if (event.event === "VERIFICATION_STARTED") {
-      const cycle = event.details?.verificationCycle;
-      if (Number.isInteger(cycle)) {
-        if (!surfaces.has(cycle)) surfaces.set(cycle, new Set());
-        if (!signatures.has(cycle)) signatures.set(cycle, new Set());
-      }
-    }
     if (event.event === "VERIFICATION_RECORDED") {
       record(event.details?.verificationCycle ?? 1, event.details ?? {});
     }
@@ -102,46 +116,45 @@ function snapshotHasContentDelta(previousDetails, currentDetails) {
     || differs(prev.evidence, cur.evidence);
 }
 
-export function buildInformationGainProjection(events, taskId) {
-  const taskEvents = (events ?? [])
-    .filter((event) => !taskId || !event.taskId || event.taskId === taskId)
-    .sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));
+function intervalKnowledge(taskEvents, previousDiagnostic, diagnostic) {
+  const intervalStart = previousDiagnostic ? previousDiagnostic.seq : -Infinity;
+  let hypothesisDispositionChanged = false;
+  const knownUpToPrev = ledgerRelationSet();
+  for (const event of taskEvents) {
+    if (event.event === "INTERVENTION_RECORDED" && previousDiagnostic && (event.seq ?? 0) <= previousDiagnostic.seq) {
+      const fingerprint = event.details?.interventionSemanticFingerprint
+        ?? `${event.details?.intervention?.statement ?? ""}`.trim().toLowerCase();
+      if (fingerprint) knownUpToPrev.add(fingerprint);
+    }
+  }
+  let novelIntervention = false;
+  for (const event of intervalEvents(taskEvents, intervalStart, diagnostic.seq)) {
+    if (event.event === "HYPOTHESIS_DISPOSITION_RECORDED") hypothesisDispositionChanged = true;
+    if (event.event === "INTERVENTION_RECORDED") {
+    const fingerprint = event.details?.interventionSemanticFingerprint
+      ?? `${event.details?.intervention?.statement ?? ""}`.trim().toLowerCase();
+    if (fingerprint && !knownUpToPrev.has(fingerprint)) novelIntervention = true;
+    }
+  }
+  return { hypothesisDispositionChanged, novelIntervention };
+}
 
-  const diagnosticEvents = diagnosticEventsForTask(taskEvents, taskId)
-    .sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));
-  if (diagnosticEvents.length === 0) return [];
+function* iterateInformationGainProjection(events, taskId) {
+  const taskEvents = orderedTaskEvents(events, taskId);
+  const diagnosticEvents = { *[Symbol.iterator]() {
+    for (const event of taskEvents) {
+      if (["DIAGNOSTIC_CASE_RECORDED", "DIAGNOSIS_RECORDED"].includes(event.event)
+        && (!taskId || event.taskId === taskId)) yield event;
+    }
+  } };
 
   const failure = failureStateByCycle(taskEvents);
 
-  // Build final per-cycle entries first; effectiveGain is computed once at the
-  // end from fully final dimensions (no post-mutation anywhere).
-  const built = [];
   let previousDiagnostic = null;
+  let previousSnapshot = null;
   for (const diagnostic of diagnosticEvents) {
-    const intervalStart = previousDiagnostic ? previousDiagnostic.seq : -Infinity;
-    const interval = intervalEvents(taskEvents, intervalStart, diagnostic.seq);
-
-    const hypothesisDispositionChanged =
-      interval.some((event) => event.event === "HYPOTHESIS_DISPOSITION_RECORDED");
+    const { hypothesisDispositionChanged, novelIntervention } = intervalKnowledge(taskEvents, previousDiagnostic, diagnostic);
 
-    // Intervention deltas recognize only genuinely NEW semantic interventions:
-    // recorded after the previous diagnosis, attributed to the current
-    // correction cycle, and never attempted before. Repeating an already-known
-    // intervention — or merely having executed the previous cycle's corrective
-    // action — is not new information.
-    const knownUpToPrev = new Set(
-      taskEvents
-        .filter((event) => event.event === "INTERVENTION_RECORDED"
-          && (previousDiagnostic ? (event.seq ?? 0) <= previousDiagnostic.seq : false))
-        .map((event) => event.details?.interventionSemanticFingerprint
-          ?? `${event.details?.intervention?.statement ?? ""}`.trim().toLowerCase())
-        .filter(Boolean),
-    );
-    const novelInInterval = interval
-      .filter((event) => event.event === "INTERVENTION_RECORDED")
-      .map((event) => event.details?.interventionSemanticFingerprint
-        ?? `${event.details?.intervention?.statement ?? ""}`.trim().toLowerCase())
-      .filter((fingerprint) => fingerprint && !knownUpToPrev.has(fingerprint));
     // A genuinely new intervention counts as information only when the
     // diagnosis itself moves: an identical re-proposal of the previous
     // diagnosis after executing its already-known corrective action carries
@@ -149,18 +162,18 @@ export function buildInformationGainProjection(events, taskId) {
     const sameSemanticsAsPrevious = Boolean(previousDiagnostic)
       && !snapshotHasContentDelta(previousDiagnostic.details ?? {}, diagnostic.details ?? {});
     const interventionChanged = Boolean(previousDiagnostic)
-      && novelInInterval.length > 0
+      && novelIntervention
       && !sameSemanticsAsPrevious;
 
     const cycle = diagnostic.details?.verificationCycle ?? 1;
     const previousCycle = previousDiagnostic?.details?.verificationCycle ?? null;
-    const surface = [...(failure.surfaces.get(cycle) ?? new Set())].sort();
-    const signatures = [...(failure.signatures.get(cycle) ?? new Set())].sort();
+    const surface = [...(failure.surfaces.values(cycle))].sort();
+    const signatures = [...(failure.signatures.values(cycle))].sort();
     const previousSurface = previousCycle !== null && previousCycle !== undefined
-      ? [...(failure.surfaces.get(previousCycle) ?? new Set())].sort()
+      ? [...(failure.surfaces.values(previousCycle))].sort()
       : null;
     const previousSignatures = previousCycle !== null && previousCycle !== undefined
-      ? [...(failure.signatures.get(previousCycle) ?? new Set())].sort()
+      ? [...(failure.signatures.values(previousCycle))].sort()
       : null;
     const hasPreviousFailureState = previousSurface !== null;
     const failureSurfaceChanged = hasPreviousFailureState
@@ -181,7 +194,7 @@ export function buildInformationGainProjection(events, taskId) {
 
     const snapshot = snapshotFor(diagnostic);
 
-    built.push({
+    const entry = {
       verificationCycle: cycle,
       sequence: diagnostic.seq ?? null,
       diagnosticSequence: diagnostic.seq ?? null,
@@ -195,62 +208,53 @@ export function buildInformationGainProjection(events, taskId) {
         failureSurfaceChanged,
         interventionChanged,
         strategyChanged,
-        hypothesisEliminated: false,
+        hypothesisEliminated: eliminatedHypothesis(previousDiagnostic, diagnostic),
       },
       evidence: {
         semanticRefs: [...(snapshot.evidenceRefs ?? [])].sort(),
         surface, signatures, strategyFingerprint,
       },
-    });
-
+    };
+    const dimensions = compareDiagnosticCycles(previousSnapshot, snapshot, entry.dimensionsInput);
+    const classification = classifyGain(dimensions, { first: previousDiagnostic === null });
+    const effectiveGain = isEffectiveGain(dimensions, classification);
+    yield finalizeGainEntry(entry, { dimensions, classification, effectiveGain });
     previousDiagnostic = diagnostic;
+    previousSnapshot = snapshot;
   }
+}
 
-  // Hypothesis elimination: an id disappearing only counts as elimination when
-  // no surviving hypothesis carries the same normalized statement — ID-only
-  // churn is artificial novelty and must never create gain.
-  for (let i = 1; i < built.length; i++) {
-    if (built[i].sourceModel !== "STRUCTURED_DIAGNOSTIC_CASE_V1"
-      || built[i - 1].sourceModel !== "STRUCTURED_DIAGNOSTIC_CASE_V1") continue;
-    const previousHypotheses = diagnosticEvents[i - 1]?.details?.hypotheses ?? [];
-    const currentHypotheses = diagnosticEvents[i]?.details?.hypotheses ?? [];
-    const currentStatements = new Set(currentHypotheses.map(
-      (hypothesis) => `${hypothesis.statement}`.trim().toLowerCase()));
-    built[i].dimensionsInput.hypothesisEliminated = previousHypotheses.some((hypothesis) => {
-      const survivedById = currentHypotheses.some((candidate) => candidate.id === hypothesis.id);
-      return !survivedById
-        && !currentStatements.has(`${hypothesis.statement}`.trim().toLowerCase());
-    });
-  }
-
-  // Final classification + single-point effectiveGain computation.
-  const entries = computeInformationGain(built.map((entry) => ({
+function finalizeGainEntry(entry, { dimensions, classification, effectiveGain }) {
+  return Object.freeze({
     verificationCycle: entry.verificationCycle,
     sequence: entry.sequence,
-    snapshot: entry.snapshot,
-    context: entry.dimensionsInput,
-  })));
-
-  return built.map((entry, index) => {
-    const { dimensions, classification, effectiveGain } = entries[index];
-    return Object.freeze({
-      verificationCycle: entry.verificationCycle,
-      sequence: entry.sequence,
-      diagnosticSequence: entry.diagnosticSequence,
-      sourceModel: entry.sourceModel,
-      evidence: Object.freeze({
-        semanticRefs: Object.freeze(entry.evidence.semanticRefs),
-        failureSurface: Object.freeze(entry.evidence.surface),
-        failureSignatures: Object.freeze(entry.evidence.signatures),
-        strategyFingerprint: entry.evidence.strategyFingerprint,
-      }),
-      dimensions: Object.freeze({ ...dimensions }),
-      classification,
-      effectiveGain,
-    });
+    diagnosticSequence: entry.diagnosticSequence,
+    sourceModel: entry.sourceModel,
+    evidence: Object.freeze({
+      semanticRefs: Object.freeze(entry.evidence.semanticRefs),
+      failureSurface: Object.freeze(entry.evidence.surface),
+      failureSignatures: Object.freeze(entry.evidence.signatures),
+      strategyFingerprint: entry.evidence.strategyFingerprint,
+    }),
+    dimensions: Object.freeze({ ...dimensions }),
+    classification,
+    effectiveGain,
   });
 }
 
+export function buildInformationGainProjection(events, taskId) {
+  return [...iterateInformationGainProjection(events, taskId)];
+}
+
+/** Internal latest-only use does not retain all diagnostic result objects. */
+export function summarizeInformationGain(events, taskId, { verificationCycle = null } = {}) {
+  let latest = null;
+  for (const entry of iterateInformationGainProjection(events, taskId)) {
+    if (verificationCycle === null || verificationCycle === undefined || entry.verificationCycle === verificationCycle) latest = entry;
+  }
+  return evaluateStructuredDiagnosticStall(latest ? [latest] : []);
+}
+
 // One canonical structured-stall policy (fail-fast):
 //   The latest comparable diagnostic state that produces no effective
 //   information gain is stalled and may not trigger another blind correction

package/src/core/inspect.js

@@ -17,6 +17,8 @@ import { evaluateProgress } from "./progress.js";
 import { readEvents } from "./events.js";
 import { taskStructuralQualityDirectory } from "./task-paths.js";
 import { projectStructuralQualityStatus } from "./structural-quality/status.js";
+import { operationalArtifactExists } from "../storage/operational-context.js";
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
 
 function reasonCodesFor({ state, trace, progress }) {
   const codes = [];
@@ -169,7 +171,15 @@ function profileMetadata(bytes) {
 
 import { taskArtifactPath } from "./task-paths.js";
 
-export async function inspectTarget({ target, packageRoot, contractFile = null, authorityContext, runtimeContext, taskId = null, stateFile = null } = {}) {
+async function inspectStatePresence(target, relativePath) {
+  return operationalArtifactExists(target, relativePath) ?? await fileExists(ensureWithin(target, relativePath));
+}
+
+export async function inspectTarget(options = {}) {
+  return withProjectReadSnapshot(options.target, () => inspectSelectedTarget(options));
+}
+
+async function inspectSelectedTarget({ target, packageRoot, contractFile = null, authorityContext, runtimeContext, taskId = null, stateFile = null } = {}) {
   let manifest = null;
   let manifestError = null;
   try {
@@ -184,8 +194,7 @@ export async function inspectTarget({ target, packageRoot, contractFile = null,
     ? { ...profileMetadata(await readBytes(profilePath)), path: profileRelativePath }
     : { mode: null, status: null };
   const effectiveStateRel = stateFile ?? (taskId ? taskArtifactPath(taskId, "state") : WORK_STATE_PATH);
-  const statePath = ensureWithin(target, effectiveStateRel);
-  const statePresent = await fileExists(statePath);
+  const statePresent = await inspectStatePresence(target, effectiveStateRel);
   const classifiedState = await readAndClassifyWorkState({ target, packageRoot, contractFile, taskId, stateFile: effectiveStateRel });
   const rawState = classifiedState?.state ?? null;
   const taskInfo = taskId ? await findTaskById(target, taskId, packageRoot) : null;

package/src/core/integration-invocation-policy.js

@@ -1,3 +1,4 @@
+import { getStorageCapabilities } from "../storage/capabilities.js";
 import { CLI_COMMAND_DEFINITIONS } from "./cli-command-definitions.js";
 import { COMMAND_EXECUTORS } from "./command-executors.js";
 import { PROTOCOL_VERSION } from "./protocol.js";
@@ -24,7 +25,8 @@ export const INTEGRATION_RISK_CLASSES = Object.freeze({
 });
 
 const READ_ONLY_COMMANDS = Object.freeze(new Set([
-  "protocol-info", "status", "next", "continuity", "reconcile-continuity",
+  "storage-migration-status",
+  "protocol-info", "decision-status", "decision-show", "context-plan", "model-route", "semantic-plan", "test-inventory", "status", "next", "continuity", "reconcile-continuity",
   "task-list", "task-show", "task-lock-status", "progress", "audit", "report",
   "inspect", "validate-state", "validate-protocol", "validate-receipt",
   "policy-status", "policy-diff", "rule-verify", "policy",
@@ -37,7 +39,7 @@ const READ_ONLY_COMMANDS = Object.freeze(new Set([
 ]));
 
 const LOOP_MUTATION_COMMANDS = Object.freeze(new Set([
-  "route", "preflight", "advance", "task-create", "task-scope",
+  "discover", "contract-create", "route", "preflight", "advance", "task-create", "task-scope",
   "record-continuity", "clear-continuity", "prepare-completion",
   "record-check", "record-diagnosis", "record-decision-criterion",
   "record-terminal-result", "complete",
@@ -69,6 +71,13 @@ const STATIC_RISK_CLASSES = Object.freeze({
   "usage-record": INTEGRATION_RISK_CLASSES.LOOP_MUTATION,
   init: INTEGRATION_RISK_CLASSES.MAINTENANCE,
   update: INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "storage-migration-resume": INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "storage-rollback-resume": INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "storage-rollback": INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "storage-migrate": INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "storage-backup": INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "storage-restore": INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "storage-restore-resume": INTEGRATION_RISK_CLASSES.MAINTENANCE,
   activate: INTEGRATION_RISK_CLASSES.MAINTENANCE,
   "task-migrate": INTEGRATION_RISK_CLASSES.MAINTENANCE,
   "migrate-protocol": INTEGRATION_RISK_CLASSES.MAINTENANCE,
@@ -86,7 +95,17 @@ const STATIC_RISK_CLASSES = Object.freeze({
   bundle: INTEGRATION_RISK_CLASSES.MAINTENANCE,
   "profile-interview": INTEGRATION_RISK_CLASSES.MAINTENANCE,
   "task-recover": INTEGRATION_RISK_CLASSES.CLAIM_RELEASE_RECOVERY,
+  "task-abandon": INTEGRATION_RISK_CLASSES.CLAIM_RELEASE_RECOVERY,
   "task-repair-legacy-recovery": INTEGRATION_RISK_CLASSES.LEGACY_MIGRATION,
+  "gate-record": INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "gate-revalidate": INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "test-utility": INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "test-prune-plan": INTEGRATION_RISK_CLASSES.READ_ONLY,
+  "test-prune-probe": INTEGRATION_RISK_CLASSES.EXTERNAL_EXECUTION,
+  "task-repair-contract-bootstrap": INTEGRATION_RISK_CLASSES.LEGACY_MIGRATION,
+  "task-migrate-contract-bootstrap-repair": INTEGRATION_RISK_CLASSES.LEGACY_MIGRATION,
+  "checkpoint-revalidate": INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "contract-revise": INTEGRATION_RISK_CLASSES.MAINTENANCE,
 });
 
 // Sparse input-dependent refinements over the static table.
@@ -133,6 +152,7 @@ export function getForgeLoopCapabilities({ packageVersion = null } = {}) {
     integrationApiVersion: FORGELOOP_INTEGRATION_RUNTIME_VERSION,
     executorParity: Object.keys(COMMAND_EXECUTORS).length === Object.keys(CLI_COMMAND_DEFINITIONS).length,
     features: {
+      operationalStorage: getStorageCapabilities(),
       taskClaimRecovery: {
         version: 1,
         durableRecoveryState: true,
@@ -169,6 +189,18 @@ export function getForgeLoopCapabilities({ 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,
@@ -295,6 +327,7 @@ export function getForgeLoopCapabilities({ packageVersion = null } = {}) {
       { name: "task/approvals", scope: "TASK" },
       { name: "task/metrics", scope: "TASK" },
       { name: "task/context", scope: "TASK" },
+      { name: "task/audit-view", scope: "TASK" },
       { name: "task/evaluations", scope: "TASK" },
       { name: "project/capability-policy", scope: "PROJECT" },
       { name: "repository/index-status", scope: "PROJECT" },
@@ -352,8 +385,8 @@ export function classifyForgeLoopInvocation(command, input = {}) {
     removesArtifacts: definition.removes.length > 0,
     executesExternalProcess: definition.mayExecuteExternalProcess === true,
     affectsClaimAuthority: [
-      "task-resume", "task-recover", "task-repair-legacy-recovery",
-      "task-create", "task-scope", "complete",
+      "task-resume", "task-recover", "task-repair-legacy-recovery", "task-repair-contract-bootstrap",
+      "task-create", "task-scope", "complete", "task-migrate-contract-bootstrap-repair",
     ].includes(command),
     destructive: [
       INTEGRATION_RISK_CLASSES.AUTHORITY_MUTATION,