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

package/dist/neutral-upload.js

@@ -0,0 +1,102 @@
+export const NEUTRAL_UPLOAD_RAW_CHUNK_BYTES = 4 * 1024 * 1024;
+export const NEUTRAL_UPLOAD_MAX_ENCODED_CHUNK_BYTES = 8 * 1024 * 1024;
+export const NEUTRAL_UPLOAD_MAX_OBJECT_BYTES = 512 * 1024 * 1024;
+export const NEUTRAL_UPLOAD_MAX_CHUNKS = 128;
+export const NEUTRAL_UPLOAD_MAX_OBJECTS = 64;
+export const NEUTRAL_UPLOAD_MAX_PLAN_BYTES = 1024 * 1024 * 1024;
+/** 每个 raw chunk 独立压缩，禁止跨 chunk gzip 状态。descriptor 仅在全部 writer 成功后返回。 */
+export async function encodeNeutralUploadLogicalObject(input, writer, options) {
+    assertDescriptor(input);
+    const codec = options.codec ?? "gzip-member-v1";
+    if (codec !== "identity-v1" && codec !== "gzip-member-v1")
+        throw new TypeError("neutral upload codec 无效");
+    const objectHash = options.create_sha256();
+    const refs = [];
+    let rawLength = 0;
+    let pending = new Uint8Array(NEUTRAL_UPLOAD_RAW_CHUNK_BYTES);
+    let pendingLength = 0;
+    const flush = async () => {
+        if (pendingLength === 0)
+            return;
+        if (refs.length >= NEUTRAL_UPLOAD_MAX_CHUNKS)
+            throw new RangeError("neutral upload chunk 数超过 128");
+        const raw = pending.slice(0, pendingLength);
+        const encoded = codec === "identity-v1" ? raw : await gzipMember(raw);
+        if (encoded.byteLength > NEUTRAL_UPLOAD_MAX_ENCODED_CHUNK_BYTES)
+            throw new RangeError("neutral upload encoded chunk 超过 8 MiB");
+        const ref = Object.freeze({
+            index: refs.length,
+            raw_offset: rawLength - raw.byteLength,
+            raw_byte_length: raw.byteLength,
+            raw_sha256: options.create_sha256().update(raw).digestHex(),
+            codec,
+            encoded_byte_length: encoded.byteLength,
+            encoded_sha256: options.create_sha256().update(encoded).digestHex(),
+        });
+        await writer({ object_id: input.object_id, ref, bytes: encoded });
+        refs.push(ref);
+        pending = new Uint8Array(NEUTRAL_UPLOAD_RAW_CHUNK_BYTES);
+        pendingLength = 0;
+    };
+    for await (const value of input.bytes) {
+        if (!(value instanceof Uint8Array))
+            throw new TypeError("neutral upload source 只能产生 Uint8Array");
+        if (rawLength + value.byteLength > NEUTRAL_UPLOAD_MAX_OBJECT_BYTES)
+            throw new RangeError("neutral upload object 超过 512 MiB");
+        objectHash.update(value);
+        let offset = 0;
+        while (offset < value.byteLength) {
+            const copied = Math.min(pending.byteLength - pendingLength, value.byteLength - offset);
+            pending.set(value.subarray(offset, offset + copied), pendingLength);
+            pendingLength += copied;
+            offset += copied;
+            rawLength += copied;
+            if (pendingLength === pending.byteLength)
+                await flush();
+        }
+    }
+    await flush();
+    if (rawLength === 0)
+        throw new RangeError("neutral upload 不允许空 logical object");
+    return Object.freeze({
+        object_id: input.object_id,
+        object_kind: input.object_kind,
+        ...(input.section_key === undefined ? {} : { section_key: input.section_key }),
+        ...(input.media_type === undefined ? {} : { media_type: input.media_type }),
+        ...(input.canonical_encoding === undefined ? {} : { canonical_encoding: input.canonical_encoding }),
+        raw_byte_length: rawLength,
+        raw_sha256: objectHash.digestHex(),
+        chunks: Object.freeze(refs),
+    });
+}
+export function assertNeutralUploadPlanLimits(objects) {
+    if (objects.length === 0 || objects.length > NEUTRAL_UPLOAD_MAX_OBJECTS)
+        throw new RangeError("neutral upload plan object 数无效");
+    if (new Set(objects.map((object) => object.object_id)).size !== objects.length)
+        throw new TypeError("neutral upload object_id 重复");
+    let raw = 0;
+    let encoded = 0;
+    for (const object of objects) {
+        raw += object.raw_byte_length;
+        encoded += object.chunks.reduce((sum, chunk) => sum + chunk.encoded_byte_length, 0);
+        if (!Number.isSafeInteger(raw) || !Number.isSafeInteger(encoded) || raw > NEUTRAL_UPLOAD_MAX_PLAN_BYTES || encoded > NEUTRAL_UPLOAD_MAX_PLAN_BYTES) {
+            throw new RangeError("neutral upload plan aggregate 超过 1 GiB");
+        }
+    }
+}
+function assertDescriptor(input) {
+    for (const [field, value] of [["object_id", input.object_id], ["object_kind", input.object_kind]]) {
+        if (value.length === 0 || value !== value.trim().normalize("NFC"))
+            throw new TypeError(`${field} 无效`);
+    }
+    if (!["manifest", "revision_index", "section", "local_project_wesp", "view"].includes(input.object_kind))
+        throw new TypeError("object_kind 无效");
+    const isSection = input.object_kind === "section" || input.object_kind === "local_project_wesp" || input.object_kind === "view";
+    if (isSection !== (input.section_key !== undefined && input.media_type !== undefined && input.canonical_encoding !== undefined)) {
+        throw new TypeError("section descriptor 不闭合");
+    }
+}
+async function gzipMember(raw) {
+    const stream = new Blob([raw]).stream().pipeThrough(new CompressionStream("gzip"));
+    return new Uint8Array(await new Response(stream).arrayBuffer());
+}

