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

package/dist/local-account-embedding.d.ts

@@ -0,0 +1,34 @@
+import { AuthoringModelConnectionError, type AuthoringEmbeddingPort } from "./authoring-model-connection.js";
+import { LOCAL_ACCOUNT_MODEL_PROXY_ORIGIN } from "./account-model-proxy.js";
+export interface LocalAccountEmbeddingPort extends AuthoringEmbeddingPort {
+    readonly origin: typeof LOCAL_ACCOUNT_MODEL_PROXY_ORIGIN | string;
+    readonly accountIdentity: string;
+    readonly descriptorSha256: string;
+    readonly descriptorSha256ByInputKind: Readonly<{
+        document: string;
+        query: string;
+    }>;
+    /** 任何可能使用本地向量 cache 的入口必须先调用；即使全命中也验证当前登录账户。 */
+    assertCurrentAccount(options?: Readonly<{
+        signal?: AbortSignal;
+    }>): Promise<void>;
+}
+export interface CreateLocalAccountEmbeddingPortOptions {
+    readonly projectRoot: string;
+    readonly projectId: string;
+    readonly fetch?: typeof globalThis.fetch;
+}
+export interface LocalAccountEmbeddingTerminalReceipt {
+    readonly operationId: string;
+    readonly status: "authorized_no_response" | "settled_no_response" | "failed_no_response" | "reconcile_required";
+    readonly ledgerStatus: "authorized" | "dispatched" | "provider_succeeded" | "settled" | "failed" | "ambiguous" | "reconcile_required";
+    readonly retryable: false;
+    readonly retryPolicy: "do_not_change_idempotency_key";
+}
+/** 已持久化但无向量响应时，调用方只能保留同一 key 进行 reconcile，绝不生成新计费操作。 */
+export declare class LocalAccountEmbeddingTerminalError extends AuthoringModelConnectionError {
+    readonly receipt: LocalAccountEmbeddingTerminalReceipt;
+    readonly name = "LocalAccountEmbeddingTerminalError";
+    constructor(receipt: LocalAccountEmbeddingTerminalReceipt);
+}
+export declare function createLocalAccountEmbeddingPort(options: CreateLocalAccountEmbeddingPortOptions): Promise<LocalAccountEmbeddingPort>;

package/dist/local-account-embedding.js

