@world-engines/tmw 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,46 @@
+WorldEngine 官方作者工具许可证
+
+版权所有 (c) 2026 Nixdorfer。保留所有权利。
+
+本仓库的源代码、构建材料及附带资源（统称“本作品”）不是开源软件，
+不适用任何 OSI 认证的开源许可证。
+
+一、官方作者工具分发许可
+
+版权所有者可以通过其官方网站、npm registry、签名安装包或其他官方渠道，
+复制并分发由本作品构建的 WorldEngine 作者工具及其必要运行资源
+（统称“官方作者工具”）。仅版权所有者或其书面指定的发布者享有此分发权。
+
+二、作者用户许可
+
+从官方渠道取得官方作者工具的作者用户，可以：
+
+1. 安装和运行官方作者工具；
+2. 使用官方作者工具创作、编辑、预览、导入、导出和提交其有权处理的内容；
+3. 为上述使用目的制作合理必要的本地备份副本。
+
+三、未授予的权利
+
+除第二条明确允许的行为外，本许可证不授予作者用户或其他第三方以下权利：
+
+1. 修改、改编、反编译、反汇编或制作官方作者工具的派生作品；
+2. 复制、镜像、转发、再上传、出售、出租、再分发或再许可官方作者工具；
+3. 使用本作品的源代码、构建材料或任何部分开发、提供或训练其他产品或服务；
+4. 删除或规避版权、许可、签名、访问控制或其他权利管理信息。
+
+法律强制允许且合同不得排除的权利不受上述限制影响。
+
+四、源代码查看
+
+第三方可以在已获合法访问权限的范围内查看本作品，用于审查、安全研究或学习参考；
+查看不授予运行、复制、修改、分发、再许可或用于其他产品与服务的权利。
+
+五、无担保与责任限制
+
+本作品与官方作者工具均按“现状”提供，不附带任何明示或暗示的担保。
+在适用法律允许的最大范围内，版权所有者不对因访问或使用本作品或官方作者工具
+造成的任何损失承担责任。
+
+六、终止
+
+违反本许可证将立即终止相应的访问与使用权；终止不影响版权所有者已经产生的权利和救济。

package/dist/activation.d.ts

