jsonstat-io 0.1.0

package/dist/arrow/index.d.ts

@@ -0,0 +1,125 @@
+export { a as ArrowConversionError, A as ArrowToCubeOptions, b as arrowToCube, c as arrowToDataset } from '../arrowToCube-Mjr79ZHM.js';
+import { Table, Field, Schema } from 'apache-arrow';
+import { O as Observations, R as RoleMap, D as DatasetMeta } from '../ir-Jae2ymov.js';
+import '../jsonstat-BX4mBLci.js';
+
+/**
+ * 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 };

package/dist/arrow/index.js

@@ -0,0 +1,3 @@
+export { ArrowConversionError, META_PREFIX, arrowToCube, arrowToDataset, buildFieldMeta, buildSchemaMeta, cubeToArrow, getFieldMeta, getFieldMetaJson, getFieldRole, isMeasureField, isStatusField, readSchemaMeta } from '../chunk-IDTQZG4B.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/arrow/index.js.map

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

package/dist/arrowToCube-BdRWZ5oG.d.cts

@@ -0,0 +1,29 @@
+import { J as JsonStatDataset } from './jsonstat-BX4mBLci.cjs';
+import { Table } from 'apache-arrow';
+import { R as RoleMap, O as Observations } from './ir-BArfNxo-.cjs';
+
+declare class ArrowConversionError extends Error {
+    constructor(message: string);
+}
+interface ArrowToCubeOptions {
+    /** Explicit measure column name. Overrides detection + metadata. */
+    measure?: string;
+    /** Explicit dimension column names, in order. Overrides detection. */
+    dimensions?: string[];
+    /** Explicit status column name. Overrides metadata. */
+    status?: string;
+    /** Explicit role assignments (merge with, and take precedence over, metadata). */
+    roles?: RoleMap;
+    /** Value-form hint forwarded to the cube model. */
+    valueForm?: "auto" | "dense" | "sparse";
+}
+/**
+ * Convert an Arrow [`Table`] into the [`Observations`] IR.
+ *
+ * @throws [`ArrowConversionError`](#arrowconversionerror) on mapping problems.
+ */
+declare function arrowToCube(table: Table, options?: ArrowToCubeOptions): Observations;
+/** Convenience: convert an Arrow table straight to a JSON-stat dataset. */
+declare function arrowToDataset(table: Table, options?: ArrowToCubeOptions): Promise<JsonStatDataset>;
+
+export { type ArrowToCubeOptions as A, ArrowConversionError as a, arrowToCube as b, arrowToDataset as c };

package/dist/arrowToCube-Mjr79ZHM.d.ts

@@ -0,0 +1,29 @@
+import { J as JsonStatDataset } from './jsonstat-BX4mBLci.js';
+import { Table } from 'apache-arrow';
+import { R as RoleMap, O as Observations } from './ir-Jae2ymov.js';
+
+declare class ArrowConversionError extends Error {
+    constructor(message: string);
+}
+interface ArrowToCubeOptions {
+    /** Explicit measure column name. Overrides detection + metadata. */
+    measure?: string;
+    /** Explicit dimension column names, in order. Overrides detection. */
+    dimensions?: string[];
+    /** Explicit status column name. Overrides metadata. */
+    status?: string;
+    /** Explicit role assignments (merge with, and take precedence over, metadata). */
+    roles?: RoleMap;
+    /** Value-form hint forwarded to the cube model. */
+    valueForm?: "auto" | "dense" | "sparse";
+}
+/**
+ * Convert an Arrow [`Table`] into the [`Observations`] IR.
+ *
+ * @throws [`ArrowConversionError`](#arrowconversionerror) on mapping problems.
+ */
+declare function arrowToCube(table: Table, options?: ArrowToCubeOptions): Observations;
+/** Convenience: convert an Arrow table straight to a JSON-stat dataset. */
+declare function arrowToDataset(table: Table, options?: ArrowToCubeOptions): Promise<JsonStatDataset>;
+
+export { type ArrowToCubeOptions as A, ArrowConversionError as a, arrowToCube as b, arrowToDataset as c };

package/dist/chunk-2HY7NRKX.js

