@cassiomc1/forgeloop 1.5.0 → 1.6.0

package/src/commands/record-diagnosis.js

@@ -1,11 +1,13 @@
 import { recordDiagnosis } from "../core/diagnosis.js";
+import { recordStructuredDiagnosticCase } from "../core/diagnostic-record.js";
 import { withTaskMutation } from "../core/task-command.js";
 
-export { recordDiagnosis };
+export { recordDiagnosis, recordStructuredDiagnosticCase };
 
 export async function runRecordDiagnosis({
   target,
   packageRoot,
+  file = null,
   hypothesis,
   failureClass,
   evidenceRefs = [],
@@ -15,6 +17,26 @@ export async function runRecordDiagnosis({
   taskId,
   task,
 }) {
+  if (file) {
+    const legacyFields = [hypothesis, failureClass, settledBy, nextSafeAction].some((value) => value !== undefined && value !== null)
+      || (Array.isArray(evidenceRefs) && evidenceRefs.length > 0)
+      || Boolean(evidenceRef);
+    if (legacyFields) {
+      const error = new Error("record-diagnosis accepts either --file (structured case) or legacy diagnosis fields, not both");
+      error.code = "E_INPUT_CONFLICT";
+      throw error;
+    }
+    return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "record-diagnosis", async (ctx) => {
+      return recordStructuredDiagnosticCase({
+        target,
+        packageRoot,
+        caseFile: file,
+        caseInput: null,
+        taskId: ctx?.taskId ?? null,
+      });
+    });
+  }
+
   const refs = Array.isArray(evidenceRefs) && evidenceRefs.length > 0
     ? evidenceRefs
     : (evidenceRef ? [evidenceRef] : []);
@@ -34,6 +56,20 @@ export async function runRecordDiagnosis({
 }
 
 export function formatRecordDiagnosisResult(result) {
+  if (result.diagnosticCase) {
+    const d = result.diagnosticCase;
+    return [
+      `FORGELOOP DIAGNOSTIC CASE RECORDED`,
+      `CYCLE: ${d.verificationCycle}`,
+      `REVISION: ${d.diagnosticRevision}`,
+      `FAILURE CLASS: ${d.failureClass}`,
+      `OBSERVATIONS: ${(d.observations ?? []).length}`,
+      `CONTRIBUTORS: ${(d.contributors ?? []).length}`,
+      `HYPOTHESES: ${(d.hypotheses ?? []).map((hypothesis) => hypothesis.id).join(", ")}`,
+      `NEXT SAFE ACTION: ${d.nextSafeAction?.statement ?? ""}`,
+      `FINGERPRINT: ${d.diagnosticFingerprint}`,
+    ].join("\n") + "\n";
+  }
   const d = result.diagnosis ?? result.event?.details ?? {};
   return [
     `FORGELOOP DIAGNOSIS RECORDED`,

package/src/commands/record-hypothesis-disposition.js

@@ -0,0 +1,45 @@
+import { recordHypothesisDisposition } from "../core/diagnostic-record.js";
+import { withTaskMutation } from "../core/task-command.js";
+
+export { recordHypothesisDisposition };
+
+export async function runRecordHypothesisDisposition({
+  target,
+  packageRoot,
+  hypothesis,
+  hypothesisRef = null,
+  status,
+  evidenceRefs = [],
+  evidenceRef = null,
+  reason,
+  taskId,
+  task,
+}) {
+  const refs = Array.isArray(evidenceRefs) && evidenceRefs.length > 0
+    ? evidenceRefs
+    : (evidenceRef ? [evidenceRef] : []);
+
+  return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "record-hypothesis-disposition", async (ctx) => {
+    return recordHypothesisDisposition({
+      target,
+      packageRoot,
+      hypothesisRef: hypothesis ?? hypothesisRef,
+      status,
+      evidenceRefs: refs,
+      reason,
+      taskId: ctx?.taskId ?? null,
+    });
+  });
+}
+
+export function formatRecordHypothesisDispositionResult(result) {
+  const disposition = result.disposition ?? {};
+  return [
+    "FORGELOOP HYPOTHESIS DISPOSITION RECORDED",
+    `CYCLE: ${disposition.verificationCycle}`,
+    `HYPOTHESIS: ${disposition.hypothesisRef}`,
+    `STATUS: ${disposition.status}`,
+    `EVIDENCE: ${(disposition.evidenceRefs ?? []).join(", ")}`,
+    `REASON: ${disposition.reason}`,
+  ].join("\n") + "\n";
+}

package/src/commands/record-intervention.js

@@ -0,0 +1,35 @@
+import { recordIntervention } from "../core/diagnostic-record.js";
+import { withTaskMutation } from "../core/task-command.js";
+
+export { recordIntervention };
+
+export async function runRecordIntervention({
+  target,
+  packageRoot,
+  file = null,
+  taskId,
+  task,
+}) {
+  return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "record-intervention", async (ctx) => {
+    return recordIntervention({
+      target,
+      packageRoot,
+      interventionFile: file,
+      interventionInput: null,
+      taskId: ctx?.taskId ?? null,
+    });
+  });
+}
+
+export function formatRecordInterventionResult(result) {
+  const intervention = result.intervention?.intervention ?? {};
+  return [
+    "FORGELOOP INTERVENTION RECORDED",
+    `CYCLE: ${result.intervention?.verificationCycle}`,
+    `ID: ${intervention.id}`,
+    `KIND: ${intervention.kind}`,
+    `STATEMENT: ${intervention.statement}`,
+    `HYPOTHESES: ${(intervention.hypothesisRefs ?? []).join(", ")}`,
+    result.repeatedSemanticIntervention ? "WARNING: this semantic intervention has been recorded before" : null,
+  ].filter((line) => line !== null).join("\n") + "\n";
+}

package/src/commands/reflect.js

@@ -0,0 +1,38 @@
+import { buildTaskReflection } from "../core/reflection.js";
+import { resolveTaskContext, TASK_SELECTION_MODES } from "../core/task-context.js";
+
+export { buildTaskReflection };
+
+export function formatReflectResult(result) {
+  const lines = [
+    "ForgeLoop Reflection",
+    "─".repeat(56),
+    "",
+    `Task:       ${result.taskId ?? "unknown"}`,
+    `Phase:      ${result.taskPhase ?? "UNKNOWN"}`,
+    `Status:     ${result.status}`,
+    `Cycles:     ${result.verificationCycles}`,
+    `Integrity:  ${result.integrityValid ? "VALID" : "INCONSISTENT"}`,
+    "",
+    `Hypotheses: ${result.hypotheses.created} created, ${result.hypotheses.open} open, ${result.hypotheses.supported} supported, ${result.hypotheses.weakened} weakened, ${result.hypotheses.falsified} falsified`,
+    `Interventions: ${result.interventions.count} (${result.interventions.informative} informative, ${result.interventions.nonInformative} non-informative)`,
+    `Oscillation: ${result.oscillation.detected ? "DETECTED" : "none"}`,
+    result.signals.length > 0 ? `Signals: ${result.signals.join(", ")}` : "Signals: none",
+    "",
+    `Recommended protocol action: ${result.recommendedProtocolAction}`,
+  ];
+  return lines.join("\n") + "\n";
+}
+
+export async function runReflect({ target, packageRoot, taskId, task }) {
+  const resolved = await resolveTaskContext(target, {
+    packageRoot,
+    taskId: taskId ?? task,
+    selectionMode: TASK_SELECTION_MODES.READ,
+  });
+  return buildTaskReflection({
+    target,
+    packageRoot,
+    taskId: resolved?.taskId ?? null,
+  });
+}

package/src/commands/report.js

@@ -1,6 +1,14 @@
 import { evaluateReport } from "../core/report.js";
+import { withResolvedTask } from "../core/task-command.js";
 
-export { evaluateReport as runReport };
+export async function runReport(options = {}) {
+  const target = options.target;
+  const packageRoot = options.packageRoot;
+  const taskId = options.taskId ?? options.task ?? null;
+  return withResolvedTask(target, { taskId, packageRoot }, async (ctx) => {
+    return evaluateReport({ ...options, taskId: ctx?.taskId ?? null });
+  });
+}
 
 export function formatReportResult(result) {
   const lines = ["ForgeLoop Compliance"];

package/src/commands/run-action.js

@@ -0,0 +1,18 @@
+import { executeDurableAction } from "../core/action-execution.js";
+import { withTaskMutation } from "../core/task-command.js";
+
+export async function runAction({ target, packageRoot, taskId, actionId, capability,
+  effectClass, actionTarget, idempotencyKey, requirement, requiredForCompletion,
+  argv, approvalId, timeoutMs, authorityContext }) {
+  return withTaskMutation(target, { taskId, packageRoot }, "run-action", async (ctx) =>
+    executeDurableAction({ target, packageRoot, taskId: ctx.taskId, argv, approvalId, timeoutMs,
+      authorityContext, input: { actionId, capability, effectClass, target: actionTarget,
+        operation: argv.join(" ").slice(0, 512), idempotencyKey,
+        requirement: requirement ?? null, requiredForCompletion: Boolean(requiredForCompletion) } }));
+}
+
+export function formatRunActionResult(result) {
+  return ["FORGELOOP ACTION EXECUTED", `action: ${result.action.actionId}`,
+    `state: ${result.action.state}`, `execution: ${result.execution.executionId}`,
+    `exit code: ${result.execution.exitCode ?? "not-started"}`, ""].join("\n");
+}

package/src/commands/trace.js

@@ -0,0 +1,34 @@
+import { buildTaskTrace } from "../core/trace.js";
+import { resolveTaskContext, TASK_SELECTION_MODES } from "../core/task-context.js";
+
+export { buildTaskTrace };
+
+export function formatTraceResult(result) {
+  return [
+    `FORGELOOP TRACE: ${result.task.id ?? "unknown"}`,
+    `PHASE: ${result.task.phase ?? "UNKNOWN"}`,
+    `SNAPSHOT: ${result.snapshot.consistent ? "CONSISTENT" : "INCONSISTENT"} (ledger seq ${result.snapshot.ledgerTailSequence})`,
+    `INTEGRITY: ${result.integrity.valid ? "VALID" : "INCONSISTENT"}`,
+    `HISTORY QUALITY: ${result.historyQuality.level}`,
+    `EVENTS: ${result.events.length}`,
+    `CHECKS: ${result.checks.map((check) => `${check.id}=${check.currentResult} (${check.attemptCount} attempts)`).join(", ") || "none"}`,
+    `DIAGNOSTIC CASES: ${result.diagnostics.cases.length}`,
+    `INTERVENTIONS: ${result.diagnostics.interventions.length}`,
+    `DISPOSITIONS: ${result.diagnostics.dispositions.length}`,
+    "",
+    "Use --json for the full structured trace.",
+  ].join("\n") + "\n";
+}
+
+export async function runTrace({ target, packageRoot, taskId, task }) {
+  const resolved = await resolveTaskContext(target, {
+    packageRoot,
+    taskId: taskId ?? task,
+    selectionMode: TASK_SELECTION_MODES.READ,
+  });
+  return buildTaskTrace({
+    target,
+    packageRoot,
+    taskId: resolved?.taskId ?? null,
+  });
+}

package/src/commands/validate-protocol.js

@@ -111,21 +111,29 @@ export async function runValidateProtocol({
   await validateLoaded(loaded.find((item) => item.label === "receipt"), "execution-receipt", async (value) => validateReceipt(value, packageRoot));
   await validateLoaded(loaded.find((item) => item.label === "continuity"), "continuity", async (value) => assertContinuitySemantics(value));
   for (const [value, artifactPath] of [
-    [state, stateFile],
-    [receipt, receiptFile],
+    [state, effectiveStateFile],
+    [receipt, effectiveReceiptFile],
   ]) {
     if (!value) continue;
-    const provenanceErrors = await validateChecksExecutionProvenance(value.checks, {
-      target,
-      packageRoot,
-      taskId: value.taskId,
-      artifactPath,
-    });
-    schemaErrors.push(...provenanceErrors.map((error) => ({
-      ...error,
-      message: `Command provenance validation failed: ${error.message}`,
-      artifacts: [artifactPath, ...(error.artifacts ?? [])],
-    })));
+    try {
+      // The shared validator returns the resolved execution records when all
+      // command checks are valid and throws a canonical artifact error when a
+      // binding is invalid. Do not mistake those successful records for
+      // validation errors (which previously made task-scoped validation fail
+      // with an undefined localeCompare value).
+      await validateChecksExecutionProvenance(value.checks, {
+        target,
+        packageRoot,
+        taskId: value.taskId,
+        artifactPath,
+      });
+    } catch (error) {
+      schemaErrors.push({
+        code: error.code ?? "E_EXECUTION_REF_INVALID",
+        message: `Command provenance validation failed: ${error.message}`,
+        artifacts: [artifactPath, ...(error.artifacts ?? [])].filter(Boolean),
+      });
+    }
   }
   for (const item of loaded.filter((candidate) => candidate.label.startsWith("task brief:"))) {
     await validateLoaded(item, "task-brief", async (value) => validateTaskBrief(value, packageRoot));

package/src/core/action-authorization.js

@@ -0,0 +1,106 @@
+import { readAction, transitionAuthorizedAction } from "./actions.js";
+import { loadPolicyIdentity } from "./policy-engine.js";
+import { evaluateActionCapability } from "./capability-policy.js";
+import {
+  E_ACTION_AUTHORIZATION_INVALID,
+  E_ACTION_INVALID,
+  E_ACTION_STATE_MISMATCH,
+} from "./error-codes.js";
+
+function actionAuthorizationError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+/**
+ * Canonical durable-action authorization.
+ *
+ * AUTHORIZED can only be produced here, after:
+ * - the action is PROPOSED with a known identity;
+ * - the capability policy, policy lock, and task policy snapshot agree
+ *   (loadPolicyIdentity);
+ * - the capability decision is satisfied (ALLOW / trusted host authority /
+ *   fresh HOST_ATTESTED approval);
+ * - complete policy-bound evidence is appended to the ledger event
+ *   (INV-AUTH-01, INV-AUTH-02).
+ *
+ * `authorityContext` must be supplied out-of-band by a trusted host boundary;
+ * actor-controlled input can never mint it.
+ */
+export async function authorizeAction({
+  target,
+  packageRoot,
+  taskId,
+  actionId,
+  approvalId,
+  authorityContext,
+}) {
+  const action = await readAction(target, { packageRoot, taskId, actionId });
+
+  if (action.state !== "PROPOSED") {
+    throw actionAuthorizationError(
+      E_ACTION_STATE_MISMATCH,
+      `action ${actionId} must be PROPOSED before authorization`,
+    );
+  }
+
+  const policyIdentity = await loadPolicyIdentity(target, packageRoot, taskId);
+
+  if (policyIdentity.status !== "VALID") {
+    throw actionAuthorizationError(
+      policyIdentity.code ?? E_ACTION_AUTHORIZATION_INVALID,
+      "current capability policy is not bound to a valid task policy epoch",
+    );
+  }
+
+  const capability = await evaluateActionCapability({
+    target,
+    packageRoot,
+    action,
+    authorityContext,
+    approval: approvalId ? { approvalId } : undefined,
+  });
+
+  if (!capability.allowed) {
+    throw actionAuthorizationError(
+      capability.reasonCode ?? E_ACTION_INVALID,
+      `capability ${action.capability} is not authorized: ${capability.decision}`,
+    );
+  }
+
+  const authorization = {
+    capabilityDecision: capability.decision,
+    capabilityPolicyFingerprint: capability.policyFingerprint,
+    policyLockDigest: policyIdentity.lockDigest,
+    taskPolicyDigest: policyIdentity.taskPolicyDigest,
+  };
+
+  // Decision-specific mandatory evidence (INV-AUTH-02).
+  if (capability.approval) {
+    authorization.approvalId = capability.approval.approvalId;
+    authorization.approvalFingerprint = capability.approval.approvalFingerprint;
+    authorization.authorityKind = capability.approval.authorityKind;
+    authorization.authorityRef = capability.approval.authorityRef;
+  } else if (capability.authority) {
+    authorization.authorityKind = capability.authority.authorityKind;
+    authorization.authorityRef = capability.authority.authorityRef;
+  }
+
+  const next = await transitionAuthorizedAction(target, {
+    packageRoot,
+    taskId,
+    actionId: action.actionId,
+    expectedRevision: action.revision,
+    expectedFingerprint: action.actionFingerprint,
+    details: {
+      ...authorization,
+      actionFingerprint: action.actionFingerprint,
+    },
+  });
+
+  return {
+    action: next,
+    authorization,
+  };
+}

package/src/core/action-constants.js

@@ -0,0 +1,86 @@
+export const ACTION_EFFECT_CLASSES = Object.freeze([
+  "READ_ONLY",
+  "REVERSIBLE_WRITE",
+  "IRREVERSIBLE_WRITE",
+  "EXTERNAL_PUBLICATION",
+  "DESTRUCTIVE",
+]);
+
+export const ACTION_STATES = Object.freeze([
+  "PROPOSED",
+  "AUTHORIZED",
+  "STARTED",
+  "COMMITTED",
+  "VERIFIED",
+  "FAILED",
+  "COMMIT_UNKNOWN",
+  "CANCELLED",
+]);
+
+export const ACTION_PROVENANCE = Object.freeze([
+  "FORGELOOP_EXECUTED",
+  "HOST_ATTESTED",
+  "CALLER_REPORTED",
+  // Retained for backward compatibility with v1.6.0 artifacts. Public CLI
+  // surfaces no longer mint this provenance because caller input is not host
+  // authority.
+  "HOST_REPORTED",
+  "EXTERNAL_OBSERVED",
+]);
+
+export const TRUSTED_ACTION_PROVENANCE = Object.freeze([
+  "FORGELOOP_EXECUTED",
+  "HOST_ATTESTED",
+]);
+
+export const ACTION_CAPABILITIES = Object.freeze([
+  "filesystem.read",
+  "filesystem.write",
+  "process.execute",
+  "dependency.install",
+  "network.read",
+  "network.write",
+  "repository.commit",
+  "repository.push",
+  "repository.pull_request",
+  "external.publish",
+  "external.delete",
+  "deployment.execute",
+]);
+
+export const CAPABILITY_DECISIONS = Object.freeze([
+  "ALLOW",
+  "DENY",
+  "REQUIRE_AUTHORITY",
+  "REQUIRE_APPROVAL",
+]);
+
+export const APPROVAL_STATUSES = Object.freeze(["PENDING", "APPROVED", "REJECTED"]);
+
+export const APPROVAL_DECISIONS = Object.freeze(["APPROVED", "REJECTED"]);
+
+export const APPROVAL_AUTHORITY_KINDS = Object.freeze(["CALLER_ACKNOWLEDGED", "HOST_ATTESTED"]);
+
+export const RECONCILIATION_OUTCOMES = Object.freeze([
+  "COMMITTED",
+  "NOT_COMMITTED",
+  "UNKNOWN",
+]);
+
+export const SIDE_EFFECTING_EFFECT_CLASSES = Object.freeze(
+  ACTION_EFFECT_CLASSES.filter((effectClass) => effectClass !== "READ_ONLY"),
+);
+
+// States whose semantics are security-relevant: entering them must be owned
+// by a canonical core service, never by a generic caller-controlled surface.
+export const ACTION_SECURITY_SENSITIVE_STATES = Object.freeze([
+  "AUTHORIZED",
+  "VERIFIED",
+]);
+
+export const COMMIT_UNKNOWN_RESULT_CODES = Object.freeze([
+  "IDEMPOTENCY_PROTECTED",
+  "RECONCILED_COMMITTED",
+  "RECONCILED_NOT_COMMITTED",
+  "AMBIGUOUS",
+]);

package/src/core/action-execution.js

@@ -0,0 +1,105 @@
+import { proposeAction, transitionAction } from "./actions.js";
+import { actionRequiresIdempotency } from "./action-model.js";
+import { authorizeAction } from "./action-authorization.js";
+import {
+  prepareCommandExecution,
+  runPreparedCommandExecution,
+} from "./prepared-execution.js";
+
+function actionExecutionError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function startedExecutionOutcome(action, execution) {
+  if (execution.status === "passed") return "COMMITTED";
+  if (!actionRequiresIdempotency(action.effectClass)) return "FAILED";
+  if (execution.termination === "spawn-error") return "FAILED";
+  return "COMMIT_UNKNOWN";
+}
+
+/**
+ * Execute a durable side-effecting action.
+ *
+ * Ordering is the security contract (INV-EXEC-01):
+ *   propose -> prepare (deterministic pre-launch checks, no durable write)
+ *           -> authorize (policy-bound AUTHORIZED)
+ *           -> ACTION_STARTED (last protocol mutation before launch)
+ *           -> exact-argv launch (INV-EXEC-02 conservative outcomes).
+ */
+export async function executeDurableAction({
+  target, packageRoot, taskId, input, argv, approvalId, authorityContext, runtimeContext, timeoutMs,
+}) {
+  if (!Array.isArray(argv) || argv.length === 0) {
+    throw actionExecutionError("E_ACTION_INVALID", "run-action requires exact argv after --");
+  }
+  const proposed = await proposeAction(target, { packageRoot, taskId, input: {
+    ...input,
+    provenance: "FORGELOOP_EXECUTED",
+  } });
+  const action = proposed.action;
+  if (action.state === "COMMIT_UNKNOWN") {
+    throw actionExecutionError("E_ACTION_RECONCILIATION_REQUIRED", `action ${action.actionId} must be reconciled before retry`);
+  }
+  if (action.state !== "PROPOSED") {
+    throw actionExecutionError("E_ACTION_STATE_MISMATCH", `action ${action.actionId} is already ${action.state}`);
+  }
+
+  // Deterministic pre-launch checks. Any failure here leaves the action
+  // PROPOSED with no ACTION_STARTED event and no ambiguity about whether the
+  // external effect may have happened.
+  const prepared = await prepareCommandExecution({
+    target,
+    taskId,
+    argv,
+    details: { requirement: input.requirement ?? null },
+    authorityContext,
+    runtimeContext,
+  });
+
+  const { action: authorized, authorization } = await authorizeAction({
+    target, packageRoot, taskId, actionId: action.actionId,
+    approvalId, authorityContext,
+  });
+  const started = await transitionAction(target, {
+    packageRoot, taskId, actionId: action.actionId, to: "STARTED",
+    expectedRevision: authorized.revision, expectedFingerprint: action.actionFingerprint,
+  });
+  let execution;
+  try {
+    execution = await runPreparedCommandExecution({
+      target, packageRoot, taskId, checkId: `action:${action.actionId}`,
+      requirement: input.requirement ?? `durable action ${action.actionId}`,
+      prepared, timeoutMs,
+    });
+  } catch (error) {
+    // Persistence uncertainty after the launch boundary can never downgrade a
+    // side effect to FAILED: recover to COMMIT_UNKNOWN instead.
+    const to = actionRequiresIdempotency(action.effectClass) ? "COMMIT_UNKNOWN" : "FAILED";
+    await transitionAction(target, {
+      packageRoot, taskId, actionId: action.actionId, to,
+      expectedRevision: started.revision,
+      details: {
+        reason: to === "COMMIT_UNKNOWN"
+          ? "execution outcome could not be proven after action start"
+          : "process did not launch",
+        ...(to === "COMMIT_UNKNOWN" ? { commitResultCode: "AMBIGUOUS" } : {}),
+      },
+    });
+    throw error;
+  }
+  const to = startedExecutionOutcome(action, execution.execution);
+  const result = await transitionAction(target, {
+    packageRoot, taskId, actionId: action.actionId, to,
+    expectedRevision: started.revision,
+    details: {
+      evidenceRef: execution.execution.executionId,
+      ...(to === "COMMIT_UNKNOWN" ? {
+        commitResultCode: "AMBIGUOUS",
+        reason: `started execution ended via ${execution.execution.termination} without proving external commit state`,
+      } : {}),
+    },
+  });
+  return { action: result, execution: execution.execution, executionPath: execution.path, authorization };
+}