Skip to content

Commit 526ddc8

Browse files
committed
docs(reporting): upgrade notes for owned generators and review corrections (FR-044)
CHANGELOG: upgrade notes for an owned `routes` / `routes-hono` generator, an owned `mount-read-only.ts` and a hand-written generator gating on `servesReadApi`; a new entry for the `idColumn` change; the "Changed" intro now says which entries change code and which change docs, and counts seven. Corrections: the sort error code in reporting.md is `invalid_sort`; the array- and map-valued sort caveat is stated per port; docs/README.md and docs/CONFORMANCE.md say a report is served; AGENTS.md counts three generated-lane-only sub-corpora; the authoring skill limits filter and sort to derived fields with filter operators; the C#, Java and Kotlin codegen references define a keyless projection as anything but a declared single-column identity; docs/ports/kotlin.md names the abstract report. Plan: one proof-table row per named behaviour change (2 to 8), with the no-churn constraint and the as-built list counting the same seven. Agent-context conformance fixtures regenerated from the edited skills.
1 parent efc2c91 commit 526ddc8

19 files changed

Lines changed: 105 additions & 46 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ PyPI has had no product change since `0.25.0` — nothing is broken.
7878
- Metamodel: `fixtures/conformance/` (364 fixtures; 26 shared corpora in total — per-corpus counts + the corpus x port matrix live in `docs/CONFORMANCE.md`). TS / C# / Java / Python all green.
7979
- Render: `fixtures/render-conformance/`. TS / C# / Java / Kotlin / Python byte-identical.
8080
- 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 **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".)
81-
- 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. Two sub-corpora run the **generated lane only, on all five ports** — `write-through/` and `projection/` (F22: a view-only `object.projection` serves GET list + GET by id and answers every write verb with `405 {"error": "method_not_allowed"}`). 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.
81+
- 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.
8282
- YAML / verify corpora green across the ports that ship those layers.
8383
- **Codegen-compile gate** (all five ports; a GATE, not a corpus — it has no fixtures of its own and no row in the matrix). Every corpus above gates BEHAVIOUR; none asks whether the emitted code BUILDS, which is how four "generated code does not compile" defects shipped in 1.0.4 with the whole matrix green — `gen` exits 0 in all four cases and the adopter's build is the first thing that disagrees. Each port generates from `fixtures/persistence-conformance/canonical/meta.fitness.json` (reused deliberately: a second kitchen sink would drift from the one the other corpora already maintain) and compiles the emitted tree with its real compiler — `ts.createProgram` / Roslyn / `javac` / `KotlinCompilation` / (Python, having no static compiler) importing the generated package plus `ruff` F821. **Every port excludes its framework-bound route tier** (TS `routesFile`, C# `RoutesGenerator`, Java `SpringControllerGenerator`, Kotlin `KotlinSpringControllerGenerator`): those imports are not on an in-memory compile's classpath and stubbing them drowns the signal, so that tier is proven by the api-contract integration lane instead. One cross-port rule, not four local concessions. Found 5 further real defects on first run. Boundary detail: `docs/CONFORMANCE.md` → "Split coverage".
8484

‎CHANGELOG.md‎

