@cassiomc1/forgeloop 0.1.0 → 0.1.2

package/src/core/preflight.js

@@ -0,0 +1,246 @@
+import { ARTIFACT_PATHS, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
+import { readContract } from "./contract.js";
+import { readGateIfPresent, validateGateArtifacts } from "./gate-artifact.js";
+import { requiredGatesForGuides } from "./guide-metadata.js";
+import { assertRouteInvariants } from "./router.js";
+import { assertSourceProvenance } from "./sources.js";
+import { readPersistedRoute } from "./route-artifact.js";
+import { appendProtocolEvent } from "./events.js";
+import { readWorkState } from "./work-state.js";
+import { readConfig } from "./config.js";
+import { assertSafePath, ensureWithin, fileExists, readBytes } from "./filesystem.js";
+import { sha256 } from "./manifest.js";
+import { validateProfileSources } from "./profile.js";
+
+const PREVIEW_DECISION_LIMIT = 10;
+const PREVIEW_DECISION_MAX_LENGTH = 240;
+
+function issue(code, message, artifacts = [], details = {}) {
+  return { code, message, artifacts, ...details };
+}
+
+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));
+}
+
+async function readProfile(target) {
+  const relativePath = "PROJECT_PROFILE.md";
+  await assertSafePath(target, relativePath);
+  const filePath = ensureWithin(target, relativePath);
+  if (!(await fileExists(filePath))) return { status: "missing", fingerprint: null };
+  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),
+  };
+}
+
+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" };
+  }
+}
+
+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;
+  }
+}
+
+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;
+  }
+}
+
+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;
+}
+
+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 };
+}
+
+export async function evaluatePreflight({ target, packageRoot, strict = false } = {}) {
+  const errors = [];
+  const profile = await readProfile(target);
+  const profileProvenance = await validateProfileSources(target, packageRoot);
+  const provenanceErrors = profileProvenance.errors ?? [];
+  errors.push(...provenanceErrors);
+  const contract = await loadContract(target, packageRoot, errors);
+  const route = await loadRoute(target, packageRoot, errors);
+  const config = await optionalConfig(target, packageRoot, errors);
+  const effectiveStrict = strict || config.complianceMode === "strict";
+  if (effectiveStrict && profile.status !== "verified") {
+    errors.push(issue("E_PROFILE_UNVERIFIED", "Strict preflight requires a verified project profile", ["PROJECT_PROFILE.md"]));
+  }
+  const unresolvedDecisions = contract?.value?.unresolvedDecisions ?? [];
+  if (unresolvedDecisions.length > 0) {
+    errors.push(issue(
+      "E_CONTRACT_UNRESOLVED_DECISION",
+      "The current contract contains unresolved blocking decisions.",
+      [ARTIFACT_PATHS.contract],
+      {
+        decisions: unresolvedDecisions
+          .slice(0, PREVIEW_DECISION_LIMIT)
+          .map((decision) => decision.slice(0, PREVIEW_DECISION_MAX_LENGTH)),
+        decisionCount: unresolvedDecisions.length,
+        ...(unresolvedDecisions.length > PREVIEW_DECISION_LIMIT ? { decisionsTruncated: true } : {}),
+        next: "Resolve the blocking decision with the user or applicable authority, update current-contract.json, then rerun preflight.",
+      },
+    ));
+  }
+
+  if (route && contract) {
+    assertRouteInvariants(route.value);
+    if (route.value.contractFingerprint !== undefined && route.value.contractFingerprint !== contract.fingerprint) {
+      errors.push(issue("E_ROUTE_STALE", "Routing result was created for a different contract", [ARTIFACT_PATHS.route, ARTIFACT_PATHS.contract]));
+    }
+  }
+
+  const sources = await loadSources(target, contract, packageRoot, errors);
+  const gates = await inspectGates(target, contract, route, packageRoot, errors, config);
+
+  let state = null;
+  try {
+    state = await readWorkState(target, packageRoot);
+  } catch (error) {
+    errors.push(issue("E_STATE_INVALID", error.message, [ARTIFACT_PATHS.state]));
+  }
+  if (state && route && JSON.stringify(state.selectedGuides) !== JSON.stringify(route.value.guides)) {
+    errors.push(issue("E_ROUTE_GUIDE_MISMATCH", "work-state.selectedGuides must equal routing-result.guides", [ARTIFACT_PATHS.route, ARTIFACT_PATHS.state]));
+  }
+  if (state && contract && state.contractFingerprint !== contract.fingerprint) {
+    errors.push(issue("E_CONTRACT_STALE", "work-state references a different contract", [ARTIFACT_PATHS.contract, ARTIFACT_PATHS.state]));
+  }
+
+  const sortedErrors = sortIssues(errors);
+  const taskId = contract?.value?.taskId ?? state?.taskId ?? "unknown";
+  return {
+    schemaVersion: 1,
+    protocolVersion: 1,
+    taskId,
+    status: sortedErrors.length === 0 ? "READY" : "BLOCKED",
+    profile: { ...profile, provenance: profileProvenance.status },
+    contract: contract
+      ? { status: "valid", fingerprint: contract.fingerprint }
+      : { status: "missing", fingerprint: null },
+    routing: route
+      ? { status: "valid", fingerprint: route.fingerprint, guides: [...route.value.guides] }
+      : { status: "missing", fingerprint: null, guides: [] },
+    requiredGates: gates.required,
+    satisfiedGates: gates.satisfied,
+    errors: sortedErrors,
+    fingerprints: {
+      contract: contract?.fingerprint ?? null,
+      routing: route?.fingerprint ?? null,
+      profile: profile.fingerprint,
+    },
+    ...(config.policy ? {
+      policy: {
+        name: config.policy,
+        complianceMode: config.complianceMode,
+        requiredGates: [...(config.requiredGates ?? [])],
+        requiredEvidence: [...(config.requiredEvidence ?? [])],
+      },
+    } : {}),
+    ...(sources ? { sources: { status: "valid", fingerprint: null } } : {}),
+  };
+}
+
+export async function runPreflight({ target, packageRoot, strict = false, persist = true } = {}) {
+  const result = await evaluatePreflight({ target, packageRoot, strict });
+  if (persist) {
+    await writeJsonArtifact(target, ARTIFACT_PATHS.preflight, result, "preflight", packageRoot);
+    if (result.taskId !== "unknown") {
+      for (const gate of result.satisfiedGates) {
+        await appendProtocolEvent(target, {
+          taskId: result.taskId,
+          event: "GATE_SATISFIED",
+          details: { gate },
+        }, packageRoot);
+      }
+      await appendProtocolEvent(target, {
+        taskId: result.taskId,
+        event: result.status === "READY" ? "PREFLIGHT_READY" : "PREFLIGHT_BLOCKED",
+        fingerprint: result.fingerprints.contract ?? undefined,
+        details: {
+          requiredGates: result.requiredGates,
+          satisfiedGates: result.satisfiedGates,
+        },
+      }, packageRoot);
+    }
+  }
+  return result;
+}

