postscriptum 0.1.1

Multi-interpreted-language scripting engine for Rust with Rhai and Python backends
Documentation
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
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
//! Bounded Rhai evaluation with per-eval fuel/resource budgets.
//!
//! [`BoundedRhaiEngine`] is the view-expression engine: a concrete type
//! (NOT behind `ThreadSafeEngine`, which stays frozen for the legacy
//! string-eval path) wrapping a rhai [`Engine`](rhai::Engine) with
//! caller-configurable limits. Every limit is a builder field — the
//! defaults below are starting values shared with Quartertone, not
//! fixed policy (see the gap doc §2).
//!
//! G1 wired the limits; G2 builds on `Engine::new_raw` + the curated
//! deterministic packages (see `default_limited_engine`).

use rhai::packages::{
    ArithmeticPackage, BasicArrayPackage, BasicFnPackage, BasicIteratorPackage, BasicMapPackage,
    BasicMathPackage, BasicStringPackage, LogicPackage, MoreStringPackage, Package,
};
use rhai::{AST, Dynamic, Engine, EvalAltResult, Scope};
use serde_json::Value;

use super::json::{from_dynamic_value, to_dynamic_value};
use super::validate::check_ast;
use crate::{Error, ExprIssue, ExprIssueKind, LimitKind, Result, ValidationError};

/// Starting default: operations per top-level eval (Quartertone bound).
pub const DEFAULT_MAX_OPERATIONS: u64 = 50_000;
/// Starting default: max call depth per eval (Quartertone bound).
pub const DEFAULT_MAX_CALL_LEVELS: usize = 64;
/// Starting default: max string size in bytes (Quartertone bound).
pub const DEFAULT_MAX_STRING_SIZE: usize = 64 * 1024;
/// Starting default: max array length (Quartertone bound).
pub const DEFAULT_MAX_ARRAY_SIZE: usize = 4096;
/// Starting default: max object-map size (Quartertone bound).
pub const DEFAULT_MAX_MAP_SIZE: usize = 4096;
/// Re-exported host-side source cap (defined at crate root — shared
/// with the Python backend).
pub use crate::DEFAULT_MAX_SOURCE_LEN;

/// A pre-compiled expression handle: compile once per query (G4),
/// evaluate many times against rebound scopes (G3).
///
/// Newtype over `rhai::AST` (keeps the field private so a future
/// version can reshape the handle without breaking callers beyond
/// the constructor). The AST is bound to the curated G2 package set
/// at compile time; evaluating it on any `BoundedRhaiEngine` applies
/// that engine's budgets.
#[derive(Debug, Clone)]
pub struct CompiledExpr(AST);
/// A Rhai engine with per-eval fuel/resource budgets.
///
/// Limits apply per top-level eval (rhai builds a fresh
/// `GlobalRuntimeState` per call, so the operation counter resets —
/// one hungry row cannot starve the next; pinned by test).
/// Aimed at smaller scripts (view expressions, computed columns);
/// not a batch-compute engine.
///
/// ## Determinism contract (G2a)
///
/// The same rows + the same expressions render byte-identical output:
/// no entropy, no clock reads inside expressions (`rand()`/`now()`
/// are unregistered). The deterministic alternatives are:
///
/// - **Sampling/jitter:** the `hash(...)` helper over row content —
///   same input, same output, every eval, every engine instance.
/// - **Timestamps:** never read the clock inside expressions. The host
///   binds one `frozen_now` value into scope per query — the same
///   value for every row of the page — and row data carries its own
///   timestamps.
///
/// ```
/// use postscriptum::BoundedRhaiEngine;
///
/// let mut engine = BoundedRhaiEngine::with_defaults();
/// // Frozen clock: bound ONCE per query, same value for every row.
/// // (G3's `set_var` replaces the string interpolation below.)
/// let frozen_now = "2026-09-17T12:00:00Z";
/// let expr = format!("let frozen_now = \"{frozen_now}\"; frozen_now");
/// assert_eq!(engine.eval(&expr).unwrap(), "2026-09-17T12:00:00Z");
/// // Deterministic sampling instead of `rand()`.
/// let h1 = engine.eval("hash(\"row-42\")").unwrap();
/// let h2 = engine.eval("hash(\"row-42\")").unwrap();
/// assert_eq!(h1, h2);
/// ```
pub struct BoundedRhaiEngine {
    engine: Engine,
    scope: Scope<'static>,
    max_source_len: usize,
}

impl BoundedRhaiEngine {
    /// Build with all starting defaults.
    pub fn new() -> Self {
        Self {
            engine: default_limited_engine(
                DEFAULT_MAX_OPERATIONS,
                DEFAULT_MAX_CALL_LEVELS,
                DEFAULT_MAX_STRING_SIZE,
                DEFAULT_MAX_ARRAY_SIZE,
                DEFAULT_MAX_MAP_SIZE,
            ),
            scope: Scope::new(),
            max_source_len: DEFAULT_MAX_SOURCE_LEN,
        }
    }

