@metaobjectsdev/metadata 1.0.12 → 1.1.0

package/src/attr-schema-validate.ts

@@ -45,7 +45,7 @@ import type { MetaData } from "./shared/meta-data.js";
 import { ParseError } from "./errors.js";
 import type { AttrSchema, TypeRegistry } from "./registry.js";
 import { childRuleMatches } from "./registry.js";
-import { TYPE_FIELD, TYPE_METADATA } from "./shared/base-types.js";
+import { TYPE_FIELD } from "./shared/base-types.js";
 import { ATTR_SUBTYPE_PROPERTIES } from "./core/attr/attr-constants.js";
 // #337: turns "unknown X" into "retired in V — here is the migration". Changes no load
 // outcome; retired vocabulary still fails with the same code.
@@ -58,6 +58,7 @@ import {
   FIELD_ATTR_INT_VALUE_MAP,
   ENUM_MEMBER_PATTERN,
 } from "./core/field/field-constants.js";
+import { isSharedEnumDeclaration } from "./core/field/shared-enum.js";
 import {
   FIELD_ATTR_DB_COLUMN_TYPE,
   DB_COLUMN_TYPE_VALUES,
@@ -337,18 +338,13 @@ function validateNode(
   // only own @values need checking here (mirrors the own-attrs-only policy of
   // Checks 2+3 above — inherited attrs were validated on the declaring node).
   if (node.type === TYPE_FIELD && node.subType === FIELD_SUBTYPE_ENUM) {
-    // #246: the shared-enum super, if any — a root-level abstract field.enum (one
-    // whose parent is the metadata root, not an object). FR-019 materializes such a
-    // declaration ONCE per port as a single named type, so anything a consuming
-    // field re-declares that is part of the shared TYPE's contract is a conflict.
-    // Immediate-super-only, matching codegen's resolveSharedEnumDecl (enum-shared.ts)
-    // so the validator and the collapse agree on what "shared" means.
-    const sharedSuper =
-      node.superData !== undefined &&
-      node.superData.isAbstract &&
-      node.superData.parent?.type === TYPE_METADATA
-        ? node.superData
-        : undefined;
+    // #246: the shared-enum super, if any. FR-019 materializes a shared declaration
+    // ONCE per port as a single named type, so anything a field directly under it
+    // re-declares that is part of the shared TYPE's contract is a conflict. The
+    // predicate is the one codegen's resolver walks with (core/field/shared-enum.ts).
+    // Only the IMMEDIATE super is checked: a redeclaration further down the chain is
+    // legal, and the resolver answers it with a per-object inline type.
+    const sharedSuper = isSharedEnumDeclaration(node.superData) ? node.superData : undefined;
 
     // ADR-0039: own — validates the @values DECLARED on this node; a concrete enum
     // extending an abstract one inherits already-validated @values (own-attrs-only).

package/src/constants.ts

@@ -45,6 +45,7 @@ export * from "./core/index/index-constants.js";
 export * from "./core/object/object-constants.js";
 export * from "./core/query/query-constants.js";
 export * from "./core/relationship/relationship-constants.js";
+export * from "./core/reporting/reporting-constants.js";
 export * from "./core/validator/validator-constants.js";
 export * from "./persistence/db/db-constants.js";
 export * from "./persistence/origin/origin-constants.js";

package/src/core/attr/meta-attr-filter.ts

@@ -14,6 +14,7 @@ import {
   FILTER_COMPOSE_OR,
   FILTER_COMPOSE_AND,
 } from "../query/query-constants.js";
+import { FILTER_RELATIVE_NOW } from "../reporting/reporting-constants.js";
 import { registerAttrClass } from "../../attr-class-map.js";
 
 export class FilterAttr extends MetaAttr {
@@ -60,7 +61,13 @@ function desugarFilterObject(filter: AttrObject): AttrObject {
 function desugarClause(raw: AttrJson): AttrObject {
   if (raw === null) return { [FILTER_OP_IS_NULL]: true };
   if (Array.isArray(raw)) return { [FILTER_OP_IN]: raw };
-  if (typeof raw === "object") return raw as AttrObject;
+  // FR-044 F2: an object carrying a `now` key is a relative-date VALUE, never an
+  // op map (`now` is not an operator). Shorthand `{ f: { now: "-P7D" } }` therefore
+  // means `eq` like every other shorthand value, and survives as an opaque operand;
+  // validation then refuses it (`eq` is not a range op) instead of reading `now` as an op.
+  if (typeof raw === "object") {
+    return FILTER_RELATIVE_NOW in raw ? { [FILTER_OP_EQ]: raw } : (raw as AttrObject);
+  }
   return { [FILTER_OP_EQ]: raw };
 }
 

package/src/core/attr/meta-attr.ts

@@ -49,6 +49,22 @@ const BASE_ATTR_DATA_TYPE: Readonly<Record<string, DataType>> = {
 };
 
 export class MetaAttr extends MetaData implements DataTypeAware {
+  /**
+   * ADR-0059 R5 — for a reference attribute, the top-level object each reference
+   * names, set once by the loader's `resolveReferences` pass. A scalar value holds
+   * one node; a list value holds one entry per element (`undefined` where that
+   * element did not resolve). Unset when the attr is not a reference or did not
+   * resolve.
+   */
+  resolvedTarget?: MetaData | readonly (MetaData | undefined)[];
+
+  /**
+   * ADR-0059 R5 — the value exactly as authored, kept when `resolveReferences`
+   * rewrites `value` to its canonical spelling. `meta fmt` writes this back
+   * (`refs: "authored"`). Unset when the value was never rewritten.
+   */
+  authoredValue?: AttrValue;
+
   /** This attribute's coerced value (stored on the instance under RESERVED_KEY_VALUE). */
   get value(): AttrValue | undefined {
     // ADR-0039: own — an attr node's own scalar payload (the RESERVED_KEY_VALUE
@@ -95,7 +111,14 @@ export class MetaAttr extends MetaData implements DataTypeAware {
     if (dt === DATA_TYPE_STRING) {
       return typeof value === "string" ? [] : [this._typeError("string", value)];
     }
-    if (dt === DATA_TYPE_INT || dt === DATA_TYPE_LONG || dt === DATA_TYPE_DOUBLE) {
+    if (dt === DATA_TYPE_INT || dt === DATA_TYPE_LONG) {
+      if (typeof value !== "number") return [this._typeError("number", value)];
+      // Rule A: an integral number (4, 4.0, 1e2) is an int; a fraction is not.
+      return Number.isInteger(value)
+        ? []
+        : [{ message: `attribute '@${this.name}' must be of type '${this.subType}' but got the fraction ${value}; this attribute is integral, so write an integer (for a validator @min/@max, use an integer bound)` }];
+    }
+    if (dt === DATA_TYPE_DOUBLE) {
       return typeof value === "number" ? [] : [this._typeError("number", value)];
     }
     if (dt === DATA_TYPE_BOOLEAN) {

package/src/core/field/shared-enum.ts

@@ -0,0 +1,53 @@
+// Shared enum declarations — the single authority for "which type does this enum
+// field have" (FR-019, ADR-0026 Amendment 1). The loader's #246 check and every
+// codegen site that names, references, imports or materializes an enum type call
+// these two functions; neither keeps a predicate of its own.
+
+import { TYPE_FIELD, TYPE_METADATA } from "../../shared/base-types.js";
+import type { MetaData } from "../../shared/meta-data.js";
+import { FIELD_ATTR_INT_VALUE_MAP, FIELD_ATTR_VALUES, FIELD_SUBTYPE_ENUM } from "./field-constants.js";
+import type { MetaField } from "./meta-field.js";
+
+function isEnumField(node: MetaData | undefined): node is MetaField {
+  return node !== undefined && node.type === TYPE_FIELD && node.subType === FIELD_SUBTYPE_ENUM;
+}
+
+/**
+ * True when `node` is a shared enum declaration: an abstract `field.enum` that is a
+ * direct child of the metadata root (a package-level sibling of `object.entity`). An
+ * abstract enum nested inside an object is not one.
+ */
+export function isSharedEnumDeclaration(node: MetaData | undefined): node is MetaField {
+  return isEnumField(node) && isRootAbstract(node);
+}
+
+function isRootAbstract(field: MetaField): boolean {
+  return field.isAbstract && field.parent?.type === TYPE_METADATA;
+}
+
+/**
+ * The shared enum declaration an enum field's type resolves to, or undefined when the
+ * field keeps a per-object inline type.
+ *
+ * Walks from the field itself up its `extends` chain. At each node, in order: a shared
+ * declaration answers (the nearest one wins, so `Money extends Currency` answers
+ * `Money`); a node that declares its own `@values` or `@intValueMap` starts a new
+ * vocabulary and answers undefined; otherwise the walk continues at the super. A
+ * non-enum node, the end of the chain or a cycle answers undefined. The hosting
+ * object's subtype and the number of hops play no part.
+ */
+export function resolveSharedEnumDeclaration(field: MetaData | undefined): MetaField | undefined {
+  const seen = new Set<MetaData>();
+  let node = field;
+  while (isEnumField(node) && !seen.has(node)) {
+    if (isRootAbstract(node)) return node;
+    // ADR-0039 own (declared-here layer): the question is whether THIS node redeclares
+    // the vocabulary. A resolving read would see the inherited @values on every hop and
+    // stop the walk at the first one.
+    const own = node.ownAttrs();
+    if (own.has(FIELD_ATTR_VALUES) || own.has(FIELD_ATTR_INT_VALUE_MAP)) return undefined;
+    seen.add(node);
+    node = node.superData;
+  }
+  return undefined;
+}

package/src/core/identity/meta-identity.ts

@@ -16,6 +16,9 @@ import {
   IDENTITY_REFERENCE_ATTR_ON_UPDATE,
 } from "./identity-constants.js";
 import type { MetaRoot } from "../../shared/meta-root.js";
+import type { MetaObject } from "../object/meta-object.js";
+import { TYPE_OBJECT } from "../../shared/base-types.js";
+import { refTarget } from "../../naming-refs.js";
 
 /** Strongly-typed identity generation strategies. */
 export type IdentityGeneration = "increment" | "uuid" | "assigned";
@@ -144,7 +147,7 @@ export class MetaReferenceIdentity extends MetaIdentity {
    * points at. Priority: explicit dotted-form `@references: "Entity.field"`
    * override → target entity's primary identity field → "id" fallback.
    *
-   * Returns undefined only if the target entity cannot be found in `root`.
+   * Returns undefined only if the target entity does not resolve.
    * Centralizes the FK-target resolution rule used by projection view DDL,
    * Drizzle schema emit, and migration schema comparison.
    */
@@ -152,17 +155,11 @@ export class MetaReferenceIdentity extends MetaIdentity {
     const explicit = this.targetFields[0];
     if (explicit !== undefined) return explicit;
 
-    const targetName = this.targetEntity;
-    if (targetName === undefined) return undefined;
-    // targetEntity may be package-qualified (FQN); findObject is keyed by bare
-    // name, so fall back to the bare suffix after the last "::". Mirrors the
-    // resolveTargetTable fix; without it a cross-package reference resolves no
-    // target and the PK column wrongly defaults to "id".
-    const targetObj = root.findObject(targetName)
-      ?? (targetName.includes("::")
-        ? root.findObject(targetName.slice(targetName.lastIndexOf("::") + 2))
-        : undefined);
-    if (!targetObj) return undefined;
+    // ADR-0059 R7: the target the loader bound for @references, else (a tree built
+    // without the loader) the value resolved from this reference's package.
+    const bound = refTarget(this, IDENTITY_REFERENCE_ATTR_REFERENCES);
+    if (bound === undefined || bound.type !== TYPE_OBJECT) return undefined;
+    const targetObj = bound as MetaObject;
 
     const primary = targetObj.primaryIdentity();
     // ADR-0039: resolving — the target's @fields may be inherited via extends.

package/src/core/index.ts

@@ -16,3 +16,8 @@ export { UriSource } from "../loader/sources/uri-source.js";
 export { parseYaml } from "./parser-yaml.js";
 export { loadAndExportJson } from "./export-json.js";
 export type { ExportResult } from "./export-json.js";
+
+// The `meta verify` field lint's structural pre-parse walk. Lives here, not on the
+// root entry, because it parses YAML.
+export { declaredDuplicateFields } from "../loader/declared-duplicate-fields.js";
+export type { DeclaredDuplicateField } from "../loader/declared-duplicate-fields.js";

package/src/core/object/object-constants.ts

@@ -14,12 +14,15 @@ import { SUBTYPE_BASE } from "../../shared/base-types.js";
 export const OBJECT_SUBTYPE_ENTITY = "entity";
 export const OBJECT_SUBTYPE_VALUE = "value";
 export const OBJECT_SUBTYPE_PROJECTION = "projection";
+//   - report : declared dimensions x measures of one entity, compiled to a read-only view (FR-044)
+export const OBJECT_SUBTYPE_REPORT = "report";
 
 export const OBJECT_SUBTYPES = [
   SUBTYPE_BASE,
   OBJECT_SUBTYPE_ENTITY,
   OBJECT_SUBTYPE_VALUE,
   OBJECT_SUBTYPE_PROJECTION,
+  OBJECT_SUBTYPE_REPORT,
 ] as const;
 export type ObjectSubType = (typeof OBJECT_SUBTYPES)[number];
 
@@ -49,3 +52,19 @@ export const OBJECT_ATTR_DISCRIMINATOR_VALUE = "discriminatorValue";
  *  but resolves against the projection's OWN declared fields rather than one
  *  aggregated entity. An aggregate-derived field is not addressable (fail-closed). */
 export const OBJECT_PROJECTION_ATTR_FILTER = "filter";
+
+// ---------------------------------------------------------------------------
+// FR-044 — object.report attrs
+// ---------------------------------------------------------------------------
+/** The object.entity whose rows the report aggregates. */
+export const OBJECT_REPORT_ATTR_FROM = "from";
+/** Dimension names of @from; a time dimension is written `name:grain`. */
+export const OBJECT_REPORT_ATTR_DIMENSIONS = "dimensions";
+/** Measure names of @from. */
+export const OBJECT_REPORT_ATTR_MEASURES = "measures";
+/** Optional segment of @from scoping the rows. */
+export const OBJECT_REPORT_ATTR_SEGMENT = "segment";
+/** Optional row scope over @from's fields (an attr.filter). */
+export const OBJECT_REPORT_ATTR_FILTER = "filter";
+/** Optional to-one path from @from to the entity whose rows supply the report's rows (R8). */
+export const OBJECT_REPORT_ATTR_SPINE = "spine";

package/src/core/object/object-definition.embedded.ts

@@ -80,6 +80,27 @@ export const OBJECT_DEFINITION: ProviderDefinition = {
           "min": 0,
           "max": null
         },
+        {
+          "type": "dimension",
+          "subType": "*",
+          "name": "*",
+          "min": 0,
+          "max": null
+        },
+        {
+          "type": "measure",
+          "subType": "*",
+          "name": "*",
+          "min": 0,
+          "max": null
+        },
+        {
+          "type": "segment",
+          "subType": "*",
+          "name": "*",
+          "min": 0,
+          "max": null
+        },
         {
           "type": "attr",
           "subType": "string",
@@ -132,6 +153,65 @@ export const OBJECT_DEFINITION: ProviderDefinition = {
           "description": "Optional row-scope predicate (a portable attr.filter object: eq/ne/gt/gte/lt/lte/like/in/isNull with and/or, desugared to { field: { op: value } } at parse time) selecting which rows the view returns — lowered to an outer SQL WHERE. Resolves against the projection's own declared fields; an aggregate-derived field is not addressable (fail-closed)."
         }
       ]
+    },
+    {
+      "type": "object",
+      "subType": "report",
+      "extendsBase": true,
+      "description": "A declared report (FR-044): a fixed combination of dimensions and measures of ONE entity (@from), compiled to a read-only view. One row per distinct dimension tuple; no dimensions means exactly one row. Fields are DERIVED, not declared: one per dimension (a time dimension's field is <dimension><Grain>, e.g. purchasedAtDay) and one per measure. Every measure must belong to @from (two fact tables are two reports). @filter and @segment scope rows before grouping and combine by AND. Read-only: no writes, no get-by-id.",
+      "whenToUse": "Dashboard totals, per-day series and per-group summaries that would otherwise be hand-written GROUP BY queries.",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "from",
+          "min": 1,
+          "max": 1,
+          "description": "The object.entity whose rows the report aggregates."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "dimensions",
+          "isArray": true,
+          "min": 0,
+          "max": 1,
+          "description": "Dimension names of @from; a time dimension is written 'name:grain'. Absent means one global row."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "measures",
+          "isArray": true,
+          "min": 1,
+          "max": 1,
+          "description": "Measure names of @from."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "segment",
+          "min": 0,
+          "max": 1,
+          "description": "Optional segment of @from scoping the rows."
+        },
+        {
+          "type": "attr",
+          "subType": "filter",
+          "name": "filter",
+          "min": 0,
+          "max": 1,
+          "description": "Optional row scope over @from's fields; may use relative-date values."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "spine",
+          "min": 0,
+          "max": 1,
+          "description": "Optional to-one path from @from to the entity whose rows supply the report's rows (e.g. 'Purchase.program'), written like a dimension's @via. With it the report has one row per distinct dimension tuple among THAT entity's rows, including the ones no row of @from refers to: a count there is 0 and any other measure is null unless it declares @default. Every listed dimension must be reached through this path. @segment and @filter still scope the rows of @from and never remove a row. A row of @from whose reference is null or matches nothing is in no row of the report."
+        }
+      ]
     }
   ]
 };

package/src/core/relationship/derive-m2m-fields.ts

@@ -44,7 +44,9 @@ import type { MetaRoot } from "../../shared/meta-root.js";
 import type { MetaRelationship } from "./meta-relationship.js";
 import type { MetaReferenceIdentity } from "../identity/meta-identity.js";
 import { stripPackage } from "../../naming.js";
-import { resolveObjectRef } from "../../naming-refs.js";
+import { refTarget } from "../../naming-refs.js";
+import { IDENTITY_REFERENCE_ATTR_REFERENCES } from "../identity/identity-constants.js";
+import { RELATIONSHIP_ATTR_OBJECT_REF, RELATIONSHIP_ATTR_THROUGH } from "./relationship-constants.js";
 import { TYPE_OBJECT } from "../../shared/base-types.js";
 import { PACKAGE_SEPARATOR } from "../../shared/structural.js";
 
@@ -69,37 +71,6 @@ function refFkField(ref: MetaReferenceIdentity): string | undefined {
   return ref.fields[0];
 }
 
-/**
- * The root entity a reference name denotes, or undefined — resolved by the ONE
- * matcher the loader uses (`resolveObjectRef`, ADR-0041/0042): a fully-qualified
- * name binds exactly on its resolution key, a bare name binds in the REFERRER's
- * package.
- *
- * This exists so the SUBJECT comparison below can be made on object IDENTITY.
- * A bare-name compare cannot tell `a::NodeBase` from `b::NodeBase`, which made a
- * genuine cross-package hetero M:N read as a self-join the moment the subject
- * set held two names — and the first-match-wins bare arm this used to carry
- * (Java's deferred #174) bound a bare name to whichever same-short-named entity
- * happened to load first, which is load-ORDER dependence, not a naming rule.
- */
-function findEntity(
-  root: MetaRoot,
-  name: string | undefined,
-  referrerPkg: string,
-): MetaObject | undefined {
-  if (name === undefined || name === "") return undefined;
-  // ADR-0041/0042 through the single resolveObjectRef matcher — an FQN resolves
-  // exactly on its resolution key, a BARE name resolves in the REFERRER's
-  // package. The bare arm used to be `objects().find(o => o.name === bare)`,
-  // which took whichever same-short-named entity loaded first: a bare
-  // `@objectRef: "Tag"` on an abstract base in package `base` bound to
-  // `acme::Tag` merely because the acme source was read first. Callers pass the
-  // referrer that owns the name they are resolving — the DECLARING entity for
-  // the relationship's own @objectRef, the JUNCTION for its references' —
-  // because those are different packages whenever a base is inherited across one.
-  return resolveObjectRef(root, name, referrerPkg).node as MetaObject | undefined;
-}
-
 /**
  * Derive the source/target junction FK fields for a M:N relationship.
  *
@@ -108,7 +79,7 @@ function findEntity(
  * @param source  the entity the caller is navigating from. Accepted alongside
  *                `rel.parent` as a name for the relationship's subject, and used
  *                as the declaring entity when `rel` has no entity parent.
- * @param root    the loaded model root (to find the junction entity)
+ * @param root    the loaded model root
  * @throws M2MDerivationError when the junction is missing/malformed or the
  *         self-join is ambiguous.
  */
@@ -134,9 +105,10 @@ export function deriveM2MFields(
       `relationship "${declaringEntity.name}.${rel.name}" is missing @through (required for M:N derivation)`,
     );
   }
-  // ADR-0041/0042 — resolve @through through the SAME matcher the loader uses
-  // (resolveObjectRef, via validation-passes' _findObject): an FQN resolves
-  // exactly on its resolution key, a bare name resolves package-locally.
+  // ADR-0059 R7 — @through, @objectRef and the junction's @references are read
+  // as bound targets (refTarget), each resolved in the package of the node that
+  // declares it, so an inherited reference keeps the meaning it had where it was
+  // written.
   //
   // This used to be `root.findObject(fqn)` with a fall back to the bare suffix
   // after the last "::". findObject is keyed by BARE name, so the FQN lookup
@@ -147,12 +119,7 @@ export function deriveM2MFields(
   // nowhere near the navigating entity. The pairing then failed, so a valid
   // cross-package M:N emitted no traversal route in TS and C# and failed the
   // build in Java, Kotlin and Python.
-  //
-  // Note findEntity() below was ALREADY FQN-exact for the same reason (see its
-  // doc comment). The two halves of one function disagreed about how a
-  // package-qualified name resolves; only the junction half was wrong.
-  const referrerPkg = declaringEntity.package ?? declaringEntity.fileDefaultPackage ?? "";
-  const junction = resolveObjectRef(root, throughName, referrerPkg).node as MetaObject | undefined;
+  const junction = refTarget(rel, RELATIONSHIP_ATTR_THROUGH) as MetaObject | undefined;
   if (junction === undefined) {
     throw new M2MDerivationError(
       `relationship "${declaringEntity.name}.${rel.name}" @through "${throughName}" does not resolve to an entity`,
@@ -202,16 +169,16 @@ export function deriveM2MFields(
     name !== undefined && subjectNames.includes(stripPackage(name));
 
   // The junction owns its references' @references names, so those resolve in the
-  // JUNCTION's package; the relationship's own @objectRef resolves in the
-  // DECLARING entity's. Under `extends` across packages these differ, and using
-  // one for both is what bound a bare @objectRef to the wrong same-named entity.
-  const junctionPkg = junction.package ?? junction.fileDefaultPackage ?? "";
+  // package of the node that declares them; the relationship's own @objectRef in
+  // the package of the node that declares it. Under `extends` across packages these
+  // differ, and using one for both is what bound a bare @objectRef to the wrong
+  // same-named entity.
   const refEntity = (r: MetaReferenceIdentity): MetaObject | undefined =>
-    findEntity(root, r.targetEntity, junctionPkg);
+    refTarget(r, IDENTITY_REFERENCE_ATTR_REFERENCES) as MetaObject | undefined;
 
   // Defensive bare fallback when @objectRef does not resolve — loader validation
   // normally guarantees it does. Same carve-out the Java reference makes.
-  const targetEntityNode = findEntity(root, targetName, referrerPkg);
+  const targetEntityNode = refTarget(rel, RELATIONSHIP_ATTR_OBJECT_REF) as MetaObject | undefined;
   const isSelfJoin = targetEntityNode !== undefined
     ? isSubject(targetEntityNode)
     : isSubjectName(targetName);

package/src/core/relationship/find-reference.ts

@@ -8,7 +8,8 @@
 
 import type { MetaObject } from "../object/meta-object.js";
 import type { MetaReferenceIdentity } from "../identity/meta-identity.js";
-import { stripPackage } from "../../naming.js";
+import { refTarget } from "../../naming-refs.js";
+import { IDENTITY_REFERENCE_ATTR_REFERENCES } from "../identity/identity-constants.js";
 
 export interface ReferenceLookup {
   /** The entity whose identity.reference points at `other`. */
@@ -39,7 +40,8 @@ export function findReferencesBetween(
   const found: ReferenceLookup[] = [];
   for (const [holder, other] of [[a, b], [b, a]] as const) {
     for (const ref of holder.referenceIdentities()) {
-      if (stripPackage(ref.targetEntity) === other.name) {
+      // ADR-0059 R7: compare the bound target, never a short name.
+      if (refTarget(ref, IDENTITY_REFERENCE_ATTR_REFERENCES) === other) {
         found.push({ holder, other, referenceIdentity: ref });
       }
     }

package/src/core/relationship/resolve-relationship-reference.ts

@@ -10,7 +10,9 @@
 
 import type { MetaObject } from "../object/meta-object.js";
 import type { MetaReferenceIdentity } from "../identity/meta-identity.js";
-import { stripPackage } from "../../naming.js";
+import type { MetaData } from "../../shared/meta-data.js";
+import { refTarget } from "../../naming-refs.js";
+import { IDENTITY_REFERENCE_ATTR_REFERENCES } from "../identity/identity-constants.js";
 
 /**
  * Trailing suffixes stripped from a CANDIDATE's name/FK field when building its
@@ -51,20 +53,20 @@ export function referencePairingKeys(ref: MetaReferenceIdentity): Set<string> {
 }
 
 /**
- * Every identity.reference on `holder` whose @references targets `targetEntity`.
- * Package-insensitive on both sides: @references and @objectRef may each be bare
- * or fully qualified.
+ * Every identity.reference on `holder` whose @references targets `targetEntity`: a
+ * reference matches when its @references is bound to that node (ADR-0059 R7: identity,
+ * never a short name). An unresolved target (undefined) matches nothing.
  */
 export function referenceCandidatesFor(
   holder: MetaObject,
-  targetEntity: string,
+  targetEntity: MetaData | undefined,
 ): MetaReferenceIdentity[] {
-  const target = stripPackage(targetEntity);
+  if (targetEntity === undefined) return [];
   // ADR-0039: resolving — referenceIdentities() honors references inherited via extends.
   return holder
     .referenceIdentities()
-    .filter((ref) => stripPackage(ref.targetEntity ?? "") === target)
-    .filter((ref) => refFkField(ref) !== undefined);
+    .filter((ref) => refFkField(ref) !== undefined)
+    .filter((ref) => refTarget(ref, IDENTITY_REFERENCE_ATTR_REFERENCES) === targetEntity);
 }
 
 /**
@@ -82,7 +84,7 @@ export function referenceCandidatesFor(
 export function resolveRelationshipReference(
   holder: MetaObject,
   relationshipName: string,
-  targetEntity: string,
+  targetEntity: MetaData | undefined,
   sourceRefField?: string,
 ): MetaReferenceIdentity | undefined {
   const candidates = referenceCandidatesFor(holder, targetEntity);

package/src/core/reporting/meta-dimension.ts

@@ -0,0 +1,41 @@
+// MetaDimension — concrete node class for type=dimension nodes (FR-044).
+//
+// Extends MetaData directly. Accessors are RESOLVING (ADR-0039): a dimension
+// declared on an abstract base entity is read through the same accessors as one
+// declared on the concrete entity.
+
+import { MetaData } from "../../shared/meta-data.js";
+import {
+  DIMENSION_SUBTYPE_TIME,
+  REPORTING_ATTR_GRAINS,
+  REPORTING_ATTR_OF,
+  REPORTING_ATTR_VIA,
+  TIME_GRAINS,
+  type TimeGrain,
+} from "./reporting-constants.js";
+
+export class MetaDimension extends MetaData {
+  /** True for `dimension.time` (grain truncation); false for `dimension.attribute`. */
+  isTime(): boolean {
+    return this.subType === DIMENSION_SUBTYPE_TIME;
+  }
+
+  /** Dotted `Entity.field` reference naming the grouped column. */
+  of(): string | undefined {
+    const v = this.attr(REPORTING_ATTR_OF);
+    return typeof v === "string" ? v : undefined;
+  }
+
+  /** Optional dotted to-one relationship path from the owning entity to the `@of` entity. */
+  via(): string | undefined {
+    const v = this.attr(REPORTING_ATTR_VIA);
+    return typeof v === "string" ? v : undefined;
+  }
+
+  /** The grains a `dimension.time` supports (empty for `dimension.attribute`). */
+  grains(): TimeGrain[] {
+    const v = this.attr(REPORTING_ATTR_GRAINS);
+    const items = Array.isArray(v) ? v : typeof v === "string" ? [v] : [];
+    return items.filter((g): g is TimeGrain => (TIME_GRAINS as readonly unknown[]).includes(g));
+  }
+}

package/src/core/reporting/meta-measure.ts

@@ -0,0 +1,75 @@
+// MetaMeasure — concrete node class for type=measure nodes (FR-044).
+//
+// Extends MetaData directly. Accessors are RESOLVING (ADR-0039).
+
+import { MetaData } from "../../shared/meta-data.js";
+import {
+  MEASURE_AGGS,
+  MEASURE_SUBTYPE_RATIO,
+  REPORTING_ATTR_AGG,
+  REPORTING_ATTR_DEFAULT,
+  REPORTING_ATTR_DENOMINATOR,
+  REPORTING_ATTR_DISTINCT,
+  REPORTING_ATTR_FILTER,
+  REPORTING_ATTR_NUMERATOR,
+  REPORTING_ATTR_OF,
+  REPORTING_ATTR_SEGMENT,
+  type MeasureAgg,
+} from "./reporting-constants.js";
+
+function optionalString(v: unknown): string | undefined {
+  return typeof v === "string" ? v : undefined;
+}
+
+export class MetaMeasure extends MetaData {
+  /** True for `measure.ratio`; false for `measure.aggregate`. */
+  isRatio(): boolean {
+    return this.subType === MEASURE_SUBTYPE_RATIO;
+  }
+
+  /** The aggregate function (`measure.aggregate` only). */
+  agg(): MeasureAgg | undefined {
+    const v = this.attr(REPORTING_ATTR_AGG);
+    return (MEASURE_AGGS as readonly unknown[]).includes(v) ? (v as MeasureAgg) : undefined;
+  }
+
+  /** True when `@distinct` is set (legal only with `@agg: count`). */
+  distinct(): boolean {
+    return this.attr(REPORTING_ATTR_DISTINCT) === true;
+  }
+
+  /** The `Entity.field` references in `@of`: a bare string is one column, a list is the tuple form. */
+  ofColumns(): string[] {
+    const v = this.attr(REPORTING_ATTR_OF);
+    if (Array.isArray(v)) return v.filter((x): x is string => typeof x === "string");
+    return typeof v === "string" ? [v] : [];
+  }
+
+  /** Name of a segment declared on the same entity; combines with `@filter` by AND. */
+  segmentName(): string | undefined {
+    return optionalString(this.attr(REPORTING_ATTR_SEGMENT));
+  }
+
+  /** The canonical row-scope filter, when one is declared. */
+  filter(): Record<string, unknown> | undefined {
+    const v = this.attr(REPORTING_ATTR_FILTER);
+    return typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : undefined;
+  }
+
+  /** `@default`: the integer this measure reads when it would otherwise be null (rule M7/M8
+   *  decide where it is legal). ADR-0039: resolving, so an inherited measure keeps it. */
+  defaultValue(): number | undefined {
+    const v = this.attr(REPORTING_ATTR_DEFAULT);
+    return typeof v === "number" && Number.isInteger(v) ? v : undefined;
+  }
+
+  /** Name of the `measure.aggregate` sibling used as the numerator (`measure.ratio` only). */
+  numerator(): string | undefined {
+    return optionalString(this.attr(REPORTING_ATTR_NUMERATOR));
+  }
+
+  /** Name of the `measure.aggregate` sibling used as the denominator (`measure.ratio` only). */
+  denominator(): string | undefined {
+    return optionalString(this.attr(REPORTING_ATTR_DENOMINATOR));
+  }
+}