@honua/app-platform 0.1.12 → 0.1.13

package/columnar/geoarrow-aggregate.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Bounded, deterministic reduction of a normative Honua GeoArrow batch.
+ *
+ * Every other columnar operation is row-preserving or row-dropping. This one
+ * reduces: it scans only the packed buffer views returned by
+ * {@link inspectGeoArrowBatch}, accumulates into group-indexed scalars, and
+ * emits a result batch whose row count is the group count. No input row is ever
+ * materialized as an object, `decodeGeoArrowBatch` is never called, and peak
+ * retained memory is bounded by the group ceiling rather than the row count.
+ *
+ * The result is a dependency-free Honua columnar batch carrying the
+ * `honua.aggregate` layout (see {@link readGeoArrowAggregateBatch}) rather than
+ * a GeoArrow batch, because the normative GeoArrow layout admits exactly one
+ * geometry column plus optional temporal, dictionary, and feature-id columns
+ * and therefore has nowhere to carry metric columns.
+ *
+ * ## Determinism
+ *
+ * A reduction that is not deterministic is not cacheable, and this one is the
+ * first columnar operation whose output is small enough to be worth caching.
+ * Three things could otherwise make the same input produce different output.
+ *
+ * 1. **Worker scheduling.** The scan yields to the host task queue so a cancel
+ *    can land, but the arithmetic never observes the scheduler: accumulation is
+ *    one sequential pass over the packed buffers, and a yield only suspends it.
+ *    The yield cadence is therefore a pure performance knob — varying
+ *    `yieldIntervalRows` cannot change a single output byte.
+ * 2. **Group ordering.** Groups are emitted ascending by key with the declared
+ *    null group last, never in first-seen or hash-iteration order, so two
+ *    batches holding the same rows in a different layout produce the same
+ *    output row order. Duplicate dictionary entries encoding the same string
+ *    are canonicalized to one group rather than to whichever index appeared
+ *    first.
+ * 3. **Floating-point associativity.** `count`, `min`, and `max` are
+ *    order-independent by construction. `sum` and `mean` are not, and a naive
+ *    running total makes the reported value depend on the order the rows were
+ *    visited in: `[1e16, 1, 1, -1e16]` accumulates left to right to `0` when
+ *    the exact answer is `2`. Both use Kahan–Babuška–Neumaier compensation
+ *    instead, carrying every addition's discarded low-order bits in a second
+ *    group-indexed accumulator and folding them in once at the end. That is a
+ *    bound on the error rather than a proof of bit-identity under every
+ *    conceivable permutation, but it removes the cancellation family that makes
+ *    naive accumulation order-dependent in practice.
+ *
+ * @experimental
+ */
+import { type GeoArrowConversionLimits } from "./geoarrow-types.js";
+import type { ColumnarBatchV1 } from "./types.js";
+import type { ColumnarWorkerOperation } from "./worker.js";
+/** Honua's dependency-free aggregate-result layout, recorded in schema metadata. */
+export declare const HONUA_GEOARROW_AGGREGATE_LAYOUT_VERSION: "1.0";
+/** Default ceiling on distinct groups, including the declared null group. */
+export declare const DEFAULT_GEOARROW_AGGREGATE_MAX_GROUPS = 65536;
+/**
+ * Rows scanned between cooperative abort checks. Well inside the 65,536-row
+ * ceiling the columnar data-plane contract requires.
+ */
+export declare const GEOARROW_AGGREGATE_ABORT_CHECK_ROWS = 8192;
+/** Rows scanned between cooperative event-loop yields, so a cancel can land. */
+export declare const DEFAULT_GEOARROW_AGGREGATE_YIELD_ROWS = 16384;
+/**
+ * Inclusive magnitude ceiling for a spatial-grid cell index on either axis,
+ * chosen so a packed `(x, y)` cell key stays an exact safe integer.
+ */
+export declare const GEOARROW_AGGREGATE_MAX_GRID_CELL_INDEX = 33554432;
+/** Reducers supported over a declared numeric column. */
+export type GeoArrowAggregateMetricKind = "count" | "sum" | "min" | "max" | "mean";
+/** Numeric columns readable straight from a GeoArrow batch's packed buffers. */
+export type GeoArrowAggregateNumericColumn = "featureId" | "temporal" | "x" | "y" | "z" | "m";
+/** One declared output metric. */
+export interface GeoArrowAggregateMetricSpec {
+    /** Output field name. Must be unique and must not collide with a group field. */
+    readonly name: string;
+    readonly kind: GeoArrowAggregateMetricKind;
+    /**
+     * Source column. Required for `sum`, `min`, `max`, and `mean`. Optional for
+     * `count`: omitted counts rows in the group, supplied counts non-null values.
+     */
+    readonly column?: GeoArrowAggregateNumericColumn;
+}
+/** Calendar-independent truncation units applied to the temporal column. */
+export type GeoArrowAggregateTruncationUnit = "second" | "minute" | "hour" | "day";
+/** Group by the batch's dictionary column, keyed by its decoded value. */
+export interface GeoArrowAggregateDictionaryGroupSpec {
+    readonly kind: "dictionary";
+}
+/** Group by the batch's temporal column truncated to a fixed-width unit. */
+export interface GeoArrowAggregateTemporalGroupSpec {
+    readonly kind: "temporal";
+    readonly unit: GeoArrowAggregateTruncationUnit;
+}
+/** Group by a regular grid cell derived from the geometry column. */
+export interface GeoArrowAggregateGridGroupSpec {
+    readonly kind: "grid";
+    /** Cell size in source CRS units: one positive number, or `[x, y]`. */
+    readonly cellSize: number | readonly [number, number];
+    /** Grid origin in source CRS units. Defaults to `[0, 0]`. */
+    readonly origin?: readonly [number, number];
+}
+export type GeoArrowAggregateGroupSpec = GeoArrowAggregateDictionaryGroupSpec | GeoArrowAggregateTemporalGroupSpec | GeoArrowAggregateGridGroupSpec;
+/** How rows whose group key is null (or whose geometry is empty) are treated. */
+export type GeoArrowAggregateNullKeyPolicy = "null-group" | "skip";
+/** Options for the bounded GeoArrow aggregation worker operation. */
+export interface CreateGeoArrowAggregateOperationOptions {
+    /** Stable id assigned to the aggregated output batch. */
+    readonly id: string;
+    /**
+     * Schema id for the aggregated field set. It is also written as the result
+     * `identity.schemaVersion`, so it must change whenever the group or metric
+     * specification changes.
+     */
+    readonly schemaId: string;
+    readonly group: GeoArrowAggregateGroupSpec;
+    readonly metrics: readonly GeoArrowAggregateMetricSpec[];
+    /** Output group field name. Grid grouping emits `<name>_x` and `<name>_y`. */
+    readonly groupField?: string;
+    /** Ceiling on distinct groups. Defaults to {@link DEFAULT_GEOARROW_AGGREGATE_MAX_GROUPS}. */
+    readonly maxGroups?: number;
+    /** Null-key policy. Defaults to `"null-group"`. */
+    readonly nullKeys?: GeoArrowAggregateNullKeyPolicy;
+    /** Rows scanned between cooperative event-loop yields. */
+    readonly yieldIntervalRows?: number;
+    /** Conversion ceilings applied to the input inspection and the output batch. */
+    readonly limits?: GeoArrowConversionLimits;
+}
+/** One decoded aggregate row: the group key plus every declared metric. */
+export interface GeoArrowAggregateRow {
+    /**
+     * Dictionary value, truncated timestamp in the source temporal unit, or
+     * `[cellX, cellY]`. `null` identifies the declared null group.
+     */
+    readonly key: string | number | readonly [number, number] | null;
+    /** Metric values by declared name; `null` when a group had no non-null input. */
+    readonly metrics: Readonly<Record<string, number | null>>;
+}
+/** Source provenance recorded on an aggregate result batch. */
+export interface GeoArrowAggregateSource {
+    readonly batchId: string;
+    readonly schemaId: string;
+    readonly rowCount: number;
+    readonly planId: string;
+    readonly sourceId: string;
+    readonly sourceVersion: string;
+    /** Rows dropped because their group key was null under the `skip` policy. */
+    readonly skippedRows: number;
+}
+/** A decoded aggregate result batch. */
+export interface GeoArrowAggregateResult {
+    readonly batch: ColumnarBatchV1;
+    readonly group: GeoArrowAggregateGroupSpec;
+    readonly groupField: string;
+    readonly metrics: readonly GeoArrowAggregateMetricSpec[];
+    readonly nullKeys: GeoArrowAggregateNullKeyPolicy;
+    readonly maxGroups: number;
+    readonly source: GeoArrowAggregateSource;
+    readonly rows: readonly GeoArrowAggregateRow[];
+}
+/**
+ * Create a bounded GeoArrow aggregation for registration with
+ * `startColumnarWorkerHost`.
+ *
+ * The returned operation scans the input batch's packed buffers exactly once,
+ * accumulates into group-indexed scalars, and emits a `honua.aggregate` result
+ * batch. It fails closed — always before the output batch is allocated — when
+ * the group ceiling is exceeded, when a metric value is non-finite, and when a
+ * declared column does not exist in the batch. The input batch is never
+ * mutated.
+ */
+export declare function createGeoArrowAggregateOperation(options: CreateGeoArrowAggregateOperationOptions): ColumnarWorkerOperation;
+/**
+ * Decode a `honua.aggregate` result batch produced by
+ * {@link createGeoArrowAggregateOperation}.
+ *
+ * Materialization is bounded by the group count, which the producing operation
+ * already capped, so this is always safe to call on a result the SDK produced.
+ */
+export declare function readGeoArrowAggregateBatch(batch: ColumnarBatchV1, limits?: GeoArrowConversionLimits): GeoArrowAggregateResult;
+//# sourceMappingURL=geoarrow-aggregate.d.ts.map

package/columnar/geoarrow-aggregate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geoarrow-aggregate.d.ts","sourceRoot":"","sources":["../../../src/columnar/geoarrow-aggregate.ts"],"names":[],"mappings":"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"}