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

package/dist/project-host.d.ts

@@ -0,0 +1,59 @@
+import { type AuthoringBridgeAdapter, type AuthoringEffectIdentity, type AuthoringToolCall, type AuthoringToolName, type AuthoringToolReceiptV1 } from "@world-engines/authoring-bridge";
+import { type ScenarioProjectionHydrator, type ScenarioSourceReadback, type ScenarioWriteRequest, type ScenarioWriterFaultInjector } from "./scenario-writer.js";
+import { type DesktopAuthoringCapabilities, type GraphProjectionReadback } from "./desktop-authoring-runtime.js";
+import type { LadybugGraphSnapshotRequest } from "./ladybug-runtime.js";
+export interface ProjectStatus {
+    readonly project_id: string;
+    readonly project_revision: number;
+    readonly snapshot_id: string;
+    readonly snapshot_digest: string;
+    readonly scenario_integrity: "clean" | "dirty";
+    readonly view_state: "clean" | "dirty";
+    readonly root_dependencies_installed: boolean;
+    readonly view_dependencies_installed: boolean;
+}
+export interface DoctorCheck {
+    readonly name: string;
+    readonly ok: boolean;
+    readonly detail: string;
+}
+export interface ProjectDoctorReport {
+    readonly schema_version: 1;
+    readonly project_id: string;
+    readonly ok: boolean;
+    readonly checks: readonly DoctorCheck[];
+}
+export type SnapshotRequest = AuthoringEffectIdentity;
+export interface LocalProjectHostOptions {
+    readonly authoring_adapter?: AuthoringBridgeAdapter;
+    /** Desktop 的真实 authoring handler；未提供 Browser store/IDB/localStorage fallback。 */
+    readonly desktop_authoring_capabilities?: DesktopAuthoringCapabilities;
+    readonly scenario_projection_hydrator?: ScenarioProjectionHydrator;
+    /** 只用于 crash recovery integration test，生产路径不得注入。 */
+    readonly scenario_writer_fault_injector?: ScenarioWriterFaultInjector;
+}
+export declare class LocalProjectHost {
+    #private;
+    readonly root: string;
+    private constructor();
+    static open(root: string, options?: LocalProjectHostOptions): Promise<LocalProjectHost>;
+    inspect(): Promise<ProjectStatus>;
+    /** exact-21 descriptor 始终稳定；三个外部 callback 的执行可用性由真实注入端口决定。 */
+    isToolAvailable(name: AuthoringToolName): boolean;
+    /** Download completion fence：从真实 source/view/manifest 重新计算，不消费 receipt 自报字段。 */
+    readTransferReadback(): Promise<Readonly<{
+        project_revision: number;
+        snapshot_digest: string;
+        scenario_sha256: string;
+        view_source_tree_sha256: string;
+    }>>;
+    /** Desktop adapter 只通过此窄端口调用已显式注入的 capability；没有 handler 即 fail-closed。 */
+    dispatchTool(call: AuthoringToolCall): Promise<unknown>;
+    readSourceReadback(): Promise<ScenarioSourceReadback>;
+    /** Node-only 完整投影核对，不扩展 exact-21，不注入 embedding/model capability。 */
+    readGraphProjectionReadback(request?: LadybugGraphSnapshotRequest): Promise<GraphProjectionReadback>;
+    writeScenario(request: ScenarioWriteRequest): Promise<AuthoringToolReceiptV1>;
+    doctor(): Promise<ProjectDoctorReport>;
+    snapshot(request: SnapshotRequest): Promise<AuthoringToolReceiptV1>;
+    close(): Promise<void>;
+}

package/dist/project-host.js

