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
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
//! The drive layer: what a validated arrangement DOES.
//!
//! [`arrange`](crate::arrange) declares a topology and checks it; nothing there opens a channel or
//! runs an operator. This layer does both. It is BUILT to the 2026-08-08 design record rather than
//! moved from the previous crate, on the user's own ruling — the earlier runtime's premise (every
//! inter-node edge carries a droppable hint and the real input is always a pull) was replaced, and
//! a replaced premise is not a foundation to patch.
//!
//! # Four delivery modes, per upstream, mixable in one fan-in
//!
//! A node names, per inbound upstream, HOW it is fed:
//!
//! - [`Listen::Channel`] — the DEFAULT. `flume` carries the real messages: a [`Delivery`] holds a
//!   [`Payload`] of one item or a batch, and the consumer answers on the paired oneshot with an
//!   [`Ack`]. The data channel is BOUNDED and BLOCKS, so a full channel is backpressure and data is
//!   never dropped.
//! - [`Listen::Changes`] — the upstream STORE's own change feed, behind the [`AsyncChanges`]
//!   capability trait. A store publishes a feed where it has CDC or an ordered pull; a fulltext,
//!   vector or blob store publishes none, and asking one for a feed is `E0277` at the authored
//!   string. The doorbell-plus-pull machinery — a bounded coalescing hint, a `WHERE key > p ORDER
//!   BY key LIMIT n` page, drain-side dedup, a sweep — is the SQLite feed's portable FLOOR rather
//!   than the protocol: a backend with a native feed implements the same trait over its own.
//! - [`Listen::Poll`] — the node's OWN clock over that upstream, one interval per upstream. The first
//!   two are passive: something upstream produces and the node is fed. A garbage collector, a
//!   compactor and a stuck-watermark healer are none of those — they ACT on a schedule, over stores
//!   nobody is writing at that moment — so maintenance becomes ordinary declared topology rather
//!   than a side channel beside the graph. A poll edge carries no messages: a [`Ticked`] names the
//!   upstream that came due and the node reads through the handles its [`Seats`] lending gives it.
//!   See [`poll`](self::poll) for the clock and [`Schedule`] for the intervals.
//! - [`Listen::Transient`] — a QUERY edge. Same `flume` and same oneshot, different semantics: no
//!   ack window, no durable position, no journal, and the oneshot carries the RESULT rather than
//!   an [`Ack`]. It is the SECOND EDGE KIND rather than a fourth way of being fed the first kind's
//!   messages, and it is what makes a query travel declared edges instead of an RPC surface bolted
//!   on beside them. See [`invoke`](self::invoke) for the whole of it.
//!
//! The first three MIX in one fan-in because they all meet at the inbox: a [`ChangeIntake`] pulls
//! its store and sends ordinary deliveries into the consumer's inbox, and a [`Ticker`] puts a tick
//! on the same one — so a node reading a channel, a change feed and its own clock at once is a node
//! with three producers, which is what an MPMC channel already is.
//!
//! The fourth mixes in the fan-in and NOT in the inbox, and that is the read-path law rather than an
//! inconsistency: a query must never queue behind an indexing write batch, so a node that both
//! indexes and answers has a [`QueryArm`] beside its [`Resident`] — two receivers, two loops, two
//! values. An index node subscribing to an indexing node's embeddings AND to a query node's is one
//! node with edges of both kinds, which is exactly the fan-in the ruling describes.
//!
//! # WHAT THE TRANSIENT EDGE IS FOR — and what it is deliberately NOT
//!
//! [`Listen::Transient`] is not a second road the search layer travels. A search TOWER WALK is
//! IN-PROCESS at the search grain: a question resolves its own steps inline, on the caller's stack,
//! with no channel anywhere in the walk itself. That is the default and it stays the default,
//! because a channel between two steps of one question buys a hop and a copy and pays for neither.
//!
//! The transient edge is what a STEP that ALREADY LIVES IN A GRAPH RESIDENT rides. The distinction
//! is residency, not the step's role: a hop whose body is a plain function is a call, and a hop
//! whose body is a node in this graph is reached the way every node is reached — over its declared
//! edge — because the alternative is a second way to address the same value.
//!
//! # The case the column exists for: query-time compute over an EXCLUSIVE model
//!
//! One case makes the whole column load-bearing, and it is worth stating so this edge kind is not
//! read as an unspent second road: a value that is `&mut`-only or `!Send` — an embedding model, a
//! tokenizer holding a scratch arena, a device context — cannot be shared and cannot cross threads,
//! so it can be reached only by the ONE resident that owns it. When the SAME model serves both the
//! indexing flow and the question flow, that resident has to answer two callers. The indexing side
//! reaches it over a durable edge and the question side over a transient one, so the exclusive
//! value is entered from exactly one place and the arm ordering is what
//! [`QueryArm`]-beside-[`Resident`] already gives.
//!
//! ENGINE-RESIDENT DATA is the other half, and it keeps the road it already had: a question that
//! only needs rows out of a store goes through the DOOR THAT HOLDS THE SLOTS —
//! [`SlotLane`] over a branded [`SlotHandle`](crate::SlotHandle) — and never over an edge. A store
//! handle is shareable and a search over one is stateless, so routing it through a resident would
//! add a queue in front of a concurrent reader. The two roads divide on what the answer needs to
//! TOUCH: an exclusive value, or a store.
//!
//! # Residency
//!
//! One resident per node, for the process's life. A [`DriverKind::Thread`](crate::DriverKind) node
//! owns one OS thread — the operator is CONSTRUCTED on it once, so a model context loads once and
//! never migrates — which PARKS in a blocking receive when idle and dies only when its senders
//! disconnect. The async kind is resident the same way over `recv_async`, one task for the node's
//! life. Ruled out by name: an elastic blocking pool, per-wake or per-batch spawning, and tearing a
//! resident down on idle. The two differ in ENGINE and never in lifecycle, which is why they share
//! one [`Wake`] vocabulary and one loop body.
//!
//! The sweep is the liveness floor under both, and it reaches them by the two doors the engines
//! actually have: a thread SELF-TIMES with `recv_timeout`, and an async task is RUNG — a
//! a clock puts a [`Wake::Sweep`] into the same inbox, coalescing on a full channel exactly as a
//! doorbell does. One flume transport either way, so neither engine needs a timer of its own — and
//! WHOSE clock rings the async one is the [`engine`](self::engine) substrate's answer: the app's own
//! runtime through [`AfterClock`] where a deployment named one, and a [`Sweeper`] thread where it
//! did not.
//!
//! A node's POLL entries ride those same two doors, one clock hand per entry: the thread engine
//! folds its next-due instants into the timeout it was already computing, and the async engine
//! takes a [`Sweeper::ticking`] over the same table. The asymmetry is the sweep's, not a second
//! design — and neither engine knows whether an entry recurs on an interval or on a calendar,
//! because both ask [`Recurrence::until_next`] and nothing else.
//!
//! # Exactly-once EFFECT
//!
//! At-least-once delivery plus keyed replace everywhere. Nothing here tries to deliver a message
//! exactly once — a dropped ack re-delivers, a lost hint is swept up, a crash between the effect
//! and the cursor advance replays the tail — and what makes that safe is that the storage layer
//! writes by key. The one ordering this layer owes is the other half: a durable position advances
//! only AFTER the effect it covers is durable.
//!
//! [`AsyncLands`] is where a node's own half of that ordering is spelled. A resident with a write lane
//! hands each delivery's records to it, and answers the oneshot only for the records that came
//! back committed — so `Persisted` is a fact about a store rather than about a dispatch, and a
//! batch that landed in part releases in part.
//!
//! # Two lanes, one per arm
//!
//! [`AsyncLands`] is the write arm's seam and [`Serves`] is the read arm's, and they are twins on
//! purpose: both are capabilities a type IMPLEMENTS rather than hooks a launch assembles, both take
//! `&mut self`, and neither names a backend. A resident's durability crosses one; a query arm's
//! answer crosses the other. What differs is that this side ships a lane — [`SlotLane`], the
//! branded verb wearing the seam — where the write side ships none, and [`serve`](self::serve)
//! records why.

