@cassiomc1/forgeloop 1.3.0 → 1.6.0

package/src/core/action-readiness.js

@@ -0,0 +1,141 @@
+import { readAction, listActions } from "./actions.js";
+import { projectActionLedger } from "./action-ledger-projection.js";
+
+export const ACTION_READINESS_STATUSES = Object.freeze([
+  "SATISFIED",
+  "PENDING",
+  "FAILED",
+  "AMBIGUOUS",
+  "UNTRUSTED",
+]);
+
+function result(actionId, status, reasons, extra = {}) {
+  return {
+    actionId,
+    status,
+    reasons,
+    ...extra,
+  };
+}
+
+/**
+ * Canonical readiness projection for one durable action. Completion truth is
+ * derived here and nowhere else (INV-VERIFY-02): raw `state === "VERIFIED"`
+ * labels are never sufficient without trusted authorization and canonical
+ * verification evidence replayed from the ledger.
+ */
+export async function evaluateActionReadiness({
+  target,
+  packageRoot,
+  taskId,
+  action,
+}) {
+  const resolved = action ?? await readAction(target, { packageRoot, taskId, actionId: action?.actionId });
+  const ledger = await projectActionLedger({
+    target,
+    packageRoot,
+    taskId,
+    actionId: resolved.actionId,
+    artifact: resolved,
+  });
+
+  if (!ledger.valid) {
+    return result(resolved.actionId, "UNTRUSTED", [
+      "action ledger chronology is invalid or diverges from the artifact",
+      ...ledger.errors.map((error) => error.message),
+    ], { authorization: ledger.authorization, verification: ledger.verification });
+  }
+
+  // REQUIRE_APPROVAL authorizations bind the exact resolved approval content;
+  // any post-authorization mutation of the approval artifact must be
+  // readiness/audit-visible (INV-FINAL-APPROVAL-01).
+  const authorizationDetails = ledger.authorization.details;
+  if (authorizationDetails?.capabilityDecision === "REQUIRE_APPROVAL") {
+    try {
+      const { validateBoundApprovalFingerprint } = await import("./approvals.js");
+      await validateBoundApprovalFingerprint(target, {
+        packageRoot,
+        taskId,
+        approvalId: authorizationDetails.approvalId,
+        expectedFingerprint: authorizationDetails.approvalFingerprint,
+      });
+    } catch (error) {
+      return result(resolved.actionId, "UNTRUSTED", [
+        `bound approval integrity failed: ${error.message}`,
+      ], { authorization: ledger.authorization, verification: ledger.verification });
+    }
+  }
+
+  if (resolved.state === "COMMIT_UNKNOWN") {
+    return result(resolved.actionId, "AMBIGUOUS", [
+      "external commit state is unknown; reconcile through a trusted boundary",
+    ], { authorization: ledger.authorization, verification: ledger.verification });
+  }
+
+  if (resolved.state === "FAILED" || resolved.state === "CANCELLED") {
+    return result(resolved.actionId, "FAILED", [
+      `action is ${resolved.state}`,
+    ], { authorization: ledger.authorization, verification: ledger.verification });
+  }
+
+  if (resolved.state !== "VERIFIED") {
+    return result(resolved.actionId, "PENDING", [
+      `action is ${resolved.state}; verification requires canonical independent evidence`,
+    ], { authorization: ledger.authorization, verification: ledger.verification });
+  }
+
+  // A required action without a requirement can never be strongly verified:
+  // legacy artifacts stay readable but cannot become trusted-satisfied
+  // (INV-FINAL-VERIFY-02).
+  if (
+    resolved.requiredForCompletion
+    && (typeof resolved.requirement !== "string" || resolved.requirement.length === 0)
+  ) {
+    return result(resolved.actionId, "UNTRUSTED", [
+      "required action has no canonical requirement binding",
+    ], { authorization: ledger.authorization, verification: ledger.verification });
+  }
+
+  // VERIFIED label present: trust requires modern authorization evidence.
+  if (!ledger.authorization.valid) {
+    return result(resolved.actionId, "UNTRUSTED", [
+      "authorization evidence is invalid or legacy pre-hardening",
+    ], { authorization: ledger.authorization, verification: ledger.verification });
+  }
+
+  if (!ledger.verification.valid) {
+    return result(resolved.actionId, "UNTRUSTED", [
+      "verification evidence is missing or not canonical",
+    ], { authorization: ledger.authorization, verification: ledger.verification });
+  }
+
+  return result(resolved.actionId, "SATISFIED", [], {
+    authorization: ledger.authorization,
+    verification: ledger.verification,
+  });
+}
+
+/**
+ * Readiness summary over every required-for-completion action in a task.
+ */
+export async function evaluateRequiredActionReadiness({
+  target,
+  packageRoot,
+  taskId,
+}) {
+  const actions = await listActions(target, { packageRoot, taskId });
+  const required = actions.filter((action) => action.requiredForCompletion);
+  const evaluated = [];
+  for (const action of required) {
+    evaluated.push(await evaluateActionReadiness({ target, packageRoot, taskId, action }));
+  }
+  return {
+    total: required.length,
+    satisfied: evaluated.filter((item) => item.status === "SATISFIED").length,
+    unresolved: evaluated.filter((item) => item.status !== "SATISFIED").length,
+    ambiguous: evaluated.filter((item) => item.status === "AMBIGUOUS").length,
+    failed: evaluated.filter((item) => item.status === "FAILED").length,
+    untrusted: evaluated.filter((item) => item.status === "UNTRUSTED").length,
+    actions: evaluated,
+  };
+}

