@metaobjectsdev/sdk 0.23.2 → 0.24.1

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

@@ -114,9 +114,9 @@ All live in `metaobjects-codegen-kotlin` under
 | `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` 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`) |
+| `KotlinOutputParserGenerator` | 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. |
+| `KotlinExtractorGenerator` | the FR-010 tolerant `extract` mapper for a responding `template.prompt` (all-nullable mirror → strict payload) |
+| `KotlinOutputPromptGenerator` | the FR-010 output-format prompt fragment for a responding `template.prompt` (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) |
@@ -129,7 +129,7 @@ wrapper (same column mapping, no write path). The `CREATE VIEW` DDL is emitted b
 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
+`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,

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

@@ -38,6 +38,16 @@ metaobjects docs ./metadata --out ./docs   # → ./docs/api/python (AGENT-API.md
 `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`.**
 
+**The two `docs` positionals are NOT the same argument.** This one is the METADATA
+directory. The Node `meta docs` positional — used by every stack, since `migrate`,
+`verify --db` and the neutral model docs are Node-only — is the PROJECT ROOT that
+CONTAINS the metadata. Run `meta docs` with no positional, from the project root:
+
+```bash
+metaobjects docs ./metadata --out ./docs   # Python: the METADATA dir
+meta docs --out ./docs                     # Node: run from the PROJECT ROOT (no positional)
+```
+
 ## Generators
 
 Wire generators by their stable name (`--generators <names>`), or run the default set.
@@ -50,13 +60,13 @@ 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 — 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. |
+| `payload` / `output-parser` / `output-prompt` / `extractor` / `render-helper` / `trace-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 payload VO, the strict parser (`<template>_response_parser`), the **output-format prompt fragment** (`<template>_response_format`; 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
+children (`passthrough` / `aggregate` / `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.*`

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

@@ -67,6 +67,17 @@ block, and the inferred types.
 A second file, `.metaobjects/config.json`, holds static project state parseable by
 non-TS tooling; `meta init` scaffolds both plus the `metaobjects/` source dir.
 
+`sources` in that file is where the metadata lives — `metaobjects/` is only its
+DEFAULT value, so a project can point it anywhere. **Every entry is an OBJECT, never
+a bare string**, and it names a DIRECTORY or a file:
+
+```jsonc
+{ "schema_version": 1, "sources": [{ "path": "model" }, { "path": "../shared/metadata" }] }
+```
+
+Every command's directory argument (`meta docs <project-root>`, `--cwd`) is the
+PROJECT ROOT that CONTAINS the metadata — never the metadata directory itself.
+
 ## The generators
 
 From `@metaobjectsdev/codegen-ts/generators` (server-side, framework-neutral):
@@ -78,7 +89,7 @@ From `@metaobjectsdev/codegen-ts/generators` (server-side, framework-neutral):
 | `routesFile()` | `<Entity>.routes.ts` — Fastify CRUD routes on the cross-port REST contract. `routesFileHono()` is the Hono/Workers variant. A TPH `@discriminator` base mounts polymorphic `GET /<base>(+/:id)` plus a per-subtype CRUD set at `<basePath>/<discriminatorValue lowercased>` — create omits the discriminator (the URL names the subtype; the runtime injects it); get/update/delete scoped to the subtype (cross-subtype → 404); discriminator immutable via the runtime `discriminator` option. |
 | `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` |
+| `outputParser()` | `<Name>.response.ts` (`parse*` / `safeParse*`) per **responding `template.prompt`** — one carrying `@responseRef` (ADR-0052: this tier is INBOUND; `template.output` is outbound only and emits nothing here). Siblings: `outputPrompt()` → `<Name>.responseFormat.ts` (the FR-010 output-format fragment, presentation via `@promptStyle`), `extractor()` → `<Name>.extractor.ts` (the tolerant `extract` mapper). |
 | `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`
@@ -87,8 +98,8 @@ finder (no create/update/delete). The `CREATE VIEW` DDL is generated by `meta mi
 from the projection's `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 row-scoped with `@filter`), `origin.collection` (a
