fix(codegen-ts): the routes template invites a copy that does not compile

FR-040's answer to "MetaObjects does not ship a codegen package per framework" is
that you own the generator and retarget its emit. Most tiers make that true by
RELOCATING the composition into the ejected file — `entity.ts` and `queries.ts`
carry the composer's body verbatim, so every primitive they call is public by
construction. The routes tier does not: its composition is richer (M:N junction
traversal, TPH per-subtype route sets) and stays in the engine as
`renderRoutesFile`, so the template's `customize:` note tells an adopter
retargeting to another HTTP framework to copy that body out of the package source.

Follow that instruction and you get a file that does not compile. Of the sixteen
symbols the body imports from inside the package, fourteen resolve from
`@metaobjectsdev/codegen-ts` and two do not — `routesHandlerName` and
`TPH_POLYMORPHIC_VERBS`, both `TS2305: has no exported member`. Verified against
the package's own exports map, not inferred: a probe importing all sixteen from the
public entry reported exactly those two.

It matters more than the two lines suggest. HTTP framework is the tier an adopter is
MOST likely to have an opinion about — anyone outside Fastify and Hono has to
retarget it, and everyone else can leave every other tier alone. So the one escape
that had to work is the one that did not, and it failed at the point where the
adopter has already committed to the approach.

Both are exported now, and the gate is the durable half. It DERIVES the required set
from `renderRoutesFile`'s own import statements rather than restating them, because a
hand-kept list reproduces the defect one level up: the body gains an import, nobody
re-reads the list, and the escape silently breaks again. It also asserts its own
premise — that the reference template still contains the sentence inviting the copy —
so if that instruction is withdrawn the test fails and asks to be re-read rather than
quietly guarding nothing.

Proven by breaking it: with `routesHandlerName` un-exported the gate goes red naming
it, and green again when restored.

Found while auditing how tightly the generated surface couples to the libraries the
maintainer's own adopter estates happen to use. All seven are TypeScript on Drizzle
with Postgres or D1, so the estate loop cannot see this class of problem — an escape
hatch nobody in the estate set needs to take.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01At3v6M6uqECZ2Sb5eUv6YY

Author: dmealing

server/typescript/packages/codegen-ts/src/index.ts

@@ -83,7 +83,12 @@ export { warnRetiredCodegenAttrs } from "./retired-codegen-attrs.js";
 
 export { formatTs } from "./format.js";
 
-export { pluralize, columnNameFromField, tableNameFromEntity, viewNameFromProjection } from "./naming.js";
+export { pluralize, columnNameFromField, tableNameFromEntity, viewNameFromProjection, routesHandlerName } from "./naming.js";
+// routesHandlerName is public for the same reason the routes-expose members below are: the
+// routes reference template tells an adopter retargeting to another HTTP framework to copy
+// `renderRoutesFile`'s body out of the package source, and that body names this. See the
+// owned-composition-imports gate in test/ — it derives the required set from that body rather
+// than trusting this list to stay complete.
 
 export { packageToPath, entityOutputPath, crossEntitySpecifier, barrelEntrySpecifier, relativeModuleSpecifier, entityModuleSpecifier, siblingSpecifier, barrelModuleSpecifier } from "./import-path.js";
 export type { OutputLayout, ResolvedTarget } from "./import-path.js";
@@ -194,7 +199,7 @@ export { renderEntityConstants, resourcePath } from "./templates/entity-constant
 export { renderQueriesFile } from "./templates/queries-file.js";
 // #348 — which CRUD verbs a generated routes file mounts. Public because an OWNED
 // routes generator (ADR-0034) composes the same render call and needs the same option.
-export { CRUD_VERBS, resolveExpose, intersectExpose, exposeLine } from "./routes-expose.js";
+export { CRUD_VERBS, TPH_POLYMORPHIC_VERBS, resolveExpose, intersectExpose, exposeLine } from "./routes-expose.js";
 export type { CrudVerb, ExposeOption } from "./routes-expose.js";
 export { renderRoutesFile } from "./templates/routes-file.js";
 export { renderRoutesFileHono } from "./templates/routes-file-hono.js";