mod autonomous;
mod changes;
mod channel;
mod downstream;
mod engine;
mod fate;
mod feed;
mod generations;
mod intake;
mod invoke;
mod journal;
mod lane;
mod launch;
mod lifecycle;
mod message;
mod notify;
mod observe;
mod pair;
mod policy;
mod poll;
mod progress;
mod registry;
mod resident;
mod retired;
mod serve;
mod stream;
mod tick;
mod window;

pub use autonomous::{Helm, Runs, Upstreams};
pub use changes::{
  AsyncChanges, ChangeIntake, Doorbell, Hint, IntakeError, Page, Pulled, Rung, doorbell,
};
#[cfg(feature = "sqlite")]
pub use changes::{SqliteFeed, SqliteFeedError};
pub use channel::{ChannelOptions, Evictor, Inbox, Nudge, Outbox, Wake, channel, open};
pub use downstream::{Attached, Attaches, Downstream, Sink, Socket, Wanted};
pub use engine::{AfterClock, Unruntimed};
pub use fate::{Fate, Terminal};
#[cfg(target_os = "macos")]
pub use feed::Darwin;
pub use feed::{
  DEFAULT_FEED_DEPTH, FeedContext, FeedPolicy, Fixed, MemoryAware, MemoryProbe, Pressure, Steady,
  Unpressured,
};
pub use generations::{
  CURRENT_TABLE_PREFIX, Culled, Curator, CuratorBody, CuratorReport, CurrentRow, CurrentTable,
  DEFAULT_KEEP, Generational, GenerationsEngine, GenerationsOptions, GenerationsOverride,
  GenerationsStore, GenerationsStoreError, RUN_COLUMN, RunId, Scope, Turning,
  UnknownGenerationsEngine, UnnameableScope, UnnameableTable, prepare,
};
#[cfg(any(feature = "sqlite", feature = "postgres", feature = "mysql"))]
pub use generations::{GenerationsSql, SqlGenerations, current_filter};
pub use intake::{Arm, Intake, arm, park_on, select};
pub use invoke::{
  Answers, AsyncAnswers, Awaiting, Door, Invoke, Invokes, Onward, QueryArm, QueryError, Reply,
  Served, door, reply,
};
pub use journal::{
  Attributes, JournalDrain, JournalQueue, JournalRow, JournalTap, JournalWriter, Ledger, Written,
  journal_queue,
};
pub use lane::{AsyncLands, Commit, Lands, Unwritten};
// The thread engine's future driver, lifted to the crate because the public face of it —
// [`conduit::park_on`](crate::conduit::park_on) — is what a body outside this layer spends. The
// driver itself stays private: what a caller is owed is the park with a sweep, not the loop under
// it.
pub(crate) use lane::block_until;
pub use launch::{
  App, ArrangementError, Assembly, AsyncConstructor, AsyncInitialize, AsyncTeardown, Autonomous,
  AutonomousBody, BareOptions, Blueprint, BoxedError, Bridged, Buffered, Cell, ChannelShelf,
  Channels, Context, Creation, Declared, DeclaredResident, Died, DisabledUpstreamError,
  DroppingUnboundedError, EdgeTypeError, Enablement, Enrolled, FeederAbsentError, Goodbye, Grant,
  GrantsNoStoreError, Habitats, Ignition, Initialize, Initializes, LandsNowhereError, LaneMount,
  LaunchError, Lived, MakesNothing, MandatoryOptionsError, MandatoryResourceOptionsError,
  MissingResourceError, Mount, MountBody, Mounted, MountedLane, NoDefaultOptions, NodeAttribution,
  NodeBody, NodeSection, NodeWiring, Ordered, Party, Plan, PolicyShelf, Posted, Produced,
  ProductSeatError, PureLeafError, Refusal, ResourceSourceError, Resources, Shutdown, SlotBinding,
  SplitOriginError, Staging, Stopped, StreamBody, StreamWires, Streaming, TakenInboxError, Tuned,
  UnboundCorpus, UnboundSlotError, UnbridgedOriginError, UnbuiltTargetError,
  UncataloguedResourceError, Unchanneled, UndeclaredResourceError, UnknownGrantError,
  UnknownNodeError, UnknownUpstreamError, Unpoliced, Untorn, Upstream, UpstreamWiring, Wired,
  Wiring, Worn, bare_options, bare_origin_options, bare_resource_options, drive_awaited_origin,
  drive_origin,
};
pub use lifecycle::{
  Arrival, Failure, Lifecycle, LifecycleTap, Observation, RecordingTap, Station, Taps,
};
pub use message::{
  Ack, AckReceiver, AckSender, Answer, Custody, Delivery, Item, Owing, Payload, PayloadIter,
  ReceiptMap, Settled, SettledParts, Share, Unreceipted, Unsettled, ack_channel,
};
pub use notify::Notified;
pub use observe::TracingLevel;
#[cfg(feature = "tracing")]
pub use observe::TracingTap;
pub use pair::{Group, Joins, Pairing};
pub use policy::{
  Backpressure, CatchUp, Coalesce, Concern, DeadlinePolicy, Deadlines, DropNewest, DropOldest,
  Handover, Missed, NoDeadline, NoRetry, Occupancy, OverflowDecision, OverflowPolicy, Policies,
  QueryDeadline, Retries, RetryDecision, RetryPolicy, ShedKey, Sheds, TickDecision, TickPolicy,
  Ticks,
};
pub use poll::{
  Cadence, Calendar, CalendarError, PollUpstream, Recurrence, Schedule, Seats, Swept, Ticked,
  Ticker, Unpolled,
};
pub use progress::{PositionKey, Positions, RecordedPositions, Track};
#[cfg(feature = "sqlite")]
pub use progress::{SqlitePositions, SqlitePositionsError};
pub use registry::{
  DEFAULT_BATCH_MAX_ITEMS, DEFAULT_BATCH_MAX_WAIT, DEFAULT_DEBOUNCE, DEFAULT_RETIRE_DRAIN,
  DEFAULT_SETTLE, DriverEngine, Flip, GenerationLedger, Registries, Registry, RegistryCounts,
  RegistryDriver, RegistryOptions, RegistryOverride, RetireOrigin, RetiredLedger, Retirement,
  RootAction, RootAdvance, RootKey, RootProjection, RootState, Stamp,
};
// CRATE-PRIVATE and BEHIND THE BINDING: the wire-erased door the GraphQL registry face reaches
// families through by name has exactly one caller, `graphql::registry`, which is itself gated — see
// `registry::dynamic`'s own module note for the measurement that settled it against `BatchDoor`'s
// unconditional precedent one module over.
#[cfg(feature = "async-graphql")]
pub(crate) use registry::DynRegistry;
pub use resident::{Drained, Drives, Resident, Tally};
#[cfg(feature = "mongodb")]
pub use retired::MongoRetired;
pub use retired::{
  Keeper, KeeperBody, KeeperReport, Landing, RETIRED_TABLE_PREFIX, RetiredEngine, RetiredMirror,
  RetiredOptions, RetiredReader, RetiredReaders, RetiredRow, RetiredStore, RetiredStoreError,
  RetiredTable, UnknownRetiredEngine, UnnameableFamily, rebuild,
};
#[cfg(any(feature = "sqlite", feature = "postgres", feature = "mysql"))]
pub use retired::{RetiredSql, SqlRetired};
pub use serve::{
  AsyncServes, DefaultServe, Flow, FulltextAsk, FulltextScope, Responding, Serve, Serves, SlotLane,
  VectorAsk, VectorScope,
};
pub use stream::{
  DEFAULT_IN_FLIGHT, StreamLane, StreamOptions, Streamed, Streams, UNDIVIDABLE, Vanished,
};
#[cfg(feature = "rayon")]
pub use tick::Rayon;
pub use tick::{AsyncSpawn, AsyncTick, AtMostOne, InFlight, Spawn, Tasks, Thread, Tick};
pub use window::{Answered, Harvest, Lineage, Outbound, Owed};

