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
//! THE ROSTER a slot publishes, the GATE a tag reaches one lane through, and the two refusals.

use core::fmt;

use smol_bytes::Utf8Bytes;

use crate::{Slot, name::folds_to};

use super::{LaneIdent, LanguageTag};

#[cfg(test)]
mod tests;

/// ONE LANE, as the declaration that minted it wrote it: a key, and the tags it accepts beside it.
///
/// The per-lane facts of a fan's grammar in the shape a reader spends them —
/// [`Step`](crate::Step)'s own construction one layer over, and `const`-constructible for the same
/// reason: a corpus's lanes are a fact about its declaration and not a value anybody computes.
///
/// # THE ALIASES ARE THE DECLARATION'S, and that is where the judgement belongs
///
/// Whether `zh-Hant` is its own lane or folds into `zh` is not a fact about Chinese — it is a
/// decision about whether this deployment's analyzer, corpus and query mix make the distinction pay.
/// So the framework carries no default alias table at all, and a deployment that wants traditional
/// folded in says so:
///
/// ```text
/// zh(accepts(zh_hans, zh_hant, cmn))
/// ```
///
/// # WHAT IS NOT HERE
///
/// The ANALYZER. A lane's tokenizer is an instance built at boot from a deployment's own words, and
/// a `const` row is exactly the wrong home for one — the same division
/// [`Describe`](crate::Describe)'s blueprint already draws against a slot maker's knobs. What this
/// row carries is the lane's EXISTENCE, which is a compile-time fact because it shapes the slot.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Lane {
  /// The key this lane is known by — the one word the gate ever hands back.
  key: &'static LaneIdent,
  /// The tags it accepts beside its own key.
  accepts: &'static [&'static LaneIdent],
  /// Whether this lane answers every tag no other lane has a home for.
  catch_all: bool,
}

impl Lane {
  /// The lane `key` names, accepting nothing but tags that reduce to the key itself.
  ///
  /// Everything a lane MAY write arrives through the builder below, so the absence of a call IS the
  /// absence of the word — [`Step::of`](crate::Step::of)'s own shape.
  #[inline]
  #[must_use]
  pub const fn of(key: &'static LaneIdent) -> Self {
    Self {
      key,
      accepts: &[],
      catch_all: false,
    }
  }

  /// The same lane, also accepting `accepts`.
  #[inline]
  #[must_use]
  pub const fn accepting(mut self, accepts: &'static [&'static LaneIdent]) -> Self {
    self.accepts = accepts;
    self
  }

  /// **THE CATCH-ALL** — the same lane, answering every tag no other lane has a home for.
  ///
  /// A wide roster is unrunnable without one. Thirty-two scripts and a world of language tags meet
  /// a corpus that declares four lanes, and the arrivals nobody planned for — a tag from a
  /// long-tail script, a locale a producer invented, a word that is not a tag at all — have to go
  /// SOMEWHERE or the search stops answering. This is where a deployment says where.
  ///
  /// # IT IS A ROSTER ROW, and that is what keeps the doctrine intact
  ///
  /// The law is *no UNDECLARED fallback*, not *no fallback*. Falling back to a lane nobody chose
  /// would be the silent mis-filing the gate exists to prevent; falling back to a lane somebody
  /// WROTE DOWN is a decision, visible in the place decisions are read, and it appears in every
  /// refusal and every roster listing like any other lane.
  ///
  /// # EXACTLY ONE per roster
  ///
  /// Two would make *which stranger goes where* depend on list order, which is the thing a roster
  /// is not allowed to decide by accident. [`lane_collisions`] refuses the second and names both
  /// claimants, exactly as it does for a word two lanes claim.
  ///
  /// # It is LAST, never first
  ///
  /// Every keyed and aliased lane — and every language-only near-home — is offered the tag before
  /// this one is. A catch-all cannot take a tag that had a home; it takes the ones that did not.
  #[inline]
  #[must_use]
  pub const fn catch_all(mut self) -> Self {
    self.catch_all = true;
    self
  }

  /// Whether this lane answers the tags no other lane has a home for.
  #[inline]
  #[must_use]
  pub const fn is_catch_all(&self) -> bool {
    self.catch_all
  }

  /// This lane's key — the canonical word, and the only one that leaves the gate.
  #[inline]
  #[must_use]
  pub const fn key(&self) -> &'static LaneIdent {
    self.key
  }

  /// The tags this lane accepts beside its own key.
  #[inline]
  #[must_use]
  pub const fn accepts(&self) -> &'static [&'static LaneIdent] {
    self.accepts
  }
}

