1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
//! Execution context — runtime variables accessible between steps.
//!
//! Provides `$variable` interpolation in user prompts and system prompts.
//! Variables are populated automatically by the runner as steps execute.
//!
//! Built-in variables:
//! $result — output of the most recent step
//! $step_name — name of the current step
//! $step_type — type of the current step
//! $flow_name — name of the current flow
//! $persona_name — name of the current persona
//! $unit_index — 1-based index of the current execution unit
//! $step_index — 1-based index of the current step within the unit
//! ${StepName} — result of a specific named step (e.g., ${Analyze})
//!
//! Variable syntax: `$name` or `${name}` (braces for disambiguation).
use std::collections::HashMap;
/// Variable names the runner manages internally. They are excluded from
/// the "user binding" view (see [`ExecContext::user_bindings`]) so that
/// a `persist`/`mutate` into a SQL-backed `axonstore` writes only the
/// flow's own data as a row — never runner bookkeeping.
const BUILTIN_VARS: &[&str] = &[
"flow_name",
"persona_name",
"unit_index",
"result",
"step_name",
"step_type",
"step_index",
];
/// Execution context — holds runtime variables for a single execution unit.
#[derive(Debug, Clone)]
pub struct ExecContext {
vars: HashMap<String, String>,
}
impl ExecContext {
/// Create a new context with unit-level variables pre-set.
pub fn new(flow_name: &str, persona_name: &str, unit_index: usize) -> Self {
let mut vars = HashMap::new();
vars.insert("flow_name".to_string(), flow_name.to_string());
vars.insert("persona_name".to_string(), persona_name.to_string());
vars.insert("unit_index".to_string(), format!("{}", unit_index + 1));
vars.insert("result".to_string(), String::new());
ExecContext { vars }
}
/// Set a variable.
pub fn set(&mut self, key: &str, value: &str) {
self.vars.insert(key.to_string(), value.to_string());
}
/// Get a variable value.
pub fn get(&self, key: &str) -> Option<&str> {
self.vars.get(key).map(|s| s.as_str())
}
/// §Fase 37.d (D3) — the full variable map, for resolving `${name}`
/// placeholders in a store `where:` clause against the flow context
/// (the Request Binding Contract on the synchronous filter path).
pub fn vars(&self) -> &HashMap<String, String> {
&self.vars
}
/// Set the current step context variables.
pub fn set_step(&mut self, step_name: &str, step_type: &str, step_index: usize) {
self.vars.insert("step_name".to_string(), step_name.to_string());
self.vars.insert("step_type".to_string(), step_type.to_string());
self.vars.insert("step_index".to_string(), format!("{}", step_index + 1));
}
/// Record the result of a step (updates $result and ${StepName}).
pub fn set_result(&mut self, step_name: &str, result: &str) {
self.vars.insert("result".to_string(), result.to_string());
self.vars.insert(step_name.to_string(), result.to_string());
}
/// Interpolate variables in a string.
///
/// Replaces `${name}` and `$name` with their values from the context.
/// Unknown variables are left as-is. Delegates to the free
/// [`interpolate_vars`] so the streaming dispatcher interpolates
/// `persist` field values with byte-identical semantics (D5).
pub fn interpolate(&self, text: &str) -> String {
interpolate_vars(text, &self.vars)
}
/// Number of variables currently set.
pub fn var_count(&self) -> usize {
self.vars.len()
}
/// The user-meaningful bindings — every variable that is not a
/// runner built-in ([`BUILTIN_VARS`]): `let` bindings and step
/// results keyed by step name. These are the columns a `persist` /
/// `mutate` into a postgresql-backed `axonstore` writes as a row
/// (Fase 35.e). Sorted by name for deterministic SQL.
pub fn user_bindings(&self) -> Vec<(String, String)> {
let mut out: Vec<(String, String)> = self
.vars
.iter()
.filter(|(k, _)| !BUILTIN_VARS.contains(&k.as_str()))
.map(|(k, v)| (k.clone(), v.clone()))
.collect();
out.sort_by(|a, b| a.0.cmp(&b.0));
out
}
}
/// §Fase 35.o — Interpolate `${name}` / `$name` references in `text`
/// against an arbitrary variable map. Extracted from
/// [`ExecContext::interpolate`] so both execution paths — the sync
/// runner (`ExecContext.vars`) and the streaming dispatcher
/// (`DispatchCtx.let_bindings`) — interpolate `persist` field values
/// with byte-identical semantics (D5: the two paths never diverge).
/// Unknown variables are left literal.
pub fn interpolate_vars(text: &str, vars: &HashMap<String, String>) -> String {
let bytes = text.as_bytes();
let mut out = String::with_capacity(text.len());
let mut i = 0;
while i < bytes.len() {
if bytes[i] == b'$' && i + 1 < bytes.len() {
if bytes[i + 1] == b'{' {
// ${name} form
if let Some(close) = text[i + 2..].find('}') {
let var_name = &text[i + 2..i + 2 + close];
if let Some(val) = vars.get(var_name) {
out.push_str(val);
} else {
// Unknown variable — keep literal
out.push_str(&text[i..i + 3 + close]);
}
i += 3 + close;
continue;
}
} else if bytes[i + 1].is_ascii_alphabetic() || bytes[i + 1] == b'_' {
// $name form — consume alphanumeric + underscore
let start = i + 1;
let mut end = start;
while end < bytes.len()
&& (bytes[end].is_ascii_alphanumeric() || bytes[end] == b'_')
{
end += 1;
}
let var_name = &text[start..end];
if let Some(val) = vars.get(var_name) {
out.push_str(val);
} else {
out.push_str(&text[i..end]);
}
i = end;
continue;
}
}
out.push(bytes[i] as char);
i += 1;
}
out
}
// ── Tests ──────────────────────────────────────────────────────────────────
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn new_context_has_unit_vars() {
let ctx = ExecContext::new("Analyze", "Expert", 0);
assert_eq!(ctx.get("flow_name"), Some("Analyze"));
assert_eq!(ctx.get("persona_name"), Some("Expert"));
assert_eq!(ctx.get("unit_index"), Some("1"));
assert_eq!(ctx.get("result"), Some(""));
}
#[test]
fn set_step_updates_vars() {
let mut ctx = ExecContext::new("F", "P", 0);
ctx.set_step("Gather", "step", 0);
assert_eq!(ctx.get("step_name"), Some("Gather"));
assert_eq!(ctx.get("step_type"), Some("step"));
assert_eq!(ctx.get("step_index"), Some("1"));
}
#[test]
fn set_result_updates_both() {
let mut ctx = ExecContext::new("F", "P", 0);
ctx.set_result("Analyze", "The answer is 42");
assert_eq!(ctx.get("result"), Some("The answer is 42"));
assert_eq!(ctx.get("Analyze"), Some("The answer is 42"));
}
#[test]
fn interpolate_dollar_name() {
let mut ctx = ExecContext::new("F", "P", 0);
ctx.set_result("Analyze", "42");
let out = ctx.interpolate("The result is $result from step $step_name");
// $step_name not set yet — left as-is
assert!(out.contains("The result is 42"));
}
#[test]
fn interpolate_braced() {
let mut ctx = ExecContext::new("F", "P", 0);
ctx.set_result("Analyze", "42");
let out = ctx.interpolate("Previous: ${Analyze}, flow: ${flow_name}");
assert_eq!(out, "Previous: 42, flow: F");
}
#[test]
fn interpolate_unknown_kept_literal() {
let ctx = ExecContext::new("F", "P", 0);
let out = ctx.interpolate("Value: $unknown and ${also_unknown}");
assert_eq!(out, "Value: $unknown and ${also_unknown}");
}
#[test]
fn interpolate_no_vars() {
let ctx = ExecContext::new("F", "P", 0);
let out = ctx.interpolate("No variables here.");
assert_eq!(out, "No variables here.");
}
#[test]
fn interpolate_adjacent_vars() {
let mut ctx = ExecContext::new("F", "P", 0);
ctx.set("a", "hello");
ctx.set("b", "world");
let out = ctx.interpolate("$a$b");
assert_eq!(out, "helloworld");
}
#[test]
fn interpolate_dollar_at_end() {
let ctx = ExecContext::new("F", "P", 0);
let out = ctx.interpolate("price is $");
assert_eq!(out, "price is $");
}
#[test]
fn interpolate_dollar_number() {
let ctx = ExecContext::new("F", "P", 0);
let out = ctx.interpolate("cost: $100");
assert_eq!(out, "cost: $100");
}
#[test]
fn set_and_get_custom() {
let mut ctx = ExecContext::new("F", "P", 0);
ctx.set("custom_key", "custom_value");
assert_eq!(ctx.get("custom_key"), Some("custom_value"));
}
#[test]
fn var_count() {
let ctx = ExecContext::new("F", "P", 0);
// flow_name, persona_name, unit_index, result = 4
assert_eq!(ctx.var_count(), 4);
}
#[test]
fn user_bindings_excludes_builtins() {
let mut ctx = ExecContext::new("F", "P", 0);
ctx.set_step("Gather", "step", 0);
ctx.set_result("Gather", "data");
ctx.set("tenant_id", "acme");
// Built-ins (flow_name, persona_name, unit_index, result,
// step_name, step_type, step_index) are excluded; only the
// `let`/result bindings remain, sorted by name.
let bindings = ctx.user_bindings();
assert_eq!(
bindings,
vec![
("Gather".to_string(), "data".to_string()),
("tenant_id".to_string(), "acme".to_string()),
]
);
}
#[test]
fn user_bindings_empty_for_fresh_context() {
let ctx = ExecContext::new("F", "P", 0);
assert!(ctx.user_bindings().is_empty());
}
}