@cassiomc1/forgeloop 1.6.2 → 1.6.4

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

package/src/core/workspace-binding.js

@@ -0,0 +1,211 @@
+import path from "node:path";
+import { realpath } from "node:fs/promises";
+
+import { appendProtocolEvent } from "./events.js";
+import { canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
+import { assertSchema, readSchema } from "./schema-validation.js";
+import { assertSecretFree } from "./receipt.js";
+import { getPackageRoot } from "./templates.js";
+import {
+  taskWorkspaceBindingPath,
+} from "./task-paths.js";
+import {
+  currentRepositoryFingerprint,
+  repositoryWorktreeMetadata,
+} from "./repository.js";
+import { withTaskTransaction } from "./transaction.js";
+import { assertTaskMutationAllowed } from "./task-claim-state.js";
+
+const SHA256 = /^[a-f0-9]{64}$/u;
+
+function bindingError(code, message, artifacts = []) {
+  const error = new Error(message);
+  error.name = "WorkspaceBindingError";
+  error.code = code;
+  if (artifacts.length > 0) error.artifacts = artifacts;
+  return error;
+}
+
+function normalizeIdentityPath(value) {
+  const normalized = path.normalize(value).replaceAll("\\", "/");
+  return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+async function absoluteGitPath(target, value) {
+  const candidate = path.isAbsolute(value) ? value : path.resolve(target, value);
+  try {
+    return normalizeIdentityPath(await realpath(candidate));
+  } catch {
+    return normalizeIdentityPath(candidate);
+  }
+}
+
+export async function captureWorkspaceIdentity(target) {
+  let metadata;
+  try {
+    metadata = await repositoryWorktreeMetadata(target);
+  } catch (error) {
+    throw bindingError(
+      "E_WORKSPACE_IDENTITY_UNAVAILABLE",
+      "The current directory is not a Git worktree whose identity ForgeLoop can prove",
+      error?.artifacts ?? [],
+    );
+  }
+
+  const commonDirectory = await absoluteGitPath(target, metadata.commonDirectory);
+  const gitDirectory = await absoluteGitPath(target, metadata.gitDirectory);
+  const topLevel = await absoluteGitPath(target, metadata.topLevel);
+  const repositoryIdentity = canonicalFingerprint({
+    commonDirectory,
+    objectFormat: metadata.objectFormat,
+  });
+  const workspaceIdentity = canonicalFingerprint({
+    commonDirectory,
+    gitDirectory,
+    topLevel,
+    objectFormat: metadata.objectFormat,
+  });
+  const repositoryFingerprint = await currentRepositoryFingerprint(target);
+  return {
+    repositoryIdentity,
+    workspaceIdentity,
+    branchAtBind: repositoryFingerprint.branch,
+    headAtBind: repositoryFingerprint.head,
+    metadata: { objectFormat: metadata.objectFormat },
+  };
+}
+
+export async function validateWorkspaceBinding(binding, packageRoot = getPackageRoot()) {
+  try {
+    const schema = await readSchema("workspace-binding", packageRoot);
+    assertSchema(binding, schema, "workspace binding");
+  } catch (error) {
+    throw bindingError("E_WORKSPACE_BINDING_INVALID", error.message);
+  }
+  if (!SHA256.test(binding.repositoryIdentity) || !SHA256.test(binding.workspaceIdentity)) {
+    throw bindingError("E_WORKSPACE_BINDING_INVALID", "Workspace binding identities must be lowercase SHA-256 values");
+  }
+  assertSecretFree(binding);
+  return binding;
+}
+
+export async function readWorkspaceBinding(target, { taskId, packageRoot = getPackageRoot() } = {}) {
+  if (!taskId) throw bindingError("E_WORKSPACE_BINDING_INVALID", "taskId is required to read a workspace binding");
+  const relativePath = taskWorkspaceBindingPath(taskId);
+  try {
+    const artifact = await readJsonArtifact(target, relativePath, "workspace-binding", packageRoot);
+    await validateWorkspaceBinding(artifact.value, packageRoot);
+    if (artifact.value.taskId !== taskId) {
+      throw bindingError("E_WORKSPACE_BINDING_INVALID", "Workspace binding taskId does not match its task namespace", [relativePath]);
+    }
+    return { ...artifact, value: artifact.value };
+  } catch (error) {
+    if (error.code === "ARTIFACT_MISSING") return null;
+    if (error.code === "E_WORKSPACE_BINDING_INVALID") throw error;
+    throw bindingError("E_WORKSPACE_BINDING_INVALID", `Workspace binding is invalid: ${error.message}`, [relativePath]);
+  }
+}
+
+export async function resolveWorkspaceBindingStatus(target, { taskId, packageRoot = getPackageRoot() } = {}) {
+  const relativePath = taskWorkspaceBindingPath(taskId);
+  let artifact;
+  try {
+    artifact = await readWorkspaceBinding(target, { taskId, packageRoot });
+  } catch (error) {
+    return {
+      status: "INVALID",
+      taskId,
+      path: relativePath,
+      binding: null,
+      current: null,
+      error: { code: error.code ?? "E_WORKSPACE_BINDING_INVALID", message: error.message },
+    };
+  }
+  if (!artifact) return { status: "UNBOUND", taskId, path: relativePath, binding: null, current: null };
+
+  let current;
+  try {
+    current = await captureWorkspaceIdentity(target);
+  } catch (error) {
+    return {
+      status: "UNAVAILABLE",
+      taskId,
+      path: relativePath,
+      binding: artifact.value,
+      bindingFingerprint: artifact.fingerprint,
+      current: null,
+      error: { code: error.code ?? "E_WORKSPACE_IDENTITY_UNAVAILABLE", message: error.message },
+    };
+  }
+  const matches = artifact.value.repositoryIdentity === current.repositoryIdentity
+    && artifact.value.workspaceIdentity === current.workspaceIdentity;
+  return {
+    status: matches ? "MATCH" : "MISMATCH",
+    taskId,
+    path: relativePath,
+    binding: artifact.value,
+    bindingFingerprint: artifact.fingerprint,
+    current,
+  };
+}
+
+export async function assertWorkspaceBinding(target, { taskId, packageRoot = getPackageRoot(), operation = "mutation" } = {}) {
+  const result = await resolveWorkspaceBindingStatus(target, { taskId, packageRoot });
+  if (result.status === "UNBOUND" || result.status === "MATCH") return result;
+  const code = result.status === "MISMATCH"
+    ? "E_WORKSPACE_BINDING_MISMATCH"
+    : result.status === "UNAVAILABLE"
+      ? "E_WORKSPACE_IDENTITY_UNAVAILABLE"
+      : "E_WORKSPACE_BINDING_INVALID";
+  const message = result.status === "MISMATCH"
+    ? `Workspace binding does not match the current Git worktree before ${operation}`
+    : result.status === "UNAVAILABLE"
+      ? `Current Git worktree identity is unavailable before ${operation}`
+      : `Workspace binding is invalid before ${operation}`;
+  throw bindingError(code, message, [result.path]);
+}
+
+export async function bindTaskWorkspace(target, { taskId, packageRoot = getPackageRoot(), now = new Date().toISOString() } = {}) {
+  if (!taskId) throw bindingError("E_WORKSPACE_BINDING_INVALID", "workspace-bind requires an explicit taskId");
+  const relativePath = taskWorkspaceBindingPath(taskId);
+  return withTaskTransaction({ target, taskId, packageRoot, operation: "workspace-bind", recordCommitEvent: true }, async () => {
+    await assertTaskMutationAllowed(target, { taskId, packageRoot });
+    const existing = await readWorkspaceBinding(target, { taskId, packageRoot });
+    const current = await captureWorkspaceIdentity(target);
+    if (existing) {
+      if (existing.value.repositoryIdentity === current.repositoryIdentity
+        && existing.value.workspaceIdentity === current.workspaceIdentity) {
+        return {
+          taskId,
+          status: "MATCH",
+          bound: false,
+          alreadyBound: true,
+          path: relativePath,
+          binding: existing.value,
+          fingerprint: existing.fingerprint,
+        };
+      }
+      throw bindingError("E_WORKSPACE_BINDING_MISMATCH", "Task is already bound to a different Git worktree; unrestricted rebinding is not supported", [relativePath]);
+    }
+    const binding = await validateWorkspaceBinding({
+      schemaVersion: 1,
+      protocolVersion: 1,
+      taskId,
+      mode: "GIT_WORKTREE",
+      repositoryIdentity: current.repositoryIdentity,
+      workspaceIdentity: current.workspaceIdentity,
+      branchAtBind: current.branchAtBind,
+      headAtBind: current.headAtBind,
+      boundAt: now,
+      metadata: current.metadata,
+    }, packageRoot);
+    const artifact = await writeJsonArtifact(target, relativePath, binding, "workspace-binding", packageRoot, { taskId, operation: "workspace-bind" });
+    await appendProtocolEvent(target, {
+      taskId,
+      event: "WORKSPACE_BOUND",
+      fingerprint: artifact.fingerprint,
+      details: { workspaceFingerprint: artifact.fingerprint },
+    }, packageRoot, { taskId });
+    return { taskId, status: "MATCH", bound: true, alreadyBound: false, path: relativePath, binding, fingerprint: artifact.fingerprint };
+  });
+}