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
//! **LAYER TWO** — the initialization walk: after the resources are built and their stores opened,
//! every declaration's HOME in every target it points at is MADE, and only then does the graph
//! serve.
//!
//! ```text
//! layer one AsyncResource::build ─► Store::open the mounts exist
//! │
//! layer two per declaration × per target it points at:
//! │ Initialize::initializer(mount) ─► the AUTHOR'S factory visitor
//! │ visitor.next_type::<Declaration>() ─► its blueprint, made
//! ▼
//! the barrier every walk finished ─► nodes built ─► wired ─► ignited ─► SERVING
//! ```
//!
//! # THE COMPLETENESS LAW
//!
//! One node's fields may need initializing on BOTH sides at once — a `title` elected into a
//! synchronous tantivy mount, an `embedding` into a remote vector store that answers with a future,
//! a `persist` into a SQL database. So the walk is driven per (declaration × target), each target on
//! ITS OWN FACE, and the union of those steps is what covers a mixed node completely. No step is
//! skipped for being on the other side, and the whole set finishes before anything is wired — a
//! launch that served first would have a request reach a corpus that does not exist yet.
//!
//! A refusal anywhere in it is a REFUSED LAUNCH ([`LaunchError::Initializing`]), raised inside the
//! create walk's own fallible phase so that everything already built says its goodbyes on the way
//! out — the pre-ignition unwind, unchanged.
//!
//! # MOUNTED IS VISITED, and it is UNCONDITIONAL
//!
//! A target a declaration POINTS AT is a target this deployment mounts, and every mount is built at
//! launch and shown its declarations — a write mount and a read-only one alike. The distinction the
//! walk used to draw between them is retired, because it was never a distinction the deployment
//! could keep: what makes a mount a WRITE mount is a node that lands into it, and what makes one a
//! WIRE mount is a resolver holding a [`Shared<R>`](crate::Shared) that the graph cannot see at all.
//! A search door is exactly as much of a holder as a landing node is, so a launch that built only
//! what the graph could see left the read path opening a corpus that was never made.
//!
//! [`Habitats::TARGETS`] is how the fact travels: a declaration names its targets in a `const`, an
//! emitted launch states them on the [`Plan`](super::Plan) before the validate walk, and they join
//! the enabled nodes' own demands in the one set the create walk builds from. Which leaves exactly
//! ONE laziness, and it is the honest one — a resource NOTHING points at and NO enabled node
//! demands is neither built nor walked, so a catalog's unused models stay unloaded.
//!
//! The read-only half of that is not a formality, and [`Initialize`] says what an honest body for it
//! does: open the table, keep the handle, verify the schema is the one this deployment was compiled
//! against.
//!
//! # WHO knows what, and why the steps are per DECLARATION rather than per resource
//!
//! Which targets a declaration's legs point at is written in the DECLARATION — `lexical(resource =
//! "crate::Ft")` — and a graph root cannot see it: the root holds a list of member types and a list
//! of resource types, and the PAIRING between them is a fact of neither list. A root-side loop over
//! `resources × members` would therefore demand that every mounted target be a habitat for every
//! member, which is false of every mixed deployment there is — a full-text mount is no home for a
//! vector declaration.
//!
//! So the step is emitted where the pairing is known, on the declaration, through [`Habitats`]; and
//! the ROOT drives one call per fused member. **One visitor per target even so** — the walk's own
//! shape — because [`Creation`](super::Creation) keeps the visitors it builds and hands each
//! declaration the one that target already had. A slot maker therefore sees every declaration that
//! lives in its mount, in member order, exactly as a walk over one list would have shown it.
//!
//! # And the corpora that named NO target
//!
//! [`Habitats::UNBOUND`] is the other half of the same list: a leg that wrote no `resource = "…"`
//! has no type for a step to name, and what binds it is the deployment's own catalog — exactly one
//! kind-compatible resource declared and the leg takes it, zero or several and the launch refuses
//! listing the candidates. The root reads this const off each member and states it on the
//! [`Plan`](super::Plan) before the validate walk, which is what makes the sole-default law
//! reachable from an emitted launch rather than only from a hand-wired one.
use ;
use Utf8Bytes;
use ;
use crate::;
/// ONE CORPUS a declaration owns whose leg named NO resource — the row a launch resolves by the
/// SOLE-DEFAULT law.
///
/// [`SlotBinding`](super::SlotBinding)'s `const`-constructible twin. The launch floor's own type
/// holds an owned name because the walk builds one per plan; this one is written INSIDE a
/// declaration's expansion, where every part is `&'static` and the whole list is an item — so a
/// declaration states its unbound corpora once, at compile time, and nothing is assembled per boot.
/// **LAYER TWO, on the DECLARATION** — every home this declaration owns, in every target its legs
/// point at, and every corpus of its whose leg pointed at nothing.
///
/// # Who implements it
///
/// `#[ingraph::fulltext(…)]`, `#[ingraph::vector(…)]` and their siblings, from the `resource = "…"`
/// paths their elections wrote. A declaration whose legs all point at nothing implements it with an
/// empty [`make`](Self::make), an empty [`TARGETS`](Self::TARGETS) and a full
/// [`UNBOUND`](Self::UNBOUND); a declaration with no elections at all takes all three defaults and
/// is a no-op on every half.
///
/// # Every member DEFAULTS, and that is what keeps a hand-written declaration whole
///
/// The trait is read by a graph root's emitted launch, once per fused member. A member that has
/// nothing to say about any of the three says nothing, exactly as
/// [`DeclaredResource`](crate::DeclaredResource)'s two seats default — and for the same reason: a
/// seat that must be filled makes every declaration written before it a breaking change.
/// **LAYER TWO's BLOCKING FACE, on the RESOURCE** — the factory visitor this mount's homes are made
/// by.
///
/// # It is the AUTHOR'S MACHINE
///
/// A slot maker holds its own connection and its own per-slot values, so the framework builds
/// nothing here: it asks the resource for one and shows it types. `#[ingraph::resource(<word>)]`
/// names the shipped machine for a builtin engine — [`TantivySlotMaker`](crate::TantivySlotMaker) —
/// and a foreign resource's author names theirs, which is the same open seam the mount faces are on.
///
/// # The DB is the RESOURCE and not the engine
///
/// [`Visitor`](Self::Visitor) is pinned to `TypeVisitor<Db = Self>`, so a maker built for one mount
/// is shown only the declarations that describe themselves in THAT mount. Two deployments' tantivy
/// stores are two resource types and therefore two habitats, which is what keeps a second mount
/// addressable at all.
///
/// # THE THREE HONEST BODIES
///
/// Every mounted target implements this, and the walk shows every one of them its declarations —
/// there is no word, no marker and no seat that opts a resource out. What differs between targets is
/// what the machine DOES when it is shown one, and in practice it is one of three things:
///
/// | body | the target it is honest for |
/// |---|---|
/// | **noop** — [`MakesNothing`] | the store creates its own homes on first use: an index directory that appears at the first write, a collection a driver opens on demand, a bucket the object store mints when something lands in it |
/// | **open-or-create** | the walk makes what is not there and reopens what is — the shipped [`TantivySlotMaker`](crate::TantivySlotMaker), whose `Index::open_or_create` is idempotent by construction |
/// | **read-side open and verify** | a mount this deployment only READS: open the table, keep the handle warm, and check that the schema in front of it is the one these declarations were compiled against |
///
/// The third row is the one a read-only deployment is owed. *Nothing is written here* is not the same
/// sentence as *nothing is to be done here*: a replica still has a table to open, a handle to keep
/// and a schema that can have drifted, and the launch is the only moment at which finding that out is
/// still cheap. A target whose credentials are read-only is the author's own branch inside the body —
/// open where the deployment reads, create where it writes — and not a question the framework asks.
///
/// # Forgetting it is `E0277`, which is harder teeth than a marker
///
/// The seat is mandatory: a resource a declaration points at and that implements neither this nor
/// [`AsyncInitialize`] does not compile, at the launch, naming the trait it lacks. A marker meaning
/// *this one needs nothing* would have had the opposite property — silence would be the default and a
/// forgotten one would be indistinguishable from a deliberate one — so the noop is a BODY that
/// somebody wrote, and the compiler is what makes sure somebody did.
/// **LAYER TWO's AWAITED FACE** — [`Initialize`]'s twin, for a mount whose creates answer with a
/// future.
///
/// The dual-mode law at this grain: a resource implements one of the two, or BOTH where its machine
/// genuinely has two faces, and nothing bridges them by blanket. Which one a launch drives is the
/// resource's own `#[ingraph::resource(async)]` word, read back through
/// [`DeclaredResource::SYNC`](crate::DeclaredResource::SYNC) at the emission that spells the call.
/// **THE NOOP BODY** — the machine a target names when it has nothing to make.
///
/// # It is a BODY and not a marker
///
/// Naming it does not take this mount out of the walk. Layer two visits every mounted target
/// unconditionally, and a mount whose machine is this one is shown every declaration that lives in
/// it exactly as any other is — it simply answers each of them by doing nothing. There is no seat
/// anywhere that means *skip me*, and this is not one wearing a different hat.
///
/// # What it is honest for
///
/// A store that creates its own homes on first use: an index directory that appears at the first
/// write, a collection a driver opens on demand, a bucket the object store mints when something
/// lands in it. For such a target *nothing to make ahead of time* is a real answer rather than a
/// gap, and this is that answer in one line instead of a hand-written visitor whose body is `Ok(())`.
///
/// It is the FIRST of [`Initialize`]'s three honest bodies and the one to reach for LAST: a mount
/// this deployment only reads still has a table to open and a schema to check, and a noop there is
/// silence rather than honesty. What the order of layer two buys even here is the moment: the walk
/// runs before the first construction, so a target that later grows an eager step gains it without
/// any caller changing shape.
///
/// # It wears BOTH faces, and that is not the blanket the pair refuses
///
/// One type, two impls, the SAME `Db` — so a resource of either mode names it and neither face is
/// invented for the other. The blanket the visitor pair refuses is over every `V`, which would
/// collide with a machine that wears the two faces for two DIFFERENT targets; a concrete type
/// stating both is exactly what that freedom is for.
///
/// # Examples
///
/// ```
/// use ingraph::{Resources, Habitat, Initialize, MakesNothing, Shared, SlotSpec};
/// # use ingraph::AsyncResource;
///
/// pub struct Qdrant;
/// # impl AsyncResource for Qdrant {
/// # type Options = ();
/// # type Error = core::convert::Infallible;
/// # async fn build(_ctx: &Resources, _: ()) -> Result<Self, Self::Error> { Ok(Self) }
/// # }
///
/// impl Habitat for Qdrant {
/// type Blueprint = &'static [SlotSpec];
/// }
///
/// impl Initialize for Qdrant {
/// type Visitor = MakesNothing<Self>;
///
/// fn initializer(_mount: Shared<Self>) -> Self::Visitor {
/// MakesNothing::new()
/// }
/// }
/// ```
/// **THE MODE-DISPATCHED DRIVER** — what an emitted launch names once per (declaration × target),
/// whichever face that target wears.
///
/// # `M` is the resource's MODE, as a type
///
/// `Selected<{ <R as DeclaredResource>::SYNC }>` — [`Block`] or [`Async`], the same crossing every
/// other mode-selecting emission in this crate makes. The call is spelled at a CONCRETE resource, so
/// the const is nameable there; nothing generic ever has to evaluate it.
///
/// # Two impls, and a resource may take both
///
/// One per mode, so they cannot overlap, and each closes over the face its mode names. A resource
/// implementing [`Initialize`] AND [`AsyncInitialize`] gets both rows and stays addressable on
/// either — the two-face freedom, at the resource's grain.
///
/// # Nothing implements this by hand
///
/// It is the framework's bridge between the two author faces and one call shape. What an author
/// writes is [`Initialize`] or [`AsyncInitialize`], one associated type and one line.