@metaobjectsdev/metadata 1.0.13 → 1.1.0

package/dist/core/reporting/report-accessors.js

@@ -0,0 +1,56 @@
+// 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 { 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";
+function stringList(v) {
+    if (Array.isArray(v))
+        return v.filter((x) => typeof x === "string");
+    return typeof v === "string" ? [v] : [];
+}
+/** The `@from` entity name of a report. */
+export function reportFrom(obj) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    if (item.grain === undefined || item.grain === "")
+        return item.name;
+    return item.name + item.grain.charAt(0).toUpperCase() + item.grain.slice(1);
+}
+//# sourceMappingURL=report-accessors.js.map

package/dist/core/reporting/report-accessors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-accessors.js","sourceRoot":"","sources":["../../../src/core/reporting/report-accessors.ts"],"names":[],"mappings":"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"}

package/dist/core/reporting/report-describe.d.ts

@@ -0,0 +1,59 @@
+import type { MetaData } from "../../shared/meta-data.js";
+import type { MetaRoot } from "../../shared/meta-root.js";
+import type { MetaObject } from "../object/meta-object.js";
+import { type ReportField, type ReportShape } from "./report-shape.js";
+/** A row-scope filter as the loader holds it: compact JSON in declared order, in a code span. */
+export declare function describeFilter(filter: unknown): string;
+/**
+ * "segment `paid` and filter `{…}`": the rows a measure or a report is scoped to, or
+ * undefined when it declares neither. The two combine by AND, as the lowering combines them.
+ */
+export declare function describeRowScope(segment: unknown, filter: unknown): string | undefined;
+/** A dimension as its entity declares it: the column, and for a time dimension its grains. */
+export declare function describeDimension(dim: MetaData): string;
+/**
+ * A dimension as ONE report column. A time dimension is truncated to the grain the report
+ * picked; reports are UTC only (there is no time-zone vocabulary). After a `via` clause
+ * the truncation is set off by a comma, so it reads as applying to the column and not to
+ * the relationship path.
+ */
+export declare function describeDimensionColumn(dim: MetaData, grain?: string): string;
+/**
+ * A measure in words: the aggregate and its row scope, or the ratio and its null rule. A
+ * `@default` ends either with the value it reads when there is nothing to aggregate; a
+ * defaulted ratio is never null, so its null rule gives way to that clause.
+ */
+export declare function describeMeasure(measure: MetaData): string;
+/** A segment in words: its filter. */
+export declare function describeSegment(segment: MetaData): string;
+/** One derived report column's definition, from the dimension or measure it comes from. */
+export declare function describeReportField(field: ReportField): string;
+/**
+ * Where a report with `@spine` takes its rows (R8): "one row per distinct dimension tuple
+ * among the rows of `Program`, reached by `Purchase.program`, including those no `Purchase`
+ * refers to". Undefined for a report without `@spine`, whose rows are the groups of its
+ * `@from` rows and need no sentence. The spine is printed as declared.
+ */
+export declare function describeReportRows(shape: ReportShape, root: MetaRoot): string | undefined;
+/**
+ * A report's row scope ({@link describeRowScope} over its `@segment` and `@filter`), or
+ * undefined when it declares neither. Under `@spine` the scope chooses which rows of `@from`
+ * are aggregated and never removes a row of the report, so it reads "aggregating only
+ * segment `paid`".
+ */
+export declare function describeReportRowScope(report: MetaObject): string | undefined;
+/** The neutral logical type of a derived column: its Table B subtype, `[]` for an array. */
+export declare function reportFieldTypeName(field: ReportField): string;
+/**
+ * Why a report is not served, or undefined when it is. The loader refuses an abstract
+ * report (R11) and a read source whose `@kind` is not `view` (R10), so the one way a loaded
+ * report goes unserved is declaring no read source at all (Plan 3 Table A).
+ */
+export declare function reportNotServedReason(report: MetaObject): string | undefined;
+/**
+ * The attributes the describer for `node` reads, so a documentation coverage audit can
+ * mark exactly those as rendered and no others. Kept beside the describers: a describer
+ * that starts reading a new attribute adds it here. Empty for any other node.
+ */
+export declare function reportingDescribedAttrs(node: MetaData): readonly string[];
+//# sourceMappingURL=report-describe.d.ts.map

