@awebai/oats 0.25.9 → 0.26.0

package/lib/portable-composition.mjs

@@ -1,136 +0,0 @@
-/** Source-aware software choice planning. Consumes validated parser results;
- * qualifies no hosting identity and performs no acquisition, approval or enrollment.
- * All precedence/conflicts still go through the single resolveChoices engine. */
-import { canonicalJson, compareUtf8 } from "./portable-values.mjs";
-import { invalidShape, objectAt, pointerKey } from "./portable-shape.mjs";
-import { validateOrigin } from "./resolution-shape.mjs";
-import { sameIdentity, validateSoulIdentity } from "./portable-identity.mjs";
-import { FUNDAMENTAL_SLOTS, validatePolicyChoices } from "./portable-policy.mjs";
-import { capabilityChoiceKey, layerChoiceKey, settingChoiceKey, soulConstraints, sourceSelectionValue } from "./soul-constraints.mjs";
-import { resolveChoices } from "./portable-choices.mjs";
-import { validateRepoAnchor, validateSelectionSource } from "./source-spec.mjs";
-import { isMaterializedCapabilityId } from "./capability-provenance.mjs";
-
-function originAt(parsed, pointer, kind) {
-  const locator = parsed.origins[pointer];
-  if (!locator) invalidShape(pointer, "planning requires the original declaration origin");
-  const origin = { ...locator, kind };
-  validateOrigin(origin);
-  return origin;
-}
-
-export function planSoftwareChoices(input) {
-  canonicalJson(input);
-  objectAt(input, ["identity", "soul", "workspace", "adoptions", "operator", "providerRequirements"], ["identity", "soul"]);
-  const { identity, soul, workspace = null, adoptions = [], operator = null, providerRequirements = [] } = input;
-  validateSoulIdentity(identity);
-  const requirements = soulConstraints(soul), candidates = [], settingsCandidates = [];
-  if (!Array.isArray(adoptions) || !Array.isArray(providerRequirements)) invalidShape("", "adoptions and provider constraints must be arrays");
-  const add = (parsed, key, value, pointer, kind) => candidates.push({ key, value, kind, origin: originAt(parsed, pointer, kind) });
-  const collect = (parsed, policy, pointer, kind, sourceContext) => {
-    const selection = (id, item, at, key) => {
-      const selectedSource = item === false || item === "none" ? null : sourceSelectionValue(id, parsed, at, sourceContext);
-      add(parsed, key, selectedSource, at, kind);
-      if (item && typeof item === "object") for (const [name, value] of Object.entries(item.settings ?? {})) {
-        settingsCandidates.push({ owner: { key, value: selectedSource }, candidate: { key: settingChoiceKey(id, name), value, kind,
-          origin: originAt(parsed, `${at}/settings/${pointerKey(name)}`, kind) } });
-      }
-    };
-    for (const [id, item] of Object.entries(policy.capabilities ?? {})) selection(id, item, `${pointer}/capabilities/${pointerKey(id)}`, capabilityChoiceKey(id));
-    for (const slot of FUNDAMENTAL_SLOTS) if (Object.hasOwn(policy, slot)) {
-      const item = policy[slot]; selection(item === "none" ? null : item.capability, item, `${pointer}/${slot}`, layerChoiceKey(slot));
-    }
-  };
-  if (workspace?.declaration.defaults) collect(workspace, workspace.declaration.defaults, "/defaults", "workspace-default");
-  if (soul.declaration.defaults) collect(soul, soul.declaration.defaults, "/defaults", "soul-default");
-
-  // Discovery supplies qualified identity. An alias never performs this lookup.
-  // Several aliases may contribute compatible fields; conflicting equal-authority
-  // fields are reported by resolveChoices with both original document pointers.
-  for (const adoption of adoptions) {
-    objectAt(adoption, ["identity", "parsed", "origins", "pointer"], ["identity", "parsed", "origins", "pointer"]);
-    validateSoulIdentity(adoption.identity);
-    if (!sameIdentity(adoption.identity, identity)) continue;
-    const imported = adoption.parsed.reference;
-    if (identity.kind !== "git-soul" || imported.soul !== identity.exportPath) invalidShape("/adoptions", "qualified adoption does not match its exported source path");
-    if (identity.repository.kind === "canonical-remote" && imported.source !== identity.repository.remote) invalidShape("/adoptions", "import source contradicts its qualified canonical identity");
-    const parsed = { sources: adoption.parsed.sources, origins: adoption.origins };
-    const root = `${adoption.pointer}/adoption`, value = imported.adoption ?? {};
-    if (value.providers) collect(parsed, value.providers, `${root}/providers`, "import-adoption");
-    for (const field of ["bindings", "teamAliases"]) for (const [key, item] of Object.entries(value[field] ?? {})) {
-      add(parsed, `/adoption/${field}/${pointerKey(key)}`, item, `${root}/${field}/${pointerKey(key)}`, "import-adoption");
-    }
-  }
-  if (operator) {
-    objectAt(operator, ["policy", "document", "localBase", "allowLocalPaths", "sourceContext", "bindings"], ["policy", "document"]);
-    if (operator.bindings !== undefined) objectAt(operator.bindings, null, [], "/operator/bindings");
-    if (operator.sourceContext !== undefined) validateRepoAnchor(operator.sourceContext);
-    if (operator.allowLocalPaths !== undefined && typeof operator.allowLocalPaths !== "boolean") invalidShape("/operator/allowLocalPaths", "expected explicit boolean local-source authorization");
-    validateOrigin({ kind: "operator", document: operator.document, pointer: "/policy" });
-    if (operator.document.kind !== "operator") invalidShape("/operator/document", "operator choices need an operator input locator");
-    const origins = Object.create(null);
-    const mark = (value, pointer) => {
-      origins[pointer] = { document: operator.document, pointer };
-      if (value && typeof value === "object") for (const [key, child] of Object.entries(value)) mark(child, `${pointer}/${pointerKey(key)}`);
-    };
-    mark(operator.policy, "/policy");
-    const sources = validatePolicyChoices(operator.policy, { pointer: "/policy", origins,
-      localBase: operator.localBase, allowLocalPaths: operator.allowLocalPaths === true });
-    collect({ sources, origins }, operator.policy, "/policy", "operator", operator.sourceContext);
-  }
-  for (const requirement of [...requirements, ...providerRequirements]) validateOrigin(requirement.origin);
-  // Provider-owned fixed fields join the SAME constraint pipeline. This function
-  // neither interprets a payload nor executes a provider to obtain these inputs.
-  const allRequirements = [...requirements, ...providerRequirements];
-  // Eligibility follows the selected owning field AND source. Reuse the same
-  // engine for this deterministic source pass, then final field resolution;
-  // nothing is fetched/re-observed and no second precedence policy is introduced.
-  const sourceChoices = resolveChoices({ requirements: allRequirements, candidates }).choices;
-  const excludedSettings = [];
-  for (const { owner, candidate } of settingsCandidates) {
-    if (sameIdentity(sourceChoices[owner.key]?.value ?? null, owner.value)) candidates.push(candidate);
-    else excludedSettings.push({ ...candidate, owner, reason: "owning-source-overridden" });
-  }
-  const result = resolveChoices({ requirements: allRequirements, candidates });
-  const capabilities = Object.create(null), providers = Object.create(null), settings = Object.create(null);
-  const problems = [...result.problems];
-  const select = (key) => {
-    const choice = result.choices[key];
-    if (!choice || choice.value === null) return null;
-    objectAt(choice.value, ["capability", "source"], ["capability", "source"], key);
-    const { capability, source } = choice.value;
-    if (!isMaterializedCapabilityId(capability)) invalidShape(key, "invalid selected capability identity");
-    if (key.startsWith("/capabilities/") && key !== capabilityChoiceKey(capability)) invalidShape(key, "capability choice key differs from its selected identity");
-    validateSelectionSource(source);
-    if (Object.hasOwn(capabilities, capability)) {
-      const prior = capabilities[capability];
-      if (!sameIdentity(prior.source, source)) problems.push({ code: "requirement-conflict", key,
-        message: "one capability identity has incompatible selected sources", origins: [result.choices[prior.choiceKeys[0]].selectedBy, choice.selectedBy] });
-      prior.choiceKeys.push(key);
-    } else capabilities[capability] = { source, choiceKeys: [key] };
-    return capability;
-  };
-  for (const key of Object.keys(result.choices).sort(compareUtf8)) if (key.startsWith("/capabilities/")) select(key);
-  for (const slot of FUNDAMENTAL_SLOTS) {
-    const key = layerChoiceKey(slot);
-    if (Object.hasOwn(result.choices, key)) providers[slot] = select(key);
-  }
-  // Only selected software receives settings; alternative/default history remains
-  // in choices for explanation, not an ambient configuration to execute later.
-  for (const id of Object.keys(capabilities)) settings[id] = Object.create(null);
-  const unescape = (part) => part.replace(/~1/g, "/").replace(/~0/g, "~");
-  for (const key of Object.keys(result.choices)) {
-    if (key.startsWith("/layers/") && !FUNDAMENTAL_SLOTS.some((slot) => key === layerChoiceKey(slot))) invalidShape(key, "unknown fundamental slot choice");
-    if (!key.startsWith("/settings/")) continue;
-    const separator = key.indexOf("/", "/settings/".length);
-    if (separator < 0) invalidShape(key, "setting choice must name a capability and setting");
-    const id = unescape(key.slice("/settings/".length, separator)), name = unescape(key.slice(separator + 1));
-    if (!isMaterializedCapabilityId(id) || settingChoiceKey(id, name) !== key) invalidShape(key, "noncanonical setting choice key");
-    if (Object.hasOwn(settings, id)) settings[id][name] = key;
-  }
-  return { ...result, status: problems.some((problem) => problem.code === "requirement-conflict") ? "conflict" : result.status,
-    requirements: allRequirements, candidates, capabilities, providers, settings, excludedSettings, problems,
-    providerInputs: { knowledge: soul.declaration.knowledge ?? null, stores: workspace?.declaration.knowledge?.stores ?? [] },
-    // Advertisements/adoption aliases are data, never wider-team consent.
-    advertisedTeams: soul.declaration.teams ?? [] };
-}

