Skip to content

Commit 735ab76

Browse files
committed
docs(reporting): Python read-only API docs and the Kotlin coercer scope, as built (FR-044)
1 parent 1b7799c commit 735ab76

4 files changed

Lines changed: 29 additions & 15 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -132,7 +132,7 @@ it until 1.1 ships._
132132

133133
### Changed
134134

135-
Five corrections that shipped with report serving and reach models that declare no report.
135+
Six corrections that shipped with report serving and reach models that declare no report.
136136
Each one changes generated output on the next `gen`, so the drift gate reports it until you
137137
regenerate.
138138

@@ -159,19 +159,28 @@ regenerate.
159159
generated for it, and a keyless one (the shape above) no longer lists `/:id` or the by-id
160160
function. Write-through projections and entities are unchanged. `meta verify --docs` reports
161161
the affected pages as stale until regenerated.
162+
- **Python API docs: a read-only projection's page gains the read surface it was missing.**
163+
The api-docs builder documented a view-backed projection by its model alone. Its page now
164+
also lists what the read-only router emits: the repository Protocol, `GET <path>`,
165+
`GET <path>/{id}` only when the projection has an item route (the rule above), and the
166+
filter allowlist. No write verb is listed, since the router answers those with `405`.
167+
Entities and write-through objects are unchanged. Regenerate the docs to pick the pages up.
162168
- **Java: a filter allowlist with more than ten filterable fields now compiles.**
163169
`SpringFilterAllowlistGenerator` spelled `OPS_BY_FIELD` with `Map.of`, which has no overload
164170
past ten pairs, so an entity or projection with eleven or more `@filterable` fields generated
165171
a class `javac` refused. It now uses `Map.ofEntries` above ten. Ten or fewer are
166172
byte-identical.
167173
- **Kotlin: the generated Spring controller of any entity or projection with a `field.decimal`
168-
or `field.float` scalar field regenerates with different bytes.** Its filter coercion now
174+
or `field.float` scalar field regenerates with different bytes, whether or not the field is
175+
`@filterable`.** That covers writable, write-through and read-only controllers. Its filter
176+
coercion now
169177
calls a new `coerce<Entity>Decimal` / `coerce<Entity>Float` function where it called
170178
`coerce<Entity>Double`. Before, a list filter on such a column threw `ClassCastException`,
171179
a `500` on a request the allowlist had admitted, because the handler cast the coerced
172180
`Double` to the column's `BigDecimal` or `Float`. A single-table-inheritance (TPH) controller
173-
changes for a float field only; its filter pipeline already left decimals out. A model with
174-
only string, int, long, double and the other non-decimal, non-float subtypes keeps its bytes.
181+
changes for a float field only (on the base or a subtype); its filter pipeline already left
182+
decimals out. `field.double` is unchanged, so a model with no decimal and no float field
183+
keeps its bytes.
175184
Separately, a read-only controller or row mapper over a field named after a member of
176185
Exposed's `Table` (such as `source`) now reads the suffixed column property
177186
(`sourceColumn`) and compiles; every other field name keeps its bytes.

‎docs/features/reporting.md‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ no query-time choice of dimensions or measures (a report is a fixed combination,
2222
once), and no time-zone vocabulary: time grains and relative dates are UTC.
2323

