@metaobjectsdev/sdk 0.23.1 → 0.24.0

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
 

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

@@ -1,11 +1,13 @@
 # Python parser-on-receipt
 
-For every `template.output`, the `output-parser` generator (run via `metaobjects gen`)
-emits a **typed parser** that validates an LLM/raw response against the template's
-`@payloadRef` payload Pydantic model. This is the receive side only — codegen emits
-**no** provider/LLM-call layer; you compose the call yourself. The payload class comes
-from the sibling `payload` generator, so the parser and the payload VO can't silently
-drift.
+For every RESPONDING `template.prompt` — one declaring `@responseRef` — the
+`output-parser` generator (run via `metaobjects gen`) emits a **typed parser** that
+validates a model's reply against that shape's Pydantic model. 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 record
+class comes from the sibling `payload` generator, so the parser and the record can't
+silently drift.
 
 ## Contents
 - Wire the generators
@@ -18,7 +20,7 @@ drift.
 
 ## Wire the generators
 
-Select `output-parser` (the `payload` generator that emits the `<Name>Payload` it
+Select `output-parser` (the `payload` generator that emits the `<Name>Response` it
 parses into runs alongside it):
 
 ```bash
@@ -30,17 +32,17 @@ metaobjects gen ./metadata --out ./generated --generators payload,output-parser
 
 ## What it emits
 
-Per `template.output`, `metaobjects gen` writes one `<template_name>_output_parser.py`
-with a single throw-only entry point. Python uses one API (not TS's
+Per responding `template.prompt`, `metaobjects gen` writes one
+`<template_name>_response_parser.py` with a single throw-only entry point. Python uses one API (not TS's
 `parse`/`safeParse`) because raising `pydantic.ValidationError` is the idiomatic
 failure — the pydantic / Instructor / FastAPI norm; a Result-style wrapper would be
 un-Pythonic.
 
 ```python
-# generated <template_name>_output_parser.py (shape)
-from .npc_response_payload import NpcResponsePayload   # the @payloadRef VO (Pydantic v2 BaseModel)
+# generated <template_name>_response_parser.py (shape)
+from .npc_response_response import NpcResponseResponse   # the @responseRef record (Pydantic v2 BaseModel)
 
-def parse_npc_response(text: str) -> NpcResponsePayload:
+def parse_npc_response(text: str) -> NpcResponseResponse:
     """Validates text against the payload model.
 
     Raises:
@@ -49,16 +51,20 @@ def parse_npc_response(text: str) -> NpcResponsePayload:
     ...
 ```
 
-For `@format: json|xml` outputs the generator additionally emits a **tolerant**
-best-effort variant — `extract_lenient_<name>(text) -> ExtractionResult[<Name>PayloadExtracted]`
+Every responding prompt ALSO gets a **tolerant** best-effort variant —
+`extract_lenient_<name>_with_loader(root, text) -> ExtractionResult[<Name>ResponseExtracted]`
 (from the `metaobjects` render `extract` engine) for cases where you want a classified
-per-field report rather than a raise. The lenient mirror (`<Name>PayloadExtracted`)
-uses `Optional[...]` fields — a missing/malformed component is `None`, not a raise.
+per-field report rather than a raise. The lenient mirror (`<Name>ResponseExtracted`) uses
+`Optional[...]` fields — a missing/malformed component is `None`, not a raise.
 
-## The output-format prompt fragment (FR-010)
+The STRICT `parse_*` is JSON-only (ADR-0053): an `@responseFormat: xml` reply gets the
+tolerant path and no `parse_*` at all, because strict all-or-nothing semantics layered
+over a REPAIRING XML reader would raise or accept based on how much repair happened.
 
-For every json/xml-format `template.output`, the `output-prompt` generator (run via
-`metaobjects gen`) emits one `<template_name>_output_prompt.py` module exposing
+## The response-format prompt fragment (FR-010)
+
+For every responding `template.prompt`, the `output-prompt` generator (run via
+`metaobjects gen`) emits one `<template_name>_response_format.py` module exposing
 `render_<name>_format(overrides=None) -> str`, backed by the render engine's
 `render_output_format()` — the "produce your answer like this" fragment for the
 model:
@@ -67,11 +73,13 @@ model:
 metaobjects gen ./metadata --out ./generated --generators payload,output-prompt
 ```
 
-`@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 `output-parser` generator. The baked spec's root name
-is the payload class name, agreeing with the parser's `extract_<name>()` 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
+`output-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, so a
+text-bodied prompt asking for a JSON answer got no fragment. The baked spec's root name
+is the response class name, agreeing with the parser's `extract_<name>()` root.
 
 ## The three-step consumer pattern
 
@@ -80,7 +88,7 @@ here) → parse the response with the generated parser:
 
 ```python
 from pydantic import ValidationError
-from .npc_response_output_parser import parse_npc_response
+from .npc_response_response_parser import parse_npc_response
 
 text = my_llm_client.complete(prompt_text)   # YOUR code — no generated provider
 try:
@@ -119,7 +127,41 @@ one boundary, not both.
 > generator emits a `record_<entity>(recorder, input, redact=None)` helper (per
 > concrete entity extending `LlmCallBase` with a `@responseRef`/`@payloadRef`-carrying
 > `template.prompt`) that tolerantly extracts the typed response, builds the base
-> trace row, and persists it once. What's still TS-only is the **`call<Entity>`
+> trace row, and persists it once.
+>
+> `LlmCallBase` is shipped metadata, not something you author: opt in when you load,
+> then inherit from it. Without the opt-in the `extends` fails with
+> `ERR_UNRESOLVED_SUPER`.
+>
+> ```python
+> load_directory("metadata/", libraries=["ai"])   # metaobjects::ai::LlmCallBase
+> ```
+> For `metaobjects gen` / `verify`, declare it in `metaobjects.config.yaml` instead —
+> the CLI reads the same opt-in from there:
+> ```yaml
+> metadata: metadata/
+> libraries: ["ai"]
+> ```
+> ```yaml
+> - object.entity:
+>     name: AssistantCall
+>     extends: metaobjects::ai::LlmCallBase
+>     children:
+>       - source.rdb:       { table: assistant_call, role: primary }
+>       - identity.primary: { name: id, fields: ["spanId"] }
+>       # Typed columns are AUTHORED, never derived (ADR-0024 amendment).
+>       # Declare BOTH: the generated record_<entity> writes voRequest and
+>       # voResponse unconditionally, and any key the entity does not declare
+>       # raises "no field '<name>' in metadata" on the first persist.
+>       - field.object: { name: voRequest,  objectRef: MyRequestVO,  storage: jsonb }
+>       - field.object: { name: voResponse, objectRef: MyResponseVO, storage: jsonb }
+> ```
+>
+> Note the opt-in also brings in the library's own concrete `LlmCall` entity
+> (table `llm_call`) alongside the abstract base — it will appear in codegen output
+> and in a schema diff unless you filter it.
+>
+> What's still TS-only is the **`call<Entity>`
 > render→call→record convenience loop** — Python intentionally does not emit it,
 > because the `LlmClient` seam it wraps is BYO / vendor-neutral here (ADR-0024). So
 > you compose render → your LLM call → the generated `record_<entity>(...)` yourself;