@honua/app-platform 0.0.20-alpha.0 → 0.1.1-beta.0

package/scene-workspace/source-to-cesium.js

@@ -0,0 +1,791 @@
+/**
+ * Experimental accepted-plan Source -> Cesium entity workflow.
+ *
+ * The projection half is renderer-neutral and SSR safe. Cesium is resolved
+ * only while mounting, either through an injected module/loader or a lazy
+ * optional-peer import.
+ *
+ * @experimental Not covered by the pre-1.0 semver contract.
+ */
+import { HonuaCapabilityNotSupportedError } from "../core/errors.js";
+import { canonicalStringify, toJsonValue } from "../query-planner/canonical.js";
+import { queryFromCanonical, queryIrSourceIdentity } from "../query-planner/ir.js";
+import { hashQueryPlanV1 } from "../query-planner/planner.js";
+import { HonuaQueryPlanExecutionError, } from "../query-planner/types.js";
+export const DEFAULT_CESIUM_ENTITY_LIMIT = 10_000;
+export class HonuaCesiumEntityAdapterError extends Error {
+    code;
+    detail;
+    constructor(code, message, detail, options) {
+        super(message, options);
+        this.code = code;
+        this.detail = detail;
+        this.name = "HonuaCesiumEntityAdapterError";
+    }
+}
+export function projectSourceToCesium(source, plan, result, options = {}) {
+    assertProjectionPlanContext(source, plan);
+    const maxEntities = validatePlanAndOptions(source, plan, options);
+    if (result.aggregateRows !== undefined)
+        throw unsupportedPlan(plan);
+    const queryLimit = plan.ir.query.pagination?.limit;
+    if (result.features.length > queryLimit) {
+        throw new HonuaCesiumEntityAdapterError("entity-limit-exceeded", `Source returned ${result.features.length} features for accepted query limit ${queryLimit}.`, { queryLimit, returnedFeatureCount: result.features.length });
+    }
+    const sourceId = `honua-${safeId(source.descriptor.id)}`;
+    const idField = options.featureIdField ?? source.descriptor.schema?.primaryKey;
+    const diagnostics = [
+        diagnostic(source, plan, "strategy-selected", "info", "project", "exact", "Selected bounded Cesium entity query strategy.", {
+            maxEntities,
+        }),
+    ];
+    const entities = [];
+    let unsupportedGeometry = 0;
+    let missingIdentity = 0;
+    let invalidIntervals = 0;
+    let unsupportedVerticalDatum = 0;
+    let unsupportedAttributes = 0;
+    const entityIds = new Set();
+    for (const feature of result.features) {
+        const attributes = snapshotJsonAttributes(feature.attributes);
+        if (!attributes) {
+            unsupportedAttributes += 1;
+            continue;
+        }
+        const featureId = idField ? attributes[idField] : undefined;
+        if (typeof featureId !== "string" && typeof featureId !== "number") {
+            missingIdentity += 1;
+            continue;
+        }
+        if (geometryHasZ(feature.geometry) && options.verticalDatum !== "ellipsoidal-wgs84") {
+            unsupportedVerticalDatum += 1;
+            continue;
+        }
+        const geometry = projectGeometry(feature);
+        if (!geometry) {
+            unsupportedGeometry += 1;
+            continue;
+        }
+        const interval = options.time ? projectInterval(attributes, options.time) : undefined;
+        if (options.time && !interval) {
+            invalidIntervals += 1;
+            continue;
+        }
+        const entityId = `${sourceId}:${typeof featureId === "number" ? "n" : "s"}:${encodeURIComponent(String(featureId))}`;
+        if (entityIds.has(entityId)) {
+            throw new HonuaCesiumEntityAdapterError("entity-conflict", `Accepted query returned duplicate stable feature identity "${String(featureId)}".`, { entityId, featureId });
+        }
+        entityIds.add(entityId);
+        entities.push(Object.freeze({
+            id: entityId,
+            featureId,
+            properties: attributes,
+            geometry: immutableJsonSnapshot(geometry),
+            ...(interval ? { interval: immutableJsonSnapshot(interval) } : {}),
+        }));
+        if (entities.length > maxEntities) {
+            throw new HonuaCesiumEntityAdapterError("entity-limit-exceeded", `Cesium projection exceeded the ${maxEntities} entity safety ceiling.`, { maxEntities, sourceId: source.descriptor.id });
+        }
+    }
+    if (result.features.length === 0) {
+        diagnostics.push(diagnostic(source, plan, "empty-result", "info", "execute", "exact", "The accepted plan returned no features."));
+    }
+    if (result.exceededTransferLimit) {
+        diagnostics.push(diagnostic(source, plan, "transfer-limit", "warning", "execute", "unsupported", "The rendered page is not the complete source result.", {
+            renderedEntityCount: entities.length,
+        }));
+    }
+    if (result.degraded?.length) {
+        diagnostics.push(diagnostic(source, plan, "source-degraded", "warning", "execute", "unsupported", "The source reported degraded execution semantics.", {
+            reasons: result.degraded.map((entry) => entry.reason),
+        }));
+    }
+    if (missingIdentity > 0) {
+        diagnostics.push(diagnostic(source, plan, "identity-missing", "warning", "project", "unsupported", `${missingIdentity} feature(s) lacked stable identity and were omitted.`, {
+            featureIdField: idField,
+            omittedFeatureCount: missingIdentity,
+        }));
+    }
+    if (unsupportedAttributes > 0) {
+        diagnostics.push(diagnostic(source, plan, "attributes-unsupported", "warning", "project", "unsupported", `${unsupportedAttributes} feature attribute object(s) were not strict JSON-like values and were omitted.`, { omittedFeatureCount: unsupportedAttributes }));
+    }
+    if (unsupportedGeometry > 0) {
+        diagnostics.push(diagnostic(source, plan, "geometry-unsupported", "warning", "project", "unsupported", `${unsupportedGeometry} feature geometry value(s) were omitted.`, {
+            omittedFeatureCount: unsupportedGeometry,
+        }));
+    }
+    if (unsupportedVerticalDatum > 0) {
+        diagnostics.push(diagnostic(source, plan, "vertical-datum-unsupported", "warning", "project", "unsupported", `${unsupportedVerticalDatum} feature(s) carried Z values without an explicit supported vertical datum and were omitted.`, { supportedVerticalDatum: "ellipsoidal-wgs84", omittedFeatureCount: unsupportedVerticalDatum }));
+    }
+    if (invalidIntervals > 0) {
+        diagnostics.push(diagnostic(source, plan, "time-interval-invalid", "warning", "project", "unsupported", `${invalidIntervals} feature time interval(s) were invalid and omitted.`, {
+            omittedFeatureCount: invalidIntervals,
+        }));
+    }
+    return Object.freeze({
+        strategy: "entity-query",
+        sourceId,
+        planId: plan.id,
+        planFingerprint: plan.fingerprint,
+        sourceVersion: plan.ir.source.sourceVersion,
+        schemaVersion: plan.ir.source.schemaVersion,
+        authorizationScope: Object.freeze([...plan.ir.source.authorizationScope]),
+        entities: Object.freeze(entities),
+        diagnostics: Object.freeze(diagnostics),
+        state: diagnostics.some((entry) => entry.severity === "warning")
+            ? "degraded"
+            : entities.length === 0
+                ? "empty"
+                : "ready",
+    });
+}
+export async function mountSourceToCesium(collection, source, plan, options = {}) {
+    const mountOptions = snapshotMountOptions(options);
+    assertProjectionPlanContext(source, plan);
+    validatePlanAndOptions(source, plan, mountOptions);
+    const lifecycle = new AbortController();
+    const initialSignal = combineSignals([lifecycle.signal, mountOptions.signal]);
+    initialSignal.throwIfAborted();
+    assertExecutionContext(source, plan, executionOptions(mountOptions));
+    const cesium = await resolveCesium(mountOptions.cesium);
+    initialSignal.throwIfAborted();
+    const result = await executeAcceptedPlan(source, plan, initialSignal);
+    initialSignal.throwIfAborted();
+    let projection = projectSourceToCesium(source, plan, result, mountOptions);
+    const initialSpecs = materializeProjection(cesium, projection);
+    assertEntityIdsAvailable(collection, initialSpecs.keys());
+    let mounted = new Map();
+    const attemptedInitialIds = [];
+    try {
+        for (const [id, spec] of initialSpecs) {
+            initialSignal.throwIfAborted();
+            attemptedInitialIds.push(id);
+            mounted.set(id, spec);
+            collection.add(spec);
+            initialSignal.throwIfAborted();
+        }
+    }
+    catch (cause) {
+        // Include each attempted id: some renderer wrappers mutate and then throw.
+        const failures = removeIds(collection, attemptedInitialIds);
+        mounted = new Map();
+        if (initialSignal.aborted && failures.length === 0)
+            throw initialSignal.reason;
+        throw mutationError("Failed to mount Cesium entities transactionally.", cause, failures);
+    }
+    let state = projection.state;
+    let diagnostics = projection.diagnostics;
+    let refreshTail = Promise.resolve();
+    let lifecycleEpoch = 0;
+    let disposeActive = false;
+    const runRefresh = async (refreshOptions) => {
+        if (state === "disposed" || state === "disposing") {
+            throw new HonuaCesiumEntityAdapterError("disposed", "Cannot refresh a disposed Cesium entity mount.");
+        }
+        const currentEpoch = lifecycleEpoch;
+        const refreshContext = snapshotExecutionOptions(refreshOptions);
+        const signal = combineSignals([lifecycle.signal, refreshContext.signal]);
+        signal.throwIfAborted();
+        assertExecutionContext(source, plan, { ...executionOptions(mountOptions), ...refreshContext });
+        const nextResult = await executeAcceptedPlan(source, plan, signal);
+        signal.throwIfAborted();
+        assertLifecycleActive(currentEpoch, lifecycleEpoch, state, signal);
+        const next = projectSourceToCesium(source, plan, nextResult, mountOptions);
+        signal.throwIfAborted();
+        const nextSpecs = materializeProjection(cesium, next);
+        const previous = new Map(mounted);
+        assertEntityIdsAvailable(collection, [...nextSpecs.keys()].filter((id) => !previous.has(id)));
+        const attemptedNextIds = [];
+        try {
+            removeIdsOrThrow(collection, [...previous.keys()]);
+            assertLifecycleActive(currentEpoch, lifecycleEpoch, state, signal);
+            mounted = new Map();
+            for (const [id, spec] of nextSpecs) {
+                assertLifecycleActive(currentEpoch, lifecycleEpoch, state, signal);
+                attemptedNextIds.push(id);
+                mounted.set(id, spec);
+                collection.add(spec);
+                assertLifecycleActive(currentEpoch, lifecycleEpoch, state, signal);
+            }
+        }
+        catch (cause) {
+            const ownedSpecs = new Map([...previous, ...nextSpecs]);
+            const cleanupFailures = removeIds(collection, [...mounted.keys(), ...attemptedNextIds]);
+            mounted = presentOwnedSpecs(collection, ownedSpecs);
+            if (lifecycleInvalidated(currentEpoch, lifecycleEpoch, state)) {
+                if (cleanupFailures.length > 0) {
+                    throw mutationError("Cesium entity disposal interrupted refresh and cleanup was incomplete.", cause, cleanupFailures);
+                }
+                throw lifecycle.signal.reason;
+            }
+            const restoreFailures = [];
+            for (const [id, spec] of previous) {
+                try {
+                    assertLifecycleActive(currentEpoch, lifecycleEpoch, state, lifecycle.signal);
+                    mounted.set(id, spec);
+                    if (!collection.getById(id))
+                        collection.add(spec);
+                    assertLifecycleActive(currentEpoch, lifecycleEpoch, state, lifecycle.signal);
+                }
+                catch (error) {
+                    mounted.delete(id);
+                    restoreFailures.push(error);
+                    if (lifecycleInvalidated(currentEpoch, lifecycleEpoch, state))
+                        break;
+                }
+            }
+            if (lifecycleInvalidated(currentEpoch, lifecycleEpoch, state)) {
+                const rollbackOwnedSpecs = new Map(mounted);
+                const disposalCleanupFailures = removeIds(collection, [...rollbackOwnedSpecs.keys()]);
+                mounted = presentOwnedSpecs(collection, rollbackOwnedSpecs);
+                if (disposalCleanupFailures.length > 0) {
+                    throw mutationError("Cesium entity disposal interrupted rollback and cleanup was incomplete.", cause, [
+                        ...cleanupFailures,
+                        ...restoreFailures,
+                        ...disposalCleanupFailures,
+                    ]);
+                }
+                throw lifecycle.signal.reason;
+            }
+            if (signal.aborted && cleanupFailures.length === 0 && restoreFailures.length === 0)
+                throw signal.reason;
+            state = "degraded";
+            diagnostics = Object.freeze([
+                ...diagnostics,
+                diagnostic(source, plan, "incremental-update-failed", "warning", "update", "unsupported", "Cesium entity rebuild failed; restoration was attempted.", {
+                    rollbackSucceeded: cleanupFailures.length === 0 && restoreFailures.length === 0,
+                }),
+            ]);
+            throw mutationError("Failed to rebuild the mounted Cesium entity snapshot.", cause, [
+                ...cleanupFailures,
+                ...restoreFailures,
+            ]);
+        }
+        assertLifecycleActive(currentEpoch, lifecycleEpoch, state, signal);
+        diagnostics = Object.freeze([
+            ...next.diagnostics,
+            diagnostic(source, plan, "incremental-update", "info", "update", "equivalent", "Rebuilt the bounded entity snapshot while preserving stable entity ids.", {
+                previousEntityCount: previous.size,
+                nextEntityCount: mounted.size,
+                rebuildBoundary: "entity-snapshot",
+            }),
+        ]);
+        projection = Object.freeze({ ...next, diagnostics });
+        state = next.state;
+        return projection;
+    };
+    return {
+        strategy: "entity-query",
+        sourceId: projection.sourceId,
+        get entityIds() {
+            return [...mounted.keys()];
+        },
+        planId: plan.id,
+        planFingerprint: plan.fingerprint,
+        get state() {
+            return state;
+        },
+        get diagnostics() {
+            return diagnostics;
+        },
+        refresh(refreshOptions = {}) {
+            const refreshContext = snapshotExecutionOptions(refreshOptions);
+            const value = refreshTail.then(() => runRefresh(refreshContext));
+            refreshTail = value.then(() => undefined, () => undefined);
+            return value;
+        },
+        dispose() {
+            if (state === "disposed")
+                return;
+            if (disposeActive)
+                return;
+            disposeActive = true;
+            lifecycleEpoch += 1;
+            lifecycle.abort(new DOMException("Cesium entity mount disposed", "AbortError"));
+            state = "disposing";
+            try {
+                const failures = [];
+                for (const id of [...mounted.keys()]) {
+                    try {
+                        if (!collection.getById(id) || collection.removeById(id))
+                            mounted.delete(id);
+                        else
+                            failures.push(new Error(`Cesium refused to remove entity "${id}".`));
+                    }
+                    catch (error) {
+                        failures.push(error);
+                    }
+                }
+                if (failures.length > 0) {
+                    throw mutationError("Cesium entity disposal is incomplete and may be retried.", failures[0], failures);
+                }
+                state = "disposed";
+            }
+            finally {
+                disposeActive = false;
+            }
+        },
+    };
+}
+async function resolveCesium(injected) {
+    try {
+        const runtime = typeof injected === "function"
+            ? await injected()
+            : (injected ?? (await import("cesium")));
+        assertCesiumRuntime(runtime);
+        return runtime;
+    }
+    catch (cause) {
+        if (cause instanceof HonuaCesiumEntityAdapterError)
+            throw cause;
+        throw new HonuaCesiumEntityAdapterError("peer-unavailable", "Cesium entity mounting requires the optional cesium peer or an injected runtime module.", undefined, { cause });
+    }
+}
+function materializeProjection(cesium, projection) {
+    return new Map(projection.entities.map((item) => [item.id, materializeEntity(cesium, item)]));
+}
+function materializeEntity(cesium, item) {
+    const positions = item.geometry.kind === "point"
+        ? [toCartesian(cesium, item.geometry.coordinates)]
+        : item.geometry.coordinates.map((coordinate) => toCartesian(cesium, coordinate));
+    const geometry = item.geometry.kind === "point"
+        ? { position: positions[0], point: { pixelSize: 8 } }
+        : item.geometry.kind === "polyline"
+            ? { polyline: { positions, width: 2 } }
+            : { polygon: { hierarchy: new cesium.PolygonHierarchy(positions) } };
+    const availability = item.interval
+        ? new cesium.TimeIntervalCollection([
+            new cesium.TimeInterval({
+                start: cesium.JulianDate.fromIso8601(item.interval.start),
+                stop: cesium.JulianDate.fromIso8601(item.interval.end),
+            }),
+        ])
+        : undefined;
+    return Object.freeze({
+        id: item.id,
+        properties: item.properties,
+        ...geometry,
+        ...(availability ? { availability } : {}),
+    });
+}
+function toCartesian(cesium, coordinate) {
+    return cesium.Cartesian3.fromDegrees(coordinate[0], coordinate[1], coordinate[2]);
+}
+function projectGeometry(feature) {
+    const value = feature.geometry;
+    if (!value || typeof value !== "object")
+        return undefined;
+    const geometry = value;
+    if (isFiniteNumber(geometry.x) && isFiniteNumber(geometry.y)) {
+        if (!validLongitudeLatitude(geometry.x, geometry.y) || !validOptionalHeight(geometry, "z"))
+            return undefined;
+        const height = isFiniteNumber(geometry.z) ? geometry.z : 0;
+        return { kind: "point", coordinates: [geometry.x, geometry.y, height] };
+    }
+    if (geometry.type === "Point") {
+        const coordinate = coordinate3(geometry.coordinates);
+        return coordinate ? { kind: "point", coordinates: coordinate } : undefined;
+    }
+    if (geometry.type === "LineString") {
+        const coordinates = coordinates3(geometry.coordinates);
+        return coordinates && coordinates.length >= 2 ? { kind: "polyline", coordinates } : undefined;
+    }
+    if (geometry.type === "Polygon") {
+        const rings = geometry.coordinates;
+        if (!Array.isArray(rings) || rings.length !== 1 || !Object.hasOwn(rings, 0))
+            return undefined;
+        const coordinates = coordinates3(rings[0]);
+        return coordinates && validRing(coordinates) ? { kind: "polygon", coordinates } : undefined;
+    }
+    if (Array.isArray(geometry.paths) && geometry.paths.length === 1 && Object.hasOwn(geometry.paths, 0)) {
+        const coordinates = coordinates3(geometry.paths[0]);
+        return coordinates && coordinates.length >= 2 ? { kind: "polyline", coordinates } : undefined;
+    }
+    if (Array.isArray(geometry.rings) && geometry.rings.length === 1 && Object.hasOwn(geometry.rings, 0)) {
+        const coordinates = coordinates3(geometry.rings[0]);
+        return coordinates && validRing(coordinates) ? { kind: "polygon", coordinates } : undefined;
+    }
+    return undefined;
+}
+function geometryHasZ(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const geometry = value;
+    if (Object.hasOwn(geometry, "z"))
+        return true;
+    const candidate = geometry.coordinates ?? geometry.paths ?? geometry.rings;
+    return coordinateTreeHasZ(candidate);
+}
+function coordinateTreeHasZ(value) {
+    if (!Array.isArray(value))
+        return false;
+    if (Object.hasOwn(value, 0) && Object.hasOwn(value, 1) && isFiniteNumber(value[0]) && isFiniteNumber(value[1]))
+        return value.length >= 3 && Object.hasOwn(value, 2);
+    for (let index = 0; index < value.length; index += 1) {
+        if (!Object.hasOwn(value, index))
+            return false;
+        if (coordinateTreeHasZ(value[index]))
+            return true;
+    }
+    return false;
+}
+function coordinate3(value) {
+    if (!Array.isArray(value) ||
+        value.length < 2 ||
+        value.length > 3 ||
+        !Object.hasOwn(value, 0) ||
+        !Object.hasOwn(value, 1) ||
+        (value.length === 3 && !Object.hasOwn(value, 2)) ||
+        !isFiniteNumber(value[0]) ||
+        !isFiniteNumber(value[1]) ||
+        !validLongitudeLatitude(value[0], value[1]) ||
+        (value.length === 3 && !isFiniteNumber(value[2])))
+        return undefined;
+    return [value[0], value[1], value.length === 3 ? value[2] : 0];
+}
+function coordinates3(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const result = [];
+    for (let index = 0; index < value.length; index += 1) {
+        if (!Object.hasOwn(value, index))
+            return undefined;
+        const coordinate = coordinate3(value[index]);
+        if (!coordinate)
+            return undefined;
+        result.push(coordinate);
+    }
+    return result;
+}
+function validLongitudeLatitude(longitude, latitude) {
+    return longitude >= -180 && longitude <= 180 && latitude >= -90 && latitude <= 90;
+}
+function validOptionalHeight(geometry, key) {
+    return !Object.hasOwn(geometry, key) || geometry[key] === undefined || isFiniteNumber(geometry[key]);
+}
+function validRing(coordinates) {
+    if (coordinates.length < 4)
+        return false;
+    const first = coordinates[0];
+    const last = coordinates.at(-1);
+    return first !== undefined && last !== undefined && first.every((value, index) => value === last[index]);
+}
+function projectInterval(attributes, time) {
+    const start = isoInstant(attributes[time.startField]);
+    const end = isoInstant(attributes[time.endField]);
+    if (!start || !end || Date.parse(end) < Date.parse(start))
+        return undefined;
+    return { start, end };
+}
+function isoInstant(value) {
+    if (typeof value === "number" && !Number.isSafeInteger(value))
+        return undefined;
+    if (typeof value === "string" && !validOffsetIsoInstant(value))
+        return undefined;
+    const date = typeof value === "number" || typeof value === "string" ? new Date(value) : undefined;
+    return date && Number.isFinite(date.getTime()) ? date.toISOString() : undefined;
+}
+const OFFSET_ISO_INSTANT = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,3})?(?:Z|([+-])(\d{2}):(\d{2}))$/;
+function validOffsetIsoInstant(value) {
+    const match = OFFSET_ISO_INSTANT.exec(value);
+    if (!match)
+        return false;
+    const [, yearText, monthText, dayText, hourText, minuteText, secondText, , offsetHourText, offsetMinuteText] = match;
+    const year = Number(yearText);
+    const month = Number(monthText);
+    const day = Number(dayText);
+    const hour = Number(hourText);
+    const minute = Number(minuteText);
+    const second = Number(secondText);
+    const offsetHour = offsetHourText === undefined ? 0 : Number(offsetHourText);
+    const offsetMinute = offsetMinuteText === undefined ? 0 : Number(offsetMinuteText);
+    const daysInMonth = month >= 1 && month <= 12 ? new Date(Date.UTC(year, month, 0)).getUTCDate() : 0;
+    return (day >= 1 &&
+        day <= daysInMonth &&
+        hour <= 23 &&
+        minute <= 59 &&
+        second <= 59 &&
+        offsetHour <= 14 &&
+        offsetMinute <= 59 &&
+        (offsetHour < 14 || offsetMinute === 0));
+}
+function validatePlanAndOptions(source, plan, options) {
+    if (!source.capabilities.has("query")) {
+        throw new HonuaCapabilityNotSupportedError("query", source.descriptor.protocol, source.descriptor.id);
+    }
+    const step = plan.steps[0];
+    const limit = plan.ir.query.pagination?.limit;
+    if (plan.steps.length !== 1 ||
+        step?.engine !== "remote" ||
+        step.operation !== "query" ||
+        plan.ir.query.aggregation !== undefined ||
+        plan.ir.query.returnGeometry !== true ||
+        !Number.isSafeInteger(limit) ||
+        limit <= 0) {
+        throw unsupportedPlan(plan);
+    }
+    if (canonicalStringify(toJsonValue(step.query)) !== canonicalStringify(toJsonValue(plan.ir.query))) {
+        throw new HonuaQueryPlanExecutionError("invalid-plan", "Remote query step does not match the accepted canonical query IR.");
+    }
+    const maxEntities = positiveInteger(options.maxEntities, DEFAULT_CESIUM_ENTITY_LIMIT, "maxEntities");
+    if (limit > maxEntities) {
+        throw new HonuaCesiumEntityAdapterError("entity-limit-exceeded", `Accepted query limit ${limit} exceeds the Cesium entity ceiling ${maxEntities}.`, { queryLimit: limit, maxEntities });
+    }
+    const outSr = plan.ir.query.outSr;
+    if (outSr !== 4326 && outSr !== "4326" && outSr !== "EPSG:4326") {
+        throw new HonuaCesiumEntityAdapterError("unsupported-crs", "Cesium entity projection requires an accepted query with outSr 4326; implicit or non-WGS84 coordinates are not reinterpreted.", { outSr });
+    }
+    const idField = options.featureIdField ?? source.descriptor.schema?.primaryKey;
+    if (!idField) {
+        throw new HonuaCesiumEntityAdapterError("invalid-option", "Cesium entity projection requires featureIdField or descriptor.schema.primaryKey.");
+    }
+    if (options.time !== undefined && (!options.time.startField || !options.time.endField)) {
+        throw new HonuaCesiumEntityAdapterError("invalid-option", "time.startField and time.endField must be non-empty.");
+    }
+    return maxEntities;
+}
+function unsupportedPlan(plan) {
+    return new HonuaCesiumEntityAdapterError("unsupported-plan", "Cesium entity mounting requires one bounded remote feature query with geometry.", { planId: plan.id, operations: plan.steps.map((step) => step.operation) });
+}
+function executeAcceptedPlan(source, plan, signal) {
+    const step = plan.steps[0];
+    if (!step || step.engine !== "remote" || step.operation !== "query")
+        throw unsupportedPlan(plan);
+    return source.query(queryFromCanonical(step.query, signal));
+}
+function assertProjectionPlanContext(source, plan) {
+    if (hashQueryPlanV1(plan) !== plan.fingerprint) {
+        throw new HonuaQueryPlanExecutionError("invalid-plan", "Plan content does not match its fingerprint.");
+    }
+    const identity = queryIrSourceIdentity(source.descriptor, {
+        schemaVersion: plan.ir.source.schemaVersion,
+        sourceVersion: plan.ir.source.sourceVersion,
+        authorizationScope: plan.ir.source.authorizationScope,
+    });
+    const runtimeCapabilities = [...source.capabilities].sort();
+    if (canonicalStringify(toJsonValue(identity)) !== canonicalStringify(toJsonValue(plan.ir.source)) ||
+        canonicalStringify(toJsonValue(runtimeCapabilities)) !==
+            canonicalStringify(toJsonValue([...source.descriptor.capabilities].sort()))) {
+        throw new HonuaQueryPlanExecutionError("plan-context-mismatch", "Source identity or capabilities do not match the accepted Cesium projection context.");
+    }
+}
+function assertExecutionContext(source, plan, options) {
+    const current = queryIrSourceIdentity(source.descriptor, options);
+    if (canonicalStringify(toJsonValue(current)) !== canonicalStringify(toJsonValue(plan.ir.source))) {
+        throw new HonuaQueryPlanExecutionError("plan-context-mismatch", "Source identity, version, capabilities, or authorization scope changed after planning.");
+    }
+}
+function diagnostic(source, plan, code, severity, stage, fidelity, message, detail) {
+    return Object.freeze({
+        code,
+        severity,
+        stage,
+        fidelity,
+        sourceId: source.descriptor.id,
+        planId: plan.id,
+        message,
+        ...(detail ? { detail: immutableJsonSnapshot(detail) } : {}),
+    });
+}
+function executionOptions(options) {
+    return {
+        ...(options.signal ? { signal: options.signal } : {}),
+        ...(options.schemaVersion ? { schemaVersion: options.schemaVersion } : {}),
+        ...(options.sourceVersion ? { sourceVersion: options.sourceVersion } : {}),
+        ...(options.authorizationScope ? { authorizationScope: options.authorizationScope } : {}),
+    };
+}
+function snapshotExecutionOptions(options) {
+    return Object.freeze({
+        ...(options.signal ? { signal: options.signal } : {}),
+        ...(options.schemaVersion !== undefined ? { schemaVersion: options.schemaVersion } : {}),
+        ...(options.sourceVersion !== undefined ? { sourceVersion: options.sourceVersion } : {}),
+        ...(options.authorizationScope ? { authorizationScope: Object.freeze([...options.authorizationScope]) } : {}),
+    });
+}
+function snapshotMountOptions(options) {
+    const execution = snapshotExecutionOptions(options);
+    return Object.freeze({
+        ...execution,
+        ...(options.cesium ? { cesium: options.cesium } : {}),
+        ...(options.featureIdField !== undefined ? { featureIdField: options.featureIdField } : {}),
+        ...(options.maxEntities !== undefined ? { maxEntities: options.maxEntities } : {}),
+        ...(options.verticalDatum !== undefined ? { verticalDatum: options.verticalDatum } : {}),
+        ...(options.time
+            ? {
+                time: Object.freeze({ startField: options.time.startField, endField: options.time.endField }),
+            }
+            : {}),
+    });
+}
+function assertLifecycleActive(expectedEpoch, currentEpoch, state, signal) {
+    if (lifecycleInvalidated(expectedEpoch, currentEpoch, state)) {
+        throw new DOMException("Cesium entity mount disposed", "AbortError");
+    }
+    signal.throwIfAborted();
+}
+function lifecycleInvalidated(expectedEpoch, currentEpoch, state) {
+    return expectedEpoch !== currentEpoch || state === "disposed" || state === "disposing";
+}
+function assertCesiumRuntime(value) {
+    const runtime = value;
+    if (!runtime ||
+        typeof runtime.Cartesian3?.fromDegrees !== "function" ||
+        typeof runtime.JulianDate?.fromIso8601 !== "function" ||
+        typeof runtime.TimeInterval !== "function" ||
+        typeof runtime.TimeIntervalCollection !== "function" ||
+        typeof runtime.PolygonHierarchy !== "function") {
+        throw new HonuaCesiumEntityAdapterError("peer-unavailable", "The Cesium runtime does not provide the entity adapter APIs required by this mount.");
+    }
+}
+const INVALID_JSON_ATTRIBUTE = Symbol("invalid-json-attribute");
+function immutableJsonSnapshot(value) {
+    const snapshot = snapshotJsonValue(value, new Set());
+    if (snapshot === INVALID_JSON_ATTRIBUTE)
+        throw new TypeError("Internal value is not JSON-like.");
+    return snapshot;
+}
+function snapshotJsonAttributes(value) {
+    const snapshot = snapshotJsonValue(value, new Set());
+    return snapshot !== INVALID_JSON_ATTRIBUTE && isPlainObject(snapshot)
+        ? snapshot
+        : undefined;
+}
+function snapshotJsonValue(value, ancestors) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : INVALID_JSON_ATTRIBUTE;
+    if (typeof value !== "object")
+        return INVALID_JSON_ATTRIBUTE;
+    if (ancestors.has(value))
+        return INVALID_JSON_ATTRIBUTE;
+    ancestors.add(value);
+    if (Array.isArray(value)) {
+        const copy = [];
+        for (let index = 0; index < value.length; index += 1) {
+            if (!Object.hasOwn(value, index)) {
+                ancestors.delete(value);
+                return INVALID_JSON_ATTRIBUTE;
+            }
+            const entry = snapshotJsonValue(value[index], ancestors);
+            if (entry === INVALID_JSON_ATTRIBUTE) {
+                ancestors.delete(value);
+                return INVALID_JSON_ATTRIBUTE;
+            }
+            copy.push(entry);
+        }
+        ancestors.delete(value);
+        return Object.freeze(copy);
+    }
+    if (!isPlainObject(value)) {
+        ancestors.delete(value);
+        return INVALID_JSON_ATTRIBUTE;
+    }
+    const copy = {};
+    for (const key of Reflect.ownKeys(value)) {
+        if (typeof key !== "string") {
+            ancestors.delete(value);
+            return INVALID_JSON_ATTRIBUTE;
+        }
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor?.enumerable || !("value" in descriptor)) {
+            ancestors.delete(value);
+            return INVALID_JSON_ATTRIBUTE;
+        }
+        const entry = snapshotJsonValue(descriptor.value, ancestors);
+        if (entry === INVALID_JSON_ATTRIBUTE) {
+            ancestors.delete(value);
+            return INVALID_JSON_ATTRIBUTE;
+        }
+        Object.defineProperty(copy, key, {
+            value: entry,
+            enumerable: true,
+            writable: false,
+            configurable: false,
+        });
+    }
+    ancestors.delete(value);
+    return Object.freeze(copy);
+}
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function removeIds(collection, ids) {
+    const failures = [];
+    for (const id of new Set(ids)) {
+        try {
+            if (collection.getById(id) && !collection.removeById(id))
+                failures.push(new Error(`Cesium refused to remove entity "${id}".`));
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    return failures;
+}
+function removeIdsOrThrow(collection, ids) {
+    const failures = removeIds(collection, ids);
+    if (failures.length > 0)
+        throw failures[0];
+}
+function presentOwnedSpecs(collection, specs) {
+    const present = new Map();
+    for (const [id, spec] of specs) {
+        try {
+            if (collection.getById(id))
+                present.set(id, spec);
+        }
+        catch {
+            // Conservatively retain ownership so a later disposal can retry the id.
+            present.set(id, spec);
+        }
+    }
+    return present;
+}
+function mutationError(message, cause, failures) {
+    return new HonuaCesiumEntityAdapterError("renderer-mutation-failed", message, { cleanupFailureCount: failures.length, cleanupFailures: failures.map(errorMessage) }, { cause });
+}
+function entityConflict(id) {
+    return new HonuaCesiumEntityAdapterError("entity-conflict", `Cesium entity "${id}" already exists.`, {
+        entityId: id,
+    });
+}
+function assertEntityIdsAvailable(collection, ids) {
+    for (const id of ids) {
+        if (collection.getById(id))
+            throw entityConflict(id);
+    }
+}
+function combineSignals(signals) {
+    const available = signals.filter((signal) => signal !== undefined);
+    return available.length === 1 ? available[0] : AbortSignal.any(available);
+}
+function safeId(value) {
+    const normalized = value.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+    let start = 0;
+    let end = normalized.length;
+    while (start < end && normalized.charCodeAt(start) === 45)
+        start += 1;
+    while (end > start && normalized.charCodeAt(end - 1) === 45)
+        end -= 1;
+    return normalized.slice(start, end) || "source";
+}
+function positiveInteger(value, fallback, name) {
+    const candidate = value ?? fallback;
+    if (!Number.isSafeInteger(candidate) || candidate <= 0) {
+        throw new HonuaCesiumEntityAdapterError("invalid-option", `${name} must be a positive safe integer.`, {
+            [name]: value,
+        });
+    }
+    return candidate;
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}