@awebai/oats 0.25.9 → 0.26.0

package/lib/prepare-composition.mjs

@@ -1,170 +0,0 @@
-/** 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. */
-/** Origins of the choices that selected a capability — the same derivation preparation
- *  bindings use, so completion refusals render beside binding problems. */
-function originsOf(plan, capability) {
-  const seen = new Map();
-  for (const key of plan.capabilities?.[capability]?.choiceKeys ?? []) {
-    const origin = plan.choices?.[key]?.selectedBy;
-    if (origin) seen.set(canonicalJson(origin), origin);
-  }
-  return [...seen.values()];
-}
-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;
-    let completion;
-    if (bound.problems.length) completion = { record: null, problems: bound.problems };
-    else {
-      try { completion = kernel.complete({ seed, plan, manifests, mode, deployment, directory, launch: input.launch, helperLaunches: input.helperLaunches }); }
-      catch (error) {
-        // A typed completion refusal that names its capability is a preparation problem like any
-        // other (slot/capability/origins), never a bare top-level error. Anything else propagates.
-        if (!Array.isArray(error?.problems) || !["needs-configuration", "requirement-conflict"].includes(error.code)) throw error;
-        completion = { record: null, problems: error.problems.map(problem => ({ ...problem, origins: problem.origins ?? originsOf(plan, problem.capability) })) };
-      }
-    }
-    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

