@honua/app-platform 0.1.1-beta.0 → 0.1.4-beta.0

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

@@ -5,7 +5,26 @@
  * 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.
+ * `refresh()` is a diff, not a rebuild (issue #1050). It runs the same
+ * discipline the beta primitive mount runs on (#930): identity is the projected
+ * entity id qualified by geometry kind, configuration is an order-independent
+ * fingerprint of the projected feature, a feature that cannot be fingerprinted
+ * is treated as changed rather than reusable, and every crossing is reported.
+ * The consequence a host can rely on is object identity: a feature whose row did
+ * not change keeps the *same* live `Entity`, so `viewer.selectedEntity`, a
+ * tracked entity, and a graphic the host mutated all survive a refresh. A
+ * feature that did change keeps its `Entity` too — only the facets that moved
+ * are written onto it.
+ *
+ * {@link mountCesiumScene} (`./cesium-scene-owner.ts`) composes this mount with
+ * the primitive mount under one owner, so a host does not sequence two
+ * teardowns itself.
+ *
+ * @experimental Held back from the beta `@honua/app-platform/scene-workspace`
+ *   tier: the slice has no symbology surface, and adding one means new required
+ *   shapes rather than purely additive ones (see `docs/cesium-entity-adapter.md`).
+ *   Not covered by the pre-1.0 semver contract. The scene primitive adapter
+ *   alongside it is beta.
  */
 import { HonuaCapabilityNotSupportedError } from "../core/errors.js";
 import { canonicalStringify, toJsonValue } from "../query-planner/canonical.js";
@@ -23,6 +42,33 @@ export class HonuaCesiumEntityAdapterError extends Error {
         this.name = "HonuaCesiumEntityAdapterError";
     }
 }
+/** The entity boundary vocabulary, in escalation order. */
+export const CESIUM_ENTITY_REBUILD_BOUNDARIES = Object.freeze([
+    "none",
+    "entity-configuration",
+    "entity-identity",
+    "snapshot-membership",
+    "entity-geometry-kind",
+    "unfingerprintable",
+]);
+const ENTITY_BOUNDARY_REASONS = Object.freeze({
+    none: "Identity and configuration are unchanged; the live entity was reused untouched.",
+    "entity-configuration": "The configuration fingerprint changed; the live entity was updated in place.",
+    "entity-identity": "The feature was not previously mounted; an entity was constructed for it.",
+    "snapshot-membership": "The feature left the snapshot; its entity was released.",
+    "entity-geometry-kind": "The feature's geometry kind changed; the entity was released and rebuilt.",
+    unfingerprintable: "The feature could not be fingerprinted deterministically and was rebuilt conservatively.",
+});
+/** Build one boundary report with the vocabulary's own stable reason text. */
+function entityRebuildBoundaryReport(entityId, boundary) {
+    return Object.freeze({
+        entityId,
+        boundary,
+        incremental: boundary === "none",
+        preserved: boundary === "none" || boundary === "entity-configuration",
+        reason: ENTITY_BOUNDARY_REASONS[boundary],
+    });
+}
 export function projectSourceToCesium(source, plan, result, options = {}) {
     assertProjectionPlanContext(source, plan);
     const maxEntities = validatePlanAndOptions(source, plan, options);
@@ -43,6 +89,7 @@ export function projectSourceToCesium(source, plan, result, options = {}) {
     let unsupportedGeometry = 0;
     let missingIdentity = 0;
     let invalidIntervals = 0;
+    let invalidPositionSamples = 0;
     let unsupportedVerticalDatum = 0;
     let unsupportedAttributes = 0;
     const entityIds = new Set();
@@ -71,6 +118,13 @@ export function projectSourceToCesium(source, plan, result, options = {}) {
             invalidIntervals += 1;
             continue;
         }
+        const positionSamples = options.time?.positionField
+            ? projectPositionSamples(attributes, options.time.positionField, geometry, options.verticalDatum)
+            : undefined;
+        if (positionSamples === null) {
+            invalidPositionSamples += 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 });
@@ -82,6 +136,7 @@ export function projectSourceToCesium(source, plan, result, options = {}) {
             properties: attributes,
             geometry: immutableJsonSnapshot(geometry),
             ...(interval ? { interval: immutableJsonSnapshot(interval) } : {}),
+            ...(positionSamples ? { positionSamples: immutableJsonSnapshot(positionSamples) } : {}),
         }));
         if (entities.length > maxEntities) {
             throw new HonuaCesiumEntityAdapterError("entity-limit-exceeded", `Cesium projection exceeded the ${maxEntities} entity safety ceiling.`, { maxEntities, sourceId: source.descriptor.id });
@@ -122,6 +177,9 @@ export function projectSourceToCesium(source, plan, result, options = {}) {
             omittedFeatureCount: invalidIntervals,
         }));
     }
