@cassiomc1/forgeloop 1.6.2 → 1.6.4

package/src/commands/responsibility-set.js

@@ -0,0 +1,20 @@
+import { setResponsibilityContract } from "../core/responsibility.js";
+
+export async function runResponsibilitySet(options = {}) {
+  return setResponsibilityContract(options.target, {
+    ...options,
+    allowedPaths: options.responsibilityAllowedPaths?.length ? options.responsibilityAllowedPaths : undefined,
+    readOnlyPaths: options.responsibilityReadOnlyPaths?.length ? options.responsibilityReadOnlyPaths : undefined,
+    requiredCheckIds: options.responsibilityRequiredChecks?.length ? options.responsibilityRequiredChecks : undefined,
+    label: options.responsibilityLabel,
+    frozenInputs: {
+      contract: options.responsibilityFreezeContract,
+      route: options.responsibilityFreezeRoute,
+      claims: options.responsibilityFreezeClaims,
+    },
+  });
+}
+
+export function formatResponsibilitySetResult(result) {
+  return `FORGELOOP RESPONSIBILITY SET\ntask: ${result.taskId}\nlabel: ${result.responsibility.label}\nfingerprint: ${result.fingerprint}\npath: ${result.path}\n\n`;
+}

package/src/commands/responsibility-status.js

