@metaobjectsdev/sdk 0.23.2 → 0.24.0

package/src/memory.ts

@@ -1,5 +1,3 @@
-import { join } from "node:path";
-import { readdir, stat } from "node:fs/promises";
 import {
   composeRegistry,
   coreProviders,
@@ -8,21 +6,8 @@ import {
   type MetaRoot,
 } from "@metaobjectsdev/metadata";
 import { FileSource } from "@metaobjectsdev/metadata/core";
+import { resolveCollection } from "./collection.js";
 import { forgeTypesProvider } from "./forge-types.js";
-import { discoverWorkspace, resolveExtendsOrder } from "./workspace.js";
-
-/**
- * Default directory name (relative to project root) where metadata JSON files
- * are scanned. Scaffold via `meta init`; the directory is committed to git.
- */
-export const DEFAULT_METADATA_DIR = "metaobjects";
-
-/**
- * Default directory name (relative to project root) for MetaObjects' own
- * runtime state: config.json, .gen-state/, package.meta.json, agent docs.
- * Scaffold via `meta init`; most contents are committed to git.
- */
-export const DEFAULT_METAOBJECTS_DIR = ".metaobjects";
 
 /**
  * Options for {@link loadMemory}. Consumers can supply additional
@@ -50,6 +35,31 @@ export interface LoadMemoryOptions {
    * the `meta verify` command opts in to `true` (strict-by-default, #96).
    */
   strict?: boolean;
+  /**
+   * An already-resolved, absolute metadata file list — normally
+   * `resolveCollection(...).files`. When supplied, `loadMemory` loads exactly
+   * these files and resolves nothing itself.
+   *
+   * Omitting it is not a different WAY of finding metadata, only a different
+   * place the same resolution happens: `loadMemory` then calls
+   * `resolveCollection(repoRoot)` itself. Passing it saves the second
+   * resolution when the caller already holds a collection (every routed CLI
+   * command does) and lets a caller load a file set it computed some other
+   * way; it can no longer diverge from what the config declares.
+   */
+  files?: readonly string[];
+  /**
+   * MetaObjects-shipped library packages to load ALONGSIDE the project's own files
+   * (e.g. `["ai"]` for `metaobjects::ai::LlmCallBase`). Prepended, so an
+   * `extends: "metaobjects::ai::LlmCallBase"` in project metadata resolves.
+   *
+   * Opt-in rather than always-on: a library package registers real top-level nodes, and
+   * a project that never references one should not have them appear in its model, its
+   * generated output or its docs. Without this the CLI could not load the metadata that
+   * shipped generators like `trace-helper` exist to consume, so the generator was
+   * reachable from the command line while its input was not (#333).
+   */
+  libraries?: readonly string[];
 }
 
 /** Default provider bundle threaded by {@link loadMemory} when no options
@@ -62,10 +72,15 @@ export const defaultLoadMemoryProviders: readonly MetaDataTypeProvider[] = [
 ];
 
 /**
- * Load all metadata files from `<repoRoot>/metaobjects/` into a single
- * MetaData. If `<repoRoot>/.meta/package.meta.json` declares `extends:` deps
- * and a workspace can be discovered (pnpm-workspace.yaml or package.json
- * workspaces), peer packages are loaded too in topological dep-first order.
+ * Load a project's metadata into a single MetaData tree.
+ *
+ * Which files those are is `resolveCollection`'s decision, never this
+ * function's: with no {@link LoadMemoryOptions.files} it calls
+ * `resolveCollection(repoRoot)` — nearest-ancestor `.metaobjects/config.json`,
+ * then that config's declared `sources`, falling back to the default source
+ * directory only when a project declares none. `loadMemory` names no directory
+ * of its own, so a caller cannot end up loading from somewhere the rest of the
+ * toolchain does not.
  *
  * Excludes `_pending/`. Registers metaobjects core types plus Meta Forge's
  * descriptive top-level types (decision, principle, etc.) so mixed content
@@ -73,11 +88,15 @@ export const defaultLoadMemoryProviders: readonly MetaDataTypeProvider[] = [
  * {@link LoadMemoryOptions.providers}) are composed AFTER the defaults so
  * they may depend on core/forge ids.
  *
- * Throws if `metaobjects/` doesn't exist (callers should run `meta init`).
+ * Throws `ERR_COLLECTION_NOT_FOUND` when nothing resolves (callers should run
+ * `meta init`), unless `options.files` is supplied.
  *
- * @param repoRoot The project's working-directory root (e.g. process.cwd()).
- *   `loadMemory` resolves `metaobjects/` and (if workspace-aware) the
- *   transitive `extends:` graph automatically.
+ * @param repoRoot Where resolution STARTS — the working directory, typically
+ *   `process.cwd()`. The walk goes up from here for the governing config, so
+ *   this need not be the project root itself.
+ *   **Ignored entirely when `options.files` is supplied**: that list is already
+ *   resolved, so nothing reads this path. Every routed CLI command passes both,
+ *   and the argument is inert at all of them.
  * @param options Optional {@link LoadMemoryOptions} — supply additional
  *   providers or replace the default bundle entirely.
  */
