Doc system test

Conflict resolvers

Where a conflict resolver runs, the two different rules that pick one, and the request it gets.

Meta block front matter of this doc
namespaces
  • durian.cloud/cyanprint/authoring
  • durian.cloud/cyanprint/registry
  • durian.cloud/cyanprint/coordinator
  • durian.cloud/cyanprint/composition
type
flow

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 mergeLayering (dependency or stack)
Runs inthe coordinator, merger containerthe CLI
A clash istwo processors of one template version write one pathtwo template versions write one path
Resolvers come fromthat template versioneach template version that wrote the path (stack: stacked templates only)
How one is pickedevery resolver whose glob matcheseach version votes its first match; all votes must agree
No matchlast processor winslast layer wins
Two matchesthe build failslast layer wins, recorded as ambiguous
Codesulfone.boron/docker_executor/merger.go:362-506sulfone.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):

jsonjson
{
"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.template holds 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 from processorIDs).
  • origin.layer is 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 only content.

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:3 and web:6: votes are "resolver" and "none", so there is no agreement; web:6 (the later layer) wins and the clash is recorded as lww_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.