@awebai/oats 0.23.1 → 0.24.0

package/lib/portable-digest.mjs

@@ -0,0 +1,105 @@
+/** Explicit new digest domains. Existing v1 package/artifact functions remain
+ * literal in their owning modules; this module never reinterprets legacy hashes. */
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, readdirSync, readlinkSync } from "node:fs";
+import { join } from "node:path";
+import { oatsError } from "./errors.mjs";
+import { canonicalJson, compareUtf8, dataLimits, decodeUtf8 } from "./portable-values.mjs";
+
+export const TREE_FORMAT = "oats.tree-exec.v1";
+export const PACKAGE_FORMAT = "oats.package-payload-exec.v1";
+export const JSON_FORMAT = "oats.json.v1";
+export const BYTES_FORMAT = "oats.bytes.v1";
+const digest = (format, data) => ({ format, value: `sha256-${createHash("sha256").update(data).digest("hex")}` });
+
+export function jsonIntegrity(value, options) { return digest(JSON_FORMAT, canonicalJson(value, options)); }
+export function bytesIntegrity(value) {
+  if (!Buffer.isBuffer(value) && !(value instanceof Uint8Array)) {
+    throw oatsError("invalid-declaration", "raw-byte integrity requires bytes");
+  }
+  return digest(BYTES_FORMAT, value);
+}
+export function validateIntegrity(value, formats = [TREE_FORMAT, PACKAGE_FORMAT, JSON_FORMAT, BYTES_FORMAT]) {
+  const invalid = () => { throw oatsError("invalid-artifact-reference", "expected explicit supported digest format and full SHA-256"); };
+  if (!value || typeof value !== "object" || Array.isArray(value)) invalid();
+  const prototype = Object.getPrototypeOf(value), fields = Object.getOwnPropertyDescriptors(value);
+  if ((prototype !== null && prototype !== Object.prototype) || Reflect.ownKeys(fields).length !== 2) invalid();
+  for (const key of ["format", "value"]) {
+    if (!Object.hasOwn(fields, key) || !Object.hasOwn(fields[key], "value") || !fields[key].enumerable) invalid();
+  }
+  if (!formats.includes(fields.format.value) || typeof fields.value.value !== "string"
+      || !/^sha256-[a-f0-9]{64}$/.test(fields.value.value)) invalid();
+  return value;
+}
+
+const sameFile = (a, b) => a.dev === b.dev && a.ino === b.ino && a.size === b.size
+  && a.mode === b.mode && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs;
+
+/** Domain NUL; then UTF-8-path-sorted records:
+ * F || uint64(path bytes) || path || owner-exec byte || uint64(content bytes) || content
+ * S || uint64(path bytes) || path || uint64(target bytes) || literal target
+ * Length framing prevents the legacy binary record-boundary ambiguity.
+ * Empty directories and non-owner-execute mode bits do not enter identity.
+ * Containment remains the retention caller's responsibility; links aren't followed. */
+export function treeIntegrity(root, { format = TREE_FORMAT, ...options } = {}) {
+  if (![TREE_FORMAT, PACKAGE_FORMAT].includes(format)) {
+    throw oatsError("unsupported-wire-version", "unsupported portable tree digest format");
+  }
+  const limits = dataLimits({ maxBytes: 256 * 1024 * 1024, ...options });
+  const entries = [], hash = createHash("sha256");
+  let visited = 0, bytes = 0;
+  const account = (length) => {
+    bytes += length;
+    if (bytes > limits.maxBytes) throw oatsError("resource-limit", "artifact digest byte limit exceeded");
+  };
+  const length = (size) => {
+    const value = Buffer.alloc(8);
+    value.writeBigUInt64BE(BigInt(size));
+    return value;
+  };
+  const field = (data) => { account(8 + data.length); hash.update(length(data.length)); hash.update(data); };
+  const walk = (dir, parts) => {
+    if (parts.length > limits.maxDepth) throw oatsError("resource-limit", "artifact tree depth limit exceeded");
+    const names = readdirSync(dir, { encoding: "buffer" });
+    for (const raw of names) {
+      if (++visited > limits.maxEntries) throw oatsError("resource-limit", "artifact tree entry limit exceeded");
+      const name = decodeUtf8(raw, "artifact filename");
+      if (format === PACKAGE_FORMAT && (name === "node_modules" || (!parts.length && name === "oats-lock.json"))) continue;
+      const path = join(dir, name), relative = [...parts, name].join("/");
+      const stat = lstatSync(path);
+      if (stat.isSymbolicLink()) entries.push({ path, relative, stat, kind: "S" });
+      else if (stat.isDirectory()) walk(path, [...parts, name]);
+      else if (stat.isFile()) entries.push({ path, relative, stat, kind: "F" });
+      else throw oatsError("invalid-artifact", "unsupported artifact tree entry");
+    }
+  };
+  const rootStat = lstatSync(root);
+  if (!rootStat.isDirectory()) throw oatsError("invalid-artifact", "artifact digest root must be a real directory");
+  walk(root, []);
+  hash.update(`${format}\0`);
+  for (const entry of entries.sort((a, b) => compareUtf8(a.relative, b.relative))) {
+    account(1); hash.update(entry.kind); field(Buffer.from(entry.relative, "utf8"));
+    if (entry.kind === "S") {
+      const target = readlinkSync(entry.path, { encoding: "buffer" });
+      decodeUtf8(target, "artifact symlink target");
+      field(target);
+      continue;
+    }
+    const fd = openSync(entry.path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+      const before = fstatSync(fd);
+      if (!before.isFile() || !sameFile(entry.stat, before)) {
+        throw oatsError("integrity-drift", "artifact input changed during digest");
+      }
+      account(1 + 8 + before.size);
+      hash.update(Buffer.from([(before.mode & 0o100) !== 0 ? 1 : 0]));
+      hash.update(length(before.size));
+      const content = readFileSync(fd);
+      if (content.length !== before.size || !sameFile(before, fstatSync(fd))) {
+        throw oatsError("integrity-drift", "artifact input changed during digest");
+      }
+      hash.update(content);
+    } finally { closeSync(fd); }
+  }
+  return { format, value: `sha256-${hash.digest("hex")}` };
+}

