@@ -0,0 +1,34 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec)!: `action.ai.outputSchema` and `agent.structuredOutput.schema` refuse an untyped subschema that carries a type-scoped keyword, at its path, as the AI runtime does (#21289)
+
+Clause-②: yes (narrowing)
+
+<!-- adr-0087: registered ai-json-schema-untyped-subschema-refused -->
+
+**BREAKING** — an accept-set narrowing on two published authoring slots, shipped as `minor` under the repo's launch-window convention for accept-set narrowings. Every schema it refuses was already refused by the AI runtime before the action or agent ran, so nothing that worked stops working; what moves is where the refusal is reported — at authoring, at the subschema's path, instead of at the first invocation.
+
+**`@objectstack/spec`**
+
+- **`action.ai.outputSchema`** (stack actions and object-nested actions) and **`agent.structuredOutput.schema`** were open records. The cloud AI runtime compiles both through one guard whose schema reader does not check a type-scoped keyword on a subschema with no `type`, and refuses the whole schema. Both slots are now declared by one factory that mirrors that guard exactly:
+  - **refused:** an object node whose `type` is absent and which carries any of the 22 type-scoped keywords (`properties`, `required`, `additionalProperties`, `patternProperties`, `propertyNames`, `minProperties`, `maxProperties`, `items`, `prefixItems`, `contains`, `minItems`, `maxItems`, `uniqueItems`, `minLength`, `maxLength`, `pattern`, `format`, `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf`), with any value;
+  - **where:** the schema root, every value of `properties`, `patternProperties`, `$defs`, `definitions` and `dependentSchemas`, and the subschema (or each array entry) of `items`, `additionalProperties`, `contains`, `propertyNames`, `not`, `if`, `then`, `else`, `unevaluatedProperties`, `unevaluatedItems`, `anyOf`, `oneOf`, `allOf` and `prefixItems` — under typed parents too; `$ref` is not followed;
+  - **accepted:** boolean subschemas, `{}`, a node with any `type` value, and an untyped node carrying only keywords outside the list (`enum`, `const`, `$ref`, `anyOf`, `title`, `description`, `default`, …);
+  - each offending subschema is its own issue, located at the slot path plus the subschema path (`ai.outputSchema.properties.customer`), and the message names the keyword and the `type` to declare.
+- The TypeScript types of both slots are unchanged (`Record<string, unknown>`). The published JSON Schema does not state the rule: it is a refinement, which the JSON Schema projection does not carry, so a JSON Schema validator still accepts such a schema in either slot. The affected published schemas name the slot in their `x-dropped-refinements` list.
+
+## FROM → TO
+
+| you wrote | write instead |
+|:--|:--|
+| `outputSchema: { properties: { id: { type: 'string' } }, required: ['id'] }` | `outputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] }` |
+| `schema: { type: 'object', properties: { tags: { items: { type: 'string' } } } }` | `schema: { type: 'object', properties: { tags: { type: 'array', items: { type: 'string' } } } }` |
+| `{ properties: { code: { pattern: '^[A-Z]+$' } } }` anywhere in either slot | `{ type: 'object', properties: { code: { type: 'string', pattern: '^[A-Z]+$' } } }` |
+
+The one-line fix: declare its `type` on every subschema that carries a type-scoped keyword — `"object"`, `"array"`, `"string"`, or `"number"` / `"integer"`, as the refusal names.
+
+## Who is affected, measured
+
+On `origin/main` `135daaa06b`: the package fixtures author either slot three times (one action `ai.outputSchema`, two `structuredOutput.schema`), every subschema typed; the examples, the documentation and the published skills author neither slot. No fixture needed a change. Deployed metadata was not measured. A stored action or agent carrying such a schema still loads; its next save is refused until the `type` is declared.
@@ -117,7 +117,7 @@ const result = AIModelConfigSchema.parse(data);
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **format** | `Enum<'json_object' \| 'json_schema' \| 'regex' \| 'grammar' \| 'xml'>` | ✅ | Expected output format |
-| **schema** | `Record<string, any>` | optional | JSON Schema definition for output |
+| **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 |
@@ -144,7 +144,7 @@ Structured output configuration for agent responses
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **format** | `Enum<'json_object' \| 'json_schema' \| 'regex' \| 'grammar' \| 'xml'>` | ✅ | Expected output format |
-| **schema** | `Record<string, any>` | optional | JSON Schema definition for output |
+| **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 |
 
@@ -140,7 +140,7 @@ L2 sandboxed JS body — runs inside an isolated VM with declared capabilities
 | **description** | `string` | optional | LLM-facing description (≥40 chars). Required when exposed. |
 | **category** | `Enum<'data' \| 'action' \| 'flow' \| 'integration' \| 'vector_search' \| 'analytics' \| 'utility'>` | optional | Tool category override (defaults to "action"). |
 | **paramHints** | `Record<string, { description?: string; enum?: (string \| number)[]; examples?: any[] }>` | optional | Per-parameter AI hints keyed by param name. |
-| **outputSchema** | `Record<string, any>` | optional | JSON Schema for the action return value. |
+| **outputSchema** | `Record<string, any>` | optional | JSON Schema for the action return value. 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". |
 | **requiresConfirmation** | `boolean` | optional | Override HITL confirmation for AI invocations. |
 
 ### Nested Shape: `Action.onSuccess`
@@ -163,7 +163,7 @@ L2 sandboxed JS body — runs inside an isolated VM with declared capabilities
 | **description** | `string` | optional | LLM-facing description (≥40 chars). Required when exposed. |
 | **category** | `Enum<'data' \| 'action' \| 'flow' \| 'integration' \| 'vector_search' \| 'analytics' \| 'utility'>` | optional | Tool category override (defaults to "action"). |
 | **paramHints** | `Record<string, { description?: string; enum?: (string \| number)[]; examples?: any[] }>` | optional | Per-parameter AI hints keyed by param name. |
-| **outputSchema** | `Record<string, any>` | optional | JSON Schema for the action return value. |
+| **outputSchema** | `Record<string, any>` | optional | JSON Schema for the action return value. 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". |
 | **requiresConfirmation** | `boolean` | optional | Override HITL confirmation for AI invocations. |
 
 
 
@@ -2,12 +2,17 @@
   "description": "Shrink-only ledger of every PUBLISHED JSON Schema that is STILL WIDER than the Zod type it was generated from, because a rule written as `.refine()` reaches the runtime and not the file (#18670). `z.toJSONSchema()` has no arm for a `custom` check: a plain record, the same record with a `.refine()`, and the same record with an ABORTING `.refine()` all project byte-identically (measured on zod 4.4.3, the version packages/spec resolves). So a document one of these files ACCEPTS can still be refused at parse time, and an author -- or an AI -- validating against packages/spec/json-schema/** finds out a release later. Each `sites` path is a position under that schema at which a refinement is dropped; the same paths are written onto the artifact itself as `x-dropped-refinements`. Item 2 closed the first patterns: a refinement DECLARED through the closed list in src/shared/refinement-projection.ts is emitted into the published file, reads `projected` rather than `dropped`, and its row LEAVES this ledger in the same PR -- which is why the ledger shrinks and never grows on a repair. Every refinement outside that closed list stays here, and adding an arm to the list is a public-contract decision, not a refactor. Hand-edited on purpose and with no `gen:` script: a generator would let a new gap be admitted by running a command instead of by a decision, which is the silence this ledger exists to end. Adding, removing or moving a site fails packages/spec/scripts/build-schemas.ts until the line moves with it, and the failure prints the corrected entry in full. ⛔ Do not delete or weaken a refinement to shorten this file -- the runtime rule is correct; it is the projection that is silent, and the remedy is to teach the closed list a NAMED pattern, never to drop the rule.",
   "measured": {
     "zod": "4.4.3",
-    "publishedSchemasWithDroppedRefinements": 212,
-    "droppedRefinementSites": 616,
+    "publishedSchemasWithDroppedRefinements": 215,
+    "droppedRefinementSites": 635,
     "refinementSitesThatDidProject": 369,
     "refinementSitesWithNoJsonFormToCompare": 0
   },
   "entries": {
+    "ai/Agent": {
+      "sites": [
+        "structuredOutput.schema"
+      ]
+    },
     "ai/BlueprintField": {
       "sites": [
         "summaryOperations.filter.lazy"
@@ -38,6 +43,11 @@
         "objects.element.fields.element.summaryOperations.filter.lazy"
       ]
     },
+    "ai/StructuredOutputConfig": {
+      "sites": [
+        "schema"
+      ]
+    },
     "api/AnalyticsQueryRequest": {
       "sites": [
         "where.lazy"
@@ -51,7 +61,9 @@
     "api/AssembledInstalledPackage": {
       "sites": [
         "manifest.actions.element.in",
+        "manifest.actions.element.in.ai.outputSchema",
         "manifest.actions.element.in.params.element.in",
+        "manifest.agents.element.structuredOutput.schema",
         "manifest.connectors.element.out",
         "manifest.dashboards.element.globalFilters.element",
         "manifest.dashboards.element.widgets.element",
@@ -154,7 +166,9 @@
       "sites": [
         "data.options[0].manifest.navigationContributions.element.items.element.lazy.options[0]",
         "data.options[1].manifest.actions.element.in",
+        "data.options[1].manifest.actions.element.in.ai.outputSchema",
         "data.options[1].manifest.actions.element.in.params.element.in",
+        "data.options[1].manifest.agents.element.structuredOutput.schema",
         "data.options[1].manifest.connectors.element.out",
         "data.options[1].manifest.dashboards.element.globalFilters.element",
         "data.options[1].manifest.dashboards.element.widgets.element",
@@ -242,7 +256,9 @@
       "sites": [
         "options[0].manifest.navigationContributions.element.items.element.lazy.options[0]",
         "options[1].manifest.actions.element.in",
+        "options[1].manifest.actions.element.in.ai.outputSchema",
         "options[1].manifest.actions.element.in.params.element.in",
+        "options[1].manifest.agents.element.structuredOutput.schema",
         "options[1].manifest.connectors.element.out",
         "options[1].manifest.dashboards.element.globalFilters.element",
         "options[1].manifest.dashboards.element.widgets.element",
@@ -290,7 +306,9 @@
       "sites": [
         "data.packages.element.options[0].manifest.navigationContributions.element.items.element.lazy.options[0]",
         "data.packages.element.options[1].manifest.actions.element.in",
+        "data.packages.element.options[1].manifest.actions.element.in.ai.outputSchema",
         "data.packages.element.options[1].manifest.actions.element.in.params.element.in",
+        "data.packages.element.options[1].manifest.agents.element.structuredOutput.schema",
         "data.packages.element.options[1].manifest.connectors.element.out",
         "data.packages.element.options[1].manifest.dashboards.element.globalFilters.element",
         "data.packages.element.options[1].manifest.dashboards.element.widgets.element",
@@ -340,13 +358,15 @@
     "api/MetadataTypeInfoResponse": {
       "sites": [
         "data.actions.element.in",
+        "data.actions.element.in.ai.outputSchema",
         "data.actions.element.in.params.element.in"
       ]
     },
     "api/ObjectDefinitionResponse": {
       "sites": [
         "data",
         "data.actions.element.in",
+        "data.actions.element.in.ai.outputSchema",
         "data.actions.element.in.params.element.in",
         "data.fieldGroups",
         "data.fields.out.valueType",
@@ -740,6 +760,7 @@
       "sites": [
         "",
         "actions.element.in",
+        "actions.element.in.ai.outputSchema",
         "actions.element.in.params.element.in",
         "fieldGroups",
         "fields.out.valueType",
@@ -918,6 +939,7 @@
       "sites": [
         "",
         "actions.element.in",
+        "actions.element.in.ai.outputSchema",
         "actions.element.in.params.element.in"
       ]
     },
@@ -1016,6 +1038,7 @@
         "operations.element.options[0].field.relatedListFilter.lazy",
         "operations.element.options[3].object",
         "operations.element.options[3].object.actions.element.in",
+        "operations.element.options[3].object.actions.element.in.ai.outputSchema",
         "operations.element.options[3].object.actions.element.in.params.element.in",
         "operations.element.options[3].object.fieldGroups",
         "operations.element.options[3].object.fields.out.valueType",
@@ -1033,6 +1056,7 @@
       "sites": [
         "object",
         "object.actions.element.in",
+        "object.actions.element.in.ai.outputSchema",
         "object.actions.element.in.params.element.in",
         "object.fieldGroups",
         "object.fields.out.valueType",
@@ -1075,6 +1099,7 @@
         "options[0].field.relatedListFilter.lazy",
         "options[3].object",
         "options[3].object.actions.element.in",
+        "options[3].object.actions.element.in.ai.outputSchema",
         "options[3].object.actions.element.in.params.element.in",
         "options[3].object.fieldGroups",
         "options[3].object.fields.out.valueType",
@@ -1136,9 +1161,15 @@
     "ui/Action": {
       "sites": [
         "in",
+        "in.ai.outputSchema",
         "in.params.element.in"
       ]
     },
+    "ui/ActionAi": {
+      "sites": [
+        "outputSchema"
+      ]
+    },
     "ui/ActionParam": {
       "sites": [
         "in"
 
@@ -6,6 +6,7 @@ import { ProtectionSchema } from '../shared/protection.zod';
 import { MetadataProtectionFields } from '../kernel/metadata-protection.zod';
 import { StateMachineSchema } from '../automation/state-machine.zod';
 import { lazySchema } from '../shared/lazy-schema';
+import { aiJsonSchemaSlot } from '../shared/ai-json-schema-slot';
 import { strictObject } from '../shared/strict-object';
 
 /**
@@ -90,8 +91,19 @@ export const StructuredOutputConfigSchema = lazySchema(() => strictObject({
   /** Output format type */
   format: StructuredOutputFormatSchema.describe('Expected output format'),
 
-  /** JSON Schema definition for output validation */
-  schema: z.record(z.string(), z.unknown()).optional().describe('JSON Schema definition for output'),
+  /**
+   * JSON Schema definition for output validation. The cloud AI runtime
+   * compiles it, and its schema reader refuses an untyped subschema that
+   * carries a type-scoped keyword (`properties`, `items`, `pattern`,
+   * `minimum`, …). The slot refuses the same schemas here, at the subschema's
+   * path, through the one factory `action.ai.outputSchema` shares
+   * (`shared/ai-json-schema-slot.ts`).
+   */
+  schema: aiJsonSchemaSlot('structuredOutput.schema').optional().describe(
+    '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".',
+  ),
 
   /** Whether to enforce exact schema compliance */
   strict: z.boolean().default(false).describe('Enforce exact schema compliance'),