@cassiomc1/forgeloop 1.3.0 → 1.6.0

package/src/core/integration-resources.js

@@ -0,0 +1,178 @@
+import path from "node:path";
+import { runProtocolInfo } from "../commands/protocol-info.js";
+import { readContract } from "./contract.js";
+import { discoverTasks } from "./task-discovery.js";
+import { resolveTaskClaimState } from "./task-claim-state.js";
+import { runStatus } from "../commands/status.js";
+import { runContinuity } from "../commands/continuity.js";
+import { listActions, readAction } from "./actions.js";
+import { listApprovals } from "./approvals.js";
+import { buildTrajectoryMetrics } from "./trajectory-metrics.js";
+import { loadCapabilityPolicy } from "./capability-policy.js";
+import { readdir } from "node:fs/promises";
+import { readJsonArtifact } from "./artifacts.js";
+import { taskDirectory } from "./task-paths.js";
+
+/**
+ * Canonical integration resource allowlist.
+ *
+ * This is NOT a replacement for ARTIFACT_REGISTRY: the artifact registry
+ * describes persisted protocol artifacts; this registry describes what is
+ * safe to expose through structured integrations. Anything not listed here
+ * must never be readable through an integration transport.
+ *
+ * task/ownership is derived exclusively from resolveTaskClaimState() — the
+ * canonical claim resolver. Integrations must present these values; they
+ * must never derive them from raw artifacts such as task.json or
+ * recovery.json.
+ */
+export const INTEGRATION_RESOURCE_DEFINITIONS = Object.freeze({
+  "protocol/info": Object.freeze({
+    scope: "PROJECT",
+    description: "ForgeLoop protocol version, schema compatibility, features, and command metadata.",
+  }),
+  "project/tasks": Object.freeze({
+    scope: "PROJECT",
+    description: "All discovered tasks with canonical ownership projection fields.",
+  }),
+  "task/status": Object.freeze({
+    scope: "TASK",
+    description: "Canonical status projection for one task, including ownership fields.",
+  }),
+  "task/ownership": Object.freeze({
+    scope: "TASK",
+    description: "Canonical validated claim ownership for one task.",
+  }),
+  "task/contract": Object.freeze({
+    scope: "TASK",
+    description: "The task's current contract.",
+  }),
+  "task/continuity": Object.freeze({
+    scope: "TASK",
+    description: "Cross-harness continuity state for one task.",
+  }),
+  "task/actions": Object.freeze({ scope: "TASK", description: "Canonical durable action summaries for one task." }),
+  "task/action": Object.freeze({ scope: "TASK", description: "One canonical durable action artifact." }),
+  "task/approvals": Object.freeze({ scope: "TASK", description: "Durable approval artifacts for one task." }),
+  "task/metrics": Object.freeze({ scope: "TASK", description: "Read-only trajectory metrics for one task." }),
+  "task/evaluations": Object.freeze({ scope: "TASK", description: "Persisted trajectory evaluations for one task." }),
+  "project/capability-policy": Object.freeze({ scope: "PROJECT", description: "Project capability policy, never host authority." }),
+});
+
+function ownershipProjection(projection) {
+  return {
+    taskId: projection.taskId,
+    phase: projection.phase,
+    claimState: projection.claimState,
+    mutationAllowed: projection.mutationAllowed,
+    ownershipValid: projection.ownershipValid,
+    recoveryStatus: projection.recoveryStatus,
+    historicalWriteClaims: [...projection.historicalWriteClaims],
+    effectiveWriteClaims: [...projection.effectiveWriteClaims],
+    reasonCodes: [...projection.reasonCodes],
+  };
+}
+
+export async function readForgeLoopIntegrationResource(uri, {
+  projectPath = ".",
+  packageRoot = undefined,
+  packageVersion = null,
+  taskId = null,
+  actionId = null,
+} = {}) {
+  const resource = INTEGRATION_RESOURCE_DEFINITIONS[uri];
+  if (!resource) {
+    const error = new Error(`Unknown ForgeLoop integration resource: ${uri}`);
+    error.code = "E_INTEGRATION_RESOURCE_UNKNOWN";
+    throw error;
+  }
+
+  switch (uri) {
+    case "protocol/info": {
+      return { uri, data: await runProtocolInfo({ packageVersion }) };
+    }
+    case "project/tasks": {
+      const tasks = await discoverTasks(projectPath, packageRoot);
+      return {
+        uri,
+        data: {
+          count: tasks.length,
+          tasks: tasks.map((task) => ({
+            taskId: task.taskId,
+            healthy: task.healthy !== false,
+            phase: task.phase ?? null,
+            mutationAllowed: task.mutationAllowed !== false,
+          })),
+        },
+      };
+    }
+    case "task/status":
+    case "task/ownership":
+    case "task/contract":
+    case "task/continuity": {
+      if (typeof taskId !== "string" || !taskId) {
+        const error = new Error(`Resource ${uri} requires a taskId`);
+        error.code = "E_TASK_REQUIRED";
+        throw error;
+      }
+      break;
+    }
+    case "task/actions":
+    case "task/action":
+    case "task/approvals":
+    case "task/metrics":
+    case "task/evaluations": {
+      if (typeof taskId !== "string" || !taskId) {
+        const error = new Error(`Resource ${uri} requires a taskId`); error.code = "E_TASK_REQUIRED"; throw error;
+      }
+      break;
+    }
+  }
+
+  if (uri === "task/ownership") {
+    const projection = await resolveTaskClaimState(projectPath, { taskId, packageRoot });
+    return { uri, taskId, data: ownershipProjection(projection) };
+  }
+  if (uri === "task/actions") {
+    const actions = await listActions(projectPath, { packageRoot, taskId });
+    return { uri, taskId, data: { actions } };
+  }
+  if (uri === "task/action") {
+    if (!actionId) { const error = new Error("Resource task/action requires actionId"); error.code = "E_ACTION_INVALID"; throw error; }
+    return { uri, taskId, data: await readAction(projectPath, { packageRoot, taskId, actionId }) };
+  }
+  if (uri === "task/approvals") {
+    return { uri, taskId, data: { approvals: await listApprovals(projectPath, { packageRoot, taskId }) } };
+  }
+  if (uri === "task/metrics") {
+    return { uri, taskId, data: await buildTrajectoryMetrics({ target: projectPath, packageRoot, taskId }) };
+  }
+  if (uri === "task/evaluations") {
+    const dir = path.join(projectPath, taskDirectory(taskId), "evaluations");
+    let names = []; try { names = await readdir(dir); } catch { /* absent is an empty projection */ }
+    const evaluations = [];
+    for (const name of names.filter((entry) => /^eval-[A-Za-z0-9_-]+\.json$/.test(entry)).sort()) {
+      evaluations.push((await readJsonArtifact(projectPath, `${taskDirectory(taskId)}/evaluations/${name}`, "trajectory-evaluation", packageRoot)).value);
+    }
+    return { uri, taskId, data: { evaluations } };
+  }
+  if (uri === "project/capability-policy") {
+    return { uri, data: await loadCapabilityPolicy(projectPath, packageRoot) };
+  }
+  if (uri === "task/status") {
+    const result = await runStatus({ target: projectPath, packageRoot, taskId });
+    return { uri, taskId, data: result };
+  }
+  if (uri === "task/contract") {
+    try {
+      const contract = await readContract(projectPath, packageRoot, { taskId });
+      return { uri, taskId, data: contract.value };
+    } catch (error) {
+      error.message = `Resource task/contract unavailable: ${error.message}`;
+      throw error;
+    }
+  }
+  // task/continuity
+  const continuity = await runContinuity({ target: projectPath, packageRoot, taskId });
+  return { uri, taskId, data: continuity };
+}