Lines changed: 39 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,18 @@ it until 1.1 ships._
112112
is also the first to assert a `field.date` literally. Anyone who declared a view-sourced
113113
report under the unreleased 1.1 vocabulary will see these files on the next `gen`. See
114114
[docs/features/reporting.md](docs/features/reporting.md#how-a-report-is-served).
115+
**Upgrading an owned TypeScript `routes` or `routes-hono` generator.** A copy ejected before
116+
this release holds the old template inline and still gates on `servesReadApi`, which is now
117+
true for a served report. Run against a model with one, it writes the report's route file
118+
from its projection branch: `GET /:id` and the three item refusals are mounted, with no
119+
`itemRoutes: false`. Re-eject it (`meta eject routes --force`, which also rewrites the
120+
adapter copy under `codegen/runtime/`), or add the `itemRoutes: false` and
121+
`resource: "report"` lines to your copy's read-only mount options. An owned
122+
`mount-read-only.ts` that predates those two options must be re-synced as well: a current
123+
routes generator passes them, and its output fails typecheck against the older
124+
`MountReadOnlyOptions`. A hand-written generator that gates on `servesReadApi`, or on
125+
`!isAbstract` as the `meta generator` scaffold does, now receives a served report's read
126+
model: gate UI output on `servesClientTier`.
115127
- **Reports have model and API pages in `meta docs` (FR-044).** Every report gets a model page
116128
(its `@from`, its view or "Not served" with the reason, its row scope, and a column table
117129
with a definition per column) listed under `## Reports` on the model index, and a page on the
@@ -132,22 +144,42 @@ it until 1.1 ships._
132144

133145
### Changed
134146

135-
Six corrections that shipped with report serving and reach models that declare no report.
136-
Each one changes generated output on the next `gen`, so the drift gate reports it until you
137-
regenerate.
147+
Seven corrections that shipped with report serving and reach models that declare no report.
148+
Each one changes generated code on the next `gen`, or generated docs on the next `meta docs`
149+
or Python api-docs build, as its entry says. A drift gate that covers that output reports it
150+
until you regenerate.
138151

139152
- **TypeScript and Python: a read-only projection with no declared identity and no field named
140153
`id` loses its item surface.** It no longer gets `GET /{id}` or the three item-verb refusals,
141154
its by-id query (`find<Name>ById` in TypeScript, `find_by_id` on the Python repository
142155
Protocol) or, in TypeScript, its detail hook and `detail` query keys. That surface could not
143156
address a row: TypeScript built the query with no `WHERE` and answered the view's first row,
144-
and Python bound an `id: int` to nothing. **Unchanged:** a projection with a declared
145-
identity (a composite one still binds its first field), and a projection with an `id` field
146-
and no declared identity. C#, Java and Kotlin are unchanged and remain stricter: they mount
157+
and Python bound an `id: int` to nothing. **Unchanged by this entry:** a projection with a
158+
declared identity (a composite one still binds its first field; the next entry covers one
159+
keyed on a field not named `id`), and a projection with an `id` field and no declared
160+
identity. C#, Java and Kotlin are unchanged and remain stricter: they mount
147161
`/{id}` only for a declared single-column identity, so a projection with an `id` field and no
148162
declared identity has item routes in TypeScript and Python and none in the other three. The
149163
TypeScript mounts (`mountReadOnlyCrudRoutes`, Fastify and Hono) take a new `itemRoutes: false`
150-
option for this; it defaults to mounting them.
164+
option for this; it defaults to mounting them. **Upgrading:** an owned `routes` or
165+
`routes-hono` generator ejected before this release keeps mounting the item routes for this
166+
shape until you re-eject it or add `itemRoutes: false` to its read-only mount options, and
167+
an owned `mount-read-only.ts` needs the re-sync described under the served-report entry
168+
above.
169+
- **TypeScript: a read-only projection whose identity is on a field not named `id` now
170+
addresses that field.** The shape: a view-only `object.projection` whose
171+
`identity.primary` names a single field such as `code`, or a composite identity whose first
172+
field is not `id`. Its generated `<Name>.routes.ts` / `<Name>.routes.hono.ts` gains one line
173+
in the read-only mount options, `idColumn: "<field>"`, the same field `find<Name>ById`
174+
already read. Before, the mount looked for a column `id`, found none, built the query with
175+
no `WHERE` and answered `GET /<path>/<anything>` with the view's first row. A projection
176+
keyed on `id` keeps its bytes. Both read-only mounts (Fastify and Hono) also stop answering
177+
with a row when the view has no column under `idColumn`: `GET /:id` now answers
178+
`404 {"error": "not_found"}`. That covers an owned routes generator that predates this
179+
line, as long as it imports the mounts from the package or from a re-synced owned copy.
180+
`itemRouteField` and `DEFAULT_ID_FIELD` are exported from `@metaobjectsdev/codegen-ts` for
181+
an owned routes generator. `idColumn` is the column's key in the Drizzle view (the field
182+
name), not its physical name.
151183
- **TypeScript: a `field.decimal` in a view read schema is `z.string()`, not `z.number()`.**
152184
Affects the generated read schema of any `object.projection` (and report) with a decimal
153185
field. The value Drizzle reads from a `numeric` view column was always a string, so the old

‎agent-context/skills/metaobjects-authoring/SKILL.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -743,8 +743,10 @@ Three rules an author trips on:
743743
**A report is served only when it declares `source.rdb` with `@kind: view`.** That declaration
744744
is what makes `meta migrate` create the view (Postgres, SQLite, D1), what every port's
745745
runtime reads, and what makes every port's generators serve it: one read-only list route at
746-
the pluralized snake_case name (`InvoicesByMonth` is `/invoices_by_months`), with filter,
747-
sort and paging on every derived field, `405` on `POST` and no `/{id}` route. A report with
746+
the pluralized snake_case name (`InvoicesByMonth` is `/invoices_by_months`), with paging,
747+
and filter and sort on every derived field whose type has filter operators (an `object` or
748+
`map` derived field is neither filterable nor sortable), `405` on `POST` and no `/{id}`
749+
route. A report with
748750
no `source.*` is checked at load and generates nothing.
749751

