@litfamily/litmuse 0.0.0-stage → 0.1.0

package/plugin/skills/visual-qa/scripts/png-chunks.mjs

@@ -0,0 +1,107 @@
+import { VisualQaError } from "./errors.mjs";
+
+export const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+export const PNG_MAX_BYTES = 25 * 1024 * 1024;
+
+function crcTable() {
+  const table = new Uint32Array(256);
+  for (let index = 0; index < 256; index += 1) {
+    let value = index;
+    for (let bit = 0; bit < 8; bit += 1) {
+      value = (value & 1) === 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
+    }
+    table[index] = value >>> 0;
+  }
+  return table;
+}
+
+const CRC_TABLE = crcTable();
+
+export function crc32(bytes) {
+  let crc = 0xffffffff;
+  for (const byte of bytes) {
+    crc = (CRC_TABLE[(crc ^ byte) & 0xff] ?? 0) ^ (crc >>> 8);
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+export function readPngChunks(buffer) {
+  if (buffer.length > PNG_MAX_BYTES) {
+    throw new VisualQaError("PNG_FILE_TOO_LARGE", "PNG_FILE_TOO_LARGE: maximum 25 MiB");
+  }
+  if (buffer.length < 8 || !buffer.subarray(0, 8).equals(PNG_SIGNATURE)) {
+    throw new VisualQaError("PNG_SIGNATURE_INVALID", "PNG signature is invalid");
+  }
+  const chunks = [];
+  const criticalCounts = new Map();
+  let idatClosed = false;
+  let seenIdat = false;
+  let offset = 8;
+  while (offset < buffer.length) {
+    if (offset + 12 > buffer.length) {
+      throw new VisualQaError("PNG_TRUNCATED", "PNG_TRUNCATED: incomplete chunk header or CRC");
+    }
+    const length = buffer.readUInt32BE(offset);
+    const typeBytes = buffer.subarray(offset + 4, offset + 8);
+    const type = typeBytes.toString("ascii");
+    if (!/^[A-Za-z]{4}$/u.test(type)) {
+      throw new VisualQaError("PNG_CHUNK_TYPE_INVALID", "PNG chunk type must be four ASCII letters");
+    }
+    const dataStart = offset + 8;
+    const dataEnd = dataStart + length;
+    const nextOffset = dataEnd + 4;
+    if (dataEnd < dataStart || nextOffset > buffer.length) {
+      throw new VisualQaError("PNG_TRUNCATED", `PNG_TRUNCATED: incomplete ${type} chunk`);
+    }
+    const data = buffer.subarray(dataStart, dataEnd);
+    const expectedCrc = buffer.readUInt32BE(dataEnd);
+    const actualCrc = crc32(Buffer.concat([typeBytes, data]));
+    if (actualCrc !== expectedCrc) {
+      throw new VisualQaError("PNG_CRC_MISMATCH", `PNG_CRC_MISMATCH: ${type}`);
+    }
+    const critical = (typeBytes[0] & 0x20) === 0;
+    if (critical && !["IHDR", "PLTE", "IDAT", "IEND"].includes(type)) {
+      throw new VisualQaError("PNG_UNKNOWN_CRITICAL_CHUNK", `unknown critical chunk: ${type}`);
+    }
+    if (critical && type !== "IDAT") {
+      const count = (criticalCounts.get(type) ?? 0) + 1;
+      criticalCounts.set(type, count);
+      if (count > 1) {
+        throw new VisualQaError("PNG_DUPLICATE_CRITICAL_CHUNK", `duplicate critical chunk: ${type}`);
+      }
+    }
+    if (chunks.length === 0 && type !== "IHDR") {
+      throw new VisualQaError("PNG_CHUNK_ORDER_INVALID", "IHDR must be first");
+    }
+    if (type === "IHDR" && chunks.length !== 0) {
+      throw new VisualQaError("PNG_DUPLICATE_CRITICAL_CHUNK", "duplicate or misplaced IHDR");
+    }
+    if (type === "PLTE" && seenIdat) {
+      throw new VisualQaError("PNG_CHUNK_ORDER_INVALID", "PLTE must precede IDAT");
+    }
+    if (type === "IDAT") {
+      if (idatClosed) throw new VisualQaError("PNG_CHUNK_ORDER_INVALID", "IDAT chunks must be contiguous");
+      seenIdat = true;
+    } else if (seenIdat && type !== "IEND") {
+      idatClosed = true;
+    }
+    if (type === "IEND" && (!seenIdat || data.length !== 0)) {
+      throw new VisualQaError("PNG_CHUNK_ORDER_INVALID", "IEND requires preceding IDAT and zero length");
+    }
+    chunks.push(Object.freeze({ type, data }));
+    offset = nextOffset;
+    if (type === "IEND") {
+      if (offset !== buffer.length) {
+        throw new VisualQaError("PNG_TRAILING_DATA", "unexpected bytes after IEND");
+      }
+      break;
+    }
+  }
+  if (chunks[0]?.type !== "IHDR" || chunks.at(-1)?.type !== "IEND") {
+    throw new VisualQaError("PNG_TRUNCATED", "PNG_TRUNCATED: IHDR/IEND boundary is incomplete");
+  }
+  if (chunks[0].data.length !== 13) {
+    throw new VisualQaError("PNG_HEADER_INVALID", "IHDR must contain 13 bytes");
+  }
+  return chunks;
+}

package/plugin/skills/visual-qa/scripts/png-crc.ts

@@ -0,0 +1,27 @@
+import { Buffer } from "node:buffer"
+
+export const PNG_SIGNATURE: Buffer = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+
+function buildCrcTable(): Uint32Array {
+	const table = new Uint32Array(256)
+	for (let n = 0; n < 256; n++) {
+		let c = n
+		for (let k = 0; k < 8; k++) {
+			c = (c & 1) === 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
+		}
+		table[n] = c >>> 0
+	}
+	return table
+}
+
+const CRC_TABLE = buildCrcTable()
+
+export function crc32(data: Buffer): number {
+	let crc = 0xffffffff
+	for (let i = 0; i < data.length; i++) {
+		const byte = data[i] ?? 0
+		const entry = CRC_TABLE[(crc ^ byte) & 0xff] ?? 0
+		crc = entry ^ (crc >>> 8)
+	}
+	return (crc ^ 0xffffffff) >>> 0
+}

package/plugin/skills/visual-qa/scripts/png-decode.mjs

@@ -0,0 +1,143 @@
+import { inflateSync } from "node:zlib";
+
+import { VisualQaError } from "./errors.mjs";
+import { readPngChunks } from "./png-chunks.mjs";
+
+const MAX_AXIS = 16_384;
+const MAX_PIXELS = 64 * 1024 * 1024;
+const MAX_DECODED_BYTES = 256 * 1024 * 1024;
+
+function channelsFor(colorType) {
+  const channels = new Map([[0, 1], [2, 3], [4, 2], [6, 4]]).get(colorType);
+  if (!channels) throw new VisualQaError("PNG_UNSUPPORTED", `unsupported PNG color type ${colorType}`);
+  return channels;
+}
+
+function parseHeader(data) {
+  if (data.length !== 13) throw new VisualQaError("PNG_HEADER_INVALID", "IHDR must contain 13 bytes");
+  const width = data.readUInt32BE(0);
+  const height = data.readUInt32BE(4);
+  const bitDepth = data[8];
+  const colorType = data[9];
+  if (width < 1 || height < 1 || width > MAX_AXIS || height > MAX_AXIS) {
+    throw new VisualQaError("PNG_RESOURCE_LIMIT", "PNG_RESOURCE_LIMIT: dimensions exceed 16,384");
+  }
+  const pixels = width * height;
+  if (pixels > MAX_PIXELS || pixels * 4 > MAX_DECODED_BYTES) {
+    throw new VisualQaError("PNG_RESOURCE_LIMIT", "PNG_RESOURCE_LIMIT: decoded storage exceeds 64 MP / 256 MiB");
+  }
+  if (bitDepth !== 8 || data[10] !== 0 || data[11] !== 0 || data[12] !== 0) {
+    throw new VisualQaError("PNG_UNSUPPORTED", "only non-interlaced 8-bit deflate PNG is supported");
+  }
+  return { width, height, colorType, channels: channelsFor(colorType) };
+}
+
+function assertPeakBudget(inputBytes, idatBytes, header) {
+  const rowBytes = header.width * header.channels;
+  const inflatedBytes = header.height * (rowBytes + 1);
+  const pixelBytes = header.width * header.height * header.channels;
+  const rgbaBytes = header.width * header.height * 4;
+  const peakBytes = inputBytes + idatBytes + inflatedBytes
+    + (2 * rowBytes) + pixelBytes + rgbaBytes;
+  if (!Number.isSafeInteger(peakBytes) || peakBytes > MAX_DECODED_BYTES) {
+    throw new VisualQaError(
+      "PNG_RESOURCE_LIMIT",
+      "PNG_RESOURCE_LIMIT: peak decode allocation exceeds 256 MiB",
+    );
+  }
+  return { rowBytes, inflatedBytes, pixelBytes };
+}
+
+function paeth(left, above, upperLeft) {
+  const estimate = left + above - upperLeft;
+  const leftDistance = Math.abs(estimate - left);
+  const aboveDistance = Math.abs(estimate - above);
+  const upperDistance = Math.abs(estimate - upperLeft);
+  if (leftDistance <= aboveDistance && leftDistance <= upperDistance) return left;
+  return aboveDistance <= upperDistance ? above : upperLeft;
+}
+
+function unfilterRow(filter, input, previous, bytesPerPixel) {
+  const output = Buffer.allocUnsafe(input.length);
+  for (let index = 0; index < input.length; index += 1) {
+    const raw = input[index] ?? 0;
+    const left = index >= bytesPerPixel ? output[index - bytesPerPixel] ?? 0 : 0;
+    const above = previous?.[index] ?? 0;
+    const upperLeft = index >= bytesPerPixel ? previous?.[index - bytesPerPixel] ?? 0 : 0;
+    if (filter === 0) output[index] = raw;
+    else if (filter === 1) output[index] = (raw + left) & 0xff;
+    else if (filter === 2) output[index] = (raw + above) & 0xff;
+    else if (filter === 3) output[index] = (raw + Math.floor((left + above) / 2)) & 0xff;
+    else if (filter === 4) output[index] = (raw + paeth(left, above, upperLeft)) & 0xff;
+    else throw new VisualQaError("PNG_FILTER_INVALID", `unsupported PNG filter ${filter}`);
+  }
+  return output;
+}
+
+function decodeScanlines(idat, header, allocation) {
+  const { rowBytes, inflatedBytes: expectedBytes, pixelBytes } = allocation;
+  let inflated;
+  try {
+    inflated = inflateSync(idat, { maxOutputLength: expectedBytes + 1 });
+  } catch (error) {
+    throw new VisualQaError("PNG_DECOMPRESSION_INVALID", `bounded PNG inflate failed: ${error.message}`);
+  }
+  if (inflated.length !== expectedBytes) {
+    throw new VisualQaError("PNG_TRUNCATED", "PNG_TRUNCATED: decoded scanline length mismatch");
+  }
+  const pixels = Buffer.allocUnsafe(pixelBytes);
+  let previous;
+  for (let row = 0; row < header.height; row += 1) {
+    const start = row * (rowBytes + 1);
+    const decoded = unfilterRow(
+      inflated[start] ?? 0,
+      inflated.subarray(start + 1, start + 1 + rowBytes),
+      previous,
+      header.channels,
+    );
+    decoded.copy(pixels, row * rowBytes);
+    previous = decoded;
+  }
+  return pixels;
+}
+
+function rgbaPixels(pixels, header) {
+  const rgba = new Uint8Array(header.width * header.height * 4);
+  let transparent = false;
+  for (let pixel = 0; pixel < header.width * header.height; pixel += 1) {
+    const source = pixel * header.channels;
+    const target = pixel * 4;
+    const gray = pixels[source] ?? 0;
+    rgba[target] = header.channels < 3 ? gray : pixels[source] ?? 0;
+    rgba[target + 1] = header.channels < 3 ? gray : pixels[source + 1] ?? 0;
+    rgba[target + 2] = header.channels < 3 ? gray : pixels[source + 2] ?? 0;
+    const alpha = header.channels === 2
+      ? pixels[source + 1] ?? 255
+      : header.channels === 4 ? pixels[source + 3] ?? 255 : 255;
+    rgba[target + 3] = alpha;
+    if (alpha < 255) transparent = true;
+  }
+  return { rgba, transparent };
+}
+
+export function decodePng(buffer) {
+  const chunks = readPngChunks(buffer);
+  const header = parseHeader(chunks[0].data);
+  const idat = chunks.filter(({ type }) => type === "IDAT");
+  if (idat.length === 0) throw new VisualQaError("PNG_TRUNCATED", "PNG_TRUNCATED: missing IDAT");
+  const idatBytes = idat.reduce((total, { data }) => total + data.length, 0);
+  const allocation = assertPeakBudget(buffer.length, idatBytes, header);
+  const pixels = decodeScanlines(
+    Buffer.concat(idat.map(({ data }) => data), idatBytes),
+    header,
+    allocation,
+  );
+  const normalized = rgbaPixels(pixels, header);
+  return {
+    width: header.width,
+    height: header.height,
+    rgba: normalized.rgba,
+    hasAlphaChannel: header.colorType === 4 || header.colorType === 6,
+    hasTransparentPixels: normalized.transparent,
+  };
+}

package/plugin/skills/visual-qa/scripts/png-decode.ts

@@ -0,0 +1,206 @@
+import { Buffer } from "node:buffer"
+import { inflateSync } from "node:zlib"
+
+import { PNG_SIGNATURE } from "./png-crc.ts"
+import type { DecodedImage } from "./types.ts"
+
+export class PngDecodeError extends Error {
+	readonly name = "PngDecodeError"
+}
+
+interface PngHeader {
+	readonly width: number
+	readonly height: number
+	readonly bitDepth: number
+	readonly colorType: number
+	readonly channels: number
+}
+
+interface PngChunk {
+	readonly type: string
+	readonly data: Buffer
+}
+
+function readChunks(buffer: Buffer): readonly PngChunk[] {
+	const chunks: PngChunk[] = []
+	let offset = 8
+	while (offset + 8 <= buffer.length) {
+		const length = buffer.readUInt32BE(offset)
+		const type = buffer.toString("ascii", offset + 4, offset + 8)
+		const dataStart = offset + 8
+		const dataEnd = dataStart + length
+		if (dataEnd + 4 > buffer.length) break
+		chunks.push({ type, data: buffer.subarray(dataStart, dataEnd) })
+		offset = dataEnd + 4
+	}
+	return chunks
+}
+
+function channelsForColorType(colorType: number): number {
+	switch (colorType) {
+		case 0:
+			return 1
+		case 2:
+			return 3
+		case 4:
+			return 2
+		case 6:
+			return 4
+		default:
+			throw new PngDecodeError(`unsupported color type ${colorType}`)
+	}
+}
+
+function parseHeader(data: Buffer): PngHeader {
+	if (data.length < 13) {
+		throw new PngDecodeError("invalid IHDR chunk length")
+	}
+	const colorType = data[9] ?? 0
+	return {
+		width: data.readUInt32BE(0),
+		height: data.readUInt32BE(4),
+		bitDepth: data[8] ?? 0,
+		colorType,
+		channels: channelsForColorType(colorType),
+	}
+}
+
+function paeth(a: number, b: number, c: number): number {
+	const p = a + b - c
+	const pa = Math.abs(p - a)
+	const pb = Math.abs(p - b)
+	const pc = Math.abs(p - c)
+	if (pa <= pb && pa <= pc) return a
+	if (pb <= pc) return b
+	return c
+}
+
+function unfilterRow(filterType: number, row: Buffer, prev: Buffer | null, bpp: number): Buffer {
+	const out = Buffer.alloc(row.length)
+	for (let i = 0; i < row.length; i++) {
+		const raw = row[i] ?? 0
+		const a = i >= bpp ? (out[i - bpp] ?? 0) : 0
+		const b = prev ? (prev[i] ?? 0) : 0
+		const c = i >= bpp && prev ? (prev[i - bpp] ?? 0) : 0
+		switch (filterType) {
+			case 0:
+				out[i] = raw
+				break
+			case 1:
+				out[i] = (raw + a) & 0xff
+				break
+			case 2:
+				out[i] = (raw + b) & 0xff
+				break
+			case 3:
+				out[i] = (raw + ((a + b) >> 1)) & 0xff
+				break
+			case 4:
+				out[i] = (raw + paeth(a, b, c)) & 0xff
+				break
+			default:
+				throw new PngDecodeError(`unsupported filter type ${filterType}`)
+		}
+	}
+	return out
+}
+
+function decodePixels(idat: Buffer, width: number, height: number, bpp: number): Buffer {
+	const inflated = inflateSync(idat)
+	const rowBytes = width * bpp
+	if (inflated.length < height * (rowBytes + 1)) {
+		throw new PngDecodeError("truncated image data")
+	}
+	const pixels = Buffer.alloc(width * height * bpp)
+	let prev: Buffer | null = null
+	for (let y = 0; y < height; y++) {
+		const rowStart = y * (rowBytes + 1)
+		const filterType = inflated[rowStart] ?? 0
+		const filtered = inflated.subarray(rowStart + 1, rowStart + 1 + rowBytes)
+		const row = unfilterRow(filterType, filtered, prev, bpp)
+		row.copy(pixels, y * rowBytes)
+		prev = row
+	}
+	return pixels
+}
+
+function normalizeToRgba(
+	pixels: Buffer,
+	pixelCount: number,
+	channels: number,
+): { readonly rgba: Uint8Array; readonly hasTransparent: boolean } {
+	const rgba = new Uint8Array(pixelCount * 4)
+	let hasTransparent = false
+	for (let i = 0; i < pixelCount; i++) {
+		const src = i * channels
+		let r = 0
+		let g = 0
+		let b = 0
+		let a = 255
+		switch (channels) {
+			case 1: {
+				const v = pixels[src] ?? 0
+				r = v
+				g = v
+				b = v
+				break
+			}
+			case 2: {
+				const v = pixels[src] ?? 0
+				r = v
+				g = v
+				b = v
+				a = pixels[src + 1] ?? 255
+				break
+			}
+			case 3: {
+				r = pixels[src] ?? 0
+				g = pixels[src + 1] ?? 0
+				b = pixels[src + 2] ?? 0
+				break
+			}
+			default: {
+				r = pixels[src] ?? 0
+				g = pixels[src + 1] ?? 0
+				b = pixels[src + 2] ?? 0
+				a = pixels[src + 3] ?? 255
+			}
+		}
+		const dst = i * 4
+		rgba[dst] = r
+		rgba[dst + 1] = g
+		rgba[dst + 2] = b
+		rgba[dst + 3] = a
+		if (a < 255) hasTransparent = true
+	}
+	return { rgba, hasTransparent }
+}
+
+export function decodePng(buffer: Buffer): DecodedImage {
+	if (buffer.length < 8 || !buffer.subarray(0, 8).equals(PNG_SIGNATURE)) {
+		throw new PngDecodeError("not a PNG file (bad signature)")
+	}
+	const chunks = readChunks(buffer)
+	const ihdr = chunks.find((chunk) => chunk.type === "IHDR")
+	if (ihdr === undefined) {
+		throw new PngDecodeError("missing IHDR chunk")
+	}
+	const header = parseHeader(ihdr.data)
+	if (header.bitDepth !== 8) {
+		throw new PngDecodeError(`unsupported bit depth ${header.bitDepth}`)
+	}
+	const idatChunks = chunks.filter((chunk) => chunk.type === "IDAT")
+	if (idatChunks.length === 0) {
+		throw new PngDecodeError("missing IDAT chunk")
+	}
+	const idat = Buffer.concat(idatChunks.map((chunk) => chunk.data))
+	const pixels = decodePixels(idat, header.width, header.height, header.channels)
+	const normalized = normalizeToRgba(pixels, header.width * header.height, header.channels)
+	return {
+		width: header.width,
+		height: header.height,
+		rgba: normalized.rgba,
+		hasAlphaChannel: header.colorType === 4 || header.colorType === 6,
+		hasTransparentPixels: normalized.hasTransparent,
+	}
+}

package/plugin/skills/visual-qa/scripts/png-synth.ts

@@ -0,0 +1,57 @@
+import { Buffer } from "node:buffer"
+import { deflateSync } from "node:zlib"
+
+import { crc32, PNG_SIGNATURE } from "./png-crc.ts"
+
+const BIT_DEPTH_8 = 8
+const COLOR_TYPE_RGBA = 6
+const FILTER_NONE = 0
+const RGBA_CHANNELS = 4
+
+function pngChunk(type: string, data: Buffer): Buffer {
+	const typeBuffer = Buffer.from(type, "ascii")
+	const length = Buffer.alloc(4)
+	length.writeUInt32BE(data.length, 0)
+	const crcBuffer = Buffer.alloc(4)
+	crcBuffer.writeUInt32BE(crc32(Buffer.concat([typeBuffer, data])), 0)
+	return Buffer.concat([length, typeBuffer, data, crcBuffer])
+}
+
+export function encodeRgbaPng(width: number, height: number, rgba: Uint8Array): Buffer {
+	const rowBytes = width * RGBA_CHANNELS
+	const raw = Buffer.alloc(height * (rowBytes + 1))
+	for (let y = 0; y < height; y++) {
+		const rowStart = y * (rowBytes + 1)
+		raw[rowStart] = FILTER_NONE
+		for (let x = 0; x < rowBytes; x++) {
+			raw[rowStart + 1 + x] = rgba[y * rowBytes + x] ?? 0
+		}
+	}
+	const header = Buffer.alloc(13)
+	header.writeUInt32BE(width, 0)
+	header.writeUInt32BE(height, 4)
+	header[8] = BIT_DEPTH_8
+	header[9] = COLOR_TYPE_RGBA
+	return Buffer.concat([
+		PNG_SIGNATURE,
+		pngChunk("IHDR", header),
+		pngChunk("IDAT", deflateSync(raw)),
+		pngChunk("IEND", Buffer.alloc(0)),
+	])
+}
+
+export function solidRgba(
+	width: number,
+	height: number,
+	color: readonly [number, number, number, number],
+): Uint8Array {
+	const rgba = new Uint8Array(width * height * RGBA_CHANNELS)
+	for (let pixel = 0; pixel < width * height; pixel++) {
+		const offset = pixel * RGBA_CHANNELS
+		rgba[offset] = color[0]
+		rgba[offset + 1] = color[1]
+		rgba[offset + 2] = color[2]
+		rgba[offset + 3] = color[3]
+	}
+	return rgba
+}

package/plugin/skills/visual-qa/scripts/review-rules.mjs

@@ -0,0 +1,137 @@
+import { stableJson } from "../../../lib/strict-json.mjs";
+import { sha256 } from "./evidence-io.mjs";
+
+export const REVIEW_SCHEMA = "litfamily.review-receipt/v1alpha1";
+export const REVIEWERS = ["quality-reviewer", "lit-verifier"];
+// A receipt may name the agent bare or as the namespaced subagent type (`litmuse/quality-reviewer`).
+const reviewerIdentity = (id) => (typeof id === "string" && id.startsWith("litmuse/") ? id.slice("litmuse/".length) : id);
+const HASH = /^[a-f0-9]{64}$/u;
+const ID = /^[a-z][a-z0-9-]*:[a-z0-9][a-z0-9./-]*$/u;
+const INPUT_KEYS = [
+  "design_contract_hash", "source_hash", "capture_hash", "artifacts_hash",
+];
+const RECEIPT_KEYS = [
+  "schema_id", "review_id", "fresh_context_id", "reviewer_capability", "input_hashes",
+  "reviewed_inventory", "confidence", "findings", "independence_assertion",
+  "peer_draft_received", "implementer_context",
+  "started_at", "ended_at", "timeout", "cancelled", "verdict",
+];
+const FINDING_KEYS = ["id", "severity", "blocking", "message", "evidence_ids"];
+const ISO_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/u;
+
+function object(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+export function reviewShapeValid(receipt) {
+  if (!object(receipt) || RECEIPT_KEYS.some((field) => !Object.hasOwn(receipt, field))
+    || Object.keys(receipt).some((field) => !RECEIPT_KEYS.includes(field))
+    || receipt.schema_id !== REVIEW_SCHEMA
+    || !ID.test(receipt.review_id) || !ID.test(receipt.fresh_context_id)
+    || !REVIEWERS.includes(reviewerIdentity(receipt.reviewer_capability))
+    || !object(receipt.input_hashes)
+    || Object.keys(receipt.input_hashes).length !== INPUT_KEYS.length
+    || Object.keys(receipt.input_hashes).some((key) => !INPUT_KEYS.includes(key))
+    || INPUT_KEYS.some((key) => !Object.hasOwn(receipt.input_hashes, key))
+    || INPUT_KEYS.some((key) => !HASH.test(receipt.input_hashes[key]))
+    || !Array.isArray(receipt.reviewed_inventory)
+    || receipt.reviewed_inventory.length < 1 || receipt.reviewed_inventory.length > 512
+    || receipt.reviewed_inventory.length !== new Set(receipt.reviewed_inventory).size
+    || receipt.reviewed_inventory.some((id) => !ID.test(id))
+    || !["HIGH", "MEDIUM", "LOW"].includes(receipt.confidence)
+    || !Array.isArray(receipt.findings)
+    || receipt.findings.length > 256
+    || typeof receipt.independence_assertion !== "boolean"
+    || typeof receipt.peer_draft_received !== "boolean"
+    || typeof receipt.implementer_context !== "boolean"
+    || typeof receipt.timeout !== "boolean"
+    || typeof receipt.cancelled !== "boolean"
+    || !["PASS", "FAIL", "BLOCKED"].includes(receipt.verdict)) return false;
+  if (!ISO_TIME.test(receipt.started_at) || !ISO_TIME.test(receipt.ended_at)) return false;
+  const start = Date.parse(receipt.started_at);
+  const end = Date.parse(receipt.ended_at);
+  return Number.isFinite(start) && Number.isFinite(end) && end >= start
+    && receipt.findings.every((finding) => object(finding)
+      && FINDING_KEYS.every((key) => Object.hasOwn(finding, key))
+      && ID.test(finding.id)
+      && ["P0", "P1", "P2", "P3"].includes(finding.severity)
+      && typeof finding.blocking === "boolean"
+      && typeof finding.message === "string"
+      && finding.message.length > 0
+      && Array.isArray(finding.evidence_ids)
+      && finding.evidence_ids.length > 0
+      && finding.evidence_ids.length <= 128
+      && finding.evidence_ids.length === new Set(finding.evidence_ids).size
+      && finding.evidence_ids.every((id) => ID.test(id))
+      && Object.keys(finding).every((key) => FINDING_KEYS.includes(key)));
+}
+
+export function validateReviewSet(
+  receipts, hashes, expectedInputs, expectedInventory, artifactIds, now, maximumAgeSeconds,
+  required = true,
+) {
+  const blocked = [];
+  const failures = [];
+  if (!required) {
+    if (Array.isArray(receipts) && receipts.length === 0
+      && Array.isArray(hashes) && hashes.length === 0) {
+      return { blocked, failures };
+    }
+    return { blocked, failures: ["REVIEW_RECEIPT_COUNT_INVALID"] };
+  }
+  if (!Array.isArray(receipts) || receipts.length !== 2
+    || !Array.isArray(hashes) || hashes.length !== 2) {
+    failures.push("REVIEW_RECEIPT_COUNT_INVALID");
+    return { blocked, failures };
+  }
+  if (receipts.some((receipt) => !reviewShapeValid(receipt))) {
+    failures.push("REVIEW_RECEIPT_SCHEMA_INVALID");
+    return { blocked, failures };
+  }
+  if (new Set(receipts.map(({ reviewer_capability: id }) => reviewerIdentity(id))).size !== 2
+    || new Set(receipts.map(({ review_id: id }) => id)).size !== 2
+    || new Set(receipts.map(({ fresh_context_id: id }) => id)).size !== 2
+    || receipts.some((receipt) =>
+      receipt.review_id !== `review:${receipt.reviewer_capability}`
+      || receipt.independence_assertion !== true
+      || receipt.peer_draft_received !== false
+      || receipt.implementer_context !== false)) {
+    failures.push("REVIEW_RECEIPT_INDEPENDENCE_INVALID");
+  }
+  if (receipts.some((receipt) =>
+    INPUT_KEYS.some((key) => receipt.input_hashes[key] !== expectedInputs[key]))) {
+    failures.push("REVIEW_RECEIPT_INPUT_MISMATCH");
+  }
+  if (receipts.some((receipt) =>
+    receipt.reviewed_inventory.length !== expectedInventory.length
+    || receipt.reviewed_inventory.some((id, index) => id !== expectedInventory[index]))) {
+    failures.push("REVIEW_RECEIPT_INVENTORY_MISMATCH");
+  }
+  if (receipts.some(({ findings }) => findings.some((finding) =>
+    (["P0", "P1"].includes(finding.severity) && finding.blocking !== true)
+    || finding.evidence_ids.some((id) => !artifactIds.has(id))))) {
+    failures.push("REVIEW_FINDING_INVALID");
+  }
+  if (receipts.some((receipt, index) => sha256(stableJson(receipt)) !== hashes[index])) {
+    failures.push("REVIEW_RECEIPT_HASH_INVALID");
+  }
+  if (receipts.some(({ timeout }) => timeout)) blocked.push("BLOCKED_REVIEW_TIMEOUT");
+  if (receipts.some(({ cancelled }) => cancelled)) blocked.push("BLOCKED_REVIEW_CANCELLED");
+  if (receipts.some(({ verdict }) => verdict !== "PASS")) failures.push("REVIEW_RECEIPT_NOT_PASS");
+  if (receipts.some(({ findings }) => findings.some(({ blocking, severity }) =>
+    blocking || ["P0", "P1"].includes(severity)))) {
+    failures.push("REVIEW_BLOCKING_FINDING");
+  }
+  if (receipts.some((receipt) => receipt.verdict === "PASS"
+    && (receipt.timeout || receipt.cancelled || receipt.findings.some(({ blocking, severity }) =>
+      blocking || ["P0", "P1"].includes(severity))))) {
+    failures.push("REVIEW_RECEIPT_VERDICT_INCOHERENT");
+  }
+  if (receipts.some(({ ended_at }) => Date.parse(ended_at) > now)) {
+    failures.push("REVIEW_RECEIPT_TIMESTAMP_INVALID");
+  }
+  if (receipts.some(({ ended_at }) => now - Date.parse(ended_at) > maximumAgeSeconds * 1000)) {
+    blocked.push("BLOCKED_EVIDENCE_STALE");
+  }
+  return { blocked: [...new Set(blocked)], failures: [...new Set(failures)] };
+}