@world-engines/scenario-review-snapshot 1.1.3 → 1.1.4

package/dist/artifact-digest.js

@@ -252,6 +252,12 @@ export function parseArtifactV5(value) {
         throw new Error("artifact_v5_required");
     }
     const packageFormat = root.package_format_version;
+    if (packageFormat === EARLIER_LEGACY_ARTIFACT_PACKAGE_FORMAT_VERSION_V5) {
+        // Package V2 缺 immutable database delivery 身份，补默认字段或重算 digest 都会把 legacy
+        // manifest 伪装成 verified V5；只能由 parseLegacyArtifactV5Package2 显式 legacy reader 读取。
+        // 这里给出可路由的 legacy_reader_required 信号，而不是与未知版本共用的 invalid code。
+        throw new Error("artifact_v5_legacy_package_reader_required");
+    }
     if (packageFormat !== LEGACY_ARTIFACT_PACKAGE_FORMAT_VERSION_V5
         && packageFormat !== ARTIFACT_PACKAGE_FORMAT_VERSION_V5 && packageFormat !== 5) {
         throw new Error("artifact_v5_package_format_version_invalid");

package/dist/artifact-stream.d.ts

@@ -0,0 +1,233 @@
+import { type ArtifactV5, type FrozenArtifactBundle, type PublishedArtifactHead, type PublishedArtifactHeadCore, type Sha256Hex } from "./artifact.js";
+export declare const FROZEN_ARTIFACT_STREAM_WIRE_VERSION: 1;
+/**
+ * 有界流的字节预算。数值与 `frozen-artifact-resolver.ts` 的 `FROZEN_STREAM_BUDGET`
+ * 逐字一致；本模块是这一组数字的唯一定义点，两侧都从这里引用。
+ */
+export declare const FROZEN_ARTIFACT_STREAM_BUDGET: Readonly<{
+    /**
+     * 单帧载荷上限：与 edge `ARTIFACT_RESPONSE_STREAM_CHUNK_BYTES` 同值。
+     * base64(16 KiB)=21,848 必须放得进 preRead(32 KiB 行缓冲) 与 preDecode(24 KiB base64 上限)。
+     */
+    readonly chunkSizeBytes: 16384;
+    /**
+     * 常驻内存上限（wire 头 peak_memory_budget_bytes）：与 edge 的
+     * ARTIFACT_STREAM_PEAK_MEMORY_BUDGET_BYTES 同值。它是平台容量上限，不是用户体积配额：
+     * 下发线由 edge isolate 与浏览器把整批 entry 常驻内存（resolver 会为每个 entry 一次性
+     * new Uint8Array(sizeBytes)），65 MiB 已接近 isolate 128 MB 扣掉读取与解帧开销后的容量。
+     * 用户体积限制已在 2026-09-18 全部移除，这里保留的只是平台容量。
+     */
+    readonly peakMemoryBudgetBytes: 68157440;
+    /**
+     * 任一 entry 的统一上限（wire 头 max_entry_bytes）：与 edge 的
+     * ARTIFACT_STREAM_MAX_ENTRY_BYTES 及 frozen-artifact-resolver.ts 的 buffers 判定同值。
+     */
+    readonly maxEntryBytes: 67108864;
+    /**
+     * 历史上非 database / 非 view publication 的 entry 会被额外收紧到 16 KiB；该按 kind 的
+     * 体积拒收已移除：它与 wire 头宣告的 max_entry_bytes（64 MiB）以及 resolver 的统一判定
+     * 自相矛盾，并会拒掉真实规模的对象（诡异复苏 61 节点蓝图的 trigger_semantics 本身
+     * 44,922 B）。保留该键只为兼容既有读取方，取值与 maxEntryBytes 相同：不再有任何按
+     * kind 的体积拒收。
+     */
+    readonly maxRuntimeEntryBytes: 67108864;
+    readonly preReadAllocationCeilingBytes: 32768;
+    readonly preDecodeAllocationCeilingBytes: 24576;
+}>;
+/** index 0 恒为 artifact manifest（ArtifactV5 canonical JSON）。 */
+export declare const FROZEN_ARTIFACT_MANIFEST_ENTRY_KIND: "artifact_manifest";
+export declare const FROZEN_ARTIFACT_MANIFEST_ENTRY_RELATIVE_PATH: "artifact-v5.json";
+/**
+ * manifest + 9 个冻结对象（= resolver 的 FROZEN_OBJECT_ENTRY_COUNT，区别于
+ * artifact.ts 里只数对象的 FROZEN_ARTIFACT_OBJECT_COUNT=9）；10..11 只允许是 view publication。
+ */
+export declare const FROZEN_ARTIFACT_STREAM_BASE_ENTRY_COUNT: 10;
+export declare const FROZEN_ARTIFACT_STREAM_MAX_ENTRY_COUNT: 12;
+/** database delivery entry kind；历史上是唯一走 maxEntryBytes 的非 view publication kind。 */
+export declare const FROZEN_DATABASE_DELIVERY_ENTRY_KIND: "database";
+/** view publication 的 wire kind ↔ device；相对路径直接取自 capture 自身的字面量类型。 */
+export declare const FROZEN_VIEW_PUBLICATION_WIRE_KINDS: Readonly<{
+    readonly mobile: "view_publish_mobile";
+    readonly pc: "view_publish_pc";
+}>;
+export declare function isFrozenViewPublicationEntryKind(kind: string): boolean;
+/**
+ * entry 的字节上限。历史上 database / view publication 走 maxEntryBytes，其余冻结对象被
+ * 额外收紧到 16 KiB；按 kind 的收紧已移除，现在所有 kind 共用 wire 头宣告的统一上限
+ * （与 frozen-artifact-resolver.ts 的 buffers 判定同义）。
+ */
+export declare function frozenArtifactStreamEntryMaxBytes(kind: string): number;
+/** 客户端逐行校验要求 `chunk_count === ceil(size_bytes / chunk_size_bytes)`。 */
+export declare function frozenArtifactStreamEntryChunkCount(sizeBytes: number): number;
+/** 校验所需的最小 entry 形状；不含字节，便于单独测试拒绝矩阵。 */
+export interface FrozenArtifactStreamEntryShape {
+    readonly kind: string;
+    readonly relativePath: string;
+    readonly sizeBytes: number;
+}
+export interface FrozenArtifactStreamEntryDescriptor extends FrozenArtifactStreamEntryShape {
+    readonly sha256: string;
+    readonly chunkCount: number;
+}
+/** 一个待编码对象的字节；顺序即 wire 上的 entry 顺序。 */
+export interface FrozenArtifactStreamEntrySource extends FrozenArtifactStreamEntryShape {
+    readonly bytes: Uint8Array;
+}
+export interface FrozenArtifactStreamHeadLineage {
+    readonly head_revision: number;
+    readonly review_ticket_id: string;
+    readonly review_snapshot_hash: Sha256Hex;
+    readonly review_coverage_hash: Sha256Hex;
+    readonly published_at: number;
+    readonly previous_head_digest: Sha256Hex | null;
+}
+export interface FrozenArtifactStreamPlanOptions {
+    /**
+     * 发布 head。给完整 head（含 `head_digest`）则原样校验；给 head core 则由本模块计算摘要。
+     * 两种形态都必须绑定到 bundle 里的 artifact。
+     */
+    readonly head: PublishedArtifactHeadCore | PublishedArtifactHead;
+    /**
+     * 服务端签发的 `object_set_sha256`。生产路径由发布侧权威签发（客户端只比对
+     * header 与 terminal 一致），因此这里允许显式传入；省略时按有序 entry 身份确定性派生。
+     */
+    readonly objectSetSha256?: string;
+}
+export interface FrozenArtifactStreamPlan {
+    readonly head: PublishedArtifactHead;
+    readonly objectSetSha256: Sha256Hex;
+    readonly entries: readonly FrozenArtifactStreamEntrySource[];
+    readonly descriptors: readonly FrozenArtifactStreamEntryDescriptor[];
+    readonly totalPayloadBytes: number;
+    readonly totalChunks: number;
+}
+export interface FrozenArtifactBoundedStreamAllocationReceipt {
+    readonly phase: "bounded";
+    readonly wireVersion: typeof FROZEN_ARTIFACT_STREAM_WIRE_VERSION;
+    readonly maxEntryBytes: typeof FROZEN_ARTIFACT_STREAM_BUDGET.maxEntryBytes;
+    readonly preReadAllocationCeilingBytes: typeof FROZEN_ARTIFACT_STREAM_BUDGET.preReadAllocationCeilingBytes;
+    readonly preDecodeAllocationCeilingBytes: typeof FROZEN_ARTIFACT_STREAM_BUDGET.preDecodeAllocationCeilingBytes;
+}
+/** 与 ui-shell `ArtifactV5StreamHeader` 同形（字段名与字面量预算一致）。 */
+export interface FrozenArtifactBoundedStreamHeader {
+    readonly wireVersion: typeof FROZEN_ARTIFACT_STREAM_WIRE_VERSION;
+    readonly scenarioId: string;
+    readonly headDigest: Sha256Hex;
+    readonly artifactCanonicalDigest: Sha256Hex;
+    readonly artifactManifestSha256: Sha256Hex;
+    readonly objectSetSha256: Sha256Hex;
+    readonly head: PublishedArtifactHead;
+    readonly chunkSizeBytes: typeof FROZEN_ARTIFACT_STREAM_BUDGET.chunkSizeBytes;
+    readonly peakMemoryBudgetBytes: typeof FROZEN_ARTIFACT_STREAM_BUDGET.peakMemoryBudgetBytes;
+    readonly allocationReceipt: FrozenArtifactBoundedStreamAllocationReceipt;
+    readonly totalPayloadBytes: number;
+    readonly totalChunks: number;
+    readonly entries: readonly FrozenArtifactStreamEntryDescriptor[];
+}
+export interface FrozenArtifactBoundedStreamChunk {
+    readonly sequence: number;
+    readonly entryIndex: number;
+    readonly entryOffset: number;
+    readonly sha256: string;
+    readonly bytes: Uint8Array;
+}
+export interface FrozenArtifactBoundedStreamTerminal {
+    readonly wireVersion: typeof FROZEN_ARTIFACT_STREAM_WIRE_VERSION;
+    readonly headDigest: Sha256Hex;
+    readonly artifactCanonicalDigest: Sha256Hex;
+    readonly objectSetSha256: Sha256Hex;
+    readonly totalPayloadBytes: number;
+    readonly totalChunks: number;
+    readonly payloadSha256: string;
+}
+/** 与 ui-shell `ArtifactV5BoundedStream` 同形。 */
+export interface FrozenArtifactBoundedStream {
+    readonly header: FrozenArtifactBoundedStreamHeader;
+    readonly chunks: AsyncIterable<FrozenArtifactBoundedStreamChunk>;
+    readonly completion: Promise<FrozenArtifactBoundedStreamTerminal>;
+}
+export interface FrozenArtifactStreamHeaderEntryWire {
+    readonly kind: string;
+    readonly relative_path: string;
+    readonly size_bytes: number;
+    readonly sha256: string;
+    readonly chunk_count: number;
+}
+/**
+ * NDJSON header 帧。字段顺序与 edge 生产者的 `head_json` + header 一致，使同一 plan
+ * 在本模块与 Rust 编码器下产出同一批字节（golden 逐字节可比）。
+ */
+export interface FrozenArtifactStreamHeaderWire {
+    readonly type: "header";
+    readonly wire_version: typeof FROZEN_ARTIFACT_STREAM_WIRE_VERSION;
+    readonly scenario_id: string;
+    readonly head: PublishedArtifactHead;
+    readonly head_digest: Sha256Hex;
+    readonly artifact_canonical_digest: Sha256Hex;
+    readonly artifact_manifest_sha256: Sha256Hex;
+    readonly object_set_sha256: Sha256Hex;
+    readonly chunk_size_bytes: number;
+    readonly peak_memory_budget_bytes: number;
+    readonly max_entry_bytes: number;
+    readonly pre_read_allocation_ceiling_bytes: number;
+    readonly pre_decode_allocation_ceiling_bytes: number;
+    readonly total_payload_bytes: number;
+    readonly total_chunks: number;
+    readonly entries: readonly FrozenArtifactStreamHeaderEntryWire[];
+}
+export interface FrozenArtifactStreamChunkWire {
+    readonly type: "chunk";
+    readonly wire_version: typeof FROZEN_ARTIFACT_STREAM_WIRE_VERSION;
+    readonly sequence: number;
+    readonly entry_index: number;
+    readonly entry_offset: number;
+    readonly byte_length: number;
+    readonly sha256: string;
+    readonly bytes_base64: string;
+}
+export interface FrozenArtifactStreamTerminalWire {
+    readonly type: "terminal";
+    readonly wire_version: typeof FROZEN_ARTIFACT_STREAM_WIRE_VERSION;
+    readonly head_digest: Sha256Hex;
+    readonly artifact_canonical_digest: Sha256Hex;
+    readonly object_set_sha256: Sha256Hex;
+    readonly total_payload_bytes: number;
+    readonly total_chunks: number;
+    readonly payload_sha256: string;
+}
+/**
+ * entry 顺序与预算校验。逐条对应 `frozen-artifact-resolver.ts:459-481`（单 entry 上限、
+ * 逐步累计的 peak 预算）与 `:517-543`、`:560`（index 0 为 manifest、1..9 不得是 view
+ * publication、10+ 必须全是 view publication、总数 10..12）。
+ *
+ * kind 是否属于冻结对象集不在这里判断：它已由 `parseFrozenArtifactBundle` 的
+ * `assertBundleMatchesArtifact` 固定，本函数只保证「顺序 / 位置 / 预算」三条不变式。
+ */
+export declare function assertFrozenArtifactStreamEntries(entries: readonly FrozenArtifactStreamEntryShape[]): void;
+/**
+ * 由 artifact 推导一个绑定正确的发布 head。head 的 artifact 侧字段（scenario/epoch/
+ * runtime contract/source revision/canonical digest/manifest sha256）只在这一处取值，
+ * 调用方只提供发布谱系，避免每个生产者各自复算一遍摘要。
+ */
+export declare function buildFrozenArtifactStreamHead(artifact: ArtifactV5, lineage: FrozenArtifactStreamHeadLineage): PublishedArtifactHead;
+/**
+ * bundle → 有序 entry 计划。entry 顺序 = manifest、按相对路径升序的 9 个冻结对象、
+ * mobile 后 pc 的 view publication，与 edge 生产者的写出顺序一致。
+ */
+export declare function buildFrozenArtifactStreamPlan(bundle: FrozenArtifactBundle, options: FrozenArtifactStreamPlanOptions): FrozenArtifactStreamPlan;
+export declare function buildFrozenArtifactBoundedStreamHeader(plan: FrozenArtifactStreamPlan): FrozenArtifactBoundedStreamHeader;
+export declare function buildFrozenArtifactBoundedStreamTerminal(plan: FrozenArtifactStreamPlan): FrozenArtifactBoundedStreamTerminal;
+/** 由已校验计划产出有界流；载荷逐窗口产出，不整包物化。 */
+export declare function encodeFrozenArtifactBoundedStreamFromPlan(plan: FrozenArtifactStreamPlan): FrozenArtifactBoundedStream;
+/** bundle → 有界流（= `buildFrozenArtifactStreamPlan` + `encodeFrozenArtifactBoundedStreamFromPlan`）。 */
+export declare function encodeFrozenArtifactBoundedStream(bundle: FrozenArtifactBundle, options: FrozenArtifactStreamPlanOptions): FrozenArtifactBoundedStream;
+export declare function buildFrozenArtifactStreamHeaderWire(plan: FrozenArtifactStreamPlan): FrozenArtifactStreamHeaderWire;
+/**
+ * 由已校验计划产出 NDJSON 帧（每条含换行，可直接拼接为响应体）。
+ * payload_sha256 在产出过程中增量累计，不等同于先拼接再哈希。
+ */
+export declare function encodeFrozenArtifactNdjsonFramesFromPlan(plan: FrozenArtifactStreamPlan): AsyncGenerator<string, void, void>;
+export declare function encodeFrozenArtifactNdjsonFrames(bundle: FrozenArtifactBundle, options: FrozenArtifactStreamPlanOptions): AsyncIterable<string>;
+/** 已校验计划 → 完整 NDJSON 响应体字节（single-file HTML 内嵌用）。 */
+export declare function encodeFrozenArtifactNdjsonBytesFromPlan(plan: FrozenArtifactStreamPlan): Promise<Uint8Array>;
+export declare function encodeFrozenArtifactNdjsonBytes(bundle: FrozenArtifactBundle, options: FrozenArtifactStreamPlanOptions): Promise<Uint8Array>;