2424
**Entirely opt-in.** Nothing here applies to a model that declares none of it. The change
25-
that served reports also corrected three things about read-only projections and one filter
25+
that served reports also corrected four things about read-only projections and one filter
2626
defect per JVM port; [Compatibility](#compatibility) lists them.
2727

2828
## The problem it solves
@@ -567,12 +567,16 @@ generated output for models that declare no report. Each is in the
567567
read-only projection's page no longer lists create, update or delete
568568
functions, write verbs or Insert/Update schemas, and a keyless one no longer lists `/:id` or
569569
the by-id function. `meta verify --docs` reports the page as stale until you regenerate.
570+
- **Python API docs: a read-only projection's page gains its read surface.** It listed the
571+
model alone; it now also lists the repository Protocol, `GET <path>`, `GET <path>/{id}` when
572+
the projection has an item route, and the filter allowlist, and never a write verb.
570573
- **Java: a filter allowlist with more than ten filterable fields** now compiles (it is
571574
spelled with `Map.ofEntries`). Ten or fewer are byte-identical.
572575
- **Kotlin: a list filter on a `field.decimal` or `field.float` column** no longer throws.
573-
The generated controller of any entity or projection with a decimal or float scalar field
574-
regenerates with different bytes (a `coerce<Entity>Decimal` / `coerce<Entity>Float` function
575-
where it used `coerce<Entity>Double`). A controller that reads a field named after a member
576+
The generated controller of any entity or projection with a decimal or float scalar field,
577+
filterable or not, regenerates with different bytes (a `coerce<Entity>Decimal` /
578+
`coerce<Entity>Float` function where it used `coerce<Entity>Double`); a single-table
579+
inheritance controller changes for a float field only, and `field.double` is unchanged. A controller that reads a field named after a member
576580
of Exposed's `Table` (such as `source`) now compiles; every other name keeps its bytes.
577581

578582
The design and its decisions are in

‎docs/ports/csharp.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -463,8 +463,9 @@ always sends. Filter operators (`eq` / `ne` / `gt` / `gte` / `lt` / `lte`
463463
/ `in` / `like` / `isNull`) per [`api-contract.md`](../features/api-contract.md)
464464
ship too — the generated `<Entity>FilterAllowlist` (`FilterAllowlistGenerator`)
465465
feeds `FilterParser.Parse` + `EfCoreFilterDispatch.ApplyFilter`, both wired
466-
directly into the generated list handler. The one real gap: read-only
467-
projections (`source.rdb @kind: view/...`) don't get filter routes today — see
466+
directly into the generated list handler. A read-only projection
467+
(`source.rdb @kind: view`) and a view-backed report get the same filter and sort
468+
on their list route, against an allowlist of their own fields. Remaining gaps are in
468469
[`server/csharp/MetaObjects.Codegen/Generators/KNOWN_GAPS.md`](../../server/csharp/MetaObjects.Codegen/Generators/KNOWN_GAPS.md).
469470

470471
## Capability snapshot

‎docs/superpowers/plans/2026-10-04-fr-044-plan-3-report-read-routes.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ What the code does that the documents do not say, found while verifying. Each on
4949
- **The route segment rule is unchanged:** the object name, `snake_case`d, then pluralized (`docs/features/api-contract.md`). No report-specific spelling.
5050
- **Default physical table-name pluralization is frozen** (1.0.13). This plan derives no physical name.
5151
- **Routes, DTOs, allowlists, hooks and controllers are reference helpers** (ADR-0034 Amendment 3). TypeScript's ejectable copies under `codegen-ts/src/reference/` change in the same commit as the package generators; `reference-byte-identical.test.ts` holds them together.
52-
- **No-churn:** a model with no `object.report` produces byte-identical output in every generator and every docs surface, with five exceptions, each a named behaviour change in the [proof table](#no-churn-and-back-compat-proof): the two that open questions 4 and 5 name (a read-only projection with no declared identity and no `id` field, in TypeScript and Python; a decimal in a TypeScript view read schema), and three found during execution (the API docs of a read-only object document only what is generated, in TypeScript, with the matching Python fix ruled and in progress when this was written; a Java filter allowlist of more than ten fields; a Kotlin controller over a decimal or float field).
52+
- **No-churn:** a model with no `object.report` produces byte-identical output in every generator and every docs surface, with five exceptions, each a named behaviour change in the [proof table](#no-churn-and-back-compat-proof): the two that open questions 4 and 5 name (a read-only projection with no declared identity and no `id` field, in TypeScript and Python; a decimal in a TypeScript view read schema), and three found during execution (the API docs of a read-only object document exactly what is generated: TypeScript pages lose never-generated symbols, Python pages gain the read symbols they lacked; a Java filter allowlist of more than ten fields; a Kotlin controller over a decimal or float field).
5353
- ADR-0039: read effective properties with resolving accessors. Any `own*()` call carries a comment naming its sanctioned case. Python `attr()` is OWN.
5454
- TS: named constants for metamodel strings, no `any`, never `instanceof` a node from another package.
5555
- Public repo: no private project names, no absolute home paths, in code, fixtures, docs or commit messages.
@@ -1148,8 +1148,8 @@ Expected: PASS.
11481148
| **Behaviour change 1** (unreleased vocabulary) | A view-backed report now generates code and mounts a route. Nothing released carries `object.report` |
11491149
| **Behaviour change 2** (released behaviour, open question 4) | In TypeScript and Python, a read-only projection with **no declared identity and no field named `id`** loses its `/{id}` routes, its by-id query (`find…ById` / `find_by_id`) and, in TypeScript, its detail hook. That shape could not serve a row by key. A projection with a declared identity, or with an `id` field and no declared identity, served rows by key before and is unchanged (ruled during Task 3: `hasItemRoute` / `has_item_route`). C#, Java and Kotlin keep requiring a declared single-column identity. The CHANGELOG names it |
11501150
| **Behaviour change 3** (released output, open question 5) | In TypeScript, a decimal field of a view read schema is `z.string()`, not `z.number()`. The runtime value was always a string. The CHANGELOG names it |
1151-
| **Behaviour change 4** (released docs output, found in Task 5) | In TypeScript (`meta docs` API pages), a read-only object's API unit documents only what is generated (the same fix is ruled for Python's api-docs builder and was in progress when this row was written; the CHANGELOG names Python only once it lands): a read-only projection's page no longer lists create/update/delete functions, write verbs or Insert/Update schemas, and a keyless one no longer lists `/:id` or the by-id function. Write-through projections and entities are unchanged. The CHANGELOG names it |
1152-
| **Behaviour change 5** (released output, found in Tasks 7 and 8) | Kotlin: the generated Spring controller of any entity or projection with a `field.decimal` or `field.float` scalar field regenerates with different bytes (`coerce<E>Decimal` / `coerce<E>Float` in place of `coerce<E>Double`), because a filter on such a column threw `ClassCastException` (a 500). A TPH controller changes for a float field only. Models with only double, int, long or string fields keep their bytes. Java: a filter allowlist of more than ten fields is spelled with `Map.ofEntries` (it did not compile before); ten or fewer keep their bytes. The CHANGELOG names both |
1151+
| **Behaviour change 4** (released docs output, found in Task 5) | A read-only object's API unit documents exactly what is generated, and the two ports move in opposite directions. **TypeScript** (`meta docs` API pages): a read-only projection's page LOSES create/update/delete functions, write verbs and Insert/Update schemas that were never generated, and a keyless one loses `/:id` and the by-id function. **Python** (the api-docs builder): a read-only projection's unit had only its model symbol and GAINS the repository seam, `GET <path>`, `GET <path>/{id}` only when it has an item route, and the filter allowlist; never a write verb. A served report's unit uses the same helper. Entities and write-through objects are unchanged in both. The CHANGELOG names each |
1152+
| **Behaviour change 5** (released output, found in Tasks 7 and 8) | Kotlin: the generated Spring controller (writable, write-through and read-only: projection or report) of any object with a `field.decimal` or `field.float` scalar field, filterable or not, regenerates with different bytes (`coerce<E>Decimal` / `coerce<E>Float` in place of `coerce<E>Double`), because a filter on such a column threw `ClassCastException` (a 500). A TPH controller changes for a `field.float` only, on the base or a subtype (decimals are excluded from the TPH filter list). `field.double` is unchanged. Java: a filter allowlist of more than ten fields is spelled with `Map.ofEntries` (it did not compile before); ten or fewer keep their bytes. The CHANGELOG names both |
11531153

11541154
## Unverified items
11551155

@@ -1189,8 +1189,8 @@ What execution changed or added, beyond the answers above. The tables and tasks
11891189
- **A. No UI tier for a report (answer 6).** TypeScript gates the UI tier (the TanStack generators and the source-only Angular generators) on a new `servesClientTier` predicate, while `servesReadApi` is true for a served report. `agent/ui.md` lists no report. An adopter-owned (ejected) hook generator that still gates on `servesReadApi` would emit for a report; the CHANGELOG tells owners to switch to `servesClientTier`.
11901190
- **B. The item-route rule (answer 4).** TypeScript `hasItemRoute` and Python `has_item_route`: false for every report; otherwise true when the by-id column exists on the object (a declared primary identity, or no identity and a field named `id`); false otherwise. Only a read-only projection with no identity and no `id` field loses its `/{id}` routes, by-id query and, in TypeScript, its detail hook. This differs from C#, Java and Kotlin, which require a declared single-column identity and are unchanged.
11911191
- **C. Decimal (answer 5).** A `field.decimal` in a TypeScript view read schema is `z.string()`, for reports and projections.
1192-
- **D. API docs accuracy (new, behaviour change 4).** In TypeScript a read-only object's API unit documents only what is generated. The same fix is ruled for Python and was in progress when this note was written.
1193-
- **E. Per-port fixes found on the way.** C#: a report's enum dimension is sortable (report-only; an entity's enum field is still not sortable in C#). Java: the filter-allowlist generator handles more than ten filterable fields (`Map.ofEntries`). Kotlin: a filter on a decimal or float column no longer throws, which changes the generated controller of any entity or projection with such a field (behaviour change 5); reads of a field whose name needs `safeColumnProperty` compile, byte-neutral for every other name.
1192+
- **D. API docs accuracy (new, behaviour change 4).** A read-only object's API unit documents exactly what is generated. In TypeScript a read-only projection's page loses the write and (when keyless) by-id symbols that were never generated. In Python a read-only projection's unit, which had only its model symbol, gains the repository seam, `GET <path>`, `GET <path>/{id}` when it has an item route, and the filter allowlist.
1193+
- **E. Per-port fixes found on the way.** C#: a report's enum dimension is sortable (report-only; an entity's enum field is still not sortable in C#). Java: the filter-allowlist generator handles more than ten filterable fields (`Map.ofEntries`). Kotlin: a filter on a decimal or float column no longer throws, which changes the generated controller of any object with such a field, filterable or not, and of a TPH base for a float only (behaviour change 5); reads of a field whose name needs `safeColumnProperty` compile, byte-neutral for every other name.
11941194
- **Requirements ledger (Task 10 Step 5).** Nothing moved. No entry of `metaobjects/meta.requirements.yaml` is about serving a report: `objectReport` and the `reporting` branch describe declaring the vocabulary, and the ledger carries no `@implementedBy` on any node by design.
11951195

11961196
## Open questions for the captain

0 commit comments

Comments
 (0)