-nested array), `origin.computed` (a row-level `@expr`), `origin.first` (one related row's
+`@distinct`/`@orderBy`; any aggregate row-scoped with `@filter`),
+`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

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

@@ -28,7 +28,7 @@ cite. (3) Whether anyone fills the ledger in is itself untested; advertising it
 is the brochure failure this skill exists to avoid.
 
 TRIGGER to revisit — the release carrying `requirement.*` has shipped, AND either:
-  Arm A  a dogfooded project's `abandoned`/`superseded` entries are shown, retrospectively,
+  Arm A  a dogfooded project's retired capabilities are shown, retrospectively,
          to have been discoverable PRE-adoption from repo evidence at file:line standard
          (removal commit, dead flag, do-not-reintroduce comment);
   Arm B  a team that adopted via this assessment hits a resurrection the ledger would have
@@ -267,8 +267,8 @@ signature class. Hunt all ten classes:
    @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
+   pick (`origin.first @via` — covers the common `DISTINCT ON` / lateral-join shape),
+   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`;
@@ -407,7 +407,7 @@ promising it or counting it in benefits:
 - hand `COUNT/SUM` subqueries, read-model SQL → `object.projection` + `origin.passthrough`
   / `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.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`.

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

@@ -19,10 +19,13 @@ language lives in a reference fragment (pointed to at the bottom).
 A **template** is a typed pair: a logical reference to external text + a payload
 value-object declaring exactly what data the text expects.
 
-| Subtype | Use | Extra attrs |
-|---|---|---|
-| `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` |
+A template subtype's axis is **DIRECTION** — which way the text travels, not what it
+is about (ADR-0052).
+
+| Subtype | Direction | Use | Extra attrs |
+|---|---|---|---|
+| `template.prompt` | outbound, and optionally inbound | LLM-targeted | `@maxTokens`, `@requiredSlots`, `@requiredTags`, `@model`, `@responseRef`, `@responseFormat`, `@promptStyle` |
+| `template.output` | outbound ONLY | email / docs / config / export | `@kind: document \| email` (default `document`), `@requiredTags`; `@kind: email` adds `@subjectRef` / `@htmlBodyRef` / `@textBodyRef` |
 
 Both carry the generic attrs:
 
