@awebai/oats 0.23.2 → 0.24.1

package/lib/portable-onboarding-acceptance.mjs

@@ -0,0 +1,66 @@
+/** Fresh setup acceptance boundary. Read-only comparison and explicit mutation
+ * handoff only; all source discovery and request construction remain owned by
+ * portable-onboarding. */
+import { canonicalJson, freezeJson } from "./portable-values.mjs";
+import { sameIdentity } from "./portable-identity.mjs";
+import { buildFreshPreparationRequest, recheckFreshOnboarding } from "./portable-onboarding.mjs";
+import { oatsError } from "./errors.mjs";
+
+export const PORTABLE_ONBOARDING_ACCEPTANCE_VERSION = 1;
+
+/** Prove two issued/ready inspections name one unchanged source while retaining
+ * distinct organization and standalone work/context facts. */
+export function compareFreshSourceAcceptance({ organization, standalone }) {
+  const organizationRequest = buildFreshPreparationRequest(organization), standaloneRequest = buildFreshPreparationRequest(standalone);
+  if (!organization.workspace || organization.context.kind !== "workspace") throw oatsError("invalid-declaration", "organization acceptance requires an explicit workspace context");
+  if (standalone.workspace !== null || standalone.context.kind !== "standalone") throw oatsError("invalid-declaration", "standalone acceptance requires an explicit standalone context");
+  if (standalone.workTarget.git.present) throw oatsError("invalid-declaration", "standalone acceptance work target must be explicitly non-Git");
+  if (!sameIdentity(organization.source.identity, standalone.source.identity)) throw oatsError("source-identity-change", "acceptance inspections name different source identities");
+  if (organization.source.revision.commit !== standalone.source.revision.commit
+      || organization.source.exportPath !== standalone.source.exportPath
+      || organization.source.definition !== standalone.source.definition) {
+    throw oatsError("integrity-drift", "acceptance inspections do not name the same unchanged source export");
+  }
+  return freezeJson({ schemaVersion: PORTABLE_ONBOARDING_ACCEPTANCE_VERSION, status: "ready",
+    source: { identity: organization.source.identity, commit: organization.source.revision.commit,
+      exportPath: organization.source.exportPath, definition: organization.source.definition },
+    organization: { context: organization.context, workTarget: organization.workTarget,
+      preparation: organizationRequest.preparation },
+    standalone: { context: standalone.context, workTarget: standalone.workTarget,
+      preparation: standaloneRequest.preparation },
+    effects: { writes: false, preparation: false, approval: false, enrollment: false } });
+}
+
+function approvalRequests(result) {
+  const requests = [];
+  for (const selection of Array.isArray(result?.selections) ? result.selections : []) {
+    for (const capability of Array.isArray(selection.approvalRequired) ? selection.approvalRequired : []) {
+      requests.push({ capability, artifactSet: selection.artifactSet, request: selection.request });
+    }
+  }
+  return requests;
+}
+
+/** Recheck fresh deployment state immediately before an explicitly supplied
+ * public preparation function. Missing integration/provisioning remains pending;
+ * no stale inspection is permission to overwrite managed state. */
+export function prepareFreshOnboarding(inspection, options = {}, { prepareCapturedComposition } = {}) {
+  canonicalJson(options);
+  const built = buildFreshPreparationRequest(inspection, options);
+  const preflight = recheckFreshOnboarding(inspection);
+  const requestedBindings = built.preparation.operator?.bindings ?? null;
+  if (preflight.deployment.state === "absent") return freezeJson({ schemaVersion: PORTABLE_ONBOARDING_ACCEPTANCE_VERSION,
+    status: "pending", code: "fresh-deployment-provisioning-required", mutationAttempted: false,
+    preparation: built.preparation, workTarget: built.workTarget, requestedBindings,
+    resolution: null, approvalRequests: [], problems: [{ code: "fresh-deployment-provisioning-required", message: "provision the explicit fresh deployment path before preparation" }] });
+  if (typeof prepareCapturedComposition !== "function") return freezeJson({ schemaVersion: PORTABLE_ONBOARDING_ACCEPTANCE_VERSION,
+    status: "pending", code: "onboarding-integration-required", mutationAttempted: false,
+    preparation: built.preparation, workTarget: built.workTarget, requestedBindings,
+    resolution: null, approvalRequests: [], problems: [{ code: "onboarding-integration-required", message: "the public captured preparation adapter is not available" }] });
+  const result = prepareCapturedComposition(built.preparation);
+  if (!result || typeof result !== "object" || Array.isArray(result)) throw oatsError("invalid-resolution", "public preparation returned no structured result");
+  return freezeJson({ schemaVersion: PORTABLE_ONBOARDING_ACCEPTANCE_VERSION,
+    status: typeof result.status === "string" ? result.status : "pending", mutationAttempted: true,
+    preparation: built.preparation, workTarget: built.workTarget, requestedBindings,
+    resolution: result.resolution ?? null, approvalRequests: approvalRequests(result), problems: Array.isArray(result.problems) ? result.problems : [] });
+}

package/lib/portable-onboarding-request.mjs