package/lib/portable-digest.mjs

@@ -1,105 +0,0 @@
-/** Explicit new digest domains. Existing v1 package/artifact functions remain
- * literal in their owning modules; this module never reinterprets legacy hashes. */
-import { createHash } from "node:crypto";
-import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, readdirSync, readlinkSync } from "node:fs";
-import { join } from "node:path";
-import { oatsError } from "./errors.mjs";
-import { canonicalJson, compareUtf8, dataLimits, decodeUtf8 } from "./portable-values.mjs";
-
-export const TREE_FORMAT = "oats.tree-exec.v1";
-export const PACKAGE_FORMAT = "oats.package-payload-exec.v1";
-export const JSON_FORMAT = "oats.json.v1";
-export const BYTES_FORMAT = "oats.bytes.v1";
-const digest = (format, data) => ({ format, value: `sha256-${createHash("sha256").update(data).digest("hex")}` });
-
-export function jsonIntegrity(value, options) { return digest(JSON_FORMAT, canonicalJson(value, options)); }
-export function bytesIntegrity(value) {
-  if (!Buffer.isBuffer(value) && !(value instanceof Uint8Array)) {
-    throw oatsError("invalid-declaration", "raw-byte integrity requires bytes");
-  }
-  return digest(BYTES_FORMAT, value);
-}
-export function validateIntegrity(value, formats = [TREE_FORMAT, PACKAGE_FORMAT, JSON_FORMAT, BYTES_FORMAT]) {
-  const invalid = () => { throw oatsError("invalid-artifact-reference", "expected explicit supported digest format and full SHA-256"); };
-  if (!value || typeof value !== "object" || Array.isArray(value)) invalid();
-  const prototype = Object.getPrototypeOf(value), fields = Object.getOwnPropertyDescriptors(value);
-  if ((prototype !== null && prototype !== Object.prototype) || Reflect.ownKeys(fields).length !== 2) invalid();
-  for (const key of ["format", "value"]) {
-    if (!Object.hasOwn(fields, key) || !Object.hasOwn(fields[key], "value") || !fields[key].enumerable) invalid();
-  }
-  if (!formats.includes(fields.format.value) || typeof fields.value.value !== "string"
-      || !/^sha256-[a-f0-9]{64}$/.test(fields.value.value)) invalid();
-  return value;
-}
-
-const sameFile = (a, b) => a.dev === b.dev && a.ino === b.ino && a.size === b.size
-  && a.mode === b.mode && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs;
-
-/** Domain NUL; then UTF-8-path-sorted records:
- * F || uint64(path bytes) || path || owner-exec byte || uint64(content bytes) || content
- * S || uint64(path bytes) || path || uint64(target bytes) || literal target
- * Length framing prevents the legacy binary record-boundary ambiguity.
- * Empty directories and non-owner-execute mode bits do not enter identity.
- * Containment remains the retention caller's responsibility; links aren't followed. */
-export function treeIntegrity(root, { format = TREE_FORMAT, ...options } = {}) {
-  if (![TREE_FORMAT, PACKAGE_FORMAT].includes(format)) {
-    throw oatsError("unsupported-wire-version", "unsupported portable tree digest format");
-  }
-  const limits = dataLimits({ maxBytes: 256 * 1024 * 1024, ...options });
-  const entries = [], hash = createHash("sha256");
-  let visited = 0, bytes = 0;
-  const account = (length) => {
-    bytes += length;
-    if (bytes > limits.maxBytes) throw oatsError("resource-limit", "artifact digest byte limit exceeded");
-  };
-  const length = (size) => {
-    const value = Buffer.alloc(8);
-    value.writeBigUInt64BE(BigInt(size));
-    return value;
-  };
-  const field = (data) => { account(8 + data.length); hash.update(length(data.length)); hash.update(data); };
-  const walk = (dir, parts) => {
-    if (parts.length > limits.maxDepth) throw oatsError("resource-limit", "artifact tree depth limit exceeded");
-    const names = readdirSync(dir, { encoding: "buffer" });
-    for (const raw of names) {
-      if (++visited > limits.maxEntries) throw oatsError("resource-limit", "artifact tree entry limit exceeded");
-      const name = decodeUtf8(raw, "artifact filename");
-      if (format === PACKAGE_FORMAT && (name === "node_modules" || (!parts.length && name === "oats-lock.json"))) continue;
-      const path = join(dir, name), relative = [...parts, name].join("/");
-      const stat = lstatSync(path);
-      if (stat.isSymbolicLink()) entries.push({ path, relative, stat, kind: "S" });
-      else if (stat.isDirectory()) walk(path, [...parts, name]);
-      else if (stat.isFile()) entries.push({ path, relative, stat, kind: "F" });
-      else throw oatsError("invalid-artifact", "unsupported artifact tree entry");
-    }
-  };
-  const rootStat = lstatSync(root);
-  if (!rootStat.isDirectory()) throw oatsError("invalid-artifact", "artifact digest root must be a real directory");
-  walk(root, []);
-  hash.update(`${format}\0`);
-  for (const entry of entries.sort((a, b) => compareUtf8(a.relative, b.relative))) {
-    account(1); hash.update(entry.kind); field(Buffer.from(entry.relative, "utf8"));
-    if (entry.kind === "S") {
-      const target = readlinkSync(entry.path, { encoding: "buffer" });
-      decodeUtf8(target, "artifact symlink target");
-      field(target);
-      continue;
-    }
-    const fd = openSync(entry.path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
-    try {
-      const before = fstatSync(fd);
-      if (!before.isFile() || !sameFile(entry.stat, before)) {
-        throw oatsError("integrity-drift", "artifact input changed during digest");
-      }
-      account(1 + 8 + before.size);
-      hash.update(Buffer.from([(before.mode & 0o100) !== 0 ? 1 : 0]));
-      hash.update(length(before.size));
-      const content = readFileSync(fd);
-      if (content.length !== before.size || !sameFile(before, fstatSync(fd))) {
-        throw oatsError("integrity-drift", "artifact input changed during digest");
-      }
-      hash.update(content);
-    } finally { closeSync(fd); }
-  }
-  return { format, value: `sha256-${hash.digest("hex")}` };
-}

package/lib/portable-identity.mjs

@@ -1,40 +0,0 @@
-/** Qualified identity value types, not a proof of hosting/provider ownership.
- * Discovery obtains facts from the authenticated host adapter, never repo YAML. */
-import { canonicalJson } from "./portable-values.mjs";
-import { jsonIntegrity } from "./portable-digest.mjs";
-import { parseLockedSource3, parseRepositorySource, portablePath } from "./source-spec.mjs";
-import { invalidShape, objectAt, stringAt } from "./portable-shape.mjs";
-
-export function validateRepositoryIdentity(value) {
-  canonicalJson(value, { maxBytes: 64 * 1024, maxDepth: 8, maxEntries: 64 });
-  objectAt(value, value?.kind === "provider-repository" ? ["kind", "provider", "host", "id"] : ["kind", "remote"], ["kind"]);
-  if (value.kind === "provider-repository") {
-    for (const name of ["provider", "host", "id"]) stringAt(value[name], `/${name}`);
-    if (!/^[a-z][a-z0-9.-]*$/.test(value.provider) || !/^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/.test(value.host)) {
-      invalidShape("", "provider and host identity must be canonical");
-    }
-  } else if (value.kind === "canonical-remote") {
-    stringAt(value.remote, "/remote");
-    if (parseRepositorySource(value.remote).normalized !== value.remote) invalidShape("/remote", "repository identity remote is not canonical");
-  } else invalidShape("/kind", "unsupported repository identity");
-  return value;
-}
-export function validateSoulIdentity(value) {
-  canonicalJson(value, { maxBytes: 64 * 1024, maxDepth: 12, maxEntries: 128 });
-  objectAt(value, value?.kind === "git-soul" ? ["kind", "repository", "exportPath"] : ["kind", "source", "exportPath"], ["kind", "exportPath"]);
-  if (value.kind === "git-soul") validateRepositoryIdentity(value.repository);
-  else if (value.kind === "local-soul") {
-    if (parseLockedSource3(value.source, ".").kind !== "path") invalidShape("/source", "local soul identity requires an explicit local source");
-  } else invalidShape("/kind", "unsupported soul identity");
-  portablePath(value.exportPath, { allowRoot: value.kind === "local-soul" });
-  return value;
-}
-export function validateWorkspaceIdentity(value) {
-  canonicalJson(value, { maxBytes: 64 * 1024, maxDepth: 12, maxEntries: 128 });
-  objectAt(value, ["repository", "path"], ["repository", "path"]);
-  validateRepositoryIdentity(value.repository);
-  if (value.path !== "oats-workspace.yaml") invalidShape("/path", "workspace identity names oats-workspace.yaml");
-  return value;
-}
-export function sameIdentity(a, b) { return canonicalJson(a) === canonicalJson(b); }
-export function soulIdentityKey(value) { validateSoulIdentity(value); return jsonIntegrity(value).value; }

package/lib/portable-lock.mjs

@@ -1,117 +0,0 @@
-/** Lock v3 is mutable input to future preparation, NEVER historical dispatch
- * authority. Existing v1/v2 readers and stores are not migrated by this module. */
-import { join } from "node:path";
-import { canonicalJson, parseStrictJson } from "./portable-values.mjs";
-import { JSON_FORMAT, jsonIntegrity, validateIntegrity } from "./portable-digest.mjs";
-import { validateArtifactSet, validateOrigin } from "./resolution-shape.mjs";
-import { objectAt, stringAt } from "./portable-shape.mjs";
-import { parseLockedSource3 } from "./source-spec.mjs";
-import { readPortableBytes } from "./portable-files.mjs";
-import { portableScope, withPortableStateWrite, writeGuardedPortableDocument } from "./portable-state.mjs";
-import { oatsError } from "./errors.mjs";
-
-const invalid = (message) => { throw oatsError("invalid-lock", message); };
-export const emptyLock3 = () => ({ lockfileVersion: 3, artifactSets: {}, selections: {} });
-export function requestKey3(request) {
-  canonicalJson(request);
-  objectAt(request, ["source", "path"], ["source", "path"]);
-  parseLockedSource3(request.source, request.path);
-  return jsonIntegrity(request).value;
-}
-export function artifactSetKey3(set) { validateArtifactSet(set); return jsonIntegrity(set).value; }
-function validateProblem(problem) {
-  objectAt(problem, ["code", "message", "origins", "target", "details"], ["code", "message", "origins"]);
-  stringAt(problem.code, "/freshness/problems/code"); stringAt(problem.message, "/freshness/problems/message");
-  if (!Array.isArray(problem.origins)) invalid("refresh problem origins must be an array");
-  problem.origins.forEach(validateOrigin);
-}
-
-export function validateLock3(lock) {
-  try {
-    canonicalJson(lock);
-    if (lock?.lockfileVersion === 1 || lock?.lockfileVersion === 2) {
-      throw oatsError("migration-required", "legacy lock requires its explicit evidence/migration reader; it is not lock v3");
-    }
-    objectAt(lock, ["lockfileVersion", "artifactSets", "selections"], ["lockfileVersion", "artifactSets", "selections"]);
-    if (lock.lockfileVersion !== 3) throw oatsError("unsupported-wire-version", "unsupported selection-lock version");
-    objectAt(lock.artifactSets, null, []); objectAt(lock.selections, null, []);
-    const indexes = new Map(), checked = new Set();
-    for (const [key, set] of Object.entries(lock.artifactSets)) {
-      if (artifactSetKey3(set) !== key) invalid("artifact-set key differs from its canonical content");
-      const requests = new Map();
-      for (const [id, pkg] of Object.entries(set.packages)) {
-        const request = jsonIntegrity({ source: pkg.source, path: pkg.path }).value;
-        if (!requests.has(request)) requests.set(request, []);
-        requests.get(request).push(id);
-      }
-      indexes.set(key, requests);
-    }
-    for (const [key, selection] of Object.entries(lock.selections)) {
-      objectAt(selection, ["request", "current", "available", "freshness"], ["request", "current", "available", "freshness"]);
-      if (requestKey3(selection.request) !== key) invalid("selection key differs from its normalized source request");
-      for (const name of ["current", "available"]) {
-        const selected = selection[name];
-        if (selected === null) continue;
-        stringAt(selected, `/selections/${name}`);
-        if (!Object.hasOwn(lock.artifactSets, selected)) invalid("selection references an absent artifact set");
-        const roots = indexes.get(selected).get(key);
-        if (roots?.length !== 1) invalid("selection has no unique root package matching its request");
-        if (checked.has(`${selected}:${key}`)) continue;
-        const set = lock.artifactSets[selected], reached = new Set([roots[0]]), pending = [roots[0]];
-        while (pending.length) {
-          for (const dependency of set.packages[pending.pop()].dependencies) {
-            if (!reached.has(dependency)) { reached.add(dependency); pending.push(dependency); }
-          }
-        }
-        if (reached.size !== Object.keys(set.packages).length) invalid("selected set includes packages outside the requested dependency closure");
-        for (const row of Object.values(set.capabilities)) if (row.origin.kind !== "package") invalid("package selection cannot smuggle a direct local capability");
-        checked.add(`${selected}:${key}`);
-      }
-      const freshness = selection.freshness;
-      objectAt(freshness, ["state", "observedAt", "problems"], ["state", "observedAt", "problems"]);
-      if (!["refreshed", "offline", "failed", "not-checked"].includes(freshness.state)) invalid("invalid freshness state");
-      if (freshness.observedAt !== null) {
-        stringAt(freshness.observedAt, "/freshness/observedAt");
-        const date = new Date(freshness.observedAt);
-        if (!Number.isFinite(date.getTime()) || date.toISOString() !== freshness.observedAt) invalid("observation timestamp must be canonical UTC ISO time");
-      }
-      if (freshness.state === "refreshed" && (freshness.observedAt === null || selection.available === null)) invalid("successful refresh needs an observed available set and timestamp");
-      if (!Array.isArray(freshness.problems)) invalid("refresh problems must be an array");
-      freshness.problems.forEach(validateProblem);
-    }
-    return lock;
-  } catch (error) {
-    if (["invalid-declaration", "invalid-source", "invalid-artifact-reference"].includes(error.code)) {
-      const failure = oatsError("invalid-lock", error.message); failure.cause = error; throw failure;
-    }
-    throw error;
-  }
-}
-
-/** Explicit scope only. Absent differs from empty-v1, unsupported or damaged.
- * Integrity is the CAS token, not software verification or executable consent. */
-export function readLock3(scope) {
-  const path = join(portableScope(scope), "oats-lock.json");
-  const bytes = readPortableBytes(path, { allowMissing: true, invalidCode: "invalid-lock" });
-  if (bytes === null) return { lock: null, integrity: null };
-  const lock = parseStrictJson(bytes);
-  validateLock3(lock);
-  if (!bytes.equals(Buffer.from(canonicalJson(lock)))) invalid("selection lock must use canonical JSON bytes");
-  return { lock, integrity: jsonIntegrity(lock) };
-}
-
-/** All new writers share a cooperative guard and compare the complete snapshot.
- * No implicit legacy migration, row merging, approval, tree cleanup or live cutover. */
-export function writeLock3(scope, expectedPreviousIntegrity, next) {
-  if (expectedPreviousIntegrity !== null) validateIntegrity(expectedPreviousIntegrity, [JSON_FORMAT]);
-  validateLock3(next);
-  return withPortableStateWrite(scope, (context) => {
-    const { deployment } = context;
-    const previous = readLock3(deployment);
-    if (canonicalJson(previous.integrity) !== canonicalJson(expectedPreviousIntegrity)) throw oatsError("selection-changed", "selection lock changed; repeat explicit preparation");
-    const integrity = jsonIntegrity(next);
-    if (canonicalJson(previous.integrity) === canonicalJson(integrity)) return { lock: next, integrity, status: "kept" };
-    writeGuardedPortableDocument(context, join(deployment, "oats-lock.json"), next, { absent: previous.lock === null });
-    return { lock: next, integrity, status: "written" };
-  });
-}

package/lib/portable-onboarding-request.mjs

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