@@ -36,13 +39,22 @@ Both carry the generic attrs:
 `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
-shape (an `object.value` or sourceless `object.projection`, #210) the prompt
-expects, for typed LLM-call trace derivation.
+conformance fixture). `@requiredTags` names output tags the rendered text must contain
+(`verify` checks it) on both subtypes.
+
+**The INBOUND half belongs to `template.prompt` alone.** `@responseRef` names the
+response shape (an `object.value` or sourceless `object.projection`, #210) a model's
+reply is parsed into, and its PRESENCE is what asks for the whole inbound tier: the
+response record, the response-format fragment, the parser-on-receipt and the tolerant
+extractor. `@responseFormat` (`json` default / `xml`, ADR-0053) is the syntax of that
+REPLY; `@promptStyle` (`guide` / `inline` / `exampleOnly`, FR-010) selects how the
+fragment presents the shape.
+
+> **`@format` and `@responseFormat` are different facts.** `@format` is the syntax of
+> the BODY you render; `@responseFormat` is the syntax of the answer you expect. A
+> plain-text prompt asking for a JSON object is the common case. Putting `@promptStyle`
+> or `@responseFormat` on a `template.output` is a LOAD ERROR — an output renders a
+> document and nothing reads a reply to it.
 
 A third, structurally different subtype is also registered core vocabulary:
 **`template.toolcall`** (`@toolName` + `@payloadRef`, ADR-0011) — a vendor-agnostic
@@ -63,7 +75,7 @@ declared `field.<subType>` + `isArray` + `@objectRef`, and a nested payload is a
 declared `field.object @objectRef` to another `object.value` (`isArray: true` for a
 list — nested targets stay value-only, loader-enforced). The caller supplies the
 field values at render time. An `origin.*` child on a payload field is IGNORED for
-typing — and the assembly origins (`aggregate` / `collection` / `computed` /
+typing — and the assembly origins (`aggregate` / `computed` /
 `first`) are ILLEGAL on an `object.value` host (`ERR_SUBTYPE_RULE_VIOLATION`, #210):
 an origin-derived payload lives on the sourceless projection, which `@payloadRef`
 accepts. Projections generally are covered by the `metaobjects-authoring` skill and
@@ -192,33 +204,42 @@ For every template, the verify step resolves the text, parses each `{{...}}`
 reference, and checks it exists on the payload VO. If the text references
 `{{authorName}}` but the payload only has `displayName`, **the build fails.** This
 is the prompt-vs-payload drift gate — run it in CI. It walks both `template.prompt`
-and `template.output` nodes the same way.
+and `template.output` nodes the same way (both RENDER; only the direction of what comes
+back differs).
+
+## A RESPONDING `template.prompt` generates a parser-on-receipt
+
+For every `template.prompt` declaring `@responseRef`, codegen emits a **typed parser**
+that turns a model's reply back into that shape. It binds `@responseRef`, never
+`@payloadRef` — `@payloadRef` types the request the prompt renders outbound, and the
+question and the answer are usually different shapes. Each port emits the parser
+idiomatically: a throw-on-invalid parse plus, where the language has the precedent, a
+Result-style "safe" variant that doesn't throw.
 
-## `template.output` also generates a parser-on-receipt
+**A `template.output` gets no parser, ever.** Nothing reads a reply to a document. (Before
+ADR-0052 it did, with no format filter at all — so an `@format: markdown` document got a
+generated `JSON.parse` over rendered prose.)
 
-For every `template.output`, codegen emits a **typed parser** that turns an LLM/raw
-response back into the `@payloadRef` value-object — the reverse direction, reusing
-the same payload VO (no new authoring). Each port emits it idiomatically: a
-throw-on-invalid parse plus, where the language has the precedent, a Result-style
-"safe" variant that doesn't throw. The parser file is a companion to the payload-VO
-file; `verify` catches payload-VO ↔ parser drift at build time too.
+The strict tier is JSON-only: an `@responseFormat: xml` reply gets the tolerant extract
+and nothing strict, because strict all-or-nothing semantics layered over a REPAIRING XML
+reader would raise or accept based on how much repair happened.
 
 The three-step consumer pattern is identical everywhere: render the prompt → call
-your LLM client → parse the response with the generated parser.
+your LLM client → parse the reply with the generated parser.
 
-## `template.output` also generates the output-format prompt fragment (FR-010)
+## A RESPONDING `template.prompt` generates the response-format 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.
+For every `template.prompt` whose `@responseRef` resolves, codegen additionally emits 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. The gate is
+`@responseRef` PRESENCE, not a format value: the old `@format ∈ {json,xml}` gate read the
+syntax of the OUTBOUND body to decide whether to instruct the model about the syntax of
+its REPLY, so a text-bodied prompt asking for a JSON answer got no fragment at all.
+`@responseFormat` selects which syntax the fragment teaches; the fragment and the
+extractor agree on the same root name.
 
-`@promptStyle` on the `template.output` controls the fragment's presentation
+`@promptStyle` on the `template.prompt` controls the fragment's presentation
 (default `guide`):
 
 | `@promptStyle` | Presentation |

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

@@ -1,15 +1,18 @@
 # C# parser-on-receipt
 
-For every `template.output`, `MetaObjects.Codegen`'s `OutputParserGenerator` emits a
-**typed parser** that validates an LLM/raw response against the template's
-`@payloadRef` payload record. This is the receive side only — codegen emits **no**
-provider/LLM-call layer; you compose the call yourself. The payload record comes from
-the payload generator, so the parser and the payload VO can't silently drift.
+For every RESPONDING `template.prompt` — one declaring `@responseRef` —
+`MetaObjects.Codegen`'s `OutputParserGenerator` emits a **typed parser** that validates
+a model's reply against that shape. ADR-0052: the tier binds `@responseRef`, never
+`@payloadRef` (which types the request the prompt renders outbound), and a
+`template.output` gets no parser at all. This is the receive side only — codegen emits
+**no** provider/LLM-call layer; you compose the call yourself. C# names records after the
+resolved VALUE OBJECT, so the response record simply IS that VO's record — no second
+naming convention, and the parser and the record can't silently drift.
 
 ## Contents
 - Wire the generator
 - What it emits
-- The output-format prompt fragment (FR-010)
+- The response-format prompt fragment (FR-010)
 - The three-step consumer pattern
 - Recommended LLM caller (bring-your-own)
 - Consumer dependency
@@ -27,12 +30,14 @@ dotnet meta gen ./metadata --out ./Generated --namespace Acme.Blog
 
 ## What it emits
 
-Per `template.output`, `dotnet meta gen` writes one `<TemplateName>.output.cs` with a
-static `<TemplateName>Parser` following the .NET BCL `Parse`/`TryParse` dual API —
+Per responding `template.prompt`, `dotnet meta gen` writes one
+`<PromptName>.response.cs` with a static `<PromptName>Parser` following the .NET BCL
+`Parse`/`TryParse` dual API. The strict tier is JSON-only — an `@responseFormat: xml`
+reply gets the tolerant extract and neither `Parse` nor `TryParse` —
 `Parse` throws, `TryParse` returns a bool plus an out-error:
 
 ```csharp
