@springbrand/eval-harness 0.1.0-alpha.0 → 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
@@ -38,11 +43,30 @@ independent Eval SP deployment; the shared SP dev API and database are not used.
 
 The initialization body includes the Data sample and, only when referenced by
 that sample, `initialSession: {bundleId, sessionId, context?: {format, content}}`
-and/or `initialMaterials: {bundleId, materialId, files}`. `content` is canonical
+and/or `initialMaterials: [{bundleId, materialId, files}]`. `content` is canonical
 Session JSON or JSONL; each material file supplies its path, media type and
-base64 bytes. Supplied Session context is imported into the Chat before the Prompt and only
-material files are written to SpaceDO. A sample may specify either source, both,
-or neither. There is no Dataset-level source binding.
+base64 bytes. The material list must match the sample's `initialMaterials`
+references position by position, without duplicates. Supplied Session context is
+imported into the Chat before the Prompt and only files are written to SpaceDO,
+each material under its own `evalMaterialRoot`. A sample may specify either
+source, both, or neither. There is no Dataset-level source binding. An Evaluator
+initialization must carry `evaluationOutputSchema: {content}`, written as UTF-8
+`application/schema+json` to `EVAL_OUTPUT_SCHEMA_PATH`
+(`/evaluation-output.schema.json`); a Subject Chat rejects it. Evaluators do not
+import an initial Session. Schema validity and result validation belong to Eval
+Platform; SP preserves the supplied text. `evalMaterialFilesSchema`
+validates one material's `EvalMaterialFile` list: at most `EVAL_MATERIAL_MAX_FILES`, with unique
+paths. One initialization carries at most `EVAL_INITIAL_FILE_MAX_BYTES` per file
+and `EVAL_INITIALIZATION_MAX_BYTES` in total; size violations are Zod `too_big`
+issues. `evalMaterialFilesByteSize` returns one material's decoded bytes exactly as
+that total counts them. `readEvalCanonicalContext` accepts at most
+`EVAL_SESSION_CONTENT_MAX_CHARS` characters and `EVAL_SESSION_MAX_ENTRIES`
+entries. `EVAL_INITIALIZATION_BODY_MAX_BYTES` bounds transport JSON, accounting
+for base64 material bytes, escaped Session or Schema text, and JSON framing.
+Eval consumes these constants instead of copying the values. Its result is
+`evalInitializationResultSchema`: `{manifestHash, target, materials:
+[{bundleId, materialId, rootPath}], evaluationOutputSchemaPath?}` in request
+order; replaying the same request returns the stored result.
 
 An Evaluator is an ordinary Eval Chat with its own Session, Submission and
 Space; its creation facts add only `evaluationId`. It never reads or writes the
@@ -61,6 +85,46 @@ hash, writes `/evidence/<path>` and returns `{path, size, sha256}`. Only an
 Evaluator imports; an identical repeat is a no-op, different content is a 409,
 and imports stop with the Chat's stop latch.
 
