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

package/dist/transfer.js

@@ -0,0 +1,273 @@
+import { createHash } from "node:crypto";
+import { lstat, open, readFile, readdir, rename } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { AuthoringBridgeError, validateAuthoringEffectIdentity } from "@world-engines/authoring-bridge";
+import { validateLocalAuthorProjectManifest } from "@world-engines/project-format";
+import { assertSafeExistingProjectPath, assertSafeProjectParent, ensureSafeProjectDirectory, safeProjectPath } from "./safe-project-path.js";
+function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function jsonDigest(value) {
+    return sha256Hex(new TextEncoder().encode(JSON.stringify(value)));
+}
+const VIEW_TOOLCHAIN_DIRECTORY_NAMES = new Set(["node_modules", "dist", ".vite"]);
+function comparePath(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function isNotFound(error) {
+    return error.code === "ENOENT";
+}
+async function atomicWriteJson(root, path, stagingRoot, value) {
+    await assertSafeExistingProjectPath(root, stagingRoot);
+    await assertSafeProjectParent(root, path);
+    const bytes = new TextEncoder().encode(`${JSON.stringify(value, null, 2)}\n`);
+    const temporaryPath = join(stagingRoot, `transfer-${sha256Hex(bytes)}.tmp`);
+    await assertSafeProjectParent(root, temporaryPath);
+    const handle = await open(temporaryPath, "wx");
+    try {
+        await handle.writeFile(bytes);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await assertSafeProjectParent(root, path);
+    await rename(temporaryPath, path);
+    await assertSafeExistingProjectPath(root, path);
+}
+async function readManifest(root) {
+    try {
+        const path = await safeProjectPath(root, "worldengine.project.json");
+        return validateLocalAuthorProjectManifest(JSON.parse(await readFile(await assertSafeExistingProjectPath(root, path), "utf8")));
+    }
+    catch (error) {
+        if (error instanceof AuthoringBridgeError)
+            throw error;
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "worldengine.project.json 无效", { cause: error instanceof Error ? error.message : String(error) });
+    }
+}
+async function collectAuthorityFiles(root, directory, entries, excludedDirectoryNames) {
+    const canonicalDirectory = await assertSafeExistingProjectPath(root, directory);
+    const children = await readdir(canonicalDirectory, { withFileTypes: true });
+    children.sort((left, right) => comparePath(left.name, right.name));
+    for (const child of children) {
+        if (excludedDirectoryNames?.has(child.name))
+            continue;
+        const path = join(canonicalDirectory, child.name);
+        const info = await lstat(path);
+        if (info.isSymbolicLink()) {
+            throw new AuthoringBridgeError("E_PATH_OUTSIDE_PROJECT", `拒绝符号链接、junction 或 reparse point：${path}`);
+        }
+        if (info.isDirectory()) {
+            await collectAuthorityFiles(root, path, entries, excludedDirectoryNames);
+            continue;
+        }
+        if (!info.isFile())
+            continue;
+        const canonical = await assertSafeExistingProjectPath(root, path);
+        const bytes = new Uint8Array(await readFile(canonical));
+        entries.push({
+            project_relative_path: relative(root, canonical).replaceAll("\\", "/"),
+            sha256: sha256Hex(bytes),
+            bytes: bytes.byteLength,
+        });
+    }
+}
+/**
+ * 只枚举 manifest、Scenario Part 与 View Part；toolchain、认证态、缓存、日志、staging 和 operation ledger 不属于可传输 authority。
+ */
+export async function buildLocalProjectTransferInventory(root, expectedProjectRevision) {
+    const canonicalRoot = await assertSafeExistingProjectPath(root, root);
+    const manifest = await readManifest(canonicalRoot);
+    if (expectedProjectRevision !== undefined && expectedProjectRevision !== manifest.project_revision) {
+        throw new AuthoringBridgeError("E_STALE_PROJECT_REVISION", `期望 revision ${expectedProjectRevision}，当前 ${manifest.project_revision}`);
+    }
+    const manifestPath = await safeProjectPath(canonicalRoot, "worldengine.project.json");
+    const canonicalManifestPath = await assertSafeExistingProjectPath(canonicalRoot, manifestPath);
+    const manifestBytes = new Uint8Array(await readFile(canonicalManifestPath));
+    const entries = [{
+            project_relative_path: "worldengine.project.json",
+            sha256: sha256Hex(manifestBytes),
+            bytes: manifestBytes.byteLength,
+        }];
+    // Scenario 的所有普通文件都是 source authority；只有 View 会承载本地 toolchain 目录。
+    await collectAuthorityFiles(canonicalRoot, join(canonicalRoot, "scenario"), entries);
+    await collectAuthorityFiles(canonicalRoot, join(canonicalRoot, "view"), entries, VIEW_TOOLCHAIN_DIRECTORY_NAMES);
+    entries.sort((left, right) => comparePath(left.project_relative_path, right.project_relative_path));
+    return {
+        schema_version: 1,
+        project_id: manifest.project_id,
+        project_revision: manifest.project_revision,
+        entries,
+    };
+}
+async function canonicalInventory(root, manifest, request) {
+    if (request.inventory.schema_version !== 1 || request.inventory.project_id !== manifest.project_id) {
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "transfer inventory project_id 必须匹配本地 manifest");
+    }
+    if (request.expected_project_revision !== manifest.project_revision) {
+        throw new AuthoringBridgeError("E_STALE_PROJECT_REVISION", `期望 revision ${request.expected_project_revision}，当前 ${manifest.project_revision}`);
+    }
+    if (!Array.isArray(request.inventory.entries)) {
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "transfer inventory entries 必须为数组");
+    }
+    // 请求中的 inventory 不是 authority，但仍拒绝其携带的越界路径，避免将未受信任输入悄悄接受为有效 transfer 请求。
+    await Promise.all(request.inventory.entries.map((entry) => safeProjectPath(root, entry.project_relative_path)));
+    const local = await buildLocalProjectTransferInventory(root, manifest.project_revision);
+    return { schema_version: 1, project_id: local.project_id, entries: local.entries };
+}
+function assertVerifiedReceipt(receipt, operationId) {
+    if (receipt.operation_id !== operationId || !receipt.remote_transfer_id || !receipt.readback_verified) {
+        throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "remote transfer 未返回权威读回回执");
+    }
+}
+function statusFailure(error) {
+    return new AuthoringBridgeError(error instanceof AuthoringBridgeError ? error.code : "E_VALIDATION_FAILED", "本地同步状态不可用");
+}
+/** 本地 Project 与真实远端 adapter 之间的 fail-closed 边界；不包含 MCP 或网络 fallback。 */
+export class ProjectTransferCoordinator {
+    root;
+    #remoteAdapter;
+    constructor(root, options) {
+        this.root = root;
+        this.#remoteAdapter = options.remote_adapter;
+    }
+    static async open(root, options = {}) {
+        return new ProjectTransferCoordinator(await assertSafeExistingProjectPath(root, root), options);
+    }
+    async availability() {
+        if (this.#remoteAdapter === undefined)
+            return { state: "unavailable", detail: "未配置真实 remote transfer adapter" };
+        if ((await this.#remoteAdapter.authState()) === "signed_out")
+            return { state: "signed_out", detail: "当前 identity 未登录" };
+        return { state: "ready", detail: "已认证的 remote transfer adapter 可用" };
+    }
+    async inventory() {
+        return buildLocalProjectTransferInventory(this.root);
+    }
+    async status() {
+        try {
+            const inventory = await this.inventory();
+            const remoteAdapter = await this.availability();
+            const operationsPath = await safeProjectPath(this.root, ".worldengine/operations");
+            let pendingDurableLedgerCount = 0;
+            try {
+                const canonicalOperationsPath = await assertSafeExistingProjectPath(this.root, operationsPath);
+                const operations = await readdir(canonicalOperationsPath, { withFileTypes: true });
+                for (const operation of operations) {
+                    if (!operation.name.startsWith("transfer-") || !operation.name.endsWith(".json"))
+                        continue;
+                    const path = join(canonicalOperationsPath, operation.name);
+                    const info = await lstat(path);
+                    if (info.isSymbolicLink()) {
+                        throw new AuthoringBridgeError("E_PATH_OUTSIDE_PROJECT", "transfer operation ledger 路径无效");
+                    }
+                    if (!info.isFile()) {
+                        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "transfer operation ledger 不是普通文件");
+                    }
+                    const ledger = JSON.parse(await readFile(await assertSafeExistingProjectPath(this.root, path), "utf8"));
+                    if (ledger.execution_state === "prepared" || ledger.execution_state === "in_flight")
+                        pendingDurableLedgerCount += 1;
+                    else if (ledger.execution_state !== "completed") {
+                        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "transfer operation ledger 状态无效");
+                    }
+                }
+            }
+            catch (error) {
+                if (!isNotFound(error))
+                    throw error;
+            }
+            return {
+                schema_version: 1,
+                project_id: inventory.project_id,
+                project_revision: inventory.project_revision,
+                inventory_digest: jsonDigest({ schema_version: inventory.schema_version, project_id: inventory.project_id, entries: inventory.entries }),
+                inventory_entry_count: inventory.entries.length,
+                pending_durable_ledger_count: pendingDurableLedgerCount,
+                auth_state: remoteAdapter.state === "ready" ? "authenticated" : remoteAdapter.state,
+                remote_adapter: remoteAdapter,
+            };
+        }
+        catch (error) {
+            throw statusFailure(error);
+        }
+    }
+    async prepare(request) {
+        validateAuthoringEffectIdentity(request);
+        const requestDigest = jsonDigest(request);
+        const operationKey = sha256Hex(new TextEncoder().encode(request.operation_id));
+        await ensureSafeProjectDirectory(this.root, ".worldengine/operations");
+        await ensureSafeProjectDirectory(this.root, ".worldengine/staging");
+        await ensureSafeProjectDirectory(this.root, ".worldengine/preimages");
+        const ledgerPath = await safeProjectPath(this.root, `.worldengine/operations/transfer-${operationKey}.json`);
+        try {
+            const ledger = JSON.parse(await readFile(await assertSafeExistingProjectPath(this.root, ledgerPath), "utf8"));
+            if (ledger.request_digest !== requestDigest)
+                throw new AuthoringBridgeError("E_OPERATION_ID_CONFLICT", "同一 transfer operation_id 使用了不同请求");
+            return ledger.plan;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        const manifest = await readManifest(this.root);
+        const inventory = await canonicalInventory(this.root, manifest, request);
+        const stagingPath = await safeProjectPath(this.root, `.worldengine/staging/transfer-${operationKey}`);
+        const preimagePath = await safeProjectPath(this.root, `.worldengine/preimages/transfer-${operationKey}.json`);
+        const plan = {
+            schema_version: 1,
+            operation_id: request.operation_id,
+            request_digest: requestDigest,
+            plan_digest: jsonDigest({ request_digest: requestDigest, manifest_project_revision: manifest.project_revision, inventory }),
+            inventory,
+            staging_path: stagingPath,
+            preimage_path: preimagePath,
+        };
+        await ensureSafeProjectDirectory(this.root, `.worldengine/staging/transfer-${operationKey}`);
+        await atomicWriteJson(this.root, preimagePath, await safeProjectPath(this.root, ".worldengine/staging"), plan);
+        const ledger = { schema_version: 1, request_digest: requestDigest, plan, execution_state: "prepared" };
+        await atomicWriteJson(this.root, ledgerPath, await safeProjectPath(this.root, ".worldengine/staging"), ledger);
+        return plan;
+    }
+    async execute(plan, confirmation) {
+        if (confirmation?.operation_id !== plan.operation_id || confirmation.plan_digest !== plan.plan_digest) {
+            throw new AuthoringBridgeError("E_CONFIRMATION_REQUIRED", "transfer 需要匹配当前计划的明确确认");
+        }
+        const availability = await this.availability();
+        if (availability.state !== "ready")
+            throw new AuthoringBridgeError("E_AUTH_REQUIRED", availability.detail, { state: availability.state });
+        const operationKey = sha256Hex(new TextEncoder().encode(plan.operation_id));
+        const ledgerPath = await safeProjectPath(this.root, `.worldengine/operations/transfer-${operationKey}.json`);
+        const ledger = JSON.parse(await readFile(await assertSafeExistingProjectPath(this.root, ledgerPath), "utf8"));
+        if (ledger.plan.plan_digest !== plan.plan_digest || ledger.plan.request_digest !== plan.request_digest) {
+            throw new AuthoringBridgeError("E_OPERATION_ID_CONFLICT", "transfer 计划与 operation ledger 不一致");
+        }
+        if (ledger.receipt !== undefined)
+            return ledger.receipt;
+        const stagingRoot = await safeProjectPath(this.root, ".worldengine/staging");
+        const inFlight = { ...ledger, execution_state: "in_flight" };
+        await atomicWriteJson(this.root, ledgerPath, stagingRoot, inFlight);
+        const reconciled = await this.#remoteAdapter.reconcile(plan.operation_id);
+        if (reconciled.state === "completed") {
+            assertVerifiedReceipt(reconciled.receipt, plan.operation_id);
+            await atomicWriteJson(this.root, ledgerPath, stagingRoot, { ...inFlight, execution_state: "completed", receipt: reconciled.receipt });
+            return reconciled.receipt;
+        }
+        const receipt = await this.#remoteAdapter.execute(inFlight.plan);
+        assertVerifiedReceipt(receipt, plan.operation_id);
+        await atomicWriteJson(this.root, ledgerPath, stagingRoot, { ...inFlight, execution_state: "completed", receipt });
+        return receipt;
+    }
+    async reconcile(operationId) {
+        if (typeof operationId !== "string" || operationId.trim() === "")
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "operation_id 不能为空");
+        const availability = await this.availability();
+        if (availability.state !== "ready")
+            return availability;
+        const result = await this.#remoteAdapter.reconcile(operationId);
+        if (result.state === "not_found")
+            return result;
+        assertVerifiedReceipt(result.receipt, operationId);
+        return result;
+    }
+}

package/dist/trigger-runtime.d.ts

@@ -0,0 +1,121 @@
+import { type ExecuteTmw3AuthoringOutcome } from "@world-engines/tmw/authoring-runtime";
+import { type TmwJsonValue } from "@world-engines/tmw/runtime-trace";
+import { type TriggerDocumentV3 } from "@world-engines/tmw";
+/** ProjectHost 的受控试玩 state executor；不暴露 Ladybug Connection 或任意 statement。 */
+export declare class ProjectTriggerRuntime {
+    #private;
+    authoringCapabilities(): {
+        capability_registry: import("@world-engines/tmw").CanonicalTmwCapabilityRegistryV3;
+        local_effect_capabilities: ({
+            capability_id: string;
+            argument_schema: {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: Record<string, unknown>;
+            } | {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: Record<string, unknown>;
+            } | {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: Record<string, unknown>;
+            } | {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: Record<string, unknown>;
+            } | {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: Record<string, unknown>;
+            } | {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: Record<string, unknown>;
+            } | {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: Record<string, unknown>;
+            } | {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: Record<string, unknown>;
+            } | {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: Record<string, unknown>;
+            } | {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: Record<string, unknown>;
+            } | {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: Record<string, unknown>;
+            };
+        } | {
+            capability_id: string;
+            argument_schema: Readonly<{
+                type: "object";
+                additionalProperties: false;
+                properties: Record<string, unknown>;
+                required: string[];
+            }> | Readonly<{
+                type: "object";
+                additionalProperties: false;
+                properties: Record<string, unknown>;
+                required: string[];
+            }> | Readonly<{
+                type: "object";
+                additionalProperties: false;
+                properties: Record<string, unknown>;
+                required: string[];
+            }> | Readonly<{
+                type: "object";
+                additionalProperties: false;
+                properties: Record<string, unknown>;
+                required: string[];
+            }> | Readonly<{
+                type: "object";
+                additionalProperties: false;
+                properties: Record<string, unknown>;
+                required: string[];
+            }>;
+        } | {
+            capability_id: string;
+            argument_schema: Readonly<Record<string, unknown>>;
+        } | {
+            capability_id: string;
+            argument_schema: import("@world-engines/tmw").TmwJsonValue;
+        })[];
+    };
+    /** GUI/Agent 新建 trigger 时的合法空白候选；只返回值，不修改 source。 */
+    emptyDocument(): Promise<TriggerDocumentV3>;
+    validate(document: unknown): Promise<Readonly<{
+        ok: boolean;
+        issues: readonly string[];
+        document_sha256?: string;
+        plan_sha256?: string;
+    }>>;
+    execute(input: Readonly<{
+        document: unknown;
+        event: Readonly<{
+            type: string;
+            payload?: Readonly<Record<string, TmwJsonValue>>;
+            id?: string;
+        }>;
+        state?: TmwJsonValue;
+        semantic_predicates?: Readonly<Record<string, "true" | "false" | "unknown">>;
+    }>): Promise<ExecuteTmw3AuthoringOutcome>;
+}

package/dist/trigger-runtime.js

@@ -0,0 +1,153 @@
+import { executeTmw3Authoring, validateTmw3Authoring, } from "@world-engines/tmw/authoring-runtime";
+import { canonicalTmwJson, canonicalTmwJsonValue, tmwSha256Hex, } from "@world-engines/tmw/runtime-trace";
+import { getCanonicalTmwCapabilityRegistryV3, runtimeContractHashV3, TMW_EVENT_CAPABILITY_ARGUMENT_SCHEMAS, } from "@world-engines/tmw";
+import { beginTmwBuilder } from "@world-engines/tmw/builder";
+import { canonicalTmwSceneStateV1, reduceTmwSceneV1, tmwSceneOperationFromEffect } from "@world-engines/tmw/scene-state";
+import { validateTmwSceneSourceReferencesV1 } from "@world-engines/tmw/scene-author-source";
+import { initialTmwGameplayStateFromWorldV1, persistentTmwGameplayStateV1, reduceTmwGameplayEffectV1, prepareTmwGameplayEffectsV1, TMW_GAMEPLAY_CAPABILITY_ARGUMENT_SCHEMAS } from "@world-engines/tmw/gameplay-state";
+function object(value, label) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`tmw_authoring_${label}_object_required`);
+    }
+    return structuredClone(value);
+}
+function nonEmptyStringArray(value, label) {
+    if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== "string" || item.length === 0)) {
+        throw new Error(`tmw_authoring_${label}_string_array_required`);
+    }
+    return [...value];
+}
+function entityId(effect) {
+    if (effect.selector?.op !== "entity_id")
+        throw new Error("tmw_authoring_entity_id_selector_required");
+    return effect.selector.entity_id;
+}
+function writePath(target, path, value) {
+    let cursor = target;
+    for (const segment of path.slice(0, -1)) {
+        const current = cursor[segment];
+        const next = current === undefined ? {} : object(current, "attribute_path");
+        cursor[segment] = next;
+        cursor = next;
+    }
+    cursor[path[path.length - 1]] = canonicalTmwJsonValue(value, "authoring_attribute_value");
+}
+/** 既有 world effect 的本地适配器；Scene 注册与语义 hash authority 来自 TMW 核心。 */
+const AUTHORING_EFFECT_HANDLERS = Object.freeze({
+    "world.set_attribute": {
+        argument_schema: { type: "object", required: ["path"], properties: { path: { type: "array", minItems: 1, items: { type: "string", minLength: 1 } }, value: {} } },
+        apply: (entities, _emittedEvents, effect) => {
+            const id = entityId(effect);
+            const argumentsObject = object(effect.input, "set_attribute_arguments");
+            const path = nonEmptyStringArray(argumentsObject.path, "set_attribute_path");
+            const entity = object(entities[id] ?? {}, "entity");
+            writePath(entity, path, argumentsObject.value ?? null);
+            entities[id] = entity;
+        },
+    },
+    "world.emit_event": {
+        argument_schema: { type: "object" },
+        apply: (_entities, emittedEvents, effect) => { emittedEvents.push(canonicalTmwJsonValue(effect.input, "emitted_event")); },
+    },
+});
+/** ProjectHost 的受控试玩 state executor；不暴露 Ladybug Connection 或任意 statement。 */
+export class ProjectTriggerRuntime {
+    authoringCapabilities() {
+        return {
+            capability_registry: getCanonicalTmwCapabilityRegistryV3(),
+            local_effect_capabilities: [...Object.entries(TMW_GAMEPLAY_CAPABILITY_ARGUMENT_SCHEMAS).map(([capability_id, argument_schema]) => ({ capability_id, argument_schema })), ...Object.entries(TMW_EVENT_CAPABILITY_ARGUMENT_SCHEMAS).map(([capability_id, argument_schema]) => ({ capability_id, argument_schema })), ...Object.entries(AUTHORING_EFFECT_HANDLERS).map(([capability_id, handler]) => ({
+                    capability_id,
+                    argument_schema: structuredClone(handler.argument_schema),
+                })), ...getCanonicalTmwCapabilityRegistryV3().capabilities.filter((item) => item.capability_id.startsWith("scene.")).map((item) => ({ capability_id: item.capability_id, argument_schema: structuredClone(item.argument_schema) }))],
+        };
+    }
+    #effectPort = {
+        stage: async (input) => {
+            const state = object(input.state, "state");
+            const entities = object(state.entities ?? {}, "state_entities");
+            const emittedEvents = Array.isArray(state.emitted_events)
+                ? [...state.emitted_events]
+                : [];
+            state.entities = entities;
+            state.emitted_events = emittedEvents;
+            let gameplay = initialTmwGameplayStateFromWorldV1(state);
+            let gameplayTouched = state.gameplayState !== undefined;
+            for (const plan of input.plans) {
+                if (plan.status !== "ready")
+                    continue;
+                for (const effect of plan.effects) {
+                    const guarded = prepareTmwGameplayEffectsV1(gameplay, [effect]);
+                    if (guarded.effects.length === 0)
+                        continue;
+                    const gameplayNext = reduceTmwGameplayEffectV1(gameplay, effect.capabilityId, effect.input);
+                    if (gameplayNext !== null) {
+                        gameplay = gameplayNext;
+                        gameplayTouched = true;
+                        continue;
+                    }
+                    if (guarded.state !== gameplay) {
+                        gameplay = guarded.state;
+                        gameplayTouched = true;
+                    }
+                    const operation = tmwSceneOperationFromEffect(effect.capabilityId, effect.input);
+                    if (operation === null)
+                        this.#applyEffect(entities, emittedEvents, effect);
+                    else {
+                        const current = state.scene === null || state.scene === undefined ? null : canonicalTmwSceneStateV1(state.scene);
+                        const next = reduceTmwSceneV1(current, operation, `${input.operation_id}:${effect.effectId}`);
+                        const references = object(state.scene_source_references ?? null, "scene_source_references");
+                        validateTmwSceneSourceReferencesV1(next, references);
+                        state.scene = next;
+                    }
+                }
+            }
+            if (gameplayTouched)
+                state.gameplayState = persistentTmwGameplayStateV1(gameplay);
+            const canonicalState = canonicalTmwJsonValue(state, "authoring_state_readback");
+            return Object.freeze({
+                state: canonicalState,
+                receipt_digest: await tmwSha256Hex(canonicalTmwJson({
+                    operationId: input.operation_id,
+                    eventId: input.event.eventId,
+                    state: canonicalState,
+                })),
+            });
+        },
+    };
+    /** GUI/Agent 新建 trigger 时的合法空白候选；只返回值，不修改 source。 */
+    async emptyDocument() {
+        const registry = getCanonicalTmwCapabilityRegistryV3();
+        const built = await beginTmwBuilder({
+            runtime_contract_hash: await runtimeContractHashV3(),
+            registry,
+        }).build();
+        if (!built.ok)
+            throw new Error(`tmw_authoring_empty_document_invalid:${built.diagnostics.map((item) => item.code).join(",")}`);
+        return built.value;
+    }
+    async validate(document) {
+        const result = await validateTmw3Authoring(document);
+        if (!result.ok)
+            return Object.freeze({ ok: false, issues: result.diagnostics.map((item) => `${item.code}:${item.path}`) });
+        return Object.freeze({ ok: true, issues: Object.freeze([]), document_sha256: result.document_sha256, plan_sha256: result.plan_sha256 });
+    }
+    execute(input) {
+        return executeTmw3Authoring({
+            document: input.document,
+            event: {
+                event_type: input.event.type,
+                payload: input.event.payload ?? {},
+                ...(input.event.id === undefined ? {} : { event_id: input.event.id }),
+            },
+            initial_state: input.state ?? { entities: {}, emitted_events: [] },
+            ...(input.semantic_predicates === undefined ? {} : { semantic_predicates: input.semantic_predicates }),
+            effect_port: this.#effectPort,
+        });
+    }
+    #applyEffect(entities, emittedEvents, effect) {
+        const handler = Object.hasOwn(AUTHORING_EFFECT_HANDLERS, effect.capabilityId) ? AUTHORING_EFFECT_HANDLERS[effect.capabilityId] : undefined;
+        if (handler === undefined)
+            throw new Error(`tmw_authoring_effect_capability_forbidden:${effect.capabilityId}`);
+        handler.apply(entities, emittedEvents, effect);
+    }
+}

package/dist/vendor/wasm-core/asset-hashes.json

@@ -0,0 +1,5 @@
+{
+  "wasm_core.js": "7ee6ad38b7a265bf1684a83f791e1e3a183f5e5010e2e1592dddfdf99ba72ff4",
+  "wasm_core_bg.wasm": "4ffe27b5576d3f10a9e2b37a1fec7f741655e43fb9cfc9329005ec4201d083d1",
+  "wasm_core.d.ts": "5f8dc1320a5c7267aacafe65ff6c6b88e908124d8609f7ec0163211733e85486"
+}