package/dist/core/reporting/report-describe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-describe.d.ts","sourceRoot":"","sources":["../../../src/core/reporting/report-describe.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAG1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAkB3D,OAAO,EAAqB,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAY1F,iGAAiG;AACjG,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAEtD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAKtF;AAaD,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAIvD;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAK7E;AAWD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,QAAQ,GAAG,MAAM,CAkBzD;AAED,sCAAsC;AACtC,wBAAgB,eAAe,CAAC,OAAO,EAAE,QAAQ,GAAG,MAAM,CAEzD;AAED,2FAA2F;AAC3F,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAG9D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAUzF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAK7E;AAED,4FAA4F;AAC5F,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAG9D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAE5E;AAWD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,MAAM,EAAE,CAKzE"}

package/dist/core/reporting/report-describe.js

@@ -0,0 +1,182 @@
+// The reporting vocabulary in words (FR-044): what a dimension groups by, what a measure
+// computes, which rows a segment or report is scoped to, and why a report is not served.
+//
+// One home for the wording. The docs generators print these sentences on the markdown model pages
+// (codegen-ts) and on the HTML site (docs-site); both read them from here, so the two
+// surfaces cannot say different things about the same node.
+//
+// Every function returns PLAIN TEXT whose identifiers sit in single-backtick spans
+// ("sum of `Invoice.amountCents` where segment `paid`"). A caller turns the spans into
+// its own markup. Nothing here derives SQL: a description says what a column means, never
+// how the view computes it.
+//
+// Browser-safe: no Node-only import.
+import { TYPE_DIMENSION, TYPE_MEASURE, TYPE_SEGMENT } from "../../shared/base-types.js";
+import { AGG_ALL } from "../../persistence/origin/origin-constants.js";
+import { OBJECT_REPORT_ATTR_FILTER, OBJECT_REPORT_ATTR_SEGMENT, OBJECT_REPORT_ATTR_SPINE } from "../object/object-constants.js";
+import { DIMENSION_SUBTYPE_TIME, MEASURE_SUBTYPE_RATIO, REPORTING_ATTR_AGG, REPORTING_ATTR_DEFAULT, REPORTING_ATTR_DENOMINATOR, REPORTING_ATTR_DISTINCT, REPORTING_ATTR_FILTER, REPORTING_ATTR_GRAINS, REPORTING_ATTR_NUMERATOR, REPORTING_ATTR_OF, REPORTING_ATTR_SEGMENT, REPORTING_ATTR_VIA, } from "./reporting-constants.js";
+import { reportSpine } from "./report-accessors.js";
+import { reportReadSource } from "./report-read-model.js";
+import { reportSpineEntity } from "./report-shape.js";
+/** Inline code. A backtick cannot sit inside a single-backtick span, so it is dropped. */
+function tick(text) {
+    return `\`${text.replace(/`/g, "")}\``;
+}
+function stringList(v) {
+    if (Array.isArray(v))
+        return v.filter((x) => typeof x === "string");
+    return typeof v === "string" ? [v] : [];
+}
+/** A row-scope filter as the loader holds it: compact JSON in declared order, in a code span. */
+export function describeFilter(filter) {
+    return tick(JSON.stringify(filter ?? {}));
+}
+/**
+ * "segment `paid` and filter `{…}`": the rows a measure or a report is scoped to, or
+ * undefined when it declares neither. The two combine by AND, as the lowering combines them.
+ */
+export function describeRowScope(segment, filter) {
+    const parts = [];
+    if (typeof segment === "string" && segment !== "")
+        parts.push(`segment ${tick(segment)}`);
+    if (filter !== undefined && filter !== null)
+        parts.push(`filter ${describeFilter(filter)}`);
+    return parts.length > 0 ? parts.join(" and ") : undefined;
+}
+/** "`Program.title` via `Purchase.program`": the column a dimension groups by. */
+function dimensionColumn(dim) {
+    // ADR-0039: resolving reads, here and in every describer below, so a node that
+    // `extends` another is described by its effective attributes. References are
+    // printed as the author wrote them (ADR-0059), not as the loader resolved them.
+    const of = dim.authoredAttr(REPORTING_ATTR_OF);
+    const via = dim.authoredAttr(REPORTING_ATTR_VIA);
+    const column = tick(typeof of === "string" ? of : "");
+    return typeof via === "string" && via !== "" ? `${column} via ${tick(via)}` : column;
+}
+/** A dimension as its entity declares it: the column, and for a time dimension its grains. */
+export function describeDimension(dim) {
+    const column = dimensionColumn(dim);
+    if (dim.subType !== DIMENSION_SUBTYPE_TIME)
+        return column;
+    return `${column}; grains: ${stringList(dim.attr(REPORTING_ATTR_GRAINS)).join(", ")}`;
+}
+/**
+ * A dimension as ONE report column. A time dimension is truncated to the grain the report
+ * picked; reports are UTC only (there is no time-zone vocabulary). After a `via` clause
+ * the truncation is set off by a comma, so it reads as applying to the column and not to
+ * the relationship path.
+ */
+export function describeDimensionColumn(dim, grain) {
+    const column = dimensionColumn(dim);
+    if (grain === undefined || grain === "")
+        return column;
+    const joiner = column.includes(" via ") ? "," : "";
+    return `${column}${joiner} truncated to ${grain}, UTC`;
+}
+/**
+ * "; `0` when there is nothing to aggregate": the clause a measure's `@default` adds (R9), or
+ * "" when it declares none. The declared integer is printed as written.
+ */
+function defaultClause(measure) {
+    const declared = measure.attr(REPORTING_ATTR_DEFAULT);
+    return typeof declared === "number" ? `; ${tick(String(declared))} when there is nothing to aggregate` : "";
+}
+/**
+ * A measure in words: the aggregate and its row scope, or the ratio and its null rule. A
+ * `@default` ends either with the value it reads when there is nothing to aggregate; a
+ * defaulted ratio is never null, so its null rule gives way to that clause.
+ */
+export function describeMeasure(measure) {
+    const fallback = defaultClause(measure);
+    if (measure.subType === MEASURE_SUBTYPE_RATIO) {
+        const numerator = measure.attr(REPORTING_ATTR_NUMERATOR);
+        const denominator = measure.attr(REPORTING_ATTR_DENOMINATOR);
+        const quotient = `${tick(String(numerator ?? ""))} / ${tick(String(denominator ?? ""))}`;
+        return fallback !== "" ? `${quotient}${fallback}` : `${quotient}, null when the denominator is 0`;
+    }
+    const columns = stringList(measure.authoredAttr(REPORTING_ATTR_OF)).map(tick);
+    const scope = describeRowScope(measure.attr(REPORTING_ATTR_SEGMENT), measure.attr(REPORTING_ATTR_FILTER));
+    if (columns.length === 0) {
+        // @agg any / all with no @of (loader rule M0): the row condition is the quantified predicate.
+        const quantifier = measure.attr(REPORTING_ATTR_AGG) === AGG_ALL ? "every row" : "some row";
+        return `true when ${quantifier} has ${scope ?? ""}${fallback}`;
+    }
+    const of = columns.length === 1 ? columns[0] : `(${columns.join(", ")})`;
+    const distinct = measure.attr(REPORTING_ATTR_DISTINCT) === true ? "distinct " : "";
+    return `${String(measure.attr(REPORTING_ATTR_AGG) ?? "")} of ${distinct}${of}${scope !== undefined ? ` where ${scope}` : ""}${fallback}`;
+}
+/** A segment in words: its filter. */
+export function describeSegment(segment) {
+    return describeFilter(segment.attr(REPORTING_ATTR_FILTER));
+}
+/** One derived report column's definition, from the dimension or measure it comes from. */
+export function describeReportField(field) {
+    if (field.dimension !== undefined)
+        return describeDimensionColumn(field.dimension, field.grain);
+    return field.measure !== undefined ? describeMeasure(field.measure) : "";
+}
+/**
+ * Where a report with `@spine` takes its rows (R8): "one row per distinct dimension tuple
+ * among the rows of `Program`, reached by `Purchase.program`, including those no `Purchase`
+ * refers to". Undefined for a report without `@spine`, whose rows are the groups of its
+ * `@from` rows and need no sentence. The spine is printed as declared.
+ */
+export function describeReportRows(shape, root) {
+    const entity = reportSpineEntity(shape.report, shape.from, root);
+    // Printed as the author wrote it (ADR-0059).
+    const authored = reportSpine(shape.report) !== undefined ? shape.report.authoredAttr(OBJECT_REPORT_ATTR_SPINE) : undefined;
+    const spine = typeof authored === "string" ? authored : undefined;
+    if (spine === undefined || entity === undefined)
+        return undefined;
+    return (`one row per distinct dimension tuple among the rows of ${tick(entity.name)}, reached by ${tick(spine)}, ` +
+        `including those no ${tick(shape.from.name)} refers to`);
+}
+/**
+ * A report's row scope ({@link describeRowScope} over its `@segment` and `@filter`), or
+ * undefined when it declares neither. Under `@spine` the scope chooses which rows of `@from`
+ * are aggregated and never removes a row of the report, so it reads "aggregating only
+ * segment `paid`".
+ */
+export function describeReportRowScope(report) {
+    // ADR-0039: resolving.
+    const scope = describeRowScope(report.attr(OBJECT_REPORT_ATTR_SEGMENT), report.attr(OBJECT_REPORT_ATTR_FILTER));
+    if (scope === undefined)
+        return undefined;
+    return reportSpine(report) !== undefined ? `aggregating only ${scope}` : scope;
+}
+/** The neutral logical type of a derived column: its Table B subtype, `[]` for an array. */
+export function reportFieldTypeName(field) {
+    // ADR-0039: resolvedIsArray() is the resolving read of the native array flag.
+    return field.typeSource?.resolvedIsArray() === true ? `${field.subType}[]` : field.subType;
+}
+/**
+ * Why a report is not served, or undefined when it is. The loader refuses an abstract
+ * report (R11) and a read source whose `@kind` is not `view` (R10), so the one way a loaded
+ * report goes unserved is declaring no read source at all (Plan 3 Table A).
+ */
+export function reportNotServedReason(report) {
+    return reportReadSource(report) === undefined ? "Not served: declares no view source" : undefined;
+}
+const DIMENSION_ATTRS = [REPORTING_ATTR_OF, REPORTING_ATTR_VIA];
+const TIME_DIMENSION_ATTRS = [...DIMENSION_ATTRS, REPORTING_ATTR_GRAINS];
+const AGGREGATE_ATTRS = [
+    REPORTING_ATTR_AGG, REPORTING_ATTR_OF, REPORTING_ATTR_DISTINCT, REPORTING_ATTR_SEGMENT, REPORTING_ATTR_FILTER,
+    REPORTING_ATTR_DEFAULT,
+];
+const RATIO_ATTRS = [REPORTING_ATTR_NUMERATOR, REPORTING_ATTR_DENOMINATOR, REPORTING_ATTR_DEFAULT];
+const SEGMENT_ATTRS = [REPORTING_ATTR_FILTER];
+/**
+ * The attributes the describer for `node` reads, so a documentation coverage audit can
+ * mark exactly those as rendered and no others. Kept beside the describers: a describer
+ * that starts reading a new attribute adds it here. Empty for any other node.
+ */
+export function reportingDescribedAttrs(node) {
+    if (node.type === TYPE_DIMENSION)
+        return node.subType === DIMENSION_SUBTYPE_TIME ? TIME_DIMENSION_ATTRS : DIMENSION_ATTRS;
+    if (node.type === TYPE_MEASURE)
+        return node.subType === MEASURE_SUBTYPE_RATIO ? RATIO_ATTRS : AGGREGATE_ATTRS;
+    if (node.type === TYPE_SEGMENT)
+        return SEGMENT_ATTRS;
+    return [];
+}
+//# sourceMappingURL=report-describe.js.map

