jsonstat-io 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Xavier Badosa
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing
+   permissions and limitations under the License.

package/README.md

@@ -0,0 +1,200 @@
+# jsonstat-io
+
+> Convert between [JSON-stat 2.0](https://jsonstat.org/) cubes and the columnar stack — Apache Arrow, Parquet, DuckDB, Polars, CSVW, CSV. An Arrow-bridged, bidirectional interop layer for the lakehouse ecosystem.
+
+`jsonstat-io` bridges the **columnar stack** — Arrow, Parquet, DuckDB, Polars — and the **JSON-stat statistical format** in a single, dependency-light package. Because Parquet, DuckDB, and Polars all emit Apache Arrow tables natively, one conversion path serves them all in **both directions**:
+
+- **Import:** columnar → JSON-stat (`importToDataset`)
+- **Export:** JSON-stat → columnar (`exportDataset`)
+
+This is the *Arrow-hub* insight: **N sources → one Arrow hub → JSON-stat**, and back. The same `arrowToCube` / `cubeToArrow` pair powers every binary format.
+
+- **Bidirectional.** Import and export are both first-class, fully-tested directions sharing one round-trip-safe IR.
+- **Pure-TS core.** The cube engine is pure TypeScript, with a documented seam to swap in a Rust/Wasm accelerator later without changing the public API.
+- **Isomorphic.** Works in Node (≥18) and the browser. Heavy format engines (Parquet/DuckDB/Polars) are optional peer dependencies, imported lazily so browser bundles stay lean.
+
+## Install
+
+```sh
+npm install jsonstat-io
+```
+
+The only hard runtime dependencies are [`apache-arrow`](https://arrow.apache.org/docs/js/) and [`commander`](https://github.com/tj/commander.js) (CLI only). Format-specific engines are **optional peers** — install only what you use:
+
+```sh
+npm install parquet-wasm         # Parquet (browser + Node)
+npm install duckdb-async         # DuckDB (Node)
+npm install @duckdb/duckdb-wasm  # DuckDB (browser)
+npm install nodejs-polars        # Polars (Node only)
+npm install jsonstat-validator   # optional output validation
+```
+
+## Quick start
+
+### Import — columnar → JSON-stat (Node or browser)
+
+```ts
+import { importToDataset } from "jsonstat-io";
+
+// Auto-detects Parquet from magic bytes → Arrow hub → JSON-stat dataset.
+const dataset = await importToDataset("./sales.parquet");
+console.log(JSON.stringify(dataset, null, 2));
+```
+
+One call handles files, URLs, stdin (`"-"`), `Uint8Array`, and `Blob`:
+
+```ts
+await importToDataset("https://example.com/data.arrow");    // URL
+await importToDataset(bytes);                                // Uint8Array
+await importToDataset("./report.csv", { from: "csv" });      // force CSV
+```
+
+### Export — JSON-stat → columnar (Node or browser)
+
+```ts
+import { exportDataset } from "jsonstat-io";
+
+// JSON-stat dataset → Arrow Table
+const table = await exportDataset(dataset, { to: "arrow" });
+
+// → Parquet bytes (needs parquet-wasm)
+const parquetBytes = await exportDataset(dataset, { to: "parquet" });
+
+// → CSV text + CSVW metadata
+const { csv, metadata } = await exportDataset(dataset, { to: "csvw" });
+```
+
+### CLI
+
+The `--to` flag drives direction: `jsonstat` (default) imports; `arrow|parquet|csv|csvw` exports.
+
+```sh
+# IMPORT: file → JSON-stat, written to stdout
+npx jsonstat-io ./sales.parquet
+
+# Write to a file, with a dataset label
+npx jsonstat-io ./sales.parquet -o sales.jsonstat.json --label "Sales 2024"
+
+# Pipe CSV on stdin, assign roles explicitly
+cat data.csv | npx jsonstat-io - --measure amount --role time=year,geo=country
+
+# EXPORT: JSON-stat → Parquet
+npx jsonstat-io ./sales.jsonstat.json --to parquet -o sales.parquet
+
+# JSON-stat → CSV (+ sibling -metadata.json)
+npx jsonstat-io ./sales.jsonstat.json --to csv -o sales.csv
+```
+
+See [`docs/cli.md`](./docs/cli.md) for the full CLI reference.
+
+## Why Arrow as the hub?
+
+| Format   | Arrow-native? | Import adapter                       | Export adapter                       |
+|----------|:-------------:|--------------------------------------|--------------------------------------|
+| Parquet  | ✅ `parquet-wasm` | [`/parquet`](./docs/formats/parquet.md) | [`/parquet`](./docs/formats/parquet.md) |
+| DuckDB   | ✅ `.arrow()`     | [`/duckdb`](./docs/formats/duckdb.md)  | [`/duckdb`](./docs/formats/duckdb.md)  |
+| Polars   | ✅ `toArrow()`    | [`/polars`](./docs/formats/polars.md)  | [`/polars`](./docs/formats/polars.md)  |
+| Arrow IPC| ✅ (it *is* Arrow)| [`/arrow`](./docs/formats/arrow.md)    | [`/arrow`](./docs/formats/arrow.md)    |
+| CSVW     | ❌ → IR directly  | [`/csvw`](./docs/formats/csvw.md)      | [`/csvw`](./docs/formats/csvw.md)      |
+| Plain CSV| ❌ → IR directly  | [`/csv`](./docs/formats/csv.md)        | [`/csv`](./docs/formats/csv.md)        |
+
+Every Arrow-producing format funnels through **one** `arrowToCube` / `cubeToArrow` pair. This means the JSON-stat mapping logic (dimensions, roles, sparse/dense, status) is implemented and tested exactly once per direction, then reused. Adding a new Arrow-native format is a ~30-line adapter.
+
+## How it works
+
+```
+IMPORT (columnar → JSON-stat)
+┌──────────┐   ┌─────────────┐   ┌──────────┐   ┌──────────────┐
+│ Parquet  │──▶│ parquet-wasm│──▶│          │   │              │
+│ DuckDB   │──▶│ .arrow()    │──▶│ Arrow    │──▶│ arrowToCube  │──┐
+│ Polars   │──▶│ toArrow()   │──▶│ Table    │   │ (the hub)    │  │
+│ Arrow IPC│──▶│ tableFromIPC│──▶│          │   │              │  │
+└──────────┘   └─────────────┘   └──────────┘   └──────────────┘  │
+                                                                   ▼
+┌──────────┐   ┌─────────────┐                          ┌────────────────┐
+│ CSVW     │──▶│ csvwToCube  │─────────────────────────▶│ Observations   │
+│ CSV      │──▶│ csvToCube   │─────────────────────────▶│ IR (tidy long) │
+│ JSON-stat│──▶│ readDataset │─────────────────────────▶│ (round-trip)   │
+└──────────┘   └─────────────┘                          └───────┬────────┘
+                                                                 │ buildDataset
+                                                                 ▼
+                                                         ┌───────────────┐
+                                                         │ JSON-stat 2.0 │
+                                                         │ Dataset       │
+                                                         └───────────────┘
+
+EXPORT (JSON-stat → columnar)
+   JSON-stat Dataset ──▶ readDataset ──▶ Observations IR ──┬─▶ cubeToArrow ──▶ Arrow / Parquet / DuckDB / Polars
+                                                          ├─▶ cubeToCsv   ──▶ CSV text
+                                                          └─▶ cubeToCsvw  ──▶ CSV + CSVW metadata
+```
+
+The central intermediate representation is the **Observations IR** ([`Observations`](./src/model/ir.ts)): a tidy long table with dimension columns, exactly one measure column, and an optional status column. Every source produces it; [`buildDataset`](./src/core/cubeBuilder.ts) scatters it into the row-major JSON-stat cube, and [`readDataset`](./src/core/cubeReader.ts) flattens a cube back into the IR for export.
+
+## Architecture at a glance
+
+```
+src/
+├── model/          # Pure types: JSON-stat + Observations IR (zero runtime)
+├── core/           # The engine: strides math, cube builder, cube reader
+│   ├── strides.ts      # Row-major stride arithmetic (flatPosition, multiIndex)
+│   ├── cubeBuilder.ts  # Observations IR → JSON-stat Dataset (import)
+│   └── cubeReader.ts   # JSON-stat Dataset → Observations IR (export)
+├── arrow/          # The Arrow hub (bidirectional)
+│   ├── schemaMeta.ts   # jsonstat.* metadata key contract
+│   ├── arrowToCube.ts  # Arrow Table → Observations IR (import)
+│   └── arrowFromCube.ts# Observations IR → Arrow Table (export)
+├── sources/        # Per-format adapters (optional peers, lazy, bidirectional)
+│   ├── parquet.ts  duckdb.ts  polars.ts  csvw.ts  csv.ts
+├── sink/           # serialize.ts — JSON-stat → canonical JSON string/bytes
+├── util/           # detect.ts (format sniffing), fetch.ts (loading), density.ts
+├── cli/            # args.ts (parsing) + index.ts (commander entry)
+└── index.ts        # Public API barrel + importToDataset / exportDataset
+```
+
+See [`docs/architecture.md`](./docs/architecture.md) for the layered design rationale, [`docs/mapping.md`](./docs/mapping.md) for the spec-fidelity mapping table, and [`docs/api.md`](./docs/api.md) for the full API reference.
+
+## Spec fidelity
+
+`jsonstat-io` preserves the full JSON-stat 2.0 model, not just values, in both directions:
+
+- **Roles** (`time`, `geo`, `metric`) — from Arrow schema metadata or explicit options.
+- **Category labels, units, coordinates, child hierarchies** — round-tripped via `jsonstat.*` metadata keys.
+- **Dense vs sparse value forms** — auto-decided by null ratio, or forced via options.
+- **Status** (string / array / object forms) — emitted per-row, deduplicated when uniform.
+- **Canonical key ordering** — the serializer reorders top-level keys to the canonical order for diff-stable output.
+
+See [`docs/mapping.md`](./docs/mapping.md) for the complete fidelity table.
+
+## Node vs Browser
+
+| Capability              | Node ≥18 | Browser |
+|-------------------------|:--------:|:-------:|
+| Arrow IPC               | ✅       | ✅      |
+| Parquet (`parquet-wasm`)| ✅       | ✅      |
+| DuckDB (wasm)           | ✅       | ✅      |
+| DuckDB (native)         | ✅       | —       |
+| Polars                  | ✅       | —       |
+| CSVW / CSV              | ✅       | ✅      |
+| CLI                     | ✅       | —       |
+| File paths / stdin      | ✅       | —       |
+
+In the browser, pass `Uint8Array` or `Blob` directly; the library never touches `node:fs`.
+
+## Documented seams
+
+1. **Rust/Wasm accelerator:** The pure-TS stride math and value scattering in `core/` is the performance-critical path. The public API (`buildDataset`, `arrowToCube`, `exportDataset`) is stable; an accelerator can replace the internals behind the same signatures.
+
+## Testing
+
+159 tests cover the stride math, cube builder/reader, Arrow hub round-trips, JSON-stat round-trips, export round-trips (Arrow, CSV, CSVW, Parquet), format detection, density decisions, serialization, and CLI argument parsing:
+
+```sh
+npm test          # vitest run
+npm run typecheck # tsc --noEmit
+npm run build     # tsup (ESM + CJS + .d.ts)
+```
+
+## License
+
+Apache-2.0 © Xavier Badosa

package/dist/arrow/index.cjs

@@ -0,0 +1,60 @@
+'use strict';
+
+var chunkPHLCWTHB_cjs = require('../chunk-PHLCWTHB.cjs');
+
+
+
+Object.defineProperty(exports, "ArrowConversionError", {
+  enumerable: true,
+  get: function () { return chunkPHLCWTHB_cjs.ArrowConversionError; }
+});
+Object.defineProperty(exports, "META_PREFIX", {
+  enumerable: true,
+  get: function () { return chunkPHLCWTHB_cjs.META_PREFIX; }
+});
+Object.defineProperty(exports, "arrowToCube", {
+  enumerable: true,
+  get: function () { return chunkPHLCWTHB_cjs.arrowToCube; }
+});
+Object.defineProperty(exports, "arrowToDataset", {
+  enumerable: true,
+  get: function () { return chunkPHLCWTHB_cjs.arrowToDataset; }
+});
+Object.defineProperty(exports, "buildFieldMeta", {
+  enumerable: true,
+  get: function () { return chunkPHLCWTHB_cjs.buildFieldMeta; }
+});
+Object.defineProperty(exports, "buildSchemaMeta", {
+  enumerable: true,
+  get: function () { return chunkPHLCWTHB_cjs.buildSchemaMeta; }
+});
+Object.defineProperty(exports, "cubeToArrow", {
+  enumerable: true,
+  get: function () { return chunkPHLCWTHB_cjs.cubeToArrow; }
+});
+Object.defineProperty(exports, "getFieldMeta", {
+  enumerable: true,
+  get: function () { return chunkPHLCWTHB_cjs.getFieldMeta; }
+});
+Object.defineProperty(exports, "getFieldMetaJson", {
+  enumerable: true,
+  get: function () { return chunkPHLCWTHB_cjs.getFieldMetaJson; }
+});
+Object.defineProperty(exports, "getFieldRole", {
+  enumerable: true,
+  get: function () { return chunkPHLCWTHB_cjs.getFieldRole; }
+});
+Object.defineProperty(exports, "isMeasureField", {
+  enumerable: true,
+  get: function () { return chunkPHLCWTHB_cjs.isMeasureField; }
+});
+Object.defineProperty(exports, "isStatusField", {
+  enumerable: true,
+  get: function () { return chunkPHLCWTHB_cjs.isStatusField; }
+});
+Object.defineProperty(exports, "readSchemaMeta", {
+  enumerable: true,
+  get: function () { return chunkPHLCWTHB_cjs.readSchemaMeta; }
+});
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/arrow/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.cjs"}

package/dist/arrow/index.d.cts

@@ -0,0 +1,125 @@
+export { a as ArrowConversionError, A as ArrowToCubeOptions, b as arrowToCube, c as arrowToDataset } from '../arrowToCube-BdRWZ5oG.cjs';
+import { Table, Field, Schema } from 'apache-arrow';
+import { O as Observations, R as RoleMap, D as DatasetMeta } from '../ir-BArfNxo-.cjs';
+import '../jsonstat-BX4mBLci.cjs';
+
+/**
+ * arrowFromCube — the inverse of [`arrowToCube`](./arrowToCube.ts): converts the
+ * [`Observations`](../model/ir.ts) IR into an Apache Arrow [`Table`].
+ *
+ * ## Role
+ *
+ * This is the **Phase-2 export seam**: the forward path from JSON-stat to the
+ * columnar lakehouse stack. Export = [`readDataset`](../core/cubeReader.ts)
+ * (JSON-stat → IR) → `cubeToArrow` (IR → Arrow) → Arrow-to-Parquet/DuckDB/
+ * Polars/CSV writers (which Arrow ecosystems provide natively).
+ *
+ * It is shipped in v0.1 (alongside [`cubeReader`](../core/cubeReader.ts)) for
+ * two reasons: (1) the round-trip tests use it to assert that JSON-stat → IR →
+ * Arrow → IR → JSON-stat is stable; (2) proving the IR is bidirectional now
+ * de-risks Phase 2 to "just write the sink writers".
+ *
+ * ## Mapping
+ *
+ * - Each dimension → a dictionary-encoded Utf8 column (dictionary = the
+ *   resolved category list), annotated with `jsonstat.*` field metadata so the
+ *   round-trip preserves labels/units/roles/hierarchies.
+ * - The measure → a Float64 column (nulls preserved), marked
+ *   `jsonstat.measure=true`.
+ * - The status column (if any) → a Utf8 column marked `jsonstat.status=true`.
+ * - Dataset-level metadata (label/source/updated/extension/roles/valueForm) is
+ *   written to the schema metadata.
+ */
+
+/**
+ * Convert the [`Observations`](../model/ir.ts) IR into an Arrow [`Table`].
+ *
+ * Each dimension becomes a dictionary column; the measure becomes a Float64
+ * column; the optional status becomes a Utf8 column. All `jsonstat.*`
+ * metadata is attached so the result round-trips through [`arrowToCube`](./arrowToCube.ts).
+ *
+ * @throws Error if a dimension column referenced by the model is missing.
+ */
+declare function cubeToArrow(obs: Observations): Table;
+
+/**
+ * Arrow schema metadata contract for JSON-stat.
+ *
+ * Producers (Parquet/DuckDB/Polars/CSVW adapters, or hand-built Arrow tables)
+ * annotate Arrow [`Field`](https://arrow.apache.org/docs/js/) metadata with
+ * `jsonstat.*` keys so that [`arrowToCube`](./arrowToCube.ts) can reconstruct
+ * the full JSON-stat model — not just the raw values. Without these keys the
+ * converter falls back to heuristic inference (dictionary columns = dimensions,
+ * first numeric column = measure); with them, the mapping is exact and
+ * lossless, which is what the round-trip tests require.
+ *
+ * ## Metadata key reference
+ *
+ * Field-level keys (on `Field.metadata`):
+ *
+ * | Key                          | Value                                  | Meaning |
+ * |------------------------------|----------------------------------------|---------|
+ * | `jsonstat.role`              | `"time"` / `"geo"` / `"metric"`        | Dimension role |
+ * | `jsonstat.measure`           | `"true"`                               | Marks this column as the measure (overrides type heuristics) |
+ * | `jsonstat.status`            | `"true"`                               | Marks this column as the per-row status column |
+ * | `jsonstat.label`             | string                                 | Dimension label |
+ * | `jsonstat.categoryLabels`    | JSON object: `{id: label}`             | Category labels |
+ * | `jsonstat.categoryUnits`     | JSON object: `{id: {decimals,...}}`    | Per-category unit metadata (metric role) |
+ * | `jsonstat.categoryCoords`    | JSON object: `{id: [lon,lat]}`         | Per-category coordinates (geo role) |
+ * | `jsonstat.categoryChild`     | JSON object: `{parent: [child,...]}`   | Hierarchy |
+ * | `jsonstat.categoryOrder`     | JSON array: `[id,...]`                 | Explicit category ordering (e.g. chronological) |
+ *
+ * Schema-level keys (on `Schema.metadata`):
+ *
+ * | Key                          | Value                                  | Meaning |
+ * |------------------------------|----------------------------------------|---------|
+ * | `jsonstat.label`             | string                                 | Dataset label |
+ * | `jsonstat.source`            | string                                 | Dataset source |
+ * | `jsonstat.updated`           | ISO 8601 string                        | Dataset update time |
+ * | `jsonstat.extension`         | JSON object                            | Provider extension data |
+ * | `jsonstat.valueForm`         | `"auto"`/`"dense"`/`"sparse"`          | Value emission hint |
+ *
+ * See [docs/mapping.md](../../docs/mapping.md) for the full fidelity table.
+ */
+
+/** Metadata namespace prefix used for all JSON-stat keys. */
+declare const META_PREFIX = "jsonstat.";
+/** Read a single string metadata value from a field. */
+declare function getFieldMeta(field: Field, key: string): string | undefined;
+/** Read and JSON-parse a field metadata value, with a fallback. */
+declare function getFieldMetaJson<T>(field: Field, key: string): T | undefined;
+/** Is this field marked as the measure column? */
+declare function isMeasureField(field: Field): boolean;
+/** Is this field marked as the status column? */
+declare function isStatusField(field: Field): boolean;
+/** Read the dimension role assigned to a field, if any. */
+declare function getFieldRole(field: Field): "time" | "geo" | "metric" | undefined;
+/** Build a metadata Map for a field from JSON-stat-oriented hints. */
+declare function buildFieldMeta(hints: {
+    role?: "time" | "geo" | "metric";
+    measure?: boolean;
+    status?: boolean;
+    label?: string;
+    categoryLabels?: Record<string, string>;
+    categoryUnits?: Record<string, unknown>;
+    categoryCoords?: Record<string, [number, number]>;
+    categoryChild?: Record<string, string[]>;
+    categoryOrder?: string[];
+}): Map<string, string>;
+/** Read dataset-level metadata from a schema. */
+declare function readSchemaMeta(schema: Schema): {
+    meta?: DatasetMeta;
+    roles?: RoleMap;
+    valueForm?: "auto" | "dense" | "sparse";
+};
+/** Build a schema-level metadata Map from dataset hints. */
+declare function buildSchemaMeta(hints: {
+    label?: string;
+    source?: string;
+    updated?: string;
+    extension?: Record<string, unknown>;
+    roles?: RoleMap;
+    valueForm?: "auto" | "dense" | "sparse";
+}): Map<string, string>;
+
+export { META_PREFIX, buildFieldMeta, buildSchemaMeta, cubeToArrow, getFieldMeta, getFieldMetaJson, getFieldRole, isMeasureField, isStatusField, readSchemaMeta };