Module patch 

Patch algebra for entry lists: the composition mechanism behind bundles and profiles.

A patch list is a bare top-level YAML array of PatchOptions rows. Each row either inserts entries (insert) or overrides an existing entry by id. apply_entry_patches is THE patch semantics — the one routine every consumer (mounting, recomposition, offline config dumps) funnels through, so a dump can never drift from what boots.

Two contracts are load-bearing:

• Detachment. Inputs are never modified and the result shares nothing with them — even with no patches the returned list is a fresh copy. Recomposition must always restart from the original patch data; feeding a materialized composition back in would bake earlier patches into the base and make a removed or changed patch impossible to revert.
• Single flatten. Layer lists (compose_layers, compose_with_provenance) are flattened into ONE apply_entry_patches call — the same single call a boot makes, not one call per layer. The single-pass id index is built once (base rows plus inserted rows as the same pass adds them) and never sees rows a plain config replacement introduced inside a group; a per-layer composition would rebuild the index between layers and let later layers patch rows boot never mounts.

Patch-file IO follows the fail-loud contract: a named overlay (load_overlay_patches) must exist — its absence is a misconfiguration — while an optional user layer (load_optional_patches) treats a missing file as “no layer”. A present-but-broken file (unreadable, unparsable, not a top-level array, an entry that is not a mapping) always fails loud: a patch file that cannot apply must never be silently skipped.

Structs

DumpLayer

One labeled patch layer, for provenance-aware composition and dumps.

PatchOptions

One patch row: insert entries, or override an existing entry by id.

Provenance

Where one composed row came from: its origin layer and every later layer that changed it.

Functions

apply_entry_patches

Apply patch rows to an entry list — THE patch semantics of this crate, shared by mounting, recomposition, and offline config tooling so a dump can never drift from what boots.

compose_layers

Compose patch layers into the effective entry list over an empty root.

compose_with_provenance

Compose layers exactly as compose_layers does (single flatten over base) while tracking, per row, which layer contributed it and which layers changed it.

load_optional_patches

Load an optional patch-list file: a top-level YAML array of patch rows. A missing file means “no layer” (Ok(None)); any other read failure, a parse failure, a non-array document, or a non-mapping entry is a hard error — a present patch file that cannot apply is a misconfiguration and must fail loud, never be silently skipped.

load_overlay_patches

Load a required overlay patch list — a bundle’s cordis.patch.yml or a --patch overlay. Same file format as load_optional_patches, but a missing file is a hard error: the caller named this file, so its absence is a misconfiguration, not “no overlay”.

render_config_dump

Compose layers over base and render the dump in one step — the offline twin of compose_with_provenance plus render_dump. See those for the single-flatten, provenance, and warning-attribution contracts.

render_dump

Render composed rows as one loadable YAML document, grouped under a # == origin[, patched by …] comment per contiguous run of rows with the same source. ${{ env.NAME }} templates print verbatim, unevaluated.