@cassiomc1/forgeloop 1.5.0 → 1.6.1

package/src/core/completion.js

@@ -13,6 +13,25 @@ import { isRecoverableCompletionEvidenceCode } from "./completion-recovery.js";
 import { evaluateTerminalRequirements } from "./evidence-readiness.js";
 import { PROJECT_ARTIFACT_PATHS, taskArtifactPath } from "./task-paths.js";
 import { detectPolicyCapability, evaluateTargetPolicy } from "./policy-engine.js";
+import { listActions } from "./actions.js";
+
+async function actionReceiptSummary(target, packageRoot, taskId) {
+  const actions = await listActions(target, { packageRoot, taskId });
+  const { evaluateRequiredActionReadiness } = await import("./action-readiness.js");
+  const readiness = await evaluateRequiredActionReadiness({ target, packageRoot, taskId });
+  return {
+    count: actions.length,
+    required: readiness.total,
+    verified: actions.filter((action) => action.state === "VERIFIED").length,
+    // Raw state counts are observability only; trusted completion is below.
+    trustedSatisfied: readiness.satisfied,
+    unresolvedRequired: readiness.unresolved,
+    failed: actions.filter((action) => action.state === "FAILED").length,
+    ambiguous: actions.filter((action) => action.state === "COMMIT_UNKNOWN").length,
+    pending: actions.filter((action) => !["VERIFIED", "FAILED", "CANCELLED"].includes(action.state)).length,
+    actionRefs: actions.map((action) => action.actionId),
+  };
+}
 
 /**
  * Canonical completion return statuses shared by the runtime, tests, and
@@ -424,6 +443,44 @@ export async function evaluateCompletion({
     }
   }
 
+  const actionTaskId = contract?.value?.taskId ?? taskId;
+  const durableActions = actionTaskId
+    ? await listActions(target, { packageRoot, taskId: actionTaskId })
+    : [];
+  const contractRequirements = new Set([
+    ...(contract?.value?.verification ?? []), ...(contract?.value?.successCriteria ?? []),
+  ]);
+  // Completion truth consumes the canonical action-readiness projection, not
+  // raw state labels: a forged VERIFIED label can never satisfy a required
+  // action (INV-VERIFY-02).
+  const { evaluateRequiredActionReadiness } = await import("./action-readiness.js");
+  const requiredActionReadiness = actionTaskId
+    ? await evaluateRequiredActionReadiness({ target, packageRoot, taskId: actionTaskId })
+    : { total: 0, satisfied: 0, unresolved: 0, ambiguous: 0, failed: 0, untrusted: 0, actions: [] };
+  for (const readiness of requiredActionReadiness.actions) {
+    if (readiness.status === "SATISFIED") continue;
+    const action = durableActions.find((candidate) => candidate.actionId === readiness.actionId);
+    if (
+      readiness.status === "FAILED"
+      && action?.state === "CANCELLED"
+      && action.requirement
+      && !contractRequirements.has(action.requirement)
+    ) {
+      continue;
+    }
+    const code = readiness.status === "AMBIGUOUS"
+      ? "E_ACTION_RECONCILIATION_REQUIRED"
+      : readiness.status === "UNTRUSTED"
+        ? "E_ACTION_VERIFICATION_REQUIRED"
+        : "E_ACTION_STATE_MISMATCH";
+    errors.push(issue(
+      code,
+      `Required action ${readiness.actionId} is not trusted-satisfied (${readiness.status}): ${readiness.reasons[0] ?? ""}`,
+      [taskArtifactPath(action?.taskId ?? actionTaskId, "actions")],
+      { actionId: readiness.actionId, actionState: action?.state, readiness: readiness.status },
+    ));
+  }
+
   const sortedErrors = sortIssues(errors);
   const valid = sortedErrors.length === 0;
   return {
@@ -440,6 +497,17 @@ export async function evaluateCompletion({
       status: ledger.valid ? "valid" : "invalid",
       events: ledger.events.length,
     },
+    actions: {
+      count: durableActions.length,
+      required: requiredActionReadiness.total,
+      verified: durableActions.filter((action) => action.state === "VERIFIED").length,
+      trustedSatisfied: requiredActionReadiness.satisfied,
+      unresolvedRequired: requiredActionReadiness.unresolved,
+      failed: durableActions.filter((action) => action.state === "FAILED").length,
+      ambiguous: durableActions.filter((action) => action.state === "COMMIT_UNKNOWN").length,
+      pending: durableActions.filter((action) => !["VERIFIED", "FAILED", "CANCELLED"].includes(action.state)).length,
+      actionRefs: durableActions.map((action) => action.actionId),
+    },
   };
 }
 
@@ -528,6 +596,7 @@ export async function runComplete({
       if (receipt) {
         nextReceipt = await createReceipt({
           ...receipt.value,
+          actions: await actionReceiptSummary(target, packageRoot, state.taskId),
           stateFingerprint: canonicalFingerprint(next),
           verificationCycle: next.verificationCycle ?? receipt.value.verificationCycle ?? 1,
         }, packageRoot, { target, taskId: state.taskId, authorityContext, runtimeContext });
@@ -574,6 +643,7 @@ export async function runComplete({
       next.revision = (state.revision ?? 0) + 1;
       const nextReceipt = await createReceipt({
         ...receipt.value,
+        actions: await actionReceiptSummary(target, packageRoot, state.taskId),
         stateFingerprint: canonicalFingerprint(next),
         verificationCycle: next.verificationCycle ?? receipt.value.verificationCycle ?? 1,
       }, packageRoot, { target, taskId: state.taskId, authorityContext, runtimeContext });

package/src/core/continuity-reconciliation.js

@@ -169,20 +169,25 @@ export function classifyContinuity({
   });
 }
 
-export async function reconcileContinuity({ target, packageRoot } = {}) {
+export async function reconcileContinuity({ target, packageRoot, taskId = null } = {}) {
   const [{ readWorkState }, { readContract }, repository] = await Promise.all([
     import("./work-state.js"),
     import("./contract.js"),
     import("./repository.js"),
   ]);
 
-  const state = await readWorkState(target, packageRoot);
+  const state = await readWorkState(target, { packageRoot, taskId });
   let continuityArtifact;
   try {
-    continuityArtifact = await readContinuity(target, packageRoot);
+    continuityArtifact = await readContinuity(target, { packageRoot, taskId });
   } catch (error) {
     if (error.code === "ARTIFACT_MISSING") {
-      return { ...classifyContinuity({ continuity: null, state }), path: ".forgeloop/continuity.json", present: false };
+      return {
+        ...classifyContinuity({ continuity: null, state }),
+        path: ".forgeloop/continuity.json",
+        present: false,
+        diagnosticContext: await deriveDiagnosticContextSafe({ target, packageRoot, state }),
+      };
     }
     return {
       ...baseResult("INVALID", {
@@ -197,7 +202,7 @@ export async function reconcileContinuity({ target, packageRoot } = {}) {
 
   let contractFingerprint = null;
   try {
-    const contract = await readContract(target, packageRoot);
+    const contract = await readContract(target, packageRoot, { taskId });
     contractFingerprint = contract.fingerprint;
   } catch {
     contractFingerprint = null;
@@ -220,5 +225,19 @@ export async function reconcileContinuity({ target, packageRoot } = {}) {
     present: true,
     fingerprint: continuityArtifact.fingerprint,
     continuity: continuityArtifact.value,
+    diagnosticContext: await deriveDiagnosticContextSafe({ target, packageRoot, state }),
   };
 }
+
+async function deriveDiagnosticContextSafe({ target, packageRoot, state }) {
+  try {
+    const [{ readEvents }, { deriveDiagnosticContext }] = await Promise.all([
+      import("./events.js"),
+      import("./reflection.js"),
+    ]);
+    const events = await readEvents(target, packageRoot, { taskId: state?.taskId ?? null });
+    return { present: true, ...deriveDiagnosticContext(events, state) };
+  } catch {
+    return { present: false };
+  }
+}

package/src/core/diagnostic-model.js

@@ -0,0 +1,396 @@
+import { canonicalFingerprint } from "./artifacts.js";
+import { assertFailureClass } from "./protocol.js";
+
+export const DIAGNOSTIC_SCHEMA_VERSION = 1;
+
+const LIMITS = Object.freeze({
+  observationsPerCase: 64,
+  contributorsPerCase: 64,
+  hypothesesPerCase: 32,
+  evidenceRefsPerHypothesis: 32,
+  contributorRefsPerHypothesis: 32,
+  statementLength: 4096,
+  reasonLength: 4096,
+  idLength: 128,
+});
+
+export const DIAGNOSTIC_LIMITS = LIMITS;
+
+export const OBSERVATION_KINDS = Object.freeze([
+  "CHECK_RESULT",
+  "EXECUTION_RESULT",
+  "REPOSITORY_STATE",
+  "ENVIRONMENT_STATE",
+  "DEPENDENCY_STATE",
+  "MANUAL_OBSERVATION",
+  "PROTOCOL_STATE",
+]);
+
+export const OBSERVATION_PROVENANCE = Object.freeze([
+  "FORGELOOP_EXECUTED",
+  "ACTOR_REPORTED",
+  "MANUAL_OBSERVATION",
+]);
+
+export const CONTRIBUTOR_TYPES = Object.freeze([
+  "CODE",
+  "CONFIGURATION",
+  "ARCHITECTURE",
+  "DEPENDENCY",
+  "ENVIRONMENT",
+  "DATA",
+  "TIMING",
+  "CONCURRENCY",
+  "STATE",
+  "AUTHORITY",
+  "CAPABILITY",
+  "ASSUMPTION",
+  "INTERFACE",
+  "PROCESS",
+  "EXTERNAL_SERVICE",
+  "UNKNOWN",
+]);
+
+export const CONTRIBUTOR_STATUSES = Object.freeze([
+  "OBSERVED",
+  "INFERRED",
+  "SUSPECTED",
+  "ELIMINATED",
+  "CONFIRMED_RELEVANT",
+]);
+
+export const HYPOTHESIS_STATUSES = Object.freeze([
+  "OPEN",
+  "SUPPORTED",
+  "WEAKENED",
+  "FALSIFIED",
+  "SUPERSEDED",
+  "UNRESOLVED",
+]);
+
+export const SETTLEMENT_TYPES = Object.freeze([
+  "PREDICATE",
+  "CHECK_STATUS",
+  "FAILURE_SIGNATURE_CHANGE",
+  "REQUIREMENT_STATUS",
+  "MANUAL_OBSERVATION",
+]);
+
+export const INTERVENTION_KINDS = Object.freeze([
+  "CODE_CHANGE",
+  "CONFIG_CHANGE",
+  "TEST_CHANGE",
+  "FIXTURE_CHANGE",
+  "ENVIRONMENT_CHANGE",
+  "DEPENDENCY_CHANGE",
+  "ROLLBACK",
+  "ISOLATION",
+  "INSTRUMENTATION",
+  "NO_MUTATION_EXPERIMENT",
+  "OTHER",
+]);
+
+export const DISPOSITION_TRANSITIONS = Object.freeze({
+  OPEN: ["SUPPORTED", "WEAKENED", "FALSIFIED", "SUPERSEDED", "UNRESOLVED"],
+  SUPPORTED: ["WEAKENED", "FALSIFIED", "SUPERSEDED"],
+  WEAKENED: ["SUPPORTED", "FALSIFIED", "SUPERSEDED"],
+});
+
+function invalid(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  throw error;
+}
+
+export function assertDiagnosticId(value, label) {
+  if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value)) {
+    invalid("E_DIAGNOSTIC_CASE_INVALID", `${label} must match ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`);
+  }
+  return value;
+}
+
+function assertBoundedText(value, label, maxLength, code = "E_DIAGNOSTIC_CASE_INVALID") {
+  if (typeof value !== "string" || !value.trim() || value.length > maxLength) {
+    invalid(code, `${label} must be a non-empty string of at most ${maxLength} characters`);
+  }
+  return value;
+}
+
+function assertStringRefArray(value, label, maxItems, missingCode) {
+  if (!Array.isArray(value)) invalid(missingCode ?? "E_DIAGNOSTIC_CASE_INVALID", `${label} must be an array`);
+  if (value.length > maxItems) invalid("E_DIAGNOSTIC_CASE_INVALID", `${label} exceeds limit of ${maxItems}`);
+  for (const ref of value) {
+    if (typeof ref !== "string" || !ref.trim()) {
+      invalid(missingCode ?? "E_DIAGNOSTIC_CASE_INVALID", `each ${label} entry must be a non-empty string`);
+    }
+  }
+  return [...new Set(value.map((ref) => ref.trim()))];
+}
+
+export function normalizeDiagnosticText(value) {
+  return String(value).trim().replace(/\s+/gu, " ").toLowerCase();
+}
+
+export function canonicalizeDiagnosticValue(value) {
+  if (Array.isArray(value)) return [...new Set(value.map(canonicalizeDiagnosticValue))].sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value)
+        .filter(([key]) => key !== "id" && key !== "createdAt")
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, child]) => [key, canonicalizeDiagnosticValue(child)]),
+    );
+  }
+  if (typeof value === "string") return normalizeDiagnosticText(value);
+  return value;
+}
+
+export function diagnosticSemanticFingerprint({ verificationCycle, failureClass, case_ }) {
+  return canonicalFingerprint({
+    verificationCycle,
+    failureClass,
+    observations: [...case_.observations]
+      .map(({ kind, evidenceRef, statement, provenance }) => canonicalizeDiagnosticValue({ kind, evidenceRef, statement, provenance }))
+      .sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))),
+    contributors: [...case_.contributors]
+      .map(({ type, statement, basis, status }) => canonicalizeDiagnosticValue({ type, statement, basis, status }))
+      .sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))),
+    hypotheses: [...case_.hypotheses]
+      .map(({ statement, contributorRefs, evidenceRefs, settledBy }) => canonicalizeDiagnosticValue({ statement, contributorRefs, evidenceRefs, settledBy }))
+      .sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))),
+    nextSafeAction: canonicalizeDiagnosticValue(case_.nextSafeAction?.statement ?? null),
+  });
+}
+
+export function assertObservation(observation, label = "observation") {
+  if (!observation || typeof observation !== "object" || Array.isArray(observation)) {
+    invalid("E_OBSERVATION_INVALID", `${label} must be an object`);
+  }
+  assertDiagnosticId(observation.id, `${label}.id`);
+  if (!OBSERVATION_KINDS.includes(observation.kind)) {
+    invalid("E_OBSERVATION_INVALID", `${label}.kind must be one of ${OBSERVATION_KINDS.join(", ")}`);
+  }
+  assertBoundedText(observation.statement, `${label}.statement`, LIMITS.statementLength);
+  if (observation.evidenceRef !== undefined && observation.evidenceRef !== null) {
+    assertDiagnosticId(observation.evidenceRef, `${label}.evidenceRef`);
+  }
+  if (observation.provenance !== undefined && observation.provenance !== null
+    && !OBSERVATION_PROVENANCE.includes(observation.provenance)) {
+    invalid("E_OBSERVATION_INVALID", `${label}.provenance must be one of ${OBSERVATION_PROVENANCE.join(", ")}`);
+  }
+  return observation;
+}
+
+export function assertContributor(contributor, label = "contributor") {
+  if (!contributor || typeof contributor !== "object" || Array.isArray(contributor)) {
+    invalid("E_CONTRIBUTOR_INVALID", `${label} must be an object`);
+  }
+  assertDiagnosticId(contributor.id, `${label}.id`);
+  if (!CONTRIBUTOR_TYPES.includes(contributor.type)) {
+    invalid("E_CONTRIBUTOR_INVALID", `${label}.type must be one of ${CONTRIBUTOR_TYPES.join(", ")}`);
+  }
+  assertBoundedText(contributor.statement, `${label}.statement`, LIMITS.statementLength, "E_CONTRIBUTOR_INVALID");
+  assertStringRefArray(contributor.basis ?? [], `${label}.basis`, LIMITS.evidenceRefsPerHypothesis);
+  if (contributor.status !== undefined && !CONTRIBUTOR_STATUSES.includes(contributor.status)) {
+    invalid("E_CONTRIBUTOR_INVALID", `${label}.status must be one of ${CONTRIBUTOR_STATUSES.join(", ")}`);
+  }
+  return contributor;
+}
+
+export function assertSettlement(settledBy, label = "settledBy") {
+  if (!settledBy || typeof settledBy !== "object" || Array.isArray(settledBy)) {
+    invalid("E_HYPOTHESIS_SETTLEMENT_MISSING", `${label} must be an object`);
+  }
+  if (!SETTLEMENT_TYPES.includes(settledBy.type)) {
+    invalid("E_HYPOTHESIS_SETTLEMENT_MISSING", `${label}.type must be one of ${SETTLEMENT_TYPES.join(", ")}`);
+  }
+  if (settledBy.type === "CHECK_STATUS") {
+    assertDiagnosticId(settledBy.checkId, `${label}.checkId`);
+    if (typeof settledBy.expectedStatus !== "string" || !settledBy.expectedStatus) {
+      invalid("E_HYPOTHESIS_SETTLEMENT_MISSING", `${label}.expectedStatus is required for CHECK_STATUS settlement`);
+    }
+    return settledBy;
+  }
+  assertBoundedText(settledBy.statement, `${label}.statement`, LIMITS.statementLength, "E_HYPOTHESIS_SETTLEMENT_MISSING");
+  return settledBy;
+}
+
+export function assertHypothesis(hypothesis, label = "hypothesis") {
+  if (!hypothesis || typeof hypothesis !== "object" || Array.isArray(hypothesis)) {
+    invalid("E_HYPOTHESIS_INVALID", `${label} must be an object`);
+  }
+  assertDiagnosticId(hypothesis.id, `${label}.id`);
+  assertBoundedText(hypothesis.statement, `${label}.statement`, LIMITS.statementLength, "E_HYPOTHESIS_INVALID");
+  assertStringRefArray(
+    hypothesis.contributorRefs ?? [],
+    `${label}.contributorRefs`,
+    LIMITS.contributorRefsPerHypothesis,
+    "E_CONTRIBUTOR_REFERENCE_INVALID",
+  );
+  assertStringRefArray(
+    hypothesis.evidenceRefs ?? [],
+    `${label}.evidenceRefs`,
+    LIMITS.evidenceRefsPerHypothesis,
+    "E_DIAGNOSTIC_CASE_EVIDENCE_INVALID",
+  );
+  assertSettlement(hypothesis.settledBy, `${label}.settledBy`);
+  if (hypothesis.status !== undefined && hypothesis.status !== "OPEN") {
+    invalid("E_HYPOTHESIS_INVALID", `${label}.status must be OPEN when recorded in a case`);
+  }
+  return hypothesis;
+}
+
+export function assertDiagnosticCaseDetails(details) {
+  if (!details || typeof details !== "object" || Array.isArray(details)) {
+    invalid("E_DIAGNOSTIC_CASE_INVALID", "Diagnostic case details must be an object");
+  }
+  if (details.schemaVersion !== DIAGNOSTIC_SCHEMA_VERSION) {
+    invalid("E_DIAGNOSTIC_CASE_INVALID", `diagnostic case schemaVersion must be ${DIAGNOSTIC_SCHEMA_VERSION}`);
+  }
+  if (!Number.isInteger(details.verificationCycle) || details.verificationCycle < 1) {
+    invalid("E_DIAGNOSTIC_CASE_CYCLE_MISMATCH", "verificationCycle must be an integer >= 1");
+  }
+  if (!Number.isInteger(details.diagnosticRevision) || details.diagnosticRevision < 1) {
+    invalid("E_DIAGNOSTIC_CASE_INVALID", "diagnosticRevision must be an integer >= 1");
+  }
+  try {
+    assertFailureClass(details.failureClass);
+  } catch {
+    invalid("E_DIAGNOSTIC_CASE_INVALID", `invalid failureClass: ${details.failureClass}`);
+  }
+
+  if (!Array.isArray(details.observations) || details.observations.length > LIMITS.observationsPerCase) {
+    invalid("E_DIAGNOSTIC_CASE_INVALID", `observations must be an array of at most ${LIMITS.observationsPerCase}`);
+  }
+  details.observations.forEach((observation, index) => assertObservation(observation, `observations[${index}]`));
+
+  if (!Array.isArray(details.contributors) || details.contributors.length > LIMITS.contributorsPerCase) {
+    invalid("E_DIAGNOSTIC_CASE_INVALID", `contributors must be an array of at most ${LIMITS.contributorsPerCase}`);
+  }
+  details.contributors.forEach((contributor, index) => assertContributor(contributor, `contributors[${index}]`));
+
+  if (!Array.isArray(details.hypotheses)
+    || details.hypotheses.length < 1
+    || details.hypotheses.length > LIMITS.hypothesesPerCase) {
+    invalid("E_DIAGNOSTIC_CASE_INVALID", `hypotheses must contain between 1 and ${LIMITS.hypothesesPerCase} hypotheses`);
+  }
+  details.hypotheses.forEach((hypothesis, index) => assertHypothesis(hypothesis, `hypotheses[${index}]`));
+
+  const ids = [
+    ...details.observations.map((o) => o.id),
+    ...details.contributors.map((c) => c.id),
+    ...details.hypotheses.map((h) => h.id),
+  ];
+  if (new Set(ids).size !== ids.length) {
+    invalid("E_DIAGNOSTIC_CASE_INVALID", "duplicate IDs within the same diagnostic case are not allowed");
+  }
+  const observationIds = new Set(details.observations.map((o) => o.id));
+  const contributorIds = new Set(details.contributors.map((c) => c.id));
+  for (const contributor of details.contributors) {
+    for (const basis of contributor.basis ?? []) {
+      if (!observationIds.has(basis)) invalid("E_CONTRIBUTOR_REFERENCE_INVALID", `contributor ${contributor.id} references unknown observation ${basis}`);
+    }
+  }
+  for (const hypothesis of details.hypotheses) {
+    for (const ref of hypothesis.contributorRefs ?? []) {
+      if (!contributorIds.has(ref)) invalid("E_CONTRIBUTOR_REFERENCE_INVALID", `hypothesis ${hypothesis.id} references unknown contributor ${ref}`);
+    }
+  }
+
+  if (!details.nextSafeAction || typeof details.nextSafeAction !== "object"
+    || typeof details.nextSafeAction.statement !== "string" || !details.nextSafeAction.statement.trim()) {
+    invalid("E_DIAGNOSTIC_CASE_INVALID", "nextSafeAction.statement must be a non-empty string");
+  }
+  if (details.nextSafeAction.statement.length > LIMITS.statementLength) {
+    invalid("E_DIAGNOSTIC_CASE_INVALID", `nextSafeAction.statement exceeds ${LIMITS.statementLength} characters`);
+  }
+
+  if (typeof details.diagnosticFingerprint !== "string" || !/^[a-f0-9]{64}$/.test(details.diagnosticFingerprint)) {
+    invalid("E_DIAGNOSTIC_CASE_INVALID", "diagnosticFingerprint must be a SHA-256 fingerprint");
+  }
+  const computed = diagnosticSemanticFingerprint({
+    verificationCycle: details.verificationCycle,
+    failureClass: details.failureClass,
+    case_: details,
+  });
+  if (computed !== details.diagnosticFingerprint) {
+    invalid("E_DIAGNOSTIC_CASE_INVALID", "diagnosticFingerprint does not match computed semantic fingerprint");
+  }
+  if (details.previousDiagnosticFingerprint !== undefined && details.previousDiagnosticFingerprint !== null
+    && (typeof details.previousDiagnosticFingerprint !== "string" || !/^[a-f0-9]{64}$/.test(details.previousDiagnosticFingerprint))) {
+    invalid("E_DIAGNOSTIC_CASE_INVALID", "previousDiagnosticFingerprint must be a SHA-256 fingerprint or null");
+  }
+  return details;
+}
+
+export function assertInterventionDetails(details) {
+  if (!details || typeof details !== "object" || Array.isArray(details)) {
+    invalid("E_INTERVENTION_INVALID", "Intervention event details must be an object");
+  }
+  if (details.schemaVersion !== DIAGNOSTIC_SCHEMA_VERSION) {
+    invalid("E_INTERVENTION_INVALID", `intervention schemaVersion must be ${DIAGNOSTIC_SCHEMA_VERSION}`);
+  }
+  if (!Number.isInteger(details.verificationCycle) || details.verificationCycle < 1) {
+    invalid("E_INTERVENTION_INVALID", "intervention verificationCycle must be an integer >= 1");
+  }
+  const intervention = details.intervention;
+  if (!intervention || typeof intervention !== "object" || Array.isArray(intervention)) {
+    invalid("E_INTERVENTION_INVALID", "intervention.intervention must be an object");
+  }
+  assertDiagnosticId(intervention.id, "intervention.id");
+  if (!INTERVENTION_KINDS.includes(intervention.kind)) {
+    invalid("E_INTERVENTION_INVALID", `intervention.kind must be one of ${INTERVENTION_KINDS.join(", ")}`);
+  }
+  assertBoundedText(intervention.statement, "intervention.statement", LIMITS.statementLength, "E_INTERVENTION_INVALID");
+  assertStringRefArray(intervention.targets ?? [], "intervention.targets", 32);
+  const hypothesisRefs = assertStringRefArray(
+    intervention.hypothesisRefs ?? [],
+    "intervention.hypothesisRefs",
+    LIMITS.hypothesesPerCase,
+    "E_INTERVENTION_REFERENCE_INVALID",
+  );
+  if (hypothesisRefs.length === 0) {
+    invalid("E_INTERVENTION_HYPOTHESIS_MISSING", "intervention must bind to at least one hypothesis");
+  }
+  if (intervention.reversible !== undefined && typeof intervention.reversible !== "boolean") {
+    invalid("E_INTERVENTION_INVALID", "intervention.reversible must be boolean");
+  }
+  return details;
+}
+
+export function interventionSemanticFingerprint(details) {
+  const intervention = details.intervention;
+  return canonicalFingerprint({
+    kind: intervention.kind,
+    statement: normalizeDiagnosticText(intervention.statement),
+    targets: [...new Set((intervention.targets ?? []).map((target) => target.trim()))].sort(),
+    hypothesisRefs: [...new Set((intervention.hypothesisRefs ?? []).map((ref) => ref.trim()))].sort(),
+  });
+}
+
+export function assertHypothesisDispositionDetails(details) {
+  if (!details || typeof details !== "object" || Array.isArray(details)) {
+    invalid("E_HYPOTHESIS_DISPOSITION_INVALID", "Disposition event details must be an object");
+  }
+  if (details.schemaVersion !== DIAGNOSTIC_SCHEMA_VERSION) {
+    invalid("E_HYPOTHESIS_DISPOSITION_INVALID", `disposition schemaVersion must be ${DIAGNOSTIC_SCHEMA_VERSION}`);
+  }
+  if (!Number.isInteger(details.verificationCycle) || details.verificationCycle < 1) {
+    invalid("E_HYPOTHESIS_DISPOSITION_INVALID", "disposition verificationCycle must be an integer >= 1");
+  }
+  assertDiagnosticId(details.hypothesisRef, "hypothesisRef");
+  if (!HYPOTHESIS_STATUSES.includes(details.status)) {
+    invalid("E_HYPOTHESIS_DISPOSITION_INVALID", `disposition status must be one of ${HYPOTHESIS_STATUSES.join(", ")}`);
+  }
+  assertStringRefArray(
+    details.evidenceRefs ?? [],
+    "evidenceRefs",
+    LIMITS.evidenceRefsPerHypothesis,
+    "E_HYPOTHESIS_DISPOSITION_EVIDENCE_INVALID",
+  );
+  if ((details.evidenceRefs ?? []).length === 0) {
+    invalid("E_HYPOTHESIS_DISPOSITION_EVIDENCE_INVALID", "disposition requires at least one evidenceRef");
+  }
+  assertBoundedText(details.reason, "reason", LIMITS.reasonLength, "E_HYPOTHESIS_DISPOSITION_INVALID");
+  return details;
+}

package/src/core/diagnostic-projection.js

@@ -0,0 +1,51 @@
+export function diagnosticEventsForTask(events, taskId) {
+  return (events ?? []).filter((event) =>
+    (event.event === "DIAGNOSTIC_CASE_RECORDED" || event.event === "DIAGNOSIS_RECORDED")
+    && (!taskId || event.taskId === taskId));
+}
+
+function structuredProjection(event) {
+  const details = event.details ?? {};
+  return {
+    sourceModel: "STRUCTURED_DIAGNOSTIC_CASE_V1",
+    event,
+    details,
+    diagnosticCase: details,
+    informationGain: details.informationGain ?? null,
+  };
+}
+
+function legacyProjection(event) {
+  const details = event.details ?? {};
+  return {
+    sourceModel: "LEGACY_DIAGNOSIS_V1",
+    event,
+    details,
+    diagnosticCase: null,
+    informationGain: details.informationGain ?? null,
+  };
+}
+
+export function resolveCurrentCycleDiagnostic(events, taskId, verificationCycle) {
+  const candidates = diagnosticEventsForTask(events, taskId)
+    .filter((event) => {
+      const cycle = event.details?.verificationCycle;
+      return verificationCycle == null || cycle == null || cycle === verificationCycle;
+    })
+    .sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));
+
+  const structured = [...candidates].reverse().find((event) => event.event === "DIAGNOSTIC_CASE_RECORDED");
+  if (structured) return structuredProjection(structured);
+
+  const legacy = [...candidates].reverse().find((event) => event.event === "DIAGNOSIS_RECORDED");
+  if (legacy) return legacyProjection(legacy);
+
+  return null;
+}
+
+export function projectDiagnosticCases(events, taskId) {
+  return diagnosticEventsForTask(events, taskId)
+    .filter((event) => event.event === "DIAGNOSTIC_CASE_RECORDED")
+    .sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0))
+    .map((event) => ({ sequence: event.seq, at: event.at, ...event.details }));
+}