-// generated <TemplateName>.output.cs (shape)
+// generated <PromptName>.response.cs (shape)
 public static class NpcResponseParser
 {
     /// <exception cref="JsonException">malformed JSON or schema mismatch.</exception>
@@ -53,25 +58,25 @@ 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)
+## The response-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
+For every responding `template.prompt`, `MetaObjects.Codegen`'s `OutputPromptGenerator`
+(stable name `output-prompt-generator`) emits a `<PromptName>.responseFormat.cs`
+declaring a static `<PromptName>ResponseFormat` 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.
+`@promptStyle` on the `template.prompt` (`guide` default / `inline` / `exampleOnly`)
+controls the fragment's presentation; guidance is never emitted as comments. Skipped for
+`template.output` nodes and an unresolved `@responseRef` — the same skip contract as the
+parser generator. There is NO format gate: the old `@format ∈ {json,xml}` test read the
+syntax of the outbound body to decide whether to describe the reply. The baked spec's
+root name is the response record's, agreeing with the parser's root.
 
 ## The three-step consumer pattern
 

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

@@ -1,14 +1,16 @@
 # Java parser-on-receipt
 
-For every `template.output`, `codegen-spring`'s `SpringOutputParserGenerator` emits
-a **typed parser** that validates an LLM/raw response against the template's
-`@payloadRef` payload record. This is the receive side only — codegen emits **no**
-provider/LLM-call layer; you compose the call yourself.
+For every RESPONDING `template.prompt` — one declaring `@responseRef` —
+`codegen-spring`'s `SpringOutputParserGenerator` emits a **typed parser** that validates
+a model's reply against that shape. ADR-0052: the tier binds `@responseRef`, never
+`@payloadRef` (which types the request the prompt renders outbound), and a
+`template.output` gets no parser at all. This is the receive side only — codegen emits
+**no** provider/LLM-call layer; you compose the call yourself.
 
 ## Contents
 - Wire the generator
 - What it emits
-- The output-format prompt fragment (FR-010)
+- The response-format prompt fragment (FR-010)
 - The three-step consumer pattern
 - Recommended LLM caller (bring-your-own)
 - Drift gate
