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.
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 it lives in one run
- Start. The batch run builds each template spec with the last history entry's
deterministic_states(always{}), or{}for a new template. - 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. - One node's loop.
TemplateEngine::start_withcopies it intostate_data. Each init call sendsstate_dataasdeterministicStates. - In the template. The SDK wraps the map in a fresh
StatelessDeterminism.d.get(key, make)returns the stored value, or callsmake()and stores the result in that map. - Back to the CLI. A question reply carries the map as
deterministicState. When the user's answer is accepted, the CLI replacesstate_datawith it. - Validation. A validate call for a question sends the map from before that question's reply, not the new one.
- End. The final reply has only the Cyan. The engine returns
Complete(cyan, answers)andstate_datais dropped.
The four places it is lost
| Where | What the code does | Effect |
|---|---|---|
| SDK final reply | returns { data: cyan } only | values made after the last question never reach the CLI |
Complete outcome | carries the Cyan and answers, no map | the map collected so far is dropped |
| state writer | builds a new empty map for the history entry | the next run starts from {} |
| headless walk | starts both walks from {}, takes no state argument | every headless call makes new values |
Here is the real code for the whole path, from d.get to the state file.
- 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;} - 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;}} - 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(),}; - 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(),) - 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;} - 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()))} - 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)}; - 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.
- Init call 1
d.get finds no value and makes A. The script then stops at name.
sent map {}d.get makes A = 4f9c2e71-aaaareply question name, map {instance-id: A} - 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.get makes B (discarded)reply valid: nullCLI map now {instance-id: A} - Init call 2
d.get returns A. The script stops at port.
sent map {instance-id: A}d.get returns Areply question port, map {instance-id: A} - 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.get returns Areply valid: Use a port from 1024 to 65535 - Validate '3000'
Same map; 3000 is accepted.
sent map {instance-id: A}reply valid: null - Init call 3
d.get returns A. The script stops at features (a checkbox: no validate call).
sent map {instance-id: A}d.get returns Areply question features, map {instance-id: A} - 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}reply final, Cyan onlyoutcome Complete, no map - Saved
The history entry for web version 5 is written with an empty map. The next replay will make a new value.
.cyan_state.yaml deterministic_states: {}app.config.json instanceId A
Parity across SDKs
All three SDKs implement get(key, make) the same way in the common case. They differ at the edges.
| Case | Node | Python | .NET |
|---|---|---|---|
stored "" | reused | reused | reused |
stored null | made again | made again | returned as is |
| map itself null | throws | throws | throws |
| logs the map on a new value | no | no | yes, 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
NeedInputoutcome 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. tryhas a fifth meaning of "deterministic state".extract_deterministic_statescopies 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 withd.getvalues. Found while reading; not run.
Questions for the designer
- Should the final reply return the map, and should the state writer save it per history entry?
- Should a headless run accept a map (in the answers file or the envelope) so a caller can carry it between calls?
- Should a validate call carry the map from the question's own reply, so validators see the same values as the next init call?
- Should nodes of one tree share one map, or keep separate ones?