@awebai/oats 0.23.2 → 0.24.0

package/lib/portable-soul.mjs

@@ -0,0 +1,38 @@
+/** Versioned soul declarations: parsing and origins, not composition or execution.
+ * Requirements constrain the later single resolver; defaults never erase them. */
+import { parseConfigData } from "./config-data.mjs";
+import { portablePath } from "./source-spec.mjs";
+import { invalidShape, objectAt, stringAt, stringSetAt, versionAt } from "./portable-shape.mjs";
+import { validatePolicyChoices, validateProviderDeclaration } from "./portable-policy.mjs";
+
+export { FUNDAMENTAL_SLOTS } from "./portable-policy.mjs";
+const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const ALIAS = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+const LAUNCH_CONFIG_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const ROOT_FIELDS = ["schemaVersion", "name", "description", "requires", "defaults", "knowledge", "teams", "resources", "work", "runtime", "model", "yolo", "launch-config", "backend"];
+
+export function parsePortableSoul(input, { origin = null, localBase, allowLocalPaths = false, limits } = {}) {
+  const parsed = parseConfigData(input, { origin, limits });
+  const value = objectAt(parsed.value, ROOT_FIELDS, ["schemaVersion", "name"]);
+  versionAt(value.schemaVersion);
+  stringAt(value.name, "/name", { pattern: NAME });
+  if (Object.hasOwn(value, "description")) stringAt(value.description, "/description", { empty: true });
+  const sources = Object.create(null);
+  for (const section of ["requires", "defaults"]) {
+    if (!Object.hasOwn(value, section)) continue;
+    Object.assign(sources, validatePolicyChoices(value[section], {
+      pointer: `/${section}`, required: section === "requires", origins: parsed.origins,
+      origin, localBase, allowLocalPaths,
+    }));
+  }
+  if (Object.hasOwn(value, "knowledge")) validateProviderDeclaration(value.knowledge, "/knowledge");
+  if (Object.hasOwn(value, "teams")) stringSetAt(value.teams, "/teams", (item, pointer) => stringAt(item, pointer, { pattern: ALIAS }));
+  if (Object.hasOwn(value, "resources")) stringSetAt(value.resources, "/resources", (item) => portablePath(item, { allowRoot: true }));
+  if (Object.hasOwn(value, "work") && !["worktree", "checkout", "attached", "workspace", "directory"].includes(value.work)) invalidShape("/work", "unsupported work mode");
+  if (Object.hasOwn(value, "runtime") && !["pi", "claude", "codex"].includes(value.runtime)) invalidShape("/runtime", "unsupported runtime");
+  if (Object.hasOwn(value, "model")) stringAt(value.model, "/model");
+  if (Object.hasOwn(value, "launch-config")) stringAt(value["launch-config"], "/launch-config", { pattern: LAUNCH_CONFIG_NAME });
+  if (Object.hasOwn(value, "backend") && !["tmux", "herdr"].includes(value.backend)) invalidShape("/backend", "unsupported session backend");
+  if (Object.hasOwn(value, "yolo") && typeof value.yolo !== "boolean") invalidShape("/yolo", "expected boolean");
+  return { declaration: value, sources, origins: parsed.origins, integrity: parsed.integrity };
+}

package/lib/portable-state.mjs