@@ -1,92 +0,0 @@
-/** 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';
-import { providerReasons, safeProviderReason } from './provider-reasons.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 originsFor=id=>[...new Map((plan.capabilities[id]?.choiceKeys ?? []).flatMap(key=>{
-    const choice=plan.choices[key];return choice?.selectedBy?[choice.selectedBy]:[];
-  }).map(origin=>[canonicalJson(origin),origin])).values()];
-  const problem=(slot,id,code,message,origins=originsFor(id))=>({code,message,origins,slot,capability:id});
-  const refuse=(slot,id,phase,error)=>problem(slot,id,safeCodes.has(error?.code)?error.code:'provider-not-qualified',
-    safeProviderReason(error?.message,providerReasons(manifests.get(id))) ?? `${id} ${slot} ${phase} binding could not be prepared`); // Recheck fixed text; never arbitrary exceptions.
-  for (const [id,manifest] of manifests) {
-    if (!Object.hasOwn(seed.artifacts.capabilities,id) || !manifest.layer) continue;
-    if (plan.providers[manifest.layer] !== id) problems.push(problem(manifest.layer,id,'needs-configuration','fundamental capability must be selected in its own layer'));
-  }
-  for (const [slot,id] of Object.entries(plan.providers)) {
-    if (id === null) continue;
-    const manifest=manifests.get(id);
-    if (manifest?.layer !== slot) { problems.push(problem(slot,id,'provider-not-qualified',`${id} does not declare the selected ${slot} layer`));continue; }
-    if (!manifest.binding) { problems.push(problem(slot,id,'provider-not-qualified',`${id}@${manifest.version} declares no binding interface; ${slot} cannot be prepared`));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(slot,id,'normalize',error)); }
-  }
-  // One unsupported slot must not mask another slot's normalized requirements
-  // or invalid choices. The same resolver still decides every value.
-  const resolved=resolveChoices({requirements,candidates});
-  for (const item of resolved.problems) {
-    const slot=Object.keys(plan.providers).find(slot=>bindingField(item.key,slot));
-    if (!slot) throw oatsError('invalid-binding-output','provider choice problem has no owned binding slot');
-    problems.push({...item,slot,capability:plan.providers[slot]});
-  }
-  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) {
-    if (resolved.problems.some(item=>bindingField(item.key,slot))) continue;
-    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(slot,id,'bind',error)); }
-  }
-  nextPlan.problems=problems;
-  nextPlan.status=problems.some(item=>item.code==='requirement-conflict')?'conflict':problems.length?'needs-configuration':'resolved';
-  return {plan:nextPlan,seed:{...seed,choices:resolved.choices,bindings,messagingChoice},problems};
-}

package/lib/prepared-resources.mjs

@@ -1,127 +0,0 @@
-/** Build retained command/curriculum records from already selected software.
- * Kernel callbacks own existing skill discovery and manifest command semantics. */
-import { existsSync, mkdirSync, readFileSync } from "node:fs";
-import { dirname, join, relative, sep } from "node:path";
-import { copyTreeSafe } from "./artifact-tree.mjs";
-import { treeIntegrity, jsonIntegrity } from "./portable-digest.mjs";
-import { retainPortableArtifact, verifyPortableArtifact } from "./portable-artifacts.mjs";
-import { commitCapturedResolution, verifyResolutionInputs } from "./captured-resolutions.mjs";
-import { readPortableBytes } from "./portable-files.mjs";
-import { captureHelperInjectionChoices } from "./helper-injection-policy.mjs";
-import { parseConfigData } from "./config-data.mjs";
-import { oatsError } from "./errors.mjs";
-import { normalizePackagePath } from "./capability-provenance.mjs";
-import { compileCapturedLaunchRequest } from "./captured-launch-request.mjs";
-
-export function completePreparedResources({ seed, plan, manifests, mode, deployment, directory, launch, helperLaunches = {} }, kernel) {
-  const problems = [];
-  for (const [id, manifest] of manifests) {
-    if (!Object.hasOwn(seed.artifacts.capabilities, id)) continue;
-    if (manifest.layer && seed.bindings?.[manifest.layer]?.capability !== id) problems.push({ code: "provider-not-qualified", message: `provider ${id} needs its binding adapter before complete preparation`, origins: [] });
-    const settings = Object.fromEntries(Object.entries(plan.settings[id] ?? {}).map(([name, key]) => [name, plan.choices[key].value]));
-    kernel.settings(manifest, settings);
-  }
-  if (problems.length) return { record: null, problems };
-  const snapshot = join(directory, "kernel-resources"); mkdirSync(snapshot); mkdirSync(join(snapshot, "injects"));
-  const kernelSkills = ["oats-portable", "oats-portable-artifacts"];
-  const workInjection = (workMode) => workMode === "directory" ? "portable-work-directory.md" : `work-${workMode}.md`;
-  const injectionFiles = ["oats-portable.md", "portable-instance-boundary.md", ...kernel.workModes.map(workInjection)];
-  // Only known kernel resources, never a sweep of the checkout/node_modules,
-  // author directories, deployment config or credentials.
-  for (const name of kernelSkills) copyTreeSafe(join(kernel.root, "skills", name), join(snapshot, "skills", name));
-  for (const file of injectionFiles) copyTreeSafe(join(kernel.root, "injects", file), join(snapshot, "injects", file));
-  const bundle = { kind: "resource", integrity: treeIntegrity(snapshot) };
-  retainPortableArtifact(deployment, snapshot, bundle);
-  const portable = (root, path) => relative(root, path).split(sep).join("/") || ".";
-  const effectiveSettings = Object.fromEntries(Object.entries(plan.settings).map(([id, values]) => [id,
-    Object.fromEntries(Object.entries(values).map(([name, key]) => [name, plan.choices[key].value]))]));
-  const definitions = Object.values(seed.artifacts.capabilities).map(row => ({ artifact: row.artifact,
-    bytes: readPortableBytes(join(verifyPortableArtifact(deployment, row.artifact).dir, "oats.json")) }));
-  const build = (subject, workMode, helpers, launchRequest) => {
-    const helperPolicy = subject.kind === "helper" ? captureHelperInjectionChoices(plan, definitions) : null;
-    const resources = Object.create(null), blocks = [], skills = [], names = new Set(), omissions = [];
-    const owner = subject.kind === "persistent" ? subject.soul.sourceArtifact : subject.provider;
-    const sourceRoot = verifyPortableArtifact(deployment, owner).dir;
-    const definition = subject.kind === "persistent" ? subject.soul.definition : subject.definition.path;
-    const soulRoot = join(sourceRoot, dirname(definition));
-    resources.body = { owner, path: portable(sourceRoot, join(soulRoot, "AGENTS.md")), kind: "file" };
-    const inject = (source, owner, path) => {
-      const key = `instruction:${source}`; resources[key] = { owner, path, kind: "file" }; blocks.push({ source, resource: key });
-    };
-    inject("kernel:oats-portable", bundle, "injects/oats-portable.md");
-    inject("kernel:instance-boundary", bundle, "injects/portable-instance-boundary.md");
-    inject(`work-mode:${workMode}`, bundle, `injects/${workInjection(workMode)}`);
-    const skillTree = (owner, root, tree, label, required = true) => {
-      const entries = kernel.skills(tree);
-      if (required && !entries.length) throw oatsError("resource-not-found", "a declared skill tree contains no readable skill");
-      for (const entry of entries) {
-        if (names.has(entry.name)) throw oatsError("needs-configuration", `skill ${entry.name} has multiple sources; an explicit override is required`);
-        names.add(entry.name);
-        const key = `skill:${label}:${entry.name}`; resources[key] = { owner, path: portable(root, entry.src), kind: "skill" };
-        skills.push({ name: entry.name, resource: key });
-      }
-    };
-    const kernelRoot = verifyPortableArtifact(deployment, bundle).dir;
-    for (const name of kernelSkills) skillTree(bundle, kernelRoot, join(kernelRoot, "skills", name), "kernel");
-    if (existsSync(join(soulRoot, "skills"))) skillTree(owner, sourceRoot, join(soulRoot, "skills"), "soul", false);
-    const providerManifests = Object.create(null);
-    for (const [id, row] of Object.entries(seed.artifacts.capabilities)) {
-      const manifest = manifests.get(id), root = verifyPortableArtifact(deployment, row.artifact).dir;
-      const key = `manifest:${id}`; resources[key] = { owner: row.artifact, path: "oats.json", kind: "manifest" }; providerManifests[id] = key;
-      for (const path of manifest.skills ?? []) skillTree(row.artifact, root, join(root, path), id);
-      if (helperPolicy) {
-        const policy = helperPolicy.policies.get(id);
-        if (policy.fact) {
-          if (policy.resource) {
-            resources[policy.resourceKey] = policy.resource;
-            blocks.push({ source: policy.source, resource: policy.resourceKey, choice: policy.fact.key });
-          } else omissions.push({ source: policy.source, reason: "helper-policy", choice: policy.fact.key });
-        }
-      } else if (manifest.inject) inject(`capability:${id}`, row.artifact, portable(root, join(root, manifest.inject)));
-      for (const [kind, declarations] of [["command", manifest.commands ?? {}], ["hook", kernel.hooks(manifest)]]) {
-        for (const [name, value] of Object.entries(declarations)) {
-          if (typeof value !== "string" || !value.trim() || value.includes("\0")) throw oatsError("invalid-resolution", "declared executable is not valid text");
-          resources[`executable:${id}:${kind}:${name}`] = { owner: row.artifact, path: portable(root, join(root, value.trim().split(/\s+/)[0])), kind: "file" };
-        }
-      }
-    }
-    const capturedLaunch = compileCapturedLaunchRequest(launchRequest, { artifacts: seed.artifacts, manifests, settings: effectiveSettings, resources }, kernel);
-    return { ...seed, subject, choices: helperPolicy?.choices ?? seed.choices, bindings: seed.bindings ?? {}, messagingChoice: seed.messagingChoice ?? { schemaVersion: 1, enabled: false }, resources, resourceBundles: [bundle], helpers,
-      dispatch: { schemaVersion: 1, providerManifests, settingsChoices: plan.settings, launch: capturedLaunch, runtimePackages: [], hostRequirements: [], workTargetInputs: {},
-        composition: { schemaVersion: 1, mode: workMode, body: "body", blocks, skills, omissions } } };
-  };
-  // Preflight EVERY helper before publishing any helper record. Until helpers
-  // run their own complete provider/software preparation, inheriting a parent's
-  // binding over helper-authored policy would create a usable contradiction.
-  const helperPlans = [], helperKeys = new Set();
-  for (const [id, row] of Object.entries(seed.artifacts.capabilities)) {
-    const root = verifyPortableArtifact(deployment, row.artifact).dir;
-    for (const path of manifests.get(id).agents ?? []) {
-      const normalized = normalizePackagePath(path);
-      if (normalized === undefined) throw oatsError("invalid-declaration", "invalid helper export path");
-      const definitionPath = `${normalized === "." ? "" : `${normalized}/`}soul.yaml`;
-      const definition = parseConfigData(readFileSync(join(root, definitionPath))).value;
-      const authoredPolicy = ["requires", "defaults"].filter((field) => definition[field] && Object.keys(definition[field]).length);
-      for (const field of ["knowledge", "teams", "resources"]) if (Object.hasOwn(definition, field)) authoredPolicy.push(field);
-      if (authoredPolicy.length) return { record: null, problems: [{ code: "needs-configuration",
-        message: `helper has authored ${authoredPolicy.join(", ")} policy requiring dedicated preparation; parent bindings were not inherited`, origins: [] }] };
-      const helperMode = definition.work ?? "directory";
-      if (!kernel.workModes.includes(helperMode)) throw oatsError("invalid-declaration", "helper work mode is invalid");
-      const subject = { kind: "helper", provider: row.artifact, name: definition.name, definition: { owner: row.artifact, path: definitionPath, kind: "file" } };
-      const key = `${id}:${definition.name}`;
-      if (helperKeys.has(key)) throw oatsError("invalid-declaration", "duplicate helper export name");
-      helperKeys.add(key); helperPlans.push({ key, subject, helperMode });
-    }
-  }
-  for (const key of Object.keys(helperLaunches)) if (!helperKeys.has(key)) throw oatsError("helper-not-selected", "helper launch request must name an exact selected helper-map key");
-  // Compile EVERY launch request before publishing any helper record. No partial
-  // usable helper graph when a later helper's runtime inputs are unsupported.
-  const records = helperPlans.map(({ key, subject, helperMode }) => ({ key, record: build(subject, helperMode, {}, helperLaunches[key]) }));
-  const record = build(seed.subject, mode, {}, launch), helpers = Object.create(null);
-  // Verify every prospective file/owner/witness before publishing ANY member
-  // of this graph, including a primary file omitted only for helpers.
-  for (const candidate of [...records.map(item => item.record), record]) verifyResolutionInputs(deployment,
-    { schemaVersion: 1, id: jsonIntegrity(candidate).value }, { draft: candidate });
-  for (const item of records) helpers[item.key] = commitCapturedResolution(deployment, item.record);
-  return { record: { ...record, helpers }, problems: [] };
-}

