@metaobjectsdev/metadata 0.24.0-rc.1 → 0.24.0

package/src/retired-vocabulary.ts

@@ -0,0 +1,280 @@
+// server/typescript/packages/metadata/src/retired-vocabulary.ts
+//
+// Vocabulary this project USED to register, and what to do instead.
+//
+// WHY THIS EXISTS (#337). Under ADR-0023 the registry is strict and sealed, so retired
+// vocabulary fails the load — correctly. But the message it failed with said the attribute
+// was "not declared by any registered provider", which tells an author their metadata is
+// malformed when the truth is that the vocabulary was retired ON PURPOSE, in a named
+// release, with a written migration. An adopter read that error, concluded the tool had a
+// registration bug, filed it as one, and argued against a decision whose reasoning they had
+// never seen — because nothing in the error pointed at it. The migration guide answered
+// their objection precisely. They never found it.
+//
+// THIS CHANGES NO LOAD OUTCOME. Retired vocabulary still fails, with the same error code,
+// at the same site. Only the message gains a sentence. That is deliberate: making any of
+// these load again would undo an adjudicated breaking change, and a "helpful" shim is how a
+// retirement quietly stops being one.
+//
+// SCOPE IS BY TYPE, NEVER BY BARE NAME. `@unique` is retired on `identity.secondary` and
+// perfectly live on a field; a name-only match would brand a valid declaration as retired,
+// which is worse than the generic message it replaces. Every entry names the type it
+// applies to, and `*` means "every subtype of this type" — never "every type".
+//
+// A GENUINE TYPO MUST STAY GENERIC. This map is consulted only after the normal check has
+// already decided to fail, and it returns undefined for anything it does not recognise, so
+// `@maxLenght` still reports as an unknown attribute. The map speaks only where it KNOWS.
+//
+// CROSS-PORT: this is a DIAGNOSTIC, not registered vocabulary — it affects no registry
+// manifest and no load outcome, so it carries no registry-conformance obligation. The other
+// four ports fail identically today, just with the generic message; mirroring this map is a
+// per-port ergonomics follow-up, not a conformance gap.
+
+/** What a reader needs at the moment their load fails. */
+export interface RetirementNote {
+  /** The release that retired it. */
+  readonly since: string;
+  /** One line: what it was, and why it went. */
+  readonly why: string;
+  /** The vocabulary that replaced it, when something did. */
+  readonly replacedBy?: string;
+  /** Repo-relative migration guide. */
+  readonly migration?: string;
+}
+
+/**
+ * The mechanical fix, when one exists.
+ *
+ * ABSENT MEANS JUDGMENT — `@status: abandoned` can be resolved by deleting the node, by
+ * retyping it, or by fixing the residue it describes, and only a human knows which. A tool
+ * that guessed would emit metadata that LOADS and means something different, which is worse
+ * than refusing: the adopter would believe the migration finished.
+ */
+export type VocabularyRewrite =
+  /** The attribute name changed; the value is untouched. */
+  | { readonly kind: "renameAttr"; readonly to: string }
+  /** The attribute went away with no replacement — drop it. */
+  | { readonly kind: "dropAttr" }
+  /**
+   * Both the name and the value changed (`@readOnly: true` → `@mutability: "readOnly"`).
+   *
+   * `otherwise` is REQUIRED, and that is the point. The attribute is retired for EVERY
+   * value it could hold, so an entry that names only the value it can rewrite has said
+   * nothing about the rest — and the rewriter's only honest options are to drop them or to
+   * refuse them. Leaving it implicit is how `@readOnly: false` came to be silently skipped:
+   * the entry's prose said "treated as a drop", the code fell through to `continue`, and
+   * `meta upgrade` exited 0 on a file that still would not load.
+   */
+  | {
+      readonly kind: "renameAttrValue";
+      readonly toAttr: string;
+      readonly fromValue: unknown;
+      readonly toValue: unknown;
+      /** What happens to every value other than `fromValue`. */
+      readonly otherwise: "drop" | "refuse";
+    };
+
+/** One retirement. `subType: "*"` means every subtype of `type`. */
+export interface RetiredEntry extends RetirementNote {
+  readonly type: string;
+  /** `*` for every subtype of `type`, else the exact subtype. */
+  readonly subType: string;
+  /** Retired ATTRIBUTE name (no `@`), when the attribute itself went. */
+  readonly attr?: string;
+  /** Retired VALUES of a surviving attribute, when only some members went. */
+  readonly attrValues?: readonly string[];
+  /** Set when the SUBTYPE itself was retired (`attr`/`attrValues` absent). */
+  readonly isSubTypeRetirement?: boolean;
+  /** How `meta upgrade` fixes it. Absent ⇒ the human decides; the tool refuses and
+   *  prints `migration`. */
+  readonly rewrite?: VocabularyRewrite;
+}
+
+const REQUIREMENT_MIGRATION = "docs/features/migrations/verified-by-retirement.md";
+
+export const RETIRED_VOCABULARY: readonly RetiredEntry[] = [
+  // ── 0.24.0: `@violation` is renamed `@counterexample` ──
+  //
+  // Pure rename — no semantics change. The field always held a static falsifiability test
+  // ("what would contradict this"), authored once, never a state. `@violation` READ as a
+  // status, and did so to the person who approved the vocabulary, who asked whether it
+  // meant "we know this requirement is currently violated". A name that misleads its own
+  // owner has earned replacing.
+  //
+  // Fully mechanical, which is the point: adopters migrate with `meta upgrade --apply`
+  // rather than a hand sweep. This entry is the first real user of that tool.
+  {
+    type: "requirement", subType: "*", attr: "violation",
+    since: "0.24.0",
+    why: "it named a static falsifiability test but read as a status — 'this requirement " +
+         "is in violation' — which is not what the field has ever held",
+    replacedBy: "@counterexample",
+    migration: "docs/features/migrations/violation-to-counterexample.md",
+    rewrite: { kind: "renameAttr", to: "counterexample" },
+  },
+
+  // ── FR-038: the requirement vocabulary becomes prescriptive-only (0.24.0) ──
+  {
+    type: "requirement", subType: "*", attr: "verifiedBy",
+    since: "0.24.0",
+    why: "it asked you to name a test, and verify could only check that the NAME occurred " +
+         "somewhere in your test sources — never that the named test verified the claim",
+    migration: REQUIREMENT_MIGRATION,
+    // Nothing replaced it, so the fix is removal. Safe to automate: the attribute drove no
+    // behaviour anyone else can observe.
+    rewrite: { kind: "dropAttr" },
+  },
+  {
+    type: "requirement", subType: "*", attr: "supersededBy",
+    since: "0.24.0",
+    why: "a requirement is prescriptive — it states what should be true and is never a " +
+         "journal of what happened",
+    migration: REQUIREMENT_MIGRATION,
+    rewrite: { kind: "dropAttr" },
+  },
+  {
+    type: "requirement", subType: "*", attr: "status",
+    attrValues: ["abandoned", "superseded"],
+    since: "0.24.0",
+    why: "retiring a capability is DELETING its requirement; version control holds that it " +
+         "existed, and `notes` on a surviving entry holds what a reader still needs",
+    migration: REQUIREMENT_MIGRATION,
+  },
+
+  // ── FR-037 R1: @readOnly becomes the @mutability enum (0.24.0) ──
+  {
+    type: "field", subType: "*", attr: "readOnly",
+    since: "0.24.0",
+    why: "a boolean could not express write-once, so the axis became an enum",
+    replacedBy: "@mutability",
+    migration: "docs/features/migrations/readonly-to-mutability.md",
+    // Key AND value: `@readOnly: true` becomes `@mutability: "readOnly"`. `@readOnly: false`
+    // was the default and simply goes away — hence `otherwise: "drop"` rather than inventing
+    // a mutability the author never stated. Both arms must be stated: the attribute is
+    // deregistered for every value, so an unhandled arm is a file that still fails to load
+    // after a run that reported success.
+    rewrite: {
+      kind: "renameAttrValue",
+      toAttr: "mutability",
+      fromValue: true,
+      toValue: "readOnly",
+      otherwise: "drop",
+    },
+  },
+
+  // ── FR-037 R2: origin.collection retires to reserved-not-registered (0.24.0) ──
+  {
+    type: "origin", subType: "collection", isSubTypeRetirement: true,
+    since: "0.24.0",
+    why: "it duplicated `origin.aggregate @agg: collect` on a strictly smaller attribute " +
+         "set, and nothing dispatched on it",
+    replacedBy: "origin.aggregate @agg: collect",
+    migration: "docs/features/migrations/origin-collection-retirement.md",
+  },
+
+  // ── ADR-0040: uniqueness lives in the TYPE, not an attribute (0.15.1) ──
+  {
+    type: "identity", subType: "secondary", attr: "unique",
+    since: "0.15.1",
+    why: "`identity.secondary` is now always a unique alternate key — uniqueness is encoded " +
+         "in the type, so the attribute had nothing left to say",
+    replacedBy: "index.lookup (for a NON-unique retrieval index)",
+    migration: "docs/features/migrations/identity-secondary-to-index-lookup.md",
+  },
+
+  // ── Metamodel 1.0: @dbColumnType slim-and-derive (0.15.0) ──
+  {
+    type: "field", subType: "*", attr: "dbColumnType",
+    attrValues: ["uuid_array", "text_array"],
+    since: "0.15.0",
+    why: "array-ness is DERIVED from `isArray`, so an array-flavoured physical type restated " +
+         "something the model already knew",
+    replacedBy: "isArray: true on the field",
+    // On a VALUE-scoped entry, `dropAttr` means "drop it when the value is one of the
+    // retired ones" — never unconditionally. `@dbColumnType: jsonb` is live vocabulary on
+    // the same attribute, and removing it would silently change the column type.
+    //
+    // Safe because the attribute said nothing the model did not already know: the field
+    // carrying `uuid_array` necessarily has `isArray: true`, which is where array-ness now
+    // comes from. There is no guide for this one, so without the rewrite an adopter would
+    // be told it is retired and given nowhere to go — which is what the dead-end test that
+    // caught this exists to prevent.
+    rewrite: { kind: "dropAttr" },
+  },
+];
+
+/**
+ * True when `entry` governs `typeKey` (`"<type>.<subType>"`).
+ *
+ * Exported because the rewriter scopes every occurrence with the SAME rule. It used to
+ * carry its own copy, and a scoping rule that lives in two files is one that will be fixed
+ * in one of them.
+ */
+export function scopeMatches(entry: RetiredEntry, typeKey: string): boolean {
+  const dot = typeKey.indexOf(".");
+  if (dot < 0) return false;
+  if (entry.type !== typeKey.slice(0, dot)) return false;
+  return entry.subType === "*" || entry.subType === typeKey.slice(dot + 1);
+}
+
+/** The reader-facing half of an entry, without the matching machinery. */
+export function note(entry: RetiredEntry): RetirementNote {
+  return {
+    since: entry.since,
+    why: entry.why,
+    ...(entry.replacedBy !== undefined ? { replacedBy: entry.replacedBy } : {}),
+    ...(entry.migration !== undefined ? { migration: entry.migration } : {}),
+  };
+}
+
+/** First entry satisfying `match`, as a note. The three lookups below differ only in it. */
+function noted(match: (e: RetiredEntry) => boolean): RetirementNote | undefined {
+  const hit = RETIRED_VOCABULARY.find(match);
+  return hit === undefined ? undefined : note(hit);
+}
+
+/**
+ * The attribute NAME itself was retired for this type. Returns undefined for an attr whose
+ * name is unknown here — a typo must keep reporting as a typo.
+ *
+ * An entry carrying `attrValues` is a VALUE retirement on a surviving attribute, so it is
+ * deliberately not matched here: `@status` is still perfectly good vocabulary.
+ */
+export function retiredAttr(typeKey: string, attrName: string): RetirementNote | undefined {
+  return noted(
+    (e) => e.attr === attrName && e.attrValues === undefined && scopeMatches(e, typeKey),
+  );
+}
+
+/** A specific VALUE of a surviving attribute was retired. */
+export function retiredAttrValue(
+  typeKey: string,
+  attrName: string,
+  value: unknown,
+): RetirementNote | undefined {
+  if (typeof value !== "string") return undefined;
+  return noted(
+    (e) => e.attr === attrName && e.attrValues?.includes(value) === true && scopeMatches(e, typeKey),
+  );
+}
+
+/** The SUBTYPE itself was retired (`origin.collection`). */
+export function retiredSubType(type: string, subType: string): RetirementNote | undefined {
+  return noted((e) => e.isSubTypeRetirement === true && e.type === type && e.subType === subType);
+}
+
+/**
+ * The sentence appended to a failing diagnostic. Kept here rather than at each call site so
+ * all three failure sites word a retirement identically — an adopter who has seen one
+ * recognises the next.
+ */
+export function retirementHint(n: RetirementNote): string {
+  // Sentences are built WITHOUT their terminator and punctuated once at the end. The
+  // previous form appended a period to each fragment and then repaired the doubling with a
+  // global `".." → "."` — which would silently rewrite an ellipsis, or a `../` in a
+  // migration path, inside the user-facing load error.
+  const parts = [`retired in ${n.since} — ${n.why}`];
+  if (n.replacedBy !== undefined) parts.push(`Use ${n.replacedBy} instead`);
+  if (n.migration !== undefined) parts.push(`Migration: ${n.migration}`);
+  return `${parts.join(". ")}.`;
+}