package/lib/portable-files.mjs

@@ -0,0 +1,26 @@
+/** Bounded descriptor-backed reads shared by private portable metadata stores. */
+import { constants, closeSync, fstatSync, lstatSync, openSync, readSync } from "node:fs";
+import { oatsError } from "./errors.mjs";
+
+export function readPortableBytes(path, { missingCode = "resource-not-found", invalidCode = "invalid-declaration", allowMissing = false } = {}) {
+  let stat;
+  try { stat = lstatSync(path); }
+  catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    if (allowMissing) return null;
+    throw oatsError(missingCode, "portable metadata is absent");
+  }
+  if (!stat.isFile()) throw oatsError(invalidCode, "portable metadata must be a regular file");
+  if (stat.size > 8 * 1024 * 1024) throw oatsError("resource-limit", "portable metadata byte limit exceeded");
+  const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const before = fstatSync(fd);
+    if (!before.isFile() || before.dev !== stat.dev || before.ino !== stat.ino || before.size !== stat.size) throw oatsError("integrity-drift", "portable metadata changed during opening");
+    const buffer = Buffer.alloc(stat.size + 1);
+    let count = 0, size;
+    while (count < buffer.length && (size = readSync(fd, buffer, count, buffer.length - count, null)) > 0) count += size;
+    const after = fstatSync(fd);
+    if (count !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs) throw oatsError("integrity-drift", "portable metadata changed during reading");
+    return buffer.subarray(0, count);
+  } finally { closeSync(fd); }
+}

package/lib/portable-identity.mjs

