ingraph 0.1.0

A declaration-driven indexing framework: records and nodes are written as Rust types, and the storage rows, the dataflow between them and the GraphQL query surface are emitted from the declaration.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
//! The journal: how far a content ROOT got through a node.
//!
//! **A journal of FINAL STATES, keyed `(root, node)`, each entry replaced in place — not an append
//! log.**
//!
//! That is the organ's whole semantics and the reason for its name, and it is worth stating before
//! anything else because the word invites the other reading: a journal in the everyday sense
//! ACCUMULATES, and this one does not. What is kept is where a root GOT TO through a node — one
//! entry per pair — and the next observation about that pair overwrites the entry rather than
//! adding to a history. A deployment wanting the append log is keeping a different table, and
//! nothing here is it.
//!
//! One row per `(root, node)`, written by KEYED REPLACE — the LAST state. `|roots| × |nodes|` rows,
//! activity-independent, and a replayed observation overwrites the row it wrote last time rather
//! than appending a second one.
//!
//! # Where the root comes from, now that nothing carries one
//!
//! Nothing on the WIRE does, and nothing here changes that: an edge moves the app's own declared
//! struct and [`ItemId`](super::ItemId) is a transport token that is meaningless across two senders.
//! What the framework cannot do is read a root out of a type it does not know — and what it can do
//! is take a PROJECTION from the party that does. A declared key is lineage-shaped, root-first, so
//! *the root of this record* is a field access at the node's own type, supplied by the emitted
//! wrapper and typed at compile time. [`Attributes`] is the seam that projection arrives through.
//!
//! # Two writers, and they promise different things
//!
//! - The **strong half** is a node's own COMPLETION, and it never goes through a tap. A node that
//!   can re-read itself writes its row in the transaction that moves its cursor — that is
//!   [`Positions::advance`](super::Positions::advance), which takes the rows beside the position —
//!   and a node that cannot writes a lone upsert through [`Ledger`]. Either way the write happens
//!   before the ack it certifies goes out, and a refusal makes the delivery a failure.
//! - The **diagnostic half** is everything else — a refusal, a failure, a station a node passed
//!   through — and it is best effort by construction: [`JournalTap`] builds a row and offers it to a
//!   bounded [`JournalQueue`], and a [`JournalWriter`] somewhere else drains it. A full queue DROPS, and the
//!   drop is harmless because the row is keyed: the next observation for that `(root, node)`
//!   overwrites whatever the dropped one would have written.
//!
//! The line between them is FINAL STATES. A station that SETTLES is a completion and earns a row
//! that cannot be lost; a [`Failed`](super::Lifecycle::Failed) holds the window and will be tried
//! again, so putting it in the half that cannot be dropped would write a non-final state the
//! successful retry would then have to un-write. That division is also what keeps the tap contract
//! from bending: the half that must land is not an observation at all — it is the node's own write,
//! made in a transaction it was already making.
//!
//! # The row is the application's, and the framework only says how to build one
//!
//! [`JournalRow`] is the whole contract, and both writers go through it. A deployment that wants its own
//! columns — or its own table, or none at all — implements it on its own declared record and changes
//! nothing else.

use core::{future::Future, time::Duration};

use std::time::SystemTime;

use super::{NodeName, lifecycle::Arrival};

