bstack_raii 0.1.0

Typed, RAII-style ownership and lifetime layer over the bstack allocation primitives
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
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
# bstack_raii

Typed, RAII-style ownership for persistent objects — `Rc`/`Weak` semantics that
survive a process restart or crash, backed by [`bstack`] files.

`std::rc::Rc` and `Weak` live and die with the process. `bstack_raii` gives you
the same model, but the object graph *and its reference counts* live on disk,
crash-safely. You define blocks as ordinary structs and enums; the
[`#[bstack_block]`](#structs) / [`#[bstack_enum]`](#enums-bstack_enum) macros
generate the on-disk layout, typed accessors, constructors, recursive teardown,
and refcounting.

On top of that core it grows a full object layer:

- **Five ownership kinds** — [`#[bstack_owned]`, `#[embed]`, `#[bstack_strong]`,
  `#[bstack_weak]`, `#[bstack_ref]`](#field-ownership) — each with matching
  deep-clone ([`TryCloneIn`]#cloning-tryclonein--tryclone), recursive teardown,
  and [`bstack_move!`]#moving-out-bstack_move semantics.
- **Rich field shapes** — growable [`Vec` / `String`]#vectors-and-strings,
  fixed-size [`[T; N]` arrays]#fixed-size-arrays-t-n, nullable
  [`Option`]#nullable-fields-option, POD tuples, and
  [generic blocks]#generic-blocks, composed to depth.
- **[Cross-file pointers]#cross-file-pointers-foreignt (`Foreign<T>`)** — a wide
  pointer naming a target file *and* an offset in it, so an object graph can span
  many `bstack` files, resolved through a process-wide file registry.
- **Crash-safe compound ops** — clone and teardown commit as one atomic batch and,
  on a WAL-anchoring allocator, reclaim crash-orphaned allocations on the next open.
- **[Standard-library collections]#standard-library-collections** — persistent
  `HashMap`, `BTreeMap`, `VecDeque`, `LinkedList`, `String`, and more.
- **A self-describing on-disk schema (RTTI)** — an optional type-registry stack
  (see [BYTECODE.md]BYTECODE.md) letting a general program interpret bstack_raii
  structures on disk with no compiled-in Rust types.

It layers on the mainline `bstack` allocator (`BStackRange` / `BStackSlice` /
`BStackOwnedSlice`), which supplies the atomicity, crash-safety, and
single-ownership primitives underneath.

> **Status:** feature-complete and tested, but the on-disk ABI is not yet
> stable (pre-1.0).

## Contents

- [Quick start]#quick-start
- [Concepts]#concepts
- [How it works on disk]#how-it-works-on-disk
- [Handles & lifetimes]#handles--lifetimes
  - [Type naming]#type-naming
- [Generated types]#generated-types
- [Blocks]#blocks
  - [Field ownership]#field-ownership
  - [Structs]#structs
  - [Reference-counted blocks]#reference-counted-blocks
  - [Vectors and strings]#vectors-and-strings
  - [Fixed-size arrays: `[T; N]`]#fixed-size-arrays-t-n
  - [Nullable fields: `Option`]#nullable-fields-option
  - [Enums: `#[bstack_enum]`]#enums-bstack_enum
  - [Field types]#field-types
  - [Generic blocks]#generic-blocks
- [Mutating fields: `#[bstack_mut]`]#mutating-fields-bstack_mut
- [Moving out: `bstack_move!`]#moving-out-bstack_move
- [Cloning: `TryCloneIn` / `TryClone`]#cloning-tryclonein--tryclone
- [Casting: `bstack_cast!`]#casting-bstack_cast
- [Cross-file pointers: `Foreign<T>`]#cross-file-pointers-foreignt
- [Type tags (`EightCC`)]#type-tags-eightcc
- [Standard library collections]#standard-library-collections
- [Examples]#examples
- [Limitations]#limitations
- [Error codes]#error-codes

## Quick start

Add both crates (`bstack` supplies the allocator; `bstack_raii` the object
layer):

```toml
[dependencies]
bstack_raii = "0.1"
bstack = "0.4"
```

```rust
use std::io;
use bstack::FirstFitBStackAllocator;
use bstack_raii::{BStack, BStackAllocator, BStackDrop, TryClone, bstack_block};

// A shared, reference-counted, weak-observable block.
#[bstack_block(rc, weak)]
struct Config {
    version: u64,
    flags: u64,
}

// A block that owns a *strong* reference to a shared Config.
#[bstack_block]
struct Session {
    id: u64,
    #[bstack_strong]
    config: Config,
}

fn main() -> io::Result<()> {
    let alloc = FirstFitBStackAllocator::new(BStack::open("app.bstack")?)?;
    let stack = alloc.stack();

    let config = Config::new(&alloc, 3, 0b1010)?;      // BStackRc<Config>, strong = 1
    let session = Session::new(&alloc, 0, config.try_clone()?)?; // strong = 2

    // Read fields through generated accessors.
    let cfg = session.handle().get_config(stack)?;      // -> a Config handle
    println!("v{} flags {:#b}", cfg.get_version(stack)?, cfg.get_flags(stack)?);

    drop(config);                  // strong = 1 — the session still owns it (Rc: auto-decrement)
    session.bstack_drop(&alloc)?;  // strong = 0 — Config freed automatically by its refcount
    Ok(())
}
```

Two things are load-bearing here, both covered below:

- **Owned vs. shared teardown.** A uniquely-owned `Session` handle frees
  **nothing on `Drop`** — free it explicitly with `bstack_drop`, so a persistent
  root is never silently deleted. A shared `Config` (`BStackRc`) *does*
  auto-manage its refcount on `Drop`. See [Handles & lifetimes]#handles--lifetimes.
- Every block also gets a stable 8-byte on-disk type tag — see
  [Type tags]#type-tags-eightcc.

A fuller walk-through is in [`examples/sessions.rs`](examples/sessions.rs):
`cargo run --example sessions`.

## Concepts

A **block** is a fixed-size record on disk. You write it as an ordinary `struct`
(or [`enum`](#enums-bstack_enum)) and annotate it; the macro generates a parallel
`#[repr(C, packed)]` on-disk layout and its machinery.

Both macros take the same three **modes**:

| Mode         | Meaning                                                  |
|--------------|----------------------------------------------------------|
| *(none)*     | Plain, exclusively owned (like `Box`).                   |
| `(rc)`       | Reference-counted, inline count (like `Rc`, no `Weak`).  |
| `(rc, weak)` | Refcounted **and** weak-observable (like `Rc` + `Weak`). |

Every non-POD field carries an [ownership annotation](#field-ownership) deciding
how it is torn down. `Pod` fields are stored inline and copied by value.

> **The allocator bound: [`BStackRaiiAllocator`].** Every operation is generic over
> [`BStackRaiiAllocator`], an `unsafe` trait over a freeing `bstack` allocator that
> asserts the **null niche**: offset 0 is never handed out, so a `0` offset reads as
> "none" everywhere. It also exposes an *optional* WAL anchor that lets teardown and
> clone reclaim crash-orphaned allocations on the next open.
>
> **Every bstack-provided allocator implements it** — `FirstFitBStackAllocator`,
> `SlabBStackAllocator`, `GhostTreeBstackAllocator`, … — and a custom one opts in
> with `unsafe impl BStackRaiiAllocator for MyAlloc {}`. **Not `LinearBStackAllocator`**:
> its `dealloc` is a no-op and it can hand out offset 0. For growable fields use a
> **realloc-safe** allocator; `FirstFitBStackAllocator` is one.
>
> **The WAL anchor in practice.** Call [`wal::finish`]`(&allocator)` once after `open`
> to complete any transaction a prior crash left in flight; `try_clone_in` and
> `bstack_drop` also call it opportunistically. [`STD_WAL_ANCHOR`] is the offset
> every bstack-provided allocator reserves.

## How it works on disk

Every block begins with a 16-byte `BlockHeader { size: u64, tag: EightCC }` (the
[tag](#type-tags-eightcc) is the downcast discriminant). References are bare `u64`
offsets; a target's length is recovered from `size_of::<T::OnDisk>()`, so blocks
are **fixed-size**.

The three modes differ only in what is injected after the header:

- **`#[bstack_block]`** — nothing; the payload follows the header directly.
- **`(rc)`** — an inline `refcount: u64`. The block is freed when it hits zero.
- **`(rc, weak)`** — a `ctrl` back-pointer to a separate **control block**
  (`XOnDiskRef`) holding `strong` / `weak` counters and a forward pointer to the
  data. The data block is reclaimed when `strong` hits zero; the control block
  persists until `weak` also hits zero, so a `Weak` can outlive the data — like
  `Arc` / `Weak`.

**Growable fields** (`Vec` / `String`) don't fit a fixed-size block, so they live
out of line: the field holds a 16-byte descriptor `{ data_off, data_size }`
*inline*, pointing at a separate data block that reallocates as it grows (see
[Vectors and strings](#vectors-and-strings)).

Refcount updates are single-lock read-modify-writes on `bstack` (crash-atomic).
Everything is durable and speaks [`std::io::Result`].

## Handles & lifetimes

The typed handle `X` is a bare `Copy` `(offset, len)` with no allocator; you read
fields through it. Ownership wrappers layer on top:

| Handle               | Allocator | Ownership                        | Teardown                                                             |
|----------------------|-----------|----------------------------------|----------------------------------------------------------------------|
| `X` (the block type) | no        | none (borrowed view / bare ref)  | `x.bstack_drop(alloc)?` — explicit only                              |
| `BStackOwned<X>`     | no        | exclusive (ownership marker)     | `owned.bstack_drop(alloc)?` — **nothing on `Drop`**                  |
| `AutoDrop<T>`        | yes       | RAII guard over any `BStackDrop` | runs `bstack_drop` on Rust `Drop`                                    |
| `BStackRc<X>`        | yes       | shared strong                    | `try_clone` / `downgrade`; **auto-decrements on `Drop`**, frees at 0 |
| `BStackWeak<X>`      | yes       | none (keeps control block alive) | `try_clone` / `upgrade`; auto-decrements weak on `Drop`              |
| `BStackRef<X>`       | no        | none (raw offset)                | none                                                                 |

**Owned is manual; shared is automatic.** A `BStackOwned<X>` carries no allocator
and frees **nothing** when it drops. Free it explicitly, or wrap it in an
`AutoDrop` guard for RAII:

```rust
let owned: BStackOwned<Node> = Node::new(&alloc, /* … */)?;
let value = owned.handle().get_tag(stack)?;   // read a field (or `owned.get_tag(stack)?` via Deref)

owned.bstack_drop(&alloc)?;               // free it now, explicitly …
// … or: let _guard = owned.auto(&alloc); // RAII — freed when `_guard` drops
```

Shared handles (`BStackRc` / `BStackWeak`) manage their counts on `Drop`, like
`std::rc`. Duplicating one bumps an on-disk counter, so cloning is the [`TryClone`]
trait, not `Clone`. `BStackRc` derefs to `X`; a `BStackWeak` doesn't — `upgrade` it
to a `BStackRc` first.

### Type naming

The **`BStack`** prefix marks the primary tier: the handles (`BStackOwned`,
`BStackRc`, `BStackWeak`, `BStackRef`), the capability traits (`BStackBlock`,
`BStackDrop`, `BStackShared`, …), and the [collections](#standard-library-collections)
(`BStackHashMap`, `BStackString`, …). Everything else drops the prefix:

- **Low-level ref / drop-core tokens** — `OwnedRef`, `StrongRef`, `WeakRef`,
  `VecRef`, `AnyRef` (`BStackRef` keeps the prefix — it's the typed pointer, not a
  token).
- **Module-namespaced subsystems** — RTTI (`RttiType`, `Shape`, `Value`, …) and
  cross-file pointers (`Foreign`, `ForeignOwned`, …).
- **On-disk primitives** — `EightCC`, `Offset`, `WidePtr`, `FileId`.

## Generated types

Each macro generates a small, fixed set of types (for a block named `X` / `E`):

| Source                               | Types generated                                                                                                                                                |
|--------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `#[bstack_block] struct X`           | `X` — the [handle]#handles--lifetimes; `XOnDisk` — the `#[repr(C, packed)]` on-disk payload                                                                  |
| `#[bstack_block(rc, weak)] struct X` | the above, plus `XOnDiskRef` — the [control block]#how-it-works-on-disk (`strong`/`weak` counters)                                                           |
| `#[bstack_enum] enum E`              | `E`, `EOnDisk` (plus `EOnDiskRef` for `(rc, weak)`), and two companion enums — see [Enums]#enums-bstack_enum: `EData` (owned form) and `EView` (read result) |

Alongside the types come the trait impls (`BStackBlock`, `BStackDrop`,
`BStackCast`, `BStackMove`, and for rc modes `BStackShared` / `BStackWeakable`)
and inherent methods (`new`, field accessors, `set_<field>`, enum `read`, …). You
name only the handle (`X` / `E`) and `EData` / `EView` for enums.

## Blocks

A block is a `struct` or `enum` annotated with `#[bstack_block]` /
`#[bstack_enum]`. This section covers how fields and variants are declared.

### Field ownership

Every non-POD field carries exactly one annotation, which decides its teardown
and what [`bstack_move!`](#moving-out-bstack_move) yields:

| Annotation         | Child kind required    | On teardown                         | `bstack_move!` yields       |
|--------------------|------------------------|-------------------------------------|-----------------------------|
| `#[bstack_owned]`  | any block              | recursively frees the child         | `BStackOwned<T>`            |
| `#[embed]`         | any block              | frees the child's children in place | `BStackOwned<T>` (re-homed) |
| `#[bstack_strong]` | `(rc)` or `(rc, weak)` | decrements refcount; frees at zero  | `BStackRc<T>`               |
| `#[bstack_weak]`   | `(rc, weak)`           | decrements weak count only          | `Option<BStackWeak<T>>`     |
| `#[bstack_ref]`    | any block              | nothing                             | `BStackRef<T>`              |
| *(none)* — POD     | `Pod` type             | nothing (inline)                    | the value                   |

Rules are enforced at compile time. A `#[bstack_weak]` field whose target isn't
`(rc, weak)` or an unannotated non-`Pod` field is a compile error.

#### `#[embed]` — inline a child block

`#[bstack_owned]` stores a `u64` **offset** to a separately-allocated child.
`#[embed]` instead stores the child's *whole on-disk form* **inline** in the
parent, so it needs no separate allocation:

```text
#[bstack_owned]:  [ parent header ][ .. u64 offset .. ] ─▶ [ child header ][ child fields ]
#[embed]:         [ parent header ][ child header ][ child fields ][ .. ]
```

```rust
#[bstack_block]
struct Holder {
    #[embed] child: Child,   // Child's OnDisk lives here, inline
    tag: u32,
}
enum Wrapper {
    #[embed] One(Child),     // also works as an enum variant
    None,
}
```

It's still **exclusive ownership**: `new` takes a `BStackOwned<Child>`, folds its
bytes in, and frees the child's redundant shell (its own children stay live). The
accessor hands back a borrowed `Child` handle; teardown frees the embedded child's
children in place; `bstack_move!` re-homes the child to a fresh `BStackOwned<Child>`.
You can embed any block, but not a tuple, `Vec`, or `Option`.

### Structs

```rust
#[bstack_block]
struct Node {
    #[bstack_owned]  payload: Payload,    // exclusively owns the child
    #[bstack_strong] shared:  SharedThing,// a shared, refcounted reference
    #[bstack_weak]   parent:  Node,       // a non-owning back-pointer (may dangle)
    #[bstack_ref]    sibling: Node,       // a raw reference, no ownership
    tag: u32,                             // POD, stored inline
}
```

Besides the [generated types](#generated-types), the macro emits inherent
methods:

- a `new(...)` **constructor**, consuming the child handles (`#[bstack_owned]` →
  `BStackOwned<T>`, `#[bstack_strong]` → `BStackRc<T>`, `#[bstack_ref]` →
  `BStackRef<T>`, POD by value; `#[bstack_weak]` fields are **not** parameters);
- **accessors** — `node.get_field(stack)` reads each field;
- **mutators** — writing a field is opt-in per
  [`#[bstack_mut]`]#mutating-fields-bstack_mut (`set_<field>` / `replace_<field>`),
  plus a `set_<field>` for wiring each `#[bstack_weak]`
  [back-pointer]#reference-counted-blocks;
- recursive teardown, [casting]#casting-bstack_cast, and
  [moving]#moving-out-bstack_move.

A **tuple struct** works if every field is `Pod`: positional fields get synthetic
names, so `struct Rgb(u8, u8, u8)` is built `Rgb::new(&alloc, 10, 20, 30)`, read via
`rgb.get_field0(stack)?` / …, and `bstack_move!` returns the fields in order. A
**unit struct** (`#[bstack_block] struct Marker;`) is a non-empty **header-only** block.

### Reference-counted blocks

Declare `#[bstack_block(rc)]` / `#[bstack_block(rc, weak)]`. `new` returns a
`BStackRc<X>`; clone it with `try_clone`, and for `(rc, weak)` get a non-owning
observer with `downgrade` / `upgrade`:

```rust
let a = Config::new(&alloc, 1, 0)?;   // BStackRc<Config>, strong = 1
let b = a.try_clone()?;               // strong = 2
let w = a.downgrade()?;               // BStackWeak<Config>
drop(a); drop(b);                     // strong = 0 — the data is freed
assert!(w.upgrade()?.is_none());      // the object is gone
```

**Weak fields** starts null and are wired afterward with
`set_<field>(&alloc, target.downgrade()?)`; the accessor `get_<field>(&alloc)`
*upgrades* to `Option<BStackRc<T>>`. The field stores the target's *control-block*
offset, so dropping the strong owner first and the holder second is sound.

### Vectors and strings

A `Vec<T>` (POD `T`) or `String` field stores a growable sequence, backed by the
inline descriptor from [How it works on disk](#how-it-works-on-disk).

```rust
#[bstack_block]
struct Record {
    name: String,
    tags: Vec<u32>,      // POD vectors are un-annotated (any Pod element type)
    id: u64,
}

let rec = Record::new(&alloc, "hello", &[1u32, 2, 3], 42)?;  // &str / &[T] / value
let mut tags = rec.handle().get_tags(&alloc)?;    // a BStackVec<u32> handle
tags.push(4)?;                                    // grows; rewrites the inline descriptor
assert_eq!(rec.handle().get_tags(&alloc)?.to_vec()?, vec![1, 2, 3, 4]);
```

The accessor returns a [`BStackVec<T>`] (`len` / `to_vec` / `push`); freeing the
block frees the data. A *detached* vector (from `BStackVec::from_slice` or
`bstack_move!`) persists only once written into a field
([moved-out-is-unrooted](#moving-out-bstack_move)).

When the elements are `#[bstack_block]` values, the **annotation** states the
elements' ownership; an **un-annotated** `Vec<T>` is always POD (`T: Pod`):

| Field                                | Element handle       | Accessor                 | On the struct's teardown                              |
|--------------------------------------|----------------------|--------------------------|-------------------------------------------------------|
| `Vec<T>` / `String` *(un-annotated)* | POD value (`T: Pod`) | `BStackVec<T>`           | frees the data block                                  |
| `#[bstack_owned] Vec<Thing>`         | `BStackOwned<Thing>` | `BStackBlockVec<Thing>`  | recursively frees every child, then the offset array  |
| `#[bstack_strong] Vec<Thing>`        | `BStackRc<Thing>`    | `BStackStrongVec<Thing>` | releases each strong ref (frees at 0), then the array |
| `#[bstack_weak] Vec<Thing>`          | `BStackWeak<Thing>`  | `BStackWeakVec<Thing>`   | releases each weak ref, then the array                |
| `#[bstack_ref] Vec<Thing>`           | `BStackRef<Thing>`   | `BStackRefVec<Thing>`    | frees the offset array only                           |

The constructor takes a `Vec` of the matching element handle; the accessor
returns the vector handle (`len` / `to_vec` / `get`; `BStackWeakVec` has
`upgrade(i)`; each has a `push_*`).

A vector's element may itself be a [fixed-size array](#fixed-size-arrays-t-n):
`Vec<[T; N]>`, POD or any annotated kind. But an element must be a single leaf:
`Vec<Vec<T>>` and `Vec<(A, B)>` are rejected.

To **share** a vector, wrap it in its own `#[bstack_block]` and share *that* with
`#[bstack_strong]` / `#[bstack_ref]`.

### Fixed-size arrays: `[T; N]`

A fixed-size array `[T; N]` is stored **inline**. The annotation states the
elements' ownership; an un-annotated array of `Pod` is itself `Pod`.

```rust
#[bstack_block]
struct Board {
    cells: [u16; 9],                    // POD array (un-annotated) — inline bytes
    #[bstack_owned] tiles: [Leaf; 3],   // 3 owned children (freed on teardown)
    #[bstack_ref]   marks: [Leaf; 2],   // 2 borrowed refs (free nothing)
    #[embed]        kids:  [Child; 2],  // 2 children embedded verbatim, inline
}

let b = Board::new(&alloc, [0; 9], [a, b, c], [r0, r1], [k0, k1])?;
let tiles: [Leaf; 3] = b.handle().get_tiles(stack)?;   // an array of block views
```

A reference array stores `[u64; N]` inline. The constructor takes an array of the
matching handle, the accessor hands back `[T; N]` block views, and teardown
frees/releases each element per the annotation. `#[bstack_weak]` is wired per index
(`set_field(&alloc, i, weak)`) and upgrades each slot to `[Option<BStackRc<T>>; N]`.
`#[embed] [Child; N]` stores the N children's on-disk forms back-to-back.

Arrays compose freely:

- **Per-element `Option`** — `[Option<T>; N]` makes each slot nullable; a
  whole-array `Option<[T; N]>` is rejected (put the `Option` on the element).
- **Nesting to any depth** — `[[T; N]; M]`, `[[[T; N]; M]; K]`, … work for every
  kind (POD / owned / strong / weak / ref / embed).

### Nullable fields: `Option`

Wrap a reference or vector field in `Option` to make it nullable. On disk it's
unchanged — a `0` offset is `None`; an *empty* present vector still has a non-zero
data block, distinct from `None`:

```rust
#[bstack_block]
struct Node {
    #[bstack_owned]  left: Option<Child>,     // may be absent
    #[bstack_strong] shared: Option<Thing>,
    labels: Option<Vec<u32>>,                 // nullable POD vector
}
```

The accessor returns `io::Result<Option<_>>`, the constructor takes an `Option`
(`Option<BStackOwned<Child>>` / `Option<&[T]>` / …), and `bstack_move!` yields
`Option<_>`. (`#[bstack_weak]` fields are already nullable.)

An `Option` on an **un-annotated POD** field is different: `Option<A>` is stored
*inline* whenever `A: bytemuck::PodInOption` (so `Option<A>: Pod`) and handed
back by value. A plain `Option<u32>` is *not* `Pod` and is rejected.

`Option` *is* a Rust `enum`, but this is a macro niche optimization and **not** a
[`#[bstack_enum]`](#enums-bstack_enum) (no discriminant byte, no `EData` / `EView`,
no extra block). Any other sum type is a `#[bstack_enum]`.

### Enums: `#[bstack_enum]`

A `#[bstack_enum]` lowers a Rust `enum` to a **tagged-union block**: a
discriminant plus a payload sized to the largest variant. A variant is either a
**POD aggregate** or an **annotated single-field tuple** whose annotation works
like a struct field's annotation:

```rust
#[bstack_enum]
enum Node {
    Empty,                            // unit (POD aggregate, 0 fields)
    Num(u32),                         // POD, inline
    Rect { w: u32, h: u32 },          // POD struct variant, packed inline
    #[bstack_ref]    Link(Leaf),      // borrowed reference (frees nothing)
    #[bstack_owned]  Child(Leaf),     // owned child (freed on teardown)
    #[bstack_strong] Shared(Thing),   // a strong ref (Thing is (rc)/(rc, weak))
    #[bstack_weak]   Watch(Thing),    // a weak ref (Thing is (rc, weak))
}

let node = Node::new(&alloc, NodeData::Child(leaf))?;   // construct a variant
match node.handle().read(&alloc)? {                     // read / match it
    NodeView::Child(c) => assert_eq!(c.get_val(stack)?, 7),
    _ => {}
}
node.bstack_drop(&alloc)?;                              // frees the owned child too
```

The two [companion enums](#generated-types) are directional duals:

- **`NodeData`** — the in-memory *owned* form (POD by value; `#[bstack_owned]` →
  `BStackOwned<T>`, `#[bstack_strong]` → `BStackRc<T>`, `#[bstack_weak]` →
  `BStackWeak<T>`, `#[bstack_ref]` → `BStackRef<T>`). The **same** type is passed
  to `new` and returned by [`bstack_move!`]#moving-out-bstack_move.
- **`NodeView`** — the read result: POD by value, owned/ref children as borrowed
  handles, a weak variant *upgraded* to `Option<BStackRc<T>>`. `read` takes the
  allocator.

A single-field variant carries the same shapes a struct field does:

```rust
#[bstack_enum]
enum Cell {
    Empty,
    Tags(Vec<u32>),                          // POD vector variant
    Text(String),                            // POD string variant
    #[bstack_owned] Kids(Vec<Leaf>),         // owned vector (freed on teardown)
    #[bstack_ref]   Row([Leaf; 3]),          // inline reference array
    #[bstack_owned] Grid(Vec<[Leaf; 2]>),    // vector of reference-arrays
}
```

An array variant `V([T; N])` mirrors a scalar `V(T)` per element; a vector variant
`V(Vec<…>)` stores a descriptor. The same nesting and directed-error rules apply as
for struct fields.

Like a struct, an enum has [modes](#concepts): `#[bstack_enum(rc)]` / `(rc, weak)`
make the enum itself refcounted / weak-observable (`new` returns `BStackRc<E>`), so
it can be a `#[bstack_strong]` / `#[bstack_weak]` field. [`bstack_move!`](#moving-out-bstack_move)
and [`bstack_cast!`](#casting-bstack_cast) work as on structs. Moving frees the
shell and hands the active variant out through `NodeData`.

An enum is a block, so it is **always referenced** like a struct. A POD aggregate
variant's fields must all be `Pod` and it takes no annotation. Duplicate
discriminant values are a clear compile error.

#### Discriminant width

The discriminant defaults to the **smallest integer** that fits every variant's
value, honors explicit `= value` discriminants, and chooses a **signed** type
if any value is negative.

Pin it with `repr(..)` — `#[bstack_enum(repr(u16))]` (any of
`u8|u16|u32|u64|i8|i16|i32|i64`; `usize`/`isize` are rejected). `repr(aligned)` is
`repr(u64)`, letting a variant's on-disk `u64` ref gets aligned writes.

Enums take the same tag controls as structs: `tag = "…"`, `ctrl_tag = "…"` (for
`(rc, weak)`), and `allow(overlong_tag)` — e.g.
`#[bstack_enum(repr(u64), rc, weak, tag = "NODE")]`.

#### Default variant

Mark one **unit** variant `#[default]` to generate `impl Default for <Enum>Data`
returning it. `Default::default()` takes no allocator, so only a **unit** variant
qualifies (`[BSTACK0206]` otherwise), and at most one may be marked (`[BSTACK0207]`).
Then `Node::new(&alloc, NodeData::default())?` builds that variant.

### Field types

`Vec<T>`, `String`, `Option<…>`, and `[T; N]` in a field are **recognized
spellings**, not the `std` types — the macro lowers each to a bstack_raii on-disk
form. They **compose**, with two directed-error limits: at most one `Option` layer
(`Option<Option<T>>` → use a `#[bstack_enum]`), and a `Vec` element must be a single
leaf (`Vec<Vec<T>>` → a named `#[bstack_block]`).

A **POD tuple** field — `a: (A, B, …)`, every element `Pod` — also works: stored
through a generated packed wrapper and handed back as a tuple. `bstack_move!` keeps
each tuple as **one** element (a `(u8, u8)` comes back whole, not flattened). A
tuple is *not* a valid `Vec`/array element — `Vec<(A, B)>` is rejected in favor of
a named `#[bstack_block]`.

A field written `&T` is coerced to owned `T` (and `&str` to `String`) with a
compile warning; silence it with `#[bstack_block(allow(coerced_ref))]`.

### Generic blocks

A `#[bstack_block]` / `#[bstack_enum]` may be **generic** over type parameters
(and, for arrays, `const` parameters). Each concrete instantiation is its own block
type and [type tag](#type-tags-eightcc).

```rust
#[bstack_block]
struct Node<T> {
    #[bstack_owned] child: T,          // owns a child of any block type
    #[bstack_ref]   refs:  [T; 3],     // an array of references to T
    weight: u32,
}

#[bstack_block]
struct Buf<const N: usize> { data: [u16; N], len: u32 }   // const-length POD array

let n = Node::<Leaf>::new(&alloc, leaf, [r0, r1, r2], 5)?;
let b = Buf::<8>::new(&alloc, [0; 8], 0)?;
```

A type parameter works in **every** field shape it makes sense in:

- **Reference kinds** — `#[bstack_owned/strong/weak/ref]` (scalar, `Vec<T>`,
  `[T; N]`, `Vec<[T; N]>`, …): the on-disk form is a bare `u64` offset, so the
  layout is independent of `T`. The parameter is auto-bounded `BStackBlock` (plus
  `BStackShared` / `BStackWeakable` for a strong / weak use).
- **Inline kinds** — a POD field (`item: T`, `T: Pod`) or `#[embed] item: T`
  (`BStackBlock`): `T` is stored *inline*, so `XOnDisk` becomes generic over it. A
  parameter can't be used **both** as POD and as a reference.
- **`const N`** in an array length — `[T; N]` (single dimension). A nested
  `[[T; N]; M]` with a const dimension is rejected; make one dimension concrete.

Each instantiation folds its arguments into the tag, so
[`bstack_cast!`](#casting-bstack_cast) can't confuse `Node<A>` with `Node<B>`. A
generic **enum** is supported in the layout-preserving case only: a type parameter
may appear in a reference variant (`#[bstack_owned] Branch(T)`), not in a
POD/`#[embed]` variant.

Currently unsupported (a clear compile error): lifetime parameters, a generic
block in `rc` / `rc, weak` mode, and const parameters in a generic *enum*.

## Mutating fields: `#[bstack_mut]`

Every scalar field gets a reader (`get_<field>`). *Writing* one is opt-in: mark it
`#[bstack_mut]` and the macro adds the mutator for its kind. Immutability is the
default, and each generated write is a single crash-atomic `set`.

```rust
#[bstack_block]
struct Counter {
    #[bstack_mut] hits: u64,   // writable
    created_at: u64,           // read-only (no setter generated)
}

let c = Counter::new(&alloc, 0, now)?;
c.handle().set_hits(stack, 42)?;             // atomic overwrite
assert_eq!(c.handle().get_hits(stack)?, 42);
```

The mutator depends on the field's ownership:

| Field kind         | Mutator                              | Semantics                                                                     |
|--------------------|--------------------------------------|-------------------------------------------------------------------------------|
| POD                | `set_<field>(stack, value)`          | overwrite the inline bytes                                                    |
| `#[bstack_ref]`    | `set_<field>(stack, ref)`            | repoint the offset (nullable → `Option<BStackRef>`, `None` writes `0`)        |
| `#[bstack_owned]`  | `replace_<field>(stack, new)`        | install `new`, **return the old** `BStackOwned<T>` (neither leaked nor freed) |
| `#[bstack_strong]` | `replace_<field>(&alloc, new)`       | install `new`, return the old `BStackRc<T>` (dropping it decrements)          |
| `#[bstack_ref]`    | *(also)* `replace_<field>(stack, r)` | ref is the only kind with **both** `set_` and `replace_`                      |

`replace_` is a persistent `mem::replace`: it hands the old value back to reuse or free.

Because it **consumes** the new value, `replace_` returns `Result<Old,
ReplaceError<New>>`: an I/O failure hands the consumed value back in
`ReplaceError.value`. The *old* value is never at risk. The lone `value: None`
case is a strong field whose old handle fails to reconstruct *after* commit;
the old block is then reclaimable only via crash-recovery.

`#[bstack_weak]` fields already have their own
[`set_<field>`](#reference-counted-blocks) wiring, making `#[bstack_mut]` a no-op.
`#[bstack_mut]` on an `#[embed]` field is a compile error.

### Containers

`#[bstack_mut]` also works on POD tuples and block-reference arrays; a `Vec` is
already mutable and needs no annotation:

| Field shape                          | Mutator(s)                                                                 |
|--------------------------------------|----------------------------------------------------------------------------|
| POD tuple `(A, B, …)`                | `set_<field>(stack, tuple)` — one atomic overwrite (owns no children)       |
| `#[bstack_owned/strong] [T; N]`      | `replace_<field>_at(&alloc, i, new) -> old` and `replace_<field>(&alloc, arr) -> old_arr` |
| `#[bstack_ref] [T; N]`               | *(also)* `set_<field>_at` / `set_<field>` (a ref owns nothing)              |
| `Vec<T>` (any kind)                  | *none needed* — mutate in place via the `get_<field>()` handle (`push_*`, …) |
| `#[bstack_owned/strong/weak] Foreign<T>` | `replace_<field>(&alloc, new) -> old` — moves the old cross-file target out as `ForeignOwned`/`ForeignRc`/`ForeignWeak` |
| `#[bstack_ref] Foreign<T>`           | *(also)* `set_<field>` / `replace_<field>` trafficking in plain `Foreign`   |

Arrays are fixed-size. The element mutators use a **row-major flat** `index`
(for `[[T; M]; N]`, slot `i*M + j` is `grid[i][j]`). Both `replace_` forms are one
crash-atomic `set` and uphold the same `ReplaceError` contract. A `Vec` persists its
descriptor back to the field on every mutation, so mutating the accessor handle *is*
mutating the field; `#[bstack_mut]` on a `Vec` is an accepted no-op.

A **scalar `Foreign<T>` / `Option<Foreign<T>>`** field is mutable, and its swap is
*purely local* and atomic: `replace_` hands the old target back as its RAII dual;
it needs no registry access and works even if the target file is detached. Owning
kinds get **only** `replace_`; a foreign `ref` also gets `set_`. `Foreign` inside
a container or tuple has no mutator yet.

### Enums

An enum's payload has no stable "field" to set, so `#[bstack_mut]` on the **enum
itself** generates a *whole-value* mutator that overwrites the discriminant +
payload together:

```rust
#[bstack_enum]
#[bstack_mut]
enum State { Idle, Active(u32), #[bstack_owned] Holding(Child) }

// owns nothing → `set` (wholesale overwrite):
// e.handle().set(&alloc, StateData::Active(7))?;
// owns children → `replace` (moves the old value out, ReplaceError contract):
let old = e.handle().replace(&alloc, StateData::Idle)?; // old: StateData::Holding(BStackOwned<Child>)
```

`set` is generated when no variant owns anything (pure POD / `ref` / foreign-`ref`);
`replace` when some variant owns children (owned / strong / weak / foreign),
returning the old value as `EData`. `#[bstack_mut]` on a **variant** is an error (it
goes on the enum), as is `#[bstack_mut]` on a shared (`rc` / `rc, weak`) enum or one
with an `#[embed]` variant.

There is also a raw escape hatch on **every** scalar field:
`unsafe fn raw_<field>_slice(stack) -> BStackSlice`, which is a view over the field's
inline storage (`.read()` / `.write()`). Writing bypasses the typed invariants and is `unsafe`.

## Moving out: `bstack_move!`

`bstack_move!` destructures a handle, transferring each field/variant out and
freeing only the parent *shell*.

On a **`BStackOwned<X>`** it is infallible. Because a bare owned handle carries
no allocator, pass one — `bstack_move!(owned, &alloc)`:

```rust
let pair: BStackOwned<Pair> = /* … */;
let (left, shared, right) = bstack_move!(pair, &alloc)?;
//   ^BStackOwned<Leaf>  ^BStackRc<Thing>  ^u32
```

On a **`BStackRc<X>`** it is a `try_unwrap`: success only when this is the **sole
strong owner**, else it hands the handle back. A weak observer doesn't block it. An
allocator-carrying handle (a `BStackRc`, or `owned.auto(&alloc)`) takes the
single-argument form:

```rust
match bstack_move!(rc)? {
    Ok((left, shared, right)) => { /* we were the only owner */ }
    Err(rc)                    => { /* someone else still holds it */ }
}
```

An [enum](#enums-bstack_enum) moves out through its `EData` companion instead of
a tuple.

> **Moved-out values are unrooted.** A handle from `bstack_move!` — like one from
> `X::new` — is detached from any persistent structure. Its block still lives on
> disk, but is reachable *only* through your in-memory handle: drop it without
> re-attaching or freeing it and it becomes unreachable garbage.

## Cloning: `TryCloneIn` / `TryClone`

Duplicating a handle means one of two things depending on whether the block is
uniquely owned or shared.

### Deep-clone an owned block: `TryCloneIn`

A plain `#[bstack_block]` / `#[bstack_enum]` implements `TryCloneIn`, a **deep**,
fallible clone into a fresh, independent `BStackOwned<Self>`:

```rust
use bstack_raii::TryCloneIn;

let copy: BStackOwned<Node> = node.try_clone_in(&alloc)?;
```

Each field is duplicated according to its ownership, which is the mirror of teardown:

| Field                 | On clone                                                                                                               |
|-----------------------|------------------------------------------------------------------------------------------------------------------------|
| POD / `#[bstack_ref]` | byte-copied (a ref clone **aliases** the same target)                                                                  |
| `#[bstack_owned]`     | the child is recursively deep-cloned into a fresh block                                                                |
| `#[embed]`            | the inline child is folded — its own children deep-cloned in place                                                     |
| `#[bstack_strong]`    | the shared child stays shared; its strong count is bumped                                                              |
| `#[bstack_weak]`      | stays weak to the same target; its weak count is bumped                                                                |
| `Vec<Thing>`          | per element, by the vector's annotation (POD data copied; owned elements deep-cloned; strong/weak bumped; ref aliased) |

So owned subtrees are copied into independent storage while shared children are
*re-referenced*: freeing the clone never disturbs the original's owned data.

> **Atomicity & crash-safety.** A clone allocates the whole new subtree up front,
> then commits every payload write *and* refcount bump as one crash-atomic batch
> (`BStack::inplace_gen`): a mid-clone allocation failure rolls back with nothing
> written, and a crash never leaves a torn copy. With a WAL anchor the fresh
> allocations are logged as made, so a crash *mid-clone* is reclaimed on the next
> open, completed by [`wal::finish`]. On a bulk-capable allocator
> (`BStackBulkAllocator`) the whole subtree is allocated in a single atomic `alloc_bulk`.

### Duplicate a shared handle: `TryClone`

A shared block is **not** deep-cloned. `BStackRc` / `BStackWeak` implement
`TryClone`, whose `try_clone` bumps the on-disk refcount and hands back another
handle to the *same* block, like `Rc::clone`:

```rust
use bstack_raii::TryClone;

let rc2 = rc.try_clone()?;      // another strong owner of the same block
let weak2 = weak.try_clone()?;  // another weak observer of the same block
```

An `(rc)` / `(rc, weak)` block therefore has no `try_clone_in`. A weak reference has
no coherent deep copy at all.

## Casting: `bstack_cast!`

Convert between typed handles and the untyped `bstack` primitives. Upcasts are
infallible; downcasts check the block's [tag](#type-tags-eightcc). Name the target
with `as`:

```rust
use bstack_raii::{BStackCastAs, BStackCastInto};   // the cast methods

let owned: BStackOwned<Node> = /* … */;
let slice = bstack_cast!(owned.auto(&alloc) as BStackOwnedSlice);   // owned upcast

match bstack_cast!(slice as BStackOwned<Node, _>) {                 // owned downcast
    Ok(node) => { /* tag matched */ }
    Err(e)   => { let slice = e.into_slice(); /* not a Node — slice handed back */ }
}

let view = node.handle().as_slice(stack);                           // borrowed upcast
let maybe: Option<Node> = bstack_cast!(view as Node)?;              // borrowed downcast
```

The equivalent methods (`into_slice`, `cast_into::<T>`, `cast_as::<T>`,
`as_slice`) can also be called directly. Casting works the same for enums.

## Cross-file pointers: `Foreign<T>`

Every reference covered so far points *within one file*. A `Foreign<T>` crosses
the boundary with a **wide pointer** naming both a target **file** and an offset inside
it, so an object graph can span many `bstack` files, each an independent crash-safe
unit.

### The file registry

Paths are awkward to store on disk, so a process-wide **registry** maps each file's
path ↔ a small, stable numeric [`FileId`]. A `Foreign` stores `(FileId, offset)`,
resolved to a live file through the registry. It is opt-in.

```rust
use bstack_raii::registry;

registry::init("registry.bstack")?;                  // once, at startup
let store_id = registry::attach("store.bstack", store_alloc)?;  // hand a file to the registry
```

`init` brings up the registry, which a small `bstack` file, allowing ids to survive a restart.
`attach` registers a file's path and installs its allocator as the **live host** a
`Foreign` into that file resolves through; it takes a
[`SyncBStackRaiiAllocator`](src/registry.rs) ([`BStackRaiiAllocator`] + `Send + Sync`),
which every bstack allocator qualifies. `FileId::SELF` (id `0`) is the current file, resolved
locally.

### Declaring a foreign field

A `Foreign<T>` field **must** carry an [ownership annotation](#field-ownership),
meaning the same thing as in-file. The target `T` must be a `#[bstack_block]` — an
un-annotated / POD / `#[embed]` `Foreign` is a compile error:

```rust
#[bstack_block]
struct Card {
    title: String,
    #[bstack_owned] body: Foreign<Document>,   // owns a Document in another file
}

// `Foreign::new` / `Foreign::at` are `unsafe` (a raw offset can't prove it names a
// valid `T`); the safe ways are `bstack_cast!(slice as Foreign<T>)` / `from_local`,
// or reading a field.
let ptr = unsafe { Foreign::<Document>::new(store_id, doc_off) };
let card = Card::new(&catalog, "report", ptr)?;

// Resolve across the boundary: `with` runs a closure against the target and its
// file's stack — `Ok(None)` if null, `Err` if that file isn't live.
let size = card.handle().get_body(catalog.stack())?
    .with(&catalog, |doc, fs| doc.get_size(fs).unwrap())?  // io::Result<Option<u64>>
    .expect("owned Foreign is never null");
```

`Foreign<'a, T>` is a 16-byte, zero-cost enum: an **explicit** pointer (a `FileId`
+ offset) or a [`SELF`] pointer. An accessor returns it with `'a` **bound to the
`&'a BStack` it read through**, so a `SELF` pointer can never be stored into or
outlive its file; an explicit pointer ignores the borrow and can be [`detach`]ed
to a `'static` `Foreign` (a `SELF` one cannot).

The annotation decides what teardown and clone do **in the target's own file**:

| Annotation         | Cross-file teardown                       | Cross-file clone                                  | `bstack_move!` yields    |
|--------------------|-------------------------------------------|---------------------------------------------------|--------------------------|
| `#[bstack_owned]`  | frees the target in its file              | deep-clones it into a fresh block in that file    | `ForeignOwned<T>`        |
| `#[bstack_strong]` | decrements its refcount there (free at 0) | bumps its refcount there (stays shared)           | `ForeignRc<T>`           |
| `#[bstack_weak]`   | decrements its weak count there           | bumps its weak count there                        | `ForeignWeak<T>`         |
| `#[bstack_ref]`    | nothing                                   | byte-copies the pointer (aliases the same target) | `Foreign<T>`             |

So tearing down a `Card` reclaims its `Document` in the store file, and cloning a
`Card` gives the copy its own independent `Document` there. (`#[bstack_owned]` needs
a deep-cloneable target, so `#[bstack_owned] Foreign<SharedBlock>` where the target
is itself `(rc)` is a compile error; use `#[bstack_strong]`.)

Moving an owning foreign field out with `bstack_move!` hands back its **RAII dual** —
`ForeignOwned` / `ForeignRc` / `ForeignWeak`, the cross-file analogues of
`BStackOwned` / `BStackRc` / `BStackWeak`. Each is non-`Copy` and carries
`.bstack_drop(&home)` (frees the target in its own file) and `.into_foreign()`
(→ a plain `Foreign` to re-store). A `#[bstack_ref]` field moves out as a plain
`Foreign`. Each also **resolves to its in-file handle** with `.into_local(..)` —
`ForeignOwned → BStackOwned<T>`, `ForeignRc::into_local(&target) → BStackRc<T>`,
`ForeignWeak::into_local(&target) → BStackWeak<T>`. Like `BStackOwned`, these don't
free on `Drop`. *(Currently scalar foreign fields only; an owning `Foreign` inside a
`Vec`/array/tuple/enum moves out as a bare `Foreign`.)*

> **Nullable & atomicity.** `Option<Foreign<T>>` is nullable on the offset-0 niche.
> Cross-file operations are *best-effort atomic*: the far side is committed before
> the home side, so a mid-op failure errs toward an over-provision (reclaimable) and
> never an under-count. If the target file is detached, teardown leaks (never
> corrupts) and a clone returns an error rather than aliasing an owner.

### Containers and shapes

A `Foreign<T>` composes everywhere an in-file reference does:

```rust
#[bstack_owned] parts: Vec<Foreign<Document>>,          // a growable list of pointers
#[bstack_owned] shards: [Foreign<Document>; 4],          // an inline fixed array
#[bstack_ref]   pair: (u32, Foreign<Document>),          // a foreign element in a tuple
```

Nesting and generics compose too. `Vec<Option<Foreign<T>>>`, nested arrays, and
generic targets all work, in struct fields and `#[bstack_enum]` variants alike.

A `Foreign` must target a plain block, not a pointer or container, so `Foreign<Vec<T>>`,
`Foreign<Foreign<T>>`, `Foreign<[T; N]>`, and `Foreign<(A, B)>` are rejected (bridge
through a named `#[bstack_block]`). A collection *of* pointers (`Vec<Foreign<T>>`) is
fine allowed.

[`bstack_cast!`](#casting-bstack_cast) bridges a `Foreign` and a local handle:
`slice as Foreign<T>` tags a slice with its file identity; `foreign as BStackRef<T>`
recovers a same-file reference for a local target. Both return `Option` (no I/O).

A full two-file walk-through is in [`examples/crossfile.rs`](examples/crossfile.rs):
`cargo run --example crossfile`.

## Type tags (`EightCC`)

Each block's header carries an 8-byte tag — the discriminant a
[downcast](#casting-bstack_cast) checks. It's computed at compile time: a short
**readable prefix** followed by a **hash tail**.

1. **Prefix** — derived from the type name: for a multi-word camel-case name, the
   uppercased word initials (`OrderLine` → `OL`); for a single word, its de-voweled
   uppercase (`Session` → `SSSN`, clamped). 2–4 bytes.
2. **Hash** — a 64-bit **FNV-1a** hash of `crate_name ++ "\0" ++ type_name`, with
   `module_path!()` folded into the tail (so same-named types in different modules
   stay distinct), little-endian. Every byte then has its **high bit set** (`| 0x80`),
   pushing it out of the printable range.
3. **Overlay** — the prefix bytes overwrite the low bytes of the hash; the high
   bytes are the hash tail.

A hex dump thus reads as a prefix followed by clearly-not-a-name bytes (every hash
byte ≥ `0x80`), e.g. `O L 8B C2 A9 F0 BD 91`. Being pure and deterministic, the tag
is stable across builds and versions. Override the prefix for a fixed tag (0–8 bytes;
fewer than 8 leaves room for the hash, exactly 8 is fully manual):

```rust
#[bstack_block(rc, tag = "ORDLINE")]        // explicit data tag
struct OrderLine { /* … */ }
```

`ctrl_tag = "…"` overrides the control-block tag (default: the data tag, distinct).
An override longer than 8 bytes is truncated with a compile warning;
`#[bstack_block(allow(overlong_tag))]` silences it.

This also works for `#[bstack_enum]` — e.g. `#[bstack_enum(rc, tag = "ENMTAG")] enum Mode { Unit, Val(u32) }`.

## Standard library collections

Built entirely on the primitives above — no privileged access. Every collection is
a plain [`BStackBlock`] (`BStackDrop` + `TryCloneIn`), so it can be used bare (a
top-level `BStackOwned<...>`) or composed as a `#[bstack_owned]` field, nested in
another collection, or held in a `#[bstack_enum]` variant.

| Type                              | Rust analogue                    | What it holds |
|------------------------------------|-----------------------------------|----------------|
| [`BStackCow<T>`]                  | `std::borrow::Cow`                | either a borrowed reference or an owned block, deep-copying on first write. |
| [`BStackBox<T>`]                  | `std::boxed::Box`                 | a single owned `Pod` value in its own block — the macro-free way to own a bare scalar/POD struct. |
| [`BStackLinkedList<T>`]           | `std::collections::LinkedList`    | an owned doubly-linked list of block values. Prefer `BStackDeque` / `BStackBlockVec` unless you need O(1) end/splice ops. |
| [`BStackDeque<T>`]                | `std::collections::VecDeque`      | an owned double-ended queue: a contiguous ring, O(1) amortized push/pop at both ends. |
| [`BStackHashMap<K, V>`]           | `std::collections::HashMap`       | an owned open-addressing map from a `Pod` key to a block value. |
| [`BStackBTreeMap<K, V>`]          | `std::collections::BTreeMap`      | an owned **ordered** map (copy-on-write B-tree) with sorted iteration. Keys are `Pod + Ord`. |
| [`BStackString`]                  | `std::string::String`             | a standalone owned, growable UTF-8 string block — the first-class way to own text (a deque element, a map value). |
| [`BStackCountingBloomFilter<K>`]  | (Bloom filter)                    | a probabilistic set: no false negatives, supports removal — a cheap fast-reject front for exact lookups. |
| [`BStackHashSet<K>`]              | `std::collections::HashSet`       | an owned open-addressing set of `Pod` keys, with an embedded Bloom-filter fast-reject front. |
| [`BStackBTreeSet<K>`]             | `std::collections::BTreeSet`      | an owned **ordered** set (copy-on-write B-tree), with an embedded Bloom-filter front. Keys are `Pod + Ord`. |
| [`BStackBinaryHeap<K, V>`]        | `std::collections::BinaryHeap`    | an owned priority queue (array-backed binary **min**-heap): `pop` returns the smallest-key entry. Keys are `Pod + Ord`. |

Each is constructed with `new` (or `with_capacity`), torn down with `bstack_drop`,
and deep-cloned with `try_clone_in`:

```rust
use bstack_raii::{BStackDrop, BStackHashMap, BStackString};

let map = BStackHashMap::<u32, BStackString>::new(&alloc)?;
map.insert(&alloc, 1, BStackString::new(&alloc, "one")?)?;
map.insert(&alloc, 2, BStackString::new(&alloc, "two")?)?;

let v = map.get(alloc.stack(), &1)?.unwrap();  // -> a BStackString handle
assert_eq!(v.to_string(alloc.stack())?, "one");

map.bstack_drop(&alloc)?;  // frees the map AND every owned BStackString value
```

Composing one into a block field: clone and teardown recurse through it
automatically:

```rust
#[bstack_block]
struct Session {
    id: u64,
    #[bstack_owned]
    log: BStackDeque<BStackString>,
}
```

Each collection's iterator (`HashMapIter`, `DequeIter`, `ListIter`, `BTreeMapIter`,
…) borrows the allocator's [`BStack`] and yields owned element handles.

## Examples

Runnable end-to-end programs live in [`examples/`](examples/):

| Example                                 | Run                             | Shows                                                                                                          |
|-----------------------------------------|---------------------------------|----------------------------------------------------------------------------------------------------------------|
| [`sessions.rs`]examples/sessions.rs   | `cargo run --example sessions`  | shared `(rc, weak)` ownership, refcount-driven cleanup, durability across a reopen                             |
| [`expr.rs`]examples/expr.rs           | `cargo run --example expr`      | a recursive `#[bstack_enum]` tree — evaluation, deep clone (`TryCloneIn`), `bstack_move!`                      |
| [`crossfile.rs`]examples/crossfile.rs | `cargo run --example crossfile` | [`Foreign<T>`]#cross-file-pointers-foreignt across two files — resolution, cross-file ownership, reclamation |

## Limitations

- **Fixed-size block payloads.** [Arrays]#fixed-size-arrays-t-n `[T; N]` (nested
  to any depth) are stored *inline*; a *variable-length* sequence lives out-of-line
  via an inline descriptor (`Vec<T>` / `String`, `#[bstack_owned/strong/weak/ref]
  Vec<Thing>`, `Vec<[Thing; N]>`, and their `Option<…>` forms).
- **Requires a [`BStackRaiiAllocator`]** — a freeing allocator that reserves offset
  0; not `LinearBStackAllocator` (see [Concepts]#concepts).
- **[Generic blocks]#generic-blocks** work over type parameters (every field kind)
  and `const` array lengths; not over lifetime parameters, `rc` / `rc, weak` mode,
  or const parameters in a generic enum.
- **`Vec` / `Option` nesting** is capped at a single leaf / one `Option` layer (see
  [Field types]#field-types); deeper nesting or a tuple element needs a named
  `#[bstack_block]` / `#[bstack_enum]`.
- **Enums** support unit / POD / all four annotated variant kinds (as scalars,
  arrays, and vectors) in all three modes, plus `bstack_move!` / `bstack_cast!`;
  struct and multi-field tuple variants aren't supported, nor an `#[embed]` variant.
- **[Cross-file pointers]#cross-file-pointers-foreignt** (`Foreign<T>`) must target
  a plain block, never a pointer or container ("no double pointer"); their operations
  are *best-effort atomic* (a failure over-provisions rather than under-counts), and
  resolution requires the target file `attach`ed to the registry.
- **[Standard library collections]#standard-library-collections** can't be shared
  (`#[bstack_strong]` / `#[bstack_weak]`) — they aren't `(rc)` blocks; `bstack_move!`
  only works on `BStackBox`.
- The on-disk **ABI is not yet stable**.

## Error codes

Every compile-time error from the `#[bstack_block]`, `#[bstack_enum]`,
`bstack_move!`, and `bstack_cast!` macros carries a stable `[BSTACKxxxx]` code, e.g.:

```text
error: [BSTACK0301] `Foreign` is a pointer and cannot be `#[embed]`ed
```

The message states the fix inline; **[ERRORS.md](ERRORS.md)** is the full reference,
with one entry per code (grouped by domain — attributes `00xx`, field shapes `01xx`,
enums `02xx`, `Foreign` `03xx`, generics `04xx`, `#[embed]` `05xx`, `#[bstack_mut]`
`06xx`, cast/move macros `07xx`).

## License

MIT (same as `bstack`).

[`bstack`]: https://github.com/williamwutq/bstack
[`std::io::Result`]: https://doc.rust-lang.org/std/io/type.Result.html
[`TryClone`]: src/clone.rs
[`BStackVec<T>`]: src/vec.rs
[`FileId`]: src/registry.rs
[`BStackRaiiAllocator`]: src/lib.rs
[`BStackBlock`]: src/block.rs
[`wal::finish`]: src/wal.rs
[`STD_WAL_ANCHOR`]: src/wal.rs
[`BStack`]: https://docs.rs/bstack
[`BStackCow<T>`]: src/stdlib/cow.rs
[`BStackBox<T>`]: src/stdlib/boxed.rs
[`BStackLinkedList<T>`]: src/stdlib/list.rs
[`BStackDeque<T>`]: src/stdlib/deque.rs
[`BStackHashMap<K, V>`]: src/stdlib/map.rs
[`BStackBTreeMap<K, V>`]: src/stdlib/tree.rs
[`BStackString`]: src/stdlib/string.rs
[`BStackCountingBloomFilter<K>`]: src/stdlib/bloom.rs
[`BStackHashSet<K>`]: src/stdlib/hashset.rs
[`BStackBTreeSet<K>`]: src/stdlib/btreeset.rs
[`BStackBinaryHeap<K, V>`]: src/stdlib/heap.rs