@awebai/oats 0.25.8 → 0.26.0

package/lib/portable-onboarding.mjs

@@ -1,256 +0,0 @@
-/** Read-only fresh setup and source discovery facade.
- *
- * Existing project content is allowed. Relevant OATS-managed state produces a
- * separate-path hold; nothing is deleted, rewritten, installed, enrolled or
- * prepared here. Repository reads are delegated to the existing transaction and
- * workspace discovery/parser stack. */
-import { lstatSync, opendirSync, realpathSync } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { createWorkspaceDiscovery } from "./workspace-discovery.mjs";
-import { parseMemberExports } from "./workspace-definition.mjs";
-import { canonicalJson, compareUtf8, freezeJson } from "./portable-values.mjs";
-import { validateOrigin } from "./resolution-shape.mjs";
-import { oatsError } from "./errors.mjs";
-
-export const PORTABLE_ONBOARDING_VERSION = 1;
-const PREPARATION_ONLY_FIELDS = Object.freeze(["operator", "launch", "helperLaunches", "mode", "allowLocalPaths"]);
-const issued = new WeakMap();
-const preflightWitnesses = new WeakMap();
-const MANAGED_PATHS = Object.freeze([
-  ["deployment-config", "oats-config.yaml"],
-  ["selection-lock", "oats-lock.json"],
-  ["schedules", "oats-schedules.json"],
-  ["portable-state", ".agents/portable"],
-  ["captured-resolutions", ".agents/resolutions"],
-  ["migration-evidence", ".agents/resolution-evidence"],
-  ["installed-capabilities", ".agents/capabilities/installed"],
-  ["retained-capabilities", ".agents/capabilities/artifacts"],
-  ["retained-souls", ".agents/soul-artifacts"],
-  ["retained-resources", ".agents/resource-artifacts"],
-  ["schedule-state", ".agents/schedules"],
-  ["installed-packages", ".agents/packages/installed"],
-  ["native-history", ".oats-native-record"],
-]);
-
-const present = (path) => { try { return lstatSync(path); } catch (error) { if (error.code === "ENOENT") return null; throw error; } };
-function exact(value, allowed, required, where) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) throw oatsError("invalid-declaration", `${where} must be an object`);
-  for (const key of Object.keys(value)) if (!allowed.includes(key)) throw oatsError("invalid-declaration", `${where} has unsupported field ${key}`);
-  for (const key of required) if (!Object.hasOwn(value, key)) throw oatsError("invalid-declaration", `${where} is missing ${key}`);
-  return value;
-}
-function canonicalExistingDirectory(path, label) {
-  if (typeof path !== "string" || !isAbsolute(path) || resolve(path) !== path) throw oatsError("invalid-declaration", `${label} must be a normalized absolute path`);
-  let actual;
-  try { actual = realpathSync(path); } catch (error) { if (error.code === "ENOENT") throw oatsError("source-unavailable", `${label} is absent`); throw error; }
-  if (actual !== path || !lstatSync(actual).isDirectory()) throw oatsError("invalid-declaration", `${label} must be a real non-symlinked directory`);
-  return actual;
-}
-function directoryIdentity(path) {
-  const stat = lstatSync(path);
-  if (!stat.isDirectory()) throw oatsError("selection-changed", "fresh setup directory is no longer a real directory");
-  return { dev: stat.dev, ino: stat.ino };
-}
-function freshDeploymentPath(path) {
-  if (typeof path !== "string" || !isAbsolute(path) || resolve(path) !== path) throw oatsError("invalid-declaration", "fresh deployment must be a normalized absolute path");
-  const stat = present(path);
-  if (stat) {
-    if (!stat.isDirectory() || realpathSync(path) !== path) throw oatsError("invalid-declaration", "fresh deployment path must be a real non-symlinked directory");
-    return { path, state: "existing", identity: { dev: stat.dev, ino: stat.ino } };
-  }
-  let parent;
-  try { parent = realpathSync(dirname(path)); }
-  catch (error) { if (error.code === "ENOENT") throw oatsError("source-unavailable", "fresh deployment parent is absent"); throw error; }
-  if (parent !== dirname(path) || !lstatSync(parent).isDirectory()) throw oatsError("invalid-declaration", "fresh deployment parent must be a real non-symlinked directory");
-  return { path, state: "absent", parent: directoryIdentity(parent) };
-}
-function relativePath(root, path) { return relative(root, path).split(sep).join("/"); }
-function scanInstanceState(root, base, budget) {
-  const found = [], path = join(root, base), stat = present(path);
-  if (!stat) return found;
-  if (!stat.isDirectory() || realpathSync(path) !== path) return [{ kind: "managed-agents-root", path: base }];
-  const directory = opendirSync(path);
-  try {
-    for (;;) {
-      const entry = directory.readSync();
-      if (entry === null) break;
-      if (++budget.visited > budget.maxEntries) throw oatsError("resource-limit", "fresh deployment instance scan entry limit exceeded");
-      if (!entry.isDirectory()) continue;
-      for (const [kind, child] of [["instance-homes", "instances"], ["retirement-state", ".oats-retirement"]]) {
-        const target = join(path, entry.name, child);
-        if (present(target)) found.push({ kind, path: relativePath(root, target) });
-      }
-    }
-  } finally { directory.closeSync(); }
-  return found;
-}
-
-/** Detect only known deployment-owned state. Ordinary files, Git metadata,
- * authored souls/capabilities and source repositories do not make a path dirty. */
-export function preflightFreshDeployment({ deployment, maxEntries = 4096 }) {
-  canonicalJson({ deployment, maxEntries });
-  if (!Number.isSafeInteger(maxEntries) || maxEntries < 1 || maxEntries > 100_000) throw oatsError("resource-limit", "invalid fresh deployment scan budget");
-  const selected = freshDeploymentPath(deployment), managedState = [];
-  if (selected.state === "existing") {
-    for (const [kind, relative] of MANAGED_PATHS) if (present(join(selected.path, relative))) managedState.push({ kind, path: relative });
-    const budget = { visited: 0, maxEntries };
-    managedState.push(...scanInstanceState(selected.path, "agents", budget), ...scanInstanceState(selected.path, "local-agents", budget));
-  }
-  managedState.sort((a, b) => compareUtf8(`${a.path}:${a.kind}`, `${b.path}:${b.kind}`));
-  if (canonicalJson(freshDeploymentPath(deployment)) !== canonicalJson(selected)) {
-    throw oatsError("selection-changed", "fresh deployment changed during preflight; inspect it again");
-  }
-  const status = managedState.length ? "separate-deployment-required" : "ready";
-  const result = freezeJson({ schemaVersion: PORTABLE_ONBOARDING_VERSION, status,
-    deployment: { path: selected.path, state: selected.state }, managedState,
-    advice: managedState.length ? ["Preserve this deployment and choose a separate fresh deployment path; no existing state was changed."] : [],
-    effects: { writes: false, deletes: false, installs: false, enrollment: false } });
-  preflightWitnesses.set(result, selected);
-  return result;
-}
-
-export function inspectWorkTarget(path) {
-  const canonical = canonicalExistingDirectory(path, "work target"), marker = present(join(canonical, ".git"));
-  return { path: canonical, state: "existing", git: marker ? { present: true, kind: marker.isDirectory() ? "directory" : marker.isFile() ? "file" : "other" } : { present: false, kind: null } };
-}
-function sourceOrigin(workspace, alias) {
-  const index = workspace?.parsed.imports.findIndex((entry) => entry.alias === alias) ?? -1;
-  if (index < 0) throw oatsError("export-not-found", "requested alias is not advertised by the explicit workspace");
-  return { reference: workspace.parsed.imports[index], origin: { ...workspace.parsed.origins[`/imports/${index}`], kind: "import-adoption" } };
-}
-function explicitContext(input) {
-  const hasWorkspace = Object.hasOwn(input, "workspace");
-  const hasStandalone = Object.hasOwn(input, "standaloneContextKey");
-  if (hasWorkspace && hasStandalone) throw oatsError("invalid-declaration", "workspace and standaloneContextKey are mutually exclusive contexts");
-  if (hasWorkspace) return null;
-  if (!hasStandalone) throw oatsError("needs-configuration", "standalone onboarding requires an explicit standaloneContextKey (null explicitly means no private messaging context)");
-  const key = input.standaloneContextKey;
-  if (key !== null && (typeof key !== "string" || !key || Buffer.byteLength(key, "utf8") > 256 || key.trim() !== key || /[\x00-\x1f\x7f]/.test(key))) {
-    throw oatsError("invalid-declaration", "standaloneContextKey must be explicit null or non-empty text up to 256 UTF-8 bytes");
-  }
-  return { kind: "standalone", key };
-}
-function catalogSelection(value, count) {
-  if (value === undefined) return [];
-  if (!Array.isArray(value) || value.length > count || value.some((index) => !Number.isSafeInteger(index) || index < 0 || index >= count)
-      || new Set(value).size !== value.length) throw oatsError("invalid-declaration", "catalogIndexes must be unique declared workspace catalog indexes");
-  return [...value].sort((a, b) => a - b);
-}
-
-/** Inspect one explicit source and optional explicit workspace/member/catalogs.
- * The caller owns the repository transaction lifetime. */
-export function inspectPortableOnboarding(input, { repositories } = {}) {
-  canonicalJson(input);
-  exact(input, ["deployment", "workTarget", "source", "origin", "workspace", "member", "catalogIndexes", "standaloneContextKey", ...PREPARATION_ONLY_FIELDS],
-    ["deployment", "workTarget", "source", "origin"], "portable onboarding inspection");
-  if (!repositories || typeof repositories !== "object") throw oatsError("invalid-source", "portable onboarding needs an explicit repository transaction");
-  validateOrigin(input.origin);
-  const standalone = explicitContext(input);
-  const deployment = preflightFreshDeployment({ deployment: input.deployment });
-  const target = inspectWorkTarget(input.workTarget), discovery = createWorkspaceDiscovery(repositories);
-  const ignored = PREPARATION_ONLY_FIELDS.filter(field => Object.hasOwn(input, field));
-  // Retain authored data privately for explicit request export ONLY. Inspection
-  // neither validates provider/launch semantics nor exposes these values.
-  const witness = { deployment: preflightWitnesses.get(deployment), work: directoryIdentity(target.path),
-    preparationFields: Object.fromEntries(ignored.map(field => [field, structuredClone(input[field])])) };
-  const workspace = Object.hasOwn(input, "workspace") ? discovery.readWorkspace(input.workspace) : null;
-  const selected = typeof input.source === "string" ? sourceOrigin(workspace, input.source) : { reference: input.source, origin: input.origin };
-  const imported = discovery.importSoul(selected.reference, { origin: selected.origin });
-  const indexDocument = repositories.readFile(imported.observation, "oats.yaml");
-  const exports = parseMemberExports(indexDocument.bytes, { origin: indexDocument.origin });
-  const membership = input.member ? (() => {
-    if (!workspace) throw oatsError("needs-configuration", "member inspection needs an explicit workspace");
-    return discovery.checkMember(workspace, input.member);
-  })() : { schemaVersion: 1, status: "not-requested", evidence: [], problems: [] };
-  const catalogs = [];
-  const selectedCatalogs = catalogSelection(input.catalogIndexes, workspace?.parsed.catalogs.length ?? 0);
-  if (selectedCatalogs.length && !workspace) throw oatsError("needs-configuration", "catalog inspection needs an explicit workspace");
-  for (const index of selectedCatalogs) {
-    const declared = workspace.parsed.catalogs[index], base = workspace.parsed.origins[`/catalogs/${index}`];
-    if (!declared.path) throw oatsError("needs-configuration", "catalog inspection needs an explicit descriptor path");
-    const origin = { ...base, kind: "workspace-default" }; validateOrigin(origin);
-    const observation = repositories.observe(declared.source, { ...(declared.revision ? { revision: declared.revision } : {}), origin });
-    const document = repositories.readFile(observation, declared.path);
-    catalogs.push({ index, declaration: declared, source: observation.source, document: document.origin });
-  }
-  const declaredTeams = workspace?.parsed.declaration.teams ?? {};
-  const status = deployment.status !== "ready" ? deployment.status
-    : input.member && membership.status !== "eligible" ? "needs-configuration" : "ready-for-preparation";
-  const result = freezeJson({ schemaVersion: PORTABLE_ONBOARDING_VERSION, status, deployment, workTarget: target, ignored,
-    source: { location: imported.reference.source, reference: imported.reference, identity: imported.identity,
-      revision: imported.observation.source, alias: imported.reference.alias, exportPath: imported.reference.soul,
-      definition: imported.definition, roots: imported.roots, exports: exports.exports, provenance: imported.provenance },
-    workspace: workspace ? { request: structuredClone(input.workspace), identity: workspace.identity, source: workspace.source,
-      name: workspace.parsed.declaration.name, members: workspace.parsed.members,
-      imports: workspace.parsed.imports, catalogs: workspace.parsed.catalogs } : null,
-    context: workspace ? { kind: "workspace", identity: workspace.identity } : standalone,
-    repositoryMembership: { request: input.member ? structuredClone(input.member) : null, result: membership },
-    teams: { declared: declaredTeams, enrollment: "not-performed", privateTeamQualification: "not-evaluated" },
-    catalogs, problems: membership.problems ?? [],
-    effects: { deploymentWrites: false, repositoryReads: true, repositoryScratch: "caller-owned",
-      installs: false, activation: false, credentials: false, teams: false, jobs: false } });
-  issued.set(result, witness);
-  if (status === "ready-for-preparation") recheckFreshOnboarding(result);
-  return result;
-}
-
-/** Metadata-only public view, NOT a serialized fresh-inspection witness or a
- * preparation request. Provider payloads/adoption values have not gone through
- * their owner's nonsecret classification and must not leak through inspection. */
-export function describePortableOnboarding(inspection) {
-  if (!issued.has(inspection)) throw oatsError("invalid-declaration", "inspection summary requires an issued onboarding view");
-  const reference = value => ({ source: value.source, soul: value.soul, revision: value.revision, alias: value.alias,
-    adoptionPresent: Object.hasOwn(value, "adoption") });
-  const { reference: selected, exports, ...source } = inspection.source;
-  return freezeJson({ ...inspection,
-    source: { ...source, adoptionPresent: Object.hasOwn(selected, "adoption"), exports: {
-      souls: (exports.souls ?? []).map(({ path, definition, description }) => ({ path, definition, ...(description === undefined ? {} : { description }) })),
-      packages: (exports.packages ?? []).map(({ path, description }) => ({ path, ...(description === undefined ? {} : { description }) })),
-      knowledge: (exports.knowledge ?? []).map(({ contract, version }) => ({ contract, version, payloadOmitted: true })),
-    } },
-    workspace: inspection.workspace ? { ...inspection.workspace, imports: inspection.workspace.imports.map(reference) } : null,
-    omitted: { providerPayloads: true, adoptionValues: true },
-  });
-}
-
-/** Ephemeral local root custody, not a new persistent authority/schema. Ordinary
- * project content changes are allowed; replacing the inspected directories or
- * provisioning a previously absent deployment requires a fresh inspection. */
-export function recheckFreshOnboarding(inspection) {
-  const witness = issued.get(inspection);
-  if (!witness) throw oatsError("invalid-declaration", "fresh target recheck requires an issued inspection");
-  const current = preflightFreshDeployment({ deployment: inspection.deployment.deployment.path });
-  if (current.status !== "ready") throw oatsError("fresh-deployment-required", "fresh deployment acquired managed state after inspection; preserve it and choose another path");
-  if (canonicalJson(preflightWitnesses.get(current)) !== canonicalJson(witness.deployment)) {
-    throw oatsError("selection-changed", "inspected deployment or its absent-path parent changed; inspect it again");
-  }
-  let work;
-  try { work = directoryIdentity(canonicalExistingDirectory(inspection.workTarget.path, "work target")); }
-  catch { throw oatsError("selection-changed", "inspected work target is no longer available at its owned path"); }
-  if (canonicalJson(work) !== canonicalJson(witness.work)) throw oatsError("selection-changed", "inspected work target directory changed; inspect it again");
-  return current;
-}
-
-/** Build data for the existing preparation API. This function never invokes it.
- * Work target remains adjacent and distinct from deployment/source inputs. */
-export function buildFreshPreparationRequest(inspection, options = {}) {
-  canonicalJson(options);
-  exact(options, ["operator", "mode", "allowLocalPaths"], [], "fresh preparation options");
-  if (!issued.has(inspection)) throw oatsError("invalid-declaration", "fresh preparation requires an inspection issued by this module");
-  if (inspection.status !== "ready-for-preparation") throw oatsError("fresh-deployment-required", "fresh preparation is held by deployment or membership preflight");
-  const { operator, mode, allowLocalPaths = false } = options;
-  if (typeof allowLocalPaths !== "boolean") throw oatsError("invalid-declaration", "allowLocalPaths must be boolean");
-  if (mode !== undefined && (typeof mode !== "string" || !mode.trim())) throw oatsError("invalid-declaration", "preparation mode must be non-empty text");
-  const input = { deployment: inspection.deployment.deployment.path, workTarget: inspection.workTarget.path,
-    source: inspection.source.reference,
-    origin: inspection.source.revision.provenance[0], allowLocalPaths,
-    ...(inspection.workspace ? { workspace: inspection.workspace.request } : { standaloneContextKey: inspection.context.key }),
-    ...(inspection.repositoryMembership.request ? { member: inspection.repositoryMembership.request } : {}),
-    ...issued.get(inspection).preparationFields,
-    ...(operator === undefined ? {} : { operator }), ...(mode === undefined ? {} : { mode }),
-    ...(Object.hasOwn(options, "allowLocalPaths") ? { allowLocalPaths } : {}) };
-  canonicalJson(input);
-  return freezeJson({ schemaVersion: PORTABLE_ONBOARDING_VERSION, operation: "prepare", persisted: false,
-    preparation: input, workTarget: inspection.workTarget,
-    effects: { writes: false, installs: false, activation: false, enrollment: false } });
-}

