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
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
//! What a record contributes to an index, and which index it lands in: [`FulltextRecord`],
//! [`FulltextTable`], [`BlobRecord`], [`BlobTable`], [`VectorRecord`].
//!
//! Four traits and no engine. A document is text, an embedding is coordinates, a key is a value and
//! a slot is a name — none of them mentions Tantivy or FTS5 or Lance — so this module compiles in a
//! build with no backend family at all, exactly as the storage forms do. What an engine adds is
//! NOTHING a record has to know about: a key reports itself in COLUMNS ([`Field`](crate::Field),
//! one impl per TYPE), and the JOIN between a record and an engine is the EMISSION's — the code that
//! can see a record's fields is the code that crosses them into an engine's entry.
//!
//! An engine RECORD TRAIT used to make that join —
//! `TantivyRecord: FulltextRecord + Identifiable<Id: TantivyKey>` was the shape — and A′ retired it.
//! A trait joining a record to an engine has to name the engine's own key capability, which is a
//! local trait over foreign key types, which is the orphan wall: `impl TantivyKey for i64` in a
//! declaring crate was `E0117`, so the crate owed the id vocabulary a shipped impl per member and a
//! completeness proof beside them. An ENGINE-BLIND row has no such wall — it names no engine for an
//! orphan rule to be about — and the join it used to make is a line of emitted code instead.
//!
//! # Three families are here, and the fourth is not
//!
//! Meta records are not written, because nothing asks for one: a row's value is backend-shaped
//! columns rather than anything a neutral trait could return. The ADDRESS is the one piece all four
//! share, which is why it is the entity binding's — [`Identifiable`](crate::Identifiable)'s id,
//! reached through [`Transformer`] — and sits beside the families rather than inside one of them.
//!
//! Blob was the second to arrive, and what asked is [`store`](crate::store): a blob store's seam is
//! the cheapest of the three, because a blob's address is derivable from its key alone — it needs
//! no query language, no element vocabulary and no document schema to be useful. Its NAMING
//! authority, [`BlobTable`], arrived with the blob-engine round, and what asked for it is
//! [`Creation::async_blob_slot`](crate::Creation::async_blob_slot): a launch that mints a handle has to read the
//! family's name off the declaration, or the caller states a pairing nothing checks.
//!
//! Vector is the third, and what unblocked it was the ELEMENT. This note used to say that a vector
//! record could not be spelled without the element vocabulary first, and that was true of the
//! vocabulary it meant: 721 lines holding three marker types, a runtime enum shadowing them, a
//! packing per element and an engine-admission seam. [`Embedding<E, N>`](crate::Embedding) replaced
//! it by naming the element type instead of a marker for it, so what a vector record now needs to
//! be spelled is a slice per elected column. Its own naming authority has NOT crossed — no launch
//! door mints a vector handle yet, and until one does there is nothing for the const to be read by.
//!
//! # Identity is ORTHOGONAL to the document, and a supertrait of the name
//!
//! [`FulltextRecord`] does not require [`Transformer`], and [`FulltextTable`] does. That is one
//! decision twice, and the two bounds are what it buys:
//!
//! - `T: FulltextRecord` is what a party rendering text writes, and it reaches no `T::Key` —
//!   `E0220`, pinned by that trait's own `compile_fail` doctest. Under the supertrait the bound
//!   would carry identity silently, and no type could have a document before it had a key.
//! - `T: FulltextTable` is what a party writing to the index writes, and it reaches `T::Key`
//!   through the supertrait chain without naming [`Transformer`]. A slot name is where a document
//!   is put, and a namer that could not reach what the document is answered as would name a
//!   resource it can say nothing else about.
//!
//! ADDRESSING is not what holds that second bound up, and the stale answer is the obvious one.
//! Which entry a document replaces or deletes is the ID's question — an unbrowsable engine names an
//! entry by the id it came in under — and [`Identifiable`](crate::Identifiable) answers it alone,
//! being a supertrait of [`Transformer`] rather than a member of it, so a bound naming that smaller
//! trait would already have reached the address. What keeps [`Transformer`] here is the OUTPUT
//! half: the whole key, ancestry included, is what a hit is handed back under, and that is what the
//! doctest below writes — `address_of` returns `T::Key`, which no smaller bound projects.
//!
//! Both halves are pinned: the second by this module's doctest, the first by its `compile_fail`
//! twin and by `tests/downstream.rs`, which writes both functions from outside the crate.

use core::future::Future;
use std::borrow::Cow;

use crate::{SlotName, Transformer, VectorColumn};

