@cassiomc1/forgeloop 1.6.3 → 1.6.5

package/src/core/task-paths.js

@@ -20,6 +20,11 @@ export const TASK_ARTIFACT_FILES = Object.freeze({
   evaluations: "evaluations",
   policySnapshot: "policy-snapshot.json",
   recovery: "recovery.json",
+  workspaceBinding: "workspace-binding.json",
+  handoffs: "handoffs",
+  responsibility: "responsibility.json",
+  verificationScope: "verification-scope.json",
+  attestations: "attestations",
 });
 
 export const POLICY_ROOT = ".forgeloop/policy";
@@ -99,6 +104,65 @@ export function taskEvaluationPath(taskId, evaluationId) {
   return `${taskDirectory(taskId)}/${TASK_ARTIFACT_FILES.evaluations}/${evaluationId}.json`;
 }
 
+function assertArtifactId(value, pattern, label) {
+  if (typeof value !== "string" || !pattern.test(value)) {
+    throw new Error(`Invalid ${label}: ${value}`);
+  }
+  return value;
+}
+
+export function taskWorkspaceBindingPath(taskId) {
+  return taskArtifactPath(taskId, "workspaceBinding");
+}
+
+export function taskResponsibilityPath(taskId) {
+  return taskArtifactPath(taskId, "responsibility");
+}
+
+export function taskVerificationScopePath(taskId) {
+  return taskArtifactPath(taskId, "verificationScope");
+}
+
+export function taskHandoffDirectory(taskId) {
+  return taskArtifactPath(taskId, "handoffs");
+}
+
+export function taskHandoffPath(taskId, handoffId) {
+  assertArtifactId(handoffId, /^handoff-[A-Za-z0-9_-]+$/, "handoff ID");
+  return `${taskHandoffDirectory(taskId)}/${handoffId}.json`;
+}
+
+export function taskAttestationDirectory(taskId) {
+  return taskArtifactPath(taskId, "attestations");
+}
+
+export function taskCodeManifestPath(taskId) {
+  return `${taskAttestationDirectory(taskId)}/code-manifest.json`;
+}
+
+export function taskAttestationStatementPath(taskId) {
+  return `${taskAttestationDirectory(taskId)}/statement.json`;
+}
+
+export function taskAttestationBundlePath(taskId) {
+  return `${taskAttestationDirectory(taskId)}/statement.sigstore.json`;
+}
+
+export function taskAttestationHistoryDirectory(taskId, verificationCycle) {
+  if (!Number.isInteger(verificationCycle) || verificationCycle < 1) {
+    throw new Error(`Invalid attestation verification cycle: ${verificationCycle}`);
+  }
+  return `${taskAttestationDirectory(taskId)}/history/cycle-${verificationCycle}`;
+}
+
+export function taskCodeManifestHistoryPath(taskId, verificationCycle) {
+  return `${taskAttestationHistoryDirectory(taskId, verificationCycle)}/code-manifest.json`;
+}
+
+export function taskAttestationStatementHistoryPath(taskId, verificationCycle) {
+  return `${taskAttestationHistoryDirectory(taskId, verificationCycle)}/statement.json`;
+}
+
 export function taskLockPath(taskId) {
   assertTaskId(taskId);
   return `${TASK_LOCK_ROOT}/${taskStorageKey(taskId)}.lock`;
@@ -132,5 +196,13 @@ export function buildTaskArtifactPaths(taskId) {
     lock: taskLockPath(taskId),
     policySnapshot: `${dir}/${TASK_ARTIFACT_FILES.policySnapshot}`,
     recovery: `${dir}/${TASK_ARTIFACT_FILES.recovery}`,
+    workspaceBinding: `${dir}/${TASK_ARTIFACT_FILES.workspaceBinding}`,
+    handoffs: `${dir}/${TASK_ARTIFACT_FILES.handoffs}`,
+    responsibility: `${dir}/${TASK_ARTIFACT_FILES.responsibility}`,
+    verificationScope: `${dir}/${TASK_ARTIFACT_FILES.verificationScope}`,
+    attestations: `${dir}/${TASK_ARTIFACT_FILES.attestations}`,
+    codeManifest: taskCodeManifestPath(taskId),
+    attestationStatement: taskAttestationStatementPath(taskId),
+    attestationBundle: taskAttestationBundlePath(taskId),
   });
 }

