The noyalib Manual

noyalib is a YAML 1.2 library for Rust: pure safe code (#![forbid(unsafe_code)]), full serde integration, a lossless CST for byte-faithful editing, JSON Schema validation, and 406/406 on the official YAML test suite. Six crates ship in lockstep at the identical =0.0.X — the library plus the noya-cli binaries, the LSP and MCP servers, the WASM bundle, and the noyalib-serde-yaml drop-in replacement for archived serde_yaml.

This manual is the rendered form of the Markdown that lives in the repository’s docs/ directory — every page here is a file there, and the repository copy is canonical.

Where to start

The rest of the documentation

• API reference — docs.rs/noyalib (also rendered alongside this manual)
• Getting started — GETTING_STARTED.md
• Per-crate guides — each satellite repository’s README and docs/ directory

Getting started with noyalib

A focused walkthrough for someone who just landed on the repo and wants to use the library. The full reference is the root README; this page is the on-ramp.

Install

As a Rust library

[dependencies]
noyalib = "0.0.58"

no_std (alloc-only) and lean profiles are documented in the per-crate README.

As a CLI tool

The noyafmt and noyavalidate binaries ship through every mainstream package channel:

cargo install noya-cli --locked        # crates.io (noyafmt + noyavalidate)
brew tap sebastienrousseau/tap && brew install noyalib   # macOS
yay -S noyalib-bin                     # Arch / AUR

The library crate is noyalib; the binary crate that produces noyafmt / noyavalidate is noya-cli. See the Install section of the root README for the full per-channel matrix.

Full per-channel install matrix lives in pkg/PUBLISH.md.

First parse

use noyalib::{from_str, to_string};

#[derive(Debug, serde::Serialize, serde::Deserialize, PartialEq)]
struct Config {
    name: String,
    port: u16,
    features: Vec<String>,
}

fn main() -> Result<(), noyalib::Error> {
    let yaml = "
name: noyalib
port: 8080
features:
  - parse
  - emit
";
    let cfg: Config = from_str(yaml)?;
    assert_eq!(cfg.port, 8080);

    let back = to_string(&cfg)?;
    assert!(back.contains("name: noyalib"));
    Ok(())
}

What you probably want next

Building from source

The full developer guide (toolchain, task map, reproducing every CI gate locally) is DEVELOPMENT.md.

git clone https://github.com/sebastienrousseau/noyalib.git
cd noyalib
make                # cargo check + clippy + test
make fmt            # rustfmt --check
make deny           # cargo-deny supply-chain audit

Prerequisites: Rust 1.89.0+ (edition 2024) for the core library and the CLI / LSP satellite crates alike. make orchestrates the full local check suite.

Running examples

The crates/noyalib/examples/ directory contains 76 runnable examples covering every public surface — schema validation, borrowed-path parsing, CST editing, no_std, robotics newtypes, figment integration, and more. Each compiles independently:

cargo run --example hello
cargo run --example schema_validation --features validate-schema
cargo run --example figment --features figment

Where to ask for help

• Bug reports / feature requests: GitHub Issues
• Security issues: see SECURITY.md for the disclosure process — do not file public issues for vulnerabilities
• Migration questions: docs/MIGRATION-FROM-SERDE-YAML.md covers the common gotchas

noyalib user guide

A long-form companion to the README. The README is the elevator pitch and reference; this guide walks through every public-facing surface in the order you typically encounter it.

If you’ve used serde_yaml 0.9 before, also see MIGRATION-FROM-SERDE-YAML.md — most call sites are mechanical to update.

Contents

1. Reading YAML
2. Writing YAML
3. The dynamic Value tree
4. Source spans (Spanned<T>)
5. Strict deserialise (typo detection)
6. Parser policies (defence in depth)
7. Structured diagnostics
8. Lossless edits (cst::Document)
9. Schema validation and autofix
10. Multi-document streams + parallel parse
11. The CLI tools (noyafmt, noyavalidate)
12. WASM, MCP, and LSP

1. Reading YAML

The simplest case — read into a typed struct via serde:

#![allow(unused)]
fn main() {
use noyalib::from_str;

#[derive(Debug, serde::Deserialize)]
struct Server {
    host: String,
    port: u16,
}

let yaml = r#"
host: api.example.com
port: 8080
"#;
let s: Server = from_str(yaml)?;
assert_eq!(s.port, 8080);
}

Every input shape serde_yaml supports has a noyalib equivalent:

Each has a _with_config(input, &ParserConfig) variant for when you need to tighten parser limits or opt into legacy behaviours (see section 6).

2. Writing YAML

Mirror surface for the write side:

#![allow(unused)]
fn main() {
use noyalib::to_string;

#[derive(serde::Serialize)]
struct Server { host: String, port: u16 }

let yaml = to_string(&Server {
    host: "api.example.com".into(),
    port: 8080,
})?;
println!("{yaml}");
// host: api.example.com
// port: 8080
}

to_string_with_config(&v, &cfg) accepts a SerializerConfig that tunes indent, flow style, scalar style, document markers, and block-scalar thresholds. See crates/noyalib/examples/emit.rs for every option in action.

3. The dynamic Value tree

When the schema isn’t fixed at compile time, work with Value:

#![allow(unused)]
fn main() {
use noyalib::{from_str, Value};

let yaml = "
server:
  port: 8080
items:
  - name: first
    debug: true
  - name: second
";

let v: Value = from_str(yaml)?;

// Dot-path traversal.
let port = v.get_path("server.port").and_then(|n| n.as_u64());

// Sequence indexing.
let first = v.get("items").and_then(|s| s.get(0));

// Path queries — wildcards and recursive descent.
let names = v.query("items[*].name");          // every name in the list
let any   = v.query("..debug");                // every `debug` at any depth

// A key the grammar would read as structure is bracket-quoted;
// `join_keys` spells the path from literal keys.
let app = v.get_path(r#"labels["app.kubernetes.io/name"]"#);
let same = v.get_path(&noyalib::path::join_keys(["labels", "app.kubernetes.io/name"]));

// Mutation.
let mut v = v;
v["server"]["port"] = Value::from(9090u16);
}

Missing keys return None; never panic on lookup.

For lower-overhead reads, the borrowed AST shares scalar bytes with the input:

#![allow(unused)]
fn main() {
use noyalib::borrowed::from_str_borrowed;

let yaml  = "host: localhost\nport: 8080\n";
let v     = from_str_borrowed(yaml)?;
let host  = v.as_mapping().unwrap().get("host").unwrap().as_str();
// host points into `yaml` — no String allocation for the scalar.
}

BorrowedValue<'a> doesn’t follow YAML aliases (*name); use the owned path for documents that anchor.

4. Source spans (Spanned<T>)

Wrap any deserialise target in Spanned<T> to record where in the input it came from:

#![allow(unused)]
fn main() {
use noyalib::{from_str, Spanned};

#[derive(serde::Deserialize)]
struct Cfg {
    port: Spanned<u16>,
    host: Spanned<String>,
}

let cfg: Cfg = from_str("port: 8080\nhost: api\n")?;
assert_eq!(cfg.port.value, 8080);
assert_eq!(cfg.port.start.line(), 1);
assert_eq!(cfg.port.start.column(), 6);
}

Spanned<T> round-trips through serde::Serialize as T — the span info is read-side only. Combine with miette to render the exact offending region:

#![allow(unused)]
fn main() {
use noyalib::Spanned;
#[derive(serde::Deserialize)]
struct Cfg { port: Spanned<u16>, host: Spanned<String> }
let yaml = "port: 80\nhost: api\n";
let cfg: Cfg = noyalib::from_str(yaml)?;
let report = noyalib::diagnostic::spanned_error(
    yaml,
    &cfg.port,
    "port must be >= 1024 (privileged ports not allowed)",
);
eprintln!("{report:?}");
}

See crates/noyalib/examples/validation.rs.

5. Strict deserialise (typo detection)

The single biggest config-file footgun: a typo in a key name silently deserialises into the field’s Default. from_str is lenient by design (extras are ignored), from_str_strict errors out:

#![allow(unused)]
fn main() {
#[derive(Debug, serde::Deserialize)]
struct Cfg { port: u16, host: String }

let yaml = "port: 8080\nhost: api\nporrt: 9090\n";

// Lenient: silently drops the typo.
let c: Cfg = noyalib::from_str(yaml)?;
assert_eq!(c.port, 8080);

// Strict: typed error pointing at `porrt`.
let err = noyalib::from_str_strict::<Cfg>(yaml).unwrap_err();
assert!(err.to_string().contains("porrt"));
}

The strict path walks nested structs — a typo at server.unknown is reported with its parent path. Available on every input shape:

Strictness is opt-in per call site, not global — be strict about config you own and lenient about a third party’s payload in the same program. Runnable walk-through: crates/noyalib/examples/strict_deserialise.rs (cargo run --example strict_deserialise --features strict-deserialise).

6. Parser policies (defence in depth)

YAML’s anchor / merge-key / custom-tag features have historically been amplification vectors (billion-laughs) and remote-code- execution vectors (!!python/object). noyalib doesn’t instantiate arbitrary objects via tags, but you may still want to reject documents that abuse the spec at parse time:

#![allow(unused)]
fn main() {
use noyalib::{from_str_with_config, ParserConfig};
use noyalib::policy::{DenyAnchors, DenyTags, MaxScalarLength};

let cfg = ParserConfig::new()
    .with_policy(DenyAnchors)             // no `&name` / `*name`
    .with_policy(DenyTags)                // reject custom !tag scalars
    .with_policy(MaxScalarLength(64_000)) // cap individual scalar size
    .max_alias_expansions(100)            // billion-laughs guard
    .max_depth(64);

let input = "host: api.example.com\nport: 8080\n";

let res: Result<noyalib::Value, _> =
    from_str_with_config(input, &cfg);
}

Use ParserConfig::profile(ParserProfile::Standard), Strict, or SerdeYaml when the selected trust and compatibility contract should be explicit in code. ParserConfig::strict() remains an alias for the strict profile.

ParserLimits groups the resource budgets independently from YAML semantics. config.limits() extracts the active budgets, and config.with_limits(limits) replaces all of them while preserving version, key, policy, property, registry, and resolver settings.

7. Structured diagnostics

Every parse error carries (line, column, byte_offset) plus a machine-readable error code. The default API exposes a renderer-neutral payload for editors, services, and custom user interfaces:

#![allow(unused)]
fn main() {
use noyalib::{DiagnosticCode, Value};

let err = noyalib::from_str::<Value>("port: [unclosed").unwrap_err();
let diagnostic = err.diagnostic();
assert_eq!(diagnostic.code(), DiagnosticCode::Parse);
assert_eq!(diagnostic.code().as_str(), "noyalib::parse");

if let Some(label) = diagnostic.primary_label() {
    let byte_range = label.span().offset()..label.span().end();
    println!("{} at {byte_range:?}", label.message());
}
}

SourceSpan offsets and lengths are bytes in the original UTF-8 input. Protocol adapters must convert them when a client uses another coordinate system, such as the UTF-16 positions required by LSP.

The minimum, no-feature path also renders a rustc-style snippet:

#![allow(unused)]
fn main() {
use noyalib::Value;

let input = "port: [unclosed";
let err = noyalib::from_str::<Value>(input).unwrap_err();
println!("{}", err.format_with_source(input));
// error: expected ',' or ']'
//   --> input.yaml:1:7
//    |
//  1 | port: [unclosed
//    |       ^^^^^^^^^ here
}

Enable --features miette to render the same payload through the miette::Diagnostic interface with cargo / rustc-style ANSI output. Enable --features ariadne for an ariadne::Report; both adapters consume the canonical code, help, severity, and label list rather than maintaining their own mappings.

// Needs `miette` in *your* Cargo.toml alongside noyalib's `miette`
// feature, so this block is shown rather than compiled here.
fn main() -> miette::Result<()> {
    let cfg: Config = noyalib::from_str(yaml)
        .map_err(|e| miette::Report::new(e)
            .with_source_code(yaml.to_owned()))?;
    Ok(())
}

See crates/noyalib/examples/diagnostic.rs.

8. Lossless edits (cst::Document)

from_str → to_string round-tripping discards comments and exact whitespace by design — the YAML data model excludes both. When you need byte-faithful editing (Renovate-style version bumps, manifest patchers, formatters), use the lossless CST instead:

#![allow(unused)]
fn main() {
use noyalib::cst::parse_document;

let mut doc = parse_document(r#"
Production config
server:
  host: api.example.com
  port: 8080      # bind to public IP
"#)?;

// Surgical edit — only the touched span is rewritten.
doc.set("server.port", "9090")?;
println!("{doc}");
//
// # Production config
// server:
//   host: api.example.com
//   port: 9090      # bind to public IP
//
// (Comment and trailing whitespace preserved byte-for-byte.)
}

The CST exposes:

See crates/noyalib/examples/lossless_edit.rs and crates/noyalib/examples/entry_api.rs.

9. Schema validation and autofix

Under --features validate-schema:

#![allow(unused)]
fn main() {
use noyalib::{from_str, schema_for, validate_against_schema, JsonSchema};

#[derive(serde::Serialize, serde::Deserialize, JsonSchema)]
struct ServerConfig {
    /// Port the server binds on.
    port: u16,
    /// Hostname or IP literal.
    host: String,
}

let schema = schema_for::<ServerConfig>()?;
let data: noyalib::Value = from_str("port: 8080\nhost: api")?;
validate_against_schema(&data, &schema)?;
}

The matching coerce_to_schema(&mut data, &schema) engine rewrites obvious type slips — e.g. port: "8080" (quoted string where the schema declares integer) — back to the schema’s expected type, then re-validates. This is the library engine behind noyavalidate --fix. See crates/noyalib/examples/schema_validation.rs.

9b. Custom YAML tags (Value::Tagged)

YAML lets any node carry a “tag” — a type label like !Color, !Celsius, !!python/object. noyalib surfaces these on the default from_str::<Value> path so downstream code can dispatch on them safely (no global type registry, no runtime code lookup, no attacker-controlled instantiation):

#![allow(unused)]
fn main() {
use noyalib::{from_str, Value};

let v: Value = from_str("!Color '#ff8800'\n")?;
match &v {
    Value::Tagged(t) => {
        println!("tag: {}", t.tag().as_str());          // "!Color"
        println!("inner: {:?}", t.value().as_str());    // Some("#ff8800")
    }
    _ => unreachable!(),
}
Ok::<(), noyalib::Error>(())
}

This contract holds for all three tag-bearing shapes:

With the lossless-u64 feature enabled and ParserConfig::lossless_u64_integers(true), !!int scalars in (i64::MAX, u64::MAX] resolve as Value::Number(Unsigned(_)).

Reading through the wrapper. Two helpers on Value step through the tag for transparent reads:

#![allow(unused)]
fn main() {
use noyalib::{from_str, Value};
let v: Value = from_str("!Color '#ff8800'\n")?;
assert_eq!(v.untag_ref().as_str(), Some("#ff8800"));    // borrow-friendly
let owned = v.untag();                                  // consumes
Ok::<(), noyalib::Error>(())
}

Typed targets see through tags transparently. A #[derive(serde::Deserialize)] struct Foo { ... } against !Foo {x: 1} yields Foo { x: 1 } — the typed visitor never observes the tag string. This is what lets schema-tagged YAML inputs deserialise into bare structs.

Opt out via TagRegistry. When you want noyalib to strip known tags inline on the streaming path (no AST detour, no wrapper to step through), register them:

#![allow(unused)]
fn main() {
use std::sync::Arc;
use noyalib::{from_str_with_config, ParserConfig, TagRegistry};

let cfg = ParserConfig::new()
    .tag_registry(Arc::new(TagRegistry::new().with("!Color")));
// Now `!Color "#ff8800"` deserialises directly into a String,
// no Tagged wrapper, no AST fallback.
}

Reject custom tags entirely. For schema-strict contexts — audit pipelines, security-sensitive ingest — policy::DenyTags fails any document carrying a non-core tag at parse time:

#![allow(unused)]
fn main() {
use noyalib::{from_str_with_config, ParserConfig, Value};
use noyalib::policy::DenyTags;

let cfg = ParserConfig::new().with_policy(DenyTags);
let bad: Result<Value, _> = from_str_with_config("k: !Foo 1\n", &cfg);
assert!(bad.is_err());
}

Round-trip a Tagged value back to YAML. The generic to_string serialises through serde, which routes Value::Tagged(...) as a single-entry map (the right shape for serde_json interop) — losing the YAML-tag wire form. For lossless emit, the dedicated to_string_value / to_writer_value family bypasses the serde pipeline:

#![allow(unused)]
fn main() {
use noyalib::{from_str, to_string_value, Value};
let v: Value = from_str("!Color '#ff8800'\n")?;
let yaml = to_string_value(&v)?;
// `yaml` re-parses into an equivalent `Value::Tagged`.
assert!(matches!(noyalib::from_str::<Value>(&yaml)?, Value::Tagged(_)));
Ok::<(), noyalib::Error>(())
}

Known limitation: the tag-preserving fast path on the deserialise side is engaged only when the target is exactly T = Value (detected via [std::any::TypeId]). Wrapper targets like Spanned<Value>, Vec<Value>, Option<Value>, HashMap<_, Value> route the inner deserialise through the standard transparent-unwrap path. If you need both spans and tag preservation, parse twice (once into Value for tag-aware queries, once into Spanned<T> for the span-aware view).

10. Multi-document streams + parallel parse

YAML’s --- document separator lets one file carry many independent documents (Kubernetes manifests, audit-event streams). The eager API:

#![allow(unused)]
fn main() {
use noyalib::Value;
#[derive(serde::Deserialize)]
struct MyConfig { a: i64 }
let stream = "a: 1\n---\na: 2\n";
use noyalib::{load_all, load_all_as};

// `load_all` yields a lazy iterator of `Result<Value>`; collect it.
let docs: Vec<Value>      = load_all(stream)?.collect::<Result<_, _>>()?;
// `load_all_as` deserializes every document and returns a `Vec<T>` directly.
let typed: Vec<MyConfig>  = load_all_as::<MyConfig>(stream)?;
}

For large streams, the parallel feature unlocks linear-with- cores throughput:

#![allow(unused)]
fn main() {
#[derive(serde::Deserialize)]
struct MyConfig { a: i64 }
let stream = "a: 1\n---\na: 2\n";
// Drop-in for `load_all_as`. Pre-scans `---` boundaries on a
// single thread, then deserialises each document concurrently.
let docs: Vec<MyConfig> = noyalib::parallel::parse(stream)?;
}

The pre-scan is O(input_len); the per-document work parallelises across the Rayon thread pool. Services can supply a bounded, caller-owned pool instead of using Rayon’s global pool:

#![allow(unused)]
fn main() {
let stream = "---\na: 1\n---\na: 2\n---\na: 3\n---\na: 4\n";
let pool = noyalib::parallel::ThreadPoolBuilder::new()
    .num_threads(2)
    .build()?;
let docs = noyalib::parallel::parse_with_config_in_pool::<noyalib::Value>(
    stream,
    &noyalib::ParserConfig::default(),
    &pool,
)?;
assert_eq!(docs.len(), 4);
}

The pool owns the concurrency limit and lifecycle. Inputs with fewer than four documents remain sequential to avoid scheduling overhead.

10b. Error-recovering parser for LSP / IDE (recovery feature)

The default from_str family returns Err at the first syntax violation. LSP / IDE consumers need the opposite contract: keep going past errors, build a best-effort partial tree, collect every error encountered so the editor can show a complete diagnostics list and offer autocomplete on the recoverable subtrees.

#![allow(unused)]
fn main() {
// Cargo.toml: noyalib = { version = "0.0.58", features = ["recovery"] }
use noyalib::recovery::parse_lenient;

let half_typed = "name: noyalib\nfeatures: [recovery, sval\n# ^ unclosed\n";
let r = parse_lenient(half_typed);
assert!(!r.is_complete);
println!("errors: {}", r.errors.len());
// r.value is the best-effort recovered tree.
}

Three-pass recovery: strict pass → DuplicateKeyPolicy::Last retry → line-truncation retry. Multi-document input split on ---; each document recovered independently. Error collection bounded by LenientConfig::max_errors.

See crates/noyalib/examples/recovery_lenient.rs.

10c. Native async parsing on tokio (tokio feature)

For high-concurrency services parsing YAML from network sources, the tokio feature provides bounded drain helpers and a backpressured document stream:

// Needs an async runtime and, for pattern 2, `tokio-util` in *your*
// Cargo.toml, so this block is shown rather than compiled here.
// Cargo.toml: noyalib = { version = "0.0.58", features = ["tokio"] }
use noyalib::tokio_async::{async_yaml_stream, from_async_reader_multi};

// Pattern 1: drain-and-parse
let docs: Vec<MyDoc> = from_async_reader_multi(&mut reader).await?;

// Pattern 2: backpressured stream, one parsed document per item
let documents = async_yaml_stream::<_, MyDoc>(reader);

Per-document boundaries follow the YAML 1.2.2 §9.1.2 --- grammar: column-0 marker followed by whitespace or EOL. Parsing each complete document is synchronous when the stream is polled; the stream prevents additional reads until the consumer requests the next item.

See crates/noyalib/examples/tokio_async_reader.rs.

10d. sval streaming adapter (sval feature)

Alternative to the default serde route for callers wanting to skip serde_derive’s compile-time overhead or the binary-size cost of serde monomorphisation. The adapter implements sval::Value for the noyalib value graph so any sval::Stream consumer can read it:

// `sval` and the `sval::Stream` you hand it are *your* dependencies,
// so this block is shown rather than compiled here.
// Cargo.toml: noyalib = { version = "0.0.58", features = ["sval"] }
let value: noyalib::Value = noyalib::from_str("name: noyalib")?;
sval::Value::stream(&value, &mut my_stream)?;

serde remains the default route; sval is opt-in.

See crates/noyalib/examples/sval_streaming.rs.

11. The CLI tools (noyafmt, noyavalidate)

Two command-line companions ship from the split-out sebastienrousseau/noya-cli repo (split at v0.0.13, ADR-0005; released in strict lockstep):

# Format YAML in-place via the lossless CST.
noyafmt --write config.yaml

# Verify formatting without writing — for CI gates.
noyafmt --check ci/*.yaml

# Validate syntax + (optionally) JSON Schema 2020-12.
noyavalidate --schema schema.yaml in.yaml

# Validate + auto-fix obvious type slips.
noyavalidate --schema schema.yaml --fix in.yaml

Both use the same noyalib::cst::format + coerce_to_schema engines exposed to library callers. Distro-installable via crates.io (cargo install noya-cli --locked), Homebrew, AUR, and the other channels in pkg/PUBLISH.md.

12. WASM, MCP, and LSP

Three satellite crates — each split to its own repo (ADR-0005) and released in strict lockstep with this library — target specific deployment shapes:

• noyalib-wasm (sebastienrousseau/noyalib-wasm). wasm-pack output published to npm as @sebastienrousseau/noyalib-wasm. Browser IDEs use it for live YAML formatting / validation; the bundle is ~338 KB after LTO. Split to its own repo in v0.0.12 (ADR-0005); releases in strict lockstep with this workspace.

• noyalib-mcp (sebastienrousseau/noyalib-mcp). Model Context Protocol server speaking JSON-RPC over stdio. AI agents (Claude Code, GitHub Copilot, …) call parse, format, get, set, validate tools without needing a Rust toolchain. Available as npx @sebastienrousseau/noyalib-mcp (the wrapper bootstraps the binary) and as a GHCR container image ghcr.io/sebastienrousseau/noyalib-mcp. Split to its own repo in v0.0.13 (ADR-0005); releases in strict lockstep with this workspace.

• noyalib-lsp (sebastienrousseau/noyalib-lsp). Language Server Protocol implementation. Editors get format-on-save, inline diagnostics, schema-driven hover docs. Bundled into the noyalib VS Code / Open VSX extension (pkg/vscode/).

Where next

• Source spans + miette diagnostics: crates/noyalib/examples/diagnostic.rs
• Anchor manipulation: crates/noyalib/examples/anchor_shared.rs
• Schema codegen: crates/noyalib/examples/schema_validation.rs
• Figment / garde / validator integration: crates/noyalib/examples/figment.rs, crates/noyalib/examples/validation_garde.rs, crates/noyalib/examples/validation_validator.rs
• CST architecture: ARCHITECTURE.md
• Migrating from serde_yaml: MIGRATION-FROM-SERDE-YAML.md

Reporting issues / sending PRs

Filed at https://github.com/sebastienrousseau/noyalib. Reproducer YAML + the parser config you used together is the fastest path to a fix.

Ecosystem comparison

How noyalib lines up against the other Rust YAML libraries it is likely to be evaluated alongside. Cells reflect the state of the named crates as of 2026-05 (verified against the latest crates.io release of each); corrections welcome via PR.

For per-crate migration guides (function tables, behavioural notes, drop-in shim notes), see MIGRATION.md and the per-crate guides linked from there.

Reading the table

• YAML Test Suite (100% strict) — noyalib is the only Rust YAML implementation that passes all 406 active cases in the YAML 1.2 official Test Suite under strict comparison. The other libraries either don’t track this metric publicly or apply lenience that lets cases the spec rejects pass through.
• C-FFI rows — serde_yml and serde_yaml_ng (the active forks of dtolnay/serde-yaml) wrap libyaml via unsafe-libyaml in their dep tree. Pure-Rust alternatives don’t have this transitive C dependency.
• Streaming deser — noyalib::from_str::<T> walks parser events directly into the typed target without building an intermediate Value AST. The other crates that do have serde integration build the AST first.
• DoS hardening (~12 budgets) — max_depth, max_alias_expansions, max_document_length, max_sequence_length, max_mapping_keys, max_events, max_nodes, max_total_scalar_bytes, max_documents, max_merge_keys, plus the cumulative-alias-byte budget, the alias/anchor ratio guard, and the per-document size cap. See POLICIES.md for defaults and override knobs.

How to verify a row yourself

The cells were sourced from each crate’s Cargo.toml, docs.rs API surface, and recent release notes. To re-verify (e.g. after a new release elsewhere):

# Source-of-truth dump for any crate's exported surface:
cargo doc --no-deps -p <crate> --open

# Dependency tree (catches the libyaml C-FFI hop):
cargo tree -p <crate> --target all

If you spot a stale or wrong cell, file a correction at https://github.com/sebastienrousseau/noyalib/issues.

Benchmarks

All numbers below were measured on Apple M4 (aarch64-apple-darwin), Rust 1.95 stable, criterion --warm-up-time 2 --measurement-time 4. All libraries compiled with --release (LTO=fat, codegen-units=1, panic=abort). Run locally via cargo bench --bench comparison.

PGO — scripts/pgo.sh runs the full LLVM profile-guided optimisation pipeline (instrument → train against the YAML test suite + benches/fixtures/ → merge profdata → optimised rebuild). Adds 5-15% on top of the numbers below; recommended for production deployments.

For algorithmic-complexity guarantees (O(n) parser, O(d) stack depth, O(1) anchor lookup, etc.), see POLICIES.md §4 — Performance & algorithmic complexity.

Headline (5-way Rust YAML head-to-head, every fixture)

Compares noyalib against the five most-used pure-Rust YAML libraries: serde_yaml_ng (the de-facto ecosystem successor to the unmaintained serde_yaml), yaml-rust2 (the heaviest-tuned non-serde parser), serde_yml (the maintainer’s prior crate), yaml-spanned (the closest other span-tracking parser), and serde-saphyr (a high-performance newcomer).

The serde_yml and serde_yaml_ng figures below are recorded measurements, not rerunnable today: both crates were retired from benches/comparison.rs, serde_yml in v0.0.6 (RUSTSEC-2025-0068) and serde_yaml_ng in v0.0.58 (its unsafe-libyaml dependency is unmaintained, RUSTSEC-2024-0449), so that cargo deny and cargo audit stay clean without exemptions.

Deserialize (parse a YAML document into a Value AST)

(serde_yml, yaml-spanned, serde-saphyr ship single-document APIs only — no apples-to-apples cell on the multi-document fixture.)

Serialize (emit a typed value to YAML)

Round-trip (deserialize + serialize)

Headline numbers

noyalib is faster than every Rust YAML library on every fixture measured. Speedup ranges:

Serialize: 3.00×–4.34× over serde_yaml_ng. Round-trip: 1.83× over serde_yaml_ng. The gap to yaml-rust2 is the narrowest because that library doesn’t carry the Spanned<T> plumbing, the per-tag Cow<'a, str> propagation, or the Value::Tagged preservation that noyalib does — paying for those costs is part of the engineering cost. Closing the remaining gap to ≥ 2× over yaml-rust2 runs through SemVer-breaking refactors (CompactString keys in Mapping, bump-arena event lifetimes, eliminating the Value AST on the typed path).

Typed deserialization (streaming, no Value AST)

from_str::<T> walks parser events directly into the typed target, bypassing the Value AST when the caller asked for a typed T. The streaming path bakes in YAML 1.2 semantics (<<: *alias merges natively, !!binary is propagated as a typed tag).

Why serialize is so far ahead

The serializer was built around itoa / ryu direct-write buffers (the fast-int / fast-float features) plus SIMD-driven quote-need detection that lets plain ASCII output emit borrowed bytes without escaping. serde_yaml_ng routes through fmt::Write and revalidates UTF-8 on output — that’s the source of the 3-4× gap.

Why deserialize against yaml-rust2 is closer

yaml-rust2 is a heavily-tuned parser that doesn’t carry the Spanned<T> plumbing, the per-tag Cow<'a, str> propagation, or the Value::Tagged preservation that noyalib does. The 1.12-1.35× gap reflects the engineering cost of those guarantees; yaml-rust2 is a good baseline because it’s the closest pure-Rust parser in feature shape. The path to ≥ 2× over yaml-rust2 on deserialize runs through SemVer-breaking refactors (CompactString keys in Mapping, bump-arena event lifetimes, eliminating the Value AST on the typed path).

Roundtrip (deserialize + serialize)

SIMD structural-discovery throughput

How fast each library can find every YAML delimiter in a 1 MiB real-shaped document. The structural-bitmask path replaces the classical “find one delimiter at a time” pattern with a 32-byte chunk that drains every delimiter via mask.trailing_zeros() before reloading. (benches/structural_bitmask.rs)

serde_yaml_ng and serde-saphyr use byte-by-byte structural discovery — they sit alongside the scalar baseline row and lose to the 32-byte-bitmask path by an order of magnitude on the 1 MiB workload.

SWAR decimal-integer parsing

Plain-scalar integer resolution via the SIMD-Within-A-Register pipeline that folds 8 ASCII digits per u64 cycle. (benches/numeric_parse.rs)

How the SWAR pipeline works

The standard library’s i64::from_str walks one digit at a time, branching on each character to validate it’s 0..=9 and folding into the accumulator with acc * 10 + digit. SWAR fuses this loop:

1. Load 8 bytes into a u64 register (one aligned mov).
2. Subtract b'0' lane-wise (sub_packed).
3. Validate every byte is < 10 via a single masked compare.
4. Combine the eight digits into a single integer with two multiply-and-add rounds (the 0x010A0064... constant pipeline).

The result is an 8-digit chunk consumed in 6 instructions instead of ~24, and i64::MAX (19 digits) parses in 9.75 ns versus 24.6 ns — a 2.5x speedup. The full pipeline is documented inline in crates/noyalib/src/simd.rs.

Every SWAR pipeline has a portable byte-by-byte fallback that Miri verifies under big-endian (mips64) so the byte-order assumption stays explicit.

Parallel multi-document throughput

Linear scaling across CPU cores for ----separated streams (telemetry logs, audit exports, Kubernetes-resource snapshots). Pre-scan runs in O(input_len) on the main thread; the per- document parse work distributes across the Rayon thread pool. (benches/streaming_vs_value.rs, benches/large_doc_soak.rs)

#![allow(unused)]
fn main() {
#[derive(serde::Deserialize, PartialEq, Debug)]
struct MyType { kind: String }
let yaml = "kind: a\n---\nkind: b\n";
// Single-threaded baseline:
let docs: Vec<MyType> = noyalib::load_all_as(yaml)?;

// Parallel (off by default — pulls Rayon under `parallel`
// feature). Drop-in replacement, scales near-linearly with cores
// on multi-document inputs:
let docs: Vec<MyType> = noyalib::parallel::parse(yaml)?;
assert_eq!(docs.len(), 2);
}

Other Rust YAML libraries the comparison table covers run single-threaded.

Architecture validation

Reproduce: make bench-compare (the comparison bench with the compare-saphyr feature, so serde-saphyr is in the same run) and cargo bench --bench architecture.

Head-to-head with serde-saphyr (2026-09-06)

serde-saphyr is the other pure-Rust crate that passes the full official test suite, so it is the comparison that matters. Same run, same host, same command, every crate in the same criterion session:

make bench-compare   # cargo bench --bench comparison --features compare-saphyr

Host: Apple A18 Pro. Toolchain: rustc 1.98.0 (88d9e12ae 2026-08-18). Times are criterion medians in the default bench profile (no LTO tuning), so they sit above the headline table’s tuned numbers; the ratios are what to read.

serde-saphyr does not appear on the multi-document fixture because its from_str reads one document. Rerun the command to refresh this table; the numbers above are reproducible to within criterion’s reported confidence intervals.

v0.0.6 feature benchmarks

Three additional bench arms cover the optional surfaces added in v0.0.6 (recovery, sval, tokio). Run together with:

cargo bench --bench v006_features --features recovery,sval,tokio

Project metrics

Profile-Guided Optimization (PGO) — noyalib

Profile-Guided Optimization is a compiler technique that lays out hot paths inline, cold paths off the fast track, and optimises branch ordering based on the actual execution profile of a representative workload — rather than the static heuristics LLVM uses by default. For YAML parsing, where the scanner’s per-byte dispatch is the dominant cost, PGO typically yields 5–15% speedup on from_str::<Value> and cst::parse_document against representative inputs.

This document is the operational guide: how to build a PGO’d noyalib binary, what’s instrumented, and what gains to expect.

Status: opt-in. The default cargo install noya-cli path does not use PGO (PGO requires a two-pass build that’s longer and produces target-specific artefacts). Distro packagers and downstream teams who want the extra 5–15% can run scripts/pgo.sh to produce a PGO’d binary.

Quick start

# Run the full PGO pipeline against the default training corpus.
./scripts/pgo.sh

# Custom training input:
./scripts/pgo.sh path/to/representative-workload.yaml

# Train a different binary (default is noyafmt):
PGO_TARGET=noyavalidate ./scripts/pgo.sh

The script:

1. Builds an instrumented binary with RUSTFLAGS=-Cprofile-generate=….
2. Runs the instrumented binary against the training corpus (default: every YAML under tests/yaml-test-suite/ plus benches/fixtures/).
3. Merges the per-process *.profraw files via llvm-profdata merge into a single merged.profdata.
4. Builds the optimised binary with RUSTFLAGS=-Cprofile-use=…/merged.profdata.

Output: target/release/<binary> is now PGO’d. The script prints a hyperfine recipe for measuring the gain against the non-PGO baseline.

Requirements

• rustc 1.89.0+. PGO has been stable since Rust 1.45; noyalib’s MSRV (1.89.0) easily clears that.
• llvm-profdata on $PATH. Install via rustup component add llvm-tools-preview. The script auto-discovers the rustup-shipped binary if $PATH lookup fails.
• Training corpus that resembles real production input. The default corpus (the YAML test suite + benches fixtures) is broad — for per-team optimisation, replace it with your own representative YAML.

What gets instrumented

PGO instruments every basic block of the trained binary including its statically-linked dependencies. For noyafmt / noyavalidate, that’s:

• noyalib::parser::scanner — the per-byte dispatch loop.
• noyalib::parser::events — the event-tree state machine.
• noyalib::parser::loader — the AST builder.
• noyalib::cst::* — when the binary touches the CST path (noyafmt --check, --fix).
• noyalib::ser — emit-side hot paths.
• Transitive deps — serde, indexmap, ryu, itoa, memchr.

The compiler then re-orders branches in the optimised pass so the most-taken arm of each match is checked first. For YAML, that’s overwhelmingly plain scalar in the scanner dispatch and Mapping / Sequence in the event-tree machine.

Expected gains

Measured on Apple M4, Rust 1.94 stable, 97 KB synthetic mapping-of-records document:

Gains are workload-specific. Ranges of 5–20% are typical for programs whose hot path is well-defined and stable; YAML parsing is exactly that kind of workload.

Combining with the workspace [profile.release] settings

The PGO build composes with the workspace release profile (opt-level = 3, lto = "fat", codegen-units = 1, overflow-checks = true). The training pass uses the same release profile (instrumentation aside), so the optimised build benefits from both LTO + PGO together.

CI integration

The scripts/pgo.sh workflow is intentionally kept out of the per-PR CI path because:

1. The two-pass build doubles the wall-clock cost.
2. PGO artefacts are target-specific (per architecture).
3. A small per-PR perf regression isn’t best caught via PGO — CodSpeed already tracks per-bench drift on the standard release profile.

PGO belongs in the release pipeline when the binary is about to ship to a wide audience. The .github/workflows/release-binaries.yml workflow is the natural integration point — build PGO’d artefacts for the published binaries (noyafmt, noyavalidate, noyalib-mcp, noyalib-lsp) per host triple.

Cross-platform notes

• Linux: works out of the box with the rustup-shipped llvm-tools-preview.
• macOS: same. Apple-silicon-specific PGO data is produced; do not reuse a Mac-trained merged.profdata on Linux x86_64.
• Windows: works with llvm-profdata.exe from the rustup llvm-tools-preview component. The MSVC linker handles the -Cprofile-use= flag; no extra setup needed.

Trained merged.profdata is per host triple — re-run the script on each release runner.

Troubleshooting

• “cannot find llvm-profdata” → install via rustup component add llvm-tools-preview.
• “profile data file is empty” → the training step didn’t produce any .profraw files. Verify the binary actually executed against the training corpus (the script tees output via /dev/null; check exit codes).
• “profile data is incompatible” → the rustc version that generated the profile differs from the one consuming it. Re-run the full pipeline on the current toolchain.

Further reading

• The Rust Reference — profile-guided optimization.
• LLVM Profile-Guided Optimization.
• The cargo-pgo crate provides a higher-level driver alternative to the shell script — drop-in replacement for scripts/pgo.sh if your team prefers a Cargo-native UX.

Glossary

Domain vocabulary used across noyalib’s documentation, code, and commit messages. When a term has both a YAML-spec meaning and a noyalib-specific meaning, both are listed.

YAML specification terms

Anchor. A &name marker placed before a node so the node can be referenced later via an alias. Per the YAML 1.2 spec each document has its own anchor namespace; noyalib resets the anchor table on DocumentEnd.

Alias. A *name reference that resolves to the value previously labelled by an anchor of the same name within the same document. noyalib resolves aliases eagerly on both the owned (Value) and borrowed (BorrowedValue) paths.

Block style. Indentation-driven layout — the multi-line form most configuration files use. Contrast with flow style. noyalib’s formatter defaults to block style for non-leaf collections.

Flow style. JSON-shaped inline layout — [a, b, c], {k: v}. Mostly used for short collections inside a block document.

Plain scalar. A scalar with no quoting — port: 8080. The resolver determines its type from its lexical form (the core schema in YAML 1.2; the broad schema in YAML 1.1).

Folded scalar. A >-introduced multi-line scalar that joins lines with a space, preserving paragraph breaks.

Literal scalar. A |-introduced multi-line scalar that preserves every newline byte for byte.

Tag. An explicit type annotation — !!str, !!int, or a custom URI like !shopping. noyalib carries tags through the parse and emits them on serialise where present.

Document marker. --- (start) or ... (end). A YAML stream is a sequence of zero or more documents; the markers are optional for the first document but required between subsequent ones.

Directive. A %-prefixed line at the document head — %YAML 1.2 for version, %TAG !x! tag:example.com,2026: for tag prefix shorthands. Per the spec, at most one %YAML directive per document.

Merge key. The << key. When its value is a mapping (or a sequence of mappings), the merged keys are inherited unless overridden. noyalib supports three policies via MergeKeyPolicy::{Auto, Disabled, Strict}.

Surrogate pair. A two-\uXXXX JSON-style escape that combines into a single supplementary-plane code point via the UTF-16 algorithm. noyalib pairs them in double-quoted scalars; lone surrogates are rejected.

Sexagesimal. Base-60 integer notation — 1:30 reads as 1*60 + 30 = 90. YAML 1.2 dropped this from the core schema; noyalib accepts it under legacy_sexagesimal (auto-on with YamlVersion::V1_1).

Norway problem. YAML 1.1 resolves bare no to false. The country code for Norway is NO. Configuration files that store two-letter country codes were silently mis-typed for years until YAML 1.2 narrowed the boolean lexicon to true / false. noyalib reproduces the 1.1 behaviour under legacy_booleans.

noyalib architecture terms

Value. The owned, dynamically-typed YAML value enum — Null / Bool / Number / String / Sequence / Mapping / Tagged. Heap-allocated; the natural counterpart to serde_json::Value.

BorrowedValue<'a>. The zero-copy variant where string scalars and mapping keys are Cow<'a, str> and borrow directly from the input buffer. The shape is otherwise identical to Value.

Mapping. noyalib’s string-keyed map type. Insertion-ordered (backed by IndexMap). Mapping keys that the YAML resolver produces as non-strings (numbers, booleans, sequences) are stringified on entry.

MappingAny. The Value-keyed map type for documents whose mapping keys are themselves complex YAML values (sequences, mappings, etc.). Use this when string-keyed Mapping would lose fidelity.

Streaming deserializer. The pull-style from_str::<T> path that binds directly into T without materialising a Value intermediate. Faster and lower-memory than the loader path; the default for typed deserialisation.

Loader. The path that materialises Value first, then runs Deserializer<'_> against it. Used for dynamic-shape inputs and the strict-mode and span-tracking helpers.

Green tree. The immutable, byte-faithful CST that backs noyalib::cst::Document. Stores every byte of the source — content, whitespace, comments, indentation, line breaks. Edits rewrite the tree structurally and re-emit byte-for-byte where untouched.

Span tree. A side-table mapping every Value node to its source byte range. Built lazily by the loader when the caller requests Spanned<T> deserialisation or path-aware diagnostics.

Spanned scalar. A scalar value paired with its source byte range (start..end). Used by Spanned<T> for editor diagnostics and JSON-Schema $id-style cross-references.

Strict deserialise. from_str_strict<T> and friends — surface input keys that the target type does not declare as a typed Error::UnknownField listing every offending path. Backed by serde_ignored.

CST mutation. Editing through noyalib::cst::Document rather than re-serialising a modified T. Preserves comments, indent choices, and sibling formatting; the diff is local to the edited span.

Tag registry. A user-supplied TagRegistry that maps custom !tag URIs to handlers. Lets the streaming path strip or transform application-specific tags inline rather than routing through the AST fallback.

Cargo / build terms

MSRV. Minimum Supported Rust Version. The whole lockstep set — the noyalib core library and every satellite crate — shares a single floor of 1.89.0 as of v0.0.58.

#![forbid(unsafe_code)]. A crate-root attribute that makes any unsafe block a compile error. Applied to every crate in the workspace; non-negotiable.

Lean profile. The --no-default-features --features ["std"] build (or the minimal meta-feature alias) — drops itoa, ryu, and serde_ignored for FIPS / embedded / audit-heavy environments. 5 runtime deps instead of 8.

compat-serde-yaml. The drop-in shim crate feature that exposes a name-for-name surface compatible with serde_yaml 0.9. Every type it exposes is a noyalib-native type re-exported under the serde_yaml name; no upstream dep.

Doctest. A Rust code block (```rust) inside a docstring or README that cargo test --doc compiles and runs. noyalib has ~384 doctests; the noyalib README is wired into doctesting via #[doc = include_str!("../README.md")].

Migrating to noyalib

This is the umbrella index for migrating to noyalib from every actively-published Rust YAML crate. Each link goes to a standalone, self-contained guide with TL;DR diff, function table, behavioural notes, and migration checklist.

Crates.io / docs.rs state verified 2026-09-05. If the upstream API has shifted since, file an issue at https://github.com/sebastienrousseau/noyalib/issues and we’ll update.

Coming from serde_yaml and want zero source changes? Rename the package and keep every call site:

serde_yaml = { package = "noyalib-serde-yaml", version = "=0.0.52" }

noyalib-serde-yaml is the behavioural serde_yaml 0.9 shim, released in lockstep with the core. The guides below are for moving to the native API.

Pick your starting crate

Already on noyalib from before the v0.0.12 workspace split? That move is covered separately in MIGRATION-WORKSPACE-SPLIT.md.

What to expect from noyalib regardless of source crate

Across every guide, three behavioural notes recur. They each default to safer / stricter behaviour than serde_yaml 0.9 and its forks; opt-outs are documented per guide.

1. Value::Tagged is preserved through the Value data path. from_str::<Value>("!Custom 'hi'\n") returns Value::Tagged(t) (t.tag() == "!Custom", t.value() == Value::String("hi")). Typed targets (#[derive(serde::Deserialize)] struct Foo { … }) still see through the tag transparently — the preservation only affects the dynamic Value path.
2. YAML 1.2 strict booleans by default. country: NO parses as Value::String("NO"), not Value::Bool(false). Opt into YAML 1.1 boolean recognition via ParserConfig::new().legacy_booleans(true) if you need the old behaviour for round-trip compatibility with legacy files.
3. Multi-doc streams use load_all_as. noyalib::load_all_as::<T>(input)? returns a Vec<T> directly. The Deserializer::from_str(...).map(...) pattern from serde_yaml and its forks collapses to this one entry point.

What noyalib adds (no equivalent in any of the eight)

• noyalib::from_str_strict::<T> — error on unknown keys.
• noyalib::Spanned<T> — source-location wrapper for typed fields. (yaml-spanned covers a similar use case for the dynamic path; noyalib covers both dynamic and typed.)
• noyalib::cst::Document — lossless byte-faithful edits with comment / whitespace preservation.
• noyalib::ParserConfig / noyalib::SerializerConfig — unified, fluent-builder configuration covering every per-call toggle.
• noyalib::validate_against_schema — JSON Schema 2020-12 validation against the parsed document.
• noyalib::compat::serde_yaml — name-for-name re-export shim for the most common in-flight use serde_yaml::*; pattern, with no transitive serde_yaml 0.9 dependency.
• A set of binaries: noyafmt (formatter), noyavalidate (schema validator + auto-fixer), noyalib-mcp (Model Context Protocol server for AI tooling), noyalib-lsp (Language Server Protocol implementation).

What noyalib does not do (yet)

• No equivalent to serde-saphyr’s strict panic-free-by-construction proof — noyalib’s defence is #![forbid(unsafe_code)] plus the resource-limit gates, not formal verification.
• No streaming Deserializer you can next() event-by-event from user code — noyalib::Deserializer is a serde-trait driver, not an event iterator.
• No equivalent to serde-yaml-bw’s Value::Alias variant — noyalib resolves aliases at parse time per YAML 1.2 §7.1.

If your migration runs into a shape we don’t cover, file an issue at https://github.com/sebastienrousseau/noyalib/issues with the upstream crate version and the input that misbehaves.

Migrating to noyalib from other Rust YAML crates

serde_yaml 0.9 is unmaintained — the upstream dtolnay/serde-yaml repo was archived 2024-03-25 and RUSTSEC-2024-0320 flags every cargo audit run that depends on it. Several active forks now sit downstream (yaml_serde, serde-yaml-ng, serde-norway, serde-yaml-bw, serde_yml until it was archived 2025-09); the serde-saphyr and yaml-spanned crates take different design shapes (no DOM, span-aware parsing) but live in the same niche.

noyalib is a clean-room reimplementation of YAML 1.2 with the same serde data model, no unsafe code, and no libyaml C dependency. The bulk of this document is the name-for-name migration guide for serde_yaml 0.9 (the most common starting point); per-library shorthand for every other ecosystem crate ships at the bottom under Migrating from other YAML libraries.

TL;DR

For most call sites, the migration is mechanical:

-[dependencies]
-serde_yaml = "0.9"
+[dependencies]
+noyalib = "0.0"

-use serde_yaml::Value;
-let v: Value = serde_yaml::from_str(input)?;
-let s        = serde_yaml::to_string(&v)?;
+use noyalib::Value;
+let v: Value = noyalib::from_str(input)?;
+let s        = noyalib::to_string(&v)?;

If you want the change to be invisible to call sites, enable the compat-serde-yaml feature:

[dependencies]
noyalib = { version = "0.0", features = ["compat-serde-yaml"] }

-use serde_yaml;
+use noyalib::compat::serde_yaml;

Every public symbol the shim exposes is backed by a noyalib-native type — there’s no transitive dependency on the archived serde_yaml crate.

Function-by-function mapping

Things noyalib adds (no equivalent in serde_yaml)

These are pure additions — adopting them is optional, the migration above doesn’t require any of them.

See the public API surface map at the top of crates/noyalib/src/lib.rs.

Things noyalib does not do (yet)

• Round-trip comments through the data-binding API. The YAML data model excludes comments by spec. noyalib::cst::Document preserves them byte-for-byte for the lossless tooling path, but from_str::<T> → to_string(&T) does not. No Rust YAML library does this end-to-end.
• Implicit <<: merge keys outside of explicit handling. YAML 1.2 dropped merge keys from the spec; noyalib follows 1.2 by default but ships an opt-in MergeKeyPolicy::Auto for backwards compatibility.
• Custom-tag dispatch via serde(rename). noyalib surfaces non-core tags as Value::Tagged(...) rather than routing them to a typed enum variant by tag-string. Adopt noyalib::TagRegistry if you need strip-through behaviour for known tags.

Behavioural differences worth knowing

1. Value::Tagged is a 7th variant — and noyalib preserves scalar tags too

serde_yaml::Value has six variants (Null, Bool, Number, String, Sequence, Mapping); noyalib::Value adds Tagged(Box<TaggedValue>) as a 7th. If you exhaustively match against Value somewhere, the migration adds one arm:

 match value {
     Value::Null         => …,
     Value::Bool(b)      => …,
     Value::Number(n)    => …,
     Value::String(s)    => …,
     Value::Sequence(s)  => …,
     Value::Mapping(m)   => …,
+    Value::Tagged(t)    => handle_tag(t.tag(), t.value()),
 }

Where serde_yaml differs from noyalib: serde_yaml 0.9 drops custom-tag scalars from the Value tree by default — a !Custom 'hello' scalar deserialises into Value::String("hello") and the tag is lost. noyalib preserves the tag: from_str::<Value>("!Custom 'hello'\n") returns Value::Tagged(t) (t.tag() == "!Custom", t.value() == Value::String("hello")). This matches noyalib’s behaviour for tagged sequences and tagged mappings — three Tagged shapes, one consistent rule.

If your existing code worked because the tag was silently dropped, migrate by either:

• Calling value.untag() (or value.untag_ref() for borrow-friendly reads) before any as_str / as_i64 / type-cast you used to do directly. This is the smallest diff.
• Switching to a typed deserialise. Typed targets (#[derive(serde::Deserialize)] struct Foo { ... }) see through tags transparently — from_str::<Foo>("!Foo {x: 1}") yields Foo { x: 1 } regardless of the tag.
• Registering the tag with TagRegistry::with for inline strip-through on the streaming path. Useful when you want noyalib to dispatch into a typed handler keyed on the tag string.

If you don’t inspect tags at all and want the old serde_yaml behaviour wholesale, that’s the compat::serde_yaml shim’s default: see “Drop-in compatibility shim” below.

2. Default boolean recognition is YAML 1.2 strict

serde_yaml 0.9 followed YAML 1.1 — bare yes / no / on / off parsed as booleans. noyalib follows YAML 1.2 by default — only true / false count.

This is the “Norway problem” fix: country: NO no longer silently rewrites to country: false.

If you depend on the legacy behaviour (Docker Compose, GitHub Actions, pre-1.2 toolchains), opt back in:

#![allow(unused)]
fn main() {
use noyalib::Value;
use noyalib::{from_str_with_config, ParserConfig};
let cfg = ParserConfig::new().legacy_booleans(true);
let v: Value = from_str_with_config("country: NO\n", &cfg)?;
assert_eq!(v["country"].as_bool(), Some(false));
}

3. Multi-doc streams use load_all_as

serde_yaml’s Deserializer::from_str returns an iterator of Result<Value>. noyalib exposes:

#![allow(unused)]
fn main() {
#[derive(serde::Deserialize)]
struct MyType { a: i64 }
let stream = "a: 1\n---\na: 2\n";
// Eager parse, returns Vec<T>.
let docs: Vec<MyType> = noyalib::load_all_as::<MyType>(stream)?;

// Or collect Values — `load_all` yields a lazy `Result<Value>` iterator.
let docs: Vec<noyalib::Value> = noyalib::load_all(stream)?.collect::<Result<_, _>>()?;
}

For very large streams (audit logs, Kubernetes-resource snapshots), the parallel path is a drop-in replacement:

#![allow(unused)]
fn main() {
#[derive(serde::Deserialize)]
struct MyType { a: i64 }
let stream = "a: 1\n---\na: 2\n";
// Same input, parses each doc concurrently across Rayon.
let docs: Vec<MyType> = noyalib::parallel::parse(stream)?;
assert_eq!(docs.len(), 2);
}

Requires the parallel feature.

4. Error handling stays type-safe

noyalib::Error is a #[non_exhaustive] enum carrying the location and a structured message. The Display implementation matches the rustc-error format closely:

error: expected ',' or ']'
  --> input.yaml:2:7
   |
 1 | host: localhost
 2 | port: [broken
   |       ^^^^^^ here

from_str_with_config accepts a ParserConfig carrying every limit you might want (max_depth, max_alias_expansions, max_total_scalar_bytes, duplicate_key_policy, strict_booleans, etc.). The factory ParserConfig::strict() turns every dial up for untrusted input.

5. The deserialise-target bound is T: 'static

serde_yaml::from_str<T> constrains T: for<'de> Deserialize<'de>. noyalib::from_str<T> adds T: 'static. Every real-world DeserializeOwned type already satisfies this — the HRTB on its own already disallows borrowed lifetimes — and the 'static is what lets noyalib detect at the call site whether the caller’s target is Value itself (in which case the tag-preserving fast path engages) or something else (typed deserialise stays transparent).

Concretely: a &'a str target was already disallowed by the HRTB; String, Vec<...>, HashMap<String, V>, and every derive-d struct continue to work unchanged. If you hit a compile error whose message mentions a missing 'static bound on a T you control, add + 'static to the bound — that’s the only diff.

This bound is a soft constraint. The few external trait signatures that drop 'static from their DeserializeOwned bound (notably figment::Format::from_str) are accommodated by a private internal entry point that bypasses the tag-preserving fast path. You don’t see it; your Format impl just works.

Drop-in compatibility shim

Two forms, both behavioural since v0.0.29 — the shim parses under ParserConfig::serde_yaml_compat() and its Error renders upstream’s wording and locations, pinned by an 18-case contract suite whose expectations were captured live from serde_yaml 0.9.34 (tests/serde_yaml_contract.rs).

Zero source changes — the package rename. The noyalib-serde-yaml crate re-exports the shim under a package name Cargo can substitute for serde_yaml:

[dependencies]
serde_yaml = { package = "noyalib-serde-yaml", version = "=0.0.58" }

Every use serde_yaml::… keeps compiling and behaving — << stays a literal key, 0123 stays a string, u64::MAX keeps precision, alias bombs fail with upstream’s repetition limit exceeded, and the pinned error classes carry libyaml’s phrasing and locations.

Two-line form. If you prefer depending on noyalib directly, enable the compat-serde-yaml feature:

[dependencies]
noyalib = { version = "0.0", features = ["compat-serde-yaml"] }

#![allow(unused)]
fn main() {
// Module path matches `serde_yaml`'s, but every type is
// noyalib-native — no transitive dep on the archived crate.
use noyalib::compat::serde_yaml::{from_str, to_string, Value, Mapping, Number};
}

The shim is feature-gated so users who don’t need migration help don’t see the extra surface. One documented partial in the error contract: a custom tag refused under deserialize_any anchors its location at the value where upstream anchors at the tag — message and refusal semantics are exact.

Migration checklist

For each crate that depends on serde_yaml:

• Replace serde_yaml = "0.9" → noyalib = "0.0" (or noyalib = { version = "0.0", features = ["compat-serde-yaml"] } for the shim path).
• Replace use serde_yaml::*; → use noyalib::*; (or use noyalib::compat::serde_yaml::*;).
• If you exhaustively match Value, add a Tagged(_) arm (or call .untag() first).
• Decide YAML 1.1-vs-1.2 boolean handling: stay on YAML 1.2 strict (the safer default) or opt into legacy_booleans(true).
• Run cargo audit. The RUSTSEC-2024-0320 advisory should no longer match anything.
• Run your existing test suite. The noyalib-shaped from_str is a drop-in for the surface above; failures almost always trace to one of the three behavioural notes in this document.

If you hit a snag, file an issue at https://github.com/sebastienrousseau/noyalib/issues with the input that misbehaves — every report makes the migration story better.

Migrating from other YAML libraries

If you’re coming from a different YAML crate (serde_yml, yaml_serde, serde-yaml-ng, serde-norway, serde-yaml-bw, serde-saphyr, or yaml-spanned), each has its own dedicated guide with a TL;DR diff, function-mapping table, behavioural notes, and migration checklist:

• MIGRATION-FROM-SERDE-YML.md — serde_yml 0.0 (archived 2025-09)
• MIGRATION-FROM-YAML-SERDE.md — yaml_serde 0.10 (active fork)
• MIGRATION-FROM-SERDE-YAML-NG.md — serde-yaml-ng 0.10 (active drop-in fork)
• MIGRATION-FROM-SERDE-NORWAY.md — serde-norway 0.9 (hard-fork)
• MIGRATION-FROM-SERDE-YAML-BW.md — serde-yaml-bw 2.5 (non-drop-in 2.x)
• MIGRATION-FROM-SERDE-SAPHYR.md — serde-saphyr 0.0 (no Value DOM)
• MIGRATION-FROM-YAML-SPANNED.md — yaml-spanned 0.0 (parser-only, span-aware)

The umbrella index is MIGRATION.md — start there if you’re not sure which guide applies, or skim the compatibility matrix to pick the right one.

Migrating from serde-yaml-ng to noyalib

serde-yaml-ng (crate name serde_yaml_ng) is acatton’s independent continuation of serde_yaml. The README markets it as “as compatible as possible” with the original. 0.10.0 (2024-05-26) is the most recent release — actively maintained but the cadence is slow.

noyalib is a clean-room reimplementation of YAML 1.2 with the same serde data model, no unsafe code, and no libyaml C dependency.

Crates.io / docs.rs state verified 2026-09-05 (every function this guide names still exists on docs.rs). If the upstream API has shifted since, file an issue and we’ll update.

TL;DR

-[dependencies]
-serde_yaml_ng = "0.10"
+[dependencies]
+noyalib = "0.0"

-use serde_yaml_ng::Value;
-let v: Value = serde_yaml_ng::from_str(input)?;
-let s        = serde_yaml_ng::to_string(&v)?;
+use noyalib::Value;
+let v: Value = noyalib::from_str(input)?;
+let s        = noyalib::to_string(&v)?;

Function-by-function mapping

serde_yaml_ng mirrors serde_yaml 0.9 exactly.

serde_yaml_ng::Value is the same 7-variant enum: Null, Bool, Number, String, Sequence, Mapping, Tagged(Box<TaggedValue>). Match arms unchanged.

Behavioural differences worth knowing

The three notes that apply to the serde_yaml migration apply here. Full discussion in MIGRATION-FROM-SERDE-YAML.md; headlines:

1. Value::Tagged is preserved. from_str::<Value>("!Custom 'hi'\n") returns Value::Tagged(t) (t.tag() == "!Custom", t.value() == Value::String("hi")). serde_yaml_ng matched serde_yaml’s pre-Tagged behaviour; noyalib preserves the wrapper. Call .untag() to get the inner.
2. YAML 1.2 strict booleans by default. country: NO stays Value::String("NO"). Opt into YAML 1.1 boolean recognition via ParserConfig::new().legacy_booleans(true).
3. Multi-doc streams — use noyalib::load_all_as::<T>(input) for Vec<T> of every document in the stream.

Drop-in compatibility shim

[dependencies]
noyalib = { version = "0.0", features = ["compat-serde-yaml"] }

-use serde_yaml_ng::{from_str, to_string, Value, Mapping, Number};
+use noyalib::compat::serde_yaml::{from_str, to_string, Value, Mapping, Number};

The shim is a noyalib-native re-export under the compat::serde_yaml path; no transitive serde_yaml_ng dependency.

Migration checklist

• Replace serde_yaml_ng = "0.10" → noyalib = "0.0" (or noyalib = { version = "0.0", features = ["compat-serde-yaml"] } for the shim path).
• Replace use serde_yaml_ng::*; → use noyalib::*; (or use noyalib::compat::serde_yaml::*;).
• If you exhaustively match Value, the 7-arm shape is unchanged.
• Decide YAML 1.1-vs-1.2 boolean handling.
• Run your existing test suite.

If you hit a snag, file an issue at https://github.com/sebastienrousseau/noyalib/issues.

Migrating from serde_yml to noyalib

serde_yml was a continuation fork of serde_yaml after upstream archival. The serde_yml repo was itself archived 2025-09-03; 0.0.13 (2024-08-25) is the last published release. The fork inherits the full serde_yaml 0.9 API shape including the 7-variant Value and the with::singleton_map* family.

noyalib is a clean-room reimplementation of YAML 1.2 with the same serde data model, no unsafe code, and no libyaml C dependency.

Crates.io / docs.rs state verified 2026-09-05 (every function this guide names still exists on docs.rs). If the upstream API has shifted since, file an issue and we’ll update.

TL;DR

-[dependencies]
-serde_yml = "0.0"
+[dependencies]
+noyalib = "0.0"

-use serde_yml::Value;
-let v: Value = serde_yml::from_str(input)?;
-let s        = serde_yml::to_string(&v)?;
+use noyalib::Value;
+let v: Value = noyalib::from_str(input)?;
+let s        = noyalib::to_string(&v)?;

That is the entire migration for the typical call site — serde_yml’s public surface mirrors serde_yaml’s function-for-function and noyalib’s does the same.

Function-by-function mapping

serde_yml’s Value enum has the same 7 variants as serde_yaml’s and noyalib’s — Null, Bool, Number, String, Sequence, Mapping, Tagged(Box<TaggedValue>). No match-arm changes are required.

Behavioural differences worth knowing

The same three behavioural notes that apply to the serde_yaml migration apply here. See MIGRATION-FROM-SERDE-YAML.md for the full discussion; the headlines:

1. Value::Tagged is preserved through the Value data path. noyalib::from_str::<Value>("!Custom 'hi'\n") returns Value::Tagged(t) (t.tag() == "!Custom", t.value() == Value::String("hi")), not the transparent-unwrapped Value::String("hi"). serde_yml’s behaviour matched serde_yaml’s pre-Tagged behaviour. To get the unwrapped string, call value.untag().as_str().
2. YAML 1.2 strict booleans by default. country: NO parses as Value::String("NO"), not Value::Bool(false). Opt into YAML 1.1 boolean recognition via ParserConfig::new().legacy_booleans(true) if you need the old behaviour for round-trip compatibility with legacy files.
3. Multi-doc streams use load_all_as. serde_yml’s Deserializer::from_str(...).map(...) pattern maps to noyalib::load_all_as::<T>(input)? returning Vec<T>.

Drop-in compatibility shim

Because serde_yml’s API is a verbatim mirror of serde_yaml’s, the same compat shim works:

[dependencies]
noyalib = { version = "0.0", features = ["compat-serde-yaml"] }

-use serde_yml::{from_str, to_string, Value, Mapping, Number};
+use noyalib::compat::serde_yaml::{from_str, to_string, Value, Mapping, Number};

The shim re-exports noyalib-native types under noyalib::compat::serde_yaml::* — no transitive dependency on the archived serde_yaml 0.9 nor serde_yml 0.0.

Migration checklist

• Replace serde_yml = "0.0" → noyalib = "0.0" (or noyalib = { version = "0.0", features = ["compat-serde-yaml"] } for the shim path).
• Replace use serde_yml::*; → use noyalib::*; (or use noyalib::compat::serde_yaml::*;).
• If you exhaustively match Value, the 7 variant arms are already correct — no shape change.
• Decide YAML 1.1-vs-1.2 boolean handling: stay on YAML 1.2 strict (the safer default) or opt into legacy_booleans(true).
• Run cargo audit. The migration removes any transitive serde_yaml 0.9 advisory exposure.
• Run your existing test suite. Failures almost always trace to one of the three behavioural notes above.

If you hit a snag, file an issue at https://github.com/sebastienrousseau/noyalib/issues with the input that misbehaves.

Migrating from serde-saphyr to noyalib

serde-saphyr (module serde_saphyr) is bourumir-wyngs’s clean-room serde adapter on top of the saphyr parser. 1.2.0 (2026-08-30) is the current release. The README explicitly states:

serde-saphyr is not a fork of serde-yaml and shares no code with it (apart from some reused tests).

The marquee design choice: no Value DOM. serde-saphyr streams events directly into the typed deserialise target. If you need an untyped sink, the README suggests serde_json::Value.

noyalib is a clean-room reimplementation of YAML 1.2 with the same serde data model, no unsafe code, and no libyaml C dependency. noyalib’s default from_str<T> path is also streaming-first; the Value DOM is added, not removed.

Crates.io / docs.rs state verified 2026-09-05 (every function this guide names still exists on docs.rs). If the upstream API has shifted since, file an issue and we’ll update.

TL;DR

-[dependencies]
-serde-saphyr = "0.0"
+[dependencies]
+noyalib = "0.0"

-use serde_saphyr::from_str;
-let cfg: Config = from_str(input)?;
+use noyalib::from_str;
+let cfg: Config = from_str(input)?;

The typed-target migration is a name swap. The major adds are the Value DOM, the Spanned<T> wrapper, the lossless cst::Document editor, and JSON Schema validation.

Function-by-function mapping

Options builders

serde_saphyr uses an explicit Options struct (or the options! macro shorthand) per call. noyalib uses ParserConfig / SerializerConfig builders:

-use serde_saphyr::{from_str_with_options, options};
-let cfg: Config = from_str_with_options(input, options! {
-    max_depth: 64,
-})?;
+use noyalib::{from_str_with_config, ParserConfig};
+let parser = ParserConfig::new().max_depth(64);
+let cfg: Config = from_str_with_config(input, &parser)?;

Same shape, different surface — the noyalib builder is a fluent struct so you can clone / share configs across call sites.

Adding a Value DOM

If you used serde_saphyr and wanted untyped inspection, you were probably routing through serde_json::Value. noyalib has a YAML-native Value:

-let v: serde_json::Value = serde_saphyr::from_str(input)?;
+let v: noyalib::Value = noyalib::from_str(input)?;

noyalib::Value keeps YAML’s full data model (numeric types distinct from JSON’s, Tagged for custom tags, ordered mappings via IndexMap).

Behavioural differences worth knowing

1. noyalib has a Value DOM, but doesn’t require it. The default from_str::<T> path streams directly into typed targets — same shape as serde_saphyr, no AST allocated. The Value tree is only built when the caller asks for it via from_str::<Value>.
2. Panic-free parser. Both crates target the same “defensive parser” niche. serde-saphyr’s “panic-free” guarantee corresponds to noyalib’s #![forbid(unsafe_code)] plus the resource-limit gates (max_depth, max_alias_expansions, max_document_length).
3. Value::Tagged exists in noyalib. Custom-tag scalars like !Custom 'hi' surface as Value::Tagged(t) (t.tag() == "!Custom", t.value() == Value::String("hi")). If you hit a tagged scalar in serde_saphyr’s typed path the tag was simply preserved in the YAML 1.2 sense; noyalib typed deserialise sees through the tag transparently to the inner value, matching the serde_saphyr typed contract.
4. YAML 1.2 strict by default. country: NO stays a string. serde-saphyr is YAML 1.2 by design; the migration is neutral on this dimension.
5. Tag-driven instantiation rejected. serde-saphyr rejects YAML tags that try to pick a typed-deserialise target (the so-called “billion-laughs of types” attack); noyalib’s typed path also ignores tags during target resolution, only using them for the Value data path.

Drop-in compatibility shim

noyalib::compat::serde_yaml mirrors serde_yaml 0.9, not serde-saphyr. There’s no serde-saphyr-shaped shim because the surface is small enough that the function-by-function table above is the migration. If you want to keep use serde_saphyr::*; imports, define a thin local module that re-exports the noyalib equivalents:

#![allow(unused)]
fn main() {
mod yaml_compat {
// in src/yaml_compat.rs
pub use noyalib::{
    from_reader, from_slice, from_str,
    to_fmt_writer, to_string,
    to_writer as to_io_writer,  // rename
    ParserConfig as Options,
    SerializerConfig as SerializerOptions,
};
}
let _: yaml_compat::Options = yaml_compat::Options::new();
}

Migration checklist

• Replace serde-saphyr = "0.0" → noyalib = "0.0".
• Replace use serde_saphyr::*; → use noyalib::*;.
• Replace Options { max_depth: …, … } / options! { … } → ParserConfig::new().max_depth(…)….
• Replace *_with_options calls with *_with_config(input, &cfg).
• Replace to_io_writer with to_writer, to_string_multiple with to_string_multi.
• If you routed dynamic inspection through serde_json::Value, switch to noyalib::Value for the YAML data model (numeric types distinct from JSON, Tagged for custom tags, ordered mappings).
• Run your existing test suite.

If you hit a snag, file an issue at https://github.com/sebastienrousseau/noyalib/issues.

Migrating from serde-norway to noyalib

serde-norway (crate name serde_norway) is cafkafk’s hard-fork of serde_yaml. 0.9.42 (2024-12-21) is the most recent release. The fork name nods at the YAML 1.1 “Norway problem” (country: NO parsing as false). The API is serde_yaml-shape-identical — the rebrand is the value-add, not API divergence.

noyalib is a clean-room reimplementation of YAML 1.2 with the same serde data model, no unsafe code, and no libyaml C dependency.

Crates.io / docs.rs state verified 2026-09-05 (every function this guide names still exists on docs.rs). If the upstream API has shifted since, file an issue and we’ll update.

TL;DR

-[dependencies]
-serde_norway = "0.9"
+[dependencies]
+noyalib = "0.0"

-use serde_norway::Value;
-let v: Value = serde_norway::from_str(input)?;
-let s        = serde_norway::to_string(&v)?;
+use noyalib::Value;
+let v: Value = noyalib::from_str(input)?;
+let s        = noyalib::to_string(&v)?;

Function-by-function mapping

serde_norway mirrors serde_yaml 0.9 exactly.

serde_norway::Value is the same 7-variant enum: Null, Bool, Number, String, Sequence, Mapping, Tagged(Box<TaggedValue>). Match arms unchanged.

Behavioural differences worth knowing

If you adopted serde_norway specifically because of the Norway problem, the migration to noyalib keeps that fix in place — noyalib defaults to YAML 1.2 strict booleans (only true / false parse as Value::Bool). country: NO stays Value::String("NO") under both crates.

The other two behavioural notes that apply to every serde_yaml fork apply here too. Full discussion in MIGRATION-FROM-SERDE-YAML.md:

1. Value::Tagged is preserved through the Value data path. from_str::<Value>("!Custom 'hi'\n") returns Value::Tagged(t) (t.tag() == "!Custom", t.value() == Value::String("hi")). Call .untag() to get the inner if you used the unwrapped form.
2. YAML 1.2 strict booleans by default. Same default as serde_norway — no behavioural change.
3. Multi-doc streams use load_all_as. noyalib::load_all_as::<T>(input) returns Vec<T> directly.

Drop-in compatibility shim

[dependencies]
noyalib = { version = "0.0", features = ["compat-serde-yaml"] }

-use serde_norway::{from_str, to_string, Value, Mapping, Number};
+use noyalib::compat::serde_yaml::{from_str, to_string, Value, Mapping, Number};

Migration checklist

• Replace serde_norway = "0.9" → noyalib = "0.0" (or noyalib = { version = "0.0", features = ["compat-serde-yaml"] } for the shim path).
• Replace use serde_norway::*; → use noyalib::*; (or use noyalib::compat::serde_yaml::*;).
• If you exhaustively match Value, the 7-arm shape is unchanged.
• No boolean-handling decision needed — both crates default to YAML 1.2 strict.
• Run your existing test suite.

If you hit a snag, file an issue at https://github.com/sebastienrousseau/noyalib/issues.

Migrating from serde-yaml-bw to noyalib

serde-yaml-bw (crate name serde_yaml_bw) is bourumir-wyngs’s hardened fork of serde_yaml. 2.5.7 (2026-08-15) is the current release. The bw reads as “better warnings” / “billion-laughs warden” — the fork’s marquee features are billion-laughs DoS hardening, anchor / alias preservation, merge-key support, nested-enum support, and binary scalars.

The 2.x major version line breaks serde_yaml’s API in several places. The README explicitly states:

serde_yaml_bw is a fork of serde-yaml originally, but it is not a drop-in replacement.

noyalib is a clean-room reimplementation of YAML 1.2 with the same serde data model, no unsafe code, and no libyaml C dependency. This guide is the function-mapping bridge to noyalib’s surface.

Crates.io / docs.rs state verified 2026-09-05 (every function this guide names still exists on docs.rs). If the upstream API has shifted since, file an issue and we’ll update.

TL;DR

-[dependencies]
-serde_yaml_bw = "2"
+[dependencies]
+noyalib = "0.0"

-use serde_yaml_bw::Value;
-let v: Value = serde_yaml_bw::from_str(input)?;
-let s        = serde_yaml_bw::to_string(&v)?;
+use noyalib::Value;
+let v: Value = noyalib::from_str(input)?;
+let s        = noyalib::to_string(&v)?;

The mechanical migration is similar — the surface diverges in the multi-document API, the options builders, and the Value enum shape (8 variants vs 7).

Function-by-function mapping

SerializerBuilder ↔ SerializerConfig

serde_yaml_bw’s builder pattern:

// The *old* library's API, shown for comparison — `serde_yaml_bw` is
// not a dependency here, so this block is not compiled.
use serde_yaml_bw::SerializerBuilder;
let mut buf = Vec::new();
let mut ser = SerializerBuilder::default()
    .check_unresolved_anchors(true)
    .build(&mut buf);
value.serialize(&mut ser)?;

The noyalib equivalent uses a config struct:

#![allow(unused)]
fn main() {
let value: noyalib::Value = noyalib::from_str("a: 1\n")?;
use noyalib::SerializerConfig;
let cfg = SerializerConfig::new();
// configure cfg as needed
let mut buf = Vec::new();
noyalib::to_writer_with_config(&mut buf, &value, &cfg)?;
assert_eq!(String::from_utf8(buf)?, "a: 1");
}

Multi-document streams

serde_yaml_bw exposes a four-way fan-out (from_str_multi / from_slice_multi / from_reader_multi / from_multiple) for multi-doc input. noyalib collapses these into a single load_all_as entry point:

#![allow(unused)]
fn main() {
#[derive(serde::Deserialize)]
struct Cfg { a: i64 }
let input = "a: 1\n---\na: 2\n";
let docs: Vec<Cfg> = noyalib::load_all_as(input)?;
assert_eq!(docs.len(), 2);
}

For raw Value per document:

#![allow(unused)]
fn main() {
let input = "a: 1\n---\na: 2\n";
let docs: Vec<noyalib::Value> = noyalib::load_all_as(input)?;
assert_eq!(docs.len(), 2);
}

Value shape — 8 variants → 7 variants

serde_yaml_bw::Value has 8 variants:

• Null (with optional anchor)
• Bool(bool) (with optional anchor)
• Number(Number) (with optional anchor)
• String(String) (with optional anchor)
• Sequence(Sequence) (with optional anchor)
• Mapping(Mapping) (with optional anchor)
• Alias(String) — anchor reference, unresolved
• Tagged(Box<TaggedValue>)

noyalib::Value has 7 variants — there’s no Alias. noyalib resolves aliases at parse time, per YAML 1.2:

 match v {
     Value::Null            => …,
     Value::Bool(_)         => …,
     Value::Number(_)       => …,
     Value::String(_)       => …,
     Value::Sequence(_)     => …,
     Value::Mapping(_)      => …,
-    Value::Alias(_name)    => …,
     Value::Tagged(_)       => …,
 }

If your code matched Value::Alias, replace those arms with the post-resolution variant — once resolved, the alias becomes whatever the anchor pointed at (usually String, Mapping, or Sequence).

If you relied on serde_yaml_bw’s anchor metadata on each scalar variant, noyalib does not surface that on the Value tree directly. The CST layer (noyalib::cst::Document) keeps anchor / alias source spans and exposes them via the Document::span_at(path) and Document::comments_at(path) APIs for editor-grade tooling.

Behavioural differences worth knowing

1. Alias resolution is eager. noyalib resolves *anchor_name to the anchor’s value at parse time (per YAML 1.2 §7.1). serde_yaml_bw’s Value::Alias variant has no equivalent in noyalib; if you need to detect an alias use site, work at the CST layer.
2. Billion-laughs DoS hardening. Both crates guard against exponential alias amplification. noyalib’s defaults: max_alias_expansions = 100, max_document_length bounded by the input size; configure via ParserConfig::new().max_alias_expansions(...).
3. Merge keys (<<) — both crates support YAML 1.1 merge keys. noyalib’s MergeKeyPolicy enum lets you choose: Auto (default), AsOrdinary (treat << as a literal key), or Error (reject).
4. Value::Tagged is preserved. from_str::<Value>("!Custom 'hi'\n") returns Value::Tagged(t) where t.tag() == "!Custom" and t.value() == Value::String("hi") — same as serde_yaml_bw.
5. YAML 1.2 strict booleans by default. country: NO stays Value::String("NO"). Opt into YAML 1.1 boolean recognition via ParserConfig::new().legacy_booleans(true).

Drop-in compatibility shim

The noyalib::compat::serde_yaml shim mirrors serde_yaml 0.9 (7-variant Value), not serde_yaml_bw. If you used serde_yaml_bw’s 2.x-specific surface (the multi-doc family, SerializerBuilder, the Alias variant), the shim won’t help — use the noyalib-native APIs directly.

Migration checklist

• Replace serde_yaml_bw = "2" → noyalib = "0.0".
• Replace use serde_yaml_bw::*; → use noyalib::*;.
• If you matched Value::Alias, drop those arms and handle the post-resolution variant instead.
• Replace *_multi / *_multiple calls with noyalib::load_all_as.
• Replace SerializerBuilder / *Options builders with noyalib::SerializerConfig / noyalib::ParserConfig.
• If you used the _with_options overload family, use noyalib::from_str_with_config (and the matching to_writer_with_config, from_reader_with_config, …).
• Decide YAML 1.1-vs-1.2 boolean handling.
• Run your existing test suite. Failures usually trace to either the Alias arm or the multi-doc API change.

If you hit a snag, file an issue at https://github.com/sebastienrousseau/noyalib/issues.

Migrating from yaml_serde to noyalib

yaml_serde (also resolvable as yaml-serde) is the actively maintained fork of serde_yaml under the yaml org. 0.10.7 (2026-08-18) is the current release. The fork advertises itself as a true drop-in for serde_yaml and documents a Cargo package = rename so existing use serde_yaml::*; imports keep compiling without touching call sites.

noyalib is a clean-room reimplementation of YAML 1.2 with the same serde data model, no unsafe code, and no libyaml C dependency.

Crates.io / docs.rs state verified 2026-09-05 (every function this guide names still exists on docs.rs). If the upstream API has shifted since, file an issue and we’ll update.

TL;DR

-[dependencies]
-yaml_serde = "0.10"
+[dependencies]
+noyalib = "0.0"

-use yaml_serde::Value;
-let v: Value = yaml_serde::from_str(input)?;
-let s        = yaml_serde::to_string(&v)?;
+use noyalib::Value;
+let v: Value = noyalib::from_str(input)?;
+let s        = noyalib::to_string(&v)?;

If you adopted yaml_serde via the Cargo package-rename trick (keeping use serde_yaml::*; in source), drop the rename:

-[dependencies]
-serde_yaml = { package = "yaml_serde", version = "0.10" }
+[dependencies]
+noyalib = "0.0"

-use serde_yaml::{from_str, to_string, Value};
+use noyalib::{from_str, to_string, Value};

Function-by-function mapping

yaml_serde mirrors serde_yaml 0.9 exactly. Every entry below holds for both spellings; substitute your import path.

yaml_serde::Value is the same 7-variant enum as serde_yaml::Value and noyalib::Value: Null, Bool, Number, String, Sequence, Mapping, Tagged(Box<TaggedValue>).

Behavioural differences worth knowing

The three behavioural notes that apply to the serde_yaml migration apply here. The full discussion lives in MIGRATION-FROM-SERDE-YAML.md; the headlines:

1. Value::Tagged is preserved through the Value data path. noyalib::from_str::<Value>("!Custom 'hi'\n") returns Value::Tagged(t) (t.tag() == "!Custom", t.value() == Value::String("hi")). To get the unwrapped inner, call value.untag().as_str().
2. YAML 1.2 strict booleans by default. country: NO stays Value::String("NO"). Opt into legacy YAML 1.1 boolean recognition via ParserConfig::new().legacy_booleans(true).
3. Multi-doc streams use load_all_as. noyalib::load_all_as::<T>(input) returns Vec<T> directly.

Drop-in compatibility shim

If you adopted yaml_serde to keep use serde_yaml::*; imports compiling and you can’t change call sites at all, the noyalib compat shim does the same:

[dependencies]
noyalib = { version = "0.0", features = ["compat-serde-yaml"] }

-use serde_yaml::{from_str, to_string, Value, Mapping, Number};
+use noyalib::compat::serde_yaml::{from_str, to_string, Value, Mapping, Number};

The shim re-exports noyalib-native types under noyalib::compat::serde_yaml::* — no transitive dep on either upstream.

Migration checklist

• Replace yaml_serde = "0.10" (or the package-rename pattern under serde_yaml = { package = "yaml_serde" }) → noyalib = "0.0".
• Replace use yaml_serde::*; → use noyalib::*; (or use noyalib::compat::serde_yaml::*; for the shim path).
• If you exhaustively match Value, the 7 variant arms are already correct — no shape change.
• Decide YAML 1.1-vs-1.2 boolean handling: stay on YAML 1.2 strict (the safer default) or opt into legacy_booleans(true).
• Run your existing test suite. Failures almost always trace to one of the three behavioural notes above.

If you hit a snag, file an issue at https://github.com/sebastienrousseau/noyalib/issues with the input that misbehaves.

Migrating from yaml-spanned to noyalib

yaml-spanned is romnn’s span-aware YAML parser built on libyaml-safer. 0.0.3 (2025-12-27) is the current release. The crate’s value proposition is preserving source spans on every value so diagnostics can point at the exact line and column.

Two things to know up front:

1. yaml-spanned does not provide to_string / to_writer. It is a parser / DOM-construction crate, not a serializer. If you used it for read-only or DOM-walk workloads, you were probably pairing it with serde_yaml (or another crate) for the emit side.
2. yaml-spanned is built on libyaml-safer, which uses unsafe internally. noyalib is #![forbid(unsafe_code)] end-to-end; the migration tightens the safety guarantee.

noyalib is a clean-room reimplementation of YAML 1.2 with the same serde data model, no unsafe code, no libyaml C dependency, and a typed span wrapper (Spanned<T>) that covers the same diagnostic use case.

Crates.io / docs.rs state verified 2026-09-05 (every function this guide names still exists on docs.rs). If the upstream API has shifted since, file an issue and we’ll update.

TL;DR

If you used yaml-spanned for span info on a typed config:

-use yaml_spanned::{from_str, Value};
-let v: Value = from_str(input)?;
-// Walk v.span() / v.value to extract span+payload.
+use noyalib::{from_str, Spanned};
+#[derive(serde::Deserialize)]
+struct Config { name: Spanned<String>, port: Spanned<u16> }
+let cfg: Config = from_str(input)?;
+let line = cfg.name.start.line();
+let col  = cfg.name.start.column();

If you used yaml-spanned for general dynamic inspection without typed targets:

-use yaml_spanned::{from_str, Value};
-let v: Value = from_str(input)?;
+use noyalib::{from_str, Value};
+let v: Value = from_str(input)?;

noyalib::Value covers the same 7-variant DOM. For per-value spans on the dynamic path, parse through the CST:

#![allow(unused)]
fn main() {
let input = "server:\n  port: 8080\n  host: localhost\n";
let doc = noyalib::cst::parse_document(input)?;
let span = doc.span_at("server.port");  // (start, end) byte offsets
assert!(span.is_some());
}

Function-by-function mapping

Span access

yaml-spanned returns a Spanned<Value> wrapper from every parse entry. To read both the value and the source span, you unpack the wrapper.

noyalib::Spanned<T> plays the same role at the typed deserialise layer:

#![allow(unused)]
fn main() {
let input = "host: localhost\nport: 8080\n";
use noyalib::Spanned;

#[derive(serde::Deserialize)]
struct ServerConfig {
    host: Spanned<String>,
    port: Spanned<u16>,
}

let cfg: ServerConfig = noyalib::from_str(input)?;
println!(
    "host at line {}, col {}",
    cfg.host.start.line(),
    cfg.host.start.column(),
);
println!(
    "port range: bytes {}..{}",
    cfg.port.start.index(),
    cfg.port.end.index(),
);
}

For dynamic-path workloads (where yaml-spanned returned a Spanned<Value>), use noyalib::cst::parse_document and query spans by path:

#![allow(unused)]
fn main() {
let input = "server:\n  host: localhost\n";
let doc = noyalib::cst::parse_document(input)?;
if let Some((start, end)) = doc.span_at("server.host") {
    println!("server.host span: bytes {start}..{end}");
}
}

The CST layer also exposes comments at each node (doc.comments_at(path)), which yaml-spanned does not preserve.

Lossy iterators

yaml-spanned’s from_str_lossy* family silently drops documents that fail to parse. noyalib’s load_all returns a DocumentIterator yielding Result<Value> — the caller decides whether to drop, log, or fail-fast:

-let docs: Vec<Spanned<Value>> = yaml_spanned::from_str_lossy_all(input);
+let docs: Vec<noyalib::Value> = noyalib::load_all(input)?
+    .filter_map(|res| res.ok())
+    .collect();

The explicit form is recommended — silent error-drop in a parser is rarely what users actually want.

Builder ↔ Value construction

yaml-spanned’s Builder lets you construct a Value tree programmatically. noyalib exposes the same surface via the From / Into impls and the variant constructors:

-let v = Builder::mapping()
-    .entry("name", Builder::string("noyalib"))
-    .entry("port", Builder::integer(8080))
-    .build();
+let mut m = noyalib::Mapping::new();
+m.insert("name".into(), noyalib::Value::from("noyalib"));
+m.insert("port".into(), noyalib::Value::from(8080_i64));
+let v = noyalib::Value::Mapping(m);

For source-faithful edits (preserving comments and formatting), use noyalib::cst::Document instead — the programmatic Builder shape doesn’t track source bytes.

Behavioural differences worth knowing

1. #![forbid(unsafe_code)]. yaml-spanned transitively uses unsafe (via libyaml-safer). noyalib forbids it throughout the workspace; the migration tightens the safety claim.
2. Full YAML 1.2 surface. noyalib supports YAML 1.2 strict booleans, the JSON-compatible schema, custom tag handling via TagRegistry, anchor / alias resolution, and merge keys (<<) — all of which yaml-spanned either inherits from libyaml-safer or doesn’t expose.
3. Spans on the typed path. Spanned<T> is a serde wrapper, so it composes with any #[derive(serde::Deserialize)] target — not just the dynamic Value.
4. Comments preserved at the CST layer. noyalib::cst::Document::comments_at(path) returns the comments attached to a path; useful for round-trip-faithful editors / formatters / linters.
5. Built-in serialization. yaml-spanned is parser-only; noyalib provides to_string / to_writer / to_string_multi / to_writer_multi / to_fmt_writer for the full emit surface.

Drop-in compatibility shim

There’s no yaml-spanned-shaped shim because the surface is small. If you previously routed all your span work through yaml_spanned::Spanned<Value>, the noyalib equivalent is noyalib::Spanned<Value> — the same wrapper type at the same position in the type system.

Migration checklist

• Replace yaml_spanned = "0.0" → noyalib = "0.0".
• Replace use yaml_spanned::*; → use noyalib::*; plus use noyalib::Spanned; where you wrap span-bearing fields.
• Where you used Spanned<Value> for span+dynamic, prefer a typed config with Spanned<T> per field, or fall back to noyalib::cst::parse_document for path-based span queries.
• If you used from_str_lossy*, replace with explicit load_all(input)?.filter_map(...) — silent drops are rarely what production code wants.
• If you used Builder for programmatic construction, switch to Value::Mapping(...) / From<T> impls (or cst::Document for source-faithful edits).
• Add to_string / to_writer calls if the project previously paired yaml-spanned (read) with another crate (write) — noyalib covers both sides.
• Run your existing test suite.

If you hit a snag, file an issue at https://github.com/sebastienrousseau/noyalib/issues.

Migration Guide — noyalib workspace split

This guide covers what changed for consumers when the noyalib workspace was split into satellite repositories under ADR-0005. It’s aimed at:

• Rust developers who cargo add noyalib* or ship binaries that depend on the workspace.
• JavaScript / TypeScript developers using the WASM or MCP npm packages.
• DevOps running noyalib containers from GHCR.
• Downstream repo maintainers who vendored the monorepo via git submodule or path = "…".

If you’re only consuming published packages (crates.io, npm, GHCR), the short version is: no code changes required, just update version pins.

Split timeline

Strict-lockstep versioning: every satellite pins noyalib = "=X.Y.Z" matching the release tag. Satellites release simultaneously with the parent library.

For Rust library consumers

Consuming noyalib (the library core)

No changes. noyalib still lives in this repo and publishes to crates.io as before:

[dependencies]
noyalib = "0.0.58"

Consuming a satellite crate

Each satellite still publishes to crates.io under the same crate name. Only the source repository changed. Update your Cargo.toml version pin:

[dependencies]
noyalib-wasm = "0.0.58"   # crates.io; the repo does not matter to Cargo
noyalib-mcp  = "0.0.58"

The ADR-0005 strict-lockstep contract guarantees these versions move in lockstep with noyalib.

Filing issues + reading source

Point issue reports at the satellite repo, not this one:

• noyalib-wasm issues → https://github.com/sebastienrousseau/noyalib-wasm/issues
• noyalib-mcp issues → https://github.com/sebastienrousseau/noyalib-mcp/issues

Repository-scoped issue tracking keeps AI-agent framework maintainers’ bug reports on the MCP repo, browser-integration questions on the WASM repo, and library-parser concerns here.

For JavaScript / TypeScript consumers

@sebastienrousseau/noyalib-wasm (WASM bindings)

Available on npmjs.org. The npm scope changed from the pre-split plan of @noyalib (scope not registered) to @sebastienrousseau (auto-scoped to publisher). Package identity is stable from v0.0.12 onward.

npm install @sebastienrousseau/noyalib-wasm
# or
pnpm add @sebastienrousseau/noyalib-wasm

JavaScript API is unchanged. Import paths, function signatures, and TypeScript typings are byte-for-byte identical to what was shipped from the monorepo. See the satellite’s Quick Start.

@sebastienrousseau/noyalib-mcp (MCP server wrapper)

Available on npmjs.org.

npx @sebastienrousseau/noyalib-mcp

MCP tool inventory is unchanged. The server still exposes parse, format, get, set, validate with the same schemas and JSON-RPC wire format. Your Claude Desktop / Cursor / Continue.dev / Zed configs don’t need updating.

For DevOps consumers

Container images (GHCR)

• ghcr.io/sebastienrousseau/noyafmt — still ships from this monorepo.
• ghcr.io/sebastienrousseau/noyalib — still ships from this monorepo.
• ghcr.io/sebastienrousseau/noyalib-mcp — now ships from the satellite repo (image path unchanged; only the source repo changed).

All images are cosign keyless-signed. Verify against the split repo’s OIDC identity:

cosign verify \
    --certificate-identity-regexp 'https://github.com/sebastienrousseau/noyalib-mcp/' \
    --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
    ghcr.io/sebastienrousseau/noyalib-mcp:0.0.58

MCP Registry entry

io.github.sebastienrousseau/noyalib-mcp — identity unchanged, publisher moved to the split repo. AI-agent hosts (Claude Desktop, mcp.run, Glama) resolve the entry to the same ghcr.io/sebastienrousseau/noyalib-mcp image.

For downstream monorepo vendors

If you had a git submodule or path = "…" pointing at crates/noyalib-wasm/ or crates/noyalib-mcp/ in the monorepo, those paths no longer exist in the split releases (v0.0.12 onward). Migrate to one of:

Option A — pull from crates.io (recommended)

[dependencies]
noyalib-wasm = "=0.0.58"    # exact-match pins recommended
noyalib-mcp  = "=0.0.58"

Same version identity, same crate identity — only the source repo changed.

Option B — pull from the satellite git repo

[dependencies]
noyalib-wasm = { git = "https://github.com/sebastienrousseau/noyalib-wasm", tag = "v0.0.58" }
noyalib-mcp  = { git = "https://github.com/sebastienrousseau/noyalib-mcp",  tag = "v0.0.58" }

Option C — subtree-vendor the satellite

git subtree add --prefix=vendor/noyalib-wasm \
    https://github.com/sebastienrousseau/noyalib-wasm v0.0.58 --squash

If you were also depending on pkg/npm-mcp-wrapper/ or pkg/docker/Dockerfile.mcp, those moved to the satellite too — see the satellite’s pkg/ directory.

What did NOT change

• noyalib library crate: same identity, same public API, same MSRV (1.86, raised in v0.0.16). Any patch fix here still lands here.
• noyalib docs (docs.rs, GitHub Pages): unchanged.
• Sigstore verification recipes: unchanged (identity migrated to the split repos where applicable — see cosign snippets above).

Rollback

If any split turns out to be problematic during the 14-day soak review, the ADR-0005 rollback recipe restores the pre-split monorepo shape in ≤ 5 minutes of cargo compilation on a warm cache. Rollback yanks the satellite crate versions on crates.io so the monorepo re-takes precedence transparently for downstream users.

Questions?

• Rust library / core parser questions: file at https://github.com/sebastienrousseau/noyalib/issues
• WASM / browser / bundler questions: file at https://github.com/sebastienrousseau/noyalib-wasm/issues
• MCP / AI agent tooling questions: file at https://github.com/sebastienrousseau/noyalib-mcp/issues
• Security issues: email sebastian.rousseau@gmail.com — do not open a public issue.

noyalib architecture

The map a contributor (or a distro packager) needs to find their way around the codebase. Companion to USER-GUIDE.md (which covers the public API) and the per-module rustdoc on docs.rs.

Workspace layout

crates/
├── noyalib/              # the library — public API
│   ├── src/
│   │   ├── lib.rs        # public re-exports + module index
│   │   ├── parser/       # event-stream parser
│   │   ├── cst/          # lossless concrete-syntax tree
│   │   ├── streaming.rs  # zero-AST typed deserialise (hot path)
│   │   ├── de.rs         # AST-shaped deserialise (Value path)
│   │   ├── ser.rs        # serialiser
│   │   ├── diagnostic.rs  # renderer-neutral codes, severity, and byte spans
│   │   ├── value.rs      # 7-variant Value enum
│   │   ├── borrowed.rs   # zero-copy AST
│   │   ├── simd.rs       # find_any_of, SWAR decimals, structural-bitmask
│   │   └── …
│   ├── tests/            # integration tests + YAML 1.2 official suite
│   ├── examples/         # 76 runnable usage examples
│   └── benches/          # Criterion benches

The only workspace member is crates/noyalib (members = ["crates/noyalib"]). Crates that used to live under crates/ have been split into their own repositories per ADR-0005, and the xtask crate was removed:

• noya-cli (noyafmt + noyavalidate binaries) → sebastienrousseau/noya-cli (split at v0.0.13)
• noyalib-lsp (Language Server Protocol implementation) → sebastienrousseau/noyalib-lsp (split at v0.0.13)
• noyalib-mcp → sebastienrousseau/noyalib-mcp (split at v0.0.13)
• noyalib-wasm → sebastienrousseau/noyalib-wasm (split at v0.0.12)
• xtask (internal release tooling) → removed; PGO and release tasks now run from scripts/

The split satellite crates consume noyalib from crates.io via strict-lockstep =X.Y.Z version pins.

Errors cross integration boundaries through Error::diagnostic(). That method produces the canonical Diagnostic payload used by terminal renderers and editor protocols. Optional adapters translate the payload into miette or ariadne; satellites must not duplicate the error-variant mapping. Source labels remain UTF-8 byte spans until the protocol boundary, where adapters perform any required coordinate conversion.

The lib crate is #![forbid(unsafe_code)] workspace-wide. The satellite crates inherit the same forbid; only the third-party deps internally use unsafe (and Miri verifies the interaction is sound — see scripts/miri.sh).

End-to-end pipelines

There are two pipelines through the library, picked automatically based on the caller’s type:

                   ┌──────────────────────────────────────────────┐
                   │                                              │
   from_str::<T>   │   ┌───────┐   ┌────────┐   ┌──────────────┐  │
   (typed target) ─┼─► scanner├─► events ├─► StreamingDeser ├──┼─► T
                   │   └───────┘   └────────┘   └──────────────┘  │
                   │                                              │
   from_str::<Value>                                              │
   (dynamic) ─────►   scanner ──► events ──► loader ─────────────┼─► Value
                                                                 │
   parse_document                                                │
   (CST tooling) ─►   scanner ──► events ──► green-tree builder ─┼─► Document
                                                                 │
                                                                 ▼
                                                  to_string / to_writer / ser

The shared bottom of the funnel is the scanner (one implementation, byte-faithful). The shared middle is the event stream (a flat sequence of Event::Scalar, SequenceStart, MappingStart, etc.). What’s done with the events differs by caller intent.

Parser internals

Phase 1 — scanner

crates/noyalib/src/parser/scanner.rs. Walks the input one byte at a time, emits low-level tokens (indent / dedent / plain-scalar boundary / flow-open / flow-close / quote / anchor / alias / tag).

The hot path inside the scanner uses noyalib::simd:

• find_any_of — given a needle set {':', '\n', '#', …}, find the first byte in a window. Routes through:
  • memchr::memchr / memchr2 / memchr3 (SSE2 / NEON) for arity-1 / 2 / 3 needle sets — the most common shape.
  • SWAR (8-byte-stride u64 packing) for arity 4–8.
  • Scalar fall-back for everything else.
• StructuralIter (under --features simd) — walks 32-byte chunks and produces a bitmask of every delimiter position in one pass via mask.trailing_zeros(). Same shape as simdjson’s structural-character pass. Yields ~4× over the memchr loop on 1 MiB workloads (~9× on nightly under core::simd’s 32-byte vector).
• parse_decimal_u64 / parse_decimal_i64 — SIMD-Within- A-Register decimal parser. Folds 8 ASCII digits per u64 cycle via three pair-wise multiply-add phases; ~2× faster than <i64 as FromStr>::from_str on large numbers.

All unsafe-free — the SIMD primitives are pure-Rust SWAR or nightly core::simd; the SSE2 / NEON paths come from the memchr crate, which uses well-vetted unsafe internally.

Phase 2 — events

crates/noyalib/src/parser/events.rs. Reads the scanner’s tokens and emits semantic events. This is the YAML 1.2 spec’s production rule layer — handle <<: merge keys, anchor capture (&name), alias resolution (*name), tag handling (!foo, !!str).

Anchor expansion is bounded by max_alias_expansions in ParserConfig — the billion-laughs vector is mathematically impossible above the configured budget. The accumulator uses saturating_add so a crafted overflow input still trips the limit cleanly (no integer-wrap escape).

Phase 3a — typed streaming (the hot path)

crates/noyalib/src/streaming.rs. The default from_str::<T> path. Walks parser events directly into the typed target’s serde_core::de::Visitor interface — no intermediate Value AST is ever materialised.

This is the architectural difference from serde_yaml-shaped libraries, which always go event → AST → typed target. For the common case (deserialise into a struct), eliminating the AST saves ~one allocation per scalar plus the rebuild work.

The streaming path bakes in YAML 1.2 semantics:

• <<: *alias merges natively into the surrounding mapping.
• !!binary propagates as a typed tag.
• Custom tags surface via Value::Tagged (the streaming path routes through the AST loader for these — they’re rare enough that the overhead is acceptable).

Phase 3b — AST loader (for Value targets)

crates/noyalib/src/parser/loader.rs. Builds Value (the 7-variant enum: Null, Bool, Number, String, Sequence, Mapping, Tagged). Used by:

• Callers that explicitly ask for Value (from_str::<Value>).
• Callers that need parser policies (which run against the built Value, not the streaming pipeline).
• Callers that opt out of streaming via ParserConfig::ignore_binary_tag_for_string(true).

Value keys are interned via noyalib::interner::KeyInterner when the caller provides one — for Kubernetes-shaped streams (20-byte keys × 10 000 records) this drops memory footprint from ~200 KB of fresh allocations to ~20 B of strings + ~160 KB of Arc pointers.

Phase 3c — CST builder (for tooling)

crates/noyalib/src/cst/. The third path through events.

The CST is a side-table green tree. Each node carries:

• A kind tag (MappingNode, SequenceNode, Scalar, …).
• A byte span (start, end) into the original input.
• A list of child node indices.

Crucially, the original input bytes are kept alongside the tree. Document::to_string() is byte-identical to the input that produced it, because to_string() simply prints the original bytes back, sliced by the node boundaries.

Edits work by:

1. Resolving the edit path (server.port) to the byte span of the value to replace.
2. Replacing the bytes in that span only.
3. Rebuilding any green-tree nodes whose boundaries shift.

Step 3 is bounded by the size of the edit — neighbouring mappings / sequences / comments are completely untouched. This is the algorithmic distinction from “round-trip via AST” — that approach has to re-emit the entire document on every edit.

Foundation of the noyafmt (formatter) and noyavalidate --fix (schema-driven autofix) tools.

The Value tree

crates/noyalib/src/value.rs. The 7-variant enum:

#![allow(unused)]
fn main() {
use noyalib::{Mapping, Number, TaggedValue};
pub enum Value {
    Null,
    Bool(bool),
    Number(Number),
    String(String),
    Sequence(Vec<Value>),
    Mapping(Mapping),
    Tagged(Box<TaggedValue>),
}
// Not a copy of the real type — a check that every variant above still
// exists on it, so this sketch cannot drift unnoticed.
fn exhaustive(v: &noyalib::Value) -> &'static str {
    match v {
        noyalib::Value::Null => "Null",
        noyalib::Value::Bool(_) => "Bool",
        noyalib::Value::Number(_) => "Number",
        noyalib::Value::String(_) => "String",
        noyalib::Value::Sequence(_) => "Sequence",
        noyalib::Value::Mapping(_) => "Mapping",
        noyalib::Value::Tagged(_) => "Tagged",
    }
}
assert_eq!(exhaustive(&noyalib::Value::Null), "Null");
}

Mapping wraps IndexMap<String, Value> so iteration order matches insertion order (and source order, for parsed documents).

TaggedValue carries a Tag + an inner Value. Tags are interned strings; comparisons are byte-equal on the canonical form (!!str and tag:yaml.org,2002:str both compare equal).

Path queries (Value::query("items[*].name")) implement a small subset of the JSONPath grammar — wildcards (*), recursive descent (..), bracket-quoted keys (labels["app.kubernetes.io/name"], for a key the grammar would otherwise read as structure). The same grammar is behind every path-taking cst::Document method. See crates/noyalib/src/path.rs for the full grammar and the quote_key / push_key / join_keys spelling helpers.

Spans

crates/noyalib/src/spanned.rs. Spanned<T> is a transparent wrapper:

#![allow(unused)]
fn main() {
use noyalib::Location;
pub struct Spanned<T> {
    pub value: T,
    pub start: Location,
    pub end:   Location,
}
// The real type, with the same three fields reachable by name.
let s: noyalib::Spanned<u64> = noyalib::from_str("5")?;
let _: (u64, Location, Location) = (s.value, s.start, s.end);
// `Location`'s fields are private; these are the accessors.
let _ = (s.start.line(), s.start.column(), s.end.index());
}

Location carries (line, column, byte_offset) — 1-indexed lines and columns, 0-indexed bytes (matching rustc’s idioms).

Span tracking is thread-local; the AST loader fills a span map during parsing, then Spanned<T> deserialise reads from it during the typed-deserialise pass. Cleared between calls.

The thread-local is the reason Spanned<T> requires the std feature — no_std builds use the regular T directly.

Serialiser

crates/noyalib/src/ser.rs. Single-pass serde_core::Serializer that emits canonical YAML 1.2 output:

• Plain scalars when safe (no leading - / ? / : / , / flow-open characters, no special-form like null / true / numbers that could be misread).
• Double-quoted otherwise, with the YAML escape table.
• Block sequences and mappings (the default); flow form opt-in via FlowSeq<T> / FlowMap<T> newtypes from noyalib::fmt.
• Block scalars (|, >) when string content would otherwise span multiple lines, gated by block_scalar_threshold.

Emission is configurable via SerializerConfig:

#![allow(unused)]
fn main() {
use noyalib::SerializerConfig;
let cfg = SerializerConfig::new()
    .indent(4)
    .quote_all(true)
    .compact_list_indent(true)        // K8s-style lists
    .document_start(true);
let v: noyalib::Value = noyalib::from_str("a:\n  - 1\n")?;
let out = noyalib::to_string_value_with_config(&v, &cfg)?;
assert!(out.starts_with("---\n"), "document_start not applied: {out:?}");
}

Streaming deserialiser hot path

The streaming path is roughly:

// Shape only: `...` stands for the real visitor calls.
loop {
    match scanner.next_token()? {
        Token::MappingStart       => visitor.visit_map(...),
        Token::Scalar(text, kind) => visitor.visit_str(text)
                                     .or_else(... typed coercion ...),
        Token::SequenceStart      => visitor.visit_seq(...),
        // ...
    }
}

Coercion (e.g. plain scalar 8080 → u16 field) happens at the visit boundary. The plain-scalar resolver in crates/noyalib/src/streaming.rs is the YAML 1.2 schema-resolution table:

legacy_octal_numbers(true) opts into YAML 1.1’s bare-0 prefix; off by default because the modern 0o form is unambiguous.

Optional surfaces (v0.0.6)

Three v0.0.6 modules sit alongside the core pipeline; each is gated behind its own Cargo feature so the default build pays zero compile / binary-size cost for them.

All three are pure-safe Rust (preserving the workspace unsafe_code = "forbid" invariant) and exercised by unit tests inline, integration tests under crates/noyalib/tests/, and bench arms in crates/noyalib/benches/v006_features.rs.

Tests

Total: ~4100 tests. Runtime: ~110 s for cargo test --workspace --all-features --no-fail-fast on an M-series Mac.

Coverage

Workspace coverage is measured by cargo +nightly llvm-cov and gated in CI at 96 % functions / 94 % lines / 93 % regions. Excluded from instrumentation:

• subprocess-driven protocol smoke tests (the same logic is covered by per-module unit tests). These live in the split noyalib-mcp / noyalib-lsp repos per ADR-0005, so they are no longer part of this workspace’s instrumentation set.

(Prior to v0.0.12, crates/noyalib-wasm/src/lib.rs was also excluded — its JsValue marshalling requires the wasm-bindgen runtime, so it’s covered by wasm_bindgen_test invocations in the satellite repo at sebastienrousseau/noyalib-wasm per ADR-0005.)

Phase 7 of PLAN.md ratchets these gates to 98 / 98 / 98.

Miri

scripts/miri.sh runs Miri on the high-leverage modules (parser::, scanner::, value::, interner::, simd::) and verifies the interaction between noyalib (which is #![forbid(unsafe_code)]) and the runtime deps (indexmap, rustc-hash, ryu, itoa, memchr, smallvec — all of which use unsafe internally) is sound.

The full lib test suite runs under Miri on a weekly schedule (miri-full job in ci.yml); the focused subset runs per-PR.

-Zmiri-symbolic-alignment-check is intentionally not enabled because memchr’s x86_64 SSE2 path triggers a known false positive in _mm_load_si128 on dynamically-aligned pointers. The other defaults — Stacked Borrows, leak detection, uninit-memory checks, OOB checks — are on.

Cross-platform

The SWAR pipelines and the core::simd structural-bitmask path are byte-order agnostic. u64::from_be_bytes + wrapping_mul arithmetic produce the same results on big-endian targets; verified via MIRI_TARGET=mips64-unknown-linux-gnuabi64 runs in the weekly Miri-full job.

Where to read next

• Public API: USER-GUIDE.md
• Migration: MIGRATION-FROM-SERDE-YAML.md
• Distribution / packaging: ../pkg/PUBLISH.md
• Verifying release artefacts: ../pkg/VERIFY.md
• Design notes (historical): design/
• Releases / phase work plan: PLAN.md

Green Tree — Side-Table CST for Round-Tripping Edits

Status: design proposal · Author: Sebastien Rousseau (with Claude assistance) · Last updated: 2026-04-30

TL;DR

Add a second, parallel parse output: an immutable byte-faithful green tree that retains every byte of the source — content, whitespace, comments, line breaks, indentation. Keep Value and the StreamingDeserializer exactly as they are. Expose the green tree through a new Document type whose mutation API rewrites the tree structurally, then re-emits the modified tree byte-for-byte where untouched and minimally where edited.

This is the architecture popularised by rowan (rust-analyzer) and taplo (TOML). It is the pragmatic alternative to a unified CST, which would tax every consumer who only wants from_str::<MyType>(…).

Goals

1. 100% lossless round-trip when nothing is edited. parse → emit is byte-identical for any well-formed input.
2. Local minimal diffs on edit. Mutating one scalar rewrites only the bytes for that scalar; surrounding indentation, comments, blank lines, and other-key content are preserved verbatim.
3. Zero performance impact on the existing fast path. Users who call from_str::<T> or StreamingDeserializer see no change in compile-time size, runtime allocation, or throughput.
4. One source of truth for parsing. The green tree builds from the same scanner token stream that already feeds Value — no second parser, no divergence.
5. Stable foundation for ongoing strictness fixes. Indentation rigor, document hygiene, and other lenient-cluster fixes target the existing scanner/loader; the green tree retrofit must not require redoing them.

Non-goals

• Replacing Value. Value remains the data API for serde-style use.
• Comment attachment semantics (which comment “belongs” to which node). The capture surface in src/comments.rs is sufficient for most consumers; node-attached comments can be a follow-up.
• Cross-document editing. Document is single-document; multi-doc streams are a Vec<Document> (see API).
• Schema-aware editing (e.g. “set the value of version to a string even if it parses as a number”). Caller’s responsibility to provide the right fragment.

What already exists

The retrofit lands on top of substantial infrastructure that this crate already carries:

The header comment in src/comments.rs:24-27 already anticipated this work:

The building blocks are here: the scanner now preserves comment spans, so a future commit can layer an AST side-table on top without re-plumbing the parser.

That commit is what this document specifies.

Architecture

Two trees, one parse

                                    ┌─────────────────────────┐
                                    │   StreamingDeserializer │  ← unchanged
                                    └─────────────────────────┘
                                                 ▲
            ┌──── tokens ────┬──── events ───────┴── (no value built)
            │                │
       ┌────┴────┐       ┌───┴────────┐
       │ Scanner │ ────▶ │ EventStream│
       └────┬────┘       └───┬────────┘
            │                │
            └──── events ────┼─────▶ ┌────────────────┐
                             │       │ value::Loader  │  ── Value
                             │       └────────────────┘
                             └─────▶ ┌────────────────┐
                                     │  cst::Builder  │  ── GreenNode (Arc)
                                     └────────────────┘            │
                                                                   ▼
                                                         ┌──────────────────┐
                                                         │     Document     │
                                                         │   (mutable API)  │
                                                         └──────────────────┘

• Value and GreenNode are independent products of the same parse. Either can be built alone (cheap path) or both together (CST path) at minimal extra cost.
• The scanner runs once. Token spans are reused.
• Mutation happens on Document, never on Value directly.

Green tree shape

The green tree is a rowan-style untyped, immutable tree where every node either:

• Holds source text directly (a leaf Token), or
• Holds a sequence of child green nodes plus the syntax kind.

Critically, leaves include trivia — whitespace runs, newlines, indentation runs, comments — not just content tokens. The concatenation of every leaf’s text in document order reproduces the input byte-for-byte.

Sketch of the core types (lives in a new src/cst/ module):

// src/cst/mod.rs

/// Kind of a syntax node or token.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum SyntaxKind {
    // ── trivia (leaves only) ────────────────────────
    Whitespace,
    Newline,
    Comment,
    // ── structural punctuation (leaves) ─────────────
    DashIndicator,        // `-`
    QuestionIndicator,    // `?`
    ColonIndicator,       // `:`
    AnchorMark,           // `&name`
    AliasMark,            // `*name`
    TagMark,              // `!tag`
    DocStart,             // `---`
    DocEnd,               // `...`
    // ── scalar leaves ───────────────────────────────
    PlainScalar,
    SingleQuotedScalar,
    DoubleQuotedScalar,
    LiteralScalar,
    FoldedScalar,
    // ── composite nodes ─────────────────────────────
    Document,
    BlockMapping,
    BlockSequence,
    FlowMapping,
    FlowSequence,
    BlockMappingEntry,    // `key: value` (with surrounding trivia)
    FlowMappingEntry,
    BlockSequenceEntry,   // `- value` (with surrounding trivia)
    FlowSequenceEntry,
    Key,                  // wraps the key node + the `:`
    Value,                // wraps the value node
}

/// Immutable green node — `Arc`-shared, byte-faithful.
#[derive(Debug, Clone)]
pub struct GreenNode {
    kind: SyntaxKind,
    text_len: usize,            // total byte length, cached
    children: Arc<[GreenChild]>,
}

#[derive(Debug, Clone)]
enum GreenChild {
    Node(GreenNode),
    Token { kind: SyntaxKind, text: Box<str> },
}

impl GreenNode {
    pub fn kind(&self) -> SyntaxKind { self.kind }
    pub fn text_len(&self) -> usize { self.text_len }
    pub fn children(&self) -> impl Iterator<Item = &GreenChild>;
    /// Concatenation of every descendant token's text in document
    /// order. For an unmutated tree, equals the original input.
    pub fn text(&self) -> String;
}

The “red” side is implicit: a SyntaxNode cursor that walks the green tree and tracks parent pointers and absolute byte offsets on demand. Following rowan, this is computed lazily — not stored. We do not need a separate RedNode type; cursors satisfy the typed-API requirement.

Public API

A new top-level Document type sits on top of the green tree:

// src/cst/document.rs (new file)

/// A YAML document with byte-faithful source preservation.
///
/// Parses input and retains every byte — content, whitespace,
/// comments — so that an unmodified `Document` re-emits identical
/// bytes. Edits rewrite only the affected fragment; surrounding text
/// is preserved verbatim.
///
/// Multi-document streams are returned as `Vec<Document>` from
/// [`parse_stream`].
#[derive(Debug, Clone)]
pub struct Document {
    green: GreenNode,
    /// Cached byte buffer; invalidated on edit.
    cached_emit: OnceLock<String>,
}

/// Parse a single-document YAML string into an editable `Document`.
pub fn parse_document(input: &str) -> Result<Document>;

/// Parse a multi-document stream.
pub fn parse_stream(input: &str) -> Result<Vec<Document>>;

impl Document {
    /// The root syntax node.
    pub fn syntax(&self) -> SyntaxNode<'_>;

    /// Re-emit the document. Byte-identical to the original input
    /// when no edits have been applied.
    pub fn to_string(&self) -> String;

    // ── Typed read-only access ──────────────────────────────────
    pub fn as_value(&self) -> Value;          // one-shot conversion

    // ── Typed mutation (Renovate-class) ─────────────────────────
    pub fn get(&self, path: impl AsPath) -> Option<NodeRef<'_>>;
    pub fn set(&mut self, path: impl AsPath, value: impl Emit);
    pub fn remove(&mut self, path: impl AsPath);

    // ── Span-based mutation (linter/formatter-class) ────────────
    /// Replace the bytes at `span` with `text`. The caller is
    /// responsible for the replacement being syntactically valid in
    /// that position; `Document` re-validates the result before
    /// committing.
    pub fn replace_span(&mut self, span: Span, text: &str)
        -> Result<(), EditError>;
}

/// Path into a YAML document — `JsonPath`-style.
pub trait AsPath { /* "/foo/bar/0" or [Segment::Key("foo"), …] */ }

/// Source for a value being inserted. Implementations exist for
/// `&str`, `i64`, `f64`, `bool`, `Value`, and any `Serialize` type.
/// The `Document` formats the new value to match the existing scalar
/// style at the target site (literal/folded/plain/quoted) wherever
/// possible, and otherwise emits the simplest valid form.
pub trait Emit { fn emit(&self, ctx: EmitCtx<'_>) -> String; }

Four design decisions

1. Separate parse entry point — yes

parse_document(input) is a new top-level function alongside from_str / from_slice / load_all. We do not add a Value::with_trivia() constructor; Value does not gain a hidden green-tree field. This keeps the fast path’s type signature unchanged and its size and layout untouched, and prevents accidental opt-in (an Emit of a Value from parse_document is unambiguous; an Emit of a Value from from_str is impossible at the type-system level).

Trade-off: callers who want CST behaviour must opt in explicitly. We think that is the correct default.

2. Both typed and span-based mutation

• Typed (get / set / remove) is the headline API. It is what Renovate-class consumers want: “set the version at dependencies.serde to 2.0.”
• Span-based (replace_span) is the formatter / linter API. Users who already operate on spans (e.g. consumers of Spanned<T>) get a low-level escape hatch.

Both paths converge on the same green-tree rewrite logic. set is implemented as replace_span(node.span(), formatted).

3. Re-emission policy: leave indentation alone

When set replaces a value, the surrounding indentation, comments, and blank lines are preserved verbatim. We do not re-indent a sibling block when one entry’s value changes shape, even if the result is “ugly” by a hand-written style.

This matches taplo’s policy. Aggressive reformatting is out-of-scope for Document; consumers who want it run their own formatter.

The one exception: when set introduces a multi-line value where a single-line value lived (e.g. a literal block scalar replacing a plain scalar), Document indents the new lines to match the entry’s existing column.

4. Anchor / alias under mutation

If an edit targets a node that has an anchor or is the target of an alias elsewhere in the document:

• Edit a node with an anchor → keep the anchor, change the content. Aliases continue to refer to the (now-different) node.
• Edit a node that is aliased elsewhere (the alias resolves to it) → emit a warning; the alias now resolves to a different value. This is allowed by default. A strict mode (Document::strict_aliases) errors instead.
• Edit an alias node (*foo) directly → forbidden. set on an alias returns EditError::AliasNotEditable. To change the value the alias points to, mutate the anchored node.

This is the area where most “CST for YAML” projects accumulate scars; conservative defaults plus an opt-in strict mode is the only position that has held up in practice (see serde_yaml’s and yaml-rust2’s issues archives).

Migration plan

Phased; each phase is releasable and independently useful.

Phase 0 — design lock-in

This document. No code changes.

Phase 1 — green-tree builder

• New src/cst/ module: SyntaxKind, GreenNode, GreenChild, SyntaxNode, Builder.
• The builder consumes the existing Event stream from src/parser/events.rs plus the un-skipped trivia from the scanner (ScannedComment plus a new internal trivia capture for whitespace and newlines, which are currently elided by skip_to_next_token but whose spans are easy to retain).
• New API: parse_document(input) -> Result<Document> and parse_stream(input) -> Result<Vec<Document>>. Read-only initially: no set or replace_span yet.
• New test: tests/cst/round_trip.rs — for a corpus of inputs (existing tests/yaml-test-suite/ cases), assert parse_document(s).unwrap().to_string() == s.
• Acceptance criterion: 100% byte-identical re-emit on every test suite case the existing parser accepts.

Phase 2 — typed mutation

• Document::get / set / remove and the AsPath / Emit traits.
• tests/cst/mutation.rs — for each of N curated cases, apply a named edit, check the resulting to_string() against a golden file under tests/cst/golden/.

Phase 3 — span-based mutation + edit validation

• Document::replace_span. Re-validates by re-parsing the resulting text and checking that the affected node still parses to a syntactically valid scalar/collection.
• EditError type with the alias / multi-line / shape-mismatch variants.

Phase 4 — round-trip strictness fixes

The remaining 41 lenient cases (indentation rigor, document hygiene, implicit-key multi-line) are now revisited. The strictness fixes land at the scanner / loader level — the green-tree builder inherits them automatically. There is no green-tree-specific strictness work.

This phase only follows phases 1–3 because some of the remaining strictness fixes (notably indentation rigor) require richer trivia tracking that the green-tree builder will already need. We land the trivia capture once.

Performance contract

Phase 1’s introduction of green-tree construction must not slow down existing entry points. The verification is two-fold:

• The criterion benches under benches/ (benchmarks, comparison, architecture, validation_overhead) gate at ±5% against main. CI fails on regression.
• The parse_document path is benchmarked separately. Its overhead vs from_str::<Value> should be ≤2× — comparable to taplo’s ratio. The streaming path stays the undisputed champion for from_str::<MyType> use.

Open questions

• YAML 1.1 vs 1.2 directive handling. The spec is loose on preserving directive text across a round-trip. Decision needed: does parse_document → set → to_string preserve the original %YAML 1.2 directive byte-for-byte, or canonicalise it? Default proposal: preserve verbatim (consistent with the indentation policy).
• Preserving non-canonical scalar styles. A plain 42 and a quoted "42" deserialise to the same Value, but their CST representations differ. set(path, 42) on a quoted-style site should emit "42", not 42. Decision: yes — Emit carries an EmitCtx that knows the existing style at the target.
• Does Document implement serde::Deserialize? Probably not — forces consumers through Document::as_value() which is the intended boundary. But Document::as_value() should be cheap; the green tree already has all the data.
• Memory layout. GreenChild::Token { text: Box<str> } allocates per leaf. For very large documents (k8s-class manifests), an arena may be worth the complexity. Defer to phase 1 measurements.

Test / regression strategy

• Round-trip property test. Every yaml-test-suite case that parses must round-trip byte-identically. Wired into tests/yaml_compliance_report.rs’s existing infrastructure.
• Golden mutation tests. Per phase 2 above; cargo test --test cst_mutation -- --bless to regenerate.
• Fuzz harness. Extend the existing fuzz/ corpus with a green-tree round-trip target — for any input the parser accepts, parse_document → to_string → parse_document → to_string must be a fixed point.
• Anchor/alias scar tests. A dedicated test file in tests/cst/anchors.rs for the four scenarios in §4.

What this design explicitly avoids

• rowan as a hard dependency. We replicate the green-node pattern directly. rowan is excellent but pulls in text-size, countme, and friends; the implementation here is small enough (≤500 LoC) that the dependency cost is not justified for a YAML parser. If we need the typed-syntax-tree generator later, we can reconsider.
• A second tokenizer. The green tree is built from the same scanner output that already feeds Value. Strictness fixes in the scanner improve both immediately and stay improved.
• Implicit fallback to lenient parsing on edit. If replace_span produces invalid YAML, the edit is rejected with EditError. Document never silently emits invalid output.

References

• rowan (rust-analyzer) — green-tree pattern.
• taplo (TOML) — single-document edit-aware API; closest analogue in the broader ecosystem.
• YAML 1.2.2 §6 – §9 — production rules informing the green-tree granularity.
• tests/yaml-test-suite/ — round-trip corpus.

THE ARCHITECT ᛫ Sebastien Rousseau ᛫ https://sebastienrousseau.com THE ENGINE ᛞ EUXIS ᛫ Enterprise Unified Execution Intelligence System ᛫ https://euxis.co

Ecosystem dependency graph

The shape of repository-to-repository dependencies across the noyalib ecosystem. The arrows read “depends on”. Each satellite is released from its own repository; the core workspace contains only noyalib.

graph TD
    noyalib["noyalib<br/>core library<br/>MSRV 1.89"]

    noya_cli["noya-cli<br/>noyafmt + noyavalidate<br/>MSRV 1.89"]
    noyalib_lsp["noyalib-lsp<br/>LSP server<br/>MSRV 1.89"]
    noyalib_mcp["noyalib-mcp<br/>MCP server<br/>MSRV 1.89"]
    noyalib_wasm["noyalib-wasm<br/>WASM bindings<br/>MSRV 1.89"]
    noyalib_serde_yaml["noyalib-serde-yaml<br/>compatibility package<br/>MSRV 1.89"]

    noya_cli --> noyalib
    noyalib_lsp --> noyalib
    noyalib_mcp --> noyalib
    noyalib_wasm --> noyalib
    noyalib_serde_yaml --> noyalib

    classDef core fill:#1f6feb,stroke:#0d419d,color:#fff
    classDef satellite fill:#3fb950,stroke:#1f6f3a,color:#fff
    class noyalib core
    class noya_cli,noyalib_lsp,noyalib_mcp,noyalib_wasm,noyalib_serde_yaml satellite

Reading the graph

noyalib is the only repository with no ecosystem dependencies. It is the root of the graph. Every satellite sits downstream of it. This is enforced architecturally: noyalib cannot import from noya-cli, noyalib-lsp, etc., even via tests.

Satellite crates (noya-cli, noyalib-lsp, noyalib-mcp, noyalib-wasm, noyalib-serde-yaml) depend only on noyalib. They never depend on each other, even when their feature surface overlaps. The MCP server and the LSP server, for instance, both implement format and parse operations, but each does so by calling noyalib::cst::format directly — neither imports from the other. This keeps the per-crate dependency footprint minimal and the integration tests independent.

There is no xtask crate. It was the build-tooling crate (it provided the completions and manpages subcommands) and was retired with the workspace split (#134): man pages and shell completions belong to noya-cli, which generates them in its own repository. What remains here runs from Makefile targets (make sbom, make notice, make vendor) and scripts/.

MSRV (single lockstep floor)

CI’s Per-crate MSRV job still enforces the floor per crate — it reads each crates/*/Cargo.toml’s rust-version and compiles against exactly that — so a satellite adopting a higher floor cannot silently drag the core up with it. The mechanism that kept the floors independent is intact; what changed in v0.0.16 is only the numbers it reads.

As of v0.0.58 every crate declares 1.89.0, by decision (ADR-0014) rather than by toolchain need. The toolchain-driven floor is 1.86, set by criterion 0.8, a dev-dependency: with rust-version temporarily set to 1.85, cargo +1.85.0 check --lib compiles cleanly but cargo +1.85.0 check --all-targets fails with criterion@0.8.2 requires rustc 1.86. So no test, bench or coverage run can execute below 1.86, and the project publishes the floor it verifies rather than the lower one the library alone would reach.

No runtime dependency of the core crate requires 1.86 — the highest runtime floor in the tree is 1.85. The earlier claim that validate-schema’s ICU chain forced 1.86 was an artefact of a lockfile refresh that did not ship; see CHANGELOG.md for v0.0.16.

External dependency surface

Dependency counts change with lockfile and feature resolution, so this page does not copy a hand-maintained table. The weekly ecosystem scorecard records the current runtime closure for all six repositories; use docs/ECOSYSTEM.md for that evidence.

Generating this graph

To inspect the core workspace graph:

cargo depgraph --workspace-only --dedup-transitive-deps | dot -Tsvg > /tmp/deps.svg

The cross-repository Mermaid graph is maintained from the repository list used by scripts/ecosystem-scorecard.sh. When that list changes, update this file and docs/ARCHITECTURE.md.

Testing strategy

noyalib’s test pyramid is unusually wide for a library of its size. This document explains why — what each layer catches, where it runs, and how to extend it.

The five layers

graph TD
    A[Doctests<br/>~384] --> B[Unit tests<br/>inline #[cfg(test)]]
    B --> C[Integration tests<br/>tests/*.rs · 139 files]
    C --> D[Property + proptest]
    D --> E[Fuzz · libfuzzer<br/>10 targets]
    F[Miri · UB detection] -.parallel.-> C
    G[Bench · Criterion<br/>16 harnesses] -.parallel.-> C
    H[Spec compliance<br/>406/406 strict yaml-test-suite] -.parallel.-> C

Each layer catches a different bug class. None replaces another — they compose.

Doctests (~384)

Every public item carries a runnable example in its docstring. The noyalib README is also wired into the doctest sweep via:

// `include_str!` resolves relative to the file it appears in, so this
// only compiles inside the crate it documents.
#[cfg(doctest)]
#[doc = include_str!("../README.md")]
mod readme_doctests {}

So every ```rust block in the README is exercised on every PR. This catches API drift in code samples — a frequent rot vector in libraries with marketing-grade READMEs.

Run: cargo test --doc -p noyalib --all-features

Unit tests

Co-located with implementation in #[cfg(test)] mod tests blocks. Used for tightly-scoped invariants — encoding tables, scanner state machines, format-config heuristics. Not the place for end-to-end flows; those live in tests/.

Integration tests (139 files in crates/noyalib/tests/)

Each file is a focused theme. Selection of the most load-bearing:

Run: cargo test --workspace --all-features

Property + proptest

proptest generates structured YAML inputs to assert universal properties — parse(emit(value)) == value, parse(format(s)) is total over valid YAML, etc. Catches edge cases that case-by-case tests miss because the input space is hostile in shape, not just content.

Fuzz (10 targets, libfuzzer)

Located in fuzz/fuzz_targets/:

CI runs a 10-second smoke pass per PR via the Differential fuzz job. Long-form pre-release fuzz runs are operator-driven.

Run a 30-second smoke locally:

cargo +nightly fuzz run fuzz_parse -- -max_total_time=30 -timeout=5

The fuzz pass for v0.0.1 caught one pre-existing scanner panic (scanner.rs:1644 — slice index starts at 2 but ends at 0 on adversarial implicit-key tracking) that the existing corpus had never triggered. Both crashing inputs are now locked in scanner_panic_regressions.rs.

Miri (UB detection)

cargo +nightly miri test runs the entire suite under the Miri interpreter, which catches undefined behaviour stdlib usage that ordinary tests miss — uninitialised reads, out-of-bounds aliasing, strict-provenance violations.

The workspace forbids unsafe_code so noyalib’s own code can’t introduce UB. Miri is therefore catching deps’ problems reachable from noyalib’s code. It has caught memchr SSE2 false positives on -Zmiri-symbolic-alignment-check (which is now disabled in scripts/miri.sh) and would catch any future regression in indexmap’s iteration invariants or serde’s borrow lifetime plumbing.

CI runs a focused Miri pass per PR (60-min timeout) and a full Miri + big-endian sweep on schedule.

Run: ./scripts/miri.sh

Benchmarks (16 Criterion harnesses)

Performance is treated as a correctness invariant — regressions are bugs the same way wrong output is. Per-crate harnesses:

CI runs the comparison + microbench suites via CodSpeed on every PR (the CodSpeed perf dashboard workflow); regressions block merge.

Run: cargo bench --workspace

Spec compliance: 406/406 strict

The yaml-test-suite is the canonical 1.2 conformance corpus. noyalib’s compliance harness reports 406/406 strict-pass, 0 failures, and 0 skips out of 406 total cases (each case directory yields one or more variant assertions; the totals reflect those variant counts). The full breakdown rebuilds on every CI run into target/yaml-compliance-report.md.

The strict-pass set is locked by tests/official_suite.rs so a regression — any case dropping from pass to skip / fail — fails CI immediately. Each new correctness fix lands with the corresponding suite case unblocked.

Coverage gate

CI’s Coverage gate (≥96%) job runs cargo +nightly llvm-cov across the workspace and fails under:

• --fail-under-functions 96 — every public/private fn
• --fail-under-lines 94 — line coverage
• --fail-under-regions 93 — region (branch) coverage

Excluded from the report: noyalib-wasm/src/lib.rs (JsValue marshalling needs a wasm-bindgen runtime; covered separately by wasm_bindgen_test under wasm-pack test) and the protocol.rs end-to-end subprocess tests in MCP/LSP (don’t run cleanly under llvm-cov instrumentation; the same logic is covered by per-module unit tests).

Adding a test

Match the layer to the bug class:

Every new public surface ships with new tests in the same commit / PR — never as a follow-up. This invariant is in CONTRIBUTING.md and enforced socially in review.

noyalib — Engineering Policies

This document is the single source of truth for noyalib’s engineering posture: MSRV, SemVer, security audits, performance guarantees, concurrency, platform support, and the feature-flag matrix. Every README in the workspace links here; if there’s a contradiction between this file and a per-crate README, this file wins.

Last reviewed: 2026-07-22. The dates on individual sections capture when each policy was last audited.

Contents

1. MSRV (Minimum Supported Rust Version)
2. SemVer & API stability
3. Security & audits
4. Performance & algorithmic complexity
5. Concurrency guarantees
6. Platform support
7. Feature-flag matrix
8. Panic policy
9. Error model
10. Dependency policy
11. Release & changelog policy

1. MSRV (Minimum Supported Rust Version)

What the MSRV number means here. It is the lowest toolchain on which the project can be built and tested, not the lowest on which the library alone happens to compile. Those differed at the 1.86.0 floor: cargo +1.85.0 check --lib succeeds, but cargo +1.85.0 check --all-targets fails with criterion@0.8.2 requires rustc 1.86. We publish the number we verify. Advertising 1.85 would be an untested promise — no CI leg could run there, so nothing would catch the day it broke.

When we bump it. Only when the toolchain we build and test at actually moves — a dependency (runtime or dev) raising its floor, or a language feature we choose to adopt. Never speculatively, and never for tidiness. “Headroom” is not a reason: an MSRV can be raised the day it is needed, and raising it early only costs downstream users. The one exception is the v0.0.58 raise to 1.89.0, a maintainer decision to share one floor with his other Rust crates, recorded in ADR-0014. As a standing guarantee, noyalib will not require a rustc newer than 12 months old at the time of release (1.89.0 shipped 2025-08-07, so the current floor is comfortably inside that).

How it ships (revised 2026-07-22, effective v0.0.16): while the project is in its 0.0.x line, an MSRV bump — core or satellite — ships as a patch (0.0.x → 0.0.x+1), in lockstep across all five crates. It must be called out in CHANGELOG.md under an explicit ### Changed — MSRV heading so consumers can find it by scanning, and the new floor must be reflected in the table above, which is the single source of truth.

This supersedes the previous rule that a core MSRV bump was a minor-version event. That rule was written when 0.1.0 was the next planned cut; under the current 0.0.x posture there is no minor slot to spend, and SUPPORT.md already warns that a patch may carry breaking changes in 0.x. Treating MSRV bumps as patches keeps the version line monotonic and honest rather than reserving a semantic that the 0.0.x scheme cannot express. This changes at 1.0: once the crate is 1.x, an MSRV bump becomes a genuine minor-version event again, per the 1.0 gates in PLAN.md.

CI matrix verifies the MSRV per-crate via the Per-crate MSRV workflow job — no change to that job is required when a downstream crate updates its dependency floor; the workflow reads rust-version from each Cargo.toml.

2. SemVer & API stability

noyalib follows SemVer 2.0.0 strictly, with one well-defined exception below.

What constitutes a breaking change

A change is breaking (requires a major-version bump under 1.0+, or a minor-version bump on the 0.x line) if it:

• Removes or renames a publicly exported item (function, type, trait, const, enum variant, module).
• Changes the signature of a publicly exported function or trait method (excluding broadening the bound, which is non-breaking).
• Changes the layout of a publicly exported struct in a way that breaks pattern-match exhaustiveness (adds a non-#[non_exhaustive] variant or field).
• Changes the default behaviour of a parser / serializer (e.g., flips YAML 1.1 ↔ 1.2 boolean recognition).
• Removes a feature flag or changes a feature’s set of enabled deps.

What is not a breaking change

• Adding a new public item.
• Adding a new variant to a #[non_exhaustive] enum.
• Adding a new field to a #[non_exhaustive] struct.
• Tightening a parser to reject input it previously accepted as long as that input was malformed YAML 1.2 (not in the test suite’s accept-set). Such changes are noted in the changelog under “Stricter rejection”.
• Tightening a deserializer to reject input that was previously coerced (e.g., from_str_strict). The strict path is opt-in.
• Performance, code-size, or compile-time changes that preserve the observable contract.

Pre-1.0 (current state — 0.0.x)

While on the 0.0.x line, every release may be breaking per SemVer’s pre-1.0 carve-out — Cargo treats each 0.0.x as its own incompatible version, so the patch position is the only one that moves (see the MSRV bump policy in §1, which follows from this). We try to avoid breakage anyway; the cargo-semver-checks CI gate catches accidental breaks. The 0.0.x line is intentionally narrow: we expect to ship a single big-bang 0.0.1, then iterate 0.0.2, 0.0.3, … through 0.0.999, then graduate to 0.1.0 for the first genuinely stable release.

Compatibility tooling

• cargo-semver-checks: runs in CI on every PR; fails the build on detected breaks.
• #[non_exhaustive] is applied to every config struct (ParserConfig, SerializerConfig) so adding fields is always non-breaking.
• MSRV stability: see §1 above.

3. Security & audits

Reference: SECURITY.md at the repo root.

Compile-time safety

• #![forbid(unsafe_code)] at the workspace level. The lint applies to every crate in crates/. Verified by Rust CI / Check & Test on every PR.
• No C dependencies, no FFI calls. No libyaml, no libc, no transitively-unsafe parser. The runtime deps that do use unsafe (indexmap, rustc-hash, ryu, itoa, memchr, smallvec) are checked under Miri on every PR (focused) and weekly (full + big-endian).
• No network I/O and no filesystem writes from the library itself, and no environment-variable reads at run time (the build script reads RUSTC and NOYALIB_COVERAGE). The library reads files only when asked to: SafeFileResolver (include_fs) under its root, and the figment provider’s Yaml::file and Yaml::file_with_config. JSON Schema $ref never resolves outside the schema document. The noya-cli binaries read and write files.

Resource-limit gates

The parser has explicit DoS guards. Defaults are conservative; override via ParserConfig.

The corresponding regression tests live in tests/stress_load.rs.

v0.0.6 opt-in surface limits

The recovery, tokio, and sval modules (each behind its own Cargo feature) add their own DoS-resistance posture on top of the shared parser limits:

• recovery::parse_lenient rejects a ----marker scan beyond ParserConfig::max_documents to defeat marker-spam inputs, and caps the cumulative line-truncation-retry cost at LenientConfig::truncation_event_budget (default 1 MiB) to defeat O(n²) re-parse on 10k-line adversarial documents.
• tokio_async::from_async_reader{,_multi}{,_with_config} probe one byte beyond max_document_length for a single document or max_stream_bytes for a stream. Oversized input is rejected, never parsed as a truncated prefix. A leading UTF-8 BOM is stripped so Windows-saved buffers round-trip identically to LF-on-Linux equivalents.
• tokio_async::YamlDecoder exposes max_frame_size(usize): when the inter-frame BytesMut holds an incomplete document beyond the cap, the next decode call returns Error::Io(InvalidData) rather than letting an adversarial producer pin memory by streaming without ---. Constructors derive the cap from ParserConfig::max_document_length; callers may tighten it, and max_document_length caps a frame whatever max_frame_size says. Multiple complete documents already present in one read are measured independently rather than rejected by their aggregate buffered size. The boundary scan resumes where the previous decode stopped, so a frame arriving in many small reads is scanned once, not once per read.
• sval_adapter forwards non-finite floats verbatim by default; use to_sval_writer_with_config with SvalConfig::coerce_non_finite_to_null to emit Null instead, required for downstreams like sval_json that reject NaN / ±∞.

max_depth guard correctness (fixed in v0.0.6 / issue #46)

The max_depth limit above relies on balanced increment / decrement of self.depth along every code path. Two correctness bugs that made the guard either over- or under-count were patched in v0.0.6:

• Over-count, false-positive. StreamingMapAccess’s iterators did not check the access object’s finished flag. Serde visitors that called next_entry after Ok(None) — ValueVisitor::visit_map does this — re-entered the iterator, read the next event from the parent mapping, and treated it as the inner exhausted child’s. The recursive deserialize_any on each spilled value inflated self.depth by one per empty flow {}, so a pnpm-lock.yaml-shaped input with N consecutive {} hit the limit at exactly N = max_depth. Fixed: explicit if self.finished { return Ok(None) } guards on the three iterators; balanced decrement on Ok and Err in deserialize_any / _seq / _map.
• Under-count, silent bypass. The NoSpanLoader path (value-target fast path, no_std multi-document loading) incremented self.depth on SequenceStart / MappingStart but did not compare against max_depth. Adversarial deeply-nested input through that path could consume stack without ever firing the documented guard. Fixed: mirror the span loader’s check.

Regression suite: crates/noyalib/tests/issue_46.rs — 10 tests including a 50 000-package full pnpm-lock-v9 shape, 3 000 consecutive empty flow mappings, deterministic depth-cliff probe at n ∈ [100, 128, 129, 130, 200, 500, 1000], and a 200-level-deep sequence for the no-span path.

Audit pipeline

Each PR runs:

• cargo audit (RustSec advisory DB).
• cargo deny (allow / deny / skip rules; SPDX licence whitelisting via deny.toml).
• cargo vet (vetted-deps register at supply-chain/).
• cargo semver-checks (API break detection).
• CodeQL (GitHub-native static analysis).
• Differential fuzz (10 s smoke run, comparing noyalib against serde_yaml_ng / yaml-rust2 for divergent acceptance behaviour).
• Miri (focused) — verifies the supply-chain unsafe interaction surface is sound.

Weekly (or on-demand) jobs:

• Soak fuzz (per-target).
• Soak Miri (full suite + big-endian via mips64 cross).

Supply-chain provenance

• All releases on crates.io carry npm-provenance-style attestations when published from CI (cosign keyless via the GitHub Actions OIDC issuer).
• Verification recipe in pkg/VERIFY.md.

OpenSSF Scorecard posture

The scorecard report lives at scorecard.dev/viewer/?uri=github.com/sebastienrousseau/noyalib. v0.0.6 lifts the score from 6.5/10 to ~9/10 by closing every check that is fixable in source — the four remaining items below require external action and are tracked here so contributors can see the residual gap:

Disclosure

Report security issues to sebastian.rousseau@gmail.com. Initial response within 48 hours; mitigation plan within 7 days of confirmation. Full policy at SECURITY.md.

4. Performance & algorithmic complexity

The reference target is constant memory per input byte on the parser hot path, with a clear structural bound on every operation. The headline numbers below were captured on 2026-05-08 against a 97 KB synthetic mapping-of-records document.

Algorithmic guarantees

• Parser: single pass, O(n) time, O(d) stack (d = nesting depth, capped at max_depth).
• Loader: O(n) events from parser → O(n) allocations for the AST.
• Anchor resolution: each alias is a hash-map lookup (O(1) expected), and the cumulative byte-budget for resolved aliases is bounded by max_document_length to defeat billion-laughs amplification.
• Owned mapping: IndexMap-backed with randomized hashing on hosted builds; key insertion is O(1) amortised and ordered iteration is O(n). Allocation-only no_std targets retain deterministic Fx hashing.
• Path lookup (Document::get(path)): O(d + len(path)) worst case where d is path-depth (no cross-cuts).
• Schema validation: O(n × s) where n = document size and s = schema size; bounded by jsonschema’s own guarantees.

Where the SIMD lives

• Decimal-integer parsing (simd::parse_decimal_*) — SWAR.
• Plain-scalar termination scan — memchr + SWAR fallback.
• Structural-bitmask iteration (simd::SimdScanner) — SWAR.

Every SIMD pipeline has a portable fallback verified by Miri under big-endian (mips64) so the byte-order assumption stays explicit.

Benchmark methodology

• cargo bench runs the criterion suite under [profile.release] with opt-level = 3, lto = "fat", codegen-units = 1, overflow-checks = true.
• CodSpeed tracks per-PR drift on every benchmark.
• Measurements above are single-thread; see §5 for the parallel-parsing story.

Profile-Guided Optimization (PGO) — opt-in 5-15% on top

The default cargo install noya-cli build runs the workspace release profile (opt-level = 3, lto = "fat", codegen-units = 1). A two-pass PGO build adds another 5-15% speedup on the parser hot path by laying out branches based on the actual execution profile rather than LLVM’s static heuristics.

PGO is opt-in: distro packagers and downstream teams who ship the binaries to a wide audience can run scripts/pgo.sh to produce a PGO’d binary. The full pipeline (instrumented build → train against representative corpus → optimised rebuild via llvm-profdata merge) is documented at docs/PGO.md.

Per-host-triple training is required — a Mac-trained merged.profdata cannot be reused on Linux x86_64.

Known performance non-goals

• We do not match serde-saphyr’s typed-target throughput on the smallest inputs — the AST loader has a per-document setup cost that pays off on documents larger than ~64 KB.
• We do not zero-allocate; the typed deserialise still allocates for String, Vec, and the like at boundary conversions.
• We do not support memory-mapped streaming over multi-GB documents; the entire input must fit in &[u8] / &str.

5. Concurrency guarantees

Send / Sync bounds

Parallelism story

• Single-document parse is single-threaded. It’s fast enough that splitting a single doc across cores costs more than it gains for typical inputs.
• Multi-document streams can be parsed in parallel via noyalib::parallel::parse::<T>(input) (gated behind the parallel feature). Each document parses on its own rayon job.
• Service-owned concurrency uses parallel::parse_with_config_in_pool(input, config, pool) so the caller controls the worker count, thread lifecycle, names, and stack sizes without touching Rayon’s global pool.
• The Deserializer itself is not Sync-after-construction in a useful way — there’s no parallel access to a single document’s events.

Anchor / alias semantics under concurrency

Anchors are resolved at parse time (per YAML 1.2 §7.1). Once resolution completes, the resulting Value tree is fully owned, so there is no shared-mutable state across threads. Sending a parsed Value between threads is the same as sending any other owned data structure.

Reentrance

Every public parse / emit function is reentrant. There is no mutable global state. The library does not initialise any singletons, does not register any signal handlers, and does not spawn background threads on its own (only the parallel feature opts in to rayon thread-pool use).

6. Platform support

Tier 1 (CI-verified every PR)

Tier 2 (verified on demand / weekly)

Bare-metal, no_std (CI-verified every PR)

Built with --no-default-features; alloc is required, std is not present at all on these targets.

See § no_std (alloc-only) build for why these carry the invariant that wasm32-unknown-unknown cannot.

no_std (alloc-only) build

The noyalib crate compiles cleanly with --no-default-features against core + alloc. The Per-crate no_std (alloc-only) build workflow job runs exactly that on every PR.

Do not add --features minimal when you want no_std. minimal is defined as minimal = ["std"] — it is a dependency-budget alias that turns std back on while dropping itoa, ryu and serde_ignored (see §7, Feature compatibility). Combining it with --no-default-features yields a std build, so it silently does not test what the name suggests. This document previously recommended that exact combination; corrected in v0.0.16.

Bare-metal included. no_std here means alloc-only, and it is verified on five configurations on every PR: the native host, wasm32-unknown-unknown, and the three bare-metal *-none targets thumbv7em-none-eabihf, riscv32imac-unknown-none-elf and aarch64-unknown-none.

The bare-metal targets are the ones that actually hold the line. wasm32-unknown-unknown has std available, so a dependency pulling it in unconditionally passes there — which is exactly how #210 went unnoticed. A *-none target has no std at all, so the same mistake fails the build.

This section previously said bare-metal did not build, and named two blockers. Both were fixed and the text was not updated:

1. indexmap, rustc-hash and memchr are now all declared default-features = false, so nothing pulls std transitively.
2. FxHashMap / FxHashSet are hashbrown::HashMap / HashSet with FxBuildHasher (see the no_std prelude in lib.rs) rather than the rustc_hash aliases, which do not exist without std.

If you need bare-metal support, please open an issue — it is a tractable change, but it is a deliberate non-goal today rather than an oversight.

When in no_std mode:

• from_reader / to_writer (which need std::io) are unavailable. Use from_slice / to_string and route through your own writer impl.
• figment integration unavailable.
• miette integration unavailable.
• The noyavalidate binary unavailable (it bundles miette/fancy).

Cross-platform behavioural notes

• Line endings: parse / emit normalize to \n regardless of platform. The CST preserves source bytes verbatim, including CRLF (\r\n), if the input contained them.
• File paths in noya-cli / noyalib-mcp: handled via std::path::Path; Unicode-faithful on macOS / Linux, Windows handles non-Unicode paths by fall-through to UTF-8 lossy.
• Atomic file writes in noyalib-mcp::tool_set: write to a sibling temp file, fsync, then rename. POSIX: atomic. Windows: MoveFileExW(MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH) semantics — atomic-with-flush.
• Number formatting: deterministic via ryu / itoa. No locale dependency. 0.1 + 0.2 displays as 0.30000000000000004 exactly the same on every platform.

7. Feature-flag matrix

noyalib (the library) — defaults: std, fast-int, fast-float, strict-deserialise.

Feature compatibility

• minimal is not additive with fast-int / fast-float / strict-deserialise — using minimal means you opted out of those three. cargo build --features minimal builds with only std enabled.
• validate-schema and schema both pull serde_json; if you enable both, you get exactly one copy.
• parallel is std-only — there’s no rayon no_std.
• compat-serde-yaml is independent and pulls no extra deps.
• nightly-simd requires a nightly toolchain at build time; gracefully no-ops to portable scalar fallbacks when built on stable. Not enabled in default — opt-in via cargo +nightly build --features nightly-simd.
• compare-saphyr is not intended for production builds. It compiles in serde_saphyr purely so the comparison benches in crates/noyalib/benches/comparison.rs can pit noyalib head-to-head against it; downstream packagers must not enable this feature in shipped binaries.

8. Panic policy

The library API does not panic on well-formed input. Panic sources, exhaustively:

1. unwrap / expect in tests and examples — never on user-facing code paths.
2. Internal invariants — crate::error::invariant_violated is the canonical panic site; firing it indicates a bug that should be reported. The function’s docstring documents the conditions that should make it unreachable.
3. Allocator OOM — Rust’s default behaviour. A user with a custom global allocator that returns null will see the process abort, not unwind, because we set panic = "abort" in [profile.release].

panic = "abort" in release means panics terminate the process; do not rely on catching them. Library callers who need panic safety should use std::panic::catch_unwind in debug builds; in release, treat any panic as a bug to file.

9. Error model

Public surface uses a single error type per crate (noyalib::Error, noya_cli::Error, etc.). The noyalib::Error enum is #[non_exhaustive] and carries location info wherever possible.

Invariants

• Every public from_* function returns Result<T, Error>, never panics on malformed input.
• Every public to_* function returns Result<…, Error>, never panics on representable values.
• Errors include a Location { line, column, byte_offset } whenever the underlying source span is available.
• Error::diagnostic() is the canonical adapter boundary. It exposes stable namespaced codes, protocol-neutral severity, help text, and ordered byte spans without requiring a rendering dependency.
• Error: Send + Sync + 'static — safe to propagate across threads and into anyhow / eyre / Box<dyn Error>.

miette integration

With features = ["miette"], Error implements miette::Diagnostic by adapting Error::diagnostic(), so CLI tools render rich location-aware output without a second error-code or label mapping. The noyavalidate binary is the canonical example. The ariadne feature consumes the same payload.

Truncation

Long source snippets in error messages are truncated to a configurable budget via Error::format_with_source_truncated (default 4 KB) so the diagnostic doesn’t dump megabytes of context into a CI log.

10. Dependency policy

Default-on dependencies (5 unconditional + 3 default-on optional)

• serde (no-default-features, with derive + alloc)
• indexmap (>=2, <2.11) — ordered mappings
• itoa (default-on optional via fast-int)
• ryu (default-on optional via fast-float)
• serde_ignored (default-on optional via strict-deserialise)

Opt-in dependencies (gated by feature)

miette, garde, validator, schemars, serde_json, jsonschema, figment, rayon, plus the three default-on opt-outs covered in §7.

Adoption rules

• New dependencies require explicit rationale in the Cargo.toml comment block.
• Every dep is checked against cargo-vet (vetted-deps register) and cargo-deny (allow / deny / skip rules).
• No wildcard version requirements (the cargo-deny config rejects them). Every entry pins a >= lower bound and an < upper bound; this protects against transitive silent-bumps.
• Audit advisories (cargo audit) fail the build on any flagged dep.

cargo-vet exemption conventions

supply-chain/config.toml is machine-generated — cargo vet fmt strips comments, so the conventions governing it are recorded here instead of inline.

• Exemptions are version-pinned. Bumping a dependency invalidates its exemption and the crate re-enters the unaudited set. This is deliberate: it is why a blanket cargo update is not a routine operation here (see the v0.0.16 notes, where a 71-crate refresh put 81 crates back on the unaudited list at once).
• suggest = false means “deliberately parked” — cargo vet suggest will stop proposing it. New exemptions are added without it, so they stay on the suggest list until someone either audits them or consciously parks them. The absence of suggest = false is a to-do marker, not an oversight; do not add it in bulk to quieten the suggest output.
• Never add exemptions in bulk to make a red gate green. An exemption is an assertion that a human looked. If a change produces more new exemptions than a reviewer can actually read, the change is too large — split it.

11. Release & changelog policy

• The CHANGELOG.md follows Keep a Changelog 1.1.0 with explicit [Unreleased] rolling section.
• Every commit ending up in a release is annotated with the Assisted-by: trailer per the Linux kernel coding-assistants standard so AI tooling provenance is auditable.
• Releases are tagged v0.0.X, GPG-signed, and the cargo-semver-checks gate must pass before a tag is pushed.
• Yanking is reserved for genuine security issues; behavioural bugs ship a fix rather than a yank.

Open an issue if any policy here is unclear

These policies are intended to be operational, not aspirational. If you hit a case where the policy doesn’t tell you what to expect, file an issue at https://github.com/sebastienrousseau/noyalib/issues with the scenario — every clarification we add here closes a future ambiguity.

MSRV and deprecation policy

Written down because it was being applied from memory, and memory lost twice in a single release cycle — see Why this exists.

Minimum Supported Rust Version

Current MSRV: 1.89.0, declared as rust-version in crates/noyalib/Cargo.toml and enforced by the msrv-core and msrv-per-crate CI jobs.

What the MSRV covers

The library, on its default features and on --all-features. It does not cover:

• development tooling (cargo-vet, cargo-audit, coverage);
• dev-dependencies, which may require a newer toolchain than the library does — see below, because this is the subtle one;
• the nightly-simd feature, which requires nightly by definition.

Raising the MSRV

• A raise ships only on the breaking-change axis — during the 0.0.x series that is the patch number (the same axis every breaking change uses; see the SemVer section of the crate docs), and from 0.x onward the minor number. It is always called out in the changelog under its own heading and never happens silently in a compatible release. (Earlier wording said “minor version bump, never patch-level”, which is unsatisfiable while the release number only moves in the patch position — the v0.0.16 raise from 1.85 to 1.86 shipped exactly this way.)
• A raise needs a reason recorded in the changelog entry: which API, and why the alternative was rejected. “It was more convenient” is not a reason; “the alternative allocates on a hot path” is.
• The one raise made without a toolchain reason is the v0.0.58 move to 1.89.0, which puts the family on one floor with the maintainer’s other Rust crates. It is recorded as a decision in ADR-0014, not as a precedent.
• Prefer writing the older form. Option::map_or over Option::is_none_or costs nothing and keeps the floor where it is.

Dev-dependencies are in scope for CI, not for the contract

A dev-dependency whose own rust-version exceeds ours fails the MSRV job even though no consumer of the library is affected. When that happens:

1. Pin the dev-dependency back to the last version under our floor, if one exists that is not yanked.
2. If no such version exists, that is a decision, not a mechanical fix. Raising the library’s MSRV to accommodate a test-only dependency narrows what consumers can use, and should be made explicitly rather than to make a red job green.

Deprecation

Process

1. Mark with #[deprecated(since = "x.y.z", note = "...")]. The note must name the replacement, not just say the item is deprecated.
2. Keep it for at least two minor releases after the marking release.
3. Remove only in a release that documents the removal in the changelog under Removed.

What is not deprecated

Behaviour changes that fix a defect are not deprecations — they are fixes, and ship as such with the reasoning in the changelog. v0.0.19 changed bare nan / inf scalars from resolving as floats to staying strings; that was a correctness fix to spec-conformance, documented, not a deprecation cycle.

Why this exists

Both of these were hit inside one release cycle, which is what turned an implicit convention into a written one:

• Option::is_none_or was used in the v0.0.21 no_std work. It is stable from 1.82; the MSRV was 1.86, so this one was fine, but the same pattern in a sibling crate with a 1.80 floor was caught only by clippy’s incompatible_msrv. The lint is the backstop; writing the older form is the habit.
• A dev-dependency raised its own MSRV five releases past a sibling crate’s floor, with its predecessor version yanked. There was no mechanical fix, only a choice between pinning to an older major and raising a user-facing promise to accommodate a test tool. Without a written policy that choice gets made by whoever is trying to get CI green.

Enforcement

The first two are mechanical and should stay that way. The last two are judgement, and this document exists so the judgement is consistent.

OpenSSF Best Practices Badge — self-assessment

noyalib holds the passing-level badge: project 13057, 100% of the 65 passing criteria, achieved 2026-05-31. The badge is embedded in the workspace README.md header. This file is the maintenance record: each criterion mapped to the artefact that satisfies it, so answers can be re-verified when the project changes and the Silver application can start from it.

Passing-level criteria — prefilled answers

The 65 criteria are organised under six headings on the badge site. Each row below maps the criterion → the noyalib artefact that satisfies it.

Basics

Change control

Reporting

Quality

Security

Analysis

Silver / Gold level (future)

The “Silver” badge adds 30+ more criteria around release process maturity and “Gold” 30 more around supply-chain transparency. The passing entry is complete; tracking Silver for the v0.1.0 milestone via https://www.bestpractices.dev/en/projects/13057/silver/edit.

noyafmt as a pre-commit hook

noyafmt --check exits 1 when any of its file arguments would be rewritten by formatting, printing one path per line on stdout. That shape matches what pre-commit, lefthook, and plain Git pre-commit hooks expect of a formatter gate.

Plain Git hook (.git/hooks/pre-commit)

#!/usr/bin/env sh
set -eu

# Only inspect staged YAML files. `--diff-filter=ACMR` excludes
# deletions and rename-source paths. `-z` + `xargs -0` is robust
# against paths containing spaces.
files=$(git diff --cached --diff-filter=ACMR --name-only -z -- '*.yaml' '*.yml')
[ -z "$files" ] && exit 0

# Run noyafmt --check on every staged YAML file. Any file that needs
# formatting is printed on stdout; we tee it so the developer sees it
# AND we use the exit status to fail the commit.
unformatted=$(printf '%s' "$files" | xargs -0 noyafmt --check || true)
if [ -n "$unformatted" ]; then
    echo "noyafmt: the following files are not formatted:"
    echo "$unformatted" | sed 's/^/    /'
    echo
    echo "fix them with: noyafmt --write \"\$file\""
    exit 1
fi

pre-commit framework (.pre-commit-config.yaml)

repos:
  - repo: local
    hooks:
      - id: noyafmt
        name: noyafmt
        entry: noyafmt --check
        language: system
        types: [yaml]

CI gate (GitHub Actions)

- name: noyafmt --check
  run: |
    cargo install noya-cli --version 0.0.29 --locked --no-default-features --features noyafmt
    git ls-files '*.yaml' '*.yml' | xargs noyafmt --check

Editor integration (VS Code, Helix, Zed)

noyafmt --stdin reads from stdin and writes to stdout, so any editor that supports “external formatter” hooks can use it directly:

Packaging noyalib for a distribution

Written for downstream maintainers (Debian, Fedora, Arch, Nix, Homebrew). Everything here is CI-enforced upstream, so it stays true between releases.

Licensing

Dual MIT OR Apache-2.0, REUSE 3.3 compliant: every file carries machine-readable licensing (inline SPDX headers or REUSE.toml annotations), lintable with reuse lint. The vendored YAML test suite under crates/noyalib/tests/yaml-test-suite/ is MIT, copyright yaml-test-suite contributors.

Toolchain floor

MSRV is declared as rust-version in each crate’s Cargo.toml and CI-enforced (currently 1.89.0, identical across the family). Raises happen only on the breaking-change axis with the reason recorded in the CHANGELOG — policy and history in MSRV-AND-DEPRECATION.md. Dev-dependencies may need a newer toolchain than the library; the contract covers the library on default and all-features.

The version pin model

Six crates release in lockstep at the identical =0.0.X: noyalib (the library), noya-cli (the noyafmt/noyavalidate binaries), noyalib-lsp, noyalib-mcp, noyalib-wasm, and noyalib-serde-yaml (a package-rename drop-in for archived serde_yaml). Satellites pin the core exactly; packaging noya-cli 0.0.X requires noyalib 0.0.X. The pin is the compatibility contract — do not relax it.

Building and testing offline

make vendor          # cargo vendor the full dependency tree
cargo build --locked --offline
cargo test --locked --offline

Lockfiles are committed and CI builds --locked; a resolver run is never required. The official YAML test suite is vendored, so the full compliance suite (406 cases) runs hermetically.

Binaries, manpages, completions (noya-cli)

make install in the noya-cli repository honors PREFIX and DESTDIR and installs binaries, roff manpages, and bash/zsh/fish completions to FHS paths. The committed manpages and completions are regenerated from the clap definitions (make assets) and CI fails if they drift; [package.metadata.deb] and [package.metadata.generate-rpm] in its Cargo.toml describe the same layout for cargo deb / cargo generate-rpm. Release binaries are built with cargo auditable, so cargo audit bin can read the embedded dependency list.

Verifying upstream artefacts

Tags and commits are signed (KEYS.asc at the repo root); release artefacts carry sigstore bundles, SHA256/SHA512 checksum files, a CycloneDX SBOM, and SLSA Build L2 provenance attestations (gh attestation verify <artefact> --repo sebastienrousseau/noyalib --signer-workflow sebastienrousseau/noyalib/.github/workflows/release.yml). The full cookbook is pkg/VERIFY.md.

Questions

Open an issue with the packaging label, or see SUPPORT.md. Security contacts are in SECURITY.md — never a public issue for a vulnerability.

noyalib production-readiness plan

This document is the long-form roadmap for shipping noyalib as a distro-grade Rust library and CLI tool: ≥ 98 % unit-test, doc, example, and benchmark coverage on every package; a ripgrep-shaped repo layout; and a multi-platform release pipeline that produces signed artefacts ready for crates.io, npm, the VS Code Marketplace, Linux distros (deb / rpm / Arch / Nix), Homebrew, AUR, Scoop, and a container registry.

Superseded in part. Phase 2.2 below proposes a crates/xtask/ runner (cargo xtask completions, cargo xtask manpages, …). That crate was built, then retired with the workspace split (#134, closed): man pages and shell completions now belong to noya-cli and are generated in its repository, and what remains here runs from Makefile targets and scripts/. cargo xtask is not a command in this repo. The rest of the plan stands.

The plan is written so any maintainer can pick up where the last commit left off. Each phase is sized for a single self-contained PR; the order respects dependencies (gates first, restructure early, distro outreach last).

Working invariants

These rules apply to every change inside this plan. They are binding even when not restated in a section.

• CI must always be green. Every push verifies the workflow status; any red job is fixed in the same session before declaring done. Never bypass with --no-verify, [skip ci], or if: false.
• Conventional Commits with signed (-S) commits. Assisted-by: trailer is appended automatically by the commit-msg hook; the branding signature is appended manually per ~/.claude/CLAUDE.md.
• #![forbid(unsafe_code)] at every crate root in the workspace. No exceptions.
• No fabrication. API names, flag names, paths, version numbers, and CI matrix entries are checked against the source before committing.
• Single zero-logic commit for the restructure (Phase 1). The Big Move changes only file paths and Cargo.toml members = entries. No comment edits, no formatting changes, no refactoring inside the moved files. This preserves git blame --follow accuracy for every line.

Locked decisions

Status snapshot (cf2d877)