Dependency layering
How the file outputs of every template version in one dependency tree are laid on top of each other, and how a file clash is settled.
Dependency layering turns the outputs of a flattened dependency tree into one file set. A path made by one layer is copied. A path made by two or more layers is a file clash: the layers vote for a conflict resolver, and if they all agree, that resolver merges the file; otherwise the last layer wins.
How it works
Input
- A list of layer outputs, one per template version that ran, in run order.
- For each layer, the conflict resolvers its template version declares, each with a config and file globs.
Built by
build_resolver_registry(operator.rs:121-148) from every template version in the tree.
Per path
ResolverAwareLayerer::layer_merge (layerer.rs:213-372) walks every path that any layer made (collect_all_paths, layerer.rs:101):
- Collect the variations: each layer that has this path gives its content and its resolver vote (
get_file_variations,layerer.rs:121-150). A layer's vote is the first of its resolvers whose glob matches the path, or no resolver (registry.rs:35-49). A bad glob never matches (registry.rs:69-72). - One variation: copy it. No resolver is called (
layerer.rs:234-238). - Two or more: count the votes with
determine_consensus(consensus.rs:69-122):
| Votes | Outcome | Recorded as |
|---|---|---|
| all for the same resolver, same image, same config | call that resolver | resolver |
| all for no resolver | last layer wins | lww_all_no_resolver |
| some for a resolver, some for none | last layer wins | lww_no_consensus |
| for two different resolvers, or one resolver with two configs | last layer wins | lww_ambiguous_resolver |
"Same resolver" means same image reference, same tag, and the same config JSON (consensus.rs:10-33).
- Calling the resolver: every variation is sent, in layer order, as text with its origin (template version id and layer) to
POST /proxy/resolver/{id}/api/resolveon the coordinator (layerer.rs:153-182). Itscontentbecomes the file. - Every clash is recorded as a file conflict entry (
layerer.rs:184-209). The project lifecycle saves these into the state file underfile_conflicts(state/models.rs:39).
Where this runs
- Inside one dependency tree, after all its template versions ran (
operator.rs:534-547). Resolvers come from every template version in the tree. - The same layerer is reused across stacked templates with a different resolver source. See template stacking.
Worked example
Layers from the flattening example: lint:2 (0), docker:7 (1), node-base:3 (2), web:5 (3).
docker:7 and node-base:3 both declare resolver atomi/json-merger:1 with config {} on package.json. web:5 is a template group, so it makes no files.
| Path | Made by | Votes | Result |
|---|---|---|---|
Dockerfile | docker:7 | none needed | copied |
package.json | docker:7, node-base:3 | json-merger, json-merger | json-merger merges both |
README.md | lint:2, node-base:3 | none, none | node-base:3 wins (last) |
.eslintrc | lint:2, node-base:3 | none, json-merger | node-base:3 wins; recorded as no consensus |
If lint:2 also wanted package.json merged but declared json-merger with config {"arrays":"concat"}, the configs differ: the vote is ambiguous and node-base:3 wins.
Rules worth knowing
- A resolver never sees a single variation. It is called only on a clash.
- Content is sent as text. Bytes are turned into UTF-8 with lossy decoding (
layerer.rs:116-118). Binary files are not safe to resolve. - "No resolver" is a vote. One layer without a resolver for the path blocks the merge for every layer (
consensus.rs:3). - Layer numbers count every template version in the tree, including template groups that made no files (
operator.rs:151-161). The output list holds only the layers that made files (operator.rs:244-257,372,494). Found while reading, not run: when a template group sits before a template with files in run order, the resolver votes are read for the wrong template version.
Why this way
- A vote, not a choice by the last layer. Inferred: a resolver changes content that other templates wrote, so every template that wrote the file must opt in to the same merge. Otherwise the outcome stays the predictable "last layer wins".
- Last layer wins as the fallback. It is the same rule the run order is built for: the root and the parents come last.