alkhttp/tasks/adapters/review-002-yaml-normalization.md

id, name, status, depends_on, scope, risk, impact, level, tags

id	name	status	depends_on	scope	risk	impact	level	tags
review-002-yaml-normalization	YAML input normalization — duplicates, .inf, merge keys, non-string keys (OAI-12)	completed		narrow	medium	component	implementation	adapters review-002 from-openapi openapi-spec

Description

Review 002 OAI-12 [major]. OpenAPISpec::from_yaml (openapi_spec.rs:153-158) is a single yaml_serde::from_str::<Value> with zero post-parse normalization; three verified corruptions flow through unimpeded (empirically confirmed against yaml_serde 0.10.7):

1. Duplicate keys silently last-win on the Value path (visit_map → values.insert) while the JSON path errors on the same document — the two input formats disagree, YAML's failure mode is silent.
2. .inf/.nan numbers become Value::Null through Number::from_f64(∞) → None — a declared constraint (maximum: .inf is unusual, but any float inf) silently vanishes from the advertised schema.
3. Merge keys (<<: *anchor) are not applied (yaml_serde's apply_merge() is opt-in and unused) — << survives as a literal property name in the resolved/advertised schema.

Non-string keys (200: response codes as numbers etc.) were checked — plain statuses survive via string round-trips — but numeric inference into any string-matched field is a live hazard (e.g. style: 1).

Acceptance Criteria

• A post-parse normalization pass on the YAML path (before from_value): reject duplicate keys (loud, naming the path or at least the document context), reject .inf/.nan-derived nulls-from-floats (either reject or reject-with-context), and decide merge keys: either invoke apply_merge() (matching YAML 1.1 user expectations; ADR-051 declares YAML 1.2 via yaml_serde — verify which the crate claims) or reject << keys loudly
• Non-string keys: reject or coerce-with-loudness (decide; JSON path parity is the goal — the same document should mean the same thing through both entry points or the difference must be loud)
• Tests at the from_yaml seam (not the parser): duplicate keys → error; .inf → loud error (not silent null); merge key applied or rejected; quoted-always spec ("200":) unchanged
• A doc note on the YAML/JSON parity contract (ADR-051 section or the module doc)
• cargo test, cargo clippy --all-targets -- -D warnings, cargo fmt --check pass

References

• docs/reviews/002-post-remediation-review.md (Part E', OAI-12; Test-gap 9)
• src/adapters/openapi_spec.rs:153-158 (the seam), from_openapi.rs (the consumers)
• docs/architecture/decisions/051-yaml-input-for-from-openapi.md
• tasks/adapters/review-001-openapi-import-integrity.md (the import-integrity context)

Notes

Keep the walk cheap (one pass, no allocation beyond error messages). The alias-bomb/depth bounds are dependency-provided and verified working (review 002 re-verified) — do not re-implement them; the task is about semantic normalization, not resource limits. ADR-051 is the decision record to update if the merge-key stance changes behavior.

Summary

Post-parse YAML normalization at the from_yaml seam: loud duplicate-key rejection (yaml_serde native), merge keys applied (shallow), .inf/.nan + non-representable keys rejected with pointers, scalar keys stringified per YAML 1.2 core schema. Premise correction recorded: serde_json Value itself last-wins on dups - parity contract is YAML-stricter-by-design. ADR-051 section added.