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
//! The positions, asserted over types this module registers nothing for.
//!
//! Every claim here is a type equation, and the types it is written over are declared in this file
//! rather than taken from the registry. That is deliberate: the registry's rows are what a later
//! test pins, and the MECHANISM has to hold for a type the framework has never seen — which is the
//! whole thing the marker layer buys over a row keyed on the type.

use super::*;
// The filter types come from the crate root rather than from `super::*`: what this module declares
// is the INTERPRETATION, and what one resolves to is a row kept with the axis that owns the answer.
// Every claim below is a type equation across that boundary, so naming both sides is the point.
use crate::{
  BytesFilter, EnumFilter, ListFilter, Nullable, QuantifiedFilter, SetFilter, TextFilter,
};

/// Two type expressions name the SAME type. Unifying `A` is the whole check: rustc rejects the call
/// when the two differ, so a wrong answer is a compile error rather than a failed assertion.
fn same<A>(_: core::marker::PhantomData<A>, _: core::marker::PhantomData<A>) {}

/// A container this crate did not declare and does not register, standing in for the downstream
/// collection the orphan rule always allowed and the framework could never reach.
struct Roll<T>(core::marker::PhantomData<T>);

/// A field type a declaring crate owns — the element the framework's `Vec` rows have to cover
/// without knowing it exists.
struct Tag;

// The two rows that make `Tag` an ELEMENT rather than only a field type. A collection filter carries
// the filter ONE member is guarded by, so its second parameter defaults through the element's own
// reading, and an element with no reading has none for that default to project through.
impl EnumFilterMarker for Tag {
  type Filter = EnumFilter<Tag>;
}

impl DefaultMarker for Tag {
  type Marker = EnumMarker<Tag>;
}

// What a `Vec` of it means, which is what a composed marker over an OPTIONAL collection reads to
// default its inner half: the peel lands on `Vec<Tag>`, and a `Vec` takes its reading from here.
impl DefaultVecMarker for Tag {
  type Marker = ListMarker<Vec<Tag>>;
}

impl BytesFilterMarker for Roll<Tag> {
  type Filter = BytesFilter<Roll<Tag>>;
}

// What a `Roll` HOLDS — the row a composed marker over it reads, and the one a downstream container
// writes beside its filter rows. Without it `ListMarker<Roll<Tag>, _>` has nothing to check its
// inner marker against.
impl<T> State<Extracted<Inner>> for Roll<T> {
  type Output = T;
}

impl<T> ListFilterMarker for Roll<T> {
  type Filter<VF> = ListFilter<T, VF>;
}

impl<T> SetFilterMarker for Roll<T> {
  type Filter<VF> = SetFilter<T, VF>;
}

// The third COLLECTION position, which a downstream container answers exactly as it answers the
// other two — one row, naming a local type, and no framework change to admit it.
impl<T> QuantifiedFilterMarker for Roll<T> {
  type Filter<VF> = QuantifiedFilter<T, VF>;
}

/// The claim the whole module is for: ONE type, four positions, four answers, and no coherence
/// error between them.
///
/// `Roll<Tag>` is a type nothing here registers, so a registry keyed on the type would have to
/// choose one of these four for it. The markers make all four spellable at once, because
/// `BytesMarker<Roll<Tag>>`, `ListMarker<Roll<Tag>>`, `SetMarker<Roll<Tag>>` and
/// `QuantifiedMarker<Roll<Tag>>` are different self types and the outer impls therefore cannot
/// overlap.
#[test]
fn one_type_answers_once_per_position() {
  same(
    core::marker::PhantomData::<<BytesMarker<Roll<Tag>> as ToGraphqlFilter>::Filter>,
    core::marker::PhantomData::<BytesFilter<Roll<Tag>>>,
  );
  same(
    core::marker::PhantomData::<<ListMarker<Roll<Tag>> as ToGraphqlFilter>::Filter>,
    core::marker::PhantomData::<ListFilter<Tag, EnumFilter<Tag>>>,
  );
  same(
    core::marker::PhantomData::<<SetMarker<Roll<Tag>> as ToGraphqlFilter>::Filter>,
    core::marker::PhantomData::<SetFilter<Tag, EnumFilter<Tag>>>,
  );
  // The narrow collection reading, over the same container and the same element. It resolves through
  // its own family trait, so the three collection answers are three rows rather than one with a
  // flag — which is what lets a container answer some of them and not others.
  same(
    core::marker::PhantomData::<<QuantifiedMarker<Roll<Tag>> as ToGraphqlFilter>::Filter>,
    core::marker::PhantomData::<QuantifiedFilter<Tag, EnumFilter<Tag>>>,
  );
}

