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

package/src/naming.ts

@@ -121,6 +121,57 @@ export function deleteByIdFnName(entityName: string): string {
   return `delete${entityName}ById`;
 }
 
+// ---------------------------------------------------------------------------
+// ADR-0038 — reverse-relationship navigation as explicit FK finders.
+//
+// For each FK relationship (entity `E` references entity `T` via an
+// `identity.reference` FK field), `E`'s query surface gains a finder returning
+// the `E` rows matching a given `T` id. Two variants: a single-value finder and
+// a batched (anti-N+1) `…In` finder.
+//
+// CANONICAL NAMING CONVENTION (the cross-port contract — every port replicates
+// this spelling exactly):
+//
+//   find<EPlural>By<FkField>(value)      → SELECT … FROM E WHERE <fkColumn> = ?
+//   find<EPlural>By<FkField>In(values)   → SELECT … FROM E WHERE <fkColumn> IN (…)
+//
+// where:
+//   - <EPlural>  is the source entity name pluralized, PascalCase
+//     (`GameSession` → `GameSessions`) — the same spelling `list<Plural>` uses.
+//   - <FkField>  is the FK FIELD name (NOT the relationship/navigation name and
+//     NOT the raw column), PascalCased, with a single trailing `Id` dropped if
+//     present. The FK field name is unique within an entity, so the finder name
+//     is unique by construction — this is what dissolves the same-pair collision
+//     and removes any need for a naming attribute.
+//
+// SAME-PAIR EXAMPLE (GameSession has THREE FKs to Scene):
+//   FK field `currentSceneId`           → findGameSessionsByCurrentScene
+//   FK field `lastOpeningNarrativeSceneId` → findGameSessionsByLastOpeningNarrativeScene
+//   FK field `transitioningFromSceneId` → findGameSessionsByTransitioningFromScene
+// Three distinct finders — no collision.
+// ---------------------------------------------------------------------------
+
+/**
+ * Lower an FK field name to the `<FkField>` segment of a reverse finder name:
+ * PascalCase the field, then drop a single trailing `Id` if present.
+ * E.g. `currentSceneId` → `CurrentScene`, `authorId` → `Author`, `scene` → `Scene`.
+ */
+export function reverseFinderFkSegment(fkFieldName: string): string {
+  const pascal = toPascalCase(toCamelCase(fkFieldName));
+  // Drop a single trailing "Id" (but not a bare "Id" — that would yield "").
+  return pascal.length > 2 && pascal.endsWith("Id") ? pascal.slice(0, -2) : pascal;
+}
+
+/** Generated reverse single-value finder name: `find<EPlural>By<FkField>`. */
+export function reverseFinderFnName(sourceEntityName: string, fkFieldName: string): string {
+  return `find${pluralize(sourceEntityName)}By${reverseFinderFkSegment(fkFieldName)}`;
+}
+
+/** Generated reverse batched finder name: `find<EPlural>By<FkField>In`. */
+export function reverseFinderInFnName(sourceEntityName: string, fkFieldName: string): string {
+  return `${reverseFinderFnName(sourceEntityName, fkFieldName)}In`;
+}
+
 /**
  * Generated Fastify route-registrar name: camelCase `<entity>Routes`. The routes
  * generator (templates/routes-file.ts) emits a single exported

package/src/payload-codegen.ts

@@ -46,10 +46,11 @@ const SCALAR_TS: Record<string, string> = {
   timestamp: "string",
 };
 
+// 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/@responseRef are 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));
 }
 
 /**
@@ -68,7 +69,7 @@ function fieldTsType(
     const ref = field.attr(FIELD_ATTR_OBJECT_REF);
     const refName = typeof ref === "string" ? ref : "unknown";
     // isArray is a structural property on MetaData, not an attr.
-    const isArray = field.isArray;
+    const isArray = field.resolvedIsArray();
     const result: { type: string; refVo?: string } = {
       type: isArray ? `${refName}[]` : refName,
     };
@@ -83,15 +84,15 @@ function fieldTsType(
     if (values !== undefined) {
       const aliasName = enumUnionAliasName(ownerName, field as MetaField);
       return {
-        type: field.isArray ? `${aliasName}[]` : aliasName,
+        type: field.resolvedIsArray() ? `${aliasName}[]` : aliasName,
         enumAlias: { name: aliasName, decl: `export type ${aliasName} = ${enumUnionString(values)};` },
       };
     }
     // No @values → fall through to the raw-string representation.
-    return { type: field.isArray ? "string[]" : "string" };
+    return { type: field.resolvedIsArray() ? "string[]" : "string" };
   }
   const scalar = SCALAR_TS[field.subType] ?? "unknown";
-  return { type: field.isArray ? `${scalar}[]` : scalar };
+  return { type: field.resolvedIsArray() ? `${scalar}[]` : scalar };
 }
 
 /** True iff the field's @required is explicitly set to true. */
