@awebai/oats 0.25.9 → 0.26.0

package/lib/captured-pi-host.mjs

@@ -1,167 +0,0 @@
-/** Execution-side authority for the explicitly selected native SDK host.
- * Reuses the kernel's actual retained loader and original indexed admission;
- * it never selects a current config, creates an incarnation or admits an action. */
-import { createHash } from "node:crypto";
-import { lstatSync, readlinkSync, readdirSync, realpathSync } from "node:fs";
-import { dirname, isAbsolute, join, resolve } from "node:path";
-import { nativeHistoryPath } from "../packages/record/lib/native-history.mjs";
-import { validateCapturedSessionTarget } from "./captured-session-backend.mjs";
-import { loadCapturedDispatch, applicableRequirements } from "./core.mjs";
-import { readCapturedInstanceAuthority, assertCapturedInstanceCustody, capturedDirectoryIdentity } from "./captured-instance-index.mjs";
-import { validateIntentRef } from "./captured-admission-shape.mjs";
-import { canonicalJson, parseStrictJson } from "./portable-values.mjs";
-import { readPortableBytes } from "./portable-files.mjs";
-import { jsonIntegrity, treeIntegrity } from "./portable-digest.mjs";
-import { assertCapturedPiStart, capturedPiSessionDirectory } from "./captured-pi-custody.mjs";
-import { PI_SDK_HOST, parsePiHostRecipeArgs, parsePiHostArgv, piHostArgv, readPiHostTask, runPiSdkHost, validatePiHostRecipe } from "./pi-sdk-host.mjs";
-import { readPiOutcome, summarizePiOutcome, writePiExitMarker, writePiOutcome } from "./captured-pi-outcome.mjs";
-import { oatsError } from "./errors.mjs";
-
-const same = (a, b) => canonicalJson(a) === canonicalJson(b);
-const refuse = message => { throw oatsError("E_PI_HOST_CUSTODY", message); };
-
-/** Relate the ORIGINAL process ref to the same logical admission. A retry may
- * advance the index counter without redispatching that process. The exact
- * pending ref remains the anchor; the caller MUST also validate its started-v2
- * record/root, input, target, launch and curriculum before any SDK effect. */
-export function verifyPiDispatchRef(row, intent, pending, model) {
-  validateIntentRef(intent);
-  const admitted = row.intents.find(value => value.executionId === intent.executionId);
-  const priorLiveAttempt = admitted && admitted.attempt > intent.attempt;
-  if (row.incarnationId !== intent.incarnationId || !admitted || !Number.isSafeInteger(admitted.attempt)
-    || admitted.attempt < intent.attempt || admitted.capability !== null || admitted.action.kind !== "session"
-    || !["start", "restart"].includes(admitted.action.name)
-    || !(["running", "completed", "unconfirmed"].includes(admitted.state) || (priorLiveAttempt && admitted.state === "admitted"))) {
-    refuse("Pi host execution is not an admitted native action");
-  }
-  if (!pending || pending.id !== intent.executionId || !pending.capturedIntent || !same(pending.capturedIntent, intent)
-    || typeof pending.nativeRecordId !== "string" || !/^[a-f0-9-]{36}$/.test(pending.nativeRecordId)
-    || pending.runtime !== "pi" || pending.model !== model) refuse("Pi host lacks the original native dispatch receipt");
-  // Reconciliation may retain a partial observation or the completed adoption
-  // result. Neither may contradict the original pending dispatch. Absence is
-  // not root authority: the mandatory started-v2 check still supplies that.
-  if (priorLiveAttempt) {
-    const observed = admitted.receipt;
-    if ((observed?.id !== undefined && observed.id !== pending.id)
-      || (observed?.nativeRecordId !== undefined && observed.nativeRecordId !== pending.nativeRecordId)
-      || (observed?.target !== undefined && !same(observed.target, pending.target))) {
-      refuse("Pi reconciliation observation differs from the original dispatch");
-    }
-  }
-  return admitted;
-}
-
-export function verifyCapturedPiHost(options, env = process.env) {
-  if (!env.OATS_DEPLOYMENT || !env.OATS_INCARNATION_ID || !env.OATS_EXECUTION_ID || !/^[1-9][0-9]*$/.test(env.OATS_EXECUTION_ATTEMPT ?? "")
-    || env.OATS_INSTANCE_HOME !== options.home) refuse("Pi host has no original admitted execution context");
-  const intent = { schemaVersion: 1, incarnationId: env.OATS_INCARNATION_ID, executionId: env.OATS_EXECUTION_ID, attempt: Number(env.OATS_EXECUTION_ATTEMPT) };
-  return verifyCapturedPiContext(options, intent, { deployment: env.OATS_DEPLOYMENT, resolutionId: env.OATS_RESOLUTION, instance: env.OATS_INSTANCE });
-}
-
-// Shared read-only verification, NOT an invocation/env constructor. Inspecting
-// observed facts does not impersonate a process or admit another action.
-function verifyCapturedPiContext(options, intent, selector) {
-  const { home, sessionDir } = options;
-  validateIntentRef(intent);
-  const { row, metadata } = readCapturedInstanceAuthority(selector.deployment, home);
-  if (row.incarnationId !== intent.incarnationId || row.executionBinding.resolution.id !== selector.resolutionId
-    || selector.instance !== row.instance) refuse("Pi host invocation differs from original captured custody");
-  const pending = parseStrictJson(readPortableBytes(join(home, ".oats-start-pending.json")));
-  const admitted = verifyPiDispatchRef(row, intent, pending, options.model);
-  validateCapturedSessionTarget(pending.target, metadata.captured.nativeBackend, row.instance);
-  if (pending.target.backend === "herdr" && !same(admitted.receipt?.target, pending.target)) refuse("Pi Herdr target lacks indexed observation");
-  if (!row.nativeScaffold || !same(row.nativeScaffold, metadata.captured.nativeScaffold)) refuse("Pi native scaffold authority changed");
-  const history = nativeHistoryPath(home);
-  for (const [key, path] of Object.entries({ historyRoot: dirname(history), history })) {
-    if (!same(capturedDirectoryIdentity(path), row.nativeScaffold.directories[key])) refuse("Pi native record custody directory changed");
-  }
-  if (sessionDir !== capturedPiSessionDirectory(home)) refuse("Pi session directory differs from the kernel-selected root");
-  assertCapturedPiStart(home, pending.nativeRecordId, { incarnationId: row.incarnationId, intent, sessionDir });
-  const loaded = loadCapturedDispatch({ deployment: row.executionBinding.deployment, resolution: row.executionBinding.resolution, action: { kind: "compose" } });
-  const launch = loaded.record.dispatch.launch;
-  const profile = validatePiHostRecipe(launch);
-  if (launch.executable !== PI_SDK_HOST || !same({ ...launch, hooks: { launch: {}, env: {}, contributions: [] } }, pending.launch) || launch.model !== options.model
-    || !same(profile, parsePiHostRecipeArgs(["--oats-pi-host", options.hostVersion, "--mode", options.mode, "--thinking", options.thinkingLevel, "--sdk-root", options.sdkRoot, "--sdk-version", options.sdkVersion]))) refuse("Pi host differs from the exact retained launch selection");
-  if (loaded.record.dispatch.composition?.mode !== "directory" || loaded.record.dispatch.runtimePackages.length
-    || applicableRequirements("pi", [...loaded.capabilities.values()]).length
-    || [...loaded.capabilities.values()].some(cap => cap.manifest.hooks?.launch)
-    || row.intents.some(value => value.action.kind === "hook" && value.action.name === "spawn" && !value.replayable)
-    || loaded.approvals.some(value => !["approved", "not-required"].includes(value.status))) refuse("retained source is not eligible for the zero-plugin host");
-  const { bytes } = readPiHostTask(options.taskFile);
-  const input = { backend: metadata.captured.nativeBackend, taskIntegrity: { format: "oats.bytes.v1", value: `sha256-${createHash("sha256").update(bytes).digest("hex")}` } };
-  if (!same(jsonIntegrity(input), admitted.inputIntegrity)) refuse("Pi task/backend differs from the admitted input");
-  const agentsPath = join(home, "AGENTS.md");
-  if (readPortableBytes(agentsPath).toString("utf8") !== loaded.composition.text
-    || !lstatSync(join(home, "CLAUDE.md")).isSymbolicLink() || readlinkSync(join(home, "CLAUDE.md")) !== "AGENTS.md"
-    || !lstatSync(join(home, "soul")).isSymbolicLink() || realpathSync(join(home, "soul")) !== dirname(loaded.resources.get(loaded.record.dispatch.composition.body))) refuse("Pi home curriculum differs from retained composition");
-  if (!same(readdirSync(join(home, ".agents/skills")).sort(), loaded.composition.skills.map(skill => skill.name).sort())) refuse("Pi projected skill inventory changed");
-  for (const skill of loaded.composition.skills) {
-    if (!same(treeIntegrity(join(home, ".agents/skills", skill.name)), treeIntegrity(skill.path))) refuse("Pi projected skill bytes changed");
-  }
-  const current = assertCapturedInstanceCustody(row);
-  const currentPending = parseStrictJson(readPortableBytes(join(home, ".oats-start-pending.json")));
-  const currentIntent = verifyPiDispatchRef(current, intent, currentPending, options.model);
-  if (!same(currentPending, pending) || !same(currentIntent.inputIntegrity, admitted.inputIntegrity)) refuse("Pi dispatch evidence changed during verification");
-  // Keep the process's ORIGINAL ref, never the advanced reconciliation counter.
-  assertCapturedPiStart(home, pending.nativeRecordId, { incarnationId: row.incarnationId, intent, sessionDir });
-  return { cwd: home, agentsPath, text: loaded.composition.text,
-    skills: loaded.composition.skills.map(skill => ({ name: skill.name, path: join(skill.path, "SKILL.md") })),
-    outcomeAuthority: { home, sessionDir, incarnationId: row.incarnationId, intent,
-      nativeRecordId: pending.nativeRecordId, executionBinding: row.executionBinding,
-      target: pending.target, inputIntegrity: admitted.inputIntegrity,
-      selected: { runtime: "pi", ...options.modelSelection, sdkVersion: options.sdkVersion } } };
-}
-
-export function runCapturedPiSdkHost(argv) {
-  return runPiSdkHost(argv, { verifyContext: options => verifyCapturedPiHost(options),
-    onOutcome: (options, observed, verified) => writePiOutcome("sdk", verified.outcomeAuthority, observed,
-      () => { if (!same(verifyCapturedPiHost(options).outcomeAuthority, verified.outcomeAuthority)) refuse("Pi outcome custody changed"); }) });
-}
-
-function outcomeOptions(home, nativeRecordId) {
-  const pending = parseStrictJson(readPortableBytes(join(home, ".oats-start-pending.json")));
-  if (pending.nativeRecordId !== nativeRecordId) refuse("Pi outcome is not the original current dispatch; historical re-selection is unsupported");
-  return { pending, options: parsePiHostArgv(piHostArgv(pending.launch, { home, sessionDir: capturedPiSessionDirectory(home) })) };
-}
-
-/** PRIVATE launcher entry, not part of the accepted launch recipe grammar.
- * exitCode is the enclosing launcher's saved `$?`, not runPrintMode's return. */
-export function parsePiExitArgv(argv) {
-  const keys = ["--oats-pi-record-exit", "--home", "--native-record", "--exit-status"];
-  if (!Array.isArray(argv) || argv.length !== 8 || keys.some((key, i) => argv[i * 2] !== key)
-    || argv[1] !== "1" || typeof argv[3] !== "string" || !isAbsolute(argv[3]) || resolve(argv[3]) !== argv[3] || argv[3].includes("\0")
-    || typeof argv[5] !== "string" || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(argv[5])
-    || typeof argv[7] !== "string" || !/^(0|[1-9][0-9]{0,2})$/.test(argv[7]) || Number(argv[7]) > 255) {
-    throw oatsError("E_PI_HOST_ARGS", "invalid private Pi process observation arguments");
-  }
-  return { home: argv[3], nativeRecordId: argv[5], exitCode: Number(argv[7]) };
-}
-
-export function recordCapturedPiExit(argv, env = process.env) {
-  const { home, nativeRecordId, exitCode } = parsePiExitArgv(argv);
-  if (env.OATS_INSTANCE_HOME !== home || !env.OATS_DEPLOYMENT) refuse("Pi exit observer has no original home context");
-  readCapturedInstanceAuthority(env.OATS_DEPLOYMENT, home); // before reading pending paths
-  const { options } = outcomeOptions(home, nativeRecordId);
-  const authority = verifyCapturedPiHost(options, env).outcomeAuthority;
-  const check = () => { if (!same(verifyCapturedPiHost(options, env).outcomeAuthority, authority)) refuse("Pi process observation custody changed"); };
-  writePiOutcome("process", authority, { exitCode, source: "launcher-wait-status" }, check);
-  writePiExitMarker(authority, check);
-  return 0; // observer status ONLY; enclosing shell retains the native status
-}
-
-/** Explicit public read-only query for the current ORIGINAL pending dispatch.
- * No backend/model call, process-env impersonation, admission or provisioning. */
-export function inspectCapturedPiOutcome(home, { deployment, resolution, nativeRecordId }) {
-  const { row } = readCapturedInstanceAuthority(deployment, home);
-  if (!same(row.executionBinding.resolution, resolution)) refuse("Pi outcome selector differs from original captured home");
-  const { options, pending } = outcomeOptions(home, nativeRecordId);
-  const selector = { deployment, resolutionId: resolution.id, instance: row.instance };
-  // Strict JSON decoding uses null-prototype maps. Reify the SAME validated wire
-  // ref as ordinary data for the record API; never advance its attempt or mint it.
-  validateIntentRef(pending.capturedIntent);
-  const intent = { ...pending.capturedIntent };
-  const authority = verifyCapturedPiContext(options, intent, selector).outcomeAuthority;
-  const check = () => { if (!same(verifyCapturedPiContext(options, intent, selector).outcomeAuthority, authority)) refuse("Pi outcome inspection custody changed"); };
-  const sdk = readPiOutcome("sdk", authority, check), process = readPiOutcome("process", authority, check);
-  return summarizePiOutcome(authority, sdk, process, check);
-}

