Conflict resolvers
Where a conflict resolver runs, the two different rules that pick one, and the request it gets.
A conflict resolver is an artifact that merges several versions of one file into one, for example two package.json files.
A template version declares its resolvers in cyan.yaml, each with a config and file globs.
Resolvers run at two places, with different rules: inside the coordinator when two processors of one template write the same file,
and inside the CLI when two template versions write the same file.
The two places
| Processor output merge | Layering (dependency or stack) | |
|---|---|---|
| Runs in | the coordinator, merger container | the CLI |
| A clash is | two processors of one template version write one path | two template versions write one path |
| Resolvers come from | that template version | each template version that wrote the path (stack: stacked templates only) |
| How one is picked | every resolver whose glob matches | each version votes its first match; all votes must agree |
| No match | last processor wins | last layer wins |
| Two matches | the build fails | last layer wins, recorded as ambiguous |
| Code | sulfone.boron/docker_executor/merger.go:362-506 | sulfone.iridium/cyancoordinator/src/operations/composition/layerer.rs:213-372 |
Details: processor output merge and dependency layering.
The request
Both places send the same body to the resolver container's POST /api/resolve (port 5553 in the Node SDK, sulfone.helium/sdks/node/src/main.ts:150):
{"config": { "arrays": "concat" },"files": [{ "path": "package.json", "content": "{\"name\":\"shop\"}", "origin": { "template": "4f…", "layer": 1 } },{ "path": "package.json", "content": "{\"scripts\":{}}", "origin": { "template": "c1…", "layer": 2 } }]}
Reply: { "path": "package.json", "content": "…" } (sulfone.helium/sdks/node/src/domain/resolver/output.ts).
origin.templateholds a different thing at each place. In layering it is the template version id (layerer.rs:166-169). In processor output merge it is the processor id (merger.go:128-131, filled fromprocessorIDs).origin.layeris the list index at each place: processor order, or run order.- The coordinator checks the reply path in processor output merge, and fails if it differs (
merger.go:463-465). Layering takes onlycontent.
How the call reaches the container
- Layering: CLI → coordinator
POST /proxy/resolver/{resolver version id}/api/resolve→ the shared resolver container (sulfone.boron/server.go:728-789). The proxy waits at most 30 seconds (server.go:757), though the CLI waits 600 (client.rs:22-27). - Processor output merge: the merger container calls the resolver container directly by its container name (
merger.go:139-166). - Resolver containers are started during warm-up. They are not tied to a session (
SessionId: "",server.go:736).
Worked example
Template version atomi/web:6 has two processors, both writing tsconfig.json, and two resolvers whose globs both match *.json:
- Processor output merge: two resolvers match, so the build fails with "Multiple resolvers match conflicting file" (
merger.go:487-489).
Now web:6 declares one resolver for *.json, and its dependency atomi/node-base:3 also writes tsconfig.json but declares none:
- Processor output merge inside
web:6: one resolver matches, it merges the two processor outputs. - Layering between
node-base:3andweb:6: votes are "resolver" and "none", so there is no agreement;web:6(the later layer) wins and the clash is recorded aslww_no_consensus.
Why the rules differ
- Inside one template version, one author owns every processor and resolver, so two matches is that author's mistake and fails loudly. Inferred.
- Across template versions, different authors own the files, so a merge needs every author's consent and the fallback is never an error. Inferred.