owlrunkit 0.18.4 → 0.19.0

package/packages/attest/src/dependency-environment.mjs

@@ -0,0 +1,128 @@
+import {
+  existsSync,
+  lstatSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+} from "node:fs";
+import path from "node:path";
+
+import { sha256Bytes, sha256Canonical } from "./formal.mjs";
+
+const MAX_DEPENDENCY_MATERIAL_BYTES = 128 * 1024 * 1024;
+const DEPENDENCY_MATERIALS = Object.freeze([
+  "package.json",
+  "package-lock.json",
+  "npm-shrinkwrap.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  "bun.lock",
+  "bun.lockb",
+  ".pnp.cjs",
+  ".pnp.loader.mjs",
+  "node_modules/.package-lock.json",
+  "node_modules/.modules.yaml",
+]);
+
+function normalizePath(value) {
+  return value.split(path.sep).join("/");
+}
+
+function withinRoot(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === ""
+    || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+function comparePaths(left, right) {
+  return left.localeCompare(right, "en");
+}
+
+function canonicalRealDirectory(requested, label) {
+  const absolute = path.resolve(requested);
+  const stat = lstatSync(absolute);
+  if (stat.isSymbolicLink() || !stat.isDirectory() || realpathSync(absolute) !== absolute) {
+    throw new Error(`${label} must be a real directory without symlink traversal.`);
+  }
+  return absolute;
+}
+
+function dependencyMaterial(root, relativePath, budget) {
+  const absolute = path.resolve(root, ...relativePath.split("/"));
+  if (!withinRoot(root, absolute) || !existsSync(absolute)) return null;
+  const stat = lstatSync(absolute);
+  if (stat.isSymbolicLink() || !stat.isFile() || realpathSync(absolute) !== absolute) {
+    throw new Error(`Dependency binding material must be a regular non-symlink file: ${relativePath}`);
+  }
+  budget.bytes += stat.size;
+  if (budget.bytes > MAX_DEPENDENCY_MATERIAL_BYTES) {
+    throw new Error("Dependency binding material exceeds the byte limit.");
+  }
+  return { path: relativePath, sha256: sha256Bytes(readFileSync(absolute)) };
+}
+
+function installedDependencyMaterialPaths(root) {
+  const nodeModules = path.join(root, "node_modules");
+  const discovered = new Set();
+  const addRealFile = (candidate) => {
+    let resolved;
+    try {
+      resolved = realpathSync(candidate);
+    } catch {
+      return;
+    }
+    if (!withinRoot(root, resolved) || !lstatSync(resolved).isFile()) {
+      throw new Error("Dependency resolution metadata escapes its declared root.");
+    }
+    discovered.add(normalizePath(path.relative(root, resolved)));
+  };
+  const addPackage = (candidate) => addRealFile(path.join(realpathSync(candidate), "package.json"));
+  for (const name of readdirSync(nodeModules).sort(comparePaths)) {
+    if (name === ".bin") {
+      for (const binName of readdirSync(path.join(nodeModules, name)).sort(comparePaths)) {
+        addRealFile(path.join(nodeModules, name, binName));
+      }
+      continue;
+    }
+    if (name.startsWith(".")) continue;
+    const entry = path.join(nodeModules, name);
+    const stat = lstatSync(entry);
+    if (name.startsWith("@") && stat.isDirectory() && !stat.isSymbolicLink()) {
+      for (const child of readdirSync(entry).sort(comparePaths)) addPackage(path.join(entry, child));
+    } else {
+      addPackage(entry);
+    }
+    if (discovered.size > 20_000) {
+      throw new Error("Dependency resolution metadata exceeds the file limit.");
+    }
+  }
+  return [...discovered].sort(comparePaths);
+}
+
+export function captureDependencyEnvironment(dependencyRoot) {
+  if (dependencyRoot === undefined || dependencyRoot === null) return null;
+  const root = canonicalRealDirectory(dependencyRoot, "Dependency root");
+  const nodeModules = path.join(root, "node_modules");
+  const nodeModulesStat = lstatSync(nodeModules);
+  if (nodeModulesStat.isSymbolicLink()
+    || !nodeModulesStat.isDirectory()
+    || realpathSync(nodeModules) !== nodeModules) {
+    throw new Error("Dependency root must contain a real node_modules directory.");
+  }
+  const budget = { bytes: 0 };
+  const materialPaths = [...new Set([
+    ...DEPENDENCY_MATERIALS,
+    ...installedDependencyMaterialPaths(root),
+  ])].sort(comparePaths);
+  const materials = materialPaths
+    .map(relativePath => dependencyMaterial(root, relativePath, budget))
+    .filter(Boolean);
+  if (!materials.some(material => material.path === "package.json") || materials.length < 2) {
+    throw new Error("Dependency root must bind package.json and lock or install metadata.");
+  }
+  const identity = { root, materials };
+  return {
+    ...identity,
+    fingerprint: sha256Canonical(identity),
+  };
+}

package/packages/attest/src/index.mjs

@@ -44,6 +44,7 @@ export function attestFile({ subjectPath, workspaceRoot }) {
   if (new Set([
     "OwlCodaQuickVerificationReceiptV1",
     "OwlCodaQuickVerificationReceiptV2",
+    "OwlCodaQuickVerificationReceiptV3",
   ]).has(subject.value.schemaVersion)) {
     const details = attestQuickReceiptDetailsFromBytes({
       receiptPath: subject.absolutePath,

package/packages/attest/src/quick-receipt-contract.mjs

@@ -34,10 +34,33 @@ const SNAPSHOT_REQUIRED_KEYS = [
   "policyVersion",
   "sourceFingerprint",
 ];
+const SNAPSHOT_V2_REQUIRED_KEYS = [
+  ...SNAPSHOT_REQUIRED_KEYS.filter(key => key !== "sourceFingerprint"),
+  "ignoredPathBindings",
+  "ignoredPathsFingerprint",
+  "sourceStateFingerprint",
+  "sourceFingerprint",
+];
 const KNOWN_RECEIPT_ISSUES = new Set([
   "quick_ignored_artifact_unbound",
   "source_mutated_during_verification",
 ]);
+const V3_RECEIPT_ISSUES = new Set([
+  ...KNOWN_RECEIPT_ISSUES,
+  "bound_ignored_path_mutated_during_verification",
+  "dependency_environment_mutated_during_verification",
+  "consumer_source_mutated_during_verification",
+  "quick_isolation_cleanup_failed",
+]);
+const V3_MUTATION_DECISIONS = new Set([
+  "source_unchanged",
+  "invalidated_by_command_source_mutation",
+  "invalidated_by_bound_ignored_mutation",
+  "invalidated_by_dependency_environment_mutation",
+  "invalidated_by_consumer_source_mutation",
+  "invalidated_by_isolation_cleanup_failure",
+  "invalidated_by_multiple_mutations",
+]);
 
 function validDateTime(value) {
   return typeof value === "string"
@@ -54,16 +77,30 @@ function validCoreIdentity(value) {
     && isSha256Ref(value.coreManifestSha256);
 }
 
+function sourceStateFingerprint(value) {
+  return sha256Canonical({
+    repositoryIdentity: value.repositoryIdentity,
+    headCommit: value.headCommit,
+    trackedTreeIdentity: value.trackedTreeIdentity,
+    submodules: value.submodules,
+    dirtyOverlay: value.dirtyOverlay,
+    dependencyLockfiles: value.dependencyLockfiles,
+    excludedRoots: value.excludedRoots,
+  });
+}
+
 export function validWorkspaceSnapshotShape(value) {
-  if (!hasExactKeys(value, SNAPSHOT_REQUIRED_KEYS)) return false;
+  const snapshotV1 = value?.schemaVersion === "OwlCodaWorkspaceSnapshotV1";
+  const snapshotV2 = value?.schemaVersion === "OwlCodaWorkspaceSnapshotV2";
+  if (!(snapshotV1 || snapshotV2)) return false;
+  if (!hasExactKeys(value, snapshotV2 ? SNAPSHOT_V2_REQUIRED_KEYS : SNAPSHOT_REQUIRED_KEYS)) return false;
   if (
-    value.schemaVersion !== "OwlCodaWorkspaceSnapshotV1"
-    || typeof value.repositoryIdentity !== "string"
+    typeof value.repositoryIdentity !== "string"
     || value.repositoryIdentity.length === 0
     || !(value.headCommit === null || /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(value.headCommit))
     || !isSha256Ref(value.trackedTreeIdentity)
-    || value.ignoredPathsBound !== false
-    || value.policyVersion !== "workspace-snapshot-v1"
+    || value.ignoredPathsBound !== snapshotV2
+    || value.policyVersion !== (snapshotV2 ? "workspace-snapshot-v2" : "workspace-snapshot-v1")
     || !isSha256Ref(value.sourceFingerprint)
     || !Array.isArray(value.submodules)
     || !Array.isArray(value.dirtyOverlay)
@@ -92,6 +129,22 @@ export function validWorkspaceSnapshotShape(value) {
     && isSha256Ref(entry.sha256))) {
     return false;
   }
+  if (snapshotV2 && (
+    !Array.isArray(value.ignoredPathBindings)
+    || value.ignoredPathBindings.length === 0
+    || !isSha256Ref(value.ignoredPathsFingerprint)
+    || !isSha256Ref(value.sourceStateFingerprint)
+    || !value.ignoredPathBindings.every(entry =>
+      hasExactKeys(entry, ["path", "state", "sha256"])
+      && typeof entry.path === "string"
+      && entry.path.length > 0
+      && ["missing", "file", "directory"].includes(entry.state)
+      && (entry.sha256 === null || isSha256Ref(entry.sha256)))
+    || sha256Canonical(value.ignoredPathBindings) !== value.ignoredPathsFingerprint
+    || sourceStateFingerprint(value) !== value.sourceStateFingerprint
+  )) {
+    return false;
+  }
   return true;
 }
 
@@ -109,13 +162,138 @@ function validOutputArtifact(value) {
     && value.sizeBytes >= 0;
 }
 
+function validDependencyEnvironment(value) {
+  if (value === null) return true;
+  if (!hasExactKeys(value, ["root", "materials", "fingerprint"])
+    || typeof value.root !== "string"
+    || value.root.length === 0
+    || !Array.isArray(value.materials)
+    || value.materials.length < 2
+    || !isSha256Ref(value.fingerprint)
+    || !value.materials.every(material =>
+      hasExactKeys(material, ["path", "sha256"])
+      && typeof material.path === "string"
+      && material.path.length > 0
+      && isSha256Ref(material.sha256))) {
+    return false;
+  }
+  return sha256Canonical({ root: value.root, materials: value.materials }) === value.fingerprint;
+}
+
+function validExecutionIsolation(value, receipt) {
+  if (value === null) {
+    return receipt.mutationClasses.consumerSource === "not_isolated"
+      && receipt.mutationClasses.consumerIgnoredArtifacts === "not_isolated";
+  }
+  return hasExactKeys(value, [
+    "schemaVersion",
+    "mode",
+    "consumerRoot",
+    "sourceCopy",
+    "cacheEnvironmentVariables",
+    "dependencyEnvironment",
+    "dependencyEnvironmentAfter",
+    "consumerDelta",
+    "cleanupStatus",
+  ])
+    && value.schemaVersion === "OwlCodaRunKitQuickIsolationV1"
+    && value.mode === "temporary_consumer"
+    && typeof value.consumerRoot === "string"
+    && value.consumerRoot.length > 0
+    && value.consumerRoot === receipt.exactCommand.cwd
+    && hasExactKeys(value.sourceCopy, ["fileCount", "totalBytes", "fingerprint"])
+    && Number.isInteger(value.sourceCopy.fileCount)
+    && value.sourceCopy.fileCount >= 0
+    && Number.isInteger(value.sourceCopy.totalBytes)
+    && value.sourceCopy.totalBytes >= 0
+    && isSha256Ref(value.sourceCopy.fingerprint)
+    && Array.isArray(value.cacheEnvironmentVariables)
+    && value.cacheEnvironmentVariables.length > 0
+    && new Set(value.cacheEnvironmentVariables).size === value.cacheEnvironmentVariables.length
+    && value.cacheEnvironmentVariables.every(name => typeof name === "string" && name.length > 0)
+    && validDependencyEnvironment(value.dependencyEnvironment)
+    && validDependencyEnvironment(value.dependencyEnvironmentAfter)
+    && (value.dependencyEnvironment !== null || value.dependencyEnvironmentAfter === null)
+    && hasExactKeys(value.consumerDelta, ["sourcePaths", "ignoredPaths"])
+    && [value.consumerDelta.sourcePaths, value.consumerDelta.ignoredPaths].every(paths =>
+      Array.isArray(paths)
+      && new Set(paths).size === paths.length
+      && paths.every(entry => typeof entry === "string" && entry.length > 0))
+    && ["removed", "cleanup_failed"].includes(value.cleanupStatus);
+}
+
+function validMutationClasses(value) {
+  return hasExactKeys(value, [
+    "workspaceSource",
+    "boundIgnoredPaths",
+    "dependencyEnvironment",
+    "consumerSource",
+    "consumerIgnoredArtifacts",
+  ])
+    && ["unchanged", "changed"].includes(value.workspaceSource)
+    && ["not_bound", "unchanged", "changed"].includes(value.boundIgnoredPaths)
+    && ["not_bound", "unchanged", "changed"].includes(value.dependencyEnvironment)
+    && ["not_isolated", "unchanged", "changed"].includes(value.consumerSource)
+    && ["not_isolated", "none", "changed_and_discarded"].includes(value.consumerIgnoredArtifacts);
+}
+
+function validV3MutationTruth(receipt) {
+  const workspaceSourceChanged = sourceStateFingerprint(receipt.workspaceBefore)
+    !== sourceStateFingerprint(receipt.workspaceAfter);
+  const boundIgnored = receipt.workspaceBefore.ignoredPathsBound === true;
+  const boundIgnoredChanged = boundIgnored
+    && receipt.workspaceBefore.ignoredPathsFingerprint
+      !== receipt.workspaceAfter.ignoredPathsFingerprint;
+  const isolation = receipt.executionIsolation;
+  const consumerSourceChanged = (isolation?.consumerDelta.sourcePaths.length ?? 0) > 0;
+  const consumerIgnoredChanged = (isolation?.consumerDelta.ignoredPaths.length ?? 0) > 0;
+  const dependencyBound = isolation !== null && isolation?.dependencyEnvironment !== null;
+  const dependencyChanged = dependencyBound
+    && (isolation.dependencyEnvironmentAfter === null
+      || isolation.dependencyEnvironmentAfter.fingerprint
+        !== isolation.dependencyEnvironment.fingerprint);
+  const cleanupFailed = isolation?.cleanupStatus === "cleanup_failed";
+  if (receipt.mutationClasses.workspaceSource !== (workspaceSourceChanged ? "changed" : "unchanged")
+    || receipt.mutationClasses.boundIgnoredPaths !== (boundIgnored
+      ? boundIgnoredChanged ? "changed" : "unchanged"
+      : "not_bound")
+    || receipt.mutationClasses.dependencyEnvironment !== (dependencyBound
+      ? dependencyChanged ? "changed" : "unchanged"
+      : "not_bound")
+    || receipt.mutationClasses.consumerSource !== (isolation === null
+      ? "not_isolated"
+      : consumerSourceChanged ? "changed" : "unchanged")
+    || receipt.mutationClasses.consumerIgnoredArtifacts !== (isolation === null
+      ? "not_isolated"
+      : consumerIgnoredChanged ? "changed_and_discarded" : "none")) {
+    return false;
+  }
+  const facts = [
+    [workspaceSourceChanged, "invalidated_by_command_source_mutation", "source_mutated_during_verification"],
+    [boundIgnoredChanged, "invalidated_by_bound_ignored_mutation", "bound_ignored_path_mutated_during_verification"],
+    [dependencyChanged, "invalidated_by_dependency_environment_mutation", "dependency_environment_mutated_during_verification"],
+    [consumerSourceChanged, "invalidated_by_consumer_source_mutation", "consumer_source_mutated_during_verification"],
+    [cleanupFailed, "invalidated_by_isolation_cleanup_failure", "quick_isolation_cleanup_failed"],
+  ].filter(([active]) => active);
+  const expectedDecision = facts.length === 0
+    ? "source_unchanged"
+    : facts.length === 1 ? facts[0][1] : "invalidated_by_multiple_mutations";
+  const expectedIssues = facts.map(([, , issue]) => issue).sort();
+  return receipt.mutationDecision === expectedDecision
+    && JSON.stringify([...receipt.issueCodes].sort()) === JSON.stringify(expectedIssues);
+}
+
 export function validQuickReceiptShape(receipt) {
   const receiptV1 = receipt?.schemaVersion === "OwlCodaQuickVerificationReceiptV1";
   const receiptV2 = receipt?.schemaVersion === "OwlCodaQuickVerificationReceiptV2";
-  const requiredKeys = receiptV2
+  const receiptV3 = receipt?.schemaVersion === "OwlCodaQuickVerificationReceiptV3";
+  const requiredKeys = receiptV3
+    ? [...RECEIPT_REQUIRED_KEYS, "sourceWorkspaceRoot", "executionIsolation", "mutationClasses"]
+    : receiptV2
     ? [...RECEIPT_REQUIRED_KEYS, "inputArtifacts"]
     : RECEIPT_REQUIRED_KEYS;
-  if (!(receiptV1 || receiptV2) || !hasExactKeys(receipt, requiredKeys, ["signatureRef"])) return false;
+  const optionalKeys = receiptV3 ? ["inputArtifacts", "signatureRef"] : ["signatureRef"];
+  if (!(receiptV1 || receiptV2 || receiptV3) || !hasExactKeys(receipt, requiredKeys, optionalKeys)) return false;
   if (
     typeof receipt.receiptId !== "string"
     || receipt.receiptId.length === 0
@@ -142,10 +320,13 @@ export function validQuickReceiptShape(receipt) {
     || !hasExactKeys(receipt.outputArtifacts, ["stdout", "stderr"])
     || !validOutputArtifact(receipt.outputArtifacts.stdout)
     || !validOutputArtifact(receipt.outputArtifacts.stderr)
-    || !["source_unchanged", "invalidated_by_command_source_mutation"].includes(receipt.mutationDecision)
+    || !(receiptV3
+      ? V3_MUTATION_DECISIONS.has(receipt.mutationDecision)
+      : ["source_unchanged", "invalidated_by_command_source_mutation"].includes(receipt.mutationDecision))
     || !Array.isArray(receipt.issueCodes)
     || new Set(receipt.issueCodes).size !== receipt.issueCodes.length
-    || !receipt.issueCodes.every((entry) => typeof entry === "string" && KNOWN_RECEIPT_ISSUES.has(entry))
+    || !receipt.issueCodes.every((entry) => typeof entry === "string"
+      && (receiptV3 ? V3_RECEIPT_ISSUES : KNOWN_RECEIPT_ISSUES).has(entry))
   ) {
     return false;
   }
@@ -155,6 +336,18 @@ export function validQuickReceiptShape(receipt) {
   )) {
     return false;
   }
+  if (receiptV3 && (
+    typeof receipt.sourceWorkspaceRoot !== "string"
+    || receipt.sourceWorkspaceRoot.length === 0
+    || !validMutationClasses(receipt.mutationClasses)
+    || !validExecutionIsolation(receipt.executionIsolation, receipt)
+    || receipt.inputArtifacts !== undefined
+      && (!hasExactKeys(receipt.inputArtifacts, ["stdin"])
+        || !validOutputArtifact(receipt.inputArtifacts.stdin))
+    || !validV3MutationTruth(receipt)
+  )) {
+    return false;
+  }
   if (receipt.signatureRef !== undefined) {
     if (!hasExactKeys(receipt.signatureRef, ["path", "sha256"])
       || typeof receipt.signatureRef.path !== "string"

package/packages/attest/src/quick.mjs

@@ -13,11 +13,17 @@ import {
   quickSnapshotFingerprintValid,
   validQuickReceiptShape,
 } from "./quick-receipt-contract.mjs";
+import { captureDependencyEnvironment } from "./dependency-environment.mjs";
 import { captureWorkspaceSnapshot } from "./workspace-snapshot.mjs";
 
 export { validQuickReceiptShape } from "./quick-receipt-contract.mjs";
 
 export const SUPPORTED_QUICK_CORE_IDENTITIES = Object.freeze([
+  {
+    contractVersion: "0.2",
+    coreVersion: "0.19.0",
+    coreManifestSha256: "sha256:803fb7de76a6ccffd1ec5e0164eeff15a580209fa6dfbef9e561345ab616b403",
+  },
   {
     contractVersion: "0.2",
     coreVersion: "0.18.4",
@@ -125,6 +131,23 @@ export const SUPPORTED_QUICK_CORE_IDENTITIES = Object.freeze([
   },
 ]);
 
+function dependencyEnvironmentCurrent(binding, materials) {
+  if (binding === null || binding === undefined) return true;
+  try {
+    const current = captureDependencyEnvironment(binding.root);
+    if (current.root !== binding.root || current.fingerprint !== binding.fingerprint) return false;
+    for (const material of current.materials) {
+      materials.push({
+        path: resolveBoundMaterial(current.root, material.path),
+        sha256: material.sha256,
+      });
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function resolveBoundMaterial(root, relativePath) {
   if (path.isAbsolute(relativePath) || relativePath.includes("\0")) {
     throw new Error("material path must be workspace-relative");
@@ -199,7 +222,7 @@ export function attestQuickReceiptDetailsFromBytes({
     throw error;
   }
   if (!isPlainJsonObject(receipt) || !validQuickReceiptShape(receipt)) {
-    const error = new Error("Quick receipt does not satisfy the strict Wave 1 shape");
+    const error = new Error("Quick receipt does not satisfy a supported strict shape");
     error.code = "receipt_schema_invalid";
     throw error;
   }
@@ -239,7 +262,11 @@ export function attestQuickReceiptDetailsFromBytes({
   let receiptWorkspaceRoot;
   if (selectedWorkspaceRoot !== undefined) {
     try {
-      receiptWorkspaceRoot = realpathSync(receipt.exactCommand.cwd);
+      receiptWorkspaceRoot = realpathSync(
+        receipt.schemaVersion === "OwlCodaQuickVerificationReceiptV3"
+          ? receipt.sourceWorkspaceRoot
+          : receipt.exactCommand.cwd,
+      );
     } catch {
       receiptWorkspaceRoot = undefined;
     }
@@ -272,11 +299,19 @@ export function attestQuickReceiptDetailsFromBytes({
   }
   if (materialMissing) issues.push("attestation_material_missing");
   if (materialMismatch) issues.push("receipt_material_hash_mismatch");
+  const ignoredPaths = receipt.workspaceAfter.ignoredPathsBound === true
+    ? receipt.workspaceAfter.ignoredPathBindings.map(entry => entry.path)
+    : [];
   const currentSourceValid = selectedWorkspaceRoot === undefined
     || commandWorkspaceMatches
-      && captureWorkspaceSnapshot(selectedWorkspaceRoot).sourceFingerprint
+      && captureWorkspaceSnapshot(selectedWorkspaceRoot, { ignoredPaths }).sourceFingerprint
         === receipt.workspaceAfter.sourceFingerprint;
-  const sourceValid = receiptSourceValid && currentSourceValid;
+  const dependencyEnvironmentValid = dependencyEnvironmentCurrent(
+    receipt.executionIsolation?.dependencyEnvironment,
+    materials,
+  );
+  if (!dependencyEnvironmentValid) issues.push("receipt_dependency_environment_mismatch");
+  const sourceValid = receiptSourceValid && currentSourceValid && dependencyEnvironmentValid;
   if (!sourceValid || receipt.mutationDecision !== "source_unchanged") {
     issues.push("receipt_source_mismatch");
   }
@@ -285,6 +320,7 @@ export function attestQuickReceiptDetailsFromBytes({
   const deterministicFailure = !coreValid
     || !contextValid
     || materialMismatch
+    || !dependencyEnvironmentValid
     || !sourceValid
     || receipt.mutationDecision !== "source_unchanged"
     || !commandPassed;

package/packages/attest/src/workspace-snapshot.mjs

@@ -1,10 +1,12 @@
 import { execFileSync } from "node:child_process";
-import { lstatSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
+import { lstatSync, readFileSync, readdirSync, readlinkSync, realpathSync } from "node:fs";
 import path from "node:path";
 
 import { sha256Bytes, sha256Canonical } from "./formal.mjs";
 
 const CONTROL_ROOT = ".owlcoda/runkit";
+const MAX_BOUND_IGNORED_FILES = 10_000;
+const MAX_BOUND_IGNORED_BYTES = 512 * 1024 * 1024;
 const LOCKFILE_NAMES = new Set([
   "bun.lock",
   "bun.lockb",
@@ -157,12 +159,117 @@ function trackedTreeIdentity(root, headCommit) {
   });
 }
 
-export function captureWorkspaceSnapshot(workspaceRoot) {
+function safeIgnoredPath(value) {
+  if (typeof value !== "string" || value.length === 0 || path.isAbsolute(value)) return false;
+  if (value.includes("\\") || value.includes("\0")) return false;
+  const segments = value.split("/");
+  return segments.every(segment => segment.length > 0 && segment !== "." && segment !== "..")
+    && !isControlPath(value);
+}
+
+function withinRoot(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === ""
+    || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+function assertIgnoredByGit(root, relativePath) {
+  const tracked = git(root, ["ls-files", "-z", "--", relativePath]);
+  if (tracked.length > 0) {
+    throw new Error(`Explicit ignored binding cannot replace tracked source binding: ${relativePath}`);
+  }
+  try {
+    git(root, ["check-ignore", "--no-index", "-q", "--", relativePath]);
+  } catch {
+    throw new Error(`Explicit ignored binding is not covered by Git ignore rules: ${relativePath}`);
+  }
+}
+
+function hashIgnoredTree(root, relativePath, budget) {
+  const absolute = path.resolve(root, ...relativePath.split("/"));
+  if (!withinRoot(root, absolute)) throw new Error(`Ignored binding escapes workspace: ${relativePath}`);
+  let stat;
+  try {
+    stat = lstatSync(absolute);
+  } catch (error) {
+    if (error?.code === "ENOENT") return { path: relativePath, state: "missing", sha256: null };
+    throw error;
+  }
+  if (stat.isSymbolicLink() || realpathSync(absolute) !== absolute) {
+    throw new Error(`Ignored binding cannot traverse a symlink: ${relativePath}`);
+  }
+  if (stat.isFile()) {
+    budget.files += 1;
+    budget.bytes += stat.size;
+    if (budget.files > MAX_BOUND_IGNORED_FILES || budget.bytes > MAX_BOUND_IGNORED_BYTES) {
+      throw new Error("Explicit ignored binding exceeds the bounded file or byte limit.");
+    }
+    return { path: relativePath, state: "file", sha256: sha256Bytes(readFileSync(absolute)) };
+  }
+  if (!stat.isDirectory()) {
+    throw new Error(`Ignored binding must be a regular file, directory, or missing path: ${relativePath}`);
+  }
+  const files = [];
+  const visit = (directory, prefix) => {
+    for (const name of readdirSync(directory).sort((left, right) => left.localeCompare(right, "en"))) {
+      const child = path.join(directory, name);
+      const childRelative = prefix ? `${prefix}/${name}` : name;
+      const childStat = lstatSync(child);
+      if (childStat.isSymbolicLink() || realpathSync(child) !== child) {
+        throw new Error(`Ignored binding cannot traverse a symlink: ${relativePath}/${childRelative}`);
+      }
+      if (childStat.isDirectory()) {
+        visit(child, childRelative);
+      } else if (childStat.isFile()) {
+        budget.files += 1;
+        budget.bytes += childStat.size;
+        if (budget.files > MAX_BOUND_IGNORED_FILES || budget.bytes > MAX_BOUND_IGNORED_BYTES) {
+          throw new Error("Explicit ignored binding exceeds the bounded file or byte limit.");
+        }
+        files.push({ path: childRelative, sha256: sha256Bytes(readFileSync(child)) });
+      } else {
+        throw new Error(`Ignored binding contains a special file: ${relativePath}/${childRelative}`);
+      }
+    }
+  };
+  visit(absolute, "");
+  return { path: relativePath, state: "directory", sha256: sha256Canonical(files) };
+}
+
+function bindIgnoredPaths(root, requestedPaths) {
+  if (!Array.isArray(requestedPaths)
+    || requestedPaths.length === 0
+    || requestedPaths.some(value => !safeIgnoredPath(value))) {
+    throw new Error("Explicit ignored bindings must be safe literal workspace-relative paths.");
+  }
+  const paths = [...new Set(requestedPaths)].sort((left, right) => left.localeCompare(right, "en"));
+  if (paths.length !== requestedPaths.length) {
+    throw new Error("Explicit ignored bindings must not contain duplicates.");
+  }
+  const budget = { files: 0, bytes: 0 };
+  return paths.map(relativePath => {
+    assertIgnoredByGit(root, relativePath);
+    return hashIgnoredTree(root, relativePath, budget);
+  });
+}
+
+export function workspaceSourceStateFingerprint(snapshot) {
+  return sha256Canonical({
+    repositoryIdentity: snapshot.repositoryIdentity,
+    headCommit: snapshot.headCommit,
+    trackedTreeIdentity: snapshot.trackedTreeIdentity,
+    submodules: snapshot.submodules,
+    dirtyOverlay: snapshot.dirtyOverlay,
+    dependencyLockfiles: snapshot.dependencyLockfiles,
+    excludedRoots: snapshot.excludedRoots,
+  });
+}
+
+export function captureWorkspaceSnapshot(workspaceRoot, { ignoredPaths = [] } = {}) {
   const root = realpathSync(workspaceRoot);
   git(root, ["rev-parse", "--is-inside-work-tree"]);
   const headCommit = optionalGit(root, ["rev-parse", "HEAD"]) || null;
-  const payload = {
-    schemaVersion: "OwlCodaWorkspaceSnapshotV1",
+  const base = {
     repositoryIdentity: repositoryIdentity(root),
     headCommit,
     trackedTreeIdentity: trackedTreeIdentity(root, headCommit),
@@ -170,8 +277,28 @@ export function captureWorkspaceSnapshot(workspaceRoot) {
     dirtyOverlay: parseStatus(root),
     dependencyLockfiles: dependencyLockfiles(root),
     excludedRoots: [CONTROL_ROOT],
-    ignoredPathsBound: false,
-    policyVersion: "workspace-snapshot-v1",
+  };
+  if (ignoredPaths.length === 0) {
+    const payload = {
+      schemaVersion: "OwlCodaWorkspaceSnapshotV1",
+      ...base,
+      ignoredPathsBound: false,
+      policyVersion: "workspace-snapshot-v1",
+    };
+    return {
+      ...payload,
+      sourceFingerprint: sha256Canonical(payload),
+    };
+  }
+  const ignoredPathBindings = bindIgnoredPaths(root, ignoredPaths);
+  const payload = {
+    schemaVersion: "OwlCodaWorkspaceSnapshotV2",
+    ...base,
+    ignoredPathsBound: true,
+    ignoredPathBindings,
+    ignoredPathsFingerprint: sha256Canonical(ignoredPathBindings),
+    sourceStateFingerprint: workspaceSourceStateFingerprint(base),
+    policyVersion: "workspace-snapshot-v2",
   };
   return {
     ...payload,