package/dist/core/reporting/report-describe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-describe.js","sourceRoot":"","sources":["../../../src/core/reporting/report-describe.ts"],"names":[],"mappings":"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"}

package/dist/core/reporting/report-read-model.d.ts

@@ -0,0 +1,34 @@
+import type { MetaRoot } from "../../shared/meta-root.js";
+import { MetaSource } from "../../persistence/source/meta-source.js";
+import { MetaObject } from "../object/meta-object.js";
+/**
+ * The source a report is READ from: its own read-only source with `@role: primary`,
+ * else its first own read-only source. Undefined when it declares none (Table A:
+ * not lowered, not served).
+ *
+ * This is the rule that NAMES the lowered view — `viewName` / `projectionViewSource`
+ * in codegen-ts's `projection/extract-view-spec.ts`, reached for a report through
+ * `projectionViewName`. It is restated here because the metadata package cannot
+ * depend on a codegen package; the two must stay the same rule, or the runtime
+ * reads a relation the lowering did not create.
+ *
+ * What the loader permits, measured: a report may declare several read-only sources
+ * (a `@role: replica` view beside its primary view loads clean, in either order);
+ * `@role` defaults to `primary`; a report whose sources include no primary is
+ * `ERR_SOURCE_NO_PRIMARY` and a writable source on a report is refused. So for every
+ * model that loads, the primary branch fires. The first-read-only fallback covers a
+ * tree built in code, and keeps this rule identical to the lowering's.
+ */
+export declare function reportReadSource(report: MetaObject): MetaSource | undefined;
+/**
+ * The read model of an `object.report`: one field per Table B row, in Table B
+ * order, plus a copy of the source the report is read from (see
+ * `reportReadSource`) when it declares one (Table A). A sourceless report yields a model with no source: it has a shape
+ * and no view, and the caller decides what that means (the runtime refuses to
+ * serve it).
+ *
+ * Cached per report node; the model is frozen. Throws what `reportShape` throws
+ * when a reference does not resolve.
+ */
+export declare function reportReadModel(report: MetaObject, root: MetaRoot): MetaObject;
+//# sourceMappingURL=report-read-model.d.ts.map