package/src/core/action-reconciliation-policy.js

@@ -0,0 +1,49 @@
+import {
+  E_ACTION_RECONCILIATION_AUTHORITY_REQUIRED,
+  E_ACTION_RECONCILIATION_EVIDENCE_INVALID,
+} from "./error-codes.js";
+import { isTrustedHostAuthorityContext } from "./capability-policy.js";
+
+/**
+ * Only these outcomes settle external commit state. They relax or resolve the
+ * COMMIT_UNKNOWN safety posture and therefore require trusted evidence;
+ * UNKNOWN is a pure observation and is always caller-recordable
+ * (INV-RECON-01, INV-RECON-02).
+ */
+export function reconciliationRequiresAuthority(outcome) {
+  return outcome === "COMMITTED" || outcome === "NOT_COMMITTED";
+}
+
+/**
+ * Validate that a reconciliation invocation may settle external state.
+ * Settlement requires:
+ * - a trusted host-boundary authority context (out-of-band), and
+ * - at least one bounded evidence reference binding the observation.
+ */
+export function assertReconciliationSettlementAllowed({ outcome, authorityContext, evidenceRefs }) {
+  if (!reconciliationRequiresAuthority(outcome)) return null;
+
+  if (!isTrustedHostAuthorityContext(authorityContext)) {
+    const error = new Error("settling external commit state requires trusted host attestation");
+    error.code = E_ACTION_RECONCILIATION_AUTHORITY_REQUIRED;
+    throw error;
+  }
+  if (
+    !Array.isArray(evidenceRefs)
+    || evidenceRefs.length === 0
+    || evidenceRefs.some((ref) => typeof ref !== "string" || !ref || ref.length > 256)
+  ) {
+    const error = new Error("settling external commit state requires bounded non-empty evidence references");
+    error.code = E_ACTION_RECONCILIATION_EVIDENCE_INVALID;
+    throw error;
+  }
+  if (typeof authorityContext.grantRef !== "string" || !authorityContext.grantRef) {
+    const error = new Error("trusted settlement authority must carry a bounded grant reference");
+    error.code = E_ACTION_RECONCILIATION_AUTHORITY_REQUIRED;
+    throw error;
+  }
+  return {
+    authorityKind: "HOST_ATTESTED",
+    authorityRef: authorityContext.grantRef,
+  };
+}