package/src/core/next-action-model.js

@@ -16,6 +16,9 @@ export const NEXT_ACTIONS = Object.freeze({
   RECORD_DIAGNOSIS: "RECORD_DIAGNOSIS",
   CORRECT: "CORRECT",
   CHANGE_STRATEGY: "CHANGE_STRATEGY",
+  REQUIRE_NEW_DIAGNOSTIC_INFORMATION: "REQUIRE_NEW_DIAGNOSTIC_INFORMATION",
+  INTRODUCE_NEW_OBSERVATION: "INTRODUCE_NEW_OBSERVATION",
+  RECORD_INTERVENTION: "RECORD_INTERVENTION",
   ENTER_REVIEWING: "ENTER_REVIEWING",
   RECORD_TERMINAL_RESULT: "RECORD_TERMINAL_RESULT",
   PREPARE_COMPLETION: "PREPARE_COMPLETION",
@@ -31,9 +34,74 @@ export const NEXT_ACTIONS = Object.freeze({
   REPAIR_POLICY: "REPAIR_POLICY",
   RESTORE_BASELINE: "RESTORE_BASELINE",
   CONTINUE_WITH_EXISTING_BASELINE: "CONTINUE_WITH_EXISTING_BASELINE",
+  RECONCILE_CLOSURE: "RECONCILE_CLOSURE",
+  RECONCILE_ACTION: "RECONCILE_ACTION",
+  AUTHORIZE_ACTION: "AUTHORIZE_ACTION",
+  REQUEST_ACTION_APPROVAL: "REQUEST_ACTION_APPROVAL",
+  RESOLVE_ACTION_APPROVAL: "RESOLVE_ACTION_APPROVAL",
+  VERIFY_EXTERNAL_ACTION: "VERIFY_EXTERNAL_ACTION",
+  RECOVER_TASK: "RECOVER_TASK",
+  RESUME_RECOVERED_TASK: "RESUME_RECOVERED_TASK",
+  RESOLVE_RECOVERY_INCONSISTENCY: "RESOLVE_RECOVERY_INCONSISTENCY",
   NONE: "NONE",
 });
 
+export function directCommandSpec(commandId, taskId, requiredInputs = []) {
+  return {
+    commandId,
+    executable: "forgeloop",
+    subcommand: commandId,
+    argv: [commandId, `--task=${taskId}`, "--json"],
+    requiredInputs,
+  };
+}
+
+export function recoveryGuidanceForClassification(classification, taskId) {
+  if (classification === "RECOVERABLE") {
+    return {
+      nextAction: NEXT_ACTIONS.RECONCILE_CLOSURE,
+      commands: ["forgeloop reconcile-closure --task <id>"],
+      commandSpecs: [directCommandSpec("reconcile-closure", taskId, [
+        { name: "checkId", option: "--id=<contract-verification-id>" },
+        { name: "requirement", option: "--requirement=<exact-contract-verification-text>" },
+        { name: "command", option: "-- <verification-command...>" },
+      ])],
+    };
+  }
+  if (classification === "STALE" || classification === "ABANDONED") {
+    return {
+      nextAction: NEXT_ACTIONS.RECOVER_TASK,
+      commands: ["forgeloop task-recover --task <id> --acknowledge-recovery --json"],
+      commandSpecs: [directCommandSpec("task-recover", taskId, [
+        {
+          name: "acknowledgeRecovery",
+          option: "--acknowledge-recovery",
+          description: "Caller acknowledgement only; not host-attested authority.",
+        },
+      ])],
+    };
+  }
+  if (classification === "RECOVERED") {
+    return {
+      nextAction: NEXT_ACTIONS.RESUME_RECOVERED_TASK,
+      commands: ["forgeloop task-resume --task <id> --json"],
+      commandSpecs: [directCommandSpec("task-resume", taskId)],
+    };
+  }
+  if (classification === "INCONSISTENT") {
+    return {
+      nextAction: NEXT_ACTIONS.RESOLVE_RECOVERY_INCONSISTENCY,
+      commands: ["forgeloop validate-protocol --task <id> --json"],
+      commandSpecs: [directCommandSpec("validate-protocol", taskId)],
+    };
+  }
+  return {
+    nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER,
+    commands: ["forgeloop task-show --task <id> --json"],
+    commandSpecs: [directCommandSpec("task-show", taskId)],
+  };
+}
+
 export function result({
   taskId = "unknown",
   currentPhase = "RECEIVED",
@@ -44,6 +112,12 @@ export function result({
   requiredArtifacts = [],
   missingArtifacts = [],
   progress = undefined,
+  diagnosticGuidance = undefined,
+  authorityRequired = undefined,
+  hostActionRequired = undefined,
+  approvalRequired = undefined,
+  capabilityDecision = undefined,
+  reconciliationAuthorityRequired = undefined,
 }) {
   const normalizedReasons = reasons
     .map((reason) => {
@@ -76,6 +150,14 @@ export function result({
     requiredArtifacts: uniqueSorted(requiredArtifacts),
     missingArtifacts: uniqueSorted(missingArtifacts),
     ...(progress ? { progress: structuredClone(progress) } : {}),
+    ...(diagnosticGuidance ? { diagnosticGuidance: structuredClone(diagnosticGuidance) } : {}),
+    ...(authorityRequired ? { authorityRequired: structuredClone(authorityRequired) } : {}),
+    ...(hostActionRequired ? { hostActionRequired: structuredClone(hostActionRequired) } : {}),
+    ...(approvalRequired ? { approvalRequired: structuredClone(approvalRequired) } : {}),
+    ...(capabilityDecision ? { capabilityDecision: structuredClone(capabilityDecision) } : {}),
+    ...(reconciliationAuthorityRequired
+      ? { reconciliationAuthorityRequired: structuredClone(reconciliationAuthorityRequired) }
+      : {}),
   };
 }
 
@@ -126,6 +208,18 @@ export function recordDiagnosisCommandSpec() {
   };
 }
 
+export function recordInterventionCommandSpec(taskId = null) {
+  return {
+    commandId: "record-intervention",
+    executable: "forgeloop",
+    subcommand: "record-intervention",
+    argv: ["record-intervention", ...(taskId ? [`--task=${taskId}`] : [])],
+    requiredInputs: [
+      { name: "file", option: "--file=<intervention-json-path>" },
+    ],
+  };
+}
+
 export function recordTerminalResultCommandSpec(requirement) {
   const reqId = requirement.id ?? requirement;
   const type = requirement.type ?? "PUBLICATION";