@awebai/oats 0.25.9 → 0.26.0

package/lib/package-materialization.mjs

@@ -1,83 +0,0 @@
-/** Shared materialization mechanics. Kernel manifest/runtime validators are
- * supplied once by the caller; this module selects no source, lock or approval. */
-import { chmodSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { capabilityArtifactIntegrity, copyTreeSafe } from "./artifact-tree.mjs";
-import { CAPABILITY_INSTALLATION_FILE } from "./capability-provenance.mjs";
-import { executableSurfaceOf } from "./capability-execution.mjs";
-import { oatsError } from "./errors.mjs";
-
-/** Provenance format v1 is byte-stable across writer kernels and digest versions:
- * exactly these keys/order, two-space JSON, one LF, mode0644, no writer version. */
-function capabilityInstallationRecord(cap, pkg) {
-  return {
-    schemaVersion: 1,
-    capability: cap.id,
-    version: cap.manifest.version,
-    package: pkg.package,
-    packageVersion: pkg.version,
-    source: pkg.source,
-    commit: pkg.commit,
-    packagePath: pkg.path,
-    capabilityPath: cap.rel,
-  };
-}
-function assertMaterializationInput(root) {
-  if (!lstatSync(root).isDirectory()) throw oatsError("invalid-package-manifest", "a materialized capability root must be a real directory, not a source alias");
-  let metadata;
-  try { metadata = lstatSync(join(root, CAPABILITY_INSTALLATION_FILE)); }
-  catch (error) { if (error.code === "ENOENT") return; throw error; }
-  if (!metadata.isFile() || (metadata.mode & 0o100) !== 0 || !readdirSync(root).includes(CAPABILITY_INSTALLATION_FILE)) {
-    throw oatsError("invalid-package-manifest", "source provenance entry must not be a link, executable, directory or filesystem alias");
-  }
-}
-function writeCapabilityInstallation(dest, cap, pkg) {
-  assertMaterializationInput(dest);
-  const temporary = mkdtempSync(join(dest, ".installation-")), candidate = join(temporary, "record.json");
-  let failed = false, primary;
-  try {
-    writeFileSync(candidate, JSON.stringify(capabilityInstallationRecord(cap, pkg), null, 2) + "\n", { flag: "wx", mode: 0o644 });
-    chmodSync(candidate, 0o644);
-    // Replace the reserved entry itself, never follow a source-controlled link
-    // or mutate another file sharing its inode. Valid v1 serialization is unchanged.
-    renameSync(candidate, join(dest, CAPABILITY_INSTALLATION_FILE));
-  } catch (error) { failed = true; primary = error; throw error; }
-  finally {
-    try { rmSync(candidate, { force: true }); rmdirSync(temporary); }
-    catch (cleanup) {
-      const error = failed ? new AggregateError([primary, cleanup], "provenance write and staging cleanup failed", { cause: primary })
-        : new Error("provenance staging cleanup failed", { cause: cleanup });
-      error.code = failed ? primary.code : cleanup.code; error.stagingPath = temporary; throw error;
-    }
-  }
-}
-
-export function createCapabilityMaterializer({ materializeCapabilityDeps, assertCapabilitySelfContained, assertMaterializedDepsContained, assertNoNativeBinaries }) {
-  for (const validate of [materializeCapabilityDeps, assertCapabilitySelfContained, assertMaterializedDepsContained, assertNoNativeBinaries]) {
-    if (typeof validate !== "function") throw new TypeError("materializer requires the kernel's complete validation callbacks");
-  }
-  /** The returned legacy integrity remains literal compatibility evidence. New
-   * preparation computes the explicit new-format integrity over this same tree. */
-  return function materializeCapability({ cap, pkg, artifactsDir }) {
-    assertMaterializationInput(cap.dir);
-    const rep = materializeCapabilityDeps(cap.dir);
-    if (rep.error) throw oatsError("invalid-package-manifest", `runtime dependency materialization failed for capability "${cap.id}" of package "${pkg.package}": ${rep.error}`);
-    assertCapabilitySelfContained(cap.dir, cap.manifest);
-    assertMaterializedDepsContained(cap.dir);
-    assertNoNativeBinaries(cap.dir);
-    const dest = join(artifactsDir, cap.id);
-    mkdirSync(dirname(dest), { recursive: true });
-    if (cap.rel === ".") {
-      // Published flat packages need their original root for subsequent template
-      // reads; copy instead of moving, preserving literal links and real modes.
-      copyTreeSafe(cap.dir, dest);
-    } else renameSync(cap.dir, dest);
-    writeCapabilityInstallation(dest, cap, pkg);
-    return {
-      capability: cap.id, version: cap.manifest.version, package: pkg.package, path: cap.rel,
-      dir: dest, integrity: capabilityArtifactIntegrity(dest),
-      layer: cap.manifest.layer ?? null,
-      executableSurface: executableSurfaceOf(cap.manifest), manifest: cap.manifest,
-    };
-  };
-}

package/lib/pi-sdk-host.mjs

@@ -1,229 +0,0 @@
-/** Explicit, zero-plugin Pi SDK host. No auth wrapper, default resource loader,
- * private SDK imports, model substitution or interpretation of legacy Pi argv. */
-import { lstatSync, realpathSync } from "node:fs";
-import { isAbsolute, join, resolve, sep } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { readPortableBytes } from "./portable-files.mjs";
-import { parseStrictJson } from "./portable-values.mjs";
-import { oatsError } from "./errors.mjs";
-
-export const PI_SDK_HOST_VERSION = "1";
-export const PI_SDK_VERSION = "0.85.1";
-export const PI_SDK_HOST = fileURLToPath(new URL("../bin/oats-pi-sdk-host.mjs", import.meta.url));
-const fail = (code, message) => { throw oatsError(code, message); };
-const absolute = value => typeof value === "string" && value.length > 0 && !value.includes("\0") && isAbsolute(value) && resolve(value) === value;
-export function isPiSdkHost(recipe) {
-  return recipe?.runtime === "pi" && recipe.executable === PI_SDK_HOST;
-}
-
-export function parsePiHostModel(value) {
-  if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*\/[^\s\0*?\\]+$/.test(value)
-    || value.includes("!") || value.includes("$") || value.includes("..")) {
-    fail("E_PI_HOST_MODEL", "captured Pi host requires an exact provider/model identifier");
-  }
-  const slash = value.indexOf("/");
-  return { provider: value.slice(0, slash), id: value.slice(slash + 1) };
-}
-
-/** Only operator-owned options; internal home/session/model/task are NEVER here. */
-export function parsePiHostRecipeArgs(args) {
-  const keys = ["--oats-pi-host", "--mode", "--thinking", "--sdk-root", "--sdk-version"];
-  if (!Array.isArray(args) || args.length !== keys.length * 2
-    || args.some(value => typeof value !== "string" || value.includes("\0"))
-    || keys.some((key, i) => args[i * 2] !== key)
-    || args[1] !== PI_SDK_HOST_VERSION || args[3] !== "print" || args[5] !== "medium"
-    || !absolute(args[7]) || args[9] !== PI_SDK_VERSION) {
-    fail("E_PI_HOST_ARGS", "unsupported captured Pi SDK host profile or arguments");
-  }
-  return { hostVersion: args[1], mode: args[3], thinkingLevel: args[5], sdkRoot: args[7], sdkVersion: args[9] };
-}
-
-export function validatePiHostRecipe(recipe) {
-  if (!isPiSdkHost(recipe) || recipe.executableResource || (recipe.executableResolvedFrom !== undefined && recipe.executableResolvedFrom !== "explicit-host")) {
-    fail("E_PI_HOST_SELECTION", "Pi SDK host requires its exact explicit kernel executable");
-  }
-  const options = parsePiHostRecipeArgs(recipe.args);
-  parsePiHostModel(recipe.model);
-  if (!recipe.env || typeof recipe.env !== "object" || Array.isArray(recipe.env) || Object.keys(recipe.env).length
-    || recipe.yolo !== false) fail("E_PI_HOST_SELECTION", "Pi host-v1 has no launch environment contributions or yolo policy");
-  if (recipe.hooks && (Object.keys(recipe.hooks.env ?? {}).length || Object.keys(recipe.hooks.launch ?? {}).length || (recipe.hooks.contributions ?? []).length)) {
-    fail("E_PI_HOST_SELECTION", "Pi host-v1 does not accept launch-hook contributions");
-  }
-  return options;
-}
-
-export function piHostArgv(recipe, { home, sessionDir, taskFile = join(home, "TASK.md") }) {
-  validatePiHostRecipe(recipe);
-  if (![home, sessionDir, taskFile].every(absolute) || taskFile !== join(home, "TASK.md")) fail("E_PI_HOST_ARGS", "invalid kernel Pi host paths");
-  return ["--home", home, "--session-dir", sessionDir, "--model", recipe.model, "--task-file", taskFile, ...recipe.args];
-}
-
-export function parsePiHostArgv(argv) {
-  const keys = ["--home", "--session-dir", "--model", "--task-file"];
-  if (!Array.isArray(argv) || argv.length !== 18 || keys.some((key, i) => argv[i * 2] !== key)) {
-    fail("E_PI_HOST_ARGS", "Pi host accepts only the kernel-rendered argv prefix and closed host profile");
-  }
-  const [home, sessionDir, model, taskFile] = keys.map((_, i) => argv[i * 2 + 1]);
-  if (![home, sessionDir, taskFile].every(absolute) || taskFile !== join(home, "TASK.md")) fail("E_PI_HOST_ARGS", "invalid kernel Pi host paths");
-  const modelSelection = parsePiHostModel(model);
-  return { home, sessionDir, model, modelSelection, taskFile, ...parsePiHostRecipeArgs(argv.slice(8)) };
-}
-
-/** Package metadata only; no SDK import, auth inspection, refresh or model call. */
-export function resolvePiSdkEntry({ sdkRoot, sdkVersion }) {
-  if (!absolute(sdkRoot) || sdkVersion !== PI_SDK_VERSION || !lstatSync(sdkRoot).isDirectory() || realpathSync(sdkRoot) !== sdkRoot) {
-    fail("E_PI_HOST_SDK", "Pi SDK root must be the exact physical selected installation");
-  }
-  // OATS-managed payloads must use their own retained-resource approval surface.
-  if (sdkRoot.split(sep).includes(".agents")) fail("E_PI_HOST_SDK", "managed OATS resources cannot be used as an external SDK installation");
-  const pkg = parseStrictJson(readPortableBytes(join(sdkRoot, "package.json")));
-  const entry = pkg.exports?.["."]?.import;
-  if (pkg.name !== "@earendil-works/pi-coding-agent" || pkg.version !== sdkVersion || typeof entry !== "string" || !entry.startsWith("./")) {
-    fail("E_PI_HOST_SDK", "selected SDK package/name/version/public export does not match the host profile");
-  }
-  const file = resolve(sdkRoot, entry);
-  if (!file.startsWith(sdkRoot + sep) || realpathSync(file) !== file || !lstatSync(file).isFile()) fail("E_PI_HOST_SDK", "Pi public SDK export escapes its selected installation");
-  return pathToFileURL(file).href;
-}
-
-export function readPiHostTask(taskFile) {
-  const bytes = readPortableBytes(taskFile);
-  if (bytes.length > 512 * 1024) fail("E_PI_HOST_TASK", "captured Pi task exceeds the launch bound");
-  let task;
-  try { task = new TextDecoder("utf-8", { fatal: true }).decode(bytes); }
-  catch { fail("E_PI_HOST_TASK", "captured Pi task is not UTF-8"); }
-  if (!task.trim() || task.includes("\0")) fail("E_PI_HOST_TASK", "captured Pi print requires a nonempty task");
-  return { bytes, task };
-}
-
-/** Public ResourceLoader interface. verify() reopens retained authority on EVERY
- * reload, before loadSkills reads anything. No SDK discovery/loader is copied. */
-export function createPiResourceLoader(sdk, { cwd, agentDir, verify }) {
-  let agents, skills, extensions;
-  const ready = () => { if (!agents) fail("E_PI_HOST_CURRICULUM", "Pi curriculum has not been verified"); };
-  return {
-    getExtensions() { ready(); return extensions; },
-    getSkills() { ready(); return skills; },
-    getPrompts: () => ({ prompts: [], diagnostics: [] }),
-    getThemes: () => ({ themes: [], diagnostics: [] }),
-    getAgentsFiles() { ready(); return { agentsFiles: [agents] }; },
-    getSystemPrompt: () => undefined,
-    getSystemPromptSource: () => undefined,
-    getAppendSystemPrompt: () => [],
-    getAppendSystemPromptSources: () => [],
-    extendResources(paths) {
-      if (!paths || typeof paths !== "object" || Array.isArray(paths)
-        || Object.keys(paths).some(key => !["skillPaths", "promptPaths", "themePaths"].includes(key))
-        || Object.values(paths).some(value => !Array.isArray(value) || value.length)) {
-        fail("E_PI_HOST_CURRICULUM", "unselected Pi resource additions are not supported");
-      }
-    },
-    async reload() {
-      agents = skills = extensions = undefined; // failed reload cannot expose a stale verified view
-      const selected = await verify();
-      if (selected.cwd !== cwd || typeof selected.text !== "string" || !Array.isArray(selected.skills)) fail("E_PI_HOST_CURRICULUM", "Pi retained curriculum context changed");
-      const result = sdk.loadSkills({ cwd, agentDir, skillPaths: selected.skills.map(skill => skill.path), includeDefaults: false });
-      if (result.diagnostics.length || result.skills.length !== selected.skills.length) fail("E_PI_HOST_CURRICULUM", "Pi skill loader did not consume the exact retained skill set");
-      for (const wanted of selected.skills) {
-        const found = result.skills.filter(skill => skill.name === wanted.name);
-        if (found.length !== 1 || realpathSync(found[0].filePath) !== realpathSync(wanted.path)) fail("E_PI_HOST_CURRICULUM", "Pi skill identity differs from its retained selection");
-      }
-      await verify(); // no selected-file drift during SDK parsing
-      agents = { path: selected.agentsPath, content: selected.text };
-      skills = result;
-      extensions = { extensions: [], errors: [], runtime: sdk.createExtensionRuntime() };
-    },
-  };
-}
-
-/** Print exposes no history UI/import/resume/branch operations. The proxy is a
- * before-delegation boundary around the real public SDK runtime, not an engine
- * replacement. It never calls a late factory after opening an unowned target. */
-export function guardPiPrintRuntime(runtime) {
-  const unsupported = new Set(["switchSession", "importFromJsonl", "fork", "newSession"]);
-  return new Proxy(runtime, {
-    get(target, key) {
-      if (unsupported.has(key)) return () => fail("E_PI_HOST_HISTORY", "session replacement/import is not supported by this explicit print profile");
-      const value = Reflect.get(target, key, target);
-      return typeof value === "function" ? value.bind(target) : value;
-    },
-  });
-}
-
-/** Non-authorizing metadata from actual PUBLIC SDK/session objects. No prompt,
- * content, raw error, credential/profile or request-as-result material is copied. */
-export function observePiSdkSession(session, sdkVersion) {
-  const text = value => typeof value === "string" && value.length > 0 && value.length <= 4096 && !value.includes("\0") ? value : null;
-  const manager = session.sessionManager, header = manager.getHeader();
-  const messages = session.messages, last = messages.at(-1);
-  const entry = manager.getBranch().findLast(value => value.type === "message");
-  const native = entry?.message;
-  const matchesLast = last?.role === "assistant" && native?.role === "assistant"
-    && native.timestamp === last.timestamp && native.provider === last.provider
-    && native.model === last.model && native.stopReason === last.stopReason;
-  const finalAssistant = matchesLast && text(entry.id) && text(native.provider) && text(native.model)
-    && Number.isFinite(native.timestamp) && native.timestamp >= 0
-    && ["stop", "length", "toolUse", "error", "aborted"].includes(native.stopReason)
-    ? { entryId: entry.id, provider: native.provider, model: native.model,
-      responseModel: text(native.responseModel), stopReason: native.stopReason, timestamp: native.timestamp } : null;
-  return {
-    sdkVersion: text(sdkVersion),
-    header: header?.type === "session" && Number.isSafeInteger(header.version) && text(header.id) && text(header.cwd) && text(header.timestamp)
-      ? { type: "session", version: header.version, id: header.id, cwd: header.cwd, timestamp: header.timestamp } : null,
-    sessionId: text(manager.getSessionId()), sessionFile: text(manager.getSessionFile()),
-    model: text(session.model?.provider) && text(session.model?.id) ? { provider: session.model.provider, id: session.model.id } : null,
-    finalAssistant,
-  };
-}
-
-/** Production uses native services in the user's UNCHANGED profile. No options
- * are passed to ModelRuntime to override stores/auth/config/refresh behavior.
- * Dependencies are injectable for UNIT orchestration checks, not readiness. */
-export async function runPiSdkHost(argv, { verifyContext, onOutcome, importSdk = url => import(url), cwd = process.cwd() } = {}) {
-  const options = parsePiHostArgv(argv);
-  if (typeof verifyContext !== "function" || realpathSync(cwd) !== options.home) fail("E_PI_HOST_CUSTODY", "Pi host requires its admitted captured home context");
-  const verify = () => verifyContext(options);
-  await verify();
-  const { task } = readPiHostTask(options.taskFile);
-  const entry = resolvePiSdkEntry(options);
-  const sdk = await importSdk(entry); // the verified PUBLIC root export only
-  if (sdk.VERSION !== options.sdkVersion) fail("E_PI_HOST_SDK", "loaded Pi SDK version differs from selection");
-  await verify();
-  const agentDir = sdk.getAgentDir(); // native profile resolution, never sessionDir
-  const modelRuntime = await sdk.ModelRuntime.create();
-  const model = modelRuntime.getModel(options.modelSelection.provider, options.modelSelection.id);
-  if (!model || model.provider !== options.modelSelection.provider || model.id !== options.modelSelection.id) fail("E_PI_HOST_MODEL", "selected native Pi model is unavailable; no default was selected");
-  const factory = async ({ cwd: target, agentDir: profile, sessionManager, sessionStartEvent }) => {
-    await verify();
-    if (target !== options.home || profile !== agentDir || sessionManager.getCwd() !== target || sessionManager.getSessionDir() !== options.sessionDir) fail("E_PI_HOST_HISTORY", "Pi runtime context differs from its owned history");
-    const settingsManager = sdk.SettingsManager.create(target, agentDir);
-    const resourceLoader = createPiResourceLoader(sdk, { cwd: target, agentDir, verify });
-    await resourceLoader.reload();
-    const services = { cwd: target, agentDir, modelRuntime, settingsManager, resourceLoader, diagnostics: [] };
-    const built = await sdk.createAgentSessionFromServices({ services, sessionManager, sessionStartEvent, model, thinkingLevel: options.thinkingLevel });
-    if (built.session.model?.id !== model.id || built.session.model?.provider !== model.provider || built.modelFallbackMessage) fail("E_PI_HOST_MODEL", "Pi substituted the captured model");
-    return { ...built, services, diagnostics: [] };
-  };
-  await verify();
-  const sessionManager = sdk.SessionManager.create(options.home, options.sessionDir);
-  const runtime = await sdk.createAgentSessionRuntime(factory, { cwd: options.home, agentDir, sessionManager });
-  let handedToPrint = false, observation = null;
-  try {
-    if (onOutcome) runtime.setBeforeSessionInvalidate(() => {
-      // Public synchronous hook: capture real session data BEFORE disposal, never
-      // synthesize a header/model/final message from the requested launch values.
-      try { observation = observePiSdkSession(runtime.session, sdk.VERSION); }
-      catch { observation = null; } // unavailable evidence cannot qualify success
-    });
-    await verify();
-    if (readPiHostTask(options.taskFile).task !== task) fail("E_PI_HOST_TASK", "captured task changed during Pi startup");
-    handedToPrint = true; // native runPrintMode owns normal disposal/signals/errors
-    const exitCode = await sdk.runPrintMode(guardPiPrintRuntime(runtime), { mode: "text", initialMessage: task });
-    const verified = await verify(); // no successful host outcome after observed custody drift
-    if (!Number.isInteger(exitCode) || exitCode < 0 || exitCode > 255) fail("E_PI_HOST_OUTCOME", "native print mode returned no valid status");
-    if (onOutcome) await onOutcome(options, { exitCode, observation }, verified);
-    return exitCode;
-  } finally {
-    if (!handedToPrint) await runtime.dispose();
-  }
-}

