Doc system test

Answer

The value for one question id - String, StringArray or Bool - its three spellings, which question kind gives which, and why only the id is matched.

Meta block front matter of this doc
namespaces
  • durian.cloud/cyanprint/prompting
  • durian.cloud/cyanprint/project-lifecycle
  • durian.cloud/cyanprint/composition
type
format

What it is. An answer is the value given for one question id. It is one of three types: String, StringArray or Bool.

What problem it solves. The template is replayed many times, by many runs, on many machines. The answer is the small, typed value that travels with every replay and is saved in the state file, so the same script can be run again with the same input.

What newcomers get wrong. There are three spellings of one answer, and mixing them is the most common mistake. Answers are matched to questions by id only: the CLI never checks on the interactive path that a saved answer's type fits the question; the template finds out when it reads it.

The picture shows where each spelling is used.

flowchart LR
  subgraph Files["{ type: String | StringArray | Bool, value }"]
    SF[".cyan_state.yaml<br/>history answers"]
    AF["headless answers file"]
    NC["node cache entry"]
  end
  subgraph Wire["{ type: string | str_array | boolean, answer }"]
    HTTP["init and validate calls<br/>to the template"]
  end
  subgraph Yaml["plain YAML value"]
    PR["preset answers<br/>in a parent's cyan.yaml"]
  end
  CLI(("CLI answer map<br/>Answer enum"))
  SF --> CLI
  AF --> CLI
  NC --> CLI
  PR -->|"string, bool, string list only"| CLI
  CLI -->|ans_req_mapper| HTTP
Three spellings of one answer

Which question kind gives which answer

The kind of question fixes the answer type. The spellings are exact.

Question kindAnswer typeFile spellingWire spelling
textString{type: String, value: "shop"}{"type":"string","answer":"shop"}
passwordString{type: String, value: "…"}{"type":"string","answer":"…"}
selectString{type: String, value: "22"}{"type":"string","answer":"22"}
dateString, YYYY-MM-DD{type: String, value: "2026-12-01"}{"type":"string","answer":"2026-12-01"}
checkboxStringArray{type: StringArray, value: [docker]}{"type":"str_array","answer":["docker"]}
confirmBool{type: Bool, value: true}{"type":"boolean","answer":true}

A skipped prompt gives no answer at all, not an empty string (see question).

Matching by id only

  1. The CLI sends the whole answer map on every init call. Keys the script never asks are sent too and ignored.
  2. The SDK's inquirer looks up the question id. If the id is absent, it throws the checkpoint exception and the CLI asks.
  3. If the id is present, the inquirer checks the type the kind expects. A wrong type is an ordinary error, not a question: the init call fails and the loop ends with Err.
  4. Answers are looked up, never removed, so a second question with the same id reads the same answer.

What counts as "present" differs slightly between SDKs:

SDKPresent whenfalse, "", []
Nodeanswers[id] is truthy (the wrapper object)present
Pythonid in answerspresent
.NETContainsKey(id)present

The wrapper is an object, so a false or empty answer still counts as given in all three.

Here is the real code: the CLI's type, its wire form, and the lookup in each SDK.

