test(integration): DocsConsistencyTest — the docs get a compiler

Machine-checks the living docs (CLAUDE.md, README, docs/*.md)
against the codebase: project FQNs must resolve (nested classes via
$ fallback), META-INF/services mentions must name real files,
relative links must not dangle, and backticked Class.method(...)
claims must name real methods — external receivers live on a
conscious allowlist extended in the same diff that cites a new
API. Historical records (adr/, released CHANGELOG sections) are
exempt by policy.

First run caught 11 fossils the same-day MANUAL audit missed, all
fixed here: pre-refactor FQNs in tutorial.md imports, a phantom
io.github.dfa1.vortex.extension package, Registry.* claims from
two renames ago and an ArraySegments API that no longer exists in
compatibility.md, plus Registry/Encoding diagram names and a
"DType blob (Protobuf)" claim in explanation.md. The vortex-
reviewer agent gains a standing stale-docs dimension for the prose
claims a regex cannot check.

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

Author: dfa1

.claude/agents/vortex-reviewer.md

@@ -57,3 +57,11 @@ Group findings by severity: **Blocker** / **Should-fix** / **Nit**. Each finding
 relevant `-pl <mod> -Dtest=...`) and quote real output. End with a verdict: APPROVE or CHANGES
 NEEDED. Be specific and skeptical — your job is to catch what the coder missed, especially wrong-answer
 and memory-safety bugs.
+
+## Standing dimension: stale docs
+
+For every identifier the diff renames, moves, or deletes (classes, methods, packages, service
+files), grep the LIVING docs — `CLAUDE.md`, `README.md`, `docs/*.md` — for remaining mentions.
+A stale mention is a finding (severity: convention). `adr/` and released CHANGELOG sections are
+historical and exempt. `DocsConsistencyTest` (integration) machine-checks FQNs/method claims/
+links, but prose claims about behavior or policy drift too — check those by reading, not grep.

TODO.md

@@ -67,19 +67,13 @@ Per-encoding gotchas:
 ## Build
 
 - [ ] use JPMS, watch out for "dfa1" in package name
-- [ ] **Docs need a compiler** — living prose (CLAUDE.md, `docs/*.md`) drifts from code with no
-  gate (2026-07-04 found: phantom `register(ExtensionDecoder)`, stale "not yet implemented" on
-  MASKED/PATCHED, dead service-file path, stale FQNs after package moves). Tiered plan:
-  1. Markdown link checker in CI (relative links; the `docs/adr` → `adr/` move rewrote ~40 by hand).
-  2. `DocsConsistencyTest` (integration module): extract backticked FQNs / `Class#member` refs /
-     `META-INF/services` paths from living docs, assert existence via reflection. Historical files
-     (`adr/`, released CHANGELOG sections) exempt by policy.
-  3. Golden-test or generate enumerable tables (encodings/extensions/layout ids in
+- [ ] **Docs compiler — remaining tiers** — `DocsConsistencyTest` (integration) now gates FQNs,
+  method claims, service-file paths, and relative links in the living docs (first run caught 11
+  fossils the same-day manual audit missed). Remaining:
+  1. Golden-test or generate enumerable tables (encodings/extensions/layout ids in
      `docs/reference.md`, `docs/compatibility.md`) from `EncodingId.WellKnown`/`LayoutId.WellKnown`/
      service manifests — a declared capability the code lacks is a bug, in both directions.
-  4. Compile ` ```java ` blocks from living docs (defer until 1–3 pay rent).
-  Plus: standing stale-docs dimension in the vortex-reviewer agent (grep living docs for
-  identifiers a diff renames/moves/deletes).
+  2. Compile ` ```java ` blocks from living docs (tutorial imports were stale for months).
 
 ## Tooling
 

docs/compatibility.md

@@ -32,7 +32,7 @@ resolves only the standalone decoders in `reader`; no encoder class is loaded.
 | Item | Introduced | Java status |
 |------|------------|-------------|
 | `DType::Union` (`fbs.DType.Type.Union = 12`) | Rust 0.71.0 | ❌ Decode throws `VortexException("unsupported DType typeType=12")`. No `DType.Union` variant in Java's sealed type. |
-| `vortex.onpair` experimental string encoding | Rust 0.74.0 | ❌ Not registered. Files using it fail to decode unless `Registry.allowUnknown()` is enabled. |
+| `vortex.onpair` experimental string encoding | Rust 0.74.0 | ❌ Not registered. Files using it fail to decode unless `ReadRegistry.builder().allowUnknown()` is enabled. |
 | `vortex.variant` arbitrary nested objects | Rust (`vortex.parquet.variant`) | ⚠️ Java encodes/decodes variant columns of **typed scalar** values (constant / chunked-of-constants core, optional shredded child); Java↔Rust round-trip verified. Arbitrary nested JSON objects and real path-based shredding need the `vortex.parquet.variant` physical encoding — deferred ([ADR 0014](../adr/0014-variant-encoding-strategy.md)). |
 | Arrow extension array import affecting Variant shape | Rust 0.74.0 (#8125) | Untested. Re-run integration fixtures against v0.74.0 once published. |
 | Duplicate struct field names | Rust writer rejects ("StructLayout must have unique field names"); Rust reader tolerates foreign files (first-match access) | ⚠️ Deliberate divergence on read: Java rejects such files with `VortexException("duplicate field name in file schema")` instead of tolerating them — the name-keyed `Chunk` API cannot represent both columns, and silent column loss is worse than a loud failure on a file the reference writer refuses to produce. Java's writer mirrors the Rust writer's rejection. |
@@ -87,7 +87,7 @@ decoder falls into one of three shapes:
 - **Lazy** — output is a `LazyXxxArray` / `ChunkedXxxArray` record that holds the encoded child
   plus the transform parameters. Per-row `getXxx(i)` applies the transform on demand. No
   output buffer is allocated unless a caller explicitly materializes via
-  `ArraySegments.of(arr, arena)`.
+  `Array.materialize(arena)`.
 - **Materialized** — output is a buffer allocated from `ctx.arena()` populated during `decode()`.
   Required for decompression-style encodings (Bitpacked, Pco, Zstd, etc.) where reading element
   `i` would require decoding a window.
@@ -156,21 +156,21 @@ metadata. The Rust catalog lives in
 [`vortex-array/src/extension/`](https://github.com/vortex-data/vortex/tree/develop/vortex-array/src/extension);
 each subdir below names a canonical extension id and its on-disk shape.
 
-Extensions live in `io.github.dfa1.vortex.extension`. Each spec extension is a
-singleton implementing the `Extension` interface, with typed encode/decode
-methods on the concrete impl. Resolve a column to its impl via
-`Registry.lookup(ExtensionId)`, or grab the singleton directly:
+Read-side extensions live in `io.github.dfa1.vortex.reader.extension` (write-side encoders
+implement `ExtensionEncoder` in the writer module). Each spec extension is a singleton
+implementing the `ExtensionDecoder` interface, with typed decode methods on the concrete
+impl — grab the singleton directly:
 
 ```java
 DType.Extension dtype = (DType.Extension) schema.field("birthdays");
-List<LocalDate> values = DateExtension.INSTANCE.decodeAll(chunk.column("birthdays"));
+List<LocalDate> values = DateExtensionDecoder.INSTANCE.decodeAll(chunk.column("birthdays"));
 ```
 
 End-to-end round-trip — write a `List<LocalDate>`, read it back:
 
 ```java
 var schema = DType.structBuilder()
-        .field("birthdays", DateExtension.INSTANCE.dtype(false))
+        .field("birthdays", DateExtensionDecoder.INSTANCE.dtype(false))
         .build();
 writer.writeChunk(c -> c.put("birthdays", dates));              // Collection auto-routed
 
@@ -182,9 +182,8 @@ try (var iter = reader.scan(ScanOptions.all());
 
 `Chunk.as(name, Class)` hides the per-extension decode dispatch for the four
 spec extensions (`LocalDate` ↔ `vortex.date`, `LocalTime` ↔ `vortex.time`,
-`Instant` ↔ `vortex.timestamp`, `UUID` ↔ `vortex.uuid`). Third-party
-extensions still go through `Registry.lookup(ExtensionId)` and the impl's own
-typed methods.
+`Instant` ↔ `vortex.timestamp`, `UUID` ↔ `vortex.uuid`); the dispatch is closed over the
+spec set. Third-party extensions call their own impl's typed methods directly.
 
 `ExtensionId` is the enum of known spec ids (`VORTEX_DATE`, `VORTEX_TIME`,
 `VORTEX_TIMESTAMP`, `VORTEX_UUID`). Unknown wire ids on `DType.Extension`

docs/explanation.md

@@ -68,9 +68,9 @@ Re-measured 2026-06-08 against commit `051a794`.
 
 Two Parquet variants are measured to isolate format cost from API overhead:
 
-- **batch**: `ColumnReader.nextBatch()` + loop over `getDoubles()`/`getInts()` arrays — apples-to-apples with Vortex's
+- **batch**: Hardwood's `ColumnReader.nextBatch()` + loop over `getDoubles()`/`getInts()` arrays — apples-to-apples with Vortex's
   batch fold
-- **row-by-row**: `RowReader.next()` + `getDouble("col")` per row — measures the full row-cursor overhead on top of
+- **row-by-row**: Hardwood's `RowReader.next()` + `getDouble("col")` per row — measures the full row-cursor overhead on top of
   format decode
 
 | Benchmark                                                                | ops/s        | vs Parquet batch         |
@@ -367,8 +367,8 @@ vortexReader.scan(opts) → ScanIterator
 ScanIterator.next() → Chunk (per row-group, AutoCloseable; owns its own Arena)
   └─ decodeLayout(layout, dtype, chunk.arena)
        ├─ Flat   → slice MemorySegment from mmap region
-       │           └─ Registry.decodeSegment(seg, …)
-       │                └─ Encoding.decode(DecodeContext)  →  Array (zero-copy)
+       │           └─ SerializedArrayDecoder.decode(seg, …)
+       │                └─ ReadRegistry → EncodingDecoder.decode(DecodeContext)  →  Array (zero-copy)
        ├─ Chunked → collect Flat children, decode each, concatenate buffers
        ├─ Zoned   → skip zone-map metadata, recurse into child layout
        └─ Dict    → decode values layout + codes layout separately, then expand
@@ -394,21 +394,21 @@ writer.writeChunk(c -> c.put(column, data[]).put(...))
   └─ record Layout node (encoding ID + rowCount + segment index)
 
 writer.close()
-  └─ write DType blob  (Protobuf)
+  └─ write DType blob  (FlatBuffer)
   └─ write Footer blob (FlatBuffer) → SegmentSpec[] + ArraySpec[]
   └─ write Layout blob (FlatBuffer) → Struct → Zoned(Stats) → Chunked → [Flat …]
   └─ write Postscript  (FlatBuffer) → blob offsets + lengths
   └─ write 8-byte trailer           → version · postscriptLen · magic (VTXF)
 ```
 
-### How `Registry` resolves encodings
+### How `ReadRegistry` resolves encodings
 
-`Registry.loadAll()` uses `ServiceLoader` to discover all `Encoding`
-implementations on the classpath. Each encoding declares its ID via `encodingId()`.
-At decode time the registry maps the ID string from the Layout node to the right
-`Encoding` instance and calls `decode(DecodeContext)`.
+`ReadRegistry.loadAll()` uses `ServiceLoader` to discover all `EncodingDecoder`
+implementations on the classpath. Each decoder declares its identity via `encodingId()`.
+At decode time the registry maps the typed id from the array node to the right
+`EncodingDecoder` instance and calls `decode(DecodeContext)`.
 
-Custom encodings can be added at build time: `Registry.builder().register(myEncoding).build()`.
+Custom decoders can be added at build time: `ReadRegistry.builder().registerServiceLoaded().register(myDecoder).build()`.
 Files with unrecognized IDs throw `VortexException` unless the builder enabled `allowUnknown()`.
 
 ## Testing strategy

docs/testing.md

@@ -181,3 +181,16 @@ run-once part and leave the hot, specialized part alone, with a comment saying w
 
 The throughline: let the tools point at the data, then decide with the context they do not
 have.
+
+## Docs consistency gate
+
+`DocsConsistencyTest` (integration module, plain surefire) machine-checks the living docs
+(`CLAUDE.md`, `README.md`, `docs/*.md`) against the codebase: project FQNs must resolve,
+`META-INF/services` mentions must name real files, relative links must not dangle, and
+backticked `Class.method(...)` claims must name real methods (external receivers live on a
+conscious allowlist in the test). Historical records (`adr/`, released CHANGELOG sections)
+are exempt. Run it alone with:
+
+```bash
+./mvnw test -pl integration -am -Dtest=DocsConsistencyTest
+```

docs/tutorial.md

@@ -100,8 +100,8 @@ The file is complete and readable as soon as `VortexWriter` is closed.
 ## 4. Read it back
 
 ```java
-import io.github.dfa1.vortex.io.VortexReader;
-import io.github.dfa1.vortex.scan.ScanOptions;
+import io.github.dfa1.vortex.reader.VortexReader;
+import io.github.dfa1.vortex.reader.ScanOptions;
 import io.github.dfa1.vortex.reader.array.DoubleArray;
 import io.github.dfa1.vortex.reader.array.LongArray;