package/src/core/action-reconciliation.js

@@ -0,0 +1,66 @@
+import { readAction, transitionAction } from "./actions.js";
+import { assertReconciliationSettlementAllowed } from "./action-reconciliation-policy.js";
+import { E_ACTION_EVIDENCE_INVALID, E_ACTION_STATE_MISMATCH } from "./error-codes.js";
+
+function reconciliationError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+/**
+ * Reconcile a COMMIT_UNKNOWN action from observed external state.
+ *
+ * - UNKNOWN is a safe observation: the action remains COMMIT_UNKNOWN
+ *   (INV-RECON-01).
+ * - COMMITTED settles the ambiguity as externally committed.
+ * - NOT_COMMITTED proves the external effect did not happen and returns the
+ *   action to PROPOSED so any retry re-evaluates policy, approval, authority,
+ *   and the task policy snapshot (INV-RECON-03). Stale authorization can
+ *   never be reused.
+ *
+ * Settling outcomes (COMMITTED / NOT_COMMITTED) require trusted host
+ * attestation plus bounded evidence, supplied out-of-band (INV-RECON-02).
+ */
+export async function reconcileAction({ target, packageRoot, taskId, actionId, outcome,
+  evidenceRefs = [], observedAt = new Date().toISOString(), provenance = "EXTERNAL_OBSERVED",
+  authorityContext }) {
+  if (!["COMMITTED", "NOT_COMMITTED", "UNKNOWN"].includes(outcome)) {
+    throw reconciliationError(E_ACTION_EVIDENCE_INVALID,
+      "reconciliation outcome must be COMMITTED, NOT_COMMITTED, or UNKNOWN");
+  }
+  if (provenance !== "EXTERNAL_OBSERVED") {
+    throw reconciliationError(E_ACTION_EVIDENCE_INVALID,
+      "reconciliation provenance must be EXTERNAL_OBSERVED");
+  }
+  const settlement = assertReconciliationSettlementAllowed({ outcome, authorityContext, evidenceRefs });
+
+  const action = await readAction(target, { packageRoot, taskId, actionId });
+  if (action.state !== "COMMIT_UNKNOWN") {
+    throw reconciliationError(E_ACTION_STATE_MISMATCH,
+      `action ${actionId} is ${action.state}, not COMMIT_UNKNOWN`);
+  }
+  if (outcome === "UNKNOWN") {
+    const unchanged = await transitionAction(target, { packageRoot, taskId, actionId,
+      to: "COMMIT_UNKNOWN", expectedRevision: action.revision,
+      details: { reconciliationOutcome: outcome, evidenceRefs, observedAt, reconciliationAt: observedAt } });
+    return { action: unchanged, outcome, changed: false };
+  }
+
+  // NOT_COMMITTED deliberately returns to PROPOSED (not AUTHORIZED): the next
+  // execution must produce fresh authorization under the current policy epoch.
+  const to = outcome === "COMMITTED" ? "COMMITTED" : "PROPOSED";
+  const next = await transitionAction(target, { packageRoot, taskId, actionId, to,
+    expectedRevision: action.revision,
+    details: {
+      reconciliationOutcome: outcome,
+      evidenceRefs,
+      observedAt,
+      reconciliationAt: observedAt,
+      ...(settlement ? {
+        authorityKind: settlement.authorityKind,
+        authorityRef: settlement.authorityRef,
+      } : {}),
+    } });
+  return { action: next, outcome, changed: true };
+}

package/src/core/action-verification.js