@@ -0,0 +1,49 @@
+/** Thin request-file transport for explicit new-work preparation.
+ * The CLI owns flag parsing through its existing router; public core owns the
+ * preparation schema/resolver. This module reads no ambient authority and never
+ * prepares, installs, approves, activates or dispatches a command. */
+import { isAbsolute, resolve } from "node:path";
+import { readPortableBytes } from "./portable-files.mjs";
+import { canonicalJson, freezeJson, parseStrictJson } from "./portable-values.mjs";
+import { objectAt } from "./portable-shape.mjs";
+import { oatsError } from "./errors.mjs";
+
+/**
+ * file: explicit normalized absolute JSON file.
+ * inputFlags: OTHER prepare value flags already parsed by the existing router;
+ *   request/json are consumed by that router and must not occur here. Even a
+ *   false/null/empty-valued competing flag is a conflict by own-key presence.
+ * explicitSelector: existing capturedSelector(argv, {}) result, or null. No
+ *   second global selector parser, inherited resolution or environment lookup.
+ *
+ * Return the decoded request itself, not a wrapper/private prepare input. Unknown
+ * request fields survive unchanged so the sole public core validator can refuse
+ * them; never strip them to produce an apparently compatible request.
+ */
+export function readPortablePreparationRequest(options) {
+  canonicalJson(options);
+  objectAt(options, ["file", "inputFlags", "explicitSelector"], ["file"]);
+  const { file, inputFlags = {}, explicitSelector = null } = options;
+  objectAt(inputFlags, null, []);
+  if (Object.keys(inputFlags).length) throw oatsError("E_BAD_ARGS", "--request cannot be combined with other preparation input flags");
+  if (explicitSelector !== null) throw oatsError("E_BAD_ARGS", "new-work preparation cannot use explicit captured selectors");
+  if (typeof file !== "string" || !isAbsolute(file) || resolve(file) !== file || file.includes("\0")) {
+    throw oatsError("E_BAD_ARGS", "--request needs a normalized absolute JSON file path");
+  }
+  let bytes;
+  try { bytes = readPortableBytes(file, { missingCode: "E_BAD_ARGS", invalidCode: "E_BAD_ARGS" }); }
+  catch (error) {
+    // Do not echo request content, source/settings or OS diagnostic payloads.
+    throw oatsError(error.code === "resource-limit" ? "resource-limit"
+      : error.code === "integrity-drift" ? "integrity-drift" : "E_BAD_ARGS", "preparation request file could not be read as bounded regular bytes");
+  }
+  let input;
+  try { input = parseStrictJson(bytes); }
+  catch (error) {
+    throw oatsError(error.code === "resource-limit" ? "resource-limit" : "invalid-declaration", "preparation request file must contain bounded strict UTF-8 JSON");
+  }
+  // Only the transport's JSON-object boundary is checked here, not a copy of the
+  // public preparation field/choice/provider validation contract.
+  objectAt(input, null, []);
+  return freezeJson(input);
+}

package/lib/portable-onboarding.mjs

@@ -0,0 +1,249 @@
+/** 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 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;
+}
+
+function workTarget(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"],
+    ["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 = workTarget(input.workTarget), discovery = createWorkspaceDiscovery(repositories);
+  const witness = { deployment: preflightWitnesses.get(deployment), work: directoryIdentity(target.path) };
+  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,
+    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,
+    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 } : {}),
+    ...(operator === undefined ? {} : { operator }), ...(mode === undefined ? {} : { mode }) };
+  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

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

@@ -0,0 +1,44 @@
+/** 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-shape.mjs

@@ -0,0 +1,35 @@
+/** Small shape checks shared by portable document/record codecs. Call only on
+ * decoded or canonical-data-validated values; these helpers do not resolve policy. */
+import { oatsError } from "./errors.mjs";
+import { scalarString } from "./portable-values.mjs";
+
+export const pointerKey = (key) => key.replace(/~/g, "~0").replace(/\//g, "~1");
+export function invalidShape(pointer, message, code = "invalid-declaration") {
+  throw oatsError(code, `${message} at ${pointer || "/"}`);
+}
+export function objectAt(value, allowed, required, pointer = "") {
+  if (!value || typeof value !== "object" || Array.isArray(value)) invalidShape(pointer, "expected object");
+  if (allowed) for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) invalidShape(`${pointer}/${pointerKey(key)}`, "unknown field");
+  }
+  for (const key of required ?? []) if (!Object.hasOwn(value, key)) invalidShape(`${pointer}/${pointerKey(key)}`, "missing field");
+  return value;
+}
+export function stringAt(value, pointer, { pattern, empty = false } = {}) {
+  scalarString(value, pointer);
+  if ((!empty && !value) || (pattern && !pattern.test(value))) invalidShape(pointer, "invalid string");
+  return value;
+}
+export function versionAt(value, pointer = "/schemaVersion") {
+  if (value !== 1) invalidShape(pointer, "unsupported wire version", "unsupported-wire-version");
+}
+export function stringSetAt(value, pointer, validate = stringAt) {
+  if (!Array.isArray(value)) invalidShape(pointer, "expected array");
+  const seen = new Set();
+  value.forEach((item, index) => {
+    validate(item, `${pointer}/${index}`);
+    if (seen.has(item)) invalidShape(`${pointer}/${index}`, "duplicate set entry");
+    seen.add(item);
+  });
+  return value;
+}