@@ -0,0 +1,80 @@
+/** Cooperative serialization for new portable-state writers, not legacy cutover
+ * or hostile-host locking. A crashed guard is held for explicit recovery. */
+import { linkSync, lstatSync, mkdirSync, mkdtempSync, realpathSync, renameSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import { canonicalJson } from "./portable-values.mjs";
+import { ensureStoreIgnore } from "./capability-artifacts.mjs";
+import { oatsError } from "./errors.mjs";
+
+export function portableScope(scope) {
+  if (typeof scope !== "string" || !isAbsolute(scope)) throw oatsError("invalid-artifact-store", "portable deployment must be explicit and absolute");
+  const actual = realpathSync(scope);
+  if (!lstatSync(actual).isDirectory()) throw oatsError("invalid-artifact-store", "portable deployment must be a directory");
+  return actual;
+}
+export function portableStateDirectory(scope, create = false) {
+  let root = portableScope(scope);
+  for (const name of [".agents", "portable"]) {
+    root = join(root, name);
+    if (create) { try { mkdirSync(root, { mode: 0o700 }); } catch (error) { if (error.code !== "EEXIST") throw error; } }
+    let stat;
+    try { stat = lstatSync(root); } catch (error) { if (!create && error.code === "ENOENT") return null; throw error; }
+    if (!stat.isDirectory()) throw oatsError("invalid-artifact-store", "managed portable-state component is not a real directory");
+  }
+  if (create) ensureStoreIgnore(root);
+  return root;
+}
+const activeWrites = new WeakSet();
+
+/** Only an active synchronous write can publish a mutable metadata document. */
+export function writeGuardedPortableDocument(context, target, value, { absent = false } = {}) {
+  if (!activeWrites.has(context)) throw oatsError("selection-changed", "portable write context is not active");
+  const { root, deployment } = context;
+  if (dirname(target) !== root && target !== join(deployment, "oats-lock.json")) throw oatsError("invalid-artifact-store", "portable write target is outside its owned metadata namespace");
+  const bytes = canonicalJson(value), staging = mkdtempSync(join(root, ".document-")), candidate = join(staging, "document.json");
+  let failed = false, primary;
+  try {
+    writeFileSync(candidate, bytes, { flag: "wx", mode: 0o600 });
+    if (absent) {
+      try { linkSync(candidate, target); }
+      catch (error) { if (error.code === "EEXIST") throw oatsError("selection-changed", "portable metadata appeared during first publication"); throw error; }
+    } else renameSync(candidate, target);
+  } 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], "portable metadata write and staging cleanup failed", { cause: primary })
+        : new Error("portable metadata staging cleanup failed", { cause: cleanup });
+      error.code = failed ? primary.code : cleanup.code; error.stagingPath = staging; throw error;
+    }
+  }
+}
+
+export function withPortableStateWrite(scope, write) {
+  const deployment = portableScope(scope), root = portableStateDirectory(deployment, true), guard = join(root, ".write-guard");
+  try { mkdirSync(guard, { mode: 0o700 }); }
+  catch (error) {
+    if (error.code === "EEXIST") throw oatsError("selection-changed", "portable state has another writer or a held recovery guard");
+    throw error;
+  }
+  const owned = lstatSync(guard), context = Object.freeze({ deployment, root });
+  activeWrites.add(context);
+  let failed = false, primary;
+  try { return write(context); }
+  catch (error) { failed = true; primary = error; throw error; }
+  finally {
+    activeWrites.delete(context);
+    try {
+      const current = lstatSync(guard);
+      if (!current.isDirectory() || current.dev !== owned.dev || current.ino !== owned.ino) throw oatsError("selection-changed", "portable write guard ownership changed");
+      // Empty owned guard only; never force-remove a foreign/stale guard tree.
+      rmdirSync(guard);
+    } catch (cleanup) {
+      const error = failed ? new AggregateError([primary, cleanup], "portable state write and guard cleanup failed", { cause: primary })
+        : new Error("portable write guard cleanup failed", { cause: cleanup });
+      error.code = failed ? primary.code : cleanup.code;
+      error.guardPath = guard;
+      throw error;
+    }
+  }
+}

package/lib/portable-values.mjs

