ingraph-derive 0.1.0

The attribute and derive macros for ingraph: the words a record, node, key, filter and vocabulary declaration is written in.
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
//! THE ENGINE BLOCKS, read off a field — the words, their options, the liveness marker, and every
//! refusal each of them carries.
//!
//! Beside [`tests`](super::tests) and [`asked`](super::asked) rather than inside either, on the same
//! precedent: one file per thing being proved, so a reader looking for what an engine block MEANS
//! finds it whole.
//!
//! # What is asserted here, and what is asserted elsewhere
//!
//! Here: the MODEL a declaration produces, and the SENTENCE a refusal carries. The emission's own
//! shapes — the slot markers, the fan-out door — are `ingraph-codegen`'s `index/engines.rs`, where a
//! method's name is a token to read. Whether a write actually reaches one store or two is
//! `ingraph`'s `tests/engine_fanout.rs`, where there are live stores to read back.
//!
//! # Every refusal is stated as an EXCLUSION too
//!
//! The vocabulary is OPEN, so the walk admits any word it does not own — which means a test that
//! only checked *this word parsed* would pass for a parser that admitted everything, including the
//! words the framework does own. So the accepting tests name what the word must NOT have swallowed
//! (`copy` is still a projection, `knn` is still the election), and the refusing ones pin the
//! sentence rather than the fact that something was refused.

use ingraph_codegen::{
  index::IndexModel,
  prelude::{NodeKind, Projection},
};

use super::tests::{fulltext, refused};

/// The pass under test at the VECTOR kind, which is where an `Embedding` field is legal.
fn vector(input: &syn::DeriveInput) -> syn::Result<IndexModel> {
  let (host, arguments) = crate::host::split(input);
  super::super::index::parse(&host, &arguments, NodeKind::Vector)
}

/// Every `(field, engine)` pair a model declares, as `field::engine` strings in declared order.
fn slots(model: &IndexModel) -> Vec<String> {
  model
    .slots()
    .into_iter()
    .map(|slot| format!("{}::{}", slot.field, slot.engine))
    .collect()
}

/// A full-text document whose two fields wear the given marker lists verbatim.
fn document(title: &str, body: &str) -> syn::DeriveInput {
  let title: proc_macro2::TokenStream = title.parse().expect("a marker list");
  let body: proc_macro2::TokenStream = body.parse().expect("a marker list");
  syn::parse_quote! {
    #[ingraph(upstream(node = "asr::Segment", title = "speaker", body = "text"), dedup(hash))]
    pub struct SearchDocument {
      #[ingraph(#title)]
      title: String,
      #[ingraph(#body)]
      body: String,
    }
  }
}

#[test]
fn a_bare_word_beside_the_marker_is_an_engine() {
  let model = fulltext(&document("searchable, lexical", "searchable")).expect("accepted");
  // `body` wrote no engine block, so it takes the SOLE-DEFAULT LABEL — its own field name.
  assert_eq!(slots(&model), ["title::lexical", "body::body"]);
}

/// The BLOCK form, and its contents are carried rather than read: they name a knob of an engine this
/// crate has never heard of, so reading them would close the vocabulary through the back door.
#[test]
fn an_engine_block_carries_its_own_options_verbatim() {
  let model = fulltext(&document(
    "searchable, hnsw(ef = 200, m = 16)",
    "searchable",
  ))
  .expect("accepted");
  let carried = model.engines[0].engines[0].options.to_string();
  assert!(carried.contains("ef"), "the knobs are carried: {carried}");
  assert!(carried.contains("200"), "with their values: {carried}");
  assert!(carried.contains("16"), "all of them: {carried}");
}

/// ORDER is kept, for the reason the record side keeps its backends' order: the slots emit in the
/// order the author wrote them, so an expansion is stable and diffable.
#[test]
fn several_engines_keep_the_order_they_were_written_in() {
  let model =
    fulltext(&document("searchable, hnsw, lexical, sonic", "searchable")).expect("accepted");
  assert_eq!(
    slots(&model),
    [
      "title::hnsw",
      "title::lexical",
      "title::sonic",
      "body::body"
    ]
  );
}

/// The words may be written BEFORE the election, and this is why the two judgements the walk cannot
/// make live after it: a marker list has no order.
#[test]
fn an_engine_may_be_written_before_the_marker() {
  let model = fulltext(&document("hnsw, searchable, lexical", "searchable")).expect("accepted");
  assert_eq!(
    slots(&model),
    ["title::hnsw", "title::lexical", "body::body"]
  );
}

/// The open half must not have eaten the closed one. A parser that took every unclaimed word as an
/// engine and stopped there would still pass the tests above.
#[test]
fn the_framework_words_are_still_the_framework_s() {
  let model = fulltext(&document("searchable, optional, hnsw", "searchable")).expect("accepted");
  assert_eq!(model.fields[0].project, Projection::Optional);
  assert_eq!(model.searchable.len(), 2);
  assert_eq!(slots(&model), ["title::hnsw", "body::body"]);
}

