Module merge 

Layered source merging with whiteout / opaque-dir semantics.

Folds Source::Layered(Vec<Source>) into a single flattened tar archive on disk (held in a NamedTempFile for the duration of the repack). The flattened tar then drives the existing populate_* pipelines unchanged.

Two tombstone conventions are supported:

• Tar-OCI (the canonical container-image convention):
  • .wh.<name> in directory D → delete D/<name> from the in-progress merged tree, including any subtree.
  • .wh..wh..opq in directory D → drop everything previously contributed to D/* before this layer’s own children of D are folded in.
• OverlayFS native:
  • Character device with major=0, minor=0 → delete this path.
  • Directory carrying the xattr trusted.overlay.opaque == "y" → opaque-dir semantics (drop lower-layer children at this path).

Layering is bottom→top: the first source in the Vec is the base, later sources override files of the same path and apply tombstones to the running merge. Tombstones themselves are never written to the output.

The fold is two-pass per layer:

1. Index the layer (tar → TarStreamIndex; FS image → list+stat walk through AnyFs).
2. Apply tombstones, then overlay non-tombstoned entries on the running merged tree.

When all layers are folded, the merged tree is serialised into a NamedTempFile as a plain (uncompressed) tar — the smallest representation that round-trips every Unix entry kind (regular, dir, symlink, char/block/fifo/socket via PAX, xattrs via SCHILY.xattr.*). Source::Layered then becomes equivalent to a TarArchive { path: <tempfile>, codec: None } for downstream pipelines.

Functions

flatten_to_tempfile

Flatten layers into a single tar archive on disk. Returns the temp-file handle (the caller MUST keep it alive for the lifetime of any downstream Source::TarArchive that references it).

populate_from_layered

Populate dst with the result of merging layers. Allocates a tempfile, holds it alive across the populate, then drops it once the destination filesystem has consumed every entry.