/// A full-text entry: the document to index.
///
/// Unlike a meta record, the neutral trait exposes the VALUE — a document is text in every backend,
/// where a row's value is backend-shaped columns — so there is something for a bound-free trait to
/// return.
///
/// # `type Document` is the SIMPLE shape, and the general one is designed
///
/// `docs/2026-07-28-derive-design-notes.md` records the direction this becomes:
/// `fn document(&self, doc: &mut DocSink)` plus a const field-declaration list, symmetric with a
/// key's encode. That shape can write SEVERAL NAMED fields, each with its own tokenizer, index
/// option and stored flag, which one associated type cannot express — a single `Document` is one
/// box of text.
///
/// It is not built here because neither half of it exists: there is no `DocSink`, no field
/// declaration, and no derive to emit against them. When it lands, [`Document`](Self::Document)
/// goes away and [`document`](Self::document) takes a sink and returns nothing, so every impl
/// written against this trait is rewritten. The trait's name, its independence from [`Transformer`]
/// and its place in the family are what survive that change; the method signature is not.
///
/// # Examples
///
/// A bound naming only this trait reaches the document and no key, which is the separation's whole
/// content:
///
/// ```
/// use ingraph::FulltextRecord;
///
/// struct Caption(String);
///
/// impl FulltextRecord for Caption {
///   type Document = String;
///
///   fn document(&self) -> &String {
///     &self.0
///   }
/// }
///
/// fn document_of<T: FulltextRecord>(record: &T) -> &T::Document {
///   record.document()
/// }
///
/// assert_eq!(document_of(&Caption("a red car".to_owned())), "a red car");
/// ```
///
/// And it reaches no key, because there is none to reach:
///
/// ```compile_fail,E0220
/// use ingraph::FulltextRecord;
///
/// fn key_of<T: FulltextRecord>(record: &T) -> T::Key {
///   record.key()
/// }
/// ```
pub trait FulltextRecord {
  /// What is indexed — one text field, or a structured multi-field document.
  ///
  /// Bound by nothing here: what a document must BE is the searching engine's question, and each
  /// engine's own record trait asks it. Naming a bound at this level would answer it for engines
  /// that have not arrived.
  type Document;

  /// The document to index.
  ///
  /// By reference: it is a payload, read rather than consumed, and a record is indexed without
  /// being given up.
  fn document(&self) -> &Self::Document;
}

/// WHICH full-text slot a record's documents land in — the record's durable SLOT name.
///
/// A slot rather than a table, because that is the vocabulary the full-text engines share: one
/// Tantivy index or one FTS5 virtual table PER SLOT, which is what gives each its own corpus
/// statistics.
///
/// # Why the name lives on the RECORD
///
/// `Self` is the record type, which keeps three things apart that a single name per entity would
/// conflate: an entity is not an index, a key TYPE is not an index (two records can share one key
/// type), and a slot is not a table. Each family names its OWN resource with its OWN key.
///
/// A `const`, because a record's slot is fixed at its type and needs no value to ask — and because
/// a `const` is the position [`SlotName::new`]'s refusal becomes `E0080` in, at the impl that
/// names the slot rather than at a store that renders it.
///
/// # Examples
///
/// ```
/// use ingraph::{FulltextRecord, FulltextTable, Identifiable, SlotName, Transformer};
///
/// struct Caption {
///   media: u64,
///   frame: u32,
///   text: String,
/// }
///
/// #[derive(Debug, PartialEq)]
/// struct CaptionKey {
///   media: u64,
///   frame: u32,
/// }
///
/// #[derive(Debug, PartialEq)]
/// struct CaptionLineage {
///   media: u64,
/// }
///
/// impl Identifiable for Caption {
///   type Id = u32;
///
///   fn id_ref(&self) -> &u32 {
///     &self.frame
///   }
/// }
///
/// impl Transformer for Caption {
///   type Key = CaptionKey;
///   type Lineage = CaptionLineage;
///   type Record = Self;
///   type Graphql = ();
///
///   fn key(&self) -> CaptionKey {
///     CaptionKey {
///       media: self.media,
///       frame: self.frame,
///     }
///   }
/// }
///
/// impl FulltextRecord for Caption {
///   type Document = String;
///
///   fn document(&self) -> &String {
///     &self.text
///   }
/// }
///
/// impl FulltextTable for Caption {
///   const SLOT: &'static SlotName = SlotName::new("captions");
/// }
///
/// // The bound names this trait alone, and reaches the whole key — the output address, ancestry
/// // included — through the supertrait chain.
/// fn address_of<T: FulltextTable>(record: &T) -> (&'static SlotName, T::Key) {
///   (T::SLOT, record.key())
/// }
///
/// let caption = Caption {
///   media: 7,
///   frame: 12,
///   text: "a red car".to_owned(),
/// };
/// let (slot, key) = address_of(&caption);
///
/// assert_eq!(slot.as_ref(), "captions");
/// assert_eq!(key, CaptionKey { media: 7, frame: 12 });
/// ```
pub trait FulltextTable: Transformer {
  /// The full-text slot this record's documents land in.
  ///
  /// `E0080` at this declaration for a malformed name — see [`SlotName::new`].
  const SLOT: &'static SlotName;
}