@@ -0,0 +1,259 @@
+import { totalCells, flatPosition } from './chunk-L65CRXTV.js';
+
+// src/core/cubeBuilder.ts
+var CubeBuilderError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CubeBuilderError";
+  }
+};
+function resolveDimension(id, column) {
+  let categories;
+  if (column.categoryOrder && column.categoryOrder.length > 0) {
+    const known = new Set(column.categoryOrder);
+    for (const v of column.values) {
+      if (!known.has(v)) {
+        throw new CubeBuilderError(
+          `Dimension "${id}": value "${v}" not present in categoryOrder`
+        );
+      }
+    }
+    categories = column.categoryOrder.slice();
+  } else {
+    const seen = /* @__PURE__ */ new Set();
+    categories = [];
+    for (const v of column.values) {
+      if (v == null) {
+        throw new CubeBuilderError(
+          `Dimension "${id}": contains a null category value; dimensions cannot be null`
+        );
+      }
+      if (!seen.has(v)) {
+        seen.add(v);
+        categories.push(v);
+      }
+    }
+  }
+  const position = /* @__PURE__ */ new Map();
+  categories.forEach((c, i) => position.set(c, i));
+  return { id, column, categories, position };
+}
+function buildDimensionBlock(resolved) {
+  const dimension = {};
+  const size = [];
+  for (const r of resolved) {
+    const cat = {};
+    cat.index = r.categories.slice();
+    if (r.column.categoryLabels) cat.label = { ...r.column.categoryLabels };
+    if (r.column.categoryUnits) cat.unit = { ...r.column.categoryUnits };
+    if (r.column.categoryCoordinates)
+      cat.coordinates = { ...r.column.categoryCoordinates };
+    if (r.column.categoryChild) cat.child = { ...r.column.categoryChild };
+    const dim = { category: cat };
+    if (r.column.label) dim.label = r.column.label;
+    if (r.column.href) dim.href = r.column.href;
+    dimension[r.id] = dim;
+    size.push(r.categories.length);
+  }
+  return { dimension, size };
+}
+function scatterValues(obs, resolved, size) {
+  const total = totalCells(size);
+  const dense = new Array(total).fill(null);
+  const seen = new Uint8Array(total);
+  let duplicates = 0;
+  const n = obs.measure.values.length;
+  const k = resolved.length;
+  for (let row = 0; row < n; row++) {
+    const indices = new Array(k);
+    for (let d = 0; d < k; d++) {
+      const r = resolved[d];
+      const v = r.column.values[row];
+      const p = r.position.get(v);
+      if (p === void 0) {
+        throw new CubeBuilderError(
+          `Dimension "${r.id}": value "${v}" has no position (row ${row})`
+        );
+      }
+      indices[d] = p;
+    }
+    const pos = flatPosition(indices, size);
+    if (seen[pos] === 1) duplicates++;
+    seen[pos] = 1;
+    dense[pos] = obs.measure.values[row];
+  }
+  return { dense, duplicates };
+}
+function chooseValueForm(dense, requested, threshold) {
+  const total = dense.length;
+  const nullCount = dense.reduce((acc, v) => acc + (v === null ? 1 : 0), 0);
+  const nullRatio = total === 0 ? 0 : nullCount / total;
+  let form;
+  if (requested === "dense") form = "dense";
+  else if (requested === "sparse") form = "sparse";
+  else form = nullRatio > threshold ? "sparse" : "dense";
+  if (form === "dense") {
+    return { value: dense, form, nullRatio };
+  }
+  const obj = {};
+  for (let i = 0; i < total; i++) {
+    const v = dense[i];
+    if (v !== null) obj[String(i)] = v;
+  }
+  return { value: obj, form, nullRatio };
+}
+function emitStatus(perCell, requested) {
+  if (requested === "none") return void 0;
+  const total = perCell.length;
+  if (total === 0) return void 0;
+  const first = perCell[0];
+  let uniform = true;
+  const distinct = /* @__PURE__ */ new Set();
+  for (const s of perCell) {
+    distinct.add(s);
+    if (s !== first) uniform = false;
+  }
+  if (requested === "string") return first;
+  if (requested === "array") return perCell.slice();
+  if (requested === "object") {
+    return sparseStatus(perCell);
+  }
+  if (uniform && first !== "") return first;
+  const counts = /* @__PURE__ */ new Map();
+  for (const s of perCell) counts.set(s, (counts.get(s) ?? 0) + 1);
+  let dominant = "";
+  let dominantCount = -1;
+  for (const [s, c] of counts) {
+    if (c > dominantCount) {
+      dominant = s;
+      dominantCount = c;
+    }
+  }
+  const nonDominant = total - dominantCount;
+  if (dominant !== "" && nonDominant / total < 0.4) {
+    return sparseStatus(perCell, dominant);
+  }
+  return perCell.slice();
+}
+function sparseStatus(perCell, defaultStatus) {
+  const obj = {};
+  for (let i = 0; i < perCell.length; i++) {
+    const s = perCell[i];
+    if (s === "" || s === defaultStatus) continue;
+    obj[String(i)] = s;
+  }
+  return obj;
+}
+function validate(obs, resolved) {
+  const n = obs.measure.values.length;
+  for (const r of resolved) {
+    if (r.column.values.length !== n) {
+      throw new CubeBuilderError(
+        `Dimension "${r.id}": ${r.column.values.length} values \u2260 ${n} measure values`
+      );
+    }
+  }
+  if (obs.status && obs.status.values.length !== n) {
+    throw new CubeBuilderError(
+      `Status column: ${obs.status.values.length} values \u2260 ${n} measure values`
+    );
+  }
+  const modelIds = new Set(obs.model.dimensionIds);
+  const colIds = new Set(Object.keys(obs.dimensions));
+  for (const id of modelIds) {
+    if (!colIds.has(id)) {
+      throw new CubeBuilderError(`model.dimensionIds lists "${id}" but no column exists`);
+    }
+  }
+  for (const id of colIds) {
+    if (!modelIds.has(id)) {
+      throw new CubeBuilderError(`Column "${id}" is not listed in model.dimensionIds`);
+    }
+  }
+}
+function buildDataset(obs, options = {}) {
+  const model = obs.model;
+  const dimensionIds = model.dimensionIds;
+  const resolved = dimensionIds.map((id) => {
+    const col = obs.dimensions[id];
+    if (!col) throw new CubeBuilderError(`Missing dimension column "${id}"`);
+    return resolveDimension(id, col);
+  });
+  validate(obs, resolved);
+  const { dimension, size } = buildDimensionBlock(resolved);
+  const { dense, duplicates } = scatterValues(obs, resolved, size);
+  const valueForm = options.valueForm ?? model.valueForm ?? "auto";
+  const threshold = options.sparseThreshold ?? model.sparseThreshold ?? 0.5;
+  const { value, form, nullRatio } = chooseValueForm(dense, valueForm, threshold);
+  let status;
+  if (obs.status) {
+    const statusForm = options.statusForm ?? model.statusForm ?? "auto";
+    if (statusForm !== "none") {
+      status = buildPerCellStatus(obs, resolved, size, statusForm);
+    }
+  }
+  const dataset = {
+    version: "2.0",
+    class: "dataset",
+    id: dimensionIds.slice(),
+    size,
+    dimension,
+    value
+  };
+  const role = filterRoles(model.roles);
+  if (role) dataset.role = role;
+  const meta = options.meta ?? model.meta;
+  if (meta) {
+    if (meta.label) dataset.label = meta.label;
+    if (meta.source) dataset.source = meta.source;
+    if (meta.updated) dataset.updated = meta.updated;
+    if (meta.extension) dataset.extension = meta.extension;
+  }
+  if (status) dataset.status = status;
+  return {
+    dataset,
+    diagnostics: {
+      valueForm: form,
+      nullRatio,
+      duplicates,
+      cellCount: dense.length
+    }
+  };
+}
+function buildPerCellStatus(obs, resolved, size, statusForm) {
+  const total = totalCells(size);
+  const perCell = new Array(total).fill("");
+  const n = obs.measure.values.length;
+  const k = resolved.length;
+  const statusVals = obs.status?.values;
+  if (!statusVals) return void 0;
+  for (let row = 0; row < n; row++) {
+    const indices = new Array(k);
+    for (let d = 0; d < k; d++) {
+      indices[d] = resolved[d].position.get(resolved[d].column.values[row]);
+    }
+    const pos = flatPosition(indices, size);
+    perCell[pos] = statusVals[row] ?? "";
+  }
+  return emitStatus(perCell, statusForm);
+}
+function filterRoles(roles) {
+  if (!roles) return void 0;
+  const out = {};
+  let any = false;
+  for (const key of ["time", "geo", "metric"]) {
+    const arr = roles[key];
+    if (arr && arr.length > 0) {
+      out[key] = arr.slice();
+      any = true;
+    }
+  }
+  return any ? out : void 0;
+}
+function toDataset(obs, options) {
+  return buildDataset(obs, options).dataset;
+}
+
+export { CubeBuilderError, buildDataset, toDataset };
+//# sourceMappingURL=chunk-2HY7NRKX.js.map
+//# sourceMappingURL=chunk-2HY7NRKX.js.map