package/lib/portable-artifacts.mjs

@@ -1,115 +0,0 @@
-/** New-format immutable tree storage. Selection, source identity observation,
- * provenance/requirements, approval and dispatch remain separate upper layers.
- * No ambient lock/config/network lookup and no migration of legacy evidence. */
-import { lstatSync, mkdirSync, realpathSync } from "node:fs";
-import { isAbsolute, join, relative, resolve } from "node:path";
-import { assertRetainableTree, ensureStoreIgnore } from "./capability-artifacts.mjs";
-import { isMaterializedCapabilityId } from "./capability-provenance.mjs";
-import { publishArtifactTree } from "./artifact-tree.mjs";
-import { canonicalJson } from "./portable-values.mjs";
-import { TREE_FORMAT, jsonIntegrity, treeIntegrity, validateIntegrity } from "./portable-digest.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 path = relative(root, target);
-  return path === ".." || path.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) || isAbsolute(path);
-};
-
-function referenceParts(reference) {
-  canonicalJson(reference, { maxBytes: 64 * 1024, maxDepth: 16, maxEntries: 1024 });
-  if (!reference || typeof reference !== "object" || Array.isArray(reference)) {
-    throw oatsError("invalid-artifact-reference", "expected a portable artifact reference");
-  }
-  validateIntegrity(reference.integrity, [TREE_FORMAT]);
-  const keys = Object.keys(reference).sort().join(",");
-  let root, extra = [];
-  if (reference.kind === "capability" && keys === "capability,integrity,kind" && isMaterializedCapabilityId(reference.capability)) {
-    root = [".agents", "capabilities", "artifacts"]; extra = [reference.capability];
-  } else if (reference.kind === "soul" && keys === "identity,integrity,kind"
-      && reference.identity && typeof reference.identity === "object" && !Array.isArray(reference.identity)
-      && Object.keys(reference.identity).length > 0) {
-    // The source/record codec qualifies the identity and witness. Storage only
-    // derives an opaque safe key from that exact identity; aliases are not keys.
-    root = [".agents", "soul-artifacts"]; extra = [jsonIntegrity(reference.identity).value];
-  } else if (reference.kind === "resource" && keys === "integrity,kind") {
-    root = [".agents", "resource-artifacts"];
-  } else throw oatsError("invalid-artifact-reference", "invalid portable artifact reference kind/fields");
-  return { root, tail: [...extra, "tree-exec-v1", reference.integrity.value] };
-}
-function explicitScope(scope) {
-  if (typeof scope !== "string" || !isAbsolute(scope)) {
-    throw oatsError("invalid-artifact-store", "artifact deployment scope must be explicit and absolute");
-  }
-  try {
-    const actual = realpathSync(scope);
-    if (!lstatSync(actual).isDirectory()) throw oatsError("invalid-artifact-store", "artifact scope is not a directory");
-    return actual;
-  } catch (error) {
-    if (error.code === "ENOENT") throw oatsError("artifact-not-found", "artifact deployment scope is absent");
-    throw error;
-  }
-}
-
-/** Lexical path only. This does not verify the store, bytes, provenance or trust. */
-export function portableArtifactDir(scope, reference) {
-  if (typeof scope !== "string" || !isAbsolute(scope)) {
-    throw oatsError("invalid-artifact-store", "artifact deployment scope must be explicit and absolute");
-  }
-  const { root, tail } = referenceParts(reference);
-  return join(resolve(scope), ...root, ...tail);
-}
-function storeDirectory(scope, reference, create) {
-  const parts = referenceParts(reference), prefix = [...parts.root, ...parts.tail.slice(0, -1)];
-  let path = explicitScope(scope);
-  for (let index = 0; index < prefix.length; index++) {
-    path = join(path, prefix[index]);
-    if (create) {
-      try { mkdirSync(path, { mode: 0o700 }); }
-      catch (error) { if (error.code !== "EEXIST") throw error; }
-    }
-    const stat = exists(path);
-    if (!stat) throw oatsError("artifact-not-found", "portable artifact store is absent");
-    if (!stat.isDirectory()) throw oatsError("invalid-artifact-store", "managed artifact store component is not a real directory");
-    if (create && index === parts.root.length - 1) ensureStoreIgnore(path);
-  }
-  return path;
-}
-function verifyTree(path, reference) {
-  const stat = exists(path);
-  if (!stat) throw oatsError("artifact-not-found", "portable artifact tree is absent");
-  if (!stat.isDirectory()) throw oatsError("invalid-artifact", "portable artifact root must be a real directory");
-  // Digest traversal is bounded and does not follow links. Then qualify link
-  // containment; neither check uses the original source or an ambient package row.
-  const actual = treeIntegrity(path);
-  if (actual.value !== reference.integrity.value) throw oatsError("integrity-drift", "portable artifact digest does not match its reference");
-  assertRetainableTree(path);
-  return path;
-}
-
-/** Byte/containment verification only, not a complete captured-resolution proof. */
-export function verifyPortableArtifact(scope, reference) {
-  const root = storeDirectory(scope, reference, false);
-  const dir = join(root, reference.integrity.value);
-  verifyTree(dir, reference);
-  return { reference, dir };
-}
-export function retainPortableArtifact(scope, sourceDir, reference) {
-  referenceParts(reference);
-  const deployment = explicitScope(scope);
-  if (typeof sourceDir !== "string" || !isAbsolute(sourceDir)) {
-    throw oatsError("invalid-artifact", "artifact input must be an explicit materialized directory");
-  }
-  verifyTree(sourceDir, reference);
-  const candidate = portableArtifactDir(deployment, reference), source = realpathSync(sourceDir);
-  if (!outside(source, candidate) && source !== candidate) {
-    throw oatsError("invalid-artifact", "artifact source contains its destination store");
-  }
-  const parent = storeDirectory(deployment, reference, true), dir = join(parent, reference.integrity.value);
-  if (exists(dir)) { verifyTree(dir, reference); return { reference, dir, status: "kept" }; }
-  const status = publishArtifactTree(sourceDir, dir, (tree) => verifyTree(tree, reference));
-  return { reference, dir, status };
-}

