@metaobjectsdev/metadata 1.0.13 → 1.1.1-rc.1

package/dist/loader/reporting-validation.js

@@ -0,0 +1,883 @@
+// FR-044 — cross-node rules for the reporting vocabulary. The rule ids (D1…F2)
+// match the rule table in docs/superpowers/plans/2026-10-03-fr-044-plan-1-reporting-vocabulary.md
+// (R8, R9, M7 and M8: Table B of docs/superpowers/plans/2026-10-09-fr-044-zero-rows-and-measure-defaults.md)
+// and the error fixtures in fixtures/conformance/error-*. Every port implements
+// the same table WITH THE SAME MESSAGE TEXT; the fixtures are the contract.
+//
+// Two design rules hold throughout, so one broken rule yields exactly one error:
+//   - No cascades. A member that fails a structural rule is not checked further
+//     (a dimension whose @via fails D2 skips D1/D3/D4; a measure that fails one
+//     of M0–M4, or whose @default is a fraction, skips M7/M8; a report whose
+//     @from fails R1 skips R2/R3/R6/R7, R8/R9 and its @filter; a report whose
+//     @spine fails R8 skips R9, and R9
+//     skips a dimension whose @via fails D2; an invalid @dimensions/@measures
+//     item derives no report field for R6).
+//   - Each error's `source` is the offending node (the dimension / measure /
+//     segment / report, or for R4/R5 the declared child), so a conformance
+//     fixture's jsonPath points at it.
+//
+// Inheritance (ADR-0039): an entity's members are read through children(), so a
+// member declared on an abstract base is validated against every entity that
+// inherits it. Members declared on an entity are validated first (pass 1), then
+// inherited ones (pass 2); an error already reported for the same node with the
+// same message is not repeated, so a broken base member is reported ONCE, and
+// a failure that only an inheritor exposes carries " (inherited by '<entity>')".
+import { ParseError } from "../errors.js";
+import { refTarget, resolveObjectRef } from "../naming-refs.js";
+import { PACKAGE_SEPARATOR, CHILD_REF_SEPARATOR } from "../shared/structural.js";
+import { TYPE_OBJECT, TYPE_FIELD, TYPE_IDENTITY, TYPE_RELATIONSHIP, TYPE_SOURCE, TYPE_DIMENSION, TYPE_MEASURE, TYPE_SEGMENT, } from "../shared/base-types.js";
+import { OBJECT_SUBTYPE_ENTITY, OBJECT_SUBTYPE_REPORT, OBJECT_REPORT_ATTR_FILTER, OBJECT_REPORT_ATTR_SEGMENT, OBJECT_REPORT_ATTR_SPINE, } from "../core/object/object-constants.js";
+import { FIELD_SUBTYPE_INT, FIELD_SUBTYPE_LONG, FIELD_SUBTYPE_DOUBLE, FIELD_SUBTYPE_FLOAT, FIELD_SUBTYPE_DECIMAL, FIELD_SUBTYPE_CURRENCY, FIELD_SUBTYPE_BOOLEAN, FIELD_SUBTYPE_OBJECT, FIELD_SUBTYPE_MAP, FIELD_SUBTYPE_DATE, FIELD_SUBTYPE_TIMESTAMP, FIELD_ATTR_OBJECT_REF, } from "../core/field/field-constants.js";
+import { IDENTITY_SUBTYPE_REFERENCE, IDENTITY_REFERENCE_ATTR_REFERENCES, } from "../core/identity/identity-constants.js";
+import { RELATIONSHIP_ATTR_OBJECT_REF, RELATIONSHIP_ATTR_CARDINALITY, CARDINALITY_ONE, } from "../core/relationship/relationship-constants.js";
+import { FILTER_COMPOSE_OR, FILTER_COMPOSE_AND, FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE, opsForField, } from "../core/query/query-constants.js";
+import { ATTR_SUBTYPE_FILTER } from "../core/attr/attr-constants.js";
+import { isMetaObject, isMetaRoot, isReadOnlySource, isWritableSource } from "../shared/node-guards.js";
+import { SOURCE_KIND_VIEW } from "../persistence/source/source-constants.js";
+import { AGG_ALL, AGG_ANY } from "../persistence/origin/origin-constants.js";
+import { FILTER_RELATIVE_NOW, ISO_DURATION_RE, AGG_COUNT, AGG_SUM, AGG_AVG, AGG_MIN, AGG_MAX, GRAIN_HOUR, REPORTING_ATTR_NUMERATOR, REPORTING_ATTR_DENOMINATOR, REPORTING_ATTR_DEFAULT, REPORTING_ATTR_VIA, MEASURE_SUBTYPE_AGGREGATE, } from "../core/reporting/reporting-constants.js";
+import { MetaDimension } from "../core/reporting/meta-dimension.js";
+import { MetaMeasure } from "../core/reporting/meta-measure.js";
+import { MetaSegment } from "../core/reporting/meta-segment.js";
+import { measureResultSubType } from "../core/reporting/report-shape.js";
+import { reportDerivedFieldName, reportDimensionItems, reportFrom, reportMeasureNames, reportSpine, } from "../core/reporting/report-accessors.js";
+// ---------------------------------------------------------------------------
+// Closed sets the rules consult
+// ---------------------------------------------------------------------------
+/** M4 — the field subtypes `sum`/`avg` accept. */
+const NUMERIC_FIELD_SUBTYPES = [
+    FIELD_SUBTYPE_INT,
+    FIELD_SUBTYPE_LONG,
+    FIELD_SUBTYPE_DOUBLE,
+    FIELD_SUBTYPE_FLOAT,
+    FIELD_SUBTYPE_DECIMAL,
+    FIELD_SUBTYPE_CURRENCY,
+];
+/** M4 — the field subtypes `min`/`max` refuse (no total order). */
+const UNORDERED_FIELD_SUBTYPES = [
+    FIELD_SUBTYPE_BOOLEAN,
+    FIELD_SUBTYPE_OBJECT,
+    FIELD_SUBTYPE_MAP,
+];
+/** D3 / F2 — the temporal field subtypes. */
+const TEMPORAL_FIELD_SUBTYPES = [FIELD_SUBTYPE_DATE, FIELD_SUBTYPE_TIMESTAMP];
+/** F2 — the only ops a relative-date value may sit under. */
+const RELATIVE_DATE_OPS = [FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE];
+const ERR_INVALID_DIMENSION = "ERR_INVALID_DIMENSION";
+const ERR_INVALID_MEASURE = "ERR_INVALID_MEASURE";
+const ERR_INVALID_REPORT = "ERR_INVALID_REPORT";
+const ERR_REPORT_FOREIGN_MEASURE = "ERR_REPORT_FOREIGN_MEASURE";
+const ERR_BAD_ATTR_FILTER = "ERR_BAD_ATTR_FILTER";
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+export function validateReporting(root) {
+    const sink = new ErrorSink();
+    // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
+    const objects = root.children().filter((c) => c.type === TYPE_OBJECT);
+    const entities = objects.filter((o) => o.subType === OBJECT_SUBTYPE_ENTITY);
+    // Pass 1: every member against the entity that declares it (an abstract base
+    // included — its members must be self-consistent). Pass 2: inherited members
+    // against each inheriting entity, so an override that breaks one is caught.
+    for (const entity of entities)
+        checkEntityMembers(root, entity, true, sink);
+    for (const entity of entities)
+        checkEntityMembers(root, entity, false, sink);
+    for (const report of objects.filter((o) => o.subType === OBJECT_SUBTYPE_REPORT)) {
+        checkReport(root, report, sink);
+    }
+    // F1 on every host that is not a reporting host.
+    checkNoRelativeDates(root, sink);
+    return sink.errors;
+}
+/** Collects errors, dropping a repeat — the shape an unmodified inherited
+ *  member's failure takes when it is re-validated under an inheriting entity.
+ *  A message is `head + suffix + body`. A pass-2 error (suffix
+ *  " (inherited by '<entity>')") is dropped when pass 1 already reported the
+ *  same failure without a suffix, or the same inheritor already reported it;
+ *  a second inheritor's identical failure is still reported, under its own name. */
+class ErrorSink {
+    errors = [];
+    seen = new Map();
+    push(node, code, head, body, suffix = "") {
+        // `base` drops a pass-2 copy of a failure pass 1 already reported; a pass-2
+        // entry is keyed WITH its suffix, so two inheritors that break the same
+        // inherited member the same way are each reported.
+        const base = `${code}\u0000${head}${body}`;
+        const key = `${base}\u0000${suffix}`;
+        let keys = this.seen.get(node);
+        if (keys === undefined) {
+            keys = new Set();
+            this.seen.set(node, keys);
+        }
+        if (keys.has(base) || keys.has(key))
+            return;
+        keys.add(suffix === "" ? base : key);
+        this.errors.push(new ParseError(`${head}${suffix}${body}`, { code, source: node.source }));
+    }
+}
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+/** The node's package for ADR-0042 bare-reference resolution. */
+function pkgOf(node) {
+    return node.package ?? node.fileDefaultPackage ?? "";
+}
+/**
+ * Split a dotted `Owner.child[.child…]` reference at the first `.` after the
+ * last `::` (the same rule `_refNamedOwner` applies to extends refs), so an
+ * FQN owner (`acme::shop::Purchase.program`) keeps its package. Undefined when
+ * there is no owner, no child, or an empty child segment.
+ */
+function splitDotted(ref) {
+    const lastSep = ref.lastIndexOf(PACKAGE_SEPARATOR);
+    const segStart = lastSep === -1 ? 0 : lastSep + PACKAGE_SEPARATOR.length;
+    const dot = ref.indexOf(CHILD_REF_SEPARATOR, segStart);
+    if (dot <= segStart)
+        return undefined;
+    const path = ref.slice(dot + CHILD_REF_SEPARATOR.length).split(CHILD_REF_SEPARATOR);
+    if (path.some((s) => s === ""))
+        return undefined;
+    return { owner: ref.slice(0, dot), path };
+}
+/** True when `candidate` is `entity` or an entity it extends (the super chain). */
+function isSelfOrAncestor(candidate, entity) {
+    const visited = new Set();
+    for (let n = entity; n !== undefined && !visited.has(n); n = n.superData) {
+        if (n === candidate)
+            return true;
+        visited.add(n);
+    }
+    return false;
+}
+function childOfType(obj, type, name) {
+    // ADR-0039: resolving — inherited members (via extends) are visible.
+    return obj.children().find((c) => c.type === type && c.name === name);
+}
+/** A field's `@objectRef`, read with the resolving accessor (ADR-0039). */
+function objectRefOf(field) {
+    return field.attr(FIELD_ATTR_OBJECT_REF);
+}
+function fieldOf(obj, name) {
+    return childOfType(obj, TYPE_FIELD, name);
+}
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** An object operand carrying a `now` key — a relative-date value, well-formed
+ *  (exactly `{ now }`) or not. A malformed one is refused, never read as data. */
+function isRelativeValue(v) {
+    return isPlainObject(v) && Object.keys(v).includes(FILTER_RELATIVE_NOW);
+}
+/** True for a well-formed relative value: exactly the one key `now`. */
+function isExactRelativeValue(v) {
+    return Object.keys(v).length === 1;
+}
+/** The relative value an op's operand carries: the operand itself, or one inside an array operand. */
+function relativeOperand(v) {
+    if (isRelativeValue(v))
+        return v;
+    if (Array.isArray(v))
+        return v.find(isRelativeValue);
+    return undefined;
+}
+/** Deep search of an operand VALUE: is a relative value (well-formed or not) anywhere inside it? */
+function operandContainsRelativeValue(v) {
+    if (isRelativeValue(v))
+        return true;
+    if (Array.isArray(v))
+        return v.some(operandContainsRelativeValue);
+    if (isPlainObject(v))
+        return Object.values(v).some(operandContainsRelativeValue);
+    return false;
+}
+/**
+ * Does a filter contain a relative value in any operand? Walks the filter grammar
+ * (`and`/`or` arrays, `{ field: { op: operand } }`) so only operand VALUES are
+ * searched: a field key that happens to be named `now` is a field, not a relative date.
+ */
+function filterContainsRelativeValue(filter) {
+    if (!isPlainObject(filter))
+        return false;
+    for (const [key, clause] of Object.entries(filter)) {
+        if (key === FILTER_COMPOSE_OR || key === FILTER_COMPOSE_AND) {
+            if (Array.isArray(clause) && clause.some(filterContainsRelativeValue))
+                return true;
+            continue;
+        }
+        if (isRelativeValue(clause))
+            return true; // un-desugared shorthand
+        if (isPlainObject(clause) && Object.values(clause).some(operandContainsRelativeValue))
+            return true;
+    }
+    return false;
+}
+function quoteValue(v) {
+    return typeof v === "string" ? v : JSON.stringify(v);
+}
+/** `<type>.<subType> '<name>'`, or just `<type>.<subType>` for an unnamed node (e.g. a source or origin). */
+function childLabel(node) {
+    const head = `${node.type}.${node.subType}`;
+    return node.name !== "" ? `${head} '${node.name}'` : head;
+}
+/** `<type>.<subType> '<FQN>'` for a root-level object, else its childLabel plus ` in <parent label>`. */
+function nodeLabel(node) {
+    const parent = node.parent;
+    if (parent === undefined || parent.parent === undefined) {
+        return `${node.type}.${node.subType} '${node.resolutionKey()}'`;
+    }
+    return `${childLabel(node)} in ${nodeLabel(parent)}`;
+}
+/**
+ * The FQN a member message names for `entity`: the DECLARING entity in place of
+ * the host, so a failure is worded identically whichever entity reached the
+ * member (the suffix names the inheritor) and the ErrorSink repeat test holds.
+ */
+function shown(ctx, entity) {
+    return (entity === ctx.host ? ctx.declaring : entity).resolutionKey();
+}
+function checkEntityMembers(root, entity, declaredHere, sink) {
+    // ADR-0039: resolving — inherited members are validated against this entity.
+    for (const member of entity.children()) {
+        if (member.type !== TYPE_DIMENSION && member.type !== TYPE_MEASURE && member.type !== TYPE_SEGMENT)
+            continue;
+        const declaring = member.parent ?? entity;
+        if ((declaring === entity) !== declaredHere)
+            continue;
+        const ctx = {
+            root,
+            host: entity,
+            declaring,
+            label: `${member.type} '${member.name}' on entity '${declaring.resolutionKey()}'`,
+            suffix: declaredHere ? "" : ` (inherited by '${entity.resolutionKey()}')`,
+            sink,
+        };
+        if (member instanceof MetaDimension)
+            checkDimension(ctx, member);
+        else if (member instanceof MetaMeasure)
+            checkMeasure(ctx, member);
+        else if (member instanceof MetaSegment) {
+            const filter = member.filter();
+            if (filter !== undefined) {
+                checkFilter(filter, entity, declaring.resolutionKey(), ctx.label, member, ctx.suffix, sink);
+            }
+        }
+    }
+}
+function checkDimension(ctx, dim) {
+    const err = (message) => ctx.sink.push(dim, ERR_INVALID_DIMENSION, ctx.label, `: ${message}`, ctx.suffix);
+    // D2 — the @via walk; its terminal is the entity @of must name.
+    let ofEntity = ctx.host;
+    const via = dim.via();
+    if (via !== undefined) {
+        const terminal = walkToOneVia(ctx.root, ctx.host, via, err, d2Walk(ctx.declaring));
+        if (terminal === undefined)
+            return;
+        ofEntity = terminal;
+    }
+    // D1 — @of is Entity.field on the owning entity (or the @via terminal).
+    const of = dim.of();
+    if (of === undefined)
+        return; // missing @of is ERR_MISSING_REQUIRED_ATTR (attr schema pass)
+    const parts = splitDotted(of);
+    if (parts === undefined || parts.path.length !== 1) {
+        err(`@of '${of}' must be Entity.field.`);
+        return;
+    }
+    // D1 — after @via, a bare Owner resolves in the package of the entity @via reaches: the path
+    // already fixes the entity, so `Realm.name` after a hop onto `world::Realm` names it. Without
+    // @via it resolves in the declaring entity's package.
+    const ownerPkg = via === undefined ? pkgOf(ctx.declaring) : pkgOf(ofEntity);
+    const named = resolveObjectRef(ctx.root, parts.owner, ownerPkg).node;
+    if (!isSelfOrAncestor(named, ofEntity)) {
+        if (via === undefined) {
+            err(`@of '${of}' must name a field of the owning entity '${ctx.declaring.resolutionKey()}'. ` +
+                `Reach another entity's field with @via.`);
+        }
+        else {
+            err(`@of '${of}' must name a field of '${shown(ctx, ofEntity)}', the entity @via '${via}' reaches.`);
+        }
+        return;
+    }
+    const fieldName = parts.path[0];
+    // With @via the field is looked up on the entity @of NAMES (resolving: its own plus
+    // inherited), not on the @via terminal: a base the terminal extends must itself carry the field, or the
+    // dimension names a column the base table lacks and `meta migrate` fails on it. Without @via
+    // the host IS the checked entity: a dimension inherited from a base is checked against the
+    // inheritor's own (possibly overriding) field.
+    const lookup = via === undefined ? ofEntity : named;
+    const field = fieldOf(lookup, fieldName);
+    if (field === undefined) {
+        const declaredOnTerminal = lookup !== ofEntity && fieldOf(ofEntity, fieldName) !== undefined;
+        err(declaredOnTerminal
+            ? `@of '${of}' names no field '${fieldName}' on '${shown(ctx, lookup)}': only '${shown(ctx, ofEntity)}', ` +
+                `the entity @via reaches, declares it. Name it '${ofEntity.name}.${fieldName}'.`
+            : `@of '${of}' names no field '${fieldName}' on '${shown(ctx, lookup)}'.`);
+        return;
+    }
+    // D5 — a dimension groups by a scalar. A field.object (or a field carrying @objectRef) is a JSON
+    // document: no port serves a report over one, and a document is not a value to group rows by.
+    if (field.subType === FIELD_SUBTYPE_OBJECT || objectRefOf(field) !== undefined) {
+        err(`@of '${of}' is a field.${field.subType}${objectRefOf(field) !== undefined ? " with an @objectRef" : ""}, ` +
+            `which a report cannot group by. Group by a scalar field of it.`);
+        return;
+    }
+    if (!dim.isTime())
+        return;
+    // D3 — a time dimension groups a date or timestamp.
+    if (!TEMPORAL_FIELD_SUBTYPES.includes(field.subType)) {
+        err(`a time dimension's @of must be a field.date or field.timestamp, but '${of}' is field.${field.subType}.`);
+        return;
+    }
+    // D4 — a date has no hour.
+    if (field.subType === FIELD_SUBTYPE_DATE && dim.grains().includes(GRAIN_HOUR)) {
+        err(`grain 'hour' is impossible on '${of}', a field.date (a date has no hour). Remove 'hour' from @grains.`);
+    }
+}
+/** D2 — a dimension's @via, declared on `declaring`. Reproduces D2's messages exactly. */
+function d2Walk(declaring) {
+    const declaringKey = declaring.resolutionKey();
+    return {
+        attr: REPORTING_ATTR_VIA,
+        ownerPkg: pkgOf(declaring),
+        hostName: declaringKey,
+        start: `the owning entity '${declaringKey}'`,
+        startShort: "the owning entity",
+        toOneReason: "A dimension follows only @cardinality: one relationships and identity.reference hops, so grouping " +
+            "can never multiply the measured rows.",
+    };
+}
+/** R8 — a report's @spine, started at @from; Owner resolves in @from's package (it must be
+ *  @from or an entity @from extends), whatever package the report is in. */
+function spineWalk(from, fromKey) {
+    return {
+        attr: OBJECT_REPORT_ATTR_SPINE,
+        ownerPkg: pkgOf(from),
+        hostName: fromKey,
+        start: `@from '${fromKey}'`,
+        startShort: `@from '${fromKey}'`,
+        toOneReason: "A @spine follows only @cardinality: one relationships and identity.reference hops, so each fact row " +
+            "joins at most one row of the spine entity and is never counted twice.",
+    };
+}
+/**
+ * Walk `Owner.hop[.hop...]` from `host`: Owner is `host` or an entity it
+ * extends, and every hop is a to-one `relationship.*` or an
+ * `identity.reference`. Returns the terminal entity, or undefined after
+ * reporting the first failure. D2 and R8 both run it; `walk` says which.
+ */
+function walkToOneVia(root, host, via, err, walk) {
+    const named = `@${walk.attr} '${via}'`;
+    const nameOf = (entity) => (entity === host ? walk.hostName : entity.resolutionKey());
+    const parts = splitDotted(via);
+    if (parts === undefined) {
+        err(`${named} must be Owner.hop[.hop...], starting at ${walk.startShort}.`);
+        return undefined;
+    }
+    const owner = resolveObjectRef(root, parts.owner, walk.ownerPkg).node;
+    if (!isSelfOrAncestor(owner, host)) {
+        err(`${named} must start at ${walk.start}.`);
+        return undefined;
+    }
+    let current = host;
+    for (const hopName of parts.path) {
+        const hop = childOfType(current, TYPE_RELATIONSHIP, hopName) ??
+            current
+                .children()
+                .find((c) => c.type === TYPE_IDENTITY && c.subType === IDENTITY_SUBTYPE_REFERENCE && c.name === hopName);
+        if (hop === undefined) {
+            err(`${named} names '${hopName}', which is not a relationship or identity.reference of ` +
+                `'${nameOf(current)}'.`);
+            return undefined;
+        }
+        const isReference = hop.type === TYPE_IDENTITY;
+        if (!isReference && hop.attr(RELATIONSHIP_ATTR_CARDINALITY) !== CARDINALITY_ONE) {
+            err(`${named} crosses relationship '${hopName}' on '${nameOf(current)}', which is not to-one. ` +
+                walk.toOneReason);
+            return undefined;
+        }
+        // ADR-0059 R3 — a hop target resolves in the package of the node that declares the
+        // hop's reference attribute, so an inherited hop means what it meant where it was written.
+        const target = refTarget(hop, isReference ? IDENTITY_REFERENCE_ATTR_REFERENCES : RELATIONSHIP_ATTR_OBJECT_REF);
+        if (target === undefined) {
+            err(`${named} hop '${hopName}' on '${nameOf(current)}' targets no object.`);
+            return undefined;
+        }
+        current = target;
+    }
+    return current;
+}
+/**
+ * The entity a dimension's `@via` reaches, walked from `declaring` with D2's rules,
+ * or undefined when the walk fails (D2 reports why). ADR-0059 R3: a dimension's `@of`
+ * resolves in this entity's package, so the loader's `resolveReferences` pass reuses
+ * the walk rather than restating it.
+ */
+export function dimensionViaTerminal(root, declaring, via) {
+    return walkToOneVia(root, declaring, via, () => { }, d2Walk(declaring));
+}
+function checkMeasure(ctx, measure) {
+    const err = (message) => ctx.sink.push(measure, ERR_INVALID_MEASURE, ctx.label, `: ${message}`, ctx.suffix);
+    // A measure's @default is a whole number: attr.int refuses a fraction (Rule A) and a
+    // non-number, so that is the one error. M7-M9 run only when @default is an integral
+    // number (Rule B: one mistake, one error).
+    const declaredDefault = measure.attr(REPORTING_ATTR_DEFAULT);
+    const invalidDefault = declaredDefault !== undefined && !(typeof declaredDefault === "number" && Number.isInteger(declaredDefault));
+    if (measure.isRatio()) {
+        checkRatioOperands(ctx, measure, err);
+        return;
+    }
+    if (measure.subType !== MEASURE_SUBTYPE_AGGREGATE)
+        return;
+    const checked = checkAggregateColumns(ctx, measure, err);
+    const clean = checked !== undefined;
+    const ofField = checked?.field;
+    // M7 / M8 — where a @default can apply. Only when M0–M4 passed and the @default is
+    // an integral number: one mistake, one error (the attribute type check reports a bad value).
+    if (clean && !invalidDefault && declaredDefault !== undefined) {
+        const agg = measure.agg();
+        if (agg === AGG_COUNT) {
+            err(`@default cannot apply to @agg: count. A count is never null (it is 0 when nothing matches); ` +
+                `remove @default.`);
+        }
+        else if ((agg === AGG_ANY || agg === AGG_ALL) &&
+            typeof declaredDefault === "number" &&
+            declaredDefault !== 0 &&
+            declaredDefault !== 1) {
+            // M9 — a boolean measure's @default is 0 (false) or 1 (true).
+            err(`@default '${declaredDefault}' on @agg '${agg}' must be 0 (false) or 1 (true): the measure is a boolean.`);
+        }
+        else if ((agg === AGG_MIN || agg === AGG_MAX) &&
+            ofField !== undefined &&
+            !NUMERIC_FIELD_SUBTYPES.includes(ofField.subType)) {
+            err(`@default is a number, but '${measure.ofColumns()[0]}', the @of of @agg '${agg}', is a ` +
+                `field.${ofField.subType}. A default is supported on numeric measures only.`);
+        }
+    }
+    // M5 — @segment names a segment of the owning entity.
+    const segment = measure.segmentName();
+    if (segment !== undefined && childOfType(ctx.host, TYPE_SEGMENT, segment) === undefined) {
+        err(`@segment '${segment}' names no segment of '${ctx.declaring.resolutionKey()}'.`);
+    }
+    // S1 / F2 — the measure's own row scope.
+    const filter = measure.filter();
+    if (filter !== undefined) {
+        checkFilter(filter, ctx.host, ctx.declaring.resolutionKey(), ctx.label, measure, ctx.suffix, ctx.sink);
+    }
+}
+/**
+ * M0–M4, in order; the first failure stops the chain (no M2+M3 double report).
+ * Returns undefined when one of them fired; otherwise `field` is the single
+ * resolved @of field (undefined for a tuple), for M7/M8.
+ */
+function checkAggregateColumns(ctx, measure, err) {
+    const agg = measure.agg();
+    const columns = measure.ofColumns();
+    // M0 — @of names the column aggregated. Only any / all may omit it: they then quantify the
+    // measure's row condition (@filter AND @segment) over the group, "some row (every row)
+    // passes", so they need a condition to quantify.
+    if (columns.length === 0 && agg !== undefined) {
+        if (agg !== AGG_ANY && agg !== AGG_ALL) {
+            err(`@agg '${agg}' needs @of, the column it aggregates. Only @agg any / all may omit @of, to ask ` +
+                `whether some row (any) or every row (all) passes the measure's @filter or @segment.`);
+            return undefined;
+        }
+        if (measure.filter() === undefined && measure.segmentName() === undefined) {
+            err(`@agg '${agg}' without @of quantifies the measure's row condition, but it declares neither ` +
+                `@filter nor @segment. Name a field.boolean in @of, or add the condition.`);
+            return undefined;
+        }
+        return { field: undefined };
+    }
+    // M1 — every @of item is a field of the owning entity.
+    const fields = [];
+    for (const item of columns) {
+        const parts = splitDotted(item);
+        if (parts === undefined || parts.path.length !== 1) {
+            err(`@of '${item}' must be Entity.field.`);
+            return undefined;
+        }
+        const named = resolveObjectRef(ctx.root, parts.owner, pkgOf(ctx.declaring)).node;
+        if (!isSelfOrAncestor(named, ctx.host)) {
+            err(`@of '${item}' must name a field of the owning entity '${ctx.declaring.resolutionKey()}'. ` +
+                `A measure aggregates its own entity's rows; declare it on the entity that owns the column.`);
+            return undefined;
+        }
+        const field = fieldOf(ctx.host, parts.path[0]);
+        if (field === undefined) {
+            err(`@of '${item}' names no field '${parts.path[0]}' on '${ctx.declaring.resolutionKey()}'.`);
+            return undefined;
+        }
+        // M10 — a measure aggregates scalars. A field.object (or a field carrying @objectRef) is a JSON
+        // document, which no port aggregates in a report.
+        if (field.subType === FIELD_SUBTYPE_OBJECT || objectRefOf(field) !== undefined) {
+            err(`@of '${item}' is a field.${field.subType}${objectRefOf(field) !== undefined ? " with an @objectRef" : ""}, ` +
+                `which a report cannot aggregate. Aggregate a scalar field of it.`);
+            return undefined;
+        }
+        fields.push(field);
+    }
+    // M2 — a tuple is a distinct count only.
+    if (columns.length > 1 && (agg !== AGG_COUNT || !measure.distinct())) {
+        err(`@of lists ${columns.length} columns; a tuple is legal only with @agg: count and @distinct: true ` +
+            `(a distinct count of the tuple).`);
+        return undefined;
+    }
+    // M3 — @distinct is a count modifier.
+    if (measure.distinct() && agg !== undefined && agg !== AGG_COUNT) {
+        err(`@distinct: true requires @agg: count, not '${agg}'.`);
+        return undefined;
+    }
+    // M4 — the aggregate must be meaningful for the column's type.
+    const field = fields.length === 1 ? fields[0] : undefined;
+    if (field === undefined || agg === undefined)
+        return { field };
+    const item = columns[0];
+    if ((agg === AGG_SUM || agg === AGG_AVG) && !NUMERIC_FIELD_SUBTYPES.includes(field.subType)) {
+        err(`@agg '${agg}' needs a numeric field (field.int, long, double, float, decimal or currency), ` +
+            `but '${item}' is field.${field.subType}.`);
+        return undefined;
+    }
+    if ((agg === AGG_MIN || agg === AGG_MAX) && UNORDERED_FIELD_SUBTYPES.includes(field.subType)) {
+        err(`@agg '${agg}' cannot order '${item}', a field.${field.subType}.`);
+        return undefined;
+    }
+    if ((agg === AGG_ANY || agg === AGG_ALL) && field.subType !== FIELD_SUBTYPE_BOOLEAN) {
+        err(`@agg '${agg}' needs a field.boolean, but '${item}' is field.${field.subType}.`);
+        return undefined;
+    }
+    return { field };
+}
+/** M6 — each operand names a measure.aggregate of the same entity whose result is a number. */
+function checkRatioOperands(ctx, ratio, err) {
+    const operands = [
+        [REPORTING_ATTR_NUMERATOR, ratio.numerator()],
+        [REPORTING_ATTR_DENOMINATOR, ratio.denominator()],
+    ];
+    for (const [attr, ref] of operands) {
+        if (ref === undefined)
+            continue; // missing operand is ERR_MISSING_REQUIRED_ATTR
+        const target = childOfType(ctx.host, TYPE_MEASURE, ref);
+        if (target === undefined) {
+            err(`@${attr} '${ref}' names no measure of '${ctx.declaring.resolutionKey()}'.`);
+        }
+        else if (target.subType !== MEASURE_SUBTYPE_AGGREGATE) {
+            err(`@${attr} '${ref}' is a measure.${target.subType}; a ratio's operands must be measure.aggregate ` +
+                `(a ratio of ratios is not supported).`);
+        }
+        else if (target instanceof MetaMeasure && isMetaObject(ctx.host) && isMetaRoot(ctx.root)) {
+            const result = measureResultSubType(target, ctx.host, ctx.root);
+            if (result !== undefined && !NUMERIC_FIELD_SUBTYPES.includes(result)) {
+                err(`@${attr} '${ref}' is a ${result} measure; a ratio divides numbers, so its operands must be numeric ` +
+                    `measures (a count, a sum, an avg, or a min or max of a numeric field).`);
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// S1 / F2 — a reporting-host @filter over its entity
+// ---------------------------------------------------------------------------
+/**
+ * Validate a canonical (post-desugar) attr.filter against `entity`'s fields:
+ * every key names a field (S1), every op is legal for that field (S1), and a
+ * relative-date operand sits on a date/timestamp, under a range op, with a
+ * valid ISO-8601 duration (F2). One error per offending clause op.
+ */
+function checkFilter(filter, entity, entityKey, hostLabel, host, suffix, sink) {
+    const err = (message) => sink.push(host, ERR_BAD_ATTR_FILTER, hostLabel, `: ${message}`, suffix);
+    for (const [key, clause] of Object.entries(filter)) {
+        if (key === FILTER_COMPOSE_OR || key === FILTER_COMPOSE_AND) {
+            if (!Array.isArray(clause)) {
+                err(`@filter '${key}' must be an array of sub-clauses.`);
+                continue;
+            }
+            for (const sub of clause) {
+                if (isPlainObject(sub))
+                    checkFilter(sub, entity, entityKey, hostLabel, host, suffix, sink);
+                else
+                    err(`@filter '${key}' contains a non-object sub-clause.`);
+            }
+            continue;
+        }
+        const field = fieldOf(entity, key);
+        if (field === undefined) {
+            err(`@filter names '${key}', which is not a field of '${entityKey}'.`);
+            continue;
+        }
+        if (!isPlainObject(clause) || Object.keys(clause).length === 0) {
+            err(`@filter on '${key}' must be an { op: value } object.`);
+            continue;
+        }
+        const allowed = opsForField(field);
+        for (const [op, operand] of Object.entries(clause)) {
+            if (!allowed.includes(op)) {
+                err(`@filter on '${key}' uses op '${op}', which is not allowed for field.${field.subType}. ` +
+                    `Allowed ops: ${allowed.join(", ") || "(none)"}.`);
+                continue;
+            }
+            const relative = relativeOperand(operand);
+            if (relative === undefined)
+                continue;
+            if (!isExactRelativeValue(relative)) {
+                err(`@filter on '${key}' has a malformed relative date ${JSON.stringify(relative)}; a relative date is ` +
+                    `exactly { now: "<ISO-8601 duration>" } with no other keys.`);
+                continue;
+            }
+            if (!TEMPORAL_FIELD_SUBTYPES.includes(field.subType)) {
+                err(`@filter on '${key}' uses a relative date ({ now: ... }), but '${key}' is field.${field.subType}; ` +
+                    `relative dates apply only to field.date and field.timestamp.`);
+                continue;
+            }
+            if (!RELATIVE_DATE_OPS.includes(op)) {
+                err(`@filter on '${key}' puts a relative date under op '${op}'; relative dates are legal only under ` +
+                    `gt, gte, lt and lte.`);
+                continue;
+            }
+            const duration = relative[FILTER_RELATIVE_NOW];
+            if (typeof duration !== "string" || !ISO_DURATION_RE.test(duration)) {
+                err(`@filter on '${key}' has relative date '${quoteValue(duration)}', which is not an ISO-8601 ` +
+                    `duration (e.g. '-P7D', '-PT12H').`);
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// R1–R7 — object.report
+// ---------------------------------------------------------------------------
+function checkReport(root, report, sink) {
+    const label = `report '${report.resolutionKey()}'`;
+    const err = (message, node = report, code = ERR_INVALID_REPORT) => sink.push(node, code, label, message);
+    // R4 — a report's fields and identity are derived, never declared.
+    // ADR-0039: own — the rule is about what the author declared on THIS report.
+    for (const child of report.ownChildren()) {
+        if (child.type === TYPE_FIELD || child.type === TYPE_IDENTITY) {
+            err(` declares ${childLabel(child)}; a report's fields and identity are derived ` +
+                `from @dimensions and @measures, never declared.`, child);
+        }
+    }
+    // R5 — a report is read-only, so any source it has is read-only.
+    // ADR-0039: resolving — an inherited source binds the report just the same.
+    for (const source of report.children().filter((c) => c.type === TYPE_SOURCE)) {
+        if (isWritableSource(source)) {
+            err(`: ${childLabel(source)} is writable; a report is read-only, so its source must ` +
+                `declare a read-only @kind (view, materializedView, storedProc or tableFunction).`, source);
+        }
+    }
+    // R10 — a report is read through a view. The other read-only kinds are not read by a plain
+    // SELECT (a stored procedure and a table function are called, not selected from), and no port
+    // lowers or serves them. A view or materialized view the adopter creates is declared
+    // `@kind: view` with `@unmanaged: true`; a SELECT reads either one.
+    // ADR-0039: resolving, as R5 reads it.
+    for (const source of report.children().filter(isReadOnlySource)) {
+        if (source.effectiveKind !== SOURCE_KIND_VIEW) {
+            err(`: ${childLabel(source)} has @kind '${source.effectiveKind}'; a report is read through a view, so its ` +
+                `source must be @kind: view. For a view or materialized view you create yourself, declare ` +
+                `@kind: view with @unmanaged: true.`, source);
+        }
+    }
+    // R11 — a report cannot be abstract: its fields are derived from its own @dimensions and
+    // @measures, no port reads or serves an abstract report, and report inheritance is not part of
+    // the vocabulary.
+    if (report.isAbstract) {
+        err(`: is abstract; a report cannot be abstract, because its fields are derived from its own @dimensions ` +
+            `and @measures and no port reads or serves an abstract report. Remove abstract: true.`);
+    }
+    // R1 — @from resolves to an object.entity. Without it, R2/R3/R6/R7, R8/R9 and
+    // the @filter have nothing to resolve against, so they are skipped.
+    const fromRef = reportFrom(report);
+    if (fromRef === undefined)
+        return; // missing @from is ERR_MISSING_REQUIRED_ATTR
+    const from = resolveObjectRef(root, fromRef, pkgOf(report)).node;
+    if (from === undefined) {
+        err(`: @from '${fromRef}' does not resolve to an object.`);
+        return;
+    }
+    if (from.type !== TYPE_OBJECT || from.subType !== OBJECT_SUBTYPE_ENTITY) {
+        err(`: @from '${fromRef}' is an ${from.type}.${from.subType}; a report aggregates the rows of an object.entity.`);
+        return;
+    }
+    const fromKey = from.resolutionKey();
+    // R6 — derived field name -> the item that derived it ("dimension item 'x'" / "measure 'y'").
+    const derived = new Map();
+    const claim = (fieldName, what) => {
+        const prior = derived.get(fieldName);
+        if (prior === what) {
+            // The same measure listed twice: name the repeat, not a "collision" with itself.
+            err(`: @measures lists '${fieldName}' more than once.`);
+            return;
+        }
+        if (prior !== undefined) {
+            err(`: ${prior} and ${what} both derive report field '${fieldName}'. Report field names must be unique; ` +
+                `rename the measure or drop one item.`);
+            return;
+        }
+        derived.set(fieldName, what);
+    };
+    // R2 — each @dimensions item names a dimension of @from, with a grain exactly when it is a time dimension.
+    const seenItems = new Set();
+    for (const item of reportDimensionItems(report)) {
+        const raw = item.grain === undefined ? item.name : `${item.name}:${item.grain}`;
+        if (seenItems.has(raw)) {
+            err(`: @dimensions lists '${raw}' more than once.`);
+            continue;
+        }
+        seenItems.add(raw);
+        const dim = childOfType(from, TYPE_DIMENSION, item.name);
+        if (!(dim instanceof MetaDimension)) {
+            err(`: @dimensions item '${raw}' names no dimension of @from '${fromKey}'.`);
+            continue;
+        }
+        if (dim.isTime()) {
+            const grains = dim.grains();
+            if (item.grain === undefined) {
+                err(`: @dimensions item '${raw}' names time dimension '${item.name}' without a grain; write ` +
+                    `'${item.name}:<grain>' with a grain from its @grains (${grains.join(", ")}).`);
+                continue;
+            }
+            if (!grains.includes(item.grain)) {
+                err(`: @dimensions item '${raw}' uses grain '${item.grain}', which time dimension '${item.name}' does not ` +
+                    `declare. Its @grains: ${grains.join(", ")}.`);
+                continue;
+            }
+        }
+        else if (item.grain !== undefined) {
+            err(`: @dimensions item '${raw}' gives a grain to attribute dimension '${item.name}'; only a time ` +
+                `dimension takes a grain.`);
+            continue;
+        }
+        claim(reportDerivedFieldName(item), `dimension item '${raw}'`);
+    }
+    // R3 — each @measures item names a measure of @from.
+    for (const item of reportMeasureNames(report)) {
+        const measureName = checkReportMeasure(root, report, from, item, label, sink);
+        if (measureName !== undefined)
+            claim(measureName, `measure '${measureName}'`);
+    }
+    // R7 — @segment names a segment of @from.
+    const segment = report.attr(OBJECT_REPORT_ATTR_SEGMENT);
+    if (typeof segment === "string" && childOfType(from, TYPE_SEGMENT, segment) === undefined) {
+        err(`: @segment '${segment}' names no segment of @from '${fromKey}'.`);
+    }
+    // R8 — @spine is a to-one path from @from: rule D2's walk, started at @from.
+    const spine = reportSpine(report);
+    if (spine !== undefined) {
+        const terminal = walkToOneVia(root, from, spine, (message) => err(`: ${message}`), spineWalk(from, fromKey));
+        // R9 — every listed dimension is reached through the spine. Skipped when R8 failed.
+        if (terminal !== undefined) {
+            const spineHops = splitDotted(spine)?.path ?? [];
+            const items = reportDimensionItems(report);
+            if (items.length === 0) {
+                err(`: @spine '${spine}' needs at least one dimension. The report's rows are the dimension tuples of ` +
+                    `'${terminal.resolutionKey()}'; with no dimension it would be one totals row.`);
+            }
+            // One verdict per dimension, however many grains list it.
+            const checkedDimensions = new Set();
+            for (const item of items) {
+                if (checkedDimensions.has(item.name))
+                    continue;
+                checkedDimensions.add(item.name);
+                const dim = childOfType(from, TYPE_DIMENSION, item.name);
+                if (!(dim instanceof MetaDimension))
+                    continue; // R2 already reported it
+                const via = dim.via();
+                if (via === undefined) {
+                    err(`: dimension '${item.name}' is read from @from '${fromKey}', so it has no value in a row that has ` +
+                        `no facts. With @spine '${spine}' every dimension must be reached through it: declare the ` +
+                        `dimension over a field of '${terminal.resolutionKey()}' (or an entity to-one from it) with an ` +
+                        `@via that begins '${spine}'.`);
+                    continue;
+                }
+                // A @via that does not walk is D2's error, on the dimension; R9 does not report it again.
+                const discard = () => undefined;
+                if (walkToOneVia(root, from, via, discard, d2Walk(dim.parent ?? from)) === undefined)
+                    continue;
+                // Hop names are compared as written; the owner segment is not compared.
+                const hops = splitDotted(via)?.path ?? [];
+                if (spineHops.every((h, i) => hops[i] === h))
+                    continue;
+                err(`: dimension '${item.name}' is reached by @via '${via}', which does not begin with the hops of ` +
+                    `@spine '${spine}'. Hop names are compared as written: if both name the same join, write the same ` +
+                    `hops; otherwise the dimension is not reached through the spine.`);
+            }
+        }
+    }
+    // S1 / F2 — the report's row scope over @from.
+    const filter = report.attr(OBJECT_REPORT_ATTR_FILTER);
+    if (isPlainObject(filter))
+        checkFilter(filter, from, fromKey, label, report, "", sink);
+}
+/**
+ * R3 for one `@measures` item (bare `name` or dotted `Entity.name`). Returns
+ * the measure's name when it is a measure of @from (for R6), else reports
+ * ERR_REPORT_FOREIGN_MEASURE (it is another entity's measure) or
+ * ERR_INVALID_REPORT (it is nobody's) and returns undefined.
+ */
+function checkReportMeasure(root, report, from, item, label, sink) {
+    const fromKey = from.resolutionKey();
+    let owner;
+    let name;
+    const parts = splitDotted(item);
+    if (parts !== undefined && parts.path.length === 1) {
+        owner = resolveObjectRef(root, parts.owner, pkgOf(report)).node;
+        name = parts.path[0];
+        if (owner !== undefined && isSelfOrAncestor(owner, from) && childOfType(from, TYPE_MEASURE, name))
+            return name;
+        if (owner !== undefined && childOfType(owner, TYPE_MEASURE, name) === undefined)
+            owner = undefined;
+    }
+    else if (!item.includes(CHILD_REF_SEPARATOR)) {
+        name = item;
+        if (childOfType(from, TYPE_MEASURE, name) !== undefined)
+            return name;
+        // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
+        owner = root
+            .children()
+            .find((o) => o.type === TYPE_OBJECT &&
+            o.subType === OBJECT_SUBTYPE_ENTITY &&
+            childOfType(o, TYPE_MEASURE, name) !== undefined);
+    }
+    else {
+        owner = undefined;
+    }
+    if (owner !== undefined) {
+        const ownerKey = owner.resolutionKey();
+        sink.push(report, ERR_REPORT_FOREIGN_MEASURE, label, ` lists measure '${item.slice(item.lastIndexOf(CHILD_REF_SEPARATOR) + 1)}', which belongs to ` +
+            `'${ownerKey}', not @from '${fromKey}'. All measures of a report come from @from; make a second ` +
+            `report over '${ownerKey}'.`);
+    }
+    else {
+        sink.push(report, ERR_INVALID_REPORT, label, `: @measures item '${item}' names no measure of @from '${fromKey}' or of any other entity.`);
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// F1 — relative-date values only on reporting hosts
+// ---------------------------------------------------------------------------
+/** True for the hosts whose `@filter` may carry a relative-date value. */
+function isReportingFilterHost(node) {
+    return (node.type === TYPE_SEGMENT ||
+        (node.type === TYPE_MEASURE && node.subType === MEASURE_SUBTYPE_AGGREGATE) ||
+        (node.type === TYPE_OBJECT && node.subType === OBJECT_SUBTYPE_REPORT));
+}
+/**
+ * F1 — walk the whole tree and refuse a `{ now: ... }` value in any attr.filter
+ * outside a reporting host (a projection @filter, a dataGrid preset, an
+ * origin.aggregate/first @filter): those hosts have no lowering for it.
+ */
+function checkNoRelativeDates(node, sink) {
+    if (!isReportingFilterHost(node)) {
+        // ADR-0039: own — only locally declared filters are lowered, and the walk
+        // visits every declared node exactly once (an inherited filter is checked
+        // where it is declared; origin.* never inherits, ADR-0029).
+        for (const attr of node.ownMetaAttrs()) {
+            if (attr.subType === ATTR_SUBTYPE_FILTER && filterContainsRelativeValue(attr.value)) {
+                sink.push(node, ERR_BAD_ATTR_FILTER, nodeLabel(node), `: @${attr.name} uses a relative date ({ now: ... }), which is legal only in the ` +
+                    `@filter of a segment, measure.aggregate or object.report.`);
+            }
+        }
+    }
+    // ADR-0039: own — a tree walk; each declared node is visited once, at its declaration.
+    for (const child of node.ownChildren())
+        checkNoRelativeDates(child, sink);
+}
+//# sourceMappingURL=reporting-validation.js.map