/// The ARTIFACT FAMILY a blob record's objects land in — the blob side's naming authority, and
/// [`FulltextTable`]'s sibling in every respect that matters.
///
/// Where a full-text slot is a corpus and a vector slot is a table, a blob slot is the FIRST SEGMENT
/// of a hierarchical object name — a directory under a filesystem store's root, the leading
/// object-key segment in an object store. Everything below it is the key's own walk, so this const
/// is the whole of what a family is called.
///
/// # Why the name lives on the RECORD, and why it is a `const`
///
/// [`FulltextTable`]'s two reasons, unchanged, because they were never about full text. `Self` is
/// the record type, which keeps an entity, a key TYPE and a slot apart where one name per entity
/// would conflate them; and a `const` is the position [`SlotName::new`]'s refusal becomes `E0080`
/// in — at the impl that NAMES the family, rather than at a store that renders it. A slot reaches a
/// directory, where no quoting exists, so the charset fence is not decoration.
///
/// # The [`Transformer`] supertrait, for the same half it is there for one family over
///
/// Not addressing — [`Identifiable`](crate::Identifiable) would already have reached that. It is the
/// OUTPUT half: what a caller holding a family gets back is the whole `Self::Key`, ancestry
/// included, because that key IS the address under this family's slot. A namer that could not
/// project the key would be naming a resource it can say nothing else about.
///
/// # Examples
///
/// ```
/// use ingraph::{BlobRecord, BlobTable, Identifiable, SlotName, Transformer};
///
/// struct Thumbnail {
///   media: u64,
///   frame: u32,
///   pixels: Vec<u8>,
/// }
///
/// #[derive(Debug, PartialEq)]
/// struct ThumbnailKey {
///   media: u64,
///   frame: u32,
/// }
///
/// impl Identifiable for Thumbnail {
///   type Id = u32;
///
///   fn id_ref(&self) -> &u32 {
///     &self.frame
///   }
/// }
///
/// impl Transformer for Thumbnail {
///   type Key = ThumbnailKey;
///   type Lineage = u64;
///   type Record = Self;
///   type Graphql = ();
///
///   fn key(&self) -> ThumbnailKey {
///     ThumbnailKey {
///       media: self.media,
///       frame: self.frame,
///     }
///   }
/// }
///
/// impl BlobRecord for Thumbnail {
///   type Bytes = Vec<u8>;
///
///   fn bytes(&self) -> &Vec<u8> {
///     &self.pixels
///   }
///
///   fn extension() -> Option<&'static str> {
///     Some("png")
///   }
/// }
///
/// impl BlobTable for Thumbnail {
///   const SLOT: &'static SlotName = SlotName::new("thumbnails");
/// }
///
/// // What a launch door writes: the family's name and the key that addresses inside it, off ONE
/// // type and with no pairing for a caller to state.
/// fn family_of<T: BlobTable>(record: &T) -> (&'static SlotName, T::Key) {
///   (T::SLOT, record.key())
/// }
///
/// let thumbnail = Thumbnail {
///   media: 7,
///   frame: 12,
///   pixels: vec![0x89, 0x50],
/// };
/// let (slot, key) = family_of(&thumbnail);
///
/// assert_eq!(slot.as_ref(), "thumbnails");
/// assert_eq!(key, ThumbnailKey { media: 7, frame: 12 });
/// ```
pub trait BlobTable: Transformer {
  /// The artifact family this record's objects land in.
  ///
  /// `E0080` at this declaration for a malformed name — see [`SlotName::new`].
  const SLOT: &'static SlotName;
}

/// AN ARTIFACT FAMILY, seen from the declaration that SERVES it — the bridge two macro expansions
/// cross when neither can read the other's tokens.
///
/// # The wall this exists to go around
///
/// A blob family's wire fields belong on the OUTPUT OBJECT of the entity its objects are derived
/// from, and that object is written by the ENTITY's expansion. What the fields need — the family's
/// slot, how its addresses end, which store holds them — is written on the FAMILY's declaration. Two
/// derives do not see each other's tokens, and a second `#[Object]` block bolted onto one type
/// afterwards is `E0119` three times over (`ContainerType`, `OutputType`, `ObjectType`), so nothing
/// can be added later either.
///
/// So the family's declaration writes these facts into a TYPE, and the entity's `locate(…)` word
/// hands its expansion the family's PATH. Everything crosses as a projection off that path, which is
/// zero cross-expansion token reading, and the wall never arises.
///
/// # What is here, and what is deliberately one trait out
///
/// This trait carries what the DECLARATION knows about itself, and nothing that depends on a
/// deployment or on a wire face. The three facts that do are traits of their own, each with its own
/// presence:
///
/// | fact | trait | present when |
/// |---|---|---|
/// | the slot, the type-level suffix, the upstream | [`BlobArtifact`] | always |
/// | the suffix a hydrated ROW renders | [`ArtifactSuffix`] | always, defaulting to [`SUFFIX`](Self::SUFFIX) |
/// | where the objects live, and how an address is reached | [`ArtifactStore`] | the family named a store this crate can spell, or a third party wrote the impl |
/// | the bytes may be served INLINE | [`ArtifactData`] | the declaration wrote `data` |
///
/// The split is what keeps the family open. A store the framework has never heard of is bound at a
/// GRAPH ROOT, which no declaration's expansion can see — so [`ArtifactStore`] is left for whoever
/// can name the store, and the family's own declaration still answers everything else.
pub trait BlobArtifact {
  /// The upstream whose messages this family holds one object each of.
  ///
  /// A blob node's key IS its upstream's — the family mints no identity of its own — so this is also
  /// where the KEY that addresses an object comes from, reached as
  /// `<Self::Upstream as Transformer>::Key`. That is why the bound is [`Transformer`] and nothing
  /// narrower: the address is the whole key, ancestry included, because the store nests its objects
  /// by exactly that walk.
  type Upstream: Transformer;