server/typescript/packages/codegen-ts/test/owned-composition-imports.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * A reference template that says "copy this body out of the package source" is making a promise
+ * the exports map has to keep.
+ *
+ * ADR-0034 gives an adopter an ownable copy of each generator, and most tiers relocate the whole
+ * composition into that copy — `entity.ts` and `queries.ts` carry the composer's body verbatim, so
+ * every primitive they call is public by construction. The routes tier does NOT: its composition
+ * (M:N junction traversal, TPH per-subtype route sets) stays in the engine as `renderRoutesFile`,
+ * and the template's `customize:` note tells an adopter retargeting to another HTTP framework to
+ * copy that body out of the package source.
+ *
+ * That instruction was UNTRUE. Measured 2026-09-07 against the published surface: of the sixteen
+ * symbols `renderRoutesFile`'s body imports from inside the package, fourteen resolved from
+ * `@metaobjectsdev/codegen-ts` and two did not — `routesHandlerName` and `TPH_POLYMORPHIC_VERBS`,
+ * both `TS2305: has no exported member`. So the documented escape ended in a file that does not
+ * compile, on the ONE tier every adopter outside Fastify and Hono has to retarget. The whole
+ * ownership story is what the project offers instead of a codegen package per framework (FR-040),
+ * and it was load-bearing exactly where it was broken.
+ *
+ * This gate DERIVES the required set from the body rather than restating it, because a hand-kept
+ * list is the same defect one level up: `renderRoutesFile` gains an import, nobody re-reads this
+ * file, and the escape silently breaks again.
+ *
+ * It is deliberately scoped to the compositions a template tells you to copy. A body nobody is
+ * invited to copy owes nothing.
+ */
+
+const PKG = join(import.meta.dir, "..");
+
+/** Compositions a reference template instructs an adopter to copy out of the package source. */
+const COPYABLE_COMPOSITIONS = [
+  {
+    body: "src/templates/routes-file.ts",
+    invitedBy: "src/reference/routes.ts",
+    // The sentence in that template that makes the promise. Matched on the fragment that fits
+    // one line, because the header is comment-wrapped and the full sentence spans two. If it is
+    // reworded, this test's premise changed and the pairing has to be re-read rather than the
+    // string patched.
+    promise: "copy `renderRoutesFile`'s body out",
+  },
+] as const;
+
+/** Named imports a module takes from paths INSIDE the package (relative specifiers). */
+function internalNamedImports(source: string): string[] {
+  const names = new Set<string>();
+  // `import { a, type B, c as d } from "./x.js"` / "../y.js" — multi-line bodies included.
+  const re = /import\s*(?:type\s+)?\{([^}]*)\}\s*from\s*"(\.[^"]*)"/g;
+  for (const m of source.matchAll(re)) {
+    for (const raw of m[1]!.split(",")) {
+      const name = raw
+        .replace(/^\s*type\s+/, "")
+        .split(/\s+as\s+/)[0]!
+        .trim();
+      if (name) names.add(name);
+    }
+  }
+  return [...names].sort();
+}
+
+/** Everything the package's public entry re-exports, by name. */
+function publicSurface(): Set<string> {
+  const index = readFileSync(join(PKG, "src/index.ts"), "utf8");
+  const names = new Set<string>();
+  for (const m of index.matchAll(
+    /export\s*(?:type\s+)?\{([^}]*)\}\s*from\s*"[^"]*"/g,
+  )) {
+    for (const raw of m[1]!.split(",")) {
+      const part = raw.replace(/^\s*type\s+/, "").trim();
+      // `a as b` re-exports under b — the name an adopter can import.
+      const name = (part.includes(" as ") ? part.split(/\s+as\s+/)[1] : part)?.trim();
+      if (name) names.add(name);
+    }
+  }
+  for (const m of index.matchAll(
+    /export\s+(?:declare\s+)?(?:const|function|class|type|interface)\s+([A-Za-z_$][\w$]*)/g,
+  )) {
+    names.add(m[1]!);
+  }
+  return names;
+}
+
+describe("a composition an adopter is told to copy imports only public API", () => {
+  const surface = publicSurface();
+
+  for (const { body, invitedBy, promise } of COPYABLE_COMPOSITIONS) {
+    test(`${body} — every internal import is reachable from the package entry`, () => {
+      const template = readFileSync(join(PKG, invitedBy), "utf8");
+      // The premise: the reference template really does invite the copy. If this fails, the
+      // instruction moved or was withdrawn — decide which before touching the assertion below.
+      expect(template).toContain(promise);
+
+      const required = internalNamedImports(readFileSync(join(PKG, body), "utf8"));
+      expect(required.length).toBeGreaterThan(0);
+
+      const missing = required.filter((n) => !surface.has(n));
+      expect(missing).toEqual([]);
+    });
+  }
+});