Doc system test

Answer carry-over

How the composition state passes answers from node to node in one tree, fails on a type change, and undoes the headless pruning of unused answers.

Meta block front matter of this doc
namespaces
  • durian.cloud/cyanprint/composition
  • durian.cloud/cyanprint/prompting
  • durian.cloud/cyanprint/project-lifecycle
type
algorithm
code
  • sulfone.iridium/cyancoordinator/src/operations/composition/state.rs
  • sulfone.iridium/cyancoordinator/src/operations/composition/operator.rs
  • sulfone.iridium/cyanprompt/src/domain/services/template/engine.rs
  • sulfone.iridium/cyanprint/src/run.rs
issues
  • https://github.com/AtomiCloud/sulfone.iridium/issues?q=TBD+headless-pruning-undone-by-composition
  • https://github.com/AtomiCloud/sulfone.iridium/issues?q=TBD+deterministic-state-not-carried
  • https://github.com/AtomiCloud/sulfone.iridium/issues?q=TBD+cache-hit-replays-unpruned-answers

The problem. Four nodes of one tree each ask their own questions, but the user should feel one interview: a value answered once should not be asked again, and the stacked template's saved answers must hold everything the tree used.

The idea. One composition state travels down the run order. Each node starts from what it holds, and each node's completed answers are merged into it. At the end, its answer map is what the state file saves for the stacked template.

The picture shows the state passing through web:5's tree.

flowchart LR
  I["start: caller answers<br/>(saved or answers file)"] --> D7["docker:7"]
  D7 -->|"+ node_version"| L2["lint:2"]
  L2 -->|"(nothing new)"| NB["node-base:3"]
  NB -->|"+ module_type (preset)"| W5["web:5"]
  W5 -->|"+ name, port, features"| E["end state"]
  E --> H["history answers of atomi/web"]
The composition state through web:5's tree

How it works

The composition state has four fields: shared_answers (id to answer), shared_deterministic_states (key to text), execution_order (version ids) and need_input (one question, or none).

  1. Start. The state is a copy of the caller's answers and deterministic map: the saved history answers on a replay, the answers file in headless mode, or nothing on a first interactive create.
  2. Group node: only its version id is added to execution_order.
  3. Node with images: its own answer map is built from shared_answers (answer namespacing, then presets). It runs live or comes from the node cache.
  4. Complete: each answer the node hands back is inserted into shared_answers. Same id and same type: replaced. Same id, other type: the run fails with type conflict for key '<id>'. Answers inserted before the bad one stay (there is no undo, but the run fails anyway).
  5. Need input (headless): the question is stored in need_input; this node's partial answers are not added. The run stops before layering.
  6. Order. The node's version id is added to execution_order in both cases.
  7. End. The batch run saves the final shared_answers as the stacked template's history entry answers.

What "answers the node hands back" means depends on the mode:

ModeA completed node hands back
interactiveevery answer it was seeded with, plus every answer typed
headlessonly answers its questions actually reached (pruned)
cache hitthe answers stored with the entry

Here is the real code.

sulfone.iridiumcyancoordinator/src/operations/composition/operator.rs
  1. lines 591-604The state starts as a copy of the caller's answers and deterministic map; flatten, run, collect commands.
    cyancoordinator/src/operations/composition/operator.rs:591-604rust
    let dependencies = self.dependency_resolver.resolve_dependencies(template)?;
    let shared_state = CompositionState {
    shared_answers: answers.clone(),
    shared_deterministic_states: deterministic_states.clone(),
    execution_order: Vec::new(),
    need_input: None,
    };
    let (vfs, final_state, session_ids) =
    self.execute_composition(&dependencies, &shared_state, headless)?;
    let commands = Self::collect_commands(&dependencies);
    Ok((vfs, final_state, session_ids, commands))
    }
  2. sulfone.iridium/cyancoordinator/src/operations/composition/state.rs:49-66Complete: insert each answer; a changed type is an error, not a crash.
    cyancoordinator/src/operations/composition/state.rs:49-66rust
    TemplateState::Complete(_, answers) => {
    // Merge answers into shared state
    for (key, value) in answers.iter() {
    if let Some(existing) = self.shared_answers.get(key) {
    // Type conflict check - surface as a recoverable error rather
    // than panicking on a merge path.
    if discriminant(existing) != discriminant(value) {
    return Err(Box::new(std::io::Error::new(
    std::io::ErrorKind::InvalidData,
    format!(
    "type conflict for key '{key}': existing answer type differs from new answer type"
    ),
    )) as Box<dyn Error + Send>);
    }
    }
    self.shared_answers.insert(key.clone(), value.clone());
    }
    }
  3. sulfone.iridium/cyancoordinator/src/operations/composition/state.rs:67-77NeedInput: keep the question. Every outcome adds the node to the order.
    cyancoordinator/src/operations/composition/state.rs:67-77rust
    TemplateState::NeedInput(question, _) => {
    // Headless: record the unanswered question (domain type) so the
    // composition can short-circuit and surface it to the CLI, which converts
    // it to the wire representation at the point of emission.
    self.need_input = Some(question.clone());
    }
    TemplateState::QnA() | TemplateState::Err(_) => {}
    }
    self.execution_order.push(template_id);
    Ok(())
  4. sulfone.iridium/cyanprompt/src/domain/services/template/engine.rs:84-86Interactive: Complete carries the whole seeded map plus new answers.
    cyanprompt/src/domain/services/template/engine.rs:84-86rust
    TemplateOutput::Final(c) => {
    Ok(TemplateState::Complete(c.cyan, answers.clone()))
    }
  5. sulfone.iridium/cyanprompt/src/domain/services/template/engine.rs:177-185Headless: Complete carries only the revealed answers, to keep stale values out of saved state.
    cyanprompt/src/domain/services/template/engine.rs:177-185rust
    Ok(TemplateOutput::Final(c)) => {
    // Persist ONLY the answers the coordinator actually revealed and
    // accepted during the discovery walk — not the full caller-supplied
    // map. `revealed` excludes over-supplied / untaken-branch answers
    // (and their secrets), so a stale value for a question that was never
    // prompted cannot leak into persisted state and be silently reused on
    // a later run where the branch changes.
    return TemplateState::Complete(c.cyan, revealed);
    }
  6. sulfone.iridium/cyanprint/src/run.rs:225-226The batch run keeps the final shared answers per stacked template; they become its history answers.
    cyanprint/src/run.rs:225-226rust
    // Store the final answers for this template (includes Q&A answers)
    final_answers_map.insert(spec.key(), final_state.shared_answers);

