@cassiomc1/forgeloop 1.1.0 → 1.2.1

package/src/core/progress.js

@@ -0,0 +1,143 @@
+import { diagnosisEventsForTask } from "./diagnosis-model.js";
+
+export const PROGRESS_STATUS = Object.freeze({
+  ADVANCING: "ADVANCING",
+  WATCH: "WATCH",
+  STALLED: "STALLED",
+});
+
+export const PROGRESS_SIGNAL = Object.freeze({
+  NO_DIAGNOSTIC_INFORMATION_GAIN: "NO_DIAGNOSTIC_INFORMATION_GAIN",
+  REPEATED_FAILED_REQUIREMENT: "REPEATED_FAILED_REQUIREMENT",
+  REPEATED_FAILURE_WITH_SAME_DIAGNOSIS: "REPEATED_FAILURE_WITH_SAME_DIAGNOSIS",
+  HIGH_CORRECTION_CYCLE_COUNT: "HIGH_CORRECTION_CYCLE_COUNT",
+});
+
+export function diagnosisRequirements(diagnosis, checksById) {
+  if (!diagnosis) return [];
+  return [...new Set(
+    (diagnosis.evidenceRefs ?? [])
+      .map((id) => checksById.get(id)?.requirement)
+      .filter(Boolean),
+  )].sort();
+}
+
+export function evaluateProgress({ state, events = [] } = {}) {
+  const signals = [];
+  let status = PROGRESS_STATUS.ADVANCING;
+
+  if (!state) {
+    return { status, signals };
+  }
+
+  const taskEvents = Array.isArray(events) ? events.filter((e) => !state.taskId || e.taskId === state.taskId) : [];
+  const diagEvents = diagnosisEventsForTask(taskEvents, state.taskId);
+  const latestDiag = diagEvents.at(-1)?.details ?? null;
+
+  // Build checksById index for resolving requirement from check IDs
+  const checksById = new Map();
+  for (const check of state.checks ?? []) {
+    if (check.id) checksById.set(check.id, check);
+    if (check.checkId) checksById.set(check.checkId, check);
+  }
+  for (const event of taskEvents) {
+    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);
+    }
+  }
+
+  // 1. Check if latest diagnosis has NO information gain (global stall)
+  if (latestDiag && latestDiag.informationGain === "NONE") {
+    status = PROGRESS_STATUS.STALLED;
+    signals.push({
+      code: PROGRESS_SIGNAL.NO_DIAGNOSTIC_INFORMATION_GAIN,
+      severity: "BLOCKING_FOR_RETRY",
+      message: "Latest diagnosis repeats the prior hypothesis with the same evidence.",
+      verificationCycles: [latestDiag.verificationCycle],
+    });
+  }
+
+  // 2. Track failed requirements across distinct verification cycles
+  const reqCycles = new Map();
+  const checks = state.checks ?? [];
+  for (const check of checks) {
+    if (check.status === "failed" || check.status === "blocked") {
+      const cycle = check.details?.verificationCycle ?? state.verificationCycle ?? 1;
+      const req = check.requirement ?? "default";
+      if (!reqCycles.has(req)) reqCycles.set(req, new Set());
+      reqCycles.get(req).add(cycle);
+    }
+  }
+
+  // Also extract from VERIFICATION_RECORDED events
+  for (const event of taskEvents) {
+    if (event.event === "VERIFICATION_RECORDED") {
+      const details = event.details ?? {};
+      if (details.status === "failed" || details.status === "blocked") {
+        const cycle = details.verificationCycle ?? 1;
+        const req = details.requirement ?? "default";
+        if (!reqCycles.has(req)) reqCycles.set(req, new Set());
+        reqCycles.get(req).add(cycle);
+      }
+    }
+  }
+
+  const latestDiagReqs = diagnosisRequirements(latestDiag, checksById);
+
+  for (const [req, cyclesSet] of [...reqCycles.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    if (cyclesSet.size >= 3) {
+      const sortedCycles = [...cyclesSet].sort((a, b) => a - b);
+      const isLatestStalledForThisReq = latestDiag && latestDiag.informationGain === "NONE" && latestDiagReqs.includes(req);
+      if (isLatestStalledForThisReq) {
+        if (!signals.some((s) => s.code === PROGRESS_SIGNAL.REPEATED_FAILURE_WITH_SAME_DIAGNOSIS && s.requirement === req)) {
+          signals.push({
+            code: PROGRESS_SIGNAL.REPEATED_FAILURE_WITH_SAME_DIAGNOSIS,
+            severity: "BLOCKING_FOR_RETRY",
+            message: `Requirement "${req}" failed in ${cyclesSet.size} cycles and the latest diagnoses contain no new information.`,
+            verificationCycles: sortedCycles,
+            requirement: req,
+          });
+        }
+        status = PROGRESS_STATUS.STALLED;
+      } else {
+        if (!signals.some((s) => s.code === PROGRESS_SIGNAL.REPEATED_FAILED_REQUIREMENT && s.requirement === req)) {
+          signals.push({
+            code: PROGRESS_SIGNAL.REPEATED_FAILED_REQUIREMENT,
+            severity: "ADVISORY",
+            message: `Requirement "${req}" failed across ${cyclesSet.size} distinct verification cycles.`,
+            verificationCycles: sortedCycles,
+            requirement: req,
+          });
+        }
+        if (status !== PROGRESS_STATUS.STALLED) {
+          status = PROGRESS_STATUS.WATCH;
+        }
+      }
+    }
+  }
+
+  // 3. High cycle count
+  const currentCycle = state.verificationCycle ?? 1;
+  if (currentCycle >= 4) {
+    signals.push({
+      code: PROGRESS_SIGNAL.HIGH_CORRECTION_CYCLE_COUNT,
+      severity: "ADVISORY",
+      message: `Task has reached verification cycle ${currentCycle}.`,
+      verificationCycles: Array.from({ length: currentCycle }, (_, i) => i + 1),
+    });
+    if (status !== PROGRESS_STATUS.STALLED) {
+      status = PROGRESS_STATUS.WATCH;
+    }
+  }
+
+  // Sort signals deterministically
+  signals.sort((left, right) =>
+    left.code.localeCompare(right.code) || (left.requirement || "").localeCompare(right.requirement || "")
+  );
+
+  return {
+    status,
+    signals,
+  };
+}

