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

package/dist/lossless-blob.js

@@ -0,0 +1,270 @@
+export const LOSSLESS_BLOB_CHUNK_BYTES = 4 * 1024 * 1024;
+export const LOSSLESS_BLOB_MAX_BYTES = 512 * 1024 * 1024;
+export const LOSSLESS_BLOB_MAX_CHUNKS = 128;
+export class LosslessBlobError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LosslessBlobError";
+    }
+}
+/**
+ * 流式编码原始 bytes。writer 返回的 object_key 仅是不透明定位符；鉴权属于运输层。
+ * 失败时已写 chunk 不会出现在 descriptor 中，writer 应把它们留在临时 staging 中清理。
+ */
+export async function encodeLosslessBlob(source, writer, options) {
+    const codec = options.codec ?? "gzip-v1";
+    const createSha256 = options.createSha256;
+    if (codec !== "identity" && codec !== "gzip-v1") {
+        throw new LosslessBlobError("codec 必须是 identity 或 gzip-v1");
+    }
+    const rawHash = createSha256();
+    let rawLength = 0;
+    const checkedSource = mapBytes(source, (bytes) => {
+        rawLength = checkedAdd(rawLength, bytes.byteLength, LOSSLESS_BLOB_MAX_BYTES, "raw");
+        rawHash.update(bytes);
+    });
+    const encodedSource = codec === "identity"
+        ? checkedSource
+        : transformBytes(checkedSource, new CompressionStream("gzip"));
+    const encodedHash = createSha256();
+    const chunks = [];
+    const objectKeys = new Set();
+    let encodedLength = 0;
+    let pending = new Uint8Array(LOSSLESS_BLOB_CHUNK_BYTES);
+    let pendingLength = 0;
+    const flush = async () => {
+        if (pendingLength === 0)
+            return;
+        if (chunks.length >= LOSSLESS_BLOB_MAX_CHUNKS) {
+            throw new LosslessBlobError(`encoded chunk 数超过 ${LOSSLESS_BLOB_MAX_CHUNKS}`);
+        }
+        const bytes = pending.slice(0, pendingLength);
+        const sha256 = createSha256().update(bytes).digestHex();
+        const index = chunks.length;
+        const objectKey = await writer({ index, bytes, sha256 });
+        if (typeof objectKey !== "string" || objectKey.length === 0) {
+            throw new LosslessBlobError(`writer 为 chunk ${index} 返回了空 object_key`);
+        }
+        if (objectKeys.has(objectKey)) {
+            throw new LosslessBlobError(`writer 返回了重复 object_key: ${objectKey}`);
+        }
+        objectKeys.add(objectKey);
+        chunks.push({ index, byte_length: bytes.byteLength, sha256, object_key: objectKey });
+        pending = new Uint8Array(LOSSLESS_BLOB_CHUNK_BYTES);
+        pendingLength = 0;
+    };
+    for await (const bytes of encodedSource) {
+        assertBytes(bytes);
+        encodedLength = checkedAdd(encodedLength, bytes.byteLength, LOSSLESS_BLOB_MAX_BYTES, "encoded");
+        encodedHash.update(bytes);
+        let offset = 0;
+        while (offset < bytes.byteLength) {
+            const copied = Math.min(LOSSLESS_BLOB_CHUNK_BYTES - pendingLength, bytes.byteLength - offset);
+            pending.set(bytes.subarray(offset, offset + copied), pendingLength);
+            pendingLength += copied;
+            offset += copied;
+            if (pendingLength === LOSSLESS_BLOB_CHUNK_BYTES)
+                await flush();
+        }
+    }
+    await flush();
+    const descriptor = {
+        schema_version: 1,
+        codec,
+        raw: { byte_length: rawLength, sha256: rawHash.digestHex() },
+        encoded: { byte_length: encodedLength, sha256: encodedHash.digestHex() },
+        chunks,
+    };
+    validateLosslessBlobDescriptor(descriptor);
+    return descriptor;
+}
+/**
+ * 返回逐块验证后的原始 byte 流。只有迭代到 EOF 且未抛错，整个 blob 才 verified；
+ * 调用方必须写临时 staging，并在迭代成功结束后原子 commit，不能发布此前产出的前缀。
+ */
+export function decodeLosslessBlob(candidate, reader, options) {
+    const descriptor = validateLosslessBlobDescriptor(candidate);
+    return decodeVerified(descriptor, reader, options.createSha256);
+}
+export function validateLosslessBlobDescriptor(candidate) {
+    assertExactObject(candidate, ["schema_version", "codec", "raw", "encoded", "chunks"], "descriptor");
+    if (candidate.schema_version !== 1)
+        throw new LosslessBlobError("schema_version 必须是 1");
+    if (candidate.codec !== "identity" && candidate.codec !== "gzip-v1") {
+        throw new LosslessBlobError("codec 必须是 identity 或 gzip-v1");
+    }
+    const raw = validateDigest(candidate.raw, "raw");
+    const encoded = validateDigest(candidate.encoded, "encoded");
+    if (!Array.isArray(candidate.chunks) || candidate.chunks.length > LOSSLESS_BLOB_MAX_CHUNKS) {
+        throw new LosslessBlobError(`chunks 必须是至多 ${LOSSLESS_BLOB_MAX_CHUNKS} 项的数组`);
+    }
+    const chunks = [];
+    const keys = new Set();
+    let sum = 0;
+    for (let index = 0; index < candidate.chunks.length; index += 1) {
+        const value = candidate.chunks[index];
+        assertExactObject(value, ["index", "byte_length", "sha256", "object_key"], `chunks[${index}]`);
+        if (value.index !== index)
+            throw new LosslessBlobError(`chunks[${index}].index 必须严格连续且有序`);
+        const byteLength = value.byte_length;
+        if (typeof byteLength !== "number" || !Number.isSafeInteger(byteLength) || byteLength <= 0 || byteLength > LOSSLESS_BLOB_CHUNK_BYTES) {
+            throw new LosslessBlobError(`chunks[${index}].byte_length 超出范围`);
+        }
+        if (index < candidate.chunks.length - 1 && byteLength !== LOSSLESS_BLOB_CHUNK_BYTES) {
+            throw new LosslessBlobError(`非末尾 chunk ${index} 必须恰好为 4 MiB`);
+        }
+        assertSha256(value.sha256, `chunks[${index}].sha256`);
+        if (typeof value.object_key !== "string" || value.object_key.length === 0 || keys.has(value.object_key)) {
+            throw new LosslessBlobError(`chunks[${index}].object_key 必须非空且唯一`);
+        }
+        keys.add(value.object_key);
+        sum = checkedAdd(sum, byteLength, LOSSLESS_BLOB_MAX_BYTES, "chunks encoded");
+        chunks.push({
+            index,
+            byte_length: byteLength,
+            sha256: value.sha256,
+            object_key: value.object_key,
+        });
+    }
+    if (sum !== encoded.byte_length)
+        throw new LosslessBlobError("encoded.byte_length 与 chunk 总长不一致");
+    if ((encoded.byte_length === 0) !== (chunks.length === 0)) {
+        throw new LosslessBlobError("空 encoded blob 与 chunks 不一致");
+    }
+    if (candidate.codec === "identity" &&
+        (raw.byte_length !== encoded.byte_length || raw.sha256 !== encoded.sha256)) {
+        throw new LosslessBlobError("identity codec 的 raw/encoded digest 必须一致");
+    }
+    return { schema_version: 1, codec: candidate.codec, raw, encoded, chunks };
+}
+async function* decodeVerified(descriptor, reader, createSha256) {
+    // 第一遍先完成所有 encoded 完整性验证，避免把未验证 encoded 前缀送入 inflater。
+    const encodedHash = createSha256();
+    let encodedLength = 0;
+    for (const chunk of descriptor.chunks) {
+        const bytes = await readVerifiedChunk(chunk, reader, createSha256);
+        encodedLength = checkedAdd(encodedLength, bytes.byteLength, descriptor.encoded.byte_length, "encoded");
+        encodedHash.update(bytes);
+    }
+    if (encodedLength !== descriptor.encoded.byte_length)
+        throw new LosslessBlobError("encoded byte_length 不匹配");
+    if (encodedHash.digestHex() !== descriptor.encoded.sha256)
+        throw new LosslessBlobError("encoded SHA-256 不匹配");
+    async function* verifiedEncoded() {
+        for (const chunk of descriptor.chunks)
+            yield await readVerifiedChunk(chunk, reader, createSha256);
+    }
+    const rawSource = descriptor.codec === "identity"
+        ? verifiedEncoded()
+        : transformBytes(verifiedEncoded(), new DecompressionStream("gzip"));
+    const rawHash = createSha256();
+    let rawLength = 0;
+    for await (const bytes of rawSource) {
+        assertBytes(bytes);
+        rawLength = checkedAdd(rawLength, bytes.byteLength, descriptor.raw.byte_length, "raw");
+        rawHash.update(bytes);
+        yield bytes;
+    }
+    if (rawLength !== descriptor.raw.byte_length)
+        throw new LosslessBlobError("raw byte_length 不匹配");
+    if (rawHash.digestHex() !== descriptor.raw.sha256)
+        throw new LosslessBlobError("raw SHA-256 不匹配");
+}
+async function readVerifiedChunk(chunk, reader, createSha256) {
+    const chunkHash = createSha256();
+    let chunkLength = 0;
+    const result = new Uint8Array(chunk.byte_length);
+    const source = await reader(chunk);
+    if (source === null || typeof source !== "object" || !(Symbol.asyncIterator in source)) {
+        throw new LosslessBlobError(`reader 未返回 chunk ${chunk.index} 的 AsyncIterable`);
+    }
+    for await (const bytes of source) {
+        assertBytes(bytes);
+        chunkLength = checkedAdd(chunkLength, bytes.byteLength, chunk.byte_length, `chunk ${chunk.index}`);
+        chunkHash.update(bytes);
+        result.set(bytes, chunkLength - bytes.byteLength);
+    }
+    if (chunkLength !== chunk.byte_length)
+        throw new LosslessBlobError(`chunk ${chunk.index} 被截断`);
+    if (chunkHash.digestHex() !== chunk.sha256)
+        throw new LosslessBlobError(`chunk ${chunk.index} SHA-256 不匹配`);
+    return result;
+}
+async function* mapBytes(source, observe) {
+    for await (const bytes of source) {
+        assertBytes(bytes);
+        observe(bytes);
+        yield bytes;
+    }
+}
+async function* transformBytes(source, transform) {
+    const writer = transform.writable.getWriter();
+    const reader = transform.readable.getReader();
+    const pumping = (async () => {
+        try {
+            for await (const bytes of source)
+                await writer.write(bytes);
+            await writer.close();
+        }
+        catch (error) {
+            await writer.abort(error).catch(() => undefined);
+            throw error;
+        }
+    })().then(() => ({ ok: true }), (error) => ({ ok: false, error }));
+    let completed = false;
+    try {
+        while (true) {
+            const result = await reader.read();
+            if (result.done)
+                break;
+            yield result.value;
+        }
+        const result = await pumping;
+        if (!result.ok)
+            throw result.error;
+        completed = true;
+    }
+    finally {
+        if (!completed) {
+            await reader.cancel().catch(() => undefined);
+            await writer.abort().catch(() => undefined);
+            await pumping;
+        }
+        reader.releaseLock();
+    }
+}
+function validateDigest(value, field) {
+    assertExactObject(value, ["byte_length", "sha256"], field);
+    const byteLength = value.byte_length;
+    if (typeof byteLength !== "number" || !Number.isSafeInteger(byteLength) || byteLength < 0 || byteLength > LOSSLESS_BLOB_MAX_BYTES) {
+        throw new LosslessBlobError(`${field}.byte_length 超出范围`);
+    }
+    assertSha256(value.sha256, `${field}.sha256`);
+    return { byte_length: byteLength, sha256: value.sha256 };
+}
+function assertExactObject(value, keys, field) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new LosslessBlobError(`${field} 必须是对象`);
+    }
+    const actual = Object.keys(value).sort();
+    const expected = [...keys].sort();
+    if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
+        throw new LosslessBlobError(`${field} 字段 schema 不匹配`);
+    }
+}
+function assertSha256(value, field) {
+    if (typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value)) {
+        throw new LosslessBlobError(`${field} 必须是小写 SHA-256 hex`);
+    }
+}
+function assertBytes(value) {
+    if (!(value instanceof Uint8Array))
+        throw new LosslessBlobError("byte source 只能产生 Uint8Array");
+}
+function checkedAdd(current, addition, maximum, field) {
+    const result = current + addition;
+    if (!Number.isSafeInteger(result) || result > maximum) {
+        throw new LosslessBlobError(`${field} 超过 ${maximum} bytes`);
+    }
+    return result;
+}

