@springbrand/eval-harness 0.1.0-alpha.1 → 0.1.0-alpha.2

package/README.md

@@ -6,6 +6,11 @@ creation and routing, Severn owns Submission and canonical Session history,
 Workspace owns files, and API owns billing settlements. Eval Project, Dataset,
 Sampling and scoring remain in `eval-platform`.
 
+The root export also exposes `hasZipSignature`, `inspectStrictZip`,
+`StrictZipError`, `STRICT_ZIP_OOXML_LIMITS` and their `StrictZip*` types from
+the shared ZIP inspector. Consumers supply explicit archive limits; inspection
+does not retain expanded bytes unless `retainBytes` is enabled.
+
 The Eval Run Worker authenticates with a dedicated service token. Its requests
 include the owning user ID because an SP Inbox is addressed by user. The Chat
 creation facts and each Submission operation key are immutable. Initialization

package/dist/{index.d.ts → eval-harness/src/index.d.ts}

@@ -1,4 +1,5 @@
 import { z } from "zod";
+export { hasZipSignature, inspectStrictZip, StrictZipError, STRICT_ZIP_OOXML_LIMITS, type StrictZipEntry, type StrictZipEntryLimit, type StrictZipErrorCode, type StrictZipInspectOptions, type StrictZipLimits, type StrictZipResult, } from "../../utils/src/index.js";
 export declare const EVAL_SERVICE_HEADER = "X-Eval-Service-Token";
 export declare const EVAL_HARNESS_PATH = "/internal/v1/eval-harness";
 export declare const evalEnsureChatSchema: z.ZodObject<{
@@ -231,4 +232,3 @@ export type EvalEvidenceFileReceipt = {
 export declare function isEvalSha256(value: string | null): value is string;
 /** Compare creation and operation facts without depending on JSON property order. */
 export declare function stableEvalFacts(value: unknown): string;
-export {};

package/dist/eval-harness/src/index.js

@@ -0,0 +1,266 @@
+import { z } from "zod";
+import { canonicalJsonStringify, sha256Hex } from "../../utils/src/index.js";
+export { hasZipSignature, inspectStrictZip, StrictZipError, STRICT_ZIP_OOXML_LIMITS, } from "../../utils/src/index.js";
+export const EVAL_SERVICE_HEADER = "X-Eval-Service-Token";
+export const EVAL_HARNESS_PATH = "/internal/v1/eval-harness";
+const id = z.string().trim().min(1);
+const uuid = z.uuid();
+export const evalEnsureChatSchema = z.strictObject({
+    chatId: uuid,
+    role: z.enum(["subject", "evaluator"]),
+    framework: z.literal("sp"),
+    samplingId: id,
+    projectId: id,
+    agentConfig: z.strictObject({ ownerUserId: uuid, userAgentId: uuid }),
+    /** Only an Evaluator carries it; the Evaluator still owns an ordinary Chat and its own Space. */
+    evaluationId: id.optional(),
+    runtime: z.strictObject({ timeoutMs: z.number().finite().positive().optional() }).optional(),
+}).superRefine((value, context) => {
+    if ((value.role === "evaluator") !== (value.evaluationId !== undefined)) {
+        context.addIssue({ code: "custom", path: ["evaluationId"], message: "Evaluation ID must match role" });
+    }
+});
+export const EVAL_INITIAL_FILE_MAX_BYTES = 5_000_000;
+export const EVAL_INITIALIZATION_MAX_BYTES = 20_000_000;
+export const EVAL_MATERIAL_MAX_FILES = 500;
+export const EVAL_SESSION_CONTENT_MAX_CHARS = 2_000_000;
+export const EVAL_SESSION_MAX_ENTRIES = 10_000;
+export const EVAL_OUTPUT_SCHEMA_PATH = "/evaluation-output.schema.json";
+export const EVAL_INITIAL_MATERIALS_ROOT = "/initial-materials";
+/** Subject Session JSON and Evaluator Schema JSON can expand to six bytes per character. */
+export const EVAL_INITIALIZATION_BODY_MAX_BYTES = Math.max(Math.ceil(EVAL_INITIALIZATION_MAX_BYTES * 4 / 3) + EVAL_SESSION_CONTENT_MAX_CHARS * 6, Math.ceil((EVAL_INITIALIZATION_MAX_BYTES - EVAL_INITIAL_FILE_MAX_BYTES) * 4 / 3) + EVAL_INITIAL_FILE_MAX_BYTES * 6) + 1_000_000;
+const base64Bytes = (value) => value.length / 4 * 3 - (value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0);
+const utf8Bytes = (value) => new TextEncoder().encode(value).byteLength;
+/** Decoded bytes of validated Material files, counted exactly as the initialization budget counts them. */
+export const evalMaterialFilesByteSize = (files) => files.reduce((sum, file) => sum + base64Bytes(file.contentBase64), 0);
+const tooBig = (context, maximum, message, path = []) => context.addIssue({ code: "too_big", origin: "file", maximum, inclusive: true, path, message });
+const maxFileBytes = (bytes) => (value, context) => {
+    if (bytes(value) > EVAL_INITIAL_FILE_MAX_BYTES)
+        tooBig(context, EVAL_INITIAL_FILE_MAX_BYTES, "File is too large");
+};
+const evalMaterialFileSchema = z.strictObject({
+    path: z.string().refine((path) => evalPathParts(path) !== null, "Invalid initial material path"),
+    mediaType: id,
+    contentBase64: z.base64().superRefine(maxFileBytes(base64Bytes)),
+});
+export const evalMaterialFilesSchema = z.array(evalMaterialFileSchema).max(EVAL_MATERIAL_MAX_FILES).superRefine((files, context) => {
+    const seen = new Set();
+    files.forEach(({ path }, index) => {
+        if (seen.has(path))
+            context.addIssue({ code: "custom", path: [index, "path"], message: "Duplicate material path" });
+        seen.add(path);
+    });
+});
+const evalInitialMaterialSchema = z.strictObject({
+    bundleId: id,
+    materialId: id,
+    files: evalMaterialFilesSchema,
+});
+export const evalInitialContextSchema = z.strictObject({
+    format: z.enum(["json", "jsonl"]),
+    content: z.string().min(1),
+});
+export const evalInitializationSchema = z.strictObject({
+    idempotencyKey: id,
+    data: z.record(z.string(), z.unknown()).and(z.object({ userPrompt: z.string().trim().min(1) })),
+    initialSession: z.strictObject({
+        bundleId: id,
+        sessionId: id,
+        context: evalInitialContextSchema.optional(),
+    }).optional(),
+    initialMaterials: z.array(evalInitialMaterialSchema).min(1).optional(),
+    evaluationOutputSchema: z.strictObject({
+        content: z.string().min(1).superRefine(maxFileBytes(utf8Bytes)),
+    }).optional(),
+}).superRefine((value, context) => {
+    const session = value.data.initialSession;
+    const refs = value.data.initialMaterials;
+    const materials = value.initialMaterials;
+    if (session ? !value.initialSession || session.bundleId !== value.initialSession.bundleId ||
+        session.sessionId !== value.initialSession.sessionId : value.initialSession !== undefined) {
+        context.addIssue({ code: "custom", path: ["initialSession"], message: "Session content must match the Data reference" });
+    }
+    if (refs === undefined ? materials !== undefined : !Array.isArray(refs) || refs.length !== materials?.length ||
+        materials.some((material, index) => {
+            const ref = refs[index];
+            return ref?.bundleId !== material.bundleId || ref?.materialId !== material.materialId;
+        })) {
+        context.addIssue({ code: "custom", path: ["initialMaterials"], message: "Material content must match the Data reference" });
+    }
+    const seen = new Set();
+    materials?.forEach(({ bundleId, materialId }, index) => {
+        const key = JSON.stringify([bundleId, materialId]);
+        if (seen.has(key))
+            context.addIssue({ code: "custom", path: ["initialMaterials", index], message: "Duplicate material" });
+        seen.add(key);
+    });
+    const total = (materials ?? []).reduce((sum, material) => sum + evalMaterialFilesByteSize(material.files), value.evaluationOutputSchema ? utf8Bytes(value.evaluationOutputSchema.content) : 0);
+    if (total > EVAL_INITIALIZATION_MAX_BYTES) {
+        tooBig(context, EVAL_INITIALIZATION_MAX_BYTES, "Initialization files are too large");
+    }
+});
+export const evalInitializationResultSchema = z.strictObject({
+    manifestHash: id,
+    target: z.literal("workspace"),
+    materials: z.array(z.strictObject({ bundleId: id, materialId: id, rootPath: z.string().startsWith("/") })),
+    evaluationOutputSchemaPath: z.literal(EVAL_OUTPUT_SCHEMA_PATH).exactOptional(),
+});
+export const evalSubmitSchema = z.strictObject({
+    idempotencyKey: id,
+    prompt: z.string().trim().min(1),
+    unattended: z.literal(true),
+    runtime: z.strictObject({ timeoutMs: z.number().finite().positive().optional() }).optional(),
+});
+export const evalBillingResourcesSchema = z.strictObject({
+    usageEvents: z.array(z.record(z.string(), z.unknown())),
+    billingSettlements: z.array(z.record(z.string(), z.unknown())),
+});
+export function projectEvalSubmission(input) {
+    const normalizedStatus = {
+        pending: "queued",
+        running: "running",
+        completed: "completed",
+        error: "failed",
+        skipped: "failed",
+        aborted: "interrupted",
+    }[input.status];
+    if (!normalizedStatus)
+        throw new Error("Unknown SP Submission status");
+    return { ...input, normalizedStatus: normalizedStatus };
+}
+/** JSON stores one canonical snapshot; JSONL stores one canonical entry per line. */
+export function readEvalCanonicalContext(input) {
+    if (input.content.length > EVAL_SESSION_CONTENT_MAX_CHARS)
+        throw new Error("Initial context is too large");
+    const parsed = input.format === "json"
+        ? JSON.parse(input.content)
+        : { entries: input.content.split(/\r?\n/u).filter((line) => line.trim()).map((line) => JSON.parse(line)) };
+    if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.entries)) {
+        throw new Error("Initial context must contain canonical entries");
+    }
+    const entries = parsed.entries;
+    if (entries.length > EVAL_SESSION_MAX_ENTRIES)
+        throw new Error("Initial context has too many entries");
+    const seen = new Set();
+    for (const entry of entries) {
+        if (!entry || typeof entry !== "object")
+            throw new Error("Invalid canonical context entry");
+        const row = entry;
+        if (typeof row.id !== "string" || !row.id || seen.has(row.id) ||
+            !Number.isSafeInteger(row.createdAt) || Number(row.createdAt) < 0 ||
+            !row.message || typeof row.message !== "object" || Array.isArray(row.message) ||
+            !["user", "assistant", "toolResult"].includes(row.message.role ?? "")) {
+            throw new Error("Invalid or duplicate canonical context entry");
+        }
+        seen.add(row.id);
+    }
+    if (entries.length > 0 && entries[0].message.role !== "user") {
+        throw new Error("Initial context must begin with a user message");
+    }
+    return { entries: entries };
+}
+/** The one file an Evaluator writes its scored result to, in its own Space. */
+export const EVAL_RESULT_FILE = "result.json";
+export const EVAL_RESULT_PATH = `/output/${EVAL_RESULT_FILE}`;
+export const EVAL_RESULT_MAX_BYTES = 1_000_000;
+/** Reads the result file as raw UTF-8 text; any byte order mark and formatting are kept. */
+export async function readEvalStructuredOutput(path, bytes) {
+    if (bytes.byteLength > EVAL_RESULT_MAX_BYTES)
+        throw new Error(`${EVAL_RESULT_FILE} exceeds ${EVAL_RESULT_MAX_BYTES} bytes`);
+    let content;
+    try {
+        content = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        throw new Error(`${EVAL_RESULT_FILE} is not valid UTF-8`);
+    }
+    const contentHash = `sha256:${await sha256Hex(bytes)}`;
+    return { path, content, contentHash };
+}
+export function evalMaterialRoot(bundleId, materialId) {
+    return `${EVAL_INITIAL_MATERIALS_ROOT}/${evalPathSegment(bundleId)}/${evalPathSegment(materialId)}`;
+}
+function evalPathSegment(value) {
+    return encodeURIComponent(value).replaceAll(".", "%2E");
+}
+/** Absolute paths below a root; `.`/`..`, `.git`, backslashes and NUL never reach the Space. */
+function evalPathParts(path) {
+    const parts = path.split("/").slice(1);
+    if (!path.startsWith("/") || parts.length === 0 || parts.some((part) => !part || part === "." || part === ".." || part === ".git" || part.includes("\\") || part.includes("\0"))) {
+        return null;
+    }
+    return parts;
+}
+export function evalMaterialPath(root, path) {
+    const parts = evalPathParts(path);
+    if (!parts)
+        throw new Error("Invalid initial material path");
+    return `${root}/${parts.join("/")}`;
+}
+/*
+ * Evidence: a Subject's artifacts and complete trajectory are exported once, then imported into
+ * the Evaluator's own Space under `/evidence`. Neither Chat ever reads the other's Space.
+ */
+/** Where imported evidence lives in the Evaluator's own Space. */
+export const EVAL_EVIDENCE_ROOT = "/evidence";
+/** Bundle-relative paths, used by the import route; evalEvidencePath returns their Workspace paths. */
+export const EVAL_EVIDENCE_PATHS = {
+    subjectInputs: "/subject-inputs",
+    artifacts: "/artifacts",
+    trajectory: "/trajectory",
+    manifest: "/manifest.json",
+};
+/** One exported or imported file crosses a single Durable Object RPC as bytes. */
+export const EVAL_EVIDENCE_FILE_MAX_BYTES = 25_000_000;
+export const EVAL_EVIDENCE_TRAJECTORY_PAGE_MAX = 200;
+export const EVAL_EVIDENCE_SHA256_HEADER = "X-Eval-Content-Sha256";
+/** One Subject artifact; its bytes are read separately so the inventory stays small. */
+export const evalEvidenceArtifactSchema = z.strictObject({
+    path: z.string().startsWith("/").min(2),
+    size: z.number().int().nonnegative(),
+    mediaType: id,
+});
+export const evalEvidenceArtifactsSchema = z.strictObject({
+    artifacts: z.array(evalEvidenceArtifactSchema),
+});
+export function readEvalTrajectoryPageQuery(params) {
+    const afterSeq = Number(params.get("afterSeq") ?? "0");
+    const limit = Number(params.get("limit") ?? String(EVAL_EVIDENCE_TRAJECTORY_PAGE_MAX));
+    if (!Number.isSafeInteger(afterSeq) || afterSeq < 0 ||
+        !Number.isSafeInteger(limit) || limit < 1 || limit > EVAL_EVIDENCE_TRAJECTORY_PAGE_MAX) {
+        throw new Error("Invalid trajectory page");
+    }
+    return { afterSeq, limit };
+}
+/** A Space path for one evidence file; `relative` keeps the bundle's own layout below `/evidence`. */
+export function evalEvidencePath(relative) {
+    const parts = evalPathParts(relative);
+    if (!parts || (relative !== EVAL_EVIDENCE_PATHS.manifest &&
+        ![EVAL_EVIDENCE_PATHS.subjectInputs, EVAL_EVIDENCE_PATHS.artifacts, EVAL_EVIDENCE_PATHS.trajectory]
+            .some((root) => relative.startsWith(`${root}/`))))
+        throw new Error("Invalid evidence path");
+    return `${EVAL_EVIDENCE_ROOT}/${parts.join("/")}`;
+}
+/** Original Subject inputs stay separate from produced artifacts and the Evaluator's own materials. */
+export function evalSubjectInputEvidencePath(bundleId, materialId, path) {
+    return evalMaterialPath(`${EVAL_EVIDENCE_PATHS.subjectInputs}/${evalPathSegment(bundleId)}/${evalPathSegment(materialId)}`, path);
+}
+export function evalArtifactEvidencePath(path) {
+    return evalMaterialPath(EVAL_EVIDENCE_PATHS.artifacts, path);
+}
+/** Positive part numbers preserve the complete raw JSONL trajectory's order. */
+export function evalTrajectoryEvidencePath(part) {
+    if (!Number.isSafeInteger(part) || part < 1)
+        throw new Error("Invalid trajectory part");
+    return `${EVAL_EVIDENCE_PATHS.trajectory}/events-${String(part).padStart(6, "0")}.jsonl`;
+}
+export function isEvalSha256(value) {
+    return value !== null && /^[0-9a-f]{64}$/u.test(value);
+}
+/** Compare creation and operation facts without depending on JSON property order. */
+export function stableEvalFacts(value) {
+    const facts = canonicalJsonStringify(value);
+    if (facts === undefined)
+        throw new TypeError("Eval facts must be JSON");
+    return facts;
+}

