@metaobjectsdev/codegen-ts 0.9.0 → 0.11.0-rc.1

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:
@@ -120,7 +114,7 @@ export function zodTypeFor(field: MetaField): string {
 export function currencyMetaFor(field: MetaField): { currency: string; locale: string } | null {
   if (field.subType !== FIELD_SUBTYPE_CURRENCY) return null;
   const currency =
-    (field.ownAttr(FIELD_ATTR_CURRENCY) as string | undefined) ?? FIELD_ATTR_CURRENCY_DEFAULT;
+    (field.attr(FIELD_ATTR_CURRENCY) as string | undefined) ?? FIELD_ATTR_CURRENCY_DEFAULT;
   const viewChild = field.views().find((c) => c.subType === VIEW_SUBTYPE_CURRENCY);
   const locale =
     (viewChild?.ownAttr(VIEW_CURRENCY_ATTR_LOCALE) as string | undefined) ??

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.attr(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";
@@ -86,7 +93,7 @@ export const ${entity.name}SortAllowlist = {} as const satisfies SortAllowlist;
   }
   const rows = sortable
     .map((f) => {
-      const defaultOrder = f.ownAttr(FIELD_ATTR_SORTABLE_DEFAULT_ORDER) as string | undefined;
+      const defaultOrder = f.attr(FIELD_ATTR_SORTABLE_DEFAULT_ORDER) as string | undefined;
       const rule =
         defaultOrder === "asc" || defaultOrder === "desc"
           ? `{ defaultOrder: ${JSON.stringify(defaultOrder)} as const }`

package/src/templates/filter-shared.ts

@@ -15,10 +15,10 @@ import { FIELD_ATTR_FILTERABLE, FIELD_ATTR_SORTABLE } from "@metaobjectsdev/meta
  *   3. no @sortable     → sortable iff @filterable === true
  */
 export function isSortableField(field: MetaField): boolean {
-  const sortableAttr = field.ownAttr(FIELD_ATTR_SORTABLE);
+  const sortableAttr = field.attr(FIELD_ATTR_SORTABLE);
   if (sortableAttr === true) return true;
   if (sortableAttr === false) return false;
-  return field.ownAttr(FIELD_ATTR_FILTERABLE) === true;
+  return field.attr(FIELD_ATTR_FILTERABLE) === true;
 }
 
 /**

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,10 +45,16 @@ 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 filterableFieldsList = allFields.filter((c) => c.ownAttr(FIELD_ATTR_FILTERABLE) === true);
+  const allFields = entity.fields().filter((c) => c.name !== exclude);
+  const filterableFieldsList = allFields.filter((c) => c.attr(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).
   const sortFieldNames = allFields.filter(isSortableField).map((f) => `"${f.name}"`);

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:
@@ -81,14 +76,21 @@ export function isArray(field: MetaData): boolean {
 
 /** True iff the field's @required is explicitly true (or the string "true"). */
 export function isRequired(field: MetaData): boolean {
-  const v = field.ownAttr(FIELD_ATTR_REQUIRED);
+  const v = field.attr(FIELD_ATTR_REQUIRED);
+  if (v === true) return true;
+  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.attr(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);
+  const v = field.attr(FIELD_ATTR_VALUES);
   if (Array.isArray(v)) return v.map((e) => String(e));
   return [];
 }
@@ -98,7 +100,7 @@ export function enumValues(field: MetaData): string[] {
  * or null when absent. Read own-attr only — `@coerceDefault` is concrete, never inherited.
  */
 export function coerceDefault(field: MetaData): string | null {
-  const v = field.ownAttr(FIELD_ATTR_COERCE_DEFAULT);
+  const v = field.attr(FIELD_ATTR_COERCE_DEFAULT);
   return typeof v === "string" && v.length > 0 ? v : null;
 }
 
@@ -106,7 +108,7 @@ export function coerceDefault(field: MetaData): string | null {
  * FR-011: the field's `@default` member symbol (absent-fill enum value), or null when absent.
  */
 export function defaultValue(field: MetaData): string | null {
-  const v = field.ownAttr(FIELD_ATTR_DEFAULT);
+  const v = field.attr(FIELD_ATTR_DEFAULT);
   return typeof v === "string" && v.length > 0 ? v : null;
 }
 
@@ -126,7 +128,7 @@ export function resolveNormalize(field: MetaData, ownerObject: MetaData | null):
 
 /** The `@normalize` attr of a node as a NormalizeMode, or null when absent. */
 function normalizeAttrOf(node: MetaData): NormalizeMode | null {
-  const v = node.ownAttr(FIELD_ATTR_NORMALIZE);
+  const v = node.attr(FIELD_ATTR_NORMALIZE);
   return typeof v === "string" && v.length > 0 ? (v as NormalizeMode) : null;
 }
 

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,41 @@ 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 { valueObjectModuleSpecifier } from "../import-path.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 {
-  const varName = variableNameFromEntity(entity.name);
+/**
+ * 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, ctx?: RenderContext): Code {
+  // The inferred Row/Insert types reference the Drizzle table var, so they must
+  // resolve to the SAME (possibly overridden) collection name the schema emits.
+  // ctx is optional for bare unit-test calls — those fall back to the default
+  // always-pluralize spelling.
+  const varName = ctx ? ctx.collectionName(entity.name) : 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 +87,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 +118,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 +144,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 +160,68 @@ 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.attr(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);
+    const ref = field.attr(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 is named by the BARE short name. The import MODULE is
+      // resolved through the shared layout/package/extStyle-aware helper (the SAME
+      // one the Zod schema + Drizzle .$type<> use) so all three agree. Without a
+      // ctx (bare unit-test calls) fall back to the flat same-dir specifier.
+      const base = stripPackage(ref);
+      const moduleSpec = ctx
+        ? valueObjectModuleSpecifier(base, ctx.packageOf, entity.package, ctx.outputLayout, ctx.extStyle)
+        : `./${base}.js`;
+      const refImp = imp(`${base}@${moduleSpec}`);
       return field.isArray ? code`${refImp}[]` : code`${refImp}`;
     }
     return field.isArray ? code`unknown[]` : code`unknown`;
@@ -145,6 +232,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,15 +263,15 @@ 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` : "";
 
   const lines: Code[] = [];
   for (const field of entity.fields()) {
-    const required = field.ownAttr(FIELD_ATTR_REQUIRED) === true;
+    const required = field.attr(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};`);
   }