Doc system test

Stateless replay

How the CLI asks a template's questions - the script reruns from the top on every call with every answer so far; a 3-question script runs 4 times.

Meta block front matter of this doc
namespaces
  • durian.cloud/cyanprint/prompting
  • durian.cloud/cyanprint/authoring
  • durian.cloud/cyanprint/coordinator
type
algorithm
code
  • sulfone.iridium/cyanprompt/src/domain/services/template/engine.rs
  • sulfone.iridium/cyanprompt/src/domain/services/template/validate.rs
  • sulfone.iridium/cyanprompt/src/http/client.rs
  • sulfone.iridium/cyancoordinator/src/template/executor.rs
  • sulfone.helium/sdks/node/src/domain/template/service.ts
  • sulfone.helium/sdks/node/src/domain/service/stateless_inquirer.ts
  • sulfone.helium/sdks/node/src/domain/service/stateless_determinism.ts
  • sulfone.helium/sdks/python/cyanprintsdk/domain/template/service.py
  • sulfone.helium/sdks/dotnet/sulfone-helium/Domain/Template/Service.cs

The problem. The template's script is ordinary linear code (ask name, ask port, …) but it runs in a shared container on a server, and the person answering is at a terminal elsewhere. The server cannot pause the script mid-function and wait, for minutes, on an HTTP request.

The idea. Never pause: rerun. Each call sends every answer so far; the script runs from the top, reads answers by id, and stops by throwing at the first question it has no answer for. The CLI asks that question and calls again with one more answer. With N questions the script runs N+1 times.

The loop below is the whole algorithm: CLI on the left, template on the right.

flowchart TD
  S["CLI: answers = saved + preset + carried<br/>state = spec's map"] --> I["init call: all answers, state"]
  I --> R["SDK: new inquirer(answers), new determinism(state)<br/>run the author's script from the top"]
  R --> Q{"script asks an id<br/>not in answers?"}
  Q -->|yes| X["checkpoint exception<br/>→ question reply + state"]
  Q -->|no, script returns| F["final reply: Cyan"]
  Q -->|other exception| ERR["no usable reply → Err"]
  X --> P["CLI: prompt (validate calls<br/>for text, password, date)"]
  P -->|answer| U["answers[id] = value<br/>state = reply's state"]
  P -->|Esc| K["skip: remove current id<br/>(empty map: exit 0)"]
  U --> I
  K --> I
  F --> C["Complete(Cyan, answers)"]
The replay loop

How it works

CLI side (TemplateEngine::start_with):

  1. Start from the answers the caller passes (saved answers, preset answers, answers carried from earlier nodes) and the caller's deterministic state.
  2. Send both in an init call to /proxy/template/<version id>/api/template/init (question protocol).
  3. On a question reply: remember its id, build the prompt, and for text, password and date attach a validator that makes a validate call with the answers and state as they were before this reply.
  4. Show the prompt. An answer is stored under the id and the state is replaced by the reply's state. Esc is a skip. A prompt or mapping error ends the loop with Err.
  5. Go to 2.
  6. On a final reply: end with Complete(Cyan, answers). The state is dropped.

Template side (the template service of each SDK, per request):

  1. Map the request; build a new StatelessInquirer over the answers and a new StatelessDeterminism over the state map.
  2. Call the author's function from its first line.
  3. Each i.text, i.select, … looks up its question id. Present: return the value (wrong type: ordinary error). Absent: throw OutOfAnswerException holding the question, the checkpoint exception.
  4. Catch it and reply questionnaire with the question and the determinism helper's map.
  5. If the function returns, reply final with its Cyan.
  6. Any other exception is not caught by the service.

Cost. A script with N questions takes N+1 init calls. Each typed attempt at a text, password or date question adds one validate call, which is one more full replay. Everything the script does before a question runs again on every call.

Here is the real code, CLI loop first, then the SDK side in all three languages.

