Doc system test

Deterministic state

The map of d.get values the CLI carries between one template's init calls - where it lives in one run, the four places it is lost, and SDK parity.

Meta block front matter of this doc
namespaces
  • durian.cloud/cyanprint/prompting
  • durian.cloud/cyanprint/authoring
  • durian.cloud/cyanprint/project-lifecycle
  • durian.cloud/cyanprint/composition
type
feature
issues
  • https://github.com/AtomiCloud/sulfone.iridium/issues?q=TBD+deterministic-state-not-saved
  • https://github.com/AtomiCloud/sulfone.helium/issues?q=TBD+final-reply-drops-deterministic-state
  • https://github.com/AtomiCloud/sulfone.iridium/issues?q=TBD+headless-ignores-deterministic-state

What it is. Deterministic state is a map of string keys to string values that a template fills through the determinism helper d.get(key, make). The CLI holds it between init calls and sends it back on each one.

What problem it solves. In a stateless replay the script runs again from the top for every question. A random UUID or a timestamp made before a question would be made again, differently, on the next call. d.get makes the value once, the map carries it back, and every later replay reads the same value.

What newcomers get wrong. It works only inside one template's question loop. It is not passed between templates of a tree, it is not in the final reply, it is not saved, and a headless walk ignores it. So every new run, every replay of the merge base and every headless call makes new values. The project-wide consequence is in client-side state; this page is the prompting side.

The picture shows the map's life in one interactive run of one template, and the four places it ends.

flowchart TD
  START["spec's deterministic_states<br/>(from history: always {})"] --> SD["CLI state_data<br/>(TemplateEngine)"]
  SD -->|"init: deterministicStates"| SDK["SDK: new StatelessDeterminism(map)<br/>d.get reads or fills it"]
  SDK -->|"question reply: deterministicState"| SD
  SDK -->|"final reply: cyan only"| L1["LOST 1: no field in the final reply"]
  L1 --> C["Complete(cyan, answers)"]
  SD -.->|"dropped when the loop ends"| L2["LOST 2: Complete has no state"]
  C --> W["state writer: history entry"]
  W --> L3["LOST 3: deterministic_states: {}"]
  H["headless walk"] --> L4["LOST 4: starts from {}<br/>whatever the caller has"]
Where deterministic state lives and where it is lost

Where it lives in one run

  1. Start. The batch run builds each template spec with the last history entry's deterministic_states (always {}), or {} for a new template.
  2. Into the tree. The composition run hands that same map to every node as shared_deterministic_states. Nothing ever writes to it, so each node starts from the spec's map.
  3. One node's loop. TemplateEngine::start_with copies it into state_data. Each init call sends state_data as deterministicStates.
  4. In the template. The SDK wraps the map in a fresh StatelessDeterminism. d.get(key, make) returns the stored value, or calls make() and stores the result in that map.
  5. Back to the CLI. A question reply carries the map as deterministicState. When the user's answer is accepted, the CLI replaces state_data with it.
  6. Validation. A validate call for a question sends the map from before that question's reply, not the new one.
  7. End. The final reply has only the Cyan. The engine returns Complete(cyan, answers) and state_data is dropped.

The four places it is lost

WhereWhat the code doesEffect
SDK final replyreturns { data: cyan } onlyvalues made after the last question never reach the CLI
Complete outcomecarries the Cyan and answers, no mapthe map collected so far is dropped
state writerbuilds a new empty map for the history entrythe next run starts from {}
headless walkstarts both walks from {}, takes no state argumentevery headless call makes new values

Here is the real code for the whole path, from d.get to the state file.