package/dist/scenario-part.d.ts

@@ -0,0 +1,8 @@
+/**
+ * protobuf wire: field 1 (schema_version), varint 1。
+ * 所有 author sections 使用 protobuf 默认空值；initializer 不制造第二套 JSON authority。
+ */
+export declare const EMPTY_SCENARIO_PART_SOURCE_V1_PROTOBUF: Uint8Array;
+export declare function createEmptyScenarioPartWesp(subtle?: SubtleCrypto): Promise<Uint8Array>;
+export declare function validateScenarioPartSourceV1Protobuf(payload: Uint8Array): Uint8Array;
+export declare function decodeScenarioPartWesp(encoded: Uint8Array, subtle?: SubtleCrypto): Promise<Uint8Array>;

package/dist/scenario-part.js

@@ -0,0 +1,193 @@
+import { ProjectFormatError } from "./errors.js";
+import { decodeWesp, encodeWesp } from "./wesp.js";
+/**
+ * protobuf wire: field 1 (schema_version), varint 1。
+ * 所有 author sections 使用 protobuf 默认空值；initializer 不制造第二套 JSON authority。
+ */
+export const EMPTY_SCENARIO_PART_SOURCE_V1_PROTOBUF = new Uint8Array([0x08, 0x01]);
+export function createEmptyScenarioPartWesp(subtle) {
+    return encodeWesp(EMPTY_SCENARIO_PART_SOURCE_V1_PROTOBUF, subtle);
+}
+function protobufInvalid(message) {
+    throw new ProjectFormatError("E_SCENARIO_PROTOBUF_INVALID", message);
+}
+function readVarint(bytes, offset) {
+    let value = 0n;
+    for (let index = 0; index < 10; index += 1) {
+        const byte = bytes[offset + index];
+        if (byte === undefined)
+            protobufInvalid("protobuf varint 被截断");
+        if (index === 9 && byte > 1)
+            protobufInvalid("protobuf varint 超过 uint64");
+        value |= BigInt(byte & 0x7f) << BigInt(index * 7);
+        if ((byte & 0x80) === 0)
+            return { value, next_offset: offset + index + 1 };
+    }
+    return protobufInvalid("protobuf varint 超过 10 bytes");
+}
+function readLengthDelimited(bytes, offset) {
+    const length = readVarint(bytes, offset);
+    if (length.value > BigInt(Number.MAX_SAFE_INTEGER))
+        protobufInvalid("protobuf length 超过安全整数");
+    const end = length.next_offset + Number(length.value);
+    if (end > bytes.byteLength)
+        protobufInvalid("protobuf length-delimited field 被截断");
+    return { payload: bytes.slice(length.next_offset, end), next_offset: end };
+}
+function skipUnknownField(bytes, wireType, offset) {
+    if (wireType === 0)
+        return readVarint(bytes, offset).next_offset;
+    if (wireType === 1) {
+        if (offset + 8 > bytes.byteLength)
+            protobufInvalid("protobuf fixed64 被截断");
+        return offset + 8;
+    }
+    if (wireType === 2)
+        return readLengthDelimited(bytes, offset).next_offset;
+    if (wireType === 5) {
+        if (offset + 4 > bytes.byteLength)
+            protobufInvalid("protobuf fixed32 被截断");
+        return offset + 4;
+    }
+    return protobufInvalid(`不支持 protobuf wire_type ${wireType}`);
+}
+const UTF8_DECODER = new TextDecoder("utf-8", { fatal: true });
+function validateUtf8(payload, label) {
+    try {
+        UTF8_DECODER.decode(payload);
+    }
+    catch {
+        protobufInvalid(`${label} 不是合法 UTF-8`);
+    }
+}
+function singularFields(messageName) {
+    if (messageName === "ScenarioPartSourceV1")
+        return new Set([1, 2, 3, 4, 5, 6, 7, 8]);
+    if (messageName === "SpatialWorldSourceV1")
+        return new Set([1, 2, 3, 4]);
+    if (messageName === "SpatialTopologyV1")
+        return new Set([1, 2]);
+    if (messageName === "SpatialObjectV1")
+        return new Set([1, 2, 3, 4]);
+    return new Set([1, 2]);
+}
+function maxKnownField(messageName) {
+    if (messageName === "ScenarioPartSourceV1")
+        return 8;
+    if (messageName === "SpatialWorldSourceV1")
+        return 13;
+    if (messageName === "SpatialTopologyV1")
+        return 2;
+    if (messageName === "SpatialObjectV1")
+        return 5;
+    return 2;
+}
+function readKnownLengthDelimited(bytes, offset, wireType, label) {
+    if (wireType !== 2)
+        protobufInvalid(`${label} wire type 错误`);
+    return readLengthDelimited(bytes, offset);
+}
+function validateMessage(bytes, messageName) {
+    let offset = 0;
+    let schemaVersion;
+    const seenSingularFields = new Set();
+    const singular = singularFields(messageName);
+    while (offset < bytes.byteLength) {
+        const tag = readVarint(bytes, offset);
+        offset = tag.next_offset;
+        const fieldNumberValue = tag.value >> 3n;
+        if (fieldNumberValue > 0x1fffffffn)
+            protobufInvalid(`${messageName} field_number 超过 protobuf 上限`);
+        const fieldNumber = Number(fieldNumberValue);
+        const wireType = Number(tag.value & 0x07n);
+        if (fieldNumber === 0)
+            protobufInvalid(`${messageName} 包含 field_number 0`);
+        const known = fieldNumber <= maxKnownField(messageName);
+        if (known && singular.has(fieldNumber)) {
+            if (seenSingularFields.has(fieldNumber))
+                protobufInvalid(`${messageName} field ${fieldNumber} 重复`);
+            seenSingularFields.add(fieldNumber);
+        }
+        if (fieldNumber === 1
+            && (messageName === "ScenarioPartSourceV1" || messageName === "SpatialWorldSourceV1")) {
+            if (wireType !== 0)
+                protobufInvalid(`${messageName}.schema_version wire type 错误`);
+            const version = readVarint(bytes, offset);
+            if (version.value > 0xffffffffn)
+                protobufInvalid(`${messageName}.schema_version 超过 uint32`);
+            schemaVersion = version.value;
+            offset = version.next_offset;
+            continue;
+        }
+        if (messageName === "ScenarioPartSourceV1" && fieldNumber >= 2 && fieldNumber <= 8) {
+            const field = readKnownLengthDelimited(bytes, offset, wireType, `${messageName} field ${fieldNumber}`);
+            if (fieldNumber === 8)
+                validateMessage(field.payload, "SpatialWorldSourceV1");
+            offset = field.next_offset;
+            continue;
+        }
+        if (messageName === "SpatialWorldSourceV1" && fieldNumber >= 2 && fieldNumber <= 13) {
+            const field = readKnownLengthDelimited(bytes, offset, wireType, `${messageName} field ${fieldNumber}`);
+            if (fieldNumber === 2 || fieldNumber === 13) {
+                validateUtf8(field.payload, `${messageName} field ${fieldNumber}`);
+            }
+            else if (fieldNumber === 3) {
+                validateMessage(field.payload, "SpatialTopologyV1");
+            }
+            else if (fieldNumber >= 7 && fieldNumber <= 11) {
+                validateMessage(field.payload, "SpatialObjectV1");
+            }
+            else if (fieldNumber === 12) {
+                validateMessage(field.payload, "SpatialPresetV1");
+            }
+            offset = field.next_offset;
+            continue;
+        }
+        if (messageName === "SpatialTopologyV1" && fieldNumber >= 1 && fieldNumber <= 2) {
+            if (fieldNumber === 1) {
+                if (wireType !== 0)
+                    protobufInvalid(`${messageName}.kind wire type 错误`);
+                const kind = readVarint(bytes, offset);
+                if (kind.value > 3n)
+                    protobufInvalid(`${messageName}.kind 不受支持`);
+                offset = kind.next_offset;
+            }
+            else {
+                offset = readKnownLengthDelimited(bytes, offset, wireType, `${messageName}.settings`).next_offset;
+            }
+            continue;
+        }
+        if (messageName === "SpatialObjectV1" && fieldNumber >= 1 && fieldNumber <= 5) {
+            const field = readKnownLengthDelimited(bytes, offset, wireType, `${messageName} field ${fieldNumber}`);
+            if (fieldNumber <= 3 || fieldNumber === 5) {
+                validateUtf8(field.payload, `${messageName} field ${fieldNumber}`);
+            }
+            offset = field.next_offset;
+            continue;
+        }
+        if (messageName === "SpatialPresetV1" && fieldNumber >= 1 && fieldNumber <= 2) {
+            const field = readKnownLengthDelimited(bytes, offset, wireType, `${messageName} field ${fieldNumber}`);
+            if (fieldNumber === 1)
+                validateUtf8(field.payload, `${messageName}.preset_id`);
+            offset = field.next_offset;
+            continue;
+        }
+        offset = skipUnknownField(bytes, wireType, offset);
+    }
+    if (messageName === "ScenarioPartSourceV1" || messageName === "SpatialWorldSourceV1") {
+        if (schemaVersion === undefined)
+            protobufInvalid(`${messageName}.schema_version 缺失`);
+        if (schemaVersion === 1n)
+            return;
+        throw new ProjectFormatError("E_SCENARIO_SCHEMA_VERSION_UNSUPPORTED", `${messageName}.schema_version=${schemaVersion.toString()} 不受支持`);
+    }
+}
+export function validateScenarioPartSourceV1Protobuf(payload) {
+    if (!(payload instanceof Uint8Array))
+        throw new TypeError("ScenarioPart protobuf 必须是 Uint8Array");
+    validateMessage(payload, "ScenarioPartSourceV1");
+    return payload;
+}
+export async function decodeScenarioPartWesp(encoded, subtle) {
+    return validateScenarioPartSourceV1Protobuf(await decodeWesp(encoded, subtle));
+}