/// **WHAT PARTITIONS ONE SLOT HOLDS** — the neutral layer's whole knowledge of a fan.
///
/// A corpus whose text is written in several languages is answered by several indexes, and this is
/// the seam every reader that needs to know which ones asks. It carries the KEYS and nothing about
/// what they mean: a lane's analyzer, its tokenizer's name and the block those words were written in
/// are the backend's, and a reader that parsed them would be a second authority on a vocabulary it
/// does not own.
///
/// # IT IS DEFAULTED, and the default is the zero-configuration corpus
///
/// A declaration that names no lanes has ONE — [`LaneIdent::UND`] — so an unfanned corpus is a
/// fanned one with a roster of length one and no reader anywhere carries an *is this fanned* fork.
/// A hand-written slot joins by writing nothing at all.
///
/// # It is a PUBLIC seam
///
/// A third-party slot implements it by hand, exactly as it implements [`Slot`]. Nothing here is a
/// macro's to own.
#[diagnostic::on_unimplemented(
  message = "`{Self}` publishes no lane roster",
  label = "no lanes",
  note = "a fanned corpus states its partitions here; an unfanned one takes the default roster by \
          writing `impl Lanes for {Self} {{}}`"
)]
pub trait Lanes: Slot {
  /// Every lane this slot holds, in declaration order — ONE default lane where nothing was said.
  ///
  /// Declaration order is the contract, exactly as it is for
  /// [`DeclaredTower::STEPS`](crate::DeclaredTower::STEPS): the gate reads the roster in it, so an
  /// entry's PLACE here is the order its key is offered a tag in.
  const LANES: &'static [Lane] = &[Lane::of(LaneIdent::UND)];
}

/// **WHAT ONE LANE OF THIS SLOT IS ASKED WITH** — the probe type a router wired to it must produce.
///
/// ```text
/// LaneRouter { Question = <the road's question>, Routed = <Slot as LanedStore>::Probe }
///                                                          └── this member, and E0271 if it is not
/// ```
///
/// # It exists so that a MIS-WIRING is `E0271` and not a conversion
///
/// The ruling that shaped the router called it a CROSSING rather than an endomorphism: a rich
/// question goes in and PROBES come out, and the probe's type is the router's own. That is only
/// checkable if the slot states which type it accepts, which is this member — so a declaration
/// wiring a router states an EQUALITY, and a router that answers in some other currency is refused
/// at the seat by the compiler rather than converted somewhere in the middle. See
/// [`LaneFan`](crate::LaneFan), the typed seat this equality is read at.
///
/// # It is the SLOT's and not the ENGINE's
///
/// A slot is `(field × engine)` and it is what a router is wired TO, so the probe is stated here
/// rather than on a store face: two slots of one engine may take different probes — a full-text
/// corpus takes a query string, a coordinate one takes a vector — and a member on the engine could
/// not say that. What the shipped full-text emission answers is a [`String`],
/// because a full-text probe is the text a lane's analyzer parses.
///
/// # It is a SEPARATE trait from [`Lanes`] on purpose
///
/// [`Lanes`] is the neutral layer's whole share of the fan and it is DEFAULTED, so every slot may
/// wear it by writing nothing. A probe type has no default that could be right, so a slot that has
/// not decided one does not implement this — and a declaration that wires a router to such a slot
/// gets `E0277` naming this trait rather than a silent unit type.
#[diagnostic::on_unimplemented(
  message = "`{Self}` states no lane probe",
  label = "no probe type",
  note = "a router wired to this slot answers in its probe currency; state it with `impl LanedStore \
          for {Self} {{ type Probe = …; }}`"
)]
pub trait LanedStore: Lanes {
  /// The currency ONE LANE of this slot is asked in — what a wired router's
  /// [`Routed`](crate::LaneRouter::Routed) must equal.
  type Probe;
}