  /// The artifact family this record's objects land in — the first segment of a stored object's
  /// hierarchical name.
  ///
  /// The same seat [`BlobTable::SLOT`] is, restated here rather than reached through that trait,
  /// because the two are asked by different parties: `BlobTable` is what a WRITE lane bounds on and
  /// is implemented by the record whose bytes are stored, where this is what a READ face projects
  /// off the family's own type. A family satisfying both binds one name twice, which is a fact of
  /// the declaration rather than a duplication a reader has to keep in step.
  const SLOT: &'static SlotName;

  /// The suffix every one of this family's addresses ends with, WHERE THE TYPE KNOWS IT — the
  /// `extension = "png"` form, and [`None`] for all five others.
  ///
  /// [`None`] therefore means two different things, and the distinction is not lost — it is one
  /// trait down: the extensionless form answers [`None`] from [`ArtifactSuffix::suffix`] too, and a
  /// column form answers whatever the row held. This const is the FLOOR that method's default body
  /// stands on, so a family deciding its suffix per entry overrides the method and leaves this
  /// [`None`], which is the honest reading — there is no one suffix for it to state.
  const SUFFIX: Option<&'static str> = None;
}

/// The SUFFIX one HYDRATED ROW renders — where the `extension` word's six forms are resolved.
///
/// # Why the row is a type PARAMETER and not an associated type
///
/// The row this reads is the entity's OUTPUT OBJECT, whose type the family's own expansion cannot
/// name: it exists only where the entity declared a `graphql(…)` block, and naming it would make
/// every artifact family demand a wire face from its upstream — including the families that only
/// ever store. As a parameter it costs nothing: the four COLUMN forms emit ONE impl at the row they
/// actually read, and the two forms that read no row take the blanket and bind for every `Row` there
/// is.
///
/// # The DEFAULT is the two column-less forms, and it is not a placeholder
///
/// `extension = "png"` and the omitted form both answer off the type, so the default body IS their
/// implementation and a family taking either emits `impl<Row> ArtifactSuffix<Row> for …` with an
/// empty body. There is no overlap with the column forms, because a family is on exactly one of the
/// six roads.
///
/// # The `with` hook eats the COLUMN VALUE, and that is what makes it ONE function
///
/// The write lane holds an upstream field and the read face holds the entity's own column; a hook
/// over the VALUE is spendable from either, where a hook over the row would need two different rows
/// and would be two functions pretending to be one. Nothing about that is enforced at this seat —
/// the hook is called by the emission, at the span its author wrote — and it is stated because this
/// is where the read half of it arrives.
pub trait ArtifactSuffix<Row>: BlobArtifact {
  /// The suffix `row`'s object is addressed under, or [`None`] for an extensionless family.
  ///
  /// A [`Cow`] because the six forms end in different places: a static suffix and an enum variant's
  /// textual form are `&'static str`, a string column borrows out of the row, and a `with` hook
  /// returns whatever becomes one. Nothing allocates for a form that did not need to.
  ///
  /// # Errors
  ///
  /// [`UnfencedSuffix`] where the row held a value the declaration's own fence does not admit —
  /// `any_of`'s output fence on the string road, `variants`' input fence on the enum one. Checking
  /// is what makes those words RULES rather than promises: the alternative is a family quietly
  /// addressing an object under a suffix its own declaration says it never produces.
  fn suffix(_row: &Row) -> Result<Option<Cow<'_, str>>, UnfencedSuffix> {
    Ok(Self::SUFFIX.map(Cow::Borrowed))
  }
}

/// A row held a value its family's own fence does not admit.
///
/// It carries all four parts of the sentence a caller has to be able to write — WHICH family, WHICH
/// column, what the row held, and what the declaration admits — because a resolver surfacing this on
/// the wire has no other source for any of them.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UnfencedSuffix {
  family: &'static str,
  column: &'static str,
  admitted: &'static [&'static str],
  found: String,
}

impl UnfencedSuffix {
  /// The refusal, as an emission raises it.
  #[must_use]
  #[inline]
  pub const fn new(
    family: &'static str,
    column: &'static str,
    admitted: &'static [&'static str],
    found: String,
  ) -> Self {
    Self {
      family,
      column,
      admitted,
      found,
    }
  }

  /// The artifact family whose fence refused.
  #[must_use]
  #[inline]
  pub const fn family(&self) -> &'static str {
    self.family
  }

  /// The column the suffix was to be read out of.
  #[must_use]
  #[inline]
  pub const fn column(&self) -> &'static str {
    self.column
  }

  /// What the declaration admits — suffixes on the string road, variant paths on the enum one.
  #[must_use]
  #[inline]
  pub const fn admitted(&self) -> &'static [&'static str] {
    self.admitted
  }

  /// What the row actually held.
  #[must_use]
  #[inline]
  pub fn found(&self) -> &str {
    &self.found
  }
}

impl core::fmt::Display for UnfencedSuffix {
  fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
    write!(
      f,
      "`{}` holds {:?} in `{}`, which the family's own fence does not admit: {}",
      self.family,
      self.found,
      self.column,
      self.admitted.join(", ")
    )
  }
}

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

