Skip to main content

decl_lang/
session.rs

1//! The session object (docs/tooling/02_repl.md §1) — a port of the
2//! reference implementation's session.ts: a universe — the modules loaded
3//! from an entry file, their texts taken as a snapshot — plus an operation
4//! log (bindings, document edits, session declarations, reloads). The
5//! state is the universe with the log applied, recomputed deterministically
6//! from the snapshot, which is what makes `:undo` exact and a scripted
7//! session reproducible. The REPL (repl.rs) drives it; nothing here prints,
8//! and every answer is the same checker, inference, and engine the command
9//! line runs.
10use crate::ast::{Decl, DeclBody, Expr, TPart};
11use crate::checker::check_module;
12use crate::engine::{fmt_f, Engine, RootSrc};
13use crate::fmt::format;
14use crate::infer::{infer, make_ctx, std_names, type_text, Ctx, Ty};
15use crate::module::{load_modules, Module};
16use crate::package::{open_package_universe, verify_lock};
17use crate::parse::{parse_expr_text, parse_source};
18use crate::qengine::edits::Edits;
19use crate::render::{absolute, declared_form, emit_root, resolve_in, Emission, Emitted, Form};
20use crate::semantics::{
21    json_str, parse_path, path_str, read_json, rec_members, seg_text, sort_diags, Diag, Env, Fail,
22    Locals, MKind, RTk, Scope, Seg, SegPath, SlotState, Value, RT,
23};
24use crate::yaml::{is_yaml_path, read_yaml};
25use regex::Regex;
26use std::cell::{Cell, RefCell};
27use std::collections::{HashMap, HashSet};
28use std::path::{Path, PathBuf};
29use std::rc::Rc;
30use std::sync::LazyLock;
31use std::time::Instant;
32
33// a detached declaration's type text on one line (compiled once)
34static SQUEEZE_WS: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"\s*\n\s*").unwrap());
35
36// ---------------- operations ----------------
37#[derive(Clone, Debug)]
38/// what a document is bound from
39pub enum BindSource {
40    /// a JSON file, with its text as read
41    File {
42        /// the file's path
43        file: String,
44        /// its text
45        text: String,
46    },
47    /// JSON text given in the session
48    Inline {
49        /// the text
50        text: String,
51    },
52    /// an expression evaluated over the universe
53    Expr {
54        /// the expression's text
55        text: String,
56    },
57}
58
59#[derive(Clone, Copy, Debug, PartialEq)]
60/// an edit of a document
61pub enum EditKind {
62    /// a member added
63    Create,
64    /// a member's value replaced
65    Update,
66    /// a member removed
67    Remove,
68}
69impl EditKind {
70    /// The edit's name, as the REPL spells it.
71    pub fn word(self) -> &'static str {
72        match self {
73            EditKind::Create => "create",
74            EditKind::Update => "update",
75            EditKind::Remove => "remove",
76        }
77    }
78}
79
80#[derive(Clone)]
81/// an operation of the session log (docs/tooling/02_repl.md §1)
82pub enum Op {
83    /// bind a document to a root
84    Bind {
85        /// the root
86        name: String,
87        /// the document
88        src: BindSource,
89    },
90    /// unbind a root
91    Unbind {
92        /// the root
93        name: String,
94    },
95    /// edit a document
96    Edit {
97        /// the edit
98        kind: EditKind,
99        /// the canonical path edited
100        path: String,
101        /// the new value, as an expression
102        expr: Option<String>,
103    },
104    /// declare a type, a function, or a constant in the session
105    Declare {
106        /// its name
107        name: String,
108        /// the declaration's text
109        text: String,
110    },
111    /// add a session output
112    Output {
113        /// its name
114        name: String,
115        /// its type annotation
116        ty: Option<String>,
117        /// its expression
118        expr: String,
119    },
120    /// drop a session declaration
121    Drop {
122        /// its name
123        name: String,
124    },
125    /// re-read the universe from disk
126    Reload {
127        /// the texts as they were, so undo restores them
128        snapshot: HashMap<PathBuf, String>,
129    },
130    /// forget every operation
131    Reset,
132}
133
134#[derive(Clone, Copy, Debug, PartialEq)]
135/// where a root's document came from
136pub enum Origin {
137    /// a file
138    File,
139    /// inline text
140    Inline,
141    /// an expression
142    Expr,
143    /// the input's fallback
144    Fallback,
145    /// an output detached by an edit
146    Detached,
147}
148impl Origin {
149    /// The origin's name, as `:roots` shows it.
150    pub fn word(self) -> &'static str {
151        match self {
152            Origin::File => "file",
153            Origin::Inline => "inline",
154            Origin::Expr => "expr",
155            Origin::Fallback => "fallback",
156            Origin::Detached => "detached",
157        }
158    }
159}
160
161/// the document a root is built from, as the session holds it
162#[derive(Clone)]
163pub struct Document {
164    /// where it came from
165    pub origin: Origin,
166    /// the file, for a file
167    pub file: Option<String>,
168    /// the document, in the JSON reader's shape
169    pub doc: Value,
170    /// what it started from, for `:diff`
171    pub base: Value,
172    /// whether an edit changed it
173    pub edited: bool,
174}
175
176#[derive(Default)]
177struct State {
178    snapshot: HashMap<PathBuf, String>,
179    decls: Vec<(String, String)>, // session declarations, in order
180    outputs: Vec<(String, Option<String>, String)>, // session outputs `x = e`
181    documents: Vec<(String, Document)>,
182}
183impl State {
184    fn decl(&self, n: &str) -> Option<&String> {
185        self.decls.iter().find(|(k, _)| k == n).map(|(_, t)| t)
186    }
187    fn output(&self, n: &str) -> Option<(&Option<String>, &String)> {
188        self.outputs
189            .iter()
190            .find(|(k, _, _)| k == n)
191            .map(|(_, t, e)| (t, e))
192    }
193    fn document(&self, n: &str) -> Option<&Document> {
194        self.documents.iter().find(|(k, _)| k == n).map(|(_, d)| d)
195    }
196    fn document_mut(&mut self, n: &str) -> Option<&mut Document> {
197        self.documents
198            .iter_mut()
199            .find(|(k, _)| k == n)
200            .map(|(_, d)| d)
201    }
202    fn set_document(&mut self, n: &str, d: Document) {
203        if let Some(e) = self.documents.iter_mut().find(|(k, _)| k == n) {
204            e.1 = d;
205        } else {
206            self.documents.push((n.to_string(), d));
207        }
208    }
209    fn remove_decl(&mut self, n: &str) -> bool {
210        let before = self.decls.len();
211        self.decls.retain(|(k, _)| k != n);
212        before != self.decls.len()
213    }
214    fn remove_output(&mut self, n: &str) -> bool {
215        let before = self.outputs.len();
216        self.outputs.retain(|(k, _, _)| k != n);
217        before != self.outputs.len()
218    }
219}
220
221#[derive(Debug, Clone)]
222/// an operation refused, with the reason
223pub struct SessionError(pub String);
224impl SessionError {
225    fn new(msg: impl Into<String>) -> SessionError {
226        SessionError(msg.into())
227    }
228}
229/// an operation's outcome
230pub type SResult<T> = Result<T, SessionError>;
231
232#[derive(Clone, Copy, Debug)]
233/// the milliseconds of a run, by phase (`:time`)
234pub struct Timing {
235    /// loading
236    pub load: f64,
237    /// checking
238    pub check: f64,
239    /// binding
240    pub bind: f64,
241    /// evaluating
242    pub evaluate: f64,
243    /// all of it
244    pub total: f64,
245    /// the incremental step: how many slots were recomputed, and out of how many (a full run: None)
246    pub recomputed: Option<usize>,
247    /// the slots in the universe, when the incremental step counted them
248    pub slots: Option<usize>,
249}
250
251/// full recomputation on every question (the harness's cross-check)
252pub fn full_recompute() -> bool {
253    std::env::var("DECL_FULL_RECOMPUTE")
254        .map(|v| !v.is_empty())
255        .unwrap_or(false)
256}
257
258#[derive(Clone, Copy, PartialEq)]
259/// how much of a run to do
260pub enum Mode {
261    /// load and check only
262    Check,
263    /// evaluate what is asked
264    Lazy,
265    /// evaluate everything
266    Full,
267}
268
269/// the overrides of a root's declared form (docs/tooling/05_render.md §3.4)
270#[derive(Debug, Clone, Default)]
271pub struct RenderOverrides {
272    /// `--format yaml` / `--format json`
273    pub yaml: Option<bool>,
274    /// `--indent n`
275    pub indent: Option<usize>,
276    /// `--template path`
277    pub template: Option<String>,
278}
279/// a root in its declared form: one text, the files of a fan-out, or the error
280#[derive(Debug, Clone)]
281pub enum Rendered {
282    /// one text, of the kind `json`, `yaml`, or `text` (a template's)
283    Text {
284        /// `json`, `yaml`, or `text`
285        kind: String,
286        /// the text
287        text: String,
288    },
289    /// the files of a fan-out root, in element order
290    Files(Vec<(String, String)>),
291    /// the error, with the template's path when a template is at fault
292    Error {
293        /// the diagnostic
294        diag: Diag,
295        /// the file the diagnostic is reported against
296        file: Option<String>,
297    },
298}
299
300#[derive(Clone)]
301/// one run of the universe: the modules, the checks, the engine, the diagnostics
302pub struct Run {
303    /// the modules loaded
304    pub modules: Vec<Rc<Module>>,
305    /// the entry module
306    pub entry: Option<Rc<Module>>,
307    /// the loading diagnostics
308    pub load_diags: Vec<Diag>,
309    /// the static findings, by file
310    pub checks: Vec<(String, Diag)>,
311    /// session outputs whose expressions do not check (path: the output)
312    pub session_checks: Vec<Diag>,
313    /// the session outputs bound, as bound
314    pub session_roots: Vec<(String, Rc<Expr>, RT)>,
315    /// the engine, when evaluation ran
316    pub eng: Option<Rc<Engine>>,
317    /// the evaluation diagnostics
318    pub diags: Vec<Diag>,
319    /// the timing
320    pub timing: Timing,
321}
322
323/// a root as `:roots` lists it
324pub struct RootInfo {
325    /// output or input
326    pub kind: &'static str,
327    /// its name
328    pub name: String,
329    /// the module declaring it; empty for a session root
330    pub module: String,
331    /// whether it is exported
332    pub exported: bool,
333    /// whether the session declared it
334    pub session: bool,
335    /// how it is bound, for an input or a detached output
336    pub binding: String,
337    /// the bound file, when there is one
338    pub detail: String,
339    /// whether an edit changed its document
340    pub edited: bool,
341}
342
343/// an expression evaluated in the session
344pub struct ExprResult {
345    /// its value as JSON, when it has one
346    pub value: Option<String>,
347    /// the diagnostics it raised
348    pub diags: Vec<Diag>,
349    /// Some(code, message): a failure; an empty message prints only `(invalid)`
350    pub error: Option<(Option<String>, String)>,
351}
352
353fn ms(i: Instant) -> f64 {
354    i.elapsed().as_secs_f64() * 1000.0
355}
356/// Whether a diagnostic concerns a root: its path starts there.
357pub fn is_root_diag(d: &Diag, root: &str) -> bool {
358    d.path == root
359        || d.path.starts_with(&format!("{root}."))
360        || d.path.starts_with(&format!("{root}["))
361}
362
363/// parse one expression: the text is wrapped in a constant declaration
364pub fn parse_expr(text: &str) -> SResult<Rc<Expr>> {
365    parse_expr_text(text)
366        .ok_or_else(|| SessionError::new(format!("cannot parse expression: {}", text.trim())))
367}
368
369/// parse one module-level declaration; returns it with its name
370pub fn parse_decl(text: &str) -> SResult<(Decl, String)> {
371    let r = parse_source(&format!("{}\n", text.trim()));
372    if !r.errors.is_empty() || r.decls.len() != 1 {
373        return Err(SessionError::new(format!(
374            "cannot parse declaration: {}",
375            text.trim().lines().next().unwrap_or("")
376        )));
377    }
378    let d = r.decls.into_iter().next().unwrap();
379    let name = match (&d.body, d.name()) {
380        (_, Some(n)) => n.to_string(),
381        (DeclBody::Import { from, .. }, None) => format!("import {from}"),
382        (DeclBody::ReExport { from, .. }, None) => format!("re_export {from}"),
383        _ => String::new(),
384    };
385    Ok((d, name))
386}
387
388// a document's text is JSON, or YAML when its file says so (docs/tooling/05_render.md §2)
389fn parse_doc(text: &str, what: &str, file: Option<&str>) -> SResult<Value> {
390    if file.is_some_and(is_yaml_path) {
391        return read_yaml(text)
392            .map_err(|e| SessionError::new(format!("{what} is not well-formed YAML: {e}")));
393    }
394    read_json(text).map_err(|_| SessionError::new(format!("{what} is not well-formed JSON")))
395}
396
397// ---------------- JSON documents (read_json's shape) ----------------
398/// A document in the wire form: canonical JSON, one line.
399pub fn doc_json(v: &Value) -> String {
400    match v {
401        Value::Null => "null".into(),
402        Value::Bool(b) => b.to_string(),
403        Value::Int(i) => i.to_string(),
404        Value::Float(f) => fmt_f(*f),
405        Value::Str(s) => json_str(s),
406        Value::JArr(items) => format!(
407            "[{}]",
408            items.iter().map(doc_json).collect::<Vec<_>>().join(",")
409        ),
410        Value::JObj(es) => format!(
411            "{{{}}}",
412            es.iter()
413                .map(|(k, x)| format!("{}:{}", json_str(k), doc_json(x)))
414                .collect::<Vec<_>>()
415                .join(",")
416        ),
417        _ => "null".into(),
418    }
419}
420
421fn doc_step(v: &Value, seg: &Seg) -> Option<Value> {
422    match (v, seg) {
423        (Value::JObj(es), Seg::Name(k)) | (Value::JObj(es), Seg::Key(k)) => es
424            .iter()
425            .find(|(kk, _)| kk.as_str() == &**k)
426            .map(|(_, x)| x.clone()),
427        (Value::JArr(items), Seg::Idx(i)) => items.get(*i).cloned(),
428        _ => None,
429    }
430}
431
432// ---------------- pretty printing ----------------
433/// canonical JSON, re-indented (numbers and strings untouched)
434pub fn pretty_json(compact: &str) -> String {
435    let cs: Vec<char> = compact.chars().collect();
436    let mut out = String::new();
437    let mut depth = 0usize;
438    let mut i = 0;
439    let pad = |d: usize| "  ".repeat(d);
440    while i < cs.len() {
441        let c = cs[i];
442        if c == '"' {
443            let mut j = i + 1;
444            while j < cs.len() && cs[j] != '"' {
445                if cs[j] == '\\' {
446                    j += 1;
447                }
448                j += 1;
449            }
450            out.extend(&cs[i..=j.min(cs.len() - 1)]);
451            i = j + 1;
452            continue;
453        }
454        if c == '{' || c == '[' {
455            let close = if c == '{' { '}' } else { ']' };
456            if i + 1 < cs.len() && cs[i + 1] == close {
457                out.push(c);
458                out.push(close);
459                i += 2;
460                continue;
461            }
462            depth += 1;
463            out.push(c);
464            out.push('\n');
465            out.push_str(&pad(depth));
466            i += 1;
467            continue;
468        }
469        if c == '}' || c == ']' {
470            depth = depth.saturating_sub(1);
471            out.push('\n');
472            out.push_str(&pad(depth));
473            out.push(c);
474            i += 1;
475            continue;
476        }
477        if c == ',' {
478            out.push_str(",\n");
479            out.push_str(&pad(depth));
480            i += 1;
481            continue;
482        }
483        if c == ':' {
484            out.push_str(": ");
485            i += 1;
486            continue;
487        }
488        out.push(c);
489        i += 1;
490    }
491    out
492}
493
494fn identifiers(text: &str) -> HashSet<String> {
495    Regex::new(r"[A-Za-z_][A-Za-z0-9_]*")
496        .unwrap()
497        .find_iter(text)
498        .map(|m| m.as_str().to_string())
499        .collect()
500}
501
502fn relative_path(from_dir: &Path, p: &Path) -> String {
503    let a: Vec<_> = from_dir.components().collect();
504    let b: Vec<_> = p.components().collect();
505    let mut i = 0;
506    while i < a.len() && i < b.len() && a[i] == b[i] {
507        i += 1;
508    }
509    let mut parts: Vec<String> = vec!["..".to_string(); a.len() - i];
510    parts.extend(
511        b[i..]
512            .iter()
513            .map(|c| c.as_os_str().to_string_lossy().to_string()),
514    );
515    parts.join("/")
516}
517
518// ---------------- the session ----------------
519/// the session: the universe of an entry module, the documents bound, the
520/// session's declarations, and the log of operations with its cursor
521pub struct Session {
522    /// the entry module, absolute
523    pub entry_path: Option<PathBuf>,
524    /// the operations applied, in order
525    pub log: Vec<Op>,
526    /// how many of them are in force (undo moves it back)
527    pub cursor: usize,
528    /// the last run's timing
529    pub last_timing: Cell<Option<Timing>>,
530    /// Disable retained document queries for this Session (a fresh-evaluation oracle).
531    pub full_recompute: bool,
532    snapshot0: HashMap<PathBuf, String>,
533    state: State,
534    // the last full run, kept for the incremental step (§6): reused as long
535    // as the universe's texts and declarations are the same, its engine
536    // rebinding the documents that changed and recomputing what read them
537    last: RefCell<Option<Last>>,
538    /// texts that override the disk (the language server's open buffers), by absolute path
539    pub overlay: HashMap<PathBuf, String>,
540}
541
542/// the file name of the session's own declarations
543pub const SCRATCH: &str = "<session>";
544
545#[derive(Clone)]
546struct Last {
547    key: String,
548    docs: Vec<(String, String)>,
549    run: Run,
550}
551
552fn under(path: &str, root: &str) -> bool {
553    path.strip_prefix(root).is_some_and(|suffix| {
554        suffix.is_empty() || suffix.starts_with('.') || suffix.starts_with('[')
555    })
556}
557
558impl Session {
559    /// A session over an entry module (none: a scratch session).
560    pub fn new(entry: Option<&str>) -> Session {
561        Session::with_overlay(entry, None)
562    }
563    /// `overlay`: texts that override the disk (the language server's open buffers), by absolute path
564    pub fn with_overlay(
565        entry: Option<&str>,
566        overlay: Option<&HashMap<PathBuf, String>>,
567    ) -> Session {
568        let entry_path = entry.map(|e| std::path::absolute(e).unwrap_or_else(|_| PathBuf::from(e)));
569        let mut s = Session {
570            entry_path,
571            log: vec![],
572            cursor: 0,
573            last_timing: Cell::new(None),
574            full_recompute: false,
575            snapshot0: HashMap::new(),
576            state: State::default(),
577            last: RefCell::new(None),
578            overlay: overlay.cloned().unwrap_or_default(),
579        };
580        s.snapshot0 = s.snapshot_from_disk();
581        s.state = s.initial_state();
582        s
583    }
584
585    /// The entry module's absolute path.
586    pub fn entry_abs(&self) -> PathBuf {
587        self.entry_path.clone().unwrap_or_else(|| {
588            std::path::absolute(SCRATCH).unwrap_or_else(|_| PathBuf::from(SCRATCH))
589        })
590    }
591    /// The entry module's file name, as `:roots` shows it.
592    pub fn entry_name(&self) -> String {
593        self.entry_path
594            .as_ref()
595            .and_then(|p| p.file_name())
596            .map(|n| n.to_string_lossy().to_string())
597            .unwrap_or_else(|| SCRATCH.to_string())
598    }
599
600    // the universe's texts as they are on disk now: the entry and every
601    // module reachable from it (a module that cannot be read is absent and
602    // reported on use, as the command line reports it)
603    fn snapshot_from_disk(&self) -> HashMap<PathBuf, String> {
604        let mut snap = HashMap::new();
605        let Some(entry) = &self.entry_path else {
606            return snap;
607        };
608        let pkg = open_package_universe(entry);
609        let r = load_modules(
610            entry,
611            pkg.as_ref().map(|u| &u.resolver),
612            Some(&self.overlay),
613        );
614        let mut paths: Vec<PathBuf> = vec![entry.clone()];
615        paths.extend(r.modules.iter().map(|m| m.path.clone()));
616        for p in paths {
617            if let Some(t) = self.overlay.get(&p) {
618                snap.insert(p, t.clone());
619                continue;
620            }
621            if let Ok(t) = std::fs::read_to_string(&p) {
622                snap.insert(p, t);
623            }
624        }
625        snap
626    }
627    fn initial_state(&self) -> State {
628        State {
629            snapshot: self.snapshot0.clone(),
630            decls: vec![],
631            outputs: vec![],
632            documents: vec![],
633        }
634    }
635
636    // ---- the log ----
637    /// Apply an operation and log it; a refused operation is an error and is not
638    /// logged. An operation after undo discards what was undone.
639    pub fn apply(&mut self, op: Op) -> SResult<()> {
640        self.log.truncate(self.cursor); // a new operation after :undo discards what was undone
641        let mut st = std::mem::take(&mut self.state);
642        let r = self.apply_to(&mut st, &op); // a refused operation errs and is not logged
643        self.state = st;
644        r?;
645        self.log.push(op);
646        self.cursor += 1;
647        Ok(())
648    }
649    /// Step back `n` operations; returns how many were undone.
650    pub fn undo(&mut self, n: usize) -> usize {
651        let to = self.cursor.saturating_sub(n);
652        let stepped = self.cursor - to;
653        self.cursor = to;
654        self.replay();
655        stepped
656    }
657    /// Step forward `n` operations; returns how many were redone.
658    pub fn redo(&mut self, n: usize) -> usize {
659        let to = (self.cursor + n).min(self.log.len());
660        let stepped = to - self.cursor;
661        self.cursor = to;
662        self.replay();
663        stepped
664    }
665    fn replay(&mut self) {
666        let mut st = self.initial_state();
667        let ops: Vec<Op> = self.log[..self.cursor].to_vec();
668        for op in &ops {
669            let _ = self.apply_to(&mut st, op);
670        }
671        self.state = st;
672    }
673    /// The reload operation for the universe as it is on disk now.
674    pub fn reload_op(&self) -> Op {
675        Op::Reload {
676            snapshot: self.snapshot_from_disk(),
677        }
678    }
679
680    fn apply_to(&self, st: &mut State, op: &Op) -> SResult<()> {
681        match op {
682            Op::Bind { name, src } => {
683                let (modules, _, _) = self.build(st);
684                if !modules
685                    .iter()
686                    .any(|m| m.env.inputs.borrow().contains_key(name))
687                {
688                    return Err(SessionError::new(format!("no input named {name}")));
689                }
690                let (doc, origin, file) = match src {
691                    BindSource::Expr { text } => (self.eval_to_doc(st, text)?, Origin::Expr, None),
692                    BindSource::File { file, text } => (
693                        parse_doc(text, file, Some(file))?,
694                        Origin::File,
695                        Some(file.clone()),
696                    ),
697                    BindSource::Inline { text } => {
698                        (parse_doc(text, "the document", None)?, Origin::Inline, None)
699                    }
700                };
701                st.set_document(
702                    name,
703                    Document {
704                        origin,
705                        file,
706                        base: doc.clone(),
707                        doc,
708                        edited: false,
709                    },
710                );
711                Ok(())
712            }
713            Op::Unbind { name } => {
714                if st.document(name).is_none() {
715                    return Err(SessionError::new(format!("{name} is not bound")));
716                }
717                st.documents.retain(|(k, _)| k != name);
718                Ok(())
719            }
720            Op::Edit { kind, path, expr } => self.edit(st, *kind, path, expr.as_deref()),
721            Op::Declare { name, text } => {
722                st.remove_decl(name);
723                st.remove_output(name);
724                st.decls.push((name.clone(), text.clone()));
725                Ok(())
726            }
727            Op::Output { name, ty, expr } => {
728                st.remove_decl(name);
729                st.remove_output(name);
730                st.outputs.push((name.clone(), ty.clone(), expr.clone()));
731                Ok(())
732            }
733            Op::Drop { name } => {
734                let a = st.remove_decl(name);
735                let b = st.remove_output(name);
736                if !a && !b {
737                    return Err(SessionError::new(format!(
738                        "no session declaration named {name}"
739                    )));
740                }
741                Ok(())
742            }
743            Op::Reload { snapshot } => {
744                st.snapshot = snapshot.clone();
745                Ok(())
746            }
747            Op::Reset => {
748                st.decls.clear();
749                st.outputs.clear();
750                st.documents.clear();
751                Ok(())
752            }
753        }
754    }
755
756    // ---- documents and edits (§3) ----
757    fn eval_to_doc(&self, st: &State, expr_text: &str) -> SResult<Value> {
758        let expr = parse_expr(expr_text)?;
759        let r = self.engine_for(st);
760        if r.eng.is_none() || r.entry.is_none() {
761            return Err(SessionError::new(self.load_failure(&r)));
762        }
763        let sc = Scope::new("", Some(r.entry.as_ref().unwrap().env.clone()));
764        self.scratch(&r, |eng, _| {
765            let result = (|| -> Result<Value, Fail> {
766                let v = eng.ev(&expr, &sc)?;
767                let v = eng.materialize(v, &[Seg::Name("_".into())])?;
768                eng.force_all(&v);
769                Ok(v)
770            })();
771            match result {
772                Ok(v) => {
773                    let text = eng.serialize(&v, "", false);
774                    if text.is_empty() {
775                        return Err(SessionError::new("the value is not data"));
776                    }
777                    read_json(&text).map_err(|_| SessionError::new("the value is not data"))
778                }
779                Err(Fail::Eval(e)) => Err(SessionError::new(e.msg)),
780                Err(_) => Err(SessionError::new("the value is invalid")),
781            }
782        })
783    }
784
785    fn edit(&self, st: &mut State, kind: EditKind, path: &str, expr: Option<&str>) -> SResult<()> {
786        let segs: SegPath =
787            parse_path(path, "").map_err(|_| SessionError::new(format!("bad path {path}")))?;
788        let root = match segs.first() {
789            Some(Seg::Name(n)) if !n.is_empty() => n.clone(),
790            _ => return Err(SessionError::new(format!("bad path {path}"))),
791        };
792        if segs.len() < 2 {
793            return Err(SessionError::new(format!(
794                "a path below a root is required, got {path}"
795            )));
796        }
797        let value = match kind {
798            EditKind::Remove => None,
799            _ => Some(self.eval_to_doc(st, expr.unwrap_or(""))?),
800        };
801        self.document_of(st, &root)?;
802        let doc = st.document(&root).cloned().unwrap();
803        let new_doc = edit_value(&doc.doc, &segs, 1, kind, value.as_ref(), path)?;
804        let d = st.document_mut(&root).unwrap();
805        d.doc = new_doc;
806        d.edited = true;
807        Ok(())
808    }
809
810    // the document of a root, made if the root has none yet: an unbound
811    // input's fallback, or an output detached into its settable projection
812    fn document_of(&self, st: &mut State, root: &str) -> SResult<()> {
813        if st.document(root).is_some() {
814            return Ok(());
815        }
816        let (modules, _, _) = self.build(st);
817        let input_mod = modules
818            .iter()
819            .any(|m| m.env.inputs.borrow().contains_key(root));
820        let output_mod = modules
821            .iter()
822            .any(|m| m.env.outputs.borrow().iter().any(|(o, _, _)| o == root));
823        if !input_mod && !output_mod {
824            return Err(SessionError::new(if st.output(root).is_some() {
825                format!("{root} is a session output; edit the roots it reads")
826            } else {
827                format!("no root named {root}")
828            }));
829        }
830        let r = self.run_state(st, Mode::Full);
831        let (Some(eng), Some(entry)) = (&r.eng, &r.entry) else {
832            return Err(SessionError::new(self.load_failure(&r)));
833        };
834        let v = entry.env.root(root);
835        let bad = v.is_none()
836            || r.diags
837                .iter()
838                .any(|d| d.severity == "error" && is_root_diag(d, root));
839        if bad {
840            return Err(SessionError::new(format!(
841                "{root} is invalid; fix it before editing"
842            )));
843        }
844        let text = eng.serialize(&v.unwrap(), root, true);
845        let doc = read_json(&text)
846            .map_err(|_| SessionError::new(format!("{root} is invalid; fix it before editing")))?;
847        st.set_document(
848            root,
849            Document {
850                origin: if input_mod {
851                    Origin::Fallback
852                } else {
853                    Origin::Detached
854                },
855                file: None,
856                base: doc.clone(),
857                doc,
858                edited: false,
859            },
860        );
861        Ok(())
862    }
863
864    // ---- building the universe ----
865    fn build(&self, st: &State) -> (Vec<Rc<Module>>, Option<Rc<Module>>, Vec<Diag>) {
866        let entry_abs = self.entry_abs();
867        let mut overlay = st.snapshot.clone();
868        let text = st.snapshot.get(&entry_abs).cloned().or_else(|| {
869            if self.entry_path.is_none() {
870                Some(String::new())
871            } else {
872                None
873            }
874        });
875        if let Some(mut text) = text {
876            let detached: Vec<String> = st
877                .documents
878                .iter()
879                .filter(|(_, d)| d.origin == Origin::Detached)
880                .map(|(n, _)| n.clone())
881                .collect();
882            text = detach_outputs(&text, &detached);
883            let extra: Vec<&str> = st.decls.iter().map(|(_, t)| t.as_str()).collect();
884            if !extra.is_empty() {
885                if text.ends_with('\n') {
886                    text.pop();
887                }
888                text.push('\n');
889                text.push_str(&extra.join("\n"));
890                text.push('\n');
891            }
892            overlay.insert(entry_abs.clone(), text);
893        }
894        let pkg = if self.entry_path.is_some() {
895            open_package_universe(&entry_abs)
896        } else {
897            None
898        };
899        let mut diags: Vec<Diag> = vec![];
900        if let Some(u) = &pkg {
901            diags.extend(u.diags.clone());
902            diags.extend(verify_lock(u));
903        }
904        let r = load_modules(
905            &entry_abs,
906            pkg.as_ref().map(|u| &u.resolver),
907            Some(&overlay),
908        );
909        diags.extend(r.diags);
910        (r.modules, r.entry, diags)
911    }
912
913    fn load_failure(&self, r: &Run) -> String {
914        match r.load_diags.first() {
915            Some(d) => format!(
916                "{}{}",
917                d.code
918                    .as_ref()
919                    .map(|c| format!("[{c}] "))
920                    .unwrap_or_default(),
921                d.message
922            ),
923            None => "the universe did not load".into(),
924        }
925    }
926
927    // an inference context over the entry's scope in which the session's
928    // outputs are variables of their inferred types, in declaration order
929    fn session_ctx(
930        &self,
931        st: &State,
932        env: &Rc<Env>,
933        report: Rc<dyn Fn(&str, String)>,
934        up_to: Option<&str>,
935    ) -> Ctx {
936        let mut cx = make_ctx(env.clone(), report);
937        for (name, ty_text, expr_text) in &st.outputs {
938            if Some(name.as_str()) == up_to {
939                break;
940            }
941            let Ok(expr) = parse_expr(expr_text) else {
942                continue;
943            }; // a session output that does not parse is not in scope
944            let mut quiet = make_ctx(env.clone(), Rc::new(|_, _| {}));
945            quiet.vars = cx.vars.clone();
946            let mut rt = infer(&quiet, &expr).rt;
947            if let Some(t) = ty_text {
948                if let Ok((d, _)) = parse_decl(&format!("output {name}: {t} = 0")) {
949                    if let DeclBody::Output { ty, .. } = &d.body {
950                        rt = env.resolve(ty, None).ok();
951                    }
952                }
953            }
954            cx.vars.insert(name.clone(), Ty { rt, abs: false });
955        }
956        cx
957    }
958
959    /// load, check, and (unless `mode` says otherwise) evaluate the state
960    pub fn run(&self, mode: Mode) -> Run {
961        self.run_state(&self.state, mode)
962    }
963    fn run_state(&self, st: &State, mode: Mode) -> Run {
964        #[cfg(feature = "runtime-diagnostics")]
965        let mut timings = crate::evaluation_diagnostics::Span::new("session_run", 0);
966        if mode == Mode::Full && !self.full_recompute && !full_recompute() {
967            if let Some(r) = self.step_from(st) {
968                #[cfg(feature = "runtime-diagnostics")]
969                timings.mark("reuse");
970                #[cfg(feature = "runtime-diagnostics")]
971                timings.finish();
972                return r;
973            }
974        }
975        #[cfg(feature = "runtime-diagnostics")]
976        timings.mark("try_reuse");
977        let r = self.run_fresh(st, mode);
978        #[cfg(feature = "runtime-diagnostics")]
979        timings.mark("fresh_run");
980        if mode == Mode::Full {
981            *self.last.borrow_mut() = if r.eng.is_some() {
982                Some(Last {
983                    key: self.universe_key(st),
984                    docs: self.doc_keys(st),
985                    run: r.clone(),
986                })
987            } else {
988                None
989            };
990        }
991        #[cfg(feature = "runtime-diagnostics")]
992        timings.mark("cache_last");
993        #[cfg(feature = "runtime-diagnostics")]
994        timings.finish();
995        r
996    }
997    fn universe_key(&self, st: &State) -> String {
998        let mut snap: Vec<(String, &String)> = st
999            .snapshot
1000            .iter()
1001            .map(|(p, t)| (p.display().to_string(), t))
1002            .collect();
1003        snap.sort();
1004        let mut detached: Vec<&String> = st
1005            .documents
1006            .iter()
1007            .filter(|(_, d)| d.origin == Origin::Detached)
1008            .map(|(n, _)| n)
1009            .collect();
1010        detached.sort();
1011        format!(
1012            "{:?}|{:?}|{:?}|{:?}|{:?}",
1013            self.entry_abs(),
1014            snap,
1015            st.decls,
1016            st.outputs,
1017            detached
1018        )
1019    }
1020    fn doc_keys(&self, st: &State) -> Vec<(String, String)> {
1021        st.documents
1022            .iter()
1023            .map(|(n, d)| (n.clone(), doc_json(&d.doc)))
1024            .collect()
1025    }
1026    // the incremental step: the same universe, some documents changed
1027    fn step_from(&self, st: &State) -> Option<Run> {
1028        let last = self.last.borrow().clone()?;
1029        let (Some(eng), Some(entry)) = (last.run.eng.clone(), last.run.entry.clone()) else {
1030            return None;
1031        };
1032        if last.key != self.universe_key(st) {
1033            return None;
1034        }
1035        let docs = self.doc_keys(st);
1036        let mut changed: Vec<String> = vec![];
1037        for (n, k) in &docs {
1038            if last.docs.iter().find(|(m, _)| m == n).map(|(_, v)| v) != Some(k) {
1039                changed.push(n.clone());
1040            }
1041        }
1042        for (n, _) in &last.docs {
1043            if !docs.iter().any(|(m, _)| m == n) {
1044                changed.push(n.clone());
1045            }
1046        }
1047        if changed.is_empty() {
1048            self.last_timing.set(Some(last.run.timing));
1049            return Some(last.run.clone());
1050        }
1051        let t0 = Instant::now();
1052        let r = &last.run;
1053        let env = entry.env.clone();
1054        let edits = eng.edits.borrow().clone()?;
1055        let before = edits.slot_computes.get();
1056        edits.begin(
1057            &eng,
1058            &changed,
1059            &st.documents
1060                .iter()
1061                .map(|(n, d)| (n.clone(), d.doc.clone()))
1062                .collect(),
1063        );
1064        let bind = |current: &Rc<Engine>| {
1065            *current.edits.borrow_mut() = Some(edits.clone());
1066            for m in &r.modules {
1067                current.install_hooks(&m.env, true);
1068            }
1069            for (name, d) in &st.documents {
1070                let m = r
1071                    .modules
1072                    .iter()
1073                    .find(|x| x.env.inputs.borrow().contains_key(name))
1074                    .cloned()
1075                    .unwrap_or_else(|| entry.clone());
1076                let decl = m.env.inputs.borrow().get(name).cloned();
1077                let Some((ty_ast, _)) = decl else {
1078                    continue;
1079                };
1080                let sc = Scope::new(name, Some(m.env.clone()));
1081                match m.env.resolve(&ty_ast, None) {
1082                    Ok(rt) => current.bind_root(name, RootSrc::Doc(d.doc.clone()), &rt, &sc),
1083                    Err(e) => env.report(Diag::error(e, name.clone(), None)),
1084                }
1085            }
1086            for m in &r.modules {
1087                for (name, ty_ast, expr) in m.env.outputs.borrow().clone() {
1088                    let sc = Scope::new(&name, Some(m.env.clone()));
1089                    match m.env.resolve(&ty_ast, None) {
1090                        Ok(rt) => current.bind_root(&name, RootSrc::Expr(&expr), &rt, &sc),
1091                        Err(e) => env.report(Diag::error(e, name.clone(), None)),
1092                    }
1093                }
1094            }
1095            for (name, expr, rt) in &r.session_roots {
1096                current.bind_root(
1097                    name,
1098                    RootSrc::Expr(expr),
1099                    rt,
1100                    &Scope::new(name, Some(entry.env.clone())),
1101                );
1102            }
1103        };
1104        let current = Engine::evaluate_session(&env, &bind, Some(eng));
1105        current.validate_all("");
1106        let sorted = sort_diags(env.diagnostics_vec());
1107        env.diag_set(sorted.clone());
1108        let recomputed = edits.slot_computes.get() - before;
1109        let elapsed = ms(t0);
1110        let timing = Timing {
1111            load: 0.0,
1112            check: 0.0,
1113            bind: 0.0,
1114            evaluate: elapsed,
1115            total: elapsed,
1116            recomputed: Some(recomputed),
1117            slots: Some(current.indexed_slots()),
1118        };
1119        let run = Run {
1120            eng: Some(current),
1121            diags: sorted,
1122            timing,
1123            ..r.clone()
1124        };
1125        *self.last.borrow_mut() = Some(Last {
1126            key: last.key.clone(),
1127            docs,
1128            run: run.clone(),
1129        });
1130        self.last_timing.set(Some(timing));
1131        Some(run)
1132    }
1133    fn run_fresh(&self, st: &State, mode: Mode) -> Run {
1134        #[cfg(feature = "runtime-diagnostics")]
1135        let mut timings = crate::evaluation_diagnostics::Span::new("session_fresh", 0);
1136        let t0 = Instant::now();
1137        let (modules, entry, load_diags) = self.build(st);
1138        #[cfg(feature = "runtime-diagnostics")]
1139        timings.mark("load");
1140        let load = ms(t0);
1141        let mut out = Run {
1142            modules,
1143            entry,
1144            load_diags,
1145            checks: vec![],
1146            session_checks: vec![],
1147            session_roots: vec![],
1148            eng: None,
1149            diags: vec![],
1150            timing: Timing {
1151                load,
1152                check: 0.0,
1153                bind: 0.0,
1154                evaluate: 0.0,
1155                total: 0.0,
1156                recomputed: None,
1157                slots: None,
1158            },
1159        };
1160        let finish = |mut out: Run| -> Run {
1161            out.timing.total = ms(t0);
1162            self.last_timing.set(Some(out.timing));
1163            out
1164        };
1165        if !out.load_diags.is_empty() || out.entry.is_none() {
1166            #[cfg(feature = "runtime-diagnostics")]
1167            timings.mark("load_error_return");
1168            #[cfg(feature = "runtime-diagnostics")]
1169            timings.finish();
1170            return finish(out);
1171        }
1172        let entry = out.entry.clone().unwrap();
1173        let t1 = Instant::now();
1174        for m in &out.modules {
1175            for d in check_module(&m.decls, Some(m.env.clone()), None) {
1176                out.checks.push((m.path.display().to_string(), d));
1177            }
1178        }
1179        // session outputs: their expressions are inferred where a declared
1180        // output's would be checked; the inferred type is the root's type
1181        let mut session_roots: Vec<(String, Rc<Expr>, RT)> = vec![];
1182        for (name, ty_text, expr_text) in &st.outputs {
1183            let taken = out.modules.iter().any(|m| {
1184                m.env.inputs.borrow().contains_key(name)
1185                    || m.env.outputs.borrow().iter().any(|(o, _, _)| o == name)
1186            });
1187            if taken {
1188                out.session_checks.push(Diag {
1189                    severity: "error".into(),
1190                    id: None,
1191                    code: Some("E3018".into()),
1192                    message: format!("root {name} is already declared by the universe"),
1193                    path: name.clone(),
1194                    loc: None,
1195                    by: None,
1196                });
1197                continue;
1198            }
1199            let expr = match parse_expr(expr_text) {
1200                Ok(e) => e,
1201                Err(e) => {
1202                    out.session_checks.push(Diag {
1203                        severity: "error".into(),
1204                        id: None,
1205                        code: None,
1206                        message: e.0,
1207                        path: name.clone(),
1208                        loc: None,
1209                        by: None,
1210                    });
1211                    continue;
1212                }
1213            };
1214            let sink: Rc<RefCell<Vec<Diag>>> = Rc::new(RefCell::new(vec![]));
1215            let sink2 = sink.clone();
1216            let n2 = name.clone();
1217            let cx = self.session_ctx(
1218                st,
1219                &entry.env,
1220                Rc::new(move |code, msg| {
1221                    sink2.borrow_mut().push(Diag {
1222                        severity: "error".into(),
1223                        id: None,
1224                        code: Some(code.to_string()),
1225                        message: msg,
1226                        path: n2.clone(),
1227                        loc: None,
1228                        by: None,
1229                    })
1230                }),
1231                Some(name),
1232            );
1233            let ty = infer(&cx, &expr);
1234            let found: Vec<Diag> = sink.borrow().clone();
1235            if !found.is_empty() {
1236                out.session_checks.extend(found);
1237                continue;
1238            }
1239            let rt: RT = match ty_text {
1240                Some(t) => {
1241                    let resolved =
1242                        parse_decl(&format!("output {name}: {t} = 0")).and_then(|(d, _)| match &d
1243                            .body
1244                        {
1245                            DeclBody::Output { ty, .. } => {
1246                                entry.env.resolve(ty, None).map_err(SessionError::new)
1247                            }
1248                            _ => Err(SessionError::new("not an output")),
1249                        });
1250                    match resolved {
1251                        Ok(rt) => rt,
1252                        Err(e) => {
1253                            out.session_checks.push(Diag {
1254                                severity: "error".into(),
1255                                id: None,
1256                                code: None,
1257                                message: e.0,
1258                                path: name.clone(),
1259                                loc: None,
1260                                by: None,
1261                            });
1262                            continue;
1263                        }
1264                    }
1265                }
1266                None => ty.rt.unwrap_or_else(|| crate::semantics::ty(RTk::Any)),
1267            };
1268            session_roots.push((name.clone(), expr, rt));
1269        }
1270        out.timing.check = ms(t1);
1271        #[cfg(feature = "runtime-diagnostics")]
1272        timings.mark("check");
1273        // a static error in a module stops full evaluation as it stops `decl
1274        // evaluate`; a session output that does not check is left out, and a
1275        // bare expression (lazy) evaluates over what loaded regardless
1276        if mode == Mode::Check
1277            || (mode == Mode::Full && out.checks.iter().any(|(_, d)| d.severity == "error"))
1278        {
1279            #[cfg(feature = "runtime-diagnostics")]
1280            timings.mark("check_return");
1281            #[cfg(feature = "runtime-diagnostics")]
1282            timings.finish();
1283            return finish(out);
1284        }
1285
1286        let t2 = Instant::now();
1287        let modules = out.modules.clone();
1288        let edits = (mode == Mode::Full && !self.full_recompute && !full_recompute())
1289            .then(|| Rc::new(Edits::default()));
1290        let bind = |eng: &Rc<Engine>| {
1291            *eng.edits.borrow_mut() = edits.clone();
1292            for m in &modules {
1293                eng.install_hooks(&m.env, true);
1294            }
1295            // documents first (an output may read an input, §5.5), then the
1296            // modules' outputs, then the session's
1297            for (name, d) in &st.documents {
1298                let m = modules
1299                    .iter()
1300                    .find(|x| x.env.inputs.borrow().contains_key(name))
1301                    .cloned()
1302                    .unwrap_or_else(|| entry.clone());
1303                let decl = m.env.inputs.borrow().get(name).cloned();
1304                let Some((ty_ast, _)) = decl else { continue };
1305                let sc = Scope::new(name, Some(m.env.clone()));
1306                match m.env.resolve(&ty_ast, None) {
1307                    Ok(rt) => eng.bind_root(name, RootSrc::Doc(d.doc.clone()), &rt, &sc),
1308                    Err(e) => entry.env.report(Diag::error(e, name.clone(), None)),
1309                }
1310            }
1311            for m in &modules {
1312                let outs = m.env.outputs.borrow().clone();
1313                for (name, ty_ast, expr) in outs {
1314                    let sc = Scope::new(&name, Some(m.env.clone()));
1315                    match m.env.resolve(&ty_ast, None) {
1316                        Ok(rt) => eng.bind_root(&name, RootSrc::Expr(&expr), &rt, &sc),
1317                        Err(e) => entry.env.report(Diag::error(e, name.clone(), None)),
1318                    }
1319                }
1320            }
1321            for (name, expr, rt) in &session_roots {
1322                let sc = Scope::new(name, Some(entry.env.clone()));
1323                eng.bind_root(name, RootSrc::Expr(expr), rt, &sc);
1324            }
1325        };
1326        if mode == Mode::Lazy {
1327            let eng = Engine::new(entry.env.clone());
1328            bind(&eng);
1329            out.session_roots = session_roots;
1330            out.eng = Some(eng.clone());
1331            out.timing.bind = ms(t2);
1332            eng.set_phase(2);
1333            out.diags = entry.env.diagnostics_vec();
1334            #[cfg(feature = "runtime-diagnostics")]
1335            timings.mark("lazy_bind");
1336            #[cfg(feature = "runtime-diagnostics")]
1337            timings.finish();
1338            return finish(out);
1339        }
1340        #[cfg(feature = "runtime-diagnostics")]
1341        timings.mark("prepare_bind");
1342        let t3 = Instant::now();
1343        let eng = Engine::evaluate_session(&entry.env, &bind, None);
1344        #[cfg(feature = "runtime-diagnostics")]
1345        timings.mark("evaluate");
1346        out.session_roots = session_roots;
1347        out.eng = Some(eng.clone());
1348        out.timing.bind = t3.duration_since(t2).as_secs_f64() * 1000.0; // between two instants: never negative
1349        #[cfg(feature = "runtime-diagnostics")]
1350        timings.mark("retain_result");
1351        eng.validate_all("");
1352        #[cfg(feature = "runtime-diagnostics")]
1353        timings.mark("validate");
1354        out.diags = entry.env.diagnostics_vec(); // sorted by drive's caller? no: sorted here (§6.7)
1355        let sorted = sort_diags(out.diags.clone());
1356        entry.env.diag_set(sorted.clone());
1357        out.diags = sorted;
1358        out.timing.evaluate = ms(t3);
1359        #[cfg(feature = "runtime-diagnostics")]
1360        timings.mark("diagnostics_and_timing");
1361        #[cfg(feature = "runtime-diagnostics")]
1362        timings.finish();
1363        finish(out)
1364    }
1365
1366    // ---- questions ----
1367    // the engine an expression evaluates over: the last full run's when the
1368    // universe evaluates (complete, so `$referrers` answers over every
1369    // instance, and nothing is rebuilt), else a lazy run's (bound, unforced)
1370    fn engine_for(&self, st: &State) -> Run {
1371        let full = self.run_state(st, Mode::Full);
1372        if full.eng.is_some() {
1373            full
1374        } else {
1375            self.run_state(st, Mode::Lazy)
1376        }
1377    }
1378    // evaluate `f` over the run's engine and leave the run as it was: the
1379    // diagnostics the expression added and the instances it materialized
1380    // under `_` are removed, forced slots keep the values a full run gives
1381    fn scratch<T>(&self, r: &Run, f: impl FnOnce(&Rc<Engine>, &Rc<Env>) -> T) -> T {
1382        let (eng, env) = (r.eng.clone().unwrap(), r.entry.clone().unwrap().env.clone());
1383        let n = env.diag_len();
1384        let reg = env.registry_len();
1385        let roots: HashSet<String> = env.root_names().into_iter().collect();
1386        let (slots, reads) = {
1387            let candidates = eng.query_pool().scratch_ids();
1388            let current_slots = eng.slots_by_key.borrow();
1389            let current_reads = eng.reads.borrow();
1390            let mut slots = Vec::new();
1391            let mut reads = Vec::new();
1392            for key in candidates {
1393                if under(&key, "_") {
1394                    if let Some(slot) = current_slots.get(&key) {
1395                        slots.push((key.clone(), slot.clone()));
1396                    }
1397                }
1398                if let Some(deps) = current_reads.get(&key) {
1399                    reads.push((key, deps.clone()));
1400                }
1401            }
1402            (slots, reads)
1403        };
1404        let out = eng.transient(|| f(&eng, &env));
1405        // an input demanded through its fallback by the expression alone is not a root of the run
1406        let demanded: Vec<String> = env
1407            .root_names()
1408            .into_iter()
1409            .filter(|k| !roots.contains(k))
1410            .collect();
1411        let under_demanded = |p: &str| demanded.iter().any(|k| under(p, k));
1412        for k in &demanded {
1413            env.remove_root(k);
1414            eng.failed_inputs.borrow_mut().remove(k);
1415            eng.remove_query_reads(&format!("root:{k}"));
1416        }
1417        if demanded.is_empty() {
1418            // The pool can also contain keys held by old Runs. Membership in
1419            // these current maps, rather than pool liveness, decides cleanup.
1420            let candidates = eng.query_pool().scratch_ids();
1421            for key in &candidates {
1422                eng.reads.borrow_mut().remove(key);
1423            }
1424            // Drop all temporary reads before any slot, with the same per-key
1425            // borrow scope as before: releasing an Inst can drop a public
1426            // Bridge callback's user-provided captures.
1427            for key in candidates {
1428                if under(&key, "_") {
1429                    eng.slots_by_key.borrow_mut().remove(&key);
1430                }
1431            }
1432        } else {
1433            // Arbitrary fallback-root names still need the complete scan.
1434            // Preserve its key snapshots and per-removal borrowing/drop order.
1435            let keys: Vec<_> = eng.reads.borrow().keys().cloned().collect();
1436            for key in keys {
1437                let path = key.strip_prefix("assert:").unwrap_or(&key);
1438                if under_demanded(path) || under(path, "_") {
1439                    eng.reads.borrow_mut().remove(&key);
1440                }
1441            }
1442            let keys: Vec<_> = eng.slots_by_key.borrow().keys().cloned().collect();
1443            for key in keys {
1444                if under_demanded(&key) || under(&key, "_") {
1445                    eng.slots_by_key.borrow_mut().remove(&key);
1446                }
1447            }
1448        }
1449        eng.slots_by_key.borrow_mut().extend(slots);
1450        eng.reads.borrow_mut().extend(reads);
1451        env.diag_truncate(n);
1452        if demanded.is_empty() {
1453            // The existing prefix is unchanged by the old predicate even if
1454            // a caller publicly changed an instance's path. Only the appended
1455            // tail can contain new scratch instances; no path text is needed.
1456            env.registry_retain_from(
1457                reg,
1458                |inst| !matches!(inst.borrow().path.first(), Some(Seg::Name(n)) if &**n == "_"),
1459            );
1460        } else {
1461            let mut i = 0usize;
1462            env.registry_retain(|inst| {
1463                let idx = i;
1464                i += 1;
1465                let p = path_str(&inst.borrow().path, None);
1466                let scratch_root =
1467                    matches!(inst.borrow().path.first(), Some(Seg::Name(n)) if &**n == "_");
1468                if idx < reg {
1469                    !under_demanded(&p)
1470                } else {
1471                    !scratch_root && !under_demanded(&p)
1472                }
1473            });
1474        }
1475        eng.computing.borrow_mut().clear();
1476        if let Some(edits) = eng.edits.borrow().as_ref() {
1477            edits.prune(&eng);
1478        }
1479        eng.maintain_query_ids();
1480        out
1481    }
1482
1483    // ---- questions ----
1484    /// partial evaluation of one expression (§2.1)
1485    pub fn evaluate_expr(&self, text: &str) -> SResult<ExprResult> {
1486        let expr = parse_expr(text)?;
1487        let r = self.engine_for(&self.state);
1488        if r.eng.is_none() || r.entry.is_none() {
1489            return Ok(ExprResult {
1490                value: None,
1491                diags: r.load_diags.clone(),
1492                error: Some((None, String::new())),
1493            });
1494        }
1495        let entry_env = r.entry.as_ref().unwrap().env.clone();
1496        let sc = Scope::new("", Some(entry_env.clone()));
1497        let named = identifiers(text);
1498        Ok(self.scratch(&r, |eng, env| {
1499            // the run may already have reported (a root whose binding failed); the
1500            // expression's own diagnostics are the ones that arise from here on,
1501            // plus the diagnostics of the roots it names
1502            let from = env.diag_len();
1503            let arising = |env: &Env| -> Vec<Diag> {
1504                let all = env.diagnostics_vec();
1505                let mut out: Vec<Diag> = all[..from.min(all.len())]
1506                    .iter()
1507                    .filter(|d| named.contains(&d.path))
1508                    .cloned()
1509                    .collect();
1510                out.extend(all[from.min(all.len())..].iter().cloned());
1511                sort_diags(out)
1512            };
1513            let result = (|| -> Result<Value, Fail> {
1514                let v = eng.ev(&expr, &sc)?;
1515                let v = eng.materialize(v, &[Seg::Name("_".into())])?;
1516                eng.force_all(&v);
1517                Ok(v)
1518            })();
1519            match result {
1520                Ok(v) => ExprResult {
1521                    value: Some(self.value_text(eng, &v)),
1522                    diags: arising(env),
1523                    error: None,
1524                },
1525                Err(Fail::Eval(e)) => ExprResult {
1526                    value: None,
1527                    diags: arising(env),
1528                    error: Some((e.code, e.msg)),
1529                },
1530                Err(_) => ExprResult {
1531                    value: None,
1532                    diags: arising(env),
1533                    error: Some((None, String::new())),
1534                },
1535            }
1536        }))
1537    }
1538    fn value_text(&self, eng: &Engine, v: &Value) -> String {
1539        match v {
1540            Value::Absent | Value::Undef => "absent".into(),
1541            Value::Clo(_) | Value::Nat(_) | Value::Std(_) => "<function>".into(),
1542            Value::NsRef(_) => "<namespace>".into(),
1543            Value::Pat(re) => format!("/{re}/"),
1544            _ => eng.serialize(v, "", false),
1545        }
1546    }
1547
1548    /// the roots of the universe and of the session (`:roots`)
1549    pub fn roots(&self) -> Vec<RootInfo> {
1550        let (modules, _, _) = self.build(&self.state);
1551        let entry_abs = self.entry_abs();
1552        let entry_dir = entry_abs
1553            .parent()
1554            .map(|p| p.to_path_buf())
1555            .unwrap_or_default();
1556        let rel = |p: &Path| {
1557            if p == entry_abs {
1558                self.entry_name()
1559            } else {
1560                relative_path(&entry_dir, p)
1561            }
1562        };
1563        let mut out = vec![];
1564        for m in &modules {
1565            // the module's roots in declaration order, from its text as loaded
1566            // (a detached output is blanked from the universe but still a root)
1567            let parsed;
1568            let decls: &Vec<Decl> = if m.path == entry_abs {
1569                parsed = parse_source(
1570                    self.state
1571                        .snapshot
1572                        .get(&m.path)
1573                        .map(|s| s.as_str())
1574                        .unwrap_or(""),
1575                )
1576                .decls;
1577                &parsed
1578            } else {
1579                &m.decls
1580            };
1581            for decl in decls {
1582                match &decl.body {
1583                    DeclBody::Output { name, .. } => {
1584                        let d = self.state.document(name);
1585                        out.push(RootInfo {
1586                            kind: "output",
1587                            name: name.clone(),
1588                            module: rel(&m.path),
1589                            exported: decl.exported,
1590                            session: false,
1591                            binding: if d.map(|d| d.origin) == Some(Origin::Detached) {
1592                                "detached".into()
1593                            } else {
1594                                String::new()
1595                            },
1596                            detail: String::new(),
1597                            edited: d.map(|d| d.edited).unwrap_or(false),
1598                        });
1599                    }
1600                    DeclBody::Input { name, fallback, .. } => {
1601                        let d = self.state.document(name);
1602                        let binding = match d {
1603                            Some(d) if d.origin == Origin::Fallback => "fallback",
1604                            Some(_) => "bound",
1605                            None => {
1606                                if fallback.is_some() {
1607                                    "fallback"
1608                                } else {
1609                                    "unbound"
1610                                }
1611                            }
1612                        };
1613                        let detail = match d {
1614                            Some(d) => match d.origin {
1615                                Origin::File => d.file.clone().unwrap_or_default(),
1616                                Origin::Inline => "(inline)".into(),
1617                                Origin::Expr => "(expression)".into(),
1618                                _ => String::new(),
1619                            },
1620                            None => String::new(),
1621                        };
1622                        out.push(RootInfo {
1623                            kind: "input",
1624                            name: name.clone(),
1625                            module: rel(&m.path),
1626                            exported: false,
1627                            session: false,
1628                            binding: binding.into(),
1629                            detail,
1630                            edited: d.map(|d| d.edited).unwrap_or(false),
1631                        });
1632                    }
1633                    _ => {}
1634                }
1635            }
1636        }
1637        for (name, _, _) in &self.state.outputs {
1638            out.push(RootInfo {
1639                kind: "output",
1640                name: name.clone(),
1641                module: String::new(),
1642                exported: false,
1643                session: true,
1644                binding: String::new(),
1645                detail: String::new(),
1646                edited: false,
1647            });
1648        }
1649        out
1650    }
1651    /// Every root's name, the session's included.
1652    pub fn all_root_names(&self) -> Vec<String> {
1653        self.roots().into_iter().map(|r| r.name).collect()
1654    }
1655    /// Whether a root of that name exists.
1656    pub fn has_root(&self, name: &str) -> bool {
1657        self.all_root_names().iter().any(|n| n == name)
1658    }
1659
1660    /// static diagnostics of every module, with the file each is reported against
1661    pub fn check(&self) -> Vec<(String, Diag)> {
1662        let r = self.run(Mode::Check);
1663        let entry = self.entry_abs().display().to_string();
1664        let mut out: Vec<(String, Diag)> = r
1665            .load_diags
1666            .iter()
1667            .map(|d| (entry.clone(), d.clone()))
1668            .collect();
1669        out.extend(r.checks);
1670        out.extend(r.session_checks.into_iter().map(|d| (entry.clone(), d)));
1671        out
1672    }
1673
1674    /// full evaluation of the named roots (`:evaluate`), or of the exported outputs
1675    /// a root in the form its module declares (docs/tooling/05_render.md §3,
1676    /// §8), with the overrides given: its text, or the files of a fan-out;
1677    /// None when nothing applies (canonical JSON, no override); an error as
1678    /// its diagnostic, with the template's path when a template is at fault
1679    pub fn render(&self, run: &Run, name: &str, over: &RenderOverrides) -> Option<Rendered> {
1680        let (Some(entry), Some(eng)) = (run.entry.clone(), run.eng.clone()) else {
1681            return None;
1682        };
1683        let mut found: Option<(&Decl, &Rc<Module>)> = None;
1684        for m in &run.modules {
1685            for d in &m.decls {
1686                if matches!(&d.body, DeclBody::Output { name: n, .. } if n == name) {
1687                    found = Some((d, m));
1688                }
1689            }
1690        }
1691        let form = match found {
1692            Some((d, _)) => match declared_form(d) {
1693                Ok(f) => f,
1694                Err(m) => {
1695                    return Some(Rendered::Error {
1696                        diag: Diag::error(m, name.to_string(), Some("E7004")),
1697                        file: None,
1698                    })
1699                }
1700            },
1701            None => Form::default(),
1702        };
1703        let applies = form != Form::default()
1704            || over.yaml.is_some()
1705            || over.indent.is_some()
1706            || over.template.is_some();
1707        if !applies {
1708            return None;
1709        }
1710        let v = entry.env.root(name)?;
1711        let read_tpl = |abs: &str| std::fs::read_to_string(abs).ok();
1712        let tpl_path = over.template.clone().or_else(|| form.template.clone());
1713        let template = match &tpl_path {
1714            None => None,
1715            Some(t) => {
1716                let abs = if over.template.is_some() {
1717                    absolute(t)
1718                } else {
1719                    let dir = found
1720                        .and_then(|(_, m)| m.path.parent().map(|p| p.to_string_lossy().to_string()))
1721                        .unwrap_or_else(|| ".".into());
1722                    resolve_in(&dir, t)
1723                };
1724                let Some(text) = read_tpl(&abs) else {
1725                    return Some(Rendered::Error {
1726                        diag: Diag::error(
1727                            "template cannot be read",
1728                            name.to_string(),
1729                            Some("E7003"),
1730                        ),
1731                        file: Some(t.clone()),
1732                    });
1733                };
1734                let dir = std::path::Path::new(&abs)
1735                    .parent()
1736                    .map(|p| p.to_string_lossy().to_string())
1737                    .unwrap_or_else(|| ".".into());
1738                Some((t.clone(), text, dir))
1739            }
1740        };
1741        let has_template = template.is_some();
1742        match emit_root(&Emission {
1743            eng,
1744            menv: entry.env.clone(),
1745            root_name: name.to_string(),
1746            value: v,
1747            form: form.clone(),
1748            yaml: over.yaml,
1749            indent: over.indent,
1750            template,
1751            read_template: &read_tpl,
1752        }) {
1753            Ok(Emitted::Many(files)) => Some(Rendered::Files(files)),
1754            Ok(Emitted::One(text)) => Some(Rendered::Text {
1755                kind: if has_template {
1756                    "text".into()
1757                } else if over.yaml.unwrap_or(form.yaml) {
1758                    "yaml".into()
1759                } else {
1760                    "json".into()
1761                },
1762                text,
1763            }),
1764            Err(e) => Some(Rendered::Error {
1765                diag: e.diag(),
1766                file: e.file.clone(),
1767            }),
1768        }
1769    }
1770
1771    /// full evaluation of the named roots (`:evaluate`), or of the exported
1772    /// outputs: the run, each root's document (None when invalid), and
1773    /// whether the exported outputs were asked for
1774    pub fn evaluate(
1775        &self,
1776        names: &[String],
1777    ) -> SResult<(Run, Vec<(String, Option<String>)>, bool)> {
1778        let r = self.run(Mode::Full);
1779        let exported = names.is_empty();
1780        let Some(entry) = r.entry.clone() else {
1781            return Ok((r, vec![], exported));
1782        };
1783        let want: Vec<String> = if names.is_empty() {
1784            entry
1785                .decls
1786                .iter()
1787                .filter(|d| d.exported)
1788                .filter_map(|d| match &d.body {
1789                    DeclBody::Output { name, .. } => Some(name.clone()),
1790                    _ => None,
1791                })
1792                .collect()
1793        } else {
1794            names.to_vec()
1795        };
1796        for n in names {
1797            if !self.has_root(n) {
1798                return Err(SessionError::new(format!("no root named {n}")));
1799            }
1800        }
1801        let Some(eng) = r.eng.clone() else {
1802            return Ok((r, want.into_iter().map(|n| (n, None)).collect(), exported));
1803        };
1804        let mut docs = vec![];
1805        for name in want {
1806            let v = entry.env.root(&name);
1807            let bad = v.is_none()
1808                || r.diags
1809                    .iter()
1810                    .any(|d| d.severity == "error" && is_root_diag(d, &name));
1811            let json = if bad {
1812                None
1813            } else {
1814                Some(eng.serialize(&v.unwrap(), &name, false))
1815            };
1816            docs.push((name, json));
1817        }
1818        Ok((r, docs, exported))
1819    }
1820
1821    /// whole-document validation of the named roots (`:validate`), or of every root
1822    pub fn validate(
1823        &self,
1824        names: &[String],
1825    ) -> SResult<(Run, Vec<(String, usize, usize)>, Vec<Diag>)> {
1826        for n in names {
1827            if !self.has_root(n) {
1828                return Err(SessionError::new(format!("no root named {n}")));
1829            }
1830        }
1831        let r = self.run(Mode::Full);
1832        let want: Vec<String> = if !names.is_empty() {
1833            names.to_vec()
1834        } else if let Some(entry) = &r.entry {
1835            entry
1836                .env
1837                .roots
1838                .borrow()
1839                .borrow()
1840                .iter()
1841                .map(|(n, _)| n.clone())
1842                .collect()
1843        } else {
1844            vec![]
1845        };
1846        let diags: Vec<Diag> = r
1847            .diags
1848            .iter()
1849            .filter(|d| {
1850                want.iter().any(|n| is_root_diag(d, n)) || (d.path.is_empty() && names.is_empty())
1851            })
1852            .cloned()
1853            .collect();
1854        let verdicts = want
1855            .iter()
1856            .map(|name| {
1857                let errors = r
1858                    .diags
1859                    .iter()
1860                    .filter(|d| d.severity == "error" && is_root_diag(d, name))
1861                    .count()
1862                    + if r
1863                        .entry
1864                        .as_ref()
1865                        .map(|e| e.env.root(name).is_some())
1866                        .unwrap_or(false)
1867                    {
1868                        0
1869                    } else if r.eng.is_some() {
1870                        1
1871                    } else {
1872                        0
1873                    };
1874                let warnings = r
1875                    .diags
1876                    .iter()
1877                    .filter(|d| d.severity == "warn" && is_root_diag(d, name))
1878                    .count();
1879                (name.clone(), errors, warnings)
1880            })
1881            .collect();
1882        Ok((r, verdicts, diags))
1883    }
1884
1885    /// the static type of an expression (`:type`)
1886    pub fn type_of(&self, text: &str) -> SResult<(String, bool, Vec<Diag>)> {
1887        let expr = parse_expr(text)?;
1888        let (_, entry, diags) = self.build(&self.state);
1889        let Some(entry) = entry else {
1890            return Err(SessionError::new(
1891                diags
1892                    .first()
1893                    .map(|d| d.message.clone())
1894                    .unwrap_or_else(|| "the universe did not load".into()),
1895            ));
1896        };
1897        let sink: Rc<RefCell<Vec<Diag>>> = Rc::new(RefCell::new(vec![]));
1898        let sink2 = sink.clone();
1899        let cx = self.session_ctx(
1900            &self.state,
1901            &entry.env,
1902            Rc::new(move |code, message| {
1903                sink2.borrow_mut().push(Diag {
1904                    severity: "error".into(),
1905                    id: None,
1906                    code: Some(code.to_string()),
1907                    message,
1908                    path: String::new(),
1909                    loc: None,
1910                    by: None,
1911                })
1912            }),
1913            None,
1914        );
1915        let ty = infer(&cx, &expr);
1916        let found = sink.borrow().clone();
1917        Ok((type_text(ty.rt.as_ref()), ty.abs, found))
1918    }
1919
1920    /// the canonical path of the place a navigation names (`:path`)
1921    pub fn path_of(&self, text: &str) -> SResult<String> {
1922        let expr = parse_expr(text)?;
1923        let r = self.engine_for(&self.state);
1924        if r.eng.is_none() || r.entry.is_none() {
1925            return Err(SessionError::new(self.load_failure(&r)));
1926        }
1927        let entry = r.entry.clone().unwrap();
1928        let sc = Scope::new("", Some(entry.env.clone()));
1929        self.scratch(&r, |eng, _| {
1930            let result = (|| -> Result<Option<SegPath>, Fail> {
1931                let mut segs = eng.eval_place(&expr, &sc)?;
1932                // a scalar member or element is a place too: its container's place, one step down
1933                if segs.is_none() {
1934                    match &*expr {
1935                        Expr::Member { x, name, .. } => {
1936                            if let Some(mut base) = eng.eval_place(x, &sc)? {
1937                                base.push(Seg::Name(Rc::from(name.clone())));
1938                                segs = Some(base);
1939                            }
1940                        }
1941                        Expr::Index { x, i } => {
1942                            if let Some(mut base) = eng.eval_place(x, &sc)? {
1943                                let iv = eng.ev(i, &sc)?;
1944                                base.push(match iv {
1945                                    Value::Int(n) => Seg::Idx(n.to_string().parse().unwrap_or(0)),
1946                                    Value::Str(s) => Seg::Key(s.into_rc()),
1947                                    other => Seg::Key(Rc::from(crate::infer::js_str(&other))),
1948                                });
1949                                segs = Some(base);
1950                            }
1951                        }
1952                        Expr::Name(n) if entry.env.root(n).is_some() => {
1953                            segs = Some(vec![Seg::Name(Rc::from(n.clone()))])
1954                        }
1955                        _ => {}
1956                    }
1957                }
1958                Ok(segs)
1959            })();
1960            match result {
1961                Ok(Some(segs)) => Ok(path_str(&segs, None)),
1962                Ok(None) => Err(SessionError::new("the expression does not name a place")),
1963                Err(Fail::Eval(e)) => Err(SessionError::new(e.msg)),
1964                Err(_) => Err(SessionError::new("the place is invalid")),
1965            }
1966        })
1967    }
1968
1969    /// the declaration a name resolves to, with its documentation (`:doc`)
1970    pub fn doc_of(&self, name: &str) -> SResult<Vec<String>> {
1971        let mut parts = name.splitn(2, '.');
1972        let head = parts.next().unwrap_or("");
1973        let member = parts.next();
1974        // a session declaration first
1975        if member.is_none() {
1976            if let Some(t) = self.state.decl(head) {
1977                return Ok(t.split('\n').map(|s| s.to_string()).collect());
1978            }
1979            if let Some((ty, expr)) = self.state.output(head) {
1980                return Ok(vec![format!(
1981                    "{head}{} = {expr}",
1982                    ty.as_ref().map(|t| format!(": {t}")).unwrap_or_default()
1983                )]);
1984            }
1985        }
1986        let (modules, entry, diags) = self.build(&self.state);
1987        let Some(entry) = entry else {
1988            return Err(SessionError::new(
1989                diags
1990                    .first()
1991                    .map(|d| d.message.clone())
1992                    .unwrap_or_else(|| "the universe did not load".into()),
1993            ));
1994        };
1995        let mut module: Option<Rc<Module>> = Some(entry.clone());
1996        let mut target = head.to_string();
1997        if !entry.decls.iter().any(|d| d.name() == Some(head)) {
1998            let im = entry.env.imports.borrow().get(head).cloned();
1999            match im {
2000                Some(im) => {
2001                    module = modules
2002                        .iter()
2003                        .find(|m| Rc::ptr_eq(&m.env, &im.env))
2004                        .cloned();
2005                    target = im.name.clone();
2006                }
2007                None => module = None,
2008            }
2009        }
2010        let decl = module.as_ref().and_then(|m| {
2011            m.decls
2012                .iter()
2013                .find(|d| d.name() == Some(target.as_str()) && d.loc.is_some())
2014                .cloned()
2015        });
2016        let (Some(module), Some(decl)) = (module, decl) else {
2017            return Err(SessionError::new(format!("no declaration named {head}")));
2018        };
2019        let text = self
2020            .state
2021            .snapshot
2022            .get(&module.path)
2023            .cloned()
2024            .unwrap_or_default();
2025        let lines: Vec<&str> = text.split('\n').collect();
2026        let loc = decl.loc.unwrap();
2027        let mut from = loc.sl;
2028        let mut doc_lines: Vec<String> = vec![];
2029        let is_doc = |l: &str| l.trim_start().starts_with("///");
2030        while from > 0 && is_doc(lines[from - 1]) {
2031            from -= 1;
2032            doc_lines.insert(0, lines[from].to_string());
2033        }
2034        let body: Vec<&str> = lines[loc.sl..=loc.el.min(lines.len() - 1)].to_vec();
2035        if let Some(member) = member {
2036            let re = Regex::new(&format!(r"^\s*{}\$?\??\s*[:=]", regex::escape(member))).unwrap();
2037            let mut picked: Vec<String> = vec![];
2038            for (i, l) in body.iter().enumerate() {
2039                if re.is_match(l) {
2040                    let mut j = i;
2041                    let mut ds: Vec<String> = vec![];
2042                    while j > 0 && is_doc(body[j - 1]) {
2043                        j -= 1;
2044                        ds.insert(0, body[j].trim().to_string());
2045                    }
2046                    picked.extend(ds);
2047                    picked.push(l.trim().to_string());
2048                }
2049            }
2050            if picked.is_empty() {
2051                return Err(SessionError::new(format!("{head} has no member {member}")));
2052            }
2053            return Ok(picked);
2054        }
2055        doc_lines.extend(body.iter().map(|s| s.to_string()));
2056        Ok(doc_lines)
2057    }
2058
2059    /// the derivation of a valid place, or the root cause of an invalid one (`:trace`)
2060    pub fn trace(&self, path_text: &str) -> SResult<Vec<String>> {
2061        let segs: SegPath = parse_path(path_text, "")
2062            .map_err(|_| SessionError::new(format!("bad path {path_text}")))?;
2063        let root = seg_text(&segs[0]);
2064        if !self.has_root(&root) {
2065            return Err(SessionError::new(format!("no root named {root}")));
2066        }
2067        let r = self.run(Mode::Full);
2068        let (Some(eng), Some(entry)) = (r.eng.clone(), r.entry.clone()) else {
2069            return Err(SessionError::new(self.load_failure(&r)));
2070        };
2071        let mut lines: Vec<String> = vec![];
2072        let mut seen: HashSet<String> = HashSet::new();
2073        let has_doc = self.state.document(&root).is_some();
2074        self.walk(&mut lines, &mut seen, &r, &eng, &entry, &segs, 0, has_doc);
2075        Ok(lines)
2076    }
2077    #[allow(clippy::too_many_arguments)]
2078    fn walk(
2079        &self,
2080        lines: &mut Vec<String>,
2081        seen: &mut HashSet<String>,
2082        r: &Run,
2083        eng: &Rc<Engine>,
2084        entry: &Rc<Module>,
2085        segs: &[Seg],
2086        depth: usize,
2087        has_doc: bool,
2088    ) {
2089        let short = |v: &Value| {
2090            let t = self.value_text(eng, v);
2091            if t.chars().count() > 60 {
2092                format!("{}...", t.chars().take(57).collect::<String>())
2093            } else {
2094                t
2095            }
2096        };
2097        let path = path_str(segs, None);
2098        let ind = "  ".repeat(depth);
2099        if seen.contains(&path) {
2100            lines.push(format!("{ind}{path}  (above)"));
2101            return;
2102        }
2103        seen.insert(path.clone());
2104        let own: Vec<&Diag> = r.diags.iter().filter(|d| d.path == path).collect();
2105        let parent = if segs.len() > 1 {
2106            self.value_at(eng, entry, &segs[..segs.len() - 1])
2107        } else {
2108            None
2109        };
2110        let last = segs.last().unwrap();
2111        let slot_info = match (&parent, last) {
2112            (Some(Value::Rec(inst)), Seg::Name(n)) => {
2113                let b = inst.borrow();
2114                b.slot(n).map(|s| {
2115                    (
2116                        s.kind,
2117                        s.state,
2118                        s.value.clone(),
2119                        b.entry_order.iter().any(|x| x.as_str() == &**n),
2120                        rec_members(&b.rt)
2121                            .iter()
2122                            .find(|m| m.name.as_str() == &**n)
2123                            .cloned(),
2124                    )
2125                })
2126            }
2127            _ => None,
2128        };
2129        if let Some((kind, state, value, in_entry, m)) = slot_info {
2130            let inst = match &parent {
2131                Some(Value::Rec(i)) => i.clone(),
2132                _ => unreachable!(),
2133            };
2134            let kind_word = match kind {
2135                MKind::Der => "derived",
2136                MKind::Dflt => "defaulted",
2137                MKind::Opt => "optional",
2138                MKind::Req => "required",
2139            };
2140            let supplied =
2141                matches!(kind, MKind::Req | MKind::Opt) || (kind == MKind::Dflt && in_entry);
2142            let m_expr = m.as_ref().and_then(|m| m.expr.clone());
2143            if state == SlotState::Invalid {
2144                lines.push(format!("{ind}{path}  (invalid)"));
2145                for d in &own {
2146                    lines.push(format!("{ind}  {}", fmt_diag(d, None)));
2147                }
2148                if own.is_empty() {
2149                    if let Some(e) = &m_expr {
2150                        for rd in reads_of(e) {
2151                            if let Some(s) = self.read_segs(eng, &inst, &rd, entry) {
2152                                self.walk(lines, seen, r, eng, entry, &s, depth + 1, has_doc);
2153                            }
2154                        }
2155                    }
2156                }
2157                return;
2158            }
2159            if state == SlotState::Absent {
2160                lines.push(format!("{ind}{path}  absent"));
2161                return;
2162            }
2163            let how = if supplied {
2164                "supplied".to_string()
2165            } else {
2166                kind_word.to_string()
2167            };
2168            let ex = match (&m_expr, supplied) {
2169                (Some(e), false) => format!(": {}", expr_text(e)),
2170                _ => String::new(),
2171            };
2172            lines.push(format!("{ind}{path} = {}  ({how}{ex})", short(&value)));
2173            if !supplied && depth < 6 {
2174                if let Some(e) = &m_expr {
2175                    for rd in reads_of(e) {
2176                        match self.read_segs(eng, &inst, &rd, entry) {
2177                            Some(s) => {
2178                                self.walk(lines, seen, r, eng, entry, &s, depth + 1, has_doc)
2179                            }
2180                            None => lines.push(format!("{ind}  {}  (not a place)", expr_text(&rd))),
2181                        }
2182                    }
2183                }
2184            }
2185            return;
2186        }
2187        match self.value_at(eng, entry, segs) {
2188            None => {
2189                if r.diags
2190                    .iter()
2191                    .any(|d| d.severity == "error" && is_root_diag(d, &path))
2192                {
2193                    lines.push(format!("{ind}{path}  (invalid)"));
2194                    for d in r.diags.iter().filter(|d| is_root_diag(d, &path)) {
2195                        lines.push(format!("{ind}  {}", fmt_diag(d, None)));
2196                    }
2197                } else {
2198                    lines.push(format!("{ind}{path}  nothing there"));
2199                }
2200            }
2201            Some(v) => {
2202                let how = if segs.len() == 1 {
2203                    if has_doc {
2204                        "document"
2205                    } else {
2206                        "root literal"
2207                    }
2208                } else {
2209                    "supplied"
2210                };
2211                lines.push(format!("{ind}{path} = {}  ({how})", short(&v)));
2212                for d in &own {
2213                    lines.push(format!("{ind}  {}", fmt_diag(d, None)));
2214                }
2215            }
2216        }
2217    }
2218    fn value_at(&self, eng: &Engine, entry: &Module, segs: &[Seg]) -> Option<Value> {
2219        let mut v = entry.env.root(&seg_text(&segs[0]))?;
2220        for s in &segs[1..] {
2221            v = eng.deref(v).ok()?;
2222            v = match (&v, s) {
2223                (Value::Rec(inst), Seg::Name(n)) => {
2224                    let st = eng.force_state(inst, n);
2225                    if st == SlotState::Ok {
2226                        inst.borrow().slot(n).map(|s| s.value.clone())?
2227                    } else {
2228                        return None;
2229                    }
2230                }
2231                (Value::Rec(_), _) => return None,
2232                (Value::Arr(a), Seg::Idx(i)) => a.borrow().items.get(*i).cloned()?,
2233                (Value::Arr(_), _) => return None,
2234                (Value::Map(m), _) => m.borrow().get(&seg_text(s)).cloned()?,
2235                _ => return None,
2236            };
2237            if v.is_undef() || v.is_absent() {
2238                return None;
2239            }
2240        }
2241        Some(v)
2242    }
2243    fn read_segs(
2244        &self,
2245        eng: &Engine,
2246        inst: &Rc<RefCell<crate::semantics::RecInst>>,
2247        rd: &Rc<Expr>,
2248        entry: &Module,
2249    ) -> Option<SegPath> {
2250        // a bare name read inside a record is a sibling member (§4.4's scope
2251        // chain), else a root; a chain is navigated to the place it names
2252        if let Expr::Name(n) = &**rd {
2253            let mut cur = Some(inst.clone());
2254            while let Some(c) = cur {
2255                if c.borrow().has_slot(n) {
2256                    let mut p = c.borrow().path.to_vec();
2257                    p.push(Seg::Name(Rc::from(n.clone())));
2258                    return Some(p);
2259                }
2260                cur = c.borrow().parent.clone();
2261            }
2262            return if entry.env.root(n).is_some() {
2263                Some(vec![Seg::Name(Rc::from(n.clone()))])
2264            } else {
2265                None
2266            };
2267        }
2268        let root_name = inst.borrow().path.first().map(seg_text).unwrap_or_default();
2269        let sc = Scope {
2270            inst: Some(inst.clone()),
2271            locals: Locals::new(),
2272            root_name: root_name.into(),
2273            menv: Some(entry.env.clone()),
2274        };
2275        eng.eval_place(rd, &sc).ok().flatten()
2276    }
2277
2278    /// the candidates completion offers at the end of `text` (`:complete`)
2279    pub fn complete(&self, text: &str, commands: &[&str]) -> Vec<String> {
2280        let uniq = |xs: Vec<String>| -> Vec<String> {
2281            let mut v: Vec<String> = xs.into_iter().collect::<HashSet<_>>().into_iter().collect();
2282            v.sort();
2283            v
2284        };
2285        if text.starts_with(':') {
2286            let Some(sp) = text.find(' ') else {
2287                return uniq(
2288                    commands
2289                        .iter()
2290                        .filter(|c| c.starts_with(text))
2291                        .map(|c| c.to_string())
2292                        .collect(),
2293                );
2294            };
2295            let cmd = &text[..sp];
2296            let rest = &text[sp + 1..];
2297            let last = Regex::new(r"[\s,=]+")
2298                .unwrap()
2299                .split(rest)
2300                .last()
2301                .unwrap_or("")
2302                .to_string();
2303            let by =
2304                |xs: Vec<String>| uniq(xs.into_iter().filter(|x| x.starts_with(&last)).collect());
2305            return match cmd {
2306                ":evaluate" | ":validate" | ":unbind" | ":diff" | ":save" | ":bind" => {
2307                    by(self.all_root_names())
2308                }
2309                ":drop" => by(self
2310                    .state
2311                    .decls
2312                    .iter()
2313                    .map(|(n, _)| n.clone())
2314                    .chain(self.state.outputs.iter().map(|(n, _, _)| n.clone()))
2315                    .collect()),
2316                ":set" => by(vec!["pretty".into(), "compact".into()]),
2317                ":help" => by(commands.iter().map(|c| c.to_string()).collect()),
2318                ":trace" | ":path" | ":create" | ":update" | ":remove" => self.complete_path(&last),
2319                _ => vec![],
2320            };
2321        }
2322        let member_re = Regex::new(
2323            r"([A-Za-z_$][A-Za-z0-9_$]*(?:\.[A-Za-z_][A-Za-z0-9_$]*|\[[^\]]*\])*)\.([A-Za-z_]*)$",
2324        )
2325        .unwrap();
2326        if let Some(m) = member_re.captures(text) {
2327            let base = m.get(1).unwrap().as_str();
2328            let prefix = m.get(2).unwrap().as_str();
2329            if base == "std" || base.starts_with("std.") {
2330                let ns = if base == "std" {
2331                    String::new()
2332                } else {
2333                    format!("{}.", &base[4..])
2334                };
2335                return uniq(
2336                    std_names()
2337                        .filter(|k| k.starts_with(&ns))
2338                        .map(|k| k[ns.len()..].split('.').next().unwrap_or("").to_string())
2339                        .filter(|k| k.starts_with(prefix))
2340                        .collect(),
2341                );
2342            }
2343            let (_, entry, _) = self.build(&self.state);
2344            let Some(entry) = entry else { return vec![] };
2345            let Ok(expr) = parse_expr(base) else {
2346                return vec![];
2347            };
2348            let cx = self.session_ctx(&self.state, &entry.env, Rc::new(|_, _| {}), None);
2349            let rt = infer(&cx, &expr).rt;
2350            fn members(t: Option<&RT>) -> Option<Vec<crate::semantics::Member>> {
2351                let t = t?;
2352                match &t.k {
2353                    RTk::Rec(_) => Some(rec_members(t).to_vec()),
2354                    RTk::Union(arms) => {
2355                        let sets: Vec<Option<Vec<crate::semantics::Member>>> =
2356                            arms.borrow().iter().map(|a| members(Some(a))).collect();
2357                        if sets.iter().any(|s| s.is_none()) {
2358                            return None;
2359                        }
2360                        let sets: Vec<Vec<crate::semantics::Member>> =
2361                            sets.into_iter().map(|s| s.unwrap()).collect();
2362                        let first = sets.first().cloned().unwrap_or_default();
2363                        Some(
2364                            first
2365                                .into_iter()
2366                                .filter(|m| sets.iter().all(|s| s.iter().any(|x| x.name == m.name)))
2367                                .collect(),
2368                        )
2369                    }
2370                    RTk::Pred { base, .. } => members(Some(base)),
2371                    _ => None,
2372                }
2373            }
2374            let ms = members(rt.as_ref()).unwrap_or_default();
2375            return uniq(
2376                ms.iter()
2377                    .filter(|x| x.name.starts_with(prefix))
2378                    .map(|x| {
2379                        let kind = match x.kind {
2380                            MKind::Der => "derived",
2381                            MKind::Dflt => "defaulted",
2382                            MKind::Opt => "optional",
2383                            MKind::Req => "required",
2384                        };
2385                        format!(
2386                            "{}{}  {}{}",
2387                            x.name,
2388                            if x.hidden { "$" } else { "" },
2389                            kind,
2390                            x.ty.as_ref()
2391                                .map(|t| format!(": {}", type_text(Some(t))))
2392                                .unwrap_or_default()
2393                        )
2394                    })
2395                    .collect(),
2396            );
2397        }
2398        let word_re = Regex::new(r"([A-Za-z_$][A-Za-z0-9_$]*)$").unwrap();
2399        let prefix = word_re
2400            .captures(text)
2401            .map(|m| m.get(1).unwrap().as_str().to_string())
2402            .unwrap_or_default();
2403        if prefix.starts_with('$') {
2404            return uniq(
2405                ["$this", "$parent", "$root", "$key", "$path", "$referrers"]
2406                    .iter()
2407                    .filter(|x| x.starts_with(&prefix))
2408                    .map(|x| x.to_string())
2409                    .collect(),
2410            );
2411        }
2412        let mut names: Vec<String> = vec!["std".into()];
2413        let (_, entry, _) = self.build(&self.state);
2414        if let Some(entry) = entry {
2415            let e = &entry.env;
2416            names.extend(e.type_asts.borrow().keys().cloned());
2417            names.extend(e.consts.borrow().keys().cloned());
2418            names.extend(e.funcs.borrow().keys().cloned());
2419            names.extend(e.inputs.borrow().keys().cloned());
2420            names.extend(e.outputs.borrow().iter().map(|(o, _, _)| o.clone()));
2421            names.extend(e.imports.borrow().keys().cloned());
2422            names.extend(e.namespaces.borrow().keys().cloned());
2423            names.extend(e.diags.borrow().keys().cloned());
2424        }
2425        names.extend(self.state.outputs.iter().map(|(n, _, _)| n.clone()));
2426        let kw = [
2427            "if", "then", "else", "for", "in", "match", "with", "matches", "true", "false", "null",
2428        ];
2429        names.extend(kw.iter().map(|k| k.to_string()));
2430        uniq(
2431            names
2432                .into_iter()
2433                .filter(|n| n.starts_with(&prefix))
2434                .collect(),
2435        )
2436    }
2437    fn complete_path(&self, partial: &str) -> Vec<String> {
2438        if !partial.contains('.') && !partial.contains('[') {
2439            let mut v: Vec<String> = self
2440                .all_root_names()
2441                .into_iter()
2442                .filter(|n| n.starts_with(partial))
2443                .collect();
2444            v.sort();
2445            return v;
2446        }
2447        // the base is the shortest prefix whose remainder is `.ident?` or `[…` (the reference's lazy match)
2448        let tail_dot = Regex::new(r"^\.([A-Za-z_][A-Za-z0-9_]*)?$").unwrap();
2449        let tail_bracket = Regex::new(r#"^\["?[^\]]*$"#).unwrap();
2450        let mut base = partial.to_string();
2451        for (i, c) in partial.char_indices() {
2452            if c == '.' || c == '[' {
2453                let rest = &partial[i..];
2454                if tail_dot.is_match(rest) || tail_bracket.is_match(rest) {
2455                    base = partial[..i].to_string();
2456                    break;
2457                }
2458            }
2459        }
2460        let r = self.run(Mode::Full);
2461        let (Some(eng), Some(entry)) = (&r.eng, &r.entry) else {
2462            return vec![];
2463        };
2464        let Ok(segs) = parse_path(&base, "") else {
2465            return vec![];
2466        };
2467        let Some(v) = self.value_at(eng, entry, &segs) else {
2468            return vec![];
2469        };
2470        let Ok(v) = eng.deref(v) else { return vec![] };
2471        let mut out: Vec<String> = vec![];
2472        match &v {
2473            Value::Rec(inst) => {
2474                for (n, s) in &inst.borrow().slots {
2475                    if s.hidden {
2476                        continue;
2477                    }
2478                    out.push(format!("{base}.{n}"));
2479                }
2480            }
2481            Value::Map(m) => {
2482                for (k, _) in &m.borrow().entries {
2483                    out.push(format!("{base}[{}]", json_str(k)));
2484                }
2485            }
2486            Value::Arr(a) => {
2487                for i in 0..a.borrow().items.len() {
2488                    out.push(format!("{base}[{i}]"));
2489                }
2490            }
2491            _ => {}
2492        }
2493        let mut out: Vec<String> = out.into_iter().filter(|x| x.starts_with(partial)).collect();
2494        out.sort();
2495        out
2496    }
2497
2498    // ---- the scratch module (§4) ----
2499    /// The session's declarations as a module's text.
2500    pub fn scratch_text(&self) -> String {
2501        let mut parts: Vec<String> = self
2502            .state
2503            .decls
2504            .iter()
2505            .map(|(_, t)| t.trim().to_string())
2506            .collect();
2507        for (n, ty, expr) in &self.state.outputs {
2508            parts.push(format!(
2509                "output {n}: {} = {expr}",
2510                ty.clone().unwrap_or_else(|| self.inferred_type_text(expr))
2511            ));
2512        }
2513        if parts.is_empty() {
2514            String::new()
2515        } else {
2516            format!("{}\n", parts.join("\n"))
2517        }
2518    }
2519    fn inferred_type_text(&self, expr: &str) -> String {
2520        self.type_of(expr)
2521            .map(|(t, _, _)| t)
2522            .unwrap_or_else(|_| "any".into())
2523    }
2524    /// the scratch module as a file: imports of the entry's exports it uses, then the declarations
2525    pub fn module_text(&self) -> String {
2526        let body = self.scratch_text();
2527        let (_, entry, _) = self.build(&self.state);
2528        let used = identifiers(&body);
2529        let mut names: Vec<String> = entry
2530            .map(|e| {
2531                e.exports
2532                    .borrow()
2533                    .keys()
2534                    .filter(|n| used.contains(*n))
2535                    .cloned()
2536                    .collect()
2537            })
2538            .unwrap_or_default();
2539        names.sort();
2540        let header = match (&self.entry_path, names.is_empty()) {
2541            (Some(p), false) => format!(
2542                "import {{ {} }} from \"./{}\"\n\n",
2543                names.join(", "),
2544                p.file_name()
2545                    .map(|n| n.to_string_lossy().to_string())
2546                    .unwrap_or_default()
2547            ),
2548            _ => String::new(),
2549        };
2550        header + &body
2551    }
2552    /// The scratch module, formatted.
2553    pub fn fmt(&self) -> SResult<String> {
2554        let t = self.scratch_text();
2555        if t.is_empty() {
2556            return Ok(String::new());
2557        }
2558        format(&t).map_err(SessionError::new)
2559    }
2560    /// Write the scratch module to a file.
2561    pub fn write(&self, file: &str) -> SResult<()> {
2562        std::fs::write(file, self.module_text())
2563            .map_err(|_| SessionError::new(format!("cannot write {file}")))
2564    }
2565
2566    // ---- documents out (§3) ----
2567    /// A root's document as JSON: the bound document, or the root evaluated.
2568    pub fn document_text(&self, name: &str) -> SResult<String> {
2569        if let Some(d) = self.state.document(name) {
2570            return Ok(doc_json(&d.doc));
2571        }
2572        if !self.has_root(name) {
2573            return Err(SessionError::new(format!("no root named {name}")));
2574        }
2575        let (_, docs, _) = self.evaluate(&[name.to_string()])?;
2576        docs.into_iter()
2577            .next()
2578            .and_then(|(_, j)| j)
2579            .ok_or_else(|| SessionError::new(format!("{name} is invalid")))
2580    }
2581    /// Save a root's document to a file.
2582    pub fn save(&self, name: &str, file: &str) -> SResult<()> {
2583        let text = self.document_text(name)?;
2584        std::fs::write(file, format!("{text}\n"))
2585            .map_err(|_| SessionError::new(format!("cannot write {file}")))
2586    }
2587    /// The lines of a document's diff against what it started from.
2588    pub fn diff(&self, name: &str) -> SResult<Vec<String>> {
2589        let Some(d) = self.state.document(name) else {
2590            return Err(SessionError::new(if self.has_root(name) {
2591                format!("{name} holds no document")
2592            } else {
2593                format!("no root named {name}")
2594            }));
2595        };
2596        let (before, after) = (doc_json(&d.base), doc_json(&d.doc));
2597        if before == after {
2598            return Ok(vec!["(no changes)".to_string()]);
2599        }
2600        let a: Vec<String> = pretty_json(&before)
2601            .split('\n')
2602            .map(|s| s.to_string())
2603            .collect();
2604        let b: Vec<String> = pretty_json(&after)
2605            .split('\n')
2606            .map(|s| s.to_string())
2607            .collect();
2608        Ok(line_diff(&a, &b))
2609    }
2610
2611    // ---- introspection ----
2612    /// The session's declarations and bindings, as `:session` prints them.
2613    pub fn session_lines(&self) -> Vec<String> {
2614        let mut out = vec![];
2615        for (n, t) in &self.state.decls {
2616            out.push(format!(
2617                "declaration  {:<16} {}",
2618                n,
2619                t.trim().lines().next().unwrap_or("")
2620            ));
2621        }
2622        for (n, ty, expr) in &self.state.outputs {
2623            out.push(format!(
2624                "output       {:<16} {n}{} = {expr}",
2625                n,
2626                ty.as_ref().map(|t| format!(": {t}")).unwrap_or_default()
2627            ));
2628        }
2629        for (n, d) in &self.state.documents {
2630            out.push(format!(
2631                "document     {:<16} {}{}{}",
2632                n,
2633                d.origin.word(),
2634                d.file.as_ref().map(|f| format!(" {f}")).unwrap_or_default(),
2635                if d.edited { " (edited)" } else { "" }
2636            ));
2637        }
2638        out
2639    }
2640    /// The log with its cursor, as `:history` prints it.
2641    pub fn history_lines(&self) -> Vec<String> {
2642        let mut out = vec![format!(
2643            "{} 0  (start)",
2644            if self.cursor == 0 { "*" } else { " " }
2645        )];
2646        for (i, op) in self.log.iter().enumerate() {
2647            out.push(format!(
2648                "{} {}  {}",
2649                if self.cursor == i + 1 { "*" } else { " " },
2650                i + 1,
2651                op_text(op)
2652            ));
2653        }
2654        out
2655    }
2656    /// The log as a session script, replayable with `--script`.
2657    pub fn script_lines(&self) -> Vec<String> {
2658        self.log[..self.cursor].iter().map(op_text).collect()
2659    }
2660}
2661
2662// ---------------- helpers ----------------
2663/// A diagnostic as the REPL prints it, with the file when it is another module's.
2664pub fn fmt_diag(d: &Diag, in_file: Option<&str>) -> String {
2665    format!(
2666        "{}{}{}{}: {}{}",
2667        d.severity,
2668        d.code
2669            .as_ref()
2670            .map(|c| format!(" [{c}]"))
2671            .unwrap_or_default(),
2672        d.id.as_ref().map(|i| format!(" {i}")).unwrap_or_default(),
2673        if d.path.is_empty() {
2674            String::new()
2675        } else {
2676            format!(" at {}", d.path)
2677        },
2678        d.message,
2679        in_file.map(|f| format!(" (in {f})")).unwrap_or_default()
2680    )
2681}
2682
2683/// An operation as the session's input spells it.
2684pub fn op_text(op: &Op) -> String {
2685    match op {
2686        Op::Bind { name, src } => match src {
2687            BindSource::File { file, .. } => format!(":bind {name}={file}"),
2688            BindSource::Inline { text } => format!(
2689                ":bind {name} {}",
2690                read_json(text).map(|v| doc_json(&v)).unwrap_or_default()
2691            ),
2692            BindSource::Expr { text } => format!(":bind {name} = {}", text.trim()),
2693        },
2694        Op::Unbind { name } => format!(":unbind {name}"),
2695        Op::Edit { kind, path, expr } => format!(
2696            ":{} {path}{}",
2697            kind.word(),
2698            expr.as_ref()
2699                .map(|e| format!(" = {}", e.trim()))
2700                .unwrap_or_default()
2701        ),
2702        Op::Declare { text, .. } => text.trim().to_string(),
2703        Op::Output { name, ty, expr } => format!(
2704            "{name}{} = {}",
2705            ty.as_ref().map(|t| format!(": {t}")).unwrap_or_default(),
2706            expr.trim()
2707        ),
2708        Op::Drop { name } => format!(":drop {name}"),
2709        Op::Reload { .. } => ":reload".into(),
2710        Op::Reset => ":reset".into(),
2711    }
2712}
2713
2714// a functional edit of a document at a path (read_json's shape)
2715fn edit_value(
2716    node: &Value,
2717    segs: &[Seg],
2718    i: usize,
2719    kind: EditKind,
2720    value: Option<&Value>,
2721    path: &str,
2722) -> SResult<Value> {
2723    if i < segs.len() - 1 {
2724        let s = &segs[i];
2725        let Some(child) = doc_step(node, s) else {
2726            return Err(SessionError::new(format!(
2727                "nothing at {}",
2728                path_str(&segs[..=i], None)
2729            )));
2730        };
2731        let new_child = edit_value(&child, segs, i + 1, kind, value, path)?;
2732        return Ok(replace_child(node, s, new_child));
2733    }
2734    let last = &segs[segs.len() - 1];
2735    let k = seg_text(last);
2736    match (node, last) {
2737        (Value::JObj(es), _) => {
2738            let idx = es.iter().position(|(kk, _)| *kk == k);
2739            let mut es: Vec<(String, Value)> = (**es).clone();
2740            match kind {
2741                EditKind::Create => {
2742                    if idx.is_some() {
2743                        return Err(SessionError::new(format!("{path} already holds a value")));
2744                    }
2745                    es.push((k, value.cloned().unwrap_or(Value::Null)));
2746                }
2747                EditKind::Update => match idx {
2748                    Some(i) => es[i].1 = value.cloned().unwrap_or(Value::Null),
2749                    None => return Err(SessionError::new(format!("nothing at {path}"))),
2750                },
2751                EditKind::Remove => match idx {
2752                    Some(i) => {
2753                        es.remove(i);
2754                    }
2755                    None => return Err(SessionError::new(format!("nothing at {path}"))),
2756                },
2757            }
2758            Ok(Value::JObj(Rc::new(es)))
2759        }
2760        (Value::JArr(items), Seg::Idx(k)) => {
2761            let mut items: Vec<Value> = (**items).clone();
2762            match kind {
2763                EditKind::Create => {
2764                    if *k < items.len() {
2765                        return Err(SessionError::new(format!("{path} already holds a value")));
2766                    }
2767                    if *k > items.len() {
2768                        return Err(SessionError::new(format!(
2769                            "{path} is past the end of the array"
2770                        )));
2771                    }
2772                    items.push(value.cloned().unwrap_or(Value::Null));
2773                }
2774                EditKind::Update => {
2775                    if *k >= items.len() {
2776                        return Err(SessionError::new(format!("nothing at {path}")));
2777                    }
2778                    items[*k] = value.cloned().unwrap_or(Value::Null);
2779                }
2780                EditKind::Remove => {
2781                    if *k >= items.len() {
2782                        return Err(SessionError::new(format!("nothing at {path}")));
2783                    }
2784                    items.remove(*k);
2785                }
2786            }
2787            Ok(Value::JArr(Rc::new(items)))
2788        }
2789        _ => Err(SessionError::new(format!(
2790            "{} is not a record, map, or array",
2791            path_str(&segs[..segs.len() - 1], None)
2792        ))),
2793    }
2794}
2795fn replace_child(node: &Value, s: &Seg, child: Value) -> Value {
2796    match (node, s) {
2797        (Value::JObj(es), _) => {
2798            let k = seg_text(s);
2799            let es: Vec<(String, Value)> = es
2800                .iter()
2801                .map(|(kk, v)| {
2802                    if *kk == k {
2803                        (kk.clone(), child.clone())
2804                    } else {
2805                        (kk.clone(), v.clone())
2806                    }
2807                })
2808                .collect();
2809            Value::JObj(Rc::new(es))
2810        }
2811        (Value::JArr(items), Seg::Idx(i)) => {
2812            let items: Vec<Value> = items
2813                .iter()
2814                .enumerate()
2815                .map(|(j, v)| if j == *i { child.clone() } else { v.clone() })
2816                .collect();
2817            Value::JArr(Rc::new(items))
2818        }
2819        _ => node.clone(),
2820    }
2821}
2822
2823// a detached output (§3): its declaration becomes `input name: T` in the
2824// session's copy of the module — the name stays declared, the checker
2825// sees a root of the same type, and the session binds the projected
2826// document to it; line numbers are kept
2827fn detach_outputs(text: &str, names: &[String]) -> String {
2828    if names.is_empty() {
2829        return text.to_string();
2830    }
2831    let decls = parse_source(text).decls;
2832    let mut lines: Vec<String> = text.split('\n').map(|s| s.to_string()).collect();
2833    for d in &decls {
2834        let (DeclBody::Output { name, .. }, Some(loc)) = (&d.body, d.loc) else {
2835            continue;
2836        };
2837        if !names.contains(name) {
2838            continue;
2839        }
2840        let src = lines[loc.sl..=loc.el.min(lines.len() - 1)].join("\n");
2841        let name_at = src.find(name.as_str()).unwrap_or(0);
2842        let colon = src[name_at..]
2843            .find(':')
2844            .map(|i| i + name_at)
2845            .unwrap_or(src.len());
2846        // the type text: from the colon to the `=` at bracket depth 0
2847        let bytes = src.as_bytes();
2848        let mut depth = 0i32;
2849        let mut eq: Option<usize> = None;
2850        let mut i = colon + 1;
2851        while i < bytes.len() {
2852            let c = bytes[i] as char;
2853            if "{[(<".contains(c) {
2854                depth += 1;
2855            } else if "}])>".contains(c) {
2856                depth -= 1;
2857            } else if c == '='
2858                && depth == 0
2859                && bytes.get(i + 1) != Some(&b'=')
2860                && i > 0
2861                && !matches!(bytes[i - 1], b'!' | b'<' | b'>')
2862            {
2863                eq = Some(i);
2864                break;
2865            }
2866            i += 1;
2867        }
2868        let type_text = match eq {
2869            Some(e) => src[colon + 1..e].trim().to_string(),
2870            None => src[(colon + 1).min(src.len())..].trim().to_string(),
2871        };
2872        let squeezed = SQUEEZE_WS.replace_all(&type_text, " ").to_string();
2873        lines[loc.sl] = format!("input {name}: {squeezed}");
2874        for l in lines.iter_mut().take(loc.el + 1).skip(loc.sl + 1) {
2875            l.clear();
2876        }
2877    }
2878    lines.join("\n")
2879}
2880
2881// the places an expression reads, as navigation chains (a static
2882// approximation of the engine's read set: names, members, indexes)
2883fn reads_of(e: &Rc<Expr>) -> Vec<Rc<Expr>> {
2884    fn is_chain(x: &Expr) -> bool {
2885        match x {
2886            Expr::Name(_) | Expr::Ctx(_) => true,
2887            Expr::Member { x, .. } | Expr::Index { x, .. } => is_chain(x),
2888            _ => false,
2889        }
2890    }
2891    fn go(x: &Rc<Expr>, out: &mut Vec<Rc<Expr>>) {
2892        match &**x {
2893            Expr::Member { .. } | Expr::Index { .. } if is_chain(x) => {
2894                out.push(x.clone());
2895                if let Expr::Index { i, .. } = &**x {
2896                    go(i, out);
2897                }
2898            }
2899            Expr::Name(_) => out.push(x.clone()),
2900            Expr::Lit(_)
2901            | Expr::UnitLit { .. }
2902            | Expr::Ctx(_)
2903            | Expr::Pattern(_)
2904            | Expr::Referrers { .. } => {}
2905            Expr::Template(parts) => {
2906                for p in parts {
2907                    if let TPart::Expr(e) = p {
2908                        go(e, out);
2909                    }
2910                }
2911            }
2912            Expr::Obj(es) => es.iter().for_each(|(_, v)| go(v, out)),
2913            Expr::Arr(items) => items.iter().for_each(|(_, v)| go(v, out)),
2914            Expr::Comp { head, clauses } => {
2915                go(head, out);
2916                for c in clauses {
2917                    go(&c.iter, out);
2918                    c.filters.iter().for_each(|f| go(f, out));
2919                }
2920            }
2921            Expr::MapComp { key, val, clauses } => {
2922                go(key, out);
2923                go(val, out);
2924                for c in clauses {
2925                    go(&c.iter, out);
2926                    c.filters.iter().for_each(|f| go(f, out));
2927                }
2928            }
2929            Expr::Bin { l, r, .. } => {
2930                go(l, out);
2931                go(r, out);
2932            }
2933            Expr::Un { x, .. } | Expr::Paren(x) | Expr::Spread(x) => go(x, out),
2934            Expr::If { c, t, f } => {
2935                go(c, out);
2936                go(t, out);
2937                go(f, out);
2938            }
2939            Expr::Lambda { body, .. } => go(body, out),
2940            Expr::Call { fun, args } => {
2941                go(fun, out);
2942                args.iter().for_each(|a| go(a, out));
2943            }
2944            Expr::Member { x, .. } => go(x, out),
2945            Expr::Index { x, i } => {
2946                go(x, out);
2947                go(i, out);
2948            }
2949            Expr::With { base, patch } => {
2950                go(base, out);
2951                go(patch, out);
2952            }
2953            Expr::Match { subject, arms } => {
2954                go(subject, out);
2955                arms.iter().for_each(|a| go(&a.body, out));
2956            }
2957        }
2958    }
2959    let mut out = vec![];
2960    go(e, &mut out);
2961    out.into_iter()
2962        .filter(|x| !matches!(&**x, Expr::Name(n) if n == "true" || n == "false" || n == "null"))
2963        .collect()
2964}
2965
2966/// an expression's text, for chains and simple forms (the trace view)
2967pub fn expr_text(e: &Expr) -> String {
2968    match e {
2969        Expr::Lit(v) => match v {
2970            Value::Str(s) => json_str(s),
2971            other => crate::infer::js_str(other),
2972        },
2973        Expr::UnitLit { num, unit } => format!("{}{unit}", crate::semantics::js_num_str(*num)),
2974        Expr::Name(n) | Expr::Ctx(n) => n.clone(),
2975        Expr::Member { x, name, safe } => {
2976            format!("{}{}{name}", expr_text(x), if *safe { "?." } else { "." })
2977        }
2978        Expr::Index { x, i } => format!("{}[{}]", expr_text(x), expr_text(i)),
2979        Expr::Paren(x) => format!("({})", expr_text(x)),
2980        Expr::Spread(x) => format!("...{}", expr_text(x)),
2981        Expr::Bin { op, l, r } => format!("{} {op} {}", expr_text(l), expr_text(r)),
2982        Expr::Un { op, x } => format!("{op}{}", expr_text(x)),
2983        Expr::Call { fun, args } => format!(
2984            "{}({})",
2985            expr_text(fun),
2986            args.iter()
2987                .map(|a| expr_text(a))
2988                .collect::<Vec<_>>()
2989                .join(", ")
2990        ),
2991        Expr::If { c, t, f } => format!(
2992            "if {} then {} else {}",
2993            expr_text(c),
2994            expr_text(t),
2995            expr_text(f)
2996        ),
2997        Expr::Referrers { ty, member } => format!("$referrers({ty}, {})", json_str(member)),
2998        Expr::Template(parts) => format!(
2999            "`{}`",
3000            parts
3001                .iter()
3002                .map(|p| match p {
3003                    TPart::Text(s) => s.clone(),
3004                    TPart::Expr(e) => format!("${{{}}}", expr_text(e)),
3005                })
3006                .collect::<String>()
3007        ),
3008        Expr::Obj(es) => format!(
3009            "{{ {} }}",
3010            es.iter()
3011                .map(|(k, v)| match &**v {
3012                    Expr::Spread(x) => format!("...{}", expr_text(x)),
3013                    _ => format!("{k}: {}", expr_text(v)),
3014                })
3015                .collect::<Vec<_>>()
3016                .join(", ")
3017        ),
3018        Expr::Arr(items) => format!(
3019            "[{}]",
3020            items
3021                .iter()
3022                .map(|(spread, v)| format!("{}{}", if *spread { "..." } else { "" }, expr_text(v)))
3023                .collect::<Vec<_>>()
3024                .join(", ")
3025        ),
3026        Expr::Comp { clauses, .. } => format!(
3027            "[for {} … ]",
3028            clauses
3029                .iter()
3030                .map(|c| format!("{} in {}", c.v, expr_text(&c.iter)))
3031                .collect::<Vec<_>>()
3032                .join(", ")
3033        ),
3034        Expr::Lambda { params, .. } => format!("({}) => …", params.join(", ")),
3035        Expr::With { base, .. } => format!("{} with …", expr_text(base)),
3036        Expr::Match { subject, .. } => format!("match {} {{ … }}", expr_text(subject)),
3037        _ => "…".into(),
3038    }
3039}
3040
3041// a minimal line diff (longest common subsequence)
3042fn line_diff(a: &[String], b: &[String]) -> Vec<String> {
3043    let (n, m) = (a.len(), b.len());
3044    let mut dp = vec![vec![0usize; m + 1]; n + 1];
3045    for i in (0..n).rev() {
3046        for j in (0..m).rev() {
3047            dp[i][j] = if a[i] == b[j] {
3048                dp[i + 1][j + 1] + 1
3049            } else {
3050                dp[i + 1][j].max(dp[i][j + 1])
3051            };
3052        }
3053    }
3054    let mut out = vec![];
3055    let (mut i, mut j) = (0, 0);
3056    while i < n && j < m {
3057        if a[i] == b[j] {
3058            out.push(format!("  {}", a[i]));
3059            i += 1;
3060            j += 1;
3061        } else if dp[i + 1][j] >= dp[i][j + 1] {
3062            out.push(format!("- {}", a[i]));
3063            i += 1;
3064        } else {
3065            out.push(format!("+ {}", b[j]));
3066            j += 1;
3067        }
3068    }
3069    while i < n {
3070        out.push(format!("- {}", a[i]));
3071        i += 1;
3072    }
3073    while j < m {
3074        out.push(format!("+ {}", b[j]));
3075        j += 1;
3076    }
3077    out
3078}
3079
3080// Rust-only representation, ownership and bounded-work checks.
3081#[cfg(test)]
3082#[path = "../tests/private/session_scratch_test.rs"]
3083mod tests;