/// A VALUE reading is no longer at most one, and this is the pair that says so: `Label` answers the
/// string family and the bytes family both, from two impls that never meet.
///
/// The single trait could not express it — one `type Filter` per type, so the second value reading
/// was `E0119`. Splitting by family buys the two directions at once: a type may answer several, and
/// a type that answers none of a family's is refused by it rather than quietly given whatever its
/// one reading was.
#[test]
fn one_type_answers_two_value_families() {
  struct Label;

  impl StringFilterMarker for Label {
    type Filter = TextFilter<Label>;
  }

  impl BytesFilterMarker for Label {
    type Filter = BytesFilter<Label>;
  }

  same(
    core::marker::PhantomData::<<StringMarker<Label> as ToGraphqlFilter>::Filter>,
    core::marker::PhantomData::<TextFilter<Label>>,
  );
  same(
    core::marker::PhantomData::<<BytesMarker<Label> as ToGraphqlFilter>::Filter>,
    core::marker::PhantomData::<BytesFilter<Label>>,
  );
}

/// The framework's two `Vec` rows reach an element type it has never heard of — which is the impl
/// a declaring crate could not write for itself.
///
/// `impl ToGraphqlFilter for Vec<Tag>` outside this crate is `E0117`: `Vec` is foreign there, the
/// trait is foreign there, and `Vec` is not fundamental. Under markers there is nothing to write —
/// `impl<T> ListFilterMarker for Vec<T>` above already answers, for every `T`.
#[test]
fn the_frameworks_vec_rows_cover_an_unregistered_element() {
  same(
    core::marker::PhantomData::<<ListMarker<Vec<Tag>> as ToGraphqlFilter>::Filter>,
    core::marker::PhantomData::<ListFilter<Tag>>,
  );
  same(
    core::marker::PhantomData::<<SetMarker<Vec<Tag>> as ToGraphqlFilter>::Filter>,
    core::marker::PhantomData::<SetFilter<Tag>>,
  );
  same(
    core::marker::PhantomData::<<QuantifiedMarker<Vec<Tag>> as ToGraphqlFilter>::Filter>,
    core::marker::PhantomData::<QuantifiedFilter<Tag>>,
  );
}

/// The nullable marker wraps whatever interpretation it is HANDED, so nesting composes by type
/// application rather than by threading a state through a sequence of decisions.
///
/// Both rows are over one Rust type, and they differ only in the marker underneath — which is what
/// says the wrapper reads none of the type and all of the marker.
#[test]
fn a_nullable_marker_wraps_the_interpretation_below_it() {
  struct Reel;

  impl StringFilterMarker for Reel {
    type Filter = TextFilter<Reel>;
  }

  same(
    core::marker::PhantomData::<
      <NullableMarker<Option<Reel>, StringMarker<Reel>> as ToGraphqlFilter>::Filter,
    >,
    core::marker::PhantomData::<Nullable<TextFilter<Reel>>>,
  );
  // The SAME optional type under a different inner marker, which is what says the wrapper reads none
  // of the type and all of the marker: `Roll<Tag>` is optional here and its elements are read as
  // enumerations, and neither fact comes from `Option`.
  same(
    core::marker::PhantomData::<
      <NullableMarker<Option<Roll<Tag>>, ListMarker<Roll<Tag>>> as ToGraphqlFilter>::Filter,
    >,
    core::marker::PhantomData::<Nullable<ListFilter<Tag, EnumFilter<Tag>>>>,
  );
  same(
    core::marker::PhantomData::<
      <NullableMarker<Option<Roll<Tag>>, SetMarker<Roll<Tag>>> as ToGraphqlFilter>::Filter,
    >,
    core::marker::PhantomData::<Nullable<SetFilter<Tag, EnumFilter<Tag>>>>,
  );
}

