jsonstat-io 0.1.0

package/docs/api.md

@@ -0,0 +1,322 @@
+# API Reference
+
+The main entry `jsonstat-io` re-exports the always-loaded layers: model types, core engine, Arrow hub, sink, and isomorphic utils. Format adapters that need optional peers live behind subpath exports. Every subpath is **bidirectional** — it exports both an import function (`xToCube` / `xToDataset`) and an export function (`cubeToX`).
+
+## High-level dispatchers
+
+### `importToCube(source, options?)`
+
+```ts
+import { importToCube } from "jsonstat-io";
+
+const obs = await importToCube("./sales.parquet");
+```
+
+Loads a source (file path, URL, `"-"` for stdin, `Uint8Array`, or `Blob`), auto-detects the format, and converts it to the [`Observations`](./mapping.md#observations-ir) IR. Dispatches to the right source adapter and funnels through the Arrow hub.
+
+**Parameters:**
+- `source: string | Uint8Array | Blob` — the input.
+- `options?: ImportOptions` — detection and conversion hints.
+
+**Returns:** `Promise<Observations>`
+
+### `importToDataset(source, options?)`
+
+```ts
+import { importToDataset } from "jsonstat-io";
+
+const dataset = await importToDataset("./sales.parquet", {
+  measure: "amount",
+  roles: { time: ["year"], geo: ["country"] },
+  build: { valueForm: "sparse" },
+});
+```
+
+Like `importToCube` but also builds the final [`JsonStatDataset`](./mapping.md) via `buildDataset`.
+
+**Returns:** `Promise<JsonStatDataset>`
+
+### `ImportOptions`
+
+Extends `ArrowToCubeOptions`:
+
+| Field             | Type                              | Default     | Description |
+|-------------------|-----------------------------------|-------------|-------------|
+| `from`            | `SourceFormat \| "auto"`          | `"auto"`    | Force a format instead of auto-detecting |
+| `build`           | `BuildOptions`                    | —           | Passed to `buildDataset` |
+| `csvwMetadata`    | `unknown`                         | —           | CSVW metadata object (when `from: "csvw"`) |
+| `delimiter`       | `string`                          | `","`       | CSV delimiter |
+| `measure`         | `string`                          | *(detected)*| Measure column name |
+| `dimensions`      | `string[]`                        | *(detected)*| Dimension column names |
+| `status`          | `string`                          | *(detected)*| Status column name |
+| `roles`           | `RoleMap`                         | *(inferred)*| Role assignments |
+| `valueForm`       | `"auto" \| "dense" \| "sparse"`  | `"auto"`    | Value form hint |
+
+### `importToCube`
+
+Thrown by the dispatchers when a format cannot be detected, a required peer dependency is missing, or the source produces no data.
+
+---
+
+## Export dispatchers
+
+### `exportDataset(dataset, options)`
+
+```ts
+import { exportDataset } from "jsonstat-io";
+
+// JSON-stat dataset → Arrow Table
+const table = await exportDataset(dataset, { to: "arrow" });
+
+// → Parquet bytes (needs parquet-wasm)
+const bytes = await exportDataset(dataset, { to: "parquet" });
+
+// → CSV text
+const csv = await exportDataset(dataset, { to: "csv" });
+
+// → CSV text + CSVW metadata object
+const { csv, metadata } = await exportDataset(dataset, { to: "csvw" });
+```
+
+Flattens a JSON-stat dataset to the Observations IR via `readDataset`, then converts to the requested target format. Arrow-native targets (parquet) funnel through `cubeToArrow`; text targets (csv, csvw) serialize directly from the IR.
+
+**Parameters:**
+- `dataset: JsonStatDataset` — the input JSON-stat dataset.
+- `options: ExportOptions` — `{ to, ...format-specific options }`.
+
+**Returns:** `Promise<ExportResult>` — an Arrow `Table` (`to: "arrow"`), a `Uint8Array` (`to: "parquet"`), a `string` (`to: "csv"`), or a `{ csv, metadata }` object (`to: "csvw"`).
+
+### `ExportOptions`
+
+| Field    | Type                                | Description |
+|----------|-------------------------------------|-------------|
+| `to`     | `ExportTarget`                      | `"arrow"` \| `"parquet"` \| `"csv"` \| `"csvw"` |
+| *(format-specific)* | varies                | Passed through to the target adapter (e.g. `compression` for parquet, `delimiter` for csv) |
+
+---
+
+## Core engine
+
+### `buildDataset(obs, options?)`
+
+```ts
+import { buildDataset } from "jsonstat-io";
+
+const { dataset, size, valueForm } = buildDataset(obs, { valueForm: "sparse" });
+```
+
+Converts the `Observations` IR into a `JsonStatDataset`. Resolves dimension categories, scatters values into row-major positions, decides dense/sparse, and emits status.
+
+**Returns:** `BuildResult { dataset, size, valueForm }`
+
+### `toDataset(obs)`
+
+Convenience wrapper: `buildDataset(obs).dataset`.
+
+### `readDataset(dataset, options?)`
+
+```ts
+import { readDataset } from "jsonstat-io";
+
+const obs = readDataset(jsonStatDataset, { dropNulls: false });
+```
+
+The inverse of `buildDataset`: flattens a JSON-stat cube back into the `Observations` IR. Powers round-trip tests, the JSON-stat-as-input path, and **all export** operations (`exportDataset` calls `readDataset` first).
+
+### `BuildOptions`
+
+| Field              | Type                                              | Default | Description |
+|--------------------|---------------------------------------------------|---------|-------------|
+| `valueForm`        | `"auto" \| "dense" \| "sparse"`                  | `"auto"`| Override value form |
+| `sparseThreshold`  | `number`                                          | `0.5`   | Null ratio threshold for auto sparse |
+| `statusForm`       | `"auto" \| "array" \| "string" \| "object" \| "none"` | `"auto"`| Status emission form |
+| `meta`             | `DatasetMeta`                                     | —       | Dataset label/source/updated |
+
+### Stride utilities
+
+```ts
+import { strides, totalCells, flatPosition, multiIndex, enumerateCells } from "jsonstat-io";
+```
+
+- `strides(size: number[]): number[]` — stride of each dimension.
+- `totalCells(size: number[]): number` — product of all sizes.
+- `flatPosition(indices: number[], size: number[]): number` — multi-index → flat position.
+- `multiIndex(pos: number, size: number[]): number[]` — flat position → multi-index.
+- `enumerateCells(size: number[]): number[][]` — all cell addresses.
+
+---
+
+## Arrow hub
+
+### `arrowToCube(table, options?)`
+
+```ts
+import { arrowToCube } from "jsonstat-io";
+import { tableFromIPC } from "apache-arrow";
+
+const table = tableFromIPC(bytes);
+const obs = arrowToCube(table, { measure: "amount" });
+```
+
+Converts an Apache Arrow `Table` to the `Observations` IR. Detects dimensions (dictionary columns), measures (numeric columns), and status from the schema, resolving roles from `jsonstat.*` metadata or heuristics.
+
+### `arrowToDataset(table, options?)`
+
+Async convenience: `buildDataset(arrowToCube(table, options)).dataset`.
+
+### `cubeToArrow(obs)`
+
+The export hub: converts `Observations` IR → Arrow `Table` with dictionary-encoded dimensions and a Float64 measure, annotating fields with `jsonstat.*` metadata. This is what `exportDataset({ to: "arrow" })`, `cubeToParquet`, `cubeToDuckdb`, and `cubeToPolars` all build upon.
+
+### Schema metadata helpers
+
+```ts
+import { buildFieldMeta, readSchemaMeta, buildSchemaMeta, getFieldRole } from "jsonstat-io";
+```
+
+- `buildFieldMeta(hints)` — construct `Field.metadata` entries from role/label/category hints.
+- `readSchemaMeta(schema)` — read `jsonstat.*` schema-level metadata.
+- `buildSchemaMeta(hints)` — construct `Schema.metadata` entries.
+- `getFieldRole(field)` — extract the role from a field's metadata.
+
+---
+
+## Source adapters (subpath exports)
+
+Each subpath is bidirectional — it exports import (`xToCube` / `xToDataset`) and export (`cubeToX`) functions.
+
+### `jsonstat-io/parquet`
+
+```ts
+import { parquetToCube, parquetToDataset, cubeToParquet } from "jsonstat-io/parquet";
+
+const obs = await parquetToCube(bytes, { init: () => parquetWasm.init() });
+
+// Export: IR → Arrow → Parquet bytes
+const parquetBytes = await cubeToParquet(obs, { init: () => parquetWasm.init() });
+```
+
+Requires `parquet-wasm`. See [`formats/parquet.md`](./formats/parquet.md).
+
+### `jsonstat-io/duckdb`
+
+```ts
+import { duckdbToCube, openDuckdbNode, cubeToDuckdb } from "jsonstat-io/duckdb";
+
+const conn = await openDuckdbNode("./data.duckdb");
+const obs = await duckdbToCube(conn, "SELECT year, country, amount FROM sales");
+
+// Export: register an Arrow-backed view (or table) in the connection
+await cubeToDuckdb(conn, obs, { tableName: "sales", mode: "view" });
+```
+
+Requires `duckdb-async` (Node) or `@duckdb/duckdb-wasm` (browser). See [`formats/duckdb.md`](./formats/duckdb.md).
+
+### `jsonstat-io/polars`
+
+```ts
+import { polarsToCube, loadPolars, cubeToPolars } from "jsonstat-io/polars";
+
+const pl = await loadPolars();
+const df = pl.readCSV("data.csv");
+const obs = await polarsToCube(df);
+
+// Export: IR → Arrow → Polars DataFrame
+const dfOut = await cubeToPolars(obs);
+```
+
+Requires `nodejs-polars`. Node only. See [`formats/polars.md`](./formats/polars.md).
+
+### `jsonstat-io/csvw`
+
+```ts
+import { csvwToCube, parseCsvwMetadata, cubeToCsvw } from "jsonstat-io/csvw";
+
+const meta = parseCsvwMetadata(metadataJson);
+const obs = csvwToCube(csvText, meta, { dimensions: ["year", "country"] });
+
+// Export: IR → CSV text + CSVW metadata object
+const { csv, metadata } = cubeToCsvw(obs);
+```
+
+No dependencies. See [`formats/csvw.md`](./formats/csvw.md).
+
+### `jsonstat-io/csv`
+
+```ts
+import { csvToCube, cubeToCsv } from "jsonstat-io/csv";
+
+const obs = csvToCube(csvText, { measure: "amount", delimiter: ";" });
+
+// Export: IR → CSV text (dimensions + measure + optional status)
+const csv = cubeToCsv(obs);
+```
+
+No dependencies. Heuristic measure/dimension inference on import.
+
+---
+
+## Sink
+
+### `serialize(dataset, options?)`
+
+```ts
+import { serialize } from "jsonstat-io";
+
+const json = serialize(dataset, { pretty: true, canonicalKeys: true });
+```
+
+Produces a canonical JSON string. Optionally reorders top-level keys for diff-stable output.
+
+### `serializeToBytes(dataset, options?)`
+
+Returns `Uint8Array` instead of a string.
+
+---
+
+## Utilities
+
+### Format detection
+
+```ts
+import { detectFormat, detectFromBytes, detectFromExtension } from "jsonstat-io";
+
+detectFromBytes(bytes);            // "parquet" | "arrow" | "jsonstat" | "unknown"
+detectFromExtension("parquet");    // "parquet"
+detectFormat("data.csv", bytes);   // tries extension first, then bytes
+```
+
+### Input loading
+
+```ts
+import { loadInput } from "jsonstat-io";
+
+const { bytes, source } = await loadInput("./sales.parquet");  // Node: reads file
+const { bytes } = await loadInput(blob);                        // Browser: reads Blob
+```
+
+### Density decision
+
+```ts
+import { decideDensity } from "jsonstat-io";
+
+decideDensity(0.6, 0.5);  // { form: "sparse", nullRatio: 0.6, threshold: 0.5 }
+```
+
+---
+
+## Error classes
+
+| Class                 | Thrown by |
+|-----------------------|-----------|
+| `ImporterError`       | `importToCube`, `importToDataset`, `exportDataset` |
+| `ArrowConversionError`| `arrowToCube`, `cubeToArrow` |
+| `CubeBuilderError`    | `buildDataset` |
+| `CubeReaderError`     | `readDataset` |
+| `ParquetSourceError`  | `parquetToCube` |
+| `DuckdbSourceError`   | `duckdbToCube` |
+| `PolarsSourceError`   | `polarsToCube` |
+| `CsvwSourceError`     | `csvwToCube` |
+| `CsvSourceError`      | `csvToCube` |
+
+All extend `Error` and set `this.name` to the class name.

package/docs/architecture.md

@@ -0,0 +1,140 @@
+# Architecture
+
+This document explains the layered design of `jsonstat-io` and the rationale behind the two key decisions: the **Arrow hub** and the **Observations IR**. Both import (columnar → JSON-stat) and export (JSON-stat → columnar) are fully supported and share the same IR.
+
+## The core problem
+
+JSON-stat 2.0 is a *dense or sparse* multidimensional cube model: values are laid out in **row-major order** ("what does not change first") across the cross-product of dimension categories. Every statistical office, every data portal, and increasingly every lakehouse produces *tabular* data instead — Parquet, Arrow, CSV, DataFrames. These two worlds speak different shapes:
+
+| JSON-stat cube        | Columnar / tabular      |
+|-----------------------|-------------------------|
+| N-dimensional array   | 2D table (rows × cols)  |
+| Row-major value order | Columnar or row order   |
+| Dimensions × size     | Column names × values   |
+| Implicit cell address | Explicit row            |
+
+`jsonstat-io` bridges this gap in both directions. The challenge is not just *reading* a format — it's **faithfully reconstructing the full JSON-stat model** (roles, labels, units, coordinates, hierarchies, status, sparse/dense) from a source that carries only raw values unless you annotate it, and reversing that reconstruction losslessly on export.
+
+## The Arrow-hub insight
+
+Apache Arrow is the *de facto* in-memory standard of the columnar data stack. Critically, the major lakehouse engines all emit Arrow tables natively:
+
+- **Parquet** → Arrow via `parquet-wasm` (or DuckDB/Polars, which read Parquet)
+- **DuckDB** → Arrow via `.arrow()` / `.arrowResult()`
+- **Polars** → Arrow via `toArrow()` / `toIPC()`
+- **Arrow IPC** → Arrow via `tableFromIPC()` (it already *is* Arrow)
+
+This means a single converter pair — `arrowToCube` (import) and `cubeToArrow` (export) — handles four of the five major formats in both directions. Adding a new Arrow-native source is a ~30-line adapter that calls `arrowToCube` on import and `cubeToArrow` on export. The mapping logic (dimension detection, role resolution, value scattering, status emission) lives in exactly one place per direction and is tested once.
+
+```
+ IMPORT
+ N sources ──▶ Arrow Table ──▶ arrowToCube ──▶ Observations IR ──▶ buildDataset ──▶ JSON-stat
+              (one shape)      (one converter)  (one IR)            (one builder)    (one format)
+
+ EXPORT
+ JSON-stat ──▶ readDataset ──▶ Observations IR ──▶ cubeToArrow ──▶ Arrow Table ──▶ N targets
+                               (one IR)           (one converter)  (one shape)
+```
+
+CSVW and plain CSV do not produce Arrow natively in this package, so they build the IR directly on import and serialize from the IR directly on export — but they share the *same* IR type and the *same* builder/reader, so the downstream path is identical.
+
+## Layered architecture
+
+The package is organized in strict layers with one-way dependencies:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Public API (index.ts) + CLI (cli/)                     │  ← what consumers call
+├─────────────────────────────────────────────────────────┤
+│  Sources (parquet, duckdb, polars, csvw, csv)           │  ← format adapters
+├─────────────────────────────────────────────────────────┤
+│  Arrow hub (arrowToCube, arrowFromCube, schemaMeta)     │  ← the hub
+├─────────────────────────────────────────────────────────┤
+│  Core engine (strides, cubeBuilder, cubeReader)         │  ← the math
+├─────────────────────────────────────────────────────────┤
+│  Model (jsonstat types, Observations IR)                │  ← pure types
+├─────────────────────────────────────────────────────────┤
+│  Sink (serialize) + Utils (detect, fetch, density)      │  ← isomorphic helpers
+└─────────────────────────────────────────────────────────┘
+```
+
+Each layer depends only on the layers below it. The model layer is pure TypeScript types with zero runtime cost. The core engine is pure logic with no I/O. The Arrow hub depends on `apache-arrow` (a hard dependency). Source adapters depend on optional peers, imported lazily.
+
+### Layer 1: Model (`src/model/`)
+
+Two parallel type definitions:
+
+- **`jsonstat.ts`** — the JSON-stat 2.0 wire types: `JsonStatDataset`, `JsonStatDimension`, `JsonStatCategory`, `JsonStatRole`, `JsonStatUnit`, etc. Plus type guards (`isDataset`, `isCollection`).
+- **`ir.ts`** — the internal `Observations` IR: a tidy long table with `DimensionColumn[]`, one `MeasureColumn`, an optional `StatusColumn`, a `RoleMap`, `DatasetMeta`, and a `valueForm` hint.
+
+No runtime logic here except `observationCount()`. This is the contract every layer agrees on.
+
+### Layer 2: Core engine (`src/core/`)
+
+The mathematical heart:
+
+- **`strides.ts`** — row-major stride arithmetic. `strides(size)` computes the stride of each dimension; `flatPosition(indices, size)` maps a multi-index to a flat array position; `multiIndex` is the inverse; `enumerateCells` iterates all cell addresses.
+- **`cubeBuilder.ts`** — `buildDataset(obs, options)` resolves dimension categories (explicit order or first-seen), scatters the measure values into their row-major positions, decides dense vs sparse, and emits status. This is the "long → wide" pivot.
+- **`cubeReader.ts`** — `readDataset(dataset)` is the inverse: it takes a JSON-stat cube and *flattens* it back into the Observations IR. This powers round-trip tests and the JSON-stat-as-input path.
+
+The core has **zero I/O dependencies** — it operates on plain arrays and objects. This is what makes it isomorphic and testable.
+
+### Layer 3: Arrow hub (`src/arrow/`)
+
+- **`schemaMeta.ts`** — defines the `jsonstat.*` metadata key contract on Arrow `Field` and `Schema` objects. This is how producers annotate Arrow tables with JSON-stat semantics (roles, labels, units, coordinates, hierarchies). Without metadata, `arrowToCube` falls back to heuristics.
+- **`arrowToCube.ts`** — `arrowToCube(table, options)` reads an Arrow `Table`, detects dimensions (dictionary columns), measures (numeric columns), and status, resolves roles from metadata + options, and produces the `Observations` IR. This is the single converter that Parquet/DuckDB/Polars all funnel through.
+- **`arrowFromCube.ts`** — `cubeToArrow(obs)` is the Phase 2 seam: IR → Arrow Table. It builds dictionary-encoded dimension columns and a Float64 measure column, annotating fields with `jsonstat.*` metadata for lossless round-trips.
+
+### Layer 4: Source adapters (`src/sources/`)
+
+Each adapter is bidirectional — a thin wrapper that, on import, gets bytes (or a live connection/DataFrame) into an Arrow Table then calls `arrowToCube`, and on export, takes the Arrow Table (or IR) from `cubeToArrow` and writes it to the target format:
+
+- **`parquet.ts`** — `parquetToCube(bytes)` / `cubeToParquet(obs)` via `parquet-wasm` (lazy import). Browser + Node.
+- **`duckdb.ts`** — `duckdbToCube(conn, query)` / `cubeToDuckdb(conn, obs)` runs SQL on import, registers an Arrow view/table on export. Supports `duckdb-async` (Node) and `@duckdb/duckdb-wasm` (browser).
+- **`polars.ts`** — `polarsToCube(df)` / `cubeToPolars(obs)` via `toArrow()`/`fromArrow()`. Node only.
+- **`csvw.ts`** — `csvwToCube(text, metadata)` / `cubeToCsvw(obs)` uses CSVW metadata for lossless mapping. No deps.
+- **`csv.ts`** — `csvToCube(text)` / `cubeToCsv(obs)` infers measure/dimensions heuristically on import; serializes dimensions+measure+status columns on export. No deps.
+
+All optional peer imports are **lazy** (`await import(...)`) so they never enter a bundle that doesn't use them.
+
+### Layer 5: Sink + Utils (`src/sink/`, `src/util/`)
+
+- **`serialize.ts`** — `serialize(dataset, options)` produces canonical JSON. Optionally reorders top-level keys for diff-stable output. `serializeToBytes` returns `Uint8Array`.
+- **`detect.ts`** — `detectFormat(source, bytes)` sniffs the format from magic bytes (Parquet `PAR1`, Arrow `ARROW1`) and file extension. Used by the high-level dispatchers.
+- **`fetch.ts`** — `loadInput(source)` normalizes file paths, URLs, stdin, `Uint8Array`, and `Blob` into a uniform `LoadedInput { bytes, source }`. Uses `fetch` in the browser, `node:fs` in Node.
+- **`density.ts`** — `decideDensity(nullRatio, threshold)` implements the sparse/dense auto-decision.
+
+## The Observations IR
+
+The `Observations` IR is the keystone. It is a **tidy long table**:
+
+```ts
+interface Observations {
+  dimensions: Record<string, DimensionColumn>;  // { values: string[] }
+  measure:  MeasureColumn;                       // { values: (number|null)[] }
+  status?:  StatusColumn;                        // { values: string[] }
+  roles?:   RoleMap;                             // { time?: string[], geo?: string[], metric?: string[] }
+  meta?:    DatasetMeta;                         // { label?, source?, updated? }
+  valueForm?: "auto" | "dense" | "sparse";
+}
+```
+
+Every source produces this shape. `buildDataset` is the only consumer that pivots it into the row-major cube. This separation means:
+
+1. **Adding a source** = producing `Observations`. You never touch the cube math.
+2. **Testing the cube math** = construct `Observations` directly, no file I/O.
+3. **Round-tripping** = `readDataset` (cube → IR) + `buildDataset` (IR → cube).
+
+## Bidirectional scope
+
+Both directions are fully implemented and tested:
+
+- **Import** (columnar → JSON-stat): `arrowToCube` handles Arrow-native sources; `csvToCube` / `csvwToCube` handle text formats; `buildDataset` scatters into the cube. Exposed via [`importToDataset`](./api.md#importtodatasetsource-options).
+- **Export** (JSON-stat → columnar): `readDataset` flattens the cube to the IR; `cubeToArrow` handles Arrow-native targets (Parquet, DuckDB, Polars); `cubeToCsv` / `cubeToCsvw` handle text targets. Exposed via [`exportDataset`](./api.md#exportdatasetdataset-options).
+- **CLI:** the `--to` flag drives direction — `jsonstat` (default) imports; `arrow|parquet|csv|csvw` exports.
+
+The same Observations IR sits at the center of both directions, guaranteeing that `export → import` round-trips losslessly.
+
+## The Rust/Wasm accelerator seam
+
+The performance-critical path is `buildDataset`'s value scattering and `cubeToArrow`'s vector building — the nested-loop stride multiplication. The public API signatures (`buildDataset`, `arrowToCube`, `cubeToArrow`, `exportDataset`) are stable and framework-agnostic. An accelerator can replace the internals behind the same types, yielding a drop-in speedup with no consumer changes.

package/docs/cli.md

@@ -0,0 +1,159 @@
+# CLI Reference
+
+```sh
+npx jsonstat-io [input] [options]
+```
+
+## Synopsis
+
+```
+jsonstat-io [input] [options]
+
+Convert between columnar data (Arrow, Parquet, DuckDB, Polars, CSVW, CSV) and JSON-stat 2.0 cubes.
+
+Arguments:
+  input                    Input file path, URL, or "-" for stdin (default: "-").
+                           Supports .parquet, .arrow/.ipc, .csv, .csvw, .json/.jsonstat.
+
+Options:
+  -V, --version            Print version and exit.
+  -h, --help               Print this help and exit.
+
+Format:
+  -f, --from <format>      Source format override. One of:
+                             auto (default) — sniff from magic bytes + extension
+                             parquet        — needs parquet-wasm
+                             arrow          — Arrow IPC stream/file
+                             csv            — plain CSV (heuristic mapping)
+                             csvw           — CSV with metadata
+                             jsonstat, json — JSON-stat input (round-trip)
+  -t, --to <format>        Output format / direction. One of:
+                             jsonstat (default) — IMPORT: columnar → JSON-stat
+                             arrow              — EXPORT: JSON-stat → Arrow IPC
+                             parquet            — EXPORT: JSON-stat → Parquet (needs parquet-wasm)
+                             csv                — EXPORT: JSON-stat → CSV
+                             csvw               — EXPORT: JSON-stat → CSV + CSVW metadata
+
+Column mapping:
+      --measure <column>   Name of the measure column (overrides detection).
+      --dimensions <a,b,c> Comma-separated dimension column names, in order.
+      --role <assigns>     Role assignments: time=<col>,geo=<col>,metric=<col>
+                           (comma-separated). Example: --role time=year,geo=country
+      --status <column>    Name of the status column.
+
+Value form:
+      --sparse             Force sparse (object) value form.
+      --dense              Force dense (array) value form.
+      --auto               Auto-decide value form by null ratio (default).
+      --threshold <n>      Sparse threshold: null ratio 0–1 (default 0.5).
+
+Status form:
+      --status-form <form> Status emission. One of:
+                             auto (default) — string if uniform, else array
+                             array          — always per-cell array
+                             string         — always a single string
+                             object         — explicit {position: code}
+                             none           — omit status entirely
+
+Dataset metadata:
+      --label <text>       Dataset label.
+      --source <text>      Dataset source.
+      --updated <date>     Dataset last-updated date (ISO 8601).
+
+Output:
+  -o, --output <file>      Write to file instead of stdout.
+      --pretty             Pretty-print JSON (default: true).
+      --no-pretty          Compact JSON output (single line).
+      --canonical-keys     Reorder top-level keys canonically (default: true).
+      --no-canonical-keys  Preserve insertion key order.
+      --validate           Validate output with jsonstat-validator (if installed).
+
+CSV/CSVW:
+      --csvw-metadata <json>  Inline CSVW metadata as a JSON string.
+      --delimiter <char>      CSV delimiter (default: ",").
+```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | Success |
+| 1    | Import, validation, or write error |
+| 2    | Invalid CLI arguments |
+
+## Examples
+
+### IMPORT: Parquet → JSON-stat file
+
+```sh
+npx jsonstat-io ./sales.parquet -o sales.jsonstat.json --label "Sales 2024"
+```
+
+### IMPORT: CSV on stdin with explicit roles
+
+```sh
+cat data.csv | npx jsonstat-io - --measure amount --role time=year,geo=country
+```
+
+### IMPORT: Arrow IPC from a URL, forced sparse
+
+```sh
+npx jsonstat-io https://example.com/data.arrow --sparse --threshold 0.3
+```
+
+### IMPORT: CSVW with inline metadata
+
+```sh
+npx jsonstat-io ./data.csv --from csvw \
+  --csvw-metadata '{"tableSchema":{"columns":[{"titles":"year","datatype":"string"},{"titles":"value","datatype":"decimal"}],"primaryKey":["year"]}}'
+```
+
+### IMPORT: JSON-stat round-trip (re-emit with canonical keys)
+
+```sh
+npx jsonstat-io ./input.jsonstat --from jsonstat --canonical-keys -o canonical.jsonstat.json
+```
+
+### EXPORT: JSON-stat → Parquet
+
+```sh
+npx jsonstat-io ./sales.jsonstat.json --to parquet -o sales.parquet
+```
+
+### EXPORT: JSON-stat → Arrow IPC
+
+```sh
+npx jsonstat-io ./sales.jsonstat.json --to arrow -o sales.arrow
+```
+
+### EXPORT: JSON-stat → CSV (+ sibling CSVW metadata)
+
+```sh
+npx jsonstat-io ./sales.jsonstat.json --to csv -o sales.csv
+# writes sales.csv and sales-metadata.json
+```
+
+### EXPORT: JSON-stat → CSVW (with explicit CSVW metadata)
+
+```sh
+npx jsonstat-io ./sales.jsonstat.json --to csvw -o sales.csvw
+```
+
+### Validate the output
+
+```sh
+npm i -g jsonstat-validator
+npx jsonstat-io ./sales.parquet --validate
+```
+
+If `jsonstat-validator` is not installed, `--validate` prints a hint instead of failing.
+
+## How detection works
+
+When `--from` is omitted (or `auto`), the CLI:
+
+1. Reads magic bytes: `PAR1` → Parquet, `ARROW1` → Arrow IPC.
+2. Falls back to the file extension: `.parquet`, `.arrow`/`.ipc`, `.csv`, `.json`/`.jsonstat`.
+3. For `.csv`, tries to load a sibling `*-metadata.json` (CSVW convention). If found, uses CSVW; otherwise plain CSV.
+
+DuckDB and Polars require a live connection or DataFrame object and are **not** available via the CLI — use the programmatic API ([`docs/formats/duckdb.md`](./formats/duckdb.md), [`docs/formats/polars.md`](./formats/polars.md)).