@awebai/oats 0.25.9 → 0.27.0

package/lib/captured-scaffold.mjs

@@ -1,87 +0,0 @@
-/** Materialize one already-verified captured composition into a new private home.
- * Home placement is supplied by the lifecycle owner; this module never discovers
- * config, souls, work targets, launch software or instance roots. */
-import { existsSync, lstatSync, mkdirSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
-import { randomUUID } from "node:crypto";
-import { capturedDirectoryIdentity, registerCapturedInstance, syncCapturedMetadata } from "./captured-instance-index.mjs";
-import { copyTreeSafe } from "./artifact-tree.mjs";
-import { canonicalJson } from "./portable-values.mjs";
-import { portableScope } from "./portable-state.mjs";
-import { oatsError } from "./errors.mjs";
-
-const INSTANCE_RE = /^[a-z0-9][a-z0-9-]{0,127}$/;
-
-function sameDirectory(path, witness) {
-  try {
-    const current = lstatSync(path);
-    return current.isDirectory() && current.dev === witness.dev && current.ino === witness.ino;
-  } catch { return false; }
-}
-
-export function validateCapturedDirectoryTarget(home, instance) {
-  if (typeof home !== "string" || !isAbsolute(home) || resolve(home) !== home || basename(home) !== instance || !INSTANCE_RE.test(instance)) {
-    throw oatsError("invalid-declaration", "captured scaffold needs a normalized absolute home whose basename is its instance name");
-  }
-}
-
-export function materializeCapturedDirectoryScaffold({ home, instance, loaded }) {
-  validateCapturedDirectoryTarget(home, instance);
-  if (!loaded?.record || !loaded?.composition || !loaded?.resolution || typeof loaded.deployment !== "string") throw oatsError("invalid-resolution", "captured scaffold requires a verified composition load");
-  const { record, composition } = loaded;
-  if (record.dispatch.composition?.mode !== "directory") throw oatsError("needs-configuration", "captured scaffold currently requires retained directory work mode");
-  if (existsSync(home)) throw oatsError("E_INSTANCE_EXISTS", `instance home already exists: ${home}`);
-  const parent = dirname(home), parentStat = lstatSync(parent);
-  if (!parentStat.isDirectory() || realpathSync(parent) !== parent) throw oatsError("E_NO_CANONICAL_ROOT", "captured scaffold parent must be a physical directory");
-  const subject = record.subject, agent = subject.kind === "persistent" ? subject.soul.alias : subject.name;
-  const responsibleHuman = record.messagingChoice.enabled ? record.messagingChoice.privateKey.human : null;
-  const executionBinding = { schemaVersion: 1, deployment: portableScope(loaded.deployment), resolution: loaded.resolution };
-  const bodyFile = loaded.resources.get(record.dispatch.composition.body);
-  if (!bodyFile) throw oatsError("invalid-resolution", "captured scaffold body is absent from verified resources");
-  const sourceRoot = dirname(bodyFile);
-  const metadata = {
-    instance, agent, kind: subject.kind, home, work: "directory", launched: false, incarnationId: randomUUID(),
-    executionBinding, responsibleHuman,
-    captured: { schemaVersion: 1, resolution: loaded.resolution, lifecycle: "scaffolded-hooks-pending" },
-    capabilities: [...loaded.capabilities.values()].map(({ id, manifest, settings }) => ({ id, version: manifest.version, settings })),
-  };
-  let owned, primary, indexAttempted = false;
-  try {
-    mkdirSync(home, { mode: 0o700 }); owned = lstatSync(home);
-    symlinkSync(sourceRoot, join(home, "soul"));
-    writeFileSync(join(home, "AGENTS.md"), composition.text, { mode: 0o600 });
-    symlinkSync("AGENTS.md", join(home, "CLAUDE.md"));
-    mkdirSync(join(home, ".agents", "skills"), { recursive: true, mode: 0o700 });
-    mkdirSync(join(home, ".claude"), { mode: 0o700 });
-    for (const skill of composition.skills) copyTreeSafe(skill.path, join(home, ".agents", "skills", skill.name));
-    symlinkSync(join("..", ".agents", "skills"), join(home, ".claude", "skills"));
-    mkdirSync(join(home, "work"), { mode: 0o700 });
-    for (const skill of composition.skills) {
-      const file = join(home, ".agents", "skills", skill.name, "SKILL.md");
-      if (!existsSync(file) || !lstatSync(file).isFile()) throw oatsError("resolution-incomplete", `captured skill ${skill.name} did not materialize`);
-    }
-    metadata.captured.custody = { home: capturedDirectoryIdentity(home), work: capturedDirectoryIdentity(join(home, "work")) };
-    writeFileSync(join(home, "instance.json"), canonicalJson(metadata), { flag: "wx", mode: 0o600 });
-    for (const path of [join(home, "instance.json"), join(home, "work"), home, parent]) syncCapturedMetadata(path);
-    indexAttempted = true;
-    registerCapturedInstance(loaded.deployment, home);
-    return { home, instance, agent, work: "directory", incarnationId: metadata.incarnationId, executionBinding, responsibleHuman, launched: false, hooksPending: true };
-  } catch (error) {
-    primary = error;
-    // Publication/guard cleanup may fail AFTER index publication. Retain the
-    // home rather than erase evidence just because the call did not return.
-    if (indexAttempted) { error.home = home; error.cleanupRequired = true; }
-    throw error;
-  }
-  finally {
-    if (primary && owned && !indexAttempted) {
-      try {
-        if (!sameDirectory(home, owned)) throw oatsError("integrity-drift", "captured scaffold home ownership changed during rollback");
-        rmSync(home, { recursive: true });
-      } catch (cleanup) {
-        const error = new AggregateError([primary, cleanup], "captured scaffold and rollback failed", { cause: primary });
-        error.code = primary.code; throw error;
-      }
-    }
-  }
-}

package/lib/captured-selector.mjs

@@ -1,28 +0,0 @@
-/** Explicit independent-dispatch selectors, with the captured command's own
- * environment as a propagation channel. Never infer a record from cwd/locks. */
-import { isAbsolute } from "node:path";
-import { validateResolutionRef } from "./resolution-shape.mjs";
-import { oatsError } from "./errors.mjs";
-
-export function capturedSelector(argv, env = process.env) {
-  const values = new Map(), args = [];
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === "--") { args.push(...argv.slice(i)); break; }
-    const match = /^(--deployment|--resolution|--artifact-set)(?:=(.*))?$/.exec(arg);
-    if (!match) { args.push(arg); continue; }
-    const name = match[1].slice(2), value = match[2] ?? argv[++i];
-    if (values.has(name) || !value || value.startsWith("--")) throw oatsError("E_BAD_ARGS", `--${name} needs one unambiguous value`);
-    values.set(name, value);
-  }
-  const explicit = values.size > 0;
-  const deployment = explicit ? values.get("deployment") : env.OATS_DEPLOYMENT;
-  if (values.has("resolution") && values.has("artifact-set")) throw oatsError("E_BAD_ARGS", "choose a resolution or an artifact set, never both");
-  const artifactSet = values.get("artifact-set");
-  const id = explicit ? artifactSet ?? values.get("resolution") : env.OATS_RESOLUTION;
-  if (!explicit && deployment === undefined && id === undefined) return null;
-  if (typeof deployment !== "string" || !isAbsolute(deployment) || typeof id !== "string") throw oatsError("E_BAD_ARGS", "portable selectors need --deployment <absolute path> and one --resolution or --artifact-set <sha256-id>");
-  const resolution = { schemaVersion: 1, id };
-  validateResolutionRef(resolution);
-  return { deployment, ...(artifactSet === undefined ? { resolution } : { artifactSet }), args, explicit };
-}

