@awebai/oats 0.23.2 → 0.24.1

package/lib/errors.mjs

@@ -0,0 +1,7 @@
+/** Kernel error with a stable machine-readable code (contract §4) and optional provenance. */
+export function oatsError(code, message, provenance) {
+  const e = new Error(message);
+  e.code = code;
+  if (provenance) e.provenance = provenance;
+  return e;
+}

package/lib/helper-injection-policy.mjs

@@ -0,0 +1,98 @@
+/** Exact capability-local helper instruction facts. This is a caller of the
+ * existing resolver, never a second authority/order or provider-policy engine. */
+import { canonicalJson, parseStrictJson } from './portable-values.mjs';
+import { bytesIntegrity } from './portable-digest.mjs';
+import { pointerKey } from './portable-shape.mjs';
+import { normalizePackagePath } from './capability-provenance.mjs';
+import { resolveChoices } from './portable-choices.mjs';
+import { validateCapabilityInputDeclarations } from './capability-inputs.mjs';
+import { oatsError } from './errors.mjs';
+
+const same = (a, b) => canonicalJson(a) === canonicalJson(b);
+const prefix = '/helpers/injections/';
+export const helperInjectionChoiceKey = id => `${prefix}${pointerKey(id)}`;
+
+/** artifact/bytes are exact selected manifest inputs, not annotated objects. */
+export function helperInjectionFact({ artifact, bytes }) {
+  const manifest = validateCapabilityInputDeclarations(parseStrictJson(bytes));
+  if (artifact.kind !== 'capability' || manifest.capability !== artifact.capability) throw oatsError('invalid-resolution', 'helper policy manifest owner differs from selected artifact');
+  if (!Object.hasOwn(manifest, 'helperInjection')) return { manifest, fact: null, resource: null };
+  const policy = manifest.helperInjection, source = `capability:${artifact.capability}`, key = helperInjectionChoiceKey(artifact.capability);
+  let path = null;
+  if (policy.mode === 'inherit') {
+    path = normalizePackagePath(manifest.inject);
+    if (typeof manifest.inject !== 'string' || path === undefined || path === '.') throw oatsError('needs-configuration', 'helper inherit needs its own declared injection file');
+  } else if (policy.mode === 'file') path = policy.path;
+  const resourceKey = `instruction:${source}`;
+  const origin = { kind: 'source-export', document: { kind: 'artifact', owner: artifact, path: 'oats.json', integrity: bytesIntegrity(bytes) }, pointer: '/helperInjection' };
+  return { manifest, source, resourceKey, resource: path === null ? null : { owner: artifact, path, kind: 'file' },
+    fact: { key, kind: 'equals', value: path === null ? null : resourceKey, origin } };
+}
+
+export function captureHelperInjectionChoices(plan, definitions) {
+  const policies = new Map(), requirements = [...plan.requirements];
+  for (const definition of definitions) {
+    const policy = helperInjectionFact(definition), id = definition.artifact.capability;
+    if (policies.has(id)) throw oatsError('invalid-resolution', 'duplicate helper policy owner');
+    policies.set(id, policy);
+    if (!policy.fact && policy.manifest.inject) throw oatsError('needs-configuration', 'new helper injection requires an explicit capability policy');
+    if (policy.fact) requirements.push(policy.fact);
+  }
+  const resolved = resolveChoices({ requirements, candidates: plan.candidates });
+  if (resolved.status !== 'resolved') throw oatsError(resolved.status === 'conflict' ? 'requirement-conflict' : 'needs-configuration', 'helper policy conflicts with captured instruction choices', resolved.problems);
+  return { choices: resolved.choices, policies };
+}
+
+/** Verify BOTH directions. Read-only verification permits literal legacy
+ * evidence; publication must explicitly disallow new legacy/missing-policy mint.
+ * Existing resource verification still proves physical containment/kind. */
+export function verifyHelperInjectionPolicies(record, definitions, { publishing = false } = {}) {
+  const helper = record.subject.kind === 'helper', composition = record.dispatch.composition;
+  const expected = new Map(), selected = new Set();
+  for (const definition of definitions) {
+    const policy = helperInjectionFact(definition), id = definition.artifact.capability;
+    if (selected.has(id) || !record.artifacts.capabilities[id] || !same(record.artifacts.capabilities[id].artifact, definition.artifact)) throw oatsError('invalid-resolution', 'helper policy inputs differ from selected artifacts');
+    selected.add(id);
+    if (!helper) continue;
+    if (publishing && !policy.fact && policy.manifest.inject) throw oatsError('needs-configuration', 'new helper record lacks an explicit injection policy');
+    if (!policy.fact) continue;
+    const { fact, source, resource, resourceKey } = policy, choice = record.choices[fact.key];
+    expected.set(fact.key, fact);
+    if (!choice || !same(choice.value, fact.value) || !choice.constraints.some(entry => entry.kind === fact.kind && same(entry.value, fact.value) && same(entry.origin, fact.origin))) throw oatsError('resolution-incomplete', 'helper injection lacks its exact retained manifest witness');
+    const block = composition?.blocks.find(entry => entry.source === source), omission = composition?.omissions.find(entry => entry.source === source);
+    if (resource) {
+      if (omission || !block || block.choice !== fact.key || block.resource !== resourceKey || !record.resources[resourceKey] || !same(record.resources[resourceKey], resource)) throw oatsError('invalid-resolution', 'helper instruction block differs from declared owner/file');
+    } else if (block || !omission || omission.reason !== 'helper-policy' || omission.choice !== fact.key) throw oatsError('invalid-resolution', 'helper omission differs from explicit capability policy');
+  }
+  if (selected.size !== Object.keys(record.artifacts.capabilities).length) throw oatsError('resolution-incomplete', 'helper policy manifest inputs are incomplete');
+  const isPolicyOrigin = origin => origin?.kind === 'source-export' && (origin.pointer === '/helperInjection' || origin.pointer?.startsWith('/helperInjection/'));
+  for (const [key, choice] of Object.entries(record.choices)) {
+    if (key.startsWith(prefix) && !expected.has(key)) throw oatsError('invalid-resolution', 'helper policy choice lacks an applicable declaration');
+    for (const entry of [...choice.constraints, ...choice.considered]) if (isPolicyOrigin(entry.origin)) {
+      const fact = expected.get(key);
+      if (!fact || entry.kind !== 'equals' || !same(entry.value, fact.value) || !same(entry.origin, fact.origin)) throw oatsError('invalid-resolution', 'helper manifest witness cannot justify another choice or owner');
+    }
+    if (isPolicyOrigin(choice.selectedBy) && (!expected.has(key) || !same(choice.selectedBy, expected.get(key).origin))) throw oatsError('invalid-resolution', 'helper selected origin differs from its declaration');
+  }
+  const ownSource = fact => `capability:${fact.origin.document.owner.capability}`;
+  for (const block of composition?.blocks ?? []) if (block.choice?.startsWith(prefix)) {
+    const fact = expected.get(block.choice);
+    if (!fact || fact.value === null || block.source !== ownSource(fact) || block.resource !== fact.value) throw oatsError('invalid-resolution', 'helper instruction witness cannot control another contribution');
+  }
+  for (const omission of composition?.omissions ?? []) {
+    if (publishing && omission.reason === 'helper-knowledge') throw oatsError('needs-configuration', 'new publication cannot mint legacy slot-based helper omissions');
+    if (omission.reason === 'helper-policy') {
+      const fact = expected.get(omission.choice);
+      if (!helper || !fact || fact.value !== null || omission.source !== ownSource(fact)) throw oatsError('invalid-resolution', 'helper omission lacks its declared own policy');
+    }
+  }
+  // A missing/non-policy choice is not a way around capability ownership.
+  // Above we prove each declared contribution's exact file/omission; here every
+  // new capability contribution must point back to that owner's proved fact.
+  // Literal historical read/reuse and primary composition stay unchanged.
+  if (helper && publishing) for (const entry of [...(composition?.blocks ?? []), ...(composition?.omissions ?? [])]) {
+    if (!entry.source.startsWith('capability:')) continue;
+    const fact = expected.get(helperInjectionChoiceKey(entry.source.slice('capability:'.length)));
+    if (!fact || entry.choice !== fact.key) throw oatsError('invalid-resolution', 'new helper capability contribution lacks its declared own policy');
+  }
+}

