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

package/dist/frozen-review-local-pipeline.js

@@ -0,0 +1,609 @@
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { mkdir, mkdtemp, readFile, realpath, rename, rm, symlink, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, normalize, relative, sep } from "node:path";
+import { promisify } from "node:util";
+import { gunzip } from "node:zlib";
+import { captureNeutralSourceCompileInput, } from "@world-engines/scenario-author-source";
+import { canonicalJson, assembleNeutralFrozenPublishInput, encodeNeutralReviewDatabaseSnapshot, materializeNeutralArtifactCompilation, } from "@world-engines/scenario-review-snapshot";
+import { CURRENT_NEUTRAL_COMPILER_STAGE_VERSIONS, InMemoryCompilerStageCache, buildCurrentTmw3NeutralCompilerStageRegistry, compileTargetProfileDigest, parseCompileTargetProfile, compileNeutralScenarioSource, requireActiveCompilerRelease, } from "@world-engines/tmw";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { ensureSafeProjectDirectory, safeProjectPath } from "./safe-project-path.js";
+import { createFrozenReviewWasmEncryptor, } from "./frozen-review-wasm-encryptor.js";
+const SHA256_PATTERN = /^[0-9a-f]{64}$/u;
+const REVIEW_TARGET_PATH = ".worldengine/review-target.json";
+const compilerCache = new InMemoryCompilerStageCache();
+const execFileAsync = promisify(execFile);
+const gunzipAsync = promisify(gunzip);
+const MAX_PUBLISH_HTML_BYTES = 10 * 1024 * 1024;
+const MAX_VIEW_ARCHIVE_BYTES = 32 * 1024 * 1024;
+const MAX_VIEW_UNPACKED_BYTES = 96 * 1024 * 1024;
+const MAX_VIEW_ENTRY_BYTES = 16 * 1024 * 1024;
+const MAX_VIEW_FILES = 20_000;
+const encodeCompactReviewDatabase = encodeNeutralReviewDatabaseSnapshot;
+export function createFrozenReviewEmbeddingBatch(embedding) {
+    return async (request) => {
+        if (request.entities.length === 0)
+            fail("E_VALIDATION_FAILED", "review embedding entity 为空");
+        const vectors = await embedding.embed(request.entities.map((entity) => entity.source_text), request.signal === undefined ? undefined : { signal: request.signal });
+        if (vectors.length !== request.entities.length
+            || vectors.some((vector) => vector.length !== embedding.dimensions || vector.some((value) => !Number.isFinite(value)))) {
+            fail("E_VALIDATION_FAILED", "review embedding provider result 无效");
+        }
+        const descriptorBase = Object.freeze({
+            provider: requireText(embedding.providerId, "embedding provider"),
+            model: requireText(embedding.modelId, "embedding model"),
+            dimension: requirePositive(embedding.dimensions, "embedding dimension"),
+            source_revision: request.source.source_revision,
+            source_revision_digest: request.source.revision_digest,
+        });
+        const descriptor = Object.freeze({
+            ...descriptorBase,
+            descriptor_sha256: createHash("sha256").update(canonicalJson(descriptorBase)).digest("hex"),
+        });
+        return Object.freeze({
+            descriptor,
+            entries: Object.freeze(request.entities.map((entity, index) => Object.freeze({
+                entity_id: entity.entity_id,
+                source_kind: entity.source_kind,
+                source_text_sha256: entity.source_text_sha256,
+                vector: Object.freeze([...vectors[index]]),
+            }))),
+        });
+    };
+}
+/** 与 Creator 共读 Edge CompilerReleaseAuthority；transport 持有认证，CLI 不接触 cookie/token。 */
+export function createCompilerReleaseProfileAdmission(transport, projectId) {
+    const read = async () => {
+        const response = await transport.request(Object.freeze({
+            project_id: projectId,
+            method: "GET",
+            path: "/v1/compiler-releases/current",
+        }));
+        if (response.status !== 200) {
+            fail("E_AUTH_REQUIRED", `Compiler release authority readback 失败：${response.status}`);
+        }
+        if (typeof response.body !== "object" || response.body === null || Array.isArray(response.body)) {
+            fail("E_VALIDATION_FAILED", "Compiler release authority readback 无效");
+        }
+        const envelope = response.body;
+        if (envelope.schema_version !== 1 || !Number.isSafeInteger(envelope.revision)) {
+            fail("E_VALIDATION_FAILED", "Compiler release authority revision 无效");
+        }
+        const parseIdentity = async (value) => {
+            if (value === null || value === undefined)
+                return null;
+            if (typeof value !== "object" || Array.isArray(value)) {
+                fail("E_VALIDATION_FAILED", "Compiler release authority identity 无效");
+            }
+            const identity = value;
+            const target_profile = parseCompileTargetProfile(identity.target_profile);
+            return Object.freeze({ ...identity, target_profile });
+        };
+        return Object.freeze({
+            active: await parseIdentity(envelope.active),
+            previous_active: await parseIdentity(envelope.previous_active),
+        });
+    };
+    return async (profile) => {
+        const snapshot = await read();
+        if (snapshot.active !== null
+            && await compileTargetProfileDigest(snapshot.active.target_profile) !== snapshot.active.target_profile_sha256) {
+            fail("E_VALIDATION_FAILED", "Compiler release authority profile digest 不匹配");
+        }
+        await requireActiveCompilerRelease({
+            read: async () => snapshot,
+            writeOnce: async () => { throw new Error("compiler_release_readback_store_read_only"); },
+        }, profile);
+    };
+}
+function fail(code, message) {
+    throw new AuthoringBridgeError(code, message);
+}
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function requireSha(value, field) {
+    if (typeof value !== "string" || !SHA256_PATTERN.test(value)) {
+        fail("E_VALIDATION_FAILED", `${field} digest 无效`);
+    }
+    return value;
+}
+function requireText(value, field) {
+    if (typeof value !== "string" || value.length === 0 || value !== value.trim().normalize("NFC")) {
+        fail("E_VALIDATION_FAILED", `${field} identity 无效`);
+    }
+    return value;
+}
+function requirePositive(value, field) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+        fail("E_VALIDATION_FAILED", `${field} 无效`);
+    }
+    return value;
+}
+function object(value, field) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        fail("E_VALIDATION_FAILED", `${field} response 无效`);
+    }
+    return value;
+}
+export async function readFrozenReviewTargetBinding(root, expectedProjectId) {
+    const path = await safeProjectPath(root, REVIEW_TARGET_PATH);
+    let value;
+    try {
+        value = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        return fail("E_VALIDATION_FAILED", `${REVIEW_TARGET_PATH} 缺失或无效；先完成 Neutral source upload binding`);
+    }
+    const record = object(value, "review target");
+    const keys = Object.keys(record).sort();
+    if (keys.join("\0") !== ["project_id", "scenario_id", "schema_version", "source_digest", "source_head_digest"].sort().join("\0")
+        || record.schema_version !== 1
+        || record.project_id !== expectedProjectId) {
+        fail("E_OPERATION_ID_CONFLICT", "review target 未绑定当前 project");
+    }
+    return Object.freeze({
+        schema_version: 1,
+        project_id: expectedProjectId,
+        scenario_id: requireText(record.scenario_id, "review target scenario"),
+        source_digest: requireSha(record.source_digest, "review target source"),
+        source_head_digest: requireSha(record.source_head_digest, "review target head"),
+    });
+}
+function tarText(bytes) {
+    const end = bytes.indexOf(0);
+    return new TextDecoder("utf-8", { fatal: true }).decode(end < 0 ? bytes : bytes.subarray(0, end));
+}
+function tarOctal(bytes, field) {
+    const value = tarText(bytes).trim().replace(/^0+/u, "");
+    if (value === "")
+        return 0;
+    if (!/^[0-7]+$/u.test(value))
+        fail("E_VALIDATION_FAILED", `view tar ${field} 无效`);
+    const parsed = Number.parseInt(value, 8);
+    if (!Number.isSafeInteger(parsed) || parsed < 0)
+        fail("E_VALIDATION_FAILED", `view tar ${field} 越界`);
+    return parsed;
+}
+function canonicalTarPath(raw) {
+    if (raw.length === 0 || raw.includes("\\") || raw.includes("\0") || isAbsolute(raw)) {
+        return fail("E_VALIDATION_FAILED", "view tar path 无效");
+    }
+    const path = normalize(raw).split(sep).join("/");
+    if (path === "." || path.startsWith("../") || path.includes("/../") || path.startsWith("/")) {
+        return fail("E_VALIDATION_FAILED", "view tar path 越界");
+    }
+    return path.replace(/^\.\//u, "");
+}
+async function unpackCapturedViewProject(canonicalGzipTar) {
+    if (canonicalGzipTar.byteLength === 0 || canonicalGzipTar.byteLength > MAX_VIEW_ARCHIVE_BYTES) {
+        fail("E_VALIDATION_FAILED", "view archive size 无效");
+    }
+    let tar = canonicalGzipTar;
+    if (canonicalGzipTar[0] === 0x1f && canonicalGzipTar[1] === 0x8b) {
+        try {
+            tar = new Uint8Array(await gunzipAsync(canonicalGzipTar, { maxOutputLength: MAX_VIEW_UNPACKED_BYTES }));
+        }
+        catch {
+            return fail("E_VALIDATION_FAILED", "view gzip 无法解压");
+        }
+    }
+    if (tar.byteLength === 0 || tar.byteLength > MAX_VIEW_UNPACKED_BYTES) {
+        fail("E_VALIDATION_FAILED", "view tar size 无效");
+    }
+    const files = new Map();
+    let totalBytes = 0;
+    let offset = 0;
+    while (offset + 512 <= tar.byteLength) {
+        const header = tar.subarray(offset, offset + 512);
+        if (header.every((byte) => byte === 0))
+            break;
+        const storedChecksum = tarOctal(header.subarray(148, 156), "checksum");
+        let checksum = 0;
+        for (let index = 0; index < header.length; index += 1) {
+            checksum += index >= 148 && index < 156 ? 0x20 : header[index];
+        }
+        if (checksum !== storedChecksum)
+            fail("E_VALIDATION_FAILED", "view tar checksum 不匹配");
+        const name = tarText(header.subarray(0, 100));
+        const prefix = tarText(header.subarray(345, 500));
+        const path = canonicalTarPath(prefix.length === 0 ? name : `${prefix}/${name}`);
+        const size = tarOctal(header.subarray(124, 136), "size");
+        if (size > MAX_VIEW_ENTRY_BYTES)
+            fail("E_VALIDATION_FAILED", "view tar entry 过大");
+        const type = header[156] ?? 0;
+        const contentStart = offset + 512;
+        const contentEnd = contentStart + size;
+        if (contentEnd > tar.byteLength)
+            fail("E_VALIDATION_FAILED", "view tar 被截断");
+        if (type === 0 || type === 0x30) {
+            if (files.has(path))
+                fail("E_VALIDATION_FAILED", `view tar path 重复：${path}`);
+            if (files.size >= MAX_VIEW_FILES)
+                fail("E_VALIDATION_FAILED", "view tar files 过多");
+            totalBytes += size;
+            if (!Number.isSafeInteger(totalBytes) || totalBytes > MAX_VIEW_UNPACKED_BYTES) {
+                fail("E_VALIDATION_FAILED", "view tar total size 过大");
+            }
+            files.set(path, tar.slice(contentStart, contentEnd));
+        }
+        else if (type !== 0x35) {
+            fail("E_VALIDATION_FAILED", "view tar 禁止 link/device entry");
+        }
+        offset = contentStart + Math.ceil(size / 512) * 512;
+    }
+    if (files.size === 0)
+        fail("E_VALIDATION_FAILED", "view project 为空");
+    return files;
+}
+async function materializeCapturedViewProject(root, project) {
+    for (const [path, bytes] of project) {
+        const target = join(root, ...canonicalTarPath(path).split("/"));
+        const local = relative(root, target);
+        if (local === "" || local === ".." || local.startsWith(`..${sep}`) || isAbsolute(local)) {
+            fail("E_VALIDATION_FAILED", "view project path 越界");
+        }
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, bytes, { flag: "wx" });
+    }
+}
+function npmInvocation() {
+    if (process.platform !== "win32")
+        return { command: "npm", args: [] };
+    return {
+        command: process.execPath,
+        args: [join(dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js")],
+    };
+}
+async function buildCapturedView(projectRoot, project, revisionDigest) {
+    await ensureSafeProjectDirectory(projectRoot, ".worldengine/review-build");
+    const buildParent = await safeProjectPath(projectRoot, ".worldengine/review-build");
+    const work = await mkdtemp(join(buildParent, `${revisionDigest.slice(0, 16)}-`));
+    const canonicalParent = await realpath(buildParent);
+    const canonicalWork = await realpath(work);
+    if (!canonicalWork.startsWith(`${canonicalParent}${sep}`))
+        fail("E_VALIDATION_FAILED", "review build path 越界");
+    try {
+        await materializeCapturedViewProject(canonicalWork, project);
+        const nodeModules = await realpath(join(projectRoot, "view", "node_modules"));
+        await symlink(nodeModules, join(canonicalWork, "node_modules"), process.platform === "win32" ? "junction" : "dir");
+        const npm = npmInvocation();
+        const buildOne = async (target) => {
+            await writeFile(join(canonicalWork, ".env"), `VITE_PUBLISH_TARGET=${target}\n`, "utf8");
+            const outDir = join(canonicalWork, `dist-${target}`);
+            await execFileAsync(npm.command, [...npm.args, "run", "build", "--", "--outDir", outDir, "--emptyOutDir"], {
+                cwd: canonicalWork,
+                env: { ...process.env, VITE_PUBLISH_TARGET: target },
+                timeout: 5 * 60_000,
+                windowsHide: true,
+                maxBuffer: 4 * 1024 * 1024,
+            });
+            const html = new Uint8Array(await readFile(join(outDir, "index.html")));
+            if (html.byteLength === 0 || html.byteLength > MAX_PUBLISH_HTML_BYTES) {
+                fail("E_VALIDATION_FAILED", `view ${target} build size 无效`);
+            }
+            return html;
+        };
+        return Object.freeze({ mobile: await buildOne("mobile"), pc: await buildOne("pc") });
+    }
+    finally {
+        if (canonicalWork.startsWith(`${canonicalParent}${sep}`))
+            await rm(canonicalWork, { recursive: true, force: true });
+    }
+}
+function successBody(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 object(response.body, field);
+}
+async function readDatabaseKey(options, scenarioId, requiredBytes) {
+    const response = await options.transport.request({
+        project_id: options.project_id,
+        method: "GET",
+        path: `/v1/scenarios/${encodeURIComponent(scenarioId)}/modules/database/key`,
+    });
+    const body = successBody(response, "database key");
+    const derivation = object(body.derivation, "database key derivation");
+    const key = requireText(body.key_b64, "database key");
+    if (derivation.algo !== "HKDF-SHA256" || derivation.info_v !== 1
+        || requirePositive(body.ttl_seconds, "database key ttl") < 1
+        || requirePositive(body.max_bytes, "database key max bytes") < requiredBytes) {
+        fail("E_VALIDATION_FAILED", "database key contract 不匹配");
+    }
+    return key;
+}
+async function encryptDatabaseDelivery(options, scenarioId, plaintext) {
+    const key = await readDatabaseKey(options, scenarioId, plaintext.byteLength);
+    const ciphertext = await (options.crypto ?? createFrozenReviewWasmEncryptor()).encrypt(key, plaintext);
+    if (ciphertext.byteLength === 0 || ciphertext[0] !== 0x10)
+        fail("E_VALIDATION_FAILED", "database SCNB v2 delivery 无效");
+    return ciphertext;
+}
+/** Coordinator 的随机密文恢复 port；每次仅短暂消费同 scenario database key。 */
+export function createFrozenReviewRecoveryPort(options) {
+    const crypto = options.crypto ?? createFrozenReviewWasmEncryptor();
+    const scenario = async () => {
+        const target = await readFrozenReviewTargetBinding(options.project_root, options.project_id);
+        return target.scenario_id;
+    };
+    return Object.freeze({
+        async seal(projectId, plaintext) {
+            if (projectId !== options.project_id)
+                fail("E_OPERATION_ID_CONFLICT", "review recovery project 不匹配");
+            const key = await readDatabaseKey(options, await scenario(), plaintext.byteLength);
+            const ciphertext = await crypto.encrypt(key, plaintext);
+            if (ciphertext.byteLength === 0 || ciphertext[0] !== 0x10)
+                fail("E_VALIDATION_FAILED", "review recovery SCNB v2 无效");
+            return ciphertext;
+        },
+        async open(projectId, ciphertext) {
+            if (projectId !== options.project_id || ciphertext.byteLength === 0 || ciphertext[0] !== 0x10) {
+                fail("E_OPERATION_ID_CONFLICT", "review recovery identity 不匹配");
+            }
+            const key = await readDatabaseKey(options, await scenario(), 1);
+            return await crypto.decrypt(key, ciphertext);
+        },
+    });
+}
+/**
+ * Standalone Node 的真实发布装配器：remote capture 的同一 compiler outcome 在共享模块物化，
+ * 随后构建双端 View、用 broker key + Rust/WASM 生成 SCNB，再返回 FrozenPublishInput。
+ * prepare 不写 mutable module；唯一远端写由 Coordinator 的 attempt POST 执行。
+ */
+export function createFrozenReviewLocalArtifactAssembler(options) {
+    const compilations = new Map();
+    const materialize = async (input) => {
+        const cached = compilations.get(input.capture.revision_digest);
+        if (cached !== undefined)
+            return cached;
+        const compiled = await materializeNeutralArtifactCompilation(input.source, input.profile, input.compilation, unpackCapturedViewProject);
+        compilations.set(input.capture.revision_digest, compiled);
+        return compiled;
+    };
+    return Object.freeze({
+        async embeddingGraph(input) {
+            return (await materialize(input)).model.graph;
+        },
+        async assemble(input) {
+            if (input.signal?.aborted === true)
+                fail("E_VALIDATION_FAILED", "review assemble 已取消");
+            const compilation = await materialize(input);
+            const crypto = options.crypto ?? createFrozenReviewWasmEncryptor();
+            if (crypto.pack === undefined)
+                fail("E_VALIDATION_FAILED", "review database WASM pack 未配置");
+            const database = await encodeCompactReviewDatabase({
+                source: input.source,
+                content_epoch: input.capture.content_epoch,
+                compilation,
+                embedding: input.embedding_snapshot.materialization,
+                packFrozenDatabase: (packInput) => crypto.pack(packInput),
+            });
+            const views = await buildCapturedView(options.project_root, compilation.model.view_project, input.capture.revision_digest);
+            const runtimeResponse = await options.transport.request({
+                project_id: options.project_id,
+                method: "GET",
+                path: "/v1/runtime/current",
+            });
+            const runtime = successBody(runtimeResponse, "runtime current");
+            const runtimeMajor = requirePositive(runtime.runtime_major, "runtime major");
+            if (typeof runtime.runtime_patch !== "number" || !Number.isSafeInteger(runtime.runtime_patch) || runtime.runtime_patch < 0) {
+                fail("E_VALIDATION_FAILED", "runtime patch 无效");
+            }
+            const protocolVersion = requirePositive(runtime.protocol_version, "runtime protocol");
+            const databaseDelivery = await encryptDatabaseDelivery(options, input.capture.scenario_id, database);
+            return await assembleNeutralFrozenPublishInput({
+                source: input.source,
+                content_epoch: input.capture.content_epoch,
+                compilation,
+                embedding: input.embedding_snapshot.materialization,
+                database_bytes: database,
+                database_delivery_bytes: databaseDelivery,
+                view_publish_mobile_bytes: views.mobile,
+                view_publish_pc_bytes: views.pc,
+                runtime_identity: {
+                    runtime_generation: 3,
+                    runtime_contract_hash: compilation.model.trigger_document.runtime_contract_hash,
+                    runtime_major: runtimeMajor,
+                    runtime_patch: runtime.runtime_patch,
+                    runtime_release_id: `runtime3-${runtimeMajor}.${runtime.runtime_patch}`,
+                    protocol_version: protocolVersion,
+                    sdk_schema_version: 3,
+                },
+            });
+        },
+    });
+}
+/** neutral-transfer 在远端 readback 成功后调用；只持久化公开 identity/digest。 */
+export async function writeFrozenReviewTargetBinding(root, binding) {
+    if (binding.schema_version !== 1)
+        fail("E_VALIDATION_FAILED", "review target schema 无效");
+    requireText(binding.project_id, "review target project");
+    requireText(binding.scenario_id, "review target scenario");
+    requireSha(binding.source_digest, "review target source");
+    requireSha(binding.source_head_digest, "review target head");
+    await ensureSafeProjectDirectory(root, ".worldengine");
+    const path = await safeProjectPath(root, REVIEW_TARGET_PATH);
+    const temporary = await safeProjectPath(root, `${REVIEW_TARGET_PATH}.tmp`);
+    await writeFile(temporary, `${JSON.stringify(binding)}\n`, "utf8");
+    await rename(temporary, path);
+    return await readFrozenReviewTargetBinding(root, binding.project_id);
+}
+function currentProfile() {
+    return Object.freeze({
+        schema_version: 1,
+        compiler_release: "tmw3-neutral-compiler-1",
+        runtime_semantics: "tmw3-runtime-contract-v3",
+        sdk_schema: "chatplay-sdk-v3",
+        artifact_format: "artifact-v5-package-2",
+        stage_versions: CURRENT_NEUTRAL_COMPILER_STAGE_VERSIONS,
+    });
+}
+async function captureLocalSource(options) {
+    const sourceReady = await options.read_source_ready();
+    const target = sourceReady.target;
+    if (target.project_id !== options.project_id)
+        fail("E_OPERATION_ID_CONFLICT", "review target project 不匹配");
+    if (!(sourceReady.revision_bytes instanceof Uint8Array)) {
+        fail("E_VALIDATION_FAILED", "source-ready 缺少 canonical Neutral revision bytes");
+    }
+    const sourceBytes = sourceReady.revision_bytes.slice();
+    const sourceDigest = sha256(sourceBytes);
+    if (sourceDigest !== target.source_digest) {
+        fail("E_OPERATION_ID_CONFLICT", "canonical Neutral source 与 upload binding 不匹配");
+    }
+    const epoch = requirePositive(sourceReady.content_epoch, "content epoch");
+    const head = sourceReady.head;
+    const ownerId = requireText(head.owner_id, "author source owner");
+    const scenarioId = requireText(head.scenario_id, "author source scenario");
+    const sourceRevision = requirePositive(head.source_revision, "author source revision");
+    const revisionDigest = requireSha(head.revision_digest, "author source revision");
+    const headDigest = requireSha(head.head_digest, "author source head");
+    requireSha(head.manifest_digest, "author source manifest");
+    if (scenarioId !== target.scenario_id
+        || headDigest !== target.source_head_digest
+        || requireSha(head.source_digest, "author source") !== sourceDigest) {
+        fail("E_OPERATION_ID_CONFLICT", "远端 author-source head 与本地 upload binding 不匹配");
+    }
+    const witness = Object.freeze({ ...head });
+    const source = await captureNeutralSourceCompileInput({ witness, source_bytes: sourceBytes });
+    return Object.freeze({
+        public: Object.freeze({
+            project_id: options.project_id,
+            owner_id: ownerId,
+            scenario_id: scenarioId,
+            content_epoch: epoch,
+            source_revision: sourceRevision,
+            source_sha256: sourceDigest,
+            revision_digest: revisionDigest,
+            revision_id: headDigest,
+        }),
+        source,
+    });
+}
+export function createFrozenReviewLocalPipeline(options) {
+    const captures = new Map();
+    const compilations = new Map();
+    const embeddings = new Map();
+    return Object.freeze({
+        getPreparedEmbeddingSnapshot(capture) {
+            const prepared = embeddings.get(capture.revision_digest)?.prepared ?? null;
+            if (prepared === null)
+                return null;
+            return prepared.source.scenario_id === capture.scenario_id
+                && prepared.source.source_revision === capture.source_revision
+                && prepared.source.revision_digest === capture.revision_digest
+                ? prepared
+                : null;
+        },
+        async capture() {
+            const captured = await captureLocalSource(options);
+            captures.set(captured.public.revision_digest, captured);
+            return captured.public;
+        },
+        async compile(capture) {
+            const captured = captures.get(capture.revision_digest);
+            if (captured === undefined || captured.public.revision_id !== capture.revision_id) {
+                fail("E_OPERATION_ID_CONFLICT", "compile 未消费本次冻结 capture");
+            }
+            const profile = currentProfile();
+            const admitProfile = options.admit_profile;
+            if (admitProfile === undefined) {
+                fail("E_AUTH_REQUIRED", "Compiler release authority adapter 未配置");
+            }
+            await admitProfile(profile);
+            const outcome = await compileNeutralScenarioSource(captured.source, profile, buildCurrentTmw3NeutralCompilerStageRegistry(profile), compilerCache);
+            if (!outcome.ok) {
+                fail("E_VALIDATION_FAILED", `Neutral source 编译失败：${outcome.diagnostics.map((item) => item.code).join(",")}`);
+            }
+            const value = Object.freeze({
+                public: Object.freeze({
+                    source_revision_digest: capture.revision_digest,
+                    compiler_receipt_sha256: requireSha(outcome.receipt.receipt_sha256, "compiler receipt"),
+                }),
+                profile,
+                outcome,
+            });
+            compilations.set(capture.revision_digest, value);
+            return value.public;
+        },
+        async embed(capture, compilation, signal) {
+            const captured = captures.get(capture.revision_digest);
+            const compiled = compilations.get(capture.revision_digest);
+            if (captured === undefined || compiled === undefined
+                || compiled.public.compiler_receipt_sha256 !== compilation.compiler_receipt_sha256) {
+                fail("E_OPERATION_ID_CONFLICT", "embedding 未消费本次冻结 compilation");
+            }
+            const graph = await options.assembler.embeddingGraph({
+                capture,
+                source: captured.source,
+                profile: compiled.profile,
+                compilation: compiled.outcome,
+            });
+            const recalled = await options.read_prepared_embedding_snapshot?.(capture) ?? null;
+            if (recalled !== null) {
+                if (recalled.source.owner_id !== capture.owner_id
+                    || recalled.source.scenario_id !== capture.scenario_id
+                    || recalled.source.source_revision !== capture.source_revision
+                    || recalled.source.revision_digest !== capture.revision_digest
+                    || recalled.batch.entries.length !== graph.entities.length
+                    || recalled.materialization.vector_by_entity_id.size !== graph.entities.length) {
+                    fail("E_OPERATION_ID_CONFLICT", "Host prepared embedding snapshot 与 captured source 不匹配");
+                }
+                const value = Object.freeze({
+                    public: Object.freeze({
+                        source_revision_digest: capture.revision_digest,
+                        descriptor_sha256: recalled.batch.descriptor.descriptor_sha256,
+                        vector_count: recalled.batch.entries.length,
+                    }),
+                    vectors: recalled.materialization.vector_by_entity_id,
+                    prepared: recalled,
+                });
+                embeddings.set(capture.revision_digest, value);
+                return value.public;
+            }
+            const { prepareNeutralArtifactEmbeddingSnapshot } = await import("@world-engines/scenario-review-snapshot");
+            const prepared = await prepareNeutralArtifactEmbeddingSnapshot(graph, {
+                owner_id: capture.owner_id,
+                scenario_id: capture.scenario_id,
+                source_revision: capture.source_revision,
+                revision_digest: capture.revision_digest,
+            }, options.run_embedding_batch, signal);
+            const vectorMap = prepared.materialization.vector_by_entity_id;
+            const value = Object.freeze({
+                public: Object.freeze({
+                    source_revision_digest: capture.revision_digest,
+                    descriptor_sha256: prepared.batch.descriptor.descriptor_sha256,
+                    vector_count: vectorMap.size,
+                }),
+                vectors: vectorMap,
+                prepared,
+            });
+            embeddings.set(capture.revision_digest, value);
+            return value.public;
+        },
+        async freeze(capture, compilation, embedding, signal) {
+            const captured = captures.get(capture.revision_digest);
+            const compiled = compilations.get(capture.revision_digest);
+            const embedded = embeddings.get(capture.revision_digest);
+            if (captured === undefined || compiled === undefined || embedded === undefined
+                || compiled.public.compiler_receipt_sha256 !== compilation.compiler_receipt_sha256
+                || embedded.public.descriptor_sha256 !== embedding.descriptor_sha256
+                || embedded.public.vector_count !== embedding.vector_count) {
+                fail("E_OPERATION_ID_CONFLICT", "freeze 未消费本次冻结 pipeline identity");
+            }
+            return await options.assembler.assemble({
+                capture,
+                source: captured.source,
+                profile: compiled.profile,
+                compilation: compiled.outcome,
+                embedding,
+                vectors: embedded.vectors,
+                embedding_snapshot: embedded.prepared,
+                ...(signal === undefined ? {} : { signal }),
+            });
+        },
+    });
+}

package/dist/frozen-review-source-capture.d.ts

@@ -0,0 +1,15 @@
+import { type CreateFrozenReviewLocalPipelineOptions } from "./frozen-review-local-pipeline.js";
+import { type FrozenReviewWasmEncryptor } from "./frozen-review-wasm-encryptor.js";
+import type { ProjectTransferTransport } from "./transfer/transport.js";
+export interface CreateFrozenReviewSourceCaptureOptions {
+    readonly project_root: string;
+    readonly project_id: string;
+    readonly transport: ProjectTransferTransport | undefined;
+    /** 测试 seam；production 默认使用与 Browser 相同的 Rust/WASM scenario-key 算法。 */
+    readonly crypto?: Pick<FrozenReviewWasmEncryptor, "decrypt">;
+}
+/**
+ * 为 standalone Node review 提供真实 read_source_ready。所有远端读取都经过 project-bound
+ * ProjectAuth transport；返回值只含已解密并逐 digest 校验的 canonical Neutral revision。
+ */
+export declare function createFrozenReviewSourceCapture(options: CreateFrozenReviewSourceCaptureOptions): CreateFrozenReviewLocalPipelineOptions["read_source_ready"];