sim_incremental_core/
lib.rs

1#![forbid(unsafe_code)]
2#![deny(missing_docs)]
3//! Generic incremental query calculation for SIM runtime libraries.
4//!
5//! `sim-incremental-core` records dependencies from actual query execution. A
6//! query can read another query through its [`QueryFrame`], observe external
7//! stamps, and return any hashable Rust value. The engine keeps memoized values,
8//! reverse dependency edges, cycle paths, typed budget failures, continuation
9//! tokens, and bounded graph snapshots without depending on SIM expressions,
10//! codecs, Table/Dir storage, web surfaces, or expression-tree records.
11//!
12//! # Dataflow reuse and cycle boundary
13//!
14//! Dataflow extensions reuse this crate's existing ownership ledger instead of
15//! defining parallel protocol types:
16//!
17//! - fingerprint: [`ValueFingerprint`]
18//! - observation: [`Observation`]
19//! - revision: [`Revision`]
20//! - budget: [`QueryBudgets`]
21//! - continuation: [`ContinuationToken`]
22//! - snapshot: [`GraphSnapshot`]
23//!
24//! A cycle in a dataflow graph is valid when its edges carry monotone lattice
25//! facts: repeatedly joining those facts must converge at a fixed point. That
26//! worklist-level feedback does not recursively enter query callbacks. By
27//! contrast, a query dependency cycle occurs when a [`QueryFrame::read`] tries
28//! to re-enter a query already on the active query stack. It is a programming
29//! error reported as [`IncrementalError::Cycle`], not a fixed-point request.
30//!
31//! # Examples
32//!
33//! ```
34//! use sim_incremental_core::{IncrementalEngine, QueryResult};
35//!
36//! let mut engine = IncrementalEngine::<&'static str, i64>::new();
37//! engine.register_fn("a", |_, _| Ok(1));
38//! engine.register_fn("b", |_, frame| {
39//!     let a = frame.read("a")?;
40//!     Ok(a + 1)
41//! });
42//!
43//! let value: QueryResult<_, _> = engine.verify("b");
44//! assert_eq!(value.unwrap(), 2);
45//! ```
46
47mod budget;
48pub mod dataflow;
49mod engine;
50mod error;
51mod fingerprint;
52mod observation;
53mod query;
54mod snapshot;
55mod state;
56
57pub use budget::{BudgetKind, QueryBudgets, SnapshotBudgets};
58pub use engine::{IncrementalEngine, QueryFrame};
59pub use error::{ContinuationToken, IncrementalError, SnapshotError};
60pub use fingerprint::{FingerprintValue, ValueFingerprint};
61pub use observation::{Observation, ObservationKind, Revision};
62pub use query::{Query, QueryResult};
63pub use snapshot::{GraphSnapshot, RestoreReport, SnapshotNode};
64
65#[cfg(test)]
66mod tests;
sim_incremental_core/lib.rs

sim_incremental_core/
lib.rs