/// The INFERENCE: a type carries a marker, an `Option` of it carries whatever that marker says an
/// `Option` of it is, and a declaration spells neither.
///
/// `Codec` is an enumeration, so the marker's answer is the null test — a closed vocabulary is a
/// VALUE and a value can be absent. The collection half of the same question is
/// [`a_vec_takes_its_default_from_its_element`]'s closing row.
///
/// The `Option` row comes from ONE blanket over every `T`, so it reaches a type declared here — and
/// would reach one declared downstream, where `impl DefaultMarker for Option<TheirType>` is
/// `E0117`.
#[test]
fn an_option_infers_the_null_test_over_the_inner_marker() {
  struct Codec;

  impl EnumFilterMarker for Codec {
    type Filter = EnumFilter<Codec>;
  }

  impl DefaultMarker for Codec {
    type Marker = EnumMarker<Codec>;
  }

  same(
    core::marker::PhantomData::<<<Codec as DefaultMarker>::Marker as ToGraphqlFilter>::Filter>,
    core::marker::PhantomData::<EnumFilter<Codec>>,
  );
  same(
    core::marker::PhantomData::<
      <<Option<Codec> as DefaultMarker>::Marker as ToGraphqlFilter>::Filter,
    >,
    core::marker::PhantomData::<Nullable<EnumFilter<Codec>>>,
  );
}

/// A `Vec`'s default is the ELEMENT's to decide, which is what makes two `Vec` columns over
/// different element types resolve to different KINDS — and what lets a declaring crate say its own
/// collections are sets.
///
/// The two elements here are the two answers: `Note` takes the ordered reading and `Label` the
/// unordered one, over the same `Vec`, from rows on the elements alone.
#[test]
fn a_vec_takes_its_default_from_its_element() {
  struct Note;
  struct Label;

  // A collection filter holds the filter ONE member is guarded by, so each element needs a reading
  // of its own for the `Vec` rows to project through.
  impl EnumFilterMarker for Note {
    type Filter = EnumFilter<Note>;
  }

  impl DefaultMarker for Note {
    type Marker = EnumMarker<Note>;
  }

  impl EnumFilterMarker for Label {
    type Filter = EnumFilter<Label>;
  }

  impl DefaultMarker for Label {
    type Marker = EnumMarker<Label>;
  }

  impl DefaultVecMarker for Note {
    type Marker = ListMarker<Vec<Note>>;
  }

  impl DefaultVecMarker for Label {
    type Marker = SetMarker<Vec<Label>>;
  }

  same(
    core::marker::PhantomData::<<<Vec<Note> as DefaultMarker>::Marker as ToGraphqlFilter>::Filter>,
    core::marker::PhantomData::<ListFilter<Note>>,
  );
  same(
    core::marker::PhantomData::<<<Vec<Label> as DefaultMarker>::Marker as ToGraphqlFilter>::Filter>,
    core::marker::PhantomData::<SetFilter<Label>>,
  );
  // The two blankets compose, and the `Option` one asks the SET marker the element chose what an
  // optional set is read as — which is the set itself. Neither row above says anything about
  // nullability, and the answer says nothing about it either.
  same(
    core::marker::PhantomData::<
      <<Option<Vec<Label>> as DefaultMarker>::Marker as ToGraphqlFilter>::Filter,
    >,
    core::marker::PhantomData::<SetFilter<Label>>,
  );
}

