@honua/sdk-esri-compat 0.1.12 → 0.1.14

package/query-planner/canonical.js

@@ -0,0 +1,145 @@
+/** Deterministic JSON serialization with sorted object keys and strict values. */
+export function canonicalStringify(value) {
+    return JSON.stringify(sortJson(value));
+}
+export function toJsonValue(value, path = "$") {
+    return convertJson(value, path, new WeakSet());
+}
+function convertJson(value, path, ancestors) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError(`${path} must contain only finite numbers`);
+        return Object.is(value, -0) ? 0 : value;
+    }
+    if (Array.isArray(value)) {
+        if (ancestors.has(value))
+            throw new TypeError(`${path} must not contain cycles`);
+        ancestors.add(value);
+        const converted = value.map((entry, index) => {
+            if (entry === undefined)
+                throw new TypeError(`${path}[${index}] must not be undefined`);
+            return convertJson(entry, `${path}[${index}]`, ancestors);
+        });
+        ancestors.delete(value);
+        return converted;
+    }
+    if (typeof value === "object") {
+        if (ancestors.has(value))
+            throw new TypeError(`${path} must not contain cycles`);
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError(`${path} must contain only plain JSON objects`);
+        }
+        ancestors.add(value);
+        const converted = {};
+        for (const key of Object.keys(value).sort()) {
+            const entry = value[key];
+            if (entry !== undefined) {
+                Object.defineProperty(converted, key, {
+                    value: convertJson(entry, `${path}.${key}`, ancestors),
+                    enumerable: true,
+                    writable: true,
+                    configurable: true,
+                });
+            }
+        }
+        ancestors.delete(value);
+        return converted;
+    }
+    throw new TypeError(`${path} contains unsupported ${typeof value}`);
+}
+function sortJson(value) {
+    if (Array.isArray(value))
+        return value.map(sortJson);
+    if (value !== null && typeof value === "object") {
+        const object = value;
+        const sorted = {};
+        for (const key of Object.keys(object).sort()) {
+            Object.defineProperty(sorted, key, {
+                value: sortJson(object[key]),
+                enumerable: true,
+                writable: true,
+                configurable: true,
+            });
+        }
+        return sorted;
+    }
+    return value;
+}
+/** Portable synchronous SHA-256 over UTF-8 input (browser, worker, and Node). */
+export function sha256(value) {
+    const bytes = new TextEncoder().encode(value);
+    const bitLength = bytes.length * 8;
+    const paddedLength = Math.ceil((bytes.length + 9) / 64) * 64;
+    const padded = new Uint8Array(paddedLength);
+    padded.set(bytes);
+    padded[bytes.length] = 0x80;
+    const view = new DataView(padded.buffer);
+    const high = Math.floor(bitLength / 0x1_0000_0000);
+    const low = bitLength >>> 0;
+    view.setUint32(paddedLength - 8, high, false);
+    view.setUint32(paddedLength - 4, low, false);
+    const state = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+    ]);
+    const words = new Uint32Array(64);
+    for (let offset = 0; offset < paddedLength; offset += 64) {
+        for (let index = 0; index < 16; index++)
+            words[index] = view.getUint32(offset + index * 4, false);
+        for (let index = 16; index < 64; index++) {
+            const before15 = words[index - 15] ?? 0;
+            const before2 = words[index - 2] ?? 0;
+            const s0 = rotateRight(before15, 7) ^ rotateRight(before15, 18) ^ (before15 >>> 3);
+            const s1 = rotateRight(before2, 17) ^ rotateRight(before2, 19) ^ (before2 >>> 10);
+            words[index] = ((words[index - 16] ?? 0) + s0 + (words[index - 7] ?? 0) + s1) >>> 0;
+        }
+        let a = state[0] ?? 0;
+        let b = state[1] ?? 0;
+        let c = state[2] ?? 0;
+        let d = state[3] ?? 0;
+        let e = state[4] ?? 0;
+        let f = state[5] ?? 0;
+        let g = state[6] ?? 0;
+        let h = state[7] ?? 0;
+        for (let index = 0; index < 64; index++) {
+            const upper1 = rotateRight(e, 6) ^ rotateRight(e, 11) ^ rotateRight(e, 25);
+            const choose = (e & f) ^ (~e & g);
+            const temp1 = (h + upper1 + choose + (SHA256_CONSTANTS[index] ?? 0) + (words[index] ?? 0)) >>> 0;
+            const upper0 = rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22);
+            const majority = (a & b) ^ (a & c) ^ (b & c);
+            const temp2 = (upper0 + majority) >>> 0;
+            h = g;
+            g = f;
+            f = e;
+            e = (d + temp1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (temp1 + temp2) >>> 0;
+        }
+        state[0] = ((state[0] ?? 0) + a) >>> 0;
+        state[1] = ((state[1] ?? 0) + b) >>> 0;
+        state[2] = ((state[2] ?? 0) + c) >>> 0;
+        state[3] = ((state[3] ?? 0) + d) >>> 0;
+        state[4] = ((state[4] ?? 0) + e) >>> 0;
+        state[5] = ((state[5] ?? 0) + f) >>> 0;
+        state[6] = ((state[6] ?? 0) + g) >>> 0;
+        state[7] = ((state[7] ?? 0) + h) >>> 0;
+    }
+    return `sha256:${Array.from(state, (word) => word.toString(16).padStart(8, "0")).join("")}`;
+}
+function rotateRight(value, amount) {
+    return (value >>> amount) | (value << (32 - amount));
+}
+const SHA256_CONSTANTS = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98,
+    0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786,
+    0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8,
+    0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+    0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819,
+    0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a,
+    0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7,
+    0xc67178f2,
+]);

