@cassiomc1/forgeloop 0.1.15 → 1.0.0

package/src/core/continuity.js

@@ -0,0 +1,245 @@
+import { unlink } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  ARTIFACT_PATHS,
+  canonicalFingerprint,
+  readJsonArtifact,
+  writeJsonArtifact,
+} from "./artifacts.js";
+import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
+import { PROTOCOL_VERSION, WORK_PHASES } from "./protocol.js";
+import { assertSecretFree } from "./receipt.js";
+import { getPackageRoot } from "./templates.js";
+
+export const CONTINUITY_PATH = ARTIFACT_PATHS.continuity;
+export const CONTINUITY_SCHEMA_VERSION = 1;
+
+const LIMITS = Object.freeze({
+  taskId: 128,
+  id: 128,
+  summary: 1000,
+  path: 1024,
+  resumeNote: 2000,
+  remainingWork: 40,
+  knownIssues: 40,
+  changedAreas: 80,
+  inspectFirst: 40,
+});
+
+function continuityError(code, message, artifacts = [CONTINUITY_PATH]) {
+  const error = new Error(message);
+  error.name = "ContinuityError";
+  error.code = code;
+  error.artifacts = artifacts;
+  return error;
+}
+
+function nonEmptyString(value, label, maxLength) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw continuityError("E_CONTINUITY_INVALID", `${label} must be a non-empty string`);
+  }
+  if (value.length > maxLength) {
+    throw continuityError("E_CONTINUITY_INVALID", `${label} exceeds the ${maxLength}-character limit`);
+  }
+  if (/\p{Cc}/u.test(value)) {
+    throw continuityError("E_CONTINUITY_INVALID", `${label} contains control characters`);
+  }
+  return value;
+}
+
+function fingerprint(value, label) {
+  if (typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value)) {
+    throw continuityError("E_CONTINUITY_INVALID", `${label} must be a lowercase SHA-256 fingerprint`);
+  }
+  return value;
+}
+
+function normalizeProjectPath(value, label) {
+  nonEmptyString(value, label, LIMITS.path);
+  const portable = value.replaceAll("\\", "/");
+  if (portable.startsWith("/") || /^[A-Za-z]:\//.test(portable)) {
+    throw continuityError("E_CONTINUITY_INVALID", `${label} must remain a relative project path`);
+  }
+  const normalized = path.posix.normalize(portable);
+  if (normalized === "." || normalized === ".." || normalized.startsWith("../")) {
+    throw continuityError("E_CONTINUITY_INVALID", `${label} must not escape the task target`);
+  }
+  return normalized.replace(/^\.\//, "");
+}
+
+function normalizeWorkItem(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw continuityError("E_CONTINUITY_INVALID", `${label} must be an object`);
+  }
+  const keys = Object.keys(value).sort();
+  if (keys.some((key) => !["id", "summary"].includes(key))) {
+    throw continuityError("E_CONTINUITY_INVALID", `${label} contains an unsupported field`);
+  }
+  return {
+    id: nonEmptyString(value.id, `${label}.id`, LIMITS.id),
+    summary: nonEmptyString(value.summary, `${label}.summary`, LIMITS.summary),
+  };
+}
+
+function normalizeWorkItems(value, label, maxItems) {
+  if (!Array.isArray(value)) throw continuityError("E_CONTINUITY_INVALID", `${label} must be an array`);
+  if (value.length > maxItems) throw continuityError("E_CONTINUITY_INVALID", `${label} exceeds the ${maxItems}-item limit`);
+  const items = value.map((item, index) => normalizeWorkItem(item, `${label}[${index}]`));
+  if (new Set(items.map((item) => item.id)).size !== items.length) {
+    throw continuityError("E_CONTINUITY_INVALID", `${label} must not contain duplicate ids`);
+  }
+  return items;
+}
+
+function normalizePaths(value, label, maxItems) {
+  if (!Array.isArray(value)) throw continuityError("E_CONTINUITY_INVALID", `${label} must be an array`);
+  if (value.length > maxItems) throw continuityError("E_CONTINUITY_INVALID", `${label} exceeds the ${maxItems}-item limit`);
+  const paths = value.map((item, index) => normalizeProjectPath(item, `${label}[${index}]`));
+  if (new Set(paths).size !== paths.length) throw continuityError("E_CONTINUITY_INVALID", `${label} must not contain duplicate paths`);
+  return paths;
+}
+
+function normalizeRepositoryFingerprint(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw continuityError("E_CONTINUITY_INVALID", "repositoryFingerprint must be an object");
+  }
+  if (Object.keys(value).some((key) => !["branch", "head"].includes(key))) {
+    throw continuityError("E_CONTINUITY_INVALID", "repositoryFingerprint contains an unsupported field");
+  }
+  for (const key of ["branch", "head"]) {
+    if (value[key] !== null && typeof value[key] !== "string") {
+      throw continuityError("E_CONTINUITY_INVALID", `repositoryFingerprint.${key} must be a string or null`);
+    }
+  }
+  return { branch: value.branch ?? null, head: value.head ?? null };
+}
+
+const CONTINUITY_FIELDS = new Set([
+  "schemaVersion",
+  "protocolVersion",
+  "taskId",
+  "workStateFingerprint",
+  "contractFingerprint",
+  "phase",
+  "verificationCycle",
+  "repositoryFingerprint",
+  "updatedAt",
+  "currentFocus",
+  "remainingWork",
+  "knownIssues",
+  "changedAreas",
+  "inspectFirst",
+  "resumeNote",
+]);
+
+export function assertContinuitySemantics(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw continuityError("E_CONTINUITY_INVALID", "Continuity must be a JSON object");
+  }
+  const unknownField = Object.keys(input).find((key) => !CONTINUITY_FIELDS.has(key));
+  if (unknownField) {
+    throw continuityError("E_CONTINUITY_INVALID", `Continuity contains unsupported field: ${unknownField}`);
+  }
+  if (input.schemaVersion !== CONTINUITY_SCHEMA_VERSION || input.protocolVersion !== PROTOCOL_VERSION) {
+    throw continuityError("E_CONTINUITY_SCHEMA_UNSUPPORTED", "Unsupported continuity schema or protocol version");
+  }
+  if (!WORK_PHASES.includes(input.phase)) {
+    throw continuityError("E_CONTINUITY_INVALID", `Unknown continuity phase: ${input.phase}`);
+  }
+  if (input.verificationCycle !== undefined
+    && (!Number.isInteger(input.verificationCycle) || input.verificationCycle < 1)) {
+    throw continuityError("E_CONTINUITY_INVALID", "verificationCycle must be a positive integer");
+  }
+  const normalized = {
+    schemaVersion: CONTINUITY_SCHEMA_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    taskId: nonEmptyString(input.taskId, "taskId", LIMITS.taskId),
+    workStateFingerprint: fingerprint(input.workStateFingerprint, "workStateFingerprint"),
+    contractFingerprint: fingerprint(input.contractFingerprint, "contractFingerprint"),
+    phase: input.phase,
+    ...(input.verificationCycle !== undefined ? { verificationCycle: input.verificationCycle } : {}),
+    repositoryFingerprint: normalizeRepositoryFingerprint(input.repositoryFingerprint),
+    updatedAt: nonEmptyString(input.updatedAt, "updatedAt", 128),
+    ...(input.currentFocus !== undefined ? { currentFocus: normalizeWorkItem(input.currentFocus, "currentFocus") } : {}),
+    remainingWork: normalizeWorkItems(input.remainingWork, "remainingWork", LIMITS.remainingWork),
+    knownIssues: normalizeWorkItems(input.knownIssues, "knownIssues", LIMITS.knownIssues),
+    changedAreas: normalizePaths(input.changedAreas, "changedAreas", LIMITS.changedAreas),
+    inspectFirst: normalizePaths(input.inspectFirst, "inspectFirst", LIMITS.inspectFirst),
+    ...(input.resumeNote !== undefined
+      ? { resumeNote: nonEmptyString(input.resumeNote, "resumeNote", LIMITS.resumeNote) }
+      : {}),
+  };
+  assertSecretFree(normalized);
+  return normalized;
+}
+
+export function createContinuity(input) {
+  return assertContinuitySemantics({
+    schemaVersion: input.schemaVersion ?? CONTINUITY_SCHEMA_VERSION,
+    protocolVersion: input.protocolVersion ?? PROTOCOL_VERSION,
+    ...structuredClone(input),
+  });
+}
+
+export async function readContinuity(target, packageRoot = getPackageRoot()) {
+  const artifact = await readJsonArtifact(target, CONTINUITY_PATH, "continuity", packageRoot);
+  return { ...artifact, value: assertContinuitySemantics(artifact.value) };
+}
+
+export async function writeContinuity(target, operationalInput = {}, options = {}) {
+  const packageRoot = options.packageRoot ?? getPackageRoot();
+  let state = options.state;
+  if (!state) {
+    const { readWorkState } = await import("./work-state.js");
+    state = await readWorkState(target, packageRoot);
+  }
+  if (!state) throw continuityError("E_CONTINUITY_STATE_MISSING", "Cannot record continuity without work state", [ARTIFACT_PATHS.state]);
+
+  let contract = options.contract;
+  if (!contract) {
+    const { readContract } = await import("./contract.js");
+    contract = await readContract(target, packageRoot);
+  }
+  const currentContractFingerprint = contract?.fingerprint
+    ?? (contract ? canonicalFingerprint(contract.value ?? contract) : null);
+  if (!currentContractFingerprint) {
+    throw continuityError("E_CONTINUITY_CONTRACT_MISMATCH", "Cannot bind continuity to the current contract", [ARTIFACT_PATHS.contract]);
+  }
+  if (state.contractFingerprint !== currentContractFingerprint) {
+    throw continuityError(
+      "E_CONTINUITY_CONTRACT_MISMATCH",
+      "Work state contract fingerprint does not match the current contract",
+      [ARTIFACT_PATHS.state, ARTIFACT_PATHS.contract],
+    );
+  }
+  const value = createContinuity({
+    taskId: state.taskId,
+    workStateFingerprint: canonicalFingerprint(state),
+    contractFingerprint: state.contractFingerprint,
+    phase: state.phase,
+    ...(state.verificationCycle !== undefined ? { verificationCycle: state.verificationCycle } : {}),
+    repositoryFingerprint: options.repositoryFingerprint ?? await (async () => {
+      const { currentRepositoryFingerprint } = await import("./repository.js");
+      return currentRepositoryFingerprint(target);
+    })(),
+    updatedAt: options.now ?? new Date().toISOString(),
+    ...(operationalInput.currentFocus !== undefined ? { currentFocus: operationalInput.currentFocus } : {}),
+    remainingWork: operationalInput.remainingWork ?? [],
+    knownIssues: operationalInput.knownIssues ?? [],
+    changedAreas: operationalInput.changedAreas ?? [],
+    inspectFirst: operationalInput.inspectFirst ?? [],
+    ...(operationalInput.resumeNote !== undefined ? { resumeNote: operationalInput.resumeNote } : {}),
+  });
+  return writeJsonArtifact(target, CONTINUITY_PATH, value, "continuity", packageRoot, {
+    dryRun: options.dryRun ?? false,
+  });
+}
+
+export async function clearContinuity(target) {
+  await assertSafePath(target, CONTINUITY_PATH);
+  const artifactPath = ensureWithin(target, CONTINUITY_PATH);
+  if (!(await fileExists(artifactPath))) return { removed: false, path: CONTINUITY_PATH };
+  await unlink(artifactPath);
+  return { removed: true, path: CONTINUITY_PATH };
+}

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();
+}