package/lib/captured-pi-outcome.mjs

@@ -1,172 +0,0 @@
-/** Bounded, non-authorizing observations in the EXISTING witnessed Pi history
- * directory. These JSON files are NOT native JSONL transcripts or root proofs. */
-import { closeSync, constants, fstatSync, fsyncSync, lstatSync, openSync, readSync, realpathSync, renameSync, writeSync } from "node:fs";
-import { dirname, isAbsolute, join, resolve } from "node:path";
-import { canonicalJson, parseStrictJson } from "./portable-values.mjs";
-import { objectAt } from "./portable-shape.mjs";
-import { oatsError } from "./errors.mjs";
-
-const bad = message => { throw oatsError("E_PI_HOST_OUTCOME", message); };
-const same = (a, b) => canonicalJson(a) === canonicalJson(b);
-const limits = { maxBytes: 32768, maxDepth: 16, maxEntries: 512 };
-const code = value => Number.isInteger(value) && value >= 0 && value <= 255;
-const text = value => typeof value === "string" && value.length > 0 && value.length <= 4096 && !value.includes("\0");
-
-export function piOutcomePath(sessionDir, nativeRecordId, kind) {
-  if (!isAbsolute(sessionDir) || resolve(sessionDir) !== sessionDir || sessionDir.includes("\0")
-    || typeof nativeRecordId !== "string" || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(nativeRecordId) || !["sdk", "process"].includes(kind)) bad("invalid Pi outcome locator");
-  return join(sessionDir, `.oats-pi-${kind}-${nativeRecordId}.json`);
-}
-
-function syncDirectory(path, check) {
-  check();
-  const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
-  try { fsyncSync(fd); } finally { closeSync(fd); }
-  check();
-}
-
-/** Exclusive publication; uncertain/partial/existing evidence is retained, not
- * overwritten, adopted or cleaned to manufacture a successful observation. */
-function writeOnce(path, bytes, check) {
-  check();
-  const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600);
-  const identity = fstatSync(fd);
-  const checkFile = () => {
-    check();
-    const current = lstatSync(path);
-    if (!current.isFile() || current.dev !== identity.dev || current.ino !== identity.ino) bad("Pi outcome file was replaced during publication");
-  };
-  try {
-    checkFile();
-    let offset = 0;
-    while (offset < bytes.length) {
-      const count = writeSync(fd, bytes, offset, bytes.length - offset);
-      if (count <= 0) bad("Pi outcome write did not complete");
-      offset += count;
-    }
-    fsyncSync(fd); checkFile();
-  } finally { closeSync(fd); }
-  syncDirectory(dirname(path), check);
-  checkFile();
-}
-
-function validateObservation(observed) {
-  objectAt(observed, ["exitCode", "observation"], ["exitCode", "observation"]);
-  if (!code(observed.exitCode)) bad("SDK outcome lacks an observed numeric return status");
-  const o = observed.observation;
-  if (o === null) return;
-  objectAt(o, ["sdkVersion", "header", "sessionId", "sessionFile", "model", "finalAssistant"], ["sdkVersion", "header", "sessionId", "sessionFile", "model", "finalAssistant"]);
-  for (const field of ["sdkVersion", "sessionId", "sessionFile"]) if (o[field] !== null && !text(o[field])) bad("invalid SDK metadata");
-  if (o.header !== null) {
-    objectAt(o.header, ["type", "version", "id", "cwd", "timestamp"], ["type", "version", "id", "cwd", "timestamp"]);
-    if (o.header.type !== "session" || !Number.isSafeInteger(o.header.version) || !["id", "cwd", "timestamp"].every(k => text(o.header[k]))) bad("invalid observed SDK header");
-  }
-  if (o.model !== null) {
-    objectAt(o.model, ["provider", "id"], ["provider", "id"]);
-    if (!text(o.model.provider) || !text(o.model.id)) bad("invalid observed SDK model");
-  }
-  if (o.finalAssistant !== null) {
-    const a = o.finalAssistant;
-    objectAt(a, ["entryId", "provider", "model", "responseModel", "stopReason", "timestamp"], ["entryId", "provider", "model", "responseModel", "stopReason", "timestamp"]);
-    if (!["entryId", "provider", "model"].every(k => text(a[k])) || (a.responseModel !== null && !text(a.responseModel))
-      || !["stop", "length", "toolUse", "error", "aborted"].includes(a.stopReason) || !Number.isFinite(a.timestamp) || a.timestamp < 0) bad("invalid final assistant metadata");
-  }
-}
-
-function validateReceipt(value, kind, authority) {
-  canonicalJson(value, limits);
-  objectAt(value, ["schemaVersion", "kind", "authority", "observed"], ["schemaVersion", "kind", "authority", "observed"]);
-  if (value.schemaVersion !== 1 || value.kind !== `oats.pi-${kind}-outcome` || !same(value.authority, authority)) bad("Pi outcome differs from original dispatch authority");
-  if (kind === "sdk") validateObservation(value.observed);
-  else {
-    objectAt(value.observed, ["exitCode", "source"], ["exitCode", "source"]);
-    if (!code(value.observed.exitCode) || value.observed.source !== "launcher-wait-status") bad("process outcome lacks actual launcher status");
-  }
-  return value;
-}
-
-export function writePiOutcome(kind, authority, observed, check) {
-  const receipt = { schemaVersion: 1, kind: `oats.pi-${kind}-outcome`, authority, observed };
-  validateReceipt(receipt, kind, authority);
-  writeOnce(piOutcomePath(authority.sessionDir, authority.nativeRecordId, kind), Buffer.from(canonicalJson(receipt, limits)), check);
-  return receipt;
-}
-
-/** Preserve the legacy ID-only marker. Called AFTER process outcome publication,
- * under the same original home/root guards, never by an unguarded shell write. */
-export function writePiExitMarker(authority, check) {
-  const temporary = join(authority.home, `.oats-start-exited.${authority.nativeRecordId}.tmp`);
-  writeOnce(temporary, Buffer.from(authority.intent.executionId + "\n"), check);
-  check();
-  renameSync(temporary, join(authority.home, ".oats-start-exited"));
-  syncDirectory(authority.home, check);
-}
-
-export function readPiOutcome(kind, authority, check) {
-  const path = piOutcomePath(authority.sessionDir, authority.nativeRecordId, kind);
-  check();
-  let before;
-  try { before = lstatSync(path); }
-  catch (error) { if (error.code !== "ENOENT") throw error; check(); return null; }
-  if (!before.isFile() || before.size > limits.maxBytes) bad("Pi outcome is not a bounded regular file");
-  const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
-  try {
-    const assertNamedDescriptor = () => {
-      // A pre-open stat can ALSO belong to a redirected ancestor. Bind the FD
-      // to the CURRENT physical name under original-root proof before reading,
-      // not merely to that earlier stat or a root that was restored after open.
-      check();
-      const named = lstatSync(path), opened = fstatSync(fd);
-      if (realpathSync(path) !== path) bad("Pi outcome path is not physical");
-      for (const stat of [named, opened]) {
-        if (!stat.isFile() || stat.dev !== before.dev || stat.ino !== before.ino
-          || stat.size !== before.size || stat.mtimeMs !== before.mtimeMs || stat.ctimeMs !== before.ctimeMs) bad("Pi outcome descriptor differs from its witnessed name");
-      }
-      check();
-    };
-    assertNamedDescriptor();
-    const bytes = Buffer.alloc(before.size + 1);
-    let size = 0;
-    while (size < bytes.length) {
-      assertNamedDescriptor();
-      const n = readSync(fd, bytes, size, bytes.length - size, null);
-      if (n === 0) break;
-      size += n;
-    }
-    assertNamedDescriptor();
-    if (size !== before.size) bad("Pi outcome changed while reading");
-    return validateReceipt(parseStrictJson(bytes.subarray(0, size), limits), kind, authority);
-  } finally { closeSync(fd); }
-}
-
-/** Qualifies ONLY native-print completion, never learning/privacy/readiness or
- * another action. Actual root checks surround receipt/session-path reads. */
-export function summarizePiOutcome(authority, sdk, process, check) {
-  if (sdk) validateReceipt(sdk, "sdk", authority);
-  if (process) validateReceipt(process, "process", authority);
-  const observed = sdk?.observed.observation, selected = authority.selected;
-  let sessionFileObserved = false;
-  if (observed?.sessionFile) {
-    const file = observed.sessionFile;
-    if (!isAbsolute(file) || resolve(file) !== file || dirname(file) !== authority.sessionDir || !file.endsWith(".jsonl")) bad("SDK outcome names an unowned session file");
-    check();
-    try { sessionFileObserved = lstatSync(file).isFile() && realpathSync(file) === file; }
-    catch (error) { if (error.code !== "ENOENT") throw error; }
-    check();
-  }
-  const final = observed?.finalAssistant;
-  const finalObserved = !!(sessionFileObserved && observed.sdkVersion === selected.sdkVersion
-    && observed.header?.version === 3 && observed.header.cwd === authority.home
-    && observed.header.id === observed.sessionId && observed.model?.provider === selected.provider
-    && observed.model.id === selected.id && final?.provider === selected.provider && final.model === selected.id);
-  const processExitCode = process?.observed.exitCode ?? null, sdkExitCode = sdk?.observed.exitCode ?? null;
-  const failed = (processExitCode !== null && processExitCode !== 0) || (sdkExitCode !== null && sdkExitCode !== 0)
-    || (finalObserved && ["error", "aborted"].includes(final.stopReason));
-  const qualified = !failed && processExitCode === 0 && sdkExitCode === 0 && finalObserved && final.stopReason === "stop";
-  check();
-  return { schemaVersion: 1, contract: "oats.pi-print-completion", nonAuthorizing: true,
-    authority, status: qualified ? "succeeded" : failed ? "failed" : "incomplete", qualified,
-    processExitCode, sdkExitCode, finalObserved, sdk: observed ?? null,
-    // No default success when either observer, native header or final turn is absent.
-    evidence: { process: process !== null, sdk: sdk !== null, sessionFile: sessionFileObserved } };
-}

