@cassiomc1/forgeloop 0.1.14 → 0.1.16

package/src/core/execution.js

@@ -0,0 +1,185 @@
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+
+import {
+  ARTIFACT_PATHS,
+  executionArtifactPath,
+  readJsonArtifact,
+  writeJsonArtifact,
+} from "./artifacts.js";
+import {
+  classifyCommandResolution,
+  resolveExecutionResolution,
+  validateVerificationAuthority,
+  E_COMMAND_RESOLUTION_AMBIGUOUS,
+} from "./verification-capability.js";
+
+export { E_COMMAND_RESOLUTION_AMBIGUOUS };
+export const EXECUTION_KIND = "COMMAND_EXECUTION";
+
+function executionError(code, message, artifacts = []) {
+  const error = new Error(message);
+  error.code = code;
+  error.artifacts = 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);
+  }
+}
+
+function executeProcess(argv, cwd) {
+  return new Promise((resolve) => {
+    let spawnError = null;
+    try {
+      const child = spawn(argv[0], argv.slice(1), {
+        cwd,
+        shell: false,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      child.stdout?.resume();
+      child.stderr?.resume();
+      child.once("error", (error) => {
+        spawnError = error;
+      });
+      child.once("close", (exitCode) => {
+        resolve({ exitCode, spawnError });
+      });
+    } catch (error) {
+      resolve({ exitCode: null, spawnError: error });
+    }
+  });
+}
+
+export async function runCommandExecution({
+  target,
+  packageRoot,
+  taskId,
+  checkId,
+  requirement,
+  verificationCycle = 1,
+  argv,
+  details,
+  authorityContext,
+  runtimeContext,
+} = {}) {
+  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({
+    target,
+    taskId,
+    argv: commandArgv,
+    resolution,
+    details,
+    authorityContext,
+    runtimeContext,
+  });
+
+  const executionId = `exec-${randomUUID()}`;
+  const startedAt = new Date().toISOString();
+  const processResult = await executeProcess(commandArgv, target);
+  const finishedAt = new Date().toISOString();
+  const execution = {
+    schemaVersion: 1,
+    protocolVersion: 1,
+    executionId,
+    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 ? "passed" : "failed",
+    exitCode: processResult.exitCode,
+  };
+  const path = executionArtifactPath(executionId);
+  const written = await writeJsonArtifact(target, path, execution, "execution", packageRoot);
+  return {
+    path: written.path,
+    execution: written.value,
+    result: processResult.spawnError
+      ? "process failed to start"
+      : `process exited with code ${processResult.exitCode}`,
+  };
+}
+
+export async function readExecutionArtifact({ target, executionRef, packageRoot } = {}) {
+  let relativePath;
+  try {
+    relativePath = executionArtifactPath(executionRef);
+    const artifact = await readJsonArtifact(target, relativePath, "execution", packageRoot);
+    return artifact;
+  } catch (error) {
+    if (error.code === "E_EXECUTION_REF_INVALID") throw error;
+    throw executionError("E_EXECUTION_REF_INVALID", "Execution reference does not resolve to a valid ForgeLoop artifact", [relativePath ?? ARTIFACT_PATHS.executionDirectory]);
+  }
+}
+
+export function validateExecutionBinding({ execution, taskId, checkId, requirement, verificationCycle = 1 } = {}) {
+  if (!execution || execution.kind !== EXECUTION_KIND
+    || execution.taskId !== taskId
+    || execution.checkId !== checkId
+    || execution.requirement !== requirement
+    || execution.verificationCycle !== undefined && execution.verificationCycle !== verificationCycle) {
+    throw executionError("E_EXECUTION_REF_INVALID", "Execution artifact does not match the current check binding", [ARTIFACT_PATHS.executionDirectory]);
+  }
+  return execution;
+}

package/src/core/inspect.js

@@ -9,6 +9,8 @@ import { runDoctor } from "../commands/doctor.js";
 import { findProfilePath } from "./profile.js";
 import { FORGELOOP_KIT_DIR } from "./target-layout.js";
 import { trustedAuthorityConfiguration } from "./trusted-authority.js";
+import { reconcileContinuity } from "./continuity-reconciliation.js";
+import { continuityFinding, continuityIsHealthy } from "./continuity-observability.js";
 
 function profileMetadata(bytes) {
   const text = bytes.toString("utf8");
@@ -35,6 +37,7 @@ export async function inspectTarget({ target, packageRoot, contractFile = null,
   const statePath = ensureWithin(target, WORK_STATE_PATH);
   const statePresent = await fileExists(statePath);
   const state = await readAndClassifyWorkState({ target, packageRoot, contractFile });
+  const continuity = await reconcileContinuity({ target, packageRoot });
   const schemaRoot = manifest?.layoutVersion >= 2
     ? ensureWithin(target, FORGELOOP_KIT_DIR)
     : target;
@@ -69,6 +72,9 @@ export async function inspectTarget({ target, packageRoot, contractFile = null,
       });
     }
   }
+  const continuityIssue = continuityFinding(continuity);
+  if (continuityIssue) findings.push(continuityIssue);
+
   if (state.status === "INVALID") {
     findings.push({
       code: "state-invalid",
@@ -123,6 +129,7 @@ export async function inspectTarget({ target, packageRoot, contractFile = null,
       evidence: protocolEvidence,
     },
     state: { ...state, path: WORK_STATE_PATH, present: statePresent },
+    continuity,
     compatibility: {
       deprecated: true,
       agents: [],
@@ -132,6 +139,7 @@ export async function inspectTarget({ target, packageRoot, contractFile = null,
     ok: doctor.ok
       && !manifestError
       && schemaHealth.status === "valid"
-      && !["INVALID", "REVALIDATION_REQUIRED"].includes(state.status),
+      && !["INVALID", "REVALIDATION_REQUIRED"].includes(state.status)
+      && continuityIsHealthy(continuity),
   };
 }

package/src/core/installation-authority.js

@@ -0,0 +1,178 @@
+import {
+  E_AUTHORITY_INVALID,
+  E_AUTHORITY_SCOPE_MISMATCH,
+  E_INSTALLATION_AUTHORITY_REQUIRED,
+} from "./verification-constants.js";
+import { classifyCommandResolution } from "./command-resolution.js";
+import {
+  E_AUTHORITY_UNTRUSTED_SOURCE,
+  resolveTrustedAuthority,
+} from "./trusted-authority.js";
+
+export { E_AUTHORITY_UNTRUSTED_SOURCE };
+
+export function getInstallationAuthorityRef(check) {
+  return (
+    check?.details?.installationAuthorityRef
+    ?? check?.details?.authorityRef
+    ?? check?.installationAuthorityRef
+    ?? check?.authorityRef
+    ?? null
+  );
+}
+
+function normalizeToolName(toolName) {
+  if (typeof toolName !== "string") return "";
+  if (toolName.startsWith("@")) {
+    const parts = toolName.slice(1).split("@");
+    return `@${parts[0]}`;
+  }
+  return toolName.split("@")[0];
+}
+
+export function validateAuthorityGrant({ authority, taskId, type = "SOFTWARE_INSTALLATION", tool } = {}) {
+  if (!authority || typeof authority !== "object") {
+    return {
+      valid: false,
+      error: {
+        code: E_AUTHORITY_INVALID,
+        message: "Authority grant artifact is missing or invalid",
+      },
+    };
+  }
+
+  if (authority.schemaVersion !== 1 || authority.protocolVersion !== 1) {
+    return {
+      valid: false,
+      error: {
+        code: E_AUTHORITY_INVALID,
+        message: `Authority grant schema version (${authority.schemaVersion}) or protocol version (${authority.protocolVersion}) is invalid`,
+      },
+    };
+  }
+
+  if (authority.type !== type) {
+    return {
+      valid: false,
+      error: {
+        code: E_AUTHORITY_INVALID,
+        message: `Authority grant type '${authority.type}' does not match expected '${type}'`,
+      },
+    };
+  }
+
+  if (authority.status !== "AUTHORIZED") {
+    return {
+      valid: false,
+      error: {
+        code: E_AUTHORITY_INVALID,
+        message: `Authority grant is not active (status: '${authority.status}')`,
+      },
+    };
+  }
+
+  if (authority.source === "agent-self") {
+    return {
+      valid: false,
+      error: {
+        code: E_AUTHORITY_INVALID,
+        message: "Self-asserted authority grants with source 'agent-self' are not permitted",
+      },
+    };
+  }
+
+  if (!["operator", "host", "project-policy"].includes(authority.source)) {
+    return {
+      valid: false,
+      error: {
+        code: E_AUTHORITY_INVALID,
+        message: `Authority grant source '${authority.source}' is not recognized`,
+      },
+    };
+  }
+
+  if (taskId && authority.taskId && authority.taskId !== taskId) {
+    return {
+      valid: false,
+      error: {
+        code: E_AUTHORITY_INVALID,
+        message: `Authority grant taskId '${authority.taskId}' does not match current task '${taskId}'`,
+      },
+    };
+  }
+
+  if (tool && authority.scope?.tool && authority.scope.tool !== "*") {
+    const requestedNorm = normalizeToolName(tool);
+    const scopeNorm = normalizeToolName(authority.scope.tool);
+    const exactMatch = authority.scope.tool === tool
+      || tool.startsWith(`${authority.scope.tool}@`)
+      || authority.scope.tool.startsWith(`${tool}@`)
+      || requestedNorm === scopeNorm;
+
+    if (!exactMatch) {
+      return {
+        valid: false,
+        error: {
+          code: E_AUTHORITY_SCOPE_MISMATCH,
+          message: `Authority grant scope tool '${authority.scope.tool}' does not match requested verification tool '${tool}'`,
+        },
+      };
+    }
+  }
+
+  return { valid: true, error: null };
+}
+
+export function validateVerificationAuthority(check, options = {}) {
+  const canonicalResolution = check?.execution?.resolution ?? check?.details?.execution?.resolution;
+  const command = check?.details?.command
+    ?? (check?.kind === "command" && typeof check?.source === "string" && !check.source.startsWith("check:")
+      ? check.source
+      : null);
+
+  if (!canonicalResolution && (!command || typeof command !== "string")) return { valid: true, error: null };
+
+  const classification = canonicalResolution ?? classifyCommandResolution(command);
+  if (!classification.mayInstall) return { valid: true, error: null };
+
+  const authorityRef = getInstallationAuthorityRef(check);
+  if (!authorityRef) {
+    return {
+      valid: false,
+      error: {
+        code: E_INSTALLATION_AUTHORITY_REQUIRED,
+        message: `Verification command '${command}' uses installation-capable resolution (${classification.resolutionMode}) without recorded installation authority reference`,
+      },
+    };
+  }
+
+  const resolved = resolveTrustedAuthority({
+    authorityRef,
+    target: options.target,
+    trustedAuthorityFile: options.trustedAuthorityFile,
+    trustedAuthorityDir: options.trustedAuthorityDir,
+    authorities: options.authorities,
+    authority: options.authority,
+    authorityContext: options.authorityContext,
+    runtimeContext: options.runtimeContext,
+  });
+  if (!resolved.trusted) {
+    if (resolved.error?.code === E_AUTHORITY_INVALID && resolved.sourceConfigured === false) {
+      return {
+        valid: false,
+        error: {
+          code: E_INSTALLATION_AUTHORITY_REQUIRED,
+          message: "Installation-capable verification requires a host-attested authority context",
+        },
+      };
+    }
+    return { valid: false, error: resolved.error };
+  }
+
+  return validateAuthorityGrant({
+    authority: resolved.authority,
+    taskId: options.taskId,
+    type: "SOFTWARE_INSTALLATION",
+    tool: classification.tool,
+  });
+}

package/src/core/json-safety.js

@@ -23,7 +23,7 @@ export function assertJsonBytes(bytes, label = "JSON artifact", limits = JSON_LI
 }
 
 export function assertJsonLimits(value, label = "JSON artifact", limits = JSON_LIMITS) {
-  const visited = new WeakSet();
+  const ancestors = new Set();
 
   function visit(current, depth, location) {
     if (typeof current === "string") {
@@ -33,19 +33,23 @@ export function assertJsonLimits(value, label = "JSON artifact", limits = JSON_L
       return;
     }
     if (!current || typeof current !== "object") return;
-    if (visited.has(current)) throw new JsonLimitError(`${location} contains a circular reference`);
-    visited.add(current);
-    if (depth > limits.maxDepth) throw new JsonLimitError(`${location} exceeds the JSON depth limit`);
-    if (Array.isArray(current)) {
-      if (current.length > limits.maxArrayLength) throw new JsonLimitError(`${location} exceeds the array length limit`);
-      current.forEach((item, index) => visit(item, depth + 1, `${location}[${index}]`));
-    } else {
-      const keys = Object.keys(current);
-      if (keys.length > limits.maxObjectKeys) throw new JsonLimitError(`${location} exceeds the object key limit`);
-      for (const key of keys) {
-        if (key.length > limits.maxStringLength) throw new JsonLimitError(`${location} contains an oversized key`);
-        visit(current[key], depth + 1, `${location}.${key}`);
+    if (ancestors.has(current)) throw new JsonLimitError(`${location} contains a circular reference`);
+    ancestors.add(current);
+    try {
+      if (depth > limits.maxDepth) throw new JsonLimitError(`${location} exceeds the JSON depth limit`);
+      if (Array.isArray(current)) {
+        if (current.length > limits.maxArrayLength) throw new JsonLimitError(`${location} exceeds the array length limit`);
+        current.forEach((item, index) => visit(item, depth + 1, `${location}[${index}]`));
+      } else {
+        const keys = Object.keys(current);
+        if (keys.length > limits.maxObjectKeys) throw new JsonLimitError(`${location} exceeds the object key limit`);
+        for (const key of keys) {
+          if (key.length > limits.maxStringLength) throw new JsonLimitError(`${location} contains an oversized key`);
+          visit(current[key], depth + 1, `${location}.${key}`);
+        }
       }
+    } finally {
+      ancestors.delete(current);
     }
   }
 

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

@@ -0,0 +1,118 @@
+import { ARTIFACT_PATHS } from "./artifacts.js";
+import { requiredEvidenceForTarget } from "./completion-artifacts.js";
+import { coverageForRequirements } from "./coverage.js";
+import { assertCheckList } from "./checks.js";
+
+export function artifactError(code, message, artifacts = []) {
+  return { code, message, artifacts };
+}
+
+export function staleReasons(state, contract, route) {
+  const reasons = [];
+  if (state.contractFingerprint !== contract.fingerprint) {
+    reasons.push(artifactError(
+      "E_CONTRACT_STALE",
+      "Work state references a different current contract",
+      [ARTIFACT_PATHS.state, ARTIFACT_PATHS.contract],
+    ));
+  }
+  if (route.value.contractFingerprint !== undefined && route.value.contractFingerprint !== contract.fingerprint) {
+    reasons.push(artifactError(
+      "E_ROUTE_STALE",
+      "Routing result references a different current contract",
+      [ARTIFACT_PATHS.route, ARTIFACT_PATHS.contract],
+    ));
+  }
+  if (state.routeFingerprint !== route.fingerprint) {
+    reasons.push(artifactError(
+      "E_ROUTE_STALE",
+      "Work state references a different routing result",
+      [ARTIFACT_PATHS.state, ARTIFACT_PATHS.route],
+    ));
+  }
+  if (JSON.stringify(state.selectedGuides) !== JSON.stringify(route.value.guides)) {
+    reasons.push(artifactError(
+      "E_ROUTE_STALE",
+      "Work state guides do not match the persisted routing result",
+      [ARTIFACT_PATHS.state, ARTIFACT_PATHS.route],
+    ));
+  }
+  return reasons;
+}
+
+export function freshnessReasons(state, classification) {
+  const requiredArtifactPaths = state.requiredArtifacts?.map((artifact) => artifact.path) ?? [];
+  const reasons = [artifactError(
+    "E_STATE_REVALIDATION_REQUIRED",
+    `Work-state checkpoint requires revalidation: ${classification.reasons.join(", ")}`,
+    [ARTIFACT_PATHS.state],
+  )];
+  for (const reason of classification.reasons) {
+    const contractRelated = ["CONTRACT_CHANGED", "CONTRACT_INVALID", "CONTRACT_NOT_VERIFIED"].includes(reason);
+    const artifactRelated = reason.startsWith("REQUIRED_ARTIFACT");
+    reasons.push(artifactError(
+      contractRelated ? "E_CONTRACT_STALE" : artifactRelated ? "E_REQUIRED_ARTIFACT_STALE" : "E_REPOSITORY_CHANGED",
+      `Work-state freshness check failed: ${reason}`,
+      uniqueSorted([
+        ARTIFACT_PATHS.state,
+        ...(contractRelated ? [ARTIFACT_PATHS.contract] : []),
+        ...(artifactRelated ? requiredArtifactPaths : []),
+      ]),
+    ));
+  }
+  return reasons;
+}
+
+export function checkListReasons(state) {
+  try {
+    assertCheckList(state.checks, "work-state.checks");
+    return [];
+  } catch (error) {
+    return [artifactError(error.code ?? "E_CHECK_INVALID", error.message, [ARTIFACT_PATHS.state])];
+  }
+}
+
+export async function loadArtifact(loader, fallback) {
+  try {
+    return { value: await loader(), error: null, missingArtifacts: [] };
+  } catch (error) {
+    return {
+      value: null,
+      error,
+      missingArtifacts: error?.code === "ARTIFACT_MISSING"
+        ? (error.artifacts?.length ? error.artifacts : [fallback])
+        : [],
+    };
+  }
+}
+
+export async function requirementsAndCoverage({
+  target,
+  packageRoot,
+  contract,
+  route,
+  checks,
+  additionalEvidence = [],
+  authorityContext,
+  runtimeContext,
+}) {
+  const requirements = await requiredEvidenceForTarget({
+    target,
+    contract,
+    route,
+    packageRoot,
+    additionalEvidence,
+  });
+  return {
+    requirements,
+    coverage: coverageForRequirements(requirements, checks, {
+      target,
+      taskId: contract?.value?.taskId,
+      options: { authorityContext, runtimeContext },
+    }),
+  };
+}
+
+function uniqueSorted(values) {
+  return [...new Set(values.filter(Boolean))].sort();
+}

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

@@ -0,0 +1,65 @@
+import { ARTIFACT_PATHS } from "./artifacts.js";
+import { reconcileContinuity } from "./continuity-reconciliation.js";
+import { NEXT_ACTIONS, result } from "./next-action-model.js";
+
+const REQUIRED_ARTIFACTS = Object.freeze([ARTIFACT_PATHS.state, ARTIFACT_PATHS.continuity]);
+
+function reason(code, message, artifacts = REQUIRED_ARTIFACTS) {
+  return { code, message, artifacts };
+}
+
+export function nextActionForContinuity({ context, continuity } = {}) {
+  if (!continuity || ["ABSENT", "NOT_APPLICABLE"].includes(continuity.classification)) return null;
+
+  if (continuity.classification === "FRESH") {
+    const remaining = continuity.continuity?.remainingWork ?? [];
+    if (remaining.length === 0) return null;
+    return result({
+      ...context,
+      nextAction: NEXT_ACTIONS.CONTINUE_IMPLEMENTATION,
+      reasons: [reason(
+        "CONTINUITY_REMAINING_WORK",
+        `Execution continuity records ${remaining.length} remaining implementation item${remaining.length === 1 ? "" : "s"}.`,
+        [ARTIFACT_PATHS.continuity],
+      )],
+      requiredArtifacts: REQUIRED_ARTIFACTS,
+    });
+  }
+
+  if (continuity.classification === "RECONCILIATION_REQUIRED") {
+    return result({
+      ...context,
+      nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER,
+      commands: ["forgeloop reconcile-continuity"],
+      reasons: [reason(
+        "E_CONTINUITY_RECONCILIATION_REQUIRED",
+        "Execution continuity no longer matches canonical state or the current checkout; reconcile it before advancing verification.",
+      )],
+      requiredArtifacts: REQUIRED_ARTIFACTS,
+    });
+  }
+
+  if (["INVALID", "INCONSISTENT"].includes(continuity.classification)) {
+    const codes = continuity.reasonCodes?.length > 0
+      ? continuity.reasonCodes
+      : [continuity.classification === "INVALID" ? "E_CONTINUITY_INVALID" : "E_CONTINUITY_INCONSISTENT"];
+    return result({
+      ...context,
+      nextAction: NEXT_ACTIONS.RESOLVE_BLOCKER,
+      reasons: codes.map((code, index) => reason(
+        code,
+        continuity.reasons?.[index] ?? `Execution continuity is ${continuity.classification.toLowerCase()}.`,
+      )),
+      requiredArtifacts: REQUIRED_ARTIFACTS,
+    });
+  }
+
+  return null;
+}
+
+export async function evaluateContinuityNextAction({ target, packageRoot, context } = {}) {
+  return nextActionForContinuity({
+    context,
+    continuity: await reconcileContinuity({ target, packageRoot }),
+  });
+}