Skip to content

Commit ffa0806

Browse files
dmealingclaude
andcommitted
docs: ADR-0056 across the ports' docs, the skills, the ADRs and the changelog
- CHANGELOG [Unreleased]: the breaking generated-output change, plus Fixed entries for #388, the Python render engine reading model payloads, Python value-object module collisions, and the Python api-docs import paths. - New migration guide: docs/features/migrations/value-object-types-are-generated-once.md. - ADR-0056 gains Amendment 1, which corrects three statements the implementation proved wrong: - C# needs collision naming, because its default binding flattens every namespace. Python had none before this branch. - Rule 3's mirror placement differs by port. TypeScript and Python keep the mirror module-local; Java has no mirror type. - Rule 6 is enforced, advisorily, in TypeScript, Python and C#. The amendment also retracts rule 6's claim that the codegen-compile gates prove the pair: their corpus declares no templates. - ADR-0044 is marked as having its payload-tier half superseded. The decisions index gains an ADR-0056 row. - Port docs (Java, Kotlin, C#, Python), templates-and-payloads.md, the codegen-kotlin README, the root README's capability row, the render corpus's naming contract (per-port expected names), and the prompts, codegen and audit skill references: all of them now describe the value object's own type in place of SpringPayloadGenerator, KotlinPayloadGenerator, the C# `.payload.cs` record and payload_vo_generator. The Kotlin docs now describe the Jackson parser in place of kotlinx.serialization. The C# prompts reference's `dotnet meta gen` examples now pass `--generators`, which codegen has required since opt-in. - agent-context conformance corpus regenerated. Part of #387. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018ghY6h6CaGzZcmpHJ7msWQ
1 parent 9db8cfb commit ffa0806

33 files changed

Lines changed: 612 additions & 358 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,36 @@ edit (two registered `description` strings) and was ruled a hold, as 1.0.4's was
1515

1616
### Changed
1717

