@@ -0,0 +1,78 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec)!: an agent's `structuredOutput` is JSON-only — the `regex` / `grammar` / `xml` formats and the `coerce_types` step are retired, and the block is `live`, enforced by the cloud AI runtime (#21277)
+
+**BREAKING** — four members leave the agent's structured-output vocabulary:
+`regex`, `grammar` and `xml` from `StructuredOutputFormat` (so from
+`agent.structuredOutput.format` and `agent.structuredOutput.fallbackFormat`), and
+`coerce_types` from `TransformPipelineStep` (so from
+`agent.structuredOutput.transformPipeline`). ADR-0049 enforce-or-remove, ruled
+retire. The cloud AI runtime, the one runtime that executes agents, enforces
+`structuredOutput` on every final answer and refused an agent declaring any of the
+four before its first turn: the spec never had a key to carry the pattern or
+grammar a `regex` / `grammar` answer would be checked against, an answer is checked
+only as JSON, and no coercion engine exists. So no authored value of the four ever
+did what it named, and authoring now refuses them by name instead of the first
+live turn refusing the agent. `json_object`, `json_schema`, `trim`, `parse_json`
+and `validate` are unchanged.
+
+### FROM → TO
+
+| removed | what to write instead |
+| --- | --- |
+| `structuredOutput.format: 'regex'`, `'grammar'` or `'xml'` | `format: 'json_schema'` with a JSON Schema in `schema` when the answer must have a shape, or `format: 'json_object'`; or delete the `structuredOutput` block if the agent needs no output contract. |
+| `structuredOutput.fallbackFormat: 'regex'`, `'grammar'` or `'xml'` | `'json_object'` or `'json_schema'`, or delete the key. |
+| `'coerce_types'` in `structuredOutput.transformPipeline` | delete the step, and declare the exact types in `schema` so the answer is validated as the model wrote it. |
+
+**The one-line fix: use `json_schema` with a JSON Schema; drop `coerce_types`.**
+`os migrate meta --from 17` lists the mechanical edits for existing sources.
+
+Each retired member is refused at parse with a prescription naming the JSON
+formats, and in `tsc` (the members are gone from the `StructuredOutputFormat` /
+`TransformPipelineStep` types). Any other unknown value keeps zod's own message.
+
+### The retirement kit
+
+- **Value-level retirement.** Both enums are declared through
+  `enumWithRetiredValues` (`shared/retired-key.ts`), the house mechanism for a
+  narrowed vocabulary, with the prescriptions module-private. No authorable KEY and
+  no def changed, so nothing lands in `RETIRED_KEYS_BY_MAJOR` and the four surface
+  ratchets (`api-surface`, `authorable-surface`, `json-schema.manifest`,
+  `api-surface-signatures`) are byte-identical.
+- **D2 conversion `agent-structured-output-refused-members-removed`** (step 18,
+  retired from the load path): it deletes a `structuredOutput` block whose `format`
+  was retired (the format is required, and no rewrite can say which JSON contract
+  was meant), deletes a retired `fallbackFormat`, and drops `coerce_types` from the
+  pipeline, keeping the other steps in order. Stored `sys_metadata` agent rows replay
+  it at rehydration; one notice per edit.
+- **D3 entry `agent-structured-output-refused-members-retired`** carries the
+  judgement the conversion cannot make: whether an agent whose block was deleted
+  should now carry a `json_schema` contract.
+- **No deprecation window**, per the project's startup-stage posture.
+
+### Describes and the liveness ledger
+
+- `agent.structuredOutput` drops `[EXPERIMENTAL — not enforced]`: it states that the
+  cloud AI runtime enforces it on every final answer and that the open framework
+  edition does not run agents. Its ledger row moves `experimental` → `live`, citing
+  the cloud readers (`agent-runtime.ts#compileStructuredOutput`,
+  `ai-service.ts#AIService.settleFinalAnswer`) as attested by the cloud seat's
+  reading at cloud `cb62c3ea`, `verifiedAt` 2026-10-02. `os lint` / `os validate` no
+  longer warn `liveness-experimental-property` on an agent that sets it.
+- `fallbackFormat`'s describe states what the runtime does with it: once the primary
+  format's retries are spent, the last answer is checked against the fallback.
+- `guardrails.blockedTopics`'s describe states the enforced match: an exact,
+  case-sensitive match on the tool name, on `action_` plus the action type, or on
+  the tool category.
+- The generated agent reference page follows.
+
+⚠️ **The out-of-repo consumer population is NOT MEASURED.** `@objectstack/spec` is
+published, and tenant-authored agents were not measured. This repo authors no
+`structuredOutput` outside `packages/spec`, and the cloud seat's reading found no
+producer in cloud.
+
+Clause-②: no (narrowing)
+
+<!-- adr-0087: registered agent-structured-output-refused-members-removed, agent-structured-output-refused-members-retired -->
@@ -60,7 +60,7 @@ const result = AIModelConfigSchema.parse(data);
 | **planning** | `{ maxIterations: integer }` | optional | Autonomous reasoning and planning configuration |
 | **memory** | `{ longTerm?: object; reflectionInterval?: integer }` | optional | [EXPERIMENTAL — not enforced] Agent memory management. Parsed but no runtime consumer yet. |
 | **guardrails** | `{ maxTokensPerInvocation?: integer; maxExecutionTimeSec?: integer; blockedTopics?: string[] }` | optional | Safety guardrails for the agent (token budget, time limit, blocked topics), enforced per user turn by the cloud AI runtime; the open framework edition does not run agents. |
