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::{
70    CompileErr, FtsSql, RelSql, SqlIndex, compile_count, compile_fallback, compile_fetch,
71};
72
73mod blob;
74pub use blob::{Blob, BlobField, BlobReader};
75mod relations;
76pub use relations::{
77    DeleteRule, Many, One, Registrar, RelationDef, RelationRef, wire_join, wire_to_many,
78};
79
80#[cfg(feature = "driver-rusqlite")]
81mod rusqlite_driver;
82#[cfg(feature = "driver-rusqlite")]
83pub use rusqlite_driver::Sqlite;
84#[cfg(all(
85    feature = "driver-rusqlite",
86    target_family = "wasm",
87    target_os = "unknown"
88))]
89pub use rusqlite_driver::WebStorage;
90
91/// The derive for the [`Model`] trait (the two share a name, so `use day_persistence::Model`
92/// brings both): everything `#[derive(Observable)]` generates plus the schema half.
93/// `#[model(id)]` marks the key; docs/persistence.md lists the field and struct options.
94pub use day_persistence_macros::Model;
95
96// `#[derive(Model)]` expands its observable half to this (day-macros' `observable_impls!`),
97// reached by this crate's name so a model crate needs no day-macros dependency of its own.
98#[doc(hidden)]
99pub use day_macros::observable_impls as __observable_impls;
100
101/// What a model module starts from: `use day_persistence::prelude::*;` beside the app's `use
102/// day::prelude::*;`. The container, the `Model` trait and its derive, the relation markers,
103/// the drivers and `schema!`.
104pub mod prelude {
105    #[cfg(feature = "driver-rusqlite")]
106    pub use crate::Sqlite;
107    pub use crate::{DeleteRule, Many, Model, ModelContainer, One, Recorder, Secret, schema};
108}
109
110// ---------------------------------------------------------------------------
111// Errors
112// ---------------------------------------------------------------------------
113
114/// Why a persistence operation failed. `message` is for the log; `kind` is for the code path
115/// that can do something about it.
116#[derive(Clone, Debug)]
117pub struct DbError {
118    pub kind: DbErrorKind,
119    pub message: String,
120}
121
122#[derive(Clone, Copy, PartialEq, Eq, Debug)]
123pub enum DbErrorKind {
124    /// An asynchronous request was rejected because its worker has closed.
125    Closed,
126    /// The bounded worker queue has no room; the request was not accepted.
127    Busy,
128    /// A queued read was cancelled before it began.
129    Cancelled,
130    /// A worker operation panicked. The worker is closed and must be reopened.
131    Panicked,
132    /// The transaction committed, but refreshing resident models failed. Do not replay the
133    /// write. Recover the cache with `rescan` before editing; workers retry before their next job.
134    CommittedRefreshFailed,
135    /// The engine said no: SQL error, I/O, constraint.
136    Driver,
137    /// The stored schema and the declared one disagree in a way lightweight migration cannot
138    /// close (a type change, a rename); the file is refused, never silently rewritten.
139    Schema,
140    /// The database would not open with the key it was given.
141    BadKey,
142    /// A stored value would not decode as the field's type.
143    Decode,
144    /// The driver cannot do this (encryption on a non-cipher build, …).
145    Unsupported,
146    /// A `DeleteRule::Deny` relation refused the delete: children still reference the row.
147    Deny,
148}
149
150impl DbError {
151    pub fn new(kind: DbErrorKind, message: impl Into<String>) -> Self {
152        DbError {
153            kind,
154            message: message.into(),
155        }
156    }
157    /// Engine-error shorthand for driver implementations (public: external drivers use it too).
158    pub fn driver(message: impl Into<String>) -> Self {
159        Self::new(DbErrorKind::Driver, message)
160    }
161}
162
163impl fmt::Display for DbError {
164    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
165        write!(f, "{:?}: {}", self.kind, self.message)
166    }
167}
168
169impl std::error::Error for DbError {}
170
171// ---------------------------------------------------------------------------
172// Values and rows
173// ---------------------------------------------------------------------------
174
175/// SQLite's five storage classes, and nothing else; no driver type reaches the layer above.
176#[derive(Clone, Debug, PartialEq)]
177pub enum Value {
178    Null,
179    Int(i64),
180    Real(f64),
181    Text(String),
182    Blob(Vec<u8>),
183}
184
185impl Value {
186    pub fn as_int(&self) -> Result<i64, DbError> {
187        match self {
188            Value::Int(i) => Ok(*i),
189            other => Err(DbError::new(
190                DbErrorKind::Decode,
191                format!("expected INTEGER, found {other:?}"),
192            )),
193        }
194    }
195    pub fn as_real(&self) -> Result<f64, DbError> {
196        match self {
197            Value::Real(r) => Ok(*r),
198            Value::Int(i) => Ok(*i as f64),
199            other => Err(DbError::new(
200                DbErrorKind::Decode,
201                format!("expected REAL, found {other:?}"),
202            )),
203        }
204    }
205    pub fn as_text(&self) -> Result<&str, DbError> {
206        match self {
207            Value::Text(t) => Ok(t),
208            other => Err(DbError::new(
209                DbErrorKind::Decode,
210                format!("expected TEXT, found {other:?}"),
211            )),
212        }
213    }
214    pub fn as_blob(&self) -> Result<&[u8], DbError> {
215        match self {
216            Value::Blob(b) => Ok(b),
217            other => Err(DbError::new(
218                DbErrorKind::Decode,
219                format!("expected BLOB, found {other:?}"),
220            )),
221        }
222    }
223}
224
225/// A column's declared type. Part of the schema fingerprint, so changing one is a migration.
226#[derive(Clone, Copy, PartialEq, Eq, Debug)]
227pub enum SqlType {
228    Integer,
229    Real,
230    Text,
231    Blob,
232}
233
234impl SqlType {
235    pub fn ddl(self) -> &'static str {
236        match self {
237            SqlType::Integer => "INTEGER",
238            SqlType::Real => "REAL",
239            SqlType::Text => "TEXT",
240            SqlType::Blob => "BLOB",
241        }
242    }
243}
244
245/// One result row, by position.
246pub trait Row {
247    fn len(&self) -> usize;
248    fn get(&self, i: usize) -> Value;
249    fn is_empty(&self) -> bool {
250        self.len() == 0
251    }
252}
253
254impl Row for Vec<Value> {
255    fn len(&self) -> usize {
256        Vec::len(self)
257    }
258    fn get(&self, i: usize) -> Value {
259        self.as_slice().get(i).cloned().unwrap_or(Value::Null)
260    }
261}
262
263// ---------------------------------------------------------------------------
264// The driver interface
265// ---------------------------------------------------------------------------
266
267/// Where the database lives.
268#[derive(Clone, Debug)]
269pub enum Location {
270    Memory,
271    File(PathBuf),
272}
273
274/// A key for an encrypted database. Redacted in Debug and zeroed on drop; where it lives
275/// between launches is the app's business, never this crate's.
276#[derive(Clone)]
277pub struct Secret(String);
278
279impl Secret {
280    pub fn new(key: impl Into<String>) -> Self {
281        Secret(key.into())
282    }
283    #[cfg(feature = "cipher")]
284    pub(crate) fn reveal(&self) -> &str {
285        &self.0
286    }
287}
288
289impl fmt::Debug for Secret {
290    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
291        f.write_str("Secret(…)")
292    }
293}
294
295impl Drop for Secret {
296    fn drop(&mut self) {
297        // Best-effort scrub; the allocation may have been moved by earlier clones.
298        unsafe {
299            // SAFETY: we own the String and overwrite only its initialized bytes in place.
300            for b in self.0.as_bytes_mut() {
301                *b = 0;
302            }
303        }
304    }
305}
306
307/// How to open the database. Built by the driver's own constructors ([`Sqlite::at`] etc.);
308/// public so alternative drivers speak the same vocabulary.
309#[derive(Clone, Debug)]
310pub struct OpenOptions {
311    pub location: Location,
312    /// SQLCipher key; drivers without encryption reject it loudly.
313    pub key: Option<Secret>,
314    /// Journal in WAL mode (files only; ignored in memory). Default true.
315    pub wal: bool,
316    /// Enforce foreign keys. Default true.
317    pub foreign_keys: bool,
318    pub busy_timeout_ms: u32,
319    /// Upgrade a file written by an older SQLCipher generation (PRAGMA cipher_migrate).
320    pub cipher_migrate: bool,
321}
322
323impl OpenOptions {
324    pub fn new(location: Location) -> Self {
325        OpenOptions {
326            location,
327            key: None,
328            wal: true,
329            foreign_keys: true,
330            busy_timeout_ms: 5_000,
331            cipher_migrate: false,
332        }
333    }
334}
335
336/// What a driver can and cannot do, so the container degrades visibly instead of silently.
337#[derive(Clone, Copy, Debug, Default)]
338pub struct Capabilities {
339    /// Survives a relaunch (false for memory stores and the Recorder).
340    pub durable: bool,
341    pub encryption: bool,
342    pub wal: bool,
343    pub full_text_search: bool,
344    pub rtree: bool,
345    /// Another connection's committed writes are detectable (SQLite's `PRAGMA data_version`
346    /// counter), so [`ModelContainer::check_external`] can merge them. The built-in driver
347    /// claims it for file databases on native targets; memory databases (no second connection
348    /// can reach one), the Recorder, and the web engine (its OPFS access is exclusive) do not.
349    pub external_changes: bool,
350    /// The connection has `day_fold` registered (Rust's full-Unicode `to_lowercase` as a
351    /// scalar SQL function), so case-insensitive text predicates compile to exact SQL. The
352    /// built-in native driver registers it at open; without it those predicates take the
353    /// fallback path (SQL for everything else, the folding test re-checked in memory).
354    pub unicode_fold: bool,
355}
356
357/// What `PRAGMA wal_checkpoint(TRUNCATE)` answered ([`ModelContainer::checkpoint`]): the
358/// three columns of its status row. The engine reads the counts after the checkpoint, so a
359/// completed one answers `0` and `0` (the log was emptied); a busy one describes the log it
360/// had to leave behind. Both counts are `-1` when the database is not in WAL mode (a memory
361/// database, or `wal: false`).
362#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
363pub struct Checkpoint {
364    /// A reader or writer kept the checkpoint from completing within the busy timeout; the
365    /// WAL was folded as far as it could be and the rest waits for the next call.
366    pub busy: bool,
367    /// Frames in the WAL when the checkpoint finished.
368    pub log_frames: i64,
369    /// Frames of that log already carried into the main file.
370    pub checkpointed_frames: i64,
371}
372
373impl Checkpoint {
374    /// The whole log was folded and truncated.
375    pub fn is_complete(&self) -> bool {
376        !self.busy
377    }
378}
379
380/// One row of `PRAGMA foreign_key_check` ([`ModelContainer::foreign_key_check`]): a child
381/// row whose reference names no parent.
382#[derive(Clone, Debug, PartialEq, Eq)]
383pub struct ForeignKeyViolation {
384    /// The child table.
385    pub table: String,
386    /// The child row's rowid; `None` for a `WITHOUT ROWID` table.
387    pub rowid: Option<i64>,
388    /// The parent table the reference names.
389    pub parent: String,
390    /// The constraint's index in the child's `PRAGMA foreign_key_list`.
391    pub constraint: i64,
392}
393
394impl fmt::Display for ForeignKeyViolation {
395    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
396        match self.rowid {
397            Some(rowid) => write!(
398                f,
399                "foreign key: {} row {rowid} references missing {}",
400                self.table, self.parent
401            ),
402            None => write!(
403                f,
404                "foreign key: {} row references missing {}",
405                self.table, self.parent
406            ),
407        }
408    }
409}
410
411/// The engine trait. Object-safe on the connection side, so the container stores
412/// `Box<dyn SqliteConnection>` and never names an engine type.
413pub trait SqliteDriver {
414    type Connection: SqliteConnection;
415    fn open(self) -> Result<Self::Connection, DbError>;
416    fn capabilities(&self) -> Capabilities;
417}
418
419impl SqliteConnection for Box<dyn SqliteConnection> {
420    fn execute(&mut self, sql: &str, params: &[Value]) -> Result<u64, DbError> {
421        (**self).execute(sql, params)
422    }
423    fn query(
424        &mut self,
425        sql: &str,
426        params: &[Value],
427        row: &mut dyn FnMut(&dyn Row),
428    ) -> Result<(), DbError> {
429        (**self).query(sql, params, row)
430    }
431    fn execute_batch(&mut self, sql: &str) -> Result<(), DbError> {
432        (**self).execute_batch(sql)
433    }
434    fn query_named(
435        &mut self,
436        sql: &str,
437        params: &[Value],
438        row: &mut dyn FnMut(&[String], &dyn Row),
439    ) -> Result<(), DbError> {
440        (**self).query_named(sql, params, row)
441    }
442}
443
444/// One open connection. Everything above speaks plain SQL and [`Value`]s through it.
445pub trait SqliteConnection: 'static {
446    fn execute(&mut self, sql: &str, params: &[Value]) -> Result<u64, DbError>;
447    fn query(
448        &mut self,
449        sql: &str,
450        params: &[Value],
451        row: &mut dyn FnMut(&dyn Row),
452    ) -> Result<(), DbError>;
453    fn begin(&mut self) -> Result<(), DbError> {
454        self.execute("BEGIN", &[]).map(|_| ())
455    }
456    fn commit(&mut self) -> Result<(), DbError> {
457        self.execute("COMMIT", &[]).map(|_| ())
458    }
459    fn rollback(&mut self) -> Result<(), DbError> {
460        self.execute("ROLLBACK", &[]).map(|_| ())
461    }
462    /// Several statements in one string, no parameters: a DDL script, a migration step
463    /// (day-lite's storage speaks this). The default runs the string as one statement;
464    /// drivers whose engine executes scripts override it (the built-in native driver does).
465    fn execute_batch(&mut self, sql: &str) -> Result<(), DbError> {
466        self.execute(sql, &[]).map(|_| ())
467    }
468    /// [`SqliteConnection::query`], with the result's column names alongside each row, for
469    /// callers that surface rows as named objects (day-lite's JS bridge). A driver that
470    /// cannot name columns refuses rather than guessing.
471    fn query_named(
472        &mut self,
473        sql: &str,
474        params: &[Value],
475        row: &mut dyn FnMut(&[String], &dyn Row),
476    ) -> Result<(), DbError> {
477        let _ = (sql, params, row);
478        Err(DbError::new(
479            DbErrorKind::Unsupported,
480            "this driver does not report column names",
481        ))
482    }
483}
484
485// ---------------------------------------------------------------------------
486// The Recorder: the headless fake
487// ---------------------------------------------------------------------------
488
489/// A driver that answers from fixtures and records every statement: the piece that keeps
490/// persistence assertable with no database on disk. `let (driver, log) = Recorder::new();`
491///
492/// Fixtures answer by table, not by statement: any `SELECT … FROM <table>` serves every
493/// fixture row registered for it, whatever the `WHERE` clause says. Faulting paths keep only
494/// the keys they asked for, so `get` and `ensure_resident` behave; a query against the
495/// Recorder answers with all fixture keys, so assert the SQL it recorded, and use
496/// `Sqlite::memory()` where predicate results themselves are under test.
497pub struct Recorder {
498    state: Rc<RecorderState>,
499}
500
501struct RecorderState {
502    log: RefCell<Vec<(String, Vec<Value>)>>,
503    /// table name → rows served for a `SELECT … FROM <table>`.
504    fixtures: RefCell<HashMap<String, Vec<Vec<Value>>>>,
505}
506
507/// The recorded statement log, shared with the test that holds it.
508#[derive(Clone)]
509pub struct RecorderLog {
510    state: Rc<RecorderState>,
511}
512
513impl RecorderLog {
514    /// Every statement so far, SQL text only.
515    pub fn sql(&self) -> Vec<String> {
516        self.state
517            .log
518            .borrow()
519            .iter()
520            .map(|(s, _)| s.clone())
521            .collect()
522    }
523    /// Statements with their bound parameters.
524    pub fn entries(&self) -> Vec<(String, Vec<Value>)> {
525        self.state.log.borrow().clone()
526    }
527    pub fn clear(&self) {
528        self.state.log.borrow_mut().clear();
529    }
530}
531
532impl Recorder {
533    pub fn new() -> (Recorder, RecorderLog) {
534        let state = Rc::new(RecorderState {
535            log: RefCell::new(Vec::new()),
536            fixtures: RefCell::new(HashMap::new()),
537        });
538        (
539            Recorder {
540                state: state.clone(),
541            },
542            RecorderLog { state },
543        )
544    }
545
546    /// Rows a table's `SELECT` will answer with.
547    pub fn with_table(self, table: &str, rows: Vec<Vec<Value>>) -> Self {
548        self.state.fixtures.borrow_mut().insert(table.into(), rows);
549        self
550    }
551}
552
553pub struct RecorderConn {
554    state: Rc<RecorderState>,
555}
556
557impl SqliteDriver for Recorder {
558    type Connection = RecorderConn;
559    fn open(self) -> Result<RecorderConn, DbError> {
560        Ok(RecorderConn { state: self.state })
561    }
562    fn capabilities(&self) -> Capabilities {
563        Capabilities {
564            durable: false,
565            wal: false,
566            // The fake answers everything: an FTS/spatial model must open against fixtures
567            // (its reads just come back empty unless a fixture answers them), and folded
568            // predicates compile as if day_fold existed; the SQL is recorded, never run.
569            full_text_search: true,
570            rtree: true,
571            unicode_fold: true,
572            ..Default::default()
573        }
574    }
575}
576
577impl SqliteConnection for RecorderConn {
578    fn execute(&mut self, sql: &str, params: &[Value]) -> Result<u64, DbError> {
579        self.state
580            .log
581            .borrow_mut()
582            .push((sql.to_string(), params.to_vec()));
583        Ok(0)
584    }
585    fn query(
586        &mut self,
587        sql: &str,
588        params: &[Value],
589        row: &mut dyn FnMut(&dyn Row),
590    ) -> Result<(), DbError> {
591        self.state
592            .log
593            .borrow_mut()
594            .push((sql.to_string(), params.to_vec()));
595        // Serve a fixture when the statement reads `FROM` a table one was registered for:
596        // quoted, as the container writes it, or plain, as a raw query might.
597        if let Some(from) = sql.split(" FROM ").nth(1) {
598            let table = quoted_name(from)
599                .unwrap_or_else(|| from.split_whitespace().next().unwrap_or("").to_string());
600            if let Some(rows) = self.state.fixtures.borrow().get(&table) {
601                for r in rows {
602                    row(r);
603                }
604            }
605        }
606        Ok(())
607    }
608}
609
610// ---------------------------------------------------------------------------
611// Column values and codecs (docs/persistence.md)
612// ---------------------------------------------------------------------------
613
614/// A Rust type that knows how to be a column. One impl per type: its canonical form.
615pub trait ColumnValue: Sized + 'static {
616    /// The declared column type. Part of the schema fingerprint, so changing it is a
617    /// migration, never a surprise.
618    const SQL_TYPE: SqlType;
619    fn to_sqlite_value(&self) -> Value;
620    fn from_sqlite_value(v: Value) -> Result<Self, DbError>;
621}
622
623/// A named alternative representation for `T`, serde's `#[serde(with = …)]` idiom.
624/// Implement on a unit struct; select it per field with `#[model(with = …)]`.
625pub trait ValueCodec<T>: 'static {
626    const SQL_TYPE: SqlType;
627    fn to_sqlite_value(v: &T) -> Value;
628    fn from_sqlite_value(v: Value) -> Result<T, DbError>;
629}
630
631macro_rules! int_column {
632    ($($t:ty),*) => {$(
633        impl ColumnValue for $t {
634            const SQL_TYPE: SqlType = SqlType::Integer;
635            fn to_sqlite_value(&self) -> Value {
636                Value::Int(*self as i64)
637            }
638            fn from_sqlite_value(v: Value) -> Result<Self, DbError> {
639                Ok(v.as_int()? as $t)
640            }
641        }
642    )*};
643}
644int_column!(i8, i16, i32, i64, u8, u16, u32, u64, usize, isize);
645
646impl ColumnValue for bool {
647    const SQL_TYPE: SqlType = SqlType::Integer;
648    fn to_sqlite_value(&self) -> Value {
649        Value::Int(*self as i64)
650    }
651    fn from_sqlite_value(v: Value) -> Result<Self, DbError> {
652        Ok(v.as_int()? != 0)
653    }
654}
655
656impl ColumnValue for f64 {
657    const SQL_TYPE: SqlType = SqlType::Real;
658    fn to_sqlite_value(&self) -> Value {
659        Value::Real(*self)
660    }
661    fn from_sqlite_value(v: Value) -> Result<Self, DbError> {
662        v.as_real()
663    }
664}
665
666impl ColumnValue for f32 {
667    const SQL_TYPE: SqlType = SqlType::Real;
668    fn to_sqlite_value(&self) -> Value {
669        Value::Real(*self as f64)
670    }
671    fn from_sqlite_value(v: Value) -> Result<Self, DbError> {
672        Ok(v.as_real()? as f32)
673    }
674}
675
676impl ColumnValue for String {
677    const SQL_TYPE: SqlType = SqlType::Text;
678    fn to_sqlite_value(&self) -> Value {
679        Value::Text(self.clone())
680    }
681    fn from_sqlite_value(v: Value) -> Result<Self, DbError> {
682        Ok(v.as_text()?.to_string())
683    }
684}
685
686impl ColumnValue for Vec<u8> {
687    const SQL_TYPE: SqlType = SqlType::Blob;
688    fn to_sqlite_value(&self) -> Value {
689        Value::Blob(self.clone())
690    }
691    fn from_sqlite_value(v: Value) -> Result<Self, DbError> {
692        Ok(v.as_blob()?.to_vec())
693    }
694}
695
696/// A Uuid is a 16-byte `BLOB`: compact, indexable, and readable by any tool that knows the
697/// convention. (`day_model::Uuid` is `uuid::Uuid`, so no second dependency edge exists.)
698impl ColumnValue for day_model::Uuid {
699    const SQL_TYPE: SqlType = SqlType::Blob;
700    fn to_sqlite_value(&self) -> Value {
701        Value::Blob(self.as_bytes().to_vec())
702    }
703    fn from_sqlite_value(v: Value) -> Result<Self, DbError> {
704        day_model::Uuid::from_slice(v.as_blob()?)
705            .map_err(|e| DbError::new(DbErrorKind::Decode, format!("uuid: {e}")))
706    }
707}
708
709/// A key handle, as the bound parameter its stored form takes: `INTEGER` for integer keys,
710/// a 16-byte `BLOB` for Uuid keys, `TEXT` for string keys. `Pair` keys (join rows) bind
711/// through their own two-column clause, never through this.
712fn key_param(handle: u64) -> Value {
713    match Key::of_handle(handle) {
714        Some(Key::U64(k)) => Value::Int(k as i64),
715        Some(Key::Uuid(u)) => Value::Blob(day_model::Uuid::from_u128(u).as_bytes().to_vec()),
716        Some(Key::Str(s)) => Value::Text(s.to_string()),
717        Some(Key::Pair(..)) | None => Value::Null,
718    }
719}
720
721/// A stored key value, back as its path handle. `None` for shapes no key takes (a negative
722/// integer, a blob that is not 16 bytes); the caller treats those rows as unaddressable.
723fn value_to_handle(v: &Value) -> Option<u64> {
724    match v {
725        Value::Int(i) if *i >= 0 => Some(Key::U64(*i as u64).handle()),
726        Value::Blob(b) if b.len() == 16 => day_model::Uuid::from_slice(b)
727            .ok()
728            .map(|u| Key::Uuid(u.as_u128()).handle()),
729        Value::Text(t) => Some(Key::Str(t.as_str().into()).handle()),
730        _ => None,
731    }
732}
733
734/// `NULL` belongs to the framework: `Option` wraps any column type, encoding is called only on
735/// present values, and a NULL decodes to `None`, so an impl never sees `Null` and cannot
736/// disagree about it.
737impl<T: ColumnValue> ColumnValue for Option<T> {
738    const SQL_TYPE: SqlType = T::SQL_TYPE;
739    fn to_sqlite_value(&self) -> Value {
740        match self {
741            Some(v) => v.to_sqlite_value(),
742            None => Value::Null,
743        }
744    }
745    fn from_sqlite_value(v: Value) -> Result<Self, DbError> {
746        match v {
747            Value::Null => Ok(None),
748            v => Ok(Some(T::from_sqlite_value(v)?)),
749        }
750    }
751}
752
753/// The serde codec: any `Serialize + Deserialize` type as a `TEXT` column SQLite's own
754/// `json_*` functions can reach. `#[model(json)]` is sugar for `#[model(with = Json)]`.
755pub struct Json;
756
757impl<T> ValueCodec<T> for Json
758where
759    T: serde::Serialize + serde::de::DeserializeOwned + 'static,
760{
761    const SQL_TYPE: SqlType = SqlType::Text;
762    fn to_sqlite_value(v: &T) -> Value {
763        match serde_json::to_string(v) {
764            Ok(s) => Value::Text(s),
765            // Serialization of an in-memory value failing is a bug in the type's serde impl;
766            // surface it as a NULL rather than a panic, and the decode side will report it.
767            Err(_) => Value::Null,
768        }
769    }
770    fn from_sqlite_value(v: Value) -> Result<T, DbError> {
771        serde_json::from_str(v.as_text()?)
772            .map_err(|e| DbError::new(DbErrorKind::Decode, format!("json: {e}")))
773    }
774}
775
776// ---------------------------------------------------------------------------
777// The Model trait: what #[derive(Model)] implements
778// ---------------------------------------------------------------------------
779
780/// One column of a model's table, as the derive declares it. `field` is the struct field the
781/// column stores: the change log speaks field names, the SQL speaks column names, and this is
782/// where the two meet (they differ only under `#[model(column = "…")]`).
783#[derive(Clone, Copy, Debug)]
784pub struct ColumnDef {
785    pub name: &'static str,
786    pub field: &'static str,
787    pub sql: SqlType,
788    pub not_null: bool,
789    pub unique: bool,
790    pub indexed: bool,
791    /// A [`Blob`] column: never read by a row fault, written only when it carries pending
792    /// bytes, served on demand through the field's accessor.
793    pub lazy: bool,
794}
795
796/// The column pair a `#[model(spatial(lat = …, lon = …))]` declaration names.
797#[derive(Clone, Copy, Debug, PartialEq, Eq)]
798pub struct SpatialCols {
799    pub lat: &'static str,
800    pub lon: &'static str,
801}
802
803/// One `#[model(link(…))]` as the derive emits it: `owner.local = target.remote` is the join.
804#[derive(Clone, Copy, Debug)]
805pub struct LinkDef {
806    /// The marker field the link was declared on: the name `Owner::field()` answers to.
807    pub field: &'static str,
808    /// The owner's column holding the value.
809    pub local: &'static str,
810    /// The target's (qualified) table.
811    pub target_table: &'static str,
812    /// The target's column the value names.
813    pub remote: &'static str,
814}
815
816/// The marker a `#[model(link(…))]` field carries. It has neither a column nor state; the
817/// type is what names the far model for the derive.
818pub struct Linked<M: ?Sized> {
819    _m: std::marker::PhantomData<fn() -> M>,
820}
821
822impl<M: ?Sized> Clone for Linked<M> {
823    fn clone(&self) -> Self {
824        *self
825    }
826}
827impl<M: ?Sized> Copy for Linked<M> {}
828impl<M: ?Sized> Default for Linked<M> {
829    fn default() -> Self {
830        Linked {
831            _m: std::marker::PhantomData,
832        }
833    }
834}
835impl<M: ?Sized> PartialEq for Linked<M> {
836    fn eq(&self, _: &Self) -> bool {
837        true
838    }
839}
840impl<M: ?Sized> std::fmt::Debug for Linked<M> {
841    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
842        f.write_str("Linked")
843    }
844}
845
846/// A wired link, as the SQL compiler and the query watcher see it.
847#[derive(Clone, Copy, Debug)]
848pub(crate) struct LinkInfo {
849    pub(crate) owner_table: &'static str,
850    pub(crate) field: &'static str,
851    pub(crate) local: &'static str,
852    pub(crate) target_table: &'static str,
853    pub(crate) remote: &'static str,
854}
855
856/// A persistable model: an [`Identified`] observable struct with a schema half. Implemented by
857/// `#[derive(Model)]`; the container consumes it.
858pub trait Model: Identified + day_model::ApplyField + Clone + 'static {
859    const TABLE: &'static str;
860    /// The key column's name (the `#[model(id)]` field). Also the first entry of `COLUMNS`.
861    const KEY: &'static str;
862    const COLUMNS: &'static [ColumnDef];
863    /// Composite indexes from struct-level `#[model(index("a", "b"))]`.
864    const COMPOSITE_INDEXES: &'static [&'static [&'static str]] = &[];
865    /// `#[model(unique("a", "b"))]` on the struct: multi-column UNIQUE constraints, kept as
866    /// unique indexes (`day_uidx_{table}_{a}_{b}`), part of the fingerprint and of the
867    /// lightweight migration.
868    const UNIQUE_INDEXES: &'static [&'static [&'static str]] = &[];
869    /// Full-text-indexed columns from struct-level `#[model(fts("a", "b"))]`: an
870    /// external-content FTS5 shadow table plus sync triggers, generated at open.
871    const FTS_COLUMNS: &'static [&'static str] = &[];
872    /// The FTS5 tokenizer, from `#[model(fts(…, tokenize = "…"))]`, e.g.
873    /// `"unicode61 remove_diacritics 2"` for diacritics-insensitive search. `None` keeps
874    /// FTS5's default. Part of the schema fingerprint, so changing it rebuilds the shadow.
875    const FTS_TOKENIZE: Option<&'static str> = None;
876    /// The R*Tree pair from struct-level `#[model(spatial(lat = "…", lon = "…"))]`.
877    const SPATIAL: Option<SpatialCols> = None;
878    /// The key column's SQL shape: what a `One<Self>` foreign-key column stores.
879    const KEY_SQL: SqlType = SqlType::Integer;
880    /// Relations declared on this model's `Many` fields (`#[model(relation(…))]`).
881    const RELATIONS: &'static [RelationDef] = &[];
882    /// Relations by value (`#[model(link(…))]`): rows of another model whose `remote` column
883    /// equals this row's `local` column, with no foreign key: the shape that reaches across an
884    /// attached database (see [`ModelContainer::attach_database`]).
885    const LINKS: &'static [LinkDef] = &[];
886    /// The fields declared as [`Blob`]: the columns a fault names as `NULL` and the fold
887    /// writes only when they carry pending bytes.
888    const LAZY_FIELDS: &'static [&'static str] = &[];
889    /// After a flush wrote this row: hand over every lazy field's pending bytes and mark
890    /// them stored. The derive generates it for models with [`Blob`] fields.
891    fn settle_lazy(&mut self) -> Vec<(&'static str, std::sync::Arc<Vec<u8>>)> {
892        Vec::new()
893    }
894    /// Declared `external = "alias"`: the table belongs to a database attached under that alias
895    /// and managed elsewhere. The container creates, migrates, and fingerprints nothing for
896    /// it, and treats it as read-only.
897    const EXTERNAL: bool = false;
898    /// The alias an `EXTERNAL` table's database is attached under, the part `TABLE` is
899    /// qualified with (`catalog` in `catalog.stations`). Kept apart so SQL can quote each
900    /// half; `None` for a table in the container's own file.
901    const SCHEMA: Option<&'static str> = None;
902    /// One [`Value`] per column, in `COLUMNS` order.
903    fn to_row(&self) -> Vec<Value>;
904    fn from_row(row: &dyn Row) -> Result<Self, DbError>;
905    /// Each column's Rust-default value: what an added column backfills with.
906    fn default_row() -> Vec<Value>;
907    /// Wire this model's declared relations. Generated; the default declares none.
908    fn wire(reg: &mut Registrar<'_>) {
909        let _ = reg;
910    }
911}
912
913/// `name` as a SQL identifier: double-quoted, an embedded `"` doubled. Quoted, any name
914/// reaches the engine as itself: a keyword (`order`, `group`), a space, a quote, an emoji.
915/// Every statement the container writes names its tables and columns this way, and raw SQL
916/// written against them should too.
917pub fn ident(name: &str) -> String {
918    let mut out = String::with_capacity(name.len() + 2);
919    out.push('"');
920    for ch in name.chars() {
921        if ch == '"' {
922            out.push('"');
923        }
924        out.push(ch);
925    }
926    out.push('"');
927    out
928}
929
930/// A table's name in the two halves SQL quotes separately: the attached database's alias,
931/// if any, and the table's own name. [`Model::TABLE`] (`notes`, `catalog.stations`) stays the
932/// plain key every lookup, fingerprint and `_day_schema` row uses; this is what a statement
933/// gets.
934#[derive(Clone, Copy)]
935pub(crate) struct TableName {
936    pub(crate) schema: Option<&'static str>,
937    pub(crate) bare: &'static str,
938}
939
940impl TableName {
941    pub(crate) fn of<M: Model>() -> Self {
942        let bare = match M::SCHEMA {
943            Some(schema) => M::TABLE
944                .strip_prefix(schema)
945                .and_then(|rest| rest.strip_prefix('.'))
946                .unwrap_or(M::TABLE),
947            None => M::TABLE,
948        };
949        TableName {
950            schema: M::SCHEMA,
951            bare,
952        }
953    }
954
955    /// A table in the container's own file, named directly (a join table).
956    pub(crate) fn plain(bare: &'static str) -> Self {
957        TableName { schema: None, bare }
958    }
959
960    /// The quoted SQL that names the table in a statement: `"notes"`, `"catalog"."stations"`.
961    pub(crate) fn sql(&self) -> String {
962        table_sql(self.schema, self.bare)
963    }
964
965    /// The quoted SQL naming a shadow beside the table (`_fts`, `_geo`), in the same schema.
966    pub(crate) fn shadow(&self, suffix: &str) -> String {
967        table_sql(self.schema, &format!("{}{suffix}", self.bare))
968    }
969}
970
971pub(crate) fn table_sql(schema: Option<&str>, bare: &str) -> String {
972    match schema {
973        Some(schema) => format!("{}.{}", ident(schema), ident(bare)),
974        None => ident(bare),
975    }
976}
977
978/// The declared schema's fingerprint: table, columns, types, flags, indexes. Equal fingerprints
979/// open instantly; a difference migrates or refuses, never silently.
980pub fn model_fingerprint<M: Model>() -> u64 {
981    let mut h: u64 = 0xcbf2_9ce4_8422_2325;
982    let mut eat = |bytes: &[u8]| {
983        for b in bytes {
984            h ^= *b as u64;
985            h = h.wrapping_mul(0x1000_0000_01b3);
986        }
987    };
988    // The DDL generation this fingerprint vouches for. Bumped when what the file must look
989    // like changes (constrained column additions, unique indexes), so a fingerprint an older
990    // build recorded no longer matches and the file gets one comparison pass, which rebuilds
991    // what the older path left unconstrained and records the new fingerprint.
992    eat(b"ddl-v2|");
993    eat(M::TABLE.as_bytes());
994    eat(M::KEY.as_bytes());
995    for c in M::COLUMNS {
996        eat(c.name.as_bytes());
997        eat(c.sql.ddl().as_bytes());
998        eat(&[c.not_null as u8, c.unique as u8, c.indexed as u8]);
999    }
1000    for idx in M::COMPOSITE_INDEXES {
1001        for c in *idx {
1002            eat(c.as_bytes());
1003        }
1004        eat(b"|");
1005    }
1006    for idx in M::UNIQUE_INDEXES {
1007        eat(b"uniq:");
1008        for c in *idx {
1009            eat(c.as_bytes());
1010        }
1011        eat(b"|");
1012    }
1013    for c in M::FTS_COLUMNS {
1014        eat(b"fts:");
1015        eat(c.as_bytes());
1016    }
1017    if !M::FTS_COLUMNS.is_empty()
1018        && M::COLUMNS
1019            .iter()
1020            .any(|c| c.name == M::KEY && c.sql != SqlType::Integer)
1021    {
1022        eat(b"wide-fts-key-map-v1");
1023    }
1024    if let Some(t) = M::FTS_TOKENIZE {
1025        eat(b"tok:");
1026        eat(t.as_bytes());
1027    }
1028    if let Some(s) = M::SPATIAL {
1029        eat(b"geo:");
1030        eat(s.lat.as_bytes());
1031        eat(s.lon.as_bytes());
1032    }
1033    h
1034}
1035
1036// ---------------------------------------------------------------------------
1037// Schema sets and migrations
1038// ---------------------------------------------------------------------------
1039
1040/// The set of models a container manages; build with [`schema!`].
1041#[derive(Default)]
1042pub struct Schema {
1043    installers: Vec<Installer>,
1044    /// Run after every table is attached, because relation wiring needs both ends present.
1045    wirers: Vec<Installer>,
1046    /// Foreign-key clauses each declared relation contributes to its target's table.
1047    fk_specs: Vec<FkSpec>,
1048}
1049
1050type Installer = Box<dyn FnOnce(&ModelContainer) -> Result<(), DbError>>;
1051/// Decode raw rows into the cache silently, answering their handles.
1052type SettleFn = Rc<dyn Fn(&[u64]) -> Vec<(u64, &'static str, std::sync::Arc<Vec<u8>>)>>;
1053type AbsorbFn = Rc<dyn Fn(Vec<Vec<Value>>) -> Result<Vec<u64>, DbError>>;
1054/// Diff raw rows (selected by the resident keys) against the cache: per-field announcements
1055/// authored [`ModelContainer::EXTERNAL_AUTHOR`], resident rows missing from the input deleted
1056/// the same way. Returns whether anything differed.
1057type RefreshFn = Rc<dyn Fn(Vec<Vec<Value>>) -> Result<bool, DbError>>;
1058/// A `WHERE` clause plus its parameters, addressing one row by handle.
1059type KeyWhere = Rc<dyn Fn(u64) -> (String, Vec<Value>)>;
1060/// A `WHERE` clause plus its parameters, addressing a set of rows by handle.
1061type KeysWhere = Rc<dyn Fn(&[u64]) -> (String, Vec<Value>)>;
1062/// Evict up to N clean rows from an ordered candidate list, answering how many left.
1063type EvictFn = Rc<dyn Fn(&[u64], usize) -> usize>;
1064
1065/// One foreign-key clause, resolved from a `RelationDef` at `Schema::with` time: the child's
1066/// column carries `REFERENCES parent(key) ON DELETE …` in its generated DDL.
1067#[derive(Clone, Debug)]
1068struct FkSpec {
1069    child_table: &'static str,
1070    child_field: &'static str,
1071    parent_table: &'static str,
1072    /// `parent_table` as the `REFERENCES` clause names it.
1073    parent_sql: String,
1074    /// `parent_table` as `PRAGMA foreign_key_list` reports it: the bare, unquoted name.
1075    parent_bare: &'static str,
1076    parent_key: &'static str,
1077    rule: DeleteRule,
1078}
1079
1080impl Schema {
1081    pub fn new() -> Self {
1082        Self::default()
1083    }
1084    pub fn with<M: Model>(mut self) -> Self {
1085        for def in M::RELATIONS {
1086            if def.join.is_none() {
1087                self.fk_specs.push(FkSpec {
1088                    child_table: def.target_table,
1089                    child_field: def.inverse,
1090                    parent_table: M::TABLE,
1091                    parent_sql: TableName::of::<M>().sql(),
1092                    parent_bare: TableName::of::<M>().bare,
1093                    parent_key: M::KEY,
1094                    rule: def.delete,
1095                });
1096            }
1097        }
1098        self.installers.push(Box::new(|c| c.attach::<M>()));
1099        self.wirers.push(Box::new(|c| {
1100            let mut reg = Registrar {
1101                container: c,
1102                error: None,
1103            };
1104            M::wire(&mut reg);
1105            match reg.error {
1106                Some(e) => Err(e),
1107                None => Ok(()),
1108            }
1109        }));
1110        self
1111    }
1112}
1113
1114/// `schema![Trip, Lodging]`: the models a container manages.
1115#[macro_export]
1116macro_rules! schema {
1117    ($($m:ty),+ $(,)?) => {{
1118        let s = $crate::Schema::new();
1119        $(let s = s.with::<$m>();)+
1120        s
1121    }};
1122}
1123
1124/// Staged migrations: anything with intent behind it (a rename, a split) gets a stage the app
1125/// writes; each stage runs in its own transaction against the raw connection, and versions only
1126/// go up. Lightweight migration (added/dropped columns and indexes) runs afterward, inferred
1127/// from the schema fingerprint.
1128#[derive(Default)]
1129pub struct MigrationPlan {
1130    stages: Vec<Stage>,
1131}
1132
1133type StageFn = Box<dyn FnOnce(&mut dyn SqliteConnection) -> Result<(), DbError>>;
1134
1135struct Stage {
1136    from: u32,
1137    to: u32,
1138    run: StageFn,
1139}
1140
1141impl MigrationPlan {
1142    pub fn new() -> Self {
1143        Self::default()
1144    }
1145    /// A hand-written stage taking the database from `from` to `to`. Stages run in ascending
1146    /// order from the file's current version; a gap is an error at open.
1147    pub fn custom(
1148        mut self,
1149        from: u32,
1150        to: u32,
1151        f: impl FnOnce(&mut dyn SqliteConnection) -> Result<(), DbError> + 'static,
1152    ) -> Self {
1153        self.stages.push(Stage {
1154            from,
1155            to,
1156            run: Box::new(f),
1157        });
1158        self
1159    }
1160    fn target_version(&self) -> u32 {
1161        self.stages.iter().map(|s| s.to).max().unwrap_or(0)
1162    }
1163}
1164
1165// ---------------------------------------------------------------------------
1166// Dirty tracking: the fold, applied live
1167// ---------------------------------------------------------------------------
1168
1169/// What one row needs at the next flush. The merge rules are the change-log fold: same-row
1170/// changes coalesce, an INSERT absorbs later field writes, a DELETE absorbs everything.
1171#[derive(Clone, Debug, PartialEq)]
1172pub(crate) enum DirtyRow {
1173    Insert,
1174    Update(Vec<&'static str>),
1175    Delete,
1176}
1177
1178#[derive(Clone, Default)]
1179struct DirtyState {
1180    /// (store, key) → pending statement kind, in first-touch order.
1181    rows: HashMap<(u64, u64), DirtyRow>,
1182    order: Vec<(u64, u64)>,
1183    /// store → its dirty keys, so a relation's mid-turn overlay reads one store's rows
1184    /// instead of scanning every store's.
1185    by_store: HashMap<u64, Vec<u64>>,
1186    /// Stores whose whole value was rewritten (a wholesale `Store::update`), flushed by
1187    /// upserting every resident row. With a lazy cache no "delete the rest" is possible (the
1188    /// rest was never loaded), so wholesale rewrites are a resync of the working set only.
1189    full: Vec<u64>,
1190    /// (store, key) → the distinct author tags of the changes folded into that row, in
1191    /// first-seen order; the unauthored user edit (`None`) leaves no tag.
1192    authors: HashMap<(u64, u64), Vec<&'static str>>,
1193    /// store → the author tags of its wholesale rewrites.
1194    store_authors: HashMap<u64, Vec<&'static str>>,
1195}
1196
1197/// Record one author tag once, in first-seen order; `None` (the user) is not a tag.
1198fn add_author(tags: &mut Vec<&'static str>, author: Option<&'static str>) {
1199    if let Some(author) = author
1200        && !tags.contains(&author)
1201    {
1202        tags.push(author);
1203    }
1204}
1205
1206impl DirtyState {
1207    fn merge(&mut self, newer: Self) {
1208        for store in newer.full {
1209            if !self.full.contains(&store) {
1210                self.full.push(store);
1211            }
1212        }
1213        for (store, tags) in newer.store_authors {
1214            let mine = self.store_authors.entry(store).or_default();
1215            for tag in tags {
1216                add_author(mine, Some(tag));
1217            }
1218        }
1219        for (id, tags) in newer.authors {
1220            let mine = self.authors.entry(id).or_default();
1221            for tag in tags {
1222                add_author(mine, Some(tag));
1223            }
1224        }
1225        for id in newer.order {
1226            let next = newer.rows[&id].clone();
1227            if !self.rows.contains_key(&id) {
1228                self.order.push(id);
1229                self.by_store.entry(id.0).or_default().push(id.1);
1230            }
1231            match (self.rows.get_mut(&id), next) {
1232                (Some(DirtyRow::Update(old)), DirtyRow::Update(cols)) => {
1233                    for col in cols {
1234                        if !old.contains(&col) {
1235                            old.push(col);
1236                        }
1237                    }
1238                }
1239                (Some(DirtyRow::Insert | DirtyRow::Delete), DirtyRow::Update(_)) => {}
1240                (_, next) => {
1241                    self.rows.insert(id, next);
1242                }
1243            }
1244        }
1245    }
1246
1247    fn is_empty(&self) -> bool {
1248        self.rows.is_empty() && self.full.is_empty()
1249    }
1250
1251    fn note(&mut self, change: &day_model::Change, known_store: impl Fn(u64) -> bool) {
1252        let Some(&store) = change.components.first() else {
1253            return;
1254        };
1255        if !known_store(store) {
1256            return;
1257        }
1258        let Some(&key) = change.components.get(1) else {
1259            // A store-level change: the whole value may have been replaced.
1260            if !self.full.contains(&store) {
1261                self.full.push(store);
1262            }
1263            add_author(self.store_authors.entry(store).or_default(), change.author);
1264            return;
1265        };
1266        if key == day_model::STRUCTURE {
1267            return; // the shape path is for the UI; the row paths carry the work
1268        }
1269        let id = (store, key);
1270        if !self.rows.contains_key(&id) {
1271            self.order.push(id);
1272            self.by_store.entry(store).or_default().push(key);
1273        }
1274        add_author(self.authors.entry(id).or_default(), change.author);
1275        let slot = self.rows.entry(id).or_insert(DirtyRow::Update(Vec::new()));
1276        match (change.op, &mut *slot) {
1277            (Op::Delete, _) => *slot = DirtyRow::Delete,
1278            (Op::Insert, _) => *slot = DirtyRow::Insert,
1279            (Op::Set, DirtyRow::Insert) | (Op::Set, DirtyRow::Delete) => {}
1280            (Op::Set, DirtyRow::Update(columns)) => {
1281                if change.components.len() >= 3 && !columns.contains(&change.label) {
1282                    columns.push(change.label);
1283                }
1284            }
1285            (Op::Move, _) => {}
1286        }
1287    }
1288}
1289
1290// ---------------------------------------------------------------------------
1291// The container
1292// ---------------------------------------------------------------------------
1293
1294/// Everything the container knows how to do for one attached model type, monomorphized at
1295/// [`Schema::with`] and stored type-erased. Join tables (relations.rs) hand-build one over
1296/// their pair-keyed membership cache, which is why keys are plural and clause-shaped here.
1297pub(crate) struct TableHooks {
1298    pub(crate) table: &'static str,
1299    /// `table` split for SQL: the statements below name it through `name.sql()`.
1300    pub(crate) name: TableName,
1301    /// The key column(s), in order: the key SELECT list, the upsert's conflict target, and
1302    /// what its DO UPDATE leaves alone. One entry everywhere but join tables. Plain names,
1303    /// like `columns`; [`ident`] quotes them where a statement is written.
1304    pub(crate) key_cols: Vec<String>,
1305    /// `WHERE` clause + params addressing one row by its key handle.
1306    pub(crate) key_where: KeyWhere,
1307    pub(crate) columns: Vec<String>,
1308    /// `columns` again, as the model's static names: what a [`RowChange`] reports.
1309    pub(crate) column_names: Vec<&'static str>,
1310    /// Same order as `columns`; what a change's label matches against.
1311    pub(crate) fields: Vec<String>,
1312    /// Per column, whether it is a [`Blob`]: named as `NULL` in a row select, protected by
1313    /// `COALESCE` in the upsert, skipped by an update that carries no bytes for it.
1314    pub(crate) lazy: Vec<bool>,
1315    /// After a flush wrote these rows: settle their lazy fields to stored and return the
1316    /// pending bytes they carried, for the blob memo.
1317    pub(crate) settle: SettleFn,
1318    /// The FTS5 shadow's table name, when the model declares `fts(…)`.
1319    pub(crate) fts: Option<String>,
1320    pub(crate) fts_key: &'static str,
1321    /// The R*Tree shadow: (lat column, lon column, shadow table name).
1322    pub(crate) spatial: Option<(String, String, String)>,
1323    /// Current row values by key, read from the cache at flush time; the change log carries
1324    /// which rows and columns moved, never their contents.
1325    pub(crate) row_for: Rc<dyn Fn(u64) -> Option<Vec<Value>>>,
1326    /// Every (key, row) currently resident, for wholesale resyncs.
1327    pub(crate) all_rows: Rc<dyn Fn() -> Vec<(u64, Vec<Value>)>>,
1328    /// The resident keys, in cache (≈ fault) order: what eviction walks.
1329    pub(crate) resident_keys: Rc<dyn Fn() -> Vec<u64>>,
1330    /// The resident count, O(1): the fault path's eviction gate.
1331    pub(crate) resident_len: Rc<dyn Fn() -> usize>,
1332    pub(crate) is_resident: Rc<dyn Fn(u64) -> bool>,
1333    /// Decode raw rows into the cache silently (a fault landing).
1334    pub(crate) absorb: AbsorbFn,
1335    /// Diff raw rows against the resident set, announcing as the external author.
1336    pub(crate) refresh: RefreshFn,
1337    /// Silently drop up to `want` clean rows from the cache, taking candidates in order and
1338    /// skipping anything observed; answers how many left. One retain over the store, so an
1339    /// eviction pass costs O(cache), not O(cache × evicted). (Dirtiness is the container's
1340    /// knowledge, checked before this is called.)
1341    pub(crate) evict: EvictFn,
1342    #[cfg(not(target_arch = "wasm32"))]
1343    pub(crate) dispose_cache: Rc<dyn Fn()>,
1344    /// Bring this store under an undo history; captured here because the model type is known
1345    /// only at attach time.
1346    pub(crate) watch_undo: Rc<dyn Fn(&day_model::UndoStack)>,
1347}
1348
1349/// Why a durable transaction is being performed. Cache refreshes use EXTERNAL_AUTHOR and
1350/// do not constitute a write transaction. Remote imports persist but must not echo outbound.
1351#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
1352pub enum WriteOrigin {
1353    #[default]
1354    Local,
1355    RemoteImport,
1356    Maintenance,
1357}
1358
1359/// One row of a transaction's folded change set, as [`TransactionParticipant::before_commit`]
1360/// receives it: every row the ORM's pipeline wrote in the transaction (model edits, relation
1361/// upkeep, in-process cascades), one entry per (table, key). Rows the engine's own `ON
1362/// DELETE` clause removed without the process faulting them are not in the set.
1363#[derive(Clone, Debug, PartialEq)]
1364pub struct RowChange {
1365    /// The model's table, as [`Model::TABLE`] names it (a join table by its generated name).
1366    pub table: &'static str,
1367    /// The key as stored: one value, or the (parent, child) pair of a join row.
1368    pub key: Vec<Value>,
1369    pub kind: RowChangeKind,
1370    /// The distinct author tags ([`day_model::with_author`]) of the changes folded into
1371    /// the row, first seen first. The user's own edits carry no tag; the container's
1372    /// external-merge author never reaches the set.
1373    pub authors: Vec<&'static str>,
1374}
1375
1376/// What happened to a [`RowChange`]'s row over the transaction. Same-row changes coalesce
1377/// the way the autosave fold does: an insert absorbs later updates, a delete absorbs
1378/// everything before it, updates union their columns, and a wholesale write supersedes a
1379/// column list.
1380#[derive(Clone, Debug, PartialEq, Eq)]
1381pub enum RowChangeKind {
1382    Inserted,
1383    /// The changed columns' names, in first-touch order; transient fields never appear.
1384    Updated(Vec<&'static str>),
1385    /// The key only; the removed row's values are not retained.
1386    Deleted,
1387    /// Every column was written: a row-level replacement, or a row of a store rewritten
1388    /// wholesale (`Store::update`), which resyncs the resident rows.
1389    Rewritten,
1390}
1391
1392impl RowChange {
1393    /// Fold a later change to the same row into this one, by the autosave fold's rules.
1394    fn absorb(&mut self, later: RowChange) {
1395        for author in later.authors {
1396            add_author(&mut self.authors, Some(author));
1397        }
1398        self.kind = match (
1399            std::mem::replace(&mut self.kind, RowChangeKind::Deleted),
1400            later.kind,
1401        ) {
1402            (RowChangeKind::Updated(mut cols), RowChangeKind::Updated(more)) => {
1403                for col in more {
1404                    if !cols.contains(&col) {
1405                        cols.push(col);
1406                    }
1407                }
1408                RowChangeKind::Updated(cols)
1409            }
1410            (RowChangeKind::Updated(_), RowChangeKind::Rewritten)
1411            | (RowChangeKind::Rewritten, RowChangeKind::Updated(_) | RowChangeKind::Rewritten) => {
1412                RowChangeKind::Rewritten
1413            }
1414            (
1415                kept @ (RowChangeKind::Inserted | RowChangeKind::Deleted),
1416                RowChangeKind::Updated(_) | RowChangeKind::Rewritten,
1417            ) => kept,
1418            (_, next @ (RowChangeKind::Inserted | RowChangeKind::Deleted)) => next,
1419        };
1420    }
1421}
1422
1423/// The cache refresh a participant asks for after its own SQL may have changed model rows
1424/// that were already flushed from the caches.
1425#[derive(Clone, Debug, PartialEq, Eq, Default)]
1426pub enum Refresh {
1427    /// The participant wrote nothing the caches hold.
1428    #[default]
1429    None,
1430    /// Re-read and diff the resident rows of these tables only, drop the relation memos
1431    /// that involve them, and re-run the live queries that read them.
1432    Tables(Vec<&'static str>),
1433    /// Every resident row, every relation memo, every live query.
1434    All,
1435}
1436
1437/// Queue-confined extension participating in the SAME SQL transaction as model changes.
1438/// Callbacks must use only the supplied connection, never re-enter the container, commit,
1439/// roll back, perform network I/O, or mutate reactive models. Returning an error aborts the
1440/// transaction. `before_commit` runs after worker reactions and intermediate saves settle.
1441/// Persist extension state transactionally; callbacks may run again following a rollback.
1442pub trait TransactionParticipant: 'static {
1443    fn begin(
1444        &self,
1445        connection: &mut dyn SqliteConnection,
1446        origin: WriteOrigin,
1447    ) -> Result<(), DbError>;
1448    /// The transaction's folded change set is `changes`: accumulated across every flush in
1449    /// the transaction (a worker job's intermediate saves included), empty again after a
1450    /// rollback. The answer names the cache refresh to run after a successful COMMIT, before
1451    /// the work is acknowledged; a refresh failure surfaces as
1452    /// [`DbErrorKind::CommittedRefreshFailed`] (the data is durable, it cannot roll back).
1453    fn before_commit(
1454        &self,
1455        connection: &mut dyn SqliteConnection,
1456        origin: WriteOrigin,
1457        changes: &[RowChange],
1458    ) -> Result<Refresh, DbError>;
1459}
1460
1461pub(crate) struct ContainerInner {
1462    conn: RefCell<Box<dyn SqliteConnection>>,
1463    caps: Capabilities,
1464    /// store root id → hooks.
1465    tables: RefCell<HashMap<u64, TableHooks>>,
1466    /// model TypeId → the `Store<Keyed<M>>` handle, boxed.
1467    stores: RefCell<HashMap<TypeId, Box<dyn Any>>>,
1468    dirty: RefCell<DirtyState>,
1469    /// Live query result sets, marked stale from the change sink. Weak: the app's `Query`
1470    /// handles own the state; dead entries are pruned on dispatch.
1471    queries: RefCell<Vec<std::rc::Weak<QueryState>>>,
1472    /// The engine's cross-connection change counter as of the last look (`PRAGMA
1473    /// data_version`; it moves only when another connection commits to the file). `None`
1474    /// where the driver reports no external-change detection.
1475    data_version: Cell<Option<i64>>,
1476    /// Foreign-key clauses relations contribute to their targets' tables, set before attach.
1477    fk_specs: RefCell<Vec<FkSpec>>,
1478    /// The wired relations, maintained from the change sink and read by `RelationRef`s.
1479    pub(crate) relations: RefCell<Vec<Rc<relations::ToOneRel>>>,
1480    /// The wired many-to-manys, each over its own membership cache.
1481    pub(crate) joins: RefCell<Vec<Rc<relations::JoinRel>>>,
1482    /// The declared value links (`#[model(link(…))]`), from every attached model.
1483    pub(crate) links: RefCell<Vec<LinkInfo>>,
1484    /// The databases `attach_database` holds open, by alias.
1485    attached: RefCell<Vec<String>>,
1486    sink: Cell<Option<day_model::ChangeSinkId>>,
1487    autosave: Cell<bool>,
1488    /// An outer worker transaction owns commit/rollback; inner model saves only execute SQL.
1489    worker_transaction: Cell<bool>,
1490    participant: RefCell<Option<Rc<dyn TransactionParticipant>>>,
1491    /// The open transaction's folded change set, kept only while a participant is installed:
1492    /// appended per flush, handed to `before_commit`, cleared at begin, commit and rollback.
1493    transaction_changes: RefCell<Vec<RowChange>>,
1494    /// What `before_commit` asked for, acted on once the COMMIT has succeeded.
1495    refresh_scope: RefCell<Refresh>,
1496    refresh_pending: Cell<bool>,
1497    /// Soft per-table bound on resident rows. Dirty and observed rows never evict, so the
1498    /// working set can exceed it; everything else does not.
1499    cache_limit: Cell<usize>,
1500    /// Retry eviction after growth when dirty/observed rows prevent reaching the limit.
1501    eviction_retry: RefCell<HashMap<u64, usize>>,
1502    /// Bytes of lazy blob columns read or written recently, bounded by `blob_cache_limit`.
1503    blob_memo: RefCell<blob::BlobMemo>,
1504    blob_cache_limit: Cell<usize>,
1505    /// Child tables whose rows the engine's `ON DELETE` clauses are taking or nullifying in
1506    /// the flush under way, with no undo stack to serve: their resident rows are re-read
1507    /// after the commit (relations.rs, `parent_deleted`).
1508    engine_cascades: RefCell<Vec<&'static str>>,
1509    /// Set while `reconcile_engine_cascades` re-reads the child tables. Every row it finds
1510    /// gone or re-pointed got that way because its parent was deleted, so relation upkeep
1511    /// skips the point lookups that would ask the file for a parent that no longer exists.
1512    pub(crate) reconciling: Cell<bool>,
1513    /// The last autosave failure, observable by the UI (`when(container.last_error()…)`).
1514    pub(crate) error: day_reactive::Signal<Option<String>>,
1515    /// Guards re-entrant flushes (a turn-end firing during an explicit save).
1516    flushing: Cell<bool>,
1517}
1518
1519/// An open database and the working-set caches over it. Clone is shallow: clones share the
1520/// connection and the dirty state.
1521#[derive(Clone)]
1522pub struct ModelContainer {
1523    pub(crate) inner: Rc<ContainerInner>,
1524}
1525
1526/// The default per-table bound on resident rows ([`ModelContainer::set_cache_limit`]).
1527pub const DEFAULT_CACHE_LIMIT: usize = 8_192;
1528
1529/// How many bytes of lazy [`Blob`] values a container keeps in memory by default (32 MiB):
1530/// the memo behind [`BlobField::bytes`], bounded in bytes rather than rows.
1531pub const DEFAULT_BLOB_CACHE_LIMIT: usize = 32 * 1024 * 1024;
1532
1533impl ModelContainer {
1534    /// Open through `driver`, migrate, and attach every model in `schema`. Attaching creates
1535    /// or migrates the table and nothing more: no rows load, so open cost does not grow with
1536    /// the file. Autosave is on: any turn that touched a store flushes at its end.
1537    pub fn open<D: SqliteDriver>(driver: D, schema: Schema) -> Result<ModelContainer, DbError>
1538    where
1539        D::Connection: 'static,
1540    {
1541        Self::open_with(driver, schema, MigrationPlan::new())
1542    }
1543
1544    /// [`ModelContainer::open`], with hand-written migration stages that run first.
1545    pub fn open_with<D: SqliteDriver>(
1546        driver: D,
1547        schema: Schema,
1548        plan: MigrationPlan,
1549    ) -> Result<ModelContainer, DbError>
1550    where
1551        D::Connection: 'static,
1552    {
1553        let caps = driver.capabilities();
1554        let conn: Box<dyn SqliteConnection> = Box::new(driver.open()?);
1555        let error = day_reactive::Scope::detached().enter(|| day_reactive::Signal::new(None));
1556        let container = ModelContainer {
1557            inner: Rc::new(ContainerInner {
1558                conn: RefCell::new(conn),
1559                caps,
1560                tables: RefCell::new(HashMap::new()),
1561                stores: RefCell::new(HashMap::new()),
1562                dirty: RefCell::new(DirtyState::default()),
1563                queries: RefCell::new(Vec::new()),
1564                data_version: Cell::new(None),
1565                fk_specs: RefCell::new(Vec::new()),
1566                relations: RefCell::new(Vec::new()),
1567                joins: RefCell::new(Vec::new()),
1568                links: RefCell::new(Vec::new()),
1569                attached: RefCell::new(Vec::new()),
1570                sink: Cell::new(None),
1571                autosave: Cell::new(true),
1572                worker_transaction: Cell::new(false),
1573                refresh_pending: Cell::new(false),
1574                participant: RefCell::new(None),
1575                transaction_changes: RefCell::new(Vec::new()),
1576                refresh_scope: RefCell::new(Refresh::None),
1577                cache_limit: Cell::new(DEFAULT_CACHE_LIMIT),
1578                eviction_retry: RefCell::new(HashMap::new()),
1579                blob_memo: RefCell::new(blob::BlobMemo::default()),
1580                blob_cache_limit: Cell::new(DEFAULT_BLOB_CACHE_LIMIT),
1581                engine_cascades: RefCell::new(Vec::new()),
1582                reconciling: Cell::new(false),
1583                error,
1584                flushing: Cell::new(false),
1585            }),
1586        };
1587
1588        container.ensure_schema_table()?;
1589        container.run_stages(plan)?;
1590        let Schema {
1591            installers,
1592            wirers,
1593            fk_specs,
1594        } = schema;
1595        *container.inner.fk_specs.borrow_mut() = fk_specs;
1596        for install in installers {
1597            install(&container)?;
1598        }
1599        // Relations wire once every table is attached (both ends exist), and only then does
1600        // the sink go live.
1601        for wire in wirers {
1602            wire(&container)?;
1603        }
1604        relations::register_container(&container.inner);
1605        container.install_sink();
1606        container.install_autosave();
1607        if caps.external_changes {
1608            container
1609                .inner
1610                .data_version
1611                .set(container.file_data_version()?);
1612        }
1613        Ok(container)
1614    }
1615
1616    /// The author tag on changes [`ModelContainer::check_external`] merges in: the database's
1617    /// own contents arriving, distinguishable by every change consumer and never persisted
1618    /// back. Reserved: an app writing stores under this tag would have its writes dropped by
1619    /// the autosave fold.
1620    pub const EXTERNAL_AUTHOR: &'static str = "database";
1621
1622    /// The working-set cache for `M`, an ordinary day-model store holding the rows currently
1623    /// resident and not the table: its `keys()` are whatever happens to be faulted in. Bindings
1624    /// and accessors work on it unchanged; enumerate rows through a [`ModelContainer::query`],
1625    /// never through the cache. Panics only if `M` was not in the container's `schema!`,
1626    /// which is a wiring bug worth stopping on.
1627    pub fn cache<M: Model>(&self) -> Store<Keyed<M>> {
1628        let stores = self.inner.stores.borrow();
1629        let any = stores
1630            .get(&TypeId::of::<M>())
1631            .unwrap_or_else(|| panic!("model `{}` is not in this container's schema!", M::TABLE));
1632        *any.downcast_ref::<Store<Keyed<M>>>()
1633            .expect("store map holds the exact type it was keyed by")
1634    }
1635
1636    /// What the driver can and cannot do.
1637    pub fn capabilities(&self) -> Capabilities {
1638        self.inner.caps
1639    }
1640
1641    /// Autosave on/off (default on). Off, changes accumulate until [`ModelContainer::save`],
1642    /// and live queries answer from the last save, since only the file can answer them.
1643    pub fn set_autosave(&self, on: bool) {
1644        self.inner.autosave.set(on);
1645    }
1646
1647    /// The soft per-table bound on resident rows (default [`DEFAULT_CACHE_LIMIT`]). Dirty
1648    /// rows and rows something observes never evict; beyond that, faulting past the limit
1649    /// releases the oldest resident rows. `usize::MAX` disables eviction. Lowering the limit
1650    /// enforces it immediately.
1651    pub fn set_cache_limit(&self, rows: usize) {
1652        self.inner.cache_limit.set(rows.max(1));
1653        let store_ids: Vec<u64> = self.inner.tables.borrow().keys().copied().collect();
1654        for id in store_ids {
1655            self.enforce_cache_limit(id, &[], true);
1656        }
1657    }
1658
1659    // --- lazy blobs (blob.rs) ------------------------------------------------------------
1660
1661    /// Bound, in bytes, on the lazy [`Blob`] values kept in memory after a read or a flush
1662    /// (default [`DEFAULT_BLOB_CACHE_LIMIT`]). Lowering it releases the oldest entries now;
1663    /// a value larger than the limit is served but never kept.
1664    pub fn set_blob_cache_limit(&self, bytes: usize) {
1665        self.inner.blob_cache_limit.set(bytes);
1666        let mut memo = self.inner.blob_memo.borrow_mut();
1667        if bytes == 0 {
1668            memo.clear();
1669        } else {
1670            // Re-inserting nothing: the memo trims itself on the next insert, so trim here by
1671            // inserting an empty value under a key no row has, then forgetting it.
1672            memo.insert(
1673                (u64::MAX, u64::MAX, ""),
1674                std::sync::Arc::new(Vec::new()),
1675                bytes,
1676            );
1677            memo.forget_row(u64::MAX, u64::MAX);
1678        }
1679    }
1680
1681    /// Bytes the blob memo currently holds.
1682    pub fn blob_cache_bytes(&self) -> usize {
1683        self.inner.blob_memo.borrow().bytes()
1684    }
1685
1686    /// Values the blob memo currently holds.
1687    pub fn blob_cache_len(&self) -> usize {
1688        self.inner.blob_memo.borrow().len()
1689    }
1690
1691    /// Whether a delete may leave its rule to the engine's `ON DELETE` clause: no undo stack
1692    /// is capturing (it needs the removed rows to restore them) and no transaction
1693    /// participant is installed (its change set would miss the rows the engine removed).
1694    pub(crate) fn engine_cascade_allowed(&self) -> bool {
1695        !day_model::record_capture_active() && self.inner.participant.borrow().is_none()
1696    }
1697
1698    /// A relation whose parent row is being deleted this turn, with no undo stack to serve:
1699    /// the engine's `ON DELETE` clause will take or nullify the children in the flush, and
1700    /// the resident ones are re-read afterwards.
1701    pub(crate) fn note_engine_cascade(&self, child_table: &'static str) {
1702        let mut tables = self.inner.engine_cascades.borrow_mut();
1703        if !tables.contains(&child_table) {
1704            tables.push(child_table);
1705        }
1706    }
1707
1708    /// After a flush whose parent deletes the engine cascaded: re-read the resident rows of
1709    /// the child tables (vanished rows announce as deletes, nullified keys as field changes,
1710    /// both under the database's own author), drop their relation memos and re-run the live
1711    /// queries that read them. A vanished child is itself a parent whose children the engine
1712    /// took too, so the pass repeats while the announcements name new tables.
1713    fn reconcile_engine_cascades(&self) {
1714        for _ in 0..16 {
1715            let tables: Vec<&'static str> =
1716                std::mem::take(&mut *self.inner.engine_cascades.borrow_mut());
1717            if tables.is_empty() {
1718                return;
1719            }
1720            self.inner.reconciling.set(true);
1721            let refreshed = self.refresh_resident_in(Some(&tables));
1722            self.inner.reconciling.set(false);
1723            if let Err(error) = refreshed {
1724                self.inner.error.set(Some(error.to_string()));
1725                return;
1726            }
1727            self.invalidate_relation_memos_of(&tables);
1728            self.requery_tables(&tables);
1729        }
1730    }
1731
1732    /// After a successful flush: settle every written row's lazy fields (pending → stored),
1733    /// keep the bytes they carried in the memo, and drop the memo of every deleted row.
1734    fn settle_blobs(&self, dirty: &DirtyState) {
1735        let mut written: HashMap<u64, Vec<u64>> = HashMap::new();
1736        let mut deleted: Vec<(u64, u64)> = Vec::new();
1737        for id in &dirty.order {
1738            match dirty.rows.get(id) {
1739                Some(DirtyRow::Delete) => deleted.push(*id),
1740                Some(_) => written.entry(id.0).or_default().push(id.1),
1741                None => {}
1742            }
1743        }
1744        for store in &dirty.full {
1745            let keys = {
1746                let tables = self.inner.tables.borrow();
1747                tables
1748                    .get(store)
1749                    .map(|h| (h.resident_keys)())
1750                    .unwrap_or_default()
1751            };
1752            written.entry(*store).or_default().extend(keys);
1753        }
1754        let limit = self.inner.blob_cache_limit.get();
1755        for (store, keys) in written {
1756            let settle = {
1757                let tables = self.inner.tables.borrow();
1758                match tables.get(&store) {
1759                    Some(h) if h.lazy.iter().any(|l| *l) => h.settle.clone(),
1760                    _ => continue,
1761                }
1762            };
1763            for (key, field, bytes) in settle(&keys) {
1764                self.inner
1765                    .blob_memo
1766                    .borrow_mut()
1767                    .insert((store, key, field), bytes, limit);
1768            }
1769        }
1770        if !deleted.is_empty() {
1771            let mut memo = self.inner.blob_memo.borrow_mut();
1772            for (store, key) in deleted {
1773                memo.forget_row(store, key);
1774            }
1775        }
1776    }
1777
1778    /// The SQL half of a lazy read: the table, the key clause and the stored column name.
1779    fn blob_target(
1780        &self,
1781        store: u64,
1782        key: u64,
1783        column: &str,
1784    ) -> Option<(String, String, Vec<Value>)> {
1785        let tables = self.inner.tables.borrow();
1786        let hooks = tables.get(&store)?;
1787        let (clause, params) = (hooks.key_where)(key);
1788        Some((
1789            hooks.name.sql(),
1790            format!("{} FROM {} WHERE {clause}", ident(column), hooks.name.sql()),
1791            params,
1792        ))
1793    }
1794
1795    /// The whole value of a lazy column, from the memo or one point `SELECT`. Pending writes
1796    /// flush first with autosave, like every other read.
1797    pub(crate) fn blob_bytes(
1798        &self,
1799        store: u64,
1800        key: u64,
1801        column: &'static str,
1802    ) -> Result<std::sync::Arc<Vec<u8>>, DbError> {
1803        if self.inner.autosave.get() && !self.inner.dirty.borrow().is_empty() {
1804            self.save()?;
1805        }
1806        if let Some(hit) = self.inner.blob_memo.borrow_mut().get((store, key, column)) {
1807            return Ok(hit);
1808        }
1809        let Some((_, tail, params)) = self.blob_target(store, key, column) else {
1810            return Ok(std::sync::Arc::new(Vec::new()));
1811        };
1812        let mut bytes = Vec::new();
1813        self.conn()
1814            .query(&format!("SELECT {tail}"), &params, &mut |row| {
1815                bytes = row.get(0).as_blob().map(|b| b.to_vec()).unwrap_or_default();
1816            })?;
1817        let bytes = std::sync::Arc::new(bytes);
1818        let limit = self.inner.blob_cache_limit.get();
1819        self.inner
1820            .blob_memo
1821            .borrow_mut()
1822            .insert((store, key, column), bytes.clone(), limit);
1823        Ok(bytes)
1824    }
1825
1826    /// `length(col)`: the value's size without reading it (the memo answers when it can).
1827    pub(crate) fn blob_len(
1828        &self,
1829        store: u64,
1830        key: u64,
1831        column: &'static str,
1832    ) -> Result<usize, DbError> {
1833        if self.inner.autosave.get() && !self.inner.dirty.borrow().is_empty() {
1834            self.save()?;
1835        }
1836        if let Some(hit) = self.inner.blob_memo.borrow_mut().get((store, key, column)) {
1837            return Ok(hit.len());
1838        }
1839        let Some((table, _, params)) = self.blob_target(store, key, column) else {
1840            return Ok(0);
1841        };
1842        let clause = {
1843            let tables = self.inner.tables.borrow();
1844            tables
1845                .get(&store)
1846                .map(|h| (h.key_where)(key).0)
1847                .unwrap_or_default()
1848        };
1849        let mut len = 0usize;
1850        self.conn().query(
1851            &format!(
1852                "SELECT length({}) FROM {table} WHERE {clause}",
1853                ident(column)
1854            ),
1855            &params,
1856            &mut |row| len = row.get(0).as_int().unwrap_or(0).max(0) as usize,
1857        )?;
1858        Ok(len)
1859    }
1860
1861    /// `substr(col, start + 1, len)`: one range of the value, clamped to its length, so only
1862    /// the asked-for bytes cross from the engine.
1863    pub(crate) fn blob_range(
1864        &self,
1865        store: u64,
1866        key: u64,
1867        column: &'static str,
1868        range: std::ops::Range<usize>,
1869    ) -> Result<Vec<u8>, DbError> {
1870        if self.inner.autosave.get() && !self.inner.dirty.borrow().is_empty() {
1871            self.save()?;
1872        }
1873        if let Some(hit) = self.inner.blob_memo.borrow_mut().get((store, key, column)) {
1874            let start = range.start.min(hit.len());
1875            let end = range.end.clamp(start, hit.len());
1876            return Ok(hit[start..end].to_vec());
1877        }
1878        if range.end <= range.start {
1879            return Ok(Vec::new());
1880        }
1881        let Some((table, _, mut params)) = self.blob_target(store, key, column) else {
1882            return Ok(Vec::new());
1883        };
1884        let clause = {
1885            let tables = self.inner.tables.borrow();
1886            tables
1887                .get(&store)
1888                .map(|h| (h.key_where)(key).0)
1889                .unwrap_or_default()
1890        };
1891        let mut all = vec![
1892            Value::Int(range.start as i64 + 1),
1893            Value::Int((range.end - range.start) as i64),
1894        ];
1895        all.append(&mut params);
1896        let mut bytes = Vec::new();
1897        self.conn().query(
1898            &format!(
1899                "SELECT substr({}, ?, ?) FROM {table} WHERE {clause}",
1900                ident(column)
1901            ),
1902            &all,
1903            &mut |row| bytes = row.get(0).as_blob().map(|b| b.to_vec()).unwrap_or_default(),
1904        )?;
1905        Ok(bytes)
1906    }
1907
1908    /// Drop the memo of one row's lazy values (the row left).
1909    #[allow(dead_code)]
1910    pub(crate) fn blob_forget(&self, store: u64, key: u64) {
1911        self.inner.blob_memo.borrow_mut().forget_row(store, key);
1912    }
1913
1914    /// Drop the memo of one lazy value (a write replaced it).
1915    pub(crate) fn blob_forget_field(&self, store: u64, key: u64, column: &'static str) {
1916        self.inner
1917            .blob_memo
1918            .borrow_mut()
1919            .forget_one((store, key, column));
1920    }
1921
1922    /// Install one transaction extension before exposing the container to writers. Registration
1923    /// does not initialize its schema; do that in the worker factory first. No replacement or
1924    /// removal is supported, preventing a sync-enabled connection silently losing journaling.
1925    pub fn install_transaction_participant(
1926        &self,
1927        participant: impl TransactionParticipant,
1928    ) -> Result<(), DbError> {
1929        if self.inner.worker_transaction.get()
1930            || !self.inner.dirty.borrow().is_empty()
1931            || self.inner.participant.borrow().is_some()
1932        {
1933            return Err(DbError::new(
1934                DbErrorKind::Deny,
1935                "transaction participant must be installed on an idle, clean container",
1936            ));
1937        }
1938        *self.inner.participant.borrow_mut() = Some(Rc::new(participant));
1939        Ok(())
1940    }
1941
1942    fn participant_begin(
1943        &self,
1944        conn: &mut dyn SqliteConnection,
1945        origin: WriteOrigin,
1946    ) -> Result<(), DbError> {
1947        let participant = self.inner.participant.borrow().clone();
1948        if let Some(p) = participant {
1949            self.inner.transaction_changes.borrow_mut().clear();
1950            *self.inner.refresh_scope.borrow_mut() = Refresh::None;
1951            p.begin(conn, origin)?;
1952        }
1953        Ok(())
1954    }
1955
1956    /// Hand the participant the transaction's change set and keep its refresh request for
1957    /// [`ModelContainer::participant_refresh`], which runs once the COMMIT has succeeded.
1958    fn participant_commit(
1959        &self,
1960        conn: &mut dyn SqliteConnection,
1961        origin: WriteOrigin,
1962    ) -> Result<(), DbError> {
1963        let participant = self.inner.participant.borrow().clone();
1964        if let Some(p) = participant {
1965            let changes = std::mem::take(&mut *self.inner.transaction_changes.borrow_mut());
1966            let scope = p.before_commit(conn, origin, &changes)?;
1967            *self.inner.refresh_scope.borrow_mut() = scope;
1968        }
1969        Ok(())
1970    }
1971
1972    /// A transaction is ending without a COMMIT: its change set is not anyone's to see.
1973    fn participant_rollback(&self) {
1974        self.inner.transaction_changes.borrow_mut().clear();
1975        *self.inner.refresh_scope.borrow_mut() = Refresh::None;
1976    }
1977
1978    /// Append one flush's folded rows to the open transaction's change set, coalescing with
1979    /// the rows earlier flushes of the same transaction already recorded.
1980    fn record_changes(&self, changes: Vec<RowChange>) {
1981        if changes.is_empty() {
1982            return;
1983        }
1984        let mut set = self.inner.transaction_changes.borrow_mut();
1985        for change in changes {
1986            match set
1987                .iter_mut()
1988                .find(|c| c.table == change.table && c.key == change.key)
1989            {
1990                None => set.push(change),
1991                Some(prior) => prior.absorb(change),
1992            }
1993        }
1994    }
1995
1996    /// The last autosave failure, if any, as a tracked signal the UI can watch.
1997    pub fn last_error(&self) -> day_reactive::Signal<Option<String>> {
1998        self.inner.error
1999    }
2000
2001    /// Flush every pending change now, in one transaction. Autosave calls this at turn end;
2002    /// call it directly where the error matters at a known point.
2003    pub fn save(&self) -> Result<(), DbError> {
2004        self.save_now().map(|_| ())
2005    }
2006
2007    /// Run `f` and return the SQL one flush of everything it changed issues: the headless
2008    /// persistence assert (autosave is suspended for the duration so the statements land
2009    /// here). Twenty keystrokes into one field come back as one `UPDATE`.
2010    pub fn record_sql(&self, f: impl FnOnce()) -> Result<Vec<String>, DbError> {
2011        let prior = self.inner.autosave.replace(false);
2012        f();
2013        let result = self.save_now();
2014        self.inner.autosave.set(prior);
2015        result.map(|stmts| stmts.into_iter().map(|(sql, _)| sql).collect())
2016    }
2017
2018    fn save_now(&self) -> Result<Vec<(String, Vec<Value>)>, DbError> {
2019        if self.inner.flushing.get() {
2020            return Ok(Vec::new());
2021        }
2022        if self.inner.refresh_pending.get() {
2023            self.refresh_committed()?;
2024        }
2025        let dirty = {
2026            let mut d = self.inner.dirty.borrow_mut();
2027            if d.is_empty() {
2028                drop(d);
2029                // Nothing to flush, but a stale query may still be waiting on its deferred
2030                // requery (a fetch swap on a clean container lands here).
2031                self.run_deferred_requeries(&[]);
2032                return Ok(Vec::new());
2033            }
2034            std::mem::take(&mut *d)
2035        };
2036        self.inner.flushing.set(true);
2037        let had_writes = !dirty.is_empty();
2038        let result = self.flush(&dirty);
2039        self.inner.flushing.set(false);
2040        match &result {
2041            Ok(stmts) => {
2042                // Previously dirty rows can now be evicted on the next fault.
2043                self.inner.eviction_retry.borrow_mut().clear();
2044                // And a pass runs now for every store the flush touched: an import that only
2045                // inserts never faults, so without this every row it wrote would stay
2046                // resident, however far past the limit (a ten-million-row seed sat at 3 GB).
2047                let mut touched: Vec<u64> = dirty.order.iter().map(|(store, _)| *store).collect();
2048                touched.extend(dirty.full.iter().copied());
2049                touched.sort_unstable();
2050                touched.dedup();
2051                for store in touched {
2052                    self.enforce_cache_limit(store, &[], false);
2053                }
2054                self.settle_blobs(&dirty);
2055                self.reconcile_engine_cascades();
2056                self.inner.error.set_if_changed(None);
2057                self.run_deferred_requeries(stmts);
2058            }
2059            Err(e) => {
2060                // Keep the optimistic cache and its pending writes together. A retry must
2061                // persist the same edits, including any edits made after the failed save.
2062                {
2063                    let mut pending = self.inner.dirty.borrow_mut();
2064                    let newer = std::mem::take(&mut *pending);
2065                    *pending = dirty;
2066                    pending.merge(newer);
2067                }
2068                self.inner.error.set(Some(e.to_string()));
2069            }
2070        }
2071        if result.is_ok() && !self.inner.worker_transaction.get() && had_writes {
2072            self.participant_refresh()?;
2073        }
2074        result
2075    }
2076
2077    /// After a successful COMMIT: the refresh `before_commit` asked for. A failure here is
2078    /// [`DbErrorKind::CommittedRefreshFailed`]; the refresh stays pending (as a full one) for
2079    /// the next save to retry, since the file already holds the participant's writes.
2080    fn participant_refresh(&self) -> Result<(), DbError> {
2081        let scope = std::mem::take(&mut *self.inner.refresh_scope.borrow_mut());
2082        let tables = match scope {
2083            Refresh::None => return Ok(()),
2084            Refresh::Tables(tables) => Some(tables),
2085            Refresh::All => None,
2086        };
2087        self.inner.refresh_pending.set(true);
2088        self.refresh_committed_in(tables.as_deref()).map_err(|e| {
2089            let error = DbError::new(DbErrorKind::CommittedRefreshFailed, e.to_string());
2090            self.inner.error.set(Some(error.to_string()));
2091            error
2092        })
2093    }
2094
2095    fn refresh_committed(&self) -> Result<(), DbError> {
2096        self.refresh_committed_in(None)
2097    }
2098
2099    /// Re-read the resident rows of `tables` (every table when `None`) and bring the memos
2100    /// and live queries that depend on them up to date.
2101    fn refresh_committed_in(&self, tables: Option<&[&'static str]>) -> Result<(), DbError> {
2102        if !self.inner.dirty.borrow().is_empty() {
2103            return Err(DbError::new(
2104                DbErrorKind::Deny,
2105                "refresh committed state before making further model edits",
2106            ));
2107        }
2108        self.refresh_resident_in(tables)?;
2109        match tables {
2110            None => {
2111                self.invalidate_relation_memos();
2112                self.requery_all();
2113            }
2114            Some(tables) => {
2115                self.invalidate_relation_memos_of(tables);
2116                self.requery_tables(tables);
2117            }
2118        }
2119        if self.inner.caps.external_changes {
2120            self.inner.data_version.set(self.file_data_version()?);
2121        }
2122        self.inner.refresh_pending.set(false);
2123        self.inner.error.set_if_changed(None);
2124        Ok(())
2125    }
2126
2127    // --- faulting ----------------------------------------------------------------------------
2128
2129    /// One row, made resident (faulted from the file if it was not). `None` when no such row
2130    /// exists (or a driver error surfaced, observable through [`ModelContainer::last_error`]).
2131    pub fn get<M: Model>(&self, id: impl Into<ModelId<M>>) -> Option<day_model::Elem<M>> {
2132        match self.try_get::<M>(id) {
2133            Ok(row) => row,
2134            Err(error) => {
2135                self.inner.error.set(Some(error.to_string()));
2136                None
2137            }
2138        }
2139    }
2140
2141    /// Read a row, distinguishing an absent key from a storage or decoding failure.
2142    pub fn try_get<M: Model>(
2143        &self,
2144        id: impl Into<ModelId<M>>,
2145    ) -> Result<Option<day_model::Elem<M>>, DbError> {
2146        let store = self.cache::<M>();
2147        let h = id.into().handle();
2148        if !store.with_untracked(|k| k.get(h).is_some()) {
2149            self.ensure_resident::<M>(&[h])?;
2150        }
2151        Ok(store
2152            .with_untracked(|k| k.get(h).is_some())
2153            .then(|| store.elem(h)))
2154    }
2155
2156    /// Make these rows resident, faulting the missing ones in one chunked `SELECT`. Rows the
2157    /// file does not have are not resident afterwards; rows deleted this turn are not
2158    /// resurrected.
2159    pub fn ensure_resident<M: Model>(&self, keys: &[u64]) -> Result<(), DbError> {
2160        let store = self.cache::<M>();
2161        self.fault_into(store.store_id(), keys)
2162    }
2163
2164    /// [`ModelContainer::ensure_resident`], typed ids in.
2165    pub fn ensure<M: Model>(
2166        &self,
2167        ids: impl IntoIterator<Item = impl Into<ModelId<M>>>,
2168    ) -> Result<(), DbError> {
2169        let keys: Vec<u64> = ids.into_iter().map(|i| i.into().handle()).collect();
2170        self.ensure_resident::<M>(&keys)
2171    }
2172
2173    /// Fault every row of `M`'s table in: the document pattern, said explicitly. A sketch's
2174    /// scene or a settings table is the working set, and the app that draws all of it warms
2175    /// it once at open. Raise the cache limit first (`set_cache_limit(usize::MAX)` for a
2176    /// document container) so the warmed rows are not immediately eligible to leave; rows
2177    /// deleted this turn stay deleted. Returns how many rows are resident afterward.
2178    pub fn warm<M: Model>(&self) -> Result<usize, DbError> {
2179        let store = self.cache::<M>();
2180        let key = ident(M::KEY);
2181        let keys = self.select_id_column_checked(&format!(
2182            "SELECT {key} FROM {} ORDER BY {key}",
2183            TableName::of::<M>().sql()
2184        ))?;
2185        self.fault_into(store.store_id(), &keys)?;
2186        Ok(store.with_untracked(|k| k.len()))
2187    }
2188
2189    /// Insert one row through the front door: it becomes resident and dirty, announces, and
2190    /// folds to one `INSERT` at the next flush.
2191    pub fn insert<M: Model>(&self, row: M) {
2192        let store = self.cache::<M>();
2193        let h = row.handle();
2194        store.restructure("create", Op::Insert, h, move |k| k.push(row));
2195    }
2196
2197    /// `SELECT COUNT(*)`: the table's true size, which the cache cannot know. Settles
2198    /// pending writes first (with autosave), like every other read.
2199    pub fn table_count<M: Model>(&self) -> Result<u64, DbError> {
2200        if self.inner.autosave.get() && !self.inner.dirty.borrow().is_empty() {
2201            self.save()?;
2202        }
2203        let mut n = 0i64;
2204        self.conn().query(
2205            &format!("SELECT COUNT(*) FROM {}", TableName::of::<M>().sql()),
2206            &[],
2207            &mut |row| {
2208                n = row.get(0).as_int().unwrap_or(0);
2209            },
2210        )?;
2211        Ok(n.max(0) as u64)
2212    }
2213
2214    /// The untyped fault: bring `keys` into `store_id`'s cache.
2215    pub(crate) fn fault_into(&self, store_id: u64, keys: &[u64]) -> Result<(), DbError> {
2216        let (is_resident, absorb, columns, table, keys_where) = {
2217            let tables = self.inner.tables.borrow();
2218            let Some(hooks) = tables.get(&store_id) else {
2219                return Ok(());
2220            };
2221            (
2222                hooks.is_resident.clone(),
2223                hooks.absorb.clone(),
2224                select_list(hooks),
2225                hooks.name.sql(),
2226                keys_where_of(hooks),
2227            )
2228        };
2229        let missing: Vec<u64> = {
2230            let dirty = self.inner.dirty.borrow();
2231            keys.iter()
2232                .copied()
2233                .filter(|k| !is_resident(*k))
2234                // A row deleted this turn still exists in the file until the flush; faulting
2235                // it back would resurrect it.
2236                .filter(|k| dirty.rows.get(&(store_id, *k)) != Some(&DirtyRow::Delete))
2237                .collect()
2238        };
2239        if missing.is_empty() {
2240            return Ok(());
2241        }
2242        let mut faulted: Vec<u64> = Vec::with_capacity(missing.len());
2243        for chunk in missing.chunks(MAX_BOUND_PARAMS / 2) {
2244            let (clause, params) = keys_where(chunk);
2245            let mut rows: Vec<Vec<Value>> = Vec::new();
2246            self.conn().query(
2247                &format!("SELECT {columns} FROM {table} WHERE {clause}"),
2248                &params,
2249                &mut |row| {
2250                    let n = Row::len(row);
2251                    rows.push((0..n).map(|i| row.get(i)).collect());
2252                },
2253            )?;
2254            faulted.extend(absorb(rows)?);
2255        }
2256        // The Recorder serves whole fixture tables whatever the `WHERE` says; keep only what
2257        // was asked for so faulting stays precise there too. (Through a `HashSet`; a linear
2258        // scan here made warming half a million rows quadratic.)
2259        let wanted: std::collections::HashSet<u64> = missing.iter().copied().collect();
2260        faulted.retain(|k| wanted.contains(k));
2261        self.enforce_cache_limit(store_id, &faulted, false);
2262        Ok(())
2263    }
2264
2265    /// Release resident rows beyond the cache limit: oldest first, never a dirty row, never
2266    /// an observed one, never one just faulted for the caller still holding it.
2267    ///
2268    /// The pass walks every resident key, so it runs with hysteresis on the fault path:
2269    /// nothing happens until the cache overshoots the limit by a slack margin, and one pass
2270    /// then brings it back to the limit, amortizing the walk over the faults that filled the
2271    /// slack, instead of paying O(resident) per fault batch. (Measured: a 50k-row relation
2272    /// traversal over a 500k-row table spent 99% of its time in the un-amortized walk.)
2273    /// `strict` skips the slack, so `set_cache_limit` enforces its new bound immediately.
2274    fn enforce_cache_limit(&self, store_id: u64, protect: &[u64], strict: bool) {
2275        let limit = self.inner.cache_limit.get();
2276        if limit == usize::MAX {
2277            return;
2278        }
2279        let (resident_len, evict) = {
2280            let tables = self.inner.tables.borrow();
2281            let Some(hooks) = tables.get(&store_id) else {
2282                return;
2283            };
2284            ((hooks.resident_len)(), hooks.evict.clone())
2285        };
2286        let slack = if strict {
2287            0
2288        } else {
2289            (limit / 8).clamp(64, 4096)
2290        };
2291        let threshold = if strict {
2292            limit
2293        } else {
2294            self.inner
2295                .eviction_retry
2296                .borrow()
2297                .get(&store_id)
2298                .copied()
2299                .unwrap_or_else(|| limit.saturating_add(slack))
2300        };
2301        if resident_len <= threshold {
2302            return;
2303        }
2304        // Back off even when every row is pinned. A fixed limit gate otherwise scans an
2305        // ever-growing dirty transaction on EVERY single-row fault (quadratic work).
2306        self.inner.eviction_retry.borrow_mut().insert(
2307            store_id,
2308            resident_len.saturating_add(slack.max(resident_len / 8).max(1)),
2309        );
2310        let resident = {
2311            let tables = self.inner.tables.borrow();
2312            match tables.get(&store_id) {
2313                Some(hooks) => (hooks.resident_keys)(),
2314                None => return,
2315            }
2316        };
2317        let excess = resident.len().saturating_sub(limit);
2318        let candidates: Vec<u64> = {
2319            let dirty = self.inner.dirty.borrow();
2320            if dirty.full.contains(&store_id) {
2321                return; // a wholesale rewrite is pending; every row is implicitly dirty
2322            }
2323            let protect: std::collections::HashSet<u64> = protect.iter().copied().collect();
2324            resident
2325                .into_iter()
2326                .filter(|key| !protect.contains(key) && !dirty.rows.contains_key(&(store_id, *key)))
2327                .collect()
2328        };
2329        let evicted = evict(&candidates, excess);
2330        if evicted > 0 {
2331            let is_resident = {
2332                let tables = self.inner.tables.borrow();
2333                tables.get(&store_id).map(|h| h.is_resident.clone())
2334            };
2335            if let Some(is_resident) = is_resident {
2336                let mut memo = self.inner.blob_memo.borrow_mut();
2337                for key in candidates.iter().filter(|k| !is_resident(**k)) {
2338                    memo.forget_row(store_id, *key);
2339                }
2340            }
2341        }
2342        let remaining = resident_len.saturating_sub(evicted);
2343        self.inner.eviction_retry.borrow_mut().insert(
2344            store_id,
2345            remaining
2346                .max(limit)
2347                .saturating_add(slack.max(remaining / 8).max(1)),
2348        );
2349    }
2350
2351    // --- internals ---------------------------------------------------------------------------
2352
2353    pub(crate) fn conn(&self) -> std::cell::RefMut<'_, Box<dyn SqliteConnection>> {
2354        self.inner.conn.borrow_mut()
2355    }
2356
2357    /// Run a one-column SELECT and hand back the values as key handles. Errors surface on the
2358    /// error signal (these run on read paths with no caller to give a `Result` to).
2359    /// One-column key SELECT with the error returned, for callers that have a `Result` to
2360    /// give it to (the read paths use [`ModelContainer::select_id_column`] instead).
2361    fn select_id_column_checked(&self, sql: &str) -> Result<Vec<u64>, DbError> {
2362        let mut ids = Vec::new();
2363        self.conn().query(sql, &[], &mut |row| {
2364            if let Some(h) = value_to_handle(&row.get(0)) {
2365                ids.push(h);
2366            }
2367        })?;
2368        Ok(ids)
2369    }
2370
2371    fn select_ids_checked(&self, sql: &str, params: &[Value]) -> Result<Vec<u64>, DbError> {
2372        let mut ids = Vec::new();
2373        self.conn().query(sql, params, &mut |row| {
2374            if let Some(h) = value_to_handle(&row.get(0)) {
2375                ids.push(h);
2376            }
2377        })?;
2378        Ok(ids)
2379    }
2380    pub(crate) fn select_id_column(&self, sql: &str, params: &[Value]) -> Vec<u64> {
2381        match self.select_ids_checked(sql, params) {
2382            Ok(ids) => ids,
2383            Err(e) => {
2384                self.inner.error.set(Some(e.to_string()));
2385                Vec::new()
2386            }
2387        }
2388    }
2389
2390    /// Run a one-column SELECT for a single REAL.
2391    pub(crate) fn select_real(&self, sql: &str, params: &[Value]) -> Option<f64> {
2392        let mut v = None;
2393        if let Err(e) = self.conn().query(sql, params, &mut |row| {
2394            v = row.get(0).as_real().ok();
2395        }) {
2396            self.inner.error.set(Some(e.to_string()));
2397        }
2398        v
2399    }
2400
2401    /// This turn's unflushed rows of one store: what relation reads overlay.
2402    pub(crate) fn dirty_rows_of(&self, store_id: u64) -> Vec<(u64, DirtyRow)> {
2403        let dirty = self.inner.dirty.borrow();
2404        let Some(keys) = dirty.by_store.get(&store_id) else {
2405            return Vec::new();
2406        };
2407        keys.iter()
2408            .filter_map(|k| {
2409                dirty
2410                    .rows
2411                    .get(&(store_id, *k))
2412                    .map(|state| (*k, state.clone()))
2413            })
2414            .collect()
2415    }
2416
2417    /// One row's pending state, if any.
2418    pub(crate) fn dirty_state_of(&self, store_id: u64, key: u64) -> Option<DirtyRow> {
2419        self.inner
2420            .dirty
2421            .borrow()
2422            .rows
2423            .get(&(store_id, key))
2424            .cloned()
2425    }
2426
2427    fn ensure_schema_table(&self) -> Result<(), DbError> {
2428        self.conn().execute(
2429            "CREATE TABLE IF NOT EXISTS _day_schema (\
2430             table_name TEXT PRIMARY KEY, fingerprint TEXT NOT NULL, version INTEGER NOT NULL)",
2431            &[],
2432        )?;
2433        Ok(())
2434    }
2435
2436    fn db_version(&self) -> Result<u32, DbError> {
2437        let mut version = 0u32;
2438        self.conn().query(
2439            "SELECT version FROM _day_schema WHERE table_name = '_db'",
2440            &[],
2441            &mut |row| {
2442                version = row.get(0).as_int().unwrap_or(0) as u32;
2443            },
2444        )?;
2445        Ok(version)
2446    }
2447
2448    /// The `_db` version row, written on the caller's connection so it can ride inside the
2449    /// transaction whose effects it labels.
2450    fn write_db_version(conn: &mut dyn SqliteConnection, v: u32) -> Result<(), DbError> {
2451        conn.execute(
2452            "INSERT INTO _day_schema (table_name, fingerprint, version) VALUES ('_db', '', ?) \
2453             ON CONFLICT(table_name) DO UPDATE SET version = excluded.version",
2454            &[Value::Int(v as i64)],
2455        )?;
2456        Ok(())
2457    }
2458
2459    /// `f` and the version row it leads to, in one transaction: the stage's effects and its
2460    /// label commit together or not at all. A failure in the stage, in the version write, or
2461    /// in the commit itself takes the one rollback path.
2462    fn versioned_transaction(
2463        &self,
2464        version: u32,
2465        f: impl FnOnce(&mut dyn SqliteConnection) -> Result<(), DbError>,
2466    ) -> Result<(), DbError> {
2467        let mut conn = self.conn();
2468        conn.begin()?;
2469        let result = f(conn.as_mut())
2470            .and_then(|()| Self::write_db_version(conn.as_mut(), version))
2471            .and_then(|()| conn.commit());
2472        if result.is_err() {
2473            let _ = conn.rollback();
2474        }
2475        result
2476    }
2477
2478    fn run_stages(&self, plan: MigrationPlan) -> Result<(), DbError> {
2479        let target = plan.target_version();
2480        let mut current = self.db_version()?;
2481        if current > target && target > 0 {
2482            return Err(DbError::new(
2483                DbErrorKind::Schema,
2484                format!(
2485                    "database is at version {current}, newer than this build's {target} — \
2486                     refusing to open (an old app writing a new schema is how data rots)"
2487                ),
2488            ));
2489        }
2490        let mut stages = plan.stages;
2491        stages.sort_by_key(|s| s.from);
2492        for stage in stages {
2493            if stage.from != current {
2494                if stage.to <= current {
2495                    continue; // already applied
2496                }
2497                return Err(DbError::new(
2498                    DbErrorKind::Schema,
2499                    format!(
2500                        "migration stage {}→{} does not start at the database's version {current}",
2501                        stage.from, stage.to
2502                    ),
2503                ));
2504            }
2505            self.versioned_transaction(stage.to, stage.run)?;
2506            current = stage.to;
2507        }
2508        if target > 0 && current != target {
2509            self.versioned_transaction(target, |_| Ok(()))?;
2510        }
2511        Ok(())
2512    }
2513
2514    /// Create (or lightweight-migrate) `M`'s table and register its hooks. The cache starts
2515    /// empty: this is the line where the old engine read the whole table, and the lazy one
2516    /// exists so that nothing does.
2517    fn attach<M: Model>(&self) -> Result<(), DbError> {
2518        // FTS5's external-content table and the R*Tree address rows by ROWID (an i64), so
2519        // both need the key column to be the integer rowid. A wide-keyed model declaring one
2520        // is refused at open, naming the constraint, rather than silently mis-indexing.
2521        let key_sql = M::COLUMNS
2522            .iter()
2523            .find(|c| c.name == M::KEY)
2524            .map(|c| c.sql)
2525            .unwrap_or(SqlType::Integer);
2526        if key_sql != SqlType::Integer && M::SPATIAL.is_some() {
2527            return Err(DbError::new(
2528                DbErrorKind::Unsupported,
2529                format!(
2530                    "`{}` declares spatial(…), which addresses rows by ROWID — those \
2531                     need an integer `#[model(id)]`, not a Uuid or String key",
2532                    M::TABLE
2533                ),
2534            ));
2535        }
2536        // A second attach of the same model (a re-attached database after a catalog swap)
2537        // keeps its store and hooks; only the resident rows are stale, and they are dropped
2538        // so the next fault reads the new file.
2539        if self.inner.stores.borrow().contains_key(&TypeId::of::<M>()) {
2540            let store = self.cache::<M>();
2541            let keys: Vec<u64> = store.with_untracked(|k| k.keys());
2542            store.depopulate_many(&keys);
2543            return Ok(());
2544        }
2545        if !M::EXTERNAL {
2546            self.ensure_table::<M>()?;
2547        }
2548        for l in M::LINKS {
2549            self.inner.links.borrow_mut().push(LinkInfo {
2550                owner_table: M::TABLE,
2551                field: l.field,
2552                local: l.local,
2553                target_table: l.target_table,
2554                remote: l.remote,
2555            });
2556        }
2557
2558        let store: Store<Keyed<M>> = Store::new(Keyed::new(Vec::new()));
2559        let store_id = store.store_id();
2560
2561        let columns: Vec<String> = M::COLUMNS.iter().map(|c| c.name.to_string()).collect();
2562        let fields: Vec<String> = M::COLUMNS.iter().map(|c| c.field.to_string()).collect();
2563        let row_for = {
2564            Rc::new(move |key: u64| store.with_untracked(|k| k.get(key).map(|m| m.to_row())))
2565                as Rc<dyn Fn(u64) -> Option<Vec<Value>>>
2566        };
2567        let all_rows = {
2568            Rc::new(move || {
2569                store.with_untracked(|k| {
2570                    k.items().iter().map(|m| (m.handle(), m.to_row())).collect()
2571                })
2572            }) as Rc<dyn Fn() -> Vec<(u64, Vec<Value>)>>
2573        };
2574        let resident_keys =
2575            Rc::new(move || store.with_untracked(|k| k.keys())) as Rc<dyn Fn() -> Vec<u64>>;
2576        let resident_len =
2577            Rc::new(move || store.with_untracked(|k| k.len())) as Rc<dyn Fn() -> usize>;
2578        let is_resident = Rc::new(move |h: u64| store.with_untracked(|k| k.get(h).is_some()))
2579            as Rc<dyn Fn(u64) -> bool>;
2580
2581        let absorb = {
2582            Rc::new(
2583                move |raw_rows: Vec<Vec<Value>>| -> Result<Vec<u64>, DbError> {
2584                    let mut decoded: Vec<M> = Vec::with_capacity(raw_rows.len());
2585                    for r in raw_rows {
2586                        decoded.push(M::from_row(&r)?);
2587                    }
2588                    let keys: Vec<u64> = decoded.iter().map(|m| m.handle()).collect();
2589                    store.populate(decoded);
2590                    Ok(keys)
2591                },
2592            ) as AbsorbFn
2593        };
2594        let refresh = {
2595            Rc::new(move |raw_rows: Vec<Vec<Value>>| -> Result<bool, DbError> {
2596                let mut fresh: Vec<M> = Vec::with_capacity(raw_rows.len());
2597                for r in raw_rows {
2598                    fresh.push(M::from_row(&r)?);
2599                }
2600                let existing: Vec<u64> = store.with_untracked(|k| k.keys());
2601                let fresh_keys: std::collections::HashSet<u64> =
2602                    fresh.iter().map(|m| m.handle()).collect();
2603                let mut changed = false;
2604                day_model::with_author(ModelContainer::EXTERNAL_AUTHOR, || {
2605                    for m in fresh {
2606                        let key = m.handle();
2607                        match store.with_untracked(|k| k.get(key).map(|old| old.to_row())) {
2608                            // Selected by resident keys, so an unknown row means the cache
2609                            // moved underneath us; treat it as an arrival.
2610                            None => {
2611                                changed = true;
2612                                store.restructure("external", Op::Insert, key, |k| k.push(m));
2613                            }
2614                            Some(old) => {
2615                                let new_row = m.to_row();
2616                                let labels: Vec<&'static str> = M::COLUMNS
2617                                    .iter()
2618                                    .enumerate()
2619                                    .filter(|(i, _)| Row::get(&old, *i) != Row::get(&new_row, *i))
2620                                    .map(|(_, c)| c.field)
2621                                    .collect();
2622                                if !labels.is_empty() {
2623                                    changed = true;
2624                                    store.merge_row(key, m, &labels);
2625                                }
2626                            }
2627                        }
2628                    }
2629                    for gone in existing.into_iter().filter(|k| !fresh_keys.contains(k)) {
2630                        changed = true;
2631                        store.restructure("external", Op::Delete, gone, |k| {
2632                            k.remove(gone);
2633                        });
2634                    }
2635                });
2636                Ok(changed)
2637            }) as RefreshFn
2638        };
2639        let evict = Rc::new(move |candidates: &[u64], want: usize| {
2640            let doomed: Vec<u64> = candidates
2641                .iter()
2642                .copied()
2643                .filter(|h| !store.is_observed(*h))
2644                .take(want)
2645                .collect();
2646            store.depopulate_many(&doomed)
2647        }) as EvictFn;
2648        let watch_undo = Rc::new(move |stack: &day_model::UndoStack| stack.watch(store))
2649            as Rc<dyn Fn(&day_model::UndoStack)>;
2650        // After a flush: the pending bytes of these rows' lazy fields are in the file, so the
2651        // fields settle to stored, under the database's own author so nothing re-dirties.
2652        let settle = Rc::new(move |keys: &[u64]| {
2653            let mut out = Vec::new();
2654            if M::LAZY_FIELDS.is_empty() {
2655                return out;
2656            }
2657            day_model::with_author(ModelContainer::EXTERNAL_AUTHOR, || {
2658                for &key in keys {
2659                    let Some(mut row) = store.with_untracked(|k| k.get(key).cloned()) else {
2660                        continue;
2661                    };
2662                    let taken = row.settle_lazy();
2663                    if taken.is_empty() {
2664                        continue;
2665                    }
2666                    store.merge_row(key, row, M::LAZY_FIELDS);
2667                    out.extend(taken.into_iter().map(|(f, b)| (key, f, b)));
2668                }
2669            });
2670            out
2671        }) as SettleFn;
2672
2673        self.inner.tables.borrow_mut().insert(
2674            store_id,
2675            TableHooks {
2676                table: M::TABLE,
2677                name: TableName::of::<M>(),
2678                key_cols: vec![M::KEY.to_string()],
2679                key_where: Rc::new(|h| (format!("{} = ?", ident(M::KEY)), vec![key_param(h)])),
2680                columns,
2681                column_names: M::COLUMNS.iter().map(|c| c.name).collect(),
2682                fields,
2683                lazy: M::COLUMNS.iter().map(|c| c.lazy).collect(),
2684                settle,
2685                resident_len,
2686                fts: (!M::FTS_COLUMNS.is_empty()).then(|| format!("{}_fts", M::TABLE)),
2687                fts_key: if key_sql == SqlType::Integer {
2688                    "rowid"
2689                } else {
2690                    "day_key"
2691                },
2692                spatial: M::SPATIAL.map(|s| {
2693                    (
2694                        s.lat.to_string(),
2695                        s.lon.to_string(),
2696                        format!("{}_geo", M::TABLE),
2697                    )
2698                }),
2699                row_for,
2700                all_rows,
2701                resident_keys,
2702                is_resident,
2703                absorb,
2704                refresh,
2705                evict,
2706                #[cfg(not(target_arch = "wasm32"))]
2707                dispose_cache: Rc::new(move || store.dispose_contents()),
2708                watch_undo,
2709            },
2710        );
2711        self.inner
2712            .stores
2713            .borrow_mut()
2714            .insert(TypeId::of::<M>(), Box::new(store));
2715        Ok(())
2716    }
2717
2718    fn ensure_table<M: Model>(&self) -> Result<(), DbError> {
2719        // Relation-contributed clauses fold into the fingerprint: adopting or changing a
2720        // delete rule re-runs this path. An existing table cannot gain the SQL-level clause
2721        // in place (SQLite has no `ALTER ADD CONSTRAINT`), so the comparison below routes
2722        // that difference through the table rebuild, which writes the declared DDL whole.
2723        let mut fp_val = model_fingerprint::<M>();
2724        for s in self
2725            .inner
2726            .fk_specs
2727            .borrow()
2728            .iter()
2729            .filter(|s| s.child_table == M::TABLE)
2730        {
2731            for b in s
2732                .child_field
2733                .bytes()
2734                .chain(s.parent_table.bytes())
2735                .chain(s.rule.sql().bytes())
2736            {
2737                fp_val ^= b as u64;
2738                fp_val = fp_val.wrapping_mul(0x1000_0000_01b3);
2739            }
2740        }
2741        let fp = format!("{fp_val:016x}");
2742        let stored = self.stored_fingerprint(M::TABLE)?;
2743        if stored.as_deref() == Some(fp.as_str()) {
2744            // The layout is known to match; the generated triggers are still reconciled, so
2745            // updated trigger logic reaches an existing file (an unchanged trigger is a read
2746            // and no write).
2747            self.conn().begin()?;
2748            let result = self
2749                .create_shadow_tables::<M>()
2750                .and_then(|()| self.conn().commit());
2751            if result.is_err() {
2752                let _ = self.conn().rollback();
2753            }
2754            return result;
2755        }
2756
2757        let name = TableName::of::<M>();
2758        // A missing table is created whole; an existing one is compared column by column,
2759        // index by index, and the comparison decides between in-place DDL and a rebuild,
2760        // or refuses before anything is touched.
2761        let delta = if self.table_exists(M::TABLE)? {
2762            let file = self.file_schema(name)?;
2763            Some((self.compare_schema::<M>(&file)?, file))
2764        } else {
2765            None
2766        };
2767        // A rebuild drops and recreates the table, which `PRAGMA foreign_keys` would treat
2768        // as a delete of every row (cascading into children). The pragma is a no-op inside
2769        // a transaction, so it toggles around one, and the rebuild's own
2770        // `foreign_key_check` is what guarantees nothing dangles afterwards.
2771        let rebuild = matches!(delta, Some((SchemaDelta::Rebuild, _)));
2772        let fk_was_on = rebuild && self.foreign_keys_enabled()?;
2773        if fk_was_on {
2774            self.conn().execute("PRAGMA foreign_keys = OFF", &[])?;
2775        }
2776
2777        // DDL, copy and backfill are one transaction: a failed migration leaves the old
2778        // table, index and fingerprint usable. Remove triggers before dropping indexed
2779        // columns.
2780        // Bound first: the `RefMut` the `begin` call holds must be gone before the closure
2781        // borrows the connection again.
2782        let began = self.conn().begin();
2783        let result = began.and_then(|()| {
2784            let result = (|| {
2785                let t = name.bare;
2786                if self.table_exists(&format!("{t}_fts"))? {
2787                    for suffix in ["ai", "ad", "au"] {
2788                        self.conn().execute(
2789                            &format!(
2790                                "DROP TRIGGER IF EXISTS {}",
2791                                ident(&format!("{t}_fts_{suffix}"))
2792                            ),
2793                            &[],
2794                        )?;
2795                    }
2796                    self.conn()
2797                        .execute(&format!("DROP TABLE {}", name.shadow("_fts")), &[])?;
2798                    self.conn().execute(
2799                        &format!("DROP TABLE IF EXISTS {}", name.shadow("_fts_keys")),
2800                        &[],
2801                    )?;
2802                }
2803                let mut unique_indexes: Vec<&'static str> = Vec::new();
2804                match delta {
2805                    None => self.create_table_named::<M>(name.sql())?,
2806                    Some((SchemaDelta::Lightweight(plan), _)) => {
2807                        unique_indexes = plan.unique_indexes.clone();
2808                        self.lightweight_migrate::<M>(&plan)?;
2809                    }
2810                    Some((SchemaDelta::Rebuild, file)) => {
2811                        self.rebuild_table::<M>(&file)?;
2812                    }
2813                }
2814                self.create_indexes::<M>(&unique_indexes)?;
2815                if rebuild {
2816                    let dangling = Self::foreign_key_check_on(self.conn().as_mut())?;
2817                    if let Some(first) = dangling.first() {
2818                        return Err(DbError::new(
2819                            DbErrorKind::Schema,
2820                            format!(
2821                                "rebuilding `{}` leaves {} row(s) with a dangling foreign \
2822                                 key ({first}); the file is unchanged",
2823                                M::TABLE,
2824                                dangling.len()
2825                            ),
2826                        ));
2827                    }
2828                }
2829                self.create_shadow_tables::<M>()?;
2830                // The fingerprint is the last write: it records a layout that has been
2831                // brought to the declaration and verified, never one still in flight.
2832                self.store_fingerprint(M::TABLE, &fp)?;
2833                self.conn().commit()
2834            })();
2835            if result.is_err() {
2836                let _ = self.conn().rollback();
2837            }
2838            result
2839        });
2840        if fk_was_on {
2841            let restored = self
2842                .conn()
2843                .execute("PRAGMA foreign_keys = ON", &[])
2844                .map(|_| ());
2845            return result.and(restored);
2846        }
2847        result
2848    }
2849
2850    /// Whether this connection enforces foreign keys right now (`PRAGMA foreign_keys`). A
2851    /// driver that answers nothing (the Recorder) counts as not enforcing.
2852    fn foreign_keys_enabled(&self) -> Result<bool, DbError> {
2853        let mut on = false;
2854        self.conn().query("PRAGMA foreign_keys", &[], &mut |row| {
2855            on = row.get(0).as_int().unwrap_or(0) != 0;
2856        })?;
2857        Ok(on)
2858    }
2859
2860    /// The FTS5 and R*Tree shadows a model declares: virtual tables plus `AFTER` triggers, so
2861    /// the indexes stay true inside the same transaction as every write, even a write made by
2862    /// another tool straight into the file. Backfilled when first created.
2863    fn create_shadow_tables<M: Model>(&self) -> Result<(), DbError> {
2864        let name = TableName::of::<M>();
2865        // The plain names, for messages and `sqlite_master` lookups; the quoted ones, for
2866        // every statement. A shadow's trigger is named after the shadow, quoted as one name.
2867        let bare = name.bare;
2868        let t = name.sql();
2869        let key = ident(M::KEY);
2870        let trigger = |suffix: &str| ident(&format!("{bare}{suffix}"));
2871        if !M::FTS_COLUMNS.is_empty() {
2872            if !self.inner.caps.full_text_search {
2873                return Err(DbError::new(
2874                    DbErrorKind::Unsupported,
2875                    format!(
2876                        "`{bare}` declares fts(…) but this driver's engine has no FTS5 — the \
2877                         bundled and cipher engines compile it in"
2878                    ),
2879                ));
2880            }
2881            let fts = name.shadow("_fts");
2882            // The hidden column FTS5 takes its commands through carries the index's own name.
2883            let fts_command = ident(&format!("{bare}_fts"));
2884            let cols = column_list(M::FTS_COLUMNS);
2885            let fresh = !self.table_exists(&format!("{bare}_fts"))?;
2886            // The tokenizer rides in the DDL; its value is a compile-time literal, quoted
2887            // through SQL's own escape so an apostrophe cannot break the statement.
2888            let tokenize = match M::FTS_TOKENIZE {
2889                Some(tok) => format!(", tokenize='{}'", tok.replace('\'', "''")),
2890                None => String::new(),
2891            };
2892            let new_cols = prefixed_list("new", M::FTS_COLUMNS);
2893            let wide = M::COLUMNS
2894                .iter()
2895                .find(|c| c.name == M::KEY)
2896                .is_some_and(|c| c.sql != SqlType::Integer);
2897            if wide {
2898                if M::FTS_COLUMNS.contains(&"day_key") {
2899                    return Err(DbError::new(
2900                        DbErrorKind::Unsupported,
2901                        "day_key is reserved in a non-integer-key FTS index",
2902                    ));
2903                }
2904                let key_type = M::COLUMNS
2905                    .iter()
2906                    .find(|c| c.name == M::KEY)
2907                    .expect("key column")
2908                    .sql
2909                    .ddl();
2910                let fts_keys = name.shadow("_fts_keys");
2911                // FTS rowids stay private. An indexed mapping makes update/delete O(log n)
2912                // rather than scanning the unindexed public key in every FTS row.
2913                self.conn().execute(&format!("CREATE TABLE IF NOT EXISTS {fts_keys}(day_rowid INTEGER PRIMARY KEY, day_key {key_type} NOT NULL UNIQUE)"), &[])?;
2914                self.conn().execute(&format!("CREATE VIRTUAL TABLE IF NOT EXISTS {fts} USING fts5(day_key UNINDEXED, {cols}{tokenize})"), &[])?;
2915                let insert = format!(
2916                    "INSERT INTO {fts_keys}(day_key) VALUES (new.{key}); INSERT INTO {fts}(rowid, day_key, {cols}) VALUES ((SELECT day_rowid FROM {fts_keys} WHERE day_key = new.{key}), new.{key}, {new_cols});"
2917                );
2918                let delete = format!(
2919                    "DELETE FROM {fts} WHERE rowid = (SELECT day_rowid FROM {fts_keys} WHERE day_key = old.{key}); DELETE FROM {fts_keys} WHERE day_key = old.{key};"
2920                );
2921                let (update_of, changed) = fts_update_guard(M::KEY, M::FTS_COLUMNS);
2922                for (suffix, event, body) in [
2923                    ("_fts_ai", "INSERT".to_string(), insert.clone()),
2924                    ("_fts_ad", "DELETE".to_string(), delete.clone()),
2925                    (
2926                        "_fts_au",
2927                        format!("UPDATE OF {update_of}"),
2928                        format!("{delete} {insert}"),
2929                    ),
2930                ] {
2931                    let when = if suffix == "_fts_au" {
2932                        format!(" WHEN {changed}")
2933                    } else {
2934                        String::new()
2935                    };
2936                    self.ensure_trigger(
2937                        &format!("{bare}{suffix}"),
2938                        name.schema,
2939                        &format!(
2940                            "CREATE TRIGGER {} AFTER {event} ON {t}{when} BEGIN {body} END",
2941                            trigger(suffix)
2942                        ),
2943                    )?;
2944                }
2945                if fresh {
2946                    self.conn().execute(
2947                        &format!("INSERT INTO {fts_keys}(day_key) SELECT {key} FROM {t}"),
2948                        &[],
2949                    )?;
2950                    let qualified = prefixed_list("b", M::FTS_COLUMNS);
2951                    self.conn().execute(&format!("INSERT INTO {fts}(rowid, day_key, {cols}) SELECT k.day_rowid, b.{key}, {qualified} FROM {t} b JOIN {fts_keys} k ON k.day_key = b.{key}"), &[])?;
2952                }
2953            } else {
2954                // FTS5 reads its options as SQL string literals; the content table and its
2955                // rowid column are plain names inside them.
2956                self.conn().execute(
2957                    &format!(
2958                        "CREATE VIRTUAL TABLE IF NOT EXISTS {fts} USING fts5({cols}, \
2959                     content='{}', content_rowid='{}'{tokenize})",
2960                        bare.replace('\'', "''"),
2961                        M::KEY.replace('\'', "''")
2962                    ),
2963                    &[],
2964                )?;
2965                let old_cols = prefixed_list("old", M::FTS_COLUMNS);
2966                self.ensure_trigger(
2967                    &format!("{bare}_fts_ai"),
2968                    name.schema,
2969                    &format!(
2970                        "CREATE TRIGGER {} AFTER INSERT ON {t} BEGIN \
2971                     INSERT INTO {fts}(rowid, {cols}) VALUES (new.{key}, {new_cols}); END",
2972                        trigger("_fts_ai")
2973                    ),
2974                )?;
2975                self.ensure_trigger(
2976                    &format!("{bare}_fts_ad"),
2977                    name.schema,
2978                    &format!(
2979                        "CREATE TRIGGER {} AFTER DELETE ON {t} BEGIN \
2980                     INSERT INTO {fts}({fts_command}, rowid, {cols}) VALUES ('delete', old.{key}, {old_cols}); END",
2981                        trigger("_fts_ad")
2982                    ),
2983                )?;
2984                // Only a change to indexed content or to the row's identity re-indexes it: an
2985                // update that touches other columns, or assigns an indexed column its own
2986                // value, leaves the index alone.
2987                let (update_of, changed) = fts_update_guard(M::KEY, M::FTS_COLUMNS);
2988                self.ensure_trigger(
2989                    &format!("{bare}_fts_au"),
2990                    name.schema,
2991                    &format!(
2992                        "CREATE TRIGGER {} AFTER UPDATE OF {update_of} ON {t} WHEN {changed} BEGIN \
2993                     INSERT INTO {fts}({fts_command}, rowid, {cols}) VALUES ('delete', old.{key}, {old_cols}); \
2994                     INSERT INTO {fts}(rowid, {cols}) VALUES (new.{key}, {new_cols}); END",
2995                        trigger("_fts_au")
2996                    ),
2997                )?;
2998                if fresh {
2999                    // External-content rebuild: index whatever rows predate the declaration.
3000                    self.conn().execute(
3001                        &format!("INSERT INTO {fts}({fts_command}) VALUES ('rebuild')"),
3002                        &[],
3003                    )?;
3004                }
3005            }
3006        }
3007        if let Some(s) = M::SPATIAL {
3008            if !self.inner.caps.rtree {
3009                return Err(DbError::new(
3010                    DbErrorKind::Unsupported,
3011                    format!(
3012                        "`{bare}` declares spatial(…) but this driver's engine has no R*Tree — \
3013                         the bundled and cipher engines compile it in"
3014                    ),
3015                ));
3016            }
3017            let (lat, lon) = (ident(s.lat), ident(s.lon));
3018            let geo = name.shadow("_geo");
3019            let fresh = !self.table_exists(&format!("{bare}_geo"))?;
3020            self.conn().execute(
3021                &format!(
3022                    "CREATE VIRTUAL TABLE IF NOT EXISTS {geo} USING rtree({key}, \
3023                     min_lat, max_lat, min_lon, max_lon)"
3024                ),
3025                &[],
3026            )?;
3027            self.ensure_trigger(
3028                &format!("{bare}_geo_ai"),
3029                name.schema,
3030                &format!(
3031                    "CREATE TRIGGER {} AFTER INSERT ON {t} BEGIN \
3032                     INSERT OR REPLACE INTO {geo} VALUES (new.{key}, new.{lat}, new.{lat}, new.{lon}, new.{lon}); END",
3033                    trigger("_geo_ai")
3034                ),
3035            )?;
3036            self.ensure_trigger(
3037                &format!("{bare}_geo_au"),
3038                name.schema,
3039                &format!(
3040                    "CREATE TRIGGER {} AFTER UPDATE OF {lat}, {lon} ON {t} BEGIN \
3041                     INSERT OR REPLACE INTO {geo} VALUES (new.{key}, new.{lat}, new.{lat}, new.{lon}, new.{lon}); END",
3042                    trigger("_geo_au")
3043                ),
3044            )?;
3045            self.ensure_trigger(
3046                &format!("{bare}_geo_ad"),
3047                name.schema,
3048                &format!(
3049                    "CREATE TRIGGER {} AFTER DELETE ON {t} BEGIN \
3050                     DELETE FROM {geo} WHERE {key} = old.{key}; END",
3051                    trigger("_geo_ad")
3052                ),
3053            )?;
3054            if fresh {
3055                self.conn().execute(
3056                    &format!(
3057                        "INSERT OR REPLACE INTO {geo} \
3058                         SELECT {key}, {lat}, {lat}, {lon}, {lon} FROM {t}"
3059                    ),
3060                    &[],
3061                )?;
3062            }
3063        }
3064        Ok(())
3065    }
3066
3067    /// Install a generated trigger, replacing one whose stored text differs: updated trigger
3068    /// logic reaches an existing file on the open that carries it, and a trigger that is
3069    /// already right costs one `sqlite_master` read and no write. `create_sql` is the plain
3070    /// `CREATE TRIGGER` statement; the engine stores that text verbatim, which is what the
3071    /// comparison reads back.
3072    fn ensure_trigger(
3073        &self,
3074        bare_name: &str,
3075        schema: Option<&str>,
3076        create_sql: &str,
3077    ) -> Result<(), DbError> {
3078        let master = table_sql(schema, "sqlite_master");
3079        let mut stored: Option<String> = None;
3080        self.conn().query(
3081            &format!("SELECT sql FROM {master} WHERE type = 'trigger' AND name = ?"),
3082            &[Value::Text(bare_name.into())],
3083            &mut |row| {
3084                if let Ok(sql) = row.get(0).as_text() {
3085                    stored = Some(sql.to_string());
3086                }
3087            },
3088        )?;
3089        match stored {
3090            Some(sql) if sql == create_sql => return Ok(()),
3091            Some(_) => {
3092                self.conn().execute(
3093                    &format!("DROP TRIGGER IF EXISTS {}", table_sql(schema, bare_name)),
3094                    &[],
3095                )?;
3096            }
3097            None => {}
3098        }
3099        self.conn().execute(create_sql, &[])?;
3100        Ok(())
3101    }
3102
3103    fn table_exists(&self, table: &str) -> Result<bool, DbError> {
3104        let mut found = false;
3105        self.conn().query(
3106            "SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?",
3107            &[Value::Text(table.into())],
3108            &mut |_| found = true,
3109        )?;
3110        Ok(found)
3111    }
3112
3113    /// `M`'s declared DDL under `table_sql` (its own quoted name, or the `_new` name a
3114    /// rebuild copies into). The fresh form carries every constraint inline; the upgrade
3115    /// paths produce the same enforced constraints by other means (a `NOT NULL DEFAULT`
3116    /// addition, a `day_uidx_` unique index), and the comparison treats them as equal.
3117    fn create_table_named<M: Model>(&self, table_sql: String) -> Result<(), DbError> {
3118        let cols: Vec<String> = self
3119            .declared_columns::<M>()
3120            .iter()
3121            .map(|d| {
3122                let c = &d.def;
3123                let mut s = format!("{} {}", ident(c.name), c.sql.ddl());
3124                if d.pk {
3125                    s.push_str(" PRIMARY KEY");
3126                } else if c.not_null {
3127                    s.push_str(" NOT NULL");
3128                }
3129                if c.unique && !d.pk {
3130                    s.push_str(" UNIQUE");
3131                }
3132                // A declared relation's foreign key: enforced by the engine too, so another
3133                // process honors the same delete rule, and so a cascade's reach into rows
3134                // this process never faulted still lands in the file. Deferred, so
3135                // within-transaction statement order (a cascade's children, an undo's
3136                // re-inserts) never trips it.
3137                if let Some(fk) = &d.fk {
3138                    s.push_str(&fk.clause());
3139                }
3140                s
3141            })
3142            .collect();
3143        let body = format!("CREATE TABLE {table_sql} ({})", cols.join(", "));
3144        // `STRICT` where the engine allows it (always, for the bundled build); older system
3145        // SQLites reject the keyword, and the plain form is the fallback.
3146        if self.conn().execute(&format!("{body} STRICT"), &[]).is_err() {
3147            self.conn().execute(&body, &[])?;
3148        }
3149        Ok(())
3150    }
3151
3152    /// The indexes `M` owns in the file, by name: one per `indexed` column, one per declared
3153    /// relation's foreign-key column (what `children_of` selects on, what relation predicates
3154    /// correlate on, and what the engine scans to enforce `ON DELETE`; unindexed, each is a
3155    /// full scan of the child table), one per composite declaration, and a unique index for
3156    /// each column in `unique_indexes`, the declared-unique columns whose table carries no
3157    /// inline `UNIQUE` because they arrived through `ADD COLUMN`.
3158    fn declared_indexes<M: Model>(&self, unique_indexes: &[&'static str]) -> Vec<DeclaredIndex> {
3159        let fk_cols: Vec<&str> = self
3160            .inner
3161            .fk_specs
3162            .borrow()
3163            .iter()
3164            .filter(|s| s.child_table == M::TABLE)
3165            .filter_map(|s| {
3166                M::COLUMNS
3167                    .iter()
3168                    .find(|c| c.field == s.child_field)
3169                    .map(|c| c.name)
3170            })
3171            .collect();
3172        let bare = TableName::of::<M>().bare;
3173        let mut out: Vec<DeclaredIndex> = M::COLUMNS
3174            .iter()
3175            .filter(|c| c.indexed || (fk_cols.contains(&c.name) && c.name != M::KEY))
3176            .map(|c| DeclaredIndex {
3177                name: format!("day_idx_{bare}_{}", c.name),
3178                columns: vec![c.name.to_string()],
3179                unique: false,
3180            })
3181            .collect();
3182        out.extend(M::COMPOSITE_INDEXES.iter().map(|idx| DeclaredIndex {
3183            name: format!("day_idx_{bare}_{}", idx.join("_")),
3184            columns: idx.iter().map(|c| c.to_string()).collect(),
3185            unique: false,
3186        }));
3187        out.extend(unique_indexes.iter().map(|c| DeclaredIndex {
3188            name: format!("day_uidx_{bare}_{c}"),
3189            columns: vec![c.to_string()],
3190            unique: true,
3191        }));
3192        out.extend(M::UNIQUE_INDEXES.iter().map(|idx| DeclaredIndex {
3193            name: format!("day_uidx_{bare}_{}", idx.join("_")),
3194            columns: idx.iter().map(|c| c.to_string()).collect(),
3195            unique: true,
3196        }));
3197        out
3198    }
3199
3200    fn create_indexes<M: Model>(&self, unique_indexes: &[&'static str]) -> Result<(), DbError> {
3201        let name = TableName::of::<M>();
3202        let t = name.sql();
3203        for idx in self.declared_indexes::<M>(unique_indexes) {
3204            self.conn().execute(
3205                &format!(
3206                    "CREATE {}INDEX IF NOT EXISTS {} ON {t}({})",
3207                    if idx.unique { "UNIQUE " } else { "" },
3208                    table_sql(name.schema, &idx.name),
3209                    column_list(&idx.columns)
3210                ),
3211                &[],
3212            )?;
3213        }
3214        Ok(())
3215    }
3216
3217    /// `M`'s columns as declared, with the relation-contributed foreign key resolved: the
3218    /// declared side of [`ModelContainer::compare_schema`], and what the DDL is written from.
3219    fn declared_columns<M: Model>(&self) -> Vec<DeclaredColumn> {
3220        let specs = self.inner.fk_specs.borrow();
3221        M::COLUMNS
3222            .iter()
3223            .enumerate()
3224            .map(|(index, c)| DeclaredColumn {
3225                def: *c,
3226                index,
3227                pk: c.name == M::KEY,
3228                fk: specs
3229                    .iter()
3230                    .find(|f| f.child_table == M::TABLE && f.child_field == c.field)
3231                    .map(|s| DeclaredFk {
3232                        parent_sql: s.parent_sql.clone(),
3233                        parent_bare: s.parent_bare,
3234                        parent_key: s.parent_key,
3235                        rule: s.rule,
3236                    }),
3237            })
3238            .collect()
3239    }
3240
3241    /// The table as the file has it: `PRAGMA table_info`, `foreign_key_list`, `index_list`
3242    /// and `index_info`, read into one value the comparison and the rebuild both consume.
3243    fn file_schema(&self, name: TableName) -> Result<FileSchema, DbError> {
3244        let mut columns: Vec<FileColumn> = Vec::new();
3245        self.conn().query(
3246            &pragma_sql(name.schema, "table_info", name.bare),
3247            &[],
3248            &mut |row| {
3249                columns.push(FileColumn {
3250                    name: row.get(1).as_text().unwrap_or("").to_string(),
3251                    decl_type: row.get(2).as_text().unwrap_or("").to_ascii_uppercase(),
3252                    not_null: row.get(3).as_int().unwrap_or(0) != 0,
3253                    pk: row.get(5).as_int().unwrap_or(0) != 0,
3254                    fk: None,
3255                });
3256            },
3257        )?;
3258        self.conn().query(
3259            &pragma_sql(name.schema, "foreign_key_list", name.bare),
3260            &[],
3261            &mut |row| {
3262                let from = row.get(3).as_text().unwrap_or("").to_string();
3263                if let Some(col) = columns.iter_mut().find(|c| c.name == from) {
3264                    col.fk = Some(FileFk {
3265                        parent: row.get(2).as_text().unwrap_or("").to_string(),
3266                        parent_key: row.get(4).as_text().unwrap_or("").to_string(),
3267                        on_delete: row.get(6).as_text().unwrap_or("").to_ascii_uppercase(),
3268                    });
3269                }
3270            },
3271        )?;
3272        let mut indexes: Vec<FileIndex> = Vec::new();
3273        self.conn().query(
3274            &pragma_sql(name.schema, "index_list", name.bare),
3275            &[],
3276            &mut |row| {
3277                indexes.push(FileIndex {
3278                    name: row.get(1).as_text().unwrap_or("").to_string(),
3279                    unique: row.get(2).as_int().unwrap_or(0) != 0,
3280                    origin: row.get(3).as_text().unwrap_or("").to_string(),
3281                    columns: Vec::new(),
3282                });
3283            },
3284        )?;
3285        for idx in &mut indexes {
3286            let mut cols: Vec<(i64, String)> = Vec::new();
3287            self.conn().query(
3288                &pragma_sql(name.schema, "index_info", &idx.name),
3289                &[],
3290                &mut |row| {
3291                    cols.push((
3292                        row.get(0).as_int().unwrap_or(0),
3293                        row.get(2).as_text().unwrap_or("").to_string(),
3294                    ));
3295                },
3296            )?;
3297            cols.sort_by_key(|(seq, _)| *seq);
3298            idx.columns = cols.into_iter().map(|(_, c)| c).collect();
3299        }
3300        Ok(FileSchema { columns, indexes })
3301    }
3302
3303    /// Decide how the file's table reaches the declaration. Column and index additions and
3304    /// drops are closed in place; any other difference (a type, a nullability, a unique
3305    /// constraint, a foreign key or its delete action) is a rebuild; a change the rebuild
3306    /// could not fill truthfully (the key column, a required column with no usable default)
3307    /// is refused here, before anything is touched.
3308    fn compare_schema<M: Model>(&self, file: &FileSchema) -> Result<SchemaDelta, DbError> {
3309        let declared = self.declared_columns::<M>();
3310        let defaults = M::default_row();
3311        let bare = TableName::of::<M>().bare;
3312        let refuse = |column: &str, what: String| {
3313            Err(DbError::new(
3314                DbErrorKind::Schema,
3315                format!(
3316                    "`{}`.`{column}`: {what}; this is not a change the container can make to \
3317                     an existing table, and it refuses to open rather than guess (a staged \
3318                     migration can make it)",
3319                    M::TABLE
3320                ),
3321            ))
3322        };
3323        let mut plan = LightweightPlan::default();
3324        // Any one of these differences needs the copy; which one is immaterial to the work.
3325        let mut rebuild = false;
3326        let mut note = |_why: String| rebuild = true;
3327        let inline_unique = |col: &str| {
3328            file.indexes
3329                .iter()
3330                .any(|i| i.origin == "u" && i.columns.len() == 1 && i.columns[0] == col)
3331        };
3332        let unique_index_name = |col: &str| format!("day_uidx_{bare}_{col}");
3333        let has_unique_index = |col: &str| {
3334            let name = unique_index_name(col);
3335            file.indexes
3336                .iter()
3337                .any(|i| i.name == name && i.unique && i.columns.len() == 1 && i.columns[0] == col)
3338        };
3339
3340        for d in &declared {
3341            let c = &d.def;
3342            let default = Row::get(&defaults, d.index);
3343            let required = c.not_null || d.pk;
3344            match file.columns.iter().find(|f| f.name == c.name) {
3345                None => {
3346                    if d.pk {
3347                        return refuse(c.name, "the declared key column is not in the file".into());
3348                    }
3349                    if required && default == Value::Null {
3350                        return refuse(
3351                            c.name,
3352                            "a required column whose Rust default stores NULL cannot be \
3353                             added to existing rows"
3354                                .into(),
3355                        );
3356                    }
3357                    if d.fk.is_some() && required {
3358                        // `ADD COLUMN … REFERENCES` must default to NULL while foreign keys
3359                        // are enforced; a required reference needs the copy.
3360                        note(format!("required foreign-key column `{}` added", c.name));
3361                    } else {
3362                        plan.add.push(d.index);
3363                        if c.unique {
3364                            plan.unique_indexes.push(c.name);
3365                        }
3366                    }
3367                }
3368                Some(f) => {
3369                    if f.decl_type != c.sql.ddl() {
3370                        if d.pk {
3371                            return refuse(
3372                                c.name,
3373                                format!(
3374                                    "the key column is {} in the file and {} in the declaration",
3375                                    f.decl_type,
3376                                    c.sql.ddl()
3377                                ),
3378                            );
3379                        }
3380                        note(format!(
3381                            "`{}` is {} in the file and {} in the declaration",
3382                            c.name,
3383                            f.decl_type,
3384                            c.sql.ddl()
3385                        ));
3386                    }
3387                    if f.pk != d.pk {
3388                        return refuse(
3389                            c.name,
3390                            if d.pk {
3391                                "declared as the key but not the file's primary key".into()
3392                            } else {
3393                                "the file's primary key but not the declared key".into()
3394                            },
3395                        );
3396                    }
3397                    // The key's NOT NULL is implied by PRIMARY KEY (and reported either way
3398                    // by the engine, depending on its type), so only the other columns compare.
3399                    if !d.pk && f.not_null != c.not_null {
3400                        if c.not_null && default == Value::Null {
3401                            return refuse(
3402                                c.name,
3403                                "becomes required, but its Rust default stores NULL, so \
3404                                 existing NULLs cannot be filled"
3405                                    .into(),
3406                            );
3407                        }
3408                        note(format!(
3409                            "`{}` is {} in the file and {} in the declaration",
3410                            c.name,
3411                            if f.not_null { "NOT NULL" } else { "nullable" },
3412                            if c.not_null { "NOT NULL" } else { "nullable" }
3413                        ));
3414                    }
3415                    let want_unique = c.unique && !d.pk;
3416                    // A declared unique without the inline constraint owns its index,
3417                    // whether that index exists yet or not (`IF NOT EXISTS` keeps one).
3418                    match (want_unique, inline_unique(c.name), has_unique_index(c.name)) {
3419                        (true, false, _) => plan.unique_indexes.push(c.name),
3420                        (false, true, _) => note(format!(
3421                            "`{}` carries UNIQUE but is not declared unique",
3422                            c.name
3423                        )),
3424                        (false, false, true) => plan.drop_indexes.push(unique_index_name(c.name)),
3425                        _ => {}
3426                    }
3427                    let fk_matches = match (&d.fk, &f.fk) {
3428                        (None, None) => true,
3429                        (Some(want), Some(have)) => {
3430                            have.parent == want.parent_bare
3431                                && have.parent_key == want.parent_key
3432                                && have.on_delete == want.rule.sql()
3433                        }
3434                        _ => false,
3435                    };
3436                    if !fk_matches {
3437                        note(format!("`{}`'s foreign key differs", c.name));
3438                    }
3439                }
3440            }
3441        }
3442        for f in file
3443            .columns
3444            .iter()
3445            .filter(|f| !declared.iter().any(|d| d.def.name == f.name))
3446        {
3447            if f.pk {
3448                return refuse(&f.name, "the file's primary key is not declared".into());
3449            }
3450            // `DROP COLUMN` refuses a column under a constraint or a foreign index; those go
3451            // through the copy, which simply leaves them out.
3452            let covered_by_foreign_index = file.indexes.iter().any(|i| {
3453                i.origin == "c" && !is_day_index(&i.name, bare) && i.columns.contains(&f.name)
3454            });
3455            if f.fk.is_some() || inline_unique(&f.name) || covered_by_foreign_index {
3456                note(format!("constrained column `{}` dropped", f.name));
3457            } else {
3458                plan.drop.push(f.name.clone());
3459            }
3460        }
3461        if let Some(extra) = file
3462            .indexes
3463            .iter()
3464            .find(|i| i.origin == "u" && i.columns.len() > 1)
3465        {
3466            note(format!(
3467                "undeclared multi-column UNIQUE constraint over ({})",
3468                extra.columns.join(", ")
3469            ));
3470        }
3471        // Day's own indexes: one that no longer matches a declaration is dropped in place;
3472        // a missing one is created after the column work.
3473        let want = self.declared_indexes::<M>(&plan.unique_indexes);
3474        for i in file
3475            .indexes
3476            .iter()
3477            .filter(|i| i.origin == "c" && is_day_index(&i.name, bare))
3478        {
3479            let matches = want
3480                .iter()
3481                .any(|w| w.name == i.name && w.columns == i.columns && w.unique == i.unique);
3482            if !matches && !plan.drop_indexes.contains(&i.name) {
3483                plan.drop_indexes.push(i.name.clone());
3484            }
3485        }
3486        Ok(if rebuild {
3487            SchemaDelta::Rebuild
3488        } else {
3489            SchemaDelta::Lightweight(plan)
3490        })
3491    }
3492
3493    /// Close the gap in place: indexes that no longer match are dropped, missing columns are
3494    /// added with their declared constraints (`NOT NULL DEFAULT <Rust default>`; a nullable
3495    /// foreign key with its `REFERENCES`), and columns the declaration lost are dropped.
3496    /// Declared-unique additions get their unique index from `create_indexes`, since
3497    /// `ADD COLUMN` cannot carry `UNIQUE`.
3498    fn lightweight_migrate<M: Model>(&self, plan: &LightweightPlan) -> Result<(), DbError> {
3499        let name = TableName::of::<M>();
3500        let t = name.sql();
3501        let declared = self.declared_columns::<M>();
3502        let defaults = M::default_row();
3503        for idx in &plan.drop_indexes {
3504            self.conn().execute(
3505                &format!("DROP INDEX IF EXISTS {}", table_sql(name.schema, idx)),
3506                &[],
3507            )?;
3508        }
3509        for &i in &plan.add {
3510            let d = &declared[i];
3511            let c = &d.def;
3512            let default = Row::get(&defaults, i);
3513            let mut ddl = format!(
3514                "ALTER TABLE {t} ADD COLUMN {} {}",
3515                ident(c.name),
3516                c.sql.ddl()
3517            );
3518            if c.not_null {
3519                ddl.push_str(&format!(" NOT NULL DEFAULT {}", sql_literal(&default)?));
3520            }
3521            if let Some(fk) = &d.fk {
3522                ddl.push_str(&fk.clause());
3523            }
3524            self.conn().execute(&ddl, &[])?;
3525            // A nullable column whose Rust default is a value still backfills, as before.
3526            if !c.not_null && default != Value::Null {
3527                self.conn()
3528                    .execute(&format!("UPDATE {t} SET {} = ?", ident(c.name)), &[default])?;
3529            }
3530        }
3531        for gone in &plan.drop {
3532            self.conn()
3533                .execute(&format!("ALTER TABLE {t} DROP COLUMN {}", ident(gone)), &[])?;
3534        }
3535        Ok(())
3536    }
3537
3538    /// SQLite's documented procedure for every other change
3539    /// (<https://www.sqlite.org/lang_altertable.html#otheralter>): the declared table is
3540    /// created under a temporary name, the rows copied across (shared columns as they are,
3541    /// a required column that was nullable through `COALESCE` with its Rust default, a
3542    /// missing one from that default), the old table dropped, the new one renamed into
3543    /// place, and the application's own indexes that still apply re-created. The caller
3544    /// holds the transaction, has foreign keys off, and runs `foreign_key_check` after.
3545    /// Application-owned triggers on the table go with it; their owner re-creates them.
3546    fn rebuild_table<M: Model>(&self, file: &FileSchema) -> Result<(), DbError> {
3547        let name = TableName::of::<M>();
3548        let t = name.sql();
3549        let bare = name.bare;
3550        let tmp_bare = format!("{bare}_new");
3551        let tmp = table_sql(name.schema, &tmp_bare);
3552        let declared = self.declared_columns::<M>();
3553        let defaults = M::default_row();
3554        let master = table_sql(name.schema, "sqlite_master");
3555
3556        // The application's own indexes, to re-create when every column they name survives.
3557        let mut foreign_indexes: Vec<String> = Vec::new();
3558        self.conn().query(
3559            &format!(
3560                "SELECT name, sql FROM {master} WHERE type = 'index' AND tbl_name = ? \
3561                 AND sql IS NOT NULL"
3562            ),
3563            &[Value::Text(bare.into())],
3564            &mut |row| {
3565                let idx_name = row.get(0).as_text().unwrap_or("").to_string();
3566                if is_day_index(&idx_name, bare) {
3567                    return;
3568                }
3569                let survives = file
3570                    .indexes
3571                    .iter()
3572                    .find(|i| i.name == idx_name)
3573                    .is_some_and(|i| {
3574                        i.columns
3575                            .iter()
3576                            .all(|c| declared.iter().any(|d| d.def.name == c))
3577                    });
3578                if survives && let Ok(sql) = row.get(1).as_text() {
3579                    foreign_indexes.push(sql.to_string());
3580                }
3581            },
3582        )?;
3583
3584        // Triggers on the table go with `DROP TABLE`; the application's come back verbatim
3585        // after the rename when every column they name survives (Day's generated ones are
3586        // reconciled afterwards anyway). Checked by a dry parse against the new table.
3587        let mut triggers: Vec<String> = Vec::new();
3588        self.conn().query(
3589            &format!(
3590                "SELECT sql FROM {master} WHERE type = 'trigger' AND tbl_name = ? \
3591                 AND sql IS NOT NULL ORDER BY rowid"
3592            ),
3593            &[Value::Text(bare.into())],
3594            &mut |row| {
3595                if let Ok(sql) = row.get(0).as_text() {
3596                    triggers.push(sql.to_string());
3597                }
3598            },
3599        )?;
3600
3601        let wrap =
3602            |e: DbError| DbError::new(e.kind, format!("rebuilding `{}`: {}", M::TABLE, e.message));
3603        self.conn()
3604            .execute(&format!("DROP TABLE IF EXISTS {tmp}"), &[])
3605            .map_err(wrap)?;
3606        self.create_table_named::<M>(tmp.clone()).map_err(wrap)?;
3607        let targets = column_list(&declared.iter().map(|d| d.def.name).collect::<Vec<_>>());
3608        let mut sources: Vec<String> = Vec::with_capacity(declared.len());
3609        for d in &declared {
3610            let c = &d.def;
3611            let default = Row::get(&defaults, d.index);
3612            let required = c.not_null || d.pk;
3613            let shared = file.columns.iter().find(|f| f.name == c.name);
3614            sources.push(match shared {
3615                Some(f) if !required || f.not_null => ident(c.name),
3616                Some(_) => format!(
3617                    "COALESCE({}, {})",
3618                    ident(c.name),
3619                    sql_literal(&default).map_err(wrap)?
3620                ),
3621                None => sql_literal(&default).map_err(wrap)?,
3622            });
3623        }
3624        self.conn()
3625            .execute(
3626                &format!(
3627                    "INSERT INTO {tmp} ({targets}) SELECT {} FROM {t}",
3628                    sources.join(", ")
3629                ),
3630                &[],
3631            )
3632            .map_err(wrap)?;
3633        self.conn()
3634            .execute(&format!("DROP TABLE {t}"), &[])
3635            .map_err(wrap)?;
3636        // Other tables' triggers and views may name this table (an adapter's capture trigger
3637        // on a child table reads the parent), and a rename checks every such reference
3638        // against a schema the table is momentarily absent from. The legacy rename leaves
3639        // those references as written, which is what a rebuild under the same name wants.
3640        self.conn()
3641            .execute_batch("PRAGMA legacy_alter_table = ON")
3642            .map_err(wrap)?;
3643        let renamed = self
3644            .conn()
3645            .execute(&format!("ALTER TABLE {tmp} RENAME TO {}", ident(bare)), &[]);
3646        self.conn()
3647            .execute_batch("PRAGMA legacy_alter_table = OFF")
3648            .map_err(wrap)?;
3649        renamed.map_err(wrap)?;
3650        for sql in foreign_indexes {
3651            self.conn().execute(&sql, &[]).map_err(wrap)?;
3652        }
3653        for sql in triggers {
3654            // A trigger naming a dropped column cannot come back; its owner recreates it.
3655            let _ = self.conn().execute(&sql, &[]);
3656        }
3657        Ok(())
3658    }
3659
3660    fn stored_fingerprint(&self, table: &str) -> Result<Option<String>, DbError> {
3661        let mut fp = None;
3662        self.conn().query(
3663            "SELECT fingerprint FROM _day_schema WHERE table_name = ?",
3664            &[Value::Text(table.into())],
3665            &mut |row| {
3666                if let Ok(t) = row.get(0).as_text() {
3667                    fp = Some(t.to_string());
3668                }
3669            },
3670        )?;
3671        Ok(fp)
3672    }
3673
3674    fn store_fingerprint(&self, table: &str, fp: &str) -> Result<(), DbError> {
3675        self.conn().execute(
3676            "INSERT INTO _day_schema (table_name, fingerprint, version) VALUES (?, ?, 0) \
3677             ON CONFLICT(table_name) DO UPDATE SET fingerprint = excluded.fingerprint",
3678            &[Value::Text(table.into()), Value::Text(fp.into())],
3679        )?;
3680        Ok(())
3681    }
3682
3683    fn install_sink(&self) {
3684        let inner = Rc::downgrade(&self.inner);
3685        let sink = day_model::install_change_sink(move |change| {
3686            if let Some(inner) = inner.upgrade() {
3687                // An external merge's changes are the database's own contents arriving:
3688                // queries go stale on them like any edit, but nothing goes back to the file.
3689                if change.author != Some(ModelContainer::EXTERNAL_AUTHOR) {
3690                    let tables = inner.tables.borrow();
3691                    inner
3692                        .dirty
3693                        .borrow_mut()
3694                        .note(change, |store| tables.contains_key(&store));
3695                }
3696                let container = ModelContainer { inner };
3697                container.mark_queries_stale(change);
3698                container.relations_on_change(change);
3699            }
3700        });
3701        self.inner.sink.set(Some(sink));
3702    }
3703
3704    fn install_autosave(&self) {
3705        // Weak: `on_turn_end` registrations live for the process, and a strong clone here
3706        // would keep the container (and its connection) alive forever.
3707        let inner = Rc::downgrade(&self.inner);
3708        day_reactive::on_turn_end(move || {
3709            let Some(inner) = inner.upgrade() else { return };
3710            let this = ModelContainer { inner };
3711            if this.inner.autosave.get() && !this.inner.dirty.borrow().is_empty() {
3712                // The error lands in the signal; a turn end has no caller to give a Result to.
3713                let _ = this.save();
3714            }
3715        });
3716    }
3717
3718    fn flush(&self, dirty: &DirtyState) -> Result<Vec<(String, Vec<Value>)>, DbError> {
3719        let capture = self.inner.participant.borrow().is_some();
3720        let (stmts, changes) = self.fold(dirty, capture)?;
3721        if stmts.is_empty() {
3722            return Ok(stmts);
3723        }
3724        let mut conn = self.conn();
3725        let outer = self.inner.worker_transaction.get();
3726        if !outer {
3727            conn.begin()?;
3728            if let Err(error) = self.participant_begin(conn.as_mut(), WriteOrigin::Local) {
3729                let _ = conn.rollback();
3730                return Err(error);
3731            }
3732        }
3733        // After begin (which clears the set) and before the statements: an outer worker
3734        // transaction accumulates every inner flush, and rolls the set back with the rest.
3735        self.record_changes(changes);
3736        for (sql, params) in &stmts {
3737            if let Err(e) = conn.execute(sql, params) {
3738                if !outer {
3739                    let _ = conn.rollback();
3740                    self.participant_rollback();
3741                }
3742                return Err(e);
3743            }
3744        }
3745        if !outer
3746            && let Err(error) = self
3747                .participant_commit(conn.as_mut(), WriteOrigin::Local)
3748                .and_then(|_| conn.commit())
3749        {
3750            let _ = conn.rollback();
3751            self.participant_rollback();
3752            return Err(error);
3753        }
3754        Ok(stmts)
3755    }
3756
3757    #[cfg(not(target_arch = "wasm32"))]
3758    fn worker_dispose_caches(&self) {
3759        for hooks in self.inner.tables.borrow().values() {
3760            (hooks.dispose_cache)();
3761        }
3762        // Reactive callbacks can retain a container until thread teardown. Release transaction
3763        // resources (including replication's writer lease) before acknowledging worker close.
3764        self.inner.participant.borrow_mut().take();
3765    }
3766
3767    #[cfg(not(target_arch = "wasm32"))]
3768    fn worker_write<R>(
3769        &self,
3770        write: impl FnOnce(&Self) -> Result<R, DbError>,
3771    ) -> Result<R, DbError> {
3772        self.worker_write_origin(WriteOrigin::Local, write)
3773    }
3774
3775    #[cfg(not(target_arch = "wasm32"))]
3776    fn worker_write_origin<R>(
3777        &self,
3778        origin: WriteOrigin,
3779        write: impl FnOnce(&Self) -> Result<R, DbError>,
3780    ) -> Result<R, DbError> {
3781        self.save()?;
3782        self.conn().begin()?;
3783        let admission = self.participant_begin(self.conn().as_mut(), origin);
3784        if let Err(error) = admission {
3785            self.conn().rollback().map_err(|rollback| {
3786                DbError::new(
3787                    DbErrorKind::Closed,
3788                    format!("transaction admission rollback failed: {rollback}"),
3789                )
3790            })?;
3791            return Err(error);
3792        }
3793        self.inner.worker_transaction.set(true);
3794        let result = day_reactive::batch(|| {
3795            let value = write(self)?;
3796            self.save()?;
3797            Ok(value)
3798        })
3799        .and_then(|value| {
3800            // Reactions may have made additional writes while the batch drained. Commit only
3801            // after those writes settle, never before turn-end autosave has run.
3802            self.save()?;
3803            self.participant_commit(self.conn().as_mut(), origin)?;
3804            self.conn().commit()?;
3805            Ok(value)
3806        });
3807        self.inner.worker_transaction.set(false);
3808        if result.is_err() {
3809            self.participant_rollback();
3810            self.conn().rollback().map_err(|error| {
3811                DbError::new(
3812                    DbErrorKind::Closed,
3813                    format!("transaction rollback failed: {error}"),
3814                )
3815            })?;
3816            self.worker_discard_changes()?;
3817        }
3818        if result.is_ok() {
3819            self.participant_refresh()?;
3820        }
3821        result
3822    }
3823
3824    #[cfg(not(target_arch = "wasm32"))]
3825    fn worker_read<R>(&self, read: impl FnOnce(&Self) -> Result<R, DbError>) -> Result<R, DbError> {
3826        self.save()?;
3827        self.conn().execute_batch("PRAGMA query_only = ON")?;
3828        self.conn().begin().map_err(|error| {
3829            DbError::new(
3830                DbErrorKind::Closed,
3831                format!("could not begin read snapshot: {error}"),
3832            )
3833        })?;
3834        let autosave = self.inner.autosave.replace(false);
3835        let mut result =
3836            day_model::with_author("worker-read", || day_reactive::batch(|| read(self)));
3837        let mutated = !self.inner.dirty.borrow().is_empty();
3838        self.conn().rollback().map_err(|error| {
3839            DbError::new(
3840                DbErrorKind::Closed,
3841                format!("could not end read snapshot: {error}"),
3842            )
3843        })?;
3844        self.conn()
3845            .execute_batch("PRAGMA query_only = OFF")
3846            .map_err(|error| {
3847                DbError::new(
3848                    DbErrorKind::Closed,
3849                    format!("could not restore write mode: {error}"),
3850                )
3851            })?;
3852        if mutated {
3853            self.worker_discard_changes()?;
3854            result = Err(DbError::driver(
3855                "a worker read attempted to mutate model state",
3856            ));
3857        }
3858        self.inner.autosave.set(autosave);
3859        result
3860    }
3861
3862    #[cfg(not(target_arch = "wasm32"))]
3863    fn worker_discard_changes(&self) -> Result<(), DbError> {
3864        let autosave = self.inner.autosave.replace(false);
3865        *self.inner.dirty.borrow_mut() = DirtyState::default();
3866        self.participant_rollback();
3867        let result = self.refresh_resident();
3868        self.invalidate_relation_memos();
3869        if result.is_ok() {
3870            self.requery_all();
3871        }
3872        self.inner.autosave.set(autosave);
3873        result.map(|_| ()).map_err(|error| {
3874            DbError::new(
3875                DbErrorKind::Closed,
3876                format!("transaction cache recovery failed: {error}"),
3877            )
3878        })
3879    }
3880
3881    /// The fold, materialized: the smallest statement list that expresses `dirty`, in
3882    /// first-touch order. Row values come from the caches now; the change log carried which
3883    /// rows and columns moved, never their contents. Reads only; [`ModelContainer::flush`]
3884    /// executes the list in one transaction.
3885    ///
3886    /// With `capture`, the second answer is the same work as a change set, one entry per row
3887    /// a statement writes (the participant's view of the flush); without it, empty.
3888    #[allow(clippy::type_complexity)]
3889    fn fold(
3890        &self,
3891        dirty: &DirtyState,
3892        capture: bool,
3893    ) -> Result<(Vec<(String, Vec<Value>)>, Vec<RowChange>), DbError> {
3894        let tables = self.inner.tables.borrow();
3895        let mut stmts: Vec<(String, Vec<Value>)> = Vec::new();
3896        let mut changes: Vec<RowChange> = Vec::new();
3897        let authors_of = |store_id: u64, key: u64| -> Vec<&'static str> {
3898            dirty
3899                .authors
3900                .get(&(store_id, key))
3901                .cloned()
3902                .unwrap_or_default()
3903        };
3904
3905        // Wholesale rewrites first: upsert every resident row. (The cache is a working set;
3906        // rows outside it were never part of the rewrite, and deleting "the rest" would
3907        // delete data the rewrite never saw.)
3908        for store_id in &dirty.full {
3909            let Some(hooks) = tables.get(store_id) else {
3910                continue;
3911            };
3912            for (key, row) in (hooks.all_rows)() {
3913                stmts.push(upsert_stmt(hooks, &row));
3914                if capture {
3915                    let mut authors = dirty
3916                        .store_authors
3917                        .get(store_id)
3918                        .cloned()
3919                        .unwrap_or_default();
3920                    for tag in authors_of(*store_id, key) {
3921                        add_author(&mut authors, Some(tag));
3922                    }
3923                    changes.push(RowChange {
3924                        table: hooks.table,
3925                        key: (hooks.key_where)(key).1,
3926                        kind: RowChangeKind::Rewritten,
3927                        authors,
3928                    });
3929                }
3930            }
3931        }
3932
3933        // Per-row work, into batches that can merge. Deletes of one table merge into one
3934        // `IN`; updates merge when they write the same columns to the same values, which is
3935        // what a multi-selection edit produces ("set fill on twelve shapes").
3936        //
3937        // Deletes are held apart and emitted last. Dirty order interleaves rows by when each
3938        // first changed, which can put a parent row's delete between its children's detach
3939        // updates (the first detach dirties the parent through relation upkeep), and a
3940        // relation column's `ON DELETE CASCADE` fires per statement, `DEFERRABLE` or not, so
3941        // the mid-batch delete would take every still-attached child with it (found by Day
3942        // Sketch's ungroup: two members detached, one row left). With inserts and updates
3943        // first, a row still referencing a deleted parent at delete time is one the batch
3944        // never detached: an orphan the cascade rule is meant to take.
3945        let mut batches: Vec<Batch> = Vec::new();
3946        let mut deletes: Vec<Batch> = Vec::new();
3947        // (store, statement shape, a fingerprint of the `SET` values) → the batch it joins.
3948        let mut open: HashMap<(u64, String, u64), usize> = HashMap::new();
3949        let mut open_deletes: HashMap<(u64, String, u64), usize> = HashMap::new();
3950        // store → the insert batch collecting its new rows.
3951        let mut open_inserts: HashMap<u64, usize> = HashMap::new();
3952
3953        for id in &dirty.order {
3954            let Some(state) = dirty.rows.get(id) else {
3955                continue;
3956            };
3957            let (store_id, key) = *id;
3958            if dirty.full.contains(&store_id) {
3959                continue; // the resync above already covered it
3960            }
3961            let Some(hooks) = tables.get(&store_id) else {
3962                continue;
3963            };
3964            // A join row is addressed by a pair of columns, which no single-column `IN` can
3965            // express, so those keep one statement each.
3966            let batchable = hooks.key_cols.len() == 1;
3967            let mut capture_as = |kind: RowChangeKind| {
3968                if capture {
3969                    changes.push(RowChange {
3970                        table: hooks.table,
3971                        key: (hooks.key_where)(key).1,
3972                        kind,
3973                        authors: authors_of(store_id, key),
3974                    });
3975                }
3976            };
3977            match state {
3978                DirtyRow::Delete => {
3979                    capture_as(RowChangeKind::Deleted);
3980                    if !batchable {
3981                        let (clause, params) = (hooks.key_where)(key);
3982                        deletes.push(Batch::Single(
3983                            format!("DELETE FROM {} WHERE {clause}", hooks.name.sql()),
3984                            params,
3985                        ));
3986                        continue;
3987                    }
3988                    join_batch(&mut deletes, &mut open_deletes, store_id, None, key);
3989                }
3990                DirtyRow::Insert => {
3991                    if let Some(row) = (hooks.row_for)(key) {
3992                        capture_as(RowChangeKind::Inserted);
3993                        match open_inserts.get(&store_id) {
3994                            Some(&i) => {
3995                                if let Batch::Inserts { rows, .. } = &mut batches[i] {
3996                                    rows.push(row);
3997                                }
3998                            }
3999                            None => {
4000                                open_inserts.insert(store_id, batches.len());
4001                                batches.push(Batch::Inserts {
4002                                    store: store_id,
4003                                    rows: vec![row],
4004                                });
4005                            }
4006                        }
4007                    }
4008                }
4009                DirtyRow::Update(cols) => {
4010                    let Some(row) = (hooks.row_for)(key) else {
4011                        continue; // deleted since; its Delete entry handles it
4012                    };
4013                    if cols.is_empty() {
4014                        // A row-level replacement named no columns; write them all.
4015                        let (sql, params) = upsert_stmt(hooks, &row);
4016                        batches.push(Batch::Single(sql, params));
4017                        capture_as(RowChangeKind::Rewritten);
4018                        continue;
4019                    }
4020                    let mut sets: Vec<String> = Vec::with_capacity(cols.len());
4021                    let mut set_params: Vec<Value> = Vec::with_capacity(cols.len());
4022                    for c in cols {
4023                        let Some(i) = hooks.fields.iter().position(|n| n == c) else {
4024                            continue; // a transient field's label, never a column
4025                        };
4026                        let value = row.get(i);
4027                        if hooks.lazy.get(i).copied().unwrap_or(false) && value == Value::Null {
4028                            continue; // a stored blob the row did not rewrite: leave the bytes
4029                        }
4030                        sets.push(format!("{} = ?", ident(&hooks.columns[i])));
4031                        set_params.push(value);
4032                    }
4033                    if set_params.is_empty() {
4034                        continue; // only transient fields changed
4035                    }
4036                    if capture {
4037                        let written: Vec<&'static str> = cols
4038                            .iter()
4039                            .filter_map(|c| hooks.fields.iter().position(|n| n == c))
4040                            .map(|i| hooks.column_names[i])
4041                            .collect();
4042                        capture_as(RowChangeKind::Updated(written));
4043                    }
4044                    let clause = sets.join(", ");
4045                    if !batchable {
4046                        let (where_clause, mut where_params) = (hooks.key_where)(key);
4047                        let mut params = set_params;
4048                        params.append(&mut where_params);
4049                        batches.push(Batch::Single(
4050                            format!(
4051                                "UPDATE {} SET {clause} WHERE {where_clause}",
4052                                hooks.name.sql()
4053                            ),
4054                            params,
4055                        ));
4056                        continue;
4057                    }
4058                    join_batch(
4059                        &mut batches,
4060                        &mut open,
4061                        store_id,
4062                        Some((clause, set_params)),
4063                        key,
4064                    );
4065                }
4066            }
4067        }
4068
4069        for batch in batches.into_iter().chain(deletes) {
4070            match batch {
4071                Batch::Single(sql, params) => stmts.push((sql, params)),
4072                Batch::Inserts { store, rows } => {
4073                    let Some(hooks) = tables.get(&store) else {
4074                        continue;
4075                    };
4076                    insert_stmts(hooks, rows, &mut stmts);
4077                }
4078                Batch::Keyed { store, set, keys } => {
4079                    let Some(hooks) = tables.get(&store) else {
4080                        continue;
4081                    };
4082                    materialize(hooks, set, &keys, &mut stmts);
4083                }
4084            }
4085        }
4086        Ok((stmts, changes))
4087    }
4088
4089    // --- maintenance (docs/persistence.md) ---------------------------------------------------
4090
4091    /// `VACUUM INTO`: a transactionally consistent, already-compacted snapshot, taken while
4092    /// the app keeps writing. Restore is an open, not a verb.
4093    pub fn backup_to(&self, path: &Path) -> Result<(), DbError> {
4094        self.save()?;
4095        self.conn().execute(
4096            "VACUUM INTO ?",
4097            &[Value::Text(path.to_string_lossy().into_owned())],
4098        )?;
4099        Ok(())
4100    }
4101
4102    /// `PRAGMA integrity_check` and `PRAGMA foreign_key_check`, parsed: an empty list means
4103    /// the database is sound. A foreign-key violation reads
4104    /// `foreign key: <child> row <rowid> references missing <parent>`; the structured form is
4105    /// [`ModelContainer::foreign_key_check`].
4106    pub fn integrity_check(&self) -> Result<Vec<String>, DbError> {
4107        let mut findings = Vec::new();
4108        self.conn()
4109            .query("PRAGMA integrity_check", &[], &mut |row| {
4110                if let Ok(t) = row.get(0).as_text()
4111                    && t != "ok"
4112                {
4113                    findings.push(t.to_string());
4114                }
4115            })?;
4116        for v in self.foreign_key_check()? {
4117            findings.push(v.to_string());
4118        }
4119        Ok(findings)
4120    }
4121
4122    /// `PRAGMA foreign_key_check`, parsed: every row whose foreign key names a parent that
4123    /// does not exist. Empty when every reference resolves. Runs on the whole file, which is
4124    /// what a migration's post-check and a settings-page validation both want.
4125    pub fn foreign_key_check(&self) -> Result<Vec<ForeignKeyViolation>, DbError> {
4126        Self::foreign_key_check_on(self.conn().as_mut())
4127    }
4128
4129    fn foreign_key_check_on(
4130        conn: &mut dyn SqliteConnection,
4131    ) -> Result<Vec<ForeignKeyViolation>, DbError> {
4132        let mut violations = Vec::new();
4133        conn.query("PRAGMA foreign_key_check", &[], &mut |row| {
4134            violations.push(ForeignKeyViolation {
4135                table: row.get(0).as_text().unwrap_or("").to_string(),
4136                rowid: row.get(1).as_int().ok(),
4137                parent: row.get(2).as_text().unwrap_or("").to_string(),
4138                constraint: row.get(3).as_int().unwrap_or(0),
4139            });
4140        })?;
4141        Ok(violations)
4142    }
4143
4144    /// Fold the WAL into the main file (`PRAGMA wal_checkpoint(TRUNCATE)`), before the OS
4145    /// copies it whole (device backup). The engine's own answer comes back: whether a reader
4146    /// kept the checkpoint from completing, and how much of the log it folded.
4147    pub fn checkpoint(&self) -> Result<Checkpoint, DbError> {
4148        let mut result = Checkpoint::default();
4149        self.conn()
4150            .query("PRAGMA wal_checkpoint(TRUNCATE)", &[], &mut |row| {
4151                result = Checkpoint {
4152                    busy: row.get(0).as_int().unwrap_or(0) != 0,
4153                    log_frames: row.get(1).as_int().unwrap_or(-1),
4154                    checkpointed_frames: row.get(2).as_int().unwrap_or(-1),
4155                };
4156            })?;
4157        Ok(result)
4158    }
4159
4160    pub fn vacuum(&self) -> Result<(), DbError> {
4161        self.save()?;
4162        self.conn().execute("VACUUM", &[]).map(|_| ())
4163    }
4164
4165    /// Re-encrypt in place under a new key (`PRAGMA rekey`; feature `cipher`).
4166    #[cfg(feature = "cipher")]
4167    pub fn rekey(&self, new: Secret) -> Result<(), DbError> {
4168        self.save()?;
4169        let quoted = new.reveal().replace('\'', "''");
4170        // The PRAGMA answers with a status row; consume it as a query.
4171        self.conn()
4172            .query(&format!("PRAGMA rekey = '{quoted}'"), &[], &mut |_| {})
4173    }
4174
4175    /// Write an encrypted copy at `path` through SQLCipher's conversion path (`ATTACH` +
4176    /// `sqlcipher_export`); plaintext↔encrypted cannot happen in place.
4177    #[cfg(feature = "cipher")]
4178    pub fn encrypt_to(&self, path: &Path, key: Secret) -> Result<(), DbError> {
4179        self.export_to(path, Some(key))
4180    }
4181
4182    /// Write a plaintext copy at `path`, same mechanism with an empty key.
4183    #[cfg(feature = "cipher")]
4184    pub fn decrypt_to(&self, path: &Path) -> Result<(), DbError> {
4185        self.export_to(path, None)
4186    }
4187
4188    #[cfg(feature = "cipher")]
4189    fn export_to(&self, path: &Path, key: Option<Secret>) -> Result<(), DbError> {
4190        self.save()?;
4191        let quoted_path = path.to_string_lossy().replace('\'', "''");
4192        let quoted_key = key
4193            .as_ref()
4194            .map(|k| k.reveal().replace('\'', "''"))
4195            .unwrap_or_default();
4196        let mut conn = self.conn();
4197        conn.execute(
4198            &format!("ATTACH DATABASE '{quoted_path}' AS day_export KEY '{quoted_key}'"),
4199            &[],
4200        )?;
4201        conn.query("SELECT sqlcipher_export('day_export')", &[], &mut |_| {})
4202            .and_then(|_| conn.execute("DETACH DATABASE day_export", &[]).map(|_| ()))
4203    }
4204
4205    /// Total size in bytes (page_count × page_size).
4206    pub fn size_bytes(&self) -> Result<u64, DbError> {
4207        let mut pages = 0i64;
4208        let mut page_size = 0i64;
4209        self.conn().query("PRAGMA page_count", &[], &mut |row| {
4210            pages = row.get(0).as_int().unwrap_or(0);
4211        })?;
4212        self.conn().query("PRAGMA page_size", &[], &mut |row| {
4213            page_size = row.get(0).as_int().unwrap_or(0);
4214        })?;
4215        Ok((pages * page_size).max(0) as u64)
4216    }
4217}
4218
4219/// The multi-key `WHERE` builder for a hooks entry: `key IN (…)` for single-column keys, an OR
4220/// list of pair clauses for join tables.
4221/// `a, b, c` as a quoted SELECT list or insert column list.
4222pub(crate) fn column_list<S: AsRef<str>>(columns: &[S]) -> String {
4223    columns
4224        .iter()
4225        .map(|c| ident(c.as_ref()))
4226        .collect::<Vec<_>>()
4227        .join(", ")
4228}
4229
4230/// `prefix.a, prefix.b`: the same list through a table alias or a trigger's `new`/`old`.
4231pub(crate) fn prefixed_list<S: AsRef<str>>(prefix: &str, columns: &[S]) -> String {
4232    columns
4233        .iter()
4234        .map(|c| format!("{prefix}.{}", ident(c.as_ref())))
4235        .collect::<Vec<_>>()
4236        .join(", ")
4237}
4238
4239/// The two halves of an FTS update trigger's gate: the `UPDATE OF` column list (the key and
4240/// every indexed column, once each) and the `WHEN` expression that is true only if one of
4241/// them actually changed (`IS NOT`, so a NULL on either side compares like any value).
4242fn fts_update_guard(key: &str, fts_columns: &[&str]) -> (String, String) {
4243    let mut cols: Vec<&str> = vec![key];
4244    cols.extend(fts_columns.iter().copied().filter(|c| *c != key));
4245    let update_of = column_list(&cols);
4246    let changed = cols
4247        .iter()
4248        .map(|c| {
4249            let c = ident(c);
4250            format!("new.{c} IS NOT old.{c}")
4251        })
4252        .collect::<Vec<_>>()
4253        .join(" OR ");
4254    (update_of, changed)
4255}
4256
4257// ---------------------------------------------------------------------------
4258// Schema comparison: the declaration against the file
4259// ---------------------------------------------------------------------------
4260
4261/// One column as the model declares it, with the relation-contributed foreign key resolved.
4262struct DeclaredColumn {
4263    def: ColumnDef,
4264    /// Position in `Model::COLUMNS`, which is also the position in `Model::default_row()`.
4265    index: usize,
4266    pk: bool,
4267    fk: Option<DeclaredFk>,
4268}
4269
4270/// A declared relation's foreign key on a child column.
4271struct DeclaredFk {
4272    parent_sql: String,
4273    parent_bare: &'static str,
4274    parent_key: &'static str,
4275    rule: DeleteRule,
4276}
4277
4278impl DeclaredFk {
4279    /// The column constraint, deferred so within-transaction statement order (a cascade's
4280    /// children, an undo's re-inserts) never trips it.
4281    fn clause(&self) -> String {
4282        format!(
4283            " REFERENCES {}({}) ON DELETE {} DEFERRABLE INITIALLY DEFERRED",
4284            self.parent_sql,
4285            ident(self.parent_key),
4286            self.rule.sql()
4287        )
4288    }
4289}
4290
4291/// An index the container owns, as it is declared.
4292struct DeclaredIndex {
4293    name: String,
4294    columns: Vec<String>,
4295    unique: bool,
4296}
4297
4298/// A column as `PRAGMA table_info` and `PRAGMA foreign_key_list` report it.
4299struct FileColumn {
4300    name: String,
4301    /// Upper-cased declared type (`INTEGER`, `TEXT`, …).
4302    decl_type: String,
4303    not_null: bool,
4304    pk: bool,
4305    fk: Option<FileFk>,
4306}
4307
4308struct FileFk {
4309    parent: String,
4310    parent_key: String,
4311    on_delete: String,
4312}
4313
4314/// An index as `PRAGMA index_list` and `index_info` report it. `origin` is `c` for a
4315/// `CREATE INDEX`, `u` for an inline `UNIQUE`, `pk` for the primary key's.
4316struct FileIndex {
4317    name: String,
4318    unique: bool,
4319    origin: String,
4320    columns: Vec<String>,
4321}
4322
4323struct FileSchema {
4324    columns: Vec<FileColumn>,
4325    indexes: Vec<FileIndex>,
4326}
4327
4328/// What `lightweight_migrate` does in place: positions in `COLUMNS` to add, file columns to
4329/// drop, Day-owned index names to drop, and declared-unique columns that need a unique index.
4330#[derive(Default, Clone)]
4331struct LightweightPlan {
4332    add: Vec<usize>,
4333    drop: Vec<String>,
4334    drop_indexes: Vec<String>,
4335    unique_indexes: Vec<&'static str>,
4336}
4337
4338/// The comparison's verdict for an existing table.
4339enum SchemaDelta {
4340    Lightweight(LightweightPlan),
4341    Rebuild,
4342}
4343
4344/// Whether an index name is one the container writes for `table` (`day_idx_`, `day_uidx_`).
4345fn is_day_index(name: &str, table: &str) -> bool {
4346    name.starts_with(&format!("day_idx_{table}_"))
4347        || name.starts_with(&format!("day_uidx_{table}_"))
4348}
4349
4350/// `PRAGMA [schema.]name("arg")`.
4351fn pragma_sql(schema: Option<&str>, name: &str, arg: &str) -> String {
4352    match schema {
4353        Some(s) => format!("PRAGMA {}.{name}({})", ident(s), ident(arg)),
4354        None => format!("PRAGMA {name}({})", ident(arg)),
4355    }
4356}
4357
4358/// A [`Value`] as an SQL literal, for the places a bound parameter cannot go (a column's
4359/// `DEFAULT`, a copy's `SELECT` list): text single-quoted with `'` doubled, a blob as
4360/// `X'…'`, numbers as themselves. A non-finite real has no literal and is refused.
4361fn sql_literal(v: &Value) -> Result<String, DbError> {
4362    Ok(match v {
4363        Value::Null => "NULL".into(),
4364        Value::Int(i) => i.to_string(),
4365        Value::Real(r) if r.is_finite() => format!("{r:?}"),
4366        Value::Real(r) => {
4367            return Err(DbError::new(
4368                DbErrorKind::Schema,
4369                format!("{r} has no SQL literal to use as a column default"),
4370            ));
4371        }
4372        Value::Text(t) => format!("'{}'", t.replace('\'', "''")),
4373        Value::Blob(b) => {
4374            let mut s = String::with_capacity(b.len() * 2 + 3);
4375            s.push_str("X'");
4376            for byte in b {
4377                s.push_str(&format!("{byte:02x}"));
4378            }
4379            s.push('\'');
4380            s
4381        }
4382    })
4383}
4384
4385fn keys_where_of(hooks: &TableHooks) -> KeysWhere {
4386    if hooks.key_cols.len() == 1 {
4387        let col = ident(&hooks.key_cols[0]);
4388        Rc::new(move |keys: &[u64]| {
4389            let marks = vec!["?"; keys.len()].join(", ");
4390            (
4391                format!("{col} IN ({marks})"),
4392                keys.iter().map(|k| key_param(*k)).collect(),
4393            )
4394        })
4395    } else {
4396        let key_where = hooks.key_where.clone();
4397        Rc::new(move |keys: &[u64]| {
4398            let mut clauses = Vec::with_capacity(keys.len());
4399            let mut params = Vec::with_capacity(keys.len() * 2);
4400            for k in keys {
4401                let (c, mut p) = key_where(*k);
4402                clauses.push(format!("({c})"));
4403                params.append(&mut p);
4404            }
4405            (clauses.join(" OR "), params)
4406        })
4407    }
4408}
4409
4410/// One statement the fold will write, before the mergeable ones have merged.
4411enum Batch {
4412    /// Stands alone: a row-level rewrite (its values are the row's own), or a row addressed
4413    /// by a composite key, which no single-column `IN` can express.
4414    Single(String, Vec<Value>),
4415    /// One table's inserted rows: a multi-row upsert, chunked by the parameter ceiling.
4416    Inserts { store: u64, rows: Vec<Vec<Value>> },
4417    /// Same table, same operation, same values: one statement per chunk of keys.
4418    Keyed {
4419        store: u64,
4420        /// The `SET` clause and its parameters for an update; `None` for a delete.
4421        set: Option<(String, Vec<Value>)>,
4422        keys: Vec<u64>,
4423    },
4424}
4425
4426/// SQLite's conservative bound-parameter ceiling. Modern builds allow far more, but a
4427/// `system` engine may be an older one, and chunking costs nothing to write.
4428const MAX_BOUND_PARAMS: usize = 900;
4429
4430/// Add `key` to the batch sharing this table, clause and values, or open a new one.
4431///
4432/// The slot key separates a delete from an update (their clauses differ), and separates
4433/// updates writing different values, which must stay different statements. Grouping is by
4434/// hash so a large flush stays linear; the values are compared before merging, so a hash
4435/// collision costs a second statement rather than a wrong one.
4436fn join_batch(
4437    batches: &mut Vec<Batch>,
4438    open: &mut HashMap<(u64, String, u64), usize>,
4439    store: u64,
4440    set: Option<(String, Vec<Value>)>,
4441    key: u64,
4442) {
4443    let clause = set.as_ref().map(|(c, _)| c.clone()).unwrap_or_default();
4444    let print = set.as_ref().map(|(_, p)| fingerprint(p)).unwrap_or(0);
4445    let slot = (store, clause, print);
4446    if let Some(&i) = open.get(&slot)
4447        && let Batch::Keyed {
4448            set: existing,
4449            keys,
4450            ..
4451        } = &mut batches[i]
4452        && existing.as_ref().map(|(_, p)| p.as_slice()) == set.as_ref().map(|(_, p)| p.as_slice())
4453    {
4454        keys.push(key);
4455        return;
4456    }
4457    open.insert(slot, batches.len());
4458    batches.push(Batch::Keyed {
4459        store,
4460        set,
4461        keys: vec![key],
4462    });
4463}
4464
4465/// A cheap order-sensitive hash of bound values, for grouping identical updates. Equality is
4466/// still checked before two rows share a statement; this only decides who to compare with.
4467fn fingerprint(values: &[Value]) -> u64 {
4468    let mut h: u64 = 0xcbf2_9ce4_8422_2325;
4469    let mut eat = |bytes: &[u8]| {
4470        for b in bytes {
4471            h ^= *b as u64;
4472            h = h.wrapping_mul(0x1000_0000_01b3);
4473        }
4474    };
4475    for v in values {
4476        match v {
4477            Value::Null => eat(&[0]),
4478            Value::Int(i) => {
4479                eat(&[1]);
4480                eat(&i.to_le_bytes());
4481            }
4482            // Bit pattern, not numeric value: two values that hash apart are only compared
4483            // separately, never merged wrongly.
4484            Value::Real(r) => {
4485                eat(&[2]);
4486                eat(&r.to_bits().to_le_bytes());
4487            }
4488            Value::Text(t) => {
4489                eat(&[3]);
4490                eat(t.as_bytes());
4491            }
4492            Value::Blob(b) => {
4493                eat(&[4]);
4494                eat(b);
4495            }
4496        }
4497    }
4498    h
4499}
4500
4501/// Write a batch out: the familiar `= ?` form for one key, chunked `IN` statements for more.
4502fn materialize(
4503    hooks: &TableHooks,
4504    set: Option<(String, Vec<Value>)>,
4505    keys: &[u64],
4506    out: &mut Vec<(String, Vec<Value>)>,
4507) {
4508    // One key keeps the `= ?` form: it is the common case by far, it reads plainly in a
4509    // trace, and it is one more statement shape the cache can hold.
4510    let table = hooks.name.sql();
4511    if keys.len() == 1 {
4512        let (where_clause, where_params) = (hooks.key_where)(keys[0]);
4513        match set {
4514            Some((clause, mut params)) => {
4515                params.extend(where_params);
4516                out.push((
4517                    format!("UPDATE {table} SET {clause} WHERE {where_clause}"),
4518                    params,
4519                ));
4520            }
4521            None => out.push((
4522                format!("DELETE FROM {table} WHERE {where_clause}"),
4523                where_params,
4524            )),
4525        }
4526        return;
4527    }
4528
4529    let key_col = ident(&hooks.key_cols[0]);
4530    let set_len = set.as_ref().map(|(_, p)| p.len()).unwrap_or(0);
4531    let cap = MAX_BOUND_PARAMS.saturating_sub(set_len).max(1);
4532    for chunk in keys.chunks(cap) {
4533        let mut params: Vec<Value> = Vec::with_capacity(set_len + chunk.len());
4534        if let Some((_, set_params)) = &set {
4535            params.extend(set_params.iter().cloned());
4536        }
4537        params.extend(chunk.iter().map(|k| key_param(*k)));
4538        let marks = vec!["?"; chunk.len()].join(", ");
4539        let sql = match &set {
4540            Some((clause, _)) => {
4541                format!("UPDATE {table} SET {clause} WHERE {key_col} IN ({marks})")
4542            }
4543            None => format!("DELETE FROM {table} WHERE {key_col} IN ({marks})"),
4544        };
4545        out.push((sql, params));
4546    }
4547}
4548
4549/// The row select list: every column, with a lazy one named as a literal `NULL` so the
4550/// row's shape stays the same while the bytes stay in the file.
4551fn select_list(hooks: &TableHooks) -> String {
4552    hooks
4553        .columns
4554        .iter()
4555        .enumerate()
4556        .map(|(i, c)| {
4557            if hooks.lazy.get(i).copied().unwrap_or(false) {
4558                "NULL".to_string()
4559            } else {
4560                ident(c)
4561            }
4562        })
4563        .collect::<Vec<_>>()
4564        .join(", ")
4565}
4566
4567/// One table's inserted rows as multi-row upserts: as many rows per statement as the
4568/// parameter ceiling allows, so a thousand new rows are a few statements rather than a
4569/// thousand.
4570fn insert_stmts(hooks: &TableHooks, rows: Vec<Vec<Value>>, out: &mut Vec<(String, Vec<Value>)>) {
4571    let per_row = hooks.columns.len().max(1);
4572    let per_stmt = (MAX_BOUND_PARAMS / per_row).max(1);
4573    for chunk in rows.chunks(per_stmt) {
4574        let sql = upsert_sql(hooks, chunk.len());
4575        let params: Vec<Value> = chunk.iter().flatten().cloned().collect();
4576        out.push((sql, params));
4577    }
4578}
4579
4580fn upsert_stmt(hooks: &TableHooks, row: &[Value]) -> (String, Vec<Value>) {
4581    (upsert_sql(hooks, 1), row.to_vec())
4582}
4583
4584/// `INSERT … VALUES (…), (…) ON CONFLICT(key) DO UPDATE SET …` for `rows` rows.
4585fn upsert_sql(hooks: &TableHooks, rows: usize) -> String {
4586    let cols = column_list(&hooks.columns);
4587    let one = format!("({})", vec!["?"; hooks.columns.len()].join(", "));
4588    let marks = vec![one.as_str(); rows.max(1)].join(", ");
4589    // A true upsert, not `INSERT OR REPLACE`: the conflict path fires `UPDATE` triggers, which
4590    // is what keeps the generated FTS/R*Tree shadows in sync (`OR REPLACE`'s implicit delete
4591    // skips `AFTER DELETE` triggers unless recursive_triggers is on). A lazy column keeps its
4592    // stored bytes when the row arrives without new ones (`NULL`).
4593    let sets = hooks
4594        .columns
4595        .iter()
4596        .enumerate()
4597        .filter(|(_, c)| !hooks.key_cols.contains(c))
4598        .map(|(i, c)| {
4599            if hooks.lazy.get(i).copied().unwrap_or(false) {
4600                format!("{0} = COALESCE(excluded.{0}, {0})", ident(c))
4601            } else {
4602                format!("{0} = excluded.{0}", ident(c))
4603            }
4604        })
4605        .collect::<Vec<_>>()
4606        .join(", ");
4607    let conflict = if sets.is_empty() {
4608        "DO NOTHING".to_string()
4609    } else {
4610        format!("DO UPDATE SET {sets}")
4611    };
4612    format!(
4613        "INSERT INTO {} ({cols}) VALUES {marks} ON CONFLICT({}) {conflict}",
4614        hooks.name.sql(),
4615        column_list(&hooks.key_cols)
4616    )
4617}
4618
4619impl Drop for ContainerInner {
4620    fn drop(&mut self) {
4621        if let Some(sink) = self.sink.take() {
4622            day_model::remove_change_sink(sink);
4623        }
4624    }
4625}
4626
4627// ---------------------------------------------------------------------------
4628// Live queries (docs/persistence.md; queries.rs holds the compiler and the diff)
4629// ---------------------------------------------------------------------------
4630
4631/// What a query's consumers have not yet seen. `Deltas` can animate a list row by row;
4632/// `Reload` means the whole set moved (a fetch swap, a tangled requery) and a reload is
4633/// the accurate answer.
4634#[derive(Clone, Debug, PartialEq)]
4635pub enum QueryEvents {
4636    None,
4637    Deltas(Vec<Delta>),
4638    Reload,
4639}
4640
4641impl QueryEvents {
4642    fn push(&mut self, deltas: &[Delta]) {
4643        match self {
4644            QueryEvents::None => *self = QueryEvents::Deltas(deltas.to_vec()),
4645            QueryEvents::Deltas(d) => d.extend_from_slice(deltas),
4646            QueryEvents::Reload => {}
4647        }
4648    }
4649    fn reload(&mut self) {
4650        *self = QueryEvents::Reload;
4651    }
4652}
4653
4654/// What one relation crossing subscribes a query to, precomputed at install (and at every
4655/// fetch swap) so the change sink's staleness check is a few comparisons.
4656struct RelWatch {
4657    /// The store on the far side of the crossing (the related table's cache).
4658    store: u64,
4659    /// The join membership store, when the crossing is a many-to-many; every link, unlink
4660    /// and reposition there is a membership change.
4661    join_store: Option<u64>,
4662    /// Field names on the far store whose write is a membership change (the foreign key, the
4663    /// order field) even though no predicate reads them.
4664    fields: Vec<&'static str>,
4665    /// Column names of the far table the inner predicate reads.
4666    columns: Vec<&'static str>,
4667}
4668
4669struct QueryState {
4670    store_id: u64,
4671    table: &'static str,
4672    /// The relation subscriptions, recomputed when the fetch is swapped.
4673    watches: RefCell<Vec<RelWatch>>,
4674    /// Extra local columns whose write is a membership change (a `One` column crossed by the
4675    /// query's own table).
4676    local_extra: RefCell<Vec<&'static str>>,
4677    set: RefCell<ResultSet>,
4678    /// Bumped whenever the result set changes; `ids()`/`count()` track it.
4679    version: day_reactive::Signal<u64>,
4680    pending: RefCell<QueryEvents>,
4681    /// A dependency-touching change arrived; the answer re-derives after the flush.
4682    needs_sql: Cell<bool>,
4683    // Reading the last committed result must not consume the post-commit invalidation.
4684    pending_commit: Cell<bool>,
4685    error: day_reactive::Signal<Option<DbError>>,
4686    /// `query_raw` only: the statement and the tables whose flush re-runs it.
4687    raw: Option<RawQuery>,
4688    /// A count-shaped query: `count` is the answer, the id set stays empty, and requeries
4689    /// run `SELECT COUNT(*)`, the badge query, O(1) memory at any result size.
4690    count_only: bool,
4691    count: Cell<usize>,
4692}
4693
4694struct RawQuery {
4695    sql: String,
4696    params: Vec<Value>,
4697    tables: Vec<String>,
4698}
4699
4700/// A live, typed result set over one model's table: ids only, answered by the engine and
4701/// kept current by dependency-gated requeries. Rows stay lazy: fault the ones you show
4702/// ([`Query::materialize`], or a list source doing it for you). Clone shares the same set.
4703pub struct Query<M: Model> {
4704    state: Rc<QueryState>,
4705    container: ModelContainer,
4706    _p: std::marker::PhantomData<fn() -> M>,
4707}
4708
4709impl<M: Model> Clone for Query<M> {
4710    fn clone(&self) -> Self {
4711        Query {
4712            state: self.state.clone(),
4713            container: self.container.clone(),
4714            _p: std::marker::PhantomData,
4715        }
4716    }
4717}
4718
4719impl<M: Model> Query<M> {
4720    /// This query's last read failure. A failed read preserves its previous result set.
4721    pub fn error(&self) -> day_reactive::Signal<Option<DbError>> {
4722        self.state.error
4723    }
4724
4725    /// Explicitly retry a query after a transient read failure (also useful after external SQL).
4726    pub fn refresh(&self) {
4727        self.state.needs_sql.set(true);
4728        self.refresh_if_stale();
4729    }
4730
4731    /// Checked form of `ids`, for imports and commands that must not mistake failure for absence.
4732    pub fn try_ids(&self) -> Result<Vec<ModelId<M>>, DbError> {
4733        let ids = self.ids();
4734        match self.state.error.get() {
4735            Some(e) => Err(e),
4736            None => Ok(ids),
4737        }
4738    }
4739
4740    /// A checked snapshot for non-UI work, fetched in batches. UI lists should use the query
4741    /// itself as their row source so they only materialize the visible working set.
4742    pub fn try_collect(&self) -> Result<Vec<M>, DbError> {
4743        let ids = self.try_ids()?;
4744        let mut rows = Vec::with_capacity(ids.len());
4745        for chunk in ids.chunks(64) {
4746            self.container
4747                .ensure_resident::<M>(&chunk.iter().map(|id| id.handle()).collect::<Vec<_>>())?;
4748            for id in chunk {
4749                if let Some(row) = self.container.try_get::<M>(*id)?
4750                    && let Some(value) = row.with_value_untracked(|v| v.cloned())
4751                {
4752                    rows.push(value);
4753                }
4754            }
4755        }
4756        Ok(rows)
4757    }
4758
4759    /// The result ids, typed and in query order, as a tracked read: the caller re-runs when
4760    /// the set changes, and only then.
4761    pub fn ids(&self) -> Vec<ModelId<M>> {
4762        self.refresh_if_stale();
4763        let _ = self.state.version.get();
4764        self.state
4765            .set
4766            .borrow()
4767            .ids()
4768            .iter()
4769            .map(|h| ModelId::from_handle(*h))
4770            .collect()
4771    }
4772
4773    /// The result count, tracked like [`Query::ids`].
4774    pub fn count(&self) -> usize {
4775        self.refresh_if_stale();
4776        let _ = self.state.version.get();
4777        self.state.set.borrow().ids().len()
4778    }
4779
4780    /// The first result, tracked.
4781    pub fn first(&self) -> Option<ModelId<M>> {
4782        self.refresh_if_stale();
4783        let _ = self.state.version.get();
4784        self.state
4785            .set
4786            .borrow()
4787            .ids()
4788            .first()
4789            .map(|h| ModelId::from_handle(*h))
4790    }
4791
4792    /// Tracked membership test.
4793    pub fn contains(&self, id: impl Into<ModelId<M>>) -> bool {
4794        self.refresh_if_stale();
4795        let _ = self.state.version.get();
4796        self.state.set.borrow().ids().contains(&id.into().handle())
4797    }
4798
4799    /// Untracked snapshot: reactively silent, but still current (pending staleness settles
4800    /// first, like every other read).
4801    pub fn ids_untracked(&self) -> Vec<ModelId<M>> {
4802        self.refresh_if_stale();
4803        self.state
4804            .set
4805            .borrow()
4806            .ids()
4807            .iter()
4808            .map(|h| ModelId::from_handle(*h))
4809            .collect()
4810    }
4811
4812    /// Bring this window of the result into the cache: what a list binding calls for the
4813    /// rows it is about to show, batched into one `SELECT`.
4814    pub fn materialize(&self, range: std::ops::Range<usize>) {
4815        let keys: Vec<u64> = {
4816            let set = self.state.set.borrow();
4817            let ids = set.ids();
4818            let end = range.end.min(ids.len());
4819            let start = range.start.min(end);
4820            ids[start..end].to_vec()
4821        };
4822        if let Err(e) = self.container.ensure_resident::<M>(&keys) {
4823            self.container.inner.error.set(Some(e.to_string()));
4824        }
4825    }
4826
4827    /// Swap the fetch (a changed filter or sort): requeries and reloads consumers. No-op when
4828    /// equal to the current one, so a `query_fn` closure can re-run cheaply.
4829    pub fn set_fetch(&self, fetch: Fetch) {
4830        if *self.state.set.borrow().fetch() == fetch {
4831            return;
4832        }
4833        self.container.rewire_watches(&self.state, &fetch);
4834        {
4835            let mut set = self.state.set.borrow_mut();
4836            *set = ResultSet::new(fetch);
4837        }
4838        // Resolve once pending statements land; mid-turn the flush has not run yet.
4839        self.state.needs_sql.set(true);
4840        self.state
4841            .pending_commit
4842            .set(!self.container.inner.dirty.borrow().is_empty());
4843        self.refresh_if_stale();
4844        self.state.pending.borrow_mut().reload();
4845        self.bump();
4846    }
4847
4848    /// Drain what changed since the last call: the list source's feed. Pending staleness
4849    /// settles first, so a drain right after an edit already narrates it.
4850    pub fn take_events(&self) -> QueryEvents {
4851        self.refresh_if_stale();
4852        std::mem::replace(&mut *self.state.pending.borrow_mut(), QueryEvents::None)
4853    }
4854
4855    /// A dependency-touching change arrived this turn and the flush has not run yet: settle
4856    /// it now. With autosave the pending statements flush (which requeries everything stale);
4857    /// with autosave off the query re-derives against the last save; the file is the only
4858    /// thing that can answer it.
4859    fn refresh_if_stale(&self) {
4860        if !self.state.needs_sql.get() {
4861            return;
4862        }
4863        if self.container.inner.autosave.get() {
4864            let _ = self.container.save();
4865        }
4866        if self.state.needs_sql.replace(false) {
4867            self.container.requery(&self.state);
4868        }
4869    }
4870
4871    fn bump(&self) {
4872        self.state
4873            .version
4874            .set(self.state.version.get_untracked().wrapping_add(1));
4875    }
4876}
4877
4878/// Builder for a [`Query`]: `container.query::<Trip>().filter(…).sort(…).live()`.
4879pub struct QueryBuilder<'c, M: Model> {
4880    container: &'c ModelContainer,
4881    fetch: Fetch,
4882    _p: std::marker::PhantomData<fn() -> M>,
4883}
4884
4885impl<M: Model> QueryBuilder<'_, M> {
4886    pub fn filter(mut self, p: Pred) -> Self {
4887        self.fetch = self.fetch.filter(p);
4888        self
4889    }
4890    pub fn sort(mut self, s: Sort) -> Self {
4891        self.fetch = self.fetch.sort(s);
4892        self
4893    }
4894    pub fn limit(mut self, n: usize) -> Self {
4895        self.fetch = self.fetch.limit(n);
4896        self
4897    }
4898    /// Run the fetch and keep it live against the change log.
4899    pub fn live(self) -> Query<M> {
4900        self.container.install_query::<M>(self.fetch, None)
4901    }
4902
4903    /// Keep only the count live, the badge form: no id vector, one `SELECT COUNT(*)` per
4904    /// requery, the same dependency gating.
4905    pub fn live_count(self) -> CountQuery<M> {
4906        CountQuery {
4907            state: self.container.install_state::<M>(self.fetch, None, true),
4908            container: self.container.clone(),
4909            _p: std::marker::PhantomData,
4910        }
4911    }
4912}
4913
4914/// A live count over one model's table, the badge query: `SELECT COUNT(*)` behind the same
4915/// dependency-gated staleness as [`Query`], holding no id vector, so a count over a
4916/// million-row result costs O(1) memory. Clone shares the same state.
4917pub struct CountQuery<M: Model> {
4918    state: Rc<QueryState>,
4919    container: ModelContainer,
4920    _p: std::marker::PhantomData<fn() -> M>,
4921}
4922
4923impl<M: Model> Clone for CountQuery<M> {
4924    fn clone(&self) -> Self {
4925        CountQuery {
4926            state: self.state.clone(),
4927            container: self.container.clone(),
4928            _p: std::marker::PhantomData,
4929        }
4930    }
4931}
4932
4933impl<M: Model> CountQuery<M> {
4934    /// The last read error, independently of the last successful count.
4935    pub fn error(&self) -> day_reactive::Signal<Option<DbError>> {
4936        self.state.error
4937    }
4938    /// Checked count for operations that require a successful read.
4939    pub fn try_get(&self) -> Result<usize, DbError> {
4940        let n = self.get();
4941        match self.state.error.get() {
4942            Some(e) => Err(e),
4943            None => Ok(n),
4944        }
4945    }
4946    /// Retry after a transient read error.
4947    pub fn refresh(&self) {
4948        self.state.needs_sql.set(true);
4949        self.refresh_if_stale();
4950    }
4951
4952    /// The count, as a tracked read: the caller re-runs when it changes, and only then.
4953    pub fn get(&self) -> usize {
4954        self.refresh_if_stale();
4955        let _ = self.state.version.get();
4956        self.state.count.get()
4957    }
4958
4959    /// Untracked snapshot: reactively silent, still current.
4960    pub fn get_untracked(&self) -> usize {
4961        self.refresh_if_stale();
4962        self.state.count.get()
4963    }
4964
4965    /// Swap the fetch (a changed filter): re-counts. No-op when equal, so a `count_fn`
4966    /// closure can re-run cheaply.
4967    pub fn set_fetch(&self, fetch: Fetch) {
4968        if *self.state.set.borrow().fetch() == fetch {
4969            return;
4970        }
4971        self.container.rewire_watches(&self.state, &fetch);
4972        *self.state.set.borrow_mut() = ResultSet::new(fetch);
4973        self.state.needs_sql.set(true);
4974        self.state
4975            .pending_commit
4976            .set(!self.container.inner.dirty.borrow().is_empty());
4977        self.refresh_if_stale();
4978    }
4979
4980    fn refresh_if_stale(&self) {
4981        if !self.state.needs_sql.get() {
4982            return;
4983        }
4984        if self.container.inner.autosave.get() {
4985            let _ = self.container.save();
4986        }
4987        if self.state.needs_sql.replace(false) {
4988            self.container.requery(&self.state);
4989        }
4990    }
4991}
4992
4993/// A fallback row: the key plus the dependency columns the fallback `SELECT` carried.
4994struct FallbackRow<'a> {
4995    cols: &'a [&'static str],
4996    /// values[0] is the key; values[1..] align with `cols`.
4997    values: &'a [Value],
4998}
4999
5000impl RowView for FallbackRow<'_> {
5001    fn col(&self, c: &str) -> Option<Value> {
5002        self.cols
5003            .iter()
5004            .position(|n| *n == c)
5005            .and_then(|i| self.values.get(i + 1).cloned())
5006    }
5007}
5008
5009impl ModelContainer {
5010    /// Start a typed query over `M`'s rows. Panics (like [`ModelContainer::cache`]) if `M` is
5011    /// not in this container's `schema!`, a wiring bug worth stopping on.
5012    pub fn query<M: Model>(&self) -> QueryBuilder<'_, M> {
5013        let _ = self.cache::<M>();
5014        QueryBuilder {
5015            container: self,
5016            fetch: Fetch::new(),
5017            _p: std::marker::PhantomData,
5018        }
5019    }
5020
5021    /// The reactive-fetch form: `f` is a computation, so a query whose fetch depends on signals
5022    /// (a search term, a filter toggle) re-derives itself when they change.
5023    pub fn query_fn<M: Model>(&self, f: impl Fn() -> Fetch + 'static) -> Query<M> {
5024        let q = self.install_query::<M>(f(), None);
5025        let q2 = q.clone();
5026        day_reactive::bind(f, move |fetch| q2.set_fetch(fetch.clone()));
5027        q
5028    }
5029
5030    /// The reactive-fetch count: a badge whose fetch depends on signals (the "Today" cutoff,
5031    /// a filter toggle) re-counts itself when they change.
5032    pub fn count_fn<M: Model>(&self, f: impl Fn() -> Fetch + 'static) -> CountQuery<M> {
5033        let q = CountQuery::<M> {
5034            state: self.install_state::<M>(f(), None, true),
5035            container: self.clone(),
5036            _p: std::marker::PhantomData,
5037        };
5038        let q2 = q.clone();
5039        day_reactive::bind(f, move |fetch| q2.set_fetch(fetch.clone()));
5040        q
5041    }
5042
5043    /// Raw SQL, declared: a read-only SELECT returning ids, re-run whenever a flush touches
5044    /// one of the named tables. The price of the escape hatch is whole-query invalidation.
5045    pub fn query_raw<M: Model>(
5046        &self,
5047        sql: impl Into<String>,
5048        params: Vec<Value>,
5049        tables: &[&str],
5050    ) -> Query<M> {
5051        self.install_query::<M>(
5052            Fetch::new().filter(Pred::Raw(String::new(), Vec::new())),
5053            Some(RawQuery {
5054                sql: sql.into(),
5055                params,
5056                tables: tables.iter().map(|s| s.to_string()).collect(),
5057            }),
5058        )
5059    }
5060
5061    /// Opt into undo: One history over every store this container manages, `levels` deep.
5062    /// Undo/redo replay flows through the same change pipeline as the user's edits, so
5063    /// autosave writes the inverse statements and live queries hear rows come back. Call it
5064    /// once, after open; clear it on migration (`UndoStack::clear`). While a stack is
5065    /// installed, deletes materialize the rows they remove (a cascade included) so the
5066    /// history can restore them.
5067    pub fn undo(&self, levels: usize) -> day_model::UndoStack {
5068        let stack = day_model::UndoStack::new(levels);
5069        for hooks in self.inner.tables.borrow().values() {
5070            (hooks.watch_undo)(&stack);
5071        }
5072        stack
5073    }
5074
5075    /// The driver's connection, directly, for maintenance, imports, or an extension's
5076    /// statements. Pending changes flush first; writes made here bypass the change log, so
5077    /// call [`ModelContainer::rescan`] afterward if they touched Day's tables.
5078    ///
5079    /// # Panics
5080    /// Panics if the pending save fails. Use [`ModelContainer::try_with_connection`] when
5081    /// the caller needs to handle storage errors.
5082    pub fn with_connection<R>(&self, f: impl FnOnce(&mut dyn SqliteConnection) -> R) -> R {
5083        self.save().expect(
5084            "pending persistence save failed; use try_with_connection to handle storage errors",
5085        );
5086        f(self.conn().as_mut())
5087    }
5088
5089    /// Flush pending edits before accessing the connection. The closure is never run if
5090    /// that save fails; its own error is returned unchanged.
5091    pub fn try_with_connection<R>(
5092        &self,
5093        f: impl FnOnce(&mut dyn SqliteConnection) -> Result<R, DbError>,
5094    ) -> Result<R, DbError> {
5095        self.save()?;
5096        f(self.conn().as_mut())
5097    }
5098
5099    /// Re-read the resident rows from the file and re-run every query: the recovery from
5100    /// writes that bypassed the change log ([`ModelContainer::with_connection`], another
5101    /// process). O(working set + query results), never O(table).
5102    pub fn rescan(&self) -> Result<(), DbError> {
5103        self.save()?;
5104        self.inner.blob_memo.borrow_mut().clear();
5105        self.refresh_resident()?;
5106        self.invalidate_relation_memos();
5107        self.requery_all();
5108        // The cache now equals the file; a later check_external should not re-merge for
5109        // whatever external commits this refresh already picked up.
5110        if self.inner.caps.external_changes {
5111            self.inner.data_version.set(self.file_data_version()?);
5112        }
5113        Ok(())
5114    }
5115
5116    /// Attach another SQLite file under `alias` and bring `schema`'s models (every one
5117    /// declared `external = "alias"`) into this container: their tables are read as they
5118    /// are, with no DDL, migration, or fingerprint, through the same caches, queries, and
5119    /// lists as the container's own. Writes to them fail at flush (the file is attached
5120    /// read-only where the engine honors `mode=ro`), which is the contract: the other
5121    /// database has its own owner.
5122    ///
5123    /// Calling it again with the same alias swaps the file: the old one is detached, every
5124    /// resident row of its models dropped, and every live query re-run: the shape a
5125    /// downloaded catalog update takes.
5126    pub fn attach_database(&self, alias: &str, path: &str, schema: Schema) -> Result<(), DbError> {
5127        if alias.is_empty() || !alias.chars().all(|c| c.is_ascii_alphanumeric() || c == '_') {
5128            return Err(DbError::new(
5129                DbErrorKind::Unsupported,
5130                format!("attach_database: {alias:?} is not a plain SQL schema name"),
5131            ));
5132        }
5133        let held = self.inner.attached.borrow().iter().any(|a| a == alias);
5134        if held {
5135            self.detach_database(alias)?;
5136        }
5137        // Flush first: a DETACH/ATTACH pair inside an open write transaction is refused.
5138        if !self.inner.dirty.borrow().is_empty() {
5139            self.save()?;
5140        }
5141        // `file:` URIs carry the read-only mode; a driver without URI filenames (the web
5142        // worker) takes the bare path and relies on nobody writing.
5143        let uri = if path.starts_with("file:") || path.contains("://") {
5144            path.to_string()
5145        } else {
5146            format!("file:{}?mode=ro", path.replace('?', "%3F"))
5147        };
5148        let attach = |target: &str| -> Result<(), DbError> {
5149            self.conn().execute(
5150                &format!("ATTACH DATABASE ? AS {}", ident(alias)),
5151                &[Value::Text(target.to_string())],
5152            )?;
5153            Ok(())
5154        };
5155        if let Err(uri_err) = attach(&uri) {
5156            attach(path).map_err(|_| uri_err)?;
5157        }
5158        self.inner.attached.borrow_mut().push(alias.to_string());
5159        let Schema {
5160            installers, wirers, ..
5161        } = schema;
5162        for install in installers {
5163            install(self)?;
5164        }
5165        for wire in wirers {
5166            wire(self)?;
5167        }
5168        self.rescan()
5169    }
5170
5171    /// Detach a database [`ModelContainer::attach_database`] holds, dropping every resident
5172    /// row of its models. Their stores stay registered (empty), so a query over them answers
5173    /// nothing until the alias is attached again.
5174    pub fn detach_database(&self, alias: &str) -> Result<(), DbError> {
5175        let position = self.inner.attached.borrow().iter().position(|a| a == alias);
5176        let Some(position) = position else {
5177            return Ok(());
5178        };
5179        if !self.inner.dirty.borrow().is_empty() {
5180            self.save()?;
5181        }
5182        self.inner.blob_memo.borrow_mut().clear();
5183        type Doomed = Vec<(Rc<dyn Fn() -> Vec<u64>>, EvictFn)>;
5184        let doomed: Doomed = self
5185            .inner
5186            .tables
5187            .borrow()
5188            .values()
5189            .filter(|h| h.name.schema == Some(alias))
5190            .map(|h| (h.resident_keys.clone(), h.evict.clone()))
5191            .collect();
5192        for (keys, evict) in &doomed {
5193            let resident = keys();
5194            let _ = evict(&resident, resident.len());
5195        }
5196        self.conn()
5197            .execute(&format!("DETACH DATABASE {}", ident(alias)), &[])?;
5198        self.inner.attached.borrow_mut().remove(position);
5199        self.rescan()
5200    }
5201
5202    /// Look for other connections' committed writes (another process, a sync engine, a CLI)
5203    /// and merge what changed. Detection is one `PRAGMA data_version` (the counter moves only
5204    /// when another connection commits, never for this one's own writes), so this is cheap
5205    /// enough to wire to app foreground, window focus, or a timer.
5206    ///
5207    /// When the counter moved, pending local edits flush first; then the resident rows are
5208    /// re-read and diffed: changed fields announce per column, disappearances take the
5209    /// structural path, every live query re-derives, all authored
5210    /// [`ModelContainer::EXTERNAL_AUTHOR`], so the autosave fold declines the echo and an
5211    /// installed undo stack skips them (another author's writes are not the user's history).
5212    /// Rows that arrived elsewhere become visible through the re-run queries and fault in
5213    /// like any other row. A row another connection rewrote arrives whole, so its
5214    /// `#[model(transient)]` fields reset to their defaults, exactly as at fault.
5215    ///
5216    /// Returns whether anything arrived. On a driver without detection
5217    /// ([`Capabilities::external_changes`]) this is `Ok(false)`; writes made
5218    /// through [`ModelContainer::with_connection`] are this connection's own and stay
5219    /// [`ModelContainer::rescan`]'s job.
5220    pub fn check_external(&self) -> Result<bool, DbError> {
5221        if !self.inner.caps.external_changes {
5222            return Ok(false);
5223        }
5224        let Some(current) = self.file_data_version()? else {
5225            return Ok(false);
5226        };
5227        if self.inner.data_version.get() == Some(current) {
5228            return Ok(false);
5229        }
5230        // Local edits flush first, so the diff compares the file against a cache with nothing
5231        // pending: an unflushed local edit must not read as the other side's deletion.
5232        self.save()?;
5233        self.refresh_resident()?;
5234        self.invalidate_relation_memos();
5235        self.requery_all();
5236        // A commit matters even when it inserted only nonresident rows: count/projection
5237        // observers still need invalidation. Advance only after a successful merge so errors
5238        // remain retryable.
5239        self.inner.data_version.set(Some(current));
5240        Ok(true)
5241    }
5242
5243    /// `PRAGMA data_version`, or `None` where the engine did not answer (the Recorder).
5244    fn file_data_version(&self) -> Result<Option<i64>, DbError> {
5245        let mut v = None;
5246        self.conn().query("PRAGMA data_version", &[], &mut |row| {
5247            if let Ok(i) = row.get(0).as_int() {
5248                v = Some(i);
5249            }
5250        })?;
5251        Ok(v)
5252    }
5253
5254    /// Re-select every resident row and feed the differences through the caches: per-field
5255    /// announcements, external deletions, all authored [`ModelContainer::EXTERNAL_AUTHOR`].
5256    fn refresh_resident(&self) -> Result<bool, DbError> {
5257        self.refresh_resident_in(None)
5258    }
5259
5260    /// [`ModelContainer::refresh_resident`] over the tables named (all of them for `None`).
5261    fn refresh_resident_in(&self, only: Option<&[&'static str]>) -> Result<bool, DbError> {
5262        struct RefreshJob {
5263            store: u64,
5264            resident_keys: Rc<dyn Fn() -> Vec<u64>>,
5265            refresh: RefreshFn,
5266            columns: String,
5267            table: String,
5268            keys_where: KeysWhere,
5269        }
5270        let jobs: Vec<RefreshJob> = {
5271            let tables = self.inner.tables.borrow();
5272            tables
5273                .iter()
5274                .filter(|(_, h)| only.is_none_or(|t| t.contains(&h.table)))
5275                .map(|(store, h)| RefreshJob {
5276                    store: *store,
5277                    resident_keys: h.resident_keys.clone(),
5278                    refresh: h.refresh.clone(),
5279                    columns: select_list(h),
5280                    table: h.name.sql(),
5281                    keys_where: keys_where_of(h),
5282                })
5283                .collect()
5284        };
5285        let mut changed = false;
5286        for RefreshJob {
5287            store,
5288            resident_keys,
5289            refresh,
5290            columns,
5291            table,
5292            keys_where,
5293        } in jobs
5294        {
5295            // Another writer may have replaced the bytes; the memo answers from the file next.
5296            self.inner.blob_memo.borrow_mut().forget_store(store);
5297            let resident = resident_keys();
5298            if resident.is_empty() {
5299                continue;
5300            }
5301            let mut rows: Vec<Vec<Value>> = Vec::new();
5302            for chunk in resident.chunks(MAX_BOUND_PARAMS / 2) {
5303                let (clause, params) = keys_where(chunk);
5304                self.conn().query(
5305                    &format!("SELECT {columns} FROM {table} WHERE {clause}"),
5306                    &params,
5307                    &mut |row| {
5308                        let n = Row::len(row);
5309                        rows.push((0..n).map(|i| row.get(i)).collect());
5310                    },
5311                )?;
5312            }
5313            // The connection borrow is released before refresh announces; a sink hearing
5314            // these changes may read back through SQL.
5315            if refresh(rows)? {
5316                changed = true;
5317            }
5318        }
5319        Ok(changed)
5320    }
5321
5322    fn install_state<M: Model>(
5323        &self,
5324        fetch: Fetch,
5325        raw: Option<RawQuery>,
5326        count_only: bool,
5327    ) -> Rc<QueryState> {
5328        let store = self.cache::<M>();
5329        let state = Rc::new(QueryState {
5330            store_id: store.store_id(),
5331            table: M::TABLE,
5332            watches: RefCell::new(Vec::new()),
5333            local_extra: RefCell::new(Vec::new()),
5334            set: RefCell::new(ResultSet::new(fetch.clone())),
5335            version: day_reactive::Scope::detached().enter(|| day_reactive::Signal::new(0)),
5336            pending: RefCell::new(QueryEvents::None),
5337            needs_sql: Cell::new(false),
5338            pending_commit: Cell::new(!self.inner.dirty.borrow().is_empty()),
5339            error: day_reactive::Scope::detached().enter(|| day_reactive::Signal::new(None)),
5340            raw,
5341            count_only,
5342            count: Cell::new(0),
5343        });
5344        self.rewire_watches(&state, &fetch);
5345        self.inner.queries.borrow_mut().push(Rc::downgrade(&state));
5346        // The seed: flush anything pending (with autosave; without it the query answers from
5347        // the last save, documented), then one SQL round trip.
5348        if self.inner.autosave.get() && !self.inner.dirty.borrow().is_empty() {
5349            let _ = self.save();
5350        }
5351        if count_only {
5352            state.count.set(self.answer_count(&state));
5353        } else {
5354            let ids = self.answer(&state);
5355            state.set.borrow_mut().reset(ids);
5356        }
5357        // The seed is the list's starting snapshot, not a stream of inserts to replay.
5358        *state.pending.borrow_mut() = QueryEvents::None;
5359        state
5360    }
5361
5362    fn install_query<M: Model>(&self, fetch: Fetch, raw: Option<RawQuery>) -> Query<M> {
5363        Query {
5364            state: self.install_state::<M>(fetch, raw, false),
5365            container: self.clone(),
5366            _p: std::marker::PhantomData,
5367        }
5368    }
5369
5370    /// (Re)compute a query's relation subscriptions from its fetch.
5371    fn rewire_watches(&self, state: &Rc<QueryState>, fetch: &Fetch) {
5372        let deps = fetch.dependencies();
5373        let mut watches: Vec<RelWatch> = Vec::new();
5374        let mut local_extra: Vec<&'static str> = Vec::new();
5375        let relations = self.inner.relations.borrow();
5376        let joins = self.inner.joins.borrow();
5377        for dep in &deps.related {
5378            let mut resolved = false;
5379            for r in relations.iter() {
5380                if r.parent_table == dep.owner && r.parent_field == dep.field {
5381                    watches.push(RelWatch {
5382                        store: r.child_store,
5383                        join_store: None,
5384                        fields: {
5385                            let mut f = vec![r.fk_field];
5386                            if let Some(o) = r.ordered {
5387                                f.push(o);
5388                            }
5389                            f
5390                        },
5391                        columns: dep.columns.clone(),
5392                    });
5393                    resolved = true;
5394                    break;
5395                }
5396                if r.child_table == dep.owner && r.fk_field == dep.field {
5397                    // The membership column lives on the query's table: a rewrite of the
5398                    // reference must mark it stale even though no predicate reads it.
5399                    if dep.owner == state.table && !local_extra.contains(&r.fk_col) {
5400                        local_extra.push(r.fk_col);
5401                    }
5402                    watches.push(RelWatch {
5403                        store: r.parent_store,
5404                        join_store: None,
5405                        fields: Vec::new(),
5406                        columns: dep.columns.clone(),
5407                    });
5408                    resolved = true;
5409                    break;
5410                }
5411            }
5412            if resolved {
5413                continue;
5414            }
5415            // A link: the far store's read columns matter, and so does the owner's value
5416            // column; rewriting it is what moves the row across the link.
5417            if let Some(l) = self
5418                .inner
5419                .links
5420                .borrow()
5421                .iter()
5422                .find(|l| l.owner_table == dep.owner && l.field == dep.field)
5423                .copied()
5424            {
5425                if dep.owner == state.table && !local_extra.contains(&l.local) {
5426                    local_extra.push(l.local);
5427                }
5428                let far = self
5429                    .inner
5430                    .tables
5431                    .borrow()
5432                    .iter()
5433                    .find(|(_, h)| h.table == l.target_table)
5434                    .map(|(id, _)| *id);
5435                if let Some(store) = far {
5436                    let mut columns = dep.columns.clone();
5437                    if !columns.contains(&l.remote) {
5438                        columns.push(l.remote);
5439                    }
5440                    watches.push(RelWatch {
5441                        store,
5442                        join_store: None,
5443                        fields: Vec::new(),
5444                        columns,
5445                    });
5446                }
5447                continue;
5448            }
5449            for j in joins.iter() {
5450                let side = if j.a_table == dep.owner && j.a_field == dep.field {
5451                    Some(j.b_store)
5452                } else if j.b_table == dep.owner && j.b_field.get() == Some(dep.field) {
5453                    Some(j.a_store)
5454                } else {
5455                    None
5456                };
5457                if let Some(other) = side {
5458                    watches.push(RelWatch {
5459                        store: other,
5460                        join_store: Some(j.join_store),
5461                        fields: Vec::new(),
5462                        columns: dep.columns.clone(),
5463                    });
5464                    break;
5465                }
5466            }
5467        }
5468        *state.watches.borrow_mut() = watches;
5469        *state.local_extra.borrow_mut() = local_extra;
5470    }
5471
5472    /// One announced change: decide, per live query, whether it can move the result, and
5473    /// mark stale where it can. No SQL runs here; the requery happens once, after the flush.
5474    fn mark_queries_stale(&self, change: &day_model::Change) {
5475        let Some(&store) = change.components.first() else {
5476            return;
5477        };
5478        let states: Vec<Rc<QueryState>> = {
5479            let mut queries = self.inner.queries.borrow_mut();
5480            queries.retain(|w| w.strong_count() > 0);
5481            queries.iter().filter_map(|w| w.upgrade()).collect()
5482        };
5483        if states.is_empty() {
5484            return;
5485        }
5486        let key = change.components.get(1).copied();
5487        if key == Some(day_model::STRUCTURE) {
5488            return; // the shape path duplicates the row paths
5489        }
5490        // The change log speaks field names; predicates speak column names.
5491        let (column, changed_table): (Option<String>, Option<&'static str>) = {
5492            let tables = self.inner.tables.borrow();
5493            let hooks = tables.get(&store);
5494            let column = if change.components.len() >= 3 {
5495                hooks.map(|h| {
5496                    h.fields
5497                        .iter()
5498                        .position(|f| f == change.label)
5499                        .map(|i| h.columns[i].clone())
5500                        // A transient field: never a dependency column.
5501                        .unwrap_or_else(|| "\u{0}".to_string())
5502                })
5503            } else {
5504                None
5505            };
5506            (column, hooks.map(|h| h.table))
5507        };
5508        let column = column.as_deref();
5509
5510        for state in &states {
5511            if state.needs_sql.get() {
5512                continue; // already stale; nothing to learn
5513            }
5514            if let Some(raw) = &state.raw {
5515                if changed_table.is_some_and(|t| raw.tables.iter().any(|r| r == t)) {
5516                    state.needs_sql.set(true);
5517                }
5518                continue;
5519            }
5520            // Both gates apply: a self-referential relation makes the query's own store a
5521            // related store too, so the own-table check must not shadow the watch check.
5522            let own_stale = state.store_id == store
5523                && match (key, change.op) {
5524                    (None, _) => true, // a wholesale rewrite: anything may have moved
5525                    (Some(_), Op::Insert) | (Some(_), Op::Delete) => true,
5526                    (Some(_), Op::Set) => match column {
5527                        // A row-level merge without a field name: assume the worst.
5528                        None => true,
5529                        Some(c) => {
5530                            let set = state.set.borrow();
5531                            set.deps().touches_local(c) || state.local_extra.borrow().contains(&c)
5532                        }
5533                    },
5534                    (Some(_), Op::Move) => false, // user order is not a query's business
5535                };
5536            let stale = own_stale || {
5537                let watches = state.watches.borrow();
5538                watches.iter().any(|w| {
5539                    if w.join_store == Some(store) {
5540                        return true; // every link/unlink/reposition is a membership change
5541                    }
5542                    if w.store != store {
5543                        return false;
5544                    }
5545                    match (key, change.op) {
5546                        (None, _) => true,
5547                        (Some(_), Op::Insert) | (Some(_), Op::Delete) => true,
5548                        (Some(_), Op::Set) => {
5549                            w.fields.contains(&change.label)
5550                                || column.is_some_and(|c| w.columns.contains(&c))
5551                        }
5552                        (Some(_), Op::Move) => false,
5553                    }
5554                })
5555            };
5556            if stale {
5557                state.needs_sql.set(true);
5558                state.pending_commit.set(true);
5559            }
5560        }
5561    }
5562
5563    /// After a flush: every stale query re-derives (plus raw queries whose tables the flush
5564    /// touched), each answer diffed into list deltas.
5565    fn run_deferred_requeries(&self, stmts: &[(String, Vec<Value>)]) {
5566        let states: Vec<Rc<QueryState>> = self
5567            .inner
5568            .queries
5569            .borrow()
5570            .iter()
5571            .filter_map(|w| w.upgrade())
5572            .collect();
5573        for state in states {
5574            let mut due = state.needs_sql.replace(false) | state.pending_commit.replace(false);
5575            if let Some(raw) = &state.raw
5576                && !due
5577            {
5578                due = stmts
5579                    .iter()
5580                    .any(|(sql, _)| raw.tables.iter().any(|t| statement_touches(sql, t)));
5581            }
5582            if due {
5583                self.requery(&state);
5584            }
5585        }
5586    }
5587
5588    /// Mark every query stale and requery now: the external-change and rescan path.
5589    fn requery_all(&self) {
5590        let states: Vec<Rc<QueryState>> = self
5591            .inner
5592            .queries
5593            .borrow()
5594            .iter()
5595            .filter_map(|w| w.upgrade())
5596            .collect();
5597        for state in states {
5598            state.needs_sql.set(false);
5599            self.requery(&state);
5600        }
5601    }
5602
5603    /// [`ModelContainer::requery_all`] for the live queries that read `tables`: a query over
5604    /// one of them, one crossing into one through a relation (or that relation's join
5605    /// table), or a raw query naming one.
5606    fn requery_tables(&self, tables: &[&'static str]) {
5607        let stores: Vec<u64> = self
5608            .inner
5609            .tables
5610            .borrow()
5611            .iter()
5612            .filter(|(_, h)| tables.contains(&h.table))
5613            .map(|(id, _)| *id)
5614            .collect();
5615        let states: Vec<Rc<QueryState>> = self
5616            .inner
5617            .queries
5618            .borrow()
5619            .iter()
5620            .filter_map(|w| w.upgrade())
5621            .collect();
5622        for state in states {
5623            let reads = match &state.raw {
5624                Some(raw) => raw.tables.iter().any(|t| tables.contains(&t.as_str())),
5625                None => {
5626                    stores.contains(&state.store_id)
5627                        || state.watches.borrow().iter().any(|w| {
5628                            stores.contains(&w.store)
5629                                || w.join_store.is_some_and(|j| stores.contains(&j))
5630                        })
5631                }
5632            };
5633            if reads {
5634                state.needs_sql.set(false);
5635                self.requery(&state);
5636            }
5637        }
5638    }
5639
5640    /// One requery: answer through the engine, adopt, narrate.
5641    fn requery(&self, state: &Rc<QueryState>) {
5642        if state.count_only {
5643            let n = self.answer_count(state);
5644            if n != state.count.get() {
5645                state.count.set(n);
5646                state
5647                    .version
5648                    .set(state.version.get_untracked().wrapping_add(1));
5649            }
5650            return;
5651        }
5652        let ids = self.answer(state);
5653        let change = state.set.borrow_mut().adopt(ids);
5654        match change {
5655            SetChange::Same => {}
5656            SetChange::Deltas(d) => {
5657                state.pending.borrow_mut().push(&d);
5658                state
5659                    .version
5660                    .set(state.version.get_untracked().wrapping_add(1));
5661            }
5662            SetChange::Reload => {
5663                state.pending.borrow_mut().reload();
5664                state
5665                    .version
5666                    .set(state.version.get_untracked().wrapping_add(1));
5667            }
5668        }
5669    }
5670
5671    /// Answer a COUNT-shaped fetch: one `SELECT COUNT(*)`, capped by the fetch's limit
5672    /// (a limited set's length is `min(count, limit)`). The fallback form counts its
5673    /// re-checked rows the same way.
5674    fn answer_count(&self, state: &Rc<QueryState>) -> usize {
5675        let result = (|| {
5676            if self.table_detached(state.table) {
5677                return Ok(0);
5678            }
5679            if let Some(raw) = &state.raw {
5680                return self
5681                    .select_ids_checked(&raw.sql, &raw.params)
5682                    .map(|ids| ids.len());
5683            }
5684            let fetch = state.set.borrow().fetch().clone();
5685            let cap = fetch.limit.unwrap_or(usize::MAX);
5686            let snapshot = self.sql_snapshot();
5687            match compile_count(state.table, &fetch, &snapshot) {
5688                Ok(q) => {
5689                    let mut n = Ok(0_i64);
5690                    self.conn().query(&q.sql, &q.params, &mut |row| {
5691                        n = row.get(0).as_int();
5692                    })?;
5693                    Ok((n?.max(0) as usize).min(cap))
5694                }
5695                Err(CompileErr::NeedsFold) => {
5696                    let (q, cols) = compile_fallback(state.table, &fetch, &snapshot)
5697                        .map_err(|e| DbError::new(DbErrorKind::Unsupported, e.message()))?;
5698                    let mut n = 0;
5699                    self.conn().query(&q.sql, &q.params, &mut |row| {
5700                        let values = (0..row.len()).map(|i| row.get(i)).collect::<Vec<_>>();
5701                        if let Some(h) = value_to_handle(&values[0])
5702                            && fetch.pred.eval(
5703                                h,
5704                                &FallbackRow {
5705                                    cols: &cols,
5706                                    values: &values,
5707                                },
5708                            )
5709                        {
5710                            n += 1;
5711                        }
5712                    })?;
5713                    Ok(n.min(cap))
5714                }
5715                Err(e) => Err(DbError::new(DbErrorKind::Unsupported, e.message())),
5716            }
5717        })();
5718        match result {
5719            Ok(n) => {
5720                state.error.set(None);
5721                n
5722            }
5723            Err(error) => {
5724                self.inner.error.set(Some(error.to_string()));
5725                state.error.set(Some(error));
5726                state.count.get()
5727            }
5728        }
5729    }
5730
5731    /// Answer a query's fetch through the engine: the compiled form, the fallback form for
5732    /// drivers without `day_fold`, or the raw statement.
5733    fn answer(&self, state: &Rc<QueryState>) -> Vec<u64> {
5734        match self.answer_checked(state) {
5735            Ok(ids) => {
5736                state.error.set(None);
5737                ids
5738            }
5739            Err(error) => {
5740                self.inner.error.set(Some(error.to_string()));
5741                state.error.set(Some(error));
5742                // A failed read is not an empty result. Retain the last successful set.
5743                state.set.borrow().ids().to_vec()
5744            }
5745        }
5746    }
5747    /// Whether `table` belongs to an attached database that is not attached right now. The
5748    /// alias is the model's declared one, not a prefix of the name: a table of the
5749    /// container's own may be called `dot.ted`.
5750    fn table_detached(&self, table: &str) -> bool {
5751        let tables = self.inner.tables.borrow();
5752        let Some(alias) = tables
5753            .values()
5754            .find(|h| h.table == table)
5755            .and_then(|h| h.name.schema)
5756        else {
5757            return false;
5758        };
5759        alias != "main"
5760            && alias != "temp"
5761            && !self.inner.attached.borrow().iter().any(|a| a == alias)
5762    }
5763    fn answer_checked(&self, state: &Rc<QueryState>) -> Result<Vec<u64>, DbError> {
5764        // Explicit detachment is a successful transition to an empty catalog, not an I/O error.
5765        if self.table_detached(state.table) {
5766            return Ok(Vec::new());
5767        }
5768        if let Some(raw) = &state.raw {
5769            return self.select_ids_checked(&raw.sql, &raw.params);
5770        }
5771        let fetch = state.set.borrow().fetch().clone();
5772        let snapshot = self.sql_snapshot();
5773        match compile_fetch(state.table, &fetch, &snapshot) {
5774            Ok(q) => self.select_ids_checked(&q.sql, &q.params),
5775            Err(CompileErr::NeedsFold) => {
5776                let (q, cols) = compile_fallback(state.table, &fetch, &snapshot)
5777                    .map_err(|e| DbError::new(DbErrorKind::Unsupported, e.message()))?;
5778                let mut ids = Vec::new();
5779                self.conn().query(&q.sql, &q.params, &mut |row| {
5780                    let values = (0..row.len()).map(|i| row.get(i)).collect::<Vec<_>>();
5781                    if let Some(h) = value_to_handle(&values[0])
5782                        && fetch.pred.eval(
5783                            h,
5784                            &FallbackRow {
5785                                cols: &cols,
5786                                values: &values,
5787                            },
5788                        )
5789                    {
5790                        ids.push(h);
5791                    }
5792                })?;
5793                if let Some(limit) = fetch.limit {
5794                    ids.truncate(limit);
5795                }
5796                Ok(ids)
5797            }
5798            Err(e) => Err(DbError::new(DbErrorKind::Unsupported, e.message())),
5799        }
5800    }
5801
5802    /// A point-in-time view of names for the SQL compiler: tables, keys, shadows, wired
5803    /// relations, and whether the driver folds case.
5804    fn sql_snapshot(&self) -> SqlSnapshot {
5805        let tables = self.inner.tables.borrow();
5806        let relations = self.inner.relations.borrow();
5807        let joins = self.inner.joins.borrow();
5808        SqlSnapshot {
5809            tables: tables
5810                .values()
5811                .map(|h| TableInfo {
5812                    table: h.table.to_string(),
5813                    sql: h.name.sql(),
5814                    key: h.key_cols[0].clone(),
5815                    fts: h.fts.as_ref().map(|_| FtsSql {
5816                        from: h.name.shadow("_fts"),
5817                        match_col: ident(&format!("{}_fts", h.name.bare)),
5818                    }),
5819                    fts_key: h.fts_key,
5820                    spatial: h
5821                        .spatial
5822                        .as_ref()
5823                        .map(|(lat, lon, _)| (lat.clone(), lon.clone(), h.name.shadow("_geo"))),
5824                })
5825                .collect(),
5826            rels: relations
5827                .iter()
5828                .map(|r| RelInfo {
5829                    parent_table: r.parent_table,
5830                    parent_field: r.parent_field,
5831                    parent_key: r.parent_key_col,
5832                    child_table: r.child_table,
5833                    child_key: r.child_key_col,
5834                    fk_field: r.fk_field,
5835                    fk_col: r.fk_col,
5836                })
5837                .collect(),
5838            joins: joins
5839                .iter()
5840                .map(|j| JoinInfo {
5841                    join_table: j.join_table,
5842                    a_table: j.a_table,
5843                    a_field: j.a_field,
5844                    a_key: j.a_key_col,
5845                    b_table: j.b_table,
5846                    b_field: j.b_field.get(),
5847                    b_key: j.b_key_col,
5848                    parent_col: j.parent_col,
5849                    child_col: j.child_col,
5850                })
5851                .collect(),
5852            links: self.inner.links.borrow().clone(),
5853            fold: self.inner.caps.unicode_fold,
5854        }
5855    }
5856}
5857
5858/// One table as the SQL compiler sees it: `table` is the plain name it is asked about,
5859/// `sql` the quoted form it writes; the shadows come already quoted, the columns plain.
5860struct TableInfo {
5861    table: String,
5862    sql: String,
5863    key: String,
5864    fts: Option<FtsSql>,
5865    fts_key: &'static str,
5866    spatial: Option<(String, String, String)>,
5867}
5868
5869struct RelInfo {
5870    parent_table: &'static str,
5871    parent_field: &'static str,
5872    parent_key: &'static str,
5873    child_table: &'static str,
5874    child_key: &'static str,
5875    fk_field: &'static str,
5876    fk_col: &'static str,
5877}
5878
5879struct JoinInfo {
5880    join_table: &'static str,
5881    a_table: &'static str,
5882    a_field: &'static str,
5883    a_key: &'static str,
5884    b_table: &'static str,
5885    b_field: Option<&'static str>,
5886    b_key: &'static str,
5887    parent_col: &'static str,
5888    child_col: &'static str,
5889}
5890
5891struct SqlSnapshot {
5892    tables: Vec<TableInfo>,
5893    rels: Vec<RelInfo>,
5894    joins: Vec<JoinInfo>,
5895    links: Vec<LinkInfo>,
5896    fold: bool,
5897}
5898
5899impl SqlIndex for SqlSnapshot {
5900    fn relation(&self, owner: &str, field: &str) -> Option<RelSql> {
5901        for r in &self.rels {
5902            if r.parent_table == owner && r.parent_field == field {
5903                return Some(RelSql::Children {
5904                    target_key: r.child_key.to_string(),
5905                    fk_col: r.fk_col.to_string(),
5906                    owner_key: r.parent_key.to_string(),
5907                });
5908            }
5909            if r.child_table == owner && r.fk_field == field {
5910                return Some(RelSql::Referent {
5911                    target_key: r.parent_key.to_string(),
5912                    fk_col: r.fk_col.to_string(),
5913                });
5914            }
5915        }
5916        for j in &self.joins {
5917            if j.a_table == owner && j.a_field == field {
5918                return Some(RelSql::Join {
5919                    join_table: j.join_table.to_string(),
5920                    owner_col: j.parent_col.to_string(),
5921                    target_col: j.child_col.to_string(),
5922                    owner_key: j.a_key.to_string(),
5923                    target_key: j.b_key.to_string(),
5924                });
5925            }
5926            if j.b_table == owner && j.b_field == Some(field) {
5927                return Some(RelSql::Join {
5928                    join_table: j.join_table.to_string(),
5929                    owner_col: j.child_col.to_string(),
5930                    target_col: j.parent_col.to_string(),
5931                    owner_key: j.b_key.to_string(),
5932                    target_key: j.a_key.to_string(),
5933                });
5934            }
5935        }
5936        for l in &self.links {
5937            if l.owner_table == owner && l.field == field {
5938                return Some(RelSql::Linked {
5939                    local_col: l.local.to_string(),
5940                    remote_col: l.remote.to_string(),
5941                    target_key: self.key_of(l.target_table)?,
5942                });
5943            }
5944        }
5945        None
5946    }
5947
5948    fn key_of(&self, table: &str) -> Option<String> {
5949        self.tables
5950            .iter()
5951            .find(|t| t.table == table)
5952            .map(|t| t.key.clone())
5953    }
5954
5955    fn table_sql(&self, table: &str) -> String {
5956        self.tables
5957            .iter()
5958            .find(|t| t.table == table)
5959            .map(|t| t.sql.clone())
5960            .unwrap_or_else(|| ident(table))
5961    }
5962
5963    fn fts_of(&self, table: &str) -> Option<FtsSql> {
5964        self.tables
5965            .iter()
5966            .find(|t| t.table == table)
5967            .and_then(|t| t.fts.clone())
5968    }
5969
5970    fn fts_key_of(&self, table: &str) -> &str {
5971        self.tables
5972            .iter()
5973            .find(|t| t.table == table)
5974            .map(|t| t.fts_key)
5975            .unwrap_or("rowid")
5976    }
5977
5978    fn geo_of(&self, table: &str, lat: &str, lon: &str) -> Option<String> {
5979        self.tables
5980            .iter()
5981            .find(|t| t.table == table)
5982            .and_then(|t| t.spatial.as_ref())
5983            .filter(|(a, o, _)| a == lat && o == lon)
5984            .map(|(_, _, g)| g.clone())
5985    }
5986
5987    fn unicode_fold(&self) -> bool {
5988        self.fold
5989    }
5990}
5991
5992/// Whether a statement's target table is `table`, a plain-text check over the SQL the fold
5993/// itself produced (`INSERT INTO "t" … ON CONFLICT`, `UPDATE "t" SET …`, `DELETE FROM "t" …`).
5994/// The fold quotes its table names, so the name is read back through the quotes; `table` is
5995/// the plain name a raw query declared.
5996fn statement_touches(sql: &str, table: &str) -> bool {
5997    for prefix in [
5998        "INSERT INTO ",
5999        "INSERT OR REPLACE INTO ",
6000        "UPDATE ",
6001        "DELETE FROM ",
6002    ] {
6003        if let Some(rest) = sql.strip_prefix(prefix) {
6004            return quoted_name(rest).as_deref() == Some(table);
6005        }
6006    }
6007    false
6008}
6009
6010/// The identifier a quoted name at the start of `sql` spells (a doubled `"` is one quote),
6011/// `None` when `sql` does not start with one.
6012fn quoted_name(sql: &str) -> Option<String> {
6013    let mut chars = sql.strip_prefix('"')?.chars();
6014    let mut name = String::new();
6015    loop {
6016        match chars.next()? {
6017            '"' => match chars.next() {
6018                Some('"') => name.push('"'),
6019                _ => return Some(name),
6020            },
6021            ch => name.push(ch),
6022        }
6023    }
6024}
6025
6026// ---------------------------------------------------------------------------
6027// Query as a list row source (feature `pieces`)
6028// ---------------------------------------------------------------------------
6029
6030#[cfg(feature = "pieces")]
6031mod pieces_glue {
6032    use std::cell::RefCell;
6033
6034    use day_model::{Elem, Keyed, Store};
6035    use day_pieces::{ModelSlot, RowConn, RowSource};
6036
6037    use crate::{Delta, Model, Query, QueryEvents};
6038
6039    /// How far around a bound row the list source faults in one batch: the price of showing
6040    /// row N is one `SELECT` that also covers the rows about to scroll in.
6041    const FAULT_BEHIND: usize = 16;
6042    const FAULT_AHEAD: usize = 64;
6043
6044    /// `list(query, row)`: the query's ids are the display order, rows fault in as the list
6045    /// binds them (a window at a time), and set changes arrive as row deltas the native list
6046    /// can animate.
6047    impl<M: Model> RowSource for Query<M> {
6048        type Slot = ModelSlot<M>;
6049        type Ref = Elem<M>;
6050        type Conn = QueryConn<M>;
6051        fn connect(self) -> QueryConn<M> {
6052            let store = self.container.cache::<M>();
6053            QueryConn {
6054                query: self,
6055                store,
6056                keys: RefCell::new(Vec::new()),
6057            }
6058        }
6059    }
6060
6061    pub struct QueryConn<M: Model> {
6062        query: Query<M>,
6063        store: Store<Keyed<M>>,
6064        keys: RefCell<Vec<u64>>,
6065    }
6066
6067    impl<M: Model> QueryConn<M> {
6068        /// Make the row at `index` (and its neighborhood) resident before anything binds it.
6069        fn fault_window(&self, index: usize) {
6070            let len = self.keys.borrow().len();
6071            let start = index.saturating_sub(FAULT_BEHIND);
6072            let end = (index + FAULT_AHEAD).min(len);
6073            self.query.materialize(start..end);
6074        }
6075    }
6076
6077    impl<M: Model> RowConn for QueryConn<M> {
6078        type Slot = ModelSlot<M>;
6079        type Ref = Elem<M>;
6080
6081        fn refresh(&self) -> Vec<u64> {
6082            let keys: Vec<u64> = self.query.ids().iter().map(|id| id.handle()).collect();
6083            *self.keys.borrow_mut() = keys.clone();
6084            keys
6085        }
6086        fn len(&self) -> usize {
6087            self.keys.borrow().len()
6088        }
6089        fn token_at(&self, index: usize) -> u64 {
6090            self.keys.borrow().get(index).copied().unwrap_or(0)
6091        }
6092        fn tokens_now(&self) -> Vec<u64> {
6093            self.keys.borrow().clone()
6094        }
6095        fn slot_at(&self, index: usize) -> Option<ModelSlot<M>> {
6096            let key = self.keys.borrow().get(index).copied()?;
6097            if !self.store.with_untracked(|k| k.get(key).is_some()) {
6098                self.fault_window(index);
6099            }
6100            Some(ModelSlot::for_key(self.store, key))
6101        }
6102        fn rebind(&self, slot: &ModelSlot<M>, index: usize) {
6103            if let Some(key) = self.keys.borrow().get(index).copied() {
6104                if !self.store.with_untracked(|k| k.get(key).is_some()) {
6105                    self.fault_window(index);
6106                }
6107                slot.rebind_key(key);
6108            }
6109        }
6110        fn select_ref(&self, index: usize) -> Option<Elem<M>> {
6111            let key = self.keys.borrow().get(index).copied()?;
6112            if !self.store.with_untracked(|k| k.get(key).is_some()) {
6113                self.fault_window(index);
6114            }
6115            Some(self.store.elem(key))
6116        }
6117        fn values_flow_by_reload(&self) -> bool {
6118            false // row values flow through the store's own per-field notifications
6119        }
6120        fn take_row_events(&self) -> Option<Vec<day_spec::props::RowDelta>> {
6121            match self.query.take_events() {
6122                QueryEvents::Deltas(d) => Some(
6123                    d.into_iter()
6124                        .map(|d| match d {
6125                            Delta::Insert(i, _) => day_spec::props::RowDelta::Insert(i),
6126                            Delta::Remove(i, _) => day_spec::props::RowDelta::Remove(i),
6127                            Delta::Move(from, to, _) => day_spec::props::RowDelta::Move(from, to),
6128                        })
6129                        .collect(),
6130                ),
6131                // Reload means "the whole set moved"; None here means the same to the list.
6132                QueryEvents::Reload | QueryEvents::None => None,
6133            }
6134        }
6135        fn commit_move(&self, from: usize, to: usize) {
6136            // The native drag already moved the row: serve that order until the app's write
6137            // (its on_reorder, typically a rank column the query sorts by) requeries. The list
6138            // expects exactly this order back as the echo of its own move; left unrotated, the
6139            // echo never matched, and the query's own move was replayed on rows already moved.
6140            let mut keys = self.keys.borrow_mut();
6141            if from < keys.len() && to < keys.len() {
6142                let key = keys.remove(from);
6143                keys.insert(to, key);
6144            }
6145        }
6146        fn commit_delete(&self, index: usize) {
6147            // The native delete affordance: drop from the local snapshot; the app's on_delete
6148            // writes the store, and the query's own delta follows as the echo.
6149            let mut keys = self.keys.borrow_mut();
6150            if index < keys.len() {
6151                keys.remove(index);
6152            }
6153        }
6154    }
6155}
6156
6157#[cfg(feature = "pieces")]
6158pub use pieces_glue::QueryConn;
6159
6160// ---------------------------------------------------------------------------
6161// Date and time codecs (feature `datetime`; docs/persistence.md)
6162// ---------------------------------------------------------------------------
6163
6164/// Column codecs for day::datetime's [`DayDate`](day_spec::controls::datetime::DayDate) and
6165/// [`DayTime`](day_spec::controls::datetime::DayTime), for `#[derive(Model)]` fields.
6166///
6167/// Canonical, what a bare field of the type stores: `DayDate` → `INTEGER` epoch days,
6168/// `DayTime` → `INTEGER` seconds-of-day: the same numeric interchange forms the pickers
6169/// already speak across native boundaries, and both sort chronologically as plain integers.
6170///
6171/// Named, picked per field with `#[model(with = …)]`: [`Iso8601`](datetime::Iso8601) stores
6172/// `TEXT` in the form `Display` writes (readable in any sqlite tool, and lexicographic order
6173/// is chronological order, ISO-8601's design goal); [`EpochSeconds`](datetime::EpochSeconds)
6174/// and [`EpochMillis`](datetime::EpochMillis) store the `INTEGER` a server that speaks Unix
6175/// time expects, midnight-of-day for a `DayDate`.
6176///
6177/// The impls live here rather than in the piece because one of the two crates has to own
6178/// them, and this is the one that depends on the other.
6179#[cfg(feature = "datetime")]
6180pub mod datetime {
6181    use crate::{ColumnValue, DbError, DbErrorKind, SqlType, Value, ValueCodec};
6182    use day_spec::controls::datetime::{DayDate, DayTime};
6183
6184    impl ColumnValue for DayDate {
6185        const SQL_TYPE: SqlType = SqlType::Integer;
6186        fn to_sqlite_value(&self) -> Value {
6187            Value::Int(self.to_epoch_days())
6188        }
6189        fn from_sqlite_value(v: Value) -> Result<Self, DbError> {
6190            Ok(DayDate::from_epoch_days(v.as_int()?))
6191        }
6192    }
6193
6194    impl ColumnValue for DayTime {
6195        const SQL_TYPE: SqlType = SqlType::Integer;
6196        fn to_sqlite_value(&self) -> Value {
6197            Value::Int(self.seconds_of_day())
6198        }
6199        fn from_sqlite_value(v: Value) -> Result<Self, DbError> {
6200            Ok(DayTime::from_seconds_of_day(v.as_int()?))
6201        }
6202    }
6203
6204    /// `TEXT` in the `Display` form: `YYYY-MM-DD` for a date, `HH:MM[:SS]` for a time.
6205    pub struct Iso8601;
6206
6207    impl ValueCodec<DayDate> for Iso8601 {
6208        const SQL_TYPE: SqlType = SqlType::Text;
6209        fn to_sqlite_value(v: &DayDate) -> Value {
6210            Value::Text(v.to_string())
6211        }
6212        fn from_sqlite_value(v: Value) -> Result<DayDate, DbError> {
6213            let s = v.as_text()?;
6214            DayDate::parse_iso(s).ok_or_else(|| {
6215                DbError::new(DbErrorKind::Decode, format!("not an ISO-8601 date: {s:?}"))
6216            })
6217        }
6218    }
6219
6220    impl ValueCodec<DayTime> for Iso8601 {
6221        const SQL_TYPE: SqlType = SqlType::Text;
6222        fn to_sqlite_value(v: &DayTime) -> Value {
6223            Value::Text(v.to_string())
6224        }
6225        fn from_sqlite_value(v: Value) -> Result<DayTime, DbError> {
6226            let s = v.as_text()?;
6227            DayTime::parse_iso(s).ok_or_else(|| {
6228                DbError::new(DbErrorKind::Decode, format!("not an ISO-8601 time: {s:?}"))
6229            })
6230        }
6231    }
6232
6233    /// `INTEGER` seconds since 1970-01-01T00:00Z; midnight of the day, for a [`DayDate`].
6234    pub struct EpochSeconds;
6235
6236    impl ValueCodec<DayDate> for EpochSeconds {
6237        const SQL_TYPE: SqlType = SqlType::Integer;
6238        fn to_sqlite_value(v: &DayDate) -> Value {
6239            Value::Int(v.to_epoch_days() * 86_400)
6240        }
6241        fn from_sqlite_value(v: Value) -> Result<DayDate, DbError> {
6242            Ok(DayDate::from_epoch_days(v.as_int()?.div_euclid(86_400)))
6243        }
6244    }
6245
6246    /// `INTEGER` milliseconds since the same epoch, for interop that expects it.
6247    pub struct EpochMillis;
6248
6249    impl ValueCodec<DayDate> for EpochMillis {
6250        const SQL_TYPE: SqlType = SqlType::Integer;
6251        fn to_sqlite_value(v: &DayDate) -> Value {
6252            Value::Int(v.to_epoch_days() * 86_400_000)
6253        }
6254        fn from_sqlite_value(v: Value) -> Result<DayDate, DbError> {
6255            Ok(DayDate::from_epoch_days(v.as_int()?.div_euclid(86_400_000)))
6256        }
6257    }
6258}
6259
6260#[cfg(all(test, feature = "driver-rusqlite"))]
6261mod eviction_tests;