@metaobjectsdev/sdk 0.16.0 → 0.17.0

package/agent-context/skills/metaobjects-codegen/SKILL.md

@@ -46,11 +46,13 @@ Every emitted file carries a `@generated` header. This is load-bearing:
 Practical rule: **pattern-derivable-from-metadata = regenerate; business logic =
 hand-write in a non-generated file.** FK columns, CRUD, validator chains,
 type-safe finders, `relations()` blocks — all derived, never hand-coded. What you
-hand-write is what metadata genuinely can't express: regex from outside metadata,
-domain logic, and *irreducible* SQL views (recursive CTEs, window functions, set
-ops). Most views are NOT irreducible — model them as an `object.projection` and the
-view DDL is generated (see the projection bullet below); a hand-written view for a
-shape origins can express is drift the drift gate can't even see.
+hand-write is what metadata genuinely can't express: regex from outside metadata and
+domain logic. Most views are NOT irreducible — model them as an `object.projection`
+and the view DDL is generated (see the projection bullet below); a hand-written view
+for a shape origins can express is drift the drift gate can't even see. A genuinely
+*irreducible* view body (recursive CTE, window function, set op) isn't hand-written
+loose either — it goes in the `source.rdb` **`@sql`** escape (#208, ADR-0043) so the
+tool still registers, fingerprints, and drift-checks it (see the projection bullet).
 
 ## Selecting generators by stable name
 
@@ -81,23 +83,50 @@ the data access too.
   standard verbs with the runtime helpers and hand-write only the custom ones (see
   the runtime skill's `mountCrudRoutes` / `mount<Verb>Route` / `expose`). You are
   never forced into all-generated or all-hand-written.
+- **Entity's OWN columns + a joined extra → an entity read-view, NOT a projection.**
+  The most common legacy view is `SELECT o.*, c.name AS customer_name FROM orders o
+  JOIN customers c …` — the entity *with a read route*, not an independent exposure.
+  Reach for an **entity read-view** first: keep the entity's writable `table` source
+  and add a **non-primary** read-only source (`source.rdb` `@role: replica`
+  `@kind: view`), declaring only the *extra* as a derived (`origin.*`) field — the
+  entity's own field set already covers `o.*`, so you re-state nothing but the extra.
+  Codegen then routes **reads** to the view and **writes** to the table (derived
+  fields don't exist there and are excluded from the write codecs); a create/update
+  re-reads the row through the view by primary key, so the returned value carries the
+  derived columns (read-your-writes). Shipped all five ports (#213 write half + #214
+  read half). Reach for a **projection** (below) instead only when it is an
+  independent exposure contract — a subset, renamed base columns, a versioned/external
+  shape, or a row-filtered view. See `docs/features/source-kinds.md`.
 - **Derived/aggregate data → declare a projection, then USE its generated query.**
   Don't hand-write a join or an `AVG()`/`COUNT()`. Declare an `object.projection`
-  with `origin.aggregate` / `origin.passthrough` / `origin.collection` children
-  **and a read-only `source.rdb` `@kind: view` child** (codegen detects a
-  projection by that read-only source, not by the subtype alone — omit it and
-  nothing is generated). `meta gen` emits a read-only query for it (and
-  `meta migrate` its DB view), and you **call that generated query from your
-  route**. Declaring the projection is only half the win — *consuming* its
-  generated query is the other half.
+  with `origin.*` children — `origin.passthrough` (a forwarded column),
+  `origin.aggregate` (`@agg` `count`/`sum`/`avg`/`min`/`max`, plus the #195
+  `any`/`all` predicate quantifiers over a `@filter` and `collect` array-rollup with
+  optional `@distinct`/`@orderBy`; any aggregate may be row-scoped with `@filter`),
+  `origin.collection` (a nested array), `origin.computed` (a row-level `@expr`), and
+  `origin.first` (one related row's column along `@via`/`@of`/`@orderBy`) — **and a
+  read-only `source.rdb` `@kind: view` child** (codegen detects a projection by that
+  read-only source, not by the subtype alone — omit it and nothing is generated).
+  `meta gen` emits a read-only query for it (and `meta migrate` its DB view), and you
+  **call that generated query from your route**. Declaring the projection is only half
+  the win — *consuming* its generated query is the other half.
+  - **Row-filtered views are a projection `@filter`, not hand-written SQL.** An
+    object-level `@filter` on `object.projection` (the same `attr.filter` shape as a
+    preset filter) scopes the whole view's rows — it lowers to the view's outer
+    `WHERE` (#207). This is the metadata-managed way to author a soft-delete / status
+    / type view without hand-writing SQL.
   - **Never hand-author the view SQL for a shape origins can express.** The
     `CREATE VIEW` body is emitted by the Node `meta migrate` from the projection's
     `origin.*` children — hand-writing it is a second source of truth that drifts
     silently, because an unmodeled DB view is *unmanaged*: `meta verify --db` never
-    flags it. Hand-written view SQL is legitimate only when a named construct
-    origins can't express (recursive CTE, window function, set op) blocks
-    projection authoring — then keep that DDL in a hand-edited migration file and
-    justify it in review.
+    flags it. For a genuinely irreducible body (recursive CTE, window function, set
+    op) that origins can't express, carry it in the `source.rdb` **`@sql`** escape
+    (#208, ADR-0043) — a hand-written body the tool registers, fingerprints, and
+    drift-checks (adopt a pre-existing view with `meta migrate --allow adopt-view`) —
+    rather than a hand-edited migration file where it goes accidentally unmanaged.
+    For a DB object owned entirely elsewhere (Flyway), mark its source
+    **`@unmanaged: true`** (view or table); migrate/verify then never touch it.
+    `@sql` and `@unmanaged` are mutually exclusive.
 
 `meta gen --list` prints every generator by stable name; the `generators` array in
 `metaobjects.config.ts` is where you opt each one in or out.

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

@@ -45,13 +45,33 @@ or run the default set. Output lands under `--namespace` in `--output-dir`.
 | `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). |
 | `filter-allowlist` | per-entity `<Entity>FilterAllowlist` (FR-009 — the server-side field+operator allowlist the routes validate against). |
 | `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). |
-| `output-parser` / `extractor` / `output-prompt` / `render-helper` | the `template.output` prompt-pillar artifacts (strict parser, tolerant `extract`, output-format prompt fragment, typed render helper) — see the **prompts** reference. |
+| `payload` | `<Payload>.payload.cs` — the strict typed payload `record` (+ any nested element records) per `template.output` `@payloadRef` (an `object.value`) that the parser/extractor bind to. |
+| `output-parser` / `extractor` / `output-prompt` / `render-helper` | the `template.output` prompt-pillar artifacts — 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. |
 | `template` | the generic Mustache `templateGenerator()` primitive. |
 
 Metadata lives under `metaobjects/` (or wherever you point `--metadata-dir`) in the
 same canonical JSON every port reads — fused-key form, `source.rdb` + `@table`,
 `@column` for a renamed physical column.
 
+**Entity read-view (write-through).** An `object.entity` that keeps its writable `table`
+primary source and adds a `@role: replica` `@kind: view` source is a write-through
+read-view (#214): the generated EF entity carries the derived `origin.*` fields read-only
+and `db-context` registers that read model against the replica view (`.ToView(...)`);
+reads route to the view, writes to the table (derived fields excluded), and a
+create/update re-reads the row via the view by primary key (read-your-writes). The replica
+view's DDL is emitted by the Node `meta migrate` from the same origin assembly as a
+projection view.
+
+## Docs — `dotnet meta docs`
+
+```bash
+dotnet meta docs metaobjects --out Docs   # → Docs/api/csharp (AGENT-API.md + per-entity pages)
+```
+
+`dotnet meta docs` emits this project's C# SDK api surface (`api/csharp`), including
+`AGENT-API.md` — the exact imports, signatures, and payload field shapes for the
+generated code. **Before calling any generated code, read `api/csharp/AGENT-API.md`.**
+
 ## Persistence + routes are the deployed artifact
 
 C# generates a *complete* server stack: the entity classes + `AppDbContext` ARE the

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

@@ -74,6 +74,19 @@ A `metaobjects:verify` Maven goal exists for **codegen-drift** (re-generate and
 committed output). Schema migration and live-DB drift are NOT Java goals — they run
 through the Node `meta` tool (see the migration reference).
 
+## Docs — `mvn metaobjects:docs`
+
+A separate `docs` goal (`DocsMojo` — NOT a `<generator>`) emits this project's SDK api
+surface (default `target/docs/api/java`), including `AGENT-API.md` — the exact imports,
+signatures, and payload field shapes for the generated code.
+
+```bash
+mvn metaobjects:docs   # → target/docs/api/java (AGENT-API.md + per-entity pages)
+```
+
+**Before calling any generated code, read `api/java/AGENT-API.md`** — it carries the
+concrete imports and signatures so you don't have to guess them.
+
 ## `codegen-spring` generators
 
 All live in `metaobjects-codegen-spring` under
@@ -82,19 +95,44 @@ first group together:
 
 | Generator | Output |
 |---|---|
-| `SpringControllerGenerator` | `<Entity>Controller.java` per writable entity (`source.rdb` `@kind="table"`) — Spring Web MVC, five CRUD endpoints on the cross-port REST contract (`?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. |
+| `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. |
 | `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. |
 | `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. |
-| `SpringPayloadGenerator` | a Java 21 `record` per template payload VO |
-| `SpringOutputParserGenerator` | the `template.output` parser-on-receipt (see the prompts reference) |
+| `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. |
+| `SpringPayloadGenerator` | a Java 21 `record` per `template` payload VO |
+| `SpringOutputParserGenerator` | the `template.output` strict parser-on-receipt (see the prompts reference) |
+| `SpringOutputPromptGenerator` | the FR-010 output-format prompt fragment for a `template.output` (presentation via `@promptStyle: guide`/`inline`/`exampleOnly`) |
+| `SpringRenderHelperGenerator` | the typed render helper for a `template.prompt` payload |
+| `LlmTraceHelperGenerator` | `<Entity>TraceHelper.java` per concrete entity — the LLM-trace helper |
 | `SpringFilterAllowlistGenerator` | per-entity filter allowlist |
 
 **Projections (read-only views).** An `object.projection` (read-only `source.rdb`
 `@kind: view` child) is served read-only through OMDB at the ObjectManager layer
 (mutating ops throw); no controller is generated (controllers cover writable entities
 only). Its `CREATE VIEW` DDL is emitted by the Node `meta migrate` from the
-projection's `origin.*` children — never hand-author the view SQL for a shape origins
-can express (an unmodeled view is unmanaged and drifts silently).
+projection's `origin.*` children — `origin.passthrough`, `origin.aggregate` (`@agg`
+`count`/`sum`/`avg`/`min`/`max`, plus the #195 `any`/`all` quantifiers over a `@filter`
+and `collect` array-rollup with `@distinct`/`@orderBy`), `origin.collection`,
+`origin.computed` (`@expr`), `origin.first`; an object-level `@filter` scopes the whole
+view's rows (#207 — lowers to the outer `WHERE`). Never hand-author the view SQL for a
+shape origins can express (an unmodeled view is unmanaged and drifts silently); carry a
+genuinely irreducible body (recursive CTE, window function, set op) in the `source.rdb`
+**`@sql`** escape (#208) so the tool still owns it, or mark a Flyway-owned object
+`@unmanaged: true`.
+
+**Entity read-view (write-through).** An `object.entity` that keeps its writable `table`
+primary source and adds a `@role: replica` `@kind: view` source is a write-through
+read-view (#214): OMDB routes reads through the replica view and writes to the table
+(derived `origin.*` fields excluded from the write path); a create/update re-reads the
+row via the view by primary key (read-your-writes). The replica view's DDL is emitted by
+`meta migrate` from the same origin assembly as a projection view.
+
+### Value-object jsonb columns
+
+A `field.object` with `@storage: jsonb` (single or `@isArray`) is a typed jsonb column
+backed by an `object.value`: `SpringValueObjectGenerator` emits that VO as a Java record
+and OMDB's Jackson codec serializes it to/from the column (a single VO, or `List<VO>` for
+an array) — the same typed-jsonb round-trip the other ports ship.
 
 Metadata lives under `src/main/metaobjects/` in the same canonical JSON the other
 ports read — fused-key form, `source.rdb` + `@table`, `@column` for a renamed

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

@@ -88,6 +88,19 @@ A `metaobjects:verify` Maven goal exists for **codegen-drift** (re-generate and
 vs committed output). Schema migration and live-DB drift are NOT JVM goals — they run
 through the Node `meta` tool (see the migration reference).
 
+## Docs — `mvn metaobjects:docs -Dmetaobjects.docs.language=kotlin`
+
+The shared `docs` goal (`DocsMojo`) renders the Kotlin SDK api surface via
+`KotlinApiDocsRenderer` when pointed at the Kotlin language (default `target/docs/api/kotlin`),
+including `AGENT-API.md` — the exact imports, signatures, and payload field shapes for the
+generated code.
+
+```bash
+mvn metaobjects:docs -Dmetaobjects.docs.language=kotlin   # → target/docs/api/kotlin (AGENT-API.md + per-entity pages)
+```
+
+**Before calling any generated code, read `api/kotlin/AGENT-API.md`.**
+
 ## `codegen-kotlin` generators
 
 All live in `metaobjects-codegen-kotlin` under
@@ -99,8 +112,12 @@ All live in `metaobjects-codegen-kotlin` under
 | `KotlinExposedTableGenerator` | `<Entity>Table.kt` — Exposed `Table` object (PK + FK + `@storage` columns) for entities with `source.rdb`. A TPH `@discriminator` base emits ONE `Table` for the whole hierarchy — every subtype-only column folded in `.nullable()` (a row of another subtype stores null there) — single-table inheritance; subtype entities emit no table of their own. |
 | `KotlinRelationsGenerator` | `<Entity>Relations.kt` — extension fns for `@cardinality="many"` query helpers |
 | `KotlinSpringControllerGenerator` | `<Entity>Controller.kt` — Spring `@RestController`, five CRUD endpoints on the cross-port REST contract, for writable entities (`source.rdb` `@kind="table"`). 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 are scoped to the subtype (cross-subtype → 404); the discriminator is immutable. |
+| `KotlinRepositoryGenerator` | `<Entity>RepositoryBase.kt` — an `open class` consumer persistence seam per writable entity (the Kotlin peer of Java's `SpringRepositoryGenerator`, but with method bodies). Carries the #203 `@autoSet` CRUD stamping: `onCreate` columns stamped once at insert, `onUpdate` columns re-stamped on every write, both excluded from the caller-supplied set. |
 | `KotlinPayloadGenerator` | `<Template>Payload.kt` — `@Serializable` payload data class from a template's `@payloadRef` |
-| `KotlinOutputParserGenerator` | the `template.output` parser-on-receipt (see the prompts reference) |
+| `KotlinOutputParserGenerator` | the `template.output` strict parser-on-receipt (see the prompts reference) |
+| `KotlinExtractorGenerator` | the FR-010 tolerant `extract` mapper for a `template.output` (all-nullable mirror → strict payload) |
+| `KotlinOutputPromptGenerator` | the FR-010 output-format prompt fragment for a `template.output` (presentation via `@promptStyle: guide`/`inline`/`exampleOnly`) |
+| `KotlinRenderHelperGenerator` | the typed render helper for a `template.prompt` payload |
 | `KotlinValidatorGenerator` | `MetadataStartupValidator.kt` + `ExposedTableValidator.kt` (once per project) |
 | `KotlinSpringConfigGenerator` | `MetadataExposedConfig.kt` — `@Configuration` wiring `Database.connect()` + the startup validator (once per project) |
 | `KotlinStoredProcGenerator` | stored-procedure call wrappers for `source.rdb` `@kind="storedProc"` |
@@ -109,9 +126,22 @@ All live in `metaobjects-codegen-kotlin` under
 **Projections (read-only views).** For an `object.projection` (read-only `source.rdb`
 `@kind: view` child), `KotlinExposedTableGenerator` emits a read-only Exposed `Table`
 wrapper (same column mapping, no write path). The `CREATE VIEW` DDL is emitted by the
-Node `meta migrate` from the projection's `origin.*` children — never hand-author the
-view SQL for a shape origins can express (an unmodeled view is unmanaged and drifts
-silently).
+Node `meta migrate` from the projection's `origin.*` children — `origin.passthrough`,
+`origin.aggregate` (`@agg` `count`/`sum`/`avg`/`min`/`max`, plus the #195 `any`/`all`
+quantifiers over a `@filter` and `collect` array-rollup with `@distinct`/`@orderBy`),
+`origin.collection`, `origin.computed` (`@expr`), `origin.first`; an object-level
+`@filter` scopes the whole view's rows (#207 — lowers to the outer `WHERE`). Never
+hand-author the view SQL for a shape origins can express (an unmodeled view is unmanaged
+and drifts silently); carry a genuinely irreducible body (recursive CTE, window function,
+set op) in the `source.rdb` **`@sql`** escape (#208) so the tool still owns it, or mark a
+Flyway-owned object `@unmanaged: true`.
+
+**Entity read-view (write-through).** An `object.entity` that keeps its writable `table`
+primary source and adds a `@role: replica` `@kind: view` source is a write-through
+read-view (#214): reads route through the replica view and writes to the table (derived
+`origin.*` fields excluded); a create/update re-reads the row via the view by primary key
+(read-your-writes). The replica view's DDL is emitted by `meta migrate` from the same
+origin assembly as a projection view.
 
 Metadata lives under `src/main/metaobjects/` in the same canonical JSON the other
 ports read — fused-key form, `source.rdb` + `@table`, `@column` for a renamed

package/agent-context/skills/metaobjects-codegen/references/python.md

@@ -28,6 +28,16 @@ the exact `gen` code path so the two can't diverge). `--templates` is the prompt
 drift gate (see the prompts reference). Schema migration + live-DB drift are **not**
 `metaobjects` — they run through the Node `meta` tool (see the migration reference).
 
+## Docs — `metaobjects docs`
+
+```bash
+metaobjects docs ./metadata --out ./docs   # → ./docs/api/python (AGENT-API.md + per-entity pages)
+```
+
+`metaobjects docs` emits this project's Python SDK api surface (`api/python`), including
+`AGENT-API.md` — the exact imports, signatures, and payload field shapes for the
+generated code. **Before calling any generated code, read `api/python/AGENT-API.md`.**
+
 ## Generators
 
 Wire generators by their stable name (`--generators <names>`), or run the default set.
@@ -40,9 +50,19 @@ a renamed physical column).
 | `entity` | one **Pydantic model** per `object.entity` / projection (the `entity-model` generator): typed fields from the metadata, nullability from `@required`, `@maxLength`/validators, enum fields → a Python `Enum`. This is the typed data model. A TPH concrete subtype (`@discriminatorValue`) pins the inherited `@discriminator` field to a `Literal[...]` so the model rejects a foreign-subtype tag. |
 | `routes` | a **FastAPI `APIRouter`** 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). The router declares a repository **`Protocol`** you implement and inject. A TPH `@discriminator` base emits ONE polymorphic router: `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. Its repository `Protocol` is subtype-keyed (`subtype=None` for the polymorphic base) so your implementation applies the single-table discriminator scope. |
 | `filter-allowlist` | per-entity filter allowlist (FR-009 — the server-side field+operator allowlist the routes validate against). |
-| `payload` / `output-parser` / `output-prompt` / `extractor` / `render-helper` / `trace-helper` | the `template.output` prompt-pillar artifacts — see the **prompts** reference. |
+| `payload` / `output-parser` / `output-prompt` / `extractor` / `render-helper` / `trace-helper` | the `template.output` prompt-pillar artifacts — the payload VO, the strict parser, the **output-format prompt fragment** (`output-prompt`; presentation via `@promptStyle: guide`/`inline`/`exampleOnly`), the tolerant `extract`, the typed render helper, and the LLM-trace helper. See the **prompts** reference. |
 | `template` | the generic Mustache `template` primitive. |
 
+**Projections + entity read-views.** An `object.projection` (read-only `source.rdb`
+`@kind: view` child) gets a read-only Pydantic model from the `entity` generator; its
+`CREATE VIEW` DDL is emitted by the Node `meta migrate` from the projection's `origin.*`
+children (`passthrough` / `aggregate` / `collection` / `computed` / `first`) — never
+hand-write the view SQL for a shape origins can express. An `object.entity` that adds a
+`@role: replica` `@kind: view` source alongside its writable `table` is a write-through
+**entity read-view** (#214): the generated read model carries the derived `origin.*`
+fields and writes exclude them — reads route to the view, writes to the table (your
+repository implements the split).
+
 ## Discriminator inheritance (TPH)
 
 Python codegen fully supports **table-per-hierarchy (TPH) inheritance**
@@ -77,13 +97,17 @@ persistence layer and no runnable server**. Two things you hand-write:
 
 ## Known gaps (current — may require a hand-edit)
 
-- **Single-field, `int` PKs only.** The generated router/repository assume a single
-  `int` primary key (`id: int`). Non-`int` single-field PKs and composite PKs need a
-  hand-edit until specified.
-- **DTO = `dict[str, Any]`.** Request bodies for `POST`/`PATCH`/`PUT` are typed
-  `dto: dict[str, Any]` and responses return `Any`; the repository `Protocol` uses
-  `Any` for the row type. The typed Pydantic model from the `entity` generator exists —
-  you can tighten the router signatures to it by hand.
+- **Composite PKs need a hand-edit.** The generated router/repository key on a single
+  primary key whose Python type is **derived from the PK field's subtype** (`field.uuid`
+  PK → `uuid.UUID`, `field.long` → `int`, `field.string` → `str`) via the same mapper the
+  Pydantic model uses — so a `field.uuid` PK is `uuid.UUID`, not `int`. A **composite** PK
+  falls back to `@fields[0]` and needs a hand-edit until specified.
+- **DTO param is `dict[str, Any]`.** The `POST`/`PATCH`/`PUT` body param is typed
+  `dto: dict[str, Any]` and responses return `Any`; the repository `Protocol` uses `Any`
+  for the row type. This does **not** mean constraints are unenforced — the router
+  validates the body against the generated `<Entity>Create` / `<Entity>Patch` Pydantic
+  models before the repository call (FR-036: field constraints run on POST/PATCH over
+  HTTP). You can further tighten the router signatures to the typed model by hand.
 
 ## Re-scaffold this context
 

package/agent-context/skills/metaobjects-codegen/references/typescript.md

@@ -79,14 +79,30 @@ From `@metaobjectsdev/codegen-ts/generators` (server-side, framework-neutral):
 | `barrel()` | `index.ts` re-exporting each `<Entity>.ts` (one-shot, not per-entity) |
 | `promptRender()` | `render<Name>()` per `template.prompt` |
 | `outputParser()` | `<Name>.output.ts` (`parse*` / `safeParse*`) per `template.output` |
+| `callableFile()` | `<Entity>.callable.ts` — an FR-015 `call<Entity>` wrapper for a `source.rdb` `@kind: storedProc`/`tableFunction` (args from the `@parameterRef` value object, in declaration order) |
 
 **Projections (read-only views).** For an `object.projection` (a read-only `source.rdb`
 `@kind: view` child), `entityFile()` emits a `pgView(...)` + read-only Zod + a read-only
 finder (no create/update/delete). The `CREATE VIEW` DDL is generated by `meta migrate`
 from the projection's `origin.*` children — `origin.passthrough` (a forwarded column),
-`origin.aggregate` (a `count`/`sum`/`avg`/`min`/`max`, optionally row-scoped with
-`@filter`), `origin.collection` (a nested array). **Never hand-write the view SQL** for a
-shape origins can express; an unmodeled view is unmanaged and drifts silently.
+`origin.aggregate` (`@agg` `count`/`sum`/`avg`/`min`/`max`, plus the #195 `any`/`all`
+predicate quantifiers over a `@filter` and `collect` array-rollup with optional
+`@distinct`/`@orderBy`; any aggregate row-scoped with `@filter`), `origin.collection` (a
+nested array), `origin.computed` (a row-level `@expr`), `origin.first` (one related row's
+column along `@via`/`@of`/`@orderBy`). An object-level `@filter` on the projection scopes
+the whole view's rows (#207 — lowers to the outer `WHERE`, the metadata-managed
+soft-delete/status view). **Never hand-write the view SQL** for a shape origins can
+express (an unmodeled view is unmanaged and drifts silently); for a genuinely irreducible
+body (recursive CTE, window function, set op), carry it in the `source.rdb` **`@sql`**
+escape (#208) so the tool still owns it, or mark a Flyway-owned object `@unmanaged: true`.
+
+**Entity read-view (write-through).** An `object.entity` that keeps its writable `table`
+primary source and adds a `@role: replica` `@kind: view` source is a write-through
+read-view (#214): `entityFile()` routes generated **reads** through the replica `pgView`
+(the read Zod carries the derived `origin.*` fields via `z.infer`), while `queriesFile()`
+writes target the table with derived fields excluded from the insert/update codecs; a
+create/update re-reads the row via the view by primary key (read-your-writes). The replica
+view's DDL is emitted by `meta migrate` from the same origin assembly as a projection view.
 
 ## Discriminator inheritance (TPH)
 

package/agent-context/skills/metaobjects-fit-assessment/SKILL.md

@@ -17,8 +17,8 @@ fetch it from GitHub / metaobjects.dev) and let it produce the report below.
 
 # MetaObjects Fit & Migration Assessment
 
-_Assessment prompt v1 (post-Phase-0 refinement). Grounded against MetaObjects npm `0.15.x` /
-Maven `7.7.x` — verify every capability claim against the current release before asserting it._
+_Assessment prompt v1 (post-Phase-0 refinement). Grounded against MetaObjects npm `0.17.x` /
+Maven `7.9.x` — verify every capability claim against the current release before asserting it._
 
 You are an AI assistant running a **pre-adoption fit assessment** for MetaObjects
 (https://github.com/metaobjectsdev/metaobjects — the cross-language metadata standard:
@@ -235,12 +235,27 @@ signature class. Hunt all ten classes:
 8. Hand-written `CREATE VIEW` / read-only SQL mirroring a read model. Run the
    **necessity test**: expressible when every output column is a passthrough
    (`origin.passthrough @from/@via`), a count/sum/avg/min/max (`origin.aggregate
-   @agg/@of/@via`, row-scoped with `@filter`), a child collection (`origin.collection`),
-   or `extends`-borrowed — and joins follow declared relationships/`identity.reference`
-   FKs. Expressible → projection candidate (note: an unmodeled hand view is *unmanaged*
-   — invisible to `verify --db`; modeling it is what makes it gateable). Not
-   expressible → BESPOKE with a NAMED construct (recursive CTE, window fn, set op,
-   `DISTINCT ON`, lateral join). "It's an aggregation" is not a justification.
+   @agg/@of/@via`, row-scoped with `@filter`), a predicate quantifier (`origin.aggregate
+   @agg: any|all`), an array rollup (`origin.aggregate @agg: collect`), a non-aggregate
+   derived scalar (`origin.computed @expr`), an argmax-style "one related row's column"
+   pick (`origin.first @via` — covers the common `DISTINCT ON` / lateral-join shape), a
+   child collection (`origin.collection`), a soft-delete/status/type row-scope (an
+   object-level `@filter` on `object.projection`), or `extends`-borrowed — and joins
+   follow declared relationships/`identity.reference` FKs. Expressible → projection
+   candidate (note: an unmodeled hand view is *unmanaged* — invisible to `verify --db`;
+   modeling it is what makes it gateable). `DISTINCT ON` and lateral join are **not**
+   automatic BESPOKE justifications — check `origin.first` first; they earn BESPOKE only
+   when the pick can't collapse to one argmax over one `@via` path (a multi-column
+   tiebreak, or a lateral doing more than pick-one-row). Not expressible → BESPOKE with a
+   NAMED construct (recursive CTE, window fn, set op, a `DISTINCT ON`/lateral join
+   `origin.first` genuinely can't express). "It's an aggregation" is not a justification.
+   BESPOKE has a better ending than "hand-write it outside the tool": if the body is
+   irreducible but still **yours** to own, carry it in the `source.rdb` **`@sql`** escape
+   (#208, ADR-0043) — a hand-written view/proc body the tool registers, fingerprints, and
+   drift-checks (adopt a pre-existing view with `meta migrate --allow adopt-view`, no
+   rewrite needed); if the object is owned **elsewhere** (Flyway, another team's
+   migration), mark its source `@unmanaged: true` so `verify --db` reports it as an
+   external, declared object instead of silently missing it.
 9. A closed variant-set hand-modeled per instance (N sibling modules on one payload
    shape) → VOCAB CANDIDATE (advisory only; ADR-0037 ordered test).
 10. One prompt's text/payload/parse scattered across services — a renamed field silently
@@ -273,8 +288,14 @@ concrete — lead with it.
 | the metadata itself | strict provenance (ADR-0023): unknown attrs fail load |
 
 State the honest limits in the same section: `verify` cannot catch semantic mismodeling
-(a uuid modeled as string passes `--db`), cannot see unmodeled DB objects, and
-`--templates` coverage depends on CLI version. A gate, not a proof system.
+(a uuid modeled as string passes `--db`), cannot see a genuinely unmodeled DB object
+(nothing ever declared it), and `--templates` coverage depends on CLI version. Name the
+two declared middle states before writing something off as unmodeled: an
+irreducible-but-owned view/proc registered via `source.rdb @sql` (#208) IS fingerprinted
+and drift-checked, and an object owned by another team's tooling can be declared
+`@unmanaged: true` so `verify --db` reports it as external rather than missing it
+silently — "unmodeled" applies only to what was never declared at all. A gate, not a
+proof system.
 
 ### P4 — Fit rubric (worked, not vibes)
 
@@ -293,7 +314,7 @@ this table worked row-by-row is invalid output):
 | DB not Postgres/SQLite/D1 | schema pillar (`migrate`, `verify --db`) OUT — say so plainly; data-access unaffected |
 | Non-entity-shaped domain (no persistent typed records to speak of) | NOT A FIT — structural, and visible in the code |
 | Few entities today (< ~5) | **NOT a flat verdict — this is the M8 trap.** Small-today ≠ small-forever, and git cannot tell you which. Use the trajectory answer (Input 3): *done at this size* → MARGINAL/NOT A FIT (say so plainly — the leverage won't repay the tooling); *expected to grow / add a language / add an LLM surface* → FIT, and note adopting later costs more (you'd retrofit a spine onto more drift). **Unanswered → emit both branches, never guess.** |
-| Schema owned by another team (DBA-gated) | migrate pillar restricted; model read-only ("metadata follows the schema"); flag the org constraint |
+| Schema owned by another team (DBA-gated) | migrate pillar restricted; model read-only ("metadata follows the schema"); objects that stay owned by that team's own tooling can be declared `source.rdb @unmanaged: true` instead of silently excluded; flag the org constraint |
 | Deep hand-tuned ORM investment | churn warning, not a disqualifier: the plan must reproduce those mappings (`@column`/`@table`/`@dbColumnType`) and price it |
 | Team rejects generated code in the repo | flag; regen-every-build works but `verify --codegen` semantics differ — call the tradeoff |
 
@@ -355,9 +376,21 @@ promising it or counting it in benefits:
   from behavior).
 - UUIDs as bare strings → `field.uuid` (never `field.string` + `@dbColumnType: uuid`).
 - hand `COUNT/SUM` subqueries, read-model SQL → `object.projection` + `origin.passthrough`
-  / `origin.aggregate` (+`@filter` for scoped aggregates) / `origin.collection`.
+  / `origin.aggregate` (`count`/`sum`/`avg`/`min`/`max`, +`@filter` for scoped
+  aggregates, +`any`/`all` predicate quantifiers, +`collect` array rollups) /
+  `origin.collection` / `origin.computed` (a non-aggregate derived scalar) /
+  `origin.first` (an argmax-style "one related row's column" pick — the usual
+  `DISTINCT ON`/lateral-join case) — plus a soft-delete/status/type view via the
+  object-level `@filter` on `object.projection` instead of a hand `WHERE`.
   **Calibration: most projection fields in real spines are passthrough/`extends`
   re-exposures; aggregates are the minority — lead with passthrough.**
+- a hand-maintained denormalized/computed column kept in sync by app code (an "update
+  the other row on write" helper mirroring a joined value onto the entity's own row) →
+  an **entity read-view** on the same `object.entity` before reaching for a projection:
+  keep the writable `table` source, add a non-primary read-only `view` source, and
+  declare the extra as a derived `origin.*` field — writes still target the table,
+  reads route through the view and re-read by PK (#214; see `docs/features/source-kinds.md`
+  "entity read-view vs projection" for when to use which).
 - hand junction joins → `relationship @cardinality: many @through` (junction declares
   two `identity.reference` children; FR-018).
 - copy-pasted base-field blocks → abstract base + `extends`.
@@ -491,14 +524,18 @@ Every prose prediction gets a claim. Ceiling statements (P5-b) MUST carry
   access still works; say it plainly.
 - **TS**: full stack — Drizzle/Zod/Fastify codegen, filter-operator routes, TanStack/React
   UI runtime, migrations. The only port with UI codegen + runtime.
-- **Java/Spring**: generated DTO records, controllers, filter allowlists (pagination/sort;
-  filter ops deferred), repository *interfaces* (consumer implements — existing ORM sits
-  behind unchanged), payload records, output parsers hand-write the Jackson one-liner;
-  entities stay hand-written on this lane; Maven `meta:gen` / `meta:verify`
-  (`codegen`/`templates` modes — no live-DB mode).
+- **Java/Spring**: generated DTO records, controllers (parse + validate the full FR-009
+  filter-op grammar via the generated `FilterAllowlist` + the `FilterParser` runtime
+  helper — per-field op allowlist, `in`-list cap, `eq` sugar; api-contract is 20/20 both
+  lanes), filter + sort allowlists (pagination/sort), repository *interfaces* (consumer
+  implements — existing ORM sits behind unchanged; the consumer's repository impl
+  translates the returned predicates to its persistence DSL), payload records, output
+  parsers hand-write the Jackson one-liner; entities stay hand-written on this lane;
+  Maven `mvn metaobjects:generate` / `mvn metaobjects:verify` (`codegen`/`templates`
+  modes — no live-DB mode).
 - **Kotlin/JVM**: `codegen-kotlin` generates entity + Exposed table + Spring controller +
   payload + relations + filter allowlist + validators + output parsers (runs via Maven
-  `meta:gen`).
+  `mvn metaobjects:generate`).
 - **C#**: generated EF Core entities + `AppDbContext` + CRUD minimal-API routes +
   render/payload/verify via `dotnet meta gen`/`verify`; no ObjectManager runtime tier;
   no migrate surface (TS-owned).

package/agent-context/skills/metaobjects-prompts/SKILL.md

@@ -21,18 +21,35 @@ value-object declaring exactly what data the text expects.
 
 | Subtype | Use | Extra attrs |
 |---|---|---|
-| `template.prompt` | LLM-targeted | `@maxTokens`, `@requiredSlots`, `@model` |
-| `template.output` | email / docs / config / export | (generic only) |
+| `template.prompt` | LLM-targeted | `@maxTokens`, `@requiredSlots`, `@requiredTags`, `@model`, `@responseRef` |
+| `template.output` | email / docs / config / export | `@kind: document \| email` (default `document`), `@promptStyle`, `@requiredTags`; `@kind: email` adds `@subjectRef` / `@htmlBodyRef` / `@textBodyRef` |
 
 Both carry the generic attrs:
 
 | Attr | Required | Purpose |
 |---|---|---|
 | `@payloadRef` | yes | the `object.value` declaring the payload shape |
-| `@textRef` | yes | the 2-layer logical text reference `group/source`, resolved by a provider |
+| `@textRef` | yes for `template.prompt` and a `template.output @kind: document` (the default) — a `template.output @kind: email` carries **no** `@textRef`; it uses `@subjectRef` + `@htmlBodyRef` (+ optional `@textBodyRef`) instead | the 2-layer logical text reference `group/source`, resolved by a provider |
 | `@format` | no | `text` (default) / `html` / `xml` / `csv` / `json` / `markdown` / `spreadsheet` — drives the escaper |
 | `@maxChars` | no | build-time size budget |
 
+`template.output @kind: email` renders a structured `EmailDocument` (subject + HTML
+body + optional plain-text body) instead of one string — the TS render helper emits
+an `EmailDocument`-returning function for it (see the `render-example-email`
+conformance fixture). `@promptStyle` (`guide` / `inline` / `exampleOnly`, FR-010)
+selects how the output-format prompt fragment presents the payload shape to an LLM
+(see "the output-format prompt fragment" below); `@requiredTags` names output tags
+the rendered text must contain (`verify` checks it) on both subtypes.
+`template.prompt` additionally carries `@responseRef` — naming the response
+value-object the prompt expects, for typed LLM-call trace derivation.
+
+A third, structurally different subtype is also registered core vocabulary:
+**`template.toolcall`** (`@toolName` + `@payloadRef`, ADR-0011) — a vendor-agnostic
+LLM tool-call envelope with no renderable text body (the body IS the
+`@payloadRef`-typed output schema, so it does not carry the generic `@textRef`/
+`@format` attrs above). The vocabulary exists today; MCP exposure of declared
+prompts/tools is roadmap, not shipped — don't promise it.
+
 ## The payload is an `object.value` projection
 
 The payload is **not** an entity — it's an `object.value` whose every field carries
@@ -44,6 +61,13 @@ an `origin.*` child saying where its value comes from. Three origin subtypes:
 | `origin.aggregate @agg <count\|sum\|avg\|min\|max>` | `count`→long, `avg`→double, others match source |
 | `origin.collection @via "Parent.rel"` | a list of a nested payload, assembled from a relationship |
 
+These are the **payload-assembly** origins — the vocabulary this skill covers.
+**Projection** read models (`object.projection` over an entity) carry a fuller origin
+vocabulary — the `@agg` predicate quantifiers `any`/`all`, the `collect` array rollup,
+plus `origin.computed` (a closed `@expr` grammar) and `origin.first` (an argmax-style
+pick) — those live in the `metaobjects-authoring` skill and
+`docs/features/source-kinds.md`, not here: don't reach for them on a payload VO.
+
 Declaring the payload as a projection is what makes payload bloat visible: adding a
 field to the prompt is a diff on the `object.value`, and a renamed source field
 breaks the build instead of silently degrading the prompt.
@@ -184,6 +208,43 @@ file; `verify` catches payload-VO ↔ parser drift at build time too.
 The three-step consumer pattern is identical everywhere: render the prompt → call
 your LLM client → parse the response with the generated parser.
 
+## `template.output` also generates the output-format prompt fragment (FR-010)
+
+For every **json/xml-format** `template.output` whose `@payloadRef` resolves to a
+value-object, codegen additionally emits an `output-prompt` artifact: a
+`render<Name>Format(...)`-shaped function backed by the render engine's
+output-format renderer — the "produce your answer like this" instruction fragment
+you splice into the prompt text so the model returns exactly the shape the parser
+above expects. It's generated only for `json`/`xml` outputs (`text`/`html`/`csv`/
+`markdown`/`spreadsheet` don't get a fragment) and skipped under the same
+unresolved-`@payloadRef` rule as the parser; the fragment and the parser's
+`extract()` codegen agree on the same root name.
+
+`@promptStyle` on the `template.output` controls the fragment's presentation
+(default `guide`):
+
+| `@promptStyle` | Presentation |
+|---|---|
+| `guide` (default) | a prose field list ("Fill in each field…") followed by an example skeleton |
+| `inline` | a single skeleton whose field values are inline placeholders / enum choices |
+| `exampleOnly` | just a filled example skeleton, nothing else |
+
+Guidance is **never** emitted as code comments — models routinely ignore comments,
+so the instruction has to live in the rendered text itself.
+
+The fragment is **baked directly from the payload's field tree at codegen time**
+(not hand-authored Mustache text), so it cannot itself drift out of sync with the
+payload the way a hand-written `@textRef` can — regenerating it after a payload
+change is the gate. The JVM render module (Java, shared by Kotlin) additionally
+exposes a field-presence check, `Verify.checkOutputPrompt(fragment,
+requiredFieldNames)`, for asserting a *rendered instance* of the fragment actually
+names every required field — useful in a test of the renderer output itself,
+distinct from the `{{field}}`-vs-payload drift check `verify` runs on hand-authored
+template text. Check the language reference for whether this project's port ships
+the equivalent.
+
 ---
 
-For this project's server-language parser specifics, read every `references/*.md` file in this skill's directory (one per server language in this project's stack).
+For this project's server-language parser + output-format-fragment specifics, read
+every `references/*.md` file in this skill's directory (one per server language in
+this project's stack).

package/agent-context/skills/metaobjects-prompts/references/csharp.md

@@ -9,6 +9,7 @@ the payload generator, so the parser and the payload VO can't silently drift.
 ## Contents
 - Wire the generator
 - What it emits
+- The output-format prompt fragment (FR-010)
 - The three-step consumer pattern
 - Recommended LLM caller (bring-your-own)
 - Consumer dependency
@@ -52,6 +53,26 @@ generator also emits a tolerant `Extract(string[, ExtractOptions])` (self-contai
 components) returning an `ExtractionResult` with a nullable `<Payload>Extracted` mirror
 — a classified per-field report rather than a throw.
 
+## The output-format prompt fragment (FR-010)
+
+For every json/xml-format `template.output`, `MetaObjects.Codegen`'s
+`OutputPromptGenerator` (stable name `output-prompt-generator`) emits a
+`<TemplateName>.prompt.cs` declaring a static `<TemplateName>Prompt` class with a
+`RenderFormat()` / `RenderFormat(PromptOverrides)` pair, backed by the render
+engine's `OutputFormatRenderer` — the "produce your answer like this" fragment for
+the model. It runs as part of the same `dotnet meta gen` invocation as the payload
+and parser generators:
+
+```bash
+dotnet meta gen ./metadata --out ./Generated --namespace Acme.Blog
+```
+
+`@promptStyle` on the `template.output` (`guide` default / `inline` / `exampleOnly`)
+controls the fragment's presentation; guidance is never emitted as comments. Skipped
+for `template.prompt` nodes, non-json/xml `@format`, and an unresolved
+`@payloadRef` — the same skip contract as the parser generator. The baked spec's
+root name is the payload class name, agreeing with the parser's root.
+
 ## The three-step consumer pattern
 
 Render the prompt → call your LLM client (provider-agnostic; nothing is generated