    /// Alias for [`Self::new`] — reads better at view call sites.
    pub fn with_defaults() -> Self {
        Self::new()
    }

    /// Cap on operations per top-level eval.
    pub fn with_max_operations(mut self, max: u64) -> Self {
        self.engine.set_max_operations(max);
        self
    }

    /// Cap on call depth per eval.
    pub fn with_max_call_levels(mut self, max: usize) -> Self {
        self.engine.set_max_call_levels(max);
        self
    }

    /// Cap on string size in bytes.
    pub fn with_max_string_size(mut self, max: usize) -> Self {
        self.engine.set_max_string_size(max);
        self
    }

    /// Cap on array length.
    pub fn with_max_array_size(mut self, max: usize) -> Self {
        self.engine.set_max_array_size(max);
        self
    }

    /// Cap on object-map size.
    pub fn with_max_map_size(mut self, max: usize) -> Self {
        self.engine.set_max_map_size(max);
        self
    }

    /// Cap on source length in bytes (host-side, checked before eval).
    pub fn with_max_source_len(mut self, max: usize) -> Self {
        self.max_source_len = max;
        self
    }

    /// Minimal string eval (legacy shape, scope owned by the engine).
    ///
    /// Scope persists across calls (variables survive between evals);
    /// budgets reset per call. Prefer [`Self::compile`] +
    /// [`Self::eval_ast_with_scope`] for the view loop.
    pub fn eval(&mut self, code: &str) -> Result<String> {
        if code.len() > self.max_source_len {
            return Err(Error::ResourceExhausted {
                backend: crate::EngineType::Rhai,
                kind: LimitKind::Source,
            });
        }
        match self
            .engine
            .eval_with_scope::<rhai::Dynamic>(&mut self.scope, code)
        {
            Ok(result) => Ok(result.to_string()),
            Err(e) => Err(map_rhai_error(e)),
        }
    }

    /// Compile once per query (G4): parse + optimize now, evaluate
    /// many times later via [`Self::eval_ast_with_scope`].
    ///
    /// The source-length cap is enforced here (bytes, before
    /// compiling) → [`Error::ResourceExhausted`] with
    /// [`LimitKind::Source`]. Syntax errors surface as [`Error::Rhai`]
    /// (structured validation is G7's job).
    pub fn compile(&self, src: &str) -> Result<CompiledExpr> {
        if src.len() > self.max_source_len {
            return Err(Error::ResourceExhausted {
                backend: crate::EngineType::Rhai,
                kind: LimitKind::Source,
            });
        }
        self.engine
            .compile(src)
            .map(CompiledExpr)
            .map_err(|e| Error::Rhai(e.to_string()))
    }

    /// Evaluate a pre-compiled handle against a caller-owned scope
    /// (G3): the view loop rebinds `this_row`/`payload`/`table` per
    /// row via [`Self::set_var`] while shared state (accumulators,
    /// counters) persists on the same scope.
    ///
    /// Returns the raw [`Dynamic`] — convert with
    /// [`from_dynamic_value`] instead of lossy `to_string()`.
    /// Budgets reset per call (same guarantee as [`Self::eval`]).
    pub fn eval_ast_with_scope(
        &mut self,
        ast: &CompiledExpr,
        scope: &mut Scope,
    ) -> Result<Dynamic> {
        // Same engine, same limiters as `eval` — only the scope moves
        // out to the caller.
        self.engine
            .eval_ast_with_scope::<Dynamic>(scope, &ast.0)
            .map_err(map_rhai_error)
    }

    /// Bind (or rebind) a JSON value in a caller-owned scope (G3).
    ///
    /// `Scope::set_value` upserts: live bindings are rebound in
    /// place, missing names are pushed. The name must satisfy the
    /// shared identifier precondition ([`Error::InvalidName`]
    /// otherwise — same rule as the Python backend, so one view
    /// definition runs on both).
    pub fn set_var(&self, scope: &mut Scope, name: &str, value: &Value) -> Result<()> {
        crate::check_var_name(name)?;
        let dynamic = to_dynamic_value(value)?;
        scope.set_value(name, dynamic);
        Ok(())
    }

    /// Convert an eval result to JSON (G3/G5) — the typed alternative
    /// to `to_string()`. Method (not just the free function) so the
    /// view loop reads fluently: `engine.to_json(&engine.eval_ast_with_scope(&ast, &mut scope)?)?`.
    pub fn to_json(&self, value: &Dynamic) -> Result<Value> {
        from_dynamic_value(value)
    }