-| **structuredOutput** | `{ format: Enum<'json_object' \| 'json_schema' \| 'regex' \| 'grammar' \| 'xml'>; schema?: Record<string, any>; strict: boolean; retryOnValidationFailure: boolean; … }` | optional | [EXPERIMENTAL — not enforced] Structured output format and validation configuration. Parsed but no runtime consumer yet. |
+| **structuredOutput** | `{ format: Enum<'json_object' \| 'json_schema'>; schema?: Record<string, any>; strict: boolean; retryOnValidationFailure: boolean; … }` | optional | Structured output contract for the agent's final answer (JSON format, schema, retries, fallback format, transform steps), enforced on every final answer by the cloud AI runtime; the open framework edition does not run agents. |
 | **protection** | `{ lock: Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>; reason: string; docsUrl?: string }` | optional | Package author protection block — lock policy for this agent. |
 | **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). |
 | **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. |
@@ -110,19 +110,19 @@ const result = AIModelConfigSchema.parse(data);
 | :--- | :--- | :--- | :--- |
 | **maxTokensPerInvocation** | `integer` | optional | Token budget per single invocation |
 | **maxExecutionTimeSec** | `integer` | optional | Max execution time in seconds |
-| **blockedTopics** | `string[]` | optional | Forbidden topics or action names |
+| **blockedTopics** | `string[]` | optional | Forbidden topics or action names: each entry is an exact, case-sensitive match on the tool name, on `action_` plus the action type, or on the tool category |
 
 ### Nested Shape: `Agent.structuredOutput`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **format** | `Enum<'json_object' \| 'json_schema' \| 'regex' \| 'grammar' \| 'xml'>` | ✅ | Expected output format |
+| **format** | `Enum<'json_object' \| 'json_schema'>` | ✅ | Expected output format |
 | **schema** | `Record<string, any>` | optional | JSON Schema definition for output. An untyped subschema that carries a type-scoped keyword (properties, items, pattern, minimum, …) is refused at its path, because the AI runtime's schema reader does not check it; declare its "type". |
 | **strict** | `boolean` | optional (default: `false`) | Enforce exact schema compliance |
 | **retryOnValidationFailure** | `boolean` | optional (default: `true`) | Retry generation when output fails validation |
 | **maxRetries** | `integer` | optional (default: `3`) | Maximum retries on validation failure |
-| **fallbackFormat** | `Enum<'json_object' \| 'json_schema' \| 'regex' \| 'grammar' \| 'xml'>` | optional | Fallback format if primary format fails |
-| **transformPipeline** | `Enum<'trim' \| 'parse_json' \| 'validate' \| 'coerce_types'>[]` | optional | Post-processing steps applied to output |
+| **fallbackFormat** | `Enum<'json_object' \| 'json_schema'>` | optional | Fallback format: once the primary format's retries are spent, the last answer is checked against this format instead |
+| **transformPipeline** | `Enum<'trim' \| 'parse_json' \| 'validate'>[]` | optional | Post-processing steps applied to output |
 
 ### Nested Shape: `Agent.protection`
 
@@ -143,28 +143,25 @@ Structured output configuration for agent responses
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **format** | `Enum<'json_object' \| 'json_schema' \| 'regex' \| 'grammar' \| 'xml'>` | ✅ | Expected output format |
+| **format** | `Enum<'json_object' \| 'json_schema'>` | ✅ | Expected output format |
 | **schema** | `Record<string, any>` | optional | JSON Schema definition for output. An untyped subschema that carries a type-scoped keyword (properties, items, pattern, minimum, …) is refused at its path, because the AI runtime's schema reader does not check it; declare its "type". |
 | **strict** | `boolean` | optional (default: `false`) | Enforce exact schema compliance |
 | **retryOnValidationFailure** | `boolean` | optional (default: `true`) | Retry generation when output fails validation |
 | **maxRetries** | `integer` | optional (default: `3`) | Maximum retries on validation failure |