package/src/core/templates.js

@@ -75,6 +75,14 @@ export const TEMPLATE_PATHS = [
   "schemas/capability-policy.schema.json",
   "schemas/trajectory-evaluation.schema.json",
   "schemas/trajectory-scenario.schema.json",
+  "schemas/workspace-binding.schema.json",
+  "schemas/handoff-envelope.schema.json",
+  "schemas/responsibility.schema.json",
+  "schemas/verification-scope.schema.json",
+  "schemas/code-manifest.schema.json",
+  "schemas/code-attestation.schema.json",
+  "schemas/attestation-verification-result.schema.json",
+  "schemas/in-toto-statement.schema.json",
 ];
 
 export function getPackageRoot() {

package/src/core/verification-scope-capability.js

@@ -0,0 +1,179 @@
+import { ARTIFACT_PATHS, canonicalFingerprint, readJsonArtifact } from "./artifacts.js";
+
+export const SCOPED_CHECKER_SCOPE_MODE = "PATH_ARGUMENTS";
+export const SCOPED_CHECKER_PATH_INSERTION = "APPEND";
+export const E_VERIFICATION_SCOPE_UNRESOLVED = "E_VERIFICATION_SCOPE_UNRESOLVED";
+
+function capabilityError(message, cause = null) {
+  const error = new Error(message);
+  error.name = "VerificationScopeCapabilityError";
+  error.code = E_VERIFICATION_SCOPE_UNRESOLVED;
+  if (cause) error.cause = cause;
+  return error;
+}
+
+function nonEmptyString(value, label) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw capabilityError(`${label} must be a non-empty string`);
+  }
+  return value;
+}
+
+function argvPrefix(value, label) {
+  if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== "string" || item.trim() === "")) {
+    throw capabilityError(`${label} must be a non-empty exact argv prefix`);
+  }
+  return [...value];
+}
+
+function assertDescriptorKeys(value, label) {
+  const allowed = new Set(["checkId", "scopeMode", "argvPrefix", "pathInsertion"]);
+  const unexpected = Object.keys(value).find((key) => !allowed.has(key));
+  if (unexpected) throw capabilityError(`${label} contains unknown property: ${unexpected}`);
+}
+
+export function normalizeScopedCheckerDescriptor(value, label = "verification.checkers[]") {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw capabilityError(`${label} must be an object`);
+  }
+  assertDescriptorKeys(value, label);
+  const checkId = nonEmptyString(value.checkId, `${label}.checkId`).trim();
+  if (value.scopeMode !== SCOPED_CHECKER_SCOPE_MODE) {
+    throw capabilityError(`${label}.scopeMode must be ${SCOPED_CHECKER_SCOPE_MODE}`);
+  }
+  if (value.pathInsertion !== SCOPED_CHECKER_PATH_INSERTION) {
+    throw capabilityError(`${label}.pathInsertion must be ${SCOPED_CHECKER_PATH_INSERTION}`);
+  }
+  return {
+    checkId,
+    scopeMode: SCOPED_CHECKER_SCOPE_MODE,
+    argvPrefix: argvPrefix(value.argvPrefix, `${label}.argvPrefix`),
+    pathInsertion: SCOPED_CHECKER_PATH_INSERTION,
+  };
+}
+
+export function normalizeScopedCheckerDescriptors(value, label = "verification.checkers") {
+  if (!Array.isArray(value)) throw capabilityError(`${label} must be an array`);
+  const descriptors = value.map((item, index) => normalizeScopedCheckerDescriptor(item, `${label}[${index}]`));
+  const seen = new Set();
+  for (const descriptor of descriptors) {
+    if (seen.has(descriptor.checkId)) throw capabilityError(`${label} contains duplicate checkId: ${descriptor.checkId}`);
+    seen.add(descriptor.checkId);
+  }
+  return descriptors.sort((left, right) => left.checkId.localeCompare(right.checkId));
+}
+
+export function normalizeVerificationConfiguration(value, label = "verification") {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw capabilityError(`${label} must be an object`);
+  }
+  const unexpected = Object.keys(value).find((key) => key !== "checkers");
+  if (unexpected) throw capabilityError(`${label} contains unknown property: ${unexpected}`);
+  return {
+    checkers: normalizeScopedCheckerDescriptors(value.checkers ?? [], `${label}.checkers`),
+  };
+}
+
+export function scopedCheckerCapabilitiesFingerprint(checkers = []) {
+  return canonicalFingerprint({
+    schemaVersion: 1,
+    scopeMode: SCOPED_CHECKER_SCOPE_MODE,
+    checkers: normalizeScopedCheckerDescriptors(checkers),
+  });
+}
+
+export async function readScopedCheckerCapabilities(target, packageRoot) {
+  try {
+    const artifact = await readJsonArtifact(target, ARTIFACT_PATHS.config, "config", packageRoot);
+    const verification = artifact.value.verification;
+    const checkers = verification
+      ? normalizeVerificationConfiguration(verification).checkers
+      : [];
+    return {
+      valid: true,
+      source: "project-config",
+      checkers,
+      fingerprint: scopedCheckerCapabilitiesFingerprint(checkers),
+      error: null,
+    };
+  } catch (error) {
+    if (error.code === "ARTIFACT_MISSING") {
+      return {
+        valid: true,
+        source: "project-config",
+        checkers: [],
+        fingerprint: scopedCheckerCapabilitiesFingerprint([]),
+        error: null,
+      };
+    }
+    return {
+      valid: false,
+      source: "project-config",
+      checkers: [],
+      fingerprint: null,
+      error,
+    };
+  }
+}
+
+function equalArgv(left, right) {
+  return Array.isArray(left)
+    && Array.isArray(right)
+    && left.length === right.length
+    && left.every((item, index) => item === right[index]);
+}
+
+export function scopedCheckerArgv(checker, selectedPaths) {
+  const descriptor = normalizeScopedCheckerDescriptor(checker, "scoped checker");
+  if (!Array.isArray(selectedPaths) || selectedPaths.some((item) => typeof item !== "string" || item.length === 0)) {
+    throw capabilityError("Verification scope selectedPaths must be an array of non-empty strings");
+  }
+  return [...descriptor.argvPrefix, ...selectedPaths];
+}
+
+export async function bindVerificationScopeCommand({
+  target,
+  packageRoot,
+  checkId,
+  argv,
+  scope,
+  capabilities = null,
+} = {}) {
+  if (!scope || scope.resolvedMode === "FULL") {
+    return {
+      argv: [...argv],
+      checker: null,
+      capabilityFingerprint: null,
+    };
+  }
+  if (!["CHANGED", "CLAIMED"].includes(scope.resolvedMode)) {
+    throw capabilityError("Verification scope has no resolved narrow mode");
+  }
+  const resolvedCapabilities = capabilities ?? await readScopedCheckerCapabilities(target, packageRoot);
+  if (!resolvedCapabilities.valid) {
+    throw capabilityError("Trusted scoped-checker capability is invalid", resolvedCapabilities.error);
+  }
+  const checker = resolvedCapabilities.checkers.find((item) => item.checkId === checkId);
+  if (!checker) {
+    throw capabilityError(`No trusted scoped checker is registered for check ${checkId}`);
+  }
+  const expectedArgv = scopedCheckerArgv(checker, scope.selectedPaths);
+  if (!equalArgv(argv, expectedArgv)) {
+    const error = capabilityError("Scoped checker argv does not match the canonical scope binding");
+    error.reason = "ARGV_MISMATCH";
+    throw error;
+  }
+  return {
+    argv: expectedArgv,
+    checker,
+    capabilityFingerprint: resolvedCapabilities.fingerprint,
+  };
+}
+
+export async function requireTrustedScopedChecker({ target, packageRoot } = {}) {
+  const capabilities = await readScopedCheckerCapabilities(target, packageRoot);
+  if (!capabilities.valid || capabilities.checkers.length === 0) {
+    throw capabilityError("A trusted scoped-checker capability is required for a narrow verification scope", capabilities.error);
+  }
+  return capabilities;
+}