package/dist/core/reporting/report-read-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-read-model.d.ts","sourceRoot":"","sources":["../../../src/core/reporting/report-read-model.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE1D,OAAO,EAAE,UAAU,EAAE,MAAM,yCAAyC,CAAC;AAGrE,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AA0EtD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,CAK3E;AAsBD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,GAAG,UAAU,CAgB9E"}

package/dist/core/reporting/report-read-model.js

@@ -0,0 +1,165 @@
+// A report's READ MODEL (FR-044): a detached object carrying one real `field.*`
+// child per derived field (Table B) and a copy of the report's own read-only source.
+//
+// WHY IT EXISTS
+//
+// An `object.report` declares no fields: its read shape is derived from its
+// dimensions and measures. A metadata-driven runtime walks an object's field
+// children in a dozen places (column list, filter and sort resolution, the name
+// map, every read coercion). Rather than teach each of them what a report is, the
+// runtime reads a report through this model and sees ordinary fields.
+//
+// WHY IT IS DETACHED
+//
+// The model is never added to the root: it has no parent, `root.objects()` does
+// not list it, and the canonical serializer, `fmt`, codegen and every other tree
+// walker never see it. Nothing in the loaded tree is mutated to build it; in
+// particular the report's own source node is COPIED, not re-parented
+// (`addChild` rewrites the child's parent). The nodes are constructed directly,
+// not through the registry, so the sealed registry is not involved and no
+// vocabulary is added: every node is an already-registered `type.subType`.
+//
+// It keeps the report's name, package and `object.report` subtype, so a consumer
+// holding it can still tell it is a report (no identity, read-only).
+import { TypeId } from "../../registry.js";
+import { TYPE_FIELD } from "../../shared/base-types.js";
+import { isReadOnlySource } from "../../shared/node-guards.js";
+import { MetaSource } from "../../persistence/source/meta-source.js";
+import { SOURCE_ATTR_ROLE, SOURCE_ROLE_PRIMARY } from "../../persistence/source/source-constants.js";
+import { FIELD_ATTR_DB_COLUMN_TYPE, FIELD_ATTR_LOCAL_TIME } from "../../persistence/db/db-constants.js";
+import { MetaObject } from "../object/meta-object.js";
+import { MetaField } from "../field/meta-field.js";
+import { FIELD_ATTR_CURRENCY, FIELD_ATTR_FILTERABLE, FIELD_ATTR_INT_VALUE_MAP, FIELD_ATTR_MAX_LENGTH, FIELD_ATTR_PRECISION, FIELD_ATTR_REQUIRED, FIELD_ATTR_SCALE, FIELD_ATTR_STORAGE, FIELD_ATTR_VALUES, FIELD_SUBTYPE_MAP, } from "../field/field-constants.js";
+import { opsForField } from "../query/query-constants.js";
+import { reportShape } from "./report-shape.js";
+/**
+ * Table B: the type-shaping attrs a derived field carries from its `typeSource`,
+ * read with the RESOLVING accessor (ADR-0039) so a value the `@of` field inherits
+ * through `extends` is carried too. `@dbColumnType` and `isArray` are handled
+ * separately below. Nothing else is carried: no `@column`, `@required`,
+ * `@default`, validators or views.
+ */
+const CARRIED_ATTRS = [
+    FIELD_ATTR_CURRENCY,
+    FIELD_ATTR_VALUES,
+    FIELD_ATTR_INT_VALUE_MAP,
+    FIELD_ATTR_MAX_LENGTH,
+    FIELD_ATTR_PRECISION,
+    FIELD_ATTR_SCALE,
+    FIELD_ATTR_LOCAL_TIME,
+    FIELD_ATTR_STORAGE,
+];
+/** True for a derived field whose source field is an array or a `field.map`. */
+function isArrayOrMap(field) {
+    return field.resolvedIsArray() || field.subType === FIELD_SUBTYPE_MAP;
+}
+function derivedField(f) {
+    const field = new MetaField(new TypeId(TYPE_FIELD, f.subType), f.name);
+    // From the derived shape, never from the type source: a `min` of a required column
+    // is still nullable, and a dimension reached by `@via` is nullable.
+    field.setAttr(FIELD_ATTR_REQUIRED, f.required);
+    const src = f.typeSource;
+    if (src !== undefined) {
+        for (const name of CARRIED_ATTRS) {
+            const value = src.attr(name);
+            if (value !== undefined)
+                field.setAttr(name, value);
+        }
+        // ADR-0039: own — `@dbColumnType` is the one deliberately own-only attr (a
+        // physical column-type override is never inherited), and every consumer reads
+        // it with `ownAttr`. So it is read own from the type source and set OWN here:
+        // the derived field carries exactly what the `@of` field itself declares, and
+        // nothing its supers declare. A field that `extends` another does not get the
+        // parent's `@dbColumnType` either, so this matches how a projection field
+        // would see it.
+        const dbColumnType = src.ownAttr(FIELD_ATTR_DB_COLUMN_TYPE);
+        if (dbColumnType !== undefined)
+            field.setAttr(FIELD_ATTR_DB_COLUMN_TYPE, dbColumnType);
+        // `isArray` is a native flag, not an attr; resolvedIsArray() is its resolving read.
+        if (src.resolvedIsArray())
+            field.setIsArray(true);
+    }
+    // Table C (Plan 3): a report author has no node to put @filterable on, so every
+    // derived field that has a filter band is filterable, and (the sort allowlist follows
+    // `@filterable`) sortable. Set on this detached model only; no vocabulary is added and the
+    // declared tree is not touched. EXCEPT an array or a map: an array column cannot be compared
+    // with a scalar (`text[] = text` is a Postgres error), and the entity rule already refuses
+    // `@filterable` on an array field, so a derived field whose source is either is neither
+    // filterable nor sortable, in every port.
+    if (!isArrayOrMap(field) && opsForField(field).length > 0)
+        field.setAttr(FIELD_ATTR_FILTERABLE, true);
+    return field;
+}
+/**
+ * The source a report is READ from: its own read-only source with `@role: primary`,
+ * else its first own read-only source. Undefined when it declares none (Table A:
+ * not lowered, not served).
+ *
+ * This is the rule that NAMES the lowered view — `viewName` / `projectionViewSource`
+ * in codegen-ts's `projection/extract-view-spec.ts`, reached for a report through
+ * `projectionViewName`. It is restated here because the metadata package cannot
+ * depend on a codegen package; the two must stay the same rule, or the runtime
+ * reads a relation the lowering did not create.
+ *
+ * What the loader permits, measured: a report may declare several read-only sources
+ * (a `@role: replica` view beside its primary view loads clean, in either order);
+ * `@role` defaults to `primary`; a report whose sources include no primary is
+ * `ERR_SOURCE_NO_PRIMARY` and a writable source on a report is refused. So for every
+ * model that loads, the primary branch fires. The first-read-only fallback covers a
+ * tree built in code, and keeps this rule identical to the lowering's.
+ */
+export function reportReadSource(report) {
+    // ADR-0039: own — source classification reads the sources the report declares
+    // ITSELF, exactly as the lowering's `viewName` does.
+    const readOnly = report.ownChildren().filter(isReadOnlySource);
+    return readOnly.find((s) => s.role === SOURCE_ROLE_PRIMARY) ?? readOnly[0];
+}
+/**
+ * A detached copy of a source node: same `type.subType`, name and effective attrs,
+ * and nothing else (attrs only — the loaded node is never re-parented).
+ *
+ * The copy is the model's ONLY source, and it is pinned to `@role: primary`: the
+ * runtime resolves an object's table through `primaryRdbSource`, which considers
+ * primary sources only, so this is what makes the read land on the selected
+ * source's physical name rather than on a default table name nobody declared.
+ */
+function copySource(source) {
+    const copy = new MetaSource(source.typeId, source.name);
+    // ADR-0039: resolving — the copy carries the source's effective configuration
+    // (@kind, the physical-name alias, @schema, @unmanaged, @sql).
+    for (const [name, value] of source.attrs())
+        copy.setAttr(name, value);
+    copy.setAttr(SOURCE_ATTR_ROLE, SOURCE_ROLE_PRIMARY);
+    return copy;
+}
+const READ_MODELS = new WeakMap();
+/**
+ * The read model of an `object.report`: one field per Table B row, in Table B
+ * order, plus a copy of the source the report is read from (see
+ * `reportReadSource`) when it declares one (Table A). A sourceless report yields a model with no source: it has a shape
+ * and no view, and the caller decides what that means (the runtime refuses to
+ * serve it).
+ *
+ * Cached per report node; the model is frozen. Throws what `reportShape` throws
+ * when a reference does not resolve.
+ */
+export function reportReadModel(report, root) {
+    const cached = READ_MODELS.get(report);
+    if (cached !== undefined)
+        return cached;
+    const shape = reportShape(report, root);
+    const model = new MetaObject(report.typeId, report.name);
+    if (report.package !== undefined)
+        model.setPackage(report.package);
+    if (report.fileDefaultPackage !== undefined)
+        model.setFileDefaultPackage(report.fileDefaultPackage);
+    for (const f of shape.fields)
+        model.addChild(derivedField(f));
+    const source = reportReadSource(report);
+    if (source !== undefined)
+        model.addChild(copySource(source));
+    model.freeze();
+    READ_MODELS.set(report, model);
+    return model;
+}
+//# sourceMappingURL=report-read-model.js.map