use core::time::Duration;

use crate::name::borrowed_name;

/// One item's identity ON THE TRANSPORT, minted by the node that sends it.
///
/// It is not the app's id and never becomes one. Core cannot read an identity out of a declared
/// struct — what an edge moves is the app's own type, and naming a field of it means naming a type
/// core does not know — so a sender mints a monotone token per outgoing item and the ack window
/// releases by that. The app's own ids reach this layer only through what an operator STATES: the
/// content a [`Skip`](crate::Skip) names, and the info a consumer puts in its [`Lifecycle`].
///
/// Monotone within one sender and meaningless across two, which is exactly what the window needs:
/// the watermark is the contiguous prefix of the order that sender SENT in, so the ordering that
/// matters is per-edge and per-sender by construction.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, derive_more::Display)]
#[display("item#{_0}")]
pub struct ItemId(u64);

impl ItemId {
  /// The token for sequence position `seq`.
  #[inline]
  #[must_use]
  pub const fn new(seq: u64) -> Self {
    Self(seq)
  }

  /// This token's sequence position.
  #[inline]
  #[must_use]
  pub const fn seq(&self) -> u64 {
    self.0
  }
}

borrowed_name! {
  /// A node's declared name, as a type a message cannot be passed as.
  ///
  /// It is what a [`LifecycleTap`] is told an observation came FROM, and half of the key the
  /// framework's own journal is replaced by — so a node name is a key that gets STORED, which is
  /// [`ReasonName`](crate::ReasonName)'s argument for being a type rather than the one loose string
  /// among this crate's names.
  ///
  /// It validates nothing, for [`ReasonName`](crate::ReasonName)'s reason and not
  /// [`SlotName`](crate::SlotName)'s: a node name is compared and printed, never quoted into a
  /// statement and never made into a path. What makes one good is that it is unique within the
  /// arrangement, which [`ChannelGraph`](crate::ChannelGraph) can answer and a charset cannot.
  pub struct NodeName;
}