@@ -0,0 +1,50 @@
+import { TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+import { type AudioPresentationProjectionV1 } from "./audio-presentation-projection.js";
+import { type DurableIntentV3 } from "./durable-intent.js";
+import type { RuntimeSavExtensionSectionV3 } from "./runtime-sav.js";
+import type { TimelineHeadV3, TimelineRevisionV3 } from "./timeline-revision.js";
+import { type TmwJsonValue } from "./runtime-trace.js";
+export interface TmwActivationExpectedHead extends TimelineHeadV3 {
+}
+export interface TmwActivationCandidateV3 {
+    readonly operationId: string;
+    readonly epoch: number;
+    readonly runtimeGeneration: typeof TMW_RUNTIME_GENERATION;
+    readonly runtimeContractHash: string;
+    readonly artifactDigest: string;
+    readonly sourceRevision: string;
+    readonly expectedHead: TmwActivationExpectedHead | null;
+    readonly timeline: TimelineRevisionV3;
+    readonly ledger: TmwJsonValue;
+    readonly ledgerHead: string;
+    readonly narrative: TmwJsonValue;
+    readonly narrativeDigest: string;
+    readonly savSection: RuntimeSavExtensionSectionV3;
+    readonly savSectionDigest: string;
+    readonly intents: ReadonlyArray<DurableIntentV3>;
+    readonly intentSetDigest: string;
+    readonly presentationIntents: ReadonlyArray<TmwJsonValue>;
+    readonly presentationIntentSetDigest: string;
+    readonly audioPresentation?: AudioPresentationProjectionV1 | null;
+    readonly preActivationTerminalDigest: string;
+}
+export interface TmwActivationReceiptV3 {
+    readonly operationId: string;
+    readonly status: "committed" | "already_committed" | "conflict";
+    readonly previousHead: TmwActivationExpectedHead | null;
+    readonly activeHead: TmwActivationExpectedHead;
+    readonly atomicWriteCount: number;
+    readonly candidateDigest: string;
+    readonly receiptDigest: string;
+}
+export interface TmwActivationAtomicPort {
+    /**
+     * Player-owned TurnCommit/CAS primitive. Edge must never implement or call
+     * this port; Edge returns only validated compute/Judge candidates.
+     */
+    commitAtomic(candidate: TmwActivationCandidateV3): Promise<TmwActivationReceiptV3>;
+    readByOperation(operationId: string): Promise<TmwActivationReceiptV3 | null>;
+}
+export declare function canonicalTmwActivationCandidate(input: TmwActivationCandidateV3): TmwActivationCandidateV3;
+export declare function tmwActivationCandidateDigest(candidateInput: TmwActivationCandidateV3): Promise<string>;
+export declare function activateTmwCandidate(candidateInput: TmwActivationCandidateV3, port: TmwActivationAtomicPort): Promise<TmwActivationReceiptV3>;

package/dist/activation.js

@@ -0,0 +1,113 @@
+import { TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+import { canonicalAudioPresentationProjection } from "./audio-presentation-projection.js";
+import { canonicalDurableIntent } from "./durable-intent.js";
+import { assertTimelineSuccessor } from "./timeline-revision.js";
+import { canonicalTmwJson, canonicalTmwJsonValue, requireTmwIdentifier, requireTmwSafeInteger, requireTmwSha256, tmwSha256Hex, } from "./runtime-trace.js";
+export function canonicalTmwActivationCandidate(input) {
+    if (input.runtimeGeneration !== 3)
+        throw new Error("unsupported_runtime_generation");
+    const timeline = assertTimelineSuccessor(input.expectedHead, input.timeline);
+    if (timeline.epoch !== input.epoch
+        || timeline.runtimeContractHash !== input.runtimeContractHash
+        || timeline.artifactDigest !== input.artifactDigest
+        || timeline.sourceRevision !== input.sourceRevision
+        || timeline.operationId !== input.operationId) {
+        throw new Error("tmw_activation_timeline_binding_mismatch");
+    }
+    if (timeline.ledgerHead !== input.ledgerHead)
+        throw new Error("tmw_activation_ledger_head_mismatch");
+    if (timeline.narrativeDigest !== input.narrativeDigest) {
+        throw new Error("tmw_activation_narrative_digest_mismatch");
+    }
+    if (timeline.savSectionDigest !== input.savSectionDigest) {
+        throw new Error("tmw_activation_sav_digest_mismatch");
+    }
+    if (timeline.intentSetDigest !== input.intentSetDigest
+        || timeline.presentationIntentSetDigest !== input.presentationIntentSetDigest) {
+        throw new Error("tmw_activation_intent_digest_mismatch");
+    }
+    return Object.freeze({
+        operationId: requireTmwIdentifier(input.operationId, "activation_operation_id"),
+        epoch: requireTmwSafeInteger(input.epoch, "activation_epoch", 1),
+        runtimeGeneration: TMW_RUNTIME_GENERATION,
+        runtimeContractHash: requireTmwSha256(input.runtimeContractHash, "activation_contract_hash"),
+        artifactDigest: requireTmwSha256(input.artifactDigest, "activation_artifact_digest"),
+        sourceRevision: requireTmwIdentifier(input.sourceRevision, "activation_source_revision"),
+        expectedHead: input.expectedHead,
+        timeline,
+        ledger: canonicalTmwJsonValue(input.ledger, "activation_ledger"),
+        ledgerHead: requireTmwSha256(input.ledgerHead, "activation_ledger_head"),
+        narrative: canonicalTmwJsonValue(input.narrative, "activation_narrative"),
+        narrativeDigest: requireTmwSha256(input.narrativeDigest, "activation_narrative_digest"),
+        savSection: input.savSection,
+        savSectionDigest: requireTmwSha256(input.savSectionDigest, "activation_sav_digest"),
+        intents: Object.freeze(input.intents.map(canonicalDurableIntent).sort((left, right) => left.intentId < right.intentId ? -1 : left.intentId > right.intentId ? 1 : 0)),
+        intentSetDigest: requireTmwSha256(input.intentSetDigest, "activation_intent_digest"),
+        presentationIntents: Object.freeze(input.presentationIntents.map((intent) => canonicalTmwJsonValue(intent, "activation_presentation_intent"))),
+        presentationIntentSetDigest: requireTmwSha256(input.presentationIntentSetDigest, "activation_presentation_digest"),
+        audioPresentation: input.audioPresentation == null
+            ? null
+            : canonicalAudioPresentationProjection(input.audioPresentation),
+        preActivationTerminalDigest: requireTmwSha256(input.preActivationTerminalDigest, "activation_terminal_digest"),
+    });
+}
+function bytesToHex(bytes) {
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function candidateDigestImage(candidate) {
+    return canonicalTmwJsonValue({
+        operationId: candidate.operationId,
+        epoch: candidate.epoch,
+        runtimeGeneration: candidate.runtimeGeneration,
+        runtimeContractHash: candidate.runtimeContractHash,
+        artifactDigest: candidate.artifactDigest,
+        sourceRevision: candidate.sourceRevision,
+        expectedHead: candidate.expectedHead,
+        timeline: candidate.timeline,
+        ledger: candidate.ledger,
+        ledgerHead: candidate.ledgerHead,
+        narrative: candidate.narrative,
+        narrativeDigest: candidate.narrativeDigest,
+        savSection: {
+            extensionId: candidate.savSection.extension_id,
+            schemaVersion: candidate.savSection.schema_version,
+            required: candidate.savSection.required,
+            payloadHex: bytesToHex(candidate.savSection.payload),
+            codec: candidate.savSection.codec,
+            sha256Hex: bytesToHex(candidate.savSection.payload_sha256),
+        },
+        savSectionDigest: candidate.savSectionDigest,
+        intents: candidate.intents,
+        intentSetDigest: candidate.intentSetDigest,
+        presentationIntents: candidate.presentationIntents,
+        presentationIntentSetDigest: candidate.presentationIntentSetDigest,
+        audioPresentation: candidate.audioPresentation ?? null,
+        preActivationTerminalDigest: candidate.preActivationTerminalDigest,
+    }, "activation_candidate_digest_image");
+}
+export async function tmwActivationCandidateDigest(candidateInput) {
+    const candidate = canonicalTmwActivationCandidate(candidateInput);
+    return await tmwSha256Hex(canonicalTmwJson(candidateDigestImage(candidate)));
+}
+export async function activateTmwCandidate(candidateInput, port) {
+    const candidate = canonicalTmwActivationCandidate(candidateInput);
+    const candidateDigest = await tmwActivationCandidateDigest(candidate);
+    const existing = await port.readByOperation(candidate.operationId);
+    if (existing !== null) {
+        if (existing.candidateDigest !== candidateDigest) {
+            throw new Error("tmw_activation_operation_identity_conflict");
+        }
+        return existing;
+    }
+    const receipt = await port.commitAtomic(candidate);
+    if (receipt.candidateDigest !== candidateDigest) {
+        throw new Error("tmw_activation_receipt_candidate_mismatch");
+    }
+    if (receipt.status !== "conflict" && receipt.activeHead.revisionId !== candidate.timeline.revisionId) {
+        throw new Error("tmw_activation_readback_mismatch");
+    }
+    if (receipt.atomicWriteCount !== (receipt.status === "conflict" ? 0 : 5)) {
+        throw new Error("tmw_activation_atomic_write_count_invalid");
+    }
+    return receipt;
+}

package/dist/audio-presentation-projection.d.ts

@@ -0,0 +1,23 @@
+export interface AudioPresentationSegmentV1 {
+    readonly segmentId: string;
+    readonly ordinal: number;
+    readonly text: string;
+    readonly speakerLabel: string | null;
+    readonly sfx: ReadonlyArray<Readonly<{
+        cueId: string;
+        ruleId: string;
+        resourceId: string;
+        priority: number;
+        cooldownMs: number;
+    }>>;
+}
+export interface AudioPresentationProjectionV1 {
+    readonly schema: "audio-presentation.v1";
+    readonly messageId: string;
+    readonly planHash: string;
+    readonly mode: "document" | "galgame";
+    readonly fullText: string;
+    readonly segments: ReadonlyArray<AudioPresentationSegmentV1>;
+}
+export declare const canonicalAudioPresentationProjection: (input: AudioPresentationProjectionV1) => AudioPresentationProjectionV1;
+export declare const audioPresentationDigestImage: (input: AudioPresentationProjectionV1) => string;

package/dist/audio-presentation-projection.js

@@ -0,0 +1,39 @@
+import { canonicalTmwJson, requireTmwIdentifier, requireTmwSafeInteger, requireTmwSha256 } from "./runtime-trace.js";
+export const canonicalAudioPresentationProjection = (input) => {
+    if (input.schema !== "audio-presentation.v1")
+        throw new Error("audio_presentation_schema_invalid");
+    const segments = input.segments.map((segment, index) => {
+        if (requireTmwIdentifier(segment.segmentId, "audio_presentation_segment_id") !== segment.segmentId
+            || requireTmwSafeInteger(segment.ordinal, "audio_presentation_segment_ordinal", 0) !== index
+            || typeof segment.text !== "string"
+            || (segment.speakerLabel !== null && typeof segment.speakerLabel !== "string")) {
+            throw new Error("audio_presentation_segment_invalid");
+        }
+        return Object.freeze({
+            ...segment,
+            sfx: Object.freeze(segment.sfx.map((cue) => Object.freeze({
+                cueId: requireTmwIdentifier(cue.cueId, "audio_presentation_cue_id"),
+                ruleId: requireTmwIdentifier(cue.ruleId, "audio_presentation_rule_id"),
+                resourceId: requireTmwIdentifier(cue.resourceId, "audio_presentation_resource_id"),
+                priority: requireTmwSafeInteger(cue.priority, "audio_presentation_priority", 0),
+                cooldownMs: requireTmwSafeInteger(cue.cooldownMs, "audio_presentation_cooldown", 0),
+            }))),
+        });
+    });
+    if (segments.length === 0 || segments.length > 128 || (input.mode !== "document" && input.mode !== "galgame")) {
+        throw new Error("audio_presentation_plan_invalid");
+    }
+    const projection = Object.freeze({
+        schema: "audio-presentation.v1",
+        messageId: requireTmwIdentifier(input.messageId, "audio_presentation_message_id"),
+        planHash: requireTmwSha256(input.planHash, "audio_presentation_plan_hash"),
+        mode: input.mode,
+        fullText: input.fullText,
+        segments: Object.freeze(segments),
+    });
+    if (projection.fullText !== projection.segments.map((segment) => segment.text).join("")) {
+        throw new Error("audio_presentation_text_mismatch");
+    }
+    return projection;
+};
+export const audioPresentationDigestImage = (input) => canonicalTmwJson(canonicalAudioPresentationProjection(input));

package/dist/author-scenario-source-v3.d.ts

@@ -0,0 +1,34 @@
+import type { TmwJsonValue } from "./runtime-contract.js";
+import { AUTHOR_SCENARIO_SOURCE_V3_SCHEMA_VERSION, TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+import type { TriggerDocumentV3 } from "./trigger-document-v3.js";
+import type { MusicCandidateSourceV3 } from "./music-candidate-set.js";
+import type { ViewInteractionSourceV3 } from "./view-interaction-manifest-v3.js";
+export interface AuthorScenarioSourceV3 {
+    readonly schema_version: typeof AUTHOR_SCENARIO_SOURCE_V3_SCHEMA_VERSION;
+    readonly runtime_generation: typeof TMW_RUNTIME_GENERATION;
+    readonly owner_id: string;
+    readonly scenario_id: string;
+    readonly epoch: number;
+    readonly source_revision: number;
+    readonly previous_revision_digest: string | null;
+    readonly trigger_document: TriggerDocumentV3;
+    readonly view_interaction_mobile: ViewInteractionSourceV3 | null;
+    readonly view_interaction_pc: ViewInteractionSourceV3 | null;
+    readonly music_candidate_source: MusicCandidateSourceV3;
+    readonly source_metadata: Readonly<Record<string, TmwJsonValue>>;
+}
+export interface AuthenticatedCreateNewSourceInput {
+    readonly operation: "create-new";
+    readonly auth_principal_id: string;
+    readonly owner_id: string;
+    readonly scenario_id: string;
+    readonly epoch: number;
+    readonly registry_version: string;
+}
+export interface AuthorSourceIdentityV3 {
+    readonly owner_id: string;
+    readonly scenario_id: string;
+    readonly epoch: number;
+    readonly source_revision: number;
+    readonly source_sha256: string;
+}

package/dist/author-scenario-source-v3.js

@@ -0,0 +1 @@
+export {};

package/dist/authoring-runtime.d.ts

@@ -0,0 +1,76 @@
+import { type TmwActivationReceiptV3 } from "./activation.js";
+import type { TmwDiagnostic } from "./diagnostics.js";
+import { type CommittedEventEnvelope } from "./event-fabric.js";
+import type { EffectPlan } from "./effect-flow.js";
+import type { RuntimeSavPayloadV3 } from "./runtime-sav.js";
+import { type RuntimeTraceSnapshot, type TmwJsonValue } from "./runtime-trace.js";
+import { type TmwSimulationTraceEntry } from "./simulator.js";
+export interface TmwAuthoringEventV3 {
+    readonly event_type: string;
+    readonly payload: Readonly<Record<string, TmwJsonValue>>;
+    readonly event_id?: string;
+}
+export interface TmwAuthoringEffectStageInput {
+    readonly operation_id: string;
+    readonly event: CommittedEventEnvelope;
+    readonly plans: ReadonlyArray<EffectPlan>;
+    readonly state: TmwJsonValue;
+}
+export interface TmwAuthoringEffectStageReceipt {
+    readonly state: TmwJsonValue;
+    readonly receipt_digest: string;
+    readonly world_mutation_recovery_operation?: TmwJsonValue;
+}
+/**
+ * 作者试玩的受控 effect seam。实现方只能消费 Runtime3 已冻结的 EffectPlan，
+ * 不能获得数据库、文件系统或任意代码执行 capability。
+ */
+export interface TmwAuthoringEffectPort {
+    stage(input: TmwAuthoringEffectStageInput): Promise<TmwAuthoringEffectStageReceipt>;
+}
+export interface ExecuteTmw3AuthoringInput {
+    readonly document: unknown;
+    readonly event: TmwAuthoringEventV3;
+    readonly initial_state: TmwJsonValue;
+    readonly effect_port: TmwAuthoringEffectPort;
+    readonly semantic_predicates?: Readonly<Record<string, "true" | "false" | "unknown">>;
+    /** Explicit authoring-simulator clock authority; never inferred from authored effective_time. */
+    readonly clock_observation?: Readonly<{
+        coordinates: CommittedEventEnvelope["coordinates"];
+        crossing_direction: CommittedEventEnvelope["crossingDirection"];
+    }>;
+    readonly source_revision?: string;
+    readonly max_trace_entries?: number;
+}
+export type ExecuteTmw3AuthoringOutcome = {
+    readonly ok: false;
+    readonly diagnostics: readonly TmwDiagnostic[];
+} | {
+    readonly ok: true;
+    readonly document_sha256: string;
+    readonly plan_sha256: string;
+    readonly simulation_trace: readonly TmwSimulationTraceEntry[];
+    readonly runtime_trace: RuntimeTraceSnapshot;
+    readonly state: TmwJsonValue;
+    readonly state_digest: string;
+    readonly runtime_sav: RuntimeSavPayloadV3;
+    readonly activation: TmwActivationReceiptV3;
+    readonly diagnostics: readonly TmwDiagnostic[];
+};
+export type ValidateTmw3AuthoringOutcome = {
+    readonly ok: false;
+    readonly diagnostics: readonly TmwDiagnostic[];
+} | {
+    readonly ok: true;
+    readonly document_sha256: string;
+    readonly plan_sha256: string;
+    readonly simulation_trace: readonly TmwSimulationTraceEntry[];
+    readonly diagnostics: readonly TmwDiagnostic[];
+};
+/** 只做真实 parser/validator/compiler 与无副作用计划模拟，不创建执行 receipt。 */
+export declare function validateTmw3Authoring(document: unknown): Promise<ValidateTmw3AuthoringOutcome>;
+/**
+ * Node/Browser 均可消费的作者试玩入口。simulation_trace 只用于计划预览；
+ * runtime_trace 仅记录 Runtime3 的真实 executeCommittedEvent 阶段。
+ */
+export declare function executeTmw3Authoring(input: ExecuteTmw3AuthoringInput): Promise<ExecuteTmw3AuthoringOutcome>;

package/dist/authoring-runtime.js

@@ -0,0 +1,282 @@
+import { tmwActivationCandidateDigest } from "./activation.js";
+import { getCanonicalTmwCapabilityRegistryV3 } from "./capability-registry.js";
+import { compileTmw3 } from "./compiler.js";
+import { TMW_EMPTY_LEDGER_HEAD } from "./event-fabric.js";
+import { createTmwRuntimeHost } from "./runtime.js";
+import { BoundedRuntimeTrace, canonicalTmwJson, canonicalTmwJsonValue, tmwSha256Hex } from "./runtime-trace.js";
+import { simulateTmw3 } from "./simulator.js";
+import { validateTmw3 } from "./validator.js";
+import { canonicalTmwSceneStateV1 } from "./scene-state.js";
+import { initialTmwGameplayStateFromWorldV1 } from "./gameplay-state.js";
+const ZERO_SHA256 = "0".repeat(64);
+async function prepareTmw3Authoring(document, runtimeTarget = "production") {
+    const registry = getCanonicalTmwCapabilityRegistryV3();
+    const validated = await validateTmw3(document, registry);
+    if (!validated.ok)
+        return validated;
+    const compiled = await compileTmw3(validated.value, registry, { runtime_target: runtimeTarget });
+    if (!compiled.ok)
+        return compiled;
+    const simulation = await simulateTmw3(validated.value, registry);
+    if (!simulation.ok)
+        return simulation;
+    return Object.freeze({
+        ok: true,
+        document: validated.value,
+        plan: compiled.plan,
+        simulation_trace: simulation.trace,
+        diagnostics: compiled.diagnostics,
+    });
+}
+/** 只做真实 parser/validator/compiler 与无副作用计划模拟，不创建执行 receipt。 */
+export async function validateTmw3Authoring(document) {
+    const prepared = await prepareTmw3Authoring(document);
+    if (!prepared.ok)
+        return prepared;
+    return Object.freeze({
+        ok: true,
+        document_sha256: prepared.plan.document_sha256,
+        plan_sha256: prepared.plan.plan_sha256,
+        simulation_trace: prepared.simulation_trace,
+        diagnostics: prepared.diagnostics,
+    });
+}
+function initialSav(input) {
+    return Object.freeze({
+        schemaVersion: 3,
+        epoch: 1,
+        runtimeGeneration: 3,
+        runtimeContractHash: input.runtimeContractHash,
+        artifactDigest: input.artifactDigest,
+        sourceRevision: input.sourceRevision,
+        activeTimelineRevision: input.timelineRevision,
+        turnId: "tmw3:authoring:fresh",
+        preActivationTerminalDigest: ZERO_SHA256,
+        activeTimeline: Object.freeze({
+            revisionId: input.timelineRevision,
+            parentRevisionId: null,
+            revisionSequence: 0,
+            epoch: 1,
+            runtimeGeneration: 3,
+            runtimeContractHash: input.runtimeContractHash,
+            artifactDigest: input.artifactDigest,
+            sourceRevision: input.sourceRevision,
+            worldlineId: input.worldlineId,
+            operationId: "tmw3:authoring:fresh",
+            ledgerHead: TMW_EMPTY_LEDGER_HEAD,
+            narrativeDigest: input.narrativeDigest,
+            savSectionDigest: ZERO_SHA256,
+            intentSetDigest: input.intentSetDigest,
+            presentationIntentSetDigest: input.intentSetDigest,
+            createdFrom: "fresh",
+            active: true,
+        }),
+        ledgerHead: TMW_EMPTY_LEDGER_HEAD,
+        eventLedger: Object.freeze({ events: Object.freeze([]) }),
+        narrative: Object.freeze({}),
+        scene: input.scene,
+        gameplayState: input.gameplayState,
+        pendingSceneClockCrossings: Object.freeze([]),
+        scheduler: Object.freeze({
+            cursor: input.scene === null ? null : Object.freeze({
+                logicalSeq: 0,
+                worldTime: input.scene.worldTime,
+                presentation: null,
+                realTime: Object.freeze({}),
+            }),
+            suspensions: Object.freeze([]),
+        }),
+        conditionState: Object.freeze({}),
+        durableIntents: Object.freeze([]),
+        presentationIntents: Object.freeze([]),
+        semanticVerdictRefs: Object.freeze([]),
+        candidateSetRevisions: Object.freeze([]),
+        operationReceiptDigests: Object.freeze([]),
+        worldMutationRecoveryOperations: Object.freeze([]),
+    });
+}
+/**
+ * Node/Browser 均可消费的作者试玩入口。simulation_trace 只用于计划预览；
+ * runtime_trace 仅记录 Runtime3 的真实 executeCommittedEvent 阶段。
+ */
+export async function executeTmw3Authoring(input) {
+    const registry = getCanonicalTmwCapabilityRegistryV3();
+    const prepared = await prepareTmw3Authoring(input.document, "simulation");
+    if (!prepared.ok)
+        return prepared;
+    const trace = new BoundedRuntimeTrace(input.max_trace_entries);
+    trace.append({ kind: "validated", stableId: prepared.plan.document_sha256 });
+    trace.append({ kind: "compiled", stableId: prepared.plan.plan_sha256 });
+    const sourceRevision = input.source_revision ?? "tmw3:authoring:source";
+    const timelineRevision = "tmw3:authoring:timeline:0";
+    const worldlineId = "tmw3:authoring:worldline";
+    const [narrativeDigest, emptySetDigest] = await Promise.all([
+        tmwSha256Hex(canonicalTmwJson({})),
+        tmwSha256Hex(canonicalTmwJson([])),
+    ]);
+    const runtime = createTmwRuntimeHost({
+        binding: Object.freeze({
+            epoch: 1,
+            runtimeGeneration: 3,
+            runtimeContractHash: prepared.document.runtime_contract_hash,
+            artifactDigest: prepared.plan.plan_sha256,
+            sourceRevision,
+            timelineRevision,
+            leaseId: "tmw3:authoring:lease",
+        }),
+        compiledPlan: prepared.plan,
+        capabilityRegistry: registry,
+    });
+    const authoringState = input.initial_state !== null && typeof input.initial_state === "object" && !Array.isArray(input.initial_state)
+        ? input.initial_state : {};
+    const scene = authoringState.scene === undefined || authoringState.scene === null ? null
+        : canonicalTmwSceneStateV1(authoringState.scene);
+    runtime.restore(initialSav({
+        runtimeContractHash: prepared.document.runtime_contract_hash,
+        artifactDigest: prepared.plan.plan_sha256,
+        sourceRevision,
+        timelineRevision,
+        worldlineId,
+        narrativeDigest,
+        intentSetDigest: emptySetDigest,
+        scene,
+        gameplayState: initialTmwGameplayStateFromWorldV1(authoringState),
+    }));
+    const payload = canonicalTmwJsonValue(input.event.payload, "authoring_event_payload");
+    const payloadHash = await tmwSha256Hex(canonicalTmwJson(payload));
+    const eventId = input.event.event_id ?? `tmw3:authoring:event:${payloadHash.slice(0, 24)}`;
+    const eventContext = runtime.viewEventCommitContext(input.event.event_type, input.clock_observation === undefined
+        ? Object.freeze({
+            coordinates: Object.freeze({
+                logicalSeq: 0,
+                worldTime: scene?.worldTime ?? null,
+                presentation: Object.freeze({
+                    planId: prepared.plan.plan_sha256,
+                    segmentId: "tmw3:authoring:test-clock",
+                    cursor: 0,
+                    eventSeq: 0,
+                }),
+                realTime: null,
+            }),
+            crossingDirection: "forward",
+        })
+        : Object.freeze({
+            coordinates: input.clock_observation.coordinates,
+            crossingDirection: input.clock_observation.crossing_direction,
+        }));
+    const commitReceiptDigest = await tmwSha256Hex(canonicalTmwJson({ eventId, payloadHash }));
+    const event = Object.freeze({
+        eventId,
+        eventType: input.event.event_type,
+        hardFact: eventContext.hardFact,
+        epoch: 1,
+        runtimeGeneration: 3,
+        runtimeContractHash: prepared.document.runtime_contract_hash,
+        artifactDigest: prepared.plan.plan_sha256,
+        sourceRevision,
+        timelineRevision,
+        scope: Object.freeze({ scenarioId: "tmw3:authoring:scenario", saveId: "tmw3:authoring:save", worldlineId }),
+        coordinates: eventContext.coordinates,
+        effectiveTime: eventContext.effectiveTime,
+        crossingDirection: eventContext.crossingDirection,
+        correlationId: "tmw3:authoring:turn",
+        causationId: null,
+        replacementLineage: Object.freeze([]),
+        payloadHash,
+        payload,
+        commitReceiptDigest,
+    });
+    let state = canonicalTmwJsonValue(input.initial_state, "authoring_initial_state");
+    const activationReceipts = new Map();
+    let activeHead = Object.freeze({
+        revisionId: timelineRevision,
+        revisionSequence: 0,
+        ledgerHead: TMW_EMPTY_LEDGER_HEAD,
+    });
+    const preparedWorldMutations = new Map();
+    trace.append({ kind: "event_prepared", stableId: event.eventId, detail: { payloadHash } });
+    const execution = await runtime.executeCommittedEvent(event, {
+        semanticJudge: {
+            async judge(request) {
+                const predicates = Object.freeze(Object.fromEntries(request.predicateKeys.map((key) => [
+                    key,
+                    input.semantic_predicates?.[key] ?? "unknown",
+                ])));
+                const digest = await tmwSha256Hex(canonicalTmwJson(predicates));
+                trace.append({ kind: "semantic_judged", stableId: request.intentId, detail: { digest } });
+                return Object.freeze({
+                    predicateValues: predicates,
+                    budgetReceiptDigest: digest,
+                    evidenceSetDigest: digest,
+                    providerReceiptDigest: digest,
+                    verdictDigest: digest,
+                });
+            },
+        },
+        effectCommit: {
+            async prepareWorldMutation(request) {
+                const binding = Object.freeze({ bindingId: `tmw3:authoring:binding:${request.operationId}`, operationId: request.operationId, turnId: request.turnId });
+                preparedWorldMutations.set(request.operationId, binding);
+                trace.append({ kind: "effect_prepared", stableId: request.operationId, detail: { worldEffectNodeIds: request.worldEffectNodeIds } });
+                return binding;
+            },
+            async stage(request) {
+                const receipt = await input.effect_port.stage({ operation_id: request.operationId, event: request.event, plans: request.plans, state });
+                state = canonicalTmwJsonValue(receipt.state, "authoring_effect_state");
+                trace.append({ kind: "effect_staged", stableId: request.operationId, detail: { receiptDigest: receipt.receipt_digest } });
+                return Object.freeze({
+                    preActivationTerminalDigest: receipt.receipt_digest,
+                    worldMutationRecoveryOperation: receipt.world_mutation_recovery_operation ?? null,
+                });
+            },
+            async finalizeWorldMutation(request) {
+                preparedWorldMutations.delete(request.operationId);
+                trace.append({ kind: "effect_finalized", stableId: request.operationId });
+            },
+            async rollbackWorldMutation(request) {
+                preparedWorldMutations.delete(request.operationId);
+                trace.append({ kind: "effect_rolled_back", stableId: request.operationId, detail: { reason: request.reason } });
+            },
+        },
+        activation: {
+            async readByOperation(operationId) {
+                return activationReceipts.get(operationId) ?? null;
+            },
+            async commitAtomic(candidate) {
+                const candidateDigest = await tmwActivationCandidateDigest(candidate);
+                const status = candidate.expectedHead?.revisionId === activeHead.revisionId
+                    && candidate.expectedHead.revisionSequence === activeHead.revisionSequence
+                    && candidate.expectedHead.ledgerHead === activeHead.ledgerHead
+                    ? "committed"
+                    : "conflict";
+                const previousHead = activeHead;
+                if (status === "committed") {
+                    activeHead = Object.freeze({ revisionId: candidate.timeline.revisionId, revisionSequence: candidate.timeline.revisionSequence, ledgerHead: candidate.ledgerHead });
+                }
+                const receiptCore = { operationId: candidate.operationId, status, previousHead, activeHead, atomicWriteCount: status === "committed" ? 5 : 0, candidateDigest };
+                const receipt = Object.freeze({ ...receiptCore, receiptDigest: await tmwSha256Hex(canonicalTmwJson(receiptCore)) });
+                activationReceipts.set(candidate.operationId, receipt);
+                trace.append({ kind: "activation_committed", stableId: candidate.operationId, detail: { candidateDigest } });
+                return receipt;
+            },
+        },
+    });
+    trace.append({ kind: "readback_verified", stableId: execution.activation.operationId, detail: { receiptDigest: execution.activation.receiptDigest } });
+    const runtimeSav = runtime.restoredSav();
+    if (runtimeSav === null)
+        throw new Error("tmw_authoring_runtime_sav_missing");
+    runtime.dispose();
+    const stateDigest = await tmwSha256Hex(canonicalTmwJson(state));
+    return Object.freeze({
+        ok: true,
+        document_sha256: prepared.plan.document_sha256,
+        plan_sha256: prepared.plan.plan_sha256,
+        simulation_trace: prepared.simulation_trace,
+        runtime_trace: trace.snapshot(),
+        state,
+        state_digest: stateDigest,
+        runtime_sav: runtimeSav,
+        activation: execution.activation,
+        diagnostics: prepared.diagnostics,
+    });
+}