@@ -169,9 +170,10 @@ function pascal(s: string): string {
 
 /** Emit a typed render handle binding a template's @textRef + @format and typing its payload. */
 export function generateRenderHandle(root: MetaData, templateName: string): string {
-  const tmpl = root.ownChildren().find((c) => c.type === TYPE_TEMPLATE && c.name === templateName);
+  const tmpl = root.children().find((c) => c.type === TYPE_TEMPLATE && c.name === templateName);
   if (!tmpl) throw new Error(`template "${templateName}" not found`);
-  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);
   // FR-032 — @payloadRef is an FQN after the desugar/sweep; the generated TS
   // TYPE NAME is the resolved value-object's bare name (an FQN like
   // `acme::ai::Payload` is not a valid TS identifier). Fall back to the last
@@ -179,8 +181,9 @@ export function generateRenderHandle(root: MetaData, templateName: string): stri
   const payloadType =
     (typeof payloadRef === "string" ? findObject(root, payloadRef)?.name : undefined) ??
     (typeof payloadRef === "string" ? stripPackage(payloadRef) : String(payloadRef));
-  const textRef = tmpl.ownAttr(TEMPLATE_ATTR_TEXT_REF);
-  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 textRef = tmpl.attr(TEMPLATE_ATTR_TEXT_REF);
+  const format = (tmpl.attr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text";
   const fn = `render${pascal(templateName)}`;
   return [
     `import { render, type Provider } from "@metaobjectsdev/render";`,

package/src/projection/extract-view-spec.ts

@@ -100,7 +100,9 @@ export interface ExtractContext {
 // ---------------------------------------------------------------------------
 
 function findRelationship(obj: MetaData, name: string): MetaData | undefined {
-  return obj.ownChildren().find(
+  // ADR-0039: resolving — a @via join hop may traverse a relationship the entity
+  // inherits via extends; own-only would silently drop the join.
+  return obj.children().find(
     (c) => c.type === TYPE_RELATIONSHIP && c.name === name,
   );
 }
@@ -110,6 +112,9 @@ function viewName(projection: MetaObject, ctx: ExtractContext): string {
   // implements the four-step rule (kind-matching alias → legacy @table →
   // source.name → entity-name fallback), so the call below correctly resolves
   // @view / @materializedView / legacy @table for projection sources.
+  // ADR-0039: own — projection source classification (mirrors C# projection
+  // OwnSources / IsReadOnlyProjection): the view name comes from the projection's
+  // OWN read-only source, not one inherited via extends.
   const viewSource = projection.ownChildren().find(
     (c): c is MetaSource => c instanceof MetaSource && c.isReadOnly(),
   );
@@ -171,6 +176,10 @@ function baseEntityFor(
   // ERR_PROJECTION_IDENTITY_NOT_EXTENDED) rejects any projection whose identity
   // is not dotted-extends-bound before codegen runs. If that loader gate is
   // ever loosened, this function must grow the same fallback.
+  // ADR-0039: own — the base anchor is derived from the projection's OWN
+  // extends-bound declarations (refNamedOwner reads each node's own superRef,
+  // which only exists on locally-declared nodes); an inherited node carries no
+  // projection-local superRef, so own-iteration is correct here.
   for (const identity of projection
     .ownChildren()
     .filter((c) => c.type === TYPE_IDENTITY)) {
@@ -178,6 +187,7 @@ function baseEntityFor(
     if (named !== undefined) return named;
   }
   const targets = new Set<MetaObject>();
+  // ADR-0039: own — see above; base-entity derivation reads own extends-bound fields.
   for (const f of projection.ownChildren().filter((c) => c.type === TYPE_FIELD)) {
     const named = refNamedOwner(f, root);
     if (named !== undefined && named !== projection) targets.add(named);
@@ -253,10 +263,15 @@ function buildJoinTree(
 ): JoinTree {
   const allPaths: Path[] = [];
 
+  // ADR-0039: own — a projection's DECLARED field set IS the exposure (FR-024/
+  // ADR-0028, inclusive + fail-closed); iterate the projection's own fields and
+  // each field's own origin. origin.* NEVER inherits (ADR-0029), so origin reads
+  // below are own by policy (category 4).
   for (const field of projection.ownChildren()) {
     if (field.type !== TYPE_FIELD) continue;
     for (const origin of field.ownChildren()) {
       if (origin.type !== TYPE_ORIGIN) continue;
+      // ADR-0039: own (category 4) — origin.* never inherits (ADR-0029).
       const viaAttr = origin.subType === ORIGIN_SUBTYPE_AGGREGATE
         ? (origin.ownAttr(ORIGIN_AGGREGATE_ATTR_VIA) as string | undefined)
         : (origin.ownAttr(ORIGIN_PASSTHROUGH_ATTR_VIA) as string | undefined);
@@ -276,7 +291,8 @@ function buildJoinTree(
       for (const relName of relSegments) {
         const rel = findRelationship(currentObj, relName);
         if (!rel) break;
-        const targetName = rel.ownAttr(RELATIONSHIP_ATTR_OBJECT_REF) as string | undefined;
+        // ADR-0039: resolving — a traversed relationship may inherit @objectRef via extends.
+        const targetName = rel.attr(RELATIONSHIP_ATTR_OBJECT_REF) as string | undefined;
         // @objectRef may be package-qualified ("pkg::Entity") — the directory loader
         // qualifies a same-package objectRef even when authored bare — but findObject
         // keys on the BARE name (like the @via/@of/@from paths above). Strip first, or
@@ -284,7 +300,8 @@ function buildJoinTree(
         const target = targetName ? root.findObject(stripPackage(targetName)) : undefined;
         if (!target || !targetName) break;
 
-        const cardAttr = rel.ownAttr(RELATIONSHIP_ATTR_CARDINALITY) as string | undefined;
+        // ADR-0039: resolving — a traversed relationship may inherit @cardinality via extends.
+        const cardAttr = rel.attr(RELATIONSHIP_ATTR_CARDINALITY) as string | undefined;
         const cardinality: "one" | "many" = cardAttr === CARDINALITY_ONE ? "one" : "many";
 
         const ref = findReferenceBetween(currentObj as MetaObject, target);
@@ -391,6 +408,9 @@ function buildSelectSpec(
   // extends-bound fields (`{ field.int: { name: id, extends: "Program.id" } }`).
 
   // Fields explicitly declared on the projection.
+  // ADR-0039: own — the projection's DECLARED field set IS the exposure
+  // (FR-024/ADR-0028); iterate own fields + each field's own origin. origin.*
+  // NEVER inherits (ADR-0029), so the origin attr reads below are own (category 4).
   for (const field of projection.ownChildren()) {
     if (field.type !== TYPE_FIELD) continue;
     const origin = field.ownChildren().find((c) => c.type === TYPE_ORIGIN);
@@ -409,6 +429,7 @@ function buildSelectSpec(
     }
 
     if (origin.subType === ORIGIN_SUBTYPE_PASSTHROUGH) {
+      // ADR-0039: own (category 4) — origin.* never inherits (ADR-0029).
       const from = origin.ownAttr(ORIGIN_PASSTHROUGH_ATTR_FROM) as string;
       const dotIdx = from.indexOf(".");
       if (dotIdx < 1) continue;
@@ -432,6 +453,7 @@ function buildSelectSpec(
         sourceColumn: sourceColumnNameFor(targetField, ctx),
       });
     } else if (origin.subType === ORIGIN_SUBTYPE_AGGREGATE) {
+      // ADR-0039: own (category 4) — origin.* never inherits (ADR-0029).
       const agg = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_AGG) as AggregateFunction;
       const of_ = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_OF) as string;
       if (!agg || !of_) continue;
@@ -446,6 +468,7 @@ function buildSelectSpec(
       if (!targetField) continue;
       // Optional scoping filter — resolved against the aggregated entity (the @of
       // entity, reached at `sourceAlias`), e.g. max(version) over only active rows.
+      // ADR-0039: own (category 4) — origin.* never inherits (ADR-0029).
       const filterAttr = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_FILTER);
       const filter = filterAttr !== undefined
         ? resolveAggregateFilter(filterAttr, targetEntity, sourceAlias, ctx)

package/src/projection/projection-detector.ts

@@ -2,12 +2,16 @@ import { MetaSource } from "@metaobjectsdev/metadata";
 import type { MetaData } from "@metaobjectsdev/metadata";
 
 function hasReadOnlyKindSource(entity: MetaData): boolean {
+  // ADR-0039: own — projection source-kind classification. Mirrors C#
+  // IsReadOnlyProjection()/projection OwnSources: an entity's projection-ness is
+  // determined by its OWN declared source @kind, not one inherited via extends.
   return entity.ownChildren().some(
     (c) => c instanceof MetaSource && c.isReadOnly(),
   );
 }
 
 function hasWritableKindSource(entity: MetaData): boolean {
+  // ADR-0039: own — projection source-kind classification (see hasReadOnlyKindSource).
   return entity.ownChildren().some(
     (c) => c instanceof MetaSource && c.isWritable(),
   );

package/src/reference/queries.ts

@@ -27,6 +27,8 @@ import {
   renderCreateFn,
   renderUpdateFn,
   renderDeleteByIdFn,
+  renderReverseFinderFns,
+  reverseFksFor,
   isTphDiscriminatorBase,
   isProjection,
   isTphSubtype,
@@ -80,6 +82,13 @@ import { ${varName}, type ${entityName}, ${entityName}InsertSchema } from ${JSON
     renderDeleteByIdFn(obj, ctx),
   ];
 
+  // ADR-0038 — reverse-relationship navigation as explicit FK finders. One
+  // find<Plural>By<FkField> (+ batched …In) per FK this entity holds. OWNED:
+  // drop this loop if you don't want reverse finders.
+  for (const fk of reverseFksFor(obj)) {
+    sections.push(renderReverseFinderFns(obj, fk, ctx));
+  }
+
   const body = joinCode(sections, { on: "\n" }).toString();
   const header =
     `// ${GENERATED_HEADER} — DO NOT EDIT.\n` +

package/src/reference/routes.ts

@@ -40,7 +40,8 @@ export const routesFile = function routesFile(opts?: RoutesFileOpts): Generator
     // per-entity opt-out via `@emitRoutes: false`; TPH subtypes get no standalone routes
     // file (their routes live in the discriminator base's); AND-composed with your filter.
     filter: (e: MetaObject) =>
-      e.ownAttr(CODEGEN_ATTR_EMIT_ROUTES) !== false && !isTphSubtype(e) && userFilter(e),
+      // ADR-0039: resolving — a concrete entity may inherit its @emit* opt-out flag via extends.
+      e.attr(CODEGEN_ATTR_EMIT_ROUTES) !== false && !isTphSubtype(e) && userFilter(e),
     generate: perEntity(async (entity, ctx) => {
       if (!ctx.renderContext) {
         throw new Error("routes-file: renderContext is required (provided by runGen)");

package/src/relation-resolver.ts

@@ -69,12 +69,14 @@ export function buildRelationMap(root: MetaRoot): RelationMap {
     if (isProjection(obj)) continue;
 
     for (const child of obj.relationships()) {
-      const cardinality = child.ownAttr(RELATIONSHIP_ATTR_CARDINALITY) as string | undefined;
+      // ADR-0039: resolving — a relationship may inherit @cardinality via extends.
+      const cardinality = child.attr(RELATIONSHIP_ATTR_CARDINALITY) as string | undefined;
 
       // FR-018 M:N: `@cardinality: "many"` + `@through` — derive the junction FK
       // columns from the junction's identity.reference children and register a
       // many(junction) navigation on the source.
-      if (cardinality === CARDINALITY_MANY && child.ownAttr(RELATIONSHIP_ATTR_THROUGH) !== undefined) {
+      // ADR-0039: resolving — @through may be inherited via extends.
+      if (cardinality === CARDINALITY_MANY && child.attr(RELATIONSHIP_ATTR_THROUGH) !== undefined) {
         const m2m = buildM2mEntry(obj, child as MetaRelationship, root);
         if (m2m) ensure(obj.name).push(m2m);
         continue;
@@ -82,7 +84,8 @@ export function buildRelationMap(root: MetaRoot): RelationMap {
 
       if (cardinality !== CARDINALITY_ONE) continue;
 
-      const targetEntityRaw = child.ownAttr(RELATIONSHIP_ATTR_OBJECT_REF) as string | undefined;
+      // ADR-0039: resolving — @objectRef may be inherited via extends.
+      const targetEntityRaw = child.attr(RELATIONSHIP_ATTR_OBJECT_REF) as string | undefined;
       if (!targetEntityRaw) continue;
       const targetEntity = stripPackage(targetEntityRaw);
 
@@ -104,11 +107,14 @@ export function buildRelationMap(root: MetaRoot): RelationMap {
         fkField,
         targetPkField: "id",
       });
-      ensure(targetEntity).push({
-        name: variableNameFromEntity(obj.name),
-        cardinality: "many",
-        targetEntity: obj.name,
-      });
+      // ADR-0038: do NOT register a reverse lazy `many()` on the target. Those
+      // entries were named after the SOURCE entity (`variableNameFromEntity(obj)`),
+      // so two relationships from the same source to the same target produced
+      // duplicate object-literal keys and silently overwrote each other (the
+      // same-pair collision). Reverse 1:N navigation is now provided as explicit,
+      // unique-by-FK-field finders in the source's queries module
+      // (find<SourcePlural>By<FkField>), which are framework-free and non-N+1.
+      // The forward one() relation above stays.
     }
   }
 
@@ -149,8 +155,9 @@ function collectJunctionNames(root: MetaRoot): Set<string> {
   const names = new Set<string>();
   for (const obj of root.objects()) {
     for (const rel of obj.relationships()) {
-      if (rel.ownAttr(RELATIONSHIP_ATTR_CARDINALITY) !== CARDINALITY_MANY) continue;
-      const through = rel.ownAttr(RELATIONSHIP_ATTR_THROUGH) as string | undefined;
+      // ADR-0039: resolving — @cardinality/@through may be inherited via extends.
+      if (rel.attr(RELATIONSHIP_ATTR_CARDINALITY) !== CARDINALITY_MANY) continue;
+      const through = rel.attr(RELATIONSHIP_ATTR_THROUGH) as string | undefined;
       if (through) names.add(stripPackage(through));
     }
   }
@@ -168,8 +175,9 @@ function buildM2mEntry(
   rel: MetaRelationship,
   root: MetaRoot,
 ): RelationEntry | null {
-  const targetRaw = rel.ownAttr(RELATIONSHIP_ATTR_OBJECT_REF) as string | undefined;
-  const throughRaw = rel.ownAttr(RELATIONSHIP_ATTR_THROUGH) as string | undefined;
+  // ADR-0039: resolving — @objectRef/@through may be inherited via extends.
+  const targetRaw = rel.attr(RELATIONSHIP_ATTR_OBJECT_REF) as string | undefined;
+  const throughRaw = rel.attr(RELATIONSHIP_ATTR_THROUGH) as string | undefined;
   if (!targetRaw || !throughRaw) return null;
   let fields;
   try {

package/src/source-detect.ts

@@ -18,7 +18,10 @@ import type { MetaObject } from "@metaobjectsdev/metadata";
  * transit data — no migration, no ORM table to point at.
  */
 export function hasWritableRdbSource(entity: MetaObject): boolean {
-  for (const child of entity.ownChildren()) {
+  // ADR-0039: resolving — an entity may inherit its writable source.rdb via extends
+  // (the JVM port's "entity inheriting its source emitted NOTHING" bug); own-only
+  // would suppress the Drizzle table for such an entity.
+  for (const child of entity.children()) {
     if (child.type !== TYPE_SOURCE) continue;
     if (child.subType !== SOURCE_SUBTYPE_RDB) continue;
     if (!(child instanceof MetaSource)) continue;

package/src/template-codegen/template-data.ts

@@ -41,7 +41,7 @@ function fieldData(field: MetaField): FieldTemplateData {
     name: field.name,
     type: field.subType,
     required: field.isRequired,
-    isArray: field.isArray === true,
+    isArray: field.resolvedIsArray(),
   };
   if (typeof field.maxLength === "number") d.maxLength = field.maxLength;
   if (field.subType === FIELD_SUBTYPE_ENUM) {

package/src/templates/callable-file.ts

@@ -44,7 +44,8 @@ export function isCallableEntity(entity: MetaObject): boolean {
 }
 
 function callableSource(entity: MetaObject): MetaSource | undefined {
-  for (const child of entity.ownChildren()) {
+  // ADR-0039: resolving — an entity may inherit its callable source.rdb via extends.
+  for (const child of entity.children()) {
     if (child.type !== TYPE_SOURCE) continue;
     if (!(child instanceof MetaSource)) continue;
     if (CALLABLE_KINDS.has(child.effectiveKind)) return child;
@@ -63,14 +64,16 @@ export function renderCallableFile(entity: MetaObject): string {
   }
 
   const procName = source.physicalName;
-  const argsRef = source.ownAttr(SOURCE_ATTR_PARAMETER_REF);
+  // ADR-0039: resolving — a source may inherit @parameterRef via extends.
+  const argsRef = source.attr(SOURCE_ATTR_PARAMETER_REF);
   const argsObjectName = typeof argsRef === "string" && argsRef !== "" ? argsRef : undefined;
 
   // Resolve the parameter value-object (when set) — same root as the entity.
   const root = entity.root();
+  // ADR-0039: resolving — root has no super (children()==ownChildren()).
   const argsObject =
     argsObjectName !== undefined
-      ? (root.ownChildren().find(
+      ? (root.children().find(
           (c) =>
             c.subType === OBJECT_SUBTYPE_VALUE && c.name === argsObjectName,
         ) as MetaObject | undefined)
@@ -78,8 +81,9 @@ export function renderCallableFile(entity: MetaObject): string {
 
   // Build the parameter list for the SQL call site. Declaration order = arg
   // order. Empty when argsObject is undefined (zero-arg proc).
+  // ADR-0039: resolving — a value object may inherit fields via extends (shape reuse).
   const paramFieldNames: string[] = argsObject
-    ? argsObject.ownChildren()
+    ? argsObject.children()
         .filter((c) => c.type === TYPE_FIELD)
         .map((f) => f.name)
     : [];

package/src/templates/entity-constants.ts

@@ -68,7 +68,8 @@ function humanize(s: string): string {
  *   "WorkoutEvent" → "/workout_events"
  */
 export function resourcePath(entity: MetaData): string {
-  const overrideAttr = entity.ownAttr("routePath");
+  // ADR-0039: resolving — a concrete entity may inherit @routePath via extends.
+  const overrideAttr = entity.attr("routePath");
   if (typeof overrideAttr === "string" && overrideAttr.length > 0) {
     return overrideAttr.startsWith("/") ? overrideAttr : `/${overrideAttr}`;
   }
@@ -130,27 +131,29 @@ function renderFieldRules(field: MetaField): string | undefined {
   let hasRequired = false;
   let hasMaxLength = false;
 
+  // ADR-0039: resolving — a validator may inherit its config attrs (@min/@max/
+  // @pattern/@message/…) via extends.
   for (const child of field.validators()) {
     if (child.subType === VALIDATOR_SUBTYPE_REQUIRED) {
-      const msg = (child.ownAttr("message") as string | undefined) ?? `${humanize(field.name)} is required`;
+      const msg = (child.attr("message") as string | undefined) ?? `${humanize(field.name)} is required`;
       ruleParts.push(`required: ${JSON.stringify(msg)}`);
       hasRequired = true;
     } else if (child.subType === VALIDATOR_SUBTYPE_LENGTH) {
-      const min = child.ownAttr(VALIDATOR_ATTR_MIN);
-      const max = child.ownAttr(VALIDATOR_ATTR_MAX);
+      const min = child.attr(VALIDATOR_ATTR_MIN);
+      const max = child.attr(VALIDATOR_ATTR_MAX);
       if (typeof min === "number") {
-        const msg = (child.ownAttr("minMessage") as string | undefined) ?? `Must be at least ${min} characters`;
+        const msg = (child.attr("minMessage") as string | undefined) ?? `Must be at least ${min} characters`;
         ruleParts.push(`minLength: { value: ${min}, message: ${JSON.stringify(msg)} }`);
       }
       if (typeof max === "number") {
-        const msg = (child.ownAttr("maxMessage") as string | undefined) ?? `Must be ${max} characters or fewer`;
+        const msg = (child.attr("maxMessage") as string | undefined) ?? `Must be ${max} characters or fewer`;
         ruleParts.push(`maxLength: { value: ${max}, message: ${JSON.stringify(msg)} }`);
         hasMaxLength = true;
       }
     } else if (child.subType === VALIDATOR_SUBTYPE_REGEX) {
-      const pattern = child.ownAttr(VALIDATOR_ATTR_PATTERN);
+      const pattern = child.attr(VALIDATOR_ATTR_PATTERN);
       if (typeof pattern === "string") {
-        const msg = (child.ownAttr("message") as string | undefined) ?? "Invalid format";
+        const msg = (child.attr("message") as string | undefined) ?? "Invalid format";
         // Emit as RegExp literal /.../ — `as const` preserves the value-ref.
         // Forward-slash inside the pattern is escaped so the literal closes correctly.
         const safe = pattern.replace(/\\/g, "\\\\").replace(/\//g, "\\/");
@@ -180,9 +183,10 @@ function renderFieldRules(field: MetaField): string | undefined {
 function renderFieldEntry(field: MetaField): string {
   const { view, viewNode } = resolveView(field);
   const label = labelFor(field);
-  const placeholder = viewNode?.ownAttr("placeholder") as string | undefined;
-  const helpText = viewNode?.ownAttr("helpText") as string | undefined;
-  const htmlType = htmlTypeFromView(view, viewNode?.ownAttr("htmlType") as string | undefined);
+  // ADR-0039: resolving — a view node may inherit @placeholder/@helpText/@htmlType via extends.
+  const placeholder = viewNode?.attr("placeholder") as string | undefined;
+  const helpText = viewNode?.attr("helpText") as string | undefined;
+  const htmlType = htmlTypeFromView(view, viewNode?.attr("htmlType") as string | undefined);
   const rules = renderFieldRules(field);
 
   const entries: string[] = [

package/src/templates/entity-file.ts

@@ -11,7 +11,7 @@ import type { MetaObject } from "@metaobjectsdev/metadata";
 import type { RenderContext } from "../render-context.js";
 import { renderDrizzleSchema } from "./drizzle-schema.js";
 import { renderInferredTypes, renderEnumTypeAliases } from "./inferred-types.js";
-import { renderZodValidators } from "./zod-validators.js";
+import { renderZodValidators, isTphSubtype } from "./zod-validators.js";
 import { renderEntityConstants } from "./entity-constants.js";
 import { renderFilterAllowlist, renderSortAllowlist } from "./filter-allowlist.js";
 import { renderFilterType } from "./filter-type.js";
@@ -88,7 +88,12 @@ export function renderEntityFile(
   // shape) OR the target is contract-only (a UI/wire package gets the read shape,
   // not a DB table). Either way: interface + Zod, no migration footprint, no
   // drizzle-orm. Consumers validate via the Zod schema and type via the interface.
-  if (!runtime || !hasWritableRdbSource(entity)) {
+  //
+  // A TPH subtype (FR-017) also routes here: it inherits the base's writable
+  // source.rdb via extends (so hasWritableRdbSource is now true under the ADR-0039
+  // resolving read), but the base owns the single shared table — the subtype must
+  // emit its per-subtype read schema (<Sub>Schema), never its own pgTable.
+  if (!runtime || !hasWritableRdbSource(entity) || isTphSubtype(entity)) {
     return renderValueObjectFile(entity, ctx.apiPrefix, ctx);
   }
 

package/src/templates/extract-delegate-emitter.ts

@@ -31,8 +31,9 @@ import {
 } from "@metaobjectsdev/metadata";
 import { fields, isArray, scalarKind, jsonStringLiteral } from "./fr010-field-mapping.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));
 }
 
 /** The @objectRef target VO for a nested-object field, or undefined when unresolvable. */

package/src/templates/extractor.ts

@@ -40,12 +40,14 @@ import { mirrorName } from "./extract-delegate-emitter.js";
 import { enumUnionAliasName } from "./inferred-types.js";
 import { enumValues } from "../enum-meta.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);
 }
 
 /** The @objectRef target VO for a nested-object field, or undefined when unresolvable. */
@@ -288,7 +290,8 @@ export function renderExtractor(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`);
   }
@@ -296,7 +299,8 @@ export function renderExtractor(root: MetaData, templateName: string): string {
   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();
+  // 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();
   if (format !== "json" && format !== "xml") {
     throw new Error(
       `template "${templateName}" @format "${format}" has no extract API to extract over (json/xml only)`,

package/src/templates/field-meta.ts

@@ -18,6 +18,11 @@ import {
   FIELD_SUBTYPE_CURRENCY,
   FIELD_SUBTYPE_ENUM,
   FIELD_SUBTYPE_UUID,
+  FIELD_SUBTYPE_URI,
+  FIELD_SUBTYPE_INET,
+  FIELD_ATTR_STRING_FORMAT,
+  STRING_FORMAT_EMAIL,
+  STRING_FORMAT_HOSTNAME,
   VIEW_SUBTYPE_TEXT,
   VIEW_SUBTYPE_DATE,
   VIEW_SUBTYPE_NUMBER,
@@ -76,9 +81,24 @@ function defaultViewForSubType(subType: string): string {
  */
 export function zodTypeFor(field: MetaField): string {
   switch (field.subType) {
-    case FIELD_SUBTYPE_STRING:
+    case FIELD_SUBTYPE_STRING: {
+      // ADR-0036/0037 Wave 3: @stringFormat narrows a plain string. Codegen owns
+      // the canonical matcher (mirrors zod-validators.ts).
+      const fmt = field.attr(FIELD_ATTR_STRING_FORMAT);
+      if (fmt === STRING_FORMAT_EMAIL) return "z.string().email()";
+      if (fmt === STRING_FORMAT_HOSTNAME) {
+        return "z.string().regex(/^(?=.{1,253}$)([a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/)";
+      }
+      return "z.string()";
+    }
     case FIELD_SUBTYPE_UUID:
       return "z.string()";
+    case FIELD_SUBTYPE_URI:
+      // ADR-0036/0037 Wave 3: a URI string — codegen owns the URL matcher.
+      return "z.string().url()";
+    case FIELD_SUBTYPE_INET:
+      // ADR-0036/0037 Wave 3: an IP string — codegen owns the IP matcher (v4+v6).
+      return "z.string().ip()";
     case FIELD_SUBTYPE_BOOLEAN:
       return "z.boolean()";
     case FIELD_SUBTYPE_DATE:
@@ -116,8 +136,9 @@ export function currencyMetaFor(field: MetaField): { currency: string; locale: s
   const currency =
     (field.attr(FIELD_ATTR_CURRENCY) as string | undefined) ?? FIELD_ATTR_CURRENCY_DEFAULT;
   const viewChild = field.views().find((c) => c.subType === VIEW_SUBTYPE_CURRENCY);
+  // ADR-0039: resolving — a view may inherit @locale via extends.
   const locale =
-    (viewChild?.ownAttr(VIEW_CURRENCY_ATTR_LOCALE) as string | undefined) ??
+    (viewChild?.attr(VIEW_CURRENCY_ATTR_LOCALE) as string | undefined) ??
     VIEW_CURRENCY_ATTR_LOCALE_DEFAULT;
   return { currency, locale };
 }
@@ -132,7 +153,8 @@ export function currencyMetaFor(field: MetaField): { currency: string; locale: s
  */
 export function labelFor(field: MetaField): string {
   for (const child of field.views()) {
-    const label = child.ownAttr("label");
+    // ADR-0039: resolving — a view may inherit @label via extends.
+    const label = child.attr("label");
     if (typeof label === "string" && label.length > 0) return label;
   }
   return humanize(field.name);

package/src/templates/find-templates.ts

@@ -5,6 +5,9 @@ import { TYPE_TEMPLATE } from "@metaobjectsdev/metadata";
 export function findTemplates(root: MetaData, subType: string): MetaData[] {
   const out: MetaData[] = [];
   const visit = (node: MetaData) => {
+    // ADR-0039: own — structural declaration walk. Enumerates every template node
+    // physically DECLARED in the tree exactly once (each → one emitted file);
+    // resolving would re-visit an inherited template on every subclass.
     for (const child of node.ownChildren()) {
       if (child.type === TYPE_TEMPLATE && child.subType === subType) out.push(child);
       visit(child);