package/lib/provider-binding-broker.mjs

@@ -1,65 +0,0 @@
-/** Execute only an approved retained provider command. Preparation does not need
- * a fabricated complete resolution merely to obtain its binding. */
-import { spawnSync } from 'node:child_process';
-import { realpathSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { canonicalJson } from './portable-values.mjs';
-import { objectAt } from './portable-shape.mjs';
-import { validateArtifactSet } from './resolution-shape.mjs';
-import { verifyPortableArtifact } from './portable-artifacts.mjs';
-import { verifyRetainedCapability, verifyResolutionInputs } from './captured-resolutions.mjs';
-import { buildCapturedInvocationContext } from './captured-invocation-context.mjs';
-import { readApprovalLedger, evaluateCapturedApprovals } from './artifact-approvals.mjs';
-import { validateBindingInterface } from './provider-binding.mjs';
-import { BINDING_LIMITS, validateBindingRequest, decodeBindingResponse } from './provider-binding-wire.mjs';
-import { oatsError } from './errors.mjs';
-import { providerReasons } from './provider-reasons.mjs';
-
-// Same kernel-owned CLI locator as lifecycle hooks; never caller env or PATH.
-const CLI_BIN=fileURLToPath(new URL('../bin/oats.mjs',import.meta.url));
-
-export function invokeProviderBinding(options,codecs) {
-  canonicalJson(options);
-  objectAt(options,['deployment','artifacts','capability','phase','settings','input','timeoutMs'],['deployment','artifacts','capability','phase','settings','input']);
-  const {deployment,artifacts,capability,phase,settings,input,timeoutMs=30000}=options;
-  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000) throw oatsError('invalid-declaration','binding timeout must be between 1 and 30000 milliseconds');
-  validateArtifactSet(artifacts);
-  if (!Object.hasOwn(artifacts.capabilities,capability)) throw oatsError('capability-not-selected','binding provider is not selected');
-  const row=artifacts.capabilities[capability],root=verifyPortableArtifact(deployment,row.artifact).dir;
-  const manifest=verifyRetainedCapability(root,artifacts,capability,codecs.manifest(root));
-  const binding=validateBindingInterface(manifest);
-  if (!binding) throw oatsError('provider-not-qualified','provider has no binding interface');
-  const request=validateBindingRequest({schemaVersion:1,phase,slot:manifest.layer,capability,settings,input});
-  if (phase === 'check' && input.invocation !== undefined) {
-    // Public check callers cannot turn a merely shape-valid projection into
-    // authority. Re-derive it from the referenced retained record/current target.
-    const verified=verifyResolutionInputs(deployment,input.invocation.executionBinding.resolution),record=verified.record;
-    if (record.capture !== 'prepared') throw oatsError('migration-required','captured check cannot use unverified reconstructed authority');
-    const actual=buildCapturedInvocationContext({loaded:{...verified,deployment,resolution:input.invocation.executionBinding.resolution,capability:{id:capability}},
-      action:input.action,instance:input.invocation.instance === null ? null : Object.fromEntries(['home','work','name','agent'].map(key=>[key,input.invocation.instance[key]])),
-      intent:input.invocation.intent,priorReceipt:input.invocation.priorReceipt});
-    const effective=Object.fromEntries(Object.entries(record.dispatch.settingsChoices[capability] ?? {}).map(([name,key])=>[name,record.choices[key].value]));
-    if (canonicalJson(actual)!==canonicalJson(input.invocation) || canonicalJson(record.artifacts)!==canonicalJson(artifacts)
-      || !record.bindings[manifest.layer] || canonicalJson(record.bindings[manifest.layer])!==canonicalJson(input.binding)
-      || canonicalJson(effective)!==canonicalJson(settings)) throw oatsError('invalid-resolution','provider check invocation differs from retained authority');
-  }
-  codecs.settings(manifest,settings);
-  const selected={record:{artifacts:{...artifacts,capabilities:{[capability]:row}}},manifests:new Map([[capability,manifest]])};
-  const approval=evaluateCapturedApprovals(selected,readApprovalLedger(deployment).ledger)[0];
-  if (approval.status !== 'approved') throw oatsError('approval-required','provider codec requires current exact-artifact approval');
-  if (codecs.host({manifest}).length) throw oatsError('host-requirement-missing','provider codec has unmet host requirements');
-  const spec=manifest.commands[binding[phase]];
-  const [script,...args]=spec.trim().split(/\s+/),file=codecs.executable(manifest,script);
-  if (!file) throw oatsError('resource-not-found','provider codec executable is unavailable');
-  const environment=Object.fromEntries(Object.entries(process.env).filter(([key])=>! /^(OATS_|OAS_|PI_)/.test(key)));
-  Object.assign(environment,{OATS_CAPABILITY:capability,OATS_CAPABILITY_ROOT:root,OATS_SETTINGS:canonicalJson(settings,BINDING_LIMITS),OATS_CLI_BIN:realpathSync(CLI_BIN)});
-  let result;
-  try {
-    result=spawnSync(process.execPath,[file,...args],{cwd:root,env:environment,input:canonicalJson(request,BINDING_LIMITS),
-      timeout:timeoutMs,killSignal:'SIGKILL',maxBuffer:BINDING_LIMITS.maxBytes,stdio:['pipe','pipe','pipe'],shell:false});
-  } catch { throw oatsError('provider-unavailable','provider codec could not execute'); }
-  if (result.error || result.signal || result.status !== 0) throw oatsError('provider-unavailable','provider codec did not complete successfully');
-  const response=decodeBindingResponse(result.stdout,request,{reasons:providerReasons(manifest)});
-  if (!response.ok) throw oatsError(response.error.code,response.error.message ?? 'provider binding phase refused');
-  return response.result;
-}

