Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ PyPI has had no product change since `0.25.0` — nothing is broken.
- **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.

**Cross-port conformance corpora** (every port runs the shared corpus):
- 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.
- 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.
- Render: `fixtures/render-conformance/`. TS / C# / Java / Kotlin / Python byte-identical.
- 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".)
- 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.
Expand Down
39 changes: 32 additions & 7 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,38 @@ here.**

## [Unreleased]

**New metamodel vocabulary: `measure.derived` and its `@expr`.** It is additive: nothing that
loaded before stops loading. This vocabulary ships in 1.3.0 with `metamodelVersion` 1.3 if it merges before the 1.3.0 publish; if it lands after, the next release moves `metamodelVersion`.

### Added

- **Report measures over Money and other value-object members (FR-044 R12).** A dimension's or
measure's `@of` may name `Entity.field.member`, a member of a value object stored with
`@storage: flattened` (`Payment.amount.amount`, `Payment.amount.currency`); the report reads
the member's own column. A `sum`, `avg`, `min` or `max` of a numeric member loads only when the
report lists a dimension over each non-numeric member of the same value object (its
currency), so amounts in different currencies are never combined; the rule follows the
measure into ratio and derived-measure operands. A member of a jsonb value object, an unknown
member and a deeper path are refused at load, and the Cube exporter refuses member paths.
Loader rules and report-shape derivation in TypeScript, C#, Java and Python.
- **`measure.derived`: arithmetic between measures (FR-044 R13).** `@expr` is FR-037 R5's
first arithmetic wave: `add`, `subtract`, `multiply` and `divide` over two operands, where an
operand is `{ "field": <name> }` (a numeric `measure.aggregate` or `measure.ratio` of the
entity, or a numeric attribute dimension the report lists) or `{ "value": <number> }`. It
expresses a ratio scaled to a percent and a measure over a grouped quantity (utilization =
billable hours × 100 ÷ (weekly capacity × 52 ÷ 12); budget burn = cost ÷ budget). The result
is a nullable `decimal`; `divide` reads null on a zero divisor. `meta migrate` lowers it on
Postgres, SQLite, MySQL and D1, every port reads and serves it, and the Cube exporter writes
one over measures as a `number` member (one reading a dimension is refused). Loader rule M11,
report rule R13 and a conformance fixture per refusal, in every loader port.

### Changed

- **Agent context routes report work to the reporting vocabulary.** The `meta init` agent guide
and the `metaobjects-authoring` skill now send grouped totals, dashboard numbers and read-only
report views to `object.report` (`references/declaring-reports.md`) before the `@sql` escape,
which they describe as the last resort for bodies the vocabulary cannot express.

### Fixed

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

### Changed

- **Agent context routes report work to the reporting vocabulary.** The `meta init` agent guide
and the `metaobjects-authoring` skill now send grouped totals, dashboard numbers and read-only
report views to `object.report` (`references/declaring-reports.md`) before the `@sql` escape,
which they describe as the last resort for bodies the vocabulary cannot express.

## [1.3.0] — 2026-11-11

_npm `1.3.0` (full lockstep across all 14 `@metaobjectsdev/*` publish candidates)._
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,10 @@ and an `object.report` combines them by name. Four node kinds:
`field.boolean` `@of`, or no `@of` and a `@filter` or `@segment`: `{ "name": "hasError",
"@agg": "any", "@filter": { "success": false } }` is "some row has `success` false" (a row
whose condition is null does not pass);
- `measure.derived` — `@expr` arithmetic (`add`, `subtract`, `multiply`, `divide`, two operands
each) over `{ "field": <measure or numeric dimension> }` and `{ "value": <number> }`:
utilization is `billableHours × 100 ÷ (weeklyCapacityHours × 52 ÷ 12)`. A dimension it reads
must be in the report's `@dimensions`; it never reads another derived measure;
- `segment.filter` — a named, reusable `@filter` ("active purchase");
- `object.report` — a top-level object: `@from` an entity, `@dimensions` (`name` or
`name:grain`), `@measures`.
Expand Down Expand Up @@ -72,6 +76,11 @@ Three rules an author trips on:
measure (a time dimension at a grain is `<name><Grain>`, so `purchasedAt:day` is
`purchasedAtDay`). A `field.*` or `identity.*` child on a report is an error.

**Money.** `@of` may name a member of a `@storage: flattened` value object,
`Payment.amount.amount`. A `sum`, `avg`, `min` or `max` of it loads only when the report also
lists a dimension over each non-numeric member (`Payment.amount.currency`), so currencies are
never added together. A jsonb value object's members are refused.

