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

package/dist/frozen-review-source-capture.js

@@ -0,0 +1,551 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { canonicalNeutralScenarioSourceBytes, canonicalScenarioSourceManifestDigestInputBytes, canonicalScenarioSourceSectionBytes, decodeNeutralScenarioSource, } from "@world-engines/scenario-author-source";
+import { TMW_RUNTIME_GENERATION } from "@world-engines/tmw";
+import { NeutralScenarioSource, ScenarioSourceManifest, ScenarioSourceSection, } from "@world-engines/protocol-ts/v1/neutral_scenario_source";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { decodeScenarioPartWesp } from "@world-engines/project-format";
+import { readFrozenReviewTargetBinding, } from "./frozen-review-local-pipeline.js";
+import { createFrozenReviewWasmEncryptor, } from "./frozen-review-wasm-encryptor.js";
+import { assertSafeExistingProjectPath } from "./safe-project-path.js";
+const SHA256 = /^[0-9a-f]{64}$/u;
+const DATABASE_KEY_PATH = "modules/database/key";
+const LOCAL_WESP_SECTION = "local_project_wesp";
+const LOCAL_WESP_MEDIA_TYPE = "application/vnd.worldengine.scenario-part+wesp";
+const LOCAL_WESP_ENCODING = "wesp-v1";
+const MAX_RAW_CHUNK_BYTES = 4 * 1024 * 1024;
+const MAX_CIPHER_CHUNK_BYTES = 8 * 1024 * 1024;
+const MAX_OBJECT_BYTES = 512 * 1024 * 1024;
+const MAX_CHUNKS = 128;
+const MAX_OBJECTS = 64;
+function fail(code, message) {
+    throw new AuthoringBridgeError(code, message);
+}
+function object(value, field) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        fail("E_VALIDATION_FAILED", `${field} 无效`);
+    return value;
+}
+function text(value, field) {
+    if (typeof value !== "string" || value.length === 0 || value !== value.trim().normalize("NFC")) {
+        fail("E_VALIDATION_FAILED", `${field} 无效`);
+    }
+    return value;
+}
+function sha(value, field) {
+    const result = text(value, field);
+    if (!SHA256.test(result))
+        fail("E_VALIDATION_FAILED", `${field} digest 无效`);
+    return result;
+}
+function positive(value, field) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0)
+        fail("E_VALIDATION_FAILED", `${field} 无效`);
+    return value;
+}
+function nonnegative(value, field) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+        fail("E_VALIDATION_FAILED", `${field} 无效`);
+    return value;
+}
+function nullableSha(value, field) {
+    return value === null ? null : sha(value, field);
+}
+function digest(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function jsonDigest(value) {
+    return digest(new TextEncoder().encode(JSON.stringify(value)));
+}
+function base64(value, field) {
+    const encoded = text(value, field);
+    if (encoded.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/u.test(encoded)
+        || encoded.slice(0, -2).includes("=")) {
+        fail("E_VALIDATION_FAILED", `${field} base64 无效`);
+    }
+    const decoded = new Uint8Array(Buffer.from(encoded, "base64"));
+    if (Buffer.from(decoded).toString("base64") !== encoded)
+        fail("E_VALIDATION_FAILED", `${field} base64 非 canonical`);
+    return decoded;
+}
+function parseHead(value, field) {
+    const row = object(value, field);
+    return Object.freeze({
+        owner_id: text(row.owner_id, `${field} owner`),
+        scenario_id: text(row.scenario_id, `${field} scenario`),
+        source_revision: positive(row.source_revision, `${field} revision`),
+        manifest_digest: sha(row.manifest_digest, `${field} manifest`),
+        source_digest: sha(row.source_digest, `${field} source`),
+        revision_digest: sha(row.revision_digest, `${field} revision`),
+        previous_head_digest: nullableSha(row.previous_head_digest, `${field} previous head`),
+        head_digest: sha(row.head_digest, `${field} head`),
+    });
+}
+function parseRevision(value) {
+    const row = object(value, "author-source revision");
+    return Object.freeze({
+        ...parseHead(row, "author-source revision"),
+        revision_size_bytes: positive(row.revision_size_bytes, "revision plaintext size"),
+        revision_ciphertext_sha256: sha(row.revision_ciphertext_sha256, "revision ciphertext"),
+        revision_ciphertext_size_bytes: positive(row.revision_ciphertext_size_bytes, "revision ciphertext size"),
+    });
+}
+function parseWitness(value) {
+    const row = object(value, "author-source object witness");
+    if (row.object_kind !== "manifest" && row.object_kind !== "revision" && row.object_kind !== "section") {
+        fail("E_VALIDATION_FAILED", "author-source object kind 无效");
+    }
+    const sectionKey = row.section_key === null ? null : text(row.section_key, "section key");
+    const mediaType = row.media_type === null ? null : text(row.media_type, "section media type");
+    const encoding = row.canonical_encoding === null ? null : text(row.canonical_encoding, "section encoding");
+    if ((row.object_kind === "section") !== (sectionKey !== null && mediaType !== null && encoding !== null)) {
+        fail("E_VALIDATION_FAILED", "author-source section witness 无效");
+    }
+    return Object.freeze({
+        object_kind: row.object_kind,
+        object_key: text(row.object_key, "object key"),
+        section_key: sectionKey,
+        media_type: mediaType,
+        canonical_encoding: encoding,
+        plaintext_size_bytes: positive(row.plaintext_size_bytes, "object plaintext size"),
+        plaintext_sha256: sha(row.plaintext_sha256, "object plaintext"),
+        ciphertext_size_bytes: positive(row.ciphertext_size_bytes, "object ciphertext size"),
+        ciphertext_sha256: sha(row.ciphertext_sha256, "object ciphertext"),
+    });
+}
+function parseReceipt(value) {
+    const row = object(value, "author-source receipt");
+    if (!Array.isArray(row.objects))
+        fail("E_VALIDATION_FAILED", "author-source receipt objects 无效");
+    return Object.freeze({
+        operation_id: text(row.operation_id, "receipt operation"),
+        request_sha256: sha(row.request_sha256, "receipt request"),
+        expected_head_digest: nullableSha(row.expected_head_digest, "receipt expected head"),
+        previous_head_digest: nullableSha(row.previous_head_digest, "receipt previous head"),
+        next_head_digest: sha(row.next_head_digest, "receipt next head"),
+        source_revision: positive(row.source_revision, "receipt source revision"),
+        manifest_digest: sha(row.manifest_digest, "receipt manifest"),
+        source_digest: sha(row.source_digest, "receipt source"),
+        revision_digest: sha(row.revision_digest, "receipt revision"),
+        revision_size_bytes: positive(row.revision_size_bytes, "receipt revision size"),
+        manifest_size_bytes: positive(row.manifest_size_bytes, "receipt manifest size"),
+        objects: Object.freeze(row.objects.map(parseWitness)),
+    });
+}
+function parseCipherObjectV2(value, field) {
+    const row = object(value, field);
+    const length = positive(row.plaintext_byte_length, `${field} plaintext length`);
+    if (length > MAX_OBJECT_BYTES || row.cipher_codec !== "scnb-v2-chunkset-v1" || !Array.isArray(row.chunks)
+        || row.chunks.length === 0 || row.chunks.length > MAX_CHUNKS) {
+        fail("E_VALIDATION_FAILED", `${field} descriptor 超限或 codec 无效`);
+    }
+    let offset = 0;
+    const chunks = row.chunks.map((candidate, index) => {
+        const chunk = object(candidate, `${field} chunk ${index}`);
+        const plaintextLength = positive(chunk.plaintext_byte_length, `${field} chunk plaintext length`);
+        const ciphertextLength = positive(chunk.ciphertext_byte_length, `${field} chunk ciphertext length`);
+        if (chunk.index !== index || chunk.plaintext_offset !== offset
+            || plaintextLength > MAX_RAW_CHUNK_BYTES || ciphertextLength > MAX_CIPHER_CHUNK_BYTES
+            || chunk.cipher_codec !== "scnb-v2-chunk-v1") {
+            fail("E_VALIDATION_FAILED", `${field} chunk identity 无效`);
+        }
+        offset += plaintextLength;
+        if (!Number.isSafeInteger(offset) || offset > MAX_OBJECT_BYTES)
+            fail("E_VALIDATION_FAILED", `${field} chunk length 溢出`);
+        return Object.freeze({
+            index,
+            plaintext_offset: nonnegative(chunk.plaintext_offset, `${field} chunk offset`),
+            plaintext_byte_length: plaintextLength,
+            plaintext_sha256: sha(chunk.plaintext_sha256, `${field} chunk plaintext`),
+            cipher_codec: "scnb-v2-chunk-v1",
+            ciphertext_byte_length: ciphertextLength,
+            ciphertext_sha256: sha(chunk.ciphertext_sha256, `${field} chunk ciphertext`),
+            object_key: text(chunk.object_key, `${field} chunk object key`),
+        });
+    });
+    if (offset !== length)
+        fail("E_VALIDATION_FAILED", `${field} chunk 总长度不匹配`);
+    return Object.freeze({
+        plaintext_byte_length: length,
+        plaintext_sha256: sha(row.plaintext_sha256, `${field} plaintext`),
+        cipher_codec: "scnb-v2-chunkset-v1",
+        chunks: Object.freeze(chunks),
+    });
+}
+function parseRevisionIndexV2(value) {
+    const row = object(value, "revision index v2");
+    if (row.revision_index_version !== 2 || !Array.isArray(row.sections) || row.sections.length === 0 || row.sections.length + 1 > MAX_OBJECTS) {
+        fail("E_VALIDATION_FAILED", "revision index v2 schema 无效");
+    }
+    const keys = new Set();
+    const sections = row.sections.map((candidate, index) => {
+        const section = object(candidate, `revision index section ${index}`);
+        const sectionKey = text(section.section_key, `revision index section ${index} key`);
+        if (keys.has(sectionKey))
+            fail("E_VALIDATION_FAILED", "revision index section key 重复");
+        keys.add(sectionKey);
+        return Object.freeze({
+            section_key: sectionKey,
+            media_type: text(section.media_type, `revision index section ${index} media type`),
+            canonical_encoding: text(section.canonical_encoding, `revision index section ${index} encoding`),
+            object: parseCipherObjectV2(section.object, `revision index section ${sectionKey}`),
+        });
+    });
+    return Object.freeze({
+        revision_index_version: 2,
+        owner_id: text(row.owner_id, "revision index owner"),
+        scenario_id: text(row.scenario_id, "revision index scenario"),
+        source_revision: positive(row.source_revision, "revision index source revision"),
+        manifest_digest: sha(row.manifest_digest, "revision index manifest"),
+        source_digest: sha(row.source_digest, "revision index source"),
+        source_size_bytes: positive(row.source_size_bytes, "revision index source size"),
+        previous_head_digest: nullableSha(row.previous_head_digest, "revision index previous head"),
+        manifest: parseCipherObjectV2(row.manifest, "revision index manifest"),
+        sections: Object.freeze(sections),
+    });
+}
+function parseReceiptV2(value) {
+    const row = object(value, "author-source receipt v2");
+    if (!Array.isArray(row.objects) || row.objects.length === 0 || row.objects.length > MAX_OBJECTS) {
+        fail("E_VALIDATION_FAILED", "author-source receipt v2 objects 无效");
+    }
+    return Object.freeze({
+        operation_id: text(row.operation_id, "receipt operation"),
+        request_sha256: sha(row.request_sha256, "receipt request"),
+        expected_head_digest: nullableSha(row.expected_head_digest, "receipt expected head"),
+        previous_head_digest: nullableSha(row.previous_head_digest, "receipt previous head"),
+        next_head_digest: sha(row.next_head_digest, "receipt next head"),
+        source_revision: positive(row.source_revision, "receipt source revision"),
+        manifest_digest: sha(row.manifest_digest, "receipt manifest"),
+        source_digest: sha(row.source_digest, "receipt source"),
+        revision_digest: sha(row.revision_digest, "receipt revision"),
+        source_size_bytes: positive(row.source_size_bytes, "receipt source size"),
+        objects: Object.freeze([...row.objects]),
+    });
+}
+function receiptObjectIdV2(receipt, kind, sectionKey) {
+    const matches = receipt.objects.map((value) => object(value, "receipt v2 object")).filter((value) => value.object_kind === kind && (kind === "manifest" ? value.section_key === undefined || value.section_key === null : value.section_key === sectionKey));
+    if (matches.length !== 1)
+        fail("E_VALIDATION_FAILED", `receipt v2 ${kind} object 不唯一`);
+    return text(matches[0].object_id, `receipt v2 ${kind} object id`);
+}
+function sameHead(left, right) {
+    return left.owner_id === right.owner_id
+        && left.scenario_id === right.scenario_id
+        && left.source_revision === right.source_revision
+        && left.manifest_digest === right.manifest_digest
+        && left.source_digest === right.source_digest
+        && left.revision_digest === right.revision_digest
+        && left.previous_head_digest === right.previous_head_digest
+        && left.head_digest === right.head_digest;
+}
+function uniqueWitness(receipt, kind, sectionKey) {
+    const matches = receipt.objects.filter((item) => item.object_kind === kind && item.section_key === sectionKey);
+    if (matches.length !== 1)
+        fail("E_VALIDATION_FAILED", `author-source ${kind} witness 不唯一`);
+    return matches[0];
+}
+async function decryptVerified(crypto, key, ciphertext, witness) {
+    if (ciphertext.byteLength !== witness.ciphertext_size_bytes || digest(ciphertext) !== witness.ciphertext_sha256) {
+        fail("E_OPERATION_ID_CONFLICT", "author-source ciphertext readback 不匹配");
+    }
+    let plaintext;
+    try {
+        plaintext = await crypto.decrypt(key, ciphertext);
+    }
+    catch {
+        return fail("E_AUTH_REQUIRED", "author-source scenario key 无法解密 readback");
+    }
+    if (plaintext.byteLength !== witness.plaintext_size_bytes || digest(plaintext) !== witness.plaintext_sha256) {
+        fail("E_OPERATION_ID_CONFLICT", "author-source plaintext readback 不匹配");
+    }
+    return plaintext;
+}
+function requireSuccess(response, field) {
+    if (response.status === 401 || response.status === 403)
+        fail("E_AUTH_REQUIRED", `${field} 未获授权`);
+    if (response.status < 200 || response.status >= 300)
+        fail("E_VALIDATION_FAILED", `${field} 失败：HTTP ${response.status}`);
+    return response.body;
+}
+async function readCipherObjectV2(transport, projectId, scenario, revisionDigest, kind, objectId, descriptor, crypto, key) {
+    const result = new Uint8Array(descriptor.plaintext_byte_length);
+    const objectHash = createHash("sha256");
+    for (const chunk of descriptor.chunks) {
+        const query = new URLSearchParams({
+            revision_digest: revisionDigest,
+            ciphertext_sha256: chunk.ciphertext_sha256,
+            ciphertext_size_bytes: String(chunk.ciphertext_byte_length),
+        });
+        const path = `/v1/scenarios/${scenario}/author-source/objects/${kind}/${encodeURIComponent(objectId)}/chunks/${chunk.index}?${query.toString()}`;
+        const response = await transport.request({ project_id: projectId, method: "GET", path });
+        requireSuccess(response, "author-source chunk readback");
+        const wire = object(response.body, "author-source chunk readback");
+        const ciphertext = base64(wire.contentBase64, "author-source chunk ciphertext");
+        if (ciphertext.byteLength !== chunk.ciphertext_byte_length || digest(ciphertext) !== chunk.ciphertext_sha256
+            || response.readback?.byte_length !== chunk.ciphertext_byte_length
+            || response.readback.sha256 !== chunk.ciphertext_sha256) {
+            fail("E_OPERATION_ID_CONFLICT", "author-source chunk ciphertext readback 不匹配");
+        }
+        let plaintext;
+        try {
+            plaintext = await crypto.decrypt(key, ciphertext);
+        }
+        catch {
+            return fail("E_AUTH_REQUIRED", "author-source chunk scenario key 无法解密");
+        }
+        if (plaintext.byteLength !== chunk.plaintext_byte_length || digest(plaintext) !== chunk.plaintext_sha256) {
+            fail("E_OPERATION_ID_CONFLICT", "author-source chunk plaintext readback 不匹配");
+        }
+        result.set(plaintext, chunk.plaintext_offset);
+        objectHash.update(plaintext);
+    }
+    if (objectHash.digest("hex") !== descriptor.plaintext_sha256) {
+        fail("E_OPERATION_ID_CONFLICT", "author-source logical object digest 不匹配");
+    }
+    return result;
+}
+async function readRevisionV2(sourceBody, input) {
+    const head = parseHead(sourceBody.head, "author-source head");
+    const revision = object(sourceBody.revision, "author-source revision v2");
+    const receipt = parseReceiptV2(sourceBody.receipt);
+    const index = parseRevisionIndexV2(sourceBody.revision_index);
+    if (head.scenario_id !== input.target_scenario_id || head.source_digest !== input.target_source_digest
+        || head.head_digest !== input.target_head_digest || revision.storage_version !== 2
+        || index.owner_id !== head.owner_id || index.scenario_id !== head.scenario_id
+        || index.source_revision !== head.source_revision || index.manifest_digest !== head.manifest_digest
+        || index.source_digest !== head.source_digest || index.previous_head_digest !== head.previous_head_digest
+        || receipt.next_head_digest !== head.head_digest || receipt.source_revision !== head.source_revision
+        || receipt.manifest_digest !== head.manifest_digest || receipt.source_digest !== head.source_digest
+        || receipt.revision_digest !== head.revision_digest || receipt.previous_head_digest !== head.previous_head_digest
+        || receipt.source_size_bytes !== index.source_size_bytes) {
+        fail("E_OPERATION_ID_CONFLICT", "author-source v2 index/receipt 与 upload binding 不匹配");
+    }
+    const expectedRevisionDigest = jsonDigest({ owner_id: head.owner_id, scenario_id: head.scenario_id, source_revision: head.source_revision, manifest_digest: head.manifest_digest, source_digest: head.source_digest, previous_head_digest: head.previous_head_digest });
+    const expectedHeadDigest = jsonDigest({ owner_id: head.owner_id, scenario_id: head.scenario_id, source_revision: head.source_revision, manifest_digest: head.manifest_digest, source_digest: head.source_digest, revision_digest: head.revision_digest, previous_head_digest: head.previous_head_digest });
+    if (expectedRevisionDigest !== head.revision_digest || expectedHeadDigest !== head.head_digest)
+        fail("E_OPERATION_ID_CONFLICT", "author-source v2 identity digest 不匹配");
+    const manifestBytes = await readCipherObjectV2(input.transport, input.project_id, input.scenario, head.revision_digest, "manifest", receiptObjectIdV2(receipt, "manifest", null), index.manifest, input.crypto, input.key);
+    let manifest;
+    try {
+        manifest = ScenarioSourceManifest.decode(manifestBytes);
+    }
+    catch {
+        return fail("E_VALIDATION_FAILED", "author-source v2 manifest protobuf 无效");
+    }
+    if (digest(canonicalScenarioSourceManifestDigestInputBytes(manifest)) !== head.manifest_digest)
+        fail("E_OPERATION_ID_CONFLICT", "author-source v2 manifest digest 不匹配");
+    const manifestIdentities = new Map(manifest.sections.map((section) => [section.section_key, section]));
+    if (manifest.scenario_id !== head.scenario_id || manifestIdentities.size !== index.sections.length)
+        fail("E_OPERATION_ID_CONFLICT", "author-source v2 manifest sections 不闭合");
+    const sectionBytes = [];
+    for (const sectionRef of index.sections) {
+        const bytes = await readCipherObjectV2(input.transport, input.project_id, input.scenario, head.revision_digest, "section", receiptObjectIdV2(receipt, "section", sectionRef.section_key), sectionRef.object, input.crypto, input.key);
+        let section;
+        try {
+            section = ScenarioSourceSection.decode(bytes);
+        }
+        catch {
+            return fail("E_VALIDATION_FAILED", `author-source v2 section protobuf 无效：${sectionRef.section_key}`);
+        }
+        const identity = manifestIdentities.get(sectionRef.section_key);
+        if (section.section_key !== sectionRef.section_key || section.media_type !== sectionRef.media_type
+            || section.canonical_encoding !== sectionRef.canonical_encoding || identity === undefined
+            || identity.media_type !== sectionRef.media_type || identity.canonical_encoding !== sectionRef.canonical_encoding
+            || Number(identity.byte_length) !== bytes.byteLength || Buffer.from(identity.sha256).toString("hex") !== digest(bytes)) {
+            fail("E_OPERATION_ID_CONFLICT", `author-source v2 section identity 不匹配：${sectionRef.section_key}`);
+        }
+        sectionBytes.push(bytes);
+    }
+    const source = NeutralScenarioSource.fromPartial({
+        source_schema_version: 1,
+        scenario_id: head.scenario_id,
+        manifest,
+        sections: sectionBytes.map((bytes) => ScenarioSourceSection.decode(bytes)),
+    });
+    const revisionBytes = canonicalNeutralScenarioSourceBytes(source);
+    if (revisionBytes.byteLength !== index.source_size_bytes || digest(revisionBytes) !== head.source_digest) {
+        fail("E_OPERATION_ID_CONFLICT", "author-source v2 canonical source digest 不匹配");
+    }
+    return Object.freeze({ head, revision_bytes: revisionBytes });
+}
+/**
+ * 为 standalone Node review 提供真实 read_source_ready。所有远端读取都经过 project-bound
+ * ProjectAuth transport；返回值只含已解密并逐 digest 校验的 canonical Neutral revision。
+ */
+export function createFrozenReviewSourceCapture(options) {
+    return async () => {
+        const transport = options.transport;
+        if (transport === undefined)
+            fail("E_AUTH_REQUIRED", "Node review 没有 ProjectAuthBroker 受控 transport");
+        const target = await readFrozenReviewTargetBinding(options.project_root, options.project_id);
+        const scenario = encodeURIComponent(target.scenario_id);
+        const localPath = join(options.project_root, "scenario", "source.wes");
+        const localWesp = new Uint8Array(await readFile(await assertSafeExistingProjectPath(options.project_root, localPath)));
+        await decodeScenarioPartWesp(localWesp);
+        const [epochResponse, sourceResponse, keyResponse] = await Promise.all([
+            transport.request({ project_id: options.project_id, method: "GET", path: "/v1/system/content-epoch" }),
+            transport.request({ project_id: options.project_id, method: "GET", path: `/v1/scenarios/${scenario}/author-source` }),
+            transport.request({ project_id: options.project_id, method: "GET", path: `/v1/scenarios/${scenario}/${DATABASE_KEY_PATH}` }),
+        ]);
+        const epochBody = object(requireSuccess(epochResponse, "content epoch readback"), "content epoch readback");
+        const contentEpoch = positive(epochBody.epoch, "content epoch");
+        if (epochBody.phase !== "active" || epochBody.runtime_generation !== TMW_RUNTIME_GENERATION) {
+            fail("E_VALIDATION_FAILED", "content epoch 当前不可用于 review");
+        }
+        const keyBody = object(requireSuccess(keyResponse, "scenario key readback"), "scenario key readback");
+        const key = text(keyBody.key_b64, "scenario key");
+        const derivation = object(keyBody.derivation, "scenario key derivation");
+        const keyMaxBytes = positive(keyBody.max_bytes, "scenario key max bytes");
+        if (derivation.algo !== "HKDF-SHA256" || derivation.info_v !== 1
+            || positive(keyBody.ttl_seconds, "scenario key ttl") < 1) {
+            fail("E_VALIDATION_FAILED", "scenario key derivation contract 不匹配");
+        }
+        const sourceBody = object(requireSuccess(sourceResponse, "author-source readback"), "author-source readback");
+        if (sourceBody.storage_version === 2) {
+            const crypto = options.crypto ?? createFrozenReviewWasmEncryptor();
+            const v2 = await readRevisionV2(sourceBody, {
+                transport,
+                project_id: options.project_id,
+                scenario,
+                target_scenario_id: target.scenario_id,
+                target_source_digest: target.source_digest,
+                target_head_digest: target.source_head_digest,
+                crypto,
+                key,
+            });
+            const decoded = await decodeNeutralScenarioSource(v2.revision_bytes);
+            const localSection = decoded.sections.find((section) => section.section_key === LOCAL_WESP_SECTION);
+            if (localSection === undefined || localSection.media_type !== LOCAL_WESP_MEDIA_TYPE
+                || localSection.canonical_encoding !== LOCAL_WESP_ENCODING
+                || !Buffer.from(localSection.payload).equals(Buffer.from(localWesp))) {
+                fail("E_OPERATION_ID_CONFLICT", "远端 canonical Neutral revision 未绑定当前本地 WESP upload");
+            }
+            return Object.freeze({ target, content_epoch: contentEpoch, head: Object.freeze({ ...v2.head }), revision_bytes: v2.revision_bytes.slice() });
+        }
+        if (sourceBody.storage_version !== undefined && sourceBody.storage_version !== 1)
+            fail("E_VALIDATION_FAILED", "author-source storage version 不支持");
+        const head = parseHead(sourceBody.head, "author-source head");
+        const revision = parseRevision(sourceBody.revision);
+        const receipt = parseReceipt(sourceBody.receipt);
+        const manifestCiphertext = base64(sourceBody.manifest_ciphertext_base64, "manifest ciphertext");
+        const revisionCiphertext = base64(sourceBody.revision_ciphertext_base64, "revision ciphertext");
+        const manifestWitness = uniqueWitness(receipt, "manifest", null);
+        const revisionWitness = uniqueWitness(receipt, "revision", null);
+        if (!sameHead(head, revision)
+            || head.scenario_id !== target.scenario_id
+            || head.source_digest !== target.source_digest
+            || head.head_digest !== target.source_head_digest
+            || receipt.next_head_digest !== head.head_digest
+            || receipt.source_revision !== head.source_revision
+            || receipt.previous_head_digest !== head.previous_head_digest
+            || receipt.manifest_digest !== head.manifest_digest
+            || receipt.source_digest !== head.source_digest
+            || receipt.revision_digest !== head.revision_digest
+            || receipt.revision_size_bytes !== revision.revision_size_bytes
+            || revision.revision_ciphertext_sha256 !== revisionWitness.ciphertext_sha256
+            || revision.revision_ciphertext_size_bytes !== revisionWitness.ciphertext_size_bytes) {
+            fail("E_OPERATION_ID_CONFLICT", "author-source head/revision/receipt 与 upload binding 不匹配");
+        }
+        if (manifestWitness.plaintext_size_bytes > keyMaxBytes
+            || revisionWitness.plaintext_size_bytes > keyMaxBytes
+            || receipt.objects.some((item) => item.plaintext_size_bytes > keyMaxBytes)) {
+            fail("E_VALIDATION_FAILED", "author-source object 超过 scenario key max_bytes");
+        }
+        const expectedRevisionDigest = jsonDigest({
+            owner_id: head.owner_id,
+            scenario_id: head.scenario_id,
+            source_revision: head.source_revision,
+            manifest_digest: head.manifest_digest,
+            source_digest: head.source_digest,
+            previous_head_digest: head.previous_head_digest,
+        });
+        const expectedHeadDigest = jsonDigest({
+            owner_id: head.owner_id,
+            scenario_id: head.scenario_id,
+            source_revision: head.source_revision,
+            manifest_digest: head.manifest_digest,
+            source_digest: head.source_digest,
+            revision_digest: head.revision_digest,
+            previous_head_digest: head.previous_head_digest,
+        });
+        if (expectedRevisionDigest !== head.revision_digest || expectedHeadDigest !== head.head_digest) {
+            fail("E_OPERATION_ID_CONFLICT", "author-source revision/head identity digest 不匹配");
+        }
+        const expectedRequestDigest = jsonDigest({
+            owner_id: head.owner_id,
+            scenario_id: head.scenario_id,
+            operation_id: receipt.operation_id,
+            expected_head_digest: receipt.expected_head_digest,
+            source_revision: head.source_revision,
+            previous_head_digest: head.previous_head_digest,
+            manifest_digest: head.manifest_digest,
+            source_digest: head.source_digest,
+            revision_digest: head.revision_digest,
+            revision_size_bytes: receipt.revision_size_bytes,
+            manifest_size_bytes: receipt.manifest_size_bytes,
+            objects: receipt.objects,
+        });
+        if (expectedRequestDigest !== receipt.request_sha256) {
+            fail("E_OPERATION_ID_CONFLICT", "author-source request receipt digest 不匹配");
+        }
+        const crypto = options.crypto ?? createFrozenReviewWasmEncryptor();
+        const [manifestBytes, revisionBytes] = await Promise.all([
+            decryptVerified(crypto, key, manifestCiphertext, manifestWitness),
+            decryptVerified(crypto, key, revisionCiphertext, revisionWitness),
+        ]);
+        if (manifestBytes.byteLength !== receipt.manifest_size_bytes
+            || revisionBytes.byteLength !== receipt.revision_size_bytes
+            || digest(manifestBytes) !== head.manifest_digest
+            || digest(revisionBytes) !== head.source_digest) {
+            fail("E_OPERATION_ID_CONFLICT", "author-source manifest/revision digest 不匹配");
+        }
+        const source = await decodeNeutralScenarioSource(revisionBytes);
+        if (source.scenario_id !== target.scenario_id
+            || !Buffer.from(canonicalNeutralScenarioSourceBytes(source)).equals(Buffer.from(revisionBytes))
+            || source.manifest === undefined
+            || !Buffer.from(canonicalScenarioSourceManifestDigestInputBytes(source.manifest)).equals(Buffer.from(manifestBytes))) {
+            fail("E_OPERATION_ID_CONFLICT", "author-source canonical Neutral revision 不匹配");
+        }
+        for (const section of source.sections) {
+            const witness = uniqueWitness(receipt, "section", section.section_key);
+            if (witness.media_type !== section.media_type || witness.canonical_encoding !== section.canonical_encoding) {
+                fail("E_OPERATION_ID_CONFLICT", `author-source section witness 不匹配：${section.section_key}`);
+            }
+            const query = new URLSearchParams({
+                section_key: section.section_key,
+                ciphertext_sha256: witness.ciphertext_sha256,
+                ciphertext_size_bytes: String(witness.ciphertext_size_bytes),
+            });
+            const response = await transport.request({
+                project_id: options.project_id,
+                method: "GET",
+                path: `/v1/scenarios/${scenario}/author-source?${query.toString()}`,
+            });
+            const body = object(requireSuccess(response, "author-source section readback"), "author-source section readback");
+            if (body.section_key !== section.section_key
+                || body.ciphertext_sha256 !== witness.ciphertext_sha256
+                || body.ciphertext_size_bytes !== witness.ciphertext_size_bytes) {
+                fail("E_OPERATION_ID_CONFLICT", `author-source section ciphertext identity 不匹配：${section.section_key}`);
+            }
+            const plaintext = await decryptVerified(crypto, key, base64(body.ciphertext_base64, "section ciphertext"), witness);
+            if (!Buffer.from(plaintext).equals(Buffer.from(canonicalScenarioSourceSectionBytes(section)))) {
+                fail("E_OPERATION_ID_CONFLICT", `author-source section plaintext 不匹配：${section.section_key}`);
+            }
+        }
+        const localSection = source.sections.find((section) => section.section_key === LOCAL_WESP_SECTION);
+        if (localSection === undefined
+            || localSection.media_type !== LOCAL_WESP_MEDIA_TYPE
+            || localSection.canonical_encoding !== LOCAL_WESP_ENCODING
+            || !Buffer.from(localSection.payload).equals(Buffer.from(localWesp))) {
+            fail("E_OPERATION_ID_CONFLICT", "远端 canonical Neutral revision 未绑定当前本地 WESP upload");
+        }
+        return Object.freeze({
+            target,
+            content_epoch: contentEpoch,
+            head: Object.freeze({ ...head }),
+            revision_bytes: revisionBytes.slice(),
+        });
+    };
+}

package/dist/frozen-review-wasm-encryptor.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Node 提审侧的 SCNB 加密薄适配器。密钥只作为参数交给 Rust/WASM 权威实现；
+ * 本模块不读取环境密钥，也不提供 JS 加密回退。
+ */
+export function createFrozenReviewWasmEncryptor(assets?: Readonly<{
+    glue_url: URL;
+    wasm_url: URL;
+}>): Readonly<{
+    pack(input: any): Promise<Readonly<{
+        codec: "frozen-database-v1";
+        vector_dtype: "f32-le" | "f64-le";
+        bytes: Uint8Array;
+    }>>;
+    encrypt(key_b64: any, plaintext: any): Promise<any>;
+    decrypt(key_b64: any, ciphertext: any): Promise<any>;
+}>;

package/dist/frozen-review-wasm-encryptor.js

@@ -0,0 +1,72 @@
+import { readFile } from "node:fs/promises";
+const initializationByGlue = new Map();
+function packagedAssets() {
+    return Object.freeze({
+        glue_url: new URL("./vendor/wasm-core/wasm_core.js", import.meta.url),
+        wasm_url: new URL("./vendor/wasm-core/wasm_core_bg.wasm", import.meta.url),
+    });
+}
+async function initialize(assets) {
+    const identity = assets.glue_url.href;
+    const current = initializationByGlue.get(identity);
+    if (current !== undefined) {
+        if (current.wasm_url !== assets.wasm_url.href) {
+            throw new Error("同一 WASM glue 不能绑定不同 wasm 资产");
+        }
+        return await current.promise;
+    }
+    const pending = (async () => {
+        const [glue, wasmBytes] = await Promise.all([
+            import(assets.glue_url.href),
+            readFile(assets.wasm_url),
+        ]);
+        glue.initSync({ module: wasmBytes });
+        return Object.freeze({
+            encrypt: glue.ext_encrypt_scenario_bytes,
+            decrypt: glue.ext_decrypt_scenario_bytes,
+            pack: glue.ext_pack_frozen_database_v1,
+            packValues: glue.ext_pack_frozen_database_values_v1,
+        });
+    })();
+    const initialization = Object.freeze({ wasm_url: assets.wasm_url.href, promise: pending });
+    initializationByGlue.set(identity, initialization);
+    try {
+        return await pending;
+    }
+    catch (error) {
+        if (initializationByGlue.get(identity) === initialization) {
+            initializationByGlue.delete(identity);
+        }
+        throw error;
+    }
+}
+/**
+ * Node 提审侧的 SCNB 加密薄适配器。密钥只作为参数交给 Rust/WASM 权威实现；
+ * 本模块不读取环境密钥，也不提供 JS 加密回退。
+ */
+export function createFrozenReviewWasmEncryptor(assets = packagedAssets()) {
+    const frozenAssets = Object.freeze({
+        glue_url: new URL(assets.glue_url.href),
+        wasm_url: new URL(assets.wasm_url.href),
+    });
+    return Object.freeze({
+        async pack(input) {
+            const [dtype, bytes] = (await initialize(frozenAssets)).packValues(input.graph_v5_json, input.embedding_index_v1_json, input.vector_values, input.sidecar_v5_json);
+            if ((dtype !== 1 && dtype !== 2) || !(bytes instanceof Uint8Array) || bytes.byteLength === 0) {
+                throw new Error("frozen_database_pack_result_invalid");
+            }
+            return Object.freeze({
+                codec: "frozen-database-v1",
+                vector_dtype: dtype === 1 ? "f32-le" : "f64-le",
+                bytes,
+            });
+        },
+        async encrypt(key_b64, plaintext) {
+            return (await initialize(frozenAssets)).encrypt(key_b64, plaintext);
+        },
+        async decrypt(key_b64, ciphertext) {
+            return (await initialize(frozenAssets)).decrypt(key_b64, ciphertext);
+        },
+    });
+}
+