@@ -0,0 +1,294 @@
+import { createHash } from "node:crypto";
+import { AuthoringModelConnectionError, } from "./authoring-model-connection.js";
+import { LOCAL_ACCOUNT_MODEL_PROXY_HOST, LOCAL_ACCOUNT_MODEL_PROXY_ORIGIN, LOCAL_ACCOUNT_MODEL_PROXY_PORT, resolveLocalAccountProjectBinding, } from "./account-model-proxy.js";
+const SHA256_PATTERN = /^[a-f0-9]{64}$/u;
+const MAX_TEXTS_HARD_LIMIT = 128;
+const MAX_RESPONSE_BYTES = 16 * 1024 * 1024;
+const REQUEST_TIMEOUT_MS = 30_000;
+/** 已持久化但无向量响应时，调用方只能保留同一 key 进行 reconcile，绝不生成新计费操作。 */
+export class LocalAccountEmbeddingTerminalError extends AuthoringModelConnectionError {
+    receipt;
+    name = "LocalAccountEmbeddingTerminalError";
+    constructor(receipt) {
+        super("provider_rejected", false, 409);
+        this.receipt = receipt;
+    }
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
+}
+function connectionError(status) {
+    if (status === 401 || status === 403)
+        return new AuthoringModelConnectionError("embedding_credentials_missing", false, status);
+    return new AuthoringModelConnectionError("provider_rejected", status === 429 || (status !== undefined && status >= 500), status);
+}
+function terminalReceipt(value) {
+    const error = record(value.error);
+    const operationId = value.operation_id;
+    const status = value.status;
+    const ledgerStatus = value.ledger_status;
+    const terminalStatuses = new Set(["authorized_no_response", "settled_no_response", "failed_no_response", "reconcile_required"]);
+    const ledgerStatuses = new Set(["authorized", "dispatched", "provider_succeeded", "settled", "failed", "ambiguous", "reconcile_required"]);
+    if (error?.code !== "E_OPERATION_UNCERTAIN"
+        || typeof operationId !== "string" || !/^[A-Za-z0-9._:-]{1,256}$/u.test(operationId)
+        || typeof status !== "string" || !terminalStatuses.has(status)
+        || typeof ledgerStatus !== "string" || !ledgerStatuses.has(ledgerStatus)
+        || value.retryable !== false || value.retry_policy !== "do_not_change_idempotency_key")
+        return undefined;
+    return Object.freeze({
+        operationId,
+        status: status,
+        ledgerStatus: ledgerStatus,
+        retryable: false,
+        retryPolicy: "do_not_change_idempotency_key",
+    });
+}
+function canonicalProxyOrigin(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new AuthoringModelConnectionError("invalid_configuration", false);
+    }
+    if (url.protocol !== "http:" || url.hostname !== LOCAL_ACCOUNT_MODEL_PROXY_HOST || url.port === ""
+        || url.username !== "" || url.password !== "" || (url.pathname !== "" && url.pathname !== "/")
+        || url.search !== "" || url.hash !== "") {
+        throw new AuthoringModelConnectionError("invalid_configuration", false);
+    }
+    return url.origin;
+}
+async function responseJson(response) {
+    if (!response.ok) {
+        if (response.status === 409) {
+            const declared = Number(response.headers.get("content-length"));
+            if (!Number.isFinite(declared) || declared <= MAX_RESPONSE_BYTES) {
+                try {
+                    const body = await response.text();
+                    if (Buffer.byteLength(body, "utf8") <= MAX_RESPONSE_BYTES) {
+                        const parsed = record(JSON.parse(body));
+                        const receipt = parsed === undefined ? undefined : terminalReceipt(parsed);
+                        if (receipt !== undefined)
+                            throw new LocalAccountEmbeddingTerminalError(receipt);
+                    }
+                }
+                catch (error) {
+                    if (error instanceof LocalAccountEmbeddingTerminalError)
+                        throw error;
+                }
+            }
+        }
+        await response.body?.cancel().catch(() => undefined);
+        throw connectionError(response.status);
+    }
+    const declared = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES) {
+        await response.body?.cancel().catch(() => undefined);
+        throw new AuthoringModelConnectionError("provider_response_invalid", false, response.status);
+    }
+    const reader = response.body?.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        if (reader !== undefined) {
+            while (true) {
+                const item = await reader.read();
+                if (item.done)
+                    break;
+                total += item.value.byteLength;
+                if (total > MAX_RESPONSE_BYTES) {
+                    await reader.cancel().catch(() => undefined);
+                    throw new AuthoringModelConnectionError("provider_response_invalid", false, response.status);
+                }
+                chunks.push(item.value);
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof AuthoringModelConnectionError)
+            throw error;
+        throw new AuthoringModelConnectionError("transport_failed", true, response.status);
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        throw new AuthoringModelConnectionError("provider_response_invalid", false, response.status);
+    }
+    const parsed = record(value);
+    if (parsed === undefined)
+        throw new AuthoringModelConnectionError("provider_response_invalid", false, response.status);
+    return parsed;
+}
+async function fetchJson(request, url, init, externalSignal) {
+    const controller = new AbortController();
+    let timedOut = false;
+    const abortFromExternal = () => controller.abort(externalSignal?.reason);
+    if (externalSignal?.aborted)
+        abortFromExternal();
+    else
+        externalSignal?.addEventListener("abort", abortFromExternal, { once: true });
+    const timer = setTimeout(() => { timedOut = true; controller.abort(); }, REQUEST_TIMEOUT_MS);
+    try {
+        const response = await request(url, { ...init, signal: controller.signal });
+        return await responseJson(response);
+    }
+    catch (error) {
+        if (externalSignal?.aborted)
+            throw new AuthoringModelConnectionError("aborted", false);
+        if (timedOut)
+            throw new AuthoringModelConnectionError("timeout", true);
+        if (error instanceof AuthoringModelConnectionError)
+            throw error;
+        throw new AuthoringModelConnectionError("transport_failed", true);
+    }
+    finally {
+        clearTimeout(timer);
+        externalSignal?.removeEventListener("abort", abortFromExternal);
+    }
+}
+function projectHeaders(projectId, rootIdentity, expectedAccountIdentity) {
+    const headers = new Headers({
+        accept: "application/json",
+        "x-worldengine-project-id": projectId,
+        "x-worldengine-project-root-sha256": rootIdentity,
+    });
+    if (expectedAccountIdentity !== undefined)
+        headers.set("x-worldengine-account-identity", expectedAccountIdentity);
+    return headers;
+}
+function embeddingIdempotencyKey(projectId, accountIdentity, descriptorSha256, inputKind, texts) {
+    const hash = createHash("sha256")
+        .update("worldengine-local-account-embedding/v1\0")
+        .update(projectId)
+        .update("\0")
+        .update(accountIdentity)
+        .update("\0")
+        .update(descriptorSha256)
+        .update(`\0${inputKind}\0`);
+    for (const text of texts) {
+        const bytes = Buffer.from(text, "utf8");
+        hash.update(String(bytes.byteLength)).update(":").update(createHash("sha256").update(bytes).digest("hex")).update("\0");
+    }
+    return `embedding:${hash.digest("hex")}`;
+}
+export async function createLocalAccountEmbeddingPort(options) {
+    const binding = await resolveLocalAccountProjectBinding(options.projectRoot, options.projectId);
+    const origin = canonicalProxyOrigin(LOCAL_ACCOUNT_MODEL_PROXY_ORIGIN);
+    if (origin !== `http://${LOCAL_ACCOUNT_MODEL_PROXY_HOST}:${LOCAL_ACCOUNT_MODEL_PROXY_PORT}`) {
+        throw new AuthoringModelConnectionError("invalid_configuration", false);
+    }
+    const request = options.fetch ?? globalThis.fetch;
+    if (typeof request !== "function")
+        throw new AuthoringModelConnectionError("invalid_configuration", false);
+    const get = async (path, signal, expectedAccountIdentity) => {
+        const init = {
+            method: "GET",
+            redirect: "manual",
+            headers: projectHeaders(options.projectId, binding.rootIdentity, expectedAccountIdentity),
+        };
+        return fetchJson(request, `${origin}${path}`, init, signal);
+    };
+    const initialSession = await get("/v1/session");
+    const accountIdentity = initialSession.account_identity;
+    if (initialSession.project_id !== options.projectId || typeof accountIdentity !== "string" || !SHA256_PATTERN.test(accountIdentity)) {
+        throw new AuthoringModelConnectionError("provider_response_invalid", false);
+    }
+    const descriptor = await get("/v1/embedding/descriptor", undefined, accountIdentity);
+    const provider = descriptor.provider;
+    const model = descriptor.model;
+    const dimensions = descriptor.dimensions;
+    const maxInputs = descriptor.max_inputs;
+    const maxInputChars = descriptor.max_input_chars;
+    const descriptorSha256 = descriptor.descriptor_sha256;
+    const inputKinds = record(descriptor.input_kinds);
+    const documentKind = record(inputKinds?.document);
+    const queryKind = record(inputKinds?.query);
+    if (descriptor.project_id !== options.projectId || descriptor.account_identity !== accountIdentity
+        || typeof provider !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(provider)
+        || typeof model !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$/u.test(model)
+        || !Number.isSafeInteger(dimensions) || dimensions < 1 || dimensions > 65_536
+        || !Number.isSafeInteger(maxInputs) || maxInputs < 1 || maxInputs > MAX_TEXTS_HARD_LIMIT
+        || !Number.isSafeInteger(maxInputChars) || maxInputChars < 1 || maxInputChars > 1_000_000
+        || typeof descriptorSha256 !== "string" || !SHA256_PATTERN.test(descriptorSha256)
+        || documentKind?.descriptor_sha256 !== descriptorSha256
+        || typeof queryKind?.descriptor_sha256 !== "string" || !SHA256_PATTERN.test(queryKind.descriptor_sha256)) {
+        throw new AuthoringModelConnectionError("provider_response_invalid", false);
+    }
+    const descriptorSha256ByInputKind = Object.freeze({ document: descriptorSha256, query: queryKind.descriptor_sha256 });
+    const assertCurrentAccount = async (assertOptions) => {
+        const current = await get("/v1/session", assertOptions?.signal);
+        if (current.project_id !== options.projectId || current.account_identity !== accountIdentity) {
+            throw new AuthoringModelConnectionError("embedding_credentials_missing", false, 409);
+        }
+        const refreshed = await get("/v1/embedding/descriptor", assertOptions?.signal, accountIdentity);
+        if (refreshed.project_id !== options.projectId || refreshed.account_identity !== accountIdentity
+            || refreshed.provider !== provider || refreshed.model !== model || refreshed.dimensions !== dimensions
+            || refreshed.max_inputs !== maxInputs || refreshed.max_input_chars !== maxInputChars
+            || refreshed.descriptor_sha256 !== descriptorSha256
+            || record(record(refreshed.input_kinds)?.document)?.descriptor_sha256 !== descriptorSha256ByInputKind.document
+            || record(record(refreshed.input_kinds)?.query)?.descriptor_sha256 !== descriptorSha256ByInputKind.query) {
+            throw new AuthoringModelConnectionError("provider_model_mismatch", false, 409);
+        }
+    };
+    return Object.freeze({
+        origin,
+        providerId: `worldengine-account/${provider}/${accountIdentity}`,
+        modelId: model,
+        dimensions: dimensions,
+        accountIdentity,
+        descriptorSha256,
+        descriptorSha256ByInputKind,
+        assertCurrentAccount,
+        async embed(texts, embedOptions) {
+            if (!Array.isArray(texts) || texts.length === 0 || texts.length > MAX_TEXTS_HARD_LIMIT
+                || texts.some((text) => typeof text !== "string" || text.length === 0 || [...text].length > maxInputChars)) {
+                throw new AuthoringModelConnectionError("invalid_request", false);
+            }
+            await assertCurrentAccount(embedOptions);
+            const inputKind = embedOptions?.inputKind ?? "document";
+            const complete = [];
+            for (let offset = 0; offset < texts.length; offset += maxInputs) {
+                const batch = texts.slice(offset, offset + maxInputs);
+                const body = JSON.stringify({ model, input: batch, dimensions, encoding_format: "float", input_kind: inputKind });
+                const postHeaders = projectHeaders(options.projectId, binding.rootIdentity, accountIdentity);
+                postHeaders.set("content-type", "application/json");
+                postHeaders.set("idempotency-key", embeddingIdempotencyKey(options.projectId, accountIdentity, descriptorSha256ByInputKind[inputKind], inputKind, batch));
+                const result = await fetchJson(request, `${origin}/v1/embeddings`, {
+                    method: "POST", redirect: "manual", headers: postHeaders, body,
+                }, embedOptions?.signal);
+                const usage = record(result.usage);
+                if (result.model !== model || result.provider !== provider || result.dimensions !== dimensions || result.input_kind !== inputKind
+                    || typeof result.operation_id !== "string" || result.operation_id.length === 0 || result.operation_id.length > 256
+                    || !Number.isSafeInteger(usage?.prompt_tokens) || usage?.prompt_tokens < 0
+                    || !Number.isSafeInteger(usage?.total_tokens) || usage?.total_tokens < usage?.prompt_tokens
+                    || !Array.isArray(result.data) || result.data.length !== batch.length) {
+                    throw new AuthoringModelConnectionError("provider_response_invalid", false);
+                }
+                const ordered = new Array(batch.length);
+                for (const itemValue of result.data) {
+                    const item = record(itemValue);
+                    const index = item?.index;
+                    const vector = item?.embedding;
+                    if (!Number.isSafeInteger(index) || index < 0 || index >= batch.length
+                        || ordered[index] !== undefined || !Array.isArray(vector) || vector.length !== dimensions
+                        || vector.some((entry) => typeof entry !== "number" || !Number.isFinite(entry))) {
+                        throw new AuthoringModelConnectionError("provider_response_invalid", false);
+                    }
+                    ordered[index] = Object.freeze([...vector]);
+                }
+                if (ordered.some((vector) => vector === undefined))
+                    throw new AuthoringModelConnectionError("provider_response_invalid", false);
+                complete.push(...ordered);
+            }
+            return Object.freeze(complete);
+        },
+    });
+}