package/dist/core/reporting/report-read-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-read-model.js","sourceRoot":"","sources":["../../../src/core/reporting/report-read-model.ts"],"names":[],"mappings":"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"}

package/dist/core/reporting/report-shape.d.ts

@@ -0,0 +1,103 @@
+import type { MetaData } from "../../shared/meta-data.js";
+import type { MetaRoot } from "../../shared/meta-root.js";
+import type { MetaObject } from "../object/meta-object.js";
+import type { MetaField } from "../field/meta-field.js";
+import { MetaDimension } from "./meta-dimension.js";
+import { MetaMeasure } from "./meta-measure.js";
+import { 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[];
+}
+/**
+ * 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 declare function reportingMemberOwner(member: MetaData, from: MetaObject): MetaData;
+/**
+ * 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 declare function resolveReportingFieldRef(ref: string, declaring: MetaData, root: MetaRoot, host?: MetaObject): MetaField | undefined;
+/**
+ * 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 declare function resolveDimensionOf(dim: MetaDimension, from: MetaObject, root: MetaRoot): {
+    readonly named: MetaObject;
+    readonly field: MetaField;
+} | undefined;
+/**
+ * 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 declare function reportingViaHops(via: string, declaring: MetaData, from: MetaObject, root: MetaRoot): string[] | undefined;
+/**
+ * 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 declare function reportSpineHops(report: MetaObject, from: MetaObject, root: MetaRoot): string[] | 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 declare function reportSpineEntity(report: MetaObject, from: MetaObject, root: MetaRoot): MetaObject | undefined;
+/**
+ * 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 declare function measureResultSubType(measure: MetaMeasure, from: MetaObject, root: MetaRoot): string | undefined;
+/**
+ * {@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 declare function measureDerivedSubType(measure: MetaMeasure, from: MetaObject, root: MetaRoot): string;
+/** 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 declare function reportShape(report: MetaObject, root: MetaRoot): ReportShape;
+//# sourceMappingURL=report-shape.d.ts.map