@awebai/oats 0.24.12 → 0.25.0

package/lib/portable-migration-artifacts.mjs

@@ -1,135 +0,0 @@
-/** 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",
-    ] };
-}

package/lib/portable-migration-evidence.mjs

@@ -1,305 +0,0 @@
-/** Read-only historical migration evidence inventory.
- *
- * Inputs are an explicit bounded target list supplied by the deployment owner.
- * This module does not discover topology, resolve current config/source, verify
- * legacy lock semantics, execute providers, or write migration state. */
-import { lstatSync, realpathSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { readPortableBytes } from "./portable-files.mjs";
-import { bytesIntegrity, validateIntegrity, BYTES_FORMAT } from "./portable-digest.mjs";
-import { canonicalJson, compareUtf8, parseStrictJson } from "./portable-values.mjs";
-import { portableScope } from "./portable-state.mjs";
-import { validateExecutionBinding, validateExecutionCapsule, validateExecutionTemplate } from "./schedule-capsule.mjs";
-import { oatsError } from "./errors.mjs";
-
-export const MIGRATION_INVENTORY_VERSION = 1;
-const MAX_TARGETS = 10_000;
-const SHA256 = /^sha256-[a-f0-9]{64}$/;
-
-const plain = (value) => !!value && typeof value === "object" && !Array.isArray(value);
-const problem = (code, message, pointer = "") => ({ code, message, pointer });
-const errorProblem = (error, pointer = "") => problem(error?.code || "invalid-evidence", String(error?.message || error), pointer);
-
-function canonicalTarget(deployment, input, kind, { allowRoot = false } = {}) {
-  if (typeof input !== "string" || !input || input.includes("\0")) throw oatsError("invalid-declaration", `${kind} target must be a non-empty path without NUL`);
-  const lexical = resolve(deployment, input);
-  const part = relative(deployment, lexical);
-  if ((!allowRoot && !part) || part === ".." || part.startsWith(`..${sep}`) || isAbsolute(part)) {
-    throw oatsError("path-escape", `${kind} target is outside the explicit migration deployment`);
-  }
-  let parent;
-  try { parent = realpathSync(dirname(lexical)); }
-  catch (error) {
-    if (error.code === "ENOENT") return { absolute: lexical, path: part || ".", parentMissing: true };
-    throw error;
-  }
-  if (parent !== dirname(lexical)) throw oatsError("path-escape", `${kind} target has a symlinked or aliased parent`);
-  return { absolute: lexical, path: part || ".", parentMissing: false };
-}
-
-function targetDirectory(deployment, input, kind, { allowRoot = false } = {}) {
-  const target = canonicalTarget(deployment, input, kind, { allowRoot });
-  if (target.parentMissing) return target;
-  let stat;
-  try { stat = lstatSync(target.absolute); }
-  catch (error) { if (error.code === "ENOENT") return { ...target, missing: true }; throw error; }
-  if (!stat.isDirectory() || realpathSync(target.absolute) !== target.absolute) {
-    throw oatsError("path-escape", `${kind} target must be a real, non-symlinked directory`);
-  }
-  return target;
-}
-
-function uniqueTargets(deployment, values, kind, options) {
-  if (!Array.isArray(values) || values.length > MAX_TARGETS || values.some((value) => typeof value !== "string")) {
-    throw oatsError("resource-limit", `${kind} target list must be an array of at most ${MAX_TARGETS} paths`);
-  }
-  const targets = values.map((value) => options?.directory
-    ? targetDirectory(deployment, value, kind, options)
-    : canonicalTarget(deployment, value, kind, options));
-  targets.sort((a, b) => compareUtf8(a.path, b.path));
-  for (let i = 1; i < targets.length; i++) if (targets[i - 1].path === targets[i].path) {
-    throw oatsError("invalid-declaration", `duplicate ${kind} migration target ${targets[i].path}`);
-  }
-  return targets;
-}
-
-function readDocument(target) {
-  if (target.parentMissing) return { receipt: { path: target.path, state: "absent" }, value: null, bytes: null };
-  const bytes = readPortableBytes(target.absolute, { allowMissing: true, invalidCode: "invalid-evidence" });
-  if (bytes === null) return { receipt: { path: target.path, state: "absent" }, value: null, bytes: null };
-  const integrity = bytesIntegrity(bytes);
-  try {
-    return { receipt: { path: target.path, state: "present", integrity }, value: parseStrictJson(bytes), bytes };
-  } catch (error) {
-    return { receipt: { path: target.path, state: "invalid", integrity, problems: [errorProblem(error)] }, value: null, bytes };
-  }
-}
-
-function mapIds(value, key, pointer, problems) {
-  const map = value?.[key];
-  if (map === undefined) return [];
-  if (!plain(map)) { problems.push(problem("invalid-evidence", `${key} must be an object map`, pointer)); return []; }
-  return Object.keys(map).sort(compareUtf8);
-}
-
-function summarizeLock(target, legacyLockDecoder) {
-  const { receipt, value, bytes } = readDocument(target);
-  if (receipt.state !== "present") return { ...receipt, format: "unknown", rowCounts: { packages: 0, capabilities: 0 }, rowIds: { packages: [], capabilities: [] }, legacyTrustClaims: 0, semanticVerification: "required" };
-  const problems = [];
-  if (!plain(value)) problems.push(problem("invalid-evidence", "historical lock root is not an object", ""));
-  const rawVersion = plain(value) ? value.lockfileVersion : undefined;
-  const version = rawVersion === undefined ? 1 : rawVersion;
-  const format = version === 1 ? "legacy-v1" : version === 2 ? "materialized-v2" : version === 3 ? "portable-v3" : "unknown";
-  if (!Number.isSafeInteger(version)) problems.push(problem("invalid-evidence", "lockfileVersion is not an integer", "/lockfileVersion"));
-  else if (![1, 2, 3].includes(version)) problems.push(problem("unsupported-wire-version", `unsupported historical lockfileVersion ${version}`, "/lockfileVersion"));
-  const rowIds = {
-    packages: plain(value) ? mapIds(value, "packages", "/packages", problems) : [],
-    capabilities: plain(value) ? mapIds(value, "capabilities", "/capabilities", problems) : [],
-  };
-  const capabilityRows = plain(value?.capabilities) ? Object.values(value.capabilities) : [];
-  const legacyTrustClaims = capabilityRows.filter((row) => plain(row) && (row.trusted === true || row.trustedExecutables === true)).length;
-  const rowCounts = { packages: rowIds.packages.length, capabilities: rowIds.capabilities.length };
-  let semanticVerification = version === 3 ? "current-reader-required" : "legacy-reader-required";
-  if ((version === 1 || version === 2) && legacyLockDecoder) {
-    try {
-      const decoded = legacyLockDecoder(Buffer.from(bytes), Object.freeze({ path: receipt.path, version }));
-      if (!plain(decoded) || decoded.version !== version) throw oatsError("invalid-lock", "legacy lock decoder returned a different version");
-      const expectedPackages = version === 2 ? rowIds.packages : [];
-      const expectedCapabilities = rowIds.capabilities;
-      const packages = plain(decoded.packages) ? Object.keys(decoded.packages).sort(compareUtf8) : [];
-      const capabilitiesSource = version === 1 ? decoded.legacyCapabilities : decoded.capabilities;
-      const capabilities = plain(capabilitiesSource) ? Object.keys(capabilitiesSource).sort(compareUtf8) : [];
-      if (canonicalJson(packages) !== canonicalJson(expectedPackages) || canonicalJson(capabilities) !== canonicalJson(expectedCapabilities)) {
-        throw oatsError("invalid-lock", "legacy lock decoder changed the historical row identity set");
-      }
-      semanticVerification = "verified";
-    } catch (error) { problems.push(errorProblem(error)); }
-  }
-  return { ...receipt, ...(problems.length ? { state: "invalid", problems } : {}), format, rowCounts, rowIds, legacyTrustClaims, semanticVerification };
-}
-
-function bindingSummary(value, problems) {
-  if (!Object.hasOwn(value, "executionBinding")) return { state: "absent" };
-  try {
-    validateExecutionBinding(value.executionBinding);
-    return { state: "valid-shape", value: JSON.parse(canonicalJson(value.executionBinding)) };
-  } catch (error) {
-    problems.push(errorProblem(error, "/executionBinding"));
-    return { state: "invalid" };
-  }
-}
-
-function capabilitySummaries(value, pointer, problems) {
-  if (value === undefined) return [];
-  if (!Array.isArray(value)) { problems.push(problem("invalid-evidence", "capabilityRuntime must be an array", pointer)); return []; }
-  const out = [];
-  for (let index = 0; index < value.length; index++) {
-    const row = value[index], at = `${pointer}/${index}`;
-    if (!plain(row) || typeof row.id !== "string" || !row.id) { problems.push(problem("invalid-evidence", "capability runtime row lacks an identity", at)); continue; }
-    const integrity = typeof row.trust?.integrity === "string" && SHA256.test(row.trust.integrity) ? row.trust.integrity : null;
-    const hookNames = plain(row.hooks) ? Object.keys(row.hooks).sort(compareUtf8) : [];
-    out.push({ id: row.id, integrity, trustedClaim: row.trust?.trusted === true, hookNames });
-  }
-  return out.sort((a, b) => compareUtf8(a.id, b.id));
-}
-
-function summarizeCleanup(target) {
-  const document = canonicalTarget(target.deployment, join(target.absolute, ".oats-rollback-incomplete.json"), "cleanup evidence");
-  const { receipt, value } = readDocument(document);
-  const problems = [];
-  if (receipt.state !== "present") return { document: receipt, capabilities: [], outstanding: { hooks: 0, git: 0, directory: false } };
-  if (!plain(value)) problems.push(problem("invalid-evidence", "cleanup descriptor root is not an object", ""));
-  const cleanup = plain(value?.cleanup) ? value.cleanup : null;
-  if (!cleanup) problems.push(problem("invalid-evidence", "cleanup descriptor has no cleanup object", "/cleanup"));
-  const outstanding = plain(cleanup?.outstanding) ? cleanup.outstanding : {};
-  const capabilities = capabilitySummaries(cleanup?.capabilityRuntime, "/cleanup/capabilityRuntime", problems);
-  return {
-    document: { ...receipt, ...(problems.length ? { state: "invalid", problems } : {}) },
-    capabilities,
-    outstanding: { hooks: Array.isArray(outstanding.hooks) ? outstanding.hooks.length : 0,
-      git: Array.isArray(outstanding.git) ? outstanding.git.length : 0, directory: outstanding.directory === true },
-    ...(problems.length ? { problems } : {}),
-  };
-}
-
-function summarizeHome(deployment, target) {
-  const document = canonicalTarget(deployment, join(target.absolute, "instance.json"), "instance evidence");
-  const { receipt, value } = readDocument(document), problems = [];
-  let instance = basename(target.absolute), executionBinding = { state: "absent" }, capabilities = [];
-  if (receipt.state === "present") {
-    if (!plain(value)) problems.push(problem("invalid-evidence", "instance metadata root is not an object", ""));
-    else {
-      if (typeof value.instance === "string" && value.instance) instance = value.instance;
-      else problems.push(problem("invalid-evidence", "instance metadata has no stable instance name", "/instance"));
-      executionBinding = bindingSummary(value, problems);
-      capabilities = capabilitySummaries(value.capabilityRuntime, "/capabilityRuntime", problems);
-    }
-  }
-  const cleanup = summarizeCleanup({ ...target, deployment });
-  return { path: target.path, instance, document: { ...receipt, ...(problems.length ? { state: "invalid", problems } : {}) },
-    executionBinding, capabilities, cleanup };
-}
-
-function executionSummary(value, kind, pointer, problems) {
-  if (value === undefined) return { state: "absent" };
-  try {
-    if (kind === "capsule") validateExecutionCapsule(value); else validateExecutionTemplate(value);
-    return { state: "valid-shape", schemaVersion: value.schemaVersion,
-      ...(Object.hasOwn(value, "executionId") ? { executionId: value.executionId } : {}),
-      deployment: value.deployment, resolution: JSON.parse(canonicalJson(value.resolution)),
-      action: JSON.parse(canonicalJson(value.action)) };
-  } catch (error) {
-    problems.push(errorProblem(error, pointer));
-    return { state: "invalid" };
-  }
-}
-
-function summarizeScheduleJob(id, definition, state) {
-  const problems = [];
-  if (definition !== undefined && !plain(definition)) problems.push(problem("invalid-evidence", "schedule definition is not an object", `/definitions/jobs/${id}`));
-  if (state !== undefined && !plain(state)) problems.push(problem("invalid-evidence", "schedule state is not an object", `/state/jobs/${id}`));
-  const attempt = plain(state?.attempt)
-    ? state.attempt.execution === undefined ? { state: "legacy" }
-      : executionSummary(state.attempt.execution, "capsule", `/state/jobs/${id}/attempt/execution`, problems)
-    : state?.attempt === undefined ? { state: "absent" } : (problems.push(problem("invalid-evidence", "schedule attempt is not an object", `/state/jobs/${id}/attempt`)), { state: "invalid" });
-  const lastRun = plain(state?.lastRun)
-    ? state.lastRun.execution === undefined ? state.lastRun.outcome === "unknown" ? { state: "legacy" } : { state: "absent" }
-      : executionSummary(state.lastRun.execution, "capsule", `/state/jobs/${id}/lastRun/execution`, problems)
-    : state?.lastRun === undefined ? { state: "absent" } : (problems.push(problem("invalid-evidence", "schedule lastRun is not an object", `/state/jobs/${id}/lastRun`)), { state: "invalid" });
-  const template = plain(definition) ? executionSummary(definition.execution, "template", `/definitions/jobs/${id}/execution`, problems) : { state: "absent" };
-  return { id, kind: typeof definition?.kind === "string" ? definition.kind : null,
-    definitionVersion: Number.isSafeInteger(definition?.definitionVersion) ? definition.definitionVersion : null,
-    recurrencePolicy: typeof definition?.recurrencePolicy === "string" ? definition.recurrencePolicy : null,
-    execution: template, attempt, lastRun, ...(problems.length ? { problems } : {}) };
-}
-
-function summarizeSchedules(deployment, target) {
-  const definitionsTarget = canonicalTarget(deployment, join(target.absolute, "oats-schedules.json"), "schedule definitions evidence");
-  const stateTarget = canonicalTarget(deployment, join(target.absolute, ".agents", "schedules", "state.json"), "schedule state evidence");
-  const definitions = readDocument(definitionsTarget), state = readDocument(stateTarget), problems = [];
-  const definitionsJobs = plain(definitions.value?.jobs) ? definitions.value.jobs : Object.create(null);
-  const stateJobs = plain(state.value?.jobs) ? state.value.jobs : Object.create(null);
-  if (definitions.receipt.state === "present" && !plain(definitions.value?.jobs)) problems.push(problem("invalid-evidence", "schedule definitions have no jobs map", "/definitions/jobs"));
-  if (state.receipt.state === "present" && !plain(state.value?.jobs)) problems.push(problem("invalid-evidence", "schedule state has no jobs map", "/state/jobs"));
-  const ids = [...new Set([...Object.keys(definitionsJobs), ...Object.keys(stateJobs)])].sort(compareUtf8);
-  return { path: target.path, definitions: definitions.receipt, state: state.receipt,
-    jobs: ids.map((id) => summarizeScheduleJob(id, definitionsJobs[id], stateJobs[id])), ...(problems.length ? { problems } : {}) };
-}
-
-/** Inventory only explicitly supplied targets. No recursive discovery occurs. */
-export function readPortableMigrationInventory(scope, { lockFiles = [], instanceHomes = [], scheduleScopes = [] } = {}, { legacyLockDecoder } = {}) {
-  if (legacyLockDecoder !== undefined && typeof legacyLockDecoder !== "function") throw oatsError("invalid-declaration", "legacyLockDecoder must be a function");
-  const deployment = portableScope(scope);
-  const locks = uniqueTargets(deployment, lockFiles, "lock evidence").map((target) => summarizeLock(target, legacyLockDecoder));
-  const homes = uniqueTargets(deployment, instanceHomes, "instance home", { directory: true }).map((target) => summarizeHome(deployment, target));
-  const schedules = uniqueTargets(deployment, scheduleScopes, "schedule scope", { directory: true, allowRoot: true }).map((target) => summarizeSchedules(deployment, target));
-  const inventory = { schemaVersion: MIGRATION_INVENTORY_VERSION, deployment, locks, homes, schedules };
-  canonicalJson(inventory);
-  return inventory;
-}
-
-function assertReceipt(receipt) {
-  if (!plain(receipt) || typeof receipt.path !== "string" || !["present", "absent", "invalid"].includes(receipt.state)) {
-    throw oatsError("invalid-evidence", "migration inventory contains an invalid document receipt");
-  }
-  if (receipt.state !== "absent") validateIntegrity(receipt.integrity, [BYTES_FORMAT]);
-}
-
-/** Minimal persisted-inventory validation; evidence authority still comes from
- * re-reading and comparing all literal document witnesses below. */
-export function validatePortableMigrationInventory(inventory) {
-  canonicalJson(inventory);
-  if (!plain(inventory) || inventory.schemaVersion !== MIGRATION_INVENTORY_VERSION || typeof inventory.deployment !== "string"
-      || !Array.isArray(inventory.locks) || !Array.isArray(inventory.homes) || !Array.isArray(inventory.schedules)) {
-    throw oatsError("invalid-evidence", "invalid migration inventory envelope");
-  }
-  for (const lock of inventory.locks) assertReceipt(lock);
-  for (const home of inventory.homes) { assertReceipt(home.document); assertReceipt(home.cleanup.document); }
-  for (const schedule of inventory.schedules) { assertReceipt(schedule.definitions); assertReceipt(schedule.state); }
-  return inventory;
-}
-
-/** Re-read every explicit witness and require the complete inventory projection
- * to be unchanged. This is still read-only and performs no migration apply. */
-export function verifyPortableMigrationInventory(scope, inventory, adapters = {}) {
-  validatePortableMigrationInventory(inventory);
-  const deployment = portableScope(scope);
-  if (deployment !== inventory.deployment) throw oatsError("selection-changed", "migration deployment identity changed");
-  const current = readPortableMigrationInventory(deployment, {
-    lockFiles: inventory.locks.map((entry) => entry.path),
-    instanceHomes: inventory.homes.map((entry) => entry.path),
-    scheduleScopes: inventory.schedules.map((entry) => entry.path),
-  }, adapters);
-  if (canonicalJson(current) !== canonicalJson(inventory)) throw oatsError("selection-changed", "historical migration evidence changed after inventory");
-  return current;
-}
-
-/** Re-read one explicit lock witness and return its strictly decoded candidate
- * rows. This does not correlate the lock to a home/job, verify artifact bytes,
- * infer missing source, or transfer its historical trust fields. */
-export function verifyHistoricalLockCandidate(scope, inventory, lockPath, { legacyLockDecoder } = {}) {
-  if (typeof legacyLockDecoder !== "function") throw oatsError("migration-required", "historical lock candidate verification needs the strict legacy-lock decoder");
-  const current = verifyPortableMigrationInventory(scope, inventory, { legacyLockDecoder });
-  const target = canonicalTarget(current.deployment, lockPath, "lock evidence");
-  const evidence = current.locks.find((entry) => entry.path === target.path);
-  if (!evidence) throw oatsError("invalid-evidence", "historical lock target is not in the verified inventory");
-  if (evidence.state !== "present" || evidence.semanticVerification !== "verified" || !["legacy-v1", "materialized-v2"].includes(evidence.format)) {
-    throw oatsError("migration-held", "historical lock candidate is absent, invalid, unsupported or not strictly verified");
-  }
-  const document = readDocument(target);
-  if (document.receipt.state !== "present" || canonicalJson(document.receipt.integrity) !== canonicalJson(evidence.integrity)) {
-    throw oatsError("selection-changed", "historical lock changed during candidate verification");
-  }
-  const version = evidence.format === "legacy-v1" ? 1 : 2;
-  const decoded = legacyLockDecoder(Buffer.from(document.bytes), Object.freeze({ path: evidence.path, version }));
-  const copied = parseStrictJson(canonicalJson(decoded));
-  if (copied.version !== version) throw oatsError("invalid-lock", "legacy lock decoder returned a different candidate version");
-  const packageIds = Object.keys(copied.packages || {}).sort(compareUtf8);
-  const capabilityIds = Object.keys(version === 1 ? copied.legacyCapabilities || {} : copied.capabilities || {}).sort(compareUtf8);
-  if (canonicalJson(packageIds) !== canonicalJson(evidence.rowIds.packages) || canonicalJson(capabilityIds) !== canonicalJson(evidence.rowIds.capabilities)) {
-    throw oatsError("invalid-lock", "legacy lock decoder changed the verified candidate row identity set");
-  }
-  return { schemaVersion: 1, path: evidence.path, integrity: evidence.integrity, version,
-    packages: copied.packages, capabilities: copied.capabilities, legacyCapabilities: copied.legacyCapabilities,
-    trustAuthority: "none", evidence: [{ kind: "migration-evidence", document: { kind: "deployment", path: evidence.path, integrity: evidence.integrity }, pointer: "" }] };
-}

package/lib/portable-migration-store.mjs

@@ -1,199 +0,0 @@
-/** Immutable, unselectable historical evidence records.
- *
- * Partial/unknown evidence lives outside `.agents/resolutions` and can never be
- * consumed as dispatch authority. Publication re-verifies all inventoried input
- * witnesses first and changes no lock, home, schedule, session or approval. */
-import { linkSync, lstatSync, mkdirSync, mkdtempSync, opendirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { ensureStoreIgnore } from "./capability-artifacts.mjs";
-import { readPortableBytes } from "./portable-files.mjs";
-import { JSON_FORMAT, jsonIntegrity, validateIntegrity } from "./portable-digest.mjs";
-import { canonicalJson, compareUtf8, parseStrictJson } from "./portable-values.mjs";
-import { portableScope } from "./portable-state.mjs";
-import { objectAt, stringAt, versionAt } from "./portable-shape.mjs";
-import { validateOrigin, validateResolutionRef } from "./resolution-shape.mjs";
-import { validatePortableMigrationInventory, verifyPortableMigrationInventory } from "./portable-migration-evidence.mjs";
-import { planPortableMigration } from "./portable-migration.mjs";
-import { verifyHistoricalHomeCapabilityCandidate } from "./portable-migration-artifacts.mjs";
-import { oatsError } from "./errors.mjs";
-
-export const RESOLUTION_EVIDENCE_VERSION = 1;
-const TARGET_KINDS = new Set(["selection-lock", "instance-home", "scheduled-job"]);
-const ACTIONS = new Set(["preserve", "verify", "hold"]);
-const exists = (path) => { try { return lstatSync(path); } catch (error) { if (error.code === "ENOENT") return null; throw error; } };
-
-export function validateResolutionEvidence(value) {
-  canonicalJson(value);
-  objectAt(value, ["schemaVersion", "target", "status", "evidence", "knownInputs", "unresolved", "resolution"],
-    ["schemaVersion", "target", "status", "evidence", "knownInputs", "unresolved", "resolution"]);
-  versionAt(value.schemaVersion);
-  objectAt(value.target, ["kind", "id"], ["kind", "id"]);
-  if (!TARGET_KINDS.has(value.target.kind)) throw oatsError("invalid-evidence", "unsupported migration evidence target kind");
-  stringAt(value.target.id, "/target/id");
-  if (!Array.isArray(value.evidence)) throw oatsError("invalid-evidence", "migration evidence origins must be an array");
-  value.evidence.forEach(validateOrigin);
-  objectAt(value.knownInputs, ["inventory", "action", "preserve"], ["inventory", "action", "preserve"]);
-  validateIntegrity(value.knownInputs.inventory, [JSON_FORMAT]);
-  if (!ACTIONS.has(value.knownInputs.action)) throw oatsError("invalid-evidence", "invalid planned migration action");
-  canonicalJson(value.knownInputs.preserve);
-  if (!Array.isArray(value.unresolved)) throw oatsError("invalid-evidence", "migration unresolved inputs must be an array");
-  for (const item of value.unresolved) {
-    objectAt(item, ["pointer", "code", "origins", "reason"], ["pointer", "code", "origins", "reason"]);
-    stringAt(item.pointer, "/unresolved/pointer", { empty: true, pattern: /^(?:\/(?:[^~]|~[01])*)*$/ });
-    stringAt(item.code, "/unresolved/code"); stringAt(item.reason, "/unresolved/reason");
-    if (!Array.isArray(item.origins)) throw oatsError("invalid-evidence", "unresolved origins must be an array");
-    item.origins.forEach(validateOrigin);
-  }
-  if (!['reconstructed', 'partial', 'unknown'].includes(value.status)) throw oatsError("invalid-evidence", "invalid migration evidence status");
-  if (value.status === "reconstructed") {
-    validateResolutionRef(value.resolution);
-    if (!value.evidence.length) throw oatsError("resolution-incomplete", "reconstructed evidence requires historical witnesses");
-    if (value.unresolved.length) throw oatsError("resolution-incomplete", "reconstructed evidence cannot retain unresolved managed inputs");
-  } else if (value.resolution !== null) {
-    throw oatsError("resolution-incomplete", "partial or unknown evidence cannot reference a captured resolution");
-  }
-  return value;
-}
-
-export function validateResolutionEvidenceRef(value) {
-  canonicalJson(value, { maxBytes: 1024, maxDepth: 4, maxEntries: 8 });
-  objectAt(value, ["schemaVersion", "id"], ["schemaVersion", "id"]);
-  versionAt(value.schemaVersion);
-  stringAt(value.id, "/id", { pattern: /^sha256-[a-f0-9]{64}$/ });
-  return value;
-}
-
-function store(scope, create) {
-  let root = portableScope(scope);
-  for (const name of [".agents", "resolution-evidence"]) {
-    root = join(root, name);
-    if (create) { try { mkdirSync(root, { mode: 0o700 }); } catch (error) { if (error.code !== "EEXIST") throw error; } }
-    const stat = exists(root);
-    if (!stat) throw oatsError("evidence-not-found", "resolution evidence store is absent");
-    if (!stat.isDirectory() || realpathSync(root) !== root) throw oatsError("invalid-evidence", "resolution evidence store component is not a real directory");
-  }
-  if (create) ensureStoreIgnore(root);
-  return root;
-}
-
-function decode(path, reference) {
-  const bytes = readPortableBytes(path, { missingCode: "evidence-not-found", invalidCode: "invalid-evidence" });
-  const value = parseStrictJson(bytes);
-  if (jsonIntegrity(value).value !== reference.id || !bytes.equals(Buffer.from(canonicalJson(value)))) {
-    throw oatsError("integrity-drift", "resolution evidence bytes differ from their canonical address");
-  }
-  validateResolutionEvidence(value);
-  return value;
-}
-
-export function readResolutionEvidence(scope, reference) {
-  validateResolutionEvidenceRef(reference);
-  return decode(join(store(scope, false), `${reference.id}.json`), reference);
-}
-
-/** Bounded diagnostic enumeration of immutable evidence. Staging and managed
- * ignore metadata are not records; every other entry must be one valid file. */
-export function listResolutionEvidence(scope, { maxEntries = 512, maxRecords = 256, maxBytes = 32 * 1024 * 1024, includeDocuments = false } = {}) {
-  if (!Number.isSafeInteger(maxEntries) || maxEntries < 1 || maxEntries > 10_000
-      || !Number.isSafeInteger(maxRecords) || maxRecords < 1 || maxRecords > 10_000
-      || !Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 256 * 1024 * 1024
-      || typeof includeDocuments !== "boolean") {
-    throw oatsError("invalid-evidence", "invalid resolution evidence listing options");
-  }
-  let root;
-  try { root = store(scope, false); }
-  catch (error) { if (error.code === "evidence-not-found") return []; throw error; }
-  const entries = [];
-  let visited = 0;
-  const directory = opendirSync(root);
-  try {
-    for (;;) {
-      const entry = directory.readSync();
-      if (entry === null) break;
-      if (++visited > maxEntries) throw oatsError("resource-limit", "resolution evidence visited-entry limit exceeded");
-      if (entry.name === ".gitignore" || entry.name.startsWith(".evidence-")) continue;
-      if (entries.length >= maxRecords) throw oatsError("resource-limit", "resolution evidence record limit exceeded");
-      entries.push(entry);
-    }
-  } finally { directory.closeSync(); }
-  const results = [];
-  let totalBytes = 0;
-  for (const entry of entries.sort((a, b) => compareUtf8(a.name, b.name))) {
-    const match = /^(sha256-[a-f0-9]{64})\.json$/.exec(entry.name);
-    if (!entry.isFile() || !match) throw oatsError("invalid-evidence", "resolution evidence store contains an unsupported entry");
-    const reference = { schemaVersion: 1, id: match[1] }, document = decode(join(root, entry.name), reference);
-    totalBytes += Buffer.byteLength(canonicalJson(document));
-    if (totalBytes > maxBytes) throw oatsError("resource-limit", "aggregate resolution evidence byte limit exceeded");
-    results.push({ reference, target: document.target, status: document.status, unresolved: document.unresolved.length,
-      ...(includeDocuments ? { document } : {}) });
-  }
-  return results;
-}
-
-function targetKey(target) { return canonicalJson(target); }
-function entryFor(plan, target) {
-  const wanted = targetKey(target), entry = plan.targets.find((candidate) => targetKey(candidate.target) === wanted);
-  if (!entry) throw oatsError("invalid-evidence", "migration target is not in the verified inventory plan");
-  if (entry.status === "reconstructed") throw oatsError("migration-required", "reconstructed publication requires the dedicated historical evidence verifier");
-  return entry;
-}
-function publishEvidence(deployment, document) {
-  validateResolutionEvidence(document);
-  const reference = { schemaVersion: 1, id: jsonIntegrity(document).value };
-  const root = store(deployment, true), destination = join(root, `${reference.id}.json`);
-  if (exists(destination)) { decode(destination, reference); return reference; }
-  const staging = mkdtempSync(join(root, ".evidence-"));
-  let failed = false, primary;
-  try {
-    const candidate = join(staging, "record.json");
-    writeFileSync(candidate, canonicalJson(document), { flag: "wx", mode: 0o600 });
-    decode(candidate, reference);
-    try { linkSync(candidate, destination); } catch (error) { if (error.code !== "EEXIST") throw error; }
-    decode(destination, reference);
-    return reference;
-  } catch (error) { failed = true; primary = error; throw error; }
-  finally {
-    try { rmSync(staging, { recursive: true, force: true }); }
-    catch (cleanup) {
-      const error = failed ? new AggregateError([primary, cleanup], "evidence publication and cleanup failed", { cause: primary })
-        : new Error("evidence staging cleanup failed", { cause: cleanup });
-      error.code = failed ? primary.code : cleanup.code; error.stagingPath = staging; throw error;
-    }
-  }
-}
-
-/** Publish exactly one target from the deterministic plan after re-reading all
- * inventory witnesses. Reconstructed records require a later dedicated verifier
- * and are deliberately outside this function. */
-export function commitPlannedResolutionEvidence(scope, inventory, target, adapters = {}) {
-  validatePortableMigrationInventory(inventory);
-  const current = verifyPortableMigrationInventory(scope, inventory, adapters);
-  const plan = planPortableMigration(current), entry = entryFor(plan, target);
-  const document = { schemaVersion: RESOLUTION_EVIDENCE_VERSION,
-    target: entry.target, status: entry.status, evidence: entry.evidence,
-    knownInputs: { inventory: plan.inventory, action: entry.action, preserve: entry.preserve ?? null },
-    unresolved: entry.unresolved, resolution: null };
-  return publishEvidence(current.deployment, document);
-}
-
-/** Persist a narrow verified home→historical capability association as
- * partial evidence. Raw legacy source/settings/commands are intentionally not
- * copied; their literal document remains addressed by the evidence origins. */
-export function commitHistoricalHomeCapabilityEvidence(scope, inventory, request, adapters = {}) {
-  validatePortableMigrationInventory(inventory);
-  const candidate = verifyHistoricalHomeCapabilityCandidate(scope, inventory, request, adapters);
-  const current = verifyPortableMigrationInventory(scope, inventory, adapters), plan = planPortableMigration(current);
-  const entry = entryFor(plan, { kind: "instance-home", id: candidate.home.path });
-  const origins = [...entry.evidence, ...candidate.artifact.evidence];
-  const seen = new Set(), evidence = origins.filter((origin) => { const key = canonicalJson(origin); if (seen.has(key)) return false; seen.add(key); return true; })
-    .sort((a, b) => compareUtf8(canonicalJson(a), canonicalJson(b)));
-  const proof = { kind: candidate.artifact.package ? "home-capability-v2" : "home-capability-v1", home: candidate.home.path,
-    capability: { id: candidate.artifact.capability.id, version: candidate.artifact.capability.row.version,
-      package: candidate.artifact.package?.id ?? null, path: candidate.artifact.package ? candidate.artifact.capability.row.path : null },
-    artifact: candidate.artifact.artifact, association: candidate.association,
-    legacyTrustedClaim: candidate.legacyTrustedClaim, selectionAuthority: candidate.artifact.selectionAuthority,
-    approvalAuthority: candidate.approvalAuthority, retentionStatus: candidate.artifact.retentionStatus };
-  const document = { schemaVersion: RESOLUTION_EVIDENCE_VERSION, target: entry.target, status: "partial", evidence,
-    knownInputs: { inventory: plan.inventory, action: "hold", preserve: proof }, unresolved: entry.unresolved, resolution: null };
-  return publishEvidence(current.deployment, document);
-}