Preset answer
A parent template version answers a dependency's question in cyan.yaml; only strings, booleans and string lists count, and the first value merged wins.
What it is. A preset answer is an answer a parent template version gives to one question of one of its dependencies, written in the parent's cyan.yaml.
It sits on the edge from parent to child in the dependency tree.
What problem it solves. web:5 needs ES modules. Without a preset, every user of web:5 would be asked node-base:3's module_type and could pick cjs. The preset fixes it to esm and the question is never shown.
What newcomers get wrong.
- A preset is a gap filler, not an order. An answer the caller already has (from the answers file, from saved history, or from an earlier node) beats it.
- Numbers are not answers.
port: 3000is dropped without a word; it must beport: "3000". - A preset does not stay with its child. Once the child completes, the preset value travels on to every later node and into the saved answers.
The picture shows where a preset sits and where it goes.
flowchart TD
Y["web:5 cyan.yaml<br/>preset_answers: module_type: esm"] -->|push| R["registry edge web:5 → node-base:3<br/>presetAnswers: module_type: esm"]
R -->|flattening| F["node-base:3 node<br/>preset map: module_type = String esm"]
F -->|run, only if no answer yet| A["node-base:3 answer map<br/>node_version 22, module_type esm"]
A -->|"not asked"| C["node-base:3 completes"]
C -->|"carry-over (raw key)"| W["web:5 gets module_type esm"]
C --> S["saved in history of atomi/web"]How it works
-
Declare. In
cyan.yaml, a dependency is either a plain string or an object withtemplateandpreset_answers:yamlyaml templates:- template: atomi/node-base:3preset_answers:module_type: esm- atomi/docker -
Push. The CLI sends
presetAnswersas raw JSON on the edge; the registry stores it with the pinned version id. -
Convert. Dependency flattening turns each value into an answer: a JSON string becomes
String, a boolean becomesBool, an array of only strings (also[]) becomesStringArray. Anything else (number, null, object, mixed array) is dropped. -
Merge. If two parents pin the same child, the child's preset map takes the first value seen for each question id; a later parent can only add ids that are still missing.
-
Fill gaps. When the child runs, its answer map is built from the caller's answers first; presets are then added only for ids still missing.
-
Skip. The template script finds the answer already there and moves on, so the question is never shown. In headless mode the question is still reached and the preset is still validated.
-
Carry on. The child's completed answers, preset included, flow to later nodes as a global (raw) answer (answer carry-over).
Here is the real code for conversion, merge and gap filling.
- lines 18-35Conversion: string, bool, all-string array. Every other JSON value returns None and is skipped.
cyancoordinator/src/operations/composition/resolver.rs:18-35rust pub fn serde_json_value_to_answer(value: &serde_json::Value) -> Option<Answer> {match value {serde_json::Value::String(s) => Some(Answer::String(s.clone())),serde_json::Value::Bool(b) => Some(Answer::Bool(*b)),serde_json::Value::Array(arr) => {let strings: Vec<String> = arr.iter().filter_map(|v| v.as_str().map(|s| s.to_string())).collect();if strings.len() == arr.len() {Some(Answer::StringArray(strings))} else {None}}_ => None,}} - lines 74-94Per edge: convert the presets; if the child is already in the order, add only missing ids (first value wins) and stop.
cyancoordinator/src/operations/composition/resolver.rs:74-94rust for dep_ref in &sorted_deps {// Extract preset_answers from the dependency reflet preset_answers: HashMap<String, Answer> = dep_ref.preset_answers.iter().filter_map(|(key, value)| {serde_json_value_to_answer(value).map(|answer| (key.clone(), answer))}).collect();// R2 Fix: Check if this template_id was already added to flattened (cross-branch).// If so, MERGE preset_answers instead of skipping or adding duplicate.if let Some(existing) = flattened.iter_mut().find(|d| d.template.principal.id == dep_ref.id){for (key, answer) in preset_answers {existing.preset_answers.entry(key).or_insert(answer);}continue;} - sulfone.iridium/cyancoordinator/src/operations/composition/operator.rs:333-339At run time: presets fill only ids the caller's answers left empty.
cyancoordinator/src/operations/composition/operator.rs:333-339rust // Preset answers (raw ids declared by the parent) fill gaps ONLY — a// caller-supplied answer for the same id, inserted above, is left untouched.for (key, answer) in &dep.preset_answers {template_answers.entry(key.clone()).or_insert_with(|| answer.clone());} - sulfone.iridium/cyanregistry/src/cli/models/template_config.rs:4-16The two cyan.yaml forms: a plain reference, or template plus preset_answers.
cyanregistry/src/cli/models/template_config.rs:4-16rust /// Template reference in cyan.yaml — accepts both plain strings and extended objects#[derive(Debug, Clone, Serialize, Deserialize)]#[serde(untagged)]pub enum CyanTemplateFileRef {/// Simple reference: "username/name" or "username/name:version"Simple(String),/// Extended reference with preset answersExtended {template: String,#[serde(default)]preset_answers: HashMap<String, serde_json::Value>,},}
Worked example: module_type in the shop
Step through step 1 of the shop example, then two variations.
- Flatten
The edge web:5 → node-base:3 carries module_type: esm. It is a JSON string, so it becomes String esm.
node-base:3 presets module_type = esm - docker:7 runs
The user answers node_version 22. It goes on as a global answer.
carried node_version 22 - node-base:3 runs
Its map starts with node_version 22. module_type is missing, so the preset fills it. The question is skipped.
node-base:3 answers node_version 22, module_type esmasked nothing - web:5 runs
module_type is now a carried answer. web:5 asks name, port and features.
carried node_version, module_type, name, port, features - Saved
All five go into the history entry of atomi/web, the preset among them.
history answers node_version, module_type, name, port, features - Variation: caller says cjs
A headless answers file with module_type cjs: the caller's answer is placed first, so the preset is ignored and node-base:3 makes CommonJS files.
node-base:3 answers module_type cjs - Variation: a number
If web:5's cyan.yaml said port: 3000 for a child, the preset would be dropped and the child would ask port.
presets (port dropped)
Why it works this way
Hard cases
- The spec and the code disagree on scope. The spec says presets are "scoped to the specific dependency template; not leaked to siblings or subsequent templates" (task-spec.md, line 64). In the code, the child's completed answers include the preset, and they flow on raw to every later node and into saved history (found while reading; not run).
- Diamond, two values. If web:5 and another parent both pinned node-base:3 with different
module_typevalues, the value from the edge the depth-first walk reaches first wins (siblings are walked in version id order, so which parent that is depends on where it sits in the tree). No warning. - An earlier node's answer beats a later node's preset. If docker:7 also asked
module_typeand the user picked cjs, node-base:3's preset would not apply. - A preset on a group edge is lost. Groups never run, and nothing passes their presets down.
- A preset for a question the child never asks is carried on and saved in an interactive run only (the interactive completion keeps every seeded answer). In a headless run the completion keeps only revealed answers, so the unasked preset is dropped and never saved (engine.rs:140, 184; found by reading; not run).
- The spec says "deterministic state", the code uses the answer map. The ticket says presets are injected "into the deterministic state" (sulfone.iridium/spec/CU-86ex0ycve/ticket.md, line 10); the code fills the answer map (operator.rs:335-339).
Questions for the designer
- The spec already decides this: a preset is "not leaked" (task-spec.md, line 64). The code breaks the spec when a preset flows to later nodes. Is that a bug to fix? (The successor sulfone.lite drops the preset cascade: a dependency's
answersseed that child and reach its descendants through normal answer sharing; lite docs/requirements/simplification-spec.md, lines 49-50.) - Should a parent's preset beat an answer the user or an earlier node gave?
- Should two different preset values for one shared child be an error? (The successor sulfone.lite allows one configuring parent per dependency, with global template uniqueness; simplification-spec.md, lines 50 and 196.)
- Should unsupported preset values (numbers, objects) fail at push?