package/lib/portable-package-preparation.mjs

@@ -1,188 +0,0 @@
-/** Package-side portable preparation over frozen observations. No current lock,
- * config cascade, approval or activation lookup; caller owns final composition/CAS. */
-import { chmodSync, lstatSync, mkdtempSync, readdirSync, readlinkSync, realpathSync } from "node:fs";
-import { isAbsolute, join, posix, relative } from "node:path";
-import { canonicalJson, compareUtf8, decodeUtf8, parseStrictJson } from "./portable-values.mjs";
-import { PACKAGE_FORMAT, bytesIntegrity, treeIntegrity } from "./portable-digest.mjs";
-import { readPortableBytes } from "./portable-files.mjs";
-import { removeOwnedStaging } from "./artifact-tree.mjs";
-import { createSourceProjection, validateProjectionPath } from "./source-projection.mjs";
-import { resolvePackageClosure } from "./package-closure.mjs";
-import { parseLockedSource3, parsePackageDependency3, parseRepositorySource, portablePath, validateRepoAnchor, validateSelectionSource } from "./source-spec.mjs";
-import { isMaterializedCapabilityId } from "./capability-provenance.mjs";
-import { objectAt } from "./portable-shape.mjs";
-import { validateArtifactSet, validateOrigin } from "./resolution-shape.mjs";
-import { retainPortableArtifact } from "./portable-artifacts.mjs";
-import { oatsError } from "./errors.mjs";
-
-const outside = (root, target) => { const path = relative(root, target); return path === ".." || path.startsWith("../") || path.startsWith("..\\") || isAbsolute(path); };
-function copyLocalPayload(source, destination) {
-  const root = realpathSync(source), parent = realpathSync(join(destination, "..")), rootStat = lstatSync(root);
-  if (!rootStat.isDirectory() || !outside(root, parent)) throw oatsError("invalid-source", "package input must be a directory outside its staging tree");
-  const entries = []; let count = 0, bytes = 0;
-  const inspect = (directory, parts) => {
-    if (parts.length > 64) throw oatsError("resource-limit", "local package source depth exceeded");
-    for (const raw of readdirSync(directory, { encoding: "buffer" })) {
-      if (++count > 10_000) throw oatsError("resource-limit", "local package source entry budget exceeded");
-      const name = decodeUtf8(raw), lowered = name.toLowerCase();
-      if (lowered === ".git") continue; // Never read/copy Git administrative state, at any depth.
-      if ([".aw", ".agents", ".oats-state"].includes(lowered) || (lowered === "instances" && parts.at(-2)?.toLowerCase() === "agents")) {
-        throw oatsError("source-incomplete", "local package subtree contains private deployment/auth/instance state");
-      }
-      const path = [...parts, name].join("/"), file = join(directory, name), stat = lstatSync(file);
-      validateProjectionPath(path);
-      if (!stat.isDirectory() && !stat.isFile() && !stat.isSymbolicLink()) throw oatsError("invalid-source", "local package source contains a special file");
-      if (stat.isFile() && (bytes += stat.size) > 256 * 1024 * 1024) throw oatsError("resource-limit", "local package source byte budget exceeded");
-      entries.push({ path, file, stat });
-      if (stat.isDirectory()) inspect(file, [...parts, name]);
-    }
-  };
-  inspect(root, []); // Complete no-follow privacy/size preflight before any copy.
-  const projection = createSourceProjection(destination);
-  const unchanged = (entry) => {
-    const actual = lstatSync(entry.file), before = entry.stat;
-    if (actual.dev !== before.dev || actual.ino !== before.ino || actual.mode !== before.mode || actual.size !== before.size
-        || actual.mtimeMs !== before.mtimeMs || actual.ctimeMs !== before.ctimeMs) throw oatsError("integrity-drift", "local package source changed during snapshot");
-  };
-  for (const entry of entries) {
-    unchanged(entry);
-    if (entry.stat.isDirectory()) projection.directory(entry.path, entry.stat.mode & 0o7777);
-    else if (entry.stat.isSymbolicLink()) projection.link(entry.path, readlinkSync(entry.file));
-    else projection.copyFile(entry.path, entry.file, entry.stat.mode & 0o7777);
-    unchanged(entry);
-  }
-  projection.finish(); chmodSync(destination, rootStat.mode & 0o7777);
-}
-
-export function preparePackageArtifacts({ requests, deployment, directory, repositories, kernel, observations = [], catalog, allowLocalPaths = false }) {
-  canonicalJson(requests);
-  if (!Array.isArray(requests) || !requests.length || typeof directory !== "string" || !isAbsolute(directory)
-      || typeof deployment !== "string" || !isAbsolute(deployment) || typeof allowLocalPaths !== "boolean") throw oatsError("invalid-source", "package preparation needs explicit requests, scope and scratch directory");
-  for (const name of ["loadPackageManifestAt", "capabilityCompatibility", "assertPlatformInvariantLocks", "materializeCapability"]) {
-    if (typeof kernel?.[name] !== "function") throw new TypeError(`package preparation requires kernel.${name}`);
-  }
-  for (const request of requests) {
-    objectAt(request, ["source", "origin", "capability"], ["source", "origin"]); validateOrigin(request.origin);
-    if (request.capability !== undefined && !isMaterializedCapabilityId(request.capability)) throw oatsError("invalid-source", "invalid requested capability identity");
-  }
-  const staging = mkdtempSync(join(realpathSync(directory), ".package-preparation-")), owned = lstatSync(staging);
-  const cached = new Map(), sourceObservations = [...observations]; let counter = 0, closed = false;
-  const cleanup = () => {
-    if (closed) return;
-    const current = lstatSync(staging);
-    if (!current.isDirectory() || current.dev !== owned.dev || current.ino !== owned.ino) throw oatsError("source-incomplete", "package staging cleanup lost ownership");
-    removeOwnedStaging(staging); closed = true;
-  };
-  const observe = (source, selector, origin) => {
-    const existing = sourceObservations.find((value) => value.source.remote === source && (value.source.commit === selector || value.source.selector === selector));
-    if (existing) return existing;
-    const observation = repositories.observe(source, { ...(selector === undefined ? {} : { revision: selector }), origin });
-    sourceObservations.push(observation);
-    return observation;
-  };
-  const readPackage = (request) => {
-    validateOrigin(request.origin);
-    let selected = request.source;
-    if (selected?.kind === "catalog") {
-      const normalized = parsePackageDependency3(selected.source);
-      if (canonicalJson(normalized) !== canonicalJson(selected)) throw oatsError("invalid-source", "catalog request fields disagree");
-    } else validateSelectionSource(selected);
-    const key = canonicalJson(selected);
-    if (cached.has(key)) return cached.get(key);
-    let originalSource, packagePath, commit, payload, sourceDocument, repoAnchor = null, localBase;
-    const destination = join(staging, `package-${counter++}`);
-    let repository, selector;
-    if (selected.kind === "repo") {
-      repoAnchor = selected.anchor;
-      if (repoAnchor.source.startsWith("path:")) {
-        const root = parseLockedSource3(repoAnchor.source, ".").localPath;
-        const localPath = join(root, selected.path);
-        selected = { kind: "path", source: `path:${localPath}`, path: ".", localPath, portable: false };
-      } else {
-        repository = repoAnchor.source; selector = repoAnchor.revision; packagePath = selected.path;
-        originalSource = `${repository}@${selector}`;
-      }
-    }
-    if (selected.kind === "catalog") {
-      if (typeof catalog !== "function") throw oatsError("needs-configuration", "package dependency requires an explicit catalog resolver");
-      const entry = catalog(selected.id, selected.selector);
-      if (!entry || typeof entry.url !== "string") throw oatsError("invalid-source", "catalog did not resolve a repository");
-      repository = parseRepositorySource(`git:${entry.url}`).normalized;
-      selector = entry.ref; packagePath = entry.path ?? "oats-package"; originalSource = selected.source;
-    } else if (selected.kind === "git") {
-      repository = parseRepositorySource(`git:${selected.url}`).normalized;
-      selector = selected.selector; packagePath = selected.path; originalSource = selected.source;
-    }
-    if (selected.kind === "path") {
-      if (!allowLocalPaths) throw oatsError("needs-configuration", "local package input requires explicit authorization");
-      localBase = selected.localPath; originalSource = selected.source; packagePath = "."; commit = "local";
-      copyLocalPayload(localBase, destination); payload = destination;
-      sourceDocument = { kind: "source", source: originalSource, revision: "local", path: "oats-package.json" };
-    } else {
-      portablePath(packagePath, { allowRoot: true });
-      const observation = observe(repository, selector, request.origin);
-      repositories.materialize(observation, [packagePath], destination);
-      payload = join(destination, packagePath); commit = observation.source.commit;
-      repoAnchor = { source: observation.source.remote, revision: commit };
-      sourceDocument = { kind: "source", source: observation.source.remote, revision: commit, path: posix.join(packagePath, "oats-package.json") };
-    }
-    // Strict JSON ingress precedes the sole existing full package/manifest codec.
-    const bytes = readPortableBytes(join(payload, "oats-package.json")); parseStrictJson(bytes);
-    sourceDocument.integrity = bytesIntegrity(bytes);
-    const manifest = kernel.loadPackageManifestAt(payload, { strict: true });
-    const dependencyRequests = (manifest.dependencies ?? []).map((spec, index) => {
-      // Local siblings are authoring input. A remote manifest never gains access
-      // to adopter files merely because another root request was local.
-      let source = parsePackageDependency3(spec, { localBase, allowLocalPaths: allowLocalPaths && localBase !== undefined });
-      if (source.kind === "repo") {
-        if (!repoAnchor) throw oatsError("needs-configuration", "repo dependency has no explicit repository snapshot anchor");
-        source = { ...source, anchor: validateRepoAnchor(repoAnchor) };
-      }
-      return { source, origin: { kind: "package-dependency", document: sourceDocument, pointer: `/dependencies/${index}` } };
-    });
-    const record = { package: manifest.package, version: manifest.version, source: originalSource, path: packagePath, commit,
-      sourceKey: canonicalJson({ source: originalSource, path: packagePath, commit }), dir: payload, manifest,
-      capabilities: manifest._capabilities, dependencyRequests, origins: [request.origin] };
-    cached.set(key, record); return record;
-  };
-  try {
-    const graph = resolvePackageClosure({ requests, readPackage,
-      validatePackage(record) {
-        const compatibility = kernel.capabilityCompatibility(record.manifest);
-        if (!compatibility.compatible) throw oatsError("incompatible-oats", `package ${record.package} requires OATS ${compatibility.range}`);
-      },
-      finalizePackage: (record, deps) => ({ ...record, deps, integrity: treeIntegrity(record.dir, { format: PACKAGE_FORMAT }) }),
-      discardPackage: () => {}, // All duplicate payloads belong to outer owned staging.
-    });
-    const owners = new Map();
-    for (const record of graph.packages.values()) for (const cap of record.capabilities) {
-      if (owners.has(cap.id) && owners.get(cap.id) !== record.package) throw oatsError("duplicate-capability-id", "selected package closures export conflicting capability identities");
-      owners.set(cap.id, record.package);
-    }
-    requests.forEach((request, index) => {
-      if (request.capability && !graph.packages.get(graph.roots[index]).capabilities.some((cap) => cap.id === request.capability)) throw oatsError("capability-list-mismatch", "selected source does not export the required capability");
-    });
-    kernel.assertPlatformInvariantLocks([...graph.packages.values()].flatMap((record) => record.capabilities.map((cap) => cap.dir)));
-    const artifactSet = { schemaVersion: 1, packages: Object.create(null), capabilities: Object.create(null) };
-    const artifacts = new Map();
-    for (const record of graph.packages.values()) {
-      artifactSet.packages[record.package] = { source: record.source, path: record.path, version: record.version, commit: record.commit,
-        integrity: record.integrity, dependencies: [...new Set(record.deps)].sort(compareUtf8) };
-      for (const cap of record.capabilities) {
-        const projected = kernel.materializeCapability({ cap, pkg: record, artifactsDir: join(staging, "artifacts") });
-        const artifact = { kind: "capability", capability: cap.id, integrity: treeIntegrity(projected.dir) };
-        artifactSet.capabilities[cap.id] = { version: projected.version, artifact, origin: { kind: "package", package: record.package, path: cap.rel, projectionVersion: 1 } };
-        artifacts.set(cap.id, projected.dir);
-      }
-    }
-    validateArtifactSet(artifactSet);
-    for (const [id, source] of artifacts) retainPortableArtifact(deployment, source, artifactSet.capabilities[id].artifact);
-    return { artifactSet, roots: graph.roots, cleanup };
-  } catch (error) {
-    try { cleanup(); } catch (failure) {
-      const combined = new AggregateError([error, failure], "package preparation and cleanup failed", { cause: error });
-      combined.code = error.code; combined.stagingPath = staging; throw combined;
-    }
-    throw error;
-  }
-}