@@ -0,0 +1,471 @@
+import { lstat, open, readFile, readdir, realpath, rename, stat, writeFile, } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { AuthoringBridgeError, createAuthoringBridgeDispatcher, validateAuthoringEffectIdentity, } from "@world-engines/authoring-bridge";
+import { computeCanonicalFileTreeDigest, computeCanonicalProjectDigest, decodeScenarioPartWesp, sha256Hex, validateLocalAuthorProjectManifest, } from "@world-engines/project-format";
+import { AGENT_KIT_ROOT_LINKS } from "@world-engines/agent-kit";
+import { assertSafeExistingProjectPath, assertSafeProjectParent, ensureSafeProjectDirectory, safeProjectPath, } from "./safe-project-path.js";
+import { acquireProjectWriterLease } from "./project-writer-lease.js";
+import { ScenarioWriter, } from "./scenario-writer.js";
+import { DesktopAuthoringRuntime } from "./desktop-authoring-runtime.js";
+async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+async function readManifest(root) {
+    try {
+        const manifestPath = await safeProjectPath(root, "worldengine.project.json");
+        return validateLocalAuthorProjectManifest(JSON.parse(await readFile(await assertSafeExistingProjectPath(root, manifestPath), "utf8")));
+    }
+    catch (error) {
+        if (error instanceof AuthoringBridgeError)
+            throw error;
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "worldengine.project.json 无效", {
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+async function listCanonicalFiles(projectRoot, contentRoot, excludedNames, directory = "") {
+    const absoluteDirectory = join(contentRoot, ...directory.split("/").filter(Boolean));
+    await assertSafeExistingProjectPath(projectRoot, absoluteDirectory);
+    const entries = await readdir(absoluteDirectory, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        if (excludedNames.has(entry.name))
+            continue;
+        const relativePath = directory === "" ? entry.name : `${directory}/${entry.name}`;
+        const absolutePath = join(absoluteDirectory, entry.name);
+        const info = await lstat(absolutePath);
+        if (info.isSymbolicLink()) {
+            throw new AuthoringBridgeError("E_PATH_OUTSIDE_PROJECT", `拒绝符号链接、junction 或 reparse point：${absolutePath}`);
+        }
+        else if (info.isDirectory()) {
+            files.push(...(await listCanonicalFiles(projectRoot, contentRoot, excludedNames, relativePath)));
+        }
+        else if (info.isFile()) {
+            const canonical = await assertSafeExistingProjectPath(projectRoot, absolutePath);
+            files.push({ path: relativePath, bytes: new Uint8Array(await readFile(canonical)) });
+        }
+    }
+    return files;
+}
+async function fileDigestOrEmpty(path) {
+    try {
+        return sha256Hex(new Uint8Array(await readFile(path)));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return sha256Hex(new Uint8Array(0));
+        throw error;
+    }
+}
+async function computeProjectDigests(root, manifest) {
+    const scenarioPath = await assertSafeExistingProjectPath(root, join(root, "scenario", "source.wes"));
+    const scenarioBytes = new Uint8Array(await readFile(scenarioPath));
+    try {
+        await decodeScenarioPartWesp(scenarioBytes);
+    }
+    catch (error) {
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "scenario/source.wes 无效", {
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+    // v2 的图片统一归 gallery，旧 assets 目录已不再是必需的作者内容。
+    const assetsRoot = manifest.schema_version === 1
+        ? await assertSafeExistingProjectPath(root, join(root, "scenario", "assets"))
+        : undefined;
+    const viewRoot = await assertSafeExistingProjectPath(root, join(root, "view"));
+    const galleryRoot = manifest.schema_version === 2
+        ? await assertSafeExistingProjectPath(root, join(root, "gallery"))
+        : undefined;
+    return {
+        scenario_source_sha256: await sha256Hex(scenarioBytes),
+        scenario_assets_digest: await computeCanonicalFileTreeDigest(assetsRoot === undefined ? [] : await listCanonicalFiles(root, assetsRoot, new Set())),
+        view_source_tree_sha256: await computeCanonicalFileTreeDigest(await listCanonicalFiles(root, viewRoot, new Set(["node_modules", "dist", ".vite", "package-lock.json"]))),
+        view_package_lock_sha256: await fileDigestOrEmpty(join(viewRoot, "package-lock.json")),
+        ...(galleryRoot === undefined ? {} : {
+            gallery_content_tree_sha256: await computeCanonicalFileTreeDigest(await listCanonicalFiles(root, galleryRoot, new Set())),
+        }),
+    };
+}
+function scenarioMatches(manifest, digests) {
+    return (manifest.scenario.source_sha256 === digests.scenario_source_sha256 &&
+        manifest.scenario.assets_digest === digests.scenario_assets_digest);
+}
+function viewMatches(manifest, digests) {
+    return (manifest.view.source_tree_sha256 === digests.view_source_tree_sha256 &&
+        manifest.view.package_lock_sha256 === digests.view_package_lock_sha256);
+}
+function galleryMatches(manifest, digests) {
+    return manifest.schema_version === 1 || manifest.gallery.content_tree_sha256 === digests.gallery_content_tree_sha256;
+}
+async function atomicWriteJson(path, stagingRoot, value) {
+    const root = resolve(stagingRoot, "..", "..");
+    await assertSafeExistingProjectPath(root, stagingRoot);
+    const bytes = new TextEncoder().encode(`${JSON.stringify(value, null, 2)}\n`);
+    const temp = join(stagingRoot, `manifest-${await sha256Hex(bytes)}.tmp`);
+    await assertSafeProjectParent(root, temp);
+    const handle = await open(temp, "wx");
+    try {
+        await handle.writeFile(bytes);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await assertSafeProjectParent(root, path);
+    await rename(temp, path);
+    await assertSafeExistingProjectPath(root, path);
+}
+function manifestEquals(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+export class LocalProjectHost {
+    root;
+    #manifest;
+    #scenarioWriter;
+    #toolDispatcher;
+    #desktopAuthoringRuntime;
+    #desktopAuthoringRuntimeOpening;
+    #desktopDispatchTail = Promise.resolve();
+    #desktopAuthoringCapabilities;
+    #closed = false;
+    constructor(root, manifest, options) {
+        this.root = root;
+        this.#manifest = manifest;
+        this.#scenarioWriter = new ScenarioWriter(root, options.scenario_projection_hydrator, options.scenario_writer_fault_injector);
+        this.#desktopAuthoringCapabilities = options.desktop_authoring_capabilities;
+        this.#toolDispatcher = options.authoring_adapter === undefined ? undefined : createAuthoringBridgeDispatcher(options.authoring_adapter);
+    }
+    static async open(root, options = {}) {
+        const canonicalRoot = await realpath(resolve(root));
+        const manifest = await readManifest(canonicalRoot);
+        const digests = await computeProjectDigests(canonicalRoot, manifest);
+        void digests;
+        return new LocalProjectHost(canonicalRoot, manifest, options);
+    }
+    #assertOpen() {
+        if (this.#closed)
+            throw new AuthoringBridgeError("E_PROJECT_NOT_OPEN", "ProjectHost 已关闭");
+    }
+    async inspect() {
+        this.#assertOpen();
+        this.#manifest = await readManifest(this.root);
+        const digests = await computeProjectDigests(this.root, this.#manifest);
+        return {
+            project_id: this.#manifest.project_id,
+            project_revision: this.#manifest.project_revision,
+            snapshot_id: this.#manifest.snapshot.snapshot_id,
+            snapshot_digest: this.#manifest.snapshot.canonical_digest,
+            scenario_integrity: scenarioMatches(this.#manifest, digests) ? "clean" : "dirty",
+            view_state: viewMatches(this.#manifest, digests) ? "clean" : "dirty",
+            root_dependencies_installed: await pathExists(join(this.root, "node_modules")),
+            view_dependencies_installed: await pathExists(join(this.root, "view", "node_modules")),
+        };
+    }
+    /** exact-21 descriptor 始终稳定；三个外部 callback 的执行可用性由真实注入端口决定。 */
+    isToolAvailable(name) {
+        if (name === "ask_user" || name === "preview_inspect" || name === "preview_interact") {
+            return this.#desktopAuthoringCapabilities?.[name] !== undefined;
+        }
+        return true;
+    }
+    /** Download completion fence：从真实 source/view/manifest 重新计算，不消费 receipt 自报字段。 */
+    async readTransferReadback() {
+        this.#assertOpen();
+        this.#manifest = await readManifest(this.root);
+        const digests = await computeProjectDigests(this.root, this.#manifest);
+        if (!scenarioMatches(this.#manifest, digests) || !viewMatches(this.#manifest, digests))
+            throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "ProjectHost transfer projection/digest readback 不一致");
+        return { project_revision: this.#manifest.project_revision, snapshot_digest: this.#manifest.snapshot.canonical_digest, scenario_sha256: digests.scenario_source_sha256, view_source_tree_sha256: digests.view_source_tree_sha256 };
+    }
+    /** Desktop adapter 只通过此窄端口调用已显式注入的 capability；没有 handler 即 fail-closed。 */
+    async dispatchTool(call) {
+        this.#assertOpen();
+        if (this.#toolDispatcher !== undefined && this.#desktopAuthoringRuntimeOpening === undefined) {
+            return this.#toolDispatcher.dispatch(call);
+        }
+        if (this.#desktopAuthoringRuntimeOpening === undefined) {
+            // 延迟建立 projection，使 writer 的 crash-recovery ledger 能先由相同 source writer 收敛。
+            // promise 本身也是 single-flight fence，避免并发 MCP 首帧打开两份 runtime 并泄漏一份。
+            this.#desktopAuthoringRuntimeOpening = DesktopAuthoringRuntime.open(this.root, {
+                readSourceReadback: () => this.readSourceReadback(),
+                writeScenario: (request) => this.writeScenario(request),
+            }, this.#desktopAuthoringCapabilities).then((runtime) => {
+                this.#desktopAuthoringRuntime = runtime;
+                this.#toolDispatcher = createAuthoringBridgeDispatcher(runtime.adapter);
+                return this.#toolDispatcher;
+            });
+        }
+        const dispatcher = await this.#desktopAuthoringRuntimeOpening;
+        const result = this.#desktopDispatchTail.then(() => dispatcher.dispatch(call));
+        this.#desktopDispatchTail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    async readSourceReadback() {
+        this.#assertOpen();
+        return this.#scenarioWriter.readSourceReadback();
+    }
+    /** Node-only 完整投影核对，不扩展 exact-21，不注入 embedding/model capability。 */
+    async readGraphProjectionReadback(request = {}) {
+        this.#assertOpen();
+        const result = this.#desktopDispatchTail.then(async () => {
+            const runtime = await DesktopAuthoringRuntime.open(this.root, {
+                readSourceReadback: () => this.readSourceReadback(),
+                writeScenario: (input) => this.writeScenario(input),
+            });
+            try {
+                return await runtime.readGraphProjectionReadback(request);
+            }
+            finally {
+                await runtime.close();
+            }
+        });
+        this.#desktopDispatchTail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    async writeScenario(request) {
+        this.#assertOpen();
+        const receipt = await this.#scenarioWriter.write(request);
+        this.#manifest = await readManifest(this.root);
+        return receipt;
+    }
+    async doctor() {
+        const status = await this.inspect();
+        const hardlinkChecks = await Promise.all(AGENT_KIT_ROOT_LINKS.filter(({ kind }) => kind === "hardlink").map(async (rootLink) => {
+            try {
+                const output = join(this.root, ...rootLink.path.split("/"));
+                const target = join(this.root, ...rootLink.target.split("/"));
+                return (await stat(output)).ino === (await stat(target)).ino;
+            }
+            catch {
+                return false;
+            }
+        }));
+        const junctionChecks = await Promise.all(AGENT_KIT_ROOT_LINKS.filter(({ kind }) => kind === "junction").map(async (rootLink) => {
+            try {
+                const output = join(this.root, ...rootLink.path.split("/"));
+                const target = await realpath(join(this.root, ...rootLink.target.split("/")));
+                return (await lstat(output)).isSymbolicLink() && (await realpath(output)) === target;
+            }
+            catch {
+                return false;
+            }
+        }));
+        const viewConfigPresent = await pathExists(join(this.root, "view", "package.json"));
+        const checks = [
+            { name: "project_format", ok: status.scenario_integrity === "clean" && status.view_state === "clean", detail: status.view_state === "clean" ? "manifest/WESP/View digest 一致" : "View 尚未 snapshot" },
+            { name: "manifest_wesp_hash", ok: status.scenario_integrity === "clean", detail: "manifest、WESP 与 scenario hash 一致" },
+            { name: "agent_instruction_hardlinks", ok: hardlinkChecks.every(Boolean), detail: "instructions/configs/launcher 单真相源" },
+            { name: "agent_skill_junctions", ok: junctionChecks.every(Boolean), detail: "agents/codex/claude skills 单真相源" },
+            { name: "view_config", ok: viewConfigPresent, detail: "view package 配置存在" },
+            { name: "root_node_modules", ok: status.root_dependencies_installed, detail: status.root_dependencies_installed ? "已安装" : "未安装" },
+            { name: "view_node_modules", ok: status.view_dependencies_installed, detail: status.view_dependencies_installed ? "已安装" : "未安装" },
+            { name: "projection_source_revision", ok: status.project_revision === this.#manifest.project_revision, detail: "projection 与 manifest revision 一致" },
+        ];
+        return {
+            schema_version: 1,
+            project_id: status.project_id,
+            ok: checks.every(({ ok }) => ok),
+            checks,
+        };
+    }
+    async snapshot(request) {
+        this.#assertOpen();
+        validateAuthoringEffectIdentity(request);
+        const requestDigest = await sha256Hex(new TextEncoder().encode(JSON.stringify(request)));
+        const ledgerKey = await sha256Hex(new TextEncoder().encode(request.operation_id));
+        await ensureSafeProjectDirectory(this.root, ".worldengine/operations");
+        await ensureSafeProjectDirectory(this.root, ".worldengine/snapshots");
+        await ensureSafeProjectDirectory(this.root, ".worldengine/staging");
+        const ledgerPath = await safeProjectPath(this.root, `.worldengine/operations/snapshot-${ledgerKey}.json`);
+        const lease = await acquireProjectWriterLease(this.root, {
+            entrypoint: "snapshot",
+            operation_id: request.operation_id,
+        });
+        try {
+            this.#manifest = await readManifest(this.root);
+            let ledger;
+            try {
+                ledger = JSON.parse(await readFile(await assertSafeExistingProjectPath(this.root, ledgerPath), "utf8"));
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            if (ledger !== undefined) {
+                if (ledger.request_digest !== requestDigest) {
+                    throw new AuthoringBridgeError("E_OPERATION_ID_CONFLICT", "同一 snapshot operation_id 使用了不同请求");
+                }
+                // 旧版本会把没有 source 变化的请求写成 in-flight，再尝试创建一个
+                // canonical digest 相同的 snapshot 文件。该文件已经存在时会留下 only-metadata
+                // 不同的 next_manifest；当前 manifest 仍是其 preimage，因此可安全收敛为 no-op。
+                const legacyNoChangePreimage = manifestEquals(this.#manifest, ledger.preimage) &&
+                    ledger.receipt.operation_id === request.operation_id &&
+                    ledger.receipt.project_id === this.#manifest.project_id &&
+                    ledger.receipt.previous_project_revision === this.#manifest.project_revision &&
+                    ledger.receipt.next_project_revision === this.#manifest.project_revision &&
+                    ledger.receipt.changed_sections.length === 0 &&
+                    ledger.receipt.project_snapshot_digest === this.#manifest.snapshot.canonical_digest;
+                if (legacyNoChangePreimage) {
+                    const completedLedger = {
+                        ...ledger,
+                        state: "completed",
+                        preimage: this.#manifest,
+                        next_manifest: this.#manifest,
+                    };
+                    await atomicWriteJson(ledgerPath, join(this.root, ".worldengine", "staging"), completedLedger);
+                    return completedLedger.receipt;
+                }
+                if (!manifestEquals(this.#manifest, ledger.preimage) && !manifestEquals(this.#manifest, ledger.next_manifest)) {
+                    throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "snapshot in-flight ledger 与当前 manifest 不一致");
+                }
+                if (manifestEquals(this.#manifest, ledger.next_manifest)) {
+                    if (ledger.state !== "completed") {
+                        await atomicWriteJson(ledgerPath, join(this.root, ".worldengine", "staging"), { ...ledger, state: "completed" });
+                    }
+                    this.#manifest = ledger.next_manifest;
+                    return ledger.receipt;
+                }
+                const snapshotPath = await safeProjectPath(this.root, `.worldengine/snapshots/${ledger.next_manifest.snapshot.snapshot_id}.json`);
+                try {
+                    const snapshot = JSON.parse(await readFile(await assertSafeExistingProjectPath(this.root, snapshotPath), "utf8"));
+                    if (!manifestEquals(snapshot, ledger.next_manifest)) {
+                        throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "snapshot preimage 与 in-flight ledger 不一致");
+                    }
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT")
+                        throw error;
+                    await assertSafeProjectParent(this.root, snapshotPath);
+                    await writeFile(snapshotPath, `${JSON.stringify(ledger.next_manifest, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+                    await assertSafeExistingProjectPath(this.root, snapshotPath);
+                }
+                await atomicWriteJson(join(this.root, "worldengine.project.json"), join(this.root, ".worldengine", "staging"), ledger.next_manifest);
+                this.#manifest = await readManifest(this.root);
+                if (!manifestEquals(this.#manifest, ledger.next_manifest)) {
+                    throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "snapshot manifest reconcile readback 不一致");
+                }
+                await atomicWriteJson(ledgerPath, join(this.root, ".worldengine", "staging"), { ...ledger, state: "completed" });
+                return ledger.receipt;
+            }
+            if (this.#manifest.project_revision !== request.expected_project_revision) {
+                throw new AuthoringBridgeError("E_STALE_PROJECT_REVISION", `期望 revision ${request.expected_project_revision}，当前 ${this.#manifest.project_revision}`);
+            }
+            const digests = await computeProjectDigests(this.root, this.#manifest);
+            const changedSections = [];
+            if (this.#manifest.scenario.source_sha256 !== digests.scenario_source_sha256 ||
+                this.#manifest.scenario.assets_digest !== digests.scenario_assets_digest)
+                changedSections.push("scenario");
+            if (!viewMatches(this.#manifest, digests))
+                changedSections.push("view");
+            if (!galleryMatches(this.#manifest, digests))
+                changedSections.push("gallery");
+            const previousRevision = this.#manifest.project_revision;
+            if (changedSections.length === 0) {
+                const receipt = {
+                    schema_version: 1,
+                    operation_id: request.operation_id,
+                    project_id: this.#manifest.project_id,
+                    previous_project_revision: previousRevision,
+                    next_project_revision: previousRevision,
+                    changed_sections: [],
+                    project_snapshot_digest: this.#manifest.snapshot.canonical_digest,
+                    readback_verified: true,
+                };
+                ledger = {
+                    schema_version: 1,
+                    request_digest: requestDigest,
+                    state: "in_flight",
+                    preimage: this.#manifest,
+                    next_manifest: this.#manifest,
+                    receipt,
+                };
+                await assertSafeProjectParent(this.root, ledgerPath);
+                await writeFile(ledgerPath, `${JSON.stringify(ledger, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+                await assertSafeExistingProjectPath(this.root, ledgerPath);
+                await atomicWriteJson(ledgerPath, join(this.root, ".worldengine", "staging"), { ...ledger, state: "completed" });
+                return receipt;
+            }
+            const nextRevision = changedSections.length === 0 ? previousRevision : previousRevision + 1;
+            const next = {
+                ...this.#manifest,
+                project_revision: nextRevision,
+                updated_at_ms: Date.now(),
+                scenario: {
+                    ...this.#manifest.scenario,
+                    source_sha256: digests.scenario_source_sha256,
+                    assets_digest: digests.scenario_assets_digest,
+                },
+                view: {
+                    ...this.#manifest.view,
+                    source_tree_sha256: digests.view_source_tree_sha256,
+                    package_lock_sha256: digests.view_package_lock_sha256,
+                },
+                ...(this.#manifest.schema_version === 1 ? {} : {
+                    gallery: {
+                        ...this.#manifest.gallery,
+                        content_tree_sha256: digests.gallery_content_tree_sha256,
+                    },
+                }),
+                snapshot: {
+                    snapshot_id: "snapshot_pending",
+                    canonical_digest: "0".repeat(64),
+                    previous_snapshot_id: this.#manifest.snapshot.snapshot_id,
+                },
+            };
+            next.snapshot.canonical_digest = await computeCanonicalProjectDigest(next);
+            next.snapshot.snapshot_id = `snapshot_${next.snapshot.canonical_digest.slice(0, 24)}`;
+            const snapshotPath = join(this.root, ".worldengine", "snapshots", `${next.snapshot.snapshot_id}.json`);
+            const receipt = {
+                schema_version: 1,
+                operation_id: request.operation_id,
+                project_id: next.project_id,
+                previous_project_revision: previousRevision,
+                next_project_revision: nextRevision,
+                changed_sections: changedSections,
+                project_snapshot_digest: next.snapshot.canonical_digest,
+                readback_verified: true,
+            };
+            ledger = {
+                schema_version: 1,
+                request_digest: requestDigest,
+                state: "in_flight",
+                preimage: this.#manifest,
+                next_manifest: next,
+                receipt,
+            };
+            await assertSafeProjectParent(this.root, ledgerPath);
+            await writeFile(ledgerPath, `${JSON.stringify(ledger, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+            await assertSafeExistingProjectPath(this.root, ledgerPath);
+            await assertSafeProjectParent(this.root, snapshotPath);
+            await writeFile(snapshotPath, `${JSON.stringify(next, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+            await assertSafeExistingProjectPath(this.root, snapshotPath);
+            await atomicWriteJson(join(this.root, "worldengine.project.json"), join(this.root, ".worldengine", "staging"), next);
+            const readback = await readManifest(this.root);
+            const readbackVerified = readback.project_revision === nextRevision &&
+                readback.snapshot.canonical_digest === next.snapshot.canonical_digest;
+            if (!readbackVerified) {
+                throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "manifest atomic write readback 不一致");
+            }
+            await atomicWriteJson(ledgerPath, join(this.root, ".worldengine", "staging"), { ...ledger, state: "completed" });
+            this.#manifest = next;
+            return receipt;
+        }
+        finally {
+            await lease.release();
+        }
+    }
+    async close() {
+        await this.#desktopDispatchTail;
+        await this.#desktopAuthoringRuntimeOpening?.catch(() => undefined);
+        await this.#desktopAuthoringRuntime?.close();
+        this.#closed = true;
+    }
+}

package/dist/project-writer-lease.d.ts

@@ -0,0 +1,18 @@
+export interface ProjectWriterLeaseOwner {
+    readonly [key: string]: unknown;
+}
+export interface ProjectWriterLease {
+    readonly path: string;
+    readonly leaseId: string;
+    /** Windows 使用 volume/file-index；POSIX 使用 dev/inode。 */
+    readonly fileIdentity: string;
+    release(): Promise<void>;
+}
+/**
+ * 获取 canonical project root 下的唯一 writer lease。
+ *
+ * 普通 acquire 绝不猜测或删除 stale lock；崩溃恢复必须先由独立的 owner/ledger
+ * 协议验证。Windows helper 持有不共享 DELETE 的 handle，并用同一 file identity
+ * 的 duplicate handle 完成删除，避免 path-based cleanup 误删后来者。
+ */
+export declare function acquireProjectWriterLease(root: string, owner?: ProjectWriterLeaseOwner): Promise<ProjectWriterLease>;