PureYAML/docs/rules/research-compatibility.md

Research Compatibility Rules

PureYAML replaces behavior that is currently studied in the private PureYAMLResearch repository. Compatibility work must be research-led and implementation-independent.

Mandatory Start Point

Before changing parser, scanner, composer, emitter, validation, or typed Codable conversion behavior:

• inspect the matching source, tests, or fixtures in PureYAMLResearch;
• identify the observable behavior PureYAML should match or deliberately reject;
• write PureYAML tests that pin that behavior before or with the implementation;
• keep all public-package code original and dependency-free.

Copying Boundary

Do not copy source from Yams, CYaml, libyaml, or research-only references into Sources/. Use the research repository for behavior discovery only.

Allowed:

• exact behavioral assertions in PureYAML tests;
• attribution in ATTRIBUTION.md and design docs;
• small independently written fixtures that describe input and expected output.

Forbidden:

• copied parser, scanner, emitter, or encoder implementation code;
• C files, generated parser files, or external SwiftPM dependencies;
• compatibility claims that were not checked against the research source or a deliberate PureYAML design decision.

Test Contract

Every compatibility test must pin at least one of:

• exact parsed value tree;
• exact emitted YAML;
• exact decoded Swift value;
• exact encoded value tree;
• exact validation issue;
• exact path-aware decoding or encoding error;
• exact required absence check for fields that must not appear.

Parser Compatibility Lessons

YAML compatibility is parser-state compatibility, not only value-model compatibility. Indicator characters such as -, ?, and : are meaningful only after indentation, flow depth, and the current parser production are taken into account.

When fixing scanner or parser behavior:

• preserve tests for the exact production corpus shape that failed, not only a smaller feature in isolation;
• combine interacting YAML features in one regression fixture when the bug requires their interaction;
• keep implementation fixes grammar-level and content-independent; never branch on corpus file names, OpenAPI field names, vendor names, schema prefixes, or other production-data fingerprints;
• for plain scalar continuation bugs, cover both sides explicitly:
  • a more-indented continuation line that starts with an indicator but remains text;
  • a same-context indicator line that must remain a collection item.