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
//! HOW DEEP ONE DELIVERY'S STREAM LINE IS CUT: the [`FeedPolicy`] seam, and the machine reading a
//! policy may decide on.
//!
//! A [`StreamOperator`](crate::StreamOperator)'s [`Feed`](crate::Feed) is bounded and the wait for
//! room IS the backpressure — that is the face's own contract. What the face deliberately does not
//! carry is the NUMBER: how deep the line is, is the lane's property and not the body's, because a
//! depth is a memory budget and a body knows nothing about how many of itself are running.
//!
//! # Why a policy and not a scalar
//!
//! A scalar would be right if one number were right. It is not: the honest depth for a demuxer
//! fanning 4 KiB packets and for a chunker fanning 2 MiB windows differ by three orders of
//! magnitude, and the same node's honest depth differs between a machine with headroom and the same
//! machine ten minutes later. So the seat is a policy, judged at each delivery's SPAWN, and
//! [`Fixed`] — the shipped default — is the scalar answer wearing the seam's own shape.
//!
//! # The seam is FRAMEWORK-OPEN, and this module is the fifth citizen of the hook law
//!
//! [`policy`](super::policy)'s law verbatim: a policy is a TYPE and never an enum arm, dyn-compatible
//! because the choice is a deployment's rather than a call site's, and the shipped strategies are
//! ordinary implementations with no privilege the seam does not give them. [`MemoryProbe`] is a
//! second open seam under the first, for the same reason one layer down: how a machine reports
//! memory pressure is a platform's question, and closing it would make every new platform a change
//! to this crate.
//!
//! # Where it differs from the four: this hook cannot fail
//!
//! [`policy`](super::policy)'s 叉 A — a hook answers `Result` and a failed decision falls back to the
//! shipped default — is not written here, and the difference is the question rather than a relaxation.
//! The four decide WHETHER to do something; this one answers HOW MUCH, and every value in its answer's
//! type is a legal answer. A policy with nothing to say returns the depth it would have defaulted to,
//! which is one line rather than an error arm every caller would have to fold away.
//!
//! [`MemoryProbe`] IS fallible, and that is the same distinction seen from the other side: a machine
//! reading can be unavailable, and [`FeedContext::pressure`] is where the missing reading becomes
//! [`Pressure::NONE`] — the posture that widens rather than the one that starves.

use core::num::NonZeroUsize;

use crate::BoxedError;

#[cfg(test)]
mod tests;

/// THE MEASURED DEFAULT DEPTH: 256 items.
///
/// # The evidence
///
/// Measured through the lane itself — a synthetic wide-fan-out
/// [`StreamOperator`](crate::StreamOperator), one delivery fanned to 200 000 items, projected into a
/// one-edge downstream set of 64 deliveries, `in_flight = 1`, the shipped [`Thread`](super::Thread)
/// spawner — on an Apple M-series laptop (darwin 25.5.0, rustc 1.97.1, `--release`), 2026-08-23.
/// Best of seven interleaved rounds per depth:
///
/// | feed depth | items/second | relative | step |
/// |---|---|---|---|
/// | 8 | 486 437 | 1.00× | — |
/// | 32 | 1 078 019 | 2.22× | +122% |
/// | 64 | 2 189 045 | 4.50× | +103% |
/// | 128 | 6 090 451 | 12.52× | +178% |
/// | **256** | **7 615 095** | **15.65×** | **+25%** |
/// | 512 | 4 142 027 | 8.52× | −46% |
/// | 1 024 | 4 280 463 | 8.80× | +3% |
/// | 2 048 | 5 804 813 | 11.93× | +36% |
///
/// **The knee is 256**: every doubling up to it buys throughput, and nothing past it does — three
/// separate sweeps put 512, 1 024 and 2 048 at or below it. What the depth is buying is the drain's
/// BATCH: a deeper line is taken in larger pieces, so a node's per-item channel and dispatch cost is
/// amortised over more items, and that amortisation runs out.
///
/// Two honesties about the number. The host was **contended** throughout — other builds were running
/// — which is why the harness interleaves the depths and keeps the best round rather than the mean;
/// the step sizes wobble between sweeps while the SHAPE does not. And the harness measures the lane
/// END TO END, so part of what a deeper feed buys is a larger projection batch rather than the feed
/// alone. A reviewer who would rather trade throughput for memory has a defensible smaller answer:
/// **128 captures about four fifths of the win at half the per-delivery memory.**
///
/// `stream::tests::the_measured_knee_is_where_the_default_sits` is the harness, `#[ignore]`d because
/// it is a measurement rather than an assertion — a number that depends on the machine cannot be a
/// gate, and a default that cites evidence has to say where the evidence is reproduced.
///
/// It is a DEFAULT and not a law: a node whose items are megabytes writes [`Fixed::of`] with a
/// smaller number, and a node that has to answer to the machine writes [`MemoryAware`].
pub const DEFAULT_FEED_DEPTH: NonZeroUsize = NonZeroUsize::new(256).expect("256 is not zero");

