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

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

package/query-planner/resource.js

@@ -0,0 +1,526 @@
+import { HonuaAbortError } from "../core/errors.js";
+import { canonicalStringify, sha256, toJsonValue } from "./canonical.js";
+import { HonuaQueryPlanExecutionError } from "./types.js";
+/** Discriminant for versioned, serializable query resource handles. */
+export const QUERY_RESOURCE_HANDLE_KIND = "honua.query-resource";
+/** First opaque query resource handle format. */
+export const QUERY_RESOURCE_HANDLE_VERSION = "1.0";
+const DEFAULT_MAX_ENTRIES = 256;
+const HARD_MAX_ENTRIES = 4_096;
+const MAX_SOURCE_COUNT = 64;
+const MAX_SOURCE_BYTES = 16_384;
+const MAX_TOTAL_SOURCE_BYTES = 131_072;
+const MAX_RESOLVER_LENGTH = 255;
+const MAX_IDENTITY_LENGTH = 256;
+const EXTENSION_IDENTIFIER_PATTERN = /^[a-z0-9](?:[a-z0-9_-]*\.)+[a-z0-9][a-z0-9_-]*$/;
+const RESOURCE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:~-]*$/;
+const AUTHORIZATION_CONTEXT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/~-]*$/;
+const JWT_SHAPE = /^eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}$/;
+const INVALID_HANDLE_MESSAGE = "GeoParquet resource handle is invalid";
+const RESOURCE_UNAVAILABLE_MESSAGE = "GeoParquet resource is unavailable";
+const RESOURCE_EXPIRED_MESSAGE = "GeoParquet resource authorization has expired";
+const RESOLUTION_FAILED_MESSAGE = "GeoParquet resource resolution failed";
+const INVALID_REGISTRY_OPTIONS_MESSAGE = "GeoParquet resource registry options are invalid";
+const INVALID_REGISTRATION_MESSAGE = "GeoParquet resource registration is invalid";
+const EXPIRED_ENTRY = Object.freeze({ state: "expired" });
+/** Create a credential-free handle without registering or resolving a locator. */
+export function createGeoParquetResourceHandle(input) {
+    const parsed = inspectRecord(input, ["resolver", "id", "authorizationContextId"], ["resourceVersion"]);
+    if (!parsed)
+        throw invalidHandle();
+    return parseGeoParquetResourceHandle({
+        kind: QUERY_RESOURCE_HANDLE_KIND,
+        version: QUERY_RESOURCE_HANDLE_VERSION,
+        protocol: "geoparquet",
+        resource: {
+            kind: "resolver",
+            resolver: parsed.get("resolver"),
+            id: parsed.get("id"),
+        },
+        authorizationContextId: parsed.get("authorizationContextId"),
+        ...(parsed.has("resourceVersion") ? { resourceVersion: parsed.get("resourceVersion") } : {}),
+    });
+}
+/** Parse an exact v1 handle without invoking accessors or retaining rejected input. */
+export function parseGeoParquetResourceHandle(value) {
+    const parsed = inspectRecord(value, ["kind", "version", "protocol", "resource", "authorizationContextId"], ["resourceVersion"]);
+    if (!parsed)
+        throw invalidHandle();
+    const resource = inspectRecord(parsed.get("resource"), ["kind", "resolver", "id"]);
+    const resolver = resource?.get("resolver");
+    const id = resource?.get("id");
+    const authorizationContextId = parsed.get("authorizationContextId");
+    const resourceVersion = parsed.get("resourceVersion");
+    const hasResourceVersion = parsed.has("resourceVersion");
+    if (parsed.get("kind") !== QUERY_RESOURCE_HANDLE_KIND ||
+        parsed.get("version") !== QUERY_RESOURCE_HANDLE_VERSION ||
+        parsed.get("protocol") !== "geoparquet" ||
+        resource?.get("kind") !== "resolver" ||
+        !isResolverIdentifier(resolver) ||
+        !isResourceIdentity(id) ||
+        !isAuthorizationContextId(authorizationContextId)) {
+        throw invalidHandle();
+    }
+    let normalizedResourceVersion;
+    if (hasResourceVersion) {
+        if (!isResourceIdentity(resourceVersion))
+            throw invalidHandle();
+        normalizedResourceVersion = resourceVersion;
+    }
+    return freezeHandle({
+        resource: { resolver, id },
+        authorizationContextId,
+        ...(normalizedResourceVersion !== undefined ? { resourceVersion: normalizedResourceVersion } : {}),
+    });
+}
+/** Stable credential-free fingerprint for plan/cache identity. */
+export function hashGeoParquetResourceHandle(value) {
+    const handle = parseGeoParquetResourceHandle(value);
+    return sha256(canonicalStringify(toJsonValue(handle)));
+}
+/**
+ * Resolve a handle through an injected resolver after enforcing scope,
+ * cancellation, output bounds, and fixed-message error redaction.
+ */
+export async function resolveGeoParquetResource(value, resolver, context) {
+    const handle = parseGeoParquetResourceHandle(value);
+    const safeContext = parseResolutionContext(context);
+    if (typeof resolver !== "function")
+        throw resolutionFailed();
+    if (isSignalAborted(safeContext.signal))
+        throw new HonuaAbortError();
+    if (safeContext.authorizationContextId !== handle.authorizationContextId)
+        throw resourceUnavailable();
+    let pending;
+    try {
+        pending = resolver(handle, safeContext);
+    }
+    catch (error) {
+        throw normalizeResolverFailure(error, safeContext.signal);
+    }
+    let resolved;
+    try {
+        resolved = await awaitAbortable(pending, safeContext.signal);
+    }
+    catch (error) {
+        throw normalizeResolverFailure(error, safeContext.signal);
+    }
+    const output = inspectRecord(resolved, ["sources"]);
+    const sources = output ? copyBoundedSources(output.get("sources")) : undefined;
+    if (!sources)
+        throw resolutionFailed();
+    return Object.freeze({ sources });
+}
+/** Create a bounded in-memory registry for private, rotation-friendly locators. */
+export function createGeoParquetResourceRegistry(options) {
+    const parsedOptions = inspectRecord(options, ["resolver"], ["maxEntries", "now"]);
+    const resolverId = parsedOptions?.get("resolver");
+    const configuredMaxEntries = parsedOptions?.get("maxEntries");
+    const configuredNow = parsedOptions?.get("now");
+    if (!parsedOptions ||
+        !isResolverIdentifier(resolverId) ||
+        (configuredMaxEntries !== undefined && !isMaxEntries(configuredMaxEntries)) ||
+        (configuredNow !== undefined && !isClock(configuredNow))) {
+        throw new TypeError(INVALID_REGISTRY_OPTIONS_MESSAGE);
+    }
+    const maxEntries = configuredMaxEntries ?? DEFAULT_MAX_ENTRIES;
+    const now = configuredNow ?? Date.now;
+    const entries = new Map();
+    let disposed = false;
+    let readingClock = false;
+    const readCurrentTime = () => {
+        if (readingClock)
+            throw resolutionFailed();
+        readingClock = true;
+        try {
+            return readClock(now);
+        }
+        finally {
+            readingClock = false;
+        }
+    };
+    const resolver = (handleValue, contextValue) => {
+        const handle = parseGeoParquetResourceHandle(handleValue);
+        const context = parseResolutionContext(contextValue);
+        if (isSignalAborted(context.signal))
+            throw new HonuaAbortError();
+        if (context.authorizationContextId !== handle.authorizationContextId ||
+            handle.resource.resolver !== resolverId ||
+            disposed) {
+            throw resourceUnavailable();
+        }
+        const key = resourceKey(handle);
+        const entry = entries.get(key);
+        if (!entry)
+            throw resourceUnavailable();
+        if (entry.state === "expired")
+            throw resourceExpired();
+        if (entry.expiresAt !== undefined) {
+            const currentTime = readCurrentTime();
+            if (disposed || entries.get(key) !== entry)
+                throw resourceUnavailable();
+            if (currentTime >= entry.expiresAt) {
+                entries.set(key, EXPIRED_ENTRY);
+                throw resourceExpired();
+            }
+        }
+        return Object.freeze({ sources: entry.sources });
+    };
+    const registry = {
+        register(input) {
+            if (disposed)
+                throw resourceUnavailable();
+            const registration = parseRegistration(input);
+            const handle = freezeHandle({
+                resource: { resolver: resolverId, id: registration.id },
+                authorizationContextId: registration.authorizationContextId,
+                ...(registration.resourceVersion !== undefined ? { resourceVersion: registration.resourceVersion } : {}),
+            });
+            const key = resourceKey(handle);
+            if (!entries.has(key) && entries.size >= maxEntries)
+                reclaimExpiredEntries(entries, maxEntries);
+            if (!entries.has(key) && entries.size >= maxEntries && hasExpiringEntries(entries)) {
+                const snapshot = [...entries.entries()];
+                const currentTime = readCurrentTime();
+                if (disposed || !entriesMatchSnapshot(entries, snapshot))
+                    throw resourceUnavailable();
+                reclaimExpiredEntries(entries, maxEntries, currentTime);
+            }
+            if (!entries.has(key) && entries.size >= maxEntries)
+                throw resourceUnavailable();
+            entries.set(key, Object.freeze({
+                state: "active",
+                sources: registration.sources,
+                ...(registration.expiresAt !== undefined ? { expiresAt: registration.expiresAt } : {}),
+            }));
+            return handle;
+        },
+        resolver,
+        revoke(handleValue) {
+            const handle = parseGeoParquetResourceHandle(handleValue);
+            if (handle.resource.resolver === resolverId)
+                entries.delete(resourceKey(handle));
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            entries.clear();
+        },
+    };
+    return Object.freeze(registry);
+}
+function parseRegistration(input) {
+    const parsed = inspectRecord(input, ["id", "authorizationContextId", "sources"], ["resourceVersion", "expiresAt"]);
+    const id = parsed?.get("id");
+    const authorizationContextId = parsed?.get("authorizationContextId");
+    const resourceVersion = parsed?.get("resourceVersion");
+    const expiresAt = parsed?.get("expiresAt");
+    const sources = parsed ? copyBoundedSources(parsed.get("sources")) : undefined;
+    if (!parsed ||
+        !isResourceIdentity(id) ||
+        !isAuthorizationContextId(authorizationContextId) ||
+        (resourceVersion !== undefined && !isResourceIdentity(resourceVersion)) ||
+        (expiresAt !== undefined && !isEpochMilliseconds(expiresAt)) ||
+        !sources) {
+        throw new TypeError(INVALID_REGISTRATION_MESSAGE);
+    }
+    return {
+        id,
+        authorizationContextId,
+        ...(resourceVersion !== undefined ? { resourceVersion } : {}),
+        sources,
+        ...(expiresAt !== undefined ? { expiresAt } : {}),
+    };
+}
+function parseResolutionContext(value) {
+    const parsed = inspectRecord(value, ["authorizationContextId"], ["signal"]);
+    const authorizationContextId = parsed?.get("authorizationContextId");
+    const signal = parsed?.get("signal");
+    if (!parsed ||
+        !isAuthorizationContextId(authorizationContextId) ||
+        (signal !== undefined && !isAbortSignal(signal))) {
+        throw resourceUnavailable();
+    }
+    return Object.freeze({
+        authorizationContextId,
+        ...(signal !== undefined ? { signal } : {}),
+    });
+}
+function freezeHandle(input) {
+    const resource = Object.freeze({
+        kind: "resolver",
+        resolver: input.resource.resolver,
+        id: input.resource.id,
+    });
+    return Object.freeze({
+        kind: QUERY_RESOURCE_HANDLE_KIND,
+        version: QUERY_RESOURCE_HANDLE_VERSION,
+        protocol: "geoparquet",
+        resource,
+        authorizationContextId: input.authorizationContextId,
+        ...(input.resourceVersion !== undefined ? { resourceVersion: input.resourceVersion } : {}),
+    });
+}
+function resourceKey(handle) {
+    return canonicalStringify(toJsonValue([
+        handle.resource.resolver,
+        handle.resource.id,
+        handle.authorizationContextId,
+        handle.resourceVersion ?? null,
+    ]));
+}
+function reclaimExpiredEntries(entries, maxEntries, currentTime) {
+    for (const [key, entry] of entries) {
+        if (entry.state === "expired" ||
+            (currentTime !== undefined && entry.expiresAt !== undefined && currentTime >= entry.expiresAt)) {
+            entries.delete(key);
+        }
+        if (entries.size < maxEntries)
+            return;
+    }
+}
+function hasExpiringEntries(entries) {
+    for (const entry of entries.values()) {
+        if (entry.state === "active" && entry.expiresAt !== undefined)
+            return true;
+    }
+    return false;
+}
+function entriesMatchSnapshot(entries, snapshot) {
+    return entries.size === snapshot.length && snapshot.every(([key, entry]) => entries.get(key) === entry);
+}
+function inspectRecord(value, requiredKeys, optionalKeys = []) {
+    try {
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            return undefined;
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null)
+            return undefined;
+        const keys = Reflect.ownKeys(value);
+        if (keys.some((key) => typeof key !== "string"))
+            return undefined;
+        const allowed = new Set([...requiredKeys, ...optionalKeys]);
+        if (keys.length < requiredKeys.length || keys.length > allowed.size)
+            return undefined;
+        if (keys.some((key) => typeof key !== "string" || !allowed.has(key)))
+            return undefined;
+        const result = new Map();
+        for (const key of requiredKeys) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor || !descriptor.enumerable || !("value" in descriptor))
+                return undefined;
+            result.set(key, descriptor.value);
+        }
+        for (const key of optionalKeys) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor)
+                continue;
+            if (!descriptor.enumerable || !("value" in descriptor))
+                return undefined;
+            result.set(key, descriptor.value);
+        }
+        return result;
+    }
+    catch {
+        return undefined;
+    }
+}
+function copyBoundedSources(value) {
+    try {
+        if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype)
+            return undefined;
+        const lengthDescriptor = Object.getOwnPropertyDescriptor(value, "length");
+        const length = lengthDescriptor && "value" in lengthDescriptor ? lengthDescriptor.value : undefined;
+        if (typeof length !== "number" || !Number.isInteger(length) || length < 1 || length > MAX_SOURCE_COUNT) {
+            return undefined;
+        }
+        const keys = Reflect.ownKeys(value);
+        if (keys.length !== length + 1 || keys.some((key) => typeof key !== "string"))
+            return undefined;
+        if (keys.some((key) => typeof key === "string" && key !== "length" && !isArrayIndex(key, length))) {
+            return undefined;
+        }
+        let totalBytes = 0;
+        const copy = [];
+        for (let index = 0; index < length; index++) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+            if (!descriptor || !descriptor.enumerable || !("value" in descriptor))
+                return undefined;
+            const source = descriptor.value;
+            if (typeof source !== "string" ||
+                source.length === 0 ||
+                source.length > MAX_SOURCE_BYTES ||
+                containsControlCharacter(source)) {
+                return undefined;
+            }
+            const bytes = new TextEncoder().encode(source).byteLength;
+            if (bytes > MAX_SOURCE_BYTES)
+                return undefined;
+            totalBytes += bytes;
+            if (totalBytes > MAX_TOTAL_SOURCE_BYTES)
+                return undefined;
+            copy.push(source);
+        }
+        return Object.freeze(copy);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isArrayIndex(key, length) {
+    if (!/^(?:0|[1-9][0-9]*)$/.test(key))
+        return false;
+    const index = Number(key);
+    return Number.isSafeInteger(index) && index >= 0 && index < length;
+}
+function containsControlCharacter(value) {
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        if (code <= 0x1f || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+function isResolverIdentifier(value) {
+    return typeof value === "string" && value.length <= MAX_RESOLVER_LENGTH && EXTENSION_IDENTIFIER_PATTERN.test(value);
+}
+function isResourceIdentity(value) {
+    return (typeof value === "string" &&
+        value.length <= MAX_IDENTITY_LENGTH &&
+        RESOURCE_ID_PATTERN.test(value) &&
+        !JWT_SHAPE.test(value));
+}
+function isAuthorizationContextId(value) {
+    return (typeof value === "string" &&
+        value.length <= MAX_IDENTITY_LENGTH &&
+        AUTHORIZATION_CONTEXT_PATTERN.test(value) &&
+        !value.endsWith("/") &&
+        !value.includes("//") &&
+        !value.split("/").some((segment) => segment === "." || segment === "..") &&
+        !JWT_SHAPE.test(value));
+}
+function isMaxEntries(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= HARD_MAX_ENTRIES;
+}
+function isClock(value) {
+    return typeof value === "function";
+}
+function isEpochMilliseconds(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function isAbortSignal(value) {
+    try {
+        return (value !== null &&
+            typeof value === "object" &&
+            typeof value.aborted === "boolean" &&
+            typeof value.addEventListener === "function" &&
+            typeof value.removeEventListener === "function");
+    }
+    catch {
+        return false;
+    }
+}
+function isSignalAborted(signal) {
+    try {
+        return signal?.aborted === true;
+    }
+    catch {
+        throw resolutionFailed();
+    }
+}
+function readClock(now) {
+    try {
+        const value = now();
+        if (!isEpochMilliseconds(value))
+            throw resolutionFailed();
+        return value;
+    }
+    catch {
+        throw resolutionFailed();
+    }
+}
+function awaitAbortable(value, signal) {
+    const pending = Promise.resolve(value);
+    if (!signal)
+        return pending;
+    if (isSignalAborted(signal)) {
+        void pending.catch(() => undefined);
+        throw new HonuaAbortError();
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                signal.removeEventListener("abort", abort);
+            }
+            catch {
+                // The fixed failure below retains no foreign signal data.
+            }
+            callback();
+        };
+        const abort = () => finish(() => reject(new HonuaAbortError()));
+        try {
+            signal.addEventListener("abort", abort, { once: true });
+        }
+        catch {
+            void pending.catch(() => undefined);
+            finish(() => reject(resolutionFailed()));
+            return;
+        }
+        try {
+            if (isSignalAborted(signal)) {
+                abort();
+                void pending.catch(() => undefined);
+                return;
+            }
+        }
+        catch (error) {
+            void pending.catch(() => undefined);
+            finish(() => reject(error));
+            return;
+        }
+        pending.then((result) => finish(() => resolve(result)), (error) => finish(() => reject(error)));
+    });
+}
+function normalizeResolverFailure(error, signal) {
+    if (isSignalAborted(signal))
+        return new HonuaAbortError();
+    try {
+        if (error instanceof HonuaQueryPlanExecutionError) {
+            const code = ownDataProperty(error, "code");
+            if (code === "resource-unavailable")
+                return resourceUnavailable();
+            if (code === "resource-expired")
+                return resourceExpired();
+        }
+    }
+    catch {
+        // Proxy and cross-realm failures are projected to the same fixed error.
+    }
+    return resolutionFailed();
+}
+function ownDataProperty(value, key) {
+    try {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        return descriptor && "value" in descriptor ? descriptor.value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function invalidHandle() {
+    return new HonuaQueryPlanExecutionError("invalid-resource-handle", INVALID_HANDLE_MESSAGE);
+}
+function resourceUnavailable() {
+    return new HonuaQueryPlanExecutionError("resource-unavailable", RESOURCE_UNAVAILABLE_MESSAGE);
+}
+function resourceExpired() {
+    return new HonuaQueryPlanExecutionError("resource-expired", RESOURCE_EXPIRED_MESSAGE);
+}
+function resolutionFailed() {
+    return new HonuaQueryPlanExecutionError("resource-resolution-failed", RESOLUTION_FAILED_MESSAGE);
+}

package/query-planner/semantic-canonical.d.ts

@@ -0,0 +1,15 @@
+import type { CanonicalSemanticQueryOptions } from "./semantic-types.js";
+export declare const SEMANTIC_QUERY_CANONICAL_KIND: "honua.semantic-query-canonical";
+export declare const SEMANTIC_QUERY_CANONICAL_VERSION: 1;
+export declare const SEMANTIC_QUERY_HASH_DOMAIN: "honua.semantic-query.hash.v1";
+/**
+ * Serialize a validated semantic query plus its schema/CRS/policy identity.
+ * Object keys are UTF-8 deterministically ordered; array order stays
+ * significant. Volatile execution state is not accepted by the semantic AST.
+ */
+export declare function serializeCanonicalSemanticQuery(value: unknown, options?: CanonicalSemanticQueryOptions): string;
+/** Return a fresh UTF-8 byte copy of the canonical semantic-query envelope. */
+export declare function canonicalSemanticQueryBytes(value: unknown, options?: CanonicalSemanticQueryOptions): Uint8Array;
+/** Domain-separated SHA-256 identity for a canonical semantic query. */
+export declare function hashSemanticQuery(value: unknown, options?: CanonicalSemanticQueryOptions): `sha256:${string}`;
+//# sourceMappingURL=semantic-canonical.d.ts.map

package/query-planner/semantic-canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-canonical.d.ts","sourceRoot":"","sources":["../../../src/query-planner/semantic-canonical.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AAIzE,eAAO,MAAM,6BAA6B,EAAG,gCAAyC,CAAC;AACvF,eAAO,MAAM,gCAAgC,EAAG,CAAU,CAAC;AAC3D,eAAO,MAAM,0BAA0B,EAAG,8BAAuC,CAAC;AAKlF;;;;GAIG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,6BAAkC,GAAG,MAAM,CAoBnH;AAED,+EAA+E;AAC/E,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,6BAAkC,GAAG,UAAU,CAEnH;AAED,wEAAwE;AACxE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,6BAAkC,GAAG,UAAU,MAAM,EAAE,CAEjH"}