package/dist/utils/src/attachment.d.ts

@@ -0,0 +1,12 @@
+export declare const ATTACHMENT_MAX_COUNT = 8;
+export declare const ATTACHMENT_MAX_BYTES: number;
+export declare const ATTACHMENT_MAX_TOTAL_BYTES: number;
+export declare const ATTACHMENT_ID_PATTERN: string;
+export type AttachmentCdnUrl = string;
+export declare function isAttachmentId(value: unknown): value is string;
+export declare function attachmentCdnUrl(publicOrigin: string, attachmentId: string): AttachmentCdnUrl;
+export declare function parseAttachmentCdnUrl(value: unknown): {
+    attachmentId: string;
+} | null;
+export declare function isAttachmentCdnUrl(value: unknown): value is AttachmentCdnUrl;
+export declare function isStrictUtf8(bytes: Uint8Array): boolean;

package/dist/utils/src/attachment.js

@@ -0,0 +1,50 @@
+export const ATTACHMENT_MAX_COUNT = 8;
+export const ATTACHMENT_MAX_BYTES = 20 * 1024 * 1024;
+export const ATTACHMENT_MAX_TOTAL_BYTES = 80 * 1024 * 1024;
+const ATTACHMENT_ID_BODY = String.raw `\d{2}-(?:0[1-9]|1[0-2])-[A-Za-z0-9_-]{16}`;
+export const ATTACHMENT_ID_PATTERN = `^${ATTACHMENT_ID_BODY}$`;
+const ATTACHMENT_PATH = new RegExp(`^/attachments/(${ATTACHMENT_ID_BODY})$`, "u");
+export function isAttachmentId(value) {
+    return typeof value === "string" && ATTACHMENT_PATH.test(`/attachments/${value}`);
+}
+export function attachmentCdnUrl(publicOrigin, attachmentId) {
+    if (!isAttachmentId(attachmentId)) {
+        throw new Error("Invalid Attachment");
+    }
+    const url = new URL(`/attachments/${attachmentId}`, publicOrigin);
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new Error("Invalid Attachment");
+    }
+    return url.href;
+}
+export function parseAttachmentCdnUrl(value) {
+    if (typeof value !== "string")
+        return null;
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        return null;
+    if (url.search || url.hash)
+        return null;
+    const match = url.pathname.match(ATTACHMENT_PATH);
+    return match
+        ? { attachmentId: match[1] }
+        : null;
+}
+export function isAttachmentCdnUrl(value) {
+    return parseAttachmentCdnUrl(value) !== null;
+}
+export function isStrictUtf8(bytes) {
+    try {
+        new TextDecoder("utf-8", { fatal: true, ignoreBOM: false }).decode(bytes);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/utils/src/base64.d.ts

@@ -0,0 +1,3 @@
+export declare function encodeBase64(bytes: Uint8Array, urlSafe?: boolean): string;
+export declare function decodeBase64(value: string, urlSafe?: boolean): Uint8Array<ArrayBuffer>;
+export declare function hexToBase64(hex: string): string;

package/dist/utils/src/base64.js

@@ -0,0 +1,27 @@
+const CHUNK_SIZE = 0x8000;
+export function encodeBase64(bytes, urlSafe = false) {
+    let binary = "";
+    for (let index = 0; index < bytes.length; index += CHUNK_SIZE) {
+        binary += String.fromCharCode(...bytes.subarray(index, index + CHUNK_SIZE));
+    }
+    const encoded = btoa(binary);
+    return urlSafe
+        ? encoded.replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "")
+        : encoded;
+}
+export function decodeBase64(value, urlSafe = false) {
+    const normalized = urlSafe
+        ? value.replaceAll("-", "+").replaceAll("_", "/")
+        : value;
+    const binary = atob(normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "="));
+    return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+export function hexToBase64(hex) {
+    if (!/^(?:[a-f\d]{2})+$/iu.test(hex))
+        throw new TypeError("Invalid hexadecimal bytes");
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let index = 0; index < bytes.length; index += 1) {
+        bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+    }
+    return encodeBase64(bytes);
+}