@@ -0,0 +1,12 @@
+import { resolveResponsibilityStatus } from "../core/responsibility.js";
+
+export async function runResponsibilityStatus({ target, packageRoot, taskId } = {}) {
+  return resolveResponsibilityStatus(target, { packageRoot, taskId });
+}
+
+export function formatResponsibilityStatusResult(result) {
+  const lines = [`FORGELOOP RESPONSIBILITY: ${result.status}`, `task: ${result.taskId}`];
+  if (result.responsibility) lines.push(`label: ${result.responsibility.label}`);
+  for (const error of result.errors ?? []) lines.push(`${error.code}: ${error.message}`);
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/run-check.js

@@ -4,6 +4,8 @@ import {
 } from "../core/completion-artifacts.js";
 import { runCommandExecution } from "../core/execution.js";
 import { withTaskMutation } from "../core/task-command.js";
+import { readVerificationScope, validateVerificationScopeFreshness } from "../core/verification-scope.js";
+import { bindVerificationScopeCommand } from "../core/verification-scope-capability.js";
 
 export async function runCheck({
   target,
@@ -13,6 +15,7 @@ export async function runCheck({
   argv,
   details,
   timeoutMs,
+  scopeRef,
   authorityContext,
   runtimeContext,
   taskId,
@@ -25,6 +28,43 @@ export async function runCheck({
   }
   return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "run-check", async (ctx) => {
     const effectiveTaskId = ctx?.taskId ?? null;
+    let executionDetails = details;
+    let commandArgv = [...argv];
+    if (scopeRef) {
+      const scope = await readVerificationScope(target, {
+        packageRoot,
+        taskId: effectiveTaskId,
+        scopePath: scopeRef,
+      });
+      const freshness = await validateVerificationScopeFreshness(target, {
+        packageRoot,
+        taskId: effectiveTaskId,
+        scope: scope.value,
+      });
+      const binding = await bindVerificationScopeCommand({
+        target,
+        packageRoot,
+        checkId: id,
+        argv: commandArgv,
+        scope: scope.value,
+        capabilities: freshness.current.checkerCapabilities,
+      });
+      commandArgv = binding.argv;
+      executionDetails = {
+        ...(details ?? {}),
+        verificationScope: {
+          ref: scope.path,
+          fingerprint: scope.fingerprint,
+          mode: scope.value.resolvedMode,
+          selectedPaths: scope.value.selectedPaths,
+          argv: [...commandArgv],
+          ...(binding.checker ? {
+            checkerId: binding.checker.checkId,
+            checkerCapabilityFingerprint: binding.capabilityFingerprint,
+          } : {}),
+        },
+      };
+    }
     const ready = await assertRecordCheckPrerequisites({
       target,
       packageRoot,
@@ -43,8 +83,8 @@ export async function runCheck({
       checkId: id,
       requirement,
       verificationCycle,
-      argv,
-      details,
+      argv: commandArgv,
+      details: executionDetails,
       timeoutMs,
       authorityContext,
       runtimeContext,
@@ -62,7 +102,7 @@ export async function runCheck({
       command: execution.execution.argv.join(" "),
       result: execution.result,
       ...(execution.execution.exitCode === null ? {} : { exitCode: execution.execution.exitCode }),
-      details,
+      details: executionDetails,
       executionRef: execution.execution.executionId,
       provenance: "FORGELOOP_EXECUTED",
       authorityContext,

package/src/commands/task-repair-legacy-recovery.js

@@ -195,7 +195,6 @@ export async function runTaskRepairLegacyRecovery({ target, packageRoot, taskId,
 
     const existingRecovery = await readTaskRecovery(target, { taskId: effectiveTaskId, packageRoot });
     const locked = await inspectLegacyRecoveryMigration(target, { taskId: effectiveTaskId, packageRoot });
-    let candidate;
     if (locked.alreadyMigrated) {
       return verifyAlreadyRepaired(target, {
         taskId: effectiveTaskId,
@@ -204,7 +203,7 @@ export async function runTaskRepairLegacyRecovery({ target, packageRoot, taskId,
         existingRecovery,
       });
     }
-    candidate = requireSingleTailCandidate({
+    const candidate = requireSingleTailCandidate({
       taskId: effectiveTaskId,
       events: locked.events,
       candidates: locked.candidates,

package/src/commands/verify-scope.js

@@ -0,0 +1,9 @@
+import { captureVerificationScope } from "../core/verification-scope.js";
+
+export async function runVerifyScope({ target, packageRoot, taskId, verificationScopeMode } = {}) {
+  return captureVerificationScope(target, { packageRoot, taskId, mode: verificationScopeMode ?? "AUTO" });
+}
+
+export function formatVerifyScopeResult(result) {
+  return `FORGELOOP VERIFICATION SCOPE: ${result.scope.resolvedMode}\ntask: ${result.scope.taskId}\nselected paths: ${result.scope.selectedPaths.length}\npath: ${result.path}\n\n`;
+}

package/src/commands/workspace-bind.js

@@ -0,0 +1,17 @@
+import { bindTaskWorkspace } from "../core/workspace-binding.js";
+
+export async function runWorkspaceBind({ target, packageRoot, taskId, now } = {}) {
+  return bindTaskWorkspace(target, { taskId, packageRoot, now });
+}
+
+export function formatWorkspaceBindResult(result) {
+  return [
+    `FORGELOOP WORKSPACE BIND: ${result.status}`,
+    `task: ${result.taskId}`,
+    `binding: ${result.path}`,
+    `workspace: ${result.binding.workspaceIdentity}`,
+    `repository: ${result.binding.repositoryIdentity}`,
+    `already bound: ${result.alreadyBound ? "yes" : "no"}`,
+    "",
+  ].join("\n");
+}

package/src/commands/workspace-status.js

@@ -0,0 +1,19 @@
+import { resolveWorkspaceBindingStatus } from "../core/workspace-binding.js";
+
+export async function runWorkspaceStatus({ target, packageRoot, taskId } = {}) {
+  return resolveWorkspaceBindingStatus(target, { taskId, packageRoot });
+}
+
+export function formatWorkspaceStatusResult(result) {
+  const lines = [
+    `FORGELOOP WORKSPACE: ${result.status}`,
+    `task: ${result.taskId}`,
+    `binding: ${result.path}`,
+  ];
+  if (result.binding) {
+    lines.push(`workspace: ${result.binding.workspaceIdentity}`);
+    lines.push(`repository: ${result.binding.repositoryIdentity}`);
+  }
+  if (result.error) lines.push(`${result.error.code}: ${result.error.message}`);
+  return `${lines.join("\n")}\n`;
+}

package/src/core/artifact-registry.js

@@ -283,4 +283,88 @@ export const ARTIFACT_REGISTRY = Object.freeze({
     isPersisted: true,
     description: "Immutable trajectory evaluation results compiled from the canonical trace against a local reference scenario.",
   }),
+  workspaceBinding: Object.freeze({
+    key: "workspaceBinding",
+    scope: "TASK",
+    path: `${TASK_STATE_ROOT}/<task-key>/${TASK_ARTIFACT_FILES.workspaceBinding}`,
+    schema: "workspace-binding",
+    owner: "PROTOCOL_GENERATED",
+    mutability: "IMMUTABLE_AFTER_BIND",
+    trustRole: "WORKSPACE_IDENTITY_BINDING",
+    isPublic: true,
+    isPersisted: true,
+    description: "Optional task binding to the exact Git worktree identity used for ForgeLoop mutation and verification.",
+  }),
+  handoffs: Object.freeze({
+    key: "handoffs",
+    scope: "TASK",
+    path: `${TASK_STATE_ROOT}/<task-key>/${TASK_ARTIFACT_FILES.handoffs}/handoff-<id>.json`,
+    schema: "handoff-envelope",
+    owner: "PROTOCOL_COMPILED",
+    mutability: "IMMUTABLE_ONCE_WRITTEN",
+    trustRole: "CANONICAL_HANDOFF_SNAPSHOT",
+    isPublic: true,
+    isPersisted: true,
+    description: "Immutable protocol-derived handoff snapshots; not delegation, review, completion, or authority evidence.",
+  }),
+  responsibility: Object.freeze({
+    key: "responsibility",
+    scope: "TASK",
+    path: `${TASK_STATE_ROOT}/<task-key>/${TASK_ARTIFACT_FILES.responsibility}`,
+    schema: "responsibility",
+    owner: "AGENT_OR_HARNESS_CONSTRAINED",
+    mutability: "IMMUTABLE_DURING_PASS",
+    trustRole: "RESPONSIBILITY_CONSTRAINT",
+    isPublic: true,
+    isPersisted: true,
+    description: "Optional mechanically verifiable pass constraints for allowed, read-only, frozen, and required-check paths.",
+  }),
+  verificationScope: Object.freeze({
+    key: "verificationScope",
+    scope: "TASK",
+    path: `${TASK_STATE_ROOT}/<task-key>/${TASK_ARTIFACT_FILES.verificationScope}`,
+    schema: "verification-scope",
+    owner: "PROTOCOL_COMPILED",
+    mutability: "RECOMPUTED_ON_SCOPE_CHANGE",
+    trustRole: "VERIFICATION_SCOPE_PLAN",
+    isPublic: true,
+    isPersisted: true,
+    description: "Read-only planning boundary for changed, claimed, full, or explicitly unresolved verification.",
+  }),
+  codeManifest: Object.freeze({
+    key: "codeManifest",
+    scope: "TASK",
+    path: `${TASK_STATE_ROOT}/<task-key>/${TASK_ARTIFACT_FILES.attestations}/code-manifest.json`,
+    schema: "code-manifest",
+    owner: "PROTOCOL_GENERATED",
+    mutability: "IMMUTABLE_ONCE_WRITTEN",
+    trustRole: "CONTENT_INTEGRITY_SNAPSHOT",
+    isPublic: true,
+    isPersisted: true,
+    description: "ForgeLoop SHA-256 source-content snapshot bound to final completion evidence.",
+  }),
+  attestationStatement: Object.freeze({
+    key: "attestationStatement",
+    scope: "TASK",
+    path: `${TASK_STATE_ROOT}/<task-key>/${TASK_ARTIFACT_FILES.attestations}/statement.json`,
+    schema: "in-toto-statement",
+    owner: "PROTOCOL_COMPILED",
+    mutability: "IMMUTABLE_ONCE_WRITTEN",
+    trustRole: "CODE_ATTESTATION_STATEMENT",
+    isPublic: true,
+    isPersisted: true,
+    description: "Deterministic in-toto Statement v1 predicate binding source content to ForgeLoop evidence.",
+  }),
+  attestationBundle: Object.freeze({
+    key: "attestationBundle",
+    scope: "TASK",
+    path: `${TASK_STATE_ROOT}/<task-key>/${TASK_ARTIFACT_FILES.attestations}/statement.sigstore.json`,
+    schema: null,
+    owner: "EXTERNAL_SIGNING_PROVIDER",
+    mutability: "EXTERNAL_IMMUTABLE",
+    trustRole: "EXTERNAL_SIGNATURE_BUNDLE",
+    isPublic: true,
+    isPersisted: true,
+    description: "Optional external signing-provider bundle; existence alone never establishes a valid signature.",
+  }),
 });

package/src/core/attestation-coverage.js

@@ -0,0 +1,134 @@
+import { getPackageRoot } from "./templates.js";
+import { discoverTasks } from "./task-discovery.js";
+import { readCodeManifest, validateCodeManifestBindings } from "./code-manifest.js";
+import { readAttestationStatement } from "./attestation.js";
+import { resolveRevisionProvider } from "./revision/provider.js";
+import { REVISION_PROVIDERS } from "./revision/registry.js";
+import { assertAttestationStatementBindings, verifyCodeManifestContent } from "./attestation-verifier.js";
+import { taskAttestationBundlePath } from "./task-paths.js";
+
+function pathMatchesExclusion(pathValue, exclusions) {
+  return exclusions.some((pattern) => {
+    const normalized = String(pattern).replaceAll("\\", "/");
+    if (normalized.endsWith("/**")) return pathValue === normalized.slice(0, -3) || pathValue.startsWith(normalized.slice(0, -2));
+    return pathValue === normalized;
+  });
+}
+
+function changedPathNames(entry) {
+  return [entry.path, entry.sourcePath].filter(Boolean);
+}
+
+function isProtocolMetadataPath(value) {
+  const normalized = String(value).replaceAll("\\", "/").replace(/^\.\//u, "");
+  return normalized === ".forgeloop" || normalized.startsWith(".forgeloop/");
+}
+
+export async function evaluateAttestationCoverage({
+  target,
+  packageRoot = getPackageRoot(),
+  revisionProvider = "git",
+  baseRevision,
+  headRevision,
+  requireCompleteCoverage = true,
+  requireSignature = false,
+  signingProvider = null,
+  signerPolicy = {},
+  exclusions = [],
+} = {}) {
+  const provider = typeof revisionProvider === "string"
+    ? await resolveRevisionProvider({ target, providerName: revisionProvider, registry: REVISION_PROVIDERS })
+    : revisionProvider;
+  const changedEntries = await provider.getChangedEntries({ target, baseRevision, headRevision });
+  const changedPaths = [...new Set(changedEntries.flatMap(changedPathNames)
+    .filter((value) => !isProtocolMetadataPath(value)))].sort();
+  const validAttestations = [];
+  const errors = [];
+  const tasks = await discoverTasks(target, packageRoot);
+  for (const task of tasks.filter((item) => item.healthy !== false && item.taskId)) {
+    try {
+      const statement = await readAttestationStatement({ target, packageRoot, taskId: task.taskId });
+      const manifest = await readCodeManifest({ target, packageRoot, taskId: task.taskId });
+      await validateCodeManifestBindings({ target, packageRoot, taskId: task.taskId, manifest: manifest.value, revisionProvider: provider });
+      assertAttestationStatementBindings(statement.value, manifest.value, task.taskId, manifest.fingerprint);
+      await verifyCodeManifestContent({ target, manifest: manifest.value, revisionProvider: provider, revision: headRevision });
+      let signatureStatus = "UNSIGNED";
+      if (requireSignature) {
+        const { verifyAttestation } = await import("./attestation-verifier.js");
+        const verified = await verifyAttestation({
+          target,
+          packageRoot,
+          taskId: task.taskId,
+          revision: headRevision,
+          revisionProvider: provider,
+          requireSignature: true,
+          signingProvider,
+          bundlePath: taskAttestationBundlePath(task.taskId),
+          identity: signerPolicy.identity,
+          issuer: signerPolicy.issuer,
+          trustedRoot: signerPolicy.trustedRoot,
+        });
+        signatureStatus = verified.signature.status;
+        if (verified.status !== "VALID") {
+          const error = new Error(verified.errors[0]?.message ?? "Signature verification failed");
+          error.code = verified.errors[0]?.code ?? "E_ATTESTATION_SIGNATURE_INVALID";
+          throw error;
+        }
+      }
+      validAttestations.push({
+        taskId: task.taskId,
+        statement,
+        manifest: manifest.value,
+        signatureStatus,
+      });
+    } catch (error) {
+      if (error.code !== "E_ATTESTATION_STATEMENT_MISSING" && error.code !== "E_ATTESTATION_MANIFEST_MISSING") {
+        errors.push({ taskId: task.taskId, code: error.code ?? "E_ATTESTATION_INVALID", message: error.message });
+      }
+    }
+  }
+  const coveredByPath = new Map();
+  const overlaps = [];
+  for (const attestation of validAttestations) {
+    for (const entry of attestation.manifest.entries) {
+      for (const name of changedPathNames(entry)) {
+        const digest = entry.kind === "DELETED" ? "DELETED" : entry.sha256 ?? entry.providerContentId ?? "UNKNOWN";
+        const existing = coveredByPath.get(name);
+        if (existing && existing.digest !== digest) {
+          errors.push({ code: "E_ATTESTATION_COVERAGE_CONFLICT", message: `Conflicting attestation content for ${name}`, path: name, tasks: [existing.taskId, attestation.taskId] });
+        } else if (existing) {
+          overlaps.push({ path: name, tasks: [...new Set([existing.taskId, attestation.taskId])] });
+        } else {
+          coveredByPath.set(name, { taskId: attestation.taskId, digest });
+        }
+      }
+    }
+  }
+  const excluded = changedPaths.filter((item) => pathMatchesExclusion(item, exclusions));
+  const uncoveredPaths = changedPaths.filter((item) => !pathMatchesExclusion(item, exclusions) && !coveredByPath.has(item));
+  if (requireCompleteCoverage && uncoveredPaths.length > 0) errors.push({ code: "E_ATTESTATION_COVERAGE_GAP", message: `Changed source paths are not covered by valid attestations: ${uncoveredPaths.join(", ")}`, paths: uncoveredPaths });
+  const status = errors.length === 0 && (!requireCompleteCoverage || uncoveredPaths.length === 0) ? "VALID" : "INVALID";
+  const signatureStatus = requireSignature
+    ? (validAttestations.every((item) => item.signatureStatus === "VALID") && (validAttestations.length > 0 || changedPaths.length === 0) ? "VALID" : "INVALID")
+    : "UNSIGNED";
+  return {
+    schemaVersion: 1,
+    status,
+    level: status === "VALID" ? (requireSignature ? "ATTESTED" : "VERIFIED") : "PROCESSED",
+    revisionProvider: provider.name ?? "unknown",
+    baseRevision,
+    headRevision,
+    changedPaths: changedPaths.length,
+    coveredPaths: [...coveredByPath.keys()].filter((item) => !excluded.includes(item)).length,
+    uncoveredPaths,
+    tasks: validAttestations.length,
+    overlaps,
+    errors,
+    signature: {
+      required: requireSignature,
+      status: signatureStatus,
+      ...(signerPolicy.identity ? { identity: signerPolicy.identity } : {}),
+      ...(signerPolicy.issuer ? { issuer: signerPolicy.issuer } : {}),
+    },
+  };
+}

package/src/core/attestation-verifier.js

@@ -0,0 +1,227 @@
+import { createHash } from "node:crypto";
+
+import { canonicalFingerprint } from "./artifacts.js";
+import { getPackageRoot } from "./templates.js";
+import { readCodeManifest, validateCodeManifestBindings } from "./code-manifest.js";
+import { readAttestationStatement, validateAttestationStatement } from "./attestation.js";
+import { assertRevisionProvider, resolveRevisionProvider } from "./revision/provider.js";
+import { REVISION_PROVIDERS } from "./revision/registry.js";
+import { assertSigningProvider, resolveSigningProvider } from "./signing/provider.js";
+import { SIGNING_PROVIDERS } from "./signing/registry.js";
+import { taskAttestationBundlePath, taskAttestationStatementPath } from "./task-paths.js";
+import { ensureWithin, fileExists } from "./filesystem.js";
+import { E_ATTESTATION_CONFIGURATION_INVALID } from "./error-codes.js";
+
+function verifierError(code, message, artifacts = []) {
+  const error = new Error(message);
+  error.name = "AttestationVerificationError";
+  error.code = code;
+  error.artifacts = artifacts;
+  return error;
+}
+
+function sha256(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+export function assertAttestationStatementBindings(statement, manifest, taskId, manifestFingerprint = canonicalFingerprint(manifest)) {
+  const predicate = statement.predicate;
+  if (predicate.task.taskId !== taskId || predicate.task.verificationCycle !== manifest.verificationCycle) {
+    throw verifierError("E_ATTESTATION_SCOPE_MISMATCH", "Attestation statement task or verification cycle does not match the manifest");
+  }
+  if (predicate.content.manifestFingerprint !== manifestFingerprint) {
+    throw verifierError("E_ATTESTATION_SUBJECT_MISMATCH", "Statement does not bind the current code manifest");
+  }
+  if (predicate.content.contentDigest !== manifest.contentDigest) {
+    throw verifierError("E_ATTESTATION_SUBJECT_MISMATCH", "Statement subject does not bind the manifest content digest");
+  }
+  const expectedPaths = [...new Set(manifest.entries.flatMap((entry) => [entry.path, entry.sourcePath].filter(Boolean)))].sort();
+  const actualPaths = [...new Set(predicate.content.coveredPaths)].sort();
+  if (JSON.stringify(expectedPaths) !== JSON.stringify(actualPaths)) {
+    throw verifierError("E_ATTESTATION_SCOPE_MISMATCH", "Statement covered paths do not match the manifest");
+  }
+  const bindingPairs = [
+    ["contractFingerprint", "E_ATTESTATION_CONTRACT_MISMATCH"],
+    ["routeFingerprint", "E_ATTESTATION_ROUTE_MISMATCH"],
+    ["stateFingerprint", "E_ATTESTATION_STATE_MISMATCH"],
+    ["receiptFingerprint", "E_ATTESTATION_RECEIPT_MISMATCH"],
+    ["ledgerSeq", "E_ATTESTATION_LEDGER_MISMATCH"],
+    ["ledgerHash", "E_ATTESTATION_LEDGER_MISMATCH"],
+  ];
+  for (const [key, code] of bindingPairs) {
+    if (predicate.evidence[key] !== manifest.bindings[key]) {
+      throw verifierError(code, `Statement evidence does not match the manifest binding: ${key}`);
+    }
+  }
+}
+
+async function verifyEntryContent(provider, { target, revision }, entry) {
+  if (entry.kind === "DELETED" || entry.operation === "DELETED") {
+    try {
+      await provider.readContent({ target, revision, path: entry.path });
+      throw verifierError("E_ATTESTATION_CONTENT_MISMATCH", `Deleted path exists at revision ${revision}: ${entry.path}`);
+    } catch (error) {
+      if (error.code === "E_ATTESTATION_CONTENT_MISMATCH") throw error;
+      if (error.notFound === true) return { valid: true };
+      throw verifierError("E_ATTESTATION_CONTENT_MISMATCH", `Unable to prove that deleted path is absent at revision ${revision}: ${entry.path}`, [entry.path]);
+    }
+  }
+  if (entry.kind === "GITLINK") {
+    let identity;
+    try {
+      identity = await provider.getContentIdentity({ target, revision, path: entry.path });
+    } catch (error) {
+      if (error.notFound === true) throw verifierError("E_ATTESTATION_CONTENT_MISMATCH", `Gitlink is absent at revision ${revision}: ${entry.path}`, [entry.path]);
+      throw error;
+    }
+    if (identity !== entry.providerContentId) {
+      throw verifierError("E_ATTESTATION_CONTENT_MISMATCH", `Gitlink identity differs from the attested snapshot: ${entry.path}`, [entry.path]);
+    }
+    return { valid: true, actualIdentity: identity };
+  }
+  let bytes;
+  try {
+    bytes = await provider.readContent({ target, revision, path: entry.path });
+  } catch (error) {
+    if (error.code?.startsWith("E_REVISION_") && error.notFound !== true) throw error;
+    throw verifierError("E_ATTESTATION_CONTENT_MISMATCH", `Attested path cannot be read at revision ${revision}: ${entry.path}`, [entry.path]);
+  }
+  const actualDigest = sha256(bytes);
+  if (actualDigest !== entry.sha256) {
+    throw verifierError("E_ATTESTATION_CONTENT_MISMATCH", `Current source content differs from the attested snapshot: ${entry.path}`, [entry.path]);
+  }
+  if (entry.providerContentId) {
+    let actualIdentity;
+    try {
+      actualIdentity = await provider.getContentIdentity({ target, revision, path: entry.path });
+    } catch (error) {
+      if (error.code?.startsWith("E_REVISION_") && error.notFound !== true) throw error;
+      throw verifierError("E_ATTESTATION_CONTENT_MISMATCH", `Attested provider identity cannot be read at revision ${revision}: ${entry.path}`, [entry.path]);
+    }
+    if (actualIdentity !== entry.providerContentId) {
+      throw verifierError("E_ATTESTATION_CONTENT_MISMATCH", `Provider content identity differs from the attested snapshot: ${entry.path}`, [entry.path]);
+    }
+  }
+  return { valid: true, actualDigest };
+}
+
+export async function verifyCodeManifestContent({ target, manifest, revisionProvider, revision = null } = {}) {
+  const provider = typeof revisionProvider === "string"
+    ? await resolveRevisionProvider({ target, providerName: revisionProvider, registry: REVISION_PROVIDERS })
+    : revisionProvider;
+  assertRevisionProvider(provider);
+  const targetRevision = revision ?? (manifest.capture.mode === "WORKTREE" ? "WORKTREE" : manifest.capture.observedRevision);
+  const results = [];
+  for (const entry of manifest.entries) {
+    results.push({ path: entry.path, ...(await verifyEntryContent(provider, { target, revision: targetRevision }, entry)) });
+  }
+  return { valid: true, revision: targetRevision, results, provider };
+}
+
+export async function verifyAttestation({
+  target,
+  packageRoot = getPackageRoot(),
+  taskId,
+  revision = null,
+  bundlePath = null,
+  identity = null,
+  issuer = null,
+  revisionProvider = null,
+  signingProvider = null,
+  trustedRoot = null,
+  requireSignature = false,
+} = {}) {
+  let effectiveRequireSignature = requireSignature === true;
+  let effectiveSigningProvider = signingProvider;
+  let effectiveBundlePath = bundlePath;
+  let configuredPolicy = {};
+  let configurationError = null;
+  try {
+    const { readConfig } = await import("./config.js");
+    const config = await readConfig(target, packageRoot);
+    const signing = config.attestation?.signing ?? {};
+    effectiveRequireSignature ||= signing.required === true;
+    effectiveSigningProvider ??= signing.provider;
+    configuredPolicy = signing.policy ?? {};
+  } catch (error) {
+    if (error.code !== "ARTIFACT_MISSING") configurationError = error;
+  }
+  if (effectiveRequireSignature && !effectiveBundlePath) effectiveBundlePath = taskAttestationBundlePath(taskId);
+  const result = {
+    schemaVersion: 1,
+    status: "INVALID",
+    level: "PROCESSED",
+    taskId,
+    revisionProvider: typeof revisionProvider === "string" ? revisionProvider : "git",
+    revision: revision ?? null,
+    content: { status: "NOT_CHECKED", checkedPaths: 0 },
+    receipt: "NOT_CHECKED",
+    statement: "NOT_CHECKED",
+    ledger: "NOT_CHECKED",
+    signature: { required: effectiveRequireSignature, status: effectiveRequireSignature ? "UNAVAILABLE" : "NOT_CHECKED" },
+    errors: [],
+  };
+  if (configurationError) {
+    result.errors.push({ code: E_ATTESTATION_CONFIGURATION_INVALID, message: configurationError.message });
+    return result;
+  }
+  try {
+    const statementArtifact = await readAttestationStatement({ target, packageRoot, taskId });
+    const manifestArtifact = await readCodeManifest({ target, packageRoot, taskId });
+    await validateAttestationStatement(statementArtifact.value, packageRoot);
+    result.statement = "VALID";
+    result.ledger = "VALID";
+    result.receipt = "VALID";
+    assertAttestationStatementBindings(
+      statementArtifact.value,
+      manifestArtifact.value,
+      taskId,
+      manifestArtifact.fingerprint,
+    );
+    const provider = typeof revisionProvider === "string"
+      ? await resolveRevisionProvider({ target, providerName: revisionProvider, registry: REVISION_PROVIDERS })
+      : revisionProvider ?? await resolveRevisionProvider({ target, providerName: manifestArtifact.value.capture.revisionProvider, registry: REVISION_PROVIDERS });
+    result.revisionProvider = provider.name ?? result.revisionProvider;
+    await validateCodeManifestBindings({ target, packageRoot, taskId, manifest: manifestArtifact.value, revisionProvider: provider });
+    const content = await verifyCodeManifestContent({ target, manifest: manifestArtifact.value, revisionProvider: provider, revision });
+    result.revision = content.revision;
+    result.content = { status: "VALID", checkedPaths: content.results.length };
+    const signingPolicy = {
+      ...configuredPolicy,
+      identity,
+      issuer,
+      ...(trustedRoot ? { trustedRoot } : {}),
+    };
+    if (effectiveRequireSignature && !(await fileExists(ensureWithin(target, effectiveBundlePath)))) {
+      throw verifierError("E_ATTESTATION_UNSIGNED", `Required attestation signature bundle is missing: ${effectiveBundlePath}`);
+    }
+    const signer = typeof effectiveSigningProvider === "object"
+      ? assertSigningProvider(effectiveSigningProvider)
+      : await resolveSigningProvider({
+        providerName: effectiveSigningProvider ?? (effectiveBundlePath ? "sigstore" : "none"),
+        registry: SIGNING_PROVIDERS,
+      });
+    const signature = await signer.verify({
+      target,
+      statementPath: taskAttestationStatementPath(taskId),
+      bundlePath: effectiveBundlePath,
+      policy: signingPolicy,
+    });
+    result.signature = {
+      required: effectiveRequireSignature,
+      status: signature.status,
+      provider: signer.name,
+      ...(identity ? { identity } : {}),
+      ...(issuer ? { issuer } : {}),
+    };
+    if (effectiveRequireSignature && signature.status !== "VALID") {
+      throw verifierError(signature.code ?? "E_ATTESTATION_SIGNATURE_INVALID", signature.message ?? "Required signature is not valid");
+    }
+    result.status = "VALID";
+    result.level = signature.status === "VALID" ? "ATTESTED" : "VERIFIED";
+    return result;
+  } catch (error) {
+    result.errors.push({ code: error.code ?? "E_ATTESTATION_STATEMENT_INVALID", message: error.message, ...(error.artifacts ? { artifacts: error.artifacts } : {}) });
+    return result;
+  }
+}