Skip to content

Commit 6333671

Browse files
committed
feat(reporting): measure.derived in C#, Java and Python; docs and gates (FR-044 R13)
Ports measure.derived (M11 @expr validation, R13 dimension operands, the nullable-decimal column type) to the C#, Java and Python loaders, so all four loader ports pass the shared derived and value-object fixtures. Also: - docs: reporting.md, the authoring skill references, the FR-044 spec (R11 amendment) and an FR-037 R5 note; CHANGELOG under Unreleased. - a measureDerived requirement, with the requirement harness regenerated. - fixture counts (490) in AGENTS.md and CONFORMANCE.md, the site payload and the site reference regenerated. - cube-members.ts: imports moved above valueObjectMemberError, so the eject scanner sees every import and the ejected cube template compiles. - Java: a measure whose @agg is outside the closed set no longer throws an NPE in the value-object unit check. - test typecheck fixes for the derived and value-object Cube tests.
1 parent 2778e10 commit 6333671

60 files changed

Lines changed: 1204 additions & 107 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ PyPI has had no product change since `0.25.0` — nothing is broken.
7171
- **Kotlin** — `codegen-kotlin` (KotlinPoet on JVM): entity + Exposed table + Spring controller + payload + relations + filter allowlist + validator + stored-proc + output-parser generators. `integration-tests-kotlin` runs the persistence-conformance corpus through Exposed against Testcontainers Postgres.
7272