package/src/core/protocol.js

@@ -93,6 +93,14 @@ export const FAILURE_CODES = Object.freeze([
   "E_CONTINUITY_CONTRACT_MISMATCH",
   "E_CONTINUITY_PHASE_MISMATCH",
   "E_CONTINUITY_RECONCILIATION_REQUIRED",
+  "E_DIAGNOSIS_REQUIRED",
+  "E_DIAGNOSIS_INVALID",
+  "E_DIAGNOSIS_EVIDENCE_INVALID",
+  "E_DIAGNOSIS_CYCLE_MISMATCH",
+  "E_DIAGNOSIS_NO_NEW_INFORMATION",
+  "E_PROGRESS_STALLED",
+  "E_DECISION_CRITERION_INVALID",
+  "E_DECISION_NOT_UNRESOLVED",
 ]);
 
 export const WORK_PHASES = Object.freeze([

package/src/core/settlement-model.js

@@ -0,0 +1,85 @@
+import { createHash } from "node:crypto";
+
+export function normalizeDecisionText(value) {
+  if (typeof value !== "string" || !value.trim()) {
+    const error = new Error("Decision text must be a non-empty string");
+    error.code = "E_DECISION_CRITERION_INVALID";
+    throw error;
+  }
+  return value.trim().replace(/\s+/gu, " ").toLowerCase();
+}
+
+export function decisionId(decisionText) {
+  const normalized = normalizeDecisionText(decisionText);
+  const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+  return `decision-${hash}`;
+}
+
+export function normalizeDecisionCriterionInput(input) {
+  if (!input || typeof input !== "object") {
+    const error = new Error("Decision criterion input must be an object");
+    error.code = "E_DECISION_CRITERION_INVALID";
+    throw error;
+  }
+  if (typeof input.decision !== "string" || !input.decision.trim()) {
+    const error = new Error("decision must be a non-empty string");
+    error.code = "E_DECISION_CRITERION_INVALID";
+    throw error;
+  }
+  if (typeof input.settledBy !== "string" || !input.settledBy.trim()) {
+    const error = new Error("settledBy must be a non-empty string");
+    error.code = "E_DECISION_CRITERION_INVALID";
+    throw error;
+  }
+  return {
+    decision: input.decision.trim(),
+    settledBy: input.settledBy.trim(),
+  };
+}
+
+export function assertDecisionCriterionDetails(details) {
+  if (!details || typeof details !== "object" || Array.isArray(details)) {
+    const error = new Error("Decision criterion details must be an object");
+    error.code = "E_DECISION_CRITERION_INVALID";
+    throw error;
+  }
+  if (typeof details.decision !== "string" || !details.decision.trim()) {
+    const error = new Error("Decision criterion decision must be a non-empty string");
+    error.code = "E_DECISION_CRITERION_INVALID";
+    throw error;
+  }
+  const expectedId = decisionId(details.decision);
+  if (details.decisionId !== expectedId) {
+    const error = new Error(`Decision criterion decisionId "${details.decisionId}" does not match computed "${expectedId}"`);
+    error.code = "E_DECISION_CRITERION_INVALID";
+    throw error;
+  }
+  if (typeof details.settledBy !== "string" || !details.settledBy.trim()) {
+    const error = new Error("Decision criterion settledBy must be a non-empty string");
+    error.code = "E_DECISION_CRITERION_INVALID";
+    throw error;
+  }
+  if (typeof details.contractFingerprint !== "string" || !/^[a-f0-9]{64}$/.test(details.contractFingerprint)) {
+    const error = new Error("Decision criterion contractFingerprint must be a 64-char hex string");
+    error.code = "E_DECISION_CRITERION_INVALID";
+    throw error;
+  }
+  return details;
+}
+
+export function decisionCriterionEvents(events, taskId) {
+  if (!Array.isArray(events)) return [];
+  return events.filter((e) => e.event === "DECISION_CRITERION_RECORDED" && (!taskId || e.taskId === taskId));
+}
+
+export function criterionForDecision(events, taskId, decisionText, contractFingerprint) {
+  const decId = decisionId(decisionText);
+  const taskEvents = decisionCriterionEvents(events, taskId);
+  for (let i = taskEvents.length - 1; i >= 0; i--) {
+    const details = taskEvents[i].details;
+    if (details?.decisionId === decId && (!contractFingerprint || details?.contractFingerprint === contractFingerprint)) {
+      return details;
+    }
+  }
+  return null;
+}

package/src/core/settlement.js

@@ -0,0 +1,78 @@
+import { readContract } from "./contract.js";
+import { appendProtocolEvent, validateEventLedger } from "./events.js";
+import {
+  assertDecisionCriterionDetails,
+  criterionForDecision,
+  decisionCriterionEvents,
+  decisionId,
+  normalizeDecisionCriterionInput,
+  normalizeDecisionText,
+} from "./settlement-model.js";
+
+export {
+  assertDecisionCriterionDetails,
+  criterionForDecision,
+  decisionCriterionEvents,
+  decisionId,
+  normalizeDecisionCriterionInput,
+  normalizeDecisionText,
+};
+
+export async function recordDecisionCriterion({
+  target,
+  packageRoot,
+  decision,
+  settledBy,
+  taskId = null,
+  contractPath = null,
+  eventsPath = null,
+}) {
+  const normalized = normalizeDecisionCriterionInput({ decision, settledBy });
+  const contract = await readContract(target, packageRoot, { taskId, contractPath });
+  if (!contract || !contract.value) {
+    const error = new Error("Current contract not found");
+    error.code = "E_CONTRACT_MISSING";
+    throw error;
+  }
+
+  const unresolved = contract.value.unresolvedDecisions ?? [];
+  if (!unresolved.includes(normalized.decision)) {
+    const error = new Error(`Decision "${normalized.decision}" is not present in current unresolvedDecisions`);
+    error.code = "E_DECISION_NOT_UNRESOLVED";
+    throw error;
+  }
+
+  const ledger = await validateEventLedger(target, packageRoot, { taskId: taskId ?? null, eventsPath });
+  if (!ledger.valid) {
+    const first = ledger.errors[0];
+    const error = new Error(first.message);
+    error.code = first.code;
+    throw error;
+  }
+
+  const decId = decisionId(normalized.decision);
+  const details = {
+    decision: normalized.decision,
+    decisionId: decId,
+    settledBy: normalized.settledBy,
+    contractFingerprint: contract.fingerprint,
+  };
+
+  assertDecisionCriterionDetails(details);
+
+  const event = await appendProtocolEvent(
+    target,
+    {
+      taskId: contract.value.taskId,
+      event: "DECISION_CRITERION_RECORDED",
+      details,
+    },
+    packageRoot,
+    { taskId: taskId ?? null, eventsPath },
+  );
+
+  return {
+    event,
+    criterion: details,
+  };
+}