Skip to main content

rebuilding_read_models/
main.rs

1//! Operating derived state: four views over one log, on one SQLite file.
2//!
3//! `transfers-on-sqlite` proves a projection survives a reopen. It runs *one*
4//! view, and a single view is the one arrangement in which none of the
5//! questions an operator actually has can be asked: it is never skewed against
6//! a peer, never rebuilt, never reset, and never the one that breaks while the
7//! others must keep going.
8//!
9//! This program has four views over one log and does the four things to them
10//! that a running system eventually demands.
11//!
12//! Run with `cargo run -p rebuilding-read-models`.
13//!
14//! # What this demonstrates that the other examples cannot
15//!
16//! 1. **Two views sit at two checkpoints, and a reader must tolerate it.** A
17//!    checkpoint is per `(store, ProjectionId)`. Halfway through, this program
18//!    advances one view and not the other and then joins the two tables, so
19//!    the stale row is visible rather than argued about.
20//! 2. **A view added late is backfilled beside the one it replaces.** The
21//!    typed runner always claims `Authority::Live`, so a rebuild is bought
22//!    with a *second* `ProjectionId` writing a *second* table — blue and
23//!    green — and the swap is the application's, at the moment it chooses. It
24//!    rides in the old id's reset batch, so retirement and swap are one
25//!    transaction, and a swap that fails leaves the old view whole.
26//! 3. **Reset is a real operation, and rebuilding is chunk-size invariant.**
27//!    `ProjectionStore::reset` clears the read model and the checkpoint as one
28//!    unit and leaves `Checkpoint::NeverRun` behind — not a checkpoint at the
29//!    first position, which is how event 1 gets skipped permanently and
30//!    silently. Rebuilt at chunk 1 and at chunk 500, the rows are identical.
31//! 4. **One poisoned view does not stall the others.** The failure is the one
32//!    that actually happens in production: a projection written against a
33//!    field the log does not carry. It fails to *decode*, names the position
34//!    it failed at, commits nothing, and the other three carry on — because
35//!    the failure policy is this application's and not the runner's.
36//!
37//! # What it does not demonstrate, stated so nobody reads more into it
38//!
39//! It is one process and it never crashes. `transfers-on-sqlite` owns the
40//! durability claim and `tickets-over-http` owns the two-process one; the
41//! subject here is what an operator does to a view that is already working.
42//! Nor is the poisoned view a claim about fault *injection*: nothing here
43//! interrupts a commit halfway. That belongs to the conformance suite. The one
44//! promotion that fails on purpose fails on a statement, inside a transaction
45//! that is then rolled back — an operator's typo, not a crash.
46//!
47//! # The domain, and why it is not another ledger
48//!
49//! Order fulfilment, because it is the smallest domain that naturally wants
50//! *several* views of one log that disagree about what matters — stock is
51//! per-SKU, status is per-order, and the dispatch count is per-day and belongs
52//! to neither. Three shapes over one event set is the situation the
53//! projection port exists for, and one shape cannot demonstrate it.
54
55use std::io::{self, Write as _};
56use std::path::{Path, PathBuf};
57
58use anyhow::{Result, bail};
59use happenstance::bytes::Bytes;
60use happenstance::{
61    Checkpoint, Chunk, Codec, CodecError, CommandError, DecisionModel, Delivered, DomainEvent,
62    EventStore, EventType, InvalidTag, Json, Projection, ProjectionError, ProjectionId,
63    ProjectionStore, Query, ReadOptions, Retry, Tag, Tags, checkpoint_id, collect, commit,
64    run_projection,
65};
66use happenstance_sqlite::connection::open_configured;
67use happenstance_sqlite::event_store::{SqliteEventStore, SqliteEventStoreError};
68use happenstance_sqlite::projection_store::{
69    SqliteBatch, SqliteProjectionStore, SqliteProjectionStoreError,
70};
71use rusqlite::Connection;
72use rusqlite::types::Value;
73use serde::{Deserialize, Serialize};
74
75/// How many times a command may be attempted before it gives up.
76///
77/// Spelled at every call site for the reason `course-subscriptions` gives: a
78/// loop whose only exit is success is a hang with better manners. This run is
79/// single-writer, so the bound is never spent.
80const ATTEMPTS: u32 = 3;
81
82/// The chunk the ordinary catch-up runs use.
83///
84/// Small enough that a first run commits more than once, which is the only way
85/// a checkpoint's *intermediate* positions are ever written.
86const CHUNK: usize = 4;
87
88/// The two chunk sizes a rebuild is run at, to show the rows do not depend on
89/// how the replay was divided.
90///
91/// One is the smallest legal chunk — a commit per event — and the other is
92/// larger than this log will ever be, so the whole replay lands in a single
93/// batch. If those two disagree, the fold is carrying state it should not.
94const REBUILD_CHUNKS: [usize; 2] = [1, 500];
95
96/// The two days this run dispatches on.
97///
98/// Literals rather than a clock. A transcript that changes with the calendar
99/// is a transcript nobody can diff, and the daily view exists to be counted,
100/// not to be current.
101const DAYS: [&str; 2] = ["2026-09-01", "2026-09-02"];
102
103/// The five read-model tables this application owns.
104///
105/// They are the application's tables, not the adapter's: `SqliteProjectionStore`
106/// migrates `projection_checkpoint` and `projection_meta` and stops there. A
107/// projection store that invented your read model's schema would be a framework
108/// rather than a port — which is also why the blue/green swap below is plain
109/// SQL this file writes, and not a method somebody else designed.
110const READ_MODEL_DDL: &str = "
111CREATE TABLE IF NOT EXISTS stock_on_hand (
112    sku      TEXT PRIMARY KEY,
113    on_hand  INTEGER NOT NULL
114) STRICT;
115CREATE TABLE IF NOT EXISTS order_status (
116    order_ref TEXT PRIMARY KEY,
117    status    TEXT NOT NULL,
118    sku       TEXT NOT NULL,
119    quantity  INTEGER NOT NULL
120) STRICT;
121CREATE TABLE IF NOT EXISTS daily_dispatches (
122    day        TEXT PRIMARY KEY,
123    dispatched INTEGER NOT NULL
124) STRICT;
125CREATE TABLE IF NOT EXISTS daily_dispatches_v2 (
126    day        TEXT PRIMARY KEY,
127    dispatched INTEGER NOT NULL
128) STRICT;
129CREATE TABLE IF NOT EXISTS couriered (
130    order_ref TEXT PRIMARY KEY,
131    courier   TEXT NOT NULL
132) STRICT;
133";
134
135#[tokio::main(flavor = "current_thread")]
136async fn main() -> Result<()> {
137    let path = database_path();
138    remove_database(&path);
139
140    writeln!(io::stdout().lock(), "== the database this run writes to ==")?;
141    writeln!(io::stdout().lock(), "   {}", path.display())?;
142
143    // The run is a function so that every store, connection and projection it
144    // builds is dropped before the file is removed — on Windows an open handle
145    // is what makes the cleanup silently fail and the next run start on the
146    // tail of this one.
147    let outcome = run(&path).await;
148    remove_database(&path);
149    outcome
150}
151
152/// Everything this program does, inside one scope over one file.
153async fn run(path: &Path) -> Result<()> {
154    let events = SqliteEventStore::open(path)?;
155    let models = SqliteProjectionStore::open(path)?;
156    let app = open_configured(path)?;
157    app.execute_batch(READ_MODEL_DDL)?;
158
159    seed_the_log(&events).await?;
160    two_views_two_checkpoints(&events, &models, &app).await?;
161    a_third_view_added_late(&events, &models, &app).await?;
162    reset_and_rebuild(&events, &models, &app).await?;
163    one_poisoned_view(&events, &models).await?;
164
165    writeln!(io::stdout().lock(), "\n== final log ==")?;
166    print_log(&events).await?;
167
168    Ok(())
169}
170
171// ---------------------------------------------------------------------------
172// The five things this program does
173// ---------------------------------------------------------------------------
174
175/// Writes the events every view below is derived from.
176///
177/// One refusal is exercised on the way, so the log is the product of decisions
178/// rather than of appends: an order for more units than the shelf holds is
179/// rejected against the same boundary that would have let it through.
180async fn seed_the_log(events: &SqliteEventStore) -> Result<()> {
181    writeln!(io::stdout().lock(), "\n== seeding the fulfilment log ==")?;
182
183    receive_stock(events, "sku-1", 13).await?;
184    receive_stock(events, "sku-2", 6).await?;
185    place_order(events, "o-1", "sku-1", 3).await?;
186    place_order(events, "o-2", "sku-1", 2).await?;
187    place_order(events, "o-3", "sku-2", 4).await?;
188    dispatch_order(events, "o-1", DAYS[0]).await?;
189    dispatch_order(events, "o-2", DAYS[0]).await?;
190    writeln!(
191        io::stdout().lock(),
192        "   two SKUs received, three orders placed, two dispatched"
193    )?;
194
195    match place_order(events, "o-9", "sku-2", 5).await {
196        Ok(()) => bail!("an order against an emptied shelf should have been rejected"),
197        Err(err) => writeln!(io::stdout().lock(), "   rejected: {err}")?,
198    }
199
200    Ok(())
201}
202
203/// Advances one view and not the other, and shows what a reader then sees.
204///
205/// The skew is not a defect being confessed to — it is the arrangement. A
206/// checkpoint is per `(store, ProjectionId)`, so two views over one log are
207/// two independent positions, and an application that joins them is reading
208/// two different moments. Printing both checkpoints beside the rows is the
209/// only way to say that without it sounding theoretical.
210async fn two_views_two_checkpoints(
211    events: &SqliteEventStore,
212    models: &SqliteProjectionStore,
213    app: &Connection,
214) -> Result<()> {
215    writeln!(
216        io::stdout().lock(),
217        "\n== two views over one log, at two checkpoints =="
218    )?;
219
220    let mut stock = StockOnHand::new();
221    let mut status = OrderStatus::new();
222    let applied_stock = drive(events, models, &mut stock, CHUNK).await?;
223    let applied_status = drive(events, models, &mut status, CHUNK).await?;
224    writeln!(
225        io::stdout().lock(),
226        "   stock_on_hand applied {applied_stock}, order_status applied {applied_status}"
227    )?;
228
229    // Both are caught up here, which is the only state in which the skew below
230    // is attributable to what this function does next rather than to how they
231    // were built.
232    print_checkpoint(models, &stock).await?;
233    print_checkpoint(models, &status).await?;
234
235    writeln!(
236        io::stdout().lock(),
237        "\n   -- a fourth order is placed, and only one view is run --"
238    )?;
239    place_order(events, "o-4", "sku-1", 5).await?;
240    let applied_stock = drive(events, models, &mut stock, CHUNK).await?;
241    writeln!(
242        io::stdout().lock(),
243        "   stock_on_hand applied {applied_stock}, order_status was not run"
244    )?;
245    print_checkpoint(models, &stock).await?;
246    print_checkpoint(models, &status).await?;
247
248    writeln!(io::stdout().lock(), "\n   stock_on_hand:")?;
249    print_table(app, "SELECT sku, on_hand FROM stock_on_hand ORDER BY sku")?;
250    writeln!(io::stdout().lock(), "   order_status:")?;
251    print_table(
252        app,
253        "SELECT order_ref, status FROM order_status ORDER BY order_ref",
254    )?;
255    writeln!(
256        io::stdout().lock(),
257        "   o-4's five units are already off the shelf and it has no status row:\n   \
258         a join across these two tables is a join across two moments"
259    )?;
260
261    writeln!(
262        io::stdout().lock(),
263        "\n   -- order_status is brought level --"
264    )?;
265    let applied_status = drive(events, models, &mut status, CHUNK).await?;
266    writeln!(
267        io::stdout().lock(),
268        "   order_status applied {applied_status}"
269    )?;
270    print_checkpoint(models, &stock).await?;
271    print_checkpoint(models, &status).await?;
272
273    Ok(())
274}
275
276/// Backfills a view that did not exist when the log was written, then promotes it.
277///
278/// The typed runner always claims `Authority::Live`, so there is no in-place
279/// rebuild to reach for and this is not a limitation being worked around: a
280/// second `ProjectionId` writing a second table is blue/green, and it is the
281/// arrangement that lets the old view keep answering queries the whole time.
282///
283/// The promotion is plain SQL this file writes, because the read model belongs
284/// to this application. **The `ProjectionId` deliberately does not change with
285/// it.** `daily_dispatches_v2` keeps its name after the swap, because the
286/// checkpoint is keyed by that name and the derived query (`checkpoint_id`) —
287/// renaming it to look tidy would throw the resume point away and replay the
288/// whole log. The table is not part of the query, so the swap keeps the key.
289///
290/// The swap is pushed into the *old* id's reset batch rather than run beside
291/// it, and that is what makes it one transaction. It is attempted once with
292/// the new table's name mistyped first, to show what that buys: the drop runs,
293/// the rename fails, and the old view keeps its rows and its checkpoint.
294async fn a_third_view_added_late(
295    events: &SqliteEventStore,
296    models: &SqliteProjectionStore,
297    app: &Connection,
298) -> Result<()> {
299    writeln!(
300        io::stdout().lock(),
301        "\n== a third view, added after the fact =="
302    )?;
303
304    let mut blue = DailyDispatches::counting_orders();
305    let applied = drive(events, models, &mut blue, CHUNK).await?;
306    writeln!(
307        io::stdout().lock(),
308        "   daily_dispatches backfilled from zero: applied {applied}"
309    )?;
310    print_table(
311        app,
312        "SELECT day, dispatched FROM daily_dispatches ORDER BY day",
313    )?;
314
315    writeln!(
316        io::stdout().lock(),
317        "\n   -- the count was wrong: it wanted units, not orders --"
318    )?;
319    let mut green = DailyDispatches::counting_units();
320    let applied = drive(events, models, &mut green, CHUNK).await?;
321    writeln!(
322        io::stdout().lock(),
323        "   daily_dispatches_v2 backfilled beside it: applied {applied}"
324    )?;
325    print_table(
326        app,
327        "SELECT day, dispatched FROM daily_dispatches_v2 ORDER BY day",
328    )?;
329    writeln!(
330        io::stdout().lock(),
331        "   both views are live at once, and neither has stopped answering"
332    )?;
333
334    // From here blue's runner is stopped and green's is paused: neither is
335    // driven again until green comes back as `promoted`. A runner still
336    // scheduled under blue's id would replay the whole log into whichever
337    // table has the name it writes to once its checkpoint is reset.
338    writeln!(
339        io::stdout().lock(),
340        "\n   -- a promotion whose rename fails --"
341    )?;
342    match retire(models, &blue, &MISTYPED_PROMOTION).await {
343        Ok(()) => bail!("a promotion from a table that does not exist was committed"),
344        Err(err) => writeln!(io::stdout().lock(), "   refused: {err}")?,
345    }
346    print_checkpoint(models, &blue).await?;
347    print_table(
348        app,
349        "SELECT day, dispatched FROM daily_dispatches ORDER BY day",
350    )?;
351    writeln!(
352        io::stdout().lock(),
353        "   the drop ran and was rolled back with the rename: blue is untouched"
354    )?;
355
356    writeln!(
357        io::stdout().lock(),
358        "\n   -- promoted, and the checkpoint comes with it --"
359    )?;
360    // The swap is blue's reset batch, so retiring blue and renaming green into
361    // its place are one transaction. A reader sees the old table until the
362    // reset commits and the new one after it, never an empty one between. Done
363    // as a retirement and then a separate swap, the gap between the two is a
364    // view with no rows and an id at `NeverRun` — which the attempt above
365    // would have left behind for good.
366    retire(models, &blue, &PROMOTION).await?;
367    let mut promoted = DailyDispatches::promoted();
368    // The resume below rests on this: the promoted view derives green's
369    // checkpoint id, because it shares green's name, event type and scope.
370    // Only its table changed, and the table is not part of the query.
371    if checkpoint_id(&promoted)? != checkpoint_id(&green)? {
372        bail!("the promoted view would not resume from green's checkpoint");
373    }
374    print_checkpoint(models, &promoted).await?;
375
376    dispatch_order(events, "o-3", DAYS[1]).await?;
377    let applied = drive(events, models, &mut promoted, CHUNK).await?;
378    writeln!(
379        io::stdout().lock(),
380        "   one more dispatch, and the promoted view applied {applied} — not the whole log"
381    )?;
382    print_table(
383        app,
384        "SELECT day, dispatched FROM daily_dispatches ORDER BY day",
385    )?;
386
387    Ok(())
388}
389
390/// Clears a view and builds it again, twice, at two very different chunk sizes.
391///
392/// `reset` is the operation that makes a read model disposable, and it clears
393/// the rows and the checkpoint as **one** unit of work: a delete that succeeded
394/// while the checkpoint survived would leave a view that is empty and believes
395/// it is current. What it leaves behind is `Checkpoint::NeverRun`, which is a
396/// different thing from a checkpoint at the first position — an operator who
397/// substitutes one for the other makes the next run resume *after* event 1, and
398/// event 1 is then skipped permanently and silently.
399///
400/// The two chunk sizes are the assertion. Chunk 1 commits once per event and
401/// chunk 500 commits the whole replay at once; if the rows differ, the fold is
402/// carrying state across events that it should be writing into the row.
403async fn reset_and_rebuild(
404    events: &SqliteEventStore,
405    models: &SqliteProjectionStore,
406    app: &Connection,
407) -> Result<()> {
408    /// The query both rebuilds are compared through.
409    const ROWS: &str = "SELECT sku, on_hand FROM stock_on_hand ORDER BY sku";
410
411    writeln!(
412        io::stdout().lock(),
413        "\n== reset, and rebuilt at two chunk sizes =="
414    )?;
415    let mut rebuilt = Vec::with_capacity(REBUILD_CHUNKS.len());
416
417    for chunk in REBUILD_CHUNKS {
418        let mut stock = StockOnHand::new();
419        retire(models, &stock, &["DELETE FROM stock_on_hand"]).await?;
420        let cleared = models.checkpoint(&checkpoint_id(&stock)?).await?;
421        let applied = drive(events, models, &mut stock, chunk).await?;
422        writeln!(
423            io::stdout().lock(),
424            "   cleared to {}, rebuilt at chunk {chunk}: applied {applied}",
425            render_checkpoint(cleared)
426        )?;
427        rebuilt.push(render_table(app, ROWS)?);
428    }
429
430    match rebuilt.as_slice() {
431        [small, large] if small == large => {
432            let mut out = io::stdout().lock();
433            writeln!(out, "   both rebuilds produced the same rows:")?;
434            write!(out, "{small}")?;
435            Ok(())
436        }
437        [small, large] => {
438            bail!("a rebuild's rows depend on its chunk size\nchunk 1:\n{small}chunk 500:\n{large}")
439        }
440        // Unreachable while `REBUILD_CHUNKS` has two entries. Spelled as a
441        // refusal rather than as an index, because an index would turn a
442        // changed constant into a panic in a program whose whole subject is
443        // not losing data quietly.
444        other => bail!("expected two rebuilds, got {}", other.len()),
445    }
446}
447
448/// Breaks one view and shows the other three keep moving.
449///
450/// The failure is the one that actually happens: somebody writes a projection
451/// against a field the log does not carry. It is not injected and nothing is
452/// corrupted — the events are exactly as they were written, and the *reader*
453/// is what disagrees with them. That failure surfaces as a decode error naming
454/// the position it stopped at, the chunk is rolled back, and the checkpoint
455/// stays where it was, which for a view that never ran is nowhere.
456///
457/// What this program does next is the part no library can decide: it records
458/// the failure and runs the others. `run_projection` drives one projection and
459/// halts on its first failure, which is the right primitive — a runner that
460/// swallowed the error would be deciding, for every application at once, that
461/// a wrong read model is better than a stalled one.
462async fn one_poisoned_view(
463    events: &SqliteEventStore,
464    models: &SqliteProjectionStore,
465) -> Result<()> {
466    writeln!(
467        io::stdout().lock(),
468        "\n== one poisoned view does not stall the others =="
469    )?;
470
471    let mut couriered = Couriered::new();
472    let (stopped_at, why) = poison(events, models, &mut couriered).await?;
473    writeln!(
474        io::stdout().lock(),
475        "   couriered stopped at position {stopped_at}: {why}"
476    )?;
477    // Every `.await` is resolved before the `writeln!` that prints its result:
478    // the locked handle is taken before the format arguments are evaluated, so
479    // an `.await` inside them would hold the guard across a suspension.
480    let key = checkpoint_id(&couriered)?;
481    let checkpoint = render_checkpoint(models.checkpoint(&key).await?);
482    writeln!(
483        io::stdout().lock(),
484        "   its checkpoint is {checkpoint} — the chunk was rolled back and nothing was committed"
485    )?;
486
487    writeln!(
488        io::stdout().lock(),
489        "\n   -- an event arrives while that view is broken --"
490    )?;
491    cancel_order(events, "o-4").await?;
492
493    let mut stock = StockOnHand::new();
494    let mut status = OrderStatus::new();
495    let mut daily = DailyDispatches::promoted();
496    let applied = drive(events, models, &mut stock, CHUNK).await?;
497    writeln!(io::stdout().lock(), "   stock_on_hand applied {applied}")?;
498    let applied = drive(events, models, &mut status, CHUNK).await?;
499    writeln!(io::stdout().lock(), "   order_status applied {applied}")?;
500    let applied = drive(events, models, &mut daily, CHUNK).await?;
501    writeln!(io::stdout().lock(), "   daily_dispatches applied {applied}")?;
502
503    let (still_stuck, _) = poison(events, models, &mut couriered).await?;
504    writeln!(
505        io::stdout().lock(),
506        "   couriered is still stuck at position {still_stuck}"
507    )?;
508
509    Ok(())
510}
511
512// ---------------------------------------------------------------------------
513// Identity, validated once at the edge
514// ---------------------------------------------------------------------------
515
516/// A stock-keeping unit, validated once into the tag its events carry.
517///
518/// The resolution `course-subscriptions` and `transfers-on-sqlite` both reach,
519/// and for the same reason: `DomainEvent::tags` is infallible while
520/// `Tag::key_value` can refuse, so a domain type whose tags come from runtime
521/// values holds the validated form instead of rebuilding it on every call.
522#[derive(Debug, Clone, Serialize, Deserialize)]
523#[serde(try_from = "String", into = "String")]
524struct Sku {
525    /// The identifier as the application wrote it.
526    id: String,
527    /// The same value, validated into the tag every event for it carries.
528    tag: Tag,
529}
530
531impl Sku {
532    /// Validates `id` into the tag every event for this SKU is written with.
533    fn new(id: &str) -> Result<Self, InvalidTag> {
534        Ok(Self {
535            id: id.to_owned(),
536            tag: Tag::key_value("sku", id)?,
537        })
538    }
539
540    /// The identifier as the application wrote it.
541    fn as_str(&self) -> &str {
542        &self.id
543    }
544}
545
546impl TryFrom<String> for Sku {
547    type Error = InvalidTag;
548
549    fn try_from(id: String) -> Result<Self, InvalidTag> {
550        Self::new(&id)
551    }
552}
553
554impl From<Sku> for String {
555    fn from(sku: Sku) -> Self {
556        sku.id
557    }
558}
559
560/// An order reference, validated once into the tag its events carry.
561#[derive(Debug, Clone, Serialize, Deserialize)]
562#[serde(try_from = "String", into = "String")]
563struct OrderId {
564    /// The reference as the application wrote it.
565    id: String,
566    /// The same value, validated into the tag every event for it carries.
567    tag: Tag,
568}
569
570impl OrderId {
571    /// Validates `id` into the tag every event for this order is written with.
572    fn new(id: &str) -> Result<Self, InvalidTag> {
573        Ok(Self {
574            id: id.to_owned(),
575            tag: Tag::key_value("order", id)?,
576        })
577    }
578
579    /// The reference as the application wrote it.
580    fn as_str(&self) -> &str {
581        &self.id
582    }
583}
584
585impl TryFrom<String> for OrderId {
586    type Error = InvalidTag;
587
588    fn try_from(id: String) -> Result<Self, InvalidTag> {
589        Self::new(&id)
590    }
591}
592
593impl From<OrderId> for String {
594    fn from(order: OrderId) -> Self {
595        order.id
596    }
597}
598
599// ---------------------------------------------------------------------------
600// The domain: one enum, named once
601// ---------------------------------------------------------------------------
602
603/// Everything that can happen while a shelf is emptied into orders.
604///
605/// One enum, so a query and a fold cannot name different sets. There is no
606/// `_ =>` arm anywhere in this file: a fifth variant is a compile error in
607/// every decision model and every projection that has not been told what it
608/// means, and that absence is the guarantee.
609#[derive(Debug, Serialize, Deserialize)]
610enum Fulfilment {
611    /// Stock arrived on the shelf.
612    StockReceived {
613        /// What arrived.
614        sku: Sku,
615        /// How many units.
616        quantity: u32,
617    },
618    /// An order took units off the shelf and is waiting to go out.
619    OrderPlaced {
620        /// The order now waiting.
621        order: OrderId,
622        /// What it holds.
623        sku: Sku,
624        /// How many units it holds.
625        quantity: u32,
626    },
627    /// An order left the building.
628    OrderDispatched {
629        /// The order that went.
630        order: OrderId,
631        /// What it held.
632        sku: Sku,
633        /// How many units it held.
634        quantity: u32,
635        /// The day it went, as a plain `YYYY-MM-DD` string.
636        day: String,
637    },
638    /// An order was called off and its units went back on the shelf.
639    OrderCancelled {
640        /// The order called off.
641        order: OrderId,
642        /// What it was holding.
643        sku: Sku,
644        /// How many units go back.
645        quantity: u32,
646    },
647}
648
649/// The four names this log carries, declared once and returned by name.
650///
651/// `Handover` below re-declares one of them: it is a *narrower* view of the same
652/// log, and sharing the constant is what stops the two lists drifting apart.
653const STOCK_RECEIVED: EventType = EventType::from_static("StockReceived");
654/// See [`STOCK_RECEIVED`].
655const ORDER_PLACED: EventType = EventType::from_static("OrderPlaced");
656/// See [`STOCK_RECEIVED`].
657const ORDER_DISPATCHED: EventType = EventType::from_static("OrderDispatched");
658/// See [`STOCK_RECEIVED`].
659const ORDER_CANCELLED: EventType = EventType::from_static("OrderCancelled");
660
661impl DomainEvent for Fulfilment {
662    const EVENT_TYPES: &'static [EventType] = &[
663        STOCK_RECEIVED,
664        ORDER_PLACED,
665        ORDER_DISPATCHED,
666        ORDER_CANCELLED,
667    ];
668
669    fn event_type(&self) -> EventType {
670        match self {
671            Self::StockReceived { .. } => STOCK_RECEIVED,
672            Self::OrderPlaced { .. } => ORDER_PLACED,
673            Self::OrderDispatched { .. } => ORDER_DISPATCHED,
674            Self::OrderCancelled { .. } => ORDER_CANCELLED,
675        }
676    }
677
678    fn tags(&self) -> Tags {
679        match self {
680            Self::StockReceived { sku, .. } => [sku.tag.clone()].into_iter().collect(),
681            Self::OrderPlaced { order, sku, .. }
682            | Self::OrderDispatched { order, sku, .. }
683            | Self::OrderCancelled { order, sku, .. } => {
684                [order.tag.clone(), sku.tag.clone()].into_iter().collect()
685            }
686        }
687    }
688
689    fn encode<C: Codec>(&self, codec: &C) -> Result<Bytes, CodecError> {
690        codec.encode(self)
691    }
692
693    fn decode<C: Codec>(
694        codec: &C,
695        _event_type: &EventType,
696        data: &Bytes,
697    ) -> Result<Self, CodecError> {
698        codec.decode(data)
699    }
700}
701
702/// The event set the `couriered` view was written against, and the log is not.
703///
704/// It declares the same event *type* as `Fulfilment`'s dispatch variant and a
705/// different *shape*: a `courier` this application has never written. Nothing
706/// about that is detectable at compile time — the type name matches, the query
707/// nominates the right events, and the mistake surfaces where every schema
708/// mistake surfaces, at the first payload that has to be decoded.
709///
710/// It is a separate enum rather than a variant of `Fulfilment` because it
711/// belongs to a different reader. That is the whole situation being modelled:
712/// two teams, one log, and a disagreement about what was written.
713#[derive(Debug, Serialize, Deserialize)]
714enum Handover {
715    /// A dispatch, as a later reader expected it to have been recorded.
716    OrderDispatched {
717        /// The order that went.
718        order: OrderId,
719        /// Who carried it. **Never written by this application.**
720        courier: String,
721    },
722}
723
724impl DomainEvent for Handover {
725    const EVENT_TYPES: &'static [EventType] = &[ORDER_DISPATCHED];
726
727    fn event_type(&self) -> EventType {
728        match self {
729            Self::OrderDispatched { .. } => ORDER_DISPATCHED,
730        }
731    }
732
733    fn tags(&self) -> Tags {
734        match self {
735            Self::OrderDispatched { order, .. } => [order.tag.clone()].into_iter().collect(),
736        }
737    }
738
739    fn encode<C: Codec>(&self, codec: &C) -> Result<Bytes, CodecError> {
740        codec.encode(self)
741    }
742
743    fn decode<C: Codec>(
744        codec: &C,
745        _event_type: &EventType,
746        data: &Bytes,
747    ) -> Result<Self, CodecError> {
748        codec.decode(data)
749    }
750}
751
752/// Why a decision refused.
753///
754/// Every variant carries the value the transcript prints — `sku-2 holds 2,
755/// needs 5` and never `out of stock` — so a reader can act on the refusal
756/// where it is printed instead of opening a second document to learn what
757/// happened.
758#[derive(Debug, thiserror::Error)]
759enum Refusal {
760    /// A receipt of nothing is not a receipt.
761    #[error("cannot receive zero units of {sku}")]
762    ZeroQuantity {
763        /// The SKU nothing arrived for.
764        sku: String,
765    },
766    /// An order reference may be used once.
767    #[error("order {order} has already been placed")]
768    AlreadyPlaced {
769        /// The reference already in use.
770        order: String,
771    },
772    /// The shelf cannot cover the order.
773    #[error("{sku} holds {on_hand}, needs {needed}")]
774    OutOfStock {
775        /// The SKU that cannot cover it.
776        sku: String,
777        /// What is on the shelf.
778        on_hand: i64,
779        /// What the order asked for.
780        needed: u32,
781    },
782    /// Nothing can happen to an order nobody placed.
783    #[error("order {order} has not been placed")]
784    NotPlaced {
785        /// The reference nobody placed.
786        order: String,
787    },
788    /// An order goes out once.
789    #[error("order {order} has already been dispatched")]
790    AlreadyDispatched {
791        /// The order already gone.
792        order: String,
793    },
794    /// A cancelled order is finished.
795    #[error("order {order} has already been cancelled")]
796    AlreadyCancelled {
797        /// The order already called off.
798        order: String,
799    },
800}
801
802// ---------------------------------------------------------------------------
803// The decision models: one per consistency concern
804// ---------------------------------------------------------------------------
805
806/// What is on the shelf for one SKU.
807///
808/// Scoped to a single `sku` tag, so the query this model derives nominates
809/// every event ever written about that SKU and nothing else.
810#[derive(Debug, Clone)]
811struct Stock {
812    /// The tags every event inside this boundary carries.
813    scope: Tags,
814    /// Units currently on the shelf, after placements and cancellations.
815    on_hand: i64,
816}
817
818impl Stock {
819    /// Validates the scope once, here, where the caller already writes a `?`.
820    fn new(sku: &Sku) -> Result<Self, InvalidTag> {
821        Ok(Self {
822            scope: Tags::from_pairs([("sku", sku.as_str())])?,
823            on_hand: 0,
824        })
825    }
826}
827
828impl DecisionModel for Stock {
829    type Event = Fulfilment;
830
831    fn scope(&self) -> &Tags {
832        &self.scope
833    }
834
835    fn apply(&mut self, event: Self::Event) {
836        match event {
837            Fulfilment::StockReceived { quantity, .. }
838            | Fulfilment::OrderCancelled { quantity, .. } => {
839                self.on_hand = self.on_hand.saturating_add(i64::from(quantity));
840            }
841            Fulfilment::OrderPlaced { quantity, .. } => {
842                self.on_hand = self.on_hand.saturating_sub(i64::from(quantity));
843            }
844            // A dispatch moves nothing: the units left the shelf when the order
845            // was placed, and counting them again here would show a shelf going
846            // negative for stock that was already reserved. The arm exists
847            // because the fold is exhaustive over the enum, and that
848            // exhaustiveness is the whole guarantee.
849            Fulfilment::OrderDispatched { .. } => {}
850        }
851    }
852}
853
854/// One order's own history.
855///
856/// Scoped to a single `order` tag. It is what makes a dispatch buildable from
857/// folded state rather than from arguments the caller has to repeat: the SKU
858/// and the quantity come out of the order's own placement.
859#[derive(Debug, Clone)]
860struct Order {
861    /// The tags every event inside this boundary carries.
862    scope: Tags,
863    /// What this order holds, once it has been placed.
864    held: Option<(Sku, u32)>,
865    /// Whether it has already gone out.
866    dispatched: bool,
867    /// Whether it has already been called off.
868    cancelled: bool,
869}
870
871impl Order {
872    /// Validates the scope once, here, where the caller already writes a `?`.
873    fn new(order: &OrderId) -> Result<Self, InvalidTag> {
874        Ok(Self {
875            scope: Tags::from_pairs([("order", order.as_str())])?,
876            held: None,
877            dispatched: false,
878            cancelled: false,
879        })
880    }
881}
882
883impl DecisionModel for Order {
884    type Event = Fulfilment;
885
886    fn scope(&self) -> &Tags {
887        &self.scope
888    }
889
890    fn apply(&mut self, event: Self::Event) {
891        match event {
892            Fulfilment::OrderPlaced { sku, quantity, .. } => self.held = Some((sku, quantity)),
893            Fulfilment::OrderDispatched { .. } => self.dispatched = true,
894            Fulfilment::OrderCancelled { .. } => self.cancelled = true,
895            // A stock receipt carries no `order` tag, so this model's query
896            // never nominates one. The arm exists for exhaustiveness.
897            Fulfilment::StockReceived { .. } => {}
898        }
899    }
900}
901
902// ---------------------------------------------------------------------------
903// The four command handlers
904// ---------------------------------------------------------------------------
905
906/// Puts units on the shelf.
907async fn receive_stock(events: &SqliteEventStore, sku: &str, quantity: u32) -> Result<()> {
908    let sku = Sku::new(sku)?;
909    let boundary = Stock::new(&sku)?;
910
911    commit(
912        events,
913        boundary,
914        Retry::attempts(ATTEMPTS.try_into()?),
915        |_shelf: &Stock| {
916            if quantity == 0 {
917                return Err(Refusal::ZeroQuantity {
918                    sku: sku.id.clone(),
919                });
920            }
921            Ok(vec![Fulfilment::StockReceived {
922                sku: sku.clone(),
923                quantity,
924            }])
925        },
926    )
927    .await
928    .map(|_| ())
929    .map_err(rejected)
930}
931
932/// Takes units off the shelf for an order that does not exist yet.
933///
934/// The one decision here that spans two entities: *can the shelf cover it* is
935/// the SKU's concern and *is this reference already in use* is the order's, and
936/// the tuple is both, OR'd into one query and checked by one append condition.
937/// This example does not dwell on it — `handles-and-quotas` is where the
938/// composition argument is made — but the shelf number every view below is
939/// derived from is only trustworthy because this boundary is drawn correctly.
940async fn place_order(
941    events: &SqliteEventStore,
942    order: &str,
943    sku: &str,
944    quantity: u32,
945) -> Result<()> {
946    let order = OrderId::new(order)?;
947    let sku = Sku::new(sku)?;
948    let boundary = (Stock::new(&sku)?, Order::new(&order)?);
949
950    commit(
951        events,
952        boundary,
953        Retry::attempts(ATTEMPTS.try_into()?),
954        |(shelf, existing): &(Stock, Order)| {
955            if existing.held.is_some() {
956                return Err(Refusal::AlreadyPlaced {
957                    order: order.id.clone(),
958                });
959            }
960            if shelf.on_hand < i64::from(quantity) {
961                return Err(Refusal::OutOfStock {
962                    sku: sku.id.clone(),
963                    on_hand: shelf.on_hand,
964                    needed: quantity,
965                });
966            }
967            Ok(vec![Fulfilment::OrderPlaced {
968                order: order.clone(),
969                sku: sku.clone(),
970                quantity,
971            }])
972        },
973    )
974    .await
975    .map(|_| ())
976    .map_err(rejected)
977}
978
979/// Sends an order out, on a named day.
980async fn dispatch_order(events: &SqliteEventStore, order: &str, day: &str) -> Result<()> {
981    let order = OrderId::new(order)?;
982    let boundary = Order::new(&order)?;
983
984    commit(
985        events,
986        boundary,
987        Retry::attempts(ATTEMPTS.try_into()?),
988        |state: &Order| {
989            let Some((sku, quantity)) = state.held.clone() else {
990                return Err(Refusal::NotPlaced {
991                    order: order.id.clone(),
992                });
993            };
994            if state.dispatched {
995                return Err(Refusal::AlreadyDispatched {
996                    order: order.id.clone(),
997                });
998            }
999            if state.cancelled {
1000                return Err(Refusal::AlreadyCancelled {
1001                    order: order.id.clone(),
1002                });
1003            }
1004            Ok(vec![Fulfilment::OrderDispatched {
1005                order: order.clone(),
1006                sku,
1007                quantity,
1008                day: day.to_owned(),
1009            }])
1010        },
1011    )
1012    .await
1013    .map(|_| ())
1014    .map_err(rejected)
1015}
1016
1017/// Calls an order off and puts its units back.
1018async fn cancel_order(events: &SqliteEventStore, order: &str) -> Result<()> {
1019    let order = OrderId::new(order)?;
1020    let boundary = Order::new(&order)?;
1021
1022    commit(
1023        events,
1024        boundary,
1025        Retry::attempts(ATTEMPTS.try_into()?),
1026        |state: &Order| {
1027            let Some((sku, quantity)) = state.held.clone() else {
1028                return Err(Refusal::NotPlaced {
1029                    order: order.id.clone(),
1030                });
1031            };
1032            if state.dispatched {
1033                return Err(Refusal::AlreadyDispatched {
1034                    order: order.id.clone(),
1035                });
1036            }
1037            if state.cancelled {
1038                return Err(Refusal::AlreadyCancelled {
1039                    order: order.id.clone(),
1040                });
1041            }
1042            Ok(vec![Fulfilment::OrderCancelled {
1043                order: order.clone(),
1044                sku,
1045                quantity,
1046            }])
1047        },
1048    )
1049    .await
1050    .map(|_| ())
1051    .map_err(rejected)
1052}
1053
1054// ---------------------------------------------------------------------------
1055// The four views
1056// ---------------------------------------------------------------------------
1057
1058/// Units on the shelf, per SKU.
1059///
1060/// The fold carries **no state of its own** and writes a *delta* against the
1061/// row. That is deliberate rather than minimal: a runner resumes from its
1062/// checkpoint, so a projection holding a running total in memory would start
1063/// from zero and write absolute numbers wrong by everything it did not replay.
1064/// It is also what makes the chunk-size invariance above true.
1065#[derive(Debug)]
1066struct StockOnHand {
1067    /// Which read model this is, within the projection store.
1068    id: ProjectionId,
1069    /// Every event, so the tags constrain nothing.
1070    scope: Tags,
1071}
1072
1073/// The stock view's projection id. A free `const`, so the compiler validates
1074/// it: an invalid id here is a build error, not a crash at start-up.
1075const STOCK_ON_HAND: ProjectionId = ProjectionId::from_static("stock_on_hand");
1076
1077impl StockOnHand {
1078    /// The view over every SKU.
1079    fn new() -> Self {
1080        Self {
1081            id: STOCK_ON_HAND,
1082            scope: Tags::empty(),
1083        }
1084    }
1085}
1086
1087impl Projection for StockOnHand {
1088    type Event = Fulfilment;
1089    type Store = SqliteProjectionStore;
1090    type Error = SqliteProjectionStoreError;
1091
1092    fn id(&self) -> &ProjectionId {
1093        &self.id
1094    }
1095
1096    fn scope(&self) -> &Tags {
1097        &self.scope
1098    }
1099
1100    async fn apply(
1101        &mut self,
1102        event: Delivered<Fulfilment>,
1103        batch: &mut SqliteBatch,
1104    ) -> Result<(), SqliteProjectionStoreError> {
1105        let (sku, delta) = match event.into_event() {
1106            Fulfilment::StockReceived { sku, quantity }
1107            | Fulfilment::OrderCancelled { sku, quantity, .. } => (sku, i64::from(quantity)),
1108            Fulfilment::OrderPlaced { sku, quantity, .. } => (sku, -i64::from(quantity)),
1109            Fulfilment::OrderDispatched { sku, .. } => (sku, 0),
1110        };
1111
1112        batch.push(
1113            "INSERT INTO stock_on_hand (sku, on_hand) VALUES (?1, ?2) \
1114             ON CONFLICT(sku) \
1115             DO UPDATE SET on_hand = stock_on_hand.on_hand + excluded.on_hand",
1116            [Value::Text(sku.into()), Value::Integer(delta)],
1117        );
1118
1119        Ok(())
1120    }
1121}
1122
1123/// Where each order has got to.
1124///
1125/// Unlike the shelf, this view writes an *absolute* value: the status is the
1126/// last one seen, not an accumulation, so replaying it from any checkpoint
1127/// lands on the same answer.
1128#[derive(Debug)]
1129struct OrderStatus {
1130    /// Which read model this is, within the projection store.
1131    id: ProjectionId,
1132    /// Every event, so the tags constrain nothing.
1133    scope: Tags,
1134}
1135
1136/// The order view's projection id.
1137const ORDER_STATUS: ProjectionId = ProjectionId::from_static("order_status");
1138
1139impl OrderStatus {
1140    /// The view over every order.
1141    fn new() -> Self {
1142        Self {
1143            id: ORDER_STATUS,
1144            scope: Tags::empty(),
1145        }
1146    }
1147}
1148
1149impl Projection for OrderStatus {
1150    type Event = Fulfilment;
1151    type Store = SqliteProjectionStore;
1152    type Error = SqliteProjectionStoreError;
1153
1154    fn id(&self) -> &ProjectionId {
1155        &self.id
1156    }
1157
1158    fn scope(&self) -> &Tags {
1159        &self.scope
1160    }
1161
1162    async fn apply(
1163        &mut self,
1164        event: Delivered<Fulfilment>,
1165        batch: &mut SqliteBatch,
1166    ) -> Result<(), SqliteProjectionStoreError> {
1167        let (order, status, sku, quantity) = match event.into_event() {
1168            Fulfilment::OrderPlaced {
1169                order,
1170                sku,
1171                quantity,
1172            } => (order, "placed", sku, quantity),
1173            Fulfilment::OrderDispatched {
1174                order,
1175                sku,
1176                quantity,
1177                ..
1178            } => (order, "dispatched", sku, quantity),
1179            Fulfilment::OrderCancelled {
1180                order,
1181                sku,
1182                quantity,
1183            } => (order, "cancelled", sku, quantity),
1184            // Nominated and ignored. The derived query is the event set crossed
1185            // with the scope, and this view's scope is empty, so a stock
1186            // receipt arrives here whether it is wanted or not — the checkpoint
1187            // still advances past it, which is what "the position considered"
1188            // means.
1189            Fulfilment::StockReceived { .. } => return Ok(()),
1190        };
1191
1192        batch.push(
1193            "INSERT INTO order_status (order_ref, status, sku, quantity) \
1194             VALUES (?1, ?2, ?3, ?4) \
1195             ON CONFLICT(order_ref) DO UPDATE SET status = excluded.status",
1196            [
1197                Value::Text(order.into()),
1198                Value::Text(status.to_owned()),
1199                Value::Text(sku.into()),
1200                Value::Integer(i64::from(quantity)),
1201            ],
1202        );
1203
1204        Ok(())
1205    }
1206}
1207
1208/// The upsert into the first table, and into the second.
1209///
1210/// Two constants rather than one `format!` over a table name, and the reason is
1211/// [`SqliteBatch::push`], which takes `&'static str`. Interpolating a
1212/// table name here was *safe* — it was a `&'static str` chosen by one of the
1213/// three constructors below and could never hold user input — but that safety
1214/// lived in a comment, and a comment is what the signature stopped accepting.
1215/// The two statements differ in one identifier, which is exactly the amount of
1216/// duplication that buys the property.
1217///
1218/// [`push_raw_sql`](SqliteBatch::push_raw_sql) is the escape hatch for
1219/// a statement whose *shape* is decided at run time — an `IN (…)` list sized by
1220/// how many keys are being written. This one's shape is not: only which of two
1221/// fixed statements runs is decided at run time, and that is a choice between
1222/// constants rather than a statement built from a value.
1223const UPSERT_DAILY_DISPATCHES: &str = "INSERT INTO daily_dispatches (day, dispatched) VALUES (?1, ?2) \
1224     ON CONFLICT(day) \
1225     DO UPDATE SET dispatched = daily_dispatches.dispatched + excluded.dispatched";
1226
1227/// The same statement against the backfill's own table. See
1228/// [`UPSERT_DAILY_DISPATCHES`] for why this is a second constant.
1229const UPSERT_DAILY_DISPATCHES_V2: &str = "INSERT INTO daily_dispatches_v2 (day, dispatched) VALUES (?1, ?2) \
1230     ON CONFLICT(day) \
1231     DO UPDATE SET dispatched = daily_dispatches_v2.dispatched + excluded.dispatched";
1232
1233/// The blue/green swap, run as the retiring view's reset batch.
1234///
1235/// No `DELETE` first: the drop takes blue's rows with it. A delete naming
1236/// `daily_dispatches` would be a hazard rather than a redundancy anywhere after
1237/// the rename, because the name by then belongs to green.
1238const PROMOTION: [&str; 2] = [
1239    "DROP TABLE daily_dispatches",
1240    "ALTER TABLE daily_dispatches_v2 RENAME TO daily_dispatches",
1241];
1242
1243/// The same swap with the new table's name mistyped, so it fails *after* the
1244/// drop has run — the one point at which a promotion split across two
1245/// transactions would already have committed blue's retirement.
1246const MISTYPED_PROMOTION: [&str; 2] = [
1247    "DROP TABLE daily_dispatches",
1248    "ALTER TABLE daily_dispatch_v2 RENAME TO daily_dispatches",
1249];
1250
1251/// How much went out each day, counted one of two ways.
1252///
1253/// One type with two configurations rather than two types, because the blue
1254/// and green halves of a rebuild differ in exactly the way a real one does:
1255/// the fold changed its mind about what it was counting, and everything else
1256/// stayed put.
1257#[derive(Debug)]
1258struct DailyDispatches {
1259    /// Which read model this is. **It does not change when the table is
1260    /// promoted** — the checkpoint is keyed by this name and the derived
1261    /// query, and renaming it to match the promoted table would discard the
1262    /// resume point.
1263    id: ProjectionId,
1264    /// Every event, so the tags constrain nothing.
1265    scope: Tags,
1266    /// The upsert this instance issues, and with it the table it writes into.
1267    upsert: &'static str,
1268    /// What one dispatch adds to its day.
1269    counting: Counting,
1270}
1271
1272/// What one dispatch adds to its day's total.
1273#[derive(Debug, Clone, Copy)]
1274enum Counting {
1275    /// One per order that went out.
1276    Orders,
1277    /// One per unit that went out.
1278    Units,
1279}
1280
1281/// The first attempt's projection id.
1282const DAILY_DISPATCHES: ProjectionId = ProjectionId::from_static("daily_dispatches");
1283
1284/// The replacement's projection id, kept across the promotion: the checkpoint
1285/// travels with the id, not with the table.
1286const DAILY_DISPATCHES_V2: ProjectionId = ProjectionId::from_static("daily_dispatches_v2");
1287
1288impl DailyDispatches {
1289    /// The first attempt: one per order.
1290    fn counting_orders() -> Self {
1291        Self {
1292            id: DAILY_DISPATCHES,
1293            scope: Tags::empty(),
1294            upsert: UPSERT_DAILY_DISPATCHES,
1295            counting: Counting::Orders,
1296        }
1297    }
1298
1299    /// The replacement, backfilled beside the first into its own table.
1300    fn counting_units() -> Self {
1301        Self {
1302            id: DAILY_DISPATCHES_V2,
1303            scope: Tags::empty(),
1304            upsert: UPSERT_DAILY_DISPATCHES_V2,
1305            counting: Counting::Units,
1306        }
1307    }
1308
1309    /// The replacement after the swap: the same id, the promoted table.
1310    fn promoted() -> Self {
1311        Self {
1312            id: DAILY_DISPATCHES_V2,
1313            scope: Tags::empty(),
1314            upsert: UPSERT_DAILY_DISPATCHES,
1315            counting: Counting::Units,
1316        }
1317    }
1318}
1319
1320impl Projection for DailyDispatches {
1321    type Event = Fulfilment;
1322    type Store = SqliteProjectionStore;
1323    type Error = SqliteProjectionStoreError;
1324
1325    fn id(&self) -> &ProjectionId {
1326        &self.id
1327    }
1328
1329    fn scope(&self) -> &Tags {
1330        &self.scope
1331    }
1332
1333    async fn apply(
1334        &mut self,
1335        event: Delivered<Fulfilment>,
1336        batch: &mut SqliteBatch,
1337    ) -> Result<(), SqliteProjectionStoreError> {
1338        let (day, delta) = match event.into_event() {
1339            Fulfilment::OrderDispatched { day, quantity, .. } => match self.counting {
1340                Counting::Orders => (day, 1),
1341                Counting::Units => (day, i64::from(quantity)),
1342            },
1343            // Nominated and ignored, for the reason `order_status` gives.
1344            Fulfilment::StockReceived { .. }
1345            | Fulfilment::OrderPlaced { .. }
1346            | Fulfilment::OrderCancelled { .. } => return Ok(()),
1347        };
1348
1349        // Which of the two constants runs is the whole of what this instance's
1350        // configuration decides. SQLite binds values and not identifiers, so a
1351        // table name can only ever reach a statement by being part of its text —
1352        // which is why the statement, and not the name, is the thing chosen.
1353        batch.push(self.upsert, [Value::Text(day), Value::Integer(delta)]);
1354
1355        Ok(())
1356    }
1357}
1358
1359/// The view that was written against a field the log does not carry.
1360///
1361/// It compiles, its query is well formed, and it nominates exactly the events
1362/// it means to. The disagreement is in the payload, and the payload is the one
1363/// thing no signature describes.
1364#[derive(Debug)]
1365struct Couriered {
1366    /// Which read model this is, within the projection store.
1367    id: ProjectionId,
1368    /// Every dispatch, so the tags constrain nothing.
1369    scope: Tags,
1370}
1371
1372/// The courier view's projection id.
1373const COURIERED: ProjectionId = ProjectionId::from_static("couriered");
1374
1375impl Couriered {
1376    /// The view over every dispatch.
1377    fn new() -> Self {
1378        Self {
1379            id: COURIERED,
1380            scope: Tags::empty(),
1381        }
1382    }
1383}
1384
1385impl Projection for Couriered {
1386    type Event = Handover;
1387    type Store = SqliteProjectionStore;
1388    type Error = SqliteProjectionStoreError;
1389
1390    fn id(&self) -> &ProjectionId {
1391        &self.id
1392    }
1393
1394    fn scope(&self) -> &Tags {
1395        &self.scope
1396    }
1397
1398    async fn apply(
1399        &mut self,
1400        event: Delivered<Handover>,
1401        batch: &mut SqliteBatch,
1402    ) -> Result<(), SqliteProjectionStoreError> {
1403        let Handover::OrderDispatched { order, courier } = event.into_event();
1404
1405        batch.push(
1406            "INSERT INTO couriered (order_ref, courier) VALUES (?1, ?2) \
1407             ON CONFLICT(order_ref) DO UPDATE SET courier = excluded.courier",
1408            [Value::Text(order.into()), Value::Text(courier)],
1409        );
1410
1411        Ok(())
1412    }
1413}
1414
1415// ---------------------------------------------------------------------------
1416// Driving views, and reporting on them
1417// ---------------------------------------------------------------------------
1418
1419/// Brings one view up to date and reports how much it applied.
1420///
1421/// Generic over the projection rather than written four times, and generic is
1422/// as far as it can go: `Projection` has an associated event type and an
1423/// associated store, so there is no `dyn Projection` to put in a registry and
1424/// no loop to write. A heterogeneous set of views is a sequence of calls, and
1425/// that is a property of the port, not a shortcoming of this file.
1426///
1427/// `P::Error: Send + Sync` because `anyhow` asks it of every error `?` moves
1428/// in, and a projection's own error carries no such bound by design: a
1429/// `!Send` application is allowed one.
1430async fn drive<P>(
1431    events: &SqliteEventStore,
1432    models: &SqliteProjectionStore,
1433    projection: &mut P,
1434    chunk: usize,
1435) -> Result<usize>
1436where
1437    P: Projection<Store = SqliteProjectionStore>,
1438    P::Error: Send + Sync,
1439{
1440    let chunk = Chunk::of(chunk.try_into()?);
1441    let progress = run_projection(events, models, projection, &Json, chunk).await?;
1442    Ok(progress.applied)
1443}
1444
1445/// Runs the broken view, which is expected to fail, and says where it stopped.
1446///
1447/// Returns the position and the decoder's own message. A run that *succeeded*
1448/// would be the interesting failure — it would mean the log had grown a
1449/// `courier` field nobody in this file wrote — so it is refused out loud
1450/// rather than reported as a pass.
1451async fn poison(
1452    events: &SqliteEventStore,
1453    models: &SqliteProjectionStore,
1454    projection: &mut Couriered,
1455) -> Result<(u64, String)> {
1456    let chunk = Chunk::of(CHUNK.try_into()?);
1457    match run_projection(events, models, projection, &Json, chunk).await {
1458        Ok(progress) => bail!(
1459            "the couriered view decoded {} event(s) it could not have",
1460            progress.applied
1461        ),
1462        Err(ProjectionError::Decode {
1463            position, source, ..
1464        }) => Ok((position.get(), error_chain(&source))),
1465        // `ProjectionError` is `#[non_exhaustive]`. A read failure or a commit
1466        // failure here would be a different defect wearing this one's clothes.
1467        Err(other) => bail!("expected a decode failure, got: {other}"),
1468    }
1469}
1470
1471/// Renders an error and everything under it, joined by `: `.
1472///
1473/// `CodecError`'s own `Display` says the payload could not be decoded, which
1474/// is a category. The value a reader needs — *which field was missing* — is
1475/// one link down the source chain, and a message that stops at the top of that
1476/// chain is the same defect `rejected` exists to avoid one layer up.
1477fn error_chain(error: &dyn core::error::Error) -> String {
1478    let mut rendered = error.to_string();
1479    let mut source = error.source();
1480
1481    while let Some(cause) = source {
1482        rendered.push_str(": ");
1483        rendered.push_str(&cause.to_string());
1484        source = cause.source();
1485    }
1486
1487    rendered
1488}
1489
1490/// Clears a view's rows and its checkpoint as one unit of work.
1491///
1492/// The statements are the *application's*, because the read model is: the port
1493/// takes a batch and commits it alongside the checkpoint reset, and it has no
1494/// idea which tables this program invented. Used for the two things reset is
1495/// actually for — retiring a view, and preparing a rebuild — and a retirement
1496/// may carry a blue/green swap, which is what puts the swap in the same
1497/// transaction as the checkpoint it retires.
1498///
1499/// A slice of statements rather than one string of several: the batch runs one
1500/// statement per `push`, and rusqlite refuses a push that holds two with
1501/// `MultipleStatement` — at commit, after the batch has left this function.
1502///
1503/// It takes the projection rather than an id, so the reset names the id the
1504/// runner commits under, `checkpoint_id`. A reset of `projection.id()`, the
1505/// bare name, clears a row the runner never wrote and leaves its checkpoint
1506/// standing.
1507async fn retire<P: Projection>(
1508    models: &SqliteProjectionStore,
1509    projection: &P,
1510    statements: &[&'static str],
1511) -> Result<()> {
1512    let key = checkpoint_id(projection)?;
1513    let mut batch = models.begin().await?;
1514    for statement in statements {
1515        batch.push(statement, []);
1516    }
1517    models.reset(batch, &key).await?;
1518    Ok(())
1519}
1520
1521/// Prints where a view has got to, under its name.
1522///
1523/// Read through `checkpoint_id` for the reason `retire` resets through it:
1524/// the bare name reads `never run` whatever the runner did.
1525async fn print_checkpoint<P: Projection>(
1526    models: &SqliteProjectionStore,
1527    projection: &P,
1528) -> Result<()> {
1529    let name = projection.id();
1530    let checkpoint = render_checkpoint(models.checkpoint(&checkpoint_id(projection)?).await?);
1531    writeln!(io::stdout().lock(), "   {name} is {checkpoint}")?;
1532    Ok(())
1533}
1534
1535/// Renders a checkpoint as the transcript prints it.
1536fn render_checkpoint(checkpoint: Checkpoint) -> String {
1537    match checkpoint {
1538        Checkpoint::NeverRun => "never run".to_owned(),
1539        Checkpoint::Live { through } => format!("live through {through}"),
1540        Checkpoint::Rebuilding { through } => format!("rebuilding through {through}"),
1541        // `Checkpoint` is `#[non_exhaustive]`, so the wildcard is required. It
1542        // is not laziness: a fourth state added upstream must not silently
1543        // render as one of these three.
1544        other => format!("{other:?}"),
1545    }
1546}
1547
1548// ---------------------------------------------------------------------------
1549// Reading what the views wrote
1550// ---------------------------------------------------------------------------
1551
1552/// Prints a read-model query's rows, three spaces in.
1553fn print_table(app: &Connection, sql: &str) -> Result<()> {
1554    let rows = render_table(app, sql)?;
1555    write!(io::stdout().lock(), "{rows}")?;
1556    Ok(())
1557}
1558
1559/// Renders a read-model query's rows, so two of them can be compared.
1560///
1561/// Every column comes back as a `rusqlite::types::Value` rather than as a
1562/// typed `get`, because this one function serves five tables with different
1563/// column types and a typed read would need one function per table.
1564fn render_table(app: &Connection, sql: &str) -> Result<String> {
1565    let mut statement = app.prepare(sql)?;
1566    let columns = statement.column_count();
1567    let mut rows = statement.query([])?;
1568    let mut rendered = String::new();
1569
1570    while let Some(row) = rows.next()? {
1571        let mut cells = Vec::with_capacity(columns);
1572        for index in 0..columns {
1573            cells.push(render_cell(&row.get::<_, Value>(index)?));
1574        }
1575        rendered.push_str("      ");
1576        rendered.push_str(&cells.join("  "));
1577        rendered.push('\n');
1578    }
1579
1580    Ok(rendered)
1581}
1582
1583/// Renders one cell of a read-model row.
1584fn render_cell(value: &Value) -> String {
1585    match value {
1586        Value::Null => "NULL".to_owned(),
1587        Value::Integer(number) => format!("{number}"),
1588        Value::Real(number) => format!("{number}"),
1589        Value::Text(text) => text.clone(),
1590        Value::Blob(bytes) => format!("<{} bytes>", bytes.len()),
1591    }
1592}
1593
1594/// Prints every event in the store, in the order the store assigned.
1595async fn print_log(events: &SqliteEventStore) -> Result<()> {
1596    let log = collect(events.read(&Query::all(), ReadOptions::new())).await?;
1597
1598    for event in log {
1599        writeln!(
1600            io::stdout().lock(),
1601            "   {:>3}  {:<16} {:?}",
1602            event.position.get(),
1603            event.event_type().as_str(),
1604            event.tags()
1605        )?;
1606    }
1607
1608    Ok(())
1609}
1610
1611// ---------------------------------------------------------------------------
1612// The file this run owns
1613// ---------------------------------------------------------------------------
1614
1615/// Where this run's database lives.
1616///
1617/// Under the process id, so a `cargo run` and the test that spawns the binary
1618/// never meet on one file.
1619fn database_path() -> PathBuf {
1620    std::env::temp_dir().join(format!("happenstance-rebuilding-{}.db", std::process::id()))
1621}
1622
1623/// Removes the database and the two files WAL mode keeps beside it.
1624///
1625/// Deleting only the `.db` and leaving `-wal` behind is how a "fresh" run
1626/// starts on the tail of the last one.
1627fn remove_database(path: &Path) {
1628    for suffix in ["", "-wal", "-shm"] {
1629        let mut name = path.as_os_str().to_owned();
1630        name.push(suffix);
1631        drop(std::fs::remove_file(PathBuf::from(name)));
1632    }
1633}
1634
1635/// Renders a command failure as the message the transcript prints.
1636///
1637/// `CommandError::Refused` carries the handler's *own* refusal, and that is
1638/// what a reader must see: `CommandError`'s own `Display` says "the decision
1639/// refused", which is a category rather than a value.
1640fn rejected(err: CommandError<SqliteEventStoreError, Refusal>) -> anyhow::Error {
1641    match err {
1642        CommandError::Refused(refusal) => refusal.into(),
1643        other => other.into(),
1644    }
1645}