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

package/src/templates/extractor.ts

@@ -0,0 +1,333 @@
+// server/typescript/packages/codegen-ts/src/templates/extractor.ts
+//
+// The strict `extract` tier — a generated `<Name>.extractor.ts` that sits OVER the existing tolerant
+// extractLenient<Name> and turns dirty LLM text into the STRICT typed payload graph (nested objects +
+// arrays-of-objects populated) in one call.
+//
+// Cross-port parity: this mirrors the Java ExtractorCodeGenerator (FOC Task 6). The Java port's
+// extract(loader, text) / extractLenient(loader, text) both take the loaded MetaDataLoader and delegate
+// to the Phase-B runtime extract (MetaObjectExtractor) so the WHOLE nested graph is assembled; the
+// returned flavored object IS the strict type there (the binding provider makes newInstance()
+// return it). TS has no flavored object-class — extractLenient returns an all-nullable `<Name>Extracted`
+// mirror and the strict payload is a separate `interface`, so the TS port adds the recursive
+// mirror→strict mapper (toStrict<Type>) that the Java/Kotlin ports get for free from the runtime.
+//
+// Why extract takes the MetaRoot: the SELF-CONTAINED extractLenient<Name>(text) leaves nested objects
+// null (the historical FR-010 gap). The nested-capable path is extractLenient<Name>WithLoader(root, text),
+// which delegates to the runtime extract. So the extract tier — like the Java port — is loader
+// (MetaRoot)-driven. extractLenient<Name>WithLoader is re-exposed here under the public name extractLenient<Name>.
+//
+// NO registry / binding provider / factory; codegen walks the whole type graph statically (the
+// same MetaObject walk the extract-schema / payload emitters use).
+
+import {
+  type MetaData,
+  type MetaField,
+  TYPE_OBJECT,
+  TYPE_TEMPLATE,
+  TEMPLATE_SUBTYPE_OUTPUT,
+  FIELD_SUBTYPE_OBJECT,
+  FIELD_SUBTYPE_ENUM,
+  FIELD_ATTR_OBJECT_REF,
+  FIELD_ATTR_REQUIRED,
+  TEMPLATE_ATTR_PAYLOAD_REF,
+  TEMPLATE_ATTR_FORMAT,
+  PACKAGE_SEPARATOR,
+} from "@metaobjectsdev/metadata";
+import { fields, isArray } from "./fr010-field-mapping.js";
+import { mirrorName } from "./extract-delegate-emitter.js";
+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);
+}
+
+function findTemplate(root: MetaData, name: string): MetaData | undefined {
+  return root.ownChildren().find((c) => c.type === TYPE_TEMPLATE && c.name === name);
+}
+
+/** The @objectRef target VO for a nested-object field, or undefined when unresolvable. */
+function refVo(field: MetaData, root: MetaData): MetaData | undefined {
+  const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
+  if (typeof ref !== "string") return undefined;
+  const direct = findObject(root, ref);
+  if (direct !== undefined) return direct;
+  const sep = ref.lastIndexOf(PACKAGE_SEPARATOR);
+  if (sep >= 0) return findObject(root, ref.slice(sep + PACKAGE_SEPARATOR.length));
+  return undefined;
+}
+
+function isObjectField(field: MetaData): boolean {
+  return field.subType === FIELD_SUBTYPE_OBJECT;
+}
+
+/**
+ * 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.
+ */
+function enumAlias(field: MetaData, ownerName: string): string | undefined {
+  if (field.subType !== FIELD_SUBTYPE_ENUM) return undefined;
+  const values = enumValues(field as MetaField);
+  if (values === undefined) return undefined;
+  return enumUnionAliasName(ownerName, field as MetaField);
+}
+
+/**
+ * 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).
+ */
+function isFieldRequired(field: MetaData): boolean {
+  return field.ownAttr(FIELD_ATTR_REQUIRED) === true;
+}
+
+/** The mirror→strict mapper name for a value-object (`toStrict<Name>`). */
+function mapperName(vo: MetaData): string {
+  return `toStrict${vo.name}`;
+}
+
+/**
+ * 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.
+ */
+function strictArg(field: MetaData, root: MetaData, ownerName: string): string {
+  const name = field.name;
+  const required = isFieldRequired(field);
+
+  if (isObjectField(field)) {
+    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`;
+    }
+    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`;
+    }
+    // Single nested object.
+    if (required) return `${fn}(m.${name}!)`;
+    return `m.${name} ? ${fn}(m.${name}) : null`;
+  }
+
+  // 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!`
+  // 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).
+  //
+  // 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
+  // `tsc --strict` TS2322 error. So the null-filtered result is CAST to `<Alias>[]`. The cast is
+  // sound: the engine validated each present element is a member of the closed set (else the field
+  // is lost/MALFORMED and extract throws), so the runtime string IS a valid union member.
+  const alias = enumAlias(field, ownerName);
+  if (isArray(field)) {
+    if (required) {
+      const filtered = `(m.${name} ?? []).filter((x): x is NonNullable<typeof x> => x != null)`;
+      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}`;
+    return alias !== undefined
+      ? `m.${name} == null ? null : (${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`).
+  //
+  // 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}!` : `m.${name} ?? null`;
+}
+
+/**
+ * Emit one `toStrict<VO>(m)` mapper per value-object reachable from `vo` (payload + nested,
+ * deduped, cycle-safe). Each maps the all-nullable `<VO>Extracted` mirror onto the strict `<VO>`
+ * payload interface. The ROOT mapper reads the canonically-named root mirror (`<Template>Extracted`)
+ * since the template name may differ from the payload VO name.
+ */
+function emitMappers(payloadVo: MetaData, root: MetaData, rootMirror: string): string {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  emitMapper(payloadVo, root, seen, out, rootMirror);
+  return out.join("\n\n");
+}
+
+function emitMapper(
+  vo: MetaData,
+  root: MetaData,
+  seen: Set<string>,
+  out: string[],
+  mirrorOverride?: string,
+): void {
+  if (seen.has(vo.name)) return;
+  seen.add(vo.name);
+
+  const fn = mapperName(vo);
+  const strict = vo.name;
+  const mir = mirrorOverride ?? mirrorName(vo);
+  const assigns = fields(vo).map((f) => `    ${f.name}: ${strictArg(f, root, vo.name)},`);
+  out.push(
+    [
+      `/** Map the all-nullable \`${mir}\` mirror onto the strict \`${strict}\` payload. Generated. */`,
+      `function ${fn}(m: ${mir}): ${strict} {`,
+      `  return {`,
+      ...assigns,
+      `  };`,
+      `}`,
+    ].join("\n"),
+  );
+
+  for (const f of fields(vo)) {
+    if (isObjectField(f)) {
+      const target = refVo(f, root);
+      if (target !== undefined) emitMapper(target, root, seen, out);
+    }
+  }
+}
+
+/**
+ * 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.
+ */
+function reachablePayloadTypes(vo: MetaData, root: MetaData): string[] {
+  const order: string[] = [];
+  const seen = new Set<string>();
+  const visit = (cur: MetaData) => {
+    if (seen.has(cur.name)) return;
+    seen.add(cur.name);
+    order.push(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 (isObjectField(f)) {
+        const target = refVo(f, root);
+        if (target !== undefined) visit(target);
+      }
+    }
+  };
+  visit(vo);
+  return order;
+}
+
+/** Collect the mirror-interface names reachable from `vo` (root mirror + nested VO mirrors). */
+function reachableMirrorTypes(vo: MetaData, root: MetaData, rootMirror: string): string[] {
+  const out: string[] = [rootMirror];
+  const seen = new Set<string>([vo.name]);
+  const visit = (cur: MetaData) => {
+    for (const f of fields(cur)) {
+      if (isObjectField(f)) {
+        const target = refVo(f, root);
+        if (target !== undefined && !seen.has(target.name)) {
+          seen.add(target.name);
+          out.push(mirrorName(target));
+          visit(target);
+        }
+      }
+    }
+  };
+  visit(vo);
+  return out;
+}
+
+/**
+ * Render the full `<TemplateName>.extractor.ts` for one `template.output` node.
+ * Throws if the template isn't found / isn't a template.output / its @payloadRef doesn't resolve,
+ * or if the target format is not json/xml (the extract tier requires the extract<Name> API, which
+ * only the json/xml output-parsers emit).
+ */
+export function renderExtractor(root: MetaData, templateName: string): string {
+  const tmpl = findTemplate(root, templateName);
+  if (!tmpl) {
+    throw new Error(`template "${templateName}" not found in metadata root`);
+  }
+  if (tmpl.subType !== TEMPLATE_SUBTYPE_OUTPUT) {
+    throw new Error(`template "${templateName}" is not a template.output (got subtype "${tmpl.subType}")`);
+  }
+  const payloadRef = tmpl.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
+  if (typeof payloadRef !== "string") {
+    throw new Error(`template "${templateName}" missing @payloadRef`);
+  }
+  const vo = findObject(root, payloadRef);
+  if (!vo) {
+    throw new Error(`template "${templateName}" @payloadRef "${payloadRef}" not found in metadata root`);
+  }
+  const format = ((tmpl.ownAttr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text").toLowerCase();
+  if (format !== "json" && format !== "xml") {
+    throw new Error(
+      `template "${templateName}" @format "${format}" has no extract API to extract over (json/xml only)`,
+    );
+  }
+
+  const strictType = vo.name; // the payload VO's interface name (payload-codegen emits the bare VO name)
+  const rootMirror = `${templateName}Extracted`;
+  const extractLenientWithName = `extractLenient${templateName}WithLoader`; // the nested-capable lenient extract (output-parser)
+  const extractLenientPublic = `extractLenient${templateName}`; // re-exposed never-throws lenient tier name
+  const extractName = `extract${templateName}`;
+  const rootMapper = mapperName(vo);
+
+  const payloadTypes = reachablePayloadTypes(vo, root);
+  const mirrorTypes = reachableMirrorTypes(vo, root, rootMirror);
+  const mappers = emitMappers(vo, root, rootMirror);
+
+  const lostMsg =
+    `${extractName}: lost required field(s): `;
+
+  return (
+    `// GENERATED — extractor for "${templateName}".\n` +
+    `//\n` +
+    `// Turns dirty LLM text into a fully-typed \`${strictType}\` graph (nested objects +\n` +
+    `// arrays-of-objects populated) in one call, by delegating to the nested-capable extract and\n` +
+    `// 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` +
+    `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` +
+    ` * extracted mirror onto the strict payload.\n` +
+    ` *\n` +
+    ` * @throws Error iff a \`@required\` field was lost (the strict opt-in gate).\n` +
+    ` */\n` +
+    `export function ${extractName}(root: MetaRoot, text: string): ${strictType} {\n` +
+    `  const r = ${extractLenientWithName}(root, text);\n` +
+    `  if (r.report.hasLostRequired()) {\n` +
+    `    throw new Error(${JSON.stringify(lostMsg)} + r.report.lostRequired().join(", "));\n` +
+    `  }\n` +
+    `  return ${rootMapper}(r.data!);\n` +
+    `}\n` +
+    `\n` +
+    `/**\n` +
+    ` * Extract a \`${strictType}\` from dirty \`text\` using the loaded \`root\`, never throwing.\n` +
+    ` * Re-exposes the nested-capable extract; inspect \`report\` for lost/defaulted fields.\n` +
+    ` */\n` +
+    `export function ${extractLenientPublic}(root: MetaRoot, text: string): ExtractionResult<${rootMirror}> {\n` +
+    `  return ${extractLenientWithName}(root, text);\n` +
+    `}\n` +
+    `\n` +
+    `${mappers}\n`
+  );
+}

package/src/templates/field-meta.ts

@@ -19,6 +19,7 @@ import {
   FIELD_SUBTYPE_TIMESTAMP,
   FIELD_SUBTYPE_CURRENCY,
   FIELD_SUBTYPE_ENUM,
+  FIELD_SUBTYPE_UUID,
   VIEW_SUBTYPE_TEXT,
   VIEW_SUBTYPE_DATE,
   VIEW_SUBTYPE_NUMBER,
@@ -80,6 +81,7 @@ function defaultViewForSubType(subType: string): string {
 export function zodTypeFor(field: MetaField): string {
   switch (field.subType) {
     case FIELD_SUBTYPE_STRING:
+    case FIELD_SUBTYPE_UUID:
       return "z.string()";
     case FIELD_SUBTYPE_BOOLEAN:
       return "z.boolean()";

package/src/templates/filter-type.ts

@@ -13,25 +13,27 @@ import {
   FIELD_SUBTYPE_LONG,
   FIELD_SUBTYPE_DOUBLE,
   FIELD_SUBTYPE_FLOAT,
-  FIELD_SUBTYPE_DECIMAL,
   opsForSubType,
 } from "@metaobjectsdev/metadata";
 import { isSortableField } from "./filter-shared.js";
 
-const NUMBER_SUBTYPES = new Set<string>([
+// VALUE-type classification only (distinct from the OPERATOR band, which comes from
+// opsForSubType). decimal is deliberately NOT here: its operator band stays NUMERIC
+// (eq/ne/gt/gte/lt/lte/in/isNull, see OPS_BY_SUBTYPE) but its VALUE type is `string`,
+// 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,
-  FIELD_SUBTYPE_DECIMAL,
 ]);
 
-/** Maps a field subtype to its TS value type name for operator union codegen. */
+/** Maps a field subtype to its TS VALUE type name for operator union codegen. */
 function tsNameFor(fieldSubType: string): string {
   if (fieldSubType === FIELD_SUBTYPE_BOOLEAN) return "boolean";
-  if (NUMBER_SUBTYPES.has(fieldSubType)) return "number";
+  if (NUMBER_VALUE_SUBTYPES.has(fieldSubType)) return "number";
   return "string";
 }
 

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

@@ -1,9 +1,9 @@
 // server/typescript/packages/codegen-ts/src/templates/fr010-field-mapping.ts
 //
-// Shared field-kind mapping for the FR-010 codegen emitters (recover-schema-emitter +
+// 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
-// FieldKind member, the idiomatic nullable TS type used by the recover mirror interface,
-// and the RecoverMap accessor that reads it from the forgiving outcome map.
+// 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.
 //
 // Mirrors the C# Fr010FieldMapping (adapted to TS syntax + the `| null` nullable mirror).
 // Bounded scope (parity with Java/Kotlin/C#): scalar / enum / scalar-array. Nested object +
@@ -14,6 +14,7 @@ import {
   TYPE_FIELD,
   FIELD_SUBTYPE_STRING,
   FIELD_SUBTYPE_CLASS,
+  FIELD_SUBTYPE_UUID,
   FIELD_SUBTYPE_DATE,
   FIELD_SUBTYPE_TIME,
   FIELD_SUBTYPE_TIMESTAMP,
@@ -30,6 +31,11 @@ import {
   FIELD_SUBTYPE_OBJECT,
   FIELD_ATTR_REQUIRED,
   FIELD_ATTR_VALUES,
+  FIELD_ATTR_COERCE_DEFAULT,
+  FIELD_ATTR_DEFAULT,
+  FIELD_ATTR_NORMALIZE,
+  NORMALIZE_DEFAULT,
+  type NormalizeMode,
 } from "@metaobjectsdev/metadata";
 
 /** The render-engine FieldKind member name for a scalar field subtype, or null if non-scalar. */
@@ -37,9 +43,14 @@ 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:
     case FIELD_SUBTYPE_TIMESTAMP:
+    // field.decimal is a precision-exact decimal STRING on the wire (not a
+    // float64): extract/output map it as a string scalar so digits survive a
+    // round-trip — matching the generated TS `string` representation.
+    case FIELD_SUBTYPE_DECIMAL:
       return "STRING";
     case FIELD_SUBTYPE_INT:
     case FIELD_SUBTYPE_SHORT:
@@ -50,7 +61,6 @@ export function scalarKind(subType: string): string | null {
       return "LONG";
     case FIELD_SUBTYPE_DOUBLE:
     case FIELD_SUBTYPE_FLOAT:
-    case FIELD_SUBTYPE_DECIMAL:
       return "DOUBLE";
     case FIELD_SUBTYPE_BOOLEAN:
       return "BOOLEAN";
@@ -83,12 +93,52 @@ export function enumValues(field: MetaData): string[] {
   return [];
 }
 
-/** The nullable TS type for a field in the recover mirror interface. */
+/**
+ * FR-011: the field's `@coerceDefault` member symbol (present-but-uncoercible enum fallback),
+ * 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);
+  return typeof v === "string" && v.length > 0 ? v : 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);
+  return typeof v === "string" && v.length > 0 ? v : null;
+}
+
+/**
+ * FR-011: resolve the enum normalization mode for a field — field-level `@normalize`,
+ * else the owning `object.value`'s `@normalize` (the per-object default), else the global
+ * `NORMALIZE_DEFAULT` ("strip"). `ownerObject` may be null (resolution then skips the
+ * object tier). Mirrors the cross-port field → object → global resolution.
+ */
+export function resolveNormalize(field: MetaData, ownerObject: MetaData | null): NormalizeMode {
+  const fieldMode = normalizeAttrOf(field);
+  if (fieldMode != null) return fieldMode;
+  const objMode = ownerObject == null ? null : normalizeAttrOf(ownerObject);
+  if (objMode != null) return objMode;
+  return NORMALIZE_DEFAULT;
+}
+
+/** 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);
+  return typeof v === "string" && v.length > 0 ? (v as NormalizeMode) : null;
+}
+
+/** The nullable TS type for a field in the extract mirror interface. */
 export function mirrorType(field: MetaData): string {
-  // Matches asStringList's `(string | null)[] | null` return — a recovered array
+  // Nested object (single or array): the self-contained path defers to null (typed unknown);
+  // the runtime-delegating path overrides this with the nested mirror type. Checked BEFORE the
+  // generic isArray branch so an array-of-objects is NOT mistyped as a string array.
+  if (field.subType === FIELD_SUBTYPE_OBJECT) return "unknown"; // nested deferred
+  // Matches asStringList's `(string | null)[] | null` return — a extracted array
   // can contain null elements where individual items were lost.
   if (isArray(field)) return "(string | null)[] | null";
-  if (field.subType === FIELD_SUBTYPE_OBJECT) return "unknown"; // nested deferred
   if (field.subType === FIELD_SUBTYPE_ENUM) return "string | null"; // enum is string-backed
   switch (scalarKind(field.subType)) {
     case "INT":
@@ -103,13 +153,16 @@ export function mirrorType(field: MetaData): string {
 }
 
 /**
- * The RecoverMap.as* helper name that reads this field from the forgiving map, or null
+ * The ExtractMap.as* helper name that reads this field from the forgiving map, or null
  * for a nested object (which emits a null literal, not a helper call). Single source of
- * truth for the per-field dispatch — both recoverMapCall and recoverMapHelpersUsed use it.
+ * truth for the per-field dispatch — both extractMapCall and extractMapHelpersUsed use it.
  */
-function recoverMapHelper(field: MetaData): string | null {
+function extractMapHelper(field: MetaData): string | null {
+  // Nested object (single or array) → null literal in the self-contained path (no helper).
+  // Checked BEFORE isArray so an array-of-objects is NOT read via asStringList (which would not
+  // type-check against the nested mirror's `(NestedExtracted | null)[]`). Mirrors the Java fix.
+  if (field.subType === FIELD_SUBTYPE_OBJECT) return null;
   if (isArray(field)) return "asStringList";
-  if (field.subType === FIELD_SUBTYPE_OBJECT) return null; // null literal, no helper
   if (field.subType === FIELD_SUBTYPE_ENUM) return "asString";
   switch (scalarKind(field.subType)) {
     case "INT":
@@ -125,18 +178,18 @@ function recoverMapHelper(field: MetaData): string | null {
   }
 }
 
-/** The RecoverMap.as* helper name + call that reads this field from the forgiving map `d`. */
-export function recoverMapCall(field: MetaData): string {
-  const helper = recoverMapHelper(field);
-  if (helper === null) return "null /* FR-010: nested recover deferred */";
+/** The ExtractMap.as* helper name + call that reads this field from the forgiving map `d`. */
+export function extractMapCall(field: MetaData): string {
+  const helper = extractMapHelper(field);
+  if (helper === null) return "null /* FR-010: nested extract deferred */";
   return `${helper}(d, ${jsonStringLiteral(field.name)})`;
 }
 
-/** Distinct RecoverMap helper names used across a value-object's fields (for the import). */
-export function recoverMapHelpersUsed(vo: MetaData): string[] {
+/** Distinct ExtractMap helper names used across a value-object's fields (for the import). */
+export function extractMapHelpersUsed(vo: MetaData): string[] {
   const used = new Set<string>();
   for (const f of fields(vo)) {
-    const helper = recoverMapHelper(f);
+    const helper = extractMapHelper(f);
     if (helper !== null) used.add(helper);
   }
   return [...used].sort();

package/src/templates/inferred-types.ts

@@ -26,6 +26,7 @@ import {
   FIELD_SUBTYPE_TIME,
   FIELD_SUBTYPE_TIMESTAMP,
   FIELD_SUBTYPE_CLASS,
+  FIELD_SUBTYPE_UUID,
   FIELD_ATTR_REQUIRED,
   FIELD_ATTR_OBJECT_REF,
 } from "@metaobjectsdev/metadata";
@@ -46,6 +47,29 @@ export type ${entity.name}Update = Partial<${entity.name}Insert>;
 `;
 }
 
+/**
+ * The string-literal-union type-alias name for a `field.enum` field — the SINGLE
+ * source of truth for enum-union naming (reused by the entity inferred-types
+ * emitter AND the payload-VO emitter so both agree byte-for-byte).
+ *
+ * - If the field extends an abstract field.enum (super), use the super field's
+ *   PascalCase name (so multiple fields sharing one abstract enum collapse to a
+ *   single alias).
+ * - Otherwise use `<Owner><FieldPascal>` for inline enums, where `<Owner>` is the
+ *   owning object's name (entity OR payload value-object).
+ */
+export function enumUnionAliasName(ownerName: string, field: MetaField): string {
+  const superField = field.resolveSuper();
+  return superField !== undefined
+    ? toPascalCase(superField.name)
+    : `${ownerName}${toPascalCase(field.name)}`;
+}
+
+/** The `"A" | "B"` union string for a set of enum member values. */
+export function enumUnionString(values: string[]): string {
+  return values.map((v) => JSON.stringify(v)).join(" | ");
+}
+
 /**
  * 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.
@@ -63,17 +87,11 @@ export function renderEnumTypeAliases(entity: MetaObject): Code | null {
     const values = enumValues(field);
     if (values === undefined) continue;
 
-    // Derive the type-alias name.
-    const superField = field.resolveSuper();
-    const typeName = superField !== undefined
-      ? toPascalCase(superField.name)
-      : `${entity.name}${toPascalCase(field.name)}`;
-
+    const typeName = enumUnionAliasName(entity.name, field);
     if (seen.has(typeName)) continue;
     seen.add(typeName);
 
-    const union = values.map((v) => JSON.stringify(v)).join(" | ");
-    lines.push(`export type ${typeName} = ${union};`);
+    lines.push(`export type ${typeName} = ${enumUnionString(values)};`);
   }
 
   return lines.length > 0 ? code`${lines.join("\n")}` : null;
@@ -86,13 +104,17 @@ 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",
-  [FIELD_SUBTYPE_DECIMAL]: "number",
+  // field.decimal is precision-exact: Drizzle's pg `numeric` column infers as
+  // `string` (the driver returns NUMERIC as a string to avoid float rounding),
+  // so the value-object/structural-interface scalar mapping must match.
+  [FIELD_SUBTYPE_DECIMAL]: "string",
   [FIELD_SUBTYPE_CURRENCY]: "number",
   [FIELD_SUBTYPE_BOOLEAN]: "boolean",
   [FIELD_SUBTYPE_DATE]: "string",
@@ -100,14 +122,6 @@ const SCALAR_TS_BY_SUBTYPE: Record<string, string> = {
   [FIELD_SUBTYPE_TIMESTAMP]: "string",
 };
 
-/** Type-alias name for a field.enum, mirroring renderEnumTypeAliases. */
-function enumTypeAliasName(entity: MetaObject, field: MetaField): string {
-  const superField = field.resolveSuper();
-  return superField !== undefined
-    ? toPascalCase(superField.name)
-    : `${entity.name}${toPascalCase(field.name)}`;
-}
-
 /**
  * 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
@@ -130,7 +144,7 @@ function valueObjectFieldType(entity: MetaObject, field: MetaField): Code {
   if (field.subType === FIELD_SUBTYPE_ENUM) {
     const values = enumValues(field);
     if (values !== undefined) {
-      const alias = enumTypeAliasName(entity, field);
+      const alias = enumUnionAliasName(entity.name, field);
       return field.isArray ? code`${alias}[]` : code`${alias}`;
     }
     return field.isArray ? code`string[]` : code`string`;