package/dist/local-gallery.d.ts

@@ -0,0 +1,35 @@
+import { LocalProjectHost } from "./project-host.js";
+export declare const LOCAL_GALLERY_MAX_IMPORT_BYTES: number;
+export declare const LOCAL_GALLERY_MAX_FILES = 2048;
+export type LocalGalleryArea = "scenario" | "view";
+export type LocalGalleryOwnerKind = "entity" | "relation";
+export interface LocalGalleryImage {
+    readonly path: string;
+    readonly asset_path: string;
+    readonly mime: "image/png" | "image/jpeg" | "image/webp" | "image/gif" | "image/avif";
+    readonly size: number;
+    readonly sha256: string;
+    readonly owner_kind?: LocalGalleryOwnerKind;
+    readonly owner_id?: string;
+}
+export interface LocalGalleryImportRequest {
+    readonly operation_id: string;
+    readonly expected_project_revision: number;
+    readonly area: LocalGalleryArea;
+    readonly owner_kind?: LocalGalleryOwnerKind;
+    readonly owner_id?: string;
+    readonly filename: string;
+    readonly content_base64: string;
+}
+export type LocalGalleryImportResult = LocalGalleryImage & Readonly<{
+    operation_id: string;
+    previous_project_revision: number;
+    next_project_revision: number;
+    project_snapshot_digest: string;
+    readback_verified: boolean;
+}>;
+export declare function listLocalGalleryImages(root: string, area: LocalGalleryArea, ownerKind?: LocalGalleryOwnerKind, ownerId?: string): Promise<readonly LocalGalleryImage[]>;
+export declare function readLocalGalleryImage(root: string, path: string): Promise<LocalGalleryImage & {
+    bytes: Uint8Array;
+}>;
+export declare function importLocalGalleryImage(host: LocalProjectHost, request: LocalGalleryImportRequest): Promise<LocalGalleryImportResult>;

