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

package/LICENSE

@@ -0,0 +1,46 @@
+WorldEngine 官方作者工具许可证
+
+版权所有 (c) 2026 Nixdorfer。保留所有权利。
+
+本仓库的源代码、构建材料及附带资源（统称“本作品”）不是开源软件，
+不适用任何 OSI 认证的开源许可证。
+
+一、官方作者工具分发许可
+
+版权所有者可以通过其官方网站、npm registry、签名安装包或其他官方渠道，
+复制并分发由本作品构建的 WorldEngine 作者工具及其必要运行资源
+（统称“官方作者工具”）。仅版权所有者或其书面指定的发布者享有此分发权。
+
+二、作者用户许可
+
+从官方渠道取得官方作者工具的作者用户，可以：
+
+1. 安装和运行官方作者工具；
+2. 使用官方作者工具创作、编辑、预览、导入、导出和提交其有权处理的内容；
+3. 为上述使用目的制作合理必要的本地备份副本。
+
+三、未授予的权利
+
+除第二条明确允许的行为外，本许可证不授予作者用户或其他第三方以下权利：
+
+1. 修改、改编、反编译、反汇编或制作官方作者工具的派生作品；
+2. 复制、镜像、转发、再上传、出售、出租、再分发或再许可官方作者工具；
+3. 使用本作品的源代码、构建材料或任何部分开发、提供或训练其他产品或服务；
+4. 删除或规避版权、许可、签名、访问控制或其他权利管理信息。
+
+法律强制允许且合同不得排除的权利不受上述限制影响。
+
+四、源代码查看
+
+第三方可以在已获合法访问权限的范围内查看本作品，用于审查、安全研究或学习参考；
+查看不授予运行、复制、修改、分发、再许可或用于其他产品与服务的权利。
+
+五、无担保与责任限制
+
+本作品与官方作者工具均按“现状”提供，不附带任何明示或暗示的担保。
+在适用法律允许的最大范围内，版权所有者不对因访问或使用本作品或官方作者工具
+造成的任何损失承担责任。
+
+六、终止
+
+违反本许可证将立即终止相应的访问与使用权；终止不影响版权所有者已经产生的权利和救济。

package/dist/account-project-root.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 账户模型代理的 project-root identity 唯一 canonical 输入。
+ * 调用方必须先解析 realpath；Windows 路径按文件系统语义折叠大小写。
+ */
+export declare function canonicalAccountProjectRootIdentityBytes(canonicalRoot: string, platform: "win32" | "posix"): Uint8Array;

package/dist/account-project-root.js

@@ -0,0 +1,12 @@
+const ACCOUNT_PROJECT_ROOT_DOMAIN = "worldengine-account-project-root-v1\0";
+/**
+ * 账户模型代理的 project-root identity 唯一 canonical 输入。
+ * 调用方必须先解析 realpath；Windows 路径按文件系统语义折叠大小写。
+ */
+export function canonicalAccountProjectRootIdentityBytes(canonicalRoot, platform) {
+    if (typeof canonicalRoot !== "string" || canonicalRoot.length === 0) {
+        throw new TypeError("canonical project root 不能为空");
+    }
+    const normalized = platform === "win32" ? canonicalRoot.toLowerCase() : canonicalRoot;
+    return new TextEncoder().encode(`${ACCOUNT_PROJECT_ROOT_DOMAIN}${normalized}`);
+}

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+export type ProjectFormatErrorCode = "E_PROJECT_MANIFEST_INVALID" | "E_PROJECT_PATH_INVALID" | "E_SCENARIO_PROTOBUF_INVALID" | "E_SCENARIO_SCHEMA_VERSION_UNSUPPORTED" | "E_WESP_DIGEST_MISMATCH" | "E_WESP_MAGIC_INVALID" | "E_WESP_SIZE_MISMATCH" | "E_WESP_VERSION_UNSUPPORTED";
+export declare class ProjectFormatError extends Error {
+    readonly code: ProjectFormatErrorCode;
+    constructor(code: ProjectFormatErrorCode, message: string);
+}

package/dist/errors.js

@@ -0,0 +1,8 @@
+export class ProjectFormatError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "ProjectFormatError";
+        this.code = code;
+    }
+}

package/dist/file-tree.d.ts