/// **THE DECLARATION ROAD TO THE NARROW READING**, and it is the row a declaring crate already
/// writes to say its `Vec` is a set — one word different.
///
/// `Sighting` is the element this kind was cut for: a pair carrying a float, so no literal a client
/// could type is a useful operand for it. It has an element READING all the same — its own filter,
/// where its fields are asked about honestly — and the `Vec` row is where the collection seat picks
/// the reading that publishes only the two questions the element can answer.
///
/// Nothing about the element is asked by the answer, which is what the closing row states: the
/// projection resolves for a type with no wire form of any kind.
#[test]
fn a_vec_takes_the_quantified_reading_from_its_element() {
  use core::marker::PhantomData as P;

  /// A detection: a code and a confidence. Deliberately NOT `Clone`, `PartialEq`, `Send` or `Sync`,
  /// and with no crossing of any sort — every one of those is a bound the narrow collection does not
  /// ask for, and a fixture that satisfied them would not say so.
  struct Sighting(
    #[expect(
      dead_code,
      reason = "the field IS the fixture: a float is what leaves this element with no honest \
                literal form, and a `Cell` is what leaves it neither `Send` nor `Sync`. Both are \
                properties the projection below has to resolve WITHOUT, so a fixture that read the \
                value would be asserting less than this one does"
    )]
    core::cell::Cell<f32>,
  );

  /// The element's OWN filter, standing in for what a declaration composes: what a caller asks about
  /// one member, in a vocabulary where a float is a range rather than a literal to match.
  struct SightingFilter;

  impl ScalarFilterMarker for Sighting {
    type Filter = SightingFilter;
  }

  impl DefaultMarker for Sighting {
    type Marker = ScalarMarker<Sighting>;
  }

  // The one row a declaring crate writes, and the whole of what mounting the narrow kind costs it.
  impl DefaultVecMarker for Sighting {
    type Marker = QuantifiedMarker<Vec<Sighting>>;
  }

  same(
    P::<<<Vec<Sighting> as DefaultMarker>::Marker as ToGraphqlFilter>::Filter>,
    P::<QuantifiedFilter<Sighting, SightingFilter>>,
  );
  // The `Option` blanket asks the marker the element chose what an optional one reads as, and at a
  // collection the `Option` is transparent — so an `Option<Vec<Sighting>>` column is the same
  // filter, `Option` and all.
  same(
    P::<<<Option<Vec<Sighting>> as DefaultMarker>::Marker as ToGraphqlFilter>::Filter>,
    P::<QuantifiedFilter<Sighting, SightingFilter>>,
  );
}

/// **What the second parameter BUYS**, over the one type where the framework's own default is the
/// interesting one: `Vec<u8>` is a blob, so a `Vec<Vec<u8>>` is a list OF BLOBS by default — and the
/// override reads the same Rust type as a list of LISTS.
///
/// Both rows are one Rust type and the outer marker is the same `ListMarker`; only the inner marker
/// differs, and the element filter differs with it. That is the reading the marker layer could not
/// express while the collection markers carried no element marker, and it is why the parameter is
/// here rather than waiting for a declaration word.
#[test]
fn an_inner_marker_overrides_the_elements_default_reading() {
  use core::marker::PhantomData as P;

  use crate::{ScalarFilter, ScalarMarker};

  // Inferred: the element's own `DefaultVecMarker` row says a `Vec<u8>` is bytes.
  same(
    P::<<ListMarker<Vec<Vec<u8>>> as ToGraphqlFilter>::Filter>,
    P::<ListFilter<Vec<u8>, BytesFilter<Vec<u8>>>>,
  );
  // Overridden: the same collection, its elements read as lists of small integers.
  same(
    P::<<ListMarker<Vec<Vec<u8>>, ListMarker<Vec<u8>>> as ToGraphqlFilter>::Filter>,
    P::<ListFilter<Vec<u8>, ListFilter<u8, ScalarFilter<u8>>>>,
  );
  // …and naming the inner marker explicitly where it AGREES with the default resolves to the
  // default's answer, which is what makes the parameter an override rather than a second dialect.
  same(
    P::<<ListMarker<Vec<u8>, ScalarMarker<u8>> as ToGraphqlFilter>::Filter>,
    P::<<ListMarker<Vec<u8>> as ToGraphqlFilter>::Filter>,
  );
}

