@metaobjectsdev/metadata 1.0.13 → 1.1.0

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));
+  }
+}

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

@@ -0,0 +1,14 @@
+// MetaSegment — concrete node class for type=segment nodes (FR-044).
+//
+// Extends MetaData directly. Accessors are RESOLVING (ADR-0039).
+
+import { MetaData } from "../../shared/meta-data.js";
+import { REPORTING_ATTR_FILTER } from "./reporting-constants.js";
+
+export class MetaSegment extends MetaData {
+  /** The named row scope: a canonical attr.filter over the declaring entity's fields. */
+  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;
+  }
+}

package/src/core/reporting/report-accessors.ts

@@ -0,0 +1,73 @@
+// Free accessors over an `object.report` node (FR-044). Used by the Plan 2
+// lowering and by the loader's report validation, so the `name:grain` parse and
+// the derived-field-name rule have exactly one definition.
+
+import type { MetaData } from "../../shared/meta-data.js";
+import {
+  OBJECT_REPORT_ATTR_DIMENSIONS,
+  OBJECT_REPORT_ATTR_FROM,
+  OBJECT_REPORT_ATTR_MEASURES,
+  OBJECT_REPORT_ATTR_SPINE,
+} from "../object/object-constants.js";
+import { CHILD_REF_SEPARATOR } from "../../shared/structural.js";
+import { REPORT_DIMENSION_GRAIN_SEPARATOR } from "./reporting-constants.js";
+
+export interface ReportDimensionItem {
+  readonly name: string;
+  readonly grain?: string;
+}
+
+function stringList(v: unknown): string[] {
+  if (Array.isArray(v)) return v.filter((x): x is string => typeof x === "string");
+  return typeof v === "string" ? [v] : [];
+}
+
+/** The `@from` entity name of a report. */
+export function reportFrom(obj: MetaData): string | undefined {
+  const v = obj.attr(OBJECT_REPORT_ATTR_FROM);
+  return typeof v === "string" ? v : undefined;
+}
+
+/** `@spine`: the to-one path to the entity whose rows supply the report's rows. */
+export function reportSpine(obj: MetaData): string | undefined {
+  const v = obj.attr(OBJECT_REPORT_ATTR_SPINE);
+  return typeof v === "string" && v !== "" ? v : undefined;
+}
+
+/** The `@dimensions` items, each `name` or `name:grain`. */
+export function reportDimensionItems(obj: MetaData): ReportDimensionItem[] {
+  return stringList(obj.attr(OBJECT_REPORT_ATTR_DIMENSIONS)).map((raw) => {
+    const i = raw.indexOf(REPORT_DIMENSION_GRAIN_SEPARATOR);
+    return i === -1 ? { name: raw } : { name: raw.slice(0, i), grain: raw.slice(i + 1) };
+  });
+}
+
+/** The `@measures` items AS WRITTEN: each a bare measure `name`, or a dotted
+ *  `Entity.name` (loader rule R3). Use {@link reportMeasureItemName} for the measure name. */
+export function reportMeasureNames(obj: MetaData): string[] {
+  return stringList(obj.attr(OBJECT_REPORT_ATTR_MEASURES));
+}
+
+/**
+ * The measure a `@measures` item names: the segment after its LAST `.`
+ * (`total`, `Sale.total` and `acme::shop::Sale.total` all name `total`). It is also
+ * the derived report field's name. The part before that `.`, when present, is an
+ * entity qualifier, which {@link reportMeasureItemOwner} returns.
+ */
+export function reportMeasureItemName(item: string): string {
+  const dot = item.lastIndexOf(CHILD_REF_SEPARATOR);
+  return dot === -1 ? item : item.slice(dot + CHILD_REF_SEPARATOR.length);
+}
+
+/** The entity qualifier of a dotted `@measures` item (`Sale` in `Sale.total`), or
+ *  undefined for a bare item. Loader rule R3: it names `@from` or an entity `@from` extends. */
+export function reportMeasureItemOwner(item: string): string | undefined {
+  const dot = item.lastIndexOf(CHILD_REF_SEPARATOR);
+  return dot === -1 ? undefined : item.slice(0, dot);
+}
+
+/** The derived report field for a dimension item: `name` (attribute) or `name` + Capitalized(grain) (time). */
+export function reportDerivedFieldName(item: ReportDimensionItem): string {
+  if (item.grain === undefined || item.grain === "") return item.name;
+  return item.name + item.grain.charAt(0).toUpperCase() + item.grain.slice(1);
+}