750752
A report `@from` a TPH subtype is refused when its view is derived (the subtype shares its

‎agent-context/skills/metaobjects-codegen/references/csharp.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -66,8 +66,9 @@ Its REST surface is generated and READ-ONLY (F22): GET list + GET by id, the sam
6666
`?filter[...]`/`?sort=` grammar as a table entity against allowlists built from the
6767
projection's OWN declared field set, and `POST` / `PATCH` / `PUT` / `DELETE` each
6868
answering `405 {"error": "method_not_allowed"}` — 405 and not 404 because the same
69-
path answers GET. A KEYLESS projection (no `identity.primary`) mounts no `/{id}` route
70-
at all, so it refuses only the collection verb.
69+
path answers GET. A KEYLESS projection mounts no `/{id}` route at all, so it refuses only
70+
the collection verb. Keyless here means anything but a declared single-column
71+
`identity.primary`: no identity, or a composite one.
7172

7273
Those refusals are mounted EXPLICITLY, not left to ASP.NET: unmounted, the framework
7374
answers its own 405 with an EMPTY body, which is a wire shape no other port sends.

‎agent-context/skills/metaobjects-codegen/references/java.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -169,8 +169,9 @@ Its REST surface is generated and READ-ONLY (F22): GET list + GET by id, the sam
169169
`?filter[...]`/`?sort=` grammar as a table entity against allowlists built from the
170170
projection's OWN declared field set, and `POST` / `PATCH` / `PUT` / `DELETE` each
171171
answering `405 {"error": "method_not_allowed"}` — 405 and not 404 because the same
172-
path answers GET. A KEYLESS projection (no `identity.primary`) mounts no `/{id}` route
173-
at all, so it refuses only the collection verb.
172+
path answers GET. A KEYLESS projection mounts no `/{id}` route at all, so it refuses only
173+
the collection verb. Keyless here means anything but a declared single-column
174+
`identity.primary`: no identity, or a composite one.
174175
`SpringControllerGenerator`, `SpringRepositoryGenerator` and `SpringFilterAllowlistGenerator`
175176
move together here — they share one emit predicate, because the generated controller names
176177
the other two. The repository interface a projection gets is the read-only one:

‎agent-context/skills/metaobjects-codegen/references/kotlin.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -179,8 +179,9 @@ Its REST surface is generated and READ-ONLY (F22): GET list + GET by id, the sam
179179
`?filter[...]`/`?sort=` grammar as a table entity against allowlists built from the
180180
projection's OWN declared field set, and `POST` / `PATCH` / `PUT` / `DELETE` each
181181
answering `405 {"error": "method_not_allowed"}` — 405 and not 404 because the same
182-
path answers GET. A KEYLESS projection (no `identity.primary`) mounts no `/{id}` route
183-
at all, so it refuses only the collection verb.
182+
path answers GET. A KEYLESS projection mounts no `/{id}` route at all, so it refuses only
183+
the collection verb. Keyless here means anything but a declared single-column
184+
`identity.primary`: no identity, or a composite one.
184185
The controller takes no constructor parameters — nothing binds a request body, so it
185186
injects neither an `ObjectMapper` nor a `Validator`. `KotlinFilterAllowlistGenerator`
186187
moves with it on one shared predicate: the emitted controller names the allowlist.

‎docs/CONFORMANCE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ regenerate with `ls -d fixtures/<corpus>/*/ | wc -l` for directory-shaped corpor
5151
| [`fixtures/fmt-conformance/`](../fixtures/fmt-conformance/) (#304 — `meta fmt`) | 12 | ✓ (reference) | ✓ | inherits via Java | ✓ | ✓ |
5252
| [`fixtures/field-lint-conformance/`](../fixtures/field-lint-conformance/) (the `verify` field authoring lint) | 15 | ✓ (reference) | ✓ | inherits via Java | ✓ | ✓ |
5353
| [`fixtures/naming-conformance/`](../fixtures/naming-conformance/) | 8 cases | ✓ | ✓ | inherits via Java (`RouteNaming.pluralize`) | ✓ | ✓ |
54-
| [`fixtures/codegen-noop/`](../fixtures/codegen-noop/) (FR-044 — reporting vocabulary is inert) | 1 model pair (`reporting/with` vs `reporting/without`) | ✓ (codegen + migrate) | ✓ | ✓ | ✓ | ✓ |
54+
| [`fixtures/codegen-noop/`](../fixtures/codegen-noop/) (FR-044 — reporting vocabulary: what is lowered, what stays inert) | 1 model pair (`reporting/with` vs `reporting/without`) | ✓ (codegen + migrate) | ✓ | ✓ | ✓ | ✓ |
5555

5656
A ✓ means the port runs the corpus green; an explicit `n / m` is used where a port
5757
carries a ledgered divergence. The two ledgered YAML fixtures are documented

‎docs/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ this tree is documentation, not the source of truth.
6666
| Build on a metadata model another repository publishes (`dependencies`, `meta deps sync`, overlay/extend across the boundary) | [`features/metadata-dependencies.md`](features/metadata-dependencies.md) |
6767
| Adopt a design MetaObjects already ships — users/groups/roles, an LLM trace envelope — instead of authoring it (`libraries`, `meta eject <library>`) | [`features/libraries.md`](features/libraries.md) |
6868
| Record what the system is supposed to do, and stop agents reviving retired features | [`features/requirements.md`](features/requirements.md) |
69-
| Declare what a dashboard groups by and counts (`dimension`, `measure`, `segment`, `object.report`; load-time checked; a view-backed report becomes a SQL view, no routes yet) | [`features/reporting.md`](features/reporting.md) |
69+
| Declare what a dashboard groups by and counts (`dimension`, `measure`, `segment`, `object.report`; load-time checked; a view-backed report becomes a SQL view served by a generated read-only list route; no client hook yet) | [`features/reporting.md`](features/reporting.md) |
7070
| Wire prompt construction (FR-004) | [`features/templates-and-payloads.md`](features/templates-and-payloads.md) |
7171
| Share a metadata shape across multiple instances (abstracts, `extends:`) | [`features/abstracts-and-inheritance.md`](features/abstracts-and-inheritance.md) |
7272
| Add a custom metamodel subtype or attribute to a downstream project | [`features/extending-with-providers.md`](features/extending-with-providers.md) + [`recipes/extending-metaobjects-with-providers.md`](recipes/extending-metaobjects-with-providers.md) |

‎docs/features/reporting.md‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -324,7 +324,7 @@ boolean), dimension and measure alike, with exactly the operators that type has
324324
object, and each such field sorts (default direction `asc`). A derived field typed `object`
325325
or `map` is neither filterable nor sortable. The allowlists are the report's **own** derived
326326
fields: a field of the `@from` entity that the report does not expose is refused with
327-
`400 invalid_filter_field` or `400 invalid_sort_field`. No vocabulary was added for this; the
327+
`400 invalid_filter_field` or `400 invalid_sort`. No vocabulary was added for this; the
328328
generators mark each derived field filterable on the detached read model, and nothing is
329329
written on a dimension, measure or report node.
330330

@@ -415,9 +415,14 @@ the bodies are valid under MySQL's default `ONLY_FULL_GROUP_BY`.
415415
- **A decimal's JSON spelling differs by port.** An `avg`, a ratio and a `sum` of a decimal
416416
are decimals. Each port sends its own form and the corpus asserts none of them, so a client
417417
that reads one from two backends must parse both a string and a number.
418-
- **An array-valued derived field is not gated.** A dimension over an `isArray` field takes
419-
its element subtype's filter operators; C# leaves an array out of its sort allowlist. The
420-
corpus has no such dimension, so do not rely on filtering or sorting one across ports.
418+
- **An array- or map-valued derived field is not gated, and the ports' sort allowlists differ
419+
for one.** A dimension over an `isArray` field takes its element subtype's filter operators
420+
in every port. For sorting, C# leaves an array out of its sort allowlist; TypeScript, Java,
421+
Kotlin and Python decide by subtype alone and so list it. A `map`-typed field has no filter
422+
operators and is left out of the sort allowlist by TypeScript, C#, Java and Kotlin; Python's
423+
router drops only `object` fields, so it would list a `map` one. The corpus has no array or
424+
map dimension, so none of this is asserted: do not rely on filtering or sorting one across
425+
ports.
421426
- **No generated client.** A served report has a route and a row type; a hook, grid or form
422427
for it is yours to write until the UI tier covers reports.
423428
- **With `@via`, `@of` must name an entity that has the field** (declared on it or inherited by

0 commit comments

Comments
 (0)