@awebai/oats 0.23.2 → 0.24.0

package/lib/pi-sdk-host.mjs

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

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

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

package/lib/portable-composition.mjs

@@ -0,0 +1,136 @@
+/** Source-aware software choice planning. Consumes validated parser results;
+ * qualifies no hosting identity and performs no acquisition, approval or enrollment.
+ * All precedence/conflicts still go through the single resolveChoices engine. */
+import { canonicalJson, compareUtf8 } from "./portable-values.mjs";
+import { invalidShape, objectAt, pointerKey } from "./portable-shape.mjs";
+import { validateOrigin } from "./resolution-shape.mjs";
+import { sameIdentity, validateSoulIdentity } from "./portable-identity.mjs";
+import { FUNDAMENTAL_SLOTS, validatePolicyChoices } from "./portable-policy.mjs";
+import { capabilityChoiceKey, layerChoiceKey, settingChoiceKey, soulConstraints, sourceSelectionValue } from "./soul-constraints.mjs";
+import { resolveChoices } from "./portable-choices.mjs";
+import { validateRepoAnchor, validateSelectionSource } from "./source-spec.mjs";
+import { isMaterializedCapabilityId } from "./capability-provenance.mjs";
+
+function originAt(parsed, pointer, kind) {
+  const locator = parsed.origins[pointer];
+  if (!locator) invalidShape(pointer, "planning requires the original declaration origin");
+  const origin = { ...locator, kind };
+  validateOrigin(origin);
+  return origin;
+}
+
+export function planSoftwareChoices(input) {
+  canonicalJson(input);
+  objectAt(input, ["identity", "soul", "workspace", "adoptions", "operator", "providerRequirements"], ["identity", "soul"]);
+  const { identity, soul, workspace = null, adoptions = [], operator = null, providerRequirements = [] } = input;
+  validateSoulIdentity(identity);
+  const requirements = soulConstraints(soul), candidates = [], settingsCandidates = [];
+  if (!Array.isArray(adoptions) || !Array.isArray(providerRequirements)) invalidShape("", "adoptions and provider constraints must be arrays");
+  const add = (parsed, key, value, pointer, kind) => candidates.push({ key, value, kind, origin: originAt(parsed, pointer, kind) });
+  const collect = (parsed, policy, pointer, kind, sourceContext) => {
+    const selection = (id, item, at, key) => {
+      const selectedSource = item === false || item === "none" ? null : sourceSelectionValue(id, parsed, at, sourceContext);
+      add(parsed, key, selectedSource, at, kind);
+      if (item && typeof item === "object") for (const [name, value] of Object.entries(item.settings ?? {})) {
+        settingsCandidates.push({ owner: { key, value: selectedSource }, candidate: { key: settingChoiceKey(id, name), value, kind,
+          origin: originAt(parsed, `${at}/settings/${pointerKey(name)}`, kind) } });
+      }
+    };
+    for (const [id, item] of Object.entries(policy.capabilities ?? {})) selection(id, item, `${pointer}/capabilities/${pointerKey(id)}`, capabilityChoiceKey(id));
+    for (const slot of FUNDAMENTAL_SLOTS) if (Object.hasOwn(policy, slot)) {
+      const item = policy[slot]; selection(item === "none" ? null : item.capability, item, `${pointer}/${slot}`, layerChoiceKey(slot));
+    }
+  };
+  if (workspace?.declaration.defaults) collect(workspace, workspace.declaration.defaults, "/defaults", "workspace-default");
+  if (soul.declaration.defaults) collect(soul, soul.declaration.defaults, "/defaults", "soul-default");
+
+  // Discovery supplies qualified identity. An alias never performs this lookup.
+  // Several aliases may contribute compatible fields; conflicting equal-authority
+  // fields are reported by resolveChoices with both original document pointers.
+  for (const adoption of adoptions) {
+    objectAt(adoption, ["identity", "parsed", "origins", "pointer"], ["identity", "parsed", "origins", "pointer"]);
+    validateSoulIdentity(adoption.identity);
+    if (!sameIdentity(adoption.identity, identity)) continue;
+    const imported = adoption.parsed.reference;
+    if (identity.kind !== "git-soul" || imported.soul !== identity.exportPath) invalidShape("/adoptions", "qualified adoption does not match its exported source path");
+    if (identity.repository.kind === "canonical-remote" && imported.source !== identity.repository.remote) invalidShape("/adoptions", "import source contradicts its qualified canonical identity");
+    const parsed = { sources: adoption.parsed.sources, origins: adoption.origins };
+    const root = `${adoption.pointer}/adoption`, value = imported.adoption ?? {};
+    if (value.providers) collect(parsed, value.providers, `${root}/providers`, "import-adoption");
+    for (const field of ["bindings", "teamAliases"]) for (const [key, item] of Object.entries(value[field] ?? {})) {
+      add(parsed, `/adoption/${field}/${pointerKey(key)}`, item, `${root}/${field}/${pointerKey(key)}`, "import-adoption");
+    }
+  }
+  if (operator) {
+    objectAt(operator, ["policy", "document", "localBase", "allowLocalPaths", "sourceContext", "bindings"], ["policy", "document"]);
+    if (operator.bindings !== undefined) objectAt(operator.bindings, null, [], "/operator/bindings");
+    if (operator.sourceContext !== undefined) validateRepoAnchor(operator.sourceContext);
+    if (operator.allowLocalPaths !== undefined && typeof operator.allowLocalPaths !== "boolean") invalidShape("/operator/allowLocalPaths", "expected explicit boolean local-source authorization");
+    validateOrigin({ kind: "operator", document: operator.document, pointer: "/policy" });
+    if (operator.document.kind !== "operator") invalidShape("/operator/document", "operator choices need an operator input locator");
+    const origins = Object.create(null);
+    const mark = (value, pointer) => {
+      origins[pointer] = { document: operator.document, pointer };
+      if (value && typeof value === "object") for (const [key, child] of Object.entries(value)) mark(child, `${pointer}/${pointerKey(key)}`);
+    };
+    mark(operator.policy, "/policy");
+    const sources = validatePolicyChoices(operator.policy, { pointer: "/policy", origins,
+      localBase: operator.localBase, allowLocalPaths: operator.allowLocalPaths === true });
+    collect({ sources, origins }, operator.policy, "/policy", "operator", operator.sourceContext);
+  }
+  for (const requirement of [...requirements, ...providerRequirements]) validateOrigin(requirement.origin);
+  // Provider-owned fixed fields join the SAME constraint pipeline. This function
+  // neither interprets a payload nor executes a provider to obtain these inputs.
+  const allRequirements = [...requirements, ...providerRequirements];
+  // Eligibility follows the selected owning field AND source. Reuse the same
+  // engine for this deterministic source pass, then final field resolution;
+  // nothing is fetched/re-observed and no second precedence policy is introduced.
+  const sourceChoices = resolveChoices({ requirements: allRequirements, candidates }).choices;
+  const excludedSettings = [];
+  for (const { owner, candidate } of settingsCandidates) {
+    if (sameIdentity(sourceChoices[owner.key]?.value ?? null, owner.value)) candidates.push(candidate);
+    else excludedSettings.push({ ...candidate, owner, reason: "owning-source-overridden" });
+  }
+  const result = resolveChoices({ requirements: allRequirements, candidates });
+  const capabilities = Object.create(null), providers = Object.create(null), settings = Object.create(null);
+  const problems = [...result.problems];
+  const select = (key) => {
+    const choice = result.choices[key];
+    if (!choice || choice.value === null) return null;
+    objectAt(choice.value, ["capability", "source"], ["capability", "source"], key);
+    const { capability, source } = choice.value;
+    if (!isMaterializedCapabilityId(capability)) invalidShape(key, "invalid selected capability identity");
+    if (key.startsWith("/capabilities/") && key !== capabilityChoiceKey(capability)) invalidShape(key, "capability choice key differs from its selected identity");
+    validateSelectionSource(source);
+    if (Object.hasOwn(capabilities, capability)) {
+      const prior = capabilities[capability];
+      if (!sameIdentity(prior.source, source)) problems.push({ code: "requirement-conflict", key,
+        message: "one capability identity has incompatible selected sources", origins: [result.choices[prior.choiceKeys[0]].selectedBy, choice.selectedBy] });
+      prior.choiceKeys.push(key);
+    } else capabilities[capability] = { source, choiceKeys: [key] };
+    return capability;
+  };
+  for (const key of Object.keys(result.choices).sort(compareUtf8)) if (key.startsWith("/capabilities/")) select(key);
+  for (const slot of FUNDAMENTAL_SLOTS) {
+    const key = layerChoiceKey(slot);
+    if (Object.hasOwn(result.choices, key)) providers[slot] = select(key);
+  }
+  // Only selected software receives settings; alternative/default history remains
+  // in choices for explanation, not an ambient configuration to execute later.
+  for (const id of Object.keys(capabilities)) settings[id] = Object.create(null);
+  const unescape = (part) => part.replace(/~1/g, "/").replace(/~0/g, "~");
+  for (const key of Object.keys(result.choices)) {
+    if (key.startsWith("/layers/") && !FUNDAMENTAL_SLOTS.some((slot) => key === layerChoiceKey(slot))) invalidShape(key, "unknown fundamental slot choice");
+    if (!key.startsWith("/settings/")) continue;
+    const separator = key.indexOf("/", "/settings/".length);
+    if (separator < 0) invalidShape(key, "setting choice must name a capability and setting");
+    const id = unescape(key.slice("/settings/".length, separator)), name = unescape(key.slice(separator + 1));
+    if (!isMaterializedCapabilityId(id) || settingChoiceKey(id, name) !== key) invalidShape(key, "noncanonical setting choice key");
+    if (Object.hasOwn(settings, id)) settings[id][name] = key;
+  }
+  return { ...result, status: problems.some((problem) => problem.code === "requirement-conflict") ? "conflict" : result.status,
+    requirements: allRequirements, candidates, capabilities, providers, settings, excludedSettings, problems,
+    providerInputs: { knowledge: soul.declaration.knowledge ?? null, stores: workspace?.declaration.knowledge?.stores ?? [] },
+    // Advertisements/adoption aliases are data, never wider-team consent.
+    advertisedTeams: soul.declaration.teams ?? [] };
+}