/// HOW SHORT OF MEMORY THE MACHINE IS, as the fraction of the way from comfortable to critical.
///
/// # One number for platforms that count differently
///
/// macOS answers a three-valued level and Linux answers a stalled-time percentage, and a policy that
/// had to match on which platform it was running on would be a policy nobody could write once. So the
/// seam normalises: [`NONE`](Self::NONE) is a machine with headroom, [`CRITICAL`](Self::CRITICAL) is
/// one about to start killing processes, and everything between is between. What each platform's own
/// reading maps to is that platform's [`MemoryProbe`] to state and to document.
///
/// # It is `PartialEq` and not `Eq`
///
/// A fraction is an `f64`, which is [`Route`](crate::Route)'s trade one layer over: the ordering and
/// the equality are the float's own, and demanding a total one would mean quantising a reading for
/// the benefit of a derive.
#[derive(Debug, Clone, Copy, PartialEq, PartialOrd, Default)]
pub struct Pressure(f64);

impl Pressure {
  /// THE MACHINE HAS ROOM — the reading a probe that cannot read answers with, and the default.
  pub const NONE: Self = Self(0.0);

  /// THE MACHINE IS ABOUT TO START KILLING THINGS.
  pub const CRITICAL: Self = Self(1.0);

  /// The reading `fraction` of the way from [`NONE`](Self::NONE) to [`CRITICAL`](Self::CRITICAL).
  ///
  /// CLAMPED into `0.0..=1.0`, and a `NaN` reads as [`NONE`](Self::NONE): a probe is somebody else's
  /// code and a policy scaling by an out-of-range reading would compute a depth outside the floor and
  /// ceiling it was given, which is the one thing [`MemoryAware`] promises never to do.
  #[inline]
  #[must_use]
  pub fn of(fraction: f64) -> Self {
    if fraction.is_nan() {
      return Self::NONE;
    }
    Self(fraction.clamp(0.0, 1.0))
  }

  /// How far from [`NONE`](Self::NONE) to [`CRITICAL`](Self::CRITICAL) this reading is — `0.0..=1.0`.
  #[inline]
  #[must_use]
  pub const fn fraction(self) -> f64 {
    self.0
  }
}