@@ -0,0 +1,5 @@
+export interface CanonicalFileTreeEntry {
+    readonly path: string;
+    readonly bytes: Uint8Array;
+}
+export declare function computeCanonicalFileTreeDigest(entries: readonly CanonicalFileTreeEntry[], subtle?: SubtleCrypto): Promise<string>;

package/dist/file-tree.js

@@ -0,0 +1,55 @@
+import { ProjectFormatError } from "./errors.js";
+import { sha256Hex } from "./integrity.js";
+function compareBytes(left, right) {
+    const length = Math.min(left.length, right.length);
+    for (let index = 0; index < length; index += 1) {
+        const difference = (left[index] ?? 0) - (right[index] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return left.length - right.length;
+}
+function validateRelativeCanonicalPath(path) {
+    if (path.length === 0 ||
+        path.includes("\\") ||
+        path.startsWith("/") ||
+        /^[A-Za-z]:/.test(path) ||
+        path.split("/").some((segment) => segment === "" || segment === "." || segment === "..")) {
+        throw new ProjectFormatError("E_PROJECT_PATH_INVALID", `非法 canonical file-tree path：${path}`);
+    }
+    const normalized = path.normalize("NFC");
+    if (normalized !== path) {
+        throw new ProjectFormatError("E_PROJECT_PATH_INVALID", `file-tree path 必须使用 NFC：${path}`);
+    }
+    return path;
+}
+export async function computeCanonicalFileTreeDigest(entries, subtle) {
+    const encoder = new TextEncoder();
+    const normalized = entries.map((entry) => {
+        if (!(entry.bytes instanceof Uint8Array))
+            throw new TypeError("file-tree bytes 必须是 Uint8Array");
+        const path = validateRelativeCanonicalPath(entry.path);
+        return { path, pathBytes: encoder.encode(path), bytes: entry.bytes };
+    });
+    normalized.sort((left, right) => compareBytes(left.pathBytes, right.pathBytes));
+    for (let index = 1; index < normalized.length; index += 1) {
+        if (normalized[index - 1]?.path === normalized[index]?.path) {
+            throw new ProjectFormatError("E_PROJECT_MANIFEST_INVALID", `file-tree path 重复：${normalized[index]?.path ?? ""}`);
+        }
+    }
+    const totalSize = normalized.reduce((sum, entry) => sum + 4 + entry.pathBytes.byteLength + 8 + entry.bytes.byteLength, 0);
+    const canonical = new Uint8Array(totalSize);
+    const view = new DataView(canonical.buffer);
+    let offset = 0;
+    for (const entry of normalized) {
+        view.setUint32(offset, entry.pathBytes.byteLength);
+        offset += 4;
+        canonical.set(entry.pathBytes, offset);
+        offset += entry.pathBytes.byteLength;
+        view.setBigUint64(offset, BigInt(entry.bytes.byteLength));
+        offset += 8;
+        canonical.set(entry.bytes, offset);
+        offset += entry.bytes.byteLength;
+    }
+    return sha256Hex(canonical, subtle);
+}

package/dist/gallery-migration.d.ts

@@ -0,0 +1,28 @@
+import { type CanonicalFileTreeEntry } from "./file-tree.js";
+import { type GalleryScenarioEntityIdentity } from "./gallery.js";
+import { type LocalAuthorProjectManifestV1 } from "./manifest.js";
+export interface LegacyGalleryMigrationEntry extends CanonicalFileTreeEntry {
+    readonly scenario_entity?: GalleryScenarioEntityIdentity;
+}
+export interface LocalAuthorProjectGalleryMigrationMoveV1 {
+    readonly source_path: string;
+    readonly source_sha256: string;
+    readonly destination_path: string;
+}
+export interface LocalAuthorProjectGalleryMigrationPlanV1 {
+    readonly schema_version: 1;
+    readonly kind: "legacy-gallery-v1-to-v2";
+    readonly project_id: string;
+    readonly project_revision: number;
+    readonly source_manifest_canonical_digest: string;
+    readonly legacy_entry_count: number;
+    readonly legacy_tree_digest: string;
+    readonly gallery_content_tree_sha256: string;
+    readonly moves: readonly LocalAuthorProjectGalleryMigrationMoveV1[];
+}
+/**
+ * 只生成可恢复计划，不触碰文件系统。调用者应用前必须重算 manifest 与 legacy_tree preimage；
+ * scenario legacy 文件没有明确 node/edge 绑定时 fail closed，禁止猜测归属。
+ */
+export declare function planLocalAuthorProjectGalleryMigration(manifest: LocalAuthorProjectManifestV1, entries: readonly LegacyGalleryMigrationEntry[], subtle?: SubtleCrypto): Promise<LocalAuthorProjectGalleryMigrationPlanV1>;
+export declare function assertLocalAuthorProjectGalleryMigrationPreimage(manifest: LocalAuthorProjectManifestV1, entries: readonly LegacyGalleryMigrationEntry[], plan: LocalAuthorProjectGalleryMigrationPlanV1, subtle?: SubtleCrypto): Promise<void>;

package/dist/gallery-migration.js

@@ -0,0 +1,65 @@
+import { computeCanonicalFileTreeDigest } from "./file-tree.js";
+import { encodeGalleryLegacyAssetFileName, galleryScenarioAssetPath, galleryViewAssetPath } from "./gallery.js";
+import { sha256Hex } from "./integrity.js";
+import { computeCanonicalProjectDigest, validateLocalAuthorProjectManifest } from "./manifest.js";
+import { ProjectFormatError } from "./errors.js";
+const VIEW_IMAGE = /\.([a-z0-9]+)$/;
+const ALLOWED_VIEW_IMAGE_EXTENSIONS = new Set(["avif", "gif", "jpeg", "jpg", "png", "svg", "webp"]);
+function legacyRelativePath(path, root) {
+    return path.startsWith(`${root}/`) ? path.slice(root.length + 1) : undefined;
+}
+/**
+ * 只生成可恢复计划，不触碰文件系统。调用者应用前必须重算 manifest 与 legacy_tree preimage；
+ * scenario legacy 文件没有明确 node/edge 绑定时 fail closed，禁止猜测归属。
+ */
+export async function planLocalAuthorProjectGalleryMigration(manifest, entries, subtle) {
+    validateLocalAuthorProjectManifest(manifest);
+    if (manifest.schema_version !== 1)
+        throw new ProjectFormatError("E_PROJECT_MANIFEST_INVALID", "gallery legacy migration 只接受 manifest v1");
+    const moves = await Promise.all(entries.map(async (entry) => {
+        const scenarioRelative = legacyRelativePath(entry.path, "scenario/assets");
+        const viewRelative = legacyRelativePath(entry.path, "view/public");
+        let destinationPath;
+        if (scenarioRelative !== undefined) {
+            if (entry.scenario_entity === undefined)
+                throw new ProjectFormatError("E_PROJECT_MANIFEST_INVALID", `legacy scenario asset 缺少 node/edge 绑定：${entry.path}`);
+            destinationPath = galleryScenarioAssetPath(entry.scenario_entity.kind, entry.scenario_entity.id, encodeGalleryLegacyAssetFileName(scenarioRelative));
+        }
+        else if (viewRelative !== undefined) {
+            const match = VIEW_IMAGE.exec(viewRelative.toLowerCase());
+            if (match === null || !ALLOWED_VIEW_IMAGE_EXTENSIONS.has(match[1] ?? ""))
+                throw new ProjectFormatError("E_PROJECT_MANIFEST_INVALID", `legacy view/public 含非图片或无扩展资源：${entry.path}`);
+            destinationPath = galleryViewAssetPath(await sha256Hex(entry.bytes, subtle), match[1]);
+        }
+        else {
+            throw new ProjectFormatError("E_PROJECT_PATH_INVALID", `legacy gallery migration 路径不受支持：${entry.path}`);
+        }
+        return Object.freeze({ source_path: entry.path, source_sha256: await sha256Hex(entry.bytes, subtle), destination_path: destinationPath });
+    }));
+    const destinations = new Set();
+    for (const move of moves) {
+        if (destinations.has(move.destination_path))
+            throw new ProjectFormatError("E_PROJECT_MANIFEST_INVALID", `gallery migration destination 冲突：${move.destination_path}`);
+        destinations.add(move.destination_path);
+    }
+    return Object.freeze({
+        schema_version: 1,
+        kind: "legacy-gallery-v1-to-v2",
+        project_id: manifest.project_id,
+        project_revision: manifest.project_revision,
+        source_manifest_canonical_digest: await computeCanonicalProjectDigest(manifest, subtle),
+        legacy_entry_count: entries.length,
+        legacy_tree_digest: await computeCanonicalFileTreeDigest(entries, subtle),
+        gallery_content_tree_sha256: await computeCanonicalFileTreeDigest(moves.map((move) => ({
+            path: move.destination_path.slice("gallery/".length),
+            bytes: entries.find((entry) => entry.path === move.source_path).bytes,
+        })), subtle),
+        moves: Object.freeze(moves.sort((left, right) => left.source_path.localeCompare(right.source_path, "en"))),
+    });
+}
+export async function assertLocalAuthorProjectGalleryMigrationPreimage(manifest, entries, plan, subtle) {
+    const actual = await planLocalAuthorProjectGalleryMigration(manifest, entries, subtle);
+    if (JSON.stringify(plan) !== JSON.stringify(actual)) {
+        throw new ProjectFormatError("E_PROJECT_MANIFEST_INVALID", "gallery migration preimage 已过期或不匹配");
+    }
+}

package/dist/gallery.d.ts

@@ -0,0 +1,16 @@
+export type GalleryScenarioEntityKind = "node" | "edge";
+export declare const LOCAL_AUTHOR_GALLERY_PATHS: Readonly<{
+    readonly root: "gallery";
+    readonly scenario: "gallery/scenario";
+    readonly view: "gallery/view";
+}>;
+export interface GalleryScenarioEntityIdentity {
+    readonly kind: GalleryScenarioEntityKind;
+    readonly id: string;
+}
+export declare function encodeGalleryScenarioEntityDirectory(kind: GalleryScenarioEntityKind, id: string): string;
+export declare function decodeGalleryScenarioEntityDirectory(directory: string): GalleryScenarioEntityIdentity;
+export declare function galleryScenarioAssetPath(kind: GalleryScenarioEntityKind, id: string, fileName: string): string;
+/** 将 legacy root 下的相对路径压成可逆单文件名，避免嵌套目录逃逸或扁平化碰撞。 */
+export declare function encodeGalleryLegacyAssetFileName(relativePath: string): string;
+export declare function galleryViewAssetPath(contentSha256: string, extension?: string): string;

package/dist/gallery.js

@@ -0,0 +1,86 @@
+import { ProjectFormatError } from "./errors.js";
+export const LOCAL_AUTHOR_GALLERY_PATHS = Object.freeze({
+    root: "gallery",
+    scenario: "gallery/scenario",
+    view: "gallery/view",
+});
+const SHA256 = /^[a-f0-9]{64}$/;
+const SAFE_LEAF = /^[^./\\][^/\\]*$/u;
+const SAFE_EXTENSION = /^[a-z0-9]+$/;
+function assertUnicodeScalarString(value) {
+    if (value.length === 0)
+        throw new ProjectFormatError("E_PROJECT_PATH_INVALID", "gallery entity id 不能为空");
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (next < 0xdc00 || next > 0xdfff)
+                throw new ProjectFormatError("E_PROJECT_PATH_INVALID", "gallery entity id 含孤立 surrogate");
+            index += 1;
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff) {
+            throw new ProjectFormatError("E_PROJECT_PATH_INVALID", "gallery entity id 含孤立 surrogate");
+        }
+    }
+    if (new TextEncoder().encode(value).byteLength > 100)
+        throw new ProjectFormatError("E_PROJECT_PATH_INVALID", "gallery entity id UTF-8 超过 100 bytes");
+}
+function hex(bytes) {
+    return Array.from(bytes, (value) => value.toString(16).padStart(2, "0")).join("");
+}
+export function encodeGalleryScenarioEntityDirectory(kind, id) {
+    if (kind !== "node" && kind !== "edge")
+        throw new ProjectFormatError("E_PROJECT_PATH_INVALID", `gallery entity kind 无效：${String(kind)}`);
+    assertUnicodeScalarString(id);
+    return `${kind}-${hex(new TextEncoder().encode(id))}`;
+}
+export function decodeGalleryScenarioEntityDirectory(directory) {
+    const match = /^(node|edge)-([a-f0-9]+)$/.exec(directory);
+    if (match === null || match[2].length % 2 !== 0)
+        throw new ProjectFormatError("E_PROJECT_PATH_INVALID", `gallery entity directory 非 canonical：${directory}`);
+    const bytes = new Uint8Array(match[2].length / 2);
+    for (let index = 0; index < bytes.length; index += 1)
+        bytes[index] = Number.parseInt(match[2].slice(index * 2, index * 2 + 2), 16);
+    let id;
+    try {
+        id = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw new ProjectFormatError("E_PROJECT_PATH_INVALID", `gallery entity directory 含非法 UTF-8：${directory}`);
+    }
+    const kind = match[1];
+    if (encodeGalleryScenarioEntityDirectory(kind, id) !== directory)
+        throw new ProjectFormatError("E_PROJECT_PATH_INVALID", `gallery entity directory 非 canonical：${directory}`);
+    return Object.freeze({ kind, id });
+}
+function assertSafeLeaf(fileName) {
+    const stem = fileName.split(".")[0]?.toUpperCase() ?? "";
+    if (!SAFE_LEAF.test(fileName) || /[\u0000-\u001f<>:"|?*]/u.test(fileName) || fileName === "." || fileName === ".." || fileName.endsWith(".") || fileName.endsWith(" ") || /^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$/.test(stem) || fileName.normalize("NFC") !== fileName) {
+        throw new ProjectFormatError("E_PROJECT_PATH_INVALID", `gallery 文件名非法：${fileName}`);
+    }
+}
+export function galleryScenarioAssetPath(kind, id, fileName) {
+    assertSafeLeaf(fileName);
+    return `${LOCAL_AUTHOR_GALLERY_PATHS.scenario}/${encodeGalleryScenarioEntityDirectory(kind, id)}/${fileName}`;
+}
+/** 将 legacy root 下的相对路径压成可逆单文件名，避免嵌套目录逃逸或扁平化碰撞。 */
+export function encodeGalleryLegacyAssetFileName(relativePath) {
+    if (relativePath.length === 0 || relativePath.includes("\\") || relativePath.startsWith("/") || relativePath.split("/").some((segment) => segment === "" || segment === "." || segment === "..") || relativePath.normalize("NFC") !== relativePath) {
+        throw new ProjectFormatError("E_PROJECT_PATH_INVALID", `legacy gallery path 非 canonical：${relativePath}`);
+    }
+    assertUnicodeScalarString(relativePath);
+    const encoded = `legacy-${hex(new TextEncoder().encode(relativePath))}`;
+    if (encoded.length > 240)
+        throw new ProjectFormatError("E_PROJECT_PATH_INVALID", "legacy gallery path 编码后超过安全文件名长度");
+    return encoded;
+}
+export function galleryViewAssetPath(contentSha256, extension) {
+    if (!SHA256.test(contentSha256))
+        throw new ProjectFormatError("E_PROJECT_PATH_INVALID", "gallery view asset digest 必须是小写 SHA-256");
+    if (extension === undefined || extension === "")
+        return `${LOCAL_AUTHOR_GALLERY_PATHS.view}/${contentSha256}`;
+    const canonicalExtension = (extension.startsWith(".") ? extension.slice(1) : extension).toLowerCase();
+    if (!SAFE_EXTENSION.test(canonicalExtension))
+        throw new ProjectFormatError("E_PROJECT_PATH_INVALID", `gallery view asset 扩展名非法：${extension}`);
+    return `${LOCAL_AUTHOR_GALLERY_PATHS.view}/${contentSha256}.${canonicalExtension}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./errors.js";
+export * from "./account-project-root.js";
+export * from "./file-tree.js";
+export * from "./gallery.js";
+export * from "./gallery-migration.js";
+export * from "./integrity.js";
+export * from "./lossless-blob.js";
+export * from "./neutral-upload.js";
+export * from "./manifest.js";
+export * from "./scenario-part.js";
+export * from "./tar.js";
+export * from "./wesp.js";
+export * from "./windows-executable.js";

package/dist/index.js

@@ -0,0 +1,13 @@
+export * from "./errors.js";
+export * from "./account-project-root.js";
+export * from "./file-tree.js";
+export * from "./gallery.js";
+export * from "./gallery-migration.js";
+export * from "./integrity.js";
+export * from "./lossless-blob.js";
+export * from "./neutral-upload.js";
+export * from "./manifest.js";
+export * from "./scenario-part.js";
+export * from "./tar.js";
+export * from "./wesp.js";
+export * from "./windows-executable.js";

package/dist/integrity.d.ts

@@ -0,0 +1,6 @@
+export declare function bytesToHex(bytes: Uint8Array): string;
+/** 比较固定格式 SHA-256 hex，避免提前退出造成不必要的差异行为。 */
+export declare function sha256HexEquals(left: string, right: string): boolean;
+export declare function sha256Bytes(bytes: Uint8Array, subtle?: SubtleCrypto): Promise<Uint8Array>;
+export declare function sha256Hex(bytes: Uint8Array, subtle?: SubtleCrypto): Promise<string>;
+export declare function assertSha256Hex(value: unknown, field: string): asserts value is string;

package/dist/integrity.js

@@ -0,0 +1,26 @@
+import { ProjectFormatError } from "./errors.js";
+export function bytesToHex(bytes) {
+    return Array.from(bytes, (value) => value.toString(16).padStart(2, "0")).join("");
+}
+/** 比较固定格式 SHA-256 hex，避免提前退出造成不必要的差异行为。 */
+export function sha256HexEquals(left, right) {
+    if (left.length !== 64 || right.length !== 64)
+        return false;
+    let difference = 0;
+    for (let index = 0; index < 64; index += 1) {
+        difference |= left.charCodeAt(index) ^ right.charCodeAt(index);
+    }
+    return difference === 0;
+}
+export async function sha256Bytes(bytes, subtle = globalThis.crypto.subtle) {
+    const digest = await subtle.digest("SHA-256", bytes);
+    return new Uint8Array(digest);
+}
+export async function sha256Hex(bytes, subtle) {
+    return bytesToHex(await sha256Bytes(bytes, subtle));
+}
+export function assertSha256Hex(value, field) {
+    if (typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value)) {
+        throw new ProjectFormatError("E_PROJECT_MANIFEST_INVALID", `${field} 必须是小写 SHA-256 hex`);
+    }
+}

package/dist/lossless-blob.d.ts

@@ -0,0 +1,49 @@
+/** Lossless blob descriptor v1：只描述传输对象，不授予 object_key 的访问权限。 */
+export interface LosslessBlobDescriptorV1 {
+    readonly schema_version: 1;
+    readonly codec: "identity" | "gzip-v1";
+    readonly raw: LosslessBlobDigest;
+    readonly encoded: LosslessBlobDigest;
+    readonly chunks: readonly LosslessBlobChunkDescriptor[];
+}
+export interface LosslessBlobDigest {
+    readonly byte_length: number;
+    readonly sha256: string;
+}
+export interface LosslessBlobChunkDescriptor extends LosslessBlobDigest {
+    readonly index: number;
+    readonly object_key: string;
+}
+export type LosslessBlobByteSource = AsyncIterable<Uint8Array>;
+export type LosslessBlobChunkWriter = (chunk: Readonly<{
+    index: number;
+    bytes: Uint8Array;
+    sha256: string;
+}>) => Promise<string> | string;
+export type LosslessBlobChunkReader = (chunk: LosslessBlobChunkDescriptor) => Promise<LosslessBlobByteSource> | LosslessBlobByteSource;
+export interface LosslessBlobSha256 {
+    update(bytes: Uint8Array): LosslessBlobSha256;
+    digestHex(): string;
+}
+export interface LosslessBlobOptions {
+    readonly codec?: LosslessBlobDescriptorV1["codec"];
+    /** 运行时官方/受审计的增量 SHA-256 adapter；模块不自研密码学实现。 */
+    readonly createSha256: () => LosslessBlobSha256;
+}
+export declare const LOSSLESS_BLOB_CHUNK_BYTES: number;
+export declare const LOSSLESS_BLOB_MAX_BYTES: number;
+export declare const LOSSLESS_BLOB_MAX_CHUNKS = 128;
+export declare class LosslessBlobError extends Error {
+    constructor(message: string);
+}
+/**
+ * 流式编码原始 bytes。writer 返回的 object_key 仅是不透明定位符；鉴权属于运输层。
+ * 失败时已写 chunk 不会出现在 descriptor 中，writer 应把它们留在临时 staging 中清理。
+ */
+export declare function encodeLosslessBlob(source: LosslessBlobByteSource, writer: LosslessBlobChunkWriter, options: LosslessBlobOptions): Promise<LosslessBlobDescriptorV1>;
+/**
+ * 返回逐块验证后的原始 byte 流。只有迭代到 EOF 且未抛错，整个 blob 才 verified；
+ * 调用方必须写临时 staging，并在迭代成功结束后原子 commit，不能发布此前产出的前缀。
+ */
+export declare function decodeLosslessBlob(candidate: unknown, reader: LosslessBlobChunkReader, options: Pick<LosslessBlobOptions, "createSha256">): LosslessBlobByteSource;
+export declare function validateLosslessBlobDescriptor(candidate: unknown): LosslessBlobDescriptorV1;