Doc system test

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.

Meta block front matter of this doc
namespaces
  • durian.cloud/cyanprint/composition
  • durian.cloud/cyanprint/prompting
  • durian.cloud/cyanprint/authoring
type
feature
issues
  • https://github.com/AtomiCloud/sulfone.iridium/issues?q=TBD+preset-number-silently-dropped
  • https://github.com/AtomiCloud/sulfone.iridium/issues?q=TBD+preset-spec-says-deterministic-state

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: 3000 is dropped without a word; it must be port: "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"]
The life of module_type: esm

How it works

  1. Declare. In cyan.yaml, a dependency is either a plain string or an object with template and preset_answers:

    yamlyaml
    templates:
    - template: atomi/node-base:3
    preset_answers:
    module_type: esm
    - atomi/docker
  2. Push. The CLI sends presetAnswers as raw JSON on the edge; the registry stores it with the pinned version id.

  3. Convert. Dependency flattening turns each value into an answer: a JSON string becomes String, a boolean becomes Bool, an array of only strings (also []) becomes StringArray. Anything else (number, null, object, mixed array) is dropped.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

sulfone.iridiumcyancoordinator/src/operations/composition/resolver.rs
  1. 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,
    }
    }
  2. 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 ref
    let 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;
    }
  3. 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());
    }
  4. 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 answers
    Extended {
    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.

module_type through web:5's tree
  1. 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 presetsmodule_type = esm
  2. docker:7 runs

    The user answers node_version 22. It goes on as a global answer.

    carriednode_version 22
  3. 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 answersnode_version 22, module_type esm
    askednothing
  4. web:5 runs

    module_type is now a carried answer. web:5 asks name, port and features.

    carriednode_version, module_type, name, port, features
  5. Saved

    All five go into the history entry of atomi/web, the preset among them.

    history answersnode_version, module_type, name, port, features
  6. 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 answersmodule_type cjs
  7. 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_type values, 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_type and 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

  1. 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 answers seed that child and reach its descendants through normal answer sharing; lite docs/requirements/simplification-spec.md, lines 49-50.)
  2. Should a parent's preset beat an answer the user or an earlier node gave?
  3. 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.)
  4. Should unsupported preset values (numbers, objects) fail at push?