/// WHERE A MEMORY READING COMES FROM — the open seam under [`MemoryAware`].
///
/// # It is a seam because the answer is the PLATFORM's
///
/// macOS publishes a pressure level through `sysctl`, Linux publishes stall percentages through
/// `/proc/pressure/memory`, a container publishes its cgroup's, and a deployment that already
/// computes a memory budget of its own publishes that. Not one of those can be the enum arm the
/// others are missing, which is [`policy`](super::policy)'s own framework-open law read one layer
/// down.
///
/// # What ships
///
/// [`Unpressured`] — the default, which reads nothing and always answers [`Pressure::NONE`], so a
/// deployment that installs no probe behaves exactly as one with a machine that never runs short.
/// [`Steady`] pins a reading, which is what a test asserts through and what a deployment with its own
/// out-of-band signal writes. [`Darwin`] is the one real platform reading in this round; the Linux
/// PSI probe is named, unwritten, and follows.
pub trait MemoryProbe: Send + Sync {
  /// How short of memory the machine is right now.
  ///
  /// # Errors
  ///
  /// Anything the reading needs and could not get — an absent `sysctl`, an unreadable file, a
  /// permission. [`FeedContext::pressure`] is where a failed read becomes [`Pressure::NONE`], so a
  /// probe that cannot answer widens the feed rather than starving it: a policy must not be able to
  /// throttle a pipeline because it could not find out whether it should.
  fn pressure(&self) -> Result<Pressure, BoxedError>;
}

/// THE MACHINE NEVER RUNS SHORT — the shipped [`MemoryProbe`], and today's behaviour as a type.
///
/// It reads nothing, so it costs nothing and cannot fail. A deployment that says nothing about
/// memory gets this, which is what makes [`MemoryAware`] under an unconfigured probe answer its
/// ceiling every time — the honest reading of *nobody has told me otherwise*.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
pub struct Unpressured;

impl MemoryProbe for Unpressured {
  #[inline]
  fn pressure(&self) -> Result<Pressure, BoxedError> {
    Ok(Pressure::NONE)
  }
}

/// A PINNED READING — the probe a test asserts through, and the one a deployment with its own signal
/// writes.
///
/// It ships rather than living in a test module for [`RecordingTap`](super::RecordingTap)'s reason:
/// every walk over this seam needs one, and a copy per test file is the same six lines written five
/// times. A deployment computing its own budget out of band — a supervisor's watermark, a cgroup
/// reading it already takes — hands one of these over and the seam is spent without a platform probe
/// anywhere.
#[derive(Debug, Clone, Copy, PartialEq, PartialOrd, Default)]
pub struct Steady(Pressure);

impl Steady {
  /// The probe that always reads `pressure`.
  #[inline]
  #[must_use]
  pub const fn at(pressure: Pressure) -> Self {
    Self(pressure)
  }

  /// The reading it hands out.
  #[inline]
  #[must_use]
  pub const fn pressure(&self) -> Pressure {
    self.0
  }
}

impl MemoryProbe for Steady {
  #[inline]
  fn pressure(&self) -> Result<Pressure, BoxedError> {
    Ok(self.0)
  }
}

/// macOS's OWN PRESSURE LEVEL, read through `kern.memorystatus_vm_pressure_level`.
///
/// # What the three levels map to
///
/// The kernel publishes a three-valued dispatch level — normal, warn, critical — which is the same
/// signal `DISPATCH_SOURCE_TYPE_MEMORYPRESSURE` delivers to an application, read as a poll instead of
/// as an event. The mapping is stated rather than derived, because there is no fraction underneath it
/// to derive one from:
///
/// | `kern.memorystatus_vm_pressure_level` | [`Pressure`] |
/// |---|---|
/// | `1` — normal | [`NONE`](Pressure::NONE) |
/// | `2` — warn | half way |
/// | `4` — critical | [`CRITICAL`](Pressure::CRITICAL) |
/// | anything else | an error, rather than a guess |
///
/// # The `unsafe` is one `sysctl` read, and it takes no dependency
///
/// The extern is declared here rather than pulled from a bindings crate, which is the manifest's own
/// posture about what a row has to buy: `sysctlbyname` is four pointers and an `int` in libSystem,
/// which every Darwin binary already links, and a dependency for one declaration would add a crate to
/// the graph for a signature that fits on a line. The call writes a fixed four bytes into a local
/// `i32` and reads nothing back that it did not size, and the length is checked on the way out — a
/// short answer is refused rather than read as a level.
#[cfg(target_os = "macos")]
#[cfg_attr(docsrs, doc(cfg(target_os = "macos")))]
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
pub struct Darwin;

