@world-engines/project-host 0.1.0-alpha.0

package/dist/desktop-authoring-runtime.js

@@ -0,0 +1,1602 @@
+import { AuthoringBridgeError, } from "@world-engines/authoring-bridge";
+import { decodeScenarioPartWesp, encodeWesp, sha256Hex } from "@world-engines/project-format";
+import { canonicalJson, projectNeutralArtifactEmbeddingSources } from "@world-engines/scenario-review-snapshot";
+import { normalizeEntityProps, serializeEntityProps } from "@world-engines/authoring-ui/entity-props";
+import { decodeSpatialWorldProtobuf, encodeSpatialWorldProtobuf, } from "@world-engines/spatial-authoring";
+import { validatePlaneGeneration } from "@world-engines/spatial-authoring/plane-generation";
+import { validateRoadGeneration } from "@world-engines/spatial-authoring/road-generation";
+import { SPATIAL_TEMPLATE_PRESETS, validateSpatialTemplateConfiguration, validateSpatialTemplateLibrary, } from "@world-engines/spatial-authoring/spatial-templates";
+import { PROCEDURAL_GENERATOR_IDENTITY, PROCEDURAL_WORLD_PROFILE, validateProceduralWorld, } from "@world-engines/spatial-authoring/procedural-city";
+import { LadybugProjectRuntime, embedLadybugQuery } from "./ladybug-runtime.js";
+import { ProjectTriggerRuntime } from "./trigger-runtime.js";
+import { reduceTmwSceneV1, tmwSceneOperationFromEffect } from "@world-engines/tmw/scene-state";
+import { initialTmwSceneFromMetadata, validateTmwSceneSourceReferencesV1 } from "@world-engines/tmw/scene-author-source";
+import { assertSafeExistingProjectPath, ensureSafeProjectDirectory } from "./safe-project-path.js";
+function canonicalEmbeddingGraph(graph) {
+    return {
+        entities: graph.entities.map((candidate) => ({
+            ...candidate,
+            entity_id: typeof candidate.entity_id === "string" ? candidate.entity_id : candidate.id,
+        })),
+        relations: graph.relations.map((relation) => {
+            const src = typeof relation.from_id === "string" ? relation.from_id : relation.src;
+            const dst = typeof relation.to_id === "string" ? relation.to_id : relation.dst;
+            const kind = relation.kind;
+            return {
+                ...relation,
+                relation_id: typeof relation.relation_id === "string" ? relation.relation_id
+                    : `physical:${String(src)}:${String(kind)}:${String(dst)}`,
+                from_id: src,
+                to_id: dst,
+            };
+        }),
+    };
+}
+/**
+ * 本地 prepare 与正式 review reader 共用的 corpus 文本 seam。
+ */
+export function buildAuthoringRecallCorpus(graph) {
+    return projectNeutralArtifactEmbeddingSources(canonicalEmbeddingGraph(graph));
+}
+const LADYBUG_RECALL_PROJECTION_FORMAT = "projection-v2-scope-batch-digest";
+const WORLD_GET_MAX_LIMIT = 200;
+const WORLD_GET_MAX_RELATIONS_PER_PAGE = 2_000;
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder("utf-8", { fatal: true });
+function fail(message, code = "E_VALIDATION_FAILED") {
+    throw new AuthoringBridgeError(code, message);
+}
+function record(value, label) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        fail(`${label} 必须是 object`);
+    return value;
+}
+function exactKeys(value, expected, label) {
+    const actual = Object.keys(value).sort();
+    const canonical = [...expected].sort();
+    if (actual.length !== canonical.length || actual.some((key, index) => key !== canonical[index])) {
+        fail(`${label} 字段必须严格为：${canonical.join(", ")}`);
+    }
+}
+function stringValue(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        fail(`${label} 必须是非空 string`);
+    return value;
+}
+function canonicalBase64(value, label) {
+    if (typeof value !== "string" || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(value))
+        fail(`${label} 必须是 canonical base64`);
+    const decoded = Buffer.from(value, "base64");
+    if (decoded.toString("base64") !== value)
+        fail(`${label} 必须是 canonical base64`);
+    return value;
+}
+function resourceRefsSection(bytes) {
+    if (bytes.byteLength === 0)
+        return [];
+    let value;
+    try {
+        value = JSON.parse(textDecoder.decode(bytes));
+    }
+    catch {
+        return fail("resource_refs 不是合法 JSON section");
+    }
+    if (!Array.isArray(value))
+        fail("resource_refs 必须是 array");
+    const seen = new Set();
+    return value.map((candidate, index) => {
+        const ref = record(candidate, `resource_refs[${index}]`);
+        exactKeys(ref, ["path", "media_type", "bytes_base64"], `resource_refs[${index}]`);
+        const path = stringValue(ref.path, `resource_refs[${index}].path`);
+        if (seen.has(path))
+            fail("resource_refs.path 不能重复");
+        seen.add(path);
+        return {
+            path,
+            media_type: stringValue(ref.media_type, `resource_refs[${index}].media_type`),
+            bytes_base64: canonicalBase64(ref.bytes_base64, `resource_refs[${index}].bytes_base64`),
+        };
+    });
+}
+function worldSearchScopeId(value) {
+    if (value === undefined)
+        return undefined;
+    const filters = record(value, "world_search.filters");
+    const keys = Object.keys(filters);
+    if (keys.length !== 1 || keys[0] !== "scope_id") {
+        fail("world_search.filters 当前只支持 scope_id 精确过滤");
+    }
+    const scopeId = filters.scope_id;
+    if (typeof scopeId !== "string" || !/^[^\0\r\n]{1,512}$/u.test(scopeId)) {
+        fail("world_search.filters.scope_id 无效");
+    }
+    return scopeId;
+}
+function jsonSection(bytes, fallback, label) {
+    if (bytes.byteLength === 0)
+        return fallback;
+    try {
+        return record(JSON.parse(textDecoder.decode(bytes)), label);
+    }
+    catch {
+        return fail(`${label} 不是合法 JSON section`);
+    }
+}
+function stableJson(value) {
+    return textEncoder.encode(JSON.stringify(value));
+}
+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));
+}
+/** locale 与 UTF-16 surrogate 顺序都不能参与稳定分页；这里显式按 Unicode code point 排序。 */
+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 compareRelation(left, right) {
+    return compareCodepoint(left.src, right.src)
+        || compareCodepoint(left.dst, right.dst)
+        || compareCodepoint(left.kind, right.kind)
+        || compareCodepoint(JSON.stringify(left.props), JSON.stringify(right.props));
+}
+function encodeWorldGetCursor(readback, afterId) {
+    const cursor = {
+        v: 1,
+        project_id: readback.project_id,
+        source_sha256: readback.source_sha256,
+        project_revision: readback.project_revision,
+        after_id: afterId,
+    };
+    return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+}
+function decodeWorldGetCursor(encoded) {
+    if (encoded.length > 16_384 || !/^[A-Za-z0-9_-]+$/u.test(encoded))
+        fail("world_get cursor 无效", "E_SCHEMA_INVALID");
+    let value;
+    try {
+        const bytes = Buffer.from(encoded, "base64url");
+        if (bytes.toString("base64url") !== encoded)
+            fail("world_get cursor 无效", "E_SCHEMA_INVALID");
+        value = JSON.parse(textDecoder.decode(bytes));
+    }
+    catch {
+        return fail("world_get cursor 无效", "E_SCHEMA_INVALID");
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        fail("world_get cursor 无效", "E_SCHEMA_INVALID");
+    const cursor = value;
+    const keys = Object.keys(cursor).sort();
+    if (keys.join("\0") !== ["after_id", "project_id", "project_revision", "source_sha256", "v"].join("\0")
+        || cursor.v !== 1
+        || typeof cursor.project_id !== "string" || cursor.project_id.length === 0
+        || typeof cursor.source_sha256 !== "string" || !/^[a-f0-9]{64}$/u.test(cursor.source_sha256)
+        || !Number.isSafeInteger(cursor.project_revision) || cursor.project_revision < 0
+        || typeof cursor.after_id !== "string" || cursor.after_id.trim().length === 0) {
+        fail("world_get cursor 无效", "E_SCHEMA_INVALID");
+    }
+    return cursor;
+}
+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 decodeScenarioSourceV1(bytes) {
+    // schema_version 是唯一 varint field；其余 ScenarioPart 字段都是 bytes / nested message。
+    let offset = 0;
+    let version = 0;
+    const sections = new Map();
+    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 === 1 && wire === 0) {
+            const next = readVarint(bytes, offset);
+            version = next.value;
+            offset = next.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 = sections.get(field) ?? [];
+        values.push(bytes.slice(offset, end));
+        sections.set(field, values);
+        offset = end;
+    }
+    return { schema_version: version, metadata: first(sections, 2), logical_graph: first(sections, 3), trigger_semantics: first(sections, 4), layout: first(sections, 5), resource_refs: first(sections, 6), prompt_retrieval: first(sections, 7), spatial_world: sections.get(8)?.[0] };
+}
+function encodedField(field, value) { return concat([varint(field * 8 + 2), varint(value.length), value]); }
+function encodeScenarioSourceV1(source) {
+    const fieldsToWrite = [[2, source.metadata], [3, source.logical_graph], [4, source.trigger_semantics], [5, source.layout], [6, source.resource_refs], [7, source.prompt_retrieval]];
+    if (source.spatial_world !== undefined)
+        fieldsToWrite.push([8, source.spatial_world]);
+    return concat([varint(8), varint(source.schema_version), ...fieldsToWrite.filter(([, value]) => value.length > 0).map(([field, value]) => encodedField(field, value))]);
+}
+/** 只替换一个已知 bytes field；其他已知/未知 protobuf field 均保持原始字节和顺序。 */
+function replaceScenarioBytesField(input, wanted, replacement) {
+    const output = [];
+    let offset = 0;
+    let replaced = false;
+    while (offset < input.length) {
+        const start = offset;
+        const tag = readVarint(input, offset);
+        offset = tag.next;
+        const field = Math.floor(tag.value / 8), wire = tag.value % 8;
+        if (wire === 0)
+            offset = readVarint(input, offset).next;
+        else if (wire === 2) {
+            const length = readVarint(input, offset);
+            offset = length.next + length.value;
+            if (offset > input.length)
+                fail("Scenario protobuf length 被截断");
+        }
+        else
+            fail("Scenario protobuf 包含不支持字段");
+        if (field === wanted) {
+            if (wire !== 2 || replaced)
+                fail("Scenario resource_refs field 重复或 wire 无效");
+            replaced = true;
+            if (replacement.byteLength > 0)
+                output.push(encodedField(wanted, replacement));
+        }
+        else
+            output.push(input.slice(start, offset));
+    }
+    if (!replaced && replacement.byteLength > 0)
+        output.push(encodedField(wanted, replacement));
+    return concat(output);
+}
+function spatialIds(spatial) {
+    if (spatial === undefined)
+        return [];
+    const source = fields(spatial);
+    const result = [];
+    for (const field of [7, 8, 9, 10, 11])
+        for (const object of source.get(field) ?? []) {
+            const id = first(fields(object), 1);
+            if (id.length > 0)
+                result.push(textDecoder.decode(id));
+        }
+    return result;
+}
+const SPATIAL_KEY = /^[a-z][a-z0-9-]{0,63}$/;
+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 spatialId(kind, key) { return `spatial:${kind}:${key}`; }
+function planeGeneration(value) {
+    try {
+        return validatePlaneGeneration(value);
+    }
+    catch (error) {
+        return fail(error instanceof Error ? error.message : "PlaneGenerationV1 无效");
+    }
+}
+function roadGeneration(value) {
+    try {
+        return validateRoadGeneration(value);
+    }
+    catch (error) {
+        return fail(error instanceof Error ? error.message : "RoadGenerationV1 无效");
+    }
+}
+function proceduralWorld(value, widthMeters, heightMeters) {
+    try {
+        return validateProceduralWorld(value, { widthMeters, heightMeters });
+    }
+    catch (error) {
+        return fail(error instanceof Error ? error.message : "ProceduralWorldV1 无效");
+    }
+}
+function spatialTemplates(value) {
+    try {
+        return validateSpatialTemplateConfiguration(value);
+    }
+    catch (error) {
+        return fail(error instanceof Error ? error.message : "SpatialTemplateConfigurationV1 无效");
+    }
+}
+function spatialTemplateLibrary(value) {
+    try {
+        return validateSpatialTemplateLibrary(value);
+    }
+    catch (error) {
+        return fail(error instanceof Error ? error.message : "SpatialTemplateLibraryV1 无效");
+    }
+}
+function spatialTemplateKind(value) {
+    if (value === "city" || value === "parcel" || value === "building" || value === "interior")
+        return value;
+    return fail("template kind 必须是 city、parcel、building 或 interior");
+}
+function builtInSpatialTemplatePresets() {
+    return Object.values(SPATIAL_TEMPLATE_PRESETS);
+}
+function effectiveSpatialTemplatePresets(library) {
+    return [...builtInSpatialTemplatePresets(), ...(library?.presets ?? [])];
+}
+function emptyProceduralWorld(worldSeed) {
+    return proceduralWorld({
+        profile: PROCEDURAL_WORLD_PROFILE,
+        identity: PROCEDURAL_GENERATOR_IDENTITY,
+        worldSeed,
+        cities: [],
+    }, 1, 1);
+}
+const decodeSpatialWorld = decodeSpatialWorldProtobuf;
+const encodeSpatialWorld = encodeSpatialWorldProtobuf;
+function spatialWorldReadback(world) {
+    const copy = clone(world);
+    delete copy._wireBase64;
+    delete copy._topologyWireBase64;
+    delete copy._topologyWireKind;
+    for (const object of copy.objects) {
+        delete object._wireField;
+        delete object._wireBase64;
+        delete object._wireSignature;
+        delete object._authorSettings;
+    }
+    return copy;
+}
+function stableSourceModelJson(model) {
+    const { resource_refs_changed: _resourceRefsChanged, ...stable } = model;
+    return stableStructuralJson({ ...stable, spatial_world: model.spatial_world === undefined ? undefined : spatialWorldReadback(model.spatial_world) });
+}
+function clone(value) { return JSON.parse(JSON.stringify(value)); }
+function canonicalProps(value, label) {
+    const props = record(value, label);
+    try {
+        const visit = (candidate) => {
+            if (Array.isArray(candidate)) {
+                candidate.forEach(visit);
+                return;
+            }
+            if (typeof candidate !== "object" || candidate === null)
+                return;
+            const row = candidate;
+            if (row._system_prop_envelope_v1 === true) {
+                // 共享 codec 只用于结构/metadata 校验；返回原 wire，避免把旧 number/boolean/null 标量字符串化。
+                serializeEntityProps(normalizeEntityProps({ value: row }));
+            }
+            Object.values(row).forEach(visit);
+        };
+        visit(props);
+        return clone(props);
+    }
+    catch {
+        return fail(`${label} 不符合 canonical entity props contract`);
+    }
+}
+function canonicalViewAccess(value, label) {
+    if (value !== undefined && value !== "inherit" && value !== "deny" && value !== "read" && value !== "read_write")
+        fail(`${label} 无效`);
+}
+function validateEntityRow(row) {
+    if (!Array.isArray(row.name) || row.name.length === 0 || row.name.some((value) => typeof value !== "string" || value.length === 0))
+        fail("entity.name 必须是非空 string array");
+    canonicalViewAccess(row.view_access, "entity.view_access");
+    if (row.disabled !== undefined && typeof row.disabled !== "boolean")
+        fail("entity.disabled 必须是 boolean");
+}
+function validateRelationRow(row) {
+    canonicalViewAccess(row.view_access, "relation.view_access");
+    if (row.initial_available !== undefined && typeof row.initial_available !== "boolean")
+        fail("relation.initial_available 必须是 boolean");
+    for (const key of ["title", "content"])
+        if (row[key] !== undefined && typeof row[key] !== "string")
+            fail(`relation.${key} 必须是 string`);
+}
+function entityIdentity(row) {
+    return stringValue(row.entity_id ?? row.id, "entity.entity_id");
+}
+function relationIdentity(row) {
+    const src = stringValue(row.from_id ?? row.src, "relation.from_id");
+    const dst = stringValue(row.to_id ?? row.dst, "relation.to_id");
+    return { ...(row.relation_id === undefined ? {} : { relationId: stringValue(row.relation_id, "relation.relation_id") }), src, dst };
+}
+function persistedGraph(graph) {
+    const entities = graph.entities.map((entity) => {
+        const row = { ...entity };
+        if (typeof row.entity_id === "string")
+            delete row.id;
+        return row;
+    });
+    const relations = graph.relations.map((relation) => {
+        const row = { ...relation };
+        if (typeof row.from_id === "string")
+            delete row.src;
+        if (typeof row.to_id === "string")
+            delete row.dst;
+        return row;
+    });
+    return { ...graph, entities, relations };
+}
+function runtimeDefinitions(model) {
+    const current = model.retrieval.runtime_definitions;
+    if (current === undefined) {
+        const created = { triggers: [], trigger_variables_schema: [], cg_defs: [], achievement_defs: [], transaction_defs: [] };
+        model.retrieval.runtime_definitions = created;
+        return created;
+    }
+    return record(current, "prompt_retrieval.runtime_definitions");
+}
+function cgDefinitions(model) {
+    const definitions = runtimeDefinitions(model);
+    if (!Array.isArray(definitions.cg_defs))
+        fail("runtime_definitions.cg_defs 必须是 array");
+    return definitions.cg_defs;
+}
+function validateCgDefinition(model, value) {
+    const row = record(value, "cg definition");
+    const cg_id = stringValue(row.cg_id, "cg.cg_id");
+    const name = stringValue(row.name, "cg.name");
+    const asset_path = stringValue(row.asset_path, "cg.asset_path");
+    const anchor = record(row.anchor, "cg.anchor");
+    if (anchor.attr_path !== undefined)
+        fail("cg.anchor.attr_path 尚不受发布 runtime 支持；不能把子属性绑定降级为根 attr_key");
+    const kind = stringValue(anchor.kind, "cg.anchor.kind");
+    if (kind !== "node" && kind !== "edge" && kind !== "attr")
+        fail("cg.anchor.kind 无效");
+    const id = stringValue(anchor.id, "cg.anchor.id");
+    const attrKey = anchor.attr_key;
+    if ((kind === "attr") !== (typeof attrKey === "string" && attrKey.length > 0))
+        fail("cg.anchor.attr_key 与 kind 不匹配");
+    if (kind === "node" || kind === "attr") {
+        const entity = model.logical_graph.entities.find((item) => item.id === id);
+        if (entity === undefined || (kind === "attr" && !Object.hasOwn(entity.props, attrKey)))
+            fail("cg anchor entity/attr 不存在");
+    }
+    else if (!model.logical_graph.relations.some((item) => item.relation_id === id))
+        fail("cg anchor relation 不存在");
+    const unlock = row.unlock_trigger_id;
+    if (unlock !== undefined && (typeof unlock !== "string" || unlock.length === 0))
+        fail("cg.unlock_trigger_id 无效");
+    return { cg_id, name, asset_path, anchor: { kind, id, ...(kind === "attr" ? { attr_key: attrKey } : {}) }, ...(unlock === undefined ? {} : { unlock_trigger_id: unlock }) };
+}
+function sourceModel(source) {
+    const message = decodeScenarioSourceV1(source);
+    if (message.schema_version !== 1)
+        fail("ScenarioPartSourceV1 schema_version 必须为 1");
+    const metadata = jsonSection(message.metadata, {}, "metadata");
+    const graph = jsonSection(message.logical_graph, { entities: [], relations: [], history: [] }, "logical_graph");
+    const trigger = jsonSection(message.trigger_semantics, { triggers: [] }, "trigger_semantics");
+    const layout = jsonSection(message.layout, { interaction: {}, blueprint: {} }, "layout");
+    const retrieval = jsonSection(message.prompt_retrieval, {}, "prompt_retrieval");
+    const resourceRefs = resourceRefsSection(message.resource_refs);
+    const entities = Array.isArray(graph.entities) ? graph.entities.map((item) => {
+        const row = record(item, "logical_graph.entities[]");
+        return { ...row, id: entityIdentity(row), kind: stringValue(row.kind, "entity.kind"), props: record(row.props ?? {}, "entity.props") };
+    }) : fail("logical_graph.entities 必须是 array");
+    const relations = Array.isArray(graph.relations) ? graph.relations.map((item) => {
+        const row = record(item, "logical_graph.relations[]");
+        const identity = relationIdentity(row);
+        return { ...row, src: identity.src, dst: identity.dst, ...(identity.relationId === undefined ? {} : { relation_id: identity.relationId }), kind: stringValue(row.kind, "relation.kind"), props: record(row.props ?? {}, "relation.props") };
+    }) : fail("logical_graph.relations 必须是 array");
+    const triggers = trigger.triggers === undefined ? undefined : Array.isArray(trigger.triggers) ? trigger.triggers.map((item) => {
+        const row = record(item, "trigger_semantics.triggers[]");
+        const spatialRefs = row.spatial_refs === undefined ? undefined : (Array.isArray(row.spatial_refs) ? row.spatial_refs.map((ref) => stringValue(ref, "trigger.spatial_refs[]")) : fail("trigger.spatial_refs 必须是 array"));
+        return spatialRefs === undefined
+            ? { ...row, id: stringValue(row.id, "trigger.id") }
+            : { ...row, id: stringValue(row.id, "trigger.id"), spatial_refs: spatialRefs };
+    }) : fail("trigger_semantics.triggers 必须是 array");
+    const history = Array.isArray(graph.history) ? graph.history.map((item) => record(item, "logical_graph.history[]")) : fail("logical_graph.history 必须是 array");
+    const spatialWorld = decodeSpatialWorld(message.spatial_world);
+    return { message, model: { metadata, logical_graph: { ...graph, entities, relations, history }, trigger_semantics: triggers === undefined ? trigger : { ...trigger, triggers }, layout: { interaction: record(layout.interaction ?? {}, "layout.interaction"), blueprint: record(layout.blueprint ?? {}, "layout.blueprint") }, retrieval, resource_refs: resourceRefs, resource_refs_changed: false, spatial_ids: spatialWorld?.objects.map((object) => object.id) ?? spatialIds(message.spatial_world), spatial_world: spatialWorld } };
+}
+function encodeModel(message, model) {
+    const next = {
+        ...message,
+        metadata: stableJson(model.metadata),
+        logical_graph: stableJson(persistedGraph(model.logical_graph)),
+        trigger_semantics: stableJson(model.trigger_semantics),
+        layout: stableJson(model.layout),
+        ...(model.resource_refs_changed ? { resource_refs: stableJson(model.resource_refs) } : {}),
+        prompt_retrieval: stableJson(model.retrieval),
+        spatial_world: encodeSpatialWorld(model.spatial_world),
+    };
+    return encodeWesp(encodeScenarioSourceV1(next));
+}
+function mergePatch(previous, patch) {
+    return { ...previous, ...patch };
+}
+/** history 只保留可解释 mutation 摘要，避免把 rawBase64/embedding/整份 source 再复制一遍。 */
+function worldOperationHistorySummary(value) {
+    const operation = record(value, "world operation history");
+    const summary = {};
+    for (const key of ["type", "id", "kind", "src", "dst", "key", "label", "x", "y", "confirmed", "actorId"]) {
+        const field = operation[key];
+        if (field === null || typeof field === "string" || typeof field === "number" || typeof field === "boolean")
+            summary[key] = field;
+    }
+    if (typeof operation.props === "object" && operation.props !== null && !Array.isArray(operation.props)) {
+        const props = operation.props;
+        summary.changed_prop_ids = Object.keys(props).filter((key) => key !== "embedding" && key !== "rawBase64" && key !== "originalBytesBase64").sort();
+        const source = typeof props.source === "object" && props.source !== null && !Array.isArray(props.source)
+            ? props.source
+            : props;
+        const sourceSummary = {};
+        for (const key of ["scopeId", "scope_id", "sourceId", "source_id", "sourceRevision", "source_revision", "sourceSha256", "source_sha256", "byte_sha256", "byteLength", "byte_length", "raw_byte_length", "documentId", "document_id", "operation_id"]) {
+            const field = source[key];
+            if (typeof field === "string" || typeof field === "number")
+                sourceSummary[key] = field;
+        }
+        if (Object.keys(sourceSummary).length > 0)
+            summary.source = sourceSummary;
+    }
+    return summary;
+}
+function validateSpatialReferences(model) {
+    try {
+        validateTmwSceneSourceReferencesV1(initialTmwSceneFromMetadata(model.metadata), sceneSourceReferences(model));
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : "Scene source reference 无效");
+    }
+    const spatial = new Set(model.spatial_ids);
+    for (const trigger of model.trigger_semantics.triggers ?? []) {
+        for (const ref of trigger.spatial_refs ?? [])
+            if (!spatial.has(ref))
+                fail(`Trigger ${trigger.id} 引用了不存在的 spatial_id：${ref}`);
+    }
+    for (const entity of model.logical_graph.entities) {
+        const ref = entity.props.spatial_ref;
+        if (ref !== undefined && (typeof ref !== "string" || !spatial.has(ref)))
+            fail(`Ladybug ${entity.id} 引用了不存在的 spatial_ref`);
+    }
+    const actorId = model.spatial_world?.topology.controlledActorId;
+    if (actorId !== undefined && actorId !== null) {
+        const actor = model.logical_graph.entities.find((entity) => entity.id === actorId);
+        if (actor === undefined)
+            fail(`controlled actor 不存在：${actorId}`);
+        if (actor.kind !== "character" && actor.kind !== "npc")
+            fail(`controlled actor 必须是 character 或 npc：${actorId}`);
+    }
+}
+function sceneSourceReferences(model) {
+    const proceduralCityIds = model.spatial_world?.topology.procedural?.cities.map((city) => city.id) ?? [];
+    return {
+        entityNodeIds: model.logical_graph.entities.map((entity) => entity.id),
+        spatialWorld: model.spatial_world === undefined ? null : {
+            worldId: model.spatial_world.worldId, revision: model.spatial_world.spatialRevision,
+            spatialIds: [...model.spatial_ids, ...proceduralCityIds],
+        },
+    };
+}
+/** 空间写入只推进同一地图中仍存在目标的 version pin；绝不把删除或异世界引用迁移到别处。 */
+function rebindSceneSpatialReference(reference, world, spatialIds) {
+    if (typeof reference !== "object" || reference === null || Array.isArray(reference))
+        return reference;
+    const value = reference;
+    if (value.worldId !== world.worldId || typeof value.spatialId !== "string" || !spatialIds.has(value.spatialId))
+        return reference;
+    return { worldId: world.worldId, sourceRevision: world.spatialRevision, spatialId: value.spatialId };
+}
+/** 同事务内更新已有 Scene 字面引用，避免地图版本已推进而 source 暂时不可读。 */
+function rebindSceneSpatialReferencesAfterSpatialMutation(model) {
+    const world = model.spatial_world;
+    if (world === undefined)
+        return;
+    const spatialIds = new Set(sceneSourceReferences(model).spatialWorld?.spatialIds ?? []);
+    const scene = initialTmwSceneFromMetadata(model.metadata);
+    if (scene?.spatialRef !== null && scene?.spatialRef !== undefined) {
+        const spatialRef = rebindSceneSpatialReference(scene.spatialRef, world, spatialIds);
+        if (spatialRef !== scene.spatialRef)
+            model.metadata.initial_scene = { ...scene, spatialRef };
+    }
+    const document = model.trigger_semantics;
+    for (const effect of Array.isArray(document.effects) ? document.effects : []) {
+        if (typeof effect !== "object" || effect === null || Array.isArray(effect))
+            continue;
+        const node = effect;
+        if (node.capability_id !== "scene.begin" && node.capability_id !== "scene.location.set")
+            continue;
+        if (typeof node.arguments !== "object" || node.arguments === null || Array.isArray(node.arguments))
+            continue;
+        const argumentsValue = node.arguments;
+        const spatialRef = rebindSceneSpatialReference(argumentsValue.spatialRef, world, spatialIds);
+        if (spatialRef !== argumentsValue.spatialRef)
+            node.arguments = { ...argumentsValue, spatialRef };
+    }
+    for (const condition of Array.isArray(document.conditions) ? document.conditions : []) {
+        if (typeof condition !== "object" || condition === null || Array.isArray(condition))
+            continue;
+        const node = condition;
+        if (typeof node.expression !== "object" || node.expression === null || Array.isArray(node.expression))
+            continue;
+        const expression = node.expression;
+        if (expression.op !== "scene_field" || expression.field !== "location")
+            continue;
+        const value = rebindSceneSpatialReference(expression.value, world, spatialIds);
+        if (value !== expression.value)
+            node.expression = { ...expression, value };
+    }
+}
+/** 从同一 WESP 的 Ladybug/Trigger section 重建删除影响；不把 UI projection 当 authority。 */
+function rebuildSpatialReferenceProjection(model) {
+    const world = model.spatial_world;
+    if (world === undefined)
+        return;
+    for (const object of world.objects)
+        object.references = [];
+    const byId = new Map(world.objects.map((object) => [object.id, object]));
+    const add = (spatialId, reference) => {
+        const target = byId.get(spatialId);
+        if (target !== undefined)
+            target.references.push(reference);
+    };
+    const scene = initialTmwSceneFromMetadata(model.metadata);
+    if (scene?.spatialRef !== null && scene?.spatialRef !== undefined) {
+        add(scene.spatialRef.spatialId, { ownerId: scene.sceneId, ownerKind: "scenario", fieldPath: "metadata.initial_scene.spatialRef" });
+    }
+    for (const entity of model.logical_graph.entities) {
+        if (typeof entity.props.spatial_ref === "string")
+            add(entity.props.spatial_ref, { ownerId: entity.id, ownerKind: "ladybug", fieldPath: "attributes.spatial_ref" });
+    }
+    for (const trigger of model.trigger_semantics.triggers ?? []) {
+        for (const spatialId of trigger.spatial_refs ?? [])
+            add(spatialId, { ownerId: trigger.id, ownerKind: "trigger", fieldPath: "spatial_refs" });
+    }
+}
+function removeSpatialReferences(model, spatialId) {
+    for (const entity of model.logical_graph.entities)
+        if (entity.props.spatial_ref === spatialId)
+            delete entity.props.spatial_ref;
+    for (const trigger of model.trigger_semantics.triggers ?? []) {
+        if (trigger.spatial_refs !== undefined)
+            trigger.spatial_refs = trigger.spatial_refs.filter((reference) => reference !== spatialId);
+    }
+}
+export class DesktopAuthoringRuntime {
+    root;
+    port;
+    capabilities;
+    adapter;
+    #triggerRuntime = new ProjectTriggerRuntime();
+    #recallRuntime;
+    #recallSourceSha256;
+    #recallGraphOnly = false;
+    #recallPreparedIdentity;
+    constructor(root, port, capabilities) {
+        this.root = root;
+        this.port = port;
+        this.capabilities = capabilities;
+        const handlers = {
+            world_schema: () => this.#worldSchema(),
+            spatial_template_library: () => this.#spatialTemplateLibrary(),
+            world_search: (ctx) => this.#worldSearch(ctx.call.input),
+            world_get: (ctx) => this.#worldGet(ctx.call.input),
+            world_traverse: (ctx) => this.#worldTraverse(ctx.call.input),
+            world_apply: (ctx) => this.#effect(ctx, "world", (model, input) => this.#applyWorld(model, input, ctx.effect_identity.operation_id)),
+            world_history: (ctx) => this.#history(ctx.call.input),
+            trigger_schema: async () => {
+                const { readback } = await this.#readModel();
+                return {
+                    schema_version: 3,
+                    document: "TMW TriggerDocumentV3",
+                    authority: "scenario/source.wes#trigger_semantics",
+                    project_id: readback.project_id,
+                    project_revision: readback.project_revision,
+                    source_sha256: readback.source_sha256,
+                    empty_document: await this.#triggerRuntime.emptyDocument(),
+                    ...this.#triggerRuntime.authoringCapabilities(),
+                };
+            },
+            trigger_read: (ctx) => this.#triggerRead(ctx.call.input),
+            trigger_apply: (ctx) => this.#effect(ctx, "trigger", (model, input) => this.#applyTrigger(model, input)),
+            trigger_validate: (ctx) => this.#triggerValidate(ctx.call.input),
+            trigger_simulate: (ctx) => this.#triggerSimulate(ctx.call.input),
+            interaction_layout_read: () => this.#layoutRead("interaction"),
+            interaction_layout_apply: (ctx) => this.#effect(ctx, "layout", (model, input) => { model.layout.interaction = mergePatch(model.layout.interaction, record(input.patch, "patch")); }),
+            trigger_blueprint_layout_read: () => this.#layoutRead("blueprint"),
+            trigger_blueprint_layout_apply: (ctx) => this.#effect(ctx, "layout", (model, input) => { model.layout.blueprint = mergePatch(model.layout.blueprint, record(input.patch, "patch")); }),
+            retrieval_config_read: () => this.#readModel().then(({ model }) => clone(model.retrieval)),
+            retrieval_config_apply: (ctx) => this.#effect(ctx, "retrieval", (model, input) => { model.retrieval = mergePatch(model.retrieval, record(input.patch, "patch")); }),
+            retrieval_probe: (ctx) => this.#worldSearch({ query: ctx.call.input.query, mode: "hybrid", limit: ctx.call.input.top_k }),
+        };
+        const names = Object.keys(handlers);
+        if (capabilities.ask_user !== undefined) {
+            handlers.ask_user = (ctx) => capabilities.ask_user(ctx.call.input);
+            names.push("ask_user");
+        }
+        if (capabilities.preview_inspect !== undefined) {
+            handlers.preview_inspect = (ctx) => capabilities.preview_inspect(ctx.call.input);
+            names.push("preview_inspect");
+        }
+        if (capabilities.preview_interact !== undefined) {
+            handlers.preview_interact = (ctx) => capabilities.preview_interact(ctx.call.input);
+            names.push("preview_interact");
+        }
+        this.adapter = { capabilities: names, handlers };
+    }
+    static async open(root, port, capabilities = {}) {
+        const runtime = new DesktopAuthoringRuntime(root, port, capabilities);
+        await runtime.#hydrateFromSource();
+        return runtime;
+    }
+    async close() {
+        await this.#recallRuntime?.close();
+    }
+    /** 固定完整 Node/Edge 读回；派生 graph-only cache 不调用模型，不能成为第二 source authority。 */
+    async readGraphProjectionReadback(request = {}) {
+        const { runtime, model, readback } = await this.#ensureRecallRuntime(true);
+        const graph = await runtime.readGraphSnapshot(request);
+        const current = await this.port.readSourceReadback();
+        if (current.source_sha256 !== readback.source_sha256 || current.project_revision !== readback.project_revision) {
+            fail("图核对期间 source revision 已改变", "E_STALE_PROJECT_REVISION");
+        }
+        const nodeIds = new Set(graph.nodes.map((node) => node.id));
+        const edgeKeys = new Set(graph.edges.map((edge) => JSON.stringify([edge.src, edge.dst, edge.kind])));
+        return {
+            schema_version: 1,
+            source_sha256: readback.source_sha256,
+            project_revision: readback.project_revision,
+            graph,
+            authoring: {
+                metadata: clone(model.metadata),
+                runtime_definitions: clone(runtimeDefinitions(model)),
+                entities: clone(model.logical_graph.entities.filter((entity) => nodeIds.has(entity.id))),
+                relations: clone(model.logical_graph.relations.filter((relation) => edgeKeys.has(JSON.stringify([relation.src, relation.dst, relation.kind])))),
+            },
+        };
+    }
+    async #readModel() {
+        const readback = await this.port.readSourceReadback();
+        const payload = await decodeScenarioPartWesp(readback.source);
+        const parsed = sourceModel(payload);
+        rebuildSpatialReferenceProjection(parsed.model);
+        validateSpatialReferences(parsed.model);
+        return { readback, payload, ...parsed };
+    }
+    async #hydrateFromSource() {
+        await this.#readModel();
+        await this.#recallRuntime?.close();
+        this.#recallRuntime = undefined;
+        this.#recallSourceSha256 = undefined;
+    }
+    async #validateRecallVectors(model, readback, scopeId, port) {
+        const entities = model.logical_graph.entities.filter((entity) => entity.props.retrieval_excluded !== true
+            && !["world_ingestion_batch", "world_ingestion_source_control", "world_document_ingestion_source_control"].includes(entity.kind)
+            && (scopeId === undefined || entity.props.scope_id === scopeId));
+        const corpus = buildAuthoringRecallCorpus(model.logical_graph);
+        const requestedEntities = await Promise.all(corpus.filter((entry) => entities.some((entity) => entity.id === entry.entity_id)).map(async (entry) => Object.freeze({ ...entry, source_text_sha256: await sha256Hex(textEncoder.encode(entry.source_text)) })));
+        const prepared = await this.capabilities.get_prepared_embedding_snapshot?.({
+            project_id: readback.project_id, project_revision: readback.project_revision, source_sha256: readback.source_sha256,
+            ...(scopeId === undefined ? {} : { scope_id: scopeId }),
+            entities: requestedEntities,
+        });
+        if (prepared == null) {
+            throw new AuthoringBridgeError("E_VALIDATION_FAILED", "semantic_recall_corpus_vectors_unverified；请先运行 review prepare", {
+                failure: "E_REVIEW_PREPARE_REQUIRED",
+            });
+        }
+        if (prepared.project_id !== readback.project_id || prepared.project_revision !== readback.project_revision
+            || prepared.source_sha256 !== readback.source_sha256 || !prepared.scope_id || (scopeId !== undefined && scopeId !== prepared.scope_id)) {
+            return fail("semantic_recall_prepared_source_mismatch");
+        }
+        const { source, batch, materialization } = prepared.snapshot;
+        const descriptor = batch.descriptor;
+        if (!source.owner_id || !source.scenario_id || !Number.isSafeInteger(source.source_revision) || source.source_revision < 1
+            || !/^[a-f0-9]{64}$/u.test(source.revision_digest) || descriptor.source_revision !== source.source_revision
+            || descriptor.source_revision_digest !== source.revision_digest || !/^[a-f0-9]{64}$/u.test(descriptor.descriptor_sha256)
+            || descriptor.provider !== port.providerId || descriptor.model !== port.modelId || descriptor.dimension !== port.dimensions
+            || !Number.isSafeInteger(descriptor.dimension) || descriptor.dimension < 1)
+            return fail("semantic_recall_descriptor_mismatch");
+        const canonical = (value) => textEncoder.encode(canonicalJson(value));
+        const descriptorHash = await sha256Hex(canonical(descriptor));
+        if (descriptorHash !== await sha256Hex(canonical(materialization.descriptor)))
+            return fail("semantic_recall_descriptor_mismatch");
+        if (materialization.index_resource.path !== "__derived__/embedding-index-v1.json")
+            return fail("semantic_recall_index_invalid");
+        let index;
+        try {
+            index = record(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(materialization.index_resource.bytes)), "embedding index");
+        }
+        catch {
+            return fail("semantic_recall_index_invalid");
+        }
+        if (index.schema_version !== 1 || !Array.isArray(index.entries)
+            || ["provider", "model", "dimension", "descriptor_sha256", "source_revision", "source_revision_digest"].some((key) => index[key] !== descriptor[key])) {
+            return fail("semantic_recall_index_invalid");
+        }
+        if (entities.length === 0 || (scopeId !== undefined && entities.some((entity) => entity.props.scope_id !== prepared.scope_id))
+            || batch.entries.length !== entities.length || index.entries.length !== entities.length
+            || materialization.vector_by_entity_id.size !== entities.length)
+            return fail("semantic_recall_corpus_incomplete");
+        const entries = new Map(batch.entries.map((entry) => [entry.entity_id, entry]));
+        const requestedById = new Map(requestedEntities.map((entry) => [entry.entity_id, entry]));
+        const indexEntries = new Map(index.entries.map((value) => { const entry = record(value, "embedding index entry"); return [entry.entity_id, entry]; }));
+        if (entries.size !== entities.length || indexEntries.size !== entities.length)
+            return fail("semantic_recall_corpus_incomplete");
+        const vectors = new Map();
+        for (const entity of entities) {
+            const entry = entries.get(entity.id);
+            const indexed = indexEntries.get(entity.id);
+            const vector = materialization.vector_by_entity_id.get(entity.id);
+            const requested = requestedById.get(entity.id);
+            if (requested === undefined)
+                return fail("semantic_recall_vector_binding_mismatch");
+            const textHash = await sha256Hex(textEncoder.encode(requested.source_text));
+            if (entry === undefined || indexed === undefined || vector === undefined || entry.source_kind !== requested.source_kind
+                || indexed.source_kind !== requested.source_kind || entry.source_text_sha256 !== textHash || indexed.source_text_sha256 !== textHash
+                || vector.length !== descriptor.dimension || vector.some((value) => !Number.isFinite(value)) || !vector.some((value) => value !== 0)) {
+                return fail("semantic_recall_vector_binding_mismatch");
+            }
+            const vectorHash = await sha256Hex(canonical([...vector]));
+            if (vectorHash !== indexed.vector_sha256 || vectorHash !== await sha256Hex(canonical([...entry.vector])))
+                return fail("semantic_recall_vector_hash_mismatch");
+            vectors.set(entity.id, Object.freeze([...vector]));
+        }
+        return { sourceSha256: readback.source_sha256, projectRevision: readback.project_revision, scopeId: prepared.scope_id,
+            dimensions: descriptor.dimension, vectors,
+            cacheIdentity: await sha256Hex(canonical({ scope: prepared.scope_id, descriptor, indexHash: await sha256Hex(materialization.index_resource.bytes) })) };
+    }
+    async #ensureRecallRuntime(graphOnly = false, prepared) {
+        const { model, readback } = await this.#readModel();
+        if (prepared !== undefined && (prepared.sourceSha256 !== readback.source_sha256 || prepared.projectRevision !== readback.project_revision))
+            return fail("semantic_recall_prepared_source_mismatch");
+        if (this.#recallRuntime !== undefined && this.#recallSourceSha256 === readback.source_sha256 && this.#recallGraphOnly === graphOnly && this.#recallPreparedIdentity === prepared?.cacheIdentity) {
+            return { runtime: this.#recallRuntime, model, readback };
+        }
+        await this.#recallRuntime?.close();
+        this.#recallRuntime = undefined;
+        this.#recallSourceSha256 = undefined;
+        const projectedEntities = model.logical_graph.entities.filter((entity) => graphOnly || (entity.kind !== "world_ingestion_batch"
+            && entity.kind !== "world_ingestion_source_control"
+            && entity.kind !== "world_document_ingestion_source_control"));
+        const projectedIds = new Set(projectedEntities.map((entity) => entity.id));
+        // 图投影只验证实体/关系；不得为了它构造受 embedding 单条长度约束的文本语料。
+        const corpus = graphOnly
+            ? new Map()
+            : new Map(buildAuthoringRecallCorpus(model.logical_graph).map((entry) => [entry.entity_id, entry.source_text]));
+        const dimensions = graphOnly ? 1 : prepared?.dimensions ?? 1;
+        const embeddingCacheIdentity = graphOnly ? "graph-only-complete-v1" : prepared?.cacheIdentity ?? "keyword-only";
+        const recallDirectory = await ensureSafeProjectDirectory(this.root, `.worldengine/projections/ladybug-recall/${LADYBUG_RECALL_PROJECTION_FORMAT}/${readback.source_sha256}/readonly-corpus-v1/${embeddingCacheIdentity}`);
+        const runtime = await LadybugProjectRuntime.open({
+            directory: recallDirectory,
+            dimensions,
+        });
+        try {
+            await assertSafeExistingProjectPath(this.root, recallDirectory);
+            await runtime.ingest({
+                schemaVersion: 1,
+                batchId: `wesp-${readback.source_sha256}`,
+                source: {
+                    sourceId: "scenario/source.wes",
+                    contentSha256: readback.source_sha256,
+                    extractedAtMs: 0,
+                    extractor: { harness: "worldengine-project-host", contractVersion: "wesp-logical-graph-v1" },
+                },
+                entities: projectedEntities.map((entity) => ({
+                    id: entity.id,
+                    kind: entity.kind,
+                    text: graphOnly ? `${entity.id} ${entity.kind}` : corpus.get(entity.id) ?? `${entity.id} ${entity.kind}`,
+                    props: entity.props,
+                    ...(!graphOnly && prepared?.vectors.has(entity.id)
+                        ? { embedding: prepared.vectors.get(entity.id) }
+                        : {}),
+                })),
+                relations: model.logical_graph.relations.filter((relation) => projectedIds.has(relation.src) && projectedIds.has(relation.dst)),
+            });
+            await assertSafeExistingProjectPath(this.root, recallDirectory);
+        }
+        catch (error) {
+            await runtime.close();
+            if (error instanceof AuthoringBridgeError)
+                throw error;
+            return fail("Ladybug projection hydrate 失败");
+        }
+        this.#recallRuntime = runtime;
+        this.#recallSourceSha256 = readback.source_sha256;
+        this.#recallGraphOnly = graphOnly;
+        this.#recallPreparedIdentity = prepared?.cacheIdentity;
+        return { runtime, model, readback };
+    }
+    async #effect(ctx, section, mutate) {
+        const identity = ctx.effect_identity;
+        const { readback, payload, message, model } = await this.#readModel();
+        if (readback.project_revision !== identity.expected_project_revision)
+            fail(`期望 revision ${identity.expected_project_revision}，当前 ${readback.project_revision}`, "E_STALE_PROJECT_REVISION");
+        const next = clone(model);
+        await mutate(next, ctx.call.input);
+        rebuildSpatialReferenceProjection(next);
+        validateSpatialReferences(next);
+        const operations = Array.isArray(ctx.call.input.operations) ? ctx.call.input.operations : [];
+        const resourceOnly = section === "world" && operations.length > 0 && operations.every((value) => {
+            const type = typeof value === "object" && value !== null && !Array.isArray(value) ? value.type : undefined;
+            return type === "bind_gallery_resource" || type === "unbind_resource_ref";
+        });
+        const source = resourceOnly
+            ? next.resource_refs_changed
+                ? await encodeWesp(replaceScenarioBytesField(payload, 6, stableJson(next.resource_refs)))
+                : readback.source
+            : await encodeModel(message, next);
+        const receipt = await this.port.writeScenario({ ...identity, expected_source_sha256: readback.source_sha256, source });
+        await this.#hydrateFromSource();
+        const written = await this.#readModel();
+        const sourceMatches = resourceOnly
+            ? stableStructuralJson(written.model.resource_refs) === stableStructuralJson(next.resource_refs)
+            : stableSourceModelJson(written.model) === stableSourceModelJson(next);
+        if (written.readback.project_revision !== receipt.next_project_revision
+            || written.model.logical_graph.entities.length !== next.logical_graph.entities.length
+            || !sourceMatches) {
+            fail("WESP write readback 与 typed mutation 不一致", "E_OPERATION_UNCERTAIN");
+        }
+        return { ...receipt, changed_sections: receipt.changed_sections.length === 0 ? [] : [section], readback_verified: true };
+    }
+    async #applyWorld(model, input, operationId) {
+        const operations = input.operations;
+        if (!Array.isArray(operations))
+            fail("operations 必须是 array");
+        const resourceOperationCount = operations.filter((value) => {
+            const type = typeof value === "object" && value !== null && !Array.isArray(value) ? value.type : undefined;
+            return type === "bind_gallery_resource" || type === "unbind_resource_ref";
+        }).length;
+        if (resourceOperationCount > 0 && resourceOperationCount !== operations.length)
+            fail("resource_refs 操作不能与其他 world operation 混合");
+        let spatialMutated = false;
+        for (const [operationIndex, value] of operations.entries()) {
+            const op = record(value, "world operation");
+            const type = stringValue(op.type, "world operation.type");
+            if (type.startsWith("scene.")) {
+                const { type: _type, ...argumentsValue } = op;
+                try {
+                    const operation = tmwSceneOperationFromEffect(type, argumentsValue);
+                    if (operation === null)
+                        fail("无效 Scene operation");
+                    model.metadata.initial_scene = reduceTmwSceneV1(initialTmwSceneFromMetadata(model.metadata), operation, `${operationId}:${operationIndex}`);
+                }
+                catch (error) {
+                    fail(error instanceof Error ? error.message : "Scene operation 无效");
+                }
+            }
+            else if (type === "upsert_entity") {
+                const id = stringValue(op.id, "entity.id");
+                const index = model.logical_graph.entities.findIndex((item) => item.id === id);
+                const entity = { ...(index === -1 ? {} : model.logical_graph.entities[index]), id, kind: stringValue(op.kind, "entity.kind"), props: record(op.props ?? {}, "entity.props") };
+                if (index === -1)
+                    model.logical_graph.entities.push(entity);
+                else
+                    model.logical_graph.entities[index] = entity;
+            }
+            else if (type === "delete_entity") {
+                const id = stringValue(op.id, "entity.id");
+                if (model.spatial_world?.topology.controlledActorId === id)
+                    fail(`必须先解除 controlled actor 绑定：${id}`);
+                model.logical_graph.entities = model.logical_graph.entities.filter((item) => item.id !== id);
+                model.logical_graph.relations = model.logical_graph.relations.filter((item) => item.src !== id && item.dst !== id);
+            }
+            else if (type === "upsert_relation") {
+                const src = stringValue(op.src, "relation.src"), dst = stringValue(op.dst, "relation.dst"), kind = stringValue(op.kind, "relation.kind");
+                const index = model.logical_graph.relations.findIndex((item) => item.src === src && item.dst === dst && item.kind === kind);
+                const relation = { ...(index === -1 ? {} : model.logical_graph.relations[index]), src, dst, kind, props: record(op.props ?? {}, "relation.props") };
+                if (!model.logical_graph.entities.some((item) => item.id === relation.src) || !model.logical_graph.entities.some((item) => item.id === relation.dst))
+                    fail("relation 两端实体必须存在");
+                if (index === -1)
+                    model.logical_graph.relations.push(relation);
+                else
+                    model.logical_graph.relations[index] = relation;
+            }
+            else if (type === "upsert_entity_row") {
+                const row = record(op.entity, "entity row");
+                validateEntityRow(row);
+                const id = entityIdentity(row);
+                const index = model.logical_graph.entities.findIndex((item) => item.id === id);
+                const entity = { ...row, entity_id: id, id, kind: stringValue(row.kind, "entity.kind"), props: canonicalProps(row.props ?? {}, "entity.props") };
+                if (index === -1)
+                    model.logical_graph.entities.push(entity);
+                else
+                    model.logical_graph.entities[index] = entity;
+            }
+            else if (type === "upsert_relation_row") {
+                const row = record(op.relation, "relation row");
+                validateRelationRow(row);
+                const identity = relationIdentity(row);
+                if (identity.relationId === undefined)
+                    fail("relation row 缺少 relation_id");
+                if (!model.logical_graph.entities.some((item) => item.id === identity.src) || !model.logical_graph.entities.some((item) => item.id === identity.dst))
+                    fail("relation 两端实体必须存在");
+                const relation = { ...row, relation_id: identity.relationId, from_id: identity.src, to_id: identity.dst, src: identity.src, dst: identity.dst, kind: stringValue(row.kind, "relation.kind"), props: canonicalProps(row.props ?? {}, "relation.props") };
+                const index = model.logical_graph.relations.findIndex((item) => item.relation_id === identity.relationId
+                    || (item.relation_id === undefined && item.src === identity.src && item.dst === identity.dst && item.kind === relation.kind));
+                if (index === -1)
+                    model.logical_graph.relations.push(relation);
+                else
+                    model.logical_graph.relations[index] = relation;
+            }
+            else if (type === "delete_relation") {
+                const src = stringValue(op.src, "relation.src"), dst = stringValue(op.dst, "relation.dst"), kind = stringValue(op.kind, "relation.kind");
+                model.logical_graph.relations = model.logical_graph.relations.filter((item) => item.src !== src || item.dst !== dst || item.kind !== kind);
+            }
+            else if (type === "upsert_cg") {
+                const cg = validateCgDefinition(model, op.cg ?? op);
+                const definitions = runtimeDefinitions(model);
+                const current = cgDefinitions(model);
+                const index = current.findIndex((item) => item.cg_id === cg.cg_id);
+                definitions.cg_defs = index === -1 ? [...current, cg] : current.map((item, offset) => offset === index ? cg : item);
+            }
+            else if (type === "delete_cg") {
+                const cgId = stringValue(op.cg_id, "cg.cg_id");
+                const definitions = runtimeDefinitions(model);
+                definitions.cg_defs = cgDefinitions(model).filter((item) => item.cg_id !== cgId);
+            }
+            else if (type === "bind_gallery_resource") {
+                exactKeys(op, ["type", "path"], "bind_gallery_resource");
+                const path = stringValue(op.path, "bind_gallery_resource.path");
+                const { readLocalGalleryImage } = await import("./local-gallery.js");
+                const image = await readLocalGalleryImage(this.root, path);
+                const next = {
+                    path: image.asset_path,
+                    media_type: image.mime,
+                    bytes_base64: Buffer.from(image.bytes).toString("base64"),
+                };
+                const index = model.resource_refs.findIndex((entry) => entry.path === next.path);
+                if (index === -1) {
+                    model.resource_refs.push(next);
+                    model.resource_refs_changed = true;
+                }
+                else if (stableStructuralJson(model.resource_refs[index]) !== stableStructuralJson(next)) {
+                    fail("resource_refs 已存在同路径但内容不一致", "E_OPERATION_UNCERTAIN");
+                }
+            }
+            else if (type === "unbind_resource_ref") {
+                exactKeys(op, ["type", "path"], "unbind_resource_ref");
+                const path = stringValue(op.path, "unbind_resource_ref.path");
+                const next = model.resource_refs.filter((entry) => entry.path !== path);
+                if (next.length === model.resource_refs.length)
+                    fail("resource_refs 不存在该 path", "E_REFERENCE_MISSING");
+                model.resource_refs = next;
+                model.resource_refs_changed = true;
+            }
+            else if (type === "spatial_set_generation") {
+                exactKeys(op, ["type", "generation", "confirmed"], "spatial_set_generation");
+                if (typeof op.confirmed !== "boolean")
+                    fail("spatial_set_generation.confirmed 必须是 boolean");
+                const generation = planeGeneration(op.generation);
+                let world = model.spatial_world;
+                if (world === undefined) {
+                    const procedural = proceduralWorld({
+                        profile: PROCEDURAL_WORLD_PROFILE,
+                        identity: PROCEDURAL_GENERATOR_IDENTITY,
+                        worldSeed: generation.seed,
+                        cities: [],
+                    }, generation.widthMeters, generation.heightMeters);
+                    world = { schemaVersion: 1, worldId: "world", spatialRevision: 0, topology: { kind: "freeform", width: generation.widthMeters, height: generation.heightMeters, generation, procedural }, objects: [] };
+                    model.spatial_world = world;
+                    model.spatial_ids = [];
+                }
+                else {
+                    if (world._wireBase64 !== undefined && world._topologyWireKind !== 2)
+                        fail("旧的非平面或未知 spatial topology 不能静默改写为平面地图");
+                    const shrinking = generation.widthMeters < world.topology.width || generation.heightMeters < world.topology.height;
+                    if (shrinking && world.objects.some((object) => object.x > generation.widthMeters || object.y > generation.heightMeters)) {
+                        fail("生成范围缩小会使现有 spatial object 超出边界");
+                    }
+                    if (world.topology.generation !== undefined
+                        && stableStructuralJson(world.topology.generation) !== stableStructuralJson(generation)
+                        && op.confirmed !== true)
+                        fail("替换现有平面生成参数必须显式确认");
+                    const previousProcedural = world.topology.procedural;
+                    if (previousProcedural !== undefined && previousProcedural.cities.length > 0
+                        && world.topology.generation !== undefined
+                        && stableStructuralJson(world.topology.generation) !== stableStructuralJson(generation)) {
+                        proceduralWorld(previousProcedural, generation.widthMeters, generation.heightMeters);
+                        fail("已有程序化城市时不能修改 generation；必须先迁移或清理城市");
+                    }
+                    const procedural = proceduralWorld({
+                        ...(previousProcedural ?? emptyProceduralWorld(generation.seed)),
+                        worldSeed: generation.seed,
+                    }, generation.widthMeters, generation.heightMeters);
+                    world.topology = { ...world.topology, width: generation.widthMeters, height: generation.heightMeters, generation, procedural };
+                }
+            }
+            else if (type === "spatial_set_road_generation") {
+                exactKeys(op, ["type", "roadGeneration", "confirmed"], "spatial_set_road_generation");
+                if (op.confirmed !== true)
+                    fail("保存道路设置必须显式确认");
+                const world = model.spatial_world;
+                if (world?.topology.generation === undefined)
+                    fail("保存道路设置必须先保存有效 generation");
+                world.topology = { ...world.topology, roadGeneration: roadGeneration(op.roadGeneration) };
+            }
+            else if (type === "save_template_definition") {
+                // 定义库与 active selection 分离：保存/更新定义绝不触碰生成器、objects 或已套用模板。
+                exactKeys(op, ["type", "definition"], "save_template_definition");
+                const world = model.spatial_world;
+                if (world === undefined)
+                    fail("保存模板定义必须先保存有效 generation");
+                const definition = record(op.definition, "template definition");
+                const candidateDefinition = spatialTemplateLibrary({ version: 1, presets: [definition] }).presets[0];
+                if (builtInSpatialTemplatePresets().some((preset) => preset.kind === candidateDefinition.kind && preset.id === candidateDefinition.id)) {
+                    fail("内置模板不可覆盖；请使用新的 kind/id 保存自定义模板定义");
+                }
+                const current = world.topology.templateLibrary ?? { version: 1, presets: [] };
+                const existing = current.presets.filter((preset) => preset.kind === candidateDefinition.kind && preset.id === candidateDefinition.id);
+                const highestRevision = existing.reduce((highest, preset) => Math.max(highest, preset.revision), 0);
+                if (candidateDefinition.revision !== highestRevision + 1)
+                    fail("模板定义 revision 必须从 1 开始并对同 kind/id 连续递增");
+                const library = spatialTemplateLibrary({ version: 1, presets: [...current.presets, candidateDefinition] });
+                world.topology = { ...world.topology, templateLibrary: library };
+            }
+            else if (type === "apply_template_selection") {
+                // 仅把经 library 校验的冻结快照写入 active configuration；不会创建、删除或搬移空间几何。
+                exactKeys(op, ["type", "kind", "selection", "confirmedImpact"], "apply_template_selection");
+                if (op.confirmedImpact !== true)
+                    fail("套用模板到现有地图必须显式确认影响");
+                const world = model.spatial_world;
+                if (world === undefined)
+                    fail("套用模板必须先保存有效 generation");
+                const kind = spatialTemplateKind(op.kind);
+                const candidate = spatialTemplates({ version: 1, [kind]: op.selection });
+                const selection = candidate[kind];
+                const matching = effectiveSpatialTemplatePresets(world.topology.templateLibrary).find((preset) => preset.kind === kind && preset.id === selection.presetId && preset.revision === selection.revision);
+                if (matching === undefined || stableStructuralJson(matching.parameters) !== stableStructuralJson(selection.parameters)) {
+                    fail("模板选择必须精确匹配已发布或本世界保存的模板定义");
+                }
+                const previous = world.topology.templates;
+                world.topology = { ...world.topology, templates: spatialTemplates({ ...(previous ?? { version: 1 }), [kind]: selection }) };
+            }
+            else if (type === "spatial_city_create") {
+                exactKeys(op, ["type", "city"], "spatial_city_create");
+                const world = model.spatial_world;
+                if (world?.topology.generation === undefined)
+                    fail("创建程序化城市必须先保存有效 generation");
+                const current = world.topology.procedural ?? emptyProceduralWorld(world.topology.generation.seed);
+                const procedural = proceduralWorld({ ...current, cities: [...current.cities, op.city] }, world.topology.width, world.topology.height);
+                world.topology = { ...world.topology, procedural };
+            }
+            else if (type === "spatial_set_controlled_actor") {
+                exactKeys(op, ["type", "actorId"], "spatial_set_controlled_actor");
+                const world = model.spatial_world;
+                if (world?.topology.generation === undefined)
+                    fail("选择 controlled actor 必须先保存有效 generation");
+                const actorId = controlledActorId(op.actorId, "spatial_set_controlled_actor.actorId");
+                if (actorId === undefined)
+                    fail("spatial_set_controlled_actor.actorId 必须显式为 entity id 或 null");
+                if (actorId !== null) {
+                    const actor = model.logical_graph.entities.find((entity) => entity.id === actorId);
+                    if (actor === undefined)
+                        fail(`controlled actor 不存在：${actorId}`);
+                    if (actor.kind !== "character" && actor.kind !== "npc")
+                        fail(`controlled actor 必须是 character 或 npc：${actorId}`);
+                }
+                world.topology = { ...world.topology, controlledActorId: actorId };
+            }
+            else if (type === "spatial_create") {
+                const world = model.spatial_world;
+                if (world === undefined)
+                    fail("spatial_world 尚未初始化");
+                const key = stringValue(op.key, "spatial key");
+                const kind = spatialKind(op.kind, "spatial kind");
+                const label = stringValue(op.label, "spatial label");
+                if (!SPATIAL_KEY.test(key))
+                    fail("spatial key 必须是稳定 kebab-case");
+                const id = spatialId(kind, key);
+                if (world.objects.some((object) => object.id === id))
+                    fail(`spatial object 已存在：${id}`);
+                const x = finiteCoordinate(op.x, "spatial x");
+                const y = finiteCoordinate(op.y, "spatial y");
+                if (x < 0 || x > world.topology.width || y < 0 || y > world.topology.height)
+                    fail("spatial object 坐标超出 topology");
+                world.objects.push({ id, key, kind, label, x, y, references: [] });
+                model.spatial_ids = world.objects.map((object) => object.id);
+            }
+            else if (type === "spatial_update") {
+                const world = model.spatial_world;
+                if (world === undefined)
+                    fail("spatial_world 尚未初始化");
+                const id = stringValue(op.id, "spatial id");
+                const object = world.objects.find((entry) => entry.id === id);
+                if (object === undefined)
+                    fail(`不存在 spatial object：${id}`);
+                if (op.label !== undefined)
+                    object.label = stringValue(op.label, "spatial label");
+                if (op.x !== undefined)
+                    object.x = finiteCoordinate(op.x, "spatial x");
+                if (op.y !== undefined)
+                    object.y = finiteCoordinate(op.y, "spatial y");
+                if (object.x < 0 || object.x > world.topology.width || object.y < 0 || object.y > world.topology.height)
+                    fail("spatial object 坐标超出 topology");
+            }
+            else if (type === "spatial_remove") {
+                const world = model.spatial_world;
+                if (world === undefined)
+                    fail("spatial_world 尚未初始化");
+                const id = stringValue(op.id, "spatial id");
+                const object = world.objects.find((entry) => entry.id === id);
+                if (object === undefined)
+                    fail(`不存在 spatial object：${id}`);
+                if (object.references.length > 0 && op.confirmed !== true)
+                    fail("存在空间引用影响，必须显式确认删除");
+                if (op.confirmed === true)
+                    removeSpatialReferences(model, id);
+                world.objects = world.objects.filter((entry) => entry.id !== id);
+                model.spatial_ids = world.objects.map((entry) => entry.id);
+            }
+            else
+                fail(`不支持的 world operation：${type}`);
+            if ((type.startsWith("spatial_") || type === "save_template_definition" || type === "apply_template_selection") && model.spatial_world !== undefined) {
+                model.spatial_world.spatialRevision += 1;
+                spatialMutated = true;
+            }
+        }
+        if (spatialMutated)
+            rebindSceneSpatialReferencesAfterSpatialMutation(model);
+        model.logical_graph.history.push({ at: Date.now(), domain: "world", operations: operations.map(worldOperationHistorySummary) });
+    }
+    async #applyTrigger(model, input) {
+        const operations = input.operations;
+        if (!Array.isArray(operations))
+            fail("operations 必须是 array");
+        for (const value of operations) {
+            const op = record(value, "trigger operation");
+            const type = stringValue(op.type, "trigger operation.type");
+            if (type === "replace_document") {
+                const document = record(op.document, "trigger document");
+                const validation = await this.#triggerRuntime.validate(document);
+                if (!validation.ok)
+                    fail(`TMW3 trigger document 无效：${validation.issues.join(",")}`);
+                model.trigger_semantics = clone(document);
+            }
+            else if (type === "upsert") {
+                if (model.trigger_semantics.version === 3)
+                    fail("TMW3 必须使用 replace_document，不能降级为 legacy trigger 格式");
+                const triggers = model.trigger_semantics.triggers ?? [];
+                const trigger = record(op.trigger, "trigger");
+                const spatialRefs = trigger.spatial_refs === undefined ? undefined : (Array.isArray(trigger.spatial_refs) ? trigger.spatial_refs.map((ref) => stringValue(ref, "trigger.spatial_refs[]")) : fail("trigger.spatial_refs 必须是 array"));
+                const next = spatialRefs === undefined
+                    ? { ...trigger, id: stringValue(trigger.id, "trigger.id") }
+                    : { ...trigger, id: stringValue(trigger.id, "trigger.id"), spatial_refs: spatialRefs };
+                const index = triggers.findIndex((item) => item.id === next.id);
+                if (index === -1)
+                    triggers.push(next);
+                else
+                    triggers[index] = next;
+                model.trigger_semantics = { triggers };
+            }
+            else if (type === "delete") {
+                if (model.trigger_semantics.version === 3)
+                    fail("TMW3 必须使用 replace_document，不能降级为 legacy trigger 格式");
+                const id = stringValue(op.id, "trigger.id");
+                model.trigger_semantics = { triggers: (model.trigger_semantics.triggers ?? []).filter((item) => item.id !== id) };
+            }
+            else
+                fail(`不支持的 trigger operation：${type}`);
+        }
+        model.logical_graph.history.push({ at: Date.now(), domain: "trigger", operations: clone(operations) });
+    }
+    async #worldSearch(input) {
+        const query = stringValue(input.query, "query");
+        const requestedMode = stringValue(input.mode, "mode");
+        const mode = requestedMode === "full_text" ? "keyword" : requestedMode;
+        if (mode !== "keyword" && mode !== "semantic" && mode !== "hybrid")
+            fail("world_search mode 无效");
+        const limit = typeof input.limit === "number" ? input.limit : 20;
+        const scopeId = worldSearchScopeId(input.filters);
+        if (query === "spatial:") {
+            if (scopeId !== undefined)
+                fail("spatial: 查询不支持 scope_id filter");
+            const { model, readback } = await this.#readModel();
+            return { mode: requestedMode, results: [], spatial_world: model.spatial_world === undefined ? null : { ...spatialWorldReadback(model.spatial_world), revision: readback.project_revision } };
+        }
+        let prepared;
+        let embeddingPort;
+        if (mode !== "keyword") {
+            embeddingPort = this.capabilities.resolve_ladybug_embedding_port === undefined
+                ? this.capabilities.ladybug_embedding_port
+                : await this.capabilities.resolve_ladybug_embedding_port();
+            if (embeddingPort === undefined)
+                return fail("semantic_recall_query_provider_required", "E_AUTH_REQUIRED");
+            const { model, readback } = await this.#readModel();
+            prepared = await this.#validateRecallVectors(model, readback, scopeId, embeddingPort);
+        }
+        const { runtime, readback } = await this.#ensureRecallRuntime(false, prepared);
+        let hits;
+        // 唯一远端调用只编码本次query，发生失败时不能降级为keyword结果。
+        const queryEmbedding = prepared === undefined ? undefined : await embedLadybugQuery(embeddingPort, query);
+        try {
+            hits = await runtime.recall({ queryText: query, mode, topK: limit, ...(scopeId === undefined ? {} : { scopeId }),
+                ...(queryEmbedding === undefined ? {} : { queryEmbedding }) });
+        }
+        catch (error) {
+            if (error instanceof AuthoringBridgeError)
+                throw error;
+            return fail("Ladybug recall 需要有效的真实索引与 model provider");
+        }
+        if (prepared !== undefined) {
+            const current = await this.port.readSourceReadback();
+            if (current.source_sha256 !== readback.source_sha256 || current.project_revision !== readback.project_revision)
+                return fail("semantic_recall_prepared_source_mismatch");
+        }
+        return {
+            mode: requestedMode,
+            results: hits.map((hit) => ({
+                id: hit.id,
+                kind: hit.kind,
+                props: hit.props,
+                score: hit.score,
+                channels: hit.channels,
+                sources: hit.sources,
+            })),
+        };
+    }
+    async #worldSchema() {
+        const { model, readback } = await this.#readModel();
+        return {
+            schema_version: 1,
+            project_id: readback.project_id,
+            project_revision: readback.project_revision,
+            source_sha256: readback.source_sha256,
+            entities: ["id", "kind", "props"],
+            relations: ["src", "dst", "kind", "props"],
+            entity_listing: { tool: "world_get", order: "id_asc", max_limit: WORLD_GET_MAX_LIMIT, cursor: "source-bound-v1" },
+            entity_kinds: [...new Set(model.logical_graph.entities.map((entity) => entity.kind))].sort(),
+            relation_kinds: [...new Set(model.logical_graph.relations.map((relation) => relation.kind))].sort(),
+            runtime_definitions: { cg_defs: { fields: ["cg_id", "name", "asset_path", "anchor", "unlock_trigger_id"], anchor_kinds: ["node", "edge", "attr"], attr_path_supported: false } },
+            operations: { entity_row: "upsert_entity_row", relation_row: "upsert_relation_row", cg: ["upsert_cg", "delete_cg"], resource_refs: ["bind_gallery_resource", "unbind_resource_ref"] },
+            spatial_templates: {
+                authority: "scenario/source.wes#spatial_world.topology.templates",
+                library_tool: "spatial_template_library",
+                optional_for_legacy_worlds: true,
+                operations: ["save_template_definition", "apply_template_selection"],
+                apply_requires_confirmed_impact: true,
+                persists: "active preset identity and frozen parameters only; no geometry",
+                library_authority: "scenario/source.wes#spatial_world.topology.templateLibrary",
+            },
+            metadata: { keys: Object.keys(model.metadata).sort() },
+            scene: {
+                authority: "scenario/source.wes#metadata.initial_scene",
+                runtime_authority: "RuntimeSavPayloadV3.scene",
+                read_tool: "world_get", apply_tool: "world_apply", schema_version: 1,
+                operations: ["scene.begin", "scene.end", "scene.present.add", "scene.present.remove", "scene.present.replace", "scene.time.set", "scene.location.set", "scene.note.add", "scene.note.remove"],
+                note_lifetimes: ["once", "scene_end"], manuscript_text: "verbatim",
+            },
+        };
+    }
+    async #spatialTemplateLibrary() {
+        const { model, readback } = await this.#readModel();
+        return {
+            version: 1,
+            presets: clone(effectiveSpatialTemplatePresets(model.spatial_world?.topology.templateLibrary)),
+            project_revision: readback.project_revision,
+            source_sha256: readback.source_sha256,
+        };
+    }
+    async #worldGet(input) {
+        const { model, readback } = await this.#readModel();
+        if (Array.isArray(input.ids)) {
+            const ids = input.ids;
+            const relations = input.include_relations === true ? model.logical_graph.relations : [];
+            return {
+                entities: model.logical_graph.entities.filter((entry) => ids.includes(entry.id)),
+                relations: relations.filter((entry) => ids.includes(entry.src) || ids.includes(entry.dst)),
+                metadata: clone(model.metadata),
+                runtime_definitions: clone(runtimeDefinitions(model)),
+            };
+        }
+        const limit = input.limit;
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > WORLD_GET_MAX_LIMIT) {
+            fail(`world_get list limit 必须在 1..${WORLD_GET_MAX_LIMIT}`, "E_SCHEMA_INVALID");
+        }
+        const entities = [...model.logical_graph.entities].sort((left, right) => compareCodepoint(left.id, right.id));
+        if (new Set(entities.map((entity) => entity.id)).size !== entities.length) {
+            fail("world_get list 要求 entity id 唯一");
+        }
+        let start = 0;
+        if (input.cursor !== undefined) {
+            const cursor = decodeWorldGetCursor(input.cursor);
+            if (cursor.project_id !== readback.project_id)
+                fail("world_get cursor 不属于当前 project");
+            if (cursor.source_sha256 !== readback.source_sha256 || cursor.project_revision !== readback.project_revision) {
+                fail("world_get cursor 对应的 source revision 已变化", "E_STALE_PROJECT_REVISION");
+            }
+            const anchor = entities.findIndex((entity) => entity.id === cursor.after_id);
+            if (anchor === -1)
+                fail("world_get cursor anchor 不存在", "E_SCHEMA_INVALID");
+            start = anchor + 1;
+        }
+        const page = entities.slice(start, start + limit);
+        const pageIds = new Set(page.map((entity) => entity.id));
+        const relations = input.include_relations === true
+            ? model.logical_graph.relations
+                .filter((relation) => pageIds.has(relation.src) || pageIds.has(relation.dst))
+                .sort(compareRelation)
+            : [];
+        if (relations.length > WORLD_GET_MAX_RELATIONS_PER_PAGE) {
+            throw new AuthoringBridgeError("E_VALIDATION_FAILED", `world_get 当前页相接 relations 超过 ${WORLD_GET_MAX_RELATIONS_PER_PAGE} 条；请缩小 entity page 或关闭 include_relations`, { failure: "E_WORLD_GET_RELATION_PAGE_TOO_LARGE", max_relations_per_page: WORLD_GET_MAX_RELATIONS_PER_PAGE, actual_relation_count: relations.length });
+        }
+        const hasMore = start + page.length < entities.length;
+        return {
+            entities: page,
+            relations,
+            next_cursor: hasMore && page.length > 0 ? encodeWorldGetCursor(readback, page[page.length - 1].id) : null,
+            total_count: entities.length,
+            order: "id_asc",
+            project_revision: readback.project_revision,
+            source_sha256: readback.source_sha256,
+            metadata: clone(model.metadata),
+            runtime_definitions: clone(runtimeDefinitions(model)),
+        };
+    }
+    async #worldTraverse(input) {
+        const startIds = input.start_ids;
+        const direction = input.direction;
+        const depth = input.depth;
+        const limit = typeof input.limit === "number" ? input.limit : 100;
+        const scopeId = input.scope_id;
+        if (scopeId !== undefined && (typeof scopeId !== "string" || !/^[^\0\r\n]{1,512}$/u.test(scopeId))) {
+            fail("world_traverse.scope_id 无效");
+        }
+        const entityKinds = new Set(Array.isArray(input.entity_kinds) ? input.entity_kinds : []);
+        const relationKinds = Array.isArray(input.relation_kinds) ? input.relation_kinds : [];
+        if (entityKinds.size > 64 || relationKinds.length > 64)
+            fail("world_traverse kind filter 最多 64 项");
+        const { runtime, model } = await this.#ensureRecallRuntime(true);
+        let traversal;
+        try {
+            traversal = await runtime.traverse({
+                startIds,
+                ...(scopeId === undefined ? {} : { scopeId }),
+                direction,
+                maxHops: depth,
+                relationKinds,
+                semanticOnly: input.semantic_only === true,
+                maxPaths: limit,
+                nodeBudget: Math.min(1_000, Math.max(limit, startIds.length)),
+            });
+        }
+        catch (error) {
+            if (error instanceof AuthoringBridgeError)
+                throw error;
+            return fail("Ladybug traverse 请求无效或 readback 不一致");
+        }
+        const visited = new Set(traversal.visitedNodeIds);
+        const edgeKeys = new Set(traversal.paths.flatMap((path) => path.edges)
+            .map((edge) => JSON.stringify([edge.src, edge.dst, edge.kind])));
+        const entities = model.logical_graph.entities
+            .filter((entry) => visited.has(entry.id) && (entityKinds.size === 0 || entityKinds.has(entry.kind)))
+            .slice(0, limit);
+        const relations = model.logical_graph.relations
+            .filter((entry) => edgeKeys.has(JSON.stringify([entry.src, entry.dst, entry.kind])))
+            .slice(0, limit);
+        const evidenceByIdentity = new Map();
+        for (const edge of traversal.paths.flatMap((path) => path.edges)) {
+            for (const source of edge.sources)
+                evidenceByIdentity.set(JSON.stringify(source), source);
+        }
+        return {
+            entities,
+            relations,
+            paths: traversal.paths,
+            evidence: [...evidenceByIdentity.values()],
+            visited_node_ids: traversal.visitedNodeIds,
+            truncated: traversal.truncated,
+        };
+    }
+    async #history(input) { const { model } = await this.#readModel(); const ids = new Set(input.target_ids); const limit = typeof input.limit === "number" ? input.limit : 50; return { entries: model.logical_graph.history.filter((entry) => JSON.stringify(entry).split("\"").some((value) => ids.has(value))).slice(-limit) }; }
+    async #triggerRead(input) {
+        const { model, readback } = await this.#readModel();
+        const ids = Array.isArray(input.trigger_ids) ? new Set(input.trigger_ids) : undefined;
+        const legacy = model.trigger_semantics.triggers;
+        return {
+            project_id: readback.project_id,
+            project_revision: readback.project_revision,
+            source_sha256: readback.source_sha256,
+            document: clone(model.trigger_semantics),
+            ...(legacy === undefined ? {} : { triggers: legacy.filter((entry) => ids === undefined || ids.has(entry.id)) }),
+        };
+    }
+    async #triggerValidate(input) {
+        const { model } = await this.#readModel();
+        const candidate = input.candidate_document === undefined ? model.trigger_semantics : record(input.candidate_document, "candidate_document");
+        return this.#triggerRuntime.validate(candidate);
+    }
+    async #triggerSimulate(input) {
+        const { model } = await this.#readModel();
+        const event = record(input.event, "event");
+        const supplied = record(input.state ?? {}, "state");
+        const state = {
+            entities: Object.fromEntries(model.logical_graph.entities.map((entity) => [entity.id, clone(entity.props)])),
+            ...supplied,
+            scene: supplied.scene === undefined ? initialTmwSceneFromMetadata(model.metadata) : supplied.scene,
+            // 试玩可以修改候选 state，但不能伪造存在性与地图 revision 的 source authority。
+            scene_source_references: sceneSourceReferences(model),
+        };
+        return this.#triggerRuntime.execute({
+            document: model.trigger_semantics,
+            event: {
+                type: stringValue(event.type, "event.type"),
+                ...(event.id === undefined ? {} : { id: stringValue(event.id, "event.id") }),
+                payload: record(event.payload ?? {}, "event.payload"),
+            },
+            state: state,
+        });
+    }
+    async #layoutRead(kind) { const { model } = await this.#readModel(); return clone(model.layout[kind]); }
+}