Codify safe unknown YAML tag handling

[MariusStorhaug]

Context

YAML 1.2.2 distinguishes valid tags, recognized tags, valid content, and native type availability. A processor may compose a representation for a valid unknown tag even when it cannot construct a native application type.

Official YAML 1.2.2 references:

• https://yaml.org/spec/1.2.2/#3313-recognized-and-valid-tags
• https://yaml.org/spec/1.2.2/#3314-available-tags
• https://yaml.org/spec/1.2.2/#691-node-tags
• Normative module spec: spec/Unknown-Tag-Policy.md

Current State

The module intentionally avoids YAML-driven type activation. Valid unknown tagged scalars project as strings, unknown tagged collections project by kind, and representation-level commands preserve effective tags.

Objective

Codify, verify, and document the safe unknown-tag policy so users can rely on valid application tags without risking reflection or command invocation.

PowerShell Design Considerations

• Rich PowerShell projection should remain safe by default: tags must not name .NET types, commands, modules, or paths.
• Representation-level commands should preserve unknown tags for users who need lossless YAML graph operations.
• Future resolver parameters should be explicit opt-in parameters with clear parameter sets and should not change default safety.
• Errors should distinguish invalid tag syntax from valid-but-unknown tags.

Tasks

• Verify valid unknown scalar tags project as strings by default.
• Verify valid unknown collection tags project by collection kind by default.
• Verify representation-level commands preserve valid unknown effective tags.
• Verify invalid tags fail before unknown-tag fallback applies.
• Document the safety model and future resolver interaction.

Benefits

• Supports application-specific YAML safely.
• Prevents accidental code activation from untrusted YAML.
• Preserves tags for representation-preserving workflows.

Acceptance Criteria

• Valid unknown tags are accepted by conversion/import/test/format/merge surfaces.
• Unknown tagged scalars remain strings unless an explicit future resolver changes construction.
• Unknown tags are preserved by representation-preserving output.
• Invalid tags terminate with YamlInvalidTag and do not enter the unknown-tag policy.
• Tests prove that tag text never causes .NET type creation or PowerShell command invocation.

Related

• Spec folder: spec/Unknown-Tag-Policy.md
• Related closed groundwork: Support tags and !! shorthand #24