@cassiomc1/forgeloop 1.3.0 → 1.6.0

package/src/core/filesystem.js

@@ -10,6 +10,55 @@ import {
   unlink,
 } from "node:fs/promises";
 import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+
+const WINDOWS_TRANSIENT_RETRY_DELAYS_MS = Object.freeze([5, 10, 20, 40]);
+
+async function fsCallWithTransientWindowsRetry(fsImpl, filePath, {
+  platform = process.platform,
+  retryDelaysMs = WINDOWS_TRANSIENT_RETRY_DELAYS_MS,
+  delayImpl = delay,
+} = {}) {
+  let retryIndex = 0;
+  while (true) {
+    try {
+      return await fsImpl(filePath);
+    } catch (error) {
+      const retryable = platform === "win32"
+        && (error?.code === "EPERM" || error?.code === "EACCES")
+        && retryIndex < retryDelaysMs.length;
+      if (!retryable) throw error;
+      await delayImpl(retryDelaysMs[retryIndex]);
+      retryIndex += 1;
+    }
+  }
+}
+
+export async function realpathWithTransientWindowsRetry(filePath, {
+  platform = process.platform,
+  retryDelaysMs = WINDOWS_TRANSIENT_RETRY_DELAYS_MS,
+  realpathImpl = realpath,
+  delayImpl = delay,
+} = {}) {
+  return fsCallWithTransientWindowsRetry(realpathImpl, filePath, {
+    platform,
+    retryDelaysMs,
+    delayImpl,
+  });
+}
+
+export function lstatWithTransientWindowsRetry(filePath, {
+  platform = process.platform,
+  retryDelaysMs = WINDOWS_TRANSIENT_RETRY_DELAYS_MS,
+  lstatImpl = lstat,
+  delayImpl = delay,
+} = {}) {
+  return fsCallWithTransientWindowsRetry(lstatImpl, filePath, {
+    platform,
+    retryDelaysMs,
+    delayImpl,
+  });
+}
 
 export function ensureWithin(root, relativePath) {
   if (path.isAbsolute(relativePath)) {
@@ -27,7 +76,7 @@ export function ensureWithin(root, relativePath) {
 export async function assertSafePath(root, relativePath) {
   const destination = ensureWithin(root, relativePath);
   const absoluteRoot = path.resolve(root);
-  const rootInfo = await lstat(absoluteRoot);
+  const rootInfo = await lstatWithTransientWindowsRetry(absoluteRoot);
   if (rootInfo.isSymbolicLink() || !rootInfo.isDirectory()) {
     throw new Error(`Target directory must not be a symlink: ${absoluteRoot}`);
   }
@@ -37,7 +86,7 @@ export async function assertSafePath(root, relativePath) {
   for (const segment of segments) {
     current = path.join(current, segment);
     try {
-      const info = await lstat(current);
+      const info = await lstatWithTransientWindowsRetry(current);
       if (info.isSymbolicLink()) {
         throw new Error(`Path uses a symlink inside target directory: ${relativePath}`);
       }
@@ -50,12 +99,12 @@ export async function assertSafePath(root, relativePath) {
   let existing = destination;
   while (true) {
     try {
-      const info = await lstat(existing);
+      const info = await lstatWithTransientWindowsRetry(existing);
       if (info.isSymbolicLink()) {
         throw new Error(`Path uses a symlink inside target directory: ${relativePath}`);
       }
-      const resolvedRoot = await realpath(absoluteRoot);
-      const resolvedExisting = await realpath(existing);
+      const resolvedRoot = await realpathWithTransientWindowsRetry(absoluteRoot);
+      const resolvedExisting = await realpathWithTransientWindowsRetry(existing);
       const relativeResolved = path.relative(resolvedRoot, resolvedExisting);
       if (relativeResolved === ".." || relativeResolved.startsWith(`..${path.sep}`) || path.isAbsolute(relativeResolved)) {
         throw new Error(`Path escapes target directory: ${relativePath}`);
@@ -137,4 +186,4 @@ export async function writeFileAtomic(filePath, bytes, { dryRun = false } = {})
     }
     throw error;
   }
-}
+}

package/src/core/history.js

@@ -0,0 +1,110 @@
+import { buildTaskTrace } from "./trace.js";
+
+export const HISTORY_FILTER_OPTIONS = Object.freeze([
+  "type",
+  "phase",
+  "failures",
+  "checks",
+  "since",
+  "until",
+  "limit",
+]);
+
+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 checkAttempts = trace.checks.reduce(
+    (total, check) => total + check.attemptCount,
+    0,
+  );
+  const failedAttempts = trace.checks.reduce(
+    (total, check) => total + check.failedAttempts,
+    0,
+  );
+
+  return {
+    schemaVersion: 1,
+    command: "history",
+    task: trace.task,
+    snapshot: trace.snapshot,
+    summary: {
+      eventCount: events.length,
+      totalEventCount: trace.events.length,
+      checkAttemptCount: checkAttempts,
+      failedAttemptCount: failedAttempts,
+      diagnosticCaseCount: trace.diagnostics.cases.length,
+      interventionCount: trace.diagnostics.interventions.length,
+    },
+    historyQuality: trace.historyQuality,
+    integrity: trace.integrity,
+    events,
+    ...(omittedEvents > 0 ? { truncated: true, truncation: { reason: "OUTPUT_LIMIT", omittedEvents } } : {}),
+  };
+}
+
+export function formatHistoryEvent(event) {
+  const time = event.timestamp && !Number.isNaN(Date.parse(event.timestamp))
+    ? new Date(event.timestamp).toISOString().slice(11, 19)
+    : "--:--:--";
+  const lines = [`${time}  ${event.type}`];
+  if (event.summary && event.summary !== event.type) lines.push(`           ${event.summary}`);
+  if (event.data?.provenance) lines.push(`           provenance: ${event.data.provenance}`);
+  return lines.join("\n");
+}
+
+export function formatHistoryResult(result) {
+  const lines = [
+    "ForgeLoop Execution History",
+    "─".repeat(56),
+    "",
+    `Task:      ${result.task.id ?? "unknown"}`,
+    `Phase:     ${result.task.phase ?? "UNKNOWN"}`,
+    `Integrity: ${result.integrity.valid ? "VALID" : "INCONSISTENT"}`,
+    `History quality: ${result.historyQuality.level}`,
+    result.historyQuality.reasons.length > 0 ? `Reasons: ${result.historyQuality.reasons.join(", ")}` : null,
+    "",
+    ...result.events.map(formatHistoryEvent),
+  ].filter((line) => line !== null);
+  if (result.truncated) {
+    lines.push("", `[truncated: ${result.truncation.omittedEvents} earlier events omitted]`);
+  }
+  return lines.join("\n") + "\n";
+}

package/src/core/hypothesis-projection.js

@@ -0,0 +1,85 @@
+import { DISPOSITION_TRANSITIONS } from "./diagnostic-model.js";
+
+const TERMINAL_STATUSES = Object.freeze(["FALSIFIED", "SUPERSEDED", "UNRESOLVED"]);
+export const HYPOTHESIS_LEGACY_ID = "h-legacy";
+
+function canTransition(from, to) {
+  if (from === to) return false;
+  if (TERMINAL_STATUSES.includes(from)) return false;
+  return (DISPOSITION_TRANSITIONS[from] ?? []).includes(to);
+}
+
+function blankState(id) {
+  return {
+    id,
+    sourceEventSeq: null,
+    sourceCycle: null,
+    initialStatus: "OPEN",
+    currentStatus: "OPEN",
+    dispositionHistory: [],
+  };
+}
+
+export function projectHypothesisStates(events, { taskId = null } = {}) {
+  const ordered = [...events].sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));
+  const byId = new Map();
+  const invalidTransitions = [];
+
+  const ensure = (id, seq, cycle) => {
+    if (!byId.has(id)) {
+      const state = blankState(id);
+      state.sourceEventSeq = seq ?? null;
+      state.sourceCycle = cycle ?? null;
+      byId.set(id, state);
+    }
+    return byId.get(id);
+  };
+
+  for (const event of ordered) {
+    if (taskId && event.taskId && event.taskId !== taskId) continue;
+    const details = event.details ?? {};
+    if (event.event === "DIAGNOSTIC_CASE_RECORDED") {
+      for (const hypothesis of details.hypotheses ?? []) {
+        if (!hypothesis?.id) continue;
+        ensure(hypothesis.id, event.seq, details.verificationCycle);
+      }
+    } else if (event.event === "DIAGNOSIS_RECORDED") {
+      ensure(HYPOTHESIS_LEGACY_ID, event.seq, details.verificationCycle);
+    } else if (event.event === "HYPOTHESIS_DISPOSITION_RECORDED") {
+      const ref = details.hypothesisRef;
+      if (!ref || !details.status) continue;
+      const state = ensure(ref, null, null);
+      if (!canTransition(state.currentStatus, details.status)) {
+        invalidTransitions.push({
+          sequence: event.seq,
+          hypothesisRef: ref,
+          from: state.currentStatus,
+          to: details.status,
+        });
+        continue;
+      }
+      state.currentStatus = details.status;
+      state.dispositionHistory.push({
+        sequence: event.seq,
+        status: details.status,
+        evidenceRefs: [...(details.evidenceRefs ?? [])],
+        reason: details.reason ?? null,
+      });
+    }
+  }
+
+  const hypotheses = [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
+  return {
+    hypotheses,
+    openHypotheses: hypotheses.filter((hypothesis) => hypothesis.currentStatus === "OPEN").map((hypothesis) => hypothesis.id),
+    invalidTransitions,
+  };
+}
+
+export function getOpenHypotheses(projection) {
+  return projection?.openHypotheses ?? [];
+}
+
+export function getHypothesisState(projection, id) {
+  return projection?.hypotheses.find((hypothesis) => hypothesis.id === id) ?? null;
+}

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

@@ -0,0 +1,283 @@
+import { diagnosticEventsForTask } from "./diagnostic-projection.js";
+import { normalizeDiagnosticSnapshot, computeInformationGain } from "./information-gain.js";
+import { computeFailureSignature } from "./failure-signature.js";
+
+function snapshotFor(event) {
+  const details = event.details ?? {};
+  if (event.event === "DIAGNOSTIC_CASE_RECORDED") {
+    return normalizeDiagnosticSnapshot({ ...details, legacy: false });
+  }
+  return normalizeDiagnosticSnapshot({ ...details, legacy: true });
+}
+
+const sameSortedSet = (a, b) =>
+  JSON.stringify([...(a ?? [])].sort()) === JSON.stringify([...(b ?? [])].sort());
+
+// Cycle interval rule (documented contract):
+//   For diagnostic event D[n], the analysis interval is
+//   (D[n-1].sequence, D[n].sequence] — previous diagnostic sequence exclusive,
+//   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 failureStateByCycle(taskEvents) {
+  const surfaces = new Map();
+  const signatures = new Map();
+  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({
+        requirement,
+        status: details.status,
+        exitCode: Number.isInteger(details.exitCode) ? details.exitCode : null,
+        failureToken: typeof details.failureToken === "string" ? details.failureToken : (typeof details.details?.failureToken === "string" ? details.details.failureToken : null),
+      }));
+    }
+  };
+  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 ?? {});
+    }
+  }
+  return { surfaces, signatures };
+}
+
+
+function strategyFingerprintFor(diagnosticEvent, interventionsUpTo) {
+  const details = diagnosticEvent?.details ?? {};
+  const components = {
+    hypotheses: (details.hypotheses ?? []).map((hypothesis) => `${hypothesis.statement}`.trim().toLowerCase()),
+    contributors: (details.contributors ?? []).map((contributor) => `${contributor.statement}`.trim().toLowerCase()),
+    legacyHypothesis: diagnosticEvent?.event === "DIAGNOSIS_RECORDED"
+      ? [`${details.hypothesis ?? ""}`.trim().toLowerCase()]
+      : [],
+    interventions: interventionsUpTo.map((entry) => entry.fingerprint),
+  };
+  return JSON.stringify([
+    [...components.hypotheses, ...components.legacyHypothesis].sort(),
+    components.contributors.sort(),
+    components.interventions.sort(),
+  ]);
+}
+
+function snapshotHasContentDelta(previousDetails, currentDetails) {
+  const statementsOf = (details) => ({
+    observations: new Set((details.observations ?? []).map((o) => `${o.statement}`.trim().toLowerCase())),
+    contributors: new Set((details.contributors ?? []).map((c) => `${c.statement}`.trim().toLowerCase())),
+    hypotheses: new Set((details.hypotheses ?? []).map((h) => `${h.statement}`.trim().toLowerCase())),
+    legacyHypothesis: details.hypothesis ? new Set([`${details.hypothesis}`.trim().toLowerCase()]) : null,
+    evidence: new Set([
+      ...((details.hypotheses ?? []).flatMap((h) => h.evidenceRefs ?? [])),
+      ...((details.observations ?? []).map((o) => o.evidenceRef).filter(Boolean)),
+      ...(details.evidenceRefs ?? []),
+    ]),
+  });
+  const prev = statementsOf(previousDetails);
+  const cur = statementsOf(currentDetails);
+  const differs = (a, b) => {
+    if (!a || !b) return false;
+    for (const value of b) if (!a.has(value)) return true;
+    return false;
+  };
+  return differs(prev.observations, cur.observations)
+    || differs(prev.contributors, cur.contributors)
+    || differs(prev.hypotheses, cur.hypotheses)
+    || differs(prev.legacyHypothesis, cur.legacyHypothesis)
+    || 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));
+
+  const diagnosticEvents = diagnosticEventsForTask(taskEvents, taskId)
+    .sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));
+  if (diagnosticEvents.length === 0) return [];
+
+  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;
+  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");
+
+    // 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
+    // no new semantic state.
+    const sameSemanticsAsPrevious = Boolean(previousDiagnostic)
+      && !snapshotHasContentDelta(previousDiagnostic.details ?? {}, diagnostic.details ?? {});
+    const interventionChanged = Boolean(previousDiagnostic)
+      && novelInInterval.length > 0
+      && !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 previousSurface = previousCycle != null
+      ? [...(failure.surfaces.get(previousCycle) ?? new Set())].sort()
+      : null;
+    const previousSignatures = previousCycle != null
+      ? [...(failure.signatures.get(previousCycle) ?? new Set())].sort()
+      : null;
+    const hasPreviousFailureState = previousSurface !== null;
+    const failureSurfaceChanged = hasPreviousFailureState
+      ? !sameSortedSet(surface, previousSurface)
+      : false;
+    const failureSignatureChanged = hasPreviousFailureState
+      ? !sameSortedSet(signatures, previousSignatures)
+      : false;
+
+    // Strategy compares the PROPOSED diagnostic approach: the case's own
+    // semantic content on both sides (identical bases, so the delta is real).
+    const strategyFingerprint = strategyFingerprintFor(diagnostic, []);
+    const previousStrategyFingerprint = previousDiagnostic
+      ? strategyFingerprintFor(previousDiagnostic, [])
+      : null;
+    const strategyChanged = Boolean(previousStrategyFingerprint
+      && strategyFingerprint !== previousStrategyFingerprint);
+
+    const snapshot = snapshotFor(diagnostic);
+
+    built.push({
+      verificationCycle: cycle,
+      sequence: diagnostic.seq ?? null,
+      diagnosticSequence: diagnostic.seq ?? null,
+      sourceModel: diagnostic.event === "DIAGNOSTIC_CASE_RECORDED"
+        ? "STRUCTURED_DIAGNOSTIC_CASE_V1"
+        : "LEGACY_DIAGNOSIS_V1",
+      snapshot,
+      dimensionsInput: {
+        hypothesisDispositionChanged,
+        failureSignatureChanged,
+        failureSurfaceChanged,
+        interventionChanged,
+        strategyChanged,
+        hypothesisEliminated: false,
+      },
+      evidence: {
+        semanticRefs: [...(snapshot.evidenceRefs ?? [])].sort(),
+        surface, signatures, strategyFingerprint,
+      },
+    });
+
+    previousDiagnostic = diagnostic;
+  }
+
+  // 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) => ({
+    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,
+    });
+  });
+}
+
+// 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
+//   retry. The first diagnosis is never stalled. Legacy diagnosis keeps its
+//   own compatibility rule (informationGain === NONE).
+export function evaluateStructuredDiagnosticStall(gainProjection, { verificationCycle = null } = {}) {
+  const candidates = verificationCycle == null
+    ? (gainProjection ?? [])
+    : (gainProjection ?? []).filter((entry) => entry.verificationCycle === verificationCycle);
+
+  const latest = candidates.at(-1) ?? null;
+  if (!latest) {
+    return { stalled: false, latestGain: null, reason: null };
+  }
+  if (latest.classification === "FIRST_DIAGNOSIS") {
+    return { stalled: false, latestGain: latest, reason: null };
+  }
+  const stalled = latest.effectiveGain === false;
+  return {
+    stalled,
+    latestGain: latest,
+    reason: stalled ? "NO_DIAGNOSTIC_INFORMATION_GAIN" : null,
+  };
+}
+
+export function computeCycleInformationGain(events, taskId, verificationCycle) {
+  const projection = buildInformationGainProjection(events, taskId);
+  const matching = projection.filter((entry) => entry.verificationCycle === verificationCycle);
+  return matching.at(-1) ?? null;
+}