@metaobjectsdev/cli 1.0.3 → 1.0.4

package/src/lib/library-eject.ts

@@ -0,0 +1,298 @@
+// `meta eject <library>` — FR-043 §3.4, the copy door for a shipped library's METADATA.
+//
+// ADR-0034 ruled that a reference GENERATOR is copied into the adopter's repo because
+// the adopter owns their code. §3.4 extends the same ruling to declared design, and
+// makes it the EXPECTED mode rather than the fallback: a library is first a reference —
+// something to copy, rename, and cut down. Using one in place, tracking upstream, is the
+// deliberate minority choice.
+//
+// Two things follow, and both are here rather than in the generator path:
+//
+//   The destination is `Collection.sourceRoots[0]` — the project's first DECLARED
+//   source root, resolved through `resolveCollection()`. Never `metaobjects/`: that
+//   string is the default value of `sources` and nothing else (CLAUDE.md names the five
+//   sites allowed to spell it, and this is not one of them).
+//
+//   Every file carries a provenance header. It is what makes the copy's origin legible
+//   a year later, what `--list` reads to report staleness against the shipped tree, and
+//   what carries the ONE instruction that makes the eject complete: remove the library
+//   from `libraries`, or both trees load and merge (ERR_LIBRARY_PACKAGE_COLLISION).
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { MetaDataLoader, PACKAGE_SEPARATOR, canonicalSerialize, type MetaData } from "@metaobjectsdev/metadata";
+import {
+  libraryManifests, libraryRefSource, libraryRefs, librarySources,
+  knownLibraryTokens, splitLayerToken,
+} from "@metaobjectsdev/metadata/library";
+import { resolveCollection } from "@metaobjectsdev/sdk";
+import { cliVersion } from "./version.js";
+
+/** The first line of every ejected file — the marker `--list` scans for. */
+export const EJECT_MARKER = "# meta-eject:";
+
+/** True when `name` is a shipped library rather than a generator. */
+export function isLibraryName(name: string): boolean {
+  return name in libraryManifests();
+}
+
+/** Every shipped library name, sorted. */
+export function ejectableLibraryNames(): string[] {
+  return Object.keys(libraryManifests()).sort();
+}
+
+/**
+ * Where an ejected ref lands: `meta.<library>.<file>.yaml`.
+ *
+ * Not the library's own basename. `model.yaml` / `db.yaml` / `requirements.yaml` are
+ * meaningful inside `library/iam/` and meaningless in a directory holding an
+ * application's whole model — and three libraries ejected into one root would collide
+ * outright. The `meta.<concept>.<...>` shape is the file-naming convention this project
+ * documents.
+ */
+export function ejectedFileName(library: string, ref: string): string {
+  return `meta.${library}.${basename(ref)}.yaml`;
+}
+
+function header(library: string, ref: string): string {
+  return [
+    `${EJECT_MARKER} library=${library} ref=${ref} cli=${cliVersion()}`,
+    `# Copied from the MetaObjects shipped library "${library}". YOU OWN THIS FILE: rename`,
+    `# the package, delete what you do not need, change anything. Nothing regenerates it,`,
+    `# and no gate compares it to the shipped tree except \`meta eject --list\`.`,
+    `#`,
+    `# ONE STEP REMAINS: remove "${library}" (and any "${library}/<layer>") from`,
+    `# \`libraries\` in .metaobjects/config.json. Left there, the shipped tree and this`,
+    `# copy BOTH load and merge — additions take effect and deletions do not, because the`,
+    `# library still declares what you removed. The loader refuses that outright`,
+    `# (ERR_LIBRARY_PACKAGE_COLLISION) rather than letting it run.`,
+    "",
+  ].join("\n");
+}
+
+export interface EjectedLibraryFile {
+  ref: string;
+  /** Path relative to the project root. */
+  path: string;
+  status: "created" | "preserved" | "replaced";
+}
+
+export interface LibraryEjectResult {
+  library: string;
+  /** Absolute destination directory. */
+  root: string;
+  files: EjectedLibraryFile[];
+  /** The tokens for this library the project currently declares — what to remove. */
+  stillOptedIn: readonly string[];
+}
+
+async function fileExists(p: string): Promise<boolean> {
+  try {
+    return (await stat(p)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export async function ejectLibrary(opts: {
+  cwd: string;
+  name: string;
+  force?: boolean;
+}): Promise<LibraryEjectResult> {
+  const manifest = libraryManifests()[opts.name];
+  if (manifest === undefined) {
+    throw new Error(
+      `unknown library "${opts.name}". Shipped libraries: ${ejectableLibraryNames().join(", ")}.`,
+    );
+  }
+  const collection = await resolveCollection(opts.cwd);
+  const root = collection.sourceRoots[0];
+  if (root === undefined) {
+    throw new Error(
+      `this project declares no metadata source root, so there is nowhere to put ` +
+        `"${opts.name}". Declare "sources" in .metaobjects/config.json, or run 'meta init'.`,
+    );
+  }
+
+  await mkdir(root, { recursive: true });
+  const files: EjectedLibraryFile[] = [];
+  for (const ref of libraryRefs(opts.name)) {
+    const text = header(opts.name, ref) + (await libraryRefSource(ref).read());
+    const name = ejectedFileName(opts.name, ref);
+    const abs = join(root, name);
+    const existed = await fileExists(abs);
+    if (existed && opts.force !== true) {
+      files.push({ ref, path: name, status: "preserved" });
+      continue;
+    }
+    await writeFile(abs, text, "utf8");
+    files.push({ ref, path: name, status: existed ? "replaced" : "created" });
+  }
+
+  return {
+    library: opts.name,
+    root,
+    files,
+    stillOptedIn: collection.libraries.filter((t) => splitLayerToken(t)[0] === opts.name),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// staleness — `meta eject --list`
+// ---------------------------------------------------------------------------
+
+export interface LibraryStaleness {
+  library: string;
+  /** Files in this project carrying the eject marker for this library. */
+  files: string[];
+  verdict: "identical" | "differs" | "unreadable";
+  /** Nodes present in both whose own-mode serialization differs. */
+  changed: number;
+  /** Nodes the SHIPPED tree has that the ejected copy does not — upstream moved. */
+  upstreamOnly: number;
+  /** Nodes the ejected copy has that the shipped tree does not — your additions. */
+  localOnly: number;
+  /** Why the comparison could not be made, when `verdict` is "unreadable". */
+  reason?: string;
+  /** Still named in `libraries` — the ejection is not finished. */
+  stillOptedIn: boolean;
+}
+
+/** The longest package prefix every node shares — the library's own root package.
+ *
+ *  Segment-wise, never by string prefix: `acme::identity` and `acme::identityhub` share
+ *  six characters and no package at all. */
+function commonPackagePrefix(packages: readonly string[]): string {
+  if (packages.length === 0) return "";
+  let common = packages[0]!.split(PACKAGE_SEPARATOR);
+  for (const pkg of packages.slice(1)) {
+    const segments = pkg.split(PACKAGE_SEPARATOR);
+    let i = 0;
+    while (i < common.length && i < segments.length && common[i] === segments[i]) i++;
+    common = common.slice(0, i);
+  }
+  return common.join(PACKAGE_SEPARATOR);
+}
+
+/** Root-level nodes keyed by their package path RELATIVE to the library's own root
+ *  package, canonically serialized in OWN mode.
+ *
+ *  Relative rather than by resolution key, because §3.4 says an adopter who ejects "may
+ *  rename the package freely" — keying on the FQN would report every node of a renamed
+ *  copy as both upstream-only and local-only, which is the least useful answer
+ *  available. Relative rather than by BARE NAME, because a library free to use two
+ *  packages is free to declare `User` in both, and one key for two declarations means
+ *  the one serialized last silently wins: a real divergence in the other is reported as
+ *  `identical`. The relative path is what survives the rename — moving the root leaves
+ *  every suffix below it exactly where it was — so it distinguishes without giving that
+ *  edit anything to catch on. A single-package library yields the bare names it always
+ *  did. Own mode, because the question is what each file DECLARES; the effective tree
+ *  would fold a shipped base's fields into a subtype and report a difference that is not
+ *  in either file. */
+export function ownNodesByName(root: MetaData): Map<string, string> {
+  const nodes = [...root.children()];
+  const packageOf = (node: MetaData) => node.package ?? node.fileDefaultPackage ?? "";
+  // The ROOT package, neutralized in every node's serialization — for the same reason
+  // the keying is relative to it. A rename reaches the `package` key AND every `extends`
+  // inside the node, so comparing the raw text would report a renamed copy as wholly
+  // changed: the loudest possible answer to the one edit §3.4 explicitly invites. The
+  // root rather than each node's own package, so that a deeper node's reference back up
+  // to the root package is neutralized in it too.
+  const rootPackage = commonPackagePrefix(nodes.map(packageOf));
+
+  const out = new Map<string, string>();
+  for (const node of nodes) {
+    const pkg = packageOf(node);
+    const suffix =
+      rootPackage === "" ? pkg
+      : pkg === rootPackage ? ""
+      : pkg.slice(rootPackage.length + PACKAGE_SEPARATOR.length);
+    const key = suffix === "" ? node.name : `${suffix}${PACKAGE_SEPARATOR}${node.name}`;
+    const text = canonicalSerialize(node);
+    out.set(key, rootPackage === "" ? text : text.replaceAll(rootPackage, "<package>"));
+  }
+  return out;
+}
+
+/** Every project file carrying an eject marker, grouped by library. */
+async function ejectedFilesByLibrary(files: readonly string[]): Promise<Map<string, string[]>> {
+  const out = new Map<string, string[]>();
+  for (const file of files) {
+    let head: string;
+    try {
+      head = (await readFile(file, "utf8")).slice(0, 400);
+    } catch {
+      continue;
+    }
+    const match = new RegExp(`^${EJECT_MARKER} library=(\\S+)`, "m").exec(head);
+    const library = match?.[1];
+    if (library === undefined) continue;
+    out.set(library, [...(out.get(library) ?? []), file]);
+  }
+  return out;
+}
+
+/**
+ * Per-library staleness for the copies THIS project owns.
+ *
+ * The same gap `--list` closes for generators, one level up: an ejected copy can sit any
+ * number of releases behind the tree it came from and nothing compares the two. The
+ * comparison is structural, through the canonical serializer, so re-indentation and key
+ * order never show up — the only thing that can be reported is a declaration that
+ * actually changed.
+ */
+export async function libraryStaleness(cwd: string): Promise<LibraryStaleness[]> {
+  let collection;
+  try {
+    collection = await resolveCollection(cwd);
+  } catch {
+    return []; // no project — nothing is ejected here
+  }
+  const byLibrary = await ejectedFilesByLibrary(collection.ownFiles);
+  const selected = new Set(collection.libraries.map((t) => splitLayerToken(t)[0]));
+
+  const rows: LibraryStaleness[] = [];
+  for (const [library, files] of [...byLibrary].sort(([a], [b]) => a.localeCompare(b))) {
+    const row: LibraryStaleness = {
+      library,
+      files: files.map((f) => f.slice(cwd.length + 1)),
+      verdict: "identical",
+      changed: 0,
+      upstreamOnly: 0,
+      localOnly: 0,
+      stillOptedIn: selected.has(library),
+    };
+    if (!(library in libraryManifests())) {
+      rows.push({ ...row, verdict: "unreadable", reason: `this build ships no library "${library}"` });
+      continue;
+    }
+
+    // Both trees WHOLE, never file by file: a db layer is nothing but `overlay: true`
+    // redeclarations, so loading one alone is ERR_OVERLAY_NO_TARGET by construction.
+    const tokens = knownLibraryTokens().filter((t) => splitLayerToken(t)[0] === library);
+    const shipped = await new MetaDataLoader({ strict: true }).load(librarySources(tokens));
+    const { FileSource } = await import("@metaobjectsdev/metadata/core");
+    const local = await new MetaDataLoader({ strict: true }).load(
+      files.map((f) => new FileSource(f)),
+    );
+    if (local.errors.length > 0) {
+      rows.push({
+        ...row,
+        verdict: "unreadable",
+        reason: `the ejected copy does not load on its own: ${local.errors[0]!.message}`,
+      });
+      continue;
+    }
+
+    const up = ownNodesByName(shipped.root);
+    const mine = ownNodesByName(local.root);
+    for (const [name, text] of up) {
+      if (!mine.has(name)) row.upstreamOnly++;
+      else if (mine.get(name) !== text) row.changed++;
+    }
+    for (const name of mine.keys()) if (!up.has(name)) row.localOnly++;
+    row.verdict =
+      row.changed + row.upstreamOnly + row.localOnly === 0 ? "identical" : "differs";
+    rows.push(row);
+  }
+  return rows;
+}

package/src/lib/library-listing.ts

@@ -0,0 +1,258 @@
+// `meta gen --list` — the LIBRARY rows (FR-043 §4).
+//
+// It is the codegen catalog, with `kind: "library"` rows in the same table rather than
+// a parallel one: one door, one namespace, one `--probe`, one skill procedure. An agent
+// about to model "users and permissions" should meet `iam` in the list it was already
+// reading, not in a second command it has to know exists.
+//
+// THE ROW DESCRIBES THE BOX; THE PROJECT BLOCK DESCRIBES YOUR SHELF. `provides` counts
+// what the library ships across ALL its layers — what you would get if you took every
+// layer — while `project.tablesAdded` counts what YOUR selection actually put into the
+// model. Those are different numbers whenever an adopter takes the core layer alone,
+// which Amendment 1 makes the common case: `libraries: ["iam"]` provides nine entities
+// and adds zero tables.
+//
+// Every fact here is COMPUTED — from the manifest, or by loading the library and
+// counting. Nothing is a second copy of a sentence written somewhere else, which is the
+// rule §4 states as "every manifest fact is resolved, not trusted".
+import {
+  MetaDataLoader,
+  TYPE_OBJECT,
+  TYPE_REQUIREMENT,
+  OBJECT_SUBTYPE_ENTITY,
+  isWritableSource,
+  type MetaData,
+} from "@metaobjectsdev/metadata";
+import {
+  libraryManifests,
+  librarySources,
+  knownLibraryTokens,
+  splitLayerToken,
+  type LibraryManifest,
+} from "@metaobjectsdev/metadata/library";
+import { SERVER_LANGS } from "@metaobjectsdev/sdk";
+
+/** One `--list` row for a shipped library. */
+export interface LibraryCatalogRow {
+  name: string;
+  kind: "library";
+  /** The manifest's own `kind` — what SORT of library this is (`feature`, `nfr`). A
+   *  second axis from the row's `kind`, which is the catalog discriminator. */
+  libraryKind: string;
+  stability: string;
+  /** The language ports this library is reachable from. Every port embeds the whole
+   *  `library/` tree from one generator script, so this is all of them — and a test
+   *  resolves that against each port's embedded module rather than trusting it. */
+  ports: readonly string[];
+  description: string;
+  useWhen?: string;
+  packages: readonly string[];
+  /** Selection tokens, core first — `["iam", "iam/db"]`. The bare name IS the core
+   *  layer, and a layer token implies it. This is the field an adopter acts on: under
+   *  Amendment 1 you do not opt into a library, you opt into its layers. */
+  layers: ReadonlyArray<{ token: string; description?: string }>;
+  /** What is in the box, across every layer. */
+  provides: {
+    entities: number;
+    abstracts: number;
+    requirements: number;
+    generators: readonly string[];
+  };
+  project?: LibraryProjectFacts;
+}
+
+export interface LibraryProjectFacts {
+  /** Does this project's `libraries` name this library at all? */
+  optedIn: boolean;
+  /** The tokens this project selected, in config order. Empty when not opted in. */
+  selectedLayers: readonly string[];
+  /** Project entities whose `extends` chain reaches a node this library owns — the
+   *  adoption that opting out would break. `null` unless the model was loaded. */
+  extendedBy: readonly string[] | null;
+  /** Tables this library's SELECTED layers contribute to the loaded model. Zero for a
+   *  core-only selection, which is the inertness promise expressed as a number. */
+  tablesAdded: number | null;
+  /** Requirement entries the library put into this project's ledger. */
+  requirementsAdded: number | null;
+  /** Generators the manifest says this library implies, which this project has not
+   *  wired. Not an error: the library is metadata, and wiring is the adopter's call. */
+  impliedGeneratorsNotWired: readonly string[];
+}
+
+/** What a `--list` caller knows about the project, for the library rows. */
+export interface LibraryProjectContext {
+  /** The project's `libraries` selection, verbatim. */
+  libraries: readonly string[];
+  /** Stable names wired in `generators: [...]`. */
+  wiredNames: ReadonlySet<string>;
+  /** The loaded model, when one was loaded (`--probe`). */
+  metadata?: MetaData;
+}
+
+/** Every selection token belonging to one library, core first. */
+function tokensOf(name: string): string[] {
+  return knownLibraryTokens().filter((t) => splitLayerToken(t)[0] === name);
+}
+
+/** Walk every node, since a requirement nests to any depth and an object does not. */
+function walk(node: MetaData, visit: (n: MetaData) => void): void {
+  for (const child of node.children()) {
+    visit(child);
+    walk(child, visit);
+  }
+}
+
+function effectivePackage(node: MetaData): string {
+  return node.package ?? node.fileDefaultPackage ?? "";
+}
+
+/**
+ * Load one library with ALL of its layers and count what it ships.
+ *
+ * The FULL selection, not the core: `provides` answers "what is in this library",
+ * and an adopter reading it is deciding whether to opt in at all. What their current
+ * selection actually added is the project block's job.
+ */
+async function providesOf(name: string, manifest: LibraryManifest): Promise<LibraryCatalogRow["provides"]> {
+  const result = await new MetaDataLoader({ strict: true }).load(librarySources(tokensOf(name)));
+  let entities = 0;
+  let abstracts = 0;
+  let requirements = 0;
+  walk(result.root, (n) => {
+    if (n.type === TYPE_REQUIREMENT) requirements++;
+    else if (n.type === TYPE_OBJECT && n.subType === OBJECT_SUBTYPE_ENTITY) {
+      if (n.isAbstract) abstracts++;
+      else entities++;
+    }
+  });
+  return {
+    entities,
+    abstracts,
+    requirements,
+    generators: (manifest.generators ?? []).map((g) => g.name),
+  };
+}
+
+/**
+ * The project facts for one library.
+ *
+ * `extendedBy` and the two counts read the LOADED model rather than the library,
+ * because that is the question being answered: not "what does iam contain" but "what
+ * is iam doing in this repo". Without `--probe` there is no model and they are null —
+ * never zero, which would read as "nothing", the opposite of "not measured".
+ */
+function projectFactsFor(
+  manifest: LibraryManifest,
+  ctx: LibraryProjectContext,
+): LibraryProjectFacts {
+  const name = manifest.name;
+  const selectedLayers = ctx.libraries.filter((t) => splitLayerToken(t)[0] === name);
+  const impliedGeneratorsNotWired = (manifest.generators ?? [])
+    .map((g) => g.name)
+    .filter((g) => !ctx.wiredNames.has(g));
+
+  const facts: LibraryProjectFacts = {
+    optedIn: selectedLayers.length > 0,
+    selectedLayers,
+    extendedBy: null,
+    tablesAdded: null,
+    requirementsAdded: null,
+    impliedGeneratorsNotWired,
+  };
+  if (ctx.metadata === undefined) return facts;
+
+  const owned = new Set(manifest.packages ?? []);
+  const extendedBy: string[] = [];
+  let tablesAdded = 0;
+  let requirementsAdded = 0;
+  walk(ctx.metadata, (n) => {
+    const mine = owned.has(effectivePackage(n));
+    if (n.type === TYPE_REQUIREMENT && mine) requirementsAdded++;
+    if (n.type !== TYPE_OBJECT) return;
+    if (mine) {
+      // A writable source is what migrate keys a CREATE TABLE off (#248 —
+      // persistability derives from source presence, never from the subtype), so
+      // counting them here and counting tables there cannot drift apart.
+      if (n.children().some(isWritableSource)) tablesAdded++;
+      return;
+    }
+    // A project entity reaching this library through `extends`, at any depth: the
+    // adoption an adopter would break by removing the library from `libraries`.
+    for (let sup = n.superData; sup !== undefined; sup = sup.superData) {
+      if (owned.has(effectivePackage(sup))) {
+        extendedBy.push(`${effectivePackage(n)}::${n.name}`);
+        return;
+      }
+    }
+  });
+
+  facts.extendedBy = extendedBy.sort();
+  facts.tablesAdded = tablesAdded;
+  facts.requirementsAdded = requirementsAdded;
+  return facts;
+}
+
+/** Every shipped library, as `--list` rows, in name order. */
+export async function buildLibraryRows(
+  ctx?: LibraryProjectContext,
+): Promise<LibraryCatalogRow[]> {
+  const rows: LibraryCatalogRow[] = [];
+  for (const [name, manifest] of Object.entries(libraryManifests()).sort(([a], [b]) =>
+    a.localeCompare(b),
+  )) {
+    const layers = tokensOf(name).map((token) => {
+      const layer = (manifest.layers ?? {})[splitLayerToken(token)[1]];
+      return layer?.description === undefined
+        ? { token }
+        : { token, description: layer.description };
+    });
+    rows.push({
+      name,
+      kind: "library",
+      libraryKind: manifest.kind ?? "feature",
+      stability: manifest.stability ?? "preview",
+      ports: SERVER_LANGS,
+      description: manifest.description ?? "",
+      ...(manifest.useWhen !== undefined ? { useWhen: manifest.useWhen } : {}),
+      packages: manifest.packages ?? [],
+      layers,
+      provides: await providesOf(name, manifest),
+      ...(ctx === undefined ? {} : { project: projectFactsFor(manifest, ctx) }),
+    });
+  }
+  return rows;
+}
+
+function plural(n: number, one: string, many: string): string {
+  return `${n} ${n === 1 ? one : many}`;
+}
+
+/** The human rendering — one section, after the generator layers. */
+export function renderLibraryText(rows: readonly LibraryCatalogRow[]): string[] {
+  if (rows.length === 0) return [];
+  const lines: string[] = [];
+  lines.push("");
+  lines.push("libraries  —  declared design you opt into, a LAYER at a time; the core layer adds no tables");
+  for (const r of rows) {
+    const marks: string[] = [r.stability];
+    if (r.project?.optedIn) marks.push(`opted in: ${r.project.selectedLayers.join(", ")}`);
+    if (r.project?.tablesAdded) marks.push(`${plural(r.project.tablesAdded, "table", "tables")} added`);
+    lines.push(`  ${r.name}  —  ${r.description}  [${marks.join(", ")}]`);
+    if (r.useWhen !== undefined) lines.push(`      use when: ${r.useWhen}`);
+    lines.push(
+      `      provides: ${plural(r.provides.entities, "entity", "entities")}, ` +
+        `${r.provides.abstracts} abstract, ` +
+        `${plural(r.provides.requirements, "requirement", "requirements")}`,
+    );
+    lines.push(`      layers:   ${r.layers.map((l) => l.token).join(", ")}`);
+    if (r.project !== null && r.project?.impliedGeneratorsNotWired.length) {
+      lines.push(
+        `      implies:  ${r.project.impliedGeneratorsNotWired.join(", ")} (not wired)`,
+      );
+    }
+  }
+  lines.push("");
+  lines.push('Opt in with `"libraries": ["iam", "iam/db"]` in .metaobjects/config.json —');
+  lines.push("the bare name is the core layer, and a layer token implies it.");
+  return lines;
+}

package/src/lib/library-prefix-advisory.ts

@@ -0,0 +1,78 @@
+// FR-043 §3.5 — `metaobjects::` in an adopter's own metadata, with no ejection provenance.
+//
+// The loader already REFUSES a node in a library's package while that library is opted
+// in (ERR_LIBRARY_PACKAGE_COLLISION / ERR_LIBRARY_PACKAGE_NOT_OWNED). This is the other
+// half, and it is advisory on purpose: with the library NOT opted in there is nothing
+// broken to refuse — the nodes are simply the adopter's, sitting under a prefix this
+// project ships libraries into.
+//
+// Two ways to arrive there, and the advice is the same for both:
+//
+//   a hand-copy, rather than `meta eject <library>` — no provenance header, so nothing
+//     can tell later where it came from or how far it has drifted;
+//   a package名 chosen freely that happens to start `metaobjects::` — which will
+//     collide the day a library ships into it.
+//
+// A file carrying the eject marker is exempt: that IS the provenance, and `meta eject
+// --list` reports its staleness.
+import { readFile } from "node:fs/promises";
+import { EJECT_MARKER } from "./library-eject.js";
+import type { MetaData } from "@metaobjectsdev/metadata";
+
+/** The prefix every shipped library declares into. */
+export const LIBRARY_PACKAGE_PREFIX = "metaobjects::";
+
+export interface LibraryPrefixFinding {
+  file: string;
+  fqn: string;
+  message: string;
+}
+
+/**
+ * Root nodes under `metaobjects::` whose file carries no ejection provenance.
+ *
+ * Reads the loaded tree for the nodes and the FILES only for the marker — the marker is
+ * `meta eject`'s own bookkeeping, not metadata, so there is nothing in the model to read
+ * it from.
+ */
+export async function scanForUnprovenancedLibraryPrefix(
+  root: MetaData,
+  ownFiles: readonly string[],
+  projectRoot: string,
+): Promise<LibraryPrefixFinding[]> {
+  const suspect = root
+    .children()
+    .filter((n) => n.resolutionKey().startsWith(LIBRARY_PACKAGE_PREFIX));
+  if (suspect.length === 0) return [];
+
+  // Which of this project's own files carry the marker — read once, not per node.
+  const provenanced = new Set<string>();
+  for (const file of ownFiles) {
+    try {
+      if ((await readFile(file, "utf8")).slice(0, 400).includes(EJECT_MARKER)) {
+        provenanced.add(file.slice(projectRoot.length + 1));
+      }
+    } catch {
+      // unreadable — it contributes no exemption, which is the safe direction
+    }
+  }
+
+  const out: LibraryPrefixFinding[] = [];
+  for (const node of suspect) {
+    const files = "files" in node.source ? node.source.files : [];
+    // A node the SHIPPED library contributed is not the adopter's — `library:` ids say so.
+    if (files.some((f) => f.startsWith("library:"))) continue;
+    if (files.some((f) => provenanced.has(f) || [...provenanced].some((p) => p.endsWith(f)))) continue;
+    out.push({
+      file: files[0] ?? "(unknown)",
+      fqn: node.resolutionKey(),
+      message:
+        `${node.resolutionKey()} is declared under "${LIBRARY_PACKAGE_PREFIX}", which is where ` +
+        `MetaObjects ships its libraries, and no file declaring it carries an ejection header. ` +
+        `If it was copied from a library, re-copy it with 'meta eject <library>' so its origin ` +
+        `and its drift stay legible; if it is your own, move it to a package you own — a later ` +
+        `release shipping a node of that name would merge into yours.`,
+    });
+  }
+  return out;
+}