package/query-planner/columnar-plan.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Plan-derived columnar batch identity.
+ *
+ * `ColumnarBatchIdentityV1` is the cache-key contract shipped by #940: source
+ * id, source version, schema version, plan id, authorization scope, ordering,
+ * and freshness together decide whether two batches are the same answer. Until
+ * now the only source-side producer minted those fields itself, so
+ * `columnarBatchCacheKey` keyed on a plan id no planner ever issued.
+ *
+ * This module closes that: every identity field except freshness is read from
+ * an accepted {@link QueryExecutionPlan}, and `planId` is the plan's own
+ * `validity.fingerprint`. A plan, schema, scope, or query change therefore
+ * changes the cache key by construction rather than by convention.
+ *
+ * Freshness is the one execution-time input. Planning stays observation-clock
+ * free — an observation instant in a plan would make the plan fingerprint
+ * change on every explain — so the caller supplies it when the source is
+ * actually read.
+ *
+ * The module imports only types from `../columnar/`, so it adds no runtime edge
+ * to the columnar data plane.
+ *
+ * @module
+ */
+import type { ColumnarBatchIdentityV1 } from "../columnar/types.js";
+import { type QueryExecutionPlan } from "./types.js";
+/** Execution-time freshness evidence for a plan-produced batch. */
+export interface ColumnarBatchIdentityFromPlanOptions {
+    /**
+     * RFC 3339 instant at which the source result was observed. Required, and
+     * supplied at execution: it is deliberately not a plan input.
+     */
+    readonly observedAt: string;
+    /** RFC 3339 instant after which the batch must be revalidated. */
+    readonly staleAfter?: string;
+    /** Opaque source validator, such as an HTTP ETag. Never a credential. */
+    readonly validator?: string;
+    /** Opaque monotonic source generation or revision. */
+    readonly generation?: string;
+}
+/**
+ * Derive the batch identity a columnar-selected plan implies.
+ *
+ * Field derivation:
+ * - `planId` — the plan's `validity.fingerprint` verbatim, so two plans that
+ *   are interchangeable for reuse share a cache entry and two that are not,
+ *   do not. The broader `plan.fingerprint` also covers cost estimates, which
+ *   change nothing about which rows come back, so it is deliberately not used.
+ * - `sourceId` / `sourceVersion` / `schemaVersion` — the plan's declared source
+ *   identity, falling back to the plan's own descriptor and schema fingerprints
+ *   when the source declares no version string. Both fallbacks are plan-derived
+ *   and change whenever the underlying identity changes.
+ * - `authorizationScope` — the plan's authorization-scope *fingerprint*, never
+ *   the raw scope values.
+ * - `ordering` — the canonical query's `orderBy`, as an ordering contract.
+ * - `freshness` — from {@link ColumnarBatchIdentityFromPlanOptions}.
+ *
+ * @throws HonuaCapabilityNotSupportedError when the plan did not select
+ *   columnar execution. A columnar identity minted from an object plan would
+ *   let a batch claim provenance the planner never granted.
+ */
+export declare function columnarBatchIdentityFromPlan(plan: QueryExecutionPlan, options: ColumnarBatchIdentityFromPlanOptions): ColumnarBatchIdentityV1;
+//# sourceMappingURL=columnar-plan.d.ts.map

