[chr-hertel]

Fixes #586
Closes #587

json_decode(assoc: true) makes {} and [] the same value, so tool arguments got validated against the wrong JSON type - and the schema can't restore what's already lost. tools/call arguments now keep their JSON types, the rest of the message stays arrays since its typed parsers lose nothing that way.

• The parameter type decides what a handler gets: array still gets arrays at every level, \stdClass, object, mixed and untyped ones get \stdClass. So not \stdClass everywhere like Preserve native JSON types when passing arguments to tool handlers #587 asks for, but you can opt in per parameter.
• arguments must be a JSON object per spec, so null and [] are refused with -32600 - PHP clients encoding an empty array will notice, our own Client doesn't send that.
• array<string, T> generates object instead of array, which only worked around the lost {}. An empty default is advertised as {}.
• OriginatingRequestBinder sorts \stdClass as well, otherwise a retry with reordered nested members fails verification.

A PHP object can't hold a member name starting with NUL. Such a message falls back to arrays and parses like before, except tools/call, which can't keep its argument types then and is refused with -32600 - that's why this drops the NUL datasets and the raw handler from #665.

BC breaks are in the CHANGELOG.

[Copilot]

🟡 Changes recommended

Active issues cause malformed JSON to return the wrong protocol error and schema overrides to leave advertised defaults that fail validation.

2 open issues

• Normalize defaults after applying schema type overrides · New
• Preserve parse errors when object decoding encounters a leading-NUL key · New

What changed in this PR

Preserves JSON object and array distinctions in tool arguments, addressing validation failures from #586 and supporting type-preserving handler inputs from #587.

Changes:

• Preserve JSON types through parsing and validation, with conversion based on handler parameter types.
• Update map schemas, empty defaults, and request-state binding.
• Add regression coverage and document breaking changes.

File	Description
tests/​Unit/​Server/​Transport/​StdioDualEraTest.php	Test JSON types and invalid arguments across both protocol eras.
tests/​Unit/​Server/​Stateless/​StatelessProtocolTest.php	Use object-shaped empty arguments.
tests/​Unit/​Server/​Stateless/​StandardHeaderValidatorTest.php	Update empty argument fixtures.
tests/​Unit/​Server/​Stateless/​OriginatingRequestBinderTest.php	Test object ordering and type-sensitive binding.
tests/​Unit/​Server/​RequestContextTest.php	Use object-shaped request arguments.
tests/​Unit/​Server/​Handler/​Request/​CallToolHandlerTest.php	Encode argument fixtures as objects.
tests/​Unit/​Server/​BuilderTest.php	Update empty tool arguments.
tests/​Unit/​Schema/​Request/​CallToolRequestTest.php	Cover argument parsing, rejection, and serialization.
tests/​Unit/​JsonRpc/​MessageFactoryTest.php	Cover type preservation and batch detection.
tests/​Unit/​Client/​Stateless/​HeaderFactoryTest.php	Update empty argument fixture.
tests/​Unit/​Capability/​Registry/​ReferenceHandlerTest.php	Test parameter-driven object conversion.
tests/​Unit/​Capability/​Discovery/​SchemaGeneratorTest.php	Cover map schemas, defaults, and nested lists.
tests/​Integration/​StatelessLifecycleTest.php	Send object-shaped empty arguments.
tests/​Integration/​RequestStateBindingTest.php	Remove leading-NUL argument datasets.
tests/​Integration/​Fixture/​request_state.php	Remove the custom handler for NUL-member tests.
src/​Server/​Stateless/​StatelessProtocol.php	Parse the original request body without re-encoding.
src/​Server/​Stateless/​OriginatingRequestBinder.php	Canonicalize objects while preserving type distinctions.
src/​Server/​Handler/​Request/​CallToolHandler.php	Validate root arguments as an object.
src/​Schema/​Request/​CallToolRequest.php	Preserve nested types and require object arguments.
src/​Schema/​JsonRpc/​Request.php	Add overridable parameter conversion.
src/​Schema/​JsonRpc/​Notification.php	Convert decoded objects to arrays.
src/​JsonRpc/​MessageFactory.php	Decode objects distinctly and reject NUL-prefixed members.
src/​JsonRpc/​Json.php	Add recursive object-to-array conversion.
src/​Capability/​Registry/​ReferenceHandler.php	Convert arguments according to parameter types.
src/​Capability/​Discovery/​SchemaGenerator.php	Infer map types and normalize empty object defaults.
docs/​servers/​schemas.md	Explain argument representations and map annotations.
CHANGELOG.md	Record compatibility changes.

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The iterable conversion rejects valid Traversable arguments such as ArrayIterator before handler invocation, so existing Traversable values must be preserved.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Preserve Traversable arguments for iterable parameters

src/​Capability/​Registry/​ReferenceHandler.php:250

Routing iterable through castToArray() also rejects valid Traversable arguments supplied programmatically: an ArrayIterator accepted by the PHP handler now throws Cannot cast value to array before invocation. Keep existing Traversable values unchanged for iterable parameters, while recursively converting JSON objects and arrays.

2 resolved since last review

• Preserve parse errors when object decoding encounters a leading-NUL key
• Normalize defaults after applying schema type overrides

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Rejecting NUL-prefixed member names and changing request-state canonicalization introduce intentional breaking changes to protocol interoperability and multi-instance compatibility that warrant human review.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues are reported for the changes preserving JSON object and array distinctions in tool arguments.

No open issues 🎉

_{Review effort: Balanced}