@@ -0,0 +1,40 @@
+/** Qualified identity value types, not a proof of hosting/provider ownership.
+ * Discovery obtains facts from the authenticated host adapter, never repo YAML. */
+import { canonicalJson } from "./portable-values.mjs";
+import { jsonIntegrity } from "./portable-digest.mjs";
+import { parseLockedSource3, parseRepositorySource, portablePath } from "./source-spec.mjs";
+import { invalidShape, objectAt, stringAt } from "./portable-shape.mjs";
+
+export function validateRepositoryIdentity(value) {
+  canonicalJson(value, { maxBytes: 64 * 1024, maxDepth: 8, maxEntries: 64 });
+  objectAt(value, value?.kind === "provider-repository" ? ["kind", "provider", "host", "id"] : ["kind", "remote"], ["kind"]);
+  if (value.kind === "provider-repository") {
+    for (const name of ["provider", "host", "id"]) stringAt(value[name], `/${name}`);
+    if (!/^[a-z][a-z0-9.-]*$/.test(value.provider) || !/^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/.test(value.host)) {
+      invalidShape("", "provider and host identity must be canonical");
+    }
+  } else if (value.kind === "canonical-remote") {
+    stringAt(value.remote, "/remote");
+    if (parseRepositorySource(value.remote).normalized !== value.remote) invalidShape("/remote", "repository identity remote is not canonical");
+  } else invalidShape("/kind", "unsupported repository identity");
+  return value;
+}
+export function validateSoulIdentity(value) {
+  canonicalJson(value, { maxBytes: 64 * 1024, maxDepth: 12, maxEntries: 128 });
+  objectAt(value, value?.kind === "git-soul" ? ["kind", "repository", "exportPath"] : ["kind", "source", "exportPath"], ["kind", "exportPath"]);
+  if (value.kind === "git-soul") validateRepositoryIdentity(value.repository);
+  else if (value.kind === "local-soul") {
+    if (parseLockedSource3(value.source, ".").kind !== "path") invalidShape("/source", "local soul identity requires an explicit local source");
+  } else invalidShape("/kind", "unsupported soul identity");
+  portablePath(value.exportPath, { allowRoot: value.kind === "local-soul" });
+  return value;
+}
+export function validateWorkspaceIdentity(value) {
+  canonicalJson(value, { maxBytes: 64 * 1024, maxDepth: 12, maxEntries: 128 });
+  objectAt(value, ["repository", "path"], ["repository", "path"]);
+  validateRepositoryIdentity(value.repository);
+  if (value.path !== "oats-workspace.yaml") invalidShape("/path", "workspace identity names oats-workspace.yaml");
+  return value;
+}
+export function sameIdentity(a, b) { return canonicalJson(a) === canonicalJson(b); }
+export function soulIdentityKey(value) { validateSoulIdentity(value); return jsonIntegrity(value).value; }

package/lib/portable-lock.mjs