package/src/core/profile.js

@@ -0,0 +1,48 @@
+import { readFile } from "node:fs/promises";
+
+import { ARTIFACT_PATHS, readJsonArtifact } from "./artifacts.js";
+import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
+import { assertSourceProvenance } from "./sources.js";
+
+const SOURCE_ID_PATTERN = /\b(?:USER|FILE|CMD|DECISION|OBS|INFER|UNKNOWN)-[A-Z0-9_-]+\b/g;
+const DIRECTIVE_PATTERN = /forgeloop-source:\s*([A-Z0-9_-]+)\s+kind=([a-z-]+)/gi;
+
+function issue(code, message, artifacts = []) {
+  return { code, message, artifacts };
+}
+
+export async function validateProfileSources(target, packageRoot) {
+  const profilePath = "PROJECT_PROFILE.md";
+  await assertSafePath(target, profilePath);
+  const absolutePath = ensureWithin(target, profilePath);
+  if (!(await fileExists(absolutePath))) {
+    return { status: "missing", refs: [], errors: [] };
+  }
+  const text = await readFile(absolutePath, "utf8");
+  const refs = [...new Set(text.match(SOURCE_ID_PATTERN) ?? [])].sort();
+  const directives = [...text.matchAll(DIRECTIVE_PATTERN)].map((match) => ({ id: match[1], kind: match[2] }));
+  if (refs.length === 0 && directives.length === 0) {
+    return { status: "not-referenced", refs: [], errors: [] };
+  }
+  const errors = [];
+  let registry;
+  try {
+    registry = (await readJsonArtifact(target, ARTIFACT_PATHS.sources, "source-registry", packageRoot)).value;
+  } catch (error) {
+    errors.push(issue("E_PROFILE_SOURCE_MISSING", error.message, [ARTIFACT_PATHS.sources]));
+    return { status: "invalid", refs, errors };
+  }
+  try {
+    assertSourceProvenance(registry, refs);
+  } catch (error) {
+    errors.push(issue(error.code ?? "E_PROFILE_SOURCE_UNKNOWN", error.message, [ARTIFACT_PATHS.sources]));
+  }
+  for (const directive of directives) {
+    try {
+      assertSourceProvenance(registry, [directive.id], { expectedKind: directive.kind });
+    } catch (error) {
+      errors.push(issue(error.code ?? "E_PROFILE_SOURCE_MISCLASSIFIED", error.message, [ARTIFACT_PATHS.sources]));
+    }
+  }
+  return { status: errors.length === 0 ? "valid" : "invalid", refs, errors };
+}

