Skip to content

Commit 446cc51

Browse files
committed
Merge remote-tracking branch 'origin/main' into fm/mo-list-null-order
# Conflicts: # CHANGELOG.md
2 parents e6af185 + 0ec0e45 commit 446cc51

55 files changed

Lines changed: 1843 additions & 73 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: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ number. Both patterns are the convergent-publishing rule working as intended. **
4646
`dist-tag rm` 403s for every token we hold (`docs/RELEASING.md` §4).
4747
`metamodelVersion` read **`1.0`** through 1.0.13 — C4 landed and G4 shipped it, and no 1.0.x patch
4848
moved it (1.0.4 relaxed `@sourceRefField` onto `@cardinality: one` with a prose-only
49-
manifest footprint, and was ruled a hold). **`metamodelVersion` now reads `1.1`** for the FR-044 reporting vocabulary and the requirements slice 1 (the first slice of two, covering existence gates and per-entity coverage). Per-release detail lives in **`CHANGELOG.md`** — it is the log, and this file does
49+
manifest footprint, and was ruled a hold). `metamodelVersion` read **`1.1`** from 1.1.0 for the FR-044 reporting vocabulary and the requirements slice 1 (the first slice of two, covering existence gates and per-entity coverage). **On `main` it now reads `1.2`** for calendar-aligned relative report windows (`startOf` on a relative date). Per-release detail lives in **`CHANGELOG.md`** — it is the log, and this file does
5050
not duplicate it.
5151