sulfone.heliumsdks/node/src/domain/service/stateless_determinism.ts
  1. lines 6-17d.get: a stored non-null value wins; otherwise make it and store it in the request's own map.
    sdks/node/src/domain/service/stateless_determinism.ts:6-17typescript
    get(key: string, origin: () => string): string {
    if (!this.states) throw new Error('NullReferenceException: States dictionary is null');
    const state = this.states[key];
    if (state != null) {
    return state;
    }
    const val = origin();
    this.states[key] = val;
    return val;
    }
  2. sulfone.helium/sdks/node/src/domain/template/service.ts:16-35Question reply returns d.states; final reply returns the Cyan only.
    sdks/node/src/domain/template/service.ts:16-35typescript
    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;
    }
    }
  3. sulfone.iridium/cyanprompt/src/domain/services/template/engine.rs:35-43The engine starts from the caller's map and sends it on every init call.
    cyanprompt/src/domain/services/template/engine.rs:35-43typescript
    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(),
    };
  4. sulfone.iridium/cyanprompt/src/domain/services/template/engine.rs:53-60The validator is built with the map as it was before this question's reply.
    cyanprompt/src/domain/services/template/engine.rs:53-60typescript
    let ans = prompt_mapper(&q.question)
    .map(|p| {
    add_template_validator(
    p,
    Rc::clone(&self.client),
    answers.clone(),
    state_data.clone(),
    )
  5. sulfone.iridium/cyanprompt/src/domain/services/template/engine.rs:74-77Only an accepted answer takes the reply's map.
    cyanprompt/src/domain/services/template/engine.rs:74-77typescript
    Some(val) => {
    answers.insert(question_id.clone(), val);
    state_data = q.deterministic_state;
    }
  6. sulfone.iridium/cyanprompt/src/domain/services/template/engine.rs:84-86Complete: Cyan and answers, no map.
    cyanprompt/src/domain/services/template/engine.rs:84-86typescript
    TemplateOutput::Final(c) => {
    Ok(TemplateState::Complete(c.cyan, answers.clone()))
    }
  7. sulfone.iridium/cyancoordinator/src/template/executor.rs:208-214Headless gets answers only; interactive gets answers and the map.
    cyancoordinator/src/template/executor.rs:208-214typescript
    let state = if headless {
    // Headless re-derives deterministic state internally; the caller
    // supplies only answers.
    prompter.start_headless(answers_clone)
    } else {
    prompter.start_with(answers_clone, states_clone)
    };
  8. sulfone.iridium/cyancoordinator/src/state/services.rs:62-71The history entry is saved with a new empty map.
    cyancoordinator/src/state/services.rs:62-71typescript
    let template_key = format!("{}/{}", username, template.template.name);
    let deterministic_states = HashMap::new();
    let history_entry = TemplateHistoryEntry {
    version: template.principal.version,
    time: Utc::now(),
    answers: answers.clone(),
    deterministic_states,
    };

Worked example: instance-id in web:5, step 1

web:5's script calls d.get("instance-id", uuid) first, then asks name, port (text, with a range validator) and features. Its answer map already holds node_version and module_type from earlier nodes. Step through every call to the web:5 container in step 1 of the shop example.

web:5's calls during cyanprint create atomi/web:5 ./shop
  1. Init call 1

    d.get finds no value and makes A. The script then stops at name.

    sent map{}
    d.getmakes A = 4f9c2e71-aaaa
    replyquestion name, map {instance-id: A}
  2. Validate 'shop'

    Sent with the map from BEFORE the name reply, which is {}. The replay makes a new value B and throws it away. name has no validator in the script: valid. Now the CLI keeps the reply's map.

    sent map{}
    d.getmakes B (discarded)
    replyvalid: null
    CLI map now{instance-id: A}
  3. Init call 2

    d.get returns A. The script stops at port.

    sent map{instance-id: A}
    d.getreturns A
    replyquestion port, map {instance-id: A}
  4. Validate '80'

    Sent with the map from before the port reply, which already holds A. port's validator refuses 80.

    sent map{instance-id: A}
    d.getreturns A
    replyvalid: Use a port from 1024 to 65535
  5. Validate '3000'

    Same map; 3000 is accepted.

    sent map{instance-id: A}
    replyvalid: null
  6. Init call 3

    d.get returns A. The script stops at features (a checkbox: no validate call).

    sent map{instance-id: A}
    d.getreturns A
    replyquestion features, map {instance-id: A}
  7. Init call 4

    Every question is answered. The Cyan's config holds instanceId A, so the files get A. The reply has no map.

    sent map{instance-id: A}
    replyfinal, Cyan only
    outcomeComplete, no map
  8. Saved

    The history entry for web version 5 is written with an empty map. The next replay will make a new value.

    .cyan_state.yamldeterministic_states: {}
    app.config.jsoninstanceId A

Parity across SDKs

All three SDKs implement get(key, make) the same way in the common case. They differ at the edges.

CaseNodePython.NET
stored ""reusedreusedreused
stored nullmade againmade againreturned as is
map itself nullthrowsthrowsthrows
logs the map on a new valuenonoyes, whole map to stdout

None of them seeds a random generator, freezes the clock or locks; the map belongs to one request.

Why it is built this way

Hard cases

  • Values made after the last question are never returned, even within the run: the final reply has no map. They only stay stable if they were first made before some question.
  • One validation sees another value. A validate call sends the map from before the question's reply. When a value is first made in the same replay that stops at a question (web:5's name), the validation replay makes it again, differently (step "Validate 'shop'" above).
  • No sharing between nodes. docker:7 and web:5 in one run each start from {}; a key used by both gets two values.
  • A headless need input carries a map (the NeedInput outcome holds one), but the envelope has no field for it, so the next headless call starts from {} again.
  • Two headless walks, two values. The discovery walk and the outcome walk each start from {}; a template that branches on a random value can be validated on one path and built on another (headless mode).
  • The node cache hides the loss on one machine. A cache hit returns old bytes with the old value (node cache).
  • Keys are per template only by habit. Nothing namespaces d.get keys; inside one template two d.get("id", …) calls share one value.
  • try has a fifth meaning of "deterministic state". extract_deterministic_states copies every String answer into a "states" map (try_cmd.rs:1390-1400); it is used only to print "N deterministic states" (try_cmd.rs:1557-1562) and has nothing to do with d.get values. Found while reading; not run.

Questions for the designer

  1. Should the final reply return the map, and should the state writer save it per history entry?
  2. Should a headless run accept a map (in the answers file or the envelope) so a caller can carry it between calls?
  3. Should a validate call carry the map from the question's own reply, so validators see the same values as the next init call?
  4. Should nodes of one tree share one map, or keep separate ones?