sulfone.iridiumcyanprompt/src/domain/services/template/engine.rs
  1. lines 35-47The loop: every init call carries the whole answer map and the current state.
    cyanprompt/src/domain/services/template/engine.rs:35-47rust
    let mut answers: HashMap<String, Answer> = initial_answers.unwrap_or_default();
    let mut state_data: HashMap<String, String> = initial_states.clone().unwrap_or_default();
    let mut last_question_id: Option<String> = None;
    while state.cont() {
    let input = TemplateAnswerInput {
    answers: answers.clone(),
    deterministic_state: state_data.clone(),
    };
    let result = self
    .client
    .prompt_template(input)
    .and_then(|resp| match resp {
  2. lines 48-62Question reply: remember the id, map it to a prompt, attach a validator built with the pre-question maps, prompt.
    cyanprompt/src/domain/services/template/engine.rs:48-62rust
    TemplateOutput::QnA(q) => {
    // Get ID from the Question struct using pattern matching
    let question_id = &q.question.id();
    last_question_id = Some(question_id.clone());
    let ans = prompt_mapper(&q.question)
    .map(|p| {
    add_template_validator(
    p,
    Rc::clone(&self.client),
    answers.clone(),
    state_data.clone(),
    )
    })
    .and_then(|p| prompt(p))
  3. lines 64-78Esc removes the current id (or exits on an empty map); an answer is stored and the reply's state taken.
    cyanprompt/src/domain/services/template/engine.rs:64-78rust
    .map(|x| match x {
    // if skipped
    None => {
    if answers.is_empty() {
    println!("User aborted! Exiting...");
    exit(0)
    } else if let Some(last_id) = &last_question_id {
    answers.remove(last_id);
    }
    }
    Some(val) => {
    answers.insert(question_id.clone(), val);
    state_data = q.deterministic_state;
    }
    });
  4. lines 84-93Final reply → Complete with the answers; any error → Err with its text.
    cyanprompt/src/domain/services/template/engine.rs:84-93rust
    TemplateOutput::Final(c) => {
    Ok(TemplateState::Complete(c.cyan, answers.clone()))
    }
    });
    state = match result {
    Ok(ok) => ok,
    Err(err) => TemplateState::Err(err.to_string()),
    };
    }
  5. sulfone.helium/sdks/node/src/domain/template/service.ts:16-35Node: fresh helpers per request; OutOfAnswerException becomes the question reply; return becomes the final reply.
    sdks/node/src/domain/template/service.ts:16-35rust
    async template(answer: TemplateInput): Promise<TemplateOutput> {
    const i = new StatelessInquirer(answer.answers);
    const d = new StatelessDeterminism(answer.deterministicState);
    try {
    const r = await this._template.template(i, d);
    return {
    data: r,
    } satisfies TemplateFinalOutput;
    } catch (e) {
    if (e instanceof OutOfAnswerException) {
    const q: Question = e.question;
    return {
    deterministicState: d.states,
    question: q,
    } satisfies TemplateQnAOutput;
    }
    throw e;
    }
    }
  6. sulfone.helium/sdks/node/src/domain/service/stateless_inquirer.ts:15-21The checkpoint: an absent id throws with the question.
    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];
    }
  7. sulfone.helium/sdks/python/cyanprintsdk/domain/template/service.py:20-31Python: the same shape.
    sdks/python/cyanprintsdk/domain/template/service.py:20-31rust
    async def template(self, answer: TemplateInput) -> TemplateOutput:
    i = StatelessInquirer(answer.answers)
    d = StatelessDeterminism(answer.deterministic_state)
    try:
    r = await self._template.template(i, d)
    return TemplateFinalOutput(data=r)
    except OutOfAnswerException as e:
    q: Question = e.question
    return TemplateQnAOutput(deterministic_state=d.states, question=q)
    except Exception as e:
    raise e
  8. sulfone.helium/sdks/dotnet/sulfone-helium/Domain/Template/Service.cs:8-21.NET: the same shape.
    sdks/dotnet/sulfone-helium/Domain/Template/Service.cs:8-21rust
    public async Task<ITemplateOutput> Template(TemplateInput answer)
    {
    var i = new StatelessInquirer(answer.Answers);
    var d = new StatelessDeterminism(answer.DeterministicState);
    try
    {
    var r = await template.Template(i, d);
    return new TemplateFinalOutput(r);
    }
    catch (OutOfAnswerException e)
    {
    return new TemplateQnAOutput(d.States, e.Question);
    }
    }

