Doc system test

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.

WordMeaning
Dependency treeA template version plus every template version it pins under templates in cyan.yaml, transitively; each a node by version id.
NodeOne 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 groupA template version with no images that only lists other templates; in a composition it is a node that never runs. Defined by authoring.
Dependency flatteningTurning a dependency tree into its run order - post-order, siblings by version id, a shared node once with merged presets, root last.
Run orderThe list of nodes a composition run goes through, children first, siblings by version id, root last; also the layer order.
LayerOne output's position when outputs are laid on top of each other - run order index in dependency layering, stack index in stacking.
Dependency layeringLaying the outputs of one tree's nodes into one file set, path by path, with resolver votes and last layer wins.
File clashTwo or more nodes (or stacked templates) write the same path; settled without the user by a resolver or last layer wins.
Resolver voteOne writer's choice for a clashing path - the first conflict resolver it declares whose glob matches the path, or none.
Resolver agreementEvery writer of a path votes the same resolver instance (Docker reference, tag and config hash); only then is the resolver called.
Last layer winsWhen writers do not agree on a resolver, the version from the highest layer is kept byte for byte.
Preset answerAn answer a parent template version gives to one question of a dependency, in cyan.yaml preset_answers; fills gaps only.
Answer namespacingWith more than one node with images, an answer key / targets one node; other keys are global.
Composition runRunning one template version's whole dependency tree - flatten, run or serve each node in order carrying answers, then layer.
Composition stateThe answers, deterministic values, run order so far and pending question carried from node to node in one composition run.
Node cacheThe local, on-by-default store of one node's output archive and completed answers, keyed by its inputs before its questions.
Cache keySHA-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.