/// WHERE an artifact family's objects live, and the verb a wire face spends on them.
///
/// # Why the verb is HERE and not bounded at the face
///
/// A resolver holding a family's type and a store would still be unable to call the seam: minting
/// the handle takes one of two construction traits, the read scope is the backend's own associated
/// type, and the payload is a third. Every one of those is knowable only where the STORE TYPE is —
/// and that is exactly this impl. So the impl carries the CALL and the face carries the QUESTION,
/// which is what lets one face be written for every backend there will ever be.
///
/// # Its presence IS the openness, and not a gap
///
/// A family naming a store `ingraph` ships gets this impl from its own expansion. A family naming a
/// store bound at a graph root does not, and cannot: the binding is written where the program is
/// assembled, and no declaration's expansion can see a graph root. So the trait is left
/// hand-implementable, and a third-party store reaches every wire field the shipped one does by
/// writing it — which is the whole of what this seam's openness claim comes to.
///
/// # `type Active` is DEAD, and this is not it under another name
///
/// The design once had a family's expansion project the DEPLOYMENT-SELECTED engine into an
/// associated type. That was measured impossible and ruled out: under single-write the emission
/// writes no door at all, the deployment picks by which handle it OPENS, and a family may legally
/// declare no store. What is projected here is none of those — it is the store TYPE the family's own
/// declared word names, which is a fact of the declaration and not a selection. The OPENED store
/// still arrives at run time, through the door in a request's context, and nothing on this trait is
/// a handle, a root, or a live connection.
#[diagnostic::on_unimplemented(
  message = "`{Self}` has no store its addresses resolve against",
  label = "no store for this artifact family",
  note = "two roads: declare a store `ingraph` ships on the family — `#[ingraph::blob(…, fs)]`, \
          whose expansion writes this impl — or, for a store bound at a graph root, implement \
          `ArtifactStore` for the family yourself; the binding is written where the program is \
          assembled, and no declaration's expansion can see a graph root"
)]
pub trait ArtifactStore: BlobArtifact {
  /// The connection-manager this family's objects live in — the type a request's
  /// [`BlobDoor`](crate::BlobDoor) is keyed by, and therefore the routing itself.
  ///
  /// That door's own law, read from the other end: one door per store type, so an application
  /// serving two families out of two stores installs two doors and each family reaches the one it
  /// named.
  type Store;

  /// WHERE an object is, as this family's store describes it — the form the wire field returns.
  ///
  /// BARE, exactly as [`AsyncLocate::Location`](crate::AsyncLocate::Location) is and for its reason: the
  /// backend defines it, and what a wire face needs OF it is asked at the wire face, where a
  /// location no binding can render fails at the field rather than at this seat.
  type Location;

  /// The read body [`ArtifactData::read`] yields — the store's own, carried through.
  ///
  /// `AsRef<[u8]>` and no more, because the one thing a face does with it is encode it. The seat
  /// stays the backend's for [`AsyncBlobEngine::Payload`](crate::AsyncBlobEngine::Payload)'s reason.
  type Payload: AsRef<[u8]>;

  /// This family's failure — ONE type over both verbs, so a generic use is never
  /// `E0221`-ambiguous.
  ///
  /// `Send + Sync + 'static` so a resolver can surface it on the wire, which is the only party that
  /// ever holds one.
  type Error: core::error::Error + Send + Sync + 'static;

  /// WHERE this family's object for `key` is, or [`None`] where the store KNOWS there is nothing
  /// there yet.
  ///
  /// # ABSENCE IS A VALUE, and a store fault is still an error
  ///
  /// An artifact is written by the indexing pipeline ASYNCHRONOUSLY, after the entity it is derived
  /// from already exists — so *not yet generated* is a normal state of a perfectly healthy
  /// deployment, and a seam that reported it as a failure would be calling the ordinary case an
  /// accident. `None` is what says so, and a bare wire position publishes it as `null`.
  /// [`Error`](Self::Error) keeps what actually went wrong: an address that will not render, a store
  /// that could not be asked.
  ///
  /// # Each impl draws its OWN split, because only the store knows what it is able to know
  ///
  /// A store that can answer presence for FREE and UN-EXPIRING answers it — one whose presence is a
  /// row column it is already holding says `None` honestly, and nothing is spent to find that out.
  ///
  /// The two stores that cannot answer `Some` unconditionally, and say so in their own
  /// documentation. A NETWORK store has no room for a presence check here at all: the seam is
  /// SYNCHRONOUS — [`AsyncLocate::locate`](crate::AsyncLocate::locate)'s pin carried up one layer — so it
  /// renders its address, signs it where it signs, and hands it over. The shipped FILESYSTEM family
  /// takes the same posture, and the reason is TOCTOU rather than budget: a `stat`'s answer expires
  /// the instant it is produced — a `Some` can be gone by the time a client fetches, a `None` can
  /// exist by then — so every consumer must handle absence AT USE anyway, and the per-row syscall
  /// buys an unreliable hint while writing the 404 handling twice.
  ///
  /// So the division is **addressing here, presence at use**: [`ArtifactData::read`] finds an
  /// absence for free and un-expired, because reading IS looking, and a client's own GET finds it at
  /// the fetch. Recorded plainly for whoever deploys on the filesystem family: a bare locate
  /// position never answers `null` there, and the placeholder UX rides `onerror` or the data road.
  ///
  /// The two answers still promise exactly what a store can promise: `Some` is *this is the address,
  /// as far as this store can tell*, and `None` is *this store knows there is nothing to address*. A
  /// backend whose address is a signed URL signs it here; a filesystem joins its root.
  ///
  /// # Errors
  ///
  /// [`Error`](Self::Error) where the address cannot be rendered, or where the store could not be
  /// asked whether the object is there. A MISSING object is neither.
  fn locate(
    store: &Self::Store,
    key: &<Self::Upstream as Transformer>::Key,
    suffix: Option<&str>,
  ) -> Result<Option<Self::Location>, Self::Error>;
}