    /// Validate one expression without running it (G7): syntax,
    /// `eval()` refusal, then unknown roots — in that order.
    ///
    /// `locator` identifies the expression to the caller
    /// (`columns[3].expression`, `filter_expression`, …) and is
    /// preserved verbatim on every issue. `allowed_roots` lists every
    /// name the caller binds (row roots AND `frozen_now` AND any
    /// accumulator — anything missing is flagged).
    ///
    /// UX only, never the security boundary: unclassifiable nodes
    /// fail OPEN (G1 fuel + G2 sandbox are the backstop). Over-cap
    /// sources are rejected here as `Syntax`-kind length issues.
    pub fn check_expression(
        &self,
        src: &str,
        locator: &str,
        allowed_roots: &[&str],
    ) -> std::result::Result<(), ValidationError> {
        if src.len() > self.max_source_len {
            return Err(ValidationError(vec![ExprIssue {
                locator: locator.to_string(),
                message: format!(
                    "expression too long ({} bytes, max {})",
                    src.len(),
                    self.max_source_len
                ),
                kind: ExprIssueKind::Syntax,
            }]));
        }
        let ast = match self.engine.compile(src) {
            Ok(ast) => ast,
            Err(e) => {
                return Err(ValidationError(vec![ExprIssue {
                    locator: locator.to_string(),
                    message: format!("invalid expression: {e}"),
                    kind: ExprIssueKind::Syntax,
                }]));
            }
        };
        let issues = check_ast(&ast, locator, allowed_roots);
        if issues.is_empty() {
            Ok(())
        } else {
            Err(ValidationError(issues))
        }
    }

    /// Fork a caller-owned scope into an independent copy (G6):
    /// mutating the fork never affects the original and vice versa.
    ///
    /// Snapshot ≡ fork (eager `Scope::clone`, no copy-on-write), so
    /// no separate `snapshot` method exists. Volatile callers fork
    /// per call; views share one scope per query page (the sequential
    /// loop needs no fork). Same engine reused — limits and packages
    /// live on the engine, data on the scope.
    ///
    /// Ordering caveat: accumulator results depend on row order —
    /// meaningful only with an explicit sort (no aggregation
    /// builtins; totals emerge from conservation + order).
    pub fn fork_scope<'a>(&self, scope: &Scope<'a>) -> Scope<'a> {
        scope.clone()
    }

    /// Empty a caller-owned scope (G6): every binding is gone, the
    /// next eval referencing one fails with an unknown-variable
    /// error. Same ordering caveat as [`Self::fork_scope`].
    pub fn clear_scope(&self, scope: &mut Scope) {
        scope.clear();
    }
}

impl Default for BoundedRhaiEngine {
    fn default() -> Self {
        Self::new()
    }
}

/// Build the bare deterministic engine (G2): `new_raw` + exactly the
/// curated packages, with `print`/`debug` neutered to silent no-ops.
///
/// Registered: arithmetic, arrays, maps, strings (+more), logic,
/// basic fns, math, iteration. `type_of` needs no package (native
/// dispatch — verified against rhai 1.26 `func/call.rs`).
///
/// Excluded: `Debugging`, `Time` (`BasicTimePackage`), `LanguageCore`
/// (takes `sleep`/`exit` with it — a `sleep(999)` blocks outside ANY
/// fuel cap), `Blob` (`BasicBlobPackage`), `BitField`. `eval()`
/// cannot be removed (core dispatch): runtime backstop is the G1 fuel
/// caps, refusal is G7 validation. No file resolver is registered, so
/// `import` fails.
fn default_limited_engine(
    max_operations: u64,
    max_call_levels: usize,
    max_string_size: usize,
    max_array_size: usize,
    max_map_size: usize,
) -> Engine {
    let mut engine = Engine::new_raw();
    // Same registration call as quartertone's `bounded_engine` (keeps
    // the future migration diff trivial).
    ArithmeticPackage::new().register_into_engine(&mut engine);
    BasicArrayPackage::new().register_into_engine(&mut engine);
    BasicMapPackage::new().register_into_engine(&mut engine);
    BasicStringPackage::new().register_into_engine(&mut engine);
    MoreStringPackage::new().register_into_engine(&mut engine);
    LogicPackage::new().register_into_engine(&mut engine);
    BasicFnPackage::new().register_into_engine(&mut engine);
    BasicMathPackage::new().register_into_engine(&mut engine);
    BasicIteratorPackage::new().register_into_engine(&mut engine);
    // Documented silent no-ops — server logs stay clean. Note
    // `to_string`/`to_debug` keep working; only the stdout side effect
    // is swallowed.
    engine.on_print(|_| {});
    engine.on_debug(|_, _, _| {});
    register_deterministic_helpers(&mut engine);
    engine.set_max_operations(max_operations);
    engine.set_max_call_levels(max_call_levels);
    engine.set_max_string_size(max_string_size);
    engine.set_max_array_size(max_array_size);
    engine.set_max_map_size(max_map_size);
    engine
}

