Doc system test

Dependency layering

How the outputs of every node in one dependency tree are laid into one file set - per-path resolver votes, unanimous agreement, last layer wins, clash records.

Meta block front matter of this doc
namespaces
  • durian.cloud/cyanprint/composition
  • durian.cloud/cyanprint/authoring
  • durian.cloud/cyanprint/project-lifecycle
  • durian.cloud/cyanprint/coordinator
type
algorithm
code
  • sulfone.iridium/cyancoordinator/src/operations/composition/layerer.rs
  • sulfone.iridium/cyancoordinator/src/operations/composition/operator.rs
  • sulfone.iridium/cyancoordinator/src/conflict_file_resolver/consensus.rs
  • sulfone.iridium/cyancoordinator/src/conflict_file_resolver/registry.rs
  • sulfone.iridium/cyancoordinator/src/conflict_file_resolver/models.rs
  • sulfone.iridium/cyancoordinator/src/client.rs
issues
  • https://github.com/AtomiCloud/sulfone.iridium/issues?q=TBD+group-shifts-resolver-votes
  • https://github.com/AtomiCloud/sulfone.iridium/issues?q=TBD+cache-hit-skips-resolver-warm

The problem. Several nodes of one tree write the same path: all four of web:5's nodes write package.json. CyanPrint must end with one file per path, never ask the user, and give each author a say in how their file is joined with the others.

The idea. For each path, every node that wrote it casts a resolver vote: the conflict resolver it declares for that path, or none. Only if all votes name the same conflict resolver with the same config (resolver agreement) is the conflict resolver called; otherwise last layer wins. Every file clash is recorded.

The picture shows the rule for one path.

flowchart TD
  P["one path: collect its versions<br/>in run order (layer 0, 1, 2, …)"] --> U{how many writers?}
  U -->|one| C[copy it, no record]
  U -->|two or more| V["each writer votes:<br/>its first resolver whose glob matches, or none"]
  V --> K{the votes}
  K -->|"all the same resolver instance"| R["call that resolver with every version"] --> RR[resolver]
  K -->|all none| A[last layer wins] --> RA[lww_all_no_resolver]
  K -->|"some resolver, some none"| N[last layer wins] --> RN[lww_no_consensus]
  K -->|"two different instances, no none"| B[last layer wins] --> RB[lww_ambiguous_resolver]
  R -->|"call fails"| E[the whole composition fails]
The per-path rule

How it works

Dependency layering runs once at the end of every composition run, over the outputs of the nodes that ran or came from the node cache, in run order. The same code, with votes from the stacked templates only, does template stacking.

  1. Fast paths. No outputs: an empty set. One output: copied as is. Both clear the clash list, so a one-node tree records no clashes.
  2. Collect paths across all outputs, in the order first seen. Each output's paths come from a hash map, so this order is not stable.
  3. Per path, collect versions. For each output (index i) that has the path: its bytes, the node at position i of the run order (its version id and layer i), and that node's vote.
  4. The vote. Look up the node's conflict resolver declarations (from its own template version, never its parent's). The first declaration with any glob that matches the path is the vote; no match is none. Globs use the Rust glob crate: * also matches / and a leading dot, and a bad pattern never matches.
  5. One writer: copy, no record.
  6. Two or more writers (even with identical bytes): count the votes. A conflict resolver instance is its Docker reference, Docker tag and a 64-bit hash of its config written as JSON text. The registry id, the version number and the globs are not compared.
    • every vote is the same instance: agreed;
    • every vote is none: all none;
    • at least one instance and at least one none: no consensus (checked before ambiguity);
    • only instances, of two or more kinds: ambiguous.
  7. Agreed: one call to the conflict resolver, through the coordinator's proxy, with every version in layer order. The returned content becomes the file; the returned path is ignored. Any error fails the whole composition. There is no fallback to last layer wins.
  8. Otherwise: the last version (highest layer) is kept, byte for byte.
  9. Record a file clash record: path, resolution, every writer, plus resolver_used, winner_template, or the with_resolver / without_resolver lists.

The conflict resolver request is the same shape at both places that call conflict resolvers (conflict resolvers):

jsonjson
{ "config": { "arrays": "concat" },
"files": [
{ "path": "package.json", "content": "{…}", "origin": { "template": "7a90c2d4-1e3f-4b5a-8c6d-9e0f1a2b3c4d", "layer": 0 } },
{ "path": "package.json", "content": "{…}", "origin": { "template": "b2e4911f-7c6d-4e5f-8a9b-1c2d3e4f5a6b", "layer": 2 } } ] }

It goes to POST /proxy/resolver/{resolver version id}/api/resolve on the coordinator, which forwards it to the shared conflict resolver container on port 5553 with a 30 second limit (a timeout comes back as 502). The reply is { "path": "...", "content": "..." }.

