Skip to main content

day_persistence/
relations.rs

1// Copyright © The Daybrite Project
2// SPDX-License-Identifier: MPL-2.0
3
4//! Relations (docs/persistence.md): `One<M>` foreign keys, `Many<M>` maintained inverses,
5//! delete rules, and the machinery that keeps them true.
6//!
7//! A to-one relation is stored in one place, the foreign-key column on the child, and the
8//! parent's `Many` side is a view over it, answered from the engine's foreign-key index and
9//! memoized per parent. Nothing is loaded at open: the first read of one parent's
10//! children is one indexed `SELECT`, remembered until a membership write invalidates it.
11//! Write `lodging.trip()` and the trip's `lodging()` read wakes; call
12//! `trip.lodging().add(id)` and it writes the lodging's foreign key through the front door,
13//! so the change announces, captures for undo, folds to one `UPDATE`, and marks any live
14//! query watching either table stale.
15//!
16//! Reads made mid-turn see the truth: the memo answers from the last flush, overlaid with
17//! this turn's unflushed dirty rows, so a child reparented a millisecond ago is under its new
18//! parent before any SQL runs.
19//!
20//! Delete rules run where the delete announces: a parent's removal cascades (recursively:
21//! the nested deletes take the same pipeline, so undoing the cascade is one unit that
22//! restores the whole subtree), nullifies (`Option<One<M>>` references clear), or denies
23//! (the checked door [`crate::ModelContainer::delete`] refuses while children remain). The
24//! generated DDL carries the matching `REFERENCES … ON DELETE …` clause,
25//! `DEFERRABLE INITIALLY DEFERRED` so within-transaction statement order never trips it. The
26//! clause also holds another process to the same rules, and is what deletes the non-resident
27//! rows a cascade reaches: the pipeline walks every child (so queries, memos and undo hear),
28//! and the engine's clause is the backstop that makes the file agree.
29
30use std::cell::{Cell, RefCell};
31use std::collections::HashMap;
32use std::marker::PhantomData;
33use std::rc::{Rc, Weak};
34
35use day_model::{ApplyField, Keyed, ModelId, Op, Store, announce, field_id};
36
37use crate::{
38    ColumnValue, ContainerInner, DbError, DbErrorKind, DirtyRow, Model, ModelContainer, Row,
39    SqlType, TableName, Value, ident, key_param, value_to_handle,
40};
41
42// ---------------------------------------------------------------------------
43// The reference types
44// ---------------------------------------------------------------------------
45
46/// A to-one reference: the foreign-key column on the child row. `One<M>` alone is a required
47/// reference (`NOT NULL`); wrap it `Option<One<M>>` for a nullable one. `Copy`, 16 bytes, and
48/// an ordinary [`ColumnValue`], so the derive treats the field as a plain column whose stored
49/// form is the target's key shape.
50pub struct One<M: ?Sized> {
51    id: Option<u64>,
52    _m: PhantomData<fn() -> M>,
53}
54
55impl<M: ?Sized> Clone for One<M> {
56    fn clone(&self) -> Self {
57        *self
58    }
59}
60impl<M: ?Sized> Copy for One<M> {}
61impl<M: ?Sized> Default for One<M> {
62    /// Unset. A required (`NOT NULL`) reference left at its default surfaces at flush time as
63    /// the constraint violation it is; set it before the turn ends.
64    fn default() -> Self {
65        One {
66            id: None,
67            _m: PhantomData,
68        }
69    }
70}
71impl<M: ?Sized> PartialEq for One<M> {
72    fn eq(&self, other: &Self) -> bool {
73        self.id == other.id
74    }
75}
76impl<M: ?Sized> Eq for One<M> {}
77impl<M: ?Sized> std::hash::Hash for One<M> {
78    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
79        self.id.hash(state);
80    }
81}
82impl<M: ?Sized> std::fmt::Debug for One<M> {
83    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
84        match self.id {
85            Some(h) => write!(f, "One({:?})", ModelId::<M>::from_handle(h)),
86            None => f.write_str("One(unset)"),
87        }
88    }
89}
90
91impl<M: ?Sized> One<M> {
92    /// A reference to `id`.
93    pub fn to(id: impl Into<ModelId<M>>) -> Self {
94        One {
95            id: Some(id.into().handle()),
96            _m: PhantomData,
97        }
98    }
99    /// The unset reference (what [`Default`] gives).
100    pub const fn none() -> Self {
101        One {
102            id: None,
103            _m: PhantomData,
104        }
105    }
106    /// The referenced id, or `None` when unset.
107    pub fn id(self) -> Option<ModelId<M>> {
108        self.id.map(ModelId::from_handle)
109    }
110    pub(crate) fn from_handle(h: u64) -> Self {
111        One {
112            id: Some(h),
113            _m: PhantomData,
114        }
115    }
116    pub(crate) fn from_handle_opt(h: Option<u64>) -> Self {
117        One {
118            id: h,
119            _m: PhantomData,
120        }
121    }
122    pub(crate) fn handle_opt(self) -> Option<u64> {
123        self.id
124    }
125}
126
127impl<M: Model> ColumnValue for One<M> {
128    /// The target's key shape: `INTEGER`, a 16-byte `BLOB`, or `TEXT`.
129    const SQL_TYPE: SqlType = M::KEY_SQL;
130    fn to_sqlite_value(&self) -> Value {
131        match self.id {
132            Some(h) => key_param(h),
133            None => Value::Null,
134        }
135    }
136    fn from_sqlite_value(v: Value) -> Result<Self, DbError> {
137        match value_to_handle(&v) {
138            Some(h) => Ok(One::from_handle(h)),
139            None => Err(DbError::new(
140                DbErrorKind::Decode,
141                format!("a stored reference would not read as a key: {v:?}"),
142            )),
143        }
144    }
145}
146
147/// Predicates over a to-one reference column: the identity and presence tests, which need
148/// nothing but the foreign-key column already stored here.
149impl<M: Model> crate::Col<One<M>> {
150    /// The reference points at exactly this row.
151    pub fn is(self, id: impl Into<ModelId<M>>) -> crate::Pred {
152        self.eq(One::<M>::from_handle(id.into().handle()))
153    }
154
155    /// The reference points at one of these rows: the set form, and what a query feeding
156    /// another query compiles to. (Named apart from the generic [`crate::Col::is_in`], which
157    /// takes `One` values; this one takes ids, which is what a caller holds.)
158    pub fn is_one_of(self, ids: impl IntoIterator<Item = impl Into<ModelId<M>>>) -> crate::Pred {
159        self.is_in(
160            ids.into_iter()
161                .map(|i| One::<M>::from_handle(i.into().handle()))
162                .collect::<Vec<_>>(),
163        )
164    }
165
166    /// The reference was never set, or a nullify rule cleared it.
167    pub fn is_unset(self) -> crate::Pred {
168        self.is_null()
169    }
170
171    /// The reference points somewhere.
172    pub fn is_set(self) -> crate::Pred {
173        self.is_not_null()
174    }
175}
176
177/// Traversing a to-one reference in a predicate: "lodgings whose trip is done". A to-one is
178/// a to-many of at most one, so the quantifier vocabulary is the same one the `Many` side
179/// uses; `any` reads as "its target matches, and there is one".
180impl<M: Model> crate::Col<One<M>> {
181    pub fn any(self, inner: crate::Pred) -> crate::Pred {
182        self.quantified(crate::Quant::Any, inner)
183    }
184    pub fn none(self, inner: crate::Pred) -> crate::Pred {
185        self.quantified(crate::Quant::None, inner)
186    }
187
188    fn quantified(self, quant: crate::Quant, inner: crate::Pred) -> crate::Pred {
189        crate::Pred::Related {
190            owner: self.owner,
191            field: self.field,
192            target: <M as Model>::TABLE,
193            quant,
194            inner: Box::new(inner),
195        }
196    }
197}
198
199/// The same, over a nullable reference.
200impl<M: Model> crate::Col<Option<One<M>>> {
201    pub fn any(self, inner: crate::Pred) -> crate::Pred {
202        self.quantified(crate::Quant::Any, inner)
203    }
204    pub fn none(self, inner: crate::Pred) -> crate::Pred {
205        self.quantified(crate::Quant::None, inner)
206    }
207
208    fn quantified(self, quant: crate::Quant, inner: crate::Pred) -> crate::Pred {
209        crate::Pred::Related {
210            owner: self.owner,
211            field: self.field,
212            target: <M as Model>::TABLE,
213            quant,
214            inner: Box::new(inner),
215        }
216    }
217}
218
219/// The same tests over a nullable reference (`Option<One<M>>`), which is what a relation with
220/// a nullify delete rule requires the child to hold.
221impl<M: Model> crate::Col<Option<One<M>>> {
222    pub fn is(self, id: impl Into<ModelId<M>>) -> crate::Pred {
223        self.eq(Some(One::<M>::from_handle(id.into().handle())))
224    }
225
226    pub fn is_one_of(self, ids: impl IntoIterator<Item = impl Into<ModelId<M>>>) -> crate::Pred {
227        self.is_in(
228            ids.into_iter()
229                .map(|i| Some(One::<M>::from_handle(i.into().handle())))
230                .collect::<Vec<_>>(),
231        )
232    }
233
234    /// The reference was never set, or a nullify rule cleared it.
235    pub fn is_unset(self) -> crate::Pred {
236        self.is_null()
237    }
238
239    /// The reference points somewhere.
240    pub fn is_set(self) -> crate::Pred {
241        self.is_not_null()
242    }
243}
244
245/// The to-many side: a marker field. It stores nothing; membership lives in the children's
246/// foreign keys (or the join table), and the field exists so the relation has an observable
247/// path of its own and a declared home for `#[model(relation(…))]`. Reads go through the
248/// generated accessor's [`RelationRef`].
249pub struct Many<M: ?Sized> {
250    _m: PhantomData<fn() -> M>,
251}
252
253impl<M: ?Sized> Clone for Many<M> {
254    fn clone(&self) -> Self {
255        *self
256    }
257}
258impl<M: ?Sized> Copy for Many<M> {}
259impl<M: ?Sized> Default for Many<M> {
260    fn default() -> Self {
261        Many { _m: PhantomData }
262    }
263}
264impl<M: ?Sized> PartialEq for Many<M> {
265    fn eq(&self, _: &Self) -> bool {
266        true
267    }
268}
269impl<M: ?Sized> Eq for Many<M> {}
270impl<M: ?Sized> std::fmt::Debug for Many<M> {
271    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
272        f.write_str("Many")
273    }
274}
275
276/// What deleting a referenced parent does. Declared per relation
277/// (`#[model(relation(delete = "…"))]`); the default is `Nullify` (also SwiftData's default
278/// for `@Relationship`).
279#[derive(Clone, Copy, PartialEq, Eq, Debug)]
280pub enum DeleteRule {
281    /// Children survive; their references clear. Needs `Option<One<M>>` on the child: a
282    /// required reference cannot hold "nothing", and wiring refuses the combination.
283    Nullify,
284    /// Children delete with the parent, recursively, through the normal pipeline, undoable
285    /// as one unit and heard by live queries.
286    Cascade,
287    /// The delete is refused while children remain, through
288    /// [`crate::ModelContainer::delete`], the checked door; a raw `restructure` bypasses the
289    /// check and the deferred SQL `RESTRICT` refuses at flush instead.
290    Deny,
291}
292
293impl DeleteRule {
294    pub(crate) fn sql(self) -> &'static str {
295        match self {
296            DeleteRule::Nullify => "SET NULL",
297            DeleteRule::Cascade => "CASCADE",
298            DeleteRule::Deny => "RESTRICT",
299        }
300    }
301}
302
303/// One declared relation, as the derive records it on the parent (`Many`) side.
304#[derive(Clone, Copy, Debug)]
305pub struct RelationDef {
306    /// The `Many` field's name on the declaring model.
307    pub field: &'static str,
308    /// The target model's table.
309    pub target_table: &'static str,
310    /// To-one/to-many: the target's foreign-key field. Join relations leave it empty.
311    pub inverse: &'static str,
312    pub delete: DeleteRule,
313    /// The target's order field (`REAL`) for an ordered to-many.
314    pub ordered: Option<&'static str>,
315    /// A join table name: the many-to-many form.
316    pub join: Option<&'static str>,
317}
318
319// ---------------------------------------------------------------------------
320// Wiring
321// ---------------------------------------------------------------------------
322
323/// What `Model::wire` receives: the container mid-open. Wiring failures collect here and
324/// fail the open with the first one, named.
325pub struct Registrar<'c> {
326    pub(crate) container: &'c ModelContainer,
327    pub(crate) error: Option<DbError>,
328}
329
330impl Registrar<'_> {
331    fn fail(&mut self, message: String) {
332        if self.error.is_none() {
333            self.error = Some(DbError::new(DbErrorKind::Schema, message));
334        }
335    }
336}
337
338/// One wired to-one/to-many relation. The typed closures are monomorphized over both model
339/// types by [`wire_to_many`], so every write goes through the front door with full type
340/// knowledge; the SQL half (table and column names) is what lazy reads and the query
341/// compiler drive.
342pub(crate) struct ToOneRel {
343    pub(crate) container: Weak<ContainerInner>,
344    pub(crate) parent_store: u64,
345    pub(crate) parent_table: &'static str,
346    pub(crate) parent_field: &'static str,
347    pub(crate) parent_key_col: &'static str,
348    pub(crate) child_store: u64,
349    pub(crate) child_table: &'static str,
350    /// `child_table` as the lazy reads below name it.
351    pub(crate) child_sql: String,
352    pub(crate) child_key_col: &'static str,
353    /// The foreign key as the child's field (the change log's language) and column (SQL's).
354    pub(crate) fk_field: &'static str,
355    pub(crate) fk_col: &'static str,
356    pub(crate) delete: DeleteRule,
357    pub(crate) ordered: Option<&'static str>,
358    pub(crate) ord_col: Option<&'static str>,
359    read_fk: Box<dyn Fn(u64) -> Option<u64>>,
360    write_fk: Box<dyn Fn(u64, Option<u64>) -> bool>,
361    delete_child: Box<dyn Fn(u64)>,
362    /// Bring children into the cache (before their fields are written, or for undo capture).
363    materialize: Materialize,
364    read_ord_cached: Box<dyn Fn(u64) -> Option<f64>>,
365    pub(crate) write_ord: Box<dyn Fn(u64, f64) -> bool>,
366    /// parent → children (relation order), filled per parent on first read.
367    memo: RefCell<HashMap<u64, Vec<u64>>>,
368    /// child → memoized parent, maintained only for children of memoized parents: the O(1)
369    /// walk-back a foreign-key rewrite needs.
370    memo_parent: RefCell<HashMap<u64, u64>>,
371}
372
373impl ToOneRel {
374    fn with_container<R>(&self, f: impl FnOnce(&ModelContainer) -> R) -> Option<R> {
375        self.container.upgrade().map(|inner| {
376            let c = ModelContainer { inner };
377            f(&c)
378        })
379    }
380
381    /// The parent's children, in relation order: the memo, or one indexed `SELECT`, overlaid
382    /// with this turn's unflushed dirty rows so mid-turn reads see the truth.
383    pub(crate) fn children_of(&self, parent: u64) -> Vec<u64> {
384        if let Some(hit) = self.memo.borrow().get(&parent) {
385            return hit.clone();
386        }
387        let Some(mut ids) = self.with_container(|c| {
388            let order = ident(self.ord_col.unwrap_or(self.child_key_col));
389            c.select_id_column(
390                &format!(
391                    "SELECT {k} FROM {t} WHERE {fk} = ? ORDER BY {order}, {k}",
392                    k = ident(self.child_key_col),
393                    t = self.child_sql,
394                    fk = ident(self.fk_col),
395                ),
396                &[key_param(parent)],
397            )
398        }) else {
399            return Vec::new();
400        };
401        self.overlay_children(parent, &mut ids);
402        let mut memo = self.memo.borrow_mut();
403        let mut back = self.memo_parent.borrow_mut();
404        for id in &ids {
405            back.insert(*id, parent);
406        }
407        memo.insert(parent, ids.clone());
408        ids
409    }
410
411    /// Correct a freshly-selected child list against this turn's unflushed edits: dirty
412    /// resident children join or leave by their current foreign key, and dirty deletes leave.
413    fn overlay_children(&self, parent: u64, ids: &mut Vec<u64>) {
414        let Some(dirty) = self.with_container(|c| c.dirty_rows_of(self.child_store)) else {
415            return;
416        };
417        for (child, state) in dirty {
418            let is_mine = state != DirtyRow::Delete && (self.read_fk)(child) == Some(parent);
419            let at = ids.iter().position(|c| *c == child);
420            match (is_mine, at) {
421                (false, Some(i)) => {
422                    ids.remove(i);
423                }
424                (true, None) => {
425                    // Place by the relation's order (the child is resident: it is dirty).
426                    let ord = (self.read_ord_cached)(child).unwrap_or(f64::INFINITY);
427                    let at = if self.ordered.is_some() {
428                        ids.iter()
429                            .position(|c| (self.read_ord_cached)(*c).unwrap_or(0.0) > ord)
430                            .unwrap_or(ids.len())
431                    } else {
432                        ids.partition_point(|c| *c < child)
433                    };
434                    ids.insert(at, child);
435                }
436                _ => {}
437            }
438        }
439    }
440
441    /// The parent this child belongs to: the memo when it knows, the child's cached
442    /// foreign key, or one point `SELECT`.
443    pub(crate) fn parent_of(&self, child: u64) -> Option<u64> {
444        if let Some(p) = self.memo_parent.borrow().get(&child) {
445            return Some(*p);
446        }
447        if let Some(p) = (self.read_fk)(child) {
448            return Some(p);
449        }
450        self.with_container(|c| {
451            c.select_id_column(
452                &format!(
453                    "SELECT {fk} FROM {t} WHERE {k} = ?",
454                    fk = ident(self.fk_col),
455                    t = self.child_sql,
456                    k = ident(self.child_key_col),
457                ),
458                &[key_param(child)],
459            )
460            .into_iter()
461            .next()
462        })
463        .flatten()
464    }
465
466    /// One child's order value: cache first (which covers every unflushed write), the file
467    /// otherwise.
468    pub(crate) fn read_order(&self, child: u64) -> f64 {
469        if let Some(v) = (self.read_ord_cached)(child) {
470            return v;
471        }
472        let Some(col) = self.ord_col else { return 0.0 };
473        self.with_container(|c| {
474            c.select_real(
475                &format!(
476                    "SELECT {} FROM {t} WHERE {k} = ?",
477                    ident(col),
478                    t = self.child_sql,
479                    k = ident(self.child_key_col),
480                ),
481                &[key_param(child)],
482            )
483        })
484        .flatten()
485        .unwrap_or(0.0)
486    }
487
488    pub(crate) fn set_fk(&self, child: u64, parent: Option<u64>) -> bool {
489        // Writes need the row resident; the announcement then routes back through
490        // `reparent`, which is where the memos and both parents' announcements happen:
491        // one path for every door.
492        (self.materialize)(&[child]);
493        (self.write_fk)(child, parent)
494    }
495
496    fn announce_parent(&self, parent: u64) {
497        announce(
498            &[self.parent_store, parent, field_id(self.parent_field)],
499            self.parent_field,
500        );
501    }
502
503    fn forget(&self, parent: u64) {
504        if let Some(children) = self.memo.borrow_mut().remove(&parent) {
505            let mut back = self.memo_parent.borrow_mut();
506            for c in children {
507                back.remove(&c);
508            }
509        }
510    }
511
512    pub(crate) fn invalidate_all(&self) {
513        self.memo.borrow_mut().clear();
514        self.memo_parent.borrow_mut().clear();
515    }
516
517    /// A child arrived (an insert, an undo re-insert, an external merge).
518    pub(crate) fn child_added(&self, child: u64) {
519        if let Some(p) = (self.read_fk)(child) {
520            self.forget(p);
521            self.announce_parent(p);
522        }
523    }
524
525    /// A child left. The memo knows its parent when the parent was ever read; otherwise the
526    /// file still holds the row until the flush, so one point `SELECT` answers.
527    pub(crate) fn child_removed(&self, child: u64) {
528        let parent = self
529            .memo_parent
530            .borrow()
531            .get(&child)
532            .copied()
533            .or_else(|| self.parent_of(child));
534        if let Some(p) = parent {
535            self.forget(p);
536            self.announce_parent(p);
537        }
538    }
539
540    /// The child's foreign key was rewritten: both parents' views move. The new parent is the
541    /// child's own field; the old one is the memo when a reader ever established it, the
542    /// file otherwise (the un-flushed value is exactly the pre-write one). A reader whose
543    /// memo was current re-establishes it on its own re-read, so repeated reparents in one
544    /// turn stay coherent for anything watching.
545    pub(crate) fn reparent(&self, child: u64) {
546        let new = (self.read_fk)(child);
547        let old = self
548            .memo_parent
549            .borrow()
550            .get(&child)
551            .copied()
552            .or_else(|| self.former_parent_file(child));
553        if let Some(p) = old {
554            self.forget(p);
555        }
556        if let Some(p) = new
557            && Some(p) != old
558        {
559            self.forget(p);
560        }
561        self.announce_parent_set(old, new);
562    }
563
564    /// Announce each distinct parent in the pair.
565    fn announce_parent_set(&self, a: Option<u64>, b: Option<u64>) {
566        if let Some(p) = a {
567            self.announce_parent(p);
568        }
569        if let Some(p) = b
570            && Some(p) != a
571        {
572            self.announce_parent(p);
573        }
574    }
575
576    /// The parent the file records for this child: the pre-flush truth, bypassing both the
577    /// memo and the (already rewritten) cached row.
578    fn former_parent_file(&self, child: u64) -> Option<u64> {
579        self.with_container(|c| {
580            c.select_id_column(
581                &format!(
582                    "SELECT {fk} FROM {t} WHERE {k} = ?",
583                    fk = ident(self.fk_col),
584                    t = self.child_sql,
585                    k = ident(self.child_key_col),
586                ),
587                &[key_param(child)],
588            )
589            .into_iter()
590            .next()
591        })
592        .flatten()
593    }
594
595    /// The child's order field moved: its parent's view reorders.
596    pub(crate) fn order_changed(&self, child: u64) {
597        if let Some(p) = self.parent_of(child) {
598            self.forget(p);
599            self.announce_parent(p);
600        }
601    }
602
603    pub(crate) fn parent_deleted(&self, container: &ModelContainer, parent: u64) {
604        let children = self.children_of(parent);
605        self.forget(parent);
606        if children.is_empty() {
607            return;
608        }
609        match self.delete {
610            DeleteRule::Cascade => {
611                // Each nested delete takes the whole pipeline (announce, undo capture,
612                // dirty, query staleness) and, for a self-referential tree, recurses
613                // through this same method one level down. When an undo stack stands by,
614                // the rows materialize first so their deletes carry what inversion needs;
615                // without one the deletes are value-free and the fold batches them.
616                if day_model::record_capture_active() {
617                    (self.materialize)(&children);
618                }
619                for child in children {
620                    (self.delete_child)(child);
621                }
622            }
623            DeleteRule::Nullify => {
624                (self.materialize)(&children);
625                for child in children {
626                    (self.write_fk)(child, None);
627                }
628            }
629            DeleteRule::Deny => {
630                // Too late to refuse: the row is gone from the store. The checked door
631                // (`ModelContainer::delete`) refuses before; a bypass surfaces here and at
632                // the deferred SQL RESTRICT.
633                container.inner.error.set(Some(format!(
634                    "deny: `{}` was deleted while `{}` rows still reference it — use \
635                     ModelContainer::delete for deny relations",
636                    self.parent_field, self.fk_field
637                )));
638            }
639        }
640    }
641}
642
643/// Read a child's foreign key, whichever nullability the field declared.
644fn fk_of<P: Model, C: Model>(c: &C, inverse: &str) -> Option<u64> {
645    let any = ApplyField::read_field(c, inverse)?;
646    if let Some(one) = any.downcast_ref::<One<P>>() {
647        return one.handle_opt();
648    }
649    if let Some(opt) = any.downcast_ref::<Option<One<P>>>() {
650        return opt.and_then(|o| o.handle_opt());
651    }
652    None
653}
654
655/// Wire one `Many` declaration; called from the derive-generated `Model::wire`.
656pub fn wire_to_many<P: Model, C: Model>(
657    reg: &mut Registrar<'_>,
658    field: &'static str,
659    inverse: &'static str,
660    delete: DeleteRule,
661    ordered: Option<&'static str>,
662) {
663    let container = reg.container.clone();
664    let Some(parent_store) = container.try_cache::<P>() else {
665        reg.fail(format!(
666            "relation `{}.{field}` wired before `{}` attached",
667            P::TABLE,
668            P::TABLE
669        ));
670        return;
671    };
672    let Some(child_store) = container.try_cache::<C>() else {
673        reg.fail(format!(
674            "relation `{}.{field}` targets `{}`, which is not in this container's schema!",
675            P::TABLE,
676            C::TABLE
677        ));
678        return;
679    };
680    let Some(col) = C::COLUMNS.iter().find(|c| c.field == inverse) else {
681        reg.fail(format!(
682            "relation `{}.{field}` names inverse `{inverse}`, which is not a persisted \
683             field of `{}`",
684            P::TABLE,
685            C::TABLE
686        ));
687        return;
688    };
689    if delete == DeleteRule::Nullify && col.not_null {
690        reg.fail(format!(
691            "relation `{}.{field}` is delete = \"nullify\", but `{}.{inverse}` is a required \
692             `One<…>` — make it `Option<One<…>>`, or use cascade/deny",
693            P::TABLE,
694            C::TABLE
695        ));
696        return;
697    }
698    let mut ord_col = None;
699    if let Some(ord) = ordered {
700        match C::COLUMNS
701            .iter()
702            .find(|c| c.field == ord && c.sql == SqlType::Real)
703        {
704            Some(c) => ord_col = Some(c.name),
705            None => {
706                reg.fail(format!(
707                    "relation `{}.{field}` is ordered by `{ord}`, which is not a REAL (`f64`) \
708                     field of `{}` — the order column is a real, visible field of the child",
709                    P::TABLE,
710                    C::TABLE
711                ));
712                return;
713            }
714        }
715    }
716
717    let read_fk = Box::new(move |h: u64| {
718        child_store.with_untracked(|k| k.get(h).and_then(|c| fk_of::<P, C>(c, inverse)))
719    });
720    let write_fk = Box::new(move |h: u64, parent: Option<u64>| {
721        if child_store.write_field(h, inverse, One::<P>::from_handle_opt(parent)) {
722            return true;
723        }
724        let opt: Option<One<P>> = parent.map(One::<P>::from_handle);
725        child_store.write_field(h, inverse, opt)
726    });
727    let delete_child = Box::new(move |h: u64| {
728        child_store.restructure("cascade", Op::Delete, h, |k| {
729            k.remove(h);
730        });
731    });
732    let mat_container = container.clone();
733    let materialize = Box::new(move |keys: &[u64]| {
734        let _ = mat_container.ensure_resident::<C>(keys);
735    });
736    let read_ord_cached: Box<dyn Fn(u64) -> Option<f64>> = match ordered {
737        Some(ord) => Box::new(move |h| {
738            child_store.with_untracked(|k| {
739                k.get(h)
740                    .and_then(|c| ApplyField::read_field(c, ord))
741                    .and_then(|v| v.downcast_ref::<f64>().copied())
742            })
743        }),
744        None => Box::new(|_| None),
745    };
746    let write_ord: Box<dyn Fn(u64, f64) -> bool> = match ordered {
747        Some(ord) => Box::new(move |h, v| child_store.write_field(h, ord, v)),
748        None => Box::new(|_, _| false),
749    };
750
751    let rel = Rc::new(ToOneRel {
752        container: Rc::downgrade(&container.inner),
753        parent_store: parent_store.store_id(),
754        parent_table: P::TABLE,
755        parent_field: field,
756        parent_key_col: P::KEY,
757        child_store: child_store.store_id(),
758        child_table: C::TABLE,
759        child_sql: TableName::of::<C>().sql(),
760        child_key_col: C::KEY,
761        fk_field: inverse,
762        fk_col: col.name,
763        delete,
764        ordered,
765        ord_col,
766        read_fk,
767        write_fk,
768        delete_child,
769        materialize,
770        read_ord_cached,
771        write_ord,
772        memo: RefCell::new(HashMap::new()),
773        memo_parent: RefCell::new(HashMap::new()),
774    });
775
776    container.inner.relations.borrow_mut().push(rel);
777}
778
779// ---------------------------------------------------------------------------
780// Many-to-many: the join table
781// ---------------------------------------------------------------------------
782
783/// One membership row of a generated join table. Its key is the pair, which is what makes a
784/// membership addressable, undoable and mergeable by the same machinery every other row uses,
785/// with no second vocabulary. The store over these rows is a cache like every other: only
786/// memberships this process touched are resident.
787#[derive(Clone, Default, PartialEq, Debug)]
788pub(crate) struct JoinRow {
789    pub(crate) parent: u64,
790    pub(crate) child: u64,
791    /// The ordered form's position; 0.0 when the relation is unordered.
792    pub(crate) position: f64,
793}
794
795impl day_model::Identified for JoinRow {
796    fn key(&self) -> day_model::Key {
797        day_model::Key::Pair(self.parent, self.child)
798    }
799}
800
801impl ApplyField for JoinRow {
802    fn apply_field(&mut self, label: &str, value: &dyn std::any::Any) -> bool {
803        match (label, value.downcast_ref::<f64>()) {
804            ("position", Some(v)) => {
805                self.position = *v;
806                true
807            }
808            _ => false,
809        }
810    }
811    fn read_field(&self, label: &str) -> Option<Rc<dyn std::any::Any>> {
812        match label {
813            "position" => Some(Rc::new(self.position)),
814            _ => None,
815        }
816    }
817}
818
819/// A wired many-to-many: one per join table, whichever side (or both) declared it.
820///
821/// Membership lives in the join table; both directions answer from its indexes, memoized per
822/// row. When both models declare the relation over the same `join = "…"` table, the second
823/// declaration attaches as this relation's B side rather than opening a second store; two
824/// stores over one table would double every write and disagree about column order.
825pub(crate) struct JoinRel {
826    pub(crate) container: Weak<ContainerInner>,
827    pub(crate) join_table: &'static str,
828    /// `join_table` as the lazy reads below name it.
829    pub(crate) join_sql: String,
830    pub(crate) parent_col: &'static str,
831    pub(crate) child_col: &'static str,
832    /// The side that wired first: its rows are the join row's `parent`.
833    pub(crate) a_store: u64,
834    pub(crate) a_table: &'static str,
835    pub(crate) a_field: &'static str,
836    pub(crate) a_key_col: &'static str,
837    pub(crate) a_delete: DeleteRule,
838    /// The other side. `b_field` is set only if that model declared the relation too, and
839    /// is held in a `Cell` because the second declaration fills it in during wiring while
840    /// the first declaration's `Rc` is already held.
841    pub(crate) b_store: u64,
842    pub(crate) b_table: &'static str,
843    pub(crate) b_key_col: &'static str,
844    pub(crate) b_field: Cell<Option<&'static str>>,
845    pub(crate) b_delete: Cell<DeleteRule>,
846    pub(crate) join_store: u64,
847    /// Order is the A side's: a membership's position places a B row within one A row.
848    pub(crate) ordered: bool,
849    store: Store<Keyed<JoinRow>>,
850    delete_a: Box<dyn Fn(u64)>,
851    delete_b: Box<dyn Fn(u64)>,
852    /// A-side row → its members, and B-side row → its holders, filled on first read.
853    memo_fwd: RefCell<HashMap<u64, Vec<u64>>>,
854    memo_rev: RefCell<HashMap<u64, Vec<u64>>>,
855}
856
857impl JoinRel {
858    fn with_container<R>(&self, f: impl FnOnce(&ModelContainer) -> R) -> Option<R> {
859        self.container.upgrade().map(|inner| {
860            let c = ModelContainer { inner };
861            f(&c)
862        })
863    }
864
865    /// The members `key` holds, read from whichever side `forward` names: A→B forward, B→A
866    /// reverse. One indexed `SELECT` on first read, memoized, overlaid with this turn's
867    /// unflushed links and unlinks.
868    pub(crate) fn members_of(&self, key: u64, forward: bool) -> Vec<u64> {
869        {
870            let memo = if forward {
871                &self.memo_fwd
872            } else {
873                &self.memo_rev
874            };
875            if let Some(hit) = memo.borrow().get(&key) {
876                return hit.clone();
877            }
878        }
879        let (own_col, other_col) = if forward {
880            (self.parent_col, self.child_col)
881        } else {
882            (self.child_col, self.parent_col)
883        };
884        let (other_col, own_col) = (ident(other_col), ident(own_col));
885        let order = if self.ordered && forward {
886            format!("position, {other_col}")
887        } else {
888            other_col.clone()
889        };
890        let Some(mut ids) = self.with_container(|c| {
891            c.select_id_column(
892                &format!(
893                    "SELECT {other_col} FROM {t} WHERE {own_col} = ? ORDER BY {order}",
894                    t = self.join_sql,
895                ),
896                &[key_param(key)],
897            )
898        }) else {
899            return Vec::new();
900        };
901        self.overlay_members(key, forward, &mut ids);
902        let memo = if forward {
903            &self.memo_fwd
904        } else {
905            &self.memo_rev
906        };
907        memo.borrow_mut().insert(key, ids.clone());
908        ids
909    }
910
911    /// Correct a freshly-selected member list against this turn's unflushed link/unlink rows.
912    fn overlay_members(&self, key: u64, forward: bool, ids: &mut Vec<u64>) {
913        let Some(dirty) = self.with_container(|c| c.dirty_rows_of(self.join_store)) else {
914            return;
915        };
916        for (handle, state) in dirty {
917            let Some(day_model::Key::Pair(p, c)) = day_model::Key::of_handle(handle) else {
918                continue;
919            };
920            let (own, other) = if forward { (p, c) } else { (c, p) };
921            if own != key {
922                continue;
923            }
924            let at = ids.iter().position(|m| *m == other);
925            match (state != DirtyRow::Delete, at) {
926                (false, Some(i)) => {
927                    ids.remove(i);
928                }
929                (true, None) => {
930                    if self.ordered && forward {
931                        let pos = self.position_of(p, c);
932                        let at = ids
933                            .iter()
934                            .position(|m| self.position_of(key, *m) > pos)
935                            .unwrap_or(ids.len());
936                        ids.insert(at, other);
937                    } else {
938                        let at = ids.partition_point(|m| *m < other);
939                        ids.insert(at, other);
940                    }
941                }
942                _ => {}
943            }
944        }
945    }
946
947    /// The rows on the other side that hold `key`: the join's back-resolution.
948    pub(crate) fn holders_of(&self, key: u64, forward: bool) -> Vec<u64> {
949        // Looking back from a B row means asking the reverse direction, and vice versa.
950        self.members_of(key, !forward)
951    }
952
953    pub(crate) fn position_of(&self, parent: u64, child: u64) -> f64 {
954        let cached = self.store.with_untracked(|k| {
955            k.get(day_model::Key::Pair(parent, child).handle())
956                .map(|r| r.position)
957        });
958        if let Some(p) = cached {
959            return p;
960        }
961        if !self.ordered {
962            return 0.0;
963        }
964        self.with_container(|c| {
965            c.select_real(
966                &format!(
967                    "SELECT position FROM {t} WHERE {pc} = ? AND {cc} = ?",
968                    t = self.join_sql,
969                    pc = ident(self.parent_col),
970                    cc = ident(self.child_col),
971                ),
972                &[key_param(parent), key_param(child)],
973            )
974        })
975        .flatten()
976        .unwrap_or(0.0)
977    }
978
979    /// Whether the pair is currently a membership: the cache, the dirty set, or the file.
980    fn is_member(&self, parent: u64, child: u64) -> bool {
981        let handle = day_model::Key::Pair(parent, child).handle();
982        if let Some(state) = self.with_container(|c| c.dirty_state_of(self.join_store, handle))
983            && let Some(state) = state
984        {
985            return state != DirtyRow::Delete;
986        }
987        if self.store.with_untracked(|k| k.get(handle).is_some()) {
988            return true;
989        }
990        self.with_container(|c| {
991            !c.select_id_column(
992                &format!(
993                    "SELECT 1 FROM {t} WHERE {pc} = ? AND {cc} = ?",
994                    t = self.join_sql,
995                    pc = ident(self.parent_col),
996                    cc = ident(self.child_col),
997                ),
998                &[key_param(parent), key_param(child)],
999            )
1000            .is_empty()
1001        })
1002        .unwrap_or(false)
1003    }
1004
1005    /// Wake both sides' readers: a membership change moves `a.field()` and `b.field()` alike.
1006    fn announce_pair(&self, parent: u64, child: u64) {
1007        announce(
1008            &[self.a_store, parent, field_id(self.a_field)],
1009            self.a_field,
1010        );
1011        if let Some(bf) = self.b_field.get() {
1012            announce(&[self.b_store, child, field_id(bf)], bf);
1013        }
1014    }
1015
1016    fn forget_pair(&self, parent: u64, child: u64) {
1017        self.memo_fwd.borrow_mut().remove(&parent);
1018        self.memo_rev.borrow_mut().remove(&child);
1019    }
1020
1021    pub(crate) fn invalidate_all(&self) {
1022        self.memo_fwd.borrow_mut().clear();
1023        self.memo_rev.borrow_mut().clear();
1024    }
1025
1026    /// A join row arrived (an `add`, an undo's re-insert, an external merge).
1027    pub(crate) fn row_added(&self, handle: u64) {
1028        if let Some(day_model::Key::Pair(p, c)) = day_model::Key::of_handle(handle) {
1029            self.forget_pair(p, c);
1030            self.announce_pair(p, c);
1031        }
1032    }
1033
1034    pub(crate) fn row_removed(&self, handle: u64) {
1035        if let Some(day_model::Key::Pair(p, c)) = day_model::Key::of_handle(handle) {
1036            self.forget_pair(p, c);
1037            self.announce_pair(p, c);
1038        }
1039    }
1040
1041    /// A membership's position moved: reposition and wake both sides.
1042    pub(crate) fn row_moved(&self, handle: u64) {
1043        if let Some(day_model::Key::Pair(p, c)) = day_model::Key::of_handle(handle) {
1044            self.forget_pair(p, c);
1045            self.announce_pair(p, c);
1046        }
1047    }
1048
1049    /// Either side's row was deleted: its memberships go with it, and under that side's own
1050    /// cascade rule so do the rows across the join that nobody else still holds.
1051    pub(crate) fn side_deleted(&self, is_a: bool, key: u64) {
1052        let others = self.members_of(key, is_a);
1053        if others.is_empty() {
1054            return;
1055        }
1056        let capture = day_model::record_capture_active();
1057        for other in &others {
1058            let (p, c) = if is_a { (key, *other) } else { (*other, key) };
1059            let handle = day_model::Key::Pair(p, c).handle();
1060            if capture && self.store.with_untracked(|k| k.get(handle).is_none()) {
1061                // Materialize the membership so its delete carries what undo inversion
1062                // needs: the pair is known; only an ordered position needs the file.
1063                let position = self.position_of(p, c);
1064                self.store.populate(vec![JoinRow {
1065                    parent: p,
1066                    child: c,
1067                    position,
1068                }]);
1069            }
1070            self.store.restructure("unlink", Op::Delete, handle, |k| {
1071                k.remove(handle);
1072            });
1073        }
1074        let rule = if is_a {
1075            self.a_delete
1076        } else {
1077            self.b_delete.get()
1078        };
1079        if rule == DeleteRule::Cascade {
1080            // Cascade across a join takes the rows this one held, but only those no other
1081            // row still holds, or deleting one album would take a shared photo with it.
1082            // (`forward` here is the deleted side's perspective: the counterpart's holders
1083            // are read from the opposite index.)
1084            for other in others {
1085                let holders = self.holders_of(other, is_a);
1086                let still_held = holders.iter().any(|h| *h != key);
1087                if !still_held {
1088                    if is_a {
1089                        (self.delete_b)(other);
1090                    } else {
1091                        (self.delete_a)(other);
1092                    }
1093                }
1094            }
1095        }
1096    }
1097
1098    fn link(&self, parent: u64, child: u64, position: f64) -> bool {
1099        if self.is_member(parent, child) {
1100            return false; // already a member; membership is a set
1101        }
1102        let handle = day_model::Key::Pair(parent, child).handle();
1103        self.store.restructure("link", Op::Insert, handle, |k| {
1104            k.push(JoinRow {
1105                parent,
1106                child,
1107                position,
1108            })
1109        });
1110        true
1111    }
1112
1113    fn unlink(&self, parent: u64, child: u64) -> bool {
1114        if !self.is_member(parent, child) {
1115            return false;
1116        }
1117        let handle = day_model::Key::Pair(parent, child).handle();
1118        if day_model::record_capture_active()
1119            && self.store.with_untracked(|k| k.get(handle).is_none())
1120        {
1121            let position = self.position_of(parent, child);
1122            self.store.populate(vec![JoinRow {
1123                parent,
1124                child,
1125                position,
1126            }]);
1127        }
1128        self.store.restructure("unlink", Op::Delete, handle, |k| {
1129            k.remove(handle);
1130        });
1131        true
1132    }
1133}
1134
1135/// Wire one many-to-many; called from the derive-generated `Model::wire`.
1136pub fn wire_join<P: Model, C: Model>(
1137    reg: &mut Registrar<'_>,
1138    field: &'static str,
1139    join_table: &'static str,
1140    ordered: Option<&'static str>,
1141    delete: DeleteRule,
1142) {
1143    let container = reg.container.clone();
1144    let (Some(parent_store), Some(child_store)) =
1145        (container.try_cache::<P>(), container.try_cache::<C>())
1146    else {
1147        reg.fail(format!(
1148            "relation `{}.{field}` targets `{}`, which is not in this container's schema!",
1149            P::TABLE,
1150            C::TABLE
1151        ));
1152        return;
1153    };
1154
1155    // The other side already wired this table: attach as its B side (one relation, one
1156    // store, both directions) rather than opening a second store over the same rows.
1157    {
1158        let joins = container.inner.joins.borrow();
1159        if let Some(existing) = joins.iter().find(|j| j.join_table == join_table) {
1160            let ok = existing.a_store == child_store.store_id()
1161                && existing.b_store == parent_store.store_id();
1162            if !ok {
1163                let msg = format!(
1164                    "join table `{join_table}` is declared by `{}.{field}` and by another \
1165                     relation over different models — a join table belongs to exactly one pair",
1166                    P::TABLE
1167                );
1168                drop(joins);
1169                reg.fail(msg);
1170                return;
1171            }
1172            if existing.b_field.get().is_some() {
1173                let msg = format!(
1174                    "join table `{join_table}` is declared twice on `{}` — one field per side",
1175                    P::TABLE
1176                );
1177                drop(joins);
1178                reg.fail(msg);
1179                return;
1180            }
1181            if ordered.is_some() && !existing.ordered {
1182                let msg = format!(
1183                    "relation `{}.{field}` asks for order, but `{join_table}`'s other side \
1184                     declared it unordered — a membership has ONE position, so order is \
1185                     declared on one side only",
1186                    P::TABLE
1187                );
1188                drop(joins);
1189                reg.fail(msg);
1190                return;
1191            }
1192            existing.b_field.set(Some(field));
1193            existing.b_delete.set(delete);
1194            return;
1195        }
1196    }
1197
1198    if ordered.is_some_and(|o| o != "position") {
1199        reg.fail(format!(
1200            "relation `{}.{field}` is a join relation: its order lives on the join row, so \
1201             `ordered` takes no field name (a child can sit at different positions under \
1202             different parents)",
1203            P::TABLE
1204        ));
1205        return;
1206    }
1207    let ordered = ordered.is_some();
1208
1209    // Column names are derived and documented: the singular of each table, `_id`-suffixed.
1210    let parent_col: &'static str = Box::leak(format!("{}_id", singular(P::TABLE)).into_boxed_str());
1211    let child_col: &'static str = Box::leak(format!("{}_id", singular(C::TABLE)).into_boxed_str());
1212    if parent_col == child_col {
1213        reg.fail(format!(
1214            "relation `{}.{field}`: a self-join needs distinct column names, which the \
1215             derived `{parent_col}` pair cannot give",
1216            P::TABLE
1217        ));
1218        return;
1219    }
1220
1221    if let Err(e) =
1222        container.ensure_join_table::<P, C>(join_table, parent_col, child_col, ordered, delete)
1223    {
1224        reg.error.get_or_insert(e);
1225        return;
1226    }
1227
1228    // The membership cache starts empty; memberships fault through the memos on read and
1229    // enter through link/unlink on write; the file is never read whole.
1230    let store = Store::new(Keyed::new(Vec::new()));
1231    let delete_a = Box::new(move |h: u64| {
1232        parent_store.restructure("cascade", Op::Delete, h, |k| {
1233            k.remove(h);
1234        });
1235    });
1236    let delete_b = Box::new(move |h: u64| {
1237        child_store.restructure("cascade", Op::Delete, h, |k| {
1238            k.remove(h);
1239        });
1240    });
1241    let rel = Rc::new(JoinRel {
1242        container: Rc::downgrade(&container.inner),
1243        join_table,
1244        join_sql: ident(join_table),
1245        parent_col,
1246        child_col,
1247        a_store: parent_store.store_id(),
1248        a_table: P::TABLE,
1249        a_field: field,
1250        a_key_col: P::KEY,
1251        a_delete: delete,
1252        b_store: child_store.store_id(),
1253        b_table: C::TABLE,
1254        b_key_col: C::KEY,
1255        b_field: Cell::new(None),
1256        b_delete: Cell::new(DeleteRule::Nullify),
1257        join_store: store.store_id(),
1258        ordered,
1259        store,
1260        delete_a,
1261        delete_b,
1262        memo_fwd: RefCell::new(HashMap::new()),
1263        memo_rev: RefCell::new(HashMap::new()),
1264    });
1265
1266    container.register_join_hooks(join_table, parent_col, child_col, ordered, store);
1267    container.inner.joins.borrow_mut().push(rel);
1268}
1269
1270/// `trips` → `trip`, `boxes` → `box`, `categories` → `category`: the join column's stem.
1271fn singular(table: &str) -> String {
1272    if let Some(stem) = table.strip_suffix("ies") {
1273        return format!("{stem}y");
1274    }
1275    for suffix in ["ses", "xes", "zes", "ches", "shes"] {
1276        if let Some(stem) = table.strip_suffix(suffix) {
1277            return format!("{stem}{}", &suffix[..suffix.len() - 2]);
1278        }
1279    }
1280    table.strip_suffix('s').unwrap_or(table).to_string()
1281}
1282
1283// ---------------------------------------------------------------------------
1284// The accessor surface
1285// ---------------------------------------------------------------------------
1286
1287day_reactive::tls_group! {
1288    /// Every open container, so a `RelationRef` (which holds only a Field) can find the
1289    /// relation its parent store belongs to. Weak: dropping the container is the removal.
1290    static CONTAINERS: RefCell<Vec<Weak<ContainerInner>>> = const { RefCell::new(Vec::new()) };
1291
1292}
1293
1294pub(crate) fn register_container(inner: &Rc<ContainerInner>) {
1295    CONTAINERS.with(|c| {
1296        let mut v = c.borrow_mut();
1297        v.retain(|w| w.strong_count() > 0);
1298        v.push(Rc::downgrade(inner));
1299    });
1300}
1301
1302/// A resolved relation, either shape, and for a join, which end asked (`forward` is the A
1303/// side, the one whose declaration created the table).
1304enum Wired {
1305    ToOne(Rc<ToOneRel>),
1306    Join(Rc<JoinRel>, bool),
1307}
1308
1309fn find_relation(parent_store: u64, field: &str) -> Option<Wired> {
1310    CONTAINERS.with(|c| {
1311        c.borrow()
1312            .iter()
1313            .filter_map(Weak::upgrade)
1314            .find_map(|inner| {
1315                if let Some(r) = inner
1316                    .relations
1317                    .borrow()
1318                    .iter()
1319                    .find(|r| r.parent_store == parent_store && r.parent_field == field)
1320                {
1321                    return Some(Wired::ToOne(r.clone()));
1322                }
1323                inner.joins.borrow().iter().find_map(|r| {
1324                    if r.a_store == parent_store && r.a_field == field {
1325                        Some(Wired::Join(r.clone(), true))
1326                    } else if r.b_store == parent_store && r.b_field.get() == Some(field) {
1327                        Some(Wired::Join(r.clone(), false))
1328                    } else {
1329                        None
1330                    }
1331                })
1332            })
1333    })
1334}
1335
1336/// Bring a set of rows into the cache: what a relation write does before it writes.
1337type Materialize = Box<dyn Fn(&[u64])>;
1338
1339/// Read one row's order value by handle; write it back. The pair is what an ordered relation
1340/// needs, whichever shape holds the order (a child's field, or a membership's position).
1341type ReadOrder = Box<dyn Fn(u64) -> f64>;
1342type WriteOrder = Box<dyn Fn(u64, f64) -> bool>;
1343
1344/// What placing one row inside an ordered relation needs, resolved from whichever shape holds
1345/// the order.
1346struct Placement {
1347    ordered: bool,
1348    read_ord: ReadOrder,
1349    write_ord: WriteOrder,
1350    is_member: bool,
1351}
1352
1353/// What the generated accessor for a `Many` field returns: the relation, addressed from one
1354/// parent. Reads are tracked through the parent's field path (membership changes wake
1355/// exactly the readers of this parent's relation), and writes go through the children's
1356/// foreign keys, where membership is stored.
1357pub struct RelationRef<S: Copy + 'static, P: 'static, T: 'static> {
1358    field: day_model::Field<S, P, Many<T>>,
1359}
1360
1361impl<S: Copy + 'static, P: 'static, T: 'static> Clone for RelationRef<S, P, T> {
1362    fn clone(&self) -> Self {
1363        *self
1364    }
1365}
1366impl<S: Copy + 'static, P: 'static, T: 'static> Copy for RelationRef<S, P, T> {}
1367
1368impl<S: day_model::Source<P>, P: 'static, T: 'static> RelationRef<S, P, T> {
1369    pub fn new(field: day_model::Field<S, P, Many<T>>) -> Self {
1370        RelationRef { field }
1371    }
1372
1373    fn resolve(&self) -> Option<(Wired, u64)> {
1374        let mut parts = Vec::new();
1375        day_model::Source::components(self.field, &mut parts);
1376        if parts.len() < 2 {
1377            return None;
1378        }
1379        find_relation(parts[0], self.field.label()).map(|r| (r, parts[1]))
1380    }
1381
1382    /// The children this parent holds, in relation order.
1383    fn members(&self) -> Vec<u64> {
1384        match self.resolve() {
1385            Some((Wired::ToOne(r), p)) => r.children_of(p),
1386            Some((Wired::Join(r, forward), p)) => r.members_of(p, forward),
1387            None => Vec::new(),
1388        }
1389    }
1390
1391    /// The children's ids, in relation order, tracked: the caller re-runs when membership
1392    /// (or order) changes, and not when a child's other fields do.
1393    pub fn ids(&self) -> Vec<ModelId<T>> {
1394        self.field.with(|_| ());
1395        self.members()
1396            .into_iter()
1397            .map(ModelId::from_handle)
1398            .collect()
1399    }
1400
1401    /// The count, tracked like [`RelationRef::ids`].
1402    pub fn count(&self) -> usize {
1403        self.field.with(|_| ());
1404        self.members().len()
1405    }
1406
1407    pub fn is_empty(&self) -> bool {
1408        self.count() == 0
1409    }
1410
1411    /// Tracked membership test.
1412    pub fn contains(&self, id: impl Into<ModelId<T>>) -> bool {
1413        let h = id.into().handle();
1414        self.field.with(|_| ());
1415        self.members().contains(&h)
1416    }
1417
1418    /// Take `child` into this relation by writing its foreign key (reparenting it away from
1419    /// any previous parent, whose readers wake too). On an ordered relation the child lands
1420    /// last, its order field written past the current end. Returns false when the relation
1421    /// is unwired or the child is gone.
1422    pub fn add(&self, child: impl Into<ModelId<T>>) -> bool {
1423        let h = child.into().handle();
1424        match self.resolve() {
1425            Some((Wired::ToOne(r), parent)) => {
1426                if !r.set_fk(h, Some(parent)) {
1427                    return false;
1428                }
1429                if r.ordered.is_some() {
1430                    let last = r
1431                        .children_of(parent)
1432                        .iter()
1433                        .filter(|c| **c != h)
1434                        .map(|c| r.read_order(*c))
1435                        .fold(f64::NEG_INFINITY, f64::max);
1436                    let next = if last.is_finite() { last + 1.0 } else { 1.0 };
1437                    (r.write_ord)(h, next);
1438                }
1439                true
1440            }
1441            Some((Wired::Join(r, forward), key)) => {
1442                // Whichever end asked, the stored pair is always (A, B).
1443                let (a, b) = if forward { (key, h) } else { (h, key) };
1444                let next = if r.ordered {
1445                    let last = r
1446                        .members_of(a, true)
1447                        .iter()
1448                        .map(|c| r.position_of(a, *c))
1449                        .fold(f64::NEG_INFINITY, f64::max);
1450                    if last.is_finite() { last + 1.0 } else { 1.0 }
1451                } else {
1452                    0.0
1453                };
1454                r.link(a, b, next)
1455            }
1456            None => false,
1457        }
1458    }
1459
1460    /// Ordered relations: place `child` at `index` among the current children, normally one
1461    /// write of the child's order field (fractional keying), plus the adopt when it was not
1462    /// yet this parent's. When the gap between neighbors has bisected away, the siblings
1463    /// rebalance to whole numbers first (O(n), rare, and every write still takes the front
1464    /// door). Returns false on an unordered or unwired relation.
1465    pub fn insert_at(&self, child: impl Into<ModelId<T>>, index: usize) -> bool {
1466        let h = child.into().handle();
1467        let Some((wired, parent)) = self.resolve() else {
1468            return false;
1469        };
1470        // Read the neighbors' order values, place between them, and write one row, whichever
1471        // shape holds the order (the child's field, or the membership's position).
1472        let Placement {
1473            ordered,
1474            read_ord,
1475            write_ord,
1476            is_member,
1477        } = match &wired {
1478            Wired::ToOne(r) => {
1479                let (r1, r2) = (r.clone(), r.clone());
1480                Placement {
1481                    ordered: r.ordered.is_some(),
1482                    read_ord: Box::new(move |c| r1.read_order(c)),
1483                    write_ord: Box::new(move |c, v| {
1484                        (r2.materialize)(&[c]);
1485                        (r2.write_ord)(c, v)
1486                    }),
1487                    is_member: r.parent_of(h) == Some(parent) && {
1488                        // `parent_of` answers from the file too; membership here means the
1489                        // Current truth, which children_of's overlay establishes.
1490                        r.children_of(parent).contains(&h)
1491                    },
1492                }
1493            }
1494            Wired::Join(r, forward) => {
1495                let (r1, r2) = (r.clone(), r.clone());
1496                Placement {
1497                    // Order belongs to the A side: a membership's position places a B row
1498                    // within one A row, so the reverse view has no order to write.
1499                    ordered: r.ordered && *forward,
1500                    read_ord: Box::new(move |c| r1.position_of(parent, c)),
1501                    write_ord: Box::new(move |c, v| {
1502                        let handle = day_model::Key::Pair(parent, c).handle();
1503                        if r2.store.with_untracked(|k| k.get(handle).is_none()) {
1504                            let position = r2.position_of(parent, c);
1505                            r2.store.populate(vec![JoinRow {
1506                                parent,
1507                                child: c,
1508                                position,
1509                            }]);
1510                        }
1511                        r2.store.write_field(handle, "position", v)
1512                    }),
1513                    is_member: r.members_of(parent, *forward).contains(&h),
1514                }
1515            }
1516        };
1517        if !ordered {
1518            return false;
1519        }
1520        if !is_member && !self.add(ModelId::<T>::from_handle(h)) {
1521            return false;
1522        }
1523        let siblings: Vec<u64> = match &wired {
1524            Wired::ToOne(r) => r.children_of(parent),
1525            Wired::Join(r, forward) => r.members_of(parent, *forward),
1526        }
1527        .into_iter()
1528        .filter(|c| *c != h)
1529        .collect();
1530        let index = index.min(siblings.len());
1531        let prev = index.checked_sub(1).and_then(|i| siblings.get(i).copied());
1532        let next = siblings.get(index).copied();
1533        let ord = match (prev.map(&read_ord), next.map(&read_ord)) {
1534            (None, None) => 1.0,
1535            (Some(a), None) => a + 1.0,
1536            (None, Some(b)) => b - 1.0,
1537            (Some(a), Some(b)) => {
1538                let mid = a + (b - a) / 2.0;
1539                if mid > a && mid < b {
1540                    mid
1541                } else {
1542                    // The gap is spent: rebalance the siblings to whole numbers, then the
1543                    // target slot's midpoint is roomy again.
1544                    for (i, c) in siblings.iter().enumerate() {
1545                        write_ord(*c, (i + 1) as f64);
1546                    }
1547                    index as f64 + 0.5
1548                }
1549            }
1550        };
1551        write_ord(h, ord)
1552    }
1553
1554    /// Move an existing child to `index`: [`RelationRef::insert_at`], reading as intent.
1555    pub fn move_to(&self, child: impl Into<ModelId<T>>, index: usize) -> bool {
1556        self.insert_at(child, index)
1557    }
1558
1559    /// Clear `child`'s reference; it leaves this relation and belongs to no parent. On a
1560    /// required (`One<…>`, non-`Option`) inverse the cleared reference is a constraint
1561    /// violation at flush: reparent or delete the child instead.
1562    pub fn remove(&self, child: impl Into<ModelId<T>>) -> bool {
1563        let h = child.into().handle();
1564        match self.resolve() {
1565            Some((Wired::ToOne(r), p)) => {
1566                if !r.children_of(p).contains(&h) {
1567                    return false; // not this parent's child
1568                }
1569                r.set_fk(h, None)
1570            }
1571            Some((Wired::Join(r, forward), key)) => {
1572                let (a, b) = if forward { (key, h) } else { (h, key) };
1573                r.unlink(a, b)
1574            }
1575            None => false,
1576        }
1577    }
1578
1579    /// [`RelationRef::remove`] for every current child.
1580    pub fn clear(&self) {
1581        match self.resolve() {
1582            Some((Wired::ToOne(r), p)) => {
1583                let children = r.children_of(p);
1584                (r.materialize)(&children);
1585                for child in children {
1586                    (r.write_fk)(child, None);
1587                }
1588            }
1589            Some((Wired::Join(r, forward), key)) => {
1590                for other in r.members_of(key, forward) {
1591                    let (a, b) = if forward { (key, other) } else { (other, key) };
1592                    r.unlink(a, b);
1593                }
1594            }
1595            None => {}
1596        }
1597    }
1598}
1599
1600// ---------------------------------------------------------------------------
1601// Container-side dispatch
1602// ---------------------------------------------------------------------------
1603
1604impl ModelContainer {
1605    /// Route one announced change into relation maintenance. Called from the change sink,
1606    /// After dirty-marking and query staleness; the writes it makes (cascades, nullifies)
1607    /// nest through the same pipeline.
1608    pub(crate) fn relations_on_change(&self, change: &day_model::Change) {
1609        let Some(&store) = change.components.first() else {
1610            return;
1611        };
1612        if self.inner.relations.borrow().is_empty() && self.inner.joins.borrow().is_empty() {
1613            return;
1614        }
1615        let rels: Vec<Rc<ToOneRel>> = self.inner.relations.borrow().iter().cloned().collect();
1616        for rel in rels {
1617            if rel.child_store == store {
1618                match (change.components.get(1).copied(), change.op) {
1619                    (Some(k), _) if k == day_model::STRUCTURE => {}
1620                    (Some(child), Op::Set) if change.components.len() >= 3 => {
1621                        if change.label == rel.fk_field {
1622                            rel.reparent(child);
1623                        } else if Some(change.label) == rel.ordered {
1624                            rel.order_changed(child);
1625                        }
1626                    }
1627                    (Some(child), Op::Insert) if change.components.len() == 2 => {
1628                        rel.child_added(child);
1629                    }
1630                    (Some(child), Op::Delete) if change.components.len() == 2 => {
1631                        rel.child_removed(child);
1632                    }
1633                    _ => {}
1634                }
1635            }
1636            if rel.parent_store == store
1637                && change.components.len() == 2
1638                && change.op == Op::Delete
1639                && change.components[1] != day_model::STRUCTURE
1640            {
1641                rel.parent_deleted(self, change.components[1]);
1642            }
1643        }
1644
1645        let joins: Vec<Rc<JoinRel>> = self.inner.joins.borrow().iter().cloned().collect();
1646        for rel in joins {
1647            let Some(&key) = change.components.get(1) else {
1648                continue;
1649            };
1650            if key == day_model::STRUCTURE {
1651                continue;
1652            }
1653            if rel.join_store == store {
1654                match change.op {
1655                    Op::Insert if change.components.len() == 2 => rel.row_added(key),
1656                    Op::Delete if change.components.len() == 2 => rel.row_removed(key),
1657                    Op::Set if change.components.len() >= 3 && change.label == "position" => {
1658                        rel.row_moved(key)
1659                    }
1660                    _ => {}
1661                }
1662            }
1663            // Either side's deletion drops its memberships (and, under cascade from the
1664            // parent side, the children no other parent still holds).
1665            if change.op == Op::Delete && change.components.len() == 2 {
1666                if rel.a_store == store {
1667                    rel.side_deleted(true, key);
1668                } else if rel.b_store == store {
1669                    rel.side_deleted(false, key);
1670                }
1671            }
1672        }
1673    }
1674
1675    /// Drop every relation memo: the external-change and rescan reset.
1676    pub(crate) fn invalidate_relation_memos(&self) {
1677        for r in self.inner.relations.borrow().iter() {
1678            r.invalidate_all();
1679        }
1680        for j in self.inner.joins.borrow().iter() {
1681            j.invalidate_all();
1682        }
1683    }
1684
1685    /// Drop the memos of every relation with an end (or, for a many-to-many, its join
1686    /// table) in `tables`: what a table-scoped refresh invalidates.
1687    pub(crate) fn invalidate_relation_memos_of(&self, tables: &[&'static str]) {
1688        for r in self.inner.relations.borrow().iter() {
1689            if tables.contains(&r.parent_table) || tables.contains(&r.child_table) {
1690                r.invalidate_all();
1691            }
1692        }
1693        for j in self.inner.joins.borrow().iter() {
1694            if tables.contains(&j.join_table)
1695                || tables.contains(&j.a_table)
1696                || tables.contains(&j.b_table)
1697            {
1698                j.invalidate_all();
1699            }
1700        }
1701    }
1702
1703    /// The cache for `M` when it is in this container's schema: the non-panicking
1704    /// [`ModelContainer::cache`].
1705    pub fn try_cache<M: Model>(&self) -> Option<Store<Keyed<M>>> {
1706        self.inner
1707            .stores
1708            .borrow()
1709            .get(&std::any::TypeId::of::<M>())
1710            .and_then(|a| a.downcast_ref::<Store<Keyed<M>>>())
1711            .copied()
1712    }
1713
1714    /// Delete one row, honoring deny rules: a parent still referenced through a
1715    /// `DeleteRule::Deny` relation is refused with the relation named. Cascade and nullify
1716    /// need no checked door (a plain `restructure` delete triggers them), but deny cannot
1717    /// refuse after the row is gone, so this is deny's contract.
1718    pub fn delete<M: Model>(&self, id: impl Into<ModelId<M>>) -> Result<(), DbError> {
1719        let h = id.into().handle();
1720        let store = self.cache::<M>();
1721        let rels: Vec<Rc<ToOneRel>> = self.inner.relations.borrow().iter().cloned().collect();
1722        for r in rels
1723            .iter()
1724            .filter(|r| r.parent_store == store.store_id() && r.delete == DeleteRule::Deny)
1725        {
1726            let n = r.children_of(h).len();
1727            if n > 0 {
1728                return Err(DbError::new(
1729                    DbErrorKind::Deny,
1730                    format!(
1731                        "`{}` row still referenced by {n} `{}` row(s) through `{}` — \
1732                         delete or reparent them first",
1733                        M::TABLE,
1734                        r.fk_field,
1735                        r.parent_field
1736                    ),
1737                ));
1738            }
1739        }
1740        let joins: Vec<Rc<JoinRel>> = self.inner.joins.borrow().iter().cloned().collect();
1741        for r in joins.iter().filter(|r| {
1742            (r.a_store == store.store_id() && r.a_delete == DeleteRule::Deny)
1743                || (r.b_store == store.store_id() && r.b_delete.get() == DeleteRule::Deny)
1744        }) {
1745            let forward = r.a_store == store.store_id();
1746            let n = r.members_of(h, forward).len();
1747            if n > 0 {
1748                return Err(DbError::new(
1749                    DbErrorKind::Deny,
1750                    format!(
1751                        "`{}` row still holds {n} membership(s) through `{}` — unlink them \
1752                         first",
1753                        M::TABLE,
1754                        if forward {
1755                            r.a_field
1756                        } else {
1757                            r.b_field.get().unwrap_or(r.a_field)
1758                        }
1759                    ),
1760                ));
1761            }
1762        }
1763        // The delete works resident or not (a value-free Delete folds to one statement),
1764        // but an installed undo stack needs the row to invert it.
1765        if day_model::record_capture_active() {
1766            let _ = self.ensure_resident::<M>(&[h]);
1767        }
1768        store.restructure("delete", Op::Delete, h, |k| {
1769            k.remove(h);
1770        });
1771        Ok(())
1772    }
1773
1774    /// Create (once) a generated join table: the pair as the primary key, a foreign key per
1775    /// side with its own delete rule, and an index on the reverse side so the child→parents
1776    /// direction is as cheap as the forward one.
1777    pub(crate) fn ensure_join_table<P: Model, C: Model>(
1778        &self,
1779        table: &str,
1780        parent_col: &str,
1781        child_col: &str,
1782        ordered: bool,
1783        delete: DeleteRule,
1784    ) -> Result<(), DbError> {
1785        // The engine's own rule for the parent side matches the declaration; the child side
1786        // always clears its memberships, because a membership row without its child is
1787        // garbage in any reading of the relation.
1788        let position = if ordered {
1789            ", position REAL NOT NULL"
1790        } else {
1791            ""
1792        };
1793        let index = ident(&format!("day_idx_{table}_{child_col}"));
1794        let (table, parent_col, child_col) = (ident(table), ident(parent_col), ident(child_col));
1795        let body = format!(
1796            "CREATE TABLE IF NOT EXISTS {table} (\
1797             {parent_col} {} NOT NULL REFERENCES {}({}) ON DELETE {} DEFERRABLE INITIALLY DEFERRED, \
1798             {child_col} {} NOT NULL REFERENCES {}({}) ON DELETE CASCADE DEFERRABLE INITIALLY DEFERRED\
1799             {position}, PRIMARY KEY ({parent_col}, {child_col}))",
1800            P::KEY_SQL.ddl(),
1801            TableName::of::<P>().sql(),
1802            ident(P::KEY),
1803            if delete == DeleteRule::Deny {
1804                "RESTRICT"
1805            } else {
1806                "CASCADE"
1807            },
1808            C::KEY_SQL.ddl(),
1809            TableName::of::<C>().sql(),
1810            ident(C::KEY),
1811        );
1812        if self.conn().execute(&format!("{body} STRICT"), &[]).is_err() {
1813            self.conn().execute(&body, &[])?;
1814        }
1815        self.conn().execute(
1816            &format!("CREATE INDEX IF NOT EXISTS {index} ON {table}({child_col})"),
1817            &[],
1818        )?;
1819        Ok(())
1820    }
1821
1822    /// Give a join store the same table hooks every model store has, so one fold, one
1823    /// external merge and one undo history cover memberships too.
1824    pub(crate) fn register_join_hooks(
1825        &self,
1826        table: &'static str,
1827        parent_col: &'static str,
1828        child_col: &'static str,
1829        ordered: bool,
1830        store: Store<Keyed<JoinRow>>,
1831    ) {
1832        let mut columns = vec![parent_col.to_string(), child_col.to_string()];
1833        let mut column_names = vec![parent_col, child_col];
1834        let mut fields = vec![parent_col.to_string(), child_col.to_string()];
1835        if ordered {
1836            columns.push("position".into());
1837            column_names.push("position");
1838            fields.push("position".into());
1839        }
1840        let to_row = move |r: &JoinRow| {
1841            let mut v = vec![key_param(r.parent), key_param(r.child)];
1842            if ordered {
1843                v.push(Value::Real(r.position));
1844            }
1845            v
1846        };
1847        let decode = move |r: &Vec<Value>| -> Result<JoinRow, DbError> {
1848            match (
1849                value_to_handle(&Row::get(r, 0)),
1850                value_to_handle(&Row::get(r, 1)),
1851            ) {
1852                (Some(p), Some(c)) => Ok(JoinRow {
1853                    parent: p,
1854                    child: c,
1855                    position: if ordered {
1856                        Row::get(r, 2).as_real().unwrap_or(0.0)
1857                    } else {
1858                        0.0
1859                    },
1860                }),
1861                _ => Err(DbError::new(
1862                    DbErrorKind::Decode,
1863                    format!("`{table}` holds a membership whose ids will not read as keys"),
1864                )),
1865            }
1866        };
1867        let (pc, cc) = (ident(parent_col), ident(child_col));
1868        let hooks = crate::TableHooks {
1869            table,
1870            name: TableName::plain(table),
1871            key_cols: vec![parent_col.to_string(), child_col.to_string()],
1872            key_where: Rc::new(move |h| match day_model::Key::of_handle(h) {
1873                Some(day_model::Key::Pair(p, c)) => (
1874                    format!("{pc} = ? AND {cc} = ?"),
1875                    vec![key_param(p), key_param(c)],
1876                ),
1877                _ => (format!("{pc} IS NULL"), Vec::new()),
1878            }),
1879            columns,
1880            column_names,
1881            fields,
1882            fts: None,
1883            fts_key: "rowid",
1884            spatial: None,
1885            row_for: Rc::new(move |h| store.with_untracked(|k| k.get(h).map(to_row))),
1886            all_rows: Rc::new(move || {
1887                store.with_untracked(|k| {
1888                    k.items()
1889                        .iter()
1890                        .map(|r| (day_model::Identified::handle(r), to_row(r)))
1891                        .collect()
1892                })
1893            }),
1894            resident_keys: Rc::new(move || store.with_untracked(|k| k.keys())),
1895            resident_len: Rc::new(move || store.with_untracked(|k| k.len())),
1896            is_resident: Rc::new(move |h| store.with_untracked(|k| k.get(h).is_some())),
1897            absorb: Rc::new(move |raw| {
1898                let mut rows = Vec::with_capacity(raw.len());
1899                for r in &raw {
1900                    rows.push(decode(r)?);
1901                }
1902                let keys = rows
1903                    .iter()
1904                    .map(day_model::Identified::handle)
1905                    .collect::<Vec<_>>();
1906                store.populate(rows);
1907                Ok(keys)
1908            }),
1909            refresh: Rc::new(move |raw| {
1910                // Memberships are a set: the diff against the resident rows is which pairs
1911                // arrived, moved, or left.
1912                let mut fresh: Vec<JoinRow> = Vec::with_capacity(raw.len());
1913                for r in &raw {
1914                    fresh.push(decode(r)?);
1915                }
1916                let existing: Vec<u64> = store.with_untracked(|k| k.keys());
1917                let arriving: std::collections::HashSet<u64> =
1918                    fresh.iter().map(day_model::Identified::handle).collect();
1919                let mut changed = false;
1920                day_model::with_author(ModelContainer::EXTERNAL_AUTHOR, || {
1921                    for row in fresh {
1922                        let h = day_model::Identified::handle(&row);
1923                        match store.with_untracked(|k| k.get(h).cloned()) {
1924                            None => {
1925                                changed = true;
1926                                store.restructure("external", Op::Insert, h, |k| k.push(row));
1927                            }
1928                            Some(old) if ordered && old.position != row.position => {
1929                                changed = true;
1930                                store.write_field(h, "position", row.position);
1931                            }
1932                            Some(_) => {}
1933                        }
1934                    }
1935                    for gone in existing.into_iter().filter(|h| !arriving.contains(h)) {
1936                        changed = true;
1937                        store.restructure("external", Op::Delete, gone, |k| {
1938                            k.remove(gone);
1939                        });
1940                    }
1941                });
1942                Ok(changed)
1943            }),
1944            #[cfg(not(target_arch = "wasm32"))]
1945            dispose_cache: Rc::new(move || store.dispose_contents()),
1946            evict: Rc::new(move |candidates, want| {
1947                let doomed: Vec<u64> = candidates
1948                    .iter()
1949                    .copied()
1950                    .filter(|h| !store.is_observed(*h))
1951                    .take(want)
1952                    .collect();
1953                store.depopulate_many(&doomed)
1954            }),
1955            watch_undo: Rc::new(move |stack: &day_model::UndoStack| stack.watch(store)),
1956        };
1957        self.inner
1958            .tables
1959            .borrow_mut()
1960            .insert(store.store_id(), hooks);
1961    }
1962}