@metaobjectsdev/metadata 0.14.2 → 0.15.0-rc.1

package/src/loader/validation-passes.ts

@@ -107,7 +107,8 @@ import {
 
 export function validateDataGridSortFields(root: MetaData): ParseError[] {
   const errors: ParseError[] = [];
-  for (const obj of root.ownChildren().filter((c) => c.type === TYPE_OBJECT)) {
+  // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
+  for (const obj of root.children().filter((c) => c.type === TYPE_OBJECT)) {
     // Use children() so inherited fields (via extends:/super:) are
     // visible when validating @defaultSortField references.
     const effective = obj.children();
@@ -115,7 +116,8 @@ export function validateDataGridSortFields(root: MetaData): ParseError[] {
       effective.filter((c) => c.type === TYPE_FIELD).map((f) => f.name),
     );
     for (const layout of effective.filter((c) => c.type === TYPE_LAYOUT && c.subType === LAYOUT_SUBTYPE_DATA_GRID)) {
-      const sortField = layout.ownAttr(LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_FIELD);
+      // ADR-0039: resolving — a layout may inherit its grid attrs via extends.
+      const sortField = layout.attr(LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_FIELD);
       if (typeof sortField === "string" && !fieldNames.has(sortField)) {
         errors.push(
           new ParseError(
@@ -144,6 +146,8 @@ export function validateDataGridSortFields(root: MetaData): ParseError[] {
 /** Recursively collect all template.* nodes anywhere in the metadata tree. */
 function allTemplates(node: MetaData): MetaData[] {
   const out: MetaData[] = [];
+  // ADR-0039: own — structural walk over the PHYSICAL declaration tree collecting
+  // every declared template.* node (each visited once at its declaration site).
   for (const c of node.ownChildren()) {
     if (c.type === TYPE_TEMPLATE) out.push(c);
     out.push(...allTemplates(c));
@@ -161,9 +165,11 @@ export function validateTemplatePayloadRefs(root: MetaData): ParseError[] {
     // body). The closed-enum membership of @kind is handled by validateAttrSchema
     // (allowedValues) — here we only enforce the conditional ref presence.
     if (tmpl.subType === TEMPLATE_SUBTYPE_OUTPUT) {
-      const kind = tmpl.ownAttr(TEMPLATE_ATTR_KIND);
+      // ADR-0039: resolving — a template may inherit its refs/attrs via extends.
+      const kind = tmpl.attr(TEMPLATE_ATTR_KIND);
       if (kind === TEMPLATE_KIND_EMAIL) {
-        if (typeof tmpl.ownAttr(TEMPLATE_ATTR_SUBJECT_REF) !== "string") {
+        // ADR-0039: resolving — a template may inherit @subjectRef via extends.
+        if (typeof tmpl.attr(TEMPLATE_ATTR_SUBJECT_REF) !== "string") {
           errors.push(
             new ParseError(
               `template "${tmpl.name}" @kind "email" requires @subjectRef`,
@@ -171,7 +177,8 @@ export function validateTemplatePayloadRefs(root: MetaData): ParseError[] {
             ),
           );
         }
-        if (typeof tmpl.ownAttr(TEMPLATE_ATTR_HTML_BODY_REF) !== "string") {
+        // ADR-0039: resolving — a template may inherit @htmlBodyRef via extends.
+        if (typeof tmpl.attr(TEMPLATE_ATTR_HTML_BODY_REF) !== "string") {
           errors.push(
             new ParseError(
               `template "${tmpl.name}" @kind "email" requires @htmlBodyRef`,
@@ -183,7 +190,8 @@ export function validateTemplatePayloadRefs(root: MetaData): ParseError[] {
         // @kind absent or "document" → require @textRef. (An out-of-enum @kind is
         // separately reported by validateAttrSchema; we still require @textRef so a
         // document is never bodyless.)
-        if (typeof tmpl.ownAttr(TEMPLATE_ATTR_TEXT_REF) !== "string") {
+          // ADR-0039: resolving — a template may inherit @textRef via extends.
+        if (typeof tmpl.attr(TEMPLATE_ATTR_TEXT_REF) !== "string") {
           errors.push(
             new ParseError(
               `template "${tmpl.name}" @kind "document" requires @textRef`,
@@ -194,7 +202,8 @@ export function validateTemplatePayloadRefs(root: MetaData): ParseError[] {
       }
     } else if (tmpl.subType === TEMPLATE_SUBTYPE_PROMPT) {
       // template.prompt always carries a renderable body via @textRef.
-      if (typeof tmpl.ownAttr(TEMPLATE_ATTR_TEXT_REF) !== "string") {
+        // ADR-0039: resolving — a template may inherit @textRef via extends.
+      if (typeof tmpl.attr(TEMPLATE_ATTR_TEXT_REF) !== "string") {
         errors.push(
           new ParseError(
             `template "${tmpl.name}" requires @textRef`,
@@ -204,9 +213,11 @@ export function validateTemplatePayloadRefs(root: MetaData): ParseError[] {
       }
     }
 
-    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);
     if (typeof payloadRef !== "string") continue; // absence handled by the required-attr schema check
-    const payload = root.ownChildren().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, payloadRef));
+    // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
+    const payload = root.children().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, payloadRef));
     if (!payload || payload.subType !== OBJECT_SUBTYPE_VALUE) {
       // FR5d — @payloadRef is a reference; emit format=resolved with
       // referrer=template FQN, target=the unresolved payloadRef string.
@@ -221,9 +232,11 @@ export function validateTemplatePayloadRefs(root: MetaData): ParseError[] {
       );
       continue;
     }
-    const responseRef = tmpl.ownAttr(TEMPLATE_ATTR_RESPONSE_REF);
+    // ADR-0039: resolving — a template may inherit @responseRef via extends.
+    const responseRef = tmpl.attr(TEMPLATE_ATTR_RESPONSE_REF);
     if (typeof responseRef === "string") {
-      const resVo = root.ownChildren().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, responseRef));
+      // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
+      const resVo = root.children().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, responseRef));
       if (!resVo || resVo.subType !== OBJECT_SUBTYPE_VALUE) {
         errors.push(
           new ParseError(
@@ -236,7 +249,8 @@ export function validateTemplatePayloadRefs(root: MetaData): ParseError[] {
     const fieldNames = new Set(
       payload.children().filter((c) => c.type === TYPE_FIELD).map((f) => f.name),
     );
-    const slots = tmpl.ownAttr(TEMPLATE_ATTR_REQUIRED_SLOTS);
+    // ADR-0039: resolving — a template may inherit @requiredSlots via extends.
+    const slots = tmpl.attr(TEMPLATE_ATTR_REQUIRED_SLOTS);
     const slotList = Array.isArray(slots) ? slots : typeof slots === "string" ? [slots] : [];
     for (const slot of slotList) {
       if (typeof slot === "string" && !fieldNames.has(slot)) {
@@ -265,14 +279,16 @@ export function validateTemplatePayloadRefs(root: MetaData): ParseError[] {
 
 export function validateFilterableHasIndex(root: MetaData): string[] {
   const warnings: string[] = [];
-  for (const obj of root.ownChildren().filter((c) => c.type === TYPE_OBJECT)) {
+  // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
+  for (const obj of root.children().filter((c) => c.type === TYPE_OBJECT)) {
     // Use children() so inherited fields and identities (via extends:/super:)
     // are included when checking filterable-without-index.
     const effective = obj.children();
     // Build the set of field names that are part of any identity on this object.
     const indexedFieldNames = new Set<string>();
     for (const identity of effective.filter((c) => c.type === TYPE_IDENTITY)) {
-      const fields = identity.ownAttr(IDENTITY_ATTR_FIELDS);
+      // ADR-0039: resolving — an identity may inherit @fields via extends.
+      const fields = identity.attr(IDENTITY_ATTR_FIELDS);
       if (typeof fields === "string") {
         for (const name of fields.split(",")) indexedFieldNames.add(name.trim());
       } else if (Array.isArray(fields)) {
@@ -281,9 +297,11 @@ export function validateFilterableHasIndex(root: MetaData): string[] {
     }
 
     for (const field of effective.filter((c) => c.type === TYPE_FIELD)) {
-      const filterable = field.ownAttr(FIELD_ATTR_FILTERABLE);
+      // ADR-0039: resolving — a concrete field may inherit @filterable via extends.
+      const filterable = field.attr(FIELD_ATTR_FILTERABLE);
       if (filterable !== true) continue;
-      if (field.ownAttr(FIELD_ATTR_DB_INDEXED) === true) continue;
+      // ADR-0039: resolving — a concrete field may inherit @db.indexed via extends.
+      if (field.attr(FIELD_ATTR_DB_INDEXED) === true) continue;
       if (indexedFieldNames.has(field.name)) continue;
       warnings.push(
         `[filterable-without-index] field "${obj.name}.${field.name}" has @filterable: true but is not ` +
@@ -306,10 +324,12 @@ export function validateFilterableHasIndex(root: MetaData): string[] {
 
 export function validateFilterableHasSupportedOps(root: MetaData): ParseError[] {
   const errors: ParseError[] = [];
-  for (const obj of root.ownChildren().filter((c) => c.type === TYPE_OBJECT)) {
+  // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
+  for (const obj of root.children().filter((c) => c.type === TYPE_OBJECT)) {
     // children() — inherited @filterable fields (via extends:/super:) are visible.
     for (const field of obj.children().filter((c) => c.type === TYPE_FIELD)) {
-      if (field.ownAttr(FIELD_ATTR_FILTERABLE) !== true) continue;
+      // ADR-0039: resolving — a concrete field may inherit @filterable via extends.
+      if (field.attr(FIELD_ATTR_FILTERABLE) !== true) continue;
       if (opsForSubType(field.subType).length > 0) continue;
       errors.push(
         new ParseError(
@@ -341,7 +361,8 @@ export function validateFilterableHasSupportedOps(root: MetaData): ParseError[]
 function _findObject(root: MetaData, name: string): MetaData | undefined {
   // FR-032 — origin heads are FQN-qualified 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));
+  // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
+  return root.children().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, name));
 }
 
 function _findField(obj: MetaData, name: string): MetaData | undefined {
@@ -497,7 +518,8 @@ function _validateViaPath(
       );
       return undefined;
     }
-    const refTarget = rel.ownAttr(RELATIONSHIP_ATTR_OBJECT_REF);
+    // ADR-0039: resolving — a relationship may inherit @objectRef via extends.
+    const refTarget = rel.attr(RELATIONSHIP_ATTR_OBJECT_REF);
     if (typeof refTarget !== "string" || refTarget === "") {
       errors.push(
         new ParseError(
@@ -587,6 +609,8 @@ function _deriveBaseEntity(
 
   // 1) The extended identity anchors the base entity (declared, not inferred).
   //    The anchor is the entity NAMED in the ref's owner part — see _refNamedOwner.
+  // ADR-0039: own — inspects THIS projection's OWN declared identities to read
+  // their extends refs (an inherited identity carries no local superRef to anchor).
   for (const identity of obj.ownChildren().filter((c) => c.type === TYPE_IDENTITY)) {
     const extended = identity.superResolved;
     if (extended !== undefined && extended.type === TYPE_IDENTITY) {
@@ -600,6 +624,8 @@ function _deriveBaseEntity(
   // 2) Fallback: the single distinct entity targeted by plain field-extends —
   //    again preferring the ref-named owner over the physical declaring ancestor.
   const targets = new Set<MetaData>();
+  // ADR-0039: own — inspects THIS projection's OWN declared fields to read their
+  // extends refs (an inherited field carries no local superRef to anchor).
   for (const f of obj.ownChildren().filter((c) => c.type === TYPE_FIELD)) {
     const sup = f.superResolved;
     if (sup === undefined) continue;
@@ -679,7 +705,8 @@ function _inferViaSingleHop(
     .children()
     .filter((c) => c.type === TYPE_RELATIONSHIP)
     .filter((rel) => {
-      const ref = rel.ownAttr(RELATIONSHIP_ATTR_OBJECT_REF);
+      // ADR-0039: resolving — a relationship may inherit @objectRef via extends.
+      const ref = rel.attr(RELATIONSHIP_ATTR_OBJECT_REF);
       return typeof ref === "string" && stripPackage(ref) === targetEntity.name;
     });
   // FR5d — referrer is `<host-FQN>::<fieldName>`, target is the from/of ref
@@ -815,15 +842,19 @@ function _checkExtendsOriginAgreement(
 
 export function validateOriginPaths(root: MetaData): ParseError[] {
   const errors: ParseError[] = [];
-  for (const obj of root.ownChildren().filter((c) => c.type === TYPE_OBJECT)) {
+  // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
+  for (const obj of root.children().filter((c) => c.type === TYPE_OBJECT)) {
     // FR-024 B5: object.value hosts are EXEMPT from @via inference and
     // cardinality checks — a value's origin.passthrough is FR-015 parameter
     // lineage (values are constructed, never assembled; spec §7), not an
     // assembly path. Their @from refs are still resolution-validated.
     const isValueHost = obj.subType === OBJECT_SUBTYPE_VALUE;
+    // ADR-0039: own — origin validation operates on the OWN-declared field+origin
+    // layer (the established cross-port contract; origin.* never inherits, ADR-0029).
     for (const field of obj.ownChildren().filter((c) => c.type === TYPE_FIELD)) {
       for (const origin of field.ownChildren().filter((c) => c.type === TYPE_ORIGIN)) {
         if (origin.subType === ORIGIN_SUBTYPE_PASSTHROUGH) {
+          // ADR-0039: own — origin.* never inherits (ADR-0029).
           const from = origin.ownAttr(ORIGIN_PASSTHROUGH_ATTR_FROM);
           if (typeof from !== "string" || from === "") {
             // Missing-attr (not a reference resolution failure) — keep the
@@ -842,6 +873,7 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
           if (fromTarget !== undefined) {
             _checkExtendsOriginAgreement(field, fromTarget.field, from, obj, origin.source, errors);
           }
+          // ADR-0039: own — origin.* never inherits (ADR-0029).
           const via = origin.ownAttr(ORIGIN_PASSTHROUGH_ATTR_VIA);
           if (typeof via === "string" && via !== "") {
             const hops = _validateViaPath(via, root, obj, field.name, origin.source, errors);
@@ -864,6 +896,7 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
             }
           }
         } else if (origin.subType === ORIGIN_SUBTYPE_AGGREGATE) {
+          // ADR-0039: own — origin.* never inherits (ADR-0029).
           const of_ = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_OF);
           if (typeof of_ !== "string" || of_ === "") {
             errors.push(
@@ -878,6 +911,7 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
           // an aggregate computes something new (count/sum/…); spec §4 defines
           // agreement for passthrough only.
           const ofTarget = _validateFromPath(of_, root, obj, field.name, origin.source, errors, "origin.aggregate.@of");
+          // ADR-0039: own — origin.* never inherits (ADR-0029).
           const via = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_VIA);
           if (typeof via === "string" && via !== "") {
             const hops = _validateViaPath(via, root, obj, field.name, origin.source, errors);
@@ -953,14 +987,17 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
 
 export function validateDerivedFieldProvidability(root: MetaData): ParseError[] {
   const errors: ParseError[] = [];
+  // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
   for (const obj of root
-    .ownChildren()
+    .children()
     .filter((c) => c.type === TYPE_OBJECT && c.subType === OBJECT_SUBTYPE_ENTITY)) {
     const hasReadCapableSource = obj
       .children()
       .filter((c) => c.type === TYPE_SOURCE)
       .some((s) => (s as MetaSource).isReadOnly());
     if (hasReadCapableSource) continue;
+    // ADR-0039: own — origin-bearing fields are validated on the OWN-declared
+    // layer (mirrors validateOriginPaths; origin.* never inherits, ADR-0029).
     for (const field of obj.ownChildren().filter((c) => c.type === TYPE_FIELD)) {
       if (!field.ownChildren().some((c) => c.type === TYPE_ORIGIN)) continue;
       errors.push(
@@ -994,9 +1031,14 @@ export function validateDerivedFieldProvidability(root: MetaData): ParseError[]
 
 export function validateFieldObjectStorage(root: MetaData): ParseError[] {
   const errors: ParseError[] = [];
-  for (const obj of root.ownChildren().filter((c) => c.type === TYPE_OBJECT)) {
+  // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
+  for (const obj of root.children().filter((c) => c.type === TYPE_OBJECT)) {
+    // ADR-0039: own — the concrete field is an OWN child of this object; its
+    // inheritable attrs (@objectRef/@storage) are read resolving below.
     for (const field of obj.ownChildren().filter((c) => c.type === TYPE_FIELD)) {
-      const objectRef = field.ownAttr(FIELD_ATTR_OBJECT_REF);
+      // ADR-0039: resolving — a concrete field.object may inherit @objectRef from
+      // an abstract base via extends; reading own-only would wrongly reject it.
+      const objectRef = field.attr(FIELD_ATTR_OBJECT_REF);
       const hasObjectRef = typeof objectRef === "string" && objectRef.length > 0;
 
       if (field.subType === FIELD_SUBTYPE_OBJECT && !hasObjectRef) {
@@ -1011,9 +1053,10 @@ export function validateFieldObjectStorage(root: MetaData): ParseError[] {
         continue;
       }
 
-      const storage = field.ownAttr(FIELD_ATTR_STORAGE);
+      // ADR-0039: resolving — @storage and array-ness may be inherited via extends.
+      const storage = field.attr(FIELD_ATTR_STORAGE);
       if (storage === undefined || storage === null) continue;
-      if (storage === STORAGE_FLATTENED && field.isArray === true) {
+      if (storage === STORAGE_FLATTENED && field.resolvedIsArray()) {
         errors.push(
           new ParseError(
             `field "${obj.name}.${field.name}" sets @storage "flattened" with isArray=true; flattened storage requires a single nested value`,
@@ -1053,13 +1096,17 @@ const _MAP_SCALAR_VALUE_SUBTYPES = new Set<string>([
 
 export function validateFieldMap(root: MetaData): ParseError[] {
   const errors: ParseError[] = [];
-  for (const obj of root.ownChildren().filter((c) => c.type === TYPE_OBJECT)) {
+  // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
+  for (const obj of root.children().filter((c) => c.type === TYPE_OBJECT)) {
+    // ADR-0039: own — the concrete field is an OWN child; its inheritable attrs
+    // (@valueType/@objectRef) are read resolving below.
     for (const field of obj.ownChildren().filter((c) => c.type === TYPE_FIELD)) {
       if (field.subType !== FIELD_SUBTYPE_MAP) continue;
 
-      const valueType = field.ownAttr(FIELD_ATTR_VALUE_TYPE);
+      // ADR-0039: resolving — @valueType / @objectRef may be inherited via extends.
+      const valueType = field.attr(FIELD_ATTR_VALUE_TYPE);
       const hasValueType = typeof valueType === "string" && valueType.length > 0;
-      const objectRef = field.ownAttr(FIELD_ATTR_OBJECT_REF);
+      const objectRef = field.attr(FIELD_ATTR_OBJECT_REF);
       const hasObjectRef = typeof objectRef === "string" && objectRef.length > 0;
 
       if (hasValueType === hasObjectRef) {
@@ -1160,6 +1207,8 @@ export function validateFieldDefaults(root: MetaData): ParseError[] {
 function _walkFieldDefaults(node: MetaData, errors: ParseError[]): void {
   if (node.type === TYPE_FIELD && node.subType !== FIELD_SUBTYPE_ENUM) {
     // Enum @default membership is validated by attr-schema-validate Check 5.
+    // ADR-0039: own — validates the @default declared on THIS node (matches the
+    // @values / FR-011 own-attr passes; an inherited default was gated on its parent).
     const raw = node.ownAttr(FIELD_ATTR_DEFAULT);
     if (raw !== undefined && raw !== null && !Array.isArray(raw) && typeof raw !== "object") {
       const def = _stringifyDefault(raw as string | number | boolean);
@@ -1179,6 +1228,7 @@ function _walkFieldDefaults(node: MetaData, errors: ParseError[]): void {
       }
     }
   }
+  // ADR-0039: own — structural walk visiting every physical node once at its site.
   for (const child of node.ownChildren()) _walkFieldDefaults(child, errors);
 }
 
@@ -1193,18 +1243,21 @@ function _walkFieldDefaults(node: MetaData, errors: ParseError[]): void {
 
 export function validateDataGridFilterValues(root: MetaData): ParseError[] {
   const errors: ParseError[] = [];
-  for (const obj of root.ownChildren().filter((c) => c.type === TYPE_OBJECT)) {
+  // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
+  for (const obj of root.children().filter((c) => c.type === TYPE_OBJECT)) {
     const effective = obj.children();
     const allow = new Map<string, readonly string[]>();
     for (const f of effective.filter((c) => c.type === TYPE_FIELD)) {
-      if (f.ownAttr(FIELD_ATTR_FILTERABLE) === true) {
+      // ADR-0039: resolving — a concrete field may inherit @filterable via extends.
+      if (f.attr(FIELD_ATTR_FILTERABLE) === true) {
         allow.set(f.name, opsForSubType(f.subType));
       }
     }
     for (const layout of effective.filter(
       (c) => c.type === TYPE_LAYOUT && c.subType === LAYOUT_SUBTYPE_DATA_GRID,
     )) {
-      const filter = layout.ownAttr(LAYOUT_DATA_GRID_ATTR_FILTER);
+      // ADR-0039: resolving — a layout may inherit @filter via extends.
+      const filter = layout.attr(LAYOUT_DATA_GRID_ATTR_FILTER);
       // Type errors (e.g. legacy string form) are reported by validateAttrSchema.
       if (typeof filter !== "object" || filter === null || Array.isArray(filter)) continue;
       checkFilterClauses(filter as Record<string, unknown>, allow, obj.name, layout.name, layout.source, errors);
@@ -1257,13 +1310,18 @@ function _countJunctionReferences(junction: MetaData): number {
 
 export function validateRelationships(root: MetaData): ParseError[] {
   const errors: ParseError[] = [];
-  for (const obj of root.ownChildren().filter((c) => c.type === TYPE_OBJECT)) {
+  // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
+  for (const obj of root.children().filter((c) => c.type === TYPE_OBJECT)) {
+    // ADR-0039: own — a relationship is validated on the entity that DECLARES it
+    // (the M:N slim-vocabulary rules apply to own-declared relationships; its
+    // inheritable attrs are read resolving below).
     for (const rel of obj.ownChildren().filter((c) => c.type === TYPE_RELATIONSHIP)) {
-      const through = rel.ownAttr(RELATIONSHIP_ATTR_THROUGH);
-      const sourceRefField = rel.ownAttr(RELATIONSHIP_ATTR_SOURCE_REF_FIELD);
-      const symmetric = rel.ownAttr(RELATIONSHIP_ATTR_SYMMETRIC) === true;
-      const cardinality = rel.ownAttr(RELATIONSHIP_ATTR_CARDINALITY);
-      const objectRef = rel.ownAttr(RELATIONSHIP_ATTR_OBJECT_REF);
+      // ADR-0039: resolving — a relationship may inherit its M:N attrs via extends.
+      const through = rel.attr(RELATIONSHIP_ATTR_THROUGH);
+      const sourceRefField = rel.attr(RELATIONSHIP_ATTR_SOURCE_REF_FIELD);
+      const symmetric = rel.attr(RELATIONSHIP_ATTR_SYMMETRIC) === true;
+      const cardinality = rel.attr(RELATIONSHIP_ATTR_CARDINALITY);
+      const objectRef = rel.attr(RELATIONSHIP_ATTR_OBJECT_REF);
 
       const hasThrough = typeof through === "string" && through !== "";
       const hasSourceRefField = typeof sourceRefField === "string" && sourceRefField !== "";

package/src/loader/validation-registry.ts

@@ -19,7 +19,8 @@ class SymbolTableImpl implements SymbolTable {
 
   static build(root: MetaData): SymbolTableImpl {
     const t = new SymbolTableImpl();
-    for (const child of root.ownChildren()) {
+    // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
+    for (const child of root.children()) {
       if (child.type !== TYPE_OBJECT) continue;
       if (child.name) t.byRef.set(child.name, child);
       t.byRef.set(child.fqn(), child);
@@ -60,7 +61,9 @@ export function runRegisteredValidation(root: MetaData, registry: TypeRegistry):
     const def = registry.find(node.type, node.subType);
     if (def) {
       for (const desc of def.references ?? []) {
-        const raw = node.ownAttr(desc.attr);
+        // ADR-0039: resolving — a reference attr (e.g. @objectRef/@through) may be
+        // inherited via extends; read the effective value.
+        const raw = node.attr(desc.attr);
         if (typeof raw !== "string" || raw === "") continue; // absence is the required-attr pass's job
         const entityRef = desc.dottedFieldPath ? (raw.split(".")[0] ?? raw) : raw;
         const target = ctx.symbols.resolveObject(entityRef);
@@ -88,6 +91,8 @@ export function runRegisteredValidation(root: MetaData, registry: TypeRegistry):
       }
       def.validate?.(node, ctx);
     }
+    // ADR-0039: own — structural walk visiting every physical node once at its
+    // declaration site (an inherited child is validated on its declaring parent).
     for (const child of node.ownChildren()) walk(child);
   }
 }

package/src/naming.ts

@@ -82,7 +82,8 @@ export function resolveColumnName(
   field: MetaData,
   strategy: ColumnNamingStrategy = DEFAULT_COLUMN_NAMING_STRATEGY,
 ): string {
-  const col = field.ownAttr(FIELD_ATTR_COLUMN);
+  // ADR-0039: resolving — a concrete field may inherit @column via extends.
+  const col = field.attr(FIELD_ATTR_COLUMN);
   if (typeof col === "string" && col) return col;
   return applyColumnNamingStrategy(field.name, strategy);
 }
@@ -95,12 +96,14 @@ export function resolveColumnName(
  * SQLite treats it as the only allowed value (no schema concept).
  */
 export function resolveTableSchema(entity: MetaData): string | undefined {
-  const source = entity.ownChildren().find(
+  // ADR-0039: resolving — a concrete entity may inherit its source.rdb via extends.
+  const source = entity.children().find(
     (c): c is MetaSource =>
       c instanceof MetaSource && c.role === SOURCE_ROLE_PRIMARY,
   );
   if (!source) return undefined;
-  const schema = source.ownAttr(SOURCE_ATTR_SCHEMA);
+  // ADR-0039: resolving — an inherited source's @schema lives on the super node.
+  const schema = source.attr(SOURCE_ATTR_SCHEMA);
   if (typeof schema === "string" && schema !== "") return schema;
   return undefined;
 }

package/src/object-serializer.ts

@@ -41,7 +41,8 @@ export function objectToJson(
   for (const field of mo.fields()) {
     const raw = instance[field.name];
     if (raw === undefined) continue; // absent field → omit
-    out[field.name] = field.isArray
+    // ADR-0039: resolving — array-ness may be inherited via extends.
+    out[field.name] = field.resolvedIsArray()
       ? mapArray(raw, (el) => toJsonValue(field, el, mo))
       : toJsonValue(field, raw, mo);
   }
@@ -57,7 +58,8 @@ export function jsonToObject(
   for (const field of mo.fields()) {
     const raw = json[field.name];
     if (raw === undefined) continue;
-    out[field.name] = field.isArray
+    // ADR-0039: resolving — array-ness may be inherited via extends.
+    out[field.name] = field.resolvedIsArray()
       ? mapArray(raw, (el) => fromJsonValue(field, el, mo))
       : fromJsonValue(field, raw, mo);
   }
@@ -147,6 +149,8 @@ function coerceNumeric(raw: unknown): unknown {
 function resolveObjectRef(field: MetaField, mo: MetaObject): MetaObject | undefined {
   const ref = field.objectRef;
   if (ref === undefined) return undefined;
+  // ADR-0039: own — lookup is on the tree ROOT, which has no super chain
+  // (it never `extends`), so its own children ARE its effective children.
   const found: MetaData | undefined = mo.root().ownChildByTypeAndName(TYPE_OBJECT, ref);
   if (found === undefined) return undefined;
   return found as MetaObject;

package/src/parser-core.ts

@@ -672,6 +672,8 @@ function parseNodeInto(
     // Snapshot of own attrs (name → value) — used to detect ERR_MERGE_CONFLICT
     // when a new contribution sets an attr the target already declared to a
     // different non-empty value.
+    // ADR-0039: own — overlay/merge machinery, operating on the AUTHORED
+    // declaration layer (pre super-resolution).
     preMergeAttrSnapshot = new Map(target.ownAttrs());
   }
 
@@ -897,6 +899,8 @@ function createOrFindMetaData(
 
   // Look up an existing child with (type, name). Skip unnamed nodes — they
   // are always distinct (e.g. inline validators, anonymous attrs).
+  // ADR-0039: own — overlay/merge lookup on the AUTHORED declaration layer
+  // (an overlay targets a same-file/same-node own child, pre super-resolution).
   const existing = name !== "" ? parent.ownChildByTypeAndName(type, name) : undefined;
 
   if (isOverlayNode) {
@@ -1245,6 +1249,7 @@ function processChildren(
         childNodePath,
       );
 
+      // ADR-0039: own — tree-building dedup on the AUTHORED declaration layer.
       if (childModel !== undefined && !parent.ownChildren().includes(childModel)) {
         parent.addChild(childModel);
       }

package/src/persistence/db/db-constants.ts

@@ -2,7 +2,6 @@
 
 import {
   FIELD_SUBTYPE_STRING,
-  FIELD_SUBTYPE_TIMESTAMP,
 } from "../../core/field/field-constants.js";
 
 /** Column name override on a field (maps to @column in metadata). */
@@ -38,20 +37,29 @@ export const FIELD_ATTR_DB_COLUMN_TYPE = "dbColumnType";
 export const DB_COLUMN_TYPE_UUID = "uuid";
 /** `@dbColumnType: jsonb` — genuinely-open `jsonb` column (legal on field.string). */
 export const DB_COLUMN_TYPE_JSONB = "jsonb";
-/** `@dbColumnType: timestamp_with_tz` — `timestamp with time zone` (legal on field.timestamp). */
-export const DB_COLUMN_TYPE_TIMESTAMP_WITH_TZ = "timestamp_with_tz";
-/** `@dbColumnType: uuid_array` — native Postgres `uuid[]` column (legal on field.string). */
-export const DB_COLUMN_TYPE_UUID_ARRAY = "uuid_array";
-/** `@dbColumnType: text_array` — native Postgres `text[]` column (legal on field.string). */
-export const DB_COLUMN_TYPE_TEXT_ARRAY = "text_array";
 
-/** The closed set of legal `@dbColumnType` values (raw-dialect passthrough deferred). */
+/**
+ * ADR-0036 Wave 2: `@localTime` — a boolean flag on `field.timestamp` marking the
+ * rare naive / wall-clock case. When true the column is Postgres `timestamp
+ * without time zone`; absent/false (the default) is an absolute instant →
+ * `timestamptz`. This replaces the retired `@dbColumnType: timestamp_with_tz`
+ * escape hatch — timezone-awareness now lives in the logical field type
+ * (instant-by-default) + this opt-out, not in a physical column-type string.
+ */
+export const FIELD_ATTR_LOCAL_TIME = "localTime";
+
+/**
+ * The closed set of legal `@dbColumnType` values (raw-dialect passthrough deferred).
+ * dbColumnType slim-and-derive (ADR-0036 Wave 1, decision 4): the native-array
+ * overrides `uuid_array`/`text_array` are fully removed — native `uuid[]`/`text[]`
+ * are DERIVED from a field subtype + `isArray`, never declared via an escape hatch.
+ * Wave 2 (decision 1) retires `timestamp_with_tz` entirely — tz-awareness moves to
+ * `field.timestamp` (instant by default) + `@localTime` (the naive opt-out). The
+ * legal set is now just `{ uuid, jsonb }`, both on field.string.
+ */
 export const DB_COLUMN_TYPE_VALUES = [
   DB_COLUMN_TYPE_UUID,
   DB_COLUMN_TYPE_JSONB,
-  DB_COLUMN_TYPE_TIMESTAMP_WITH_TZ,
-  DB_COLUMN_TYPE_UUID_ARRAY,
-  DB_COLUMN_TYPE_TEXT_ARRAY,
 ] as const;
 export type DbColumnTypeValue = (typeof DB_COLUMN_TYPE_VALUES)[number];
 
@@ -59,12 +67,9 @@ export type DbColumnTypeValue = (typeof DB_COLUMN_TYPE_VALUES)[number];
  * Legal `@dbColumnType` value → the field subtypes it may be applied to (ADR-0013,
  * R6 Plan 2b). Any other (subtype × value) pairing — or an unrecognized value — is
  * an ERR_BAD_ATTR_VALUE. Keyed by value; the value-set is enforced by membership in
- * this map. Subtype names are the bare FIELD_SUBTYPE_* constants (string / timestamp).
+ * this map. Subtype names are the bare FIELD_SUBTYPE_* constants (string).
  */
 export const DB_COLUMN_TYPE_LEGAL_SUBTYPES: Readonly<Record<DbColumnTypeValue, readonly string[]>> = {
   [DB_COLUMN_TYPE_UUID]: [FIELD_SUBTYPE_STRING],
   [DB_COLUMN_TYPE_JSONB]: [FIELD_SUBTYPE_STRING],
-  [DB_COLUMN_TYPE_TIMESTAMP_WITH_TZ]: [FIELD_SUBTYPE_TIMESTAMP],
-  [DB_COLUMN_TYPE_UUID_ARRAY]: [FIELD_SUBTYPE_STRING],
-  [DB_COLUMN_TYPE_TEXT_ARRAY]: [FIELD_SUBTYPE_STRING],
 } as const;

package/src/persistence/db/db-definition.embedded.ts

@@ -35,7 +35,25 @@ export const DB_DEFINITION: ProviderDefinition = {
           "name": "dbColumnType",
           "min": 0,
           "max": 1,
-          "description": "Physical DB column-type override (ADR-0013 escape hatch). Legal values are uuid | jsonb | timestamp_with_tz | uuid_array | text_array, each legal only on a specific logical field subtype (uuid/jsonb/uuid_array/text_array on field.string, timestamp_with_tz on field.timestamp). uuid_array/text_array emit native SQL arrays (uuid[]/text[]). The logical field type and its native binding are unchanged."
+          "allowedValues": [
+            "uuid",
+            "jsonb"
+          ],
+          "description": "Physical DB column-type override (ADR-0013 escape hatch). Legal values are uuid | jsonb, both on field.string (uuid = native Postgres uuid column over a string-typed field; jsonb = genuinely-open JSON column). The logical field type and its native binding are unchanged. Native SQL arrays (uuid[]/text[]) are NOT declared here — they are derived from a field subtype + isArray (ADR-0036 Wave 1). The retired timestamp_with_tz value is gone — timezone-awareness lives in field.timestamp (instant by default) + @localTime (the naive opt-out), per ADR-0036 Wave 2."
+        }
+      ]
+    },
+    {
+      "type": "field",
+      "subType": "timestamp",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "boolean",
+          "name": "localTime",
+          "min": 0,
+          "max": 1,
+          "description": "When true, the timestamp is a naive wall-clock value with no timezone (Postgres `timestamp without time zone`); absent/false (the default) = an absolute instant (`timestamptz`). ADR-0036 Wave 2 — replaces the retired @dbColumnType: timestamp_with_tz escape hatch."
         }
       ]
     },

package/src/persistence/origin/meta-origin.ts

@@ -30,12 +30,14 @@ export class MetaOrigin extends MetaData {}
 export class MetaPassthroughOrigin extends MetaOrigin {
   /** The dotted-path cross-entity field reference this origin passes through (e.g. "Program.title"). */
   get from(): string | undefined {
+    // ADR-0039: own — origin.* never inherits (ADR-0029), so own is correct.
     const v = this.ownAttr(ORIGIN_PASSTHROUGH_ATTR_FROM);
     return typeof v === "string" ? v : undefined;
   }
 
   /** Optional dotted relationship path used to reach the source entity (e.g. "Program.weeks"). */
   get via(): string | undefined {
+    // ADR-0039: own — origin.* never inherits (ADR-0029), so own is correct.
     const v = this.ownAttr(ORIGIN_PASSTHROUGH_ATTR_VIA);
     return typeof v === "string" ? v : undefined;
   }
@@ -50,18 +52,21 @@ export class MetaPassthroughOrigin extends MetaOrigin {
 export class MetaAggregateOrigin extends MetaOrigin {
   /** The aggregate function (count | sum | avg | min | max). */
   get agg(): AggregateFunction | undefined {
+    // ADR-0039: own — origin.* never inherits (ADR-0029), so own is correct.
     const v = this.ownAttr(ORIGIN_AGGREGATE_ATTR_AGG);
     return typeof v === "string" ? (v as AggregateFunction) : undefined;
   }
 
   /** The dotted-path target of the aggregate (e.g. "Week.id"). */
   get of(): string | undefined {
+    // ADR-0039: own — origin.* never inherits (ADR-0029), so own is correct.
     const v = this.ownAttr(ORIGIN_AGGREGATE_ATTR_OF);
     return typeof v === "string" ? v : undefined;
   }
 
   /** The dotted relationship path the aggregate walks (e.g. "Program.weeks"). */
   get via(): string | undefined {
+    // ADR-0039: own — origin.* never inherits (ADR-0029), so own is correct.
     const v = this.ownAttr(ORIGIN_AGGREGATE_ATTR_VIA);
     return typeof v === "string" ? v : undefined;
   }
@@ -76,6 +81,7 @@ export class MetaAggregateOrigin extends MetaOrigin {
 export class MetaCollectionOrigin extends MetaOrigin {
   /** The dotted relationship path (or wildcard selector) this collection is sourced from. */
   get via(): string | undefined {
+    // ADR-0039: own — origin.* never inherits (ADR-0029), so own is correct.
     const v = this.ownAttr(ORIGIN_COLLECTION_ATTR_VIA);
     return typeof v === "string" ? v : undefined;
   }