5252
The npm surface is **14 `@metaobjectsdev/*` packages in full lockstep**; the two `angular`
@@ -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/` (410 fixtures; 31 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/` (413 fixtures; 31 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: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,22 @@ here.**
1010

1111
## [Unreleased]
1212

13+
### Added
14+
15+
- **Calendar-aligned relative report windows.** A relative date in a report, segment or measure
16+
filter can now carry `startOf`: `{ "now": "-P90D", "startOf": "day" }` is midnight UTC 90 days
17+
back, where `{ "now": "-P90D" }` is 90 days before the moment of the query. `startOf` is `day`,
18+
`week` (ISO, Monday) or `month`; the duration is applied first, then the result is truncated.
19+
The truncation is written into the report view SQL for Postgres, SQLite/D1 and MySQL, so every
20+
port that reads the view gets it. Any other `startOf`, or an extra key, is refused with
21+
`ERR_BAD_ATTR_FILTER` in every port. Pinned by the `reporting-relative-startof`,
22+
`error-relative-date-bad-startof` and `error-relative-date-extra-key` conformance fixtures and
23+
the persistence `report-relative-date` scenario, which seeds a row a minute either side of the
24+
window start. UTC only; there is no time-zone form. **`metamodelVersion` moves `1.1` to `1.2`**
25+
(a new accepted filter value form, no registered attribute): a model that uses `startOf` needs
26+
every port at this version. A model that does not use it is unchanged. See
27+
[docs/features/reporting.md](docs/features/reporting.md#calendar-aligned-windows-startof).
28+
1329
### Changed
1430

1531
- **A list or report sort puts nulls last ascending and first descending, on every engine, in
@@ -21,6 +37,16 @@ here.**
2137
`col IS NULL` key where it does not (MySQL). Pinned by the api-contract `report/` scenario
2238
`sort-null-ordering`; see [api-contract.md](docs/features/api-contract.md#null-ordering).
2339

40+
### Fixed
41+
42+
- **A relative date with months or years now lands on the same day on SQLite and D1 as on
43+
Postgres and MySQL.** SQLite rolls an overflowing month shift into the next month, so
44+
`{ "now": "-P1M" }` on March 31 was March 3 in a SQLite view and February 28 on Postgres, and
45+
with `startOf: "month"` the window started a whole month late. The SQLite view SQL now clamps
46+
the shift to the last day of the target month, as Postgres and MySQL do, and applies years and
47+
months as one month count. A SQLite report view whose relative date has a month or year
48+
component gets new SQL, so `meta migrate` proposes recreating it; nothing else changes.
49+
2450
## [1.1.3] — 2026-10-26
2551

2652
_npm `1.1.3` (full lockstep across all 14 `@metaobjectsdev/*` publish candidates), PyPI `1.1.3`, NuGet `1.1.3` and Maven Central `8.1.3`._

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,8 @@ Only those last two rows make a measure other than `count`, or a dimension reach
6464

6565
A filter value `{ "now": "-P30D" }` (the current time plus a signed ISO-8601 duration) is legal only on a `field.date` or `field.timestamp`, under `gt`, `gte`, `lt` or `lte`, and only in the `@filter` of a `segment`, a `measure.aggregate` or an `object.report`. It is evaluated when the view is **queried**, against the UTC clock.
6666

67+
Add `"startOf": "day"`, `"week"` or `"month"` to cut the window to a calendar boundary: `{ "now": "-P90D", "startOf": "day" }` is midnight UTC, 90 days back, not 90 days before the moment of the query. The duration is applied first, then the result is truncated, and a week starts on Monday. No other unit is accepted (`ERR_BAD_ATTR_FILTER`), and there is no time-zone form.
68+
6769
## Nulls and zeros
6870

6971
- A `count` is `0` over nothing, never null. It counts rows whose `@of` column is not null; a tuple with any null component is not counted.

‎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) | 410 | ✓ | ✓ | inherits via `metadata-ktx` | ✓ | ✓ |
29+
| [`fixtures/conformance/`](../fixtures/conformance/) (metamodel) | 413 | ✓ | ✓ | 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/) | 37 | ✓ | ✓ | inherits via Java | ✓ | ✓ |
3232
| [`fixtures/verify-strict-conformance/`](../fixtures/verify-strict-conformance/) | 1 | ✓ | — | — | — | ✓ |
@@ -278,7 +278,7 @@ unit-test runners (`bun test`, `dotnet test`, `pytest`, `mvn test`) pull Docker.
278278

279279
## Fixture-to-doc mapping
280280

281-
### `fixtures/conformance/` — metamodel loader + canonical serializer (410)
281+
### `fixtures/conformance/` — metamodel loader + canonical serializer (413)
282282

283283
| Fixture prefix | Feature doc |
284284
|---|---|
@@ -554,7 +554,7 @@ files into a real Cube.
554554

555555
## Orphaned fixtures (tested but not yet documented)
556556

557-
The fixtures in the nine corpora mapped above (metamodel 410 + yaml 16 + verify 37
557+
The fixtures in the nine corpora mapped above (metamodel 413 + yaml 16 + verify 37
558558
+ render 16 + persistence 59 + api-contract 106 + source-resolution 25 + scope 10 +
559559
dependency 23) each map to a feature doc, and so do the two requirement corpora and the
560560
`cube-model` corpus, whose case lists live in their own READMEs. None are orphaned today. The remaining

‎docs/features/cube-export.md‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ joins, dimensions, measures, segments, and a rollup for each served report._
88
listed by `meta gen --list`, imported from its package to run as shipped (or copied into your
99
repo with `meta eject cube-model` to change it), and checked by `meta verify --codegen`. It is not core: what MetaObjects guarantees is the vocabulary and
1010
the loader's checks on it, and a generator that writes files into your repo is a helper you can
11-
copy and own. It adds no vocabulary (`metamodelVersion` stays 1.1) and has no runtime: the
11+
copy and own. It adds no vocabulary and has no runtime: the
1212
files it writes import nothing.
1313

1414
**What it does.** For each concrete entity that has a table and declares a `dimension`,
@@ -680,8 +680,7 @@ jobs API) before a query can use them.
680680

681681
## Compatibility
682682

683-
Nothing here changes a model or a file you already have. No vocabulary was registered, and
684-
`metamodelVersion` stays 1.1. The report view lowering and the exporter now share one SQL
683+
Nothing here changes a model or a file you already have. No vocabulary was registered. The report view lowering and the exporter now share one SQL
685684
module, a move that left every view's bytes as they were. No other generator's output changed.
686685

687686
The design, the contract tables and the decisions made while building it are in

‎docs/features/reporting.md‎

Lines changed: 41 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,8 @@ Closed sets:
6969
`@spine` is a path written like a dimension's `@via`. A measure's `@default` is an integer.
7070

7171
Plus one new value form inside the existing portable filter grammar: the **relative date**
72-
`{ "now": "<ISO-8601 duration>" }` (see [Relative dates](#relative-dates-in-filters)).
72+
`{ "now": "<ISO-8601 duration>" }`, optionally with `"startOf"` (see
73+
[Relative dates](#relative-dates-in-filters)).
7374

7475
## Declaring one
7576

@@ -877,10 +878,35 @@ signed duration (`-P7D` is seven days ago, `-PT12H` twelve hours ago):
877878
It is evaluated when the view is **queried**, not when it is created. A view that uses it
878879
is therefore not cacheable by query text.
879880

881+
#### Calendar-aligned windows: `startOf`
882+
883+
A bare `-P90D` is 90 days before the moment of the query, so the window start moves through
884+
the day and a daily report counts a partial day at its oldest edge. Add `startOf` to cut the
885+
start to a calendar boundary:
886+
887+
```jsonc
888+
"@filter": { "occurredAt": { "gte": { "now": "-P90D", "startOf": "day" } } }
889+
```
890+
891+
| `startOf` | The window starts at |
892+
|---|---|
893+
| `day` | 00:00 UTC of the day the shifted instant falls on |
894+
| `week` | 00:00 UTC on the Monday of that ISO week |
895+
| `month` | 00:00 UTC on the first of that month |
896+
897+
The duration is applied first and the result is then truncated: `{ "now": "-P1M", "startOf":
898+
"month" }` is the first of last month, and `{ "now": "P0D", "startOf": "month" }` is the first
899+
of this month. The cut is in UTC, the same clock as the time grains. There is no time-zone
900+
form; a window aligned to another zone is a separate piece of work. The view SQL carries the
901+
truncation on Postgres, SQLite (and D1) and MySQL, so every port that reads the view gets it.
902+
903+
Only `day`, `week` and `month` are accepted. The key is legal exactly where `now` is, and
904+
only beside `now`.
905+
880906
| Rule | Code | Refused |
881907
|---|---|---|
882908
| **F1** | `ERR_BAD_ATTR_FILTER` | A relative value anywhere except the `@filter` of a `segment`, a `measure.aggregate` or an `object.report`. In a `layout.dataGrid` preset, a projection `@filter` or an `origin.aggregate` `@filter` it fails the load, because no lowering exists for those hosts. |
883-
| **F2** | `ERR_BAD_ATTR_FILTER` | A relative value on any field except a `field.date` or `field.timestamp`; under any operator except `gt, gte, lt, lte`; as an object that carries keys besides `now`; or with a duration that does not match the ISO-8601 pattern `^[+-]?P(?!$)(\d+Y)?(\d+M)?(\d+W)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+S)?)?$`. |
909+
| **F2** | `ERR_BAD_ATTR_FILTER` | A relative value on any field except a `field.date` or `field.timestamp`; under any operator except `gt, gte, lt, lte`; as an object that carries keys besides `now` and `startOf`; with a duration that does not match the ISO-8601 pattern `^[+-]?P(?!$)(\d+Y)?(\d+M)?(\d+W)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+S)?)?$`; or with a `startOf` other than `day`, `week` or `month`. |
884910

885911
An operator-less `{ "occurredAt": { "now": "-P7D" } }` is read as `eq`, and `eq` is not one
886912
of the four operators a relative date may sit under, so it is refused.
@@ -903,17 +929,26 @@ A model that declares no reporting vocabulary gets nothing new from it. Outside
903929
loads changes in two places: a bare `extends` naming an object in another package is refused in
904930
TypeScript, Python and C#, and fixes to Java and Python parsing bugs move those ports toward what
905931
TypeScript already did. The [CHANGELOG](../../CHANGELOG.md) lists them and the models they affect,
906-
and [upgrading-1.0-to-1.1.md](migrations/upgrading-1.0-to-1.1.md) the upgrade steps. Until 1.1
907-
ships, `main` carries `metamodelVersion` 1.1, so no 1.0.x PATCH is cut from it.
932+
and [upgrading-1.0-to-1.1.md](migrations/upgrading-1.0-to-1.1.md) the upgrade steps. 1.1
933+
shipped with `metamodelVersion` 1.1; `main` now carries 1.2 (below), so no 1.1.x PATCH is cut
934+
from it.
935+
936+
`startOf` on a relative date is a second MINOR: `metamodelVersion` moves `1.1` to `1.2`. It
937+
is a new accepted value form inside `attr.filter`, so no registered attribute changed, and a
938+
model that does not use it loads and generates exactly as before. A model that uses it needs
939+
every port at this version, because an older loader refuses the extra key as a malformed
940+
relative date. The view SQL changes only for a report that declares it, and for a SQLite view
941+
whose relative date shifts by months or years, which now clamps to the end of a short month
942+
as Postgres and MySQL do.
908943

909944
`@spine` and a measure's `@default` joined the same 1.1 change before it shipped, so
910-
`metamodelVersion` stays 1.1. A model that uses neither generates exactly as before. No
945+
`metamodelVersion` did not move for them. A model that uses neither generates exactly as before. No
911946
generator you can own changed for them (the view SQL and the model pages' wording come from the
912947
packages), so an owned generator needs no resync. A report that declares
913948
`@spine`, or lists a measure with `@default`, lowers to different SQL and a tighter row type
914949
than the same report without it.
915950

916-
Serving reports added no vocabulary (`metamodelVersion` stays 1.1). The same change corrected
951+
Serving reports added no vocabulary and did not move `metamodelVersion`. The same change corrected
917952
generated output for models that declare no report. Each is in the
918953
[CHANGELOG](../../CHANGELOG.md) with the shape it affects:
919954

‎docs/superpowers/specs/2026-10-02-fr-044-core-reporting-design.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -273,6 +273,14 @@ An `attr.filter` value form meaning "the current time plus an ISO-8601 duration"
273273
against `field.timestamp` and `field.date`. Evaluated when the view is **queried**, not when
274274
it is created.
275275

276+
*Amendment (calendar windows):* the value may also carry `startOf: day | week | month`
277+
(`{ now: "-P90D", startOf: "day" }`). The duration is applied, then the instant is truncated to
278+
the start of that UTC calendar unit (ISO week, Monday). It lowers on Postgres, SQLite/D1 and
279+
MySQL in the report view SQL, is validated by rule F2 in every port, and is pinned by the
280+
`reporting-relative-startof` and `error-relative-date-*` conformance fixtures and by the
281+
persistence `report-relative-date` scenario. Time zones are not part of it. `metamodelVersion`
282+
`1.2`.
283+
276284
**ADR-0037:** a new value form inside an existing registered grammar, not a new attribute.
277285
**Admission:** RDB `now() - interval` (PG) / `strftime('%Y-%m-%dT%H:%M:%fZ','now','-7 days')`
278286
(SQLite, matching the ISO text storage adapters use); MongoDB `$$NOW` arithmetic; Search date

‎examples/showcase/site-payload.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,10 @@
44
"pypi": "1.1.3",
55
"nuget": "1.1.3",
66
"maven": "8.1.3",
7-
"metamodel": "1.1"
7+
"metamodel": "1.2"
88
},
99
"counts": {
10-
"fixtures": 410,
10+
"fixtures": 413,
1111
"corpora": 31,
1212
"baseTypes": 17
1313
},

‎fixtures/agent-context-conformance/java-kotlin-react-tanstack/expected/.claude/skills/metaobjects-authoring/references/reporting.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,8 @@ Only those last two rows make a measure other than `count`, or a dimension reach
6464

6565
A filter value `{ "now": "-P30D" }` (the current time plus a signed ISO-8601 duration) is legal only on a `field.date` or `field.timestamp`, under `gt`, `gte`, `lt` or `lte`, and only in the `@filter` of a `segment`, a `measure.aggregate` or an `object.report`. It is evaluated when the view is **queried**, against the UTC clock.
6666

67+
Add `"startOf": "day"`, `"week"` or `"month"` to cut the window to a calendar boundary: `{ "now": "-P90D", "startOf": "day" }` is midnight UTC, 90 days back, not 90 days before the moment of the query. The duration is applied first, then the result is truncated, and a week starts on Monday. No other unit is accepted (`ERR_BAD_ATTR_FILTER`), and there is no time-zone form.
68+
6769
## Nulls and zeros
6870

6971
- A `count` is `0` over nothing, never null. It counts rows whose `@of` column is not null; a tuple with any null component is not counted.

‎fixtures/agent-context-conformance/java-react/expected/.claude/skills/metaobjects-authoring/references/reporting.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,8 @@ Only those last two rows make a measure other than `count`, or a dimension reach
6464

6565
A filter value `{ "now": "-P30D" }` (the current time plus a signed ISO-8601 duration) is legal only on a `field.date` or `field.timestamp`, under `gt`, `gte`, `lt` or `lte`, and only in the `@filter` of a `segment`, a `measure.aggregate` or an `object.report`. It is evaluated when the view is **queried**, against the UTC clock.
6666

67+
Add `"startOf": "day"`, `"week"` or `"month"` to cut the window to a calendar boundary: `{ "now": "-P90D", "startOf": "day" }` is midnight UTC, 90 days back, not 90 days before the moment of the query. The duration is applied first, then the result is truncated, and a week starts on Monday. No other unit is accepted (`ERR_BAD_ATTR_FILTER`), and there is no time-zone form.
68+
6769
## Nulls and zeros
6870

6971
- A `count` is `0` over nothing, never null. It counts rows whose `@of` column is not null; a tuple with any null component is not counted.

0 commit comments

Comments
 (0)