@cassiomc1/forgeloop 2.0.0-rc.5 → 2.0.0

package/src/core/diagnosis.js

@@ -1,6 +1,7 @@
 import { appendProtocolEvent, validateEventLedger } from "./events.js";
 import { readWorkState, mutateWorkState } from "./work-state.js";
 import { getTaskTransaction, withTaskTransaction } from "./transaction.js";
+import { assertDiagnosisPhase, assertReviewChronology } from "./review-correction.js";
 import {
   DIAGNOSIS_INFORMATION_GAIN,
   assertDiagnosisDetails,
@@ -49,11 +50,7 @@ async function recordDiagnosisInTransaction({
     error.code = "E_STATE_MISSING";
     throw error;
   }
-  if (state.phase !== "DIAGNOSING") {
-    const error = new Error(`Recording a diagnosis requires phase DIAGNOSING, currently ${state.phase}`);
-    error.code = "E_PHASE_PREREQUISITE_MISSING";
-    throw error;
-  }
+  assertDiagnosisPhase(state);
   if (typeof state.verificationCycle !== "number" || state.verificationCycle < 1) {
     const error = new Error("Active verification cycle must be an integer >= 1");
     error.code = "E_DIAGNOSIS_INVALID";
@@ -67,6 +64,7 @@ async function recordDiagnosisInTransaction({
     error.code = first.code;
     throw error;
   }
+  assertReviewChronology(state, ledger.events);
 
   const verificationStarted = ledger.events.some(
     (e) => e.taskId === state.taskId && e.event === "VERIFICATION_STARTED",

package/src/core/diagnostic-record.js

@@ -11,6 +11,7 @@ import {
   interventionSemanticFingerprint,
 } from "./diagnostic-model.js";
 import { projectHypothesisStates, getHypothesisState } from "./hypothesis-projection.js";
+import { assertDiagnosisPhase, assertReviewChronology, requiresFailureBinding } from "./review-correction.js";
 
 const TERMINAL_STATUSES = Object.freeze(["FALSIFIED", "SUPERSEDED", "UNRESOLVED"]);
 
@@ -112,10 +113,9 @@ async function recordDiagnosticCase({
   }
 
   const state = await requireActiveState(target, { packageRoot, taskId });
-  if (state.phase !== "DIAGNOSING") {
-    throw stateError("E_PHASE_PREREQUISITE_MISSING", `Recording a structured diagnostic case requires phase DIAGNOSING, currently ${state.phase}`);
-  }
+  assertDiagnosisPhase(state);
   const ledger = await requireValidLedger(target, packageRoot, taskId);
+  assertReviewChronology(state, ledger.events);
 
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
     throw stateError("E_DIAGNOSTIC_CASE_INVALID", "diagnostic case must be a JSON object");
@@ -156,7 +156,7 @@ async function recordDiagnosticCase({
 
   // A VERIFICATION_FAILURE case must bind to failed/blocked evidence from the
   // active correction cycle so it cannot be formally valid yet semantically empty.
-  if (parsed.failureClass === "VERIFICATION_FAILURE") {
+  if (requiresFailureBinding(state, parsed.failureClass)) {
     const bindsToFailure = [
       ...parsed.hypotheses.flatMap((hypothesis) => hypothesis.evidenceRefs ?? []),
       ...(parsed.observations ?? [])

package/src/core/next-action-recovery-phases.js

@@ -4,6 +4,7 @@ import { artifactError } from "./next-action-artifacts.js";
 import { resolveCurrentCycleDiagnostic } from "./diagnostic-projection.js";
 import { buildTaskReflection } from "./reflection.js";
 import { evaluateProgress, PROGRESS_STATUS } from "./progress.js";
+import { reviewCorrectionAction } from "./next-action-review-correction.js";
 
 export async function resolveDiagnosingPhase({ target, packageRoot, normalized, state, context, eventsRel, requiredArtifacts, stateRel }) {
     const ledger = await validateEventLedger(target, packageRoot, { taskId: normalized.taskId ?? null });
@@ -65,6 +66,8 @@ export async function resolveDiagnosingPhase({ target, packageRoot, normalized,
   }
 
 export async function resolveCorrectingPhase({ target, packageRoot, normalized, state, context, requiredArtifacts }) {
+    const correction = await reviewCorrectionAction({ target, packageRoot, taskId: normalized.taskId ?? null, state, context, requiredArtifacts });
+    if (correction) return correction;
     const ledgerForCorrection = await validateEventLedger(target, packageRoot, { taskId: normalized.taskId ?? null });
     const correctionCycle = state.verificationCycle ?? 1;
     const hasStructuredCase = ledgerForCorrection.events.some(

package/src/core/next-action-review-correction.js

@@ -0,0 +1,26 @@
+import { validateEventLedger } from "./events.js";
+import { resolveCurrentCycleDiagnostic } from "./diagnostic-projection.js";
+import { hasCurrentReview, reviewFailures } from "./review-correction.js";
+import { NEXT_ACTIONS, decision, recordCheckCommandSpec, recordDiagnosisCommandSpec, result } from "./next-action-model.js";
+import { artifactError } from "./next-action-artifacts.js";
+
+export async function reviewCorrectionAction({ target, packageRoot, taskId, state, context, requiredArtifacts }) {
+  const failures = reviewFailures(state);
+  if (state.phase === "REVIEWING" && failures.length === 0) return null;
+  const ledger = await validateEventLedger(target, packageRoot, { taskId });
+  if (!ledger.valid || !hasCurrentReview(state, ledger.events)) return null;
+  if (failures.length === 0) {
+    return result({ ...context, nextAction: NEXT_ACTIONS.RECORD_VERIFICATION,
+      reasons: [artifactError("E_REVIEW_FINDING_REQUIRED", "Record an observed failed or blocked review finding before diagnosis or retry")],
+      commandSpecs: [recordCheckCommandSpec("<reviewed requirement>")], requiredArtifacts });
+  }
+  const diagnosis = resolveCurrentCycleDiagnostic(ledger.events, state.taskId, state.verificationCycle);
+  if (!diagnosis) {
+    return result({ ...context, nextAction: NEXT_ACTIONS.RECORD_DIAGNOSIS,
+      reasons: [artifactError("E_DIAGNOSIS_REQUIRED", "Diagnose the failed review finding using evidence from the current verification cycle")],
+      commandSpecs: [recordDiagnosisCommandSpec()], requiredArtifacts });
+  }
+  return state.phase === "REVIEWING"
+    ? decision(context, NEXT_ACTIONS.CORRECT, artifactError("PHASE_REVIEWING", "The diagnosed review finding requires correction"))
+    : null;
+}

package/src/core/next-action-review-phase.js

@@ -6,17 +6,18 @@ import { evaluateRequiredEvidence, classifyRequirement, terminalRequirementsForC
 import { validateEventLedger, validateCompletionRecoveryAuthorization } from "./events.js";
 import { NEXT_ACTIONS, commandFor, decision, recordTerminalResultCommandSpec, result } from "./next-action-model.js";
 import { artifactError, checkListReasons, loadArtifact, requirementsAndCoverage } from "./next-action-artifacts.js";
+import { reviewCorrectionAction } from "./next-action-review-correction.js";
 
-export async function resolveReviewingPhase({ state, context, requiredArtifacts, target, packageRoot, contract, route, preflight, authorityContext, runtimeContext, explicitTaskId, eventsRel, receiptRel, stateRel, policyRecoveryAction }) {
-    const invalidChecks = checkListReasons(state);
-    if (invalidChecks.length > 0) {
-      return result({
-        ...context,
-        nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER,
-        reasons: invalidChecks,
-        requiredArtifacts,
-      });
-    }
+export async function resolveReviewingPhase(options) {
+  const { target, packageRoot, explicitTaskId, state, context, requiredArtifacts } = options;
+  const invalidChecks = checkListReasons(state);
+  if (invalidChecks.length > 0) return result({ ...context, nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER, reasons: invalidChecks, requiredArtifacts });
+  const correction = await reviewCorrectionAction({ target, packageRoot, taskId: explicitTaskId, state, context, requiredArtifacts });
+  if (correction) return correction;
+  return resolveReviewingEvidence(options);
+}
+
+async function resolveReviewingEvidence({ state, context, requiredArtifacts, target, packageRoot, contract, route, preflight, authorityContext, runtimeContext, explicitTaskId, eventsRel, receiptRel, stateRel, policyRecoveryAction }) {
     const evidence = await requirementsAndCoverage({
       target,
       packageRoot,

package/src/core/reconcile-closure.js

@@ -13,6 +13,7 @@ import { classifyLoadedWorkState, readWorkState, mutateWorkState } from "./work-
 import { classifyRequirement } from "./evidence-readiness.js";
 import { assertDiagnosingToCorrectingTransition } from "./phase.js";
 import { resolveCurrentCycleDiagnostic } from "./diagnostic-projection.js";
+import { hasCurrentReview } from "./review-correction.js";
 
 export const RECONCILE_EVENT = "CHECKPOINT_RECONCILED";
 
@@ -214,6 +215,10 @@ async function rebindReconciliationState(target, {
     // reconcile itself records the cycle diagnosis below (provenance bound to
     // the passed evidence execution).
     const cycleDiagnosis = resolveCurrentCycleDiagnostic(ledger.events, state.taskId, state.verificationCycle ?? 1);
+    // Refresh only the repository binding for a task that entered correction
+    // from review before recording its new finding. No diagnosis is invented;
+    // advance to VERIFYING still requires one from this cycle.
+    if (state.phase === "CORRECTING" && !cycleDiagnosis && hasCurrentReview(state, ledger.events)) return state;
     if (state.phase === "DIAGNOSING" && !cycleDiagnosis) {
       return { ...state, undiagnosedDiagnosingRebind: true };
     }

package/src/core/review-correction.js

@@ -0,0 +1,51 @@
+export function isReviewCorrection(state) {
+  return state.phase === "REVIEWING"
+    || (state.phase === "CORRECTING" && state.previousPhase === "REVIEWING");
+}
+
+export function hasCurrentReview(state, events) {
+  return isReviewCorrection(state) && events.some((event) => event.taskId === state.taskId
+    && event.event === "REVIEW_STARTED"
+    && event.details?.verificationCycle === state.verificationCycle);
+}
+
+export function reviewFailures(state) {
+  return (state.checks ?? []).filter((check) => check.details?.verificationCycle === state.verificationCycle
+    && ((check.status === "failed" && check.evidenceKind === "OBSERVED")
+      || (check.status === "blocked" && check.evidenceKind === "BLOCKED")));
+}
+
+function prerequisite(code, message, artifacts = []) {
+  return Object.assign(new Error(message), { code, artifacts });
+}
+
+export function assertCheckPhase(state, status, evidenceKind, stateRel) {
+  const reviewFinding = isReviewCorrection(state) && ((status === "failed" && evidenceKind === "OBSERVED")
+    || (status === "blocked" && evidenceKind === "BLOCKED"));
+  if (state.phase !== "VERIFYING" && !reviewFinding) {
+    throw prerequisite("E_PHASE_PREREQUISITE_MISSING", `record-check requires VERIFYING or a negative review finding; found ${state.phase}`, [stateRel]);
+  }
+  return reviewFinding;
+}
+
+export function assertDiagnosisPhase(state) {
+  if (state.phase !== "DIAGNOSING" && !isReviewCorrection(state)) {
+    throw prerequisite("E_PHASE_PREREQUISITE_MISSING", `Recording a diagnosis requires DIAGNOSING or a review finding, currently ${state.phase}`);
+  }
+}
+
+export function assertReviewChronology(state, events, artifacts = []) {
+  if (isReviewCorrection(state) && !hasCurrentReview(state, events)) {
+    throw prerequisite("E_PHASE_CHRONOLOGY_INVALID", "Review findings require REVIEW_STARTED in the current verification cycle", artifacts);
+  }
+}
+
+export function requiresFailureBinding(state, failureClass) {
+  return failureClass === "VERIFICATION_FAILURE" || isReviewCorrection(state);
+}
+
+export function assertReviewRequirement(state, requirement, canonicalRequirement) {
+  if (isReviewCorrection(state) && !canonicalRequirement) {
+    throw prerequisite("E_CHECK_INVALID", `Review finding must reference a required contract or guide check: ${requirement}`);
+  }
+}

package/src/storage/capabilities.js

@@ -6,7 +6,7 @@ export function getStorageCapabilities() {
   return {
     version: 1,
     defaultBackend: "sqlite",
-    soleSQLiteWriter: false,
+    soleSQLiteWriter: true,
     sqlite: {
       format: STORAGE_FORMAT,
       formatVersion: STORAGE_FORMAT_VERSION,