/// The per-node hook: what a record this node emitted descends from, and where an observation about
/// that record goes.
///
/// # One seam, because the loop asks one thing
///
/// Two questions cross it — project this record's root, take this answer — and they are one seam
/// because they are one fact from the loop's vantage: *how this node attributes its outputs, and
/// where the attribution goes*. The DECOMPOSITION is the implementation's and it is real: the
/// projection is per node, and whatever the observations go to is shared by every node of a root
/// family — which is exactly what a composing implementation holds two of.
///
/// # The root is TYPED, and fixed per node
///
/// A node's chain root is a compile-time fact — a keyframe descends from a media and never from
/// anything else — so [`Root`](Self::Root) is an associated type and never an erased id. Journal
/// tables are per ROOT FAMILY, and the root columns are the root key's own real columns.
///
/// # Queue and return
///
/// [`observe`](Self::observe) is called from inside a resident's loop and may not block it, exactly
/// as [`LifecycleTap`](super::LifecycleTap) may not. An implementation that writes to a store
/// queues the write and returns; a full queue DROPS, and the drop costs nothing because the row it
/// would have written is replaced by the next one for the same key.
///
/// # Absence is `()`
///
/// A node with no projection wired carries `()`, on [`AsyncLands`](super::AsyncLands)' precedent. Its
/// observations stay COUNTER-GRADE — a [`LifecycleTap`](super::LifecycleTap) still sees every one
/// of them, with the station and the info and no root — which is a legal deployment, and the one a
/// node whose payload has no declared key is left with.
///
/// # WHICH implementation a launched node wears, and the two roads to it
///
/// A DECLARATION states it: [`Declared::Attribution`](super::Declared::Attribution) is the seat and
/// the `attributed` word is what fills it, with
/// [`RootProjection<Out>`](crate::RootProjection) — whose impl every declared record emits beside
/// itself — for the node that wrote the word and `()` for the node that did not.
/// [`Wiring::resident`](super::Wiring::resident) installs whatever the seat names, on every
/// buffered node it wires and with no branch of its own.
///
/// A DEPLOYMENT attaches one: [`Resident::attributing`](crate::Resident::attributing) takes any
/// value implementing this trait, which is the road for an attribution that carries state — a
/// journal writer, a queue, a handle — since no walk can mint one of those from a type alone. It
/// runs after the seat and replaces what the seat installed, so the two compose rather than
/// compete.
pub trait Attributes<T> {
  /// **THIS ROOT FAMILY'S OWN NAME** — the lowercase spelling of the root type, `media` for
  /// `MediaId`, and the only thing a [`TypeId`](std::any::TypeId) cannot supply about a family.
  ///
  /// What reads it is [`Registries::open`](crate::Registries::open), which resolves a family's own
  /// `[registry.<family>]` override against it. Nothing else does, and nothing checks it against a
  /// roster: the family table is open by ruling, so a spelling nothing matches is an override
  /// nobody asks for rather than a refusal.
  ///
  /// It DEFAULTS to the empty string, which is *unnamed — read the registry's own defaults*, and
  /// that is what every projection written before there was a registry to name one keeps saying.
  /// [`RegistryOptions::for_family`](crate::RegistryOptions::for_family) is total on the family, so
  /// an empty name resolves to the shipped defaults exactly as an unwritten section does.
  const FAMILY: &'static str = "";

  /// The chain-root key this node's records descend from.
  type Root;

  /// The root `record` descends from — a field access on the record's declared key.
  fn root(&self, record: &T) -> Self::Root;

  /// Take one observation about `root`, as answered by `worker`. Queue and return.
  fn observe(&self, root: &Self::Root, worker: &NodeName, arrival: &Arrival);
}

/// No attribution — the node's observations stay counter-grade.
///
/// It is the absence spelled as a type rather than an `Option`, so a node that wires no projection
/// pays no branch and the loop is written once. Both methods are the empty program, and `Root = ()`
/// is what makes a row builder needing a real root unsatisfiable at the WIRING rather than at run
/// time.
///
/// It is also what makes the launch's install UNCONDITIONAL. The blanket is over EVERY `T`, so a
/// declaration that seats `()` at [`Declared::Attribution`](super::Declared::Attribution) satisfies
/// the wiring's bound whatever its output turns out to be — which is why the walk writes one line
/// for the whole catalog rather than a branch it has no way to take.
impl<T> Attributes<T> for () {
  type Root = ();

  #[inline(always)]
  fn root(&self, _record: &T) {}

  #[inline(always)]
  fn observe(&self, _root: &(), _worker: &NodeName, _arrival: &Arrival) {}
}

