@deeeed/metamask-harness 0.41.0 → 0.42.0

package/dist/network-observation.js

@@ -0,0 +1,271 @@
+import fs from "node:fs";
+import path from "node:path";
+import brokerModule from "../adapters/mobile/bridge-runtime/lib/cdp-broker.cjs";
+import {
+  createExtensionNetworkObserver
+} from "./adapters/extension/network-observer.js";
+const AUTO_CAPTURE_ID = "run-network";
+const AUTO_ARTIFACT_PATH = "network/run-summary.json";
+const { brokerSocketPath, createBrokerClient } = brokerModule;
+const sessions = /* @__PURE__ */ new Map();
+async function startRunNetworkObservation(adapter, target, artifactsDir, env, ports = {}) {
+  if (adapter === "core") return void 0;
+  const runtimeEnv = {
+    ...env,
+    ...ports.cdpPort ? { CDP_PORT: ports.cdpPort, RECIPE_CDP_PORT: ports.cdpPort } : {},
+    ...ports.watcherPort ? { WATCHER_PORT: ports.watcherPort } : {}
+  };
+  const key = path.resolve(artifactsDir);
+  const session = {
+    artifactsDir: key,
+    autoStarted: false,
+    autoStartedAt: Date.now(),
+    nodeEvents: []
+  };
+  sessions.set(key, session);
+  try {
+    session.backend = adapter === "mobile" ? await createMobileNetworkBackend(target, runtimeEnv) : await createExtensionNetworkObserver(extensionCdpPort(runtimeEnv), key);
+  } catch (error) {
+    session.setupError = boundedError(error);
+  }
+  if (runtimeEnv.MM_HARNESS_AUTO_NETWORK_CAPTURE !== "0") {
+    session.autoStartedAt = Date.now();
+    if (session.backend) {
+      try {
+        await session.backend.start({
+          id: AUTO_CAPTURE_ID,
+          bodyJsonFields: ["type"],
+          maxDurationMs: 60 * 60 * 1e3,
+          maxRequests: 1e4,
+          methods: [],
+          urlIncludes: []
+        });
+        session.autoStarted = true;
+      } catch (error) {
+        session.setupError = boundedError(error);
+      }
+    }
+  }
+  return {
+    onActionEvent(event) {
+      session.nodeEvents.push({ ...event, epochMs: Date.now() });
+    },
+    async finalize(artifactManifestPath) {
+      try {
+        if (runtimeEnv.MM_HARNESS_AUTO_NETWORK_CAPTURE !== "0") {
+          const summary = await automaticSummary(session);
+          writeSummary(key, AUTO_ARTIFACT_PATH, summary);
+          if (artifactManifestPath) {
+            indexArtifact(
+              artifactManifestPath,
+              AUTO_ARTIFACT_PATH,
+              "Automatic network observation"
+            );
+          }
+        }
+      } finally {
+        sessions.delete(key);
+        await session.backend?.close();
+      }
+    }
+  };
+}
+async function handleRunNetworkAction(platform, action, node, context) {
+  if (platform !== "extension") return null;
+  if (action === "app.network_assert") {
+    const assertion = await import("../library/actions/shared/app/network-assert.mjs");
+    return {
+      output: await assertion.assertNetwork({ action, node, context })
+    };
+  }
+  if (action !== "app.network_capture") return null;
+  const phase = String(node.phase ?? "").toLowerCase();
+  const id = String(node.id ?? "").trim();
+  if (!["start", "end"].includes(phase) || !id) {
+    throw new Error(
+      "app.network_capture requires phase=start|end and a non-empty id."
+    );
+  }
+  const session = sessions.get(path.resolve(context.artifactsDir));
+  if (!session?.backend) {
+    throw new Error(
+      `Extension network observation is unavailable: ${session?.setupError ?? "run observer was not started"}.`
+    );
+  }
+  if (phase === "start") {
+    const result = await session.backend.start(captureParams(id, node));
+    return {
+      output: {
+        action,
+        phase,
+        ...asRecord(result)
+      }
+    };
+  }
+  const artifactPath = String(
+    node.artifact_path ?? `network/${id}-summary.json`
+  );
+  const summary = await session.backend.end(id);
+  writeSummary(context.artifactsDir, artifactPath, summary);
+  return {
+    output: {
+      action,
+      phase,
+      ...summary
+    },
+    artifacts: [
+      {
+        path: artifactPath,
+        type: "report",
+        nodeId: context.nodeId
+      }
+    ]
+  };
+}
+async function createMobileNetworkBackend(target, env) {
+  const runtimeDir = env.RECIPE_RUNTIME_DIR ? path.resolve(target, env.RECIPE_RUNTIME_DIR) : path.join(target, "temp", "recipe", "runtime");
+  const socketPath = brokerSocketPath(runtimeDir);
+  const discoveryClient = await createBrokerClient(socketPath, "", 1e4);
+  const targets = await discoveryClient.control("list-targets", {}, 1e4);
+  discoveryClient.close();
+  const deviceId = selectMobileBrokerTarget(targets, env);
+  const client = await createBrokerClient(socketPath, deviceId, 1e4);
+  return {
+    start(params) {
+      return client.control("capture-start", params, 1e4);
+    },
+    async end(id) {
+      return asRecord(await client.control("capture-end", { id }, 1e4));
+    },
+    async close() {
+      client.close();
+    }
+  };
+}
+function selectMobileBrokerTarget(value, env) {
+  const targets = Array.isArray(value) ? value.map(asRecord).filter((target) => target.deviceId) : [];
+  const platform = String(
+    env.MM_HARNESS_EXPLICIT_PLATFORM ?? env.RECIPE_HARNESS_PLATFORM ?? ""
+  ).toLowerCase();
+  const pin = String(
+    platform === "android" ? env.ANDROID_TARGET_DEVICE_NAME ?? env.ANDROID_DEVICE ?? "" : platform === "ios" ? env.IOS_SIMULATOR ?? "" : env.IOS_SIMULATOR ?? env.ANDROID_TARGET_DEVICE_NAME ?? env.ANDROID_DEVICE ?? ""
+  ).trim();
+  const candidates = pin ? targets.filter(
+    (target) => String(target.name ?? "").toLowerCase().includes(pin.toLowerCase())
+  ) : targets;
+  if (candidates.length !== 1) {
+    throw new Error(
+      `Mobile network observation requires one broker target; found ${candidates.length}.`
+    );
+  }
+  return String(candidates[0].deviceId);
+}
+async function automaticSummary(session) {
+  let summary;
+  if (session.autoStarted && session.backend) {
+    try {
+      summary = await session.backend.end(AUTO_CAPTURE_ID);
+    } catch (error) {
+      summary = unavailableSummary(session.autoStartedAt, boundedError(error));
+    }
+  } else {
+    summary = unavailableSummary(
+      session.autoStartedAt,
+      session.setupError ?? "Network observer did not start."
+    );
+  }
+  const startedAt = Number(summary.startedAtEpochMs ?? session.autoStartedAt);
+  return {
+    ...summary,
+    nodeEvents: session.nodeEvents.map((event) => ({
+      action: event.action,
+      elapsedMs: Math.max(0, event.epochMs - startedAt),
+      nodeId: event.nodeId,
+      status: event.status
+    }))
+  };
+}
+function unavailableSummary(startedAtEpochMs, reason) {
+  return {
+    schemaVersion: 1,
+    id: AUTO_CAPTURE_ID,
+    status: "unavailable",
+    startedAtEpochMs,
+    endedAtEpochMs: Date.now(),
+    maxDurationMs: 60 * 60 * 1e3,
+    reconnects: 0,
+    droppedRequests: 0,
+    unavailableReasons: [reason],
+    coverageGapReasons: [],
+    uninspectableBodyRequests: 0,
+    projectedBodyFields: ["type"],
+    totalRequests: 0,
+    requestsByMethod: {},
+    requestsByHost: {},
+    requestsByType: {},
+    requests: []
+  };
+}
+function captureParams(id, node) {
+  return {
+    id,
+    urlIncludes: node.url_includes ?? [],
+    methods: node.methods ?? [],
+    bodyJsonFields: node.body_json_fields ?? [],
+    maxRequests: node.max_requests,
+    maxDurationMs: node.max_duration_ms
+  };
+}
+function writeSummary(artifactsDir, relativePath, summary) {
+  const destination = resolveArtifact(artifactsDir, relativePath);
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.writeFileSync(destination, `${JSON.stringify(summary, null, 2)}
+`);
+}
+function resolveArtifact(artifactsDir, relativePath) {
+  const root = path.resolve(artifactsDir);
+  const resolved = path.resolve(root, relativePath);
+  if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) {
+    throw new Error("Network artifact_path escapes artifactsDir.");
+  }
+  return resolved;
+}
+function indexArtifact(artifactManifestPath, relativePath, label) {
+  const manifest = asRecord(
+    JSON.parse(fs.readFileSync(artifactManifestPath, "utf8"))
+  );
+  const artifacts = Array.isArray(manifest.artifacts) ? manifest.artifacts.filter(
+    (artifact) => asRecord(artifact).path !== relativePath
+  ) : [];
+  artifacts.push({
+    path: relativePath,
+    type: "report",
+    label,
+    category: "diagnostic"
+  });
+  manifest.artifacts = artifacts;
+  fs.writeFileSync(
+    artifactManifestPath,
+    `${JSON.stringify(manifest, null, 2)}
+`
+  );
+}
+function extensionCdpPort(env) {
+  const port = Number(
+    env.CDP_PORT ?? env.RECIPE_CDP_PORT ?? process.env.CDP_PORT
+  );
+  if (!Number.isInteger(port) || port <= 0) {
+    throw new Error("Extension network observation requires CDP_PORT.");
+  }
+  return port;
+}
+function boundedError(error) {
+  return String(error instanceof Error ? error.message : error).slice(0, 256);
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+export {
+  handleRunNetworkAction,
+  startRunNetworkObservation
+};

package/docs/NETWORK-CAPTURE.md

@@ -0,0 +1,98 @@
+# Recipe-scoped network capture
+
+`app.network_capture` records HTTP requests between two Recipe Protocol v1 nodes without product instrumentation. Mobile uses its shared Hermes CDP broker; Extension uses one browser-level CDP observer across the extension page, service worker, and offscreen targets.
+
+```json
+{
+  "action": "app.network_capture",
+  "phase": "start",
+  "id": "perps-home",
+  "url_includes": ["api.hyperliquid.xyz/info"],
+  "methods": ["POST"],
+  "body_json_fields": ["type", "req.coin", "dex"],
+  "next": "exercise-flow"
+}
+```
+
+```json
+{
+  "action": "app.network_capture",
+  "phase": "end",
+  "id": "perps-home",
+  "artifact_path": "network/perps-home.json",
+  "next": "assert-network"
+}
+```
+
+```json
+{
+  "action": "app.network_assert",
+  "id": "perps-home",
+  "artifact_path": "network/perps-home.json",
+  "required_status": "complete",
+  "next": "done"
+}
+```
+
+The end node writes and indexes a JSON summary containing request totals, counts by method/host/retained body type, relative timestamps, reconnects, and dropped events.
+
+## Automatic run evidence
+
+Every live Mobile or Extension recipe run also writes `network/run-summary.json`. The automatic artifact is metadata-only and records:
+
+- method, host, sanitized path, elapsed time, and the safe top-level request `type` when present;
+- `running`, `passed`, and `failed` node-boundary events on the same elapsed-time axis;
+- completeness, reconnect, drop, and coverage-gap status.
+
+This makes requests between node boundaries inspectable without adding capture nodes to every recipe. Set `MM_HARNESS_AUTO_NETWORK_CAPTURE=0` only for observer-overhead comparisons or a runtime that intentionally forbids network inspection. Explicit `app.network_capture` windows remain the source for focused filters, assertions, and additional allowlisted body fields.
+
+## Status semantics
+
+- `complete`: the debugger target stayed attached and every retained event fit inside the configured cap.
+- `partial`: the target rotated/disconnected, the window exceeded `max_duration_ms`, events exceeded a retention bound, or a requested body field could not be inspected safely. Never interpret zero requests from a partial capture as proof of absence.
+- `unavailable`: the selected runtime rejected Network capture or no observer-owned target became available.
+
+Use `required_status`, `required_min_requests`, `required_max_requests`,
+`required_types`, and `forbidden_types` on a separate `app.network_assert`
+node. The end node is therefore recorded and its JSON artifact indexed before
+an assertion can fail. Absence assertions (`required_max_requests` and
+`forbidden_types`) require `required_status: "complete"`; partial or unavailable
+coverage cannot prove absence. Type assertions also require `type` in the start
+node's `body_json_fields`, so an unobserved discriminator cannot prove presence
+or absence.
+
+## Redaction
+
+- Query strings, request headers, response bodies, cookies, and authorization are never stored.
+- Request bodies are omitted unless `body_json_fields` explicitly allowlists bounded, non-sensitive primitive fields.
+- Field names containing address, account, user, token, secret, password, key, cookie, or authorization are rejected.
+- Each capture is capped at 4 MiB in addition to `max_requests`, which defaults
+  to 1,000 and is capped at 10,000.
+- `max_duration_ms` defaults to five minutes and is capped at one hour; at
+  most 16 windows may be active for one device.
+- The local broker socket is mode `0600`.
+
+## Runtime design
+
+Mobile uses one per-slot broker for console events, bridge commands, HUD actions, and Network events. The broker reconnects when Hermes rotates and marks active captures partial because events emitted while no target exists cannot be proven complete.
+
+Extension uses the browser CDP target to attach to every target owned by the loaded MetaMask extension. Target creation or removal re-enables Network collection and marks active captures partial when continuity cannot be proven.
+
+| Adapter | Automatic run artifact | Explicit window/assert | Raw interactive view |
+| --- | --- | --- | --- |
+| Mobile | Supported | Supported | React Native DevTools |
+| Extension | Supported | Supported | Chrome DevTools |
+| Core | Not applicable | Not declared | Not applicable |
+
+## Recipe v1 observation-window convention
+
+Observation capabilities use one lifecycle:
+
+1. start a bounded observer;
+2. execute ordinary recipe nodes;
+3. end the observer and index its artifact;
+4. assert the indexed artifact separately.
+
+Every observer reports `complete`, `partial`, or `unavailable`; a partial or unavailable window cannot prove absence. A future Mobile FPS/jank observer should reuse this lifecycle and node-boundary timeline, but no FPS action is advertised until its device overhead and metrics are validated.
+
+Local validation of the shared request processor measured about 1.6 microseconds of median CPU per retained request. Five real observer lifecycle samples measured 19.9 ms median on Mobile and 9.4 ms median on Extension; observed maxima were 117 ms and 192 ms. These are harness-overhead measurements, not product-network or UI latency claims.

package/docs/QA.md

@@ -124,6 +124,8 @@ mm-harness debug
 - [ ] Status matches verified product routes: `Login`/`LockScreen` are locked;
   `WalletView` is unlocked.
 - [ ] App and Metro logs are separate.
+- [ ] A restarted Metro rotates the previous `metro.log`, records its generation and retention actions in launch JSON, and classifies bundle failures only from the current log.
+- [ ] `mm-harness logs --full` preserves errors, completion, and meaningful timestamped bundle progress without repeated same-percentage module counts.
 - [ ] A JS edit rebuilds through Metro and appears after reload without a native
   rebuild; revert restores a clean tree.
 

package/docs/RECIPES.md

@@ -259,6 +259,16 @@ when repeated direct access has a stable cross-task contract.
 The protocol is authoritative:
 <https://farmslot.io/docs/reference/recipe-protocol-v1>.
 
+## Capture network requests
+
+Use `app.network_capture` start/end nodes to record redacted HTTP requests made
+inside one Mobile or Extension recipe window, then a separate
+`app.network_assert` node when the recipe needs self-checking evidence. Every
+live recipe also indexes a bounded metadata-only run summary with node-boundary
+events. The result distinguishes complete, partial, and unavailable evidence
+so a target rotation cannot be misreported as zero requests. See
+[Recipe-scoped network capture](NETWORK-CAPTURE.md).
+
 ## Share a library
 
 ```text

package/library/actions/mobile/app/network_assert.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { pathToFileURL } from 'node:url';
+
+import { assertNetwork } from '../../shared/app/network-assert.mjs';
+import { runAdapter } from '../platform/bridge.mjs';
+
+export { assertNetwork };
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  runAdapter(assertNetwork);
+}

package/library/actions/mobile/app/network_capture.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import {
+  bridgeCommand,
+  runAdapter,
+} from '../platform/bridge.mjs';
+import { resolveNetworkArtifact } from '../../shared/app/network-artifact.mjs';
+
+export async function captureNetwork(input) {
+  const node = input.node ?? {};
+  const phase = String(node.phase ?? '').toLowerCase();
+  const id = String(node.id ?? '').trim();
+  if (!['start', 'end'].includes(phase) || !id) {
+    throw new Error(
+      'app.network_capture requires phase=start|end and a non-empty id.',
+    );
+  }
+
+  if (phase === 'start') {
+    const result = await bridgeCommand(input, [
+      'network-capture-start',
+      JSON.stringify({
+        id,
+        urlIncludes: node.url_includes ?? [],
+        methods: node.methods ?? [],
+        bodyJsonFields: node.body_json_fields ?? [],
+        maxRequests: node.max_requests,
+        maxDurationMs: node.max_duration_ms,
+      }),
+    ]);
+    return { action: input.action, phase, ...result };
+  }
+
+  const artifactsDir = input.context?.artifactsDir;
+  if (!artifactsDir) {
+    throw new Error('app.network_capture requires artifactsDir.');
+  }
+  const artifactPath = String(
+    node.artifact_path ?? `network/${id}-summary.json`,
+  );
+  const artifactFile = resolveNetworkArtifact(artifactsDir, artifactPath);
+
+  const summary = await bridgeCommand(input, [
+    'network-capture-end',
+    JSON.stringify({ id }),
+  ]);
+  await mkdir(path.dirname(artifactFile), { recursive: true });
+  await writeFile(artifactFile, `${JSON.stringify(summary, null, 2)}\n`);
+
+  return {
+    action: input.action,
+    phase,
+    ...summary,
+    artifacts: [
+      {
+        path: artifactPath,
+        type: 'report',
+        nodeId: String(input.context?.nodeId ?? 'network-capture'),
+      },
+    ],
+  };
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  runAdapter(captureNetwork);
+}

package/library/actions/mobile/platform/bridge.mjs

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { constants as fsConstants } from 'node:fs';
+import { constants as fsConstants, existsSync } from 'node:fs';
 import { mkdir, mkdtemp, open, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { execFile, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
@@ -7,6 +7,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import bridgeErrors from '../../../../adapters/mobile/bridge-runtime/lib/bridge-errors.cjs';
+import brokerModule from '../../../../adapters/mobile/bridge-runtime/lib/cdp-broker.cjs';
 import { resolveMobileToolPath } from './tool-paths.mjs';
 
 const {
@@ -16,6 +17,7 @@ const {
   coded,
   parseErrorMarker,
 } = bridgeErrors;
+const { brokerSocketPath } = brokerModule;
 
 // Re-exported so the TS adapter classifies on the same code constants without a
 // second import path into the cjs bridge-runtime.
@@ -430,7 +432,10 @@ export async function bridgeCommand(input, args) {
   const script = bridgeScript(input);
   // bridgeEnv is async: it may call `adb getprop` to resolve the Metro device name.
   const env = await bridgeEnv(input);
-  if (adapterActionActive) {
+  const brokerSocket = brokerSocketPath(
+    path.dirname(resolveBridgeLockPath(input, env)),
+  );
+  if (adapterActionActive && !existsSync(brokerSocket)) {
     env.CDP_BRIDGE_LOCK_OWNER_PID = await acquireActionBridgeLock(input, env);
   }
   const result = await new Promise((resolve, reject) => {

package/library/actions/shared/app/network-artifact.mjs

@@ -0,0 +1,10 @@
+import path from 'node:path';
+
+export function resolveNetworkArtifact(artifactsDir, relativePath) {
+  const root = path.resolve(artifactsDir);
+  const resolved = path.resolve(root, relativePath);
+  if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) {
+    throw new Error('Network artifact_path escapes artifactsDir.');
+  }
+  return resolved;
+}

package/library/actions/shared/app/network-assert.mjs

@@ -0,0 +1,154 @@
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+
+import { resolveNetworkArtifact } from './network-artifact.mjs';
+
+export async function assertNetwork(input) {
+  const node = input.node ?? {};
+  const id = String(node.id ?? '').trim();
+  const artifactsDir = input.context?.artifactsDir;
+  if (!id || !artifactsDir) {
+    throw new Error('app.network_assert requires id and artifactsDir.');
+  }
+  const artifactPath = String(
+    node.artifact_path ?? `network/${id}-summary.json`,
+  );
+  const artifactFile = resolveNetworkArtifact(artifactsDir, artifactPath);
+  const handle = await open(
+    artifactFile,
+    constants.O_RDONLY | constants.O_NOFOLLOW,
+  );
+  let summary;
+  try {
+    const artifactStat = await handle.stat();
+    if (!artifactStat.isFile() || artifactStat.size > 5 * 1024 * 1024) {
+      throw new Error(
+        'app.network_assert summary is not a bounded regular file.',
+      );
+    }
+    summary = JSON.parse(await handle.readFile('utf8'));
+  } finally {
+    await handle.close();
+  }
+  validateSummary(summary, id);
+
+  const requiredStatus = node.required_status;
+  if (requiredStatus && summary.status !== requiredStatus) {
+    throw new Error(
+      `app.network_assert expected ${requiredStatus}, got ${summary.status}.`,
+    );
+  }
+  const requiredMinRequests = node.required_min_requests;
+  const requiredMaxRequests = node.required_max_requests;
+  const requiredTypes = node.required_types ?? [];
+  const forbiddenTypes = node.forbidden_types ?? [];
+  if (
+    (requiredTypes.length > 0 || forbiddenTypes.length > 0) &&
+    !summary.projectedBodyFields.includes('type')
+  ) {
+    throw new Error(
+      'app.network_assert type assertions require body_json_fields to include type.',
+    );
+  }
+  if (
+    (requiredMaxRequests !== undefined || forbiddenTypes.length > 0) &&
+    requiredStatus !== 'complete'
+  ) {
+    throw new Error(
+      'app.network_assert negative assertions require required_status=complete.',
+    );
+  }
+  for (const [name, value] of [
+    ['required_min_requests', requiredMinRequests],
+    ['required_max_requests', requiredMaxRequests],
+  ]) {
+    if (value !== undefined && (!Number.isInteger(value) || value < 0)) {
+      throw new Error(`app.network_assert ${name} is invalid.`);
+    }
+  }
+  if (
+    Number.isInteger(requiredMinRequests) &&
+    Number.isInteger(requiredMaxRequests) &&
+    requiredMinRequests > requiredMaxRequests
+  ) {
+    throw new Error('app.network_assert request assertion range is invalid.');
+  }
+  if (
+    Number.isInteger(requiredMinRequests) &&
+    summary.totalRequests < requiredMinRequests
+  ) {
+    throw new Error(
+      `app.network_assert expected at least ${requiredMinRequests} request(s), got ${summary.totalRequests}.`,
+    );
+  }
+  if (
+    Number.isInteger(requiredMaxRequests) &&
+    summary.totalRequests > requiredMaxRequests
+  ) {
+    throw new Error(
+      `app.network_assert expected at most ${requiredMaxRequests} request(s), got ${summary.totalRequests}.`,
+    );
+  }
+  for (const type of requiredTypes) {
+    if (!hasPositiveOwnCount(summary.requestsByType, type)) {
+      throw new Error(`app.network_assert did not observe required type ${type}.`);
+    }
+  }
+  for (const type of forbiddenTypes) {
+    if (hasPositiveOwnCount(summary.requestsByType, type)) {
+      throw new Error(`app.network_assert observed forbidden type ${type}.`);
+    }
+  }
+
+  return {
+    action: input.action,
+    id,
+    artifactPath,
+    status: summary.status,
+    totalRequests: summary.totalRequests,
+  };
+}
+
+function hasPositiveOwnCount(counts, key) {
+  return (
+    Object.hasOwn(counts, key) &&
+    Number.isInteger(counts[key]) &&
+    counts[key] > 0
+  );
+}
+
+function validateSummary(summary, expectedId) {
+  if (
+    !summary ||
+    typeof summary !== 'object' ||
+    Array.isArray(summary) ||
+    summary.schemaVersion !== 1 ||
+    summary.id !== expectedId ||
+    !['complete', 'partial', 'unavailable'].includes(summary.status) ||
+    !Number.isInteger(summary.totalRequests) ||
+    summary.totalRequests < 0 ||
+    !Array.isArray(summary.requests) ||
+    summary.requests.length !== summary.totalRequests ||
+    !Number.isInteger(summary.uninspectableBodyRequests) ||
+    summary.uninspectableBodyRequests < 0 ||
+    !Array.isArray(summary.projectedBodyFields) ||
+    summary.projectedBodyFields.some((field) => typeof field !== 'string') ||
+    !summary.requestsByType ||
+    typeof summary.requestsByType !== 'object' ||
+    Array.isArray(summary.requestsByType)
+  ) {
+    throw new Error('app.network_assert summary contract is invalid.');
+  }
+  const typeCounts = Object.values(summary.requestsByType);
+  for (const count of typeCounts) {
+    if (!Number.isInteger(count) || count < 1) {
+      throw new Error('app.network_assert summary type counts are invalid.');
+    }
+  }
+  if (
+    typeCounts.reduce((total, count) => total + count, 0) !==
+    summary.totalRequests
+  ) {
+    throw new Error('app.network_assert summary type counts are inconsistent.');
+  }
+}