package/query-planner/columnar-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"columnar-plan.d.ts","sourceRoot":"","sources":["../../../src/query-planner/columnar-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAA6C,MAAM,sBAAsB,CAAC;AAE/G,OAAO,EAA2B,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAE9E,mEAAmE;AACnE,MAAM,WAAW,oCAAoC;IACnD;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,oCAAoC,GAC5C,uBAAuB,CAqBzB"}

package/query-planner/columnar-plan.js

@@ -0,0 +1,94 @@
+/**
+ * Plan-derived columnar batch identity.
+ *
+ * `ColumnarBatchIdentityV1` is the cache-key contract shipped by #940: source
+ * id, source version, schema version, plan id, authorization scope, ordering,
+ * and freshness together decide whether two batches are the same answer. Until
+ * now the only source-side producer minted those fields itself, so
+ * `columnarBatchCacheKey` keyed on a plan id no planner ever issued.
+ *
+ * This module closes that: every identity field except freshness is read from
+ * an accepted {@link QueryExecutionPlan}, and `planId` is the plan's own
+ * `validity.fingerprint`. A plan, schema, scope, or query change therefore
+ * changes the cache key by construction rather than by convention.
+ *
+ * Freshness is the one execution-time input. Planning stays observation-clock
+ * free — an observation instant in a plan would make the plan fingerprint
+ * change on every explain — so the caller supplies it when the source is
+ * actually read.
+ *
+ * The module imports only types from `../columnar/`, so it adds no runtime edge
+ * to the columnar data plane.
+ *
+ * @module
+ */
+import { HonuaCapabilityNotSupportedError } from "../core/errors.js";
+import { HonuaQueryPlanningError } from "./types.js";
+/**
+ * Derive the batch identity a columnar-selected plan implies.
+ *
+ * Field derivation:
+ * - `planId` — the plan's `validity.fingerprint` verbatim, so two plans that
+ *   are interchangeable for reuse share a cache entry and two that are not,
+ *   do not. The broader `plan.fingerprint` also covers cost estimates, which
+ *   change nothing about which rows come back, so it is deliberately not used.
+ * - `sourceId` / `sourceVersion` / `schemaVersion` — the plan's declared source
+ *   identity, falling back to the plan's own descriptor and schema fingerprints
+ *   when the source declares no version string. Both fallbacks are plan-derived
+ *   and change whenever the underlying identity changes.
+ * - `authorizationScope` — the plan's authorization-scope *fingerprint*, never
+ *   the raw scope values.
+ * - `ordering` — the canonical query's `orderBy`, as an ordering contract.
+ * - `freshness` — from {@link ColumnarBatchIdentityFromPlanOptions}.
+ *
+ * @throws HonuaCapabilityNotSupportedError when the plan did not select
+ *   columnar execution. A columnar identity minted from an object plan would
+ *   let a batch claim provenance the planner never granted.
+ */
+export function columnarBatchIdentityFromPlan(plan, options) {
+    if (plan.validity.representation !== "columnar") {
+        throw new HonuaCapabilityNotSupportedError("columnar-execution", plan.ir.source.protocol, plan.ir.source.id, {
+            context: { representation: plan.validity.representation, reason: plan.representation.reason },
+        });
+    }
+    const observedAt = requireText(options.observedAt, "observedAt");
+    return Object.freeze({
+        sourceId: plan.ir.source.id,
+        sourceVersion: plan.ir.source.sourceVersion ?? plan.provenance.source.descriptorFingerprint,
+        schemaVersion: plan.ir.source.schemaVersion ?? plan.validity.schemaFingerprint,
+        planId: plan.validity.fingerprint,
+        authorizationScope: plan.provenance.authorizationScope.fingerprint,
+        ordering: planOrdering(plan),
+        freshness: Object.freeze({
+            observedAt,
+            ...(options.staleAfter === undefined ? {} : { staleAfter: requireText(options.staleAfter, "staleAfter") }),
+            ...(options.validator === undefined ? {} : { validator: requireText(options.validator, "validator") }),
+            ...(options.generation === undefined ? {} : { generation: requireText(options.generation, "generation") }),
+        }),
+    });
+}
+/**
+ * The ordering contract the plan's canonical query establishes.
+ *
+ * Null placement is declared `last` because the compiled DuckDB `ORDER BY`
+ * emits no explicit `NULLS` clause and DuckDB's default null order is
+ * `NULLS LAST`; the identity states the order the rows actually arrive in
+ * rather than leaving it unspecified. A batch whose schema does not carry
+ * every ordering key is refused when the batch is created — the identity is
+ * never quietly loosened to match a narrower batch.
+ */
+function planOrdering(plan) {
+    const orderBy = plan.ir.query.orderBy ?? [];
+    const keys = orderBy.map((sort) => Object.freeze({
+        field: sort.field,
+        direction: sort.direction === "desc" ? "descending" : "ascending",
+        nulls: "last",
+    }));
+    return Object.freeze({ stable: keys.length > 0, keys: Object.freeze(keys) });
+}
+function requireText(value, label) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new HonuaQueryPlanningError("invalid-query", `columnar batch identity ${label} must be a non-empty string`);
+    }
+    return value;
+}