7373
**Cross-port conformance corpora** (every port runs the shared corpus):
74-
- Metamodel: `fixtures/conformance/` (471 fixtures; 38 shared corpora in total — per-corpus counts + the corpus x port matrix live in `docs/CONFORMANCE.md`). TS / C# / Java / Python all green.
74+
- Metamodel: `fixtures/conformance/` (490 fixtures; 38 shared corpora in total — per-corpus counts + the corpus x port matrix live in `docs/CONFORMANCE.md`). TS / C# / Java / Python all green.
7575
- Render: `fixtures/render-conformance/`. TS / C# / Java / Kotlin / Python byte-identical.
7676
- Persistence: `fixtures/persistence-conformance/`. **Query** scenarios run on every port (TS / C# / Java / Kotlin / Python), each provisioning its test DB by executing the committed, TS-produced `canonical/schema.postgres.sql` (Postgres only — Derby dropped for the cross-port query corpus, ADR-0015; the FR-044 `report-*` scenarios also run on SQLite, MySQL and D1 where a port has the engine, see [docs/CONFORMANCE.md](docs/CONFORMANCE.md)). The **migration** scenarios are exercised by **TS only** (TS owns schema migrations). **The corpus now gates WRITES, not just reads (SP-H):** an `op: roundtrip` scenario type INSERTs through each port's runtime/ORM write codec (NOT raw SQL), reads the row back, and asserts the wire-normalized value. The `AllTypes` entity (`roundtrip-all-types.yaml`) carries one field of **every** persistable `field.*` subtype — string/int/long/double/float/decimal/boolean/date/time/timestamp(+tz)/currency/enum/uuid/object — plus an **array-of-VO** `field.object @isArray @storage:jsonb` column (`labels`, written as 2-element / empty-`[]` / single-element arrays across the three rows) — so every subtype write+read (incl. the array-of-value-object jsonb codec) round-trips through every port against Testcontainers PG. (`field.byte`/`field.short`/`field.class` were cut as non-functional registration-only stubs — the matrix tracks only genuinely-supported subtypes; see `fixtures/registry-conformance/README.md` → "Per-subtype write-round-trip matrix".)
7777
- API-contract: `fixtures/api-contract-conformance/`. TS / C# / Java / Kotlin / Python all green — each port runs **two lanes**: a hand-rolled reference server AND its **generated** API artifact booted over HTTP (the deployed controller/routes; TS+C# full-stack vs Testcontainers PG, Java/Kotlin/Python generated controller + in-memory repo behind the consumer seam). The generated fan-out found 10 real deployment bugs golden snapshots missed. Three sub-corpora run the **generated lane only, on all five ports** — `write-through/`, `projection/` (F22: a view-only `object.projection` serves GET list + GET by id and answers every write verb with `405 {"error": "method_not_allowed"}`) and `report/` (FR-044: a view-backed `object.report` serves GET list, answers `POST` with that same `405`, and mounts no `/{id}` route). That is deliberate, not a gap: what is under test is whether a port's GENERATOR emits those routes, and a hand-rolled reference server would answer every scenario by construction. The `m2m/` sub-corpus also gates **TPH x M:N together** (base-declared, subtype-declared, abstract-mid-declared, a non-subtype source onto a subtype TARGET, and the cross-subtype source id answering `200 []`) — the two corpora were originally built disjoint (`tph/` had no relationships, `m2m/` no discriminators), which is precisely how that defect class survived.

‎CHANGELOG.md‎

Lines changed: 32 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,38 @@ here.**
1010

1111
## [Unreleased]
1212

13+
**New metamodel vocabulary: `measure.derived` and its `@expr`.** It is additive: nothing that
14+
loaded before stops loading. If this ships after 1.3.0, the release moves `metamodelVersion`.
15+
16+
### Added
17+
18+
- **Report measures over Money and other value-object members (FR-044 R12).** A dimension's or
19+
measure's `@of` may name `Entity.field.member`, a member of a value object stored with
20+
`@storage: flattened` (`Payment.amount.amount`, `Payment.amount.currency`); the report reads
21+
the member's own column. A `sum`, `avg`, `min` or `max` of a numeric member loads only when the
22+
report lists a dimension over each non-numeric member of the same value object (its
23+
currency), so amounts in different currencies are never combined; the rule follows the
24+
measure into ratio and derived-measure operands. A member of a jsonb value object, an unknown
25+
member and a deeper path are refused at load, and the Cube exporter refuses member paths.
26+
Loader rules and report-shape derivation in TypeScript, C#, Java and Python.
27+
- **`measure.derived`: arithmetic between measures (FR-044 R13).** `@expr` is FR-037 R5's
28+
first arithmetic wave: `add`, `subtract`, `multiply` and `divide` over two operands, where an
29+
operand is `{ "field": <name> }` (a numeric `measure.aggregate` or `measure.ratio` of the
30+
entity, or a numeric attribute dimension the report lists) or `{ "value": <number> }`. It
31+
expresses a ratio scaled to a percent and a measure over a grouped quantity (utilization =
32+
billable hours × 100 ÷ (weekly capacity × 52 ÷ 12); budget burn = cost ÷ budget). The result
33+
is a nullable `decimal`; `divide` reads null on a zero divisor. `meta migrate` lowers it on
34+
Postgres, SQLite, MySQL and D1, every port reads and serves it, and the Cube exporter writes
35+
one over measures as a `number` member (one reading a dimension is refused). Loader rule M11,
36+
report rule R13 and a conformance fixture per refusal, in every loader port.
37+
38+
### Changed
39+
40+
- **Agent context routes report work to the reporting vocabulary.** The `meta init` agent guide
41+
and the `metaobjects-authoring` skill now send grouped totals, dashboard numbers and read-only
42+
report views to `object.report` (`references/declaring-reports.md`) before the `@sql` escape,
43+
which they describe as the last resort for bodies the vocabulary cannot express.
44+
1345
### Fixed
1446

1547
- **A projection view keeps the columns a reverse `@via` hop feeds.** An origin `@via` that walks
@@ -24,13 +56,6 @@ here.**
2456
rather than summing the flattened amount column, keeps a sum from adding amounts in different
2557
currencies. `count` is unaffected.
2658

27-
### Changed
28-
29-
- **Agent context routes report work to the reporting vocabulary.** The `meta init` agent guide
30-
and the `metaobjects-authoring` skill now send grouped totals, dashboard numbers and read-only
31-
report views to `object.report` (`references/declaring-reports.md`) before the `@sql` escape,
32-
which they describe as the last resort for bodies the vocabulary cannot express.
33-
3459
## [1.3.0] — 2026-11-11
3560

3661
_npm `1.3.0` (full lockstep across all 14 `@metaobjectsdev/*` publish candidates)._

‎agent-context/skills/metaobjects-authoring/references/declaring-reports.md‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,10 @@ and an `object.report` combines them by name. Four node kinds:
1818
`field.boolean` `@of`, or no `@of` and a `@filter` or `@segment`: `{ "name": "hasError",
1919
"@agg": "any", "@filter": { "success": false } }` is "some row has `success` false" (a row
2020
whose condition is null does not pass);
21+
- `measure.derived` — `@expr` arithmetic (`add`, `subtract`, `multiply`, `divide`, two operands
22+
each) over `{ "field": <measure or numeric dimension> }` and `{ "value": <number> }`:
23+
utilization is `billableHours × 100 ÷ (weeklyCapacityHours × 52 ÷ 12)`. A dimension it reads
24+
must be in the report's `@dimensions`; it never reads another derived measure;
2125
- `segment.filter` — a named, reusable `@filter` ("active purchase");
2226
- `object.report` — a top-level object: `@from` an entity, `@dimensions` (`name` or
2327
`name:grain`), `@measures`.
@@ -72,6 +76,11 @@ Three rules an author trips on:
7276
measure (a time dimension at a grain is `<name><Grain>`, so `purchasedAt:day` is
7377
`purchasedAtDay`). A `field.*` or `identity.*` child on a report is an error.
7478

79+
**Money.** `@of` may name a member of a `@storage: flattened` value object,
80+
`Payment.amount.amount`. A `sum`, `avg`, `min` or `max` of it loads only when the report also
81+
lists a dimension over each non-numeric member (`Payment.amount.currency`), so currencies are
82+
never added together. A jsonb value object's members are refused.
83+
7584
Two questions to answer for every report:
7685

7786
- **Do I want the rows that have no facts?** A report's rows come from the facts, so a
@@ -99,8 +108,8 @@ A report `@from` a TPH subtype is refused when its view is derived (the subtype
99108
base's table): declare it `@from` the base with an `@filter` on the discriminator field.
100109

101110
What does not exist: no grid or form for a report (TypeScript generates a list hook; no other port has a client tier), no way to narrow which
102-
derived fields are filterable, no `measure.derived`
103-
(arithmetic between measures beyond `measure.ratio`), no query-time choice of dimensions or
111+
derived fields are filterable, no product measure
112+
(`sum(hours × rate)`), no member of a jsonb value object, no query-time choice of dimensions or
104113
measures (a report is a fixed, compiled combination), and no time-zone vocabulary (grains and
105114
relative dates are UTC). Column types, the null rules, Monday weeks and per-engine differences
106115
are in `references/reporting.md`.

‎agent-context/skills/metaobjects-authoring/references/reporting.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ A report declares no fields. Its columns are one per `@dimensions` item in liste
4949
| `min` / `max` | the measure's name | the `@of` field's type | no |
5050
| `any` / `all` (boolean OR / AND, `bool_or` / `bool_and`; over a `field.boolean` `@of`, or with no `@of` over the measure's `@filter` / `@segment`) | the measure's name | `boolean` | no |
5151
| `measure.ratio` | the measure's name | `decimal` | no |
52+
| `measure.derived` | the measure's name | `decimal` | no |
5253
| any measure above except `count`, declaring `@default` | the measure's name | as above | yes: it reads the default instead of null |
5354
| in a `@spine` report, a dimension over a column of the spine entity | the dimension's name | the `@of` field's type | yes when the field is `@required` or in that entity's `identity.primary`; no for a dimension beyond the spine entity |
5455

@@ -72,6 +73,7 @@ Add `"startOf": "day"`, `"week"` or `"month"` to cut the window to a calendar bo
7273
- A `sum` of nothing is **null**, not zero: no matching rows, or a filtered measure that matched none of a group's rows. So are `avg`, `min` and `max`.
7374
- An `any` or `all` over no rows, or only null values, is **null**, not `false`. `"@default": 0` reads `false` and `"@default": 1` reads `true` (any other number is refused).
7475
- A ratio is `numerator / NULLIF(denominator, 0)`: a zero denominator is **null**. Each operand must be a numeric measure: a `count`, a `sum`, an `avg`, or a `min` or `max` of a numeric field. An `any` or `all` (a boolean), or a `min` or `max` of a date, timestamp, string, uuid or enum, is refused as `@numerator` or `@denominator`. For a share, use an `@agg: count` with a `@filter`.
76+
- A derived measure's `divide` divides as a ratio does (null on a zero divisor); a null operand makes it null, so default the operand measure when `0` is meant.
7577
- A report with no dimensions is one row for the whole table, and still one row over an empty table (counts `0`, sums and ratios null).
7678

7779
**Ask: is zero true here, or is null?** If "nothing to aggregate" means zero (revenue of a program nobody bought is `0`), declare `"@default": 0` on the measure (`revenue` in the example under "Rows with no facts"). If it means unknown (the average rating of a product with no ratings is not `0`), leave it null. Do not default in the client what the model can state once.

‎docs/CONFORMANCE.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ regenerate with `ls -d fixtures/<corpus>/*/ | wc -l` for directory-shaped corpor
2626

2727
| Corpus | Fixtures | TS | Java | Kotlin | C# | Python |
2828
|---|---|---|---|---|---|---|
29-
| [`fixtures/conformance/`](../fixtures/conformance/) (metamodel) | 471 | ✓ | ✓ | inherits via `metadata-ktx` | ✓ | ✓ |
29+
| [`fixtures/conformance/`](../fixtures/conformance/) (metamodel) | 490 | ✓ | ✓ | inherits via `metadata-ktx` | ✓ | ✓ |
3030
| [`fixtures/yaml-conformance/`](../fixtures/yaml-conformance/) | 16 | 16 / 16 | 15 / 16 (1 ledgered: `yaml-quoted-leading-zero` — Java pipeline strips quotes off `"007"`) | inherits via Java | 15 / 16 (1 ledgered: `error-yaml-coerced-hex-in-string` — YamlDotNet doesn't coerce `0xFF`) | 16 / 16 |
3131
| [`fixtures/verify-conformance/`](../fixtures/verify-conformance/) | 45 | ✓ | ✓ | inherits via Java | ✓ | ✓ |
3232
| [`fixtures/verify-strict-conformance/`](../fixtures/verify-strict-conformance/) | 1 | ✓ | — | — | — | ✓ |
@@ -354,7 +354,7 @@ unit-test runners (`bun test`, `dotnet test`, `pytest`, `mvn test`) pull Docker.
354354

355355
## Fixture-to-doc mapping
356356

357-
### `fixtures/conformance/` — metamodel loader + canonical serializer (471)
357+
### `fixtures/conformance/` — metamodel loader + canonical serializer (490)
358358

359359
| Fixture prefix | Feature doc |
360360
|---|---|
@@ -716,7 +716,7 @@ JSON and verify payload feeds it unchanged.
716716

717717
## Orphaned fixtures (tested but not yet documented)
718718

719-
The fixtures in the nine corpora mapped above (metamodel 471 + yaml 16 + verify 45
719+
The fixtures in the nine corpora mapped above (metamodel 490 + yaml 16 + verify 45
720720
+ render 18 + persistence 62 + api-contract 123 + source-resolution 25 + scope 10 +
721721
dependency 47) each map to a feature doc, and so do the two requirement corpora, `shared-model-conformance`, the
722722
`cube-model` corpus and `explorer-conformance`, whose case lists live in their own READMEs. None are orphaned today. The remaining

0 commit comments

Comments
 (0)