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

package/dist/local-preview-session.js

@@ -0,0 +1,395 @@
+import { createHash, randomUUID } from "node:crypto";
+import { open, readFile } from "node:fs/promises";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { canonicalAccountProjectRootIdentityBytes } from "@world-engines/project-format";
+import { LOCAL_ACCOUNT_MODEL_PROXY_ORIGIN } from "./account-model-proxy.js";
+import { LocalPreviewWorldlineFacade } from "./local-preview-worldlines.js";
+import { ensureSafeProjectDirectory, safeProjectPath } from "./safe-project-path.js";
+const MAX_TEXT = 64 * 1024;
+const MAX_MESSAGES = 200;
+const ID = /^[A-Za-z0-9._:-]{1,128}$/u;
+const MODEL = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$/u;
+function fail(code, message) { throw new AuthoringBridgeError(code, message); }
+function record(value) { return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined; }
+function messageId(prefix) { return `${prefix}:${randomUUID()}`; }
+function eventDigest(value) { return createHash("sha256").update(value).digest("hex"); }
+async function defaultModelClient(request) {
+    const proxy = new URL(LOCAL_ACCOUNT_MODEL_PROXY_ORIGIN);
+    const sessionHeaders = { Host: proxy.host, "x-worldengine-project-id": request.projectId, "x-worldengine-project-root-sha256": request.rootIdentity };
+    const session = await fetch(`${proxy.origin}/v1/session`, { headers: sessionHeaders, signal: AbortSignal.timeout(60_000) });
+    const sessionBody = record(await session.json().catch(() => undefined));
+    const accountIdentity = sessionBody?.account_identity;
+    if (!session.ok || typeof accountIdentity !== "string")
+        fail(session.status === 401 ? "E_AUTH_REQUIRED" : "E_OPERATION_UNCERTAIN", "账户模型代理不可用");
+    if (request.accountIdentity !== null && request.accountIdentity !== accountIdentity)
+        fail("E_ACCOUNT_CHANGED", "Preview session 已绑定其他账户；请新建本地 Preview session");
+    await request.bindAccount(accountIdentity);
+    const response = await fetch(`${proxy.origin}/v1/chat/completions`, {
+        method: "POST",
+        headers: { ...sessionHeaders, "x-worldengine-account-identity": accountIdentity, "content-type": "application/json", "idempotency-key": request.idempotencyKey },
+        body: JSON.stringify({ model: request.model, messages: request.messages, stream: false }), signal: AbortSignal.timeout(60_000),
+    });
+    const body = record(await response.json().catch(() => undefined));
+    const choices = Array.isArray(body?.choices) ? body.choices : [];
+    const choice = record(choices[0]);
+    const content = record(choice?.message)?.content;
+    if (!response.ok || typeof content !== "string" || content.length === 0 || content.length > MAX_TEXT) {
+        const code = record(body?.error)?.code;
+        fail(typeof code === "string" ? code : response.status === 401 ? "E_AUTH_REQUIRED" : "E_OPERATION_UNCERTAIN", "模型回合未完成");
+    }
+    return { content };
+}
+/** 项目内、host-owned 的开发 Preview 消息会话；它不是正式 Player save authority。 */
+export class LocalPreviewSession {
+    #root;
+    #projectId;
+    #rootIdentity;
+    #modelClient;
+    #readOnlyProjection;
+    #runtime;
+    #hostNotificationSnapshot;
+    #now;
+    #listeners = new Set();
+    #revisionWaiters = new Set();
+    #messages = [];
+    #turns = new Map();
+    #accountIdentity = null;
+    #loaded = false;
+    #busy = false;
+    #sending = false;
+    #revision = 0;
+    #writerCommitted;
+    #failedViewDeliveries = new Map();
+    constructor(root, projectId, modelClient, now, readOnlyProjection, runtime, hostNotificationSnapshot, writerCommitted) {
+        this.#root = root;
+        this.#projectId = projectId;
+        this.#modelClient = modelClient;
+        this.#now = now;
+        this.#readOnlyProjection = readOnlyProjection;
+        this.#runtime = runtime;
+        this.#hostNotificationSnapshot = hostNotificationSnapshot;
+        this.#writerCommitted = writerCommitted;
+        this.#rootIdentity = createHash("sha256").update(canonicalAccountProjectRootIdentityBytes(root, process.platform === "win32" ? "win32" : "posix")).digest("hex");
+    }
+    static async open(input) {
+        const session = new LocalPreviewSession(input.root, input.projectId, input.modelClient ?? defaultModelClient, input.now ?? Date.now, input.readOnlyProjection, input.runtime, input.hostNotificationSnapshot, input.writerCommitted);
+        await session.#load();
+        return session;
+    }
+    onNotification(listener) { this.#listeners.add(listener); return () => this.#listeners.delete(listener); }
+    inspect() {
+        return Object.freeze({ development_preview: true, save_id: this.saveId, revision: this.#revision, pending: [...this.#turns.values()].filter((turn) => turn.state === "queued" || turn.state === "running").length, account_bound: this.#accountIdentity !== null, turns: [...this.#turns.values()].slice(-MAX_MESSAGES).map((turn) => Object.freeze({ turn_id: turn.id, state: turn.state, ...(turn.error_code === undefined ? {} : { error_code: turn.error_code }) })) });
+    }
+    async inspectForHost() {
+        let inspected = this.inspect();
+        if (this.#runtime !== undefined) {
+            const snapshot = await (await this.#runtime()).worldlineRuntime().snapshotWorldlines();
+            if (snapshot !== null)
+                inspected = Object.freeze({ ...inspected, worldline_save_id: snapshot.scope.saveId, worldline_author_namespace: snapshot.scope.authorNamespace });
+        }
+        if (this.#hostNotificationSnapshot !== undefined)
+            inspected = Object.freeze({ ...inspected, notification_snapshot: await this.#hostNotificationSnapshot() });
+        return inspected;
+    }
+    async waitForRevision(after, timeoutMs) {
+        if (!Number.isSafeInteger(after) || after < 0 || !Number.isSafeInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > 15_000)
+            fail("EINVAL", "revision wait 参数无效");
+        if (this.#revision > after || timeoutMs === 0)
+            return await this.inspectForHost();
+        await new Promise((resolvePromise) => { const done = () => { this.#revisionWaiters.delete(done); clearTimeout(timer); resolvePromise(); }; const timer = setTimeout(done, timeoutMs); this.#revisionWaiters.add(done); });
+        return await this.inspectForHost();
+    }
+    get saveId() { return `local-preview:${this.#projectId}:${eventDigest(this.#rootIdentity).slice(0, 16)}`; }
+    pendingViewDeliveryFailures() { return Object.freeze([...this.#failedViewDeliveries].map(([operation_id, capture_sha256]) => Object.freeze({ operation_id, capture_sha256 }))); }
+    async recordViewDeliveryFailure(input) { if (!ID.test(input.operation_id) || !/^[a-f0-9]{64}$/u.test(input.capture_sha256))
+        fail("EINVAL", "View delivery failure identity 无效"); await this.#append({ v: 1, type: "view_delivery_failed", operation_id: input.operation_id, capture_sha256: input.capture_sha256 }); }
+    async resolveViewDeliveryFailure(operationId) { if (!ID.test(operationId) || !this.#failedViewDeliveries.has(operationId))
+        return; await this.#append({ v: 1, type: "view_delivery_resolved", operation_id: operationId }); }
+    async handle(method, params, worldlineContext) {
+        if (method === "chat.listMessages")
+            return await this.#list(params);
+        if (method === "chat.sendUserMessage")
+            return this.#send(params);
+        if (method === "preview.status")
+            return this.inspect();
+        if (method === "preview.capabilities") {
+            if (params === null || typeof params !== "object" || Array.isArray(params) || Object.keys(params).length !== 0)
+                fail("EINVAL", "参数无效");
+            return (await this.#projection()).capabilities();
+        }
+        if (method === "worldline.list" || method === "worldline.fork" || method === "worldline.activate") {
+            if (worldlineContext === undefined)
+                fail("E_CAPABILITY_UNAVAILABLE", "本地 Preview worldline 缺少 host request identity");
+            const result = await new LocalPreviewWorldlineFacade((await this.#writerRuntime()).worldlineRuntime()).handle(method, params, worldlineContext);
+            if (method === "worldline.fork" || method === "worldline.activate")
+                this.#touch();
+            return result;
+        }
+        if (["scenario.getMeta", "scenario.getProgress", "scenario.getVariable", "scenario.getUnlock", "scenario.getOwnedResources", "state.get", "state.getEntry", "state.keys", "asset.list", "asset.getUrl"].includes(method)) {
+            return await (await this.#projection()).handle(method, params);
+        }
+        fail("EPERM", "本地 Preview 未授予该能力");
+    }
+    async #projection() {
+        if (this.#readOnlyProjection === undefined)
+            fail("E_CAPABILITY_UNAVAILABLE", "本地 Preview 只读 Runtime projection 尚未就绪");
+        return typeof this.#readOnlyProjection === "function" ? await this.#readOnlyProjection() : this.#readOnlyProjection;
+    }
+    async #load() {
+        if (this.#loaded)
+            return;
+        const path = await safeProjectPath(this.#root, ".worldengine/local-preview-session.v1.jsonl");
+        let source;
+        try {
+            source = await readFile(path, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                this.#loaded = true;
+                return;
+            }
+            throw error;
+        }
+        if (source !== "" && !source.endsWith("\n"))
+            fail("E_PREVIEW_SESSION_LOG_CORRUPT", "Preview session 日志尾部不完整");
+        for (const line of source.split("\n").filter(Boolean)) {
+            let item;
+            try {
+                item = record(JSON.parse(line)) ?? fail("E_PREVIEW_SESSION_LOG_CORRUPT", "Preview session 日志无效");
+            }
+            catch (error) {
+                if (error instanceof AuthoringBridgeError)
+                    throw error;
+                fail("E_PREVIEW_SESSION_LOG_CORRUPT", "Preview session 日志无效");
+            }
+            this.#apply(item, false);
+        }
+        this.#loaded = true;
+        const interrupted = [...this.#turns.values()].filter((turn) => turn.state === "queued" || turn.state === "running");
+        for (const turn of interrupted)
+            await this.#append({ v: 1, type: "turn", ...turn, state: "failed", error_code: "E_OPERATION_UNCERTAIN" });
+    }
+    #apply(item, notify) {
+        const type = item.type;
+        if (type === "session") {
+            if (item.project_id !== this.#projectId || item.save_id !== this.saveId)
+                fail("E_PREVIEW_SESSION_LOG_CORRUPT", "Preview session identity 不匹配");
+            return;
+        }
+        if (type === "account") {
+            if (typeof item.account_identity !== "string" || (this.#accountIdentity !== null && this.#accountIdentity !== item.account_identity))
+                fail("E_PREVIEW_SESSION_LOG_CORRUPT", "Preview session account 无效");
+            this.#accountIdentity = item.account_identity;
+            return;
+        }
+        if (type === "model_result") {
+            if (typeof item.turn_id !== "string" || typeof item.message_id !== "string" || typeof item.writer_receipt_digest !== "string" || !/^[a-f0-9]{64}$/u.test(item.writer_receipt_digest))
+                fail("E_PREVIEW_SESSION_LOG_CORRUPT", "Preview model receipt 无效");
+            return;
+        }
+        if (type === "view_delivery_failed") {
+            if (typeof item.operation_id !== "string" || !ID.test(item.operation_id) || typeof item.capture_sha256 !== "string" || !/^[a-f0-9]{64}$/u.test(item.capture_sha256))
+                fail("E_PREVIEW_SESSION_LOG_CORRUPT", "View delivery failure receipt 无效");
+            this.#failedViewDeliveries.set(item.operation_id, item.capture_sha256);
+            this.#revision += 1;
+            return;
+        }
+        if (type === "view_delivery_resolved") {
+            if (typeof item.operation_id !== "string" || !ID.test(item.operation_id))
+                fail("E_PREVIEW_SESSION_LOG_CORRUPT", "View delivery recovery receipt 无效");
+            this.#failedViewDeliveries.delete(item.operation_id);
+            this.#revision += 1;
+            return;
+        }
+        if (type === "accepted_user") {
+            if (typeof item.id !== "string" || typeof item.request_id !== "string" || typeof item.user_message_id !== "string" || !Number.isSafeInteger(item.ts))
+                fail("E_PREVIEW_SESSION_LOG_CORRUPT", "Preview accepted user receipt 无效");
+            this.#turns.set(item.id, { id: item.id, request_id: item.request_id, user_message_id: item.user_message_id, state: "queued" });
+            this.#revision += 1;
+            if (notify)
+                this.#notify({ topic: "turn.changed", data: { turnId: item.id, state: "queued" } });
+            return;
+        }
+        if (type === "turn_created") {
+            if (typeof item.id !== "string" || typeof item.request_id !== "string" || typeof item.user_message_id !== "string" || typeof item.text !== "string" || !Number.isSafeInteger(item.ts))
+                fail("E_PREVIEW_SESSION_LOG_CORRUPT", "Preview session turn 无效");
+            const message = Object.freeze({ id: item.user_message_id, saveId: this.saveId, role: "user", text: item.text, ts: item.ts, meta: Object.freeze({ turnId: item.id, source: "local-preview" }) });
+            this.#messages.push(message);
+            this.#turns.set(item.id, { id: item.id, request_id: item.request_id, user_message_id: item.user_message_id, state: "queued" });
+            this.#revision += 1;
+            if (notify) {
+                this.#notify({ topic: "message.added", data: message });
+                this.#notify({ topic: "turn.changed", data: { turnId: item.id, state: "queued" } });
+            }
+            return;
+        }
+        if (type === "assistant_committed") {
+            if (typeof item.id !== "string" || typeof item.turn_id !== "string" || !Number.isSafeInteger(item.ts))
+                fail("E_PREVIEW_SESSION_LOG_CORRUPT", "Preview committed message 无效");
+            this.#messages.push(Object.freeze({ id: item.id, saveId: this.saveId, role: "assistant", ts: item.ts, meta: Object.freeze({ turnId: item.turn_id, source: "local-preview" }) }));
+            this.#revision += 1;
+            if (notify)
+                this.#notify({ topic: "message.added", data: { id: item.id, role: "assistant" } });
+            return;
+        }
+        if (type === "message") {
+            if (typeof item.id !== "string" || (item.role !== "user" && item.role !== "assistant") || typeof item.text !== "string" || typeof item.turn_id !== "string" || !Number.isSafeInteger(item.ts))
+                fail("E_PREVIEW_SESSION_LOG_CORRUPT", "Preview session message 无效");
+            // 旧 JSONL assistant body 没有 Runtime SQLite receipt，不能被升格为 checkpoint 或当前消息 authority。
+            if (item.role === "assistant")
+                return;
+            const message = Object.freeze({ id: item.id, saveId: this.saveId, role: item.role, text: item.text, ts: item.ts, meta: Object.freeze({ turnId: item.turn_id, source: "local-preview" }) });
+            this.#messages.push(message);
+            this.#revision += 1;
+            if (notify)
+                this.#notify({ topic: "message.added", data: message });
+            return;
+        }
+        if (type === "turn") {
+            if (typeof item.id !== "string" || typeof item.request_id !== "string" || typeof item.user_message_id !== "string" || !["queued", "running", "completed", "failed"].includes(String(item.state)))
+                fail("E_PREVIEW_SESSION_LOG_CORRUPT", "Preview session turn 无效");
+            const turn = { id: item.id, request_id: item.request_id, user_message_id: item.user_message_id, state: item.state, ...(typeof item.error_code === "string" ? { error_code: item.error_code } : {}) };
+            this.#turns.set(turn.id, turn);
+            this.#revision += 1;
+            if (notify)
+                this.#notify({ topic: "turn.changed", data: { turnId: turn.id, state: turn.state, ...(turn.error_code === undefined ? {} : { errorCode: turn.error_code }) } });
+            return;
+        }
+        fail("E_PREVIEW_SESSION_LOG_CORRUPT", "Preview session event 无效");
+    }
+    async #append(item) {
+        await ensureSafeProjectDirectory(this.#root, ".worldengine");
+        const path = await safeProjectPath(this.#root, ".worldengine/local-preview-session.v1.jsonl");
+        const handle = await open(path, "a", 0o600);
+        try {
+            await handle.writeFile(`${JSON.stringify(item)}\n`, "utf8");
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        this.#apply(item, true);
+    }
+    #notify(notification) { for (const listener of this.#listeners) {
+        try {
+            listener(notification);
+        }
+        catch { /* observer failures cannot alter the persisted turn. */ }
+    } for (const wake of [...this.#revisionWaiters])
+        wake(); }
+    #touch() { this.#revision += 1; for (const wake of [...this.#revisionWaiters])
+        wake(); }
+    async #list(value) {
+        const params = record(value) ?? fail("EINVAL", "参数无效");
+        const limit = params.limit === undefined ? MAX_MESSAGES : params.limit;
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_MESSAGES)
+            fail("EINVAL", "limit 无效");
+        const after = params.after;
+        const before = params.before;
+        if ((after !== undefined && typeof after !== "string") || (before !== undefined && typeof before !== "string"))
+            fail("EINVAL", "cursor 无效");
+        if (this.#runtime !== undefined) {
+            const messages = await (await this.#runtime()).readCommittedMessages();
+            const afterIndex = typeof after === "string" ? messages.findIndex((message) => message.messageId === after) : -1;
+            const beforeIndex = typeof before === "string" ? messages.findIndex((message) => message.messageId === before) : messages.length;
+            const start = after === undefined ? 0 : afterIndex < 0 ? messages.length : afterIndex + 1;
+            const end = before === undefined ? messages.length : beforeIndex < 0 ? 0 : beforeIndex;
+            return messages.slice(start, Math.max(start, end)).slice(-limit).map((message) => Object.freeze({ id: message.messageId, saveId: this.saveId, role: message.role, text: message.text, ts: 0, meta: Object.freeze({ turnId: message.turnId, source: "local-preview" }) }));
+        }
+        const afterIndex = typeof after === "string" ? this.#messages.findIndex((message) => message.id === after) : -1;
+        const beforeIndex = typeof before === "string" ? this.#messages.findIndex((message) => message.id === before) : this.#messages.length;
+        const start = after === undefined ? 0 : afterIndex < 0 ? this.#messages.length : afterIndex + 1;
+        const end = before === undefined ? this.#messages.length : beforeIndex < 0 ? 0 : beforeIndex;
+        return this.#messages.slice(start, Math.max(start, end)).slice(-limit);
+    }
+    async #send(value) {
+        const params = record(value) ?? fail("EINVAL", "参数无效");
+        const text = params.text;
+        const requestId = params.requestId;
+        if (typeof text !== "string" || text.trim().length === 0 || text.length > MAX_TEXT || typeof requestId !== "string" || !ID.test(requestId))
+            fail("EINVAL", "消息或 requestId 无效");
+        const existing = [...this.#turns.values()].find((turn) => turn.request_id === requestId);
+        if (existing !== undefined)
+            return { messageId: existing.user_message_id, turnId: existing.id, state: existing.state === "completed" || existing.state === "failed" ? existing.state : "queued" };
+        if (this.#sending || this.#busy || [...this.#turns.values()].some((turn) => turn.state === "queued" || turn.state === "running"))
+            fail("E_PREVIEW_TURN_PENDING", "上一个 Preview 回合仍在进行");
+        this.#sending = true;
+        try {
+            const turnId = messageId("local-turn");
+            const userId = messageId("local-message");
+            const ts = this.#now();
+            const runtime = await this.#writerRuntime();
+            await runtime.appendAcceptedUserMessage({ operation_id: `preview.user.${turnId}`, turn_id: turnId, message_id: userId, text });
+            await this.#append({ v: 1, type: "accepted_user", id: turnId, request_id: requestId, user_message_id: userId, ts });
+            void this.#run(turnId);
+            return { messageId: userId, turnId, state: "queued" };
+        }
+        finally {
+            this.#sending = false;
+        }
+    }
+    async #run(turnId) {
+        const turn = this.#turns.get(turnId);
+        if (turn === undefined || this.#busy)
+            return;
+        this.#busy = true;
+        try {
+            await this.#append({ v: 1, type: "turn", ...turn, state: "running" });
+            const runtime = await this.#writerRuntime();
+            const preparation = await runtime.prepareWriterTurn({ operation_id: `preview.writer.${turn.id}`, turn_id: turn.id });
+            const model = await this.#readModel();
+            const messages = await this.#writerMessages(runtime, preparation);
+            const result = await this.#modelClient({ projectId: this.#projectId, rootIdentity: this.#rootIdentity, accountIdentity: this.#accountIdentity, bindAccount: async (accountIdentity) => { if (this.#accountIdentity === null)
+                    await this.#append({ v: 1, type: "account", account_identity: accountIdentity });
+                else if (this.#accountIdentity !== accountIdentity)
+                    fail("E_ACCOUNT_CHANGED", "Preview session 已绑定其他账户；请新建本地 Preview session"); }, model, idempotencyKey: `preview:${eventDigest(`${this.saveId}:${turn.request_id}`).slice(0, 56)}`, messages });
+            const assistantId = messageId("local-message");
+            const ordered = [...(await runtime.readCommittedMessages()).map((message) => message.messageId), assistantId];
+            const writerReceiptDigest = eventDigest(`${turn.id}\0${result.content}\0${preparation.identity}`);
+            await this.#append({ v: 1, type: "model_result", turn_id: turn.id, message_id: assistantId, writer_receipt_digest: writerReceiptDigest });
+            await runtime.commitSuccessfulWriterResult({ prepare_identity: preparation.identity, text: result.content, message_id: assistantId, ordered_message_ids: ordered, writer_receipt_digest: writerReceiptDigest });
+            if (runtime.readCommittedWriterMessage(assistantId)?.text !== result.content)
+                fail("E_OPERATION_UNCERTAIN", "Preview Runtime writer commit 读回不一致");
+            await this.#append({ v: 1, type: "assistant_committed", id: assistantId, ts: this.#now(), turn_id: turnId });
+            await this.#append({ v: 1, type: "turn", ...turn, state: "completed" });
+            try {
+                await this.#writerCommitted?.({ turn_id: turnId });
+            }
+            catch { /* 已持久 writer 不能因 View delivery 调度失败变成失败回合。 */ }
+        }
+        catch (error) {
+            const code = error instanceof AuthoringBridgeError ? error.code : "E_OPERATION_UNCERTAIN";
+            try {
+                await this.#append({ v: 1, type: "turn", ...turn, state: "failed", error_code: code });
+            }
+            catch { /* retained queued/running log is intentionally uncertain and never auto-retried. */ }
+        }
+        finally {
+            this.#busy = false;
+        }
+    }
+    async #readModel() {
+        const path = await safeProjectPath(this.#root, "view/preview.config.json");
+        let value;
+        try {
+            value = JSON.parse(await readFile(path, "utf8"));
+        }
+        catch {
+            fail("E_PREVIEW_MODEL_CONFIG_REQUIRED", "view/preview.config.json 缺失或无效");
+        }
+        const config = record(value);
+        if (config === undefined || Object.keys(config).sort().join("\0") !== "model\0schema_version" || config.schema_version !== 1 || typeof config.model !== "string" || !MODEL.test(config.model))
+            fail("E_PREVIEW_MODEL_CONFIG_REQUIRED", "view/preview.config.json 无效");
+        return config.model;
+    }
+    async #writerRuntime() { if (this.#runtime === undefined)
+        fail("E_CAPABILITY_UNAVAILABLE", "本地 Preview writer Runtime 尚未就绪"); return await this.#runtime(); }
+    async #writerMessages(runtime, preparation) {
+        const snapshot = runtime.readProjectionSnapshot();
+        const context = JSON.stringify({ development_preview: true, scene: preparation.scene, manuscript_notes: preparation.scene?.manuscriptNotes ?? [], source_metadata: snapshot.source_projection?.metadata ?? null });
+        if (context.length > MAX_TEXT)
+            fail("E_VALIDATION_FAILED", "Preview Runtime 上下文过大");
+        const history = await runtime.readCommittedMessages();
+        return Object.freeze([{ role: "system", content: `当前本地开发 Preview Runtime 上下文：${context}` }, ...history.map((message) => ({ role: message.role, content: message.text }))]);
+    }
+}

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

@@ -0,0 +1,40 @@
+import { type NeutralScenarioSource, type ScenarioSourceManifest, type ScenarioSourceSection } from "@world-engines/scenario-author-source";
+import { type CapturedUploadSnapshot } from "./transfer/upload.js";
+export interface LocalPreviewSourceCaptureIdentity {
+    readonly kind: "worldengine.local-preview-source/v1";
+    readonly project_id: string;
+    readonly local_scenario_id: string;
+    readonly local_view_id: string;
+    readonly project_revision: number;
+    readonly snapshot_id: string;
+    readonly snapshot_digest: string;
+    /** 本地 manifest 绑定的 snapshot 更新时间；不是作者资产的创建时间。 */
+    readonly snapshot_updated_at_ms: number;
+    readonly scenario_sha256: string;
+    readonly view_source_tree_sha256: string;
+    readonly view_package_lock_sha256: string;
+    readonly neutral_source_sha256: string;
+    readonly neutral_manifest_sha256: string;
+    /** 本地 identity 的内容哈希；不是远端 head、lease 或发布回执。 */
+    readonly capture_sha256: string;
+}
+/**
+ * 仅供本地 Player 编译前的 immutable input 使用。
+ * 它明确不满足 NeutralSourceCaptureWitness：没有 owner、source revision 或远端 head。
+ */
+export interface LocalPreviewSourceCapture {
+    readonly identity: LocalPreviewSourceCaptureIdentity;
+    readonly source: NeutralScenarioSource;
+    readonly source_bytes: Uint8Array;
+    readonly manifest: ScenarioSourceManifest;
+    readonly sections: readonly ScenarioSourceSection[];
+}
+export interface CaptureLocalPreviewSourceOptions {
+    readonly project_root: string;
+    /** 仅测试 seam；生产调用不得替换真实的本地 upload snapshot reader。 */
+    readonly capture_upload_snapshot?: (root: string) => Promise<CapturedUploadSnapshot>;
+}
+/**
+ * 从一个已 snapshot 一致的本地 Project 捕获中性作者源。全程只读；没有 upload、embedding、head/lease 或发布副作用。
+ */
+export declare function captureLocalPreviewSource(options: CaptureLocalPreviewSourceOptions): Promise<LocalPreviewSourceCapture>;

package/dist/local-preview-source.js

@@ -0,0 +1,192 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { canonicalNeutralScenarioSourceBytes, createNeutralScenarioSource, } from "@world-engines/scenario-author-source";
+import { ScenarioPartSourceV1 } from "@world-engines/protocol-ts/v1/scenario_part_source";
+import { computeCanonicalFileTreeDigest, computeCanonicalProjectDigest, decodeScenarioPartWesp, validateLocalAuthorProjectManifest, } from "@world-engines/project-format";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { LocalProjectHost } from "./project-host.js";
+import { assertSafeExistingProjectPath } from "./safe-project-path.js";
+import { captureUploadSnapshot, mapScenarioPartToNeutralSections, } from "./transfer/upload.js";
+const SHA256 = /^[a-f0-9]{64}$/u;
+const SVP_HEADER_BYTES = 17;
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function bytesEqual(left, right) {
+    return left.byteLength === right.byteLength && Buffer.from(left).equals(Buffer.from(right));
+}
+function error(message) {
+    throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", message);
+}
+function manifestDigestHex(manifest) {
+    return Buffer.from(manifest.manifest_sha256).toString("hex");
+}
+function captureDigest(identity) {
+    const entries = Object.entries(identity).map(([key, value]) => `${key.length}:${key}${String(value).length}:${String(value)}`);
+    return sha256(new TextEncoder().encode(entries.join("|")));
+}
+function parseViewSnapshot(bytes) {
+    if (bytes.byteLength < SVP_HEADER_BYTES || bytes[0] !== 0x53 || bytes[1] !== 0x56
+        || bytes[2] !== 0x50 || bytes[3] !== 0x01 || bytes[4] !== 0) {
+        error("本地 View capture 不是未压缩 SVP v1");
+    }
+    const length = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(13, true);
+    if (length !== bytes.byteLength - SVP_HEADER_BYTES)
+        error("本地 View capture 长度无效");
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(SVP_HEADER_BYTES)));
+    }
+    catch {
+        error("本地 View capture JSON 无效");
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value) || !Array.isArray(value.files)) {
+        error("本地 View capture 缺少 files");
+    }
+    const seen = new Set();
+    return Object.freeze(value.files.map((entry) => {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+            error("本地 View capture 文件无效");
+        const candidate = entry;
+        const path = candidate.path;
+        const content = candidate.content_base64;
+        if (typeof path !== "string" || path.length === 0 || path.includes("\\") || path.startsWith("/")
+            || path.split("/").some((segment) => segment === "" || segment === "." || segment === "..") || seen.has(path)) {
+            error("本地 View capture 文件路径无效");
+        }
+        if (typeof content !== "string" || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(content)) {
+            error("本地 View capture 文件内容无效");
+        }
+        const decoded = new Uint8Array(Buffer.from(content, "base64"));
+        if (Buffer.from(decoded).toString("base64") !== content)
+            error("本地 View capture base64 非 canonical");
+        seen.add(path);
+        return Object.freeze({ path, bytes: decoded });
+    }));
+}
+async function readBinding(root) {
+    const path = await assertSafeExistingProjectPath(root, join(root, "worldengine.project.json"));
+    const bytes = new Uint8Array(await readFile(path));
+    let manifest;
+    try {
+        manifest = validateLocalAuthorProjectManifest(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)));
+    }
+    catch (cause) {
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "worldengine.project.json 无效", { cause: cause instanceof Error ? cause.message : String(cause) });
+    }
+    if (await computeCanonicalProjectDigest(manifest) !== manifest.snapshot.canonical_digest)
+        error("本地 Project manifest 未绑定有效 snapshot");
+    return Object.freeze({
+        manifest_bytes: bytes,
+        manifest,
+        project_id: manifest.project_id,
+        project_revision: manifest.project_revision,
+        snapshot_id: manifest.snapshot.snapshot_id,
+        snapshot_digest: manifest.snapshot.canonical_digest,
+        snapshot_updated_at_ms: manifest.updated_at_ms,
+        scenario_sha256: manifest.scenario.source_sha256,
+        view_source_tree_sha256: manifest.view.source_tree_sha256,
+        view_package_lock_sha256: manifest.view.package_lock_sha256,
+    });
+}
+function capturedObjects(snapshot) {
+    const scenario = snapshot.objects.filter((object) => object.part_kind === "scenario");
+    const view = snapshot.objects.filter((object) => object.part_kind === "view");
+    if (scenario.length !== 1 || view.length !== 1 || snapshot.objects.length !== 2)
+        error("本地 capture objects 不完整或不唯一");
+    for (const object of [scenario[0], view[0]]) {
+        if (!SHA256.test(object.sha256) || object.byte_length !== object.bytes.byteLength || sha256(object.bytes) !== object.sha256) {
+            error("本地 capture object digest 不一致");
+        }
+    }
+    return Object.freeze({ scenario: scenario[0].bytes.slice(), view: view[0].bytes.slice() });
+}
+function assertClean(status) {
+    if (status.scenario_integrity !== "clean" || status.view_state !== "clean") {
+        error("本地 Project 尚未 snapshot 一致，拒绝捕获 Player 输入");
+    }
+}
+/**
+ * 从一个已 snapshot 一致的本地 Project 捕获中性作者源。全程只读；没有 upload、embedding、head/lease 或发布副作用。
+ */
+export async function captureLocalPreviewSource(options) {
+    const root = await assertSafeExistingProjectPath(resolve(options.project_root), resolve(options.project_root));
+    const host = await LocalProjectHost.open(root);
+    try {
+        const beforeStatus = await host.inspect();
+        assertClean(beforeStatus);
+        const beforeTransfer = await host.readTransferReadback();
+        const before = await readBinding(root);
+        if (before.project_id !== beforeStatus.project_id || before.project_revision !== beforeTransfer.project_revision
+            || before.snapshot_digest !== beforeTransfer.snapshot_digest || before.scenario_sha256 !== beforeTransfer.scenario_sha256
+            || before.view_source_tree_sha256 !== beforeTransfer.view_source_tree_sha256) {
+            error("本地 Project readback 与 manifest snapshot 不一致");
+        }
+        const snapshot = await (options.capture_upload_snapshot ?? captureUploadSnapshot)(root);
+        if (snapshot.snapshot.snapshot_id !== before.snapshot_id || snapshot.snapshot.snapshot_digest !== before.snapshot_digest
+            || snapshot.snapshot.updated_at_ms !== before.snapshot_updated_at_ms) {
+            error("本地 capture 未绑定当前 manifest snapshot");
+        }
+        const objects = capturedObjects(snapshot);
+        const files = parseViewSnapshot(objects.view);
+        const capturedViewTree = await computeCanonicalFileTreeDigest(files
+            .filter((file) => file.path !== "package-lock.json")
+            .map((file) => ({ path: file.path, bytes: file.bytes })));
+        const capturedPackageLock = files.find((file) => file.path === "package-lock.json");
+        const capturedPackageLockSha256 = sha256(capturedPackageLock?.bytes ?? new Uint8Array());
+        if (sha256(objects.scenario) !== before.scenario_sha256 || capturedViewTree !== before.view_source_tree_sha256
+            || capturedPackageLockSha256 !== before.view_package_lock_sha256) {
+            error("本地 capture bytes 与 manifest source/view digest 不一致");
+        }
+        const protobuf = await decodeScenarioPartWesp(objects.scenario);
+        const sections = mapScenarioPartToNeutralSections(ScenarioPartSourceV1.decode(protobuf), objects.view, objects.scenario);
+        const source = await createNeutralScenarioSource(before.manifest.scenario.local_scenario_id, sections);
+        const sourceBytes = canonicalNeutralScenarioSourceBytes(source).slice();
+        const neutralManifest = source.manifest;
+        if (neutralManifest === undefined)
+            error("本地 neutral source 缺少 manifest");
+        const neutralSourceSha256 = sha256(sourceBytes);
+        const neutralManifestSha256 = manifestDigestHex(neutralManifest);
+        const after = await readBinding(root);
+        const afterStatus = await host.inspect();
+        assertClean(afterStatus);
+        const afterTransfer = await host.readTransferReadback();
+        if (!bytesEqual(before.manifest_bytes, after.manifest_bytes)
+            || before.project_id !== after.project_id || before.project_revision !== after.project_revision
+            || before.snapshot_id !== after.snapshot_id || before.snapshot_digest !== after.snapshot_digest
+            || before.snapshot_updated_at_ms !== after.snapshot_updated_at_ms
+            || before.scenario_sha256 !== after.scenario_sha256 || before.view_source_tree_sha256 !== after.view_source_tree_sha256
+            || before.view_package_lock_sha256 !== after.view_package_lock_sha256
+            || afterTransfer.project_revision !== beforeTransfer.project_revision || afterTransfer.snapshot_digest !== beforeTransfer.snapshot_digest
+            || afterTransfer.scenario_sha256 !== beforeTransfer.scenario_sha256 || afterTransfer.view_source_tree_sha256 !== beforeTransfer.view_source_tree_sha256) {
+            error("本地 Project 在 Player input capture 期间发生变化");
+        }
+        const identityWithoutCapture = Object.freeze({
+            kind: "worldengine.local-preview-source/v1",
+            project_id: before.project_id,
+            local_scenario_id: before.manifest.scenario.local_scenario_id,
+            local_view_id: before.manifest.view.local_view_id,
+            project_revision: before.project_revision,
+            snapshot_id: before.snapshot_id,
+            snapshot_digest: before.snapshot_digest,
+            snapshot_updated_at_ms: before.snapshot_updated_at_ms,
+            scenario_sha256: before.scenario_sha256,
+            view_source_tree_sha256: before.view_source_tree_sha256,
+            view_package_lock_sha256: before.view_package_lock_sha256,
+            neutral_source_sha256: neutralSourceSha256,
+            neutral_manifest_sha256: neutralManifestSha256,
+        });
+        const identity = Object.freeze({ ...identityWithoutCapture, capture_sha256: captureDigest(identityWithoutCapture) });
+        return Object.freeze({
+            identity,
+            source,
+            source_bytes: sourceBytes,
+            manifest: neutralManifest,
+            sections: Object.freeze([...source.sections]),
+        });
+    }
+    finally {
+        await host.close();
+    }
+}