Skip to main content

decl_lang/qengine/
edits.rs

1//! Replay Session root binding over retained records and member revisions.
2use crate::engine::{Engine, Inst, RootSrc};
3use crate::qengine::graph::{QueryId, ReadSet};
4use crate::qengine::revisions::{comparable, Matches, Revisions};
5use crate::semantics::*;
6use rustc_hash::{FxHashMap, FxHashSet};
7use std::borrow::Cow;
8use std::cell::{Cell, RefCell};
9use std::collections::HashMap;
10use std::rc::{Rc, Weak};
11
12/// A pair of process-wide clocks, sampled only at edit phase boundaries.
13#[cfg(feature = "runtime-diagnostics")]
14#[derive(Clone, Copy, Debug, Default, serde::Serialize)]
15pub struct EditStamp {
16    /// Monotonic wall-clock timestamp in nanoseconds, with an unspecified epoch.
17    pub wall_ns: u64,
18    /// Process CPU-clock timestamp in nanoseconds, including all process threads.
19    pub cpu_ns: u64,
20    /// False if either clock could not be read. Clocks are not sampled atomically.
21    pub valid: bool,
22}
23
24#[cfg(feature = "runtime-diagnostics")]
25impl EditStamp {
26    fn now() -> Self {
27        fn read(id: libc::clockid_t) -> Option<u64> {
28            let mut time = libc::timespec {
29                tv_sec: 0,
30                tv_nsec: 0,
31            };
32            // Diagnostic clock failure must not change evaluation behavior.
33            if unsafe { libc::clock_gettime(id, &mut time) } != 0 {
34                return None;
35            }
36            u64::try_from(time.tv_sec)
37                .ok()?
38                .checked_mul(1_000_000_000)?
39                .checked_add(u64::try_from(time.tv_nsec).ok()?)
40        }
41        match (
42            read(libc::CLOCK_MONOTONIC),
43            read(libc::CLOCK_PROCESS_CPUTIME_ID),
44        ) {
45            (Some(wall_ns), Some(cpu_ns)) => Self {
46                wall_ns,
47                cpu_ns,
48                valid: true,
49            },
50            _ => Self::default(),
51        }
52    }
53}
54
55/// Disjoint interval in one preparation or finish call, including its bookkeeping.
56#[cfg(feature = "runtime-diagnostics")]
57#[derive(Clone, Copy, Debug, serde::Serialize)]
58pub struct EditPhase {
59    /// Fixed phase identifier, in execution order within its containing array.
60    pub name: &'static str,
61    /// Opening clock sample; consecutive recorded phases share their boundary.
62    pub start: EditStamp,
63    /// Closing clock sample, including partial work when unwinding.
64    pub end: EditStamp,
65    /// Elapsed wall nanoseconds, including instrumentation; zero when invalid.
66    pub wall_ns: u64,
67    /// Elapsed process CPU nanoseconds, including instrumentation; zero when invalid.
68    pub cpu_ns: u64,
69    /// Whether this phase was entered and its closing boundary was recorded.
70    pub recorded: bool,
71    /// Whether this interval finished normally rather than during unwinding.
72    pub completed: bool,
73    /// Whether both boundary samples succeeded and neither clock decreased.
74    pub valid: bool,
75}
76
77#[cfg(feature = "runtime-diagnostics")]
78impl EditPhase {
79    fn empty(name: &'static str) -> Self {
80        Self {
81            name,
82            start: EditStamp::default(),
83            end: EditStamp::default(),
84            wall_ns: 0,
85            cpu_ns: 0,
86            recorded: false,
87            completed: false,
88            valid: false,
89        }
90    }
91}
92
93/// Counts collected from existing traversals; no query names or values are retained.
94/// All counts concern one preparation call. Table sizes describe observed state,
95/// while scans, writes, and enqueues count work, including repeated entries.
96/// Incomplete preparations may leave later counters at their initial zero values.
97#[cfg(feature = "runtime-diagnostics")]
98#[derive(Clone, Copy, Debug, Default, serde::Serialize)]
99pub struct EditPreparationWork {
100    /// Number of requested changed-root names, including any repeated names.
101    pub changed_roots: u64,
102    /// Whether the prior environment diagnostic list was nonempty, regardless of severity.
103    pub previous_errors: bool,
104    /// Entries in the initial registry snapshot, including duplicate record handles.
105    pub registry_records: u64,
106    /// Distinct canonical paths in the retained-record pool after the root census.
107    pub pooled_records: u64,
108    /// Distinct root names in the saved root-value table after the census.
109    pub saved_roots: u64,
110    /// Root query entries saved with their read sets, including empty read sets.
111    pub saved_root_reads: u64,
112    /// Changed-root visits with both a prior document and a next document to diff.
113    pub diff_roots: u64,
114    /// Changed-root visits using whole-value collection instead of document diffing.
115    pub collected_roots: u64,
116    /// Distinct known producer keys after processing all requested changed roots.
117    pub known_producers: u64,
118    /// Cumulative unique forced counts after diff, special reads, saved values,
119    /// retention checks, and the final error fallback. These reasons overlap.
120    /// Adjacent differences depend on this order and are not disjoint causal totals.
121    pub forced_after_seeding: [u64; 5],
122    /// Query entries scanned in the existing dependency graph, including empty read sets.
123    pub read_queries: u64,
124    /// Dependency entries traversed across all query read sets.
125    pub read_edges: u64,
126    /// Dependency occurrences, in edge/snapshot/round/value order (not queries).
127    pub special_edges: [u64; 4],
128    /// Distinct dependency keys in the temporary reverse index.
129    pub reverse_keys: u64,
130    /// Distinct reverse-index dependency keys with the whole-value `value:` prefix.
131    pub value_dependency_keys: u64,
132    /// Final reverse degrees: 1, 2, 3, 4, 5..8, 9..32, 33..128, 129+.
133    pub reverse_degree_buckets: [u64; 8],
134    /// Largest number of reader entries attached to any one dependency key.
135    pub reverse_max_degree: u64,
136    /// Sum of reverse-reader vector capacities, in entries rather than bytes.
137    pub reverse_vector_capacity: u64,
138    /// Slot visits across the registry snapshot, including repeated record entries.
139    pub registered_slots_scanned: u64,
140    /// Writes of Ok or Absent slot values, including overwrites of an existing key.
141    pub saved_slot_writes: u64,
142    /// Constant entries visited across all registered constant environments.
143    pub constants_scanned: u64,
144    /// Writes of evaluated constant values, including any existing-key overwrites.
145    pub saved_constant_writes: u64,
146    /// Distinct root, slot, and constant keys in the completed saved-value table.
147    pub saved_values: u64,
148    /// Saved-value hash-table capacity in entries, not bytes or allocated buckets.
149    pub saved_values_capacity: u64,
150    /// Top-level saved values checked for safe retention; recursive visits are excluded.
151    pub retention_checks: u64,
152    /// Top-level retention checks that failed, whether or not their keys were already forced.
153    pub retention_rejections: u64,
154    /// Forced keys placed in the queue before whole-value owner expansion.
155    pub initial_queue: u64,
156    /// Whole-value dependency owners examined, stopping at the first missing owner.
157    pub value_owners_examined: u64,
158    /// Examined whole-value owners found in the retained-record pool.
159    pub value_owners_found: u64,
160    /// Whether a missing whole-value owner triggered the conservative all-values fallback.
161    pub missing_owner_fallback: bool,
162    /// Saved-value keys enqueued by that fallback, without checking prior queue membership.
163    pub fallback_enqueues: u64,
164    /// Descendant keys enqueued from found whole-value owners, before closure traversal.
165    pub owner_descendant_enqueues: u64,
166    /// Descendant-collection calls for dequeued keys outside the known-producer set.
167    pub producer_collects: u64,
168    /// Producer descendant keys enqueued after filtering already-invalid keys.
169    pub producer_descendant_enqueues: u64,
170    /// First visits to known producer keys that skip descendant collection.
171    pub known_producers_skipped: u64,
172    /// Reverse-reader entries enqueued, including keys already queued or invalid.
173    pub reader_enqueues: u64,
174    /// Total queue removals, including repeated visits to the same key.
175    pub queue_pops: u64,
176    /// Queue removals whose key had already entered the invalid set.
177    pub duplicate_pops: u64,
178    /// Maximum queue length observed at its initial fill and each extension boundary.
179    pub queue_peak_len: u64,
180    /// Maximum queue capacity observed at the same boundaries, in key entries.
181    pub queue_peak_capacity: u64,
182    /// Distinct record, array, and map identities visited by closure collection.
183    pub walked_values: u64,
184    /// Distinct keys in the final invalid set, matching the prepared-query count.
185    pub invalid_queries: u64,
186    /// One call per Pending value, excluding recursive capture/memo visits.
187    pub pending_captures: u64,
188    /// Record, mutable collection, immutable collection, other root captures.
189    pub pending_capture_kinds: [u64; 4],
190    /// Capture-memo entries after Pending creation and before the memo is dropped.
191    pub capture_memo_entries: u64,
192    /// Computed slots assigned Unforced/Undef during reset, regardless of their prior state.
193    pub reset_slots: u64,
194    /// Invalid constants assigned unevaluated/Undef during reset.
195    pub reset_constants: u64,
196}
197
198/// Table cardinalities sampled at fixed finish boundaries, not traversal counts.
199/// An inactive finish runs only prune; fields for later phases remain zero.
200#[cfg(feature = "runtime-diagnostics")]
201#[derive(Clone, Copy, Debug, Default, serde::Serialize)]
202pub struct EditFinishWork {
203    /// Cached input descriptions before and after prune.
204    pub input_entries: [u64; 2],
205    /// Cached root descriptions before prune, after prune, and after graph prune.
206    pub root_entries: [u64; 3],
207    /// Registered query-slot entries before and after graph prune.
208    pub slot_entries: [u64; 2],
209    /// Query read-set entries before and after graph prune, including empty sets.
210    pub read_entries: [u64; 2],
211    /// Retained revision stamps before and after releasing Pending values and pruning stamps.
212    pub revision_entries: [u64; 2],
213}
214
215/// Sum of one finish phase across separate calls; this is not a continuous interval.
216#[cfg(feature = "runtime-diagnostics")]
217#[derive(Clone, Copy, Debug, serde::Serialize)]
218pub struct EditFinishPhaseTotal {
219    /// Fixed phase identifier, in the same order as the latest finish phases.
220    pub name: &'static str,
221    /// Recorded intervals included in this sum, including partial intervals.
222    pub recorded_calls: u64,
223    /// Sum of valid interval wall nanoseconds, excluding gaps between calls.
224    pub wall_ns: u64,
225    /// Sum of valid interval process CPU nanoseconds, excluding gaps between calls.
226    pub cpu_ns: u64,
227    /// Whether every included interval had valid clocks and its totals fit in u64.
228    pub valid: bool,
229}
230
231#[cfg(feature = "runtime-diagnostics")]
232impl EditFinishPhaseTotal {
233    fn empty(name: &'static str) -> Self {
234        Self {
235            name,
236            recorded_calls: 0,
237            wall_ns: 0,
238            cpu_ns: 0,
239            valid: true,
240        }
241    }
242}
243
244/// Bounded finish attribution since the latest begin, reset by the next begin.
245/// Phase sums exclude work between calls and must not be added to the latest
246/// finish again. Before the first begin, sequence-zero finishes share this tally.
247#[cfg(feature = "runtime-diagnostics")]
248#[derive(Clone, Copy, Debug, serde::Serialize)]
249pub struct EditFinishAggregate {
250    /// Calls that returned or unwound, including calls omitted because of reentry.
251    pub calls: u64,
252    /// Counted calls that passed the active check after prune.
253    pub active_calls: u64,
254    /// Counted calls that did not complete normally.
255    pub partial_calls: u64,
256    /// Outer calls omitted after same-preparation reentry superseded their trace.
257    /// Their intervals may overlap newer calls, so adding them would double-count.
258    pub superseded_calls: u64,
259    /// Complete unambiguous coverage: no partial/omitted call, clock failure, or overflow.
260    /// True with zero calls denotes an empty tally, not a measured finish.
261    pub valid: bool,
262    /// Noncontiguous per-phase sums; no endpoints or between-call duration are implied.
263    pub phases: [EditFinishPhaseTotal; 6],
264}
265
266#[cfg(feature = "runtime-diagnostics")]
267impl Default for EditFinishAggregate {
268    fn default() -> Self {
269        Self {
270            calls: 0,
271            active_calls: 0,
272            partial_calls: 0,
273            superseded_calls: 0,
274            valid: true,
275            phases: [
276                "prune",
277                "graph_prune",
278                "revisions_release",
279                "caches_release",
280                "query_sweep",
281                "scope_release",
282            ]
283            .map(EditFinishPhaseTotal::empty),
284        }
285    }
286}
287
288#[cfg(feature = "runtime-diagnostics")]
289impl EditFinishAggregate {
290    fn add(&mut self, report: &SessionEditDiagnostics, superseded: bool) {
291        fn add(total: &mut u64, value: u64) -> bool {
292            if let Some(next) = total.checked_add(value) {
293                *total = next;
294                true
295            } else {
296                *total = u64::MAX;
297                false
298            }
299        }
300        self.valid &= add(&mut self.calls, 1);
301        self.valid &= add(&mut self.active_calls, u64::from(report.finish_was_active));
302        self.valid &= add(&mut self.partial_calls, u64::from(!report.finish_completed));
303        self.valid &= add(&mut self.superseded_calls, u64::from(superseded));
304        self.valid &= report.finish_completed && !superseded;
305        if superseded {
306            return;
307        }
308        for (total, phase) in self.phases.iter_mut().zip(&report.finish) {
309            if phase.recorded {
310                total.valid &= add(&mut total.recorded_calls, 1);
311                total.valid &= add(&mut total.wall_ns, phase.wall_ns);
312                total.valid &= add(&mut total.cpu_ns, phase.cpu_ns);
313                total.valid &= phase.valid;
314                self.valid &= total.valid;
315            }
316        }
317    }
318}
319
320/// Latest edit attribution. Native builds without runtime-diagnostics contain
321/// none of these clocks, counters, or storage. Access is a fixed-size copy.
322/// A hot/equal run without begin preserves `sequence`; finish has its own count.
323#[cfg(feature = "runtime-diagnostics")]
324#[derive(Clone, Copy, Debug, serde::Serialize)]
325pub struct SessionEditDiagnostics {
326    /// Diagnostic serialization schema version; currently 1.
327    pub schema: u32,
328    /// Wrapping preparation-call count; zero before the first begin call.
329    pub sequence: u64,
330    /// Wrapping finish-call count, including inactive prune-only calls.
331    pub finish_sequence: u64,
332    /// Revision immediately after Pending creation; later reference rounds may advance it.
333    pub revision: usize,
334    /// Whether the latest preparation and its original scratch drops completed normally.
335    pub preparation_completed: bool,
336    /// Whether the latest finish completed normally; reset by the next preparation.
337    pub finish_completed: bool,
338    /// Whether the latest finish remained active after prune and entered graph cleanup.
339    pub finish_was_active: bool,
340    /// Ordered preparation intervals from root census through implicit scratch release.
341    /// Normal rebinding and member evaluation follow this call; native callbacks
342    /// triggered by drops remain inside the phase that triggered them.
343    pub preparation: [EditPhase; 9],
344    /// Ordered finish intervals from prune through implicit scope release.
345    /// An inactive finish records only the first interval.
346    pub finish: [EditPhase; 6],
347    /// State sizes and work counts from the latest preparation, retained across finish calls.
348    pub preparation_work: EditPreparationWork,
349    /// State sizes from the latest finish, reset on each begin or finish call.
350    pub finish_work: EditFinishWork,
351    /// All finish calls associated with this preparation, including later inactive calls.
352    pub finish_aggregate: EditFinishAggregate,
353}
354
355#[cfg(feature = "runtime-diagnostics")]
356impl Default for SessionEditDiagnostics {
357    fn default() -> Self {
358        Self {
359            schema: 1,
360            sequence: 0,
361            finish_sequence: 0,
362            revision: 0,
363            preparation_completed: false,
364            finish_completed: false,
365            finish_was_active: false,
366            preparation: [
367                "root_census",
368                "changed_seeds",
369                "reverse_index",
370                "saved_values",
371                "retention_seeds",
372                "invalidation_closure",
373                "pending_capture",
374                "reset",
375                "scratch_release",
376            ]
377            .map(EditPhase::empty),
378            finish: [
379                "prune",
380                "graph_prune",
381                "revisions_release",
382                "caches_release",
383                "query_sweep",
384                "scope_release",
385            ]
386            .map(EditPhase::empty),
387            preparation_work: EditPreparationWork::default(),
388            finish_work: EditFinishWork::default(),
389            finish_aggregate: EditFinishAggregate::default(),
390        }
391    }
392}
393
394/// Declared before the original locals, so the last interval includes their
395/// existing implicit drops. Holds no runtime owner and no diagnostic borrow
396/// across native callbacks. A nested edit supersedes this call's publication.
397#[cfg(feature = "runtime-diagnostics")]
398struct EditTrace<'a> {
399    edits: &'a Edits,
400    epoch: u64,
401    report: SessionEditDiagnostics,
402    preparing: bool,
403    next: usize,
404    stamp: EditStamp,
405    completed: bool,
406    close_on_drop: bool,
407}
408
409#[cfg(feature = "runtime-diagnostics")]
410impl<'a> EditTrace<'a> {
411    fn new(edits: &'a Edits, preparing: bool) -> Self {
412        let stamp = EditStamp::now();
413        let old = edits.diagnostics.get();
414        let report = if preparing {
415            SessionEditDiagnostics {
416                sequence: old.sequence.wrapping_add(1),
417                finish_sequence: old.finish_sequence,
418                ..SessionEditDiagnostics::default()
419            }
420        } else {
421            SessionEditDiagnostics {
422                finish_sequence: old.finish_sequence.wrapping_add(1),
423                finish: SessionEditDiagnostics::default().finish,
424                finish_work: EditFinishWork::default(),
425                finish_completed: false,
426                finish_was_active: false,
427                ..old
428            }
429        };
430        let epoch = edits.diagnostic_epoch.get().wrapping_add(1);
431        edits.diagnostic_epoch.set(epoch);
432        edits.diagnostics.set(report);
433        Self {
434            edits,
435            epoch,
436            report,
437            preparing,
438            next: 0,
439            stamp,
440            completed: false,
441            close_on_drop: true,
442        }
443    }
444
445    fn mark(&mut self, completed: bool) {
446        let end = EditStamp::now();
447        let phase = if self.preparing {
448            &mut self.report.preparation[self.next]
449        } else {
450            &mut self.report.finish[self.next]
451        };
452        phase.start = self.stamp;
453        phase.end = end;
454        phase.recorded = true;
455        phase.completed = completed;
456        phase.valid = self.stamp.valid
457            && end.valid
458            && end.wall_ns >= self.stamp.wall_ns
459            && end.cpu_ns >= self.stamp.cpu_ns;
460        if phase.valid {
461            phase.wall_ns = end.wall_ns - self.stamp.wall_ns;
462            phase.cpu_ns = end.cpu_ns - self.stamp.cpu_ns;
463        }
464        self.stamp = end;
465        self.next += 1;
466    }
467
468    fn queue(&mut self, queue: &Vec<Cow<'_, str>>) {
469        let work = &mut self.report.preparation_work;
470        work.queue_peak_len = work.queue_peak_len.max(queue.len() as u64);
471        work.queue_peak_capacity = work.queue_peak_capacity.max(queue.capacity() as u64);
472    }
473
474    fn degree(n: usize) -> usize {
475        match n {
476            1 => 0,
477            2 => 1,
478            3 => 2,
479            4 => 3,
480            5..=8 => 4,
481            9..=32 => 5,
482            33..=128 => 6,
483            _ => 7,
484        }
485    }
486}
487
488#[cfg(feature = "runtime-diagnostics")]
489impl Drop for EditTrace<'_> {
490    fn drop(&mut self) {
491        let completed = self.completed && !std::thread::panicking();
492        if self.close_on_drop {
493            self.mark(completed);
494        }
495        if self.preparing {
496            self.report.preparation_completed = completed;
497            if self.edits.diagnostic_epoch.get() == self.epoch {
498                self.edits.diagnostics.set(self.report);
499            }
500        } else {
501            self.report.finish_completed = completed;
502            let mut current = self.edits.diagnostics.get();
503            // A newly prepared edit owns a separate aggregate. Old callback
504            // scopes must not add their times to the new preparation.
505            if current.sequence != self.report.sequence {
506                return;
507            }
508            let superseded = self.edits.diagnostic_epoch.get() != self.epoch;
509            current.finish_aggregate.add(&self.report, superseded);
510            if !superseded {
511                self.report.finish_aggregate = current.finish_aggregate;
512                self.edits.diagnostics.set(self.report);
513            } else {
514                // Preserve the newer latest-call report. The aggregate records
515                // omitted coverage explicitly rather than summing nested time.
516                self.edits.diagnostics.set(current);
517            }
518        }
519    }
520}
521
522fn same_rc<T>(a: &Option<Rc<T>>, b: &Option<Rc<T>>) -> bool {
523    match (a, b) {
524        (Some(a), Some(b)) => Rc::ptr_eq(a, b),
525        (None, None) => true,
526        _ => false,
527    }
528}
529
530fn root_exists(eng: &Engine, name: &str) -> bool {
531    eng.env
532        .roots
533        .borrow()
534        .borrow()
535        .iter()
536        .any(|(n, _)| n == name)
537}
538
539/// Raw Session descriptions use the first occurrence of a repeated key. Keep
540/// narrow or infrequently searched descriptions as a slice; amortize a borrowed
541/// index only over wider repeated searches. The index owns no input payloads.
542struct FirstInputs<'a> {
543    entries: &'a [(String, Value)],
544    index: Option<FxHashMap<&'a str, &'a Value>>,
545}
546
547impl<'a> FirstInputs<'a> {
548    fn new(entries: &'a [(String, Value)], lookups: usize) -> Self {
549        let index =
550            if entries.len() > 8 && lookups > 1 && entries.len().saturating_mul(lookups) > 64 {
551                let mut index = FxHashMap::default();
552                for (key, value) in entries {
553                    index.entry(key.as_str()).or_insert(value);
554                }
555                Some(index)
556            } else {
557                None
558            };
559        Self { entries, index }
560    }
561
562    fn get(&self, name: &str) -> Option<&'a Value> {
563        match &self.index {
564            Some(index) => index.get(name).copied(),
565            None => self
566                .entries
567                .iter()
568                .find(|(key, _)| key == name)
569                .map(|(_, value)| value),
570        }
571    }
572}
573
574fn same_raw(a: &Value, b: &Value) -> bool {
575    match (a, b) {
576        (Value::JArr(a), Value::JArr(b)) => {
577            Rc::ptr_eq(a, b)
578                || a.len() == b.len() && a.iter().zip(b.iter()).all(|(a, b)| same_raw(a, b))
579        }
580        (Value::JObj(a), Value::JObj(b)) => {
581            Rc::ptr_eq(a, b)
582                || a.len() == b.len()
583                    && a.iter()
584                        .zip(b.iter())
585                        .all(|((ak, a), (bk, b))| ak == bk && same_raw(a, b))
586        }
587        (Value::PreVal(a), Value::PreVal(b)) => {
588            let (x, y) = (&a.scope, &b.scope);
589            let (al, bl) = (x.locals.entries(), y.locals.entries());
590            Rc::ptr_eq(a, b)
591                || Rc::ptr_eq(&a.expr, &b.expr)
592                    && same_rc(&x.inst, &y.inst)
593                    && same_rc(&x.menv, &y.menv)
594                    && x.root_name == y.root_name
595                    && al.len() == bl.len()
596                    && al
597                        .iter()
598                        .all(|(k, v)| bl.get(k).is_some_and(|w| same_raw(v, w)))
599        }
600        (Value::Rec(a), Value::Rec(b)) => Rc::ptr_eq(a, b),
601        (Value::Arr(a), Value::Arr(b)) => Rc::ptr_eq(a, b),
602        (Value::Map(a), Value::Map(b)) => Rc::ptr_eq(a, b),
603        (Value::Int(_), Value::Int(_))
604        | (Value::Float(_), Value::Float(_))
605        | (Value::Str(_), Value::Str(_))
606        | (Value::Bool(_), Value::Bool(_))
607        | (Value::Null, Value::Null)
608        | (Value::Absent, Value::Absent)
609        | (Value::Undef, Value::Undef)
610        | (Value::Q(_), Value::Q(_)) => value_eq(a, b),
611        _ => false,
612    }
613}
614
615#[derive(Hash, PartialEq, Eq)]
616enum CaptureKey {
617    Record(usize),
618    Array(usize),
619    Map(usize),
620    Int(i64),
621    Float(u64),
622    String(Rc<str>),
623    Bool(bool),
624    Null,
625    Absent,
626    Undef,
627}
628fn capture(value: &Value, eng: &Engine, memo: &mut FxHashMap<CaptureKey, Matches>) -> Matches {
629    let key = match value {
630        Value::Rec(r) => Some(CaptureKey::Record(Rc::as_ptr(r) as usize)),
631        Value::Arr(a) => Some(CaptureKey::Array(Rc::as_ptr(a) as usize)),
632        Value::Map(m) => Some(CaptureKey::Map(Rc::as_ptr(m) as usize)),
633        Value::Int(Num::Small(n)) => Some(CaptureKey::Int(*n)),
634        Value::Float(n) => Some(CaptureKey::Float(n.to_bits())),
635        Value::Str(s) => Some(CaptureKey::String(s.to_rc())),
636        Value::Bool(b) => Some(CaptureKey::Bool(*b)),
637        Value::Null => Some(CaptureKey::Null),
638        Value::Absent => Some(CaptureKey::Absent),
639        Value::Undef => Some(CaptureKey::Undef),
640        _ => None,
641    };
642    if let Some(prior) = key.as_ref().and_then(|k| memo.get(k)) {
643        return prior.clone();
644    }
645    let matches = capture_shape(value, eng, memo);
646    if let Some(key) = key {
647        memo.insert(key, matches.clone());
648    }
649    matches
650}
651fn capture_shape(
652    value: &Value,
653    eng: &Engine,
654    memo: &mut FxHashMap<CaptureKey, Matches>,
655) -> Matches {
656    match value {
657        Value::Absent => Rc::new(|n, _| matches!(n, Value::Absent)),
658        Value::Rec(inst) => {
659            let identity = Rc::as_ptr(inst) as usize;
660            let b = inst.borrow();
661            let rt = b.rt.clone();
662            let order = b.entry_order.clone();
663            let members: Vec<_> = b
664                .slots
665                .iter()
666                .map(|(n, s)| (n.clone(), s.kind, s.hidden))
667                .collect();
668            let extras: Vec<_> = b
669                .extras
670                .iter()
671                .map(|(k, v)| (k.clone(), capture(v, eng, memo)))
672                .collect();
673            Rc::new(move |next, eng| {
674                let Value::Rec(n) = next else {
675                    return false;
676                };
677                let b = n.borrow();
678                Rc::as_ptr(n) as usize == identity
679                    && Rc::ptr_eq(&rt, &b.rt)
680                    && b.entry_order == order
681                    && b.slots.len() == members.len()
682                    && b.slots
683                        .iter()
684                        .zip(&members)
685                        .all(|((n, s), (k, kind, hidden))| {
686                            n == k && s.kind == *kind && s.hidden == *hidden
687                        })
688                    && b.extras.len() == extras.len()
689                    && b.extras
690                        .iter()
691                        .zip(&extras)
692                        .all(|((k, v), (n, matches))| k == n && matches(v, eng))
693            })
694        }
695        Value::Arr(a) => {
696            let a = a.borrow();
697            let path = a.path.clone();
698            let items: Vec<_> = a.items.iter().map(|v| capture(v, eng, memo)).collect();
699            Rc::new(move |n, eng| {
700                let Value::Arr(n) = n else {
701                    return false;
702                };
703                let n = n.borrow();
704                n.path == path
705                    && n.items.len() == items.len()
706                    && n.items.iter().zip(&items).all(|(v, m)| m(v, eng))
707            })
708        }
709        Value::Map(m) => {
710            let m = m.borrow();
711            let path = m.path.clone();
712            let entries: Vec<_> = m
713                .entries
714                .iter()
715                .map(|(k, v)| (k.clone(), capture(v, eng, memo)))
716                .collect();
717            Rc::new(move |n, eng| {
718                let Value::Map(n) = n else {
719                    return false;
720                };
721                let n = n.borrow();
722                n.path == path
723                    && n.entries.len() == entries.len()
724                    && n.entries
725                        .iter()
726                        .zip(&entries)
727                        .all(|((k, v), (l, m))| k == l && m(v, eng))
728            })
729        }
730        _ if comparable(value, eng) => {
731            let old = value.clone();
732            Rc::new(move |n, eng| comparable(n, eng) && value_eq(&old, n))
733        }
734        _ => Rc::new(|_, _| false),
735    }
736}
737
738#[derive(Clone)]
739enum RootInput {
740    Expr(Rc<crate::ast::Expr>),
741    Doc(Value),
742}
743type Inputs = FxHashMap<usize, (Weak<RefCell<RecInst>>, Vec<(String, Value)>)>;
744
745/// Retained Session queries, sharing the Engine's member cache.
746pub struct Edits {
747    /// Whether an edit is currently being materialized.
748    pub active: Cell<bool>,
749    /// Revision verification and result cutoff counters.
750    pub revisions: Rc<Revisions>,
751    /// Member programs actually executed, including reference rounds.
752    pub slot_computes: Cell<usize>,
753    /// Record instances retained in the current edit's first materialization.
754    pub retained_records: Cell<usize>,
755    /// Queries prepared for verification in the latest edit.
756    pub prepared_queries: Cell<usize>,
757    #[cfg(feature = "runtime-diagnostics")]
758    diagnostics: Cell<SessionEditDiagnostics>,
759    #[cfg(feature = "runtime-diagnostics")]
760    diagnostic_epoch: Cell<u64>,
761    invalid: RefCell<FxHashSet<String>>,
762    root_values: RefCell<FxHashMap<String, Value>>,
763    root_reads: RefCell<FxHashMap<String, ReadSet>>,
764    binding_reuse: Cell<bool>,
765    inputs: RefCell<Inputs>,
766    roots: RefCell<FxHashMap<String, RootInput>>,
767    pool: RefCell<FxHashMap<String, Inst>>,
768    live: RefCell<FxHashSet<usize>>,
769}
770
771impl Default for Edits {
772    fn default() -> Self {
773        let revisions = Rc::new(Revisions::default());
774        revisions.resolve.set(Some(Self::resolve));
775        Self {
776            active: Cell::new(false),
777            revisions,
778            slot_computes: Cell::new(0),
779            retained_records: Cell::new(0),
780            prepared_queries: Cell::new(0),
781            #[cfg(feature = "runtime-diagnostics")]
782            diagnostics: Cell::new(SessionEditDiagnostics::default()),
783            #[cfg(feature = "runtime-diagnostics")]
784            diagnostic_epoch: Cell::new(0),
785            invalid: RefCell::new(FxHashSet::default()),
786            root_values: RefCell::new(FxHashMap::default()),
787            root_reads: RefCell::new(FxHashMap::default()),
788            binding_reuse: Cell::new(true),
789            inputs: RefCell::new(FxHashMap::default()),
790            roots: RefCell::new(FxHashMap::default()),
791            pool: RefCell::new(FxHashMap::default()),
792            live: RefCell::new(FxHashSet::default()),
793        }
794    }
795}
796
797impl Edits {
798    /// Copy the latest bounded Session edit attribution without reading clocks.
799    /// Phase work includes instrumentation; it is not a native timing claim.
800    #[cfg(feature = "runtime-diagnostics")]
801    pub fn diagnostics(&self) -> SessionEditDiagnostics {
802        self.diagnostics.get()
803    }
804
805    fn resolve(eng: &Engine, key: &str) -> R<bool> {
806        let slot = eng.query_slot_shared(key);
807        if let Some((inst, name)) = slot {
808            eng.force_slot(&inst, &name)?;
809            return Ok(true);
810        }
811        if let Some((index, name)) = key.strip_prefix("const:").and_then(|k| k.split_once('|')) {
812            let env = index
813                .parse::<usize>()
814                .ok()
815                .and_then(|i| eng.const_envs.borrow().get(i).cloned());
816            if let Some(env) = env {
817                if env.consts.borrow().contains_key(name) {
818                    eng.force_const_in(&env, name, "")?;
819                    return Ok(true);
820                }
821            }
822        }
823        Ok(false)
824    }
825
826    fn retain(&self, eng: &Engine, value: &Value, seen: &mut FxHashSet<usize>) -> bool {
827        match value {
828            Value::Rec(inst) => {
829                let id = Rc::as_ptr(inst) as usize;
830                if !seen.insert(id) {
831                    return true;
832                }
833                let path = path_str(&inst.borrow().path, None);
834                self.pool
835                    .borrow()
836                    .get(&path)
837                    .is_some_and(|old| Rc::ptr_eq(old, inst))
838                    && self.inputs.borrow().get(&id).is_none_or(|(_, entries)| {
839                        entries.iter().all(|(_, v)| self.retain(eng, v, seen))
840                    })
841            }
842            Value::Arr(a) => a.borrow().items.iter().all(|v| self.retain(eng, v, seen)),
843            Value::Map(m) => m
844                .borrow()
845                .entries
846                .iter()
847                .all(|(_, v)| self.retain(eng, v, seen)),
848            Value::JArr(a) => a.iter().all(|v| self.retain(eng, v, seen)),
849            Value::JObj(m) => m.iter().all(|(_, v)| self.retain(eng, v, seen)),
850            Value::PreVal(p) => {
851                p.scope.inst.as_ref().is_none_or(|i| {
852                    self.pool
853                        .borrow()
854                        .get(&path_str(&i.borrow().path, None))
855                        .is_some_and(|old| Rc::ptr_eq(old, i))
856                }) && p
857                    .scope
858                    .locals
859                    .entries()
860                    .values()
861                    .all(|v| self.retain(eng, v, seen))
862            }
863            _ => comparable(value, eng),
864        }
865    }
866
867    fn collect(
868        eng: &Engine,
869        value: &Value,
870        into: &mut FxHashSet<String>,
871        seen: &mut FxHashSet<(u8, usize)>,
872    ) {
873        let identity = match value {
874            Value::Rec(r) => (0, Rc::as_ptr(r) as usize),
875            Value::Arr(a) => (1, Rc::as_ptr(a) as usize),
876            Value::Map(m) => (2, Rc::as_ptr(m) as usize),
877            _ => return,
878        };
879        if !seen.insert(identity) {
880            return;
881        }
882        match value {
883            Value::Rec(inst) => {
884                let b = inst.borrow();
885                let path = path_str(&b.path, None);
886                for (name, slot) in &b.slots {
887                    let key = format!("{path}.{name}");
888                    eng.register_query_slot(&key, inst.clone(), name.clone());
889                    into.insert(key);
890                    if slot.state == SlotState::Ok {
891                        Self::collect(eng, &slot.value, into, seen);
892                    }
893                }
894            }
895            Value::Arr(a) => {
896                for v in &a.borrow().items {
897                    Self::collect(eng, v, into, seen);
898                }
899            }
900            Value::Map(m) => {
901                for v in m.borrow().entries.values() {
902                    Self::collect(eng, v, into, seen);
903                }
904            }
905            _ => {}
906        }
907    }
908
909    fn diff(
910        eng: &Engine,
911        before: &Value,
912        next: &Value,
913        value: &Value,
914        producer: &str,
915        forced: &mut FxHashSet<String>,
916        known: &mut FxHashSet<String>,
917    ) {
918        if same_raw(before, next) {
919            return;
920        }
921        known.insert(producer.into());
922        forced.insert(producer.into());
923        match (value, before, next) {
924            (Value::Rec(inst), Value::JObj(a), Value::JObj(b)) => {
925                let names: FxHashSet<_> = a.iter().chain(b.iter()).map(|(k, _)| k).collect();
926                let before = FirstInputs::new(a, names.len());
927                let next = FirstInputs::new(b, names.len());
928                for name in names {
929                    let av = before.get(name);
930                    let bv = next.get(name);
931                    if av.is_some() == bv.is_some()
932                        && same_raw(av.unwrap_or(&Value::Undef), bv.unwrap_or(&Value::Undef))
933                    {
934                        continue;
935                    }
936                    let bound = inst.borrow();
937                    if let Some(slot) = bound.slot(name) {
938                        let key = format!("{}.{name}", path_str(&bound.path, None));
939                        eng.register_query_slot(&key, inst.clone(), Rc::from(name.as_str()));
940                        Self::diff(
941                            eng,
942                            av.unwrap_or(&Value::Undef),
943                            bv.unwrap_or(&Value::Undef),
944                            &slot.value,
945                            &key,
946                            forced,
947                            known,
948                        );
949                        forced.insert(key);
950                    }
951                }
952            }
953            (Value::Arr(v), Value::JArr(a), Value::JArr(b)) => {
954                let v = v.borrow();
955                for i in 0..a.len().max(b.len()) {
956                    Self::diff(
957                        eng,
958                        a.get(i).unwrap_or(&Value::Undef),
959                        b.get(i).unwrap_or(&Value::Undef),
960                        v.items.get(i).unwrap_or(&Value::Undef),
961                        producer,
962                        forced,
963                        known,
964                    );
965                }
966            }
967            (Value::Map(v), Value::JObj(a), Value::JObj(b)) => {
968                let names: FxHashSet<_> = a.iter().chain(b.iter()).map(|(k, _)| k).collect();
969                let before = FirstInputs::new(a, names.len());
970                let next = FirstInputs::new(b, names.len());
971                let v = v.borrow();
972                for name in names {
973                    let av = before.get(name).unwrap_or(&Value::Undef);
974                    let bv = next.get(name).unwrap_or(&Value::Undef);
975                    Self::diff(
976                        eng,
977                        av,
978                        bv,
979                        v.entries.get(name).unwrap_or(&Value::Undef),
980                        producer,
981                        forced,
982                        known,
983                    );
984                }
985            }
986            _ => Self::collect(eng, value, forced, &mut FxHashSet::default()),
987        }
988    }
989
990    pub(crate) fn begin(
991        &self,
992        eng: &Engine,
993        changed: &[String],
994        documents: &HashMap<String, Value>,
995    ) {
996        #[cfg(feature = "runtime-diagnostics")]
997        let mut trace = EditTrace::new(self, true);
998        eng.clear_materialized();
999        let mut values = FxHashMap::default();
1000        let mut forced = FxHashSet::default();
1001        let errors = eng.env.diag_len() > 0;
1002        self.binding_reuse.set(!errors);
1003        let records = eng.env.registry_snapshot();
1004        *self.pool.borrow_mut() = records
1005            .iter()
1006            .map(|r| (path_str(&r.borrow().path, None), r.clone()))
1007            .collect();
1008        self.live.borrow_mut().clear();
1009        self.retained_records.set(0);
1010        *self.root_values.borrow_mut() = eng.env.roots_vec().into_iter().collect();
1011        *self.root_reads.borrow_mut() = eng
1012            .env
1013            .root_names()
1014            .iter()
1015            .map(|n| {
1016                let key = format!("root:{n}");
1017                let deps = eng.query_reads(&key).unwrap_or_default();
1018                (key, deps)
1019            })
1020            .collect();
1021        #[cfg(feature = "runtime-diagnostics")]
1022        {
1023            let work = &mut trace.report.preparation_work;
1024            work.changed_roots = changed.len() as u64;
1025            work.previous_errors = errors;
1026            work.registry_records = records.len() as u64;
1027            work.pooled_records = self.pool.borrow().len() as u64;
1028            work.saved_roots = self.root_values.borrow().len() as u64;
1029            work.saved_root_reads = self.root_reads.borrow().len() as u64;
1030            trace.mark(true);
1031        }
1032        let mut known = FxHashSet::default();
1033        for name in changed {
1034            let key = format!("root:{name}");
1035            forced.insert(key.clone());
1036            known.insert(key.clone());
1037            let previous = self.roots.borrow().get(name).cloned();
1038            let value = eng.env.root(name).unwrap_or(Value::Undef);
1039            if let (Some(RootInput::Doc(before)), Some(next)) = (previous, documents.get(name)) {
1040                #[cfg(feature = "runtime-diagnostics")]
1041                {
1042                    trace.report.preparation_work.diff_roots += 1;
1043                }
1044                Self::diff(eng, &before, next, &value, &key, &mut forced, &mut known);
1045            } else {
1046                #[cfg(feature = "runtime-diagnostics")]
1047                {
1048                    trace.report.preparation_work.collected_roots += 1;
1049                }
1050                Self::collect(eng, &value, &mut forced, &mut FxHashSet::default());
1051            }
1052        }
1053        #[cfg(feature = "runtime-diagnostics")]
1054        {
1055            trace.report.preparation_work.known_producers = known.len() as u64;
1056            trace.report.preparation_work.forced_after_seeding[0] = forced.len() as u64;
1057            trace.mark(true);
1058        }
1059        // Preparation only reads the dependency graph. Borrow its thin reader
1060        // handles so queued readers can share the already-canonical key text.
1061        // Keep textual reverse keys and the original iteration/enqueue order.
1062        let reads = eng.reads.borrow();
1063        let mut readers: FxHashMap<&str, Vec<&QueryId>> = FxHashMap::default();
1064        for (key, deps) in reads.iter() {
1065            for dep in deps.iter() {
1066                let next = readers.entry(dep.as_str()).or_default();
1067                #[cfg(feature = "runtime-diagnostics")]
1068                let before_capacity = next.capacity();
1069                #[cfg(feature = "runtime-diagnostics")]
1070                {
1071                    let work = &mut trace.report.preparation_work;
1072                    work.read_edges += 1;
1073                    if next.is_empty() {
1074                        work.reverse_keys += 1;
1075                        if dep.starts_with("value:") {
1076                            work.value_dependency_keys += 1;
1077                        }
1078                    } else {
1079                        work.reverse_degree_buckets[EditTrace::degree(next.len())] -= 1;
1080                    }
1081                    for (i, prefix) in ["edge:", "snapshot:", "round:", "value:"]
1082                        .iter()
1083                        .enumerate()
1084                    {
1085                        if dep.starts_with(prefix) {
1086                            work.special_edges[i] += 1;
1087                        }
1088                    }
1089                }
1090                next.push(key);
1091                #[cfg(feature = "runtime-diagnostics")]
1092                {
1093                    let work = &mut trace.report.preparation_work;
1094                    work.reverse_degree_buckets[EditTrace::degree(next.len())] += 1;
1095                    work.reverse_max_degree = work.reverse_max_degree.max(next.len() as u64);
1096                    work.reverse_vector_capacity += (next.capacity() - before_capacity) as u64;
1097                }
1098                if ["edge:", "snapshot:", "round:", "value:"]
1099                    .iter()
1100                    .any(|p| dep.starts_with(p))
1101                {
1102                    forced.insert(key.as_str().to_owned());
1103                }
1104            }
1105        }
1106        #[cfg(feature = "runtime-diagnostics")]
1107        {
1108            trace.report.preparation_work.read_queries = reads.len() as u64;
1109            trace.report.preparation_work.forced_after_seeding[1] = forced.len() as u64;
1110            trace.mark(true);
1111        }
1112        for (name, value) in eng.env.roots_vec() {
1113            values.insert(format!("root:{name}"), value);
1114        }
1115        for inst in &records {
1116            let b = inst.borrow();
1117            let path = path_str(&b.path, None);
1118            for (name, slot) in &b.slots {
1119                #[cfg(feature = "runtime-diagnostics")]
1120                {
1121                    trace.report.preparation_work.registered_slots_scanned += 1;
1122                }
1123                let key = format!("{path}.{name}");
1124                if matches!(slot.state, SlotState::Ok | SlotState::Absent) {
1125                    #[cfg(feature = "runtime-diagnostics")]
1126                    {
1127                        trace.report.preparation_work.saved_slot_writes += 1;
1128                    }
1129                    values.insert(
1130                        key.clone(),
1131                        if slot.state == SlotState::Absent {
1132                            Value::Absent
1133                        } else {
1134                            slot.value.clone()
1135                        },
1136                    );
1137                }
1138                if errors {
1139                    forced.insert(key.clone());
1140                    eng.register_query_slot(&key, inst.clone(), name.clone());
1141                }
1142            }
1143        }
1144        for (index, env) in eng.const_envs.borrow().iter().enumerate() {
1145            for (name, con) in env.consts.borrow().iter() {
1146                #[cfg(feature = "runtime-diagnostics")]
1147                {
1148                    trace.report.preparation_work.constants_scanned += 1;
1149                }
1150                let key = format!("const:{index}|{name}");
1151                if con.state.get() {
1152                    #[cfg(feature = "runtime-diagnostics")]
1153                    {
1154                        trace.report.preparation_work.saved_constant_writes += 1;
1155                    }
1156                    values.insert(key.clone(), con.value.borrow().clone());
1157                }
1158                if errors {
1159                    forced.insert(key);
1160                }
1161            }
1162        }
1163        #[cfg(feature = "runtime-diagnostics")]
1164        {
1165            let work = &mut trace.report.preparation_work;
1166            work.saved_values = values.len() as u64;
1167            work.saved_values_capacity = values.capacity() as u64;
1168            work.forced_after_seeding[2] = forced.len() as u64;
1169            trace.mark(true);
1170        }
1171        if !eng.queried.borrow().is_empty() {
1172            for (key, value) in &values {
1173                #[cfg(feature = "runtime-diagnostics")]
1174                {
1175                    trace.report.preparation_work.retention_checks += 1;
1176                }
1177                if !self.retain(eng, value, &mut FxHashSet::default()) {
1178                    #[cfg(feature = "runtime-diagnostics")]
1179                    {
1180                        trace.report.preparation_work.retention_rejections += 1;
1181                    }
1182                    forced.insert(key.clone());
1183                }
1184            }
1185        }
1186        #[cfg(feature = "runtime-diagnostics")]
1187        {
1188            trace.report.preparation_work.forced_after_seeding[3] = forced.len() as u64;
1189        }
1190        if errors {
1191            forced.extend(reads.keys().map(|key| key.as_str().to_owned()));
1192        }
1193        #[cfg(feature = "runtime-diagnostics")]
1194        {
1195            trace.report.preparation_work.forced_after_seeding[4] = forced.len() as u64;
1196            trace.mark(true);
1197        }
1198        let mut invalid = FxHashSet::default();
1199        // Stable seed, saved-value and reader text can be borrowed until the
1200        // traversal ends. Generated descendant sets instead transfer their
1201        // Strings, preserving their owned iteration order without interning.
1202        let mut queue: Vec<Cow<'_, str>> = forced
1203            .iter()
1204            .map(|key| Cow::Borrowed(key.as_str()))
1205            .collect();
1206        #[cfg(feature = "runtime-diagnostics")]
1207        {
1208            trace.report.preparation_work.initial_queue = queue.len() as u64;
1209            trace.queue(&queue);
1210        }
1211        let mut walked = FxHashSet::default();
1212        for dep in readers.keys() {
1213            let Some(path) = dep.strip_prefix("value:") else {
1214                continue;
1215            };
1216            #[cfg(feature = "runtime-diagnostics")]
1217            {
1218                trace.report.preparation_work.value_owners_examined += 1;
1219            }
1220            let record = self.pool.borrow().get(path).cloned();
1221            if let Some(record) = record {
1222                let mut descendants = FxHashSet::default();
1223                Self::collect(eng, &Value::Rec(record), &mut descendants, &mut walked);
1224                #[cfg(feature = "runtime-diagnostics")]
1225                {
1226                    trace.report.preparation_work.value_owners_found += 1;
1227                    trace.report.preparation_work.owner_descendant_enqueues +=
1228                        descendants.len() as u64;
1229                }
1230                queue.extend(descendants.into_iter().map(Cow::Owned));
1231            } else {
1232                // Unknown/frozen owners retain the conservative fallback.
1233                #[cfg(feature = "runtime-diagnostics")]
1234                {
1235                    trace.report.preparation_work.missing_owner_fallback = true;
1236                    trace.report.preparation_work.fallback_enqueues = values.len() as u64;
1237                }
1238                queue.extend(values.keys().map(|key| Cow::Borrowed(key.as_str())));
1239                #[cfg(feature = "runtime-diagnostics")]
1240                {
1241                    trace.queue(&queue);
1242                }
1243                break;
1244            }
1245            #[cfg(feature = "runtime-diagnostics")]
1246            {
1247                trace.queue(&queue);
1248            }
1249        }
1250        while let Some(key) = queue.pop() {
1251            #[cfg(feature = "runtime-diagnostics")]
1252            {
1253                trace.report.preparation_work.queue_pops += 1;
1254            }
1255            // Duplicates keep their LIFO position, but do not allocate another
1256            // owned string merely to discover that the key is already invalid.
1257            if invalid.contains(key.as_ref()) {
1258                #[cfg(feature = "runtime-diagnostics")]
1259                {
1260                    trace.report.preparation_work.duplicate_pops += 1;
1261                }
1262                continue;
1263            }
1264            invalid.insert(key.as_ref().to_owned());
1265            if !known.contains(key.as_ref()) {
1266                if let Some(value) = values.get(key.as_ref()) {
1267                    let mut descendants = FxHashSet::default();
1268                    Self::collect(eng, value, &mut descendants, &mut walked);
1269                    #[cfg(feature = "runtime-diagnostics")]
1270                    let before_len = queue.len();
1271                    queue.extend(
1272                        descendants
1273                            .into_iter()
1274                            .filter(|k| !invalid.contains(k))
1275                            .map(Cow::Owned),
1276                    );
1277                    #[cfg(feature = "runtime-diagnostics")]
1278                    {
1279                        trace.report.preparation_work.producer_collects += 1;
1280                        trace.report.preparation_work.producer_descendant_enqueues +=
1281                            (queue.len() - before_len) as u64;
1282                        trace.queue(&queue);
1283                    }
1284                }
1285            }
1286            #[cfg(feature = "runtime-diagnostics")]
1287            if known.contains(key.as_ref()) {
1288                trace.report.preparation_work.known_producers_skipped += 1;
1289            }
1290            if let Some(next) = readers.get(key.as_ref()) {
1291                #[cfg(feature = "runtime-diagnostics")]
1292                {
1293                    trace.report.preparation_work.reader_enqueues += next.len() as u64;
1294                }
1295                queue.extend(next.iter().map(|key| Cow::Borrowed(key.as_str())));
1296                #[cfg(feature = "runtime-diagnostics")]
1297                {
1298                    trace.queue(&queue);
1299                }
1300            }
1301        }
1302        // Release the drained queue's buffer and all borrowed text before
1303        // capturing Pending values or allowing dependency mutation.
1304        drop(queue);
1305        drop(readers);
1306        drop(reads);
1307        self.prepared_queries.set(invalid.len());
1308        #[cfg(feature = "runtime-diagnostics")]
1309        {
1310            trace.report.preparation_work.walked_values = walked.len() as u64;
1311            trace.report.preparation_work.invalid_queries = invalid.len() as u64;
1312            trace.mark(true);
1313        }
1314        let mut captured = FxHashMap::default();
1315        self.revisions
1316            .begin_queries(eng, &invalid, &values, &forced, |v| {
1317                #[cfg(feature = "runtime-diagnostics")]
1318                {
1319                    let work = &mut trace.report.preparation_work;
1320                    work.pending_captures += 1;
1321                    let kind = match v {
1322                        Value::Rec(_) => 0,
1323                        Value::Arr(_) | Value::Map(_) => 1,
1324                        Value::JArr(_) | Value::JObj(_) => 2,
1325                        _ => 3,
1326                    };
1327                    work.pending_capture_kinds[kind] += 1;
1328                }
1329                capture(v, eng, &mut captured)
1330            });
1331        #[cfg(feature = "runtime-diagnostics")]
1332        {
1333            trace.report.preparation_work.capture_memo_entries = captured.len() as u64;
1334        }
1335        drop(captured);
1336        #[cfg(feature = "runtime-diagnostics")]
1337        {
1338            trace.report.revision = self.revisions.revision.get();
1339            trace.mark(true);
1340        }
1341        for key in &invalid {
1342            if let Some((inst, name)) = eng.query_slot_shared(key) {
1343                if let Some(slot) = inst.borrow_mut().slot_mut(&name) {
1344                    if slot.compute.is_some() {
1345                        #[cfg(feature = "runtime-diagnostics")]
1346                        {
1347                            trace.report.preparation_work.reset_slots += 1;
1348                        }
1349                        slot.state = SlotState::Unforced;
1350                        slot.value = Value::Undef;
1351                    }
1352                }
1353            }
1354        }
1355        for (index, env) in eng.const_envs.borrow().iter().enumerate() {
1356            for (name, con) in env.consts.borrow().iter() {
1357                if invalid.contains(&format!("const:{index}|{name}")) {
1358                    #[cfg(feature = "runtime-diagnostics")]
1359                    {
1360                        trace.report.preparation_work.reset_constants += 1;
1361                    }
1362                    con.state.set(false);
1363                    *con.value.borrow_mut() = Value::Undef;
1364                }
1365            }
1366        }
1367        *self.invalid.borrow_mut() = invalid;
1368        eng.env.roots_clear();
1369        eng.env.registry_clear();
1370        eng.env.diag_truncate(0);
1371        eng.failed_inputs.borrow_mut().clear();
1372        eng.deferred_slots.borrow_mut().clear();
1373        eng.deferred_roots.borrow_mut().clear();
1374        eng.phase.set(1);
1375        eng.settled.set(false);
1376        *eng.prev.borrow_mut() = None;
1377        *eng.snap.borrow_mut() = None;
1378        eng.queried.borrow_mut().clear();
1379        eng.ref_index.borrow_mut().clear();
1380        eng.computing_edges.borrow_mut().clear();
1381        eng.edge_bases.borrow_mut().clear();
1382        *eng.round_roots.borrow_mut() = None;
1383        self.active.set(true);
1384        #[cfg(feature = "runtime-diagnostics")]
1385        {
1386            trace.mark(true);
1387            trace.completed = true;
1388        }
1389    }
1390
1391    pub(crate) fn root(
1392        &self,
1393        eng: &Engine,
1394        name: &str,
1395        raw: &RootSrc,
1396        run: impl FnOnce() -> R<Value>,
1397    ) -> R<Value> {
1398        let next = match raw {
1399            RootSrc::Expr(e) => RootInput::Expr((*e).clone()),
1400            RootSrc::Doc(v) => RootInput::Doc(v.clone()),
1401        };
1402        let previous = self.roots.borrow_mut().insert(name.into(), next.clone());
1403        if !self.active.get() {
1404            return run();
1405        }
1406        let same = match (&previous, &next) {
1407            (Some(RootInput::Expr(a)), RootInput::Expr(b)) => Rc::ptr_eq(a, b),
1408            (Some(RootInput::Doc(a)), RootInput::Doc(b)) => same_raw(a, b),
1409            _ => false,
1410        };
1411        let key = format!("root:{name}");
1412        if !same {
1413            self.revisions.force(eng, &key);
1414        }
1415        if !self.invalid.borrow().contains(&key) {
1416            let value = self.root_values.borrow().get(name).cloned();
1417            if let Some(value) = value {
1418                eng.replace_query_reads(
1419                    &key,
1420                    self.root_reads
1421                        .borrow()
1422                        .get(&key)
1423                        .cloned()
1424                        .unwrap_or_default(),
1425                );
1426                self.activate(eng, &value);
1427                return Ok(value);
1428            }
1429        }
1430        self.compute(eng, &key, run)
1431    }
1432
1433    pub(crate) fn unchanged(&self, inst: &Inst, entries: &[(String, Value)]) -> bool {
1434        if !self.binding_reuse.get() {
1435            return false;
1436        }
1437        let inputs = self.inputs.borrow();
1438        let Some((weak, before)) = inputs.get(&(Rc::as_ptr(inst) as usize)) else {
1439            return false;
1440        };
1441        if !weak.upgrade().is_some_and(|r| Rc::ptr_eq(&r, inst)) {
1442            return false;
1443        }
1444        before.len() == entries.len()
1445            && inst
1446                .borrow()
1447                .entry_order
1448                .iter()
1449                .map(String::as_str)
1450                .eq(entries.iter().map(|(n, _)| n.as_str()))
1451            && {
1452                let before = FirstInputs::new(before, entries.len());
1453                entries
1454                    .iter()
1455                    .all(|(k, v)| before.get(k).is_some_and(|b| same_raw(b, v)))
1456            }
1457    }
1458
1459    pub(crate) fn record(&self, rt: &RT, path: &[Seg], parent: Option<&Inst>) -> Option<Inst> {
1460        if !self.active.get() {
1461            return None;
1462        }
1463        let old = self.pool.borrow().get(&path_str(path, None)).cloned()?;
1464        let matches = {
1465            let b = old.borrow();
1466            Rc::ptr_eq(&b.rt, rt) && same_rc(&b.parent, &parent.cloned())
1467        };
1468        matches.then_some(old)
1469    }
1470
1471    pub(crate) fn bound(
1472        &self,
1473        eng: &Engine,
1474        inst: &Inst,
1475        entries: &[(String, Value)],
1476        old_slots: Vec<(Rc<str>, Slot)>,
1477    ) {
1478        let id = Rc::as_ptr(inst) as usize;
1479        if self.active.get() {
1480            let mut old: FxHashMap<_, _> = old_slots.into_iter().collect();
1481            let inputs = self.inputs.borrow();
1482            let before = inputs
1483                .get(&id)
1484                .filter(|(weak, _)| weak.upgrade().is_some_and(|r| Rc::ptr_eq(&r, inst)))
1485                .map(|(_, v)| v);
1486            let names: Vec<_> = inst.borrow().slots.iter().map(|(n, _)| n.clone()).collect();
1487            let before = before.map(|entries| FirstInputs::new(entries, names.len()));
1488            let next = FirstInputs::new(entries, names.len());
1489            for name in names {
1490                let key = format!("{}.{name}", path_str(&inst.borrow().path, None));
1491                let a = before.as_ref().and_then(|entries| entries.get(&name));
1492                let n = next.get(&name);
1493                let same = match (a, n) {
1494                    (Some(a), Some(b)) => same_raw(a, b),
1495                    (None, None) => true,
1496                    _ => false,
1497                };
1498                let old_slot = old.remove(&name);
1499                let kind = inst.borrow().slot(&name).unwrap().kind;
1500                if before.is_none() || !same || old_slot.as_ref().is_none_or(|s| s.kind != kind) {
1501                    self.revisions.force(eng, &key);
1502                } else if let Some(slot) = old_slot {
1503                    *inst.borrow_mut().slot_mut(&name).unwrap() = slot;
1504                }
1505                eng.register_query_slot(&key, inst.clone(), name);
1506            }
1507        }
1508        self.inputs
1509            .borrow_mut()
1510            .insert(id, (Rc::downgrade(inst), entries.to_vec()));
1511        if self.active.get() {
1512            for (_, slot) in &inst.borrow().slots {
1513                if slot.state == SlotState::Ok {
1514                    self.activate(eng, &slot.value);
1515                }
1516            }
1517        }
1518    }
1519
1520    pub(crate) fn register(&self, eng: &Engine, inst: &Inst) {
1521        if !self.live.borrow_mut().insert(Rc::as_ptr(inst) as usize) {
1522            return;
1523        }
1524        eng.env.registry_push(inst.clone());
1525        if self
1526            .pool
1527            .borrow()
1528            .get(&path_str(&inst.borrow().path, None))
1529            .is_some_and(|old| Rc::ptr_eq(old, inst))
1530        {
1531            self.retained_records.set(self.retained_records.get() + 1);
1532        }
1533    }
1534
1535    pub(crate) fn activate(&self, eng: &Engine, value: &Value) {
1536        if !self.active.get() || eng.no_reg.get() > 0 {
1537            return;
1538        }
1539        match value {
1540            Value::Rec(inst) => {
1541                if eng.owner_of(inst).is_some()
1542                    || self.live.borrow().contains(&(Rc::as_ptr(inst) as usize))
1543                {
1544                    return;
1545                }
1546                self.register(eng, inst);
1547                for (_, s) in &inst.borrow().slots {
1548                    if s.state == SlotState::Ok {
1549                        self.activate(eng, &s.value);
1550                    }
1551                }
1552            }
1553            Value::Arr(a) => {
1554                for v in &a.borrow().items {
1555                    self.activate(eng, v);
1556                }
1557            }
1558            Value::Map(m) => {
1559                for v in m.borrow().entries.values() {
1560                    self.activate(eng, v);
1561                }
1562            }
1563            _ => {}
1564        }
1565    }
1566
1567    pub(crate) fn compute(
1568        &self,
1569        eng: &Engine,
1570        key: &str,
1571        run: impl FnOnce() -> R<Value>,
1572    ) -> R<Value> {
1573        let id = eng.query_id(key);
1574        self.compute_id(eng, &id, run)
1575    }
1576
1577    pub(crate) fn compute_id(
1578        &self,
1579        eng: &Engine,
1580        id: &QueryId,
1581        run: impl FnOnce() -> R<Value>,
1582    ) -> R<Value> {
1583        let value = self.revisions.compute_id(eng, id, run)?;
1584        self.activate(eng, &value);
1585        Ok(value)
1586    }
1587
1588    /// Number of retained record input descriptions (a diagnostic counter).
1589    pub fn cached_inputs(&self) -> usize {
1590        self.inputs.borrow().len()
1591    }
1592
1593    pub(crate) fn prune(&self, eng: &Engine) {
1594        if !self.inputs.borrow().is_empty() {
1595            // Only addresses escape this borrow. Release both registry borrows
1596            // before dropping cached values: a native capture's destructor can
1597            // replace the public registry or roots during retain.
1598            let live: FxHashSet<_> = eng
1599                .env
1600                .registry
1601                .borrow()
1602                .borrow()
1603                .iter()
1604                .map(|r| Rc::as_ptr(r) as usize)
1605                .collect();
1606            self.inputs
1607                .borrow_mut()
1608                .retain(|id, (weak, _)| live.contains(id) && weak.strong_count() > 0);
1609        }
1610        self.roots
1611            .borrow_mut()
1612            .retain(|name, _| root_exists(eng, name));
1613    }
1614
1615    pub(crate) fn finish(&self, eng: &Engine) {
1616        #[cfg(feature = "runtime-diagnostics")]
1617        let mut trace = EditTrace::new(self, false);
1618        #[cfg(feature = "runtime-diagnostics")]
1619        {
1620            trace.report.finish_work.input_entries[0] = self.inputs.borrow().len() as u64;
1621            trace.report.finish_work.root_entries[0] = self.roots.borrow().len() as u64;
1622        }
1623        self.prune(eng);
1624        #[cfg(feature = "runtime-diagnostics")]
1625        {
1626            trace.report.finish_work.input_entries[1] = self.inputs.borrow().len() as u64;
1627            trace.report.finish_work.root_entries[1] = self.roots.borrow().len() as u64;
1628            trace.report.finish_was_active = self.active.get();
1629            trace.mark(true);
1630        }
1631        if !self.active.get() {
1632            #[cfg(feature = "runtime-diagnostics")]
1633            {
1634                trace.completed = true;
1635                trace.close_on_drop = false;
1636            }
1637            return;
1638        }
1639        #[cfg(feature = "runtime-diagnostics")]
1640        {
1641            trace.report.finish_work.slot_entries[0] = eng.slots_by_key.borrow().len() as u64;
1642            trace.report.finish_work.read_entries[0] = eng.reads.borrow().len() as u64;
1643        }
1644        let live = self.live.borrow();
1645        eng.slots_by_key.borrow_mut().retain(|key, (inst, _)| {
1646            if live.contains(&(Rc::as_ptr(inst) as usize)) {
1647                true
1648            } else {
1649                eng.reads.borrow_mut().remove(key);
1650                false
1651            }
1652        });
1653        self.roots
1654            .borrow_mut()
1655            .retain(|name, _| root_exists(eng, name));
1656        // Assertions run again after settling; their previous reads have no
1657        // cached result to retain, just like roots removed by this edit.
1658        eng.reads.borrow_mut().retain(|key, _| {
1659            !key.starts_with("assert:")
1660                && key
1661                    .strip_prefix("root:")
1662                    .is_none_or(|name| root_exists(eng, name))
1663        });
1664        #[cfg(feature = "runtime-diagnostics")]
1665        {
1666            let work = &mut trace.report.finish_work;
1667            work.root_entries[2] = self.roots.borrow().len() as u64;
1668            work.slot_entries[1] = eng.slots_by_key.borrow().len() as u64;
1669            work.read_entries[1] = eng.reads.borrow().len() as u64;
1670            trace.mark(true);
1671            trace.report.finish_work.revision_entries[0] = self.revisions.tracked_queries() as u64;
1672        }
1673        self.revisions.finish();
1674        self.revisions.prune(eng);
1675        #[cfg(feature = "runtime-diagnostics")]
1676        {
1677            trace.report.finish_work.revision_entries[1] = self.revisions.tracked_queries() as u64;
1678            trace.mark(true);
1679        }
1680        self.pool.borrow_mut().clear();
1681        drop(live);
1682        self.live.borrow_mut().clear();
1683        self.invalid.borrow_mut().clear();
1684        self.root_values.borrow_mut().clear();
1685        self.root_reads.borrow_mut().clear();
1686        self.active.set(false);
1687        #[cfg(feature = "runtime-diagnostics")]
1688        {
1689            trace.mark(true);
1690        }
1691        eng.sweep_query_ids();
1692        #[cfg(feature = "runtime-diagnostics")]
1693        {
1694            trace.mark(true);
1695            trace.completed = true;
1696        }
1697    }
1698}
1699
1700#[cfg(test)]
1701#[path = "../../tests/private/edits_prune_test.rs"]
1702mod prune_tests;
1703
1704#[cfg(all(test, feature = "runtime-diagnostics"))]
1705#[path = "../../tests/private/edits_diagnostics_test.rs"]
1706mod diagnostics_tests;