Doc system test

UL

Words: composition

Namespace: durian.cloud/cyanprint/composition

Running one template version and its whole dependency tree, and laying their files into one file set

WordMeaning
Dependency treeA template version plus every template version it depends on, directly or through others, each fixed by version id.
Dependency flatteningThe walk that turns a dependency tree into one run order - children first, siblings by version id, root last.
Run orderThe list of template versions in the order they run in one composition; its index is each one's layer.
LayerOne template version's file output, numbered by its place in run order or in the stack; a higher layer lies on top.
Dependency layeringLaying the layers of one dependency tree on top of each other into one file set, settling each file clash.
File clashTwo or more layers make the same path; settled by a conflict resolver or by last layer wins, and recorded.
Resolver voteWhat one layer asks for on a file clash - the first of its conflict resolvers whose glob matches the path, or none.
Resolver agreementEvery layer in a file clash votes for the same resolver image, tag and config, so that resolver merges the file.
Last layer winsThe fallback for a file clash with no resolver agreement - the highest layer's copy is kept.
Preset answerAn answer a parent template version sets for a dependency's question, stored in the registry with the dependency ref.
Answer namespacingIn a composition with more than one template that has an image, a caller can scope an answer as <version id>/<question id>.
Node cacheA local cache of one template version's file output, keyed by its id, version, images, answers and pinned processors and plugins.

Dependency tree

A template version plus every template version it depends on, directly or through others, each fixed by version id.

  • Do not say: dependency graph, composition
  • See: Dependency flattening, Version id

The tree is read from the registry: each template version lists its dependencies as templates refs that hold a version id, a version number and preset answers (cyanregistry/src/http/models/template_res.rs:55-59). Example: atomi/web:5 depends on atomi/node-base:3 and atomi/docker:7; node-base:3 depends on atomi/lint:2. The tree has four template versions. The same template at two versions is two nodes.

Dependency flattening

The walk that turns a dependency tree into one run order - children first, siblings by version id, root last.

  • Do not say: dependency resolution, resolve, resolver
  • See: Run order, Conflict resolver

Code: flatten_impl in cyancoordinator/src/operations/composition/resolver.rs:63-117; the code type is DependencyResolver. It never picks a version; pins were made at push. Example: for web:5 above the run order is lint:2, docker:7, node-base:3, web:5 when docker's id sorts before node-base's. Full walk-through: docs/domain/composition/implementation/dependency-flattening.md

Run order

The list of template versions in the order they run in one composition; its index is each one's layer.

  • See: Layer, Dependency flattening

Built by dependency flattening. Siblings are ordered by version id (a GUID), not by their order in cyan.yaml. Example: [lint:2, docker:7, node-base:3, web:5]; docker:7 is layer 1.

Layer

One template version's file output, numbered by its place in run order or in the stack; a higher layer lies on top.

  • Do not say: level, tier
  • See: Dependency layering, Last layer wins

Code: TemplateInfo.layer (conflict_file_resolver/models.rs), set in build_template_infos (operator.rs:151-161). Also sent to resolvers as origin.layer. In processor output merge the same field holds the processor's index; that is a different thing, see Processor output merge in the coordinator words. Example: in run order [lint:2, docker:7], docker:7 is layer 1 and wins a file clash nobody resolves.

Dependency layering

Laying the layers of one dependency tree on top of each other into one file set, settling each file clash.

  • Also called: vertical layering
  • Do not say: merge, layer merge
  • See: Template stacking, File clash

Code: ResolverAwareLayerer::layer_merge (cyancoordinator/src/operations/composition/layerer.rs:213-372). Example: lint:2 and node-base:3 both make README.md and neither has a resolver: node-base:3's copy is kept. Full walk-through: docs/domain/composition/implementation/dependency-layering.md

File clash

Two or more layers make the same path; settled by a conflict resolver or by last layer wins, and recorded.

  • Do not say: conflict, collision
  • See: Resolver vote, Merge conflict

Code name: a conflict, recorded as FileConflictEntry and saved under file_conflicts in the state file. Not the same as a merge conflict, which is git's conflict in the three-way merge. Example: docker:7 and node-base:3 both make package.json.

Resolver vote

What one layer asks for on a file clash - the first of its conflict resolvers whose glob matches the path, or none.

  • Do not say: resolver choice, nomination
  • See: Resolver agreement

Code: ResolverChoice from ConflictFileResolverRegistry::get_resolver_choice (conflict_file_resolver/registry.rs:35-49). "None" is a real vote: it blocks a merge. Example: node-base:3 declares atomi/json-merger:1 on *.json; for package.json its vote is json-merger with its config.

Resolver agreement

Every layer in a file clash votes for the same resolver image, tag and config, so that resolver merges the file.

  • Also called: consensus
  • See: Resolver vote, Last layer wins

Code: ConsensusResult::Agreed from determine_consensus (conflict_file_resolver/consensus.rs:69-122). Any other vote mix falls back to last layer wins: all none, some none, or two different resolvers or configs.

Last layer wins

The fallback for a file clash with no resolver agreement - the highest layer's copy is kept.

  • Also called: LWW
  • See: File clash

Code: LWW; recorded as lww_all_no_resolver, lww_no_consensus or lww_ambiguous_resolver. Example: votes "json-merger" and "none" on .eslintrc - the higher layer's file is kept, recorded lww_no_consensus.

Preset answer

An answer a parent template version sets for a dependency's question, stored in the registry with the dependency ref.

  • See: Dependency tree

Written in cyan.yaml as - template: atomi/docker with preset_answers: { port: "8080" }. A caller's answer for the same id wins over a preset (operator.rs:308-339). When two parents preset the same key, the first in walk order wins. Only string, boolean and string-list values are kept (resolver.rs:18-35).

Answer namespacing

In a composition with more than one template that has an image, a caller can scope an answer as <version id>/<question id>.

  • See: Preset answer

Code: classify_namespace, strip_namespace, namespace_template_state (operator.rs:733-818). An unscoped answer goes to every template; a scoped one only to that template and wins over the unscoped one. Example: answers { "name": "shop", "c1…/name": "shop-api" } - node-base gets shop-api, every other template gets shop.

Node cache

A local cache of one template version's file output, keyed by its id, version, images, answers and pinned processors and plugins.

  • Do not say: cache
  • See: Layer

Code: cyancoordinator/src/cache/ (key in key.rs:62-71). Layering always runs again on cached outputs. Commands: cyanprint cache path|size|clear.