@cassiomc1/forgeloop 0.1.14 → 0.1.16

package/src/core/preflight-loaders.js

@@ -0,0 +1,112 @@
+import { ARTIFACT_PATHS, readJsonArtifact } from "./artifacts.js";
+import { readContract } from "./contract.js";
+import { readGateIfPresent, validateGateArtifacts } from "./gate-artifact.js";
+import { requiredGatesForGuides } from "./guide-metadata.js";
+import { assertSourceProvenance } from "./sources.js";
+import { readPersistedRoute } from "./route-artifact.js";
+import { ensureWithin, readBytes } from "./filesystem.js";
+import { sha256 } from "./manifest.js";
+import { findProfilePath, validateProfileSources } from "./profile.js";
+import { issue } from "./preflight-model.js";
+
+export async function readProfile(target) {
+  const relativePath = await findProfilePath(target);
+  if (!relativePath) return { status: "missing", fingerprint: null };
+  const filePath = ensureWithin(target, relativePath);
+  const bytes = await readBytes(filePath);
+  const text = bytes.toString("utf8");
+  const mode = text.match(/^profile-mode:\s*([^\s]+)\s*$/m)?.[1] ?? null;
+  const status = text.match(/^profile-status:\s*([^\s]+)\s*$/m)?.[1] ?? null;
+  return {
+    status: status === "verified" && mode !== "template" ? "verified" : "unverified",
+    mode,
+    profileStatus: status,
+    fingerprint: sha256(bytes),
+  };
+}
+
+export async function optionalConfig(target, packageRoot, errors) {
+  try {
+    const artifact = await readJsonArtifact(target, ARTIFACT_PATHS.config, "config", packageRoot);
+    return artifact.value;
+  } catch (error) {
+    if (error.code === "ARTIFACT_MISSING") return { schemaVersion: 1, protocolVersion: 1, complianceMode: "standard" };
+    errors.push(issue("E_CONFIG_INVALID", error.message, [ARTIFACT_PATHS.config]));
+    return { schemaVersion: 1, protocolVersion: 1, complianceMode: "standard" };
+  }
+}
+
+export async function loadContract(target, packageRoot, errors) {
+  try {
+    return await readContract(target, packageRoot);
+  } catch (error) {
+    errors.push(issue(error.code === "ARTIFACT_MISSING" ? "E_CONTRACT_MISSING" : "E_CONTRACT_INVALID", error.message, [ARTIFACT_PATHS.contract]));
+    return null;
+  }
+}
+
+export async function loadRoute(target, packageRoot, errors) {
+  try {
+    return await readPersistedRoute(target, packageRoot);
+  } catch (error) {
+    const code = error.code === "ARTIFACT_MISSING"
+      ? "E_ROUTE_MISSING"
+      : ["E_ROUTE_REASON_MISSING", "E_ROUTE_INVALID"].includes(error.code) ? error.code : "E_ROUTE_INVALID";
+    errors.push(issue(code, error.message, [ARTIFACT_PATHS.route]));
+    return null;
+  }
+}
+
+export async function loadSources(target, contract, packageRoot, errors) {
+  if (!contract?.value?.sourceRefs?.length) return null;
+  let registry;
+  try {
+    registry = (await readJsonArtifact(target, ARTIFACT_PATHS.sources, "source-registry", packageRoot)).value;
+  } catch (error) {
+    errors.push(issue(error.code === "ARTIFACT_MISSING" ? "E_PROFILE_SOURCE_MISSING" : "E_PROFILE_SOURCE_UNKNOWN", error.message, [ARTIFACT_PATHS.sources]));
+    return null;
+  }
+  try {
+    assertSourceProvenance(registry, contract.value.sourceRefs);
+  } catch (error) {
+    errors.push(issue(error.code ?? "E_PROFILE_SOURCE_UNKNOWN", error.message, [ARTIFACT_PATHS.sources]));
+  }
+  return registry;
+}
+
+export async function inspectGates(target, contract, route, packageRoot, errors, config = {}) {
+  if (!route) return { required: [], satisfied: [], records: {} };
+  const guideGates = await requiredGatesForGuides(route.value.guides, packageRoot);
+  const required = [...new Set([...guideGates, ...(config.requiredGates ?? [])])].sort();
+  const satisfied = [];
+  const records = {};
+  for (const gate of required) {
+    let artifact;
+    try {
+      artifact = await readGateIfPresent(target, gate, packageRoot);
+    } catch (error) {
+      errors.push(issue(error.code === "ARTIFACT_MISSING" ? "E_GATE_UNVERIFIED" : "E_GATE_INVALID", error.message, [`${ARTIFACT_PATHS.gates}/${gate}.json`], { gate }));
+      continue;
+    }
+    if (!artifact) {
+      errors.push(issue("E_GATE_UNVERIFIED", `Required gate is missing or unverified: ${gate}`, [`${ARTIFACT_PATHS.gates}/${gate}.json`], { gate }));
+      continue;
+    }
+    records[gate] = artifact;
+    if (artifact.value.taskId !== contract?.value?.taskId) {
+      errors.push(issue("E_GATE_TASK_MISMATCH", `Gate ${gate} belongs to a different task`, [artifact.path], { gate }));
+      continue;
+    }
+    if (artifact.value.status !== "satisfied") {
+      errors.push(issue("E_GATE_UNVERIFIED", `Required gate is ${artifact.value.status}: ${gate}`, [artifact.path], { gate }));
+      continue;
+    }
+    const stale = await validateGateArtifacts(target, artifact.value, packageRoot);
+    if (stale.length > 0) {
+      errors.push(issue("E_GATE_STALE", `Gate ${gate} references stale artifacts`, [artifact.path], { gate, stale }));
+      continue;
+    }
+    satisfied.push(gate);
+  }
+  return { required, satisfied: satisfied.sort(), records };
+}