@@ -0,0 +1,117 @@
+/** Lock v3 is mutable input to future preparation, NEVER historical dispatch
+ * authority. Existing v1/v2 readers and stores are not migrated by this module. */
+import { join } from "node:path";
+import { canonicalJson, parseStrictJson } from "./portable-values.mjs";
+import { JSON_FORMAT, jsonIntegrity, validateIntegrity } from "./portable-digest.mjs";
+import { validateArtifactSet, validateOrigin } from "./resolution-shape.mjs";
+import { objectAt, stringAt } from "./portable-shape.mjs";
+import { parseLockedSource3 } from "./source-spec.mjs";
+import { readPortableBytes } from "./portable-files.mjs";
+import { portableScope, withPortableStateWrite, writeGuardedPortableDocument } from "./portable-state.mjs";
+import { oatsError } from "./errors.mjs";
+
+const invalid = (message) => { throw oatsError("invalid-lock", message); };
+export const emptyLock3 = () => ({ lockfileVersion: 3, artifactSets: {}, selections: {} });
+export function requestKey3(request) {
+  canonicalJson(request);
+  objectAt(request, ["source", "path"], ["source", "path"]);
+  parseLockedSource3(request.source, request.path);
+  return jsonIntegrity(request).value;
+}
+export function artifactSetKey3(set) { validateArtifactSet(set); return jsonIntegrity(set).value; }
+function validateProblem(problem) {
+  objectAt(problem, ["code", "message", "origins", "target", "details"], ["code", "message", "origins"]);
+  stringAt(problem.code, "/freshness/problems/code"); stringAt(problem.message, "/freshness/problems/message");
+  if (!Array.isArray(problem.origins)) invalid("refresh problem origins must be an array");
+  problem.origins.forEach(validateOrigin);
+}
+
+export function validateLock3(lock) {
+  try {
+    canonicalJson(lock);
+    if (lock?.lockfileVersion === 1 || lock?.lockfileVersion === 2) {
+      throw oatsError("migration-required", "legacy lock requires its explicit evidence/migration reader; it is not lock v3");
+    }
+    objectAt(lock, ["lockfileVersion", "artifactSets", "selections"], ["lockfileVersion", "artifactSets", "selections"]);
+    if (lock.lockfileVersion !== 3) throw oatsError("unsupported-wire-version", "unsupported selection-lock version");
+    objectAt(lock.artifactSets, null, []); objectAt(lock.selections, null, []);
+    const indexes = new Map(), checked = new Set();
+    for (const [key, set] of Object.entries(lock.artifactSets)) {
+      if (artifactSetKey3(set) !== key) invalid("artifact-set key differs from its canonical content");
+      const requests = new Map();
+      for (const [id, pkg] of Object.entries(set.packages)) {
+        const request = jsonIntegrity({ source: pkg.source, path: pkg.path }).value;
+        if (!requests.has(request)) requests.set(request, []);
+        requests.get(request).push(id);
+      }
+      indexes.set(key, requests);
+    }
+    for (const [key, selection] of Object.entries(lock.selections)) {
+      objectAt(selection, ["request", "current", "available", "freshness"], ["request", "current", "available", "freshness"]);
+      if (requestKey3(selection.request) !== key) invalid("selection key differs from its normalized source request");
+      for (const name of ["current", "available"]) {
+        const selected = selection[name];
+        if (selected === null) continue;
+        stringAt(selected, `/selections/${name}`);
+        if (!Object.hasOwn(lock.artifactSets, selected)) invalid("selection references an absent artifact set");
+        const roots = indexes.get(selected).get(key);
+        if (roots?.length !== 1) invalid("selection has no unique root package matching its request");
+        if (checked.has(`${selected}:${key}`)) continue;
+        const set = lock.artifactSets[selected], reached = new Set([roots[0]]), pending = [roots[0]];
+        while (pending.length) {
+          for (const dependency of set.packages[pending.pop()].dependencies) {
+            if (!reached.has(dependency)) { reached.add(dependency); pending.push(dependency); }
+          }
+        }
+        if (reached.size !== Object.keys(set.packages).length) invalid("selected set includes packages outside the requested dependency closure");
+        for (const row of Object.values(set.capabilities)) if (row.origin.kind !== "package") invalid("package selection cannot smuggle a direct local capability");
+        checked.add(`${selected}:${key}`);
+      }
+      const freshness = selection.freshness;
+      objectAt(freshness, ["state", "observedAt", "problems"], ["state", "observedAt", "problems"]);
+      if (!["refreshed", "offline", "failed", "not-checked"].includes(freshness.state)) invalid("invalid freshness state");
+      if (freshness.observedAt !== null) {
+        stringAt(freshness.observedAt, "/freshness/observedAt");
+        const date = new Date(freshness.observedAt);
+        if (!Number.isFinite(date.getTime()) || date.toISOString() !== freshness.observedAt) invalid("observation timestamp must be canonical UTC ISO time");
+      }
+      if (freshness.state === "refreshed" && (freshness.observedAt === null || selection.available === null)) invalid("successful refresh needs an observed available set and timestamp");
+      if (!Array.isArray(freshness.problems)) invalid("refresh problems must be an array");
+      freshness.problems.forEach(validateProblem);
+    }
+    return lock;
+  } catch (error) {
+    if (["invalid-declaration", "invalid-source", "invalid-artifact-reference"].includes(error.code)) {
+      const failure = oatsError("invalid-lock", error.message); failure.cause = error; throw failure;
+    }
+    throw error;
+  }
+}
+
+/** Explicit scope only. Absent differs from empty-v1, unsupported or damaged.
+ * Integrity is the CAS token, not software verification or executable consent. */
+export function readLock3(scope) {
+  const path = join(portableScope(scope), "oats-lock.json");
+  const bytes = readPortableBytes(path, { allowMissing: true, invalidCode: "invalid-lock" });
+  if (bytes === null) return { lock: null, integrity: null };
+  const lock = parseStrictJson(bytes);
+  validateLock3(lock);
+  if (!bytes.equals(Buffer.from(canonicalJson(lock)))) invalid("selection lock must use canonical JSON bytes");
+  return { lock, integrity: jsonIntegrity(lock) };
+}
+
+/** All new writers share a cooperative guard and compare the complete snapshot.
+ * No implicit legacy migration, row merging, approval, tree cleanup or live cutover. */
+export function writeLock3(scope, expectedPreviousIntegrity, next) {
+  if (expectedPreviousIntegrity !== null) validateIntegrity(expectedPreviousIntegrity, [JSON_FORMAT]);
+  validateLock3(next);
+  return withPortableStateWrite(scope, (context) => {
+    const { deployment } = context;
+    const previous = readLock3(deployment);
+    if (canonicalJson(previous.integrity) !== canonicalJson(expectedPreviousIntegrity)) throw oatsError("selection-changed", "selection lock changed; repeat explicit preparation");
+    const integrity = jsonIntegrity(next);
+    if (canonicalJson(previous.integrity) === canonicalJson(integrity)) return { lock: next, integrity, status: "kept" };
+    writeGuardedPortableDocument(context, join(deployment, "oats-lock.json"), next, { absent: previous.lock === null });
+    return { lock: next, integrity, status: "written" };
+  });
+}

