Add opt-in YAML presentation metadata model

[MariusStorhaug]

Context

YAML 1.2.2 treats comments, scalar style, tag handles, anchor names, directives, and indentation as presentation details. Object projection can legitimately discard those details, but users editing existing YAML often need an opt-in round trip that preserves or controls presentation metadata.

Official YAML 1.2.2 references:

• https://yaml.org/spec/1.2.2/#412-load
• https://yaml.org/spec/1.2.2/#323-presentation-stream
• https://yaml.org/spec/1.2.2/#64-comments
• Normative module spec: spec/Presentation-Metadata.md

Current State

Issue #28 already tracks preserving comments through a conversion round trip. The broader presentation metadata capability also includes scalar styles, tag spelling, anchor names, and presentation control APIs.

Objective

Extend the existing presentation-preservation work into a complete opt-in metadata model that supports rich PowerShell editing without silently losing YAML presentation details.

PowerShell Design Considerations

• Metadata should be opt-in so normal object projection remains simple and idiomatic.
• Consider commands or parameter sets that make metadata-bearing objects explicit rather than surprising users with hidden properties.
• Preserve pipeline friendliness: metadata should survive common assignment, filtering, and re-emission workflows where feasible.
• Provide clear boundaries for when metadata cannot be preserved through arbitrary PowerShell object transformations.

Tasks

• Preserve comments as already requested by Preserve comments through ConvertFrom-Yaml/ConvertTo-Yaml round-trip #28.
• Preserve or expose scalar style metadata.
• Preserve or expose tag spelling and handle metadata where feasible.
• Preserve or expose anchor name metadata where feasible.
• Provide commands or parameters to inspect, set, test, and use presentation metadata.
• Document where ordinary PowerShell object transformations lose metadata.

Benefits

• Enables editing YAML configuration while keeping human-authored context.
• Gives users explicit control over presentation rather than implicit best-effort behavior.
• Provides a foundation for representation-preserving transformations.

Acceptance Criteria

• Comment preservation requirements from Preserve comments through ConvertFrom-Yaml/ConvertTo-Yaml round-trip #28 remain satisfied.
• Metadata retention is opt-in and default projection remains simple.
• Re-emission can use retained metadata when the caller requests it.
• Metadata inspection and mutation are available through idiomatic PowerShell surfaces.
• Loss boundaries are documented and tested.

Related

• Existing issue: Preserve comments through ConvertFrom-Yaml/ConvertTo-Yaml round-trip #28
• Spec folder: spec/Presentation-Metadata.md