@metaobjectsdev/cli 1.0.9-rc.3 → 1.0.9-rc.5

package/src/lib/advisory.ts

@@ -108,6 +108,72 @@ export function ranSection<Row>(rows: Row[]): AdvisorySection<Row> {
   return { status: "ran", total: rows.length, rows };
 }
 
+// The `rule` of each advisory row that is NOT an anti-pattern-scanner finding. A row whose
+// rule is none of these came from the scanner: an authored site hand-rolling a construct.
+export const RULE_MISSING_BASE_URL = "missing-base-url";
+export const RULE_REMOVED_PROP_PREFIX = "removed-prop:";
+export const RULE_LIBRARY_PREFIX = "library-prefix-unprovenanced";
+export const RULE_UNINDEXED_FK = "unindexed-foreign-key";
+export const RULE_REFERENTIAL_ACTION_CONFLICT = "overridden-referential-action";
+
+/** The next-step line for `n` rows of one advisory kind, each naming what the rows are. */
+const ADVISORY_HELP: ReadonlyArray<{ matches: (rule: string) => boolean; line: (n: number) => string }> = [
+  {
+    matches: (r) => r === RULE_UNINDEXED_FK,
+    line: (n) =>
+      `${n} foreign key(s) with no covering index — see antiPatterns.rows[] (rule "${RULE_UNINDEXED_FK}"); each names the index.lookup to declare`,
+  },
+  {
+    matches: (r) => r === RULE_REFERENTIAL_ACTION_CONFLICT,
+    line: (n) =>
+      `${n} foreign key(s) whose two sides disagree on the referential action — see antiPatterns.rows[] (rule "${RULE_REFERENTIAL_ACTION_CONFLICT}")`,
+  },
+  {
+    matches: (r) => r === RULE_MISSING_BASE_URL,
+    line: (n) =>
+      `${n} entity-fetcher provider(s) mounted with no baseUrl while apiPrefix is set — see antiPatterns.rows[] (rule "${RULE_MISSING_BASE_URL}")`,
+  },
+  {
+    matches: (r) => r.startsWith(RULE_REMOVED_PROP_PREFIX),
+    line: (n) =>
+      `${n} provider(s) still mounted with a prop 1.0 renamed away — see antiPatterns.rows[] (rule "${RULE_REMOVED_PROP_PREFIX}<prop>")`,
+  },
+  {
+    matches: (r) => r === RULE_LIBRARY_PREFIX,
+    line: (n) =>
+      `${n} node(s) declared under "metaobjects::" with no ejection provenance — see antiPatterns.rows[] (rule "${RULE_LIBRARY_PREFIX}")`,
+  },
+];
+
+/**
+ * One next-step line per KIND of advisory row, in a structured payload's `help`.
+ *
+ * The advisory section carries several kinds of row keyed by `rule`, and the help line used
+ * to count them all as "authored site(s) hand-roll what MetaObjects can model" — so a project
+ * whose only advisories were unindexed foreign keys was told it hand-rolled three constructs.
+ * Scanner findings keep that line; every other kind is counted under its own label.
+ */
+export function advisoryHelpLines(rows: readonly AdvisoryFindingRow[]): string[] {
+  const counts = ADVISORY_HELP.map(() => 0);
+  let handRolled = 0;
+  for (const row of rows) {
+    const kind = ADVISORY_HELP.findIndex((k) => k.matches(row.rule));
+    if (kind === -1) handRolled++;
+    else counts[kind] = (counts[kind] ?? 0) + 1;
+  }
+  const lines: string[] = [];
+  if (handRolled > 0) {
+    lines.push(
+      `${handRolled} authored site(s) hand-roll what MetaObjects can model — see antiPatterns.rows[] and run \`meta types <construct>\``,
+    );
+  }
+  ADVISORY_HELP.forEach((k, i) => {
+    const n = counts[i] ?? 0;
+    if (n > 0) lines.push(k.line(n));
+  });
+  return lines;
+}
+
 /** Project the scanner's findings into payload rows. `snippet` is deliberately
  *  dropped: it is a copy of the reader's own source line, and `file`+`line`
  *  already address it. */