impl NodeName {
  /// View `name` as a node name.
  ///
  /// `const`, so a hand-written arrangement can spell its node names in constants.
  #[inline]
  #[must_use]
  pub const fn new(name: &str) -> &Self {
    Self::view(name)
  }

  /// This name as a `str`.
  #[inline]
  #[must_use]
  pub const fn as_str(&self) -> &str {
    &self.0
  }
}

/// How one inbound upstream feeds a node — the per-upstream word, mixable in one fan-in.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, derive_more::Display, derive_more::IsVariant)]
#[display("{}", self.as_str())]
pub enum Listen {
  /// The DEFAULT: real messages over a bounded channel (see the module note).
  Channel,
  /// The upstream STORE's change feed (see [`AsyncChanges`]), and WHOSE HAND fills that store.
  ///
  /// The feeder is part of the word because it is the one fact a change feed cannot tell you: a feed
  /// reports what arrived, never who put it there. A default `changes(<db>)` says an enabled node of
  /// THIS graph lands into the watched store, which the launch walk can check and does; `external`
  /// declares the cross-process shape, and the check stands down because the answer is outside the
  /// process.
  Changes(Feeder),
  /// This node's OWN clock over that upstream, ticking every so often (see [`Schedule`]).
  ///
  /// The interval rides the WORD and not the node, which is what lets one maintenance node reap one
  /// store every ten minutes and compact another every hour. Nothing schedule-shaped exists at node
  /// level, so there is no second place for a upstream's cadence to be stated from.
  Poll(Duration),
  /// A QUERY edge — the second EDGE KIND, on the first kind's transport.
  ///
  /// The other three are ways of being fed the SAME thing: indexing flow, with an ack window behind
  /// it, a durable position under it and a journal beside it. This one is a different thing
  /// altogether. It carries an [`Invoke`] — an input and the oneshot the RESULT threads back on —
  /// and it has none of those three, because there is nothing to release, nothing to resume from
  /// and nothing to certify: the query's completion happens at its caller.
  ///
  /// It rides this vocabulary rather than one of its own for the reason the ruling gives: the query
  /// path IS topology. An index node subscribing to an indexing node's embeddings and to a query
  /// node's is one fan-in with two edge kinds, and the enablement coupling, the disabled-upstream
  /// refusal and the observability rules all sit on this edge uniformly — no special-case
  /// vocabulary.
  ///
  /// It carries no interval and no capacity: what it feeds is a [`QueryArm`], whose transient inbox
  /// is minted by [`door`] and is NOT the node's data [`Inbox`]. That separation is the read-path
  /// law rather than a detail — see [`invoke`](self::invoke).
  Transient,
}

