@awebai/oats 0.25.9 → 0.27.0

package/lib/soul-constraints.mjs

@@ -1,40 +0,0 @@
-/** Source-derived hard field constraints, shared by preparation and verification.
- * No defaults are resolved here and no source/artifact is acquired. */
-import { invalidShape, pointerKey } from "./portable-shape.mjs";
-import { validateRepoAnchor } from "./source-spec.mjs";
-import { FUNDAMENTAL_SLOTS } from "./portable-policy.mjs";
-
-export const capabilityChoiceKey = (id) => `/capabilities/${pointerKey(id)}`;
-export const settingChoiceKey = (id, name) => `/settings/${pointerKey(id)}/${pointerKey(name)}`;
-export const layerChoiceKey = (slot) => `/layers/${slot}`;
-
-/** A repo: relation belongs to the declaring source, not the consumer's cwd or
- * another authority's identically spelled relative path. Operator inputs need
- * an explicit source context because their origin is not a repository document. */
-export function sourceSelectionValue(id, parsed, pointer, sourceContext) {
-  const source = parsed.sources[`${pointer}/source`];
-  if (!source) invalidShape(`${pointer}/source`, "missing normalized selection source");
-  if (source.kind !== "repo") return { capability: id, source };
-  const anchor = sourceContext ?? parsed.origins[`${pointer}/source`]?.document;
-  if (!anchor || typeof anchor.source !== "string") invalidShape(`${pointer}/source`, "repo source needs an explicit declaring repository snapshot", "needs-configuration");
-  const snapshot = validateRepoAnchor({ source: anchor.source, revision: anchor.revision });
-  return { capability: id, source: { ...source, anchor: snapshot } };
-}
-
-export function soulConstraints(parsed) {
-  const result = [], source = parsed.declaration.requires ?? {};
-  const origin = (pointer) => ({ ...parsed.origins[pointer], kind: "soul-requirement" });
-  const selection = (id, item, pointer, key) => {
-    result.push({ key, kind: "equals", value: sourceSelectionValue(id, parsed, pointer), origin: origin(pointer) });
-    for (const [name, value] of Object.entries(item.settings ?? {})) {
-      result.push({ key: settingChoiceKey(id, name), kind: "equals", value, origin: origin(`${pointer}/settings/${pointerKey(name)}`) });
-    }
-  };
-  for (const [id, item] of Object.entries(source.capabilities ?? {})) selection(id, item, `/requires/capabilities/${pointerKey(id)}`, capabilityChoiceKey(id));
-  for (const slot of FUNDAMENTAL_SLOTS) {
-    if (!Object.hasOwn(source, slot)) continue;
-    if (source[slot] === "any") result.push({ key: layerChoiceKey(slot), kind: "required", origin: origin(`/requires/${slot}`) });
-    else selection(source[slot].capability, source[slot], `/requires/${slot}`, layerChoiceKey(slot));
-  }
-  return result;
-}

package/lib/source-projection.mjs