@@ -129,7 +195,7 @@ export function missingBaseUrlRows(findings: readonly BaseUrlFinding[]): Advisor
   return findings.map((f) => ({
     file: f.file,
     line: f.line,
-    rule: "missing-base-url",
+    rule: RULE_MISSING_BASE_URL,
     construct: f.construct,
     message: f.message,
   }));
@@ -144,7 +210,7 @@ export function removedPropRows(findings: readonly RemovedPropFinding[]): Adviso
   return findings.map((f) => ({
     file: f.file,
     line: f.line,
-    rule: `removed-prop:${f.prop}`,
+    rule: `${RULE_REMOVED_PROP_PREFIX}${f.prop}`,
     construct: f.construct,
     message: f.message,
   }));
@@ -157,7 +223,7 @@ export function libraryPrefixRows(
   return findings.map((f) => ({
     file: f.file,
     line: 0,
-    rule: "library-prefix-unprovenanced",
+    rule: RULE_LIBRARY_PREFIX,
     construct: f.fqn,
     message: f.message,
   }));
@@ -174,7 +240,7 @@ export function unindexedFkRows(
   return findings.map((f) => ({
     file: f.file,
     line: 0,
-    rule: "unindexed-foreign-key",
+    rule: RULE_UNINDEXED_FK,
     construct: f.construct,
     message: f.message,
   }));
@@ -190,7 +256,7 @@ export function referentialActionConflictRows(
   return findings.map((f) => ({
     file: f.file,
     line: 0,
-    rule: "overridden-referential-action",
+    rule: RULE_REFERENTIAL_ACTION_CONFLICT,
     construct: f.construct,
     message: f.message,
   }));

package/src/lib/args.ts

@@ -279,6 +279,14 @@ export interface VerifyFlags {
   templates: boolean;
   /** Run the codegen-drift gate: is the GENERATED contribution of each file current? */
   codegen: boolean;
+  /**
+   * With `--codegen`: fail the build on any hand edit inside a generated file, for teams
+   * that want generated code untouchable. Off by default, because hand edits are the
+   * documented workflow (`meta gen` three-way-merges them) — without it they are
+   * reported as a notice and never change the exit code. Refused without `--codegen`:
+   * it modifies that gate and would otherwise parse cleanly and do nothing.
+   */
+  forbidHandEdits: boolean;
   /**
    * Run the docs-drift gate: regenerate the `meta docs` surfaces into a temp dir and diff
    * them against the committed docs tree.
@@ -370,6 +378,7 @@ export const VERIFY_OPTIONS = {
   "skip-schema": { type: "boolean", default: false },
   templates: { type: "boolean", default: false },
   codegen: { type: "boolean", default: false },
+  "forbid-hand-edits": { type: "boolean", default: false },
   docs: { type: "boolean", default: false },
   deps: { type: "boolean", default: false },
   replay: { type: "boolean", default: false },
@@ -427,6 +436,12 @@ export function parseVerifyArgs(argv: string[]): VerifyFlags {
 
   const templates = !!values.templates;
   const codegen = !!values.codegen;
+  const forbidHandEdits = !!values["forbid-hand-edits"];
+  if (forbidHandEdits && !codegen) {
+    throw new Error(
+      "--forbid-hand-edits only applies to the codegen gate. Run: meta verify --codegen --forbid-hand-edits",
+    );
+  }
   const docs = !!values.docs;
   const deps = !!values.deps;
   const replay = !!values.replay;
@@ -448,6 +463,7 @@ export function parseVerifyArgs(argv: string[]): VerifyFlags {
     skipSchema: !!values["skip-schema"],
     templates,
     codegen,
+    forbidHandEdits,
     docs,
     deps,
     replay,

package/src/lib/catalog-listing.ts

@@ -34,6 +34,11 @@ import {
   type LibraryCatalogRow, type LibraryProjectContext,
 } from "./library-listing.js";
 import { installSetFor } from "./install-set.js";
+import {
+  RUNTIME_ENTRIES, resolveRuntimePackage, runtimeClosure, runtimeCopyStatus, runtimeInstall,
+  type RuntimeCopyRow,
+} from "./runtime-eject.js";
+import { OWNED_RUNTIME_DIR } from "@metaobjectsdev/codegen-ts";
 import { readPackageManifest, declaredDependencyNames } from "./package-manifest.js";
 
 /**
@@ -67,6 +72,13 @@ export interface GeneratorCatalogRow {
     ejectable: boolean;
     /** Whether this project already owns a copy. `null` with no project. */
     owned: boolean | null;
+    /**
+     * ADR-0034 Amendment 3 (2026-09-24): the HTTP-adapter source this generator's output
+     * imports, as far as the project owns a copy of it under `codegen/runtime/` — each
+     * file compared to the installed runtime package. Absent when the generator's output
+     * imports no adapter, or the project owns none of it.
+     */
+    runtimeCopy?: RuntimeCopyRow[];
   };
   project?: {
     /** Wired in this project's `generators: [...]`. */
@@ -167,7 +179,17 @@ export interface CatalogProject {
 export interface CatalogListingOpts {
   project?: CatalogProject;
   /** Run every generator in memory and report a real file count. Needs `project` + `metadata`. */
-  probe?: { metadata: MetaData; scope?: (fqn: string) => boolean };
+  probe?: {
+    metadata: MetaData;
+    scope?: (fqn: string) => boolean;
+    /**
+     * The collection's OWN source files — the same list `meta gen` threads onto
+     * `ctx.sourceFiles`. `shared-model` loads them standalone to build its artifact, so
+     * without them the probe asked it to publish nothing and reported the refusal as
+     * "probe failed" on every fresh project, for a generator that would in fact run.
+     */
+    sourceFiles?: readonly string[];
+  };
 }
 
 /**
@@ -183,6 +205,7 @@ async function probeOne(
   project: CatalogProject,
   metadata: MetaData,
   scope: ((fqn: string) => boolean) | undefined,
+  sourceFiles: readonly string[] | undefined,
 ): Promise<{ count: number; needsConfig?: string[] } | { error: string }> {
   const count = async (config: MetaobjectsGenConfig): Promise<number> => {
     const result = await runGen({
@@ -191,6 +214,7 @@ async function probeOne(
       projectRoot: project.projectRoot,
       dryRun: true,
       ...(scope !== undefined ? { scope } : {}),
+      ...(sourceFiles !== undefined ? { sourceFiles } : {}),
     });
     return result.files.length;
   };
@@ -225,12 +249,37 @@ const PROBE_DB_IMPORT_PLACEHOLDER = "./db";
 // the listing
 // ---------------------------------------------------------------------------
 
+/** Per generator that hands over adapter source, the project's copies of the files it reaches. */
+async function ownedRuntimeByGenerator(
+  projectRoot: string,
+): Promise<Map<string, { files: RuntimeCopyRow[]; packages: string[] }>> {
+  const out = new Map<string, { files: RuntimeCopyRow[]; packages: string[] }>();
+  const status = await runtimeCopyStatus(projectRoot);
+  if (status.length === 0) return out;
+  const { srcRoot } = resolveRuntimePackage();
+  for (const [name, modules] of Object.entries(RUNTIME_ENTRIES)) {
+    const closure = runtimeClosure(srcRoot, modules);
+    const reached = new Set(closure.files.map((f) => `${OWNED_RUNTIME_DIR}/${f}`));
+    const files = status.filter((r) => reached.has(r.path));
+    if (files.length > 0) out.set(name, { files, packages: closure.packages });
+  }
+  return out;
+}
+
 export async function buildCatalogListing(opts: CatalogListingOpts = {}): Promise<CatalogRow[]> {
   const rows: CatalogRow[] = [];
+  const runtimeCopies = opts.project === undefined
+    ? new Map<string, { files: RuntimeCopyRow[]; packages: string[] }>()
+    : await ownedRuntimeByGenerator(opts.project.projectRoot);
 
   for (const entry of listCatalog()) {
     const template = entry.ejectable ? readTemplate(entry.name) : undefined;
-    const install = installSetFor([entry]);
+    // A project that owns this generator's adapter copy installs what the COPY imports,
+    // not the runtime package — the same trade `meta eject` prints.
+    const owned = runtimeCopies.get(entry.name);
+    const install = owned === undefined
+      ? installSetFor([entry])
+      : installSetFor([entry], [], { generators: new Set([entry.name]), ...runtimeInstall(owned.packages) });
     const pkg = packageOf(entry.name) ?? "";
 
     const row: GeneratorCatalogRow = {
@@ -254,6 +303,7 @@ export async function buildCatalogListing(opts: CatalogListingOpts = {}): Promis
         kind: entry.ejectable ? "reference-template" : "package-only",
         ejectable: entry.ejectable,
         owned: opts.project === undefined ? null : opts.project.ownedNames.has(entry.name),
+        ...(owned !== undefined ? { runtimeCopy: owned.files } : {}),
       },
     };
 
@@ -269,7 +319,13 @@ export async function buildCatalogListing(opts: CatalogListingOpts = {}): Promis
       let probeError: string | undefined;
       let needsConfig: string[] | undefined;
       if (opts.probe !== undefined) {
-        const outcome = await probeOne(entry, project, opts.probe.metadata, opts.probe.scope);
+        const outcome = await probeOne(
+          entry,
+          project,
+          opts.probe.metadata,
+          opts.probe.scope,
+          opts.probe.sourceFiles,
+        );
         if ("count" in outcome) {
           wouldEmit = outcome.count;
           needsConfig = outcome.needsConfig;
@@ -390,6 +446,15 @@ export function renderCatalogText(rows: CatalogRow[], probed: boolean): string {
     if (!r.source.ejectable) marks.push("package-only");
     if (r.project?.wired) marks.push("WIRED");
     if (r.source.owned) marks.push("owned");
+    if (r.source.runtimeCopy !== undefined) {
+      // The adapter source this generator's output imports, compared to the package.
+      const differing = r.source.runtimeCopy.filter((c) => c.verdict === "differs").length;
+      marks.push(
+        differing === 0
+          ? "owned runtime: identical to the package"
+          : `owned runtime: ${differing} file(s) DIFFER from the package — meta eject --list`,
+      );
+    }
     if (probed && r.project?.wouldEmit !== null && r.project?.wouldEmit !== undefined) {
       const needs = r.project.needsConfig;
       marks.push(

package/src/lib/codegen-drift.ts

@@ -68,6 +68,16 @@ export interface CodegenDriftResult {
    * to end. Two doors asking one question must not answer it twice.
    */
   handEditedNames: string[];
+  /**
+   * Project-relative paths of generated files that carry a PRESERVED hand edit, sorted:
+   * the generated contribution is current (a fresh regen hashes to what we recorded
+   * writing) but the committed file differs from it. Not drift — `meta gen` keeps these
+   * edits by design — so they never set `clean` to false. Reported so the edits are
+   * VISIBLE: a validator weakened inside a generated file used to pass this gate in
+   * silence. The command decides whether they fail the build (`--forbid-hand-edits`).
+   * Never overlaps `driftedFiles`.
+   */
+  handEdited: string[];
   /** Set when the gate could not run (e.g. no outDir to compare against). */
   error?: string;
 }
@@ -138,6 +148,7 @@ export async function computeCodegenDrift(
       driftedFiles: [],
       lines: [],
       handEditedNames: [],
+      handEdited: [],
       error:
         "verify --codegen: no outDir configured — cannot locate the committed " +
         "generated output to diff against. Set 'outDir' (and/or per-target " +
@@ -207,6 +218,7 @@ export async function computeCodegenDrift(
     const driftedFiles = new Set<string>();
     const lines: string[] = [];
     const handEditedNames = new Set<string>();
+    const handEdited = new Set<string>();
 
     // Whether we have any record of what we wrote here. With records, the orphan
     // branch below can scope itself to our own output; with none, it cannot tell
@@ -286,6 +298,10 @@ export async function computeCodegenDrift(
               // nothing is proven, so the old byte verdict stands.
               driftedFiles.add(relKey);
               lines.push(`~ ${relKey} (committed content differs from a fresh regen)`);
+            } else {
+              // The generated contribution is current and the bytes still differ: a
+              // hand edit `meta gen` preserved. Not drift, but never silent either.
+              handEdited.add(relKey);
             }
           }
         }
@@ -298,6 +314,7 @@ export async function computeCodegenDrift(
       driftedFiles: sorted,
       lines,
       handEditedNames: [...handEditedNames].sort(),
+      handEdited: [...handEdited].sort(),
     };
   } finally {
     rmSync(tempRoot, { recursive: true, force: true });

package/src/lib/install-set.ts

@@ -20,7 +20,7 @@
 import { createRequire } from "node:module";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import type { GeneratorRegistryEntry } from "@metaobjectsdev/codegen-ts";
+import { HTTP_RUNTIME_PACKAGE, type GeneratorRegistryEntry } from "@metaobjectsdev/codegen-ts";
 import { cliVersion } from "./version.js";
 import { packageOf } from "./catalog.js";
 import type { PackageManifest } from "./package-manifest.js";
@@ -63,6 +63,13 @@ export function peerRangesOf(packageName: string): Record<string, string> {
   }
 }
 
+/** What an owned adapter copy changes about the install set — see `installSetFor`. */
+export interface OwnedRuntimeInstall {
+  generators: ReadonlySet<string>;
+  runtime: ReadonlyMap<string, string | undefined>;
+  dev: ReadonlyMap<string, string | undefined>;
+}
+
 export interface InstallSet {
   /** Build-time packages, `name@range`. */
   dev: string[];
@@ -114,6 +121,10 @@ export function installSetFor(
    *  catalog does not know them). Build-time, so dev — unless the runtime set already
    *  installs the package, which satisfies the build too. */
   templatePackages: readonly string[] = [],
+  /** ADR-0034 Amendment 3 (2026-09-24): generators whose adapter SOURCE was copied into the
+   *  project, and what that copy imports. Their output no longer imports the runtime package,
+   *  so it is not installed on their account; the copy's own imports are, instead. */
+  ownedRuntime?: OwnedRuntimeInstall,
 ): InstallSet {
   const version = cliVersion();
   const dev = new Map<string, string | undefined>();
@@ -123,7 +134,10 @@ export function installSetFor(
     const pkg = packageOf(entry.name);
     if (pkg !== undefined) addPackage(dev, pkg, `^${version}`);
 
-    for (const rt of entry.runtimePackages ?? []) addPackage(runtime, rt, `^${version}`);
+    for (const rt of entry.runtimePackages ?? []) {
+      if (ownedRuntime?.generators.has(entry.name) && rt === HTTP_RUNTIME_PACKAGE) continue;
+      addPackage(runtime, rt, `^${version}`);
+    }
 
     if (entry.runtimePeers !== undefined && entry.runtimePeers.length > 0) {
       // Ranges come from whichever runtime package declares these as peers — the union
@@ -137,6 +151,9 @@ export function installSetFor(
     }
   }
 
+  for (const [name, range] of ownedRuntime?.runtime ?? []) addPackage(runtime, name, range);
+  for (const [name, range] of ownedRuntime?.dev ?? []) addPackage(dev, name, range);
+
   for (const p of templatePackages) {
     if (!runtime.has(p)) addPackage(dev, p, `^${version}`);
   }

package/src/lib/runtime-eject.ts

@@ -0,0 +1,263 @@
+// ADR-0034 Amendment 3 (2026-09-24 ruling) — ejecting a helper hands over ALL of its code.
+//
+// `meta eject routes` used to copy a generator whose OUTPUT still imported the HTTP adapter
+// from `@metaobjectsdev/runtime-ts` — the mount helpers, filter parser, error envelopes and
+// pagination, which is where most route defects have lived. Owning the generator while the
+// code it emits calls into a package is half of owning it: a defect in the adapter still
+// waits on an upstream release.
+//
+// So eject also copies the adapter SOURCE the output depends on — the transitive closure of
+// relative imports from the entry module each generator's output names — into
+// `codegen/runtime/`, laid out exactly as the package's own `src/` so every relative import
+// in it resolves unchanged. Package imports are left as they are: what the closure reaches
+// outside the package is `@metaobjectsdev/metadata` (core: the filter-op vocabulary and the
+// canonical serializer) and third-party libraries (drizzle-orm, fastify, hono, zod, qs).
+//
+// The copies are VERBATIM. That is what makes "is my copy still the package's?" a byte
+// comparison and "what did upstream change?" a plain `diff -r` against the installed
+// package's `src/`, with no header to strip first.
+
+import { createRequire } from "node:module";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, relative, sep } from "node:path";
+import {
+  HTTP_RUNTIME_MODULES,
+  HTTP_RUNTIME_PACKAGE,
+  OWNED_RUNTIME_DIR,
+  type HttpRuntimeModule,
+} from "@metaobjectsdev/codegen-ts";
+import { compareOwnedCopy, type OwnedComparison } from "./owned-copy.js";
+import { cliVersion } from "./version.js";
+
+/**
+ * The ejectable generators whose OUTPUT imports the adapter tier, and the adapter modules
+ * it imports. `entity` is here for its allowlist TYPES only, which is one file.
+ */
+export const RUNTIME_ENTRIES: Readonly<Record<string, readonly HttpRuntimeModule[]>> = {
+  routes: ["drizzle-fastify"],
+  "routes-hono": ["hono"],
+  entity: ["allowlists"],
+};
+
+/** True iff ejecting `name` also copies adapter source. */
+export function ejectsRuntime(name: string): boolean {
+  return Object.hasOwn(RUNTIME_ENTRIES, name);
+}
+
+interface RuntimePackage {
+  /** `<root>/src` — the source the copies are taken from and compared against. */
+  srcRoot: string;
+  manifest: {
+    dependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+  };
+}
+
+/**
+ * The installed `@metaobjectsdev/runtime-ts`: its `src/` and its manifest.
+ *
+ * Resolves the package ENTRY and walks up to the manifest that names it, never
+ * `"<pkg>/package.json"`: the exports map does not export that subpath, and under real Node
+ * asking for it throws ERR_PACKAGE_PATH_NOT_EXPORTED (see `install-set.ts`). `src/` ships
+ * in the published package (`files: ["dist", "src", ...]`).
+ */
+export function resolveRuntimePackage(): RuntimePackage {
+  const req = createRequire(import.meta.url);
+  let dir = dirname(req.resolve(HTTP_RUNTIME_PACKAGE));
+  for (let hops = 0; hops < 8; hops++) {
+    const candidate = join(dir, "package.json");
+    if (existsSync(candidate)) {
+      const manifest = JSON.parse(readFileSync(candidate, "utf8")) as RuntimePackage["manifest"] & { name?: string };
+      if (manifest.name === HTTP_RUNTIME_PACKAGE) {
+        const srcRoot = join(dir, "src");
+        if (!existsSync(srcRoot)) {
+          throw new Error(`${HTTP_RUNTIME_PACKAGE} at ${dir} ships no src/ — cannot copy the adapter source.`);
+        }
+        return { srcRoot, manifest };
+      }
+    }
+    const up = dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  throw new Error(`could not locate the installed ${HTTP_RUNTIME_PACKAGE} package.`);
+}
+
+/** Relative (`./`, `../`) and bare module specifiers a source file imports or re-exports. */
+function specifiersOf(source: string): string[] {
+  const out: string[] = [];
+  // `import … from "x"` and the re-export forms (`export { … } from`, `export * from`) only —
+  // a bare `export function f() { return Array.from("…") }` must not read as an import.
+  const STATEMENT =
+    /(?:^|\n)\s*(?:import\s+[^;"']*?\s+from|export\s+(?:type\s+)?(?:\*(?:\s+as\s+\w+)?|\{[^}]*\})\s*from)\s*["']([^"']+)["']/g;
+  for (const m of source.matchAll(STATEMENT)) {
+    if (m[1] !== undefined) out.push(m[1]);
+  }
+  for (const m of source.matchAll(/(?:^|\n)\s*import\s*["']([^"']+)["']/g)) {
+    if (m[1] !== undefined) out.push(m[1]);
+  }
+  return out;
+}
+
+/** `@scope/name/sub` → `@scope/name`; `name/sub` → `name`. */
+function packageNameOf(spec: string): string {
+  const parts = spec.split("/");
+  return spec.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0]!;
+}
+
+function toPosix(p: string): string {
+  return p.split(sep).join("/");
+}
+
+export interface RuntimeClosure {
+  /** Source files, POSIX paths relative to the package's `src/`, sorted. */
+  files: string[];
+  /** Packages the closure imports (never `node:` builtins), sorted. */
+  packages: string[];
+}
+
+/** Every file the given adapter modules reach through relative imports, and what else they import. */
+export function runtimeClosure(srcRoot: string, modules: readonly HttpRuntimeModule[]): RuntimeClosure {
+  const files = new Set<string>();
+  const packages = new Set<string>();
+  const queue = modules.map((m) => `${HTTP_RUNTIME_MODULES[m].file}.ts`);
+  while (queue.length > 0) {
+    const rel = queue.shift()!;
+    if (files.has(rel)) continue;
+    const abs = join(srcRoot, rel);
+    if (!existsSync(abs)) {
+      throw new Error(`${HTTP_RUNTIME_PACKAGE}: ${rel} is imported but not shipped in src/.`);
+    }
+    files.add(rel);
+    for (const spec of specifiersOf(readFileSync(abs, "utf8"))) {
+      if (spec.startsWith("./") || spec.startsWith("../")) {
+        const target = toPosix(join(dirname(rel), spec)).replace(/\.js$/, ".ts");
+        queue.push(target.endsWith(".ts") ? target : `${target}.ts`);
+      } else if (!spec.startsWith("node:")) {
+        packages.add(packageNameOf(spec));
+      }
+    }
+  }
+  return { files: [...files].sort(), packages: [...packages].sort() };
+}
+
+export type RuntimeFileStatus = "created" | "preserved" | "replaced";
+
+export interface RuntimeFileResult {
+  /** Project-relative path of the copy. */
+  path: string;
+  status: RuntimeFileStatus;
+  /** How the copy ALREADY on disk compared to the package's source. Absent when there was none. */
+  comparison?: OwnedComparison | undefined;
+}
+
+export interface RuntimeEjectResult {
+  files: RuntimeFileResult[];
+  /** Packages the copied source imports — what the adopter now installs directly. */
+  packages: string[];
+}
+
+/**
+ * Copy the adapter source `names` emit imports of into `<cwd>/codegen/runtime/`.
+ * Never overwrites a file without `force`, the same rule the generator copy keeps.
+ */
+export async function ejectRuntime(cwd: string, names: readonly string[], force: boolean): Promise<RuntimeEjectResult> {
+  const modules = [...new Set(names.flatMap((n) => RUNTIME_ENTRIES[n] ?? []))];
+  if (modules.length === 0) return { files: [], packages: [] };
+  const { srcRoot } = resolveRuntimePackage();
+  const closure = runtimeClosure(srcRoot, modules);
+  const files: RuntimeFileResult[] = [];
+  for (const rel of closure.files) {
+    const source = await readFile(join(srcRoot, rel), "utf8");
+    const path = `${OWNED_RUNTIME_DIR}/${rel}`;
+    const abs = join(cwd, path);
+    const existing = existsSync(abs) ? await readFile(abs, "utf8") : undefined;
+    const comparison = existing === undefined ? undefined : await compareOwnedCopy(existing, source);
+    if (existing !== undefined && !force) {
+      files.push({ path, status: "preserved", comparison });
+      continue;
+    }
+    await mkdir(dirname(abs), { recursive: true });
+    await writeFile(abs, source, "utf8");
+    files.push({ path, status: existing === undefined ? "created" : "replaced", comparison });
+  }
+  return { files, packages: closure.packages };
+}
+
+/**
+ * The install lines the copied source needs, with ranges read from the runtime package's
+ * own manifest (never restated here). A `@metaobjectsdev/*` package moves with the CLI.
+ * A package that ships no types of its own gets its `@types/*` sibling as a dev dependency
+ * when the runtime package itself develops against one.
+ */
+export function runtimeInstall(packages: readonly string[]): {
+  runtime: Map<string, string | undefined>;
+  dev: Map<string, string | undefined>;
+} {
+  const { manifest } = resolveRuntimePackage();
+  const known = { ...manifest.peerDependencies, ...manifest.dependencies };
+  const runtime = new Map<string, string | undefined>();
+  const dev = new Map<string, string | undefined>();
+  for (const p of packages) {
+    runtime.set(p, p.startsWith("@metaobjectsdev/") ? `^${cliVersion()}` : known[p]);
+    const typesPkg = `@types/${p.replace(/^@/, "").replace("/", "__")}`;
+    const typesRange = manifest.devDependencies?.[typesPkg];
+    if (typesRange !== undefined) dev.set(typesPkg, typesRange);
+  }
+  return { runtime, dev };
+}
+
+/** One owned adapter file, compared to the package it came from. */
+export interface RuntimeCopyRow {
+  path: string;
+  verdict: OwnedComparison["verdict"] | "not-in-package";
+  localOnly: number;
+  referenceOnly: number;
+}
+
+function listTs(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const abs = join(dir, entry);
+    if (statSync(abs).isDirectory()) out.push(...listTs(abs));
+    else if (entry.endsWith(".ts")) out.push(abs);
+  }
+  return out;
+}
+
+/**
+ * Every file under `<cwd>/codegen/runtime/`, compared to the installed package's source.
+ * Empty when the project owns no adapter copy. `not-in-package` is a file the package does
+ * not ship — your own addition, or one upstream deleted or renamed.
+ */
+export async function runtimeCopyStatus(cwd: string): Promise<RuntimeCopyRow[]> {
+  const root = join(cwd, OWNED_RUNTIME_DIR);
+  if (!existsSync(root)) return [];
+  let srcRoot: string;
+  try {
+    srcRoot = resolveRuntimePackage().srcRoot;
+  } catch {
+    return [];
+  }
+  const rows: RuntimeCopyRow[] = [];
+  for (const abs of listTs(root).sort()) {
+    const rel = toPosix(relative(root, abs));
+    const path = `${OWNED_RUNTIME_DIR}/${rel}`;
+    const upstream = join(srcRoot, rel);
+    if (!existsSync(upstream)) {
+      rows.push({ path, verdict: "not-in-package", localOnly: 0, referenceOnly: 0 });
+      continue;
+    }
+    const cmp = await compareOwnedCopy(readFileSync(abs, "utf8"), readFileSync(upstream, "utf8"));
+    rows.push({ path, verdict: cmp.verdict, localOnly: cmp.localOnly, referenceOnly: cmp.referenceOnly });
+  }
+  return rows;
+}
+
+/** The command that shows exactly how one owned file differs from the installed package's. */
+export function runtimeDiffCommand(path: string): string {
+  const rel = path.startsWith(`${OWNED_RUNTIME_DIR}/`) ? path.slice(OWNED_RUNTIME_DIR.length + 1) : path;
+  return `diff -u node_modules/${HTTP_RUNTIME_PACKAGE}/src/${rel} ${OWNED_RUNTIME_DIR}/${rel}`;
+}