Worked example: web:5's tree

Step through the state in step 1 of the shop example (interactive), then a headless run that brings an extra answer.

The composition state through web:5
  1. Start

    A first create: no saved answers.

    shared_answers(empty)
    order(empty)
  2. docker:7

    The user picks 22. Complete hands back node_version.

    shared_answersnode_version 22
    order7a90
  3. lint:2

    Seeded with node_version, asks nothing, hands it back unchanged.

    shared_answersnode_version 22
    order7a90, 3c1f
  4. node-base:3

    Seeded with node_version and the preset module_type esm. Both come back; module_type is now shared.

    shared_answersnode_version, module_type esm
    order7a90, 3c1f, b2e4
  5. web:5

    Asks name, port, features. Everything comes back.

    shared_answersnode_version, module_type, name shop, port 3000, features [docker]
    order7a90, 3c1f, b2e4, e5d0
  6. Saved

    All five become the history answers of atomi/web.

    historynode_version, module_type, name, port, features
  7. Headless, extra answer

    a.json also holds ci_provider github, meant for a later ci create. No node asks it, and each headless node hands back only what it reached. But the state started with it.

    shared_answers… plus ci_provider github
    historyatomi/web now holds ci_provider

Why it works this way

Hard cases

  • Pruning is undone. The state starts with every caller answer and only ever adds; nothing removes a key no node reached. The pruned map from each node is merged into a map that already holds the stale values, so they reach the saved history anyway.
  • A cache hit brings unpruned answers into a headless run. An entry made by an interactive run stores every seeded and typed answer (engine.rs:84-86; operator.rs:501-507). A later headless hit replays all of them into the state (operator.rs:383-398), so they reach the state file by a second path, even when the headless run's own pruning would have dropped them.
  • Headless runs ignore the caller's deterministic map, but the cache key still includes it. start_headless takes answers only (sulfone.iridium/cyancoordinator/src/template/executor.rs:208-214), yet the key hashes shared_deterministic_states (operator.rs:343-348). Harmless today only because the saved maps are always empty.
  • Unused answers change cache keys. Every later node's map holds the extra answer, so its cache key differs from a run without it.
  • Deterministic state is never carried. Complete holds no deterministic values, and a need-input's values are ignored, so shared_deterministic_states ends as it started. One node's d.get value never reaches the next node.
  • A partial node leaves nothing. On need input, that node's answers so far are dropped; earlier nodes may already be stored in the node cache.
  • Type changes are mostly caught earlier. When a node asks a question whose seeded answer has the wrong type, the Node SDK fails first ("Incorrect answer type"). The state's check catches what reaches it, for example from a cache entry.

Questions for the designer

  1. Should the composition state start empty and hold only answers some node reached?
  2. The design already says yes: "Shared state (answers, deterministic states) flows from dependencies to dependents" (sulfone.iridium/docs/developer/02-architecture.md, line 81). The code does not do it, so this is a bug against the design. Should it be fixed? (The successor sulfone.lite lets a dependency entry seed deterministicState and stores deterministic state in the state file: lite docs/requirements/simplification-spec.md, lines 49 and 78-79.)
  3. Should a type change for one id be an error, or should the later node's answer win?
  4. Should a stacked template's history hold its dependencies' answers, or only its own?