package/dist/utils/src/content-hash.d.ts

@@ -0,0 +1,5 @@
+export declare function sha256Hex(value: string | Uint8Array): Promise<string>;
+export declare function hashFileSet(files: readonly {
+    path: string;
+    bytes: Uint8Array;
+}[]): Promise<string>;

package/dist/utils/src/content-hash.js

@@ -0,0 +1,27 @@
+export async function sha256Hex(value) {
+    const bytes = typeof value === "string" ? new TextEncoder().encode(value) : value;
+    const buffer = new ArrayBuffer(bytes.byteLength);
+    new Uint8Array(buffer).set(bytes);
+    const digest = await crypto.subtle.digest("SHA-256", buffer);
+    return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+export function hashFileSet(files) {
+    const encoder = new TextEncoder();
+    const entries = [...files]
+        .sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0))
+        .map((file) => ({ path: encoder.encode(file.path), bytes: file.bytes }));
+    const framed = new Uint8Array(entries.reduce((total, entry) => total + 8 + entry.path.byteLength + entry.bytes.byteLength, 0));
+    const view = new DataView(framed.buffer);
+    let offset = 0;
+    for (const entry of entries) {
+        view.setUint32(offset, entry.path.byteLength);
+        offset += 4;
+        framed.set(entry.path, offset);
+        offset += entry.path.byteLength;
+        view.setUint32(offset, entry.bytes.byteLength);
+        offset += 4;
+        framed.set(entry.bytes, offset);
+        offset += entry.bytes.byteLength;
+    }
+    return sha256Hex(framed);
+}