@@ -31,17 +33,20 @@ the payload record it parses into) to the Maven plugin's `<generators>` list:
 
 ## What it emits
 
-Per `template.output`, `mvn metaobjects:generate` writes a `<Name>Parser` class with a static
-`parse` method returning the `@payloadRef` payload record. The strict path throws
-`com.fasterxml.jackson.core.JsonProcessingException` on malformed input:
+Per responding `template.prompt`, `mvn metaobjects:generate` writes a `<Name>Parser`
+class with a static `parse` method returning the `<Name>Response` record — this port's
+records are TEMPLATE-named, so a responding prompt gets a SECOND record beside
+`<Name>Payload`. The strict path throws
+`com.fasterxml.jackson.core.JsonProcessingException` on malformed input, and is
+JSON-only: an `@responseFormat: xml` reply gets the tolerant extract and no `parse`:
 
 ```java
 // generated <Name>Parser.java (shape)
 public final class NpcResponseParser {
     private NpcResponseParser() { }   // no instances
 
-    public static NpcResponsePayload parse(String text) throws JsonProcessingException {
-        // Jackson-backed: validates the text against the payload record
+    public static NpcResponseResponse parse(String text) throws JsonProcessingException {
+        // Jackson-backed: validates the text against the @responseRef record
     }
 }
 ```
@@ -61,10 +66,10 @@ reference) return `MetaObjectAware` instances instead, and those need
 `JsonObjectWriter`/`MetaObjectSerializer` — not a bare mapper — to serialize
 correctly (see the codegen reference's "Serializing generated objects" section).
 
-## The output-format prompt fragment (FR-010)
+## The response-format prompt fragment (FR-010)
 
-For every json/xml-format `template.output`, `codegen-spring`'s
-`SpringOutputPromptGenerator` emits a `<TemplateShortName>OutputPrompt` class with a
+For every responding `template.prompt`, `codegen-spring`'s
+`SpringOutputPromptGenerator` emits a `<PromptShortName>ResponseFormat` class with a
 static `renderFormat()` / `renderFormat(PromptOverrides)` pair, backed by
 `OutputFormatRenderer` from the `metaobjects-render` module — the "produce your
 answer like this" fragment for the model. Wire it alongside
@@ -77,11 +82,12 @@ answer like this" fragment for the model. Wire it alongside
 </generator>
 ```
 
-`@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 unresolved `@payloadRef` —
-the same skip contract as the parser generator. The `SPEC`'s root name is the
-capitalized payload class name, agreeing with the parser's extract-codegen root.
+`@promptStyle` on the `template.prompt` (`guide` default / `inline` / `exampleOnly`)
+controls the fragment's presentation; guidance is never emitted as comments. Skipped for
+`template.output` nodes and an unresolved `@responseRef` — the same skip contract as the
+parser generator. There is NO format gate: the old `@format ∈ {json,xml}` test read the
+syntax of the outbound body to decide whether to describe the reply. The `SPEC`'s root
+name is the response record's, agreeing with the parser's extract-codegen root.
 
 ## The three-step consumer pattern
 

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

@@ -1,16 +1,19 @@
 # Kotlin parser-on-receipt
 
-For every `template.output`, `codegen-kotlin`'s `KotlinOutputParserGenerator` emits
-a **typed parser** that validates an LLM/raw response against the template's
-`@payloadRef` payload data class. This is the receive side only — codegen emits
-**no** provider/LLM-call layer; you compose the call yourself. The payload data
-class itself comes from `KotlinPayloadGenerator` (a `@Serializable data class`), so
-the parser and the payload VO can't silently drift.
+For every RESPONDING `template.prompt` — one declaring `@responseRef` —
+`codegen-kotlin`'s `KotlinOutputParserGenerator` emits a **typed parser** that validates
+a model's reply against that shape. ADR-0052: the tier binds `@responseRef`, never
+`@payloadRef` (which types the request the prompt renders outbound), and a
+`template.output` gets no parser at all. This is the receive side only — codegen emits
+**no** provider/LLM-call layer; you compose the call yourself. The data class itself comes
+from `KotlinPayloadGenerator` (a `@Serializable data class`) — this port's classes are
+TEMPLATE-named, so a responding prompt gets a SECOND one, `<Name>Response`, beside
+`<Name>Payload`, and the parser and the record can't silently drift.
 
 ## Contents
 - Wire the generators
 - What it emits
-- The output-format prompt fragment (FR-010)
+- The response-format prompt fragment (FR-010)
 - The three-step consumer pattern
 - Consumer dependency
 - Recommended LLM caller (bring-your-own)
@@ -34,9 +37,10 @@ the payload it parses into) to the Maven plugin's `<generators>` list:
 
 ## What it emits
 