package/dist/chunk-2HY7NRKX.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/cubeBuilder.ts"],"names":[],"mappings":"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","file":"chunk-2HY7NRKX.js","sourcesContent":["/**\n * CubeBuilder — turns an [`Observations`](../model/ir.ts) IR into a JSON-stat\n * [`Dataset`](../model/jsonstat.ts).\n *\n * This is the central transform of the importer: a tidy long table → an\n * N-dimensional cube laid out in row-major order (\"what does not change, first\";\n * see wiki/format-specification.md).\n *\n * Responsibilities:\n *  1. Resolve dimension order and enumerate categories (first-seen order unless\n *     `categoryOrder` pins it).\n *  2. Build the `dimension` block with `category.index`/`label`/`unit`/\n *     `coordinates`/`child` and dimension `label`.\n *  3. Scatter the measure values into a row-major `value` array (dense) or a\n *     sparse object, per [`CubeModel.valueForm`](../model/ir.ts) and the null\n *     ratio threshold.\n *  4. Emit `status` in the most compact correct form (string/array/object).\n *  5. Attach `role`, and dataset-level `label`/`source`/`updated`/`extension`.\n *\n * Pure: no I/O, no side effects. All index math delegated to\n * [`strides`](./strides.ts).\n */\n\nimport type {\n  DatasetMeta,\n  DimensionColumn,\n  Observations,\n} from \"../model/ir\";\nimport type {\n  JsonStatCategory,\n  JsonStatDataset,\n  JsonStatDimension,\n  JsonStatRole,\n  JsonStatStatus,\n  JsonStatValue,\n} from \"../model/jsonstat\";\nimport { enumerateCells, flatPosition, totalCells } from \"./strides\";\n\n// ---------------------------------------------------------------------------\n// Errors\n// ---------------------------------------------------------------------------\n\n/** Thrown when the IR violates a structural invariant the builder relies on. */\nexport class CubeBuilderError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"CubeBuilderError\";\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Options\n// ---------------------------------------------------------------------------\n\nexport interface BuildOptions {\n  /** Override the emitted value form. Defaults to `model.valueForm ?? \"auto\"`. */\n  valueForm?: \"auto\" | \"dense\" | \"sparse\";\n  /** Override the sparse threshold (null ratio). Defaults to 0.5. */\n  sparseThreshold?: number;\n  /** Override status emission. Defaults to `model.statusForm ?? \"auto\"`. */\n  statusForm?: \"auto\" | \"array\" | \"string\" | \"object\" | \"none\";\n  /** Override dataset metadata. Defaults to `model.meta`. */\n  meta?: DatasetMeta;\n}\n\n// ---------------------------------------------------------------------------\n// Category resolution\n// ---------------------------------------------------------------------------\n\n/**\n * Resolved view of a dimension: the ordered category IDs and a map from\n * category ID → its position (0-based). The position is what gets multiplied\n * by the dimension's stride when scattering values.\n */\ninterface ResolvedDimension {\n  id: string;\n  column: DimensionColumn;\n  categories: string[];\n  position: Map<string, number>;\n}\n\nfunction resolveDimension(id: string, column: DimensionColumn): ResolvedDimension {\n  let categories: string[];\n  if (column.categoryOrder && column.categoryOrder.length > 0) {\n    // Honor an explicit order, but verify every observed value is covered.\n    const known = new Set(column.categoryOrder);\n    for (const v of column.values) {\n      if (!known.has(v)) {\n        throw new CubeBuilderError(\n          `Dimension \"${id}\": value \"${v}\" not present in categoryOrder`,\n        );\n      }\n    }\n    categories = column.categoryOrder.slice();\n  } else {\n    // First-seen order, deduplicated.\n    const seen = new Set<string>();\n    categories = [];\n    for (const v of column.values) {\n      if (v == null) {\n        throw new CubeBuilderError(\n          `Dimension \"${id}\": contains a null category value; dimensions cannot be null`,\n        );\n      }\n      if (!seen.has(v)) {\n        seen.add(v);\n        categories.push(v);\n      }\n    }\n  }\n  const position = new Map<string, number>();\n  categories.forEach((c, i) => position.set(c, i));\n  return { id, column, categories, position };\n}\n\n// ---------------------------------------------------------------------------\n// Dimension block\n// ---------------------------------------------------------------------------\n\n/** Build the JSON-stat `dimension` object and the `size` array. */\nfunction buildDimensionBlock(\n  resolved: ResolvedDimension[],\n): { dimension: Record<string, JsonStatDimension>; size: number[] } {\n  const dimension: Record<string, JsonStatDimension> = {};\n  const size: number[] = [];\n  for (const r of resolved) {\n    const cat: JsonStatCategory = {};\n    // index: array form is the canonical, simplest representation.\n    cat.index = r.categories.slice();\n    if (r.column.categoryLabels) cat.label = { ...r.column.categoryLabels };\n    if (r.column.categoryUnits) cat.unit = { ...r.column.categoryUnits };\n    if (r.column.categoryCoordinates)\n      cat.coordinates = { ...r.column.categoryCoordinates };\n    if (r.column.categoryChild) cat.child = { ...r.column.categoryChild };\n\n    const dim: JsonStatDimension = { category: cat };\n    if (r.column.label) dim.label = r.column.label;\n    if (r.column.href) dim.href = r.column.href;\n    dimension[r.id] = dim;\n    size.push(r.categories.length);\n  }\n  return { dimension, size };\n}\n\n// ---------------------------------------------------------------------------\n// Value scattering (long table → row-major cube)\n// ---------------------------------------------------------------------------\n\n/**\n * Scatter measure values into a dense array of length `total` (null-filled)\n * using row-major positions computed from the resolved dimensions.\n *\n * If two observations map to the same cell, the *last* one wins and a warning\n * is surfaced via the returned diagnostics (the cube model assumes one value\n * per cell; duplicates indicate an ill-formed source).\n */\nfunction scatterValues(\n  obs: Observations,\n  resolved: ResolvedDimension[],\n  size: number[],\n): { dense: (number | null)[]; duplicates: number } {\n  const total = totalCells(size);\n  const dense: (number | null)[] = new Array(total).fill(null);\n  const seen = new Uint8Array(total); // 0 = empty, 1 = filled\n  let duplicates = 0;\n  const n = obs.measure.values.length;\n  const k = resolved.length;\n  for (let row = 0; row < n; row++) {\n    const indices = new Array<number>(k);\n    for (let d = 0; d < k; d++) {\n      const r = resolved[d];\n      const v = r.column.values[row];\n      const p = r.position.get(v);\n      if (p === undefined) {\n        // resolveDimension guarantees coverage when categoryOrder is used, but\n        // guard regardless.\n        throw new CubeBuilderError(\n          `Dimension \"${r.id}\": value \"${v}\" has no position (row ${row})`,\n        );\n      }\n      indices[d] = p;\n    }\n    const pos = flatPosition(indices, size);\n    if (seen[pos] === 1) duplicates++;\n    seen[pos] = 1;\n    dense[pos] = obs.measure.values[row];\n  }\n  return { dense, duplicates };\n}\n\n// ---------------------------------------------------------------------------\n// Value form selection (dense vs sparse)\n// ---------------------------------------------------------------------------\n\n/**\n * Decide between dense (array) and sparse (object) `value` representation.\n *\n * Per wiki/sparse-cubes.md: sparse is preferred when many cells are null. The\n * threshold is the null ratio above which the object form is more compact.\n */\nfunction chooseValueForm(\n  dense: (number | null)[],\n  requested: \"auto\" | \"dense\" | \"sparse\",\n  threshold: number,\n): { value: JsonStatValue; form: \"dense\" | \"sparse\"; nullRatio: number } {\n  const total = dense.length;\n  const nullCount = dense.reduce<number>((acc, v) => acc + (v === null ? 1 : 0), 0);\n  const nullRatio = total === 0 ? 0 : nullCount / total;\n\n  let form: \"dense\" | \"sparse\";\n  if (requested === \"dense\") form = \"dense\";\n  else if (requested === \"sparse\") form = \"sparse\";\n  else form = nullRatio > threshold ? \"sparse\" : \"dense\";\n\n  if (form === \"dense\") {\n    return { value: dense, form, nullRatio };\n  }\n  // Sparse object: only non-null cells, keyed by stringified flat position.\n  const obj: Record<string, number> = {};\n  for (let i = 0; i < total; i++) {\n    const v = dense[i];\n    if (v !== null) obj[String(i)] = v;\n  }\n  return { value: obj, form, nullRatio };\n}\n\n// ---------------------------------------------------------------------------\n// Status emission\n// ---------------------------------------------------------------------------\n\n/**\n * Emit `status` in the most compact correct form.\n *\n * - If all statuses are identical and non-empty → string form.\n * - Else if few distinct non-default statuses → object form (sparse status).\n * - Else → array form (one entry per cell, aligned with dense `value`).\n *\n * The caller passes the *dense* per-cell status array (length = total cells).\n */\nfunction emitStatus(\n  perCell: string[],\n  requested: \"auto\" | \"array\" | \"string\" | \"object\" | \"none\",\n): JsonStatStatus | undefined {\n  if (requested === \"none\") return undefined;\n  const total = perCell.length;\n  if (total === 0) return undefined;\n\n  // Collect distinct statuses and whether they're uniform.\n  const first = perCell[0];\n  let uniform = true;\n  const distinct = new Set<string>();\n  for (const s of perCell) {\n    distinct.add(s);\n    if (s !== first) uniform = false;\n  }\n\n  if (requested === \"string\") return first; // caller's explicit choice\n  if (requested === \"array\") return perCell.slice();\n\n  if (requested === \"object\") {\n    return sparseStatus(perCell);\n  }\n\n  // auto:\n  if (uniform && first !== \"\") return first;\n  // If most cells share the dominant status, sparse object form is compact.\n  const counts = new Map<string, number>();\n  for (const s of perCell) counts.set(s, (counts.get(s) ?? 0) + 1);\n  let dominant = \"\";\n  let dominantCount = -1;\n  for (const [s, c] of counts) {\n    if (c > dominantCount) {\n      dominant = s;\n      dominantCount = c;\n    }\n  }\n  // Use object form when fewer than ~40% of cells deviate from the dominant.\n  const nonDominant = total - dominantCount;\n  if (dominant !== \"\" && nonDominant / total < 0.4) {\n    return sparseStatus(perCell, dominant);\n  }\n  return perCell.slice();\n}\n\n/** Build the sparse object status form. Omits `defaultStatus` entries. */\nfunction sparseStatus(\n  perCell: string[],\n  defaultStatus?: string,\n): Record<string, string> {\n  const obj: Record<string, string> = {};\n  for (let i = 0; i < perCell.length; i++) {\n    const s = perCell[i];\n    if (s === \"\" || s === defaultStatus) continue;\n    obj[String(i)] = s;\n  }\n  return obj;\n}\n\n// ---------------------------------------------------------------------------\n// Validation\n// ---------------------------------------------------------------------------\n\n/** Validate the structural invariants the builder relies on. */\nfunction validate(obs: Observations, resolved: ResolvedDimension[]): void {\n  const n = obs.measure.values.length;\n  for (const r of resolved) {\n    if (r.column.values.length !== n) {\n      throw new CubeBuilderError(\n        `Dimension \"${r.id}\": ${r.column.values.length} values ≠ ${n} measure values`,\n      );\n    }\n  }\n  if (obs.status && obs.status.values.length !== n) {\n    throw new CubeBuilderError(\n      `Status column: ${obs.status.values.length} values ≠ ${n} measure values`,\n    );\n  }\n  // Every model.dimensionIds entry must have a column, and vice versa.\n  const modelIds = new Set(obs.model.dimensionIds);\n  const colIds = new Set(Object.keys(obs.dimensions));\n  for (const id of modelIds) {\n    if (!colIds.has(id)) {\n      throw new CubeBuilderError(`model.dimensionIds lists \"${id}\" but no column exists`);\n    }\n  }\n  for (const id of colIds) {\n    if (!modelIds.has(id)) {\n      throw new CubeBuilderError(`Column \"${id}\" is not listed in model.dimensionIds`);\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Build result & public API\n// ---------------------------------------------------------------------------\n\nexport interface BuildResult {\n  dataset: JsonStatDataset;\n  /** Diagnostics from the build (non-fatal observations). */\n  diagnostics: {\n    valueForm: \"dense\" | \"sparse\";\n    nullRatio: number;\n    duplicates: number;\n    cellCount: number;\n  };\n}\n\n/**\n * Build a JSON-stat [`Dataset`](../model/jsonstat.ts) from an\n * [`Observations`](../model/ir.ts) IR.\n *\n * @throws [`CubeBuilderError`](#cubebuildererror) on invariant violations.\n */\nexport function buildDataset(obs: Observations, options: BuildOptions = {}): BuildResult {\n  const model = obs.model;\n  const dimensionIds = model.dimensionIds;\n\n  // Resolve dimensions in the model-declared order (this defines stride order).\n  const resolved = dimensionIds.map((id) => {\n    const col = obs.dimensions[id];\n    if (!col) throw new CubeBuilderError(`Missing dimension column \"${id}\"`);\n    return resolveDimension(id, col);\n  });\n\n  validate(obs, resolved);\n\n  const { dimension, size } = buildDimensionBlock(resolved);\n\n  // Scatter measure values into the dense row-major array.\n  const { dense, duplicates } = scatterValues(obs, resolved, size);\n\n  // Choose value form.\n  const valueForm = options.valueForm ?? model.valueForm ?? \"auto\";\n  const threshold = options.sparseThreshold ?? model.sparseThreshold ?? 0.5;\n  const { value, form, nullRatio } = chooseValueForm(dense, valueForm, threshold);\n\n  // Status: if present, build a dense per-cell status array aligned with `value`.\n  let status: JsonStatStatus | undefined;\n  if (obs.status) {\n    const statusForm = options.statusForm ?? model.statusForm ?? \"auto\";\n    if (statusForm !== \"none\") {\n      status = buildPerCellStatus(obs, resolved, size, statusForm);\n    }\n  }\n\n  const dataset: JsonStatDataset = {\n    version: \"2.0\",\n    class: \"dataset\",\n    id: dimensionIds.slice(),\n    size,\n    dimension,\n    value,\n  };\n\n  // Roles (only attach defined role keys, and only if non-empty).\n  const role = filterRoles(model.roles);\n  if (role) dataset.role = role;\n\n  // Dataset-level metadata.\n  const meta = options.meta ?? model.meta;\n  if (meta) {\n    if (meta.label) dataset.label = meta.label;\n    if (meta.source) dataset.source = meta.source;\n    if (meta.updated) dataset.updated = meta.updated;\n    if (meta.extension) dataset.extension = meta.extension;\n  }\n\n  if (status) dataset.status = status;\n\n  return {\n    dataset,\n    diagnostics: {\n      valueForm: form,\n      nullRatio,\n      duplicates,\n      cellCount: dense.length,\n    },\n  };\n}\n\n/**\n * Build a per-cell status array by scattering the status column into row-major\n * order, then reduce to the requested form. Cells with no observation default\n * to \"\" (empty), which the emitter treats as \"no status\".\n */\nfunction buildPerCellStatus(\n  obs: Observations,\n  resolved: ResolvedDimension[],\n  size: number[],\n  statusForm: \"auto\" | \"array\" | \"string\" | \"object\" | \"none\",\n): JsonStatStatus | undefined {\n  const total = totalCells(size);\n  const perCell: string[] = new Array(total).fill(\"\");\n  const n = obs.measure.values.length;\n  const k = resolved.length;\n  const statusVals = obs.status?.values;\n  if (!statusVals) return undefined;\n  for (let row = 0; row < n; row++) {\n    const indices = new Array<number>(k);\n    for (let d = 0; d < k; d++) {\n      indices[d] = resolved[d].position.get(resolved[d].column.values[row])!;\n    }\n    const pos = flatPosition(indices, size);\n    perCell[pos] = statusVals[row] ?? \"\";\n  }\n  return emitStatus(perCell, statusForm);\n}\n\n/** Return a role object with only non-empty arrays, or undefined if all empty. */\nfunction filterRoles(roles?: JsonStatRole): JsonStatRole | undefined {\n  if (!roles) return undefined;\n  const out: JsonStatRole = {};\n  let any = false;\n  for (const key of [\"time\", \"geo\", \"metric\"] as const) {\n    const arr = roles[key];\n    if (arr && arr.length > 0) {\n      out[key] = arr.slice();\n      any = true;\n    }\n  }\n  return any ? out : undefined;\n}\n\n/**\n * Convenience: build and return *just* the dataset (no diagnostics).\n * Useful for the common programmatic case.\n */\nexport function toDataset(obs: Observations, options?: BuildOptions): JsonStatDataset {\n  return buildDataset(obs, options).dataset;\n}\n\n// Re-export for consumers who want to enumerate cells themselves.\nexport { enumerateCells };\n"]}