Skip to main content

ingraph_codegen/
journal.rs

1//! The JOURNAL declaration's emission: the canonical record, and the row contract over it.
2//!
3//! ```ignore
4//! #[ingraph::journal(root = "MediaId", sqlite)]
5//! pub struct VideoJournal;
6//! ```
7//!
8//! # It emits a RECORD, and that is the whole design
9//!
10//! What the word mounts is not a second kind of thing. [`columns`] mints the four the organ is
11//! keyed and read by, the front end hands them to the ORDINARY record pass under
12//! [`NodeKind::Record`](crate::model::NodeKind::Record), and this model emits that record's own
13//! expansion plus one impl. So a mounted journal has the `*Key` type, the accessor family, the
14//! per-database row, the comparison lowering, the order-by vocabulary and the cursor that every
15//! declared record has — because it IS one — and a deployment queries its run state exactly as it
16//! queries anything else it declared.
17//!
18//! The one thing added is [`JournalModel::row`]: `impl JournalRow<Root>`, which is the same trait
19//! the HAND path implements by hand. The macro is sugar over that contract and never a replacement,
20//! so the two paths meet at one seam and a writer cannot tell them apart.
21//!
22//! # The four columns, and why each is the one it is
23//!
24//! | column | type | why |
25//! |---|---|---|
26//! | `root` | the type `root = "…"` named | one journal table per ROOT FAMILY, and the root is that family |
27//! | `node` | `String` | `NodeName`'s storable face, which is what the hand corpus already stores |
28//! | `station` | `String` | `Station`'s, for the same reason — the framework's own stable word |
29//! | `at` | `Timestamp` | the framework's own instant: feature-free, and stored on every backend |
30//!
31//! `root` is the LINEAGE and `node` is the ID, so `key = lineage ⊕ id` spells `(root, node)` with
32//! nothing declared for it — and the keyed replace that makes an entry the LAST STATE is the
33//! ordinary write of that key. That is the organ's semantics arriving from the record law rather
34//! than from anything written here.
35//!
36//! `root`'s CITIZENSHIP is not checked here and is not left unchecked: it is a key column of an
37//! ordinary record, so a type no backend can store is the storability audit's own refusal, at the
38//! declaration that named it.
39//!
40//! # `SystemTime` → `Timestamp`: the crossing PANICS, and the alternative is a durable lie
41//!
42//! [`JournalRow::of`](../../ingraph/trait.JournalRow.html) is handed a `SystemTime` and the `at`
43//! column is a `Timestamp`, whose range is jiff's ±9999 years. The conversion is `TryFrom` rather
44//! than `From` on purpose — `ingraph::Timestamp`'s own note says why: *a saturating `From` would
45//! substitute an instant for the one a caller handed over*.
46//!
47//! The signature this emission has to satisfy returns `Self` and cannot report a refusal, so the
48//! two available postures are to substitute an instant or to stop. It stops. A journal row is
49//! DURABLE and is read as *when this node got there*, so a substituted instant is a row asserting a
50//! moment that never happened — and what reaches this crossing is a system clock wrong by thousands
51//! of years rather than a value worth rounding. The panic names the fact and carries jiff's own
52//! refusal; a deployment that would rather keep the row writes the HAND path, whose `of` is its own
53//! and may say whatever it likes about an instant it cannot hold.
54
55use quote::quote;
56
57use crate::model::RecordModel;
58
59#[cfg(test)]
60mod tests;
61
62/// A validated journal declaration, ready to emit.
63///
64/// PLAIN, for the reason every model in this crate has plain fields: the derive today and a
65/// manifest front end later reach the same emitter.
66#[derive(Debug, Clone)]
67pub struct JournalModel {
68  /// The canonical record this journal IS — the four columns of [`columns`], parsed by the ordinary
69  /// record pass, so everything a declared record emits is emitted here too.
70  pub record: RecordModel,
71  /// The chain root the journal is keyed by — the type `root = "…"` named, and the `Root` parameter
72  /// of the emitted [`JournalRow`](../../ingraph/trait.JournalRow.html) impl.
73  pub root: syn::Type,
74}
75
76impl JournalModel {
77  /// The record's own expansion, and the row contract over it.
78  #[must_use]
79  pub fn emit(&self) -> proc_macro2::TokenStream {
80    let record = self.record.emit();
81    let row = row(&self.record.krate, &self.record.record, &self.root);
82    quote! {
83      #record
84      #row
85    }
86  }
87}
88
89/// `impl JournalRow<Root>` — the four things the framework knows, mapped onto the four columns.
90///
91/// A free function over the three tokens it spends rather than a method, so the claim about what it
92/// writes is readable without assembling a whole record model to make it.
93///
94/// Every path is rooted through the shelf, as every emitted framework path is, and every trait item
95/// is reached in qualified form: an expansion lands in a namespace whose `From` and whose `TryFrom`
96/// are not necessarily the ones this code means.
97pub(crate) fn row(
98  krate: &syn::Path,
99  name: &syn::Ident,
100  root: &syn::Type,
101) -> proc_macro2::TokenStream {
102  let drive = quote!(#krate::__private::drive);
103  let instant = quote!(#krate::__private::primitives::Timestamp);
104  quote! {
105    impl #drive::JournalRow<#root> for #name {
106      fn of(
107        root: &#root,
108        node: &#drive::NodeName,
109        arrival: &#drive::Arrival,
110        at: ::std::time::SystemTime,
111      ) -> Self {
112        Self {
113          root: ::core::clone::Clone::clone(root),
114          node: ::std::string::String::from(#drive::NodeName::as_str(node)),
115          station: ::std::string::String::from(
116            #drive::Station::as_str(&#drive::Arrival::station(arrival)),
117          ),
118          // The crossing that cannot report — see the module note for why it stops rather than
119          // substituting an instant nobody observed.
120          at: match <#instant as ::core::convert::TryFrom<::std::time::SystemTime>>::try_from(at) {
121            ::core::result::Result::Ok(instant) => instant,
122            ::core::result::Result::Err(refused) => ::core::panic!(
123              "a journal row's `at` is outside the range `ingraph::Timestamp` can hold, so this \
124               row cannot be written: {}. The instant a journal keeps is durable and is read as \
125               when the node got there, so substituting one would record a moment that never \
126               happened — this is a clock wrong by thousands of years rather than a value to round",
127              refused,
128            ),
129          },
130        }
131      }
132    }
133  }
134}
135
136/// The four canonical columns, minted whole — the ONE authority for a mounted journal's shape.
137///
138/// Handed back as a declaration's own field list, markers and all, because that is what the record
139/// pass reads: the front end swaps them into the host it was given and every rule downstream is the
140/// rule that was already there. Nothing about the shape is decided twice.
141///
142/// The four columns are the SAME four whether or not the journal named a store, which is the
143/// participation inversion read from the mint's side.
144///
145/// The `root` column used to carry a bare `#[ingraph(persist)]` and the other three used to carry
146/// one beside their own word, both only where a storage block had been written — because the marker
147/// was what put a column in the row. Data fields ARE the row now, so a marker that says so is a word
148/// nobody reads, and the branch that wrote it is gone with it. WHICH RUNG the mount lands on is the
149/// front end's, decided from the store words and spent as the node kind it parses under; nothing
150/// about the column list depends on it.
151///
152/// The KEY-side columns (`root` and `node`) carry no family label and cannot: a label on a key
153/// column is refused by the record grammar, the key's own crossing being decided by its type.
154#[must_use]
155pub fn columns(root: &syn::Type, krate: &syn::Path) -> syn::FieldsNamed {
156  syn::parse_quote!({
157    /// The chain ROOT this entry is about — one journal table per root family, and this is the
158    /// family. The key's first column.
159    root: #root,
160
161    /// The NODE that did the work, as the framework's own stable word for it. The key's last
162    /// column, so `(root, node)` is the whole address and an entry is replaced in place.
163    #[ingraph(id)]
164    node: ::std::string::String,
165
166    /// Where the node GOT TO — the station of the observation this entry was built from.
167    #[ingraph(string)]
168    station: ::std::string::String,
169
170    /// WHEN, as the framework's own instant.
171    #[ingraph(scalar)]
172    at: #krate::__private::primitives::Timestamp,
173  })
174}