@metaobjectsdev/codegen-ts 0.9.0 → 0.10.0

package/src/templates/extractor.ts

@@ -33,6 +33,7 @@ import {
   TEMPLATE_ATTR_PAYLOAD_REF,
   TEMPLATE_ATTR_FORMAT,
   PACKAGE_SEPARATOR,
+  refMatchesObject,
 } from "@metaobjectsdev/metadata";
 import { fields, isArray } from "./fr010-field-mapping.js";
 import { mirrorName } from "./extract-delegate-emitter.js";
@@ -40,7 +41,7 @@ import { enumUnionAliasName } from "./inferred-types.js";
 import { enumValues } from "../enum-meta.js";
 
 function findObject(root: MetaData, name: string): MetaData | undefined {
-  return root.ownChildren().find((c) => c.type === TYPE_OBJECT && c.name === name);
+  return root.ownChildren().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, name));
 }
 
 function findTemplate(root: MetaData, name: string): MetaData | undefined {
@@ -64,9 +65,9 @@ function isObjectField(field: MetaData): boolean {
 
 /**
  * The union-alias type name for a `field.enum` with effective `@values`, or undefined when the
- * field is not a value-constrained enum. Reuses `enumUnionAliasName` — the SAME naming the payload
- * emitter (`payload-codegen.ts`) types the field as — so the cast target resolves to the exact
- * alias exported from `payloads.ts`. `ownerName` is the owning value-object's interface name.
+ * field is not a value-constrained enum. Reuses `enumUnionAliasName` — the SAME naming the entity
+ * inferred-types emitter types the field as — so the cast target resolves to the exact alias
+ * exported from the owning VO's entity module. `ownerName` is the owning value-object's interface name.
  */
 function enumAlias(field: MetaData, ownerName: string): string | undefined {
   if (field.subType !== FIELD_SUBTYPE_ENUM) return undefined;
@@ -76,11 +77,12 @@ function enumAlias(field: MetaData, ownerName: string): string | undefined {
 }
 
 /**
- * True iff the field is required IN THE STRICT PAYLOAD TYPE. This MUST match
- * payload-codegen.ts's `isFieldRequired` predicate EXACTLY (boolean `true` only) — the payload
- * interface decides `T` vs `T | null` by that predicate, and the mapper's optionality assumption
- * (`m.f!` vs `m.f ?? null`) has to agree with the type it is constructing. A `@required:"true"`
- * string field is therefore `T | null` in the payload AND optional here (no skew).
+ * True iff the field is required IN THE STRICT PAYLOAD TYPE. The strict payload IS the VO's own
+ * generated entity-module interface (`renderValueObjectInterface`), which types a required field
+ * `f: T` and an optional one `f?: T` (i.e. `T | undefined` — NOT `T | null`). So the mapper's
+ * optionality assumption (`m.f!` vs `m.f ?? undefined`) has to agree with THAT interface, and an
+ * absent optional maps to `undefined`, never `null`. This predicate matches the interface's
+ * required test (boolean `true` only) so the two never skew.
  */
 function isFieldRequired(field: MetaData): boolean {
   return field.ownAttr(FIELD_ATTR_REQUIRED) === true;
@@ -93,8 +95,10 @@ function mapperName(vo: MetaData): string {
 
 /**
  * The mapper-body initializer expression for one field, reading mirror member `m.<name>` and
- * mapping it onto the strict payload's exact optionality (required → `m.f!`; optional → `m.f ?? null`).
- * Nested single/array objects recurse into their toStrict<Type> mapper, guarding null when optional.
+ * mapping it onto the strict payload's exact optionality (required → `m.f!`; optional → `m.f ?? undefined`).
+ * The strict payload is the VO's generated entity-module interface, whose optional fields are
+ * `f?: T` (= `T | undefined`, never `T | null`), so an absent optional maps to `undefined`.
+ * Nested single/array objects recurse into their toStrict<Type> mapper, guarding when optional.
  */
 function strictArg(field: MetaData, root: MetaData, ownerName: string): string {
   const name = field.name;
@@ -104,25 +108,25 @@ function strictArg(field: MetaData, root: MetaData, ownerName: string): string {
     const target = refVo(field, root);
     if (target === undefined) {
       // Unresolved @objectRef — the payload type would be `unknown`; pass through as-is.
-      return required ? `m.${name}!` : `m.${name} ?? null`;
+      return required ? `m.${name}!` : `m.${name} ?? undefined`;
     }
     const fn = mapperName(target);
     if (isArray(field)) {
       // Required array-of-objects: each element mapped; element nulls dropped at the type level
       // via the non-null assertion (extract never yields null elements for a present array).
       if (required) return `m.${name}!.map((e) => ${fn}(e!))`;
-      return `m.${name} ? m.${name}!.map((e) => ${fn}(e!)) : null`;
+      return `m.${name} ? m.${name}!.map((e) => ${fn}(e!)) : undefined`;
     }
     // Single nested object.
     if (required) return `${fn}(m.${name}!)`;
-    return `m.${name} ? ${fn}(m.${name}) : null`;
+    return `m.${name} ? ${fn}(m.${name}) : undefined`;
   }
 
   // Scalar ARRAY (e.g. `field.string` with isArray): the mirror types it `(T | null)[] | null`
-  // but the strict payload types it `T[]` (required) / `T[] | null` (optional). A bare `m.f!`
+  // but the strict payload types it `T[]` (required) / `T[]?` (optional). A bare `m.f!`
   // would leave the element type `T | null`, a `tsc --strict` TS2322 error. Filter out null
   // elements so the element type narrows to non-null (consistent with the lost-element DROP policy
-  // already used for required arrays-of-objects above).
+  // already used for required arrays-of-objects above). An absent optional array maps to `undefined`.
   //
   // ENUM arrays: the mirror element is a plain `string`, but the strict payload types it as the
   // closed `<Alias>[]` union. The null-filter alone narrows to `string[]`, not `<Alias>[]` — a
@@ -136,23 +140,23 @@ function strictArg(field: MetaData, root: MetaData, ownerName: string): string {
       return alias !== undefined ? `(${filtered}) as ${alias}[]` : filtered;
     }
     const filtered = `m.${name}.filter((x): x is NonNullable<typeof x> => x != null)`;
-    const guarded = `m.${name} == null ? null : ${filtered}`;
+    const guarded = `m.${name} == null ? undefined : ${filtered}`;
     return alias !== undefined
-      ? `m.${name} == null ? null : (${filtered}) as ${alias}[]`
+      ? `m.${name} == null ? undefined : (${filtered}) as ${alias}[]`
       : guarded;
   }
 
   // Scalar / enum (single): the strict payload's optionality decides the shape.
-  // Required → non-null assertion; optional → `?? null` (matches the payload's `f?: T | null`).
+  // Required → non-null assertion; optional → `?? undefined` (matches the entity-module `f?: T`).
   //
   // ENUM scalar: the mirror member is a plain `string`, but the strict payload types it as the
   // closed `<Alias>` union — assigning `string` into `<Alias>` is a `tsc --strict` TS2322 error.
   // So the value is CAST to `<Alias>`. Sound for the same reason as enum arrays above: the engine
   // already validated membership (or extract throws on a lost required field).
   if (alias !== undefined) {
-    return required ? `m.${name}! as ${alias}` : `(m.${name} ?? null) as ${alias} | null`;
+    return required ? `m.${name}! as ${alias}` : `(m.${name} ?? undefined) as ${alias} | undefined`;
   }
-  return required ? `m.${name}!` : `m.${name} ?? null`;
+  return required ? `m.${name}!` : `m.${name} ?? undefined`;
 }
 
 /**
@@ -202,24 +206,44 @@ function emitMapper(
 }
 
 /**
- * Collect the strict payload-interface names reachable from `vo` (for the type-only import),
- * PLUS every enum union-alias reachable from those VOs. Both are exported from `payloads.ts`
- * (the alias is hoisted above the interface there), so the extractor's `as <Alias>` casts need
- * the alias names imported alongside the interface names. Deduped, in discovery order.
+ * One payload-type import group: the strict types (VO interface + its own enum
+ * union-aliases) imported from a single VO entity module.
  */
-function reachablePayloadTypes(vo: MetaData, root: MetaData): string[] {
-  const order: string[] = [];
-  const seen = new Set<string>();
+interface PayloadImportGroup {
+  /** The VO whose entity module exports these types (`./<module>.js`). */
+  module: string;
+  /** The strict type names exported by that module, in discovery order. */
+  types: string[];
+}
+
+/**
+ * Group the strict payload types reachable from `vo` BY THE ENTITY MODULE THAT EXPORTS THEM.
+ *
+ * Each value-object gets its own generated entity module (`entityFile()` emits `<VO>.ts` exporting
+ * `export interface <VO>`), and `renderEnumTypeAliases` hoists every `field.enum` union-alias INTO
+ * the OWNING VO's module (`export type <Owner><Field> = ...` co-located with the interface). So a
+ * VO's interface AND the aliases for its own enum fields are imported from `./<VO>.js` — NOT from a
+ * single `payloads.ts` (which no generator emits). Deduped, in discovery order, one group per VO.
+ */
+function reachablePayloadGroups(vo: MetaData, root: MetaData): PayloadImportGroup[] {
+  const groups: PayloadImportGroup[] = [];
+  const seenVo = new Set<string>();
+  const seenAlias = new Set<string>();
   const visit = (cur: MetaData) => {
-    if (seen.has(cur.name)) return;
-    seen.add(cur.name);
-    order.push(cur.name);
+    if (seenVo.has(cur.name)) return;
+    seenVo.add(cur.name);
+    // The VO interface + its OWN enum aliases share the VO's entity module.
+    const types: string[] = [cur.name];
     for (const f of fields(cur)) {
       const alias = enumAlias(f, cur.name);
-      if (alias !== undefined && !seen.has(alias)) {
-        seen.add(alias);
-        order.push(alias);
+      if (alias !== undefined && !seenAlias.has(alias)) {
+        seenAlias.add(alias);
+        types.push(alias);
       }
+    }
+    groups.push({ module: cur.name, types });
+    // Recurse into nested object refs (their interfaces live in their own modules).
+    for (const f of fields(cur)) {
       if (isObjectField(f)) {
         const target = refVo(f, root);
         if (target !== undefined) visit(target);
@@ -227,7 +251,7 @@ function reachablePayloadTypes(vo: MetaData, root: MetaData): string[] {
     }
   };
   visit(vo);
-  return order;
+  return groups;
 }
 
 /** Collect the mirror-interface names reachable from `vo` (root mirror + nested VO mirrors). */
@@ -286,10 +310,16 @@ export function renderExtractor(root: MetaData, templateName: string): string {
   const extractName = `extract${templateName}`;
   const rootMapper = mapperName(vo);
 
-  const payloadTypes = reachablePayloadTypes(vo, root);
+  const payloadGroups = reachablePayloadGroups(vo, root);
   const mirrorTypes = reachableMirrorTypes(vo, root, rootMirror);
   const mappers = emitMappers(vo, root, rootMirror);
 
+  // One type-only import per VO entity module (the VO interface + its own enum
+  // union-aliases co-located there). NOT a single non-existent `./payloads.js`.
+  const payloadImports = payloadGroups
+    .map((g) => `import type { ${g.types.join(", ")} } from "./${g.module}.js";`)
+    .join("\n");
+
   const lostMsg =
     `${extractName}: lost required field(s): `;
 
@@ -301,13 +331,13 @@ export function renderExtractor(root: MetaData, templateName: string): string {
     `// mapping the all-nullable mirror onto the strict payload. No registry / binding / factory.\n` +
     `\n` +
     `import {\n  ${extractLenientWithName},\n  type ${mirrorTypes.join(",\n  type ")},\n} from "./${templateName}.output.js";\n` +
-    `import type { ${payloadTypes.join(", ")} } from "./payloads.js";\n` +
+    `${payloadImports}\n` +
     `import type { MetaRoot } from "@metaobjectsdev/metadata";\n` +
     `import type { ExtractionResult } from "@metaobjectsdev/render";\n` +
     `\n` +
     `/**\n` +
     ` * Extract a fully-typed \`${strictType}\` from dirty \`text\` using the loaded \`root\` (which must\n` +
-    ` * declare the "${payloadRef}" payload value-object). Runs the tolerant extract, then maps the\n` +
+    ` * declare the "${strictType}" payload value-object). Runs the tolerant extract, then maps the\n` +
     ` * extracted mirror onto the strict payload.\n` +
     ` *\n` +
     ` * @throws Error iff a \`@required\` field was lost (the strict opt-in gate).\n` +

package/src/templates/field-meta.ts

@@ -8,8 +8,6 @@ import {
   FIELD_SUBTYPE_STRING,
   FIELD_SUBTYPE_INT,
   FIELD_SUBTYPE_LONG,
-  FIELD_SUBTYPE_SHORT,
-  FIELD_SUBTYPE_BYTE,
   FIELD_SUBTYPE_DOUBLE,
   FIELD_SUBTYPE_FLOAT,
   FIELD_SUBTYPE_DECIMAL,
@@ -54,8 +52,6 @@ function defaultViewForSubType(subType: string): string {
       return VIEW_SUBTYPE_CHECKBOX;
     case FIELD_SUBTYPE_INT:
     case FIELD_SUBTYPE_LONG:
-    case FIELD_SUBTYPE_SHORT:
-    case FIELD_SUBTYPE_BYTE:
     case FIELD_SUBTYPE_DOUBLE:
     case FIELD_SUBTYPE_FLOAT:
     case FIELD_SUBTYPE_DECIMAL:
@@ -92,8 +88,6 @@ export function zodTypeFor(field: MetaField): string {
       return "z.string()";
     case FIELD_SUBTYPE_INT:
     case FIELD_SUBTYPE_LONG:
-    case FIELD_SUBTYPE_SHORT:
-    case FIELD_SUBTYPE_BYTE:
     case FIELD_SUBTYPE_CURRENCY:
       return "z.number().int()";
     case FIELD_SUBTYPE_DOUBLE:

package/src/templates/filter-allowlist.ts

@@ -5,8 +5,6 @@ import {
   FIELD_ATTR_SORTABLE_DEFAULT_ORDER,
   FIELD_SUBTYPE_BOOLEAN,
   FIELD_SUBTYPE_INT,
-  FIELD_SUBTYPE_SHORT,
-  FIELD_SUBTYPE_BYTE,
   FIELD_SUBTYPE_LONG,
   FIELD_SUBTYPE_DOUBLE,
   FIELD_SUBTYPE_FLOAT,
@@ -14,18 +12,19 @@ import {
   FIELD_SUBTYPE_DATE,
   FIELD_SUBTYPE_TIME,
   FIELD_SUBTYPE_TIMESTAMP,
+  FIELD_SUBTYPE_CURRENCY,
   opsForSubType,
 } from "@metaobjectsdev/metadata";
 import { sortableFields } from "./filter-shared.js";
 
 const NUMBER_SUBTYPES = new Set<string>([
   FIELD_SUBTYPE_INT,
-  FIELD_SUBTYPE_SHORT,
-  FIELD_SUBTYPE_BYTE,
   FIELD_SUBTYPE_LONG,
   FIELD_SUBTYPE_DOUBLE,
   FIELD_SUBTYPE_FLOAT,
   FIELD_SUBTYPE_DECIMAL,
+  // currency is integer minor units — coerces as a number on the wire.
+  FIELD_SUBTYPE_CURRENCY,
 ]);
 
 const DATETIME_SUBTYPES = new Set<string>([
@@ -42,13 +41,20 @@ function filterSubTypeFor(fieldSubType: string): "string" | "number" | "boolean"
   return "string";
 }
 
-function filterableFields(entity: MetaObject): MetaField[] {
+function filterableFields(entity: MetaObject, exclude?: string): MetaField[] {
   // fields() returns effective fields, so inherited fields (from extends:/super:) are included in allowlists.
-  return entity.fields().filter((c) => c.ownAttr(FIELD_ATTR_FILTERABLE) === true);
+  return entity
+    .fields()
+    .filter((c) => c.ownAttr(FIELD_ATTR_FILTERABLE) === true && c.name !== exclude);
 }
 
-export function renderFilterAllowlist(entity: MetaObject): Code {
-  const fields = filterableFields(entity);
+/**
+ * `exclude` (FR-017): drop a field from the allowlist. Used by per-subtype TPH
+ * allowlists to omit the discriminator — it's pinned by the per-subtype route
+ * path, so a client must not filter on it.
+ */
+export function renderFilterAllowlist(entity: MetaObject, exclude?: string): Code {
+  const fields = filterableFields(entity, exclude);
   if (fields.length === 0) {
     return code`
 import type { FilterAllowlist } from "@metaobjectsdev/runtime-ts/drizzle-fastify";
@@ -72,11 +78,12 @@ ${rows}
 `;
 }
 
-export function renderSortAllowlist(entity: MetaObject): Code {
+export function renderSortAllowlist(entity: MetaObject, exclude?: string): Code {
   // Sortable = explicit @sortable === true, OR (no @sortable AND @filterable === true).
   // @sortable: false explicitly opts out.
   // Uses shared isSortableField predicate — must stay in sync with renderFilterType.
-  const sortable = sortableFields(entity);
+  // `exclude` (FR-017): per-subtype TPH allowlists omit the discriminator.
+  const sortable = sortableFields(entity).filter((f) => f.name !== exclude);
   if (sortable.length === 0) {
     return code`
 import type { SortAllowlist } from "@metaobjectsdev/runtime-ts/drizzle-fastify";

package/src/templates/filter-type.ts

@@ -8,8 +8,6 @@ import {
   FIELD_ATTR_FILTERABLE,
   FIELD_SUBTYPE_BOOLEAN,
   FIELD_SUBTYPE_INT,
-  FIELD_SUBTYPE_SHORT,
-  FIELD_SUBTYPE_BYTE,
   FIELD_SUBTYPE_LONG,
   FIELD_SUBTYPE_DOUBLE,
   FIELD_SUBTYPE_FLOAT,
@@ -23,8 +21,6 @@ import { isSortableField } from "./filter-shared.js";
 // matching the entity field representation (exact decimal string, not lossy number).
 const NUMBER_VALUE_SUBTYPES = new Set<string>([
   FIELD_SUBTYPE_INT,
-  FIELD_SUBTYPE_SHORT,
-  FIELD_SUBTYPE_BYTE,
   FIELD_SUBTYPE_LONG,
   FIELD_SUBTYPE_DOUBLE,
   FIELD_SUBTYPE_FLOAT,
@@ -49,9 +45,15 @@ function renderFieldUnion(field: MetaField): string {
   return `${tsName} | { ${opEntries.join("; ")} }`;
 }
 
-export function renderFilterType(entity: MetaObject): Code {
+/**
+ * `exclude` (FR-017): drop a field from the client filter type. Used by
+ * per-subtype TPH filter types to omit the discriminator (it's pinned by the
+ * per-subtype route path), keeping the client `<Sub>Filter` type aligned with
+ * the server's per-subtype allowlist.
+ */
+export function renderFilterType(entity: MetaObject, exclude?: string): Code {
   // fields() returns effective fields, so inherited fields (from extends:/super:) are included in filter types.
-  const allFields = entity.fields();
+  const allFields = entity.fields().filter((c) => c.name !== exclude);
   const filterableFieldsList = allFields.filter((c) => c.ownAttr(FIELD_ATTR_FILTERABLE) === true);
   // Sort union uses isSortableField — same predicate as renderSortAllowlist to prevent
   // client/server mismatches (@filterable: true + @sortable: false must be excluded from both).

package/src/templates/find-templates.ts

@@ -0,0 +1,15 @@
+import type { MetaData } from "@metaobjectsdev/metadata";
+import { TYPE_TEMPLATE } from "@metaobjectsdev/metadata";
+
+/** All template nodes of `subType` anywhere in the tree (top-level OR nested in entities). */
+export function findTemplates(root: MetaData, subType: string): MetaData[] {
+  const out: MetaData[] = [];
+  const visit = (node: MetaData) => {
+    for (const child of node.ownChildren()) {
+      if (child.type === TYPE_TEMPLATE && child.subType === subType) out.push(child);
+      visit(child);
+    }
+  };
+  visit(root);
+  return out;
+}

package/src/templates/fr010-field-mapping.ts

@@ -1,7 +1,7 @@
 // server/typescript/packages/codegen-ts/src/templates/fr010-field-mapping.ts
 //
-// Shared field-kind mapping for the FR-010 codegen emitters (extract-schema-emitter +
-// output-format-spec-emitter). Maps a metadata field subtype onto the render engine's
+// Shared field-kind mapping for the FR-010 codegen emitters (the output-format-spec
+// emitter et al.). Maps a metadata field subtype onto the render engine's
 // FieldKind member, the idiomatic nullable TS type used by the extract mirror interface,
 // and the ExtractMap accessor that reads it from the forgiving outcome map.
 //
@@ -13,14 +13,11 @@ import {
   type MetaData,
   TYPE_FIELD,
   FIELD_SUBTYPE_STRING,
-  FIELD_SUBTYPE_CLASS,
   FIELD_SUBTYPE_UUID,
   FIELD_SUBTYPE_DATE,
   FIELD_SUBTYPE_TIME,
   FIELD_SUBTYPE_TIMESTAMP,
   FIELD_SUBTYPE_INT,
-  FIELD_SUBTYPE_SHORT,
-  FIELD_SUBTYPE_BYTE,
   FIELD_SUBTYPE_LONG,
   FIELD_SUBTYPE_CURRENCY,
   FIELD_SUBTYPE_DOUBLE,
@@ -34,6 +31,7 @@ import {
   FIELD_ATTR_COERCE_DEFAULT,
   FIELD_ATTR_DEFAULT,
   FIELD_ATTR_NORMALIZE,
+  FIELD_ATTR_XML_TEXT,
   NORMALIZE_DEFAULT,
   type NormalizeMode,
 } from "@metaobjectsdev/metadata";
@@ -42,7 +40,6 @@ import {
 export function scalarKind(subType: string): string | null {
   switch (subType) {
     case FIELD_SUBTYPE_STRING:
-    case FIELD_SUBTYPE_CLASS:
     case FIELD_SUBTYPE_UUID:
     case FIELD_SUBTYPE_DATE:
     case FIELD_SUBTYPE_TIME:
@@ -53,8 +50,6 @@ export function scalarKind(subType: string): string | null {
     case FIELD_SUBTYPE_DECIMAL:
       return "STRING";
     case FIELD_SUBTYPE_INT:
-    case FIELD_SUBTYPE_SHORT:
-    case FIELD_SUBTYPE_BYTE:
       return "INT";
     case FIELD_SUBTYPE_LONG:
     case FIELD_SUBTYPE_CURRENCY:
@@ -86,6 +81,13 @@ export function isRequired(field: MetaData): boolean {
   return typeof v === "string" && v.toLowerCase() === "true";
 }
 
+/** True iff the field's @xmlText is explicitly true (the XML text-content extract marker). */
+export function xmlText(field: MetaData): boolean {
+  const v = field.ownAttr(FIELD_ATTR_XML_TEXT);
+  if (v === true) return true;
+  return typeof v === "string" && v.toLowerCase() === "true";
+}
+
 /** The string members of an enum field's @values attr (empty when absent). */
 export function enumValues(field: MetaData): string[] {
   const v = field.ownAttr(FIELD_ATTR_VALUES);

package/src/templates/inferred-types.ts

@@ -14,8 +14,6 @@ import {
   FIELD_SUBTYPE_OBJECT,
   FIELD_SUBTYPE_STRING,
   FIELD_SUBTYPE_INT,
-  FIELD_SUBTYPE_SHORT,
-  FIELD_SUBTYPE_BYTE,
   FIELD_SUBTYPE_LONG,
   FIELD_SUBTYPE_DOUBLE,
   FIELD_SUBTYPE_FLOAT,
@@ -25,23 +23,36 @@ import {
   FIELD_SUBTYPE_DATE,
   FIELD_SUBTYPE_TIME,
   FIELD_SUBTYPE_TIMESTAMP,
-  FIELD_SUBTYPE_CLASS,
   FIELD_SUBTYPE_UUID,
   FIELD_ATTR_REQUIRED,
   FIELD_ATTR_OBJECT_REF,
 } from "@metaobjectsdev/metadata";
 import { variableNameFromEntity, toPascalCase } from "../naming.js";
+import { stripPackage } from "@metaobjectsdev/metadata";
 import { enumValues } from "../enum-meta.js";
 import { renderDocsFor } from "./jsdoc.js";
+import { sharedEnumForField } from "../enum-shared.js";
+import { sharedEnumImportSpecifier, providedEnumImportSpecifier } from "../enum-import.js";
+import type { RenderContext } from "../render-context.js";
 
-export function renderInferredTypes(entity: MetaObject): Code {
+/**
+ * Emit Drizzle's InferSelectModel / InferInsertModel aliases for an entity.
+ *
+ * `tphBase` (FR-017): when this entity is a TPH discriminator base, the
+ * discriminated-union type (emitted by the tph-discriminator template) owns the
+ * bare `<Base>` name, so the raw single-table row type is emitted as `<Base>Row`
+ * to avoid a duplicate `export type <Base>`. Insert/Update keep their names
+ * (no collision); they describe the physical TPH table row shape.
+ */
+export function renderInferredTypes(entity: MetaObject, tphBase = false): Code {
   const varName = variableNameFromEntity(entity.name);
   const selectSym = imp("InferSelectModel@drizzle-orm");
   const insertSym = imp("InferInsertModel@drizzle-orm");
   const docs = renderDocsFor(entity);
   const docsPrefix = docs ? `${docs}\n` : "";
+  const rowName = tphBase ? `${entity.name}Row` : entity.name;
   return code`
-${docsPrefix}export type ${entity.name} = ${selectSym}<typeof ${varName}>;
+${docsPrefix}export type ${rowName} = ${selectSym}<typeof ${varName}>;
 export type ${entity.name}Insert = ${insertSym}<typeof ${varName}>;
 export type ${entity.name}Update = Partial<${entity.name}Insert>;
 `;
@@ -71,12 +82,23 @@ export function enumUnionString(values: string[]): string {
 }
 
 /**
- * Emit one `export type <Name> = "A" | "B";` line per field.enum field on the entity.
- * - If the field extends an abstract field.enum (super), use the super field's PascalCase name.
- * - Otherwise use `<Entity><FieldPascal>` for inline enums.
- * Returns null if the entity has no enum fields.
+ * Emit the enum type-alias section for an entity file. Three cases per field:
+ *
+ *  • inline enum (members declared directly on the field; no root-abstract super)
+ *    → `export type <Entity><Field> = "A" | "B";` — UNCHANGED (byte-identical).
+ *  • shared materialized enum (extends a NON-@provided root-level abstract
+ *    field.enum) → re-export the materialized type from the shared `./enums`
+ *    module (`export { type E } from "./enums"`) instead of redeclaring it. The
+ *    type is materialized ONCE in enums.ts (FR-019).
+ *  • provided enum (extends a @provided root-level abstract field.enum) →
+ *    re-export the type from the configured external module
+ *    (`export { type E } from "<providedEnumModule>"`); metaobjects emits no
+ *    declaration for it. A missing config is a codegen-time error.
+ *
+ * `ctx` is required to compute the shared/provided import specifiers. Returns
+ * null when the entity has no enum-alias lines to emit.
  */
-export function renderEnumTypeAliases(entity: MetaObject): Code | null {
+export function renderEnumTypeAliases(entity: MetaObject, ctx?: RenderContext): Code | null {
   // De-duplicate by type-alias name — multiple fields can extend the same abstract enum.
   const seen = new Set<string>();
   const lines: string[] = [];
@@ -91,7 +113,21 @@ export function renderEnumTypeAliases(entity: MetaObject): Code | null {
     if (seen.has(typeName)) continue;
     seen.add(typeName);
 
-    lines.push(`export type ${typeName} = ${enumUnionString(values)};`);
+    // Without a RenderContext (bare unit-test calls) the shared/provided import
+    // specifiers can't be computed — fall back to inline emission. Real runs
+    // always pass ctx (entity-file template), so shared materialization applies.
+    const shared = ctx !== undefined ? sharedEnumForField(field) : undefined;
+    if (shared === undefined) {
+      // Inline enum — emit the literal union exactly as before.
+      lines.push(`export type ${typeName} = ${enumUnionString(values)};`);
+      continue;
+    }
+    // Shared / provided enum — re-export from the materialized module or the
+    // configured external module; never redeclare the union here.
+    const spec = shared.provided
+      ? providedEnumImportSpecifier(ctx!, shared.name)
+      : sharedEnumImportSpecifier(ctx!, entity.package);
+    lines.push(`export { type ${shared.name} } from ${JSON.stringify(spec)};`);
   }
 
   return lines.length > 0 ? code`${lines.join("\n")}` : null;
@@ -103,11 +139,8 @@ export function renderEnumTypeAliases(entity: MetaObject): Code | null {
 
 const SCALAR_TS_BY_SUBTYPE: Record<string, string> = {
   [FIELD_SUBTYPE_STRING]: "string",
-  [FIELD_SUBTYPE_CLASS]: "string",
   [FIELD_SUBTYPE_UUID]: "string",
   [FIELD_SUBTYPE_INT]: "number",
-  [FIELD_SUBTYPE_SHORT]: "number",
-  [FIELD_SUBTYPE_BYTE]: "number",
   [FIELD_SUBTYPE_LONG]: "number",
   [FIELD_SUBTYPE_DOUBLE]: "number",
   [FIELD_SUBTYPE_FLOAT]: "number",
@@ -122,19 +155,62 @@ const SCALAR_TS_BY_SUBTYPE: Record<string, string> = {
   [FIELD_SUBTYPE_TIMESTAMP]: "string",
 };
 
+/**
+ * The PLAIN-STRING TS type expression for a field — the SINGLE source of truth
+ * for "what TS type does the codegen give this field". `valueObjectFieldType`
+ * (which returns a `Code` so cross-module `field.object` refs hoist via
+ * `imp(...)`) makes the SAME per-branch decisions; this string form exists for
+ * consumers (the api-docs field-shape builder) that need the type name as text,
+ * not a hoisting `Code`. The branch logic MUST stay in lock-step with
+ * `valueObjectFieldType` below.
+ *
+ *  • field.object → the referenced object's bare (package-stripped) name, `[]`
+ *    when an array; `unknown` / `unknown[]` when the @objectRef is missing.
+ *  • field.enum   → the same enum-union alias `enumUnionAliasName` emits
+ *    (`<Owner><Field>` or the abstract super's PascalCase), `string` fallback.
+ *  • scalar       → SCALAR_TS_BY_SUBTYPE (else `unknown`), `[]` when an array.
+ */
+export function fieldTsTypeString(ownerName: string, field: MetaField): string {
+  if (field.subType === FIELD_SUBTYPE_OBJECT) {
+    const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
+    if (typeof ref === "string" && ref.length > 0) {
+      const base = stripPackage(ref);
+      return field.isArray ? `${base}[]` : base;
+    }
+    return field.isArray ? "unknown[]" : "unknown";
+  }
+  if (field.subType === FIELD_SUBTYPE_ENUM) {
+    const values = enumValues(field);
+    if (values !== undefined) {
+      // The emitted TS type is an enum-union ALIAS (`<Owner><Field>`), but its
+      // definition IS this literal union — inline it so the documented shape is
+      // self-contained (an agent sees the exact allowed values, not an opaque
+      // alias name). Array enums wrap the parenthesized union: `(A | B)[]`.
+      const union = enumUnionString(values);
+      return field.isArray ? `(${union})[]` : union;
+    }
+    return field.isArray ? "string[]" : "string";
+  }
+  const scalar = SCALAR_TS_BY_SUBTYPE[field.subType] ?? "unknown";
+  return field.isArray ? `${scalar}[]` : scalar;
+}
+
 /**
  * One-line TS type expression for a field on a value-only object.
  * Returns a `Code` so cross-module `field.object` refs can be hoisted via
  * ts-poet `imp(...)` — matching how the Zod emitter hoists `<Ref>InsertSchema`.
  */
-function valueObjectFieldType(entity: MetaObject, field: MetaField): Code {
+function valueObjectFieldType(entity: MetaObject, field: MetaField, ctx?: RenderContext): Code {
   // field.object: import the referenced TS interface from its sibling module
   // so ts-poet hoists the import. Mirrors zod-validators.ts's `<Ref>InsertSchema`
   // import strategy, just for the type alias instead of the schema constant.
   if (field.subType === FIELD_SUBTYPE_OBJECT) {
     const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
     if (typeof ref === "string" && ref.length > 0) {
-      const refImp = imp(`${ref}@./${ref}.js`);
+      // @objectRef may be authored fully-qualified (acme::sales::Brief) or bare; the
+      // referenced interface + its sibling module are named by the BARE short name.
+      const base = stripPackage(ref);
+      const refImp = imp(`${base}@./${base}.js`);
       return field.isArray ? code`${refImp}[]` : code`${refImp}`;
     }
     return field.isArray ? code`unknown[]` : code`unknown`;
@@ -145,6 +221,20 @@ function valueObjectFieldType(entity: MetaObject, field: MetaField): Code {
     const values = enumValues(field);
     if (values !== undefined) {
       const alias = enumUnionAliasName(entity.name, field);
+      // FR-019: a shared/provided enum's type lives in another module (./enums or
+      // the provided module). Use imp() so ts-poet hoists `import { type E }` —
+      // the local interface can then reference E. Inline enums reference the
+      // locally-declared `<Entity><Field>` alias as before.
+      if (ctx !== undefined) {
+        const shared = sharedEnumForField(field);
+        if (shared !== undefined) {
+          const spec = shared.provided
+            ? providedEnumImportSpecifier(ctx, shared.name)
+            : sharedEnumImportSpecifier(ctx, entity.package);
+          const sym = imp(`${shared.name}@${spec}`);
+          return field.isArray ? code`${sym}[]` : code`${sym}`;
+        }
+      }
       return field.isArray ? code`${alias}[]` : code`${alias}`;
     }
     return field.isArray ? code`string[]` : code`string`;
@@ -162,7 +252,7 @@ function valueObjectFieldType(entity: MetaObject, field: MetaField): Code {
  * trip through Drizzle nullable columns, so the null-bridge is unnecessary
  * here — and forces consumers into a residual cast at the call site.
  */
-export function renderValueObjectInterface(entity: MetaObject): Code {
+export function renderValueObjectInterface(entity: MetaObject, ctx?: RenderContext): Code {
   const docs = renderDocsFor(entity);
   const docsPrefix = docs ? `${docs}\n` : "";
 
@@ -170,7 +260,7 @@ export function renderValueObjectInterface(entity: MetaObject): Code {
   for (const field of entity.fields()) {
     const required = field.ownAttr(FIELD_ATTR_REQUIRED) === true;
     const optional = required ? "" : "?";
-    const tsType = valueObjectFieldType(entity, field);
+    const tsType = valueObjectFieldType(entity, field, ctx);
     lines.push(code`  ${field.name}${optional}: ${tsType};`);
   }