refactor(scan)!: replace ScanResult with closeable Chunk; ScanIterator implements Iterator<Chunk>

ScanIterator.hasNext() used to silently close the previous chunk's Arena,
invalidating any Array references the caller still held — a footgun the
compiler could not catch. Java has no borrow checker, so Rust-style lending-
iterator semantics cannot be enforced at compile time.

Move to idiomatic Java lifecycle:

- ScanResult → Chunk implements AutoCloseable. Each Chunk owns a confined
  Arena holding its decoded buffers; close() releases the arena.
- ScanIterator now implements Iterator<Chunk>, AutoCloseable. hasNext() is
  side-effect-free; next() returns a fresh Chunk and throws
  IllegalStateException if a prior chunk is still open. Iterator close()
  closes any still-open chunk as a safety net.
- forEachRemaining(Consumer<? super Chunk>) is overridden to wrap each
  next() in try-with-resources, so the standard JDK method works safely
  without inventing a custom forEachChunk.

After Chunk.close(), touching previously-returned Array views raises FFM's
scope check (IllegalStateException) instead of returning undefined data.

Idiomatic call site:

    try (var reader = VortexReader.open(path);
         var iter   = reader.scan(opts)) {
        while (iter.hasNext()) {
            try (Chunk chunk = iter.next()) {
                ...
            }
        }
    }

CLAUDE.md gains a "prefer idiomatic modern Java" rule documenting the
preference for overriding standard JDK methods (forEachRemaining) over
parallel custom names. README, docs/explanation.md, docs/reference.md and
CHANGELOG updated. All call sites (CLI, CSV exporter, benchmarks, all unit
and integration tests) migrated to try-with-resources or forEachRemaining.

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

Author: dfa1

CHANGELOG.md

@@ -9,12 +9,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `Chunk` (`io.github.dfa1.vortex.scan.Chunk`) — replaces `ScanResult`. Each chunk owns
+  a confined `Arena` and implements `AutoCloseable`. The standard
+  `Iterator.forEachRemaining(Consumer<Chunk>)` is overridden on `ScanIterator` to wrap
+  each chunk in try-with-resources, so callers that don't need early-exit get
+  automatic per-chunk cleanup with no new API to learn.
+
 ### Changed
 
+- **Breaking — scan API lifecycle.** `ScanIterator` now implements
+  `Iterator<Chunk>`. `next()` returns a `Chunk` that the caller must close
+  (try-with-resources); `hasNext()` is side-effect-free. Calling `next()` while a
+  prior `Chunk` is still open throws `IllegalStateException`. This removes the
+  previous footgun where `iter.hasNext()` silently closed the previous chunk's
+  arena, invalidating any `Array` references the caller still held. Use after
+  `close()` raises FFM's scope check (`IllegalStateException`) instead of returning
+  undefined data. See the updated examples in `README.md` and
+  `docs/explanation.md#memory-model`.
+
 ### Fixed
 
 ### Removed
 
+- `ScanResult` — renamed to `Chunk` and given lifecycle methods. Update imports:
+  `io.github.dfa1.vortex.scan.ScanResult` → `io.github.dfa1.vortex.scan.Chunk`.
+
 [0.5.0]: https://github.com/dfa1/vortex-java/compare/v0.4.0...main
 
 ## [0.4.0] — 2026-06-07

CLAUDE.md

