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

package/dist/transfer/download.js

@@ -0,0 +1,598 @@
+import { createHash } from "node:crypto";
+import { lstat, mkdir, open, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { computeCanonicalFileTreeDigest, computeCanonicalProjectDigest, decodeScenarioPartWesp, validateLocalAuthorProjectManifest } from "@world-engines/project-format";
+import { assertSafeExistingProjectPath, assertSafeProjectParent, ensureSafeProjectDirectory, safeProjectPath } from "../safe-project-path.js";
+import { withProjectWriterLease } from "../scenario-writer.js";
+const RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+const VIEW_EXCLUDED = new Set(["node_modules", "dist", ".vite"]);
+const PROJECT_GIT_VIEW_EXCLUDED = new Set(["node_modules", "dist", ".vite", ".git", ".worldengine"]);
+/** Windows checkout 与 strict Git source CAS 共用的大小写无关过滤定义。 */
+export function isProjectGitViewExcludedName(name) {
+    return PROJECT_GIT_VIEW_EXCLUDED.has(name.toLowerCase());
+}
+function digest(bytes) { return createHash("sha256").update(bytes).digest("hex"); }
+function operationKey(operationId) { return digest(new TextEncoder().encode(operationId)); }
+function wantsScenario(selection) { return selection === "scenario" || selection === "both"; }
+function wantsView(selection) { return selection === "view" || selection === "both"; }
+function remoteError(status) {
+    if (status === 401 || status === 403)
+        throw new AuthoringBridgeError("E_AUTH_REQUIRED", "远端 Download 请求未获授权");
+    throw new AuthoringBridgeError("E_VALIDATION_FAILED", `远端 Download 请求失败：HTTP ${status}`);
+}
+function object(value, message) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", message);
+    return value;
+}
+function string(value, message) {
+    if (typeof value !== "string" || value === "")
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", message);
+    return value;
+}
+function number(value, message) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", message);
+    return value;
+}
+function remoteObject(value, message) {
+    const input = object(value, message);
+    const byteLength = input.byteLength ?? input.byte_length;
+    const mediaType = input.mediaType ?? input.media_type;
+    return { key: string(input.key, message), sha256: string(input.sha256, message), byteLength: number(byteLength, message), mediaType: string(mediaType, message) };
+}
+export function parseRemoteDownloadPlan(value, now = Date.now()) {
+    const input = object(value, "远端 download plan 无效");
+    const frozen = object(input.frozenRemote, "远端 download plan 缺少 frozen remote");
+    if (!Array.isArray(input.parts) || input.parts.length < 1 || input.parts.length > 2 || new Set(input.parts).size !== input.parts.length || input.parts.some((part) => part !== "scenario" && part !== "view")) {
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "远端 download plan parts 无效");
+    }
+    const plan = {
+        planId: string(input.planId, "远端 download plan 缺少 planId"),
+        planDigest: string(input.planDigest, "远端 download plan 缺少 planDigest"),
+        expiresAtMs: number(input.expiresAtMs, "远端 download plan 缺少 expiresAtMs"),
+        frozenRemote: {
+            scenarioId: string(frozen.scenarioId, "frozen remote scenario 无效"), scenarioHead: string(frozen.scenarioHead, "frozen remote scenario head 无效"),
+            viewId: string(frozen.viewId, "frozen remote view 无效"), viewDigest: string(frozen.viewDigest, "frozen remote view digest 无效"), bindingRevision: number(frozen.bindingRevision, "frozen remote binding revision 无效"),
+        },
+        parts: input.parts,
+        ...(input.scenarioObject === undefined ? {} : { scenarioObject: remoteObject(input.scenarioObject, "scenario staging object 无效") }),
+        ...(input.viewObject === undefined ? {} : { viewObject: remoteObject(input.viewObject, "view staging object 无效") }),
+    };
+    if (!/^[a-f0-9]{64}$/.test(plan.planDigest) || !/^[a-f0-9]{64}$/.test(plan.frozenRemote.scenarioHead) || !/^[a-f0-9]{64}$/.test(plan.frozenRemote.viewDigest))
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "远端 download plan digest 无效");
+    if (plan.expiresAtMs <= now)
+        throw new AuthoringBridgeError("E_CONFIRMATION_REQUIRED", "远端 download plan 已过期；请重新计划");
+    if (plan.parts.includes("scenario") !== (plan.scenarioObject !== undefined) || plan.parts.includes("view") !== (plan.viewObject !== undefined))
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "远端 download plan objects 与 parts 不一致");
+    for (const objectRef of [plan.scenarioObject, plan.viewObject])
+        if (objectRef !== undefined && (!/^[a-f0-9]{64}$/.test(objectRef.sha256) || objectRef.byteLength <= 0 || objectRef.byteLength > 8 * 1024 * 1024 || !objectRef.key || objectRef.key.length > 256))
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "远端 download object authority 无效");
+    return plan;
+}
+export function parseRemoteDownloadOperation(value, expected) {
+    const input = object(value, "远端 download operation 无效");
+    const operation = { operationId: string(input.operationId, "远端 operation 缺少 operationId"), planId: string(input.planId, "远端 operation 缺少 planId"), planDigest: string(input.planDigest, "远端 operation 缺少 planDigest"), state: string(input.state, "远端 operation 缺少 state") };
+    if (!/^[a-f0-9]{64}$/.test(operation.planDigest) || operation.operationId.length > 256 || (expected !== undefined && (operation.planId !== expected.planId || operation.planDigest !== expected.planDigest || (expected.operationId !== undefined && operation.operationId !== expected.operationId))))
+        throw new AuthoringBridgeError("E_OPERATION_ID_CONFLICT", "远端 operation 未绑定冻结 plan/identity");
+    return operation;
+}
+function selection(parts) { return parts.length === 2 ? "both" : parts[0]; }
+function assertPlan(plan) {
+    if (plan.schema_version !== 1 || !plan.operation_id || !/^[a-f0-9]{64}$/.test(plan.plan_digest) || !Number.isSafeInteger(plan.expected_project_revision) || plan.expected_project_revision < 0) {
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "Download Replace plan 无效");
+    }
+    if (!["scenario", "view", "both"].includes(plan.selection))
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "Download Replace selection 无效");
+    if (wantsScenario(plan.selection) && plan.scenario === undefined)
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "Scenario plan 缺失");
+    if (wantsView(plan.selection) && plan.view === undefined)
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "View plan 缺失");
+    if (plan.strict_source_cas !== undefined && (plan.strict_source_cas.schema_version !== 1
+        || !/^[a-f0-9]{64}$/.test(plan.strict_source_cas.expected_source_sha256)
+        || !/^[a-f0-9]{64}$/.test(plan.strict_source_cas.expected_view_source_tree_sha256))) {
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "strict source CAS 无效");
+    }
+}
+function relativeFilePath(path) {
+    if (typeof path !== "string" || path.trim() === "" || path.includes("\\") || path.split("/").some((part) => part === "" || part === "." || part === "..")) {
+        throw new AuthoringBridgeError("E_PATH_OUTSIDE_PROJECT", "下载文件路径必须是安全相对路径");
+    }
+    return path;
+}
+async function writeAtomic(root, path, value) {
+    const staging = await ensureSafeProjectDirectory(root, ".worldengine/staging");
+    const bytes = new TextEncoder().encode(`${JSON.stringify(value, null, 2)}\n`);
+    const temp = join(staging, `download-${digest(bytes)}.tmp`);
+    await rm(temp, { force: true });
+    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);
+}
+async function readManifest(root) {
+    const path = await safeProjectPath(root, "worldengine.project.json");
+    return validateLocalAuthorProjectManifest(JSON.parse(await readFile(await assertSafeExistingProjectPath(root, path), "utf8")));
+}
+async function pathExists(path) { try {
+    await lstat(path);
+    return true;
+}
+catch (e) {
+    if (e.code === "ENOENT")
+        return false;
+    throw e;
+} }
+async function listFiles(root, directory, prefix = "", excluded = (name) => VIEW_EXCLUDED.has(name)) {
+    const canonical = await assertSafeExistingProjectPath(root, directory);
+    const entries = await readdir(canonical, { withFileTypes: true });
+    const output = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (excluded(entry.name))
+            continue;
+        const absolute = join(canonical, entry.name);
+        const info = await lstat(absolute);
+        if (info.isSymbolicLink())
+            throw new AuthoringBridgeError("E_PATH_OUTSIDE_PROJECT", `拒绝符号链接：${absolute}`);
+        const childPath = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+        if (info.isDirectory())
+            output.push(...await listFiles(root, absolute, childPath, excluded));
+        else if (info.isFile())
+            output.push({ path: childPath, bytes: new Uint8Array(await readFile(await assertSafeExistingProjectPath(root, absolute))) });
+    }
+    return output;
+}
+async function viewDigests(root) {
+    const view = await assertSafeExistingProjectPath(root, join(root, "view"));
+    const source = await computeCanonicalFileTreeDigest(await listFiles(root, view));
+    const lockPath = join(view, "package-lock.json");
+    const lock = await pathExists(lockPath) ? digest(new Uint8Array(await readFile(await assertSafeExistingProjectPath(root, lockPath)))) : digest(new Uint8Array());
+    return { source_tree_sha256: source, package_lock_sha256: lock };
+}
+async function strictProjectGitViewSourceDigest(root) {
+    const view = await assertSafeExistingProjectPath(root, join(root, "view"));
+    return computeCanonicalFileTreeDigest(await listFiles(root, view, "", isProjectGitViewExcludedName));
+}
+function dependencyVersions(bytes) {
+    if (bytes === undefined)
+        return new Map();
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        return new Map();
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return new Map();
+    const source = value;
+    const output = new Map();
+    for (const field of ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"]) {
+        const section = source[field];
+        if (typeof section !== "object" || section === null || Array.isArray(section))
+            continue;
+        for (const [name, version] of Object.entries(section))
+            if (typeof version === "string")
+                output.set(name, version);
+    }
+    return output;
+}
+function dependencyDiff(local, incoming) {
+    const before = dependencyVersions(local["package.json"]);
+    const after = dependencyVersions(incoming["package.json"]);
+    const added = [...after.keys()].filter((key) => !before.has(key)).sort();
+    const removed = [...before.keys()].filter((key) => !after.has(key)).sort();
+    const changed = [...after.keys()].filter((key) => before.has(key) && before.get(key) !== after.get(key)).sort();
+    const lockfile_changes = ["package-lock.json", "pnpm-lock.yaml", "yarn.lock"].some((path) => {
+        const beforeBytes = local[path];
+        const afterBytes = incoming[path];
+        return (beforeBytes === undefined) !== (afterBytes === undefined) || (beforeBytes !== undefined && afterBytes !== undefined && digest(beforeBytes) !== digest(afterBytes));
+    });
+    return { added, removed, changed, lockfile_changes };
+}
+async function selectedLocalFiles(root, parts) {
+    const output = [];
+    for (const part of parts) {
+        const directory = join(root, part);
+        const files = await listFiles(root, directory);
+        output.push(...files.map((file) => ({ path: `${part}/${file.path}`, bytes: file.bytes })));
+    }
+    return output.sort((left, right) => left.path.localeCompare(right.path));
+}
+function incomingViewFiles(plan) {
+    const output = {};
+    for (const file of plan.view?.files ?? [])
+        output[relativeFilePath(file.path)] = new Uint8Array(Buffer.from(file.content_base64, "base64"));
+    return output;
+}
+async function inspectLocalDownload(root, plan, remotePlanId = plan.operation_id) {
+    assertPlan(plan);
+    const manifest = await readManifest(root);
+    const parts = plan.selection === "both" ? ["scenario", "view"] : [plan.selection];
+    if (plan.scenario !== undefined) {
+        const source = new Uint8Array(Buffer.from(plan.scenario.source_base64, "base64"));
+        if (digest(source) !== plan.scenario.sha256)
+            throw new AuthoringBridgeError("E_VALIDATION_FAILED", "Scenario hash 与 frozen plan 不一致");
+        await decodeScenarioPartWesp(source);
+    }
+    const incoming = incomingViewFiles(plan);
+    for (const [path, bytes] of Object.entries(incoming)) {
+        const source = plan.view.files.find((file) => file.path === path);
+        if (digest(bytes) !== source.sha256)
+            throw new AuthoringBridgeError("E_VALIDATION_FAILED", `View hash 不一致：${path}`);
+    }
+    const files = await selectedLocalFiles(root, parts);
+    const localView = {};
+    for (const file of files)
+        if (file.path.startsWith("view/"))
+            localView[file.path.slice("view/".length)] = file.bytes;
+    const current_snapshot_digest = await computeCanonicalFileTreeDigest(files);
+    const scenarioFiles = files.filter((file) => file.path.startsWith("scenario/"));
+    const viewFiles = files.filter((file) => file.path.startsWith("view/"));
+    const local_overwrite_summary = {
+        scenario_file_count: String(scenarioFiles.length),
+        scenario_bytes: String(scenarioFiles.reduce((total, file) => total + file.bytes.length, 0)),
+        view_file_count: String(viewFiles.length),
+        view_bytes: String(viewFiles.reduce((total, file) => total + file.bytes.length, 0)),
+        current_snapshot_digest,
+    };
+    const object_digests = {};
+    if (plan.scenario !== undefined)
+        object_digests.scenario = plan.scenario.sha256;
+    if (plan.view !== undefined)
+        object_digests.view = digest(new TextEncoder().encode(JSON.stringify(plan.view.files.map((file) => [file.path, file.sha256]))));
+    const facts = { project_id: manifest.project_id, remote_plan_id: remotePlanId, remote_plan_digest: plan.plan_digest, expected_project_revision: manifest.project_revision, parts, object_digests, local_overwrite_summary, dependency_diff: dependencyDiff(localView, incoming) };
+    return { schema_version: 1, ...facts, local_inspection_digest: digest(new TextEncoder().encode(JSON.stringify(facts))) };
+}
+export class DownloadReplaceCoordinator {
+    root;
+    #dependencies;
+    constructor(root, dependencies) { this.root = root; this.#dependencies = dependencies; }
+    static async open(root, dependencies = {}) {
+        return new DownloadReplaceCoordinator(await assertSafeExistingProjectPath(root, root), dependencies);
+    }
+    /** 深模块 seam：调用方只提交冻结内容，所有本地树、依赖与 digest 由 host 自己读取。 */
+    async inspect(plan, remotePlanId = plan.operation_id) {
+        return inspectLocalDownload(this.root, plan, remotePlanId);
+    }
+    async prepare(plan) {
+        assertPlan(plan);
+        const key = operationKey(plan.operation_id);
+        const stage = await ensureSafeProjectDirectory(this.root, `.worldengine/download-staging/${key}`);
+        const incoming = join(stage, "incoming");
+        await ensureSafeProjectDirectory(this.root, ".worldengine/download-operations");
+        const ledgerPath = await safeProjectPath(this.root, `.worldengine/download-operations/${key}.json`);
+        let existing;
+        if (await pathExists(ledgerPath)) {
+            const ledger = JSON.parse(await readFile(await assertSafeExistingProjectPath(this.root, ledgerPath), "utf8"));
+            if (ledger.plan.plan_digest !== plan.plan_digest)
+                throw new AuthoringBridgeError("E_OPERATION_ID_CONFLICT", "operation_id 已绑定另一份 Download plan");
+            if (ledger.state === "completed")
+                return;
+            if (ledger.state === "prepared" && await pathExists(incoming))
+                return;
+            // restore/crash 后 incoming 已被 swap 消费。必须从同一冻结 plan 重建 staging，
+            // 不能创建新 operation，也不能把旧 preimage 当作新输入。
+            existing = ledger;
+        }
+        await rm(incoming, { recursive: true, force: true });
+        await mkdir(incoming, { recursive: true });
+        if (wantsScenario(plan.selection)) {
+            const bytes = new Uint8Array(Buffer.from(plan.scenario.source_base64, "base64"));
+            if (digest(bytes) !== plan.scenario.sha256)
+                throw new AuthoringBridgeError("E_VALIDATION_FAILED", "Scenario hash 与 frozen plan 不一致");
+            await decodeScenarioPartWesp(bytes);
+            await mkdir(join(incoming, "scenario"));
+            await mkdir(join(incoming, "scenario", "assets"));
+            await writeFile(join(incoming, "scenario", "source.wes"), bytes, { flag: "wx" });
+        }
+        if (wantsView(plan.selection)) {
+            const view = join(incoming, "view");
+            await mkdir(view);
+            const seen = new Set();
+            for (const file of plan.view.files) {
+                const path = relativeFilePath(file.path);
+                if (seen.has(path))
+                    throw new AuthoringBridgeError("E_SCHEMA_INVALID", "View plan 包含重复路径");
+                seen.add(path);
+                const bytes = new Uint8Array(Buffer.from(file.content_base64, "base64"));
+                if (digest(bytes) !== file.sha256)
+                    throw new AuthoringBridgeError("E_VALIDATION_FAILED", `View hash 不一致：${path}`);
+                const target = resolve(view, ...path.split("/"));
+                if (!target.startsWith(`${view}${sep}`))
+                    throw new AuthoringBridgeError("E_PATH_OUTSIDE_PROJECT", "View staging 路径越界");
+                await mkdir(resolve(target, ".."), { recursive: true });
+                await writeFile(target, bytes, { flag: "wx" });
+            }
+            await listFiles(this.root, view); // tree/reparse 验证
+            if (plan.view.install_dependencies) {
+                if (this.#dependencies.installViewDependencies === undefined)
+                    throw new AuthoringBridgeError("E_VALIDATION_FAILED", "未注入 staging dependency installer");
+                await this.#dependencies.installViewDependencies(view);
+            }
+        }
+        await ensureSafeProjectDirectory(this.root, ".worldengine/download-history");
+        const history = await safeProjectPath(this.root, `.worldengine/download-history/${key}`);
+        await writeAtomic(this.root, ledgerPath, existing === undefined
+            ? { schema_version: 1, plan, state: "prepared", history_path: history }
+            : { ...existing, state: "prepared", receipt: undefined });
+    }
+    async apply(plan, confirmation, inspection) {
+        if (confirmation?.operation_id !== plan.operation_id || confirmation.plan_digest !== plan.plan_digest)
+            throw new AuthoringBridgeError("E_CONFIRMATION_REQUIRED", "Download Replace 必须确认冻结 plan 后才写入本地项目");
+        const key = operationKey(plan.operation_id);
+        await ensureSafeProjectDirectory(this.root, ".worldengine/download-operations");
+        const ledgerPath = await safeProjectPath(this.root, `.worldengine/download-operations/${key}.json`);
+        for (;;) {
+            const replay = await withProjectWriterLease(this.root, async () => {
+                const ledger = await this.#readLedger(ledgerPath);
+                if (ledger === undefined)
+                    return undefined;
+                if (ledger.plan.plan_digest !== plan.plan_digest)
+                    throw new AuthoringBridgeError("E_OPERATION_ID_CONFLICT", "operation ledger 不匹配");
+                if (ledger.state === "completed")
+                    return ledger.receipt;
+                if (ledger.state !== "prepared")
+                    await this.#restoreUnderLease(plan.operation_id);
+                return undefined;
+            });
+            if (replay !== undefined)
+                return replay;
+            // staging/npm ci 可能很慢，且不触碰已发布 project parts，绝不能占有 writer lease。
+            await this.prepare(plan);
+            const receipt = await withProjectWriterLease(this.root, async () => {
+                const ledger = await this.#readLedger(ledgerPath);
+                if (ledger === undefined)
+                    throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "download operation ledger 丢失");
+                if (ledger.plan.plan_digest !== plan.plan_digest)
+                    throw new AuthoringBridgeError("E_OPERATION_ID_CONFLICT", "operation ledger 不匹配");
+                if (ledger.state === "completed")
+                    return ledger.receipt;
+                if (ledger.state !== "prepared") {
+                    await this.#restoreUnderLease(plan.operation_id);
+                    return undefined;
+                }
+                return this.#applyPreparedUnderLease(plan, key, ledgerPath, ledger, inspection);
+            });
+            if (receipt !== undefined)
+                return receipt;
+        }
+    }
+    async #readLedger(ledgerPath) {
+        if (!await pathExists(ledgerPath))
+            return undefined;
+        return JSON.parse(await readFile(await assertSafeExistingProjectPath(this.root, ledgerPath), "utf8"));
+    }
+    async #applyPreparedUnderLease(plan, key, ledgerPath, initialLedger, confirmedInspection) {
+        const manifest = await readManifest(this.root);
+        if (manifest.project_revision < plan.expected_project_revision)
+            throw new AuthoringBridgeError("E_STALE_PROJECT_REVISION", `期望 revision 至少 ${plan.expected_project_revision}，当前 ${manifest.project_revision}`);
+        if (plan.strict_source_cas !== undefined) {
+            if (manifest.project_revision !== plan.expected_project_revision)
+                throw new AuthoringBridgeError("E_STALE_PROJECT_REVISION", `strict source CAS 期望 revision ${plan.expected_project_revision}，当前 ${manifest.project_revision}`);
+            const currentSource = digest(new Uint8Array(await readFile(await assertSafeExistingProjectPath(this.root, join(this.root, "scenario", "source.wes")))));
+            const currentViewSourceDigest = await strictProjectGitViewSourceDigest(this.root);
+            if (currentSource !== plan.strict_source_cas.expected_source_sha256 || currentViewSourceDigest !== plan.strict_source_cas.expected_view_source_tree_sha256) {
+                throw new AuthoringBridgeError("E_STALE_PROJECT_REVISION", "strict source CAS 检测到本地 source 或视图树已改变");
+            }
+        }
+        const currentInspection = await this.inspect(plan, confirmedInspection?.remote_plan_id ?? plan.operation_id);
+        if (confirmedInspection !== undefined) {
+            if (confirmedInspection.schema_version !== 1 || confirmedInspection.project_id !== manifest.project_id || confirmedInspection.remote_plan_digest !== plan.plan_digest || confirmedInspection.expected_project_revision !== plan.expected_project_revision || JSON.stringify(confirmedInspection.parts) !== JSON.stringify(currentInspection.parts)) {
+                throw new AuthoringBridgeError("E_VALIDATION_FAILED", "download inspection 未绑定当前项目/冻结 plan");
+            }
+        }
+        const inspection_changed_since_confirmation = confirmedInspection !== undefined && confirmedInspection.local_inspection_digest !== currentInspection.local_inspection_digest;
+        const history = await ensureSafeProjectDirectory(this.root, `.worldengine/download-history/${key}`);
+        await writeAtomic(this.root, join(history, "manifest.json"), manifest);
+        await writeAtomic(this.root, join(history, "metadata.json"), { schema_version: 1, operation_id: plan.operation_id, created_at_ms: (this.#dependencies.now ?? Date.now)(), pinned: false, inspection_changed_since_confirmation, local_inspection_digest: currentInspection.local_inspection_digest, local_overwrite_summary: currentInspection.local_overwrite_summary });
+        let ledger = { ...initialLedger, state: "preimage_saved" };
+        await writeAtomic(this.root, ledgerPath, ledger);
+        const incoming = join(this.root, ".worldengine", "download-staging", key, "incoming");
+        try {
+            if (wantsScenario(plan.selection)) {
+                await rename(join(this.root, "scenario"), join(history, "scenario"));
+                await rename(join(incoming, "scenario"), join(this.root, "scenario"));
+                await this.#dependencies.fault?.("after_scenario_rename");
+            }
+            if (wantsView(plan.selection)) {
+                await rename(join(this.root, "view"), join(history, "view"));
+                await rename(join(incoming, "view"), join(this.root, "view"));
+                await this.#dependencies.fault?.("after_view_rename");
+            }
+            ledger = { ...ledger, state: "swapped" };
+            await writeAtomic(this.root, ledgerPath, ledger);
+            const scenario = wantsScenario(plan.selection) ? digest(new Uint8Array(await readFile(join(this.root, "scenario", "source.wes")))) : manifest.scenario.source_sha256;
+            await decodeScenarioPartWesp(new Uint8Array(await readFile(join(this.root, "scenario", "source.wes"))));
+            const view = await viewDigests(this.root);
+            const next = { ...manifest, project_revision: manifest.project_revision + 1, updated_at_ms: (this.#dependencies.now ?? Date.now)(), scenario: { ...manifest.scenario, source_sha256: scenario }, view: { ...manifest.view, ...view }, snapshot: { ...manifest.snapshot, previous_snapshot_id: manifest.snapshot.snapshot_id, snapshot_id: "snapshot_pending", canonical_digest: "0".repeat(64) } };
+            next.snapshot.canonical_digest = await computeCanonicalProjectDigest(next);
+            next.snapshot.snapshot_id = `snapshot_${next.snapshot.canonical_digest.slice(0, 24)}`;
+            await writeAtomic(this.root, join(this.root, "worldengine.project.json"), next);
+            const readback = await readManifest(this.root);
+            if (readback.project_revision !== next.project_revision || readback.snapshot.canonical_digest !== next.snapshot.canonical_digest)
+                throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "manifest readback 不一致");
+            const receipt = { operation_id: plan.operation_id, previous_project_revision: manifest.project_revision, next_project_revision: next.project_revision, selection: plan.selection, readback_verified: true, restored: false, scenario_sha256: scenario, view_source_tree_sha256: view.source_tree_sha256, project_snapshot_digest: next.snapshot.canonical_digest, inspection_changed_since_confirmation, local_inspection_digest: currentInspection.local_inspection_digest, local_overwrite_summary: currentInspection.local_overwrite_summary };
+            await this.#dependencies.readProjection?.(receipt);
+            ledger = { ...ledger, state: "completed", receipt };
+            await writeAtomic(this.root, ledgerPath, ledger);
+            return receipt;
+        }
+        catch (error) {
+            await this.#restoreUnderLease(plan.operation_id);
+            throw error;
+        }
+    }
+    async restore(operationId) {
+        return withProjectWriterLease(this.root, () => this.#restoreUnderLease(operationId));
+    }
+    async #restoreUnderLease(operationId) {
+        const key = operationKey(operationId);
+        const ledgerPath = await safeProjectPath(this.root, `.worldengine/download-operations/${key}.json`);
+        const ledger = JSON.parse(await readFile(await assertSafeExistingProjectPath(this.root, ledgerPath), "utf8"));
+        const history = await assertSafeExistingProjectPath(this.root, ledger.history_path);
+        const staging = await ensureSafeProjectDirectory(this.root, `.worldengine/download-staging/${key}/replaced`);
+        for (const part of ["scenario", "view"]) {
+            if (!(part === "scenario" ? wantsScenario(ledger.plan.selection) : wantsView(ledger.plan.selection)))
+                continue;
+            const original = join(history, part);
+            const target = join(this.root, part);
+            if (await pathExists(original)) {
+                if (await pathExists(target)) {
+                    const displaced = join(staging, part);
+                    await rm(displaced, { recursive: true, force: true });
+                    await rename(target, displaced);
+                }
+                await rename(original, target);
+            }
+        }
+        const preimage = JSON.parse(await readFile(join(history, "manifest.json"), "utf8"));
+        await writeAtomic(this.root, join(this.root, "worldengine.project.json"), preimage);
+        await writeAtomic(this.root, ledgerPath, { ...ledger, state: "restored" });
+    }
+    async setHistoryPinned(operationId, pinned) { const key = operationKey(operationId); const metadata = await safeProjectPath(this.root, `.worldengine/download-history/${key}/metadata.json`); const value = JSON.parse(await readFile(await assertSafeExistingProjectPath(this.root, metadata), "utf8")); await writeAtomic(this.root, metadata, { ...value, pinned }); }
+    async pruneHistory(now = (this.#dependencies.now ?? Date.now)()) { const root = await ensureSafeProjectDirectory(this.root, ".worldengine/download-history"); for (const entry of await readdir(root, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const metadata = join(root, entry.name, "metadata.json");
+        try {
+            const value = JSON.parse(await readFile(metadata, "utf8"));
+            if (!value.pinned && typeof value.created_at_ms === "number" && now - value.created_at_ms > RETENTION_MS)
+                await rm(join(root, entry.name), { recursive: true, force: true });
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    } }
+}
+/**
+ * 将稳定远端路由收敛成可重放的单 target 下载：先由远端冻结对象，再在本地验证
+ * staging 内容；本地失败不会新建 operation，而是让同一 operation 走 reconcile。
+ */
+export class RemoteDownloadCoordinator {
+    #projectId;
+    #transport;
+    #local;
+    constructor(projectId, transport, local) {
+        this.#projectId = projectId;
+        this.#transport = transport;
+        this.#local = local;
+    }
+    static async open(root, projectId, transport, dependencies = {}) {
+        if (!projectId)
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "download 缺少 project_id");
+        return new RemoteDownloadCoordinator(projectId, transport, await DownloadReplaceCoordinator.open(root, dependencies));
+    }
+    #transportOrThrow() {
+        if (this.#transport === undefined)
+            throw new AuthoringBridgeError("E_AUTH_REQUIRED", "CLI 没有 ProjectAuthBroker 受控 transport");
+        return this.#transport;
+    }
+    async plan(request) {
+        if (request.project_id !== this.#projectId || !request.target_pair_id || request.parts.length < 1 || request.parts.length > 2 || new Set(request.parts).size !== request.parts.length) {
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "download plan 必须是当前项目的单 target 与明确 parts");
+        }
+        const body = { projectId: request.project_id, targetPairId: request.target_pair_id, parts: [...request.parts] };
+        const response = await this.#transportOrThrow().request({ project_id: this.#projectId, method: "POST", path: "/v1/creator/project-transfer/download/plan", body, body_digest: digest(new TextEncoder().encode(JSON.stringify(body))) });
+        if (response.status < 200 || response.status >= 300)
+            remoteError(response.status);
+        return parseRemoteDownloadPlan(response.body);
+    }
+    async confirm(plan, confirmPlanDigest) {
+        if (confirmPlanDigest !== plan.planDigest)
+            throw new AuthoringBridgeError("E_CONFIRMATION_REQUIRED", "--confirm-plan 与远端冻结 plan digest 不匹配");
+        if (plan.expiresAtMs <= Date.now())
+            throw new AuthoringBridgeError("E_CONFIRMATION_REQUIRED", "远端 download plan 已过期；请重新计划");
+        const body = { planId: plan.planId, planDigest: plan.planDigest, confirmation: "force_overwrite" };
+        const response = await this.#transportOrThrow().request({ project_id: this.#projectId, method: "POST", path: "/v1/creator/project-transfer/download/confirm", body, body_digest: digest(new TextEncoder().encode(JSON.stringify(body))) });
+        if (response.status < 200 || response.status >= 300)
+            remoteError(response.status);
+        return parseRemoteDownloadOperation(response.body, { planId: plan.planId, planDigest: plan.planDigest });
+    }
+    async operation(operationId, reconcile = false) {
+        if (!operationId)
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "download operation_id 不能为空");
+        const response = await this.#transportOrThrow().request({ project_id: this.#projectId, method: reconcile ? "POST" : "GET", path: `/v1/creator/project-transfer/download/operations/${encodeURIComponent(operationId)}${reconcile ? "/reconcile" : ""}` });
+        if (response.status < 200 || response.status >= 300)
+            remoteError(response.status);
+        return parseRemoteDownloadOperation(response.body, { operationId, planId: string(object(response.body, "远端 operation 无效").planId, "operation planId 无效"), planDigest: string(object(response.body, "远端 operation 无效").planDigest, "operation planDigest 无效") });
+    }
+    async apply(plan, operation) {
+        if (operation.planId !== plan.planId || operation.planDigest !== plan.planDigest)
+            throw new AuthoringBridgeError("E_OPERATION_ID_CONFLICT", "同一 download operation 不能绑定另一份 plan");
+        const source = plan.scenarioObject === undefined ? undefined : await this.#fetchObject(plan.scenarioObject, "application/vnd.worldengine.wesp");
+        const view = plan.viewObject === undefined ? undefined : await this.#fetchObject(plan.viewObject, "application/vnd.worldengine.svp");
+        const localPlan = {
+            schema_version: 1,
+            operation_id: operation.operationId,
+            plan_digest: plan.planDigest,
+            expected_project_revision: (await readManifest(this.#local.root)).project_revision,
+            selection: selection(plan.parts),
+            ...(source === undefined ? {} : { scenario: { source_base64: Buffer.from(source).toString("base64"), sha256: digest(source) } }),
+            ...(view === undefined ? {} : { view: decodeRemoteViewBundle(view) }),
+        };
+        try {
+            return await this.#local.apply(localPlan, { operation_id: operation.operationId, plan_digest: plan.planDigest });
+        }
+        catch (error) {
+            // 不确定的本地异常只能读取同一 remote identity；不发送新的 confirm。
+            await this.operation(operation.operationId, true).catch(() => undefined);
+            throw error;
+        }
+    }
+    async restore(operationId) { await this.#local.restore(operationId); }
+    async #fetchObject(objectRef, expectedMediaType) {
+        if (objectRef.mediaType !== expectedMediaType)
+            throw new AuthoringBridgeError("E_VALIDATION_FAILED", `远端 staging object media type 无效：${objectRef.mediaType}`);
+        const response = await this.#transportOrThrow().request({ project_id: this.#projectId, method: "GET", path: `/v1/creator/project-transfer/download/staging/${encodeURIComponent(objectRef.key)}` });
+        if (response.status < 200 || response.status >= 300)
+            remoteError(response.status);
+        const encoded = object(response.body, "远端 staging object 响应无效").contentBase64;
+        const bytes = new Uint8Array(Buffer.from(string(encoded, "远端 staging object 缺少 contentBase64"), "base64"));
+        if (bytes.length !== objectRef.byteLength || digest(bytes) !== objectRef.sha256 || (response.readback !== undefined && (response.readback.byte_length !== bytes.length || response.readback.sha256 !== objectRef.sha256))) {
+            throw new AuthoringBridgeError("E_VALIDATION_FAILED", "远端 staging object readback 不匹配");
+        }
+        return bytes;
+    }
+}
+export function decodeRemoteViewBundle(bytes) {
+    let value;
+    // SVP v1: magic/version/flags + updated_at_ms + payload length。当前 ProjectHost
+    // 只接受 upload snapshot 生成的未压缩 flags=0 形式；旧 CLI JSON 仅为兼容已冻结 operation。
+    let payload = bytes;
+    if (bytes.length >= 17 && bytes[0] === 0x53 && bytes[1] === 0x56 && bytes[2] === 0x50 && bytes[3] === 0x01) {
+        if (bytes[4] !== 0)
+            throw new AuthoringBridgeError("E_VALIDATION_FAILED", "远端 SVP 压缩形式不受 ProjectHost 支持");
+        const length = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(13, true);
+        if (bytes.length !== 17 + length)
+            throw new AuthoringBridgeError("E_VALIDATION_FAILED", "远端 SVP payload 长度无效");
+        payload = bytes.subarray(17);
+    }
+    try {
+        value = JSON.parse(new TextDecoder().decode(payload));
+    }
+    catch {
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "远端 View staging bundle 不是有效 SVP JSON");
+    }
+    const input = object(value, "远端 View staging bundle 无效");
+    if (!Array.isArray(input.files) || (input.installDependencies !== undefined && typeof input.installDependencies !== "boolean"))
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "远端 View staging bundle 缺少 files/installDependencies");
+    return {
+        install_dependencies: input.installDependencies === true,
+        files: input.files.map((entry) => {
+            const file = object(entry, "远端 View 文件无效");
+            const contentBase64 = file.contentBase64 ?? file.content_base64;
+            const encoded = string(contentBase64, "远端 View 文件 contentBase64 无效");
+            return { path: string(file.path, "远端 View 文件 path 无效"), content_base64: encoded, sha256: file.sha256 === undefined ? digest(new Uint8Array(Buffer.from(encoded, "base64"))) : string(file.sha256, "远端 View 文件 sha256 无效") };
+        }),
+    };
+}

package/dist/transfer/transport.d.ts

@@ -0,0 +1,26 @@
+/**
+ * ProjectAuthBroker 注入的无状态受控 HTTP 出口。它故意不暴露 cookie、token 或
+ * WebView profile；调用者只提供 project identity、经过摘要的 body 与路径。
+ */
+export interface ProjectTransferTransport {
+    request(request: Readonly<{
+        project_id: string;
+        method: "GET" | "POST" | "PUT" | "HEAD";
+        path: string;
+        content_type?: "application/x-ndjson; profile=\"chat-artifact-v5-submit-stream-v1\"" | "application/x-git-upload-pack-request" | "application/x-git-receive-pack-request";
+        operation_id?: string;
+        body_digest?: string;
+        body_size?: number;
+        raw_body_digest?: string;
+        raw_body_size?: number;
+        body_codec?: "identity-v1" | "gzip-member-v1";
+        body?: unknown | Uint8Array;
+    }>): Promise<Readonly<{
+        status: number;
+        body: unknown;
+        readback?: Readonly<{
+            sha256: string;
+            byte_length: number;
+        }>;
+    }>>;
+}

package/dist/transfer/transport.js

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