Here is the real code, from the composition into the vote and back.

sulfone.iridiumcyancoordinator/src/operations/composition/operator.rs
  1. lines 127-145Every node in the run order registers its own conflict resolver declarations, keyed by its version id. Groups too.
    cyancoordinator/src/operations/composition/operator.rs:127-145rust
    for dep in dependencies {
    let template = &dep.template;
    let template_id = template.principal.id.clone();
    let resolvers: Vec<ResolverInstance> = template
    .resolvers
    .iter()
    .map(|r| ResolverInstance {
    id: r.id.clone(),
    docker_ref: r.docker_reference.clone(),
    docker_tag: r.docker_tag.clone(),
    config: r.config.clone(),
    file_patterns: r.files.clone(),
    })
    .collect();
    if !resolvers.is_empty() {
    registry.register(template_id, resolvers);
    }
    }
  2. lines 151-161Layer info for EVERY node in the run order, groups included: index i gets node i.
    cyancoordinator/src/operations/composition/operator.rs:151-161rust
    fn build_template_infos(dependencies: &[ResolvedDependency]) -> Vec<TemplateInfo> {
    dependencies
    .iter()
    .enumerate()
    .map(|(idx, dep)| TemplateInfo {
    template_id: dep.template.principal.id.clone(),
    template_version: dep.template.principal.version,
    layer: idx as i32,
    })
    .collect()
    }
  3. lines 534-547Layer the outputs of the nodes that ran; keep the clashes for the state file.
    cyancoordinator/src/operations/composition/operator.rs:534-547rust
    } else if let Some(ref client) = self.client {
    // Use resolver-aware layering
    // Vertical layering: collect resolvers from ALL templates in dependency tree
    let registry = Self::build_resolver_registry(dependencies);
    let template_infos = Self::build_template_infos(dependencies);
    let layerer =
    ResolverAwareLayerer::new(registry, template_infos, client.clone(), headless);
    let result = layerer.layer_merge(&vfs_outputs)?;
    // Track conflicts for state writing
    self.file_conflicts = layerer.get_conflicts();
    result
  4. sulfone.iridium/cyancoordinator/src/operations/composition/layerer.rs:126-149Output i is matched to layer info i, and that node's vote for the path is looked up.
    cyancoordinator/src/operations/composition/layerer.rs:126-149rust
    let mut variations = Vec::new();
    let path_str = path.to_string_lossy();
    for (idx, vfs) in vfs_list.iter().enumerate() {
    if let Some(content) = vfs.get_file(path) {
    let template_info =
    self.template_infos
    .get(idx)
    .cloned()
    .unwrap_or_else(|| TemplateInfo {
    template_id: format!("unknown-{idx}"),
    template_version: 0,
    layer: idx as i32,
    });
    let resolver_choice = self
    .registry
    .get_resolver_choice(&template_info.template_id, &path_str);
    variations.push((template_info, resolver_choice, content.clone()));
    }
    }
    variations
  5. sulfone.iridium/cyancoordinator/src/conflict_file_resolver/registry.rs:35-49The vote: the first declared conflict resolver with a matching glob, else none.
    cyancoordinator/src/conflict_file_resolver/registry.rs:35-49rust
    pub fn get_resolver_choice(&self, template_id: &str, path: &str) -> ResolverChoice {
    let resolvers = match self.template_resolvers.get(template_id) {
    Some(r) => r,
    None => return ResolverChoice::None,
    };
    // Find the first resolver that matches the file path
    for resolver in resolvers {
    if self.matches_any_pattern(path, &resolver.file_patterns) {
    return ResolverChoice::Some(resolver.clone());
    }
    }
    ResolverChoice::None
    }
  6. sulfone.iridium/cyancoordinator/src/conflict_file_resolver/consensus.rs:10-33A conflict resolver instance = Docker reference + tag + hash of the config's JSON text.
    cyancoordinator/src/conflict_file_resolver/consensus.rs:10-33rust
    /// Unique key for resolver instance comparison
    #[derive(Debug, Clone, PartialEq, Eq, Hash)]
    struct ResolverInstanceKey {
    docker_ref: String,
    docker_tag: String,
    config_hash: u64,
    }
    impl ResolverInstanceKey {
    fn from_instance(instance: &ResolverInstance) -> Self {
    let config_hash = Self::hash_json(&instance.config);
    ResolverInstanceKey {
    docker_ref: instance.docker_ref.clone(),
    docker_tag: instance.docker_tag.clone(),
    config_hash,
    }
    }
    fn hash_json(value: &serde_json::Value) -> u64 {
    let mut hasher = std::collections::hash_map::DefaultHasher::new();
    value.to_string().hash(&mut hasher);
    hasher.finish()
    }
    }
  7. sulfone.iridium/cyancoordinator/src/conflict_file_resolver/consensus.rs:95-121The four outcomes (Ambiguous is at 118-121). Agreed uses the first writer's instance (its registry id is the one called).
    cyancoordinator/src/conflict_file_resolver/consensus.rs:95-121rust
    // Case 1: All variations agree on same resolver
    if without_resolver.is_empty() && resolver_groups.len() == 1 {
    let (_, group) = resolver_groups.iter().next().unwrap();
    if group.len() == with_resolver.len() {
    // All have the same resolver
    let resolver = group[0].1.clone();
    return ConsensusResult::Agreed(resolver);
    }
    }
    // Case 2: All variations have no resolver
    if resolver_groups.is_empty() {
    return ConsensusResult::AllNone;
    }
    // Case 3: No consensus - some have resolver, some don't
    if !with_resolver.is_empty() && !without_resolver.is_empty() {
    return ConsensusResult::NoConsensus {
    with_resolver,
    without_resolver,
    };
    }
    // Case 4: Multiple different resolvers
    ConsensusResult::Ambiguous {
    resolvers: resolver_groups.into_values().flatten().collect(),
    }
  8. sulfone.iridium/cyancoordinator/src/operations/composition/layerer.rs:247-267Agreed: call the conflict resolver; a failure returns through ? and fails the run.
    cyancoordinator/src/operations/composition/layerer.rs:247-267rust
    let consensus = determine_consensus(choices);
    let path_str = path.to_string_lossy();
    match consensus {
    ConsensusResult::Agreed(resolver) => {
    // All agree on same resolver - resolve the conflict via HTTP
    let resolved_content =
    self.resolve_with_resolver(&resolver, path, &variations)?;
    result.add_file(path.clone(), resolved_content);
    // Track conflict resolution
    let entry = Self::create_conflict_entry(
    path,
    ConflictResolution::Resolver,
    Some(&resolver),
    None,
    None,
    None,
    &variations,
    );
    self.conflicts.borrow_mut().push(entry);
  9. sulfone.iridium/cyancoordinator/src/operations/composition/layerer.rs:304-328No consensus: keep the last version; record who voted what.
    cyancoordinator/src/operations/composition/layerer.rs:304-328rust
    if let Some((template_info, _, content)) = variations.last() {
    result.add_file(path.clone(), content.clone());
    // Track conflict resolution - now with resolver info preserved
    let with_resolver_info: Vec<TemplateResolverInfo> = wr
    .iter()
    .map(|(t, resolver)| TemplateResolverInfo {
    template_id: t.template_id.clone(),
    docker_ref: format!(
    "{}:{}",
    resolver.docker_ref, resolver.docker_tag
    ),
    })
    .collect();
    let without_resolver_info: Vec<String> =
    wor.iter().map(|t| t.template_id.clone()).collect();
    let entry = Self::create_conflict_entry(
    path,
    ConflictResolution::LwwNoConsensus,
    None,
    Some(with_resolver_info),
    Some(without_resolver_info),
    Some(&template_info.template_id),
    &variations,

Worked example: web:5's four outputs

Step through step 1 of the shop example. The run order is docker:7 (layer 0), lint:2 (1), node-base:3 (2), web:5 (3). lint:2 declares no conflict resolver; the other three declare json-merger:1 for package.json with config {"arrays":"concat"}.

Layering web:5's tree
  1. Collect paths

    Twelve paths across four outputs. Two have more than one writer.

    clashingpackage.json, .gitignore
    single10 other paths
  2. package.json: versions

    All four nodes wrote it, so there are four versions in layer order.

    writersdocker:7, lint:2, node-base:3, web:5
  3. package.json: votes

    lint:2 has no declaration, so it votes none.

    votesjson-merger, none, json-merger, json-merger
    outcomeno consensus
  4. package.json: result

    The last layer, web:5, wins byte for byte. lint:2's eslint devDependency and docker:7's docker:build script are lost.

    fileweb:5's package.json
    recordlww_no_consensus, winner e5d0
  5. .gitignore

    lint:2 and node-base:3 wrote it. node-base:3 declares json-merger only for package.json, so both vote none.

    votesnone, none
    outcomeall none
    recordlww_all_no_resolver, winner b2e4
  6. Every other path

    One writer each: copied, no record.

    clash recordspackage.json, .gitignore
  7. Variation: lint:2 declares json-merger too

    Four equal votes: agreed. One call with four versions, layers 0 to 3. The reply joins all scripts and the devDependency.

    votesjson-merger x4
    outcomeagreed
    recordconflict resolver

The tree below is the layered set of step 1, with the two clashes.

web:5's layered set
  • .eslintrc.jsonaddedlint:2 only
  • .gitignoreconflictlint:2 vs node-base:3, all none: node-base:3's fileshow file
    node_modules/
    dist/
    
  • Dockerfileaddeddocker:7 only
  • package.jsonconflict4 writers, no consensus: web:5's fileshow file
    {
      "scripts": {
        "dev": "node src/server.ts",
        "test": "jest"
      }
    }
    
  • README.mdaddedweb:5 only
  • tsconfig.jsonaddednode-base:3 only

The record for package.json in the state file looks like this:

yamlyaml
- path: package.json
resolution: lww_no_consensus
with_resolver:
- { template_id: 7a90c2d4-1e3f-4b5a-8c6d-9e0f1a2b3c4d, docker_ref: "atomi/json-merger:1" }
- { template_id: b2e4911f-7c6d-4e5f-8a9b-1c2d3e4f5a6b, docker_ref: "atomi/json-merger:1" }
- { template_id: e5d07b3a-2f1e-4d3c-9b8a-7f6e5d4c3b2a, docker_ref: "atomi/json-merger:1" }
without_resolver: [3c1f0a6e-5b2d-4c8e-9f10-2a7b6c5d4e3f]
winner_template: e5d07b3a-2f1e-4d3c-9b8a-7f6e5d4c3b2a
variations: [{ template_id: 7a90… }, { template_id: 3c1f… }, { template_id: b2e4… }, { template_id: e5d0… }]

A group shifts the votes

The layer info list holds every node in the run order, groups included, but the output list holds only nodes that ran. Output i is matched to node i, so after a template group every later output carries the wrong node's id and vote.

Step through a variation: node-base:3 pins the group atomi/js-kit:1 (version id 0b7e…, no images, no conflict resolvers), which pins lint:2. lint:2 also declares json-merger for package.json.

A group in web:5's tree
  1. Run order

    Five nodes; the group runs nothing.

    run orderdocker:7, lint:2, js-kit:1, node-base:3, web:5
    outputsdocker:7, lint:2, node-base:3, web:5
  2. Matching

    Output 2 (node-base:3's files) gets js-kit's info; output 3 (web:5's files) gets node-base:3's.

    output 2 labelledjs-kit:1
    output 3 labellednode-base:3
    web:5's infonever used
  3. package.json votes

    Every real writer declares json-merger, but node-base:3's file votes with js-kit's (empty) declarations.

    votesjson-merger, json-merger, none, json-merger
    outcomeno consensus (should be agreed)
  4. Record

    web:5's file wins, but the record names node-base:3 as the winner; .gitignore names the group as a writer.

    winner_templateb2e4 (wrong)

Why it works this way

Hard cases

  • Clashes are not diffs. Two writers with identical bytes still clash, are recorded, and call the conflict resolver if they agree.
  • Text only. Versions are sent as lossy UTF-8; a binary file sent to a conflict resolver comes back changed.
  • Same image, other id. Two declarations with equal image and config but different registry ids agree; the first writer's id is the one called.
  • Config compared as normalised JSON text. Agreement hashes Value::to_string() of the config. This build of serde_json has no preserve_order (Cargo.lock lists no indexmap under it), so object keys come out sorted and spacing is dropped: key order and whitespace in cyan.yaml cannot make two equal configs disagree. Found while reading; not run.
  • Order is not stable across paths: conflict resolver calls and records follow hash map order. Within one path, versions are always in layer order.
  • Only the last pass is kept. The clash list is cleared at the start of every composition and every layering pass; with stacking, the stacking pass replaces it (state file).
  • A cache hit still layers. Cached outputs go through the same votes as fresh ones; only the node run is skipped.
  • A cache hit warms no conflict resolver. Conflict resolver containers are started only inside the coordinator's template warm (sulfone.boron/docker_executor/template_executor.go:387-420), and the CLI warms a template only on a cache miss (sulfone.iridium/cyancoordinator/src/template/executor.rs:93-99, reached from operator.rs:426-447). If every node hits, an agreed vote still calls the proxy; when no earlier run left the container up, the proxy cannot reach it, answers 502 (server.go:758-768) and the run fails. Inferred from the code; found by reading; not run.
  • A bad glob is silent here, fatal in the coordinator. An invalid pattern in a files list never matches in the CLI (registry.rs:68-72), so that writer votes none. The coordinator's merger returns an error and fails the build (merger.go:105-108, 423-426). See conflict resolvers.
  • Timeouts differ. The CLI waits up to 600 seconds; the coordinator's proxy gives up after 30 and returns 502, which fails the run.

Questions for the designer

  1. Why unanimous agreement, with "none" as a vote, rather than a majority or the highest layer's conflict resolver? (The successor sulfone.lite keeps iridium's exact consensus: lite docs/requirements/simplification-spec.md lines 107-112.)
  2. Should agreement compare registry ids and config values instead of image and config text?
  3. Should a failed conflict resolver call fall back to last layer wins, with a warning?
  4. Should clashes with identical bytes be skipped?
  5. Should the clash records keep every layering pass (dependency and stacking), not only the last?