/// **THE GATE** — one tag in, one lane out, and it is the only road to a lane there is.
///
/// ```
/// use ingraph::{Lane, LaneIdent, lane_for};
///
/// static LANES: &[Lane] = &[
///   Lane::of(LaneIdent::new("en")),
///   Lane::of(LaneIdent::new("zh"))
///     .accepting(&[LaneIdent::new("zh_hans"), LaneIdent::new("zh_hant"), LaneIdent::new("cmn")]),
/// ];
///
/// // BROAD IN: a region drops, a script folds through the alias, a POSIX spelling reads.
/// assert_eq!(lane_for("en-US", LANES).unwrap().key(), LaneIdent::new("en"));
/// assert_eq!(lane_for("zh-Hant-TW", LANES).unwrap().key(), LaneIdent::new("zh"));
/// assert_eq!(lane_for("cmn", LANES).unwrap().key(), LaneIdent::new("zh"));
///
/// // STRICT OUT: nothing matching is a refusal that names the roster, never a silent fallback.
/// assert!(lane_for("sw", LANES).is_err());
/// ```
///
/// # THE ORDER OF THE TWO PASSES IS LOAD-BEARING
///
/// Every lane's KEY is offered the tag before any lane's aliases are. A deployment that splits
/// Chinese into `zh` and `zh-Hant` while an older `zh` still lists `zh_hant` among its aliases gets
/// the KEY, which is the reading its newer word intended — and the collision that arrangement
/// really is gets named by [`lane_collisions`] rather than silently resolved by list order.
///
/// # NOTHING MATCHING IS A REFUSAL
///
/// There is no fallback lane and no implicit `und`. A document filed under an analyzer nobody chose
/// for it is a defect that surfaces months later as results that are quietly worse, so the gate
/// refuses instead and names the tag, the roster and every alias — a sentence whose reader can
/// either add a lane or add an alias.
///
/// A deployment that genuinely wants a catch-all declares one, which makes the choice visible in the
/// place choices are read.
///
/// # Errors
///
/// [`UnknownLane`] where `tag` reduces to nothing this roster keys or accepts, and where `tag` is
/// not a language tag at all.
pub fn lane_for(tag: &str, lanes: &'static [Lane]) -> Result<&'static Lane, UnknownLane> {
  // A TAG THIS GRAMMAR CANNOT READ skips the four matching steps — there is nothing to match with —
  // and goes straight to the catch-all. A catch-all that caught `sw` but refused `x-private` would
  // be a half-promise, and the strangers a producer emits by accident are exactly the malformed
  // ones.
  let Some(reduced) = LanguageTag::parse(tag) else {
    return catch_all(lanes).ok_or_else(|| UnknownLane::new(tag, lanes));
  };

  // ① EXACT KEY.
  for lane in lanes {
    if reduced.matches(lane.key()) {
      return Ok(lane);
    }
  }
  // ② EXACT ALIAS.
  for lane in lanes {
    for accepted in lane.accepts() {
      if reduced.matches(accepted) {
        return Ok(lane);
      }
    }
  }
  // ③ LANGUAGE-ONLY KEY — the nearest home, once nothing was declared for this exact tag.
  for lane in lanes {
    if reduced.matches_language(lane.key()) {
      return Ok(lane);
    }
  }
  // ④ LANGUAGE-ONLY ALIAS.
  for lane in lanes {
    for accepted in lane.accepts() {
      if reduced.matches_language(accepted) {
        return Ok(lane);
      }
    }
  }

  // ⑤ THE DECLARED CATCH-ALL, and ⑥ the refusal where none was declared.
  catch_all(lanes).ok_or_else(|| UnknownLane::new(tag, lanes))
}

/// The roster's catch-all, where one was declared.
///
/// The FIRST is answered, and a second is not a tie this function breaks: [`lane_collisions`]
/// refuses a roster carrying two, so reaching here with two is a roster that was never audited.
fn catch_all(lanes: &'static [Lane]) -> Option<&'static Lane> {
  lanes.iter().find(|lane| lane.is_catch_all())
}

/// **TWO LANES CANNOT CLAIM ONE WORD** — the roster's own audit, public so a deployment may spend it
/// where it likes.
///
/// Every key and every alias in `lanes` is compared with every other through this crate's one fold,
/// and the first pair that folds alike is refused. `zh` accepting `zh_hant` beside a lane keyed
/// `zh-Hant` is the shape it catches, and so is one lane listing an alias twice.
///
/// # WHY IT IS A FUNCTION AND NOT A GUARANTEE
///
/// A roster is a `const`, so this is checkable before anything runs — and the ruling asks for
/// exactly that, refused at the declaration. This function is what such a check CALLS: a
/// declaration's own expansion spends it, a boot walk spends it over the slots it is about to make,
/// and a downstream's test spends it over a roster written by hand. One implementation, three
/// vantages, and no second opinion about what a collision is.
///
/// # Errors
///
/// [`LaneCollision`] naming the folded word and both lanes that claimed it.
pub fn lane_collisions(lanes: &'static [Lane]) -> Result<(), LaneCollision> {
  // EXACTLY ONE CATCH-ALL. Two would make *which stranger goes where* depend on list order, which is
  // precisely the accident the gate's whole shape is built to refuse.
  let mut catch_alls = lanes.iter().filter(|lane| lane.is_catch_all());
  if let (Some(first), Some(second)) = (catch_alls.next(), catch_alls.next()) {
    return Err(LaneCollision::over_the_catch_all(first.key(), second.key()));
  }

  // EVERY PAIR ONCE, over the FLAT CLAIM POSITIONS the compile-time half reads — which is what keeps
  // the two vantages one audit: the pair this walk judges and the pair a declaration's `const`
  // refuses are the same two words, resolved by the same function and compared through the same
  // fold. The inner cursor starts one past the outer, so a word is never judged against itself and
  // no pair is judged twice.
  let mut at = 0;
  while let Some((word, owner)) = lane_claim(lanes, at) {
    let mut other = at + 1;
    while let Some((against, also)) = lane_claim(lanes, other) {
      if folds_to(word, against) {
        return Err(LaneCollision::new(word, owner, also));
      }
      other += 1;
    }
    at += 1;
  }

  Ok(())
}

/// **HOW MANY WORDS A ROSTER CLAIMS** — one per key and one per alias.
///
/// The length of the flat sequence [`lane_claim`] addresses, and what an emission counts its
/// per-word assertions out of.
#[inline]
#[must_use]
pub const fn lane_claims(lanes: &[Lane]) -> usize {
  let mut lane = 0;
  let mut claimed = 0;
  while lane < lanes.len() {
    claimed += 1 + lanes[lane].accepts.len();
    lane += 1;
  }
  claimed
}

/// **THE WORD AT FLAT POSITION `at`, AND THE LANE THAT CLAIMS IT** — keys and aliases in declaration
/// order, each lane's key before its own aliases.
///
/// [`None`] past the end, which is what lets both walks below run without asking the length first.
///
/// `const`, because the vantage that matters most reads it in one: a roster is a `const`, so the
/// audit belongs at the declaration and a declaration is compiled before anything runs.
#[must_use]
pub const fn lane_claim(lanes: &[Lane], at: usize) -> Option<(&LaneIdent, &LaneIdent)> {
  let mut lane = 0;
  let mut before = 0;
  while lane < lanes.len() {
    let here = 1 + lanes[lane].accepts.len();
    if at < before + here {
      let within = at - before;
      let word = if within == 0 {
        lanes[lane].key
      } else {
        lanes[lane].accepts[within - 1]
      };
      return Some((word, lanes[lane].key));
    }
    before += here;
    lane += 1;
  }
  None
}

/// **THE COMPILE-TIME HALF OF [`lane_collisions`]' WORD RULE** — whether the word at flat position
/// `at` was already claimed by an EARLIER position.
///
/// It asks [`lane_collisions`]' question from the other end, and that is deliberate: the walk above
/// reports the pair at the FIRST claimant, which is the right sentence for a roster held in a value,
/// and a declaration wants the caret on the SECOND spelling — the one whose author has something to
/// delete. Same words, same fold, one relation.
///
/// A word out of range answers `false`: there is no word there to have been claimed.
#[must_use]
pub const fn lane_claim_repeats(lanes: &[Lane], at: usize) -> bool {
  let Some((word, _)) = lane_claim(lanes, at) else {
    return false;
  };
  let mut before = 0;
  while before < at {
    let Some((earlier, _)) = lane_claim(lanes, before) else {
      return false;
    };
    if folds_to(word.as_str(), earlier.as_str()) {
      return true;
    }
    before += 1;
  }
  false
}

/// **THE COMPILE-TIME HALF OF [`lane_collisions`]' CATCH-ALL RULE** — whether a lane BEFORE `at`
/// already declared it.
///
/// [`lane_claim_repeats`]' posture on the other rule, and for the same reason: a roster declares
/// exactly one, so the refusal belongs on the second one written.
#[must_use]
pub const fn lane_catch_all_repeats(lanes: &[Lane], at: usize) -> bool {
  if at >= lanes.len() || !lanes[at].catch_all {
    return false;
  }
  let mut before = 0;
  while before < at {
    if lanes[before].catch_all {
      return true;
    }
    before += 1;
  }
  false
}

/// **NO LANE ANSWERS THIS TAG** — the gate's refusal, naming what it was handed and what it had.
///
/// It carries the roster, so the sentence a reader gets is actionable rather than a bare *unknown*:
/// what was asked for, what exists, and what each existing lane already accepts.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UnknownLane {
  /// The tag as it arrived — OWNED, because a refusal outlives the borrow that produced it.
  tag: Utf8Bytes,
  /// The roster it was offered to.
  lanes: &'static [Lane],
}

impl UnknownLane {
  /// The refusal for `tag` against `lanes`.
  #[inline]
  #[must_use]
  pub fn new(tag: &str, lanes: &'static [Lane]) -> Self {
    Self {
      tag: Utf8Bytes::from(tag.to_owned()),
      lanes,
    }
  }

  /// The tag that reached no lane.
  #[inline]
  #[must_use]
  pub fn tag(&self) -> &str {
    self.tag.as_str()
  }

  /// The roster it was offered to.
  #[inline]
  #[must_use]
  pub const fn lanes(&self) -> &'static [Lane] {
    self.lanes
  }
}