package/dist/tar.d.ts

@@ -0,0 +1,7 @@
+/** Canonical ustar file archive used by Creator and sandbox Node build workers. */
+export interface TarEntry {
+    readonly path: string;
+    readonly bytes: Uint8Array;
+}
+export declare const packTar: (entries: readonly TarEntry[]) => Uint8Array;
+export declare const unpackTar: (buf: Uint8Array) => readonly TarEntry[];

package/dist/tar.js

@@ -0,0 +1,169 @@
+const BLOCK_SIZE = 512;
+const NAME_MAX = 100;
+const PREFIX_MAX = 155;
+const USTAR_MAGIC = "ustar\0";
+const USTAR_VERSION = "00";
+const DEFAULT_MODE = "0000644";
+const TYPEFLAG_FILE = "0";
+const hasControlCharacter = (value) => [...value].some((character) => {
+    const code = character.charCodeAt(0);
+    return code < 0x20 || code === 0x7f;
+});
+const assertSafePath = (path) => {
+    if (path.length === 0 || path !== path.normalize("NFC") || path.startsWith("/")
+        || path.includes("\\") || path.includes("\0") || /^[A-Za-z]:/u.test(path)) {
+        throw new Error("tar_path_invalid");
+    }
+    for (const part of path.split("/")) {
+        if (part.length === 0 || part === "." || part === ".." || hasControlCharacter(part)) {
+            throw new Error("tar_path_invalid");
+        }
+    }
+};
+const padOctal = (value, width) => {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new Error("octal_overflow");
+    const octal = value.toString(8);
+    if (octal.length > width)
+        throw new Error("octal_overflow");
+    return octal.padStart(width, "0");
+};
+const writeString = (buf, offset, value, width) => {
+    const encoded = new TextEncoder().encode(value);
+    if (encoded.length > width)
+        throw new Error("field_too_long");
+    buf.set(encoded, offset);
+};
+const readString = (buf, offset, width) => {
+    let end = offset;
+    const limit = offset + width;
+    while (end < limit && buf[end] !== 0)
+        end += 1;
+    return new TextDecoder("utf-8", { fatal: true }).decode(buf.subarray(offset, end));
+};
+const readOctal = (buf, offset, width) => {
+    const raw = readString(buf, offset, width).trim();
+    if (raw.length === 0)
+        return 0;
+    if (!/^[0-7]+$/u.test(raw))
+        throw new Error("invalid_octal");
+    const parsed = Number.parseInt(raw, 8);
+    if (!Number.isSafeInteger(parsed))
+        throw new Error("invalid_octal");
+    return parsed;
+};
+const splitName = (path) => {
+    const encoder = new TextEncoder();
+    if (encoder.encode(path).length <= NAME_MAX)
+        return { name: path, prefix: "" };
+    for (let index = path.length - 1; index > 0; index -= 1) {
+        if (path.charCodeAt(index) !== 0x2f)
+            continue;
+        const prefix = path.slice(0, index);
+        const name = path.slice(index + 1);
+        if (encoder.encode(prefix).length <= PREFIX_MAX && encoder.encode(name).length <= NAME_MAX && name.length > 0) {
+            return { name, prefix };
+        }
+    }
+    throw new Error("path_too_long");
+};
+const computeChecksum = (header) => {
+    let sum = 0;
+    for (let index = 0; index < BLOCK_SIZE; index += 1)
+        sum += header[index] ?? 0;
+    return sum;
+};
+const buildHeader = (entry) => {
+    assertSafePath(entry.path);
+    if (!(entry.bytes instanceof Uint8Array))
+        throw new Error("tar_entry_bytes_invalid");
+    const header = new Uint8Array(BLOCK_SIZE);
+    const { name, prefix } = splitName(entry.path);
+    writeString(header, 0, name, NAME_MAX);
+    writeString(header, 100, `${DEFAULT_MODE}\0`, 8);
+    writeString(header, 108, `${padOctal(0, 7)}\0`, 8);
+    writeString(header, 116, `${padOctal(0, 7)}\0`, 8);
+    writeString(header, 124, `${padOctal(entry.bytes.length, 11)}\0`, 12);
+    writeString(header, 136, `${padOctal(0, 11)}\0`, 12);
+    header.fill(0x20, 148, 156);
+    writeString(header, 156, TYPEFLAG_FILE, 1);
+    writeString(header, 257, USTAR_MAGIC, 6);
+    writeString(header, 263, USTAR_VERSION, 2);
+    if (prefix.length > 0)
+        writeString(header, 345, prefix, PREFIX_MAX);
+    writeString(header, 148, `${computeChecksum(header).toString(8).padStart(6, "0")}\0 `, 8);
+    return header;
+};
+const isZeroBlock = (buf, offset) => {
+    for (let index = 0; index < BLOCK_SIZE; index += 1)
+        if (buf[offset + index] !== 0)
+            return false;
+    return true;
+};
+export const packTar = (entries) => {
+    const paths = new Set();
+    const parts = [];
+    let total = BLOCK_SIZE * 2;
+    for (const entry of entries) {
+        assertSafePath(entry.path);
+        if (paths.has(entry.path))
+            throw new Error("tar_path_duplicate");
+        paths.add(entry.path);
+        const header = buildHeader(entry);
+        const padding = new Uint8Array((BLOCK_SIZE - (entry.bytes.length % BLOCK_SIZE)) % BLOCK_SIZE);
+        total += header.length + entry.bytes.length + padding.length;
+        if (!Number.isSafeInteger(total))
+            throw new Error("tar_size_overflow");
+        parts.push(header, entry.bytes.slice(), padding);
+    }
+    const result = new Uint8Array(total);
+    let cursor = 0;
+    for (const part of [...parts, new Uint8Array(BLOCK_SIZE * 2)]) {
+        result.set(part, cursor);
+        cursor += part.length;
+    }
+    return result;
+};
+export const unpackTar = (buf) => {
+    if (!(buf instanceof Uint8Array) || buf.byteLength < BLOCK_SIZE * 2)
+        throw new Error("tar_truncated");
+    const entries = [];
+    const paths = new Set();
+    let offset = 0;
+    let terminated = false;
+    while (offset + BLOCK_SIZE <= buf.length) {
+        if (isZeroBlock(buf, offset)) {
+            if (offset + BLOCK_SIZE * 2 > buf.length || !isZeroBlock(buf, offset + BLOCK_SIZE))
+                throw new Error("tar_trailer_invalid");
+            terminated = true;
+            break;
+        }
+        const header = buf.subarray(offset, offset + BLOCK_SIZE);
+        const headerCopy = header.slice();
+        const storedChecksum = readOctal(headerCopy, 148, 8);
+        headerCopy.fill(0x20, 148, 156);
+        if (storedChecksum !== computeChecksum(headerCopy))
+            throw new Error("tar_checksum_invalid");
+        const name = readString(header, 0, NAME_MAX);
+        const prefix = readString(header, 345, PREFIX_MAX);
+        const path = prefix.length > 0 ? `${prefix}/${name}` : name;
+        assertSafePath(path);
+        if (paths.has(path))
+            throw new Error("tar_path_duplicate");
+        const size = readOctal(header, 124, 12);
+        const typeflag = readString(header, 156, 1) || TYPEFLAG_FILE;
+        if (typeflag !== TYPEFLAG_FILE)
+            throw new Error("tar_type_unsupported");
+        const dataStart = offset + BLOCK_SIZE;
+        const padding = (BLOCK_SIZE - (size % BLOCK_SIZE)) % BLOCK_SIZE;
+        const next = dataStart + size + padding;
+        if (!Number.isSafeInteger(next) || next > buf.length)
+            throw new Error("tar_truncated");
+        paths.add(path);
+        entries.push(Object.freeze({ path, bytes: buf.slice(dataStart, dataStart + size) }));
+        offset = next;
+    }
+    if (!terminated)
+        throw new Error("tar_trailer_missing");
+    return Object.freeze(entries);
+};