impl Listen {
  /// A stable name for a refusal and for logs.
  ///
  /// The NAME and not the schedule: an interval is a fact about one upstream's wiring, and what a
  /// refusal or a log line is identifying is the mode. [`Schedule`] is where a cadence is read.
  #[inline]
  #[must_use]
  pub const fn as_str(&self) -> &'static str {
    match self {
      Self::Channel => "channel",
      Self::Changes(_) => "changes",
      Self::Poll(_) => "poll",
      Self::Transient => "transient",
    }
  }
}

/// WHOSE HAND fills the store a [`Changes`](Listen::Changes) edge watches.
///
/// The two-process shape is a first-class citizen rather than an escape hatch, and this is what makes
/// it one: the dependence on something outside the graph is DECLARED, so it reads in the declaration
/// and the launch walk knows not to look for a lander it will never find. What is refused is the
/// SILENT version — a default feed nobody fills, which starts, waits forever and reports nothing.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, derive_more::Display, derive_more::IsVariant)]
#[display("{}", self.as_str())]
pub enum Feeder {
  /// The DEFAULT: a node of this graph lands into the watched store.
  InGraph,
  /// `external` — the hand that fills the store is outside this process.
  External,
}

impl Feeder {
  /// A stable name for a refusal and for logs.
  #[inline]
  #[must_use]
  pub const fn as_str(&self) -> &'static str {
    match self {
      Self::InGraph => "in-graph",
      Self::External => "external",
    }
  }
}

