@cassiomc1/forgeloop 1.5.0 → 1.6.0

package/src/core/execution.js

@@ -1,5 +1,3 @@
-import { createHash, randomUUID } from "node:crypto";
-import { spawn } from "node:child_process";
 import { readdir } from "node:fs/promises";
 import path from "node:path";
 import { ensureWithin, fileExists } from "./filesystem.js";
@@ -7,17 +5,19 @@ import {
   ARTIFACT_PATHS,
   executionArtifactPath,
   readJsonArtifact,
-  writeJsonArtifact,
 } from "./artifacts.js";
 import { taskArtifactPath, taskExecutionPath } from "./task-paths.js";
-import {
-  resolveExecutionResolution,
-  validateVerificationAuthority,
-  E_COMMAND_RESOLUTION_AMBIGUOUS,
-} from "./verification-capability.js";
 
-export { E_COMMAND_RESOLUTION_AMBIGUOUS };
-export const EXECUTION_KIND = "COMMAND_EXECUTION";
+export { E_COMMAND_RESOLUTION_AMBIGUOUS } from "./verification-capability.js";
+import {
+  prepareCommandExecution,
+  runPreparedCommandExecution,
+} from "./prepared-execution.js";
+export {
+  prepareCommandExecution,
+  runPreparedCommandExecution,
+  TERMINATION_GRACE_MS_PREPARED as TERMINATION_GRACE_MS,
+} from "./prepared-execution.js";
 
 function executionError(code, message, artifacts = []) {
   const error = new Error(message);
@@ -26,111 +26,6 @@ function executionError(code, message, artifacts = []) {
   return error;
 }
 
-function normalizeArgv(argv) {
-  if (!Array.isArray(argv) || argv.length === 0 || argv.some((item) => typeof item !== "string" || item.trim() === "")) {
-    throw executionError("E_EXECUTION_INVALID", "Execution argv must contain at least one non-empty string");
-  }
-  return [...argv];
-}
-
-function validateAuthorityBeforeLaunch({ target, taskId, argv, resolution, details, authorityContext, runtimeContext }) {
-  if (!resolution.mayInstall) return;
-  const check = {
-    kind: "command",
-    source: argv[0],
-    details: {
-      ...(details ?? {}),
-      execution: { resolution },
-    },
-  };
-  const authority = validateVerificationAuthority(check, {
-    target,
-    taskId,
-    authorityContext,
-    runtimeContext,
-  });
-  if (!authority.valid) {
-    throw executionError(authority.error.code ?? "E_INSTALLATION_AUTHORITY_REQUIRED", authority.error.message);
-  }
-}
-
-const MAX_CAPTURED_OUTPUT_BYTES = 64 * 1024;
-export const TERMINATION_GRACE_MS = 1_000;
-
-function digest(bytes) {
-  return createHash("sha256").update(bytes).digest("hex");
-}
-
-function executeProcess(argv, cwd, { timeoutMs = null } = {}) {
-  return new Promise((resolve) => {
-    let spawnError = null;
-    let timedOut = false;
-    let settled = false;
-    let timeout = null;
-    let forceTermination = null;
-    const stdout = [];
-    const stderr = [];
-    let stdoutBytes = 0;
-    let stderrBytes = 0;
-    let outputTruncated = false;
-    const capture = (chunks, chunk, total) => {
-      const available = MAX_CAPTURED_OUTPUT_BYTES - total;
-      if (available <= 0) {
-        outputTruncated = true;
-        return total;
-      }
-      if (chunk.length > available) {
-        chunks.push(chunk.subarray(0, available));
-        outputTruncated = true;
-        return total + available;
-      }
-      chunks.push(chunk);
-      return total + chunk.length;
-    };
-    const finish = (result) => {
-      if (settled) return;
-      settled = true;
-      if (timeout) clearTimeout(timeout);
-      if (forceTermination) clearTimeout(forceTermination);
-      resolve({
-        ...result,
-        timedOut,
-        stdout: Buffer.concat(stdout),
-        stderr: Buffer.concat(stderr),
-        stdoutBytes,
-        stderrBytes,
-        outputTruncated,
-      });
-    };
-    try {
-      const child = spawn(argv[0], argv.slice(1), {
-        cwd,
-        shell: false,
-        stdio: ["ignore", "pipe", "pipe"],
-      });
-      child.stdout?.on("data", (chunk) => { stdoutBytes = capture(stdout, chunk, stdoutBytes); });
-      child.stderr?.on("data", (chunk) => { stderrBytes = capture(stderr, chunk, stderrBytes); });
-      child.once("error", (error) => {
-        spawnError = error;
-      });
-      child.once("close", (exitCode, signal) => {
-        finish({ exitCode, signal, spawnError });
-      });
-      if (Number.isInteger(timeoutMs) && timeoutMs > 0) {
-        timeout = setTimeout(() => {
-          timedOut = true;
-          child.kill("SIGTERM");
-          forceTermination = setTimeout(() => {
-            child.kill("SIGKILL");
-          }, TERMINATION_GRACE_MS);
-        }, timeoutMs);
-      }
-    } catch (error) {
-      finish({ exitCode: null, signal: null, spawnError: error });
-    }
-  });
-}
-
 /**
  * Resolves where a new execution artifact should be written. Task-scoped
  * execution artifacts require a real modern task namespace (a task.json
@@ -148,6 +43,12 @@ export async function resolveExecutionArtifactPath(target, taskId, executionId)
   return executionArtifactPath(executionId);
 }
 
+/**
+ * Deterministic pre-launch preparation followed by an exact-argv launch.
+ * Kept as the canonical single-command entrypoint for non-durable callers
+ * (run-check); durable actions use the two phases separately so that
+ * ACTION_STARTED lands exactly on the launch boundary (INV-EXEC-01).
+ */
 export async function runCommandExecution({
   target,
   packageRoot,
@@ -162,87 +63,24 @@ export async function runCommandExecution({
   executionPath,
   timeoutMs = null,
 } = {}) {
-  const commandArgv = normalizeArgv(argv);
-  const resolution = await resolveExecutionResolution({
-    argv: commandArgv,
-    cwd: target,
-  });
-
-  if (
-    resolution.resolutionMode === "UNKNOWN"
-    && resolution.mayInstall === true
-    && (
-      resolution.reason === "NPM_WORKSPACE_SCRIPT_UNRESOLVED"
-      || resolution.reason === "NPM_SUBCOMMAND_AMBIGUOUS"
-      || resolution.reason === "NPM_COMMAND_UNCLASSIFIED"
-      || resolution.reason === "NPM_OPTION_VALUE_AMBIGUOUS"
-    )
-  ) {
-    const error = new Error(
-      resolution.reason === "NPM_WORKSPACE_SCRIPT_UNRESOLVED"
-        ? "npm workspace script execution cannot be proven from the current target. Run ForgeLoop against the selected workspace directory."
-        : "Command execution context could not be proven safe before launch."
-    );
-    error.code = E_COMMAND_RESOLUTION_AMBIGUOUS;
-    error.resolution = resolution;
-    throw error;
-  }
-
-  validateAuthorityBeforeLaunch({
+  const prepared = await prepareCommandExecution({
     target,
-    taskId,
-    argv: commandArgv,
-    resolution,
+    argv,
     details,
     authorityContext,
     runtimeContext,
   });
-
-  const executionId = `exec-${randomUUID()}`;
-  const startedAt = new Date().toISOString();
-  const processResult = await executeProcess(commandArgv, target, { timeoutMs });
-  const finishedAt = new Date().toISOString();
-  const execution = {
-    schemaVersion: 1,
-    protocolVersion: 1,
-    executionId,
+  return runPreparedCommandExecution({
+    target,
+    packageRoot,
     taskId,
     checkId,
     requirement,
     verificationCycle,
-    kind: EXECUTION_KIND,
-    argv: commandArgv,
-    cwd: target,
-    resolution: {
-      resolutionMode: resolution.resolutionMode,
-      mayInstall: resolution.mayInstall,
-      installer: resolution.installer,
-      tool: resolution.tool,
-    },
-    ...(resolution.dispatch ? { dispatch: resolution.dispatch } : {}),
-    startedAt,
-    finishedAt,
-    status: processResult.exitCode === 0 && !processResult.spawnError && !processResult.timedOut ? "passed" : "failed",
-    exitCode: processResult.exitCode,
-    durationMs: Math.max(0, Date.parse(finishedAt) - Date.parse(startedAt)),
-    termination: processResult.spawnError ? "spawn-error" : processResult.timedOut ? "timeout" : processResult.signal ? "signal" : "exit",
-    signal: processResult.signal ?? null,
-    stdoutSha256: digest(processResult.stdout),
-    stderrSha256: digest(processResult.stderr),
-    stdoutBytes: processResult.stdoutBytes,
-    stderrBytes: processResult.stderrBytes,
-    outputTruncated: processResult.outputTruncated,
-    ...(Number.isInteger(timeoutMs) && timeoutMs > 0 ? { timeoutMs, terminationGraceMs: TERMINATION_GRACE_MS } : {}),
-  };
-  const execPath = executionPath ?? await resolveExecutionArtifactPath(target, taskId, executionId);
-  const written = await writeJsonArtifact(target, execPath, execution, "execution", packageRoot);
-  return {
-    path: written.path,
-    execution: written.value,
-    result: processResult.spawnError
-      ? "process failed to start"
-      : `process exited with code ${processResult.exitCode}`,
-  };
+    prepared,
+    timeoutMs,
+    executionPath,
+  });
 }
 
 export async function readExecutionArtifact({ target, executionRef, packageRoot, taskId } = {}) {
@@ -287,7 +125,7 @@ export async function readExecutionArtifact({ target, executionRef, packageRoot,
 }
 
 export function validateExecutionBinding({ execution, taskId, checkId, requirement, verificationCycle = 1 } = {}) {
-  if (!execution || execution.kind !== EXECUTION_KIND
+  if (!execution || execution.kind !== "COMMAND_EXECUTION"
     || execution.taskId !== taskId
     || execution.checkId !== checkId
     || execution.requirement !== requirement

package/src/core/failure-signature.js

@@ -0,0 +1,70 @@
+import { canonicalFingerprint } from "./artifacts.js";
+
+export function computeFailureSignature({ requirement, checkKind = null, status, exitCode = null, failureToken = null }) {
+  if (!requirement || typeof requirement !== "string") {
+    const error = new Error("failure signature requires a requirement");
+    error.code = "E_FAILURE_SIGNATURE_INVALID";
+    throw error;
+  }
+  if (!status || typeof status !== "string") {
+    const error = new Error("failure signature requires a status");
+    error.code = "E_FAILURE_SIGNATURE_INVALID";
+    throw error;
+  }
+  return canonicalFingerprint({
+    requirement,
+    ...(checkKind ? { checkKind } : {}),
+    status,
+    ...(Number.isInteger(exitCode) ? { exitCode } : {}),
+    ...(failureToken ? { failureToken: String(failureToken) } : {}),
+  });
+}
+
+function failureTokenOf(details) {
+  if (typeof details?.failureToken === "string" && details.failureToken) return details.failureToken;
+  if (typeof details?.details?.failureToken === "string" && details.details.failureToken) return details.details.failureToken;
+  return null;
+}
+
+export function projectFailureSignatures({ state = null, events = [] } = {}) {
+  const byCycle = new Map();
+  const record = (cycle, details) => {
+    if (details.status !== "failed" && details.status !== "blocked") return;
+    const requirement = details.requirement ?? details.id ?? details.checkId;
+    if (!requirement) return;
+    const signature = computeFailureSignature({
+      requirement,
+      status: details.status,
+      exitCode: Number.isInteger(details.exitCode) ? details.exitCode : null,
+      failureToken: failureTokenOf(details),
+    });
+    if (!byCycle.has(cycle)) byCycle.set(cycle, new Map());
+    const cycleMap = byCycle.get(cycle);
+    if (!cycleMap.has(signature)) cycleMap.set(signature, { signature, requirements: new Set(), cycles: new Set() });
+    cycleMap.get(signature).requirements.add(requirement);
+    cycleMap.get(signature).cycles.add(cycle);
+  };
+
+  for (const event of events) {
+    if (event.event !== "VERIFICATION_RECORDED") continue;
+    record(event.details?.verificationCycle ?? 1, event.details ?? {});
+  }
+  for (const check of state?.checks ?? []) {
+    if (check.status !== "failed" && check.status !== "blocked") continue;
+    record(check.details?.verificationCycle ?? state?.verificationCycle ?? 1, check);
+  }
+
+  const signaturesByIdentity = new Map();
+  for (const [, cycleMap] of [...byCycle.entries()].sort(([a], [b]) => a - b)) {
+    for (const [signature, entry] of cycleMap) {
+      if (!signaturesByIdentity.has(signature)) signaturesByIdentity.set(signature, { signature, cycles: [], requirements: new Set() });
+      const aggregated = signaturesByIdentity.get(signature);
+      aggregated.cycles.push(...entry.cycles);
+      for (const requirement of entry.requirements) aggregated.requirements.add(requirement);
+    }
+  }
+
+  return [...signaturesByIdentity.values()]
+    .map((entry) => ({ ...entry, cycles: [...new Set(entry.cycles)].sort((a, b) => a - b), requirements: [...entry.requirements].sort() }))
+    .sort((a, b) => a.signature.localeCompare(b.signature));
+}

package/src/core/failure-surface.js

@@ -0,0 +1,57 @@
+export function projectFailureSurfaces({ state = null, events = [] } = {}) {
+  const failedRequirementsByCycle = new Map();
+  // Track every canonically verified cycle so a successful verification
+  // appears explicitly as surface: [] instead of silently disappearing.
+  const knownCycles = new Set();
+  const record = (cycle, requirement) => {
+    if (!Number.isInteger(cycle)) cycle = Number(cycle) || 1;
+    knownCycles.add(cycle);
+    if (!failedRequirementsByCycle.has(cycle)) failedRequirementsByCycle.set(cycle, new Set());
+    if (!requirement) return;
+    failedRequirementsByCycle.get(cycle).add(requirement);
+  };
+  const knowCycle = (cycle) => {
+    if (Number.isInteger(cycle)) knownCycles.add(cycle);
+  };
+
+  for (const event of events) {
+    if (event.event === "VERIFICATION_STARTED") {
+      knowCycle(event.details?.verificationCycle);
+    }
+    if (event.event !== "VERIFICATION_RECORDED") continue;
+    const d = event.details ?? {};
+    if (d.status === "failed" || d.status === "blocked") {
+      record(d.verificationCycle ?? 1, d.requirement ?? d.id ?? d.checkId);
+    } else {
+      knowCycle(d.verificationCycle);
+    }
+  }
+
+  for (const check of state?.checks ?? []) {
+    knowCycle(check.details?.verificationCycle ?? state?.verificationCycle ?? 1);
+    if (check.status !== "failed" && check.status !== "blocked") continue;
+    record(check.details?.verificationCycle ?? state?.verificationCycle ?? 1, check.requirement ?? check.id ?? check.checkId);
+  }
+  for (const cycle of knownCycles) {
+    if (!failedRequirementsByCycle.has(cycle)) failedRequirementsByCycle.set(cycle, new Set());
+  }
+
+  return [...failedRequirementsByCycle.entries()]
+    .sort(([a], [b]) => a - b)
+    .map(([verificationCycle, requirements]) => ({
+      verificationCycle,
+      surface: [...requirements].sort(),
+      size: requirements.size,
+    }));
+}
+
+export function compareFailureSurface(previous, current) {
+  if (!previous || !current) return { changed: false, direction: "UNCHANGED" };
+  const previousSet = new Set(previous);
+  const currentSet = new Set(current);
+  const removed = [...previousSet].filter((item) => !currentSet.has(item));
+  const added = [...currentSet].filter((item) => !previousSet.has(item));
+  if (added.length > 0) return { changed: true, direction: "EXPANDED", added, removed };
+  if (removed.length > 0) return { changed: true, direction: "REDUCED", added, removed };
+  return { changed: false, direction: "UNCHANGED", added, removed };
+}

package/src/core/history.js

@@ -0,0 +1,110 @@
+import { buildTaskTrace } from "./trace.js";
+
+export const HISTORY_FILTER_OPTIONS = Object.freeze([
+  "type",
+  "phase",
+  "failures",
+  "checks",
+  "since",
+  "until",
+  "limit",
+]);
+
+export async function buildTaskHistory({
+  target,
+  packageRoot,
+  taskId = null,
+  filters = {},
+} = {}) {
+  const trace = await buildTaskTrace({ target, packageRoot, taskId });
+  let events = [...trace.events];
+
+  if (filters.type) {
+    const types = String(filters.type).split(",").map((value) => value.trim()).filter(Boolean);
+    if (types.length > 0) {
+      events = events.filter((event) => types.includes(event.type) || types.includes(event.category));
+    }
+  }
+  if (filters.phase) {
+    const phases = String(filters.phase).split(",").map((value) => value.trim()).filter(Boolean);
+    if (phases.length > 0) events = events.filter((event) => phases.includes(event.phase));
+  }
+  if (filters.failures) {
+    events = events.filter((event) => event.category === "verification"
+      && ["failed", "blocked"].includes(String(event.data?.status ?? "")));
+  }
+  if (filters.checks) {
+    events = events.filter((event) => event.category === "verification");
+  }
+  if (filters.since) {
+    const since = Date.parse(filters.since);
+    if (!Number.isNaN(since)) events = events.filter((event) => event.timestamp && Date.parse(event.timestamp) >= since);
+  }
+  if (filters.until) {
+    const until = Date.parse(filters.until);
+    if (!Number.isNaN(until)) events = events.filter((event) => event.timestamp && Date.parse(event.timestamp) <= until);
+  }
+
+  let omittedEvents = 0;
+  if (Number.isInteger(filters.limit) && filters.limit >= 0 && events.length > filters.limit) {
+    omittedEvents = events.length - filters.limit;
+    events = events.slice(-filters.limit);
+  }
+
+  const checkAttempts = trace.checks.reduce(
+    (total, check) => total + check.attemptCount,
+    0,
+  );
+  const failedAttempts = trace.checks.reduce(
+    (total, check) => total + check.failedAttempts,
+    0,
+  );
+
+  return {
+    schemaVersion: 1,
+    command: "history",
+    task: trace.task,
+    snapshot: trace.snapshot,
+    summary: {
+      eventCount: events.length,
+      totalEventCount: trace.events.length,
+      checkAttemptCount: checkAttempts,
+      failedAttemptCount: failedAttempts,
+      diagnosticCaseCount: trace.diagnostics.cases.length,
+      interventionCount: trace.diagnostics.interventions.length,
+    },
+    historyQuality: trace.historyQuality,
+    integrity: trace.integrity,
+    events,
+    ...(omittedEvents > 0 ? { truncated: true, truncation: { reason: "OUTPUT_LIMIT", omittedEvents } } : {}),
+  };
+}
+
+export function formatHistoryEvent(event) {
+  const time = event.timestamp && !Number.isNaN(Date.parse(event.timestamp))
+    ? new Date(event.timestamp).toISOString().slice(11, 19)
+    : "--:--:--";
+  const lines = [`${time}  ${event.type}`];
+  if (event.summary && event.summary !== event.type) lines.push(`           ${event.summary}`);
+  if (event.data?.provenance) lines.push(`           provenance: ${event.data.provenance}`);
+  return lines.join("\n");
+}
+
+export function formatHistoryResult(result) {
+  const lines = [
+    "ForgeLoop Execution History",
+    "─".repeat(56),
+    "",
+    `Task:      ${result.task.id ?? "unknown"}`,
+    `Phase:     ${result.task.phase ?? "UNKNOWN"}`,
+    `Integrity: ${result.integrity.valid ? "VALID" : "INCONSISTENT"}`,
+    `History quality: ${result.historyQuality.level}`,
+    result.historyQuality.reasons.length > 0 ? `Reasons: ${result.historyQuality.reasons.join(", ")}` : null,
+    "",
+    ...result.events.map(formatHistoryEvent),
+  ].filter((line) => line !== null);
+  if (result.truncated) {
+    lines.push("", `[truncated: ${result.truncation.omittedEvents} earlier events omitted]`);
+  }
+  return lines.join("\n") + "\n";
+}

package/src/core/hypothesis-projection.js

@@ -0,0 +1,85 @@
+import { DISPOSITION_TRANSITIONS } from "./diagnostic-model.js";
+
+const TERMINAL_STATUSES = Object.freeze(["FALSIFIED", "SUPERSEDED", "UNRESOLVED"]);
+export const HYPOTHESIS_LEGACY_ID = "h-legacy";
+
+function canTransition(from, to) {
+  if (from === to) return false;
+  if (TERMINAL_STATUSES.includes(from)) return false;
+  return (DISPOSITION_TRANSITIONS[from] ?? []).includes(to);
+}
+
+function blankState(id) {
+  return {
+    id,
+    sourceEventSeq: null,
+    sourceCycle: null,
+    initialStatus: "OPEN",
+    currentStatus: "OPEN",
+    dispositionHistory: [],
+  };
+}
+
+export function projectHypothesisStates(events, { taskId = null } = {}) {
+  const ordered = [...events].sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));
+  const byId = new Map();
+  const invalidTransitions = [];
+
+  const ensure = (id, seq, cycle) => {
+    if (!byId.has(id)) {
+      const state = blankState(id);
+      state.sourceEventSeq = seq ?? null;
+      state.sourceCycle = cycle ?? null;
+      byId.set(id, state);
+    }
+    return byId.get(id);
+  };
+
+  for (const event of ordered) {
+    if (taskId && event.taskId && event.taskId !== taskId) continue;
+    const details = event.details ?? {};
+    if (event.event === "DIAGNOSTIC_CASE_RECORDED") {
+      for (const hypothesis of details.hypotheses ?? []) {
+        if (!hypothesis?.id) continue;
+        ensure(hypothesis.id, event.seq, details.verificationCycle);
+      }
+    } else if (event.event === "DIAGNOSIS_RECORDED") {
+      ensure(HYPOTHESIS_LEGACY_ID, event.seq, details.verificationCycle);
+    } else if (event.event === "HYPOTHESIS_DISPOSITION_RECORDED") {
+      const ref = details.hypothesisRef;
+      if (!ref || !details.status) continue;
+      const state = ensure(ref, null, null);
+      if (!canTransition(state.currentStatus, details.status)) {
+        invalidTransitions.push({
+          sequence: event.seq,
+          hypothesisRef: ref,
+          from: state.currentStatus,
+          to: details.status,
+        });
+        continue;
+      }
+      state.currentStatus = details.status;
+      state.dispositionHistory.push({
+        sequence: event.seq,
+        status: details.status,
+        evidenceRefs: [...(details.evidenceRefs ?? [])],
+        reason: details.reason ?? null,
+      });
+    }
+  }
+
+  const hypotheses = [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
+  return {
+    hypotheses,
+    openHypotheses: hypotheses.filter((hypothesis) => hypothesis.currentStatus === "OPEN").map((hypothesis) => hypothesis.id),
+    invalidTransitions,
+  };
+}
+
+export function getOpenHypotheses(projection) {
+  return projection?.openHypotheses ?? [];
+}
+
+export function getHypothesisState(projection, id) {
+  return projection?.hypotheses.find((hypothesis) => hypothesis.id === id) ?? null;
+}