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

package/dist/transfer/upload.d.ts

@@ -0,0 +1,162 @@
+import { ScenarioPartSourceV1 } from "@world-engines/protocol-ts/v1/scenario_part_source";
+import { type NeutralUploadLogicalObjectRefV2 } from "@world-engines/project-format";
+import { type FrozenReviewTargetBinding } from "../frozen-review-local-pipeline.js";
+import type { ProjectTransferTransport } from "./transport.js";
+export type UploadPartKind = "scenario" | "view";
+export interface UploadTarget {
+    readonly client_target_key: string;
+    readonly scenario_id?: string;
+    readonly view_id?: string;
+    readonly creates_scenario: boolean;
+    readonly creates_view: boolean;
+    readonly scenario_title?: string;
+    readonly view_title?: string;
+    readonly copy_on_bind: boolean;
+    readonly scenario_head?: string;
+    readonly view_digest?: string;
+    readonly binding_revision?: number;
+}
+export interface UploadSnapshot {
+    readonly snapshot_id: string;
+    readonly snapshot_digest: string;
+    readonly updated_at_ms: number;
+}
+export interface UploadObject {
+    readonly part_kind: UploadPartKind;
+    readonly sha256: string;
+    readonly byte_length: number;
+    readonly media_type: string;
+}
+export interface RemoteUploadPlan extends UploadSnapshot {
+    readonly operation_id: string;
+    readonly plan_id: string;
+    readonly plan_digest: string;
+    readonly expires_at_ms: number;
+    readonly targets: readonly UploadTarget[];
+    readonly objects: readonly UploadObject[];
+    readonly logical_objects?: readonly NeutralUploadLogicalObjectRefV2[];
+}
+export interface RemoteUploadOperation {
+    readonly operation_id: string;
+    readonly plan_id: string;
+    readonly plan_digest: string;
+    readonly state: string;
+    readonly targets: readonly Readonly<Record<string, unknown>>[];
+}
+export interface BindFrozenReviewUploadTargetOptions {
+    /** 多 target operation 必须显式提供；单 target 可省略。 */
+    readonly client_target_key?: string;
+}
+export interface UploadPlanRequest {
+    readonly operation_id: string;
+    readonly expires_at_ms: number;
+    readonly targets: readonly UploadTarget[];
+}
+export interface CapturedUploadObject extends UploadObject {
+    readonly bytes: Uint8Array;
+}
+export interface CapturedUploadSnapshot {
+    readonly snapshot: UploadSnapshot;
+    readonly objects: readonly CapturedUploadObject[];
+}
+export interface UploadPlanWireTarget {
+    readonly clientTargetKey: string;
+    readonly scenarioMode: "existing" | "create";
+    readonly scenarioId?: string;
+    readonly scenarioTitle?: string;
+    readonly viewMode: "existing" | "create";
+    readonly viewId?: string;
+    readonly viewTitle?: string;
+    readonly createsScenario: boolean;
+    readonly createsView: boolean;
+    readonly copyOnBind: boolean;
+    readonly scenarioHead?: string;
+    readonly viewDigest?: string;
+    readonly bindingRevision?: number;
+}
+/** CLI/GUI 与 Edge UploadPlanBody 共用的唯一 client target builder。 */
+export declare function buildUploadPlanTarget(target: UploadTarget): UploadPlanWireTarget;
+/** 生成未压缩 SVP v1；flags=0 是 SVP codec 支持的合法形式，避免 CLI 依赖 WebAssembly brotli。 */
+/** Desktop private sidecar 与 CLI 共用的真实冻结快照；只返回当前项目 authority bytes。 */
+export declare function captureUploadSnapshot(root: string): Promise<CapturedUploadSnapshot>;
+/** 与 Edge wesp::scenario_sections 共用 golden 语义的 Node 映射。 */
+export declare function mapScenarioPartToNeutralSections(source: ScenarioPartSourceV1, view: Uint8Array, localWesp: Uint8Array): readonly [{
+    readonly section_key: string;
+    readonly media_type: "application/json";
+    readonly canonical_encoding: "canonical-json-v1";
+    readonly payload: Uint8Array;
+}, {
+    readonly section_key: string;
+    readonly media_type: "application/json";
+    readonly canonical_encoding: "canonical-json-v1";
+    readonly payload: Uint8Array;
+}, {
+    readonly section_key: string;
+    readonly media_type: "application/json";
+    readonly canonical_encoding: "canonical-json-v1";
+    readonly payload: Uint8Array;
+}, {
+    readonly section_key: string;
+    readonly media_type: "application/json";
+    readonly canonical_encoding: "canonical-json-v1";
+    readonly payload: Uint8Array;
+}, {
+    readonly section_key: "view_project";
+    readonly media_type: "application/vnd.worldengine.svp";
+    readonly canonical_encoding: "svp-v1";
+    readonly payload: Uint8Array;
+}, {
+    readonly section_key: string;
+    readonly media_type: "application/json";
+    readonly canonical_encoding: "canonical-json-v1";
+    readonly payload: Uint8Array;
+}, {
+    readonly section_key: string;
+    readonly media_type: "application/json";
+    readonly canonical_encoding: "canonical-json-v1";
+    readonly payload: Uint8Array;
+}, {
+    readonly section_key: string;
+    readonly media_type: "application/json";
+    readonly canonical_encoding: "canonical-json-v1";
+    readonly payload: Uint8Array;
+}, {
+    readonly section_key: string;
+    readonly media_type: "application/json";
+    readonly canonical_encoding: "canonical-json-v1";
+    readonly payload: Uint8Array;
+}, {
+    readonly section_key: string;
+    readonly media_type: "application/json";
+    readonly canonical_encoding: "canonical-json-v1";
+    readonly payload: Uint8Array;
+}, {
+    readonly section_key: string;
+    readonly media_type: "application/json";
+    readonly canonical_encoding: "canonical-json-v1";
+    readonly payload: Uint8Array;
+}, {
+    readonly section_key: "local_project_wesp";
+    readonly media_type: "application/vnd.worldengine.scenario-part+wesp";
+    readonly canonical_encoding: "wesp-v1";
+    readonly payload: Uint8Array;
+}, {
+    readonly section_key: "spatial_world";
+    readonly media_type: "application/x-protobuf";
+    readonly canonical_encoding: "chat.v1.SpatialWorldSourceV1";
+    readonly payload: any;
+}];
+/** GUI/CLI 共用的远端 fanout coordinator；所有恢复始终使用同一 operation_id。 */
+export declare class RemoteUploadCoordinator {
+    #private;
+    private constructor();
+    static open(root: string, projectId: string, transport: ProjectTransferTransport | undefined): Promise<RemoteUploadCoordinator>;
+    plan(request: UploadPlanRequest): Promise<RemoteUploadPlan>;
+    confirm(plan: RemoteUploadPlan, planDigest: string): Promise<RemoteUploadOperation>;
+    operation(operationId: string, reconcile?: boolean): Promise<RemoteUploadOperation>;
+    /** 仅消费 terminal authoritative upload witness；不从本地 WESP 或 plan 推导 Neutral identity。 */
+    bindFrozenReviewTarget(operationId: string, options?: BindFrozenReviewUploadTargetOptions): Promise<FrozenReviewTargetBinding>;
+    /** retry 只能复用既有 operation identity，服务端负责从该 operation 的冻结计划恢复。 */
+    retry(operationId: string): Promise<RemoteUploadOperation>;
+    undo(operationId: string): Promise<RemoteUploadOperation>;
+}