#[cfg(target_os = "macos")]
mod darwin {
  use core::ffi::{c_char, c_int, c_void};

  // libSystem's own, and the whole of what this probe needs. `size_t` is `usize` on every Apple
  // target, which is what lets the length round-trip through a plain local.
  unsafe extern "C" {
    pub(super) fn sysctlbyname(
      name: *const c_char,
      oldp: *mut c_void,
      oldlenp: *mut usize,
      newp: *mut c_void,
      newlen: usize,
    ) -> c_int;
  }
}

/// The reading `kern.memorystatus_vm_pressure_level` refused to give.
#[cfg(target_os = "macos")]
#[derive(Debug, Clone, Copy, PartialEq, Eq, derive_more::Display)]
#[display(
  "the machine's memory-pressure level could not be read (`kern.memorystatus_vm_pressure_level`)"
)]
struct Unreadable;

#[cfg(target_os = "macos")]
impl core::error::Error for Unreadable {}

/// A pressure level outside the kernel's own three, carried rather than guessed at.
#[cfg(target_os = "macos")]
#[derive(Debug, Clone, Copy, PartialEq, Eq, derive_more::Display)]
#[display(
  "`kern.memorystatus_vm_pressure_level` answered {_0}, which is not one of its three levels"
)]
struct UnknownLevel(i32);

#[cfg(target_os = "macos")]
impl core::error::Error for UnknownLevel {}

#[cfg(target_os = "macos")]
impl MemoryProbe for Darwin {
  fn pressure(&self) -> Result<Pressure, BoxedError> {
    const NAME: &[u8] = b"kern.memorystatus_vm_pressure_level\0";
    const NORMAL: i32 = 1;
    const WARN: i32 = 2;
    const CRITICAL: i32 = 4;

    let mut level: i32 = 0;
    let mut size = core::mem::size_of::<i32>();
    // SAFETY: `NAME` is nul-terminated; `oldp` points at a live `i32` and `oldlenp` at a live `usize`
    // holding exactly that `i32`'s size, which is the buffer the kernel is allowed to fill; the write
    // half is the documented null/zero pair. Nothing borrowed here outlives the call.
    let rc = unsafe {
      darwin::sysctlbyname(
        NAME.as_ptr().cast::<core::ffi::c_char>(),
        core::ptr::from_mut(&mut level).cast::<core::ffi::c_void>(),
        &raw mut size,
        core::ptr::null_mut(),
        0,
      )
    };
    if rc != 0 || size != core::mem::size_of::<i32>() {
      return Err(Box::new(Unreadable));
    }
    match level {
      NORMAL => Ok(Pressure::NONE),
      WARN => Ok(Pressure::of(0.5)),
      CRITICAL => Ok(Pressure::CRITICAL),
      other => Err(Box::new(UnknownLevel(other))),
    }
  }
}

/// WHAT A [`FeedPolicy`] IS SHOWN when one delivery is about to be spawned.
///
/// The facts a depth can honestly be decided on, and no more: how many deliveries this node already
/// has in flight, how many it is allowed, and the machine underneath. It carries no identity — a
/// policy is chosen for a node and told nothing about which delivery it is deciding for, because a
/// depth that varied per item would be a routing decision wearing a memory seat.
#[derive(Clone, Copy)]
pub struct FeedContext<'a> {
  in_flight: usize,
  width: NonZeroUsize,
  probe: &'a dyn MemoryProbe,
}

impl<'a> FeedContext<'a> {
  /// The context for a node holding `in_flight` deliveries of an allowed `width`, over `probe`.
  #[inline]
  #[must_use]
  pub const fn new(in_flight: usize, width: NonZeroUsize, probe: &'a dyn MemoryProbe) -> Self {
    Self {
      in_flight,
      width,
      probe,
    }
  }