sulfone.iridiumcyanprompt/src/domain/models/answer.rs
  1. lines 4-10The CLI's Answer: serde tag type, content value. This is the file spelling.
    cyanprompt/src/domain/models/answer.rs:4-10rust
    #[derive(Clone, PartialEq, Serialize, Deserialize)]
    #[serde(tag = "type", content = "value")]
    pub enum Answer {
    String(String),
    StringArray(Vec<String>),
    Bool(bool),
    }
  2. sulfone.iridium/cyanprompt/src/http/core/answer_req.rs:21-31The wire spelling: tag type with string, str_array or boolean, and the value under answer.
    cyanprompt/src/http/core/answer_req.rs:21-31rust
    #[derive(Debug, Clone, Serialize, Deserialize)]
    #[serde(tag = "type")]
    pub enum AnswerReq {
    #[serde(rename = "str_array")]
    StringArray(StringArrayAnswerReq),
    #[serde(rename = "string")]
    String(StringAnswerReq),
    #[serde(rename = "boolean")]
    Bool(BoolAnswerReq),
    }
  3. sulfone.iridium/cyanprompt/src/http/mapper.rs:72-80Every init and validate call maps each Answer to its wire form.
    cyanprompt/src/http/mapper.rs:72-80rust
    pub fn ans_req_mapper(a: &Answer) -> AnswerReq {
    match a {
    Answer::String(s) => AnswerReq::String(StringAnswerReq { answer: s.clone() }),
    Answer::StringArray(sa) => {
    AnswerReq::StringArray(StringArrayAnswerReq { answer: sa.clone() })
    }
    Answer::Bool(b) => AnswerReq::Bool(BoolAnswerReq { answer: *b }),
    }
    }
  4. sulfone.helium/sdks/node/src/domain/service/stateless_inquirer.ts:15-21Node: an absent id throws OutOfAnswerException with the question; a present one is returned.
    sdks/node/src/domain/service/stateless_inquirer.ts:15-21rust
    private getAnswer(q: Question): Answer {
    if (!this.#answers[q.id]) {
    throw new OutOfAnswerException('', q);
    }
    return this.#answers[q.id];
    }
  5. sulfone.helium/sdks/node/src/domain/service/stateless_inquirer.ts:126-129Text: a non-string answer is an ordinary error, not a new question.
    sdks/node/src/domain/service/stateless_inquirer.ts:126-129rust
    const answer = this.getAnswer(q);
    if (isStringAnswer(answer)) return Promise.resolve(answer.answer);
    throw new Error(`Incorrect answer type. Expected: StringAnswer. Got: ${typeof answer}`);
  6. sulfone.helium/sdks/python/cyanprintsdk/domain/service/stateless_inquirer.py:29-33Python: membership test.
    sdks/python/cyanprintsdk/domain/service/stateless_inquirer.py:29-33rust
    def _get_answer(self, q: Question) -> Answer:
    if q.id not in self._answers:
    raise OutOfAnswerException("", q)
    return self._answers[q.id]
  7. sulfone.helium/sdks/dotnet/sulfone-helium/Domain/Service/StatelessInquirer.cs:11-19.NET: ContainsKey.
    sdks/dotnet/sulfone-helium/Domain/Service/StatelessInquirer.cs:11-19rust
    private IAnswer GetAnswer(IQuestion q)
    {
    if (!_answers.ContainsKey(q.Id))
    {
    throw new OutOfAnswerException("", q);
    }
    return _answers[q.Id];
    }

Worked example: features through the shop's life

Step through one answer, web:5's features, from the prompt in step 1 of the shop example to the replay in step 4.

The features answer across ./shop
  1. Step 1: the user ticks docker

    The checkbox prompt returns a list; the engine stores it under the id.

    whereCLI answer map
    spellingAnswer::StringArray(["docker"])
  2. Step 1: last init call to web:5

    The whole map goes to the template, mapped to wire form.

    whereHTTP body
    spelling"features": {"type":"str_array","answer":["docker"]}
  3. Step 1: saved

    The history entry for web version 5 gets the answer in file spelling.

    where.cyan_state.yaml
    spellingfeatures: { type: StringArray, value: [docker] }
  4. Step 4: update web 5 → 6

    The saved answers seed web:6's replay. features is present, so web:6 never asks it; only the new runtime question is asked.

    whereHTTP body to web:6
    spelling"features": {"type":"str_array","answer":["docker"]}
    askedruntime only

Why it is built this way

Hard cases

  • Type checks are late on the interactive path. Saved answers, preset answers and answers from earlier nodes enter the map unchecked. A wrong type surfaces only when the script reads the id, as an init call failure (Err), never as a prompt.
  • Headless checks types early. For every question the discovery walk reaches, the CLI checks the answer's type against the kind (and select/checkbox membership, date range) before any call. See answer validation.
  • How the SDK picks the wire type. .NET reads the type tag. Node and Python ignore it and decide from the value (a string, a list, a boolean). The CLI always sends the tag, so all three work; a hand-made body without type works only on Node and Python.
  • One id, two types across nodes. If two nodes of one composition complete the same raw id with different types, the run stops with "type conflict for key".
  • Checkbox duplicates. Nothing rejects ["docker","docker"], interactive or headless.
  • Presets lose numbers. A preset port: 3000 (a YAML number) is dropped; only strings, booleans and string lists become answers (preset answer).
  • Answers of other templates travel along. web:5's init calls carry node_version and module_type too; the template simply never reads them.

Questions for the designer

  1. Was the split between {type, answer} on the wire and {type, value} in files chosen, or did it grow from the SDK classes?
  2. Should the CLI check a saved or preset answer's type against the question on the interactive path, as headless does?
  3. Should a checkbox answer be a set (no duplicates)?