package/lib/portable-policy.mjs

@@ -1,44 +0,0 @@
-/** Shared authored selection shapes for the two policy authorities. Validation
- * only: no precedence, provider selection, acquisition, enrollment or execution. */
-import { isMaterializedCapabilityId } from "./capability-provenance.mjs";
-import { parsePortableSource } from "./source-spec.mjs";
-import { invalidShape, objectAt, pointerKey, stringAt } from "./portable-shape.mjs";
-
-export const FUNDAMENTAL_SLOTS = Object.freeze(["knowledge", "messaging", "tasks"]);
-export function validatePolicyChoices(value, { pointer, required = false, origins = {}, origin = null, localBase, allowLocalPaths = false }) {
-  const rules = objectAt(value, ["capabilities", ...FUNDAMENTAL_SLOTS], [], pointer);
-  const sources = Object.create(null);
-  const capabilityAt = (id, at) => { if (!isMaterializedCapabilityId(id)) invalidShape(at, "invalid capability identity"); };
-  const selection = (item, at, capability) => {
-    objectAt(item, capability === undefined ? ["capability", "source", "settings"] : ["source", "settings"],
-      capability === undefined ? ["capability", "source"] : ["source"], at);
-    capabilityAt(capability ?? item.capability, capability === undefined ? `${at}/capability` : at);
-    stringAt(item.source, `${at}/source`);
-    try { sources[`${at}/source`] = parsePortableSource(item.source, { localBase, allowLocalPaths }); }
-    catch (error) { error.provenance = [origins[`${at}/source`] ?? { document: origin, pointer: `${at}/source` }]; throw error; }
-    if (Object.hasOwn(item, "settings")) objectAt(item.settings, null, [], `${at}/settings`);
-  };
-  if (Object.hasOwn(rules, "capabilities")) {
-    objectAt(rules.capabilities, null, [], `${pointer}/capabilities`);
-    for (const [id, item] of Object.entries(rules.capabilities)) {
-      const at = `${pointer}/capabilities/${pointerKey(id)}`;
-      capabilityAt(id, at);
-      if (!required && item === false) continue;
-      selection(item, at, id);
-    }
-  }
-  for (const slot of FUNDAMENTAL_SLOTS) {
-    if (!Object.hasOwn(rules, slot)) continue;
-    const item = rules[slot], at = `${pointer}/${slot}`;
-    if ((required && item === "any") || (!required && item === "none")) continue;
-    selection(item, at);
-  }
-  return sources;
-}
-
-export function validateProviderDeclaration(value, pointer) {
-  const envelope = objectAt(value, ["contract", "version", "payload"], ["contract", "version", "payload"], pointer);
-  stringAt(envelope.contract, `${pointer}/contract`, { pattern: /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/ });
-  if (!Number.isSafeInteger(envelope.version) || envelope.version < 1) invalidShape(`${pointer}/version`, "invalid provider contract version");
-  return envelope;
-}

package/lib/portable-soul.mjs

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

package/lib/portable-state.mjs

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