package/query-planner/cql2-json.d.ts

@@ -0,0 +1,17 @@
+import { type SourceProtocol } from "../contract/schema.js";
+import type { Cql2JsonExpression, Cql2JsonInterchangeOptions, QueryFilter, SourceSpatiality } from "./semantic-types.js";
+type RuntimeFilter = QueryFilter<Record<string, unknown>, SourceProtocol, SourceSpatiality>;
+/**
+ * Export the CQL2-representable semantic-filter subset. CQL2 carries spatial
+ * CRS outside the expression, so every spatial export requires `filterCrs`
+ * and verifies that each operand uses that exact executable binding.
+ */
+export declare function semanticFilterToCql2Json<TRecord, TProtocol extends SourceProtocol, TSpatiality extends SourceSpatiality>(filter: QueryFilter<TRecord, TProtocol, TSpatiality>, options?: Cql2JsonInterchangeOptions): Cql2JsonExpression;
+/**
+ * Import the strict CQL2 JSON subset into the same runtime-validated semantic
+ * AST used by builders. Unknown functions, property-property comparisons,
+ * distance extensions, and other non-representable constructs fail closed.
+ */
+export declare function semanticFilterFromCql2Json(value: string | unknown, options?: Cql2JsonInterchangeOptions): RuntimeFilter;
+export {};
+//# sourceMappingURL=cql2-json.d.ts.map

package/query-planner/cql2-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cql2-json.d.ts","sourceRoot":"","sources":["../../../src/query-planner/cql2-json.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,cAAc,EAIpB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EACV,kBAAkB,EAClB,0BAA0B,EAC1B,WAAW,EAEX,gBAAgB,EAEjB,MAAM,qBAAqB,CAAC;AAI7B,KAAK,aAAa,GAAG,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,EAAE,gBAAgB,CAAC,CAAC;AAuE5F;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EACP,SAAS,SAAS,cAAc,EAChC,WAAW,SAAS,gBAAgB,EACpC,MAAM,EAAE,WAAW,CAAC,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,EAAE,OAAO,GAAE,0BAA+B,GAAG,kBAAkB,CAYpH;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,GAAG,OAAO,EACvB,OAAO,GAAE,0BAA+B,GACvC,aAAa,CAaf"}