/// How a journal row is BUILT — the whole of what the framework says about the row's shape.
///
/// The row is the APPLICATION's own declared record, so the framework knows four things about it:
/// the root it is keyed by, the node that did the work, what was observed, and when. This is the
/// contract that hands those four over, and every writer goes through it, so two writers can never
/// disagree about what a row means.
///
/// # The key is already the derive's
///
/// `key = lineage ⊕ id` is a law of a declared record, so a journal whose lineage is the ROOT's
/// columns and whose id is the NODE's name gets `(root, node)` as its emitted key with nothing
/// written for it — and the keyed replace that makes the entry the LAST STATE is the ordinary write of
/// that key. That is why this contract says nothing about keys: the declaration already did.
///
/// **The STATEMENT that performs it is the store's own, and this is worth knowing before reaching
/// for the obvious helper.** `query::sql::upsert`'s conflict target is `SqlQuery::ADDRESS`, which a
/// record's expansion emits as ONE column — the id — on the reasoning that an id already names at
/// most one row. A journal's id is a node NAME shared by every root, so that helper addresses the
/// wrong thing and an engine whose table is keyed by the pair refuses it by name rather than
/// collapsing rows. [`Ledger::record`]'s own sentence — *upsert `rows` by their own `(root, node)`
/// key* — has always been the store's to keep, and it still is.
///
/// **And the ruled repair is half the emitter's, which is the half worth naming.** The design answer
/// is that a journal's expansion should write `ADDRESS` as the key rather than as the id, on the
/// reasoning that the address holds a SLICE and its width was always the emitter's choice. That is
/// so on the WRITE side: the conflict target is `ADDRESS`'s key list and `SqlWrite::bind_address` is
/// indexed by position in it, so both would follow a wider address without being asked. It is not so
/// on the read side, where the width is the TRAIT's rather than the expansion's —
/// `SqlQuery::addresses` takes a slice of `Identifiable::Id`, which is the id column alone. So
/// widening one impl's const would leave that impl replacing rows on several columns while its own
/// address PREDICATE names one, and an edge correlation binding one against both. What the repair
/// needs is therefore a move in the record address contract — one address, or two with the write's
/// and the read's told apart — which is the query lane's act and not this organ's.
///
/// # What the implementor decides
///
/// Everything else. Which columns exist, what the observation's info is unpacked into, whether a
/// failure's rendering is kept, what the timestamp's own type is. The framework hands the whole
/// [`Arrival`] rather than a station and a string, because a deployment that knows its own info
/// type asks for it back — which is what the erasure exists for.
///
/// # The ready-made row is a WORD rather than a generic type, and the reason is measured
///
/// ```ignore
/// #[ingraph::journal(root = "MediaId", sqlite)]
/// pub struct VideoJournal;
/// ```
///
/// That is the one-line mount, and what it mounts is a CANONICAL CONCRETE RECORD: a `root` column of
/// the named type, `node`, `station`, and `at` as [`Timestamp`](crate::Timestamp) — plus this
/// contract, plus everything an ordinary declaration emits. The type is the author's to name and
/// queryable like anything else they declared, which is the whole reason it is a type at all.
///
/// A shipped generic `Journal<Root>` was the other candidate and it is not declarable:
/// `#[ingraph::record]` refuses a generic host — *generic records are not supported — a record must
/// be concrete, because a key column's type is read straight off the declaration* — and `Root` is
/// exactly such a type, the emitted `*Key` being built from it. An attribute macro OWNS the item it
/// sits on, so a marker struct can be replaced by a concrete record where a generic one could not be
/// substituted; that is what made the word possible and the type impossible.
///
/// The `at` column needed a citizen before the word could be written. `SystemTime` is what this
/// contract is handed and no storable temporal type existed that every backend could hold, so
/// [`Timestamp`](crate::Timestamp) was minted for it: nanosecond precision, feature-free, stored as
/// two columns on every SQL backend and a sub-document on MongoDB. The mounted `of` crosses into it
/// through the fallible conversion and PANICS rather than substituting — a journal row is durable
/// and is read as *when the node got there*, so a rounded instant would record a moment that never
/// happened, and what reaches that arm is a clock wrong by thousands of years.
///
/// # The HAND path is not replaced by any of that
///
/// The word is SUGAR over this contract. A deployment that wants its own columns — a rendered
/// failure, a refusal's content, a timestamp of its own type — declares an ordinary record and
/// implements [`JournalRow`] on it, exactly as before, and every writer above reaches the two
/// through one seam and cannot tell them apart. The macro's own refusals say so: a host carrying
/// fields is answered by naming this path rather than by reporting a shape error.
pub trait JournalRow<Root> {
  /// The row saying `node` reached `arrival`'s station for `root`, at `at`.
  fn of(root: &Root, node: &NodeName, arrival: &Arrival, at: SystemTime) -> Self;
}

/// The row a deployment keeping NO journal writes.
///
/// A zero-sized row, so building one and holding a page of them costs nothing — which is what lets
/// a writer build rows unconditionally instead of branching on whether anybody wanted them.
impl<Root> JournalRow<Root> for () {
  #[inline(always)]
  fn of(_root: &Root, _unit: &NodeName, _arrival: &Arrival, _at: SystemTime) -> Self {}
}

