docs(adr): flesh out Option B C-Data detail in ADR 0016

Add concrete Arrow C-Data Interface requirements: ArrowSchema/ArrowArray
struct fields, per-Array-subtype format codes + buffer order, and the three
work items (validity bitmap packing, lazy materialise, lifetime/release pin).
Record the relationship to a standalone Array.materialize(arena) delegation
seam, which would produce the Arrow values buffer.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: dfa1

docs/adr/0016-vortex-arrow-bridge.md

@@ -69,6 +69,79 @@ dependency entirely. The consumer imports via any Arrow C-Data-aware runtime.
   structs and lifetime/release-callback management over FFM — significant complexity;
   validity/offset buffer layout must match Arrow's spec exactly.
 
+#### Option B — concrete C-Data requirements
+
+The interface is two C structs filled via FFM `MemoryLayout.structLayout(...)`:
+
+- `ArrowSchema` — `format` (type-code string), `name`, `metadata`, `flags`
+  (`ARROW_FLAG_NULLABLE = 2`), `n_children`, `children`, `dictionary`, `release`,
+  `private_data`.
+- `ArrowArray` — `length`, `null_count` (`-1` = unknown), `offset`, `n_buffers`,
+  `n_children`, `buffers` (array of pointers), `children`, `dictionary`, `release`,
+  `private_data`.
+
+Buffer count and order per Vortex `Array` subtype (validity is always `buffers[0]`):
+
+| Vortex Array             | `format`       | n_buffers | buffers (in order)                 |
+|--------------------------|----------------|-----------|------------------------------------|
+| `LongArray` (I64/U64)    | `l` / `L`      | 2         | validity, values                   |
+| `IntArray`               | `i` / `I`      | 2         | validity, values                   |
+| `ShortArray`             | `s` / `S`      | 2         | validity, values                   |
+| `ByteArray`              | `c` / `C`      | 2         | validity, values                   |
+| `DoubleArray`            | `g`            | 2         | validity, values                   |
+| `FloatArray`             | `f`            | 2         | validity, values                   |
+| `Float16Array`           | `e`            | 2         | validity, values                   |
+| `BoolArray`              | `b`            | 2         | validity, data (packed bitmap)     |
+| `VarBinArray.OffsetMode` | `u` / `z`      | 3         | validity, offsets (i32), data      |
+| (large offsets)          | `U` / `Z`      | 3         | validity, offsets (i64), data      |
+| `VarBinArray.ViewMode`   | `vu` / `vz`    | ≥3        | validity, views (16B), data buf(s) |
+| `DecimalArray`           | `d:P,S[,bits]` | 2         | validity, values (fixed width)     |
+| `StructArray`            | `+s`           | 1         | validity; children = fields        |
+| `ListArray`              | `+l` / `+L`    | 2         | validity, offsets; 1 child         |
+| `FixedSizeListArray`     | `+w:N`         | 1         | validity; 1 child                  |
+| `Dict*`                  | indices format | 2         | validity, codes; `dictionary` → values |
+| `NullArray`              | `n`            | 0         | —                                  |
+
+Extension types (date/time/timestamp/uuid) map either to a native Arrow code
+(`tdD` date32, `tsu:tz` timestamp) or to the storage type plus an
+`ARROW:extension:name` entry in `metadata`.
+
+Three pieces of work beyond just handing over the existing mmap slices:
+
+1. **Validity bitmap.** Arrow wants a packed LSB bitmap (`1 = valid`, byte-aligned,
+   length rounded up to 8) plus a `null_count`. Our `MaskedArray.validity()` is a
+   per-element `BoolArray`, so it must be packed; `validity == null` emits a null
+   buffer pointer with `null_count = 0`.
+2. **Lazy materialisation.** Lazy arrays (ZigZag/FoR/ALP/Dict/RLE) store the
+   *encoded* form, which is not the Arrow values layout, so they must be materialised
+   into a contiguous LE segment first. This is exactly the producer step that
+   `ArraySegments.of(...)` (or a future `Array.materialize(arena)` delegation seam,
+   see below) performs, so the internal materialise path feeds the `values` buffer
+   directly. Primitive values, VarBin data+offsets, and StringView are already
+   Arrow-shaped (zero-copy).
+3. **Lifetime / release contract.** Buffers are zero-copy slices of the mmap'd file
+   (lifetime = `VortexReader` arena), but the Arrow consumer outlives the producing
+   stack frame. `private_data` must hold a strong reference pinning the arena alive;
+   the `release` callback (an FFM upcall stub) drops that reference, frees the
+   malloc'd pointer arrays, and sets `release = NULL`. Freeing the arena before the
+   consumer calls `release` is a use-after-unmap → native segfault, not a Java
+   exception. This is the highest-risk part.
+
+### Relationship to the internal materialise seam
+
+`ArraySegments.of(Array, SegmentAllocator)` already centralises "turn any array
+(lazy or eager) into a contiguous LE primitive segment", and currently re-states each
+encoding's decode formula (ZigZag/FoR/ALP) in a large switch separate from the
+per-element accessor on the lazy array. A standalone refactor — moving that bulk
+materialisation onto the array types as an `Array.materialize(SegmentAllocator)`
+delegation (mirroring the existing `Array.limited(...)` pattern, kept on a
+package-private seam to avoid widening the public API) — stands on its own as a
+locality cleanup. It is **not** an Arrow feature, but it is the natural producer of
+the Arrow `values` buffer, so Option B should build on it rather than duplicate it.
+The contiguous LE segment it yields already matches Arrow's primitive values-buffer
+layout; the gap to a full Arrow array is validity + offsets + children, per the table
+above.
+
 ### Option C — No bridge; document manual conversion
 
 Ship nothing; point users at the typed views and let them copy into Arrow themselves.