-| **fallbackFormat** | `Enum<'json_object' \| 'json_schema' \| 'regex' \| 'grammar' \| 'xml'>` | optional | Fallback format if primary format fails |
-| **transformPipeline** | `Enum<'trim' \| 'parse_json' \| 'validate' \| 'coerce_types'>[]` | optional | Post-processing steps applied to output |
+| **fallbackFormat** | `Enum<'json_object' \| 'json_schema'>` | optional | Fallback format: once the primary format's retries are spent, the last answer is checked against this format instead |
+| **transformPipeline** | `Enum<'trim' \| 'parse_json' \| 'validate'>[]` | optional | Post-processing steps applied to output |
 
 
 ---
 
 ## StructuredOutputFormat
 
-Output format for structured agent responses
+Output format for structured agent responses (JSON only)
 
 ### Allowed Values
 
 * `json_object`
 * `json_schema`
-* `regex`
-* `grammar`
-* `xml`
 
 
 ---
@@ -178,7 +175,6 @@ Post-processing step for structured output
 * `trim`
 * `parse_json`
 * `validate`
-* `coerce_types`
 
 
 ---
 
@@ -103,9 +103,11 @@
       "note": "Flipped from experimental on the cloud seat's reading, not on a reading taken from this repo — no seat in the flipping session could read cloud. The reading: the repo:cloud seat repo:cloud#1 (session_01Wxo1xhh2bU66T73q23jzE4), comment 5940785002 on objectstack-ai/objectstack#20274, of cloud main @235c5b29 (the merge of objectstack-ai/cloud#2559), read 2026-10-01; verifiedAt is that reading's date, and every evidence and producer pointer above is quoted from it. The blanket verdict covers all three children: maxTokensPerInvocation, maxExecutionTimeSec and blockedTopics. These keys are live because the cloud runtime consumes them; the OPEN framework edition does not run agents (this file's _note). ⛔ Re-attest by re-reading cloud, never by re-stamping the date."
     },
     "structuredOutput": {
-      "status": "experimental",
-      "evidence": "no runtime reader",
-      "note": "aspirational."
+      "status": "live",
+      "verifiedAt": "2026-10-02",
+      "evidenceScope": "cross-repo",
+      "evidence": "cloud @cb62c3ea: packages/service-ai/src/agent-runtime.ts#compileStructuredOutput — the reader: it compiles the agent's structuredOutput into the turn's output contract, reached through AgentRuntime.resolveTurnGuardrails; cloud @cb62c3ea: packages/service-ai/src/ai-service.ts#AIService.settleFinalAnswer — the enforcement, on every final answer in chatWithToolsImpl and streamChatWithTools, the forced final call included: format json_object / json_schema parsed and then checked against schema, strict, retryOnValidationFailure and maxRetries (each re-ask a guarded model round whose tokens are metered), fallbackFormat checked against the last answer once the primary's retries are spent, and transformPipeline trim / parse_json / validate. The refusal before the first round, TurnGovernor.unsupportedOutput, answered the members this spec has since retired (regex / grammar / xml and coerce_types) with AI_AGENT_STRUCTURED_OUTPUT_UNSUPPORTED.",
+      "note": "Flipped from experimental on the cloud seat's reading, not on a reading taken from this repo — no seat in the flipping session could read cloud. The reading: the repo:cloud seat repo:cloud#1 (session_01Wxo1xhh2bU66T73q23jzE4), comment 5943158888 on objectstack-ai/objectstack#20274, of cloud main @cb62c3ea (the merge of objectstack-ai/cloud#2570), read 2026-10-02; verifiedAt is that reading's date, and every evidence pointer above is quoted from it. The blanket verdict covers every child: format, schema, strict, retryOnValidationFailure, maxRetries, fallbackFormat and transformPipeline. The same change retired the four members that reading found refused rather than enforced — the regex, grammar and xml formats and the coerce_types step (ruling record 5945617233, letter A): each is refused at parse with a prescription (enumWithRetiredValues in packages/spec/src/ai/agent.zod.ts), and the ADR-0087 conversion agent-structured-output-refused-members-removed repairs stored and existing sources — so every value an author can still write is one the runtime enforces. Producer: none in cloud at that ref; tenant-authored agents are NOT MEASURED. These keys are live because the cloud runtime consumes them; the OPEN framework edition does not run agents (this file's _note). ⛔ Re-attest by re-reading cloud, never by re-stamping the date."
     },
     "knowledge": {
       "status": "dead",
 
@@ -12,4 +12,4 @@ committed anywhere: `check:liveness` sums the shards when it reads them.
 
 | Type | live | exp | elsewhere | dead | planned | classified |
 |---|---|---|---|---|---|---|
-| `agent` | 21 | 3 | 0 | 2 | 0 | 26 |
+| `agent` | 22 | 2 | 0 | 2 | 0 | 26 |