package/lib/captured-resolutions.mjs

@@ -1,275 +0,0 @@
-/** Immutable resolution records outside homes. Exact input verification is not
- * approval, enrollment or host readiness; dispatch must check those separately. */
-import { linkSync, lstatSync, mkdirSync, mkdtempSync, readlinkSync, realpathSync, rmSync, writeFileSync } from "node:fs";
-import { readPortableBytes } from "./portable-files.mjs";
-import { dirname, isAbsolute, join, relative } from "node:path";
-import { ensureStoreIgnore } from "./capability-artifacts.mjs";
-import { canonicalJson, parseStrictJson } from "./portable-values.mjs";
-import { bytesIntegrity, jsonIntegrity, PACKAGE_FORMAT, treeIntegrity } from "./portable-digest.mjs";
-import { settingChoiceKey, soulConstraints } from "./soul-constraints.mjs";
-import { verifyManifestSettings } from "./manifest-settings.mjs";
-import { verifyHelperInjectionPolicies } from "./helper-injection-policy.mjs";
-import { verifyPortableArtifact } from "./portable-artifacts.mjs";
-import { validateResolutionRef, validateResolutionShape } from "./resolution-shape.mjs";
-import { parsePortableSoul } from "./portable-soul.mjs";
-import { parseConfigData } from "./config-data.mjs";
-import { normalizePackagePath } from "./capability-provenance.mjs";
-import { parseLockedSource3, parseRepositorySource } from "./source-spec.mjs";
-import { oatsError } from "./errors.mjs";
-
-const exists = (path) => { try { return lstatSync(path); } catch (error) { if (error.code === "ENOENT") return null; throw error; } };
-const outside = (root, target) => { const part = relative(root, target); return part === ".." || part.startsWith("../") || part.startsWith("..\\") || isAbsolute(part); };
-function store(scope, create) {
-  if (typeof scope !== "string" || !isAbsolute(scope)) throw oatsError("invalid-resolution", "resolution deployment must be explicit and absolute");
-  let root;
-  try { root = realpathSync(scope); }
-  catch (error) { if (error.code === "ENOENT") throw oatsError("resolution-not-found", "resolution deployment is absent"); throw error; }
-  if (!lstatSync(root).isDirectory()) throw oatsError("invalid-resolution", "resolution deployment is not a directory");
-  for (const name of [".agents", "resolutions"]) {
-    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("resolution-not-found", "resolution store is absent");
-    if (!stat.isDirectory()) throw oatsError("invalid-resolution", "managed resolution store component is not a real directory");
-  }
-  if (create) ensureStoreIgnore(root);
-  return root;
-}
-const readBytes = (path, missingCode = "resolution-not-found") => readPortableBytes(path, { missingCode, invalidCode: "invalid-resolution" });
-function decodeRecord(path, reference) {
-  const bytes = readBytes(path), value = parseStrictJson(bytes);
-  if (jsonIntegrity(value).value !== reference.id || !bytes.equals(Buffer.from(canonicalJson(value)))) {
-    throw oatsError("integrity-drift", "captured resolution bytes differ from their canonical address");
-  }
-  // Check the address before inspecting/following any references.
-  validateResolutionShape(value);
-  return value;
-}
-export function readCapturedResolution(scope, reference) {
-  validateResolutionRef(reference);
-  return decodeRecord(join(store(scope, false), `${reference.id}.json`), reference);
-}
-function resourcePath(root, reference) {
-  const path = join(root, reference.path);
-  let actual;
-  try { actual = realpathSync(path); }
-  catch (error) { if (error.code === "ENOENT") throw oatsError("resource-not-found", "captured resource is absent"); throw error; }
-  if (outside(root, actual)) throw oatsError("resource-not-contained", "captured resource escapes its artifact");
-  const stat = lstatSync(actual), directory = ["directory", "skill", "runtime-package"].includes(reference.kind);
-  if (directory ? !stat.isDirectory() : !stat.isFile()) throw oatsError("resource-not-found", "captured resource kind differs from its declaration");
-  return actual;
-}
-
-function canonicalSoulFiles(definition) {
-  const body = join(dirname(definition), "AGENTS.md"), alias = join(dirname(definition), "CLAUDE.md");
-  if (!exists(body)?.isFile() || !exists(alias)?.isSymbolicLink() || isAbsolute(readlinkSync(alias)) || realpathSync(alias) !== realpathSync(body)) {
-    throw oatsError("resolution-incomplete", "captured soul lacks its canonical AGENTS.md/CLAUDE.md alias");
-  }
-  if (exists(join(dirname(definition), "knowledge"))) throw oatsError("resolution-incomplete", "portable soul knowledge must be external");
-}
-function verifySoulConstraints(record, root, definition) {
-  const source = record.subject.soul;
-  const localBase = source.revision.kind === "local" ? parseLockedSource3(source.revision.source, ".").localPath
-    : record.choices["/bindings/source/localBase"]?.value;
-  // Local addresses are only compared to already captured provenance here;
-  // parsing never acquires or reads the original local directory.
-  const definitionBytes = readBytes(definition, "resource-not-found");
-  const sourceDocument = { kind: "source", source: source.revision.kind === "local" ? source.revision.source : source.revision.remote,
-    revision: source.revision.kind === "local" ? "local" : source.revision.commit,
-    path: source.definition, integrity: bytesIntegrity(definitionBytes) };
-  const parsed = parsePortableSoul(definitionBytes, { origin: sourceDocument, localBase, allowLocalPaths: true });
-  const originKey = ({ kind, document, pointer }) => canonicalJson({ kind, document, pointer });
-  for (const expected of soulConstraints(parsed)) {
-    const choice = record.choices[expected.key];
-    const retained = choice?.constraints.some((constraint) => constraint.kind === expected.kind
-      && (expected.kind !== "equals" || canonicalJson(constraint.value) === canonicalJson(expected.value))
-      && originKey(constraint.origin) === originKey(expected.origin));
-    if (!retained) throw oatsError("resolution-incomplete", "captured choice omits its source hard constraint or provenance");
-  }
-  const sourcePath = (path) => {
-    if (!source.projection.roots.some((entry) => entry === "." || path === entry || path.startsWith(`${entry}/`))) {
-      throw oatsError("resolution-incomplete", "declared source resource is not in the captured projection");
-    }
-    const file = join(root, path);
-    if (!exists(file)) throw oatsError("resource-not-found", "declared source resource is absent");
-    if (outside(root, realpathSync(file))) throw oatsError("resource-not-contained", "declared source resource escapes its artifact");
-  };
-  for (const path of parsed.declaration.resources ?? []) sourcePath(path);
-  const check = (id, selection, pointer) => {
-    const row = record.artifacts.capabilities[id];
-    if (!row) throw oatsError("resolution-incomplete", "source hard requirement is not captured");
-    const required = parsed.sources[`${pointer}/source`];
-    const pkg = row.origin.kind === "package" ? record.artifacts.packages[row.origin.package] : null;
-    const actual = pkg ? parseLockedSource3(pkg.source, pkg.path) : parseLockedSource3(row.origin.source, ".");
-    let matches;
-    if (required.kind === "repo") {
-      sourcePath(required.path);
-      if (!pkg || canonicalJson(treeIntegrity(join(root, required.path), { format: PACKAGE_FORMAT })) !== canonicalJson(pkg.integrity)) {
-        throw oatsError("resolution-incomplete", "repo package payload differs from its retained source snapshot");
-      }
-      matches = source.revision.kind === "local"
-        ? actual.kind === "path" && actual.localPath === join(localBase, required.path)
-        : pkg && actual.kind === "git" && pkg.commit === source.revision.commit && pkg.path === required.path
-          && actual.url === parseRepositorySource(source.revision.remote).url;
-    } else matches = required.kind === actual.kind && required.source === actual.source && required.path === actual.path;
-    if (!matches) throw oatsError("resolution-incomplete", "captured capability source violates its soul requirement");
-    for (const [key, expected] of Object.entries(selection.settings ?? {})) {
-      const choiceKey = record.dispatch.settingsChoices[id]?.[key];
-      if (choiceKey !== settingChoiceKey(id, key) || !Object.hasOwn(record.choices, choiceKey)
-          || canonicalJson(record.choices[choiceKey].value) !== canonicalJson(expected)) {
-        throw oatsError("resolution-incomplete", "captured setting violates its soul requirement");
-      }
-    }
-  };
-  const requirements = parsed.declaration.requires ?? {};
-  for (const [id, selection] of Object.entries(requirements.capabilities ?? {})) {
-    check(id, selection, `/requires/capabilities/${id.replace(/~/g, "~0").replace(/\//g, "~1")}`);
-  }
-  for (const slot of ["knowledge", "messaging", "tasks"]) {
-    if (!Object.hasOwn(requirements, slot)) continue;
-    const provider = record.bindings[slot];
-    if (!provider) throw oatsError("resolution-incomplete", "source requires an unbound fundamental provider");
-    const required = requirements[slot];
-    if (required !== "any") {
-      if (provider.capability !== required.capability) throw oatsError("resolution-incomplete", "captured provider violates its soul requirement");
-      check(required.capability, required, `/requires/${slot}`);
-    }
-  }
-  if (parsed.declaration.knowledge) {
-    const binding = record.bindings.knowledge, declared = parsed.declaration.knowledge;
-    if (!binding || binding.payloadContract !== declared.contract || binding.payloadVersion !== declared.version) {
-      throw oatsError("resolution-incomplete", "captured knowledge binding does not support its source declaration");
-    }
-  }
-}
-
-/** Shared row/installation proof for exact record inputs and prospective
- * artifact-set approval. The caller has already verified the artifact tree. */
-export function verifyRetainedCapability(root, artifacts, id, manifest = parseStrictJson(readBytes(join(root, "oats.json"), "resource-not-found"))) {
-  const row = artifacts.capabilities[id];
-  if (!row || manifest.capability !== id || manifest.version !== row.version) throw oatsError("invalid-resolution", "retained manifest identity/version differs from its captured row");
-  if (row.origin.kind === "package") {
-    const pkg = artifacts.packages[row.origin.package];
-    const provenance = parseStrictJson(readBytes(join(root, ".oats-installation.json"), "resource-not-found"));
-    const expected = { schemaVersion: 1, capability: id, version: row.version, package: row.origin.package,
-      packageVersion: pkg.version, source: pkg.source, commit: pkg.commit, packagePath: pkg.path, capabilityPath: row.origin.path };
-    for (const [key, value] of Object.entries(expected)) if (provenance[key] !== value) throw oatsError("invalid-resolution", "retained installation provenance differs from its captured rows");
-  }
-  return manifest;
-}
-
-/** Verify only exact retained inputs. Does not read today's selection lock,
- * config, catalog, source repository, credential values or approval booleans. */
-export function verifyResolutionInputs(scope, reference, { draft, maxRecords = 256 } = {}) {
-  if (!Number.isSafeInteger(maxRecords) || maxRecords < 1 || maxRecords > 4096) throw oatsError("invalid-resolution", "invalid record graph budget");
-  const roots = new Map(), records = new Map(), active = new Set();
-  let edges = 0, bytes = 0;
-  const rootOf = (artifact) => {
-    const key = canonicalJson(artifact);
-    if (!roots.has(key)) roots.set(key, verifyPortableArtifact(scope, artifact).dir);
-    return roots.get(key);
-  };
-  const verify = (ref, supplied, depth) => {
-    validateResolutionRef(ref);
-    if (active.has(ref.id)) throw oatsError("invalid-resolution", "captured helper cycle");
-    if (records.has(ref.id)) return records.get(ref.id);
-    if (depth > 64 || records.size + active.size >= maxRecords) throw oatsError("resource-limit", "captured helper graph limit exceeded");
-    const record = supplied ?? readCapturedResolution(scope, ref);
-    validateResolutionShape(record);
-    const encoded = canonicalJson(record);
-    if (jsonIntegrity(record).value !== ref.id) throw oatsError("integrity-drift", "resolution draft/reference mismatch");
-    bytes += Buffer.byteLength(encoded);
-    if (bytes > 32 * 1024 * 1024) throw oatsError("resource-limit", "aggregate captured record byte limit exceeded");
-    active.add(ref.id);
-    try {
-      if (record.subject.kind === "persistent") {
-        const soul = record.subject.soul, root = rootOf(soul.sourceArtifact);
-        const definition = resourcePath(root, { path: soul.definition, kind: "file" });
-        for (const path of soul.projection.roots) {
-          const projected = join(root, path);
-          if (!exists(projected)) throw oatsError("resource-not-found", "captured source projection root is absent");
-          if (outside(root, realpathSync(projected))) throw oatsError("resource-not-contained", "captured source projection escapes its artifact");
-        }
-        canonicalSoulFiles(definition);
-        verifySoulConstraints(record, root, definition);
-      } else resourcePath(rootOf(record.subject.provider), record.subject.definition);
-      for (const row of Object.values(record.artifacts.capabilities)) rootOf(row.artifact);
-      for (const artifact of record.resourceBundles) rootOf(artifact);
-      const resources = new Map();
-      for (const [key, resource] of Object.entries(record.resources)) resources.set(key, resourcePath(rootOf(resource.owner), resource));
-      const definitions = Object.entries(record.dispatch.providerManifests).map(([id, resourceKey]) => ({
-        artifact: record.artifacts.capabilities[id].artifact, bytes: readBytes(resources.get(resourceKey), "resource-not-found"),
-      }));
-      const manifests = verifyManifestSettings(record, definitions);
-      verifyHelperInjectionPolicies(record, definitions);
-      for (const [id, manifest] of manifests) {
-        const row = record.artifacts.capabilities[id];
-        verifyRetainedCapability(rootOf(row.artifact), record.artifacts, id, manifest);
-        if (record.subject.kind === "helper" && record.subject.provider.capability === id) {
-          const declared = Array.isArray(manifest.agents) && manifest.agents.some((entry) => {
-            const path = normalizePackagePath(entry);
-            return path !== undefined && record.subject.definition.path === (path === "." ? "soul.yaml" : `${path}/soul.yaml`);
-          });
-          if (!declared) throw oatsError("resolution-incomplete", "captured helper is not exported by its retained provider");
-          const definition = resourcePath(rootOf(row.artifact), record.subject.definition);
-          const helper = parseConfigData(readBytes(definition, "resource-not-found")).value;
-          if (helper?.name !== record.subject.name) throw oatsError("resolution-incomplete", "captured helper name differs from its definition");
-          canonicalSoulFiles(definition);
-        }
-        for (const [slot, binding] of Object.entries(record.bindings)) {
-          if (binding.capability === id && manifest.layer !== slot) throw oatsError("invalid-resolution", "retained provider implements a different fundamental slot");
-        }
-      }
-      for (const helper of Object.values(record.helpers)) {
-        if (++edges > 4096) throw oatsError("resource-limit", "captured helper edge limit exceeded");
-        const child = verify(helper, undefined, depth + 1);
-        if (child.record.subject.kind !== "helper") throw oatsError("invalid-resolution", "captured helper reference names a persistent soul");
-      }
-      const result = { record, resources, manifests };
-      records.set(ref.id, result);
-      return result;
-    } finally { active.delete(ref.id); }
-  };
-  const result = verify(reference, draft, 0);
-  return { ...result, reference, roots, records };
-}
-
-/** Commit only a verified prepared record, by atomic no-replace publication.
- * Legacy reconstruction needs the later explicit migration/evidence verifier. */
-export function commitCapturedResolution(scope, draft) {
-  validateResolutionShape(draft);
-  if (draft.capture !== "prepared") throw oatsError("migration-required", "historical reconstruction requires the explicit migration verifier");
-  const reference = { schemaVersion: 1, id: jsonIntegrity(draft).value };
-  const verified = verifyResolutionInputs(scope, reference, { draft });
-  let existingRoot;
-  try { existingRoot = store(scope, false); }
-  catch (error) { if (error.code !== "resolution-not-found") throw error; }
-  const existingTarget = existingRoot && join(existingRoot, `${reference.id}.json`);
-  if (existingTarget && exists(existingTarget)) { decodeRecord(existingTarget, reference); return reference; }
-  // Literal old evidence can be read/reused, but no caller (including callers
-  // bypassing the compiler) may mint a new slot-derived/missing-policy helper.
-  verifyHelperInjectionPolicies(draft, Object.entries(draft.dispatch.providerManifests).map(([id, key]) => ({
-    artifact: draft.artifacts.capabilities[id].artifact, bytes: readBytes(verified.resources.get(key), "resource-not-found"),
-  })), { publishing: true });
-  const root = store(scope, true), target = join(root, `${reference.id}.json`);
-  const staging = mkdtempSync(join(root, ".resolution-"));
-  let failed = false, primary;
-  try {
-    const candidate = join(staging, "record.json");
-    writeFileSync(candidate, canonicalJson(draft), { flag: "wx", mode: 0o600 });
-    decodeRecord(candidate, reference);
-    try { linkSync(candidate, target); } catch (error) { if (error.code !== "EEXIST") throw error; }
-    decodeRecord(target, 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], "resolution publication and cleanup failed", { cause: primary })
-        : new Error("resolution staging cleanup failed", { cause: cleanup });
-      error.code = failed ? primary.code : cleanup.code;
-      error.stagingPath = staging;
-      throw error;
-    }
-  }
-}