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

package/dist/frozen-review.js

@@ -0,0 +1,802 @@
+import { createHash, randomUUID } from "node:crypto";
+import { link, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { artifactV5ManifestSha256, buildFrozenArtifactBundle, buildFrozenArtifactObjectKey, canonicalArtifactV5Bytes, publishOperationKey, } from "@world-engines/scenario-review-snapshot";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { ensureSafeProjectDirectory, safeProjectPath } from "./safe-project-path.js";
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+const SHA256_PATTERN = /^[0-9a-f]{64}$/u;
+const EMBEDDING_INDEX_PATH = "__derived__/embedding-index-v1.json";
+export const FROZEN_REVIEW_SUBMIT_STREAM_CONTENT_TYPE = 'application/x-ndjson; profile="chat-artifact-v5-submit-stream-v1"';
+const FROZEN_REVIEW_SUBMIT_STREAM_CHUNK_BYTES = 64 * 1024;
+const FROZEN_REVIEW_SUBMIT_STREAM_MAX_PAYLOAD_BYTES = 65 * 1024 * 1024;
+export function serializeFrozenReviewSubmitStream(request) {
+    const decode = (encoded) => new Uint8Array(Buffer.from(encoded, "base64"));
+    const manifest = decode(request.bundle.artifact_manifest_base64);
+    const entries = [
+        {
+            kind: "artifact_manifest",
+            relative_path: "artifact-v5.json",
+            media_type: "application/json",
+            encoding: "bytes",
+            size_bytes: manifest.byteLength,
+            sha256: request.bundle.artifact_manifest_sha256,
+            bytes: manifest,
+        },
+        ...request.bundle.objects.map((object) => ({
+            kind: object.kind,
+            relative_path: object.relative_path,
+            media_type: object.media_type,
+            encoding: object.encoding,
+            size_bytes: object.size_bytes,
+            sha256: object.sha256,
+            bytes: decode(object.bytes_base64),
+        })),
+    ];
+    if (entries.length !== 10 || entries.filter((entry) => entry.kind === "database").length !== 1) {
+        fail("E_VALIDATION_FAILED", "review submit stream 必须包含 manifest 与九个唯一 artifact objects");
+    }
+    const kinds = new Set();
+    const paths = new Set();
+    for (const entry of entries) {
+        if (kinds.has(entry.kind) || paths.has(entry.relative_path)) {
+            fail("E_VALIDATION_FAILED", "review submit stream entry kind/path 重复");
+        }
+        kinds.add(entry.kind);
+        paths.add(entry.relative_path);
+        if (entry.bytes.byteLength !== entry.size_bytes || sha256(entry.bytes) !== entry.sha256) {
+            fail("E_VALIDATION_FAILED", "review submit stream entry identity 不匹配");
+        }
+        if (entry.kind !== "database" && entry.size_bytes > 16 * 1024) {
+            fail("E_VALIDATION_FAILED", "review submit stream metadata entry 超过 16 KiB hard cap");
+        }
+    }
+    const totalPayloadBytes = entries.reduce((total, entry) => total + entry.size_bytes, 0);
+    if (!Number.isSafeInteger(totalPayloadBytes) || totalPayloadBytes <= 0
+        || totalPayloadBytes > FROZEN_REVIEW_SUBMIT_STREAM_MAX_PAYLOAD_BYTES) {
+        fail("E_VALIDATION_FAILED", "review submit stream payload 超过 65 MiB hard cap");
+    }
+    const descriptors = entries.map(({ bytes: _bytes, ...entry }) => Object.freeze({
+        ...entry,
+        chunk_count: Math.ceil(entry.size_bytes / FROZEN_REVIEW_SUBMIT_STREAM_CHUNK_BYTES),
+    }));
+    const totalChunks = descriptors.reduce((total, entry) => total + entry.chunk_count, 0);
+    if (totalChunks <= 0 || totalChunks > 8_192)
+        fail("E_VALIDATION_FAILED", "review submit stream chunk budget 无效");
+    const frames = [];
+    const frame = (value) => { frames.push(Buffer.from(`${JSON.stringify(value)}\n`, "utf8")); };
+    const header = {
+        type: "header",
+        wire_version: 1,
+        review_database_mode: "decrypt_delivery",
+        operation_key: request.operation_key,
+        review_note: request.review_note,
+        release_at: request.release_at,
+        artifact: request.bundle.artifact,
+        artifact_manifest_sha256: request.bundle.artifact_manifest_sha256,
+        chunk_size_bytes: FROZEN_REVIEW_SUBMIT_STREAM_CHUNK_BYTES,
+        total_payload_bytes: totalPayloadBytes,
+        total_chunks: totalChunks,
+        entries: descriptors,
+    };
+    const headerBytes = Buffer.from(`${JSON.stringify(header)}\n`, "utf8");
+    if (headerBytes.byteLength > 32 * 1024)
+        fail("E_VALIDATION_FAILED", "review submit stream header 超过 32 KiB hard cap");
+    frames.push(headerBytes);
+    const payloadHasher = createHash("sha256");
+    let sequence = 0;
+    entries.forEach((entry, entryIndex) => {
+        payloadHasher.update(entry.bytes);
+        for (let entryOffset = 0; entryOffset < entry.bytes.byteLength; entryOffset += FROZEN_REVIEW_SUBMIT_STREAM_CHUNK_BYTES) {
+            const chunk = entry.bytes.subarray(entryOffset, entryOffset + FROZEN_REVIEW_SUBMIT_STREAM_CHUNK_BYTES);
+            frame({
+                type: "chunk", wire_version: 1, sequence, entry_index: entryIndex,
+                entry_offset: entryOffset, byte_length: chunk.byteLength,
+                sha256: sha256(chunk), bytes_base64: Buffer.from(chunk).toString("base64"),
+            });
+            sequence += 1;
+        }
+    });
+    frame({
+        type: "terminal",
+        wire_version: 1,
+        operation_key: request.operation_key,
+        artifact_canonical_digest: request.bundle.artifact.canonical_digest,
+        total_payload_bytes: totalPayloadBytes,
+        total_chunks: totalChunks,
+        payload_sha256: payloadHasher.digest("hex"),
+    });
+    const bytes = new Uint8Array(Buffer.concat(frames));
+    if (bytes.byteLength > 96 * 1024 * 1024)
+        fail("E_VALIDATION_FAILED", "review submit HTTP body 超过 96 MiB hard cap");
+    return Object.freeze({
+        content_type: FROZEN_REVIEW_SUBMIT_STREAM_CONTENT_TYPE,
+        bytes,
+        sha256: sha256(bytes),
+        byte_length: bytes.byteLength,
+    });
+}
+function fail(code, message) {
+    throw new AuthoringBridgeError(code, message);
+}
+function requireUuid(value, field) {
+    if (!UUID_PATTERN.test(value))
+        fail("E_SCHEMA_INVALID", `${field} 必须是 UUID`);
+    return value;
+}
+function requireSha(value, field) {
+    if (typeof value !== "string" || !SHA256_PATTERN.test(value)) {
+        fail("E_VALIDATION_FAILED", `${field} digest 无效`);
+    }
+    return value;
+}
+function requirePositiveInteger(value, field) {
+    if (value === undefined)
+        return null;
+    if (!Number.isSafeInteger(value) || value <= 0)
+        fail("E_SCHEMA_INVALID", `${field} 必须是正整数`);
+    return value;
+}
+function requireReviewNote(value) {
+    if (value === undefined)
+        return null;
+    if (value.length === 0 || value !== value.trim())
+        fail("E_SCHEMA_INVALID", "review_note 无效");
+    return value;
+}
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function record(value, field) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        fail("E_OPERATION_UNCERTAIN", `${field} schema 无效`);
+    }
+    return value;
+}
+function exactKeys(value, expected, field) {
+    const actual = Object.keys(value).sort();
+    const wanted = [...expected].sort();
+    if (actual.length !== wanted.length || actual.some((key, index) => key !== wanted[index])) {
+        fail("E_OPERATION_UNCERTAIN", `${field} fields 不匹配`);
+    }
+}
+function requireInteger(value, field, positive = false) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || (positive ? value <= 0 : value < 0)) {
+        fail("E_OPERATION_UNCERTAIN", `${field} 无效`);
+    }
+    return value;
+}
+function requireString(value, field) {
+    if (typeof value !== "string" || value.length === 0)
+        fail("E_OPERATION_UNCERTAIN", `${field} 无效`);
+    return value;
+}
+function parseBase64(value, field) {
+    const encoded = requireString(value, field);
+    const bytes = new Uint8Array(Buffer.from(encoded, "base64"));
+    if (Buffer.from(bytes).toString("base64") !== encoded)
+        fail("E_OPERATION_UNCERTAIN", `${field} 不是 canonical base64`);
+    return bytes;
+}
+function canonicalRequestDigest(request) {
+    return serializeFrozenReviewSubmitStream(request).sha256;
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted === true)
+        fail("E_OPERATION_UNCERTAIN", "review operation 已取消；请按 operation status 恢复");
+}
+function assertCapture(capture) {
+    if (capture.project_id.length === 0 || capture.owner_id.length === 0) {
+        fail("E_VALIDATION_FAILED", "review capture 缺少 project/principal identity");
+    }
+    requireUuid(capture.scenario_id, "scenario_id");
+    if (!Number.isSafeInteger(capture.content_epoch) || capture.content_epoch <= 0
+        || !Number.isSafeInteger(capture.source_revision) || capture.source_revision <= 0) {
+        fail("E_VALIDATION_FAILED", "review capture epoch/revision 无效");
+    }
+    requireSha(capture.source_sha256, "source_sha256");
+    requireSha(capture.revision_digest, "revision_digest");
+    if (capture.revision_id.length === 0)
+        fail("E_VALIDATION_FAILED", "review capture revision_id 无效");
+}
+function assertPipelineBinding(capture, compilation, embedding, frozen) {
+    if (compilation.source_revision_digest !== capture.revision_digest
+        || embedding.source_revision_digest !== capture.revision_digest) {
+        fail("E_VALIDATION_FAILED", "compiler/embedding 未绑定同一 source revision");
+    }
+    requireSha(compilation.compiler_receipt_sha256, "compiler_receipt_sha256");
+    requireSha(embedding.descriptor_sha256, "embedding_descriptor_sha256");
+    if (!Number.isSafeInteger(embedding.vector_count) || embedding.vector_count <= 0) {
+        fail("E_VALIDATION_FAILED", "提审必须包含至少一个冻结 embedding vector");
+    }
+    const revision = frozen.captured_revision;
+    if (revision.owner_id !== capture.owner_id
+        || revision.scenario_id !== capture.scenario_id
+        || revision.epoch !== capture.content_epoch
+        || revision.revision_number !== capture.source_revision
+        || revision.revision_id !== capture.revision_id
+        || revision.source_sha256 !== capture.source_sha256
+        || revision.revision_digest !== capture.revision_digest) {
+        fail("E_VALIDATION_FAILED", "FrozenPublishInput 未绑定 captured revision");
+    }
+    const index = frozen.resources.find((resource) => resource.path === EMBEDDING_INDEX_PATH);
+    if (index === undefined || index.bytes.byteLength === 0) {
+        fail("E_VALIDATION_FAILED", "FrozenPublishInput 缺少 embedding index");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(index.bytes));
+    }
+    catch {
+        fail("E_VALIDATION_FAILED", "embedding index 不是合法 JSON");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        fail("E_VALIDATION_FAILED", "embedding index schema 无效");
+    }
+    const record = parsed;
+    if (record.source_revision_digest !== capture.revision_digest
+        || record.descriptor_sha256 !== embedding.descriptor_sha256
+        || !Array.isArray(record.entries)
+        || record.entries.length !== embedding.vector_count) {
+        fail("E_VALIDATION_FAILED", "embedding index 与冻结 source/descriptor 不匹配");
+    }
+}
+function toWireRequest(frozen, operationKey, reviewNote, releaseAt) {
+    const bundle = buildFrozenArtifactBundle(frozen);
+    const manifest = canonicalArtifactV5Bytes(bundle.artifact);
+    const base64 = (bytes) => Buffer.from(bytes).toString("base64");
+    return Object.freeze({
+        operation_key: operationKey,
+        review_note: reviewNote,
+        release_at: releaseAt,
+        bundle: Object.freeze({
+            artifact: Object.freeze({
+                scenario_id: bundle.artifact.scenario_id,
+                epoch: bundle.artifact.epoch,
+                runtime_generation: bundle.artifact.runtime.identity.runtime_generation,
+                runtime_contract_hash: bundle.artifact.runtime_contract_hash,
+                source_revision_digest: bundle.artifact.captured_revision.revision_digest,
+                trigger_document_sha256: bundle.artifact.trigger_document.sha256,
+                compiled_plan_sha256: bundle.artifact.compiled_plan.sha256,
+                view_interaction_mobile_sha256: bundle.artifact.view_interaction.mobile.sha256,
+                view_interaction_pc_sha256: bundle.artifact.view_interaction.pc.sha256,
+                music_candidate_source_sha256: bundle.artifact.music_candidate_source.sha256,
+                canonical_digest: bundle.artifact.canonical_digest,
+            }),
+            artifact_manifest_sha256: artifactV5ManifestSha256(bundle.artifact),
+            artifact_manifest_base64: base64(manifest),
+            review_database: Object.freeze({
+                encoding: "bytes",
+                size_bytes: frozen.database_bytes.byteLength,
+                sha256: sha256(frozen.database_bytes),
+            }),
+            objects: Object.freeze(bundle.objects.map((object) => Object.freeze({
+                kind: object.kind,
+                relative_path: object.relative_path,
+                media_type: object.media_type,
+                encoding: object.encoding,
+                size_bytes: object.size_bytes,
+                sha256: object.sha256,
+                bytes_base64: base64(object.bytes),
+            }))),
+        }),
+    });
+}
+function operationFileName(operationKey) {
+    return `frozen-review-${sha256(operationKey)}.json`;
+}
+function recoveryFileName(operationKey) {
+    return `frozen-review-${sha256(operationKey)}.recovery.json`;
+}
+async function operationPath(root, operationKey) {
+    await ensureSafeProjectDirectory(root, ".worldengine/operations");
+    return await safeProjectPath(root, `.worldengine/operations/${operationFileName(operationKey)}`);
+}
+async function recoveryPath(root, operationKey) {
+    await ensureSafeProjectDirectory(root, ".worldengine/operations");
+    return await safeProjectPath(root, `.worldengine/operations/${recoveryFileName(operationKey)}`);
+}
+function parseOperation(value) {
+    const root = record(value, "review operation");
+    exactKeys(root, [
+        "schema_version", "project_id", "operation_key", "owner_id", "scenario_id",
+        "source_revision_digest", "artifact_canonical_digest", "artifact_manifest_sha256",
+        "object_count", "review_note", "release_at", "request_digest", "state", "attempt",
+    ], "review operation");
+    if (root.schema_version !== 1)
+        fail("E_OPERATION_UNCERTAIN", "review operation schema_version 无效");
+    const operationKey = publishOperationKey(requireUuid(requireString(root.operation_key, "operation_key"), "operation_key"));
+    const state = root.state;
+    if (state !== "prepared" && state !== "submitting" && state !== "pending_review") {
+        fail("E_OPERATION_UNCERTAIN", "review operation state 无效");
+    }
+    const reviewNote = root.review_note === null ? null : requireString(root.review_note, "review_note");
+    const releaseAt = root.release_at === null ? null : requireInteger(root.release_at, "release_at", true);
+    const attempt = root.attempt === null ? null : parseAttempt(root.attempt, {
+        operation_key: operationKey,
+        bundle: { artifact: {
+                scenario_id: requireUuid(requireString(root.scenario_id, "scenario_id"), "scenario_id"),
+                canonical_digest: requireSha(root.artifact_canonical_digest, "artifact_canonical_digest"),
+            } },
+    });
+    if ((state === "pending_review") !== (attempt !== null)) {
+        fail("E_OPERATION_UNCERTAIN", "review operation attempt/state 不一致");
+    }
+    return Object.freeze({
+        schema_version: 1,
+        project_id: requireString(root.project_id, "project_id"),
+        operation_key: operationKey,
+        owner_id: requireString(root.owner_id, "owner_id"),
+        scenario_id: requireUuid(requireString(root.scenario_id, "scenario_id"), "scenario_id"),
+        source_revision_digest: requireSha(root.source_revision_digest, "source_revision_digest"),
+        artifact_canonical_digest: requireSha(root.artifact_canonical_digest, "artifact_canonical_digest"),
+        artifact_manifest_sha256: requireSha(root.artifact_manifest_sha256, "artifact_manifest_sha256"),
+        object_count: requireInteger(root.object_count, "object_count", true),
+        review_note: reviewNote,
+        release_at: releaseAt,
+        request_digest: requireSha(root.request_digest, "request_digest"),
+        state,
+        attempt,
+    });
+}
+async function readOperation(root, operationKey) {
+    try {
+        return parseOperation(JSON.parse(await readFile(await operationPath(root, operationKey), "utf8")));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+async function persistOperation(root, operation) {
+    const path = await operationPath(root, operation.operation_key);
+    const temporary = await safeProjectPath(root, `.worldengine/operations/${operationFileName(operation.operation_key)}.${randomUUID()}.tmp`);
+    // review_note 属于审核内容，只存在于受保护恢复密文；ledger 保留 request_digest 绑定。
+    const ledger = Object.freeze({ ...operation, review_note: null });
+    const bytes = `${JSON.stringify(ledger)}\n`;
+    await writeFile(temporary, bytes, { encoding: "utf8", flag: "wx" });
+    await rename(temporary, path);
+    const readback = await readOperation(root, operation.operation_key);
+    if (readback === null || readback.request_digest !== operation.request_digest || readback.state !== operation.state) {
+        fail("E_OPERATION_UNCERTAIN", "review operation ledger 写入后读回不一致");
+    }
+}
+const FROZEN_OBJECT_KINDS = new Set([
+    "database", "trigger_document", "compiled_plan", "view_interaction_mobile",
+    "view_interaction_pc", "music_candidate_source", "source_manifest",
+    "compile_target_profile", "compiler_receipt",
+]);
+function parseWireRequest(value) {
+    const root = record(value, "review recovery request");
+    exactKeys(root, ["operation_key", "review_note", "release_at", "bundle"], "review recovery request");
+    publishOperationKey(requireUuid(requireString(root.operation_key, "operation_key"), "operation_key"));
+    if (root.review_note !== null)
+        requireString(root.review_note, "review_note");
+    if (root.release_at !== null)
+        requireInteger(root.release_at, "release_at", true);
+    const bundle = record(root.bundle, "review recovery bundle");
+    exactKeys(bundle, ["artifact", "artifact_manifest_sha256", "artifact_manifest_base64", "review_database", "objects"], "review recovery bundle");
+    const artifact = record(bundle.artifact, "review recovery artifact");
+    exactKeys(artifact, [
+        "scenario_id", "epoch", "runtime_generation", "runtime_contract_hash",
+        "source_revision_digest", "trigger_document_sha256", "compiled_plan_sha256",
+        "view_interaction_mobile_sha256", "view_interaction_pc_sha256",
+        "music_candidate_source_sha256", "canonical_digest",
+    ], "review recovery artifact");
+    requireUuid(requireString(artifact.scenario_id, "scenario_id"), "scenario_id");
+    requireInteger(artifact.epoch, "epoch", true);
+    if (artifact.runtime_generation !== 3)
+        fail("E_OPERATION_UNCERTAIN", "runtime_generation 无效");
+    for (const field of [
+        "runtime_contract_hash", "source_revision_digest", "trigger_document_sha256",
+        "compiled_plan_sha256", "view_interaction_mobile_sha256", "view_interaction_pc_sha256",
+        "music_candidate_source_sha256", "canonical_digest",
+    ])
+        requireSha(artifact[field], field);
+    const manifestBytes = parseBase64(bundle.artifact_manifest_base64, "artifact_manifest_base64");
+    if (sha256(manifestBytes) !== requireSha(bundle.artifact_manifest_sha256, "artifact_manifest_sha256")) {
+        fail("E_OPERATION_UNCERTAIN", "artifact manifest 恢复校验失败");
+    }
+    const database = record(bundle.review_database, "review recovery database");
+    const databaseKeys = database.bytes_base64 === undefined
+        ? ["encoding", "size_bytes", "sha256"]
+        : ["encoding", "size_bytes", "sha256", "bytes_base64"];
+    exactKeys(database, databaseKeys, "review recovery database");
+    if (database.encoding !== "bytes")
+        fail("E_OPERATION_UNCERTAIN", "review database encoding 无效");
+    const databaseSize = requireInteger(database.size_bytes, "review_database.size_bytes");
+    const databaseSha = requireSha(database.sha256, "review_database.sha256");
+    if (database.bytes_base64 !== undefined) {
+        const databaseBytes = parseBase64(database.bytes_base64, "review_database.bytes_base64");
+        if (databaseBytes.byteLength !== databaseSize || sha256(databaseBytes) !== databaseSha) {
+            fail("E_OPERATION_UNCERTAIN", "review database 恢复校验失败");
+        }
+    }
+    if (!Array.isArray(bundle.objects))
+        fail("E_OPERATION_UNCERTAIN", "review recovery objects 无效");
+    for (const [index, candidate] of bundle.objects.entries()) {
+        const object = record(candidate, `review recovery object ${index}`);
+        exactKeys(object, ["kind", "relative_path", "media_type", "encoding", "size_bytes", "sha256", "bytes_base64"], `review recovery object ${index}`);
+        if (typeof object.kind !== "string" || !FROZEN_OBJECT_KINDS.has(object.kind)) {
+            fail("E_OPERATION_UNCERTAIN", `review recovery object ${index} kind 无效`);
+        }
+        requireString(object.relative_path, `objects.${index}.relative_path`);
+        requireString(object.media_type, `objects.${index}.media_type`);
+        if (object.encoding !== "bytes")
+            fail("E_OPERATION_UNCERTAIN", `review recovery object ${index} encoding 无效`);
+        const bytes = parseBase64(object.bytes_base64, `objects.${index}.bytes_base64`);
+        if (bytes.byteLength !== requireInteger(object.size_bytes, `objects.${index}.size_bytes`)
+            || sha256(bytes) !== requireSha(object.sha256, `objects.${index}.sha256`)) {
+            fail("E_OPERATION_UNCERTAIN", `review recovery object ${index} 校验失败`);
+        }
+    }
+    return value;
+}
+async function persistRecovery(root, projectId, operation, request, recovery) {
+    const payload = Object.freeze({ schema_version: 1, operation, request });
+    const ciphertext = await recovery.seal(projectId, new TextEncoder().encode(JSON.stringify(payload)));
+    if (!(ciphertext instanceof Uint8Array) || ciphertext.byteLength === 0) {
+        fail("E_OPERATION_UNCERTAIN", "review recovery ciphertext 无效");
+    }
+    const envelope = Object.freeze({
+        schema_version: 1,
+        project_id: projectId,
+        operation_key: operation.operation_key,
+        request_digest: operation.request_digest,
+        ciphertext_sha256: sha256(ciphertext),
+        ciphertext_base64: Buffer.from(ciphertext).toString("base64"),
+    });
+    const path = await recoveryPath(root, operation.operation_key);
+    const temporary = await safeProjectPath(root, `.worldengine/operations/${recoveryFileName(operation.operation_key)}.${randomUUID()}.tmp`);
+    await writeFile(temporary, `${JSON.stringify(envelope)}\n`, { encoding: "utf8", flag: "wx" });
+    try {
+        await link(temporary, path);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    finally {
+        await unlink(temporary).catch(() => undefined);
+    }
+    const readback = await readRecovery(root, projectId, operation.operation_key, recovery);
+    if (readback === null || !samePreparedBinding(readback.operation, operation)
+        || canonicalRequestDigest(readback.request) !== operation.request_digest) {
+        fail("E_OPERATION_UNCERTAIN", "review recovery snapshot 写入后读回不一致");
+    }
+}
+async function readRecovery(root, projectId, operationKey, recovery) {
+    let decoded;
+    try {
+        decoded = JSON.parse(await readFile(await recoveryPath(root, operationKey), "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    const envelope = record(decoded, "review recovery envelope");
+    exactKeys(envelope, ["schema_version", "project_id", "operation_key", "request_digest", "ciphertext_sha256", "ciphertext_base64"], "review recovery envelope");
+    if (envelope.schema_version !== 1 || envelope.project_id !== projectId || envelope.operation_key !== operationKey) {
+        fail("E_OPERATION_UNCERTAIN", "review recovery envelope identity 不匹配");
+    }
+    const ciphertext = parseBase64(envelope.ciphertext_base64, "ciphertext_base64");
+    if (sha256(ciphertext) !== requireSha(envelope.ciphertext_sha256, "ciphertext_sha256")) {
+        fail("E_OPERATION_UNCERTAIN", "review recovery ciphertext digest 不匹配");
+    }
+    let plaintext;
+    try {
+        plaintext = await recovery.open(projectId, ciphertext);
+    }
+    catch (error) {
+        if (error instanceof AuthoringBridgeError)
+            throw error;
+        fail("E_OPERATION_UNCERTAIN", "review recovery ciphertext 认证失败");
+    }
+    if (!(plaintext instanceof Uint8Array))
+        fail("E_OPERATION_UNCERTAIN", "review recovery plaintext 无效");
+    let payloadValue;
+    try {
+        payloadValue = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(plaintext));
+    }
+    catch {
+        fail("E_OPERATION_UNCERTAIN", "review recovery plaintext 无效");
+    }
+    const payload = record(payloadValue, "review recovery payload");
+    exactKeys(payload, ["schema_version", "operation", "request"], "review recovery payload");
+    if (payload.schema_version !== 1)
+        fail("E_OPERATION_UNCERTAIN", "review recovery payload version 无效");
+    const operation = parseOperation(payload.operation);
+    const request = parseWireRequest(payload.request);
+    const digest = canonicalRequestDigest(request);
+    if (operation.project_id !== projectId || operation.operation_key !== operationKey
+        || request.operation_key !== operationKey || operation.request_digest !== digest
+        || envelope.request_digest !== digest) {
+        fail("E_OPERATION_UNCERTAIN", "review recovery payload binding 不匹配");
+    }
+    return Object.freeze({ operation, request });
+}
+function parseAttempt(value, request) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        fail("E_VALIDATION_FAILED", "frozen review response 无效");
+    }
+    const body = value;
+    const snakeCase = "attempt_id" in body;
+    exactKeys(body, snakeCase
+        ? ["attempt_id", "operation_key", "scenario_id", "artifact_canonical_digest", "review_snapshot_hash", "review_coverage_hash", "state"]
+        : ["attemptId", "operationKey", "scenarioId", "artifactCanonicalDigest", "reviewSnapshotHash", "reviewCoverageHash", "state"], "frozen review response");
+    if (body.state !== "pending_review")
+        fail("E_OPERATION_UNCERTAIN", "远端 attempt 尚未进入 pending_review");
+    const attemptId = typeof body.attempt_id === "string" ? body.attempt_id : body.attemptId;
+    const operationKey = typeof body.operation_key === "string" ? body.operation_key : body.operationKey;
+    const scenarioId = typeof body.scenario_id === "string" ? body.scenario_id : body.scenarioId;
+    const artifactDigest = typeof body.artifact_canonical_digest === "string"
+        ? body.artifact_canonical_digest
+        : body.artifactCanonicalDigest;
+    const snapshotHash = typeof body.review_snapshot_hash === "string" ? body.review_snapshot_hash : body.reviewSnapshotHash;
+    const coverageHash = typeof body.review_coverage_hash === "string" ? body.review_coverage_hash : body.reviewCoverageHash;
+    if (typeof attemptId !== "string" || !UUID_PATTERN.test(attemptId)
+        || typeof operationKey !== "string" || operationKey !== request.operation_key
+        || typeof scenarioId !== "string" || scenarioId !== request.bundle.artifact.scenario_id
+        || typeof artifactDigest !== "string" || artifactDigest !== request.bundle.artifact.canonical_digest) {
+        fail("E_OPERATION_UNCERTAIN", "远端 frozen review response identity 不匹配");
+    }
+    return Object.freeze({
+        attempt_id: attemptId,
+        operation_key: publishOperationKey(operationKey),
+        scenario_id: scenarioId,
+        artifact_canonical_digest: requireSha(artifactDigest, "artifact_canonical_digest"),
+        review_snapshot_hash: requireSha(snapshotHash, "review_snapshot_hash"),
+        review_coverage_hash: requireSha(coverageHash, "review_coverage_hash"),
+        state: "pending_review",
+    });
+}
+function remotePath(scenarioId) {
+    return `/v1/scenarios/${encodeURIComponent(scenarioId)}/frozen-artifacts/v5/attempts`;
+}
+function readbackPath(scenarioId, operationKey) {
+    return `${remotePath(scenarioId)}/by-operation/${encodeURIComponent(operationKey)}`;
+}
+function samePreparedBinding(left, right) {
+    return left.schema_version === right.schema_version
+        && left.project_id === right.project_id
+        && left.operation_key === right.operation_key
+        && left.owner_id === right.owner_id
+        && left.scenario_id === right.scenario_id
+        && left.source_revision_digest === right.source_revision_digest
+        && left.artifact_canonical_digest === right.artifact_canonical_digest
+        && left.artifact_manifest_sha256 === right.artifact_manifest_sha256
+        && left.object_count === right.object_count
+        && left.release_at === right.release_at
+        && left.request_digest === right.request_digest;
+}
+export class FrozenReviewCoordinator {
+    #root;
+    #projectId;
+    #pipeline;
+    #transport;
+    #recovery;
+    constructor(root, projectId, pipeline, transport, recovery) {
+        this.#root = root;
+        this.#projectId = projectId;
+        this.#pipeline = pipeline;
+        this.#transport = transport;
+        this.#recovery = recovery;
+    }
+    static async open(root, projectId, options = {}) {
+        if (projectId.length === 0)
+            fail("E_SCHEMA_INVALID", "review 缺少 project_id");
+        await ensureSafeProjectDirectory(root, ".worldengine/operations");
+        return new FrozenReviewCoordinator(root, projectId, options.pipeline, options.transport, options.recovery);
+    }
+    async #prepareRequest(input) {
+        const operationKey = publishOperationKey(requireUuid(input.operation_key, "operation_key"));
+        const reviewNote = requireReviewNote(input.review_note);
+        const releaseAt = requirePositiveInteger(input.release_at, "release_at");
+        const existing = await readOperation(this.#root, operationKey);
+        if (existing !== null) {
+            if (existing.project_id !== this.#projectId
+                || existing.operation_key !== operationKey
+                || existing.release_at !== releaseAt) {
+                fail("E_OPERATION_ID_CONFLICT", "同一 review operation_key 使用了不同请求或 ledger 已损坏");
+            }
+        }
+        const recovery = this.#recovery;
+        if (recovery !== undefined) {
+            const recovered = await readRecovery(this.#root, this.#projectId, operationKey, recovery);
+            if (recovered !== null) {
+                if (recovered.operation.review_note !== reviewNote || recovered.operation.release_at !== releaseAt
+                    || (existing !== null && !samePreparedBinding(existing, recovered.operation))) {
+                    fail("E_OPERATION_ID_CONFLICT", "同一 review operation_key 使用了不同恢复快照");
+                }
+                const operation = existing === null
+                    ? recovered.operation
+                    : Object.freeze({ ...recovered.operation, state: existing.state, attempt: existing.attempt });
+                if (existing === null)
+                    await persistOperation(this.#root, operation);
+                return Object.freeze({ operation, request: recovered.request });
+            }
+        }
+        if (existing?.state === "pending_review") {
+            if (reviewNote !== null)
+                fail("E_OPERATION_UNCERTAIN", "pending review 缺少受保护快照，不能校验 review_note");
+            return existing;
+        }
+        if (existing !== null) {
+            fail("E_OPERATION_UNCERTAIN", "review operation 缺少受保护恢复快照，不能重新捕获 live source");
+        }
+        if (this.#pipeline === undefined)
+            fail("E_VALIDATION_FAILED", "当前 Node runtime 未提供本地 frozen review pipeline");
+        throwIfAborted(input.signal);
+        const capture = await this.#pipeline.capture(input.signal);
+        assertCapture(capture);
+        if (capture.project_id !== this.#projectId)
+            fail("E_OPERATION_ID_CONFLICT", "review capture project identity 不匹配");
+        const compilation = await this.#pipeline.compile(Object.freeze({ ...capture }), input.signal);
+        throwIfAborted(input.signal);
+        const embedding = await this.#pipeline.embed(Object.freeze({ ...capture }), Object.freeze({ ...compilation }), input.signal);
+        throwIfAborted(input.signal);
+        const frozen = await this.#pipeline.freeze(Object.freeze({ ...capture }), Object.freeze({ ...compilation }), Object.freeze({ ...embedding }), input.signal);
+        assertPipelineBinding(capture, compilation, embedding, frozen);
+        const request = toWireRequest(frozen, operationKey, reviewNote, releaseAt);
+        const operation = Object.freeze({
+            schema_version: 1,
+            project_id: this.#projectId,
+            operation_key: operationKey,
+            owner_id: capture.owner_id,
+            scenario_id: capture.scenario_id,
+            source_revision_digest: capture.revision_digest,
+            artifact_canonical_digest: request.bundle.artifact.canonical_digest,
+            artifact_manifest_sha256: request.bundle.artifact_manifest_sha256,
+            object_count: request.bundle.objects.length,
+            review_note: request.review_note,
+            release_at: request.release_at,
+            request_digest: canonicalRequestDigest(request),
+            state: "prepared",
+            attempt: null,
+        });
+        if (recovery === undefined)
+            fail("E_AUTH_REQUIRED", "Node review 未提供 project-scoped 受保护恢复 port");
+        await persistRecovery(this.#root, this.#projectId, operation, request, recovery);
+        await persistOperation(this.#root, operation);
+        return Object.freeze({ operation, request });
+    }
+    async prepare(input) {
+        const prepared = await this.#prepareRequest(input);
+        return "request" in prepared ? prepared.operation : prepared;
+    }
+    async submit(input) {
+        const preparedResult = await this.#prepareRequest(input);
+        if (!("request" in preparedResult))
+            return preparedResult;
+        const { operation: prepared, request } = preparedResult;
+        if (prepared.state === "pending_review")
+            return prepared;
+        const transport = this.#transport;
+        if (transport === undefined)
+            fail("E_AUTH_REQUIRED", "CLI 没有 ProjectAuthBroker 受控 transport");
+        if (canonicalRequestDigest(request) !== prepared.request_digest) {
+            fail("E_OPERATION_UNCERTAIN", "review operation ledger request digest 不匹配");
+        }
+        const stream = serializeFrozenReviewSubmitStream(request);
+        if (prepared.state === "submitting") {
+            return await this.#resumeSubmitting(prepared, request, transport);
+        }
+        const submitting = Object.freeze({ ...prepared, state: "submitting" });
+        await persistOperation(this.#root, submitting);
+        let response;
+        try {
+            response = await transport.request({
+                project_id: this.#projectId,
+                operation_id: prepared.operation_key,
+                method: "POST",
+                path: remotePath(prepared.scenario_id),
+                content_type: stream.content_type,
+                body: stream.bytes,
+                body_digest: prepared.request_digest,
+                body_size: stream.byte_length,
+            });
+        }
+        catch {
+            return await this.#resumeSubmitting(submitting, request, transport);
+        }
+        this.#assertSubmitStatus(response.status);
+        const attempt = parseAttempt(response.body, request);
+        const completed = Object.freeze({ ...prepared, state: "pending_review", attempt });
+        await persistOperation(this.#root, completed);
+        return completed;
+    }
+    #assertSubmitStatus(status) {
+        if (status >= 200 && status < 300)
+            return;
+        if (status === 401 || status === 403)
+            fail("E_AUTH_REQUIRED", "远端 review submit 未获授权");
+        fail("E_OPERATION_UNCERTAIN", `远端 review submit 失败：HTTP ${status}`);
+    }
+    async #resumeSubmitting(operation, request, transport) {
+        const readback = await transport.request({
+            project_id: this.#projectId,
+            operation_id: operation.operation_key,
+            method: "GET",
+            path: readbackPath(operation.scenario_id, operation.operation_key),
+        });
+        if (readback.status >= 200 && readback.status < 300) {
+            const attempt = parseAttempt(readback.body, request);
+            const completed = Object.freeze({ ...operation, state: "pending_review", attempt });
+            await persistOperation(this.#root, completed);
+            return completed;
+        }
+        if (readback.status !== 404) {
+            if (readback.status === 401 || readback.status === 403)
+                fail("E_AUTH_REQUIRED", "远端 review readback 未获授权");
+            fail("E_OPERATION_UNCERTAIN", `远端 review readback 失败：HTTP ${readback.status}`);
+        }
+        const stream = serializeFrozenReviewSubmitStream(request);
+        const retried = await transport.request({
+            project_id: this.#projectId,
+            operation_id: operation.operation_key,
+            method: "POST",
+            path: remotePath(operation.scenario_id),
+            content_type: stream.content_type,
+            body: stream.bytes,
+            body_digest: operation.request_digest,
+            body_size: stream.byte_length,
+        });
+        this.#assertSubmitStatus(retried.status);
+        const attempt = parseAttempt(retried.body, request);
+        const completed = Object.freeze({ ...operation, state: "pending_review", attempt });
+        await persistOperation(this.#root, completed);
+        return completed;
+    }
+    async status(operationKeyValue, reconcile = true) {
+        const operationKey = publishOperationKey(requireUuid(operationKeyValue, "operation_key"));
+        const stored = await readOperation(this.#root, operationKey);
+        if (stored === null)
+            fail("E_VALIDATION_FAILED", "review operation 不存在");
+        if (stored.project_id !== this.#projectId || stored.operation_key !== operationKey) {
+            fail("E_OPERATION_UNCERTAIN", "review operation ledger identity 不匹配");
+        }
+        let operation = stored;
+        if (this.#recovery !== undefined) {
+            const recovered = await readRecovery(this.#root, this.#projectId, operationKey, this.#recovery);
+            if (recovered === null || !samePreparedBinding(stored, recovered.operation)) {
+                fail("E_OPERATION_UNCERTAIN", "review operation ledger/recovery binding 不匹配");
+            }
+            operation = Object.freeze({ ...recovered.operation, state: stored.state, attempt: stored.attempt });
+        }
+        if (!reconcile || operation.state === "pending_review")
+            return operation;
+        if (this.#transport === undefined)
+            return operation;
+        return await this.#reconcile(operation, this.#transport);
+    }
+    async #reconcile(operation, transport) {
+        const response = await transport.request({
+            project_id: this.#projectId,
+            operation_id: operation.operation_key,
+            method: "GET",
+            path: readbackPath(operation.scenario_id, operation.operation_key),
+        });
+        if (response.status === 404)
+            fail("E_OPERATION_UNCERTAIN", "远端尚无该 review operation；可用相同 operation_key 重试 submit");
+        if (response.status < 200 || response.status >= 300) {
+            if (response.status === 401 || response.status === 403)
+                fail("E_AUTH_REQUIRED", "远端 review readback 未获授权");
+            fail("E_OPERATION_UNCERTAIN", `远端 review readback 失败：HTTP ${response.status}`);
+        }
+        const syntheticRequest = {
+            operation_key: operation.operation_key,
+            bundle: { artifact: {
+                    scenario_id: operation.scenario_id,
+                    canonical_digest: operation.artifact_canonical_digest,
+                } },
+        };
+        const attempt = parseAttempt(response.body, syntheticRequest);
+        const completed = Object.freeze({ ...operation, state: "pending_review", attempt });
+        await persistOperation(this.#root, completed);
+        return completed;
+    }
+}
+export function frozenReviewObjectKeys(request) {
+    return Object.freeze(request.bundle.objects.map((object) => buildFrozenArtifactObjectKey(request.bundle.artifact.scenario_id, request.bundle.artifact.canonical_digest, object.relative_path)));
+}