  /// How many deliveries this node has in flight right now, the one being spawned NOT counted.
  ///
  /// Counted before the admission this context is being built for, so a lane at rest shows `0` and a
  /// lane at its own ceiling shows [`width`](Self::width) minus one. That is what lets a policy
  /// divide a node's whole budget: the depth it answers is about to be one of `in_flight + 1` lines.
  #[inline]
  #[must_use]
  pub const fn in_flight(&self) -> usize {
    self.in_flight
  }

  /// How many deliveries this node is allowed in flight at once — the admission width.
  #[inline]
  #[must_use]
  pub const fn width(&self) -> NonZeroUsize {
    self.width
  }

  /// The probe, for a policy that reads it in some way of its own.
  #[inline]
  #[must_use]
  pub const fn probe(&self) -> &dyn MemoryProbe {
    self.probe
  }

  /// What the probe reads, with a failed read taken as [`Pressure::NONE`].
  ///
  /// The fallback is the widening one on purpose — see [`MemoryProbe::pressure`]'s own note: a
  /// pipeline must not be throttled because a probe could not find out whether it should be.
  #[inline]
  #[must_use]
  pub fn pressure(&self) -> Pressure {
    self.probe.pressure().unwrap_or(Pressure::NONE)
  }
}

impl core::fmt::Debug for FeedContext<'_> {
  /// The two counts and the READING — never the probe, which is a trait object with no
  /// [`Debug`](core::fmt::Debug) supertrait: asking for one would bound every deployment's probe for
  /// the benefit of this line, which is [`Policies`](super::Policies)' own trade.
  fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
    f.debug_struct("FeedContext")
      .field("in_flight", &self.in_flight)
      .field("width", &self.width)
      .field("pressure", &self.pressure())
      .finish_non_exhaustive()
  }
}

/// HOW DEEP TO CUT ONE DELIVERY'S FEED — judged at that delivery's spawn.
///
/// # The shipped default
///
/// [`Fixed`] at [`DEFAULT_FEED_DEPTH`], which is the measured knee: a deployment that says nothing
/// gets the depth the benchmark chose.
///
/// # It answers a number and cannot refuse
///
/// Every value of the answer's type is a legal depth, so there is no arm for *I could not decide* —
/// see the module note. A policy with nothing to say answers what it would have defaulted to.
pub trait FeedPolicy: Send + Sync {
  /// How deep the feed for the delivery `ctx` describes should be cut.
  fn capacity(&self, ctx: &FeedContext<'_>) -> NonZeroUsize;
}

/// THE SAME DEPTH EVERY TIME — the shipped [`FeedPolicy`], and a scalar wearing the seam's shape.
///
/// The right answer wherever the items are of a knowable size and the machine is not the constraint,
/// which is most nodes. [`default`](Default::default) is [`DEFAULT_FEED_DEPTH`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct Fixed(NonZeroUsize);

impl Fixed {
  /// Cut every feed `depth` items deep.
  #[inline]
  #[must_use]
  pub const fn of(depth: NonZeroUsize) -> Self {
    Self(depth)
  }