/// When a node releases its INPUT's ack — the per-upstream opt-in.
///
/// The two differ in what they trade for a zero-gap window, and both are correct under the
/// exactly-once-EFFECT rule the module note states.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, derive_more::Display, derive_more::IsVariant)]
#[display("{}", self.as_str())]
pub enum AckMode {
  /// The DEFAULT: release on this node's own completion. Upstream runs at full speed and this
  /// node's memory stays flat, at the cost of a transient window in which an input is released and
  /// the effect it caused downstream is not yet durable. That window HEALS rather than losing
  /// anything: a stuck watermark is swept up and re-pulled from the nearest durable upstream — the
  /// roots are records, which are always durable — and keyed replace makes the replay idempotent.
  Local,
  /// Withhold the input's ack until the outputs it produced have themselves been released, joining
  /// on ALL of them where one input fanned out. Zero gap end to end, at the cost of backpressuring
  /// the upstream; the window holds BOOKKEEPING rather than payloads, since the payload has already
  /// moved on.
  Chained,
}

impl AckMode {
  /// A stable name for a refusal and for logs.
  #[inline]
  #[must_use]
  pub const fn as_str(&self) -> &'static str {
    match self {
      Self::Local => "local",
      Self::Chained => "chained",
    }
  }
}

/// What a node does with what it produces — the fact the pure-leaf refusal is decided on.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, derive_more::Display, derive_more::IsVariant)]
#[display("{}", self.as_str())]
pub enum Effect {
  /// The node's outputs become durable, so it can be the end of a lane.
  ///
  /// Two postures reach it, and the difference is WHOSE write. A node with its own write lane
  /// lands through [`AsyncLands`] and answers only after that write commits — see
  /// [`Resident::land`]. A node without one is durable because its emissions reach a storage
  /// co-subscriber, which is what [`Chained`](AckMode::Chained) makes it wait for. A node with
  /// NEITHER is claiming a durability nothing performs, and is refused — see [`LandsNowhereError`].
  Lands,
  /// The node computes and lands nothing. Legal wherever it has a consumer, and a refusal where it
  /// does not — see [`PureLeafError`].
  Pure,
}

