@honua/react 0.1.1-beta.0 → 0.1.4-beta.0

package/query-planner/planner.js

@@ -5,11 +5,12 @@ import { compileDuckDbQuery, compileDuckDbQueryV2 } from "./duckdb.js";
 import { compileGeoServicesQuery } from "./geoservices.js";
 import { compileGrpcQuery } from "./grpc.js";
 import { createGeoParquetQueryIr, createQueryIr, deepFreeze, queryFromCanonical } from "./ir.js";
-import { compileOdataQuery } from "./odata.js";
+import { compileOdataQuery, odataProtocolQueryCompiler } from "./odata-v1.js";
 import { compileOgcApiFeaturesQuery } from "./ogc-features.js";
+import { createQueryPlanRepresentationDecision, normalizeRepresentationRequest } from "./representation.js";
 import { parseGeoParquetResourceHandle } from "./resource.js";
 import { HonuaQueryPlanExecutionError, HonuaQueryPlanningError, MAX_LOCAL_MATERIALIZATION_ROWS, QUERY_PLAN_DIAGNOSTICS_VERSION, QUERY_PLAN_KIND, QUERY_PLAN_V2_VERSION, QUERY_PLAN_VERSION, } from "./types.js";
-import { compileWfsQuery } from "./wfs.js";
+import { compileWfsQuery, wfsProtocolQueryCompiler } from "./wfs-v1.js";
 export function explainQuery(options) {
     const resource = ownGeoParquetResource(options);
     if (!resource && options.descriptor.protocol === "geoparquet")
@@ -19,6 +20,9 @@ export function explainQuery(options) {
     const fallback = normalizeFallback(options.fallback);
     const estimates = normalizeEstimates(options.estimates);
     const executionMode = normalizeExecutionMode(options.executionMode);
+    // Representation is chosen before any step is compiled so an unsatisfiable
+    // explicit pin fails closed before the plan takes shape.
+    const representation = createQueryPlanRepresentationDecision(ir, estimates, normalizeRepresentationRequest(options.representation));
     let baseSteps;
     let pushdown;
     if (ir.query.aggregation && !ir.source.capabilities.includes("queryAggregate")) {
@@ -30,7 +34,8 @@ export function explainQuery(options) {
         }
         rejectUnsafeEstimate(fallback, estimates.rows, estimates.bytes);
         const ogcFallback = ir.source.protocol === "ogc-features";
-        const inputQuery = localAggregateInputQuery(ir.query, ir.query.aggregation, fallback.maxRows, options.descriptor.schema?.primaryKey, { preserveGeometry: ogcFallback, adapterOwnsLookahead: ogcFallback });
+        const adapterOwnsLookahead = ogcFallback || ir.source.protocol === "odata" || ir.source.protocol === "wfs";
+        const inputQuery = localAggregateInputQuery(ir.query, ir.query.aggregation, fallback.maxRows, options.descriptor.schema?.primaryKey, { preserveGeometry: ogcFallback, adapterOwnsLookahead });
         baseSteps = [
             {
                 id: "remote-input",
@@ -86,8 +91,8 @@ export function explainQuery(options) {
     const { fidelity, losses } = summarizeFidelity(steps);
     const bounds = summarizePlanBounds(steps);
     const cache = createCacheDecision(options.cache);
-    const validity = createPlanValidity(ir, provenance, capabilityPolicy, fallback, executionMode);
-    const warnings = createPlanWarnings(baseSteps, ir.source);
+    const validity = createPlanValidity(ir, provenance, capabilityPolicy, fallback, executionMode, representation.selected);
+    const warnings = createPlanWarnings(baseSteps, ir.source, representation);
     const unsigned = {
         kind: QUERY_PLAN_KIND,
         version: ir.version === "2.0" ? QUERY_PLAN_V2_VERSION : QUERY_PLAN_VERSION,
@@ -102,6 +107,7 @@ export function explainQuery(options) {
         cache,
         provenance,
         validity,
+        representation,
         estimates,
         steps,
         warnings,
@@ -120,9 +126,9 @@ function compileRemoteQuery(source, query, operation = "query") {
         case "ogc-features":
             return ogcQueryAllWireRequest(compileOgcApiFeaturesQuery(source, query), operation);
         case "wfs":
-            return compileWfsQuery(source, query);
+            return wfsProtocolQueryCompiler.compile({ source, query, operation });
         case "odata":
-            return compileOdataQuery(source, query);
+            return odataProtocolQueryCompiler.compile({ source, query, operation });
         case "geoparquet":
             return isGeoParquetV2Source(source)
                 ? compileDuckDbQueryV2(source, query)
@@ -191,14 +197,14 @@ export function validateQueryPlanSnapshot(plan) {
         throw invalidPersistedPlan();
     return snapshot.plan;
 }
-/** Canonical persistence boundary for accepted v1/v2 query plans. */
+/** Canonical persistence boundary; validated legacy protocol artifacts are upgraded before serialization. */
 export function serializeQueryPlan(plan) {
     const snapshot = persistedPlanSnapshot(plan);
     if (snapshot.hash !== snapshot.plan.fingerprint)
         throw invalidPersistedPlan();
     return canonicalStringify(toJsonValue(snapshot.plan));
 }
-/** Parse a persisted plan without retaining invalid JSON or credential-bearing v1 locators. */
+/** Parse a persisted plan, upgrading validated legacy protocol artifacts without retaining unsafe input. */
 export function parseQueryPlan(serialized) {
     if (typeof serialized !== "string")
         throw invalidPersistedPlan();
@@ -255,6 +261,7 @@ export function migrateGeoParquetQueryPlanV1(legacyPlan, resourceValue) {
         ...(parsed.ir.source.sourceVersion !== undefined ? { sourceVersion: parsed.ir.source.sourceVersion } : {}),
         authorizationScope: parsed.ir.source.authorizationScope,
         estimates: parsed.estimates,
+        representation: normalizeRepresentationRequest(persistedRepresentationRequest(parsed)),
     });
 }
 function ownGeoParquetResource(options) {
@@ -294,15 +301,11 @@ function assertPlanPersistenceSafe(plan) {
                 throw invalidPersistedPlan();
             }
         }
-        for (const step of plan.steps) {
-            if (step.engine !== "remote")
-                continue;
-            const expected = compileRemoteQuery(plan.ir.source, step.query, step.operation);
-            if (!sameCanonicalValue(step.compiled, expected)) {
-                throw invalidPersistedPlan();
-            }
-        }
-        const expected = rebuildQueryPlanV1(plan);
+        const expected = isLegacyOdataQueryPlanV1(plan)
+            ? rebuildLegacyOdataQueryPlanV1(plan)
+            : isLegacyWfsQueryPlanV1(plan)
+                ? rebuildLegacyWfsQueryPlanV1(plan)
+                : rebuildQueryPlanV1(plan);
         if (canonicalStringify(toJsonValue(plan)) !== canonicalStringify(toJsonValue(expected))) {
             throw invalidPersistedPlan();
         }
@@ -324,6 +327,10 @@ function assertStructuredDiagnostics(plan) {
     const fallback = normalizeFallback(plan.fallback);
     const estimates = normalizeEstimates(plan.estimates);
     const executionMode = normalizeExecutionMode(plan.validity.executionMode);
+    // Re-derive the representation decision from the persisted request plus the
+    // persisted IR/estimates, so a tampered `selected`, `available`, or `reason`
+    // cannot survive the canonical comparison below.
+    const representation = createQueryPlanRepresentationDecision(plan.ir, estimates, normalizeRepresentationRequest(persistedRepresentationRequest(plan)));
     if (!sameCanonicalValue(plan.fallback, fallback) || !sameCanonicalValue(plan.estimates, estimates)) {
         throw invalidPersistedPlan();
     }
@@ -363,8 +370,9 @@ function assertStructuredDiagnostics(plan) {
         bounds: summarizePlanBounds(expectedSteps),
         cache: createCacheDecision(persistedCacheOptions(plan.cache)),
         provenance: expectedProvenance,
-        validity: createPlanValidity(plan.ir, expectedProvenance, plan.capabilityPolicy, fallback, executionMode),
-        warnings: createPlanWarnings(plan.steps, plan.ir.source),
+        validity: createPlanValidity(plan.ir, expectedProvenance, plan.capabilityPolicy, fallback, executionMode, representation.selected),
+        representation,
+        warnings: createPlanWarnings(plan.steps, plan.ir.source, representation),
     };
     const actual = {
         diagnosticsVersion: plan.diagnosticsVersion,
@@ -375,11 +383,19 @@ function assertStructuredDiagnostics(plan) {
         cache: plan.cache,
         provenance: plan.provenance,
         validity: plan.validity,
+        representation: plan.representation,
         warnings: plan.warnings,
     };
     if (!sameCanonicalValue(actual, expected))
         throw invalidPersistedPlan();
 }
+/** Read the persisted representation request without trusting any other member of the decision. */
+function persistedRepresentationRequest(plan) {
+    const decision = plan.representation;
+    if (decision === null || typeof decision !== "object" || Array.isArray(decision))
+        throw invalidPersistedPlan();
+    return decision.requested;
+}
 function persistedStepPushdown(step) {
     if (step.engine === "client") {
         if (step.operation !== "aggregate")
@@ -415,8 +431,9 @@ function rebuildPersistedProvenance(plan) {
     });
 }
 /** Rebuild legacy plans through the same pure planner to bind every persisted step to the IR. */
-function rebuildQueryPlanV1(plan) {
+function rebuildQueryPlanV1(plan, options = {}) {
     const source = plan.ir.source;
+    const sourceAuthorityFingerprint = parseSourceAuthorityFingerprint(source.authorityFingerprint);
     const capabilitiesValue = parsePlanCapabilities(source.capabilities);
     const geometryProperty = parseOptionalPlanMetadata(source.geometryProperty);
     const primaryKey = persistedV1FallbackPrimaryKey(plan);
@@ -479,10 +496,110 @@ function rebuildQueryPlanV1(plan) {
         ...(source.schemaVersion !== undefined ? { schemaVersion: source.schemaVersion } : {}),
         ...(source.sourceVersion !== undefined ? { sourceVersion: source.sourceVersion } : {}),
         authorizationScope: source.authorizationScope,
+        ...(sourceAuthorityFingerprint
+            ? { sourceAuthorityFingerprint }
+            : options.legacyWfsAuthority
+                ? { sourceAuthorityFingerprint: null }
+                : {}),
         estimates: plan.estimates,
         cache: persistedCacheOptions(plan.cache),
         discovery: persistedDiscoveryContext(plan.provenance.discovery),
         executionMode: plan.validity.executionMode,
+        representation: normalizeRepresentationRequest(persistedRepresentationRequest(plan)),
+    });
+}
+function parseSourceAuthorityFingerprint(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || !/^sha256:[0-9a-f]{64}$/.test(value)) {
+        throw invalidPersistedPlan();
+    }
+    return value;
+}
+/**
+ * Rebuild the exact OData plan representation emitted before operation-bound
+ * protocol artifacts were introduced. The persisted plan version remains
+ * 1.0, so those integrity-checked snapshots must be validated against their
+ * original compiler semantics before they can be migrated.
+ */
+function rebuildLegacyOdataQueryPlanV1(plan) {
+    return rebuildLegacyProtocolQueryPlanV1(plan, "odata", compileOdataQuery);
+}
+function isLegacyOdataQueryPlanV1(plan) {
+    if (plan.version !== QUERY_PLAN_VERSION || plan.ir.version !== "1.0" || plan.ir.source.protocol !== "odata") {
+        return false;
+    }
+    const remoteSteps = plan.steps.filter((step) => step.engine === "remote");
+    return remoteSteps.length > 0 && remoteSteps.every((step) => step.compiled.compiler === "odata-v4-query-v1");
+}
+/**
+ * Rebuild the exact WFS plan representation emitted before operation-bound
+ * protocol artifacts were introduced. This validates the old artifact against
+ * the old compiler before the same-version plan is migrated.
+ */
+function rebuildLegacyWfsQueryPlanV1(plan) {
+    return rebuildLegacyProtocolQueryPlanV1(plan, "wfs", compileWfsQuery);
+}
+function isLegacyWfsQueryPlanV1(plan) {
+    if (plan.version !== QUERY_PLAN_VERSION || plan.ir.version !== "1.0" || plan.ir.source.protocol !== "wfs") {
+        return false;
+    }
+    const remoteSteps = plan.steps.filter((step) => step.engine === "remote");
+    return remoteSteps.length > 0 && remoteSteps.every((step) => step.compiled.compiler === "wfs-2.0-get-feature-v1");
+}
+function rebuildLegacyProtocolQueryPlanV1(plan, protocol, compile) {
+    const modern = rebuildQueryPlanV1(plan, {
+        legacyWfsAuthority: protocol === "wfs" && plan.ir.source.authorityFingerprint === undefined,
+    });
+    if (modern.ir.source.protocol !== protocol)
+        throw invalidPersistedPlan();
+    const baseSteps = modern.steps.map((step) => {
+        const { fidelity: _fidelity, losses: _losses, bounds: _bounds, provenance: _provenance, ...base } = step;
+        if (base.engine !== "remote")
+            return base;
+        const query = base.operation === "queryAll" ? legacyProtocolQueryAllInput(base.query, modern.fallback) : base.query;
+        return {
+            ...base,
+            query,
+            compiled: compile(modern.ir.source, query),
+        };
+    });
+    const steps = baseSteps.map((step) => {
+        const diagnostics = createStepDiagnostics(step, modern.estimates, modern.provenance);
+        return step.engine === "client" ? { ...step, ...diagnostics, fidelity: "equivalent" } : { ...step, ...diagnostics };
+    });
+    const { fidelity, losses } = summarizeFidelity(steps);
+    const bounds = summarizePlanBounds(steps);
+    const warnings = createPlanWarnings(baseSteps, modern.ir.source, modern.representation);
+    const { id: _id, fingerprint: _fingerprint, fidelity: _modernFidelity, losses: _modernLosses, bounds: _modernBounds, steps: _modernSteps, warnings: _modernWarnings, ...shared } = modern;
+    const unsigned = {
+        ...shared,
+        fidelity,
+        losses,
+        bounds,
+        steps,
+        warnings,
+    };
+    const fingerprint = sha256(canonicalStringify(toJsonValue(unsigned)));
+    return deepFreeze({
+        ...unsigned,
+        id: `plan_${fingerprint.slice("sha256:".length, "sha256:".length + 16)}`,
+        fingerprint,
+    });
+}
+function legacyProtocolQueryAllInput(query, fallback) {
+    if (fallback.mode !== "bounded-local")
+        throw invalidPersistedPlan();
+    const pagination = query.pagination;
+    if (!pagination ||
+        pagination.offset !== 0 ||
+        pagination.limit !== fallback.maxRows ||
+        fallback.maxRows >= Number.MAX_SAFE_INTEGER) {
+        throw invalidPersistedPlan();
+    }
+    return deepFreeze({
+        ...query,
+        pagination: { offset: 0, limit: fallback.maxRows + 1 },
     });
 }
 function persistedV1FallbackPrimaryKey(plan) {
@@ -576,6 +693,7 @@ function rebuildGeoParquetQueryPlanV2(plan) {
         cache: persistedCacheOptions(plan.cache),
         discovery: persistedDiscoveryContext(plan.provenance.discovery),
         executionMode: plan.validity.executionMode,
+        representation: normalizeRepresentationRequest(persistedRepresentationRequest(plan)),
     });
 }
 function parsePersistedGeoParquetGeometryEncoding(value) {
@@ -670,8 +788,9 @@ function persistedPlanSnapshot(value) {
         assertPlanPersistenceSafe(plan);
         if (containsCredentialBearingPlanMaterial(plan))
             throw invalidPersistedPlan();
-        const { id: _id, fingerprint: _fingerprint, ...unsigned } = plan;
-        return { plan, hash: sha256(canonicalStringify(toJsonValue(unsigned))) };
+        const acceptedPlan = isLegacyOdataQueryPlanV1(plan) || isLegacyWfsQueryPlanV1(plan) ? rebuildQueryPlanV1(plan) : plan;
+        const { id: _id, fingerprint: _fingerprint, ...unsigned } = acceptedPlan;
+        return { plan: acceptedPlan, hash: sha256(canonicalStringify(toJsonValue(unsigned))) };
     }
     catch {
         throw invalidPersistedPlan();
@@ -809,10 +928,10 @@ function localAggregateInputQuery(query, aggregation, maxRows, primaryKey, optio
         ...base,
         ...(requiredFields.size > 0 ? { outFields: [...requiredFields].sort() } : {}),
         ...(!options.preserveGeometry ? { returnGeometry: false } : {}),
-        // The OGC Source.queryAll adapter owns the overflow sentinel: a logical
-        // N-row ceiling becomes an N + 1 wire request and is reported through
-        // exceededTransferLimit. GeoServices retains its established explicit
-        // sentinel in the canonical step for backward-compatible plan output.
+        // The OGC, OData, and WFS queryAll adapters own the overflow sentinel: a
+        // logical N-row ceiling becomes an N + 1 wire request and is reported
+        // through exceededTransferLimit. GeoServices retains its established
+        // explicit sentinel in the canonical step for backward-compatible output.
         pagination: { offset: 0, limit: maxRows + (options.adapterOwnsLookahead ? 0 : 1) },
     });
 }

package/query-planner/representation.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Deterministic result-representation selection for the query planner.
+ *
+ * The planner's {@link QueryPlanExecutionMode} axis answers *when* rows are
+ * delivered (`snapshot` vs `delta`). This module adds the orthogonal axis that
+ * answers *what shape* they arrive in: protocol-neutral `Result` feature
+ * objects, or a `ColumnarBatchV1`.
+ *
+ * Selection is metadata-only and reproducible by inspection. It reads the
+ * declared source identity (protocol plus physical geometry encoding) and the
+ * caller's {@link QueryPlanningEstimates}; it never reads result data, never
+ * constructs a worker, and never performs I/O. Two callers who explain the same
+ * query against the same declared source get the same decision, and therefore
+ * the same plan fingerprint.
+ *
+ * Capability honesty is the governing rule: a source that cannot serve columnar
+ * plans `object` and records why, and an explicit unsatisfiable pin throws
+ * {@link HonuaCapabilityNotSupportedError}. There is no silent fallback that
+ * would report a representation execution cannot deliver.
+ *
+ * @module
+ */
+import { type DuckDbGeometryEncoding, type QueryIrV1, type QueryIrV2, type QueryPlanRepresentationDecisionV1, type QueryPlanRepresentationRequest, type QueryPlanningEstimates } from "./types.js";
+/**
+ * Estimated rows at or above which `representation: "auto"` selects columnar.
+ *
+ * Set at the SDK's bounded-local materialization ceiling
+ * (`MAX_LOCAL_MATERIALIZATION_ROWS`): below it a result is small enough that
+ * feature objects stay affordable, at or above it the per-row object cost is
+ * exactly the problem a columnar batch exists to remove.
+ */
+export declare const COLUMNAR_REPRESENTATION_MIN_ROWS = 100000;
+/** Estimated payload bytes at or above which `representation: "auto"` selects columnar. */
+export declare const COLUMNAR_REPRESENTATION_MIN_BYTES: number;
+/**
+ * Physical geometry encodings with an executable columnar producer today.
+ *
+ * These are the GeoParquet 1.1 native encodings that map 1:1 onto a Honua
+ * GeoArrow geometry kind, so a batch can be produced without inventing a
+ * geometry type. The multi-part encodings (`geoarrow-multipoint`,
+ * `geoarrow-multilinestring`, `geoarrow-multipolygon`) are deliberately absent:
+ * this SDK's dependency-free GeoArrow mapping has no multi-part kind, and
+ * re-labelling their parts as a single-part column would misreport the
+ * geometry.
+ */
+export declare const COLUMNAR_REPRESENTATION_ENCODINGS: readonly DuckDbGeometryEncoding[];
+/** True for a declared geometry encoding that has an executable columnar producer. */
+export declare function isColumnarRepresentationEncoding(encoding: DuckDbGeometryEncoding | undefined): encoding is DuckDbGeometryEncoding;
+/** Validate a caller-supplied representation request; `undefined` means `auto`. */
+export declare function normalizeRepresentationRequest(value: unknown): QueryPlanRepresentationRequest;
+/**
+ * Select the plan's result representation.
+ *
+ * @throws HonuaCapabilityNotSupportedError when `requested` is `"columnar"` and
+ *   the declared source or query cannot serve it. Failing closed here is the
+ *   point: an unsatisfiable pin must never quietly become object execution.
+ */
+export declare function createQueryPlanRepresentationDecision(ir: QueryIrV1 | QueryIrV2, estimates: QueryPlanningEstimates, requested: QueryPlanRepresentationRequest): QueryPlanRepresentationDecisionV1;
+//# sourceMappingURL=representation.d.ts.map

package/query-planner/representation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"representation.d.ts","sourceRoot":"","sources":["../../../src/query-planner/representation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAEL,KAAK,sBAAsB,EAK3B,KAAK,SAAS,EACd,KAAK,SAAS,EAEd,KAAK,iCAAiC,EAGtC,KAAK,8BAA8B,EACnC,KAAK,sBAAsB,EAC5B,MAAM,YAAY,CAAC;AAEpB;;;;;;;GAOG;AACH,eAAO,MAAM,gCAAgC,SAAU,CAAC;AAExD,2FAA2F;AAC3F,eAAO,MAAM,iCAAiC,QAAkB,CAAC;AAEjE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iCAAiC,EAAE,SAAS,sBAAsB,EAI7E,CAAC;AAEH,sFAAsF;AACtF,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,sBAAsB,GAAG,SAAS,GAC3C,QAAQ,IAAI,sBAAsB,CAEpC;AAED,mFAAmF;AACnF,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,OAAO,GAAG,8BAA8B,CAM7F;AA2CD;;;;;;GAMG;AACH,wBAAgB,qCAAqC,CACnD,EAAE,EAAE,SAAS,GAAG,SAAS,EACzB,SAAS,EAAE,sBAAsB,EACjC,SAAS,EAAE,8BAA8B,GACxC,iCAAiC,CA0BnC"}

package/query-planner/representation.js

@@ -0,0 +1,140 @@
+/**
+ * Deterministic result-representation selection for the query planner.
+ *
+ * The planner's {@link QueryPlanExecutionMode} axis answers *when* rows are
+ * delivered (`snapshot` vs `delta`). This module adds the orthogonal axis that
+ * answers *what shape* they arrive in: protocol-neutral `Result` feature
+ * objects, or a `ColumnarBatchV1`.
+ *
+ * Selection is metadata-only and reproducible by inspection. It reads the
+ * declared source identity (protocol plus physical geometry encoding) and the
+ * caller's {@link QueryPlanningEstimates}; it never reads result data, never
+ * constructs a worker, and never performs I/O. Two callers who explain the same
+ * query against the same declared source get the same decision, and therefore
+ * the same plan fingerprint.
+ *
+ * Capability honesty is the governing rule: a source that cannot serve columnar
+ * plans `object` and records why, and an explicit unsatisfiable pin throws
+ * {@link HonuaCapabilityNotSupportedError}. There is no silent fallback that
+ * would report a representation execution cannot deliver.
+ *
+ * @module
+ */
+import { HonuaCapabilityNotSupportedError } from "../core/errors.js";
+import { HonuaQueryPlanningError, QUERY_PLAN_DIAGNOSTICS_VERSION, } from "./types.js";
+/**
+ * Estimated rows at or above which `representation: "auto"` selects columnar.
+ *
+ * Set at the SDK's bounded-local materialization ceiling
+ * (`MAX_LOCAL_MATERIALIZATION_ROWS`): below it a result is small enough that
+ * feature objects stay affordable, at or above it the per-row object cost is
+ * exactly the problem a columnar batch exists to remove.
+ */
+export const COLUMNAR_REPRESENTATION_MIN_ROWS = 100_000;
+/** Estimated payload bytes at or above which `representation: "auto"` selects columnar. */
+export const COLUMNAR_REPRESENTATION_MIN_BYTES = 8 * 1024 * 1024;
+/**
+ * Physical geometry encodings with an executable columnar producer today.
+ *
+ * These are the GeoParquet 1.1 native encodings that map 1:1 onto a Honua
+ * GeoArrow geometry kind, so a batch can be produced without inventing a
+ * geometry type. The multi-part encodings (`geoarrow-multipoint`,
+ * `geoarrow-multilinestring`, `geoarrow-multipolygon`) are deliberately absent:
+ * this SDK's dependency-free GeoArrow mapping has no multi-part kind, and
+ * re-labelling their parts as a single-part column would misreport the
+ * geometry.
+ */
+export const COLUMNAR_REPRESENTATION_ENCODINGS = Object.freeze([
+    "geoarrow-linestring",
+    "geoarrow-point",
+    "geoarrow-polygon",
+]);
+/** True for a declared geometry encoding that has an executable columnar producer. */
+export function isColumnarRepresentationEncoding(encoding) {
+    return encoding !== undefined && COLUMNAR_REPRESENTATION_ENCODINGS.includes(encoding);
+}
+/** Validate a caller-supplied representation request; `undefined` means `auto`. */
+export function normalizeRepresentationRequest(value) {
+    if (value === undefined)
+        return "auto";
+    if (value !== "auto" && value !== "object" && value !== "columnar") {
+        throw new HonuaQueryPlanningError("invalid-query", "representation is invalid");
+    }
+    return value;
+}
+function declaredGeometryEncoding(source) {
+    return source.protocol === "geoparquet" ? source.geoparquet?.geometryEncoding : undefined;
+}
+/**
+ * Decide whether this source and query can be served columnar, from declared
+ * metadata alone. Reasons are ordered most-fundamental first so the recorded
+ * reason names the constraint a caller would have to change first.
+ */
+function columnarCapability(source, query) {
+    const geometryEncoding = declaredGeometryEncoding(source);
+    const encoded = geometryEncoding === undefined ? {} : { geometryEncoding };
+    if (source.protocol !== "geoparquet") {
+        return { supported: false, reason: "protocol-not-columnar", ...encoded };
+    }
+    if (!isColumnarRepresentationEncoding(geometryEncoding)) {
+        return { supported: false, reason: "encoding-not-columnar", ...encoded };
+    }
+    if (query.aggregation !== undefined) {
+        return { supported: false, reason: "aggregation-not-columnar", ...encoded };
+    }
+    if (query.returnGeometry === false) {
+        return { supported: false, reason: "geometry-not-requested", ...encoded };
+    }
+    return { supported: true, reason: "workload-above-threshold", ...encoded };
+}
+function meetsColumnarThreshold(estimates) {
+    if (estimates.rows !== undefined && estimates.rows >= COLUMNAR_REPRESENTATION_MIN_ROWS)
+        return true;
+    return estimates.bytes !== undefined && estimates.bytes >= COLUMNAR_REPRESENTATION_MIN_BYTES;
+}
+/**
+ * Select the plan's result representation.
+ *
+ * @throws HonuaCapabilityNotSupportedError when `requested` is `"columnar"` and
+ *   the declared source or query cannot serve it. Failing closed here is the
+ *   point: an unsatisfiable pin must never quietly become object execution.
+ */
+export function createQueryPlanRepresentationDecision(ir, estimates, requested) {
+    const capability = columnarCapability(ir.source, ir.query);
+    if (requested === "columnar" && !capability.supported) {
+        throw new HonuaCapabilityNotSupportedError("columnar-execution", ir.source.protocol, ir.source.id, {
+            context: { representation: "columnar", reason: capability.reason },
+        });
+    }
+    const inputs = {
+        ...(capability.geometryEncoding === undefined ? {} : { geometryEncoding: capability.geometryEncoding }),
+        rowThreshold: COLUMNAR_REPRESENTATION_MIN_ROWS,
+        byteThreshold: COLUMNAR_REPRESENTATION_MIN_BYTES,
+        ...(estimates.rows === undefined ? {} : { estimatedRows: estimates.rows }),
+        ...(estimates.bytes === undefined ? {} : { estimatedBytes: estimates.bytes }),
+    };
+    const available = capability.supported
+        ? Object.freeze(["object", "columnar"])
+        : Object.freeze(["object"]);
+    const { selected, reason } = selectRepresentation(capability, estimates, requested);
+    return Object.freeze({
+        version: QUERY_PLAN_DIAGNOSTICS_VERSION,
+        requested,
+        selected,
+        available,
+        reason,
+        inputs: Object.freeze(inputs),
+    });
+}
+function selectRepresentation(capability, estimates, requested) {
+    if (requested !== "auto")
+        return { selected: requested, reason: "explicit-pin" };
+    if (!capability.supported)
+        return { selected: "object", reason: capability.reason };
+    if (estimates.rows === undefined && estimates.bytes === undefined) {
+        return { selected: "object", reason: "estimate-unavailable" };
+    }
+    return meetsColumnarThreshold(estimates)
+        ? { selected: "columnar", reason: "workload-above-threshold" }
+        : { selected: "object", reason: "workload-below-threshold" };
+}