package/lib/portable-choices.mjs

@@ -1,82 +0,0 @@
-/** The single bounded choice resolver: equality/presence constraints plus
- * fallback values. No expressions, source fetching, provider internals or trust.
- * Field codecs represent a disabled/unbound selection as null; false/[] may be
- * legitimate DATA values. This engine does not guess meaning from strings. */
-import { canonicalJson, compareUtf8 } from "./portable-values.mjs";
-import { invalidShape, objectAt, stringAt } from "./portable-shape.mjs";
-
-const PRIORITY = Object.freeze({ "manifest-default": -1, "workspace-default": 0, "soul-default": 1, "import-adoption": 2, operator: 3 });
-export const CHOICE_KINDS = Object.freeze(Object.keys(PRIORITY));
-const equal = (a, b) => canonicalJson(a) === canonicalJson(b);
-const originOrder = (a, b) => compareUtf8(canonicalJson(a.origin), canonicalJson(b.origin))
-  || compareUtf8(canonicalJson(a), canonicalJson(b));
-
-export function resolveChoices({ requirements = [], candidates = [] } = {}) {
-  canonicalJson({ requirements, candidates });
-  if (!Array.isArray(requirements) || !Array.isArray(candidates)) invalidShape("", "choice inputs must be arrays");
-  const groups = new Map(), choices = Object.create(null), problems = [];
-  const group = (key) => {
-    stringAt(key, "/key");
-    if (!key.startsWith("/")) invalidShape("/key", "choice keys are absolute JSON pointers");
-    if (!groups.has(key)) groups.set(key, { requirements: [], candidates: [] });
-    return groups.get(key);
-  };
-  for (const [index, requirement] of requirements.entries()) {
-    const at = `/requirements/${index}`;
-    objectAt(requirement, ["key", "kind", "value", "origin"], ["key", "kind", "origin"], at);
-    if (!["equals", "required"].includes(requirement.kind)) invalidShape(`${at}/kind`, "unsupported constraint kind");
-    if ((requirement.kind === "equals") !== Object.hasOwn(requirement, "value")) invalidShape(at, "constraint value does not match its kind");
-    objectAt(requirement.origin, null, [], `${at}/origin`);
-    group(requirement.key).requirements.push(requirement);
-  }
-  for (const [index, candidate] of candidates.entries()) {
-    const at = `/candidates/${index}`;
-    objectAt(candidate, ["key", "kind", "value", "origin"], ["key", "kind", "value", "origin"], at);
-    if (!Object.hasOwn(PRIORITY, candidate.kind)) invalidShape(`${at}/kind`, "unsupported choice origin kind");
-    objectAt(candidate.origin, null, [], `${at}/origin`);
-    group(candidate.key).candidates.push(candidate);
-  }
-  const conflict = (key, a, b, message) => {
-    problems.push({ code: "requirement-conflict", key, message, origins: [a.origin, b.origin] });
-  };
-  for (const key of [...groups.keys()].sort(compareUtf8)) {
-    const input = groups.get(key);
-    input.requirements.sort(originOrder);
-    input.candidates.sort((a, b) => PRIORITY[a.kind] - PRIORITY[b.kind] || originOrder(a, b));
-    const fixed = input.requirements.filter((item) => item.kind === "equals");
-    const presence = input.requirements.find((item) => item.kind === "required");
-    const seed = fixed[0];
-    let value = seed ? seed.value : null, selectedBy = seed ? seed.origin : null;
-    for (const other of fixed.slice(1)) if (!equal(seed.value, other.value)) conflict(key, seed, other, "hard requirements disagree");
-    if (seed && presence && seed.value === null) conflict(key, presence, seed, "required value is explicitly absent");
-    const considered = [];
-    let previous;
-    for (const candidate of input.candidates) {
-      if (previous && PRIORITY[candidate.kind] === PRIORITY[previous.kind] && !equal(candidate.value, previous.value)) {
-        conflict(key, previous, candidate, "equal-authority choices disagree");
-      }
-      previous = candidate;
-      const incompatible = (seed && !equal(candidate.value, seed.value)) || (presence && candidate.value === null);
-      if (incompatible) {
-        if (PRIORITY[candidate.kind] >= PRIORITY["import-adoption"]) {
-          conflict(key, seed ?? presence, candidate, "explicit choice cannot erase a hard requirement");
-        }
-        considered.push({ kind: candidate.kind, value: candidate.value, origin: candidate.origin, disposition: "overridden" });
-        continue;
-      }
-      if (!seed || PRIORITY[candidate.kind] >= PRIORITY["import-adoption"]) {
-        value = candidate.value; selectedBy = candidate.origin;
-      }
-      considered.push({ kind: candidate.kind, value: candidate.value, origin: candidate.origin, disposition: "overridden" });
-    }
-    for (const entry of considered) {
-      if (selectedBy && equal(entry.origin, selectedBy) && equal(entry.value, value)) entry.disposition = "selected";
-    }
-    if (presence && value === null && !problems.some((item) => item.key === key)) {
-      problems.push({ code: "needs-configuration", key, message: "required value has no concrete binding", origins: [presence.origin] });
-    }
-    choices[key] = { value, selectedBy, constraints: input.requirements.map(({ key: _, ...constraint }) => constraint), considered };
-  }
-  return { contractVersion: 1, status: problems.some((item) => item.code === "requirement-conflict")
-    ? "conflict" : problems.length ? "needs-configuration" : "resolved", choices, problems };
-}