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
//! WHERE an elected field is written: the engine blocks a declaration wears, and the SLOT each one
//! names.
//!
//! ```text
//! #[ingraph(knn, lance, hnsw(ef = 200), fanout)]
//! pub image: Embedding<f32, 768>,
//! ```
//!
//! One field, one election, and beside it the engines that hold it. The words are BARE and they
//! carry their own options, because on an index field the ENGINE IS THE STORE — there is no second
//! axis for a `persist(…)` wrapper to namespace against, which is the whole of why the record's
//! shape is not repeated here.
//!
//! # The semantics are the RECORD's, measured and mirrored rather than reinvented
//!
//! Several blocks are declared PORTABILITY, and the default is SINGLE-WRITE. That is not a new rule:
//! it is what `persist(sqlite, postgres)` already means, and the record side answers *which one is
//! live* in two layers that this module mirrors exactly —
//!
//! | layer | the record side | here |
//! |---|---|---|
//! | COMPILE — declared ∩ compiled-in | `__private::gate::if_<db>!` around every impl naming a concrete backend | [`EngineKind::gate`], around every impl naming a concrete engine |
//! | CALL — which store this call writes | the METHOD NAME (`insert_postgres`), the driver staying a type parameter | the SLOT (`field × engine`), the engine staying a type parameter |
//!
//! The record side's own words for the second layer: *an expansion may not spell `sqlx::Sqlite`, so
//! the method NAME is where the database is chosen and the type parameter is where the driver is.*
//! Read back here, the SLOT is where the engine is chosen and the type parameter is where the engine
//! handle is — which is the shape a derived index's emitted retrieve already had before this round,
//! carrying `__INGRAPH_ENGINE__` as a method parameter.
//!
//! So *declare many, build one, and write through whichever door the deployment opened* is
//! inherited whole. [`fanout`](FieldEngines::fanout) is the ONE departure, and it is a marker
//! precisely because it departs.
//!
//! # The vocabulary is OPEN, and [`EngineKind`] is not the vocabulary
//!
//! [`DatabaseKind`](crate::model::DatabaseKind) is CLOSED — *a database the framework does not ship
//! an emitter for has nothing to be opened* — and the engine axis is the opposite case, which is why
//! the two tables look alike and mean different things. A database needs an emitter here; an engine
//! needs only an implementation of a trait `ingraph` already publishes, and third parties are
//! expected to bring them. [`EngineKind`] is therefore the SHIPPED table — the words that self-bind
//! under their own feature — and a word outside it is an ordinary declared word whose binding is the
//! graph root's `engines(…)`.
use format_ident;
use crateNodeKind;
/// An engine `ingraph` itself ships — the words that SELF-BIND under a feature of the framework's
/// own.
///
/// # Why a table at all, when the vocabulary is open
///
/// Three facts are true of a shipped word and of no other, and each of them is a refusal or an
/// emission that has to know:
///
/// 1. it names a CONCRETE type this crate can spell, so the impls naming one ride
/// [`gate`](Self::gate) — the record side's law, applied to the engine axis;
/// 2. it is a KIND, and kind is said ONCE — at the resource. So the word at an ELECTION is a named
/// refusal whichever kind it serves, and [`serves`](Self::serves) is what lets that sentence say
/// what the word actually holds. (It was a kind-GUARDED refusal while the word self-bound at the
/// election; the resource axis dropped the guard and kept the reading.)
/// 3. it is ALREADY BOUND, so `engines(tantivy = "…")` at a graph root is a refusal — rebinding a
/// shipped word would give one word two meanings in one program.
///
/// A word outside this table is none of those things and is refused for none of them.
///
/// # It has TWO members, and that is a measurement rather than a stub
///
/// `ingraph` ships exactly two engine implementations: `TantivyFulltext` under `feature = "tantivy"`,
/// and the local-filesystem blob store under NO feature at all. There is no `VectorEngine`
/// implementation in this workspace — *lance* appears in this repository only in prose and in the
/// unbuilt `legacy/` reference — so the vector side of the grammar is served entirely by the open
/// half, which is the strongest argument the open half has.
/// THE FROM-ROAD one engine block declares: how the elected field's value becomes THIS engine's
/// document text.
///
/// # `from` and no `into`, and the direction law is why
///
/// *`from` BUILDS the projection a block is about* — here, the document. There is no `into` leg and
/// there is not going to be one: a document is written and searched, never hydrated back into the
/// domain. What a hit hands back is an ADDRESS, and that pair does round-trip, which is the axis
/// this one deliberately lacks.
///
/// # The shorthands are a SEAM, not a closed pair
///
/// `join` and `multi` are the two the framework ships because they are the two loops a converter is
/// otherwise written out as, and they differ in the one thing the declaration is about: whether a
/// phrase may match ACROSS two values. A third builtin arrives as a variant here and an arm in the
/// walk — no grammar change, because the position it is written in already exists.
///
/// # Per ENGINE BLOCK, and it could not be per field
///
/// The segmentation means different things to different engines: a positional one puts a gap
/// between segments, and a single-text-column face has to flatten them — so one converter indexes
/// correctly in the first and subtly wrongly in the second, both "working" and only the results
/// differing. A field-level, engine-agnostic road is therefore not expressible, which is what puts
/// this member on the block rather than beside the election.
/// ONE engine block as a field declared it — the word, and whatever it carried.
/// ONE LANE, as a `lanes(…)` block wrote it — the framework's half of one entry.
///
/// The engine's half of the same entry is NOT here: it is carried verbatim into
/// [`Engine::options`], because a lane's analyzer is a word only the backend reads.
/// ONE `engines(<word> = "path::To::Engine")` entry on a graph root — a WORD bound to a CONCRETE
/// TYPE.
///
/// # Why the binding is at the ROOT and not on the declaration
///
/// A word on a field is a NAME, and a name is bound where the program is assembled. Writing the path
/// on the declaration would bind it there — in a library crate that cannot know which engine the
/// application compiled, and cannot be re-pointed without editing the declaration. The root is the
/// one place that knows: it is the deployment's whole catalog already, and the same list the
/// resources are read off.
///
/// It is REFER-QUOTED for this grammar's standing reason: a word that points at something written
/// elsewhere is written in a string literal, so the path resolves at the span its author wrote.
///
/// # What it emits: the compile-time MEMBER TABLE
///
/// One marker type per bound word, carrying the concrete engine as an associated type. That table is
/// what a fused face reads to know which engines a query fans across, and it is a TYPE-level table
/// rather than a runtime map for the reason every other binding here is: a member resolved by name
/// at run time is a member no signature can be written against.
/// ONE elected field's engines, and whether all of them are live at once.
/// ONE SLOT: a field and the engine that holds it.
///
/// # Slot identity moved, and this type is the move
///
/// It used to be the DECLARATION — one `FulltextTable::SLOT` per index, and *one declaration, one
/// slot* was the keystone the brand rested on. Under the engine grammar it is `(field × engine)`,
/// and the per-slot laws follow it there: ONE Tantivy index per slot, because BM25's corpus
/// statistics are index-wide, is now one index per `(field, engine)` — which is what makes two
/// fields of one declaration searchable independently without their scores moving under each other.
///
/// The COLUMN axis is unchanged and is one grain finer: a vector slot may still hold several
/// columns, and `VectorColumn` still says which one a knn runs over. What this type adds is the axis
/// above it, not a replacement for the one below.