impl fmt::Display for UnknownLane {
  fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    write!(
      f,
      "no lane answers the tag `{}`; this corpus holds",
      self.tag
    )?;
    if self.lanes.is_empty() {
      return f.write_str(" no lanes at all");
    }
    for (at, lane) in self.lanes.iter().enumerate() {
      let separator = if at == 0 { " " } else { ", " };
      write!(f, "{separator}`{}`", &**lane.key())?;
      let mut accepts = lane.accepts().iter().copied();
      if let Some(first) = accepts.next() {
        write!(f, " (also accepting `{}`", &**first)?;
        for accepted in accepts {
          write!(f, ", `{}`", &**accepted)?;
        }
        f.write_str(")")?;
      }
    }
    // THE SECOND ROAD OUT, named beside the first: this refusal can only happen where nobody wrote a
    // catch-all down, so its reader is told that declaring one is an answer.
    f.write_str(", and no catch-all is declared")
  }
}

impl core::error::Error for UnknownLane {}

/// **WHAT TWO LANES CLAIMED** — a word, or the catch-all role.
///
/// A CLOSED framework vocabulary of two, and closed for the reason the framework-open discipline
/// names: these are the two things one roster row can claim that another row can claim too, and both
/// are the framework's own notions rather than a deployment's.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Claimed {
  /// A tag word — a key, or an alias.
  Word(Utf8Bytes),
  /// The catch-all role, of which a roster may declare exactly one.
  CatchAll,
}