@@ -0,0 +1,111 @@
+import { readAction, transitionVerifiedAction } from "./actions.js";
+import { readExecutionArtifact } from "./execution.js";
+import {
+  E_ACTION_STATE_MISMATCH,
+  E_ACTION_VERIFICATION_INVALID,
+} from "./error-codes.js";
+
+function verificationError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+/**
+ * Resolve canonical verification evidence for an action. For the first
+ * hardened release only ForgeLoop-validated execution artifacts qualify:
+ * an independent passed command execution bound to this task. Arbitrary
+ * strings and actor-reported observations fail closed (INV-VERIFY-01).
+ */
+async function resolveActionVerificationEvidence({
+  target,
+  packageRoot,
+  taskId,
+  action,
+  evidenceRef,
+}) {
+  if (typeof evidenceRef !== "string" || !evidenceRef || evidenceRef.length > 256) {
+    throw verificationError(E_ACTION_VERIFICATION_INVALID, "verification evidenceRef must be a bounded non-empty string");
+  }
+  let artifact;
+  try {
+    artifact = await readExecutionArtifact({
+      target,
+      packageRoot,
+      taskId,
+      executionRef: evidenceRef,
+    });
+  } catch (error) {
+    throw verificationError(
+      E_ACTION_VERIFICATION_INVALID,
+      `verification evidence does not resolve to a canonical ForgeLoop execution artifact: ${error.message}`,
+    );
+  }
+  const execution = artifact.value ?? artifact;
+  if (execution.status !== "passed") {
+    throw verificationError(E_ACTION_VERIFICATION_INVALID, "action verification evidence must be a passed execution");
+  }
+  if (execution.taskId !== taskId) {
+    throw verificationError(E_ACTION_VERIFICATION_INVALID, "verification evidence belongs to a different task");
+  }
+  // The action's own commit execution proves local completion only; it can
+  // never double as independent postcondition verification.
+  if (execution.checkId === `action:${action.actionId}`) {
+    throw verificationError(
+      E_ACTION_VERIFICATION_INVALID,
+      "action execution is commit evidence, not independent postcondition verification",
+    );
+  }
+  // Verification evidence must cover the exact immutable action requirement;
+  // a passed check for any other requirement is not postcondition evidence
+  // (INV-FINAL-VERIFY-01).
+  if (typeof action.requirement !== "string" || action.requirement.length === 0) {
+    throw verificationError(
+      E_ACTION_VERIFICATION_INVALID,
+      `action ${action.actionId} has no canonical requirement to verify`,
+    );
+  }
+  if (execution.requirement !== action.requirement) {
+    throw verificationError(
+      E_ACTION_VERIFICATION_INVALID,
+      `verification evidence covers requirement ${JSON.stringify(execution.requirement)} instead of ${JSON.stringify(action.requirement)}`,
+    );
+  }
+  return { kind: "FORGELOOP_EXECUTION", evidenceRef };
+}
+
+/**
+ * Canonical action verification (INV-VERIFY-01). VERIFIED is not a
+ * caller-reportable status: it requires a validated independent canonical
+ * evidence reference produced by e.g. run-check.
+ */
+export async function verifyAction({
+  target,
+  packageRoot,
+  taskId,
+  actionId,
+  evidenceRef,
+}) {
+  const action = await readAction(target, { packageRoot, taskId, actionId });
+  if (action.state !== "COMMITTED") {
+    throw verificationError(
+      E_ACTION_STATE_MISMATCH,
+      `action ${actionId} must be COMMITTED before verification; current state is ${action.state}`,
+    );
+  }
+  const evidence = await resolveActionVerificationEvidence({
+    target, packageRoot, taskId, action, evidenceRef,
+  });
+  return transitionVerifiedAction(target, {
+    packageRoot,
+    taskId,
+    actionId: action.actionId,
+    expectedRevision: action.revision,
+    expectedFingerprint: action.actionFingerprint,
+    details: {
+      evidenceRef: evidence.evidenceRef,
+      evidenceKind: evidence.kind,
+      verifiedAt: new Date().toISOString(),
+    },
+  });
+}