@world-engines/scenario-review-snapshot 0.0.0

package/dist/snapshot.js

@@ -0,0 +1,701 @@
+import { appendJsonPointer, canonicalJson, compareUtf8, parseJsonPointer, sha256Hex, toJsonValue, utf8ByteLength, } from "./canonical.js";
+export const DEFAULT_SCENARIO_REVIEW_SNAPSHOT_LIMITS = Object.freeze({
+    max_chunk_bytes: 48 * 1024,
+    max_overlap_bytes: 4 * 1024,
+    max_snapshot_bytes: 16 * 1024 * 1024,
+    max_records: 200_000,
+    max_fragments: 1_000_000,
+    max_chunks: 4_096,
+    max_value_depth: 64,
+});
+const SECTION_ORDER = [
+    "metadata", "world", "triggers", "view_mobile", "view_pc",
+];
+const RECORD_KIND_ORDER = ["meta", "node", "attr", "edge", "trigger", "view"];
+const SHA256_PATTERN = /^[0-9a-f]{64}$/u;
+const TECHNICAL_NODE_FIELDS = new Set(["embedding", "embeddingHash", "position", "needs_review"]);
+const TECHNICAL_EDGE_FIELDS = new Set(["embedding", "embeddingHash", "needs_review"]);
+const TECHNICAL_ATTR_FIELDS = new Set(["embedding", "embeddingHash", "position", "needs_review"]);
+function isTechnicalAttrField(key) {
+    return TECHNICAL_ATTR_FIELDS.has(key) || ["base64", "raw_base64", "vector"].includes(key) ||
+        key.endsWith("_base64") || key.endsWith("_embedding") || key.endsWith("_vector");
+}
+export function stableRelationId(edge) {
+    const object = requireObject(edge, "scenario_review_edge_object_required");
+    const existing = optionalNonEmptyString(object.relation_id);
+    if (existing)
+        return existing;
+    const from = requireNonEmptyString(object.from_id, "scenario_review_edge_from_id_required");
+    const kind = requireNonEmptyString(object.kind, "scenario_review_edge_kind_required");
+    const to = requireNonEmptyString(object.to_id, "scenario_review_edge_to_id_required");
+    return `relation_${sha256Hex(canonicalJson([from, kind, to])).slice(0, 32)}`;
+}
+export function buildScenarioReviewSnapshot(rawInput, rawLimits = {}) {
+    const limits = normalizeLimits(rawLimits);
+    validateEnvelope(rawInput);
+    const input = normalizeInput(rawInput, limits.max_value_depth);
+    const records = buildRecordStream(input);
+    if (records.length > limits.max_records)
+        throw new Error("scenario_review_record_limit_exceeded");
+    assertUnique(records.map((record) => record.record_id), "scenario_review_record_id_duplicate");
+    let recordStreamBytes = 0;
+    for (const record of records) {
+        recordStreamBytes = checkedAdd(recordStreamBytes, utf8ByteLength(canonicalRecordLine(record)) + 1);
+        if (recordStreamBytes > limits.max_snapshot_bytes) {
+            throw new Error("scenario_review_snapshot_size_limit_exceeded");
+        }
+    }
+    const fragments = [];
+    for (const record of records) {
+        fragments.push(...splitRecord(record, limits));
+        if (fragments.length > limits.max_fragments) {
+            throw new Error("scenario_review_fragment_limit_exceeded");
+        }
+    }
+    assertUnique(fragments.map((fragment) => fragment.fragment_id), "scenario_review_fragment_id_duplicate");
+    const chunks = buildChunks(fragments, limits);
+    if (chunks.length > limits.max_chunks)
+        throw new Error("scenario_review_chunk_limit_exceeded");
+    const coverage = buildCoverage(records, fragments, chunks);
+    validateCoverage(records, fragments, chunks, coverage);
+    const core = {
+        snapshot_schema_version: 1,
+        ticket_id: input.ticket_id,
+        scenario_id: input.scenario_id,
+        created_at: input.created_at,
+        canonical_artifact_digest: input.canonical_artifact_digest,
+        records,
+        fragments,
+        chunks,
+        coverage,
+    };
+    const snapshot_hash = sha256Hex(canonicalJson(toJsonValue(core)));
+    const snapshot = { ...core, snapshot_hash };
+    if (utf8ByteLength(canonicalJson(toJsonValue(snapshot))) > limits.max_snapshot_bytes) {
+        throw new Error("scenario_review_snapshot_size_limit_exceeded");
+    }
+    return snapshot;
+}
+export function reconstructRecordPayload(record, fragments) {
+    const selected = fragments.filter((fragment) => fragment.record_id === record.record_id);
+    if (selected.length === 0)
+        throw new Error("scenario_review_record_fragments_missing");
+    let root;
+    const strings = new Map();
+    for (const fragment of selected) {
+        if (fragment.value_kind === "string_segment") {
+            const list = strings.get(fragment.value_pointer) ?? [];
+            list.push(fragment);
+            strings.set(fragment.value_pointer, list);
+            continue;
+        }
+        const value = fragment.value_kind === "container"
+            ? fragment.container_kind === "array" ? [] : {}
+            : fragment.payload;
+        if (value === undefined)
+            throw new Error("scenario_review_fragment_payload_missing");
+        root = assignJsonPointer(root, fragment.value_pointer, value);
+    }
+    for (const [pointer, parts] of strings) {
+        parts.sort((a, b) => (a.string_offset_bytes ?? -1) - (b.string_offset_bytes ?? -1));
+        let expectedOffset = 0;
+        let total = -1;
+        let value = "";
+        for (const part of parts) {
+            if (part.string_offset_bytes !== expectedOffset || typeof part.string_segment !== "string") {
+                throw new Error("scenario_review_string_fragment_gap");
+            }
+            total = part.string_total_bytes ?? -1;
+            value += part.string_segment;
+            expectedOffset += utf8ByteLength(part.string_segment);
+        }
+        if (total !== expectedOffset)
+            throw new Error("scenario_review_string_fragment_incomplete");
+        root = assignJsonPointer(root, pointer, value);
+    }
+    if (root === undefined)
+        throw new Error("scenario_review_record_reconstruct_empty");
+    if (sha256Hex(canonicalJson(root)) !== record.canonical_payload_hash) {
+        throw new Error("scenario_review_record_reconstruct_hash_mismatch");
+    }
+    return root;
+}
+function normalizeInput(input, maxDepth) {
+    return {
+        ticket_id: input.ticket_id,
+        scenario_id: input.scenario_id,
+        created_at: input.created_at,
+        canonical_artifact_digest: input.canonical_artifact_digest,
+        metadata: toJsonValue(input.metadata, maxDepth),
+        nodes: input.nodes.map((value) => toJsonValue(value, maxDepth)),
+        edges: input.edges.map((value) => toJsonValue(value, maxDepth)),
+        triggers: input.triggers.map((value) => toJsonValue(value, maxDepth)),
+        ...(input.supplemental_records === undefined ? {} : {
+            supplemental_records: input.supplemental_records.map((record) => ({
+                record_kind: record.record_kind,
+                section: record.section,
+                record_id: record.record_id,
+                json_pointer: record.json_pointer,
+                payload: toJsonValue(record.payload, maxDepth),
+            })),
+        }),
+        view_publish_mobile: input.view_publish_mobile,
+        view_publish_pc: input.view_publish_pc,
+    };
+}
+function validateEnvelope(input) {
+    requireNonEmptyString(input.ticket_id, "scenario_review_ticket_id_required");
+    requireNonEmptyString(input.scenario_id, "scenario_review_scenario_id_required");
+    if (!Number.isSafeInteger(input.created_at) || input.created_at < 0) {
+        throw new Error("scenario_review_created_at_invalid");
+    }
+    if (!SHA256_PATTERN.test(input.canonical_artifact_digest)) {
+        throw new Error("scenario_review_artifact_digest_invalid");
+    }
+    if (typeof input.view_publish_mobile !== "string" || typeof input.view_publish_pc !== "string") {
+        throw new Error("scenario_review_view_text_required");
+    }
+}
+function normalizeLimits(raw) {
+    const limits = { ...DEFAULT_SCENARIO_REVIEW_SNAPSHOT_LIMITS, ...raw };
+    for (const [key, value] of Object.entries(limits)) {
+        if (!Number.isSafeInteger(value) || value <= 0)
+            throw new Error(`scenario_review_${key}_invalid`);
+    }
+    if (limits.max_overlap_bytes >= limits.max_chunk_bytes) {
+        throw new Error("scenario_review_overlap_limit_invalid");
+    }
+    return limits;
+}
+function buildRecordStream(input) {
+    const records = [];
+    let sourceDocumentCount = 0;
+    let sourceChunkCount = 0;
+    let sourceRawBytes = 0;
+    records.push(createRecord("meta", "metadata", "meta", "/metadata", input.metadata));
+    for (const record of input.supplemental_records ?? []) {
+        validateRecordKindSection(record.record_kind, record.section);
+        parseJsonPointer(record.json_pointer);
+        records.push(createRecord(record.record_kind, record.section, requireNonEmptyString(record.record_id, "scenario_review_record_id_required"), record.json_pointer, record.payload));
+    }
+    const nodes = input.nodes.map((node) => {
+        const object = requireObject(node, "scenario_review_node_object_required");
+        const id = requireNonEmptyString(object.entity_id, "scenario_review_node_id_required");
+        return { id, object };
+    }).sort((a, b) => compareUtf8(a.id, b.id));
+    assertUnique(nodes.map((node) => node.id), "scenario_review_node_id_duplicate");
+    for (const { id, object } of nodes) {
+        const kind = requireNonEmptyString(object.kind, "scenario_review_node_kind_required");
+        const props = object.props === undefined ? {} : requireObject(object.props, "scenario_review_node_props_object_required");
+        const nodePayload = {};
+        for (const key of Object.keys(object).sort(compareUtf8)) {
+            if (key !== "props" && !TECHNICAL_NODE_FIELDS.has(key))
+                nodePayload[key] = object[key];
+        }
+        const nodePointer = appendJsonPointer(sourceNodePointerRoot(kind), id);
+        records.push(createRecord("node", "world", `node:${id}`, nodePointer, nodePayload));
+        const decodedSource = sourceNodePointerRoot(kind) !== "/nodes"
+            ? decodeSourceDocument(props)
+            : undefined;
+        if (decodedSource !== undefined) {
+            if (sourceNodePointerRoot(kind) === "/source/documents") {
+                sourceDocumentCount += 1;
+                sourceRawBytes = checkedAdd(sourceRawBytes, decodedSource.sizeBytes);
+            }
+            records.push(createRecord("attr", "world", `attr:${id}:source-text`, appendJsonPointer(nodePointer, "source_text"), decodedSource.text));
+            records.push(createRecord("attr", "world", `attr:${id}:source-identity`, appendJsonPointer(nodePointer, "source_identity"), {
+                encoding: "base64",
+                sha256: decodedSource.sha256,
+                size_bytes: decodedSource.sizeBytes,
+            }));
+        }
+        if (sourceNodePointerRoot(kind) === "/source/chunks")
+            sourceChunkCount += 1;
+        for (const key of Object.keys(props).sort(compareUtf8)) {
+            if (isTechnicalAttrField(key) ||
+                decodedSource !== undefined && (key === "raw_base64" || key === "sha256"))
+                continue;
+            appendLeafRecords(records, `attr:${id}`, appendJsonPointer(appendJsonPointer(nodePointer, "props"), key), props[key]);
+        }
+    }
+    records.push(createRecord("meta", "metadata", "database:source-coverage-input", "/database/source_coverage_input", {
+        source_chunk_count: sourceChunkCount,
+        source_document_count: sourceDocumentCount,
+        source_raw_bytes: sourceRawBytes,
+    }));
+    const edges = input.edges.map((edge) => {
+        const object = requireObject(edge, "scenario_review_edge_object_required");
+        const id = stableRelationId(object);
+        const payload = { ...object, relation_id: id };
+        for (const field of TECHNICAL_EDGE_FIELDS)
+            delete payload[field];
+        const nested = [];
+        for (const field of ["props", "fields", "trigger", "source_refs"]) {
+            const value = payload[field];
+            if (value !== undefined) {
+                nested.push([field, value]);
+                delete payload[field];
+            }
+        }
+        const kind = requireNonEmptyString(payload.kind, "scenario_review_edge_kind_required");
+        const pointerRoot = sourceNodePointerRoot(kind) === "/nodes" ? "/edges" : "/source/relations";
+        return { id, payload, nested, pointerRoot };
+    }).sort((a, b) => compareUtf8(a.id, b.id));
+    assertUnique(edges.map((edge) => edge.id), "scenario_review_relation_id_duplicate");
+    for (const edge of edges) {
+        const edgePointer = appendJsonPointer(edge.pointerRoot, edge.id);
+        records.push(createRecord("edge", "world", `edge:${edge.id}`, edgePointer, edge.payload));
+        for (const [field, value] of edge.nested) {
+            appendLeafRecords(records, `edge-attr:${edge.id}`, appendJsonPointer(edgePointer, field), value);
+        }
+    }
+    const triggers = input.triggers.map((trigger) => {
+        const object = requireObject(trigger, "scenario_review_trigger_object_required");
+        const id = optionalNonEmptyString(object.trigger_id) ?? optionalNonEmptyString(object.id);
+        if (!id)
+            throw new Error("scenario_review_trigger_id_required");
+        return { id, object };
+    }).sort((a, b) => compareUtf8(a.id, b.id));
+    assertUnique(triggers.map((trigger) => trigger.id), "scenario_review_trigger_id_duplicate");
+    for (const trigger of triggers) {
+        records.push(createRecord("trigger", "triggers", `trigger:${trigger.id}`, appendJsonPointer("/triggers", trigger.id), trigger.object));
+    }
+    records.push(createRecord("view", "view_mobile", "view:mobile", "/views/mobile", input.view_publish_mobile));
+    records.push(createRecord("view", "view_pc", "view:pc", "/views/pc", input.view_publish_pc));
+    return records.sort(compareRecords);
+}
+function sourceNodePointerRoot(kind) {
+    const normalized = kind.toLocaleLowerCase("en-US").replace(/[- /]/gu, "_");
+    if (normalized === "source_document" || normalized.endsWith("_source_document"))
+        return "/source/documents";
+    if (normalized === "source_chunk" || normalized.endsWith("_source_chunk"))
+        return "/source/chunks";
+    if (normalized === "control" || normalized.startsWith("source_") ||
+        normalized.startsWith("world_source_") || normalized.endsWith("_control"))
+        return "/source/control";
+    return "/nodes";
+}
+function decodeSourceDocument(props) {
+    const encodedValue = props.raw_base64;
+    if (encodedValue === undefined)
+        return undefined;
+    const encoded = sourcePropString(encodedValue);
+    if (encoded === undefined)
+        throw new Error("frozen_review_source_raw_base64_invalid");
+    const expectedSha256 = sourcePropString(props.sha256);
+    if (expectedSha256 === undefined || !SHA256_PATTERN.test(expectedSha256)) {
+        throw new Error("frozen_review_source_raw_sha256_invalid");
+    }
+    let binary;
+    try {
+        binary = atob(encoded);
+    }
+    catch {
+        throw new Error("frozen_review_source_raw_base64_invalid");
+    }
+    if (btoa(binary) !== encoded)
+        throw new Error("frozen_review_source_raw_base64_noncanonical");
+    const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+    if (sha256Hex(bytes) !== expectedSha256)
+        throw new Error("frozen_review_source_raw_sha256_mismatch");
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw new Error("frozen_review_source_raw_utf8_invalid");
+    }
+    return { text, sha256: expectedSha256, sizeBytes: bytes.byteLength };
+}
+function sourcePropString(value) {
+    if (typeof value === "string")
+        return value;
+    if (value !== null && typeof value === "object" && !Array.isArray(value) && typeof value.value === "string") {
+        return value.value;
+    }
+    return undefined;
+}
+function appendLeafRecords(records, recordIdPrefix, pointer, value) {
+    if (Array.isArray(value)) {
+        if (value.length === 0) {
+            records.push(createRecord("attr", "world", `${recordIdPrefix}:${pointer}`, pointer, value));
+            return;
+        }
+        value.forEach((item, index) => appendLeafRecords(records, recordIdPrefix, appendJsonPointer(pointer, index), item));
+        return;
+    }
+    if (value !== null && typeof value === "object") {
+        const keys = Object.keys(value).sort(compareUtf8);
+        if (keys.length === 0) {
+            records.push(createRecord("attr", "world", `${recordIdPrefix}:${pointer}`, pointer, value));
+            return;
+        }
+        for (const key of keys) {
+            if (isTechnicalAttrField(key))
+                continue;
+            appendLeafRecords(records, recordIdPrefix, appendJsonPointer(pointer, key), value[key]);
+        }
+        return;
+    }
+    records.push(createRecord("attr", "world", `${recordIdPrefix}:${pointer}`, pointer, value));
+}
+function validateRecordKindSection(recordKind, section) {
+    const valid = (recordKind === "meta" && section === "metadata") ||
+        ["node", "attr", "edge"].includes(recordKind) && section === "world" ||
+        recordKind === "trigger" && section === "triggers" ||
+        recordKind === "view" && (section === "view_mobile" || section === "view_pc");
+    if (!valid)
+        throw new Error("scenario_review_record_section_invalid");
+}
+function createRecord(record_kind, section, record_id, json_pointer, payload) {
+    const normalized = toJsonValue(payload);
+    return {
+        record_kind,
+        section,
+        record_id,
+        json_pointer,
+        payload: normalized,
+        canonical_payload_hash: sha256Hex(canonicalJson(normalized)),
+    };
+}
+function compareRecords(a, b) {
+    const section = SECTION_ORDER.indexOf(a.section) - SECTION_ORDER.indexOf(b.section);
+    if (section !== 0)
+        return section;
+    const kind = RECORD_KIND_ORDER.indexOf(a.record_kind) - RECORD_KIND_ORDER.indexOf(b.record_kind);
+    return kind !== 0 ? kind : compareUtf8(a.record_id, b.record_id);
+}
+function splitRecord(record, limits) {
+    // 任一 fragment 都必须能完整进入下一块 overlap，保证相邻块至少共享一个语义单元。
+    const primaryCapacity = Math.min(limits.max_chunk_bytes - limits.max_overlap_bytes, limits.max_overlap_bytes);
+    const whole = fragmentBase(record, "", "json", { payload: record.payload });
+    if (fragmentLineBytes(whole) <= primaryCapacity)
+        return [{ ...whole, fragment_id: `${record.record_id}#0` }];
+    const raw = [];
+    decomposeValue(record, record.payload, "", 0, primaryCapacity, limits.max_value_depth, raw);
+    return raw.map((fragment, index) => ({ ...fragment, fragment_id: `${record.record_id}#${index}` }));
+}
+function decomposeValue(record, value, pointer, depth, capacity, maxDepth, out) {
+    if (depth > maxDepth)
+        throw new Error("scenario_review_value_depth_limit_exceeded");
+    const whole = fragmentBase(record, pointer, "json", { payload: value });
+    if (fragmentLineBytes(whole) <= capacity) {
+        out.push(whole);
+        return;
+    }
+    if (typeof value === "string") {
+        splitLongString(record, value, pointer, capacity, out);
+        return;
+    }
+    if (value === null || typeof value !== "object") {
+        throw new Error("scenario_review_fragment_capacity_exceeded");
+    }
+    const container = fragmentBase(record, pointer, "container", {
+        container_kind: Array.isArray(value) ? "array" : "object",
+    });
+    if (fragmentLineBytes(container) > capacity)
+        throw new Error("scenario_review_fragment_capacity_exceeded");
+    out.push(container);
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index += 1) {
+            decomposeValue(record, value[index], appendJsonPointer(pointer, index), depth + 1, capacity, maxDepth, out);
+        }
+    }
+    else {
+        for (const key of Object.keys(value).sort(compareUtf8)) {
+            decomposeValue(record, value[key], appendJsonPointer(pointer, key), depth + 1, capacity, maxDepth, out);
+        }
+    }
+}
+function splitLongString(record, value, pointer, capacity, out) {
+    const codepoints = [...value];
+    const total = utf8ByteLength(value);
+    let index = 0;
+    let offset = 0;
+    while (index < codepoints.length) {
+        let low = index + 1;
+        let high = codepoints.length;
+        let accepted = index;
+        while (low <= high) {
+            const middle = Math.floor((low + high) / 2);
+            const segment = codepoints.slice(index, middle).join("");
+            const candidate = fragmentBase(record, pointer, "string_segment", {
+                string_segment: segment,
+                string_offset_bytes: offset,
+                string_total_bytes: total,
+            });
+            if (fragmentLineBytes(candidate) <= capacity) {
+                accepted = middle;
+                low = middle + 1;
+            }
+            else {
+                high = middle - 1;
+            }
+        }
+        if (accepted === index)
+            throw new Error("scenario_review_fragment_capacity_exceeded");
+        const segment = codepoints.slice(index, accepted).join("");
+        out.push(fragmentBase(record, pointer, "string_segment", {
+            string_segment: segment,
+            string_offset_bytes: offset,
+            string_total_bytes: total,
+        }));
+        offset += utf8ByteLength(segment);
+        index = accepted;
+    }
+    if (codepoints.length === 0)
+        throw new Error("scenario_review_fragment_capacity_exceeded");
+}
+function fragmentBase(record, value_pointer, value_kind, extra) {
+    const base = {
+        record_id: record.record_id,
+        record_kind: record.record_kind,
+        section: record.section,
+        record_pointer: record.json_pointer,
+        value_pointer,
+        value_kind,
+    };
+    return { ...base, ...withoutUndefined(extra) };
+}
+function buildChunks(fragments, limits) {
+    if (fragments.length === 0)
+        throw new Error("scenario_review_fragments_empty");
+    const primaryCapacity = limits.max_chunk_bytes - limits.max_overlap_bytes;
+    const groups = [];
+    let current = [];
+    let currentBytes = 0;
+    for (const fragment of fragments) {
+        const bytes = primaryLineBytes(fragment);
+        if (bytes > primaryCapacity)
+            throw new Error("scenario_review_fragment_capacity_exceeded");
+        if (current.length > 0 &&
+            (currentBytes + bytes > primaryCapacity || current.at(-1).section !== fragment.section)) {
+            groups.push(current);
+            current = [];
+            currentBytes = 0;
+        }
+        current.push(fragment);
+        currentBytes += bytes;
+    }
+    if (current.length > 0)
+        groups.push(current);
+    if (groups.length > limits.max_chunks)
+        throw new Error("scenario_review_chunk_limit_exceeded");
+    const chunks = [];
+    for (let index = 0; index < groups.length; index += 1) {
+        const primary = groups[index];
+        const overlap = [];
+        let overlapBytes = 0;
+        if (index > 0 && groups[index - 1].at(-1).section === primary[0].section) {
+            const prior = groups[index - 1];
+            for (let cursor = prior.length - 1; cursor >= 0; cursor -= 1) {
+                const fragment = prior[cursor];
+                const bytes = overlapLineBytes(fragment);
+                if (overlapBytes + bytes > limits.max_overlap_bytes)
+                    break;
+                overlap.unshift(fragment);
+                overlapBytes += bytes;
+            }
+        }
+        const lines = [
+            ...overlap.map((fragment) => renderChunkLine("overlap", fragment)),
+            ...primary.map((fragment) => renderChunkLine("primary", fragment)),
+        ];
+        const content = lines.join("\n");
+        const byte_length = utf8ByteLength(content);
+        if (byte_length > limits.max_chunk_bytes)
+            throw new Error("scenario_review_chunk_size_limit_exceeded");
+        chunks.push({
+            chunk_index: index,
+            primary_fragment_ids: primary.map((fragment) => fragment.fragment_id),
+            overlap_fragment_ids: overlap.map((fragment) => fragment.fragment_id),
+            content,
+            byte_length,
+            chunk_hash: sha256Hex(content),
+        });
+    }
+    return chunks;
+}
+function buildCoverage(records, fragments, chunks) {
+    const primaryOwners = new Map();
+    for (const chunk of chunks) {
+        for (const id of chunk.primary_fragment_ids) {
+            const owners = primaryOwners.get(id) ?? [];
+            owners.push(chunk.chunk_index);
+            primaryOwners.set(id, owners);
+        }
+    }
+    const expectedPrimaryOrder = fragments.map((fragment) => fragment.fragment_id);
+    const actualPrimaryOrder = chunks.flatMap((chunk) => chunk.primary_fragment_ids);
+    if (actualPrimaryOrder.length !== expectedPrimaryOrder.length ||
+        actualPrimaryOrder.some((id, index) => id !== expectedPrimaryOrder[index])) {
+        throw new Error("scenario_review_primary_stream_reconstruction_invalid");
+    }
+    const coverageRecords = records.map((record) => {
+        const ids = fragments.filter((fragment) => fragment.record_id === record.record_id).map((fragment) => fragment.fragment_id);
+        const indexes = [...new Set(ids.flatMap((id) => primaryOwners.get(id) ?? []))].sort((a, b) => a - b);
+        return {
+            record_id: record.record_id,
+            record_kind: record.record_kind,
+            section: record.section,
+            json_pointer: record.json_pointer,
+            record_hash: record.canonical_payload_hash,
+            fragment_ids: ids,
+            primary_chunk_indexes: indexes,
+        };
+    });
+    const sections = SECTION_ORDER.map((section) => {
+        const sectionRecords = records.filter((record) => record.section === section);
+        const sectionFragments = fragments.filter((fragment) => fragment.section === section);
+        const indexes = [...new Set(sectionFragments.flatMap((fragment) => primaryOwners.get(fragment.fragment_id) ?? []))].sort((a, b) => a - b);
+        return {
+            section,
+            record_count: sectionRecords.length,
+            fragment_count: sectionFragments.length,
+            canonical_stream_hash: sha256Hex(sectionRecords.map(canonicalRecordLine).join("\n")),
+            first_chunk_index: indexes[0] ?? null,
+            last_chunk_index: indexes.at(-1) ?? null,
+        };
+    });
+    const ownerCounts = fragments.map((fragment) => primaryOwners.get(fragment.fragment_id)?.length ?? 0);
+    const core = {
+        records: coverageRecords,
+        sections,
+        canonical_record_count: records.length,
+        canonical_fragment_count: fragments.length,
+        primary_coverage_count: ownerCounts.filter((count) => count === 1).length,
+        overlap_reference_count: chunks.reduce((sum, chunk) => sum + chunk.overlap_fragment_ids.length, 0),
+        missing_primary_count: ownerCounts.filter((count) => count === 0).length,
+        duplicate_primary_count: ownerCounts.filter((count) => count > 1).length,
+        chunk_count: chunks.length,
+    };
+    return { ...core, coverage_hash: sha256Hex(canonicalJson(toJsonValue(core))) };
+}
+function validateCoverage(records, fragments, chunks, coverage) {
+    if (coverage.missing_primary_count !== 0 || coverage.duplicate_primary_count !== 0 ||
+        coverage.primary_coverage_count !== fragments.length) {
+        throw new Error("scenario_review_primary_coverage_invalid");
+    }
+    const fragmentIds = new Set(fragments.map((fragment) => fragment.fragment_id));
+    for (const chunk of chunks) {
+        for (const id of [...chunk.primary_fragment_ids, ...chunk.overlap_fragment_ids]) {
+            if (!fragmentIds.has(id))
+                throw new Error("scenario_review_chunk_fragment_unknown");
+        }
+        if (sha256Hex(chunk.content) !== chunk.chunk_hash || utf8ByteLength(chunk.content) !== chunk.byte_length) {
+            throw new Error("scenario_review_chunk_hash_mismatch");
+        }
+    }
+    for (const record of records)
+        reconstructRecordPayload(record, fragments);
+    const core = {
+        records: coverage.records,
+        sections: coverage.sections,
+        canonical_record_count: coverage.canonical_record_count,
+        canonical_fragment_count: coverage.canonical_fragment_count,
+        primary_coverage_count: coverage.primary_coverage_count,
+        overlap_reference_count: coverage.overlap_reference_count,
+        missing_primary_count: coverage.missing_primary_count,
+        duplicate_primary_count: coverage.duplicate_primary_count,
+        chunk_count: coverage.chunk_count,
+    };
+    if (sha256Hex(canonicalJson(toJsonValue(core))) !== coverage.coverage_hash) {
+        throw new Error("scenario_review_coverage_hash_mismatch");
+    }
+}
+function canonicalRecordLine(record) {
+    return canonicalJson(toJsonValue(record));
+}
+function renderChunkLine(role, fragment) {
+    return canonicalJson(toJsonValue({ role, fragment }));
+}
+function primaryLineBytes(fragment) {
+    return utf8ByteLength(renderChunkLine("primary", fragment)) + 1;
+}
+function overlapLineBytes(fragment) {
+    return utf8ByteLength(renderChunkLine("overlap", fragment)) + 1;
+}
+function fragmentLineBytes(fragment) {
+    // fragment_id 在拆分完成后才按序号赋值；用最大合法序号预留，避免赋值后突破容量。
+    const sized = { ...fragment, fragment_id: `${fragment.record_id}#999999` };
+    return Math.max(utf8ByteLength(canonicalJson(toJsonValue({ role: "primary", fragment: sized }))) + 1, utf8ByteLength(canonicalJson(toJsonValue({ role: "overlap", fragment: sized }))) + 1);
+}
+function assignJsonPointer(root, pointer, value) {
+    const tokens = parseJsonPointer(pointer);
+    if (tokens.length === 0)
+        return cloneJson(value);
+    if (root === undefined || root === null || typeof root !== "object") {
+        throw new Error("scenario_review_fragment_parent_missing");
+    }
+    let current = root;
+    for (let index = 0; index < tokens.length - 1; index += 1) {
+        const token = tokens[index];
+        current = readChild(current, token);
+    }
+    const finalToken = tokens.at(-1);
+    if (Array.isArray(current)) {
+        const index = parseArrayIndex(finalToken);
+        if (index !== current.length)
+            throw new Error("scenario_review_fragment_array_order_invalid");
+        current.push(cloneJson(value));
+    }
+    else if (current !== null && typeof current === "object") {
+        current[finalToken] = cloneJson(value);
+    }
+    else {
+        throw new Error("scenario_review_fragment_parent_invalid");
+    }
+    return root;
+}
+function readChild(parent, token) {
+    if (Array.isArray(parent)) {
+        const child = parent[parseArrayIndex(token)];
+        if (child === undefined)
+            throw new Error("scenario_review_fragment_parent_missing");
+        return child;
+    }
+    if (parent !== null && typeof parent === "object") {
+        const child = parent[token];
+        if (child === undefined)
+            throw new Error("scenario_review_fragment_parent_missing");
+        return child;
+    }
+    throw new Error("scenario_review_fragment_parent_invalid");
+}
+function parseArrayIndex(token) {
+    if (!/^(0|[1-9][0-9]*)$/u.test(token))
+        throw new Error("scenario_review_fragment_array_index_invalid");
+    const value = Number(token);
+    if (!Number.isSafeInteger(value))
+        throw new Error("scenario_review_fragment_array_index_invalid");
+    return value;
+}
+function cloneJson(value) {
+    return JSON.parse(canonicalJson(value));
+}
+function requireObject(value, code) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error(code);
+    return value;
+}
+function requireNonEmptyString(value, code) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        throw new Error(code);
+    return value;
+}
+function optionalNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+function assertUnique(values, code) {
+    if (new Set(values).size !== values.length)
+        throw new Error(code);
+}
+function withoutUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+}
+function checkedAdd(left, right) {
+    const result = left + right;
+    if (!Number.isSafeInteger(result))
+        throw new Error("scenario_review_size_overflow");
+    return result;
+}