impl Effect {
  /// A stable name for a refusal and for logs.
  #[inline]
  #[must_use]
  pub const fn as_str(&self) -> &'static str {
    match self {
      Self::Lands => "lands",
      Self::Pure => "pure",
    }
  }

  /// The station work at this effect REACHES, carrying `info`.
  ///
  /// A landing node reached durability before it answered, and a pure one did not and must not
  /// claim to have. It is written ONCE because three places spend it — a delivery's verdict, that
  /// verdict's station taken without its payload, and a [`Seats`] tick's own answer — and three
  /// copies of one table are three places it can stop agreeing with itself.
  #[inline]
  pub(crate) fn reached<I>(self, info: I) -> Lifecycle<I> {
    match self {
      Self::Lands => Lifecycle::Persisted(info),
      Self::Pure => Lifecycle::Processed(info),
    }
  }

  /// [`reached`](Self::reached)'s station, without the payload.
  #[inline]
  pub(crate) const fn station(self) -> Station {
    match self {
      Self::Lands => Station::Persisted,
      Self::Pure => Station::Processed,
    }
  }
}

/// Something a sweep can ring: a coalescing wake-up with no payload.
///
/// Two shapes implement it — a [`Nudge`] into a node's inbox and a [`Hint`] at a change feed's
/// doorbell — and both ring the same way, with a non-blocking send that DROPS on a full channel.
/// That is the whole of the sweep contract: ringing must never block the ringer, and a ring that
/// coalesced into one already queued has lost nothing, because a wake carries no information beyond
/// "look again".
pub trait Rings: Send {
  /// Ring it. `false` once the far end is gone, which is what tells a [`Sweeper`] to stop.
  fn ring(&self) -> bool;
}

/// The R-LESS sweep clock: one thread, ringing every registered [`Rings`] on an interval.
///
/// It exists because the two engines park differently and only one of them can time itself. A
/// resident THREAD self-times with `recv_timeout` and needs nothing here; an async task parks in
/// `recv_async`, and flume has no async deadline receive — so its sweep has to arrive as a message,
/// and a message needs a clock. One thread serves every registered ringer, which is what keeps this
/// from becoming the per-wake spawning the residency ruling excludes by name.
///
/// [`AfterClock`] is the same contract over an app's OWN runtime, and it is what a deployment that
/// named one gets. This is the fallback for the world that named none: a hand-wired arrangement
/// spawning its async bodies itself still has cadences to ring, and a timer wheel of our own is what
/// rings them when there is no runtime to ask.
///
/// Stopping is immediate rather than up to one interval late: the thread waits on a channel with a
/// timeout instead of sleeping, so dropping the handle wakes it now.
#[derive(Debug)]
pub struct Sweeper {
  stop: flume::Sender<()>,
  thread: Option<std::thread::JoinHandle<()>>,
}

