@metaobjectsdev/metadata 0.14.2 → 0.15.0

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

@@ -36,7 +36,9 @@ export class MetaSource extends MetaData {
    *  back-compat accessor that reads ONLY the @table slot — callers should
    *  use physicalName for the FR-016 four-step rule. */
   get tableName(): string | undefined {
-    const v = this.ownAttr(SOURCE_ATTR_TABLE);
+    // ADR-0039: resolving — a source may be inherited via extends (an entity
+    // extending BaseEntity inherits its source.rdb); @table can live on the super.
+    const v = this.attr(SOURCE_ATTR_TABLE);
     return typeof v === "string" && v !== "" ? v : undefined;
   }
 
@@ -45,13 +47,15 @@ export class MetaSource extends MetaData {
    * `"table"` when omitted (ADR-0007 Rule 3 — per-paradigm default).
    */
   get effectiveKind(): string {
-    const v = this.ownAttr(SOURCE_ATTR_KIND);
+    // ADR-0039: resolving — an inherited source's @kind lives on the super node.
+    const v = this.attr(SOURCE_ATTR_KIND);
     return typeof v === "string" && v !== "" ? v : DEFAULT_SOURCE_KIND;
   }
 
   /** The multi-source role for this source (defaults to "primary" when omitted). */
   get role(): string {
-    const v = this.ownAttr(SOURCE_ATTR_ROLE);
+    // ADR-0039: resolving — an inherited source's @role lives on the super node.
+    const v = this.attr(SOURCE_ATTR_ROLE);
     return typeof v === "string" && v !== "" ? v : DEFAULT_SOURCE_ROLE;
   }
 
@@ -85,13 +89,15 @@ export class MetaSource extends MetaData {
     // Step 1: kind-matching alias.
     const canonicalAttr = PHYSICAL_NAME_ATTR_BY_KIND.get(kind);
     if (canonicalAttr !== undefined) {
-      const v = this.ownAttr(canonicalAttr);
+      // ADR-0039: resolving — an inherited source's physical-name alias lives on the super.
+      const v = this.attr(canonicalAttr);
       if (typeof v === "string" && v !== "") return v;
     }
 
     // Step 2: legacy @table for non-table kind.
     if (canonicalAttr !== SOURCE_ATTR_TABLE) {
-      const legacy = this.ownAttr(SOURCE_ATTR_TABLE);
+      // ADR-0039: resolving — inherited @table lives on the super node.
+      const legacy = this.attr(SOURCE_ATTR_TABLE);
       if (typeof legacy === "string" && legacy !== "") return legacy;
     }
 

package/src/persistence/source/validate-source-parameter-ref.ts

@@ -55,7 +55,8 @@ export function validateSourceParameterRef(root: MetaData): ParseError[] {
   // matches via resolutionKey() (these fixtures declare package at metadata.root
   // only, so obj.package is undefined and the file-default must be folded in).
   const objectIndex = new Map<string, MetaData>();
-  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)) {
     objectIndex.set(obj.name, obj);
     const fqn = obj.package !== undefined && obj.package !== ""
       ? `${obj.package}${PACKAGE_SEPARATOR}${obj.name}`
@@ -64,12 +65,15 @@ export function validateSourceParameterRef(root: MetaData): ParseError[] {
     objectIndex.set(obj.resolutionKey(), obj);
   }
 
-  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 — declaration-layer source iteration (mirrors validateSourceRoles).
     for (const source of obj.ownChildren().filter(
       (c): c is MetaSource =>
         c.type === TYPE_SOURCE && c.subType === SOURCE_SUBTYPE_RDB && c instanceof MetaSource,
     )) {
-      const ref = source.ownAttr(SOURCE_ATTR_PARAMETER_REF);
+      // ADR-0039: resolving — a source may inherit @parameterRef via extends.
+      const ref = source.attr(SOURCE_ATTR_PARAMETER_REF);
       if (typeof ref !== "string" || ref === "") continue;
 
       // ERR_PARAMETER_REF_ON_NON_CALLABLE_KIND — checked even before resolution
@@ -114,11 +118,15 @@ export function validateSourceParameterRef(root: MetaData): ParseError[] {
       // with origin.passthrough must have a subtype matching the referenced
       // field. The origin path validation pass checks the from-path resolves;
       // here we just check the subtype alignment.
-      for (const paramField of target.ownChildren().filter((c) => c.type === TYPE_FIELD)) {
+      // ADR-0039: resolving — the parameter value-object's fields may be inherited.
+      for (const paramField of target.children().filter((c) => c.type === TYPE_FIELD)) {
+        // ADR-0039: own — origin.* never inherits (ADR-0029); the origin child and
+        // its @from are read own.
         const passthrough = paramField.ownChildren().find(
           (c) => c.type === TYPE_ORIGIN && c.subType === ORIGIN_SUBTYPE_PASSTHROUGH,
         );
         if (passthrough === undefined) continue;
+        // ADR-0039: own — origin.* never inherits (ADR-0029).
         const from = passthrough.ownAttr(ORIGIN_PASSTHROUGH_ATTR_FROM);
         if (typeof from !== "string" || from === "") continue;
         const dot = from.indexOf(".");
@@ -127,7 +135,8 @@ export function validateSourceParameterRef(root: MetaData): ParseError[] {
         const targetFieldName = from.slice(dot + 1);
         const targetEntity = objectIndex.get(targetEntityName);
         if (targetEntity === undefined) continue; // origin-paths pass surfaces this
-        const targetField = targetEntity.ownChildren().find(
+        // ADR-0039: resolving — the referenced entity's field may be inherited via extends.
+        const targetField = targetEntity.children().find(
           (c) => c.type === TYPE_FIELD && c.name === targetFieldName,
         );
         if (targetField === undefined) continue;

package/src/persistence/source/validate-source-physical-names.ts

@@ -42,7 +42,11 @@ export function validateSourcePhysicalNames(root: MetaData): PhysicalNameValidat
   const errors: ParseError[] = [];
   const warnings: LoaderWarning[] = [];
 
-  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 — validates the physical-name aliases DECLARED on this object's
+    // own sources (declaration-layer, mirrors validateSourceRoles); an inherited
+    // source's aliases were validated on the object that declares it.
     const sources = obj
       .ownChildren()
       .filter(
@@ -54,6 +58,9 @@ export function validateSourcePhysicalNames(root: MetaData): PhysicalNameValidat
       // Empty-string check first — explicit "" is meaningless and an
       // authoring error regardless of which alias was used.
       for (const attr of ALL_PHYSICAL_NAME_ALIASES) {
+        // ADR-0039: own — the "exactly one alias, non-empty" rule is a per-source
+        // OWN-declaration constraint (resolving would conflate an inherited alias
+        // with an own one and falsely trip ERR_PHYSICAL_NAME_MULTIPLE).
         const v = source.ownAttr(attr);
         if (typeof v === "string" && v === "") {
           errors.push(
@@ -66,6 +73,7 @@ export function validateSourcePhysicalNames(root: MetaData): PhysicalNameValidat
       }
 
       const setAliases = ALL_PHYSICAL_NAME_ALIASES.filter((attr) => {
+        // ADR-0039: own — per-source own-declaration constraint (see above).
         const v = source.ownAttr(attr);
         return typeof v === "string" && v !== "";
       });

package/src/persistence/source/validate-source-roles.ts

@@ -23,7 +23,11 @@ import { OBJECT_SUBTYPE_ENTITY } from "../../core/object/object-constants.js";
 export function validateSourceRoles(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 one-primary rule is a DECLARATION-layer check (cross-port
+    // parity: Java uses getSources(false)); it counts sources declared on THIS object,
+    // not inherited ones. The role/kind reads below resolve via MetaSource getters.
     const sources = obj
       .ownChildren()
       .filter((c) => c.type === TYPE_SOURCE)

package/src/presentation/layout/meta-layout.ts

@@ -18,13 +18,15 @@ import type { SortOrderValue } from "../../core/query/query-constants.js";
 export class MetaLayout extends MetaData {
   /** The number of rows per page for the dataGrid layout. */
   get pageSize(): number | undefined {
-    const v = this.ownAttr(LAYOUT_DATA_GRID_ATTR_PAGE_SIZE);
+    // ADR-0039: resolving — a layout may inherit its grid attrs via extends.
+    const v = this.attr(LAYOUT_DATA_GRID_ATTR_PAGE_SIZE);
     return typeof v === "number" ? v : undefined;
   }
 
   /** The field name to sort by default in the dataGrid layout. */
   get defaultSortField(): string | undefined {
-    const v = this.ownAttr(LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_FIELD);
+    // ADR-0039: resolving — a layout may inherit its grid attrs via extends.
+    const v = this.attr(LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_FIELD);
     return typeof v === "string" ? v : undefined;
   }
 
@@ -33,7 +35,8 @@ export class MetaLayout extends MetaData {
    * Returns `undefined` when the attr is absent.
    */
   get defaultSortOrder(): SortOrderValue | undefined {
-    const v = this.ownAttr(LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_ORDER);
+    // ADR-0039: resolving — a layout may inherit its grid attrs via extends.
+    const v = this.attr(LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_ORDER);
     return typeof v === "string" ? (v as SortOrderValue) : undefined;
   }
 
@@ -42,12 +45,14 @@ export class MetaLayout extends MetaData {
    * Defaults to `false` when the attr is absent.
    */
   get filterable(): boolean {
-    return this.ownAttr(LAYOUT_DATA_GRID_ATTR_FILTERABLE) === true;
+    // ADR-0039: resolving — a layout may inherit @filterable via extends.
+    return this.attr(LAYOUT_DATA_GRID_ATTR_FILTERABLE) === true;
   }
 
   /** The desugared preset filter object for the dataGrid layout, or undefined. */
   get filter(): Record<string, unknown> | undefined {
-    const v = this.ownAttr(LAYOUT_DATA_GRID_ATTR_FILTER);
+    // ADR-0039: resolving — a layout may inherit its grid attrs via extends.
+    const v = this.attr(LAYOUT_DATA_GRID_ATTR_FILTER);
     return typeof v === "object" && v !== null && !Array.isArray(v)
       ? (v as Record<string, unknown>)
       : undefined;
@@ -55,7 +60,8 @@ export class MetaLayout extends MetaData {
 
   /** The ordered list of field names to display as columns in the dataGrid layout. */
   get columns(): string[] {
-    const c = this.ownAttr(LAYOUT_DATA_GRID_ATTR_COLUMNS);
+    // ADR-0039: resolving — a layout may inherit its grid attrs via extends.
+    const c = this.attr(LAYOUT_DATA_GRID_ATTR_COLUMNS);
     return Array.isArray(c) ? (c as string[]) : [];
   }
 }

package/src/registry-manifest.ts

@@ -9,12 +9,15 @@
 //
 // The IN/OUT boundary is documented in fixtures/registry-conformance/README.md.
 // In short, the manifest emits: type.subType + per-type/per-attr `description`
-// (FR-033) + attrs[{name, valueType, isArray, required, description, rules?,
-// example?, whenToUse?}] + the structural constraint graph (children / parents /
-// cardinality, FR-033) + commonAttrs + defaultSubTypes. EXCLUDED (per-port-
-// physical or not-universally-tracked-on-the-registry): factories/native
-// bindings; AttrSchema.default and allowedValues (Java's attr model —
-// ChildRequirement — carries neither).
+// (FR-033) + attrs[{name, valueType, isArray, required, allowedValues?,
+// description, rules?, example?, whenToUse?}] + the structural constraint graph
+// (children / parents / cardinality, FR-033) + commonAttrs + defaultSubTypes.
+// `allowedValues` (ADR-0036 Wave 1, decision 5) is the closed value-set of a
+// closed-enum attr — emitted ONLY when the attr declares one, OMITTED for open /
+// format-validated attrs (@currency, @locale). It byte-gates closed vocabularies
+// cross-port (the gate that catches a value-set silently drifting between ports).
+// EXCLUDED (per-port-physical or not-universally-tracked-on-the-registry):
+// factories/native bindings; AttrSchema.default.
 //
 // FR-033 Task 5 GREW the manifest: it now also emits the documentation surface
 // (every type/attr carries a required, non-empty `description`; optional `rules`/
@@ -41,6 +44,14 @@ interface ManifestAttr {
   /** True for an array-valued attr (a list of the scalar `valueType`); the orthogonal array axis. */
   isArray: boolean;
   required: boolean;
+  /**
+   * The closed value-set of a closed-enum attr (ADR-0036 Wave 1, decision 5).
+   * Emitted ONLY when the attr declares a non-empty `allowedValues` set; OMITTED
+   * for open / format-validated attrs (e.g. @currency ISO-4217, @locale BCP-47).
+   * This byte-gates closed-enum vocabularies cross-port — the gate that catches a
+   * value-set drifting between ports (the failure mode the dbColumnType slim hit).
+   */
+  allowedValues?: readonly string[];
   /** FR-033 — human/AI-facing description of the attribute (required, non-empty). */
   description: string;
   /** FR-033 — prose documenting the complex rules enforced in code. Emitted only when present. */
@@ -119,11 +130,18 @@ function toManifestAttr(attr: AttrSchema): ManifestAttr {
   // FR-033: the documentation surface (`description` required + non-empty;
   // `rules`/`example`/`whenToUse` emitted ONLY when present) follows the
   // existing facets, preserving key order for byte-stability.
+  // The closed value-set, emitted only when present + non-empty (decision 5).
+  // AttrValue is string | number | boolean | array; a closed enum is always a set
+  // of scalar string members, so stringify each for a stable cross-port surface.
+  // Spread BEFORE `description` so the JSON key order is name → valueType →
+  // isArray → required → (allowedValues?) → description → (rules?/example?/whenToUse?).
+  const hasAllowed = attr.allowedValues !== undefined && attr.allowedValues.length > 0;
   const out: ManifestAttr = {
     name: attr.name,
     valueType,
     isArray,
     required: attr.required,
+    ...(hasAllowed ? { allowedValues: attr.allowedValues!.map((v) => String(v)) } : {}),
     description: attr.description,
   };
   if (attr.rules !== undefined) out.rules = attr.rules;
@@ -309,8 +327,10 @@ export function buildRegistryManifest(registry: TypeRegistry): RegistryManifest
  *  - 2-space indentation (JSON.stringify(_, _, 2)).
  *  - Object keys in a fixed order (JSON.stringify preserves insertion order):
  *    the manifest is built with `types`, `commonAttrs`, `defaultSubTypes`.
- *    - Each attr: `name`, `valueType`, `isArray`, `required`, `description`,
- *      then optional `rules`, `example`, `whenToUse` (each omitted when absent).
+ *    - Each attr: `name`, `valueType`, `isArray`, `required`, then optional
+ *      `allowedValues` (omitted unless the attr declares a non-empty closed set —
+ *      decision 5), then `description`, then optional `rules`, `example`,
+ *      `whenToUse` (each omitted when absent).
  *    - Each type: `type`, `subType`, `description`, then optional `rules`,
  *      `example`, `whenToUse` (omitted when absent), then `attrs`, `children`,
  *      then optional `parents` (omitted when absent/empty).

package/src/serializer-json.ts

@@ -122,12 +122,19 @@ function serializeNodeInner(
   // (re-parsing would seek a non-existent node to merge into). So it is
   // deliberately NOT serialized.
 
-  if (model.isArray === true) {
+  // ADR-0039: effective mode resolves array-ness through the super chain (a
+  // concrete field that extends an abstract array field is itself an array);
+  // own mode (canonicalSerialize) emits only the authored `isArray` so the
+  // round-trip reconstructs the same extends tree.
+  const isArrayForMode = effective ? model.resolvedIsArray() : model.isArray === true;
+  if (isArrayForMode) {
     obj[RESERVED_KEY_IS_ARRAY] = true;
   }
 
   // In effective mode use children()/attrs() (own + inherited via super chain);
   // in own mode use ownChildren()/ownAttrs() (declared on this node only).
+  // ADR-0039: own-mode canonical serializer — round-trips the AUTHORED form so
+  // re-loading reconstructs the same extends tree (the effective branch resolves).
   const childList = effective ? model.children() : model.ownChildren();
   const attrMap = effective ? model.attrs() : model.ownAttrs();
 

package/src/shared/meta-data.ts

@@ -204,6 +204,32 @@ export abstract class MetaData {
     this.isArray = val;
   }
 
+  /**
+   * Effective array-ness — the RESOLVING accessor for the native `isArray` flag
+   * (ADR-0039). `isArray` is a native boolean property, NOT an attr, so it has no
+   * resolving path through attrs()/attr(); a concrete node that `extends` an
+   * abstract array node inherits its array-ness only through the super chain.
+   * Reading the bare `isArray` field is OWN-ONLY and silently drops inherited
+   * array-ness — every codegen/runtime/effective-serializer read of a node's
+   * effective array-ness MUST route through this method instead.
+   *
+   * Returns the node's own `isArray` if set true, else walks the super chain.
+   * (Own `true` always wins; a node can only widen to array, never narrow — an
+   * abstract array base extended by a concrete node stays an array.)
+   */
+  resolvedIsArray(): boolean {
+    return this.cached("resolvedIsArray", () => {
+      let node: MetaData | undefined = this;
+      const visited = new Set<MetaData>();
+      while (node !== undefined && !visited.has(node)) {
+        if (node.isArray === true) return true;
+        visited.add(node);
+        node = node._superData;
+      }
+      return false;
+    });
+  }
+
   // ---------------------------------------------------------------------------
   // dataType
   // ---------------------------------------------------------------------------
@@ -383,21 +409,25 @@ export abstract class MetaData {
 
   /** Own children whose type matches — excludes inherited. */
   ownChildrenOfType(type: string): MetaData[] {
+    // ADR-0039: own-accessor definition — delegates to ownChildren() by contract.
     return this.ownChildren().filter((c) => c.type === type);
   }
 
   /** Own children matching both type and subType — excludes inherited. */
   ownChildrenOfSubType(type: string, subType: string): MetaData[] {
+    // ADR-0039: own-accessor definition — delegates to ownChildren() by contract.
     return this.ownChildren().filter((c) => c.type === type && c.subType === subType);
   }
 
   /** First own child with matching name, or undefined — excludes inherited. */
   ownChildByName(name: string): MetaData | undefined {
+    // ADR-0039: own-accessor definition — delegates to ownChildren() by contract.
     return this.ownChildren().find((c) => c.name === name);
   }
 
   /** First own child matching both type and name, or undefined — excludes inherited. */
   ownChildByTypeAndName(type: string, name: string): MetaData | undefined {
+    // ADR-0039: own-accessor definition — delegates to ownChildren() by contract.
     return this.ownChildren().find((c) => c.type === type && c.name === name);
   }
 

package/src/shared/meta-root.ts

@@ -12,6 +12,8 @@ export class MetaRoot extends MetaData {
   /** Object entities defined at this root level. */
   objects(): MetaObject[] {
     return this.cached("objects", () =>
+      // ADR-0039: own — the metadata root has no super chain (it never `extends`),
+      // so own children ARE its effective children.
       this.ownChildren().filter((c): c is MetaObject => c.type === TYPE_OBJECT),
     );
   }
@@ -19,6 +21,7 @@ export class MetaRoot extends MetaData {
   /** Abstract / package-level fields defined at root (rare; e.g. shared id fields). */
   fields(): MetaField[] {
     return this.cached("fields", () =>
+      // ADR-0039: own — the metadata root has no super chain (it never `extends`).
       this.ownChildren().filter((c): c is MetaField => c.type === TYPE_FIELD),
     );
   }
@@ -26,6 +29,7 @@ export class MetaRoot extends MetaData {
   /** Find an object by name. */
   findObject(name: string): MetaObject | undefined {
     return this.cached(`findObject:${name}`, () => {
+      // ADR-0039: own — the metadata root has no super chain (it never `extends`).
       const child = this.ownChildByTypeAndName(TYPE_OBJECT, name);
       return child !== undefined ? (child as MetaObject) : undefined;
     });

package/src/subtype-rules.ts

@@ -78,6 +78,7 @@ function walk(model: MetaData, errors: ParseError[], warnings: string[]): void {
     }
   }
 
+  // ADR-0039: own — structural walk visiting every physical node once at its site.
   for (const child of model.ownChildren()) {
     walk(child, errors, warnings);
   }
@@ -151,9 +152,9 @@ function validateProjectionLicensing(
     );
   }
 
-  // OWN sources only: an inherited source is validated on the (projection)
-  // object that declares it; an inherited source from a non-projection super
-  // is unreachable without first tripping the extends rule above.
+  // ADR-0039: own — OWN sources only: an inherited source is validated on the
+  // (projection) object that declares it; an inherited source from a non-projection
+  // super is unreachable without first tripping the extends rule above.
   for (const child of model.ownChildren()) {
     if (child.type !== TYPE_SOURCE) continue;
     const kind =

package/src/super-resolve.ts

@@ -49,6 +49,8 @@ function findInTree(root: MetaData, fqn: string): MetaData | undefined {
   if (root.package === undefined && root.name !== "" && root.resolutionKey() === fqn) {
     return root;
   }
+  // ADR-0039: own — super-resolution walk over the PHYSICAL declaration tree;
+  // resolving accessors would be circular while the super chain is being wired.
   for (const child of root.ownChildren()) {
     const found = findInTree(child, fqn);
     if (found !== undefined) return found;
@@ -266,6 +268,7 @@ export function resolveDeferredSupers(root: MetaData): DeferredSuperFailure[] {
 
 function walk(node: MetaData, visit: (n: MetaData) => void): void {
   visit(node);
+  // ADR-0039: own — super-resolution walk over the PHYSICAL declaration tree.
   for (const child of node.ownChildren()) {
     walk(child, visit);
   }

package/src/validate-max-occurs.ts

@@ -16,6 +16,9 @@ export function validateMaxOccurs(root: MetaData, registry: TypeRegistry): Parse
 
 function walk(node: MetaData, registry: TypeRegistry, errors: ParseError[]): void {
   const counts = new Map<string, MetaData[]>();
+  // ADR-0039: own — maxOccurs constrains the AUTHORED declaration layer (how many
+  // children a node may DECLARE); inherited children were counted at their
+  // declaring parent, so only own children count against this node's limit.
   for (const child of node.ownChildren()) {
     const key = `${child.type}.${child.subType}`;
     const list = counts.get(key);
@@ -35,5 +38,7 @@ function walk(node: MetaData, registry: TypeRegistry, errors: ParseError[]): voi
       );
     }
   }
+  // ADR-0039: own — structural walk over the physical declaration tree (each
+  // declared node is visited once at its declaration site).
   for (const child of node.ownChildren()) walk(child, registry, errors);
 }