package/src/core/protocol.js

@@ -15,6 +15,40 @@ export const FAILURE_CLASSES = Object.freeze([
   "STALE_STATE_FAILURE",
 ]);
 
+export const FAILURE_CODES = Object.freeze([
+  "E_PREFLIGHT_NOT_READY",
+  "E_CONTRACT_MISSING",
+  "E_CONTRACT_INVALID",
+  "E_CONTRACT_UNRESOLVED_DECISION",
+  "E_CONTRACT_STALE",
+  "E_ROUTE_MISSING",
+  "E_ROUTE_INVALID",
+  "E_ROUTE_STALE",
+  "E_ROUTE_GUIDE_MISMATCH",
+  "E_ROUTE_REASON_MISSING",
+  "E_GATE_REQUIRED",
+  "E_GATE_UNVERIFIED",
+  "E_GATE_STALE",
+  "E_PHASE_TRANSITION_INVALID",
+  "E_PHASE_PREREQUISITE_MISSING",
+  "E_PHASE_CHRONOLOGY_INVALID",
+  "E_EVIDENCE_REQUIRED",
+  "E_EVIDENCE_KIND_INVALID",
+  "E_EVIDENCE_STALE",
+  "E_EVIDENCE_COVERAGE_PARTIAL",
+  "E_CHECK_STATUS_CONTRADICTION",
+  "E_PROFILE_SOURCE_MISSING",
+  "E_PROFILE_SOURCE_UNKNOWN",
+  "E_PROFILE_SOURCE_MISCLASSIFIED",
+  "E_RECEIPT_ROUTE_MISMATCH",
+  "E_RECEIPT_STATE_MISMATCH",
+  "E_RECEIPT_CONTRACT_MISMATCH",
+  "E_RECEIPT_PATH_MISMATCH",
+  "E_COMPLETION_REJECTED",
+  "E_PUBLICATION_CLAIM_UNVERIFIED",
+  "E_PRODUCTION_READINESS_UNVERIFIED",
+]);
+
 export const WORK_PHASES = Object.freeze([
   "RECEIVED",
   "DISCOVERING",

package/src/core/receipt.js

@@ -2,6 +2,8 @@ import { GUIDE_IDS, PROTOCOL_VERSION } from "./protocol.js";
 import { assertSchema, readSchema } from "./schema-validation.js";
 import { assertEvidenceList, evidenceMatches } from "./evidence.js";
 import { assertJsonLimits } from "./json-safety.js";
+import { assertCheck, assertCheckList } from "./checks.js";
+import { assertCoverageList } from "./coverage.js";
 
 const RECEIPT_SCHEMA_VERSION = 1;
 const SECRET_WORDS = new Set(["token", "password", "secret", "credential"]);
@@ -59,6 +61,10 @@ export function assertReceiptSemantics(receipt) {
   assertEvidenceList(evidence, "receipt.evidence");
 
   for (const [index, check] of receipt.checks.entries()) {
+    if (check?.schemaVersion !== undefined || check?.id !== undefined || check?.evidenceKind !== undefined) {
+      assertCheck(check, `receipt.checks[${index}]`);
+      continue;
+    }
     if (check?.status === "passed") {
       const hasCommandOrResult = [check.command, check.result, check.name]
         .some((value) => typeof value === "string" && value.trim().length > 0);
@@ -68,6 +74,10 @@ export function assertReceiptSemantics(receipt) {
     }
   }
 
+  if (receipt.evidenceCoverage !== undefined) {
+    assertCoverageList(receipt.evidenceCoverage, "receipt.evidenceCoverage");
+  }
+
   if (receipt.status === "complete") {
     const verificationEvidence = evidence.filter((item) => ["OBSERVED", "INFERRED"].includes(item.kind));
     if (verificationEvidence.length === 0) {
@@ -82,10 +92,32 @@ export function assertReceiptSemantics(receipt) {
   ];
   for (const [claimed, terms, field, label] of publicationEvidence) {
     if (claimed && !evidenceMatches(evidence, terms)) {
-      throw new Error(`publication.${field} requires ${label} evidence`);
+      const error = new Error(`publication.${field} requires ${label} evidence`);
+      error.code = "E_PUBLICATION_CLAIM_UNVERIFIED";
+      throw error;
     }
   }
 
+  if (["committed", "pushed", "published", "deployed"].includes(receipt.publicationStatus)) {
+    const requiredTerms = receipt.publicationStatus === "committed"
+      ? ["commit", "committed"]
+      : receipt.publicationStatus === "pushed"
+        ? ["git push", "pushed"]
+        : receipt.publicationStatus === "deployed"
+          ? ["deploy", "deployed", "deployment"]
+          : ["publish", "published", "release"];
+    if (!evidenceMatches(evidence, requiredTerms)) {
+      const error = new Error(`publicationStatus ${receipt.publicationStatus} requires publication evidence`);
+      error.code = "E_PUBLICATION_CLAIM_UNVERIFIED";
+      throw error;
+    }
+  }
+  if (receipt.productionReadiness === "ready" && !evidenceMatches(evidence, ["production readiness", "production validation", "deployment"])) {
+    const error = new Error("productionReadiness ready requires production evidence");
+    error.code = "E_PRODUCTION_READINESS_UNVERIFIED";
+    throw error;
+  }
+
   if (receipt.review.independent === true) {
     const implementer = receipt.review.implementerId;
     const reviewer = receipt.review.reviewerId;
@@ -111,11 +143,18 @@ export async function createReceipt(input, packageRoot) {
     protocolVersion: PROTOCOL_VERSION,
     taskId: input.taskId,
     contractFingerprint: input.contractFingerprint,
+    ...(input.routeFingerprint !== undefined ? { routeFingerprint: input.routeFingerprint } : {}),
+    ...(input.stateFingerprint !== undefined ? { stateFingerprint: input.stateFingerprint } : {}),
     status: input.status ?? "in-progress",
+    ...(input.taskStatus !== undefined ? { taskStatus: input.taskStatus } : {}),
+    ...(input.verificationStatus !== undefined ? { verificationStatus: input.verificationStatus } : {}),
+    ...(input.publicationStatus !== undefined ? { publicationStatus: input.publicationStatus } : {}),
+    ...(input.productionReadiness !== undefined ? { productionReadiness: input.productionReadiness } : {}),
     selectedGuides: [...(input.selectedGuides ?? [])],
     changedPaths: [...(input.changedPaths ?? [])],
     checks: [...(input.checks ?? [])],
     evidence: [...(input.evidence ?? [])],
+    ...(input.evidenceCoverage !== undefined ? { evidenceCoverage: [...input.evidenceCoverage] } : {}),
     review: input.review ?? { status: "not-run", independent: false },
     limitations: [...(input.limitations ?? [])],
     publication: input.publication ?? {

package/src/core/report.js

@@ -0,0 +1,49 @@
+import { readFile } from "node:fs/promises";
+
+import { evaluateAudit } from "./audit.js";
+import { fileExists, ensureWithin } from "./filesystem.js";
+
+async function profileStatus(target) {
+  const profilePath = ensureWithin(target, "PROJECT_PROFILE.md");
+  if (!(await fileExists(profilePath))) return "NOT_VERIFIED";
+  const text = await readFile(profilePath, "utf8");
+  return /^profile-status:\s*verified\s*$/m.test(text) ? "PASS" : "NOT_VERIFIED";
+}
+
+function section(id, label, status, details = null) {
+  return { id, label, status, ...(details ? { details } : {}) };
+}
+
+export async function evaluateReport({ target, packageRoot, strict = false } = {}) {
+  const audit = await evaluateAudit({ target, packageRoot, strict });
+  const completion = audit.completion;
+  const preflight = completion.preflight;
+  const errorCodes = new Set(audit.errors.map((error) => error.code));
+  const coverage = completion.coverage ?? [];
+  const coverageStatus = coverage.length === 0
+    ? "NOT_VERIFIED"
+    : coverage.every((item) => item.status === "COVERED") ? "PASS" : "PARTIAL";
+  const sections = [
+    section("installation", "Installation", audit.installation.status === "ready" ? "PASS" : "NOT_VERIFIED"),
+    section("profile", "Profile", await profileStatus(target)),
+    section("contract", "Contract", preflight.contract.status === "valid" ? "PASS" : "NOT_VERIFIED"),
+    section("routing", "Routing", preflight.routing.status === "valid" ? "PASS" : "NOT_VERIFIED"),
+    section("required-gates", "Required gates", preflight.requiredGates.length === preflight.satisfiedGates.length ? "PASS" : "BLOCKED"),
+    section("phase-chronology", "Phase chronology", completion.ledger.status === "valid" ? "PASS" : "INVALID"),
+    section("evidence-coverage", "Evidence coverage", coverageStatus),
+    section("receipt", "Receipt", errorCodes.has("E_RECEIPT_MISSING") || errorCodes.has("E_RECEIPT_INVALID") ? "NOT_VERIFIED" : "PASS"),
+    section("publication", "Publication state", audit.publicationStatus.toUpperCase().replaceAll("-", "_")),
+    section("production-readiness", "Production readiness", audit.productionReadiness.toUpperCase().replaceAll("-", "_")),
+  ];
+  return {
+    schemaVersion: 1,
+    protocolVersion: 1,
+    status: audit.status,
+    verdict: audit.status === "VALID" ? "VALID" : "INCOMPLETE",
+    sections,
+    publicationStatus: audit.publicationStatus,
+    productionReadiness: audit.productionReadiness,
+    errors: audit.errors,
+    warnings: audit.warnings,
+  };
+}

package/src/core/repository.js

@@ -17,3 +17,21 @@ export async function currentRepositoryFingerprint(target) {
     return { branch: null, head: null };
   }
 }
+
+export async function currentChangedPaths(target) {
+  try {
+    const { stdout } = await execFileAsync(
+      "git",
+      ["-C", target, "status", "--porcelain=v1", "--untracked-files=all"],
+      { windowsHide: true },
+    );
+    return stdout
+      .split(/\r?\n/)
+      .filter(Boolean)
+      .map((line) => line.slice(3).trim())
+      .filter((relativePath) => relativePath && !relativePath.startsWith(".forgeloop/"))
+      .sort();
+  } catch {
+    return null;
+  }
+}

package/src/core/route-artifact.js

@@ -0,0 +1,33 @@
+import { assertRouteInvariants } from "./router.js";
+import { ARTIFACT_PATHS, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
+import { readContract } from "./contract.js";
+
+export async function persistRoute(target, route, packageRoot, options = {}) {
+  assertRouteInvariants(route);
+  let { contractFingerprint, ...writeOptions } = options;
+  if (contractFingerprint === undefined) {
+    try {
+      contractFingerprint = (await readContract(target, packageRoot)).fingerprint;
+    } catch (error) {
+      if (error.code !== "ARTIFACT_MISSING") throw error;
+    }
+  }
+  const value = contractFingerprint === undefined
+    ? route
+    : { ...route, contractFingerprint };
+  assertRouteInvariants(value);
+  return writeJsonArtifact(
+    target,
+    ARTIFACT_PATHS.route,
+    value,
+    "routing-result",
+    packageRoot,
+    writeOptions,
+  );
+}
+
+export async function readPersistedRoute(target, packageRoot) {
+  const artifact = await readJsonArtifact(target, ARTIFACT_PATHS.route, "routing-result", packageRoot);
+  assertRouteInvariants(artifact.value);
+  return artifact;
+}

package/src/core/router.js

@@ -259,31 +259,39 @@ export function evaluateRoute(input = {}) {
 }
 
 export function assertRouteInvariants(result) {
+  const invariantError = (code, message) => {
+    const error = new RouteInputError(message);
+    error.code = code;
+    return error;
+  };
   if (!result || typeof result !== "object" || Array.isArray(result)) {
-    throw new RouteInputError("Route result must be an object");
+    throw invariantError("E_ROUTE_INVALID", "Route result must be an object");
   }
   if (!Array.isArray(result.guides) || new Set(result.guides).size !== result.guides.length) {
-    throw new RouteInputError("Route result contains duplicate guides");
+    throw invariantError("E_ROUTE_INVALID", "Route result contains duplicate guides");
+  }
+  if (result.contractFingerprint !== undefined && !/^[a-f0-9]{64}$/.test(result.contractFingerprint)) {
+    throw invariantError("E_ROUTE_INVALID", "Route contractFingerprint must be a lowercase SHA-256 fingerprint");
   }
   for (const guide of result.guides) {
-    if (!GUIDE_IDS.includes(guide)) throw new RouteInputError(`Route result contains unknown guide: ${guide}`);
+    if (!GUIDE_IDS.includes(guide)) throw invariantError("E_ROUTE_INVALID", `Route result contains unknown guide: ${guide}`);
     if (!Array.isArray(result.reasons?.[guide]) || result.reasons[guide].length === 0) {
-      throw new RouteInputError(`Selected guide has no reason: ${guide}`);
+      throw invariantError("E_ROUTE_REASON_MISSING", `Selected guide has no reason: ${guide}`);
     }
   }
   for (const [guide, reasons] of Object.entries(result.excluded ?? {})) {
     if (guide !== "documentation" && !GUIDE_IDS.includes(guide)) {
-      throw new RouteInputError(`Route result contains unknown excluded guide: ${guide}`);
+      throw invariantError("E_ROUTE_INVALID", `Route result contains unknown excluded guide: ${guide}`);
     }
     if (result.guides.includes(guide)) {
-      throw new RouteInputError(`Guide cannot be selected and excluded: ${guide}`);
+      throw invariantError("E_ROUTE_INVALID", `Guide cannot be selected and excluded: ${guide}`);
     }
     if (!Array.isArray(reasons) || reasons.length === 0) {
-      throw new RouteInputError(`Excluded guide has no exclusion reason: ${guide}`);
+      throw invariantError("E_ROUTE_REASON_MISSING", `Excluded guide has no exclusion reason: ${guide}`);
     }
   }
   if (result.primary !== null && !result.guides.includes(result.primary)) {
-    throw new RouteInputError("Primary guide must be null or selected");
+    throw invariantError("E_ROUTE_INVALID", "Primary guide must be null or selected");
   }
   return result;
 }

package/src/core/schema-validation.js

@@ -13,6 +13,17 @@ export const SHIPPED_SCHEMA_NAMES = Object.freeze([
   "task-brief",
   "delegated-result",
   "evidence",
+  "current-contract",
+  "gate",
+  "source-registry",
+  "config",
+  "preflight",
+  "check",
+  "evidence-coverage",
+  "event",
+  "activation",
+  "policy",
+  "task-bundle",
 ]);
 
 export class SchemaValidationError extends Error {