@@ -0,0 +1,181 @@
+/** Bounded data codecs shared by portable declarations and retained records.
+ * No source resolution, filesystem access, getters, or caller serialization hooks. */
+import { oatsError } from "./errors.mjs";
+
+const DEFAULTS = Object.freeze({ maxBytes: 8 * 1024 * 1024, maxDepth: 64, maxEntries: 100_000 });
+export function dataLimits(options = {}) {
+  const limits = { ...DEFAULTS, ...options };
+  for (const key of Object.keys(DEFAULTS)) {
+    if (!Number.isSafeInteger(limits[key]) || limits[key] < 1) {
+      throw oatsError("invalid-declaration", `invalid data limit: ${key}`);
+    }
+  }
+  if (limits.maxDepth > 256) throw oatsError("invalid-declaration", "maximum supported data depth is 256");
+  return limits;
+}
+export function scalarString(value, where = "value") {
+  if (typeof value !== "string" || Buffer.from(value, "utf8").toString("utf8") !== value) {
+    throw oatsError("invalid-declaration", `expected Unicode-scalar string at ${where}`);
+  }
+  return value;
+}
+const typedArrayPrototype = Object.getPrototypeOf(Uint8Array.prototype);
+const byteLengthOf = Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteLength").get;
+const byteOffsetOf = Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteOffset").get;
+const bufferOf = Object.getOwnPropertyDescriptor(typedArrayPrototype, "buffer").get;
+
+/** Intrinsic getters bypass caller-owned byteLength/buffer accessors. Pass an
+ * undecorated view to platform codecs, rather than the caller's decorated object. */
+export function byteView(input, where = "input") {
+  if (!(input instanceof Uint8Array)) throw oatsError("invalid-declaration", `expected UTF-8 bytes at ${where}`);
+  try { return new Uint8Array(bufferOf.call(input), byteOffsetOf.call(input), byteLengthOf.call(input)); }
+  catch { throw oatsError("invalid-declaration", `invalid byte view at ${where}`); }
+}
+export function decodeUtf8(input, where = "input") {
+  if (typeof input === "string") return scalarString(input, where);
+  const bytes = byteView(input, where);
+  try { return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes); }
+  catch { throw oatsError("invalid-declaration", `invalid UTF-8 at ${where}`); }
+}
+export const compareUtf8 = (a, b) => Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
+
+/** Freeze a bounded JSON observation, never caller accessors or cyclic objects. */
+export function freezeJson(value) {
+  canonicalJson(value);
+  const seen = new WeakSet();
+  const freeze = (item) => {
+    if (!item || typeof item !== "object" || seen.has(item)) return;
+    seen.add(item); for (const child of Object.values(item)) freeze(child); Object.freeze(item);
+  };
+  freeze(value); return value;
+}
+
+/** Canonical JSON includes exactly one final LF. Emit sorted keys directly:
+ * JSON.stringify on a rebuilt object would reorder integer-looking keys. */
+export function canonicalJson(value, options) {
+  const limits = dataLimits(options), chunks = [], active = new WeakSet();
+  let bytes = 0, entries = 0;
+  const emit = (text) => {
+    bytes += Buffer.byteLength(text, "utf8");
+    if (bytes > limits.maxBytes) throw oatsError("resource-limit", "canonical JSON byte limit exceeded");
+    chunks.push(text);
+  };
+  const visit = (item, depth) => {
+    if (depth > limits.maxDepth || ++entries > limits.maxEntries) {
+      throw oatsError("resource-limit", "canonical JSON depth/entry limit exceeded");
+    }
+    if (item === null || typeof item === "boolean") { emit(JSON.stringify(item)); return; }
+    if (typeof item === "string") { emit(JSON.stringify(scalarString(item))); return; }
+    if (typeof item === "number" && Number.isFinite(item)) { emit(JSON.stringify(item)); return; }
+    if (typeof item !== "object") throw oatsError("invalid-declaration", "value is not finite JSON data");
+    if (active.has(item)) throw oatsError("invalid-declaration", "cyclic JSON data");
+    const array = Array.isArray(item), proto = Object.getPrototypeOf(item);
+    if (proto !== (array ? Array.prototype : Object.prototype) && !(proto === null && !array)) {
+      throw oatsError("invalid-declaration", "JSON data must use plain objects and arrays");
+    }
+    const descriptors = Object.getOwnPropertyDescriptors(item), keys = Reflect.ownKeys(descriptors);
+    if (keys.length > limits.maxEntries - entries + (array ? 1 : 0)) {
+      throw oatsError("resource-limit", "canonical JSON entry limit exceeded");
+    }
+    for (const key of keys) {
+      if (typeof key !== "string") throw oatsError("invalid-declaration", "symbol keys are not JSON data");
+      scalarString(key, "object key");
+      const descriptor = descriptors[key];
+      if (!Object.hasOwn(descriptor, "value") || (!descriptor.enumerable && !(array && key === "length"))) {
+        throw oatsError("invalid-declaration", "accessor/non-enumerable properties are not JSON data");
+      }
+    }
+    active.add(item);
+    try {
+      if (array) {
+        const length = descriptors.length.value;
+        if (length > limits.maxEntries - entries) throw oatsError("resource-limit", "canonical JSON array limit exceeded");
+        if (keys.length !== length + 1) throw oatsError("invalid-declaration", "sparse or extended arrays are not JSON data");
+        emit("[");
+        for (let i = 0; i < length; i++) {
+          if (!Object.hasOwn(descriptors, String(i))) throw oatsError("invalid-declaration", "sparse or extended arrays are not JSON data");
+          if (i) emit(",");
+          visit(descriptors[i].value, depth + 1);
+        }
+        emit("]");
+      } else {
+        emit("{");
+        keys.sort(compareUtf8).forEach((key, index) => {
+          if (index) emit(",");
+          emit(JSON.stringify(key)); emit(":"); visit(descriptors[key].value, depth + 1);
+        });
+        emit("}");
+      }
+    } finally { active.delete(item); }
+  };
+  visit(value, 0); emit("\n");
+  return chunks.join("");
+}
+
+/** JSON.parse alone cannot detect duplicate decoded keys. This small JSON
+ * decoder preserves that check and budgets; YAML must use it for JSON input,
+ * not maintain another permissive JSON reader. Objects have null prototypes. */
+export function parseStrictJson(input, options) {
+  const limits = dataLimits(options);
+  const data = typeof input === "string" ? input : byteView(input);
+  if ((typeof data === "string" ? Buffer.byteLength(data) : byteLengthOf.call(data)) > limits.maxBytes) {
+    throw oatsError("resource-limit", "JSON input byte limit exceeded");
+  }
+  const text = decodeUtf8(data);
+  let at = 0, entries = 0;
+  const bad = () => { throw oatsError("invalid-declaration", `invalid JSON at character ${at}`); };
+  const space = () => { while (at < text.length && /[\x20\t\r\n]/.test(text[at])) at++; };
+  const string = () => {
+    const start = at++;
+    while (at < text.length) {
+      const char = text[at++];
+      if (char === "\\") { at++; continue; }
+      if (char === '"') {
+        let value;
+        try { value = JSON.parse(text.slice(start, at)); } catch { bad(); }
+        return scalarString(value);
+      }
+    }
+    bad();
+  };
+  const value = (depth) => {
+    if (depth > limits.maxDepth || ++entries > limits.maxEntries) {
+      throw oatsError("resource-limit", "JSON depth/entry limit exceeded");
+    }
+    space();
+    const char = text[at];
+    if (char === '"') return string();
+    if (char === "{" || char === "[") {
+      const array = char === "[", result = array ? [] : Object.create(null), close = array ? "]" : "}";
+      at++; space();
+      if (text[at] === close) { at++; return result; }
+      for (;;) {
+        if (array) result.push(value(depth + 1));
+        else {
+          if (text[at] !== '"') bad();
+          const key = string(); space();
+          if (Object.hasOwn(result, key)) throw oatsError("invalid-declaration", `duplicate JSON key at character ${at}`);
+          if (text[at++] !== ":") bad();
+          result[key] = value(depth + 1);
+        }
+        space();
+        if (text[at] === close) { at++; return result; }
+        if (text[at++] !== ",") bad();
+        space();
+      }
+    }
+    for (const [token, decoded] of [["true", true], ["false", false], ["null", null]]) {
+      if (text.startsWith(token, at)) { at += token.length; return decoded; }
+    }
+    const number = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/.exec(text.slice(at));
+    if (number) {
+      at += number[0].length;
+      const result = Number(number[0]);
+      if (Number.isFinite(result)) return result;
+    }
+    bad();
+  };
+  const result = value(0); space();
+  if (at !== text.length) bad();
+  return result;
+}