+The Evaluator Workspace layout is one public contract, exported by this package:
+
+```text
+/initial-materials/{bundleId}/{materialId}/...  # Evaluator's own materials
+/evidence/subject-inputs/{bundleId}/{materialId}/...  # Subject's original input materials
+/evidence/artifacts/{original-relative-path}   # Subject's produced files
+/evidence/trajectory/events-000001.jsonl       # Complete raw trajectory, ordered parts
+/evidence/manifest.json                       # Evidence bundle inventory and provenance
+/evaluation-output.schema.json                # Evaluation output format
+/output/result.json                           # Evaluator's scored result
+```
+
+`EVAL_EVIDENCE_PATHS` names the bundle-relative directories. The import route takes
+paths **without** the `/evidence` prefix: `/subject-inputs/...`, `/artifacts/...`,
+`/trajectory/...` or `/manifest.json`. Other paths are rejected. The exported
+`evalSubjectInputEvidencePath`, `evalArtifactEvidencePath` and
+`evalTrajectoryEvidencePath` build those import paths; `evalEvidencePath` turns
+an import path into its absolute Workspace path. IDs are encoded as individual
+path segments and original file hierarchy is preserved, so equal basenames in
+different materials or evidence categories cannot overwrite each other.
+
+Eval Platform copies Subject inputs from the original immutable Material bundles
+referenced by this Sampling, not from the Subject's potentially edited working
+files. SP continues to exclude these inputs from artifact exports. Eval Platform
+collects **every** trajectory page until `nextAfterSeq` is null, retaining raw
+`{ingestSeq,event}` records in order; it splits oversized JSONL at event boundaries
+so every part fits `EVAL_EVIDENCE_FILE_MAX_BYTES`. Eval Platform owns the frozen
+bundle, manifest body, file hashes and preparation retries. It imports all files,
+verifies their receipts and uploads `manifest.json` last, then submits its Prompt
+with explicit evidence, Schema and result paths.
+
+SP requires completed initialization before evidence import, and a nonempty
+evidence manifest before an Evaluator's first Submission. Input writes and
+Submission admission are serialized; the first reserved Submission durably closes
+evidence imports, including after a DO restart. Replaying initialization returns
+its saved result without restoring files. Stop closes admission immediately and
+waits for accepted input writes and submissions. Evidence, initial materials and
+the fixed Schema input path are never exported as produced artifacts. SP does not
+interpret the manifest or implement Eval Platform's bundle assembly or scoring.
+
 Eval Platform writes the Evaluator instructions into the Prompt; SP submits it
 unchanged. The Evaluator's `output` adds `structuredOutput: {path, content,
 contentHash}` with the raw UTF-8 text of `/output/result.json` in its own Space

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

@@ -1,11 +1,12 @@
 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<{
     chatId: z.ZodUUID;
     role: z.ZodEnum<{
-        evaluator: "evaluator";
         subject: "subject";
+        evaluator: "evaluator";
     }>;
     framework: z.ZodLiteral<"sp">;
     samplingId: z.ZodString;
@@ -19,11 +20,29 @@ export declare const evalEnsureChatSchema: z.ZodObject<{
         timeoutMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
-export declare const evalMaterialFileSchema: z.ZodObject<{
+export declare const EVAL_INITIAL_FILE_MAX_BYTES = 5000000;
+export declare const EVAL_INITIALIZATION_MAX_BYTES = 20000000;
+export declare const EVAL_MATERIAL_MAX_FILES = 500;
+export declare const EVAL_SESSION_CONTENT_MAX_CHARS = 2000000;
+export declare const EVAL_SESSION_MAX_ENTRIES = 10000;
+export declare const EVAL_OUTPUT_SCHEMA_PATH = "/evaluation-output.schema.json";
+export declare const EVAL_INITIAL_MATERIALS_ROOT = "/initial-materials";
+/** Subject Session JSON and Evaluator Schema JSON can expand to six bytes per character. */
+export declare const EVAL_INITIALIZATION_BODY_MAX_BYTES: number;
+/** Decoded bytes of validated Material files, counted exactly as the initialization budget counts them. */
+export declare const evalMaterialFilesByteSize: (files: readonly {
+    readonly contentBase64: string;
+}[]) => number;
+declare const evalMaterialFileSchema: z.ZodObject<{
     path: z.ZodString;
     mediaType: z.ZodString;
     contentBase64: z.ZodBase64;
 }, z.core.$strict>;
+export declare const evalMaterialFilesSchema: z.ZodArray<z.ZodObject<{
+    path: z.ZodString;
+    mediaType: z.ZodString;
+    contentBase64: z.ZodBase64;
+}, z.core.$strict>>;
 export declare const evalInitialContextSchema: z.ZodObject<{
     format: z.ZodEnum<{
         json: "json";
@@ -47,7 +66,7 @@ export declare const evalInitializationSchema: z.ZodObject<{
             content: z.ZodString;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
-    initialMaterials: z.ZodOptional<z.ZodObject<{
+    initialMaterials: z.ZodOptional<z.ZodArray<z.ZodObject<{
         bundleId: z.ZodString;
         materialId: z.ZodString;
         files: z.ZodArray<z.ZodObject<{
@@ -55,8 +74,21 @@ export declare const evalInitializationSchema: z.ZodObject<{
             mediaType: z.ZodString;
             contentBase64: z.ZodBase64;
         }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+    evaluationOutputSchema: z.ZodOptional<z.ZodObject<{
+        content: z.ZodString;
     }, z.core.$strict>>;
 }, z.core.$strict>;
+export declare const evalInitializationResultSchema: z.ZodObject<{
+    manifestHash: z.ZodString;
+    target: z.ZodLiteral<"workspace">;
+    materials: z.ZodArray<z.ZodObject<{
+        bundleId: z.ZodString;
+        materialId: z.ZodString;
+        rootPath: z.ZodString;
+    }, z.core.$strict>>;
+    evaluationOutputSchemaPath: z.ZodExactOptional<z.ZodLiteral<"/evaluation-output.schema.json">>;
+}, z.core.$strict>;
 export declare const evalSubmitSchema: z.ZodObject<{
     idempotencyKey: z.ZodString;
     prompt: z.ZodString;
@@ -66,7 +98,9 @@ export declare const evalSubmitSchema: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type EvalEnsureChat = z.output<typeof evalEnsureChatSchema>;
+export type EvalMaterialFile = z.output<typeof evalMaterialFileSchema>;
 export type EvalInitialization = z.output<typeof evalInitializationSchema>;
+export type EvalInitializationResult = z.output<typeof evalInitializationResultSchema>;
 export type EvalSubmit = z.output<typeof evalSubmitSchema>;
 export type EvalSubmissionReceipt = {
     readonly submissionId: string;
@@ -135,6 +169,13 @@ export declare function evalMaterialRoot(bundleId: string, materialId: string):
 export declare function evalMaterialPath(root: string, path: string): string;
 /** Where imported evidence lives in the Evaluator's own Space. */
 export declare const EVAL_EVIDENCE_ROOT = "/evidence";
+/** Bundle-relative paths, used by the import route; evalEvidencePath returns their Workspace paths. */
+export declare const EVAL_EVIDENCE_PATHS: {
+    readonly subjectInputs: "/subject-inputs";
+    readonly artifacts: "/artifacts";
+    readonly trajectory: "/trajectory";
+    readonly manifest: "/manifest.json";
+};
 /** One exported or imported file crosses a single Durable Object RPC as bytes. */
 export declare const EVAL_EVIDENCE_FILE_MAX_BYTES = 25000000;
 export declare const EVAL_EVIDENCE_TRAJECTORY_PAGE_MAX = 200;
@@ -169,6 +210,19 @@ export declare function readEvalTrajectoryPageQuery(params: URLSearchParams): {
 };
 /** A Space path for one evidence file; `relative` keeps the bundle's own layout below `/evidence`. */
 export declare function evalEvidencePath(relative: string): string;
+/** Original Subject inputs stay separate from produced artifacts and the Evaluator's own materials. */
+export declare function evalSubjectInputEvidencePath(bundleId: string, materialId: string, path: string): string;
+export declare function evalArtifactEvidencePath(path: string): string;
+/** Positive part numbers preserve the complete raw JSONL trajectory's order. */
+export declare function evalTrajectoryEvidencePath(part: number): string;
+/** One raw evidence file imported into the Evaluator's own Space. */
+export type EvalEvidenceFileInput = {
+    /** Bundle-relative path under one of EVAL_EVIDENCE_PATHS, without the /evidence prefix. */
+    readonly path: string;
+    readonly mediaType: string;
+    readonly sha256: string;
+    readonly bytes: Uint8Array;
+};
 /** The receipt for one imported file; identical repeats return the same receipt. */
 export type EvalEvidenceFileReceipt = {
     readonly path: string;

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

@@ -1,4 +1,6 @@
 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);
@@ -18,10 +20,41 @@ export const evalEnsureChatSchema = z.strictObject({
         context.addIssue({ code: "custom", path: ["evaluationId"], message: "Evaluation ID must match role" });
     }
 });
-export const evalMaterialFileSchema = z.strictObject({
-    path: z.string().startsWith("/").min(2),
+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(),
+    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"]),
@@ -35,22 +68,42 @@ export const evalInitializationSchema = z.strictObject({
         sessionId: id,
         context: evalInitialContextSchema.optional(),
     }).optional(),
-    initialMaterials: z.strictObject({
-        bundleId: id,
-        materialId: id,
-        files: z.array(evalMaterialFileSchema).max(500),
+    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 materials = value.data.initialMaterials;
+    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 (materials ? !value.initialMaterials || materials.bundleId !== value.initialMaterials.bundleId ||
-        materials.materialId !== value.initialMaterials.materialId : value.initialMaterials !== undefined) {
+    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,
@@ -77,7 +130,7 @@ export function projectEvalSubmission(input) {
 }
 /** JSON stores one canonical snapshot; JSONL stores one canonical entry per line. */
 export function readEvalCanonicalContext(input) {
-    if (input.content.length > 2_000_000)
+    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)
@@ -86,7 +139,7 @@ export function readEvalCanonicalContext(input) {
         throw new Error("Initial context must contain canonical entries");
     }
     const entries = parsed.entries;
-    if (entries.length > 10_000)
+    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) {
@@ -121,12 +174,14 @@ export async function readEvalStructuredOutput(path, bytes) {
     catch {
         throw new Error(`${EVAL_RESULT_FILE} is not valid UTF-8`);
     }
-    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new Uint8Array(bytes)));
-    const contentHash = `sha256:${[...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+    const contentHash = `sha256:${await sha256Hex(bytes)}`;
     return { path, content, contentHash };
 }
 export function evalMaterialRoot(bundleId, materialId) {
-    return `/initial-materials/${encodeURIComponent(bundleId)}/${encodeURIComponent(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) {
@@ -148,6 +203,13 @@ export function evalMaterialPath(root, path) {
  */
 /** 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;
@@ -173,24 +235,32 @@ export function readEvalTrajectoryPageQuery(params) {
 /** 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)
+    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) {
-    return JSON.stringify(sortFacts(value));
-}
-function sortFacts(value) {
-    if (Array.isArray(value))
-        return value.map(sortFacts);
-    if (!value || typeof value !== "object")
-        return value;
-    return Object.fromEntries(Object.entries(value)
-        .filter(([, item]) => item !== undefined)
-        .sort(([left], [right]) => left.localeCompare(right))
-        .map(([key, item]) => [key, sortFacts(item)]));
+    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;

package/dist/utils/src/ooxml.js

@@ -0,0 +1,170 @@
+import { SaxesParser } from "saxes";
+import { inspectStrictZip, STRICT_ZIP_OOXML_LIMITS, } from "./strict-zip.js";
+export class OoxmlPackageError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "OoxmlPackageError";
+    }
+}
+const REQUIRED_PARTS = {
+    docx: ["[Content_Types].xml", "_rels/.rels", "word/document.xml"],
+    xlsx: [
+        "[Content_Types].xml",
+        "_rels/.rels",
+        "xl/workbook.xml",
+        "xl/_rels/workbook.xml.rels",
+    ],
+    pptx: [
+        "[Content_Types].xml",
+        "_rels/.rels",
+        "ppt/presentation.xml",
+        "ppt/_rels/presentation.xml.rels",
+    ],
+};
+const UNSAFE_METADATA = /(?:macroenabled|vbaproject|activex|oleobject)/iu;
+const XML_DECODER = new TextDecoder("utf-8", { fatal: true, ignoreBOM: false });
+export async function inspectSafeOoxml(bytes, kind, options = {}) {
+    options.signal?.throwIfAborted();
+    const absoluteTargets = new Set();
+    const result = await inspectStrictZip(bytes, STRICT_ZIP_OOXML_LIMITS, undefined, {
+        onEntry: async (entry) => {
+            options.signal?.throwIfAborted();
+            validateOoxmlPart(entry, absoluteTargets, options.allowExternalHyperlinks === true);
+            await options.onPart?.(entry);
+            options.signal?.throwIfAborted();
+        },
+    });
+    options.signal?.throwIfAborted();
+    const paths = new Set(result.entries.filter((entry) => !entry.directory).map((entry) => entry.path));
+    for (const target of absoluteTargets) {
+        if (!paths.has(target)) {
+            throw new OoxmlPackageError(`Absolute relationship target ${target} is not a package part`, "unsafe-content");
+        }
+    }
+    for (const path of REQUIRED_PARTS[kind]) {
+        if (!paths.has(path))
+            throw new OoxmlPackageError(`Missing required ${kind.toUpperCase()} part ${path}`, "missing-part");
+    }
+    return result;
+}
+function validateOoxmlPart({ path, bytes }, absoluteTargets, allowExternalHyperlinks) {
+    const folded = path.toLocaleLowerCase("en-US");
+    const segments = folded.split("/");
+    if (folded.includes("vbaproject") ||
+        segments.some((segment) => segment.startsWith("activex")) ||
+        segments.some((segment) => /^(?:encryptioninfo|encryptedpackage|dataspaces)(?:\.|$)/u.test(segment)) ||
+        (segments.includes("embeddings") && segments.some((segment) => segment.includes("oleobject") || segment.endsWith(".bin")))) {
+        throw new OoxmlPackageError(`Unsafe OOXML part ${path}`, "unsafe-content");
+    }
+    if (!/\.(?:xml|rels)$/iu.test(path))
+        return;
+    const parser = new SaxesParser({ xmlns: true, fragment: false });
+    parser.on("doctype", () => {
+        throw new OoxmlPackageError(`${path} contains a DOCTYPE`, "unsafe-content");
+    });
+    parser.on("processinginstruction", () => {
+        throw new OoxmlPackageError(`${path} contains a processing instruction`, "unsafe-content");
+    });
+    parser.on("opentag", (tag) => {
+        if (/\.rels$/iu.test(path)) {
+            assertSafeRelationship(tag, path, absoluteTargets, allowExternalHyperlinks);
+        }
+        if (path === "[Content_Types].xml") {
+            const contentType = attributeValue(tag, "contenttype");
+            if (contentType && UNSAFE_METADATA.test(contentType)) {
+                throw new OoxmlPackageError(`${path} contains unsafe metadata`, "unsafe-content");
+            }
+        }
+    });
+    try {
+        parser.write(XML_DECODER.decode(bytes)).close();
+    }
+    catch (error) {
+        if (error instanceof OoxmlPackageError)
+            throw error;
+        throw new OoxmlPackageError(`${path} contains invalid or unsafe XML`, "unsafe-content");
+    }
+}
+function assertSafeRelationship(tag, path, absoluteTargets, allowExternalHyperlinks) {
+    if (tag.local.toLocaleLowerCase("en-US") !== "relationship")
+        return;
+    const target = attributeValue(tag, "target");
+    const resolved = target === undefined ? undefined : resolveOoxmlRelationshipPart(sourcePartForRelationships(path), target);
+    const relationshipType = attributeValue(tag, "type") ?? "";
+    const targetMode = attributeValue(tag, "targetmode")?.toLocaleLowerCase("en-US");
+    if (targetMode === "external" && allowExternalHyperlinks && isSafeExternalHyperlink(relationshipType, target)) {
+        return;
+    }
+    if (targetMode === "external" ||
+        (target !== undefined && resolved === null)) {
+        throw new OoxmlPackageError(`${path} contains an unsafe relationship target`, "unsafe-content");
+    }
+    if (target?.startsWith("/") && resolved)
+        absoluteTargets.add(resolved);
+    if (UNSAFE_METADATA.test(relationshipType)) {
+        throw new OoxmlPackageError(`${path} contains an unsafe relationship type`, "unsafe-content");
+    }
+}
+function isSafeExternalHyperlink(type, target) {
+    return /\/hyperlink$/iu.test(type) && safeOoxmlExternalHyperlinkUrl(target) !== null;
+}
+export function safeOoxmlExternalHyperlinkUrl(target) {
+    if (!target)
+        return null;
+    try {
+        const url = new URL(target);
+        return (url.protocol === "http:" || url.protocol === "https:") && !url.username && !url.password
+            ? url.href
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveOoxmlRelationshipPart(sourcePart, target) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(target);
+    }
+    catch {
+        return null;
+    }
+    const path = decoded.split(/[?#]/u, 1)[0] ?? "";
+    if (!path || path.startsWith("//") || decoded.includes("\\") ||
+        (decoded.startsWith("/") && !target.startsWith("/")) ||
+        /[\u0000-\u001f\u007f]/u.test(decoded) ||
+        /^[A-Za-z][A-Za-z\d+.-]*:/u.test(decoded) ||
+        /%(?:2e|2f|5c|3a)/iu.test(target) ||
+        /%(?:2e|2f|5c|3a)/iu.test(decoded))
+        return null;
+    const absolute = path.startsWith("/");
+    const segments = (absolute ? path.slice(1) : path).split("/");
+    if (segments.some((segment) => !segment) || (absolute && segments.includes("..")))
+        return null;
+    const normalized = absolute ? [] : sourcePart.split("/").slice(0, -1);
+    for (const segment of segments) {
+        if (segment === ".")
+            continue;
+        if (segment === "..") {
+            if (normalized.length === 0)
+                return null;
+            normalized.pop();
+        }
+        else {
+            normalized.push(segment);
+        }
+    }
+    const resolved = normalized.join("/");
+    return resolved || null;
+}
+function sourcePartForRelationships(path) {
+    if (path === "_rels/.rels")
+        return "";
+    const separator = path.lastIndexOf("/_rels/");
+    return separator < 0 ? "" : `${path.slice(0, separator)}/${path.slice(separator + 7, -5)}`;
+}
+function attributeValue(tag, name) {
+    return Object.values(tag.attributes).find((attribute) => attribute.local.toLocaleLowerCase("en-US") === name)?.value;
+}

package/dist/utils/src/serialized-size.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The byte cost of a value once it is JSON.
+ *
+ * Every budget that bounds what a model may receive is stated in bytes, and a
+ * string's `length` is UTF-16 code units — so measuring with `length` silently
+ * under-counts any non-ASCII payload, which is exactly the payload most likely
+ * to be near a limit.
+ */
+export declare function serializedSize(value: unknown): number;

package/dist/utils/src/serialized-size.js

@@ -0,0 +1,11 @@
+/**
+ * The byte cost of a value once it is JSON.
+ *
+ * Every budget that bounds what a model may receive is stated in bytes, and a
+ * string's `length` is UTF-16 code units — so measuring with `length` silently
+ * under-counts any non-ASCII payload, which is exactly the payload most likely
+ * to be near a limit.
+ */
+export function serializedSize(value) {
+    return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+}

package/dist/utils/src/strict-zip.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Strict-ZIP structural safety limits. Every field is required so each caller
+ * states its own budget explicitly; pass `Infinity` for a check the caller does
+ * not want the shared inspector to enforce.
+ */
+export type StrictZipLimits = {
+    /** Maximum number of entries in the archive. */
+    entries: number;
+    /** Maximum uncompressed size of a single entry. */
+    maxEntryBytes: number;
+    /** Maximum aggregate uncompressed size across all entries. */
+    maxExpandedBytes: number;
+    /** Maximum compression ratio (uncompressed / compressed) for a non-empty entry. */
+    maxCompressionRatio: number;
+    /** Maximum filename length in characters. */
+    pathCharacters: number;
+};
+/**
+ * Default limits for OOXML packages (DOCX/XLSX/PPTX). These match the bounds the
+ * existing Attachment XLSX validator enforced and the Creation admission matrix
+ * requires.
+ */
+export declare const STRICT_ZIP_OOXML_LIMITS: StrictZipLimits;
+export type StrictZipErrorCode = "not-zip" | "invalid-archive" | "too-many-entries" | "path-too-long" | "unsafe-path" | "duplicate-path" | "case-collision" | "non-regular" | "encrypted" | "unsupported-compression" | "invalid-size" | "entry-too-large" | "aggregate-too-large" | "compression-ratio" | "invalid-entry" | "size-mismatch";
+export declare class StrictZipError extends Error {
+    readonly code: StrictZipErrorCode;
+    readonly path?: string | undefined;
+    constructor(message: string, code: StrictZipErrorCode, path?: string | undefined);
+}
+/** One inspected archive entry with its safe logical path and optional expanded bytes. */
+export type StrictZipEntry = {
+    path: string;
+    bytes?: Uint8Array;
+    directory: boolean;
+};
+/** Bounded package facts returned to a caller for further policy validation. */
+export type StrictZipResult = {
+    /** All entries sorted by path. Directory entries carry an empty byte array. */
+    entries: StrictZipEntry[];
+    compressedBytes: number;
+    expandedBytes: number;
+};
+/** Optional per-path ceiling, so a caller can state its own budget for a known path. */
+export type StrictZipEntryLimit = (path: string) => {
+    maxBytes: number;
+    message: string;
+} | undefined;
+export type StrictZipInspectOptions = {
+    /** Consume one validated file while its expanded bytes are live. */
+    onEntry?: (entry: Required<StrictZipEntry>) => void | Promise<void>;
+    /** Retain every expanded file in the returned result. Defaults to false. */
+    retainBytes?: boolean;
+    signal?: AbortSignal;
+};
+export declare function hasZipSignature(bytes: Uint8Array): boolean;
+/**
+ * Inspects an untrusted ZIP archive and returns bounded package facts. Every
+ * structural bound that protects a caller from a hostile archive — path shape,
+ * entry count, regular-file type, encryption, compression method, per-entry and
+ * aggregate expansion, compression ratio, overlapping entries, invalid CRCs,
+ * duplicate and case-colliding paths — is enforced here so no consumer needs to
+ * copy archive safety logic.
+ *
+ * Callers that inspect content should use `onEntry`, which releases each
+ * expanded file before the next is read. Only callers that need a complete
+ * in-memory archive should opt into `retainBytes`.
+ */
+export declare function inspectStrictZip(untrustedBytes: Uint8Array, limits: StrictZipLimits, entryLimit?: StrictZipEntryLimit, options?: StrictZipInspectOptions): Promise<StrictZipResult>;

package/dist/utils/src/strict-zip.js

@@ -0,0 +1,177 @@
+const MiB = 1024 * 1024;
+/**
+ * Default limits for OOXML packages (DOCX/XLSX/PPTX). These match the bounds the
+ * existing Attachment XLSX validator enforced and the Creation admission matrix
+ * requires.
+ */
+export const STRICT_ZIP_OOXML_LIMITS = {
+    entries: 2_048,
+    maxEntryBytes: 64 * MiB,
+    maxExpandedBytes: 200 * MiB,
+    maxCompressionRatio: 1_000,
+    pathCharacters: 768,
+};
+export class StrictZipError extends Error {
+    code;
+    path;
+    constructor(message, code, path) {
+        super(path ? `${path}: ${message}` : message);
+        this.code = code;
+        this.path = path;
+        this.name = "StrictZipError";
+    }
+}
+function strictZipFail(message, code, path) {
+    throw new StrictZipError(message, code, path);
+}
+export function hasZipSignature(bytes) {
+    return (bytes.length >= 4 &&
+        bytes[0] === 0x50 &&
+        bytes[1] === 0x4b &&
+        ((bytes[2] === 0x03 && bytes[3] === 0x04) ||
+            (bytes[2] === 0x05 && bytes[3] === 0x06) ||
+            (bytes[2] === 0x07 && bytes[3] === 0x08)));
+}
+function logicalPath(entry, pathCharacters) {
+    const raw = entry.filename;
+    if (raw.length > pathCharacters) {
+        strictZipFail(`Path exceeds ${pathCharacters} characters`, "path-too-long", raw);
+    }
+    if (!raw || raw.includes("\\") || raw.includes("\0") || raw.startsWith("/") || /^[A-Za-z]:/u.test(raw)) {
+        strictZipFail("Unsafe archive path", "unsafe-path", raw || "<empty path>");
+    }
+    const path = entry.directory && raw.endsWith("/") ? raw.slice(0, -1) : raw;
+    if (!path || path.split("/").some((segment) => !segment || segment === "." || segment === "..")) {
+        strictZipFail("Unsafe archive path", "unsafe-path", raw);
+    }
+    return path;
+}
+function assertRegularFile(entry, path, limits) {
+    const unixType = entry.unixMode === undefined ? 0 : entry.unixMode & 0o170000;
+    if (unixType !== 0 && unixType !== 0o100000) {
+        strictZipFail("Archive entry must be a regular file", "non-regular", path);
+    }
+    if (entry.encrypted)
+        strictZipFail("Encrypted archive entries are not supported", "encrypted", path);
+    if (entry.compressionMethod !== 0 && entry.compressionMethod !== 8) {
+        strictZipFail(`Unsupported ZIP compression method ${entry.compressionMethod}`, "unsupported-compression", path);
+    }
+    if (!Number.isSafeInteger(entry.compressedSize) ||
+        !Number.isSafeInteger(entry.uncompressedSize) ||
+        entry.compressedSize < 0 ||
+        entry.uncompressedSize < 0) {
+        strictZipFail("Invalid declared size", "invalid-size", path);
+    }
+    if (entry.uncompressedSize > limits.maxEntryBytes) {
+        strictZipFail(`Entry exceeds ${limits.maxEntryBytes} bytes`, "entry-too-large", path);
+    }
+    if (entry.uncompressedSize > 0 &&
+        entry.compressedSize > 0 &&
+        entry.uncompressedSize / entry.compressedSize > limits.maxCompressionRatio) {
+        strictZipFail("Compression ratio exceeds the allowed ceiling", "compression-ratio", path);
+    }
+}
+/**
+ * Inspects an untrusted ZIP archive and returns bounded package facts. Every
+ * structural bound that protects a caller from a hostile archive — path shape,
+ * entry count, regular-file type, encryption, compression method, per-entry and
+ * aggregate expansion, compression ratio, overlapping entries, invalid CRCs,
+ * duplicate and case-colliding paths — is enforced here so no consumer needs to
+ * copy archive safety logic.
+ *
+ * Callers that inspect content should use `onEntry`, which releases each
+ * expanded file before the next is read. Only callers that need a complete
+ * in-memory archive should opt into `retainBytes`.
+ */
+export async function inspectStrictZip(untrustedBytes, limits, entryLimit, options = {}) {
+    options.signal?.throwIfAborted();
+    if (!hasZipSignature(untrustedBytes))
+        strictZipFail("Body is not a ZIP archive", "not-zip");
+    const { Uint8ArrayReader, Uint8ArrayWriter, ZipReader } = await import("@zip.js/zip.js");
+    const reader = new ZipReader(new Uint8ArrayReader(untrustedBytes), {
+        strictness: "strict",
+        useWebWorkers: false,
+    });
+    try {
+        let entries;
+        try {
+            entries = await reader.getEntries({ strictness: "strict" });
+        }
+        catch (error) {
+            options.signal?.throwIfAborted();
+            strictZipFail(error instanceof Error ? `Invalid ZIP archive: ${error.message}` : "Invalid ZIP archive", "invalid-archive");
+        }
+        options.signal?.throwIfAborted();
+        if (entries.length > limits.entries) {
+            strictZipFail(`ZIP contains more than ${limits.entries} entries`, "too-many-entries");
+        }
+        const seen = new Set();
+        const seenCaseFolded = new Set();
+        const paths = new Map();
+        const directories = [];
+        let totalSize = 0;
+        for (const entry of entries) {
+            options.signal?.throwIfAborted();
+            const path = logicalPath(entry, limits.pathCharacters);
+            const folded = path.toLocaleLowerCase("en-US");
+            if (seen.has(path))
+                strictZipFail("Duplicate normalized archive path", "duplicate-path", path);
+            if (seenCaseFolded.has(folded))
+                strictZipFail("Case-insensitive archive path collision", "case-collision", path);
+            seen.add(path);
+            seenCaseFolded.add(folded);
+            paths.set(entry, path);
+            if (entry.directory) {
+                directories.push(path);
+                continue;
+            }
+            assertRegularFile(entry, path, limits);
+            totalSize += entry.uncompressedSize;
+            if (totalSize > limits.maxExpandedBytes) {
+                strictZipFail(`Total uncompressed size exceeds ${limits.maxExpandedBytes} bytes`, "aggregate-too-large");
+            }
+            const limit = entryLimit?.(path);
+            if (limit && entry.uncompressedSize > limit.maxBytes)
+                strictZipFail(limit.message, "entry-too-large", path);
+        }
+        const fileEntries = entries
+            .filter((entry) => !entry.directory)
+            .sort((left, right) => paths.get(left).localeCompare(paths.get(right)));
+        const result = [];
+        for (const entry of fileEntries) {
+            options.signal?.throwIfAborted();
+            const path = paths.get(entry);
+            let bytes;
+            try {
+                bytes = await entry.getData(new Uint8ArrayWriter(), {
+                    checkSignature: true,
+                    checkOverlappingEntry: true,
+                    strictness: "strict",
+                    ...(options.signal ? { signal: options.signal } : {}),
+                });
+            }
+            catch (error) {
+                options.signal?.throwIfAborted();
+                strictZipFail(error instanceof Error ? `Invalid ZIP entry: ${error.message}` : "Invalid ZIP entry", "invalid-entry", path);
+            }
+            options.signal?.throwIfAborted();
+            if (bytes.byteLength !== entry.uncompressedSize)
+                strictZipFail("Declared and actual sizes differ", "size-mismatch", path);
+            await options.onEntry?.({ path, bytes, directory: false });
+            options.signal?.throwIfAborted();
+            result.push({ path, ...(options.retainBytes ? { bytes } : {}), directory: false });
+        }
+        for (const directory of directories.sort((left, right) => left.localeCompare(right))) {
+            options.signal?.throwIfAborted();
+            result.push({ path: directory, bytes: new Uint8Array(), directory: true });
+        }
+        return {
+            entries: result,
+            compressedBytes: untrustedBytes.byteLength,
+            expandedBytes: totalSize,
+        };
+    }
+    finally {
+        await reader.close();
+    }
+}

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

@@ -0,0 +1,9 @@
+/**
+ * UUID pattern without anchors, for embedding in larger patterns such as route
+ * matchers. Matches the RFC 4122 shape produced by `crypto.randomUUID()`.
+ */
+export declare const UUID_PATTERN = "[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}";
+/** Generates the opaque UUID used by newly persisted application entities. */
+export declare function createId(): string;
+export declare function isUuid(value: unknown): value is string;
+export declare function deterministicUuid(value: string): Promise<string>;

package/dist/utils/src/uuid.js

@@ -0,0 +1,27 @@
+import { sha256Hex } from "./content-hash.js";
+/**
+ * UUID pattern without anchors, for embedding in larger patterns such as route
+ * matchers. Matches the RFC 4122 shape produced by `crypto.randomUUID()`.
+ */
+export const UUID_PATTERN = "[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}";
+const UUID_RE = new RegExp(`^${UUID_PATTERN}$`);
+/** Generates the opaque UUID used by newly persisted application entities. */
+export function createId() {
+    if (typeof crypto.randomUUID === "function")
+        return crypto.randomUUID();
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+export function isUuid(value) {
+    return typeof value === "string" && UUID_RE.test(value);
+}
+export async function deterministicUuid(value) {
+    const chars = (await sha256Hex(value)).slice(0, 32).split("");
+    chars[12] = "5";
+    chars[16] = ((Number.parseInt(chars[16], 16) & 0x3) | 0x8).toString(16);
+    const hex = chars.join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/package.json

@@ -1,34 +1,32 @@
 {
   "name": "@springbrand/eval-harness",
-  "version": "0.1.0-alpha.0",
-  "description": "SP service contract for Eval-managed Chats: routes, headers and wire schemas.",
-  "license": "MIT",
+  "version": "0.1.0-alpha.2",
   "type": "module",
+  "license": "UNLICENSED",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "types": "./dist/eval-harness/src/index.d.ts",
+      "import": "./dist/eval-harness/src/index.js"
     }
   },
   "files": [
     "dist",
     "README.md"
   ],
-  "publishConfig": {
-    "access": "public",
-    "tag": "alpha"
-  },
+  "sideEffects": false,
   "dependencies": {
+    "@zip.js/zip.js": "^2.8.34",
+    "ipaddr.js": "2.5.0",
+    "saxes": "^6.0.0",
     "zod": "^4.6.5"
   },
-  "devDependencies": {
-    "typescript": "^7.0.2",
-    "vitest": "^4.1.10"
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
   },
-  "scripts": {
-    "build": "tsc --noEmit",
-    "check": "tsc --noEmit",
-    "test": "vitest run",
-    "build:dist": "rm -rf dist && tsc -p tsconfig.build.json"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/springbrand-lab/sp-platform.git",
+    "directory": "packages/eval-harness"
   }
-}
+}