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

package/dist/local-preview-runtime.js

@@ -0,0 +1,553 @@
+import { randomUUID } from "node:crypto";
+import { link, readFile, unlink, writeFile } from "node:fs/promises";
+import { DatabaseSync } from "node:sqlite";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { CURRENT_NEUTRAL_COMPILER_STAGE_VERSIONS, InMemoryCompilerStageCache, buildCurrentTmw3NeutralCompilerStageRegistry, canonicalTmwBytes, canonicalTmwJsonValue, decodeRuntimeSavSectionSelfBound, compileNeutralScenarioSource, createTmwRuntimeHost, emptyTmwGameplayStateV1, getCanonicalTmwCapabilityRegistryV3, initialTmwSceneFromMetadata, readTmwUnlockV1, readTmwVariableV1, tmwSha256Hex, tmwActivationCandidateDigest, } from "@world-engines/tmw";
+import { captureLocalPreviewSource } from "./local-preview-source.js";
+import { ensureSafeProjectDirectory, safeProjectPath } from "./safe-project-path.js";
+import { createLocalPreviewWorldProjection, reduceLocalPreviewWorldEffects } from "./local-preview-world-effects.js";
+import { LocalPreviewWorldlineStore } from "./local-preview-worldline-store.js";
+import { LocalPreviewViewStateSqlitePort } from "./local-preview-view-state-sqlite.js";
+import { LocalPreviewMessageStore } from "./local-preview-message-store.js";
+import { LocalPreviewPlayerReadModels } from "./local-preview-player-read-models.js";
+import { localPreviewBoundResourcesFromLogicalGraph } from "./local-preview-bound-resources.js";
+const ZERO_SHA256 = "0".repeat(64);
+const SAVE_SCHEMA_VERSION = 1;
+/**
+ * 本地开发预览的单实例 Runtime seam。
+ * 它只消费 immutable capture，SAV 也只写入 capture-hash 隔离目录；不是正式 Player 保存、head、lease 或发布 authority。
+ */
+export class LocalPreviewRuntime {
+    #capture;
+    #compiledPlan;
+    #runtime;
+    #savePath;
+    #receiptSha256;
+    #store;
+    #writerPreparations = new Map();
+    constructor(input) {
+        this.#capture = input.capture;
+        this.#compiledPlan = input.compiledPlan;
+        this.#runtime = input.runtime;
+        this.#savePath = input.savePath;
+        this.#receiptSha256 = input.receiptSha256;
+        this.#store = input.store;
+    }
+    static async open(input) {
+        const capturedNow = await captureLocalPreviewSource({ project_root: input.project_root });
+        if (input.capture !== undefined && input.capture.identity.capture_sha256 !== capturedNow.identity.capture_sha256) {
+            throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "外部 local Preview capture 与当前 Project immutable capture 不一致");
+        }
+        const capture = capturedNow;
+        const profile = Object.freeze({
+            schema_version: 1,
+            compiler_release: "tmw.compiler.semantic-v2",
+            runtime_semantics: "tmw3.semantic-v2",
+            sdk_schema: "chatplay.v3",
+            artifact_format: "artifact.v5",
+            stage_versions: CURRENT_NEUTRAL_COMPILER_STAGE_VERSIONS,
+        });
+        const compilation = await compileNeutralScenarioSource({
+            witness: { scenario_id: capture.identity.local_scenario_id, manifest_digest: capture.identity.neutral_manifest_sha256 },
+            manifest: capture.manifest,
+            sections: capture.sections,
+        }, profile, buildCurrentTmw3NeutralCompilerStageRegistry(profile), new InMemoryCompilerStageCache());
+        if (!compilation.ok) {
+            throw new AuthoringBridgeError("E_VALIDATION_FAILED", `本地 Preview 编译失败：${compilation.diagnostics.map((item) => item.code).join(",")}`);
+        }
+        const trigger = compilation.derived_objects.find((object) => object.stage_id === "tmw.trigger-semantics");
+        if (trigger === undefined)
+            throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "本地 Preview 缺少 TMW compiled plan");
+        let compiledPlan;
+        try {
+            compiledPlan = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(trigger.bytes));
+        }
+        catch {
+            throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "本地 Preview TMW compiled plan 无效");
+        }
+        if (compiledPlan.plan_version !== 3 || await tmwSha256Hex(trigger.bytes) !== trigger.sha256) {
+            throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "本地 Preview compiled plan 未绑定 stage 输出");
+        }
+        const directory = await ensureSafeProjectDirectory(input.project_root, `.worldengine/local-player-preview/${capture.identity.capture_sha256}`);
+        const savePath = await safeProjectPath(input.project_root, `.worldengine/local-player-preview/${capture.identity.capture_sha256}/runtime-sav.v1.json`);
+        const initial = await createInitialSav(capture, compiledPlan);
+        const binding = planBinding(capture, compiledPlan);
+        let stored = await readSavedEnvelope(savePath, capture.identity.capture_sha256, binding);
+        if (stored === null) {
+            const logicalGraph = previewSectionJson(capture, "logical_graph");
+            const bound = localPreviewBoundResourcesFromLogicalGraph(logicalGraph);
+            const worldProjection = createLocalPreviewWorldProjection(logicalGraph);
+            await writeSavedEnvelope(input.project_root, directory, savePath, capture.identity.capture_sha256, { sav: initial, projection: Object.freeze({ ...worldProjection, frozen_attribute_resource_refs: Object.freeze(bound.frozen_attribute_resource_refs.map((ref) => Object.freeze({ ...ref, visibility: "unlocked" }))), scenario_runtime_state: Object.freeze({ ...worldProjection.scenario_runtime_state, unlocked_resource_ids: bound.initial_unlocked_resource_ids }) }), receipts: Object.freeze({}) });
+            stored = await readSavedEnvelope(savePath, capture.identity.capture_sha256, binding);
+            if (stored === null)
+                throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "本地 Preview SAV 创建后丢失");
+        }
+        const store = LocalPreviewActivationStore.open(directory, stored, capture.identity.capture_sha256);
+        const sav = store.currentSav();
+        const runtime = createTmwRuntimeHost({
+            binding: {
+                epoch: sav.epoch,
+                runtimeGeneration: 3,
+                runtimeContractHash: sav.runtimeContractHash,
+                artifactDigest: sav.artifactDigest,
+                sourceRevision: sav.sourceRevision,
+                timelineRevision: sav.activeTimelineRevision,
+                leaseId: `local.preview.${capture.identity.capture_sha256.slice(0, 24)}`,
+            },
+            compiledPlan,
+            capabilityRegistry: getCanonicalTmwCapabilityRegistryV3(),
+        });
+        runtime.restore(sav);
+        store.configureWorldlines(Object.freeze({ authority: "worldengine.local-preview-worldlines/v1", authorNamespace: "local-preview", projectId: capture.identity.project_id, scenarioId: capture.identity.local_scenario_id, saveId: `local.preview.${capture.identity.capture_sha256.slice(0, 24)}`, captureSha256: capture.identity.capture_sha256 }));
+        store.configureMessages(Object.freeze({ captureId: capture.identity.capture_sha256, saveId: `local.preview.${capture.identity.capture_sha256.slice(0, 24)}`, worldlineScope: Object.freeze({ authority: "worldengine.local-preview-worldlines/v1", authorNamespace: "local-preview", projectId: capture.identity.project_id, scenarioId: capture.identity.local_scenario_id, saveId: `local.preview.${capture.identity.capture_sha256.slice(0, 24)}`, captureSha256: capture.identity.capture_sha256 }) }));
+        return new LocalPreviewRuntime({ capture, compiledPlan, runtime, savePath, receiptSha256: compilation.receipt.receipt_sha256, store });
+    }
+    inspect() {
+        return Object.freeze({ development_preview: true, capture_sha256: this.#capture.identity.capture_sha256, project_id: this.#capture.identity.project_id, scenario_id: this.#capture.identity.local_scenario_id, compiler_receipt_sha256: this.#receiptSha256, compiled_plan_sha256: this.#compiledPlan.plan_sha256, save_path: this.#savePath, event_execution: "local_deterministic" });
+    }
+    readScene() { return this.#sav().scene; }
+    readVariable(name, scope) { return readTmwVariableV1(this.#sav().gameplayState ?? emptyTmwGameplayStateV1(), name, scope); }
+    readUnlock(kind, id) { return readTmwUnlockV1(this.#sav().gameplayState ?? emptyTmwGameplayStateV1(), kind, id); }
+    readViewInteractionBinding() {
+        const sav = this.#sav();
+        return structuredClone(Object.freeze({ source: previewSectionJson(this.#capture, "layout"), epoch: sav.epoch, artifact_digest: sav.artifactDigest, runtime_contract_hash: sav.runtimeContractHash }));
+    }
+    async openViewState(viewId) {
+        const port = this.#store.openViewState(Object.freeze({ captureId: this.#capture.identity.capture_sha256, namespace: "chatplay.custom-state.v1", saveId: `local.preview.${this.#capture.identity.capture_sha256.slice(0, 24)}`, viewId: requireId(viewId, "view_id") }));
+        await port.initialize(Object.freeze({ captureId: this.#capture.identity.capture_sha256, namespace: "chatplay.custom-state.v1", saveId: `local.preview.${this.#capture.identity.capture_sha256.slice(0, 24)}`, viewId }));
+        return port;
+    }
+    async appendAcceptedUserMessage(input) {
+        const sav = this.#sav();
+        return await this.#store.messages().appendAcceptedUserMessage({ operationId: requireId(input.operation_id, "user operation_id"), turnId: requireId(input.turn_id, "user turn_id"), messageId: requireId(input.message_id, "user message_id"), text: input.text, activeWorldlineId: sav.activeTimeline.worldlineId, expectedRuntimeHead: { revisionId: sav.activeTimeline.revisionId, revisionSequence: sav.activeTimeline.revisionSequence, ledgerHead: sav.ledgerHead } });
+    }
+    async readCommittedMessages() {
+        return this.#store.messages().listCurrentWorldline();
+    }
+    /** 仅恢复指定 operation 仍在当前 SAV 中、且可由 source ledger 精确验证的 View 事件；不扫描历史。 */
+    readAuthorViewEventsByOperation(operationIdInput) {
+        const operationId = requireId(operationIdInput, "author view operation_id");
+        const sav = this.#sav();
+        const eventId = operationId.startsWith("tmw3:") || operationId.startsWith("local.preview.event.") ? operationId : `local.preview.event.${operationId}`;
+        const recovered = this.#store.readAuthorViewEvents(`tmw3:event:${eventId}`, sav);
+        if (recovered === null)
+            throw new AuthoringBridgeError("E_REFERENCE_MISSING", "指定 operation 没有已提交的 author View delivery");
+        return recovered;
+    }
+    playerReadModels() { return new LocalPreviewPlayerReadModels({ readCommittedPlayerReadModel: async () => { const projection = this.#store.currentProjection(); if (!Object.hasOwn(projection, "frozen_attribute_resource_refs"))
+            throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "local Preview resource refs 尚未由 source capture 初始化"); return Object.freeze({ scenario_runtime_state: projection.scenario_runtime_state, frozen_attribute_resource_refs: projection.frozen_attribute_resource_refs }); } }); }
+    /** Host-only facade; it reuses activation.sqlite and never exposes DatabaseSync to iframe code. */
+    worldlineRuntime() {
+        const store = this.#store.openWorldlines(this.#worldlineScope());
+        return Object.freeze({
+            snapshotWorldlines: () => store.snapshotWorldlines(), listWorldlines: (scope) => store.listWorldlines(scope),
+            forkWorldlineAtMessage: async (scope, input) => { const result = await store.forkWorldlineAtMessage(scope, input); await this.#restoreCheckedOutWorldline(); return result; },
+            activateWorldline: async (scope, input) => { const result = await store.activateWorldline(scope, input); await this.#restoreCheckedOutWorldline(); return result; },
+        });
+    }
+    async prepareWriterTurn(input) {
+        const operationId = requireId(input.operation_id, "writer operation_id");
+        const turnId = requireId(input.turn_id, "writer turn_id");
+        const sav = this.#sav();
+        const core = { operation_id: operationId, turn_id: turnId, capture_sha256: this.#capture.identity.capture_sha256, timeline_revision: sav.activeTimelineRevision, ledger_head: sav.ledgerHead, worldline_id: sav.activeTimeline.worldlineId, world_time: sav.scene?.worldTime ?? null };
+        const prepared = Object.freeze({ ...core, identity: await tmwSha256Hex(canonicalTmwBytes(core)), scene: structuredClone(sav.scene) });
+        this.#writerPreparations.set(prepared.identity, prepared);
+        return prepared;
+    }
+    async commitSuccessfulWriterResult(input) {
+        const prepared = this.#writerPreparations.get(input.prepare_identity);
+        if (prepared === undefined)
+            throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "writer preparation 不存在或已失效");
+        if (typeof input.text !== "string" || input.text.length === 0 || input.text.length > 64 * 1024)
+            throw new AuthoringBridgeError("E_VALIDATION_FAILED", "writer text 无效");
+        const messageId = requireId(input.message_id, "writer message_id");
+        if (!Array.isArray(input.ordered_message_ids) || input.ordered_message_ids.at(-1) !== messageId)
+            throw new AuthoringBridgeError("E_VALIDATION_FAILED", "writer message 顺序无效");
+        const requestDigest = await tmwSha256Hex(canonicalTmwBytes({ prepared: input.prepare_identity, text: input.text, messageId, ordered: input.ordered_message_ids, writerReceiptDigest: input.writer_receipt_digest }));
+        const existing = await this.#store.prepareRequest(prepared.operation_id, requestDigest);
+        if (existing !== null)
+            return Object.freeze({ status: "already_committed", message_id: messageId });
+        const sav = this.#sav();
+        if (sav.activeTimelineRevision !== prepared.timeline_revision || sav.ledgerHead !== prepared.ledger_head)
+            throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "writer preparation head 已改变");
+        const noteConsumption = sav.scene === null ? null : Object.freeze({ sceneRevision: sav.scene.revision, noteIds: sav.scene.manuscriptNotes.filter((note) => note.lifetime === "once").map((note) => note.noteId) });
+        this.#store.stageProjection(prepared.operation_id, this.#store.currentProjection());
+        this.#store.stageWriterCommit(prepared.operation_id, { messageId, turnId: prepared.turn_id, text: input.text, orderedMessageIds: input.ordered_message_ids });
+        try {
+            const result = await this.#runtime.commitSuccessfulWriterTurn({ operationId: prepared.operation_id, turnId: prepared.turn_id, worldlineId: prepared.worldline_id, logicalSeq: sav.activeTimeline.revisionSequence + 1, worldTime: prepared.world_time, writerReceiptDigest: input.writer_receipt_digest, noteConsumption, pendingClockCrossings: input.pending_clock_crossings ?? Object.freeze([]) }, this.#store);
+            return Object.freeze({ status: result.status, message_id: messageId });
+        }
+        catch (error) {
+            this.#store.cancelPreparedRequest(prepared.operation_id);
+            this.#store.rollbackProjection(prepared.operation_id);
+            if (error instanceof AuthoringBridgeError)
+                throw error;
+            throw new AuthoringBridgeError("E_VALIDATION_FAILED", error instanceof Error ? error.message : "writer commit 失败");
+        }
+    }
+    readCommittedWriterMessage(messageId) { return this.#store.readMessage(requireId(messageId, "writer message_id")); }
+    /** Host-only typed input for a separate allowlisted View projector; never expose this object directly through iframe RPC. */
+    readProjectionSnapshot() {
+        const sav = this.#sav();
+        const gameplay = sav.gameplayState ?? emptyTmwGameplayStateV1();
+        return structuredClone(Object.freeze({
+            kind: "worldengine.local-preview-projection/v1", development_preview: true,
+            capture_identity: this.#capture.identity, scene: sav.scene,
+            gameplay: Object.freeze({
+                save_variables: gameplay.variables.filter((item) => item.scope === "save"),
+                unlocks: Object.freeze(Object.fromEntries(Object.keys(gameplay.entity_state_stacks).map((key) => [key,
+                    readTmwUnlockV1(gameplay, key.startsWith("edge:") ? "edge" : "node", key.slice(key.indexOf(":") + 1)),
+                ]))),
+                object_states: gameplay.entity_state_stacks,
+            }),
+            world_projection: this.#store.currentProjection(),
+            source_projection: Object.freeze({ metadata: previewSectionJson(this.#capture, "metadata"), logical_graph: previewSectionJson(this.#capture, "logical_graph"), resource_refs: previewSectionJson(this.#capture, "resource_refs") }),
+            runtime: Object.freeze({ timeline_revision: sav.activeTimelineRevision, ledger_head: sav.ledgerHead }),
+        }));
+    }
+    dispose() { this.#runtime.dispose(); this.#store.dispose(); }
+    /** 本地开发 Runtime：无远端 lease/head；同一 operation_id 读取已持久 receipt，不重复执行。 */
+    async executeEvent(input) {
+        try {
+            return await this.#executeEvent(input);
+        }
+        catch (error) {
+            if (error instanceof AuthoringBridgeError)
+                throw error;
+            throw new AuthoringBridgeError("E_VALIDATION_FAILED", error instanceof Error ? error.message : "local Preview event 执行失败");
+        }
+    }
+    /** Host-only：仅消费当前 SAV 已到期的 pending crossing；不创建或推进新的时钟事件。 */
+    async drainPendingSceneCrossings(input) {
+        const turnId = requireId(input.turn_id, "drain turn_id");
+        const maximum = input.max_events ?? 16;
+        if (!Number.isSafeInteger(maximum) || maximum < 1 || maximum > 64)
+            throw new AuthoringBridgeError("E_VALIDATION_FAILED", "drain max_events 无效");
+        const receipts = [];
+        for (let count = 0; count < maximum; count += 1) {
+            const sav = this.#sav();
+            const pending = sav.pendingSceneClockCrossings[0];
+            if (pending === undefined)
+                break;
+            const eventId = requireId(pending.eventId, "pending event_id");
+            const eventType = requireId(pending.eventType, "pending event_type");
+            const payload = canonicalTmwJsonValue(pending.payload, "pending payload");
+            const runtimeOperationId = `tmw3:event:${eventId}`;
+            const requestDigest = await tmwSha256Hex(canonicalTmwBytes({ eventId, eventType, payload, payloadHash: pending.payloadHash, commitReceiptDigest: pending.commitReceiptDigest, logicalSeq: pending.logicalSeq, worldTime: pending.worldTime, crossingDirection: pending.crossingDirection, turnId }));
+            const existing = await this.#store.prepareRequest(runtimeOperationId, requestDigest);
+            if (existing !== null) {
+                receipts.push(Object.freeze({ status: "already_committed", operation_id: eventId, author_view_events: Object.freeze([]) }));
+                break;
+            }
+            const context = this.#runtime.viewEventCommitContext(eventType, { coordinates: Object.freeze({ logicalSeq: pending.logicalSeq, worldTime: pending.worldTime, presentation: null, realTime: null }), crossingDirection: pending.crossingDirection });
+            const record = payload;
+            const event = Object.freeze({ eventId, eventType, hardFact: context.hardFact, epoch: sav.epoch, runtimeGeneration: 3, runtimeContractHash: sav.runtimeContractHash, artifactDigest: sav.artifactDigest, sourceRevision: sav.sourceRevision, timelineRevision: sav.activeTimelineRevision, scope: Object.freeze({ scenarioId: this.#capture.identity.local_scenario_id, saveId: `local.preview.${this.#capture.identity.capture_sha256.slice(0, 24)}`, worldlineId: sav.activeTimeline.worldlineId }), coordinates: context.coordinates, effectiveTime: context.effectiveTime, crossingDirection: context.crossingDirection, correlationId: typeof record.correlationId === "string" ? record.correlationId : turnId, causationId: typeof record.causationId === "string" ? record.causationId : null, replacementLineage: Object.freeze([]), payload, payloadHash: pending.payloadHash, commitReceiptDigest: pending.commitReceiptDigest });
+            try {
+                const receipt = await this.#runtime.executeCommittedEvent(event, this.#ports());
+                if (receipt.activation.status === "conflict")
+                    throw new Error("local_preview_activation_conflict");
+                receipts.push(Object.freeze({ status: receipt.activation.status === "already_committed" ? "already_committed" : "committed", operation_id: eventId, author_view_events: receipt.authorViewEvents }));
+            }
+            catch (error) {
+                this.#store.cancelPreparedRequest(runtimeOperationId);
+                throw error;
+            }
+        }
+        return Object.freeze(receipts);
+    }
+    async #executeEvent(input) {
+        const eventType = requireId(input.event_type, "event_type");
+        const operationId = requireId(input.operation_id, "operation_id");
+        const turnId = requireId(input.turn_id, "turn_id");
+        const payload = canonicalTmwJsonValue(input.payload, "local_preview_event_payload");
+        const sav = this.#sav();
+        const worldTime = input.world_time === undefined ? sav.scene?.worldTime ?? null : input.world_time;
+        if (worldTime !== null && !Number.isFinite(worldTime))
+            throw new AuthoringBridgeError("E_VALIDATION_FAILED", "local Preview world_time 无效");
+        const requestDigest = await tmwSha256Hex(canonicalTmwBytes({ eventType, payload, operationId, turnId, worldTime }));
+        const eventId = `local.preview.event.${operationId}`;
+        const runtimeOperationId = `tmw3:event:${eventId}`;
+        const existing = await this.#store.prepareRequest(runtimeOperationId, requestDigest);
+        if (existing !== null)
+            return Object.freeze({ status: "already_committed", operation_id: operationId, author_view_events: Object.freeze([]) });
+        const context = this.#runtime.viewEventCommitContext(eventType, { coordinates: Object.freeze({ logicalSeq: sav.activeTimeline.revisionSequence, worldTime, presentation: null, realTime: null }), crossingDirection: "forward" });
+        const payloadHash = await tmwSha256Hex(canonicalTmwBytes(payload));
+        const event = Object.freeze({ eventId, eventType, hardFact: context.hardFact, epoch: sav.epoch, runtimeGeneration: 3, runtimeContractHash: sav.runtimeContractHash, artifactDigest: sav.artifactDigest, sourceRevision: sav.sourceRevision, timelineRevision: sav.activeTimelineRevision, scope: Object.freeze({ scenarioId: this.#capture.identity.local_scenario_id, saveId: `local.preview.${this.#capture.identity.capture_sha256.slice(0, 24)}`, worldlineId: sav.activeTimeline.worldlineId }), coordinates: context.coordinates, effectiveTime: context.effectiveTime, crossingDirection: context.crossingDirection, correlationId: turnId, causationId: null, replacementLineage: Object.freeze([]), payloadHash, payload, commitReceiptDigest: await tmwSha256Hex(canonicalTmwBytes({ operationId, payloadHash })) });
+        try {
+            const receipt = await this.#runtime.executeCommittedEvent(event, this.#ports());
+            if (receipt.activation.status === "conflict")
+                throw new Error("local_preview_activation_conflict");
+            return Object.freeze({ status: receipt.activation.status === "already_committed" ? "already_committed" : "committed", operation_id: operationId, author_view_events: receipt.authorViewEvents });
+        }
+        catch (error) {
+            this.#store.cancelPreparedRequest(runtimeOperationId);
+            throw error;
+        }
+    }
+    #sav() { const sav = this.#runtime.restoredSav(); if (sav === null)
+        throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "本地 Preview Runtime 缺少 SAV"); return sav; }
+    #worldlineScope() { return Object.freeze({ authority: "worldengine.local-preview-worldlines/v1", authorNamespace: "local-preview", projectId: this.#capture.identity.project_id, scenarioId: this.#capture.identity.local_scenario_id, saveId: `local.preview.${this.#capture.identity.capture_sha256.slice(0, 24)}`, captureSha256: this.#capture.identity.capture_sha256 }); }
+    async #restoreCheckedOutWorldline() {
+        const sav = this.#store.currentSav();
+        const binding = Object.freeze({ epoch: sav.epoch, runtimeGeneration: 3, runtimeContractHash: sav.runtimeContractHash, artifactDigest: sav.artifactDigest, sourceRevision: sav.sourceRevision, timelineRevision: sav.activeTimelineRevision, leaseId: `local.preview.${this.#capture.identity.capture_sha256.slice(0, 24)}` });
+        this.#runtime.dispose();
+        try {
+            const next = createTmwRuntimeHost({ binding, compiledPlan: this.#compiledPlan, capabilityRegistry: getCanonicalTmwCapabilityRegistryV3() });
+            next.restore(sav);
+            this.#runtime = next;
+            this.#writerPreparations.clear();
+        }
+        catch (error) {
+            throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", error instanceof Error ? `worldline checkout restore 失败：${error.message}` : "worldline checkout restore 失败");
+        }
+    }
+    #ports() {
+        return Object.freeze({
+            semanticJudge: { async judge() { throw new Error("local_preview_semantic_judge_unavailable"); } },
+            effectCommit: {
+                prepareWorldMutation: async (value) => Object.freeze({ bindingId: `local.preview.effect.${value.operationId}`, operationId: value.operationId, turnId: value.turnId }),
+                stage: async (value) => {
+                    this.#store.stageProjection(value.operationId, reduceLocalPreviewWorldEffects(this.#store.currentProjection(), value.plans));
+                    return Object.freeze({ preActivationTerminalDigest: await tmwSha256Hex(canonicalTmwBytes({ operationId: value.operationId, eventId: value.event.eventId, effects: value.plans.flatMap((plan) => plan.effects.map((effect) => effect.effectId)) })), worldMutationRecoveryOperation: null });
+                }, finalizeWorldMutation: async (value) => { this.#store.finalizeProjection(value.operationId); }, rollbackWorldMutation: async (value) => { this.#store.rollbackProjection(value.operationId); },
+            }, activation: this.#store,
+            verifiedAuthorViewOutbox: {
+                stage: async (value) => { this.#store.stageVerifiedAuthorViewEvents({ operationId: value.operationId, ...value.binding, events: value.events }); },
+                rollback: async (value) => { this.#store.rollbackVerifiedAuthorViewEvents(value.operationId); },
+            },
+        });
+    }
+}
+function metadataScene(capture) {
+    const metadata = capture.sections.find((section) => section.section_key === "metadata");
+    if (metadata === undefined || metadata.payload.byteLength === 0)
+        return null;
+    const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(metadata.payload));
+    const record = value.metadata !== undefined && value.metadata !== null ? value.metadata : value;
+    if (typeof record !== "object" || record === null || Array.isArray(record))
+        throw new Error("local_preview_metadata_invalid");
+    return initialTmwSceneFromMetadata(record);
+}
+function previewSectionJson(capture, sectionKey) {
+    const section = capture.sections.find((item) => item.section_key === sectionKey);
+    if (section === undefined || section.payload.byteLength === 0)
+        return null;
+    try {
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(section.payload));
+    }
+    catch {
+        return null;
+    }
+}
+async function createInitialSav(capture, plan) {
+    const [narrativeDigest, emptyDigest] = await Promise.all([tmwSha256Hex(canonicalTmwBytes({})), tmwSha256Hex(canonicalTmwBytes([]))]);
+    const sourceRevision = `local.preview.${capture.identity.capture_sha256.slice(0, 24)}`;
+    const timelineRevision = `${sourceRevision}.timeline.0`;
+    const scene = metadataScene(capture);
+    return Object.freeze({
+        schemaVersion: 3, epoch: 1, runtimeGeneration: 3, runtimeContractHash: plan.runtime_contract_hash,
+        artifactDigest: plan.plan_sha256, sourceRevision, activeTimelineRevision: timelineRevision,
+        turnId: "local.preview.fresh", preActivationTerminalDigest: ZERO_SHA256,
+        activeTimeline: Object.freeze({ revisionId: timelineRevision, parentRevisionId: null, revisionSequence: 0, epoch: 1, runtimeGeneration: 3, runtimeContractHash: plan.runtime_contract_hash, artifactDigest: plan.plan_sha256, sourceRevision, worldlineId: `${sourceRevision}.worldline`, operationId: "local.preview.fresh", ledgerHead: "0".repeat(64), narrativeDigest, savSectionDigest: ZERO_SHA256, intentSetDigest: emptyDigest, presentationIntentSetDigest: emptyDigest, createdFrom: "fresh", active: true }),
+        ledgerHead: "0".repeat(64), eventLedger: Object.freeze({ events: Object.freeze([]) }), narrative: Object.freeze({}), scene,
+        gameplayState: emptyTmwGameplayStateV1(), pendingSceneClockCrossings: Object.freeze([]), scheduler: Object.freeze({ cursor: scene === null ? null : Object.freeze({ logicalSeq: 0, worldTime: 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([]),
+    });
+}
+function planBinding(capture, plan) {
+    const sourceRevision = `local.preview.${capture.identity.capture_sha256.slice(0, 24)}`;
+    return Object.freeze({ runtimeContractHash: plan.runtime_contract_hash, artifactDigest: plan.plan_sha256, sourceRevision });
+}
+function requireId(value, field) {
+    if (typeof value !== "string" || !/^[A-Za-z0-9._:-]{1,128}$/u.test(value))
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", `local Preview ${field} 无效`);
+    return value;
+}
+class LocalPreviewActivationStore {
+    #db;
+    #captureSha256;
+    #pendingRequestDigests = new Map();
+    #pendingProjections = new Map();
+    #pendingWriters = new Map();
+    #pendingAuthorViewEvents = new Map();
+    #worldlines = null;
+    #messages = null;
+    constructor(directory, initial, captureSha256) {
+        this.#captureSha256 = captureSha256;
+        this.#db = new DatabaseSync(`${directory}/activation.sqlite`);
+        this.#db.exec("CREATE TABLE IF NOT EXISTS local_preview_state (key TEXT PRIMARY KEY, value TEXT NOT NULL); CREATE TABLE IF NOT EXISTS local_preview_receipt (operation_id TEXT PRIMARY KEY, value TEXT NOT NULL); CREATE TABLE IF NOT EXISTS local_preview_request (operation_id TEXT PRIMARY KEY, digest TEXT NOT NULL); CREATE TABLE IF NOT EXISTS local_preview_message (message_id TEXT PRIMARY KEY, operation_id TEXT UNIQUE NOT NULL, role TEXT NOT NULL CHECK(role='assistant'), text TEXT NOT NULL); CREATE TABLE IF NOT EXISTS local_preview_author_view_outbox (operation_id TEXT PRIMARY KEY, capture_sha256 TEXT NOT NULL, epoch INTEGER NOT NULL, artifact_digest TEXT NOT NULL, source_revision TEXT NOT NULL, timeline_revision TEXT NOT NULL, save_id TEXT NOT NULL, worldline_id TEXT NOT NULL, events_json TEXT NOT NULL);");
+        const count = this.#db.prepare("SELECT COUNT(*) AS n FROM local_preview_state").get();
+        if (count.n === 0) {
+            this.#db.exec("BEGIN IMMEDIATE");
+            try {
+                for (const [key, value] of Object.entries(stateValues(initial.sav, initial.projection)))
+                    this.#db.prepare("INSERT INTO local_preview_state(key,value) VALUES (?,?)").run(key, JSON.stringify(value));
+                for (const [operationId, receipt] of Object.entries(initial.receipts))
+                    this.#db.prepare("INSERT INTO local_preview_receipt(operation_id,value) VALUES (?,?)").run(operationId, JSON.stringify(receipt));
+                this.#db.exec("COMMIT");
+            }
+            catch (error) {
+                this.#db.exec("ROLLBACK");
+                throw error;
+            }
+        }
+    }
+    static open(directory, initial, captureSha256) { return new LocalPreviewActivationStore(directory, initial, captureSha256); }
+    dispose() { this.#db.close(); }
+    currentSav() {
+        const row = this.#db.prepare("SELECT value FROM local_preview_state WHERE key='sav'").get();
+        if (row === undefined)
+            throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "本地 Preview activation store 缺少 SAV");
+        return JSON.parse(row.value);
+    }
+    currentProjection() {
+        const row = this.#db.prepare("SELECT value FROM local_preview_state WHERE key='projection'").get();
+        if (row === undefined)
+            throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "本地 Preview activation store 缺少 world projection");
+        return JSON.parse(row.value);
+    }
+    stageProjection(operationId, projection) { this.#pendingProjections.set(operationId, projection); }
+    finalizeProjection(operationId) { this.#pendingProjections.delete(operationId); }
+    rollbackProjection(operationId) { this.#pendingProjections.delete(operationId); }
+    configureWorldlines(scope) { this.#worldlines = new LocalPreviewWorldlineStore({ database: this.#db, scope }); }
+    openWorldlines(scope) { this.#worldlines ??= new LocalPreviewWorldlineStore({ database: this.#db, scope }); return this.#worldlines; }
+    configureMessages(scope) { this.#messages = new LocalPreviewMessageStore({ database: this.#db, scope }); }
+    messages() { if (this.#messages === null)
+        throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "local Preview message store 未配置"); return this.#messages; }
+    openViewState(scope) { return new LocalPreviewViewStateSqlitePort({ database: this.#db, scope }); }
+    stageWriterCommit(operationId, value) { this.#pendingWriters.set(operationId, value); }
+    readMessage(messageId) { const row = this.#db.prepare("SELECT message_id,text FROM local_preview_message WHERE message_id=?").get(messageId); return row === undefined ? null : Object.freeze(row); }
+    stageVerifiedAuthorViewEvents(input) { this.#pendingAuthorViewEvents.set(input.operationId, Object.freeze({ ...input, events: Object.freeze(input.events.map((event) => Object.freeze({ ...event, viewVisiblePayload: Object.freeze({ ...event.viewVisiblePayload }) }))) })); }
+    rollbackVerifiedAuthorViewEvents(operationId) { this.#pendingAuthorViewEvents.delete(operationId); }
+    readAuthorViewEvents(operationId, sav) { const row = this.#db.prepare("SELECT capture_sha256,epoch,artifact_digest,source_revision,timeline_revision,save_id,worldline_id,events_json FROM local_preview_author_view_outbox WHERE operation_id=?").get(operationId); if (row === undefined)
+        return null; if (row.capture_sha256 !== this.#captureSha256 || row.epoch !== sav.epoch || row.artifact_digest !== sav.artifactDigest || row.source_revision !== sav.sourceRevision || row.worldline_id !== sav.activeTimeline.worldlineId)
+        throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "author View outbox binding 不匹配"); const events = JSON.parse(row.events_json); if (!Array.isArray(events))
+        throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "author View outbox 损坏"); return Object.freeze(events); }
+    async prepareRequest(operationId, digest) {
+        const receipt = await this.readByOperation(operationId);
+        if (receipt === null) {
+            this.#pendingRequestDigests.set(operationId, digest);
+            return null;
+        }
+        const row = this.#db.prepare("SELECT digest FROM local_preview_request WHERE operation_id=?").get(operationId);
+        if (row === undefined || row.digest !== digest)
+            throw new AuthoringBridgeError("E_OPERATION_ID_CONFLICT", "local Preview operation_id 已绑定不同请求");
+        return receipt;
+    }
+    cancelPreparedRequest(operationId) { this.#pendingRequestDigests.delete(operationId); }
+    async readByOperation(operationId) {
+        const row = this.#db.prepare("SELECT value FROM local_preview_receipt WHERE operation_id=?").get(operationId);
+        return row === undefined ? null : JSON.parse(row.value);
+    }
+    async commitAtomic(candidate) {
+        const requestDigest = this.#pendingRequestDigests.get(candidate.operationId);
+        if (requestDigest === undefined)
+            throw new Error("local_preview_operation_not_prepared");
+        const decoded = await decodeRuntimeSavSectionSelfBound(candidate.savSection);
+        const candidateDigest = await tmwActivationCandidateDigest(candidate);
+        this.#db.exec("BEGIN IMMEDIATE");
+        try {
+            const existing = this.#db.prepare("SELECT value FROM local_preview_receipt WHERE operation_id=?").get(candidate.operationId);
+            if (existing !== undefined) {
+                this.#db.exec("COMMIT");
+                return JSON.parse(existing.value);
+            }
+            const head = JSON.parse(this.#db.prepare("SELECT value FROM local_preview_state WHERE key='head'").get().value);
+            const expected = candidate.expectedHead;
+            if (expected === null || expected.revisionId !== head.revisionId || expected.revisionSequence !== head.revisionSequence || expected.ledgerHead !== head.ledgerHead) {
+                const receipt = await localReceipt(candidate.operationId, "conflict", expected, head, 0, candidateDigest);
+                this.#db.exec("COMMIT");
+                return receipt;
+            }
+            const projection = this.#pendingProjections.get(candidate.operationId);
+            if (projection === undefined)
+                throw new Error("local_preview_projection_not_staged");
+            const progressed = withScenarioRuntimeRevision(projection, candidate.timeline.revisionSequence);
+            for (const [key, value] of Object.entries(stateValues(decoded, progressed)))
+                this.#db.prepare("INSERT OR REPLACE INTO local_preview_state(key,value) VALUES (?,?)").run(key, JSON.stringify(value));
+            const nextHead = Object.freeze({ revisionId: candidate.timeline.revisionId, revisionSequence: candidate.timeline.revisionSequence, ledgerHead: candidate.ledgerHead });
+            const receipt = await localReceipt(candidate.operationId, "committed", head, nextHead, 5, candidateDigest);
+            this.#db.prepare("INSERT INTO local_preview_receipt(operation_id,value) VALUES (?,?)").run(candidate.operationId, JSON.stringify(receipt));
+            this.#db.prepare("INSERT INTO local_preview_request(operation_id,digest) VALUES (?,?)").run(candidate.operationId, requestDigest);
+            const writer = this.#pendingWriters.get(candidate.operationId);
+            if (writer !== undefined) {
+                this.#db.prepare("INSERT INTO local_preview_message(message_id,operation_id,role,text) VALUES (?,?,?,?)").run(writer.messageId, candidate.operationId, "assistant", writer.text);
+                this.messages().recordCommittedAssistantInTransaction({ operationId: candidate.operationId, turnId: writer.turnId, messageId: writer.messageId, text: writer.text, activeWorldlineId: decoded.activeTimeline.worldlineId, orderedMessageIds: writer.orderedMessageIds });
+                if (this.#worldlines === null)
+                    throw new Error("local_preview_worldline_store_missing");
+                this.#worldlines.recordCommittedMessageCheckpointInTransaction({ messageId: writer.messageId, orderedMessageIds: writer.orderedMessageIds, sav: decoded, createdAtMs: Date.now() });
+            }
+            const authorView = this.#pendingAuthorViewEvents.get(candidate.operationId);
+            if (authorView !== undefined)
+                this.#db.prepare("INSERT INTO local_preview_author_view_outbox(operation_id,capture_sha256,epoch,artifact_digest,source_revision,timeline_revision,save_id,worldline_id,events_json) VALUES (?,?,?,?,?,?,?,?,?)").run(candidate.operationId, this.#captureSha256, authorView.epoch, authorView.artifactDigest, authorView.sourceRevision, candidate.timeline.revisionId, authorView.saveId, authorView.worldlineId, JSON.stringify(authorView.events));
+            this.#db.exec("COMMIT");
+            return receipt;
+        }
+        catch (error) {
+            try {
+                this.#db.exec("ROLLBACK");
+            }
+            catch { }
+            throw error;
+        }
+        finally {
+            this.#pendingRequestDigests.delete(candidate.operationId);
+            this.#pendingProjections.delete(candidate.operationId);
+            this.#pendingWriters.delete(candidate.operationId);
+            this.#pendingAuthorViewEvents.delete(candidate.operationId);
+        }
+    }
+}
+function stateValues(sav, projection) {
+    return Object.freeze({ head: Object.freeze({ revisionId: sav.activeTimeline.revisionId, revisionSequence: sav.activeTimeline.revisionSequence, ledgerHead: sav.ledgerHead }), sav, ledger: sav.eventLedger, narrative: sav.narrative, intents: sav.durableIntents, presentations: sav.presentationIntents, projection });
+}
+function withScenarioRuntimeRevision(projection, revision) {
+    const state = projection.scenario_runtime_state;
+    if (typeof state !== "object" || state === null || Array.isArray(state))
+        throw new Error("local_preview_scenario_runtime_state_missing");
+    return Object.freeze({ ...projection, scenario_runtime_state: Object.freeze({ ...state, schema_version: 1, state_revision: String(revision) }) });
+}
+async function localReceipt(operationId, status, previousHead, activeHead, atomicWriteCount, candidateDigest) {
+    const core = { operationId, status, previousHead, activeHead, atomicWriteCount, candidateDigest };
+    return Object.freeze({ ...core, receiptDigest: await tmwSha256Hex(canonicalTmwBytes(core)) });
+}
+async function readSavedEnvelope(path, captureSha256, binding) {
+    let bytes;
+    try {
+        bytes = new Uint8Array(await readFile(path));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    let envelope;
+    try {
+        envelope = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "本地 Preview SAV 损坏");
+    }
+    if (envelope.schema_version !== SAVE_SCHEMA_VERSION || envelope.capture_sha256 !== captureSha256 || !envelope.sav || typeof envelope.sav !== "object")
+        throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "本地 Preview SAV 与 capture 不匹配");
+    const sav = envelope.sav;
+    if (sav.epoch !== 1 || sav.runtimeGeneration !== 3 || sav.runtimeContractHash !== binding.runtimeContractHash
+        || sav.artifactDigest !== binding.artifactDigest || sav.sourceRevision !== binding.sourceRevision) {
+        throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "本地 Preview SAV runtime binding 不匹配");
+    }
+    return Object.freeze({ sav, projection: envelope.projection && typeof envelope.projection === "object" && !Array.isArray(envelope.projection) ? envelope.projection : createLocalPreviewWorldProjection({}), receipts: envelope.receipts && typeof envelope.receipts === "object" && !Array.isArray(envelope.receipts) ? envelope.receipts : Object.freeze({}) });
+}
+async function writeSavedEnvelope(root, directory, path, captureSha256, value) {
+    const tmp = await safeProjectPath(root, `.worldengine/local-player-preview/${captureSha256}/runtime-sav.${randomUUID()}.tmp`);
+    await writeFile(tmp, `${JSON.stringify({ schema_version: SAVE_SCHEMA_VERSION, capture_sha256: captureSha256, ...value })}\n`, { encoding: "utf8", flag: "wx" });
+    try {
+        await link(tmp, path);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    finally {
+        await unlink(tmp).catch(() => undefined);
+    }
+    void directory;
+}

package/dist/local-preview-session.d.ts

@@ -0,0 +1,73 @@
+import { LocalPreviewReadOnlyProjection } from "./local-preview-projections.js";
+import { LocalPreviewRuntime } from "./local-preview-runtime.js";
+import { type LocalPreviewWorldlineRequestContext } from "./local-preview-worldlines.js";
+export type LocalPreviewSessionNotification = Readonly<{
+    topic: "message.added" | "turn.changed";
+    data: Readonly<Record<string, unknown>>;
+}>;
+export type LocalPreviewModelClient = (request: Readonly<{
+    projectId: string;
+    rootIdentity: string;
+    accountIdentity: string | null;
+    bindAccount: (accountIdentity: string) => Promise<void>;
+    model: string;
+    idempotencyKey: string;
+    messages: readonly Readonly<{
+        role: "system" | "user" | "assistant";
+        content: string;
+    }>[];
+}>) => Promise<Readonly<{
+    content: string;
+}>>;
+export type LocalPreviewReadOnlyProjectionReader = () => Promise<LocalPreviewReadOnlyProjection>;
+export type LocalPreviewRuntimeReader = () => Promise<LocalPreviewRuntime>;
+export type LocalPreviewHostNotificationSnapshotReader = () => Promise<Readonly<{
+    state: Readonly<{
+        generation: number;
+        entries: readonly Readonly<{
+            key: string;
+            revision: number;
+        }>[];
+    }>;
+    owned_resources: readonly Readonly<{
+        node_id: string;
+        attr_key: string;
+        resources: readonly Readonly<{
+            type: string;
+            uri: string;
+        }>[];
+    }>[];
+}>>;
+export type LocalPreviewWriterCommittedListener = (input: Readonly<{
+    turn_id: string;
+}>) => Promise<void>;
+/** 项目内、host-owned 的开发 Preview 消息会话；它不是正式 Player save authority。 */
+export declare class LocalPreviewSession {
+    #private;
+    private constructor();
+    static open(input: Readonly<{
+        root: string;
+        projectId: string;
+        modelClient?: LocalPreviewModelClient;
+        now?: () => number;
+        readOnlyProjection?: LocalPreviewReadOnlyProjection | LocalPreviewReadOnlyProjectionReader;
+        runtime?: LocalPreviewRuntimeReader;
+        hostNotificationSnapshot?: LocalPreviewHostNotificationSnapshotReader;
+        writerCommitted?: LocalPreviewWriterCommittedListener;
+    }>): Promise<LocalPreviewSession>;
+    onNotification(listener: (notification: LocalPreviewSessionNotification) => void): () => void;
+    inspect(): Readonly<Record<string, unknown>>;
+    inspectForHost(): Promise<Readonly<Record<string, unknown>>>;
+    waitForRevision(after: number, timeoutMs: number): Promise<Readonly<Record<string, unknown>>>;
+    get saveId(): string;
+    pendingViewDeliveryFailures(): readonly Readonly<{
+        operation_id: string;
+        capture_sha256: string;
+    }>[];
+    recordViewDeliveryFailure(input: Readonly<{
+        operation_id: string;
+        capture_sha256: string;
+    }>): Promise<void>;
+    resolveViewDeliveryFailure(operationId: string): Promise<void>;
+    handle(method: string, params: unknown, worldlineContext?: LocalPreviewWorldlineRequestContext): Promise<unknown>;
+}