package/dist/utils/src/database.d.ts

@@ -0,0 +1 @@
+export declare function isUniqueConstraintViolation(error: unknown): boolean;

package/dist/utils/src/database.js

@@ -0,0 +1,9 @@
+export function isUniqueConstraintViolation(error) {
+    for (let current = error; current instanceof Error; current = current.cause) {
+        if (/UNIQUE constraint failed/i.test(current.message))
+            return true;
+        if (/duplicate key value violates unique constraint/i.test(current.message))
+            return true;
+    }
+    return false;
+}

package/dist/utils/src/html.d.ts

@@ -0,0 +1,2 @@
+/** Escapes text for a place where markup would otherwise be read as markup. */
+export declare function escapeHtml(value: string): string;

package/dist/utils/src/html.js

@@ -0,0 +1,9 @@
+/** Escapes text for a place where markup would otherwise be read as markup. */
+export function escapeHtml(value) {
+    return value
+        .replace(/&/gu, "&")
+        .replace(/</gu, "&lt;")
+        .replace(/>/gu, "&gt;")
+        .replace(/"/gu, "&quot;")
+        .replace(/'/gu, "&#39;");
+}

package/dist/utils/src/image.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Whether a capture is blank, and what it was judged against.
+ *
+ * `bytes` and `threshold` are reported either way, because a caller that
+ * retries a blank capture has to be able to say what it actually saw.
+ */
+export type BlankScreenshotVerdict = {
+    readonly blank: boolean;
+    readonly bytes: number;
+    readonly threshold: number;
+};
+export type BlankScreenshotOptions = {
+    /** Captured area in pixels: the threshold has to scale with it. */
+    readonly pixels: number;
+    readonly bytesPerPixel?: number;
+};
+/**
+ * Decide whether an encoded screenshot is blank, from its size alone.
+ *
+ * A page that has not painted yet still screenshots successfully, so a capture
+ * cannot be trusted just because the browser returned one. What separates the
+ * two is how much an encoder can throw away: a uniform surface collapses to a
+ * couple of kilobytes while even a heading and a background colour do not.
+ *
+ * Deliberately does not look at the bytes' entropy. That is the obvious second
+ * signal and it does not work here: a blank webp's compressed tail measures
+ * ~4.97 bits per byte, higher than pages full of content, because the entropy
+ * of a compressed stream says nothing about the image it encodes.
+ *
+ * Deliberately does not decode the image either — the point is to run inside a
+ * Worker right after the capture, without paying to inflate the pixels.
+ */
+export declare function detectBlankScreenshot(bytes: Uint8Array, options: BlankScreenshotOptions): BlankScreenshotVerdict;

package/dist/utils/src/image.js

@@ -0,0 +1,35 @@
+/**
+ * Halfway between a blank capture and the thinnest real one, measured on
+ * Cloudflare Browser Rendering at 1280x720, webp quality 76:
+ *
+ * | page                        | bytes  | bytes/pixel |
+ * | --------------------------- | ------ | ----------- |
+ * | about:blank, empty body     |  2_182 |     0.00237 |
+ * | solid background + heading  |  3_524 |     0.00382 |
+ * | gradient hero               |  4_628 |     0.00502 |
+ * | page of body copy           | 47_224 |     0.05124 |
+ */
+const DEFAULT_BYTES_PER_PIXEL = 0.0031;
+/** A capture below this is truncated or empty at any viewport. */
+const ABSOLUTE_MIN_BYTES = 1_024;
+/**
+ * Decide whether an encoded screenshot is blank, from its size alone.
+ *
+ * A page that has not painted yet still screenshots successfully, so a capture
+ * cannot be trusted just because the browser returned one. What separates the
+ * two is how much an encoder can throw away: a uniform surface collapses to a
+ * couple of kilobytes while even a heading and a background colour do not.
+ *
+ * Deliberately does not look at the bytes' entropy. That is the obvious second
+ * signal and it does not work here: a blank webp's compressed tail measures
+ * ~4.97 bits per byte, higher than pages full of content, because the entropy
+ * of a compressed stream says nothing about the image it encodes.
+ *
+ * Deliberately does not decode the image either — the point is to run inside a
+ * Worker right after the capture, without paying to inflate the pixels.
+ */
+export function detectBlankScreenshot(bytes, options) {
+    const perPixel = options.bytesPerPixel ?? DEFAULT_BYTES_PER_PIXEL;
+    const threshold = Math.max(ABSOLUTE_MIN_BYTES, Math.round(Math.max(0, options.pixels) * perPixel));
+    return { blank: bytes.byteLength < threshold, bytes: bytes.byteLength, threshold };
+}

package/dist/utils/src/index.d.ts

@@ -0,0 +1,12 @@
+export { canonicalJsonBytes, canonicalJsonStringify, equalJson } from "./json.js";
+export { attachmentCdnUrl, ATTACHMENT_ID_PATTERN, ATTACHMENT_MAX_BYTES, ATTACHMENT_MAX_COUNT, ATTACHMENT_MAX_TOTAL_BYTES, isAttachmentCdnUrl, isAttachmentId, isStrictUtf8, parseAttachmentCdnUrl, type AttachmentCdnUrl, } from "./attachment.js";
+export { hasZipSignature, inspectStrictZip, StrictZipError, STRICT_ZIP_OOXML_LIMITS, type StrictZipEntry, type StrictZipEntryLimit, type StrictZipErrorCode, type StrictZipInspectOptions, type StrictZipLimits, type StrictZipResult, } from "./strict-zip.js";
+export { inspectSafeOoxml, OoxmlPackageError, resolveOoxmlRelationshipPart, safeOoxmlExternalHyperlinkUrl, type OoxmlKind, type OoxmlPackageErrorCode, } from "./ooxml.js";
+export { decodeBase64, encodeBase64, hexToBase64 } from "./base64.js";
+export { hashFileSet, sha256Hex } from "./content-hash.js";
+export { escapeHtml } from "./html.js";
+export { classifyIpAddress, type IpAddressScope } from "./ip-address.js";
+export { isUniqueConstraintViolation } from "./database.js";
+export { serializedSize } from "./serialized-size.js";
+export { detectBlankScreenshot, type BlankScreenshotOptions, type BlankScreenshotVerdict, } from "./image.js";
+export { createId, deterministicUuid, isUuid, UUID_PATTERN } from "./uuid.js";

package/dist/utils/src/index.js

@@ -0,0 +1,12 @@
+export { canonicalJsonBytes, canonicalJsonStringify, equalJson } from "./json.js";
+export { attachmentCdnUrl, ATTACHMENT_ID_PATTERN, ATTACHMENT_MAX_BYTES, ATTACHMENT_MAX_COUNT, ATTACHMENT_MAX_TOTAL_BYTES, isAttachmentCdnUrl, isAttachmentId, isStrictUtf8, parseAttachmentCdnUrl, } from "./attachment.js";
+export { hasZipSignature, inspectStrictZip, StrictZipError, STRICT_ZIP_OOXML_LIMITS, } from "./strict-zip.js";
+export { inspectSafeOoxml, OoxmlPackageError, resolveOoxmlRelationshipPart, safeOoxmlExternalHyperlinkUrl, } from "./ooxml.js";
+export { decodeBase64, encodeBase64, hexToBase64 } from "./base64.js";
+export { hashFileSet, sha256Hex } from "./content-hash.js";
+export { escapeHtml } from "./html.js";
+export { classifyIpAddress } from "./ip-address.js";
+export { isUniqueConstraintViolation } from "./database.js";
+export { serializedSize } from "./serialized-size.js";
+export { detectBlankScreenshot, } from "./image.js";
+export { createId, deterministicUuid, isUuid, UUID_PATTERN } from "./uuid.js";

package/dist/utils/src/ip-address.d.ts

@@ -0,0 +1,6 @@
+export type IpAddressScope = "public" | "non-public";
+/**
+ * Classifies an IP literal without treating DNS names as addresses. IPv4-mapped
+ * IPv6 is normalized before classification so it cannot bypass IPv4 policy.
+ */
+export declare function classifyIpAddress(value: string): IpAddressScope | undefined;

package/dist/utils/src/ip-address.js

@@ -0,0 +1,11 @@
+import ipaddr from "ipaddr.js";
+/**
+ * Classifies an IP literal without treating DNS names as addresses. IPv4-mapped
+ * IPv6 is normalized before classification so it cannot bypass IPv4 policy.
+ */
+export function classifyIpAddress(value) {
+    const literal = value.replace(/^\[|\]$/gu, "");
+    if (!ipaddr.isValid(literal))
+        return undefined;
+    return ipaddr.process(literal).range() === "unicast" ? "public" : "non-public";
+}

package/dist/utils/src/json.d.ts

@@ -0,0 +1,6 @@
+/** Serializes JSON with recursively sorted object keys while preserving array order. */
+export declare function canonicalJsonStringify(value: unknown): string | undefined;
+/** Encodes canonical JSON and rejects values that JSON cannot represent at the root. */
+export declare function canonicalJsonBytes(value: unknown): Uint8Array;
+/** JSON persistence ignores object key order and omits undefined object fields. */
+export declare function equalJson(left: unknown, right: unknown): boolean;

package/dist/utils/src/json.js

@@ -0,0 +1,18 @@
+/** Serializes JSON with recursively sorted object keys while preserving array order. */
+export function canonicalJsonStringify(value) {
+    return JSON.stringify(value, (_key, item) => item !== null && typeof item === "object" && !Array.isArray(item)
+        ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0))
+        : item);
+}
+/** Encodes canonical JSON and rejects values that JSON cannot represent at the root. */
+export function canonicalJsonBytes(value) {
+    const serialized = canonicalJsonStringify(value);
+    if (serialized === undefined) {
+        throw new TypeError("Value cannot be represented as JSON");
+    }
+    return new TextEncoder().encode(serialized);
+}
+/** JSON persistence ignores object key order and omits undefined object fields. */
+export function equalJson(left, right) {
+    return canonicalJsonStringify(left) === canonicalJsonStringify(right);
+}

package/dist/utils/src/ooxml.d.ts

@@ -0,0 +1,14 @@
+import { type StrictZipEntry, type StrictZipResult } from "./strict-zip.js";
+export type OoxmlKind = "docx" | "xlsx" | "pptx";
+export type OoxmlPackageErrorCode = "unsafe-content" | "missing-part";
+export declare class OoxmlPackageError extends Error {
+    readonly code: OoxmlPackageErrorCode;
+    constructor(message: string, code: OoxmlPackageErrorCode);
+}
+export declare function inspectSafeOoxml(bytes: Uint8Array, kind: OoxmlKind, options?: {
+    signal?: AbortSignal;
+    allowExternalHyperlinks?: boolean;
+    onPart?: (entry: Required<StrictZipEntry>) => void | Promise<void>;
+}): Promise<StrictZipResult>;
+export declare function safeOoxmlExternalHyperlinkUrl(target: string | null | undefined): string | null;
+export declare function resolveOoxmlRelationshipPart(sourcePart: string, target: string): string | null;