Two questions to answer for every report:

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

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
derived fields are filterable, no `measure.derived`
(arithmetic between measures beyond `measure.ratio`), no query-time choice of dimensions or
derived fields are filterable, no product measure
(`sum(hours × rate)`), no member of a jsonb value object, no query-time choice of dimensions or
measures (a report is a fixed, compiled combination), and no time-zone vocabulary (grains and
relative dates are UTC). Column types, the null rules, Monday weeks and per-engine differences
are in `references/reporting.md`.
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ A report declares no fields. Its columns are one per `@dimensions` item in liste
| `min` / `max` | the measure's name | the `@of` field's type | no |
| `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 |
| `measure.ratio` | the measure's name | `decimal` | no |
| `measure.derived` | the measure's name | `decimal` | no |
| any measure above except `count`, declaring `@default` | the measure's name | as above | yes: it reads the default instead of null |
| 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 |

Expand All @@ -72,6 +73,7 @@ Add `"startOf": "day"`, `"week"` or `"month"` to cut the window to a calendar bo
- 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`.
- 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).
- 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`.
- 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.
- 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).

**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.
Expand Down
6 changes: 3 additions & 3 deletions docs/CONFORMANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ regenerate with `ls -d fixtures/<corpus>/*/ | wc -l` for directory-shaped corpor

| Corpus | Fixtures | TS | Java | Kotlin | C# | Python |
|---|---|---|---|---|---|---|
| [`fixtures/conformance/`](../fixtures/conformance/) (metamodel) | 471 | ✓ | ✓ | inherits via `metadata-ktx` | ✓ | ✓ |
| [`fixtures/conformance/`](../fixtures/conformance/) (metamodel) | 490 | ✓ | ✓ | inherits via `metadata-ktx` | ✓ | ✓ |
| [`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 |
| [`fixtures/verify-conformance/`](../fixtures/verify-conformance/) | 45 | ✓ | ✓ | inherits via Java | ✓ | ✓ |
| [`fixtures/verify-strict-conformance/`](../fixtures/verify-strict-conformance/) | 1 | ✓ | — | — | — | ✓ |
Expand Down Expand Up @@ -354,7 +354,7 @@ unit-test runners (`bun test`, `dotnet test`, `pytest`, `mvn test`) pull Docker.

## Fixture-to-doc mapping

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

| Fixture prefix | Feature doc |
|---|---|
Expand Down Expand Up @@ -716,7 +716,7 @@ JSON and verify payload feeds it unchanged.

## Orphaned fixtures (tested but not yet documented)

The fixtures in the nine corpora mapped above (metamodel 471 + yaml 16 + verify 45
The fixtures in the nine corpora mapped above (metamodel 490 + yaml 16 + verify 45
+ render 18 + persistence 62 + api-contract 123 + source-resolution 25 + scope 10 +
dependency 47) each map to a feature doc, and so do the two requirement corpora, `shared-model-conformance`, the
`cube-model` corpus and `explorer-conformance`, whose case lists live in their own READMEs. None are orphaned today. The remaining
Expand Down
6 changes: 5 additions & 1 deletion docs/features/cube-export.md
Original file line number Diff line number Diff line change
Expand Up @@ -327,6 +327,7 @@ somewhere to go: an `identity.reference` onto an entity that is not a cube makes
| `measure.ratio` | `type: number`. Postgres: `CAST({num} AS NUMERIC) / NULLIF({den}, 0)`. MySQL: `{num} / NULLIF({den}, 0)`. |
| a `measure.aggregate` with `@default: n` | two members. `<m>Raw` is the aggregate as the rows above write it (its `type`, `sql` and `filters`), with `public: false`. `<m>` is `type: number` (`type: boolean` for an `any` or `all`, where `n` is written `TRUE` / `FALSE` on Postgres and `1` / `0` on MySQL), `sql: 'COALESCE({<m>Raw}, n)'`, and carries the measure's `title` and `description`. |
| a `measure.ratio` with `@default: n` | `type: number`, the quotient above inside `COALESCE(…, n)` |
| `measure.derived` | `type: number`, `sql` the `@expr` over the operand measures' members (each operand is its full Cube expression, as in a ratio). `divide` is `CAST(x AS NUMERIC) / NULLIF(y, 0)` on Postgres and `x / NULLIF(y, 0)` on MySQL. A `@expr` that reads a dimension (not a measure) is `ERR_CUBE_DERIVED_DIMENSION`. |

In a ratio, `{num}` and `{den}` are references to the two operand measures, so each operand is
its full Cube expression, condition included, and an operand need not be listed in any report.
Expand Down Expand Up @@ -491,6 +492,8 @@ are printed in its messages and are not loader codes.
| `ERR_CUBE_NAME_COLLISION` | two cubes, or a cube and a view, would have one name |
| `ERR_CUBE_UNESCAPABLE_LITERAL` | a literal, an identifier or free text that is raw-wrapped (it holds a Jinja opener) holds `endraw` |
| `ERR_CUBE_UNSUPPORTED_DIALECT` | the dialect is neither `postgres` nor `mysql` and the run would write a cube |
| `ERR_CUBE_VALUE_OBJECT_MEMBER` | an `@of` names a value-object member (`Entity.field.member`); the exporter does not map it |
| `ERR_CUBE_DERIVED_DIMENSION` | a `measure.derived` `@expr` reads a dimension rather than a measure |

## Which files a run writes

Expand Down Expand Up @@ -676,7 +679,8 @@ jobs API) before a query can use them.
- **No `sqlite` or `d1`.** See [Dialects](#wiring-it).
- **No `extends`, no `refresh_key`, no partitions, no `format`.** The exporter writes cubes, and
a Cube view only for a served `@spine` report.
- **No derived measure.** `measure.derived` is not registered, so there is nothing to map.
- **No member of a value object.** An `@of` naming `Entity.field.member` is `ERR_CUBE_VALUE_OBJECT_MEMBER`
(see [What the exporter refuses](#what-the-exporter-refuses)). Read it through a report view instead.

## Compatibility

Expand Down
Loading
Loading