/// This family's bytes may be served INLINE — the `data` word, as a capability.
///
/// # A trait rather than a flag, because presence has to be CHECKABLE
///
/// The word is written on the FAMILY and the field that spends it is emitted by the ENTITY, so what
/// crosses between them has to be something a bound can ask about. A `const DATA: bool` is readable
/// at run time and useless at emission time; a trait is `E0277` at the word that asked, naming the
/// family and the word it never wrote.
///
/// # A supertrait of [`ArtifactStore`] and not of [`BlobArtifact`]
///
/// Serving bytes means READING them, and reading them takes the store — so the capability saying
/// *these bytes may travel* is only meaningful where there is somewhere to read them from.
/// # The note names BOTH ROADS, because two real words are what this bound joins
///
/// A wire field asking for bytes is written on the ENTITY — a `data` ask inside its `locate(…)`
/// position — because a field's presence belongs to the expansion that writes the `#[Object]` block.
/// The capability is written on the FAMILY, because whether an object may travel inline is a fact
/// about the objects. So an unsatisfied bound here has TWO repairs, in two different declarations,
/// and nothing at this seat can know which one the author meant. A note naming one of them would
/// send half its readers to the wrong file.
#[diagnostic::on_unimplemented(
  message = "`{Self}` does not serve its bytes inline",
  label = "this artifact family answers an address and nothing more",
  note = "TWO ROADS, and which one is the repair is yours to say: write the bare word `data` on \
          the family's own `#[ingraph::blob(…)]`, which is what PERMITS the bytes to travel; or \
          drop `data` from the `locate(…)` position that ASKED for them, leaving that position its \
          address alone. It is opt-in because a blob is arbitrarily large and base64 is a third \
          larger again — an address costs a client one round trip it controls, and inline bytes \
          cost it the whole object whether it wanted them or not"
)]
pub trait ArtifactData: ArtifactStore {
  /// The BYTES of this family's object for `key`, or [`None`] where there is no object to read.
  ///
  /// The one verb in the family that does I/O, so it is the one the dual-mode criterion twins one
  /// layer down — and it is async HERE because the only caller is a wire resolver, which is async
  /// whatever its store is. A blocking store reaches it through a future that is already complete,
  /// which is what the shipped filesystem citizen hands back and says so.
  ///
  /// # ABSENCE IS A VALUE at BOTH store-mediated roads, and the word means one thing
  ///
  /// [`ArtifactStore::locate`](Self::locate) answers an `Option` because *not yet generated* is the
  /// ordinary state of an asynchronously written artifact. The same sentence is true of the bytes,
  /// and the read is the road that finds it out FOR FREE and un-expired: a store looks in order to
  /// answer at all, so what it learns on the way is either bytes or the knowledge that there are
  /// none. Reporting the second as a failure would call the ordinary case an accident, one road
  /// after the seam beside it stopped doing so.
  ///
  /// A bare `data` position publishes the `None` as `null`; a position whose declaration signed
  /// `required` converts it into the named field error, which is `locate`'s own fork one field over
  /// and reaches the client through the same refusal type.
  ///
  /// # Errors
  ///
  /// [`Error`](Self::Error) where the object could not be READ — a permission, an address that will
  /// not render, a store that could not be reached. A MISSING object is none of those.
  fn read(
    store: &Self::Store,
    key: &<Self::Upstream as Transformer>::Key,
    suffix: Option<&str>,
  ) -> impl Future<Output = Result<Option<Self::Payload>, Self::Error>> + Send;
}

/// A blob-store entry: its byte payload and its file format.
///
/// Independent of the other record faces — no shared supertrait; its identity is the orthogonal
/// [`Transformer`] address, implemented separately. Like [`FulltextRecord`], the neutral trait
/// exposes the VALUE, because a blob's payload is a byte string in every backend.
///
/// # The key IS the address
///
/// A blob's key stores AS its fields — the segments of a HIERARCHICAL OBJECT NAME, in the key's own
/// column order, parent ids first — so an entity's subtree contains every descendant artifact and a
/// hard-delete by lineage is a prefix removal. A filesystem renders that name as directory levels,
/// an object store as object-key segments where the lineage prefix maps to a key-prefix delete.
/// Deliberately NOT content-addressed: identical bytes under two keys store twice, which is exactly
/// what keeps a key's location stable when its bytes are rewritten.
///
/// The rendering itself is the BACKEND's — see [`store`](crate::store), where a backend's own record
/// trait says how a key becomes an address. This trait states what every backend needs and no
/// backend's scheme.
pub trait BlobRecord {
  /// The byte payload this entry stores.
  ///
  /// Bound by nothing here: what a payload must BE — `AsRef<[u8]>`-class, a borrowed slice, a
  /// refcounted buffer — is the storing backend's question, and its own impl asks it.
  type Bytes;

