Skip to main content

day_persistence/
lib.rs

1// Copyright © The Daybrite Project
2// SPDX-License-Identifier: MPL-2.0
3
4//! SQLite persistence for the observable model (docs/persistence.md).
5//!
6//! An app depends on this crate directly, beside the `day` facade with its `model` feature on,
7//! and starts a model module with `use day_persistence::prelude::*`. The crate is built on the
8//! framework's public API and nothing in the framework depends on it; `#[derive(Model)]` comes
9//! from day-persistence-macros and the web engine from day-sqlite-worker.
10//!
11//! The engine owns the data; memory holds a working set. A [`ModelContainer`] opens a
12//! database through a pluggable [`SqliteDriver`], creates or migrates each model's table,
13//! and stops: no rows are read at open, so opening a million-row store costs the same as
14//! opening an empty one. Rows enter memory by faulting: a typed [`ModelContainer::get`], a
15//! batch [`ModelContainer::ensure_resident`], or a list binding materializing the rows it is
16//! about to show. Each model's [`Store`] is that working set (an ordinary day-model store,
17//! so every binding and accessor works on it unchanged), bounded by a per-table cache limit;
18//! clean rows nothing observes leave silently and fault back on the next read.
19//!
20//! The write half is day-model's change log, folded. Any write requires its row resident
21//! (editing is what faulted it in); at the end of any turn that touched a store (autosave,
22//! the default) the accumulated changes fold into the smallest statement list that expresses
23//! them: twenty keystrokes into one field is one `UPDATE`; a row inserted and then filled is
24//! one `INSERT`; a thousand-child cascade is a handful of chunked `DELETE`s.
25//!
26//! Typed live queries ([`ModelContainer::query`]) compile entirely to SQL: predicate to
27//! `WHERE` (relation crossings as correlated `EXISTS`, full-text as an FTS5 subquery, spatial
28//! boxes through the R*Tree shadow), sort to `ORDER BY` with the key as tie-break, window to
29//! `LIMIT`, so the engine's indexes answer them at any table size. Live maintenance is
30//! dependency-gated: a change to a column no query mentions costs nothing; a change a query
31//! does depend on marks it stale, and one requery after the turn's flush re-derives its id
32//! set, diffed against the previous answer so a list animates the difference instead of
33//! reloading. Rows behind the ids stay lazy: the query holds ids, and the list faults the
34//! window it shows.
35//!
36//! The driver is a trait so the engine is the app's choice: the built-in [`Sqlite`] driver
37//! (feature `driver-rusqlite`, on by default) compiles a bundled SQLite, links the system one
38//! (`system`), or builds SQLCipher (`cipher`); the [`Recorder`] answers from fixtures and
39//! records every statement, which is what keeps persistence assertable headlessly: a test
40//! can check the SQL a UI action produced without a database on disk.
41//!
42//! Another connection's committed writes arrive through [`ModelContainer::check_external`],
43//! which re-reads only the resident rows and re-runs the live queries: O(working set), never
44//! O(table). Row identity is the model's `#[model(id)]` key; display order is a projection
45//! concern and is not persisted.
46
47use std::any::{Any, TypeId};
48use std::cell::{Cell, RefCell};
49use std::collections::HashMap;
50use std::fmt;
51use std::path::{Path, PathBuf};
52use std::rc::Rc;
53
54use day_model::Source;
55use day_model::{Identified, Key, Keyed, ModelId, Op, Store};
56
57#[cfg(not(target_arch = "wasm32"))]
58mod worker;
59#[cfg(not(target_arch = "wasm32"))]
60pub use worker::{
61    DatabaseWorker, WorkerOptions, WorkerRequest, WorkerSnapshot, WorkerSubscription,
62};
63
64mod queries;
65pub use queries::{
66    Col, Delta, Deps, Fetch, FtsRef, GeoRect, GeoRef, Pred, Quant, RelatedDep, RelationCol,
67    ResultSet, RowView, SetChange, Sort, compare_values, encode_column, rank,
68};
69use queries::{CompileErr, RelSql, SqlIndex, compile_count, compile_fallback, compile_fetch};
70
71mod relations;
72pub use relations::{
73    DeleteRule, Many, One, Registrar, RelationDef, RelationRef, wire_join, wire_to_many,
74};
75
76#[cfg(feature = "driver-rusqlite")]
77mod rusqlite_driver;
78#[cfg(feature = "driver-rusqlite")]
79pub use rusqlite_driver::Sqlite;
80#[cfg(all(
81    feature = "driver-rusqlite",
82    target_family = "wasm",
83    target_os = "unknown"
84))]
85pub use rusqlite_driver::WebStorage;
86
87/// The derive for the [`Model`] trait (the two share a name, so `use day_persistence::Model`
88/// brings both): everything `#[derive(Observable)]` generates plus the schema half.
89/// `#[model(id)]` marks the key; docs/persistence.md lists the field and struct options.
90pub use day_persistence_macros::Model;
91
92// `#[derive(Model)]` expands its observable half to this (day-macros' `observable_impls!`),
93// reached by this crate's name so a model crate needs no day-macros dependency of its own.
94#[doc(hidden)]
95pub use day_macros::observable_impls as __observable_impls;
96
97/// What a model module starts from: `use day_persistence::prelude::*;` beside the app's `use
98/// day::prelude::*;`. The container, the `Model` trait and its derive, the relation markers,
99/// the drivers and `schema!`.
100pub mod prelude {
101    #[cfg(feature = "driver-rusqlite")]
102    pub use crate::Sqlite;
103    pub use crate::{DeleteRule, Many, Model, ModelContainer, One, Recorder, Secret, schema};
104}
105
106// ---------------------------------------------------------------------------
107// Errors
108// ---------------------------------------------------------------------------
109
110/// Why a persistence operation failed. `message` is for the log; `kind` is for the code path
111/// that can do something about it.
112#[derive(Clone, Debug)]
113pub struct DbError {
114    pub kind: DbErrorKind,
115    pub message: String,
116}
117
118#[derive(Clone, Copy, PartialEq, Eq, Debug)]
119pub enum DbErrorKind {
120    /// An asynchronous request was rejected because its worker has closed.
121    Closed,
122    /// The bounded worker queue has no room; the request was not accepted.
123    Busy,
124    /// A queued read was cancelled before it began.
125    Cancelled,
126    /// A worker operation panicked. The worker is closed and must be reopened.
127    Panicked,
128    /// The engine said no: SQL error, I/O, constraint.
129    Driver,
130    /// The stored schema and the declared one disagree in a way lightweight migration cannot
131    /// close (a type change, a rename); the file is refused, never silently rewritten.
132    Schema,
133    /// The database would not open with the key it was given.
134    BadKey,
135    /// A stored value would not decode as the field's type.
136    Decode,
137    /// The driver cannot do this (encryption on a non-cipher build, …).
138    Unsupported,
139    /// A `DeleteRule::Deny` relation refused the delete: children still reference the row.
140    Deny,
141}
142
143impl DbError {
144    pub fn new(kind: DbErrorKind, message: impl Into<String>) -> Self {
145        DbError {
146            kind,
147            message: message.into(),
148        }
149    }
150    /// Engine-error shorthand for driver implementations (public: external drivers use it too).
151    pub fn driver(message: impl Into<String>) -> Self {
152        Self::new(DbErrorKind::Driver, message)
153    }
154}
155
156impl fmt::Display for DbError {
157    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
158        write!(f, "{:?}: {}", self.kind, self.message)
159    }
160}
161
162impl std::error::Error for DbError {}
163
164// ---------------------------------------------------------------------------
165// Values and rows
166// ---------------------------------------------------------------------------
167
168/// SQLite's five storage classes, and nothing else; no driver type reaches the layer above.
169#[derive(Clone, Debug, PartialEq)]
170pub enum Value {
171    Null,
172    Int(i64),
173    Real(f64),
174    Text(String),
175    Blob(Vec<u8>),
176}
177
178impl Value {
179    pub fn as_int(&self) -> Result<i64, DbError> {
180        match self {
181            Value::Int(i) => Ok(*i),
182            other => Err(DbError::new(
183                DbErrorKind::Decode,
184                format!("expected INTEGER, found {other:?}"),
185            )),
186        }
187    }
188    pub fn as_real(&self) -> Result<f64, DbError> {
189        match self {
190            Value::Real(r) => Ok(*r),
191            Value::Int(i) => Ok(*i as f64),
192            other => Err(DbError::new(
193                DbErrorKind::Decode,
194                format!("expected REAL, found {other:?}"),
195            )),
196        }
197    }
198    pub fn as_text(&self) -> Result<&str, DbError> {
199        match self {
200            Value::Text(t) => Ok(t),
201            other => Err(DbError::new(
202                DbErrorKind::Decode,
203                format!("expected TEXT, found {other:?}"),
204            )),
205        }
206    }
207    pub fn as_blob(&self) -> Result<&[u8], DbError> {
208        match self {
209            Value::Blob(b) => Ok(b),
210            other => Err(DbError::new(
211                DbErrorKind::Decode,
212                format!("expected BLOB, found {other:?}"),
213            )),
214        }
215    }
216}
217
218/// A column's declared type. Part of the schema fingerprint, so changing one is a migration.
219#[derive(Clone, Copy, PartialEq, Eq, Debug)]
220pub enum SqlType {
221    Integer,
222    Real,
223    Text,
224    Blob,
225}
226
227impl SqlType {
228    pub fn ddl(self) -> &'static str {
229        match self {
230            SqlType::Integer => "INTEGER",
231            SqlType::Real => "REAL",
232            SqlType::Text => "TEXT",
233            SqlType::Blob => "BLOB",
234        }
235    }
236}
237
238/// One result row, by position.
239pub trait Row {
240    fn len(&self) -> usize;
241    fn get(&self, i: usize) -> Value;
242    fn is_empty(&self) -> bool {
243        self.len() == 0
244    }
245}
246
247impl Row for Vec<Value> {
248    fn len(&self) -> usize {
249        Vec::len(self)
250    }
251    fn get(&self, i: usize) -> Value {
252        self.as_slice().get(i).cloned().unwrap_or(Value::Null)
253    }
254}
255
256// ---------------------------------------------------------------------------
257// The driver interface
258// ---------------------------------------------------------------------------
259
260/// Where the database lives.
261#[derive(Clone, Debug)]
262pub enum Location {
263    Memory,
264    File(PathBuf),
265}
266
267/// A key for an encrypted database. Redacted in Debug and zeroed on drop; where it lives
268/// between launches is the app's business, never this crate's.
269#[derive(Clone)]
270pub struct Secret(String);
271
272impl Secret {
273    pub fn new(key: impl Into<String>) -> Self {
274        Secret(key.into())
275    }
276    #[cfg(feature = "cipher")]
277    pub(crate) fn reveal(&self) -> &str {
278        &self.0
279    }
280}
281
282impl fmt::Debug for Secret {
283    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
284        f.write_str("Secret(…)")
285    }
286}
287
288impl Drop for Secret {
289    fn drop(&mut self) {
290        // Best-effort scrub; the allocation may have been moved by earlier clones.
291        unsafe {
292            // SAFETY: we own the String and overwrite only its initialized bytes in place.
293            for b in self.0.as_bytes_mut() {
294                *b = 0;
295            }
296        }
297    }
298}
299
300/// How to open the database. Built by the driver's own constructors ([`Sqlite::at`] etc.);
301/// public so alternative drivers speak the same vocabulary.
302#[derive(Clone, Debug)]
303pub struct OpenOptions {
304    pub location: Location,
305    /// SQLCipher key; drivers without encryption reject it loudly.
306    pub key: Option<Secret>,
307    /// Journal in WAL mode (files only; ignored in memory). Default true.
308    pub wal: bool,
309    /// Enforce foreign keys. Default true.
310    pub foreign_keys: bool,
311    pub busy_timeout_ms: u32,
312    /// Upgrade a file written by an older SQLCipher generation (PRAGMA cipher_migrate).
313    pub cipher_migrate: bool,
314}
315
316impl OpenOptions {
317    pub fn new(location: Location) -> Self {
318        OpenOptions {
319            location,
320            key: None,
321            wal: true,
322            foreign_keys: true,
323            busy_timeout_ms: 5_000,
324            cipher_migrate: false,
325        }
326    }
327}
328
329/// What a driver can and cannot do, so the container degrades visibly instead of silently.
330#[derive(Clone, Copy, Debug, Default)]
331pub struct Capabilities {
332    /// Survives a relaunch (false for memory stores and the Recorder).
333    pub durable: bool,
334    pub encryption: bool,
335    pub wal: bool,
336    pub full_text_search: bool,
337    pub rtree: bool,
338    /// Another connection's committed writes are detectable (SQLite's `PRAGMA data_version`
339    /// counter), so [`ModelContainer::check_external`] can merge them. The built-in driver
340    /// claims it for file databases on native targets; memory databases (no second connection
341    /// can reach one), the Recorder, and the web engine (its OPFS access is exclusive) do not.
342    pub external_changes: bool,
343    /// The connection has `day_fold` registered (Rust's full-Unicode `to_lowercase` as a
344    /// scalar SQL function), so case-insensitive text predicates compile to exact SQL. The
345    /// built-in native driver registers it at open; without it those predicates take the
346    /// fallback path (SQL for everything else, the folding test re-checked in memory).
347    pub unicode_fold: bool,
348}
349
350/// The engine trait. Object-safe on the connection side, so the container stores
351/// `Box<dyn SqliteConnection>` and never names an engine type.
352pub trait SqliteDriver {
353    type Connection: SqliteConnection;
354    fn open(self) -> Result<Self::Connection, DbError>;
355    fn capabilities(&self) -> Capabilities;
356}
357
358impl SqliteConnection for Box<dyn SqliteConnection> {
359    fn execute(&mut self, sql: &str, params: &[Value]) -> Result<u64, DbError> {
360        (**self).execute(sql, params)
361    }
362    fn query(
363        &mut self,
364        sql: &str,
365        params: &[Value],
366        row: &mut dyn FnMut(&dyn Row),
367    ) -> Result<(), DbError> {
368        (**self).query(sql, params, row)
369    }
370    fn execute_batch(&mut self, sql: &str) -> Result<(), DbError> {
371        (**self).execute_batch(sql)
372    }
373    fn query_named(
374        &mut self,
375        sql: &str,
376        params: &[Value],
377        row: &mut dyn FnMut(&[String], &dyn Row),
378    ) -> Result<(), DbError> {
379        (**self).query_named(sql, params, row)
380    }
381}
382
383/// One open connection. Everything above speaks plain SQL and [`Value`]s through it.
384pub trait SqliteConnection: 'static {
385    fn execute(&mut self, sql: &str, params: &[Value]) -> Result<u64, DbError>;
386    fn query(
387        &mut self,
388        sql: &str,
389        params: &[Value],
390        row: &mut dyn FnMut(&dyn Row),
391    ) -> Result<(), DbError>;
392    fn begin(&mut self) -> Result<(), DbError> {
393        self.execute("BEGIN", &[]).map(|_| ())
394    }
395    fn commit(&mut self) -> Result<(), DbError> {
396        self.execute("COMMIT", &[]).map(|_| ())
397    }
398    fn rollback(&mut self) -> Result<(), DbError> {
399        self.execute("ROLLBACK", &[]).map(|_| ())
400    }
401    /// Several statements in one string, no parameters: a DDL script, a migration step
402    /// (day-lite's storage speaks this). The default runs the string as one statement;
403    /// drivers whose engine executes scripts override it (the built-in native driver does).
404    fn execute_batch(&mut self, sql: &str) -> Result<(), DbError> {
405        self.execute(sql, &[]).map(|_| ())
406    }
407    /// [`SqliteConnection::query`], with the result's column names alongside each row, for
408    /// callers that surface rows as named objects (day-lite's JS bridge). A driver that
409    /// cannot name columns refuses rather than guessing.
410    fn query_named(
411        &mut self,
412        sql: &str,
413        params: &[Value],
414        row: &mut dyn FnMut(&[String], &dyn Row),
415    ) -> Result<(), DbError> {
416        let _ = (sql, params, row);
417        Err(DbError::new(
418            DbErrorKind::Unsupported,
419            "this driver does not report column names",
420        ))
421    }
422}
423
424// ---------------------------------------------------------------------------
425// The Recorder: the headless fake
426// ---------------------------------------------------------------------------
427
428/// A driver that answers from fixtures and records every statement: the piece that keeps
429/// persistence assertable with no database on disk. `let (driver, log) = Recorder::new();`
430///
431/// Fixtures answer by table, not by statement: any `SELECT … FROM <table>` serves every
432/// fixture row registered for it, whatever the `WHERE` clause says. Faulting paths keep only
433/// the keys they asked for, so `get` and `ensure_resident` behave; a query against the
434/// Recorder answers with all fixture keys, so assert the SQL it recorded, and use
435/// `Sqlite::memory()` where predicate results themselves are under test.
436pub struct Recorder {
437    state: Rc<RecorderState>,
438}
439
440struct RecorderState {
441    log: RefCell<Vec<(String, Vec<Value>)>>,
442    /// table name → rows served for a `SELECT … FROM <table>`.
443    fixtures: RefCell<HashMap<String, Vec<Vec<Value>>>>,
444}
445
446/// The recorded statement log, shared with the test that holds it.
447#[derive(Clone)]
448pub struct RecorderLog {
449    state: Rc<RecorderState>,
450}
451
452impl RecorderLog {
453    /// Every statement so far, SQL text only.
454    pub fn sql(&self) -> Vec<String> {
455        self.state
456            .log
457            .borrow()
458            .iter()
459            .map(|(s, _)| s.clone())
460            .collect()
461    }
462    /// Statements with their bound parameters.
463    pub fn entries(&self) -> Vec<(String, Vec<Value>)> {
464        self.state.log.borrow().clone()
465    }
466    pub fn clear(&self) {
467        self.state.log.borrow_mut().clear();
468    }
469}
470
471impl Recorder {
472    pub fn new() -> (Recorder, RecorderLog) {
473        let state = Rc::new(RecorderState {
474            log: RefCell::new(Vec::new()),
475            fixtures: RefCell::new(HashMap::new()),
476        });
477        (
478            Recorder {
479                state: state.clone(),
480            },
481            RecorderLog { state },
482        )
483    }
484
485    /// Rows a table's `SELECT` will answer with.
486    pub fn with_table(self, table: &str, rows: Vec<Vec<Value>>) -> Self {
487        self.state.fixtures.borrow_mut().insert(table.into(), rows);
488        self
489    }
490}
491
492pub struct RecorderConn {
493    state: Rc<RecorderState>,
494}
495
496impl SqliteDriver for Recorder {
497    type Connection = RecorderConn;
498    fn open(self) -> Result<RecorderConn, DbError> {
499        Ok(RecorderConn { state: self.state })
500    }
501    fn capabilities(&self) -> Capabilities {
502        Capabilities {
503            durable: false,
504            wal: false,
505            // The fake answers everything: an FTS/spatial model must open against fixtures
506            // (its reads just come back empty unless a fixture answers them), and folded
507            // predicates compile as if day_fold existed; the SQL is recorded, never run.
508            full_text_search: true,
509            rtree: true,
510            unicode_fold: true,
511            ..Default::default()
512        }
513    }
514}
515
516impl SqliteConnection for RecorderConn {
517    fn execute(&mut self, sql: &str, params: &[Value]) -> Result<u64, DbError> {
518        self.state
519            .log
520            .borrow_mut()
521            .push((sql.to_string(), params.to_vec()));
522        Ok(0)
523    }
524    fn query(
525        &mut self,
526        sql: &str,
527        params: &[Value],
528        row: &mut dyn FnMut(&dyn Row),
529    ) -> Result<(), DbError> {
530        self.state
531            .log
532            .borrow_mut()
533            .push((sql.to_string(), params.to_vec()));
534        // Serve a fixture when the statement reads `FROM` a table one was registered for.
535        if let Some(from) = sql.split(" FROM ").nth(1) {
536            let table = from.split_whitespace().next().unwrap_or("");
537            if let Some(rows) = self.state.fixtures.borrow().get(table) {
538                for r in rows {
539                    row(r);
540                }
541            }
542        }
543        Ok(())
544    }
545}
546
547// ---------------------------------------------------------------------------
548// Column values and codecs (docs/persistence.md)
549// ---------------------------------------------------------------------------
550
551/// A Rust type that knows how to be a column. One impl per type: its canonical form.
552pub trait ColumnValue: Sized + 'static {
553    /// The declared column type. Part of the schema fingerprint, so changing it is a
554    /// migration, never a surprise.
555    const SQL_TYPE: SqlType;
556    fn to_sqlite_value(&self) -> Value;
557    fn from_sqlite_value(v: Value) -> Result<Self, DbError>;
558}
559
560/// A named alternative representation for `T`, serde's `#[serde(with = …)]` idiom.
561/// Implement on a unit struct; select it per field with `#[model(with = …)]`.
562pub trait ValueCodec<T>: 'static {
563    const SQL_TYPE: SqlType;
564    fn to_sqlite_value(v: &T) -> Value;
565    fn from_sqlite_value(v: Value) -> Result<T, DbError>;
566}
567
568macro_rules! int_column {
569    ($($t:ty),*) => {$(
570        impl ColumnValue for $t {
571            const SQL_TYPE: SqlType = SqlType::Integer;
572            fn to_sqlite_value(&self) -> Value {
573                Value::Int(*self as i64)
574            }
575            fn from_sqlite_value(v: Value) -> Result<Self, DbError> {
576                Ok(v.as_int()? as $t)
577            }
578        }
579    )*};
580}
581int_column!(i8, i16, i32, i64, u8, u16, u32, u64, usize, isize);
582
583impl ColumnValue for bool {
584    const SQL_TYPE: SqlType = SqlType::Integer;
585    fn to_sqlite_value(&self) -> Value {
586        Value::Int(*self as i64)
587    }
588    fn from_sqlite_value(v: Value) -> Result<Self, DbError> {
589        Ok(v.as_int()? != 0)
590    }
591}
592
593impl ColumnValue for f64 {
594    const SQL_TYPE: SqlType = SqlType::Real;
595    fn to_sqlite_value(&self) -> Value {
596        Value::Real(*self)
597    }
598    fn from_sqlite_value(v: Value) -> Result<Self, DbError> {
599        v.as_real()
600    }
601}
602
603impl ColumnValue for f32 {
604    const SQL_TYPE: SqlType = SqlType::Real;
605    fn to_sqlite_value(&self) -> Value {
606        Value::Real(*self as f64)
607    }
608    fn from_sqlite_value(v: Value) -> Result<Self, DbError> {
609        Ok(v.as_real()? as f32)
610    }
611}
612
613impl ColumnValue for String {
614    const SQL_TYPE: SqlType = SqlType::Text;
615    fn to_sqlite_value(&self) -> Value {
616        Value::Text(self.clone())
617    }
618    fn from_sqlite_value(v: Value) -> Result<Self, DbError> {
619        Ok(v.as_text()?.to_string())
620    }
621}
622
623impl ColumnValue for Vec<u8> {
624    const SQL_TYPE: SqlType = SqlType::Blob;
625    fn to_sqlite_value(&self) -> Value {
626        Value::Blob(self.clone())
627    }
628    fn from_sqlite_value(v: Value) -> Result<Self, DbError> {
629        Ok(v.as_blob()?.to_vec())
630    }
631}
632
633/// A Uuid is a 16-byte `BLOB`: compact, indexable, and readable by any tool that knows the
634/// convention. (`day_model::Uuid` is `uuid::Uuid`, so no second dependency edge exists.)
635impl ColumnValue for day_model::Uuid {
636    const SQL_TYPE: SqlType = SqlType::Blob;
637    fn to_sqlite_value(&self) -> Value {
638        Value::Blob(self.as_bytes().to_vec())
639    }
640    fn from_sqlite_value(v: Value) -> Result<Self, DbError> {
641        day_model::Uuid::from_slice(v.as_blob()?)
642            .map_err(|e| DbError::new(DbErrorKind::Decode, format!("uuid: {e}")))
643    }
644}
645
646/// A key handle, as the bound parameter its stored form takes: `INTEGER` for integer keys,
647/// a 16-byte `BLOB` for Uuid keys, `TEXT` for string keys. `Pair` keys (join rows) bind
648/// through their own two-column clause, never through this.
649fn key_param(handle: u64) -> Value {
650    match Key::of_handle(handle) {
651        Some(Key::U64(k)) => Value::Int(k as i64),
652        Some(Key::Uuid(u)) => Value::Blob(day_model::Uuid::from_u128(u).as_bytes().to_vec()),
653        Some(Key::Str(s)) => Value::Text(s.to_string()),
654        Some(Key::Pair(..)) | None => Value::Null,
655    }
656}
657
658/// A stored key value, back as its path handle. `None` for shapes no key takes (a negative
659/// integer, a blob that is not 16 bytes); the caller treats those rows as unaddressable.
660fn value_to_handle(v: &Value) -> Option<u64> {
661    match v {
662        Value::Int(i) if *i >= 0 => Some(Key::U64(*i as u64).handle()),
663        Value::Blob(b) if b.len() == 16 => day_model::Uuid::from_slice(b)
664            .ok()
665            .map(|u| Key::Uuid(u.as_u128()).handle()),
666        Value::Text(t) => Some(Key::Str(t.as_str().into()).handle()),
667        _ => None,
668    }
669}
670
671/// `NULL` belongs to the framework: `Option` wraps any column type, encoding is called only on
672/// present values, and a NULL decodes to `None`, so an impl never sees `Null` and cannot
673/// disagree about it.
674impl<T: ColumnValue> ColumnValue for Option<T> {
675    const SQL_TYPE: SqlType = T::SQL_TYPE;
676    fn to_sqlite_value(&self) -> Value {
677        match self {
678            Some(v) => v.to_sqlite_value(),
679            None => Value::Null,
680        }
681    }
682    fn from_sqlite_value(v: Value) -> Result<Self, DbError> {
683        match v {
684            Value::Null => Ok(None),
685            v => Ok(Some(T::from_sqlite_value(v)?)),
686        }
687    }
688}
689
690/// The serde codec: any `Serialize + Deserialize` type as a `TEXT` column SQLite's own
691/// `json_*` functions can reach. `#[model(json)]` is sugar for `#[model(with = Json)]`.
692pub struct Json;
693
694impl<T> ValueCodec<T> for Json
695where
696    T: serde::Serialize + serde::de::DeserializeOwned + 'static,
697{
698    const SQL_TYPE: SqlType = SqlType::Text;
699    fn to_sqlite_value(v: &T) -> Value {
700        match serde_json::to_string(v) {
701            Ok(s) => Value::Text(s),
702            // Serialization of an in-memory value failing is a bug in the type's serde impl;
703            // surface it as a NULL rather than a panic, and the decode side will report it.
704            Err(_) => Value::Null,
705        }
706    }
707    fn from_sqlite_value(v: Value) -> Result<T, DbError> {
708        serde_json::from_str(v.as_text()?)
709            .map_err(|e| DbError::new(DbErrorKind::Decode, format!("json: {e}")))
710    }
711}
712
713// ---------------------------------------------------------------------------
714// The Model trait: what #[derive(Model)] implements
715// ---------------------------------------------------------------------------
716
717/// One column of a model's table, as the derive declares it. `field` is the struct field the
718/// column stores: the change log speaks field names, the SQL speaks column names, and this is
719/// where the two meet (they differ only under `#[model(column = "…")]`).
720#[derive(Clone, Copy, Debug)]
721pub struct ColumnDef {
722    pub name: &'static str,
723    pub field: &'static str,
724    pub sql: SqlType,
725    pub not_null: bool,
726    pub unique: bool,
727    pub indexed: bool,
728}
729
730/// The column pair a `#[model(spatial(lat = …, lon = …))]` declaration names.
731#[derive(Clone, Copy, Debug, PartialEq, Eq)]
732pub struct SpatialCols {
733    pub lat: &'static str,
734    pub lon: &'static str,
735}
736
737/// One `#[model(link(…))]` as the derive emits it: `owner.local = target.remote` is the join.
738#[derive(Clone, Copy, Debug)]
739pub struct LinkDef {
740    /// The marker field the link was declared on: the name `Owner::field()` answers to.
741    pub field: &'static str,
742    /// The owner's column holding the value.
743    pub local: &'static str,
744    /// The target's (qualified) table.
745    pub target_table: &'static str,
746    /// The target's column the value names.
747    pub remote: &'static str,
748}
749
750/// The marker a `#[model(link(…))]` field carries. It has neither a column nor state; the
751/// type is what names the far model for the derive.
752pub struct Linked<M: ?Sized> {
753    _m: std::marker::PhantomData<fn() -> M>,
754}
755
756impl<M: ?Sized> Clone for Linked<M> {
757    fn clone(&self) -> Self {
758        *self
759    }
760}
761impl<M: ?Sized> Copy for Linked<M> {}
762impl<M: ?Sized> Default for Linked<M> {
763    fn default() -> Self {
764        Linked {
765            _m: std::marker::PhantomData,
766        }
767    }
768}
769impl<M: ?Sized> PartialEq for Linked<M> {
770    fn eq(&self, _: &Self) -> bool {
771        true
772    }
773}
774impl<M: ?Sized> std::fmt::Debug for Linked<M> {
775    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
776        f.write_str("Linked")
777    }
778}
779
780/// A wired link, as the SQL compiler and the query watcher see it.
781#[derive(Clone, Copy, Debug)]
782pub(crate) struct LinkInfo {
783    pub(crate) owner_table: &'static str,
784    pub(crate) field: &'static str,
785    pub(crate) local: &'static str,
786    pub(crate) target_table: &'static str,
787    pub(crate) remote: &'static str,
788}
789
790/// A persistable model: an [`Identified`] observable struct with a schema half. Implemented by
791/// `#[derive(Model)]`; the container consumes it.
792pub trait Model: Identified + day_model::ApplyField + Clone + 'static {
793    const TABLE: &'static str;
794    /// The key column's name (the `#[model(id)]` field). Also the first entry of `COLUMNS`.
795    const KEY: &'static str;
796    const COLUMNS: &'static [ColumnDef];
797    /// Composite indexes from struct-level `#[model(index("a", "b"))]`.
798    const COMPOSITE_INDEXES: &'static [&'static [&'static str]] = &[];
799    /// Full-text-indexed columns from struct-level `#[model(fts("a", "b"))]`: an
800    /// external-content FTS5 shadow table plus sync triggers, generated at open.
801    const FTS_COLUMNS: &'static [&'static str] = &[];
802    /// The FTS5 tokenizer, from `#[model(fts(…, tokenize = "…"))]`, e.g.
803    /// `"unicode61 remove_diacritics 2"` for diacritics-insensitive search. `None` keeps
804    /// FTS5's default. Part of the schema fingerprint, so changing it rebuilds the shadow.
805    const FTS_TOKENIZE: Option<&'static str> = None;
806    /// The R*Tree pair from struct-level `#[model(spatial(lat = "…", lon = "…"))]`.
807    const SPATIAL: Option<SpatialCols> = None;
808    /// The key column's SQL shape: what a `One<Self>` foreign-key column stores.
809    const KEY_SQL: SqlType = SqlType::Integer;
810    /// Relations declared on this model's `Many` fields (`#[model(relation(…))]`).
811    const RELATIONS: &'static [RelationDef] = &[];
812    /// Relations by value (`#[model(link(…))]`): rows of another model whose `remote` column
813    /// equals this row's `local` column, with no foreign key: the shape that reaches across an
814    /// attached database (see [`ModelContainer::attach_database`]).
815    const LINKS: &'static [LinkDef] = &[];
816    /// Declared `external = "alias"`: the table belongs to a database attached under that alias
817    /// and managed elsewhere. The container creates, migrates, and fingerprints nothing for
818    /// it, and treats it as read-only.
819    const EXTERNAL: bool = false;
820    /// One [`Value`] per column, in `COLUMNS` order.
821    fn to_row(&self) -> Vec<Value>;
822    fn from_row(row: &dyn Row) -> Result<Self, DbError>;
823    /// Each column's Rust-default value: what an added column backfills with.
824    fn default_row() -> Vec<Value>;
825    /// Wire this model's declared relations. Generated; the default declares none.
826    fn wire(reg: &mut Registrar<'_>) {
827        let _ = reg;
828    }
829}
830
831/// The declared schema's fingerprint: table, columns, types, flags, indexes. Equal fingerprints
832/// open instantly; a difference migrates or refuses, never silently.
833pub fn model_fingerprint<M: Model>() -> u64 {
834    let mut h: u64 = 0xcbf2_9ce4_8422_2325;
835    let mut eat = |bytes: &[u8]| {
836        for b in bytes {
837            h ^= *b as u64;
838            h = h.wrapping_mul(0x1000_0000_01b3);
839        }
840    };
841    eat(M::TABLE.as_bytes());
842    eat(M::KEY.as_bytes());
843    for c in M::COLUMNS {
844        eat(c.name.as_bytes());
845        eat(c.sql.ddl().as_bytes());
846        eat(&[c.not_null as u8, c.unique as u8, c.indexed as u8]);
847    }
848    for idx in M::COMPOSITE_INDEXES {
849        for c in *idx {
850            eat(c.as_bytes());
851        }
852        eat(b"|");
853    }
854    for c in M::FTS_COLUMNS {
855        eat(b"fts:");
856        eat(c.as_bytes());
857    }
858    if !M::FTS_COLUMNS.is_empty()
859        && M::COLUMNS
860            .iter()
861            .any(|c| c.name == M::KEY && c.sql != SqlType::Integer)
862    {
863        eat(b"wide-fts-key-map-v1");
864    }
865    if let Some(t) = M::FTS_TOKENIZE {
866        eat(b"tok:");
867        eat(t.as_bytes());
868    }
869    if let Some(s) = M::SPATIAL {
870        eat(b"geo:");
871        eat(s.lat.as_bytes());
872        eat(s.lon.as_bytes());
873    }
874    h
875}
876
877// ---------------------------------------------------------------------------
878// Schema sets and migrations
879// ---------------------------------------------------------------------------
880
881/// The set of models a container manages; build with [`schema!`].
882#[derive(Default)]
883pub struct Schema {
884    installers: Vec<Installer>,
885    /// Run after every table is attached, because relation wiring needs both ends present.
886    wirers: Vec<Installer>,
887    /// Foreign-key clauses each declared relation contributes to its target's table.
888    fk_specs: Vec<FkSpec>,
889}
890
891type Installer = Box<dyn FnOnce(&ModelContainer) -> Result<(), DbError>>;
892/// Decode raw rows into the cache silently, answering their handles.
893type AbsorbFn = Rc<dyn Fn(Vec<Vec<Value>>) -> Result<Vec<u64>, DbError>>;
894/// Diff raw rows (selected by the resident keys) against the cache: per-field announcements
895/// authored [`ModelContainer::EXTERNAL_AUTHOR`], resident rows missing from the input deleted
896/// the same way. Returns whether anything differed.
897type RefreshFn = Rc<dyn Fn(Vec<Vec<Value>>) -> Result<bool, DbError>>;
898/// A `WHERE` clause plus its parameters, addressing one row by handle.
899type KeyWhere = Rc<dyn Fn(u64) -> (String, Vec<Value>)>;
900/// A `WHERE` clause plus its parameters, addressing a set of rows by handle.
901type KeysWhere = Rc<dyn Fn(&[u64]) -> (String, Vec<Value>)>;
902/// Evict up to N clean rows from an ordered candidate list, answering how many left.
903type EvictFn = Rc<dyn Fn(&[u64], usize) -> usize>;
904
905/// One foreign-key clause, resolved from a `RelationDef` at `Schema::with` time: the child's
906/// column carries `REFERENCES parent(key) ON DELETE …` in its generated DDL.
907#[derive(Clone, Copy, Debug)]
908struct FkSpec {
909    child_table: &'static str,
910    child_field: &'static str,
911    parent_table: &'static str,
912    parent_key: &'static str,
913    rule: DeleteRule,
914}
915
916impl Schema {
917    pub fn new() -> Self {
918        Self::default()
919    }
920    pub fn with<M: Model>(mut self) -> Self {
921        for def in M::RELATIONS {
922            if def.join.is_none() {
923                self.fk_specs.push(FkSpec {
924                    child_table: def.target_table,
925                    child_field: def.inverse,
926                    parent_table: M::TABLE,
927                    parent_key: M::KEY,
928                    rule: def.delete,
929                });
930            }
931        }
932        self.installers.push(Box::new(|c| c.attach::<M>()));
933        self.wirers.push(Box::new(|c| {
934            let mut reg = Registrar {
935                container: c,
936                error: None,
937            };
938            M::wire(&mut reg);
939            match reg.error {
940                Some(e) => Err(e),
941                None => Ok(()),
942            }
943        }));
944        self
945    }
946}
947
948/// `schema![Trip, Lodging]`: the models a container manages.
949#[macro_export]
950macro_rules! schema {
951    ($($m:ty),+ $(,)?) => {{
952        let s = $crate::Schema::new();
953        $(let s = s.with::<$m>();)+
954        s
955    }};
956}
957
958/// Staged migrations: anything with intent behind it (a rename, a split) gets a stage the app
959/// writes; each stage runs in its own transaction against the raw connection, and versions only
960/// go up. Lightweight migration (added/dropped columns and indexes) runs afterward, inferred
961/// from the schema fingerprint.
962#[derive(Default)]
963pub struct MigrationPlan {
964    stages: Vec<Stage>,
965}
966
967type StageFn = Box<dyn FnOnce(&mut dyn SqliteConnection) -> Result<(), DbError>>;
968
969struct Stage {
970    from: u32,
971    to: u32,
972    run: StageFn,
973}
974
975impl MigrationPlan {
976    pub fn new() -> Self {
977        Self::default()
978    }
979    /// A hand-written stage taking the database from `from` to `to`. Stages run in ascending
980    /// order from the file's current version; a gap is an error at open.
981    pub fn custom(
982        mut self,
983        from: u32,
984        to: u32,
985        f: impl FnOnce(&mut dyn SqliteConnection) -> Result<(), DbError> + 'static,
986    ) -> Self {
987        self.stages.push(Stage {
988            from,
989            to,
990            run: Box::new(f),
991        });
992        self
993    }
994    fn target_version(&self) -> u32 {
995        self.stages.iter().map(|s| s.to).max().unwrap_or(0)
996    }
997}
998
999// ---------------------------------------------------------------------------
1000// Dirty tracking: the fold, applied live
1001// ---------------------------------------------------------------------------
1002
1003/// What one row needs at the next flush. The merge rules are the change-log fold: same-row
1004/// changes coalesce, an INSERT absorbs later field writes, a DELETE absorbs everything.
1005#[derive(Clone, Debug, PartialEq)]
1006pub(crate) enum DirtyRow {
1007    Insert,
1008    Update(Vec<&'static str>),
1009    Delete,
1010}
1011
1012#[derive(Clone, Default)]
1013struct DirtyState {
1014    /// (store, key) → pending statement kind, in first-touch order.
1015    rows: HashMap<(u64, u64), DirtyRow>,
1016    order: Vec<(u64, u64)>,
1017    /// Stores whose whole value was rewritten (a wholesale `Store::update`), flushed by
1018    /// upserting every resident row. With a lazy cache no "delete the rest" is possible (the
1019    /// rest was never loaded), so wholesale rewrites are a resync of the working set only.
1020    full: Vec<u64>,
1021}
1022
1023impl DirtyState {
1024    fn merge(&mut self, newer: Self) {
1025        for store in newer.full {
1026            if !self.full.contains(&store) {
1027                self.full.push(store);
1028            }
1029        }
1030        for id in newer.order {
1031            let next = newer.rows[&id].clone();
1032            if !self.rows.contains_key(&id) {
1033                self.order.push(id);
1034            }
1035            match (self.rows.get_mut(&id), next) {
1036                (Some(DirtyRow::Update(old)), DirtyRow::Update(cols)) => {
1037                    for col in cols {
1038                        if !old.contains(&col) {
1039                            old.push(col);
1040                        }
1041                    }
1042                }
1043                (Some(DirtyRow::Insert | DirtyRow::Delete), DirtyRow::Update(_)) => {}
1044                (_, next) => {
1045                    self.rows.insert(id, next);
1046                }
1047            }
1048        }
1049    }
1050
1051    fn is_empty(&self) -> bool {
1052        self.rows.is_empty() && self.full.is_empty()
1053    }
1054
1055    fn note(&mut self, change: &day_model::Change, known_store: impl Fn(u64) -> bool) {
1056        let Some(&store) = change.components.first() else {
1057            return;
1058        };
1059        if !known_store(store) {
1060            return;
1061        }
1062        let Some(&key) = change.components.get(1) else {
1063            // A store-level change: the whole value may have been replaced.
1064            if !self.full.contains(&store) {
1065                self.full.push(store);
1066            }
1067            return;
1068        };
1069        if key == day_model::STRUCTURE {
1070            return; // the shape path is for the UI; the row paths carry the work
1071        }
1072        let id = (store, key);
1073        if !self.rows.contains_key(&id) {
1074            self.order.push(id);
1075        }
1076        let slot = self.rows.entry(id).or_insert(DirtyRow::Update(Vec::new()));
1077        match (change.op, &mut *slot) {
1078            (Op::Delete, _) => *slot = DirtyRow::Delete,
1079            (Op::Insert, _) => *slot = DirtyRow::Insert,
1080            (Op::Set, DirtyRow::Insert) | (Op::Set, DirtyRow::Delete) => {}
1081            (Op::Set, DirtyRow::Update(columns)) => {
1082                if change.components.len() >= 3 && !columns.contains(&change.label) {
1083                    columns.push(change.label);
1084                }
1085            }
1086            (Op::Move, _) => {}
1087        }
1088    }
1089}
1090
1091// ---------------------------------------------------------------------------
1092// The container
1093// ---------------------------------------------------------------------------
1094
1095/// Everything the container knows how to do for one attached model type, monomorphized at
1096/// [`Schema::with`] and stored type-erased. Join tables (relations.rs) hand-build one over
1097/// their pair-keyed membership cache, which is why keys are plural and clause-shaped here.
1098pub(crate) struct TableHooks {
1099    pub(crate) table: &'static str,
1100    /// The key column(s), in order: the key SELECT list, the upsert's conflict target, and
1101    /// what its DO UPDATE leaves alone. One entry everywhere but join tables.
1102    pub(crate) key_cols: Vec<String>,
1103    /// `WHERE` clause + params addressing one row by its key handle.
1104    pub(crate) key_where: KeyWhere,
1105    pub(crate) columns: Vec<String>,
1106    /// Same order as `columns`; what a change's label matches against.
1107    pub(crate) fields: Vec<String>,
1108    /// The FTS5 shadow's table name, when the model declares `fts(…)`.
1109    pub(crate) fts: Option<String>,
1110    pub(crate) fts_key: &'static str,
1111    /// The R*Tree shadow: (lat column, lon column, shadow table name).
1112    pub(crate) spatial: Option<(String, String, String)>,
1113    /// Current row values by key, read from the cache at flush time; the change log carries
1114    /// which rows and columns moved, never their contents.
1115    pub(crate) row_for: Rc<dyn Fn(u64) -> Option<Vec<Value>>>,
1116    /// Every (key, row) currently resident, for wholesale resyncs.
1117    pub(crate) all_rows: Rc<dyn Fn() -> Vec<(u64, Vec<Value>)>>,
1118    /// The resident keys, in cache (≈ fault) order: what eviction walks.
1119    pub(crate) resident_keys: Rc<dyn Fn() -> Vec<u64>>,
1120    /// The resident count, O(1): the fault path's eviction gate.
1121    pub(crate) resident_len: Rc<dyn Fn() -> usize>,
1122    pub(crate) is_resident: Rc<dyn Fn(u64) -> bool>,
1123    /// Decode raw rows into the cache silently (a fault landing).
1124    pub(crate) absorb: AbsorbFn,
1125    /// Diff raw rows against the resident set, announcing as the external author.
1126    pub(crate) refresh: RefreshFn,
1127    /// Silently drop up to `want` clean rows from the cache, taking candidates in order and
1128    /// skipping anything observed; answers how many left. One retain over the store, so an
1129    /// eviction pass costs O(cache), not O(cache × evicted). (Dirtiness is the container's
1130    /// knowledge, checked before this is called.)
1131    pub(crate) evict: EvictFn,
1132    #[cfg(not(target_arch = "wasm32"))]
1133    pub(crate) dispose_cache: Rc<dyn Fn()>,
1134    /// Bring this store under an undo history; captured here because the model type is known
1135    /// only at attach time.
1136    pub(crate) watch_undo: Rc<dyn Fn(&day_model::UndoStack)>,
1137}
1138
1139pub(crate) struct ContainerInner {
1140    conn: RefCell<Box<dyn SqliteConnection>>,
1141    caps: Capabilities,
1142    /// store root id → hooks.
1143    tables: RefCell<HashMap<u64, TableHooks>>,
1144    /// model TypeId → the `Store<Keyed<M>>` handle, boxed.
1145    stores: RefCell<HashMap<TypeId, Box<dyn Any>>>,
1146    dirty: RefCell<DirtyState>,
1147    /// Live query result sets, marked stale from the change sink. Weak: the app's `Query`
1148    /// handles own the state; dead entries are pruned on dispatch.
1149    queries: RefCell<Vec<std::rc::Weak<QueryState>>>,
1150    /// The engine's cross-connection change counter as of the last look (`PRAGMA
1151    /// data_version`; it moves only when another connection commits to the file). `None`
1152    /// where the driver reports no external-change detection.
1153    data_version: Cell<Option<i64>>,
1154    /// Foreign-key clauses relations contribute to their targets' tables, set before attach.
1155    fk_specs: RefCell<Vec<FkSpec>>,
1156    /// The wired relations, maintained from the change sink and read by `RelationRef`s.
1157    pub(crate) relations: RefCell<Vec<Rc<relations::ToOneRel>>>,
1158    /// The wired many-to-manys, each over its own membership cache.
1159    pub(crate) joins: RefCell<Vec<Rc<relations::JoinRel>>>,
1160    /// The declared value links (`#[model(link(…))]`), from every attached model.
1161    pub(crate) links: RefCell<Vec<LinkInfo>>,
1162    /// The databases `attach_database` holds open, by alias.
1163    attached: RefCell<Vec<String>>,
1164    sink: Cell<Option<day_model::ChangeSinkId>>,
1165    autosave: Cell<bool>,
1166    /// An outer worker transaction owns commit/rollback; inner model saves only execute SQL.
1167    worker_transaction: Cell<bool>,
1168    /// Soft per-table bound on resident rows. Dirty and observed rows never evict, so the
1169    /// working set can exceed it; everything else does not.
1170    cache_limit: Cell<usize>,
1171    /// Retry eviction after growth when dirty/observed rows prevent reaching the limit.
1172    eviction_retry: RefCell<HashMap<u64, usize>>,
1173    /// The last autosave failure, observable by the UI (`when(container.last_error()…)`).
1174    pub(crate) error: day_reactive::Signal<Option<String>>,
1175    /// Guards re-entrant flushes (a turn-end firing during an explicit save).
1176    flushing: Cell<bool>,
1177}
1178
1179/// An open database and the working-set caches over it. Clone is shallow: clones share the
1180/// connection and the dirty state.
1181#[derive(Clone)]
1182pub struct ModelContainer {
1183    pub(crate) inner: Rc<ContainerInner>,
1184}
1185
1186/// The default per-table bound on resident rows ([`ModelContainer::set_cache_limit`]).
1187pub const DEFAULT_CACHE_LIMIT: usize = 8_192;
1188
1189impl ModelContainer {
1190    /// Open through `driver`, migrate, and attach every model in `schema`. Attaching creates
1191    /// or migrates the table and nothing more: no rows load, so open cost does not grow with
1192    /// the file. Autosave is on: any turn that touched a store flushes at its end.
1193    pub fn open<D: SqliteDriver>(driver: D, schema: Schema) -> Result<ModelContainer, DbError>
1194    where
1195        D::Connection: 'static,
1196    {
1197        Self::open_with(driver, schema, MigrationPlan::new())
1198    }
1199
1200    /// [`ModelContainer::open`], with hand-written migration stages that run first.
1201    pub fn open_with<D: SqliteDriver>(
1202        driver: D,
1203        schema: Schema,
1204        plan: MigrationPlan,
1205    ) -> Result<ModelContainer, DbError>
1206    where
1207        D::Connection: 'static,
1208    {
1209        let caps = driver.capabilities();
1210        let conn: Box<dyn SqliteConnection> = Box::new(driver.open()?);
1211        let error = day_reactive::Scope::detached().enter(|| day_reactive::Signal::new(None));
1212        let container = ModelContainer {
1213            inner: Rc::new(ContainerInner {
1214                conn: RefCell::new(conn),
1215                caps,
1216                tables: RefCell::new(HashMap::new()),
1217                stores: RefCell::new(HashMap::new()),
1218                dirty: RefCell::new(DirtyState::default()),
1219                queries: RefCell::new(Vec::new()),
1220                data_version: Cell::new(None),
1221                fk_specs: RefCell::new(Vec::new()),
1222                relations: RefCell::new(Vec::new()),
1223                joins: RefCell::new(Vec::new()),
1224                links: RefCell::new(Vec::new()),
1225                attached: RefCell::new(Vec::new()),
1226                sink: Cell::new(None),
1227                autosave: Cell::new(true),
1228                worker_transaction: Cell::new(false),
1229                cache_limit: Cell::new(DEFAULT_CACHE_LIMIT),
1230                eviction_retry: RefCell::new(HashMap::new()),
1231                error,
1232                flushing: Cell::new(false),
1233            }),
1234        };
1235
1236        container.ensure_schema_table()?;
1237        container.run_stages(plan)?;
1238        let Schema {
1239            installers,
1240            wirers,
1241            fk_specs,
1242        } = schema;
1243        *container.inner.fk_specs.borrow_mut() = fk_specs;
1244        for install in installers {
1245            install(&container)?;
1246        }
1247        // Relations wire once every table is attached (both ends exist), and only then does
1248        // the sink go live.
1249        for wire in wirers {
1250            wire(&container)?;
1251        }
1252        relations::register_container(&container.inner);
1253        container.install_sink();
1254        container.install_autosave();
1255        if caps.external_changes {
1256            container
1257                .inner
1258                .data_version
1259                .set(container.file_data_version()?);
1260        }
1261        Ok(container)
1262    }
1263
1264    /// The author tag on changes [`ModelContainer::check_external`] merges in: the database's
1265    /// own contents arriving, distinguishable by every change consumer and never persisted
1266    /// back. Reserved: an app writing stores under this tag would have its writes dropped by
1267    /// the autosave fold.
1268    pub const EXTERNAL_AUTHOR: &'static str = "database";
1269
1270    /// The working-set cache for `M`, an ordinary day-model store holding the rows currently
1271    /// resident and not the table: its `keys()` are whatever happens to be faulted in. Bindings
1272    /// and accessors work on it unchanged; enumerate rows through a [`ModelContainer::query`],
1273    /// never through the cache. Panics only if `M` was not in the container's `schema!`,
1274    /// which is a wiring bug worth stopping on.
1275    pub fn cache<M: Model>(&self) -> Store<Keyed<M>> {
1276        let stores = self.inner.stores.borrow();
1277        let any = stores
1278            .get(&TypeId::of::<M>())
1279            .unwrap_or_else(|| panic!("model `{}` is not in this container's schema!", M::TABLE));
1280        *any.downcast_ref::<Store<Keyed<M>>>()
1281            .expect("store map holds the exact type it was keyed by")
1282    }
1283
1284    /// What the driver can and cannot do.
1285    pub fn capabilities(&self) -> Capabilities {
1286        self.inner.caps
1287    }
1288
1289    /// Autosave on/off (default on). Off, changes accumulate until [`ModelContainer::save`],
1290    /// and live queries answer from the last save, since only the file can answer them.
1291    pub fn set_autosave(&self, on: bool) {
1292        self.inner.autosave.set(on);
1293    }
1294
1295    /// The soft per-table bound on resident rows (default [`DEFAULT_CACHE_LIMIT`]). Dirty
1296    /// rows and rows something observes never evict; beyond that, faulting past the limit
1297    /// releases the oldest resident rows. `usize::MAX` disables eviction. Lowering the limit
1298    /// enforces it immediately.
1299    pub fn set_cache_limit(&self, rows: usize) {
1300        self.inner.cache_limit.set(rows.max(1));
1301        let store_ids: Vec<u64> = self.inner.tables.borrow().keys().copied().collect();
1302        for id in store_ids {
1303            self.enforce_cache_limit(id, &[], true);
1304        }
1305    }
1306
1307    /// The last autosave failure, if any, as a tracked signal the UI can watch.
1308    pub fn last_error(&self) -> day_reactive::Signal<Option<String>> {
1309        self.inner.error
1310    }
1311
1312    /// Flush every pending change now, in one transaction. Autosave calls this at turn end;
1313    /// call it directly where the error matters at a known point.
1314    pub fn save(&self) -> Result<(), DbError> {
1315        self.save_now().map(|_| ())
1316    }
1317
1318    /// Run `f` and return the SQL one flush of everything it changed issues: the headless
1319    /// persistence assert (autosave is suspended for the duration so the statements land
1320    /// here). Twenty keystrokes into one field come back as one `UPDATE`.
1321    pub fn record_sql(&self, f: impl FnOnce()) -> Result<Vec<String>, DbError> {
1322        let prior = self.inner.autosave.replace(false);
1323        f();
1324        let result = self.save_now();
1325        self.inner.autosave.set(prior);
1326        result.map(|stmts| stmts.into_iter().map(|(sql, _)| sql).collect())
1327    }
1328
1329    fn save_now(&self) -> Result<Vec<(String, Vec<Value>)>, DbError> {
1330        if self.inner.flushing.get() {
1331            return Ok(Vec::new());
1332        }
1333        let dirty = {
1334            let mut d = self.inner.dirty.borrow_mut();
1335            if d.is_empty() {
1336                drop(d);
1337                // Nothing to flush, but a stale query may still be waiting on its deferred
1338                // requery (a fetch swap on a clean container lands here).
1339                self.run_deferred_requeries(&[]);
1340                return Ok(Vec::new());
1341            }
1342            std::mem::take(&mut *d)
1343        };
1344        self.inner.flushing.set(true);
1345        let result = self.flush(&dirty);
1346        self.inner.flushing.set(false);
1347        match &result {
1348            Ok(stmts) => {
1349                // Previously dirty rows can now be evicted on the next fault.
1350                self.inner.eviction_retry.borrow_mut().clear();
1351                self.inner.error.set_if_changed(None);
1352                self.run_deferred_requeries(stmts);
1353            }
1354            Err(e) => {
1355                // Keep the optimistic cache and its pending writes together. A retry must
1356                // persist the same edits, including any edits made after the failed save.
1357                {
1358                    let mut pending = self.inner.dirty.borrow_mut();
1359                    let newer = std::mem::take(&mut *pending);
1360                    *pending = dirty;
1361                    pending.merge(newer);
1362                }
1363                self.inner.error.set(Some(e.to_string()));
1364            }
1365        }
1366        result
1367    }
1368
1369    // --- faulting ----------------------------------------------------------------------------
1370
1371    /// One row, made resident (faulted from the file if it was not). `None` when no such row
1372    /// exists (or a driver error surfaced, observable through [`ModelContainer::last_error`]).
1373    pub fn get<M: Model>(&self, id: impl Into<ModelId<M>>) -> Option<day_model::Elem<M>> {
1374        match self.try_get::<M>(id) {
1375            Ok(row) => row,
1376            Err(error) => {
1377                self.inner.error.set(Some(error.to_string()));
1378                None
1379            }
1380        }
1381    }
1382
1383    /// Read a row, distinguishing an absent key from a storage or decoding failure.
1384    pub fn try_get<M: Model>(
1385        &self,
1386        id: impl Into<ModelId<M>>,
1387    ) -> Result<Option<day_model::Elem<M>>, DbError> {
1388        let store = self.cache::<M>();
1389        let h = id.into().handle();
1390        if !store.with_untracked(|k| k.get(h).is_some()) {
1391            self.ensure_resident::<M>(&[h])?;
1392        }
1393        Ok(store
1394            .with_untracked(|k| k.get(h).is_some())
1395            .then(|| store.elem(h)))
1396    }
1397
1398    /// Make these rows resident, faulting the missing ones in one chunked `SELECT`. Rows the
1399    /// file does not have are not resident afterwards; rows deleted this turn are not
1400    /// resurrected.
1401    pub fn ensure_resident<M: Model>(&self, keys: &[u64]) -> Result<(), DbError> {
1402        let store = self.cache::<M>();
1403        self.fault_into(store.store_id(), keys)
1404    }
1405
1406    /// [`ModelContainer::ensure_resident`], typed ids in.
1407    pub fn ensure<M: Model>(
1408        &self,
1409        ids: impl IntoIterator<Item = impl Into<ModelId<M>>>,
1410    ) -> Result<(), DbError> {
1411        let keys: Vec<u64> = ids.into_iter().map(|i| i.into().handle()).collect();
1412        self.ensure_resident::<M>(&keys)
1413    }
1414
1415    /// Fault every row of `M`'s table in: the document pattern, said explicitly. A sketch's
1416    /// scene or a settings table is the working set, and the app that draws all of it warms
1417    /// it once at open. Raise the cache limit first (`set_cache_limit(usize::MAX)` for a
1418    /// document container) so the warmed rows are not immediately eligible to leave; rows
1419    /// deleted this turn stay deleted. Returns how many rows are resident afterward.
1420    pub fn warm<M: Model>(&self) -> Result<usize, DbError> {
1421        let store = self.cache::<M>();
1422        let keys = self.select_id_column_checked(&format!(
1423            "SELECT {} FROM {} ORDER BY {}",
1424            M::KEY,
1425            M::TABLE,
1426            M::KEY
1427        ))?;
1428        self.fault_into(store.store_id(), &keys)?;
1429        Ok(store.with_untracked(|k| k.len()))
1430    }
1431
1432    /// Insert one row through the front door: it becomes resident and dirty, announces, and
1433    /// folds to one `INSERT` at the next flush.
1434    pub fn insert<M: Model>(&self, row: M) {
1435        let store = self.cache::<M>();
1436        let h = row.handle();
1437        store.restructure("create", Op::Insert, h, move |k| k.push(row));
1438    }
1439
1440    /// `SELECT COUNT(*)`: the table's true size, which the cache cannot know. Settles
1441    /// pending writes first (with autosave), like every other read.
1442    pub fn table_count<M: Model>(&self) -> Result<u64, DbError> {
1443        if self.inner.autosave.get() && !self.inner.dirty.borrow().is_empty() {
1444            self.save()?;
1445        }
1446        let mut n = 0i64;
1447        self.conn().query(
1448            &format!("SELECT COUNT(*) FROM {}", M::TABLE),
1449            &[],
1450            &mut |row| {
1451                n = row.get(0).as_int().unwrap_or(0);
1452            },
1453        )?;
1454        Ok(n.max(0) as u64)
1455    }
1456
1457    /// The untyped fault: bring `keys` into `store_id`'s cache.
1458    pub(crate) fn fault_into(&self, store_id: u64, keys: &[u64]) -> Result<(), DbError> {
1459        let (is_resident, absorb, columns, table, keys_where) = {
1460            let tables = self.inner.tables.borrow();
1461            let Some(hooks) = tables.get(&store_id) else {
1462                return Ok(());
1463            };
1464            (
1465                hooks.is_resident.clone(),
1466                hooks.absorb.clone(),
1467                hooks.columns.join(", "),
1468                hooks.table,
1469                keys_where_of(hooks),
1470            )
1471        };
1472        let missing: Vec<u64> = {
1473            let dirty = self.inner.dirty.borrow();
1474            keys.iter()
1475                .copied()
1476                .filter(|k| !is_resident(*k))
1477                // A row deleted this turn still exists in the file until the flush; faulting
1478                // it back would resurrect it.
1479                .filter(|k| dirty.rows.get(&(store_id, *k)) != Some(&DirtyRow::Delete))
1480                .collect()
1481        };
1482        if missing.is_empty() {
1483            return Ok(());
1484        }
1485        let mut faulted: Vec<u64> = Vec::with_capacity(missing.len());
1486        for chunk in missing.chunks(MAX_BOUND_PARAMS / 2) {
1487            let (clause, params) = keys_where(chunk);
1488            let mut rows: Vec<Vec<Value>> = Vec::new();
1489            self.conn().query(
1490                &format!("SELECT {columns} FROM {table} WHERE {clause}"),
1491                &params,
1492                &mut |row| {
1493                    let n = Row::len(row);
1494                    rows.push((0..n).map(|i| row.get(i)).collect());
1495                },
1496            )?;
1497            faulted.extend(absorb(rows)?);
1498        }
1499        // The Recorder serves whole fixture tables whatever the `WHERE` says; keep only what
1500        // was asked for so faulting stays precise there too. (Through a `HashSet`; a linear
1501        // scan here made warming half a million rows quadratic.)
1502        let wanted: std::collections::HashSet<u64> = missing.iter().copied().collect();
1503        faulted.retain(|k| wanted.contains(k));
1504        self.enforce_cache_limit(store_id, &faulted, false);
1505        Ok(())
1506    }
1507
1508    /// Release resident rows beyond the cache limit: oldest first, never a dirty row, never
1509    /// an observed one, never one just faulted for the caller still holding it.
1510    ///
1511    /// The pass walks every resident key, so it runs with hysteresis on the fault path:
1512    /// nothing happens until the cache overshoots the limit by a slack margin, and one pass
1513    /// then brings it back to the limit, amortizing the walk over the faults that filled the
1514    /// slack, instead of paying O(resident) per fault batch. (Measured: a 50k-row relation
1515    /// traversal over a 500k-row table spent 99% of its time in the un-amortized walk.)
1516    /// `strict` skips the slack, so `set_cache_limit` enforces its new bound immediately.
1517    fn enforce_cache_limit(&self, store_id: u64, protect: &[u64], strict: bool) {
1518        let limit = self.inner.cache_limit.get();
1519        if limit == usize::MAX {
1520            return;
1521        }
1522        let (resident_len, evict) = {
1523            let tables = self.inner.tables.borrow();
1524            let Some(hooks) = tables.get(&store_id) else {
1525                return;
1526            };
1527            ((hooks.resident_len)(), hooks.evict.clone())
1528        };
1529        let slack = if strict {
1530            0
1531        } else {
1532            (limit / 8).clamp(64, 4096)
1533        };
1534        let threshold = if strict {
1535            limit
1536        } else {
1537            self.inner
1538                .eviction_retry
1539                .borrow()
1540                .get(&store_id)
1541                .copied()
1542                .unwrap_or_else(|| limit.saturating_add(slack))
1543        };
1544        if resident_len <= threshold {
1545            return;
1546        }
1547        // Back off even when every row is pinned. A fixed limit gate otherwise scans an
1548        // ever-growing dirty transaction on EVERY single-row fault (quadratic work).
1549        self.inner.eviction_retry.borrow_mut().insert(
1550            store_id,
1551            resident_len.saturating_add(slack.max(resident_len / 8).max(1)),
1552        );
1553        let resident = {
1554            let tables = self.inner.tables.borrow();
1555            match tables.get(&store_id) {
1556                Some(hooks) => (hooks.resident_keys)(),
1557                None => return,
1558            }
1559        };
1560        let excess = resident.len().saturating_sub(limit);
1561        let candidates: Vec<u64> = {
1562            let dirty = self.inner.dirty.borrow();
1563            if dirty.full.contains(&store_id) {
1564                return; // a wholesale rewrite is pending; every row is implicitly dirty
1565            }
1566            let protect: std::collections::HashSet<u64> = protect.iter().copied().collect();
1567            resident
1568                .into_iter()
1569                .filter(|key| !protect.contains(key) && !dirty.rows.contains_key(&(store_id, *key)))
1570                .collect()
1571        };
1572        let evicted = evict(&candidates, excess);
1573        let remaining = resident_len.saturating_sub(evicted);
1574        self.inner.eviction_retry.borrow_mut().insert(
1575            store_id,
1576            remaining
1577                .max(limit)
1578                .saturating_add(slack.max(remaining / 8).max(1)),
1579        );
1580    }
1581
1582    // --- internals ---------------------------------------------------------------------------
1583
1584    pub(crate) fn conn(&self) -> std::cell::RefMut<'_, Box<dyn SqliteConnection>> {
1585        self.inner.conn.borrow_mut()
1586    }
1587
1588    /// Run a one-column SELECT and hand back the values as key handles. Errors surface on the
1589    /// error signal (these run on read paths with no caller to give a `Result` to).
1590    /// One-column key SELECT with the error returned, for callers that have a `Result` to
1591    /// give it to (the read paths use [`ModelContainer::select_id_column`] instead).
1592    fn select_id_column_checked(&self, sql: &str) -> Result<Vec<u64>, DbError> {
1593        let mut ids = Vec::new();
1594        self.conn().query(sql, &[], &mut |row| {
1595            if let Some(h) = value_to_handle(&row.get(0)) {
1596                ids.push(h);
1597            }
1598        })?;
1599        Ok(ids)
1600    }
1601
1602    fn select_ids_checked(&self, sql: &str, params: &[Value]) -> Result<Vec<u64>, DbError> {
1603        let mut ids = Vec::new();
1604        self.conn().query(sql, params, &mut |row| {
1605            if let Some(h) = value_to_handle(&row.get(0)) {
1606                ids.push(h);
1607            }
1608        })?;
1609        Ok(ids)
1610    }
1611    pub(crate) fn select_id_column(&self, sql: &str, params: &[Value]) -> Vec<u64> {
1612        match self.select_ids_checked(sql, params) {
1613            Ok(ids) => ids,
1614            Err(e) => {
1615                self.inner.error.set(Some(e.to_string()));
1616                Vec::new()
1617            }
1618        }
1619    }
1620
1621    /// Run a one-column SELECT for a single REAL.
1622    pub(crate) fn select_real(&self, sql: &str, params: &[Value]) -> Option<f64> {
1623        let mut v = None;
1624        if let Err(e) = self.conn().query(sql, params, &mut |row| {
1625            v = row.get(0).as_real().ok();
1626        }) {
1627            self.inner.error.set(Some(e.to_string()));
1628        }
1629        v
1630    }
1631
1632    /// This turn's unflushed rows of one store: what relation reads overlay.
1633    pub(crate) fn dirty_rows_of(&self, store_id: u64) -> Vec<(u64, DirtyRow)> {
1634        self.inner
1635            .dirty
1636            .borrow()
1637            .rows
1638            .iter()
1639            .filter(|((s, _), _)| *s == store_id)
1640            .map(|((_, k), state)| (*k, state.clone()))
1641            .collect()
1642    }
1643
1644    /// One row's pending state, if any.
1645    pub(crate) fn dirty_state_of(&self, store_id: u64, key: u64) -> Option<DirtyRow> {
1646        self.inner
1647            .dirty
1648            .borrow()
1649            .rows
1650            .get(&(store_id, key))
1651            .cloned()
1652    }
1653
1654    fn ensure_schema_table(&self) -> Result<(), DbError> {
1655        self.conn().execute(
1656            "CREATE TABLE IF NOT EXISTS _day_schema (\
1657             table_name TEXT PRIMARY KEY, fingerprint TEXT NOT NULL, version INTEGER NOT NULL)",
1658            &[],
1659        )?;
1660        Ok(())
1661    }
1662
1663    fn db_version(&self) -> Result<u32, DbError> {
1664        let mut version = 0u32;
1665        self.conn().query(
1666            "SELECT version FROM _day_schema WHERE table_name = '_db'",
1667            &[],
1668            &mut |row| {
1669                version = row.get(0).as_int().unwrap_or(0) as u32;
1670            },
1671        )?;
1672        Ok(version)
1673    }
1674
1675    fn set_db_version(&self, v: u32) -> Result<(), DbError> {
1676        self.conn().execute(
1677            "INSERT INTO _day_schema (table_name, fingerprint, version) VALUES ('_db', '', ?) \
1678             ON CONFLICT(table_name) DO UPDATE SET version = excluded.version",
1679            &[Value::Int(v as i64)],
1680        )?;
1681        Ok(())
1682    }
1683
1684    fn run_stages(&self, plan: MigrationPlan) -> Result<(), DbError> {
1685        let target = plan.target_version();
1686        let mut current = self.db_version()?;
1687        if current > target && target > 0 {
1688            return Err(DbError::new(
1689                DbErrorKind::Schema,
1690                format!(
1691                    "database is at version {current}, newer than this build's {target} — \
1692                     refusing to open (an old app writing a new schema is how data rots)"
1693                ),
1694            ));
1695        }
1696        let mut stages = plan.stages;
1697        stages.sort_by_key(|s| s.from);
1698        for stage in stages {
1699            if stage.from != current {
1700                if stage.to <= current {
1701                    continue; // already applied
1702                }
1703                return Err(DbError::new(
1704                    DbErrorKind::Schema,
1705                    format!(
1706                        "migration stage {}→{} does not start at the database's version {current}",
1707                        stage.from, stage.to
1708                    ),
1709                ));
1710            }
1711            let mut conn = self.conn();
1712            conn.begin()?;
1713            match (stage.run)(conn.as_mut()) {
1714                Ok(()) => {
1715                    conn.commit()?;
1716                    drop(conn);
1717                    current = stage.to;
1718                    self.set_db_version(current)?;
1719                }
1720                Err(e) => {
1721                    let _ = conn.rollback();
1722                    return Err(e);
1723                }
1724            }
1725        }
1726        if target > 0 {
1727            self.set_db_version(target)?;
1728        }
1729        Ok(())
1730    }
1731
1732    /// Create (or lightweight-migrate) `M`'s table and register its hooks. The cache starts
1733    /// empty: this is the line where the old engine read the whole table, and the lazy one
1734    /// exists so that nothing does.
1735    fn attach<M: Model>(&self) -> Result<(), DbError> {
1736        // FTS5's external-content table and the R*Tree address rows by ROWID (an i64), so
1737        // both need the key column to be the integer rowid. A wide-keyed model declaring one
1738        // is refused at open, naming the constraint, rather than silently mis-indexing.
1739        let key_sql = M::COLUMNS
1740            .iter()
1741            .find(|c| c.name == M::KEY)
1742            .map(|c| c.sql)
1743            .unwrap_or(SqlType::Integer);
1744        if key_sql != SqlType::Integer && M::SPATIAL.is_some() {
1745            return Err(DbError::new(
1746                DbErrorKind::Unsupported,
1747                format!(
1748                    "`{}` declares spatial(…), which addresses rows by ROWID — those \
1749                     need an integer `#[model(id)]`, not a Uuid or String key",
1750                    M::TABLE
1751                ),
1752            ));
1753        }
1754        // A second attach of the same model (a re-attached database after a catalog swap)
1755        // keeps its store and hooks; only the resident rows are stale, and they are dropped
1756        // so the next fault reads the new file.
1757        if self.inner.stores.borrow().contains_key(&TypeId::of::<M>()) {
1758            let store = self.cache::<M>();
1759            let keys: Vec<u64> = store.with_untracked(|k| k.keys());
1760            store.depopulate_many(&keys);
1761            return Ok(());
1762        }
1763        if !M::EXTERNAL {
1764            self.ensure_table::<M>()?;
1765        }
1766        for l in M::LINKS {
1767            self.inner.links.borrow_mut().push(LinkInfo {
1768                owner_table: M::TABLE,
1769                field: l.field,
1770                local: l.local,
1771                target_table: l.target_table,
1772                remote: l.remote,
1773            });
1774        }
1775
1776        let store: Store<Keyed<M>> = Store::new(Keyed::new(Vec::new()));
1777        let store_id = store.store_id();
1778
1779        let columns: Vec<String> = M::COLUMNS.iter().map(|c| c.name.to_string()).collect();
1780        let fields: Vec<String> = M::COLUMNS.iter().map(|c| c.field.to_string()).collect();
1781        let row_for = {
1782            Rc::new(move |key: u64| store.with_untracked(|k| k.get(key).map(|m| m.to_row())))
1783                as Rc<dyn Fn(u64) -> Option<Vec<Value>>>
1784        };
1785        let all_rows = {
1786            Rc::new(move || {
1787                store.with_untracked(|k| {
1788                    k.items().iter().map(|m| (m.handle(), m.to_row())).collect()
1789                })
1790            }) as Rc<dyn Fn() -> Vec<(u64, Vec<Value>)>>
1791        };
1792        let resident_keys =
1793            Rc::new(move || store.with_untracked(|k| k.keys())) as Rc<dyn Fn() -> Vec<u64>>;
1794        let resident_len =
1795            Rc::new(move || store.with_untracked(|k| k.len())) as Rc<dyn Fn() -> usize>;
1796        let is_resident = Rc::new(move |h: u64| store.with_untracked(|k| k.get(h).is_some()))
1797            as Rc<dyn Fn(u64) -> bool>;
1798
1799        let absorb = {
1800            Rc::new(
1801                move |raw_rows: Vec<Vec<Value>>| -> Result<Vec<u64>, DbError> {
1802                    let mut decoded: Vec<M> = Vec::with_capacity(raw_rows.len());
1803                    for r in raw_rows {
1804                        decoded.push(M::from_row(&r)?);
1805                    }
1806                    let keys: Vec<u64> = decoded.iter().map(|m| m.handle()).collect();
1807                    store.populate(decoded);
1808                    Ok(keys)
1809                },
1810            ) as AbsorbFn
1811        };
1812        let refresh = {
1813            Rc::new(move |raw_rows: Vec<Vec<Value>>| -> Result<bool, DbError> {
1814                let mut fresh: Vec<M> = Vec::with_capacity(raw_rows.len());
1815                for r in raw_rows {
1816                    fresh.push(M::from_row(&r)?);
1817                }
1818                let existing: Vec<u64> = store.with_untracked(|k| k.keys());
1819                let fresh_keys: std::collections::HashSet<u64> =
1820                    fresh.iter().map(|m| m.handle()).collect();
1821                let mut changed = false;
1822                day_model::with_author(ModelContainer::EXTERNAL_AUTHOR, || {
1823                    for m in fresh {
1824                        let key = m.handle();
1825                        match store.with_untracked(|k| k.get(key).map(|old| old.to_row())) {
1826                            // Selected by resident keys, so an unknown row means the cache
1827                            // moved underneath us; treat it as an arrival.
1828                            None => {
1829                                changed = true;
1830                                store.restructure("external", Op::Insert, key, |k| k.push(m));
1831                            }
1832                            Some(old) => {
1833                                let new_row = m.to_row();
1834                                let labels: Vec<&'static str> = M::COLUMNS
1835                                    .iter()
1836                                    .enumerate()
1837                                    .filter(|(i, _)| Row::get(&old, *i) != Row::get(&new_row, *i))
1838                                    .map(|(_, c)| c.field)
1839                                    .collect();
1840                                if !labels.is_empty() {
1841                                    changed = true;
1842                                    store.merge_row(key, m, &labels);
1843                                }
1844                            }
1845                        }
1846                    }
1847                    for gone in existing.into_iter().filter(|k| !fresh_keys.contains(k)) {
1848                        changed = true;
1849                        store.restructure("external", Op::Delete, gone, |k| {
1850                            k.remove(gone);
1851                        });
1852                    }
1853                });
1854                Ok(changed)
1855            }) as RefreshFn
1856        };
1857        let evict = Rc::new(move |candidates: &[u64], want: usize| {
1858            let doomed: Vec<u64> = candidates
1859                .iter()
1860                .copied()
1861                .filter(|h| !store.is_observed(*h))
1862                .take(want)
1863                .collect();
1864            store.depopulate_many(&doomed)
1865        }) as EvictFn;
1866        let watch_undo = Rc::new(move |stack: &day_model::UndoStack| stack.watch(store))
1867            as Rc<dyn Fn(&day_model::UndoStack)>;
1868
1869        self.inner.tables.borrow_mut().insert(
1870            store_id,
1871            TableHooks {
1872                table: M::TABLE,
1873                key_cols: vec![M::KEY.to_string()],
1874                key_where: Rc::new(|h| (format!("{} = ?", M::KEY), vec![key_param(h)])),
1875                columns,
1876                fields,
1877                resident_len,
1878                fts: (!M::FTS_COLUMNS.is_empty()).then(|| format!("{}_fts", M::TABLE)),
1879                fts_key: if key_sql == SqlType::Integer {
1880                    "rowid"
1881                } else {
1882                    "day_key"
1883                },
1884                spatial: M::SPATIAL.map(|s| {
1885                    (
1886                        s.lat.to_string(),
1887                        s.lon.to_string(),
1888                        format!("{}_geo", M::TABLE),
1889                    )
1890                }),
1891                row_for,
1892                all_rows,
1893                resident_keys,
1894                is_resident,
1895                absorb,
1896                refresh,
1897                evict,
1898                #[cfg(not(target_arch = "wasm32"))]
1899                dispose_cache: Rc::new(move || store.dispose_contents()),
1900                watch_undo,
1901            },
1902        );
1903        self.inner
1904            .stores
1905            .borrow_mut()
1906            .insert(TypeId::of::<M>(), Box::new(store));
1907        Ok(())
1908    }
1909
1910    fn ensure_table<M: Model>(&self) -> Result<(), DbError> {
1911        // Relation-contributed clauses fold into the fingerprint: adopting or changing a
1912        // delete rule re-runs this path. An existing table cannot gain the SQL-level clause
1913        // (SQLite has no `ALTER ADD CONSTRAINT`); the in-memory rule still enforces, and a
1914        // staged rebuild adopts the clause when the app wants the engine's backstop too.
1915        let mut fp_val = model_fingerprint::<M>();
1916        for s in self
1917            .inner
1918            .fk_specs
1919            .borrow()
1920            .iter()
1921            .filter(|s| s.child_table == M::TABLE)
1922        {
1923            for b in s
1924                .child_field
1925                .bytes()
1926                .chain(s.parent_table.bytes())
1927                .chain(s.rule.sql().bytes())
1928            {
1929                fp_val ^= b as u64;
1930                fp_val = fp_val.wrapping_mul(0x1000_0000_01b3);
1931            }
1932        }
1933        let fp = format!("{fp_val:016x}");
1934        let stored = self.stored_fingerprint(M::TABLE)?;
1935        if stored.as_deref() == Some(fp.as_str()) {
1936            return Ok(());
1937        }
1938
1939        // DDL and backfill are one transaction: a failed migration leaves the old
1940        // index and fingerprint usable. Remove triggers before dropping indexed columns.
1941        self.conn().begin()?;
1942        let result = (|| {
1943            let t = M::TABLE;
1944            if self.table_exists(&format!("{t}_fts"))? {
1945                for suffix in ["ai", "ad", "au"] {
1946                    self.conn()
1947                        .execute(&format!("DROP TRIGGER IF EXISTS {t}_fts_{suffix}"), &[])?;
1948                }
1949                self.conn().execute(&format!("DROP TABLE {t}_fts"), &[])?;
1950                self.conn()
1951                    .execute(&format!("DROP TABLE IF EXISTS {t}_fts_keys"), &[])?;
1952            }
1953            if !self.table_exists(M::TABLE)? {
1954                self.create_table::<M>()?;
1955            } else {
1956                self.lightweight_migrate::<M>()?;
1957            }
1958            self.create_indexes::<M>()?;
1959            self.create_shadow_tables::<M>()?;
1960            self.store_fingerprint(M::TABLE, &fp)?;
1961            self.conn().commit()
1962        })();
1963        if result.is_err() {
1964            let _ = self.conn().rollback();
1965        }
1966        result
1967    }
1968
1969    /// The FTS5 and R*Tree shadows a model declares: virtual tables plus `AFTER` triggers, so
1970    /// the indexes stay true inside the same transaction as every write, even a write made by
1971    /// another tool straight into the file. Backfilled when first created.
1972    fn create_shadow_tables<M: Model>(&self) -> Result<(), DbError> {
1973        let t = M::TABLE;
1974        let key = M::KEY;
1975        if !M::FTS_COLUMNS.is_empty() {
1976            if !self.inner.caps.full_text_search {
1977                return Err(DbError::new(
1978                    DbErrorKind::Unsupported,
1979                    format!(
1980                        "`{t}` declares fts(…) but this driver's engine has no FTS5 — the \
1981                         bundled and cipher engines compile it in"
1982                    ),
1983                ));
1984            }
1985            let cols = M::FTS_COLUMNS.join(", ");
1986            let fresh = !self.table_exists(&format!("{t}_fts"))?;
1987            // The tokenizer rides in the DDL; its value is a compile-time literal, quoted
1988            // through SQL's own escape so an apostrophe cannot break the statement.
1989            let tokenize = match M::FTS_TOKENIZE {
1990                Some(tok) => format!(", tokenize='{}'", tok.replace('\'', "''")),
1991                None => String::new(),
1992            };
1993            let wide = M::COLUMNS
1994                .iter()
1995                .find(|c| c.name == key)
1996                .is_some_and(|c| c.sql != SqlType::Integer);
1997            if wide {
1998                if M::FTS_COLUMNS.contains(&"day_key") {
1999                    return Err(DbError::new(
2000                        DbErrorKind::Unsupported,
2001                        "day_key is reserved in a non-integer-key FTS index",
2002                    ));
2003                }
2004                let key_type = M::COLUMNS
2005                    .iter()
2006                    .find(|c| c.name == key)
2007                    .expect("key column")
2008                    .sql
2009                    .ddl();
2010                // FTS rowids stay private. An indexed mapping makes update/delete O(log n)
2011                // rather than scanning the unindexed public key in every FTS row.
2012                self.conn().execute(&format!("CREATE TABLE IF NOT EXISTS {t}_fts_keys(day_rowid INTEGER PRIMARY KEY, day_key {key_type} NOT NULL UNIQUE)"), &[])?;
2013                self.conn().execute(&format!("CREATE VIRTUAL TABLE IF NOT EXISTS {t}_fts USING fts5(day_key UNINDEXED, {cols}{tokenize})"), &[])?;
2014                let new_cols = M::FTS_COLUMNS
2015                    .iter()
2016                    .map(|c| format!("new.{c}"))
2017                    .collect::<Vec<_>>()
2018                    .join(", ");
2019                let insert = format!(
2020                    "INSERT INTO {t}_fts_keys(day_key) VALUES (new.{key}); INSERT INTO {t}_fts(rowid, day_key, {cols}) VALUES ((SELECT day_rowid FROM {t}_fts_keys WHERE day_key = new.{key}), new.{key}, {new_cols});"
2021                );
2022                let delete = format!(
2023                    "DELETE FROM {t}_fts WHERE rowid = (SELECT day_rowid FROM {t}_fts_keys WHERE day_key = old.{key}); DELETE FROM {t}_fts_keys WHERE day_key = old.{key};"
2024                );
2025                for (suffix, event, body) in [
2026                    ("ai", "INSERT", insert.clone()),
2027                    ("ad", "DELETE", delete.clone()),
2028                    ("au", "UPDATE", format!("{delete} {insert}")),
2029                ] {
2030                    self.conn().execute(&format!("CREATE TRIGGER IF NOT EXISTS {t}_fts_{suffix} AFTER {event} ON {t} BEGIN {body} END"), &[])?;
2031                }
2032                if fresh {
2033                    self.conn().execute(
2034                        &format!("INSERT INTO {t}_fts_keys(day_key) SELECT {key} FROM {t}"),
2035                        &[],
2036                    )?;
2037                    let qualified = M::FTS_COLUMNS
2038                        .iter()
2039                        .map(|c| format!("b.{c}"))
2040                        .collect::<Vec<_>>()
2041                        .join(", ");
2042                    self.conn().execute(&format!("INSERT INTO {t}_fts(rowid, day_key, {cols}) SELECT k.day_rowid, b.{key}, {qualified} FROM {t} b JOIN {t}_fts_keys k ON k.day_key = b.{key}"), &[])?;
2043                }
2044            } else {
2045                self.conn().execute(
2046                    &format!(
2047                        "CREATE VIRTUAL TABLE IF NOT EXISTS {t}_fts USING fts5({cols}, \
2048                     content={t}, content_rowid={key}{tokenize})"
2049                    ),
2050                    &[],
2051                )?;
2052                let new_cols = M::FTS_COLUMNS
2053                    .iter()
2054                    .map(|c| format!("new.{c}"))
2055                    .collect::<Vec<_>>()
2056                    .join(", ");
2057                let old_cols = M::FTS_COLUMNS
2058                    .iter()
2059                    .map(|c| format!("old.{c}"))
2060                    .collect::<Vec<_>>()
2061                    .join(", ");
2062                self.conn().execute(
2063                    &format!(
2064                        "CREATE TRIGGER IF NOT EXISTS {t}_fts_ai AFTER INSERT ON {t} BEGIN \
2065                     INSERT INTO {t}_fts(rowid, {cols}) VALUES (new.{key}, {new_cols}); END"
2066                    ),
2067                    &[],
2068                )?;
2069                self.conn().execute(
2070                &format!(
2071                    "CREATE TRIGGER IF NOT EXISTS {t}_fts_ad AFTER DELETE ON {t} BEGIN \
2072                     INSERT INTO {t}_fts({t}_fts, rowid, {cols}) VALUES ('delete', old.{key}, {old_cols}); END"
2073                ),
2074                &[],
2075            )?;
2076                self.conn().execute(
2077                &format!(
2078                    "CREATE TRIGGER IF NOT EXISTS {t}_fts_au AFTER UPDATE ON {t} BEGIN \
2079                     INSERT INTO {t}_fts({t}_fts, rowid, {cols}) VALUES ('delete', old.{key}, {old_cols}); \
2080                     INSERT INTO {t}_fts(rowid, {cols}) VALUES (new.{key}, {new_cols}); END"
2081                ),
2082                &[],
2083            )?;
2084                if fresh {
2085                    // External-content rebuild: index whatever rows predate the declaration.
2086                    self.conn().execute(
2087                        &format!("INSERT INTO {t}_fts({t}_fts) VALUES ('rebuild')"),
2088                        &[],
2089                    )?;
2090                }
2091            }
2092        }
2093        if let Some(s) = M::SPATIAL {
2094            if !self.inner.caps.rtree {
2095                return Err(DbError::new(
2096                    DbErrorKind::Unsupported,
2097                    format!(
2098                        "`{t}` declares spatial(…) but this driver's engine has no R*Tree — \
2099                         the bundled and cipher engines compile it in"
2100                    ),
2101                ));
2102            }
2103            let (lat, lon) = (s.lat, s.lon);
2104            let fresh = !self.table_exists(&format!("{t}_geo"))?;
2105            self.conn().execute(
2106                &format!(
2107                    "CREATE VIRTUAL TABLE IF NOT EXISTS {t}_geo USING rtree({key}, \
2108                     min_lat, max_lat, min_lon, max_lon)"
2109                ),
2110                &[],
2111            )?;
2112            self.conn().execute(
2113                &format!(
2114                    "CREATE TRIGGER IF NOT EXISTS {t}_geo_ai AFTER INSERT ON {t} BEGIN \
2115                     INSERT OR REPLACE INTO {t}_geo VALUES (new.{key}, new.{lat}, new.{lat}, new.{lon}, new.{lon}); END"
2116                ),
2117                &[],
2118            )?;
2119            self.conn().execute(
2120                &format!(
2121                    "CREATE TRIGGER IF NOT EXISTS {t}_geo_au AFTER UPDATE OF {lat}, {lon} ON {t} BEGIN \
2122                     INSERT OR REPLACE INTO {t}_geo VALUES (new.{key}, new.{lat}, new.{lat}, new.{lon}, new.{lon}); END"
2123                ),
2124                &[],
2125            )?;
2126            self.conn().execute(
2127                &format!(
2128                    "CREATE TRIGGER IF NOT EXISTS {t}_geo_ad AFTER DELETE ON {t} BEGIN \
2129                     DELETE FROM {t}_geo WHERE {key} = old.{key}; END"
2130                ),
2131                &[],
2132            )?;
2133            if fresh {
2134                self.conn().execute(
2135                    &format!(
2136                        "INSERT OR REPLACE INTO {t}_geo \
2137                         SELECT {key}, {lat}, {lat}, {lon}, {lon} FROM {t}"
2138                    ),
2139                    &[],
2140                )?;
2141            }
2142        }
2143        Ok(())
2144    }
2145
2146    fn table_exists(&self, table: &str) -> Result<bool, DbError> {
2147        let mut found = false;
2148        self.conn().query(
2149            "SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?",
2150            &[Value::Text(table.into())],
2151            &mut |_| found = true,
2152        )?;
2153        Ok(found)
2154    }
2155
2156    fn create_table<M: Model>(&self) -> Result<(), DbError> {
2157        let specs = self.inner.fk_specs.borrow();
2158        let cols: Vec<String> = M::COLUMNS
2159            .iter()
2160            .map(|c| {
2161                let mut s = format!("{} {}", c.name, c.sql.ddl());
2162                if c.name == M::KEY {
2163                    s.push_str(" PRIMARY KEY");
2164                } else if c.not_null {
2165                    s.push_str(" NOT NULL");
2166                }
2167                if c.unique && c.name != M::KEY {
2168                    s.push_str(" UNIQUE");
2169                }
2170                // A declared relation's foreign key: enforced by the engine too, so another
2171                // process honors the same delete rule, and so a cascade's reach into rows
2172                // this process never faulted still lands in the file. Deferred, so
2173                // within-transaction statement order (a cascade's children, an undo's
2174                // re-inserts) never trips it.
2175                if let Some(spec) = specs
2176                    .iter()
2177                    .find(|f| f.child_table == M::TABLE && f.child_field == c.field)
2178                {
2179                    s.push_str(&format!(
2180                        " REFERENCES {}({}) ON DELETE {} DEFERRABLE INITIALLY DEFERRED",
2181                        spec.parent_table,
2182                        spec.parent_key,
2183                        spec.rule.sql()
2184                    ));
2185                }
2186                s
2187            })
2188            .collect();
2189        let body = format!("CREATE TABLE {} ({})", M::TABLE, cols.join(", "));
2190        // `STRICT` where the engine allows it (always, for the bundled build); older system
2191        // SQLites reject the keyword, and the plain form is the fallback.
2192        if self.conn().execute(&format!("{body} STRICT"), &[]).is_err() {
2193            self.conn().execute(&body, &[])?;
2194        }
2195        Ok(())
2196    }
2197
2198    fn create_indexes<M: Model>(&self) -> Result<(), DbError> {
2199        // A declared relation's foreign-key column is indexed without being asked: it is what
2200        // `children_of` selects on, what relation predicates correlate on, and what the
2201        // engine scans to enforce `ON DELETE`. Unindexed, every one of those is a full scan
2202        // of the child table.
2203        let fk_cols: Vec<&str> = self
2204            .inner
2205            .fk_specs
2206            .borrow()
2207            .iter()
2208            .filter(|s| s.child_table == M::TABLE)
2209            .filter_map(|s| {
2210                M::COLUMNS
2211                    .iter()
2212                    .find(|c| c.field == s.child_field)
2213                    .map(|c| c.name)
2214            })
2215            .collect();
2216        for c in M::COLUMNS
2217            .iter()
2218            .filter(|c| c.indexed || (fk_cols.contains(&c.name) && c.name != M::KEY))
2219        {
2220            self.conn().execute(
2221                &format!(
2222                    "CREATE INDEX IF NOT EXISTS day_idx_{t}_{c} ON {t}({c})",
2223                    t = M::TABLE,
2224                    c = c.name
2225                ),
2226                &[],
2227            )?;
2228        }
2229        for idx in M::COMPOSITE_INDEXES {
2230            let cols = idx.join(", ");
2231            let name = idx.join("_");
2232            self.conn().execute(
2233                &format!(
2234                    "CREATE INDEX IF NOT EXISTS day_idx_{t}_{name} ON {t}({cols})",
2235                    t = M::TABLE
2236                ),
2237                &[],
2238            )?;
2239        }
2240        Ok(())
2241    }
2242
2243    /// Close the gap between the file's columns and the declared ones: additions and drops
2244    /// only. A type change or a rename is refused with both names in the error; that is what
2245    /// staged migrations are for.
2246    fn lightweight_migrate<M: Model>(&self) -> Result<(), DbError> {
2247        let mut existing: Vec<String> = Vec::new();
2248        self.conn().query(
2249            &format!("PRAGMA table_info({})", M::TABLE),
2250            &[],
2251            &mut |row| {
2252                if let Ok(name) = row.get(1).as_text() {
2253                    existing.push(name.to_string());
2254                }
2255            },
2256        )?;
2257
2258        let declared: Vec<&'static str> = M::COLUMNS.iter().map(|c| c.name).collect();
2259        let defaults = M::default_row();
2260
2261        for (i, col) in M::COLUMNS.iter().enumerate() {
2262            if !existing.iter().any(|e| e == col.name) {
2263                // Add nullable, then backfill with the field's Rust default.
2264                self.conn().execute(
2265                    &format!(
2266                        "ALTER TABLE {} ADD COLUMN {} {}",
2267                        M::TABLE,
2268                        col.name,
2269                        col.sql.ddl()
2270                    ),
2271                    &[],
2272                )?;
2273                let default = Row::get(&defaults, i);
2274                if default != Value::Null {
2275                    self.conn().execute(
2276                        &format!("UPDATE {} SET {} = ?", M::TABLE, col.name),
2277                        &[default],
2278                    )?;
2279                }
2280            }
2281        }
2282        for gone in existing.iter().filter(|e| !declared.iter().any(|d| d == e)) {
2283            self.conn()
2284                .execute(&format!("ALTER TABLE {} DROP COLUMN {gone}", M::TABLE), &[])?;
2285        }
2286        Ok(())
2287    }
2288
2289    fn stored_fingerprint(&self, table: &str) -> Result<Option<String>, DbError> {
2290        let mut fp = None;
2291        self.conn().query(
2292            "SELECT fingerprint FROM _day_schema WHERE table_name = ?",
2293            &[Value::Text(table.into())],
2294            &mut |row| {
2295                if let Ok(t) = row.get(0).as_text() {
2296                    fp = Some(t.to_string());
2297                }
2298            },
2299        )?;
2300        Ok(fp)
2301    }
2302
2303    fn store_fingerprint(&self, table: &str, fp: &str) -> Result<(), DbError> {
2304        self.conn().execute(
2305            "INSERT INTO _day_schema (table_name, fingerprint, version) VALUES (?, ?, 0) \
2306             ON CONFLICT(table_name) DO UPDATE SET fingerprint = excluded.fingerprint",
2307            &[Value::Text(table.into()), Value::Text(fp.into())],
2308        )?;
2309        Ok(())
2310    }
2311
2312    fn install_sink(&self) {
2313        let inner = Rc::downgrade(&self.inner);
2314        let sink = day_model::install_change_sink(move |change| {
2315            if let Some(inner) = inner.upgrade() {
2316                // An external merge's changes are the database's own contents arriving:
2317                // queries go stale on them like any edit, but nothing goes back to the file.
2318                if change.author != Some(ModelContainer::EXTERNAL_AUTHOR) {
2319                    let tables = inner.tables.borrow();
2320                    inner
2321                        .dirty
2322                        .borrow_mut()
2323                        .note(change, |store| tables.contains_key(&store));
2324                }
2325                let container = ModelContainer { inner };
2326                container.mark_queries_stale(change);
2327                container.relations_on_change(change);
2328            }
2329        });
2330        self.inner.sink.set(Some(sink));
2331    }
2332
2333    fn install_autosave(&self) {
2334        // Weak: `on_turn_end` registrations live for the process, and a strong clone here
2335        // would keep the container (and its connection) alive forever.
2336        let inner = Rc::downgrade(&self.inner);
2337        day_reactive::on_turn_end(move || {
2338            let Some(inner) = inner.upgrade() else { return };
2339            let this = ModelContainer { inner };
2340            if this.inner.autosave.get() && !this.inner.dirty.borrow().is_empty() {
2341                // The error lands in the signal; a turn end has no caller to give a Result to.
2342                let _ = this.save();
2343            }
2344        });
2345    }
2346
2347    fn flush(&self, dirty: &DirtyState) -> Result<Vec<(String, Vec<Value>)>, DbError> {
2348        let stmts = self.fold(dirty)?;
2349        if stmts.is_empty() {
2350            return Ok(stmts);
2351        }
2352        let mut conn = self.conn();
2353        let outer = self.inner.worker_transaction.get();
2354        if !outer {
2355            conn.begin()?;
2356        }
2357        for (sql, params) in &stmts {
2358            if let Err(e) = conn.execute(sql, params) {
2359                if !outer {
2360                    let _ = conn.rollback();
2361                }
2362                return Err(e);
2363            }
2364        }
2365        if !outer && let Err(error) = conn.commit() {
2366            let _ = conn.rollback();
2367            return Err(error);
2368        }
2369        Ok(stmts)
2370    }
2371
2372    #[cfg(not(target_arch = "wasm32"))]
2373    fn worker_dispose_caches(&self) {
2374        for hooks in self.inner.tables.borrow().values() {
2375            (hooks.dispose_cache)();
2376        }
2377    }
2378
2379    #[cfg(not(target_arch = "wasm32"))]
2380    fn worker_write<R>(
2381        &self,
2382        write: impl FnOnce(&Self) -> Result<R, DbError>,
2383    ) -> Result<R, DbError> {
2384        self.save()?;
2385        self.conn().begin()?;
2386        self.inner.worker_transaction.set(true);
2387        let result = day_reactive::batch(|| {
2388            let value = write(self)?;
2389            self.save()?;
2390            Ok(value)
2391        })
2392        .and_then(|value| {
2393            // Reactions may have made additional writes while the batch drained. Commit only
2394            // after those writes settle, never before turn-end autosave has run.
2395            self.save()?;
2396            self.conn().commit()?;
2397            Ok(value)
2398        });
2399        self.inner.worker_transaction.set(false);
2400        if result.is_err() {
2401            self.conn().rollback().map_err(|error| {
2402                DbError::new(
2403                    DbErrorKind::Closed,
2404                    format!("transaction rollback failed: {error}"),
2405                )
2406            })?;
2407            self.worker_discard_changes()?;
2408        }
2409        result
2410    }
2411
2412    #[cfg(not(target_arch = "wasm32"))]
2413    fn worker_read<R>(&self, read: impl FnOnce(&Self) -> Result<R, DbError>) -> Result<R, DbError> {
2414        self.save()?;
2415        self.conn().execute_batch("PRAGMA query_only = ON")?;
2416        self.conn().begin().map_err(|error| {
2417            DbError::new(
2418                DbErrorKind::Closed,
2419                format!("could not begin read snapshot: {error}"),
2420            )
2421        })?;
2422        let autosave = self.inner.autosave.replace(false);
2423        let mut result =
2424            day_model::with_author("worker-read", || day_reactive::batch(|| read(self)));
2425        let mutated = !self.inner.dirty.borrow().is_empty();
2426        self.conn().rollback().map_err(|error| {
2427            DbError::new(
2428                DbErrorKind::Closed,
2429                format!("could not end read snapshot: {error}"),
2430            )
2431        })?;
2432        self.conn()
2433            .execute_batch("PRAGMA query_only = OFF")
2434            .map_err(|error| {
2435                DbError::new(
2436                    DbErrorKind::Closed,
2437                    format!("could not restore write mode: {error}"),
2438                )
2439            })?;
2440        if mutated {
2441            self.worker_discard_changes()?;
2442            result = Err(DbError::driver(
2443                "a worker read attempted to mutate model state",
2444            ));
2445        }
2446        self.inner.autosave.set(autosave);
2447        result
2448    }
2449
2450    #[cfg(not(target_arch = "wasm32"))]
2451    fn worker_discard_changes(&self) -> Result<(), DbError> {
2452        let autosave = self.inner.autosave.replace(false);
2453        *self.inner.dirty.borrow_mut() = DirtyState::default();
2454        let result = self.refresh_resident();
2455        self.invalidate_relation_memos();
2456        if result.is_ok() {
2457            self.requery_all();
2458        }
2459        self.inner.autosave.set(autosave);
2460        result.map(|_| ()).map_err(|error| {
2461            DbError::new(
2462                DbErrorKind::Closed,
2463                format!("transaction cache recovery failed: {error}"),
2464            )
2465        })
2466    }
2467
2468    /// The fold, materialized: the smallest statement list that expresses `dirty`, in
2469    /// first-touch order. Row values come from the caches now; the change log carried which
2470    /// rows and columns moved, never their contents. Reads only; [`ModelContainer::flush`]
2471    /// executes the list in one transaction.
2472    fn fold(&self, dirty: &DirtyState) -> Result<Vec<(String, Vec<Value>)>, DbError> {
2473        let tables = self.inner.tables.borrow();
2474        let mut stmts: Vec<(String, Vec<Value>)> = Vec::new();
2475
2476        // Wholesale rewrites first: upsert every resident row. (The cache is a working set;
2477        // rows outside it were never part of the rewrite, and deleting "the rest" would
2478        // delete data the rewrite never saw.)
2479        for store_id in &dirty.full {
2480            let Some(hooks) = tables.get(store_id) else {
2481                continue;
2482            };
2483            for (_, row) in (hooks.all_rows)() {
2484                stmts.push(upsert_stmt(hooks, &row));
2485            }
2486        }
2487
2488        // Per-row work, into batches that can merge. Deletes of one table merge into one
2489        // `IN`; updates merge when they write the same columns to the same values, which is
2490        // what a multi-selection edit produces ("set fill on twelve shapes").
2491        //
2492        // Deletes are held apart and emitted last. Dirty order interleaves rows by when each
2493        // first changed, which can put a parent row's delete between its children's detach
2494        // updates (the first detach dirties the parent through relation upkeep), and a
2495        // relation column's `ON DELETE CASCADE` fires per statement, `DEFERRABLE` or not, so
2496        // the mid-batch delete would take every still-attached child with it (found by Day
2497        // Sketch's ungroup: two members detached, one row left). With inserts and updates
2498        // first, a row still referencing a deleted parent at delete time is one the batch
2499        // never detached: an orphan the cascade rule is meant to take.
2500        let mut batches: Vec<Batch> = Vec::new();
2501        let mut deletes: Vec<Batch> = Vec::new();
2502        // (store, statement shape, a fingerprint of the `SET` values) → the batch it joins.
2503        let mut open: HashMap<(u64, String, u64), usize> = HashMap::new();
2504        let mut open_deletes: HashMap<(u64, String, u64), usize> = HashMap::new();
2505
2506        for id in &dirty.order {
2507            let Some(state) = dirty.rows.get(id) else {
2508                continue;
2509            };
2510            let (store_id, key) = *id;
2511            if dirty.full.contains(&store_id) {
2512                continue; // the resync above already covered it
2513            }
2514            let Some(hooks) = tables.get(&store_id) else {
2515                continue;
2516            };
2517            // A join row is addressed by a pair of columns, which no single-column `IN` can
2518            // express, so those keep one statement each.
2519            let batchable = hooks.key_cols.len() == 1;
2520            match state {
2521                DirtyRow::Delete => {
2522                    if !batchable {
2523                        let (clause, params) = (hooks.key_where)(key);
2524                        deletes.push(Batch::Single(
2525                            format!("DELETE FROM {} WHERE {clause}", hooks.table),
2526                            params,
2527                        ));
2528                        continue;
2529                    }
2530                    join_batch(&mut deletes, &mut open_deletes, store_id, None, key);
2531                }
2532                DirtyRow::Insert => {
2533                    if let Some(row) = (hooks.row_for)(key) {
2534                        let (sql, params) = upsert_stmt(hooks, &row);
2535                        batches.push(Batch::Single(sql, params));
2536                    }
2537                }
2538                DirtyRow::Update(cols) => {
2539                    let Some(row) = (hooks.row_for)(key) else {
2540                        continue; // deleted since; its Delete entry handles it
2541                    };
2542                    if cols.is_empty() {
2543                        // A row-level replacement named no columns; write them all.
2544                        let (sql, params) = upsert_stmt(hooks, &row);
2545                        batches.push(Batch::Single(sql, params));
2546                        continue;
2547                    }
2548                    let mut sets: Vec<String> = Vec::with_capacity(cols.len());
2549                    let mut set_params: Vec<Value> = Vec::with_capacity(cols.len());
2550                    for c in cols {
2551                        let Some(i) = hooks.fields.iter().position(|n| n == c) else {
2552                            continue; // a transient field's label, never a column
2553                        };
2554                        sets.push(format!("{} = ?", hooks.columns[i]));
2555                        set_params.push(row.get(i));
2556                    }
2557                    if set_params.is_empty() {
2558                        continue; // only transient fields changed
2559                    }
2560                    let clause = sets.join(", ");
2561                    if !batchable {
2562                        let (where_clause, mut where_params) = (hooks.key_where)(key);
2563                        let mut params = set_params;
2564                        params.append(&mut where_params);
2565                        batches.push(Batch::Single(
2566                            format!("UPDATE {} SET {clause} WHERE {where_clause}", hooks.table),
2567                            params,
2568                        ));
2569                        continue;
2570                    }
2571                    join_batch(
2572                        &mut batches,
2573                        &mut open,
2574                        store_id,
2575                        Some((clause, set_params)),
2576                        key,
2577                    );
2578                }
2579            }
2580        }
2581
2582        for batch in batches.into_iter().chain(deletes) {
2583            match batch {
2584                Batch::Single(sql, params) => stmts.push((sql, params)),
2585                Batch::Keyed { store, set, keys } => {
2586                    let Some(hooks) = tables.get(&store) else {
2587                        continue;
2588                    };
2589                    materialize(hooks, set, &keys, &mut stmts);
2590                }
2591            }
2592        }
2593        Ok(stmts)
2594    }
2595
2596    // --- maintenance (docs/persistence.md) ---------------------------------------------------
2597
2598    /// `VACUUM INTO`: a transactionally consistent, already-compacted snapshot, taken while
2599    /// the app keeps writing. Restore is an open, not a verb.
2600    pub fn backup_to(&self, path: &Path) -> Result<(), DbError> {
2601        self.save()?;
2602        self.conn().execute(
2603            "VACUUM INTO ?",
2604            &[Value::Text(path.to_string_lossy().into_owned())],
2605        )?;
2606        Ok(())
2607    }
2608
2609    /// `PRAGMA integrity_check`, parsed: an empty list means the database is sound.
2610    pub fn integrity_check(&self) -> Result<Vec<String>, DbError> {
2611        let mut findings = Vec::new();
2612        self.conn()
2613            .query("PRAGMA integrity_check", &[], &mut |row| {
2614                if let Ok(t) = row.get(0).as_text()
2615                    && t != "ok"
2616                {
2617                    findings.push(t.to_string());
2618                }
2619            })?;
2620        Ok(findings)
2621    }
2622
2623    /// Fold the WAL into the main file, before the OS copies it whole (device backup).
2624    pub fn checkpoint(&self) -> Result<(), DbError> {
2625        // The PRAGMA answers with a status row; a query with an ignored callback consumes it.
2626        self.conn()
2627            .query("PRAGMA wal_checkpoint(TRUNCATE)", &[], &mut |_| {})
2628    }
2629
2630    pub fn vacuum(&self) -> Result<(), DbError> {
2631        self.save()?;
2632        self.conn().execute("VACUUM", &[]).map(|_| ())
2633    }
2634
2635    /// Re-encrypt in place under a new key (`PRAGMA rekey`; feature `cipher`).
2636    #[cfg(feature = "cipher")]
2637    pub fn rekey(&self, new: Secret) -> Result<(), DbError> {
2638        self.save()?;
2639        let quoted = new.reveal().replace('\'', "''");
2640        // The PRAGMA answers with a status row; consume it as a query.
2641        self.conn()
2642            .query(&format!("PRAGMA rekey = '{quoted}'"), &[], &mut |_| {})
2643    }
2644
2645    /// Write an encrypted copy at `path` through SQLCipher's conversion path (`ATTACH` +
2646    /// `sqlcipher_export`); plaintext↔encrypted cannot happen in place.
2647    #[cfg(feature = "cipher")]
2648    pub fn encrypt_to(&self, path: &Path, key: Secret) -> Result<(), DbError> {
2649        self.export_to(path, Some(key))
2650    }
2651
2652    /// Write a plaintext copy at `path`, same mechanism with an empty key.
2653    #[cfg(feature = "cipher")]
2654    pub fn decrypt_to(&self, path: &Path) -> Result<(), DbError> {
2655        self.export_to(path, None)
2656    }
2657
2658    #[cfg(feature = "cipher")]
2659    fn export_to(&self, path: &Path, key: Option<Secret>) -> Result<(), DbError> {
2660        self.save()?;
2661        let quoted_path = path.to_string_lossy().replace('\'', "''");
2662        let quoted_key = key
2663            .as_ref()
2664            .map(|k| k.reveal().replace('\'', "''"))
2665            .unwrap_or_default();
2666        let mut conn = self.conn();
2667        conn.execute(
2668            &format!("ATTACH DATABASE '{quoted_path}' AS day_export KEY '{quoted_key}'"),
2669            &[],
2670        )?;
2671        conn.query("SELECT sqlcipher_export('day_export')", &[], &mut |_| {})
2672            .and_then(|_| conn.execute("DETACH DATABASE day_export", &[]).map(|_| ()))
2673    }
2674
2675    /// Total size in bytes (page_count × page_size).
2676    pub fn size_bytes(&self) -> Result<u64, DbError> {
2677        let mut pages = 0i64;
2678        let mut page_size = 0i64;
2679        self.conn().query("PRAGMA page_count", &[], &mut |row| {
2680            pages = row.get(0).as_int().unwrap_or(0);
2681        })?;
2682        self.conn().query("PRAGMA page_size", &[], &mut |row| {
2683            page_size = row.get(0).as_int().unwrap_or(0);
2684        })?;
2685        Ok((pages * page_size).max(0) as u64)
2686    }
2687}
2688
2689/// The multi-key `WHERE` builder for a hooks entry: `key IN (…)` for single-column keys, an OR
2690/// list of pair clauses for join tables.
2691fn keys_where_of(hooks: &TableHooks) -> KeysWhere {
2692    if hooks.key_cols.len() == 1 {
2693        let col = hooks.key_cols[0].clone();
2694        Rc::new(move |keys: &[u64]| {
2695            let marks = vec!["?"; keys.len()].join(", ");
2696            (
2697                format!("{col} IN ({marks})"),
2698                keys.iter().map(|k| key_param(*k)).collect(),
2699            )
2700        })
2701    } else {
2702        let key_where = hooks.key_where.clone();
2703        Rc::new(move |keys: &[u64]| {
2704            let mut clauses = Vec::with_capacity(keys.len());
2705            let mut params = Vec::with_capacity(keys.len() * 2);
2706            for k in keys {
2707                let (c, mut p) = key_where(*k);
2708                clauses.push(format!("({c})"));
2709                params.append(&mut p);
2710            }
2711            (clauses.join(" OR "), params)
2712        })
2713    }
2714}
2715
2716/// One statement the fold will write, before the mergeable ones have merged.
2717enum Batch {
2718    /// Stands alone: an upsert (its values are the row's own), or a row addressed by a
2719    /// composite key, which no single-column `IN` can express.
2720    Single(String, Vec<Value>),
2721    /// Same table, same operation, same values: one statement per chunk of keys.
2722    Keyed {
2723        store: u64,
2724        /// The `SET` clause and its parameters for an update; `None` for a delete.
2725        set: Option<(String, Vec<Value>)>,
2726        keys: Vec<u64>,
2727    },
2728}
2729
2730/// SQLite's conservative bound-parameter ceiling. Modern builds allow far more, but a
2731/// `system` engine may be an older one, and chunking costs nothing to write.
2732const MAX_BOUND_PARAMS: usize = 900;
2733
2734/// Add `key` to the batch sharing this table, clause and values, or open a new one.
2735///
2736/// The slot key separates a delete from an update (their clauses differ), and separates
2737/// updates writing different values, which must stay different statements. Grouping is by
2738/// hash so a large flush stays linear; the values are compared before merging, so a hash
2739/// collision costs a second statement rather than a wrong one.
2740fn join_batch(
2741    batches: &mut Vec<Batch>,
2742    open: &mut HashMap<(u64, String, u64), usize>,
2743    store: u64,
2744    set: Option<(String, Vec<Value>)>,
2745    key: u64,
2746) {
2747    let clause = set.as_ref().map(|(c, _)| c.clone()).unwrap_or_default();
2748    let print = set.as_ref().map(|(_, p)| fingerprint(p)).unwrap_or(0);
2749    let slot = (store, clause, print);
2750    if let Some(&i) = open.get(&slot)
2751        && let Batch::Keyed {
2752            set: existing,
2753            keys,
2754            ..
2755        } = &mut batches[i]
2756        && existing.as_ref().map(|(_, p)| p.as_slice()) == set.as_ref().map(|(_, p)| p.as_slice())
2757    {
2758        keys.push(key);
2759        return;
2760    }
2761    open.insert(slot, batches.len());
2762    batches.push(Batch::Keyed {
2763        store,
2764        set,
2765        keys: vec![key],
2766    });
2767}
2768
2769/// A cheap order-sensitive hash of bound values, for grouping identical updates. Equality is
2770/// still checked before two rows share a statement; this only decides who to compare with.
2771fn fingerprint(values: &[Value]) -> u64 {
2772    let mut h: u64 = 0xcbf2_9ce4_8422_2325;
2773    let mut eat = |bytes: &[u8]| {
2774        for b in bytes {
2775            h ^= *b as u64;
2776            h = h.wrapping_mul(0x1000_0000_01b3);
2777        }
2778    };
2779    for v in values {
2780        match v {
2781            Value::Null => eat(&[0]),
2782            Value::Int(i) => {
2783                eat(&[1]);
2784                eat(&i.to_le_bytes());
2785            }
2786            // Bit pattern, not numeric value: two values that hash apart are only compared
2787            // separately, never merged wrongly.
2788            Value::Real(r) => {
2789                eat(&[2]);
2790                eat(&r.to_bits().to_le_bytes());
2791            }
2792            Value::Text(t) => {
2793                eat(&[3]);
2794                eat(t.as_bytes());
2795            }
2796            Value::Blob(b) => {
2797                eat(&[4]);
2798                eat(b);
2799            }
2800        }
2801    }
2802    h
2803}
2804
2805/// Write a batch out: the familiar `= ?` form for one key, chunked `IN` statements for more.
2806fn materialize(
2807    hooks: &TableHooks,
2808    set: Option<(String, Vec<Value>)>,
2809    keys: &[u64],
2810    out: &mut Vec<(String, Vec<Value>)>,
2811) {
2812    // One key keeps the `= ?` form: it is the common case by far, it reads plainly in a
2813    // trace, and it is one more statement shape the cache can hold.
2814    if keys.len() == 1 {
2815        let (where_clause, where_params) = (hooks.key_where)(keys[0]);
2816        match set {
2817            Some((clause, mut params)) => {
2818                params.extend(where_params);
2819                out.push((
2820                    format!("UPDATE {} SET {clause} WHERE {where_clause}", hooks.table),
2821                    params,
2822                ));
2823            }
2824            None => out.push((
2825                format!("DELETE FROM {} WHERE {where_clause}", hooks.table),
2826                where_params,
2827            )),
2828        }
2829        return;
2830    }
2831
2832    let key_col = &hooks.key_cols[0];
2833    let set_len = set.as_ref().map(|(_, p)| p.len()).unwrap_or(0);
2834    let cap = MAX_BOUND_PARAMS.saturating_sub(set_len).max(1);
2835    for chunk in keys.chunks(cap) {
2836        let mut params: Vec<Value> = Vec::with_capacity(set_len + chunk.len());
2837        if let Some((_, set_params)) = &set {
2838            params.extend(set_params.iter().cloned());
2839        }
2840        params.extend(chunk.iter().map(|k| key_param(*k)));
2841        let marks = vec!["?"; chunk.len()].join(", ");
2842        let sql = match &set {
2843            Some((clause, _)) => format!(
2844                "UPDATE {} SET {clause} WHERE {key_col} IN ({marks})",
2845                hooks.table
2846            ),
2847            None => format!("DELETE FROM {} WHERE {key_col} IN ({marks})", hooks.table),
2848        };
2849        out.push((sql, params));
2850    }
2851}
2852
2853fn upsert_stmt(hooks: &TableHooks, row: &[Value]) -> (String, Vec<Value>) {
2854    let cols = hooks.columns.join(", ");
2855    let marks = vec!["?"; hooks.columns.len()].join(", ");
2856    // A true upsert, not `INSERT OR REPLACE`: the conflict path fires `UPDATE` triggers, which
2857    // is what keeps the generated FTS/R*Tree shadows in sync (`OR REPLACE`'s implicit delete
2858    // skips `AFTER DELETE` triggers unless recursive_triggers is on).
2859    let sets = hooks
2860        .columns
2861        .iter()
2862        .filter(|c| !hooks.key_cols.contains(c))
2863        .map(|c| format!("{c} = excluded.{c}"))
2864        .collect::<Vec<_>>()
2865        .join(", ");
2866    let conflict = if sets.is_empty() {
2867        "DO NOTHING".to_string()
2868    } else {
2869        format!("DO UPDATE SET {sets}")
2870    };
2871    (
2872        format!(
2873            "INSERT INTO {} ({cols}) VALUES ({marks}) ON CONFLICT({}) {conflict}",
2874            hooks.table,
2875            hooks.key_cols.join(", ")
2876        ),
2877        row.to_vec(),
2878    )
2879}
2880
2881impl Drop for ContainerInner {
2882    fn drop(&mut self) {
2883        if let Some(sink) = self.sink.take() {
2884            day_model::remove_change_sink(sink);
2885        }
2886    }
2887}
2888
2889// ---------------------------------------------------------------------------
2890// Live queries (docs/persistence.md; queries.rs holds the compiler and the diff)
2891// ---------------------------------------------------------------------------
2892
2893/// What a query's consumers have not yet seen. `Deltas` can animate a list row by row;
2894/// `Reload` means the whole set moved (a fetch swap, a tangled requery) and a reload is
2895/// the accurate answer.
2896#[derive(Clone, Debug, PartialEq)]
2897pub enum QueryEvents {
2898    None,
2899    Deltas(Vec<Delta>),
2900    Reload,
2901}
2902
2903impl QueryEvents {
2904    fn push(&mut self, deltas: &[Delta]) {
2905        match self {
2906            QueryEvents::None => *self = QueryEvents::Deltas(deltas.to_vec()),
2907            QueryEvents::Deltas(d) => d.extend_from_slice(deltas),
2908            QueryEvents::Reload => {}
2909        }
2910    }
2911    fn reload(&mut self) {
2912        *self = QueryEvents::Reload;
2913    }
2914}
2915
2916/// What one relation crossing subscribes a query to, precomputed at install (and at every
2917/// fetch swap) so the change sink's staleness check is a few comparisons.
2918struct RelWatch {
2919    /// The store on the far side of the crossing (the related table's cache).
2920    store: u64,
2921    /// The join membership store, when the crossing is a many-to-many; every link, unlink
2922    /// and reposition there is a membership change.
2923    join_store: Option<u64>,
2924    /// Field names on the far store whose write is a membership change (the foreign key, the
2925    /// order field) even though no predicate reads them.
2926    fields: Vec<&'static str>,
2927    /// Column names of the far table the inner predicate reads.
2928    columns: Vec<&'static str>,
2929}
2930
2931struct QueryState {
2932    store_id: u64,
2933    table: &'static str,
2934    /// The relation subscriptions, recomputed when the fetch is swapped.
2935    watches: RefCell<Vec<RelWatch>>,
2936    /// Extra local columns whose write is a membership change (a `One` column crossed by the
2937    /// query's own table).
2938    local_extra: RefCell<Vec<&'static str>>,
2939    set: RefCell<ResultSet>,
2940    /// Bumped whenever the result set changes; `ids()`/`count()` track it.
2941    version: day_reactive::Signal<u64>,
2942    pending: RefCell<QueryEvents>,
2943    /// A dependency-touching change arrived; the answer re-derives after the flush.
2944    needs_sql: Cell<bool>,
2945    // Reading the last committed result must not consume the post-commit invalidation.
2946    pending_commit: Cell<bool>,
2947    error: day_reactive::Signal<Option<DbError>>,
2948    /// `query_raw` only: the statement and the tables whose flush re-runs it.
2949    raw: Option<RawQuery>,
2950    /// A count-shaped query: `count` is the answer, the id set stays empty, and requeries
2951    /// run `SELECT COUNT(*)`, the badge query, O(1) memory at any result size.
2952    count_only: bool,
2953    count: Cell<usize>,
2954}
2955
2956struct RawQuery {
2957    sql: String,
2958    params: Vec<Value>,
2959    tables: Vec<String>,
2960}
2961
2962/// A live, typed result set over one model's table: ids only, answered by the engine and
2963/// kept current by dependency-gated requeries. Rows stay lazy: fault the ones you show
2964/// ([`Query::materialize`], or a list source doing it for you). Clone shares the same set.
2965pub struct Query<M: Model> {
2966    state: Rc<QueryState>,
2967    container: ModelContainer,
2968    _p: std::marker::PhantomData<fn() -> M>,
2969}
2970
2971impl<M: Model> Clone for Query<M> {
2972    fn clone(&self) -> Self {
2973        Query {
2974            state: self.state.clone(),
2975            container: self.container.clone(),
2976            _p: std::marker::PhantomData,
2977        }
2978    }
2979}
2980
2981impl<M: Model> Query<M> {
2982    /// This query's last read failure. A failed read preserves its previous result set.
2983    pub fn error(&self) -> day_reactive::Signal<Option<DbError>> {
2984        self.state.error
2985    }
2986
2987    /// Explicitly retry a query after a transient read failure (also useful after external SQL).
2988    pub fn refresh(&self) {
2989        self.state.needs_sql.set(true);
2990        self.refresh_if_stale();
2991    }
2992
2993    /// Checked form of `ids`, for imports and commands that must not mistake failure for absence.
2994    pub fn try_ids(&self) -> Result<Vec<ModelId<M>>, DbError> {
2995        let ids = self.ids();
2996        match self.state.error.get() {
2997            Some(e) => Err(e),
2998            None => Ok(ids),
2999        }
3000    }
3001
3002    /// A checked snapshot for non-UI work, fetched in batches. UI lists should use the query
3003    /// itself as their row source so they only materialize the visible working set.
3004    pub fn try_collect(&self) -> Result<Vec<M>, DbError> {
3005        let ids = self.try_ids()?;
3006        let mut rows = Vec::with_capacity(ids.len());
3007        for chunk in ids.chunks(64) {
3008            self.container
3009                .ensure_resident::<M>(&chunk.iter().map(|id| id.handle()).collect::<Vec<_>>())?;
3010            for id in chunk {
3011                if let Some(row) = self.container.try_get::<M>(*id)?
3012                    && let Some(value) = row.with_value_untracked(|v| v.cloned())
3013                {
3014                    rows.push(value);
3015                }
3016            }
3017        }
3018        Ok(rows)
3019    }
3020
3021    /// The result ids, typed and in query order, as a tracked read: the caller re-runs when
3022    /// the set changes, and only then.
3023    pub fn ids(&self) -> Vec<ModelId<M>> {
3024        self.refresh_if_stale();
3025        let _ = self.state.version.get();
3026        self.state
3027            .set
3028            .borrow()
3029            .ids()
3030            .iter()
3031            .map(|h| ModelId::from_handle(*h))
3032            .collect()
3033    }
3034
3035    /// The result count, tracked like [`Query::ids`].
3036    pub fn count(&self) -> usize {
3037        self.refresh_if_stale();
3038        let _ = self.state.version.get();
3039        self.state.set.borrow().ids().len()
3040    }
3041
3042    /// The first result, tracked.
3043    pub fn first(&self) -> Option<ModelId<M>> {
3044        self.refresh_if_stale();
3045        let _ = self.state.version.get();
3046        self.state
3047            .set
3048            .borrow()
3049            .ids()
3050            .first()
3051            .map(|h| ModelId::from_handle(*h))
3052    }
3053
3054    /// Tracked membership test.
3055    pub fn contains(&self, id: impl Into<ModelId<M>>) -> bool {
3056        self.refresh_if_stale();
3057        let _ = self.state.version.get();
3058        self.state.set.borrow().ids().contains(&id.into().handle())
3059    }
3060
3061    /// Untracked snapshot: reactively silent, but still current (pending staleness settles
3062    /// first, like every other read).
3063    pub fn ids_untracked(&self) -> Vec<ModelId<M>> {
3064        self.refresh_if_stale();
3065        self.state
3066            .set
3067            .borrow()
3068            .ids()
3069            .iter()
3070            .map(|h| ModelId::from_handle(*h))
3071            .collect()
3072    }
3073
3074    /// Bring this window of the result into the cache: what a list binding calls for the
3075    /// rows it is about to show, batched into one `SELECT`.
3076    pub fn materialize(&self, range: std::ops::Range<usize>) {
3077        let keys: Vec<u64> = {
3078            let set = self.state.set.borrow();
3079            let ids = set.ids();
3080            let end = range.end.min(ids.len());
3081            let start = range.start.min(end);
3082            ids[start..end].to_vec()
3083        };
3084        if let Err(e) = self.container.ensure_resident::<M>(&keys) {
3085            self.container.inner.error.set(Some(e.to_string()));
3086        }
3087    }
3088
3089    /// Swap the fetch (a changed filter or sort): requeries and reloads consumers. No-op when
3090    /// equal to the current one, so a `query_fn` closure can re-run cheaply.
3091    pub fn set_fetch(&self, fetch: Fetch) {
3092        if *self.state.set.borrow().fetch() == fetch {
3093            return;
3094        }
3095        self.container.rewire_watches(&self.state, &fetch);
3096        {
3097            let mut set = self.state.set.borrow_mut();
3098            *set = ResultSet::new(fetch);
3099        }
3100        // Resolve once pending statements land; mid-turn the flush has not run yet.
3101        self.state.needs_sql.set(true);
3102        self.state
3103            .pending_commit
3104            .set(!self.container.inner.dirty.borrow().is_empty());
3105        self.refresh_if_stale();
3106        self.state.pending.borrow_mut().reload();
3107        self.bump();
3108    }
3109
3110    /// Drain what changed since the last call: the list source's feed. Pending staleness
3111    /// settles first, so a drain right after an edit already narrates it.
3112    pub fn take_events(&self) -> QueryEvents {
3113        self.refresh_if_stale();
3114        std::mem::replace(&mut *self.state.pending.borrow_mut(), QueryEvents::None)
3115    }
3116
3117    /// A dependency-touching change arrived this turn and the flush has not run yet: settle
3118    /// it now. With autosave the pending statements flush (which requeries everything stale);
3119    /// with autosave off the query re-derives against the last save; the file is the only
3120    /// thing that can answer it.
3121    fn refresh_if_stale(&self) {
3122        if !self.state.needs_sql.get() {
3123            return;
3124        }
3125        if self.container.inner.autosave.get() {
3126            let _ = self.container.save();
3127        }
3128        if self.state.needs_sql.replace(false) {
3129            self.container.requery(&self.state);
3130        }
3131    }
3132
3133    fn bump(&self) {
3134        self.state
3135            .version
3136            .set(self.state.version.get_untracked().wrapping_add(1));
3137    }
3138}
3139
3140/// Builder for a [`Query`]: `container.query::<Trip>().filter(…).sort(…).live()`.
3141pub struct QueryBuilder<'c, M: Model> {
3142    container: &'c ModelContainer,
3143    fetch: Fetch,
3144    _p: std::marker::PhantomData<fn() -> M>,
3145}
3146
3147impl<M: Model> QueryBuilder<'_, M> {
3148    pub fn filter(mut self, p: Pred) -> Self {
3149        self.fetch = self.fetch.filter(p);
3150        self
3151    }
3152    pub fn sort(mut self, s: Sort) -> Self {
3153        self.fetch = self.fetch.sort(s);
3154        self
3155    }
3156    pub fn limit(mut self, n: usize) -> Self {
3157        self.fetch = self.fetch.limit(n);
3158        self
3159    }
3160    /// Run the fetch and keep it live against the change log.
3161    pub fn live(self) -> Query<M> {
3162        self.container.install_query::<M>(self.fetch, None)
3163    }
3164
3165    /// Keep only the count live, the badge form: no id vector, one `SELECT COUNT(*)` per
3166    /// requery, the same dependency gating.
3167    pub fn live_count(self) -> CountQuery<M> {
3168        CountQuery {
3169            state: self.container.install_state::<M>(self.fetch, None, true),
3170            container: self.container.clone(),
3171            _p: std::marker::PhantomData,
3172        }
3173    }
3174}
3175
3176/// A live count over one model's table, the badge query: `SELECT COUNT(*)` behind the same
3177/// dependency-gated staleness as [`Query`], holding no id vector, so a count over a
3178/// million-row result costs O(1) memory. Clone shares the same state.
3179pub struct CountQuery<M: Model> {
3180    state: Rc<QueryState>,
3181    container: ModelContainer,
3182    _p: std::marker::PhantomData<fn() -> M>,
3183}
3184
3185impl<M: Model> Clone for CountQuery<M> {
3186    fn clone(&self) -> Self {
3187        CountQuery {
3188            state: self.state.clone(),
3189            container: self.container.clone(),
3190            _p: std::marker::PhantomData,
3191        }
3192    }
3193}
3194
3195impl<M: Model> CountQuery<M> {
3196    /// The last read error, independently of the last successful count.
3197    pub fn error(&self) -> day_reactive::Signal<Option<DbError>> {
3198        self.state.error
3199    }
3200    /// Checked count for operations that require a successful read.
3201    pub fn try_get(&self) -> Result<usize, DbError> {
3202        let n = self.get();
3203        match self.state.error.get() {
3204            Some(e) => Err(e),
3205            None => Ok(n),
3206        }
3207    }
3208    /// Retry after a transient read error.
3209    pub fn refresh(&self) {
3210        self.state.needs_sql.set(true);
3211        self.refresh_if_stale();
3212    }
3213
3214    /// The count, as a tracked read: the caller re-runs when it changes, and only then.
3215    pub fn get(&self) -> usize {
3216        self.refresh_if_stale();
3217        let _ = self.state.version.get();
3218        self.state.count.get()
3219    }
3220
3221    /// Untracked snapshot: reactively silent, still current.
3222    pub fn get_untracked(&self) -> usize {
3223        self.refresh_if_stale();
3224        self.state.count.get()
3225    }
3226
3227    /// Swap the fetch (a changed filter): re-counts. No-op when equal, so a `count_fn`
3228    /// closure can re-run cheaply.
3229    pub fn set_fetch(&self, fetch: Fetch) {
3230        if *self.state.set.borrow().fetch() == fetch {
3231            return;
3232        }
3233        self.container.rewire_watches(&self.state, &fetch);
3234        *self.state.set.borrow_mut() = ResultSet::new(fetch);
3235        self.state.needs_sql.set(true);
3236        self.state
3237            .pending_commit
3238            .set(!self.container.inner.dirty.borrow().is_empty());
3239        self.refresh_if_stale();
3240    }
3241
3242    fn refresh_if_stale(&self) {
3243        if !self.state.needs_sql.get() {
3244            return;
3245        }
3246        if self.container.inner.autosave.get() {
3247            let _ = self.container.save();
3248        }
3249        if self.state.needs_sql.replace(false) {
3250            self.container.requery(&self.state);
3251        }
3252    }
3253}
3254
3255/// A fallback row: the key plus the dependency columns the fallback `SELECT` carried.
3256struct FallbackRow<'a> {
3257    cols: &'a [&'static str],
3258    /// values[0] is the key; values[1..] align with `cols`.
3259    values: &'a [Value],
3260}
3261
3262impl RowView for FallbackRow<'_> {
3263    fn col(&self, c: &str) -> Option<Value> {
3264        self.cols
3265            .iter()
3266            .position(|n| *n == c)
3267            .and_then(|i| self.values.get(i + 1).cloned())
3268    }
3269}
3270
3271impl ModelContainer {
3272    /// Start a typed query over `M`'s rows. Panics (like [`ModelContainer::cache`]) if `M` is
3273    /// not in this container's `schema!`, a wiring bug worth stopping on.
3274    pub fn query<M: Model>(&self) -> QueryBuilder<'_, M> {
3275        let _ = self.cache::<M>();
3276        QueryBuilder {
3277            container: self,
3278            fetch: Fetch::new(),
3279            _p: std::marker::PhantomData,
3280        }
3281    }
3282
3283    /// The reactive-fetch form: `f` is a computation, so a query whose fetch depends on signals
3284    /// (a search term, a filter toggle) re-derives itself when they change.
3285    pub fn query_fn<M: Model>(&self, f: impl Fn() -> Fetch + 'static) -> Query<M> {
3286        let q = self.install_query::<M>(f(), None);
3287        let q2 = q.clone();
3288        day_reactive::bind(f, move |fetch| q2.set_fetch(fetch.clone()));
3289        q
3290    }
3291
3292    /// The reactive-fetch count: a badge whose fetch depends on signals (the "Today" cutoff,
3293    /// a filter toggle) re-counts itself when they change.
3294    pub fn count_fn<M: Model>(&self, f: impl Fn() -> Fetch + 'static) -> CountQuery<M> {
3295        let q = CountQuery::<M> {
3296            state: self.install_state::<M>(f(), None, true),
3297            container: self.clone(),
3298            _p: std::marker::PhantomData,
3299        };
3300        let q2 = q.clone();
3301        day_reactive::bind(f, move |fetch| q2.set_fetch(fetch.clone()));
3302        q
3303    }
3304
3305    /// Raw SQL, declared: a read-only SELECT returning ids, re-run whenever a flush touches
3306    /// one of the named tables. The price of the escape hatch is whole-query invalidation.
3307    pub fn query_raw<M: Model>(
3308        &self,
3309        sql: impl Into<String>,
3310        params: Vec<Value>,
3311        tables: &[&str],
3312    ) -> Query<M> {
3313        self.install_query::<M>(
3314            Fetch::new().filter(Pred::Raw(String::new(), Vec::new())),
3315            Some(RawQuery {
3316                sql: sql.into(),
3317                params,
3318                tables: tables.iter().map(|s| s.to_string()).collect(),
3319            }),
3320        )
3321    }
3322
3323    /// Opt into undo: One history over every store this container manages, `levels` deep.
3324    /// Undo/redo replay flows through the same change pipeline as the user's edits, so
3325    /// autosave writes the inverse statements and live queries hear rows come back. Call it
3326    /// once, after open; clear it on migration (`UndoStack::clear`). While a stack is
3327    /// installed, deletes materialize the rows they remove (a cascade included) so the
3328    /// history can restore them.
3329    pub fn undo(&self, levels: usize) -> day_model::UndoStack {
3330        let stack = day_model::UndoStack::new(levels);
3331        for hooks in self.inner.tables.borrow().values() {
3332            (hooks.watch_undo)(&stack);
3333        }
3334        stack
3335    }
3336
3337    /// The driver's connection, directly, for maintenance, imports, or an extension's
3338    /// statements. Pending changes flush first; writes made here bypass the change log, so
3339    /// call [`ModelContainer::rescan`] afterward if they touched Day's tables.
3340    ///
3341    /// # Panics
3342    /// Panics if the pending save fails. Use [`ModelContainer::try_with_connection`] when
3343    /// the caller needs to handle storage errors.
3344    pub fn with_connection<R>(&self, f: impl FnOnce(&mut dyn SqliteConnection) -> R) -> R {
3345        self.save().expect(
3346            "pending persistence save failed; use try_with_connection to handle storage errors",
3347        );
3348        f(self.conn().as_mut())
3349    }
3350
3351    /// Flush pending edits before accessing the connection. The closure is never run if
3352    /// that save fails; its own error is returned unchanged.
3353    pub fn try_with_connection<R>(
3354        &self,
3355        f: impl FnOnce(&mut dyn SqliteConnection) -> Result<R, DbError>,
3356    ) -> Result<R, DbError> {
3357        self.save()?;
3358        f(self.conn().as_mut())
3359    }
3360
3361    /// Re-read the resident rows from the file and re-run every query: the recovery from
3362    /// writes that bypassed the change log ([`ModelContainer::with_connection`], another
3363    /// process). O(working set + query results), never O(table).
3364    pub fn rescan(&self) -> Result<(), DbError> {
3365        self.save()?;
3366        self.refresh_resident()?;
3367        self.invalidate_relation_memos();
3368        self.requery_all();
3369        // The cache now equals the file; a later check_external should not re-merge for
3370        // whatever external commits this refresh already picked up.
3371        if self.inner.caps.external_changes {
3372            self.inner.data_version.set(self.file_data_version()?);
3373        }
3374        Ok(())
3375    }
3376
3377    /// Attach another SQLite file under `alias` and bring `schema`'s models (every one
3378    /// declared `external = "alias"`) into this container: their tables are read as they
3379    /// are, with no DDL, migration, or fingerprint, through the same caches, queries, and
3380    /// lists as the container's own. Writes to them fail at flush (the file is attached
3381    /// read-only where the engine honors `mode=ro`), which is the contract: the other
3382    /// database has its own owner.
3383    ///
3384    /// Calling it again with the same alias swaps the file: the old one is detached, every
3385    /// resident row of its models dropped, and every live query re-run: the shape a
3386    /// downloaded catalog update takes.
3387    pub fn attach_database(&self, alias: &str, path: &str, schema: Schema) -> Result<(), DbError> {
3388        if alias.is_empty() || !alias.chars().all(|c| c.is_ascii_alphanumeric() || c == '_') {
3389            return Err(DbError::new(
3390                DbErrorKind::Unsupported,
3391                format!("attach_database: {alias:?} is not a plain SQL schema name"),
3392            ));
3393        }
3394        let held = self.inner.attached.borrow().iter().any(|a| a == alias);
3395        if held {
3396            self.detach_database(alias)?;
3397        }
3398        // Flush first: a DETACH/ATTACH pair inside an open write transaction is refused.
3399        if !self.inner.dirty.borrow().is_empty() {
3400            self.save()?;
3401        }
3402        // `file:` URIs carry the read-only mode; a driver without URI filenames (the web
3403        // worker) takes the bare path and relies on nobody writing.
3404        let uri = if path.starts_with("file:") || path.contains("://") {
3405            path.to_string()
3406        } else {
3407            format!("file:{}?mode=ro", path.replace('?', "%3F"))
3408        };
3409        let attach = |target: &str| -> Result<(), DbError> {
3410            self.conn().execute(
3411                &format!("ATTACH DATABASE ? AS {alias}"),
3412                &[Value::Text(target.to_string())],
3413            )?;
3414            Ok(())
3415        };
3416        if let Err(uri_err) = attach(&uri) {
3417            attach(path).map_err(|_| uri_err)?;
3418        }
3419        self.inner.attached.borrow_mut().push(alias.to_string());
3420        let Schema {
3421            installers, wirers, ..
3422        } = schema;
3423        for install in installers {
3424            install(self)?;
3425        }
3426        for wire in wirers {
3427            wire(self)?;
3428        }
3429        self.rescan()
3430    }
3431
3432    /// Detach a database [`ModelContainer::attach_database`] holds, dropping every resident
3433    /// row of its models. Their stores stay registered (empty), so a query over them answers
3434    /// nothing until the alias is attached again.
3435    pub fn detach_database(&self, alias: &str) -> Result<(), DbError> {
3436        let position = self.inner.attached.borrow().iter().position(|a| a == alias);
3437        let Some(position) = position else {
3438            return Ok(());
3439        };
3440        if !self.inner.dirty.borrow().is_empty() {
3441            self.save()?;
3442        }
3443        let prefix = format!("{alias}.");
3444        type Doomed = Vec<(Rc<dyn Fn() -> Vec<u64>>, EvictFn)>;
3445        let doomed: Doomed = self
3446            .inner
3447            .tables
3448            .borrow()
3449            .values()
3450            .filter(|h| h.table.starts_with(&prefix))
3451            .map(|h| (h.resident_keys.clone(), h.evict.clone()))
3452            .collect();
3453        for (keys, evict) in &doomed {
3454            let resident = keys();
3455            let _ = evict(&resident, resident.len());
3456        }
3457        self.conn()
3458            .execute(&format!("DETACH DATABASE {alias}"), &[])?;
3459        self.inner.attached.borrow_mut().remove(position);
3460        self.rescan()
3461    }
3462
3463    /// Look for other connections' committed writes (another process, a sync engine, a CLI)
3464    /// and merge what changed. Detection is one `PRAGMA data_version` (the counter moves only
3465    /// when another connection commits, never for this one's own writes), so this is cheap
3466    /// enough to wire to app foreground, window focus, or a timer.
3467    ///
3468    /// When the counter moved, pending local edits flush first; then the resident rows are
3469    /// re-read and diffed: changed fields announce per column, disappearances take the
3470    /// structural path, every live query re-derives, all authored
3471    /// [`ModelContainer::EXTERNAL_AUTHOR`], so the autosave fold declines the echo and an
3472    /// installed undo stack skips them (another author's writes are not the user's history).
3473    /// Rows that arrived elsewhere become visible through the re-run queries and fault in
3474    /// like any other row. A row another connection rewrote arrives whole, so its
3475    /// `#[model(transient)]` fields reset to their defaults, exactly as at fault.
3476    ///
3477    /// Returns whether anything arrived. On a driver without detection
3478    /// ([`Capabilities::external_changes`]) this is `Ok(false)`; writes made
3479    /// through [`ModelContainer::with_connection`] are this connection's own and stay
3480    /// [`ModelContainer::rescan`]'s job.
3481    pub fn check_external(&self) -> Result<bool, DbError> {
3482        if !self.inner.caps.external_changes {
3483            return Ok(false);
3484        }
3485        let Some(current) = self.file_data_version()? else {
3486            return Ok(false);
3487        };
3488        if self.inner.data_version.get() == Some(current) {
3489            return Ok(false);
3490        }
3491        // Local edits flush first, so the diff compares the file against a cache with nothing
3492        // pending: an unflushed local edit must not read as the other side's deletion.
3493        self.save()?;
3494        self.refresh_resident()?;
3495        self.invalidate_relation_memos();
3496        self.requery_all();
3497        // A commit matters even when it inserted only nonresident rows: count/projection
3498        // observers still need invalidation. Advance only after a successful merge so errors
3499        // remain retryable.
3500        self.inner.data_version.set(Some(current));
3501        Ok(true)
3502    }
3503
3504    /// `PRAGMA data_version`, or `None` where the engine did not answer (the Recorder).
3505    fn file_data_version(&self) -> Result<Option<i64>, DbError> {
3506        let mut v = None;
3507        self.conn().query("PRAGMA data_version", &[], &mut |row| {
3508            if let Ok(i) = row.get(0).as_int() {
3509                v = Some(i);
3510            }
3511        })?;
3512        Ok(v)
3513    }
3514
3515    /// Re-select every resident row and feed the differences through the caches: per-field
3516    /// announcements, external deletions, all authored [`ModelContainer::EXTERNAL_AUTHOR`].
3517    fn refresh_resident(&self) -> Result<bool, DbError> {
3518        struct RefreshJob {
3519            resident_keys: Rc<dyn Fn() -> Vec<u64>>,
3520            refresh: RefreshFn,
3521            columns: String,
3522            table: &'static str,
3523            keys_where: KeysWhere,
3524        }
3525        let jobs: Vec<RefreshJob> = {
3526            let tables = self.inner.tables.borrow();
3527            tables
3528                .values()
3529                .map(|h| RefreshJob {
3530                    resident_keys: h.resident_keys.clone(),
3531                    refresh: h.refresh.clone(),
3532                    columns: h.columns.join(", "),
3533                    table: h.table,
3534                    keys_where: keys_where_of(h),
3535                })
3536                .collect()
3537        };
3538        let mut changed = false;
3539        for RefreshJob {
3540            resident_keys,
3541            refresh,
3542            columns,
3543            table,
3544            keys_where,
3545        } in jobs
3546        {
3547            let resident = resident_keys();
3548            if resident.is_empty() {
3549                continue;
3550            }
3551            let mut rows: Vec<Vec<Value>> = Vec::new();
3552            for chunk in resident.chunks(MAX_BOUND_PARAMS / 2) {
3553                let (clause, params) = keys_where(chunk);
3554                self.conn().query(
3555                    &format!("SELECT {columns} FROM {table} WHERE {clause}"),
3556                    &params,
3557                    &mut |row| {
3558                        let n = Row::len(row);
3559                        rows.push((0..n).map(|i| row.get(i)).collect());
3560                    },
3561                )?;
3562            }
3563            // The connection borrow is released before refresh announces; a sink hearing
3564            // these changes may read back through SQL.
3565            if refresh(rows)? {
3566                changed = true;
3567            }
3568        }
3569        Ok(changed)
3570    }
3571
3572    fn install_state<M: Model>(
3573        &self,
3574        fetch: Fetch,
3575        raw: Option<RawQuery>,
3576        count_only: bool,
3577    ) -> Rc<QueryState> {
3578        let store = self.cache::<M>();
3579        let state = Rc::new(QueryState {
3580            store_id: store.store_id(),
3581            table: M::TABLE,
3582            watches: RefCell::new(Vec::new()),
3583            local_extra: RefCell::new(Vec::new()),
3584            set: RefCell::new(ResultSet::new(fetch.clone())),
3585            version: day_reactive::Scope::detached().enter(|| day_reactive::Signal::new(0)),
3586            pending: RefCell::new(QueryEvents::None),
3587            needs_sql: Cell::new(false),
3588            pending_commit: Cell::new(!self.inner.dirty.borrow().is_empty()),
3589            error: day_reactive::Scope::detached().enter(|| day_reactive::Signal::new(None)),
3590            raw,
3591            count_only,
3592            count: Cell::new(0),
3593        });
3594        self.rewire_watches(&state, &fetch);
3595        self.inner.queries.borrow_mut().push(Rc::downgrade(&state));
3596        // The seed: flush anything pending (with autosave; without it the query answers from
3597        // the last save, documented), then one SQL round trip.
3598        if self.inner.autosave.get() && !self.inner.dirty.borrow().is_empty() {
3599            let _ = self.save();
3600        }
3601        if count_only {
3602            state.count.set(self.answer_count(&state));
3603        } else {
3604            let ids = self.answer(&state);
3605            state.set.borrow_mut().reset(ids);
3606        }
3607        // The seed is the list's starting snapshot, not a stream of inserts to replay.
3608        *state.pending.borrow_mut() = QueryEvents::None;
3609        state
3610    }
3611
3612    fn install_query<M: Model>(&self, fetch: Fetch, raw: Option<RawQuery>) -> Query<M> {
3613        Query {
3614            state: self.install_state::<M>(fetch, raw, false),
3615            container: self.clone(),
3616            _p: std::marker::PhantomData,
3617        }
3618    }
3619
3620    /// (Re)compute a query's relation subscriptions from its fetch.
3621    fn rewire_watches(&self, state: &Rc<QueryState>, fetch: &Fetch) {
3622        let deps = fetch.dependencies();
3623        let mut watches: Vec<RelWatch> = Vec::new();
3624        let mut local_extra: Vec<&'static str> = Vec::new();
3625        let relations = self.inner.relations.borrow();
3626        let joins = self.inner.joins.borrow();
3627        for dep in &deps.related {
3628            let mut resolved = false;
3629            for r in relations.iter() {
3630                if r.parent_table == dep.owner && r.parent_field == dep.field {
3631                    watches.push(RelWatch {
3632                        store: r.child_store,
3633                        join_store: None,
3634                        fields: {
3635                            let mut f = vec![r.fk_field];
3636                            if let Some(o) = r.ordered {
3637                                f.push(o);
3638                            }
3639                            f
3640                        },
3641                        columns: dep.columns.clone(),
3642                    });
3643                    resolved = true;
3644                    break;
3645                }
3646                if r.child_table == dep.owner && r.fk_field == dep.field {
3647                    // The membership column lives on the query's table: a rewrite of the
3648                    // reference must mark it stale even though no predicate reads it.
3649                    if dep.owner == state.table && !local_extra.contains(&r.fk_col) {
3650                        local_extra.push(r.fk_col);
3651                    }
3652                    watches.push(RelWatch {
3653                        store: r.parent_store,
3654                        join_store: None,
3655                        fields: Vec::new(),
3656                        columns: dep.columns.clone(),
3657                    });
3658                    resolved = true;
3659                    break;
3660                }
3661            }
3662            if resolved {
3663                continue;
3664            }
3665            // A link: the far store's read columns matter, and so does the owner's value
3666            // column; rewriting it is what moves the row across the link.
3667            if let Some(l) = self
3668                .inner
3669                .links
3670                .borrow()
3671                .iter()
3672                .find(|l| l.owner_table == dep.owner && l.field == dep.field)
3673                .copied()
3674            {
3675                if dep.owner == state.table && !local_extra.contains(&l.local) {
3676                    local_extra.push(l.local);
3677                }
3678                let far = self
3679                    .inner
3680                    .tables
3681                    .borrow()
3682                    .iter()
3683                    .find(|(_, h)| h.table == l.target_table)
3684                    .map(|(id, _)| *id);
3685                if let Some(store) = far {
3686                    let mut columns = dep.columns.clone();
3687                    if !columns.contains(&l.remote) {
3688                        columns.push(l.remote);
3689                    }
3690                    watches.push(RelWatch {
3691                        store,
3692                        join_store: None,
3693                        fields: Vec::new(),
3694                        columns,
3695                    });
3696                }
3697                continue;
3698            }
3699            for j in joins.iter() {
3700                let side = if j.a_table == dep.owner && j.a_field == dep.field {
3701                    Some(j.b_store)
3702                } else if j.b_table == dep.owner && j.b_field.get() == Some(dep.field) {
3703                    Some(j.a_store)
3704                } else {
3705                    None
3706                };
3707                if let Some(other) = side {
3708                    watches.push(RelWatch {
3709                        store: other,
3710                        join_store: Some(j.join_store),
3711                        fields: Vec::new(),
3712                        columns: dep.columns.clone(),
3713                    });
3714                    break;
3715                }
3716            }
3717        }
3718        *state.watches.borrow_mut() = watches;
3719        *state.local_extra.borrow_mut() = local_extra;
3720    }
3721
3722    /// One announced change: decide, per live query, whether it can move the result, and
3723    /// mark stale where it can. No SQL runs here; the requery happens once, after the flush.
3724    fn mark_queries_stale(&self, change: &day_model::Change) {
3725        let Some(&store) = change.components.first() else {
3726            return;
3727        };
3728        let states: Vec<Rc<QueryState>> = {
3729            let mut queries = self.inner.queries.borrow_mut();
3730            queries.retain(|w| w.strong_count() > 0);
3731            queries.iter().filter_map(|w| w.upgrade()).collect()
3732        };
3733        if states.is_empty() {
3734            return;
3735        }
3736        let key = change.components.get(1).copied();
3737        if key == Some(day_model::STRUCTURE) {
3738            return; // the shape path duplicates the row paths
3739        }
3740        // The change log speaks field names; predicates speak column names.
3741        let (column, changed_table): (Option<String>, Option<&'static str>) = {
3742            let tables = self.inner.tables.borrow();
3743            let hooks = tables.get(&store);
3744            let column = if change.components.len() >= 3 {
3745                hooks.map(|h| {
3746                    h.fields
3747                        .iter()
3748                        .position(|f| f == change.label)
3749                        .map(|i| h.columns[i].clone())
3750                        // A transient field: never a dependency column.
3751                        .unwrap_or_else(|| "\u{0}".to_string())
3752                })
3753            } else {
3754                None
3755            };
3756            (column, hooks.map(|h| h.table))
3757        };
3758        let column = column.as_deref();
3759
3760        for state in &states {
3761            if state.needs_sql.get() {
3762                continue; // already stale; nothing to learn
3763            }
3764            if let Some(raw) = &state.raw {
3765                if changed_table.is_some_and(|t| raw.tables.iter().any(|r| r == t)) {
3766                    state.needs_sql.set(true);
3767                }
3768                continue;
3769            }
3770            // Both gates apply: a self-referential relation makes the query's own store a
3771            // related store too, so the own-table check must not shadow the watch check.
3772            let own_stale = state.store_id == store
3773                && match (key, change.op) {
3774                    (None, _) => true, // a wholesale rewrite: anything may have moved
3775                    (Some(_), Op::Insert) | (Some(_), Op::Delete) => true,
3776                    (Some(_), Op::Set) => match column {
3777                        // A row-level merge without a field name: assume the worst.
3778                        None => true,
3779                        Some(c) => {
3780                            let set = state.set.borrow();
3781                            set.deps().touches_local(c) || state.local_extra.borrow().contains(&c)
3782                        }
3783                    },
3784                    (Some(_), Op::Move) => false, // user order is not a query's business
3785                };
3786            let stale = own_stale || {
3787                let watches = state.watches.borrow();
3788                watches.iter().any(|w| {
3789                    if w.join_store == Some(store) {
3790                        return true; // every link/unlink/reposition is a membership change
3791                    }
3792                    if w.store != store {
3793                        return false;
3794                    }
3795                    match (key, change.op) {
3796                        (None, _) => true,
3797                        (Some(_), Op::Insert) | (Some(_), Op::Delete) => true,
3798                        (Some(_), Op::Set) => {
3799                            w.fields.contains(&change.label)
3800                                || column.is_some_and(|c| w.columns.contains(&c))
3801                        }
3802                        (Some(_), Op::Move) => false,
3803                    }
3804                })
3805            };
3806            if stale {
3807                state.needs_sql.set(true);
3808                state.pending_commit.set(true);
3809            }
3810        }
3811    }
3812
3813    /// After a flush: every stale query re-derives (plus raw queries whose tables the flush
3814    /// touched), each answer diffed into list deltas.
3815    fn run_deferred_requeries(&self, stmts: &[(String, Vec<Value>)]) {
3816        let states: Vec<Rc<QueryState>> = self
3817            .inner
3818            .queries
3819            .borrow()
3820            .iter()
3821            .filter_map(|w| w.upgrade())
3822            .collect();
3823        for state in states {
3824            let mut due = state.needs_sql.replace(false) | state.pending_commit.replace(false);
3825            if let Some(raw) = &state.raw
3826                && !due
3827            {
3828                due = stmts
3829                    .iter()
3830                    .any(|(sql, _)| raw.tables.iter().any(|t| statement_touches(sql, t)));
3831            }
3832            if due {
3833                self.requery(&state);
3834            }
3835        }
3836    }
3837
3838    /// Mark every query stale and requery now: the external-change and rescan path.
3839    fn requery_all(&self) {
3840        let states: Vec<Rc<QueryState>> = self
3841            .inner
3842            .queries
3843            .borrow()
3844            .iter()
3845            .filter_map(|w| w.upgrade())
3846            .collect();
3847        for state in states {
3848            state.needs_sql.set(false);
3849            self.requery(&state);
3850        }
3851    }
3852
3853    /// One requery: answer through the engine, adopt, narrate.
3854    fn requery(&self, state: &Rc<QueryState>) {
3855        if state.count_only {
3856            let n = self.answer_count(state);
3857            if n != state.count.get() {
3858                state.count.set(n);
3859                state
3860                    .version
3861                    .set(state.version.get_untracked().wrapping_add(1));
3862            }
3863            return;
3864        }
3865        let ids = self.answer(state);
3866        let change = state.set.borrow_mut().adopt(ids);
3867        match change {
3868            SetChange::Same => {}
3869            SetChange::Deltas(d) => {
3870                state.pending.borrow_mut().push(&d);
3871                state
3872                    .version
3873                    .set(state.version.get_untracked().wrapping_add(1));
3874            }
3875            SetChange::Reload => {
3876                state.pending.borrow_mut().reload();
3877                state
3878                    .version
3879                    .set(state.version.get_untracked().wrapping_add(1));
3880            }
3881        }
3882    }
3883
3884    /// Answer a COUNT-shaped fetch: one `SELECT COUNT(*)`, capped by the fetch's limit
3885    /// (a limited set's length is `min(count, limit)`). The fallback form counts its
3886    /// re-checked rows the same way.
3887    fn answer_count(&self, state: &Rc<QueryState>) -> usize {
3888        let result = (|| {
3889            if self.table_detached(state.table) {
3890                return Ok(0);
3891            }
3892            if let Some(raw) = &state.raw {
3893                return self
3894                    .select_ids_checked(&raw.sql, &raw.params)
3895                    .map(|ids| ids.len());
3896            }
3897            let fetch = state.set.borrow().fetch().clone();
3898            let cap = fetch.limit.unwrap_or(usize::MAX);
3899            let snapshot = self.sql_snapshot();
3900            match compile_count(state.table, &fetch, &snapshot) {
3901                Ok(q) => {
3902                    let mut n = Ok(0_i64);
3903                    self.conn().query(&q.sql, &q.params, &mut |row| {
3904                        n = row.get(0).as_int();
3905                    })?;
3906                    Ok((n?.max(0) as usize).min(cap))
3907                }
3908                Err(CompileErr::NeedsFold) => {
3909                    let (q, cols) = compile_fallback(state.table, &fetch, &snapshot)
3910                        .map_err(|e| DbError::new(DbErrorKind::Unsupported, e.message()))?;
3911                    let mut n = 0;
3912                    self.conn().query(&q.sql, &q.params, &mut |row| {
3913                        let values = (0..row.len()).map(|i| row.get(i)).collect::<Vec<_>>();
3914                        if let Some(h) = value_to_handle(&values[0])
3915                            && fetch.pred.eval(
3916                                h,
3917                                &FallbackRow {
3918                                    cols: &cols,
3919                                    values: &values,
3920                                },
3921                            )
3922                        {
3923                            n += 1;
3924                        }
3925                    })?;
3926                    Ok(n.min(cap))
3927                }
3928                Err(e) => Err(DbError::new(DbErrorKind::Unsupported, e.message())),
3929            }
3930        })();
3931        match result {
3932            Ok(n) => {
3933                state.error.set(None);
3934                n
3935            }
3936            Err(error) => {
3937                self.inner.error.set(Some(error.to_string()));
3938                state.error.set(Some(error));
3939                state.count.get()
3940            }
3941        }
3942    }
3943
3944    /// Answer a query's fetch through the engine: the compiled form, the fallback form for
3945    /// drivers without `day_fold`, or the raw statement.
3946    fn answer(&self, state: &Rc<QueryState>) -> Vec<u64> {
3947        match self.answer_checked(state) {
3948            Ok(ids) => {
3949                state.error.set(None);
3950                ids
3951            }
3952            Err(error) => {
3953                self.inner.error.set(Some(error.to_string()));
3954                state.error.set(Some(error));
3955                // A failed read is not an empty result. Retain the last successful set.
3956                state.set.borrow().ids().to_vec()
3957            }
3958        }
3959    }
3960    fn table_detached(&self, table: &str) -> bool {
3961        table.split_once('.').is_some_and(|(alias, _)| {
3962            alias != "main"
3963                && alias != "temp"
3964                && !self.inner.attached.borrow().iter().any(|a| a == alias)
3965        })
3966    }
3967    fn answer_checked(&self, state: &Rc<QueryState>) -> Result<Vec<u64>, DbError> {
3968        // Explicit detachment is a successful transition to an empty catalog, not an I/O error.
3969        if self.table_detached(state.table) {
3970            return Ok(Vec::new());
3971        }
3972        if let Some(raw) = &state.raw {
3973            return self.select_ids_checked(&raw.sql, &raw.params);
3974        }
3975        let fetch = state.set.borrow().fetch().clone();
3976        let snapshot = self.sql_snapshot();
3977        match compile_fetch(state.table, &fetch, &snapshot) {
3978            Ok(q) => self.select_ids_checked(&q.sql, &q.params),
3979            Err(CompileErr::NeedsFold) => {
3980                let (q, cols) = compile_fallback(state.table, &fetch, &snapshot)
3981                    .map_err(|e| DbError::new(DbErrorKind::Unsupported, e.message()))?;
3982                let mut ids = Vec::new();
3983                self.conn().query(&q.sql, &q.params, &mut |row| {
3984                    let values = (0..row.len()).map(|i| row.get(i)).collect::<Vec<_>>();
3985                    if let Some(h) = value_to_handle(&values[0])
3986                        && fetch.pred.eval(
3987                            h,
3988                            &FallbackRow {
3989                                cols: &cols,
3990                                values: &values,
3991                            },
3992                        )
3993                    {
3994                        ids.push(h);
3995                    }
3996                })?;
3997                if let Some(limit) = fetch.limit {
3998                    ids.truncate(limit);
3999                }
4000                Ok(ids)
4001            }
4002            Err(e) => Err(DbError::new(DbErrorKind::Unsupported, e.message())),
4003        }
4004    }
4005
4006    /// A point-in-time view of names for the SQL compiler: tables, keys, shadows, wired
4007    /// relations, and whether the driver folds case.
4008    fn sql_snapshot(&self) -> SqlSnapshot {
4009        let tables = self.inner.tables.borrow();
4010        let relations = self.inner.relations.borrow();
4011        let joins = self.inner.joins.borrow();
4012        SqlSnapshot {
4013            tables: tables
4014                .values()
4015                .map(|h| TableInfo {
4016                    table: h.table.to_string(),
4017                    key: h.key_cols[0].clone(),
4018                    fts: h.fts.clone(),
4019                    fts_key: h.fts_key,
4020                    spatial: h.spatial.clone(),
4021                })
4022                .collect(),
4023            rels: relations
4024                .iter()
4025                .map(|r| RelInfo {
4026                    parent_table: r.parent_table,
4027                    parent_field: r.parent_field,
4028                    parent_key: r.parent_key_col,
4029                    child_table: r.child_table,
4030                    child_key: r.child_key_col,
4031                    fk_field: r.fk_field,
4032                    fk_col: r.fk_col,
4033                })
4034                .collect(),
4035            joins: joins
4036                .iter()
4037                .map(|j| JoinInfo {
4038                    join_table: j.join_table,
4039                    a_table: j.a_table,
4040                    a_field: j.a_field,
4041                    a_key: j.a_key_col,
4042                    b_table: j.b_table,
4043                    b_field: j.b_field.get(),
4044                    b_key: j.b_key_col,
4045                    parent_col: j.parent_col,
4046                    child_col: j.child_col,
4047                })
4048                .collect(),
4049            links: self.inner.links.borrow().clone(),
4050            fold: self.inner.caps.unicode_fold,
4051        }
4052    }
4053}
4054
4055struct TableInfo {
4056    table: String,
4057    key: String,
4058    fts: Option<String>,
4059    fts_key: &'static str,
4060    spatial: Option<(String, String, String)>,
4061}
4062
4063struct RelInfo {
4064    parent_table: &'static str,
4065    parent_field: &'static str,
4066    parent_key: &'static str,
4067    child_table: &'static str,
4068    child_key: &'static str,
4069    fk_field: &'static str,
4070    fk_col: &'static str,
4071}
4072
4073struct JoinInfo {
4074    join_table: &'static str,
4075    a_table: &'static str,
4076    a_field: &'static str,
4077    a_key: &'static str,
4078    b_table: &'static str,
4079    b_field: Option<&'static str>,
4080    b_key: &'static str,
4081    parent_col: &'static str,
4082    child_col: &'static str,
4083}
4084
4085struct SqlSnapshot {
4086    tables: Vec<TableInfo>,
4087    rels: Vec<RelInfo>,
4088    joins: Vec<JoinInfo>,
4089    links: Vec<LinkInfo>,
4090    fold: bool,
4091}
4092
4093impl SqlIndex for SqlSnapshot {
4094    fn relation(&self, owner: &str, field: &str) -> Option<RelSql> {
4095        for r in &self.rels {
4096            if r.parent_table == owner && r.parent_field == field {
4097                return Some(RelSql::Children {
4098                    target_key: r.child_key.to_string(),
4099                    fk_col: r.fk_col.to_string(),
4100                    owner_key: r.parent_key.to_string(),
4101                });
4102            }
4103            if r.child_table == owner && r.fk_field == field {
4104                return Some(RelSql::Referent {
4105                    target_key: r.parent_key.to_string(),
4106                    fk_col: r.fk_col.to_string(),
4107                });
4108            }
4109        }
4110        for j in &self.joins {
4111            if j.a_table == owner && j.a_field == field {
4112                return Some(RelSql::Join {
4113                    join_table: j.join_table.to_string(),
4114                    owner_col: j.parent_col.to_string(),
4115                    target_col: j.child_col.to_string(),
4116                    owner_key: j.a_key.to_string(),
4117                    target_key: j.b_key.to_string(),
4118                });
4119            }
4120            if j.b_table == owner && j.b_field == Some(field) {
4121                return Some(RelSql::Join {
4122                    join_table: j.join_table.to_string(),
4123                    owner_col: j.child_col.to_string(),
4124                    target_col: j.parent_col.to_string(),
4125                    owner_key: j.b_key.to_string(),
4126                    target_key: j.a_key.to_string(),
4127                });
4128            }
4129        }
4130        for l in &self.links {
4131            if l.owner_table == owner && l.field == field {
4132                return Some(RelSql::Linked {
4133                    local_col: l.local.to_string(),
4134                    remote_col: l.remote.to_string(),
4135                    target_key: self.key_of(l.target_table)?,
4136                });
4137            }
4138        }
4139        None
4140    }
4141
4142    fn key_of(&self, table: &str) -> Option<String> {
4143        self.tables
4144            .iter()
4145            .find(|t| t.table == table)
4146            .map(|t| t.key.clone())
4147    }
4148
4149    fn fts_of(&self, table: &str) -> Option<String> {
4150        self.tables
4151            .iter()
4152            .find(|t| t.table == table)
4153            .and_then(|t| t.fts.clone())
4154    }
4155
4156    fn fts_key_of(&self, table: &str) -> &str {
4157        self.tables
4158            .iter()
4159            .find(|t| t.table == table)
4160            .map(|t| t.fts_key)
4161            .unwrap_or("rowid")
4162    }
4163
4164    fn geo_of(&self, table: &str, lat: &str, lon: &str) -> Option<String> {
4165        self.tables
4166            .iter()
4167            .find(|t| t.table == table)
4168            .and_then(|t| t.spatial.as_ref())
4169            .filter(|(a, o, _)| a == lat && o == lon)
4170            .map(|(_, _, g)| g.clone())
4171    }
4172
4173    fn unicode_fold(&self) -> bool {
4174        self.fold
4175    }
4176}
4177
4178/// Whether a statement's target table is `table`, a plain-text check over the SQL the fold
4179/// itself produced (`INSERT INTO t … ON CONFLICT`, `UPDATE t SET …`, `DELETE FROM t …`).
4180fn statement_touches(sql: &str, table: &str) -> bool {
4181    for prefix in [
4182        "INSERT INTO ",
4183        "INSERT OR REPLACE INTO ",
4184        "UPDATE ",
4185        "DELETE FROM ",
4186    ] {
4187        if let Some(rest) = sql.strip_prefix(prefix) {
4188            return rest.split([' ', '(']).next() == Some(table);
4189        }
4190    }
4191    false
4192}
4193
4194// ---------------------------------------------------------------------------
4195// Query as a list row source (feature `pieces`)
4196// ---------------------------------------------------------------------------
4197
4198#[cfg(feature = "pieces")]
4199mod pieces_glue {
4200    use std::cell::RefCell;
4201
4202    use day_model::{Elem, Keyed, Store};
4203    use day_pieces::{ModelSlot, RowConn, RowSource};
4204
4205    use crate::{Delta, Model, Query, QueryEvents};
4206
4207    /// How far around a bound row the list source faults in one batch: the price of showing
4208    /// row N is one `SELECT` that also covers the rows about to scroll in.
4209    const FAULT_BEHIND: usize = 16;
4210    const FAULT_AHEAD: usize = 64;
4211
4212    /// `list(query, row)`: the query's ids are the display order, rows fault in as the list
4213    /// binds them (a window at a time), and set changes arrive as row deltas the native list
4214    /// can animate.
4215    impl<M: Model> RowSource for Query<M> {
4216        type Slot = ModelSlot<M>;
4217        type Ref = Elem<M>;
4218        type Conn = QueryConn<M>;
4219        fn connect(self) -> QueryConn<M> {
4220            let store = self.container.cache::<M>();
4221            QueryConn {
4222                query: self,
4223                store,
4224                keys: RefCell::new(Vec::new()),
4225            }
4226        }
4227    }
4228
4229    pub struct QueryConn<M: Model> {
4230        query: Query<M>,
4231        store: Store<Keyed<M>>,
4232        keys: RefCell<Vec<u64>>,
4233    }
4234
4235    impl<M: Model> QueryConn<M> {
4236        /// Make the row at `index` (and its neighborhood) resident before anything binds it.
4237        fn fault_window(&self, index: usize) {
4238            let len = self.keys.borrow().len();
4239            let start = index.saturating_sub(FAULT_BEHIND);
4240            let end = (index + FAULT_AHEAD).min(len);
4241            self.query.materialize(start..end);
4242        }
4243    }
4244
4245    impl<M: Model> RowConn for QueryConn<M> {
4246        type Slot = ModelSlot<M>;
4247        type Ref = Elem<M>;
4248
4249        fn refresh(&self) -> Vec<u64> {
4250            let keys: Vec<u64> = self.query.ids().iter().map(|id| id.handle()).collect();
4251            *self.keys.borrow_mut() = keys.clone();
4252            keys
4253        }
4254        fn len(&self) -> usize {
4255            self.keys.borrow().len()
4256        }
4257        fn token_at(&self, index: usize) -> u64 {
4258            self.keys.borrow().get(index).copied().unwrap_or(0)
4259        }
4260        fn tokens_now(&self) -> Vec<u64> {
4261            self.keys.borrow().clone()
4262        }
4263        fn slot_at(&self, index: usize) -> Option<ModelSlot<M>> {
4264            let key = self.keys.borrow().get(index).copied()?;
4265            if !self.store.with_untracked(|k| k.get(key).is_some()) {
4266                self.fault_window(index);
4267            }
4268            Some(ModelSlot::for_key(self.store, key))
4269        }
4270        fn rebind(&self, slot: &ModelSlot<M>, index: usize) {
4271            if let Some(key) = self.keys.borrow().get(index).copied() {
4272                if !self.store.with_untracked(|k| k.get(key).is_some()) {
4273                    self.fault_window(index);
4274                }
4275                slot.rebind_key(key);
4276            }
4277        }
4278        fn select_ref(&self, index: usize) -> Option<Elem<M>> {
4279            let key = self.keys.borrow().get(index).copied()?;
4280            if !self.store.with_untracked(|k| k.get(key).is_some()) {
4281                self.fault_window(index);
4282            }
4283            Some(self.store.elem(key))
4284        }
4285        fn values_flow_by_reload(&self) -> bool {
4286            false // row values flow through the store's own per-field notifications
4287        }
4288        fn take_row_events(&self) -> Option<Vec<day_spec::props::RowDelta>> {
4289            match self.query.take_events() {
4290                QueryEvents::Deltas(d) => Some(
4291                    d.into_iter()
4292                        .map(|d| match d {
4293                            Delta::Insert(i, _) => day_spec::props::RowDelta::Insert(i),
4294                            Delta::Remove(i, _) => day_spec::props::RowDelta::Remove(i),
4295                            Delta::Move(from, to, _) => day_spec::props::RowDelta::Move(from, to),
4296                        })
4297                        .collect(),
4298                ),
4299                // Reload means "the whole set moved"; None here means the same to the list.
4300                QueryEvents::Reload | QueryEvents::None => None,
4301            }
4302        }
4303        fn commit_move(&self, from: usize, to: usize) {
4304            // The native drag already moved the row: serve that order until the app's write
4305            // (its on_reorder, typically a rank column the query sorts by) requeries. The list
4306            // expects exactly this order back as the echo of its own move; left unrotated, the
4307            // echo never matched, and the query's own move was replayed on rows already moved.
4308            let mut keys = self.keys.borrow_mut();
4309            if from < keys.len() && to < keys.len() {
4310                let key = keys.remove(from);
4311                keys.insert(to, key);
4312            }
4313        }
4314        fn commit_delete(&self, index: usize) {
4315            // The native delete affordance: drop from the local snapshot; the app's on_delete
4316            // writes the store, and the query's own delta follows as the echo.
4317            let mut keys = self.keys.borrow_mut();
4318            if index < keys.len() {
4319                keys.remove(index);
4320            }
4321        }
4322    }
4323}
4324
4325#[cfg(feature = "pieces")]
4326pub use pieces_glue::QueryConn;
4327
4328// ---------------------------------------------------------------------------
4329// Date and time codecs (feature `datetime`; docs/persistence.md)
4330// ---------------------------------------------------------------------------
4331
4332/// Column codecs for day::datetime's [`DayDate`](day_spec::controls::datetime::DayDate) and
4333/// [`DayTime`](day_spec::controls::datetime::DayTime), for `#[derive(Model)]` fields.
4334///
4335/// Canonical, what a bare field of the type stores: `DayDate` → `INTEGER` epoch days,
4336/// `DayTime` → `INTEGER` seconds-of-day: the same numeric interchange forms the pickers
4337/// already speak across native boundaries, and both sort chronologically as plain integers.
4338///
4339/// Named, picked per field with `#[model(with = …)]`: [`Iso8601`](datetime::Iso8601) stores
4340/// `TEXT` in the form `Display` writes (readable in any sqlite tool, and lexicographic order
4341/// is chronological order, ISO-8601's design goal); [`EpochSeconds`](datetime::EpochSeconds)
4342/// and [`EpochMillis`](datetime::EpochMillis) store the `INTEGER` a server that speaks Unix
4343/// time expects, midnight-of-day for a `DayDate`.
4344///
4345/// The impls live here rather than in the piece because one of the two crates has to own
4346/// them, and this is the one that depends on the other.
4347#[cfg(feature = "datetime")]
4348pub mod datetime {
4349    use crate::{ColumnValue, DbError, DbErrorKind, SqlType, Value, ValueCodec};
4350    use day_spec::controls::datetime::{DayDate, DayTime};
4351
4352    impl ColumnValue for DayDate {
4353        const SQL_TYPE: SqlType = SqlType::Integer;
4354        fn to_sqlite_value(&self) -> Value {
4355            Value::Int(self.to_epoch_days())
4356        }
4357        fn from_sqlite_value(v: Value) -> Result<Self, DbError> {
4358            Ok(DayDate::from_epoch_days(v.as_int()?))
4359        }
4360    }
4361
4362    impl ColumnValue for DayTime {
4363        const SQL_TYPE: SqlType = SqlType::Integer;
4364        fn to_sqlite_value(&self) -> Value {
4365            Value::Int(self.seconds_of_day())
4366        }
4367        fn from_sqlite_value(v: Value) -> Result<Self, DbError> {
4368            Ok(DayTime::from_seconds_of_day(v.as_int()?))
4369        }
4370    }
4371
4372    /// `TEXT` in the `Display` form: `YYYY-MM-DD` for a date, `HH:MM[:SS]` for a time.
4373    pub struct Iso8601;
4374
4375    impl ValueCodec<DayDate> for Iso8601 {
4376        const SQL_TYPE: SqlType = SqlType::Text;
4377        fn to_sqlite_value(v: &DayDate) -> Value {
4378            Value::Text(v.to_string())
4379        }
4380        fn from_sqlite_value(v: Value) -> Result<DayDate, DbError> {
4381            let s = v.as_text()?;
4382            DayDate::parse_iso(s).ok_or_else(|| {
4383                DbError::new(DbErrorKind::Decode, format!("not an ISO-8601 date: {s:?}"))
4384            })
4385        }
4386    }
4387
4388    impl ValueCodec<DayTime> for Iso8601 {
4389        const SQL_TYPE: SqlType = SqlType::Text;
4390        fn to_sqlite_value(v: &DayTime) -> Value {
4391            Value::Text(v.to_string())
4392        }
4393        fn from_sqlite_value(v: Value) -> Result<DayTime, DbError> {
4394            let s = v.as_text()?;
4395            DayTime::parse_iso(s).ok_or_else(|| {
4396                DbError::new(DbErrorKind::Decode, format!("not an ISO-8601 time: {s:?}"))
4397            })
4398        }
4399    }
4400
4401    /// `INTEGER` seconds since 1970-01-01T00:00Z; midnight of the day, for a [`DayDate`].
4402    pub struct EpochSeconds;
4403
4404    impl ValueCodec<DayDate> for EpochSeconds {
4405        const SQL_TYPE: SqlType = SqlType::Integer;
4406        fn to_sqlite_value(v: &DayDate) -> Value {
4407            Value::Int(v.to_epoch_days() * 86_400)
4408        }
4409        fn from_sqlite_value(v: Value) -> Result<DayDate, DbError> {
4410            Ok(DayDate::from_epoch_days(v.as_int()?.div_euclid(86_400)))
4411        }
4412    }
4413
4414    /// `INTEGER` milliseconds since the same epoch, for interop that expects it.
4415    pub struct EpochMillis;
4416
4417    impl ValueCodec<DayDate> for EpochMillis {
4418        const SQL_TYPE: SqlType = SqlType::Integer;
4419        fn to_sqlite_value(v: &DayDate) -> Value {
4420            Value::Int(v.to_epoch_days() * 86_400_000)
4421        }
4422        fn from_sqlite_value(v: Value) -> Result<DayDate, DbError> {
4423            Ok(DayDate::from_epoch_days(v.as_int()?.div_euclid(86_400_000)))
4424        }
4425    }
4426}
4427
4428#[cfg(all(test, feature = "driver-rusqlite"))]
4429mod eviction_tests;