package/dist/wesp.d.ts

@@ -0,0 +1,7 @@
+export declare function encodeWesp(protobufPayload: Uint8Array, subtle?: SubtleCrypto): Promise<Uint8Array>;
+export declare function decodeWesp(encoded: Uint8Array, subtle?: SubtleCrypto): Promise<Uint8Array>;
+export declare const WESP_V1: Readonly<{
+    magic: "WESP";
+    format_version: 1;
+    header_size: number;
+}>;

package/dist/wesp.js

@@ -0,0 +1,57 @@
+import { ProjectFormatError } from "./errors.js";
+import { sha256Bytes } from "./integrity.js";
+const WESP_MAGIC = new Uint8Array([0x57, 0x45, 0x53, 0x50]);
+const WESP_FORMAT_VERSION = 1;
+const WESP_HEADER_SIZE = WESP_MAGIC.byteLength + 1 + 8 + 32;
+function hasMagic(bytes) {
+    return WESP_MAGIC.every((value, index) => bytes[index] === value);
+}
+function equalBytes(left, right) {
+    if (left.byteLength !== right.byteLength)
+        return false;
+    let difference = 0;
+    for (let index = 0; index < left.byteLength; index += 1) {
+        difference |= (left[index] ?? 0) ^ (right[index] ?? 0);
+    }
+    return difference === 0;
+}
+export async function encodeWesp(protobufPayload, subtle) {
+    if (!(protobufPayload instanceof Uint8Array)) {
+        throw new TypeError("protobufPayload 必须是 Uint8Array");
+    }
+    const encoded = new Uint8Array(WESP_HEADER_SIZE + protobufPayload.byteLength);
+    encoded.set(WESP_MAGIC, 0);
+    encoded[4] = WESP_FORMAT_VERSION;
+    new DataView(encoded.buffer, encoded.byteOffset + 5, 8).setBigUint64(0, BigInt(protobufPayload.byteLength));
+    encoded.set(await sha256Bytes(protobufPayload, subtle), 13);
+    encoded.set(protobufPayload, WESP_HEADER_SIZE);
+    return encoded;
+}
+export async function decodeWesp(encoded, subtle) {
+    if (!(encoded instanceof Uint8Array) || encoded.byteLength < WESP_HEADER_SIZE) {
+        throw new ProjectFormatError("E_WESP_SIZE_MISMATCH", "WESP header 不完整");
+    }
+    if (!hasMagic(encoded)) {
+        throw new ProjectFormatError("E_WESP_MAGIC_INVALID", "WESP magic 不匹配");
+    }
+    if (encoded[4] !== WESP_FORMAT_VERSION) {
+        throw new ProjectFormatError("E_WESP_VERSION_UNSUPPORTED", `不支持 WESP format_version ${String(encoded[4])}`);
+    }
+    const declaredSize = new DataView(encoded.buffer, encoded.byteOffset + 5, 8).getBigUint64(0);
+    const actualSize = BigInt(encoded.byteLength - WESP_HEADER_SIZE);
+    if (declaredSize !== actualSize) {
+        throw new ProjectFormatError("E_WESP_SIZE_MISMATCH", `WESP payload 长度不匹配：声明 ${declaredSize.toString()}，实际 ${actualSize.toString()}`);
+    }
+    const expectedDigest = encoded.slice(13, WESP_HEADER_SIZE);
+    const payload = encoded.slice(WESP_HEADER_SIZE);
+    const actualDigest = await sha256Bytes(payload, subtle);
+    if (!equalBytes(expectedDigest, actualDigest)) {
+        throw new ProjectFormatError("E_WESP_DIGEST_MISMATCH", "WESP payload SHA-256 不匹配");
+    }
+    return payload;
+}
+export const WESP_V1 = Object.freeze({
+    magic: "WESP",
+    format_version: WESP_FORMAT_VERSION,
+    header_size: WESP_HEADER_SIZE,
+});