  /// The bytes to store.
  ///
  /// By reference: it is a payload, read rather than consumed, and a record is stored without being
  /// given up.
  fn bytes(&self) -> &Self::Bytes;

  /// This artifact family's file extension, for human browsability of the address's leaf
  /// (`<key>.<ext>`); `None` for extensionless, which is the default.
  ///
  /// TYPE-LEVEL, not `&self`, and that is the whole of why it is on this trait rather than a field:
  /// the address is derivable from the key alone, and a by-key `get` has NO record instance to ask
  /// — so the extension a `put` appended has to be reconstructible from the type, or a read would
  /// resolve `<key>` where the write left `<key>.png`.
  fn extension() -> Option<&'static str> {
    None
  }
}

/// A vector-index entry: its embedding.
///
/// Unlike a meta record, the neutral trait exposes the VALUE — an embedding is kind-shaped, a
/// coordinate array in every backend, where a row's value is backend-shaped columns — so there is
/// something for a bound-free trait to return. That is [`FulltextRecord`]'s asymmetry one family
/// over, and it is principled rather than incidental.
///
/// # The element is a TYPE FACT, and it is the element type itself
///
/// `type Element = f32`, not a marker standing for `f32`. The reference implementation named one
/// marker per element — `element::F32`, whose `Carrier` was `Arc<[f32]>` — for a reason that was
/// about NAMES rather than about elements: a free `F32` type would have collided with the
/// primitive and with the arms of the runtime enum beside it.
/// [`Embedding<E, N>`](crate::Embedding) dissolved that collision by naming the primitive, so the
/// element crosses as itself and [`vector`](Self::vector) hands back a slice — the carrier SPELLED
/// rather than projected through a marker's associated type.
///
/// What survives the change is why the element was a type at all: it is a COMPILE-TIME INVARIANT,
/// so one record cannot yield mixed elements across its instances. What does not survive is what
/// the marker carried BESIDE the carrier — a `descriptor()` naming a runtime element tag, and a
/// `to_value()` packing coordinates for a staged write. Each belonged to machinery this crate does
/// not have.
///
/// # The width is a fact of the FIELD, and it is not restated here
///
/// A record whose field is `Embedding<f32, 768>` yields 768 coordinates because
/// [`Embedding::new`](crate::Embedding::new) checked the length once, at construction. A `const
/// DIM` on this trait would be a second home for that fact, and two homes for one fact are free to
/// disagree. Where a width must be PASSED — [`AsyncVectorStore::vector`](crate::AsyncVectorStore::vector)
/// takes a slot's `dim` — the call site reads [`Embedding::DIM`](crate::Embedding::DIM) off the
/// same field type, so the width has one author whether it is used as a type or as a number.
///
/// # Examples
///
/// A record projecting an embedding field, and the width read off that field's own type:
///
/// ```
/// use std::sync::Arc;
///
/// use ingraph::{Embedding, VectorColumn, VectorRecord};
///
/// struct Keyframe {
///   media: u64,
///   ordinal: u32,
///   embedding: Embedding<f32, 768>,
/// }
///
/// struct KeyframeLineage {
///   media: u64,
/// }
///
/// impl VectorRecord for Keyframe {
///   type Element = f32;
///   type Filter = KeyframeLineage;
///
///   fn vectors(&self) -> impl Iterator<Item = (VectorColumn, &[f32])> {
///     core::iter::once((
///       VectorColumn::new("embedding"),
///       self.embedding.coordinates(),
///     ))
///   }
/// }
///
/// fn coordinates_of<T: VectorRecord>(record: &T) -> Vec<(VectorColumn, &[T::Element])> {
///   record.vectors().collect()
/// }
///
/// let keyframe = Keyframe {
///   media: 7,
///   ordinal: 12,
///   embedding: Embedding::new(Arc::from(vec![0.5; 768])).expect("768 coordinates"),
/// };
///
/// let elected = coordinates_of(&keyframe);
/// assert_eq!(elected.len(), 1, "one election is the smallest N, not a different shape");
/// assert_eq!(elected[0].1.len(), Embedding::<f32, 768>::DIM);
/// ```
///
/// And the bound reaches no key, because there is none to reach — the address is
/// [`Transformer`]'s, implemented beside this face rather than beneath it:
///
/// ```compile_fail,E0220
/// use ingraph::VectorRecord;
///
/// fn key_of<T: VectorRecord>(record: &T) -> T::Key {
///   record.key()
/// }
/// ```
///
/// # A record states N embeddings, and the ELECTION is what names each one
///
/// One declaration may elect several embeddings and they live as several columns of ONE slot, so
/// what this face hands back is a LIST of (column, coordinates) rather than one slice. N = 1 is the
/// smallest N and not a separate shape: a single-election record yields a one-item iterator, and no
/// caller branches on the count.
///
/// The columns are the ELECTED ones and nothing else. A declaration's other embedding-typed fields
/// are ordinary payload — stored, hydrated, reached through their own accessors — and they are
/// absent here, which is the payload posture made mechanical rather than promised: what no election
/// names, no `knn` can reach, through any column.
pub trait VectorRecord {
  /// The embedding's ELEMENT — the coordinate type itself: `f32`, a half-precision type, a
  /// quantized element a user engine brings.
  ///
  /// Bound by nothing here, for the reason [`Embedding`](crate::Embedding)'s own `E` carries none:
  /// a width, a length and a borrow are answerable for any element at all. What an ENGINE can
  /// MATERIALIZE is that engine's own question, answered by its own
  /// [`VectorEngine::Element`](crate::VectorEngine::Element) — and not on the
  /// vocabulary a declaration writes. A bound stated here would additionally make an
  /// `Embedding<Q8, 8>` that BUILDS and cannot be declared, which is the vocabulary contradicting
  /// itself one layer apart.
  type Element;