package/lib/provider-binding-wire.mjs

@@ -1,116 +0,0 @@
-/** Bounded provider wire data. No provider model, precedence or native execution. */
-import { canonicalJson, parseStrictJson } from './portable-values.mjs';
-import { objectAt, stringAt, versionAt } from './portable-shape.mjs';
-import { validateOrigin, validateProviderBinding, validateMessagingChoice, validateCapturedChoices, validateCapturedContext } from './resolution-shape.mjs';
-import { validateCapturedInvocationContext } from './captured-invocation-context.mjs';
-import { FUNDAMENTAL_SLOTS } from './portable-policy.mjs';
-import { isMaterializedCapabilityId } from './capability-provenance.mjs';
-import { BINDING_PHASES } from './provider-binding.mjs';
-import { resolveChoices } from './portable-choices.mjs';
-import { oatsError } from './errors.mjs';
-import { providerReasons, safeProviderReason, validateBindingReasons } from './provider-reasons.mjs';
-
-export const BINDING_LIMITS = Object.freeze({maxBytes:1024*1024,maxDepth:32,maxEntries:16384});
-export const BINDING_PROBLEMS = Object.freeze(['needs-configuration','requirement-conflict','invalid-binding','authorization-required','host-requirement-missing','provider-unavailable','provider-not-qualified']);
-const fail = () => { throw oatsError('invalid-binding-output','provider returned invalid binding data'); };
-const same = (a,b) => canonicalJson(a) === canonicalJson(b);
-const roleKinds = {soul:['soul-requirement','soul-default'],workspace:['workspace-default'],adoption:['import-adoption'],operator:['operator']};
-const pointer = key => typeof key === 'string' && /^(?:\/(?:[^~]|~[01])*)+$/.test(key);
-export const bindingField = (key,slot) => pointer(key) && key.startsWith(`/bindings/${slot}/`) && key.length > `/bindings/${slot}/`.length;
-function problem(value,reasons) {
-  objectAt(value,['code','message'],['code']);
-  if (!BINDING_PROBLEMS.includes(value.code)) fail();
-  if (value.message !== undefined) stringAt(value.message,'/message',{empty:true});
-  const message=safeProviderReason(value.message,reasons);
-  return {code:value.code,...(message === undefined ? {} : {message})}; // Only declared fixed text crosses.
-}
-export function validateBindingRequest(request) {
-  canonicalJson(request,BINDING_LIMITS);
-  objectAt(request,['schemaVersion','phase','slot','capability','settings','input'],['schemaVersion','phase','slot','capability','settings','input']);
-  versionAt(request.schemaVersion);
-  if (!BINDING_PHASES.includes(request.phase) || !FUNDAMENTAL_SLOTS.includes(request.slot) || !isMaterializedCapabilityId(request.capability)) fail();
-  objectAt(request.settings,null,[]); const input=request.input;
-  if (request.phase === 'normalize') {
-    objectAt(input,['declarations','context'],['declarations','context']);
-    if (!Array.isArray(input.declarations)) fail();
-    for (const declaration of input.declarations) {
-      objectAt(declaration,['kind','value','origin','origins'],['kind','value','origin','origins']);
-      if (!Object.hasOwn(roleKinds,declaration.kind)) fail();
-      validateOrigin(declaration.origin); objectAt(declaration.origins,null,[]);
-      if (!roleKinds[declaration.kind].includes(declaration.origin.kind)) fail();
-      for (const [key,origin] of Object.entries(declaration.origins)) {
-        if (key !== '' && !pointer(key)) fail();
-        validateOrigin(origin);
-        if (!roleKinds[declaration.kind].includes(origin.kind) || !same(origin.document,declaration.origin.document)) fail();
-      }
-    }
-  } else if (request.phase === 'bind') {
-    objectAt(input,['model','choices','context'],['model','choices','context']);
-    validateCapturedChoices(input.choices);
-    for (const key of Object.keys(input.choices)) if (!bindingField(key,request.slot)) fail();
-  } else {
-    objectAt(input,['binding','context','action','invocation'],['binding','context','action']);
-    validateProviderBinding(input.binding); objectAt(input.action,null,['kind']);
-    if (input.binding.capability !== request.capability) fail();
-    if (Object.hasOwn(input,'invocation')) {
-      const invocation=validateCapturedInvocationContext(input.invocation);
-      if (invocation.capability !== request.capability || !same(invocation.context,input.context) || !same(invocation.action,input.action)) fail();
-      if (request.slot === 'messaging' && (!invocation.messagingChoice.enabled || invocation.messagingChoice.privateKey.provider !== request.capability)) fail();
-    }
-  }
-  validateCapturedContext(input.context);
-  return request;
-}
-function witnessed(origin,declarations) {
-  validateOrigin(origin);
-  return declarations.some(declaration => roleKinds[declaration.kind].includes(origin.kind)
-    && [declaration.origin,...Object.values(declaration.origins)].some(candidate => {
-      const {kind:_,...a}=origin, {kind:__,...b}=candidate;
-      return same(a,b);
-    }));
-}
-export function decodeBindingResponse(bytes,request,{reasons}={}) {
-  let response;
-  try {
-    validateBindingRequest(request);
-    // Out-of-band trusted caller input, NEVER a field supplied in the response.
-    // Unknown providers legitimately have no compatibility reasons; an explicit
-    // manifest declaration was already validated with the stricter nonempty bound.
-    reasons=validateBindingReasons(reasons === undefined ? providerReasons({capability:request.capability}) : reasons,{allowEmpty:true});
-    response=parseStrictJson(bytes,BINDING_LIMITS);
-    objectAt(response,response?.ok === true ? ['schemaVersion','phase','slot','capability','ok','result'] : ['schemaVersion','phase','slot','capability','ok','error'],
-      response?.ok === true ? ['schemaVersion','phase','slot','capability','ok','result'] : ['schemaVersion','phase','slot','capability','ok','error']);
-    for (const key of ['schemaVersion','phase','slot','capability']) if (response[key] !== request[key]) fail();
-    if (response.ok === false) return {ok:false,error:problem(response.error,reasons)};
-    if (response.ok !== true) fail();
-    const result=response.result;
-    if (request.phase === 'normalize') {
-      objectAt(result,['requirements','candidates','model'],['requirements','candidates','model']);
-      if (!Array.isArray(result.requirements) || !Array.isArray(result.candidates)) fail();
-      for (const entry of [...result.requirements,...result.candidates]) {
-        if (!bindingField(entry.key,request.slot) || !witnessed(entry.origin,request.input.declarations)) fail();
-      }
-      for (const requirement of result.requirements) if (requirement.origin.kind !== 'soul-requirement') fail();
-      for (const candidate of result.candidates) if (candidate.kind !== candidate.origin.kind) fail();
-      // Reuse the sole entry codec/solver; conflicts are data for the combined plan.
-      resolveChoices(result);
-      return {ok:true,result};
-    }
-    if (request.phase === 'bind') {
-      const keys=['payloadContract','payloadVersion','payload','credentialRefs','provenance'];
-      objectAt(result,request.slot === 'messaging' ? [...keys,'messagingChoice'] : keys,request.slot === 'messaging' ? [...keys,'messagingChoice'] : keys);
-      const {messagingChoice,...fields}=result;
-      const binding=validateProviderBinding({schemaVersion:1,capability:request.capability,...fields});
-      // Source read/ownership provenance may live in the opaque normalized model;
-      // preparation validates that additional provenance against its original input.
-      if (request.slot === 'messaging') validateMessagingChoice(messagingChoice,{bindings:{messaging:binding},context:request.input.context});
-      return {ok:true,result:{binding,...(request.slot === 'messaging' ? {messagingChoice} : {})}};
-    }
-    objectAt(result,['status','problems'],['status','problems']);
-    if (!['ready','needs-configuration','authorization-required','unavailable'].includes(result.status) || !Array.isArray(result.problems)) fail();
-    const problems=result.problems.map(value=>problem(value,reasons));
-    if (result.status === 'ready' && problems.length) fail();
-    return {ok:true,result:{status:result.status,problems}};
-  } catch { fail(); }
-}
-export function bindingOriginWitnessed(origin,declarations) { return witnessed(origin,declarations); }