package/src/core/preflight-model.js

@@ -0,0 +1,83 @@
+import { ARTIFACT_PATHS } from "./artifacts.js";
+
+export function issue(code, message, artifacts = [], details = {}) {
+  return { code, message, artifacts, ...details };
+}
+
+export function sortIssues(errors) {
+  const unique = [...new Map(errors.map((error) => [
+    `${error.code}\0${error.artifacts.join("\0")}\0${error.message}`,
+    error,
+  ])).values()];
+  return unique.sort((left, right) => left.code.localeCompare(right.code)
+    || left.artifacts.join("\0").localeCompare(right.artifacts.join("\0"))
+    || left.message.localeCompare(right.message));
+}
+
+export function preflightError(code, message, artifacts = []) {
+  const error = new Error(message);
+  error.code = code;
+  error.artifacts = artifacts;
+  return error;
+}
+
+export function sameStringSet(left, right) {
+  if (!Array.isArray(left) || !Array.isArray(right)) return false;
+  const leftSet = new Set(left);
+  const rightSet = new Set(right);
+  return leftSet.size === left.length
+    && rightSet.size === right.length
+    && leftSet.size === rightSet.size
+    && [...leftSet].every((value) => rightSet.has(value));
+}
+
+export function validatePersistedPreflight(persisted, current) {
+  const errors = [];
+  if (persisted?.status !== "READY") {
+    errors.push(issue("E_PREFLIGHT_NOT_READY", "A persisted READY preflight is required", [ARTIFACT_PATHS.preflight]));
+    return errors;
+  }
+  if (current?.status !== "READY") {
+    errors.push(issue("E_PREFLIGHT_NOT_READY", "The current preflight evaluation is not READY", [ARTIFACT_PATHS.preflight]));
+  }
+  if (persisted.taskId !== current?.taskId) {
+    errors.push(issue(
+      "E_PREFLIGHT_TASK_MISMATCH",
+      "Persisted preflight does not belong to the current task",
+      [ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.contract],
+    ));
+  }
+  if (persisted.fingerprints?.contract !== current?.fingerprints?.contract
+    || persisted.contract?.fingerprint !== current?.contract?.fingerprint) {
+    errors.push(issue(
+      "E_PREFLIGHT_CONTRACT_STALE",
+      "Persisted preflight does not match the current contract fingerprint",
+      [ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.contract],
+    ));
+  }
+  if (persisted.fingerprints?.routing !== current?.fingerprints?.routing
+    || persisted.routing?.fingerprint !== current?.routing?.fingerprint) {
+    errors.push(issue(
+      "E_PREFLIGHT_ROUTE_STALE",
+      "Persisted preflight does not match the current routing fingerprint",
+      [ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.route],
+    ));
+  }
+  if (!sameStringSet(persisted.requiredGates, current?.requiredGates)
+    || !sameStringSet(persisted.satisfiedGates, current?.satisfiedGates)) {
+    errors.push(issue(
+      "E_PREFLIGHT_GATES_STALE",
+      "Persisted preflight gate sets do not match the current evaluation",
+      [ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.gates],
+    ));
+  }
+  return sortIssues(errors);
+}
+
+export const PREFLIGHT_IDENTITY_BARRIER_CODES = new Set([
+  "E_CONTRACT_STALE",
+  "E_GATE_TASK_MISMATCH",
+  "E_ROUTE_STALE",
+  "E_STATE_TASK_MISMATCH",
+  "E_ROUTE_GUIDE_MISMATCH",
+]);