package/lib/prepare-composition.mjs

@@ -0,0 +1,151 @@
+/** Explicit source-to-record preparation. Current locks are inputs to NEW work
+ * only; source/package observations are frozen once and never dispatch authority. */
+import { isAbsolute, join } from "node:path";
+import { objectAt } from "./portable-shape.mjs";
+import { canonicalJson, compareUtf8 } from "./portable-values.mjs";
+import { readPortableBytes } from "./portable-files.mjs";
+import { validateOrigin } from "./resolution-shape.mjs";
+import { createWorkspaceDiscovery } from "./workspace-discovery.mjs";
+import { parseSoulImport } from "./workspace-definition.mjs";
+import { sameIdentity } from "./portable-identity.mjs";
+import { planSoftwareChoices } from "./portable-composition.mjs";
+import { captureManifestSettings } from "./manifest-settings.mjs";
+import { bindingDeclaration, operatorBindingDeclaration, prepareProviderBindings } from "./prepared-bindings.mjs";
+import { preparePackageArtifacts } from "./portable-package-preparation.mjs";
+import { parseLockedSource3, parseRepositorySource } from "./source-spec.mjs";
+import { retainPortableArtifact, verifyPortableArtifact } from "./portable-artifacts.mjs";
+import { treeIntegrity } from "./portable-digest.mjs";
+import { readLock3, writeLock3, emptyLock3, artifactSetKey3, requestKey3 } from "./portable-lock.mjs";
+import { readApprovalLedger, evaluateCapturedApprovals } from "./artifact-approvals.mjs";
+import { commitCapturedResolution } from "./captured-resolutions.mjs";
+import { oatsError } from "./errors.mjs";
+
+// Project an ALREADY RESOLVED package graph for lock-v3's per-root set. This
+// performs no dependency parsing, source lookup, acquisition or version choice.
+function packageSubset(artifacts, root) {
+  const ids = new Set([root]), pending = [root];
+  while (pending.length) for (const id of artifacts.packages[pending.pop()].dependencies) if (!ids.has(id)) { ids.add(id); pending.push(id); }
+  return { schemaVersion: 1, packages: Object.fromEntries([...ids].sort(compareUtf8).map((id) => [id, artifacts.packages[id]])),
+    capabilities: Object.fromEntries(Object.entries(artifacts.capabilities).filter(([, row]) => row.origin.kind === "package" && ids.has(row.origin.package))) };
+}
+
+/** Repositories and kernel callbacks belong to this operation; the caller owns
+ * their lifetime/scratch cleanup. No hook, launch, enrollment or approval here. */
+export function prepareComposition(input, { repositories, kernel, previous: suppliedPrevious }) {
+  canonicalJson(input);
+  objectAt(input, ["deployment", "directory", "source", "origin", "workspace", "member", "operator", "mode", "allowLocalPaths", "standaloneContextKey", "launch", "helperLaunches"], ["deployment", "directory", "source", "origin"]);
+  const { deployment, directory, source: requested, origin, workspace: workspaceRequest, member, operator, allowLocalPaths = false } = input;
+  const hasWorkspace = Object.hasOwn(input, "workspace");
+  const hasStandaloneContext = Object.hasOwn(input, "standaloneContextKey"), standaloneContextKey = input.standaloneContextKey;
+  if (hasWorkspace && hasStandaloneContext) throw oatsError("invalid-declaration", "workspace and standaloneContextKey are mutually exclusive");
+  if (hasStandaloneContext && standaloneContextKey !== null
+      && (typeof standaloneContextKey !== "string" || !standaloneContextKey || standaloneContextKey.includes("\0") || Buffer.byteLength(standaloneContextKey, "utf8") > 256)) {
+    throw oatsError("invalid-declaration", "standaloneContextKey must be explicit null or non-empty opaque text up to 256 bytes");
+  }
+  if (typeof directory !== "string" || !isAbsolute(directory) || typeof allowLocalPaths !== "boolean") throw oatsError("invalid-declaration", "preparation needs an explicit scratch directory and local-input policy");
+  validateOrigin(origin);
+  const previous = suppliedPrevious ?? readLock3(deployment); // Public wrapper reads once BEFORE creating scratch or fetching.
+  const discovery = createWorkspaceDiscovery(repositories);
+  const workspace = hasWorkspace ? discovery.readWorkspace(workspaceRequest) : null;
+  let reference = requested, sourceOrigin = origin;
+  if (typeof requested === "string") {
+    const index = workspace?.parsed.imports.findIndex((entry) => entry.alias === requested) ?? -1;
+    if (index < 0) throw oatsError("export-not-found", "requested alias is not advertised by this workspace");
+    reference = workspace.parsed.imports[index];
+    sourceOrigin = { ...workspace.parsed.origins[`/imports/${index}`], kind: "import-adoption" };
+  }
+  if (member) {
+    if (!workspace) throw oatsError("needs-configuration", "member work needs an explicit workspace");
+    const membership = discovery.checkMember(workspace, member);
+    if (membership.status !== "eligible") return { status: "needs-configuration", resolution: null, problems: membership.problems };
+  }
+  const imported = discovery.importSoul(reference, { origin: sourceOrigin });
+  const mode = input.mode ?? imported.soul.declaration.work ?? "directory";
+  const adoptions = typeof requested !== "string" && imported.adoption ? [imported.adoption] : [];
+  // Adoption is keyed to qualified source identity, not whichever alias the
+  // caller typed. Conflicting aliases must not become a way to evade policy.
+  for (const [index, entry] of (workspace?.parsed.imports ?? []).entries()) {
+    if (!entry.adoption || entry.soul !== imported.identity.exportPath) continue;
+    const candidate = repositories.identify(entry.source);
+    if (!sameIdentity(candidate.identity, imported.identity.repository)) continue;
+    const pointer = `/imports/${index}`, origins = workspace.parsed.origins;
+    adoptions.push({ identity: imported.identity, pointer, origins,
+      parsed: parseSoulImport(entry, { pointer, origins, origin: origins[pointer].document }) });
+  }
+  let plan = planSoftwareChoices({ identity: imported.identity, soul: imported.soul,
+    ...(workspace ? { workspace: workspace.parsed } : {}), adoptions, ...(operator ? { operator } : {}) });
+  if (plan.status !== "resolved") return { status: plan.status, resolution: null, problems: plan.problems };
+  const requests = Object.entries(plan.capabilities).map(([capability, selected]) => ({ capability, source: selected.source, origin: plan.choices[selected.choiceKeys[0]].selectedBy }));
+  let prepared, primary;
+  try {
+    prepared = requests.length ? preparePackageArtifacts({ requests, deployment, directory, repositories, kernel,
+      observations: [imported.observation], allowLocalPaths, catalog: kernel.catalog })
+      : { artifactSet: { schemaVersion: 1, packages: {}, capabilities: {} }, roots: [], cleanup() {} };
+    const allArtifacts = prepared.artifactSet, manifests = new Map(), definitions = [];
+    for (const [id, row] of Object.entries(allArtifacts.capabilities)) {
+      const root = verifyPortableArtifact(deployment, row.artifact).dir;
+      manifests.set(id, kernel.manifest(root));
+      if (Object.hasOwn(plan.capabilities, id)) definitions.push({ artifact: row.artifact, bytes: readPortableBytes(join(root, "oats.json")) });
+    }
+    plan = captureManifestSettings(plan, definitions);
+    const artifacts = { ...allArtifacts, capabilities: Object.fromEntries(Object.entries(allArtifacts.capabilities).filter(([id]) => Object.hasOwn(plan.capabilities, id))) };
+    const roots = new Set(imported.roots);
+    for (const pkg of Object.values(allArtifacts.packages)) {
+      const selected = parseLockedSource3(pkg.source, pkg.path);
+      if (selected.kind === "git" && pkg.commit === imported.observation.source.commit && parseRepositorySource(`git:${selected.url}`).normalized === imported.observation.source.remote) roots.add(pkg.path);
+    }
+    const projectionRoots = [...roots].sort(compareUtf8), sourceDirectory = join(directory, "soul-projection");
+    repositories.materialize(imported.observation, projectionRoots, sourceDirectory);
+    const sourceArtifact = { kind: "soul", identity: imported.identity, integrity: treeIntegrity(sourceDirectory) };
+    retainPortableArtifact(deployment, sourceDirectory, sourceArtifact);
+    const soul = { identity: imported.identity, alias: imported.reference.alias, revision: imported.observation.source,
+      sourceArtifact, definition: imported.definition, projection: { roots: projectionRoots } };
+    const context = workspace ? { kind: "workspace", identity: workspace.identity,
+      observation: { ...workspace.parsed.origins[""], kind: "workspace-default" } }
+      : { kind: "standalone", key: hasStandaloneContext ? standaloneContextKey : null };
+    let seed = { schemaVersion: 1, capture: "prepared", subject: { kind: "persistent", soul }, context, artifacts,
+      choices: plan.choices, evidence: imported.provenance };
+    const declarations = [bindingDeclaration("soul", imported.soul.declaration, imported.soul.origins)];
+    if (workspace) declarations.push(bindingDeclaration("workspace", workspace.parsed.declaration, workspace.parsed.origins));
+    for (const adoption of adoptions) {
+      const value = adoption.parsed.reference.adoption;
+      if (value) declarations.push(bindingDeclaration("adoption", value, adoption.origins, `${adoption.pointer}/adoption`));
+    }
+    if (operator) declarations.push(operatorBindingDeclaration(operator));
+    const bound = prepareProviderBindings({ seed, plan, manifests, declarations }, options => kernel.binding({ ...options, deployment }));
+    plan = bound.plan; seed = bound.seed;
+    const completion = bound.problems.length ? { record: null, problems: bound.problems }
+      : kernel.complete({ seed, plan, manifests, mode, deployment, directory, launch: input.launch, helperLaunches: input.helperLaunches });
+    let resolution = null;
+    if (completion.record) resolution = commitCapturedResolution(deployment, completion.record);
+    // Publishing valid immutable inputs/records need not roll back on a later
+    // selection CAS loss. Never delete another transaction's retained objects.
+    const next = previous.lock ? structuredClone(previous.lock) : emptyLock3();
+    const { ledger } = readApprovalLedger(deployment), selections = [];
+    for (const root of new Set(prepared.roots)) {
+      const set = packageSubset(allArtifacts, root), key = artifactSetKey3(set), pkg = set.packages[root];
+      const request = { source: pkg.source, path: pkg.path }, requestKey = requestKey3(request);
+      const approval = evaluateCapturedApprovals({ record: { artifacts: set }, manifests }, ledger);
+      const usable = approval.every((entry) => entry.status !== "approval-required");
+      next.artifactSets[key] = set;
+      next.selections[requestKey] = { request, current: usable ? key : next.selections[requestKey]?.current ?? null, available: key,
+        freshness: { state: "refreshed", observedAt: new Date().toISOString(), problems: [] } };
+      selections.push({ request, artifactSet: key, approvalRequired: approval.filter((entry) => entry.status === "approval-required").map((entry) => entry.artifact.capability) });
+    }
+    writeLock3(deployment, previous.integrity, next);
+    const approvals = evaluateCapturedApprovals({ record: { artifacts }, manifests }, ledger);
+    return { status: resolution ? (approvals.some((entry) => entry.status === "approval-required") ? "approval-required" : "prepared") : completion.problems?.some(problem => problem.code === "requirement-conflict") ? "conflict" : "needs-configuration",
+      resolution, executionBinding: resolution ? { schemaVersion: 1, deployment, resolution } : null,
+      ...(resolution ? { responsibleHuman: completion.record.messagingChoice.enabled ? completion.record.messagingChoice.privateKey.human : null } : {}),
+      source: { source: imported.reference.source, soul: imported.reference.soul, revision: imported.observation.source.commit, alias: imported.reference.alias },
+      selections, problems: completion.problems ?? [] };
+  } catch (error) { primary = error; throw error; }
+  finally {
+    try { prepared?.cleanup(); }
+    catch (cleanup) {
+      if (!primary) throw cleanup;
+      const error = new AggregateError([primary, cleanup], "preparation and package cleanup failed", { cause: primary });
+      error.code = primary.code; throw error;
+    }
+  }
+}

