turndb 0.2.0

A content-addressed columnar store for AI traces: byte-exact, embedded, and readable by the CLI and npm from the same file.
Documentation
# Browser read path

Phase 3b ships a read-only `wasm32-unknown-unknown` core and a one-file viewer. The Rust engine
opens the ordinary container over `Arc<dyn ReadAt>`; buffer, Blob/File, and HTTP Range therefore
share the same superblock, member-directory, part, fold, visibility, cursor, and scalar code as a
native read view.

The JavaScript transport maintains a bounded 64 KiB-block LRU. A synchronous wasm read that misses
returns `TURNDB_RANGE:<offset>:<length>`; JavaScript fetches the intersecting blocks and retries the
operation. HTTP requires exact `206 Content-Range` responses and refuses a `200` whole-file
fallback. One core-admitted atomic read larger than the LRU is held as a transient exact range
across retries and released when that operation completes; it can therefore make progress without
turning the cache into an unbounded whole-file fallback. Every operation accepts an `AbortSignal`
between fills. The profile truthfully reports
`threads: false`, `writerExclusion: read_only`, and no lifecycle operations.

Structured scans prune a candidate row from part-wide metadata before opening selected value
sections when a typed predicate is impossible: numeric/timestamp/bool zone maps, string
dictionaries, and positive field-presence facts. Unknown metadata, NaN zones, absence
predicates, and every malformed advisory fact widen to “may match.” `predicatePrunedRows` is the
exact count avoided.

## SQL decision

The first viewer is structured-scan only. The columnar core compiles for
`wasm32-unknown-unknown`. DataFusion 54 does not compile under TurnDB's current feature graph:
without configuration, getrandom 0.3 refuses the target; with `getrandom_backend="wasm_js"`, that
dependency also needs a feature enabled by an upstream owner, and Tokio rejects the
`rt-multi-thread` feature on wasm. These are measured build blockers, not an API fork. The viewer
labels SQL unavailable and the browser capability profile reports `sql: false`, `arrowIpc: false`.

## Measured range behavior

[`browser-read-measurement.json`](browser-read-measurement.json) is generated by:

```sh
cargo build -p turndb-node --release
TURNDB_NATIVE_PATH=target/release/libturndb_node.so node bindings/browser/measure.mjs \
  > docs/browser-read-measurement.json
```

It creates 56 deterministic 52 MiB one-element JSON arrays (3,053,453,312 logical content bytes),
producing a 2,290,602,394-byte container. It opens that container through an exact in-memory
HTTP-206 oracle and runs a metadata-only point query for its final id. Cold open made 5 range
requests and fetched 250,267 bytes: 0.0109% of the 2.13 GiB file. The point query was then answered
entirely from those cached metadata blocks — 0 more requests and 0 more network bytes. The report
keeps the phases separate and also records their combined total; these are transport measurements,
not network-latency benchmarks.

The core contract underneath that measurement is independent of the 64 KiB HTTP cache:
[`FORMAT.md`](../FORMAT.md#parts) states the range-readable part layout, and the
container suite executes it over a multi-part, multi-segment store while proving that cold open
touches no fold block payload. The AES-CTR/base64url payload generator is deterministic, while the
JSON-array shape exercises the structural carving used by large trace payloads instead of
manufacturing a binary-CDC metadata worst case.

The self-contained artifact is [`bindings/browser/turndb-viewer.html`](../bindings/browser/turndb-viewer.html).
CI rebuilds it byte-for-byte and opens the checked physical fixture in stock Chromium and Firefox,
both as a local file with zero network requests and from a static HTTP server with real 206 ranges.