/// A node's OWN control store — where its completion rows land when it has no durable position to
/// land them with.
///
/// [`Positions`](super::Positions) is the sibling and the commoner case: a node that can re-read
/// itself keeps a cursor, and its completion row is written in the transaction that moves it. A
/// CHANNEL-fed node has no cursor — its inputs came from a sender it cannot ask again — so there is
/// nothing for its row to be atomic WITH, and a single-row upsert stands alone.
///
/// # It is not the diagnostic half, and the difference is what may hold the loop
///
/// [`Attributes::observe`] queues and returns, and a full queue drops. This does neither: the row
/// is the node's own completion, the write happens before the ack it certifies goes out, and a
/// refusal makes the delivery a failure exactly as a refused content write does. That is the whole
/// content of the word STRONG — a journal that could be dropped could not be read as an answer
/// to *did this node finish this root*.
///
/// `&mut self` for [`AsyncLands`](super::AsyncLands)' reason: a control store holds a connection,
/// and a keyed replace over a page is not atomic across two callers.
///
/// # TWO SPELLINGS of one write, which is [`Intake`](super::Intake)'s arrangement one seam over
///
/// [`record`](Self::record) is the THREAD engine's door and [`record_async`](Self::record_async) is
/// the ASYNC engine's, exactly as [`park`](super::Intake::park) and
/// [`park_async`](super::Intake::park_async) already are. The thread engine's landing runs on a
/// thread it owns and can write there directly, so it calls the first and drives no future at all;
/// the async engine awaits the second. One verb in a future shape would have made the thread
/// engine's landing spend a `block_on` for a write it was standing right next to.
///
/// What that costs an IMPLEMENTOR is one extra body, and the shape of it is the backend's own
/// answer rather than this trait's. A blocking store writes in [`record`](Self::record) and wraps a
/// [`ready`](core::future::ready) in [`record_async`](Self::record_async); a store whose only face
/// is a future does the reverse and states its own blocking posture in
/// [`record`](Self::record)'s doc — `SqlitePositions` is that case in the tree.
pub trait Ledger {
  /// The row this store keeps — the deployment's own declared record.
  type Row;

  /// What a refused write reports.
  type Error;

  /// Upsert `rows` by their own `(root, node)` key, atomically — the THREAD engine's door.
  ///
  /// It ANSWERS rather than handing back a future, which is what lets the thread engine's landing
  /// write where it stands.
  fn record(&mut self, rows: &[Self::Row]) -> Result<(), Self::Error>;

  /// [`record`](Self::record) as a future — the ASYNC engine's door, and the same upsert.
  ///
  /// `Send` because it is awaited from inside a resident, and residents are tasks on somebody's
  /// runtime. Spelled as `impl Future + Send` rather than `async fn`, so the bound is part of the
  /// contract instead of something each caller has to hope for.
  fn record_async(
    &mut self,
    rows: &[Self::Row],
  ) -> impl Future<Output = Result<(), Self::Error>> + Send;
}

/// The unused control store — what a node that declared none carries.
///
/// [`AsyncLands for ()`](super::AsyncLands)' face, and the same argument: a resident is generic over its
/// control store, so the absence of one has to be a type. It records nothing, which is not a claim
/// that a row was written — it is the absence of a claim, and a node carrying it stages no row
/// through this seam.
impl Ledger for () {
  type Error = core::convert::Infallible;
  type Row = ();

  #[inline(always)]
  fn record(&mut self, _rows: &[()]) -> Result<(), Self::Error> {
    Ok(())
  }

  #[inline(always)]
  fn record_async(&mut self, _rows: &[()]) -> impl Future<Output = Result<(), Self::Error>> + Send {
    core::future::ready(Ok(()))
  }
}

/// The DIAGNOSTIC half's bounded queue: a non-blocking push that drops the OLDEST when it is full.
///
/// Drop-oldest and not drop-newest, and the reason is what a journal IS. The row is "the last
/// run", replaced by key — so of two observations about one `(root, node)` the later one is the one
/// worth keeping, and dropping the newest would leave the record permanently stale where dropping
/// the oldest leaves it merely behind.
///
/// The capacity is the memory bound and the only one: what is queued is a built ROW and never a
/// payload, and the queue holds at most that many.
///
/// It holds the READ end too, and that is what dropping the oldest is made of — a sender alone
/// cannot take anything back. The consequence is worth knowing: this queue keeps the channel alive,
/// so a writer that has gone away leaves offers succeeding into a buffer nobody drains. That is the
/// correct shape for a best-effort seam — the alternative is an observation path that starts
/// failing because an observer left.
#[derive(Debug)]
pub struct JournalQueue<R> {
  tx: flume::Sender<R>,
  rx: flume::Receiver<R>,
}

