@metaobjectsdev/metadata 1.0.13 → 1.1.1-rc.1

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

@@ -0,0 +1,493 @@
+// Table B of docs/superpowers/plans/2026-10-03-fr-044-plan-2-report-view-lowering.md:
+// a report's derived fields. The single definition; every port has a rule-for-rule copy,
+// gated by fixtures/persistence-conformance/report-shapes.json. `required` follows Table C
+// of docs/superpowers/plans/2026-10-09-fr-044-zero-rows-and-measure-defaults.md, which
+// amends Table B for a report with `@spine` and a measure with `@default`.
+
+import type { MetaData } from "../../shared/meta-data.js";
+import type { MetaRoot } from "../../shared/meta-root.js";
+import { isMetaObject } from "../../shared/node-guards.js";
+import { refTarget, resolveObjectRef } from "../../naming-refs.js";
+import { CHILD_REF_SEPARATOR, PACKAGE_SEPARATOR } from "../../shared/structural.js";
+import type { MetaObject } from "../object/meta-object.js";
+import type { MetaField } from "../field/meta-field.js";
+import {
+  FIELD_SUBTYPE_BOOLEAN,
+  FIELD_SUBTYPE_CURRENCY,
+  FIELD_SUBTYPE_DATE,
+  FIELD_SUBTYPE_DECIMAL,
+  FIELD_SUBTYPE_DOUBLE,
+  FIELD_SUBTYPE_FLOAT,
+  FIELD_SUBTYPE_INT,
+  FIELD_SUBTYPE_LONG,
+  FIELD_SUBTYPE_TIMESTAMP,
+} from "../field/field-constants.js";
+import { TYPE_IDENTITY, TYPE_RELATIONSHIP } from "../../shared/base-types.js";
+import type { MetaReferenceIdentity } from "../identity/meta-identity.js";
+import { IDENTITY_REFERENCE_ATTR_REFERENCES, IDENTITY_SUBTYPE_REFERENCE } from "../identity/identity-constants.js";
+import { RELATIONSHIP_ATTR_OBJECT_REF, RELATIONSHIP_ATTR_SOURCE_REF_FIELD } from "../relationship/relationship-constants.js";
+import { resolveRelationshipReference } from "../relationship/resolve-relationship-reference.js";
+import { MetaDimension } from "./meta-dimension.js";
+import { MetaMeasure } from "./meta-measure.js";
+import { identityEffectiveFields } from "../identity/validate-identity-passthrough.js";
+import {
+  reportDerivedFieldName,
+  reportDimensionItems,
+  reportFrom,
+  reportMeasureItemName,
+  reportMeasureItemOwner,
+  reportMeasureNames,
+  reportSpine,
+} from "./report-accessors.js";
+import { AGG_ALL, AGG_ANY } from "../../persistence/origin/origin-constants.js";
+import {
+  AGG_AVG,
+  AGG_COUNT,
+  AGG_SUM,
+  GRAIN_HOUR,
+  TIME_GRAINS,
+  TYPE_DIMENSION,
+  TYPE_MEASURE,
+  type TimeGrain,
+} from "./reporting-constants.js";
+
+export type ReportFieldRole = "dimension" | "measure";
+
+export interface ReportField {
+  readonly name: string;
+  readonly role: ReportFieldRole;
+  /** A field subtype name (FIELD_SUBTYPE_*). */
+  readonly subType: string;
+  readonly required: boolean;
+  /** The `@of` field whose type-shaping attrs this field carries (Table B). */
+  readonly typeSource?: MetaField;
+  readonly dimension?: MetaDimension;
+  readonly grain?: TimeGrain;
+  readonly measure?: MetaMeasure;
+}
+
+export interface ReportShape {
+  readonly report: MetaObject;
+  readonly from: MetaObject;
+  readonly fields: readonly ReportField[];
+}
+
+const SUM_LONG: ReadonlySet<string> = new Set([FIELD_SUBTYPE_INT, FIELD_SUBTYPE_LONG]);
+const FLOATING: ReadonlySet<string> = new Set([FIELD_SUBTYPE_DOUBLE, FIELD_SUBTYPE_FLOAT]);
+
+/** Effective package of a node, taken from its resolution key ("<pkg>::<Name>"). */
+function packageOfKey(key: string): string {
+  const i = key.lastIndexOf(PACKAGE_SEPARATOR);
+  return i >= 0 ? key.slice(0, i) : "";
+}
+
+/** True when `candidate` is `entity` or an entity it extends (the super chain). */
+function isSelfOrAncestor(candidate: MetaData, entity: MetaData): boolean {
+  const visited = new Set<MetaData>();
+  for (let n: MetaData | undefined = entity; n !== undefined && !visited.has(n); n = n.superData) {
+    if (n === candidate) return true;
+    visited.add(n);
+  }
+  return false;
+}
+
+/**
+ * The entity that DECLARES a dimension, measure or segment reached through `from`: the
+ * member's parent, which is `from` itself or an entity `from` extends. A bare entity name
+ * inside the member (`@of`, `@via`) resolves in THIS entity's package, exactly as the
+ * loader's `validateReporting` resolves it (`pkgOf(ctx.declaring)`), never in `from`'s
+ * package or the report's.
+ */
+export function reportingMemberOwner(member: MetaData, from: MetaObject): MetaData {
+  return member.parent ?? from;
+}
+
+/**
+ * Resolve a dimension's or measure's `Entity.field` reference to the field node. The ONE
+ * rule, the same as the loader's (`validateReporting` D1 / M1):
+ *
+ *  1. The entity half resolves relative to the package of `declaring`, the entity that
+ *     declares the member ({@link reportingMemberOwner}).
+ *  2. With `host` (a measure, or a dimension without `@via`: the reference is about the
+ *     `@from` entity's own rows) the named entity must be `host` or an entity it extends,
+ *     and the field is read from `host`, so a field `host` redeclares wins.
+ *  3. Without `host` the field is read from the named entity. A dimension with `@via` passes
+ *     the entity its `@via` reaches as both `declaring` and `host`
+ *     ({@link resolveDimensionOf}).
+ *
+ * Undefined when any step fails.
+ */
+export function resolveReportingFieldRef(
+  ref: string,
+  declaring: MetaData,
+  root: MetaRoot,
+  host?: MetaObject,
+): MetaField | undefined {
+  return resolveReportingFieldRefNamed(ref, declaring, root, host)?.field;
+}
+
+/**
+ * A dimension's `@of` field, read as the loader's rule D1 reads it. Without `@via` it is
+ * {@link resolveReportingFieldRef} with `from` as the host. With `@via` the host is the
+ * entity the `@via` reaches, and a bare entity name in `@of` resolves in THAT entity's
+ * package: the path already fixes the entity, so `Realm.name` after a hop onto
+ * `world::Realm` names `world::Realm`. The field is read from the reached entity, so a field
+ * it redeclares wins. Undefined when the `@via` or the `@of` does not resolve.
+ */
+export function resolveDimensionOf(
+  dim: MetaDimension,
+  from: MetaObject,
+  root: MetaRoot,
+): { readonly named: MetaObject; readonly field: MetaField } | undefined {
+  const of = dim.of() ?? "";
+  const via = dim.via();
+  if (via === undefined) return resolveReportingFieldRefNamed(of, reportingMemberOwner(dim, from), root, from);
+  const terminal = reportingViaTerminal(via, reportingMemberOwner(dim, from), from, root);
+  if (terminal === undefined) return undefined;
+  return resolveReportingFieldRefNamed(of, terminal, root, terminal);
+}
+
+/**
+ * The entity at the end of a `@via` walked from `from` (hops as {@link reportingViaHops}
+ * reads them, each target as {@link resolveViaHop} resolves it). Undefined when any hop does
+ * not resolve.
+ */
+function reportingViaTerminal(
+  via: string,
+  declaring: MetaData,
+  from: MetaObject,
+  root: MetaRoot,
+): MetaObject | undefined {
+  const hops = reportingViaHops(via, declaring, from, root);
+  if (hops === undefined) return undefined;
+  let current: MetaObject = from;
+  for (const hop of hops) {
+    const target = resolveViaHop(current, hop)?.target;
+    if (target === undefined) return undefined;
+    current = target;
+  }
+  return current;
+}
+
+/**
+ * {@link resolveReportingFieldRef}, also returning `named`: the entity the reference's
+ * entity half names (which, with `host`, may be an ancestor of the entity `field` is read
+ * from). Table C reads `named`'s primary identity.
+ */
+function resolveReportingFieldRefNamed(
+  ref: string,
+  declaring: MetaData,
+  root: MetaRoot,
+  host?: MetaObject,
+): { readonly named: MetaObject; readonly field: MetaField } | undefined {
+  // `Entity.field`; a package qualifier uses `::`, so the member separator is the LAST dot.
+  const dot = ref.lastIndexOf(CHILD_REF_SEPARATOR);
+  if (dot <= 0) return undefined;
+  const named = resolveObjectRef(root, ref.slice(0, dot), packageOfKey(declaring.resolutionKey())).node;
+  if (!isMetaObject(named)) return undefined;
+  if (host !== undefined && !isSelfOrAncestor(named, host)) return undefined;
+  // ADR-0039: resolving, so a field inherited through extends is found.
+  const field = (host ?? named).fields().find((f) => f.name === ref.slice(dot + 1));
+  return field === undefined ? undefined : { named, field };
+}
+
+/**
+ * The hop names of a dimension's `@via` (`Owner.hop[.hop...]`), read as the loader reads it
+ * (`validateReporting` rule D2): `Owner` resolves in the package of `declaring`
+ * ({@link reportingMemberOwner}) and must be `from` or an entity `from` extends. The walk
+ * itself then starts AT `from`, whichever of the two `Owner` named. Undefined when the
+ * reference has no owner, no hop, or an owner that is not `from` or an ancestor of it.
+ */
+export function reportingViaHops(
+  via: string,
+  declaring: MetaData,
+  from: MetaObject,
+  root: MetaRoot,
+): string[] | undefined {
+  // The owner ends at the first `.` after the last `::` (a package qualifier has no `.`).
+  const lastSep = via.lastIndexOf(PACKAGE_SEPARATOR);
+  const segStart = lastSep === -1 ? 0 : lastSep + PACKAGE_SEPARATOR.length;
+  const dot = via.indexOf(CHILD_REF_SEPARATOR, segStart);
+  if (dot <= segStart) return undefined;
+  const hops = via.slice(dot + CHILD_REF_SEPARATOR.length).split(CHILD_REF_SEPARATOR);
+  if (hops.some((h) => h === "")) return undefined;
+  const owner = resolveObjectRef(root, via.slice(0, dot), packageOfKey(declaring.resolutionKey())).node;
+  if (owner === undefined || !isSelfOrAncestor(owner, from)) return undefined;
+  return hops;
+}
+
+function unresolved(reportName: string, what: string): Error {
+  return new Error(`report '${reportName}': ${what} does not resolve.`);
+}
+
+/**
+ * The hop names of a report's `@spine` (`Owner.hop[.hop...]`), read as
+ * {@link reportingViaHops} reads a `@via`, the owner resolving in `from`'s package (loader
+ * rule R8): Owner must be `from` or an entity it extends, so a bare name means `from`'s
+ * package even when the report lives in another one. Undefined when the report declares no `@spine`. Throws a plain Error
+ * naming the report when a declared `@spine` does not resolve (a report that passed
+ * `validateReporting` always resolves): reading it as "no spine" would claim a column
+ * non-null that a spine row with no facts leaves null.
+ */
+export function reportSpineHops(report: MetaObject, from: MetaObject, root: MetaRoot): string[] | undefined {
+  const spine = reportSpine(report);
+  if (spine === undefined) return undefined;
+  const hops = reportingViaHops(spine, from, from, root);
+  if (hops === undefined) throw unresolved(report.name, `@spine '${spine}'`);
+  return hops;
+}
+
+/**
+ * One hop of a `@via`/`@spine` path, as the loader's rule R8 walks it: the `relationship.*`
+ * (read through its `@objectRef`) or `identity.reference` (through its `@references`) of
+ * `current` named `hopName`, with its target resolved in the package of the node that declares
+ * the hop's reference attribute (ADR-0059 R3). Returns
+ * `target: undefined` for an unresolvable hop or a ref attr that is not a string / does not
+ * reach a metadata object.
+ * ADR-0039: resolving children(), so a hop inherited through extends is found.
+ */
+function resolveViaHop(
+  current: MetaObject,
+  hopName: string,
+): { hop: MetaData; isReference: boolean; target: MetaObject | undefined } | undefined {
+  const rel = current.children().find((c) => c.type === TYPE_RELATIONSHIP && c.name === hopName);
+  const refNode = rel !== undefined
+    ? undefined
+    : current.children().find(
+        (c) => c.type === TYPE_IDENTITY && c.subType === IDENTITY_SUBTYPE_REFERENCE && c.name === hopName,
+      );
+  const hop = rel ?? refNode;
+  if (hop === undefined) return undefined;
+  const isReference = rel === undefined;
+  const node = refTarget(hop, isReference ? IDENTITY_REFERENCE_ATTR_REFERENCES : RELATIONSHIP_ATTR_OBJECT_REF);
+  return { hop, isReference, target: isMetaObject(node) ? node : undefined };
+}
+
+/**
+ * The spine entity: the object at the end of a report's `@spine`, whose rows are the
+ * report's rows. Walked hop by hop from `from` as the loader's rule R8 walks it via
+ * {@link resolveViaHop}; an unresolved hop throws, as {@link reportSpineHops} does (a report
+ * that passed `validateReporting` always resolves). Undefined when the report declares no
+ * `@spine`.
+ */
+export function reportSpineEntity(report: MetaObject, from: MetaObject, root: MetaRoot): MetaObject | undefined {
+  const hops = reportSpineHops(report, from, root);
+  if (hops === undefined) return undefined;
+  let current: MetaObject = from;
+  for (const hop of hops) {
+    const target = resolveViaHop(current, hop)?.target;
+    if (target === undefined) throw unresolved(report.name, `@spine '${reportSpine(report) ?? ""}' hop '${hop}'`);
+    current = target;
+  }
+  return current;
+}
+
+/** True when `field` is one of the `@fields` of `entity`'s `identity.primary`. */
+function isPrimaryKeyField(entity: MetaObject, field: MetaField): boolean {
+  // ADR-0039: resolving — an identity.primary (and its @fields) inherited from an
+  // abstract base counts.
+  const pk = entity.primaryIdentity();
+  return pk !== undefined && (identityEffectiveFields(pk) ?? []).includes(field.name);
+}
+
+function declaredMember<T extends MetaData>(
+  from: MetaObject,
+  type: string,
+  name: string,
+  cls: new (...args: never[]) => T,
+): T | undefined {
+  // ADR-0039: resolving children(), so a member declared on an abstract base is found.
+  return from.children().find((c): c is T => c.type === type && c.name === name && c instanceof cls);
+}
+
+function isTimeGrain(grain: string | undefined): grain is TimeGrain {
+  return grain !== undefined && (TIME_GRAINS as readonly string[]).includes(grain);
+}
+
+/**
+ * True when every hop of `hops`, walked from `from`, is a belongs-to hop over a required
+ * foreign key: the hops the view joins INNER, so every row of the report has a match. This
+ * is the join-type rule of the view lowering (codegen-ts `walkViaPath`, #209): the reference
+ * is held by the entity the hop leaves, its first FK field is required, and every earlier hop
+ * is INNER too. `@enforce: false` does not change it. A hop that does not resolve, an
+ * ambiguous reference or a has-many hop is not INNER.
+ */
+function viaJoinsInner(hops: readonly string[], from: MetaObject, root: MetaRoot): boolean {
+  let current = from;
+  for (const hopName of hops) {
+    const resolved = resolveViaHop(current, hopName);
+    if (resolved === undefined || resolved.target === undefined) return false;
+    const { hop, isReference, target } = resolved;
+
+    // The reference the hop crosses, as the lowering resolves it. A has-many hop, whose FK
+    // sits on the child, matches none of the current entity's own references.
+    let reference: MetaReferenceIdentity | undefined;
+    if (isReference) {
+      reference = hop as unknown as MetaReferenceIdentity;
+    } else {
+      const sourceRefField = hop.attr(RELATIONSHIP_ATTR_SOURCE_REF_FIELD);
+      reference = resolveRelationshipReference(
+        current, hopName, target, typeof sourceRefField === "string" ? sourceRefField : undefined,
+      );
+    }
+    if (reference === undefined) return false;
+    const fkName = reference.fields[0];
+    const fk = fkName === undefined ? undefined : current.findField(fkName);
+    if (fk === undefined || !fk.isRequired) return false;
+    current = target;
+  }
+  return true;
+}
+
+/**
+ * Table C (`required` of a dimension). Without `@spine`: only a dimension over an `@of` field
+ * that is effectively required (`@required`, or a `validator.required` child), and, when it has a `@via`, only when every hop is a
+ * required belongs-to reference, the hops the view joins INNER ({@link viaJoinsInner}). With `@spine`: only a dimension
+ * whose `@via` hops equal the spine's (a column of the spine entity itself, whose rows are
+ * the report's rows) over an `@of` field that is `@required` or a primary-key column of the
+ * entity `@of` names. A dimension beyond the spine is reached by a LEFT OUTER join.
+ */
+function dimensionRequired(
+  dim: MetaDimension,
+  named: MetaObject,
+  of: MetaField,
+  from: MetaObject,
+  root: MetaRoot,
+  spine: readonly string[] | undefined,
+  reportName: string,
+): boolean {
+  const via = dim.via();
+  if (spine === undefined) {
+    if (via === undefined) return of.isRequired;
+    if (!of.isRequired) return false;
+    const hops = reportingViaHops(via, reportingMemberOwner(dim, from), from, root);
+    if (hops === undefined) throw unresolved(reportName, `dimension '${dim.name}' @via '${via}'`);
+    return viaJoinsInner(hops, from, root);
+  }
+  if (via === undefined) return false; // a column of @from: null in a spine row with no facts
+  const hops = reportingViaHops(via, reportingMemberOwner(dim, from), from, root);
+  if (hops === undefined) throw unresolved(reportName, `dimension '${dim.name}' @via '${via}'`);
+  const onSpine = hops.length === spine.length && hops.every((h, i) => h === spine[i]);
+  return onSpine && (of.isRequired || isPrimaryKeyField(named, of));
+}
+
+function dimensionField(
+  item: { name: string; grain?: string },
+  from: MetaObject,
+  root: MetaRoot,
+  reportName: string,
+  spine: readonly string[] | undefined,
+): ReportField {
+  const dim = declaredMember(from, TYPE_DIMENSION, item.name, MetaDimension);
+  if (dim === undefined) throw unresolved(reportName, `dimension '${item.name}' on '${from.name}'`);
+  const via = dim.via();
+  // A @via that does not walk is the @via's error, not the @of's (the @of resolves at its end).
+  if (via !== undefined && reportingViaTerminal(via, reportingMemberOwner(dim, from), from, root) === undefined) {
+    throw unresolved(reportName, `dimension '${dim.name}' @via '${via}'`);
+  }
+  const ref = resolveDimensionOf(dim, from, root);
+  if (ref === undefined) throw unresolved(reportName, `dimension '${item.name}' @of`);
+  const of = ref.field;
+  const name = reportDerivedFieldName(item);
+  const required = dimensionRequired(dim, ref.named, of, from, root, spine, reportName);
+  if (dim.isTime()) {
+    // Loader rule R2 guarantees a grain from the closed set; a tree built in code does not.
+    const grain = item.grain;
+    if (!isTimeGrain(grain)) throw unresolved(reportName, `time dimension '${item.name}' grain '${grain ?? ""}'`);
+    if (grain === GRAIN_HOUR) {
+      return { name, role: "dimension", subType: FIELD_SUBTYPE_TIMESTAMP, required, typeSource: of, dimension: dim, grain };
+    }
+    return { name, role: "dimension", subType: FIELD_SUBTYPE_DATE, required, dimension: dim, grain };
+  }
+  return { name, role: "dimension", subType: of.subType, required, typeSource: of, dimension: dim };
+}
+
+/**
+ * One `@measures` item, bare (`total`) or dotted (`Sale.total`, loader rule R3). The measure
+ * is named by the item's last segment and looked up on `from`; a qualifier resolves in the
+ * REPORT's package and must be `from` or an entity `from` extends.
+ */
+function measureField(item: string, report: MetaObject, from: MetaObject, root: MetaRoot): ReportField {
+  const reportName = report.name;
+  const name = reportMeasureItemName(item);
+  const qualifier = reportMeasureItemOwner(item);
+  if (qualifier !== undefined) {
+    const owner = resolveObjectRef(root, qualifier, packageOfKey(report.resolutionKey())).node;
+    if (owner === undefined || !isSelfOrAncestor(owner, from)) {
+      throw unresolved(reportName, `measure '${item}' on '${from.name}'`);
+    }
+  }
+  const m = declaredMember(from, TYPE_MEASURE, name, MetaMeasure);
+  if (m === undefined) throw unresolved(reportName, `measure '${item}' on '${from.name}'`);
+  const derived = deriveMeasure(m, from, root);
+  if (derived === undefined) throw unresolved(reportName, `measure '${name}' @of`);
+  // Table C: a count is never null; any other measure is not null when it has a @default.
+  const required = (!m.isRatio() && m.agg() === AGG_COUNT) || m.defaultValue() !== undefined;
+  const { subType, typeSource } = derived;
+  // The key set (no `typeSource` key when there is none) and its order are as before.
+  return typeSource === undefined
+    ? { name, role: "measure", subType, required, measure: m }
+    : { name, role: "measure", subType, required, typeSource, measure: m };
+}
+
+/** One measure's Table B subtype, and the `@of` field it carries type attrs from (if any). */
+interface MeasureDerivation {
+  readonly subType: string;
+  readonly typeSource?: MetaField;
+}
+
+/** Table B for one measure. Undefined when its `@of` does not resolve. */
+function deriveMeasure(m: MetaMeasure, from: MetaObject, root: MetaRoot): MeasureDerivation | undefined {
+  if (m.isRatio()) return { subType: FIELD_SUBTYPE_DECIMAL };
+  const agg = m.agg();
+  if (agg === AGG_COUNT) return { subType: FIELD_SUBTYPE_LONG };
+  // any / all are boolean whatever the source (the loader's M4 refuses a non-boolean @of).
+  if (agg === AGG_ANY || agg === AGG_ALL) return { subType: FIELD_SUBTYPE_BOOLEAN };
+  const of = resolveReportingFieldRef(m.ofColumns()[0] ?? "", reportingMemberOwner(m, from), root, from);
+  if (of === undefined) return undefined;
+  const src = of.subType;
+  if (agg === AGG_SUM) {
+    if (src === FIELD_SUBTYPE_CURRENCY) return { subType: FIELD_SUBTYPE_CURRENCY, typeSource: of };
+    return {
+      subType: SUM_LONG.has(src) ? FIELD_SUBTYPE_LONG : FLOATING.has(src) ? FIELD_SUBTYPE_DOUBLE : FIELD_SUBTYPE_DECIMAL,
+    };
+  }
+  if (agg === AGG_AVG) return { subType: FLOATING.has(src) ? FIELD_SUBTYPE_DOUBLE : FIELD_SUBTYPE_DECIMAL };
+  // min / max keep the source field's type.
+  return { subType: src, typeSource: of };
+}
+
+/**
+ * Table B's subtype for one measure of `from`, whether or not a report lists it (a
+ * ratio's operands are measures a report need not list). The same rule `reportShape`
+ * applies to a listed measure. Undefined when its `@of` does not resolve, which the
+ * loader (rule M6) reads before the model is known to be valid.
+ */
+export function measureResultSubType(measure: MetaMeasure, from: MetaObject, root: MetaRoot): string | undefined {
+  return deriveMeasure(measure, from, root)?.subType;
+}
+
+/**
+ * {@link measureResultSubType} for a model that passed `validateReporting`. Throws a plain
+ * Error naming the measure when its `@of` does not resolve (a valid measure always resolves).
+ */
+export function measureDerivedSubType(measure: MetaMeasure, from: MetaObject, root: MetaRoot): string {
+  const subType = measureResultSubType(measure, from, root);
+  if (subType === undefined) throw new Error(`measure '${measure.name}' on '${from.name}': @of does not resolve.`);
+  return subType;
+}
+
+/** Table B, with Table C's `required`. Throws a plain Error naming the report when a
+ *  reference does not resolve (a report that passed `validateReporting` always resolves). */
+export function reportShape(report: MetaObject, root: MetaRoot): ReportShape {
+  const fromName = reportFrom(report);
+  if (fromName === undefined) throw unresolved(report.name, "@from");
+  const from = resolveObjectRef(root, fromName, packageOfKey(report.resolutionKey())).node;
+  if (!isMetaObject(from)) throw unresolved(report.name, `@from '${fromName}'`);
+  const spine = reportSpineHops(report, from, root);
+  const fields = [
+    ...reportDimensionItems(report).map((item) => dimensionField(item, from, root, report.name, spine)),
+    ...reportMeasureNames(report).map((item) => measureField(item, report, from, root)),
+  ];
+  return { report, from, fields };
+}

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

