Document and verify representation key uniqueness across stream surfaces

[MariusStorhaug]

Context

YAML 1.2.2 requires mapping keys to be unique in the representation graph. Equality is based on node kind, effective tag, and canonical content, not source spelling or the eventual PowerShell projection target.

Official YAML 1.2.2 references:

• https://yaml.org/spec/1.2.2/#3211-nodes
• https://yaml.org/spec/1.2.2/#3213-node-comparison
• https://yaml.org/spec/1.2.2/#33-loading-failure-points
• Normative module spec: spec/Representation-Key-Uniqueness.md

Current State

The module already rejects duplicate representation keys in many paths, and the conformance corpus documents known duplicate-key policy differences. This behavior should be captured as a deliberate public contract across all stream surfaces.

Objective

Make representation-key uniqueness a fully verified and documented behavior across conversion, import, validation, formatting, and merging.

PowerShell Design Considerations

• Duplicate-key failures should happen before projection into PowerShell objects, ordered dictionaries, hashtables, or typed objects.
• Rich object projection should never hide invalid YAML by letting a later property or dictionary value overwrite an earlier one.
• Complex keys should remain supported for -AsHashtable and representation-preserving commands without weakening uniqueness checks.
• Parameter sets should steer users toward lossless projections when complex keys are expected.

Tasks

• Verify scalar key equality by effective tag and canonical value.
• Verify structural equality for sequence and mapping keys.
• Ensure aliases and anchors do not make otherwise equal keys distinct.
• Ensure all public stream surfaces reject duplicate representation keys consistently.
• Document known YAML test-suite policy differences as intentional duplicate-key enforcement.

Benefits

• Avoids silent data loss from overwritten mapping entries.
• Keeps rich PowerShell projections honest about YAML representation validity.
• Gives users predictable behavior for complex-key documents.

Acceptance Criteria

• Duplicate scalar keys with different presentation but equal canonical values fail with YamlDuplicateKey.
• Structurally equal complex keys fail with YamlDuplicateKey.
• Structurally different complex keys remain valid where the selected projection can represent them.
• Test-Yaml, Format-Yaml, and Merge-Yaml handle duplicate keys consistently with conversion/import.
• Tests cover the documented conformance-corpus policy cases.

Related

• Spec folder: spec/Representation-Key-Uniqueness.md