better README

Author: dfa1

README.md

@@ -1,46 +1,16 @@
 # vortex-java
 
-> **Experimental** — not production-ready. APIs will change without notice.
+> **Alpha** — not production-ready. APIs will change without notice.
 
 Pure-Java reader/writer for the [Vortex](https://github.com/spiraldb/vortex) columnar file format.
 
-## Performance
-
-`RustVsJavaReadBenchmark` — 10M OHLC rows, JMH throughput (higher = better), Apple M5 / 32 GB, Java 25:
-
-| Column           | Encoding         | vortex-jni  | vortex-java  | ratio         |
-|------------------|------------------|-------------|--------------|---------------|
-| `volume` (I64)   | primitive        | 51.9 ops/s  | ~115 ops/s   | **Java 2.2×** |
-| `close` (F64)    | ALP (multi-walk) | re-measure  | 62 ops/s     | re-measure    |
-| `symbol` (UTF-8) | dict + FSST      | re-measure  | 7.6 ops/s    | re-measure    |
-
-The `close` and `symbol` numbers regressed from earlier snapshots (118 and 27.8 respectively)
-because commit `347bc34` made the bench data realistic: 30 Nasdaq tickers with independent per-ticker
-price walks instead of a single global walker and a constant symbol. Rust's writer responds by
-picking heavier encodings — `vortex.dict` over `vortex.fsst` for `symbol`, and an ALP sub-encoding
-that no longer fits a single tight reference for `close`. Decode work goes up on both sides;
-JNI numbers above are stale and need re-measurement on the new workload.
-
-Reproduce: `./benchmark.sh RustVsJavaReadBenchmark`. Hardware / JDK build / commit SHA used to produce
-this snapshot should be captured alongside any update (see TODO #10c).
-
-`RustWritesJavaReadsBigFileBenchmark` — 3 GB file, 4 × I64 columns of random data (defeats
-bit-packing so segments stay large), projection on `c0`, JMH throughput:
-
-| Reader      | Throughput     | ms/op | Decode rate |
-|-------------|----------------|-------|-------------|
-| vortex-jni  | 5.9 ops/s      | ~170  | ~4.7 GB/s   |
-| vortex-java | **19.7 ops/s** | ~51   | ~15.7 GB/s — **Java 3.4×** |
-
-Memory-bandwidth bound on Apple M5 / 32 GB. Reproduce: `./benchmark.sh RustWritesJavaReadsBigFileBenchmark`
-(adds a ~30 s fixture build for the JNI write). Pass `-Dvortex.bench.bigfile=<path>` to reuse an existing
-fixture between runs.
-
-All columns decoded faster in pure Java than via JNI + Apache Arrow. Key optimisations:
-`static final` ValueLayout constants (JIT constant-folding), aligned arena allocation
-(`allocate(n, alignment)`), `getAtIndex()`/`setAtIndex()` (clearer stride for the
-auto-vectoriser), and O(1) bytes allocation for constant strings (alternating offsets
-into a single shared byte buffer).
+- ✅ Pure-Java reader for primitive, sequence, ALP, dict, FSST
+- ✅ Local (mmap) or Remote (HTTPS, single read of last 65K)
+- 🚧 Writer (in progress)
+- 🚧 Benchmark against Rust+JNI (in progress)
+- 🚧 Full encoding coverage (in progress)
+- 🚧 Vectorized decode paths (Panama Vector API)
+- ❌ No Iceberg/Spark/Flink integration yet
 
 ## Motivation
 
@@ -56,6 +26,13 @@ reads, making it easier to:
 - build and test on any platform with a standard JDK
 - debug and profile with standard JVM tooling
 
+## Who is this for?
+
+- JVM analytics engines
+- JVM-based OLAP systems
+- Anyone who wants mmap‑backed, zero‑copy columnar reads without first decompressing
+  the whole file (or row chunk)
+
 ### Why fewer layers = faster
 
 ```
@@ -66,10 +43,10 @@ reads, making it easier to:
   │  (BigIntVector.get(i))   │            │  (buffer.getAtIndex) │
   └────────────┬─────────────┘            └──────────┬───────────┘
                │ Arrow Java API                      │ FFM API
-  ┌────────────▼─────────────┐                      │ (MemorySegment,
-  │  Apache Arrow (Java)     │                      │  zero-copy slice)
-  │  VectorSchemaRoot,       │                      │
-  │  BigIntVector, …         │                      │
+  ┌────────────▼─────────────┐                       │ (MemorySegment,
+  │  Apache Arrow (Java)     │                       │  zero-copy slice)
+  │  VectorSchemaRoot,       │                       │
+  │  BigIntVector, …         │                       │
   └────────────┬─────────────┘            ┌──────────▼───────────┐
                │ Arrow C Data Interface   │  OS mmap region      │
                │ (ArrowArray/ArrowSchema) │  (file on disk)      │
@@ -101,28 +78,21 @@ file occupies. Decoding reads bytes directly from that view with no copies, no i
 Arrow format, and no boundary crossings. The JIT sees the full decode path as ordinary Java
 bytecode.
 
-## Why Vortex instead of Parquet
+## Design principles
 
-|                        | Parquet                                | Vortex                             |
-|------------------------|----------------------------------------|------------------------------------|
-| Max column-chunk size  | 2 GB (`int32` page offsets)            | 4 GB per segment (`uint32` length) |
-| Max file offset        | 2 GB (`int32` on some implementations) | 16 EB (`uint64` in footer)         |
-| Encoding extensibility | Fixed codec set                        | Plugin registry, any encoding      |
-
-Files larger than 2 GB are a practical problem with Parquet: the `int32` data-page size field in the page header caps
-individual column chunks at 2 GB.
-Vortex uses `uint64` offsets throughout the footer, and this library maps files with `MemorySegment` (Java FFM API),
-which has no per-mapping size limit — unlike the legacy `FileChannel.map()` API that caps each mapping at 2 GB.
+- Zero-copy as much as possible
+- No JNI
+- No Unsafe -- don't remove safety to gain few %
+- Align with vortex-rust and Vortex-go semantics
+- Make the JIT happy (constant layouts, predictable strides, no virtual dispatch in hot loops)
+- Prepare for the Vector API / Valhalla
 
 ## Prior art and inspiration
 
 | Project                                                     | Language | Notes                                                               |
 |-------------------------------------------------------------|----------|---------------------------------------------------------------------|
 | [spiraldb/vortex](https://github.com/spiraldb/vortex)       | Rust     | Reference implementation + JNI bindings                             |
 | [spiraldb/vortex-go](https://github.com/spiraldb/vortex-go) | Go       | Pure-language port; primary inspiration for this project's approach |
-
-### Further reading
-
 - [FFM vs Unsafe](https://inside.java/2025/06/12/ffm-vs-unsafe/) — Maurizio Cimadamore's deep-dive on why FFM (`MemorySegment`/`Arena`) supersedes `sun.misc.Unsafe`: safety, performance, and the JVM's path forward
 
 ## Serialization formats