@hraness/direct 0.7.6 → 0.7.7

package/src/tooling/bombadil-runner.ts

@@ -3,6 +3,7 @@ import { readFile, realpath, stat, writeFile } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import process from "node:process";
 import { createInterface } from "node:readline";
+import { createHash } from "node:crypto";
 
 import {
   parseDirectProbeSnapshot,
@@ -44,6 +45,12 @@ const TRACE_MAX_BYTES = 64 * 1024 * 1024;
 const TRACE_MAX_LINE_BYTES = 16 * 1024 * 1024;
 const TRACE_MAX_LINES = 10_000;
 const TRACE_MAX_SNAPSHOTS_PER_LINE = 4_096;
+const TRACE_MAX_NAMED_SNAPSHOT_NAMES = 128;
+const TRACE_MAX_DISTINCT_SNAPSHOT_VALUES_PER_NAME = 1_024;
+const TRACE_MAX_DISTINCT_URLS = 1_024;
+const TRACE_MAX_PROPERTY_NAMES = 128;
+const TRACE_MAX_CANONICAL_SNAPSHOT_BYTES = 2 * 1024 * 1024;
+const TRACE_MAX_JSON_DEPTH = 64;
 const RANDOM_RUN_OVERHEAD_MS = 30_000;
 const REPLAY_WALL_CLOCK_TIMEOUT_MS = MAX_TIME_LIMIT_SECONDS * 1_000 + RANDOM_RUN_OVERHEAD_MS;
 const PROCESS_TERMINATION_GRACE_MS = 5_000;
@@ -52,6 +59,94 @@ const SERVER_OUTPUT_TIMEOUT_MS = 3_000;
 const DIRECT_BROWSER_BRIDGE_SCHEMA = "direct.browser-bridge/v2";
 const TRACE_LINE_KEYS = new Set(["action", "snapshots", "state", "timestamp", "violations"]);
 const TRACE_SNAPSHOT_KEYS = new Set(["index", "name", "time", "value"]);
+const TRACE_STATE_KEYS = new Set([
+  "hash_current",
+  "hash_previous",
+  "resources",
+  "screenshot",
+  "url",
+]);
+const TRACE_RESOURCE_KEYS = new Set([
+  "documents",
+  "dom_nodes",
+  "js_event_listeners",
+  "js_heap_total",
+  "js_heap_used",
+  "layout_objects",
+  "script_duration",
+  "task_duration",
+  "thread_time",
+  "timestamp",
+]);
+const TRACE_VIOLATION_KEYS = new Set(["name", "violation"]);
+const TRACE_POINT_KEYS = new Set(["x", "y"]);
+const TRACE_FINGERPRINT_KEYS = new Set([
+  "accessible_name",
+  "href",
+  "id",
+  "input_type",
+  "name_attr",
+  "placeholder",
+  "role",
+  "structural_path",
+  "tag",
+  "test_id",
+  "text_content",
+]);
+const TRACE_CLICK_ACTION_KEYS = new Set(["fingerprint", "point"]);
+const TRACE_DOUBLE_CLICK_ACTION_KEYS = new Set([
+  "delay_millis",
+  "fingerprint",
+  "point",
+]);
+const TRACE_TYPE_TEXT_ACTION_KEYS = new Set(["delay_millis", "text"]);
+const TRACE_PRESS_KEY_ACTION_KEYS = new Set(["code"]);
+const TRACE_SCROLL_ACTION_KEYS = new Set(["distance", "origin"]);
+const TRACE_FILE_INPUT_ACTION_KEYS = new Set(["files", "selector"]);
+const TRACE_MOUSE_DRAG_ACTION_KEYS = new Set([
+  "delay_millis",
+  "from",
+  "steps",
+  "to",
+]);
+const TRACE_VIEWPORT_ACTION_KEYS = new Set(["height", "width"]);
+const VIEWPORT_KEYS = new Set(["deviceScaleFactor", "height", "width"]);
+const EXPLORATION_POLICY_KEYS = new Set([
+  "minDistinctNamedSnapshotValues",
+  "minNamedSnapshotChangesAfterActionKind",
+  "minNamedSnapshotChangesAfterNonWait",
+  "minNonWaitActions",
+  "requireStableTargetUrl",
+  "requiredActionKinds",
+  "requiredNamedSnapshots",
+]);
+const DEFAULT_VIEWPORT_WIDTH = 1_024;
+const DEFAULT_VIEWPORT_HEIGHT = 768;
+const DEFAULT_DEVICE_SCALE_FACTOR = 2;
+const SNAPSHOT_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_.:/-]*$/u;
+const TARGET_TAG_PATTERN = /^[a-z][a-z0-9-]*$/u;
+const ACTION_KINDS = [
+  "Back",
+  "Click",
+  "DoubleClick",
+  "Forward",
+  "MouseDrag",
+  "PressKey",
+  "Reload",
+  "ScrollDown",
+  "ScrollUp",
+  "SetFileInputFiles",
+  "SetViewport",
+  "TypeText",
+  "Wait",
+] as const;
+const ACTION_KIND_SET = new Set<string>(ACTION_KINDS);
+const UNIT_ACTION_KINDS = new Set<DirectBombadilActionKind>([
+  "Back",
+  "Forward",
+  "Reload",
+  "Wait",
+]);
 const DIRECT_OBSERVATION_KEYS = new Set([
   "activationHash",
   "activeRoute",
@@ -76,6 +171,88 @@ export interface DirectBombadilServerConfig {
   readonly startupTimeoutMs?: number;
 }
 
+export type DirectBombadilActionKind = (typeof ACTION_KINDS)[number];
+
+export interface DirectBombadilViewportConfig {
+  readonly deviceScaleFactor?: number;
+  readonly height?: number;
+  readonly width?: number;
+}
+
+export interface DirectBombadilExplorationPolicy {
+  readonly minDistinctNamedSnapshotValues?: Readonly<Record<string, number>>;
+  readonly minNamedSnapshotChangesAfterActionKind?: Readonly<Record<
+    string,
+    Readonly<Partial<Record<DirectBombadilActionKind, number>>>
+  >>;
+  readonly minNamedSnapshotChangesAfterNonWait?: Readonly<Record<string, number>>;
+  readonly minNonWaitActions?: number;
+  readonly requireStableTargetUrl?: boolean;
+  readonly requiredActionKinds?: readonly DirectBombadilActionKind[];
+  readonly requiredNamedSnapshots?: readonly string[];
+}
+
+export interface DirectBombadilExplorationSummary {
+  readonly schema: "direct.bombadil-exploration-summary/v2";
+  readonly trace: {
+    readonly bytes: number;
+    readonly lineCount: number;
+    readonly sha256: string;
+  };
+  readonly actions: {
+    readonly byKind: Readonly<Partial<Record<DirectBombadilActionKind, number>>>;
+    readonly maxWaitStreak: number;
+    readonly nonWaitCount: number;
+    readonly targetTags: Readonly<Record<string, number>>;
+    readonly total: number;
+  };
+  readonly urls: {
+    readonly distinctFingerprintCount: number;
+    readonly fingerprintSha256: readonly string[];
+    readonly observationCount: number;
+    readonly rawDistinctFingerprintCount: number;
+    readonly rawFingerprintSha256: readonly string[];
+    readonly rawObservationCount: number;
+    readonly stableTarget: boolean;
+  };
+  readonly transitions: {
+    readonly distinctNonNullHashCount: number;
+    readonly nonNullHashCount: number;
+    readonly rawDistinctNonNullHashCount: number;
+    readonly rawNonNullHashCount: number;
+  };
+  readonly namedSnapshots: readonly {
+    readonly changeAfterActionKind: Readonly<
+      Partial<Record<DirectBombadilActionKind, number>>
+    >;
+    readonly changeAfterNonWaitCount: number;
+    readonly distinctValueCount: number;
+    readonly distinctValueSha256: readonly string[];
+    readonly name: string;
+    readonly observationCount: number;
+  }[];
+  readonly propertyViolations: {
+    readonly byName: Readonly<Record<string, number>>;
+    readonly total: number;
+  };
+  readonly resourceHighWaterMarks: {
+    readonly documents: number;
+    readonly domNodes: number;
+    readonly jsEventListeners: number;
+    readonly jsHeapTotalBytes: number;
+    readonly jsHeapUsedBytes: number;
+    readonly layoutObjects: number;
+    readonly scriptDurationSeconds: number;
+    readonly taskDurationSeconds: number;
+    readonly threadTimeSeconds: number;
+  };
+  readonly policy: {
+    readonly configured: boolean;
+    readonly failures: readonly string[];
+    readonly satisfied: boolean;
+  };
+}
+
 export interface DirectBombadilFuzzConfig {
   readonly artifactName: string;
   readonly baseUrl: string;
@@ -86,6 +263,8 @@ export interface DirectBombadilFuzzConfig {
   readonly scenario: string;
   readonly specificationPath: string;
   readonly targetQuery?: Readonly<Record<string, string>>;
+  readonly explorationPolicy?: DirectBombadilExplorationPolicy;
+  readonly viewport?: DirectBombadilViewportConfig;
   readonly server: DirectBombadilServerConfig;
 }
 
@@ -107,6 +286,21 @@ export type DirectBombadilFuzzResult =
       readonly status: "passed";
     };
 
+export interface DirectBombadilFuzzCampaign {
+  readonly config: DirectBombadilFuzzConfig;
+  readonly id: string;
+}
+
+export type DirectBombadilFuzzMatrixResult =
+  | { readonly kind: "help" }
+  | {
+      readonly kind: "matrix";
+      readonly results: readonly {
+        readonly campaignId: string;
+        readonly result: Extract<DirectBombadilFuzzResult, { readonly kind: "run" }>;
+      }[];
+    };
+
 export interface DirectBombadilInvocation {
   readonly abortSignal?: AbortSignal;
   readonly command: readonly string[];
@@ -160,6 +354,7 @@ export interface DirectBombadilTraceAttestation {
 
 export interface DirectBombadilRunnerDependencies {
   readonly acquireServer: typeof acquireVerificationServer;
+  readonly createAbortController?: () => AbortController;
   readonly now: () => Date;
   readonly runBombadil: (
     invocation: DirectBombadilInvocation,
@@ -184,17 +379,41 @@ interface ProcessSignalEmitter {
   ) => unknown;
 }
 
-interface ValidatedConfig extends DirectBombadilFuzzConfig {
+type ValidatedConfig = Omit<
+  DirectBombadilFuzzConfig,
+  "explorationPolicy" | "server" | "viewport"
+> & {
   readonly artifactRoot: string;
   readonly baseUrl: string;
   readonly bombadilExecutable: string;
   readonly entryPath: `/${string}`;
+  readonly explorationPolicy: ValidatedExplorationPolicy | null;
   readonly port: string;
   readonly targetQuery: Readonly<Record<string, string>>;
+  readonly viewport: ValidatedViewport;
   readonly server: DirectBombadilServerConfig & {
     readonly readinessPath: `/${string}`;
     readonly startupTimeoutMs: number;
   };
+};
+
+interface ValidatedViewport {
+  readonly deviceScaleFactor: number;
+  readonly height: number;
+  readonly width: number;
+}
+
+interface ValidatedExplorationPolicy {
+  readonly minDistinctNamedSnapshotValues: Readonly<Record<string, number>>;
+  readonly minNamedSnapshotChangesAfterActionKind: Readonly<Record<
+    string,
+    Readonly<Partial<Record<DirectBombadilActionKind, number>>>
+  >>;
+  readonly minNamedSnapshotChangesAfterNonWait: Readonly<Record<string, number>>;
+  readonly minNonWaitActions: number;
+  readonly requireStableTargetUrl: boolean;
+  readonly requiredActionKinds: readonly DirectBombadilActionKind[];
+  readonly requiredNamedSnapshots: readonly string[];
 }
 
 function readOptionValue(
@@ -283,6 +502,12 @@ function hasExactKeys(
   return keys.length === expected.size && keys.every((key) => expected.has(key));
 }
 
+function compareCodeUnits(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
 function parseTraceDirectObservation(value: unknown): TraceDirectObservation {
   if (!isRecord(value) || !hasExactKeys(value, DIRECT_OBSERVATION_KEYS)) {
     throw new Error("Bombadil trace has an invalid named direct observation");
@@ -427,7 +652,325 @@ function exactTraceDirectObservation(
   };
 }
 
-function parseTraceLine(line: string, lineNumber: number): TraceDirectObservation {
+interface ParsedTraceAction {
+  readonly kind: DirectBombadilActionKind;
+  readonly targetTag: string | null;
+}
+
+interface ParsedTraceState {
+  readonly currentHash: number | null;
+  readonly resources: Readonly<Record<keyof typeof RESOURCE_FIELD_MAP, number>>;
+  readonly url: URL;
+}
+
+interface ParsedTraceLine {
+  readonly action: ParsedTraceAction | null;
+  readonly directObservation: TraceDirectObservation;
+  readonly namedSnapshots: readonly {
+    readonly name: string;
+    readonly valueSha256: string;
+  }[];
+  readonly propertyViolationNames: readonly string[];
+  readonly state: ParsedTraceState;
+}
+
+interface ParsedTraceEnvelope {
+  readonly action: unknown;
+  readonly snapshots: readonly unknown[];
+  readonly state: unknown;
+  readonly timestamp: number;
+  readonly violations: readonly unknown[];
+}
+
+interface ParsedDirectTraceObservation {
+  readonly observation: TraceDirectObservation;
+  readonly value: unknown;
+}
+
+const RESOURCE_FIELD_MAP = {
+  documents: "documents",
+  dom_nodes: "domNodes",
+  js_event_listeners: "jsEventListeners",
+  js_heap_total: "jsHeapTotalBytes",
+  js_heap_used: "jsHeapUsedBytes",
+  layout_objects: "layoutObjects",
+  script_duration: "scriptDurationSeconds",
+  task_duration: "taskDurationSeconds",
+  thread_time: "threadTimeSeconds",
+} as const;
+
+function canonicalJson(
+  value: unknown,
+  depth = 0,
+  maximumDepth = TRACE_MAX_JSON_DEPTH,
+): string {
+  if (depth > maximumDepth) {
+    throw new Error(`Bombadil named snapshot exceeds JSON depth ${String(maximumDepth)}`);
+  }
+  if (value === null || typeof value === "boolean" || typeof value === "string") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error("Bombadil named snapshot has a non-finite number");
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => canonicalJson(entry, depth + 1, maximumDepth)).join(",")}]`;
+  }
+  if (!isRecord(value)) throw new Error("Bombadil named snapshot is not JSON");
+  const entries = Object.keys(value).sort(compareCodeUnits).map((key) =>
+    `${JSON.stringify(key)}:${canonicalJson(value[key], depth + 1, maximumDepth)}`
+  );
+  return `{${entries.join(",")}}`;
+}
+
+function sha256(value: string | Uint8Array): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function namedSnapshotValueSha256(
+  value: unknown,
+  options: {
+    readonly maximumBytes?: number;
+    readonly maximumDepth?: number;
+  } = {},
+): string {
+  const maximumBytes = options.maximumBytes ?? TRACE_MAX_CANONICAL_SNAPSHOT_BYTES;
+  const canonical = canonicalJson(
+    value,
+    0,
+    options.maximumDepth ?? TRACE_MAX_JSON_DEPTH,
+  );
+  if (Buffer.byteLength(canonical, "utf8") > maximumBytes) {
+    throw new Error(
+      `Bombadil named snapshot exceeds ${String(maximumBytes)} canonical bytes`,
+    );
+  }
+  return sha256(canonical);
+}
+
+function validTracePoint(value: unknown): boolean {
+  return isRecord(value)
+    && hasExactKeys(value, TRACE_POINT_KEYS)
+    && typeof value.x === "number"
+    && Number.isFinite(value.x)
+    && typeof value.y === "number"
+    && Number.isFinite(value.y);
+}
+
+function parseTraceFingerprintTag(value: unknown, lineNumber: number): string {
+  if (
+    !isRecord(value)
+    || !Object.keys(value).every((key) => TRACE_FINGERPRINT_KEYS.has(key))
+  ) {
+    throw new Error(
+      `Bombadil trace line ${String(lineNumber)} has an invalid action target`,
+    );
+  }
+  for (const [key, candidate] of Object.entries(value)) {
+    if (key !== "tag" && typeof candidate !== "string") {
+      throw new Error(
+        `Bombadil trace line ${String(lineNumber)} has an invalid action target`,
+      );
+    }
+  }
+  const tag = value.tag;
+  if (
+    typeof tag !== "string"
+    || tag.length === 0
+  ) {
+    throw new Error(
+      `Bombadil trace line ${String(lineNumber)} has an invalid action target tag`,
+    );
+  }
+  if (
+    typeof value.structural_path === "string"
+    && Object.keys(value).some((key) => (
+      key !== "tag" && key !== "structural_path"
+    ))
+  ) {
+    throw new Error(
+      `Bombadil trace line ${String(lineNumber)} has an invalid action target`,
+    );
+  }
+  return tag.length <= 64 && TARGET_TAG_PATTERN.test(tag)
+    ? tag
+    : `sha256:${sha256(tag)}`;
+}
+
+function isSafeIntegerBetween(
+  value: unknown,
+  minimum: number,
+  maximum: number,
+): value is number {
+  return typeof value === "number"
+    && Number.isSafeInteger(value)
+    && value >= minimum
+    && value <= maximum;
+}
+
+function invalidTraceAction(lineNumber: number): never {
+  throw new Error(
+    `Bombadil trace line ${String(lineNumber)} has an invalid action`,
+  );
+}
+
+function parseTraceAction(value: unknown, lineNumber: number): ParsedTraceAction | null {
+  if (value === null) return null;
+  if (typeof value === "string") {
+    if (!ACTION_KIND_SET.has(value) || !UNIT_ACTION_KINDS.has(value as DirectBombadilActionKind)) {
+      return invalidTraceAction(lineNumber);
+    }
+    return { kind: value as DirectBombadilActionKind, targetTag: null };
+  }
+  if (!isRecord(value) || Object.keys(value).length !== 1) {
+    return invalidTraceAction(lineNumber);
+  }
+  const kind = Object.keys(value)[0];
+  const payload = kind === undefined ? undefined : value[kind];
+  if (
+    kind === undefined
+    || !ACTION_KIND_SET.has(kind)
+    || UNIT_ACTION_KINDS.has(kind as DirectBombadilActionKind)
+    || !isRecord(payload)
+  ) {
+    return invalidTraceAction(lineNumber);
+  }
+  const actionKind = kind as DirectBombadilActionKind;
+  let targetTag: string | null = null;
+  switch (actionKind) {
+    case "Click":
+      if (
+        !hasExactKeys(payload, TRACE_CLICK_ACTION_KEYS)
+        || !validTracePoint(payload.point)
+      ) {
+        return invalidTraceAction(lineNumber);
+      }
+      targetTag = parseTraceFingerprintTag(payload.fingerprint, lineNumber);
+      break;
+    case "DoubleClick":
+      if (
+        !hasExactKeys(payload, TRACE_DOUBLE_CLICK_ACTION_KEYS)
+        || !isSafeIntegerBetween(payload.delay_millis, 0, 1_000)
+        || !validTracePoint(payload.point)
+      ) return invalidTraceAction(lineNumber);
+      targetTag = parseTraceFingerprintTag(payload.fingerprint, lineNumber);
+      break;
+    case "TypeText":
+      if (
+        !hasExactKeys(payload, TRACE_TYPE_TEXT_ACTION_KEYS)
+        || !isSafeIntegerBetween(payload.delay_millis, 0, Number.MAX_SAFE_INTEGER)
+        || typeof payload.text !== "string"
+      ) return invalidTraceAction(lineNumber);
+      break;
+    case "PressKey":
+      if (
+        !hasExactKeys(payload, TRACE_PRESS_KEY_ACTION_KEYS)
+        || !isSafeIntegerBetween(payload.code, 0, 255)
+      ) {
+        return invalidTraceAction(lineNumber);
+      }
+      break;
+    case "ScrollDown":
+    case "ScrollUp":
+      if (
+        !hasExactKeys(payload, TRACE_SCROLL_ACTION_KEYS)
+        || typeof payload.distance !== "number"
+        || !Number.isFinite(payload.distance)
+        || !validTracePoint(payload.origin)
+      ) return invalidTraceAction(lineNumber);
+      break;
+    case "SetFileInputFiles":
+      if (
+        !hasExactKeys(payload, TRACE_FILE_INPUT_ACTION_KEYS)
+        || typeof payload.selector !== "string"
+        || !Array.isArray(payload.files)
+        || !payload.files.every((file) => typeof file === "string")
+      ) return invalidTraceAction(lineNumber);
+      break;
+    case "MouseDrag":
+      if (
+        !hasExactKeys(payload, TRACE_MOUSE_DRAG_ACTION_KEYS)
+        || !isSafeIntegerBetween(payload.delay_millis, 0, 1_000)
+        || !isSafeIntegerBetween(payload.steps, 1, 255)
+        || !validTracePoint(payload.from)
+        || !validTracePoint(payload.to)
+      ) return invalidTraceAction(lineNumber);
+      break;
+    case "SetViewport":
+      if (
+        !hasExactKeys(payload, TRACE_VIEWPORT_ACTION_KEYS)
+        || !isSafeIntegerBetween(payload.height, 1, 10_000)
+        || !isSafeIntegerBetween(payload.width, 1, 10_000)
+      ) return invalidTraceAction(lineNumber);
+      break;
+    default:
+      return invalidTraceAction(lineNumber);
+  }
+  return { kind: actionKind, targetTag };
+}
+
+function parseNonNegativeFiniteNumber(
+  value: unknown,
+  lineNumber: number,
+  field: string,
+): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throw new Error(`Bombadil trace line ${String(lineNumber)} has an invalid ${field}`);
+  }
+  return value;
+}
+
+function parseTraceState(value: unknown, lineNumber: number): ParsedTraceState {
+  if (!isRecord(value) || !hasExactKeys(value, TRACE_STATE_KEYS)) {
+    throw new Error(`Bombadil trace line ${String(lineNumber)} has an invalid browser state`);
+  }
+  if (typeof value.url !== "string" || value.url.length === 0 || value.url.length > 8_192) {
+    throw new Error(`Bombadil trace line ${String(lineNumber)} has an invalid browser URL`);
+  }
+  let url: URL;
+  try {
+    url = new URL(value.url);
+  } catch {
+    throw new Error(`Bombadil trace line ${String(lineNumber)} has an invalid browser URL`);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(`Bombadil trace line ${String(lineNumber)} has an invalid browser URL protocol`);
+  }
+  if (typeof value.screenshot !== "string" || value.screenshot.length > 8_192) {
+    throw new Error(`Bombadil trace line ${String(lineNumber)} has an invalid screenshot path`);
+  }
+  for (const field of ["hash_previous", "hash_current"] as const) {
+    const hash = value[field];
+    if (hash !== null && (
+      typeof hash !== "number"
+      || !Number.isFinite(hash)
+      || !Number.isInteger(hash)
+      || hash < 0
+    )) {
+      throw new Error(`Bombadil trace line ${String(lineNumber)} has an invalid ${field}`);
+    }
+  }
+  if (!isRecord(value.resources) || !hasExactKeys(value.resources, TRACE_RESOURCE_KEYS)) {
+    throw new Error(`Bombadil trace line ${String(lineNumber)} has invalid browser resources`);
+  }
+  const resources: Record<string, number> = {};
+  for (const field of Object.keys(RESOURCE_FIELD_MAP) as (keyof typeof RESOURCE_FIELD_MAP)[]) {
+    resources[field] = parseNonNegativeFiniteNumber(
+      value.resources[field],
+      lineNumber,
+      `resources.${field}`,
+    );
+  }
+  parseNonNegativeFiniteNumber(value.resources.timestamp, lineNumber, "resources.timestamp");
+  return {
+    currentHash: value.hash_current as number | null,
+    resources: resources as Readonly<Record<keyof typeof RESOURCE_FIELD_MAP, number>>,
+    url,
+  };
+}
+
+function parseTraceEnvelope(line: string, lineNumber: number): ParsedTraceEnvelope {
   let input: unknown;
   try {
     input = JSON.parse(line) as unknown;
@@ -447,9 +990,22 @@ function parseTraceLine(line: string, lineNumber: number): TraceDirectObservatio
   ) {
     throw new Error(`Bombadil trace line ${String(lineNumber)} has invalid state fields`);
   }
-  const snapshots = input.snapshots as unknown[];
-  const directSnapshots = snapshots.filter((snapshot): snapshot is Readonly<Record<string, unknown>> =>
-    isRecord(snapshot) && snapshot.name === "direct"
+  return {
+    action: input.action,
+    snapshots: input.snapshots as unknown[],
+    state: input.state,
+    timestamp: input.timestamp,
+    violations: input.violations,
+  };
+}
+
+function parseDirectTraceObservation(
+  envelope: ParsedTraceEnvelope,
+  lineNumber: number,
+): ParsedDirectTraceObservation {
+  const directSnapshots = envelope.snapshots.filter(
+    (snapshot): snapshot is Readonly<Record<string, unknown>> =>
+      isRecord(snapshot) && snapshot.name === "direct",
   );
   if (directSnapshots.length !== 1) {
     throw new Error(`Bombadil trace line ${String(lineNumber)} must contain one named direct snapshot`);
@@ -465,7 +1021,97 @@ function parseTraceLine(line: string, lineNumber: number): TraceDirectObservatio
   ) {
     throw new Error(`Bombadil trace line ${String(lineNumber)} has an invalid direct snapshot`);
   }
-  return parseTraceDirectObservation(snapshot.value);
+  return {
+    observation: parseTraceDirectObservation(snapshot.value),
+    value: snapshot.value,
+  };
+}
+
+function parseDirectTraceLine(line: string, lineNumber: number): TraceDirectObservation {
+  return parseDirectTraceObservation(parseTraceEnvelope(line, lineNumber), lineNumber).observation;
+}
+
+function parseTraceLine(
+  line: string,
+  lineNumber: number,
+  strictDiagnosticSnapshotNames: ReadonlySet<string>,
+): ParsedTraceLine {
+  const envelope = parseTraceEnvelope(line, lineNumber);
+  const state = parseTraceState(envelope.state, lineNumber);
+  const action = parseTraceAction(envelope.action, lineNumber);
+  const snapshots = envelope.snapshots;
+  const direct = parseDirectTraceObservation(envelope, lineNumber);
+  const namedSnapshots: Array<{ readonly name: string; readonly valueSha256: string }> = [{
+    name: "direct",
+    valueSha256: namedSnapshotValueSha256(direct.value, {
+      maximumBytes: TRACE_MAX_LINE_BYTES,
+      maximumDepth: TRACE_MAX_JSON_DEPTH + 4,
+    }),
+  }];
+  const diagnosticSnapshotValues = new Map<string, unknown[]>();
+  for (const snapshotValue of snapshots) {
+    if (
+      !isRecord(snapshotValue)
+      || !hasExactKeys(snapshotValue, TRACE_SNAPSHOT_KEYS)
+      || !Number.isSafeInteger(snapshotValue.index)
+      || !Number.isSafeInteger(snapshotValue.time)
+      || (snapshotValue.index as number) < 0
+      || (snapshotValue.time as number) < 0
+      || (snapshotValue.name !== null && typeof snapshotValue.name !== "string")
+    ) {
+      throw new Error(`Bombadil trace line ${String(lineNumber)} has an invalid snapshot`);
+    }
+    if (snapshotValue.name === null || snapshotValue.name === "direct") continue;
+    let name: string;
+    try {
+      name = validateSnapshotName(
+        snapshotValue.name,
+        `Bombadil trace line ${String(lineNumber)} snapshot name`,
+      );
+    } catch (error) {
+      if (strictDiagnosticSnapshotNames.has(snapshotValue.name)) throw error;
+      continue;
+    }
+    const values = diagnosticSnapshotValues.get(name) ?? [];
+    values.push(snapshotValue.value);
+    diagnosticSnapshotValues.set(name, values);
+  }
+  for (const [name, values] of diagnosticSnapshotValues) {
+    if (values.length !== 1) {
+      if (strictDiagnosticSnapshotNames.has(name)) {
+        throw new Error(`Bombadil trace line ${String(lineNumber)} repeats named snapshot ${name}`);
+      }
+      continue;
+    }
+    try {
+      namedSnapshots.push({
+        name,
+        valueSha256: namedSnapshotValueSha256(values[0]),
+      });
+    } catch (error) {
+      if (strictDiagnosticSnapshotNames.has(name)) throw error;
+    }
+  }
+  const propertyViolationNames: string[] = [];
+  for (const violation of envelope.violations) {
+    if (!isRecord(violation) || !hasExactKeys(violation, TRACE_VIOLATION_KEYS)) {
+      throw new Error(`Bombadil trace line ${String(lineNumber)} has an invalid property violation`);
+    }
+    propertyViolationNames.push(validateSnapshotName(
+      violation.name,
+      `Bombadil trace line ${String(lineNumber)} property violation name`,
+    ));
+    if (!isRecord(violation.violation) || Object.keys(violation.violation).length !== 1) {
+      throw new Error(`Bombadil trace line ${String(lineNumber)} has an invalid property violation`);
+    }
+  }
+  return {
+    action,
+    directObservation: direct.observation,
+    namedSnapshots,
+    propertyViolationNames,
+    state,
+  };
 }
 
 /** Exact post-run proof over Bombadil 0.7.2's bounded JSONL trace. */
@@ -499,7 +1145,7 @@ export async function attestDirectBombadilTrace(options: {
       if (Buffer.byteLength(line, "utf8") > TRACE_MAX_LINE_BYTES) {
         throw new Error(`Bombadil trace line ${String(observationCount)} is too large`);
       }
-      const observation = parseTraceLine(line, observationCount);
+      const observation = parseDirectTraceLine(line, observationCount);
       const exact = exactTraceDirectObservation(observation);
       if (exact === null) {
         if (initial !== null) {
@@ -577,6 +1223,332 @@ export async function attestDirectBombadilTrace(options: {
   };
 }
 
+function sortedCountRecord<K extends string>(
+  values: ReadonlyMap<K, number>,
+): Readonly<Partial<Record<K, number>>> {
+  return Object.freeze(Object.fromEntries(
+    [...values.entries()].sort(([left], [right]) => compareCodeUnits(left, right)),
+  ) as Partial<Record<K, number>>);
+}
+
+/**
+ * Derives bounded diagnostic exploration metadata from the raw Bombadil trace.
+ * The hashes and counts are navigation aids, not Direct coverage evidence.
+ */
+export async function summarizeDirectBombadilTrace(options: {
+  readonly explorationPolicy?: DirectBombadilExplorationPolicy;
+  readonly targetUrl: string;
+  readonly tracePath: string;
+}): Promise<DirectBombadilExplorationSummary> {
+  const metadata = await stat(options.tracePath).catch(() => null);
+  if (metadata === null || !metadata.isFile() || metadata.size === 0) {
+    throw new Error("Bombadil did not produce a nonempty trace.jsonl");
+  }
+  if (metadata.size > TRACE_MAX_BYTES) {
+    throw new Error(`Bombadil trace exceeds ${String(TRACE_MAX_BYTES)} bytes`);
+  }
+  let targetUrl: URL;
+  try {
+    targetUrl = new URL(options.targetUrl);
+  } catch {
+    throw new Error("targetUrl must be an absolute URL");
+  }
+  const policy = validateExplorationPolicy(options.explorationPolicy);
+  const strictDiagnosticSnapshotNames = explorationPolicySnapshotNames(policy);
+  const actionCounts = new Map<DirectBombadilActionKind, number>();
+  const targetTags = new Map<string, number>();
+  const urlFingerprints = new Set<string>();
+  const rawUrlFingerprints = new Set<string>();
+  const transitionHashes = new Set<string>();
+  const rawTransitionHashes = new Set<string>();
+  const snapshots = new Map<string, {
+    readonly changeAfterActionKind: Map<DirectBombadilActionKind, number>;
+    changeAfterNonWaitCount: number;
+    lastObservationIndex: number | null;
+    lastValueSha256: string | null;
+    observationCount: number;
+    readonly values: Set<string>;
+  }>();
+  const propertyViolations = new Map<string, number>();
+  const resources = {
+    documents: 0,
+    domNodes: 0,
+    jsEventListeners: 0,
+    jsHeapTotalBytes: 0,
+    jsHeapUsedBytes: 0,
+    layoutObjects: 0,
+    scriptDurationSeconds: 0,
+    taskDurationSeconds: 0,
+    threadTimeSeconds: 0,
+  };
+  let lineCount = 0;
+  let totalActions = 0;
+  let nonWaitCount = 0;
+  let waitStreak = 0;
+  let maxWaitStreak = 0;
+  let nonNullHashCount = 0;
+  let rawNonNullHashCount = 0;
+  let policyObservationCount = 0;
+  let previousObservationWasExact = false;
+  let stableTarget = true;
+  let trackedUnrelatedSnapshotNameCount = 0;
+  const unrelatedSnapshotNameLimit = Math.max(
+    0,
+    TRACE_MAX_NAMED_SNAPSHOT_NAMES - strictDiagnosticSnapshotNames.size,
+  );
+  const stream = createReadStream(options.tracePath, { encoding: "utf8" });
+  const lines = createInterface({ input: stream, crlfDelay: Infinity });
+  try {
+    for await (const line of lines) {
+      lineCount += 1;
+      if (lineCount > TRACE_MAX_LINES) {
+        throw new Error(`Bombadil trace exceeds ${String(TRACE_MAX_LINES)} lines`);
+      }
+      if (Buffer.byteLength(line, "utf8") > TRACE_MAX_LINE_BYTES) {
+        throw new Error(`Bombadil trace line ${String(lineCount)} is too large`);
+      }
+      const parsed = parseTraceLine(line, lineCount, strictDiagnosticSnapshotNames);
+      const rawRelativeUrl =
+        `${parsed.state.url.pathname}${parsed.state.url.search}${parsed.state.url.hash}`;
+      rawUrlFingerprints.add(sha256(rawRelativeUrl));
+      if (rawUrlFingerprints.size > TRACE_MAX_DISTINCT_URLS) {
+        throw new Error(
+          `Bombadil trace exceeds ${String(TRACE_MAX_DISTINCT_URLS)} distinct raw URL fingerprints`,
+        );
+      }
+      if (parsed.state.currentHash !== null) {
+        rawNonNullHashCount += 1;
+        rawTransitionHashes.add(String(parsed.state.currentHash));
+      }
+      for (const name of parsed.propertyViolationNames) {
+        if (!propertyViolations.has(name) && propertyViolations.size >= TRACE_MAX_PROPERTY_NAMES) {
+          throw new Error(
+            `Bombadil trace exceeds ${String(TRACE_MAX_PROPERTY_NAMES)} property names`,
+          );
+        }
+        propertyViolations.set(name, (propertyViolations.get(name) ?? 0) + 1);
+      }
+      for (const [sourceName, outputName] of Object.entries(RESOURCE_FIELD_MAP)) {
+        resources[outputName] = Math.max(
+          resources[outputName],
+          parsed.state.resources[sourceName as keyof typeof RESOURCE_FIELD_MAP],
+        );
+      }
+      const currentObservationIsExact =
+        exactTraceDirectObservation(parsed.directObservation) !== null;
+      if (!currentObservationIsExact) {
+        previousObservationWasExact = false;
+        continue;
+      }
+      policyObservationCount += 1;
+      const actionFollowsExactObservation = previousObservationWasExact;
+      const recordedActionKind = actionFollowsExactObservation
+        ? parsed.action?.kind ?? null
+        : null;
+
+      if (actionFollowsExactObservation && parsed.action !== null) {
+        totalActions += 1;
+        actionCounts.set(parsed.action.kind, (actionCounts.get(parsed.action.kind) ?? 0) + 1);
+        if (parsed.action.kind === "Wait") {
+          waitStreak += 1;
+          maxWaitStreak = Math.max(maxWaitStreak, waitStreak);
+        } else {
+          nonWaitCount += 1;
+          waitStreak = 0;
+        }
+        if (parsed.action.targetTag !== null) {
+          if (!targetTags.has(parsed.action.targetTag) && targetTags.size >= 128) {
+            throw new Error("Bombadil trace exceeds 128 distinct action target tags");
+          }
+          targetTags.set(
+            parsed.action.targetTag,
+            (targetTags.get(parsed.action.targetTag) ?? 0) + 1,
+          );
+        }
+      } else if (actionFollowsExactObservation) {
+        waitStreak = 0;
+      }
+
+      const relativeUrl = `${parsed.state.url.pathname}${parsed.state.url.search}${parsed.state.url.hash}`;
+      urlFingerprints.add(sha256(relativeUrl));
+      if (urlFingerprints.size > TRACE_MAX_DISTINCT_URLS) {
+        throw new Error(
+          `Bombadil trace exceeds ${String(TRACE_MAX_DISTINCT_URLS)} distinct URL fingerprints`,
+        );
+      }
+      stableTarget &&= parsed.state.url.href === targetUrl.href;
+      if (parsed.state.currentHash !== null) {
+        nonNullHashCount += 1;
+        transitionHashes.add(String(parsed.state.currentHash));
+      }
+
+      for (const snapshot of parsed.namedSnapshots) {
+        let entry = snapshots.get(snapshot.name);
+        if (entry === undefined) {
+          const isStrictSnapshot = snapshot.name === "direct"
+            || strictDiagnosticSnapshotNames.has(snapshot.name);
+          if (!isStrictSnapshot && trackedUnrelatedSnapshotNameCount >= unrelatedSnapshotNameLimit) {
+            continue;
+          }
+          if (snapshots.size >= TRACE_MAX_NAMED_SNAPSHOT_NAMES) {
+            throw new Error(
+              `Bombadil trace exceeds ${String(TRACE_MAX_NAMED_SNAPSHOT_NAMES)} named snapshots`,
+            );
+          }
+          entry = {
+            changeAfterActionKind: new Map<DirectBombadilActionKind, number>(),
+            changeAfterNonWaitCount: 0,
+            lastObservationIndex: null,
+            lastValueSha256: null,
+            observationCount: 0,
+            values: new Set<string>(),
+          };
+          snapshots.set(snapshot.name, entry);
+          if (!isStrictSnapshot) trackedUnrelatedSnapshotNameCount += 1;
+        }
+        if (
+          !entry.values.has(snapshot.valueSha256)
+          && entry.values.size >= TRACE_MAX_DISTINCT_SNAPSHOT_VALUES_PER_NAME
+        ) {
+          if (
+            snapshot.name === "direct"
+            || strictDiagnosticSnapshotNames.has(snapshot.name)
+          ) {
+            throw new Error(
+              `Bombadil trace named snapshot ${snapshot.name} exceeds ${String(TRACE_MAX_DISTINCT_SNAPSHOT_VALUES_PER_NAME)} distinct values`,
+            );
+          }
+          continue;
+        }
+        const changedAfterRecordedAction =
+          recordedActionKind !== null
+          && entry.lastObservationIndex === policyObservationCount - 1
+          && entry.lastValueSha256 !== null
+          && entry.lastValueSha256 !== snapshot.valueSha256;
+        if (changedAfterRecordedAction) {
+          entry.changeAfterActionKind.set(
+            recordedActionKind,
+            (entry.changeAfterActionKind.get(recordedActionKind) ?? 0) + 1,
+          );
+        }
+        if (changedAfterRecordedAction && recordedActionKind !== "Wait") {
+          entry.changeAfterNonWaitCount += 1;
+        }
+        entry.lastObservationIndex = policyObservationCount;
+        entry.lastValueSha256 = snapshot.valueSha256;
+        entry.observationCount += 1;
+        entry.values.add(snapshot.valueSha256);
+      }
+      previousObservationWasExact = true;
+    }
+  } finally {
+    lines.close();
+    stream.destroy();
+  }
+  if (lineCount === 0) throw new Error("Bombadil did not produce a nonempty trace.jsonl");
+
+  const policyFailures: string[] = [];
+  if (policy !== null) {
+    if (nonWaitCount < policy.minNonWaitActions) {
+      policyFailures.push("minimum non-Wait action count was not reached");
+    }
+    for (const kind of policy.requiredActionKinds) {
+      if ((actionCounts.get(kind) ?? 0) === 0) {
+        policyFailures.push(`required action kind ${kind} was not observed`);
+      }
+    }
+    for (const name of policy.requiredNamedSnapshots) {
+      if (!snapshots.has(name)) {
+        policyFailures.push(`required named snapshot ${name} was not observed`);
+      }
+    }
+    for (const [name, minimum] of Object.entries(policy.minDistinctNamedSnapshotValues)) {
+      if ((snapshots.get(name)?.values.size ?? 0) < minimum) {
+        policyFailures.push(`named snapshot ${name} did not reach its distinct-value minimum`);
+      }
+    }
+    for (const [name, minimum] of Object.entries(
+      policy.minNamedSnapshotChangesAfterNonWait,
+    )) {
+      if ((snapshots.get(name)?.changeAfterNonWaitCount ?? 0) < minimum) {
+        policyFailures.push(
+          `named snapshot ${name} did not reach its post-non-Wait change minimum`,
+        );
+      }
+    }
+    for (const [name, minimumByKind] of Object.entries(
+      policy.minNamedSnapshotChangesAfterActionKind,
+    )) {
+      for (const [kind, minimum] of Object.entries(minimumByKind) as [
+        DirectBombadilActionKind,
+        number,
+      ][]) {
+        if ((snapshots.get(name)?.changeAfterActionKind.get(kind) ?? 0) < minimum) {
+          policyFailures.push(
+            `named snapshot ${name} did not reach its post-${kind} change minimum`,
+          );
+        }
+      }
+    }
+    if (policy.requireStableTargetUrl && !stableTarget) {
+      policyFailures.push("the browser did not remain on the exact target URL");
+    }
+  }
+  const traceBytes = await readFile(options.tracePath);
+  return Object.freeze({
+    schema: "direct.bombadil-exploration-summary/v2",
+    trace: Object.freeze({
+      bytes: metadata.size,
+      lineCount,
+      sha256: sha256(traceBytes),
+    }),
+    actions: Object.freeze({
+      byKind: sortedCountRecord(actionCounts),
+      maxWaitStreak,
+      nonWaitCount,
+      targetTags: sortedCountRecord(targetTags) as Readonly<Record<string, number>>,
+      total: totalActions,
+    }),
+    urls: Object.freeze({
+      distinctFingerprintCount: urlFingerprints.size,
+      fingerprintSha256: Object.freeze([...urlFingerprints].sort(compareCodeUnits)),
+      observationCount: policyObservationCount,
+      rawDistinctFingerprintCount: rawUrlFingerprints.size,
+      rawFingerprintSha256: Object.freeze(
+        [...rawUrlFingerprints].sort(compareCodeUnits),
+      ),
+      rawObservationCount: lineCount,
+      stableTarget,
+    }),
+    transitions: Object.freeze({
+      distinctNonNullHashCount: transitionHashes.size,
+      nonNullHashCount,
+      rawDistinctNonNullHashCount: rawTransitionHashes.size,
+      rawNonNullHashCount,
+    }),
+    namedSnapshots: Object.freeze([...snapshots.entries()]
+      .sort(([left], [right]) => compareCodeUnits(left, right))
+      .map(([name, entry]) => Object.freeze({
+        changeAfterActionKind: sortedCountRecord(entry.changeAfterActionKind),
+        changeAfterNonWaitCount: entry.changeAfterNonWaitCount,
+        distinctValueCount: entry.values.size,
+        distinctValueSha256: Object.freeze([...entry.values].sort(compareCodeUnits)),
+        name,
+        observationCount: entry.observationCount,
+      }))),
+    propertyViolations: Object.freeze({
+      byName: sortedCountRecord(propertyViolations) as Readonly<Record<string, number>>,
+      total: [...propertyViolations.values()].reduce((total, value) => total + value, 0),
+    }),
+    resourceHighWaterMarks: Object.freeze(resources),
+    policy: Object.freeze({
+      configured: policy !== null,
+      failures: Object.freeze(policyFailures),
+      satisfied: policyFailures.length === 0,
+    }),
+  });
+}
+
 export function parseDirectBombadilFuzzArguments(
   arguments_: readonly string[],
   defaultBaseUrl: string,
@@ -689,7 +1661,7 @@ function validateTargetQuery(value: unknown): Readonly<Record<string, string>> {
   }
   const validated: Record<string, string> = {};
   for (const [name, queryValue] of [...entries].sort(([left], [right]) =>
-    left.localeCompare(right)
+    compareCodeUnits(left, right)
   )) {
     if (
       name.length === 0
@@ -714,6 +1686,227 @@ function validateTargetQuery(value: unknown): Readonly<Record<string, string>> {
   return Object.freeze(validated);
 }
 
+function validateSnapshotName(value: unknown, label: string): string {
+  if (
+    typeof value !== "string"
+    || value.length === 0
+    || value.length > 128
+    || !SNAPSHOT_NAME_PATTERN.test(value)
+    || PROTOTYPE_PROPERTY_NAMES.has(value)
+    || hasControlCharacters(value)
+  ) {
+    throw new Error(`${label} must be a safe bounded snapshot name`);
+  }
+  return value;
+}
+
+function validateViewport(value: unknown): ValidatedViewport {
+  if (value === undefined) {
+    return Object.freeze({
+      deviceScaleFactor: DEFAULT_DEVICE_SCALE_FACTOR,
+      height: DEFAULT_VIEWPORT_HEIGHT,
+      width: DEFAULT_VIEWPORT_WIDTH,
+    });
+  }
+  if (!isRecord(value) || !Object.keys(value).every((key) => VIEWPORT_KEYS.has(key))) {
+    throw new Error("viewport must contain only width, height, and deviceScaleFactor");
+  }
+  const validateDimension = (name: "height" | "width", input: unknown): number => {
+    if (
+      typeof input !== "number"
+      || !Number.isSafeInteger(input)
+      || input < 1
+      || input > 65_535
+    ) {
+      throw new Error(`viewport.${name} must be an integer between 1 and 65535`);
+    }
+    return input;
+  };
+  const width = validateDimension("width", value.width ?? DEFAULT_VIEWPORT_WIDTH);
+  const height = validateDimension("height", value.height ?? DEFAULT_VIEWPORT_HEIGHT);
+  const deviceScaleFactor = value.deviceScaleFactor ?? DEFAULT_DEVICE_SCALE_FACTOR;
+  if (
+    typeof deviceScaleFactor !== "number"
+    || !Number.isFinite(deviceScaleFactor)
+    || deviceScaleFactor < 0.1
+    || deviceScaleFactor > 10
+  ) {
+    throw new Error("viewport.deviceScaleFactor must be a finite number between 0.1 and 10");
+  }
+  return Object.freeze({ deviceScaleFactor, height, width });
+}
+
+function validateSnapshotMinimumMap(options: {
+  readonly label: string;
+  readonly maximum: number;
+  readonly value: unknown;
+}): Readonly<Record<string, number>> {
+  if (!isRecord(options.value) || Object.keys(options.value).length > 32) {
+    throw new Error(`${options.label} must be a bounded object`);
+  }
+  const validated: Record<string, number> = {};
+  for (const [rawName, minimum] of Object.entries(options.value).sort(([left], [right]) =>
+    compareCodeUnits(left, right)
+  )) {
+    const name = validateSnapshotName(rawName, `${options.label} key`);
+    if (
+      typeof minimum !== "number"
+      || !Number.isSafeInteger(minimum)
+      || minimum < 1
+      || minimum > options.maximum
+    ) {
+      throw new Error(
+        `${options.label} ${name} must be an integer between 1 and ${String(options.maximum)}`,
+      );
+    }
+    validated[name] = minimum;
+  }
+  return Object.freeze(validated);
+}
+
+function validateSnapshotActionMinimumMap(options: {
+  readonly label: string;
+  readonly value: unknown;
+}): Readonly<Record<
+  string,
+  Readonly<Partial<Record<DirectBombadilActionKind, number>>>
+>> {
+  if (!isRecord(options.value) || Object.keys(options.value).length > 32) {
+    throw new Error(`${options.label} must be a bounded object`);
+  }
+  const validated: Record<
+    string,
+    Readonly<Partial<Record<DirectBombadilActionKind, number>>>
+  > = {};
+  for (const [rawName, rawMinimumByKind] of Object.entries(options.value)
+    .sort(([left], [right]) => compareCodeUnits(left, right))) {
+    const name = validateSnapshotName(rawName, `${options.label} key`);
+    if (
+      !isRecord(rawMinimumByKind)
+      || Object.keys(rawMinimumByKind).length === 0
+      || Object.keys(rawMinimumByKind).length > ACTION_KINDS.length
+    ) {
+      throw new Error(`${options.label} ${name} must be a bounded action map`);
+    }
+    const minimumByKind: Partial<Record<DirectBombadilActionKind, number>> = {};
+    for (const [rawKind, minimum] of Object.entries(rawMinimumByKind)
+      .sort(([left], [right]) => compareCodeUnits(left, right))) {
+      if (!ACTION_KIND_SET.has(rawKind)) {
+        throw new Error(`${options.label} ${name} contains an unknown action kind`);
+      }
+      if (
+        typeof minimum !== "number"
+        || !Number.isSafeInteger(minimum)
+        || minimum < 1
+        || minimum > TRACE_MAX_LINES
+      ) {
+        throw new Error(
+          `${options.label} ${name}.${rawKind} must be an integer between 1 and ${String(TRACE_MAX_LINES)}`,
+        );
+      }
+      minimumByKind[rawKind as DirectBombadilActionKind] = minimum;
+    }
+    validated[name] = Object.freeze(minimumByKind);
+  }
+  return Object.freeze(validated);
+}
+
+function explorationPolicySnapshotNames(
+  policy: ValidatedExplorationPolicy | null,
+): ReadonlySet<string> {
+  const names = new Set<string>(["direct"]);
+  if (policy === null) return names;
+  for (const name of policy.requiredNamedSnapshots) names.add(name);
+  for (const name of Object.keys(policy.minDistinctNamedSnapshotValues)) names.add(name);
+  for (const name of Object.keys(policy.minNamedSnapshotChangesAfterNonWait)) names.add(name);
+  for (const name of Object.keys(policy.minNamedSnapshotChangesAfterActionKind)) names.add(name);
+  return names;
+}
+
+function validateExplorationPolicy(
+  value: unknown,
+): ValidatedExplorationPolicy | null {
+  if (value === undefined) return null;
+  if (
+    !isRecord(value)
+    || !Object.keys(value).every((key) => EXPLORATION_POLICY_KEYS.has(key))
+  ) {
+    throw new Error("explorationPolicy contains an unknown field");
+  }
+  const minNonWaitActions = value.minNonWaitActions ?? 0;
+  if (
+    typeof minNonWaitActions !== "number"
+    || !Number.isSafeInteger(minNonWaitActions)
+    || minNonWaitActions < 0
+    || minNonWaitActions > TRACE_MAX_LINES
+  ) {
+    throw new Error(
+      `explorationPolicy.minNonWaitActions must be an integer between 0 and ${String(TRACE_MAX_LINES)}`,
+    );
+  }
+  const requiredActionKindsInput = value.requiredActionKinds ?? [];
+  if (!Array.isArray(requiredActionKindsInput) || requiredActionKindsInput.length > ACTION_KINDS.length) {
+    throw new Error("explorationPolicy.requiredActionKinds must be a bounded array");
+  }
+  const requiredActionKinds = [...requiredActionKindsInput];
+  if (
+    !requiredActionKinds.every((kind): kind is DirectBombadilActionKind =>
+      typeof kind === "string" && ACTION_KIND_SET.has(kind)
+    )
+    || new Set(requiredActionKinds).size !== requiredActionKinds.length
+  ) {
+    throw new Error("explorationPolicy.requiredActionKinds contains an unknown or duplicate kind");
+  }
+  requiredActionKinds.sort(compareCodeUnits);
+
+  const requiredNamedSnapshotsInput = value.requiredNamedSnapshots ?? [];
+  if (!Array.isArray(requiredNamedSnapshotsInput) || requiredNamedSnapshotsInput.length > 32) {
+    throw new Error("explorationPolicy.requiredNamedSnapshots must be a bounded array");
+  }
+  const requiredNamedSnapshots = requiredNamedSnapshotsInput.map((name) =>
+    validateSnapshotName(name, "explorationPolicy.requiredNamedSnapshots entry")
+  );
+  if (new Set(requiredNamedSnapshots).size !== requiredNamedSnapshots.length) {
+    throw new Error("explorationPolicy.requiredNamedSnapshots contains a duplicate name");
+  }
+  requiredNamedSnapshots.sort(compareCodeUnits);
+
+  const minDistinctNamedSnapshotValues = validateSnapshotMinimumMap({
+    label: "explorationPolicy.minDistinctNamedSnapshotValues",
+    maximum: TRACE_MAX_DISTINCT_SNAPSHOT_VALUES_PER_NAME,
+    value: value.minDistinctNamedSnapshotValues ?? {},
+  });
+  const minNamedSnapshotChangesAfterActionKind =
+    validateSnapshotActionMinimumMap({
+      label: "explorationPolicy.minNamedSnapshotChangesAfterActionKind",
+      value: value.minNamedSnapshotChangesAfterActionKind ?? {},
+    });
+  const minNamedSnapshotChangesAfterNonWait = validateSnapshotMinimumMap({
+    label: "explorationPolicy.minNamedSnapshotChangesAfterNonWait",
+    maximum: TRACE_MAX_LINES,
+    value: value.minNamedSnapshotChangesAfterNonWait ?? {},
+  });
+  const requireStableTargetUrl = value.requireStableTargetUrl ?? false;
+  if (typeof requireStableTargetUrl !== "boolean") {
+    throw new Error("explorationPolicy.requireStableTargetUrl must be a boolean");
+  }
+  const validated: ValidatedExplorationPolicy = Object.freeze({
+    minDistinctNamedSnapshotValues,
+    minNamedSnapshotChangesAfterActionKind,
+    minNamedSnapshotChangesAfterNonWait,
+    minNonWaitActions,
+    requireStableTargetUrl,
+    requiredActionKinds: Object.freeze(requiredActionKinds),
+    requiredNamedSnapshots: Object.freeze(requiredNamedSnapshots),
+  });
+  if (explorationPolicySnapshotNames(validated).size > TRACE_MAX_NAMED_SNAPSHOT_NAMES) {
+    throw new Error(
+      `explorationPolicy may reference at most ${String(TRACE_MAX_NAMED_SNAPSHOT_NAMES - 1)} distinct non-Direct snapshots`,
+    );
+  }
+  return validated;
+}
+
 export function validateDirectBombadilFuzzConfig(
   config: DirectBombadilFuzzConfig,
   baseUrlOverride?: string,
@@ -782,6 +1975,8 @@ export function validateDirectBombadilFuzzConfig(
   const entryPath = config.entryPath ?? "/";
   validateEntryPath(entryPath);
   const targetQuery = validateTargetQuery(config.targetQuery ?? {});
+  const viewport = validateViewport(config.viewport);
+  const explorationPolicy = validateExplorationPolicy(config.explorationPolicy);
   const startupTimeoutMs = config.server.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
   if (
     !Number.isSafeInteger(startupTimeoutMs)
@@ -803,8 +1998,10 @@ export function validateDirectBombadilFuzzConfig(
     artifactRoot: join(repositoryRoot, "artifacts", "direct-bombadil", config.artifactName),
     bombadilExecutable: bombadilNativeBinary(repositoryRoot),
     entryPath,
+    explorationPolicy,
     port,
     targetQuery,
+    viewport,
     server: {
       ...config.server,
       cwd: serverCwd,
@@ -834,7 +2031,9 @@ export function createDirectBombadilInvocation(options: {
   readonly specificationPath: string;
   readonly targetQuery?: Readonly<Record<string, string>>;
   readonly timeLimitSeconds: number;
+  readonly viewport?: DirectBombadilViewportConfig;
 }): DirectBombadilInvocation {
+  const viewport = validateViewport(options.viewport);
   const target = new URL(options.entryPath ?? "/", `${options.baseUrl}/`);
   target.searchParams.set(SCENARIO_QUERY_KEY, options.scenario);
   for (const [name, value] of Object.entries(options.targetQuery ?? {})) {
@@ -850,6 +2049,12 @@ export function createDirectBombadilInvocation(options: {
     options.outputPath,
     "--headless",
     "--instrument-javascript=",
+    "--width",
+    String(viewport.width),
+    "--height",
+    String(viewport.height),
+    "--device-scale-factor",
+    String(viewport.deviceScaleFactor),
   ];
   if (options.replayPath === null) {
     command.push(
@@ -1007,6 +2212,7 @@ export async function runBombadilNativeProcess(
 
 const defaultDependencies: DirectBombadilRunnerDependencies = {
   acquireServer: acquireVerificationServer,
+  createAbortController: () => new AbortController(),
   now: () => new Date(),
   runBombadil: runBombadilNativeProcess,
   serverOutputTimeoutMs: SERVER_OUTPUT_TIMEOUT_MS,
@@ -1181,6 +2387,113 @@ function helpText(defaultBaseUrl: string): string {
   ].join("\n");
 }
 
+function parseMatrixCampaignArgument(arguments_: readonly string[]): {
+  readonly arguments: readonly string[];
+  readonly campaignId: string | null;
+  readonly help: boolean;
+} {
+  const forwarded: string[] = [];
+  let campaignId: string | null = null;
+  let help = false;
+  for (let index = 0; index < arguments_.length; index += 1) {
+    const argument = arguments_[index];
+    if (argument === undefined) continue;
+    if (argument === "--help" || argument === "-h") help = true;
+    if (argument === "--campaign" || argument.startsWith("--campaign=")) {
+      if (campaignId !== null) throw new Error("--campaign may be provided only once");
+      if (argument === "--campaign") {
+        const next = readOptionValue(arguments_, index, "--campaign");
+        campaignId = next.value;
+        index = next.index;
+      } else {
+        campaignId = argument.slice("--campaign=".length);
+      }
+      if (campaignId.length === 0) throw new Error("--campaign requires a value");
+      continue;
+    }
+    forwarded.push(argument);
+  }
+  return { arguments: Object.freeze(forwarded), campaignId, help };
+}
+
+function validateCampaignMatrix(
+  campaigns: readonly DirectBombadilFuzzCampaign[],
+): readonly DirectBombadilFuzzCampaign[] {
+  if (campaigns.length === 0 || campaigns.length > 32) {
+    throw new Error("Bombadil campaign matrix must contain 1-32 campaigns");
+  }
+  const ids = new Set<string>();
+  for (const campaign of campaigns) {
+    if (!ARTIFACT_NAME_PATTERN.test(campaign.id) || ids.has(campaign.id)) {
+      throw new Error("Bombadil campaign IDs must be unique lowercase kebab identifiers");
+    }
+    ids.add(campaign.id);
+  }
+  return campaigns;
+}
+
+/** Runs a bounded product-owned campaign matrix serially. */
+export async function runDirectBombadilFuzzMatrix(
+  campaignsInput: readonly DirectBombadilFuzzCampaign[],
+  arguments_: readonly string[] = process.argv.slice(2),
+  dependencyOverrides: Partial<DirectBombadilRunnerDependencies> = {},
+): Promise<DirectBombadilFuzzMatrixResult> {
+  const campaigns = validateCampaignMatrix(campaignsInput);
+  const parsed = parseMatrixCampaignArgument(arguments_);
+  if (parsed.help) {
+    process.stdout.write(`${[
+      helpText(campaigns[0]?.config.baseUrl ?? ""),
+      "  --campaign <id>   Run one campaign; required with --replay",
+      "",
+      `Campaigns: ${campaigns.map((campaign) => campaign.id).join(", ")}`,
+    ].join("\n")}\n`);
+    return { kind: "help" };
+  }
+  const selected = parsed.campaignId === null
+    ? campaigns
+    : campaigns.filter((campaign) => campaign.id === parsed.campaignId);
+  if (selected.length === 0) {
+    throw new Error(`Unknown Bombadil campaign ${parsed.campaignId ?? ""}`);
+  }
+  if (
+    parsed.campaignId === null
+    && parsed.arguments.some((argument) =>
+      argument === "--replay" || argument.startsWith("--replay=")
+    )
+  ) {
+    throw new Error("--replay requires exactly one --campaign in matrix mode");
+  }
+  const results: Array<{
+    readonly campaignId: string;
+    readonly result: Extract<DirectBombadilFuzzResult, { readonly kind: "run" }>;
+  }> = [];
+  for (const campaign of selected) {
+    const result = await runDirectBombadilFuzz(
+      campaign.config,
+      parsed.arguments,
+      dependencyOverrides,
+    );
+    if (result.kind !== "run") {
+      throw new Error("Bombadil campaign unexpectedly returned help during matrix execution");
+    }
+    results.push({ campaignId: campaign.id, result });
+  }
+  return { kind: "matrix", results: Object.freeze(results) };
+}
+
+function throwIfBombadilRunAborted(signal: AbortSignal): void {
+  if (signal.aborted) throw new Error("Bombadil fuzzing was interrupted");
+}
+
+function terminateAbortedOwnedServer(
+  signal: AbortSignal,
+  server: ManagedVerificationServer,
+): void {
+  if (!signal.aborted) return;
+  if (server.exitCode() === null) server.terminate();
+  throwIfBombadilRunAborted(signal);
+}
+
 /** Runs one bounded diagnostic Bombadil campaign and always releases its server lease. */
 export async function runDirectBombadilFuzz(
   config: DirectBombadilFuzzConfig,
@@ -1212,7 +2525,7 @@ export async function runDirectBombadilFuzz(
   });
   const outputPath = join(artifactRun.runDirectory, "bombadil");
   const tracePath = join(outputPath, "trace.jsonl");
-  const abortController = new AbortController();
+  const abortController = dependencies.createAbortController?.() ?? new AbortController();
   const invocation = createDirectBombadilInvocation({
     baseUrl: validated.baseUrl,
     bombadilExecutable: validated.bombadilExecutable,
@@ -1224,6 +2537,7 @@ export async function runDirectBombadilFuzz(
     specificationPath: validated.specificationPath,
     targetQuery: validated.targetQuery,
     timeLimitSeconds: parsed.timeLimitSeconds,
+    viewport: validated.viewport,
   });
   const abortableInvocation = { ...invocation, abortSignal: abortController.signal };
   const serverCommand = validated.server.command.map((argument) =>
@@ -1236,6 +2550,8 @@ export async function runDirectBombadilFuzz(
   let processResult: BombadilProcessResult | null = null;
   let attestation: DirectBombadilTraceAttestation | null = null;
   let attestationFailure: unknown = null;
+  let explorationSummary: DirectBombadilExplorationSummary | null = null;
+  let explorationSummaryFailure: unknown = null;
   let rawTracePath: string | null = null;
   let serverOutput = "";
   let serverOutputFailure: unknown = null;
@@ -1255,23 +2571,36 @@ export async function runDirectBombadilFuzz(
     try {
       await requireRegularFile(validated.bombadilExecutable, "The root Bombadil executable");
       bombadilVersion = await readExactBombadilVersion(validated.repositoryRoot);
-      if (abortController.signal.aborted) throw new Error("Bombadil fuzzing was interrupted");
-
-      lease = await dependencies.acquireServer({
-        baseUrl: validated.baseUrl,
-        label: validated.label,
-        readinessPath: validated.server.readinessPath,
-        reuseExistingLocalServer: false,
-        startupTimeoutMs: validated.server.startupTimeoutMs,
-        startServer: () => {
-          ownedServer = dependencies.spawnServer({
-            command: serverCommand,
-            cwd: validated.server.cwd,
-            ...(validated.server.env === undefined ? {} : { env: validated.server.env }),
-          });
-          return ownedServer;
-        },
-      });
+      throwIfBombadilRunAborted(abortController.signal);
+
+      try {
+        lease = await dependencies.acquireServer({
+          abortSignal: abortController.signal,
+          baseUrl: validated.baseUrl,
+          label: validated.label,
+          readinessPath: validated.server.readinessPath,
+          reuseExistingLocalServer: false,
+          startupTimeoutMs: validated.server.startupTimeoutMs,
+          startServer: () => {
+            throwIfBombadilRunAborted(abortController.signal);
+            ownedServer = dependencies.spawnServer({
+              command: serverCommand,
+              cwd: validated.server.cwd,
+              ...(validated.server.env === undefined ? {} : { env: validated.server.env }),
+            });
+            terminateAbortedOwnedServer(abortController.signal, ownedServer);
+            return ownedServer;
+          },
+        });
+      } catch (error) {
+        if (abortController.signal.aborted) throwIfBombadilRunAborted(abortController.signal);
+        throw error;
+      }
+      if (abortController.signal.aborted) {
+        const acquiredOwnedServer = ownedServer as ManagedVerificationServer | null;
+        if (acquiredOwnedServer?.exitCode() === null) acquiredOwnedServer.terminate();
+        throwIfBombadilRunAborted(abortController.signal);
+      }
       let processFailure: unknown = null;
       try {
         processResult = await dependencies.runBombadil(abortableInvocation);
@@ -1291,6 +2620,17 @@ export async function runDirectBombadilFuzz(
       } catch (error) {
         attestationFailure = error;
       }
+      try {
+        explorationSummary = await summarizeDirectBombadilTrace({
+          ...(validated.explorationPolicy === null
+            ? {}
+            : { explorationPolicy: validated.explorationPolicy }),
+          targetUrl: invocation.targetUrl,
+          tracePath,
+        });
+      } catch (error) {
+        explorationSummaryFailure = error;
+      }
       if (processFailure !== null) {
         throw processFailure instanceof Error
           ? processFailure
@@ -1313,6 +2653,16 @@ export async function runDirectBombadilFuzz(
           ? attestationFailure
           : new Error(renderUnknown(attestationFailure));
       }
+      if (explorationSummaryFailure !== null) {
+        throw explorationSummaryFailure instanceof Error
+          ? explorationSummaryFailure
+          : new Error(renderUnknown(explorationSummaryFailure));
+      }
+      if (explorationSummary?.policy.satisfied !== true) {
+        throw new Error(
+          `Bombadil exploration policy was not satisfied: ${explorationSummary?.policy.failures.join("; ") ?? "summary unavailable"}`,
+        );
+      }
     } catch (error) {
       failure = error;
     }
@@ -1351,6 +2701,10 @@ export async function runDirectBombadilFuzz(
   const status = failure === null ? "passed" : "failed";
   const logPath = join(artifactRun.runDirectory, "bombadil.log");
   const serverLogPath = join(artifactRun.runDirectory, "server.log");
+  const explorationSummaryPath = join(
+    artifactRun.runDirectory,
+    "exploration-summary.json",
+  );
   const record = {
     schema: ARTIFACT_SCHEMA,
     evidenceClass: "diagnostic-fuzz",
@@ -1366,6 +2720,8 @@ export async function runDirectBombadilFuzz(
     entryPath: validated.entryPath,
     targetQuery: validated.targetQuery,
     targetUrl: invocation.targetUrl,
+    viewport: validated.viewport,
+    explorationPolicy: validated.explorationPolicy,
     specificationPath: validated.specificationPath,
     replayPath,
     timeLimitSeconds: replayPath === null ? parsed.timeLimitSeconds : null,
@@ -1387,6 +2743,11 @@ export async function runDirectBombadilFuzz(
     },
     attestation,
     attestationFailure: attestationFailure === null ? null : renderUnknown(attestationFailure),
+    explorationSummary,
+    explorationSummaryPath: explorationSummary === null ? null : explorationSummaryPath,
+    explorationSummaryFailure: explorationSummaryFailure === null
+      ? null
+      : renderUnknown(explorationSummaryFailure),
     initialDirect: attestation?.initial ?? null,
     interruptedSignal: capturedSignal,
     failure: failure === null ? null : renderUnknown(failure),
@@ -1401,10 +2762,28 @@ export async function runDirectBombadilFuzz(
       `${serverOutput}${serverOutput.length > 0 ? "\n" : ""}`,
       "utf8",
     );
+    if (explorationSummary !== null) {
+      await writeJsonAtomically(explorationSummaryPath, explorationSummary);
+    }
     await writeJsonAtomically(join(artifactRun.runDirectory, "run.json"), record);
     await writeJsonAtomically(artifactRun.manifestPath, record);
 
-    const summary = `${status === "passed" ? "PASS" : "FAIL"} ${validated.label}; artifacts: ${artifactRun.runDirectory}; log: ${logPath}`;
+    const exploration = explorationSummary === null
+      ? "exploration=unavailable"
+      : [
+          `nonWait=${String(explorationSummary.actions.nonWaitCount)}`,
+          `maxWaitStreak=${String(explorationSummary.actions.maxWaitStreak)}`,
+          `namedChanges=${explorationSummary.namedSnapshots
+            .map((snapshot) => `${snapshot.name}:${String(snapshot.changeAfterNonWaitCount)}`)
+            .join(",") || "none"}`,
+          `policy=${explorationSummary.policy.satisfied ? "satisfied" : "failed"}`,
+        ].join("; ");
+    const summary = [
+      `${status === "passed" ? "PASS" : "FAIL"} ${validated.label}`,
+      exploration,
+      `artifacts: ${artifactRun.runDirectory}`,
+      `log: ${logPath}`,
+    ].join("; ");
     (status === "passed" ? process.stdout : process.stderr).write(`${summary}\n`);
 
     if (failure !== null) {