impl<R> Clone for JournalQueue<R> {
  #[inline]
  fn clone(&self) -> Self {
    Self {
      tx: self.tx.clone(),
      rx: self.rx.clone(),
    }
  }
}

impl<R> JournalQueue<R> {
  /// Offer `row`, dropping the oldest queued row where there is no space.
  ///
  /// `false` when the row was NOT queued — a racing pusher took the space this call made. That is
  /// not an error and not worth retrying: the row is keyed, so the next observation for the same
  /// `(root, node)` writes what this one would have.
  pub fn offer(&self, row: R) -> bool {
    match self.tx.try_send(row) {
      Ok(()) => true,
      Err(flume::TrySendError::Full(row)) => {
        // The oldest goes and the newest takes its place. `try_recv`/`try_send` rather than `send`,
        // because BLOCKING here is the one thing this queue exists to make impossible.
        self.rx.try_recv().ok();
        self.tx.try_send(row).is_ok()
      }
      Err(flume::TrySendError::Disconnected(_)) => false,
    }
  }

  /// How many rows are queued and not yet drained.
  #[inline]
  #[must_use]
  pub fn len(&self) -> usize {
    self.tx.len()
  }

  /// Whether none is.
  #[inline]
  #[must_use]
  pub fn is_empty(&self) -> bool {
    self.tx.is_empty()
  }
}

/// The draining end of a [`JournalQueue`] — what a [`JournalWriter`] reads.
#[derive(Debug)]
pub struct JournalDrain<R> {
  rx: flume::Receiver<R>,
}

impl<R> JournalDrain<R> {
  /// Wait up to `patience` for a row, then take everything else already queued.
  ///
  /// `None` once every queue holder is gone AND nothing is left, which is what ends a writer's loop.
  /// A wait that expired with nothing queued answers an EMPTY batch rather than `None`: the queue is
  /// still open and a row may yet arrive.
  pub fn take(&self, patience: Duration) -> Option<Vec<R>> {
    let first = match self.rx.recv_timeout(patience) {
      Ok(row) => row,
      Err(flume::RecvTimeoutError::Timeout) => return Some(Vec::new()),
      Err(flume::RecvTimeoutError::Disconnected) => {
        let rest: Vec<R> = self.rx.drain().collect();
        return (!rest.is_empty()).then_some(rest);
      }
    };
    // ONE batch out of everything already waiting: a burst of observations becomes one write, which
    // is the whole reason the diagnostic half is queued rather than written where it is produced.
    let mut batch = vec![first];
    batch.extend(self.rx.drain());
    Some(batch)
  }
}

/// A queue of `capacity` rows and the draining end of it.
#[inline]
#[must_use]
pub fn journal_queue<R>(capacity: usize) -> (JournalQueue<R>, JournalDrain<R>) {
  let (tx, rx) = flume::bounded(capacity);
  (JournalQueue { tx, rx: rx.clone() }, JournalDrain { rx })
}

/// The composition that turns a node's observations into rows: a per-node PROJECTION and the
/// arrangement's QUEUE.
///
/// The two collaborators are what [`Attributes`]' note describes, held side by side. The projection
/// is a plain function pointer because that is all it ever is — a field access on the record's
/// declared key, which an emitted wrapper writes and a test writes by hand — and a pointer keeps the
/// projection's own type out of the resident's parameter list.
#[derive(Debug)]
pub struct JournalTap<T, Root, R> {
  project: fn(&T) -> Root,
  queue: JournalQueue<R>,
}

impl<T, Root, R> JournalTap<T, Root, R> {
  /// Project a record's root with `project`, and offer the rows to `queue`.
  #[inline]
  #[must_use]
  pub const fn new(project: fn(&T) -> Root, queue: JournalQueue<R>) -> Self {
    Self { project, queue }
  }

  /// The queue rows are offered to.
  #[inline]
  #[must_use]
  pub const fn queue(&self) -> &JournalQueue<R> {
    &self.queue
  }
}