package/src/super-resolve.ts

@@ -21,6 +21,8 @@
 
 import type { MetaData } from "./shared/meta-data.js";
 import { PACKAGE_SEPARATOR, CHILD_REF_SEPARATOR } from "./shared/structural.js";
+import { TYPE_IDENTITY } from "./shared/base-types.js";
+import { IDENTITY_UNIQUE_KEY_SUBTYPES } from "./core/identity/identity-constants.js";
 
 // ---------------------------------------------------------------------------
 // Tree search helper
@@ -87,6 +89,51 @@ export function isChildTargetingRef(ref: string): boolean {
   return lastSegment.includes(CHILD_REF_SEPARATOR);
 }
 
+/**
+ * Whether a dotted `extends` target is acceptable for the extending node.
+ *
+ * Type must match exactly. Subtype must match too — with ONE exception, on identities
+ * (#310). For an identity, subtype equality was answering the wrong question: it read as
+ * "the same kind of thing", but ADR-0040 encodes uniqueness in the TYPE, so `primary` and
+ * `secondary` are both UNIQUE KEYS and differ only in which one the entity nominated as
+ * its main handle. Borrowing a key borrows uniqueness, not that nomination — so a read
+ * model may key off a business key the entity models as `identity.secondary` while never
+ * surfacing its surrogate `identity.primary` at all.
+ *
+ * The gate was never written for identities in the first place: its only conformance
+ * fixture is `error-extends-entity-field-type-mismatch`, a `field.uuid` extending a
+ * `field.string`. For a FIELD, subtype IS the datatype and inheriting across it is
+ * incoherent; for an identity, subtype is a ROLE. A field-shape rule was generalized onto
+ * a role axis without a fixture ever exercising it.
+ *
+ * `identity.reference` is excluded on both sides: a foreign key is not unique, so it can
+ * never back a borrowed key — and a set-membership test says that once, rather than
+ * enumerating the legal pairs.
+ *
+ * EXPORTED because there are two doors: this module's deferred resolution and
+ * `parser-core`'s eager check. They had independent copies of the boolean, so a change to
+ * one silently left the other enforcing the old rule on whichever path a given loader
+ * configuration takes.
+ */
+export function extendsTargetCompatible(node: MetaData, target: MetaData): boolean {
+  if (target.type !== node.type) return false;
+  if (target.subType === node.subType) return true;
+  return (
+    node.type === TYPE_IDENTITY &&
+    IDENTITY_UNIQUE_KEY_SUBTYPES.includes(node.subType) &&
+    IDENTITY_UNIQUE_KEY_SUBTYPES.includes(target.subType)
+  );
+}
+
+/**
+ * The one wording for `ERR_EXTENDS_TARGET_MISMATCH`, shared by both doors and mirrored in
+ * the other three ports. States the exception, so an author who hits it on a `field` is
+ * not left wondering why their identity case was allowed.
+ */
+export const EXTENDS_TARGET_MISMATCH_RULE =
+  "a dotted extends must target a node of the same type and subtype — the one exception " +
+  "is an identity, which may extend any UNIQUE key (identity.primary or identity.secondary)";
+
 /**
  * FR-024: split a child-targeting ref into the owner-object ref and the child
  * traversal path. A multi-dot ref (`X.y.z`) traverses child names to any depth
@@ -276,9 +323,20 @@ export function resolveDeferredSupers(root: MetaData): DeferredSuperFailure[] {
     if (target !== undefined) {
       // FR-024: a dotted ref must target a node of the SAME type and subtype
       // as the extending node. Dotted-only — top-level extends is unchanged.
+      //
+      // #310 — with ONE exception, on identities. Subtype equality here was standing in
+      // for "the target is the same kind of thing", and for identities that is the wrong
+      // question: ADR-0040 put uniqueness in the TYPE, so `identity.primary` and
+      // `identity.secondary` are both UNIQUE KEYS and differ only in which one the entity
+      // nominated as its main handle. A projection borrowing a key is borrowing
+      // uniqueness, not that nomination — so a read model may key off a business key the
+      // entity models as `identity.secondary` while never surfacing its surrogate
+      // `identity.primary` at all, which is the shape that was foreclosed.
+      //
+      // `identity.reference` stays out: an FK is not unique, so it can never back a key.
       if (
         isChildTargetingRef(node.superRef) &&
-        (target.type !== node.type || target.subType !== node.subType)
+        !extendsTargetCompatible(node, target)
       ) {
         failures.push({
           nodeFqn: node.fqn(),

package/src/template/prompt-definition.embedded.ts

@@ -19,7 +19,7 @@ export const PROMPT_DEFINITION: ProviderDefinition = {
           "name": "xmlText",
           "min": 0,
           "max": 1,
-          "description": "When true, this field receives its element's XML TEXT CONTENT during tolerant extract (JAXB @XmlValue / Jackson @JacksonXmlText / .NET [XmlText]) instead of a same-named child. No effect for @format: json."
+          "description": "When true, this field receives its element's XML TEXT CONTENT during tolerant extract (JAXB @XmlValue / Jackson @JacksonXmlText / .NET [XmlText]) instead of a same-named child. No effect when the eliciting prompt's @responseFormat is json."
         },
         {
           "type": "attr",

package/src/template/template-constants.ts

@@ -66,6 +66,10 @@ export const TEMPLATE_ATTR_HTML_BODY_REF = "htmlBodyRef";
 export const TEMPLATE_ATTR_TEXT_BODY_REF = "textBodyRef";
 
 // Prompt-overlay attrs (template.prompt only).
+//
+// ADR-0052: @responseRef is also the INBOUND gate. Its presence — never a format
+// value — is what makes a prompt emit a parser-on-receipt, a tolerant extract, and
+// the FR-010 response-format fragment. A template.output emits none of those.
 export const TEMPLATE_ATTR_RESPONSE_REF = "responseRef";
 export const TEMPLATE_ATTR_MAX_TOKENS = "maxTokens";
 export const TEMPLATE_ATTR_REQUIRED_SLOTS = "requiredSlots";
@@ -94,7 +98,8 @@ export const TEMPLATE_FORMATS = [
 ] as const;
 export type TemplateFormat = (typeof TEMPLATE_FORMATS)[number];
 
-// FR-010 artifact-1 prompt presentation style (template.output only). Closed enum;
+// FR-010 response-format fragment presentation (template.prompt only — ADR-0052 moved
+// it off template.output, where its own name contradicted the subtype). Closed enum;
 // guidance is NEVER carried in comments. Default "guide". Set project-wide via an
 // abstract template base + extends, with a render-time override on top.
 export const TEMPLATE_ATTR_PROMPT_STYLE = "promptStyle";
@@ -110,6 +115,27 @@ export const PROMPT_STYLES = [
 ] as const;
 export type PromptStyle = (typeof PROMPT_STYLES)[number];
 
+// ADR-0053 — the syntax of the model's REPLY (template.prompt only). Distinct from
+// @format, which is the syntax of the rendered PROMPT body: the two genuinely differ
+// (a plain-text prompt may elicit an XML reply), which is why one attribute cannot
+// serve both directions.
+//
+// Two members, not TEMPLATE_FORMATS' seven, because two is what every shipping
+// consumer dispatches on (Format.JSON / Format.XML) in all five ports. The rest are
+// reserved-not-registered under ADR-0007 Amendment 2's re-entry bar: a member enters
+// the registry only when a shipping consumer dispatches on it.
+//
+// Default "json" reproduces the trace helper's pre-ADR-0053 fallback exactly (anything
+// not "xml" was treated as JSON), so the default is behaviour-preserving rather than a
+// new policy.
+export const TEMPLATE_ATTR_RESPONSE_FORMAT = "responseFormat";
+export const RESPONSE_FORMAT_JSON = "json";
+export const RESPONSE_FORMAT_XML = "xml";
+
+export const TEMPLATE_RESPONSE_FORMATS = [RESPONSE_FORMAT_JSON, RESPONSE_FORMAT_XML] as const;
+export type ResponseFormat = (typeof TEMPLATE_RESPONSE_FORMATS)[number];
+export const RESPONSE_FORMAT_DEFAULT: ResponseFormat = RESPONSE_FORMAT_JSON;
+
 // @xmlText — a FIELD-level marker (boolean) for the tolerant extract engine: this field
 // receives its element's TEXT CONTENT when a template.output response is parsed from XML
 // (JAXB @XmlValue / Jackson @JacksonXmlText / .NET [XmlText]). Registered on field.* by

package/src/template/template-definition.embedded.ts

@@ -18,9 +18,9 @@ export const TEMPLATE_DEFINITION: ProviderDefinition = {
     {
       "type": "template",
       "subType": "prompt",
-      "description": "An LLM-targeted renderable prompt template (FR-004). Carries the generic reference + governance attrs plus the LLM overlay (@maxTokens / @requiredSlots / @model / @responseRef). Its renderable body is required via @textRef.",
-      "whenToUse": "You are sending text to an LLM. Declare a prompt template with a typed payload so the prompt is versioned, drift-checked against its fields, and cache-stable — instead of string-building it in code.",
-      "rules": "prompt requires @payloadRef (the typed payload it renders against) AND @textRef (the body text, provider-resolved at render time — enforced in the loader's validateTemplatePayloadRefs pass, not at the attr layer where @textRef is relaxed to optional so template.output email can omit it). @format is a closed enum keyed by the render engine's escaper. @responseRef (optional) names the response value-object the prompt expects and drives typed LLM-call trace derivation.",
+      "description": "An LLM-targeted renderable prompt template (FR-004). Carries the generic reference + governance attrs plus the LLM overlay (@maxTokens / @requiredSlots / @model / @responseRef). Its renderable body is required via @textRef. A prompt declaring @responseRef also owns the INBOUND half (ADR-0052): the parser-on-receipt, the FR-010 response-format fragment (@promptStyle), and the reply syntax (@responseFormat).",
+      "whenToUse": "You are sending text to an LLM. Declare a prompt template with a typed payload so the prompt is versioned, drift-checked against its fields, and cache-stable — instead of string-building it in code. Add @responseRef when you also want the reply parsed into a typed shape.",
+      "rules": "prompt requires @payloadRef (the typed payload it renders against) AND @textRef (the body text, provider-resolved at render time — enforced in the loader's validateTemplatePayloadRefs pass, not at the attr layer where @textRef is relaxed to optional so template.output email can omit it). @format is the syntax of the rendered PROMPT body, a closed enum keyed by the render engine's escaper; @responseFormat (ADR-0053) is the syntax of the model's REPLY. @responseRef (optional) names the response value-object the prompt expects, drives typed LLM-call trace derivation, and is the sole gate on the inbound codegen tier — which keys on its presence, never on a format value.",
       "children": [
         {
           "type": "attr",
@@ -120,16 +120,43 @@ export const TEMPLATE_DEFINITION: ProviderDefinition = {
           "name": "responseRef",
           "min": 0,
           "max": 1,
-          "description": "Optional ref to the response value-object this prompt expects (peer of @payloadRef; drives typed LLM-call trace derivation)."
+          "description": "Optional ref to the response value-object this prompt expects (peer of @payloadRef; drives typed LLM-call trace derivation). Its presence is the sole gate on the inbound codegen tier (ADR-0052): parser-on-receipt, tolerant extract, and the FR-010 response-format fragment."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "promptStyle",
+          "min": 0,
+          "max": 1,
+          "default": "guide",
+          "allowedValues": [
+            "guide",
+            "inline",
+            "exampleOnly"
+          ],
+          "description": "FR-010 response-format fragment presentation: 'guide' (prose list + example), 'inline' (inline placeholders / enum choices), or 'exampleOnly' (filled skeleton). Guidance is never emitted as comments."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "responseFormat",
+          "min": 0,
+          "max": 1,
+          "default": "json",
+          "allowedValues": [
+            "json",
+            "xml"
+          ],
+          "description": "ADR-0053: the syntax of the model's REPLY, read by the parser-on-receipt and the FR-010 response-format fragment. Distinct from @format, which is the syntax of the rendered PROMPT body. Two members because two is what every shipping consumer dispatches on; the other @format members are reserved-not-registered."
         }
       ]
     },
     {
       "type": "template",
       "subType": "output",
-      "description": "An output / serialization template (FR-004): every rendered artifact other than an LLM prompt — a document (email, export, docs, config) or an email. Carries the generic reference + governance attrs, the FR-010 @promptStyle, and the @kind + email part-refs.",
-      "whenToUse": "You render a document/email/serialized output from typed data. Declare an output template so the {{fields}} are drift-checked against the payload VO at build time.",
-      "rules": "output is either a document (@kind=\"document\" or absent → renders @textRef in @format to one string) or an email (@kind=\"email\" → renders subject + html + optional text to a structured EmailDocument). The cross-field presence rule is enforced in the loader's validateTemplatePayloadRefs pass: document requires @textRef; email requires @subjectRef AND @htmlBodyRef (with @textBodyRef optional) and carries NO @textRef. @format is a closed enum keyed by the render engine's escaper; @promptStyle (FR-010) selects the output-format prompt presentation and is never emitted as comments.",
+      "description": "An output / serialization template (FR-004): every rendered artifact other than an LLM prompt — a document (email, export, docs, config) or an email. Carries the generic reference + governance attrs and the @kind + email part-refs. OUTBOUND ONLY (ADR-0052) — it renders, and generates no parser.",
+      "whenToUse": "You render a document/email/serialized output from typed data. Declare an output template so the {{fields}} are drift-checked against the payload VO at build time. To parse a model's reply instead, declare @responseRef on the template.prompt that elicits it — never a template.output.",
+      "rules": "output is either a document (@kind=\"document\" or absent → renders @textRef in @format to one string) or an email (@kind=\"email\" → renders subject + html + optional text to a structured EmailDocument). The cross-field presence rule is enforced in the loader's validateTemplatePayloadRefs pass: document requires @textRef; email requires @subjectRef AND @htmlBodyRef (with @textBodyRef optional) and carries NO @textRef. @format is a closed enum keyed by the render engine's escaper. template.output is OUTBOUND ONLY (ADR-0052): it emits a render helper and nothing that reads a model's reply — the parser-on-receipt, the tolerant extract and the FR-010 response-format fragment all belong to template.prompt @responseRef.",
       "children": [
         {
           "type": "attr",
@@ -198,20 +225,6 @@ export const TEMPLATE_DEFINITION: ProviderDefinition = {
           "max": 1,
           "description": "Output tags the rendered text must contain (drives the verify output-tag check)."
         },
-        {
-          "type": "attr",
-          "subType": "string",
-          "name": "promptStyle",
-          "min": 0,
-          "max": 1,
-          "default": "guide",
-          "allowedValues": [
-            "guide",
-            "inline",
-            "exampleOnly"
-          ],
-          "description": "FR-010 output-format prompt presentation: 'guide' (prose list + example), 'inline' (inline placeholders / enum choices), or 'exampleOnly' (filled skeleton). Guidance is never emitted as comments."
-        },
         {
           "type": "attr",
           "subType": "string",