@@ -0,0 +1,104 @@
+// Reporting concern constants (FR-044) — type names, subtypes, attr keys and
+// the closed sets the registry enforces through `allowedValues`.
+//
+// `dimension`, `measure` and `segment` are children of `object.entity` only
+// (never root-level), and `object.report` (see object-constants.ts) references
+// them by name. The type-name constants live in shared/base-types.ts beside
+// every other base type and are re-exported here so a reporting consumer has
+// one import site.
+
+import { AGG_ALL, AGG_ANY } from "../../persistence/origin/origin-constants.js";
+import { TYPE_DIMENSION, TYPE_MEASURE, TYPE_SEGMENT } from "../../shared/base-types.js";
+
+export { TYPE_DIMENSION, TYPE_MEASURE, TYPE_SEGMENT };
+
+// ---------------------------------------------------------------------------
+// Subtypes
+// ---------------------------------------------------------------------------
+
+/** Groups by a column value as-is (no grain, no truncation). */
+export const DIMENSION_SUBTYPE_ATTRIBUTE = "attribute";
+/** Groups by a date/timestamp column truncated to a grain. */
+export const DIMENSION_SUBTYPE_TIME = "time";
+export const DIMENSION_SUBTYPES = [DIMENSION_SUBTYPE_ATTRIBUTE, DIMENSION_SUBTYPE_TIME] as const;
+export type DimensionSubType = (typeof DIMENSION_SUBTYPES)[number];
+
+/** One aggregate over the declaring entity's own rows. */
+export const MEASURE_SUBTYPE_AGGREGATE = "aggregate";
+/** A quotient of two `measure.aggregate` siblings, `numerator / NULLIF(denominator, 0)`.
+ *  `measure.derived` is deliberately NOT registered: it waits for FR-037 R5. */
+export const MEASURE_SUBTYPE_RATIO = "ratio";
+export const MEASURE_SUBTYPES = [MEASURE_SUBTYPE_AGGREGATE, MEASURE_SUBTYPE_RATIO] as const;
+export type MeasureSubType = (typeof MEASURE_SUBTYPES)[number];
+
+/** A named, reusable row filter. The only concrete segment subtype: every `*.base`
+ *  in the registry is an abstract anchor, so authors write `segment.filter`. */
+export const SEGMENT_SUBTYPE_FILTER = "filter";
+export const SEGMENT_SUBTYPES = [SEGMENT_SUBTYPE_FILTER] as const;
+export type SegmentSubType = (typeof SEGMENT_SUBTYPES)[number];
+
+// ---------------------------------------------------------------------------
+// Attrs (on dimension / measure / segment nodes)
+// ---------------------------------------------------------------------------
+
+/** Dotted `Entity.field` reference(s) naming the grouped / aggregated column(s). */
+export const REPORTING_ATTR_OF = "of";
+/** Optional dotted to-one relationship path from the owning entity to the `@of` entity. */
+export const REPORTING_ATTR_VIA = "via";
+/** The grains a `dimension.time` supports. */
+export const REPORTING_ATTR_GRAINS = "grains";
+/** The aggregate function of a `measure.aggregate`. */
+export const REPORTING_ATTR_AGG = "agg";
+/** Count distinct values (legal only with `@agg: count`). */
+export const REPORTING_ATTR_DISTINCT = "distinct";
+/** Row scope (an attr.filter) on a `measure.aggregate` or `segment.filter`. */
+export const REPORTING_ATTR_FILTER = "filter";
+/** Name of a segment declared on the same entity. */
+export const REPORTING_ATTR_SEGMENT = "segment";
+/** `measure.ratio` operand names. */
+export const REPORTING_ATTR_NUMERATOR = "numerator";
+export const REPORTING_ATTR_DENOMINATOR = "denominator";
+/** Integer a measure reads when it would otherwise be null (`measure.aggregate` / `measure.ratio`). */
+export const REPORTING_ATTR_DEFAULT = "default";
+
+// ---------------------------------------------------------------------------
+// Closed sets — mirrored by `allowedValues` in spec/metamodel/reporting.json.
+// Order is part of the contract (it is the order the registry manifest records).
+// ---------------------------------------------------------------------------
+
+/** Weeks start on Monday (ISO-8601) in every lowering. */
+export const GRAIN_HOUR = "hour";
+export const GRAIN_DAY = "day";
+export const GRAIN_WEEK = "week";
+export const GRAIN_MONTH = "month";
+export const GRAIN_QUARTER = "quarter";
+export const GRAIN_YEAR = "year";
+export const TIME_GRAINS = [GRAIN_HOUR, GRAIN_DAY, GRAIN_WEEK, GRAIN_MONTH, GRAIN_QUARTER, GRAIN_YEAR] as const;
+export type TimeGrain = (typeof TIME_GRAINS)[number];
+
+export const AGG_COUNT = "count";
+export const AGG_SUM = "sum";
+export const AGG_AVG = "avg";
+export const AGG_MIN = "min";
+export const AGG_MAX = "max";
+// `any` / `all`: boolean OR / AND over a `field.boolean` (Postgres `bool_or` / `bool_and`); the
+// measure is boolean. The names, and their constants, are `origin.aggregate`'s own.
+export const MEASURE_AGGS = [AGG_COUNT, AGG_SUM, AGG_AVG, AGG_MIN, AGG_MAX, AGG_ANY, AGG_ALL] as const;
+export type MeasureAgg = (typeof MEASURE_AGGS)[number];
+
+/** Separator in an `object.report` `@dimensions` item: `name` or `name:grain`. */
+export const REPORT_DIMENSION_GRAIN_SEPARATOR = ":";
+
+// ---------------------------------------------------------------------------
+// Relative-date filter values (spec §4 R4; rules F1/F2)
+// ---------------------------------------------------------------------------
+
+/** The single key of a relative-date filter value: `{ now: "<ISO-8601 duration>" }`
+ *  means "the current time plus that duration", evaluated when the view is queried.
+ *  Legal only in the `@filter` of a `segment`, `measure.aggregate` or `object.report`. */
+export const FILTER_RELATIVE_NOW = "now";
+
+/** A signed ISO-8601 duration (`-P7D`, `P1Y2M`, `-PT12H`). The lookaheads refuse the
+ *  degenerate `P` and `PT` forms (a designator with no component). */
+export const ISO_DURATION_RE =
+  /^[+-]?P(?!$)(\d+Y)?(\d+M)?(\d+W)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+S)?)?$/;