package/lib/herdr.mjs

@@ -1,10 +1,18 @@
-/** Herdr 0.8.x host-local session backend. SSH belongs to the CLI router. */
+/** Herdr 0.8.x/0.9.x host-local backend (explicit protocols 20/22).
+ * SSH belongs to the CLI router; protocol selection is never negotiation. */
 import { execFileSync, spawn } from "node:child_process";
 import { existsSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 
+// Keep the existing legacy/default protocol literal; captured callers select one.
 export const HERDR_PROTOCOL = 20;
+export const HERDR_SUPPORTED_PROTOCOLS = Object.freeze([20, 22]);
+export const isSupportedHerdrProtocol = (value) => HERDR_SUPPORTED_PROTOCOLS.includes(value);
+function selectedHerdrProtocol(target) {
+  if (!isSupportedHerdrProtocol(target?.protocol)) throw new Error("Herdr endpoint requires explicit supported protocol 20 or 22");
+  return target.protocol;
+}
 const quote = (s) => `'${String(s).replaceAll("'", "'\\''")}'`;
 const pause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 
@@ -27,10 +35,10 @@ export function herdrCommand(target, args, { timeout = 10000, exec = execFileSyn
 }
 
 export function herdrSnapshot(target, io) {
+  const protocol = selectedHerdrProtocol(target);
   const snapshot = herdrCommand(target, ["api", "snapshot"], io).snapshot;
-  if (snapshot?.protocol !== HERDR_PROTOCOL || !Array.isArray(snapshot.panes)) {
-    throw new Error(`unsupported Herdr protocol ${snapshot?.protocol}; OATS requires ${HERDR_PROTOCOL}`);
-  }
+  if (snapshot?.protocol !== protocol) throw new Error(`Herdr snapshot does not match selected protocol ${protocol}`);
+  if (!Array.isArray(snapshot.panes)) throw new Error("Herdr snapshot has no pane inventory");
   return snapshot;
 }
 
@@ -57,15 +65,18 @@ export function ensureHerdr({ binary = "herdr", socket, session = "oats" } = {})
 }
 
 export function allocateHerdr(target, { home, instance }, io) {
+  const protocol = selectedHerdrProtocol(target);
   const result = herdrCommand(target, ["workspace", "create", "--cwd", home, "--label", instance, "--no-focus"], io);
   const pane = result.root_pane;
   if (!pane?.pane_id || !pane?.terminal_id || !pane?.workspace_id) throw new Error("Herdr allocation returned no session identity");
-  return { ...target, workspaceId: pane.workspace_id, paneId: pane.pane_id, terminalId: pane.terminal_id };
+  return { ...target, protocol, workspaceId: pane.workspace_id, paneId: pane.pane_id, terminalId: pane.terminal_id };
 }
 
 export function inspectHerdr(target, io) {
   const snapshot = herdrSnapshot(target, io);
-  const pane = snapshot.panes.find((p) => p.pane_id === target.paneId && p.terminal_id === target.terminalId);
+  const matches = snapshot.panes.filter((p) => p.pane_id === target.paneId && p.terminal_id === target.terminalId);
+  if (io?.strictHerdrTarget && (matches.length > 1 || (matches.length === 1 && matches[0].workspace_id !== target.workspaceId))) throw new Error("Herdr target workspace/pane/terminal identity is ambiguous or changed");
+  const pane = matches[0];
   const agent = pane && snapshot.agents?.find((a) => a.terminal_id === target.terminalId);
   return { present: !!pane, pane, agent, status: agent?.agent_status || "unknown" };
 }
@@ -89,7 +100,7 @@ export function inputHerdr(target, text, io) {
 }
 
 export function validHerdrTarget(value) {
-  return value?.backend === "herdr" && value.protocol === HERDR_PROTOCOL
+  return value?.backend === "herdr" && isSupportedHerdrProtocol(value.protocol)
     && [value.socket, value.binary, value.workspaceId, value.paneId, value.terminalId].every((v) => typeof v === "string" && v.length > 0)
     && value.socket === resolve(value.socket);
 }

package/lib/instruction-composition.mjs

@@ -0,0 +1,31 @@
+/** Formatting shared by current preparation and retained instruction projection.
+ * Selection/order is supplied by the caller; this module never discovers config. */
+import { readPortableBytes } from "./portable-files.mjs";
+import { oatsError } from "./errors.mjs";
+
+export function renderInstructionText(body, blocks) {
+  let text = body.replace(/\n*$/, "\n");
+  for (const { source, file, content } of blocks) {
+    text += `\n<!-- oats:${source} src=${file} -->\n${content.trim()}\n<!-- /oats:${source} -->\n`;
+  }
+  return text;
+}
+
+/** Input is the result of exact record verification, not a current config or
+ * a mutable soul directory. All paths come from its verified resource inventory. */
+export function composeCapturedInstructions(verified) {
+  const composition = verified.record.dispatch.composition;
+  if (!composition) throw oatsError("resolution-incomplete", "captured instruction composition is absent");
+  const read = (key) => {
+    const file = verified.resources.get(key);
+    if (!file) throw oatsError("resolution-incomplete", "captured instruction resource is absent");
+    let content;
+    try { content = new TextDecoder("utf-8", { fatal: true }).decode(readPortableBytes(file)); }
+    catch (cause) { throw oatsError("invalid-resolution", "captured instructions are not readable UTF-8", { cause }); }
+    return { file, content };
+  };
+  const body = read(composition.body);
+  const blocks = composition.blocks.map(({ source, resource }) => ({ source, ...read(resource) }));
+  const skills = composition.skills.map(({ name, resource }) => ({ name, path: verified.resources.get(resource) }));
+  return { text: renderInstructionText(body.content, blocks), blocks, skills, omissions: composition.omissions };
+}

package/lib/legacy-lock-codec.mjs

@@ -0,0 +1,106 @@
+/** Sole bounded structural decoder for historical lockfileVersion 1 and the
+ * capability-materialization lockfileVersion 2.
+ *
+ * Bytes in, validated null-prototype maps out. No filesystem/config reads,
+ * migration, normalization, repair or writes. Retired-capability policy is an
+ * injected pure predicate so this leaf does not import the kernel. */
+import { byteView, parseStrictJson } from "./portable-values.mjs";
+import {
+  PACKAGE_ID_RE, TRANSITIONAL_ROW_FIELDS, capabilityIdViolation,
+  isMaterializedCapabilityId, validateCapabilityLockEntry, validateLockEntry,
+} from "./capability-provenance.mjs";
+import { oatsError } from "./errors.mjs";
+
+const LOCK_PACKAGE_KEYS = new Set(["source", "path", "version", "commit", "integrity", "dependencies"]);
+const LOCK_CAPABILITY_KEYS = new Set(["version", "package", "path", "integrity", "trusted"]);
+const noneRetired = () => undefined;
+const nullProtoMap = (raw) => {
+  const out = Object.create(null);
+  for (const key of Object.keys(raw || {})) out[key] = raw[key];
+  return out;
+};
+const kind = (value) => value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+
+/** Validate one literal v1 capability row. Unknown historical fields remain
+ * preserved, matching the existing reader; required fields and known optional
+ * field types remain strict. */
+export function legacyCapabilityEntryViolation(entry) {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return "not an object";
+  for (const key of ["source", "version", "integrity"]) if (typeof entry[key] !== "string" || !entry[key]) return `missing/invalid ${key}`;
+  if (!/^sha256-[0-9a-f]{64}$/.test(entry.integrity)) return `malformed integrity "${entry.integrity}"`;
+  if (entry.commit !== undefined && typeof entry.commit !== "string") return "invalid commit";
+  if (entry.trustedExecutables !== undefined && typeof entry.trustedExecutables !== "boolean") return "invalid trustedExecutables";
+  return null;
+}
+
+/** Decode one already-read historical lock. `file` is diagnostic provenance,
+ * not a path this codec reads. Strict JSON adds bounded/duplicate-key/UTF-8
+ * refusal before the unchanged v1/v2 semantic pass. */
+export function decodeLegacyLockBytes(input, { file = "<legacy-lock>", retiredCapabilityReason = noneRetired, limits } = {}) {
+  const bytes = byteView(input, "legacy lock bytes");
+  if (typeof file !== "string" || !file) throw oatsError("invalid-lock", "legacy lock diagnostic file must be non-empty text");
+  if (typeof retiredCapabilityReason !== "function") throw oatsError("invalid-lock", `${file}: retired-capability classifier must be a function`);
+  const bad = (message, extra = {}) => oatsError("invalid-lock", `${file}: ${message}`, [{ file, violation: message, ...extra }]);
+  let parsed;
+  try { parsed = parseStrictJson(bytes, limits); }
+  catch (error) { const failure = bad(`malformed JSON — ${error.message}`); failure.cause = error; throw failure; }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw bad(`lock root must be a JSON object (got ${kind(parsed)})`);
+  const rawVersion = parsed.lockfileVersion;
+  if (rawVersion !== undefined && typeof rawVersion !== "number") throw bad(`lockfileVersion must be a number (got ${JSON.stringify(rawVersion)})`);
+  if (rawVersion !== undefined && rawVersion !== 1 && rawVersion !== 2) throw bad(`unsupported lockfileVersion ${rawVersion}`);
+  const version = rawVersion ?? 1;
+  if (parsed.capabilities !== undefined && (!parsed.capabilities || typeof parsed.capabilities !== "object" || Array.isArray(parsed.capabilities))) {
+    throw bad(`"capabilities" must be an object map (got ${kind(parsed.capabilities)})`);
+  }
+  const out = { version, packages: Object.create(null), capabilities: Object.create(null), legacyCapabilities: Object.create(null) };
+  if (version === 1) {
+    if (parsed.packages !== undefined) throw bad(`lockfileVersion 1 must not carry a "packages" map`);
+    for (const id of Object.keys(parsed.capabilities || {})) {
+      const entry = parsed.capabilities[id];
+      if (!retiredCapabilityReason(id)) {
+        const violation = legacyCapabilityEntryViolation(entry);
+        if (violation) throw bad(`legacy entry "${id}" is malformed (${violation})`, { package: id });
+      }
+      out.legacyCapabilities[id] = entry;
+    }
+    return out;
+  }
+
+  const rawPackages = parsed.packages;
+  if (!rawPackages || typeof rawPackages !== "object" || Array.isArray(rawPackages)) {
+    throw bad(`lockfileVersion 2 requires a "packages" object map (got ${kind(rawPackages)})`);
+  }
+  const packageKeys = Object.keys(rawPackages), hasCapabilityMap = Object.hasOwn(parsed, "capabilities");
+  const stateFree = packageKeys.length === 0 && (!hasCapabilityMap || Object.keys(parsed.capabilities).length === 0);
+  const unsupported = (why) => bad(`unsupported transitional package-root lockfileVersion 2 (${why}). This is the superseded package-store lock shape; it is not converted or interpreted. Delete this lock (and any .agents/packages directory) and recreate the scope's state with \`oats install\`.`);
+  if (!stateFree) {
+    if (!hasCapabilityMap) throw unsupported(`no top-level "capabilities" map`);
+    for (const id of packageKeys) {
+      const row = rawPackages[id];
+      if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+      const tells = TRANSITIONAL_ROW_FIELDS.filter((field) => Object.hasOwn(row, field));
+      if (tells.length) throw unsupported(`package row "${id}" carries ${tells.join(", ")}`);
+    }
+  }
+  for (const id of packageKeys) {
+    if (!PACKAGE_ID_RE.test(id)) throw bad(`packages map has an invalid package key ${JSON.stringify(id)}`, { package: id });
+    const entry = rawPackages[id];
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw bad(`lock entry for "${id}" is not an object`, { package: id });
+    const extra = Object.keys(entry).filter((key) => !LOCK_PACKAGE_KEYS.has(key));
+    if (extra.length) throw bad(`lock entry for "${id}" has unknown keys: ${extra.join(", ")}`, { package: id });
+    out.packages[id] = entry;
+  }
+  for (const id of Object.keys(out.packages)) validateLockEntry(id, out.packages[id], out.packages, { file });
+  if (hasCapabilityMap) {
+    for (const id of Object.keys(parsed.capabilities)) {
+      if (!isMaterializedCapabilityId(id)) throw bad(`capabilities map has an invalid capability key: ${capabilityIdViolation(id)}`);
+      const entry = parsed.capabilities[id];
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw bad(`capability lock entry for "${id}" is not an object`, { package: id });
+      const extra = Object.keys(entry).filter((key) => !LOCK_CAPABILITY_KEYS.has(key));
+      if (extra.length) throw bad(`capability lock entry for "${id}" has unknown keys: ${extra.join(", ")}`, { package: id });
+      out.capabilities[id] = entry;
+    }
+  }
+  for (const id of Object.keys(out.capabilities)) validateCapabilityLockEntry(id, out.capabilities[id], out.packages, { file });
+  return out;
+}

package/lib/manifest-settings.mjs

@@ -0,0 +1,84 @@
+/** Manifest-owned setting defaults are intrinsic field fallbacks, not another
+ * workspace/repository policy authority. Capture them before record publication. */
+import { canonicalJson, parseStrictJson } from "./portable-values.mjs";
+import { bytesIntegrity } from "./portable-digest.mjs";
+import { objectAt, pointerKey } from "./portable-shape.mjs";
+import { validateArtifactRef, validateOrigin } from "./resolution-shape.mjs";
+import { settingChoiceKey } from "./soul-constraints.mjs";
+import { resolveChoices } from "./portable-choices.mjs";
+import { oatsError } from "./errors.mjs";
+
+export function manifestSettingDefaults(artifact, bytes) {
+  validateArtifactRef(artifact);
+  if (artifact.kind !== "capability") throw oatsError("invalid-declaration", "manifest defaults need a capability artifact owner");
+  const manifest = parseStrictJson(bytes);
+  objectAt(manifest, null, ["capability", "version"]);
+  if (manifest.capability !== artifact.capability) throw oatsError("invalid-resolution", "manifest default owner differs from its artifact");
+  const defaults = Object.create(null);
+  if (manifest.settings !== undefined) objectAt(manifest.settings, null, [], "/settings");
+  const document = { kind: "artifact", owner: artifact, path: "oats.json", integrity: bytesIntegrity(bytes) };
+  for (const [name, declaration] of Object.entries(manifest.settings ?? {})) {
+    if (!declaration || typeof declaration !== "object" || Array.isArray(declaration) || !Object.hasOwn(declaration, "default")) continue;
+    const origin = { kind: "manifest-default", document, pointer: `/settings/${pointerKey(name)}/default` };
+    validateOrigin(origin);
+    defaults[name] = { key: settingChoiceKey(artifact.capability, name), kind: "manifest-default", value: declaration.default, origin };
+  }
+  return { manifest, defaults };
+}
+
+/** Definitions are the selected, verified manifest byte snapshots. No provider
+ * payload code runs here, and no source/lock/approval lookup is performed. */
+export function captureManifestSettings(plan, definitions) {
+  canonicalJson(plan);
+  if (plan.status === "conflict") throw oatsError("requirement-conflict", "cannot capture defaults for a conflicting software plan");
+  if (!Array.isArray(definitions)) throw oatsError("invalid-declaration", "selected manifest definitions must be an array");
+  const candidates = [...plan.candidates], settings = Object.create(null), seen = new Set();
+  for (const id of Object.keys(plan.capabilities)) settings[id] = Object.assign(Object.create(null), plan.settings[id] ?? {});
+  for (const { artifact, bytes } of definitions) {
+    const { defaults } = manifestSettingDefaults(artifact, bytes), id = artifact.capability;
+    if (!Object.hasOwn(plan.capabilities, id) || seen.has(id)) throw oatsError("invalid-resolution", "manifest defaults do not match the selected capability set");
+    seen.add(id);
+    for (const [name, candidate] of Object.entries(defaults)) {
+      candidates.push(candidate); settings[id][name] = candidate.key;
+    }
+  }
+  if (seen.size !== Object.keys(plan.capabilities).length) throw oatsError("resolution-incomplete", "selected manifest defaults were not fully captured");
+  const resolved = resolveChoices({ requirements: plan.requirements, candidates });
+  return { ...plan, ...resolved, candidates, settings };
+}
+
+/** Check both directions over ALL choices, not only settings the dispatch map
+ * happens to enumerate. Neither omissions nor invented intrinsic facts are valid,
+ * including overridden facts. Read each selected manifest only once. */
+export function verifyManifestSettings(record, definitions) {
+  const manifests = new Map(), expected = new Map();
+  const originKey = ({ kind, document, pointer }) => canonicalJson({ kind, document, pointer });
+  const matches = (entry, candidate) => candidate && entry.kind === "manifest-default"
+    && canonicalJson(entry.value) === canonicalJson(candidate.value) && originKey(entry.origin) === originKey(candidate.origin);
+  for (const { artifact, bytes } of definitions) {
+    const { manifest, defaults } = manifestSettingDefaults(artifact, bytes), id = artifact.capability;
+    const selected = record.artifacts.capabilities[id];
+    if (!selected || manifests.has(id) || canonicalJson(selected.artifact) !== canonicalJson(artifact)) {
+      throw oatsError("resolution-incomplete", "default verification does not match the selected capability set");
+    }
+    manifests.set(id, manifest);
+    for (const [name, candidate] of Object.entries(defaults)) {
+      expected.set(candidate.key, candidate);
+      const key = record.dispatch.settingsChoices[id]?.[name], choice = record.choices[candidate.key];
+      if (key !== candidate.key || !choice || !choice.considered.some((entry) => matches(entry, candidate))) {
+        throw oatsError("resolution-incomplete", "captured setting omits its exact manifest default or provenance");
+      }
+    }
+  }
+  if (manifests.size !== Object.keys(record.artifacts.capabilities).length) {
+    throw oatsError("resolution-incomplete", "selected manifest defaults were not fully verified");
+  }
+  for (const [key, choice] of Object.entries(record.choices)) {
+    for (const entry of choice.considered) {
+      if (entry.kind === "manifest-default" && !matches(entry, expected.get(key))) {
+        throw oatsError("resolution-incomplete", "captured intrinsic default is not witnessed by its selected manifest");
+      }
+    }
+  }
+  return manifests;
+}

package/lib/package-closure.mjs

@@ -0,0 +1,48 @@
+/** One bounded staged dependency walker. Adapters own source syntax/fetch,
+ * manifest compatibility and digest versions; this engine owns graph identity,
+ * cycle checks and ordering, never installation, selection or executable trust. */
+import { oatsError } from "./errors.mjs";
+
+export function resolvePackageClosure({ requests, readPackage, validatePackage, finalizePackage, discardPackage,
+  context = "package preparation", maxPackages = 256, maxDepth = 64, maxRequests = 1024 }) {
+  if (!Array.isArray(requests) || !requests.length) throw oatsError("invalid-source", "package closure requires explicit root requests");
+  for (const callback of [readPackage, validatePackage, finalizePackage, discardPackage]) {
+    if (typeof callback !== "function") throw new TypeError("package closure requires complete source/validation/ownership adapters");
+  }
+  for (const limit of [maxPackages, maxDepth, maxRequests]) {
+    if (!Number.isSafeInteger(limit) || limit < 1) throw oatsError("resource-limit", "invalid package graph budget");
+  }
+  if (maxDepth > 256) throw oatsError("resource-limit", "package graph depth budget exceeds supported traversal");
+  const resolved = new Map();
+  let reads = 0;
+  const visit = (request, parent, chain) => {
+    if (++reads > maxRequests || chain.length > maxDepth) {
+      throw oatsError("resource-limit", "package dependency graph budget exceeded");
+    }
+    const record = readPackage(request, parent, chain);
+    if (!record || typeof record.package !== "string" || !record.package || typeof record.sourceKey !== "string" || !record.sourceKey
+        || !Array.isArray(record.dependencyRequests)) throw oatsError("invalid-package-manifest", "package source adapter returned incomplete graph data");
+    const id = record.package;
+    if (chain.includes(id)) throw oatsError("dependency-cycle", `package dependency cycle: ${[...chain, id].join(" → ")}`, [...chain, id]);
+    if (resolved.has(id)) {
+      const previous = resolved.get(id);
+      if (previous.sourceKey !== record.sourceKey) {
+        throw oatsError("duplicate-package-identity", `two sources claim package "${id}" at ${context}: ${previous.sourceKey} and ${record.sourceKey}`,
+          [...(previous.origins ?? [previous.sourceKey]), ...(record.origins ?? [record.sourceKey])]);
+      }
+      // A source adapter may reuse an already staged root. Never discard the
+      // authoritative copy merely because another edge reached it again.
+      if (record.dir !== previous.dir) discardPackage(record, previous);
+      return id;
+    }
+    if (resolved.size + chain.length >= maxPackages) throw oatsError("resource-limit", "package identity budget exceeded");
+    validatePackage(record);
+    const deps = record.dependencyRequests.map((dependency) => visit(dependency, record, [...chain, id]));
+    const complete = finalizePackage(record, deps);
+    if (!complete || complete.package !== id || complete.sourceKey !== record.sourceKey) throw oatsError("invalid-package-manifest", "package finalizer changed graph identity");
+    resolved.set(id, complete);
+    return id;
+  };
+  const roots = requests.map((request) => visit(request, null, []));
+  return { roots, packages: resolved };
+}

package/lib/package-materialization.mjs

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