@world-engines/spatial-authoring 0.1.0-alpha.0

package/dist/spatial-runtime.js

@@ -0,0 +1,1231 @@
+import { generateBuildingInterior, generateCityLayout, generateParcelBuildings, validateProceduralWorld, } from "./procedural-city.js";
+import { generateRoadParcels } from "./road-parcels.js";
+import { roadParcelAlgorithm, validateRoadGeneration } from "./road-generation.js";
+import { resolveRoadParcelTemplateSettings } from "./spatial-templates.js";
+export const SPATIAL_DELTA_VERSION = 1;
+export const SPATIAL_RUNTIME_CACHE_LIMITS = Object.freeze({
+    cityLayouts: 8,
+    activatedParcels: 128,
+    buildingInteriors: 64,
+});
+export const SPATIAL_DELTA_QUOTAS = Object.freeze({
+    maxOverrides: 2_048,
+    maxTombstones: 2_048,
+    maxUtf8Bytes: 1_048_576,
+});
+export const BUILDING_ENTRANCE_TOLERANCE_METERS = 1.5;
+const TERRAIN_ROAD_MAX_GRID_SIDE = 257;
+const TERRAIN_ROAD_MAX_GRID_CELLS = TERRAIN_ROAD_MAX_GRID_SIDE * TERRAIN_ROAD_MAX_GRID_SIDE;
+const TERRAIN_ROAD_MAX_CITIES = 256;
+const TERRAIN_ROAD_MAX_ROADS = 16_384;
+const TERRAIN_ROAD_MAX_UNREACHABLE = 16_384;
+const TERRAIN_ROAD_MAX_SEGMENTS_PER_ROAD = 2_048;
+const TERRAIN_ROAD_MAX_POINTS_PER_PATH = TERRAIN_ROAD_MAX_GRID_CELLS;
+export class SpatialRuntimeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "SpatialRuntimeError";
+        this.code = code;
+    }
+}
+const RUNTIME_OPTION_KEYS = ["world", "roadNetwork", "roadGeneration", "binding", "readControlledPose"];
+const BINDING_KEYS = ["artifactDigest", "baseDigest", "worldlineId", "controlledActorId"];
+const DELTA_KEYS = ["version", "binding", "overrides", "tombstones"];
+const DELTA_BINDING_KEYS = ["artifactDigest", "baseDigest", "worldlineId"];
+const OVERRIDE_KEYS = ["targetType", "targetId", "locator", "field", "value"];
+const TOMBSTONE_KEYS = ["targetType", "targetId", "locator"];
+const CITY_LOCATOR_KEYS = ["cityId"];
+const PARCEL_LOCATOR_KEYS = ["cityId", "parcelId"];
+const BUILDING_LOCATOR_KEYS = ["cityId", "parcelId", "buildingId"];
+const OVERRIDE_FIELDS = Object.freeze(["label", "blocked", "destroyed"]);
+const TARGET_TYPES = Object.freeze([
+    "city", "road", "parcel", "building", "room", "door",
+]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertRecord(value, label) {
+    if (!isRecord(value))
+        throw deltaError(`${label} 必须是对象`);
+}
+function assertExactKeys(value, keys, label) {
+    const expected = new Set(keys);
+    const unknown = Object.keys(value).filter((key) => !expected.has(key));
+    if (unknown.length > 0)
+        throw deltaError(`${label} 包含未知字段：${unknown.join(", ")}`);
+    const missing = keys.filter((key) => !Object.hasOwn(value, key));
+    if (missing.length > 0)
+        throw deltaError(`${label} 缺少字段：${missing.join(", ")}`);
+}
+function deltaError(message) {
+    return new SpatialRuntimeError("DELTA_INVALID", message);
+}
+function nonEmptyIdentity(value, label, maximum = 256) {
+    if (typeof value !== "string" || value.length < 1 || value.length > maximum || /[\u0000-\u001f\u007f\s]/u.test(value)) {
+        throw new TypeError(`${label} 必须是 1..${maximum} 字符且不含空白/控制字符`);
+    }
+    return value;
+}
+function sha256Digest(value, label) {
+    if (typeof value !== "string" || !/^[0-9a-f]{64}$/u.test(value)) {
+        throw new TypeError(`${label} 必须是 64 位小写十六进制 SHA-256`);
+    }
+    return value;
+}
+function stableId(value, label) {
+    if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(value)) {
+        throw deltaError(`${label} 必须是稳定 identifier`);
+    }
+    return value;
+}
+function validateLocator(value, type, label) {
+    assertRecord(value, label);
+    if (type === "city" || type === "road" || type === "parcel") {
+        assertExactKeys(value, CITY_LOCATOR_KEYS, label);
+        return Object.freeze({ cityId: stableId(value.cityId, `${label}.cityId`) });
+    }
+    if (type === "building") {
+        assertExactKeys(value, PARCEL_LOCATOR_KEYS, label);
+        return Object.freeze({
+            cityId: stableId(value.cityId, `${label}.cityId`),
+            parcelId: stableId(value.parcelId, `${label}.parcelId`),
+        });
+    }
+    assertExactKeys(value, BUILDING_LOCATOR_KEYS, label);
+    return Object.freeze({
+        cityId: stableId(value.cityId, `${label}.cityId`),
+        parcelId: stableId(value.parcelId, `${label}.parcelId`),
+        buildingId: stableId(value.buildingId, `${label}.buildingId`),
+    });
+}
+function targetType(value, label) {
+    if (typeof value !== "string" || !TARGET_TYPES.includes(value)) {
+        throw deltaError(`${label} 非法`);
+    }
+    return value;
+}
+function overrideField(value, label) {
+    if (typeof value !== "string" || !OVERRIDE_FIELDS.includes(value)) {
+        throw deltaError(`${label} 非法；只允许 label/blocked/destroyed，禁止 geometry`);
+    }
+    return value;
+}
+function overrideValue(field, value, label) {
+    if (field === "label") {
+        if (typeof value !== "string" || value.trim().length < 1 || value.trim().length > 128) {
+            throw deltaError(`${label} 必须是 1..128 字符的非空 label`);
+        }
+        return value.trim();
+    }
+    if (typeof value !== "boolean")
+        throw deltaError(`${label} 必须是 boolean`);
+    return value;
+}
+function finiteMetric(value, label) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        throw new TypeError(`${label} 必须是有限数`);
+    return value;
+}
+function validateBounds(value, label) {
+    if (!isRecord(value))
+        throw new TypeError(`${label} 必须是对象`);
+    const x = finiteMetric(value.x, `${label}.x`);
+    const y = finiteMetric(value.y, `${label}.y`);
+    const width = finiteMetric(value.width, `${label}.width`);
+    const height = finiteMetric(value.height, `${label}.height`);
+    if (width <= 0 || height <= 0)
+        throw new RangeError(`${label} 尺寸必须大于 0`);
+    return Object.freeze({ x, y, width, height });
+}
+function validateRevision(value) {
+    if (typeof value === "string" && value.length > 0 && value.length <= 256)
+        return value;
+    if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0)
+        return value;
+    throw new SpatialRuntimeError("HOST_POSE_INVALID", "Host pose.revision 必须是非空字符串或非负安全整数");
+}
+function intersects(first, second) {
+    return first.x <= second.x + second.width
+        && first.x + first.width >= second.x
+        && first.y <= second.y + second.height
+        && first.y + first.height >= second.y;
+}
+function contains(bounds, x, y) {
+    return x >= bounds.x && x <= bounds.x + bounds.width
+        && y >= bounds.y && y <= bounds.y + bounds.height;
+}
+function roadBounds(road) {
+    if (road.points.length < 2)
+        throw new TypeError("road.points 至少需要两个点");
+    const margin = road.widthMeters / 2;
+    let minimumX = Number.POSITIVE_INFINITY;
+    let minimumY = Number.POSITIVE_INFINITY;
+    let maximumX = Number.NEGATIVE_INFINITY;
+    let maximumY = Number.NEGATIVE_INFINITY;
+    for (const point of road.points) {
+        minimumX = Math.min(minimumX, point.x);
+        minimumY = Math.min(minimumY, point.y);
+        maximumX = Math.max(maximumX, point.x);
+        maximumY = Math.max(maximumY, point.y);
+    }
+    return {
+        x: minimumX - margin,
+        y: minimumY - margin,
+        width: maximumX - minimumX + margin * 2,
+        height: maximumY - minimumY + margin * 2,
+    };
+}
+/** polygon 的 bounds 仅服务 viewport 索引；进入 gate 始终使用真实 polygon containment。 */
+function parcelViewportBounds(parcel) {
+    if (parcel.polygon === undefined)
+        return parcel.bounds;
+    let minimumX = Number.POSITIVE_INFINITY;
+    let minimumY = Number.POSITIVE_INFINITY;
+    let maximumX = Number.NEGATIVE_INFINITY;
+    let maximumY = Number.NEGATIVE_INFINITY;
+    for (const point of parcel.polygon) {
+        minimumX = Math.min(minimumX, point.x);
+        minimumY = Math.min(minimumY, point.y);
+        maximumX = Math.max(maximumX, point.x);
+        maximumY = Math.max(maximumY, point.y);
+    }
+    return { x: minimumX, y: minimumY, width: maximumX - minimumX, height: maximumY - minimumY };
+}
+function polygonSignedArea(points) {
+    let twiceArea = 0;
+    for (let index = 0; index < points.length; index += 1) {
+        const current = points[index];
+        const next = points[(index + 1) % points.length];
+        if (current === undefined || next === undefined)
+            continue;
+        twiceArea += current.x * next.y - next.x * current.y;
+    }
+    return twiceArea / 2;
+}
+function orientation(a, b, c) {
+    return (b.x - a.x) * (c.y - a.y) - (b.y - a.y) * (c.x - a.x);
+}
+function properSegmentsIntersect(a, b, c, d) {
+    const abC = orientation(a, b, c);
+    const abD = orientation(a, b, d);
+    const cdA = orientation(c, d, a);
+    const cdB = orientation(c, d, b);
+    return ((abC > 0 && abD < 0) || (abC < 0 && abD > 0))
+        && ((cdA > 0 && cdB < 0) || (cdA < 0 && cdB > 0));
+}
+function boundaryIsSimple(points) {
+    for (let first = 0; first < points.length; first += 1) {
+        const a = points[first];
+        const b = points[(first + 1) % points.length];
+        for (let second = first + 1; second < points.length; second += 1) {
+            if (second === first || second === first + 1 || (first === 0 && second === points.length - 1))
+                continue;
+            const c = points[second];
+            const d = points[(second + 1) % points.length];
+            if (properSegmentsIntersect(a, b, c, d))
+                return false;
+        }
+    }
+    return true;
+}
+function validateTerrainCityBoundary(value, city, label) {
+    if (!isRecord(value) || Object.keys(value).some((key) => key !== "status" && key !== "cityId" && key !== "points")) {
+        throw new TypeError(`${label} 必须是严格 boundary 对象`);
+    }
+    if (value.cityId !== city.id || (value.status !== "bounded" && value.status !== "unbuildable") || !Array.isArray(value.points)) {
+        throw new TypeError(`${label} status 或 cityId 非法`);
+    }
+    if (value.status === "unbuildable") {
+        if (value.points.length !== 0)
+            throw new TypeError(`${label}.unbuildable.points 必须为空`);
+        return Object.freeze({ status: "unbuildable", cityId: city.id, points: Object.freeze([]) });
+    }
+    if (value.points.length < 3 || value.points.length > 128) {
+        throw new TypeError(`${label}.points 必须是 3..128 点数组`);
+    }
+    const points = value.points.map((raw, index) => {
+        if (!isRecord(raw) || Object.keys(raw).some((key) => key !== "x" && key !== "y")) {
+            throw new TypeError(`${label}[${index}] 字段非法`);
+        }
+        const point = Object.freeze({
+            x: finiteMetric(raw.x, `${label}[${index}].x`),
+            y: finiteMetric(raw.y, `${label}[${index}].y`),
+        });
+        if (Math.hypot(point.x - city.x, point.y - city.y) > city.parameters.radiusMeters + 0.000001) {
+            throw new RangeError(`${label}[${index}] 超出 city radiusMeters`);
+        }
+        return point;
+    });
+    for (let index = 0; index < points.length; index += 1) {
+        const current = points[index];
+        const next = points[(index + 1) % points.length];
+        if (current === undefined || next === undefined || (current.x === next.x && current.y === next.y)) {
+            throw new TypeError(`${label} 不能闭合重复或含零长度边`);
+        }
+    }
+    if (polygonSignedArea(points) <= 0 || !boundaryIsSimple(points)) {
+        throw new TypeError(`${label}.points 必须为 simple CCW 非零面积环`);
+    }
+    return Object.freeze({ status: "bounded", cityId: city.id, points: Object.freeze(points) });
+}
+function validateRoadParcelTerrain(value, label) {
+    if (!isRecord(value))
+        throw new TypeError(`${label} 必须是对象`);
+    const keys = ["width", "height", "widthMeters", "heightMeters", "originX", "originY", "elevationsMeters", "waterMask"];
+    if (Object.keys(value).some((key) => !keys.includes(key)) || keys.some((key) => !Object.hasOwn(value, key))) {
+        throw new TypeError(`${label} 字段非法`);
+    }
+    const widthRaw = value.width;
+    const heightRaw = value.height;
+    if (typeof widthRaw !== "number" || typeof heightRaw !== "number"
+        || !Number.isSafeInteger(widthRaw) || !Number.isSafeInteger(heightRaw)
+        || widthRaw < 2 || heightRaw < 2
+        || widthRaw > TERRAIN_ROAD_MAX_GRID_SIDE || heightRaw > TERRAIN_ROAD_MAX_GRID_SIDE
+        || widthRaw * heightRaw > TERRAIN_ROAD_MAX_GRID_CELLS
+        || !Array.isArray(value.elevationsMeters) || !Array.isArray(value.waterMask)
+        || value.elevationsMeters.length !== widthRaw * heightRaw || value.waterMask.length !== widthRaw * heightRaw) {
+        throw new TypeError(`${label} grid 非法`);
+    }
+    const width = widthRaw;
+    const height = heightRaw;
+    const widthMeters = finiteMetric(value.widthMeters, `${label}.widthMeters`);
+    const heightMeters = finiteMetric(value.heightMeters, `${label}.heightMeters`);
+    const originX = finiteMetric(value.originX, `${label}.originX`);
+    const originY = finiteMetric(value.originY, `${label}.originY`);
+    if (widthMeters <= 0 || heightMeters <= 0 || value.elevationsMeters.some((point) => typeof point !== "number" || !Number.isFinite(point))
+        || value.waterMask.some((water) => typeof water !== "boolean")) {
+        throw new TypeError(`${label} 采样值非法`);
+    }
+    return Object.freeze({
+        width,
+        height,
+        widthMeters,
+        heightMeters,
+        originX,
+        originY,
+        elevationsMeters: Object.freeze([...value.elevationsMeters]),
+        waterMask: Object.freeze([...value.waterMask]),
+    });
+}
+function containsParcel(parcel, x, y) {
+    if (parcel.polygon === undefined)
+        return contains(parcel.bounds, x, y);
+    let inside = false;
+    for (let index = 0, previous = parcel.polygon.length - 1; index < parcel.polygon.length; previous = index, index += 1) {
+        const from = parcel.polygon[index];
+        const to = parcel.polygon[previous];
+        if (from === undefined || to === undefined)
+            continue;
+        const cross = (to.x - from.x) * (y - from.y) - (to.y - from.y) * (x - from.x);
+        const onEdge = Math.abs(cross) <= 0.000001 && x >= Math.min(from.x, to.x) - 0.000001
+            && x <= Math.max(from.x, to.x) + 0.000001 && y >= Math.min(from.y, to.y) - 0.000001
+            && y <= Math.max(from.y, to.y) + 0.000001;
+        if (onEdge)
+            return true;
+        if ((from.y > y) !== (to.y > y) && x < (to.x - from.x) * (y - from.y) / (to.y - from.y) + from.x)
+            inside = !inside;
+    }
+    return inside;
+}
+function validateTerrainRoadNetwork(value, world) {
+    if (!isRecord(value) || Object.keys(value).some((key) => key !== "profile" && key !== "roads" && key !== "unreachable" && key !== "cityLayouts")) {
+        throw new TypeError("terrain road network 必须是严格对象");
+    }
+    if (value.profile !== "terrain-roads-v1" || !Array.isArray(value.roads)
+        || !Array.isArray(value.unreachable) || !Array.isArray(value.cityLayouts)) {
+        throw new TypeError("terrain road network profile 或集合非法");
+    }
+    if (world.cities.length > TERRAIN_ROAD_MAX_CITIES
+        || value.roads.length > TERRAIN_ROAD_MAX_ROADS
+        || value.unreachable.length > TERRAIN_ROAD_MAX_UNREACHABLE
+        || value.cityLayouts.length > TERRAIN_ROAD_MAX_CITIES) {
+        throw new RangeError("terrain road network 数量预算超限");
+    }
+    const knownCities = new Set(world.cities.map((city) => city.id));
+    const seenRoads = new Set();
+    const roads = value.roads.map((candidate, index) => {
+        if (!isRecord(candidate))
+            throw new TypeError(`terrain roads[${index}] 必须是对象`);
+        const keys = Object.keys(candidate);
+        const allowed = new Set(["id", "kind", "roadClass", "cityId", "fromCityId", "toCityId", "widthMeters", "points", "segments"]);
+        if (keys.some((key) => !allowed.has(key)) || !Object.hasOwn(candidate, "id")
+            || !Object.hasOwn(candidate, "kind") || !Object.hasOwn(candidate, "roadClass") || !Object.hasOwn(candidate, "widthMeters")
+            || !Object.hasOwn(candidate, "points") || !Object.hasOwn(candidate, "segments")) {
+            throw new TypeError(`terrain roads[${index}] 字段非法`);
+        }
+        const id = stableId(candidate.id, `terrain roads[${index}].id`);
+        if (seenRoads.has(id))
+            throw new TypeError(`terrain road id 重复：${id}`);
+        seenRoads.add(id);
+        if (candidate.kind !== "intercity" && candidate.kind !== "arterial" && candidate.kind !== "local") {
+            throw new TypeError(`terrain roads[${index}].kind 非法`);
+        }
+        if (candidate.roadClass !== "street" && candidate.roadClass !== "motorway") {
+            throw new TypeError(`terrain roads[${index}].roadClass 非法`);
+        }
+        const cityRef = (field) => {
+            const raw = candidate[field];
+            if (raw === undefined)
+                return undefined;
+            const cityId = stableId(raw, `terrain roads[${index}].${field}`);
+            if (!knownCities.has(cityId))
+                throw new TypeError(`terrain roads[${index}].${field} 未知城市`);
+            return cityId;
+        };
+        const cityId = cityRef("cityId");
+        const fromCityId = cityRef("fromCityId");
+        const toCityId = cityRef("toCityId");
+        if ((candidate.kind === "intercity") !== (fromCityId !== undefined && toCityId !== undefined)
+            || (candidate.kind !== "intercity" && cityId === undefined)) {
+            throw new TypeError(`terrain roads[${index}] 城市归属非法`);
+        }
+        const widthMeters = finiteMetric(candidate.widthMeters, `terrain roads[${index}].widthMeters`);
+        if (widthMeters <= 0 || widthMeters > 1_000)
+            throw new RangeError(`terrain roads[${index}].widthMeters 非法`);
+        const point = (raw, label) => {
+            if (!isRecord(raw) || Object.keys(raw).some((key) => key !== "x" && key !== "y" && key !== "z"))
+                throw new TypeError(`${label} 非法`);
+            return Object.freeze({ x: finiteMetric(raw.x, `${label}.x`), y: finiteMetric(raw.y, `${label}.y`), z: finiteMetric(raw.z, `${label}.z`) });
+        };
+        const points = candidate.points;
+        if (!Array.isArray(points) || points.length < 2 || points.length > TERRAIN_ROAD_MAX_POINTS_PER_PATH) {
+            throw new TypeError(`terrain roads[${index}].points 数量非法`);
+        }
+        const segments = candidate.segments;
+        if (!Array.isArray(segments) || segments.length === 0 || segments.length > TERRAIN_ROAD_MAX_SEGMENTS_PER_ROAD) {
+            throw new TypeError(`terrain roads[${index}].segments 数量非法`);
+        }
+        return Object.freeze({
+            id,
+            kind: candidate.kind,
+            roadClass: candidate.roadClass,
+            ...(cityId === undefined ? {} : { cityId }),
+            ...(fromCityId === undefined ? {} : { fromCityId }),
+            ...(toCityId === undefined ? {} : { toCityId }),
+            widthMeters,
+            points: Object.freeze(points.map((item, pointIndex) => point(item, `terrain roads[${index}].points[${pointIndex}]`))),
+            segments: Object.freeze(segments.map((segment, segmentIndex) => {
+                if (!isRecord(segment) || Object.keys(segment).some((key) => key !== "kind" && key !== "points" && key !== "lengthMeters")
+                    || (segment.kind !== "surface" && segment.kind !== "bridge" && segment.kind !== "tunnel")
+                    || !Array.isArray(segment.points)) {
+                    throw new TypeError(`terrain roads[${index}].segments[${segmentIndex}] 非法`);
+                }
+                const lengthMeters = finiteMetric(segment.lengthMeters, `terrain roads[${index}].segments[${segmentIndex}].lengthMeters`);
+                if (lengthMeters <= 0 || segment.points.length < 2 || segment.points.length > TERRAIN_ROAD_MAX_POINTS_PER_PATH) {
+                    throw new RangeError(`terrain roads[${index}].segments[${segmentIndex}] 非法`);
+                }
+                return Object.freeze({ kind: segment.kind, lengthMeters, points: Object.freeze(segment.points.map((item, pointIndex) => point(item, `terrain roads[${index}].segments[${segmentIndex}].points[${pointIndex}]`))) });
+            })),
+        });
+    });
+    const seenLayouts = new Set();
+    const cityLayouts = value.cityLayouts.map((item, index) => {
+        if (!isRecord(item) || Object.keys(item).some((key) => key !== "cityId" && key !== "roads" && key !== "boundary" && key !== "terrain") || !Array.isArray(item.roads)) {
+            throw new TypeError(`terrain cityLayouts[${index}] 非法`);
+        }
+        const cityId = stableId(item.cityId, `terrain cityLayouts[${index}].cityId`);
+        const city = world.cities.find((candidate) => candidate.id === cityId);
+        if (city === undefined || !seenLayouts.add(cityId))
+            throw new TypeError(`terrain cityLayouts[${index}] cityId 非法或重复`);
+        const boundary = validateTerrainCityBoundary(item.boundary, city, `terrain cityLayouts[${index}].boundary`);
+        const roadIds = item.roads.map((roadId) => stableId(roadId, `terrain cityLayouts[${index}].roads`));
+        if (new Set(roadIds).size !== roadIds.length || roadIds.some((roadId) => {
+            const road = roads.find((candidate) => candidate.id === roadId);
+            return road === undefined || road.cityId !== cityId;
+        }) || (boundary.status === "unbuildable" && roadIds.length !== 0)) {
+            throw new TypeError(`terrain cityLayouts[${index}] road 引用非法`);
+        }
+        return Object.freeze({
+            cityId,
+            roads: Object.freeze(roadIds),
+            boundary,
+            terrain: validateRoadParcelTerrain(item.terrain, `terrain cityLayouts[${index}].terrain`),
+        });
+    });
+    if (seenLayouts.size !== knownCities.size)
+        throw new TypeError("terrain cityLayouts 必须与 procedural cities 一一对应");
+    return Object.freeze({
+        profile: "terrain-roads-v1",
+        roads: Object.freeze(roads),
+        unreachable: Object.freeze(value.unreachable.map((item, index) => {
+            if (!isRecord(item))
+                throw new TypeError(`terrain unreachable[${index}] 必须是对象`);
+            return Object.freeze({ ...item });
+        })),
+        cityLayouts: Object.freeze(cityLayouts),
+    });
+}
+function cityBounds(city) {
+    return {
+        x: city.x - city.parameters.radiusMeters,
+        y: city.y - city.parameters.radiusMeters,
+        width: city.parameters.radiusMeters * 2,
+        height: city.parameters.radiusMeters * 2,
+    };
+}
+function targetKey(type, id) {
+    return `${type}\u0000${id}`;
+}
+function overrideKey(type, id, field) {
+    return `${targetKey(type, id)}\u0000${field}`;
+}
+function compareTarget(first, second) {
+    return first.targetType.localeCompare(second.targetType) || first.targetId.localeCompare(second.targetId);
+}
+function compareOverride(first, second) {
+    return compareTarget(first, second) || first.field.localeCompare(second.field);
+}
+function touchLru(map, key, value, maximum) {
+    map.delete(key);
+    map.set(key, value);
+    while (map.size > maximum) {
+        const oldest = map.keys().next().value;
+        if (oldest === undefined)
+            break;
+        map.delete(oldest);
+    }
+    return value;
+}
+function utf8Length(value) {
+    return new TextEncoder().encode(value).byteLength;
+}
+function decodeDeltaInput(input) {
+    if (typeof input === "string") {
+        if (utf8Length(input) > SPATIAL_DELTA_QUOTAS.maxUtf8Bytes) {
+            throw new SpatialRuntimeError("DELTA_QUOTA_EXCEEDED", "delta UTF-8 字节预算超限");
+        }
+        try {
+            return JSON.parse(input);
+        }
+        catch {
+            throw deltaError("delta JSON 非法");
+        }
+    }
+    if (input instanceof Uint8Array) {
+        if (input.byteLength > SPATIAL_DELTA_QUOTAS.maxUtf8Bytes) {
+            throw new SpatialRuntimeError("DELTA_QUOTA_EXCEEDED", "delta UTF-8 字节预算超限");
+        }
+        try {
+            return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(input));
+        }
+        catch {
+            throw deltaError("delta UTF-8/JSON 非法");
+        }
+    }
+    return input;
+}
+function viewportChunkAbortError() {
+    return new DOMException("空间视口 chunk 请求已取消", "AbortError");
+}
+function canonicalViewportNumber(value, label, positive = false) {
+    const number = finiteMetric(value, label);
+    if (positive && number <= 0)
+        throw new RangeError(`${label} 必须大于 0`);
+    // -0 不能成为另一个 cache identity。
+    return Object.is(number, -0) ? 0 : number;
+}
+function canonicalViewportRevision(value) {
+    if (typeof value === "string") {
+        if (value.length === 0 || value.length > 128)
+            throw new TypeError("spatialRevision 必须是非空且不超过 128 字符的字符串");
+        return `s:${value}`;
+    }
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new RangeError("spatialRevision 数字必须是非负安全整数");
+    return `n:${value}`;
+}
+function canonicalViewportChunkRequest(request) {
+    if (!isRecord(request))
+        throw new TypeError("viewport chunk request 必须是对象");
+    const baseDigest = sha256Digest(request.baseDigest, "viewport.baseDigest");
+    const revision = canonicalViewportRevision(request.spatialRevision);
+    if (!isRecord(request.centerMeters) || !isRecord(request.viewportSize) || !isRecord(request.chunk)) {
+        throw new TypeError("viewport chunk request 缺少 centerMeters、viewportSize 或 chunk");
+    }
+    canonicalViewportNumber(request.centerMeters.x, "viewport.centerMeters.x");
+    canonicalViewportNumber(request.centerMeters.y, "viewport.centerMeters.y");
+    canonicalViewportNumber(request.metersPerCssPixel, "viewport.metersPerCssPixel", true);
+    canonicalViewportNumber(request.viewportSize.width, "viewport.viewportSize.width", true);
+    canonicalViewportNumber(request.viewportSize.height, "viewport.viewportSize.height", true);
+    const level = request.chunk.level;
+    const x = request.chunk.x;
+    const y = request.chunk.y;
+    if (!Number.isSafeInteger(level) || level < 0 || level > 30
+        || !Number.isSafeInteger(x) || !Number.isSafeInteger(y) || x < 0 || y < 0
+        || x >= 2 ** level || y >= 2 ** level) {
+        throw new RangeError("viewport.chunk 必须是合法的有限平面 tile 坐标");
+    }
+    // 特意不把 centerMeters、metersPerCssPixel 或 viewportSize 放进 key：它们只决定
+    // 当前要哪些块和怎样投影，不能改变一个冻结世界坐标 chunk 的 authority。
+    return Object.freeze({ key: `${baseDigest}|${revision}|${level}|${x}|${y}`, baseDigest, revision });
+}
+/**
+ * scope-bound、可取消的 chunk cache。它不生成或持久化几何；调用者只能从同一个
+ * 已确认 base binding 请求 tile，取消或旧 revision 的响应绝不会成为新 revision cache。
+ */
+export function createSpatialViewportChunkCache(load) {
+    if (typeof load !== "function")
+        throw new TypeError("viewport chunk loader 必须是函数");
+    const cache = new Map();
+    const active = new Set();
+    const abortActive = () => {
+        for (const controller of active)
+            controller.abort();
+        active.clear();
+    };
+    return Object.freeze({
+        async read(request, signal) {
+            const canonical = canonicalViewportChunkRequest(request);
+            const existing = cache.get(canonical.key);
+            if (existing !== undefined)
+                return existing;
+            if (signal?.aborted === true)
+                throw viewportChunkAbortError();
+            const controller = new AbortController();
+            active.add(controller);
+            const abort = () => controller.abort();
+            signal?.addEventListener("abort", abort, { once: true });
+            try {
+                const result = await load(request, controller.signal);
+                // 外部 signal 只通过 abort listener 影响本 controller；避免把调用者的
+                // mutable AbortSignal 当作一次 await 之后仍被 TS 静态缩窄的值。
+                if (controller.signal.aborted)
+                    throw viewportChunkAbortError();
+                cache.set(canonical.key, result);
+                return result;
+            }
+            finally {
+                active.delete(controller);
+                signal?.removeEventListener("abort", abort);
+            }
+        },
+        clear() {
+            cache.clear();
+            // 清缓存是 scope retire，不允许一个旧 load 在 finally 之前重新写回。
+            abortActive();
+        },
+        retainRevision(baseDigestInput, spatialRevision) {
+            const baseDigest = sha256Digest(baseDigestInput, "viewport.baseDigest");
+            const revision = canonicalViewportRevision(spatialRevision);
+            for (const key of cache.keys()) {
+                if (!key.startsWith(`${baseDigest}|${revision}|`))
+                    cache.delete(key);
+            }
+            // revision 切换与完整 clear 有相同的 stale-response 语义；保留的已完成
+            // bytes 可读，但旧 scope 的 in-flight response 不能再成为 authority。
+            abortActive();
+        },
+        getCacheSize() {
+            return cache.size;
+        },
+    });
+}
+class SpatialRuntimeImpl {
+    world;
+    binding;
+    #readControlledPose;
+    #terrainRoadNetwork;
+    #terrainRoadGeneration;
+    #cityLayouts = new Map();
+    #activatedParcels = new Map();
+    #interiors = new Map();
+    #overrides = new Map();
+    #tombstones = new Map();
+    constructor(options) {
+        if (!isRecord(options))
+            throw new TypeError("SpatialRuntimeOptions 必须是对象");
+        const optionRecord = options;
+        const unknownOptions = Object.keys(optionRecord).filter((key) => !RUNTIME_OPTION_KEYS.includes(key));
+        if (unknownOptions.length > 0)
+            throw new TypeError(`SpatialRuntimeOptions 包含未知字段：${unknownOptions.join(", ")}`);
+        this.world = validateProceduralWorld(options.world);
+        this.binding = this.#validateBinding(options.binding);
+        this.#terrainRoadNetwork = options.roadNetwork === undefined
+            ? null
+            : validateTerrainRoadNetwork(options.roadNetwork, this.world);
+        this.#terrainRoadGeneration = options.roadGeneration === undefined
+            ? null
+            : validateRoadGeneration(options.roadGeneration);
+        if ((this.#terrainRoadNetwork === null) !== (this.#terrainRoadGeneration === null)) {
+            throw new TypeError("terrain-roads-v1 必须同时提供 roadNetwork 与 roadGeneration");
+        }
+        if (typeof options.readControlledPose !== "function")
+            throw new TypeError("readControlledPose 必须是函数");
+        this.#readControlledPose = options.readControlledPose;
+    }
+    readViewport(request) {
+        if (!isRecord(request))
+            throw new TypeError("viewport request 必须是对象");
+        const bounds = validateBounds(request.bounds, "viewport.bounds");
+        const metersPerCssPixel = finiteMetric(request.metersPerCssPixel, "viewport.metersPerCssPixel");
+        if (metersPerCssPixel <= 0)
+            throw new RangeError("viewport.metersPerCssPixel 必须大于 0");
+        const roads = [];
+        const parcels = [];
+        if (this.#terrainRoadNetwork !== null) {
+            for (const road of this.#terrainRoadNetwork.roads) {
+                if (!intersects(roadBounds(road), bounds))
+                    continue;
+                const composed = this.#compose("road", road);
+                if (composed !== null)
+                    roads.push(composed);
+            }
+            for (const city of this.world.cities) {
+                if (!intersects(cityBounds(city), bounds))
+                    continue;
+                for (const parcel of this.#layout(city).parcels) {
+                    if (!intersects(parcelViewportBounds(parcel), bounds))
+                        continue;
+                    const composed = this.#compose("parcel", parcel);
+                    if (composed !== null)
+                        parcels.push(composed);
+                }
+            }
+        }
+        else {
+            for (const city of this.world.cities) {
+                if (!intersects(cityBounds(city), bounds))
+                    continue;
+                const layout = this.#layout(city);
+                for (const road of layout.roads) {
+                    if (!intersects(roadBounds(road), bounds))
+                        continue;
+                    const composed = this.#compose("road", road);
+                    if (composed !== null)
+                        roads.push(composed);
+                }
+                for (const parcel of layout.parcels) {
+                    if (!intersects(parcelViewportBounds(parcel), bounds))
+                        continue;
+                    const composed = this.#compose("parcel", parcel);
+                    if (composed !== null)
+                        parcels.push(composed);
+                }
+            }
+        }
+        const buildings = [];
+        for (const activated of this.#activatedParcels.values()) {
+            for (const building of activated.buildings) {
+                if (!intersects(building.footprint, bounds))
+                    continue;
+                const composed = this.#compose("building", building);
+                if (composed !== null)
+                    buildings.push(composed);
+            }
+        }
+        roads.sort((first, second) => first.id.localeCompare(second.id));
+        parcels.sort((first, second) => first.id.localeCompare(second.id));
+        buildings.sort((first, second) => first.id.localeCompare(second.id));
+        return Object.freeze({
+            roads: Object.freeze(roads),
+            parcels: Object.freeze(parcels),
+            buildings: Object.freeze(buildings),
+        });
+    }
+    enterCurrentParcel() {
+        const pose = this.#pose();
+        for (const city of this.world.cities) {
+            if (!contains(cityBounds(city), pose.x, pose.y))
+                continue;
+            const layout = this.#layout(city);
+            for (const parcel of layout.parcels) {
+                if (!containsParcel(parcel, pose.x, pose.y))
+                    continue;
+                const runtimeParcel = this.#compose("parcel", parcel);
+                if (runtimeParcel === null || runtimeParcel.blocked === true || runtimeParcel.destroyed === true) {
+                    throw new SpatialRuntimeError("TARGET_UNAVAILABLE", `当前位置地块 ${parcel.id} 已不可用`);
+                }
+                let activated = this.#activatedParcels.get(parcel.id);
+                if (activated === undefined) {
+                    activated = Object.freeze({
+                        city,
+                        parcel,
+                        buildings: generateParcelBuildings(this.world.worldSeed, city, parcel, this.#templateOptions()),
+                    });
+                }
+                touchLru(this.#activatedParcels, parcel.id, activated, SPATIAL_RUNTIME_CACHE_LIMITS.activatedParcels);
+                const buildings = activated.buildings
+                    .map((building) => this.#compose("building", building))
+                    .filter((building) => building !== null)
+                    .sort((first, second) => first.id.localeCompare(second.id));
+                return Object.freeze({ pose, parcel: runtimeParcel, buildings: Object.freeze(buildings) });
+            }
+        }
+        throw new SpatialRuntimeError("POSE_OUTSIDE_PARCEL", "Host 受控角色当前位置不在任何地块内");
+    }
+    enterCurrentBuilding(buildingIdInput) {
+        const buildingId = stableId(buildingIdInput, "buildingId");
+        const pose = this.#pose();
+        let activated;
+        let building;
+        for (const candidate of this.#activatedParcels.values()) {
+            const found = candidate.buildings.find((item) => item.id === buildingId);
+            if (found !== undefined) {
+                activated = candidate;
+                building = found;
+                break;
+            }
+        }
+        if (activated === undefined || building === undefined) {
+            throw new SpatialRuntimeError("PARENT_PARCEL_NOT_ACTIVATED", `建筑 ${buildingId} 的父地块尚未由真实进入 gate 激活`);
+        }
+        if (!contains(activated.parcel.bounds, pose.x, pose.y)) {
+            throw new SpatialRuntimeError("POSE_OUTSIDE_BUILDING", `Host 受控角色不在建筑 ${buildingId} 的父地块内`);
+        }
+        const runtimeParcel = this.#compose("parcel", activated.parcel);
+        const runtimeBuilding = this.#compose("building", building);
+        if (runtimeParcel === null || runtimeParcel.blocked === true || runtimeParcel.destroyed === true
+            || runtimeBuilding === null || runtimeBuilding.blocked === true || runtimeBuilding.destroyed === true) {
+            throw new SpatialRuntimeError("TARGET_UNAVAILABLE", `建筑 ${buildingId} 或其父地块已不可用`);
+        }
+        const entranceDistance = Math.hypot(pose.x - building.entrance.x, pose.y - building.entrance.y);
+        if (!contains(building.footprint, pose.x, pose.y) && entranceDistance > BUILDING_ENTRANCE_TOLERANCE_METERS) {
+            throw new SpatialRuntimeError("POSE_OUTSIDE_BUILDING", `Host 受控角色不在建筑 ${buildingId} 内或入口容差内`);
+        }
+        let baseInterior = this.#interiors.get(building.id);
+        if (baseInterior === undefined)
+            baseInterior = generateBuildingInterior(this.world.worldSeed, building, this.#templateOptions());
+        touchLru(this.#interiors, building.id, baseInterior, SPATIAL_RUNTIME_CACHE_LIMITS.buildingInteriors);
+        const rooms = baseInterior.rooms
+            .map((room) => this.#compose("room", room))
+            .filter((room) => room !== null)
+            .sort((first, second) => first.id.localeCompare(second.id));
+        const doors = baseInterior.doors
+            .map((door) => this.#compose("door", door))
+            .filter((door) => door !== null)
+            .sort((first, second) => first.id.localeCompare(second.id));
+        const interior = Object.freeze({
+            buildingId: baseInterior.buildingId,
+            rooms: Object.freeze(rooms),
+            doors: Object.freeze(doors),
+        });
+        return Object.freeze({ pose, building: runtimeBuilding, interior });
+    }
+    clearCache() {
+        this.#cityLayouts.clear();
+        this.#activatedParcels.clear();
+        this.#interiors.clear();
+    }
+    getCacheStats() {
+        let materializedBuildings = 0;
+        for (const activated of this.#activatedParcels.values())
+            materializedBuildings += activated.buildings.length;
+        return Object.freeze({
+            cityLayouts: this.#cityLayouts.size,
+            activatedParcels: this.#activatedParcels.size,
+            materializedBuildings,
+            buildingInteriors: this.#interiors.size,
+        });
+    }
+    setOverride(targetTypeInput, targetIdInput, fieldInput, valueInput) {
+        const type = targetType(targetTypeInput, "targetType");
+        const id = stableId(targetIdInput, "targetId");
+        const field = overrideField(fieldInput, "field");
+        const value = overrideValue(field, valueInput, "value");
+        const resolved = this.#requireActiveTarget(type, id);
+        const base = resolved.base;
+        if (this.#tombstones.has(targetKey(type, id))) {
+            throw new SpatialRuntimeError("TARGET_UNAVAILABLE", `${type}:${id} 已 tombstone`);
+        }
+        const next = new Map(this.#overrides);
+        const key = overrideKey(type, id, field);
+        if ((field === "blocked" || field === "destroyed") && value === false) {
+            next.delete(key);
+        }
+        else if (field === "label" && "label" in base && base.label === value) {
+            next.delete(key);
+        }
+        else {
+            next.set(key, Object.freeze({ targetType: type, targetId: id, locator: resolved.locator, field, value }));
+        }
+        this.#assertCandidateQuota(next, this.#tombstones);
+        this.#overrides = next;
+    }
+    applyOverride(targetTypeInput, targetIdInput, patch) {
+        if (!isRecord(patch))
+            throw deltaError("override patch 必须是对象");
+        const keys = Object.keys(patch);
+        if (keys.length === 0)
+            throw deltaError("override patch 不能为空");
+        const unknown = keys.filter((key) => !OVERRIDE_FIELDS.includes(key));
+        if (unknown.length > 0)
+            throw deltaError(`override patch 包含未知字段：${unknown.join(", ")}；禁止 geometry`);
+        // SpatialCommand 是一个 typed mutation：任何字段无效都必须让整条命令无 effect，
+        // 否则重开后的 delta 会带上半条编辑而无法安全 undo/retry。
+        const beforeOverrides = this.#overrides;
+        const beforeTombstones = this.#tombstones;
+        try {
+            for (const field of OVERRIDE_FIELDS) {
+                if (!Object.hasOwn(patch, field))
+                    continue;
+                this.setOverride(targetTypeInput, targetIdInput, field, patch[field]);
+            }
+        }
+        catch (error) {
+            this.#overrides = beforeOverrides;
+            this.#tombstones = beforeTombstones;
+            throw error;
+        }
+    }
+    setTombstone(targetTypeInput, targetIdInput, tombstoned = true) {
+        const type = targetType(targetTypeInput, "targetType");
+        const id = stableId(targetIdInput, "targetId");
+        const resolved = this.#requireActiveTarget(type, id);
+        const nextTombstones = new Map(this.#tombstones);
+        const nextOverrides = new Map(this.#overrides);
+        const key = targetKey(type, id);
+        if (tombstoned) {
+            nextTombstones.set(key, Object.freeze({ targetType: type, targetId: id, locator: resolved.locator }));
+            for (const [candidateKey, operation] of nextOverrides) {
+                if (operation.targetType === type && operation.targetId === id)
+                    nextOverrides.delete(candidateKey);
+            }
+        }
+        else {
+            nextTombstones.delete(key);
+        }
+        this.#assertCandidateQuota(nextOverrides, nextTombstones);
+        this.#overrides = nextOverrides;
+        this.#tombstones = nextTombstones;
+    }
+    serializeDelta() {
+        return this.#serializeCandidate(this.#overrides, this.#tombstones);
+    }
+    serializeDeltaUtf8() {
+        return new TextEncoder().encode(JSON.stringify(this.serializeDelta()));
+    }
+    restoreDelta(input) {
+        const parsed = this.#parseDelta(input);
+        this.#overrides = parsed.overrides;
+        this.#tombstones = parsed.tombstones;
+    }
+    applyDelta(input) {
+        const parsed = this.#parseDelta(input);
+        const nextOverrides = new Map(this.#overrides);
+        const nextTombstones = new Map(this.#tombstones);
+        for (const operation of parsed.tombstones.values()) {
+            nextTombstones.set(targetKey(operation.targetType, operation.targetId), operation);
+            for (const [key, current] of nextOverrides) {
+                if (current.targetType === operation.targetType && current.targetId === operation.targetId)
+                    nextOverrides.delete(key);
+            }
+        }
+        for (const operation of parsed.overrides.values()) {
+            if (nextTombstones.has(targetKey(operation.targetType, operation.targetId)))
+                continue;
+            nextOverrides.set(overrideKey(operation.targetType, operation.targetId, operation.field), operation);
+        }
+        this.#assertCandidateQuota(nextOverrides, nextTombstones);
+        this.#overrides = nextOverrides;
+        this.#tombstones = nextTombstones;
+    }
+    #validateBinding(value) {
+        if (!isRecord(value))
+            throw new TypeError("binding 必须是对象");
+        const unknown = Object.keys(value).filter((key) => !BINDING_KEYS.includes(key));
+        const missing = BINDING_KEYS.filter((key) => !Object.hasOwn(value, key));
+        if (unknown.length > 0)
+            throw new TypeError(`binding 包含未知字段：${unknown.join(", ")}`);
+        if (missing.length > 0)
+            throw new TypeError(`binding 缺少字段：${missing.join(", ")}`);
+        return Object.freeze({
+            artifactDigest: sha256Digest(value.artifactDigest, "binding.artifactDigest"),
+            baseDigest: sha256Digest(value.baseDigest, "binding.baseDigest"),
+            worldlineId: nonEmptyIdentity(value.worldlineId, "binding.worldlineId", 128),
+            controlledActorId: nonEmptyIdentity(value.controlledActorId, "binding.controlledActorId", 128),
+        });
+    }
+    #pose() {
+        const raw = this.#readControlledPose();
+        if (!isRecord(raw)) {
+            throw new SpatialRuntimeError("HOST_POSE_UNAVAILABLE", "Host 未提供受控角色 pose");
+        }
+        let actorId;
+        try {
+            actorId = nonEmptyIdentity(raw.actorId, "Host pose.actorId", 128);
+        }
+        catch (error) {
+            throw new SpatialRuntimeError("HOST_POSE_INVALID", error instanceof Error ? error.message : "Host pose.actorId 非法");
+        }
+        if (actorId !== this.binding.controlledActorId) {
+            throw new SpatialRuntimeError("HOST_POSE_ACTOR_MISMATCH", "Host pose.actorId 与受控角色 binding 不匹配");
+        }
+        let x;
+        let y;
+        try {
+            x = finiteMetric(raw.x, "Host pose.x");
+            y = finiteMetric(raw.y, "Host pose.y");
+        }
+        catch (error) {
+            throw new SpatialRuntimeError("HOST_POSE_INVALID", error instanceof Error ? error.message : "Host pose 坐标非法");
+        }
+        return Object.freeze({ actorId, x, y, revision: validateRevision(raw.revision) });
+    }
+    #layout(city) {
+        const cached = this.#cityLayouts.get(city.id);
+        if (cached !== undefined)
+            return touchLru(this.#cityLayouts, city.id, cached, SPATIAL_RUNTIME_CACHE_LIMITS.cityLayouts);
+        if (this.#terrainRoadNetwork !== null) {
+            const terrain = this.#terrainRoadNetwork.cityLayouts.find((layout) => layout.cityId === city.id)?.terrain;
+            const boundary = this.#terrainRoadNetwork.cityLayouts.find((layout) => layout.cityId === city.id)?.boundary;
+            const generated = generateRoadParcels(this.world.worldSeed, city, {
+                // 必须带完整网络：motorway/intercity 不围 block，但仍是 forbidden corridor。
+                roads: this.#terrainRoadNetwork.roads,
+                ...(boundary === undefined ? {} : { boundary }),
+                ...(terrain === undefined ? {} : { terrain }),
+                // 由已保存 source 的 exact identity 决定，不以“当前默认版本”猜测。
+                algorithm: roadParcelAlgorithm(this.#terrainRoadGeneration.identity),
+                // 新道路的地块坡度门与发布 roadGeneration.maxGrade 相同；缺 terrain 时 helper 明确空结果。
+                settings: {
+                    maxSlope: this.#terrainRoadGeneration.maxGrade,
+                    ...(resolveRoadParcelTemplateSettings(this.world.templates) ?? {}),
+                },
+            });
+            return touchLru(this.#cityLayouts, city.id, Object.freeze({ roads: Object.freeze([]), parcels: generated.parcels }), SPATIAL_RUNTIME_CACHE_LIMITS.cityLayouts);
+        }
+        return touchLru(this.#cityLayouts, city.id, generateCityLayout(this.world.worldSeed, city, this.#templateOptions()), SPATIAL_RUNTIME_CACHE_LIMITS.cityLayouts);
+    }
+    #templateOptions() {
+        return this.world.templates === undefined ? {} : { templates: this.world.templates };
+    }
+    #compose(type, base) {
+        if (this.#tombstones.has(targetKey(type, base.id)))
+            return null;
+        const patch = {};
+        for (const field of OVERRIDE_FIELDS) {
+            const operation = this.#overrides.get(overrideKey(type, base.id, field));
+            if (operation !== undefined)
+                patch[field] = operation.value;
+        }
+        if (Object.keys(patch).length === 0)
+            return base;
+        return Object.freeze({ ...base, ...patch });
+    }
+    #requireActiveTarget(type, id) {
+        if (type === "city") {
+            const city = this.world.cities.find((candidate) => candidate.id === id);
+            if (city !== undefined)
+                return { base: city, locator: Object.freeze({ cityId: city.id }) };
+        }
+        if (type === "road" && this.#terrainRoadNetwork !== null) {
+            const road = this.#terrainRoadNetwork.roads.find((candidate) => candidate.id === id);
+            if (road !== undefined) {
+                return { base: road, locator: Object.freeze({ cityId: road.cityId ?? road.fromCityId ?? road.toCityId ?? "world" }) };
+            }
+        }
+        if (type === "parcel") {
+            for (const city of this.world.cities) {
+                const layout = this.#layout(city);
+                const base = layout.parcels.find((candidate) => candidate.id === id);
+                if (base !== undefined)
+                    return { base, locator: Object.freeze({ cityId: city.id }) };
+            }
+        }
+        if (type === "road" && this.#terrainRoadNetwork === null) {
+            for (const city of this.world.cities) {
+                const road = this.#layout(city).roads.find((candidate) => candidate.id === id);
+                if (road !== undefined)
+                    return { base: road, locator: Object.freeze({ cityId: city.id }) };
+            }
+        }
+        if (type === "building") {
+            for (const activated of this.#activatedParcels.values()) {
+                const base = activated.buildings.find((candidate) => candidate.id === id);
+                if (base !== undefined) {
+                    return {
+                        base,
+                        locator: Object.freeze({ cityId: activated.city.id, parcelId: activated.parcel.id }),
+                    };
+                }
+            }
+        }
+        if (type === "room" || type === "door") {
+            for (const [buildingId, interior] of this.#interiors) {
+                const base = type === "room"
+                    ? interior.rooms.find((candidate) => candidate.id === id)
+                    : interior.doors.find((candidate) => candidate.id === id);
+                if (base === undefined)
+                    continue;
+                for (const activated of this.#activatedParcels.values()) {
+                    if (!activated.buildings.some((candidate) => candidate.id === buildingId))
+                        continue;
+                    return {
+                        base,
+                        locator: Object.freeze({
+                            cityId: activated.city.id,
+                            parcelId: activated.parcel.id,
+                            buildingId,
+                        }),
+                    };
+                }
+            }
+        }
+        throw new SpatialRuntimeError("TARGET_NOT_FOUND", `delta target 未在允许层级物化：${type}:${id}`);
+    }
+    #resolveTargetByLocator(type, id, locator) {
+        const city = this.world.cities.find((candidate) => candidate.id === locator.cityId);
+        if (city === undefined && !(type === "road" && this.#terrainRoadNetwork !== null)) {
+            throw new SpatialRuntimeError("TARGET_NOT_FOUND", `delta locator city 不存在：${locator.cityId}`);
+        }
+        if (type === "city") {
+            if (city === undefined)
+                throw new SpatialRuntimeError("TARGET_NOT_FOUND", `delta locator city 不存在：${locator.cityId}`);
+            if (id !== city.id)
+                throw new SpatialRuntimeError("TARGET_NOT_FOUND", `delta target 与 city locator 不匹配：${id}`);
+            return city;
+        }
+        if (type === "road") {
+            if (this.#terrainRoadNetwork !== null) {
+                const road = this.#terrainRoadNetwork.roads.find((candidate) => candidate.id === id);
+                const expectedCityId = road?.cityId ?? road?.fromCityId ?? road?.toCityId ?? "world";
+                if (road === undefined || locator.cityId !== expectedCityId) {
+                    throw new SpatialRuntimeError("TARGET_NOT_FOUND", `delta road 不存在于 locator city：${id}`);
+                }
+                return road;
+            }
+            if (city === undefined)
+                throw new SpatialRuntimeError("TARGET_NOT_FOUND", `delta locator city 不存在：${locator.cityId}`);
+            const layout = generateCityLayout(this.world.worldSeed, city, this.#templateOptions());
+            const road = layout.roads.find((candidate) => candidate.id === id);
+            if (road === undefined)
+                throw new SpatialRuntimeError("TARGET_NOT_FOUND", `delta road 不存在于 locator city：${id}`);
+            return road;
+        }
+        if (city === undefined)
+            throw new SpatialRuntimeError("TARGET_NOT_FOUND", `delta locator city 不存在：${locator.cityId}`);
+        const layout = this.#terrainRoadNetwork === null
+            ? generateCityLayout(this.world.worldSeed, city, this.#templateOptions())
+            : this.#layout(city);
+        if (type === "parcel") {
+            const parcel = layout.parcels.find((candidate) => candidate.id === id);
+            if (parcel === undefined)
+                throw new SpatialRuntimeError("TARGET_NOT_FOUND", `delta parcel 不存在于 locator city：${id}`);
+            return parcel;
+        }
+        if (!("parcelId" in locator))
+            throw deltaError(`${type} locator 缺少 parcelId`);
+        const parcel = layout.parcels.find((candidate) => candidate.id === locator.parcelId);
+        if (parcel === undefined)
+            throw new SpatialRuntimeError("TARGET_NOT_FOUND", `delta locator parcel 不存在：${locator.parcelId}`);
+        const buildings = generateParcelBuildings(this.world.worldSeed, city, parcel, this.#templateOptions());
+        if (type === "building") {
+            const building = buildings.find((candidate) => candidate.id === id);
+            if (building === undefined)
+                throw new SpatialRuntimeError("TARGET_NOT_FOUND", `delta building 不存在于 locator parcel：${id}`);
+            return building;
+        }
+        if (!("buildingId" in locator))
+            throw deltaError(`${type} locator 缺少 buildingId`);
+        const building = buildings.find((candidate) => candidate.id === locator.buildingId);
+        if (building === undefined)
+            throw new SpatialRuntimeError("TARGET_NOT_FOUND", `delta locator building 不存在：${locator.buildingId}`);
+        const interior = generateBuildingInterior(this.world.worldSeed, building, this.#templateOptions());
+        const target = type === "room"
+            ? interior.rooms.find((candidate) => candidate.id === id)
+            : interior.doors.find((candidate) => candidate.id === id);
+        if (target === undefined)
+            throw new SpatialRuntimeError("TARGET_NOT_FOUND", `delta ${type} 不存在于 locator building：${id}`);
+        return target;
+    }
+    #parseDelta(input) {
+        const decoded = decodeDeltaInput(input);
+        assertRecord(decoded, "delta");
+        assertExactKeys(decoded, DELTA_KEYS, "delta");
+        if (decoded.version !== SPATIAL_DELTA_VERSION)
+            throw deltaError(`delta.version 必须为 ${SPATIAL_DELTA_VERSION}`);
+        assertRecord(decoded.binding, "delta.binding");
+        assertExactKeys(decoded.binding, DELTA_BINDING_KEYS, "delta.binding");
+        const binding = {
+            artifactDigest: sha256Digest(decoded.binding.artifactDigest, "delta.binding.artifactDigest"),
+            baseDigest: sha256Digest(decoded.binding.baseDigest, "delta.binding.baseDigest"),
+            worldlineId: nonEmptyIdentity(decoded.binding.worldlineId, "delta.binding.worldlineId", 128),
+        };
+        if (binding.artifactDigest !== this.binding.artifactDigest
+            || binding.baseDigest !== this.binding.baseDigest
+            || binding.worldlineId !== this.binding.worldlineId) {
+            throw new SpatialRuntimeError("DELTA_BINDING_MISMATCH", "delta binding 与当前 artifact/base/worldline 不匹配");
+        }
+        if (!Array.isArray(decoded.overrides) || !Array.isArray(decoded.tombstones)) {
+            throw deltaError("delta.overrides/tombstones 必须是数组");
+        }
+        if (decoded.overrides.length > SPATIAL_DELTA_QUOTAS.maxOverrides
+            || decoded.tombstones.length > SPATIAL_DELTA_QUOTAS.maxTombstones) {
+            throw new SpatialRuntimeError("DELTA_QUOTA_EXCEEDED", "delta operation 数量预算超限");
+        }
+        let encoded;
+        try {
+            encoded = JSON.stringify(decoded);
+        }
+        catch {
+            throw deltaError("delta 不是可序列化 JSON");
+        }
+        if (utf8Length(encoded) > SPATIAL_DELTA_QUOTAS.maxUtf8Bytes) {
+            throw new SpatialRuntimeError("DELTA_QUOTA_EXCEEDED", "delta UTF-8 字节预算超限");
+        }
+        const overrides = new Map();
+        const tombstones = new Map();
+        for (let index = 0; index < decoded.overrides.length; index += 1) {
+            const raw = decoded.overrides[index];
+            assertRecord(raw, `delta.overrides[${index}]`);
+            assertExactKeys(raw, OVERRIDE_KEYS, `delta.overrides[${index}]`);
+            const type = targetType(raw.targetType, `delta.overrides[${index}].targetType`);
+            const id = stableId(raw.targetId, `delta.overrides[${index}].targetId`);
+            const locator = validateLocator(raw.locator, type, `delta.overrides[${index}].locator`);
+            const field = overrideField(raw.field, `delta.overrides[${index}].field`);
+            const value = overrideValue(field, raw.value, `delta.overrides[${index}].value`);
+            this.#resolveTargetByLocator(type, id, locator);
+            const operation = Object.freeze({ targetType: type, targetId: id, locator, field, value });
+            overrides.set(overrideKey(type, id, field), operation);
+        }
+        for (let index = 0; index < decoded.tombstones.length; index += 1) {
+            const raw = decoded.tombstones[index];
+            assertRecord(raw, `delta.tombstones[${index}]`);
+            assertExactKeys(raw, TOMBSTONE_KEYS, `delta.tombstones[${index}]`);
+            const type = targetType(raw.targetType, `delta.tombstones[${index}].targetType`);
+            const id = stableId(raw.targetId, `delta.tombstones[${index}].targetId`);
+            const locator = validateLocator(raw.locator, type, `delta.tombstones[${index}].locator`);
+            this.#resolveTargetByLocator(type, id, locator);
+            const operation = Object.freeze({ targetType: type, targetId: id, locator });
+            tombstones.set(targetKey(type, id), operation);
+        }
+        for (const operation of tombstones.values()) {
+            for (const [key, override] of overrides) {
+                if (override.targetType === operation.targetType && override.targetId === operation.targetId)
+                    overrides.delete(key);
+            }
+        }
+        this.#assertCandidateQuota(overrides, tombstones);
+        return { overrides, tombstones };
+    }
+    #serializeCandidate(overrides, tombstones) {
+        const serializedOverrides = Array.from(overrides.values())
+            .sort(compareOverride)
+            .map((operation) => Object.freeze({ ...operation }));
+        const serializedTombstones = Array.from(tombstones.values())
+            .sort(compareTarget)
+            .map((operation) => Object.freeze({ ...operation }));
+        return Object.freeze({
+            version: SPATIAL_DELTA_VERSION,
+            binding: Object.freeze({
+                artifactDigest: this.binding.artifactDigest,
+                baseDigest: this.binding.baseDigest,
+                worldlineId: this.binding.worldlineId,
+            }),
+            overrides: Object.freeze(serializedOverrides),
+            tombstones: Object.freeze(serializedTombstones),
+        });
+    }
+    #assertCandidateQuota(overrides, tombstones) {
+        if (overrides.size > SPATIAL_DELTA_QUOTAS.maxOverrides || tombstones.size > SPATIAL_DELTA_QUOTAS.maxTombstones) {
+            throw new SpatialRuntimeError("DELTA_QUOTA_EXCEEDED", "delta operation 数量预算超限");
+        }
+        const bytes = utf8Length(JSON.stringify(this.#serializeCandidate(overrides, tombstones)));
+        if (bytes > SPATIAL_DELTA_QUOTAS.maxUtf8Bytes) {
+            throw new SpatialRuntimeError("DELTA_QUOTA_EXCEEDED", "delta UTF-8 字节预算超限");
+        }
+    }
+}
+export function createSpatialRuntime(options) {
+    return new SpatialRuntimeImpl(options);
+}