@honua/sdk-esri-compat 0.1.12 → 0.1.13

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" };
+}

package/query-planner/resource.d.ts

@@ -0,0 +1,94 @@
+/** Discriminant for versioned, serializable query resource handles. */
+export declare const QUERY_RESOURCE_HANDLE_KIND: "honua.query-resource";
+/** First opaque query resource handle format. */
+export declare const QUERY_RESOURCE_HANDLE_VERSION: "1.0";
+/** Credential-free resolver identity embedded in a GeoParquet resource handle. */
+export interface GeoParquetResolverResourceReferenceV1 {
+    readonly kind: "resolver";
+    /** Canonical lowercase reverse-DNS resolver identifier. */
+    readonly resolver: string;
+    /** Stable logical resource id. It must never be derived from a credential. */
+    readonly id: string;
+}
+/**
+ * Serializable identity for a GeoParquet resource whose private locator is
+ * supplied only at execution time.
+ */
+export interface GeoParquetResourceHandleV1 {
+    readonly kind: typeof QUERY_RESOURCE_HANDLE_KIND;
+    readonly version: typeof QUERY_RESOURCE_HANDLE_VERSION;
+    readonly protocol: "geoparquet";
+    readonly resource: GeoParquetResolverResourceReferenceV1;
+    /** Stable, non-secret authorization partition id; never a token or credential. */
+    readonly authorizationContextId: string;
+    /** Data revision/validator identity. Credential rotation must not change it. */
+    readonly resourceVersion?: string;
+}
+/** Ephemeral raw GeoParquet addressing returned at the trusted execution boundary. */
+export interface ResolvedGeoParquetResource {
+    /**
+     * One to 64 values, each at most 16 KiB UTF-8 and at most 128 KiB in
+     * aggregate. Never persist, log, fingerprint, or place them in a query plan.
+     */
+    readonly sources: readonly string[];
+}
+/** Per-execution authorization and cancellation state supplied to a resolver. */
+export interface GeoParquetResourceResolutionContext {
+    /** Must exactly match the stable, non-secret partition id in the handle. */
+    readonly authorizationContextId: string;
+    readonly signal?: AbortSignal;
+}
+/** Injected, lifecycle-scoped GeoParquet locator resolver. */
+export type GeoParquetResourceResolver = (handle: GeoParquetResourceHandleV1, context: GeoParquetResourceResolutionContext) => ResolvedGeoParquetResource | Promise<ResolvedGeoParquetResource>;
+/** Input used to register or atomically replace one private resource locator. */
+export interface RegisterGeoParquetResourceInput {
+    readonly id: string;
+    readonly authorizationContextId: string;
+    readonly resourceVersion?: string;
+    /** Private addressing subject to the same fixed bounds as resolved sources. */
+    readonly sources: readonly string[];
+    /** Private Unix epoch deadline in milliseconds; expiry occurs at `now >= expiresAt`. */
+    readonly expiresAt?: number;
+}
+/** Stable identity input for a handle whose private locator is registered elsewhere. */
+export interface CreateGeoParquetResourceHandleInput {
+    readonly resolver: string;
+    readonly id: string;
+    readonly authorizationContextId: string;
+    readonly resourceVersion?: string;
+}
+/** Options for an ephemeral, in-memory resolver registry. */
+export interface GeoParquetResourceRegistryOptions {
+    /** Canonical lowercase reverse-DNS resolver identifier embedded in handles. */
+    readonly resolver: string;
+    /** May tighten, but never raise, the SDK's hard 4,096-entry ceiling. */
+    readonly maxEntries?: number;
+    /** Injectable finite Unix epoch millisecond clock for lifecycle control and tests. */
+    readonly now?: () => number;
+}
+/**
+ * Lifecycle-scoped private resource registry. This is isolation, not encrypted
+ * storage: call `dispose()` when the owning client/session ends.
+ */
+export interface GeoParquetResourceRegistry {
+    register(input: RegisterGeoParquetResourceInput): GeoParquetResourceHandleV1;
+    readonly resolver: GeoParquetResourceResolver;
+    /** Idempotently removes a handle without revealing whether it existed. */
+    revoke(handle: GeoParquetResourceHandleV1): void;
+    /** Idempotently clears every private locator and closes the registry. */
+    dispose(): void;
+}
+/** Create a credential-free handle without registering or resolving a locator. */
+export declare function createGeoParquetResourceHandle(input: CreateGeoParquetResourceHandleInput): GeoParquetResourceHandleV1;
+/** Parse an exact v1 handle without invoking accessors or retaining rejected input. */
+export declare function parseGeoParquetResourceHandle(value: unknown): GeoParquetResourceHandleV1;
+/** Stable credential-free fingerprint for plan/cache identity. */
+export declare function hashGeoParquetResourceHandle(value: unknown): `sha256:${string}`;
+/**
+ * Resolve a handle through an injected resolver after enforcing scope,
+ * cancellation, output bounds, and fixed-message error redaction.
+ */
+export declare function resolveGeoParquetResource(value: unknown, resolver: GeoParquetResourceResolver, context: GeoParquetResourceResolutionContext): Promise<ResolvedGeoParquetResource>;
+/** Create a bounded in-memory registry for private, rotation-friendly locators. */
+export declare function createGeoParquetResourceRegistry(options: GeoParquetResourceRegistryOptions): GeoParquetResourceRegistry;
+//# sourceMappingURL=resource.d.ts.map

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

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