/// **TWO LANES CLAIM ONE THING** — [`lane_collisions`]' refusal.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LaneCollision {
  /// What both lanes claimed.
  claimed: Claimed,
  /// The lane that claimed it first.
  first: &'static LaneIdent,
  /// The lane that claimed it again.
  second: &'static LaneIdent,
}

impl LaneCollision {
  /// The collision `word` makes between `first` and `second`.
  #[inline]
  #[must_use]
  pub fn new(word: &LaneIdent, first: &'static LaneIdent, second: &'static LaneIdent) -> Self {
    let word: &str = word;
    Self {
      claimed: Claimed::Word(Utf8Bytes::from(word.to_owned())),
      first,
      second,
    }
  }

  /// The collision two CATCH-ALL declarations make between `first` and `second`.
  #[inline]
  #[must_use]
  pub const fn over_the_catch_all(first: &'static LaneIdent, second: &'static LaneIdent) -> Self {
    Self {
      claimed: Claimed::CatchAll,
      first,
      second,
    }
  }

  /// What both lanes claimed.
  #[inline]
  #[must_use]
  pub const fn claimed(&self) -> &Claimed {
    &self.claimed
  }

  /// The word both lanes claimed — [`None`] where what they claimed was the catch-all role.
  #[inline]
  #[must_use]
  pub fn word(&self) -> Option<&str> {
    match &self.claimed {
      Claimed::Word(word) => Some(word.as_str()),
      Claimed::CatchAll => None,
    }
  }

  /// The lane that claimed it first.
  #[inline]
  #[must_use]
  pub const fn first(&self) -> &'static LaneIdent {
    self.first
  }

  /// The lane that claimed it again.
  #[inline]
  #[must_use]
  pub const fn second(&self) -> &'static LaneIdent {
    self.second
  }
}

impl fmt::Display for LaneCollision {
  fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    write!(
      f,
      "{}",
      match &self.claimed {
        Claimed::Word(word) => format!(
          "the word `{word}` is claimed by lane `{}` and by lane `{}`; one tag cannot name two lanes",
          &**self.first, &**self.second
        ),
        Claimed::CatchAll => format!(
          "lane `{}` and lane `{}` are both declared the catch-all; a roster declares exactly one",
          &**self.first, &**self.second
        ),
      }
    )
  }
}

impl core::error::Error for LaneCollision {}