-Per `template.output`, `mvn metaobjects:generate` writes a `<Name>Parser.kt`
-`object` with a dual API matching kotlinx.serialization's exception model plus the
-Kotlin stdlib `Result<T>` convention:
+Per responding `template.prompt`, `mvn metaobjects:generate` writes a
+`<Name>Parser.kt` `object` with a dual API matching kotlinx.serialization's exception
+model plus the Kotlin stdlib `Result<T>` convention. The strict tier is JSON-only — an
+`@responseFormat: xml` reply gets the tolerant extract and neither strict function:
 
 ```kotlin
 // generated <Name>Parser.kt (shape)
@@ -44,8 +48,8 @@ object NpcResponseParser {
     private val json: Json = Json { ignoreUnknownKeys = false }
 
     /** Throws kotlinx.serialization.SerializationException on bad input. */
-    fun parseNpcResponse(text: String): NpcResponsePayload =
-        json.decodeFromString<NpcResponsePayload>(text)
+    fun parseNpcResponse(text: String): NpcResponseResponse =
+        json.decodeFromString<NpcResponseResponse>(text)
 
     /** Result-style — does not throw. */
     fun safeParseNpcResponse(text: String): Result<NpcResponsePayload> =
@@ -63,10 +67,10 @@ null) and a `extractLenient(loader, text)` overload that delegates to the runtim
 components. The lenient mirror type (`<Name>Extracted`) uses nullable fields per
 the Kotlin null-safety port — a missing/malformed component is `null`, not a throw.
 
-## The output-format prompt fragment (FR-010)
+## The response-format prompt fragment (FR-010)
 
-For every json/xml-format `template.output`, `codegen-kotlin`'s
-`KotlinOutputPromptGenerator` emits a `<TemplateShortName>OutputPrompt.kt` `object`
+For every responding `template.prompt`, `codegen-kotlin`'s
+`KotlinOutputPromptGenerator` emits a `<PromptShortName>ResponseFormat.kt` `object`
 with `renderFormat()` / `renderFormat(overrides: PromptOverrides)`, backed by
 `OutputFormatRenderer` from the `metaobjects-render` module — the "produce your
 answer like this" fragment for the model. Wire it alongside
@@ -79,11 +83,12 @@ answer like this" fragment for the model. Wire it alongside
 </generator>
 ```
 
-`@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 unresolved `@payloadRef` —
-the same skip contract as the parser generator. The `SPEC`'s root name is the
-capitalized payload class name, agreeing with the parser's extract-codegen root.
+`@promptStyle` on the `template.prompt` (`guide` default / `inline` / `exampleOnly`)
+controls the fragment's presentation; guidance is never emitted as comments. Skipped for
+`template.output` nodes and an unresolved `@responseRef` — the same skip contract as the
+parser generator. There is NO format gate: the old `@format ∈ {json,xml}` test read the
+syntax of the outbound body to decide whether to describe the reply. The `SPEC`'s root
+name is the response class's, agreeing with the parser's extract-codegen root.
 
 ## The three-step consumer pattern