GH-84: Collect an unknown key under the spelling the payload used

[magicsunday]

Overview

Closes #84. UnknownPropertyCollector promises to preserve unmapped payload keys, but stored the converted name: with the camelCase converter active an unknown favourite_colour was preserved as favouriteColour. The value was kept raw, the key was not — so the collected map was not the copy of the unmapped payload the feature exists to provide, and a consumer re-serialising it emitted a key the sender never sent.

Change

The two questions are separated:

• Whether a key is unknown is still decided on the converted name — full_name that camelises onto a declared fullName is mapped, not collected.
• The key it is stored under is now the original payload spelling. Both rewrite sources are bypassed: the name converter and a ReplaceProperty alias, whose target is by definition not a declared property here either.

Second behavioural change the review surfaced

Collected keys can no longer collide. Previously favourite_colour and favouriteColour merged into one entry (last one wins) and a value was lost; they are now two entries. The "two source keys that normalize to the same name collide" note applied to the collector too and was wrong for it — it is now scoped to declared properties in the attribute docblock, AGENTS.md and the recipe.

Why this was never caught

Every payload in the collector's test file used camelCase keys, so conversion was a no-op in all of them — while the suite runs with the converter enabled. Three tests now pin it, each red against the previous behaviour:

• a snake_case unknown key survives verbatim;
• a snake_case key that converts onto a declared property is still mapped, while a second snake_case key beside it is collected;
• two spellings normalising to the same unknown name are kept as two entries.

Filed, not folded in

A pre-existing gap the review surfaced is tracked as #136: a payload key PHP canonicalises to an integer ("42") is dropped entirely — neither collected nor reported, even in strict mode. The documentation carries an explicit caveat for it rather than claiming a round trip the code does not deliver.

Compatibility

Behavioural change for a consumer that relied on the converted key, or on two colliding spellings merging. Attribute docblock, AGENTS.md and docs/recipes/using-attributes.md updated.

Verification

composer ci:test green (508 tests, 1486 assertions), exit 0. Reviewed by the correctness, test-quality and Codex reviewers; all their findings (the collision prose, the stale merge comment and baseline docblock, the non-discriminating control test, the undocumented ReplaceProperty bypass) are folded in.

🤖 Generated with Claude Code

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[magicsunday]

/gemini review

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.