Skip to content

write_validated_trait's "byte-identical diff" claim is false for hand-edited trait YAML #322

Description

@realmarcin

Found by canarying a round-trip before the #302 edge migration.

src/traitmech/validation/write_validated.py:108 documents its emission options as:

Match the repo's existing yaml emission convention so re-running the helper over
an existing file produces a byte-identical diff.

That does not hold. Loading and immediately re-writing an unmodified file
changes it:

$ python -c "load dissimilatory_iron_reduction.yaml; write_validated_trait(doc, p)"
byte-identical: False        # 10329 -> 10335 bytes, 11 insertions / 9 deletions

Two causes, both cosmetic but diff-noisy:

  1. Quote style. note: "Textbook Fe(III)-reducer; ..." (hand-written, double
    quoted) is re-emitted unquoted and wrapped.
  2. Line width. safe_dump wraps at its default width (80), which does not
    match where the corpus's hand-edited long strings currently break. Evidence
    snippets and curation_history.changes blocks re-flow.

Why it matters

Any bulk script that touches N trait files via this helper produces a diff where
the real change is buried in reflow churn across every long string in those
files. That is the difference between a reviewable migration and an unreviewable
one — precisely the risk #301 flags for the 366-edge sweep.

The #302 migration therefore uses surgical line-based edits instead, touching
only the lines that actually change.

Fix direction

Either make the claim true or drop it:

  • Pass an explicit width= (and possibly default_style) that reproduces the
    corpus's current formatting, then prove it with a test that round-trips every
    file in data/traits/** and asserts zero diff; or
  • normalise the whole corpus once through the helper so the claim becomes true
    going forward, and gate it with that same test; or
  • soften the docstring to say only that it matches the schema convention, and
    warn that round-tripping a hand-edited file reformats it.

The middle option is the only one that makes the helper safe for bulk use, but
it is a large one-time reformat of 477 files and should be its own PR.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions