@metaobjectsdev/codegen-ts 1.0.5-rc.1 → 1.0.5-rc.3

package/src/generators/api-model.ts

@@ -118,8 +118,7 @@ import { responseShape } from "../templates/find-inbound.js";
 import { isTphSubtype } from "../templates/zod-validators.js";
 import { isTphDiscriminatorBase } from "../templates/tph-discriminator.js";
 import { isCallableEntity } from "../templates/callable-file.js";
-import { hasAnyRdbSource } from "../source-detect.js";
-import { servedPath } from "../api-surface.js";
+import { servedPath, servesReadApi } from "../api-surface.js";
 import { isProjection } from "../projection/projection-detector.js";
 import { buildPkMap } from "../pk-resolver.js";
 import { buildRelationMap, type RelationEntry, type RelationMap } from "../relation-resolver.js";
@@ -356,8 +355,9 @@ function stripTs(path: string): string {
 // ---------------------------------------------------------------------------
 
 /** Mirror of the queries generator's filter (queries-file.ts `skipNonQueryable`
- *  = `hasAnyRdbSource(e) && !isTphSubtype(e)`, #248 R2). A queryable object is
- *  any source-backed, non-TPH-subtype object:
+ *  = `servesReadApi(e) && !isTphSubtype(e)`, #248 R2). A queryable object is
+ *  any source-backed, non-abstract, non-TPH-subtype object:
+ *   • An abstract object has no table of its own, only a type-only shape.
  *   • An object with no declared/inherited source.rdb (of ANY kind) isn't
  *     backed by any store → the queries/routes/validation generators emit no
  *     CRUD for it. Value objects are subsumed here: value purity (ADR-0028)
@@ -370,7 +370,7 @@ function stripTs(path: string): string {
  *  per-subtype polymorphic helpers + subpaths are a documented deferral — see
  *  the module header.) */
 function isQueryable(obj: MetaObject): boolean {
-  return hasAnyRdbSource(obj) && !isTphSubtype(obj);
+  return servesReadApi(obj) && !isTphSubtype(obj);
 }
 
 function buildEntityUnit(
@@ -405,7 +405,7 @@ function buildEntityUnit(
     symbols.push(...dataAccessSymbols(obj, ctx, root, layout));
     symbols.push(...validationSymbols(obj, entityMod));
     // REST needs no gate of its own: the routes generator's built-in filter is
-    // `hasAnyRdbSource && !isTphSubtype` — exactly isQueryable — so every queryable
+    // `servesReadApi && !isTphSubtype` — exactly isQueryable — so every queryable
     // object gets routes. (Its `filter` option can narrow that further; this builder
     // reads the model, not the wired generator set, and cannot see it. See the module
     // header.)
@@ -415,10 +415,11 @@ function buildEntityUnit(
     if (includeHono) symbols.push(...restHonoSymbols(obj, layout, apiPrefix));
   }
 
-  // --- relation: the drizzle relations() export, when the resolver derives a
-  //     relations() block for this entity (1:N belongs-to + inverse many, M:N
-  //     @through). Independent of isQueryable — a relations() block is emitted by
-  //     the entity file regardless. ---
+  // --- relation: the drizzle relations() export, when the resolver files entries
+  //     under this entity (1:N belongs-to + inverse many, M:N @through). The map
+  //     keys by the entity whose module renders the block — the discriminator
+  //     base, for a TPH subtype; an abstract entity emits a value-object module
+  //     and never carries one. Independent of isQueryable. ---
   const relationSym = relationSymbol(obj, entityMod, relationMap);
   if (relationSym !== undefined) symbols.push(relationSym);
 

package/src/generators/queries-file.ts

@@ -2,7 +2,7 @@ import type { MetaObject } from "@metaobjectsdev/metadata";
 import { perEntity, type Generator, type GeneratorFactory } from "../generator.js";
 import { renderQueriesFile } from "../templates/queries-file.js";
 import { isTphSubtype } from "../templates/zod-validators.js";
-import { hasAnyRdbSource } from "../source-detect.js";
+import { servesReadApi } from "../api-surface.js";
 import { formatTs } from "../format.js";
 import { entityOutputPath } from "../import-path.js";
 import { effectivePackage } from "../docs-paths.js";
@@ -25,7 +25,12 @@ export interface QueriesFileOpts {
 // FR-017 Tier 2: TPH subtypes are ALSO skipped — they emit no standalone
 // queries file. Their per-subtype CRUD helpers live in the discriminator
 // base's queries file (which targets the single shared table).
-const skipNonQueryable = (e: MetaObject): boolean => hasAnyRdbSource(e) && !isTphSubtype(e);
+//
+// Abstract objects are skipped as well (`servesReadApi`): an abstract level inherits its
+// base's source but has no table of its own — only a type-only shape — so its queries
+// module imported a table and schemas that do not exist. The hooks tier already gated on
+// this predicate; the queries and routes tiers now agree with it.
+const skipNonQueryable = (e: MetaObject): boolean => servesReadApi(e) && !isTphSubtype(e);
 
 export const queriesFile = function queriesFile(opts?: QueriesFileOpts): Generator {
   const userFilter = opts?.filter;

package/src/generators/routes-file-hono.ts

@@ -1,7 +1,7 @@
 import type { MetaObject } from "@metaobjectsdev/metadata";
 import { perEntity, type Generator, type GeneratorFactory } from "../generator.js";
 import { renderRoutesFileHono } from "../templates/routes-file-hono.js";
-import { hasAnyRdbSource } from "../source-detect.js";
+import { servesReadApi } from "../api-surface.js";
 import { formatTs } from "../format.js";
 import { entityOutputPath } from "../import-path.js";
 import { isTphSubtype } from "../templates/zod-validators.js";
@@ -41,7 +41,8 @@ export interface RoutesFileHonoOpts {
  * them (ERR_UNKNOWN_ATTR).
  *
  * #248 R2: an object with no declared/inherited source.rdb (of ANY kind) isn't
- * backed by any store — gated by `hasAnyRdbSource` (does NOT add TPH handling;
+ * backed by any store — gated by `servesReadApi`, which also excludes abstract objects
+ * (no table of their own to mount) (does NOT add TPH handling;
  * that gap is pre-existing and out of scope here).
  */
 export const routesFileHono = function routesFileHono(opts?: RoutesFileHonoOpts): Generator {
@@ -51,7 +52,7 @@ export const routesFileHono = function routesFileHono(opts?: RoutesFileHonoOpts)
   // written out twice a later edit to one silently makes an entity either stop emitting
   // without being named as held back, or get warned about while still emitting.
   const passesOtherGates = (e: MetaObject): boolean =>
-    hasAnyRdbSource(e) && userFilter(e);
+    servesReadApi(e) && userFilter(e);
   const generator: Generator = {
     name: "routes-file-hono",
     // Marks this as the Hono routes generator so the runner can aggregate

package/src/generators/routes-file.ts

@@ -2,7 +2,7 @@ import type { MetaObject } from "@metaobjectsdev/metadata";
 import { perEntity, type Generator, type GeneratorFactory } from "../generator.js";
 import { renderRoutesFile } from "../templates/routes-file.js";
 import { isTphSubtype } from "../templates/zod-validators.js";
-import { hasAnyRdbSource } from "../source-detect.js";
+import { servesReadApi } from "../api-surface.js";
 import { formatTs } from "../format.js";
 import { entityOutputPath } from "../import-path.js";
 import { resolveExpose, type ExposeOption } from "../routes-expose.js";
@@ -33,7 +33,8 @@ export interface RoutesFileOpts {
  *
  * #248 R2: an object with no declared/inherited source.rdb (of ANY kind) isn't
  * backed by any store — routes against it would import Drizzle table/allowlist
- * exports the entity-file generator never emits. Gated by `hasAnyRdbSource`.
+ * exports the entity-file generator never emits. Gated by `servesReadApi`, which also
+ * excludes abstract objects: an abstract level has no table of its own to mount.
  *
  * FR-017 Tier 2: TPH subtypes get no standalone routes file — their per-subtype
  * route set lives in the discriminator base's routes file.
@@ -44,7 +45,7 @@ export const routesFile = function routesFile(opts?: RoutesFileOpts): Generator
     name: "routes-file",
     // Always set: AND-composes the built-in gates with the optional user filter.
     filter: (e: MetaObject) =>
-      hasAnyRdbSource(e) && !isTphSubtype(e) && userFilter(e),
+      servesReadApi(e) && !isTphSubtype(e) && userFilter(e),
     generate: perEntity(async (entity, ctx) => {
       if (!ctx.renderContext) {
         throw new Error("routes-file: renderContext is required (provided by runGen)");

package/src/index.ts

@@ -138,7 +138,7 @@ export { renderEntityMetaFile, entityMetaFileName, entityMetaSpecifier } from ".
 // react) to dispatch polymorphic/per-subtype emission and skip subtype files.
 export { isTphDiscriminatorBase, tphConcreteSubtypes, collectTphSubtypeFields, tphPlan, tphRouteSegment } from "./templates/tph-discriminator.js";
 export type { TphPlan, TphSubtypePlan } from "./templates/tph-discriminator.js";
-export { isTphSubtype, tphDiscriminatorBase, tphDiscriminatorPin } from "./templates/zod-validators.js";
+export { isTphSubtype, tphDiscriminatorBase, tphDiscriminatorPin, tphStorageName, tphStorageObject } from "./templates/zod-validators.js";
 
 // The ONE sortability rule. It builds the server-side `<Entity>SortAllowlist` and the
 // client-side sort union, and it is public so a UI-tier generator (a data-grid column

package/src/reference/queries.ts

@@ -50,7 +50,7 @@ import {
   isProjection,
   isWriteThrough,
   isTphSubtype,
-  hasAnyRdbSource,
+  servesReadApi,
   hasAutoSetFields,
   renderQueriesFile, // engine composer — used for the delegated variants
   formatTs,
@@ -146,7 +146,9 @@ export interface QueriesFileOpts {
 // loadable value ever has hasAnyRdbSource === true). TPH subtypes emit no
 // standalone queries file either — their per-subtype CRUD helpers live in the
 // discriminator base's queries file (which targets the single shared table).
-const skipNonQueryable = (e: MetaObject): boolean => hasAnyRdbSource(e) && !isTphSubtype(e);
+// Abstract objects are skipped too (`servesReadApi`): an abstract level has no table of
+// its own, only a type-only shape, so a queries module for it cannot compile.
+const skipNonQueryable = (e: MetaObject): boolean => servesReadApi(e) && !isTphSubtype(e);
 
 export const queriesFile = function queriesFile(opts?: QueriesFileOpts): Generator {
   const userFilter = opts?.filter;

package/src/reference/routes-hono.ts

@@ -35,7 +35,7 @@ import {
   resolveExpose,
   type ExposeOption,
   isTphSubtype,
-  hasAnyRdbSource,
+  servesReadApi,
   formatTs,
   entityOutputPath,
   effectivePackage,
@@ -64,7 +64,7 @@ export const routesFileHono = function routesFileHono(opts?: RoutesFileHonoOpts)
   // without being named as held back, or get warned about while still emitting.
   // (Same shape as tanstack's grid generator, which factors it the same way.)
   const passesOtherGates = (e: MetaObject): boolean =>
-    hasAnyRdbSource(e) && userFilter(e);
+    servesReadApi(e) && userFilter(e);
   const generator: Generator = {
     name: "routes-file-hono",
     // Marks this as the Hono routes generator so the runner can aggregate

package/src/reference/routes.ts

@@ -43,7 +43,7 @@ import {
   resolveExpose,
   type ExposeOption,
   isTphSubtype,
-  hasAnyRdbSource,
+  servesReadApi,
   formatTs,
   entityOutputPath,
   effectivePackage,
@@ -72,9 +72,10 @@ export const routesFile = function routesFile(opts?: RoutesFileOpts): Generator
     // base's); AND-composed with your filter.
     // #248 R2: an object with no declared/inherited source.rdb (of ANY kind) isn't
     // backed by any store — routes against it would import Drizzle table/allowlist
-    // exports the entity file never emits. Gated by hasAnyRdbSource.
+    // exports the entity file never emits. Gated by servesReadApi, which also skips
+    // abstract objects: an abstract level has no table of its own to mount.
     filter: (e: MetaObject) =>
-      hasAnyRdbSource(e) && !isTphSubtype(e) && userFilter(e),
+      servesReadApi(e) && !isTphSubtype(e) && userFilter(e),
     generate: perEntity(async (entity, ctx) => {
       if (!ctx.renderContext) {
         throw new Error("routes-file: renderContext is required (provided by runGen)");

package/src/relation-resolver.ts

@@ -18,6 +18,8 @@ import {
   stripPackage,
 } from "@metaobjectsdev/metadata";
 import { variableNameFromEntity } from "./naming.js";
+import { hasWritableRdbSource } from "./source-detect.js";
+import { tphStorageObject } from "./templates/zod-validators.js";
 import { isProjection } from "./projection/projection-detector.js";
 
 export interface RelationEntry {
@@ -55,8 +57,16 @@ export type RelationMap = Map<string, RelationEntry[]>;
 /**
  * Walk all entities, collect relationship children, and also register inverse
  * many() sides on the target entity.
+ *
+ * `onWarn`, when supplied, receives one line per M:N relationship whose junction FKs
+ * could not be derived: the entry is skipped (a route that mounts nothing is an
+ * ABSENCE, not an error), and the warning is the only thing that says so. The runner
+ * passes its warnings channel; callers without one keep the silent skip.
  */
-export function buildRelationMap(root: MetaRoot): RelationMap {
+export function buildRelationMap(
+  root: MetaRoot,
+  onWarn?: (msg: string) => void,
+): RelationMap {
   const result: RelationMap = new Map();
 
   const ensure = (name: string): RelationEntry[] => {
@@ -64,12 +74,71 @@ export function buildRelationMap(root: MetaRoot): RelationMap {
     return result.get(name)!;
   };
 
+  // Files a CARDINALITY-ONE entry under the entity whose module renders the
+  // relations() block. A TPH subtype has no module of its own — it is folded into
+  // the discriminator base's single table, and the block renders on the BASE's.
+  // So an entry must be filed under the entity that actually renders it, or it is
+  // silently never emitted. `tphStorageName` is the seam for exactly this (its own
+  // doc says "for the name-keyed relation map"); the TARGET side of relations-block
+  // already resolves through it — only the SOURCE side was keyed raw.
+  //
+  // Because `obj.relationships()` RESOLVES, a base-declared relationship is reached
+  // again through every subtype and would now land on the same key repeatedly, so an
+  // entry structurally identical to one already filed is skipped. A name that collides
+  // with a DIFFERENT shape is a real conflict the base's single block cannot express:
+  // it is reported through `onWarn` rather than silently overwritten, because a
+  // navigation that quietly resolves to another subtype's target is the worse failure.
+  // True when a module renders a relations() block for this storage object — the
+  // question the map's contract asks, not either cause of its answer. Both
+  // non-abstractness and a writable source.rdb are required: the entity file
+  // routes an object failing EITHER to renderValueObjectFile, which emits no
+  // block. The oracle's tableBackedObjects walk makes the same exclusion. Filing
+  // an entry without it would only document, in `meta docs`/api-model, a
+  // `<Entity>Relations` export that no module emits.
+  const rendersRelationsBlock = (storing: MetaObject): boolean =>
+    !storing.isAbstract && hasWritableRdbSource(storing);
+
+  const push = (obj: MetaObject, entry: RelationEntry): void => {
+    const storing = tphStorageObject(obj);
+    if (!rendersRelationsBlock(storing)) return;
+    const key = storing.name;
+    const entries = ensure(key);
+    const clash = entries.find((e) => e.name === entry.name);
+    if (clash !== undefined) {
+      const same =
+        clash.cardinality === entry.cardinality &&
+        clash.targetEntity === entry.targetEntity &&
+        clash.fkField === entry.fkField;
+      if (!same) {
+        onWarn?.(
+          `relationship "${entry.name}" on entity "${obj.name}" gets no relations() entry: ` +
+            `"${key}" already carries a different "${entry.name}" ` +
+            `(-> ${clash.targetEntity} via ${clash.fkField}), and a single-table hierarchy ` +
+            `renders ONE relations() block on the base, which cannot hold both. ` +
+            `Rename one of them.`,
+        );
+      }
+      return;
+    }
+    entries.push(entry);
+  };
+
   for (const obj of root.objects()) {
     // Projections (source.dbView) are view-backed; they never emit a relations()
     // block, and their inherited belongs-to relationships would otherwise register
     // a spurious inverse-many on the target entity.
     if (isProjection(obj)) continue;
 
+    // An ABSTRACT level's own declarations do not file. Its FK column reaches the
+    // base's single table only through a CONCRETE @discriminatorValue descendant
+    // (collectTphSubtypeFields folds effective fields per concrete subtype), and
+    // that descendant's RESOLVING relationships() walk reaches this same
+    // relationship and files the identical entry — the dedupe collapses the
+    // copies. With no concrete descendant there is no folded column and no rows to
+    // navigate, so absence is the honest output: an entry would make the base's
+    // relations() block name a column the table does not have.
+    if (obj.isAbstract) continue;
+
     for (const child of obj.relationships()) {
       // ADR-0039: resolving — a relationship may inherit @cardinality via extends.
       const cardinality = child.attr(RELATIONSHIP_ATTR_CARDINALITY) as string | undefined;
@@ -79,7 +148,12 @@ export function buildRelationMap(root: MetaRoot): RelationMap {
       // many(junction) navigation on the source.
       // ADR-0039: resolving — @through may be inherited via extends.
       if (cardinality === CARDINALITY_MANY && child.attr(RELATIONSHIP_ATTR_THROUGH) !== undefined) {
-        const m2m = buildM2mEntry(obj, child as MetaRelationship, root);
+        const m2m = buildM2mEntry(obj, child as MetaRelationship, root, onWarn);
+        // NOT re-keyed to the storage base: the ROUTES tier reads this map to mount
+        // an M:N under EACH concrete subtype's segment, so it needs the per-subtype
+        // entries. Collapsing them onto the base key silently reduces four mounts to
+        // one. Only the cardinality-one path below is re-keyed, because that is the
+        // one the relations() block renders on the base's module.
         if (m2m) ensure(obj.name).push(m2m);
         continue;
       }
@@ -106,7 +180,7 @@ export function buildRelationMap(root: MetaRoot): RelationMap {
       const fkField = matching.fields[0];
       if (!fkField) continue;
 
-      ensure(obj.name).push({
+      push(obj, {
         name: child.name,
         cardinality: "one",
         targetEntity,
@@ -131,7 +205,6 @@ export function buildRelationMap(root: MetaRoot): RelationMap {
   for (const junctionName of collectJunctionNames(root)) {
     const junction = root.findObject(junctionName);
     if (!junction) continue;
-    const entries = ensure(junctionName);
     for (const ref of junction.referenceIdentities()) {
       const targetRaw = ref.targetEntity;
       const fkField = ref.fields[0];
@@ -143,7 +216,7 @@ export function buildRelationMap(root: MetaRoot): RelationMap {
       const refName = ref.name && ref.name.length > 0
         ? ref.name
         : variableNameFromEntity(targetEntity);
-      entries.push({
+      push(junction, {
         name: refName,
         cardinality: "one",
         targetEntity,
@@ -174,12 +247,16 @@ function collectJunctionNames(root: MetaRoot): Set<string> {
  * Build the source-side M:N navigation entry: derive the junction FK fields from
  * the junction's two identity.reference children (the SSOT), handling hetero /
  * directed-self-join / symmetric. Returns null (skips the entry) if derivation
- * fails — the loader validation pass surfaces the actionable error separately.
+ * fails, reporting the derivation's own reason through `onWarn` when supplied —
+ * the loader's rules never check subject pairing, so a model can load clean and
+ * still carry a junction this pass cannot pair (e.g. one whose identity.reference
+ * names a concrete subtype of the declaring entity).
  */
 function buildM2mEntry(
   source: MetaObject,
   rel: MetaRelationship,
   root: MetaRoot,
+  onWarn?: (msg: string) => void,
 ): RelationEntry | null {
   // ADR-0039: resolving — @objectRef/@through may be inherited via extends.
   const targetRaw = rel.attr(RELATIONSHIP_ATTR_OBJECT_REF) as string | undefined;
@@ -188,7 +265,13 @@ function buildM2mEntry(
   let fields;
   try {
     fields = deriveM2MFields(rel, source, root);
-  } catch {
+  } catch (err) {
+    onWarn?.(
+      `M:N relationship "${rel.name}" on entity "${source.name}" gets no traversal route: its ` +
+        `@through junction "${stripPackage(throughRaw)}" could not be paired — ` +
+        `${err instanceof Error ? err.message : String(err)}. The model loads, so the run ` +
+        `continues, but the endpoint is absent (a 404).`,
+    );
     return null;
   }
   return {

package/src/runner.ts

@@ -486,7 +486,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
 
   // 3. Build shared render state once.
   const pkMap = buildPkMap(root);
-  const relationMap = buildRelationMap(root);
+  const relationMap = buildRelationMap(root, (m) => warnings.push(m));
   // ADR-0044/#228 — the ENTITY-tier collision domain is the run's EMITTED
   // `object.value` SET (NOT any per-payload closure): value-object module
   // filenames + `packageOf` are per-run/global, so the emitted-name map is built

package/src/templates/drizzle-schema.ts

@@ -25,7 +25,8 @@ import { resolveTableSchema } from "@metaobjectsdev/metadata";
 import { renderEnumIntCustomType } from "./enum-int-codec.js";
 import { renderRelationsBlock } from "./relations-block.js";
 import { renderDocsFor } from "./jsdoc.js";
-import { collectTphSubtypeFields } from "./tph-discriminator.js";
+import { collectTphSubtypeFields, tphConcreteSubtypes } from "./tph-discriminator.js";
+import { tphStorageObject } from "./zod-validators.js";
 import { effectivePackage } from "../docs-paths.js";
 
 /**
@@ -411,7 +412,19 @@ interface FkInfo {
 /** Pre-pass: map fkFieldName → FkInfo for this entity's effective (own + inherited) identity.reference children. */
 function buildFkMapForEntity(obj: MetaObject, ctx: RenderContext): Map<string, FkInfo> {
   const result = new Map<string, FkInfo>();
-  for (const ref of obj.referenceIdentities()) {
+  // FR-017 TPH: a discriminator base's table carries every concrete subtype's folded
+  // columns (collectTphSubtypeFields), so it carries their FKs too — otherwise a reference
+  // declared on a subtype, or on an abstract level between it and the base, lands as a
+  // plain column. Same effective, not-already-on-the-base rule as the column fold.
+  // A copy: referenceIdentities() is the node's cached array, and loaded metadata is read-only.
+  const refs = [...obj.referenceIdentities()];
+  const baseRefNames = new Set(refs.map((r) => r.name));
+  for (const sub of tphConcreteSubtypes(obj, ctx.loadedRoot)) {
+    for (const ref of sub.referenceIdentities()) {
+      if (!baseRefNames.has(ref.name)) refs.push(ref);
+    }
+  }
+  for (const ref of refs) {
     // @enforce: false → logical-only reference. Skip the .references() emission;
     // the column stays plain. Drizzle's relations() block (driven by
     // relation-resolver) still includes the relationship for query navigation.
@@ -419,6 +432,8 @@ function buildFkMapForEntity(obj: MetaObject, ctx: RenderContext): Map<string, F
     const fkFieldNames = ref.fields;
     if (fkFieldNames.length === 0) continue;
     const fkField = fkFieldNames[0]!;
+    // Two subtypes declaring the same reference fold to one column with one FK.
+    if (result.has(fkField)) continue;
     const targetName = ref.targetEntity;
     if (!targetName) continue;
     // @references may be authored bare OR package-qualified, and the loader can
@@ -427,10 +442,12 @@ function buildFkMapForEntity(obj: MetaObject, ctx: RenderContext): Map<string, F
     // relation-resolver, which already does this.
     const targetObj = ctx.loadedRoot.findObject(stripPackage(targetName));
     if (!targetObj) continue;
+    // A TPH subtype has no table const of its own; its rows live in the base's table.
+    const storage = tphStorageObject(targetObj);
     const targetPkField = ref.resolvedTargetPkField(ctx.loadedRoot) ?? "id";
     result.set(fkField, {
-      targetVarName: ctx.collectionName(targetObj.name),
-      targetEntityName: targetObj.name,
+      targetVarName: ctx.collectionName(storage.name),
+      targetEntityName: storage.name,
       targetPkField,
     });
   }

package/src/templates/entity-ui-descriptor.ts

@@ -53,7 +53,6 @@ import {
 import { inferViewKind, currencyMetaFor, labelFor, humanize, valueObjectFor } from "./field-meta.js";
 import { VIEW_CONTEXT_FORM } from "../view-context.js";
 import { enumValues } from "../enum-meta.js";
-import { isProjection } from "../projection/projection-detector.js";
 // `restPath` lives HERE rather than in api-surface.ts, which is where it used to sit and
 // which now re-exports it. The descriptor is what emits `$path`, so the composition has to
 // be reachable from this module; importing it back from `api-surface.js` would be a cycle,
@@ -116,30 +115,24 @@ export interface EntityUiDescriptor {
  * An object's OWN pluralized resource path — the one derivation of that spelling, and the
  * input {@link restPath} composes an address from. It is NOT `$path` on its own.
  *
- * A projection is KEBAB-cased and an entity is SNAKE-cased, and that split is not a
- * style choice: both spellings are already mounted. `renderProjectionDecl` emits
- * `$path: "/order-summaries"` and `renderEntityConstants` emits `$path:
- * "/order_summaries"`, and `routes-file.ts` mounts whichever const belongs to the object
- * — so an address computed without the split is wrong for every multi-word projection.
- * It used to live in a second function inside `projection-decl.ts`, which is exactly how
- * `agent/ui.md` and `api/AGENT-API.md` both came to print `/order_summaries` for a
- * projection served at `/order-summaries`.
+ * ONE rule for entities and projections alike: snake_case the name, then pluralize.
+ * A projection used to be KEBAB-cased here while an entity was SNAKE-cased, composed in
+ * the opposite ORDER, and that split was grandfathered rather than designed — the only
+ * reason recorded for it was that the projection const had always emitted it. It is
+ * collapsed, so `OrderSummary` is `/order_summaries` whichever it is. That renamed every
+ * multi-word projection's collection URL; see CHANGELOG.
  *
  *   "Subscriber"     → "/subscribers"
  *   "WorkoutEvent"   → "/workout_events"
- *   "ProgramSummary" → "/program-summaries"   (projection)
+ *   "ProgramSummary" → "/program_summaries"   (projection — same rule)
  *
  * A TPH SUBTYPE is not addressed by this path — it is mounted under its base — so this is
  * an INPUT to {@link restPath}, not the answer. `$path` carries `restPath`; call this only
  * when you specifically want an object's own pluralized name, never to build an address.
  */
 export function resourcePath(entity: MetaData): string {
-  // The two compositions differ in ORDER as well as separator, and both are load-bearing:
-  // pluralize-then-snake is what the projection const has always emitted, snake-then-
-  // pluralize is what the entity const has. Neither may be "tidied" into the other.
-  return isProjection(entity)
-    ? `/${toSnakeCase(pluralize(entity.name)).replace(/_/g, "-")}`
-    : `/${pluralize(toSnakeCase(entity.name))}`;
+  // One rule, every object kind and every port: snake_case, then pluralize.
+  return `/${pluralize(toSnakeCase(entity.name))}`;
 }
 
 /**

package/src/templates/relations-block.ts

@@ -8,6 +8,7 @@ import { type RenderContext } from "../render-context.js";
 import { crossEntitySpecifier } from "../import-path.js";
 import type { RelationEntry } from "../relation-resolver.js";
 import { effectivePackage } from "../docs-paths.js";
+import { tphStorageName } from "./zod-validators.js";
 
 /**
  * Render the relations() block for one entity.
@@ -31,7 +32,7 @@ export function renderRelationsBlock(entity: MetaObject, ctx: RenderContext): Co
 
   const thisEntityPackage = effectivePackage(entity);
   const lines: Code[] = entries.map((entry) =>
-    renderRelationEntry(entry, ctx, varName, thisEntityPackage),
+    renderRelationEntry(entry, ctx, entity.name, varName, thisEntityPackage),
   );
 
   return code`export const ${relationsVarName} = ${relationsFn}(${varName}, (${params}) => ({
@@ -43,6 +44,7 @@ ${joinCode(lines, { on: ",\n", trim: false })}
 function renderRelationEntry(
   entry: RelationEntry,
   ctx: RenderContext,
+  thisEntityName: string,
   thisVarName: string,
   thisEntityPackage: string | undefined,
 ): Code {
@@ -63,18 +65,24 @@ function renderRelationEntry(
     return code`  ${entry.name}: many(${junctionVarSym})`;
   }
 
-  // Use imp() for cross-entity references so ts-poet tracks and emits the import.
-  const targetSpec = crossEntitySpecifier(
-    ctx.outputLayout,
-    thisEntityPackage,
-    ctx.packageOf.get(entry.targetEntity),
-    entry.targetEntity,
-    ctx.extStyle,
-  );
-  const targetVarSym = imp(`${ctx.collectionName(entry.targetEntity)}@${targetSpec}`);
+  // Bind to the table that stores the target's rows: a TPH subtype's module has no
+  // table const, so a navigation onto `Carrier` binds `parties` from `Party`.
+  const targetTableEntity = tphStorageName(entry.targetEntity, ctx.loadedRoot);
+  // A navigation onto this entity's OWN table (`Order.parent`, or a TPH base onto one of
+  // its subtypes) names the local const: importing it from this very module clashes with
+  // its declaration (TS2440). Otherwise imp() tracks and emits the cross-entity import.
+  const targetVarSym = targetTableEntity === thisEntityName
+    ? thisVarName
+    : imp(`${ctx.collectionName(targetTableEntity)}@${crossEntitySpecifier(
+      ctx.outputLayout,
+      thisEntityPackage,
+      ctx.packageOf.get(targetTableEntity),
+      targetTableEntity,
+      ctx.extStyle,
+    )}`);
 
   if (entry.cardinality === CARDINALITY_ONE) {
-    const pkInfo = ctx.pkMap.get(entry.targetEntity);
+    const pkInfo = ctx.pkMap.get(targetTableEntity);
     const targetPkField = pkInfo?.fieldName ?? "id";
     return code`  ${entry.name}: one(${targetVarSym}, { fields: [${thisVarName}.${entry.fkField ?? "id"}], references: [${targetVarSym}.${targetPkField}] })`;
   }