@clickhouse/client 1.22.0 → 1.23.0-head.70ad405.1

package/skills/clickhouse-js-node-rowbinary/README.md

@@ -0,0 +1,319 @@
+# ClickHouse Node.js RowBinary Codec Generator
+
+**If JS had a -O3 compiler flag, this skill would be it.** (for RowBinary read & write)
+
+A skill and a library that lets a coding agent generate bespoke RowBinary codecs on the first pass from the column type definitions of a ClickHouse response. The [spirit](#the-spirit) behind the approach.
+
+**Reads and writes.** Both directions are covered: readers (decode bytes → values) and writers (encode values → bytes), split under `src/readers/` and `src/writers/`. The reader path is the more mature one — the writers mirror it type-for-type, with a few decode-only paths (`Dynamic`, `JSON`, the runtime header/compile path, and the columnar typed-array path) not yet mirrored.
+
+## Status
+
+- ✅ Sonnet 4.6: 60% -> 94.0% pass rate
+- ✅ Opus 4.8: 71% -> 94.7% pass rate
+- ✅ Haiku 4.5: 52% -> 86.0% pass rate
+- ✅ Composer 2.5 Fast: 3x parser performance
+- ✅ 724/724 tests (readers + writers)
+- ✅ type-checked
+- ✅ benchmarked
+
+## Example
+
+Take a small orders result:
+
+```sql
+SELECT id, uid, price, status FROM orders
+--  id     UInt8
+--  uid    UUID
+--  price  Decimal64(2)
+--  status Enum8('new' = 1, 'shipped' = 2, 'done' = 3)
+```
+
+**The API-only reader** — what you write by composing the library's combinators. Correct, clear, and a fine default:
+
+```ts
+const readOrderRow: Reader<OrderRow> = (s) => ({
+  id: readUInt8(s),
+  uid: formatUUID(readUUID(s)),
+  price: readDecimal64(2)(s),
+  status: readInt8(s), // raw enum int; `readEnum8(map)` resolves it to the name
+});
+```
+
+**The optimized reader the skill generates** — same row, monomorphized to
+straight-line code. The whole row is fixed-width (1 + 16 + 8 + 1 = 26 bytes), so
+the four separate bounds checks coalesce into one `advance(s, 26)` and every leaf
+read happens at a constant offset; the per-field combinators are gone:
+
+```ts
+const readOrderRowFast: Reader<OrderRow> = (s) => {
+  const { buf, view } = s;
+  const o = advance(s, 26); // one bounds check for the whole 26-byte row
+  const id = buf[o]!;
+  const uid = formatUUIDTable(buf.subarray(o + 1, o + 17));
+  const price: DecimalValue = [view.getBigInt64(o + 17, true), 2];
+  const status = view.getInt8(o + 25);
+  return { id, uid, price, status };
+};
+```
+
+Same values, same streaming-safety — **~3.4x** faster.
+
+## How to use
+
+As a library (comes with the skill):
+
+```bash
+npm install @clickhouse/rowbinary
+npx skills-npm setup
+```
+
+As a skill only:
+
+```bash
+npx skills add ClickHouse/clickhouse-js/skills/clickhouse-js-node-rowbinary
+```
+
+```console
+> Hey, Claude, tell me what the rowbinary skill can do for me.
+> A lot! It generates custom, high-performance RowBinary readers and writers…
+> Super, generate a reader for the queries in app/src/model.ts.
+< Reading skill clickhouse-js-node-rowbinary…
+```
+
+## Using it with the ClickHouse JS client
+
+This library only **decodes** the bytes — it doesn't open connections. Pair it
+with the official client to fetch a `RowBinary` response and feed the byte chunks
+into `streamRowBatches(chunks, readRow)`.
+
+`RowBinary` isn't one of the formats the client decodes itself, so don't use
+`client.query({ format: ... })` for it. Instead use `client.exec({ query })` with
+the `FORMAT RowBinary` clause written into the SQL yourself — `exec` hands back the
+**raw, undecoded byte stream** of the response, which is exactly what this library
+consumes. (Use plain `RowBinary`, not `RowBinaryWithNamesAndTypes`, unless your
+reader also skips the leading names/types header.)
+
+The row reader below is the `orders` example from [EXAMPLES.md](EXAMPLES.md); swap
+in the reader the skill generates for your own columns.
+
+```ts
+import {
+  type Reader,
+  readUInt8,
+  readInt8,
+  readUUID,
+  formatUUID,
+  readDecimal64,
+  type DecimalValue,
+  streamRowBatches,
+} from "@clickhouse/rowbinary";
+import { createClient } from "@clickhouse/client";
+
+type OrderRow = {
+  id: number;
+  uid: string;
+  price: DecimalValue;
+  status: number;
+};
+
+const readOrderRow: Reader<OrderRow> = (s) => ({
+  id: readUInt8(s),
+  uid: formatUUID(readUUID(s)),
+  price: readDecimal64(2)(s),
+  status: readInt8(s), // raw enum int; `readEnum8(map)` resolves it to the name
+});
+
+// `exec` resolves to a Node `Stream.Readable`. It is already an
+// `AsyncIterable<Uint8Array>` (chunks are `Buffer`/`Uint8Array`, which
+// `streamRowBatches` normalizes), so pass `stream` straight in:
+
+const client = createClient();
+
+const { stream } = await client.exec({
+  query: "SELECT id, uid, price, status FROM orders FORMAT RowBinary",
+});
+
+for await (const rows of streamRowBatches(stream, readOrderRow)) {
+  for (const row of rows) console.log(row); // { id, uid, price: [unscaled, scale], status }
+}
+
+await client.close();
+```
+
+## Why it's worth it
+
+Four pillars — speed, correctness, judgment, and lifting smaller models:
+
+- **~2–3x faster code than the straightforward decoder.** The skill emits
+  monomorphized, flattened, straight-line code — inlined reads, bounds checks
+  coalesced across adjacent fixed-width columns, the right array layout — measured
+  at ~1.3–3.4x over the _same logic written with the plain combinator API_
+  (`npm run bench`). This is why
+  - inlined JIT friendly code
+  - benchmarked hot paths
+  - minimal allocations
+  - v8 and Node.js specific optimizations
+- **Correct on the gotchas that otherwise quietly break.** UUID byte
+  order, `Variant`'s sort-by-type-name discriminant, `DateTime64` sub-second
+  precision, signed-high-word wide integers, faithful decimals, `Dynamic`/`JSON`
+  self-description, transparent wrappers, opaque `AggregateFunction` — each
+  encoded with a live, server-verified test ([details below](#correctness-on-the-gotcha-heavy-types)).
+- **Judgment, not just code.** The skill carries the working knowledge to make
+  the right call _before_ writing a line, so the agent neither over- nor
+  under-engineers:
+  - **Is RowBinary even right?** For string-heavy results read as text, a `JSON*`
+    format + V8's native `JSON.parse` (plus `gzip`/`zstd`) can beat a JS RowBinary
+    decoder — reach for RowBinary when the data is numeric / wide-integer /
+    binary-blob heavy.
+  - **Whole buffer or stream?** Drop the `advance()` bounds checks for a complete
+    in-memory buffer (faster); keep them for a chunked HTTP response that must
+    survive rows straddling chunk boundaries.
+  - **Drop the portability scaffolding.** RowBinary is little-endian and the
+    target is x86/ARM, so the skill steers away from big-endian / byte-swap
+    "portability" code a cautious one-shot pass tends to add.
+- **Improves smaller models' performance.** Because the skill hands over the
+  hard-won answers up front, it lifts a weaker model the most. In a 24-eval
+  with-skill vs no-skill benchmark, the skill [raised](eval_result_sonnet.md) **Sonnet 4.6** from 60.4% to
+  **94.0%** (+34pp) — bringing it level with skill-equipped **Opus 4.8** (94.7%),
+  which itself [gained](eval_result.md) +23pp (71.5% → 94.7%). Composer 2.5 Fast
+  [got](eval_result_composer.md) a 3x parser performance boost, Haiku 4.5
+  [raised](eval_result_haiku.md) from 52% to 86% — the skill closes
+  most of the model-capability gap on this task.
+
+## What it does
+
+Given the columns of a query result — their names and ClickHouse type
+definitions (as returned by `RowBinaryWithNamesAndTypes`, or supplied by the
+user) — the skill generates parser code tailored to exactly those types. Rather
+than shipping a generic, runtime-driven decoder, it emits straight-line code
+that reads each column in order, so the parser only contains the logic the
+specific result shape needs.
+
+**Schema only known at runtime?** `compileRowBinaryWithNamesAndTypes(cursor)`
+reads the `RowBinaryWithNamesAndTypes` header and folds each column type into a
+reader on the fly (type strings parsed by `@clickhouse/datatype-parser`),
+returning a `readRows` driver for the rest of the stream — a generic, no-codegen
+path for dynamic schemas. The specialized codegen above stays the fast path when
+the types are fixed.
+
+## Correctness on the gotcha-heavy types
+
+For a plain `UInt64, String, DateTime` result a strong model already writes fast,
+correct code on its own. The skill earns its keep on the **long tail of RowBinary
+traps** — the encodings where a from-scratch decoder is quietly wrong — each one
+captured here with a live, server-verified test:
+
+- **UUID** — two little-endian `UInt64` halves, each byte-reversed vs. the text
+  form (not 16 bytes in order).
+- **`Variant(...)`** — the 1-byte discriminant indexes the alternatives sorted by
+  **type name** (ClickHouse globally sorts them), NOT declaration order; `0xFF`
+  is NULL.
+- **`DateTime64(P)`** — returned as `[Date, nanoseconds]` so the sub-second part
+  isn't lost to a `Date`'s millisecond resolution; `Time`/`Time64` are durations,
+  not instants.
+- **Wide integers** — `Int128`/`Int256` compose from 64-bit words with the **high
+  word read signed**; 64-bit values stay `bigint`, never a lossy `number`.
+- **Decimals** — kept as the exact `[unscaled, scale]` pair, not a lossy float.
+- **`Dynamic` / `JSON`** — self-describing: a per-value binary type encoding, then
+  the value; declared typed `JSON` paths are written without a tag (need the
+  schema). Wrappers are erased (`Nullable`/`Variant` → concrete type).
+- **Transparent wrappers** — `LowCardinality(T)` / `SimpleAggregateFunction(f, T)`
+  decode as the inner `T` (no dictionary layer in RowBinary); `Nested(...)` is
+  `Array(Tuple(...))` with no wire of its own.
+- **`AggregateFunction(...)`** — opaque, unframed state: not decodable or even
+  skippable; finalize server-side instead.
+- **`FixedString`** preserves trailing NUL padding; **`Enum`** decodes to the
+  underlying int (the name map is metadata); **`BFloat16`** is the top 16 bits of
+  a `Float32`.
+
+This is also where a raw model is most likely to go wrong. In a clean-room test
+on a `Variant` / `UUID` / `DateTime64` / `LowCardinality` schema, a no-skill
+Sonnet produced a **silently wrong UUID** (treated the bytes as plain, missing
+the two-reversed-halves layout), and a no-skill Opus got it right only after
+**three web searches**. The skill hands over these answers up front — correct by
+construction, no lookups. See `baseline/README.md` for the full control.
+
+And the failure isn't a one-off — it's a coin-flip. Running the same no-skill
+Sonnet on the `orders` schema (`UInt8, UUID, Decimal64(2), Enum8`) **5 times in
+isolation**, only **3 of 5** runs decoded correctly; both failures were the same
+UUID byte-order scramble. Even the passing runs varied ~1.9x in generated-code
+throughput. With the skill, every run is correct. So a single A/B undersells the
+gap: from scratch the model is right roughly 60% of the time and silently wrong
+the rest, while the skill makes correctness deterministic.
+
+## Examples
+
+Six end-to-end examples live in [EXAMPLES.md](EXAMPLES.md). Each ships both an API-combinator
+reader and an optimized, monomorphized one, with a runnable round-trip test and
+a benchmark — so the speedups below are measured, not claimed (Node 24 / V8;
+`npm run bench` for your own numbers):
+
+| Example           | Columns                                              | Optimized speedup   |
+| ----------------- | ---------------------------------------------------- | ------------------- |
+| **orders**        | `UUID`, `Decimal64`, `Enum8`                         | **~3.4x**           |
+| **carts**         | nested `Array(Tuple(...))`, `Array(Nullable(...))`   | **~2.0x**           |
+| **telemetry**     | `Map`, `Array(Float64)`, `Nullable`, named `Tuple`   | **~1.4x**           |
+| **observability** | `Variant`, `DateTime64(3)`, `LowCardinality`, nested | **~1.4x**           |
+| **profiles**      | `Array(String)`, `Nullable(Int32)`                   | **~1.3x**           |
+| **events**        | `UInt64`, `String`, `DateTime` scalars               | **~1.05x — on par** |
+
+Two axes drive the win. **Composite structure** is one: monomorphization pays in
+proportion to how many per-row combinator closures it removes (`carts` /
+`telemetry` / `observability`). **Per-row formatting** is the other, independent
+of composites: `orders` is all-scalar yet the biggest win (~3.4x), almost
+entirely from swapping the BigInt UUID formatter for the lookup-table
+`formatUUIDTable`. The genuinely flat case — a scalar row with no hot formatter
+(`events`) — is on par, so the simpler API reader is the right call there.
+Measure, don't assume.
+
+## Scope
+
+- **In scope (reading):** `RowBinary`, `RowBinaryWithNames`, and
+  `RowBinaryWithNamesAndTypes` decoding for Node.js — full-buffer and streaming
+  (chunked) via `advance()`/`NeedMoreData`, `readRows()`, and the async
+  `streamRowBatches()` (with a built-in small-chunk warning and the optional
+  `coalesceChunks()` debounce filter).
+- **In scope (writing):** the inverse encode path — a `writeX` mirroring every
+  `readX`, appending bytes to a `Sink`, plus `writeRows()`. Imported from
+  `@clickhouse/rowbinary/writer`. A handful of decode-only paths are not yet
+  mirrored: `Dynamic`, `JSON`, the runtime header/compile path, and the columnar
+  typed-array path.
+- **Out of scope (for now):** browsers and Edge runtimes, non-RowBinary formats
+  (JSON / CSV / TSV / Parquet), and big-endian hosts.
+
+## The spirit
+
+A RowBinary codec generator is a narrow thing. But it's built as an instance of
+a broader bet about what libraries become once a capable LLM is part of the
+toolchain. Three shifts, each already visible in this repo:
+
+- **Self-modifiable software.** The library deliberately ships _several_
+  equivalent decoders for the same type — `readUUID` / `readUUIDBigInt` /
+  `readUUIDHiLo`, `formatUUID` / `formatUUIDTable`, `new Array(n)` vs `[]`+push,
+  streaming vs whole-buffer — because the fastest one depends on the workload,
+  not the type. Today the agent picks at generation time from measured
+  benchmarks. The next step is to pair the skill with a tracing layer that runs
+  variant A against variant B _on the live workload_ and keeps whichever wins for
+  this data shape and access pattern — a parser that re-tunes itself as the
+  traffic drifts, instead of freezing one author's guess into a release.
+
+- **Custom software.** The value here isn't a fixed high-level API; it's the
+  benchmarked building blocks plus the judgment to combine them. So the end user
+  doesn't bend their code to the authors' generic surface — they have the agent
+  assemble the high-level API _they_ actually want, shaped to their queries, row
+  shapes, and latency/memory budget. Two teams with different workloads grow two
+  different libraries from the same primitives, and neither inherits a design
+  decision that was only ever right for the original authors' use case.
+
+- **Read-write libraries.** For either of the above to be safe, the source has to
+  be legible to an LLM, not merely runnable. So this repo is written _read-write_:
+  every tradeoff is commented where it's made — the per-column ClickHouse type
+  annotations, the `SAFE TO TOGGLE` markers on the fast variants, each reader's
+  doc comment carrying its exact monomorphized form. An LLM can
+  read _why_ a decision was made and change it in depth with confidence — not
+  just call the public functions, but safely rework the internals.
+
+The through-line: the last mile is glue the LLM writes over stable, benchmarked
+blocks, so the authors' job shrinks to exporting good primitives and documenting
+their tradeoffs honestly — rather than trying to bake the right performance
+constants for every possible workload into the library ahead of time.

package/skills/clickhouse-js-node-rowbinary/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: clickhouse-js-node-rowbinary
+description: >
+  Generate TypeScript/JavaScript code that reads/decodes AND writes/encodes
+  ClickHouse RowBinary streams for the ClickHouse HTTP server.
+  Use this skill whenever a user wants to parse or produce `RowBinary`,
+  `RowBinaryWithNames`, or `RowBinaryWithNamesAndTypes`.
+  Node.js only, doesn't cover browsers.
+---
+
+# ClickHouse JS RowBinary Codec Generator for Node.js
+
+This skill generates both directions of the wire format: **readers** (decode
+bytes → values) and **writers** (encode values → bytes, the mirror). A given
+task normally needs only one side. This file is the shared entry point — the
+format gate plus the principles common to both directions; the per-direction
+decisions, guidance, and the per-type reference tables live in two sibling files.
+
+**Pick your side — read only the one you need:**
+
+- **Decoding a `RowBinary*` response** from ClickHouse into JS values →
+  **[reader.md](reader.md)**. Streaming vs whole-buffer, row-objects vs columnar,
+  fixed vs runtime schema, and the per-type reader reference.
+- **Encoding JS values into a `RowBinary` payload** to send to ClickHouse →
+  **[writer.md](writer.md)**. The `Sink`/`writeX` building blocks, `writeRows`
+  streaming, and the per-type writer reference.
+
+The per-type code is real, split by direction under `src/readers/` and
+`src/writers/`.
+
+## First: is RowBinary even the right format?
+
+RowBinary exists for throughput, but it is **not automatically the fastest
+path** — match the format to the shape of the data before committing to a
+bespoke parser.
+
+**Prefer a `JSON*` format (e.g. `JSONEachRow`) when** the result is mostly
+strings / JSON-like values that you consume wholesale — randomly accessing
+essentially every field, running string/regexp methods on them, treating values
+as text. V8's native `JSON.parse` is heavily optimized C++ and builds JS strings
+and objects faster than a JS-level RowBinary decoder can; pair it with HTTP
+response compression (`gzip` / `zstd`, which crushes JSON's repetitive keys) and
+the wire cost shrinks too.
+
+**RowBinary clearly wins when** the result is dominated by:
+
+- **Wide numerics** — `Int128`/`Int256`/`UInt128`/`UInt256`,
+  `Decimal128`/`Decimal256`.
+- **Binary / fixed-width blobs** — `IPv4`, `IPv6`, `UUID`, `FixedString`.
+- **High-volume fixed-width numeric columns** generally, where each value is a
+  single `DataView` read.
+
+**Prefer the `Native` format when** columnar load and client-side analytics are
+the main goal (fold/scan/filter columns, feed typed arrays to a Worker or WASM).
+`Native` is column-major, so it loads straight into one typed array per column
+with no transpose.
+
+For help choosing and consuming a `JSON*` format (or CSV / TSV) instead, use the
+**`clickhouse-js-node-coding`** skill.
+
+## Core guidance (both directions)
+
+These principles apply whether you are generating a reader or a writer; the
+side-specific operational guidance is in [reader.md](reader.md) /
+[writer.md](writer.md).
+
+- **Little-endian only.** RowBinary is little-endian; target x86/ARM. Read and
+  write every multi-byte number with `DataView` accessors passing a **literal**
+  `true` for the `littleEndian` flag.
+
+- **Correct first, then optimize.** First emit a correct codec built from the
+  plain per-type API. Only after it's correct (and tested) specialize it. Don't
+  bake performance assumptions in before correctness.
+
+- **Monomorphize generic/composite types.** Emit specialized, inlined code per
+  type combination instead of passing functions as arguments where the type is
+  known ahead of time.
+
+- **Inline the leaf ops.** The per-type `readX`/`writeX` functions are the
+  correct, composable reference; the generated codec should INLINE their bodies,
+  not call them, so the row loop is straight-line with no per-field indirection
+  (and so the fixed-width coalescing can fold the offset arithmetic together).
+
+- **Annotate the type per column.** Inlining erases the type structure, so put a
+  short comment above each column's encode/decode block naming the ClickHouse
+  type it handles.
+
+- **Shared scratch is not reentrant.** Some hot methods reuse a module-level
+  scratch buffer as a write-then-read pair — correct only because the access is
+  fully synchronous. An `async`/`yield` boundary between populating and reading
+  it corrupts the value.
+
+- **TypeScript by default.** Generate TypeScript code and helpers unless the user
+  explicitly asks for plain JavaScript.
+
+## Worked examples
+
+Six end-to-end examples with real speedup are catalogued in [EXAMPLES.md](EXAMPLES.md).
+
+## Out of scope
+
+- **JSON / CSV / TSV / Parquet parsing** → use `clickhouse-js-node-coding`.
+- **Connection errors, hangs, type mismatches** → use
+  `clickhouse-js-node-troubleshooting`.
+- **Browser / Web Worker / Edge** → `@clickhouse/client-web`.
+
+## Still Stuck?
+
+- [ClickHouse RowBinary format](https://clickhouse.com/docs/interfaces/formats#rowbinary)
+- [ClickHouse data types](https://clickhouse.com/docs/sql-reference/data-types)
+- [ClickHouse JS client docs](https://clickhouse.com/docs/integrations/javascript)

package/skills/clickhouse-js-node-rowbinary/case-studies/iot-rowbinary-vs-json.md

@@ -0,0 +1,83 @@
+# Case study: RowBinary vs JSON on a table of IoT readings
+
+**TL;DR** — On a dense fixed-width numeric row, the skill's optimized RowBinary
+reader decodes **3.5x faster than the best JSON format** (`JSONCompactEachRow`)
+and **5.4x faster than `JSONEachRow`**, over a wire that is **1.6–3.3x smaller**.
+This is the workload shape the [SKILL's format-choice
+guidance](../SKILL.md#first-is-rowbinary-even-the-right-format) points at
+RowBinary for — and the numbers below are _measured_, not assumed.
+
+Reproduce: `npx vitest bench --run tests/iot.bench.ts` (against a live
+ClickHouse server). Source: [`tests/iot.bench.ts`](../tests/iot.bench.ts),
+reader: [`src/examples/iot.ts`](../src/examples/iot.ts).
+
+## The data
+
+A table of IoT sensor readings — every column fixed-width, not a string in the
+row, so the whole record is a flat 41-byte run:
+
+```sql
+sensor_id   UInt32         -- 4 bytes
+ts          DateTime64(3)  -- 8 bytes
+temperature Float64        -- 8 bytes
+humidity    Float64        -- 8 bytes
+pressure    Float64        -- 8 bytes
+battery     Float32        -- 4 bytes
+status      UInt8          -- 1 byte
+```
+
+50,000 rows, fetched from a live server in three formats and decoded into
+equivalent JS objects. A cross-format check asserts the RowBinary (binary
+float) and JSON (decimal-text → float) decodes agree on every numeric column
+before any timing is taken — so this measures the same work three ways, not
+three different results.
+
+## What was compared
+
+- **RowBinary — optimized.** The skill's monomorphized reader: the seven column
+  bounds checks coalesce into one `advance(s, 41)`, every field read at a
+  constant offset off that base.
+- **RowBinary — API combinators.** The same logic written with the plain
+  per-type readers (`readUInt32`, `readFloat64`, …) — the clear default.
+- **JSONCompactEachRow — `JSON.parse`.** Newline-delimited _arrays_ (no repeated
+  keys). The strongest JSON contender a knowledgeable user would pick.
+- **JSONEachRow — `JSON.parse`.** Newline-delimited _objects_ (keys repeated
+  every row) — the naive idiomatic choice.
+
+Both JSON paths use the fastest idiomatic decode: splice the rows into one
+`[...]` document and hand it to V8's native `JSON.parse` in a single call.
+
+## Wire size (HTTP response bytes)
+
+| Format             | Size    | B/row | vs RowBinary |
+| ------------------ | ------- | ----- | ------------ |
+| RowBinary          | 2.05 MB | 41.0  | 1.0x         |
+| JSONCompactEachRow | 3.38 MB | 67.6  | 1.6x         |
+| JSONEachRow        | 6.68 MB | 133.6 | 3.3x         |
+
+## Decode throughput (full 50k-row decode; higher = faster)
+
+| Decoder                           | ops/s | ms/decode | ≈ rows/s | speedup  |
+| --------------------------------- | ----- | --------- | -------- | -------- |
+| **RowBinary — optimized**         | 399   | 2.50      | ~20.0 M  | **1.0x** |
+| RowBinary — API combinators       | 159   | 6.31      | ~7.9 M   | 0.40x    |
+| JSONCompactEachRow — `JSON.parse` | 114   | 8.76      | ~5.7 M   | 0.29x    |
+| JSONEachRow — `JSON.parse`        | 74    | 13.47     | ~3.7 M   | 0.19x    |
+
+_Node 24 / V8. Your numbers will vary; run `npm run bench` on your own hardware._
+
+## Takeaways
+
+- **This is the textbook RowBinary win.** High-volume fixed-width numerics where
+  each field is one `DataView` read and there is no text to tokenize or numbers
+  to parse from decimal strings. The monomorphization win (2.5x over the
+  combinator API) is unusually large here because the whole row coalesces into a
+  _single_ bounds check with constant-offset reads.
+- **Format choice matters more than the optimization.** Even the plain
+  combinator-API RowBinary reader (~7.9 M rows/s) beats the best JSON option —
+  before any monomorphization.
+- **The flip side still holds.** Had this been a string-heavy result (logs, JSON
+  blobs, text consumed wholesale), `JSON.parse`'s optimized C++ would likely
+  _win_, and the skill would steer you to `JSONEachRow` + compression instead.
+  For IoT telemetry, RowBinary is clearly right — match the format to the shape
+  of the data.

package/skills/clickhouse-js-node-rowbinary/case-studies/ledger-rowbinary-vs-json.md

@@ -0,0 +1,103 @@
+# Case study: RowBinary vs JSON on a financial ledger (wide ints & decimals)
+
+**TL;DR** — When every column is wider than a JS `number` can hold (`UInt128`,
+`Int64`, `Decimal128(18)`, `UInt256`), RowBinary wins _twice over_. Stock
+`JSON.parse` is not merely slow here — it is **silently wrong**, rounding every
+value to a float64. The only correct JSON path quotes the values server-side and
+re-parses each string into a `bigint`/decimal pair by hand, which is **~5x
+slower** than the optimized RowBinary reader over a **2.1–2.6x larger** wire.
+RowBinary reads each value exactly, straight off the wire.
+
+This is the workload the [SKILL's format-choice
+guidance](../SKILL.md#first-is-rowbinary-even-the-right-format) calls out
+explicitly: "RowBinary clearly wins when the result is dominated by **wide
+numerics** — `Int128`/`Int256`/`UInt128`/`UInt256`, `Decimal128`/`Decimal256`."
+
+Reproduce: `npx vitest bench --run tests/ledger.bench.ts` (against a live
+ClickHouse server). Source: [`tests/ledger.bench.ts`](../tests/ledger.bench.ts),
+reader: [`src/examples/ledger.ts`](../src/examples/ledger.ts).
+
+## The data
+
+A financial ledger — every column exceeds IEEE-754 double's 53-bit exact range:
+
+```sql
+txn_id   UInt128         -- 16 bytes
+account  Int64           --  8 bytes  (values past 2^53)
+amount   Decimal128(18)  -- 16 bytes  (~32 significant digits)
+balance  Decimal128(18)  -- 16 bytes
+fee      Decimal64(4)    --  8 bytes
+volume   UInt256         -- 32 bytes
+```
+
+50,000 rows, fixed-width (96 bytes/row), fetched from a live server.
+
+## The correctness trap
+
+ClickHouse emits these types as **bare, unquoted JSON numbers**. So stock
+`JSON.parse` parses them as float64 and silently corrupts every one — measured
+on row 0 of the live result:
+
+| Column    | Exact value (RowBinary)                   | `JSON.parse` of bare JSON                 |                  |
+| --------- | ----------------------------------------- | ----------------------------------------- | ---------------- |
+| `txn_id`  | `340282366920938463463374607431768200000` | `340282366920938463463374607431768211456` | ✗ off by 11 456  |
+| `account` | `9007199254740993`                        | `9007199254740992`                        | ✗ off by 1       |
+| `amount`  | `98765432109876.123456789012345678`       | `98765432109876.12`                       | ✗ lost 16 digits |
+
+No exception, no warning — just wrong numbers. For money and IDs, that is a
+correctness bug, not a performance footnote.
+
+### Making JSON correct costs extra work
+
+The only way to get exact values through JSON is to **quote them server-side** so
+they arrive as strings, then re-parse each one:
+
+```sql
+... SETTINGS output_format_json_quote_64bit_integers = 1,
+             output_format_json_quote_decimals = 1
+```
+
+```ts
+txn_id:  BigInt(r.txn_id),                 // string -> bigint
+amount:  parseDecimal(r.amount, 18),       // string -> [unscaled, scale]
+```
+
+That per-field `BigInt(...)` / decimal parse is work RowBinary doesn't do — it
+reads the exact `bigint` directly with two `DataView` reads — and it lands on
+top of a larger wire (strings are longer than the binary words).
+
+## Wire size (correct paths quote wide values as strings)
+
+| Format                      | Size     | vs RowBinary |
+| --------------------------- | -------- | ------------ |
+| RowBinary                   | 4.80 MB  | 1.0x         |
+| JSONCompactEachRow (quoted) | 9.88 MB  | 2.1x         |
+| JSONEachRow (quoted)        | 12.28 MB | 2.6x         |
+
+## Decode throughput (full 50k-row decode; higher = faster)
+
+| Decoder                                            | ops/s | ms/decode | ≈ rows/s | speedup  | correct?       |
+| -------------------------------------------------- | ----- | --------- | -------- | -------- | -------------- |
+| **RowBinary — optimized**                          | 130   | 7.71      | ~6.5 M   | **1.0x** | ✅             |
+| RowBinary — API combinators                        | 80    | 12.50     | ~4.0 M   | 0.62x    | ✅             |
+| JSONEachRow bare — `JSON.parse` only               | 44    | 22.74     | ~2.2 M   | 0.34x    | ❌ **corrupt** |
+| JSONCompactEachRow quoted — parse + BigInt/decimal | 26    | 37.78     | ~1.3 M   | 0.20x    | ✅             |
+| JSONEachRow quoted — parse + BigInt/decimal        | 25    | 40.70     | ~1.2 M   | 0.19x    | ✅             |
+
+_Node 24 / V8. Your numbers will vary; run `npm run bench` on your own hardware._
+
+## Takeaways
+
+- **The fast JSON path is the wrong one.** Bare `JSON.parse` is JSON's quickest
+  option and it is still 2.95x slower than RowBinary — _and_ it silently
+  corrupts every wide value. There is no "fast and correct" JSON here.
+- **The correct JSON path is ~5x slower.** Quote + per-field `BigInt`/decimal
+  parsing is the price of correctness, on top of a 2.1–2.6x larger wire.
+- **RowBinary is correct by construction.** Each value is composed from 64-bit
+  words read at constant offsets (high word signed for the signed types),
+  yielding an exact `bigint` or `[unscaled, scale]` pair — no rounding, no
+  string re-parsing.
+- **Contrast with the [IoT case study](iot-rowbinary-vs-json.md):** there the
+  numbers fit a float64 and the win was purely throughput (3.5x). Here the values
+  don't fit, so the win is _correctness first_, throughput second. Match the
+  format to the shape of the data.