@metaobjectsdev/codegen-ts 0.14.1 → 0.15.0-rc.1

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

@@ -14,6 +14,8 @@ import {
   TYPE_FIELD,
   FIELD_SUBTYPE_STRING,
   FIELD_SUBTYPE_UUID,
+  FIELD_SUBTYPE_URI,
+  FIELD_SUBTYPE_INET,
   FIELD_SUBTYPE_DATE,
   FIELD_SUBTYPE_TIME,
   FIELD_SUBTYPE_TIMESTAMP,
@@ -41,6 +43,9 @@ export function scalarKind(subType: string): string | null {
   switch (subType) {
     case FIELD_SUBTYPE_STRING:
     case FIELD_SUBTYPE_UUID:
+    // ADR-0036/0037 Wave 3: uri/inet are string scalars on the wire.
+    case FIELD_SUBTYPE_URI:
+    case FIELD_SUBTYPE_INET:
     case FIELD_SUBTYPE_DATE:
     case FIELD_SUBTYPE_TIME:
     case FIELD_SUBTYPE_TIMESTAMP:
@@ -71,7 +76,7 @@ export function fields(vo: MetaData): MetaData[] {
 
 /** isArray is a native (reserved) property on MetaData, not an attr. */
 export function isArray(field: MetaData): boolean {
-  return field.isArray === true;
+  return field.resolvedIsArray();
 }
 
 /** True iff the field's @required is explicitly true (or the string "true"). */

package/src/templates/inferred-types.ts

@@ -25,6 +25,8 @@ import {
   FIELD_SUBTYPE_TIME,
   FIELD_SUBTYPE_TIMESTAMP,
   FIELD_SUBTYPE_UUID,
+  FIELD_SUBTYPE_URI,
+  FIELD_SUBTYPE_INET,
   FIELD_ATTR_REQUIRED,
   FIELD_ATTR_OBJECT_REF,
   FIELD_ATTR_VALUE_TYPE,
@@ -149,6 +151,10 @@ export function renderEnumTypeAliases(entity: MetaObject, ctx?: RenderContext):
 const SCALAR_TS_BY_SUBTYPE: Record<string, string> = {
   [FIELD_SUBTYPE_STRING]: "string",
   [FIELD_SUBTYPE_UUID]: "string",
+  // ADR-0036/0037 Wave 3: uri/inet bind to TS `string` (TS has no native URI/IP
+  // type, same as uuid). Other ports bind to their native URI/IP type.
+  [FIELD_SUBTYPE_URI]: "string",
+  [FIELD_SUBTYPE_INET]: "string",
   [FIELD_SUBTYPE_INT]: "number",
   [FIELD_SUBTYPE_LONG]: "number",
   [FIELD_SUBTYPE_DOUBLE]: "number",
@@ -184,15 +190,15 @@ export function fieldTsTypeString(ownerName: string, field: MetaField): string {
   // the column is a bare `jsonb()` returning any parsed JSON value, so the TS type
   // stays in lock-step with the `z.unknown()` Zod emission (NOT `string`).
   if (field.attr(FIELD_ATTR_DB_COLUMN_TYPE) === DB_COLUMN_TYPE_JSONB) {
-    return field.isArray ? "unknown[]" : "unknown";
+    return field.resolvedIsArray() ? "unknown[]" : "unknown";
   }
   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.resolvedIsArray() ? `${base}[]` : base;
     }
-    return field.isArray ? "unknown[]" : "unknown";
+    return field.resolvedIsArray() ? "unknown[]" : "unknown";
   }
   if (field.subType === FIELD_SUBTYPE_ENUM) {
     const values = enumValues(field);
@@ -202,12 +208,12 @@ export function fieldTsTypeString(ownerName: string, field: MetaField): string {
       // 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.resolvedIsArray() ? `(${union})[]` : union;
     }
-    return field.isArray ? "string[]" : "string";
+    return field.resolvedIsArray() ? "string[]" : "string";
   }
   const scalar = SCALAR_TS_BY_SUBTYPE[field.subType] ?? "unknown";
-  return field.isArray ? `${scalar}[]` : scalar;
+  return field.resolvedIsArray() ? `${scalar}[]` : scalar;
 }
 
 /**
@@ -219,7 +225,7 @@ function valueObjectFieldType(entity: MetaObject, field: MetaField, ctx?: Render
   // `@dbColumnType: jsonb` (open JSON bag) → `unknown`, in lock-step with
   // fieldTsTypeString above and the `z.unknown()` Zod emission.
   if (field.attr(FIELD_ATTR_DB_COLUMN_TYPE) === DB_COLUMN_TYPE_JSONB) {
-    return field.isArray ? code`unknown[]` : code`unknown`;
+    return field.resolvedIsArray() ? code`unknown[]` : code`unknown`;
   }
   // field.object: import the referenced TS interface from its sibling module
   // so ts-poet hoists the import. Mirrors zod-validators.ts's `<Ref>InsertSchema`
@@ -237,9 +243,9 @@ function valueObjectFieldType(entity: MetaObject, field: MetaField, ctx?: Render
         ? 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.resolvedIsArray() ? code`${refImp}[]` : code`${refImp}`;
     }
-    return field.isArray ? code`unknown[]` : code`unknown`;
+    return field.resolvedIsArray() ? code`unknown[]` : code`unknown`;
   }
 
   // field.map: Record<string, V> — V is a value-object (@objectRef) or a scalar (@valueType).
@@ -274,16 +280,16 @@ function valueObjectFieldType(entity: MetaObject, field: MetaField, ctx?: Render
             ? providedEnumImportSpecifier(ctx, shared.name)
             : sharedEnumImportSpecifier(ctx, entity.package);
           const sym = imp(`${shared.name}@${spec}`);
-          return field.isArray ? code`${sym}[]` : code`${sym}`;
+          return field.resolvedIsArray() ? code`${sym}[]` : code`${sym}`;
         }
       }
-      return field.isArray ? code`${alias}[]` : code`${alias}`;
+      return field.resolvedIsArray() ? code`${alias}[]` : code`${alias}`;
     }
-    return field.isArray ? code`string[]` : code`string`;
+    return field.resolvedIsArray() ? code`string[]` : code`string`;
   }
 
   const scalar = SCALAR_TS_BY_SUBTYPE[field.subType] ?? "unknown";
-  return field.isArray ? code`${scalar}[]` : code`${scalar}`;
+  return field.resolvedIsArray() ? code`${scalar}[]` : code`${scalar}`;
 }
 
 /**

package/src/templates/output-format-spec-emitter.ts

@@ -42,12 +42,14 @@ export function specLiteral(vo: MetaData, template: MetaData, rootName: string):
 }
 
 function resolveFormat(template: MetaData): string {
-  const f = template.ownAttr(TEMPLATE_ATTR_FORMAT);
+  // ADR-0039: resolving — a template may inherit @format via extends.
+  const f = template.attr(TEMPLATE_ATTR_FORMAT);
   return typeof f === "string" && f.toLowerCase() === "xml" ? "Format.XML" : "Format.JSON";
 }
 
 function resolvePromptStyle(template: MetaData): string {
-  switch (template.ownAttr(TEMPLATE_ATTR_PROMPT_STYLE)) {
+  // ADR-0039: resolving — a template may inherit @promptStyle via extends.
+  switch (template.attr(TEMPLATE_ATTR_PROMPT_STYLE)) {
     case PROMPT_STYLE_INLINE:
       return "PromptStyle.INLINE";
     case PROMPT_STYLE_EXAMPLE_ONLY:
@@ -92,6 +94,8 @@ function promptFieldLiteral(field: MetaData): string {
 }
 
 function optStringAttr(field: MetaData, attrName: string): string {
-  const v = field.ownAttr(attrName);
+  // ADR-0039: resolving — a field may inherit @example/@instruction via extends
+  // (mirrors the Java OutputFormatSpecEmitter own→resolving flip).
+  const v = field.attr(attrName);
   return typeof v === "string" ? jsonStringLiteral(v) : "null";
 }

package/src/templates/output-parser.ts

@@ -42,20 +42,22 @@ const SCALAR_ZOD: Record<string, string> = {
   boolean: "z.boolean()",
 };
 
+// ADR-0039: resolving — root has no super (children()==ownChildren()); a top-level object/template may itself extend, so resolve rather than work-by-accident.
 function findObject(root: MetaData, name: string): MetaData | undefined {
   // FR-032 — @payloadRef is FQN after the desugar/sweep; match on the effective
   // FQN resolution key (with bare back-compat).
-  return root.ownChildren().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, name));
+  return root.children().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, name));
 }
 
+// ADR-0039: resolving — root has no super (children()==ownChildren()); a top-level object/template may itself extend, so resolve rather than work-by-accident.
 function findTemplate(root: MetaData, name: string): MetaData | undefined {
-  return root.ownChildren().find((c) => c.type === TYPE_TEMPLATE && c.name === name);
+  return root.children().find((c) => c.type === TYPE_TEMPLATE && c.name === name);
 }
 
 /** Render the Zod expression for a single field; recurses on @objectRef. */
 function fieldZod(field: MetaData, root: MetaData, seen: ReadonlySet<string>, depth: number): string {
   // isArray is a native (reserved) property on MetaData, not an attr.
-  const isArray = field.isArray === true;
+  const isArray = field.resolvedIsArray();
   let base: string;
   if (field.subType === FIELD_SUBTYPE_OBJECT) {
     const refName = field.attr(FIELD_ATTR_OBJECT_REF);
@@ -100,7 +102,8 @@ export function renderOutputParser(root: MetaData, templateName: string): string
   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);
+  // ADR-0039: resolving — a template may inherit its @* refs/format/kind via extends.
+  const payloadRef = tmpl.attr(TEMPLATE_ATTR_PAYLOAD_REF);
   if (typeof payloadRef !== "string") {
     throw new Error(`template "${templateName}" missing @payloadRef`);
   }
@@ -119,7 +122,8 @@ export function renderOutputParser(root: MetaData, templateName: string): string
   // FR-010: emit the tolerant extract() API alongside the strict Zod parser when the
   // template targets json/xml. The @payloadRef already resolved to a value-object above,
   // so a ExtractSchema can always be baked. text-format outputs get no extract.
-  const format = (tmpl.ownAttr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text";
+  // ADR-0039: resolving — a template may inherit its @* refs/format/kind via extends.
+  const format = (tmpl.attr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text";
   const lc = format.toLowerCase();
   const emitExtractLenient = lc === "json" || lc === "xml";
 

package/src/templates/output-prompt.ts

@@ -21,17 +21,20 @@ import {
 } from "@metaobjectsdev/metadata";
 import { specLiteral } from "./output-format-spec-emitter.js";
 
+// ADR-0039: resolving — root has no super (children()==ownChildren()); a top-level object/template may itself extend, so resolve rather than work-by-accident.
 function findObject(root: MetaData, name: string): MetaData | undefined {
-  return root.ownChildren().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, name));
+  return root.children().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, name));
 }
 
+// ADR-0039: resolving — root has no super (children()==ownChildren()); a top-level object/template may itself extend, so resolve rather than work-by-accident.
 function findTemplate(root: MetaData, name: string): MetaData | undefined {
-  return root.ownChildren().find((c) => c.type === TYPE_TEMPLATE && c.name === name);
+  return root.children().find((c) => c.type === TYPE_TEMPLATE && c.name === name);
 }
 
 /** True iff the template.output's @format is json or xml (the renderable structured formats). */
 export function templateSupportsPrompt(tmpl: MetaData): boolean {
-  const f = ((tmpl.ownAttr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text").toLowerCase();
+  // ADR-0039: resolving — a template may inherit its @* refs/format/kind via extends.
+  const f = ((tmpl.attr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text").toLowerCase();
   return f === "json" || f === "xml";
 }
 
@@ -51,7 +54,8 @@ export function renderOutputPrompt(root: MetaData, templateName: string): string
   if (!templateSupportsPrompt(tmpl)) {
     throw new Error(`template "${templateName}" @format is not json/xml — no prompt fragment`);
   }
-  const payloadRef = tmpl.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
+  // ADR-0039: resolving — a template may inherit its @* refs/format/kind via extends.
+  const payloadRef = tmpl.attr(TEMPLATE_ATTR_PAYLOAD_REF);
   if (typeof payloadRef !== "string") {
     throw new Error(`template "${templateName}" missing @payloadRef`);
   }

package/src/templates/projection-decl.ts

@@ -131,6 +131,9 @@ export function renderProjectionDecl(
       for (const f of baseObj.fields()) allFields.push(f);
     }
   }
+  // ADR-0039: own — category 1 (emit-declared-here): the super's effective fields
+  // were already collected above; append only the projection's OWN new fields so
+  // inherited fields are not duplicated.
   for (const f of projection.ownFields()) allFields.push(f);
 
   // A field.object passthrough carries the value-object's Zod schema (so the
@@ -149,7 +152,7 @@ export function renderProjectionDecl(
     const refBase = objectRefOf(f);
     if (refBase) {
       const schemaSym = imp(`${refBase}InsertSchema@${voModule(refBase)}`);
-      const base = f.isArray
+      const base = f.resolvedIsArray()
         ? code`${z}.array(${schemaSym})`
         : code`${schemaSym}`;
       return code`  ${f.name}: ${base}${nullable}`;

package/src/templates/queries-file.ts

@@ -15,6 +15,8 @@ import {
   renderCreateFn,
   renderUpdateFn,
   renderDeleteByIdFn,
+  renderReverseFinderFns,
+  reverseFksFor,
   getPkInfo,
 } from "./queries.js";
 import { pluralize, findByIdFnName, listFnName } from "../naming.js";
@@ -90,6 +92,16 @@ import { ${varName}, type ${entityName}, ${entityName}InsertSchema } from ${JSON
     renderDeleteByIdFn(obj, ctx),
   ];
 
+  // ADR-0038 — reverse-relationship navigation via explicit FK finders. Each FK
+  // this entity holds (`identity.reference`) gets `find<Plural>By<FkField>` +
+  // its batched `…In` sibling, so the referenced entity can navigate back to its
+  // referencing rows with a plain, single-query, framework-free read. FK field
+  // names are unique within the entity, so the finder names never collide — the
+  // same-pair case (3 FKs to one target) yields 3 distinct finders.
+  for (const fk of reverseFksFor(obj)) {
+    sections.push(renderReverseFinderFns(obj, fk, ctx));
+  }
+
   // Render ts-poet body first, then prepend the @generated header so it lands
   // at line 1 ahead of any imports.
   const body = joinCode(sections, { on: "\n" }).toString();
@@ -178,6 +190,7 @@ export async function ${listFnName(entityName)}(db: Db, opts?: { limit?: number;
 function renderTphQueriesFile(base: MetaObject, ctx: RenderContext): string {
   const baseName = base.name;
   const tableVar = ctx.collectionName(baseName);
+  // ADR-0039: own — TPH discriminator, read own to identify the base level.
   const discField = base.ownAttr(OBJECT_ATTR_DISCRIMINATOR) as string;
   const { fieldName: pkField, tsType: pkType } = getPkInfo(base, ctx);
 
@@ -225,6 +238,7 @@ export async function list${pluralize(baseName)}(db: Db, opts?: { limit?: number
   // --- Per-subtype CRUD against the single base table ---
   const subtypeSections: Code[] = [];
   for (const sub of tphConcreteSubtypes(base, ctx.loadedRoot)) {
+    // ADR-0039: own — each concrete subtype declares its OWN @discriminatorValue.
     const value = sub.ownAttr(OBJECT_ATTR_DISCRIMINATOR_VALUE) as string;
     const valueLit = JSON.stringify(value);
     const subFileSpec = entityModuleSpecifier(

package/src/templates/queries.ts

@@ -2,7 +2,7 @@
 // Each returns a ts-poet Code block; composed into a file by queries-file.ts.
 
 import { code, imp, type Code } from "ts-poet";
-import type { MetaObject } from "@metaobjectsdev/metadata";
+import { type MetaObject, stripPackage } from "@metaobjectsdev/metadata";
 import { IDENTITY_ATTR_FIELDS } from "@metaobjectsdev/metadata";
 import type { RenderContext } from "../render-context.js";
 import {
@@ -11,8 +11,19 @@ import {
   createFnName,
   updateFnName,
   deleteByIdFnName,
+  reverseFinderFnName,
+  reverseFinderInFnName,
 } from "../naming.js";
 
+/** Map a field subType to the generated TS scalar type for keys/values. */
+function subTypeToTsType(subType: string): "number" | "boolean" | "string" {
+  return subType === "long" || subType === "int" || subType === "short" || subType === "byte"
+    ? "number"
+    : subType === "boolean"
+      ? "boolean"
+      : "string";
+}
+
 /** Get the PK field name and its TS type for a given entity. */
 export function getPkInfo(entity: MetaObject, ctx: RenderContext): { fieldName: string; tsType: string } {
   // Use primaryIdentity() to find the primary identity (may be inherited from extends:/super:).
@@ -22,13 +33,7 @@ export function getPkInfo(entity: MetaObject, ctx: RenderContext): { fieldName:
   const pkFieldName = fields?.[0] ?? "id";
   const pkInfo = ctx.pkMap.get(entity.name);
   const subType = pkInfo?.fieldSubType ?? "long";
-  const tsType =
-    subType === "long" || subType === "int" || subType === "short" || subType === "byte"
-      ? "number"
-      : subType === "boolean"
-        ? "boolean"
-        : "string";
-  return { fieldName: pkFieldName, tsType };
+  return { fieldName: pkFieldName, tsType: subTypeToTsType(subType) };
 }
 
 export function renderFindByIdFn(entity: MetaObject, ctx: RenderContext): Code {
@@ -114,3 +119,58 @@ export async function ${fnName}(db: Db, ${pkField}: ${pkType}): Promise<boolean>
 }
 `;
 }
+
+/**
+ * One reverse FK finder pair (ADR-0038): the entity holding this FK (`E`) gains
+ * `find<EPlural>By<FkField>(value)` (single, `WHERE fk = ?`) and
+ * `find<EPlural>By<FkField>In(values)` (batched, `WHERE fk IN (…)`, anti-N+1) so
+ * the referenced entity `T` can navigate to its referencing `E` rows by calling
+ * the finder with a `T` id. Both are plain, framework-free, single-query reads.
+ */
+interface ReverseFk {
+  /** FK FIELD name on this entity (logical), e.g. `currentSceneId`. */
+  fkField: string;
+  /** Target entity (the `T` referenced), e.g. `Scene`. Drives the value TS type. */
+  targetEntity: string;
+}
+
+/** Collect this entity's OWN reverse FK targets, in declaration order. */
+export function reverseFksFor(entity: MetaObject): ReverseFk[] {
+  const out: ReverseFk[] = [];
+  for (const ref of entity.referenceIdentities()) {
+    const fkField = ref.fields[0];
+    const target = ref.targetEntity;
+    if (!fkField || !target) continue;
+    out.push({ fkField, targetEntity: stripPackage(target) });
+  }
+  return out;
+}
+
+/** Render the single + batched reverse finders for one FK on `entity`. */
+export function renderReverseFinderFns(entity: MetaObject, fk: ReverseFk, ctx: RenderContext): Code {
+  const varName = ctx.collectionName(entity.name);
+  const entityName = entity.name;
+  // The Drizzle table object is keyed by the LOGICAL field name (the DB column
+  // name is the argument to integer()/text()), so column access uses fk.fkField.
+  // The FK value type is the target entity's PK type (the FK references it). Fall
+  // back to the FK field's own subType, then to number (long-shaped key default).
+  const targetPk = ctx.pkMap.get(fk.targetEntity);
+  const ownField = entity.findField(fk.fkField);
+  const valueType = subTypeToTsType(targetPk?.fieldSubType ?? ownField?.subType ?? "long");
+
+  const singleName = reverseFinderFnName(entityName, fk.fkField);
+  const batchName = reverseFinderInFnName(entityName, fk.fkField);
+  const eqSym = imp("eq@drizzle-orm");
+  const inArraySym = imp("inArray@drizzle-orm");
+
+  return code`
+export async function ${singleName}(db: Db, ${fk.fkField}: ${valueType}): Promise<${entityName}[]> {
+  return db.select().from(${varName}).where(${eqSym}(${varName}.${fk.fkField}, ${fk.fkField}));
+}
+
+export async function ${batchName}(db: Db, ${fk.fkField}s: ${valueType}[]): Promise<${entityName}[]> {
+  if (${fk.fkField}s.length === 0) return [];
+  return db.select().from(${varName}).where(${inArraySym}(${varName}.${fk.fkField}, ${fk.fkField}s));
+}
+`;
+}

package/src/templates/render-helper.ts

@@ -53,12 +53,14 @@ import {
   type VerifyError,
 } from "@metaobjectsdev/render";
 
+// ADR-0039: resolving — root has no super (children()==ownChildren()); a top-level object/template may itself extend, so resolve rather than work-by-accident.
 function findObject(root: MetaData, name: string): MetaData | undefined {
-  return root.ownChildren().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, name));
+  return root.children().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, name));
 }
 
+// ADR-0039: resolving — root has no super (children()==ownChildren()); a top-level object/template may itself extend, so resolve rather than work-by-accident.
 function findTemplate(root: MetaData, name: string): MetaData | undefined {
-  return root.ownChildren().find((c) => c.type === TYPE_TEMPLATE && c.name === name);
+  return root.children().find((c) => c.type === TYPE_TEMPLATE && c.name === name);
 }
 
 /**
@@ -150,7 +152,8 @@ export function renderRenderHelper(
       `template "${templateName}" is not a template.output (got subtype "${tmpl.subType}")`,
     );
   }
-  const payloadRef = tmpl.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
+  // ADR-0039: resolving — a template may inherit its @* refs/format/kind via extends.
+  const payloadRef = tmpl.attr(TEMPLATE_ATTR_PAYLOAD_REF);
   if (typeof payloadRef !== "string") {
     throw new Error(`template "${templateName}" missing @payloadRef`);
   }
@@ -165,13 +168,15 @@ export function renderRenderHelper(
   const ft = fieldTreeLiteral(fields);
   const fnName = `render${templateName}`;
 
-  const kind = ((tmpl.ownAttr(TEMPLATE_ATTR_KIND) as string | undefined) ?? TEMPLATE_KIND_DEFAULT)
+  // ADR-0039: resolving — a template may inherit its @* refs/format/kind via extends.
+  const kind = ((tmpl.attr(TEMPLATE_ATTR_KIND) as string | undefined) ?? TEMPLATE_KIND_DEFAULT)
     .toLowerCase();
 
   if (kind === TEMPLATE_KIND_EMAIL) {
-    const subjectRef = tmpl.ownAttr(TEMPLATE_ATTR_SUBJECT_REF);
-    const htmlBodyRef = tmpl.ownAttr(TEMPLATE_ATTR_HTML_BODY_REF);
-    const textBodyRef = tmpl.ownAttr(TEMPLATE_ATTR_TEXT_BODY_REF);
+    // ADR-0039: resolving — a template may inherit its @* refs/format/kind via extends.
+    const subjectRef = tmpl.attr(TEMPLATE_ATTR_SUBJECT_REF);
+    const htmlBodyRef = tmpl.attr(TEMPLATE_ATTR_HTML_BODY_REF);
+    const textBodyRef = tmpl.attr(TEMPLATE_ATTR_TEXT_BODY_REF);
     if (typeof subjectRef !== "string") {
       throw new Error(`template "${templateName}" (email) missing @subjectRef`);
     }
@@ -210,12 +215,14 @@ export function ${fnName}(payload: ${payloadRef}, provider: Provider): EmailDocu
   }
 
   // --- document kind ---
-  const textRef = tmpl.ownAttr(TEMPLATE_ATTR_TEXT_REF);
+  // ADR-0039: resolving — a template may inherit its @* refs/format/kind via extends.
+  const textRef = tmpl.attr(TEMPLATE_ATTR_TEXT_REF);
   if (typeof textRef !== "string") {
     throw new Error(`template "${templateName}" (document) missing @textRef`);
   }
-  const format = ((tmpl.ownAttr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text").toLowerCase();
-  const maxCharsAttr = tmpl.ownAttr(TEMPLATE_ATTR_MAX_CHARS);
+  // ADR-0039: resolving — a template may inherit its @* refs/format/kind via extends.
+  const format = ((tmpl.attr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text").toLowerCase();
+  const maxCharsAttr = tmpl.attr(TEMPLATE_ATTR_MAX_CHARS);
   const maxChars =
     typeof maxCharsAttr === "number"
       ? maxCharsAttr

package/src/templates/routes-file.ts

@@ -285,7 +285,8 @@ function renderM2mMount(
 
 /** Resolve a field's physical column name on an entity (defaults if missing). */
 function resolveJunctionColumn(entity: MetaObject, fieldName: string, ctx: RenderContext): string {
-  const field = entity.ownChildren().find((c) => c.type === TYPE_FIELD && c.name === fieldName);
+  // ADR-0039: resolving — a junction FK field may be inherited via extends.
+  const field = entity.children().find((c) => c.type === TYPE_FIELD && c.name === fieldName);
   if (!field) return fieldName;
   return resolveColumnName(field, ctx.columnNamingStrategy);
 }

package/src/templates/tph-discriminator.ts

@@ -74,6 +74,9 @@ export function tphRouteSegment(discriminatorValue: string): string {
 export function tphPlan(base: MetaObject, root: MetaRoot): TphPlan | null {
   const cached = _tphPlanCache.get(base);
   if (cached !== undefined) return cached;
+  // ADR-0039: own — TPH super-resolution walk (mirrors C# TphPlan). @discriminator
+  // must be read own to identify WHICH hierarchy level owns it (the discriminator
+  // base); a subtype must not be treated as a base by inheriting it.
   const discriminatorField = base.ownAttr(OBJECT_ATTR_DISCRIMINATOR);
   let plan: TphPlan | null = null;
   if (typeof discriminatorField === "string" && discriminatorField !== "") {
@@ -117,6 +120,7 @@ export function tphConcreteSubtypes(base: MetaObject, root: MetaRoot): MetaObjec
  * caller emits each as a nullable column (rows of other subtypes store NULL).
  */
 export function collectTphSubtypeFields(base: MetaObject, root: MetaRoot): MetaField[] {
+  // ADR-0039: own — TPH super-resolution walk; @discriminator identifies the base level.
   const discFieldName = base.ownAttr(OBJECT_ATTR_DISCRIMINATOR);
   if (typeof discFieldName !== "string" || discFieldName === "") return [];
 
@@ -140,6 +144,7 @@ export function renderTphDiscriminatorUnion(
   base: MetaObject,
   root: MetaRoot,
 ): Code | null {
+  // ADR-0039: own — TPH super-resolution walk; @discriminator identifies the base level.
   const discFieldName = base.ownAttr(OBJECT_ATTR_DISCRIMINATOR);
   if (typeof discFieldName !== "string" || discFieldName === "") return null;
 
@@ -209,6 +214,8 @@ function collectConcreteSubtypes(base: MetaObject, root: MetaRoot): SubtypeBindi
     if (obj.isAbstract === true) continue;
     if (obj === base) continue;
 
+    // ADR-0039: own — each concrete subtype declares its OWN @discriminatorValue;
+    // it must NOT inherit a parent's value (super-resolution walk, category 3).
     const value = obj.ownAttr(OBJECT_ATTR_DISCRIMINATOR_VALUE);
     if (typeof value !== "string" || value === "") continue;