package/lib/portable-migration-artifacts.mjs

@@ -0,0 +1,135 @@
+/** Read-only verification of explicit historical materialized-v2 artifact
+ * candidates. Verification proves the old lock/artifact relation and observes a
+ * new owner-exec digest today; it does not prove per-home selection, historical
+ * modes, retention, reconstruction or approval. */
+import { lstatSync, realpathSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { capabilityArtifactIntegrity } from "./artifact-tree.mjs";
+import { CAPABILITY_INSTALLATION_FILE, isMaterializedCapabilityId } from "./capability-provenance.mjs";
+import { bytesIntegrity, TREE_FORMAT, treeIntegrity } from "./portable-digest.mjs";
+import { readPortableBytes } from "./portable-files.mjs";
+import { parseStrictJson } from "./portable-values.mjs";
+import { portableScope } from "./portable-state.mjs";
+import { verifyHistoricalLockCandidate } from "./portable-migration-evidence.mjs";
+import { oatsError } from "./errors.mjs";
+
+export const LEGACY_CAPABILITY_FORMAT = "oats.capability-legacy.v1";
+export const MATERIALIZED_CAPABILITY_FORMAT = "oats.capability-artifact.v1";
+
+function verifyLegacyManifestIdentity(dir, capability, row) {
+  const path = join(dir, "oats.json"), bytes = readPortableBytes(path, { missingCode: "invalid-lock", invalidCode: "invalid-lock" });
+  let document;
+  try { document = parseStrictJson(bytes); }
+  catch (error) { const failure = oatsError("invalid-lock", `historical oats.json is malformed: ${error.message}`); failure.cause = error; throw failure; }
+  if (document?.capability !== capability || document?.version !== row.version) {
+    throw oatsError("invalid-lock", "historical oats.json identity/version differs from the literal v1 lock row");
+  }
+  return { path: "oats.json", integrity: bytesIntegrity(bytes) };
+}
+
+function verifyInstallationProvenance(dir, capability, row, pkg) {
+  const path = join(dir, CAPABILITY_INSTALLATION_FILE);
+  const bytes = readPortableBytes(path, { missingCode: "invalid-lock", invalidCode: "invalid-lock" });
+  let document;
+  try { document = parseStrictJson(bytes); }
+  catch (error) { const failure = oatsError("invalid-lock", `historical ${CAPABILITY_INSTALLATION_FILE} is malformed: ${error.message}`); failure.cause = error; throw failure; }
+  const expected = { schemaVersion: 1, capability, version: row.version, package: row.package,
+    packageVersion: pkg.version, source: pkg.source, commit: pkg.commit,
+    packagePath: pkg.path, capabilityPath: row.path };
+  for (const [key, value] of Object.entries(expected)) if (document?.[key] !== value) {
+    throw oatsError("invalid-lock", `historical ${CAPABILITY_INSTALLATION_FILE} differs from the verified lock rows at ${key}`);
+  }
+  return { path: CAPABILITY_INSTALLATION_FILE, integrity: bytesIntegrity(bytes) };
+}
+
+function explicitArtifactDirectory(scope, input) {
+  if (typeof input !== "string" || !input || input.includes("\0")) throw oatsError("invalid-evidence", "historical artifact target must be a non-empty path without NUL");
+  const deployment = portableScope(scope), lexical = resolve(deployment, input);
+  const part = relative(deployment, lexical);
+  if (!part || part === ".." || part.startsWith(`..${sep}`) || isAbsolute(part)) throw oatsError("path-escape", "historical artifact target is outside the explicit deployment");
+  let actual;
+  try { actual = realpathSync(lexical); }
+  catch (error) { if (error.code === "ENOENT") throw oatsError("artifact-not-found", "historical artifact candidate is absent"); throw error; }
+  if (actual !== lexical || !lstatSync(actual).isDirectory()) throw oatsError("invalid-artifact", "historical artifact target must be a real non-symlinked directory");
+  return { deployment, dir: actual, path: part.split(sep).join("/") };
+}
+
+/** Verify one explicit v1/v2 flat artifact against one explicit verified
+ * lock. V1's literal digest implementation is supplied as an acyclic callback;
+ * the migration module never imports core or silently substitutes the v2 hash. */
+export function verifyHistoricalCapabilityCandidate(scope, inventory, { lockPath, capability, artifactDir }, adapters = {}) {
+  const { legacyLockDecoder, legacyCapabilityDigest } = adapters;
+  if (!isMaterializedCapabilityId(capability)) throw oatsError("invalid-evidence", "invalid historical capability identity");
+  const lock = verifyHistoricalLockCandidate(scope, inventory, lockPath, { legacyLockDecoder });
+  const row = lock.version === 1 ? lock.legacyCapabilities[capability] : lock.capabilities[capability];
+  if (!row) throw oatsError("migration-held", "historical lock does not name this capability candidate");
+  const target = explicitArtifactDirectory(scope, artifactDir);
+  if (lock.version === 1) {
+    if (typeof legacyCapabilityDigest !== "function") throw oatsError("migration-held", "legacy v1 capability candidate requires its literal historical digest verifier");
+    const manifest = verifyLegacyManifestIdentity(target.dir, capability, row);
+    const observedIntegrity = treeIntegrity(target.dir, { format: TREE_FORMAT });
+    const historical = legacyCapabilityDigest(target.dir);
+    if (historical !== row.integrity) throw oatsError("integrity-drift", "historical legacy artifact differs from its literal v1 lock digest");
+    const finalHistorical = legacyCapabilityDigest(target.dir), finalObserved = treeIntegrity(target.dir, { format: TREE_FORMAT });
+    const finalManifest = verifyLegacyManifestIdentity(target.dir, capability, row);
+    if (finalHistorical !== historical || finalObserved.value !== observedIntegrity.value
+        || finalManifest.integrity.value !== manifest.integrity.value) {
+      throw oatsError("integrity-drift", "historical legacy artifact or manifest changed while its migration witness was measured");
+    }
+    return { schemaVersion: 1, lock: { path: lock.path, integrity: lock.integrity }, capability: { id: capability, row }, package: null,
+      artifact: { path: target.path, historicalIntegrity: { format: LEGACY_CAPABILITY_FORMAT, value: historical },
+        observedIntegrity, manifest, modeEvidence: "observed-at-migration" },
+      selectionAuthority: "none", approvalAuthority: "none", retentionStatus: "not-retained", evidence: lock.evidence };
+  }
+  const pkg = lock.packages[row.package];
+  if (!pkg) throw oatsError("invalid-lock", "historical capability candidate has no verified provider package row");
+  // Preflight bounded/no-follow provenance before the unbounded historical
+  // hasher can read it, then require the same exact bytes after both digest
+  // measurements. The old hash algorithm itself remains literal and unchanged.
+  const provenance = verifyInstallationProvenance(target.dir, capability, row, pkg);
+  const observedIntegrity = treeIntegrity(target.dir, { format: TREE_FORMAT });
+  const historical = capabilityArtifactIntegrity(target.dir);
+  if (historical !== row.integrity) throw oatsError("integrity-drift", "historical materialized artifact differs from its literal v2 lock digest");
+  const finalHistorical = capabilityArtifactIntegrity(target.dir);
+  const finalObserved = treeIntegrity(target.dir, { format: TREE_FORMAT });
+  const finalProvenance = verifyInstallationProvenance(target.dir, capability, row, pkg);
+  if (finalHistorical !== historical || finalObserved.value !== observedIntegrity.value
+      || finalProvenance.integrity.value !== provenance.integrity.value) {
+    throw oatsError("integrity-drift", "historical artifact or provenance changed while its migration witness was measured");
+  }
+  return {
+    schemaVersion: 1,
+    lock: { path: lock.path, integrity: lock.integrity },
+    capability: { id: capability, row }, package: { id: row.package, row: pkg },
+    artifact: { path: target.path,
+      historicalIntegrity: { format: MATERIALIZED_CAPABILITY_FORMAT, value: historical },
+      observedIntegrity, provenance,
+      modeEvidence: "observed-at-migration" },
+    selectionAuthority: "none", approvalAuthority: "none", retentionStatus: "not-retained",
+    evidence: lock.evidence,
+  };
+}
+
+/** Establish only that one unchanged home metadata document named one exact v2
+ * artifact digest. This is per-capability selection evidence, not a complete
+ * composition, source/resource closure or transferred approval. */
+export function verifyHistoricalHomeCapabilityCandidate(scope, inventory, request, adapters = {}) {
+  if (typeof request?.homePath !== "string" || !request.homePath) throw oatsError("invalid-evidence", "historical home candidate needs an explicit inventory path");
+  const artifact = verifyHistoricalCapabilityCandidate(scope, inventory, request, adapters);
+  const home = inventory.homes.find((entry) => entry.path === request.homePath);
+  if (!home || home.document.state !== "present") throw oatsError("migration-held", "historical home evidence is absent or invalid");
+  if (home.executionBinding.state === "valid-shape") throw oatsError("migration-held", "home already carries a captured execution binding; verify that authority instead of reconstructing from legacy rows");
+  const matches = home.capabilities.filter((entry) => entry.id === request.capability);
+  if (matches.length !== 1 || matches[0].integrity !== artifact.artifact.historicalIntegrity.value) {
+    throw oatsError("migration-held", "home metadata does not uniquely bind this capability to the verified historical artifact digest");
+  }
+  const runtime = matches[0];
+  return { schemaVersion: 1, home: { path: home.path, document: home.document }, artifact,
+    association: "capability-runtime-integrity-match", completeness: "partial",
+    legacyTrustedClaim: runtime.trustedClaim, approvalAuthority: "none",
+    unresolved: [
+      "source revision and retained soul projection",
+      "complete managed resources, helpers and runtime packages",
+      "new-format exact-artifact approval",
+    ] };
+}