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