impl<T, Root, R> Attributes<T> for JournalTap<T, Root, R>
where
  R: JournalRow<Root>,
{
  type Root = Root;

  #[inline]
  fn root(&self, record: &T) -> Root {
    (self.project)(record)
  }

  fn observe(&self, root: &Root, worker: &NodeName, arrival: &Arrival) {
    // Built HERE and dropped on a full queue, rather than queued raw and built by the writer: an
    // `Arrival` borrows what a tap was shown, so the row is what can travel — and building it is
    // also where the deployment's own contract runs.
    self
      .queue
      .offer(R::of(root, worker, arrival, SystemTime::now()));
  }
}

/// What one [`JournalWriter`] run did.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct Written {
  batches: usize,
  written: usize,
  refused: usize,
}

impl Written {
  /// How many writes it made — a burst of observations is one.
  #[inline]
  #[must_use]
  pub const fn batches(&self) -> usize {
    self.batches
  }

  /// How many rows reached the store.
  #[inline]
  #[must_use]
  pub const fn written(&self) -> usize {
    self.written
  }

  /// How many the store would not take. Nothing is retried: the row is keyed, so the next
  /// observation for the same `(root, node)` writes what a refused one would have.
  #[inline]
  #[must_use]
  pub const fn refused(&self) -> usize {
    self.refused
  }
}

/// The DIAGNOSTIC half's writer: it drains a [`JournalQueue`] somewhere else and writes what it finds.
///
/// Somewhere else is the point. An observation must never be able to backpressure the loop that
/// produced it, so what a resident does is build a row and offer it; this is what turns a page of
/// offers into one write, on a thread or a task of its own.
///
/// The lane is [`AsyncLands`](super::AsyncLands) — the same seam a node's own content write goes through —
/// because the question is the same question: *take these records, say which of them reached the
/// store*. Nothing about the journal needed a second one.
#[derive(Debug)]
pub struct JournalWriter<R, W> {
  drain: JournalDrain<R>,
  lane: W,
  patience: Duration,
}

impl<R, W> JournalWriter<R, W> {
  /// How long a pass waits for a row before looking again.
  ///
  /// A LIVENESS floor and not a latency budget: the queue wakes this writer as soon as a row
  /// arrives, and the timeout exists so a writer whose queue holders are still alive but silent
  /// notices a shutdown rather than parking through it.
  pub const PATIENCE: Duration = Duration::from_millis(250);

  /// Write what `drain` hands over through `lane`.
  #[inline]
  #[must_use]
  pub const fn new(drain: JournalDrain<R>, lane: W) -> Self {
    Self {
      drain,
      lane,
      patience: Self::PATIENCE,
    }
  }

  /// Look at least this often.
  #[inline]
  #[must_use]
  pub const fn with_patience(mut self, patience: Duration) -> Self {
    self.set_patience(patience);
    self
  }

  /// [`with_patience`](Self::with_patience), in place.
  #[inline]
  pub const fn set_patience(&mut self, patience: Duration) -> &mut Self {
    self.patience = patience;
    self
  }

  /// How long a pass waits for a row before looking again.
  #[inline]
  #[must_use]
  pub const fn patience(&self) -> Duration {
    self.patience
  }
}

impl<R, W> JournalWriter<R, W>
where
  W: super::AsyncLands<R>,
{
  /// Drain until every queue holder is gone — the thread engine, for a writer on a thread of its
  /// own.
  pub fn run(&mut self) -> Written {
    let mut report = Written::default();
    while let Some(batch) = self.drain.take(self.patience) {
      if batch.is_empty() {
        continue;
      }
      let commit = super::lane::block_on(self.lane.land(&batch));
      Self::count(&batch, &commit, &mut report);
    }
    report
  }

  /// [`run`](Self::run), awaiting the write.
  pub async fn run_async(&mut self) -> Written {
    let mut report = Written::default();
    while let Some(batch) = self.drain.take(self.patience) {
      if batch.is_empty() {
        continue;
      }
      let commit = self.lane.land(&batch).await;
      Self::count(&batch, &commit, &mut report);
    }
    report
  }

  fn count(batch: &[R], commit: &super::Commit<W::Error>, report: &mut Written) {
    report.batches += 1;
    for position in 0..batch.len() {
      if commit.committed(position) {
        report.written += 1;
      } else {
        report.refused += 1;
      }
    }
  }
}

#[cfg(test)]
mod tests;