Worked example: web:5's three questions

web:5's script, as its author wrote it (Node SDK):

typescripttypescript
StartTemplateWithLambda(async (i, d) => {
const instanceId = d.get('instance-id', () => crypto.randomUUID());
const name = await i.text('Project name?', 'name');
const port = await i.text({ type: QuestionType.Text, id: 'port', message: 'Port?',
desc: 'Port the dev server listens on', default: '3000',
validate: v => (Number(v) >= 1024 && Number(v) <= 65535 ? null : 'Use a port from 1024 to 65535') });
const features = await i.checkbox('Features?', ['docker', 'storybook'], 'features');
return { processors: [/* atomi/shop-render:1 with { name, port, instanceId } */],
plugins: [/* atomi/shop-format:1 */] };
});

In step 1 of the shop example, web:5 is the last of four nodes, so its answer map starts with node_version: 22 (from docker:7) and module_type: esm (node-base:3's preset). Step through the four runs of the script.

web:5's script runs four times
  1. Run 1

    d.get has no value and makes A. i.text('name') has no answer: it throws.

    answers sentnode_version, module_type
    state sent{}
    lines rund.get → A, name?
    replyquestion name, state {instance-id: A}
  2. User types shop

    One validate call replays to name with the old state {}, so it makes a throw-away value; name has no validator: valid. The answer is stored and the CLI takes the reply's state.

    answers+ name=shop
    state{instance-id: A}
  3. Run 2

    d.get returns A. name is answered. i.text('port') has no answer: it throws.

    answers sentnode_version, module_type, name
    state sent{instance-id: A}
    lines rund.get → A, name ✓, port?
    replyquestion port, state {instance-id: A}
  4. User types 80, then 3000

    Two validate calls, two more replays, both with A. 80 is refused, 3000 is accepted.

    answers+ port=3000
    state{instance-id: A}
  5. Run 3

    d.get returns A. i.checkbox('features') has no answer: it throws. No validate call for a checkbox.

    answers sent… + port
    state sent{instance-id: A}
    lines rund.get → A, name ✓, port ✓, features?
    replyquestion features
  6. Run 4

    Every question is answered; the script returns its Cyan with instanceId A.

    answers sent… + features=[docker]
    state sent{instance-id: A}
    lines runall
    replyfinal, Cyan only
  7. Totals

    Four init calls and three validate calls: the first line of the script ran seven times. The outcome is Complete with five answers.

    init calls4
    validate calls3
    outcomeComplete

Why it is built this way

Hard cases

  • The script must be repeatable. Anything before a question runs on every call. A question whose options, default or order depend on the clock or a random value, without d.get, can change between calls; the CLI will then store an answer for a question the next run does not ask.
  • Side effects repeat. A network call, a log line or a temp file before the last question happens N+1 times plus once per validation, in a container that every user shares.
  • Answers already in the map are never prompted or validated. Saved answers in an update and preset answers go straight through; the validator never sees them (headless is different: see answer validation).
  • Values made after the last question are lost, because the final reply has no state (deterministic state).
  • No bound. The interactive loop runs while the outcome is QnA; a template that never finishes never ends the loop. The headless walks stop at 1000 calls each.
  • Each call has 30 s, the CLI client's default limit; the script's work before the stop counts on every call.
  • A real exception is not a question. A wrong answer type or a bug in the script ends the loop with Err; Node gives no reply from the handler at all.
  • Branches are fine. Because each call starts over, a script may ask different questions for different earlier answers; the CLI only ever sees the next one.

Questions for the designer

  1. Should the interactive loop have a call limit like the headless walks?
  2. Should the CLI detect a template that asks a question it has already answered (a sign of non-repeatable code)?
  3. The design lists going back to change answers as a benefit; should the CLI offer it?