package/dist/local-gallery.js

@@ -0,0 +1,227 @@
+import { open, readFile, readdir, rename, stat, writeFile } from "node:fs/promises";
+import { extname, join } from "node:path";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { decodeGalleryScenarioEntityDirectory, galleryScenarioAssetPath, galleryViewAssetPath, sha256Hex, validateLocalAuthorProjectManifest, } from "@world-engines/project-format";
+import { LOCAL_GUI_MAX_IMAGE_ASSET_BYTES, localGuiImageBytesMatchMime, localGuiImageMimeForPath, } from "./local-gui-image-assets.js";
+import { acquireProjectWriterLease } from "./project-writer-lease.js";
+import { assertSafeExistingProjectPath, assertSafeProjectParent, ensureSafeProjectDirectory, safeProjectPath } from "./safe-project-path.js";
+export const LOCAL_GALLERY_MAX_IMPORT_BYTES = 2 * 1024 * 1024;
+export const LOCAL_GALLERY_MAX_FILES = 2_048;
+function fail(code, message) {
+    throw new AuthoringBridgeError(code, message);
+}
+async function manifest(root) {
+    const path = await assertSafeExistingProjectPath(root, join(root, "worldengine.project.json"));
+    return validateLocalAuthorProjectManifest(JSON.parse(await readFile(path, "utf8")));
+}
+async function assertV2(root) {
+    if ((await manifest(root)).schema_version !== 2)
+        fail("E_PROJECT_MIGRATION_REQUIRED", "Gallery 需要 project manifest schema v2");
+}
+function decodeBase64(value) {
+    if (typeof value !== "string" || value.length === 0 || value.length > Math.ceil(LOCAL_GALLERY_MAX_IMPORT_BYTES / 3) * 4 + 4 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+        fail("E_SCHEMA_INVALID", "content_base64 无效或过大");
+    }
+    const bytes = new Uint8Array(Buffer.from(value, "base64"));
+    if (bytes.byteLength === 0 || bytes.byteLength > LOCAL_GALLERY_MAX_IMPORT_BYTES || Buffer.from(bytes).toString("base64") !== value) {
+        fail("E_VALIDATION_FAILED", "图片内容无效或过大");
+    }
+    return bytes;
+}
+function canonicalExtension(filename) {
+    if (typeof filename !== "string" || filename.includes("/") || filename.includes("\\"))
+        fail("E_SCHEMA_INVALID", "filename 无效");
+    const extension = extname(filename).toLowerCase();
+    if (localGuiImageMimeForPath(`image${extension}`) === undefined)
+        fail("E_VALIDATION_FAILED", "图片扩展名不受支持");
+    return extension === ".jpeg" ? "jpg" : extension.slice(1);
+}
+function scenarioKind(kind) {
+    return kind === "entity" ? "node" : "edge";
+}
+async function assertOwner(host, ownerKind, ownerId) {
+    const graph = await host.readGraphProjectionReadback();
+    const exists = ownerKind === "entity"
+        ? graph.authoring.entities.some((row) => row.entity_id === ownerId || row.id === ownerId)
+        : graph.authoring.relations.some((row) => row.relation_id === ownerId);
+    if (!exists)
+        fail("E_REFERENCE_MISSING", "Gallery owner 不存在");
+}
+async function imageReadback(root, path, owner) {
+    const absolute = await assertSafeExistingProjectPath(root, join(root, ...path.split("/")));
+    const info = await stat(absolute);
+    const mime = localGuiImageMimeForPath(path);
+    if (!info.isFile() || mime === undefined || info.size <= 0 || info.size > LOCAL_GUI_MAX_IMAGE_ASSET_BYTES)
+        fail("E_VALIDATION_FAILED", "Gallery 图片无效");
+    const bytes = new Uint8Array(await readFile(absolute));
+    if (bytes.byteLength > LOCAL_GUI_MAX_IMAGE_ASSET_BYTES || !localGuiImageBytesMatchMime(bytes, mime))
+        fail("E_VALIDATION_FAILED", "Gallery 图片扩展名与内容不一致");
+    const digest = await sha256Hex(bytes);
+    return { path, asset_path: path, mime, size: bytes.byteLength, sha256: digest, bytes, ...(owner === undefined ? {} : { owner_kind: owner.kind, owner_id: owner.id }) };
+}
+export async function listLocalGalleryImages(root, area, ownerKind, ownerId) {
+    await assertV2(root);
+    if (area !== "scenario" && area !== "view")
+        fail("E_SCHEMA_INVALID", "Gallery area 无效");
+    if ((area === "scenario") !== (ownerKind !== undefined && ownerId !== undefined))
+        fail("E_SCHEMA_INVALID", "Scenario Gallery 必须提供 owner");
+    const base = area === "view"
+        ? "gallery/view"
+        : `gallery/scenario/${galleryScenarioAssetPath(scenarioKind(ownerKind), ownerId, "placeholder.png").split("/")[2]}`;
+    let directory;
+    try {
+        directory = await assertSafeExistingProjectPath(root, join(root, ...base.split("/")));
+    }
+    catch (error) {
+        if (area === "scenario" && error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const result = [];
+    for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (result.length >= LOCAL_GALLERY_MAX_FILES)
+            fail("E_VALIDATION_FAILED", "Gallery 图片数量超过上限");
+        if (!entry.isFile() || entry.isSymbolicLink())
+            continue;
+        const path = `${base}/${entry.name}`;
+        try {
+            const { bytes: _bytes, ...image } = await imageReadback(root, path, ownerKind === undefined ? undefined : { kind: ownerKind, id: ownerId });
+            void _bytes;
+            if (`${image.sha256}.${canonicalExtension(entry.name)}` !== entry.name)
+                continue;
+            result.push(image);
+        }
+        catch (error) {
+            if (error instanceof AuthoringBridgeError && error.code === "E_VALIDATION_FAILED")
+                continue;
+            throw error;
+        }
+    }
+    return result;
+}
+export async function readLocalGalleryImage(root, path) {
+    await assertV2(root);
+    const parts = path.split("/");
+    if (parts[0] !== "gallery" || !["scenario", "view"].includes(parts[1] ?? ""))
+        fail("E_PATH_OUTSIDE_PROJECT", "Gallery path 无效");
+    if (parts[1] === "view" && parts.length === 3) {
+        const image = await imageReadback(root, path);
+        if (galleryViewAssetPath(image.sha256, canonicalExtension(parts[2])) !== path)
+            fail("E_PATH_OUTSIDE_PROJECT", "Gallery path 非 canonical");
+        return image;
+    }
+    if (parts[1] === "scenario" && parts.length === 4) {
+        const owner = decodeGalleryScenarioEntityDirectory(parts[2]);
+        const image = await imageReadback(root, path, { kind: owner.kind === "node" ? "entity" : "relation", id: owner.id });
+        if (galleryScenarioAssetPath(owner.kind, owner.id, `${image.sha256}.${canonicalExtension(parts[3])}`) !== path)
+            fail("E_PATH_OUTSIDE_PROJECT", "Gallery path 非 canonical");
+        return image;
+    }
+    fail("E_PATH_OUTSIDE_PROJECT", "Gallery path 无效");
+}
+async function atomicLedger(root, path, value) {
+    const staging = await ensureSafeProjectDirectory(root, ".worldengine/staging");
+    const bytes = new TextEncoder().encode(`${JSON.stringify(value)}\n`);
+    const temporary = join(staging, `gallery-ledger-${await sha256Hex(bytes)}.tmp`);
+    const handle = await open(temporary, "wx");
+    try {
+        await handle.writeFile(bytes);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await assertSafeProjectParent(root, path);
+    await rename(temporary, path);
+}
+export async function importLocalGalleryImage(host, request) {
+    await assertV2(host.root);
+    if (request.area !== "scenario" && request.area !== "view")
+        fail("E_SCHEMA_INVALID", "Gallery area 无效");
+    if (!Number.isSafeInteger(request.expected_project_revision) || request.expected_project_revision < 0 || typeof request.operation_id !== "string" || request.operation_id.length === 0)
+        fail("E_SCHEMA_INVALID", "Gallery effect identity 无效");
+    if ((request.area === "scenario") !== (request.owner_kind !== undefined && request.owner_id !== undefined))
+        fail("E_SCHEMA_INVALID", "Scenario Gallery 必须提供 owner");
+    if (request.owner_kind !== undefined && request.owner_kind !== "entity" && request.owner_kind !== "relation")
+        fail("E_SCHEMA_INVALID", "Gallery owner_kind 无效");
+    if (request.owner_id !== undefined && request.owner_id.length === 0)
+        fail("E_SCHEMA_INVALID", "Gallery owner_id 无效");
+    const bytes = decodeBase64(request.content_base64);
+    const extension = canonicalExtension(request.filename);
+    const mime = localGuiImageMimeForPath(`image.${extension}`);
+    if (!localGuiImageBytesMatchMime(bytes, mime))
+        fail("E_VALIDATION_FAILED", "图片扩展名与内容不一致");
+    const contentSha256 = await sha256Hex(bytes);
+    const targetPath = request.area === "view"
+        ? galleryViewAssetPath(contentSha256, extension)
+        : galleryScenarioAssetPath(scenarioKind(request.owner_kind), request.owner_id, `${contentSha256}.${extension}`);
+    const requestDigest = await sha256Hex(new TextEncoder().encode(JSON.stringify({ ...request, content_base64: contentSha256 })));
+    await ensureSafeProjectDirectory(host.root, ".worldengine/operations");
+    const ledgerKey = await sha256Hex(new TextEncoder().encode(request.operation_id));
+    const ledgerPath = await safeProjectPath(host.root, `.worldengine/operations/gallery-${ledgerKey}.json`);
+    let ledger;
+    try {
+        ledger = JSON.parse(await readFile(await assertSafeExistingProjectPath(host.root, ledgerPath), "utf8"));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    if (ledger !== undefined) {
+        if (ledger.request_digest !== requestDigest || ledger.target_path !== targetPath)
+            fail("E_OPERATION_ID_CONFLICT", "Gallery operation_id 已绑定其他请求");
+        if (ledger.state === "completed" && ledger.receipt !== undefined)
+            return ledger.receipt;
+    }
+    const lease = await acquireProjectWriterLease(host.root, { entrypoint: "gallery-import", operation_id: request.operation_id });
+    try {
+        const before = await host.inspect();
+        if (before.project_revision !== request.expected_project_revision)
+            fail("E_STALE_PROJECT_REVISION", "Gallery import project revision 已变化");
+        if (request.area === "scenario")
+            await assertOwner(host, request.owner_kind, request.owner_id);
+        const targetDirectory = targetPath.split("/").slice(0, -1).join("/");
+        await ensureSafeProjectDirectory(host.root, targetDirectory);
+        const target = await safeProjectPath(host.root, targetPath);
+        try {
+            const existing = new Uint8Array(await readFile(await assertSafeExistingProjectPath(host.root, target)));
+            if (await sha256Hex(existing) !== contentSha256)
+                fail("E_OPERATION_ID_CONFLICT", "Gallery target 内容冲突");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            const handle = await open(target, "wx");
+            try {
+                await handle.writeFile(bytes);
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            const readback = new Uint8Array(await readFile(await assertSafeExistingProjectPath(host.root, target)));
+            if (await sha256Hex(readback) !== contentSha256)
+                fail("E_OPERATION_UNCERTAIN", "Gallery import 回读不一致");
+        }
+        if (ledger === undefined) {
+            ledger = { schema_version: 1, request_digest: requestDigest, target_path: targetPath, state: "prepared" };
+            await writeFile(ledgerPath, `${JSON.stringify(ledger)}\n`, { flag: "wx" });
+        }
+    }
+    finally {
+        await lease.release();
+    }
+    const snapshot = await host.snapshot({ operation_id: `gallery_snapshot_${ledgerKey}`, expected_project_revision: request.expected_project_revision });
+    const image = await readLocalGalleryImage(host.root, targetPath);
+    const receipt = {
+        path: image.path, asset_path: image.asset_path, mime: image.mime, size: image.size, sha256: image.sha256,
+        ...(image.owner_kind === undefined ? {} : { owner_kind: image.owner_kind, owner_id: image.owner_id }),
+        operation_id: request.operation_id,
+        previous_project_revision: snapshot.previous_project_revision,
+        next_project_revision: snapshot.next_project_revision,
+        project_snapshot_digest: snapshot.project_snapshot_digest,
+        readback_verified: snapshot.readback_verified && image.sha256 === contentSha256,
+    };
+    await atomicLedger(host.root, ledgerPath, { ...ledger, state: "completed", receipt });
+    return receipt;
+}