fix(core): stamp type:'object' on object-only union output roots; SUBSCHEMA_KEYWORDS JSDoc accuracy

isProvablyObjectShapedRoot: a typeless oneOf/anyOf/allOf root whose every
member is type:'object' is also stamped, so z.discriminatedUnion / z.union of
objects / z.intersection of objects keep their 2025-era outputSchema
advertisement (the previous unconditional stamp happened to work for these;
the fix-#2 narrow heuristic regressed them). A typeless union with any
non-object member is still returned as-is. 3 new output-arm unit tests.

SUBSCHEMA_KEYWORDS JSDoc: 'consumed only within this module's tests' →
'has no consumers' (the test file does not import it either).

Author: felixweinberger

docs/migration.md

@@ -1447,10 +1447,10 @@ being handed a schema their codec cannot parse. When such a tool's handler retur
 or primitive there is invalid 2025 wire data and a strictly-conformant 2025 client would reject the entire response (the fallback included). The text block is what reaches a legacy client; the structured value reaches a 2026 client. While you serve 2025-era clients, keep schemas
 in the 2025 subset (object roots) where you can.
 
-**Typeless-root output schemas are not stamped `type:"object"`.** A Standard-Schema value whose JSON Schema root has no `type` — for example `z.union([z.string(), z.number()])` (`{anyOf:[…]}`), `z.any()` (`{}`), or `z.object({…}).nullable()` — is advertised as-is on the 2026
-era and dropped from the 2025 projection (with the same warn-once). The SDK only defaults `type:"object"` when the root carries `properties`/`patternProperties`/`additionalProperties`/`required`, because stamping it on a typeless union would produce a self-contradictory schema
-(e.g., `{type:"object", anyOf:[{type:"string"}, …]}`) that rejects every value. This is the conservative-correct choice: it means a `z.discriminatedUnion(...)` `outputSchema` (typeless `{oneOf:[{type:"object",…}, …]}`) is also dropped on the 2025 projection even though every
-branch is an object — the previous behavior happened to work for that case by accident. If you need a discriminated-union `outputSchema` advertised on the 2025 era, give it an explicit root `type` via `fromJsonSchema({ type: "object", oneOf: […] })`.
+**Typeless-root output schemas are only stamped `type:"object"` when provably safe.** A Standard-Schema value whose JSON Schema root has no `type` — for example `z.union([z.string(), z.number()])` (`{anyOf:[…]}`), `z.any()` (`{}`), or `z.object({…}).nullable()` — is advertised
+as-is on the 2026 era and dropped from the 2025 projection (with the same warn-once), because stamping `type:"object"` there would produce a self-contradictory schema that rejects every value. The SDK still defaults `type:"object"` when the root carries object keywords
+(`properties`/`patternProperties`/`additionalProperties`/`required`) **or** is a `oneOf`/`anyOf`/`allOf` whose every member is `type:"object"` — so `z.discriminatedUnion(...)`, `z.union([z.object(...), …])`, and `z.intersection(...)` of objects keep their 2025-era advertisement
+unchanged.
 
 ## Unchanged APIs
 

packages/core/src/util/standardSchema.ts

@@ -205,19 +205,18 @@ export function standardSchemaToJsonSchema(schema: StandardJSONSchemaV1, io: 'in
         );
     }
     if (io === 'output') {
-        // SEP-2106: outputSchema may have any JSON Schema root type (array, string, …) — no
-        // non-object throw. An explicit `type` (object or not) is returned as-is. A typeless
-        // root is returned as-is when it is NOT provably object-shaped — e.g. a `z.union(...)`
-        // emits `{anyOf:[…]}`, and stamping `type:'object'` there would be self-contradictory.
-        // Only when the root is typeless AND object-shaped (carries `properties` /
-        // `patternProperties` / `additionalProperties` / `required`) do we default
-        // `type:'object'` so the 2025-era wire bytes are unchanged for the pre-SEP object
-        // schemas. The legacy projection drop gates anything that does not end up
-        // `type:'object'`.
+        // SEP-2106: outputSchema may have any JSON Schema root. An explicit `type` (object or
+        // not) is returned as-is. A typeless root only gets `type:'object'` defaulted when it is
+        // PROVABLY object-shaped — either it carries object keywords at the root, or every
+        // member of a root `oneOf`/`anyOf`/`allOf` is itself `type:'object'` (the
+        // `z.discriminatedUnion(...)`, `z.union([z.object(...), ...])`, `z.intersection(...)`
+        // cases). Those pre-SEP schemas were valid 2025 wire data via the unconditional stamp,
+        // so the stamp is kept where it is provably safe. A typeless root that is NOT provably
+        // object-shaped (e.g. `z.union([z.string(), z.number()])` → `{anyOf:[…]}`) is returned
+        // as-is — stamping there would be self-contradictory. The legacy projection drop gates
+        // anything that does not end up `type:'object'`.
         if (result.type !== undefined) return result;
-        const isObjectShaped =
-            'properties' in result || 'patternProperties' in result || 'additionalProperties' in result || 'required' in result;
-        return isObjectShaped ? { type: 'object', ...result } : result;
+        return isProvablyObjectShapedRoot(result) ? { type: 'object', ...result } : result;
     }
     if (result.type !== undefined && result.type !== 'object') {
         throw new Error(
@@ -228,6 +227,25 @@ export function standardSchemaToJsonSchema(schema: StandardJSONSchemaV1, io: 'in
     return { type: 'object', ...result };
 }
 
+/**
+ * A typeless JSON Schema root is "provably object-shaped" when either it carries object keywords
+ * directly (`properties`/`patternProperties`/`additionalProperties`/`required`), or it is a
+ * composition (`oneOf`/`anyOf`/`allOf`) whose every member is itself `type:'object'`. Used to
+ * decide whether stamping `type:'object'` is safe (redundant-but-valid) versus self-contradictory.
+ */
+function isProvablyObjectShapedRoot(schema: Record<string, unknown>): boolean {
+    if ('properties' in schema || 'patternProperties' in schema || 'additionalProperties' in schema || 'required' in schema) {
+        return true;
+    }
+    for (const key of ['oneOf', 'anyOf', 'allOf'] as const) {
+        const members = schema[key];
+        if (Array.isArray(members) && members.length > 0) {
+            return members.every(m => m !== null && typeof m === 'object' && (m as Record<string, unknown>).type === 'object');
+        }
+    }
+    return false;
+}
+
 // Validation
 
 export type StandardSchemaValidationResult<T> = { success: true; data: T } | { success: false; error: string };

packages/core/src/validators/schemaBounds.ts

@@ -29,10 +29,9 @@ export const DEFAULT_MAX_SCHEMA_DEPTH = 64;
 export const DEFAULT_MAX_SUBSCHEMA_COUNT = 10_000;
 
 /**
- * Vocabulary list of JSON Schema keywords whose values are themselves schemas. Currently consumed
- * only within this module's tests; intended as the single source for the SEP-2243 `x-mcp-header`
- * reachability scan in `mcpParamHeaders.ts` (which today carries its own private list —
- * consolidation is a follow-up).
+ * Vocabulary list of JSON Schema keywords whose values are themselves schemas. Currently has no
+ * consumers; intended as the single source for the SEP-2243 `x-mcp-header` reachability scan in
+ * `mcpParamHeaders.ts` (which today carries its own private list — consolidation is a follow-up).
  *
  * NOTE: {@link assertSchemaSafeToCompile} does **not** consult this list; its walk is intentionally
  * exhaustive (every key) so a future or vendor keyword cannot smuggle a `$ref` past the guard.

packages/core/test/util/standardSchema.test.ts

@@ -58,5 +58,30 @@ describe('standardSchemaToJsonSchema', () => {
             const result = standardSchemaToJsonSchema(z.object({ a: z.string() }), 'output');
             expect(result.type).toBe('object');
         });
+
+        test('discriminatedUnion (typeless oneOf of objects) is stamped type:object', () => {
+            // every branch is `type:'object'` so stamping is redundant-but-valid; preserves
+            // 2025-era wire bytes for a pre-SEP object schema.
+            const schema = z.discriminatedUnion('kind', [
+                z.object({ kind: z.literal('a'), x: z.number() }),
+                z.object({ kind: z.literal('b'), y: z.string() })
+            ]);
+            const result = standardSchemaToJsonSchema(schema, 'output');
+            expect(result.type).toBe('object');
+            expect(result.oneOf).toBeDefined();
+        });
+
+        test('union of objects (typeless anyOf of objects) is stamped type:object', () => {
+            const schema = z.union([z.object({ a: z.number() }), z.object({ b: z.string() })]);
+            const result = standardSchemaToJsonSchema(schema, 'output');
+            expect(result.type).toBe('object');
+        });
+
+        test('mixed union (object + primitive) is NOT stamped', () => {
+            const schema = z.union([z.object({ a: z.number() }), z.string()]);
+            const result = standardSchemaToJsonSchema(schema, 'output');
+            // not every branch is type:'object' — stamping would be self-contradictory.
+            expect(result.type).toBeUndefined();
+        });
     });
 });