@@ -1,84 +0,0 @@
-/** One guarded filesystem writer for Git and explicit local source projections.
- * Source paths cannot introduce write-parent or leaf aliases before rejection. */
-import { chmodSync, constants, copyFileSync, lstatSync, mkdirSync, readdirSync, realpathSync, symlinkSync, writeFileSync } from "node:fs";
-import { isAbsolute, join } from "node:path";
-import { decodeUtf8 } from "./portable-values.mjs";
-import { portablePath } from "./source-spec.mjs";
-import { assertRetainableTree } from "./capability-artifacts.mjs";
-import { oatsError } from "./errors.mjs";
-
-export function validateProjectionPath(path, platform = process.platform) {
-  portablePath(path);
-  if (platform === "win32" && path.split("/").some((part) => /[:<>"|?*\x00-\x1f]/.test(part) || /[ .]$/.test(part)
-      || /^(?:con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(?:\.|$)/i.test(part))) throw oatsError("source-incomplete", "source path is not an ordinary filename on this host");
-  return path;
-}
-
-export function createSourceProjection(destination) {
-  if (typeof destination !== "string" || !isAbsolute(destination)) throw oatsError("invalid-source", "source projection destination must be explicit and absolute");
-  mkdirSync(destination, { mode: 0o700 });
-  const boundary = realpathSync(destination), directories = new Set([""]), expected = new Map(), directoryModes = new Map();
-  let finished = false;
-  const active = () => { if (finished) throw oatsError("source-incomplete", "source projection is already finalized"); };
-  const ensureDirectory = (parts) => {
-    let current = boundary, relative = "";
-    for (const part of parts) {
-      relative = relative ? `${relative}/${part}` : part; current = join(current, part);
-      let existed = false;
-      try { mkdirSync(current, { mode: 0o700 }); }
-      catch (error) { if (error.code !== "EEXIST") throw error; existed = true; }
-      if (!lstatSync(current).isDirectory() || (existed && !directories.has(relative))) throw oatsError("artifact-not-contained", "projection parent is a link or aliases another source path");
-      directories.add(relative);
-    }
-    return current;
-  };
-  const target = (path, kind) => {
-    active(); validateProjectionPath(path);
-    if (expected.has(path) || directories.has(path)) throw oatsError("invalid-source", "source projection repeats a path");
-    const parts = path.split("/"), parent = ensureDirectory(parts.slice(0, -1));
-    expected.set(path, kind);
-    return join(parent, parts.at(-1));
-  };
-  const modeOf = (path, mode) => {
-    chmodSync(path, mode);
-    if ((lstatSync(path).mode & 0o100) !== (mode & 0o100)) throw oatsError("source-incomplete", "host filesystem cannot retain the source owner-execute flag");
-  };
-  return {
-    directory(path, mode) {
-      active(); validateProjectionPath(path);
-      if (expected.has(path)) throw oatsError("invalid-source", "source projection path changes kind");
-      const directory = ensureDirectory(path.split("/"));
-      if (mode !== undefined) directoryModes.set(directory, mode);
-    },
-    file(path, bytes, mode) {
-      const file = target(path, "file"); writeFileSync(file, bytes, { flag: "wx", mode }); modeOf(file, mode);
-    },
-    copyFile(path, source, mode) {
-      const file = target(path, "file"); copyFileSync(source, file, constants.COPYFILE_EXCL); modeOf(file, mode);
-    },
-    link(path, value) { symlinkSync(value, target(path, "link")); },
-    finish() {
-      active();
-      const seenDirectories = new Set([""]);
-      const inspect = (directory, prefix = "") => {
-        for (const raw of readdirSync(directory, { encoding: "buffer" })) {
-          const name = decodeUtf8(raw), path = prefix ? `${prefix}/${name}` : name, target = join(directory, name), stat = lstatSync(target);
-          if (stat.isDirectory()) {
-            if (!directories.has(path)) throw oatsError("source-incomplete", "host projection directory spelling differs from source");
-            seenDirectories.add(path); inspect(target, path);
-          } else {
-            const kind = expected.get(path);
-            if (!kind || (kind === "link" ? !stat.isSymbolicLink() : !stat.isFile())) throw oatsError("source-incomplete", "host projection paths differ from source");
-            expected.delete(path);
-          }
-        }
-      };
-      inspect(boundary);
-      if (expected.size || seenDirectories.size !== directories.size) throw oatsError("source-incomplete", "host filesystem did not retain every source path");
-      assertRetainableTree(boundary);
-      for (const [path, mode] of [...directoryModes].sort((a, b) => b[0].length - a[0].length)) chmodSync(path, mode);
-      finished = true;
-      return boundary;
-    },
-  };
-}

package/lib/source-spec.mjs

@@ -1,189 +0,0 @@
-/** Portable source grammar. Pure normalization only: no cwd/HOME inference,
- * filesystem access, repository identity claims or executable approval.
- * Legacy lock readers retain their original interpretation in capability-provenance.mjs. */
-import { isAbsolute, resolve } from "node:path";
-import { oatsError } from "./errors.mjs";
-import { canonicalJson, scalarString } from "./portable-values.mjs";
-
-const refuse = (message) => { throw oatsError("invalid-source", message); };
-const text = (value) => {
-  scalarString(value, "source");
-  if (!value || value.length > 8192 || value.trim() !== value || /[\x00-\x1f\x7f]/.test(value)) refuse("invalid source text");
-  return value;
-};
-export function portablePath(value, { allowRoot = false } = {}) {
-  scalarString(value, "source path");
-  if (allowRoot && value === ".") return value;
-  if (!value || value.includes("\\") || value.includes("\0") || /^[A-Za-z]:/.test(value)
-      || value.split("/").some((part) => !part || part === "." || part === "..")) {
-    throw oatsError("path-escape", "expected a contained canonical repository-relative path");
-  }
-  return value;
-}
-export function revisionSelector(value) {
-  text(value);
-  if (value === "@" || value.startsWith("-") || value.endsWith(".") || value.includes("..")
-      || value.includes("@{") || /[\s~^:?*\[\\]/.test(value)
-      || value.split("/").some((part) => !part || part.startsWith(".") || part.endsWith(".lock"))) {
-    refuse("invalid Git revision selector");
-  }
-  return value;
-}
-
-function splitGit(body) {
-  // Locate the repository-path start before looking for the selector delimiter.
-  // SSH's user@host is authority; refs/heads/topic is one selector, not a URL.
-  let start;
-  const scheme = /^[a-z][a-z0-9+.-]*:\/\//i.exec(body);
-  if (scheme) {
-    start = body.indexOf("/", scheme[0].length);
-    if (start < 0) refuse("Git repository source needs a path");
-  } else if (/^[^/@:]+@[^/:]+:/.test(body)) start = body.indexOf(":") + 1;
-  else {
-    start = body.indexOf("/");
-    if (start < 0) refuse("Git source needs host and repository path");
-  }
-  const positions = [];
-  for (let i = start; i < body.length; i++) if (body[i] === "@") positions.push(i);
-  if (positions.length > 1) refuse("ambiguous Git selector delimiter; use an unambiguous repository locator");
-  if (!positions.length) return { repository: body, selector: undefined };
-  const at = positions[0];
-  return { repository: body.slice(0, at), selector: revisionSelector(body.slice(at + 1)) };
-}
-function remoteUrl(repository, { allowLocalGit = false } = {}) {
-  let spelling = repository, shorthand = false, scp = null;
-  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(spelling)) {
-    scp = /^([^/@:]+)@([^/:]+):(.+)$/.exec(spelling);
-    shorthand = !scp;
-    spelling = scp ? `ssh://${scp[1]}@${scp[2]}${scp[3].startsWith("/") ? "" : "/"}${scp[3]}` : `https://${spelling}`;
-  }
-  if (/\s|\\/.test(spelling)) refuse("invalid Git repository URL");
-  // Reject hidden path rewriting rather than letting URL dot normalization pick
-  // another repository. Percent-encoded separators are equally ambiguous.
-  const pathStart = spelling.indexOf("/", spelling.indexOf("://") + 3);
-  const rawPath = spelling.slice(pathStart);
-  if (pathStart < 0 || rawPath.split("/").slice(1).some((part) => {
-    let decoded;
-    try { decoded = decodeURIComponent(part); } catch { return true; }
-    return !part || decoded === "." || decoded === ".." || /[/\\\x00-\x1f\x7f]/.test(decoded);
-  })) refuse("Git repository path is not canonical");
-  let url;
-  try { url = new URL(spelling); } catch { refuse("invalid Git repository URL"); }
-  if (!["https:", "http:", "ssh:", "git:", ...(allowLocalGit ? ["file:"] : [])].includes(url.protocol)) {
-    refuse("unsupported Git transport");
-  }
-  if (url.search || url.hash || url.password || (url.username && url.protocol !== "ssh:")) {
-    refuse("Git repository locator must not contain credentials, query or fragment");
-  }
-  if (url.protocol !== "file:" && !url.hostname) refuse("Git repository needs a host");
-  if (url.hostname === "github.com" && url.pathname.split("/").filter(Boolean).length !== 2) {
-    refuse("GitHub repository locator needs owner and repository");
-  }
-  // SCP's host:path is home-relative; ssh://host/path is absolute. Keep the SCP
-  // spelling rather than changing the path that Git sends to git-upload-pack.
-  if (scp) return `${scp[1]}@${url.hostname}:${scp[3]}`;
-  if (shorthand && !url.pathname.endsWith(".git")) url.pathname += ".git";
-  return url.href;
-}
-function gitParts(spec, options) {
-  text(spec);
-  if (!spec.startsWith("git:")) refuse("expected an explicit git: source");
-  const body = spec.slice(4), hash = body.indexOf("#");
-  if (hash >= 0 && body.indexOf("#", hash + 1) >= 0) refuse("source has multiple package fragments");
-  const fragment = hash < 0 ? undefined : body.slice(hash + 1);
-  const split = splitGit(hash < 0 ? body : body.slice(0, hash));
-  return { ...split, url: remoteUrl(split.repository, options), fragment };
-}
-
-/** Repository/import/knowledge locators never acquire a package-root default. */
-export function parseRepositorySource(spec, options) {
-  const parsed = gitParts(spec, options);
-  if (parsed.selector !== undefined || parsed.fragment !== undefined) {
-    refuse("repository locator keeps revision and exported path in separate fields");
-  }
-  return { kind: "git", url: parsed.url, normalized: `git:${parsed.url}` };
-}
-
-export function parsePortableSource(spec, { localBase, allowLocalPaths = false } = {}) {
-  text(spec);
-  if (spec.startsWith("repo:")) return { kind: "repo", path: portablePath(spec.slice(5), { allowRoot: true }) };
-  if (spec.startsWith("path:")) {
-    const source = spec.slice(5);
-    if (!source || source.startsWith("~") || source.includes("#")) refuse("local source needs an explicit path, not HOME or a fragment");
-    if (!allowLocalPaths) refuse("local inputs require explicit local adoption authorization");
-    if (localBase !== undefined && !isAbsolute(localBase)) refuse("local source base must be absolute");
-    if (!isAbsolute(source) && localBase === undefined) refuse("relative path: source needs an explicit local base");
-    const path = isAbsolute(source) ? resolve(source) : resolve(localBase, source);
-    return { kind: "path", source: `path:${path}`, path: ".", localPath: path, portable: false };
-  }
-  const parsed = gitParts(spec);
-  if (parsed.selector === undefined) refuse("portable Git capability source requires a revision selector");
-  const path = parsed.fragment === undefined ? "oats-package"
-    : parsed.fragment === "" ? "." : portablePath(parsed.fragment, { allowRoot: true });
-  return { kind: "git", source: `git:${parsed.url}@${parsed.selector}`, url: parsed.url,
-    selector: parsed.selector, path, portable: true };
-}
-
-/** Package dependency inputs retain existing CLI conveniences, but never infer
- * an ambient local base or allow an unpinned Git dependency. Soul requirements
- * continue to use parsePortableSource and cannot borrow catalog nicknames. */
-export function parsePackageDependency3(spec, { localBase, allowLocalPaths = false } = {}) {
-  text(spec);
-  if (spec.startsWith("repo:") || spec.startsWith("path:")) return parsePortableSource(spec, { localBase, allowLocalPaths });
-  if (spec.startsWith(".") || spec.startsWith("/") || spec.startsWith("~")) return parsePortableSource(`path:${spec}`, { localBase, allowLocalPaths });
-  if (spec.startsWith("git:") && !spec.startsWith("git://")) return parsePortableSource(spec);
-  if (/^(https?:\/\/|ssh:\/\/|git:\/\/|git@)/.test(spec)) return parsePortableSource(`git:${spec}`);
-  const catalog = /^(?:catalog:)?([a-z0-9][a-z0-9._-]*)(?:@([^\s#]+))?$/.exec(spec);
-  if (!catalog) refuse("invalid package dependency source");
-  const source = `catalog:${catalog[1]}${catalog[2] ? `@${catalog[2]}` : ""}`;
-  parseLockedSource3(source, "oats-package");
-  return { kind: "catalog", source, id: catalog[1], ...(catalog[2] ? { selector: catalog[2] } : {}) };
-}
-
-/** Repository-relative selections carry the exact declaring observation. */
-export function validateRepoAnchor(anchor) {
-  canonicalJson(anchor);
-  if (!anchor || Object.keys(anchor).sort().join(",") !== "revision,source") refuse("invalid repository snapshot anchor");
-  if (typeof anchor.source === "string" && anchor.source.startsWith("path:")) {
-    parseLockedSource3(anchor.source, ".");
-    if (anchor.revision !== "local") refuse("local source anchor requires a local observation");
-  } else if (parseRepositorySource(anchor.source).normalized !== anchor.source || typeof anchor.revision !== "string" || !/^[a-f0-9]{40}$/.test(anchor.revision)) {
-    refuse("repository source anchor requires its exact observation");
-  }
-  return anchor;
-}
-
-/** Normalized choice values cannot disagree with their own source/path/url fields.
- * This is still data validation, not acquisition or local-path authorization. */
-export function validateSelectionSource(value) {
-  const encoded = canonicalJson(value);
-  let expected;
-  if (value?.kind === "git") {
-    portablePath(value.path, { allowRoot: true });
-    expected = parsePortableSource(`${value.source}#${value.path}`);
-  } else if (value?.kind === "path") expected = parsePortableSource(value.source, { allowLocalPaths: true });
-  else if (value?.kind === "repo") expected = { ...parsePortableSource(`repo:${value.path}`), anchor: validateRepoAnchor(value.anchor) };
-  else refuse("invalid normalized selection source");
-  if (canonicalJson(expected) !== encoded) refuse("normalized selection source fields disagree");
-  return value;
-}
-
-/** New-format locked sources already carry a canonical URL and a separate path.
- * Reading must not repair noncanonical persisted values or inherit cwd defaults. */
-export function parseLockedSource3(source, path) {
-  text(source); portablePath(path, { allowRoot: true });
-  if (source.startsWith("path:")) {
-    const local = source.slice(5);
-    if (!isAbsolute(local) || local.includes("#") || resolve(local) !== local || path !== ".") refuse("invalid canonical local lock source");
-    return { kind: "path", source, path, localPath: local, portable: false };
-  }
-  if (source.startsWith("catalog:")) {
-    const entry = /^catalog:([a-z0-9][a-z0-9._-]*)(?:@([^\s#]+))?$/.exec(source);
-    if (!entry) refuse("invalid canonical catalog lock source");
-    return { kind: "catalog", source, path, id: entry[1], selector: entry[2] };
-  }
-  const parsed = gitParts(source, { allowLocalGit: true });
-  if (parsed.fragment !== undefined || parsed.selector === undefined
-      || source !== `git:${parsed.url}@${parsed.selector}`) refuse("invalid canonical Git lock source");
-  return { kind: "git", source, path, url: parsed.url, selector: parsed.selector, portable: true };
-}

package/lib/workspace-definition.mjs

@@ -1,126 +0,0 @@
-/** Portable workspace/member/import declarations. Data validation only;
- * repository identity, reciprocal admission and fetching belong to discovery. */
-import { parseConfigData } from "./config-data.mjs";
-import { canonicalJson } from "./portable-values.mjs";
-import { parseRepositorySource, portablePath, revisionSelector } from "./source-spec.mjs";
-import { invalidShape, objectAt, pointerKey, stringAt, versionAt } from "./portable-shape.mjs";
-import { FUNDAMENTAL_SLOTS, validatePolicyChoices, validateProviderDeclaration } from "./portable-policy.mjs";
-import { isMaterializedCapabilityId } from "./capability-provenance.mjs";
-import { oatsError } from "./errors.mjs";
-
-const ALIAS = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
-const SOUL_ALIAS = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-function arrayAt(value, pointer) { if (!Array.isArray(value)) invalidShape(pointer, "expected array"); return value; }
-function repositoryAt(value, pointer, { revisionRequired = false, path = false } = {}) {
-  objectAt(value, ["source", "revision", ...(path ? ["path"] : [])], ["source", ...(revisionRequired ? ["revision"] : [])], pointer);
-  const source = parseRepositorySource(value.source);
-  if (Object.hasOwn(value, "revision")) revisionSelector(value.revision);
-  if (path && Object.hasOwn(value, "path")) portablePath(value.path);
-  return { ...value, source: source.normalized };
-}
-function duplicate(label, first, current, origins) {
-  throw oatsError("requirement-conflict", `duplicate ${label}`, [origins[first] ?? { pointer: first }, origins[current] ?? { pointer: current }]);
-}
-
-/** Identical four-field source reference for standalone and workspace imports.
- * Normalization is not verified upstream identity or an enrollment operation. */
-export function parseSoulImport(input, { pointer = "", origins = {}, origin = null, localBase, allowLocalPaths = false } = {}) {
-  canonicalJson(input, { maxBytes: 256 * 1024, maxDepth: 32, maxEntries: 10_000 });
-  const value = objectAt(input, ["source", "soul", "revision", "alias", "adoption"], ["source", "soul", "revision", "alias"], pointer);
-  const source = parseRepositorySource(value.source);
-  portablePath(value.soul); revisionSelector(value.revision);
-  stringAt(value.alias, `${pointer}/alias`, { pattern: SOUL_ALIAS });
-  const sources = Object.create(null);
-  if (Object.hasOwn(value, "adoption")) {
-    const adoption = objectAt(value.adoption, ["teamAliases", "providers", "bindings"], [], `${pointer}/adoption`);
-    if (Object.hasOwn(adoption, "teamAliases")) {
-      objectAt(adoption.teamAliases, null, [], `${pointer}/adoption/teamAliases`);
-      for (const [name, target] of Object.entries(adoption.teamAliases)) {
-        stringAt(name, `${pointer}/adoption/teamAliases`, { pattern: ALIAS });
-        stringAt(target, `${pointer}/adoption/teamAliases/${pointerKey(name)}`, { pattern: ALIAS });
-      }
-    }
-    if (Object.hasOwn(adoption, "providers")) {
-      objectAt(adoption.providers, FUNDAMENTAL_SLOTS, [], `${pointer}/adoption/providers`);
-      Object.assign(sources, validatePolicyChoices(adoption.providers, {
-        pointer: `${pointer}/adoption/providers`, origins, origin, localBase, allowLocalPaths,
-      }));
-    }
-    if (Object.hasOwn(adoption, "bindings")) objectAt(adoption.bindings, null, [], `${pointer}/adoption/bindings`);
-  }
-  return { reference: { ...value, source: source.normalized }, sources };
-}
-
-export function parseWorkspaceDefinition(input, { origin = null, localBase, allowLocalPaths = false, limits } = {}) {
-  const parsed = parseConfigData(input, { origin, limits });
-  const value = objectAt(parsed.value, ["schemaVersion", "name", "members", "defaults", "knowledge", "teams", "catalogs", "imports"], ["schemaVersion", "name"]);
-  versionAt(value.schemaVersion); stringAt(value.name, "/name");
-  const sources = Object.create(null), members = [], imports = [], catalogs = [];
-  if (Object.hasOwn(value, "defaults")) Object.assign(sources, validatePolicyChoices(value.defaults, {
-    pointer: "/defaults", origins: parsed.origins, origin, localBase, allowLocalPaths,
-  }));
-  if (Object.hasOwn(value, "members")) {
-    const seen = new Map();
-    arrayAt(value.members, "/members").forEach((entry, index) => {
-      const at = `/members/${index}`, member = repositoryAt(entry, at);
-      if (seen.has(member.source)) duplicate("member repository", seen.get(member.source), at, parsed.origins);
-      seen.set(member.source, at); members.push(member);
-    });
-  }
-  if (Object.hasOwn(value, "knowledge")) {
-    objectAt(value.knowledge, ["stores"], ["stores"], "/knowledge");
-    arrayAt(value.knowledge.stores, "/knowledge/stores").forEach((store, index) => validateProviderDeclaration(store, `/knowledge/stores/${index}`));
-  }
-  if (Object.hasOwn(value, "teams")) {
-    objectAt(value.teams, null, [], "/teams");
-    for (const [alias, team] of Object.entries(value.teams)) {
-      const at = `/teams/${pointerKey(alias)}`;
-      stringAt(alias, at, { pattern: ALIAS });
-      if (alias === "private") { if (team !== "per-human") invalidShape(at, "private team floor must be per-human"); continue; }
-      objectAt(team, ["provider", "id"], ["provider", "id"], at);
-      if (!isMaterializedCapabilityId(team.provider)) invalidShape(`${at}/provider`, "invalid messaging provider identity");
-      stringAt(team.id, `${at}/id`);
-    }
-  }
-  if (Object.hasOwn(value, "catalogs")) {
-    arrayAt(value.catalogs, "/catalogs").forEach((entry, index) => catalogs.push(repositoryAt(entry, `/catalogs/${index}`, { path: true })));
-  }
-  if (Object.hasOwn(value, "imports")) {
-    const seen = new Map();
-    arrayAt(value.imports, "/imports").forEach((entry, index) => {
-      const at = `/imports/${index}`;
-      const imported = parseSoulImport(entry, { pointer: at, origins: parsed.origins, origin, localBase, allowLocalPaths });
-      if (seen.has(imported.reference.alias)) duplicate("import alias", seen.get(imported.reference.alias), at, parsed.origins);
-      seen.set(imported.reference.alias, at);
-      Object.assign(sources, imported.sources); imports.push(imported.reference);
-    });
-  }
-  return { declaration: value, sources, members, imports, catalogs, origins: parsed.origins, integrity: parsed.integrity };
-}
-
-export function parseMemberExports(input, { origin = null, limits } = {}) {
-  const parsed = parseConfigData(input, { origin, limits });
-  const value = objectAt(parsed.value, ["schemaVersion", "workspace", "exports"], ["schemaVersion", "exports"]);
-  versionAt(value.schemaVersion);
-  const workspace = Object.hasOwn(value, "workspace") ? repositoryAt(value.workspace, "/workspace") : null;
-  const exports = objectAt(value.exports, ["souls", "packages", "knowledge"], [], "/exports");
-  for (const kind of ["souls", "packages"]) {
-    if (!Object.hasOwn(exports, kind)) continue;
-    const seen = new Map();
-    arrayAt(exports[kind], `/exports/${kind}`).forEach((entry, index) => {
-      const at = `/exports/${kind}/${index}`;
-      objectAt(entry, kind === "souls" ? ["path", "definition", "description"] : ["path", "description"],
-        kind === "souls" ? ["path", "definition"] : ["path"], at);
-      portablePath(entry.path, { allowRoot: kind === "packages" });
-      if (seen.has(entry.path)) duplicate(`${kind} export path`, seen.get(entry.path), at, parsed.origins);
-      seen.set(entry.path, at);
-      if (kind === "souls") {
-        portablePath(entry.definition);
-        if (!entry.definition.startsWith(`${entry.path}/`)) invalidShape(`${at}/definition`, "definition must be inside its exported soul path");
-      }
-      if (Object.hasOwn(entry, "description")) stringAt(entry.description, `${at}/description`, { empty: true });
-    });
-  }
-  if (Object.hasOwn(exports, "knowledge")) arrayAt(exports.knowledge, "/exports/knowledge").forEach((store, index) => validateProviderDeclaration(store, `/exports/knowledge/${index}`));
-  return { declaration: value, workspace, exports, origins: parsed.origins, integrity: parsed.integrity };
-}

package/lib/workspace-discovery.mjs

@@ -1,146 +0,0 @@
-/** Reciprocal workspace discovery and by-reference soul imports through one
- * repository transaction. Membership is observed eligibility, not enrollment. */
-import { canonicalJson, compareUtf8, freezeJson } from "./portable-values.mjs";
-import { objectAt, pointerKey } from "./portable-shape.mjs";
-import { sameIdentity } from "./portable-identity.mjs";
-import { validateOrigin } from "./resolution-shape.mjs";
-import { parseMemberExports, parseSoulImport, parseWorkspaceDefinition } from "./workspace-definition.mjs";
-import { parsePortableSoul } from "./portable-soul.mjs";
-import { oatsError } from "./errors.mjs";
-
-function declaredOrigin(parsed, pointer, kind) {
-  const result = { ...parsed.origins[pointer], kind };
-  validateOrigin(result); return result;
-}
-function minimumRoots(paths) {
-  const roots = new Set(paths);
-  if (roots.has(".")) return ["."];
-  return [...roots].filter((path) => {
-    for (let at = path.indexOf("/"); at >= 0; at = path.indexOf("/", at + 1)) if (roots.has(path.slice(0, at))) return false;
-    return true;
-  }).sort(compareUtf8);
-}
-
-export function createWorkspaceDiscovery(transaction) {
-  const workspaces = new WeakMap();
-  return {
-    readWorkspace(request) {
-      canonicalJson(request);
-      objectAt(request, ["source", "revision", "origin", "expectedIdentity"], ["source", "origin"]);
-      const observation = transaction.observe(request.source, request);
-      const document = transaction.readFile(observation, "oats-workspace.yaml");
-      const parsed = parseWorkspaceDefinition(document.bytes, { origin: document.origin });
-      const identity = { repository: observation.source.identity, path: "oats-workspace.yaml" };
-      const view = freezeJson({ schemaVersion: 1, identity, source: observation.source, parsed, accessContextKey: observation.accessContextKey });
-      workspaces.set(view, { observation, parsed, identity, document: document.origin });
-      return view;
-    },
-
-    checkMember(view, request) {
-      const workspace = workspaces.get(view);
-      if (!workspace) throw oatsError("invalid-source", "workspace view was not issued by this discovery transaction");
-      canonicalJson(request);
-      objectAt(request, ["source", "origin", "expectedIdentity"], ["source", "origin"]);
-      validateOrigin(request.origin);
-      const evidence = [], problems = [];
-      let member = null;
-      const result = (status) => freezeJson({ schemaVersion: 1, status, workspace: { identity: workspace.identity,
-        revision: workspace.observation.source.commit, document: workspace.document }, member, evidence, problems });
-      const problem = (code, message, origins) => problems.push({ code, message, origins });
-      const unavailable = (error, origins) => {
-        problem(error.code ?? "source-unavailable", error.message, origins);
-        return result(["source-identity-unresolved", "source-identity-change"].includes(error.code) ? "identity-unresolved" : "unavailable");
-      };
-      let candidate;
-      try { candidate = transaction.identify(request.source, request); }
-      catch (error) { return unavailable(error, [request.origin]); }
-      if (candidate.accessContextKey !== view.accessContextKey) {
-        problem("source-access-context-change", "membership observations use different access contexts", [request.origin]);
-        return result("unavailable");
-      }
-      const entries = workspace.parsed.members;
-      let index = entries.findIndex((entry) => entry.source === candidate.source);
-      if (index < 0) {
-        const unresolved = [];
-        for (const [at, entry] of entries.entries()) {
-          try {
-            const listed = transaction.identify(entry.source);
-            if (listed.accessContextKey !== view.accessContextKey) throw oatsError("source-access-context-change", "allowlist identity has a different access context");
-            if (sameIdentity(listed.identity, candidate.identity)) { index = at; break; }
-          } catch (error) { unresolved.push({ error, origin: declaredOrigin(workspace.parsed, `/members/${at}`, "workspace-admission") }); }
-        }
-        if (index < 0 && unresolved.length) return unavailable(unresolved[0].error, [unresolved[0].origin]);
-      }
-      if (index < 0) {
-        problem("workspace-disallows-member", "repository is not admitted by this workspace", [request.origin]);
-        return result("not-member");
-      }
-      const entry = entries[index], admission = declaredOrigin(workspace.parsed, `/members/${index}`, "workspace-admission");
-      evidence.push(admission);
-      try {
-        // The workspace's declared selector governs admission evidence, not the
-        // caller's work-tree branch or an arbitrary fork's copied descriptor.
-        const observation = transaction.observe(entry.source, { ...(entry.revision === undefined ? {} : { revision: entry.revision }),
-          origin: admission, expectedIdentity: candidate.identity });
-        if (observation.accessContextKey !== view.accessContextKey) throw oatsError("source-access-context-change", "member observation has a different access context");
-        if (!sameIdentity(observation.source.identity, candidate.identity)) throw oatsError("source-identity-change", "admission observed a different member identity");
-        const document = transaction.readFile(observation, "oats.yaml", { optional: true });
-        member = { identity: observation.source.identity, revision: observation.source.commit, document: document?.origin ?? null };
-        if (!document) {
-          problem("member-backlink-missing", "admitted repository has no member descriptor", [admission]);
-          return result("not-member");
-        }
-        const parsed = parseMemberExports(document.bytes, { origin: document.origin });
-        if (!parsed.workspace) {
-          problem("member-backlink-missing", "repository exports do not declare workspace membership", [admission]);
-          return result("not-member");
-        }
-        const backlink = declaredOrigin(parsed, "/workspace", "member-backlink"); evidence.push(backlink);
-        const target = transaction.identify(parsed.workspace.source);
-        if (target.accessContextKey !== view.accessContextKey) throw oatsError("source-access-context-change", "backlink identity has a different access context");
-        if (!sameIdentity(target.identity, workspace.identity.repository)) {
-          problem("member-backlink-mismatch", "member points to a different workspace identity", [admission, backlink]);
-          return result("not-member");
-        }
-        const linkedWorkspace = transaction.observe(parsed.workspace.source, { ...(parsed.workspace.revision === undefined ? {} : { revision: parsed.workspace.revision }),
-          origin: backlink, expectedIdentity: workspace.identity.repository });
-        if (linkedWorkspace.accessContextKey !== view.accessContextKey) throw oatsError("source-access-context-change", "backlink observation has a different access context");
-        if (!sameIdentity(linkedWorkspace.source.identity, workspace.identity.repository)) throw oatsError("source-identity-change", "backlink observed a different workspace identity");
-        if (linkedWorkspace.source.commit !== workspace.observation.source.commit) {
-          problem("workspace-observation-mismatch", "backlink resolves a different workspace revision; choose matching observations", [admission, backlink]);
-          return result("stale");
-        }
-        return result("eligible");
-      } catch (error) { return unavailable(error, evidence); }
-    },
-
-    importSoul(reference, { origin, expectedIdentity } = {}) {
-      validateOrigin(origin);
-      const parsedImport = parseSoulImport(reference, { pointer: origin.pointer, origin: origin.document });
-      const imported = parsedImport.reference;
-      const importOrigins = Object.create(null);
-      const mark = (value, pointer) => {
-        importOrigins[pointer] = { document: origin.document, pointer };
-        if (value && typeof value === "object") for (const [key, child] of Object.entries(value)) mark(child, `${pointer}/${pointerKey(key)}`);
-      };
-      mark(reference, origin.pointer);
-      const observation = transaction.observe(imported.source, { revision: imported.revision, origin, ...(expectedIdentity === undefined ? {} : { expectedIdentity }) });
-      const index = transaction.readFile(observation, "oats.yaml", { optional: true });
-      if (!index) throw oatsError("export-not-found", "source repository has no advertised soul export index");
-      const exports = parseMemberExports(index.bytes, { origin: index.origin });
-      const at = (exports.exports.souls ?? []).findIndex((entry) => entry.path === imported.soul);
-      if (at < 0) throw oatsError("export-not-found", "requested soul path is not advertised by this source revision");
-      const exported = exports.exports.souls[at], definition = transaction.readFile(observation, exported.definition);
-      const soul = parsePortableSoul(definition.bytes, { origin: definition.origin });
-      const roots = [imported.soul, ...(soul.declaration.resources ?? [])];
-      for (const [pointer, source] of Object.entries(soul.sources)) if (pointer.startsWith("/requires/") && source.kind === "repo") roots.push(source.path);
-      // The publisher's backlink is parsed as data, never followed as an adopter
-      // workspace or membership requirement. No adopter-owned soul is written.
-      const identity = { kind: "git-soul", repository: observation.source.identity, exportPath: imported.soul };
-      return freezeJson({ schemaVersion: 1, identity,
-        reference: imported, observation, definition: exported.definition, soul, roots: minimumRoots(roots),
-        adoption: imported.adoption ? { identity, parsed: parsedImport, origins: importOrigins, pointer: origin.pointer } : null,
-        provenance: [declaredOrigin(exports, `/exports/souls/${at}`, "source-export")] });
-    },
-  };
-}