/// **A marker names its own optional reading**, and the two answers are the two families: a value's
/// `Option` is a null test, a collection's is spent.
///
/// The rows are over `Roll<Tag>` and `Tag` — types the framework registers nothing for — because the
/// answer is a fact about the MARKER rather than about the type it is applied to, and a row keyed on
/// the type is the thing this layer exists to replace.
#[test]
fn a_marker_names_the_reading_an_option_of_it_takes() {
  use core::marker::PhantomData as P;

  same(
    P::<<EnumMarker<Tag> as Marker>::UnderOption>,
    P::<NullableMarker<Option<Tag>, EnumMarker<Tag>>>,
  );
  same(
    P::<<ListMarker<Roll<Tag>> as Marker>::UnderOption>,
    P::<OptionalMarker<Option<Roll<Tag>>, ListMarker<Roll<Tag>>>>,
  );
  same(
    P::<<SetMarker<Roll<Tag>> as Marker>::UnderOption>,
    P::<OptionalMarker<Option<Roll<Tag>>, SetMarker<Roll<Tag>>>>,
  );
  // The third collection family answers the collection ANSWER, and that is the point of asserting
  // it here: what makes the `Option` transparent is the storage a collection has, which does not
  // vary with the operators a reading publishes.
  same(
    P::<<QuantifiedMarker<Roll<Tag>> as Marker>::UnderOption>,
    P::<OptionalMarker<Option<Roll<Tag>>, QuantifiedMarker<Roll<Tag>>>>,
  );
  // The composed readings answer in their own lane, which is what makes a second `Option` change
  // nothing about the family: a null test stays one, an optional reading stays optional.
  same(
    P::<<NullableMarker<Option<Tag>, EnumMarker<Tag>> as Marker>::UnderOption>,
    P::<NullableMarker<Option<Option<Tag>>, NullableMarker<Option<Tag>, EnumMarker<Tag>>>>,
  );
  same(
    P::<<OptionalMarker<Option<Roll<Tag>>, ListMarker<Roll<Tag>>> as Marker>::UnderOption>,
    P::<
      OptionalMarker<
        Option<Option<Roll<Tag>>>,
        OptionalMarker<Option<Roll<Tag>>, ListMarker<Roll<Tag>>>,
      >,
    >,
  );
}

/// An optional reading's filter IS the inner marker's, with nothing of the optional type left in it
/// — which is the whole of what the marker does, stated as a type equation.
///
/// The twin beside it is the null test over the SAME two halves, so what separates the two rows is
/// the outer marker and nothing else.
#[test]
fn an_optional_reading_resolves_to_the_inner_markers_filter() {
  use core::marker::PhantomData as P;

  same(
    P::<<OptionalMarker<Option<Roll<Tag>>, ListMarker<Roll<Tag>>> as ToGraphqlFilter>::Filter>,
    P::<ListFilter<Tag, EnumFilter<Tag>>>,
  );
  same(
    P::<<NullableMarker<Option<Roll<Tag>>, ListMarker<Roll<Tag>>> as ToGraphqlFilter>::Filter>,
    P::<Nullable<ListFilter<Tag, EnumFilter<Tag>>>>,
  );
  // `VM` defaults exactly as the other composed markers' do — through what the OPTIONAL type holds,
  // so the whole spelling is the `Option` alone.
  same(
    P::<<OptionalMarker<Option<Vec<Tag>>> as ToGraphqlFilter>::Filter>,
    P::<ListFilter<Tag, EnumFilter<Tag>>>,
  );
}

/// The DEFAULT resolves to what it resolved to before the parameter existed — asserted against the
/// filter type written out, so that a change to the default is a red test here rather than a moved
/// wire face somewhere else.
#[test]
fn the_omitted_parameter_is_the_elements_own_reading() {
  use core::marker::PhantomData as P;

  same(
    P::<<ListMarker<Vec<Tag>> as ToGraphqlFilter>::Filter>,
    P::<ListFilter<Tag, EnumFilter<Tag>>>,
  );
  same(
    P::<<SetMarker<Vec<Tag>> as ToGraphqlFilter>::Filter>,
    P::<SetFilter<Tag, EnumFilter<Tag>>>,
  );
  same(
    P::<<QuantifiedMarker<Vec<Tag>> as ToGraphqlFilter>::Filter>,
    P::<QuantifiedFilter<Tag, EnumFilter<Tag>>>,
  );
  same(
    P::<<NullableMarker<Option<Tag>> as ToGraphqlFilter>::Filter>,
    P::<Nullable<EnumFilter<Tag>>>,
  );
}