package/dist/manifest.d.ts

@@ -0,0 +1,89 @@
+export declare const LOCAL_AUTHOR_PROJECT_MANIFEST_SCHEMA_VERSION = 2;
+export interface LocalAuthorProjectManifestV1 {
+    schema_version: 1;
+    project_id: string;
+    project_revision: number;
+    created_at_ms: number;
+    updated_at_ms: number;
+    scenario: {
+        local_scenario_id: string;
+        source_path: "scenario/source.wes";
+        source_sha256: string;
+        assets_digest: string;
+    };
+    view: {
+        local_view_id: string;
+        root_path: "view";
+        source_tree_sha256: string;
+        package_lock_sha256: string;
+    };
+    snapshot: {
+        snapshot_id: string;
+        canonical_digest: string;
+        previous_snapshot_id: string | null;
+    };
+    toolchain: {
+        template_version: string;
+        project_host_version: string;
+        authoring_bridge_version: string;
+        desktop_package_version: string;
+        agent_kit_version: string;
+    };
+}
+export interface LocalAuthorProjectManifestV2 extends Omit<LocalAuthorProjectManifestV1, "schema_version"> {
+    schema_version: 2;
+    gallery: {
+        root_path: "gallery";
+        scenario_root_path: "gallery/scenario";
+        view_root_path: "gallery/view";
+        content_tree_sha256: string;
+    };
+}
+export type LocalAuthorProjectManifest = LocalAuthorProjectManifestV1 | LocalAuthorProjectManifestV2;
+export interface CanonicalProjectDigestInputV1 {
+    schema_version: 1;
+    project_id: string;
+    project_revision: number;
+    scenario_source_sha256: string;
+    scenario_assets_digest: string;
+    view_source_tree_sha256: string;
+    view_package_lock_sha256: string;
+}
+export interface CanonicalProjectDigestInputV2 extends Omit<CanonicalProjectDigestInputV1, "schema_version"> {
+    schema_version: 2;
+    gallery_root_path: "gallery";
+    gallery_scenario_root_path: "gallery/scenario";
+    gallery_view_root_path: "gallery/view";
+    gallery_content_tree_sha256: string;
+}
+export type CanonicalProjectDigestInput = CanonicalProjectDigestInputV1 | CanonicalProjectDigestInputV2;
+/**
+ * 格式迁移必须在写入前持久化此 preimage，并在 apply 前重新校验。
+ * 它只绑定根 manifest 已定义的冻结 authority，不复制 Scenario/View 的第二份内容 authority。
+ */
+export interface LocalAuthorProjectManifestMigrationPreimageV1 {
+    readonly schema_version: 1;
+    readonly project_id: string;
+    readonly project_revision: number;
+    readonly canonical_digest: string;
+}
+/** M1 只允许可验证的同版本 no-op；跨版本迁移必须先显式加入新 schema 的实现。 */
+export interface LocalAuthorProjectManifestMigrationPlanV1 {
+    readonly schema_version: 1;
+    readonly kind: "noop";
+    readonly from_schema_version: 1;
+    readonly to_schema_version: 1;
+    readonly preimage: LocalAuthorProjectManifestMigrationPreimageV1;
+}
+export declare function validateLocalAuthorProjectManifest(manifest: LocalAuthorProjectManifestV1): LocalAuthorProjectManifestV1;
+export declare function validateLocalAuthorProjectManifest(manifest: LocalAuthorProjectManifestV2): LocalAuthorProjectManifestV2;
+export declare function validateLocalAuthorProjectManifest(manifest: LocalAuthorProjectManifest): LocalAuthorProjectManifest;
+export declare function canonicalProjectDigestInput(manifest: LocalAuthorProjectManifest): CanonicalProjectDigestInput;
+export declare function canonicalProjectDigestBytes(manifest: LocalAuthorProjectManifest): Uint8Array;
+export declare function computeCanonicalProjectDigest(manifest: LocalAuthorProjectManifest, subtle?: SubtleCrypto): Promise<string>;
+export declare function verifyLocalAuthorProjectManifestSnapshot(manifest: LocalAuthorProjectManifestV1, subtle?: SubtleCrypto): Promise<LocalAuthorProjectManifestV1>;
+export declare function verifyLocalAuthorProjectManifestSnapshot(manifest: LocalAuthorProjectManifestV2, subtle?: SubtleCrypto): Promise<LocalAuthorProjectManifestV2>;
+export declare function verifyLocalAuthorProjectManifestSnapshot(manifest: LocalAuthorProjectManifest, subtle?: SubtleCrypto): Promise<LocalAuthorProjectManifest>;
+export declare function createLocalAuthorProjectManifestMigrationPreimage(manifest: LocalAuthorProjectManifestV1, subtle?: SubtleCrypto): Promise<LocalAuthorProjectManifestMigrationPreimageV1>;
+export declare function planLocalAuthorProjectManifestMigration(manifest: LocalAuthorProjectManifestV1, targetSchemaVersion: number, subtle?: SubtleCrypto): Promise<LocalAuthorProjectManifestMigrationPlanV1>;
+export declare function assertLocalAuthorProjectManifestMigrationPreimage(manifest: LocalAuthorProjectManifestV1, preimage: LocalAuthorProjectManifestMigrationPreimageV1, subtle?: SubtleCrypto): Promise<LocalAuthorProjectManifestV1>;

