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

package/src/column-mapper.ts

@@ -18,6 +18,8 @@ import {
   FIELD_SUBTYPE_MAP,
   FIELD_SUBTYPE_ENUM,
   FIELD_SUBTYPE_UUID,
+  FIELD_SUBTYPE_URI,
+  FIELD_SUBTYPE_INET,
   VALIDATOR_SUBTYPE_REQUIRED,
   VALIDATOR_SUBTYPE_LENGTH,
   FIELD_ATTR_MAX_LENGTH,
@@ -34,7 +36,7 @@ import {
   FIELD_ATTR_DB_COLUMN_TYPE,
   DB_COLUMN_TYPE_UUID,
   DB_COLUMN_TYPE_JSONB,
-  DB_COLUMN_TYPE_TIMESTAMP_WITH_TZ,
+  FIELD_ATTR_LOCAL_TIME,
 } from "@metaobjectsdev/metadata";
 import { columnNameFromField } from "./naming.js";
 import { enumValues } from "./enum-meta.js";
@@ -160,19 +162,22 @@ export interface ColumnSpec {
  * migrate-ts/src/expected-schema.ts (override checked first, wins over the
  * subtype default), so codegen and DDL agree.
  *
- * Postgres-only: uuid/jsonb/timestamptz are Postgres physical column types with
- * no native SQLite analogue, so on SQLite the attribute is ignored (the caller
- * falls through to the subtype default). The native TS binding is keyed on
+ * Postgres-only: uuid/jsonb are Postgres physical column types with no native
+ * SQLite analogue, so on SQLite the attribute is ignored (the caller falls
+ * through to the subtype default). The native TS binding is keyed on
  * field.subType elsewhere and is unaffected — a `field.string @dbColumnType:uuid`
  * field stays a TS `string`; only the Drizzle column function changes.
  *
+ * ADR-0036 Wave 2: the `timestamp_with_tz` value is retired — `field.timestamp`
+ * is now instant/tz-aware BY DEFAULT (handled in the subtype switch below), and
+ * the naive opt-out is the `@localTime` boolean, not a physical override.
+ *
  * The loader has already validated the (subtype × value) pairing, so an
  * unrecognized value never reaches here; an unknown value returns undefined
  * (fall through to subtype default).
  */
 function pgColumnTypeOverride(
   field: MetaField,
-  timestampMode: "date" | "string" = "string",
 ): { fnName: string; fnOptions?: Record<string, unknown> } | undefined {
   const dbColumnType = field.attr(FIELD_ATTR_DB_COLUMN_TYPE);
   if (typeof dbColumnType !== "string") return undefined;
@@ -181,12 +186,6 @@ function pgColumnTypeOverride(
       return { fnName: "uuid" };
     case DB_COLUMN_TYPE_JSONB:
       return { fnName: "jsonb" };
-    case DB_COLUMN_TYPE_TIMESTAMP_WITH_TZ:
-      // Drizzle pg-core: timestamp(col, { withTimezone: true }) → timestamptz.
-      // mode defaults to "string" (ISO-8601 wire contract, matching the generated
-      // Zod); a consumer can opt into "date" (drizzle's native mode) via
-      // codegen.timestampMode when its hand-written code works with JS Dates.
-      return { fnName: "timestamp", fnOptions: { mode: timestampMode, withTimezone: true } };
     default:
       return undefined;
   }
@@ -199,7 +198,8 @@ function getMaxLength(field: MetaField): number | undefined {
   if (typeof lenAttr === "number") return lenAttr;
   for (const child of field.validators()) {
     if (child.subType === VALIDATOR_SUBTYPE_LENGTH) {
-      const max = child.ownAttr(VALIDATOR_ATTR_MAX);
+      // ADR-0039: resolving — a validator may inherit @max via extends.
+      const max = child.attr(VALIDATOR_ATTR_MAX);
       if (typeof max === "number") return max;
     }
   }
@@ -231,7 +231,7 @@ export function mapColumnType(
   const dbName = field.column ?? columnNameFromField(field.name, strategy);
   const importModule = dialect === "sqlite" ? "drizzle-orm/sqlite-core" : "drizzle-orm/pg-core";
   const subType = field.subType;
-  const isArray = field.isArray;
+  const isArray = field.resolvedIsArray();
 
   let fnName: string;
   let fnOptions: Record<string, unknown> | undefined;
@@ -279,7 +279,9 @@ export function mapColumnType(
         case FIELD_SUBTYPE_STRING:
         case FIELD_SUBTYPE_ENUM:
         case FIELD_SUBTYPE_UUID:
-          // SQLite has no native uuid type; store as TEXT (string native binding).
+        case FIELD_SUBTYPE_URI:
+        case FIELD_SUBTYPE_INET:
+          // SQLite has no native uuid/inet type; store as TEXT (string native binding).
           fnName = "text";
           break;
         default:
@@ -291,7 +293,7 @@ export function mapColumnType(
     // A physical @dbColumnType override wins over the subtype default (Postgres
     // only; SQLite has no native analogue and falls through above). Resolved
     // first so the override-precedence matches migrate-ts's expected-schema.
-    const override = pgColumnTypeOverride(field, timestampMode);
+    const override = pgColumnTypeOverride(field);
     if (override !== undefined) {
       // Override fully determines the physical type; skip the subtype switch.
       fnName = override.fnName;
@@ -322,6 +324,11 @@ export function mapColumnType(
           fnName = "time";
           break;
         case FIELD_SUBTYPE_TIMESTAMP:
+          // ADR-0036 Wave 2: field.timestamp is instant / tz-aware BY DEFAULT →
+          // timestamp({ withTimezone: true }) = timestamptz. A naive wall-clock
+          // value opts out with @localTime:true → timestamp({ withTimezone:
+          // false }) = `timestamp without time zone`.
+          //
           // mode:"string" so the column round-trips ISO-8601 strings — the
           // generated Zod schema validates timestamp fields as z.string() and
           // the cross-port wire format carries timestamps as JSON strings.
@@ -330,12 +337,26 @@ export function mapColumnType(
           // inconsistent with the string-typed schema + wire contract and
           // throws on a string write. See SP-B api-contract-generated lane.
           fnName = "timestamp";
-          fnOptions = { mode: timestampMode };
+          fnOptions = {
+            mode: timestampMode,
+            withTimezone: field.attr(FIELD_ATTR_LOCAL_TIME) !== true,
+          };
           break;
         case FIELD_SUBTYPE_UUID:
           // Postgres native uuid column; native TS binding stays `string`.
           fnName = "uuid";
           break;
+        case FIELD_SUBTYPE_URI:
+          // ADR-0036/0037 Wave 3: Postgres has no uri type → text. Native TS
+          // binding stays `string` (validated as a URL via Zod .url()).
+          fnName = "text";
+          break;
+        case FIELD_SUBTYPE_INET:
+          // ADR-0036/0037 Wave 3: Postgres-native `inet` column (Drizzle's
+          // pg-core `inet()` infers as `string`). Native TS binding stays
+          // `string` (validated as an IP via Zod .ip()).
+          fnName = "inet";
+          break;
         case FIELD_SUBTYPE_DECIMAL: {
           // Drizzle pg `numeric` infers as a TS `string` (precision-exact); the
           // native TS binding for field.decimal is `string` to match. Read the

package/src/generators/api-model.ts

@@ -41,7 +41,7 @@
 //                        render handle promptRender() emits into a single
 //                        aggregated `prompts.ts` (payload-codegen generateRenderHandle).
 //                        ONLY for TOP-LEVEL template.prompt nodes (matching
-//                        prompt-render-file.ts's `ctx.loadedRoot.ownChildren()`).
+//                        prompt-render-file.ts's top-level template collection).
 //
 // DEFERRALS (tracked follow-ups — NOT documented by this builder yet, stated here
 // so the gap is known + intentional):
@@ -353,7 +353,8 @@ function isQueryable(obj: MetaObject): boolean {
  *  generators which always emit. So REST symbols are gated separately from the
  *  other queryable kinds. */
 function emitsRoutes(obj: MetaObject): boolean {
-  return obj.ownAttr(CODEGEN_ATTR_EMIT_ROUTES) !== false;
+  // ADR-0039: resolving — a concrete entity may inherit @emitRoutes via extends.
+  return obj.attr(CODEGEN_ATTR_EMIT_ROUTES) !== false;
 }
 
 function buildEntityUnit(
@@ -750,13 +751,16 @@ function callableSymbol(
  *  undefined for a zero-arg proc. Mirrors the callable template's resolution
  *  (the source child's SOURCE_ATTR_PARAMETER_REF). */
 function callableArgsRef(obj: MetaObject, root: MetaRoot): string | undefined {
-  for (const child of obj.ownChildren()) {
+  // ADR-0039: resolving — a callable entity's source (and its @parameterRef) may
+  // be inherited via extends.
+  for (const child of obj.children()) {
     if (child.type !== TYPE_SOURCE) continue;
-    const ref = child.ownAttr(SOURCE_ATTR_PARAMETER_REF);
+    const ref = child.attr(SOURCE_ATTR_PARAMETER_REF);
     if (typeof ref === "string" && ref !== "") {
       // Only count it when it resolves to a value object (the template's guard).
+      // ADR-0039: resolving — root has no super (children()==ownChildren()).
       const vo = root
-        .ownChildren()
+        .children()
         .find((c) => c.subType === OBJECT_SUBTYPE_VALUE && refMatchesObject(c, ref));
       if (vo !== undefined) return ref;
     }
@@ -806,8 +810,9 @@ function restHonoSymbols(obj: MetaObject, layout: OutputLayout): ApiSymbol[] {
 // ---------------------------------------------------------------------------
 
 function templateOutputs(root: MetaRoot): MetaData[] {
+  // ADR-0039: resolving — root has no super (children()==ownChildren()).
   return root
-    .ownChildren()
+    .children()
     .filter((c) => c.type === TYPE_TEMPLATE && c.subType === TEMPLATE_SUBTYPE_OUTPUT);
 }
 
@@ -819,10 +824,11 @@ function buildTemplateUnit(tmpl: MetaData, root: MetaRoot, _layout: OutputLayout
   const extractorMod = templateModulePath(`${name}.extractor`);
   const renderMod = templateModulePath(`${name}.render`);
 
-  const payloadRef = tmpl.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
+  // ADR-0039: resolving — a template may inherit @payloadRef/@format/@kind via extends.
+  const payloadRef = tmpl.attr(TEMPLATE_ATTR_PAYLOAD_REF);
   const payload = typeof payloadRef === "string" ? payloadRef : undefined;
-  const format = ((tmpl.ownAttr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text").toLowerCase();
-  const kind = ((tmpl.ownAttr(TEMPLATE_ATTR_KIND) as string | undefined) ?? TEMPLATE_KIND_DEFAULT).toLowerCase();
+  const format = ((tmpl.attr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text").toLowerCase();
+  const kind = ((tmpl.attr(TEMPLATE_ATTR_KIND) as string | undefined) ?? TEMPLATE_KIND_DEFAULT).toLowerCase();
 
   // --- extractor: only json/xml output-parsers expose the extract API (matches
   //     extractor-file.ts's `if (format !== "json" && format !== "xml") continue`). ---
@@ -893,13 +899,14 @@ function buildTemplateUnit(tmpl: MetaData, root: MetaRoot, _layout: OutputLayout
 // template.prompt nodes — the prompt-render handle.
 // ---------------------------------------------------------------------------
 
-/** TOP-LEVEL template.prompt nodes — matching the promptRender generator's own
- *  collection (`ctx.loadedRoot.ownChildren()` filtered to TYPE_TEMPLATE +
+/** TOP-LEVEL template.prompt nodes — matching the promptRender generator's
+ *  top-level collection (root children filtered to TYPE_TEMPLATE +
  *  TEMPLATE_SUBTYPE_PROMPT). A prompt nested INSIDE an entity is not collected by
  *  the generator, so the builder must not document it either (no over-doc). */
 function templatePrompts(root: MetaRoot): MetaData[] {
+  // ADR-0039: resolving — root has no super (children()==ownChildren()).
   return root
-    .ownChildren()
+    .children()
     .filter((c) => c.type === TYPE_TEMPLATE && c.subType === TEMPLATE_SUBTYPE_PROMPT);
 }
 
@@ -919,7 +926,8 @@ function buildPromptUnit(tmpl: MetaData, root: MetaRoot): ApiUnitDoc {
   // promptRender writes the aggregated handles to `outFile` (default "prompts.ts").
   const promptsMod = templateModulePath("prompts");
 
-  const payloadRef = tmpl.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
+  // ADR-0039: resolving — a template may inherit @payloadRef via extends.
+  const payloadRef = tmpl.attr(TEMPLATE_ATTR_PAYLOAD_REF);
   const payload = typeof payloadRef === "string" ? payloadRef : undefined;
 
   if (payload) {

package/src/generators/docs-data-builder.ts

@@ -108,20 +108,21 @@ function collectValidatorParts(field: MetaField): ValidatorParts {
   const regexParts: string[] = [];
   const lengthParts: string[] = [];
   const numericParts: string[] = [];
+  // ADR-0039: resolving — a validator may inherit @min/@max/@pattern via extends.
   for (const v of field.validators()) {
     if (v.subType === VALIDATOR_SUBTYPE_REGEX) {
-      const pattern = v.ownAttr(VALIDATOR_ATTR_PATTERN);
+      const pattern = v.attr(VALIDATOR_ATTR_PATTERN);
       if (typeof pattern === "string" && pattern.length > 0) {
         regexParts.push(`pattern \`${pattern}\``);
       }
     } else if (v.subType === VALIDATOR_SUBTYPE_LENGTH) {
-      const min = v.ownAttr(VALIDATOR_ATTR_MIN);
-      const max = v.ownAttr(VALIDATOR_ATTR_MAX);
+      const min = v.attr(VALIDATOR_ATTR_MIN);
+      const max = v.attr(VALIDATOR_ATTR_MAX);
       if (typeof min === "number") lengthParts.push(`minLength: ${min}`);
       if (typeof max === "number" && typeof maxLenAttr !== "number") lengthParts.push(`maxLength: ${max}`);
     } else if (v.subType === VALIDATOR_SUBTYPE_NUMERIC) {
-      const min = v.ownAttr(VALIDATOR_ATTR_MIN);
-      const max = v.ownAttr(VALIDATOR_ATTR_MAX);
+      const min = v.attr(VALIDATOR_ATTR_MIN);
+      const max = v.attr(VALIDATOR_ATTR_MAX);
       if (typeof min === "number") numericParts.push(`min: ${min}`);
       if (typeof max === "number") numericParts.push(`max: ${max}`);
     }
@@ -148,7 +149,7 @@ export function neutralTypeStr(field: MetaField): string {
   } else {
     base = field.subType;
   }
-  if (field.isArray) base = `${base}[]`;
+  if (field.resolvedIsArray()) base = `${base}[]`;
   return base;
 }
 
@@ -160,7 +161,7 @@ function neutralTypeCell(field: MetaField): string {
 
 /** Neutral PHYSICAL type cell for the Storage table. Metadata-driven, no DDL
  *  re-derivation (ADR-0020): if the field declares a `@dbColumnType` physical
- *  override (e.g. `uuid`, `jsonb`, `timestamp_with_tz`) show it UPPERCASED;
+ *  override (e.g. `uuid`, `jsonb`) show it UPPERCASED;
  *  otherwise fall back to the same neutral LOGICAL type the Constraints table
  *  uses. Deliberately does NOT derive ANSI/ORM SQL so it can't drift vs the
  *  migrate engine or re-introduce language-specific DDL. Wrapped in backticks. */
@@ -192,7 +193,7 @@ function buildConstraintRow(
   if (isPk) rules.push("primary key");
   if (field.attr(FIELD_ATTR_UNIQUE) === true) rules.push("unique");
 
-  if (field.subType === FIELD_SUBTYPE_ENUM && !field.isArray) {
+  if (field.subType === FIELD_SUBTYPE_ENUM && !field.resolvedIsArray()) {
     const values = enumValues(field);
     if (values !== undefined && values.length > 0) {
       const list = values.map((v) => `\`${v}\``).join(", ");
@@ -289,7 +290,7 @@ function buildFieldRow(
   const rules: string[] = [];
   if (field.attr(FIELD_ATTR_UNIQUE) === true) rules.push("unique");
 
-  if (field.subType === FIELD_SUBTYPE_ENUM && !field.isArray) {
+  if (field.subType === FIELD_SUBTYPE_ENUM && !field.resolvedIsArray()) {
     const values = enumValues(field);
     if (values !== undefined && values.length > 0) {
       const list = values.map((v) => `\`${v}\``).join(", ");
@@ -344,7 +345,7 @@ function buildFieldDetail(
   const columnName = field.column;
   const dbColumnType = field.attr(FIELD_ATTR_DB_COLUMN_TYPE);
   const isUnique = field.attr(FIELD_ATTR_UNIQUE) === true;
-  const isEnum = field.subType === FIELD_SUBTYPE_ENUM && !field.isArray;
+  const isEnum = field.subType === FIELD_SUBTYPE_ENUM && !field.resolvedIsArray();
   const enumVals = isEnum ? enumValues(field) : undefined;
   const validators = field.validators();
   const hasValidatorChildren = validators.some(
@@ -423,22 +424,23 @@ function buildFieldDetail(
   // Validators — one bullet per validator subtype (regex / length / numeric),
   // rendered in declaration order so authors can rely on the order they
   // wrote.
+  // ADR-0039: resolving — a validator may inherit @min/@max/@pattern via extends.
   for (const v of validators) {
     if (v.subType === VALIDATOR_SUBTYPE_REGEX) {
-      const pattern = v.ownAttr(VALIDATOR_ATTR_PATTERN);
+      const pattern = v.attr(VALIDATOR_ATTR_PATTERN);
       if (typeof pattern === "string" && pattern.length > 0) {
         bullets.push(`**Validator (regex):** pattern \`${pattern}\``);
       }
     } else if (v.subType === VALIDATOR_SUBTYPE_LENGTH) {
-      const min = v.ownAttr(VALIDATOR_ATTR_MIN);
-      const max = v.ownAttr(VALIDATOR_ATTR_MAX);
+      const min = v.attr(VALIDATOR_ATTR_MIN);
+      const max = v.attr(VALIDATOR_ATTR_MAX);
       const fragments: string[] = [];
       if (typeof min === "number") fragments.push(`min ${min}`);
       if (typeof max === "number") fragments.push(`max ${max}`);
       if (fragments.length > 0) bullets.push(`**Validator (length):** ${fragments.join(", ")}`);
     } else if (v.subType === VALIDATOR_SUBTYPE_NUMERIC) {
-      const min = v.ownAttr(VALIDATOR_ATTR_MIN);
-      const max = v.ownAttr(VALIDATOR_ATTR_MAX);
+      const min = v.attr(VALIDATOR_ATTR_MIN);
+      const max = v.attr(VALIDATOR_ATTR_MAX);
       const fragments: string[] = [];
       if (typeof min === "number") fragments.push(`min ${min}`);
       if (typeof max === "number") fragments.push(`max ${max}`);
@@ -524,9 +526,10 @@ function describeIdentity(id: MetaIdentity): string {
 }
 
 function relationshipBullet(r: ReturnType<MetaObject["relationships"]>[number]): string {
-  const cardinality = r.ownAttr(RELATIONSHIP_ATTR_CARDINALITY);
+  // ADR-0039: resolving — a relationship may inherit its attrs via extends.
+  const cardinality = r.attr(RELATIONSHIP_ATTR_CARDINALITY);
   const card = typeof cardinality === "string" ? cardinality : "?";
-  const targetRaw = r.ownAttr(RELATIONSHIP_ATTR_OBJECT_REF);
+  const targetRaw = r.attr(RELATIONSHIP_ATTR_OBJECT_REF);
   const target = typeof targetRaw === "string" ? stripPackage(targetRaw) : "?";
   const subtype = r.subType;
   let label: string;
@@ -542,14 +545,14 @@ function relationshipBullet(r: ReturnType<MetaObject["relationships"]>[number]):
   //   symmetric (undirected) → "symmetric self-join"
   //   @sourceRefField set (directed) → "directed self-join via `<field>`"
   // The junction/disambiguator are DECLARED facts (ADR-0020 — no re-derivation).
-  const throughRaw = r.ownAttr(RELATIONSHIP_ATTR_THROUGH);
+  const throughRaw = r.attr(RELATIONSHIP_ATTR_THROUGH);
   if (typeof throughRaw === "string" && throughRaw.length > 0) {
     const through = stripPackage(throughRaw);
     const noteParts = [`${label}, through \`${through}\``];
-    if (r.ownAttr(RELATIONSHIP_ATTR_SYMMETRIC) === true) {
+    if (r.attr(RELATIONSHIP_ATTR_SYMMETRIC) === true) {
       noteParts.push("symmetric self-join");
     } else {
-      const srcRef = r.ownAttr(RELATIONSHIP_ATTR_SOURCE_REF_FIELD);
+      const srcRef = r.attr(RELATIONSHIP_ATTR_SOURCE_REF_FIELD);
       if (typeof srcRef === "string" && srcRef.length > 0) {
         noteParts.push(`directed self-join via \`${srcRef}\``);
       }
@@ -664,9 +667,11 @@ export function buildEntityDocData(
 
   // ---- UsedBy
   const usedByMatches: UsedByDoc[] = [];
-  for (const child of root.ownChildren()) {
+  // ADR-0039: resolving — root has no super (children()==ownChildren()), and a
+  // template may inherit @payloadRef via extends; resolve rather than work-by-accident.
+  for (const child of root.children()) {
     if (child.type !== TYPE_TEMPLATE) continue;
-    const ref = child.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
+    const ref = child.attr(TEMPLATE_ATTR_PAYLOAD_REF);
     if (typeof ref !== "string") continue;
     if (stripPackage(ref) !== entity.name) continue;
     // Link to the template's own doc page. The href is derived from the SAME

package/src/generators/docs-file.ts

@@ -135,7 +135,8 @@ export const docsFile = function docsFile(opts?: DocsFileOpts): Generator {
       // ALSO emit one NEUTRAL render-contract page per `template.output` node —
       // a sibling artifact, distinct from the entity page. Raw node name → file
       // (`<name>.md`), agreeing with the entity Used-by back-link target.
-      for (const child of ctx.loadedRoot.ownChildren()) {
+      // ADR-0039: resolving — root has no super (children()==ownChildren()).
+      for (const child of ctx.loadedRoot.children()) {
         if (child.type !== TYPE_TEMPLATE || child.subType !== TEMPLATE_SUBTYPE_OUTPUT) continue;
         const node = docPageNode(child);
         templateNodes.push(node);

package/src/generators/extractor-file.ts

@@ -35,13 +35,15 @@ export const extractor = function extractor(opts?: ExtractorOpts): Generator {
   const generator: Generator = {
     name: "extractor",
     generate: oncePerRun((_entities, ctx) => {
+      // ADR-0039: resolving — root has no super (children()==ownChildren()).
       const outputs = ctx.loadedRoot
-        .ownChildren()
+        .children()
         .filter((c) => c.type === TYPE_TEMPLATE && c.subType === TEMPLATE_SUBTYPE_OUTPUT);
       const files: EmittedFile[] = [];
       for (const t of outputs) {
         // The extract tier requires the extract API, which only json/xml output-parsers emit.
-        const format = ((t.ownAttr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text").toLowerCase();
+        // ADR-0039: resolving — a template may inherit @format via extends.
+        const format = ((t.attr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text").toLowerCase();
         if (format !== "json" && format !== "xml") continue;
         files.push({
           path: `${dirPrefix}${t.name}.extractor.ts`,

package/src/generators/output-prompt-file.ts

@@ -40,17 +40,19 @@ export const outputPrompt = function outputPrompt(opts?: OutputPromptOpts): Gene
     name: "output-prompt",
     generate: oncePerRun((_entities, ctx) => {
       const root = ctx.loadedRoot;
+      // ADR-0039: resolving — root has no super (children()==ownChildren()).
       const outputs = root
-        .ownChildren()
+        .children()
         .filter((c) => c.type === TYPE_TEMPLATE && c.subType === TEMPLATE_SUBTYPE_OUTPUT);
       const files: EmittedFile[] = [];
       for (const t of outputs) {
         // Only json/xml outputs get a renderable prompt fragment.
         if (!templateSupportsPrompt(t)) continue;
         // @payloadRef must resolve to a value-object (same contract as the parser).
-        const payloadRef = t.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
+        // ADR-0039: resolving — a template may inherit its @* refs/format/kind via extends.
+        const payloadRef = t.attr(TEMPLATE_ATTR_PAYLOAD_REF);
         if (typeof payloadRef !== "string") continue;
-        const vo = root.ownChildren().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, payloadRef));
+        const vo = root.children().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, payloadRef));
         if (!vo) continue;
         files.push({
           path: `${dirPrefix}${t.name}.prompt.ts`,

package/src/generators/render-helper-file.ts

@@ -48,15 +48,17 @@ export const renderHelper = function renderHelper(opts?: RenderHelperOpts): Gene
       // framework defaults; used to resolve + verify each referenced mustache so
       // the build-time drift gate runs against the same texts render() will see.
       const provider = projectProvider(ctx.projectRoot);
+      // ADR-0039: resolving — root has no super (children()==ownChildren()).
       const outputs = root
-        .ownChildren()
+        .children()
         .filter((c) => c.type === TYPE_TEMPLATE && c.subType === TEMPLATE_SUBTYPE_OUTPUT);
       const files: EmittedFile[] = [];
       for (const t of outputs) {
         // @payloadRef must resolve to a value-object (same contract as the parser).
-        const payloadRef = t.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
+        // ADR-0039: resolving — a template may inherit its @* refs/format/kind via extends.
+        const payloadRef = t.attr(TEMPLATE_ATTR_PAYLOAD_REF);
         if (typeof payloadRef !== "string") continue;
-        const vo = root.ownChildren().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, payloadRef));
+        const vo = root.children().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, payloadRef));
         if (!vo) continue;
         files.push({
           // renderRenderHelper THROWS (fails codegen) on a mustache↔VO drift —

package/src/generators/routes-file-hono.ts

@@ -30,7 +30,8 @@ export const routesFileHono = function routesFileHono(opts?: RoutesFileHonoOpts)
     // Marks this as the Hono routes generator so the runner can aggregate
     // `ctx.config.includeHonoRoutes` and api-docs auto-documents the Hono surface.
     emitsHonoRoutes: true,
-    filter: (e: MetaObject) => e.ownAttr(CODEGEN_ATTR_EMIT_ROUTES) !== false && userFilter(e),
+    // ADR-0039: resolving — a concrete entity may inherit @emitRoutes via extends.
+    filter: (e: MetaObject) => e.attr(CODEGEN_ATTR_EMIT_ROUTES) !== false && userFilter(e),
     generate: perEntity(async (entity, ctx) => {
       if (!ctx.renderContext) {
         throw new Error("routes-file-hono: renderContext is required (provided by runGen)");

package/src/generators/routes-file.ts

@@ -24,7 +24,8 @@ export const routesFile = function routesFile(opts?: RoutesFileOpts): Generator
     name: "routes-file",
     // Always set: AND-composes metadata opt-out with optional user 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/generators/template-doc-builder.ts

@@ -107,28 +107,29 @@ export function buildTemplateDocData(
 ): TemplateDocData {
   const layout = opts?.layout ?? "flat";
   const root = opts?.loadedRoot;
-  const kindRaw = ((template.ownAttr(TEMPLATE_ATTR_KIND) as string | undefined) ??
+  // ADR-0039: resolving — a template may inherit its @kind/@*Ref/@format/etc via extends.
+  const kindRaw = ((template.attr(TEMPLATE_ATTR_KIND) as string | undefined) ??
     TEMPLATE_KIND_DEFAULT).toLowerCase();
   const isEmail = kindRaw === TEMPLATE_KIND_EMAIL;
   const kind: "document" | "email" = isEmail ? TEMPLATE_KIND_EMAIL : TEMPLATE_KIND_DOCUMENT;
 
-  const payloadRefRaw = template.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
+  const payloadRefRaw = template.attr(TEMPLATE_ATTR_PAYLOAD_REF);
   const payloadName =
     typeof payloadRefRaw === "string" && payloadRefRaw.length > 0
       ? stripPackage(payloadRefRaw)
       : "unknown";
 
-  const requiredTags = attrStringList(template.ownAttr(TEMPLATE_ATTR_REQUIRED_TAGS));
-  const maxChars = readMaxChars(template.ownAttr(TEMPLATE_ATTR_MAX_CHARS));
+  const requiredTags = attrStringList(template.attr(TEMPLATE_ATTR_REQUIRED_TAGS));
+  const maxChars = readMaxChars(template.attr(TEMPLATE_ATTR_MAX_CHARS));
 
   let format = "";
   let parts: TemplateOutputPart[] | undefined;
   const sourceRefs: string[] = [];
 
   if (isEmail) {
-    const subjectRef = template.ownAttr(TEMPLATE_ATTR_SUBJECT_REF);
-    const htmlBodyRef = template.ownAttr(TEMPLATE_ATTR_HTML_BODY_REF);
-    const textBodyRef = template.ownAttr(TEMPLATE_ATTR_TEXT_BODY_REF);
+    const subjectRef = template.attr(TEMPLATE_ATTR_SUBJECT_REF);
+    const htmlBodyRef = template.attr(TEMPLATE_ATTR_HTML_BODY_REF);
+    const textBodyRef = template.attr(TEMPLATE_ATTR_TEXT_BODY_REF);
     parts = [];
     if (typeof subjectRef === "string") {
       parts.push({ label: "Subject", ref: subjectRef, format: "text", escaped: false });
@@ -143,8 +144,8 @@ export function buildTemplateDocData(
       sourceRefs.push(textBodyRef);
     }
   } else {
-    format = ((template.ownAttr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text").toLowerCase();
-    const textRef = template.ownAttr(TEMPLATE_ATTR_TEXT_REF);
+    format = ((template.attr(TEMPLATE_ATTR_FORMAT) as string | undefined) ?? "text").toLowerCase();
+    const textRef = template.attr(TEMPLATE_ATTR_TEXT_REF);
     if (typeof textRef === "string") sourceRefs.push(textRef);
   }
 
@@ -285,7 +286,8 @@ function makePartialHrefResolver(
 ): (ref: string) => string | undefined {
   // Map each documented source ref → the template node that documents it.
   const refToTemplate = new Map<string, MetaData>();
-  for (const child of root.ownChildren()) {
+  // ADR-0039: resolving — root has no super (children()==ownChildren()).
+  for (const child of root.children()) {
     if (child.type !== TYPE_TEMPLATE || child.subType !== TEMPLATE_SUBTYPE_OUTPUT) continue;
     for (const attr of [
       TEMPLATE_ATTR_TEXT_REF,
@@ -293,7 +295,8 @@ function makePartialHrefResolver(
       TEMPLATE_ATTR_HTML_BODY_REF,
       TEMPLATE_ATTR_TEXT_BODY_REF,
     ]) {
-      const v = child.ownAttr(attr);
+      // ADR-0039: resolving — a template may inherit these refs via extends.
+      const v = child.attr(attr);
       if (typeof v === "string" && v.length > 0 && !refToTemplate.has(v)) {
         refToTemplate.set(v, child);
       }

package/src/generators/trace-helper-file.ts

@@ -72,13 +72,17 @@ export const traceHelperFile = function traceHelperFile(opts?: TraceHelperOpts):
       if (!extendsBase(entity)) return [];
 
       // Find the nested template.prompt.
-      const prompt = entity.ownChildren().find(
+      // ADR-0039: resolving — a concrete trace entity may inherit its
+      // template.prompt from an abstract base (it extendsBase); own-only would
+      // miss the inherited prompt.
+      const prompt = entity.children().find(
         (c) => c.type === TYPE_TEMPLATE && c.subType === TEMPLATE_SUBTYPE_PROMPT,
       );
       if (prompt === undefined) return [];
 
-      const payloadRef = prompt.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
-      const responseRef = prompt.ownAttr(TEMPLATE_ATTR_RESPONSE_REF);
+      // ADR-0039: resolving — a prompt may inherit @payloadRef/@responseRef via extends.
+      const payloadRef = prompt.attr(TEMPLATE_ATTR_PAYLOAD_REF);
+      const responseRef = prompt.attr(TEMPLATE_ATTR_RESPONSE_REF);
 
       // @responseRef types the result; @payloadRef types the request. Both gate
       // the helper: the entity must declare voRequest/voResponse field.object
@@ -111,7 +115,8 @@ export const traceHelperFile = function traceHelperFile(opts?: TraceHelperOpts):
 
       // Derive the parse format from the prompt's @format attr.
       // "xml" → Format.XML; absent or any other value → Format.JSON.
-      const promptFormat = prompt.ownAttr(TEMPLATE_ATTR_FORMAT);
+      // ADR-0039: resolving — a prompt may inherit @format via extends.
+      const promptFormat = prompt.attr(TEMPLATE_ATTR_FORMAT);
       const formatLiteral = typeof promptFormat === "string" && promptFormat.toLowerCase() === "xml"
         ? "Format.XML"
         : "Format.JSON";
@@ -124,7 +129,8 @@ export const traceHelperFile = function traceHelperFile(opts?: TraceHelperOpts):
 
       // A renderable prompt (carries @textRef) gets an additional call<Entity> helper
       // that renders the prompt text, calls the LLM, then parses + persists a trace row.
-      const textRef = prompt.ownAttr(TEMPLATE_ATTR_TEXT_REF);
+      // ADR-0039: resolving — a prompt may inherit @textRef via extends.
+      const textRef = prompt.attr(TEMPLATE_ATTR_TEXT_REF);
       const renderable = typeof textRef === "string";
       // Same @format attr, two intentionally different shapes: extract() takes the
       // Format enum (formatLiteral, above → Format.XML/Format.JSON), render() takes the

package/src/index.ts

@@ -108,6 +108,8 @@ export {
   renderCreateFn,
   renderUpdateFn,
   renderDeleteByIdFn,
+  renderReverseFinderFns,
+  reverseFksFor,
   getPkInfo,
 } from "./templates/queries.js";