package/lib/captured-session-backend.mjs

@@ -1,52 +0,0 @@
-/** Closed inputs for the existing native session adapters. No config lookup,
- * endpoint allocation, backend registry or runtime/provider readiness probe. */
-import { isAbsolute, resolve } from 'node:path';
-import { canonicalJson } from './portable-values.mjs';
-import { objectAt } from './portable-shape.mjs';
-import { HERDR_SUPPORTED_PROTOCOLS, isSupportedHerdrProtocol, validHerdrTarget } from './herdr.mjs';
-import { oatsError } from './errors.mjs';
-
-const same = (a,b) => canonicalJson(a) === canonicalJson(b);
-const absolute = value => typeof value === 'string' && isAbsolute(value) && resolve(value) === value && !value.includes('\0');
-export function validateCapturedSessionBackend(value) {
-  canonicalJson(value);
-  const fields=value?.backend==='herdr'?['backend','binary','socket','protocol']:['backend','binary','socket','session'];
-  objectAt(value,fields,fields);
-  if(!['tmux','herdr'].includes(value.backend)||!absolute(value.binary)||!absolute(value.socket))throw oatsError('needs-configuration','captured native backend needs explicit normalized host binary/socket');
-  if(value.backend==='herdr'){
-    if(!isSupportedHerdrProtocol(value.protocol))throw oatsError('needs-configuration',`captured Herdr requires an explicitly selected protocol in ${HERDR_SUPPORTED_PROTOCOLS.join(', ')}`);
-  }else if(typeof value.session!=='string'||!/^[A-Za-z0-9_-]+$/.test(value.session))throw oatsError('needs-configuration','captured tmux needs an explicit supported session name');
-  return value;
-}
-
-export function validateCapturedSessionTarget(value,backend,instance) {
-  validateCapturedSessionBackend(backend);canonicalJson(value);
-  if(backend.backend==='tmux'){
-    objectAt(value,['backend','session','window','socket'],['backend','session','window','socket']);
-    if(!same(value,{backend:'tmux',session:backend.session,window:instance,socket:backend.socket}))throw oatsError('E_RUNTIME_AUTHORITY_MISMATCH','captured tmux target differs from admitted endpoint');
-  }else{
-    objectAt(value,['backend','binary','socket','protocol','workspaceId','paneId','terminalId'],['backend','binary','socket','protocol','workspaceId','paneId','terminalId']);
-    if(!validHerdrTarget(value)||value.binary!==backend.binary||value.socket!==backend.socket||value.protocol!==backend.protocol
-      ||[value.workspaceId,value.paneId,value.terminalId].some(id=>id.includes('\0')))throw oatsError('E_RUNTIME_AUTHORITY_MISMATCH','captured Herdr target differs from admitted endpoint/identifier contract');
-  }
-  return value;
-}
-
-/** First placement admits a server endpoint, not caller-chosen Herdr IDs.
- * Subsequent IDs must come from independently retained native observations. */
-export function assertCapturedSessionPlacement(metadata,backend,knownTargets=[]) {
-  validateCapturedSessionBackend(backend);
-  if(typeof metadata.launched!=='boolean')throw oatsError('E_RUNTIME_AUTHORITY_MISMATCH','captured metadata lacks native launch state');
-  if(metadata.launched&&!Object.hasOwn(metadata,backend.backend==='herdr'?'sessionTarget':'tmux'))throw oatsError('E_RUNTIME_AUTHORITY_MISMATCH','launched metadata lacks its native target');
-  if(Object.hasOwn(metadata,'backend')&&metadata.backend!==backend.backend)throw oatsError('E_RUNTIME_AUTHORITY_MISMATCH','captured metadata selects a different backend');
-  if(backend.backend==='tmux'){
-    if(Object.hasOwn(metadata,'sessionTarget'))throw oatsError('E_RUNTIME_AUTHORITY_MISMATCH','Herdr target cannot redirect captured tmux');
-    if(Object.hasOwn(metadata,'tmux'))validateCapturedSessionTarget({backend:'tmux',...metadata.tmux},backend,metadata.instance);
-  }else{
-    if(Object.hasOwn(metadata,'tmux'))throw oatsError('E_RUNTIME_AUTHORITY_MISMATCH','tmux metadata cannot redirect captured Herdr');
-    if(Object.hasOwn(metadata,'sessionTarget')){
-      validateCapturedSessionTarget(metadata.sessionTarget,backend,metadata.instance);
-      if(!knownTargets.some(target=>same(target,metadata.sessionTarget)))throw oatsError('E_RUNTIME_AUTHORITY_MISMATCH','Herdr metadata target lacks independent indexed custody');
-    }
-  }
-}