package/src/core/verification-scope.js

@@ -0,0 +1,271 @@
+import { canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
+import { assertSchema, readSchema } from "./schema-validation.js";
+import { getPackageRoot } from "./templates.js";
+import { currentRepositoryFingerprint } from "./repository.js";
+import { resolveRevisionProvider } from "./revision/provider.js";
+import { REVISION_PROVIDERS } from "./revision/registry.js";
+import { readScopedCheckerCapabilities } from "./verification-scope-capability.js";
+import { readContract } from "./contract.js";
+import { readPersistedRoute } from "./route-artifact.js";
+import { readWorkState } from "./work-state.js";
+import { resolveTaskClaimState } from "./task-claim-state.js";
+import { taskVerificationScopePath } from "./task-paths.js";
+import { ensureWithin, fileExists } from "./filesystem.js";
+import { appendProtocolEvent } from "./events.js";
+import { withTaskTransaction } from "./transaction.js";
+import { assertTaskMutationAllowed } from "./task-claim-state.js";
+import { assertWorkspaceBinding } from "./workspace-binding.js";
+import path from "node:path";
+
+const MODES = Object.freeze(["AUTO", "CHANGED", "CLAIMED", "FULL"]);
+
+function scopeError(code, message, artifacts = []) {
+  const error = new Error(message);
+  error.name = "VerificationScopeError";
+  error.code = code;
+  error.artifacts = artifacts;
+  return error;
+}
+
+function normalizeScopePath(value, label = "path") {
+  if (typeof value !== "string" || value.length === 0 || value.includes("\0")) {
+    throw scopeError("E_VERIFICATION_SCOPE_INVALID", `${label} must be a non-empty relative path`);
+  }
+  const replaced = value.replaceAll("\\", "/");
+  if (replaced.startsWith("/") || /^[A-Za-z]:\//u.test(replaced)) {
+    throw scopeError("E_VERIFICATION_SCOPE_INVALID", `${label} must be relative: ${value}`);
+  }
+  const normalized = path.posix.normalize(replaced);
+  const canonical = normalized.replace(/^\.\//u, "");
+  if (canonical === ".." || canonical.startsWith("../") || canonical === ".forgeloop" || canonical.startsWith(".forgeloop/")) {
+    throw scopeError("E_VERIFICATION_SCOPE_INVALID", `${label} is outside the source boundary: ${value}`);
+  }
+  if (replaced !== canonical && replaced !== `./${canonical}`) {
+    throw scopeError("E_VERIFICATION_SCOPE_INVALID", `${label} must use a canonical relative path: ${value}`);
+  }
+  return canonical;
+}
+
+function sortedPaths(paths, label = "paths") {
+  if (!Array.isArray(paths)) throw scopeError("E_VERIFICATION_SCOPE_INVALID", `${label} must be an array`);
+  return [...new Set(paths.map((value, index) => normalizeScopePath(value, `${label}[${index}]`)))].sort();
+}
+
+function pathCovered(pathValue, claims) {
+  return claims.includes(".") || claims.some((claim) => pathValue === claim || pathValue.startsWith(`${claim}/`));
+}
+
+function requirementText(requirement) {
+  return typeof requirement === "string" ? requirement : requirement?.text ?? "";
+}
+
+function requiresFullVerification(contract) {
+  return [...(contract?.value?.verification ?? []), ...(contract?.value?.successCriteria ?? [])]
+    .some((requirement) => /(?:full|entire|whole|global)\s+(?:project|repository|repo|suite|verification)|all\s+(?:tests|checks)/iu.test(requirementText(requirement)));
+}
+
+async function currentChangedPathsFromRevisionProvider(target) {
+  try {
+    const provider = await resolveRevisionProvider({ target, registry: REVISION_PROVIDERS });
+    const entries = await provider.getChangedEntries({ target, headRevision: "WORKTREE" });
+    return [...new Set(entries
+      .flatMap((entry) => [entry.path, entry.sourcePath].filter(Boolean)))].sort((left, right) => left.localeCompare(right));
+  } catch {
+    return null;
+  }
+}
+
+async function currentInputs(target, { taskId, packageRoot }) {
+  const [contract, route, state, claims, repositoryFingerprint, changedPaths, checkerCapabilities] = await Promise.all([
+    readContract(target, packageRoot, { taskId }),
+    readPersistedRoute(target, packageRoot, { taskId }),
+    readWorkState(target, { packageRoot, taskId }),
+    resolveTaskClaimState(target, { packageRoot, taskId }),
+    currentRepositoryFingerprint(target),
+    currentChangedPathsFromRevisionProvider(target),
+    readScopedCheckerCapabilities(target, packageRoot),
+  ]);
+  return {
+    contract,
+    route,
+    state,
+    claims,
+    claimsFingerprint: canonicalFingerprint(claims.effectiveWriteClaims ?? []),
+    repositoryFingerprint,
+    changedPaths: changedPaths === null ? null : sortedPaths(changedPaths),
+    checkerCapabilities,
+  };
+}
+
+function normalizeMode(value) {
+  const mode = String(value ?? "AUTO").toUpperCase();
+  if (!MODES.includes(mode)) throw scopeError("E_VERIFICATION_SCOPE_INVALID", `Unsupported verification scope mode: ${value}`);
+  return mode;
+}
+
+export async function validateVerificationScope(scope, packageRoot = getPackageRoot()) {
+  try {
+    assertSchema(scope, await readSchema("verification-scope", packageRoot), "verification scope");
+  } catch (error) {
+    throw scopeError("E_VERIFICATION_SCOPE_INVALID", error.message);
+  }
+  if (scope.taskId.length === 0 || scope.requestedMode === "IMPACTED" || scope.resolvedMode === "IMPACTED") {
+    throw scopeError("E_VERIFICATION_SCOPE_INVALID", "IMPACTED is reserved for an explicit future mapping capability");
+  }
+  const canonical = {
+    ...scope,
+    changedPaths: sortedPaths(scope.changedPaths),
+    claimedPaths: sortedPaths(scope.claimedPaths),
+    selectedPaths: sortedPaths(scope.selectedPaths),
+    reasons: [...scope.reasons],
+  };
+  return canonical;
+}
+
+export async function readVerificationScope(target, { taskId, packageRoot = getPackageRoot(), scopePath = null } = {}) {
+  const relativePath = scopePath ?? taskVerificationScopePath(taskId);
+  if (!(await fileExists(ensureWithin(target, relativePath)))) {
+    throw scopeError("E_VERIFICATION_SCOPE_INVALID", `Verification scope is missing: ${relativePath}`, [relativePath]);
+  }
+  try {
+    const artifact = await readJsonArtifact(target, relativePath, "verification-scope", packageRoot);
+    return { ...artifact, value: await validateVerificationScope(artifact.value, packageRoot) };
+  } catch (error) {
+    if (error.code === "E_VERIFICATION_SCOPE_INVALID") throw error;
+    throw scopeError("E_VERIFICATION_SCOPE_INVALID", error.message, [relativePath]);
+  }
+}
+
+export async function validateVerificationScopeFreshness(target, {
+  taskId,
+  scope,
+  packageRoot = getPackageRoot(),
+} = {}) {
+  const current = await currentInputs(target, { taskId, packageRoot });
+  const mismatches = [];
+  if (scope.taskId !== taskId) mismatches.push("taskId");
+  if (scope.verificationCycle !== (current.state?.verificationCycle ?? 1)) mismatches.push("verificationCycle");
+  if (scope.contractFingerprint !== current.contract.fingerprint) mismatches.push("contractFingerprint");
+  if (JSON.stringify(scope.repositoryFingerprint) !== JSON.stringify(current.repositoryFingerprint)) mismatches.push("repositoryFingerprint");
+  if (JSON.stringify(sortedPaths(scope.changedPaths)) !== JSON.stringify(current.changedPaths)) mismatches.push("changedPaths");
+  if (scope.claimsFingerprint && scope.claimsFingerprint !== current.claimsFingerprint) mismatches.push("claimsFingerprint");
+  if (JSON.stringify(sortedPaths(scope.claimedPaths)) !== JSON.stringify(sortedPaths(current.claims.effectiveWriteClaims ?? []))) mismatches.push("claimedPaths");
+  if (scope.checkerCapabilityFingerprint !== undefined
+    && scope.checkerCapabilityFingerprint !== current.checkerCapabilities.fingerprint) mismatches.push("checkerCapabilityFingerprint");
+  if (mismatches.length > 0) {
+    throw scopeError("E_VERIFICATION_SCOPE_STALE", `Verification scope is stale; changed bindings: ${mismatches.join(", ")}`, [taskVerificationScopePath(taskId)]);
+  }
+  return { fresh: true, current };
+}
+
+export async function resolveVerificationScope(target, {
+  taskId,
+  mode = "AUTO",
+  packageRoot = getPackageRoot(),
+  createdAt = new Date().toISOString(),
+} = {}) {
+  const requestedMode = normalizeMode(mode);
+  const inputs = await currentInputs(target, { taskId, packageRoot });
+  if (!inputs.state) throw scopeError("E_VERIFICATION_SCOPE_UNRESOLVED", "Work state is required to resolve verification scope");
+  const changedPaths = inputs.changedPaths;
+  const claimedPaths = sortedPaths(inputs.claims.effectiveWriteClaims ?? []);
+  const hasTrustedScopedChecker = inputs.checkerCapabilities.valid && inputs.checkerCapabilities.checkers.length > 0;
+  const reasons = [];
+  let resolvedMode = requestedMode;
+  let selectedPaths = [];
+  let fallback = null;
+
+  const changedIsSafe = changedPaths !== null
+    && inputs.claims.valid
+    && changedPaths.every((item) => pathCovered(item, claimedPaths));
+  if (requiresFullVerification(inputs.contract)) {
+    if (requestedMode !== "FULL") reasons.push("The current contract explicitly requires full-project verification.");
+    resolvedMode = "FULL";
+    selectedPaths = [];
+  } else if (requestedMode === "FULL") {
+    resolvedMode = "FULL";
+    reasons.push("Full verification was explicitly requested.");
+  } else if (requestedMode === "CHANGED") {
+    if (!hasTrustedScopedChecker) throw scopeError("E_VERIFICATION_SCOPE_UNRESOLVED", "CHANGED scope requires a trusted scoped-checker capability");
+    if (changedPaths === null) throw scopeError("E_VERIFICATION_SCOPE_UNRESOLVED", "CHANGED scope cannot be proved because repository changes are unavailable");
+    if (!inputs.claims.valid || !changedIsSafe) {
+      throw scopeError("E_VERIFICATION_SCOPE_UNRESOLVED", "CHANGED scope cannot be used because every changed path is not inside valid effective task claims");
+    }
+    resolvedMode = "CHANGED";
+    selectedPaths = changedPaths;
+    reasons.push("Selected exact canonical changed paths inside effective task claims.");
+  } else if (requestedMode === "CLAIMED") {
+    if (!hasTrustedScopedChecker) throw scopeError("E_VERIFICATION_SCOPE_UNRESOLVED", "CLAIMED scope requires a trusted scoped-checker capability");
+    if (!inputs.claims.valid || claimedPaths.length === 0) {
+      throw scopeError("E_VERIFICATION_SCOPE_UNRESOLVED", "CLAIMED scope cannot be proved because effective task claims are unavailable");
+    }
+    resolvedMode = "CLAIMED";
+    selectedPaths = claimedPaths;
+    reasons.push("Selected the canonical effective task claims.");
+  } else if (hasTrustedScopedChecker && changedIsSafe) {
+    resolvedMode = "CHANGED";
+    selectedPaths = changedPaths;
+    reasons.push("AUTO selected exact changed paths because a trusted scoped checker exists and all paths are inside valid effective task claims.");
+  } else if (hasTrustedScopedChecker && inputs.claims.valid && claimedPaths.length > 0 && changedPaths !== null) {
+    resolvedMode = "CLAIMED";
+    selectedPaths = claimedPaths;
+    fallback = { from: "CHANGED", to: "CLAIMED", reason: "Changed paths could not be safely narrowed to the effective claims." };
+    reasons.push("AUTO escalated to effective claims because a narrower changed-path boundary was not provable.");
+  } else {
+    resolvedMode = "FULL";
+    selectedPaths = [];
+    fallback = {
+      from: "CHANGED",
+      to: "FULL",
+      reason: hasTrustedScopedChecker
+        ? "Repository changes or claim ownership could not be proved."
+        : "No trusted scoped-checker capability was established.",
+    };
+    reasons.push(hasTrustedScopedChecker
+      ? "AUTO escalated to full verification because a narrow boundary was not provable."
+      : "AUTO selected full verification because no trusted scoped-checker capability was established.");
+  }
+
+  const scope = await validateVerificationScope({
+    schemaVersion: 1,
+    protocolVersion: 1,
+    taskId,
+    requestedMode,
+    resolvedMode,
+    verificationCycle: inputs.state.verificationCycle ?? 1,
+    changedPaths: changedPaths ?? [],
+    claimedPaths,
+    selectedPaths,
+    reasons,
+    fallback,
+    contractFingerprint: inputs.contract.fingerprint,
+    repositoryFingerprint: inputs.repositoryFingerprint,
+    claimsFingerprint: inputs.claimsFingerprint,
+    ...(inputs.checkerCapabilities.fingerprint
+      ? { checkerCapabilityFingerprint: inputs.checkerCapabilities.fingerprint }
+      : {}),
+    createdAt,
+  }, packageRoot);
+  return { scope, inputs };
+}
+
+export async function persistVerificationScope(target, scope, { taskId, packageRoot = getPackageRoot() } = {}) {
+  const relativePath = taskVerificationScopePath(taskId);
+  const artifact = await writeJsonArtifact(target, relativePath, scope, "verification-scope", packageRoot, { taskId, operation: "verify-scope" });
+  await appendProtocolEvent(target, {
+    taskId,
+    event: "VERIFICATION_SCOPE_CAPTURED",
+    fingerprint: artifact.fingerprint,
+    details: { scopeFingerprint: artifact.fingerprint, resolvedMode: scope.resolvedMode, verificationCycle: scope.verificationCycle },
+  }, packageRoot, { taskId });
+  return { path: relativePath, fingerprint: artifact.fingerprint, scope };
+}
+
+export async function captureVerificationScope(target, options = {}) {
+  return withTaskTransaction({ target, taskId: options.taskId, packageRoot: options.packageRoot, operation: "verify-scope", recordCommitEvent: true }, async () => {
+    await assertTaskMutationAllowed(target, { taskId: options.taskId, packageRoot: options.packageRoot });
+    await assertWorkspaceBinding(target, { taskId: options.taskId, packageRoot: options.packageRoot, operation: "verify-scope" });
+    const result = await resolveVerificationScope(target, options);
+    return persistVerificationScope(target, result.scope, options);
+  });
+}