Add opt-in YAML merge key resolution

[MariusStorhaug]

Context

YAML 1.2.2 core schema treats << as an ordinary mapping key, but many YAML documents use the YAML 1.1 merge-key convention. The module should support merge-key expansion as an explicit compatibility capability, never as default YAML 1.2 behavior.

Official references:

• YAML 1.2.2 mapping/key model: https://yaml.org/spec/1.2.2/#3211-nodes
• YAML 1.2.2 recommended schemas: https://yaml.org/spec/1.2.2/#10-recommended-schemas
• YAML merge key working draft: https://yaml.org/type/merge.html
• Normative module spec: spec/Merge-Key-Resolution.md

Current State

The module correctly treats << as ordinary mapping data by default. There is no opt-in parameter to expand merge keys when consuming YAML from tools that still emit the YAML 1.1 merge-key convention.

Objective

Add explicit merge-key expansion that composes with parsing, validation, formatting, merging, and PowerShell projection without changing the YAML 1.2 default.

PowerShell Design Considerations

• Use an explicit switch such as -ResolveMergeKey; do not overload default parsing.
• Keep parameter symmetry across string conversion, file import, validation, formatting, and merging.
• Make merge expansion happen before projection so rich PowerShell objects receive the expanded mapping.
• Keep error behavior classified for invalid merge values, duplicate merge keys, and merge cycles.

Tasks

• Add opt-in merge-key expansion for mappings and aliases to mappings.
• Support sequence-of-mappings merge values with YAML merge precedence rules.
• Preserve direct-entry precedence over contributed merge entries.
• Detect invalid merge values, duplicate merge keys, and merge cycles.
• Apply resource limits to expansion work.
• Document default YAML 1.2 behavior and opt-in YAML 1.1 compatibility behavior.

Benefits

• Improves interoperability with common YAML files that still use merge keys.
• Keeps YAML 1.2 conformance by default.
• Gives script authors a clear and discoverable compatibility switch.

Acceptance Criteria

• << remains ordinary mapping data without the opt-in switch.
• Merge keys expand correctly with the opt-in switch.
• Direct entries override merged entries without duplicate-key errors.
• Invalid merge values and cycles terminate with classified errors.
• Test-Yaml, Format-Yaml, and Merge-Yaml honor the opt-in behavior consistently.

Related

• Spec folder: spec/Merge-Key-Resolution.md
• Related closed stream-merging groundwork: Add representation-preserving YAML stream merging #43