+    if (invalidPositionSamples > 0) {
+        diagnostics.push(diagnostic(source, plan, "time-position-invalid", "warning", "project", "unsupported", `${invalidPositionSamples} temporal point track(s) were invalid and omitted.`, { omittedFeatureCount: invalidPositionSamples }));
+    }
     return Object.freeze({
         strategy: "entity-query",
         sourceId,
@@ -152,16 +210,16 @@ export async function mountSourceToCesium(collection, source, plan, options = {}
     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());
+    const initialRecords = materializeProjection(cesium, projection);
+    assertEntityIdsAvailable(collection, initialRecords.keys());
     let mounted = new Map();
     const attemptedInitialIds = [];
     try {
-        for (const [id, spec] of initialSpecs) {
+        for (const [id, record] of initialRecords) {
             initialSignal.throwIfAborted();
             attemptedInitialIds.push(id);
-            mounted.set(id, spec);
-            collection.add(spec);
+            mounted.set(id, record);
+            collection.add(record.spec);
             initialSignal.throwIfAborted();
         }
     }
@@ -175,6 +233,8 @@ export async function mountSourceToCesium(collection, source, plan, options = {}
     }
     let state = projection.state;
     let diagnostics = projection.diagnostics;
+    let rebuildBoundaries = Object.freeze([]);
+    let revision = 1;
     let refreshTail = Promise.resolve();
     let lifecycleEpoch = 0;
     let disposeActive = false;
@@ -192,58 +252,121 @@ export async function mountSourceToCesium(collection, source, plan, options = {}
         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 = [];
+        // ── Identity + configuration diff ──────────────────────────────
+        //
+        // Identity is the projected entity id qualified by geometry kind, exactly
+        // the discipline the beta primitive mount runs on (#930): a kind change owns
+        // a different renderer object, so it is a replacement rather than an update.
+        // A feature that cannot be fingerprinted is treated as changed, never as
+        // unchanged, so a stale entity can never claim to satisfy a snapshot it no
+        // longer matches. Nothing is materialized for a feature that is reused, so a
+        // steady-state refresh allocates no Cesium values at all.
+        const previous = mounted;
+        const nextRecords = new Map();
+        const boundaries = [];
+        const reusedIds = [];
+        const updatedIds = [];
+        const createdIds = [];
+        const updates = [];
+        const replacements = [];
+        const creations = [];
+        for (const item of next.entities) {
+            const existing = previous.get(item.id);
+            const facets = entityFacetFingerprints(item);
+            const boundary = entityRebuildBoundary(existing, item.geometry.kind, entityFingerprint(facets));
+            if (boundary === "none" && existing) {
+                nextRecords.set(item.id, existing);
+                reusedIds.push(item.id);
+                continue;
+            }
+            const record = materializeEntityRecord(cesium, item, facets);
+            nextRecords.set(item.id, record);
+            boundaries.push(entityRebuildBoundaryReport(item.id, boundary));
+            if (boundary === "entity-configuration" && existing) {
+                updates.push({ previous: existing, next: record });
+                updatedIds.push(item.id);
+            }
+            else if (existing) {
+                replacements.push(record);
+                createdIds.push(item.id);
+            }
+            else {
+                creations.push(record);
+                createdIds.push(item.id);
+            }
+        }
+        const departed = [];
+        for (const record of previous.values()) {
+            if (nextRecords.has(record.id))
+                continue;
+            departed.push(record);
+            boundaries.push(entityRebuildBoundaryReport(record.id, "snapshot-membership"));
+        }
+        const disposedIds = [...replacements.map((record) => record.id), ...departed.map((record) => record.id)];
+        assertEntityIdsAvailable(collection, creations.map((record) => record.id));
+        // Mutation order is chosen so that every step before the last is undoable:
+        // in-place writes are journaled, additions can be removed, and the entities
+        // that left the snapshot are released only once everything else has landed.
+        const writes = [];
+        const addedIds = [];
+        const replacedRecords = [];
         try {
-            removeIdsOrThrow(collection, [...previous.keys()]);
-            assertLifecycleActive(currentEpoch, lifecycleEpoch, state, signal);
-            mounted = new Map();
-            for (const [id, spec] of nextSpecs) {
+            for (const update of updates) {
                 assertLifecycleActive(currentEpoch, lifecycleEpoch, state, signal);
-                attemptedNextIds.push(id);
-                mounted.set(id, spec);
-                collection.add(spec);
+                updateEntityInPlace(collection, update.previous, update.next, writes);
                 assertLifecycleActive(currentEpoch, lifecycleEpoch, state, signal);
             }
+            for (const record of replacements) {
+                assertLifecycleActive(currentEpoch, lifecycleEpoch, state, signal);
+                const displaced = previous.get(record.id);
+                removeIdsOrThrow(collection, [record.id]);
+                if (displaced)
+                    replacedRecords.push(displaced);
+                collection.add(record.spec);
+                addedIds.push(record.id);
+                assertLifecycleActive(currentEpoch, lifecycleEpoch, state, signal);
+            }
+            for (const record of creations) {
+                assertLifecycleActive(currentEpoch, lifecycleEpoch, state, signal);
+                collection.add(record.spec);
+                addedIds.push(record.id);
+                assertLifecycleActive(currentEpoch, lifecycleEpoch, state, signal);
+            }
+            removeIdsOrThrow(collection, departed.map((record) => record.id));
+            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);
+            // Roll back only what this refresh touched. Entities it reused were never
+            // mutated, and the departed set is still attached because its removal is
+            // the last step, so recovery is a matter of undoing this refresh's own
+            // additions and writes rather than rebuilding the previous snapshot.
+            const cleanupFailures = removeIds(collection, addedIds);
+            const restoreFailures = [];
+            for (const record of replacedRecords) {
+                try {
+                    if (!collection.getById(record.id))
+                        collection.add(record.spec);
+                }
+                catch (error) {
+                    restoreFailures.push(error);
                 }
-                throw lifecycle.signal.reason;
             }
-            const restoreFailures = [];
-            for (const [id, spec] of previous) {
+            for (const write of [...writes].reverse()) {
                 try {
-                    assertLifecycleActive(currentEpoch, lifecycleEpoch, state, lifecycle.signal);
-                    mounted.set(id, spec);
-                    if (!collection.getById(id))
-                        collection.add(spec);
-                    assertLifecycleActive(currentEpoch, lifecycleEpoch, state, lifecycle.signal);
+                    write.target[write.key] = write.previous;
                 }
                 catch (error) {
-                    mounted.delete(id);
                     restoreFailures.push(error);
-                    if (lifecycleInvalidated(currentEpoch, lifecycleEpoch, state))
-                        break;
                 }
             }
+            mounted = presentOwnedRecords(collection, previous);
             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,
-                    ]);
+                const owned = new Map(mounted);
+                const disposalCleanupFailures = removeIds(collection, [...owned.keys()]);
+                mounted = presentOwnedRecords(collection, owned);
+                const failures = [...cleanupFailures, ...restoreFailures, ...disposalCleanupFailures];
+                if (failures.length > 0) {
+                    throw mutationError("Cesium entity disposal interrupted refresh and cleanup was incomplete.", cause, failures);
                 }
                 throw lifecycle.signal.reason;
             }
@@ -252,27 +375,55 @@ export async function mountSourceToCesium(collection, source, plan, options = {}
             state = "degraded";
             diagnostics = Object.freeze([
                 ...diagnostics,
-                diagnostic(source, plan, "incremental-update-failed", "warning", "update", "unsupported", "Cesium entity rebuild failed; restoration was attempted.", {
+                diagnostic(source, plan, "incremental-update-failed", "warning", "update", "unsupported", "Cesium entity reconciliation failed; restoration was attempted.", {
                     rollbackSucceeded: cleanupFailures.length === 0 && restoreFailures.length === 0,
                 }),
             ]);
-            throw mutationError("Failed to rebuild the mounted Cesium entity snapshot.", cause, [
+            throw mutationError("Failed to reconcile the mounted Cesium entity snapshot.", cause, [
                 ...cleanupFailures,
                 ...restoreFailures,
             ]);
         }
-        assertLifecycleActive(currentEpoch, lifecycleEpoch, state, signal);
+        mounted = nextRecords;
+        revision += 1;
+        rebuildBoundaries = Object.freeze([...boundaries]);
+        const escalated = escalatedEntityBoundary(rebuildBoundaries);
         diagnostics = Object.freeze([
             ...next.diagnostics,
-            diagnostic(source, plan, "incremental-update", "info", "update", "equivalent", "Rebuilt the bounded entity snapshot while preserving stable entity ids.", {
+            diagnostic(source, plan, "incremental-update", "info", "update", "equivalent", `Reconciled the bounded entity snapshot: reused ${reusedIds.length}, updated ${updatedIds.length} in place, created ${createdIds.length}, disposed ${disposedIds.length}.`, {
+                revision,
                 previousEntityCount: previous.size,
                 nextEntityCount: mounted.size,
-                rebuildBoundary: "entity-snapshot",
+                reusedEntityCount: reusedIds.length,
+                updatedEntityCount: updatedIds.length,
+                createdEntityCount: createdIds.length,
+                disposedEntityCount: disposedIds.length,
+                rebuildBoundary: escalated,
+                rebuildBoundaryCounts: boundaryCounts(rebuildBoundaries),
             }),
+            ...(rebuildBoundaries.some((report) => !report.preserved)
+                ? [
+                    diagnostic(source, plan, "rebuild-boundary", "info", "update", "equivalent", `Revision ${revision} could not carry every entity across in place; the highest boundary crossed was ${escalated}.`, {
+                        revision,
+                        rebuildBoundary: escalated,
+                        rebuildBoundaryCounts: boundaryCounts(rebuildBoundaries),
+                        replacedEntityCount: replacements.length,
+                        departedEntityCount: departed.length,
+                    }),
+                ]
+                : []),
         ]);
         projection = Object.freeze({ ...next, diagnostics });
         state = next.state;
-        return projection;
+        return Object.freeze({
+            ...projection,
+            revision,
+            reused: Object.freeze(reusedIds),
+            updated: Object.freeze(updatedIds),
+            created: Object.freeze(createdIds),
+            disposed: Object.freeze(disposedIds),
+            rebuildBoundaries,
+        });
     };
     return {
         strategy: "entity-query",
@@ -288,6 +439,12 @@ export async function mountSourceToCesium(collection, source, plan, options = {}
         get diagnostics() {
             return diagnostics;
         },
+        get revision() {
+            return revision;
+        },
+        get rebuildBoundaries() {
+            return rebuildBoundaries;
+        },
         refresh(refreshOptions = {}) {
             const refreshContext = snapshotExecutionOptions(refreshOptions);
             const value = refreshTail.then(() => runRefresh(refreshContext));
@@ -342,17 +499,155 @@ async function resolveCesium(injected) {
     }
 }
 function materializeProjection(cesium, projection) {
-    return new Map(projection.entities.map((item) => [item.id, materializeEntity(cesium, item)]));
+    return new Map(projection.entities.map((item) => [item.id, materializeEntityRecord(cesium, item, entityFacetFingerprints(item))]));
+}
+function materializeEntityRecord(cesium, item, facets) {
+    return {
+        id: item.id,
+        kind: item.geometry.kind,
+        fingerprint: entityFingerprint(facets),
+        facets,
+        spec: materializeEntity(cesium, item),
+    };
+}
+/**
+ * Per-facet, order-independent fingerprints of one projected feature.
+ *
+ * Splitting the fingerprint by facet is what lets a changed feature be updated
+ * in place surgically: a feature that only moved rewrites its position and
+ * leaves its property bag and availability — and anything the host attached to
+ * them — alone.
+ *
+ * A facet is `undefined` when it cannot be fingerprinted deterministically.
+ * `projectSourceToCesium` only ever emits deeply frozen JSON-like snapshots, so
+ * that is unreachable through the public path today; it is the fail-closed
+ * backstop for the day the projection admits a value canonicalization refuses,
+ * and it resolves to "assume changed" rather than "assume reusable".
+ */
+function entityFacetFingerprints(item) {
+    return {
+        geometry: fingerprintFacet({ geometry: item.geometry, positionSamples: item.positionSamples ?? null }),
+        properties: fingerprintFacet(item.properties),
+        availability: fingerprintFacet(item.interval ?? null),
+    };
+}
+function fingerprintFacet(value) {
+    try {
+        return canonicalStringify(toJsonValue(value));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * A stable, order-independent fingerprint of a projected feature's whole
+ * configuration, or `undefined` when any facet could not be fingerprinted.
+ *
+ * @internal Exported for unit coverage of the diff's fail-closed behavior; not
+ *   part of the `scene-workspace` barrel.
+ */
+export function cesiumEntityFingerprint(item) {
+    return entityFingerprint(entityFacetFingerprints(item));
+}
+function entityFingerprint(facets) {
+    if (facets.geometry === undefined || facets.properties === undefined || facets.availability === undefined) {
+        return undefined;
+    }
+    return `${facets.geometry}${facets.properties}${facets.availability}`;
+}
+/**
+ * Classify one projected feature against what this mount already owns.
+ *
+ * The order matters, and mirrors the primitive mount's: a feature the mount has
+ * never seen is an identity crossing regardless of whether it can be
+ * fingerprinted, a geometry-kind change is a replacement rather than a
+ * configuration change, and an unfingerprintable feature is called out as such
+ * instead of being reported as a change nobody made.
+ */
+function entityRebuildBoundary(previous, kind, fingerprint) {
+    if (previous === undefined)
+        return "entity-identity";
+    if (previous.kind !== kind)
+        return "entity-geometry-kind";
+    if (fingerprint === undefined || previous.fingerprint === undefined)
+        return "unfingerprintable";
+    return previous.fingerprint === fingerprint ? "none" : "entity-configuration";
+}
+function escalatedEntityBoundary(reports) {
+    let escalated = "none";
+    for (const report of reports) {
+        if (CESIUM_ENTITY_REBUILD_BOUNDARIES.indexOf(report.boundary) > CESIUM_ENTITY_REBUILD_BOUNDARIES.indexOf(escalated)) {
+            escalated = report.boundary;
+        }
+    }
+    return escalated;
+}
+function boundaryCounts(reports) {
+    const counts = {};
+    for (const report of reports)
+        counts[report.boundary] = (counts[report.boundary] ?? 0) + 1;
+    return counts;
+}
+/**
+ * Write a changed feature onto the `Entity` that already represents it.
+ *
+ * Only the facets whose fingerprint moved are assigned, and geometry is written
+ * at the deepest field Cesium accepts — `polyline.positions` rather than a fresh
+ * `polyline` — so a host that adjusted the graphic's width or material keeps it.
+ * Every assignment is journaled with the value it displaced so a later failure
+ * in the same refresh can undo it exactly.
+ */
+function updateEntityInPlace(collection, previous, next, writes) {
+    const live = collection.getById(next.id);
+    if (!isMutableRecord(live)) {
+        throw new HonuaCesiumEntityAdapterError("renderer-mutation-failed", `Cesium entity "${next.id}" is no longer available for an in-place update.`, { entityId: next.id });
+    }
+    if (previous.facets.geometry !== next.facets.geometry) {
+        for (const write of geometryWrites(live, next))
+            applyEntityWrite(write.target, write.key, write.value, writes);
+    }
+    if (previous.facets.properties !== next.facets.properties) {
+        applyEntityWrite(live, "properties", next.spec.properties, writes);
+    }
+    if (previous.facets.availability !== next.facets.availability) {
+        applyEntityWrite(live, "availability", next.spec.availability, writes);
+    }
+}
+function geometryWrites(live, next) {
+    if (next.kind === "point")
+        return [{ target: live, key: "position", value: next.spec.position }];
+    const graphicsKey = next.kind === "polyline" ? "polyline" : "polygon";
+    const positionsKey = next.kind === "polyline" ? "positions" : "hierarchy";
+    const graphics = live[graphicsKey];
+    const nextGraphics = next.spec[graphicsKey];
+    if (isMutableRecord(graphics) && isMutableRecord(nextGraphics)) {
+        return [{ target: graphics, key: positionsKey, value: nextGraphics[positionsKey] }];
+    }
+    return [{ target: live, key: graphicsKey, value: nextGraphics }];
+}
+function applyEntityWrite(target, key, value, writes) {
+    writes.push({ target, key, previous: target[key] });
+    target[key] = value;
+}
+function isMutableRecord(value) {
+    return typeof value === "object" && value !== null && !Object.isFrozen(value);
 }
 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 } }
+        ? {
+            position: item.positionSamples ? sampledPosition(cesium, item.positionSamples) : positions[0],
+            point: { pixelSize: 8 },
+        }
         : item.geometry.kind === "polyline"
             ? { polyline: { positions, width: 2 } }
-            : { polygon: { hierarchy: new cesium.PolygonHierarchy(positions) } };
+            : {
+                polygon: {
+                    hierarchy: new cesium.PolygonHierarchy(positions, item.geometry.holes?.map((hole) => new cesium.PolygonHierarchy(hole.map((coordinate) => toCartesian(cesium, coordinate))))),
+                },
+            };
     const availability = item.interval
         ? new cesium.TimeIntervalCollection([
             new cesium.TimeInterval({
@@ -368,6 +663,16 @@ function materializeEntity(cesium, item) {
         ...(availability ? { availability } : {}),
     });
 }
+function sampledPosition(cesium, samples) {
+    if (!cesium.SampledPositionProperty) {
+        throw new HonuaCesiumEntityAdapterError("peer-unavailable", "The Cesium runtime does not provide SampledPositionProperty for temporal entities.");
+    }
+    const property = new cesium.SampledPositionProperty();
+    for (const sample of samples) {
+        property.addSample(cesium.JulianDate.fromIso8601(sample.time), toCartesian(cesium, sample.coordinates));
+    }
+    return property;
+}
 function toCartesian(cesium, coordinate) {
     return cesium.Cartesian3.fromDegrees(coordinate[0], coordinate[1], coordinate[2]);
 }
@@ -391,22 +696,89 @@ function projectGeometry(feature) {
         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;
+        const rings = polygonRings(geometry.coordinates);
+        return rings
+            ? { kind: "polygon", coordinates: rings.outer, ...(rings.holes.length ? { holes: rings.holes } : {}) }
+            : 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;
+    if (Array.isArray(geometry.rings)) {
+        const rings = polygonRings(geometry.rings, true);
+        return rings
+            ? { kind: "polygon", coordinates: rings.outer, ...(rings.holes.length ? { holes: rings.holes } : {}) }
+            : undefined;
     }
     return undefined;
 }
+function polygonRings(value, esriConvention = false) {
+    return polygonRingsWithConvention(value, esriConvention);
+}
+function polygonRingsWithConvention(value, esriConvention) {
+    if (!Array.isArray(value) || value.length === 0)
+        return undefined;
+    for (let index = 0; index < value.length; index += 1) {
+        if (!Object.hasOwn(value, index))
+            return undefined;
+    }
+    const projected = value.map((ring) => {
+        const coordinates = coordinates3(ring);
+        return coordinates && validRing(coordinates) ? coordinates : undefined;
+    });
+    if (projected.some((ring) => ring === undefined))
+        return undefined;
+    const rings = projected;
+    if (esriConvention)
+        return classifyEsriPolygonRings(rings);
+    const [outer, ...holes] = rings;
+    return { outer, holes };
+}
+function classifyEsriPolygonRings(rings) {
+    const exteriors = rings.filter((ring) => signedRingArea(ring) < 0);
+    if (exteriors.length !== 1)
+        return undefined;
+    const outer = exteriors[0];
+    if (!outer)
+        return undefined;
+    const holes = [];
+    for (const ring of rings) {
+        if (ring === outer)
+            continue;
+        if (signedRingArea(ring) <= 0 || !ringPointInside(ring[0], outer))
+            return undefined;
+        holes.push(ring);
+    }
+    return { outer, holes };
+}
+function signedRingArea(ring) {
+    let area = 0;
+    for (let index = 0; index < ring.length - 1; index += 1) {
+        const current = ring[index];
+        const next = ring[index + 1];
+        if (!current || !next)
+            return 0;
+        area += current[0] * next[1] - next[0] * current[1];
+    }
+    return area / 2;
+}
+function ringPointInside(point, ring) {
+    if (!point)
+        return false;
+    let inside = false;
+    for (let index = 0, previous = ring.length - 1; index < ring.length; previous = index, index += 1) {
+        const current = ring[index];
+        const prior = ring[previous];
+        if (!current || !prior)
+            return false;
+        const intersects = current[1] > point[1] !== prior[1] > point[1] &&
+            point[0] < ((prior[0] - current[0]) * (point[1] - current[1])) / (prior[1] - current[1]) + current[0];
+        if (intersects)
+            inside = !inside;
+    }
+    return inside;
+}
 function geometryHasZ(value) {
     if (!value || typeof value !== "object")
         return false;
@@ -471,12 +843,45 @@ function validRing(coordinates) {
     return first !== undefined && last !== undefined && first.every((value, index) => value === last[index]);
 }
 function projectInterval(attributes, time) {
+    if (time.instantField !== undefined) {
+        const instant = isoInstant(attributes[time.instantField]);
+        return instant ? { start: instant, end: instant } : undefined;
+    }
     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 projectPositionSamples(attributes, field, geometry, verticalDatum) {
+    if (geometry.kind !== "point")
+        return null;
+    const value = attributes[field];
+    if (value === undefined)
+        return null;
+    if (!Array.isArray(value) || value.length < 2)
+        return null;
+    const samples = [];
+    let previous = Number.NEGATIVE_INFINITY;
+    for (const entry of value) {
+        if (!entry || typeof entry !== "object")
+            return null;
+        const record = entry;
+        const time = isoInstant(record.time);
+        if (Array.isArray(record.coordinates) && record.coordinates.length >= 3 && verticalDatum !== "ellipsoidal-wgs84") {
+            return null;
+        }
+        const coordinates = coordinate3(record.coordinates);
+        if (!time || !coordinates)
+            return null;
+        const epoch = Date.parse(time);
+        if (epoch <= previous)
+            return null;
+        previous = epoch;
+        samples.push({ time, coordinates });
+    }
+    return samples;
+}
 function isoInstant(value) {
     if (typeof value === "number" && !Number.isSafeInteger(value))
         return undefined;
@@ -539,11 +944,27 @@ function validatePlanAndOptions(source, plan, options) {
     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.");
-    }
+    if (options.time !== undefined)
+        assertTimeOptions(options.time);
     return maxEntities;
 }
+/**
+ * Accept exactly one temporal mapping. A mixed instant/interval request is a
+ * caller mistake that TypeScript unions and untyped callers cannot both catch,
+ * so it is rejected instead of silently preferring either variant.
+ */
+function assertTimeOptions(time) {
+    const declared = time;
+    const instantMapping = declared.instantField !== undefined;
+    const intervalMapping = declared.startField !== undefined || declared.endField !== undefined;
+    if (instantMapping === intervalMapping) {
+        throw new HonuaCesiumEntityAdapterError("invalid-option", "time must declare exactly one of instantField or startField/endField.");
+    }
+    const fields = instantMapping ? [declared.instantField] : [declared.startField, declared.endField];
+    if (fields.some((field) => typeof field !== "string" || field.length === 0)) {
+        throw new HonuaCesiumEntityAdapterError("invalid-option", "time.instantField or time.startField/time.endField must be non-empty.");
+    }
+}
 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) });
 }
@@ -611,13 +1032,17 @@ function snapshotMountOptions(options) {
         ...(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 }),
-            }
-            : {}),
+        ...(options.time ? { time: snapshotTimeOptions(options.time) } : {}),
     });
 }
+/** Validate before narrowing so a mixed mapping cannot be normalized away. */
+function snapshotTimeOptions(time) {
+    assertTimeOptions(time);
+    const position = time.positionField !== undefined ? { positionField: time.positionField } : {};
+    if (time.instantField !== undefined)
+        return Object.freeze({ instantField: time.instantField, ...position });
+    return Object.freeze({ startField: time.startField, endField: time.endField, ...position });
+}
 function assertLifecycleActive(expectedEpoch, currentEpoch, state, signal) {
     if (lifecycleInvalidated(expectedEpoch, currentEpoch, state)) {
         throw new DOMException("Cesium entity mount disposed", "AbortError");
@@ -732,16 +1157,16 @@ function removeIdsOrThrow(collection, ids) {
     if (failures.length > 0)
         throw failures[0];
 }
-function presentOwnedSpecs(collection, specs) {
+function presentOwnedRecords(collection, records) {
     const present = new Map();
-    for (const [id, spec] of specs) {
+    for (const [id, record] of records) {
         try {
             if (collection.getById(id))
-                present.set(id, spec);
+                present.set(id, record);
         }
         catch {
             // Conservatively retain ownership so a later disposal can retry the id.
-            present.set(id, spec);
+            present.set(id, record);
         }
     }
     return present;