  /// The depth it answers.
  #[inline]
  #[must_use]
  pub const fn depth(&self) -> NonZeroUsize {
    self.0
  }
}

impl Default for Fixed {
  /// [`DEFAULT_FEED_DEPTH`] — the measured knee.
  #[inline]
  fn default() -> Self {
    Self::of(DEFAULT_FEED_DEPTH)
  }
}

impl FeedPolicy for Fixed {
  #[inline]
  fn capacity(&self, _ctx: &FeedContext<'_>) -> NonZeroUsize {
    self.0
  }
}

/// AS DEEP AS THE MACHINE CAN AFFORD: the ceiling with headroom, the floor under pressure, and a
/// straight line between.
///
/// # What it computes
///
/// `ceiling - (ceiling - floor) * pressure`, rounded down and never below the floor. A machine at
/// [`Pressure::NONE`] gets the ceiling, one at [`Pressure::CRITICAL`] gets the floor, and a probe
/// that could not read gets the ceiling — see [`FeedContext::pressure`].
///
/// # It adapts PER DELIVERY, and the live half was MEASURED AND DEFERRED
///
/// The depth is judged when a delivery is spawned and stands for that delivery's whole life. A feed
/// whose bound MOVED mid-stream — widening as memory freed, narrowing as it filled — is the second
/// level of the same idea, and it is buildable: [`Feed`](crate::Feed) is this crate's own type, so
/// the bound could be held as permits in front of the transport rather than as the transport's own
/// capacity, `add_permits` widening and an acquire-and-forget narrowing.
///
/// It is NOT built, and the reason is a number. That mechanism puts one permit acquire and one
/// release on **the path every give takes** — including every give of every deployment that never
/// wanted a movable bound. Measured on the same host and day as [`DEFAULT_FEED_DEPTH`], 500 000
/// items over a depth-64 line, best of seven interleaved rounds:
///
/// | | best round |
/// |---|---|
/// | the plain bounded channel | 113.4 ms |
/// | the same traffic behind permits | 129.6 ms |
/// | **cost on the plain path** | **+14.2%** |
///
/// A first, less careful sweep put it at +33.7%. Either number is several times the ~5% a
/// framework-wide tax on an untouched path could be justified at, so the live half defers and
/// per-delivery adaptation is what this policy does. `stream::tests::what_a_movable_feed_bound_would_cost_per_give`
/// is the harness. The case that would buy it back is a LONG delivery on a machine whose pressure
/// changes under it, and a follow-up is owed to that case rather than to the mechanism.
///
/// # `floor` above `ceiling` is not refused
///
/// [`between`](Self::between) takes the two as given and answers the larger of the two wherever the
/// line would fall below the floor, so a swapped pair degrades to a fixed depth rather than to a
/// refusal. A constructor that could fail would put a `Result` in every deployment's assembly for a
/// mistake a reader can see.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct MemoryAware {
  floor: NonZeroUsize,
  ceiling: NonZeroUsize,
}

impl MemoryAware {
  /// Scale between `floor` under full pressure and `ceiling` with none.
  #[inline]
  #[must_use]
  pub const fn between(floor: NonZeroUsize, ceiling: NonZeroUsize) -> Self {
    Self { floor, ceiling }
  }

  /// The depth it will not go below.
  #[inline]
  #[must_use]
  pub const fn floor(&self) -> NonZeroUsize {
    self.floor
  }

  /// The depth it answers with headroom.
  #[inline]
  #[must_use]
  pub const fn ceiling(&self) -> NonZeroUsize {
    self.ceiling
  }
}

impl FeedPolicy for MemoryAware {
  fn capacity(&self, ctx: &FeedContext<'_>) -> NonZeroUsize {
    let floor = self.floor.get();
    let ceiling = self.ceiling.get();
    let Some(span) = ceiling.checked_sub(floor) else {
      // A swapped pair: the floor is the whole answer, which is the type's own note.
      return self.floor;
    };
    // `span` is a count of items and the fraction is `0.0..=1.0`, so the product is in range and the
    // cast is a floor division rather than a truncation of anything the caller could observe.
    #[expect(
      clippy::cast_precision_loss,
      clippy::cast_possible_truncation,
      clippy::cast_sign_loss,
      reason = "a depth is a small count and the fraction is clamped into 0.0..=1.0, so the product \
                lands inside the span it was taken from"
    )]
    let shed = (span as f64 * ctx.pressure().fraction()) as usize;
    NonZeroUsize::new(ceiling.saturating_sub(shed)).unwrap_or(self.floor)
  }
}