@@ -180,6 +180,12 @@ Omit a section if empty (e.g. integration module has no production deps; perform
 - Zero SonarQube bugs/smells policy.
 - No `sun.misc.Unsafe` or internal JDK APIs.
 - Prefer explicit over clever. Fail fast on unhandled cases.
+- Always prefer idiomatic modern Java. Reuse the standard library and language
+  features the JDK already provides — e.g. override `Iterator.forEachRemaining`
+  instead of inventing a parallel `forEachChunk`; use `Optional`, records,
+  sealed types, pattern switches, virtual threads, FFM — over hand-rolled
+  equivalents. New APIs should look and feel like JDK APIs Java developers
+  already know.
 - Always use braces for `if`/`else`/`for`/`while` bodies, even single-liners:
   ```java
   // WRONG

README.md

@@ -37,17 +37,22 @@ for zero-copy memory-mapped reads.
 try (VortexReader vf = VortexReader.open(Path.of("data/example.vortex"));
      var iter = vf.scan(ScanOptions.all())) {
     while (iter.hasNext()) {
-        var chunk = iter.next();
-        LongArray ts = chunk.column("timestamp");
-        for (long i = 0; i < ts.length(); i++) {
-            System.out.println(ts.getLong(i));
+        try (Chunk chunk = iter.next()) {
+            LongArray ts = chunk.column("timestamp");
+            for (long i = 0; i < ts.length(); i++) {
+                System.out.println(ts.getLong(i));
+            }
         }
     }
 }
 ```
 
-> **Note:** `iter.hasNext()` closes the previous chunk's arena. Access all column data
-> before calling `hasNext()` again. See [docs/explanation.md#memory-model](docs/explanation.md#memory-model).
+> **Lifecycle.** `ScanIterator` implements `Iterator<Chunk>` and `Chunk` implements
+> `AutoCloseable`. Each chunk owns a confined `Arena`; closing it releases the
+> decoded buffers. Calling `iter.next()` while a prior chunk is still open throws
+> `IllegalStateException`. Use try-with-resources, or
+> `iter.forEachRemaining(c -> ...)` which closes each chunk for you. See
+> [docs/explanation.md#memory-model](docs/explanation.md#memory-model).
 
 For more examples — writing, projection, filtering, custom encodings, and the CLI —
 see the documentation below.

csv/src/main/java/io/github/dfa1/vortex/csv/CsvExporter.java

@@ -15,7 +15,7 @@
 import io.github.dfa1.vortex.io.VortexReader;
 import io.github.dfa1.vortex.scan.ScanIterator;
 import io.github.dfa1.vortex.scan.ScanOptions;
-import io.github.dfa1.vortex.scan.ScanResult;
+import io.github.dfa1.vortex.scan.Chunk;
 
 import java.io.FilterWriter;
 import java.io.IOException;
@@ -83,20 +83,21 @@ private static void export(VortexReader reader, CsvWriter csvWriter, ExportOptio
         String[] row = new String[colCount];
         try (ScanIterator iter = reader.scan(scanOptions)) {
             while (iter.hasNext()) {
-                ScanResult chunk = iter.next();
-                Array[] arrays = new Array[colCount];
-                for (int c = 0; c < colCount; c++) {
-                    arrays[c] = chunk.column(colNames.get(c));
-                }
-                long rowCount = chunk.rowCount();
-                for (long r = 0; r < rowCount; r++) {
-                    if (!predicate.test(chunk, r)) {
-                        continue;
-                    }
+                try (Chunk chunk = iter.next()) {
+                    Array[] arrays = new Array[colCount];
                     for (int c = 0; c < colCount; c++) {
-                        row[c] = cellValue(arrays[c], r);
+                        arrays[c] = chunk.column(colNames.get(c));
+                    }
+                    long rowCount = chunk.rowCount();
+                    for (long r = 0; r < rowCount; r++) {
+                        if (!predicate.test(chunk, r)) {
+                            continue;
+                        }
+                        for (int c = 0; c < colCount; c++) {
+                            row[c] = cellValue(arrays[c], r);
+                        }
+                        csvWriter.writeRecord(row);
                     }
-                    csvWriter.writeRecord(row);
                 }
             }
         }

csv/src/main/java/io/github/dfa1/vortex/csv/RowPredicate.java

@@ -1,15 +1,23 @@
 package io.github.dfa1.vortex.csv;
 
-import io.github.dfa1.vortex.scan.ScanResult;
+import io.github.dfa1.vortex.scan.Chunk;
 
 /// Row-level predicate evaluated against decoded chunk data.
 /// Used in conjunction with zone-map pruning: zone-maps skip whole chunks,
 /// this predicate filters individual rows within surviving chunks.
 @FunctionalInterface
 public interface RowPredicate {
+    /// Returns a predicate that accepts every row.
+    ///
+    /// @return predicate that always returns {@code true}
     static RowPredicate all() {
         return (_, _) -> true;
     }
 
-    boolean test(ScanResult chunk, long rowIndex);
+    /// Tests whether a row should be exported.
+    ///
+    /// @param chunk    decoded chunk containing the row
+    /// @param rowIndex row index within {@code chunk}
+    /// @return {@code true} if the row should be exported
+    boolean test(Chunk chunk, long rowIndex);
 }

csv/src/test/java/io/github/dfa1/vortex/csv/CsvImporterTest.java

@@ -5,9 +5,9 @@
 import io.github.dfa1.vortex.core.array.LongArray;
 import io.github.dfa1.vortex.core.array.VarBinArray;
 import io.github.dfa1.vortex.io.VortexReader;
+import io.github.dfa1.vortex.scan.Chunk;
 import io.github.dfa1.vortex.scan.ScanIterator;
 import io.github.dfa1.vortex.scan.ScanOptions;
-import io.github.dfa1.vortex.scan.ScanResult;
 import io.github.dfa1.vortex.writer.WriteOptions;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.io.TempDir;
@@ -41,14 +41,15 @@ void infersTypedColumnsAndRoundTrips(@TempDir Path tmp) throws Exception {
 
             try (ScanIterator iter = reader.scan(ScanOptions.all())) {
                 assertThat(iter.hasNext()).isTrue();
-                ScanResult chunk = iter.next();
-                assertThat(chunk.rowCount()).isEqualTo(2);
-                LongArray ids = chunk.column("id");
-                assertThat(ids.getLong(0)).isEqualTo(1L);
-                assertThat(ids.getLong(1)).isEqualTo(2L);
-                VarBinArray names = chunk.column("name");
-                assertThat(names.getString(0)).isEqualTo("Alice");
-                assertThat(names.getString(1)).isEqualTo("Bob");
+                try (Chunk chunk = iter.next()) {
+                    assertThat(chunk.rowCount()).isEqualTo(2);
+                    LongArray ids = chunk.column("id");
+                    assertThat(ids.getLong(0)).isEqualTo(1L);
+                    assertThat(ids.getLong(1)).isEqualTo(2L);
+                    VarBinArray names = chunk.column("name");
+                    assertThat(names.getString(0)).isEqualTo("Alice");
+                    assertThat(names.getString(1)).isEqualTo("Bob");
+                }
             }
         }
     }
@@ -107,9 +108,10 @@ void respectsSchemaOverride(@TempDir Path tmp) throws Exception {
             assertThat(schema.fieldTypes().getFirst()).isEqualTo(new DType.Utf8(false));
             try (ScanIterator iter = reader.scan(ScanOptions.all())) {
                 assertThat(iter.hasNext()).isTrue();
-                ScanResult chunk = iter.next();
-                VarBinArray values = chunk.column("value");
-                assertThat(values.getString(0)).isEqualTo("42");
+                try (Chunk chunk = iter.next()) {
+                    VarBinArray values = chunk.column("value");
+                    assertThat(values.getString(0)).isEqualTo("42");
+                }
             }
         }
     }

docs/explanation.md

@@ -132,11 +132,40 @@ and the chunk-0 stats child — the tree collapses to `Struct → Chunked → [F
 ## Memory model
 
 `VortexReader` memory-maps the entire file into one `MemorySegment` (confined `Arena`).
-All `Array` buffers returned during a scan are zero-copy slices of that segment — their
-lifetime is tied to the `VortexReader`. Close the reader to release the mapped region.
+Decoded `Array` buffers returned during a scan are zero-copy slices of that segment —
+or of a per-chunk arena allocated for decode output. Close the reader to release
+the mapped region.
+
+### Per-chunk lifetime: `Chunk implements AutoCloseable`
+
+`ScanIterator` implements `Iterator<Chunk>`. Each `Chunk` owns a confined `Arena`
+that holds its decoded columnar buffers; calling `chunk.close()` releases the arena.
+The idiomatic pattern is nested try-with-resources:
+
+```java
+try (var reader = VortexReader.open(path);
+     var iter   = reader.scan(opts)) {           // releases iterator state
+    while (iter.hasNext()) {
+        try (Chunk chunk = iter.next()) {        // releases this chunk's arena
+            // use chunk.column(...) — refs are valid only inside this block
+        }
+    }
+}
+```
+
+Calling `iter.next()` while a previous chunk is still open throws
+`IllegalStateException` — the API refuses to silently invalidate live references.
+After `chunk.close()`, touching any previously-returned `Array` raises FFM's scope
+check (`IllegalStateException` from `MemorySegment`), not undefined behavior.
 
-The iterator-based scan API is load-bearing: `iter.hasNext()` closes the previous chunk's
-arena. Access all column data before calling `hasNext()` again.
+For bulk consumption with auto-close per element, override the standard
+`Iterator.forEachRemaining` is provided:
+
+```java
+try (var iter = reader.scan(opts)) {
+    iter.forEachRemaining(c -> sum += c.column("price").fold(0.0, Double::sum));
+}
+```
 
 For the reader / scan method signatures, see [reference.md#reader-api](reference.md#reader-api).
 
@@ -250,8 +279,8 @@ VortexReader.open(path)
 vortexReader.scan(opts) → ScanIterator
   └─ pre-index Flat nodes into ChunkSpec[] — one entry per row group per column
 
-ScanIterator.next() → ScanResult (per row-group)
-  └─ decodeLayout(layout, dtype, chunkArena)
+ScanIterator.next() → Chunk (per row-group, AutoCloseable; owns its own Arena)
+  └─ decodeLayout(layout, dtype, chunk.arena)
        ├─ Flat   → slice MemorySegment from mmap region
        │           └─ EncodingRegistry.decodeSegment(seg, …)
        │                └─ Encoding.decode(DecodeContext)  →  Array (zero-copy)
@@ -260,8 +289,9 @@ ScanIterator.next() → ScanResult (per row-group)
        └─ Dict    → decode values layout + codes layout separately, then expand
 ```
 
-All `Array` buffers are zero-copy slices of the mmap'd `MemorySegment`.
-Advancing the iterator (`hasNext()`) closes the chunk's `Arena` and releases them.
+Decoded `Array` buffers are either zero-copy slices of the mmap'd `MemorySegment`
+or allocations in the chunk's own `Arena`. `chunk.close()` releases that arena —
+after which any reference into it raises FFM's scope check.
 
 ### Write path
 

docs/reference.md

@@ -130,23 +130,29 @@ Sealed predicate used for zone-map pruning (per-chunk min/max). Chunks that cann
 
 ### `ScanIterator` (`io.github.dfa1.vortex.scan.ScanIterator`)
 
-Implements `AutoCloseable`. Drives one scan.
+Implements `Iterator<Chunk>` and `AutoCloseable`. Drives one scan.
 
-| Method      | Notes                                                                |
-|-------------|----------------------------------------------------------------------|
-| `hasNext()` | **Closes the previous chunk's arena.** Access all column data first. |
-| `next()`    | Returns `ScanResult`                                                 |
-| `close()`   | Releases iterator state                                              |
+| Method                 | Notes                                                                                |
+|------------------------|--------------------------------------------------------------------------------------|
+| `hasNext()`            | Side-effect-free. Returns whether another chunk is available after zone-map pruning. |
+| `next()`               | Returns a fresh `Chunk` whose arena the caller closes. Throws `IllegalStateException` if a prior `Chunk` is still open, or `NoSuchElementException` if exhausted. |
+| `forEachRemaining(Consumer)` | Overridden to wrap each `next()` in try-with-resources so chunks auto-close.   |
+| `close()`              | Releases iterator state and closes any chunk still open.                             |
 
-### `ScanResult` (`io.github.dfa1.vortex.scan.ScanResult`)
+### `Chunk` (`io.github.dfa1.vortex.scan.Chunk`)
 
-Record: `(long rowCount, Map<String, Array> columns)`.
+Implements `AutoCloseable`. Each chunk owns a confined `Arena` holding the decoded
+columnar buffers; closing the chunk releases the arena. After `close()`, touching
+any `Array` previously returned by `column(...)` or `columns()` raises FFM's scope
+check (`IllegalStateException`).
 
 | Method                                  | Notes                                                    |
 |-----------------------------------------|----------------------------------------------------------|
 | `rowCount()`                            | Rows in this chunk                                       |
 | `columns()`                             | All columns in this chunk                                |
 | `<T extends Array> column(String name)` | Typed column lookup; throws `VortexException` if unknown |
+| `isClosed()`                            | Whether `close()` has run                                |
+| `close()`                               | Releases the chunk's arena. Idempotent.                  |
 
 ---