package/dist/manifest.js

@@ -0,0 +1,206 @@
+import { ProjectFormatError } from "./errors.js";
+import { assertSha256Hex, sha256Hex, sha256HexEquals } from "./integrity.js";
+import { LOCAL_AUTHOR_GALLERY_PATHS } from "./gallery.js";
+export const LOCAL_AUTHOR_PROJECT_MANIFEST_SCHEMA_VERSION = 2;
+const CANONICAL_PROJECT_DIGEST_DOMAIN_V1 = "worldengine.local-author-project.digest/v1";
+const CANONICAL_PROJECT_DIGEST_DOMAIN_V2 = "worldengine.local-author-project.digest/v2";
+function assertNonEmptyString(value, field) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new ProjectFormatError("E_PROJECT_MANIFEST_INVALID", `${field} 不能为空`);
+    }
+}
+function assertSafeNonNegativeInteger(value, field) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new ProjectFormatError("E_PROJECT_MANIFEST_INVALID", `${field} 必须是非负安全整数`);
+    }
+}
+function assertExactObject(value, field, keys) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new ProjectFormatError("E_PROJECT_MANIFEST_INVALID", `${field} 必须是对象`);
+    }
+    const actualKeys = Object.keys(value);
+    if (actualKeys.length !== keys.length || actualKeys.some((key) => !keys.includes(key))) {
+        throw new ProjectFormatError("E_PROJECT_MANIFEST_INVALID", `${field} 包含未知或缺失字段`);
+    }
+}
+function assertSnapshotPreviousId(value, snapshotId) {
+    if (value === null)
+        return;
+    assertNonEmptyString(value, "snapshot.previous_snapshot_id");
+    if (value === snapshotId) {
+        throw new ProjectFormatError("E_PROJECT_MANIFEST_INVALID", "snapshot.previous_snapshot_id 不能指向自身");
+    }
+}
+export function validateLocalAuthorProjectManifest(manifest) {
+    if (manifest.schema_version !== 1 && manifest.schema_version !== LOCAL_AUTHOR_PROJECT_MANIFEST_SCHEMA_VERSION) {
+        throw new ProjectFormatError("E_PROJECT_MANIFEST_INVALID", "仅支持 manifest schema_version 1 或 2");
+    }
+    assertExactObject(manifest, "manifest", [
+        "schema_version",
+        "project_id",
+        "project_revision",
+        "created_at_ms",
+        "updated_at_ms",
+        "scenario",
+        "view",
+        "snapshot",
+        "toolchain",
+        ...(manifest.schema_version === 2 ? ["gallery"] : []),
+    ]);
+    assertExactObject(manifest.scenario, "scenario", [
+        "local_scenario_id",
+        "source_path",
+        "source_sha256",
+        "assets_digest",
+    ]);
+    assertExactObject(manifest.view, "view", [
+        "local_view_id",
+        "root_path",
+        "source_tree_sha256",
+        "package_lock_sha256",
+    ]);
+    assertExactObject(manifest.snapshot, "snapshot", [
+        "snapshot_id",
+        "canonical_digest",
+        "previous_snapshot_id",
+    ]);
+    assertExactObject(manifest.toolchain, "toolchain", [
+        "template_version",
+        "project_host_version",
+        "authoring_bridge_version",
+        "desktop_package_version",
+        "agent_kit_version",
+    ]);
+    if (manifest.schema_version === 2) {
+        assertExactObject(manifest.gallery, "gallery", ["root_path", "scenario_root_path", "view_root_path", "content_tree_sha256"]);
+        if (manifest.gallery.root_path !== LOCAL_AUTHOR_GALLERY_PATHS.root || manifest.gallery.scenario_root_path !== LOCAL_AUTHOR_GALLERY_PATHS.scenario || manifest.gallery.view_root_path !== LOCAL_AUTHOR_GALLERY_PATHS.view) {
+            throw new ProjectFormatError("E_PROJECT_PATH_INVALID", "gallery root paths 必须使用固定本地 authority");
+        }
+        assertSha256Hex(manifest.gallery.content_tree_sha256, "gallery.content_tree_sha256");
+    }
+    assertNonEmptyString(manifest.project_id, "project_id");
+    assertSafeNonNegativeInteger(manifest.project_revision, "project_revision");
+    assertSafeNonNegativeInteger(manifest.created_at_ms, "created_at_ms");
+    assertSafeNonNegativeInteger(manifest.updated_at_ms, "updated_at_ms");
+    if (manifest.updated_at_ms < manifest.created_at_ms) {
+        throw new ProjectFormatError("E_PROJECT_MANIFEST_INVALID", "updated_at_ms 不能早于 created_at_ms");
+    }
+    assertNonEmptyString(manifest.scenario.local_scenario_id, "scenario.local_scenario_id");
+    assertNonEmptyString(manifest.view.local_view_id, "view.local_view_id");
+    if (manifest.scenario.source_path !== "scenario/source.wes") {
+        throw new ProjectFormatError("E_PROJECT_PATH_INVALID", "scenario.source_path 必须固定为 scenario/source.wes");
+    }
+    if (manifest.view.root_path !== "view") {
+        throw new ProjectFormatError("E_PROJECT_PATH_INVALID", "view.root_path 必须固定为 view");
+    }
+    assertSha256Hex(manifest.scenario.source_sha256, "scenario.source_sha256");
+    assertSha256Hex(manifest.scenario.assets_digest, "scenario.assets_digest");
+    assertSha256Hex(manifest.view.source_tree_sha256, "view.source_tree_sha256");
+    assertSha256Hex(manifest.view.package_lock_sha256, "view.package_lock_sha256");
+    assertNonEmptyString(manifest.snapshot.snapshot_id, "snapshot.snapshot_id");
+    assertSha256Hex(manifest.snapshot.canonical_digest, "snapshot.canonical_digest");
+    assertSnapshotPreviousId(manifest.snapshot.previous_snapshot_id, manifest.snapshot.snapshot_id);
+    for (const [field, value] of Object.entries(manifest.toolchain)) {
+        assertNonEmptyString(value, `toolchain.${field}`);
+    }
+    return manifest;
+}
+export function canonicalProjectDigestInput(manifest) {
+    validateLocalAuthorProjectManifest(manifest);
+    const base = {
+        project_id: manifest.project_id,
+        project_revision: manifest.project_revision,
+        scenario_source_sha256: manifest.scenario.source_sha256,
+        scenario_assets_digest: manifest.scenario.assets_digest,
+        view_source_tree_sha256: manifest.view.source_tree_sha256,
+        view_package_lock_sha256: manifest.view.package_lock_sha256,
+    };
+    return manifest.schema_version === 1 ? { ...base, schema_version: 1 } : {
+        ...base,
+        schema_version: 2,
+        gallery_root_path: manifest.gallery.root_path,
+        gallery_scenario_root_path: manifest.gallery.scenario_root_path,
+        gallery_view_root_path: manifest.gallery.view_root_path,
+        gallery_content_tree_sha256: manifest.gallery.content_tree_sha256,
+    };
+}
+export function canonicalProjectDigestBytes(manifest) {
+    const input = canonicalProjectDigestInput(manifest);
+    const encoder = new TextEncoder();
+    const values = [
+        manifest.schema_version === 1 ? CANONICAL_PROJECT_DIGEST_DOMAIN_V1 : CANONICAL_PROJECT_DIGEST_DOMAIN_V2,
+        String(input.schema_version),
+        input.project_id,
+        String(input.project_revision),
+        input.scenario_source_sha256,
+        input.scenario_assets_digest,
+        input.view_source_tree_sha256,
+        input.view_package_lock_sha256,
+        ...(input.schema_version === 2 ? [input.gallery_root_path, input.gallery_scenario_root_path, input.gallery_view_root_path, input.gallery_content_tree_sha256] : []),
+    ].map((value) => encoder.encode(value));
+    const totalSize = values.reduce((size, value) => size + 4 + value.byteLength, 0);
+    const canonical = new Uint8Array(totalSize);
+    const view = new DataView(canonical.buffer);
+    let offset = 0;
+    for (const value of values) {
+        view.setUint32(offset, value.byteLength);
+        offset += 4;
+        canonical.set(value, offset);
+        offset += value.byteLength;
+    }
+    return canonical;
+}
+export async function computeCanonicalProjectDigest(manifest, subtle) {
+    return sha256Hex(canonicalProjectDigestBytes(manifest), subtle);
+}
+export async function verifyLocalAuthorProjectManifestSnapshot(manifest, subtle) {
+    validateLocalAuthorProjectManifest(manifest);
+    const expectedDigest = await computeCanonicalProjectDigest(manifest, subtle);
+    if (!sha256HexEquals(manifest.snapshot.canonical_digest, expectedDigest)) {
+        throw new ProjectFormatError("E_PROJECT_MANIFEST_INVALID", "snapshot.canonical_digest 与冻结 authority 不匹配");
+    }
+    return manifest;
+}
+export async function createLocalAuthorProjectManifestMigrationPreimage(manifest, subtle) {
+    validateLocalAuthorProjectManifest(manifest);
+    return Object.freeze({
+        schema_version: 1,
+        project_id: manifest.project_id,
+        project_revision: manifest.project_revision,
+        canonical_digest: await computeCanonicalProjectDigest(manifest, subtle),
+    });
+}
+export async function planLocalAuthorProjectManifestMigration(manifest, targetSchemaVersion, subtle) {
+    validateLocalAuthorProjectManifest(manifest);
+    if (targetSchemaVersion !== manifest.schema_version) {
+        throw new ProjectFormatError("E_PROJECT_MANIFEST_INVALID", `manifest noop plan 不支持从 schema_version 1 迁移到 ${String(targetSchemaVersion)}`);
+    }
+    return Object.freeze({
+        schema_version: 1,
+        kind: "noop",
+        from_schema_version: 1,
+        to_schema_version: 1,
+        preimage: await createLocalAuthorProjectManifestMigrationPreimage(manifest, subtle),
+    });
+}
+export async function assertLocalAuthorProjectManifestMigrationPreimage(manifest, preimage, subtle) {
+    assertExactObject(preimage, "migration.preimage", [
+        "schema_version",
+        "project_id",
+        "project_revision",
+        "canonical_digest",
+    ]);
+    if (preimage.schema_version !== 1) {
+        throw new ProjectFormatError("E_PROJECT_MANIFEST_INVALID", "不支持 migration preimage schema_version");
+    }
+    assertNonEmptyString(preimage.project_id, "migration.preimage.project_id");
+    assertSafeNonNegativeInteger(preimage.project_revision, "migration.preimage.project_revision");
+    assertSha256Hex(preimage.canonical_digest, "migration.preimage.canonical_digest");
+    const actual = await createLocalAuthorProjectManifestMigrationPreimage(manifest, subtle);
+    if (actual.project_id !== preimage.project_id ||
+        actual.project_revision !== preimage.project_revision ||
+        !sha256HexEquals(actual.canonical_digest, preimage.canonical_digest)) {
+        throw new ProjectFormatError("E_PROJECT_MANIFEST_INVALID", "migration preimage 已过期或不匹配");
+    }
+    return manifest;
+}