package/lib/prepared-bindings.mjs

@@ -0,0 +1,78 @@
+/** Provider composition over one frozen source/workspace observation. Provider
+ * codecs normalize fields; only resolveChoices selects their values. */
+import { canonicalJson } from './portable-values.mjs';
+import { resolveChoices } from './portable-choices.mjs';
+import { validateOrigin } from './resolution-shape.mjs';
+import { pointerKey } from './portable-shape.mjs';
+import { bindingField, bindingOriginWitnessed } from './provider-binding-wire.mjs';
+import { oatsError } from './errors.mjs';
+
+/** Remap dictionary keys for an adoption subtree, but retain original document
+ * pointers/spans inside each witness. No file/config is read here. */
+export function bindingDeclaration(kind,value,origins,pointer='') {
+  const role={soul:'soul-requirement',workspace:'workspace-default',adoption:'import-adoption',operator:'operator'}[kind];
+  if (!role || !origins?.[pointer]) throw oatsError('invalid-declaration','binding input has no original declaration witness');
+  const mapped=Object.create(null);
+  for (const [key,origin] of Object.entries(origins)) {
+    if (key !== pointer && !key.startsWith(`${pointer}/`)) continue;
+    const witnessed={...origin,kind:role};validateOrigin(witnessed);
+    mapped[key.slice(pointer.length)]=witnessed;
+  }
+  return {kind,value,origin:mapped[''],origins:mapped};
+}
+export function operatorBindingDeclaration(operator) {
+  canonicalJson(operator);
+  const origins=Object.create(null);
+  const mark=(value,pointer)=>{
+    origins[pointer]={kind:'operator',document:operator.document,pointer};
+    if (value && typeof value === 'object') for (const [key,child] of Object.entries(value)) mark(child,`${pointer}/${pointerKey(key)}`);
+  };
+  mark(operator,'');
+  return bindingDeclaration('operator',operator,origins);
+}
+const same=(a,b)=>canonicalJson(a)===canonicalJson(b);
+const safeCodes=new Set(['approval-required','needs-configuration','requirement-conflict','invalid-binding','invalid-binding-output',
+  'authorization-required','host-requirement-missing','provider-unavailable','provider-not-qualified','resource-not-found','integrity-drift']);
+export function prepareProviderBindings({seed,plan,manifests,declarations},invoke) {
+  const normalized=new Map(),problems=[],requirements=[...plan.requirements],candidates=[...plan.candidates];
+  const settingsFor=id=>Object.fromEntries(Object.entries(plan.settings[id] ?? {}).map(([name,key])=>[name,plan.choices[key].value]));
+  const run=(id,phase,input)=>invoke({artifacts:seed.artifacts,capability:id,phase,settings:settingsFor(id),input});
+  const refuse=error=>({code:safeCodes.has(error?.code)?error.code:'provider-not-qualified',message:'provider binding could not be prepared',origins:[]});
+  for (const [id,manifest] of manifests) {
+    if (!Object.hasOwn(seed.artifacts.capabilities,id) || !manifest.layer) continue;
+    if (plan.providers[manifest.layer] !== id) problems.push({code:'needs-configuration',message:'fundamental capability must be selected in its own layer',origins:[]});
+  }
+  if (problems.length) return {plan,seed,problems};
+  for (const [slot,id] of Object.entries(plan.providers)) {
+    if (id === null) continue;
+    const manifest=manifests.get(id);
+    if (manifest?.layer !== slot || !manifest.binding) { problems.push({code:'provider-not-qualified',message:'selected provider has no matching binding interface',origins:[]});continue; }
+    try {
+      const value=run(id,'normalize',{declarations,context:seed.context});
+      normalized.set(slot,{id,value}); requirements.push(...value.requirements);candidates.push(...value.candidates);
+    } catch(error) { problems.push(refuse(error)); }
+  }
+  if (problems.length) return {plan,seed,problems};
+  const resolved=resolveChoices({requirements,candidates});
+  if (resolved.status !== 'resolved') return {plan:{...plan,...resolved},seed,problems:resolved.problems};
+  const nextPlan={...plan,...resolved,requirements,candidates},bindings=Object.create(null);
+  let messagingChoice={schemaVersion:1,enabled:false};
+  const known=[];
+  for (const choice of Object.values(resolved.choices)) {
+    if (choice.selectedBy) known.push(choice.selectedBy);
+    for (const item of [...choice.constraints,...choice.considered]) known.push(item.origin);
+  }
+  const witnessed=origin=>bindingOriginWitnessed(origin,declarations) || known.some(candidate=>same(candidate,origin));
+  for (const [slot,{id,value}] of normalized) {
+    try {
+      const choices=Object.fromEntries(Object.entries(resolved.choices).filter(([key])=>bindingField(key,slot)));
+      const bound=run(id,'bind',{model:value.model,choices,context:seed.context});
+      for (const origin of [...bound.binding.provenance,...(bound.messagingChoice?.provenance ?? [])]) {
+        if (!witnessed(origin)) throw oatsError('invalid-binding-output','binding provenance is not witnessed by this preparation');
+      }
+      bindings[slot]=bound.binding;
+      if (slot === 'messaging') messagingChoice=bound.messagingChoice;
+    } catch(error) { problems.push(refuse(error)); }
+  }
+  return {plan:nextPlan,seed:{...seed,choices:resolved.choices,bindings,messagingChoice},problems};
+}