@@ -99,16 +118,33 @@ export async function loadMemory(
   }
   const registry = composeRegistry(providers);
 
-  // Collect all metadata file paths to load. Order matters for the parser's
-  // deferred-resolution pass (it parses in array order, then resolves supers
-  // against the merged tree afterwards) — dep packages first, current last.
-  const paths = await collectMetadataPaths(repoRoot);
+  // Both arms are `resolveCollection`'s answer — one already computed by the
+  // caller, one computed here. There is no third way to find metadata, and
+  // that is the whole of this line's design: the previous no-`files` arm
+  // scanned `<repoRoot>/<default dir>` directly, so a caller that copied the
+  // routed shape but forgot `files` silently loaded from a directory the
+  // project's config may never have mentioned.
+  const paths = options?.files !== undefined
+    ? [...options.files]
+    : [...(await resolveCollection(repoRoot)).files];
 
   const loader = new MetaDataLoader({
     registry,
     ...(options?.strict === true ? { strict: true } : {}),
   });
-  const result = await loader.load(paths.map((p) => new FileSource(p)));
+
+  // Library sources are imported lazily and only when asked for — the same reason
+  // `MetaDataLoader.fromDirectory` does it. `library-sources.ts` reads `node:fs`, so a
+  // static import from a root-reachable module drags Node built-ins into every consumer's
+  // graph; that is the #287 bundle defect, and the `./library` subpath exists for exactly
+  // the reason `./constants` does. Prepended, so a project's `extends` onto a
+  // library-shipped abstract base resolves — super resolution is order-independent, but
+  // prepending is the deterministic choice and matches `fromDirectory`.
+  const libSources =
+    options?.libraries !== undefined && options.libraries.length > 0
+      ? (await import("@metaobjectsdev/metadata/library")).librarySources([...options.libraries])
+      : [];
+  const result = await loader.load([...libSources, ...paths.map((p) => new FileSource(p))]);
 
   if (result.errors.length > 0) {
     const first = result.errors[0]!;
@@ -117,73 +153,3 @@ export async function loadMemory(
 
   return result.root;
 }
-
-// Dep packages' metaobjects/ files first (topological order), then current.
-async function collectMetadataPaths(repoRoot: string): Promise<string[]> {
-  const currentMetaDir = join(repoRoot, ".meta");
-  const ws = await discoverWorkspace(repoRoot);
-
-  // Workspace path: walk extends, load dep metaobjects/ dirs first
-  if (ws !== undefined) {
-    const currentPkg = ws.packages.find((p) => p.metaDir === currentMetaDir);
-    if (currentPkg !== undefined && currentPkg.manifest.extends.length > 0) {
-      const ordered = resolveExtendsOrder(ws, currentMetaDir);
-      const paths: string[] = [];
-      for (const pkg of ordered) {
-        // Each workspace package's metadata lives alongside its .meta/ dir
-        const pkgRoot = join(pkg.metaDir, "..");
-        paths.push(...(await listMetadataFiles(join(pkgRoot, DEFAULT_METADATA_DIR))));
-      }
-      return paths;
-    }
-  }
-
-  // Single-package path: scan metaobjects/ at the project root
-  return listMetadataFiles(join(repoRoot, DEFAULT_METADATA_DIR));
-}
-
-/**
- * Recursively list metadata files (*.json, *.yaml, *.yml) under a directory,
- * excluding _pending/ at any level. Subdirectories (e.g. projections/) are
- * walked depth-first. Files within a directory are sorted alphabetically for
- * deterministic load order; subdirectories are visited after files at the
- * same level.
- *
- * Format selection (parsing) happens downstream in `FileSource` from
- * `@metaobjectsdev/metadata`, which infers the parser from file extension.
- */
-async function listMetadataFiles(dir: string): Promise<string[]> {
-  let entries: string[];
-  try {
-    entries = await readdir(dir);
-  } catch (err) {
-    throw new Error(`loadMemory: cannot read ${dir}: ${(err as Error).message}`);
-  }
-  const paths: string[] = [];
-  const subdirs: string[] = [];
-  // #188: sort the raw `readdir` entries so file order is deterministic across
-  // runtimes/filesystems (Node vs Bun return different `readdir` orders), matching
-  // this function's docstring and the metadata package's own `DirectorySource`.
-  // (Resolution is now order-INDEPENDENT — super-resolve.ts #188 — so this is the
-  // deterministic-enumeration FLOOR, not the fix; it keeps every derived artifact
-  // that preserves declaration order, e.g. serialization, stable across runtimes.)
-  for (const entry of [...entries].sort()) {
-    if (entry === "_pending") continue;
-    const full = join(dir, entry);
-    const s = await stat(full);
-    if (s.isDirectory()) {
-      subdirs.push(full);
-    } else if (s.isFile() && isMetadataFile(entry)) {
-      paths.push(full);
-    }
-  }
-  // Recurse into subdirectories after collecting files at this level
-  for (const sub of subdirs.sort()) {
-    paths.push(...(await listMetadataFiles(sub)));
-  }
-  return paths;
-}
-
-function isMetadataFile(name: string): boolean {
-  return name.endsWith(".json") || name.endsWith(".yaml") || name.endsWith(".yml");
-}

package/src/metadata-files.ts

@@ -0,0 +1,158 @@
+// server/typescript/packages/sdk/src/metadata-files.ts
+//
+// The project's default directory names, what counts as a metadata file, and
+// the one walk that turns a directory into an ordered file list.
+//
+// **This module imports nothing from its siblings, and that is the point.**
+// `resolveCollection` (`collection.ts`) is the single authority on where
+// metadata lives, so `memory.ts`'s `loadMemory` must call it — while
+// `collection.ts` and `sources.ts` need the constants and the walk below.
+// Homing those in `memory.ts` closes an ESM cycle whose failure mode is not a
+// warning but a crash: `DEFAULT_SOURCES` (`sources.ts`) reads
+// `DEFAULT_METADATA_DIR` at module top level, so the cycle surfaces as
+// `ReferenceError: Cannot access 'DEFAULT_METADATA_DIR' before initialization`
+// on whichever module the entry point happens to reach first. A leaf both
+// sides import is the fix; a lazy `await import()` inside `loadMemory` is not
+// — that hides the cycle rather than removing it.
+import { extname, join } from "node:path";
+import { readdir, realpath, stat } from "node:fs/promises";
+
+/**
+ * The DEFAULT value of `sources` — the directory scanned when
+ * `.metaobjects/config.json` declares no sources. Scaffold via `meta init`;
+ * the directory is committed to git.
+ *
+ * **A default, and nothing else.** No read path may assume a directory of this
+ * name exists or is where metadata lives: that question is answered by
+ * `resolveCollection`, which applies this constant exactly once (via
+ * `DEFAULT_SOURCES` in `sources.ts`) when a project declares nothing. A
+ * project that declares `sources` may put its metadata anywhere, and every
+ * command follows the config. `test/no-hardcoded-metadata-dir.test.ts` is the
+ * enforcer.
+ */
+export const DEFAULT_METADATA_DIR = "metaobjects";
+
+/**
+ * Default directory name (relative to project root) for MetaObjects' own
+ * runtime state: config.json, .gen-state/, package.meta.json, agent docs.
+ * Scaffold via `meta init`; most contents are committed to git.
+ *
+ * Unlike {@link DEFAULT_METADATA_DIR} this one IS a fixed convention — it is
+ * where the config that answers "where is the metadata?" lives, so it cannot
+ * itself be configured.
+ */
+export const DEFAULT_METAOBJECTS_DIR = ".metaobjects";
+
+/** Recognized metadata file extensions, matched case-insensitively — mirrors
+ *  `DirectorySource` in `@metaobjectsdev/metadata`, which checks
+ *  `extname().toLowerCase()`. The single definition every metadata-file
+ *  walker in this package uses — and since `resolveSources` (`sources.ts`)
+ *  calls {@link listMetadataFiles} outright rather than keeping a second
+ *  recursive walk of its own, there is exactly one walker to keep honest. */
+export const METADATA_EXTENSIONS = new Set([".json", ".yaml", ".yml"]);
+
+export function isMetadataFile(name: string): boolean {
+  return METADATA_EXTENSIONS.has(extname(name).toLowerCase());
+}
+
+/** Directory excluded at every level of {@link listMetadataFiles} — drafts
+ *  that are deliberately not part of the loaded model. */
+const PENDING_DIR = "_pending";
+
+/**
+ * Recursively list metadata files (*.json, *.yaml, *.yml, matched
+ * case-insensitively — see `isMetadataFile` above) under a directory,
+ * excluding _pending/ at any level. Subdirectories (e.g. projections/) are
+ * walked depth-first. Files within a directory are sorted alphabetically for
+ * deterministic load order; subdirectories are visited AFTER the files at the
+ * same level.
+ *
+ * That per-level rule is a contract, not an implementation detail. This is the
+ * order production has always handed the loader, and declaration order survives
+ * into generated output: `codegen-ts`'s barrel emits from `root.objects()`
+ * order, and so do the shared `enums.ts`, `meta docs` page ordering and `meta
+ * export`'s `canonicalSerialize` sibling order. A flat lexicographic sort of
+ * absolute paths is NOT the same list — it disagrees whenever a subdirectory
+ * name sorts before a sibling file (`common/` before `meta.users.json`) — so
+ * `resolveSources` calls this function rather than re-walking and re-sorting.
+ * Pinned by `test/source-order.test.ts`.
+ *
+ * Exported for that gate and for `sources.ts`; not re-exported from the package
+ * index — `resolveCollection` is the public door.
+ *
+ * An entry whose `stat` fails (a dangling symlink, a TOCTOU removal between
+ * `readdir` and `stat`, an EACCES entry) is SKIPPED, matching `DirectorySource`
+ * in `@metaobjectsdev/metadata`, which this walk otherwise mirrors. A failure to
+ * read the directory itself still throws — that is the "you have no metadata
+ * here" case callers report.
+ *
+ * A symlink CYCLE (e.g. `metaobjects/link -> ..`) is a loud error rather than
+ * unbounded recursion — see {@link listMetadataFilesGuarded}.
+ *
+ * Format selection (parsing) happens downstream in `FileSource` from
+ * `@metaobjectsdev/metadata`, which infers the parser from file extension.
+ */
+export async function listMetadataFiles(dir: string): Promise<string[]> {
+  return listMetadataFilesGuarded(dir, new Set());
+}
+
+/**
+ * {@link listMetadataFiles}'s recursive worker, carrying the REAL (symlink-
+ * resolved) ancestor directories already on this walk branch.
+ *
+ * This walk follows symlinked directories on purpose (`stat`, not `lstat`,
+ * below — matching `DirectorySource` in `@metaobjectsdev/metadata`), so an
+ * unguarded directory symlink that revisits an ancestor recurses forever:
+ * Java and Python both added this exact guard when this PR promoted
+ * symlink-following to a cross-port contract; the TypeScript reference itself
+ * did not, even though the corpus cites it as authoritative. `ancestors` is
+ * extended only on the recursive call (never mutated in place), so it
+ * reflects the current branch, not siblings visited earlier at the same
+ * level — a directory legitimately reachable via two different symlinked
+ * paths (not a cycle) is not falsely rejected.
+ */
+async function listMetadataFilesGuarded(dir: string, ancestors: ReadonlySet<string>): Promise<string[]> {
+  // `realpath` failing (e.g. `dir` vanished between being listed and now) is
+  // not this guard's problem — fall back to the given path and let `readdir`
+  // below raise its own coded error.
+  const real = await realpath(dir).catch(() => dir);
+  if (ancestors.has(real)) {
+    throw new Error(`symlink loop detected while expanding metadata directory: ${dir} revisits ${real}`);
+  }
+  const nextAncestors = new Set(ancestors);
+  nextAncestors.add(real);
+
+  let entries: string[];
+  try {
+    entries = await readdir(dir);
+  } catch (err) {
+    throw new Error(`cannot read metadata directory ${dir}: ${(err as Error).message}`);
+  }
+  const paths: string[] = [];
+  const subdirs: string[] = [];
+  // #188: sort the raw `readdir` entries so file order is deterministic across
+  // runtimes/filesystems (Node vs Bun return different `readdir` orders), matching
+  // this function's docstring and the metadata package's own `DirectorySource`.
+  // (Resolution is now order-INDEPENDENT — super-resolve.ts #188 — so this is the
+  // deterministic-enumeration FLOOR, not the fix; it keeps every derived artifact
+  // that preserves declaration order, e.g. serialization, stable across runtimes.)
+  for (const entry of [...entries].sort()) {
+    if (entry === PENDING_DIR) continue;
+    const full = join(dir, entry);
+    // `stat` (not `lstat`/`Dirent.isDirectory()`) so a symlinked subdirectory is
+    // traversed — `DirectorySource` has always followed symlinks this way.
+    const s = await stat(full).catch(() => undefined);
+    if (s === undefined) continue;
+    if (s.isDirectory()) {
+      subdirs.push(full);
+    } else if (s.isFile() && isMetadataFile(entry)) {
+      paths.push(full);
+    }
+  }
+  // Recurse into subdirectories after collecting files at this level.
+  // `subdirs` is already in sorted order (built from the sorted `entries` above).
+  for (const sub of subdirs) {
+    paths.push(...(await listMetadataFilesGuarded(sub, nextAncestors)));
+  }
+  return paths;
+}

package/src/scope.ts

@@ -0,0 +1,95 @@
+// server/typescript/packages/sdk/src/scope.ts
+//
+// Phase-1 metadata-source-resolution — the scope pattern engine.
+//
+// A pure, no-I/O module deciding whether a fully-qualified node name falls
+// inside a consumer's declared `include`/`exclude` scope. Source resolution
+// and discovery (later phase-1 tasks) build on this; a cross-language
+// conformance corpus pins its semantics, so exact pattern behavior matters.
+
+// NOTE: PACKAGE_SEPARATOR is NOT re-exported from the browser-safe
+// `@metaobjectsdev/metadata/constants` barrel (that barrel only re-exports
+// the per-concern `*-constants.ts` modules; `PACKAGE_SEPARATOR` lives in
+// `shared/structural.ts`, exported from the package root). This package
+// (`@metaobjectsdev/sdk`) is server-side, not a `client/web/**` browser
+// package, so importing metamodel values from the root — the same thing
+// `memory.ts` and `forge-types.ts` in this package already do — is correct.
+import { PACKAGE_SEPARATOR, ParseError, codeSource } from "@metaobjectsdev/metadata";
+
+/** A consumer-side output filter over fully-qualified node names. */
+export interface Scope {
+  /** Absent or empty means "everything". */
+  readonly include?: readonly string[];
+  /** Applied after `include`. */
+  readonly exclude?: readonly string[];
+}
+
+export interface CompiledScope {
+  readonly include: readonly RegExp[];
+  readonly exclude: readonly RegExp[];
+}
+
+/** One package segment: any run of characters containing no separator char. */
+const SEGMENT = "[^:]+";
+/** One or more segments, separator-joined — the `**` expansion. */
+const SEGMENTS = `${SEGMENT}(?:${PACKAGE_SEPARATOR}${SEGMENT})*`;
+
+function escapeLiteral(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Compile one segment. `**` spans segments; `*` never crosses a separator. */
+function compileSegment(segment: string, pattern: string): string {
+  if (segment.length === 0) {
+    throw new ParseError(`empty segment in scope pattern "${pattern}"`, {
+      code: "ERR_SCOPE_PATTERN_INVALID",
+      source: codeSource("compileSegment"),
+    });
+  }
+  // A segment surviving the split on the two-character PACKAGE_SEPARATOR
+  // ("::") can still contain a lone ":" when the pattern has an odd colon
+  // run — e.g. "acme:::Order".split("::") => ["acme", ":Order"]. SEGMENT
+  // ([^:]+) already excludes ":" from a well-formed segment, so a leftover
+  // ":" here means the separator was malformed, not that ":" is meant
+  // literally. Left unchecked, escapeLiteral treats it as a literal
+  // character and compiles a regex requiring three colons in a row — which
+  // no legal "::"-joined fully-qualified name can ever contain, so the
+  // pattern silently matches nothing instead of failing loud.
+  if (segment.includes(":")) {
+    throw new ParseError(
+      `scope pattern "${pattern}" has a malformed separator (an odd run of ":") — segments are joined by "::", never a single ":"`,
+      { code: "ERR_SCOPE_PATTERN_INVALID", source: codeSource("compileSegment") },
+    );
+  }
+  if (segment === "**") return `(?:${SEGMENTS})`;
+  // `*` inside a segment matches any characters except the separator char.
+  return segment.split("*").map(escapeLiteral).join("[^:]*");
+}
+
+export function compilePattern(pattern: string): RegExp {
+  if (pattern.length === 0) {
+    throw new ParseError(`scope pattern must not be empty`, {
+      code: "ERR_SCOPE_PATTERN_INVALID",
+      source: codeSource("compilePattern"),
+    });
+  }
+  const body = pattern
+    .split(PACKAGE_SEPARATOR)
+    .map((segment) => compileSegment(segment, pattern))
+    .join(PACKAGE_SEPARATOR);
+  return new RegExp(`^${body}$`);
+}
+
+export function compileScope(scope: Scope): CompiledScope {
+  return {
+    include: (scope.include ?? []).map(compilePattern),
+    exclude: (scope.exclude ?? []).map(compilePattern),
+  };
+}
+
+/** True when `fqn` is inside the scope. An empty `include` means everything. */
+export function matchesScope(fqn: string, compiled: CompiledScope): boolean {
+  const included = compiled.include.length === 0 || compiled.include.some((re) => re.test(fqn));
+  if (!included) return false;
+  return !compiled.exclude.some((re) => re.test(fqn));
+}

package/src/sources.ts

@@ -0,0 +1,160 @@
+// server/typescript/packages/sdk/src/sources.ts
+//
+// Phase-1 metadata-source-resolution — source spec resolution.
+//
+// Turns a declared source SET (`.metaobjects/config.json`'s `sources`) into a
+// canonically-ordered, de-duplicated list of metadata file paths. The FULL
+// result — including which spec each entry attributes to — is a pure
+// function of the source SET, never of declaration order: permuting `specs`
+// cannot change the output, even when two specs overlap on the same file.
+// `test/order-independence.test.ts` pins that (the design's linchpin), so the
+// canonical spec ordering below is load-bearing.
+//
+// Canonical is NOT the same as "flat-sorted". Within one directory spec the
+// order is `listMetadataFiles`'s (metadata-files.ts) — files at a level, then
+// that level's subdirectories, depth-first — because that is the order production
+// has always handed the loader, and declaration order survives into generated
+// output (the barrel's export list, the shared `enums.ts`, `meta docs` page
+// order, `meta export`'s sibling order). A flat sort of absolute paths
+// silently reorders any project with a subdirectory whose name sorts before a
+// sibling file. Across specs, order is decided by spec CONTENT, which is what
+// keeps the whole result permutation-invariant. `test/source-order.test.ts`
+// pins both halves.
+import { stat } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import { ParseError, codeSource } from "@metaobjectsdev/metadata";
+import { DEFAULT_METADATA_DIR, listMetadataFiles } from "./metadata-files.js";
+
+/** Tagged union of source kinds. `resource` and `package` are declared now so
+ *  the config shape is stable across phases; only `path` resolves in phase 1 —
+ *  `resource`/`package` throw `ERR_SOURCE_KIND_UNSUPPORTED`. */
+export type SourceSpec =
+  | { readonly path: string }
+  | { readonly resource: string }
+  | { readonly package: string };
+
+export interface ResolvedSource {
+  /** Absolute path of one metadata file. */
+  readonly file: string;
+  /** The spec that contributed it — provenance for diagnostics. */
+  readonly spec: SourceSpec;
+}
+
+/** Used when `sources` is absent or empty in `.metaobjects/config.json`. A
+ *  DEFAULT, never a requirement — a project that declares `sources` explicitly
+ *  need not include the default directory at all. Built from
+ *  `DEFAULT_METADATA_DIR` (`metadata-files.ts`'s single definition) rather than
+ *  restating that name here: a second independent encoding of the same
+ *  default would let `resolveCollection`'s "does the default dir exist"
+ *  check (`collection.ts`) desync from what `resolveSources` actually
+ *  resolves the moment the default ever changed — silently reproducing the
+ *  "two code paths disagree about where metadata lives" class of bug this
+ *  whole mechanism exists to eliminate. */
+export const DEFAULT_SOURCES: readonly SourceSpec[] = [{ path: DEFAULT_METADATA_DIR }];
+
+/** Narrows `spec` to its `path` arm, throwing `ERR_SOURCE_KIND_UNSUPPORTED`
+ *  for `resource`/`package` — phase 1 resolves `path` only. Returns rather than
+ *  asserting so one call both validates and narrows: an `asserts` signature has
+ *  to be re-invoked wherever TypeScript's control-flow analysis cannot carry the
+ *  narrowing, which is a language workaround masquerading as a second check. */
+function toPathSpec(spec: SourceSpec): { readonly path: string } {
+  if ("path" in spec) return spec;
+  const kind = "resource" in spec ? "resource" : "package";
+  throw new ParseError(
+    `source kind "${kind}" is not supported by this toolchain yet; use a "path" source`,
+    { code: "ERR_SOURCE_KIND_UNSUPPORTED", source: codeSource("resolveSources") },
+  );
+}
+
+/**
+ * The declared source SET in CANONICAL order — kind-validated, then sorted by
+ * spec CONTENT rather than by declaration order.
+ *
+ * This is the ONE place declaration order is discarded, and the module's "pure
+ * function of the SET" invariant rests on it: the emitted file order, the spec
+ * attributed to a file two specs both reach, and which of several unresolvable
+ * paths reports its `ERR_SOURCE_UNRESOLVED` first are all decided here.
+ * Validation runs across the WHOLE list before any sorting or filesystem I/O —
+ * interleaved with resolution, which error code came back would depend on
+ * declaration order, contradicting that same invariant.
+ *
+ * Exported because `resolveCollection` derives `sourceRoots` from the declared
+ * specs and must use this identical ordering; a second sort would be a second
+ * definition of "canonical".
+ */
+export function orderedPathSpecs(specs: readonly SourceSpec[]): { readonly path: string }[] {
+  return specs.map(toPathSpec).sort((a, b) => {
+    const [ja, jb] = [JSON.stringify(a), JSON.stringify(b)];
+    return ja < jb ? -1 : ja > jb ? 1 : 0;
+  });
+}
+
+/**
+ * Where a declared `path` source lives on disk: absolute as written, otherwise
+ * relative to the DECLARING config's directory — never to ambient
+ * `process.cwd()`.
+ *
+ * One definition, because this expression *is* the rule for where a declared
+ * source lives, which is the single piece of knowledge this module exists to
+ * own. A caller that needs a source's root directory (rather than its files)
+ * calls this rather than restating it.
+ */
+export function resolveSpecPath(configDir: string, spec: { readonly path: string }): string {
+  return isAbsolute(spec.path) ? spec.path : resolve(configDir, spec.path);
+}
+
+/**
+ * Resolve a declared source SET to a canonically-ordered list of metadata files.
+ *
+ * The full result — each entry's `.file` AND its `.spec` — is a pure function
+ * of the SET of `specs`: permuting `specs` cannot change the output. One thing
+ * makes that hold: the specs are processed in CONTENT order
+ * (`JSON.stringify(spec)`, ascending) rather than declared order, so both the
+ * emitted file order and the spec attributed to a file overlapping two specs
+ * are decided by content alone. Declared order carries no information anywhere
+ * in this function.
+ *
+ * Within one directory spec the file order is `listMetadataFiles`'s — files at
+ * a level, then that level's subdirectories, depth-first. That is deliberately
+ * NOT a flat sort of absolute paths: see the file header, and
+ * `test/source-order.test.ts`.
+ *
+ * Only `path` specs resolve in phase 1: a directory is walked recursively, a
+ * file is taken as-is. An unresolvable `path` throws `ERR_SOURCE_UNRESOLVED`
+ * rather than silently contributing nothing; `resource`/`package` specs throw
+ * `ERR_SOURCE_KIND_UNSUPPORTED`.
+ *
+ * @param configDir absolute directory of the declaring config (the parent of
+ *   `.metaobjects/`) — relative `path` specs resolve against it, never against
+ *   ambient `process.cwd()`.
+ */
+export async function resolveSources(
+  configDir: string,
+  specs: readonly SourceSpec[],
+): Promise<ResolvedSource[]> {
+  // Kind-validated and content-ordered in one pass — see `orderedPathSpecs`.
+  const ordered = orderedPathSpecs(specs);
+
+  // Insertion order IS output order — a Map preserves it, so the per-spec walk
+  // order above survives to the caller. First contributor wins a shared file,
+  // which is content-determined because `ordered` is.
+  const byFile = new Map<string, SourceSpec>();
+
+  for (const spec of ordered) {
+    const target = resolveSpecPath(configDir, spec);
+    const stats = await stat(target).catch(() => undefined);
+    if (stats === undefined) {
+      throw new ParseError(
+        `source path "${spec.path}" does not exist (resolved to ${target}, relative to ${configDir})`,
+        { code: "ERR_SOURCE_UNRESOLVED", source: codeSource("resolveSources") },
+      );
+    }
+
+    const found = stats.isDirectory() ? await listMetadataFiles(target) : [target];
+    for (const file of found) {
+      if (!byFile.has(file)) byFile.set(file, spec);
+    }
+  }
+
+  return [...byFile].map(([file, spec]) => ({ file, spec }));
+}