package/dist/neutral-upload.d.ts

@@ -0,0 +1,48 @@
+import type { LosslessBlobByteSource, LosslessBlobSha256 } from "./lossless-blob.js";
+export type NeutralUploadObjectKind = "manifest" | "revision_index" | "section" | "local_project_wesp" | "view";
+export type NeutralUploadChunkCodec = "identity-v1" | "gzip-member-v1";
+export interface NeutralUploadChunkRefV2 {
+    readonly index: number;
+    readonly raw_offset: number;
+    readonly raw_byte_length: number;
+    readonly raw_sha256: string;
+    readonly codec: NeutralUploadChunkCodec;
+    readonly encoded_byte_length: number;
+    readonly encoded_sha256: string;
+}
+export interface NeutralUploadLogicalObjectRefV2 {
+    readonly object_id: string;
+    readonly object_kind: NeutralUploadObjectKind;
+    readonly section_key?: string;
+    readonly media_type?: string;
+    readonly canonical_encoding?: string;
+    readonly raw_byte_length: number;
+    readonly raw_sha256: string;
+    readonly chunks: readonly NeutralUploadChunkRefV2[];
+}
+export interface NeutralUploadLogicalObjectInput {
+    readonly object_id: string;
+    readonly object_kind: NeutralUploadObjectKind;
+    readonly section_key?: string;
+    readonly media_type?: string;
+    readonly canonical_encoding?: string;
+    readonly bytes: LosslessBlobByteSource;
+}
+export type NeutralUploadChunkWriter = (chunk: Readonly<{
+    object_id: string;
+    ref: NeutralUploadChunkRefV2;
+    bytes: Uint8Array;
+}>) => Promise<void> | void;
+export interface EncodeNeutralUploadOptions {
+    readonly codec?: NeutralUploadChunkCodec;
+    readonly create_sha256: () => LosslessBlobSha256;
+}
+export declare const NEUTRAL_UPLOAD_RAW_CHUNK_BYTES: number;
+export declare const NEUTRAL_UPLOAD_MAX_ENCODED_CHUNK_BYTES: number;
+export declare const NEUTRAL_UPLOAD_MAX_OBJECT_BYTES: number;
+export declare const NEUTRAL_UPLOAD_MAX_CHUNKS = 128;
+export declare const NEUTRAL_UPLOAD_MAX_OBJECTS = 64;
+export declare const NEUTRAL_UPLOAD_MAX_PLAN_BYTES: number;
+/** 每个 raw chunk 独立压缩，禁止跨 chunk gzip 状态。descriptor 仅在全部 writer 成功后返回。 */
+export declare function encodeNeutralUploadLogicalObject(input: NeutralUploadLogicalObjectInput, writer: NeutralUploadChunkWriter, options: EncodeNeutralUploadOptions): Promise<NeutralUploadLogicalObjectRefV2>;
+export declare function assertNeutralUploadPlanLimits(objects: readonly NeutralUploadLogicalObjectRefV2[]): void;