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
| Word | Meaning |
|---|---|
| Dependency tree | A template version plus every template version it depends on, directly or through others, each fixed by version id. |
| Dependency flattening | The walk that turns a dependency tree into one run order - children first, siblings by version id, root last. |
| Run order | The list of template versions in the order they run in one composition; its index is each one's layer. |
| Layer | One template version's file output, numbered by its place in run order or in the stack; a higher layer lies on top. |
| Dependency layering | Laying the layers of one dependency tree on top of each other into one file set, settling each file clash. |
| File clash | Two or more layers make the same path; settled by a conflict resolver or by last layer wins, and recorded. |
| Resolver vote | What one layer asks for on a file clash - the first of its conflict resolvers whose glob matches the path, or none. |
| Resolver agreement | Every layer in a file clash votes for the same resolver image, tag and config, so that resolver merges the file. |
| Last layer wins | The fallback for a file clash with no resolver agreement - the highest layer's copy is kept. |
| Preset answer | An answer a parent template version sets for a dependency's question, stored in the registry with the dependency ref. |
| 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>. |
| Node cache | A 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.