UL
Words: composition
Namespace: durian.cloud/cyanprint/composition
One template version's dependency tree, run on the user's machine as one unit - its run order, how answers pass between its nodes, how its outputs are laid into one file set, and the node cache.
| Word | Meaning |
|---|---|
| Dependency tree | A template version plus every template version it pins under templates in cyan.yaml, transitively; each a node by version id. |
| Node | One template version in a dependency tree, named by its version id; it runs once per composition run, or is served from the node cache. |
| Template group | A template version with no images that only lists other templates; in a composition it is a node that never runs. Defined by authoring. |
| Dependency flattening | Turning a dependency tree into its run order - post-order, siblings by version id, a shared node once with merged presets, root last. |
| Run order | The list of nodes a composition run goes through, children first, siblings by version id, root last; also the layer order. |
| Layer | One output's position when outputs are laid on top of each other - run order index in dependency layering, stack index in stacking. |
| Dependency layering | Laying the outputs of one tree's nodes into one file set, path by path, with resolver votes and last layer wins. |
| File clash | Two or more nodes (or stacked templates) write the same path; settled without the user by a resolver or last layer wins. |
| Resolver vote | One writer's choice for a clashing path - the first conflict resolver it declares whose glob matches the path, or none. |
| Resolver agreement | Every writer of a path votes the same resolver instance (Docker reference, tag and config hash); only then is the resolver called. |
| Last layer wins | When writers do not agree on a resolver, the version from the highest layer is kept byte for byte. |
| Preset answer | An answer a parent template version gives to one question of a dependency, in cyan.yaml preset_answers; fills gaps only. |
| Answer namespacing | With more than one node with images, an answer key / targets one node; other keys are global. |
| Composition run | Running one template version's whole dependency tree - flatten, run or serve each node in order carrying answers, then layer. |
| Composition state | The answers, deterministic values, run order so far and pending question carried from node to node in one composition run. |
| Node cache | The local, on-by-default store of one node's output archive and completed answers, keyed by its inputs before its questions. |
| Cache key | SHA-256 of a node's version id and number, images, answer map, deterministic map, plugins and processors, made before its questions. |
Dependency tree
A template version plus every template version it pins under templates in cyan.yaml, transitively; each a node by version id.
- Do not say: dependency graph, template group (a different thing)
- In code:
TemplateVersionRes.templates,TemplateVersionTemplateRefRes - See: Node, Preset answer, Dependency flattening
Fixed at push: a dependency named without a version is pinned to the newest version then (reference pinning). Edges carry preset answers. The same template at two versions is two nodes. Nothing checks for cycles; a back edge is skipped. Lives in the registry, inside one template version. Not related to the stacked templates of a folder.
Example: web:5's tree: web:5 → node-base:3 (preset module_type: esm) → lint:2, and web:5 → docker:7.
Not to be confused with:
- the stack: the stacked templates of one folder, linked only by its state file
- dependency layering: what happens to the tree's outputs
Node
One template version in a dependency tree, named by its version id; it runs once per composition run, or is served from the node cache.
- Do not say: dependency, child (when a node is meant)
- In code:
ResolvedDependency
A node with images (properties set) runs on the coordinator in its own session. A template group is a node with no images: it keeps its place in the run order, its resolver declarations and commands count, but it never runs.
Example: docker:7 (7a90…) is one node of web:5's tree; web:6's tree has docker:8 (8b11…) instead.
Not to be confused with:
- template: all versions of atomi/docker; a node is one version
- session: the coordinator's containers for one live node run
Template group
A template version with no images that only lists other templates; in a composition it is a node that never runs. Defined by authoring.
- In code:
principal.properties.is_none() - See: Node, Dependency layering
In composition: added to the run order and skipped; not counted for answer namespacing; its presets on its own incoming edge are not passed to its children. Because layer info counts it but outputs do not, an interior group shifts later nodes' resolver votes (a bug).
Example: A hypothetical atomi/js-kit:1 (0b7e…) that pins lint:2: it adds no files to web:5's set.
Dependency flattening
Turning a dependency tree into its run order - post-order, siblings by version id, a shared node once with merged presets, root last.
- Do not say: dependency resolution, resolver
- In code:
DefaultDependencyResolver,flatten_impl,resolve_dependencies - See: Run order
The code's name is DependencyResolver; it is not a conflict resolver. Edges are sorted by child version id as text, not cyan.yaml order. A child already in the order gets only missing preset ids (first value wins). A visited child not yet in the order is a back edge: skipped. Fetches one node at a time from the registry by version id; one failure aborts.
Example: web:5 flattens to docker:7, lint:2, node-base:3, web:5 although cyan.yaml lists node-base first.
Run order
The list of nodes a composition run goes through, children first, siblings by version id, root last; also the layer order.
- Do not say: execution order, topological order
- In code:
execution_order
Every node is run or served from cache in this order, answers flow forward along it, and its index is each output's layer, so a later node wins a clash with no agreed resolver.
Example: docker:8, lint:2, node-base:3, web:6 for web:6.
Layer
One output's position when outputs are laid on top of each other - run order index in dependency layering, stack index in stacking.
- In code:
TemplateInfo.layer,FileOrigin.layer
Sent to a conflict resolver as origin.layer. Higher layers win when no resolver is agreed. In processor output merge (coordinator) the layer is the processor's index in the Cyan instead.
Example: In web:5's tree, docker:7 is layer 0 and web:5 is layer 3.
Not to be confused with:
- a three-layer-architecture layer: unrelated
Dependency layering
Laying the outputs of one tree's nodes into one file set, path by path, with resolver votes and last layer wins.
- Also called: vertical layering
- In code:
ResolverAwareLayerer,layer_merge - See: Resolver vote, Resolver agreement, Last layer wins, File clash
Runs once at the end of every composition run, on live and cached outputs alike. Votes come from every node's own declarations. One writer: copied. Two or more: agreed → resolver call; otherwise last layer wins and a file clash record. A failed resolver call fails the run. Template stacking uses the same code with votes from the stacked templates only.
Example: web:5's package.json: votes json-merger, none, json-merger, json-merger → no consensus → web:5's file.
Not to be confused with:
- template stacking: the same rules between stacked templates
- processor output merge: clashes between processors inside one node, in the coordinator
- three-way merge: template output against the user's edits
File clash
Two or more nodes (or stacked templates) write the same path; settled without the user by a resolver or last layer wins.
- Do not say: conflict, file conflict
- In code:
FileConflictEntry - See: File clash record
Counted even when the bytes are identical. Recorded in the state file's file_conflicts (only the last layering pass is kept).
Example: Step 1: package.json (4 writers) and .gitignore (lint:2, node-base:3).
Not to be confused with:
- merge conflict: a user edit and a template change on one line, left as git markers
Resolver vote
One writer's choice for a clashing path - the first conflict resolver it declares whose glob matches the path, or none.
- In code:
ResolverChoice,get_resolver_choice - See: Resolver agreement
Taken from the writer's own template version, never its parent's. Globs use the Rust glob crate: * also matches / and a leading dot; a bad pattern never matches. None is a real vote and blocks agreement.
Example: lint:2 votes none for package.json; docker:7 votes json-merger:1 with config arrays=concat.
Resolver agreement
Every writer of a path votes the same resolver instance (Docker reference, tag and config hash); only then is the resolver called.
- Also called: consensus
- In code:
determine_consensus,ConsensusResult,ResolverInstanceKey - See: Last layer wins
Unanimous, with none as a vote. Registry id, version number and globs are not compared; config is compared as a 64-bit hash of its JSON text. The first writer's declaration is the one called. Outcomes: agreed, all none, no consensus, ambiguous.
Example: Step 3: web:5 and ci:2 both vote json-merger:1 with arrays=concat → agreed → their package.json files are joined.
Last layer wins
When writers do not agree on a resolver, the version from the highest layer is kept byte for byte.
- Also called: LWW, last write wins
Recorded as lww_all_no_resolver, lww_no_consensus or lww_ambiguous_resolver with winner_template. Not used when an agreed resolver call fails: then the run fails.
Example: Step 1: web:5's package.json wins; lint:2's eslint devDependency is lost.
Preset answer
An answer a parent template version gives to one question of a dependency, in cyan.yaml preset_answers; fills gaps only.
- Do not say: preset, default answer
- In code:
preset_answers,presetAnswers,serde_json_value_to_answer
Only a JSON string, boolean or all-string array becomes an answer; numbers and others are dropped. Merged first-value-wins when two parents pin one node. Placed after the caller's answers, so any existing answer beats it. Once the child completes, the value flows on to later nodes and into saved history.
Example: web:5 → node-base:3 with preset_answers module_type: esm; module_type is never asked.
Answer namespacing
With more than one node with images, an answer key / targets one node; other keys are global.
- Do not say: scoping, isolation
- In code:
classify_namespace,strip_namespace,namespace_template_state
Keys are classified against the known version ids, not by any slash. A node gets globals, then its own scoped keys stripped (they win). Need-input ids are always scoped. Completed answers are scoped only if the caller supplied that scoped key; the rest stay raw and reach later nodes.
Example: Headless web:5 asks 7a90c2d4-…/node_version; answering it keeps node_version scoped to docker:7.
Composition run
Running one template version's whole dependency tree - flatten, run or serve each node in order carrying answers, then layer.
- Also called: composition
- In code:
CompositionOperator.execute_template,execute_composition - See: Composition state
Called by the batch run once per template spec. Stops at once on a headless need input, with an empty file set. Returns the file set, final composition state, session ids and the commands of every node.
Example: Step 1 is one composition run of web:5; step 3 has three (web:5 base, web:5 incoming, ci:2).
Composition state
The answers, deterministic values, run order so far and pending question carried from node to node in one composition run.
- In code:
CompositionState
Starts as a copy of the caller's answers; each completed node's answers are merged in (a type change fails the run). Never drops a key, so headless pruning is undone. Its deterministic map is never updated. Its final answers become the stacked template's history answers.
Example: After web:5's tree: node_version, module_type, name, port, features.
Not to be confused with:
- state file: the folder's .cyan_state.yaml
- prompt outcome: one node's result (TemplateState in cyanprompt)
Node cache
The local, on-by-default store of one node's output archive and completed answers, keyed by its inputs before its questions.
- Do not say: output cache, build cache
- In code:
Cache,CacheStore,CacheEntry - See: Cache key
Only published nodes with images. Off with --no-output-cache or CYANPRINT_NO_CACHE. Folder from --cache-dir, CYANPRINT_CACHE or the platform cache folder. No eviction, no lock. A hit skips the node's container and questions but not layering.
Example: Step 7: ./blog hits step 1's entries and gets name shop without a question.
Not to be confused with:
- docker buildx --no-cache: image build caching, unrelated
Cache key
SHA-256 of a node's version id and number, images, answer map, deterministic map, plugins and processors, made before its questions.
- In code:
compute_key,CacheKeyMaterial
64 lowercase hex characters, also the entry's file name. Children, resolvers and commands are left out. Because the answers are those before the questions, a later run that starts the same way gets the earlier answers unasked.
Example: docker:7 in step 1 has key K1 over answers {}; the entry holds node_version 22.