package/dist/windows-executable.d.ts

@@ -0,0 +1,4 @@
+export declare class WindowsExecutableValidationError extends Error {
+}
+/** 验证 Windows x64 PE32+ 的结构边界；不依赖 Node Buffer，可由 initializer 与构建脚本共同消费。 */
+export declare function assertWindowsX64Executable(bytes: Uint8Array): void;

package/dist/windows-executable.js

@@ -0,0 +1,68 @@
+const IMAGE_FILE_MACHINE_AMD64 = 0x8664;
+const IMAGE_NT_OPTIONAL_HDR64_MAGIC = 0x20b;
+const IMAGE_SECTION_HEADER_SIZE = 40;
+const MAX_SECTION_COUNT = 96;
+export class WindowsExecutableValidationError extends Error {
+}
+function fail(message) {
+    throw new WindowsExecutableValidationError(message);
+}
+function requireRange(bytes, offset, length, label) {
+    if (!Number.isSafeInteger(offset) || !Number.isSafeInteger(length) || offset < 0 || length < 0 || offset + length > bytes.byteLength) {
+        fail(`${label} 越过 PE 文件边界`);
+    }
+}
+function asciiEquals(bytes, offset, expected) {
+    return expected.every((value, index) => bytes[offset + index] === value);
+}
+/** 验证 Windows x64 PE32+ 的结构边界；不依赖 Node Buffer，可由 initializer 与构建脚本共同消费。 */
+export function assertWindowsX64Executable(bytes) {
+    requireRange(bytes, 0, 0x40, "DOS header");
+    if (!asciiEquals(bytes, 0, [0x4d, 0x5a]))
+        fail("缺少 DOS MZ header");
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const peOffset = view.getUint32(0x3c, true);
+    if (peOffset < 0x40)
+        fail("DOS e_lfanew 不合理");
+    requireRange(bytes, peOffset, 24, "PE/COFF header");
+    if (!asciiEquals(bytes, peOffset, [0x50, 0x45, 0, 0]))
+        fail("缺少 PE\\0\\0 signature");
+    const coffOffset = peOffset + 4;
+    const machine = view.getUint16(coffOffset, true);
+    const sectionCount = view.getUint16(coffOffset + 2, true);
+    const optionalHeaderSize = view.getUint16(coffOffset + 16, true);
+    if (machine !== IMAGE_FILE_MACHINE_AMD64)
+        fail(`不是 x64 PE（Machine=0x${machine.toString(16)}）`);
+    if (sectionCount < 1 || sectionCount > MAX_SECTION_COUNT)
+        fail(`section 数量不合理: ${sectionCount}`);
+    if (optionalHeaderSize < 112)
+        fail(`x64 optional header 过短: ${optionalHeaderSize}`);
+    const optionalOffset = coffOffset + 20;
+    requireRange(bytes, optionalOffset, optionalHeaderSize, "optional header");
+    if (view.getUint16(optionalOffset, true) !== IMAGE_NT_OPTIONAL_HDR64_MAGIC)
+        fail("不是 PE32+ x64 optional header");
+    const sectionTableOffset = optionalOffset + optionalHeaderSize;
+    const sectionTableSize = sectionCount * IMAGE_SECTION_HEADER_SIZE;
+    requireRange(bytes, sectionTableOffset, sectionTableSize, "section table");
+    const sizeOfImage = view.getUint32(optionalOffset + 56, true);
+    const sizeOfHeaders = view.getUint32(optionalOffset + 60, true);
+    const numberOfRvaAndSizes = view.getUint32(optionalOffset + 108, true);
+    if (sizeOfImage < 0x1000 || sizeOfHeaders < sectionTableOffset + sectionTableSize || sizeOfHeaders > bytes.byteLength)
+        fail("optional header image/header 边界不合理");
+    if (numberOfRvaAndSizes > 16)
+        fail(`data-directory 数量不合理: ${numberOfRvaAndSizes}`);
+    let hasFileBackedSection = false;
+    for (let index = 0; index < sectionCount; index += 1) {
+        const sectionOffset = sectionTableOffset + index * IMAGE_SECTION_HEADER_SIZE;
+        const rawSize = view.getUint32(sectionOffset + 16, true);
+        const rawOffset = view.getUint32(sectionOffset + 20, true);
+        if (rawSize === 0)
+            continue;
+        if (rawOffset < sizeOfHeaders)
+            fail(`section ${index} raw data 与 PE headers 重叠`);
+        requireRange(bytes, rawOffset, rawSize, `section ${index} raw data`);
+        hasFileBackedSection = true;
+    }
+    if (!hasFileBackedSection)
+        fail("没有 file-backed section");
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@world-engines/project-format",
+  "version": "0.1.0-alpha.0",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./tar": {
+      "types": "./dist/tar.d.ts",
+      "import": "./dist/tar.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "worldengine_source_sha256": "70618ef316bd1a14b6ae3bb2ecbad26814daa3b2c41ad82cba377757d0e42924",
+  "worldengine_source_identity_provenance": {
+    "schema": "worldengine-public-namespace-projection/v1",
+    "kind": "composite-source-identity; namespace projection; not-full-source-recompile",
+    "original_name": "@worldengine/project-format",
+    "original_archive_sha256": "59259ac05463944bec2021382d98202462c7e245614a7f5a56c23b814ed989ed",
+    "original_source_sha256": "d484ac0a7b8122190d770bb42224e0c089ef9e05784744e8a8c529b2016f9c63",
+    "projected_name": "@world-engines/project-format",
+    "package_name_mapping": {
+      "@chat/blocks-editor": "@world-engines/blocks-editor",
+      "@chat/ladybug-bridge": "@world-engines/ladybug-bridge",
+      "@chat/monaco-host": "@world-engines/monaco-host",
+      "@chat/protocol-ts": "@world-engines/protocol-ts",
+      "@chat/scenario-author-source": "@world-engines/scenario-author-source",
+      "@chat/scenario-review-snapshot": "@world-engines/scenario-review-snapshot",
+      "@chat/tmw": "@world-engines/tmw",
+      "@chat/view-exposure": "@world-engines/view-exposure",
+      "@world-engines/chatplay-vite-plugin": "@world-engines/chatplay-vite-plugin",
+      "@worldengine/agent-kit": "@world-engines/agent-kit",
+      "@worldengine/authoring-bridge": "@world-engines/authoring-bridge",
+      "@worldengine/authoring-ui": "@world-engines/authoring-ui",
+      "@worldengine/create-project": "@world-engines/create-project",
+      "@worldengine/project-format": "@world-engines/project-format",
+      "@worldengine/project-host": "@world-engines/project-host",
+      "@worldengine/project-setup": "@world-engines/project-setup",
+      "@worldengine/spatial-authoring": "@world-engines/spatial-authoring",
+      "@worldengine/view-sdk": "@world-engines/view-sdk"
+    }
+  }
+}