  /// The entity's LINEAGE FILTER — what a search over this record may scope by, *nearest within
  /// media X*, and the read-side twin of [`Element`](Self::Element)'s type fact.
  ///
  /// BOUND-FREE, deliberately: the capability a scope needs is the SEARCHED ENGINE's, not this
  /// trait's — a SQL-hosted face demands a where-clause its own dialect renders, a standalone index
  /// demands its own — so each engine's own read scope
  /// ([`VectorRead::ReadContext`](crate::VectorRead::ReadContext)) is where one is lowered, and
  /// a record whose filter no face can lower is refused there rather than here. Naming it HERE is
  /// what keeps ONE filter per entity across every engine that indexes it.
  ///
  /// `()` is the no-scope case, and a face lowers it to no predicate at all — the un-scoped path,
  /// reached without a branch.
  ///
  /// It replaces the erased form the reference implementation validated at every op head: a list of
  /// column-name/value pairs, checked against the key's columns each time one was used. A typed
  /// filter names its own struct's fields at its own types, so the stray column and the mistyped
  /// value are `E0609` and `E0308` where the query is written.
  type Filter;

  /// EVERY elected embedding, each under the [`VectorColumn`] a `knn` selects it by, in the order
  /// the declaration elected them.
  ///
  /// By reference: coordinates are large, and read rather than consumed.
  ///
  /// A SLICE rather than the [`Embedding`](crate::Embedding) itself, which is the one place the
  /// width is deliberately dropped: naming the field type here would put `N` on this trait, and the
  /// section above says why the width lives in one home. What the slice loses is checked where it
  /// was established — a value of that field type has its width or was never built.
  ///
  /// An ITERATOR rather than a `Vec`, because the write half's whole use of this is to walk the
  /// columns into an engine's own entry, and the emission's implementation is an array of the
  /// declaration's own elections — so nothing allocates to be walked once.
  ///
  /// ONE [`Element`](Self::Element) across all of them, which is the SLOT's own arithmetic read from
  /// this side: a slot is opened at one element and a handle over it materializes that one
  /// ([`VectorEngine::Element`](crate::VectorEngine::Element)), so N columns of one slot are N
  /// columns of one element. A declaration electing two fields at two element types is refused by
  /// rustc where this method is emitted, at the span of the election that disagrees.
  fn vectors(&self) -> impl Iterator<Item = (VectorColumn, &[Self::Element])>;

  /// Every SET election's members, each under its column and its ORDINAL — the multi-vector round's
  /// whole footprint on the write side.
  ///
  /// # Two methods rather than one widened one
  ///
  /// A field declared `Embedding<E, N>` elects ONE embedding and a field declared
  /// `Vec<Embedding<E, N>>` elects a SET of them, and the ruling that made the TYPE state which is
  /// the same ruling that leaves the single form untouched. So a single election is reported by
  /// [`vectors`](Self::vectors) exactly as it always was, a set election is reported here, and no
  /// column appears in both. A reader asking *what is stored under this column* asks one method and
  /// learns the shape from which one answered.
  ///
  /// Widening [`vectors`](Self::vectors) instead would have put an ordinal on every single election
  /// — a number whose only legal value is zero, carried by every declaration that never asked for a
  /// set — and would have moved a face every hand-written record already implements.
  ///
  /// # The ORDINAL is a value, and it is the one thing the flat shape needs
  ///
  /// The stream is FLAT — the same [`VectorColumn`] repeats, once per member — because a nested
  /// `impl Iterator<Item = impl Iterator<…>>` is `E0562` in return position. What a nested shape
  /// would have carried by POSITION this carries by NUMBER, and the number is the better of the two:
  /// the universal physical form stores a set as one row per member keyed by owner AND ordinal, so
  /// the ordinal is a column of that row either way, and reading it off a position would be a fact
  /// this face knew and the row had to re-derive.
  ///
  /// **Frame order is preserved**: ordinals run `0..n` in the order the field holds its members, so
  /// a set of keyframe embeddings comes back in keyframe order on either physical form.
  ///
  /// # Defaulted to EMPTY, which is what every single-election record means
  ///
  /// A declaration with no set election implements nothing here, and every record written before
  /// this method existed keeps compiling and keeps meaning what it meant. The default is the honest
  /// value rather than a convenience: a record with no set elections has no set members.
  #[inline]
  fn vector_sets(&self) -> impl Iterator<Item = (VectorColumn, u32, &[Self::Element])> {
    core::iter::empty()
  }
}