@haystackeditor/cli 0.15.31 → 0.17.0

package/dist/commands/case-batch-contract.js

@@ -0,0 +1,694 @@
+/** FIXED CONTRACT — mirror of CASE-BATCH-V1 for the published CLI, whose build
+ * cannot import repository files outside `src`. The authority is
+ * `infra/lambda/haystack-design-verifier-shared/case_batch_contracts.ts`
+ * (frozen at feec1004cab4a2344d3730ccddd94d8eaaedbaec), the admission rules in
+ * `infra/lambda/haystack-design-verifier-shared/case_batch_validation.ts`
+ * (whose primitives come from `combination_search_validation.ts`), and
+ * `docs/case-batch-coordinator.md`; this file restates only what the CLI
+ * submits, reads back, and verifies. Where it restates an admission rule it
+ * restates it exactly — a submission the CLI accepts and the gateway refuses
+ * is a round trip the caller pays for and loses. It never restates the runner-side or
+ * queue-side rows: Lane D submits and polls, nothing else.
+ *
+ * The CLI carries no fleet credential and no trusted host path. The only
+ * credential any request here can carry is the caller's Haystack login bearer.
+ */
+import { createHash } from 'node:crypto';
+/** Bounds, copied verbatim from the frozen contract. */
+export const CASE_BATCH_VERSION = 'case-batch-v4';
+export const CASE_BATCH_MAX_CONCURRENT_CASES = 500;
+export const CASE_BATCH_MAX_CASES = 5_000;
+export const CASE_BATCH_MAX_INPUT_BYTES = 8 * 1024 * 1024;
+export const CASE_BATCH_MIN_CASE_WALL_MS = 1_000;
+export const CASE_BATCH_MAX_CASE_WALL_MS = 600_000;
+export const CASE_BATCH_MIN_TOTAL_BUDGET_MS = 10_000;
+export const CASE_BATCH_MAX_TOTAL_BUDGET_MS = 30 * 60_000;
+export const CASE_BATCH_VM_SLOTS_PER_CASE = 2;
+export const CASE_BATCH_ID_PATTERN = /^[A-Za-z0-9_-]{1,160}$/u;
+/** v4: `ProductCase.repeatIndex` is an integer from 1 to this; absent is the original experiment. */
+export const CASE_BATCH_MAX_REPEAT_INDEX = 16;
+/** `CombinationSearchStatus`, reused by the batch without change. */
+export const CASE_BATCH_STATUSES = [
+    'queued', 'preparing', 'searching', 'draining', 'completed', 'incomplete', 'cancelled',
+];
+export const CASE_BATCH_TERMINAL_STATUSES = ['completed', 'incomplete', 'cancelled'];
+export function isTerminalCaseBatchStatus(status) {
+    return CASE_BATCH_TERMINAL_STATUSES.includes(status);
+}
+/** Ruling 1 in docs/case-batch-coordinator.md: adding an unknown reason is
+ * additive, so a consumer that does not know a reason still reads the outcome
+ * as UNKNOWN. This CLI therefore never rejects an unrecognised reason; the
+ * list exists only to render the ones it can explain. */
+export const KNOWN_CASE_UNKNOWN_REASONS = [
+    'missing-state', 'missing-action', 'missing-harness', 'arrival-failed',
+    'comparison-unavailable', 'infrastructure', 'wall-budget', 'wall-watchdog', 'worker-exited',
+];
+/** MIRRORED RULES (v2) — `case_batch_contracts.ts`: a start value is a reference id or two joined by
+ * one '='; the action and observation kinds the runtime executes; the execution paths an outcome names. */
+export const CASE_START_VALUE_PATTERN = /^(?=.{1,256}$)[A-Za-z0-9._:/-]+(?:=[A-Za-z0-9._:/-]+)?$/u;
+export const CASE_BATCH_ACTION_KINDS = ['navigate', 'click', 'type', 'wait-for', 'exec', 'raw-pointer', 'key', 'focus',
+    'pointer-move', 'pointer-down', 'pointer-up', 'type-focused'];
+export const CASE_BATCH_OBSERVATION_KINDS = ['dom-inventory', 'visible-text-digest', 'url', 'main-document',
+    'element-count', 'element-state', 'focused-element', 'storage-snapshot'];
+export const CASE_EXECUTION_PATHS = ['resident-sealed-plan', 'sealed-plan', 'record-replay'];
+/** v4: the sources a failure fact names today (`CASE_FAILURE_SOURCES` in the contract). Read-side, a
+ *  source added later is still rendered, as an unrecognised unknown reason is: the list documents, it
+ *  does not refuse. */
+export const KNOWN_CASE_FAILURE_SOURCES = ['control-plane', 'transport', 'harness', 'runner'];
+export class CaseBatchRequestValidationError extends TypeError {
+    name = 'CaseBatchRequestValidationError';
+}
+export class CaseBatchRequestSizeError extends RangeError {
+    name = 'CaseBatchRequestSizeError';
+}
+export class CaseBatchResponseError extends Error {
+    name = 'CaseBatchResponseError';
+}
+function fail(what) {
+    throw new CaseBatchRequestValidationError(`Invalid case batch ${what}.`);
+}
+function bad(what) {
+    throw new CaseBatchResponseError(`Case batch service returned an invalid ${what}.`);
+}
+const ALPHANUMERIC = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+export function isJsonObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function object(value, what) {
+    if (!isJsonObject(value))
+        fail(what);
+    return value;
+}
+function keys(value, required, optional = []) {
+    for (const key of required)
+        if (!Object.hasOwn(value, key))
+            fail(`fields (missing ${key})`);
+    for (const key of Object.keys(value)) {
+        if (!required.includes(key) && !optional.includes(key))
+            fail(`fields (unexpected ${key})`);
+    }
+}
+function text(value, what, maximum = 4_096) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > maximum
+        || value.includes('\0'))
+        fail(what);
+    return value;
+}
+/** At most the first 64 characters of an offending value, JSON-quoted so the
+ * refusal stays on one line whatever the value contains. */
+const EXCERPT_LIMIT = 64;
+function excerpt(value) {
+    return value.length > EXCERPT_LIMIT
+        ? `${JSON.stringify(value.slice(0, EXCERPT_LIMIT))} (truncated)`
+        : JSON.stringify(value);
+}
+/** MIRRORED RULE — `referenceIdentity` in
+ * `infra/lambda/haystack-design-verifier-shared/case_batch_validation.ts`,
+ * which is `token(value, REFERENCE_IDENTITY, 1, 256, field)` over the shared
+ * `token` helper in `combination_search_validation.ts`:
+ *
+ *   REFERENCE_IDENTITY = A-Z a-z 0-9 . _ : / -
+ *   a non-empty string, 1 to 256 characters, every character in that set.
+ *
+ * The gateway applies it to `conditionId`, `variantOf`, `surfaceId`,
+ * `finalControlId`, every `staticReach` entry, and every `start` axis and
+ * value. This file cannot import the gateway module, so the rule is copied.
+ * It is copied exactly on purpose: anything the CLI accepts here and the
+ * gateway refuses is a submission that only dies at admission, after the
+ * caller has already paid to build it. */
+const REFERENCE_IDENTITY_CHARACTERS = `${ALPHANUMERIC}._:/-`;
+const REFERENCE_IDENTITY_MAXIMUM = 256;
+/** Mirrors the gateway's `start()`: at most 1000 axes on one case. */
+const CASE_START_MAX_AXES = 1_000;
+/** Mirrors the gateway's per-value JSON bound on `actions`, `arrivalCheck`,
+ * `observations` and `provenance` (262_144 bytes each). */
+const CASE_VALUE_MAX_BYTES = 262_144;
+/** Mirrors the gateway's `array(..., maximum)` counts inside one case. */
+const CASE_MAX_ACTIONS = 10_000;
+const CASE_MAX_OBSERVATIONS = 1_000;
+const CASE_MAX_STATIC_REACH = 10_000;
+/** Mirrors the gateway's `text(row.label, 'case label', 16384)`. */
+const CASE_LABEL_MAX = 16_384;
+function referenceIdentity(value, what) {
+    if (typeof value !== 'string')
+        fail(`${what} (expected a string identifier)`);
+    if (value.length === 0)
+        fail(`${what} (an identifier may not be empty)`);
+    if (value.length > REFERENCE_IDENTITY_MAXIMUM) {
+        fail(`${what} is ${value.length} characters; the gateway accepts at most `
+            + `${REFERENCE_IDENTITY_MAXIMUM}: ${excerpt(value)}`);
+    }
+    for (let position = 0; position < value.length; position += 1) {
+        const character = value[position];
+        if (!REFERENCE_IDENTITY_CHARACTERS.includes(character)) {
+            fail(`${what} has ${JSON.stringify(character)} at position ${position}, outside the `
+                + `gateway identifier charset [A-Za-z0-9._:/-]: ${excerpt(value)}`);
+        }
+    }
+    return value;
+}
+function hex(value, length, what, prefix = '') {
+    if (typeof value !== 'string' || value.length !== prefix.length + length || !value.startsWith(prefix))
+        fail(what);
+    for (const character of value.slice(prefix.length)) {
+        if (!'0123456789abcdef'.includes(character))
+            fail(what);
+    }
+    return value;
+}
+export function integer(value, what, minimum, maximum) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < minimum || value > maximum) {
+        fail(`${what} (expected an integer from ${minimum} to ${maximum})`);
+    }
+    return value;
+}
+/** Bounded JSON, as the combination-search hook already bounds its inputs:
+ * finite numbers, no prototype-polluting keys, depth 64, 8 MiB serialized. */
+export function boundedCaseBatchJson(value, what, maximumBytes = CASE_BATCH_MAX_INPUT_BYTES) {
+    const visit = (item, depth) => {
+        if (depth > 64)
+            fail(`${what} (nested deeper than 64 levels)`);
+        if (item === null || typeof item === 'string' || typeof item === 'boolean')
+            return;
+        if (typeof item === 'number') {
+            if (!Number.isFinite(item))
+                fail(`${what} (non-finite number)`);
+            return;
+        }
+        if (Array.isArray(item)) {
+            for (const entry of item)
+                visit(entry, depth + 1);
+            return;
+        }
+        for (const [key, entry] of Object.entries(object(item, what))) {
+            if (['__proto__', 'constructor', 'prototype'].includes(key))
+                fail(`${what} (unsafe key)`);
+            visit(entry, depth + 1);
+        }
+    };
+    visit(value, 0);
+    const bytes = Buffer.byteLength(JSON.stringify(value) ?? '');
+    if (bytes > maximumBytes) {
+        throw new CaseBatchRequestSizeError(`${what} is ${bytes} bytes; the case-batch bound is ${maximumBytes} bytes.`);
+    }
+    return value;
+}
+function jsonObject(value, what, maximumBytes = CASE_BATCH_MAX_INPUT_BYTES) {
+    object(value, what);
+    return boundedCaseBatchJson(value, what, maximumBytes);
+}
+export function parseProductCase(value, index) {
+    const row = object(value, `case ${index}`);
+    keys(row, ['id', 'contentDigest', 'conditionId', 'start', 'actions', 'arrivalCheck',
+        'observations', 'variantOf', 'provenance', 'surfaceId', 'finalControlId', 'staticReach', 'label'], ['arrivalActionIndex', 'settingsDigest', 'startStateSnapshotIds', 'armCommits', 'publishScreenshots', 'repeatIndex']);
+    if (row.settingsDigest !== undefined && row.startStateSnapshotIds !== undefined)
+        fail(`case ${index} names its start state twice (settingsDigest and startStateSnapshotIds)`);
+    const id = text(row.id, `case ${index} id`, 160);
+    if (!CASE_BATCH_ID_PATTERN.test(id))
+        fail(`case ${index} id (queue identity charset is [A-Za-z0-9_-], 1-160)`);
+    const startRow = object(row.start, `case ${index} start`);
+    const axes = Object.keys(startRow);
+    if (axes.length > CASE_START_MAX_AXES) {
+        fail(`case ${index} start has ${axes.length} axes; the gateway accepts at most ${CASE_START_MAX_AXES}`);
+    }
+    const start = {};
+    for (const [position, axis] of axes.entries()) {
+        if (['__proto__', 'constructor', 'prototype'].includes(axis))
+            fail(`case ${index} start (unsafe key)`);
+        const startValue = startRow[axis];
+        if (typeof startValue !== 'string' || !CASE_START_VALUE_PATTERN.test(startValue))
+            fail(`case ${index} start value for axis ${position} (${excerpt(axis)}) is not a reference id `
+                + `or two joined by one '=': ${excerpt(String(startValue))}`);
+        start[referenceIdentity(axis, `case ${index} start axis ${position}`)] = startValue;
+    }
+    if (!Array.isArray(row.actions))
+        fail(`case ${index} actions`);
+    if (row.actions.length > CASE_MAX_ACTIONS) {
+        fail(`case ${index} actions has ${row.actions.length} entries; the gateway accepts at most ${CASE_MAX_ACTIONS}`);
+    }
+    if (!Array.isArray(row.observations))
+        fail(`case ${index} observations`);
+    if (row.observations.length > CASE_MAX_OBSERVATIONS) {
+        fail(`case ${index} observations has ${row.observations.length} entries; `
+            + `the gateway accepts at most ${CASE_MAX_OBSERVATIONS}`);
+    }
+    if (!Array.isArray(row.staticReach))
+        fail(`case ${index} staticReach`);
+    if (row.staticReach.length > CASE_MAX_STATIC_REACH) {
+        fail(`case ${index} staticReach has ${row.staticReach.length} entries; `
+            + `the gateway accepts at most ${CASE_MAX_STATIC_REACH}`);
+    }
+    const nullableIdentity = (candidate, what) => candidate === null ? null : referenceIdentity(candidate, what);
+    const staticReach = row.staticReach.map((reach, position) => referenceIdentity(reach, `case ${index} staticReach[${position}]`));
+    const seenReach = new Set();
+    for (const [position, reach] of staticReach.entries()) {
+        if (seenReach.has(reach)) {
+            fail(`case ${index} staticReach[${position}] repeats an earlier entry: ${excerpt(reach)}`);
+        }
+        seenReach.add(reach);
+    }
+    return {
+        id,
+        // `hashCanonical` is sha256Hex over canonical JSON (verifier/contracts/src/canonical.ts).
+        contentDigest: hex(row.contentDigest, 64, `case ${index} contentDigest`),
+        conditionId: referenceIdentity(row.conditionId, `case ${index} conditionId`),
+        start,
+        actions: row.actions.map((action, position) => {
+            const checked = jsonObject(action, `case ${index} action ${position}`, CASE_VALUE_MAX_BYTES);
+            if (typeof checked.kind !== 'string' || !CASE_BATCH_ACTION_KINDS.includes(checked.kind))
+                fail(`case ${index} action ${position} kind ${excerpt(String(checked.kind))} is not one the runtime executes`);
+            if (checked.coverage !== undefined && typeof checked.coverage !== 'boolean')
+                fail(`case ${index} action ${position} coverage must be a boolean`);
+            return checked;
+        }),
+        // Optional and additive: refused here when it does not name an action this
+        // case carries, rather than at execution where it costs two VMs to find.
+        ...(row.arrivalActionIndex === undefined ? {}
+            : { arrivalActionIndex: integer(row.arrivalActionIndex, `case ${index} arrivalActionIndex`, 0, row.actions.length - 1) }),
+        arrivalCheck: jsonObject(row.arrivalCheck, `case ${index} arrivalCheck`, CASE_VALUE_MAX_BYTES),
+        observations: row.observations.map((observation, position) => {
+            const checked = jsonObject(observation, `case ${index} observation ${position}`, CASE_VALUE_MAX_BYTES);
+            if (typeof checked.kind !== 'string' || !CASE_BATCH_OBSERVATION_KINDS.includes(checked.kind))
+                fail(`case ${index} observation ${position} kind ${excerpt(String(checked.kind))} is not one the runtime reads`);
+            return checked;
+        }),
+        ...(row.settingsDigest === undefined ? {} : { settingsDigest: hex(row.settingsDigest, 64, `case ${index} settingsDigest`) }),
+        ...(row.startStateSnapshotIds === undefined ? {} : { startStateSnapshotIds: (() => {
+                const ids = object(row.startStateSnapshotIds, `case ${index} startStateSnapshotIds`);
+                keys(ids, ['base1', 'head']);
+                return { base1: hex(ids.base1, 16, `case ${index} startStateSnapshotIds.base1`, 'frz_'),
+                    head: hex(ids.head, 16, `case ${index} startStateSnapshotIds.head`, 'frz_') };
+            })() }),
+        ...(row.armCommits === undefined ? {} : { armCommits: (() => {
+                const commits = object(row.armCommits, `case ${index} armCommits`);
+                keys(commits, ['base1', 'head']);
+                return { base1: hex(commits.base1, 40, `case ${index} armCommits.base1`),
+                    head: hex(commits.head, 40, `case ${index} armCommits.head`) };
+            })() }),
+        ...(row.publishScreenshots === undefined ? {} : { publishScreenshots: (() => {
+                if (typeof row.publishScreenshots !== 'boolean')
+                    fail(`case ${index} publishScreenshots must be a boolean`);
+                return row.publishScreenshots;
+            })() }),
+        ...(row.repeatIndex === undefined ? {}
+            : { repeatIndex: integer(row.repeatIndex, `case ${index} repeatIndex`, 1, CASE_BATCH_MAX_REPEAT_INDEX) }),
+        variantOf: nullableIdentity(row.variantOf, `case ${index} variantOf`),
+        provenance: jsonObject(row.provenance, `case ${index} provenance`, CASE_VALUE_MAX_BYTES),
+        surfaceId: nullableIdentity(row.surfaceId, `case ${index} surfaceId`),
+        finalControlId: nullableIdentity(row.finalControlId, `case ${index} finalControlId`),
+        staticReach,
+        label: text(row.label, `case ${index} label`, CASE_LABEL_MAX),
+    };
+}
+/** The submitter's ordered cases. Order is its scheduling decision and is
+ * preserved end to end, so the CLI never sorts or deduplicates silently:
+ * a repeated id or contentDigest is refused here, as the coordinator refuses
+ * it server-side. */
+export function parseProductCases(value) {
+    const rows = Array.isArray(value)
+        ? value
+        : (isJsonObject(value) && Array.isArray(value.cases) ? value.cases : null);
+    if (!rows)
+        fail('cases file (expected a JSON array of cases, or an object with a "cases" array)');
+    if (rows.length === 0)
+        fail('cases file (a batch needs at least one case)');
+    if (rows.length > CASE_BATCH_MAX_CASES) {
+        throw new CaseBatchRequestSizeError(`The cases file has ${rows.length} cases; one submission carries at most ${CASE_BATCH_MAX_CASES}.`);
+    }
+    // The gateway bounds the whole cases document before it reads a single case
+    // (`json(value)` at the top of `parseCaseBatchCases`): finite numbers, no
+    // prototype-polluting keys, depth 64, 8 MiB serialized.
+    boundedCaseBatchJson(rows, 'cases file');
+    const cases = rows.map((row, index) => parseProductCase(row, index));
+    const ids = new Set();
+    const digests = new Set();
+    for (const item of cases) {
+        if (ids.has(item.id))
+            fail(`cases file (case id ${item.id} appears twice)`);
+        ids.add(item.id);
+        if (digests.has(item.contentDigest)) {
+            fail(`cases file (contentDigest ${item.contentDigest} appears twice; two cases with the same digest are the same experiment)`);
+        }
+        digests.add(item.contentDigest);
+    }
+    return cases;
+}
+export function parseCaseBatchLimits(value) {
+    const perCaseWallMs = integer(value.perCaseWallMs, 'perCaseWallMs', CASE_BATCH_MIN_CASE_WALL_MS, CASE_BATCH_MAX_CASE_WALL_MS);
+    return {
+        maxConcurrentCases: integer(value.maxConcurrentCases, 'maxConcurrentCases', 1, CASE_BATCH_MAX_CONCURRENT_CASES),
+        perCaseWallMs,
+        totalBudgetMs: integer(value.totalBudgetMs, 'totalBudgetMs', CASE_BATCH_MIN_TOTAL_BUDGET_MS, CASE_BATCH_MAX_TOTAL_BUDGET_MS),
+        ...(value.warmSettleMs === undefined ? {} : { warmSettleMs: integer(value.warmSettleMs, 'warmSettleMs', 0, perCaseWallMs) }),
+    };
+}
+export function parseCaseBatchRepository(value) {
+    const parts = (value ?? '').split('/');
+    if (parts.length !== 2 || parts.some(part => !/^[A-Za-z0-9_.-]{1,100}$/.test(part) || part === '.' || part === '..')) {
+        fail(`repository "${value}" (use an exact GitHub owner/repository name)`);
+    }
+    return { owner: parts[0], name: parts[1], fullName: value };
+}
+export function parseCaseBatchCommit(value, flag) {
+    if (typeof value !== 'string')
+        fail(`${flag} (required, exact 40-character lowercase commit SHA)`);
+    return hex(value, 40, `${flag} commit`);
+}
+export function parseCaseBatchWorld(value, flag) {
+    return hex(value, 16, `${flag} frozen world id`, 'frz_');
+}
+export function parseCaseBatchIdempotencyKey(value) {
+    if (typeof value !== 'string' || value.length < 8 || value.length > 128
+        || !ALPHANUMERIC.includes(value[0] ?? '')
+        || [...value].some(character => !ALPHANUMERIC.includes(character) && !'._:-'.includes(character))) {
+        fail('idempotency key (8-128 characters of letters, numbers, ".", "_", ":" or "-", starting alphanumeric)');
+    }
+    return value;
+}
+/** The precompute-captured source record, checked locally with exactly the
+ * rules the gateway applies before custody: canonical base64, gzip magic,
+ * sha256 over the COMPRESSED bytes, and a cache key that names these commits. */
+export function parseCaseBatchSource(value, baseCommit, headCommit) {
+    const row = object(value, 'source patch file');
+    keys(row, ['cacheKey', 'patchSha256', 'patchGzBase64']);
+    const patchGzBase64 = text(row.patchGzBase64, 'source patch bytes', CASE_BATCH_MAX_INPUT_BYTES);
+    let patch;
+    try {
+        patch = Buffer.from(patchGzBase64, 'base64');
+        if (patch.toString('base64') !== patchGzBase64)
+            fail('source patch encoding');
+    }
+    catch {
+        fail('source patch encoding');
+    }
+    if (patch[0] !== 0x1f || patch[1] !== 0x8b)
+        fail('source patch (not gzip)');
+    const cacheKey = text(row.cacheKey, 'source cache key');
+    const parts = cacheKey.split('-');
+    if (parts.length !== 5 || parts[3] !== 'slim')
+        fail('source cache key');
+    hex(parts[0], 12, 'source cache base');
+    hex(parts[1], 12, 'source cache head');
+    hex(parts[2], 16, 'source cache identity');
+    hex(parts[4], 64, 'source cache digest');
+    if (!cacheKey.startsWith(`${baseCommit.slice(0, 12)}-${headCommit.slice(0, 12)}-`)) {
+        fail('source cache key (it does not name --base and --head)');
+    }
+    const patchSha256 = hex(row.patchSha256, 64, 'source patch digest');
+    // The declared digest is over the COMPRESSED bytes, and the gateway checks
+    // it before custody. Format-checking it here and sending it unverified would
+    // ship a record whose digest names bytes it does not describe, so compute it.
+    const computed = createHash('sha256').update(patch).digest('hex');
+    if (computed !== patchSha256) {
+        throw new CaseBatchRequestValidationError(`Invalid case batch source patch digest: the compressed bytes hash to ${computed}, but the record declares ${patchSha256}.`);
+    }
+    return { cacheKey, patchSha256, patchGzBase64 };
+}
+/** Assemble and bound the request exactly as it goes on the wire. */
+export function buildCaseBatchRequest(input) {
+    // v3, as the gateway checks it: every declared arm commit is the batch's base or head commit.
+    for (const [index, row] of input.cases.entries()) {
+        for (const arm of ['base1', 'head']) {
+            const commit = row.armCommits?.[arm];
+            if (commit !== undefined && commit !== input.baseCommit && commit !== input.headCommit)
+                fail(`case ${index} armCommits.${arm} ${commit} is neither --base nor --head`);
+        }
+    }
+    const request = {
+        repository: input.repository,
+        baseCommit: input.baseCommit,
+        headCommit: input.headCommit,
+        idempotencyKey: input.idempotencyKey,
+        ...(input.baseWorld ? { baseWorld: input.baseWorld } : {}),
+        ...(input.headWorld ? { headWorld: input.headWorld } : {}),
+        ...(input.driver ? { driver: input.driver } : {}),
+        combinationsRef: { inline: input.combinations },
+        casesRef: { inline: input.cases },
+        limits: input.limits,
+        ...(input.source ? { source: input.source } : {}),
+    };
+    boundedCaseBatchJson(request, 'request body');
+    return request;
+}
+/** MIRRORED BOUNDS — the gateway's serialisation bounds for everything a
+ * snapshot carries. A case record the API serves is exactly the record
+ * `caseRecord()` in
+ * `infra/lambda/haystack-design-verifier-shared/case_batch_validation.ts`
+ * accepted from a runner checkpoint (stored verbatim by
+ * `agent/cloudflare/src/case-batch-store.ts`), and the snapshot envelope is
+ * assembled by `caseBatchSnapshot()` in that store file. A read-side bound
+ * tighter than the gateway's turns a batch both sides accepted into a
+ * snapshot every poll refuses, so each bound here equals the gateway's.
+ *
+ * Shared helper defaults (`combination_search_validation.ts`): `text()`
+ * defaults to 2000 characters and `date()` to 30. */
+/** `text(row.label, 'case label', 16384)` in `caseRecord()`; also the
+ * submit-side `CASE_LABEL_MAX`. */
+const RECORD_LABEL_MAX = CASE_LABEL_MAX;
+/** `referenceIdentity(row.conditionId, ...)`: `token(..., 1, 256, ...)`. */
+const RECORD_CONDITION_ID_MAX = REFERENCE_IDENTITY_MAXIMUM;
+/** `text(row.detail, 'outcome detail', 16384)` in `outcome()`. */
+const RECORD_DETAIL_MAX = 16_384;
+/** `bundlePath()`: `MAX_BUNDLE_PATH = 320`, for `comparisonPath` and
+ * `caseBundlePath`. */
+const RECORD_BUNDLE_PATH_MAX = 320;
+/** `vmId()`: `hex(value, [16, 32], field, 'sbx_')`, so at most 4 + 32. */
+const RECORD_VM_ID_MAX = 36;
+/** `leaseId()`: `token(..., 1, 128, ...)` plus `CASE_BATCH_LEASE_ID_PATTERN`. */
+const RECORD_LEASE_ID_MAX = 128;
+/** `text(entry, 'differing outcome id', 256)` in `outcome()`. */
+const RECORD_DIFFERING_OUTCOME_MAX = 256;
+/** `array(..., 10000)` for a record's and an outcome's `vmIds`, `leaseIds`
+ * and `differingOutcomes`. */
+const RECORD_ARRAY_MAX = 10_000;
+/** The gateway accepts only its fixed `unknownReasons` set (longest 22
+ * characters) and has no length bound of its own. The CLI deliberately reads
+ * an unrecognised reason as UNKNOWN (additive by ruling), so it bounds the
+ * string at 128 rather than refusing a reason added later. Looser, never
+ * tighter, than the gateway. */
+const RECORD_UNKNOWN_REASON_MAX = 128;
+/** v4: `CASE_FAILURE_FIELD_MAX` in `outcome()`: every node id, failure class and subcode is bounded
+ * by length only. */
+const RECORD_FAILURE_FIELD_MAX = 256;
+/** `validSearchRunId`: `cv_` plus 48 hex characters. */
+const SNAPSHOT_RUN_ID_MAX = 51;
+/** `hex(worlds.base, [16], 'base world', 'frz_')`: 4 + 16. */
+const SNAPSHOT_WORLD_MAX = 20;
+/** `date()` in the shared helpers: `text(value, field, 30)`. Also bounds
+ * `observedAt`, which is the row's `updated_at` ISO stamp. */
+const SNAPSHOT_STAMP_MAX = 30;
+/** `text(row.error, 'error')`: the shared `text()` default of 2000. */
+const SNAPSHOT_ERROR_MAX = 2_000;
+/** `nextCaseCursor` is a stored `case_id`: `CASE_BATCH_ID_PATTERN`, 1-160. */
+const SNAPSHOT_CASE_CURSOR_MAX = 160;
+function responseText(value, what, maximum = 4_096) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > maximum)
+        bad(what);
+    return value;
+}
+function responseInteger(value, what, minimum, maximum) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < minimum || value > maximum)
+        bad(what);
+    return value;
+}
+function responseNullableString(value, what, maximum = 4_096) {
+    return value === null ? null : responseText(value, what, maximum);
+}
+function responseStringArray(value, what, maximum) {
+    if (!Array.isArray(value) || value.length > RECORD_ARRAY_MAX)
+        bad(what);
+    return value.map(item => responseText(item, what, maximum));
+}
+function armPhases(value, what) {
+    const row = isJsonObject(value) ? value : bad(what);
+    const counter = (field) => responseInteger(row[field], `${what}.${field}`, 0, Number.MAX_SAFE_INTEGER);
+    return {
+        createMs: counter('createMs'),
+        readyMs: counter('readyMs'),
+        actionsMs: counter('actionsMs'),
+        collectMs: counter('collectMs'),
+        killMs: counter('killMs'),
+        bindingWaitMs: counter('bindingWaitMs'),
+    };
+}
+function caseArmNodeIds(value) {
+    const row = isJsonObject(value) ? value : bad('case outcome nodeIds');
+    return { base1: responseNullableString(row.base1, 'case outcome nodeIds.base1', RECORD_FAILURE_FIELD_MAX),
+        head: responseNullableString(row.head, 'case outcome nodeIds.head', RECORD_FAILURE_FIELD_MAX) };
+}
+function caseFailureFact(value) {
+    const row = isJsonObject(value) ? value : bad('case outcome failure');
+    if (row.arm !== null && row.arm !== 'base1' && row.arm !== 'head')
+        bad('case outcome failure.arm');
+    return {
+        source: responseText(row.source, 'case outcome failure.source', RECORD_FAILURE_FIELD_MAX),
+        arm: row.arm,
+        errorClass: responseText(row.errorClass, 'case outcome failure.errorClass', RECORD_FAILURE_FIELD_MAX),
+        errorCode: responseNullableString(row.errorCode, 'case outcome failure.errorCode', RECORD_FAILURE_FIELD_MAX),
+        nodeId: responseNullableString(row.nodeId, 'case outcome failure.nodeId', RECORD_FAILURE_FIELD_MAX),
+    };
+}
+function caseOutcome(value, caseId) {
+    const row = isJsonObject(value) ? value : bad('case outcome');
+    if (row.caseId !== caseId)
+        bad('case outcome (it names a different case)');
+    const status = row.status;
+    if (status !== 'AGREE' && status !== 'DIFFER' && status !== 'UNKNOWN')
+        bad('case outcome status');
+    // Additive by ruling: an unrecognised reason still reads as UNKNOWN.
+    const unknownReason = responseNullableString(row.unknownReason, 'case outcome unknownReason', RECORD_UNKNOWN_REASON_MAX);
+    if ((status === 'UNKNOWN') !== (unknownReason !== null)) {
+        bad('case outcome (only an UNKNOWN outcome carries a reason)');
+    }
+    const phases = isJsonObject(row.phases) ? row.phases : bad('case outcome phases');
+    if (typeof row.cleanupProven !== 'boolean')
+        bad('case outcome cleanupProven');
+    return {
+        caseId,
+        status,
+        unknownReason,
+        comparisonPath: responseNullableString(row.comparisonPath, 'case outcome comparisonPath', RECORD_BUNDLE_PATH_MAX),
+        caseBundlePath: responseText(row.caseBundlePath, 'case outcome caseBundlePath', RECORD_BUNDLE_PATH_MAX),
+        arrivalEvidence: row.arrivalEvidence === null
+            ? null
+            : (isJsonObject(row.arrivalEvidence) ? row.arrivalEvidence : bad('case outcome arrivalEvidence')),
+        wallMs: responseInteger(row.wallMs, 'case outcome wallMs', 0, Number.MAX_SAFE_INTEGER),
+        phases: { base1: armPhases(phases.base1, 'phases.base1'), head: armPhases(phases.head, 'phases.head') },
+        vmIds: responseStringArray(row.vmIds, 'case outcome vmIds', RECORD_VM_ID_MAX),
+        leaseIds: responseStringArray(row.leaseIds, 'case outcome leaseIds', RECORD_LEASE_ID_MAX),
+        cleanupProven: row.cleanupProven,
+        differingOutcomes: responseStringArray(row.differingOutcomes, 'case outcome differingOutcomes', RECORD_DIFFERING_OUTCOME_MAX),
+        detail: responseNullableString(row.detail, 'case outcome detail', RECORD_DETAIL_MAX),
+        ...(typeof row.executionPath === 'string' && CASE_EXECUTION_PATHS.includes(row.executionPath)
+            ? { executionPath: row.executionPath } : {}),
+        ...(row.nodeIds === undefined ? {} : { nodeIds: caseArmNodeIds(row.nodeIds) }),
+        ...(row.failure === undefined ? {} : { failure: row.failure === null ? null : caseFailureFact(row.failure) }),
+    };
+}
+export function parseCaseBatchCaseRecord(value) {
+    const row = isJsonObject(value) ? value : bad('case row');
+    // `identity()` in `caseRecord()`: CASE_BATCH_ID_PATTERN, 1-160.
+    const id = responseText(row.id, 'case row id', 160);
+    if (!CASE_BATCH_ID_PATTERN.test(id))
+        bad('case row id');
+    const status = row.status;
+    if (status !== 'running' && status !== 'completed' && status !== 'incomplete')
+        bad('case row status');
+    const finishedAtMs = row.finishedAtMs === null
+        ? null
+        : responseInteger(row.finishedAtMs, 'case row finishedAtMs', 0, Number.MAX_SAFE_INTEGER);
+    if ((status === 'running') !== (finishedAtMs === null))
+        bad('case row (status disagrees with finishedAtMs)');
+    return {
+        id,
+        label: responseText(row.label, 'case row label', RECORD_LABEL_MAX),
+        conditionId: responseText(row.conditionId, 'case row conditionId', RECORD_CONDITION_ID_MAX),
+        position: responseInteger(row.position, 'case row position', 0, CASE_BATCH_MAX_CASES - 1),
+        launchedAtMs: responseInteger(row.launchedAtMs, 'case row launchedAtMs', 0, Number.MAX_SAFE_INTEGER),
+        finishedAtMs,
+        status,
+        outcome: row.outcome === null || row.outcome === undefined ? null : caseOutcome(row.outcome, id),
+        vmIds: responseStringArray(row.vmIds, 'case row vmIds', RECORD_VM_ID_MAX),
+        leaseIds: responseStringArray(row.leaseIds, 'case row leaseIds', RECORD_LEASE_ID_MAX),
+    };
+}
+function totals(value) {
+    const row = isJsonObject(value) ? value : bad('totals');
+    const counter = (field) => responseInteger(row[field], `totals.${field}`, 0, Number.MAX_SAFE_INTEGER);
+    return {
+        cases: counter('cases'),
+        launched: counter('launched'),
+        settled: counter('settled'),
+        agree: counter('agree'),
+        differ: counter('differ'),
+        unknown: counter('unknown'),
+        cleanupProven: counter('cleanupProven'),
+        cleanupUnproven: counter('cleanupUnproven'),
+        leasesReleased: counter('leasesReleased'),
+    };
+}
+function clocks(value) {
+    const row = isJsonObject(value) ? value : bad('clocks');
+    const stamp = (field) => {
+        const candidate = row[field];
+        if (candidate === null)
+            return null;
+        const stampText = responseText(candidate, `clocks.${field}`, SNAPSHOT_STAMP_MAX);
+        if (!Number.isFinite(Date.parse(stampText)))
+            bad(`clocks.${field}`);
+        return stampText;
+    };
+    const span = (field) => responseInteger(row[field], `clocks.${field}`, 0, Number.MAX_SAFE_INTEGER);
+    return {
+        preparationStartedAt: stamp('preparationStartedAt'),
+        searchStartedAt: stamp('searchStartedAt'),
+        launchesClosedAt: stamp('launchesClosedAt'),
+        finishedAt: stamp('finishedAt'),
+        searchBudgetMs: span('searchBudgetMs'),
+        searchWallMs: span('searchWallMs'),
+        drainWallMs: span('drainWallMs'),
+    };
+}
+function admission(value) {
+    const row = isJsonObject(value) ? value : bad('admission');
+    if (row.pool !== 'small' && row.pool !== 'big')
+        bad('admission pool');
+    const counter = (field) => responseInteger(row[field], `admission.${field}`, 0, Number.MAX_SAFE_INTEGER);
+    return {
+        requestedCases: counter('requestedCases'),
+        admittedCases: counter('admittedCases'),
+        pool: row.pool,
+        freeVmSlots: counter('freeVmSlots'),
+        reservedVmSlots: counter('reservedVmSlots'),
+        workerProcesses: counter('workerProcesses'),
+        casesPerProcess: counter('casesPerProcess'),
+    };
+}
+export function parseCaseBatchSnapshot(value, expectedRunId) {
+    const row = isJsonObject(value) ? value : bad('run snapshot');
+    const runId = responseText(row.runId, 'runId', SNAPSHOT_RUN_ID_MAX);
+    if (runId !== expectedRunId)
+        bad(`run snapshot (it answers for ${runId}, not ${expectedRunId})`);
+    const status = row.status;
+    if (typeof status !== 'string' || !CASE_BATCH_STATUSES.includes(status))
+        bad('status');
+    const worlds = isJsonObject(row.worlds) ? row.worlds : bad('worlds');
+    const world = (field) => worlds[field] === null ? null : responseText(worlds[field], `worlds.${field}`, SNAPSHOT_WORLD_MAX);
+    if (!Array.isArray(row.cases))
+        bad('cases page');
+    if (!Array.isArray(row.waves))
+        bad('waves page');
+    if (typeof row.cleanupComplete !== 'boolean')
+        bad('cleanupComplete');
+    const observedAt = responseText(row.observedAt, 'observedAt', SNAPSHOT_STAMP_MAX);
+    if (!Number.isFinite(Date.parse(observedAt)))
+        bad('observedAt');
+    return {
+        runId,
+        status: status,
+        generation: responseInteger(row.generation, 'generation', 0, Number.MAX_SAFE_INTEGER),
+        observedAt,
+        clocks: clocks(row.clocks),
+        totals: totals(row.totals),
+        worlds: { base: world('base'), head: world('head') },
+        ...(row.admission === undefined || row.admission === null ? {} : { admission: admission(row.admission) }),
+        ...(row.error === undefined || row.error === null ? {} : { error: responseText(row.error, 'error', SNAPSHOT_ERROR_MAX) }),
+        cases: row.cases.map(parseCaseBatchCaseRecord),
+        waves: row.waves.map(wave => {
+            const record = isJsonObject(wave) ? wave : bad('wave row');
+            return {
+                wave: responseInteger(record.wave, 'wave.wave', 0, Number.MAX_SAFE_INTEGER),
+                atMs: responseInteger(record.atMs, 'wave.atMs', 0, Number.MAX_SAFE_INTEGER),
+                launched: responseInteger(record.launched, 'wave.launched', 0, CASE_BATCH_MAX_CASES),
+            };
+        }),
+        vmIds: responseInteger(row.vmIds, 'vmIds', 0, Number.MAX_SAFE_INTEGER),
+        cleanupComplete: row.cleanupComplete,
+        nextCaseCursor: row.nextCaseCursor === undefined || row.nextCaseCursor === null
+            ? null
+            : responseText(row.nextCaseCursor, 'nextCaseCursor', SNAPSHOT_CASE_CURSOR_MAX),
+        nextWaveCursor: row.nextWaveCursor === undefined || row.nextWaveCursor === null
+            ? null
+            : responseInteger(row.nextWaveCursor, 'nextWaveCursor', 0, Number.MAX_SAFE_INTEGER),
+    };
+}