ADR-054: maintained YAML backend for governed Markdown
Date: 2026-10-12 Status: Accepted Author: Rômulo Febasi Supersedes: ADR-004 backend selection (frontmatter contract retained) Tracking: SYN-330 (#316)
Context
The locked serde_yaml_ng 0.10.0 pulls unsafe-libyaml 0.2.11, which is unmaintained (RUSTSEC-2024-0449). The CI advisory gate rejects that graph. An ignore would hide the blocker instead of replacing the unsupported implementation. The current backend is used by frontmatter, typed values, history, provenance, proposals and export; the old promise of a one-file swap is not true in the current code.
Decision
Use yaml_serde 0.10.7, the maintained YAML Organization fork, with libyaml-rs 0.3.0. Rename imports explicitly, retain ordered Mapping/Value and the existing Error::Yaml boundary. Ban the retired serde_yaml_ng and unsafe-libyaml packages. No advisory exceptions or safety claims based only on the package name are added. libyaml-rs still contains translated unsafe Rust; this migration restores maintenance, not a proof of memory safety.
Apply compatible patched lockfile updates to anyhow, crossbeam-epoch, h2, rustls and the yanked der 0.8.0. Keep Rust 1.89, the ONNX runtime and model stack unchanged. The independently modified developer benchmark lockfile is outside this change.
Compatibility and rollback
No workspace format, database migration or bulk Markdown rewrite occurs. Existing readers and writers retain YAML semantics, unknown fields, mapping order, tags and multiline strings. Serialization already normalizes YAML formatting; comments and original quoting were never byte-preserved. Body bytes with a trailing newline are preserved. Test before/after the swap, plus full/incremental index invariants. Untouched files remain byte-identical. Rollback is a binary rollback with the same Markdown format; do not redeploy an advisory-affected binary as an operational security fix.
Alternatives
- serde_norway: compatible API, but the frontend/backend repositories have older maintenance activity than the official fork inspected on 2026-10-12.
- serde_yaml_bw: active hardening but still an unsafe libyaml lineage and a wider API/behavior change.
- serde-saphyr: pure Rust and Rust 1.89 compatible, but no Value/Mapping DOM matching the public in-memory contract; a larger domain migration deserves its own scope.
- noyalib: not selected without an independent safety/maintenance audit; API compatibility alone is insufficient.
- Adding an advisory ignore or disabling the gate: rejected.
Verification
Regression coverage preserves ordered unknown nested fields, scalar types, YAML tags, multiline values and Markdown bytes through disk writes. Existing CLI snapshots and rebuild invariants check canonical behavior. Run fmt, Clippy/tests/doc with all features, cargo deny and the Rust 1.89 build before merge. Record actual results in the PR, not anticipated passes.