package/lib/captured-source-receipt-file.mjs

@@ -1,72 +0,0 @@
-/** Private captured-source registration input. This is a synchronous hook
- * snapshot, never durable worker authority or an ambient configuration file. */
-import { lstatSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { isAbsolute, join, resolve } from "node:path";
-import { validateSoulIdentity } from "./portable-identity.mjs";
-import { canonicalJson } from "./portable-values.mjs";
-import { objectAt, stringAt } from "./portable-shape.mjs";
-import { portableStateDirectory } from "./portable-state.mjs";
-import { validateProviderBinding } from "./resolution-shape.mjs";
-import { validateExecutionBinding } from "./schedule-capsule.mjs";
-import { oatsError } from "./errors.mjs";
-
-export const CAPTURED_SOURCE_RECEIPT_LIMITS = Object.freeze({ maxBytes: 256 * 1024, maxDepth: 32, maxEntries: 16_384 });
-const RECEIPT_FIELDS = ["schemaVersion", "kind", "home", "work", "context", "agent", "instance", "sourceIdentity", "role", "executionBinding", "responsibleHuman", "binding"];
-
-function absolutePath(value, pointer) {
-  stringAt(value, pointer);
-  if (!isAbsolute(value) || resolve(value) !== value || value.includes("\0")) throw oatsError("invalid-declaration", `${pointer} must be a normalized absolute path`);
-}
-
-function human(value) {
-  if (value === null) return;
-  objectAt(value, ["provider", "id"], ["provider", "id"], "/responsibleHuman");
-  stringAt(value.provider, "/responsibleHuman/provider");
-  stringAt(value.id, "/responsibleHuman/id");
-}
-
-export function validateCapturedSourceReceipt(value) {
-  canonicalJson(value, CAPTURED_SOURCE_RECEIPT_LIMITS);
-  objectAt(value, RECEIPT_FIELDS, RECEIPT_FIELDS);
-  if (value.schemaVersion !== 1) throw oatsError("unsupported-wire-version", "captured source receipt schemaVersion must be 1");
-  if (!["persistent", "helper"].includes(value.kind)) throw oatsError("invalid-declaration", "captured source receipt kind must be persistent or helper");
-  for (const [key, field] of [["home", value.home], ["work", value.work], ["context", value.context]]) absolutePath(field, `/${key}`);
-  if (value.context !== value.executionBinding?.deployment) throw oatsError("invalid-declaration", "captured source receipt context must equal its execution deployment");
-  stringAt(value.agent, "/agent"); stringAt(value.instance, "/instance"); stringAt(value.role, "/role");
-  for (const [pointer, text] of [["/agent", value.agent], ["/instance", value.instance], ["/role", value.role]]) if (text.includes("\0")) throw oatsError("invalid-declaration", `${pointer} contains NUL`);
-  if (!value.agent || !value.instance || Buffer.byteLength(value.role, "utf8") > 128 * 1024) throw oatsError("invalid-declaration", "captured source receipt identity/role is empty or exceeds its bound");
-  if (value.kind === "persistent") {
-    if (value.sourceIdentity === null) throw oatsError("invalid-declaration", "persistent captured source receipt needs a qualified soul identity");
-    validateSoulIdentity(value.sourceIdentity);
-  } else if (value.sourceIdentity !== null) throw oatsError("invalid-declaration", "helper captured source receipt must not claim a persistent soul identity");
-  validateExecutionBinding(value.executionBinding); human(value.responsibleHuman); validateProviderBinding(value.binding);
-  return value;
-}
-
-export function withCapturedSourceReceiptFile(home, receipt, run) {
-  validateCapturedSourceReceipt(receipt);
-  if (typeof run !== "function") throw oatsError("invalid-declaration", "captured source receipt consumer must be a function");
-  if (resolve(home) !== receipt.home) throw oatsError("invalid-declaration", "captured source receipt home differs from its invocation home");
-  const directory = mkdtempSync(join(portableStateDirectory(receipt.executionBinding.deployment, true), ".source-receipt-"));
-  const owned = lstatSync(directory), file = join(directory, "receipt.json"); let primary, result, completed = false;
-  try {
-    writeFileSync(file, canonicalJson(receipt, CAPTURED_SOURCE_RECEIPT_LIMITS), { flag: "wx", mode: 0o600 });
-    result = run({ OATS_SOURCE_RECEIPT_FILE: file }); completed = true; return result;
-  } catch (error) { primary = error; throw error; }
-  finally {
-    try {
-      const current = lstatSync(directory);
-      if (!current.isDirectory() || current.dev !== owned.dev || current.ino !== owned.ino) throw oatsError("integrity-drift", "source receipt invocation directory ownership changed");
-      rmSync(directory, { recursive: true });
-    } catch (cleanup) {
-      if (!primary) {
-        const error = new AggregateError([cleanup], "captured source receipt cleanup failed after invocation", { cause: cleanup });
-        error.code = cleanup.code; error.invocationCompleted = completed; error.invocationResult = result; throw error;
-      }
-      const error = new AggregateError([primary, cleanup], "captured source receipt invocation and cleanup failed", { cause: primary });
-      error.code = primary.code;
-      if (primary.invocationCompleted) { error.invocationCompleted = true; error.invocationResult = primary.invocationResult; }
-      throw error;
-    }
-  }
-}

package/lib/helper-injection-policy.mjs

@@ -1,104 +0,0 @@
-/** 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) {
-      // Attributed like every other preparation problem: the operator learns WHICH
-      // capability lacks the declaration, not only that one does (second-operator finding).
-      const error = oatsError('needs-configuration', 'new helper injection requires an explicit capability policy');
-      error.problems = [{ code: 'needs-configuration', message: 'capability ships an inject without a helperInjection policy', capability: id, ...(policy.manifest.layer ? { slot: policy.manifest.layer } : {}) }];
-      throw error;
-    }
-    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/legacy-lock-codec.mjs

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

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

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