Skip to main content

decl_lang/
engine.rs

1//! Binding, evaluation, validation, and serialization — a port of the
2//! reference implementation's engine.ts. Semantics are the spec's: lazy
3//! slots with cycle detection, taint / root-cause diagnostics,
4//! $referrers universe ordering, canonical JSON output.
5use crate::ast::*;
6#[cfg(feature = "runtime-diagnostics")]
7use crate::evaluation_diagnostics::EventStage;
8#[cfg(feature = "runtime-diagnostics")]
9use crate::expression_diagnostics as expr_diag;
10use crate::qengine::edits::Edits;
11use crate::qengine::graph::{QueryId, QueryPool, ReadSet};
12use crate::qengine::programs::{Programs, Schema};
13use crate::qengine::revisions::Revisions;
14use crate::qengine::rounds::RoundCache;
15use crate::semantics::*;
16use crate::subsume::subsumes;
17use num_traits::Signed;
18use rustc_hash::{FxHashMap, FxHashSet};
19use std::borrow::Cow;
20use std::cell::{Cell, RefCell};
21use std::cmp::Ordering::{self, Equal, Greater, Less};
22use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet};
23use std::rc::{Rc, Weak};
24
25/// a record instance, shared: the engine's unit of binding and forcing
26pub type Inst = Rc<RefCell<RecInst>>;
27
28#[cfg(test)]
29#[path = "../tests/private/query_record_test.rs"]
30mod query_record_tests;
31
32#[cfg(test)]
33#[path = "../tests/private/materialized_cache_test.rs"]
34mod materialized_cache_tests;
35
36#[cfg(test)]
37#[path = "../tests/private/binding_path_test.rs"]
38mod binding_path_tests;
39
40#[cfg(test)]
41#[path = "../tests/private/binding_input_test.rs"]
42mod binding_input_tests;
43
44#[cfg(test)]
45#[path = "../tests/private/binding_lookup_test.rs"]
46mod binding_lookup_tests;
47
48#[cfg(test)]
49#[path = "../tests/private/binding_key_test.rs"]
50mod binding_key_tests;
51
52#[cfg(test)]
53#[path = "../tests/private/record_emission_test.rs"]
54mod record_emission_tests;
55
56// Immutable JSON containers remain owned by `raw` throughout binding. Clone
57// only the item being visited; mutable and expanded inputs keep their eager
58// snapshots and move each item out without an additional clone.
59enum BindingInput<'a, T> {
60    Borrowed(std::slice::Iter<'a, T>),
61    Owned(std::vec::IntoIter<T>),
62}
63
64impl<T: Clone> Iterator for BindingInput<'_, T> {
65    type Item = T;
66
67    fn next(&mut self) -> Option<T> {
68        match self {
69            Self::Borrowed(items) => items.next().cloned(),
70            Self::Owned(items) => items.next(),
71        }
72    }
73
74    fn size_hint(&self) -> (usize, Option<usize>) {
75        match self {
76            Self::Borrowed(items) => items.size_hint(),
77            Self::Owned(items) => items.size_hint(),
78        }
79    }
80}
81
82impl<T: Clone> ExactSizeIterator for BindingInput<'_, T> {}
83
84// Scratch lookup borrows the ordered input snapshot. Only the selected value
85// gains an owner when its slot is constructed. Each reentrant bind owns its
86// own scratch storage, while the immutable schema supplies stable indices.
87enum RecordLookup<'a> {
88    Direct(&'a [(String, Value)]),
89    Named(HashMap<&'a str, &'a Value>),
90    Indexed(IndexedInput<'a>),
91}
92
93impl<'a> RecordLookup<'a> {
94    fn new(entries: &'a [(String, Value)], members: usize, schema: Option<&Schema>) -> Self {
95        if entries.len() <= 1 || members <= 1 {
96            return Self::Direct(entries);
97        }
98        if let Some(schema) = schema.filter(|s| s.names.len() == members) {
99            let mut supplied = IndexedInput::Inline {
100                entries: [None; 8],
101                len: 0,
102            };
103            for (name, value) in entries {
104                if let Some(&index) = schema.names.get(name.as_str()) {
105                    supplied.insert(index, value, members);
106                }
107            }
108            Self::Indexed(supplied)
109        } else {
110            // Bare engines and native duplicate schema names keep the name
111            // lookup: each repeated member receives the same last input.
112            let mut supplied = HashMap::new();
113            for (name, value) in entries {
114                supplied.insert(name.as_str(), value);
115            }
116            Self::Named(supplied)
117        }
118    }
119
120    fn get(&self, index: usize, name: &str) -> Option<&'a Value> {
121        match self {
122            Self::Direct(entries) => entries
123                .iter()
124                .rev()
125                .find_map(|(key, value)| (key == name).then_some(value)),
126            Self::Named(entries) => entries.get(name).copied(),
127            Self::Indexed(entries) => entries.get(index),
128        }
129    }
130}
131
132enum IndexedInput<'a> {
133    // Eight distinct hits require no heap allocation, regardless of schema
134    // width, unknown keys, or repeated occurrences of the same input key.
135    Inline {
136        entries: [Option<(usize, &'a Value)>; 8],
137        len: usize,
138    },
139    Sparse(FxHashMap<usize, &'a Value>),
140    Dense(Vec<Option<&'a Value>>),
141}
142
143impl<'a> IndexedInput<'a> {
144    fn insert(&mut self, index: usize, value: &'a Value, members: usize) {
145        match self {
146            Self::Inline { entries, len } => {
147                if let Some((_, previous)) = entries[..*len]
148                    .iter_mut()
149                    .flatten()
150                    .find(|(key, _)| *key == index)
151                {
152                    *previous = value;
153                    return;
154                }
155                if *len < entries.len() {
156                    entries[*len] = Some((index, value));
157                    *len += 1;
158                    return;
159                }
160                // A dense cell is one pointer; a sparse pair is an index and
161                // pointer. At half density, dense payload does not exceed the
162                // distinct sparse pairs, before any hash-table overhead.
163                if *len + 1 >= members.div_ceil(2) {
164                    let mut dense = vec![None; members];
165                    for &(key, value) in entries.iter().flatten() {
166                        dense[key] = Some(value);
167                    }
168                    dense[index] = Some(value);
169                    *self = Self::Dense(dense);
170                } else {
171                    let mut sparse = FxHashMap::default();
172                    sparse.reserve(*len + 1);
173                    for &(key, value) in entries.iter().flatten() {
174                        sparse.insert(key, value);
175                    }
176                    sparse.insert(index, value);
177                    *self = Self::Sparse(sparse);
178                }
179            }
180            Self::Sparse(entries) => {
181                if let Some(previous) = entries.get_mut(&index) {
182                    *previous = value;
183                } else if entries.len() + 1 >= members.div_ceil(2) {
184                    let mut dense = vec![None; members];
185                    for (&key, &value) in entries.iter() {
186                        dense[key] = Some(value);
187                    }
188                    dense[index] = Some(value);
189                    *self = Self::Dense(dense);
190                } else {
191                    entries.insert(index, value);
192                }
193            }
194            Self::Dense(entries) => entries[index] = Some(value),
195        }
196    }
197
198    fn get(&self, index: usize) -> Option<&'a Value> {
199        match self {
200            Self::Inline { entries, len } => entries[..*len]
201                .iter()
202                .flatten()
203                .find_map(|&(key, value)| (key == index).then_some(value)),
204            Self::Sparse(entries) => entries.get(&index).copied(),
205            Self::Dense(entries) => entries[index],
206        }
207    }
208}
209
210/// the evaluator (§9): binds documents and expressions to types, forces slots
211/// lazily with dependency tracking, validates, serializes
212pub struct Engine {
213    /// the environment the roots live in
214    pub env: Rc<Env>,
215    /// slots whose forcing was deferred to phase 2 (a `$referrers` read, a reference not yet bound)
216    pub deferred_slots: RefCell<Vec<(Inst, String)>>,
217    pub(crate) no_reg: Cell<u32>,
218    pub(crate) phase: Cell<u8>,
219    /// inputs whose fallback failed to bind: later demands are tainted, not re-reported
220    pub failed_inputs: RefCell<HashSet<String>>,
221    // ---- dependency tracking (Phase 6 foundations; docs/tooling/02_repl.md §6) ----
222    // every evaluation step — a slot being computed (`path.member`), a root
223    // being bound (`root:name`), an instance's asserts (`assert:path`) —
224    // records what it read: slots, roots, and `$referrers` queries by type
225    // (`referrers:Type`); diagnostics carry the step that produced them
226    /// the dependency graph: the slot keys each computation read (the session's incremental step)
227    pub(crate) reads: RefCell<FxHashMap<QueryId, ReadSet>>,
228    /// Sessions and retained reference rounds enable dependency recording.
229    /// Ordinary one-shot work avoids the per-slot graph allocation (F21).
230    pub track: Cell<bool>,
231    /// the slots being forced, innermost last: a key already here is a cycle (E5007)
232    pub(crate) computing: RefCell<Vec<QueryId>>,
233    /// every slot by its key, for the dependency graph
234    pub(crate) slots_by_key: RefCell<FxHashMap<QueryId, (Inst, Rc<str>)>>,
235    query_keys: Rc<QueryPool>,
236    /// roots whose binding deferred through `$referrers` in phase 1: bound again after the deferred slots
237    pub deferred_roots: RefCell<Vec<DeferredRoot>>,
238    // ---- `$referrers` is answered in rounds (§7.6) ----
239    // a round answers from a fixed snapshot — round 1 from what phase 1
240    // materialized, every later round from the previous round's whole
241    // universe, kept frozen in `prev` — never from what it creates itself;
242    // rounds repeat until the queried edges stop changing (`Engine::evaluate`)
243    /// the previous round, frozen
244    pub prev: RefCell<Option<Rc<Engine>>>,
245    /// this round's roots once frozen
246    pub(crate) frozen_roots: RefCell<Option<Vec<(String, Value)>>>,
247    /// this round's instances once frozen
248    pub(crate) frozen_registry: RefCell<Option<Vec<Inst>>>,
249    /// the frozen instances by address: what `force_slot` delegates to this round
250    pub(crate) frozen_set: RefCell<FxHashSet<usize>>,
251    /// a copied round's records by canonical path: where an answer is looked up
252    pub(crate) frozen_index: RefCell<Option<FxHashMap<String, Inst>>>,
253    /// the last round: a reference into the snapshot resolves live
254    pub(crate) settled: Cell<bool>,
255    /// the snapshot a round answers from
256    pub(crate) snap: RefCell<Option<Snap>>,
257    /// the edges `T|m` queried so far
258    pub(crate) queried: RefCell<BTreeSet<String>>,
259    /// an inverse index of each edge, `T|m` -> (target path -> its referrers'
260    /// paths): built once from the edge so a `$referrers` query is a lookup,
261    /// not a scan of every candidate's refs (§7.6). Fresh per round.
262    pub(crate) ref_index: RefCell<FxHashMap<String, Rc<FxHashMap<String, Vec<SegPath>>>>>,
263    /// the edges being computed: a query for one of them from inside its own
264    /// computation is unanswerable in this round (the member is excluded)
265    pub(crate) computing_edges: RefCell<HashSet<String>>,
266    /// the depth of the forcing stack when each edge computation began: a
267    /// slot forcing below that depth waits on the answer the edge serves
268    pub(crate) edge_bases: RefCell<Vec<usize>>,
269    /// the environments whose constants this engine forced
270    pub(crate) const_envs: RefCell<Vec<Rc<Env>>>,
271    /// the answers' references into the previous round, by identity
272    pub(crate) snap_refs: RefCell<FxHashMap<usize, (Rc<SegPath>, Rc<Engine>)>>,
273    /// An unmaterialized literal is materialized once by allocation identity.
274    /// Weak raw owners pin that identity without retaining discarded captures;
275    /// Results stay strong while raw literals can be reused. Expired raw
276    /// identities are periodically retired without keeping their result graphs.
277    mat_cache: RefCell<MaterializedCache>,
278    materialized_sweep_at: Cell<usize>,
279    /// Bounded weak sharing for typed-container paths; it owns no runtime values.
280    path_pool: RefCell<PrefixPathPool>,
281    map_shapes: RefCell<MapShapePool>,
282    /// Shared executable programs, enabled by the query evaluator.
283    pub programs: RefCell<Option<Rc<Programs>>>,
284    /// Revision stamps for retained queries.
285    pub revisions: RefCell<Option<Rc<Revisions>>>,
286    /// Retained queries for document edits in a Session.
287    pub edits: RefCell<Option<Rc<Edits>>>,
288    verifying_depth: Cell<Option<usize>>,
289    /// Reference-round reuse state, enabled by the query evaluator.
290    pub round_cache: RefCell<Option<Rc<RoundCache>>>,
291    pub(crate) round_roots: RefCell<Option<HashSet<String>>>,
292    pub(crate) round_resets: RefCell<Vec<Rc<dyn Fn()>>>,
293    pub(crate) round_refs: RefCell<FxHashMap<usize, Rc<SegPath>>>,
294    pub(crate) inverse_refs: RefCell<FxHashMap<usize, Rc<SegPath>>>,
295    // Must drop after every Engine field and every frozen Engine.
296    _lifetime: lifetime::EngineGuard,
297}
298
299// Keep the Rc allocation identity pinned without retaining the raw literal's
300// Vec contents and their captured scopes. A live raw owner must keep the same
301// strong result even when every caller drops its returned handle: recomputing
302// could repeat native callbacks or observe later mutable inputs.
303// A Weak keeps its allocation address unavailable for reuse even after the
304// last raw strong owner drops; array/object variants retain the correct type.
305enum MaterializedLiteral {
306    Array(Weak<Vec<(bool, Value)>>),
307    Object(Weak<Vec<(String, Value)>>),
308}
309type MaterializedCache = FxHashMap<usize, (MaterializedLiteral, Value)>;
310const MATERIALIZED_SWEEP_MIN: usize = 1024;
311impl MaterializedLiteral {
312    fn alive(&self) -> bool {
313        match self {
314            Self::Array(owner) => owner.strong_count() != 0,
315            Self::Object(owner) => owner.strong_count() != 0,
316        }
317    }
318    fn matches(&self, raw: &Value) -> bool {
319        match (self, raw) {
320            (Self::Array(owner), Value::PreArr(v)) => owner.as_ptr() == Rc::as_ptr(v),
321            (Self::Object(owner), Value::PreObj(v)) => owner.as_ptr() == Rc::as_ptr(v),
322            _ => false,
323        }
324    }
325    fn of(raw: &Value) -> Self {
326        match raw {
327            Value::PreArr(v) => Self::Array(Rc::downgrade(v)),
328            Value::PreObj(v) => Self::Object(Rc::downgrade(v)),
329            _ => unreachable!("materialization cache only stores unbound literals"),
330        }
331    }
332}
333
334/// the values `std.array.sort` orders: one primitive kind per call (§13.2)
335fn is_orderable(x: &Value) -> bool {
336    matches!(x, Value::Int(_) | Value::Float(_) | Value::Str(_))
337}
338/// int and float by value, strings by code point (§4.5); a mix of kinds is a domain error
339fn cmp_prim(x: &Value, y: &Value) -> R<Ordering> {
340    match (x, y) {
341        (Value::Str(a), Value::Str(b)) => Ok(a.chars().cmp(b.chars())),
342        (Value::Int(a), Value::Int(b)) => Ok(a.cmp(b)),
343        (Value::Float(a), Value::Float(b)) => Ok(a.partial_cmp(b).unwrap_or(Equal)),
344        (Value::Int(a), Value::Float(b)) => {
345            Ok(a.to_f64().unwrap_or(0.0).partial_cmp(b).unwrap_or(Equal))
346        }
347        (Value::Float(a), Value::Int(b)) => {
348            Ok(a.partial_cmp(&b.to_f64().unwrap_or(0.0)).unwrap_or(Equal))
349        }
350        _ => err_code("std.array.sort: elements must be of one kind", "E5008"),
351    }
352}
353/// a stable sort by key (equal keys keep their order)
354fn sort_keyed(keyed: &mut [(Value, Value)]) -> R<()> {
355    let mut failed: Option<Fail> = None;
356    keyed.sort_by(|p, q| match cmp_prim(&p.0, &q.0) {
357        Ok(o) => o,
358        Err(e) => {
359            if failed.is_none() {
360                failed = Some(e);
361            }
362            Equal
363        }
364    });
365    match failed {
366        Some(e) => Err(e),
367        None => Ok(()),
368    }
369}
370/// one `$referrers` edge: every referrer's path (keyed by its text) with the places its member refers to
371pub(crate) type Edge = BTreeMap<String, (SegPath, Vec<SegPath>)>;
372/// the universe a round answers from
373pub struct Snap {
374    insts: HashMap<String, Vec<Inst>>,
375    pub(crate) edges: HashMap<String, Edge>,
376}
377/// what one round found: whether the queried edges were stable, and what they are
378pub struct Settled {
379    /// no queried edge changed
380    pub stable: bool,
381    /// the queried edges over the round's universe
382    pub edges: HashMap<String, Edge>,
383    /// the edges that changed, sorted
384    pub changed: Vec<String>,
385}
386/// the references under a value: arrays and maps are traversed, records are not (§7.6)
387fn refs_in(v: &Value, out: &mut Vec<SegPath>) {
388    match v {
389        Value::Ref(p) => out.push((**p).clone()),
390        Value::Arr(a) => {
391            for x in &a.borrow().items {
392                refs_in(x, out);
393            }
394        }
395        Value::Map(m) => {
396            for (_, x) in &m.borrow().entries {
397                refs_in(x, out);
398            }
399        }
400        _ => {}
401    }
402}
403fn refs_key(refs: &[SegPath]) -> String {
404    let mut ks: Vec<String> = refs.iter().map(|r| path_str(r, None)).collect();
405    ks.sort();
406    ks.join("\n")
407}
408// a fingerprint of the queried edges, for detecting a round that repeats a
409// previous one (a non-settling cycle, §7.6)
410fn edges_key(edges: &HashMap<String, Edge>) -> String {
411    let mut keys: Vec<&String> = edges.keys().collect();
412    keys.sort();
413    keys.iter()
414        .map(|k| {
415            let e = &edges[*k];
416            let inner: Vec<String> = e
417                .iter()
418                .map(|(pk, (_, refs))| format!("{pk}:{}", refs_key(refs)))
419                .collect();
420            format!("{k}={}", inner.join(";"))
421        })
422        .collect::<Vec<_>>()
423        .join("|")
424}
425fn edge_eq(a: &Edge, b: &Edge) -> bool {
426    a.len() == b.len()
427        && a.iter()
428            .all(|(k, (_, r))| b.get(k).is_some_and(|(_, q)| refs_key(r) == refs_key(q)))
429}
430/// the first referrer (canonical order) whose entry differs between two edges
431fn edge_diff(a: &Edge, b: &Edge) -> String {
432    let mut paths: Vec<&SegPath> = a
433        .keys()
434        .chain(b.keys())
435        .collect::<BTreeSet<_>>()
436        .into_iter()
437        .map(|k| &a.get(k).or_else(|| b.get(k)).unwrap().0)
438        .collect();
439    paths.sort_by(|x, y| path_key_cmp(x, y));
440    for p in paths {
441        let k = path_str(p, None);
442        match (a.get(&k), b.get(&k)) {
443            (Some((_, r)), Some((_, q))) if refs_key(r) == refs_key(q) => {}
444            _ => return k,
445        }
446    }
447    String::new()
448}
449fn group_by_type(insts: &[Inst]) -> HashMap<String, Vec<Inst>> {
450    let mut out: HashMap<String, Vec<Inst>> = HashMap::new();
451    for inst in insts {
452        if let Some(t) = inst.borrow().type_name.clone() {
453            out.entry(t).or_default().push(inst.clone());
454        }
455    }
456    out
457}
458
459/// a root binding kept for phase 2 (its source owned)
460pub struct DeferredRoot {
461    /// the root's name
462    pub name: String,
463    /// what it is bound from
464    pub src: OwnedRootSrc,
465    /// its declared type, resolved
466    pub rt: RT,
467    /// the scope it is bound in
468    pub sc: Scope,
469}
470/// what a deferred root is bound from, owned
471pub enum OwnedRootSrc {
472    /// an output's expression
473    Expr(Rc<Expr>),
474    /// a document
475    Doc(Value),
476}
477
478/// what an evaluation root is bound from: an output's expression, or an
479/// input's document (bound as-is)
480pub enum RootSrc<'a> {
481    /// an output's expression
482    Expr(&'a Rc<Expr>),
483    /// a document
484    Doc(Value),
485}
486
487pub(crate) fn num_cmp(a: &Value, b: &Value) -> Option<Ordering> {
488    match (a, b) {
489        (Value::Int(x), Value::Int(y)) => Some(x.cmp(y)),
490        (Value::Float(x), Value::Float(y)) => x.partial_cmp(y),
491        (Value::Int(x), Value::Float(y)) => x.to_f64()?.partial_cmp(y),
492        (Value::Float(x), Value::Int(y)) => x.partial_cmp(&y.to_f64()?),
493        (Value::Str(x), Value::Str(y)) => Some(x.cmp(y)),
494        _ => None,
495    }
496}
497
498fn exact_float(i: &Num) -> Option<f64> {
499    let f = i.to_f64()?;
500    if !f.is_finite() {
501        return None;
502    }
503    if Num::from_f64(f).as_ref() == Some(i) {
504        Some(f)
505    } else {
506        None
507    }
508}
509
510fn num_s(v: &Value) -> String {
511    match v {
512        Value::Float(f) => js_num_str(*f),
513        Value::Int(i) => i.to_string(),
514        Value::Str(s) => s.to_string(),
515        other => format!("{other:?}"),
516    }
517}
518
519fn lit_display(v: &Value) -> String {
520    match v {
521        Value::Bool(b) => {
522            if *b {
523                "true".into()
524            } else {
525                "false".into()
526            }
527        }
528        Value::Null => "null".into(),
529        other => num_s(other),
530    }
531}
532
533/// the trailing member of a slot key (`r.ports["a"].sel$` -> `sel$`)
534fn member_of_key(key: &str) -> String {
535    if let Some(rest) = key.strip_suffix(']') {
536        if let Some(i) = rest.rfind("[\"") {
537            return rest[i + 2..].to_string();
538        }
539    }
540    match key.rfind('.') {
541        Some(i) => key[i + 1..].to_string(),
542        None => key.to_string(),
543    }
544}
545
546pub(crate) fn to_index(v: &Value) -> R<i64> {
547    match v {
548        Value::Int(i) => i.to_i64().ok_or(()).or_else(|_| err("index out of range")),
549        Value::Float(f) => Ok(*f as i64),
550        _ => err("index must be an integer"),
551    }
552}
553
554fn path_key_cmp(a: &[Seg], b: &[Seg]) -> Ordering {
555    for (x, y) in a.iter().zip(b) {
556        let o = match (x, y) {
557            (Seg::Idx(i), Seg::Idx(j)) => i.cmp(j),
558            (Seg::Idx(_), _) => Less,
559            (_, Seg::Idx(_)) => Greater,
560            _ => seg_text(x).cmp(&seg_text(y)),
561        };
562        if o != Equal {
563            return o;
564        }
565    }
566    a.len().cmp(&b.len())
567}
568
569fn arg<'a>(a: &'a [Value], i: usize, name: &str) -> R<&'a Value> {
570    a.get(i)
571        .ok_or(())
572        .or_else(|_| err(format!("std.{name}: missing argument {i}")))
573}
574
575fn add_num(a: &Value, b: &Value) -> R<Value> {
576    Ok(match (a, b) {
577        (Value::Int(x), Value::Int(y)) => Value::Int(x + y),
578        (Value::Float(x), Value::Float(y)) => Value::Float(x + y),
579        (Value::Int(x), Value::Float(y)) => Value::Float(x.to_f64().unwrap_or(f64::INFINITY) + y),
580        (Value::Float(x), Value::Int(y)) => Value::Float(x + y.to_f64().unwrap_or(f64::INFINITY)),
581        _ => return err("bad operands for +"),
582    })
583}
584
585fn structural_of(v: &Value) -> RT {
586    match v {
587        Value::Bool(_) => ty(RTk::Prim("bool".into())),
588        Value::Int(_) => ty(RTk::Prim("int".into())),
589        Value::Float(_) => ty(RTk::Prim("float".into())),
590        Value::Str(_) => ty(RTk::Prim("string".into())),
591        Value::Null => ty(RTk::Prim("null".into())),
592        Value::Ref(_) => ty(RTk::Ref(ty(RTk::Any))),
593        Value::Arr(a) => {
594            let elem = a
595                .borrow()
596                .items
597                .first()
598                .map(structural_of)
599                .unwrap_or_else(|| ty(RTk::Any));
600            ty(RTk::Arr {
601                elem,
602                lo: None,
603                hi: None,
604            })
605        }
606        Value::Q(q) => ty(RTk::Quantity(q.dim.as_ref().clone())),
607        _ => ty(RTk::Any),
608    }
609}
610
611/// The canonical text of a float in a document (§10.4): the shortest round trip,
612/// a `.0` on a whole number, JavaScript's exponent form.
613pub fn fmt_f(n: f64) -> String {
614    let s = js_num_str(n);
615    if s.contains('.') || s.contains('e') || s.contains('E') {
616        s
617    } else {
618        format!("{s}.0")
619    }
620}
621
622/// Where the serializer's text goes: a `String` keeps all of it, [`Pieces`]
623/// hands what is complete to a writer as it grows.
624trait Emit {
625    fn text(&mut self) -> &mut String;
626    /// A container's entry is complete. All text is final here: a value that
627    /// writes anything is never rolled back, and every enclosing container has
628    /// written its opening bracket.
629    fn entry_done(&mut self);
630}
631
632impl Emit for String {
633    #[inline(always)]
634    fn text(&mut self) -> &mut String {
635        self
636    }
637    #[inline(always)]
638    fn entry_done(&mut self) {}
639}
640
641/// Serialized text drained to a writer whenever a piece of it is complete.
642/// The first write error is kept and the rest of the text discarded.
643struct Pieces<'a> {
644    text: String,
645    to: &'a mut dyn std::io::Write,
646    failed: Option<std::io::Error>,
647}
648
649impl<'a> Pieces<'a> {
650    const PIECE: usize = 256 * 1024;
651
652    fn new(to: &'a mut dyn std::io::Write) -> Self {
653        Self {
654            text: String::with_capacity(Self::PIECE + Self::PIECE / 4),
655            to,
656            failed: None,
657        }
658    }
659    fn drain(&mut self) {
660        if self.failed.is_none() {
661            self.failed = self.to.write_all(self.text.as_bytes()).err();
662        }
663        self.text.clear();
664    }
665    fn finish(mut self) -> std::io::Result<()> {
666        self.drain();
667        self.failed.map_or(Ok(()), Err)
668    }
669}
670
671impl Emit for Pieces<'_> {
672    fn text(&mut self) -> &mut String {
673        &mut self.text
674    }
675    fn entry_done(&mut self) {
676        if self.text.len() >= Self::PIECE {
677            self.drain();
678        }
679    }
680}
681
682/// The names a record was supplied with, asked once per member while the
683/// record is emitted. A short list is scanned; only a long one is indexed, so
684/// emitting a record allocates nothing unless it is wide.
685struct Supplied<'a> {
686    order: &'a [String],
687    index: Option<FxHashSet<&'a str>>,
688}
689
690impl<'a> Supplied<'a> {
691    const SCANNED: usize = 16;
692
693    fn new(order: &'a [String]) -> Self {
694        let index =
695            (order.len() > Self::SCANNED).then(|| order.iter().map(String::as_str).collect());
696        Self { order, index }
697    }
698
699    fn has(&self, name: &str) -> bool {
700        match &self.index {
701            Some(index) => index.contains(name),
702            None => self.order.iter().any(|n| n == name),
703        }
704    }
705}
706
707// Whether binding `text` to a map's key type is known to succeed with no
708// report, read or owner: `string` accepts any text and a pattern accepts what
709// it matches, both by returning the value unchanged. Every other key type, and
710// a pattern that does not match, answers false and takes the full bind, which
711// reports exactly as before.
712fn key_accepts_text(key: &RT, text: &str) -> bool {
713    match &key.k {
714        RTk::Prim(name) => name == "string",
715        RTk::Pattern { re, .. } => re.is_match(text),
716        _ => false,
717    }
718}
719
720impl Engine {
721    /// Number of retained unbound-literal materializations (a diagnostic counter).
722    pub fn cached_literals(&self) -> usize {
723        self.mat_cache.borrow().len()
724    }
725
726    /// Diagnostic cache table/root-handle counts; no entry or reachable-graph scan.
727    #[cfg(feature = "runtime-diagnostics")]
728    pub fn materialization_diagnostics(&self) -> serde_json::Value {
729        let cache = self.mat_cache.borrow();
730        serde_json::json!({
731            "entries": cache.len(), "capacity_entries": cache.capacity(),
732            "raw_identity_strength": "weak; allocation address pinned, raw Vec contents not retained by this owner",
733            "strong_raw_root_handles": 0,
734            "weak_raw_identity_handles": cache.len(),
735            "strong_result_root_handles": cache.len(),
736            "unique_raw_or_result_nodes": null,
737            "meaning": "table-owned handles, not distinct retained nodes/heap bytes; no force, scan, callback or owner clone"
738        })
739    }
740
741    /// Unbound literals may close over replaced records. Keep their auxiliary
742    /// materializations within an edit; retained member values live in slots.
743    pub(crate) fn clear_materialized(&self) {
744        #[cfg(feature = "runtime-diagnostics")]
745        crate::retention_diagnostics::cache_clear(self.mat_cache.borrow().len());
746        let retired = std::mem::take(&mut *self.mat_cache.borrow_mut());
747        self.materialized_sweep_at.set(MATERIALIZED_SWEEP_MIN);
748        drop(retired);
749    }
750
751    /// A dead raw allocation cannot be materialized again. Remove its entry
752    /// before releasing either identity or result, and run native destructors
753    /// only after releasing the cache borrow. Survivors stay strong.
754    fn prune_materialized(&self) {
755        let mut retired = Vec::new();
756        {
757            let mut cache = self.mat_cache.borrow_mut();
758            cache.retain(|_, (raw, result)| {
759                if raw.alive() {
760                    true
761                } else {
762                    retired.push(std::mem::replace(result, Value::Undef));
763                    false
764                }
765            });
766            let live = cache.len().max(MATERIALIZED_SWEEP_MIN);
767            // retain scans capacity. Avoid repeatedly scanning a once-large
768            // table after most raw owners expire, without shrinking on every
769            // sweep or retaining an unbounded scratch buffer.
770            if cache.capacity() > live.saturating_mul(4) {
771                cache.shrink_to(live);
772            }
773            self.materialized_sweep_at
774                .set(cache.len().saturating_mul(2).max(MATERIALIZED_SWEEP_MIN));
775        }
776        drop(retired);
777    }
778
779    /// Request syntax and literal materializations live only for that request.
780    pub(crate) fn transient<T>(&self, f: impl FnOnce() -> T) -> T {
781        struct Restore<'a> {
782            engine: &'a Engine,
783            programs: Option<Rc<Programs>>,
784            materialized: MaterializedCache,
785            materialized_sweep_at: usize,
786        }
787        impl Drop for Restore<'_> {
788            fn drop(&mut self) {
789                *self.engine.programs.borrow_mut() = self.programs.take();
790                #[cfg(feature = "runtime-diagnostics")]
791                crate::retention_diagnostics::cache_restore(
792                    self.engine.mat_cache.borrow().len(),
793                    self.materialized.len(),
794                );
795                let retired = std::mem::replace(
796                    &mut *self.engine.mat_cache.borrow_mut(),
797                    std::mem::take(&mut self.materialized),
798                );
799                self.engine
800                    .materialized_sweep_at
801                    .set(self.materialized_sweep_at);
802                drop(retired);
803            }
804        }
805        let programs = self.programs.borrow_mut().take();
806        if programs.is_some() {
807            *self.programs.borrow_mut() = Some(Rc::new(Programs::default()));
808        }
809        #[cfg(feature = "runtime-diagnostics")]
810        crate::retention_diagnostics::cache_suspend(self.mat_cache.borrow().len());
811        let _restore = Restore {
812            engine: self,
813            programs,
814            materialized: std::mem::take(&mut *self.mat_cache.borrow_mut()),
815            materialized_sweep_at: self.materialized_sweep_at.replace(MATERIALIZED_SWEEP_MIN),
816        };
817        f()
818    }
819
820    /// how many rounds a universe may take to settle (§7.6)
821    pub const ROUNDS: u32 = 8;
822    /// an engine without registering itself as the environment's evaluator
823    pub fn bare(env: Rc<Env>) -> Rc<Engine> {
824        Self::bare_with_queries(env, Rc::new(QueryPool::default()))
825    }
826    pub(crate) fn bare_with_queries(env: Rc<Env>, query_keys: Rc<QueryPool>) -> Rc<Engine> {
827        let eng = Rc::new(Engine {
828            _lifetime: lifetime::EngineGuard::new(),
829            env: env.clone(),
830            deferred_slots: RefCell::new(vec![]),
831            no_reg: Cell::new(0),
832            phase: Cell::new(1),
833            failed_inputs: RefCell::new(HashSet::new()),
834            reads: RefCell::new(FxHashMap::default()),
835            track: Cell::new(false),
836            computing: RefCell::new(vec![]),
837            slots_by_key: RefCell::new(FxHashMap::default()),
838            query_keys,
839            deferred_roots: RefCell::new(vec![]),
840            prev: RefCell::new(None),
841            frozen_roots: RefCell::new(None),
842            frozen_registry: RefCell::new(None),
843            frozen_set: RefCell::new(FxHashSet::default()),
844            frozen_index: RefCell::new(None),
845            settled: Cell::new(false),
846            snap: RefCell::new(None),
847            queried: RefCell::new(BTreeSet::new()),
848            ref_index: RefCell::new(FxHashMap::default()),
849            computing_edges: RefCell::new(HashSet::new()),
850            edge_bases: RefCell::new(vec![]),
851            const_envs: RefCell::new(vec![]),
852            snap_refs: RefCell::new(FxHashMap::default()),
853            mat_cache: RefCell::new(FxHashMap::default()),
854            materialized_sweep_at: Cell::new(MATERIALIZED_SWEEP_MIN),
855            path_pool: RefCell::new(PrefixPathPool::default()),
856            map_shapes: RefCell::new(MapShapePool::default()),
857            programs: RefCell::new(None),
858            revisions: RefCell::new(None),
859            edits: RefCell::new(None),
860            verifying_depth: Cell::new(None),
861            round_cache: RefCell::new(None),
862            round_roots: RefCell::new(None),
863            round_resets: RefCell::new(Vec::new()),
864            round_refs: RefCell::new(FxHashMap::default()),
865            inverse_refs: RefCell::new(FxHashMap::default()),
866        });
867        let w = Rc::downgrade(&eng);
868        *env.tagger.borrow_mut() = Some(Rc::new(move || {
869            w.upgrade()
870                .and_then(|e| e.computing.borrow().last().map(ToString::to_string))
871        }));
872        eng
873    }
874    /// Retain an immutable container path, sharing prefixes within this engine.
875    /// The returned outer Rc is new even when its full prefix chain is shared.
876    pub fn retained_path(&self, segments: &[Seg]) -> Rc<PrefixPath> {
877        self.path_pool.borrow_mut().retain(segments)
878    }
879
880    /// Retain an inline container path, sharing immutable prefix nodes.
881    /// Use this for `ArrV::path` and `MapV::path`; no outer Rc is allocated.
882    pub fn container_path(&self, segments: &[Seg]) -> PrefixPath {
883        self.path_pool.borrow_mut().retain_value(segments)
884    }
885    /// Explicit diagnostic scan of the bounded path pool, outside hot binding.
886    pub fn retained_path_pool_stats(&self) -> PrefixPathPoolStats {
887        self.path_pool.borrow().stats()
888    }
889    pub(crate) fn query_pool(&self) -> Rc<QueryPool> {
890        self.query_keys.clone()
891    }
892    pub(crate) fn query_id(&self, key: &str) -> QueryId {
893        self.query_keys.intern(key)
894    }
895    /// Find an indexed member by its textual query key.
896    ///
897    /// The returned instance is a shared live handle, not a copied record.
898    /// Retaining it retains that value; the query index itself is not exposed.
899    pub fn query_slot(&self, key: &str) -> Option<(Inst, String)> {
900        let id = self.query_keys.lookup(key)?;
901        self.query_slot_id(&id)
902            .map(|(inst, name)| (inst, name.to_string()))
903    }
904    pub(crate) fn query_slot_shared(&self, key: &str) -> Option<(Inst, Rc<str>)> {
905        let id = self.query_keys.lookup(key)?;
906        self.query_slot_id(&id)
907    }
908    pub(crate) fn query_slot_id(&self, key: &QueryId) -> Option<(Inst, Rc<str>)> {
909        self.slots_by_key.borrow().get(key).cloned()
910    }
911    pub(crate) fn register_query_slot(&self, key: &str, inst: Inst, member: Rc<str>) {
912        self.register_query_slot_id(self.query_id(key), inst, member);
913    }
914    pub(crate) fn register_query_slot_id(&self, key: QueryId, inst: Inst, member: Rc<str>) {
915        self.slots_by_key.borrow_mut().insert(key, (inst, member));
916    }
917    pub(crate) fn remove_query_slot(&self, key: &str) {
918        if let Some(id) = self.query_keys.lookup(key) {
919            self.slots_by_key.borrow_mut().remove(&id);
920        }
921    }
922    pub(crate) fn query_reads(&self, key: &str) -> Option<ReadSet> {
923        let id = self.query_keys.lookup(key)?;
924        self.query_reads_id(&id)
925    }
926    pub(crate) fn query_reads_id(&self, key: &QueryId) -> Option<ReadSet> {
927        self.reads.borrow().get(key).cloned()
928    }
929    pub(crate) fn replace_query_reads(&self, key: &str, reads: ReadSet) {
930        let id = self.query_id(key);
931        self.replace_query_reads_id(&id, reads);
932    }
933    // Writers pass an identity obtained from this Engine's evaluation lineage.
934    pub(crate) fn replace_query_reads_id(&self, key: &QueryId, reads: ReadSet) {
935        self.reads.borrow_mut().insert(key.clone(), reads);
936    }
937    pub(crate) fn remove_query_reads(&self, key: &str) {
938        if let Some(id) = self.query_keys.lookup(key) {
939            self.reads.borrow_mut().remove(&id);
940        }
941    }
942    pub(crate) fn sweep_query_ids(&self) {
943        self.query_keys.sweep();
944    }
945    pub(crate) fn maintain_query_ids(&self) {
946        self.query_keys.maintain_transient();
947    }
948    /// Number of computations with a retained read set, including empty sets.
949    pub fn dependency_queries(&self) -> usize {
950        self.reads.borrow().len()
951    }
952    /// Number of registered member slots in the query index.
953    pub fn indexed_slots(&self) -> usize {
954        self.slots_by_key.borrow().len()
955    }
956    /// Export one computation's sorted dependencies without copying other owners.
957    ///
958    /// An absent owner returns `None`; a retained empty read set returns
959    /// `Some(Vec::new())`. Changing the owned result does not change the graph.
960    pub fn query_dependencies_for(&self, key: &str) -> Option<Vec<String>> {
961        let deps = self.query_reads(key)?;
962        let mut dependencies: Vec<_> = deps.iter().map(ToString::to_string).collect();
963        dependencies.sort();
964        Some(dependencies)
965    }
966    /// Export active computation keys, outermost first and innermost last.
967    ///
968    /// The owned snapshot preserves order and does not retain the live stack.
969    pub fn query_stack(&self) -> Vec<String> {
970        self.computing
971            .borrow()
972            .iter()
973            .map(ToString::to_string)
974            .collect()
975    }
976    /// Export a sorted textual dependency graph for explicit inspection.
977    ///
978    /// The returned owned snapshot does not mutate or retain the live graph.
979    /// An owner with an empty list is distinct from an absent owner.
980    pub fn query_dependencies(&self) -> Vec<(String, Vec<String>)> {
981        let mut rows: Vec<_> = self
982            .reads
983            .borrow()
984            .iter()
985            .map(|(owner, deps)| {
986                let mut dependencies: Vec<_> = deps.iter().map(ToString::to_string).collect();
987                dependencies.sort();
988                (owner.to_string(), dependencies)
989            })
990            .collect();
991        rows.sort_by(|a, b| a.0.cmp(&b.0));
992        rows
993    }
994    /// Export the sorted logical keys of registered slots for inspection.
995    pub fn query_slot_keys(&self) -> Vec<String> {
996        let mut keys: Vec<_> = self
997            .slots_by_key
998            .borrow()
999            .keys()
1000            .map(ToString::to_string)
1001            .collect();
1002        keys.sort();
1003        keys
1004    }
1005    /// Inspect query representation storage without copying graph text.
1006    ///
1007    /// Pool counts cover the shared evaluation lineage, including identities
1008    /// held by old runs or snapshots. Read-set and index counts cover this
1009    /// engine. Capacities are usable entries and payload sizes exclude allocator
1010    /// metadata; these counters are not process RSS. This method does not prune.
1011    pub fn query_storage(&self) -> BTreeMap<&'static str, usize> {
1012        let pool = self.query_keys.census();
1013        let reads = self.reads.borrow();
1014        let slots = self.slots_by_key.borrow();
1015        let mut bodies = FxHashSet::default();
1016        let mut unique_edges = 0;
1017        let mut unique_capacity = 0;
1018        let mut shared_bodies = 0;
1019        let mut retained_handles = 0;
1020        for deps in reads.values() {
1021            if let Some(body) = deps.storage() {
1022                if bodies.insert(body.identity) {
1023                    unique_edges += body.len;
1024                    unique_capacity += body.capacity;
1025                    shared_bodies += usize::from(body.strong_count > 1);
1026                    retained_handles += body.strong_count;
1027                }
1028            }
1029        }
1030        BTreeMap::from([
1031            ("pool_entries", pool.entries),
1032            ("pool_live", pool.live),
1033            ("pool_dead", pool.dead),
1034            ("pool_text_bytes", pool.text_bytes),
1035            ("pool_live_text_bytes", pool.live_text_bytes),
1036            ("pool_dead_text_bytes", pool.dead_text_bytes),
1037            ("pool_capacity", pool.capacity),
1038            ("scratch_index_entries", pool.scratch_index_entries),
1039            ("scratch_index_capacity", pool.scratch_index_capacity),
1040            ("scratch_index_entry_bytes", pool.scratch_index_entry_bytes),
1041            ("query_id_bytes", pool.query_id_bytes),
1042            ("query_key_bytes", pool.query_key_bytes),
1043            ("text_handle_bytes", pool.text_handle_bytes),
1044            ("weak_key_bytes", pool.weak_key_bytes),
1045            ("pool_entry_bytes", pool.interner_entry_bytes),
1046            ("read_set_bytes", pool.read_set_bytes),
1047            ("dependency_set_bytes", pool.dependency_set_bytes),
1048            ("rc_header_bytes", pool.rc_header_bytes),
1049            ("read_queries", reads.len()),
1050            ("read_capacity", reads.capacity()),
1051            (
1052                "read_entry_bytes",
1053                std::mem::size_of::<(QueryId, ReadSet)>(),
1054            ),
1055            (
1056                "read_empty",
1057                reads.values().filter(|deps| deps.is_empty()).count(),
1058            ),
1059            ("read_logical_edges", reads.values().map(ReadSet::len).sum()),
1060            (
1061                "read_logical_text_bytes",
1062                reads
1063                    .values()
1064                    .flat_map(|deps| deps.iter())
1065                    .map(|id| id.len())
1066                    .sum(),
1067            ),
1068            ("read_unique_bodies", bodies.len()),
1069            ("read_unique_edges", unique_edges),
1070            ("read_unique_capacity", unique_capacity),
1071            ("read_shared_bodies", shared_bodies),
1072            ("read_body_strong_handles", retained_handles),
1073            ("indexed_slots", slots.len()),
1074            ("slot_index_capacity", slots.capacity()),
1075            (
1076                "slot_index_entry_bytes",
1077                std::mem::size_of::<(QueryId, (Inst, Rc<str>))>(),
1078            ),
1079            ("computing_depth", self.computing.borrow().len()),
1080        ])
1081    }
1082    /// The root's value as this engine's expressions read it: its own universe once frozen.
1083    pub fn root(&self, name: &str) -> Option<Value> {
1084        if let Some(roots) = self.frozen_roots.borrow().as_ref() {
1085            return roots
1086                .iter()
1087                .find(|(n, _)| n == name)
1088                .map(|(_, v)| v.clone());
1089        }
1090        self.env.root(name)
1091    }
1092    /// The key of a slot in the dependency graph: the instance's path and the member's name.
1093    pub fn slot_key(inst: &Inst, name: &str) -> String {
1094        // inst.path is immutable, so path_str is computed once per instance (F21)
1095        let b = inst.borrow();
1096        if b.ps.borrow().is_none() {
1097            let p = path_str(&b.path, None);
1098            *b.ps.borrow_mut() = Some(p);
1099        }
1100        let ps = b.ps.borrow();
1101        format!("{}.{name}", ps.as_ref().unwrap())
1102    }
1103    /// Record that the computation in progress read a slot (dependency tracking).
1104    pub fn record(&self, read: String) {
1105        if !self.track.get()
1106            || self
1107                .verifying_depth
1108                .get()
1109                .is_some_and(|d| self.computing.borrow().len() <= d)
1110        {
1111            return;
1112        }
1113        let computing = self.computing.borrow();
1114        if let Some(top) = computing.last() {
1115            let dependency = self.query_id(&read);
1116            self.reads
1117                .borrow_mut()
1118                .entry(top.clone())
1119                .or_default()
1120                .insert(dependency);
1121        }
1122    }
1123    // An actual tracked force can pass its parent's recorded identity on to
1124    // producer setup. Cached reads keep record's move-only insertion path.
1125    fn record_query(&self, read: &str) -> Option<QueryId> {
1126        if !self.track.get()
1127            || self
1128                .verifying_depth
1129                .get()
1130                .is_some_and(|d| self.computing.borrow().len() <= d)
1131        {
1132            return None;
1133        }
1134        let computing = self.computing.borrow();
1135        let top = computing.last()?;
1136        let dependency = self.query_id(read);
1137        self.reads
1138            .borrow_mut()
1139            .entry(top.clone())
1140            .or_default()
1141            .insert(dependency.clone());
1142        Some(dependency)
1143    }
1144    pub(crate) fn verify_reads<T>(&self, f: impl FnOnce() -> T) -> T {
1145        let previous = self
1146            .verifying_depth
1147            .replace(Some(self.computing.borrow().len()));
1148        let result = f();
1149        self.verifying_depth.set(previous);
1150        result
1151    }
1152    /// Run a computation as a step of the dependency graph, its reads recorded under `key`.
1153    pub fn step<T>(&self, key: &str, f: impl FnOnce() -> T) -> T {
1154        self.step_id(self.query_id(key), f)
1155    }
1156    pub(crate) fn step_id<T>(&self, id: QueryId, f: impl FnOnce() -> T) -> T {
1157        self.computing.borrow_mut().push(id.clone());
1158        if self.track.get() {
1159            if self.round_cache.borrow().is_some() {
1160                self.reads.borrow_mut().remove(&id);
1161            } else {
1162                self.reads.borrow_mut().insert(id, ReadSet::default());
1163            }
1164        }
1165        let r = f();
1166        self.computing.borrow_mut().pop();
1167        r
1168    }
1169    /// The evaluation phase: 1 while the roots bind, 2 while the deferred slots force (§9.3).
1170    pub fn phase(&self) -> u8 {
1171        self.phase.get()
1172    }
1173    /// An engine over an environment, wired in as its constant and expression evaluator.
1174    pub fn new(env: Rc<Env>) -> Rc<Engine> {
1175        let eng = Self::bare(env.clone());
1176        eng.install_hooks(&env, false);
1177        eng
1178    }
1179    /// §4.13 / unit factors: let the environment evaluate constants through this engine
1180    pub fn install_hooks(self: &Rc<Self>, env: &Rc<Env>, with_menv: bool) {
1181        let w = Rc::downgrade(self);
1182        let we: Weak<Env> = Rc::downgrade(env);
1183        *env.const_eval.borrow_mut() =
1184            Some(Rc::new(move |n: &str| match (w.upgrade(), we.upgrade()) {
1185                (Some(eng), Some(e)) => eng.force_const_in(&e, n, ""),
1186                _ => Ok(Value::Null),
1187            }));
1188        let w2 = Rc::downgrade(self);
1189        let we2: Weak<Env> = Rc::downgrade(env);
1190        *env.expr_eval.borrow_mut() = Some(Rc::new(move |x: &Rc<Expr>| match w2.upgrade() {
1191            Some(eng) => eng.ev(
1192                x,
1193                &Scope::new("", if with_menv { we2.upgrade() } else { None }),
1194            ),
1195            None => Ok(Value::Null),
1196        }));
1197    }
1198
1199    // ---------- expression evaluation ----------
1200    /// Evaluate an expression in a scope (§4, §9).
1201    pub fn ev(&self, e: &Rc<Expr>, sc: &Scope) -> R<Value> {
1202        if let Expr::Lit(v) = &**e {
1203            return Ok(v.clone());
1204        }
1205        let programs = self.programs.borrow().clone();
1206        if let Some(p) = programs {
1207            return p.get(e)(self, sc);
1208        }
1209        match &**e {
1210            Expr::Lit(v) => Ok(v.clone()),
1211            Expr::Pattern(s) => Ok(Value::pattern(s.as_str())),
1212            Expr::UnitLit { num, unit } => {
1213                let (key, to_base) = self.env.unit_info(unit).or_else(err)?;
1214                Ok(Value::quantity(key, num * to_base))
1215            }
1216            Expr::Paren(x) => self.ev(x, sc),
1217            Expr::MapComp { key, val, clauses } => {
1218                let mut entries = vec![];
1219                let mut seen = KeysSeen::default();
1220                self.map_comp(
1221                    key,
1222                    val,
1223                    clauses,
1224                    0,
1225                    sc.locals.clone(),
1226                    sc,
1227                    &mut entries,
1228                    &mut seen,
1229                )?;
1230                Ok(Value::PreObj(Rc::new(entries)))
1231            }
1232            Expr::Template(parts) => Ok(Value::Str(self.render(parts, sc)?.into())),
1233            Expr::Name(name) => self.name_value(name, sc),
1234            Expr::Ctx(n) => self.context_value(n, sc),
1235            Expr::Referrers { ty, member } => self.referrers(ty, member, sc),
1236            Expr::Spread(_) => err("spread outside an object literal"),
1237            Expr::Obj(entries) => Ok(Value::PreObj(Rc::new(
1238                entries
1239                    .iter()
1240                    .map(|(k, v)| {
1241                        (
1242                            k.clone(),
1243                            Value::PreVal(Rc::new(PreValV {
1244                                expr: {
1245                                    #[cfg(feature = "runtime-diagnostics")]
1246                                    crate::retention_diagnostics::preval(0);
1247                                    v.clone()
1248                                },
1249                                scope: sc.clone(),
1250                            })),
1251                        )
1252                    })
1253                    .collect(),
1254            ))),
1255            Expr::Arr(items) => Ok(Value::PreArr(Rc::new(
1256                items
1257                    .iter()
1258                    .map(|(sp, v)| {
1259                        (
1260                            *sp,
1261                            Value::PreVal(Rc::new(PreValV {
1262                                expr: {
1263                                    #[cfg(feature = "runtime-diagnostics")]
1264                                    crate::retention_diagnostics::preval(1);
1265                                    v.clone()
1266                                },
1267                                scope: sc.clone(),
1268                            })),
1269                        )
1270                    })
1271                    .collect(),
1272            ))),
1273            Expr::Comp { head, clauses } => {
1274                #[cfg(feature = "runtime-diagnostics")]
1275                let mut attempt =
1276                    expr_diag::Attempt::begin(expr_diag::selected(e, false), self.phase.get());
1277                let evaluate = || {
1278                    let mut items = vec![];
1279                    self.comp(
1280                        head,
1281                        clauses,
1282                        0,
1283                        sc.locals.clone(),
1284                        sc,
1285                        &mut items,
1286                        #[cfg(feature = "runtime-diagnostics")]
1287                        attempt.handle(),
1288                    )?;
1289                    Ok(Value::PreArr(Rc::new(items)))
1290                };
1291                let result = evaluate();
1292                #[cfg(feature = "runtime-diagnostics")]
1293                attempt.finish(&result);
1294                result
1295            }
1296            Expr::If { c, t, f } => {
1297                if self.truthy(&self.ev(c, sc)?)? {
1298                    self.ev(t, sc)
1299                } else {
1300                    self.ev(f, sc)
1301                }
1302            }
1303            Expr::Match { subject, arms } => {
1304                let subj = self.deref(self.ev(subject, sc)?)?;
1305                let run = |arm: &MatchArm| {
1306                    let l2 = sc.locals.with(Rc::from(arm.v.as_str()), subj.clone());
1307                    self.ev(&arm.body, &sc.with_locals(l2))
1308                };
1309                let mut catch_all = None;
1310                for arm in arms {
1311                    let Some(t) = &arm.ty else {
1312                        catch_all = Some(arm);
1313                        continue;
1314                    };
1315                    let menv = sc.menv.clone().unwrap_or_else(|| self.env.clone());
1316                    let rt = menv.resolve(t, None).or_else(err)?;
1317                    if self.member_of(&subj, &rt, sc) {
1318                        return run(arm);
1319                    }
1320                }
1321                if let Some(arm) = catch_all {
1322                    return run(arm);
1323                }
1324                err("match: no arm matched")
1325            }
1326            Expr::Lambda { params, body } => Ok(Value::Clo(Rc::new(Closure {
1327                params: params.clone(),
1328                body: body.clone(),
1329                scope: sc.clone(),
1330            }))),
1331            Expr::Un { op, x } => {
1332                let x = self.ev(x, sc)?;
1333                match op.as_str() {
1334                    "!" => Ok(Value::Bool(!self.truthy(&x)?)),
1335                    "-" => match x {
1336                        Value::Absent => err("absent consumed"),
1337                        Value::Q(mut q) => {
1338                            q.value = -q.value;
1339                            Ok(Value::Q(q))
1340                        }
1341                        Value::Int(i) => Ok(Value::Int(-i)),
1342                        Value::Float(f) => Ok(Value::Float(-f)),
1343                        _ => err("bad operand for unary -"),
1344                    },
1345                    "~" => match x {
1346                        Value::Int(i) => Ok(Value::Int(&(-i) - 1)),
1347                        _ => err("bad operand for ~"),
1348                    },
1349                    _ => err("un"),
1350                }
1351            }
1352            Expr::Bin { op, l, r } => {
1353                if op == "|>" {
1354                    let call = match &**r {
1355                        Expr::Call { fun, args } => {
1356                            let mut a = vec![l.clone()];
1357                            a.extend(args.iter().cloned());
1358                            Expr::Call {
1359                                fun: fun.clone(),
1360                                args: a,
1361                            }
1362                        }
1363                        _ => Expr::Call {
1364                            fun: r.clone(),
1365                            args: vec![l.clone()],
1366                        },
1367                    };
1368                    return self.ev(&Rc::new(call), sc);
1369                }
1370                self.binop(op, l, r, sc)
1371            }
1372            Expr::Member { x, name, safe } => {
1373                let x0 = self.ev(x, sc)?;
1374                if let Value::NsRef(ns) = &x0 {
1375                    return self.ns_value(ns, name, sc);
1376                }
1377                if *safe && matches!(x0, Value::Null | Value::Absent) {
1378                    return Ok(Value::Absent);
1379                }
1380                let d = self.deref(x0)?;
1381                self.access(&d, name)
1382            }
1383            Expr::Index { x, i } => {
1384                // a literal (or document) operand is materialized before it is indexed
1385                let x = self.mat_val(self.ev(x, sc)?)?;
1386                let i = self.ev(i, sc)?;
1387                match &x {
1388                    Value::Arr(a) => {
1389                        let n = to_index(&i)?;
1390                        let a = a.borrow();
1391                        if n < 0 || n as usize >= a.items.len() {
1392                            return err_code(format!("index {n} out of bounds"), "E5005");
1393                        }
1394                        Ok(a.items[n as usize].clone())
1395                    }
1396                    Value::Map(m) => match &i {
1397                        Value::Str(k) => Ok(m.borrow().get(k).cloned().unwrap_or(Value::Absent)),
1398                        _ => Ok(Value::Absent),
1399                    },
1400                    Value::Rec(_) => match &i {
1401                        Value::Str(k) => self.access(&x, k),
1402                        _ => err("index on record needs a string"),
1403                    },
1404                    _ => err("index on non-collection"),
1405                }
1406            }
1407            Expr::Call { fun, args } => {
1408                let mut a = Vec::with_capacity(args.len());
1409                for x in args {
1410                    a.push(self.ev(x, sc)?);
1411                }
1412                let f = self.ev_callee(fun, sc)?;
1413                self.call(&f, a, sc)
1414            }
1415            Expr::With { base, patch } => self.with_expr(base, patch, sc),
1416        }
1417    }
1418
1419    pub(crate) fn name_value(&self, name: &str, sc: &Scope) -> R<Value> {
1420        if let Some(v) = sc.locals.get(name) {
1421            return Ok(v.clone());
1422        }
1423        if let Some(inst) = &sc.inst {
1424            if let Some(v) = self.slot_lookup(inst, name)? {
1425                return Ok(v);
1426            }
1427        }
1428        let menv = sc.menv.clone().unwrap_or_else(|| self.env.clone());
1429        if let Some(v) = self.module_value(&menv, name, &sc.root_name)? {
1430            return Ok(v);
1431        }
1432        if name == "std" {
1433            return Ok(Value::Std(Rc::new(vec![])));
1434        }
1435        if let Some(v) = self.root(name) {
1436            self.record(format!("root:{name}"));
1437            return Ok(v);
1438        }
1439        if let Some(v) = self.demand_input(&menv, name)? {
1440            return Ok(v);
1441        }
1442        err(format!("unknown name {name}"))
1443    }
1444
1445    pub(crate) fn context_value(&self, n: &str, sc: &Scope) -> R<Value> {
1446        // $this / $parent / $root are references (§7.3): each denotes an
1447        // instance that contains the current one, so a value reading would
1448        // be a self-containing value; $key and $path are plain values
1449        let inst = sc.inst.as_ref();
1450        match n {
1451            "$this" => match inst {
1452                Some(i) => Ok(Value::Ref(i.borrow().path.clone())),
1453                None => err_code("$this outside a record instance", "E4090"),
1454            },
1455            "$parent" => match inst.and_then(|i| i.borrow().parent.clone()) {
1456                Some(p) => Ok(Value::Ref(p.borrow().path.clone())),
1457                None => err_code("$parent: the evaluation root has no owner", "E4090"),
1458            },
1459            "$root" => {
1460                if sc.root_name.is_empty() || self.root(&sc.root_name).is_none() {
1461                    return err_code("$root outside an evaluation root", "E4090");
1462                }
1463                Ok(Value::Ref(Rc::new(vec![Seg::Name(sc.root_name.clone())])))
1464            }
1465            "$key" => {
1466                // the key or index under which $this sits in its parent's
1467                // collection: the last path segment, present only when the
1468                // instance is a collection element (not a direct member)
1469                let Some(i) = inst else {
1470                    return err_code("$key: the instance is not a collection element", "E4090");
1471                };
1472                let b = i.borrow();
1473                let Some(parent) = &b.parent else {
1474                    return err_code("$key: the instance is not a collection element", "E4090");
1475                };
1476                if b.path.len() < parent.borrow().path.len() + 2 {
1477                    return err_code("$key: the instance is not a collection element", "E4090");
1478                }
1479                Ok(match b.path.last() {
1480                    Some(Seg::Idx(k)) => Value::Int(Num::from(*k)),
1481                    Some(Seg::Name(k)) | Some(Seg::Key(k)) => {
1482                        Value::Str(SharedText::from_rc(k.clone()))
1483                    }
1484                    None => Value::Absent,
1485                })
1486            }
1487            "$path" => match inst {
1488                Some(i) => Ok(Value::Str(path_str(&i.borrow().path, None).into())),
1489                None => err_code("$path outside a record instance", "E4090"),
1490            },
1491            _ => err(format!("unsupported context var {n}")),
1492        }
1493    }
1494
1495    fn render(&self, parts: &[TPart], sc: &Scope) -> R<String> {
1496        let mut s = String::new();
1497        for p in parts {
1498            match p {
1499                TPart::Text(t) => s.push_str(t),
1500                TPart::Expr(x) => s.push_str(&self.to_str(&self.ev(x, sc)?)?),
1501            }
1502        }
1503        Ok(s)
1504    }
1505
1506    fn comp(
1507        &self,
1508        head: &Rc<Expr>,
1509        clauses: &[ForClause],
1510        ci: usize,
1511        locals: Locals,
1512        sc: &Scope,
1513        out: &mut Vec<(bool, Value)>,
1514        #[cfg(feature = "runtime-diagnostics")] trace: Option<expr_diag::Handle>,
1515    ) -> R<()> {
1516        if ci == clauses.len() {
1517            out.push((
1518                false,
1519                Value::PreVal(Rc::new(PreValV {
1520                    expr: {
1521                        #[cfg(feature = "runtime-diagnostics")]
1522                        crate::retention_diagnostics::preval(2);
1523                        head.clone()
1524                    },
1525                    scope: sc.with_locals(locals),
1526                })),
1527            ));
1528            #[cfg(feature = "runtime-diagnostics")]
1529            expr_diag::emitted(trace);
1530            return Ok(());
1531        }
1532        let cl = &clauses[ci];
1533        #[cfg(feature = "runtime-diagnostics")]
1534        expr_diag::clause(trace, ci, 0);
1535        let it = self.ev(&cl.iter, &sc.with_locals(locals.clone()))?;
1536        for el in self.iterate(&it)? {
1537            #[cfg(feature = "runtime-diagnostics")]
1538            expr_diag::clause(trace, ci, 1);
1539            let l2 = locals.with(Rc::from(cl.v.as_str()), el);
1540            let sc2 = sc.with_locals(l2.clone());
1541            let mut ok = true;
1542            for f in &cl.filters {
1543                #[cfg(feature = "runtime-diagnostics")]
1544                expr_diag::clause(trace, ci, 2);
1545                if !self.truthy(&self.ev(f, &sc2)?)? {
1546                    #[cfg(feature = "runtime-diagnostics")]
1547                    expr_diag::clause(trace, ci, 3);
1548                    ok = false;
1549                    break;
1550                }
1551            }
1552            if ok {
1553                #[cfg(feature = "runtime-diagnostics")]
1554                expr_diag::clause(trace, ci, 4);
1555                self.comp(
1556                    head,
1557                    clauses,
1558                    ci + 1,
1559                    l2,
1560                    sc,
1561                    out,
1562                    #[cfg(feature = "runtime-diagnostics")]
1563                    trace,
1564                )?;
1565            }
1566        }
1567        Ok(())
1568    }
1569
1570    fn map_comp(
1571        &self,
1572        key: &Rc<Expr>,
1573        val: &Rc<Expr>,
1574        clauses: &[ForClause],
1575        ci: usize,
1576        locals: Locals,
1577        sc: &Scope,
1578        out: &mut Vec<(String, Value)>,
1579        seen: &mut KeysSeen,
1580    ) -> R<()> {
1581        if ci == clauses.len() {
1582            let sc2 = sc.with_locals(locals);
1583            let Value::Str(k) = self.ev(key, &sc2)? else {
1584                return err("map key must be string");
1585            };
1586            let k = k.to_string();
1587            if !seen.admits(out, &k) {
1588                return err_code(format!("duplicate key {k}"), "E5004");
1589            }
1590            let v = self.ev(val, &sc2)?;
1591            out.push((k, v));
1592            return Ok(());
1593        }
1594        let cl = &clauses[ci];
1595        let it = self.ev(&cl.iter, &sc.with_locals(locals.clone()))?;
1596        for el in self.iterate(&it)? {
1597            let l2 = locals.with(Rc::from(cl.v.as_str()), el);
1598            let sc2 = sc.with_locals(l2.clone());
1599            let mut ok = true;
1600            for f in &cl.filters {
1601                if !self.truthy(&self.ev(f, &sc2)?)? {
1602                    ok = false;
1603                    break;
1604                }
1605            }
1606            if ok {
1607                self.map_comp(key, val, clauses, ci + 1, l2, sc, out, seen)?;
1608            }
1609        }
1610        Ok(())
1611    }
1612
1613    /// Whether a value belongs to a type, as `in` and `match` decide it (§4.9).
1614    pub fn member_of(&self, v: &Value, rt: &RT, sc: &Scope) -> bool {
1615        if let Value::Rec(r) = v {
1616            let vrt = r.borrow().rt.clone();
1617            return subsumes(&self.env, &vrt, rt);
1618        }
1619        let mark = self.env.diag_len();
1620        self.no_reg.set(self.no_reg.get() + 1);
1621        let ok = self
1622            .bind(v.clone(), rt, &[Seg::Name("<match>".into())], None, sc)
1623            .is_ok();
1624        self.no_reg.set(self.no_reg.get() - 1);
1625        self.env.diag_truncate(mark);
1626        ok
1627    }
1628
1629    fn ev_callee(&self, e: &Rc<Expr>, sc: &Scope) -> R<Value> {
1630        let programs = self.programs.borrow().clone();
1631        if let Some(p) = programs {
1632            return p.callee(e)(self, sc);
1633        }
1634        if let Expr::Member { x, name, .. } = &**e {
1635            let x = self.ev_callee(x, sc)?;
1636            return match &x {
1637                Value::Std(p) => {
1638                    let mut p2 = (**p).clone();
1639                    p2.push(name.clone());
1640                    Ok(Value::Std(Rc::new(p2)))
1641                }
1642                Value::NsRef(ns) => self.ns_value(ns, name, sc),
1643                _ => {
1644                    let d = self.deref(x)?;
1645                    self.access(&d, name)
1646                }
1647            };
1648        }
1649        self.ev(e, sc)
1650    }
1651
1652    pub(crate) fn module_value(
1653        &self,
1654        menv: &Rc<Env>,
1655        name: &str,
1656        root_name: &str,
1657    ) -> R<Option<Value>> {
1658        if menv.consts.borrow().contains_key(name) {
1659            return Ok(Some(self.force_const_in(menv, name, root_name)?));
1660        }
1661        let f = menv.funcs.borrow().get(name).cloned();
1662        if let Some(f) = f {
1663            return Ok(Some(Value::Clo(Rc::new(Closure {
1664                params: f.params.iter().map(|p| p.name.clone()).collect(),
1665                body: f.body.clone(),
1666                scope: Scope::new(root_name, Some(menv.clone())),
1667            }))));
1668        }
1669        let im = menv.imports.borrow().get(name).cloned();
1670        if let Some(im) = im {
1671            if let Some(v) = self.module_value(&im.env, &im.name, root_name)? {
1672                return Ok(Some(v));
1673            }
1674            if let Some(v) = self.root(&im.name) {
1675                self.record(format!("root:{}", im.name));
1676                return Ok(Some(v)); // imported output/input root
1677            }
1678            return self.demand_input(&im.env, &im.name);
1679        }
1680        let ns = menv.namespaces.borrow().get(name).cloned();
1681        if let Some((_, exports)) = ns {
1682            return Ok(Some(Value::NsRef(Rc::new(NsRefV { exports }))));
1683        }
1684        Ok(None)
1685    }
1686
1687    pub(crate) fn ns_value(&self, ns: &NsRefV, name: &str, sc: &Scope) -> R<Value> {
1688        let ex = ns.exports.borrow().get(name).cloned();
1689        let Some(ex) = ex else {
1690            return err(format!("namespace has no export {name}"));
1691        };
1692        if let Some(v) = self.module_value(&ex.env, &ex.name, &sc.root_name)? {
1693            return Ok(v);
1694        }
1695        if let Some(v) = self.root(&ex.name) {
1696            self.record(format!("root:{}", ex.name));
1697            return Ok(v);
1698        }
1699        if let Some(v) = self.demand_input(&ex.env, &ex.name)? {
1700            return Ok(v);
1701        }
1702        err(format!("{name} is not a value"))
1703    }
1704    // an input demanded by evaluation (§5.6, §9.4): the bound document if
1705    // the tool bound one, else its fallback — bound on first demand and
1706    // memoized as a root; a fallback-less unbound input is E5006 at the
1707    // demanding path. Returns None when `name` is not an input.
1708    /// An input read by an output: the bound document, its fallback, or none (§5.6, §9.4).
1709    pub fn demand_input(&self, menv: &Rc<Env>, name: &str) -> R<Option<Value>> {
1710        let decl = menv.inputs.borrow().get(name).cloned();
1711        let Some((ty_ast, fallback)) = decl else {
1712            return Ok(None);
1713        };
1714        self.record(format!("root:{name}"));
1715        if let Some(v) = self.root(name) {
1716            return Ok(Some(v));
1717        }
1718        if self.failed_inputs.borrow().contains(name) {
1719            return Err(Fail::Taint);
1720        }
1721        let Some(fallback) = fallback else {
1722            return err_code(format!("input {name} is not bound"), "E5006");
1723        };
1724        let sc = Scope::new(name, Some(menv.clone()));
1725        let produce = || -> R<Value> {
1726            let v = self.ev(&fallback, &sc)?;
1727            let rt = menv.resolve(&ty_ast, None).or_else(err)?;
1728            self.bind(v, &rt, &[Seg::Name(Rc::from(name))], None, &sc)
1729        };
1730        let bound = self.step(&format!("root:{name}"), || {
1731            match self.edits.borrow().as_ref() {
1732                Some(edits) => edits.root(self, name, &RootSrc::Expr(&fallback), produce),
1733                None => produce(),
1734            }
1735        });
1736        match bound {
1737            Ok(v) => {
1738                self.env.set_root(name, v.clone());
1739                Ok(Some(v))
1740            }
1741            Err(e) => {
1742                if matches!(e, Fail::Taint) {
1743                    self.failed_inputs.borrow_mut().insert(name.to_string());
1744                }
1745                Err(e)
1746            }
1747        }
1748    }
1749    // bind an evaluation root (an output's expression, or an input's
1750    // document / fallback): a failing root is reported at its own path and
1751    // left unset — its demanders are tainted, nothing else is
1752    /// Bind a root — an output's expression or an input's document — to its declared type (§9.2).
1753    /// Whether this root needs binding in the retained round.
1754    pub fn should_bind_root(&self, name: &str) -> bool {
1755        self.round_roots
1756            .borrow()
1757            .as_ref()
1758            .is_none_or(|roots| roots.contains(name))
1759    }
1760    /// Bind a root, retaining its source when it must defer to phase two.
1761    pub fn bind_root(&self, name: &str, src: RootSrc, rt: &RT, sc: &Scope) {
1762        #[cfg(feature = "runtime-diagnostics")]
1763        use crate::root_binding_diagnostics::{Completion, Outcome, RootAttempt, SourceKind};
1764        // Declare diagnostic guards before runtime locals; their final boundary
1765        // includes local releases without extending any source/value lifetime.
1766        #[cfg(feature = "runtime-diagnostics")]
1767        let root_diagnostic = RootAttempt::new(
1768            name,
1769            self.phase.get(),
1770            match &src {
1771                RootSrc::Expr(_) => SourceKind::Expr,
1772                RootSrc::Doc(_) => SourceKind::Doc,
1773            },
1774        );
1775        if !self.should_bind_root(name) {
1776            #[cfg(feature = "runtime-diagnostics")]
1777            root_diagnostic.skipped();
1778            return;
1779        }
1780        let keep = match &src {
1781            RootSrc::Expr(e) => OwnedRootSrc::Expr((*e).clone()),
1782            RootSrc::Doc(v) => OwnedRootSrc::Doc(v.clone()),
1783        };
1784        let produce = || -> R<Value> {
1785            #[cfg(feature = "runtime-diagnostics")]
1786            root_diagnostic.source_started();
1787            let raw = match &src {
1788                RootSrc::Expr(e) => self.ev(e, sc)?,
1789                RootSrc::Doc(v) => v.clone(),
1790            };
1791            #[cfg(feature = "runtime-diagnostics")]
1792            root_diagnostic.source_evaluated();
1793            let result = self.bind(raw, rt, &[Seg::Name(Rc::from(name))], None, sc);
1794            #[cfg(feature = "runtime-diagnostics")]
1795            root_diagnostic.binding_returned();
1796            result
1797        };
1798        let bound = self.step(&format!("root:{name}"), || {
1799            match self.edits.borrow().as_ref() {
1800                Some(edits) => edits.root(self, name, &src, produce),
1801                None => produce(),
1802            }
1803        });
1804        #[cfg(feature = "runtime-diagnostics")]
1805        root_diagnostic.dispatch_returned(match &bound {
1806            Ok(_) => Outcome::Bound,
1807            Err(Fail::Defer) => Outcome::Defer,
1808            Err(Fail::Eval(_)) => Outcome::EvalError,
1809            Err(Fail::Taint) => Outcome::Taint,
1810        });
1811        match bound {
1812            Ok(v) => {
1813                self.env.set_root(name, v);
1814                #[cfg(feature = "runtime-diagnostics")]
1815                root_diagnostic.body_returned(Completion::Published);
1816            }
1817            Err(Fail::Eval(e)) => {
1818                self.env.report(Diag {
1819                    severity: "error".into(),
1820                    id: None,
1821                    message: e.msg,
1822                    path: name.to_string(),
1823                    code: e.code,
1824                    loc: None,
1825                    by: None,
1826                });
1827                #[cfg(feature = "runtime-diagnostics")]
1828                root_diagnostic.body_returned(Completion::EvalError);
1829            }
1830            Err(Fail::Defer) => {
1831                if self.phase.get() < 2 {
1832                    self.deferred_roots.borrow_mut().push(DeferredRoot {
1833                        name: name.to_string(),
1834                        src: keep,
1835                        rt: rt.clone(),
1836                        sc: sc.clone(),
1837                    });
1838                    #[cfg(feature = "runtime-diagnostics")]
1839                    root_diagnostic.body_returned(Completion::DeferredQueued);
1840                } else {
1841                    #[cfg(feature = "runtime-diagnostics")]
1842                    root_diagnostic.body_returned(Completion::DeferIgnored);
1843                }
1844            }
1845            Err(Fail::Taint) => {
1846                #[cfg(feature = "runtime-diagnostics")]
1847                root_diagnostic.body_returned(Completion::Taint);
1848            }
1849        }
1850    }
1851    /// phase 2: the roots that deferred are bound again (after the deferred slots)
1852    pub fn bind_deferred_roots(&self) {
1853        let pending: Vec<DeferredRoot> = self.deferred_roots.borrow_mut().drain(..).collect();
1854        for d in pending {
1855            match &d.src {
1856                OwnedRootSrc::Expr(e) => self.bind_root(&d.name, RootSrc::Expr(e), &d.rt, &d.sc),
1857                OwnedRootSrc::Doc(v) => {
1858                    self.bind_root(&d.name, RootSrc::Doc(v.clone()), &d.rt, &d.sc)
1859                }
1860            }
1861        }
1862    }
1863
1864    pub(crate) fn q_arith(&self, op: &str, l: &Value, r: &Value) -> R<Value> {
1865        let dim_or_1 = |d: &str| {
1866            if d.is_empty() {
1867                "1".to_string()
1868            } else {
1869                d.to_string()
1870            }
1871        };
1872        match op {
1873            "+" | "-" => {
1874                let (Value::Q(lq), Value::Q(rq)) = (l, r) else {
1875                    return err(format!("`{op}` mixes quantity and plain number"));
1876                };
1877                let (ld, lv, rd, rv) = (&lq.dim, &lq.value, &rq.dim, &rq.value);
1878                if ld != rd {
1879                    return err(format!(
1880                        "quantity dimension mismatch: {} vs {}",
1881                        dim_or_1(ld.as_str()),
1882                        dim_or_1(rd.as_str())
1883                    ));
1884                }
1885                Ok(Value::Q(Box::new(QuantityValue {
1886                    dim: ld.clone(),
1887                    value: if op == "+" { lv + rv } else { lv - rv },
1888                })))
1889            }
1890            "<" | "<=" | ">" | ">=" => {
1891                let (Value::Q(lq), Value::Q(rq)) = (l, r) else {
1892                    return err("quantity dimension mismatch in comparison");
1893                };
1894                let (ld, lv, rd, rv) = (&lq.dim, &lq.value, &rq.dim, &rq.value);
1895                if ld != rd {
1896                    return err("quantity dimension mismatch in comparison");
1897                }
1898                Ok(Value::Bool(match op {
1899                    "<" => lv < rv,
1900                    "<=" => lv <= rv,
1901                    ">" => lv > rv,
1902                    _ => lv >= rv,
1903                }))
1904            }
1905            _ => {
1906                let mag = |v: &Value| -> Option<f64> {
1907                    match v {
1908                        Value::Q(q) => Some(q.value),
1909                        Value::Int(i) => Some(i.to_f64().unwrap_or(f64::INFINITY)),
1910                        Value::Float(f) => Some(*f),
1911                        _ => None,
1912                    }
1913                };
1914                let (Some(lm), Some(rm)) = (mag(l), mag(r)) else {
1915                    return err(format!("bad operands for {op}"));
1916                };
1917                if op == "/" && rm == 0.0 {
1918                    return err_code("division by zero", "E5001");
1919                }
1920                let dv = |v: &Value| match v {
1921                    Value::Q(q) => vec_of_key(q.dim.as_str()),
1922                    _ => DimVec::new(),
1923                };
1924                let vec = vec_combine(&dv(l), &dv(r), if op == "*" { 1 } else { -1 });
1925                let value = if op == "*" { lm * rm } else { lm / rm };
1926                if !value.is_finite() {
1927                    return err_code("non-finite", "E5002");
1928                }
1929                let key = key_of_vec(&vec);
1930                Ok(if key.is_empty() {
1931                    Value::Float(value)
1932                } else {
1933                    Value::quantity(key, value)
1934                })
1935            }
1936        }
1937    }
1938
1939    /// the items of an array (or a range); an error for anything else
1940    pub fn iterate(&self, v: &Value) -> R<Vec<Value>> {
1941        match v {
1942            Value::PreArr(_) | Value::PreObj(_) => self.mat_arr(v),
1943            Value::Arr(a) => Ok(a.borrow().items.clone()),
1944            Value::Range(range) => {
1945                let (Value::Int(lo), Value::Int(hi)) = (&range.lo, &range.hi) else {
1946                    return err("range bounds must be integers");
1947                };
1948                let hi = if range.excl { hi.clone() } else { hi + 1 };
1949                let mut out = vec![];
1950                let mut i = lo.clone();
1951                while i < hi {
1952                    out.push(Value::Int(i.clone()));
1953                    i += 1;
1954                }
1955                Ok(out)
1956            }
1957            _ => err("not iterable"),
1958        }
1959    }
1960
1961    pub(crate) fn truthy(&self, v: &Value) -> R<bool> {
1962        match v {
1963            Value::Bool(b) => Ok(*b),
1964            _ => err("non-bool condition"),
1965        }
1966    }
1967
1968    fn binop(&self, op: &str, le: &Rc<Expr>, re: &Rc<Expr>, sc: &Scope) -> R<Value> {
1969        match op {
1970            "&&" => {
1971                return if self.truthy(&self.ev(le, sc)?)? {
1972                    Ok(Value::Bool(self.truthy(&self.ev(re, sc)?)?))
1973                } else {
1974                    Ok(Value::Bool(false))
1975                };
1976            }
1977            "||" => {
1978                return if self.truthy(&self.ev(le, sc)?)? {
1979                    Ok(Value::Bool(true))
1980                } else {
1981                    Ok(Value::Bool(self.truthy(&self.ev(re, sc)?)?))
1982                };
1983            }
1984            "??" => {
1985                let l = self.ev(le, sc)?;
1986                return if matches!(l, Value::Absent | Value::Null) {
1987                    self.ev(re, sc)
1988                } else {
1989                    Ok(l)
1990                };
1991            }
1992            _ => {}
1993        }
1994        self.apply_bin(op, self.ev(le, sc)?, self.ev(re, sc)?)
1995    }
1996
1997    fn equal_values(&self, a: &Value, b: &Value) -> bool {
1998        fn observe(eng: &Engine, v: &Value) {
1999            match v {
2000                Value::Rec(inst) => {
2001                    eng.record(format!("value:{}", path_str(&inst.borrow().path, None)))
2002                }
2003                Value::Arr(a) => {
2004                    for v in &a.borrow().items {
2005                        observe(eng, v);
2006                    }
2007                }
2008                Value::Map(m) => {
2009                    for v in m.borrow().entries.values() {
2010                        observe(eng, v);
2011                    }
2012                }
2013                _ => {}
2014            }
2015        }
2016        if self.edits.borrow().is_some()
2017            && self.track.get()
2018            && !self.computing.borrow().is_empty()
2019            && matches!(
2020                (a, b),
2021                (Value::Rec(_), Value::Rec(_))
2022                    | (Value::Arr(_), Value::Arr(_))
2023                    | (Value::Map(_), Value::Map(_))
2024            )
2025        {
2026            observe(self, a);
2027            observe(self, b);
2028        }
2029        value_eq(a, b)
2030    }
2031    pub(crate) fn apply_bin(&self, op: &str, l: Value, mut r: Value) -> R<Value> {
2032        match op {
2033            ".." | "..<" => return Ok(Value::range(l, r, op == "..<")),
2034            "matches" => {
2035                let (Value::Str(s), Value::Pat(p)) = (&l, &r) else {
2036                    return err("matches needs a string and a pattern");
2037                };
2038                if let Some(bad) = pattern_error(p.as_ref()) {
2039                    return err_code(format!("malformed pattern /{p}/: {bad}"), "E4119");
2040                }
2041                let re = compile_pattern(p.as_ref()).or_else(err)?;
2042                return Ok(Value::Bool(re.is_match(s)));
2043            }
2044            // a literal operand is materialized: equality is structural over values (§4.5)
2045            "==" => {
2046                return Ok(Value::Bool(
2047                    self.equal_values(&self.mat_val(l)?, &self.mat_val(r)?),
2048                ))
2049            }
2050            "!=" => {
2051                return Ok(Value::Bool(
2052                    !self.equal_values(&self.mat_val(l)?, &self.mat_val(r)?),
2053                ))
2054            }
2055            "in" => {
2056                if matches!(r, Value::Ref(_)) {
2057                    r = self.deref(r)?; // the container may be reached through a reference ($this, $parent)
2058                }
2059                return match &r {
2060                    Value::Range(range) => {
2061                        let ge = matches!(num_cmp(&l, &range.lo), Some(Greater | Equal));
2062                        let hi_ok = if range.excl {
2063                            num_cmp(&l, &range.hi) == Some(Less)
2064                        } else {
2065                            matches!(num_cmp(&l, &range.hi), Some(Less | Equal))
2066                        };
2067                        Ok(Value::Bool(ge && hi_ok))
2068                    }
2069                    Value::PreArr(_) | Value::PreObj(_) => Ok(Value::Bool(
2070                        self.mat_arr(&r)?.iter().any(|x| self.equal_values(&l, x)),
2071                    )),
2072                    Value::Arr(a) => Ok(Value::Bool(
2073                        a.borrow().items.iter().any(|x| self.equal_values(&l, x)),
2074                    )),
2075                    Value::Map(m) => {
2076                        let Value::Str(k) = &l else {
2077                            return Ok(Value::Bool(false));
2078                        };
2079                        Ok(Value::Bool(m.borrow().has(k)))
2080                    }
2081                    Value::Rec(rec) => {
2082                        let Value::Str(k) = &l else {
2083                            return Ok(Value::Bool(false));
2084                        };
2085                        let has = rec.borrow().has_slot(k);
2086                        Ok(Value::Bool(
2087                            has && self.force_state(rec, k) != SlotState::Absent,
2088                        ))
2089                    }
2090                    _ => err("in: bad container"),
2091                };
2092            }
2093            _ => {}
2094        }
2095        if l.is_absent() || r.is_absent() {
2096            return err("absent consumed");
2097        }
2098        if (matches!(l, Value::Q(_)) || matches!(r, Value::Q(_)))
2099            && ["+", "-", "*", "/", "<", "<=", ">", ">="].contains(&op)
2100        {
2101            return self.q_arith(op, &l, &r);
2102        }
2103        let both_i = matches!((&l, &r), (Value::Int(_), Value::Int(_)));
2104        let both_f = matches!((&l, &r), (Value::Float(_), Value::Float(_)));
2105        let both_s = matches!((&l, &r), (Value::Str(_), Value::Str(_)));
2106        match (op, &l, &r) {
2107            ("+", Value::Str(a), Value::Str(b)) => Ok(Value::Str(format!("{a}{b}").into())),
2108            ("+", Value::Int(a), Value::Int(b)) => Ok(Value::Int(a + b)),
2109            ("+", Value::Float(a), Value::Float(b)) => Ok(Value::Float(a + b)),
2110            ("-", Value::Int(a), Value::Int(b)) => Ok(Value::Int(a - b)),
2111            ("-", Value::Float(a), Value::Float(b)) => Ok(Value::Float(a - b)),
2112            ("*", Value::Int(a), Value::Int(b)) => Ok(Value::Int(a * b)),
2113            ("*", Value::Float(a), Value::Float(b)) => Ok(Value::Float(a * b)),
2114            ("/", Value::Int(a), Value::Int(b)) => {
2115                if b.is_zero() {
2116                    return err_code("division by zero", "E5001");
2117                }
2118                Ok(Value::Int(a / b))
2119            }
2120            ("/", Value::Float(a), Value::Float(b)) => {
2121                if *b == 0.0 {
2122                    return err_code("division by zero", "E5001");
2123                }
2124                let q = a / b;
2125                if !q.is_finite() {
2126                    return err_code("non-finite", "E5002");
2127                }
2128                Ok(Value::Float(q))
2129            }
2130            ("%", Value::Int(a), Value::Int(b)) => {
2131                if b.is_zero() {
2132                    return err_code("mod zero", "E5001");
2133                }
2134                Ok(Value::Int(a % b))
2135            }
2136            ("<" | "<=" | ">" | ">=", _, _) if both_i || both_f || both_s => {
2137                let o = num_cmp(&l, &r);
2138                Ok(Value::Bool(matches!(
2139                    (op, o),
2140                    ("<", Some(Less))
2141                        | ("<=", Some(Less | Equal))
2142                        | (">", Some(Greater))
2143                        | (">=", Some(Greater | Equal))
2144                )))
2145            }
2146            ("&", Value::Int(a), Value::Int(b)) => Ok(Value::Int(a & b)),
2147            ("|", Value::Int(a), Value::Int(b)) => Ok(Value::Int(a | b)),
2148            ("^", Value::Int(a), Value::Int(b)) => Ok(Value::Int(a ^ b)),
2149            ("<<" | ">>", Value::Int(a), Value::Int(b)) => {
2150                if b.is_negative() {
2151                    return err_code("negative shift count", "E5003");
2152                }
2153                let n = b
2154                    .to_usize()
2155                    .ok_or(())
2156                    .or_else(|_| err("shift count too large"))?;
2157                Ok(Value::Int(if op == "<<" { a << n } else { a >> n }))
2158            }
2159            _ => err(format!("bad operands for {op}")),
2160        }
2161    }
2162
2163    pub(crate) fn to_str(&self, v: &Value) -> R<String> {
2164        match v {
2165            Value::Str(s) => Ok(s.to_string()),
2166            Value::Bool(b) => Ok(if *b { "true".into() } else { "false".into() }),
2167            Value::Int(i) => Ok(i.to_string()),
2168            Value::Float(f) => Ok(js_num_str(*f)),
2169            _ => err("template: non-convertible"),
2170        }
2171    }
2172
2173    // A frozen member may return references into an even older snapshot.
2174    // Carry their owners into the caller before it navigates those values.
2175    fn inherit_snapshot_refs(&self, value: &Value, owner: &Engine) {
2176        match value {
2177            Value::Ref(p) => {
2178                let key = Rc::as_ptr(p) as usize;
2179                if let Some(entry) = owner.snap_refs.borrow().get(&key) {
2180                    self.snap_refs.borrow_mut().insert(key, entry.clone());
2181                }
2182                if let Some(path) = owner.inverse_refs.borrow().get(&key) {
2183                    self.inverse_refs.borrow_mut().insert(key, path.clone());
2184                }
2185            }
2186            Value::Arr(a) => {
2187                for v in &a.borrow().items {
2188                    self.inherit_snapshot_refs(v, owner);
2189                }
2190            }
2191            Value::Map(m) => {
2192                for (_, v) in m.borrow().entries.iter() {
2193                    self.inherit_snapshot_refs(v, owner);
2194                }
2195            }
2196            _ => {}
2197        }
2198    }
2199
2200    /// Read through a reference to the value it names (§7.4).
2201    pub fn deref(&self, v: Value) -> R<Value> {
2202        if let Value::Ref(p) = &v {
2203            let key = Rc::as_ptr(p) as usize;
2204            if self.round_cache.borrow().is_some()
2205                && (self.inverse_refs.borrow().contains_key(&key)
2206                    || self.snap_refs.borrow().contains_key(&key))
2207            {
2208                self.record("round:reference".into());
2209                if self.inverse_refs.borrow().contains_key(&key)
2210                    && !self.round_refs.borrow().contains_key(&key)
2211                {
2212                    self.record("round:nested".into());
2213                }
2214            }
2215            let snap = if self.settled.get() {
2216                None
2217            } else {
2218                self.snap_refs
2219                    .borrow()
2220                    .get(&(Rc::as_ptr(p) as usize))
2221                    .map(|(_, e)| e.clone())
2222            };
2223            let target = match snap {
2224                Some(e) => e.muted(|| e.resolve_segs(p))?,
2225                None => self.resolve_segs(p)?,
2226            };
2227            if target.is_undef() {
2228                return err_code(format!("dangling reference {}", path_str(p, None)), "E6002");
2229            }
2230            return Ok(target);
2231        }
2232        Ok(v)
2233    }
2234
2235    // the value at a place; Undef when there is none (an absent optional
2236    // member counts as none — §7.5). Lenient about segment kinds: engine-built
2237    // paths are canonical by construction
2238    /// The value at a canonical path from a root (§7.2), forcing what the path crosses.
2239    pub fn resolve_segs(&self, segs: &[Seg]) -> R<Value> {
2240        // A copied round holds the records an answer can name, by path.
2241        if let Some(index) = self.frozen_index.borrow().as_ref() {
2242            return Ok(index
2243                .get(&path_str(segs, None))
2244                .map_or(Value::Undef, |r| Value::Rec(r.clone())));
2245        }
2246        if let Some(Seg::Name(name)) = segs.first() {
2247            self.record(format!("root:{name}"));
2248        }
2249        let mut cur = match segs.first() {
2250            Some(Seg::Name(n)) => self.root(n).unwrap_or(Value::Undef),
2251            _ => Value::Undef,
2252        };
2253        for s in segs.iter().skip(1) {
2254            if cur.is_undef() {
2255                break;
2256            }
2257            cur = match (&cur, s) {
2258                (Value::Rec(r), Seg::Name(n) | Seg::Key(n)) => {
2259                    if r.borrow().slot(n).is_some() {
2260                        self.force_slot(r, n)?
2261                    } else {
2262                        Value::Undef
2263                    }
2264                }
2265                (Value::Arr(a), Seg::Idx(i)) => {
2266                    a.borrow().items.get(*i).cloned().unwrap_or(Value::Undef)
2267                }
2268                (Value::Map(m), Seg::Name(n) | Seg::Key(n)) => {
2269                    m.borrow().get(n).cloned().unwrap_or(Value::Undef)
2270                }
2271                _ => Value::Undef,
2272            };
2273            if cur.is_absent() {
2274                cur = Value::Undef;
2275            }
2276            if let Value::Ref(_) = cur {
2277                cur = self.deref(cur)?;
2278            }
2279        }
2280        Ok(cur)
2281    }
2282    // a path from a document must be canonical (§7.2, §7.5): a map key
2283    // bracketed, a record member dotted when the dot can spell it and
2284    // bracketed otherwise, an array index numeric — any other spelling does
2285    // not resolve
2286    /// The value at a canonical path as a document's reference string names it (§7.5).
2287    pub fn resolve_canonical(&self, segs: &[Seg]) -> R<Value> {
2288        let mut cur = match segs.first() {
2289            Some(Seg::Name(n)) => self.root(n).unwrap_or(Value::Undef),
2290            _ => Value::Undef,
2291        };
2292        for s in segs.iter().skip(1) {
2293            if cur.is_undef() {
2294                break;
2295            }
2296            cur = match (&cur, s) {
2297                (Value::Rec(r), Seg::Name(n)) if dot_spellable(n) => {
2298                    if r.borrow().slot(n).is_some() {
2299                        self.force_slot(r, n)?
2300                    } else {
2301                        Value::Undef
2302                    }
2303                }
2304                (Value::Rec(r), Seg::Key(n)) if !dot_spellable(n) => {
2305                    if r.borrow().slot(n).is_some() {
2306                        self.force_slot(r, n)?
2307                    } else {
2308                        Value::Undef
2309                    }
2310                }
2311                (Value::Arr(a), Seg::Idx(i)) => {
2312                    a.borrow().items.get(*i).cloned().unwrap_or(Value::Undef)
2313                }
2314                (Value::Map(m), Seg::Key(n)) => m.borrow().get(n).cloned().unwrap_or(Value::Undef),
2315                _ => Value::Undef,
2316            };
2317            if cur.is_absent() {
2318                cur = Value::Undef;
2319            }
2320            if let Value::Ref(_) = cur {
2321                cur = self.deref(cur)?;
2322            }
2323        }
2324        Ok(cur)
2325    }
2326
2327    /// a member of a record (or an unbound literal) by name; ABSENT when absent
2328    pub fn access(&self, x: &Value, name: &str) -> R<Value> {
2329        match x {
2330            Value::Rec(r) => {
2331                let (has, is_extra) = {
2332                    let b = r.borrow();
2333                    (b.has_slot(name), b.extra(name).is_some())
2334                };
2335                if has {
2336                    return self.force_slot(r, name); // Absent when the member is absent
2337                }
2338                if is_extra {
2339                    return err(format!("opaque field {name} accessed"));
2340                }
2341                // a member the record's type does not declare: the checker admitted the
2342                // read against a bound that declares it optional, so it is absent (§4.10)
2343                Ok(Value::Absent)
2344            }
2345            Value::PreObj(es) => {
2346                for (k, v) in self.entries_of(es)? {
2347                    if k == name {
2348                        return match v {
2349                            Value::PreVal(pv) => self.ev(&pv.expr, &pv.scope),
2350                            other => Ok(other),
2351                        };
2352                    }
2353                }
2354                Ok(Value::Absent)
2355            }
2356            // a literal that no record type claimed is a map at evaluation time
2357            // while the checker typed its members by name; the name reads the entry
2358            Value::Map(m) => Ok(m.borrow().get(name).cloned().unwrap_or(Value::Absent)),
2359            Value::Null => err("member access on null"),
2360            Value::Absent => Ok(Value::Absent),
2361            _ => err(format!("member access on non-record ({name})")),
2362        }
2363    }
2364
2365    fn slot_lookup(&self, inst: &Inst, name: &str) -> R<Option<Value>> {
2366        let mut cur = Some(inst.clone());
2367        while let Some(c) = cur {
2368            if c.borrow().has_slot(name) {
2369                return Ok(Some(self.force_slot(&c, name)?)); // Absent when the member is absent
2370            }
2371            cur = c.borrow().parent.clone();
2372        }
2373        Ok(None)
2374    }
2375
2376    /// Apply a function value — a closure, a native, a standard-library function — to arguments (§4.8).
2377    pub fn call(&self, f: &Value, args: Vec<Value>, sc: &Scope) -> R<Value> {
2378        match f {
2379            Value::Clo(c) => {
2380                let mut locals = c.scope.locals.clone();
2381                for (p, a) in c.params.iter().zip(args) {
2382                    locals = locals.with(Rc::from(p.as_str()), a);
2383                }
2384                self.ev(&c.body, &c.scope.with_locals(locals))
2385            }
2386            Value::Nat(f) => f(&args),
2387            Value::Std(p) => self.std(&p.join("."), args, sc),
2388            _ => err("call of non-function"),
2389        }
2390    }
2391
2392    fn std(&self, name: &str, a: Vec<Value>, sc: &Scope) -> R<Value> {
2393        #[cfg(feature = "runtime-diagnostics")]
2394        if name == "map.values" {
2395            expr_diag::values_attempt();
2396        }
2397        let domain = |msg: String| -> Fail {
2398            Fail::Eval(EvalErr {
2399                msg: format!("std.{name}: {msg}"),
2400                code: Some("E5008".into()),
2401            })
2402        };
2403        let arr = |path: Vec<Value>| {
2404            #[cfg(feature = "runtime-diagnostics")]
2405            if name == "map.values" {
2406                expr_diag::values_return(path.len(), path.capacity());
2407            }
2408            #[cfg(feature = "runtime-diagnostics")]
2409            crate::retention_diagnostics::standard_array(name, path.len(), path.capacity());
2410            Value::Arr(Rc::new(RefCell::new(ArrV {
2411                items: path,
2412                path: self.container_path(&[]),
2413            })))
2414        };
2415        let s = |v: &Value| -> R<String> {
2416            match v {
2417                Value::Str(s) => Ok(s.to_string()),
2418                _ => err(format!("std.{name}: expected string")),
2419            }
2420        };
2421        match name {
2422            "array.count" => Ok(Value::Int(Num::from(
2423                self.mat_arr_ref(arg(&a, 0, name)?)?.borrow().items.len(),
2424            ))),
2425            "array.all" => {
2426                // iterate by index, cloning one item at a time, so a predicate
2427                // over a freshly built array does not copy the whole vector
2428                // first (F21: the hot path in an O(n^2) model comprehension)
2429                let items = self.mat_arr_ref(arg(&a, 0, name)?)?;
2430                let n = items.borrow().items.len();
2431                for i in 0..n {
2432                    let x = items.borrow().items[i].clone();
2433                    if !self.truthy(&self.call(arg(&a, 1, name)?, vec![x], sc)?)? {
2434                        return Ok(Value::Bool(false));
2435                    }
2436                }
2437                Ok(Value::Bool(true))
2438            }
2439            "array.any" => {
2440                let items = self.mat_arr_ref(arg(&a, 0, name)?)?;
2441                let n = items.borrow().items.len();
2442                for i in 0..n {
2443                    let x = items.borrow().items[i].clone();
2444                    if self.truthy(&self.call(arg(&a, 1, name)?, vec![x], sc)?)? {
2445                        return Ok(Value::Bool(true));
2446                    }
2447                }
2448                Ok(Value::Bool(false))
2449            }
2450            "array.filter" => {
2451                let items = self.mat_arr_ref(arg(&a, 0, name)?)?;
2452                let n = items.borrow().items.len();
2453                let mut out = vec![];
2454                for i in 0..n {
2455                    let x = items.borrow().items[i].clone();
2456                    if self.truthy(&self.call(arg(&a, 1, name)?, vec![x.clone()], sc)?)? {
2457                        out.push(x);
2458                    }
2459                }
2460                Ok(arr(out))
2461            }
2462            "array.all_distinct" => {
2463                let items = self.mat_arr(arg(&a, 0, name)?)?;
2464                for i in 0..items.len() {
2465                    for j in i + 1..items.len() {
2466                        if self.equal_values(&items[i], &items[j]) {
2467                            return Ok(Value::Bool(false));
2468                        }
2469                    }
2470                }
2471                Ok(Value::Bool(true))
2472            }
2473            "array.sum" => {
2474                let items = self.mat_arr(arg(&a, 0, name)?)?;
2475                let Some(first) = items.first() else {
2476                    return Ok(Value::Int(Num::zero()));
2477                };
2478                let mut acc = if matches!(first, Value::Float(_)) {
2479                    Value::Float(0.0)
2480                } else {
2481                    Value::Int(Num::zero())
2482                };
2483                for x in &items {
2484                    acc = add_num(&acc, x)?;
2485                }
2486                Ok(acc)
2487            }
2488            "array.fold" => {
2489                let items = self.mat_arr_ref(arg(&a, 0, name)?)?;
2490                let n = items.borrow().items.len();
2491                let mut acc = arg(&a, 1, name)?.clone();
2492                for i in 0..n {
2493                    let x = items.borrow().items[i].clone();
2494                    acc = self.call(arg(&a, 2, name)?, vec![acc, x], sc)?;
2495                }
2496                Ok(acc)
2497            }
2498            "array.sort" => {
2499                let mut items = vec![];
2500                for x in self.mat_arr(arg(&a, 0, name)?)? {
2501                    items.push(self.mat_val(x)?);
2502                }
2503                if items.iter().any(|x| !is_orderable(x)) {
2504                    return Err(domain("elements must be int, float, or string".into()));
2505                }
2506                let mut keyed: Vec<(Value, Value)> =
2507                    items.into_iter().map(|x| (x.clone(), x)).collect();
2508                sort_keyed(&mut keyed)?;
2509                Ok(arr(keyed.into_iter().map(|(_, x)| x).collect()))
2510            }
2511            "array.sort_by" => {
2512                let mut keyed = vec![];
2513                for x in self.mat_arr(arg(&a, 0, name)?)? {
2514                    let k = self.mat_val(self.call(arg(&a, 1, name)?, vec![x.clone()], sc)?)?;
2515                    if !is_orderable(&k) {
2516                        return Err(domain("keys must be int, float, or string".into()));
2517                    }
2518                    keyed.push((k, x));
2519                }
2520                sort_keyed(&mut keyed)?;
2521                Ok(arr(keyed.into_iter().map(|(_, x)| x).collect()))
2522            }
2523            "array.unique" => {
2524                let mut out: Vec<Value> = vec![];
2525                for x in self.mat_arr(arg(&a, 0, name)?)? {
2526                    if !out.iter().any(|y| self.equal_values(y, &x)) {
2527                        out.push(x);
2528                    }
2529                }
2530                Ok(arr(out))
2531            }
2532            "array.reverse" => {
2533                let mut items = self.mat_arr(arg(&a, 0, name)?)?;
2534                items.reverse();
2535                Ok(arr(items))
2536            }
2537            "map.keys" => Ok(arr(self
2538                .mat_map(arg(&a, 0, name)?)?
2539                .borrow()
2540                .entries
2541                .iter()
2542                .map(|(k, _)| Value::Str(k.clone().into()))
2543                .collect())),
2544            "map.values" => Ok(arr(self
2545                .mat_map(arg(&a, 0, name)?)?
2546                .borrow()
2547                .entries
2548                .iter()
2549                .map(|(_, v)| v.clone())
2550                .collect())),
2551            "map.entries" => Ok(arr(self
2552                .mat_map(arg(&a, 0, name)?)?
2553                .borrow()
2554                .entries
2555                .iter()
2556                .map(|(k, v)| {
2557                    Value::PreObj(Rc::new(vec![
2558                        ("key".into(), Value::Str(k.clone().into())),
2559                        ("value".into(), v.clone()),
2560                    ]))
2561                })
2562                .collect())),
2563            "string.length" => Ok(Value::Int(Num::from(s(arg(&a, 0, name)?)?.chars().count()))),
2564            "string.of" => Ok(Value::Str(self.to_str(arg(&a, 0, name)?)?.into())),
2565            "string.join" => {
2566                let sep = s(arg(&a, 1, name)?)?;
2567                let parts: Vec<String> = self
2568                    .mat_arr(arg(&a, 0, name)?)?
2569                    .iter()
2570                    .map(s)
2571                    .collect::<R<_>>()?;
2572                Ok(Value::Str(parts.join(&sep).into()))
2573            }
2574            "string.starts_with" => Ok(Value::Bool(
2575                s(arg(&a, 0, name)?)?.starts_with(&s(arg(&a, 1, name)?)?),
2576            )),
2577            "string.ends_with" => Ok(Value::Bool(
2578                s(arg(&a, 0, name)?)?.ends_with(&s(arg(&a, 1, name)?)?),
2579            )),
2580            "string.contains" => Ok(Value::Bool(
2581                s(arg(&a, 0, name)?)?.contains(&s(arg(&a, 1, name)?)?),
2582            )),
2583            "string.split" => {
2584                let sep = s(arg(&a, 1, name)?)?;
2585                if sep.is_empty() {
2586                    return Err(domain("separator must be non-empty".into()));
2587                }
2588                Ok(arr(s(arg(&a, 0, name)?)?
2589                    .split(&sep)
2590                    .map(|p| Value::Str(p.to_string().into()))
2591                    .collect()))
2592            }
2593            "ref.path" => match arg(&a, 0, name)? {
2594                Value::Ref(p) => Ok(Value::Str(path_str(p, None).into())),
2595                _ => err("ref.path on non-reference"),
2596            },
2597            "math.abs" => match arg(&a, 0, name)? {
2598                Value::Int(i) => Ok(Value::Int(i.abs())),
2599                Value::Float(f) => Ok(Value::Float(f.abs())),
2600                _ => err("std.math.abs: bad operand"),
2601            },
2602            "math.min" | "math.max" => {
2603                let (x, y) = (arg(&a, 0, name)?, arg(&a, 1, name)?);
2604                let Some(o) = num_cmp(x, y) else {
2605                    return err(format!("std.{name}: bad operands"));
2606                };
2607                let pick_x = if name == "math.min" {
2608                    o == Less
2609                } else {
2610                    o == Greater
2611                };
2612                Ok(if pick_x { x.clone() } else { y.clone() })
2613            }
2614            "math.clog2" => {
2615                let n = arg(&a, 0, name)?;
2616                let Value::Int(i) = n else {
2617                    return Err(domain(format!("n >= 1 required, got {}", num_s(n))));
2618                };
2619                if i < &Num::from(1) {
2620                    return Err(domain(format!("n >= 1 required, got {i}")));
2621                }
2622                Ok(Value::Int(Num::from((i - 1).bits())))
2623            }
2624            "math.floor" | "math.ceil" => match arg(&a, 0, name)? {
2625                Value::Float(f) => {
2626                    let r = if name == "math.floor" {
2627                        f.floor()
2628                    } else {
2629                        f.ceil()
2630                    };
2631                    Num::from_f64(r)
2632                        .map(Value::Int)
2633                        .ok_or(())
2634                        .or_else(|_| err(format!("std.{name}: non-finite")))
2635                }
2636                Value::Int(i) => Ok(Value::Int(i.clone())),
2637                _ => err(format!("std.{name}: bad operand")),
2638            },
2639            "math.round" => match arg(&a, 0, name)? {
2640                Value::Float(x) => {
2641                    let f = x.floor();
2642                    let frac = x - f;
2643                    let r = if frac > 0.5 {
2644                        f + 1.0
2645                    } else if frac < 0.5 || f % 2.0 == 0.0 {
2646                        f
2647                    } else {
2648                        f + 1.0
2649                    };
2650                    Num::from_f64(r)
2651                        .map(Value::Int)
2652                        .ok_or(())
2653                        .or_else(|_| err("std.math.round: non-finite"))
2654                }
2655                Value::Int(i) => Ok(Value::Int(i.clone())),
2656                _ => err("std.math.round: bad operand"),
2657            },
2658            "int.of" => match arg(&a, 0, name)? {
2659                Value::Float(x) if x.fract() == 0.0 && x.is_finite() => {
2660                    Ok(Value::Int(Num::from_f64(*x).unwrap()))
2661                }
2662                other => Err(domain(format!(
2663                    "no fractional part allowed, got {}",
2664                    num_s(other)
2665                ))),
2666            },
2667            "int.at_least" | "int.at_most" => {
2668                let n = arg(&a, 0, name)?.clone();
2669                let least = name == "int.at_least";
2670                Ok(Value::native(move |args: &[Value]| {
2671                    let Some(x) = args.first() else {
2672                        return err("missing argument");
2673                    };
2674                    match num_cmp(x, &n) {
2675                        Some(o) => Ok(Value::Bool(if least { o != Less } else { o != Greater })),
2676                        None => err("bad operands"),
2677                    }
2678                }))
2679            }
2680            "float.of" => {
2681                let v = match arg(&a, 0, name)? {
2682                    Value::Int(i) => i.to_f64().unwrap_or(f64::INFINITY),
2683                    Value::Float(f) => *f,
2684                    Value::Str(s) => s
2685                        .parse::<f64>()
2686                        .or_else(|_| err("std.float.of: bad operand"))?,
2687                    _ => return err("std.float.of: bad operand"),
2688                };
2689                if !v.is_finite() {
2690                    return Err(domain("magnitude outside binary64 range".into()));
2691                }
2692                Ok(Value::Float(v))
2693            }
2694            "object.merge" => self.deep_merge(arg(&a, 0, name)?, arg(&a, 1, name)?),
2695            _ => err(format!("std.{name} does not exist")),
2696        }
2697    }
2698
2699    fn deep_merge(&self, base0: &Value, patch0: &Value) -> R<Value> {
2700        let base = self.mat_rec(base0)?;
2701        let patch = self.mat_rec(patch0)?;
2702        let val = |r: &Inst, n: &str| -> R<Option<Value>> {
2703            {
2704                let b = r.borrow();
2705                if let Some(v) = b.extra(n) {
2706                    return Ok(Some(v.clone()));
2707                }
2708                match b.slot(n) {
2709                    None => return Ok(None),
2710                    Some(s) if s.kind == MKind::Der => return Ok(None),
2711                    _ => {}
2712                }
2713            }
2714            let v = self.force_slot(r, n)?;
2715            if r.borrow().slot(n).map(|s| s.state) == Some(SlotState::Absent) {
2716                return Ok(None);
2717            }
2718            Ok(Some(v))
2719        };
2720        let mut names: Vec<String> = vec![];
2721        let mut push = |n: &str| {
2722            if !names.iter().any(|x| x == n) {
2723                names.push(n.to_string());
2724            }
2725        };
2726        for r in [&base, &patch] {
2727            let b = r.borrow();
2728            for n in b.entry_order.iter() {
2729                push(n);
2730            }
2731            for m in rec_members(&b.rt).iter() {
2732                if m.kind == MKind::Dflt {
2733                    push(&m.name);
2734                }
2735            }
2736        }
2737        let mut entries = vec![];
2738        for n in &names {
2739            let is_der = |r: &Inst| {
2740                r.borrow()
2741                    .slot(n)
2742                    .map(|s| s.kind == MKind::Der)
2743                    .unwrap_or(false)
2744            };
2745            if is_der(&base) || is_der(&patch) {
2746                continue;
2747            }
2748            let bv = val(&base, n)?;
2749            let pv = val(&patch, n)?;
2750            match (bv, pv) {
2751                (Some(bv), Some(pv)) => {
2752                    let bd = self.deref(bv.clone())?;
2753                    let pd = self.deref(pv.clone())?;
2754                    if matches!(bd, Value::Rec(_)) && matches!(pd, Value::Rec(_)) {
2755                        entries.push((n.clone(), self.deep_merge(&bv, &pv)?));
2756                    } else {
2757                        entries.push((n.clone(), pv));
2758                    }
2759                }
2760                (_, Some(pv)) => entries.push((n.clone(), pv)),
2761                (Some(bv), None) => entries.push((n.clone(), bv)),
2762                (None, None) => {}
2763            }
2764        }
2765        Ok(Value::PreObj(Rc::new(entries)))
2766    }
2767
2768    /// A value with its literal (or document) form materialized.
2769    pub fn mat_val(&self, v: Value) -> R<Value> {
2770        let d = self.deref(v)?;
2771        if matches!(d, Value::PreObj(_) | Value::PreArr(_)) {
2772            return self.mat_pre(d);
2773        }
2774        if matches!(d, Value::JObj(_)) {
2775            return self.materialize(d, &[]);
2776        }
2777        Ok(d)
2778    }
2779    /// An unmaterialized literal materialized once (see `mat_cache`).
2780    fn mat_pre(&self, d: Value) -> R<Value> {
2781        let key = match &d {
2782            Value::PreArr(rc) => Rc::as_ptr(rc) as usize,
2783            Value::PreObj(rc) => Rc::as_ptr(rc) as usize,
2784            _ => return self.materialize(d, &[]),
2785        };
2786        #[cfg(feature = "runtime-diagnostics")]
2787        let diagnostic_cache =
2788            crate::retention_diagnostics::CacheAttempt::start(if matches!(d, Value::PreArr(_)) {
2789                0
2790            } else {
2791                1
2792            });
2793        if let Some((identity, m)) = self.mat_cache.borrow().get(&key) {
2794            debug_assert!(identity.matches(&d), "cached literal allocation identity");
2795            #[cfg(feature = "runtime-diagnostics")]
2796            diagnostic_cache.hit();
2797            return Ok(m.clone());
2798        }
2799        #[cfg(feature = "runtime-diagnostics")]
2800        diagnostic_cache.miss();
2801        let identity = MaterializedLiteral::of(&d);
2802        let m = self.materialize(d.clone(), &[])?;
2803        #[cfg(feature = "runtime-diagnostics")]
2804        let diagnostic_before = self.mat_cache.borrow().len();
2805        self.mat_cache
2806            .borrow_mut()
2807            .insert(key, (identity, m.clone()));
2808        #[cfg(feature = "runtime-diagnostics")]
2809        {
2810            let cache = self.mat_cache.borrow();
2811            diagnostic_cache.inserted(diagnostic_before, cache.len(), cache.capacity());
2812        }
2813        let sweep = self.mat_cache.borrow().len() >= self.materialized_sweep_at.get();
2814        if sweep {
2815            self.prune_materialized();
2816        }
2817        Ok(m)
2818    }
2819    /// The entries of an unbound object literal with its spreads (§4.2)
2820    /// expanded in place: a spread copies the entries of an object-valued
2821    /// operand — a record's value members (hidden ones are not entries), a
2822    /// map's entries, or another literal's — and a key produced twice is
2823    /// E5004. Spread operands evaluate in the literal's own scope.
2824    pub fn entries_of(&self, es: &[(String, Value)]) -> R<Vec<(String, Value)>> {
2825        let is_spread =
2826            |v: &Value| matches!(v, Value::PreVal(pv) if matches!(&*pv.expr, Expr::Spread(_)));
2827        if !es.iter().any(|(_, v)| is_spread(v)) {
2828            return Ok(es.to_vec());
2829        }
2830        let mut out: Vec<(String, Value)> = vec![];
2831        let mut seen = KeysSeen::default();
2832        let mut put = |k: String, v: Value| -> R<()> {
2833            if !seen.admits(&out, &k) {
2834                return err_code(format!("duplicate key {k}"), "E5004");
2835            }
2836            out.push((k, v));
2837            Ok(())
2838        };
2839        for (k, v) in es {
2840            if !is_spread(v) {
2841                put(k.clone(), v.clone())?;
2842                continue;
2843            }
2844            let Value::PreVal(pv) = v else { unreachable!() };
2845            let Expr::Spread(inner) = &*pv.expr else {
2846                unreachable!()
2847            };
2848            let s = self.deref(self.ev(inner, &pv.scope)?)?;
2849            for (k2, v2) in self.spread_entries(s)? {
2850                put(k2, v2)?;
2851            }
2852        }
2853        Ok(out)
2854    }
2855    pub(crate) fn spread_entries(&self, s: Value) -> R<Vec<(String, Value)>> {
2856        match s {
2857            Value::PreObj(es) => self.entries_of(&es),
2858            Value::JObj(es) => Ok((*es).clone()),
2859            Value::Map(m) => Ok(m
2860                .borrow()
2861                .entries
2862                .iter()
2863                .map(|(k, v)| (k.clone(), v.clone()))
2864                .collect()),
2865            Value::Rec(r) => {
2866                // the value's entries in serialization order (§10.3): supplied
2867                // members in document order, then the members evaluation
2868                // materialized, in declaration order — every value member,
2869                // hidden ones never
2870                let (order, names) = {
2871                    let b = r.borrow();
2872                    (
2873                        b.entry_order.clone(),
2874                        rec_members(&b.rt)
2875                            .iter()
2876                            .map(|m| m.name.clone())
2877                            .collect::<Vec<_>>(),
2878                    )
2879                };
2880                let mut entries: Vec<(String, Value)> = vec![];
2881                let mut seen: Vec<String> = vec![];
2882                for n in order.iter().cloned().chain(names) {
2883                    if seen.contains(&n) {
2884                        continue;
2885                    }
2886                    seen.push(n.clone());
2887                    let (extra, hidden, has) = {
2888                        let b = r.borrow();
2889                        (
2890                            b.extra(&n).cloned(),
2891                            b.slots.iter().any(|(s, sl)| s.as_ref() == n && sl.hidden),
2892                            b.has_slot(&n),
2893                        )
2894                    };
2895                    if let Some(x) = extra {
2896                        entries.push((n, x));
2897                        continue;
2898                    }
2899                    if !has || hidden {
2900                        continue;
2901                    }
2902                    let v = self.force_slot(&r, &n)?;
2903                    if r.borrow().slot(&n).map(|s| s.state) == Some(SlotState::Absent) {
2904                        continue;
2905                    }
2906                    entries.push((n, v));
2907                }
2908                Ok(entries)
2909            }
2910            _ => err("spread of a non-object value"),
2911        }
2912    }
2913    fn mat_rec(&self, v: &Value) -> R<Inst> {
2914        let mut d = self.deref(v.clone())?;
2915        if matches!(d, Value::PreObj(_) | Value::PreArr(_)) {
2916            d = self.mat_pre(d)?; // materialize once, cached (F21)
2917        } else if matches!(d, Value::JObj(_)) {
2918            d = self.materialize(d, &[])?;
2919        }
2920        match d {
2921            Value::Rec(r) => Ok(r),
2922            _ => err_code("std.object.merge: expected records", "E5008"),
2923        }
2924    }
2925    fn mat_arr(&self, v: &Value) -> R<Vec<Value>> {
2926        Ok(self.mat_arr_ref(v)?.borrow().items.clone())
2927    }
2928    /// the materialized array without copying its items: for callers that only
2929    /// read (a length, an index) and never call back into user code while the
2930    /// borrow is held — `mat_arr` clones because iterating callbacks would else
2931    /// double-borrow this cell (F21: `count` was cloning the whole vector)
2932    fn mat_arr_ref(&self, v: &Value) -> R<Rc<RefCell<ArrV>>> {
2933        let mut d = self.deref(v.clone())?;
2934        if matches!(d, Value::PreObj(_) | Value::PreArr(_)) {
2935            d = self.mat_pre(d)?;
2936        }
2937        match d {
2938            Value::Arr(a) => Ok(a),
2939            _ => err("expected array"),
2940        }
2941    }
2942    fn mat_map(&self, v: &Value) -> R<Rc<RefCell<MapV>>> {
2943        let mut d = self.deref(v.clone())?;
2944        if matches!(d, Value::PreObj(_) | Value::PreArr(_)) {
2945            d = self.mat_pre(d)?;
2946        }
2947        match d {
2948            Value::Map(m) => Ok(m),
2949            // a record reads as the map of its value entries (§3.17)
2950            Value::Rec(r) => {
2951                let path = self.container_path(&r.borrow().path);
2952                let entries = self.spread_entries(Value::Rec(r))?;
2953                Ok(Rc::new(RefCell::new(MapV {
2954                    entries: entries.into_iter().collect(),
2955                    path,
2956                })))
2957            }
2958            _ => err("expected map"),
2959        }
2960    }
2961
2962    // ---------- referrers ----------
2963    pub(crate) fn referrers(&self, type_name: &str, member: &str, sc: &Scope) -> R<Value> {
2964        if self.phase.get() < 2 {
2965            return Err(Fail::Defer);
2966        }
2967
2968        let Some(self_inst) = &sc.inst else {
2969            return err("$referrers outside a record");
2970        };
2971        let target = self_inst.borrow().path.clone();
2972        self.record(if self.round_cache.borrow().is_some() {
2973            format!("edge:{type_name}|{member}|{}", path_str(&target, None))
2974        } else {
2975            format!("referrers:{type_name}")
2976        });
2977        let key = format!("{type_name}|{member}");
2978        let inv = {
2979            let cached = self.ref_index.borrow().get(&key).cloned();
2980            match cached {
2981                Some(i) => i,
2982                None => {
2983                    // The inverse belongs to the frozen round. Reacquiring
2984                    // its edge on a cache hit would deep-clone every referrer
2985                    // for every target, turning indexed lookup quadratic.
2986                    let edge = self.snap_edge(type_name, member)?;
2987                    // one pass over the edge inverts it: each referrer is filed
2988                    // under every distinct place its member refers to
2989                    let mut inv: FxHashMap<String, Vec<SegPath>> = FxHashMap::default();
2990                    for (rp, refs) in edge.values() {
2991                        let mut seen: FxHashSet<String> = FxHashSet::default();
2992                        for r in refs {
2993                            let tk = path_str(r, None);
2994                            if seen.insert(tk.clone()) {
2995                                inv.entry(tk).or_default().push(rp.clone());
2996                            }
2997                        }
2998                    }
2999                    let rc = Rc::new(inv);
3000                    self.ref_index.borrow_mut().insert(key, rc.clone());
3001                    rc
3002                }
3003            }
3004        };
3005        let mut out: Vec<SegPath> = inv
3006            .get(&path_str(&target, None))
3007            .cloned()
3008            .unwrap_or_default();
3009        out.sort_by(|a, b| path_key_cmp(a, b));
3010        let prev = self.prev.borrow().clone();
3011        let items: Vec<Value> = out
3012            .into_iter()
3013            .map(|p| {
3014                let rc = Rc::new(p);
3015                if self.round_cache.borrow().is_some() {
3016                    self.round_refs
3017                        .borrow_mut()
3018                        .insert(Rc::as_ptr(&rc) as usize, rc.clone());
3019                    self.inverse_refs
3020                        .borrow_mut()
3021                        .insert(Rc::as_ptr(&rc) as usize, rc.clone());
3022                }
3023                if let Some(e) = &prev {
3024                    self.snap_refs
3025                        .borrow_mut()
3026                        .insert(Rc::as_ptr(&rc) as usize, (rc.clone(), e.clone()));
3027                }
3028                Value::Ref(rc)
3029            })
3030            .collect();
3031        #[cfg(feature = "runtime-diagnostics")]
3032        crate::retention_diagnostics::array(
3033            crate::retention_diagnostics::ArraySite::Referrers,
3034            items.len(),
3035            items.capacity(),
3036        );
3037        Ok(Value::Arr(Rc::new(RefCell::new(ArrV {
3038            items,
3039            path: self.container_path(&[]),
3040        }))))
3041    }
3042    /// the edge `T|m` of the snapshot: computed from its instances on first demand
3043    fn snap_edge(&self, type_name: &str, member: &str) -> R<Edge> {
3044        if self.snap.borrow().is_none() {
3045            self.take_snapshot(HashMap::new()); // a lazy session: what is materialized
3046        }
3047        let key = format!("{type_name}|{member}");
3048        self.queried.borrow_mut().insert(key.clone());
3049        if let Some(e) = self.snap.borrow().as_ref().unwrap().edges.get(&key) {
3050            return Ok(e.clone());
3051        }
3052        if self.computing_edges.borrow().contains(&key) {
3053            return Err(Fail::Defer);
3054        }
3055        self.computing_edges.borrow_mut().insert(key.clone());
3056        let insts = self
3057            .snap
3058            .borrow()
3059            .as_ref()
3060            .unwrap()
3061            .insts
3062            .get(type_name)
3063            .cloned()
3064            .unwrap_or_default();
3065        self.edge_bases
3066            .borrow_mut()
3067            .push(self.computing.borrow().len());
3068        let edge = self.edge_of(&insts, member);
3069        self.edge_bases.borrow_mut().pop();
3070        self.computing_edges.borrow_mut().remove(&key);
3071        self.snap
3072            .borrow_mut()
3073            .as_mut()
3074            .unwrap()
3075            .edges
3076            .insert(key, edge.clone());
3077        Ok(edge)
3078    }
3079    /// the snapshot's instances: the previous round's universe, else what is materialized now
3080    pub(crate) fn take_snapshot(&self, edges: HashMap<String, Edge>) {
3081        self.ref_index.borrow_mut().clear();
3082        let prev = self.prev.borrow().clone();
3083        let insts = match &prev {
3084            Some(p) => p.frozen_registry.borrow().clone().unwrap_or_default(),
3085            None => self.env.registry_snapshot(),
3086        };
3087        *self.snap.borrow_mut() = Some(Snap {
3088            insts: group_by_type(&insts),
3089            edges,
3090        });
3091    }
3092    /// every candidate's path with the places its member refers to (an invalid member: excluded silently, §6.6)
3093    fn edge_of(&self, insts: &[Inst], member: &str) -> Edge {
3094        let mut out = Edge::new();
3095        for cand in insts {
3096            let state = cand.borrow().slot(member).map(|s| s.state);
3097            match state {
3098                None | Some(SlotState::Forcing) => continue, // in computation: needs this very edge
3099                _ => {}
3100            }
3101            let Ok(v) = self.force_slot(cand, member) else {
3102                continue;
3103            };
3104            let mut refs = vec![];
3105            refs_in(&v, &mut refs);
3106            let path = cand.borrow().path.to_vec();
3107            out.insert(path_str(&path, None), (path, refs));
3108        }
3109        out
3110    }
3111    /// the queried edges over this round's universe, answered from its snapshot
3112    fn live_edges(&self) -> HashMap<String, Edge> {
3113        let mut out: HashMap<String, Edge> = HashMap::new();
3114        loop {
3115            let todo: Vec<String> = self
3116                .queried
3117                .borrow()
3118                .iter()
3119                .filter(|k| !out.contains_key(*k))
3120                .cloned()
3121                .collect();
3122            if todo.is_empty() {
3123                return out;
3124            }
3125            let insts = group_by_type(&self.env.registry_snapshot());
3126            for key in todo {
3127                let (t, m) = key.split_once('|').unwrap();
3128                let e = self.edge_of(insts.get(t).map(|v| v.as_slice()).unwrap_or(&[]), m);
3129                out.insert(key.clone(), e);
3130            } // forcing may have materialized more, and queried more
3131        }
3132    }
3133    /// Phase 2, one round: the deferred slots and roots, then everything; stable when the queried edges did not change.
3134    pub fn settle(&self, env: &Env, edges: HashMap<String, Edge>) -> Settled {
3135        #[cfg(feature = "runtime-diagnostics")]
3136        let mut timings = crate::evaluation_diagnostics::Span::new("settle", 0);
3137        #[cfg(feature = "runtime-diagnostics")]
3138        timings.enter(EventStage::SettleTakeSnapshot);
3139        self.phase.set(2);
3140        self.take_snapshot(edges);
3141        #[cfg(feature = "runtime-diagnostics")]
3142        timings.mark("take_snapshot");
3143        #[cfg(feature = "runtime-diagnostics")]
3144        timings.enter(EventStage::SettleDeferredSnapshot);
3145        let deferred: Vec<(Inst, String)> = self.deferred_slots.borrow_mut().drain(..).collect();
3146
3147        #[cfg(feature = "runtime-diagnostics")]
3148        timings.mark("deferred_snapshot");
3149        #[cfg(feature = "runtime-diagnostics")]
3150        timings.enter(EventStage::SettleForceDeferredSlots);
3151        for (inst, name) in &deferred {
3152            self.force_slot_safe(inst, name);
3153        }
3154
3155        #[cfg(feature = "runtime-diagnostics")]
3156        timings.mark("force_deferred_slots");
3157        #[cfg(feature = "runtime-diagnostics")]
3158        timings.enter(EventStage::SettleBindDeferredRoots);
3159        self.bind_deferred_roots();
3160        #[cfg(feature = "runtime-diagnostics")]
3161        timings.mark("bind_deferred_roots");
3162        #[cfg(feature = "runtime-diagnostics")]
3163        timings.enter(EventStage::SettleForceRoots);
3164        self.force_roots(env);
3165        #[cfg(feature = "runtime-diagnostics")]
3166        timings.mark("force_roots");
3167        #[cfg(feature = "runtime-diagnostics")]
3168        timings.enter(EventStage::SettleLiveEdges);
3169        let live = self.live_edges();
3170        #[cfg(feature = "runtime-diagnostics")]
3171        timings.mark("live_edges");
3172        #[cfg(feature = "runtime-diagnostics")]
3173        timings.enter(EventStage::SettleCompareEdges);
3174        let snap = self.snap.borrow();
3175        let snap_edges = &snap.as_ref().unwrap().edges;
3176        let mut changed: Vec<String> = live
3177            .iter()
3178            .filter(|(k, e)| !snap_edges.get(*k).is_some_and(|f| edge_eq(e, f)))
3179            .map(|(k, _)| k.clone())
3180            .collect();
3181        changed.sort();
3182        drop(snap);
3183        #[cfg(feature = "runtime-diagnostics")]
3184        timings.mark("compare_edges");
3185        #[cfg(feature = "runtime-diagnostics")]
3186        timings.finish();
3187        Settled {
3188            stable: changed.is_empty(),
3189            edges: live,
3190            changed,
3191        }
3192    }
3193    /// this round's universe, kept as the next round's snapshot
3194    fn freeze(&self) {
3195        let registry = self.env.registry_snapshot();
3196        *self.frozen_set.borrow_mut() = registry.iter().map(|i| Rc::as_ptr(i) as usize).collect();
3197        *self.frozen_roots.borrow_mut() = Some(self.env.roots_vec());
3198        *self.frozen_registry.borrow_mut() = Some(registry);
3199    }
3200    /// the frozen round that owns an instance, if it is not this engine's
3201    pub(crate) fn owner_of(&self, inst: &Inst) -> Option<Rc<Engine>> {
3202        let prev = self.prev.borrow().clone()?;
3203        if prev
3204            .frozen_set
3205            .borrow()
3206            .contains(&(Rc::as_ptr(inst) as usize))
3207        {
3208            return Some(prev);
3209        }
3210        prev.owner_of(inst)
3211    }
3212    /// Run inside a frozen round: what it reports is not this evaluation's.
3213    pub fn muted<T>(&self, f: impl FnOnce() -> T) -> T {
3214        self.env.muted.set(self.env.muted.get() + 1);
3215        let r = f();
3216        self.env.muted.set(self.env.muted.get() - 1);
3217        r
3218    }
3219    /// Evaluate a universe (§7.6, §9.3): `bind` binds every root on a fresh
3220    /// engine; the rounds repeat, each answering `$referrers` from the previous
3221    /// round, until the queried edges are stable — the settled engine is the
3222    /// result. A universe still changing after `ROUNDS` rounds is E5009.
3223    pub fn evaluate(env: &Rc<Env>, bind: &dyn Fn(&Rc<Engine>), track: bool) -> Rc<Engine> {
3224        Self::evaluate_rounds(env, bind, track, false, None)
3225    }
3226    /// Evaluate with retained member, structure and reference dependencies.
3227    pub fn evaluate_query(env: &Rc<Env>, bind: &dyn Fn(&Rc<Engine>)) -> Rc<Engine> {
3228        Self::evaluate_rounds(env, bind, false, true, None)
3229    }
3230    /// Evaluate a Session, reusing its engine after an edited materialization.
3231    pub fn evaluate_session(
3232        env: &Rc<Env>,
3233        bind: &dyn Fn(&Rc<Engine>),
3234        initial: Option<Rc<Engine>>,
3235    ) -> Rc<Engine> {
3236        Self::evaluate_rounds(env, bind, true, true, initial)
3237    }
3238    fn evaluate_rounds(
3239        env: &Rc<Env>,
3240        bind: &dyn Fn(&Rc<Engine>),
3241        track: bool,
3242        incremental: bool,
3243        initial: Option<Rc<Engine>>,
3244    ) -> Rc<Engine> {
3245        #[cfg(feature = "runtime-diagnostics")]
3246        let mut timings = crate::evaluation_diagnostics::Span::new("evaluate_setup", 0);
3247        #[cfg(feature = "runtime-diagnostics")]
3248        timings.enter(EventStage::EvaluateSetup);
3249        let mut prev: Option<Rc<Engine>> = None;
3250        let mut edges: HashMap<String, Edge> = HashMap::new();
3251        // the queried edges each round have been seen before (rounds are
3252        // deterministic, so a repeat is a cycle that never settles — report at
3253        // once, not after the full round budget; §7.6)
3254        let mut seen: HashSet<String> = HashSet::new();
3255        let mut round = 0;
3256        let programs = initial
3257            .as_ref()
3258            .and_then(|e| e.programs.borrow().clone())
3259            .or_else(|| incremental.then(|| Rc::new(Programs::default())));
3260        let query_keys = initial
3261            .as_ref()
3262            .map(|eng| eng.query_pool())
3263            .unwrap_or_default();
3264        let mut retained = initial;
3265        let mut cache = incremental
3266            .then(|| RoundCache::of(env))
3267            .flatten()
3268            .map(Rc::new);
3269        let mut incremental = cache.is_some();
3270
3271        #[cfg(feature = "runtime-diagnostics")]
3272        timings.mark("setup");
3273        #[cfg(feature = "runtime-diagnostics")]
3274        timings.finish();
3275        loop {
3276            round += 1;
3277            #[cfg(feature = "runtime-diagnostics")]
3278            let mut timings = crate::evaluation_diagnostics::Span::new("round", round as usize);
3279            #[cfg(feature = "runtime-diagnostics")]
3280            timings.enter(EventStage::RoundEngineSetup);
3281            let reusing = retained.is_some();
3282            let eng = retained.take().unwrap_or_else(|| {
3283                let eng = Self::bare_with_queries(env.clone(), query_keys.clone());
3284                eng.install_hooks(env, false);
3285                eng
3286            });
3287            *eng.programs.borrow_mut() = programs.clone();
3288            *eng.round_cache.borrow_mut() = cache.clone();
3289            *eng.revisions.borrow_mut() = cache
3290                .as_ref()
3291                .filter(|c| c.revisions.revision.get() > 0)
3292                .map(|c| c.revisions.clone());
3293            eng.track.set(track || (incremental && reusing));
3294            *eng.prev.borrow_mut() = prev.clone();
3295            let mark = env.diag_len();
3296
3297            #[cfg(feature = "runtime-diagnostics")]
3298            timings.mark("engine_setup");
3299            #[cfg(feature = "runtime-diagnostics")]
3300            timings.enter(EventStage::RoundBind);
3301            bind(&eng);
3302            #[cfg(feature = "runtime-diagnostics")]
3303            timings.mark("bind");
3304            #[cfg(feature = "runtime-diagnostics")]
3305            timings.enter(EventStage::RoundForceRootsInitial);
3306            eng.force_roots(env);
3307            #[cfg(feature = "runtime-diagnostics")]
3308            timings.mark("force_roots_initial");
3309            #[cfg(feature = "runtime-diagnostics")]
3310            timings.enter(EventStage::RoundSettle);
3311            eng.track.set(eng.track.get() || incremental);
3312            let r = eng.settle(env, edges);
3313            #[cfg(feature = "runtime-diagnostics")]
3314            timings.mark("settle");
3315            #[cfg(feature = "runtime-diagnostics")]
3316            timings.enter(EventStage::RoundEditsFinish);
3317            if let Some(edits) = eng.edits.borrow().as_ref() {
3318                edits.finish(&eng);
3319            }
3320
3321            #[cfg(feature = "runtime-diagnostics")]
3322            timings.mark("edits_finish");
3323            #[cfg(feature = "runtime-diagnostics")]
3324            timings.enter(EventStage::RoundEdgeKeyAndCycle);
3325            let ekey = edges_key(&r.edges);
3326            let cycled = !r.stable && seen.contains(&ekey);
3327
3328            #[cfg(feature = "runtime-diagnostics")]
3329            timings.mark("edge_key_and_cycle");
3330            if r.stable || cycled || round == Engine::ROUNDS {
3331                #[cfg(feature = "runtime-diagnostics")]
3332                timings.enter(EventStage::RoundCompleteDropPrevious);
3333                if !r.stable {
3334                    let snap = eng.snap.borrow();
3335                    let snap_edges = &snap.as_ref().unwrap().edges;
3336                    for key in &r.changed {
3337                        let (t, m) = key.split_once('|').unwrap();
3338                        let empty = Edge::new();
3339                        env.report(Diag::error(
3340                            format!(
3341                                "$referrers({t}, \"{m}\") does not stabilize after {} rounds",
3342                                Engine::ROUNDS
3343                            ),
3344                            edge_diff(&r.edges[key], snap_edges.get(key).unwrap_or(&empty)),
3345                            Some("E5009"),
3346                        ));
3347                    }
3348                }
3349                eng.settled.set(true);
3350                *eng.prev.borrow_mut() = None;
3351                drop(prev);
3352                if let Some(cache) = &cache {
3353                    cache.release_rebased();
3354                }
3355                eng.sweep_query_ids();
3356
3357                #[cfg(feature = "runtime-diagnostics")]
3358                timings.mark("complete_drop_previous_and_identity_sweep");
3359                #[cfg(feature = "runtime-diagnostics")]
3360                timings.finish();
3361                return eng;
3362            }
3363            // the round is the next one's snapshot; the universe starts over
3364            #[cfg(feature = "runtime-diagnostics")]
3365            timings.enter(EventStage::RoundAdvance);
3366            let snapshot = cache.as_ref().and_then(|c| c.advance(&eng, &r.edges));
3367            #[cfg(feature = "runtime-diagnostics")]
3368            timings.mark("advance");
3369            if let Some(snapshot) = snapshot {
3370                #[cfg(feature = "runtime-diagnostics")]
3371                timings.enter(EventStage::RoundRetainedTransfer);
3372                seen.insert(ekey);
3373                prev = Some(snapshot);
3374                edges = r.edges;
3375                retained = Some(eng);
3376
3377                #[cfg(feature = "runtime-diagnostics")]
3378                timings.mark("retained_round_transfer");
3379                #[cfg(feature = "runtime-diagnostics")]
3380                timings.finish();
3381                continue;
3382            }
3383            #[cfg(feature = "runtime-diagnostics")]
3384            timings.enter(EventStage::RoundFallbackFreezeReset);
3385            cache = None;
3386            incremental = false;
3387            eng.freeze();
3388            env.roots_clear();
3389            env.registry_clear();
3390            env.diag_truncate(mark);
3391            for e in eng.const_envs.borrow().iter() {
3392                for c in e.consts.borrow().values() {
3393                    c.state.set(false);
3394                    *c.value.borrow_mut() = Value::Undef;
3395                }
3396            }
3397            seen.insert(ekey);
3398            prev = Some(eng);
3399            edges = r.edges;
3400            #[cfg(feature = "runtime-diagnostics")]
3401            timings.mark("fallback_freeze_reset");
3402            #[cfg(feature = "runtime-diagnostics")]
3403            timings.finish();
3404        }
3405    }
3406
3407    // ---------- binding / checking ----------
3408    /// Bind a raw value to a type at a path (§9.2): a record instance with its slots,
3409    /// an array, a map, or a scalar checked against the type.
3410    pub fn bind(
3411        &self,
3412        raw: Value,
3413        rt: &RT,
3414        path: &[Seg],
3415        parent: Option<&Inst>,
3416        sc: &Scope,
3417    ) -> R<Value> {
3418        if let Value::PreVal(pv) = &raw {
3419            let inst = parent.cloned().or_else(|| pv.scope.inst.clone());
3420            let sc2 = pv.scope.with_inst(inst);
3421            if let RTk::Ref(_) = rt.k {
3422                return match self.eval_place(&pv.expr, &sc2)? {
3423                    Some(p) => {
3424                        // reference integrity (§7.5): the place must hold a value
3425                        if self.resolve_segs(&p)?.is_undef() {
3426                            self.env.report(Diag::error(
3427                                format!("dangling reference {}", path_str(&p, None)),
3428                                path_str(path, None),
3429                                Some("E6002"),
3430                            ));
3431                            return Err(Fail::Taint);
3432                        }
3433                        Ok(Value::Ref(Rc::new(p)))
3434                    }
3435                    None => err("not a place in ref position"),
3436                };
3437            }
3438            let v = self.ev(&pv.expr, &sc2)?;
3439            return self.bind(v, rt, path, parent, sc);
3440        }
3441        let fail = |msg: String, code: Option<&str>| -> Fail {
3442            let tail = rt.tail.borrow();
3443            match &*tail {
3444                Some(Tail::Inline { template, .. }) => {
3445                    let text: String = template
3446                        .iter()
3447                        .filter_map(|p| {
3448                            if let TPart::Text(t) = p {
3449                                Some(t.as_str())
3450                            } else {
3451                                None
3452                            }
3453                        })
3454                        .collect();
3455                    self.env.report(Diag {
3456                        severity: "error".into(),
3457                        id: rt.name.borrow().clone(),
3458                        message: text,
3459                        path: path_str(path, None),
3460                        code: Some("E4001".into()),
3461                        loc: None,
3462                        by: None,
3463                    });
3464                }
3465                _ => self.env.report(Diag::error(
3466                    msg,
3467                    path_str(path, None),
3468                    Some(code.unwrap_or("E4001")),
3469                )),
3470            }
3471            Fail::Taint
3472        };
3473        match &rt.k {
3474            RTk::Prim(n) => match (n.as_str(), &raw) {
3475                ("int", Value::Int(_))
3476                | ("float", Value::Float(_))
3477                | ("bool", Value::Bool(_))
3478                | ("string", Value::Str(_))
3479                | ("null", Value::Null) => Ok(raw),
3480                ("float", Value::Int(i)) => match exact_float(i) {
3481                    Some(f) => Ok(Value::Float(f)),
3482                    None => Err(fail(format!("expected {n}"), None)),
3483                },
3484                _ => Err(fail(format!("expected {n}"), None)),
3485            },
3486            RTk::Lit(v) => {
3487                if value_eq(&raw, v) {
3488                    Ok(raw)
3489                } else {
3490                    Err(fail(
3491                        format!("expected {}", json_str(&lit_display(v))),
3492                        None,
3493                    ))
3494                }
3495            }
3496            RTk::Range { lo, hi, excl, base } => {
3497                let raw = match (&raw, base.as_str()) {
3498                    (Value::Int(i), "float") => match exact_float(i) {
3499                        Some(f) => Value::Float(f),
3500                        None => raw,
3501                    },
3502                    _ => raw,
3503                };
3504                let ok = if base == "int" {
3505                    matches!(raw, Value::Int(_))
3506                } else {
3507                    matches!(raw, Value::Float(_))
3508                };
3509                if !ok {
3510                    return Err(fail(format!("expected {base} in range"), None));
3511                }
3512                let hi_ok = if *excl {
3513                    num_cmp(&raw, hi) == Some(Less)
3514                } else {
3515                    matches!(num_cmp(&raw, hi), Some(Less | Equal))
3516                };
3517                if matches!(num_cmp(&raw, lo), Some(Greater | Equal)) && hi_ok {
3518                    return Ok(raw);
3519                }
3520                Err(fail(
3521                    format!(
3522                        "out of range {}..{}{}",
3523                        num_s(lo),
3524                        if *excl { "<" } else { "" },
3525                        num_s(hi)
3526                    ),
3527                    None,
3528                ))
3529            }
3530            RTk::Pattern { src, re } => match &raw {
3531                Value::Str(s) if re.is_match(s) => Ok(raw),
3532                _ => Err(fail(format!("does not match /{src}/"), None)),
3533            },
3534            RTk::Quantity(dim) => {
3535                if let Value::Q(q) = &raw {
3536                    if q.dim.as_str() == dim.as_str() {
3537                        return Ok(raw);
3538                    }
3539                }
3540                if let Value::JObj(es) = &raw {
3541                    if es.len() == 2 {
3542                        let v = es.iter().find(|(k, _)| k == "value").map(|(_, v)| v);
3543                        let u = es.iter().find(|(k, _)| k == "unit").map(|(_, v)| v);
3544                        if let (Some(v), Some(Value::Str(u))) = (v, u) {
3545                            let Ok((key, to_base)) = self.env.unit_info(u) else {
3546                                return Err(fail(format!("unknown unit {u}"), Some("E4073")));
3547                            };
3548                            if key != *dim {
3549                                return Err(fail("unit of wrong dimension".into(), Some("E4073")));
3550                            }
3551                            let f = match v {
3552                                Value::Int(i) => i.to_f64().unwrap_or(f64::INFINITY),
3553                                Value::Float(f) => *f,
3554                                _ => return Err(fail("expected quantity".into(), None)),
3555                            };
3556                            return Ok(Value::quantity(dim.clone(), f * to_base));
3557                        }
3558                    }
3559                }
3560                Err(fail("expected quantity".into(), None))
3561            }
3562            RTk::Ref(_) => match &raw {
3563                Value::Ref(_) => Ok(raw),
3564                Value::Str(s) => {
3565                    let segs = parse_path(s, &sc.root_name)?;
3566                    if self.resolve_canonical(&segs)?.is_undef() {
3567                        return Err(fail(format!("dangling reference {s}"), Some("E6002")));
3568                    }
3569                    Ok(Value::Ref(Rc::new(segs)))
3570                }
3571                Value::Rec(_) | Value::Arr(_) | Value::Map(_) => {
3572                    Ok(Value::Ref(Rc::new(raw.place().unwrap())))
3573                }
3574                _ => Err(fail("expected reference path".into(), None)),
3575            },
3576            RTk::Arr { elem, lo, hi } => {
3577                let items = match &raw {
3578                    Value::PreArr(pa) => {
3579                        let mut items = vec![];
3580                        for (spread, v) in pa.iter() {
3581                            if *spread {
3582                                let s = match v {
3583                                    Value::PreVal(pv) => {
3584                                        self.deref(self.ev(&pv.expr, &pv.scope)?)?
3585                                    }
3586                                    other => self.deref(other.clone())?,
3587                                };
3588                                items.extend(self.mat_arr(&s)?);
3589                            } else {
3590                                items.push(v.clone());
3591                            }
3592                        }
3593                        BindingInput::Owned(items.into_iter())
3594                    }
3595                    Value::JArr(a) => BindingInput::Borrowed(a.iter()),
3596                    Value::Arr(a) => BindingInput::Owned(a.borrow().items.clone().into_iter()),
3597                    _ => return Err(fail("expected array".into(), None)),
3598                };
3599                if let Some(lo) = lo {
3600                    let n = items.len() as i64;
3601                    let h = hi.unwrap_or(i64::MAX);
3602                    if n < *lo || n > h {
3603                        return Err(fail(format!("array size {n} outside {lo}..{h}"), None));
3604                    }
3605                }
3606                #[cfg(feature = "runtime-diagnostics")]
3607                let diagnostic_array = crate::retention_diagnostics::ArrayAttempt::start(
3608                    crate::retention_diagnostics::ArraySite::Bind,
3609                    Some(items.len()),
3610                );
3611                let arr = Rc::new(RefCell::new(ArrV {
3612                    items: Vec::with_capacity(items.len()),
3613                    path: self.container_path(path),
3614                }));
3615                // Bound containers own their paths. Reuse only this call's
3616                // temporary flat buffer, allocating it at the first child.
3617                let mut child_path = None;
3618                for (i, it) in items.enumerate() {
3619                    let p = child_path.get_or_insert_with(|| {
3620                        let mut p = Vec::with_capacity(path.len() + 1);
3621                        p.extend_from_slice(path);
3622                        p
3623                    });
3624                    p.push(Seg::Idx(i));
3625                    let bound = self.bind(it, elem, p, parent, sc);
3626                    p.pop();
3627                    match bound {
3628                        Ok(v) => arr.borrow_mut().items.push(v),
3629                        Err(Fail::Taint) => arr.borrow_mut().items.push(Value::Absent),
3630                        Err(e) => return Err(e),
3631                    }
3632                }
3633                #[cfg(feature = "runtime-diagnostics")]
3634                {
3635                    let a = arr.borrow();
3636                    diagnostic_array.finish(a.items.len(), a.items.capacity());
3637                }
3638                Ok(Value::Arr(arr))
3639            }
3640            RTk::Map { key, val } => {
3641                let es = match &raw {
3642                    Value::JObj(e) => BindingInput::Borrowed(e.iter()),
3643                    Value::PreObj(e) => BindingInput::Owned(self.entries_of(e)?.into_iter()),
3644                    Value::Map(m) => BindingInput::Owned(
3645                        m.borrow()
3646                            .entries
3647                            .iter()
3648                            .map(|(k, v)| (k.clone(), v.clone()))
3649                            .collect::<Vec<_>>()
3650                            .into_iter(),
3651                    ),
3652                    // a record binds to a map as its value entries (§3.18)
3653                    Value::Rec(_) => {
3654                        BindingInput::Owned(self.spread_entries(raw.clone())?.into_iter())
3655                    }
3656                    _ => return Err(fail("expected map".into(), None)),
3657                };
3658                let m = Rc::new(RefCell::new(MapV {
3659                    entries: MapEntries::building(),
3660                    path: self.container_path(path),
3661                }));
3662                let mut child_path = None;
3663                for (k, v) in es {
3664                    // Only a key that may be rejected is given a text value to
3665                    // bind; an accepted `string` or pattern key binds to itself
3666                    // with no report, and that result was always discarded.
3667                    if !key_accepts_text(key, &k) {
3668                        match self.bind(
3669                            Value::Str(SharedText::from_rc(Rc::from(k.as_str()))),
3670                            key,
3671                            path,
3672                            parent,
3673                            sc,
3674                        ) {
3675                            Ok(_) => {}
3676                            Err(Fail::Taint) => continue,
3677                            Err(e) => return Err(e),
3678                        }
3679                    }
3680                    // Rejected keys need no child path. Remove each accepted
3681                    // key before validating the next one, including on taint.
3682                    let p = child_path.get_or_insert_with(|| {
3683                        let mut p = Vec::with_capacity(path.len() + 1);
3684                        p.extend_from_slice(path);
3685                        p
3686                    });
3687                    p.push(Seg::Key(Rc::from(k.as_str())));
3688                    let bound = self.bind(v, val, p, parent, sc);
3689                    p.pop();
3690                    match bound {
3691                        Ok(bv) => m.borrow_mut().set(k, bv),
3692                        Err(Fail::Taint) => {}
3693                        Err(e) => return Err(e),
3694                    }
3695                }
3696                self.map_shapes
3697                    .borrow_mut()
3698                    .seal(&mut m.borrow_mut().entries);
3699                Ok(Value::Map(m))
3700            }
3701            RTk::Union(arms) => {
3702                // a literal's entry: its value decides the arm
3703                let raw = match raw {
3704                    Value::PreVal(pv) => self.ev(&pv.expr, &pv.scope)?,
3705                    other => other,
3706                };
3707                let arms = arms.borrow();
3708                let leaves: Vec<RT> = arms.iter().flat_map(leaf_recs).collect();
3709                if matches!(
3710                    raw,
3711                    Value::JObj(_) | Value::PreObj(_) | Value::Rec(_) | Value::Map(_)
3712                ) && !leaves.is_empty()
3713                {
3714                    // record arms discriminate hierarchically (§3.12): the union
3715                    // is flattened to its leaf records (a union arm contributes
3716                    // its own leaves — unions are associative), and the value is
3717                    // routed to a unique leaf, one discriminant member at a time
3718                    fn lit_set(m: Option<&Member>) -> Option<Vec<Value>> {
3719                        m.and_then(|x| x.ty.clone()).and_then(|t| match &t.k {
3720                            RTk::Lit(v) => Some(vec![v.clone()]),
3721                            RTk::Union(a) => {
3722                                let a = a.borrow();
3723                                if a.iter().all(|x| matches!(&x.k, RTk::Lit(_))) {
3724                                    Some(
3725                                        a.iter()
3726                                            .filter_map(|x| match &x.k {
3727                                                RTk::Lit(v) => Some(v.clone()),
3728                                                _ => None,
3729                                            })
3730                                            .collect(),
3731                                    )
3732                                } else {
3733                                    None
3734                                }
3735                            }
3736                            _ => None,
3737                        })
3738                    }
3739                    let set_of = |leaf: &RT, dn: &str| -> Option<Vec<Value>> {
3740                        lit_set(rec_members(leaf).iter().find(|x| x.name == dn))
3741                    };
3742                    // route: a discriminant the value supplies narrows the
3743                    // candidates; a leaf whose set holds the value stays, and a
3744                    // member the value omits (it has a default) is skipped
3745                    let mut cands: Vec<RT> = leaves.clone();
3746                    while cands.len() > 1 {
3747                        let names: Vec<String> = rec_members(&cands[0])
3748                            .iter()
3749                            .map(|m| m.name.clone())
3750                            .filter(|n| cands.iter().all(|l| set_of(l, n).is_some()))
3751                            .collect();
3752                        let mut narrowed = false;
3753                        for n in &names {
3754                            if let Some(mv) = self.raw_entry(&raw, n)? {
3755                                let lv = self.raw_lit(&mv)?;
3756                                let kept: Vec<RT> = cands
3757                                    .iter()
3758                                    .filter(|l| {
3759                                        set_of(l, n)
3760                                            .unwrap_or_default()
3761                                            .iter()
3762                                            .any(|v| value_eq(&lv, v))
3763                                    })
3764                                    .cloned()
3765                                    .collect();
3766                                if !kept.is_empty() && kept.len() < cands.len() {
3767                                    cands = kept;
3768                                    narrowed = true;
3769                                    break;
3770                                }
3771                            }
3772                        }
3773                        if !narrowed {
3774                            break;
3775                        }
3776                    }
3777                    if cands.len() == 1 {
3778                        return self.bind(raw, &cands[0], path, parent, sc);
3779                    }
3780                    return Err(fail("no union arm matches discriminant".into(), None));
3781                }
3782                for arm in arms.iter() {
3783                    if self.kind_matches(&raw, arm)? {
3784                        return self.bind(raw, arm, path, parent, sc);
3785                    }
3786                }
3787                Err(fail("no union arm matches".into(), None))
3788            }
3789            RTk::Rec(_) => self.bind_record(raw, rt, path, parent, sc),
3790            RTk::Pred { base, preds } => {
3791                let v = self.bind(raw, base, path, parent, sc)?;
3792                for p in preds {
3793                    let f = self.ev(p, &Scope::new(&sc.root_name, sc.menv.clone()))?;
3794                    let ok = matches!(self.call(&f, vec![v.clone()], sc), Ok(Value::Bool(true)));
3795                    if !ok {
3796                        return Err(fail(
3797                            format!("predicate {} not satisfied", json_str(&expr_name(p))),
3798                            None,
3799                        ));
3800                    }
3801                }
3802                Ok(v)
3803            }
3804            RTk::IsectN(arms) => {
3805                let mut v = raw.clone();
3806                for arm in arms {
3807                    v = self.bind(raw.clone(), arm, path, parent, sc)?;
3808                }
3809                Ok(v)
3810            }
3811            RTk::Any => Ok(raw),
3812            RTk::Func { .. } => match &raw {
3813                Value::Clo(_) | Value::Nat(_) | Value::Std(_) => Ok(raw),
3814                _ => Err(fail("expected function".into(), None)),
3815            },
3816        }
3817    }
3818
3819    fn raw_entry(&self, raw: &Value, name: &str) -> R<Option<Value>> {
3820        match raw {
3821            Value::JObj(es) => Ok(es.iter().find(|(k, _)| k == name).map(|(_, v)| v.clone())),
3822            Value::PreObj(es) => Ok(self
3823                .entries_of(es)?
3824                .into_iter()
3825                .find(|(k, _)| k == name)
3826                .map(|(_, v)| v)),
3827            Value::Map(m) => Ok(m.borrow().get(name).cloned()),
3828            Value::Rec(r) => {
3829                if r.borrow().has_slot(name) {
3830                    Ok(Some(self.force_slot(r, name)?))
3831                } else {
3832                    Ok(None)
3833                }
3834            }
3835            _ => Ok(None),
3836        }
3837    }
3838
3839    fn raw_lit(&self, v: &Value) -> R<Value> {
3840        match v {
3841            Value::PreVal(pv) => self.ev(&pv.expr, &pv.scope),
3842            other => Ok(other.clone()),
3843        }
3844    }
3845
3846    fn kind_matches(&self, raw: &Value, rt: &RT) -> R<bool> {
3847        Ok(match &rt.k {
3848            RTk::Prim(n) => matches!(
3849                (n.as_str(), raw),
3850                ("int", Value::Int(_))
3851                    | ("float", Value::Float(_))
3852                    | ("bool", Value::Bool(_))
3853                    | ("string", Value::Str(_))
3854                    | ("null", Value::Null)
3855            ),
3856            RTk::Lit(v) => value_eq(&self.raw_lit(raw)?, v),
3857            RTk::Range { base, .. } => {
3858                if base == "int" {
3859                    matches!(raw, Value::Int(_))
3860                } else {
3861                    matches!(raw, Value::Float(_))
3862                }
3863            }
3864            RTk::Pattern { .. } => matches!(raw, Value::Str(_)),
3865            RTk::Arr { .. } => matches!(raw, Value::JArr(_) | Value::PreArr(_) | Value::Arr(_)),
3866            _ => true,
3867        })
3868    }
3869
3870    /// Evaluate an expression as a place — a canonical path — where a reference is
3871    /// expected (§7.4); none when it names no place.
3872    pub fn eval_place(&self, e: &Rc<Expr>, sc: &Scope) -> R<Option<SegPath>> {
3873        let v = self.ev_nav(e, sc)?;
3874        Ok(match &v {
3875            Value::Segs(p) => Some((**p).clone()),
3876            Value::Ref(p) => Some((**p).clone()), // $this / $parent / $root, or a reference read through
3877            Value::Rec(_) | Value::Arr(_) | Value::Map(_) => v.place(),
3878            _ => None,
3879        })
3880    }
3881
3882    fn ev_nav(&self, e: &Rc<Expr>, sc: &Scope) -> R<Value> {
3883        let programs = self.programs.borrow().clone();
3884        if let Some(p) = programs {
3885            return p.nav(e)(self, sc);
3886        }
3887        match &**e {
3888            // a conditional in a ref position chooses between places (§7.4):
3889            // only the taken branch is navigated
3890            Expr::If { c, t, f } => {
3891                if self.truthy(&self.ev(c, sc)?)? {
3892                    self.ev_nav(t, sc)
3893                } else {
3894                    self.ev_nav(f, sc)
3895                }
3896            }
3897            Expr::Paren(x) => self.ev_nav(x, sc),
3898            // a step past a missing place (an absent optional member, a key or
3899            // index that is not there) is still a place: the chain keeps naming
3900            // the location, and reference integrity (§7.5) judges it when the
3901            // reference is bound. `?.` is an ordinary step here — a navigation in
3902            // a ref position denotes the place regardless of maybe-absent steps
3903            Expr::Member { x, name, .. } => {
3904                let x0 = self.ev_nav(x, sc)?;
3905                if let Value::Segs(p) = &x0 {
3906                    let mut p = (**p).clone();
3907                    p.push(Seg::Name(Rc::from(name.as_str())));
3908                    return Ok(Value::Segs(Rc::new(p)));
3909                }
3910                let x = self.deref(x0)?;
3911                let v = self.access(&x, name)?;
3912                if v.is_absent() {
3913                    if let Value::Rec(r) = &x {
3914                        let mut p = r.borrow().path.to_vec();
3915                        p.push(Seg::Name(Rc::from(name.as_str())));
3916                        return Ok(Value::Segs(Rc::new(p)));
3917                    }
3918                }
3919                Ok(v)
3920            }
3921            Expr::Index { x, i } => {
3922                let x0 = self.ev_nav(x, sc)?;
3923                let i = self.ev(i, sc)?;
3924                if let Value::Segs(p) = &x0 {
3925                    let mut p = (**p).clone();
3926                    // past a missing place a string index can only be a map key (bracket
3927                    // access to a dot-spellable member is a compile error, §4.3)
3928                    match &i {
3929                        Value::Str(k) => p.push(Seg::Key(k.to_rc())),
3930                        _ => p.push(Seg::Idx(to_index(&i)?.max(0) as usize)),
3931                    }
3932                    return Ok(Value::Segs(Rc::new(p)));
3933                }
3934                let x = self.deref(x0)?;
3935                match &x {
3936                    Value::Arr(a) => {
3937                        let n = to_index(&i)?;
3938                        let b = a.borrow();
3939                        if n >= 0 && (n as usize) < b.items.len() {
3940                            Ok(b.items[n as usize].clone())
3941                        } else {
3942                            let mut p = b.path.to_vec();
3943                            p.push(Seg::Idx(n.max(0) as usize));
3944                            Ok(Value::Segs(Rc::new(p)))
3945                        }
3946                    }
3947                    Value::Map(m) => {
3948                        let Value::Str(k) = &i else {
3949                            return err("map index needs a string");
3950                        };
3951                        let b = m.borrow();
3952                        match b.get(k) {
3953                            Some(v) => Ok(v.clone()),
3954                            None => {
3955                                let mut p = b.path.to_vec();
3956                                p.push(Seg::Key(k.to_rc()));
3957                                Ok(Value::Segs(Rc::new(p)))
3958                            }
3959                        }
3960                    }
3961                    Value::Rec(r) => {
3962                        let Value::Str(k) = &i else {
3963                            return err("index on record needs a string");
3964                        };
3965                        let v = self.access(&x, k)?;
3966                        if v.is_absent() {
3967                            let mut p = r.borrow().path.to_vec();
3968                            p.push(Seg::Name(k.to_rc()));
3969                            Ok(Value::Segs(Rc::new(p)))
3970                        } else {
3971                            Ok(v)
3972                        }
3973                    }
3974                    _ => self.ev(e, sc),
3975                }
3976            }
3977            _ => self.ev(e, sc),
3978        }
3979    }
3980
3981    fn bind_record(
3982        &self,
3983        raw: Value,
3984        rt: &RT,
3985        path: &[Seg],
3986        parent: Option<&Inst>,
3987        sc: &Scope,
3988    ) -> R<Value> {
3989        let RTk::Rec(rec) = &rt.k else {
3990            return err("bind_record on non-record type");
3991        };
3992        // Record binding revisits this ordered sequence for reuse, slots and
3993        // extras. Immutable input stays owned by `raw`; other inputs retain
3994        // their eager snapshots across diagnostic callbacks and reentry.
3995        let entries: Cow<'_, [(String, Value)]> = match &raw {
3996            Value::JObj(e) => Cow::Borrowed(e.as_slice()),
3997            Value::PreObj(e) => Cow::Owned(self.entries_of(e)?),
3998            // a literal no record type claimed became a map; its entries bind like a document's
3999            Value::Map(m) => Cow::Owned(
4000                m.borrow()
4001                    .entries
4002                    .iter()
4003                    .map(|(k, v)| (k.clone(), v.clone()))
4004                    .collect(),
4005            ),
4006            Value::Rec(r) => {
4007                let (order, extras, ders) = {
4008                    let b = r.borrow();
4009                    (
4010                        b.entry_order.clone(),
4011                        b.extras.clone(),
4012                        b.slots
4013                            .iter()
4014                            .filter(|(_, s)| s.kind == MKind::Der)
4015                            .map(|(n, _)| n.clone())
4016                            .collect::<Vec<_>>(),
4017                    )
4018                };
4019                let mut out = vec![];
4020                for n in order.iter().cloned() {
4021                    if ders.iter().any(|name| name.as_ref() == n) {
4022                        continue;
4023                    }
4024                    if let Some((_, v)) = extras.iter().find(|(k, _)| *k == n) {
4025                        out.push((n, v.clone()));
4026                    } else {
4027                        let v = self.force_slot(r, &n)?;
4028                        out.push((n, v));
4029                    }
4030                }
4031                Cow::Owned(out)
4032            }
4033            _ => {
4034                self.env.report(Diag::error(
4035                    "expected record",
4036                    path_str(path, None),
4037                    Some("E4001"),
4038                ));
4039                return Err(Fail::Taint);
4040            }
4041        };
4042        let members = rec.members.borrow().clone();
4043        let edits = self.edits.borrow().clone();
4044        let previous = edits
4045            .as_ref()
4046            .filter(|_| self.no_reg.get() == 0)
4047            .and_then(|e| e.record(rt, path, parent));
4048        if let (Some(previous), Some(edits)) = (&previous, &edits) {
4049            if edits.unchanged(previous, &entries) {
4050                edits.activate(self, &Value::Rec(previous.clone()));
4051                return Ok(Value::Rec(previous.clone()));
4052            }
4053        }
4054        // A literal's undeclared members on an open record are values like any
4055        // other (§3.11): evaluated and materialized before the instance exists,
4056        // so a failing one fails the binding and leaves nothing half-bound. A
4057        // document's are values already and pass through as they are; so does
4058        // whatever a native caller put in one, which stays as lazy as it came.
4059        let mut literal_extras: Vec<(&String, Value)> = vec![];
4060        if rec.open.get() && matches!(raw, Value::PreObj(_)) {
4061            for (k, v) in entries.iter() {
4062                let Value::PreVal(pv) = v else { continue };
4063                if members.iter().any(|m| m.name == *k) {
4064                    continue;
4065                }
4066                let value = self
4067                    .ev(&pv.expr, &pv.scope)
4068                    .and_then(|value| self.mat_val(value));
4069                match value {
4070                    Ok(value) => literal_extras.push((k, value)),
4071                    // reported where a declared member's failure is: at the member
4072                    Err(Fail::Eval(e)) => {
4073                        let mut p = path.to_vec();
4074                        p.push(Seg::Name(Rc::from(k.as_str())));
4075                        self.env.report(Diag {
4076                            severity: "error".into(),
4077                            id: None,
4078                            message: e.msg,
4079                            path: path_str(&p, None),
4080                            code: e.code,
4081                            loc: None,
4082                            by: None,
4083                        });
4084                        return Err(Fail::Taint);
4085                    }
4086                    Err(other) => return Err(other),
4087                }
4088            }
4089        }
4090        // This captures only ordered key text, never input Values. Looking up an
4091        // already compiled schema does not move compilation across registration
4092        // callbacks or change the captured member sequence.
4093        let entry_order = self
4094            .programs
4095            .borrow()
4096            .as_ref()
4097            .map(|programs| programs.entry_order(rt, &entries))
4098            .unwrap_or_else(|| Rc::new(entries.iter().map(|(key, _)| key.clone()).collect()));
4099        let old_slots = previous
4100            .as_ref()
4101            .map(|i| std::mem::take(&mut i.borrow_mut().slots))
4102            .unwrap_or_default();
4103        let inst = previous.unwrap_or_else(|| {
4104            record_instance(RecInst {
4105                ps: RefCell::new(None),
4106                type_name: rt.name.borrow().clone(),
4107                rt: rt.clone(),
4108                path: Rc::new(path.to_vec()),
4109                parent: parent.cloned(),
4110                slots: vec![],
4111                entry_order: entry_order.clone(),
4112                extras: vec![],
4113                menv: sc.menv.clone(),
4114            })
4115        });
4116        {
4117            let mut b = inst.borrow_mut();
4118            b.slots.clear();
4119            // Every schema member contributes one slot, including absent and
4120            // invalid members. Rebinding took the old vector for Edits::bound.
4121            b.slots.reserve_exact(members.len());
4122            b.extras.clear();
4123            b.entry_order = entry_order;
4124            b.menv = sc.menv.clone();
4125        }
4126        if self.no_reg.get() == 0 {
4127            if let Some(edits) = edits.as_ref().filter(|e| e.active.get()) {
4128                edits.register(self, &inst);
4129            } else {
4130                self.env.registry_push(inst.clone());
4131            }
4132        }
4133        let schema = self.programs.borrow().as_ref().map(|p| p.schema(rt));
4134        let supplied = RecordLookup::new(&entries, members.len(), schema.as_deref());
4135        for (index, m) in members.iter().enumerate() {
4136            let plan = schema.as_ref().map(|s| &s.members[index]);
4137            let name = plan
4138                .map(|p| p.name.clone())
4139                .unwrap_or_else(|| Rc::from(m.name.as_str()));
4140            let types = plan.map(|p| p.types.clone()).unwrap_or_else(|| {
4141                Rc::new(
4142                    m.conj
4143                        .clone()
4144                        .unwrap_or_else(|| m.ty.iter().cloned().collect()),
4145                )
4146            });
4147            let menv = m.menv.clone().or_else(|| sc.menv.clone());
4148            let root_name = sc.root_name.clone();
4149            let has = supplied.get(index, name.as_ref()).cloned();
4150            let mut push_deferred = false;
4151            // a hidden member (D34) is never part of the value: a document or
4152            // literal that supplies it is in error — there is nothing to restate
4153            if m.kind == MKind::Der && m.hidden && has.is_some() {
4154                let mut p = path.to_vec();
4155                p.push(Seg::Name(name.clone()));
4156                self.env.report(Diag::error(
4157                    format!("hidden member {name} supplied"),
4158                    path_str(&p, None),
4159                    Some("E4006"),
4160                ));
4161                inst.borrow_mut().slots.push((
4162                    name.clone(),
4163                    Slot {
4164                        kind: MKind::Der,
4165                        hidden: true,
4166                        state: SlotState::Invalid,
4167                        value: Value::Undef,
4168                        compute: None,
4169                    },
4170                ));
4171                continue;
4172            }
4173            let slot = match (m.kind, has) {
4174                (MKind::Der, has) => {
4175                    let expr = m
4176                        .expr
4177                        .clone()
4178                        .unwrap_or_else(|| Rc::new(Expr::Lit(Value::Null)));
4179                    // $referrers needs the whole universe: schedule for phase 2 up front
4180                    push_deferred = plan
4181                        .map(|p| p.deferred)
4182                        .unwrap_or_else(|| mentions_referrers(&expr));
4183                    let reusable = plan.filter(|_| has.is_none());
4184                    let create = |root_name, menv| Compute::Derived {
4185                        expr,
4186                        op: plan.and_then(|p| p.expression.clone()),
4187                        ty: m.ty.clone(),
4188                        supplied: has,
4189                        name: name.clone(),
4190                        root_name,
4191                        menv,
4192                    };
4193                    let compute = match reusable {
4194                        Some(plan) => plan.reusable_compute(MKind::Der, root_name, menv, create),
4195                        None => Rc::new(create(root_name, menv)),
4196                    };
4197                    Slot {
4198                        kind: MKind::Der,
4199                        hidden: m.hidden,
4200                        state: SlotState::Unforced,
4201                        value: Value::Undef,
4202                        compute: Some(compute),
4203                    }
4204                }
4205                (kind, Some(raw_v)) => Slot {
4206                    kind,
4207                    hidden: false,
4208                    state: SlotState::Unforced,
4209                    value: Value::Undef,
4210                    compute: Some(Rc::new(Compute::Check {
4211                        raw: raw_v,
4212                        types,
4213                        name: name.clone(),
4214                        root_name,
4215                        menv,
4216                    })),
4217                },
4218                (MKind::Dflt, None) => {
4219                    let expr = m
4220                        .dflt
4221                        .clone()
4222                        .unwrap_or_else(|| Rc::new(Expr::Lit(Value::Null)));
4223                    let create = |root_name, menv| Compute::Default {
4224                        expr,
4225                        op: plan.and_then(|p| p.fallback.clone()),
4226                        types,
4227                        name: name.clone(),
4228                        root_name,
4229                        menv,
4230                    };
4231                    let compute = match plan {
4232                        Some(plan) => plan.reusable_compute(MKind::Dflt, root_name, menv, create),
4233                        None => Rc::new(create(root_name, menv)),
4234                    };
4235                    Slot {
4236                        kind: MKind::Dflt,
4237                        hidden: false,
4238                        state: SlotState::Unforced,
4239                        value: Value::Undef,
4240                        compute: Some(compute),
4241                    }
4242                }
4243                (MKind::Opt, None) => Slot {
4244                    kind: MKind::Opt,
4245                    hidden: false,
4246                    state: SlotState::Absent,
4247                    value: Value::Undef,
4248                    compute: None,
4249                },
4250                (MKind::Req, None) => {
4251                    let mut p = path.to_vec();
4252                    p.push(Seg::Name(name.clone()));
4253                    self.env.report(Diag::error(
4254                        format!("required member {name} missing"),
4255                        path_str(&p, None),
4256                        Some("E4002"),
4257                    ));
4258                    Slot {
4259                        kind: MKind::Req,
4260                        hidden: false,
4261                        state: SlotState::Invalid,
4262                        value: Value::Undef,
4263                        compute: None,
4264                    }
4265                }
4266            };
4267            inst.borrow_mut().slots.push((name.clone(), slot));
4268            if push_deferred {
4269                self.deferred_slots
4270                    .borrow_mut()
4271                    .push((inst.clone(), name.to_string()));
4272            }
4273        }
4274        for (k, v) in entries.iter() {
4275            if schema
4276                .as_ref()
4277                .map(|s| s.names.contains_key(k.as_str()))
4278                .unwrap_or_else(|| members.iter().any(|m| m.name == *k))
4279            {
4280                continue;
4281            }
4282            if rec.open.get() {
4283                let value = literal_extras
4284                    .iter()
4285                    .find(|(name, _)| *name == k)
4286                    .map_or_else(|| v.clone(), |(_, value)| value.clone());
4287                inst.borrow_mut().set_extra(k, value);
4288            } else {
4289                let nm = rt
4290                    .name
4291                    .borrow()
4292                    .as_ref()
4293                    .map(|n| format!(" {n}"))
4294                    .unwrap_or_default();
4295                let mut p = path.to_vec();
4296                p.push(Seg::Name(Rc::from(k.as_str())));
4297                self.env.report(Diag::error(
4298                    format!("undeclared member {k} on closed record{nm}"),
4299                    path_str(&p, None),
4300                    Some("E4003"),
4301                ));
4302            }
4303        }
4304        if self.no_reg.get() == 0 {
4305            if let Some(edits) = &edits {
4306                edits.bound(self, &inst, &entries, old_slots);
4307            }
4308        }
4309        Ok(Value::Rec(inst))
4310    }
4311
4312    fn run_compute(&self, inst: &Inst, c: &Compute) -> R<Value> {
4313        let path = inst.borrow().path.clone();
4314        let scope_for = |root_name: &Rc<str>, menv: &Option<Rc<Env>>| Scope {
4315            inst: Some(inst.clone()),
4316            locals: Locals::new(),
4317            root_name: root_name.clone(),
4318            menv: menv.clone(),
4319        };
4320        let member_path = |name: &str| {
4321            let mut p = path.to_vec();
4322            p.push(Seg::Name(Rc::from(name)));
4323            p
4324        };
4325        match c {
4326            Compute::Check {
4327                raw,
4328                types,
4329                name,
4330                root_name,
4331                menv,
4332            } => {
4333                let isc = scope_for(root_name, menv);
4334                let mp = member_path(name);
4335                let mut v = Value::Null;
4336                for t in types.iter() {
4337                    v = self.bind(raw.clone(), t, &mp, Some(inst), &isc)?;
4338                }
4339                Ok(v)
4340            }
4341            Compute::Default {
4342                expr,
4343                op,
4344                types,
4345                name,
4346                root_name,
4347                menv,
4348            } => {
4349                let isc = scope_for(root_name, menv);
4350                let mp = member_path(name);
4351                if types.len() == 1 && matches!(types[0].k, RTk::Ref(_)) {
4352                    let pv = Value::PreVal(Rc::new(PreValV {
4353                        expr: {
4354                            #[cfg(feature = "runtime-diagnostics")]
4355                            crate::retention_diagnostics::preval(3);
4356                            expr.clone()
4357                        },
4358                        scope: isc.clone(),
4359                    }));
4360                    return self.bind(pv, &types[0], &mp, Some(inst), &isc);
4361                }
4362                let v = match op {
4363                    Some(op) => op(self, &isc)?,
4364                    None => self.ev(expr, &isc)?,
4365                };
4366                let mut out = Value::Null;
4367                for t in types.iter() {
4368                    out = self.bind(v.clone(), t, &mp, Some(inst), &isc)?;
4369                }
4370                Ok(out)
4371            }
4372            Compute::Derived {
4373                expr,
4374                op,
4375                ty: t,
4376                supplied,
4377                name,
4378                root_name,
4379                menv,
4380            } => {
4381                let isc = scope_for(root_name, menv);
4382                let mp = member_path(name);
4383                // a member declared `ref<T>` holds a navigation (§7.4): the
4384                // expression names a place, and is bound as one
4385                let mut v = match t {
4386                    Some(t) if matches!(t.k, RTk::Ref(_)) => {
4387                        let pv = Value::PreVal(Rc::new(PreValV {
4388                            expr: {
4389                                #[cfg(feature = "runtime-diagnostics")]
4390                                crate::retention_diagnostics::preval(4);
4391                                expr.clone()
4392                            },
4393                            scope: isc.clone(),
4394                        }));
4395                        self.bind(pv, t, &mp, Some(inst), &isc)?
4396                    }
4397                    _ => match op {
4398                        Some(op) => op(self, &isc)?,
4399                        None => self.ev(expr, &isc)?,
4400                    },
4401                };
4402                if let Some(t) = t {
4403                    if !matches!(t.k, RTk::Ref(_)) {
4404                        v = self.bind(v, t, &mp, Some(inst), &isc)?;
4405                    }
4406                } else if matches!(v, Value::PreObj(_) | Value::PreArr(_) | Value::JObj(_)) {
4407                    v = self.materialize(v, &mp)?;
4408                }
4409                if let Some(sv) = supplied {
4410                    let against = t.clone().unwrap_or_else(|| structural_of(&v));
4411                    self.no_reg.set(self.no_reg.get() + 1);
4412                    let restated = self.bind(sv.clone(), &against, &mp, Some(inst), &isc);
4413                    self.no_reg.set(self.no_reg.get() - 1);
4414                    let restated = restated?;
4415                    if !self.equal_values(&v, &restated) {
4416                        self.env.report(Diag::error(
4417                            format!("derived member {name} restated with a differing value"),
4418                            path_str(&mp, None),
4419                            Some("E4005"),
4420                        ));
4421                        return Err(Fail::Taint);
4422                    }
4423                }
4424                Ok(v)
4425            }
4426            Compute::Bridge(f) => f(),
4427        }
4428    }
4429
4430    /// Force a value whole, recursively, so it can be serialized or compared.
4431    pub fn materialize(&self, v: Value, path: &[Seg]) -> R<Value> {
4432        match v {
4433            Value::PreArr(items) => {
4434                // collect the flat items iteratively: a spread of an
4435                // unmaterialized array is walked with an explicit stack, not
4436                // host recursion, so a fold-with-spread chain of any depth
4437                // flattens without exhausting the stack (§4.2, §9.4)
4438                let mut raw: Vec<Value> = vec![];
4439                let mut stack: Vec<(Rc<Vec<(bool, Value)>>, usize)> = vec![(items, 0)];
4440                while !stack.is_empty() {
4441                    let last = stack.len() - 1;
4442                    let entry = {
4443                        let (fitems, idx) = &mut stack[last];
4444                        if *idx >= fitems.len() {
4445                            None
4446                        } else {
4447                            let e = fitems[*idx].clone();
4448                            *idx += 1;
4449                            Some(e)
4450                        }
4451                    };
4452                    let Some((spread, it)) = entry else {
4453                        stack.pop();
4454                        continue;
4455                    };
4456                    let x = match &it {
4457                        Value::PreVal(pv) => self.ev(&pv.expr, &pv.scope)?,
4458                        other => other.clone(),
4459                    };
4460                    if spread {
4461                        let d = self.deref(x)?;
4462                        if let Value::PreArr(inner) = d {
4463                            stack.push((inner, 0));
4464                        } else {
4465                            for y in self.mat_arr(&d)? {
4466                                raw.push(y);
4467                            }
4468                        }
4469                    } else {
4470                        raw.push(x);
4471                    }
4472                }
4473                #[cfg(feature = "runtime-diagnostics")]
4474                let diagnostic_array = crate::retention_diagnostics::ArrayAttempt::start(
4475                    crate::retention_diagnostics::ArraySite::Materialize,
4476                    Some(raw.len()),
4477                );
4478                let arr = Rc::new(RefCell::new(ArrV {
4479                    items: Vec::with_capacity(raw.len()),
4480                    path: self.container_path(path),
4481                }));
4482                for (i, y) in raw.into_iter().enumerate() {
4483                    let mut p = path.to_vec();
4484                    p.push(Seg::Idx(i));
4485                    let m = self.materialize(y, &p)?;
4486                    arr.borrow_mut().items.push(m);
4487                }
4488                #[cfg(feature = "runtime-diagnostics")]
4489                {
4490                    let a = arr.borrow();
4491                    diagnostic_array.finish(a.items.len(), a.items.capacity());
4492                }
4493                Ok(Value::Arr(arr))
4494            }
4495            Value::PreObj(entries) => {
4496                let m = Rc::new(RefCell::new(MapV {
4497                    entries: MapEntries::building(),
4498                    path: self.container_path(path),
4499                }));
4500                for (k, pv) in self.entries_of(&entries)?.iter() {
4501                    let x = match pv {
4502                        Value::PreVal(pv) => self.ev(&pv.expr, &pv.scope)?,
4503                        other => other.clone(),
4504                    };
4505                    let mut p = path.to_vec();
4506                    p.push(Seg::Key(Rc::from(k.as_str())));
4507                    let mv = self.materialize(x, &p)?;
4508                    m.borrow_mut().set(k.clone(), mv);
4509                }
4510                self.map_shapes
4511                    .borrow_mut()
4512                    .seal(&mut m.borrow_mut().entries);
4513                Ok(Value::Map(m))
4514            }
4515            other => Ok(other),
4516        }
4517    }
4518
4519    fn with_expr(&self, base: &Rc<Expr>, patch: &Rc<Expr>, sc: &Scope) -> R<Value> {
4520        let base = self.deref(self.ev(base, sc)?)?;
4521        if !matches!(base, Value::PreObj(_) | Value::Map(_) | Value::Rec(_)) {
4522            return err("with on non-record");
4523        }
4524        self.with_value(base, self.ev(patch, sc)?)
4525    }
4526
4527    pub(crate) fn with_value(&self, base: Value, p: Value) -> R<Value> {
4528        let merge = |entries: &mut Vec<(String, Value)>, patch: Value| -> R<()> {
4529            let Value::PreObj(pes) = patch else {
4530                return err("with: patch must be an object");
4531            };
4532            for (pk, pv) in self.entries_of(&pes)? {
4533                if let Some(e) = entries.iter_mut().find(|(n, _)| *n == pk) {
4534                    e.1 = pv;
4535                } else {
4536                    entries.push((pk, pv));
4537                }
4538            }
4539            Ok(())
4540        };
4541        if let Value::PreObj(bes) = &base {
4542            let mut entries = self.entries_of(bes)?;
4543            merge(&mut entries, p)?;
4544            return Ok(Value::PreObj(Rc::new(entries)));
4545        }
4546        if let Value::Map(m) = &base {
4547            // a literal no record type claimed: its entries, updated, still unbound
4548            let mut entries = m
4549                .borrow()
4550                .entries
4551                .iter()
4552                .map(|(k, v)| (k.clone(), v.clone()))
4553                .collect();
4554            merge(&mut entries, p)?;
4555            return Ok(Value::PreObj(Rc::new(entries)));
4556        }
4557        let Value::Rec(r) = &base else {
4558            return err("with on non-record");
4559        };
4560        let (order, members) = {
4561            let b = r.borrow();
4562            (b.entry_order.clone(), rec_members(&b.rt))
4563        };
4564        let mut entries: Vec<(String, Value)> = vec![];
4565        for n in order.iter().cloned() {
4566            let (extra, skip) = {
4567                let b = r.borrow();
4568                match b.extra(&n) {
4569                    Some(v) => (Some(v.clone()), false),
4570                    None => (
4571                        None,
4572                        b.slot(&n)
4573                            .map(|s| s.kind == MKind::Der || s.state == SlotState::Absent)
4574                            .unwrap_or(true),
4575                    ),
4576                }
4577            };
4578            if let Some(v) = extra {
4579                entries.push((n, v));
4580                continue;
4581            }
4582            if skip {
4583                continue;
4584            }
4585            let v = self.force_slot(r, &n)?;
4586            entries.push((n, v));
4587        }
4588        for m in members.iter() {
4589            if m.kind != MKind::Dflt || entries.iter().any(|(k, _)| *k == m.name) {
4590                continue;
4591            }
4592            let present = r
4593                .borrow()
4594                .slot(&m.name)
4595                .map(|s| s.state != SlotState::Absent)
4596                .unwrap_or(false);
4597            if present {
4598                let v = self.force_slot(r, &m.name)?;
4599                entries.push((m.name.clone(), v));
4600            }
4601        }
4602        merge(&mut entries, p)?;
4603        Ok(Value::PreObj(Rc::new(entries)))
4604    }
4605
4606    // ---------- slots ----------
4607    /// Force a slot and tell how it ended: ok, invalid, absent.
4608    pub fn force_state(&self, inst: &Inst, name: &str) -> SlotState {
4609        self.force_slot_safe(inst, name);
4610        inst.borrow()
4611            .slot(name)
4612            .map(|s| s.state)
4613            .unwrap_or(SlotState::Invalid)
4614    }
4615
4616    /// Force a slot, a failure recorded as its state rather than raised.
4617    pub fn force_slot_safe(&self, inst: &Inst, name: &str) {
4618        let _ = self.force_slot(inst, name);
4619    }
4620
4621    /// the cycle as the dependency graph records it: the slots forced between
4622    /// the re-entered one and now, each shown by its member, closing the loop
4623    fn cycle_path(&self, key: &str) -> String {
4624        let c = self.computing.borrow();
4625        let from = c.iter().position(|k| k.as_str() == key).unwrap_or(0);
4626        let mut chain: Vec<String> = c[from..].iter().map(|k| member_of_key(k)).collect();
4627        chain.push(member_of_key(key));
4628        chain.join(" -> ")
4629    }
4630    /// Force a slot — its check, default, or derived expression — once, with
4631    /// dependency tracking (§9.3).
4632    pub fn force_slot(&self, inst: &Inst, name: &str) -> R<Value> {
4633        if let Some(owner) = self.owner_of(inst) {
4634            self.record(format!("snapshot:{}", Self::slot_key(inst, name)));
4635            if self.round_cache.borrow().is_some()
4636                && self
4637                    .prev
4638                    .borrow()
4639                    .as_ref()
4640                    .is_none_or(|p| !Rc::ptr_eq(p, &owner))
4641            {
4642                self.record("round:nested".into());
4643            }
4644            let value = owner.muted(|| owner.force_slot(inst, name))?;
4645            self.inherit_snapshot_refs(&value, &owner);
4646            return Ok(value);
4647        }
4648        let state = {
4649            let b = inst.borrow();
4650            let Some(s) = b.slot(name) else {
4651                return err(format!("no member {name}"));
4652            };
4653            s.state
4654        };
4655        // the slot key is a per-force string allocation; a one-shot evaluate
4656        // never reads the dependency graph, so build it only when tracking or
4657        // when the slot is actually forced (past the cached early returns) (F21)
4658        let mut recorded = None;
4659        if self.track.get() && !self.computing.borrow().is_empty() {
4660            let key = Engine::slot_key(inst, name);
4661            if state == SlotState::Unforced {
4662                let id = self.record_query(&key);
4663                recorded = Some((key, id));
4664            } else {
4665                self.record(key);
4666            }
4667        }
4668        match state {
4669            SlotState::Ok => {
4670                let v = inst.borrow().slot(name).unwrap().value.clone();
4671                return Ok(match self.round_cache.borrow().as_ref() {
4672                    Some(c) => c.value(&v, self),
4673                    None => v,
4674                });
4675            }
4676            SlotState::Absent => {
4677                if let Some(edits) = self.edits.borrow().as_ref().filter(|e| e.active.get()) {
4678                    edits
4679                        .revisions
4680                        .accept(self, &Self::slot_key(inst, name), &Value::Absent);
4681                }
4682                return Ok(Value::Absent);
4683            }
4684            SlotState::Invalid => return Err(Fail::Taint),
4685            _ => {}
4686        }
4687        let (key, recorded_id) = recorded.unwrap_or_else(|| (Engine::slot_key(inst, name), None));
4688        // Only failures need a diagnostic path. Retain its pre-force value:
4689        // a native computation may replace or mutate the instance's path.
4690        let path = inst.borrow().path.clone();
4691        let diagnostic_path = || {
4692            path_str_iter(
4693                path.iter()
4694                    .chain(std::iter::once(&Seg::Name(Rc::from(name)))),
4695                None,
4696            )
4697        };
4698        if state == SlotState::Deferred {
4699            if self.phase.get() < 2 {
4700                return Err(Fail::Defer); // known to wait for phase 2: not attempted again
4701            }
4702            inst.borrow_mut().slot_mut(name).unwrap().state = SlotState::Unforced;
4703        }
4704        if state == SlotState::Forcing {
4705            // re-entered from inside an edge computation it was waiting on: the
4706            // candidate reading it is unanswerable in this round, not a cycle
4707            if let Some(&base) = self.edge_bases.borrow().last() {
4708                let at = self
4709                    .computing
4710                    .borrow()
4711                    .iter()
4712                    .position(|k| k.as_str() == key);
4713                if at.is_none_or(|i| i < base) {
4714                    return Err(Fail::Defer);
4715                }
4716            }
4717            self.env.report(Diag::error(
4718                format!("dependency cycle: {}", self.cycle_path(&key)),
4719                diagnostic_path(),
4720                Some("E5007"),
4721            ));
4722            inst.borrow_mut().slot_mut(name).unwrap().state = SlotState::Invalid;
4723            return Err(Fail::Taint);
4724        }
4725        // Cached, deferred and cyclic reads do not execute the descriptor.
4726        // Retain immutable binding-time metadata across the force without
4727        // cloning its names, supplied value, or captured owner handles.
4728        let (compute, member_name) = {
4729            let mut b = inst.borrow_mut();
4730            let (member_name, s) = b
4731                .slots
4732                .iter_mut()
4733                .find(|(n, _)| n.as_ref() == name)
4734                .unwrap();
4735            let compute = s.compute.clone();
4736            s.state = SlotState::Forcing;
4737            (compute, member_name.clone())
4738        };
4739        let id = recorded_id.unwrap_or_else(|| self.query_id(&key));
4740        self.register_query_slot_id(id.clone(), inst.clone(), member_name);
4741        let res = match &compute {
4742            Some(c) => self.step_id(id.clone(), || {
4743                let edits = self.edits.borrow().clone();
4744                let produce = || {
4745                    if let Some(edits) = &edits {
4746                        edits.slot_computes.set(edits.slot_computes.get() + 1);
4747                    }
4748                    self.run_compute(inst, c)
4749                };
4750                if let Some(edits) = edits.as_ref().filter(|e| e.active.get()) {
4751                    return edits.compute_id(self, &id, produce);
4752                }
4753                let revisions = self.revisions.borrow().clone();
4754                match revisions {
4755                    Some(revisions) => revisions.compute_id(self, &id, produce),
4756                    None => produce(),
4757                }
4758            }),
4759            None => Ok(Value::Null),
4760        };
4761        match res {
4762            Ok(v) => {
4763                let mut b = inst.borrow_mut();
4764                let s = b.slot_mut(name).unwrap();
4765                s.state = SlotState::Ok;
4766                s.value = v.clone();
4767                Ok(v)
4768            }
4769            Err(Fail::Defer) => {
4770                inst.borrow_mut().slot_mut(name).unwrap().state = SlotState::Deferred;
4771                self.deferred_slots
4772                    .borrow_mut()
4773                    .push((inst.clone(), name.to_string()));
4774                Err(Fail::Defer)
4775            }
4776            Err(Fail::Eval(e)) => {
4777                {
4778                    let mut b = inst.borrow_mut();
4779                    let s = b.slot_mut(name).unwrap();
4780                    if s.state == SlotState::Forcing {
4781                        s.state = SlotState::Invalid;
4782                    }
4783                }
4784                self.env.report(Diag {
4785                    severity: "error".into(),
4786                    id: None,
4787                    message: e.msg,
4788                    path: diagnostic_path(),
4789                    code: e.code,
4790                    loc: None,
4791                    by: None,
4792                });
4793                Err(Fail::Taint)
4794            }
4795            Err(Fail::Taint) => {
4796                let mut b = inst.borrow_mut();
4797                let s = b.slot_mut(name).unwrap();
4798                if s.state == SlotState::Forcing {
4799                    s.state = SlotState::Invalid;
4800                }
4801                Err(Fail::Taint)
4802            }
4803        }
4804    }
4805
4806    /// The value of a module-level constant, evaluated once in its module's environment.
4807    pub fn force_const_in(&self, env: &Rc<Env>, name: &str, root_name: &str) -> R<Value> {
4808        if !self.const_envs.borrow().iter().any(|e| Rc::ptr_eq(e, env)) {
4809            self.const_envs.borrow_mut().push(env.clone());
4810        }
4811        let key = (self.round_cache.borrow().is_some() || self.track.get()).then(|| {
4812            let index = self
4813                .const_envs
4814                .borrow()
4815                .iter()
4816                .position(|e| Rc::ptr_eq(e, env))
4817                .unwrap();
4818            format!("const:{index}|{name}")
4819        });
4820        if let Some(key) = &key {
4821            self.record(key.clone());
4822        }
4823        let c = env.consts.borrow().get(name).cloned();
4824        let Some(c) = c else {
4825            return err(format!("unknown constant {name}"));
4826        };
4827        if c.state.get() {
4828            let v = c.value.borrow().clone();
4829            if let Some(edits) = self.edits.borrow().as_ref() {
4830                edits.activate(self, &v);
4831            }
4832            return Ok(v);
4833        }
4834        let produce = || {
4835            c.state.set(true);
4836            let sc = Scope::new(root_name, Some(env.clone()));
4837            let mut v = self.ev(&c.expr, &sc)?;
4838            if matches!(v, Value::PreObj(_) | Value::PreArr(_) | Value::JObj(_)) {
4839                v = match &c.ty {
4840                    Some(t) => {
4841                        let rt = env.resolve(t, None).or_else(err)?;
4842                        self.bind(v, &rt, &[Seg::Name(Rc::from(name))], None, &sc)?
4843                    }
4844                    None => self.materialize(v, &[Seg::Name(Rc::from(name))])?,
4845                };
4846            }
4847            *c.value.borrow_mut() = v.clone();
4848            Ok(v)
4849        };
4850        let v = match key {
4851            Some(key) => self.step(&key, || {
4852                match self.edits.borrow().as_ref().filter(|e| e.active.get()) {
4853                    Some(edits) => edits.compute(self, &key, produce),
4854                    None => produce(),
4855                }
4856            }),
4857            None => produce(),
4858        }?;
4859        c.state.set(true);
4860        *c.value.borrow_mut() = v.clone();
4861        Ok(v)
4862    }
4863
4864    // ---------- driving ----------
4865    /// Force every slot under a value, recursively.
4866    pub fn force_all(&self, v: &Value) {
4867        match v {
4868            Value::Rec(r) => {
4869                if self
4870                    .round_cache
4871                    .borrow()
4872                    .as_ref()
4873                    .is_some_and(|c| c.clean(r))
4874                {
4875                    return;
4876                }
4877                let names: Vec<_> = r.borrow().slots.iter().map(|(n, _)| n.clone()).collect();
4878                for n in names {
4879                    self.force_slot_safe(r, &n);
4880                    let child = {
4881                        let b = r.borrow();
4882                        b.slot(&n)
4883                            .filter(|s| s.state == SlotState::Ok)
4884                            .map(|s| s.value.clone())
4885                    };
4886                    if let Some(c) = child {
4887                        self.force_all(&c);
4888                    }
4889                }
4890            }
4891            Value::Arr(a) => {
4892                let items = a.borrow().items.clone();
4893                for x in &items {
4894                    self.force_all(x);
4895                }
4896            }
4897            Value::Map(m) => {
4898                let vals: Vec<Value> = m.borrow().entries.iter().map(|(_, v)| v.clone()).collect();
4899                for x in &vals {
4900                    self.force_all(x);
4901                }
4902            }
4903            _ => {}
4904        }
4905    }
4906
4907    /// the evaluation phase: 1 materialization, 2 universe complete ($referrers answers)
4908    pub fn set_phase(&self, p: u8) {
4909        self.phase.set(p);
4910    }
4911
4912    /// force every root, run the $referrers phase, then the assertion pass
4913    /// force every root, the roots demanded on the way included (an input
4914    /// bound through its fallback while another root is forced becomes a
4915    /// root too, and is forced in the same pass — the reference walks the
4916    /// live root map)
4917    pub fn force_roots(&self, env: &Env) {
4918        let mut i = 0;
4919        loop {
4920            let v = {
4921                let rc = env.roots.borrow().clone();
4922                let roots = rc.borrow();
4923                if i >= roots.len() {
4924                    break;
4925                }
4926                roots[i].1.clone()
4927            };
4928            self.force_all(&v);
4929            i += 1;
4930        }
4931    }
4932    /// Run every assertion of every instance, reporting under the root's name (§6).
4933    pub fn validate_all(&self, root_name: &str) {
4934        for inst in self.env.registry_snapshot() {
4935            self.validate_inst(&inst, root_name);
4936        }
4937    }
4938    /// Run one instance's assertions, invalidating it on an error-severity failure (§6.6).
4939    pub fn validate_inst(&self, inst: &Inst, root_name: &str) {
4940        let asserts = match &inst.borrow().rt.k {
4941            RTk::Rec(r) => r.asserts.borrow().clone(),
4942            _ => vec![],
4943        };
4944        // An empty body cannot read anything or report a diagnostic. Preserve
4945        // step's graph reset semantics without creating a temporary query or
4946        // constructing an assertion scope for every assertion-free record.
4947        if asserts.is_empty() && !self.track.get() {
4948            return;
4949        }
4950        let key = format!("assert:{}", path_str(&inst.borrow().path, None));
4951        if asserts.is_empty() {
4952            if self.round_cache.borrow().is_some() {
4953                self.remove_query_reads(&key);
4954            } else {
4955                self.replace_query_reads(&key, ReadSet::default());
4956            }
4957            return;
4958        }
4959        self.step(&key, || self.run_asserts(inst, &asserts, root_name));
4960    }
4961    /// reset a computed slot so that it is computed again (dependency tracking)
4962    pub fn reset_slot(&self, key: &str) -> bool {
4963        let entry = self.query_slot_shared(key);
4964        let Some((inst, name)) = entry else {
4965            return false;
4966        };
4967        let mut b = inst.borrow_mut();
4968        let Some(s) = b.slot_mut(&name) else {
4969            return false;
4970        };
4971        if s.compute.is_none() {
4972            return false;
4973        }
4974        if s.state == SlotState::Ok || s.state == SlotState::Invalid {
4975            s.state = SlotState::Unforced;
4976            s.value = Value::Null;
4977        }
4978        true
4979    }
4980
4981    fn run_asserts(&self, inst: &Inst, asserts: &[AssertItem], root_name: &str) {
4982        let (menv0, ipath, type_name) = {
4983            let b = inst.borrow();
4984            (b.menv.clone(), path_str(&b.path, None), b.type_name.clone())
4985        };
4986        let sc0 = Scope {
4987            inst: Some(inst.clone()),
4988            locals: Locals::new(),
4989            root_name: Rc::from(root_name),
4990            menv: menv0.clone(),
4991        };
4992        for a in asserts {
4993            let sc = if a.menv.is_some() {
4994                sc0.with_menv(a.menv.clone())
4995            } else {
4996                sc0.clone()
4997            };
4998            if a.when {
4999                let Ok(cond) = self.ev(&a.cond, &sc) else {
5000                    continue;
5001                };
5002                if matches!(cond, Value::Bool(true)) {
5003                    let inner: Vec<AssertItem> = a
5004                        .body
5005                        .iter()
5006                        .filter_map(|b| match b {
5007                            MemberAst::Assert {
5008                                name, cond, tail, ..
5009                            } => Some(AssertItem {
5010                                when: false,
5011                                name: name.clone(),
5012                                cond: cond.clone(),
5013                                tail: tail.clone(),
5014                                body: vec![],
5015                                origin: a.origin.clone(),
5016                                menv: a.menv.clone(),
5017                            }),
5018                            MemberAst::When { cond, body, .. } => Some(AssertItem {
5019                                when: true,
5020                                name: String::new(),
5021                                cond: cond.clone(),
5022                                tail: None,
5023                                body: body.clone(),
5024                                origin: a.origin.clone(),
5025                                menv: a.menv.clone(),
5026                            }),
5027                            _ => None,
5028                        })
5029                        .collect();
5030                    self.run_asserts(inst, &inner, root_name);
5031                }
5032                continue;
5033            }
5034            let ok = match self.ev(&a.cond, &sc) {
5035                Ok(v) => v,
5036                Err(Fail::Eval(e)) => {
5037                    self.env.report(Diag {
5038                        severity: "error".into(),
5039                        id: None,
5040                        message: format!("{}: {}", a.name, e.msg),
5041                        path: ipath.clone(),
5042                        code: e.code,
5043                        loc: None,
5044                        by: None,
5045                    });
5046                    continue;
5047                }
5048                Err(_) => continue,
5049            };
5050            if matches!(ok, Value::Bool(true)) {
5051                continue;
5052            }
5053            let id = format!(
5054                "{}.{}",
5055                a.origin
5056                    .clone()
5057                    .or_else(|| type_name.clone())
5058                    .unwrap_or_default(),
5059                a.name
5060            );
5061            match &a.tail {
5062                None => self.env.report(Diag {
5063                    severity: "error".into(),
5064                    id: Some(id),
5065                    message: format!("assert {} failed", a.name),
5066                    path: ipath.clone(),
5067                    code: Some("E6001".into()),
5068                    loc: None,
5069                    by: None,
5070                }),
5071                Some(Tail::Inline { severity, template }) => {
5072                    let msg = self.render_lenient(template, &sc);
5073                    let code = match severity.as_str() {
5074                        "error" => "E6001",
5075                        "warn" => "W6001",
5076                        _ => "I6001",
5077                    };
5078                    self.env.report(Diag {
5079                        severity: severity.clone(),
5080                        id: Some(id),
5081                        message: msg,
5082                        path: ipath.clone(),
5083                        code: Some(code.into()),
5084                        loc: None,
5085                        by: None,
5086                    });
5087                }
5088                Some(Tail::Ref { name, args }) => {
5089                    let d = menv0
5090                        .as_ref()
5091                        .and_then(|e| e.diags.borrow().get(name).cloned())
5092                        .or_else(|| self.env.diags.borrow().get(name).cloned());
5093                    let Some(d) = d else {
5094                        self.env.report(Diag::error(
5095                            format!("unknown diagnostic {name}"),
5096                            ipath.clone(),
5097                            None,
5098                        ));
5099                        continue;
5100                    };
5101                    let argv: Vec<Value> = args
5102                        .iter()
5103                        .map(|x| self.ev(x, &sc).unwrap_or(Value::Absent))
5104                        .collect();
5105                    let mut locals = Locals::new();
5106                    for (i, p) in d.params.iter().enumerate() {
5107                        locals = locals.with(
5108                            Rc::from(p.name.as_str()),
5109                            argv.get(i).cloned().unwrap_or(Value::Absent),
5110                        );
5111                    }
5112                    let psc = Scope {
5113                        inst: None,
5114                        locals,
5115                        root_name: Rc::from(root_name),
5116                        menv: menv0.clone(),
5117                    };
5118                    let msg = self.render_lenient(&d.template, &psc);
5119                    let code = if d.severity == "error" {
5120                        "E6001"
5121                    } else {
5122                        "W6001"
5123                    };
5124                    self.env.report(Diag {
5125                        severity: d.severity.clone(),
5126                        id: Some(id),
5127                        message: msg,
5128                        path: ipath.clone(),
5129                        code: Some(code.into()),
5130                        loc: None,
5131                        by: None,
5132                    });
5133                }
5134            }
5135        }
5136    }
5137
5138    fn render_lenient(&self, template: &[TPart], sc: &Scope) -> String {
5139        let mut s = String::new();
5140        for p in template {
5141            match p {
5142                TPart::Text(t) => s.push_str(t),
5143                TPart::Expr(x) => {
5144                    if let Ok(v) = self.ev(x, sc) {
5145                        if let Ok(t) = self.to_str(&v) {
5146                            s.push_str(&t);
5147                        }
5148                    }
5149                }
5150            }
5151        }
5152        s
5153    }
5154
5155    // ---------- serialization ----------
5156    /// canonical JSON of a value (§10.4, D29): derived members included,
5157    /// hidden never; `settable_only` is the tool option D29 provides — the
5158    /// settable projection (required, optional, defaulted members) that a
5159    /// document for the same type would carry
5160    pub fn serialize(&self, v: &Value, root_name: &str, settable_only: bool) -> String {
5161        let mut out = String::new();
5162        self.go(v, root_name, settable_only, &mut out);
5163        out
5164    }
5165
5166    /// The same text handed to a writer in pieces as it grows, so a large
5167    /// document is never held whole. `Ok(false)`: the value has no text and
5168    /// nothing was written.
5169    pub(crate) fn serialize_to(
5170        &self,
5171        v: &Value,
5172        root_name: &str,
5173        settable_only: bool,
5174        to: &mut dyn std::io::Write,
5175    ) -> std::io::Result<bool> {
5176        let mut out = Pieces::new(to);
5177        let written = self.go(v, root_name, settable_only, &mut out);
5178        out.finish()?;
5179        Ok(written)
5180    }
5181
5182    // Append one typed value. An unsupported/absent value appends nothing and
5183    // returns false, allowing its container to omit the member or array item.
5184    fn go<O: Emit>(&self, x: &Value, root: &str, settable_only: bool, out: &mut O) -> bool {
5185        use std::fmt::Write;
5186
5187        match x {
5188            Value::Absent | Value::Undef => return false,
5189            Value::Null => out.text().push_str("null"),
5190            Value::Bool(b) => out.text().push_str(if *b { "true" } else { "false" }),
5191            Value::Int(i) => write!(out.text(), "{i}").expect("writing to String"),
5192            Value::Float(f) => out.text().push_str(&fmt_f(*f)),
5193            Value::Str(s) => write_json_str(out.text(), s),
5194            Value::Q(q) => {
5195                let unit = self
5196                    .env
5197                    .base_unit_of
5198                    .borrow()
5199                    .get(q.dim.as_str())
5200                    .cloned()
5201                    .unwrap_or_else(|| q.dim.as_ref().clone());
5202                out.text().push_str("{\"value\":");
5203                out.text().push_str(&fmt_f(q.value));
5204                out.text().push_str(",\"unit\":");
5205                write_json_str(out.text(), &unit);
5206                out.text().push('}');
5207            }
5208            Value::Ref(p) => write_json_str(out.text(), &path_str(p, Some(root))),
5209            Value::Arr(a) => {
5210                out.text().push('[');
5211                let mut comma = false;
5212                for item in &a.borrow().items {
5213                    let start = out.text().len();
5214                    if comma {
5215                        out.text().push(',');
5216                    }
5217                    if self.go(item, root, settable_only, out) {
5218                        comma = true;
5219                        out.entry_done();
5220                    } else {
5221                        out.text().truncate(start);
5222                    }
5223                }
5224                out.text().push(']');
5225            }
5226            Value::Map(m) => {
5227                out.text().push('{');
5228                let mut comma = false;
5229                for (key, value) in &m.borrow().entries {
5230                    let start = out.text().len();
5231                    if comma {
5232                        out.text().push(',');
5233                    }
5234                    write_json_str(out.text(), key);
5235                    out.text().push(':');
5236                    if self.go(value, root, settable_only, out) {
5237                        comma = true;
5238                        out.entry_done();
5239                    } else {
5240                        out.text().truncate(start);
5241                    }
5242                }
5243                out.text().push('}');
5244            }
5245            Value::Rec(r) => {
5246                let b = r.borrow();
5247                out.text().push('{');
5248                let mut comma = false;
5249                let members = rec_members(&b.rt);
5250                // Binding pushes one slot per member, in member order. A record
5251                // that holds to that is walked by position; any other (caught
5252                // half-bound, or wider than the position set) is walked by name.
5253                let aligned = members.len() <= 64
5254                    && b.slots.len() == members.len()
5255                    && b.slots
5256                        .iter()
5257                        .zip(members.iter())
5258                        .all(|((name, _), m)| name.as_ref() == m.name.as_str());
5259                let done = (!aligned).then(|| Supplied::new(&b.entry_order));
5260                let (mut supplied, mut cursor) = (0u64, 0usize);
5261                for n in b.entry_order.iter() {
5262                    // Supplied names mostly follow the member order: try the
5263                    // next position before searching.
5264                    let position = if aligned {
5265                        let hit = (cursor < b.slots.len()
5266                            && b.slots[cursor].0.as_ref() == n.as_str())
5267                        .then_some(cursor)
5268                        .or_else(|| b.slots.iter().position(|(k, _)| k.as_ref() == n.as_str()));
5269                        if let Some(i) = hit {
5270                            supplied |= 1 << i;
5271                            cursor = i + 1;
5272                        }
5273                        hit
5274                    } else {
5275                        None
5276                    };
5277                    if let Some(v) = b.extra(n) {
5278                        if comma {
5279                            out.text().push(',');
5280                        }
5281                        write_json_str(out.text(), n);
5282                        out.text().push(':');
5283                        self.raw_json(v, root, out);
5284                        comma = true;
5285                        out.entry_done();
5286                        continue;
5287                    }
5288                    let slot = if aligned {
5289                        position.map(|i| &b.slots[i].1)
5290                    } else {
5291                        b.slot(n)
5292                    };
5293                    let Some(s) = slot else { continue };
5294                    if matches!(s.state, SlotState::Invalid | SlotState::Absent)
5295                        || s.kind == MKind::Der
5296                    {
5297                        continue;
5298                    }
5299                    let start = out.text().len();
5300                    if comma {
5301                        out.text().push(',');
5302                    }
5303                    write_json_str(out.text(), n);
5304                    out.text().push(':');
5305                    if self.go(&s.value, root, settable_only, out) {
5306                        comma = true;
5307                        out.entry_done();
5308                    } else {
5309                        out.text().truncate(start);
5310                    }
5311                }
5312                for (i, m) in members.iter().enumerate() {
5313                    let was_supplied = match &done {
5314                        Some(done) => done.has(m.name.as_str()),
5315                        None => supplied & (1 << i) != 0,
5316                    };
5317                    if was_supplied && m.kind != MKind::Der {
5318                        continue;
5319                    }
5320                    if settable_only && m.kind == MKind::Der {
5321                        continue;
5322                    }
5323                    let slot = if aligned {
5324                        Some(&b.slots[i].1)
5325                    } else {
5326                        b.slot(&m.name)
5327                    };
5328                    let Some(s) = slot else { continue };
5329                    if s.hidden
5330                        || matches!(
5331                            s.state,
5332                            SlotState::Invalid
5333                                | SlotState::Absent
5334                                | SlotState::Unforced
5335                                | SlotState::Deferred
5336                        )
5337                    {
5338                        continue;
5339                    }
5340                    let start = out.text().len();
5341                    if comma {
5342                        out.text().push(',');
5343                    }
5344                    write_json_str(out.text(), &m.name);
5345                    out.text().push(':');
5346                    if self.go(&s.value, root, settable_only, out) {
5347                        comma = true;
5348                        out.entry_done();
5349                    } else {
5350                        out.text().truncate(start);
5351                    }
5352                }
5353                out.text().push('}');
5354            }
5355            Value::JObj(_) | Value::JArr(_) => self.raw_json(x, root, out),
5356            _ => return false,
5357        }
5358        true
5359    }
5360
5361    // Raw documents retain every position. Non-document values and failed or
5362    // unsupported PreVal results become null, unlike omitted typed children.
5363    fn raw_json<O: Emit>(&self, v: &Value, root: &str, out: &mut O) {
5364        match v {
5365            Value::JArr(items) => {
5366                out.text().push('[');
5367                for (index, item) in items.iter().enumerate() {
5368                    if index != 0 {
5369                        out.text().push(',');
5370                    }
5371                    self.raw_json(item, root, out);
5372                    out.entry_done();
5373                }
5374                out.text().push(']');
5375            }
5376            Value::JObj(entries) => {
5377                out.text().push('{');
5378                for (index, (key, value)) in entries.iter().enumerate() {
5379                    if index != 0 {
5380                        out.text().push(',');
5381                    }
5382                    write_json_str(out.text(), key);
5383                    out.text().push(':');
5384                    self.raw_json(value, root, out);
5385                    out.entry_done();
5386                }
5387                out.text().push('}');
5388            }
5389            Value::PreVal(pv) => match self.ev(&pv.expr, &pv.scope) {
5390                Ok(v) => {
5391                    if !self.go(&v, root, false, out) {
5392                        out.text().push_str("null");
5393                    }
5394                }
5395                Err(_) => out.text().push_str("null"),
5396            },
5397            other => {
5398                if !self.go(other, root, false, out) {
5399                    out.text().push_str("null");
5400                }
5401            }
5402        }
5403    }
5404}