@awebai/oats 0.23.1 → 0.24.0

package/lib/portable-migration-evidence.mjs

@@ -0,0 +1,305 @@
+/** 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

@@ -0,0 +1,199 @@
+/** 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);
+}

package/lib/portable-migration.mjs

@@ -0,0 +1,104 @@
+/** Pure planning over literal historical evidence. No filesystem access, writes,
+ * provider execution, source resolution, approval transfer or publication. */
+import { canonicalJson, compareUtf8 } from "./portable-values.mjs";
+import { jsonIntegrity } from "./portable-digest.mjs";
+import { validatePortableMigrationInventory } from "./portable-migration-evidence.mjs";
+import { oatsError } from "./errors.mjs";
+
+export const MIGRATION_PLAN_VERSION = 1;
+const originFor = (receipt, pointer = "") => receipt.state === "absent" ? [] : [{ kind: "migration-evidence",
+  document: { kind: "deployment", path: receipt.path, integrity: receipt.integrity }, pointer }];
+const unresolved = (code, reason, receipt, pointer = "") => ({ pointer, code, origins: originFor(receipt, pointer), reason });
+
+function lockPlan(lock) {
+  const target = { kind: "selection-lock", id: lock.path };
+  if (lock.state === "absent") return { target, status: "unknown", action: "hold", evidence: [],
+    unresolved: [unresolved("migration-held", "the historical lock file is absent", lock)] };
+  const evidence = originFor(lock);
+  if (lock.state === "invalid" || lock.format === "unknown") return { target, status: "unknown", action: "hold", evidence,
+    unresolved: [unresolved("invalid-lock", "the literal historical lock is malformed or unsupported", lock)] };
+  if (lock.format === "portable-v3") return { target, status: "partial", action: "verify", evidence,
+    unresolved: [unresolved("migration-required", "the current lock still needs its authoritative lock-v3 reader; a lock is not historical dispatch authority", lock)] };
+  const empty = lock.rowCounts.packages === 0 && lock.rowCounts.capabilities === 0;
+  return { target, status: empty ? "unknown" : "partial", action: "hold", evidence,
+    unresolved: [
+      ...(lock.semanticVerification === "verified" ? [] : [unresolved("migration-required", "the strict legacy lock reader must verify every row without reinterpretation", lock)]),
+      unresolved("migration-held", "a deployment lock does not prove which revision a particular home or job used", lock),
+      unresolved("approval-required", "legacy trust is evidence only and cannot grant new-format exact-artifact approval", lock),
+    ] };
+}
+
+function homePlan(home) {
+  const target = { kind: "instance-home", id: home.path };
+  const receipts = [home.document, home.cleanup.document].filter((entry) => entry.state !== "absent");
+  const evidence = receipts.flatMap((entry) => originFor(entry));
+  if (!receipts.length) return { target, status: "unknown", action: "hold", evidence: [],
+    unresolved: [unresolved("migration-held", "the named home has no instance or quarantine metadata", home.document)] };
+  if (home.executionBinding.state === "valid-shape") return { target, status: "partial", action: "verify", evidence,
+    preserve: { executionBinding: home.executionBinding.value },
+    unresolved: [
+      unresolved("migration-required", "the referenced captured resolution and all retained inputs must be verified before adoption", home.document, "/executionBinding"),
+      unresolved("approval-required", "current exact-artifact approval and action-specific readiness remain separate", home.document, "/executionBinding"),
+    ] };
+  const hasRuntime = home.capabilities.length || home.cleanup.capabilities.length;
+  const invalid = home.document.state === "invalid" || home.cleanup.document.state === "invalid" || home.executionBinding.state === "invalid";
+  return { target, status: hasRuntime && !invalid ? "partial" : "unknown", action: "hold", evidence,
+    unresolved: [
+      ...(invalid ? [unresolved("invalid-evidence", "historical home metadata is malformed or has an invalid captured binding", home.document)] : []),
+      unresolved("migration-held", "the home does not carry a verified complete captured resolution", home.document),
+      unresolved("migration-held", "historical source revision, full managed resources and helper closure are not established by home metadata", home.document),
+      unresolved("approval-required", "recorded legacy trust cannot authorize a reconstructed owner-exec artifact", home.document),
+      ...(home.cleanup.document.state !== "absent" ? [unresolved("migration-held", "cleanup obligations must remain retryable and cannot be discarded during migration", home.cleanup.document)] : []),
+    ] };
+}
+
+function executionCandidates(job) {
+  return [
+    ["definition", job.execution],
+    ["attempt", job.attempt],
+    ["lastRun", job.lastRun],
+  ].filter(([, value]) => value.state !== "absent");
+}
+
+function schedulePlan(schedule, job) {
+  const target = { kind: "scheduled-job", id: `${schedule.path}:${job.id}` };
+  const evidence = [schedule.definitions, schedule.state].filter((entry) => entry.state !== "absent").flatMap((entry) => originFor(entry));
+  const executions = executionCandidates(job), valid = executions.filter(([, value]) => value.state === "valid-shape");
+  const invalid = executions.some(([, value]) => value.state === "invalid") || !!job.problems?.length
+    || schedule.definitions.state === "invalid" || schedule.state.state === "invalid";
+  const unresolvedCustody = [job.attempt.state, job.lastRun.state].some((state) => state === "legacy" || state === "invalid");
+  if (unresolvedCustody) return { target, status: "unknown", action: "hold", evidence,
+    unresolved: [
+      ...(invalid ? [unresolved("invalid-evidence", "the admitted or unknown attempt evidence is malformed", schedule.state)] : []),
+      unresolved("migration-held", "an existing admitted or unknown historical attempt has no valid captured execution; preserve it exactly and require owner reconciliation", schedule.state),
+    ] };
+  if (valid.length) {
+    const preserve = { executions: valid.map(([source, value]) => ({ source, ...value })) };
+    return { target, status: "partial", action: "preserve", evidence, preserve,
+      unresolved: [
+        ...(invalid ? [unresolved("invalid-evidence", "one or more schedule records disagree with the valid captured authority and must remain held", schedule.state)] : []),
+        unresolved("migration-required", "each referenced resolution and admitted execution must be verified without rebinding", schedule.state),
+      ] };
+  }
+  const hasAttempt = job.attempt.state !== "absent" || job.lastRun.state !== "absent";
+  return { target, status: "unknown", action: "hold", evidence,
+    unresolved: [unresolved("migration-held", hasAttempt
+      ? "the admitted or unknown historical attempt has no valid captured execution; preserve it exactly and require owner reconciliation"
+      : "the legacy schedule has no captured software authority", schedule.state)] };
+}
+
+/** Produce a deterministic no-write plan. No target can become reconstructed at
+ * this stage: reconstruction requires the dedicated historical verifier. */
+export function planPortableMigration(inventory) {
+  validatePortableMigrationInventory(inventory);
+  const targets = [
+    ...inventory.locks.map(lockPlan),
+    ...inventory.homes.map(homePlan),
+    ...inventory.schedules.flatMap((schedule) => schedule.jobs.map((job) => schedulePlan(schedule, job))),
+  ].sort((a, b) => compareUtf8(`${a.target.kind}:${a.target.id}`, `${b.target.kind}:${b.target.id}`));
+  if (targets.some((entry) => entry.status === "reconstructed")) throw oatsError("invalid-evidence", "unverified planner output cannot claim reconstruction");
+  const plan = { schemaVersion: MIGRATION_PLAN_VERSION, inventory: jsonIntegrity(inventory), readyToApply: false,
+    effects: { writes: false, providerExecution: false, sessionChanges: false, scheduleChanges: false, trustTransfer: false }, targets };
+  canonicalJson(plan);
+  return plan;
+}