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

package/dist/protobuf-source-codec.js

@@ -0,0 +1,317 @@
+import { validatePlaneGeneration } from "./plane-generation.js";
+import { validateProceduralWorld } from "./procedural-city.js";
+import { validateRoadGeneration } from "./road-generation.js";
+import { validateSpatialTemplateConfiguration, validateSpatialTemplateLibrary, } from "./spatial-templates.js";
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder("utf-8", { fatal: true });
+const SPATIAL_KEY = /^[a-z][a-z0-9-]{0,63}$/;
+function fail(message) { throw new TypeError(message); }
+function record(value, label) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        fail(`${label} 必须是 object`);
+    return value;
+}
+function stringValue(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        fail(`${label} 必须是非空 string`);
+    return value;
+}
+function finiteCoordinate(value, label) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        fail(`${label} 必须是有限数`);
+    return value;
+}
+function controlledActorId(value, label) {
+    if (value === undefined || value === null)
+        return value;
+    if (typeof value !== "string" || !/^[^\0\r\n]{1,512}$/u.test(value))
+        fail(`${label} 必须是有效 entity id 或 null`);
+    return value;
+}
+function spatialKind(value, label) {
+    if (value === "location" || value === "portal" || value === "region")
+        return value;
+    return fail(`${label} 不支持的 spatial kind`);
+}
+function stableJson(value) { return textEncoder.encode(JSON.stringify(value)); }
+function compareCodepoint(left, right) {
+    const leftPoints = Array.from(left, (value) => value.codePointAt(0));
+    const rightPoints = Array.from(right, (value) => value.codePointAt(0));
+    const length = Math.min(leftPoints.length, rightPoints.length);
+    for (let index = 0; index < length; index += 1)
+        if (leftPoints[index] !== rightPoints[index])
+            return leftPoints[index] - rightPoints[index];
+    return leftPoints.length - rightPoints.length;
+}
+function stableStructuralJson(value) {
+    const normalize = (candidate) => {
+        if (Array.isArray(candidate))
+            return candidate.map(normalize);
+        if (candidate === null || typeof candidate !== "object")
+            return candidate;
+        return Object.fromEntries(Object.entries(candidate)
+            .filter(([, entry]) => entry !== undefined)
+            .sort(([left], [right]) => compareCodepoint(left, right))
+            .map(([key, entry]) => [key, normalize(entry)]));
+    };
+    return JSON.stringify(normalize(value));
+}
+function spatialObjectSignature(object) {
+    return stableStructuralJson({ id: object.id, key: object.key, kind: object.kind, label: object.label, x: object.x, y: object.y, references: object.references });
+}
+function bytesToBase64(bytes) {
+    let binary = "";
+    for (let offset = 0; offset < bytes.length; offset += 0x8000)
+        binary += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000));
+    return btoa(binary);
+}
+function base64ToBytes(encoded) {
+    const binary = atob(encoded);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1)
+        bytes[index] = binary.charCodeAt(index);
+    return bytes;
+}
+function readVarint(bytes, start) {
+    let value = 0;
+    let shift = 0;
+    for (let offset = start; offset < bytes.length && offset < start + 10; offset += 1) {
+        const byte = bytes[offset];
+        value += (byte & 0x7f) * 2 ** shift;
+        if ((byte & 0x80) === 0)
+            return { value, next: offset + 1 };
+        shift += 7;
+    }
+    return fail("Scenario protobuf varint 无效");
+}
+function varint(value) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        fail("protobuf varint 必须为非负安全整数");
+    const out = [];
+    do {
+        const byte = value % 128;
+        value = Math.floor(value / 128);
+        out.push(value === 0 ? byte : byte | 0x80);
+    } while (value !== 0);
+    return new Uint8Array(out);
+}
+function concat(parts) {
+    const out = new Uint8Array(parts.reduce((size, part) => size + part.length, 0));
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+function fields(bytes) {
+    const out = new Map();
+    let offset = 0;
+    while (offset < bytes.length) {
+        const tag = readVarint(bytes, offset);
+        offset = tag.next;
+        const field = Math.floor(tag.value / 8);
+        const wire = tag.value % 8;
+        if (field <= 0)
+            fail("Scenario protobuf field 无效");
+        if (wire === 0) {
+            offset = readVarint(bytes, offset).next;
+            continue;
+        }
+        if (wire !== 2)
+            fail("Scenario protobuf 包含不支持字段");
+        const length = readVarint(bytes, offset);
+        offset = length.next;
+        const end = offset + length.value;
+        if (end > bytes.length)
+            fail("Scenario protobuf length 被截断");
+        const values = out.get(field) ?? [];
+        values.push(bytes.slice(offset, end));
+        out.set(field, values);
+        offset = end;
+    }
+    return out;
+}
+function first(map, field) { return map.get(field)?.[0] ?? new Uint8Array(); }
+function protobufSegments(bytes) {
+    const result = [];
+    let offset = 0;
+    while (offset < bytes.length) {
+        const start = offset;
+        const tag = readVarint(bytes, offset);
+        offset = tag.next;
+        const field = Math.floor(tag.value / 8);
+        const wire = tag.value % 8;
+        if (field <= 0 || (wire !== 0 && wire !== 2))
+            fail("Scenario protobuf 包含不支持字段");
+        if (wire === 0) {
+            const value = readVarint(bytes, offset);
+            offset = value.next;
+            result.push({ field, wire, encoded: bytes.slice(start, offset), varintValue: value.value });
+            continue;
+        }
+        const length = readVarint(bytes, offset);
+        offset = length.next;
+        const end = offset + length.value;
+        if (end > bytes.length)
+            fail("Scenario protobuf length 被截断");
+        result.push({ field, wire, encoded: bytes.slice(start, end), payload: bytes.slice(offset, end) });
+        offset = end;
+    }
+    return result;
+}
+function encodedField(field, value) { return concat([varint(field * 8 + 2), varint(value.length), value]); }
+function replaceBytesField(message, fieldNumber, payload) {
+    const replacement = encodedField(fieldNumber, payload);
+    let replaced = false;
+    const output = [];
+    for (const segment of protobufSegments(message)) {
+        if (segment.field !== fieldNumber)
+            output.push(segment.encoded);
+        else if (!replaced) {
+            output.push(replacement);
+            replaced = true;
+        }
+    }
+    if (!replaced)
+        output.push(replacement);
+    return concat(output);
+}
+export function decodeSpatialWorldProtobuf(bytes) {
+    if (bytes === undefined)
+        return undefined;
+    const top = fields(bytes);
+    const topologyFields = fields(first(top, 3));
+    const topologySettings = first(topologyFields, 2);
+    const topology = topologySettings.length === 0 ? { kind: "freeform", width: 100, height: 100 } : record(JSON.parse(textDecoder.decode(topologySettings)), "spatial topology settings");
+    const kind = topology.kind === "grid" ? "grid" : "freeform";
+    const width = finiteCoordinate(topology.width, "spatial topology.width");
+    const height = finiteCoordinate(topology.height, "spatial topology.height");
+    if (width <= 0 || height <= 0)
+        fail("spatial topology 边界必须为正数");
+    const cellSize = topology.cellSize === undefined ? undefined : finiteCoordinate(topology.cellSize, "spatial topology.cellSize");
+    let generation;
+    try {
+        generation = topology.generation === undefined ? undefined : validatePlaneGeneration(topology.generation);
+    }
+    catch (error) {
+        return fail(error instanceof Error ? error.message : "PlaneGenerationV1 无效");
+    }
+    if (generation !== undefined && (generation.widthMeters !== width || generation.heightMeters !== height))
+        fail("spatial topology.generation 范围必须与 topology 一致");
+    let roadGeneration;
+    try {
+        roadGeneration = topology.roadGeneration === undefined ? undefined : validateRoadGeneration(topology.roadGeneration);
+    }
+    catch (error) {
+        return fail(error instanceof Error ? error.message : "RoadGenerationV1 无效");
+    }
+    let templateLibrary;
+    try {
+        templateLibrary = topology.templateLibrary === undefined ? undefined : validateSpatialTemplateLibrary(topology.templateLibrary);
+    }
+    catch (error) {
+        return fail(error instanceof Error ? error.message : "SpatialTemplateLibraryV1 无效");
+    }
+    let templates;
+    try {
+        templates = topology.templates === undefined ? undefined : validateSpatialTemplateConfiguration(topology.templates);
+    }
+    catch (error) {
+        return fail(error instanceof Error ? error.message : "SpatialTemplateConfigurationV1 无效");
+    }
+    let procedural;
+    try {
+        procedural = topology.procedural === undefined ? undefined : validateProceduralWorld(topology.procedural, { widthMeters: width, heightMeters: height });
+    }
+    catch (error) {
+        return fail(error instanceof Error ? error.message : "ProceduralWorldV1 无效");
+    }
+    if (procedural !== undefined && generation === undefined)
+        fail("spatial topology.procedural 必须绑定 generation");
+    if (procedural !== undefined && generation !== undefined && procedural.worldSeed !== generation.seed)
+        fail("procedural.worldSeed 必须与 generation.seed 一致");
+    const actorId = controlledActorId(topology.controlledActorId, "spatial topology.controlledActorId");
+    const objects = [];
+    for (const field of [7, 8, 9, 10, 11])
+        for (const value of top.get(field) ?? []) {
+            const object = fields(value);
+            const id = stringValue(textDecoder.decode(first(object, 1)), "spatial object id");
+            const label = stringValue(textDecoder.decode(first(object, 3)), "spatial object label");
+            const settingsBytes = first(object, 4);
+            const settings = settingsBytes.length === 0 ? {} : record(JSON.parse(textDecoder.decode(settingsBytes)), "spatial author settings");
+            const inferred = field === 7 ? "location" : field === 8 ? "portal" : "region";
+            const objectKind = settings.kind === undefined ? inferred : spatialKind(settings.kind, "spatial object kind");
+            const key = typeof settings.key === "string" ? settings.key : id.split(":").at(-1) ?? "";
+            if (!SPATIAL_KEY.test(key))
+                fail("spatial object key 无效");
+            const x = settings.x === undefined ? 0 : finiteCoordinate(settings.x, "spatial object x");
+            const y = settings.y === undefined ? 0 : finiteCoordinate(settings.y, "spatial object y");
+            if (x < 0 || x > width || y < 0 || y > height)
+                fail("spatial object 坐标超出 topology");
+            const references = Array.isArray(settings.references) ? settings.references.map((entry) => {
+                const ref = record(entry, "spatial reference");
+                const candidate = ref.ownerKind;
+                if (candidate !== "ladybug" && candidate !== "trigger" && candidate !== "scenario")
+                    fail("spatial reference ownerKind 无效");
+                return { ownerId: stringValue(ref.ownerId, "spatial reference ownerId"), ownerKind: candidate, fieldPath: stringValue(ref.fieldPath, "spatial reference fieldPath") };
+            }) : [];
+            const decoded = { id, key, kind: objectKind, label, x, y, references, _wireField: field, _wireBase64: bytesToBase64(value), _authorSettings: settings };
+            decoded._wireSignature = spatialObjectSignature(decoded);
+            objects.push(decoded);
+        }
+    const topologyBytes = first(top, 3);
+    const topologyWireKind = protobufSegments(topologyBytes).find((segment) => segment.field === 1 && segment.wire === 0)?.varintValue;
+    const { worldId: storedWorldId, spatialRevision: storedSpatialRevision, ...topologySettingsWithoutWorldId } = topology;
+    void storedWorldId;
+    const spatialRevision = storedSpatialRevision ?? 0;
+    if (!Number.isSafeInteger(spatialRevision) || spatialRevision < 0)
+        fail("spatialRevision 必须是非负安全整数");
+    const normalizedTopology = { ...topologySettingsWithoutWorldId, kind, width, height, ...(cellSize === undefined ? {} : { cellSize }), ...(generation === undefined ? {} : { generation }), ...(roadGeneration === undefined ? {} : { roadGeneration }), ...(templateLibrary === undefined ? {} : { templateLibrary }), ...(templates === undefined ? {} : { templates }), ...(procedural === undefined ? {} : { procedural }), ...(actorId === undefined ? {} : { controlledActorId: actorId }) };
+    return { schemaVersion: 1, worldId: typeof topology.worldId === "string" && SPATIAL_KEY.test(topology.worldId) ? topology.worldId : "world", spatialRevision: spatialRevision, topology: normalizedTopology, objects,
+        _wireBase64: bytesToBase64(bytes), _topologyWireBase64: bytesToBase64(topologyBytes), ...(topologyWireKind === undefined ? {} : { _topologyWireKind: topologyWireKind }) };
+}
+export function encodeSpatialWorldProtobuf(world) {
+    if (world === undefined)
+        return undefined;
+    const topologySettings = stableJson({ ...world.topology, worldId: world.worldId, spatialRevision: world.spatialRevision });
+    const topologyPayload = world._topologyWireBase64 === undefined
+        ? concat([varint(8), varint(2), encodedField(2, topologySettings)])
+        : replaceBytesField(base64ToBytes(world._topologyWireBase64), 2, topologySettings);
+    const encodeObject = (object) => {
+        const settings = stableJson({ ...(object._authorSettings ?? {}), key: object.key, kind: object.kind, x: object.x, y: object.y, references: object.references });
+        const raw = object._wireBase64 === undefined ? new Uint8Array() : base64ToBytes(object._wireBase64);
+        const payload = raw.length === 0
+            ? concat([encodedField(1, textEncoder.encode(object.id)), encodedField(3, textEncoder.encode(object.label)), encodedField(4, settings)])
+            : replaceBytesField(replaceBytesField(replaceBytesField(raw, 1, textEncoder.encode(object.id)), 3, textEncoder.encode(object.label)), 4, settings);
+        return encodedField(object._wireField ?? 7, payload);
+    };
+    if (world._wireBase64 === undefined)
+        return concat([varint(8), varint(1), encodedField(3, topologyPayload), ...world.objects.map(encodeObject)]);
+    const remaining = new Set(world.objects);
+    const output = [];
+    let topologyWritten = false;
+    for (const segment of protobufSegments(base64ToBytes(world._wireBase64))) {
+        if (segment.field === 3) {
+            if (!topologyWritten) {
+                output.push(encodedField(3, topologyPayload));
+                topologyWritten = true;
+            }
+            continue;
+        }
+        if (segment.field >= 7 && segment.field <= 11 && segment.payload !== undefined) {
+            const rawBase64 = bytesToBase64(segment.payload);
+            const object = world.objects.find((candidate) => candidate._wireBase64 === rawBase64);
+            if (object !== undefined) {
+                output.push(object._wireSignature === spatialObjectSignature(object) ? segment.encoded : encodeObject(object));
+                remaining.delete(object);
+            }
+            continue;
+        }
+        output.push(segment.encoded);
+    }
+    if (!topologyWritten)
+        output.push(encodedField(3, topologyPayload));
+    output.push(...[...remaining].map(encodeObject));
+    return concat(output);
+}

package/dist/road-generation.d.ts

@@ -0,0 +1,52 @@
+export declare const ROAD_GENERATION_PROFILE: "terrain-roads-v1";
+/**
+ * 绑定路径搜索、桥隧门户、地形采样和地块图语义的 canonical 规则字节。
+ * 任一语义变更都必须更新这份 JSON 并发布新 identity。
+ */
+export declare const LEGACY_V6_ROAD_GENERATION_RULES_CANONICAL: "{\"algorithm\":\"direction-state-a-star-v2;32-coprime-neighbors;stable-heap-tie-order;route-edge-cache-v1\",\"anchor\":\"city-guide-anchor-once;whole-candidate-single-connectors;no-grid-exact-grid-pair-foldback-v3\",\"bridge\":\"complete-dry-portal-water-span-v1;linear-deck-3d-length-at-most-maxBridgeLengthMeters;all-water-interior;no-shortcut-or-split-v2\",\"cityAccess\":\"surface-street-node-short-connect-v1;radius-over-block-times-1.5-ceil-4to12;candidate-distance-0.75to3-block;target-1.7-block;stable-city-seed-node-pair-sort;surface-only-existing-nodes;actual-sampler-direct-or-bounded-astar;complete-portal-no-acute-boundary-containment;access-unreachable-domain-v1\",\"cityBoundary\":\"radial-budget-v2;world-seed-city-seed-city-id-fnv1a-xor;24to128-rays;step-at-most10m;phase-smooth-three-harmonics-radius-0.85to1.15;actual-sampler-surface-or-complete-classify-edge-portal;surface-abs-grade-integral-ds-times-1-plus-0.6-normalized-grade-over-one-minus-normalized;normalized-grade-at-least-0.995-reject;bounded-ccw-nonclosed-3to128|unbuildable-empty;city-road-continuous-points-inside-boundary;intercity-unclipped\",\"cityField\":\"seeded-radial-terrain-contour-guide-v1\",\"direction\":\"heading-dot-at-least-zero;interior-angle-at-least90deg;all-assembled-route-final-gate-v2\",\"elevation\":\"relative-height-times-elevationScaleMeters-v1\",\"limits\":\"maxGrade-roadWidthMeters-maxBridgeLengthMeters-maxTunnelLengthMeters-v1\",\"parcelFace\":\"road-parcels-v4-boundary-highway;cityId-exact-arterial-local-street-surface-only;quantized-strict-xy-intersection-split;dcel-left-turn;positive-inside-concave-boundary;oriented-length-weighted-second-moment-principal-axis;canonical-longest-edge-isotropic-fallback;projection-midline-clip;area22500-recursion-depth8;inset-half-widest-road-plus-setback;triangulated-max-square-safe-bounds-v4\",\"parcelFrontage\":\"face-plus-uncovered-frontage-v1;cityId-exact-arterial-local-street-surface-elementary-run;polyline-slice-16to42m;two-sided-offset;depth-clamp-blockSize-times-0.18-10to20;source-and-road-corridor-clear;face-first-frontage-positive-area-nonoverlap-stable-id-greedy-v1\",\"parcelGraph\":\"road-parcels-v4-boundary-highway\",\"parcelIdentity\":\"boundary-token-sorted-hash-worldSeed-citySeed-cityId;oriented-split-normal-token;frontage-side-and-ordinal;weighted-land-use;id-sort-v3\",\"parcelTerrain\":\"polygon-touching-cells-dry-finite;adjacent-touching-cell-slope-at-most-settings-maxSlope;grid-at-most257-v1\",\"portalLookahead\":\"complete-portal-before-partial-surface-v1;exact-dry-grid-portal-preserved-v1;off-grid-origin-requires-validated-surface-connector-v1;connector-budget-cost-required-v1\",\"repair\":\"same-core-segment-splice;10m-grid;at-most8-attempts;min-margin200m-v1\",\"roadClass\":\"required-kind-intercity-arterial-local;required-class-street-motorway;intercity-motorway-else-street;all-intercity-motorway-and-city-nonbuildable-roads-forbidden-corridor;centerline-no-intersection-or-containment;clearance-half-width-plus-setback-v1\",\"shortcut\":\"surface-run-control-edge-boundaries;candidates-i-to-j-j-at-most-i-plus24-or-last;actual-sampler-water-grade-step-at-most10m;reverse-sparse-dag-heading-compatible-dot-epsilon1e-12;no-accumulated-cost;farthest-reachable-stable-descending;retain-original-if-no-complete-chain;whole-road-stable-branch-unreachable-if-final-acute;bridge-tunnel-excluded-v3\",\"terrain\":\"canonical-plane-hydrology-fixed-sampling;global-long-axis257;city-long-axis65to257;actual-finite-sampler-step10m;no-sub10m-obstacle-guarantee-v1\",\"tunnel\":\"covered-dry-portal-bore;actual-cover-at-least1m;3d-length-at-most-maxTunnelLengthMeters;no-shortcut-or-split;no-water-interior;roadWidth-surface-abutment-v2\",\"version\":6}";
+/**
+ * 该字符串绑定 profile、算法版本与上方 canonical 规则字节的 SHA-256。
+ * 道路语义变化时必须发布新 identity，禁止让旧世界静默重算为不同结果。
+ */
+export declare const LEGACY_V6_IDENTITY: "chat.worldengine.terrain-roads/v1;rules-sha256=9dc32e6e3f5e63fbf378d6b83dfa67c2e9d62dabfebe5b432956f7ff0fdb8443";
+export declare const STRUCTURED_V8_ROAD_GENERATION_RULES_CANONICAL: "{\"version\":8,\"algorithm\":\"direction-state-a-star-v2;32-coprime-neighbors;stable-heap-tie-order;route-edge-cache-v1\",\"cityField\":\"structured-two-family-seeded-skeleton-v8;candidate-only-actual-terrain-router-required\",\"cityCandidateBudget\":\"boundary-polygon-shoelace-abs-area-m2;ceil-sqrt-area-over-block-times-0.42-per-family;clamp6to15;not-nominal-radius-area;not-feasible-terrain-mask\",\"cityCandidateFamilies\":\"six-arterial-rays-from-center-four-collinear-points;arterial-base-seeded-angle-plus-sixth-turn-plus-seeded-jitter;two-transverse-families-base-and-base-plus-pi-over-two-plus-seeded-0.18rad;collector-and-local;four-point-parabolic-sweeps;seeded-bend-block-times-0.32;actual-terrain-and-boundary-gates\",\"cityBoundary\":\"radial-budget-v2;world-seed-city-seed-city-id-fnv1a-xor;24to128-rays;step-at-most10m;phase-smooth-three-harmonics-radius-0.85to1.15;actual-sampler-surface-or-complete-classify-edge-portal;surface-abs-grade-integral-ds-times-1-plus-0.6-normalized-grade-over-one-minus-normalized;normalized-grade-at-least-0.995-reject;bounded-ccw-nonclosed-3to128|unbuildable-empty;city-road-continuous-points-inside-boundary;intercity-unclipped\",\"cityStructuredClip\":\"v8-nonarterial-all-exact-boundary-inside-runs;candidate-segment-boundary-intersections;boundary-inclusive;rooted-run-nearest-original-sweep-midpoint-else-inside-run-nearest-midpoint;arterial-uses-legacy-origin-first-exit-clip;final-route-sample-boundary-verify-at-most10m\",\"cityStructuredRoot\":\"v8-transverse-same-city-surface-strict-internal-xy-intersection;parallel-collinear-endpoint-near-end-reject-epsilon1e-9;nearest-original-sweep-midpoint-then-stable-road-segment-point-pair-tie-order;root-z-actual-terrain-sample;both-old-surface-halves-revalidate-before-noding\",\"cityRootArms\":\"root-left-right-independent-anchor-direct-or-bounded-astar-finish-and-boundary-check;both-concatenate|one-commit-valid-arm-and-record-other-unreachable|none-reject;assembled-root-route-no-acute-final-gate;preserve-root-xy\",\"citySurfaceNoding\":\"v8-same-city-nonintercity-surface-only;strict-internal-xy-crossing-with-nonfinite-reject-and-dimensionless-interior-epsilon1e-9|positive-collinear-xy-overlap-line-distance-at-most1e-7;canonical-overlap-endpoints-xy-round-1e-7m-and-z-actual-terrain-sample;all-four-half-edges-or-local-endpoint-replacement-surface-revalidate;stable-road-segment-original-edge-index-descending-and-t-descending-insert-order;not-cross-city-bridge-tunnel-or-general-grade-separation\",\"cityExactSurfaceReuse\":\"after-same-city-surface-noding-and-common-overlap-endpoint-rewrite;same-city-nonintercity-contiguous-all-surface-normalized-run-only-without-crossing-bridge-or-tunnel;undirected-exact-xyz-bit-elementary-key;arterial-then-local-then-lexical-road-id-owner;partial-overlap-reuse-removes-nonowner-exact-pieces-retains-continuous-chains;single-retained-chain-keeps-parent-id|multiple-retained-chains-child-id-parent-plus-retained-child-first-last-xy-IEEE-bits-and-reuse-purpose-no-ordinal;refresh-sorted-layout-ids;no-reuse-status-output;not-near-or-unvalidated-overlap-reuse\",\"cityAccess\":\"legacy-v6-only:surface-street-node-short-connect-v1;radius-over-block-times-1.5-ceil-4to12;candidate-distance-0.75to3-block;target-1.7-block;stable-city-seed-node-pair-sort;surface-only-existing-nodes;actual-sampler-direct-or-bounded-astar;complete-portal-no-acute-boundary-containment;access-unreachable-domain-v1\",\"parcelFace\":\"structured-v8-convex-closed-face-with-every-simplified-edge-matched-to-real-ordinary-street-elementary-frontage-only;per-edge-inward-half-plane-offset-before-split;clearance-max-matching-edge-half-width-plus-nonnegative-setback;mixed-width-collinear-match-uses-max-conservative-clearance;nonconvex-unmatched-or-invalid-offset-closed-face-reject-no-topology-guess\",\"parcelSplit\":\"structured-v8-projection-midline-clip-area-settings-maxFaceAreaMeters-default22500-recursion-depth8;each-child-needs-longest-continuous-collinear-overlap-with-inset-real-street-frontage-at-least-max-10-min-20-widest-road;not-fragment-sum;on-failure-retain-parent-unsplit;cut-edge-is-not-frontage\",\"parcelFrontage\":\"face-plus-uncovered-frontage-v1;open-area-only-real-surface-ordinary-street-segment-run;polyline-slice-min16-max42-except-unsplittable-first-edge-may-exceed42;two-sided-offset;inner-road-corridor-clearance-plus-0.01;source-run-clearance-recheck-at-least-clearance-minus0.2;depth-clamp-blockSize-times-0.18-10to20;source-and-road-corridor-clear;face-first-frontage-positive-area-nonoverlap-stable-id-greedy-v1;no-entrance-or-navigation-reachability-claim\",\"legacyParcel\":\"legacy-v6-undefined-or-explicit-legacy-uses-prior-split-and-centroid-inset-path;v8-only-convex-offset-and-child-frontage-rule;shared-invalid-algorithm-fail-closed\",\"parcelGraph\":\"road-parcels-v4-boundary-highway\",\"parcelIdentity\":\"boundary-token-sorted-hash-worldSeed-citySeed-cityId;oriented-split-normal-token;frontage-side-and-ordinal;weighted-land-use;id-sort-v3\",\"parcelTerrain\":\"polygon-touching-cells-dry-finite;adjacent-touching-cell-slope-at-most-settings-maxSlope;grid-at-most257-v1\",\"roadClass\":\"required-kind-intercity-arterial-local;required-class-street-motorway;intercity-motorway-else-street;all-intercity-motorway-and-city-nonbuildable-roads-forbidden-corridor;centerline-no-intersection-or-containment;clearance-half-width-plus-setback-v1\",\"direction\":\"heading-dot-at-least-zero;interior-angle-at-least90deg;all-assembled-route-final-gate-v2\",\"limits\":\"maxGrade-roadWidthMeters-maxBridgeLengthMeters-maxTunnelLengthMeters-v1\",\"elevation\":\"relative-height-times-elevationScaleMeters-v1\",\"terrain\":\"canonical-plane-hydrology-fixed-sampling;global-long-axis257;city-long-axis65to257;actual-finite-sampler-step10m;no-sub10m-obstacle-guarantee-v1\",\"portalLookahead\":\"complete-portal-before-partial-surface-v1;exact-dry-grid-portal-preserved-v1;off-grid-origin-requires-validated-surface-connector-v1;connector-budget-cost-required-v1\",\"bridge\":\"complete-dry-portal-water-span-v1;linear-deck-3d-length-at-most-maxBridgeLengthMeters;all-water-interior;no-shortcut-or-split-v2\",\"tunnel\":\"covered-dry-portal-bore;actual-cover-at-least1m;3d-length-at-most-maxTunnelLengthMeters;no-shortcut-or-split;no-water-interior;roadWidth-surface-abutment-v2\",\"shortcut\":\"surface-run-control-edge-boundaries;candidates-i-to-j-j-at-most-i-plus24-or-last;actual-sampler-water-grade-step-at-most10m;reverse-sparse-dag-heading-compatible-dot-epsilon1e-12;no-accumulated-cost;farthest-reachable-stable-descending;retain-original-if-no-complete-chain;whole-road-stable-branch-unreachable-if-final-acute;bridge-tunnel-excluded-v3\",\"repair\":\"same-core-segment-splice;10m-grid;at-most8-attempts;min-margin200m-v1\"}";
+export declare const STRUCTURED_V8_IDENTITY: "chat.worldengine.terrain-roads/v1;rules-sha256=03ab0544e8fdfc741045dccac18a946eb95b76bc10e9880012cba50060b29b4f";
+export declare const FRONTAGE_BALANCED_V9_ROAD_GENERATION_RULES_CANONICAL: "{\"version\":9,\"algorithm\":\"direction-state-a-star-v2;32-coprime-neighbors;stable-heap-tie-order;route-edge-cache-v1\",\"cityField\":\"structured-two-family-seeded-skeleton-v8;candidate-only-actual-terrain-router-required\",\"cityCandidateBudget\":\"boundary-polygon-shoelace-abs-area-m2;ceil-sqrt-area-over-block-times-0.42-per-family;clamp6to15;not-nominal-radius-area;not-feasible-terrain-mask\",\"cityCandidateFamilies\":\"six-arterial-rays-from-center-four-collinear-points;arterial-base-seeded-angle-plus-sixth-turn-plus-seeded-jitter;two-transverse-families-base-and-base-plus-pi-over-two-plus-seeded-0.18rad;collector-and-local;four-point-parabolic-sweeps;seeded-bend-block-times-0.32;actual-terrain-and-boundary-gates\",\"cityBoundary\":\"radial-budget-v2;world-seed-city-seed-city-id-fnv1a-xor;24to128-rays;step-at-most10m;phase-smooth-three-harmonics-radius-0.85to1.15;actual-sampler-surface-or-complete-classify-edge-portal;surface-abs-grade-integral-ds-times-1-plus-0.6-normalized-grade-over-one-minus-normalized;normalized-grade-at-least-0.995-reject;bounded-ccw-nonclosed-3to128|unbuildable-empty;city-road-continuous-points-inside-boundary;intercity-unclipped\",\"cityStructuredClip\":\"v8-nonarterial-all-exact-boundary-inside-runs;candidate-segment-boundary-intersections;boundary-inclusive;rooted-run-nearest-original-sweep-midpoint-else-inside-run-nearest-midpoint;arterial-uses-legacy-origin-first-exit-clip;final-route-sample-boundary-verify-at-most10m\",\"cityStructuredRoot\":\"v8-transverse-same-city-surface-strict-internal-xy-intersection;parallel-collinear-endpoint-near-end-reject-epsilon1e-9;nearest-original-sweep-midpoint-then-stable-road-segment-point-pair-tie-order;root-z-actual-terrain-sample;both-old-surface-halves-revalidate-before-noding\",\"cityRootArms\":\"root-left-right-independent-anchor-direct-or-bounded-astar-finish-and-boundary-check;both-concatenate|one-commit-valid-arm-and-record-other-unreachable|none-reject;assembled-root-route-no-acute-final-gate;preserve-root-xy\",\"citySurfaceNoding\":\"v8-same-city-nonintercity-surface-only;strict-internal-xy-crossing-with-nonfinite-reject-and-dimensionless-interior-epsilon1e-9|positive-collinear-xy-overlap-line-distance-at-most1e-7;canonical-overlap-endpoints-xy-round-1e-7m-and-z-actual-terrain-sample;all-four-half-edges-or-local-endpoint-replacement-surface-revalidate;stable-road-segment-original-edge-index-descending-and-t-descending-insert-order;not-cross-city-bridge-tunnel-or-general-grade-separation\",\"cityExactSurfaceReuse\":\"after-same-city-surface-noding-and-common-overlap-endpoint-rewrite;same-city-nonintercity-contiguous-all-surface-normalized-run-only-without-crossing-bridge-or-tunnel;undirected-exact-xyz-bit-elementary-key;arterial-then-local-then-lexical-road-id-owner;partial-overlap-reuse-removes-nonowner-exact-pieces-retains-continuous-chains;single-retained-chain-keeps-parent-id|multiple-retained-chains-child-id-parent-plus-retained-child-first-last-xy-IEEE-bits-and-reuse-purpose-no-ordinal;refresh-sorted-layout-ids;no-reuse-status-output;not-near-or-unvalidated-overlap-reuse\",\"cityAccess\":\"legacy-v6-only:surface-street-node-short-connect-v1;radius-over-block-times-1.5-ceil-4to12;candidate-distance-0.75to3-block;target-1.7-block;stable-city-seed-node-pair-sort;surface-only-existing-nodes;actual-sampler-direct-or-bounded-astar;complete-portal-no-acute-boundary-containment;access-unreachable-domain-v1\",\"parcelAlgorithm\":\"identity-bound-v1;v6=legacy-v6-road-core-and-parcels;v8=structured-v8-road-core-and-parcels;v9=structured-v8-road-core-plus-frontage-balanced-v9-parcels;v9-vs-v8-selects-parcel-only;no-load-time-upgrade\",\"parcelFace\":\"structured-v8-convex-closed-face-with-every-simplified-edge-matched-to-real-ordinary-street-elementary-frontage-only;per-edge-inward-half-plane-offset-before-split;clearance-max-matching-edge-half-width-plus-nonnegative-setback;mixed-width-collinear-match-uses-max-conservative-clearance;nonconvex-unmatched-or-invalid-offset-closed-face-reject-no-topology-guess\",\"parcelSplit\":\"frontage-balanced-v9-primary-structured-v8-projection-midline-clip-area-settings-maxFaceAreaMeters-default22500;each-child-needs-longest-continuous-collinear-overlap-with-inset-real-street-frontage-at-least-max-10-min-20-widest-road;not-fragment-sum;when-primary-area-frontage-invalid-try-real-inset-frontage-overlap-cuts-length-desc-edge-id-normal-key;canonical-positive-frontage-tangent-normal;cut-overlap-midpoint-projection;dedup-normal-and-cut;first-area-frontage-valid-candidate;recursive-split-depth8;emitted-children-pass-existing-final-terrain-corridor-nonoverlap-gates;no-retry-after-final-rejection;on-all-area-frontage-failure-retain-parent-unsplit;cut-edge-is-not-frontage\",\"parcelFrontage\":\"face-plus-uncovered-frontage-v1;open-area-only-real-surface-ordinary-street-segment-run;polyline-slice-min16-max42-except-unsplittable-first-edge-may-exceed42;two-sided-offset;inner-road-corridor-clearance-plus-0.01;source-run-clearance-recheck-at-least-clearance-minus0.2;depth-clamp-blockSize-times-0.18-10to20;source-and-road-corridor-clear;face-first-frontage-positive-area-nonoverlap-stable-id-greedy-v1;no-entrance-or-navigation-reachability-claim\",\"legacyParcel\":\"legacy-v6-undefined-or-explicit-legacy-uses-prior-split-and-centroid-inset-path;structured-v8-uses-convex-offset-and-primary-child-frontage-rule;frontage-balanced-v9-keeps-v8-road-core-face-inset-and-primary-split-plus-stable-frontage-cut-fallback;shared-invalid-algorithm-fail-closed\",\"parcelGraph\":\"road-parcels-v4-boundary-highway\",\"parcelIdentity\":\"boundary-token-sorted-hash-worldSeed-citySeed-cityId;oriented-split-normal-token;frontage-side-and-ordinal;weighted-land-use;id-sort-v3\",\"parcelTerrain\":\"polygon-touching-cells-dry-finite;adjacent-touching-cell-slope-at-most-settings-maxSlope;grid-at-most257-v1\",\"roadClass\":\"required-kind-intercity-arterial-local;required-class-street-motorway;intercity-motorway-else-street;all-intercity-motorway-and-city-nonbuildable-roads-forbidden-corridor;centerline-no-intersection-or-containment;clearance-half-width-plus-setback-v1\",\"direction\":\"heading-dot-at-least-zero;interior-angle-at-least90deg;all-assembled-route-final-gate-v2\",\"limits\":\"maxGrade-roadWidthMeters-maxBridgeLengthMeters-maxTunnelLengthMeters-v1\",\"elevation\":\"relative-height-times-elevationScaleMeters-v1\",\"terrain\":\"canonical-plane-hydrology-fixed-sampling;global-long-axis257;city-long-axis65to257;actual-finite-sampler-step10m;no-sub10m-obstacle-guarantee-v1\",\"portalLookahead\":\"complete-portal-before-partial-surface-v1;exact-dry-grid-portal-preserved-v1;off-grid-origin-requires-validated-surface-connector-v1;connector-budget-cost-required-v1\",\"bridge\":\"complete-dry-portal-water-span-v1;linear-deck-3d-length-at-most-maxBridgeLengthMeters;all-water-interior;no-shortcut-or-split-v2\",\"tunnel\":\"covered-dry-portal-bore;actual-cover-at-least1m;3d-length-at-most-maxTunnelLengthMeters;no-shortcut-or-split;no-water-interior;roadWidth-surface-abutment-v2\",\"shortcut\":\"surface-run-control-edge-boundaries;candidates-i-to-j-j-at-most-i-plus24-or-last;actual-sampler-water-grade-step-at-most10m;reverse-sparse-dag-heading-compatible-dot-epsilon1e-12;no-accumulated-cost;farthest-reachable-stable-descending;retain-original-if-no-complete-chain;whole-road-stable-branch-unreachable-if-final-acute;bridge-tunnel-excluded-v3\",\"repair\":\"same-core-segment-splice;10m-grid;at-most8-attempts;min-margin200m-v1\"}";
+export declare const FRONTAGE_BALANCED_V9_IDENTITY: "chat.worldengine.terrain-roads/v1;rules-sha256=671b01df50d378c85208f910ba10e63ff5b03d3787619898c8de60453329b38b";
+export declare const ROAD_GENERATION_RULES_CANONICAL: "{\"version\":10,\"algorithm\":\"direction-state-a-star-v2;32-coprime-neighbors;stable-heap-tie-order;route-edge-cache-v1\",\"cityField\":\"structured-two-family-seeded-skeleton-v8;candidate-only-actual-terrain-router-required\",\"cityCandidateBudget\":\"boundary-polygon-shoelace-abs-area-m2;ceil-sqrt-area-over-block-times-0.42-per-family;clamp6to15;not-nominal-radius-area;not-feasible-terrain-mask\",\"cityCandidateFamilies\":\"six-arterial-rays-from-center-four-collinear-points;arterial-base-seeded-angle-plus-sixth-turn-plus-seeded-jitter;two-transverse-families-base-and-base-plus-pi-over-two-plus-seeded-0.18rad;collector-and-local;four-point-parabolic-sweeps;seeded-bend-block-times-0.32;actual-terrain-and-boundary-gates\",\"cityBoundary\":\"radial-budget-v2;world-seed-city-seed-city-id-fnv1a-xor;24to128-rays;step-at-most10m;phase-smooth-three-harmonics-radius-0.85to1.15;actual-sampler-surface-or-complete-classify-edge-portal;surface-abs-grade-integral-ds-times-1-plus-0.6-normalized-grade-over-one-minus-normalized;normalized-grade-at-least-0.995-reject;bounded-ccw-nonclosed-3to128|unbuildable-empty;city-road-continuous-points-inside-boundary;intercity-unclipped\",\"cityStructuredClip\":\"v8-nonarterial-all-exact-boundary-inside-runs;candidate-segment-boundary-intersections;boundary-inclusive;rooted-run-nearest-original-sweep-midpoint-else-inside-run-nearest-midpoint;arterial-uses-legacy-origin-first-exit-clip;final-route-sample-boundary-verify-at-most10m\",\"cityStructuredRoot\":\"v8-transverse-same-city-surface-strict-internal-xy-intersection;parallel-collinear-endpoint-near-end-reject-epsilon1e-9;nearest-original-sweep-midpoint-then-stable-road-segment-point-pair-tie-order;root-z-actual-terrain-sample;both-old-surface-halves-revalidate-before-noding\",\"cityRootArms\":\"root-left-right-independent-anchor-direct-or-bounded-astar-finish-and-boundary-check;both-concatenate|one-commit-valid-arm-and-record-other-unreachable|none-reject;assembled-root-route-no-acute-final-gate;preserve-root-xy\",\"citySurfaceNoding\":\"v8-same-city-nonintercity-surface-only;strict-internal-xy-crossing-with-nonfinite-reject-and-dimensionless-interior-epsilon1e-9|positive-collinear-xy-overlap-line-distance-at-most1e-7;canonical-overlap-endpoints-xy-round-1e-7m-and-z-actual-terrain-sample;all-four-half-edges-or-local-endpoint-replacement-surface-revalidate;stable-road-segment-original-edge-index-descending-and-t-descending-insert-order;not-cross-city-bridge-tunnel-or-general-grade-separation\",\"cityExactSurfaceReuse\":\"after-same-city-surface-noding-and-common-overlap-endpoint-rewrite;same-city-nonintercity-contiguous-all-surface-normalized-run-only-without-crossing-bridge-or-tunnel;undirected-exact-xyz-bit-elementary-key;arterial-then-local-then-lexical-road-id-owner;partial-overlap-reuse-removes-nonowner-exact-pieces-retains-continuous-chains;single-retained-chain-keeps-parent-id|multiple-retained-chains-child-id-parent-plus-retained-child-first-last-xy-IEEE-bits-and-reuse-purpose-no-ordinal;refresh-sorted-layout-ids;no-reuse-status-output;not-near-or-unvalidated-overlap-reuse\",\"cityAccess\":\"legacy-v6-only:surface-street-node-short-connect-v1;radius-over-block-times-1.5-ceil-4to12;candidate-distance-0.75to3-block;target-1.7-block;stable-city-seed-node-pair-sort;surface-only-existing-nodes;actual-sampler-direct-or-bounded-astar;complete-portal-no-acute-boundary-containment;access-unreachable-domain-v1\",\"parcelAlgorithm\":\"identity-bound-v1;v6=legacy-v6-road-core-and-parcels;v8=structured-v8-road-core-and-parcels;v9=structured-v8-road-core-plus-frontage-balanced-v9-parcels;v10=structured-v8-road-core-plus-shape-filled-v10-parcels;v10-vs-v9-selects-parcel-only;no-load-time-upgrade\",\"parcelFace\":\"shape-filled-v10-simple-single-ring-closed-face;real-ordinary-street-elementary-frontage-only;collinear-ring-simplify;per-edge-inward-offset-max-matching-real-road-half-width-plus-nonnegative-setback-plus-4epsilon-quantization-guard;inset-must-stay-within-source-and-strict-road-clearance;self-cross-reject;concave-ear-clip-then-stable-convex-merge;internal-chords-have-no-offset-and-no-frontage;unsupported-complex-or-hole-face-reject-no-topology-guess\",\"parcelSplit\":\"shape-filled-v10-long-axis-oriented-bounds-primary-then-stable-face-axis;projection-midline-clip-targets-settings-maxFaceAreaMeters-default22500-not-terminal-hard-limit;shape-context-cut-children-inset-by-4epsilon-per-side-leaving-8epsilon-artificial-nonroad-gap-to-prevent-quantized-shared-edge-positive-overlap;no-distance-or-overlap-gate-relaxation;both-children-area-at-least-settings-minParcelAreaMeters-default36;each-child-needs-longest-continuous-real-inset-street-frontage-at-least-max-10-min-20-widest-road;shape-node-and-recursive-output-hard-gates;pair-atomic-no-single-child-commit;frontage-balanced-real-inset-frontage-cut-fallback;recursive-depth8;at-depth-or-no-valid-cut-shape-valid-parent-may-remain-even-over-max-area;at-depth-or-no-valid-cut-invalid-shape-reject;cut-edge-is-not-frontage\",\"parcelFrontage\":\"shape-filled-v10-face-first-then-uncovered-frontage-only;closed-valid-inset-faces-fill-before-open-street;real-surface-ordinary-street-run-resampled-at-at-most-min-10-maxSliceLength;two-sided-offset;depth-at-least-blockSize-times-0.18-and-at-least-minShortSide-times-sqrt2-plus1;maxSliceLength-max-requiredStripDimension-plus10-only-when-requiredStripDimension-over42-and-min-42-maxAspectRatio-times-depth-so-minShortSide-override-remains-sliceable;slice-at-least-minShortSide-times-sqrt2-plus1;shape-safe-bounds-and-ratio-hard-gates;source-and-all-road-corridor-boundary-terrain-clear;positive-area-nonoverlap-stable-id-greedy;no-entrance-or-navigation-reachability-claim\",\"legacyParcel\":\"legacy-v6-undefined-or-explicit-legacy-uses-prior-split-and-centroid-inset-path;structured-v8-uses-convex-offset-and-primary-child-frontage-rule;frontage-balanced-v9-keeps-v8-road-core-face-inset-and-primary-split-plus-stable-frontage-cut-fallback;shape-filled-v10-keeps-v8-road-core-and-uses-simple-ring-inset-concave-decomposition-shape-hard-gates-and-uncovered-frontage-only;shared-invalid-algorithm-fail-closed\",\"parcelGraph\":\"road-parcels-v4-boundary-highway\",\"parcelIdentity\":\"boundary-token-sorted-hash-worldSeed-citySeed-cityId;oriented-split-normal-token;frontage-side-and-ordinal;weighted-land-use;id-sort-v3;shape-filled-v10-canonical-ring-ear-clip-first-valid-vertex-order-then-first-pair-convex-merge-loop;decomposed-piece-traversal-order-is-explicit-root-c-pieceIndex-and-affects-stable-id\",\"parcelTerrain\":\"polygon-touching-cells-dry-finite;adjacent-touching-cell-slope-at-most-settings-maxSlope;grid-at-most257-v1\",\"roadClass\":\"required-kind-intercity-arterial-local;required-class-street-motorway;intercity-motorway-else-street;all-intercity-motorway-and-city-nonbuildable-roads-forbidden-corridor;centerline-no-intersection-or-containment;clearance-half-width-plus-setback-v1\",\"direction\":\"heading-dot-at-least-zero;interior-angle-at-least90deg;all-assembled-route-final-gate-v2\",\"limits\":\"maxGrade-roadWidthMeters-maxBridgeLengthMeters-maxTunnelLengthMeters-v1\",\"elevation\":\"relative-height-times-elevationScaleMeters-v1\",\"terrain\":\"canonical-plane-hydrology-fixed-sampling;global-long-axis257;city-long-axis65to257;actual-finite-sampler-step10m;no-sub10m-obstacle-guarantee-v1\",\"portalLookahead\":\"complete-portal-before-partial-surface-v1;exact-dry-grid-portal-preserved-v1;off-grid-origin-requires-validated-surface-connector-v1;connector-budget-cost-required-v1\",\"bridge\":\"complete-dry-portal-water-span-v1;linear-deck-3d-length-at-most-maxBridgeLengthMeters;all-water-interior;no-shortcut-or-split-v2\",\"tunnel\":\"covered-dry-portal-bore;actual-cover-at-least1m;3d-length-at-most-maxTunnelLengthMeters;no-shortcut-or-split;no-water-interior;roadWidth-surface-abutment-v2\",\"shortcut\":\"surface-run-control-edge-boundaries;candidates-i-to-j-j-at-most-i-plus24-or-last;actual-sampler-water-grade-step-at-most10m;reverse-sparse-dag-heading-compatible-dot-epsilon1e-12;no-accumulated-cost;farthest-reachable-stable-descending;retain-original-if-no-complete-chain;whole-road-stable-branch-unreachable-if-final-acute;bridge-tunnel-excluded-v3\",\"repair\":\"same-core-segment-splice;10m-grid;at-most8-attempts;min-margin200m-v1\",\"parcelShape\":\"coordinates-round-decimal6-epsilon1e-6;minimum-oriented-convex-hull-edge-aligned-bounds;settings-maxAspectRatio-finite-at-least1-default4;settings-minShortSideMeters-finite-at-least26-default26;short-side-at-least-minShortSideMeters;long-side-at-most-short-side-times-maxAspectRatio;safe-axis-aligned-square-inside-polygon-width-and-height-at-least-minShortSideMeters;all-partition-nodes-and-emitted-parcels-terrain-boundary-corridor-clear\"}";
+export declare const ROAD_GENERATION_IDENTITY: "chat.worldengine.terrain-roads/v1;rules-sha256=58fc51cfe9986a8da0cc6931c8600cf4c1afbbcda80f58e00038b76f982aec5b";
+/**
+ * 已发布 identity 的精确 allowlist。新算法必须先有冻结的 rules digest，才能加入这里；
+ * 不得以“当前默认值”替换已保存 source 的 identity。
+ */
+export declare const SUPPORTED_ROAD_GENERATION_IDENTITIES: readonly ["chat.worldengine.terrain-roads/v1;rules-sha256=9dc32e6e3f5e63fbf378d6b83dfa67c2e9d62dabfebe5b432956f7ff0fdb8443", "chat.worldengine.terrain-roads/v1;rules-sha256=03ab0544e8fdfc741045dccac18a946eb95b76bc10e9880012cba50060b29b4f", "chat.worldengine.terrain-roads/v1;rules-sha256=671b01df50d378c85208f910ba10e63ff5b03d3787619898c8de60453329b38b", "chat.worldengine.terrain-roads/v1;rules-sha256=58fc51cfe9986a8da0cc6931c8600cf4c1afbbcda80f58e00038b76f982aec5b"];
+export type RoadGenerationIdentity = (typeof SUPPORTED_ROAD_GENERATION_IDENTITIES)[number];
+/**
+ * 已保存 identity 到 core selector 的语义映射。source 只能按它自身的已发布 identity
+ * 重放；新默认值不得覆盖旧 source。
+ */
+export type RoadGenerationAlgorithm = "legacy-v6" | "structured-v8";
+export declare function roadGenerationAlgorithm(identity: RoadGenerationIdentity): RoadGenerationAlgorithm;
+export type RoadParcelAlgorithm = "legacy-v6" | "structured-v8" | "frontage-balanced-v9" | "shape-filled-v10";
+/** 已保存 identity 独立选择 parcel 语义；V9 仍复用已发布 V8 道路 core。 */
+export declare function roadParcelAlgorithm(identity: RoadGenerationIdentity): RoadParcelAlgorithm;
+/**
+ * 只有已冻结的后继 identity 才能令旧 source 出现显式升级预览入口。
+ * 加载或保存绝不能据此静默升级。
+ */
+export declare function roadGenerationUpgradeTarget(identity: RoadGenerationIdentity): RoadGenerationIdentity | undefined;
+export interface RoadGenerationV1 {
+    readonly profile: typeof ROAD_GENERATION_PROFILE;
+    readonly identity: RoadGenerationIdentity;
+    readonly allowBridges: boolean;
+    readonly allowTunnels: boolean;
+    readonly maxBridgeLengthMeters: number;
+    readonly maxTunnelLengthMeters: number;
+    readonly maxGrade: number;
+    readonly roadWidthMeters: number;
+    /** 相对地形高度值换算为米的比例。 */
+    readonly elevationScaleMeters: number;
+}
+export declare const DEFAULT_ROAD_GENERATION: Readonly<RoadGenerationV1>;
+/** 严格验证桥隧道路设置，拒绝未知字段并返回不可变 canonical 副本。 */
+export declare function validateRoadGeneration(input: unknown): RoadGenerationV1;

package/dist/road-generation.js

@@ -0,0 +1,129 @@
+export const ROAD_GENERATION_PROFILE = "terrain-roads-v1";
+/**
+ * 绑定路径搜索、桥隧门户、地形采样和地块图语义的 canonical 规则字节。
+ * 任一语义变更都必须更新这份 JSON 并发布新 identity。
+ */
+export const LEGACY_V6_ROAD_GENERATION_RULES_CANONICAL = '{"algorithm":"direction-state-a-star-v2;32-coprime-neighbors;stable-heap-tie-order;route-edge-cache-v1","anchor":"city-guide-anchor-once;whole-candidate-single-connectors;no-grid-exact-grid-pair-foldback-v3","bridge":"complete-dry-portal-water-span-v1;linear-deck-3d-length-at-most-maxBridgeLengthMeters;all-water-interior;no-shortcut-or-split-v2","cityAccess":"surface-street-node-short-connect-v1;radius-over-block-times-1.5-ceil-4to12;candidate-distance-0.75to3-block;target-1.7-block;stable-city-seed-node-pair-sort;surface-only-existing-nodes;actual-sampler-direct-or-bounded-astar;complete-portal-no-acute-boundary-containment;access-unreachable-domain-v1","cityBoundary":"radial-budget-v2;world-seed-city-seed-city-id-fnv1a-xor;24to128-rays;step-at-most10m;phase-smooth-three-harmonics-radius-0.85to1.15;actual-sampler-surface-or-complete-classify-edge-portal;surface-abs-grade-integral-ds-times-1-plus-0.6-normalized-grade-over-one-minus-normalized;normalized-grade-at-least-0.995-reject;bounded-ccw-nonclosed-3to128|unbuildable-empty;city-road-continuous-points-inside-boundary;intercity-unclipped","cityField":"seeded-radial-terrain-contour-guide-v1","direction":"heading-dot-at-least-zero;interior-angle-at-least90deg;all-assembled-route-final-gate-v2","elevation":"relative-height-times-elevationScaleMeters-v1","limits":"maxGrade-roadWidthMeters-maxBridgeLengthMeters-maxTunnelLengthMeters-v1","parcelFace":"road-parcels-v4-boundary-highway;cityId-exact-arterial-local-street-surface-only;quantized-strict-xy-intersection-split;dcel-left-turn;positive-inside-concave-boundary;oriented-length-weighted-second-moment-principal-axis;canonical-longest-edge-isotropic-fallback;projection-midline-clip;area22500-recursion-depth8;inset-half-widest-road-plus-setback;triangulated-max-square-safe-bounds-v4","parcelFrontage":"face-plus-uncovered-frontage-v1;cityId-exact-arterial-local-street-surface-elementary-run;polyline-slice-16to42m;two-sided-offset;depth-clamp-blockSize-times-0.18-10to20;source-and-road-corridor-clear;face-first-frontage-positive-area-nonoverlap-stable-id-greedy-v1","parcelGraph":"road-parcels-v4-boundary-highway","parcelIdentity":"boundary-token-sorted-hash-worldSeed-citySeed-cityId;oriented-split-normal-token;frontage-side-and-ordinal;weighted-land-use;id-sort-v3","parcelTerrain":"polygon-touching-cells-dry-finite;adjacent-touching-cell-slope-at-most-settings-maxSlope;grid-at-most257-v1","portalLookahead":"complete-portal-before-partial-surface-v1;exact-dry-grid-portal-preserved-v1;off-grid-origin-requires-validated-surface-connector-v1;connector-budget-cost-required-v1","repair":"same-core-segment-splice;10m-grid;at-most8-attempts;min-margin200m-v1","roadClass":"required-kind-intercity-arterial-local;required-class-street-motorway;intercity-motorway-else-street;all-intercity-motorway-and-city-nonbuildable-roads-forbidden-corridor;centerline-no-intersection-or-containment;clearance-half-width-plus-setback-v1","shortcut":"surface-run-control-edge-boundaries;candidates-i-to-j-j-at-most-i-plus24-or-last;actual-sampler-water-grade-step-at-most10m;reverse-sparse-dag-heading-compatible-dot-epsilon1e-12;no-accumulated-cost;farthest-reachable-stable-descending;retain-original-if-no-complete-chain;whole-road-stable-branch-unreachable-if-final-acute;bridge-tunnel-excluded-v3","terrain":"canonical-plane-hydrology-fixed-sampling;global-long-axis257;city-long-axis65to257;actual-finite-sampler-step10m;no-sub10m-obstacle-guarantee-v1","tunnel":"covered-dry-portal-bore;actual-cover-at-least1m;3d-length-at-most-maxTunnelLengthMeters;no-shortcut-or-split;no-water-interior;roadWidth-surface-abutment-v2","version":6}';
+/**
+ * 该字符串绑定 profile、算法版本与上方 canonical 规则字节的 SHA-256。
+ * 道路语义变化时必须发布新 identity，禁止让旧世界静默重算为不同结果。
+ */
+export const LEGACY_V6_IDENTITY = "chat.worldengine.terrain-roads/v1;rules-sha256=9dc32e6e3f5e63fbf378d6b83dfa67c2e9d62dabfebe5b432956f7ff0fdb8443";
+export const STRUCTURED_V8_ROAD_GENERATION_RULES_CANONICAL = '{"version":8,"algorithm":"direction-state-a-star-v2;32-coprime-neighbors;stable-heap-tie-order;route-edge-cache-v1","cityField":"structured-two-family-seeded-skeleton-v8;candidate-only-actual-terrain-router-required","cityCandidateBudget":"boundary-polygon-shoelace-abs-area-m2;ceil-sqrt-area-over-block-times-0.42-per-family;clamp6to15;not-nominal-radius-area;not-feasible-terrain-mask","cityCandidateFamilies":"six-arterial-rays-from-center-four-collinear-points;arterial-base-seeded-angle-plus-sixth-turn-plus-seeded-jitter;two-transverse-families-base-and-base-plus-pi-over-two-plus-seeded-0.18rad;collector-and-local;four-point-parabolic-sweeps;seeded-bend-block-times-0.32;actual-terrain-and-boundary-gates","cityBoundary":"radial-budget-v2;world-seed-city-seed-city-id-fnv1a-xor;24to128-rays;step-at-most10m;phase-smooth-three-harmonics-radius-0.85to1.15;actual-sampler-surface-or-complete-classify-edge-portal;surface-abs-grade-integral-ds-times-1-plus-0.6-normalized-grade-over-one-minus-normalized;normalized-grade-at-least-0.995-reject;bounded-ccw-nonclosed-3to128|unbuildable-empty;city-road-continuous-points-inside-boundary;intercity-unclipped","cityStructuredClip":"v8-nonarterial-all-exact-boundary-inside-runs;candidate-segment-boundary-intersections;boundary-inclusive;rooted-run-nearest-original-sweep-midpoint-else-inside-run-nearest-midpoint;arterial-uses-legacy-origin-first-exit-clip;final-route-sample-boundary-verify-at-most10m","cityStructuredRoot":"v8-transverse-same-city-surface-strict-internal-xy-intersection;parallel-collinear-endpoint-near-end-reject-epsilon1e-9;nearest-original-sweep-midpoint-then-stable-road-segment-point-pair-tie-order;root-z-actual-terrain-sample;both-old-surface-halves-revalidate-before-noding","cityRootArms":"root-left-right-independent-anchor-direct-or-bounded-astar-finish-and-boundary-check;both-concatenate|one-commit-valid-arm-and-record-other-unreachable|none-reject;assembled-root-route-no-acute-final-gate;preserve-root-xy","citySurfaceNoding":"v8-same-city-nonintercity-surface-only;strict-internal-xy-crossing-with-nonfinite-reject-and-dimensionless-interior-epsilon1e-9|positive-collinear-xy-overlap-line-distance-at-most1e-7;canonical-overlap-endpoints-xy-round-1e-7m-and-z-actual-terrain-sample;all-four-half-edges-or-local-endpoint-replacement-surface-revalidate;stable-road-segment-original-edge-index-descending-and-t-descending-insert-order;not-cross-city-bridge-tunnel-or-general-grade-separation","cityExactSurfaceReuse":"after-same-city-surface-noding-and-common-overlap-endpoint-rewrite;same-city-nonintercity-contiguous-all-surface-normalized-run-only-without-crossing-bridge-or-tunnel;undirected-exact-xyz-bit-elementary-key;arterial-then-local-then-lexical-road-id-owner;partial-overlap-reuse-removes-nonowner-exact-pieces-retains-continuous-chains;single-retained-chain-keeps-parent-id|multiple-retained-chains-child-id-parent-plus-retained-child-first-last-xy-IEEE-bits-and-reuse-purpose-no-ordinal;refresh-sorted-layout-ids;no-reuse-status-output;not-near-or-unvalidated-overlap-reuse","cityAccess":"legacy-v6-only:surface-street-node-short-connect-v1;radius-over-block-times-1.5-ceil-4to12;candidate-distance-0.75to3-block;target-1.7-block;stable-city-seed-node-pair-sort;surface-only-existing-nodes;actual-sampler-direct-or-bounded-astar;complete-portal-no-acute-boundary-containment;access-unreachable-domain-v1","parcelFace":"structured-v8-convex-closed-face-with-every-simplified-edge-matched-to-real-ordinary-street-elementary-frontage-only;per-edge-inward-half-plane-offset-before-split;clearance-max-matching-edge-half-width-plus-nonnegative-setback;mixed-width-collinear-match-uses-max-conservative-clearance;nonconvex-unmatched-or-invalid-offset-closed-face-reject-no-topology-guess","parcelSplit":"structured-v8-projection-midline-clip-area-settings-maxFaceAreaMeters-default22500-recursion-depth8;each-child-needs-longest-continuous-collinear-overlap-with-inset-real-street-frontage-at-least-max-10-min-20-widest-road;not-fragment-sum;on-failure-retain-parent-unsplit;cut-edge-is-not-frontage","parcelFrontage":"face-plus-uncovered-frontage-v1;open-area-only-real-surface-ordinary-street-segment-run;polyline-slice-min16-max42-except-unsplittable-first-edge-may-exceed42;two-sided-offset;inner-road-corridor-clearance-plus-0.01;source-run-clearance-recheck-at-least-clearance-minus0.2;depth-clamp-blockSize-times-0.18-10to20;source-and-road-corridor-clear;face-first-frontage-positive-area-nonoverlap-stable-id-greedy-v1;no-entrance-or-navigation-reachability-claim","legacyParcel":"legacy-v6-undefined-or-explicit-legacy-uses-prior-split-and-centroid-inset-path;v8-only-convex-offset-and-child-frontage-rule;shared-invalid-algorithm-fail-closed","parcelGraph":"road-parcels-v4-boundary-highway","parcelIdentity":"boundary-token-sorted-hash-worldSeed-citySeed-cityId;oriented-split-normal-token;frontage-side-and-ordinal;weighted-land-use;id-sort-v3","parcelTerrain":"polygon-touching-cells-dry-finite;adjacent-touching-cell-slope-at-most-settings-maxSlope;grid-at-most257-v1","roadClass":"required-kind-intercity-arterial-local;required-class-street-motorway;intercity-motorway-else-street;all-intercity-motorway-and-city-nonbuildable-roads-forbidden-corridor;centerline-no-intersection-or-containment;clearance-half-width-plus-setback-v1","direction":"heading-dot-at-least-zero;interior-angle-at-least90deg;all-assembled-route-final-gate-v2","limits":"maxGrade-roadWidthMeters-maxBridgeLengthMeters-maxTunnelLengthMeters-v1","elevation":"relative-height-times-elevationScaleMeters-v1","terrain":"canonical-plane-hydrology-fixed-sampling;global-long-axis257;city-long-axis65to257;actual-finite-sampler-step10m;no-sub10m-obstacle-guarantee-v1","portalLookahead":"complete-portal-before-partial-surface-v1;exact-dry-grid-portal-preserved-v1;off-grid-origin-requires-validated-surface-connector-v1;connector-budget-cost-required-v1","bridge":"complete-dry-portal-water-span-v1;linear-deck-3d-length-at-most-maxBridgeLengthMeters;all-water-interior;no-shortcut-or-split-v2","tunnel":"covered-dry-portal-bore;actual-cover-at-least1m;3d-length-at-most-maxTunnelLengthMeters;no-shortcut-or-split;no-water-interior;roadWidth-surface-abutment-v2","shortcut":"surface-run-control-edge-boundaries;candidates-i-to-j-j-at-most-i-plus24-or-last;actual-sampler-water-grade-step-at-most10m;reverse-sparse-dag-heading-compatible-dot-epsilon1e-12;no-accumulated-cost;farthest-reachable-stable-descending;retain-original-if-no-complete-chain;whole-road-stable-branch-unreachable-if-final-acute;bridge-tunnel-excluded-v3","repair":"same-core-segment-splice;10m-grid;at-most8-attempts;min-margin200m-v1"}';
+export const STRUCTURED_V8_IDENTITY = "chat.worldengine.terrain-roads/v1;rules-sha256=03ab0544e8fdfc741045dccac18a946eb95b76bc10e9880012cba50060b29b4f";
+export const FRONTAGE_BALANCED_V9_ROAD_GENERATION_RULES_CANONICAL = '{"version":9,"algorithm":"direction-state-a-star-v2;32-coprime-neighbors;stable-heap-tie-order;route-edge-cache-v1","cityField":"structured-two-family-seeded-skeleton-v8;candidate-only-actual-terrain-router-required","cityCandidateBudget":"boundary-polygon-shoelace-abs-area-m2;ceil-sqrt-area-over-block-times-0.42-per-family;clamp6to15;not-nominal-radius-area;not-feasible-terrain-mask","cityCandidateFamilies":"six-arterial-rays-from-center-four-collinear-points;arterial-base-seeded-angle-plus-sixth-turn-plus-seeded-jitter;two-transverse-families-base-and-base-plus-pi-over-two-plus-seeded-0.18rad;collector-and-local;four-point-parabolic-sweeps;seeded-bend-block-times-0.32;actual-terrain-and-boundary-gates","cityBoundary":"radial-budget-v2;world-seed-city-seed-city-id-fnv1a-xor;24to128-rays;step-at-most10m;phase-smooth-three-harmonics-radius-0.85to1.15;actual-sampler-surface-or-complete-classify-edge-portal;surface-abs-grade-integral-ds-times-1-plus-0.6-normalized-grade-over-one-minus-normalized;normalized-grade-at-least-0.995-reject;bounded-ccw-nonclosed-3to128|unbuildable-empty;city-road-continuous-points-inside-boundary;intercity-unclipped","cityStructuredClip":"v8-nonarterial-all-exact-boundary-inside-runs;candidate-segment-boundary-intersections;boundary-inclusive;rooted-run-nearest-original-sweep-midpoint-else-inside-run-nearest-midpoint;arterial-uses-legacy-origin-first-exit-clip;final-route-sample-boundary-verify-at-most10m","cityStructuredRoot":"v8-transverse-same-city-surface-strict-internal-xy-intersection;parallel-collinear-endpoint-near-end-reject-epsilon1e-9;nearest-original-sweep-midpoint-then-stable-road-segment-point-pair-tie-order;root-z-actual-terrain-sample;both-old-surface-halves-revalidate-before-noding","cityRootArms":"root-left-right-independent-anchor-direct-or-bounded-astar-finish-and-boundary-check;both-concatenate|one-commit-valid-arm-and-record-other-unreachable|none-reject;assembled-root-route-no-acute-final-gate;preserve-root-xy","citySurfaceNoding":"v8-same-city-nonintercity-surface-only;strict-internal-xy-crossing-with-nonfinite-reject-and-dimensionless-interior-epsilon1e-9|positive-collinear-xy-overlap-line-distance-at-most1e-7;canonical-overlap-endpoints-xy-round-1e-7m-and-z-actual-terrain-sample;all-four-half-edges-or-local-endpoint-replacement-surface-revalidate;stable-road-segment-original-edge-index-descending-and-t-descending-insert-order;not-cross-city-bridge-tunnel-or-general-grade-separation","cityExactSurfaceReuse":"after-same-city-surface-noding-and-common-overlap-endpoint-rewrite;same-city-nonintercity-contiguous-all-surface-normalized-run-only-without-crossing-bridge-or-tunnel;undirected-exact-xyz-bit-elementary-key;arterial-then-local-then-lexical-road-id-owner;partial-overlap-reuse-removes-nonowner-exact-pieces-retains-continuous-chains;single-retained-chain-keeps-parent-id|multiple-retained-chains-child-id-parent-plus-retained-child-first-last-xy-IEEE-bits-and-reuse-purpose-no-ordinal;refresh-sorted-layout-ids;no-reuse-status-output;not-near-or-unvalidated-overlap-reuse","cityAccess":"legacy-v6-only:surface-street-node-short-connect-v1;radius-over-block-times-1.5-ceil-4to12;candidate-distance-0.75to3-block;target-1.7-block;stable-city-seed-node-pair-sort;surface-only-existing-nodes;actual-sampler-direct-or-bounded-astar;complete-portal-no-acute-boundary-containment;access-unreachable-domain-v1","parcelAlgorithm":"identity-bound-v1;v6=legacy-v6-road-core-and-parcels;v8=structured-v8-road-core-and-parcels;v9=structured-v8-road-core-plus-frontage-balanced-v9-parcels;v9-vs-v8-selects-parcel-only;no-load-time-upgrade","parcelFace":"structured-v8-convex-closed-face-with-every-simplified-edge-matched-to-real-ordinary-street-elementary-frontage-only;per-edge-inward-half-plane-offset-before-split;clearance-max-matching-edge-half-width-plus-nonnegative-setback;mixed-width-collinear-match-uses-max-conservative-clearance;nonconvex-unmatched-or-invalid-offset-closed-face-reject-no-topology-guess","parcelSplit":"frontage-balanced-v9-primary-structured-v8-projection-midline-clip-area-settings-maxFaceAreaMeters-default22500;each-child-needs-longest-continuous-collinear-overlap-with-inset-real-street-frontage-at-least-max-10-min-20-widest-road;not-fragment-sum;when-primary-area-frontage-invalid-try-real-inset-frontage-overlap-cuts-length-desc-edge-id-normal-key;canonical-positive-frontage-tangent-normal;cut-overlap-midpoint-projection;dedup-normal-and-cut;first-area-frontage-valid-candidate;recursive-split-depth8;emitted-children-pass-existing-final-terrain-corridor-nonoverlap-gates;no-retry-after-final-rejection;on-all-area-frontage-failure-retain-parent-unsplit;cut-edge-is-not-frontage","parcelFrontage":"face-plus-uncovered-frontage-v1;open-area-only-real-surface-ordinary-street-segment-run;polyline-slice-min16-max42-except-unsplittable-first-edge-may-exceed42;two-sided-offset;inner-road-corridor-clearance-plus-0.01;source-run-clearance-recheck-at-least-clearance-minus0.2;depth-clamp-blockSize-times-0.18-10to20;source-and-road-corridor-clear;face-first-frontage-positive-area-nonoverlap-stable-id-greedy-v1;no-entrance-or-navigation-reachability-claim","legacyParcel":"legacy-v6-undefined-or-explicit-legacy-uses-prior-split-and-centroid-inset-path;structured-v8-uses-convex-offset-and-primary-child-frontage-rule;frontage-balanced-v9-keeps-v8-road-core-face-inset-and-primary-split-plus-stable-frontage-cut-fallback;shared-invalid-algorithm-fail-closed","parcelGraph":"road-parcels-v4-boundary-highway","parcelIdentity":"boundary-token-sorted-hash-worldSeed-citySeed-cityId;oriented-split-normal-token;frontage-side-and-ordinal;weighted-land-use;id-sort-v3","parcelTerrain":"polygon-touching-cells-dry-finite;adjacent-touching-cell-slope-at-most-settings-maxSlope;grid-at-most257-v1","roadClass":"required-kind-intercity-arterial-local;required-class-street-motorway;intercity-motorway-else-street;all-intercity-motorway-and-city-nonbuildable-roads-forbidden-corridor;centerline-no-intersection-or-containment;clearance-half-width-plus-setback-v1","direction":"heading-dot-at-least-zero;interior-angle-at-least90deg;all-assembled-route-final-gate-v2","limits":"maxGrade-roadWidthMeters-maxBridgeLengthMeters-maxTunnelLengthMeters-v1","elevation":"relative-height-times-elevationScaleMeters-v1","terrain":"canonical-plane-hydrology-fixed-sampling;global-long-axis257;city-long-axis65to257;actual-finite-sampler-step10m;no-sub10m-obstacle-guarantee-v1","portalLookahead":"complete-portal-before-partial-surface-v1;exact-dry-grid-portal-preserved-v1;off-grid-origin-requires-validated-surface-connector-v1;connector-budget-cost-required-v1","bridge":"complete-dry-portal-water-span-v1;linear-deck-3d-length-at-most-maxBridgeLengthMeters;all-water-interior;no-shortcut-or-split-v2","tunnel":"covered-dry-portal-bore;actual-cover-at-least1m;3d-length-at-most-maxTunnelLengthMeters;no-shortcut-or-split;no-water-interior;roadWidth-surface-abutment-v2","shortcut":"surface-run-control-edge-boundaries;candidates-i-to-j-j-at-most-i-plus24-or-last;actual-sampler-water-grade-step-at-most10m;reverse-sparse-dag-heading-compatible-dot-epsilon1e-12;no-accumulated-cost;farthest-reachable-stable-descending;retain-original-if-no-complete-chain;whole-road-stable-branch-unreachable-if-final-acute;bridge-tunnel-excluded-v3","repair":"same-core-segment-splice;10m-grid;at-most8-attempts;min-margin200m-v1"}';
+export const FRONTAGE_BALANCED_V9_IDENTITY = "chat.worldengine.terrain-roads/v1;rules-sha256=671b01df50d378c85208f910ba10e63ff5b03d3787619898c8de60453329b38b";
+export const ROAD_GENERATION_RULES_CANONICAL = '{"version":10,"algorithm":"direction-state-a-star-v2;32-coprime-neighbors;stable-heap-tie-order;route-edge-cache-v1","cityField":"structured-two-family-seeded-skeleton-v8;candidate-only-actual-terrain-router-required","cityCandidateBudget":"boundary-polygon-shoelace-abs-area-m2;ceil-sqrt-area-over-block-times-0.42-per-family;clamp6to15;not-nominal-radius-area;not-feasible-terrain-mask","cityCandidateFamilies":"six-arterial-rays-from-center-four-collinear-points;arterial-base-seeded-angle-plus-sixth-turn-plus-seeded-jitter;two-transverse-families-base-and-base-plus-pi-over-two-plus-seeded-0.18rad;collector-and-local;four-point-parabolic-sweeps;seeded-bend-block-times-0.32;actual-terrain-and-boundary-gates","cityBoundary":"radial-budget-v2;world-seed-city-seed-city-id-fnv1a-xor;24to128-rays;step-at-most10m;phase-smooth-three-harmonics-radius-0.85to1.15;actual-sampler-surface-or-complete-classify-edge-portal;surface-abs-grade-integral-ds-times-1-plus-0.6-normalized-grade-over-one-minus-normalized;normalized-grade-at-least-0.995-reject;bounded-ccw-nonclosed-3to128|unbuildable-empty;city-road-continuous-points-inside-boundary;intercity-unclipped","cityStructuredClip":"v8-nonarterial-all-exact-boundary-inside-runs;candidate-segment-boundary-intersections;boundary-inclusive;rooted-run-nearest-original-sweep-midpoint-else-inside-run-nearest-midpoint;arterial-uses-legacy-origin-first-exit-clip;final-route-sample-boundary-verify-at-most10m","cityStructuredRoot":"v8-transverse-same-city-surface-strict-internal-xy-intersection;parallel-collinear-endpoint-near-end-reject-epsilon1e-9;nearest-original-sweep-midpoint-then-stable-road-segment-point-pair-tie-order;root-z-actual-terrain-sample;both-old-surface-halves-revalidate-before-noding","cityRootArms":"root-left-right-independent-anchor-direct-or-bounded-astar-finish-and-boundary-check;both-concatenate|one-commit-valid-arm-and-record-other-unreachable|none-reject;assembled-root-route-no-acute-final-gate;preserve-root-xy","citySurfaceNoding":"v8-same-city-nonintercity-surface-only;strict-internal-xy-crossing-with-nonfinite-reject-and-dimensionless-interior-epsilon1e-9|positive-collinear-xy-overlap-line-distance-at-most1e-7;canonical-overlap-endpoints-xy-round-1e-7m-and-z-actual-terrain-sample;all-four-half-edges-or-local-endpoint-replacement-surface-revalidate;stable-road-segment-original-edge-index-descending-and-t-descending-insert-order;not-cross-city-bridge-tunnel-or-general-grade-separation","cityExactSurfaceReuse":"after-same-city-surface-noding-and-common-overlap-endpoint-rewrite;same-city-nonintercity-contiguous-all-surface-normalized-run-only-without-crossing-bridge-or-tunnel;undirected-exact-xyz-bit-elementary-key;arterial-then-local-then-lexical-road-id-owner;partial-overlap-reuse-removes-nonowner-exact-pieces-retains-continuous-chains;single-retained-chain-keeps-parent-id|multiple-retained-chains-child-id-parent-plus-retained-child-first-last-xy-IEEE-bits-and-reuse-purpose-no-ordinal;refresh-sorted-layout-ids;no-reuse-status-output;not-near-or-unvalidated-overlap-reuse","cityAccess":"legacy-v6-only:surface-street-node-short-connect-v1;radius-over-block-times-1.5-ceil-4to12;candidate-distance-0.75to3-block;target-1.7-block;stable-city-seed-node-pair-sort;surface-only-existing-nodes;actual-sampler-direct-or-bounded-astar;complete-portal-no-acute-boundary-containment;access-unreachable-domain-v1","parcelAlgorithm":"identity-bound-v1;v6=legacy-v6-road-core-and-parcels;v8=structured-v8-road-core-and-parcels;v9=structured-v8-road-core-plus-frontage-balanced-v9-parcels;v10=structured-v8-road-core-plus-shape-filled-v10-parcels;v10-vs-v9-selects-parcel-only;no-load-time-upgrade","parcelFace":"shape-filled-v10-simple-single-ring-closed-face;real-ordinary-street-elementary-frontage-only;collinear-ring-simplify;per-edge-inward-offset-max-matching-real-road-half-width-plus-nonnegative-setback-plus-4epsilon-quantization-guard;inset-must-stay-within-source-and-strict-road-clearance;self-cross-reject;concave-ear-clip-then-stable-convex-merge;internal-chords-have-no-offset-and-no-frontage;unsupported-complex-or-hole-face-reject-no-topology-guess","parcelSplit":"shape-filled-v10-long-axis-oriented-bounds-primary-then-stable-face-axis;projection-midline-clip-targets-settings-maxFaceAreaMeters-default22500-not-terminal-hard-limit;shape-context-cut-children-inset-by-4epsilon-per-side-leaving-8epsilon-artificial-nonroad-gap-to-prevent-quantized-shared-edge-positive-overlap;no-distance-or-overlap-gate-relaxation;both-children-area-at-least-settings-minParcelAreaMeters-default36;each-child-needs-longest-continuous-real-inset-street-frontage-at-least-max-10-min-20-widest-road;shape-node-and-recursive-output-hard-gates;pair-atomic-no-single-child-commit;frontage-balanced-real-inset-frontage-cut-fallback;recursive-depth8;at-depth-or-no-valid-cut-shape-valid-parent-may-remain-even-over-max-area;at-depth-or-no-valid-cut-invalid-shape-reject;cut-edge-is-not-frontage","parcelFrontage":"shape-filled-v10-face-first-then-uncovered-frontage-only;closed-valid-inset-faces-fill-before-open-street;real-surface-ordinary-street-run-resampled-at-at-most-min-10-maxSliceLength;two-sided-offset;depth-at-least-blockSize-times-0.18-and-at-least-minShortSide-times-sqrt2-plus1;maxSliceLength-max-requiredStripDimension-plus10-only-when-requiredStripDimension-over42-and-min-42-maxAspectRatio-times-depth-so-minShortSide-override-remains-sliceable;slice-at-least-minShortSide-times-sqrt2-plus1;shape-safe-bounds-and-ratio-hard-gates;source-and-all-road-corridor-boundary-terrain-clear;positive-area-nonoverlap-stable-id-greedy;no-entrance-or-navigation-reachability-claim","legacyParcel":"legacy-v6-undefined-or-explicit-legacy-uses-prior-split-and-centroid-inset-path;structured-v8-uses-convex-offset-and-primary-child-frontage-rule;frontage-balanced-v9-keeps-v8-road-core-face-inset-and-primary-split-plus-stable-frontage-cut-fallback;shape-filled-v10-keeps-v8-road-core-and-uses-simple-ring-inset-concave-decomposition-shape-hard-gates-and-uncovered-frontage-only;shared-invalid-algorithm-fail-closed","parcelGraph":"road-parcels-v4-boundary-highway","parcelIdentity":"boundary-token-sorted-hash-worldSeed-citySeed-cityId;oriented-split-normal-token;frontage-side-and-ordinal;weighted-land-use;id-sort-v3;shape-filled-v10-canonical-ring-ear-clip-first-valid-vertex-order-then-first-pair-convex-merge-loop;decomposed-piece-traversal-order-is-explicit-root-c-pieceIndex-and-affects-stable-id","parcelTerrain":"polygon-touching-cells-dry-finite;adjacent-touching-cell-slope-at-most-settings-maxSlope;grid-at-most257-v1","roadClass":"required-kind-intercity-arterial-local;required-class-street-motorway;intercity-motorway-else-street;all-intercity-motorway-and-city-nonbuildable-roads-forbidden-corridor;centerline-no-intersection-or-containment;clearance-half-width-plus-setback-v1","direction":"heading-dot-at-least-zero;interior-angle-at-least90deg;all-assembled-route-final-gate-v2","limits":"maxGrade-roadWidthMeters-maxBridgeLengthMeters-maxTunnelLengthMeters-v1","elevation":"relative-height-times-elevationScaleMeters-v1","terrain":"canonical-plane-hydrology-fixed-sampling;global-long-axis257;city-long-axis65to257;actual-finite-sampler-step10m;no-sub10m-obstacle-guarantee-v1","portalLookahead":"complete-portal-before-partial-surface-v1;exact-dry-grid-portal-preserved-v1;off-grid-origin-requires-validated-surface-connector-v1;connector-budget-cost-required-v1","bridge":"complete-dry-portal-water-span-v1;linear-deck-3d-length-at-most-maxBridgeLengthMeters;all-water-interior;no-shortcut-or-split-v2","tunnel":"covered-dry-portal-bore;actual-cover-at-least1m;3d-length-at-most-maxTunnelLengthMeters;no-shortcut-or-split;no-water-interior;roadWidth-surface-abutment-v2","shortcut":"surface-run-control-edge-boundaries;candidates-i-to-j-j-at-most-i-plus24-or-last;actual-sampler-water-grade-step-at-most10m;reverse-sparse-dag-heading-compatible-dot-epsilon1e-12;no-accumulated-cost;farthest-reachable-stable-descending;retain-original-if-no-complete-chain;whole-road-stable-branch-unreachable-if-final-acute;bridge-tunnel-excluded-v3","repair":"same-core-segment-splice;10m-grid;at-most8-attempts;min-margin200m-v1","parcelShape":"coordinates-round-decimal6-epsilon1e-6;minimum-oriented-convex-hull-edge-aligned-bounds;settings-maxAspectRatio-finite-at-least1-default4;settings-minShortSideMeters-finite-at-least26-default26;short-side-at-least-minShortSideMeters;long-side-at-most-short-side-times-maxAspectRatio;safe-axis-aligned-square-inside-polygon-width-and-height-at-least-minShortSideMeters;all-partition-nodes-and-emitted-parcels-terrain-boundary-corridor-clear"}';
+export const ROAD_GENERATION_IDENTITY = "chat.worldengine.terrain-roads/v1;rules-sha256=58fc51cfe9986a8da0cc6931c8600cf4c1afbbcda80f58e00038b76f982aec5b";
+/**
+ * 已发布 identity 的精确 allowlist。新算法必须先有冻结的 rules digest，才能加入这里；
+ * 不得以“当前默认值”替换已保存 source 的 identity。
+ */
+export const SUPPORTED_ROAD_GENERATION_IDENTITIES = Object.freeze([
+    LEGACY_V6_IDENTITY,
+    STRUCTURED_V8_IDENTITY,
+    FRONTAGE_BALANCED_V9_IDENTITY,
+    ROAD_GENERATION_IDENTITY,
+]);
+export function roadGenerationAlgorithm(identity) {
+    switch (identity) {
+        case LEGACY_V6_IDENTITY:
+            return "legacy-v6";
+        case STRUCTURED_V8_IDENTITY:
+        case FRONTAGE_BALANCED_V9_IDENTITY:
+        case ROAD_GENERATION_IDENTITY:
+            return "structured-v8";
+    }
+}
+/** 已保存 identity 独立选择 parcel 语义；V9 仍复用已发布 V8 道路 core。 */
+export function roadParcelAlgorithm(identity) {
+    switch (identity) {
+        case LEGACY_V6_IDENTITY:
+            return "legacy-v6";
+        case STRUCTURED_V8_IDENTITY:
+            return "structured-v8";
+        case FRONTAGE_BALANCED_V9_IDENTITY:
+            return "frontage-balanced-v9";
+        case ROAD_GENERATION_IDENTITY:
+            return "shape-filled-v10";
+    }
+}
+/**
+ * 只有已冻结的后继 identity 才能令旧 source 出现显式升级预览入口。
+ * 加载或保存绝不能据此静默升级。
+ */
+export function roadGenerationUpgradeTarget(identity) {
+    return identity === LEGACY_V6_IDENTITY
+        || identity === STRUCTURED_V8_IDENTITY
+        || identity === FRONTAGE_BALANCED_V9_IDENTITY
+        ? ROAD_GENERATION_IDENTITY
+        : undefined;
+}
+export const DEFAULT_ROAD_GENERATION = Object.freeze({
+    profile: ROAD_GENERATION_PROFILE,
+    identity: ROAD_GENERATION_IDENTITY,
+    allowBridges: true,
+    allowTunnels: false,
+    maxBridgeLengthMeters: 300,
+    maxTunnelLengthMeters: 1_000,
+    maxGrade: 0.15,
+    roadWidthMeters: 8,
+    elevationScaleMeters: 3_000,
+});
+const ROAD_GENERATION_KEYS = new Set([
+    "profile",
+    "identity",
+    "allowBridges",
+    "allowTunnels",
+    "maxBridgeLengthMeters",
+    "maxTunnelLengthMeters",
+    "maxGrade",
+    "roadWidthMeters",
+    "elevationScaleMeters",
+]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function boundedNumber(value, field, minimum, maximum) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        throw new TypeError(`${field} 必须是有限数`);
+    if (value < minimum || value > maximum)
+        throw new RangeError(`${field} 必须位于 ${minimum}..${maximum}`);
+    return value;
+}
+function boolean(value, field) {
+    if (typeof value !== "boolean")
+        throw new TypeError(`${field} 必须是 boolean`);
+    return value;
+}
+function supportedIdentity(value) {
+    if (typeof value !== "string" || !SUPPORTED_ROAD_GENERATION_IDENTITIES.includes(value)) {
+        throw new TypeError(`identity 必须为 ${SUPPORTED_ROAD_GENERATION_IDENTITIES.join(" 或 ")}`);
+    }
+    return value;
+}
+/** 严格验证桥隧道路设置，拒绝未知字段并返回不可变 canonical 副本。 */
+export function validateRoadGeneration(input) {
+    if (!isRecord(input))
+        throw new TypeError("RoadGenerationV1 必须是对象");
+    const unknown = Object.keys(input).filter((key) => !ROAD_GENERATION_KEYS.has(key));
+    if (unknown.length > 0)
+        throw new TypeError(`RoadGenerationV1 包含未知字段：${unknown.join(", ")}`);
+    const missing = [...ROAD_GENERATION_KEYS].filter((key) => !Object.hasOwn(input, key));
+    if (missing.length > 0)
+        throw new TypeError(`RoadGenerationV1 缺少字段：${missing.join(", ")}`);
+    if (input.profile !== ROAD_GENERATION_PROFILE)
+        throw new TypeError(`profile 必须为 ${ROAD_GENERATION_PROFILE}`);
+    const identity = supportedIdentity(input.identity);
+    return Object.freeze({
+        profile: ROAD_GENERATION_PROFILE,
+        identity,
+        allowBridges: boolean(input.allowBridges, "allowBridges"),
+        allowTunnels: boolean(input.allowTunnels, "allowTunnels"),
+        maxBridgeLengthMeters: boundedNumber(input.maxBridgeLengthMeters, "maxBridgeLengthMeters", 1, 1_000_000),
+        maxTunnelLengthMeters: boundedNumber(input.maxTunnelLengthMeters, "maxTunnelLengthMeters", 1, 1_000_000),
+        maxGrade: boundedNumber(input.maxGrade, "maxGrade", 0.01, 1),
+        roadWidthMeters: boundedNumber(input.roadWidthMeters, "roadWidthMeters", 3, 40),
+        elevationScaleMeters: boundedNumber(input.elevationScaleMeters, "elevationScaleMeters", 1, 100_000),
+    });
+}