docs: move ADRs from docs/adr to top-level adr/

Relative links rewritten: docs pages point at ../adr/, ADR upward
references drop one level, ADR links into docs/ gain the prefix.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: dfa1

CHANGELOG.md

@@ -170,7 +170,7 @@ A hardening release: no new file-format capability, but a large step up in verif
 
 - Zero-warning rule: `-Xlint:all -Werror` across all modules. The `classfile` lint (which only flags missing annotation class files inside third-party Arrow bytecode) is scoped off in the two Arrow-using modules only. ([dab467e5](https://github.com/dfa1/vortex-java/commit/dab467e5), [43f6f840](https://github.com/dfa1/vortex-java/commit/43f6f840))
 - Mutation testing (PIT): opt-in `pitest` profiles in core, reader, and writer, scoped to the bounds/parse classes (`IoBounds`, `PTypeIO`, `WriteRegistry`, `ChunkImpl`, …), with common config hoisted into the parent POM. ([46904b24](https://github.com/dfa1/vortex-java/commit/46904b24), [ed8c98a1](https://github.com/dfa1/vortex-java/commit/ed8c98a1), [1200c76b](https://github.com/dfa1/vortex-java/commit/1200c76b), [840cc46a](https://github.com/dfa1/vortex-java/commit/840cc46a))
-- SonarCloud: generated `fbs/` and `proto/` sources excluded from analysis (machine output, not hand-maintained); the deliberate per-width SIMD-loop duplication is documented in [ADR 0005](docs/adr/0005-vector-api-adoption.md) rather than refactored away. Code smells dropped 857→394; coverage ~81%, all ratings A, zero bugs/vulnerabilities. ([6c591293](https://github.com/dfa1/vortex-java/commit/6c591293))
+- SonarCloud: generated `fbs/` and `proto/` sources excluded from analysis (machine output, not hand-maintained); the deliberate per-width SIMD-loop duplication is documented in [ADR 0005](adr/0005-vector-api-adoption.md) rather than refactored away. Code smells dropped 857→394; coverage ~81%, all ratings A, zero bugs/vulnerabilities. ([6c591293](https://github.com/dfa1/vortex-java/commit/6c591293))
 
 ### Tests
 
@@ -185,7 +185,7 @@ Read and write Vortex Variant (semi-structured, JSON-shaped) columns from Java.
 
 ### Added
 
-- Writer: `vortex.variant` encoder. Encodes a variant column as the canonical `vortex.variant` container over `core_storage` — an all-equal column becomes a single `vortex.constant`, a row-varying column a `vortex.chunked` of per-run constants — with an optional row-aligned typed `shredded` child recorded in `VariantMetadata.shredded_dtype`. Input is `VariantData(List<Scalar>)` with `.constant(n, v)` / `.shredded(...)` factories. Java↔Rust (JNI) round-trip verified for constant, row-varying, and shredded columns. Scalar values only — arbitrary nested objects need `vortex.parquet.variant` (deferred, [ADR 0014](docs/adr/0014-variant-encoding-strategy.md)). ([35da529d](https://github.com/dfa1/vortex-java/commit/35da529d), [e4e44980](https://github.com/dfa1/vortex-java/commit/e4e44980), [4566dca0](https://github.com/dfa1/vortex-java/commit/4566dca0))
+- Writer: `vortex.variant` encoder. Encodes a variant column as the canonical `vortex.variant` container over `core_storage` — an all-equal column becomes a single `vortex.constant`, a row-varying column a `vortex.chunked` of per-run constants — with an optional row-aligned typed `shredded` child recorded in `VariantMetadata.shredded_dtype`. Input is `VariantData(List<Scalar>)` with `.constant(n, v)` / `.shredded(...)` factories. Java↔Rust (JNI) round-trip verified for constant, row-varying, and shredded columns. Scalar values only — arbitrary nested objects need `vortex.parquet.variant` (deferred, [ADR 0014](adr/0014-variant-encoding-strategy.md)). ([35da529d](https://github.com/dfa1/vortex-java/commit/35da529d), [e4e44980](https://github.com/dfa1/vortex-java/commit/e4e44980), [4566dca0](https://github.com/dfa1/vortex-java/commit/4566dca0))
 - Reader: variant columns now decode Java-side. `ConstantEncodingDecoder` and `ChunkedEncodingDecoder` handle `DType.Variant` (materializing the inner-typed array); `VariantEncodingDecoder` wraps the result as `VariantArray`, exposing `coreStorage()` and `shredded()`. ([76e4c741](https://github.com/dfa1/vortex-java/commit/76e4c741), [4566dca0](https://github.com/dfa1/vortex-java/commit/4566dca0))
 
 ### Security
@@ -200,7 +200,7 @@ Read and write Vortex Variant (semi-structured, JSON-shaped) columns from Java.
 
 ### Changed
 
-- Decode shape: transform encodings now decode **lazy-only**. The eager `Materialized*Array` fallbacks were removed from `vortex.zigzag` (all PTypes + broadcast, [cd59fefa](https://github.com/dfa1/vortex-java/commit/cd59fefa)), `fastlanes.for` (all integer PTypes, [d7953e1f](https://github.com/dfa1/vortex-java/commit/d7953e1f)), `vortex.alp` (broadcast-without-patches, [deab8067](https://github.com/dfa1/vortex-java/commit/deab8067)), `vortex.constant` (Decimal → `LazyConstantDecimalArray`, [a6a9611e](https://github.com/dfa1/vortex-java/commit/a6a9611e)), `vortex.runend` (Bool → `LazyRunEndBoolArray`, [0bbcb81f](https://github.com/dfa1/vortex-java/commit/0bbcb81f)), `vortex.sparse` (Bool → `LazySparseBoolArray`, [db2e955b](https://github.com/dfa1/vortex-java/commit/db2e955b)), and `fastlanes.rle` (validity → `OffsetBoolArray`, empty → `LazyConstantXxxArray`, [5e83a5c3](https://github.com/dfa1/vortex-java/commit/5e83a5c3)). Decompression encodings (`bitpacked`, `pco`, `zstd`, `fsst`, `delta`, `patched`), the primitive base, the `vortex.dict` encoding-level path, and the `vortex.alp` patches path stay Materialized by design. See [ADR 0015](docs/adr/0015-drop-materialized-fallbacks.md).
+- Decode shape: transform encodings now decode **lazy-only**. The eager `Materialized*Array` fallbacks were removed from `vortex.zigzag` (all PTypes + broadcast, [cd59fefa](https://github.com/dfa1/vortex-java/commit/cd59fefa)), `fastlanes.for` (all integer PTypes, [d7953e1f](https://github.com/dfa1/vortex-java/commit/d7953e1f)), `vortex.alp` (broadcast-without-patches, [deab8067](https://github.com/dfa1/vortex-java/commit/deab8067)), `vortex.constant` (Decimal → `LazyConstantDecimalArray`, [a6a9611e](https://github.com/dfa1/vortex-java/commit/a6a9611e)), `vortex.runend` (Bool → `LazyRunEndBoolArray`, [0bbcb81f](https://github.com/dfa1/vortex-java/commit/0bbcb81f)), `vortex.sparse` (Bool → `LazySparseBoolArray`, [db2e955b](https://github.com/dfa1/vortex-java/commit/db2e955b)), and `fastlanes.rle` (validity → `OffsetBoolArray`, empty → `LazyConstantXxxArray`, [5e83a5c3](https://github.com/dfa1/vortex-java/commit/5e83a5c3)). Decompression encodings (`bitpacked`, `pco`, `zstd`, `fsst`, `delta`, `patched`), the primitive base, the `vortex.dict` encoding-level path, and the `vortex.alp` patches path stay Materialized by design. See [ADR 0015](adr/0015-drop-materialized-fallbacks.md).
 - **Breaking — sealed `Array` permits changed.** `DecimalArray` is now a `non-sealed` family interface (decimal arrays moved from `implements Array` to `implements DecimalArray`), so decimal joins the per-dtype family layer. Downstream exhaustive `switch` over `Array` must add a `case DecimalArray`. ([a6a9611e](https://github.com/dfa1/vortex-java/commit/a6a9611e))
 - **Breaking — `Array` API.** `Array.truncate(rows)` renamed to `Array.limited(rows)` and made an abstract operation implemented by every array (composites slice their children); raw-segment access moved off the `ArraySegments` utility onto `Array.materialize(SegmentAllocator)` and `Array.segmentIfPresent()`. ([87ab65e2](https://github.com/dfa1/vortex-java/commit/87ab65e2), [4d9ac1f8](https://github.com/dfa1/vortex-java/commit/4d9ac1f8), [332b067e](https://github.com/dfa1/vortex-java/commit/332b067e), [32a35e03](https://github.com/dfa1/vortex-java/commit/32a35e03))
 - CSV import reports progress every 10K rows instead of per-chunk. ([07a056e7](https://github.com/dfa1/vortex-java/commit/07a056e7))
@@ -211,7 +211,7 @@ Read and write Vortex Variant (semi-structured, JSON-shaped) columns from Java.
 
 ### Documentation
 
-- [ADR 0016](docs/adr/0016-vortex-arrow-bridge.md): captures `vortex-arrow` bridge interop options (separate module / Arrow C-Data / none); deferred until a concrete downstream need. ([a6126f29](https://github.com/dfa1/vortex-java/commit/a6126f29))
+- [ADR 0016](adr/0016-vortex-arrow-bridge.md): captures `vortex-arrow` bridge interop options (separate module / Arrow C-Data / none); deferred until a concrete downstream need. ([a6126f29](https://github.com/dfa1/vortex-java/commit/a6126f29))
 
 ### Tests
 

TODO.md

@@ -8,10 +8,10 @@
 
 ## Performance
 
-- [ ] **Benchmark publishing** — drop CI workflow, add `bench-publish` script; see [ADR-0006](docs/adr/0006-benchmark-publishing.md).
+- [ ] **Benchmark publishing** — drop CI workflow, add `bench-publish` script; see [ADR-0006](adr/0006-benchmark-publishing.md).
 - [ ] Performance tests must be peer-reviewed
 - [ ] Run performance tests on other machines (I have access only to Apple M5)
-- [ ] **Vector API adoption** — deferred; see [ADR-0005](docs/adr/0005-vector-api-adoption.md) for adoption criteria and candidate loops.
+- [ ] **Vector API adoption** — deferred; see [ADR-0005](adr/0005-vector-api-adoption.md) for adoption criteria and candidate loops.
 
 ## Security
 
@@ -44,7 +44,7 @@ Per-encoding gotchas:
 
 ### Resource caps
 
-- [ ] **Implement `ResourceLimits` + `ReadOptions`** — see [ADR-0004](docs/adr/0004-resource-caps-read-options.md) for design, defaults, and enforcement points. Also covers Pco page/bin caps.
+- [ ] **Implement `ResourceLimits` + `ReadOptions`** — see [ADR-0004](adr/0004-resource-caps-read-options.md) for design, defaults, and enforcement points. Also covers Pco page/bin caps.
 
 ### Fuzz infrastructure
 
@@ -70,23 +70,23 @@ Per-encoding gotchas:
 
 ## Tooling
 
-- [ ] Optional `vortex-arrow` bridge module for Arrow ecosystem interop — see [ADR-0016](docs/adr/0016-vortex-arrow-bridge.md)
+- [ ] Optional `vortex-arrow` bridge module for Arrow ecosystem interop — see [ADR-0016](adr/0016-vortex-arrow-bridge.md)
 
 ## API
 
 - [ ] **Error messages — structural sanitization of `VortexException`** —
   Phase E (bounds typing via `IoBounds`) shipped; remaining is Phases A–D (the `Sanitize`
-  helper + `VortexError` catalog). See [ADR-0003](docs/adr/0003-vortex-exception-sanitization.md)
+  helper + `VortexError` catalog). See [ADR-0003](adr/0003-vortex-exception-sanitization.md)
   for design and phasing.
 - [ ] Use domain primitives (`UInt32`, `UInt64`, etc.) as value classes via Project Valhalla instead of raw `long`/`int`
-    - See [ADR-0008](docs/adr/0008-domain-primitives-unsigned-integers.md) and https://dfa1.github.io/articles/rethink-domain-primitives-with-valhalla
+    - See [ADR-0008](adr/0008-domain-primitives-unsigned-integers.md) and https://dfa1.github.io/articles/rethink-domain-primitives-with-valhalla
     - Candidates: `PType` integer kinds, buffer offsets, row indices, byte lengths
     - Goal: type-safety at zero cost (value class = no heap alloc, no boxing)
 
 ## Compute
 
 - [ ] **Compute primitives — encoded-domain specialization & façade** — the remaining ADR-0013
-  follow-ups now the fused kernels have shipped. See [ADR-0013](docs/adr/0013-compute-primitives.md).
+  follow-ups now the fused kernels have shipped. See [ADR-0013](adr/0013-compute-primitives.md).
   Done: §4 `Predicate`; §5 `RowFilter` unified over `Predicate`; §6 zone-map aggregate push-down in
   both tiers — the whole-zone `ZoneReducer` fold wired into `VortexAggregatePushDownRule` (rewrites a
   whole-table `MIN`/`MAX`/`COUNT`/`SUM`/`AVG` to a single-row `Values`, auto-registered over a bare
@@ -100,7 +100,7 @@ Per-encoding gotchas:
   residual leaves tested per match). Multi-fork numbers: `fusedFilteredSumDict` 762 → 38 ms/op
   ≈ 20×; `fusedFilteredAggregateDict` 983 → 46 ms/op ≈ 22×; `fusedFilteredAggregateMulti`
   (2-leaf `AND` × 2 aggregates) 2269 → 201 ms/op ≈ 11×.
-  Next: the columnar transducer façade — [ADR-0019](docs/adr/0019-columnar-transducer-facade.md)
+  Next: the columnar transducer façade — [ADR-0019](adr/0019-columnar-transducer-facade.md)
   drafted (Proposed): declarative column-bound stages compiled to one fused pass; the remaining
   measured lever is the multi-aggregate single scan (≈ 2×) plus composition ergonomics for the
   Calcite boundary tier; review, then implement.

…dr/0001-split-read-and-write-runtimes.md adr/0001-split-read-and-write-runtimes.mddocs/adr/0001-split-read-and-write-runtimes.md renamed to adr/0001-split-read-and-write-runtimes.md docs/adr/0001-split-read-and-write-runtimes.md renamed to adr/0001-split-read-and-write-runtimes.md

@@ -353,6 +353,6 @@ of CI / integration-test fallout, plus reviewer time. Not a weekend.
 
 - [PR #27 — `sec(parser): BoundedSegment + audit trail for untrusted asSlice`](https://github.com/dfa1/vortex-java/pull/27)
 - [Phase 1–4 commits — BoundedSegment introduction and migration](https://github.com/dfa1/vortex-java/pull/27/commits)
-- [SECURITY.md — the contract this work hardens](../../SECURITY.md)
-- [CLAUDE.md — current "three touch-points" rule for adding an encoding](../../CLAUDE.md)
-- [TODO.md — parser hardening backlog](../../TODO.md)
+- [SECURITY.md — the contract this work hardens](../SECURITY.md)
+- [CLAUDE.md — current "three touch-points" rule for adding an encoding](../CLAUDE.md)
+- [TODO.md — parser hardening backlog](../TODO.md)

…r/0002-pluggable-dtype-layout-compute.md …r/0002-pluggable-dtype-layout-compute.mddocs/adr/0002-pluggable-dtype-layout-compute.md renamed to adr/0002-pluggable-dtype-layout-compute.md docs/adr/0002-pluggable-dtype-layout-compute.md renamed to adr/0002-pluggable-dtype-layout-compute.md

@@ -3,7 +3,7 @@
 - **Status:** Deferred — awaiting a real downstream consumer use case
 - **Date:** 2026-06-11
 - **Deciders:** project maintainer
-- **Related:** [ADR 0001 — Split read and write runtimes](0001-split-read-and-write-runtimes.md), [TODO.md §Audit runtime pluggability vs Rust impl](../../TODO.md)
+- **Related:** [ADR 0001 — Split read and write runtimes](0001-split-read-and-write-runtimes.md), [TODO.md §Audit runtime pluggability vs Rust impl](../TODO.md)
 
 ## Context
 
@@ -197,10 +197,10 @@ Until those four boxes can be ticked, the deferral stands.
 
 ## References
 
-- [TODO.md §"Audit runtime pluggability vs Rust impl"](../../TODO.md)
+- [TODO.md §"Audit runtime pluggability vs Rust impl"](../TODO.md)
   (line ~215, dated 2026-06-04)
 - [ADR 0001 — Split read and write runtimes out of `core`](0001-split-read-and-write-runtimes.md)
-- [docs/compatibility.md — Known wire-format gaps](../compatibility.md)
+- [docs/compatibility.md — Known wire-format gaps](../docs/compatibility.md)
   (notes `DType::Union` as one new variant Java does not yet decode)
 - Rust upstream:
   [`VortexSession`](https://docs.rs/vortex/latest/vortex/session/struct.VortexSession.html)

…dr/0003-vortex-exception-sanitization.md adr/0003-vortex-exception-sanitization.mddocs/adr/0003-vortex-exception-sanitization.md renamed to adr/0003-vortex-exception-sanitization.md docs/adr/0003-vortex-exception-sanitization.md renamed to adr/0003-vortex-exception-sanitization.md

@@ -5,7 +5,7 @@
 - **Deciders:** project maintainer
 - **Related:** [ADR 0001 — Split read and write runtimes](0001-split-read-and-write-runtimes.md),
   [ADR 0004 — Resource caps and `ReadOptions`](0004-resource-caps-read-options.md),
-  [SECURITY.md](../../SECURITY.md)
+  [SECURITY.md](../SECURITY.md)
 
 ## Context
 
@@ -415,7 +415,7 @@ programmatically inspect exception types, this decision can be revisited.
 
 ## References
 
-- [SECURITY.md — injection threat model](../../SECURITY.md)
+- [SECURITY.md — injection threat model](../SECURITY.md)
 - [PR #27 — `BoundedSegment` + audit trail for untrusted `asSlice`](https://github.com/dfa1/vortex-java/pull/27)
 - [ADR 0001 — Split read and write runtimes](0001-split-read-and-write-runtimes.md)
-- [TODO.md §"Error messages — structural sanitization"](../../TODO.md)
+- [TODO.md §"Error messages — structural sanitization"](../TODO.md)

…s/adr/0004-resource-caps-read-options.md adr/0004-resource-caps-read-options.mddocs/adr/0004-resource-caps-read-options.md renamed to adr/0004-resource-caps-read-options.md docs/adr/0004-resource-caps-read-options.md renamed to adr/0004-resource-caps-read-options.md

@@ -3,7 +3,7 @@
 - **Status:** Accepted — implementation pending
 - **Date:** 2026-06-13
 - **Deciders:** project maintainer
-- **Related:** [SECURITY.md](../../SECURITY.md), [TODO.md §Resource caps](../../TODO.md)
+- **Related:** [SECURITY.md](../SECURITY.md), [TODO.md §Resource caps](../TODO.md)
 
 ## Context
 
@@ -167,6 +167,6 @@ a user-facing query limit, not a security cap.
 
 ## References
 
-- [SECURITY.md — zip-bomb and depth-bomb mitigations](../../SECURITY.md)
-- [TODO.md §Resource caps](../../TODO.md)
+- [SECURITY.md — zip-bomb and depth-bomb mitigations](../SECURITY.md)
+- [TODO.md §Resource caps](../TODO.md)
 - [ADR 0003 — VortexException sanitization](0003-vortex-exception-sanitization.md)

docs/adr/0005-vector-api-adoption.md adr/0005-vector-api-adoption.mddocs/adr/0005-vector-api-adoption.md renamed to adr/0005-vector-api-adoption.md

@@ -3,8 +3,8 @@
 - **Status:** Deferred — adoption gated on API finalization + benchmark evidence
 - **Date:** 2026-06-13
 - **Deciders:** project maintainer
-- **Related:** [CLAUDE.md §Memory model — Hot-loop rule](../../CLAUDE.md),
-  [TODO.md §Vector API](../../TODO.md)
+- **Related:** [CLAUDE.md §Memory model — Hot-loop rule](../CLAUDE.md),
+  [TODO.md §Vector API](../TODO.md)
 
 ## Context
 
@@ -150,9 +150,9 @@ loop structure.
 
 ## References
 
-- [CLAUDE.md §Hot-loop rule](../../CLAUDE.md) — the primary vectorization
+- [CLAUDE.md §Hot-loop rule](../CLAUDE.md) — the primary vectorization
   strategy in use today
-- [TODO.md §Vector API items](../../TODO.md)
+- [TODO.md §Vector API items](../TODO.md)
 - JEP 469: Vector API (8th Incubator) —
   https://openjdk.org/jeps/469
 - JMH benchmark harness: `./bench` command, `JavaVsJniReadBenchmark`

docs/adr/0006-benchmark-publishing.md adr/0006-benchmark-publishing.mddocs/adr/0006-benchmark-publishing.md renamed to adr/0006-benchmark-publishing.md

@@ -3,7 +3,7 @@
 - **Status:** Accepted — CI workflow deleted; `bench-publish` script pending
 - **Date:** 2026-06-13
 - **Deciders:** project maintainer
-- **Related:** [TODO.md §Performance](../../TODO.md),
+- **Related:** [TODO.md §Performance](../TODO.md),
   `.github/workflows/benchmark.yml`
 
 ## Context
@@ -156,5 +156,5 @@ longer updated.
   multi-source comparison
 - [benchmark-action/github-action-benchmark](https://github.com/benchmark-action/github-action-benchmark)
   — the tool being retired
-- [TODO.md §Publish benchmarks](../../TODO.md)
-- [TODO.md §Publish reproducible perf artifacts](../../TODO.md)
+- [TODO.md §Publish benchmarks](../TODO.md)
+- [TODO.md §Publish reproducible perf artifacts](../TODO.md)

docs/adr/0007-pco-encode.md adr/0007-pco-encode.mddocs/adr/0007-pco-encode.md renamed to adr/0007-pco-encode.md

@@ -3,7 +3,7 @@
 - **Status:** Proposed
 - **Date:** 2026-06-13
 - **Deciders:** project maintainer
-- **Related:** [TODO.md — domain primitives / Valhalla item](../../TODO.md),
+- **Related:** [TODO.md — domain primitives / Valhalla item](../TODO.md),
   [ADR 0005 — Vector API adoption](0005-vector-api-adoption.md)
 
 ## Context
@@ -20,7 +20,7 @@ as their widened signed counterparts (`int`, `int`, `long`, `long`) with
 no enforcement of the unsigned range and no indication at the call site that
 the value must be treated as unsigned.
 
-The [TODO.md](../../TODO.md) item reads:
+The [TODO.md](../TODO.md) item reads:
 > Use domain primitives (`UInt32`, `UInt64`, etc.) as value classes via
 > Project Valhalla instead of raw `long`/`int`.
 
@@ -155,7 +155,7 @@ additional tooling.
 
 ## References
 
-- [TODO.md — domain primitives / Valhalla item](../../TODO.md)
+- [TODO.md — domain primitives / Valhalla item](../TODO.md)
 - [Rethink Domain Primitives with Valhalla](https://dfa1.github.io/articles/rethink-domain-primitives-with-valhalla)
 - JEP 401: Value Classes and Objects — https://openjdk.org/jeps/401
 - [ADR 0005 — Vector API adoption](0005-vector-api-adoption.md) — analogous