/// TWO FIELDS sharing an engine repeat the word, and that is TWO SLOTS. It is the case the
/// duplicate refusal must not catch, so it is pinned beside it.
#[test]
fn two_fields_may_share_an_engine_and_that_is_two_slots() {
  let model = fulltext(&document("searchable, lexical", "searchable, lexical")).expect("accepted");
  assert_eq!(slots(&model), ["title::lexical", "body::lexical"]);
}

#[test]
fn fanout_over_two_engines_is_accepted_and_recorded() {
  let model =
    fulltext(&document("searchable, hnsw, lexical, fanout", "searchable")).expect("accepted");
  assert!(model.engines[0].fanout);
  assert!(!model.engines[1].fanout);
}

/// PORTABILITY and FANOUT differ in one word and in nothing else the model carries — which is the
/// distinction ruling 3 draws, stated where it could be lost.
#[test]
fn portability_and_fanout_declare_the_same_slots() {
  let portable = fulltext(&document("searchable, hnsw, lexical", "searchable")).expect("accepted");
  let fanned =
    fulltext(&document("searchable, hnsw, lexical, fanout", "searchable")).expect("accepted");
  assert_eq!(slots(&portable), slots(&fanned));
  assert!(!portable.engines[0].fanout);
  assert!(fanned.engines[0].fanout);
}

/// **AN ELECTION NAMING NO ENGINE TAKES THE SOLE-DEFAULT LABEL — ITS OWN FIELD NAME.**
///
/// The portable case, and it is portable in the half that is a deployment's: the corpus EXISTS
/// (this is the declaration's fact), and WHERE it lives is what the deployment says. What the
/// election used to have was no slot at all, which meant the minimal `#[ingraph(searchable)]` form
/// grew storage only when somebody wrote a word — the label deciding a structural fact.
///
/// The FIELD's name and not the declaration's: two elections of one declaration are two corpora, so
/// a shared label would collapse them into one.
#[test]
fn an_election_naming_no_engine_takes_its_own_field_name() {
  let model = fulltext(&document("searchable", "searchable")).expect("accepted");
  assert_eq!(slots(&model), ["title::title", "body::body"]);
  assert_eq!(model.engines.len(), 2);
  // NOTHING POINTED, which is the other half of the law: the label is the declaration's and the
  // resource is the deployment's, resolved at launch by `ResourceCatalog::sole`.
  assert!(
    model
      .engines
      .iter()
      .flat_map(|declared| declared.engines.iter())
      .all(|engine| engine.resource.is_none()),
    "a synthesized leg pointed at something",
  );
}

#[test]
fn one_engine_cannot_be_fanned() {
  let refusal = refused(
    document("searchable, lexical, fanout", "searchable"),
    NodeKind::Fulltext,
  );
  assert!(
    refusal.contains("nothing to fan between"),
    "the refusal names what is missing: {refusal}"
  );
  assert!(
    refusal.contains("`lexical`"),
    "and the engine it did name: {refusal}"
  );
}

#[test]
fn no_engine_cannot_be_fanned_either() {
  let refusal = refused(
    document("searchable, fanout", "searchable"),
    NodeKind::Fulltext,
  );
  assert!(
    refusal.contains("declares NO engine"),
    "the refusal names the absence: {refusal}"
  );
}

/// The marker is BARE, for `searchable`'s reason: *all of them* has no knob inside it.
#[test]
fn fanout_takes_no_block() {
  let refusal = refused(
    document("searchable, hnsw, lexical, fanout(eager)", "searchable"),
    NodeKind::Fulltext,
  );
  assert!(
    refusal.contains("is a BARE marker"),
    "the refusal says which shape it takes: {refusal}"
  );
}

#[test]
fn an_engine_is_declared_once_per_field() {
  let refusal = refused(
    document("searchable, lexical, lexical", "searchable"),
    NodeKind::Fulltext,
  );
  assert!(
    refusal.contains("more than once on `title`"),
    "the ordinary duplicate family: {refusal}"
  );
  assert!(
    refusal.contains("TWO FIELDS sharing an engine"),
    "and it says what the legal repeat is: {refusal}"
  );
}

/// AN ENGINE ON PAYLOAD. There is no index for it to be the store of, and the refusal offers the
/// repair that is usually meant.
#[test]
fn an_engine_on_an_unelected_field_is_refused_by_name() {
  let refusal = refused(document("searchable", "lexical"), NodeKind::Fulltext);
  assert!(
    refusal.contains("is not elected"),
    "the refusal names the missing half: {refusal}"
  );
  assert!(
    refusal.contains("#[ingraph(searchable)]"),
    "and offers the marker: {refusal}"
  );
}