impl Sweeper {
  /// Ring every member of `ringers` each `interval`, until this handle is dropped or every ringer's
  /// far end is gone.
  ///
  /// The liveness floor's door: one interval for the whole registry, which is what a sweep is. A
  /// clock whose hands run at DIFFERENT speeds is [`ticking`](Self::ticking), and this is that with
  /// every cadence the same.
  #[must_use]
  pub fn spawn(interval: Duration, ringers: Vec<Box<dyn Rings>>) -> Self {
    Self::ticking(
      ringers
        .into_iter()
        .map(|ringer| Cadence::new(interval, ringer))
        .collect(),
    )
  }

  /// Ring each of `cadences` on ITS OWN recurrence — the poll clock's async half.
  ///
  /// One thread still, however many cadences, which is what keeps a node's per-entry schedule from
  /// becoming the per-wake spawning the residency ruling excludes by name: a fast reaper and a
  /// nightly compactor are two entries in one table walked by one clock.
  ///
  /// A cadence that has come due is rescheduled from NOW rather than from the deadline it missed,
  /// so a round that ran long is one ring and never a burst of catch-up rings. That is the same
  /// sentence [`Ticker`]'s cell states about the inbox, said about the clock — and it is
  /// [`Recurrence::until_next`], the one next-due core, so an interval and a calendar are
  /// rescheduled by the same line. A cadence that answers `None` is due NEVER and drops out of the
  /// wait fold without a branch of its own.
  #[must_use]
  pub fn ticking(cadences: Vec<Cadence>) -> Self {
    let (stop, halt) = flume::bounded(1);
    let thread = std::thread::Builder::new()
      .name("ingraph-sweep".to_owned())
      .spawn(move || {
        let now = std::time::Instant::now();
        let mut due: Vec<Option<std::time::Instant>> = cadences
          .iter()
          .map(|cadence| cadence.until_next().map(|wait| now + wait))
          .collect();
        // Per cadence, because a ringer that is not due this round was not asked and so has said
        // nothing about whether it is still there. Ringers registered together do NOT die together:
        // residents shut down one at a time, and the survivors still need their clock.
        let mut live = vec![true; cadences.len()];
        loop {
          let now = std::time::Instant::now();
          let Some(wait) = due
            .iter()
            .zip(&live)
            .filter(|&(_, live)| *live)
            .filter_map(|(due, _)| *due)
            .map(|due| due.saturating_duration_since(now))
            .min()
          else {
            // Nothing left to ring — either every far end is gone, or there was never a cadence.
            return;
          };
          // `recv_timeout` rather than `sleep`, so the halt signal is observed at once. A timeout is
          // the tick; anything else — a halt, or a dropped handle — ends the thread.
          if halt.recv_timeout(wait) != Err(flume::RecvTimeoutError::Timeout) {
            return;
          }
          let now = std::time::Instant::now();
          // Every cadence that is due, every round, and the survivors counted afterwards — NOT
          // `any`, which short-circuits and would leave the rest of the arrangement unrung behind
          // the first live one.
          for (index, cadence) in cadences.iter().enumerate() {
            if live[index] && due[index].is_some_and(|due| due <= now) {
              // The ONE next-due core, so a calendar cadence is rescheduled by the same line an
              // interval one is — and a cadence that answers `None` is due never and drops out of
              // the wait fold above without a branch of its own.
              due[index] = cadence.until_next().map(|wait| now + wait);
              live[index] = cadence.ring();
            }
          }
        }
      })
      .expect("the sweep thread");
    Self {
      stop,
      thread: Some(thread),
    }
  }
}

impl Drop for Sweeper {
  fn drop(&mut self) {
    // Signalling AND joining, in that order. The send is what wakes the thread now; the join is
    // what makes a dropped `Sweeper` mean the clock has actually stopped, which a test asserting on
    // ring counts after a shutdown depends on.
    let _ = self.stop.send(());
    if let Some(thread) = self.thread.take() {
      let _ = thread.join();
    }
  }
}

#[cfg(test)]
mod tests;