18+
- **A template's payload and response types are now its value objects' own types, in every
19+
port — the `payload` generator is removed ([ADR-0056](spec/decisions/ADR-0056-value-object-types-are-generated-once.md),
20+
#387). This changes generated output for every adopter who uses templates.** Each port used
21+
to generate a value object twice: its own type, and a template-named copy
22+
(`<Template>Payload`, `<Template>Response`, `<Short>Payload`, the `prompts.ts` interfaces)
23+
written into the template's package. In Java and Kotlin, a nested value object shared by
24+
templates in two packages landed in whichever package sorted first, and the other package
25+
did not compile. Now the value-object generator — TS `entity`, C# `entity`, Java
26+
`value-object`, Kotlin `entity`, Python `entity` — emits one type per concrete
27+
`object.value` and sourceless `object.projection`, at the value object's own location,
28+
and render helpers, parsers, extractors and output-format fragments reference it.
29+
30+
**Adopters must regenerate, update their imports, and wire the value-object generator**
31+
in any run that wires a template-tier generator. Remove `payload` from C#/Python
32+
`--generators` and `SpringPayloadGenerator` / `KotlinPayloadGenerator` from Maven
33+
`<generators>`. Delete generated files that are no longer emitted (`meta gen` never deletes
34+
one; `meta verify --codegen` names them) — including a TS `prompts.ts` that held only
35+
interfaces. Types are named after the value object; where a port emits every value object
36+
into one flat namespace (TS, C#, Python), a colliding short name is package-qualified
37+
(`AcmeAlphaNote`). The lenient mirror is `<Vo>Extracted`. Other visible changes: TS
38+
optional fields are `name?: T` (not `T | null`) and the removed exports are
39+
`generatePayloadInterfaces`, `generatePayloadInterfacesBatch` and `generateRenderHandle`;
40+
C# payloads are the `<Vo>.g.cs` POCOs with PascalCase members, and the extractor is
41+
`<Prompt>Extractor`; Java drops the generated `hasFoo()` methods (the render engine derives
42+
them) and now collides `entity` with `value-object` on every value object; Kotlin's strict
43+
parser decodes with Jackson; the Java, Kotlin, C# and Python output-format root name is the
44+
value object's short name, so rendered prompt text changes; Python's request model no
45+
longer rejects unknown keywords. Full list:
46+
[migration guide](docs/features/migrations/value-object-types-are-generated-once.md).
47+
1848
- **The filter/sort 400 envelope now NAMES the rejected field, in every port — `field` is
1949
REQUIRED, not optional.** `invalid_filter_field`, `invalid_filter_op`,
2050
`invalid_filter_value` and `invalid_sort` each carry
@@ -284,6 +314,26 @@ edit (two registered `description` strings) and was ruled a hold, as 1.0.4's was
284314
work, and Hono now does the same. The generated api-contract lane runs on Fastify, so the
285315
corpus's `patch-empty-noop` scenario never reached Hono.
286316

317+
- **Kotlin: a generated builder could emit Kotlin that does not parse (#388).** The
318+
`build()` function's `requireNotNull(x) { "x is required" }` could be wrapped by KotlinPoet
319+
at a space INSIDE the string literal, and a Kotlin string has no line continuation. The
320+
assignment is now joined with KotlinPoet's non-breaking space, so it never splits.
321+
322+
- **Python: the render engine rendered a Pydantic model payload as an empty body.** It
323+
looked names up in mappings only, so every slot of a model payload resolved to nothing and
324+
no error was raised. It now reads a model through its JSON-mode dump (enums render as
325+
their values; `{{#hasField}}` applies), which matters because generated render helpers are
326+
now typed with the value object's model.
327+
328+
- **Python: two value objects with one short name wrote one module.** The entity generator
329+
named every model `<name>.py`, so `acme::alpha::Note` and `acme::beta::Note` — or a value
330+
object and an entity sharing a name — collided. A colliding value object is now
331+
package-qualified (`AcmeAlphaNote.py`), and `field.object` / `field.map` references resolve
332+
package-local instead of by the ref's bare tail.
333+
334+
- **Python api-docs documented every model's import wrong.** They said
335+
`from .<snake_name> import <Name>`; the module is `<Name>.py`.
336+
287337
- **Web client: every filtered request 400'd against a Spring Boot backend.**
288338
`@metaobjectsdev/runtime-web`'s `buildFilterQs` — which every generated TanStack hook
289339
calls — sent the filter grammar with raw brackets (`filter[email][like]=…`). RFC 3986

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -135,7 +135,7 @@ first-week wedge plan — and `meta init` picks up from there.
135135
| `field.currency` / `field.enum` | Yes | Yes | Yes | Yes | Yes |
136136
| `field.object` + `@storage=flattened` | Yes | Yes | Yes (per-sub-field columns) | Yes (EF Core `OwnsOne`) | Loader yes; codegen partial |
137137
| Templates + render (FR-004) | Yes | Yes | Yes (wraps Java) | Yes | Yes |
138-
| Payload-VO codegen | Yes (via projection) | Yes (`SpringPayloadGenerator`) | Yes (`@Serializable`) | Yes | Yes (`payload_vo_generator`) |
138+
| Payload-VO codegen (the value object's own type, ADR-0056) | Yes (`entityFile()`) | Yes (`SpringValueObjectGenerator`) | Yes (`KotlinEntityGenerator`) | Yes (`EntityGenerator`) | Yes (`entity`) |
139139
| Migration emission | `meta migrate` (Postgres / SQLite / D1) | Via TS toolchain (`@metaobjectsdev/cli migrate`) | Via TS toolchain (`@metaobjectsdev/cli migrate`) | Via TS toolchain (ADR-0015) | Via TS toolchain (ADR-0015) |
140140
| DB-drift verify | `meta verify --db <url>` | Template-drift: `Verify.check`; schema-drift is TS-owned (ADR-0015) | Template-drift: `Verify.check`; startup: `MetadataStartupValidator` | `dotnet meta verify` (codegen-drift) | Schema-drift is TS-owned (ADR-0015) |
141141
| Template-drift verify | Yes | Yes (`Verify.check`) | Yes (via Java) | Yes (`dotnet meta verify`) | Yes (`metaobjects.render.verify`) |

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ The active generator list is declared in `pom.xml` under the plugin `<configurat
5353
| Hand-written `data class` with same fields as a modeled entity | `KotlinEntityGenerator` should own this (`<Entity>.kt`) |
5454
| Hand-written `object ... : Table(` | `KotlinExposedTableGenerator` should own this (`<Entity>Table.kt`) |
5555
| Hand-written `@RestController` on a CRUD entity | `KotlinSpringControllerGenerator` should own this |
56-
| `@Serializable` on a payload class not in generated sources | `KotlinPayloadGenerator` should own this; check `pom.xml` generator list |
56+
| A hand-written data class mirroring a template's `@payloadRef` / `@responseRef` value object | `KotlinEntityGenerator` emits that value object's data class, and it IS the payload type (ADR-0056); check `pom.xml` wires it |
5757
| `// keep in sync with` / `// mirrors the` | second-source-of-truth comment — always a finding |
5858
| `transaction(db) {` bodies that duplicate every CRUD operation | hand-written Exposed transactions are expected (see Calibration), but if they duplicate generated-CRUD logic exactly, audit further |
5959
| a table/column string in `exec("…")` raw SQL or a Flyway script | reference `<Entity>Names` (`KotlinNamesGenerator`, opt-in); `AuthorTable.name` inside the Exposed DSL is the typed handle — correct, not a finding |

‎agent-context/skills/metaobjects-audit/references/python.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,9 @@ metaobjects verify --templates # {{field}} refs vs payload VO
3535
```
3636

3737
`--generators` accepts stable generator names: `entity`, `routes`, `filter-allowlist`,
38-
`payload`, `output-parser`, `extractor`, `output-prompt`, `render-helper`, `trace-helper`,
39-
`template`. Schema migration + live-DB drift run through the **Node `meta` CLI**
38+
`names`, `output-parser`, `extractor`, `output-prompt`, `render-helper`, `trace-helper`,
39+
`template`. (There is no `payload` generator since ADR-0056: a template's payload and
40+
response types are the value objects' own `entity` models.) Schema migration + live-DB drift run through the **Node `meta` CLI**
4041
regardless of server language — see the migration reference.
4142

4243
---

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

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -46,13 +46,12 @@ in `--output-dir`.
4646

4747
| Stable name | Output |
4848
|---|---|
49-
| `entity` | `<Entity>.g.cs` — an EF Core entity class per `object.entity` / projection: PascalCase props mapped via `[Column]`, `[Table]`, `[Key]` (or class-level `[PrimaryKey]` for composites), `[MaxLength]`/validators, nullability from `@required`. Enum fields → a nested (or shared) C# `enum`; object fields → owned-type navigations; value objects → POCOs. A TPH `@discriminator` base is emitted `abstract` with `: Base` subtypes (single-table). |
49+
| `entity` | `<Entity>.g.cs` — an EF Core entity class per `object.entity` / projection: PascalCase props mapped via `[Column]`, `[Table]`, `[Key]` (or class-level `[PrimaryKey]` for composites), `[MaxLength]`/validators, nullability from `@required`. Enum fields → a nested (or shared) C# `enum`; object fields → owned-type navigations; every concrete value object and sourceless projection → a POCO, which is also the template tier's payload/response type (ADR-0056; package-qualified, e.g. `AcmeAlphaNote`, when another object shares its short name). A TPH `@discriminator` base is emitted `abstract` with `: Base` subtypes (single-table). |
5050
| `db-context` | one `AppDbContext` — a `DbSet<T>` per entity + `OnModelCreating`: `.HasConversion<string>()` (enums), `.OwnsOne(...)`/`.ToJson(...)` (owned/jsonb object fields), `.HasPrecision(p,s)` (decimals), `.UsingEntity<>(...)` (M:N), `.HasDiscriminator(e => e.Type).HasValue<Sub>(...)` (TPH). |
5151
| `routes` | `<Entity>Routes.cs` — ASP.NET **Minimal API** CRUD per writable entity (`source.rdb @kind="table"`) on the cross-port REST contract (`?filter[field][op]=`, `?sort=field:asc`, `?limit`/`?offset`, `?withCount=1` envelope, 400/404 envelopes). A TPH base emits polymorphic `GET /<base>(+/{id})` + a per-subtype CRUD set at `/<base>/<discriminatorValue lowercased>` (create injects the discriminator, cross-subtype get/update/delete → 404). |
5252
| `filter-allowlist` | per-entity `<Entity>FilterAllowlist` (FR-009 — the server-side field+operator allowlist the routes validate against). |
5353
| `callable` | `<Entity>.callable.g.cs` — an FR-015 calling method for a `source.rdb @kind="storedProc"|"tableFunction"`, via EF `FromSqlInterpolated` (args from the `@parameterRef` value object in declaration order). |
54-
| `payload` | `<Payload>.payload.cs` — the strict typed payload `record` (+ any nested element records) per `template.prompt` `@payloadRef` / `@responseRef` (each an `object.value`): `@payloadRef` types the REQUEST, `@responseRef` the REPLY the parser/extractor bind to. |
55-
| `output-parser` / `extractor` / `output-prompt` / `render-helper` | the prompt-pillar artifacts for a **responding `template.prompt`** — one carrying `@responseRef` (ADR-0052: these tiers are INBOUND; `template.output` is outbound only and emits no parser). The strict parser, the tolerant `extract`, the **output-format prompt fragment** (`output-prompt`; presentation via `@promptStyle: guide`/`inline`/`exampleOnly`), and the typed render helper. See the **prompts** reference. |
54+
| `output-parser` / `extractor` / `output-prompt` / `render-helper` | the prompt-pillar artifacts for a **responding `template.prompt`** — one carrying `@responseRef` (ADR-0052: these tiers are INBOUND; `template.output` is outbound only and emits no parser). The strict parser, the tolerant `extract`, the **output-format prompt fragment** (`output-prompt`; presentation via `@promptStyle: guide`/`inline`/`exampleOnly`), and the typed render helper. They reference the value objects' POCOs from `entity` and declare no payload type — wire `entity` too (`--list` says so). See the **prompts** reference. |
5655
| `names` | `<Entity>Names.g.cs` — `public abstract class <Entity>Names` of `const` physical database names, MIRRORING THE METADATA TREE: the object's own `Type`/`SubType`/`Name` (`Name` is the OBJECT's name, never a physical one), then per `source.rdb` keyed by `@role` — `SourcePrimaryType`/`SubType`/`Kind`, `SourcePrimarySchema` when declared, and the physical name under the alias for its `@kind` (`SourcePrimaryTable` / `SourceReplicaView` / `SourcePrimaryProc` / `…Function` / `…MaterializedView`) — then a `<Field>Field`/`<Field>Column` pair per field, then each identity and index (`IdentityPkName`, and `IdentityUqCustEmailIndex` / `IndexIxCustStatusIndex` — the DATABASE name, carried for `identity.secondary` and `index.lookup` only), then a complete `ColumnsByField`. There is no `ReadOnly`: it is a derivation over `@kind`, so ask `SourcePrimaryKind`. Emitted for every object with a declared or inherited primary source, PLUS a fragment for any abstract base such an object extends (its own identity + columns, and NO source members — it has no table). A class whose object extends another one **inherits** it (`class CopayAuthNames : AuthNames`) rather than restating its constants — a C# `const` is inherited, so `CopayAuthNames.IdColumn` and `CopayAuthNames.SourcePrimaryTable` resolve through the base (`Type`/`SubType`/`Name` are redeclared with `new`, since every artifact carries its own). `abstract`, not `static`, precisely so it can be inherited; it still cannot be instantiated. In the run, `entity` and `db-context` reference the constants (`[Table(OrderNames.SourcePrimaryTable)]`, `[Column(OrderNames.StatusColumn)]`, `.ToView(OrderNames.SourceReplicaView)`); a `--generators` selection omitting `names` falls back to literals. |
5756
| `template` | the generic Mustache `templateGenerator()` primitive. |
5857

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

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -121,8 +121,7 @@ separate `metaobjects-codegen-base` module instead.)
121121
| `SpringControllerGenerator` | `<Entity>Controller.java` per writable entity (`source.rdb` `@kind="table"`) — Spring Web MVC, five CRUD endpoints on the cross-port REST contract (`?filter[field][op]=`, `?sort`, `?limit`/`?offset`, `?withCount=1` envelope, 404/400 envelopes). A TPH `@discriminator` base emits ONE controller: polymorphic `GET /<base>(+/{id})` plus a per-subtype CRUD set at `/<base>/<discriminatorValue lowercased>` — create injects the discriminator from the URL (never the body); get/update/delete scoped to the subtype (cross-subtype → 404); discriminator immutable. |
122122
| `SpringDtoGenerator` | `<Entity>Dto.java` as a Java 21 `record`; wrapped primitives (`Long`/`Integer`/`Boolean`) so missing JSON props deserialise to `null`; currency = `Long` (integer minor units). A TPH `@discriminator` base's DTO is the **union** of every subtype's columns (subtype-only fields folded nullable, validation dropped), so one wire shape backs the polymorphic + per-subtype endpoints. |
123123
| `SpringRepositoryGenerator` | `<Entity>Repository.java` — a hand-stubbed `interface` the consumer implements with their persistence layer (Spring Data JPA / jOOQ / JDBC). For a TPH base the interface is polymorphic + per-subtype-scoped (`listByType`/`findByIdAndType`/`createWithType`/`updateByIdAndType`/`deleteByIdAndType`) over the single table; subtype entities emit no own controller/DTO/repository — they fold into the base. |
124-
| `SpringValueObjectGenerator` | a Java 21 `record` per `object.value` reached through a `field.object @storage: jsonb` column (single or `@isArray`, transitively through nested VOs) — the typed component the Jackson jsonb codec serializes to/from (carries jakarta validation, unlike a plain payload record). Program D typed-jsonb VOs. |
125-
| `SpringPayloadGenerator` | a Java 21 `record` per `template` payload VO |
124+
| `SpringValueObjectGenerator` | a Java 21 `record` per concrete `object.value` and sourceless `object.projection`, in the value object's own package — THE Java type for it (ADR-0056): the typed component the Jackson jsonb codec serializes to/from (with jakarta validation), the render helper's payload and the parser's return type. Wire it with any template-tier generator. |
126125
| `SpringOutputParserGenerator` | the strict parser-on-receipt for a **responding `template.prompt`** — one carrying `@responseRef` (ADR-0052: INBOUND; a `template.output` emits no parser). See the prompts reference. |
127126
| `SpringOutputPromptGenerator` | the FR-010 output-format prompt fragment for a responding `template.prompt` (presentation via `@promptStyle: guide`/`inline`/`exampleOnly`) |
128127
| `SpringRenderHelperGenerator` | the typed render helper for a `template.prompt` payload |
@@ -201,8 +200,8 @@ fails on the `MetaObject` back-reference** — the inherited `getMetaData()` get
201200
leads a bean-style mapper into the metadata graph, and on a modular JVM into
202201
`InaccessibleObjectException`. This is expected, not a bug to work around. If you
203202
want a type that serializes cleanly with a bare default mapper, use the
204-
`codegen-spring` record surface (`SpringDtoGenerator` / `SpringPayloadGenerator` /
205-
`SpringValueObjectGenerator`) instead — never `pojoAware`.
203+
`codegen-spring` record surface (`SpringDtoGenerator` / `SpringValueObjectGenerator`)
204+
instead — never `pojoAware`.
206205

207206
Serialize any `MetaObjectAware` instance through the MetaObjects JSON layer's
208207
`JsonObjectWriter`/`JsonObjectReader`, not a bare mapper — it applies the temporal

0 commit comments

Comments
 (0)