/// **A KIND WORD IS NOT WRITTEN AT AN ELECTION** — the retirement that pairs with `type =`'s, and
/// the one closed half this otherwise-open position has.
///
/// The word used to be a self-binding label whose only remaining question was whether the field's
/// KIND matched. Kind is said once now, at the resource, so the refusal is UNCONDITIONAL: it fires
/// on the word's own kind as readily as on the other one, and both arms are asserted here because
/// only the pair shows the guard was actually dropped rather than inverted.
#[test]
fn a_kind_word_is_not_written_at_an_election() {
  let on_its_own_kind = refused(
    document("searchable, tantivy", "searchable"),
    NodeKind::Fulltext,
  );
  let on_the_other = refused(
    syn::parse_quote! {
      #[ingraph(upstream(node = "asr::Segment", image = "coords"), dedup(hash))]
      pub struct Frames {
        #[ingraph(embedding, knn, tantivy)]
        image: Embedding<f32, 4>,
      }
    },
    NodeKind::Vector,
  );

  for refusal in [&on_its_own_kind, &on_the_other] {
    assert!(
      refusal.contains("kind is said ONCE, at the resource"),
      "the refusal says where the word went: {refusal}"
    );
    assert!(
      refusal.contains("#[ingraph::resource(tantivy)]"),
      "and shows the declaration that says it: {refusal}"
    );
    assert!(
      refusal.contains("resource = \"crate::Store\""),
      "and how this leg points at one: {refusal}"
    );
  }
}

/// A FREE word on the vector kind is accepted, which is the open vocabulary's whole point: `ingraph`
/// ships no vector engine at all, so every one of them is somebody else's.
#[test]
fn a_free_word_on_the_vector_kind_is_accepted() {
  let model = vector(&syn::parse_quote! {
    #[ingraph(upstream(node = "asr::Segment", image = "coords"), dedup(hash))]
    pub struct Frames {
      #[ingraph(embedding, knn, lance, hnsw(ef = 200))]
      image: Embedding<f32, 4>,
    }
  })
  .expect("accepted");
  assert_eq!(slots(&model), ["image::lance", "image::hnsw"]);
}

/// The TEACHING refusal: an author who wrote the record's wrapper had the record's shape in mind,
/// and the useful half of the sentence is why an index field takes none.
#[test]
fn the_persist_wrapper_on_an_index_field_is_refused_by_name() {
  let refusal = refused(
    document("searchable, persist(tantivy)", "searchable"),
    NodeKind::Fulltext,
  );
  assert!(
    refusal.contains("the ENGINE IS THE STORE"),
    "the refusal says why there is no wrapper: {refusal}"
  );
  assert!(
    refusal.contains("written BARE beside the marker"),
    "and shows the spelling that replaces it: {refusal}"
  );
}

/// A kind that elects NOTHING keeps the closed vocabulary whole — there is no open half to protect
/// on a declaration with no index for an engine to hold.
#[test]
fn an_artifact_family_takes_no_engine_word() {
  let refusal = refused(
    syn::parse_quote! {
      #[ingraph(upstream(node = "asr::Segment", body = "text"), dedup(hash))]
      pub struct Artifacts {
        #[ingraph(tantivy)]
        body: String,
      }
    },
    NodeKind::Blob,
  );
  assert!(
    refusal.contains("reads as an ENGINE"),
    "the refusal names what the word looks like: {refusal}"
  );
  assert!(
    refusal.contains("elects nothing"),
    "and why this kind has no use for one: {refusal}"
  );
}

#[test]
fn fanout_on_a_kind_that_elects_nothing_is_refused_by_name() {
  let refusal = refused(
    syn::parse_quote! {
      #[ingraph(upstream(node = "asr::Segment", body = "text"), dedup(hash))]
      pub struct Artifacts {
        #[ingraph(fanout)]
        body: String,
      }
    },
    NodeKind::Blob,
  );
  assert!(
    refusal.contains("declares none"),
    "the refusal names the absence: {refusal}"
  );
}

/// An engine is a WORD, so a path is not one — and the sentence says where a path does go, which is
/// the graph root's binding.
#[test]
fn an_engine_word_is_one_segment() {
  let refusal = refused(
    document("searchable, my::engine", "searchable"),
    NodeKind::Fulltext,
  );
  assert!(
    refusal.contains("an engine is named by ONE word"),
    "the refusal states the shape: {refusal}"
  );
}

/// `word = …` reads as an option of THIS grammar's, and it is not one: what goes inside an engine's
/// parentheses belongs to the engine.
#[test]
fn an_engine_is_a_block_and_not_a_value() {
  let refusal = refused(
    document("searchable, hnsw = \"app::Hnsw\"", "searchable"),
    NodeKind::Fulltext,
  );
  assert!(
    refusal.contains("declared as a BLOCK"),
    "the refusal states the shape: {refusal}"
  );
}

/// The head block is refused FOR GOOD now rather than as a wait, and the sentence says where the
/// engines went.
#[test]
fn the_head_storage_block_is_not_where_the_engines_are_named() {
  let refusal = refused(
    syn::parse_quote! {
      #[ingraph(upstream(node = "asr::Segment", body = "text"), fulltext(tantivy), dedup(hash))]
      pub struct SearchDocument {
        #[ingraph(searchable)]
        body: String,
      }
    },
    NodeKind::Fulltext,
  );
  assert!(
    refusal.contains("a slot is one FIELD in one engine"),
    "the refusal says why the head is the wrong grain: {refusal}"
  );
  assert!(
    !refusal.contains("has not arrived"),
    "and it is no longer a wait: {refusal}"
  );
}