package/dist/transfer/upload.js

@@ -0,0 +1,354 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { ScenarioPartSourceV1, SpatialWorldSourceV1 } from "@world-engines/protocol-ts/v1/scenario_part_source";
+import { ScenarioSourceManifest as ScenarioSourceManifestCodec } from "@world-engines/protocol-ts/v1/neutral_scenario_source";
+import { canonicalScenarioSourceSectionBytes, createNeutralScenarioSource } from "@world-engines/scenario-author-source";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { assertNeutralUploadPlanLimits, decodeScenarioPartWesp, encodeNeutralUploadLogicalObject } from "@world-engines/project-format";
+import { assertSafeExistingProjectPath } from "../safe-project-path.js";
+import { writeFrozenReviewTargetBinding } from "../frozen-review-local-pipeline.js";
+function digest(bytes) { return createHash("sha256").update(bytes).digest("hex"); }
+function createSha256() { const hash = createHash("sha256"); return { update(bytes) { hash.update(bytes); return this; }, digestHex() { return hash.digest("hex"); } }; }
+function jsonDigest(value) { return digest(new TextEncoder().encode(JSON.stringify(value))); }
+function asObject(value, message) { if (typeof value !== "object" || value === null || Array.isArray(value))
+    throw new AuthoringBridgeError("E_SCHEMA_INVALID", message); return value; }
+function asString(value, message) { if (typeof value !== "string" || value === "")
+    throw new AuthoringBridgeError("E_SCHEMA_INVALID", message); return value; }
+function asNumber(value, message) { if (typeof value !== "number" || !Number.isSafeInteger(value))
+    throw new AuthoringBridgeError("E_SCHEMA_INVALID", message); return value; }
+function remoteError(status) { if (status === 401 || status === 403)
+    throw new AuthoringBridgeError("E_AUTH_REQUIRED", "远端 Upload 请求未获授权"); throw new AuthoringBridgeError("E_VALIDATION_FAILED", `远端 Upload 请求失败：HTTP ${status}`); }
+function assertTarget(target) {
+    buildUploadPlanTarget(target);
+    for (const hash of [target.scenario_head, target.view_digest])
+        if (hash !== undefined && !/^[a-f0-9]{64}$/.test(hash))
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "upload target digest 无效");
+}
+/** CLI/GUI 与 Edge UploadPlanBody 共用的唯一 client target builder。 */
+export function buildUploadPlanTarget(target) {
+    const scenarioMode = target.creates_scenario ? "create" : "existing";
+    const viewMode = target.creates_view ? "create" : "existing";
+    if (!target.client_target_key || (scenarioMode === "create" ? (target.scenario_id !== undefined || !target.scenario_title?.trim()) : !target.scenario_id)
+        || (viewMode === "create" ? (target.view_id !== undefined || !target.view_title?.trim()) : !target.view_id)
+        || (target.copy_on_bind && (viewMode !== "create" || !target.view_title?.trim())))
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "upload target 与 Edge mode/title contract 不匹配");
+    return { clientTargetKey: target.client_target_key, scenarioMode, ...(target.scenario_id === undefined ? {} : { scenarioId: target.scenario_id }), ...(target.scenario_title === undefined ? {} : { scenarioTitle: target.scenario_title }), viewMode, ...(target.view_id === undefined ? {} : { viewId: target.view_id }), ...(target.view_title === undefined ? {} : { viewTitle: target.view_title }), createsScenario: target.creates_scenario, createsView: target.creates_view, copyOnBind: target.copy_on_bind, ...(target.scenario_head === undefined ? {} : { scenarioHead: target.scenario_head }), ...(target.view_digest === undefined ? {} : { viewDigest: target.view_digest }), ...(target.binding_revision === undefined ? {} : { bindingRevision: target.binding_revision }) };
+}
+async function files(root, relative = "") {
+    const directory = join(root, "view", ...relative.split("/").filter(Boolean));
+    const entries = await readdir(await assertSafeExistingProjectPath(root, directory), { withFileTypes: true });
+    const result = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (["node_modules", "dist", ".vite"].includes(entry.name))
+            continue;
+        const next = relative === "" ? entry.name : `${relative}/${entry.name}`;
+        const absolute = join(root, "view", ...next.split("/"));
+        const info = await lstat(absolute);
+        if (info.isSymbolicLink())
+            throw new AuthoringBridgeError("E_PATH_OUTSIDE_PROJECT", `拒绝 View 符号链接：${absolute}`);
+        if (info.isDirectory())
+            result.push(...await files(root, next));
+        else if (info.isFile())
+            result.push({ path: next, content_base64: Buffer.from(await readFile(await assertSafeExistingProjectPath(root, absolute))).toString("base64") });
+    }
+    return result;
+}
+/** 生成未压缩 SVP v1；flags=0 是 SVP codec 支持的合法形式，避免 CLI 依赖 WebAssembly brotli。 */
+/** Desktop private sidecar 与 CLI 共用的真实冻结快照；只返回当前项目 authority bytes。 */
+export async function captureUploadSnapshot(root) {
+    const manifest = asObject(JSON.parse(await readFile(join(root, "worldengine.project.json"), "utf8")), "manifest 无效");
+    const snapshot = asObject(manifest.snapshot, "manifest snapshot 无效");
+    const scenario = new Uint8Array(await readFile(await assertSafeExistingProjectPath(root, join(root, "scenario", "source.wes"))));
+    await decodeScenarioPartWesp(scenario);
+    const payload = new TextEncoder().encode(JSON.stringify({ files: await files(root) }));
+    const view = new Uint8Array(17 + payload.length);
+    view.set([0x53, 0x56, 0x50, 0x01, 0x00]);
+    const header = new DataView(view.buffer);
+    header.setBigUint64(5, BigInt(asNumber(manifest.updated_at_ms, "manifest updated_at_ms 无效")), true);
+    header.setUint32(13, payload.length, true);
+    view.set(payload, 17);
+    const objects = [
+        { part_kind: "scenario", sha256: digest(scenario), byte_length: scenario.length, media_type: "application/vnd.worldengine.wesp", bytes: scenario },
+        { part_kind: "view", sha256: digest(view), byte_length: view.length, media_type: "application/vnd.worldengine.svp", bytes: view },
+    ];
+    return { snapshot: { snapshot_id: asString(snapshot.snapshot_id, "snapshot_id 无效"), snapshot_digest: asString(snapshot.canonical_digest, "snapshot digest 无效"), updated_at_ms: asNumber(manifest.updated_at_ms, "manifest updated_at_ms 无效") }, objects };
+}
+async function* one(bytes) { yield bytes; }
+function json(bytes, fallback, field) {
+    if (bytes.byteLength === 0)
+        return fallback;
+    try {
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", `${field} 不是有效 JSON`);
+    }
+}
+function record(value, field) {
+    return asObject(value, `${field} 必须是 object`);
+}
+function canonicalJson(value) {
+    const encode = (input) => {
+        if (input === null)
+            return "null";
+        if (typeof input === "boolean" || typeof input === "string")
+            return JSON.stringify(input);
+        if (typeof input === "number") {
+            if (!Number.isFinite(input))
+                throw new AuthoringBridgeError("E_SCHEMA_INVALID", "canonical JSON number 无效");
+            return JSON.stringify(Object.is(input, -0) ? 0 : input);
+        }
+        if (Array.isArray(input))
+            return `[${input.map(encode).join(",")}]`;
+        if (typeof input === "object")
+            return `{${Object.entries(input).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([key, child]) => `${JSON.stringify(key)}:${encode(child)}`).join(",")}}`;
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "canonical JSON value 无效");
+    };
+    return new TextEncoder().encode(encode(value));
+}
+function jsonSection(section_key, payload) {
+    return { section_key, media_type: "application/json", canonical_encoding: "canonical-json-v1", payload: canonicalJson(payload) };
+}
+/** 与 Edge wesp::scenario_sections 共用 golden 语义的 Node 映射。 */
+export function mapScenarioPartToNeutralSections(source, view, localWesp) {
+    const wespSha = digest(localWesp);
+    const metadataOriginal = json(source.metadata, {}, "metadata");
+    const metadataRoot = record(metadataOriginal, "metadata");
+    const alreadyNeutral = ["metadata", "protagonist", "system_prompts", "source_metadata"].some((key) => key in metadataRoot);
+    const sourceMetadata = metadataRoot.source_metadata === undefined ? {} : { ...record(metadataRoot.source_metadata, "metadata.source_metadata") };
+    sourceMetadata.local_project_wesp_byte_length = localWesp.byteLength;
+    sourceMetadata.local_project_wesp_sha256 = wespSha;
+    const metadata = {
+        metadata: alreadyNeutral ? (metadataRoot.metadata ?? null) : Object.keys(metadataRoot).length === 0 ? null : metadataOriginal,
+        protagonist: metadataRoot.protagonist ?? null,
+        source_metadata: sourceMetadata,
+        system_prompts: metadataRoot.system_prompts ?? [],
+    };
+    const graphRoot = record(json(source.logical_graph, { entities: [], history: [], relations: [] }, "logical_graph"), "logical_graph");
+    if (!Array.isArray(graphRoot.entities) || !Array.isArray(graphRoot.relations) || !Array.isArray(graphRoot.history ?? []))
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "logical_graph 无效");
+    const entities = graphRoot.entities.map((value) => { const entity = { ...record(value, "logical_graph entity") }; const id = entity.entity_id ?? entity.id; if (typeof id !== "string" || id.length === 0)
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "logical_graph entity id 无效"); delete entity.id; entity.entity_id = id; return entity; });
+    const relationIds = new Set();
+    const relations = graphRoot.relations.map((value) => {
+        const relation = { ...record(value, "logical_graph relation") };
+        const from = relation.from_id ?? relation.src;
+        const to = relation.to_id ?? relation.dst;
+        const kind = relation.kind;
+        if (typeof from !== "string" || from.length === 0 || typeof to !== "string" || to.length === 0 || typeof kind !== "string" || kind.length === 0)
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "logical_graph relation identity 无效");
+        const relationId = relation.relation_id ?? relation.id ?? `relation.local.${digest(canonicalJson({ from_id: from, kind, to_id: to })).slice(0, 32)}`;
+        if (typeof relationId !== "string" || relationId.length === 0 || relationIds.has(relationId))
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "logical_graph relation_id 无效或重复");
+        relationIds.add(relationId);
+        delete relation.src;
+        delete relation.dst;
+        delete relation.id;
+        relation.from_id = from;
+        relation.to_id = to;
+        relation.relation_id = relationId;
+        return relation;
+    });
+    const triggerOriginal = json(source.trigger_semantics, { triggers: [] }, "trigger_semantics");
+    const triggerRoot = record(triggerOriginal, "trigger_semantics");
+    const triggerKeys = ["conditions", "edges", "effects", "events", "presentations"];
+    const trigger = triggerKeys.every((key) => Array.isArray(triggerRoot[key]))
+        ? {
+            ...Object.fromEntries(triggerKeys.map((key) => [key, triggerRoot[key]])),
+            ...(triggerRoot.value_graph === undefined ? {} : { value_graph: triggerRoot.value_graph }),
+        }
+        : Object.keys(triggerRoot).length === 1 && Array.isArray(triggerRoot.triggers) && triggerRoot.triggers.length === 0
+            ? { conditions: [], edges: [], effects: [], events: [], presentations: [] }
+            : (() => { throw new AuthoringBridgeError("E_SCHEMA_INVALID", "trigger_semantics 不受支持"); })();
+    const layoutOriginal = json(source.layout, { blueprint: {}, interaction: {} }, "layout");
+    const layoutRoot = record(layoutOriginal, "layout");
+    const interaction = layoutRoot.interaction === undefined ? undefined : record(layoutRoot.interaction, "layout.interaction");
+    const layout = {
+        view_interaction_mobile: layoutRoot.view_interaction_mobile ?? interaction?.mobile ?? null,
+        view_interaction_pc: layoutRoot.view_interaction_pc ?? interaction?.pc ?? (interaction !== undefined && Object.keys(interaction).length > 0 ? interaction : null),
+    };
+    const resourceOriginal = json(source.resource_refs, [], "resource_refs");
+    const resources = Array.isArray(resourceOriginal) ? resourceOriginal : record(resourceOriginal, "resource_refs").resources;
+    if (!Array.isArray(resources))
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "resource_refs 无效");
+    const retrievalOriginal = json(source.prompt_retrieval, {}, "prompt_retrieval");
+    const retrievalRoot = record(retrievalOriginal, "prompt_retrieval");
+    const remoteRetrieval = typeof retrievalRoot.retrieval === "object" && retrievalRoot.retrieval !== null && !Array.isArray(retrievalRoot.retrieval) ? retrievalRoot.retrieval : undefined;
+    const runtime = typeof retrievalRoot.runtime_definitions === "object" && retrievalRoot.runtime_definitions !== null && !Array.isArray(retrievalRoot.runtime_definitions) ? retrievalRoot.runtime_definitions : undefined;
+    const lookup = (key) => remoteRetrieval?.[key] ?? retrievalRoot[key];
+    const retrievalConfig = lookup("retrieval_config") ?? (Object.keys(retrievalRoot).length === 0 || ["retrieval", "music_candidates", "runtime_definitions"].some((key) => key in retrievalRoot) ? null : retrievalOriginal);
+    const promptRetrieval = { music_candidates: retrievalRoot.music_candidates ?? [], retrieval: { attr_mutex_keys: lookup("attr_mutex_keys") ?? [], play_config: lookup("play_config") ?? null, retrieval_config: retrievalConfig, style_guide_selections: lookup("style_guide_selections") ?? [], world_time: lookup("world_time") ?? null }, runtime_definitions: { achievement_defs: runtime?.achievement_defs ?? [], cg_defs: runtime?.cg_defs ?? [], transaction_defs: runtime?.transaction_defs ?? [], trigger_variables_schema: runtime?.trigger_variables_schema ?? [], triggers: runtime?.triggers ?? [] } };
+    const protobuf = localWesp.subarray(45);
+    return [
+        jsonSection("metadata", metadata),
+        jsonSection("logical_graph", { entities, relations }),
+        jsonSection("trigger_semantics", trigger),
+        jsonSection("layout", layout),
+        { section_key: "view_project", media_type: "application/vnd.worldengine.svp", canonical_encoding: "svp-v1", payload: view },
+        jsonSection("resource_refs", resources),
+        jsonSection("prompt_retrieval", promptRetrieval),
+        jsonSection("local_graph_history", graphRoot.history ?? []),
+        jsonSection("local_project_layout", layoutOriginal),
+        jsonSection("local_project_trigger_semantics", triggerOriginal),
+        jsonSection("local_project_provenance", { schema_version: 1, wesp_byte_length: localWesp.byteLength, wesp_payload_byte_length: protobuf.byteLength, wesp_payload_sha256: digest(protobuf), wesp_sha256: wespSha }),
+        { section_key: "local_project_wesp", media_type: "application/vnd.worldengine.scenario-part+wesp", canonical_encoding: "wesp-v1", payload: localWesp },
+        { section_key: "spatial_world", media_type: "application/x-protobuf", canonical_encoding: "chat.v1.SpatialWorldSourceV1", payload: source.spatial_world === undefined ? new Uint8Array() : SpatialWorldSourceV1.encode(source.spatial_world).finish() },
+    ];
+}
+/** 生成 v2 Neutral logical objects；WESP 只在 local_project_wesp section payload 中逐字节保存一次。 */
+async function captureNeutralUploadInputs(root) {
+    const captured = await captureUploadSnapshot(root);
+    const scenarioObject = captured.objects.find((object) => object.part_kind === "scenario");
+    const viewObject = captured.objects.find((object) => object.part_kind === "view");
+    const manifest = asObject(JSON.parse(await readFile(join(root, "worldengine.project.json"), "utf8")), "manifest 无效");
+    const scenarioManifest = asObject(manifest.scenario, "manifest scenario 无效");
+    const scenarioId = asString(scenarioManifest.local_scenario_id, "local scenario id 无效");
+    const protobuf = await decodeScenarioPartWesp(scenarioObject.bytes);
+    const sections = mapScenarioPartToNeutralSections(ScenarioPartSourceV1.decode(protobuf), viewObject.bytes, scenarioObject.bytes);
+    const neutral = await createNeutralScenarioSource(scenarioId, sections);
+    const inputs = [{
+            object_id: "manifest",
+            object_kind: "manifest",
+            bytes: one(ScenarioSourceManifestCodec.encode(neutral.manifest).finish()),
+        }];
+    for (const section of neutral.sections) {
+        if (section.section_key === "local_project_wesp" || section.section_key === "view_project")
+            continue;
+        inputs.push({
+            object_id: `section:${section.section_key}`,
+            object_kind: "section",
+            section_key: section.section_key,
+            media_type: section.media_type,
+            canonical_encoding: section.canonical_encoding,
+            bytes: one(canonicalScenarioSourceSectionBytes(section)),
+        });
+    }
+    const viewSection = neutral.sections.find((section) => section.section_key === "view_project");
+    inputs.push({ object_id: "view", object_kind: "view", section_key: viewSection.section_key, media_type: viewSection.media_type, canonical_encoding: viewSection.canonical_encoding, bytes: one(canonicalScenarioSourceSectionBytes(viewSection)) });
+    const localWespSection = neutral.sections.find((section) => section.section_key === "local_project_wesp");
+    inputs.push({
+        object_id: "local_project_wesp",
+        object_kind: "local_project_wesp",
+        section_key: "local_project_wesp",
+        media_type: "application/vnd.worldengine.scenario-part+wesp",
+        canonical_encoding: "wesp-v1",
+        bytes: one(canonicalScenarioSourceSectionBytes(localWespSection)),
+    });
+    return { snapshot: captured.snapshot, legacy_objects: captured.objects.map(({ bytes: _bytes, ...object }) => object), inputs };
+}
+function parsePlan(value, request, snapshot, objects) {
+    const body = asObject(value, "远端 upload plan 无效");
+    const plan_id = asString(body.planId, "远端 upload plan 缺少 planId");
+    const plan_digest = asString(body.planDigest, "远端 upload plan 缺少 planDigest");
+    const expires_at_ms = asNumber(body.expiresAtMs, "远端 upload plan 缺少 expiresAtMs");
+    if (!/^[a-f0-9]{64}$/.test(plan_digest) || expires_at_ms <= Date.now())
+        throw new AuthoringBridgeError("E_CONFIRMATION_REQUIRED", "远端 upload plan 已过期或 digest 无效");
+    return { operation_id: request.operation_id, plan_id, plan_digest, expires_at_ms, targets: request.targets, objects, ...snapshot };
+}
+function parseOperation(value) {
+    const body = asObject(value, "远端 upload operation 无效");
+    const targets = body.targets;
+    if (!Array.isArray(targets))
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "远端 upload operation 缺少 targets");
+    return { operation_id: asString(body.operationId, "远端 upload operation 缺少 operationId"), plan_id: asString(body.planId, "远端 upload operation 缺少 planId"), plan_digest: asString(body.planDigest, "远端 upload operation 缺少 planDigest"), state: asString(body.state, "远端 upload operation 缺少 state"), targets: targets.map((target) => asObject(target, "远端 upload target 无效")) };
+}
+function sha256(value, message) {
+    if (typeof value !== "string" || !/^[a-f0-9]{64}$/u.test(value))
+        throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", message);
+    return value;
+}
+function terminalReviewTarget(operation, requestedKey) {
+    if (operation.state !== "succeeded")
+        throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "upload 尚未整体成功，不能建立 review target binding");
+    let selected;
+    if (requestedKey === undefined) {
+        if (operation.targets.length !== 1)
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "多 target upload 必须显式选择 client_target_key");
+        selected = operation.targets[0];
+    }
+    else {
+        const matches = operation.targets.filter((target) => target.clientTargetKey === requestedKey);
+        if (matches.length !== 1)
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "review target client_target_key 不属于该 upload operation");
+        selected = matches[0];
+    }
+    if (selected.state !== "succeeded")
+        throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "所选 upload target 尚未成功");
+    return Object.freeze({
+        schema_version: 1,
+        project_id: "",
+        scenario_id: asString(selected.scenarioId, "terminal upload target 缺少 scenarioId"),
+        source_digest: sha256(selected.scenarioSourceDigestReadback, "terminal upload target 缺少 canonical source digest readback"),
+        source_head_digest: sha256(selected.scenarioHeadReadback, "terminal upload target 缺少 scenario head readback"),
+    });
+}
+/** GUI/CLI 共用的远端 fanout coordinator；所有恢复始终使用同一 operation_id。 */
+export class RemoteUploadCoordinator {
+    #root;
+    #projectId;
+    #transport;
+    constructor(root, projectId, transport) { this.#root = root; this.#projectId = projectId; this.#transport = transport; }
+    static async open(root, projectId, transport) { if (!projectId)
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "upload 缺少 project_id"); return new RemoteUploadCoordinator(await assertSafeExistingProjectPath(root, root), projectId, transport); }
+    #transportOrThrow() { if (!this.#transport)
+        throw new AuthoringBridgeError("E_AUTH_REQUIRED", "CLI 没有 ProjectAuthBroker 受控 transport"); return this.#transport; }
+    async plan(request) {
+        if (!request.operation_id || !Number.isSafeInteger(request.expires_at_ms) || request.expires_at_ms <= Date.now() || request.targets.length === 0 || new Set(request.targets.map((target) => target.client_target_key)).size !== request.targets.length)
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "upload plan 请求无效");
+        request.targets.forEach(assertTarget);
+        const captured = await captureNeutralUploadInputs(this.#root);
+        const transport = this.#transportOrThrow();
+        const logicalObjects = [];
+        for (const input of captured.inputs)
+            logicalObjects.push(await encodeNeutralUploadLogicalObject(input, async ({ ref, bytes }) => {
+                const path = `/v1/creator/project-transfer/staging/${ref.encoded_sha256}`;
+                const put = await transport.request({ project_id: this.#projectId, operation_id: request.operation_id, method: "PUT", path, body: bytes, body_size: ref.encoded_byte_length, body_digest: ref.encoded_sha256, raw_body_size: ref.raw_byte_length, raw_body_digest: ref.raw_sha256, body_codec: ref.codec });
+                if (put.status < 200 || put.status >= 300)
+                    remoteError(put.status);
+                const head = await transport.request({ project_id: this.#projectId, operation_id: request.operation_id, method: "HEAD", path });
+                if (head.status < 200 || head.status >= 300 || head.readback === undefined || head.readback.sha256 !== ref.encoded_sha256 || head.readback.byte_length !== ref.encoded_byte_length)
+                    throw new AuthoringBridgeError("E_VALIDATION_FAILED", "Upload v2 chunk HEAD readback 不匹配");
+            }, { codec: "gzip-member-v1", create_sha256: createSha256 }));
+        assertNeutralUploadPlanLimits(logicalObjects);
+        const body = { schemaVersion: 2, planId: `upload-${request.operation_id}`, snapshotId: captured.snapshot.snapshot_id, snapshotDigest: captured.snapshot.snapshot_digest, expiresAtMs: request.expires_at_ms, parts: ["scenario", "view"], targets: request.targets.map(buildUploadPlanTarget), objects: logicalObjects.map((object) => ({ objectId: object.object_id, objectKind: object.object_kind, ...(object.section_key === undefined ? {} : { sectionKey: object.section_key }), ...(object.media_type === undefined ? {} : { mediaType: object.media_type }), ...(object.canonical_encoding === undefined ? {} : { canonicalEncoding: object.canonical_encoding }), rawByteLength: object.raw_byte_length, rawSha256: object.raw_sha256, chunks: object.chunks.map((chunk) => ({ index: chunk.index, rawOffset: chunk.raw_offset, rawByteLength: chunk.raw_byte_length, rawSha256: chunk.raw_sha256, codec: chunk.codec, encodedByteLength: chunk.encoded_byte_length, encodedSha256: chunk.encoded_sha256 })) })) };
+        const encodedBody = new TextEncoder().encode(JSON.stringify(body));
+        if (encodedBody.byteLength > 256 * 1024)
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "Upload v2 descriptor 超过 256 KiB");
+        const response = await transport.request({ project_id: this.#projectId, operation_id: request.operation_id, method: "POST", path: "/v1/creator/project-transfer/upload-plans", body, body_digest: digest(encodedBody), body_size: encodedBody.byteLength });
+        if (response.status < 200 || response.status >= 300)
+            remoteError(response.status);
+        return { ...parsePlan(response.body, request, captured.snapshot, captured.legacy_objects), logical_objects: logicalObjects };
+    }
+    async confirm(plan, planDigest) {
+        if (planDigest !== plan.plan_digest || plan.expires_at_ms <= Date.now())
+            throw new AuthoringBridgeError("E_CONFIRMATION_REQUIRED", "--confirm-plan 与当前 upload plan 不匹配或已过期");
+        const body = { operationId: plan.operation_id, planId: plan.plan_id, planDigest: plan.plan_digest, confirmation: "force_overwrite", targets: plan.targets.map((target) => ({ clientTargetKey: target.client_target_key, scenarioId: target.scenario_id, viewId: target.view_id })) };
+        const response = await this.#transportOrThrow().request({ project_id: this.#projectId, operation_id: plan.operation_id, method: "POST", path: "/v1/creator/project-transfer/upload/confirm", body, body_digest: jsonDigest(body) });
+        if (response.status < 200 || response.status >= 300)
+            remoteError(response.status);
+        const operation = parseOperation(response.body);
+        if (operation.operation_id !== plan.operation_id || operation.plan_id !== plan.plan_id || operation.plan_digest !== plan.plan_digest)
+            throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "confirm 返回的 operation 未绑定冻结 plan");
+        return operation;
+    }
+    async operation(operationId, reconcile = false) { if (!operationId)
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "upload operation_id 不能为空"); const response = await this.#transportOrThrow().request({ project_id: this.#projectId, operation_id: operationId, method: reconcile ? "POST" : "GET", path: `/v1/creator/project-transfer/operations/${encodeURIComponent(operationId)}${reconcile ? "/reconcile" : ""}` }); if (response.status < 200 || response.status >= 300)
+        remoteError(response.status); const operation = parseOperation(response.body); if (operation.operation_id !== operationId)
+        throw new AuthoringBridgeError("E_OPERATION_ID_CONFLICT", "operation readback 返回了不同 operation_id"); return operation; }
+    /** 仅消费 terminal authoritative upload witness；不从本地 WESP 或 plan 推导 Neutral identity。 */
+    async bindFrozenReviewTarget(operationId, options = {}) {
+        const operation = await this.operation(operationId);
+        const selected = terminalReviewTarget(operation, options.client_target_key);
+        return await writeFrozenReviewTargetBinding(this.#root, Object.freeze({ ...selected, project_id: this.#projectId }));
+    }
+    /** retry 只能复用既有 operation identity，服务端负责从该 operation 的冻结计划恢复。 */
+    async retry(operationId) { if (!operationId)
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "upload operation_id 不能为空"); const response = await this.#transportOrThrow().request({ project_id: this.#projectId, operation_id: operationId, method: "POST", path: `/v1/creator/project-transfer/operations/${encodeURIComponent(operationId)}/retry` }); if (response.status < 200 || response.status >= 300)
+        remoteError(response.status); const operation = parseOperation(response.body); if (operation.operation_id !== operationId)
+        throw new AuthoringBridgeError("E_OPERATION_ID_CONFLICT", "retry 返回了不同 operation_id"); return operation; }
+    async undo(operationId) { if (!operationId)
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "upload operation_id 不能为空"); const response = await this.#transportOrThrow().request({ project_id: this.#projectId, operation_id: operationId, method: "POST", path: `/v1/creator/project-transfer/operations/${encodeURIComponent(operationId)}/undo` }); if (response.status < 200 || response.status >= 300)
+        remoteError(response.status); const operation = parseOperation(response.body); if (operation.operation_id !== operationId)
+        throw new AuthoringBridgeError("E_OPERATION_ID_CONFLICT", "undo 返回了不同 operation_id"); return operation; }
+}

package/dist/transfer-types.d.ts

@@ -0,0 +1,95 @@
+import type { AuthoringEffectIdentity } from "@world-engines/authoring-bridge";
+/** 本地盘点项只允许引用项目根目录内的相对路径。 */
+export interface ProjectTransferInventoryEntry {
+    readonly project_relative_path: string;
+    readonly sha256: string;
+    readonly bytes: number;
+}
+export interface ProjectTransferInventory {
+    readonly schema_version: 1;
+    readonly project_id: string;
+    readonly entries: readonly ProjectTransferInventoryEntry[];
+}
+/** 从当前 canonical 项目根重新计算的本地 authority 盘点。 */
+export interface ProjectTransferLocalInventory extends ProjectTransferInventory {
+    readonly project_revision: number;
+}
+export interface ProjectTransferRequest extends AuthoringEffectIdentity {
+    readonly inventory: ProjectTransferInventory;
+}
+export interface ProjectTransferPlan {
+    readonly schema_version: 1;
+    readonly operation_id: string;
+    readonly request_digest: string;
+    readonly plan_digest: string;
+    readonly inventory: ProjectTransferInventory;
+    /** 仅供本地恢复使用，始终位于项目根目录内。 */
+    readonly staging_path: string;
+    /** 执行前的不可变本地计划副本，始终位于项目根目录内。 */
+    readonly preimage_path: string;
+}
+export type ProjectTransferAvailability = {
+    readonly state: "signed_out";
+    readonly detail: string;
+} | {
+    readonly state: "unavailable";
+    readonly detail: string;
+} | {
+    readonly state: "ready";
+    readonly detail: string;
+};
+/**
+ * 同步侧边栏、CLI 与 MCP 共用的只读本地投影。
+ * auth_state 为 unavailable 时表示当前进程没有能够证明登录态的 adapter，不能伪装成 ready。
+ */
+export interface ProjectTransferSyncStatus {
+    readonly schema_version: 1;
+    readonly project_id: string;
+    readonly project_revision: number;
+    readonly inventory_digest: string;
+    readonly inventory_entry_count: number;
+    readonly pending_durable_ledger_count: number;
+    readonly auth_state: "unavailable" | "signed_out" | "authenticated";
+    readonly remote_adapter: ProjectTransferAvailability;
+}
+export interface ProjectTransferConfirmation {
+    readonly operation_id: string;
+    readonly plan_digest: string;
+}
+/**
+ * 远端传输只能由显式注入、负责真实身份与网络 I/O 的 adapter 执行。
+ * Project host 本身不包含 MCP 或网络 fallback。
+ */
+export interface ProjectTransferRemoteAdapter {
+    authState(): Promise<"signed_out" | "authenticated">;
+    /** execute 必须以 operation_id 幂等，并返回已由远端权威读取验证的 receipt。 */
+    execute(plan: ProjectTransferPlan): Promise<ProjectTransferRemoteReceipt>;
+    /**
+     * 这是 execute 前及崩溃重试时唯一允许的权威读回。
+     * only state:not_found 允许随后执行；网络、认证或未知状态必须 reject，不能降级为 not_found。
+     */
+    reconcile(operation_id: string): Promise<ProjectTransferRemoteReconcileResult>;
+}
+export interface ProjectTransferRemoteReceipt {
+    readonly operation_id: string;
+    readonly remote_transfer_id: string;
+    readonly readback_verified: boolean;
+}
+export type ProjectTransferRemoteReconcileResult = {
+    readonly state: "not_found";
+} | {
+    readonly state: "completed";
+    readonly receipt: ProjectTransferRemoteReceipt;
+};
+export type ProjectTransferReconcileResult = {
+    readonly state: "signed_out" | "unavailable";
+    readonly detail: string;
+} | {
+    readonly state: "not_found";
+} | {
+    readonly state: "completed";
+    readonly receipt: ProjectTransferRemoteReceipt;
+};
+export interface ProjectTransferCoordinatorOptions {
+    readonly remote_adapter?: ProjectTransferRemoteAdapter;
+}

package/dist/transfer-types.js

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

package/dist/transfer.d.ts

@@ -0,0 +1,18 @@
+import type { ProjectTransferAvailability, ProjectTransferConfirmation, ProjectTransferCoordinatorOptions, ProjectTransferLocalInventory, ProjectTransferPlan, ProjectTransferReconcileResult, ProjectTransferRemoteReceipt, ProjectTransferRequest, ProjectTransferSyncStatus } from "./transfer-types.js";
+/**
+ * 只枚举 manifest、Scenario Part 与 View Part；toolchain、认证态、缓存、日志、staging 和 operation ledger 不属于可传输 authority。
+ */
+export declare function buildLocalProjectTransferInventory(root: string, expectedProjectRevision?: number): Promise<ProjectTransferLocalInventory>;
+/** 本地 Project 与真实远端 adapter 之间的 fail-closed 边界；不包含 MCP 或网络 fallback。 */
+export declare class ProjectTransferCoordinator {
+    #private;
+    readonly root: string;
+    private constructor();
+    static open(root: string, options?: ProjectTransferCoordinatorOptions): Promise<ProjectTransferCoordinator>;
+    availability(): Promise<ProjectTransferAvailability>;
+    inventory(): Promise<ProjectTransferLocalInventory>;
+    status(): Promise<ProjectTransferSyncStatus>;
+    prepare(request: ProjectTransferRequest): Promise<ProjectTransferPlan>;
+    execute(plan: ProjectTransferPlan, confirmation: ProjectTransferConfirmation | undefined): Promise<ProjectTransferRemoteReceipt>;
+    reconcile(operationId: string): Promise<ProjectTransferReconcileResult>;
+}