/// Register the deterministic helpers (G2a): `hash(...)`.
///
/// `hash(value)` is FNV-1a 64-bit over the value's string form —
/// implemented inline (no dependency), fixed parameters, so output
/// is stable across platforms, processes and releases by
/// construction. Deliberately NOT `std`'s `DefaultHasher` (random
/// per-process keys would break the determinism contract). The `u64`
/// digest is cast `as i64` (wraps deterministically above
/// `i64::MAX` — pinned by the empty-string vector in
/// `tests/sandbox.rs`).
///
/// Takes `Dynamic` (not `&str`) so `hash(42)` / `hash(my_map)` work
/// via the string form instead of "function not found". Only
/// deterministically-stringified values are meaningful input; if a
/// future helper needs a separate domain, prefix the input (domain
/// separation by construction, documented here so it isn't forgotten).
/// Entropy stays a per-construction opt-in with an explicit
/// determinism waiver — never a default; no such flag is added here.
///
/// There is deliberately NO `now` helper: the frozen clock is a
/// per-query caller-owned binding (`frozen_now`, see the struct docs),
/// never engine state.
fn register_deterministic_helpers(engine: &mut Engine) {
    engine.register_fn("hash", |value: Dynamic| {
        fnv1a_64(value.to_string().as_bytes()) as i64
    });
}

/// FNV-1a 64-bit: offset basis 14695981039346656037, prime
/// 1099511628211, wrapping multiply.
fn fnv1a_64(bytes: &[u8]) -> u64 {
    const OFFSET_BASIS: u64 = 14695981039346656037;
    const PRIME: u64 = 1099511628211;
    let mut hash = OFFSET_BASIS;
    for byte in bytes {
        hash ^= *byte as u64;
        hash = hash.wrapping_mul(PRIME);
    }
    hash
}
/// [`Error::ResourceExhausted`]; everything else passes through as
/// [`Error::Rhai`] exactly like the legacy engine.
/// Single choke point: rhai limit-hit errors become matchable
/// [`Error::ResourceExhausted`]; everything else passes through as
/// [`Error::Rhai`] exactly like the legacy engine.
fn map_rhai_error(e: Box<EvalAltResult>) -> Error {
    let kind = match *e {
        EvalAltResult::ErrorTooManyOperations(_) => Some(LimitKind::Operations),
        EvalAltResult::ErrorStackOverflow(_) => Some(LimitKind::CallDepth),
        EvalAltResult::ErrorDataTooLarge(ref discriminator, _) => {
            data_too_large_kind(discriminator)
        }
        _ => None,
    };
    match kind {
        Some(kind) => Error::ResourceExhausted {
            backend: crate::EngineType::Rhai,
            kind,
        },
        // Unknown discriminator or non-limit error: preserve today's
        // behaviour rather than misclassify.
        None => Error::Rhai(e.to_string()),
    }
}

/// Classify rhai's stringly `ErrorDataTooLarge` discriminator
/// (verified against rhai 1.26 `eval/data_check.rs`).
fn data_too_large_kind(discriminator: &str) -> Option<LimitKind> {
    if discriminator.starts_with("Length of string") {
        Some(LimitKind::String)
    } else if discriminator.starts_with("Size of array") {
        Some(LimitKind::Array)
    } else if discriminator.starts_with("Size of object map") {
        Some(LimitKind::Map)
    } else {
        None
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn builder_defaults_match_pub_consts() {
        let mut engine = BoundedRhaiEngine::with_defaults();
        assert_eq!(engine.max_source_len, DEFAULT_MAX_SOURCE_LEN);
        // Limits are actually applied: a tiny-budget engine trips fast.
        let mut tiny = BoundedRhaiEngine::new().with_max_operations(10);
        let err = tiny.eval("while true {}").unwrap_err();
        assert!(
            matches!(
                err,
                Error::ResourceExhausted {
                    kind: LimitKind::Operations,
                    ..
                }
            ),
            "expected fuel exhaustion, got: {err:?}"
        );
        // …while the default engine runs ordinary code.
        assert_eq!(engine.eval("40 + 2").unwrap(), "42");
    }

    #[test]
    fn source_len_cap_is_enforced_host_side() {
        let mut engine = BoundedRhaiEngine::new().with_max_source_len(10);
        let err = engine.eval("1 + 2 + 3 + 4").unwrap_err();
        assert!(
            matches!(
                err,
                Error::ResourceExhausted {
                    kind: LimitKind::Source,
                    ..
                }
            ),
            "expected source cap, got: {err:?}"
        );
        assert_eq!(engine.eval("1 + 2").unwrap(), "3");
    }
}