Mechanism, not policy¶

yamldoc moves text. It has no opinion about what the text means.

This boundary is what keeps the library useful to callers whose needs differ, and it is enforced by a simple test:

If a decision can only be justified by reference to a particular kind of YAML — configuration, manifests, CI pipelines — it does not belong here.

What that rules out¶

Merging and precedence. Combining two documents, or two files, into an effective value is a policy decision. A configuration loader wants later-wins; a manifest tool wants them kept separate. yamldoc gives you the documents; you decide.

Overlay semantics. Related, and worth stating separately because it is the easiest assumption to make by accident. A multi-document file is a sequence of independent documents in YAML. Treating later ones as overriding earlier ones is a reasonable convention — and it is your convention, not this library's.

Schema and validation. Whether a value is acceptable depends entirely on the application.

File I/O. This is where policy hides in plain sight: atomic writes, permissions, locking, temp-and-rename, watching, filesystem abstraction. Callers have strong and differing opinions about all of it. yamldoc takes []byte and returns []byte, so it works over a real filesystem, an in-memory one, a git worktree, or an object store, and it drags no filesystem dependency into your build.

What that leaves in¶

Parsing to a document tree. Addressing nodes by path. Setting and removing values. Deciding which comments belong to which node during a mutation. Re-emitting. Detecting constructs that cannot be round-tripped safely.

Those are all questions about YAML documents, answerable without knowing what the document is for.

Where the line is deliberately awkward¶

Unsafe constructs sit right on the boundary. yamldoc detects them, because recognising that a flow collection with interior comments will not survive re-emission requires knowing how the emitter behaves — that is mechanism.

It does not decide what to do about one. Refusing the file, warning the user, or proceeding anyway are all reasonable, and which is right depends on whether you are a CLI, a server, or a migration script. So detection is reported and the choice is handed back.