@powerhousedao/switchboard 6.2.3-dev.4 → 6.2.3-dev.41

package/test/renown-trust-policy.test.ts

@@ -0,0 +1,315 @@
+import type {
+  ActionSigner,
+  ISigner,
+} from "@powerhousedao/shared/document-model";
+import {
+  ReactorBuilder,
+  ReactorClientBuilder,
+  type SignatureTrustPolicy,
+} from "@powerhousedao/reactor";
+import type { IRenown } from "@renown/sdk/node";
+import { existsSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { applySwitchboardReactorDefaults } from "../src/builder-defaults.mjs";
+import {
+  assertWorkerTrustPolicy,
+  getRenownTrustPolicyConfig,
+} from "../src/renown.js";
+
+const WALLET = "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266";
+const CONNECT_KEY = "did:key:zDnaeConnectKey";
+const SWITCHBOARD_KEY = "did:key:zDnaeSwitchboardKey";
+const SWITCHBOARD_USER = {
+  address: "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
+  networkId: "eip155",
+  chainId: 1,
+};
+const GRAPHQL = "http://renown.test/graphql";
+
+// Signed by WALLET's Anvil dev key; its expiry is ignored by the policy.
+const CREDENTIAL_ROW = {
+  documentId: "doc-cred",
+  credentialId: "urn:uuid:c7882913-68ef-48e5-9e89-f2948d2ca22c",
+  context: ["https://www.w3.org/2018/credentials/v1"],
+  type: ["VerifiableCredential", "RenownCredential"],
+  issuerId: "did:pkh:eip155:1:0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
+  issuerEthereumAddress: WALLET,
+  issuanceDate: "2026-09-24T00:48:25.566Z",
+  expirationDate: "2026-10-01T00:48:25.566Z",
+  credentialSubjectId: CONNECT_KEY,
+  credentialSubjectApp: "connect",
+  credentialStatusId: null,
+  credentialStatusType: null,
+  credentialSchemaId: "https://renown.id/schemas/renown-credential/v1",
+  credentialSchemaType: "JsonSchemaValidator2018",
+  proofVerificationMethod:
+    "did:pkh:eip155:1:0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
+  proofEthereumAddress: WALLET,
+  proofCreated: "2026-09-24T00:48:25.566Z",
+  proofPurpose: "assertionMethod",
+  proofType: "EthereumEip712Signature2021",
+  proofValue:
+    "0xe8d7a2468b9eb21286483fd88601d350ac7a8ed908506e51a34c6b119f93a7d75c6284a3f231698f6fcc8a3ad0ec5096a34811c7b6adef2d1e4146ddb22826a91c",
+  proofEip712Domain: JSON.stringify({ version: "1", chainId: 1 }),
+  proofEip712PrimaryType: "VerifiableCredential",
+  revoked: false,
+};
+
+function stubRenown(user: ActionSigner["user"] = SWITCHBOARD_USER): IRenown {
+  const signer = {
+    user,
+    app: { name: "switchboard", key: SWITCHBOARD_KEY },
+  } as unknown as ISigner;
+  return { signer } as unknown as IRenown;
+}
+
+function claim(address: string, key: string): ActionSigner {
+  return {
+    user: { address, networkId: "eip155", chainId: 1 },
+    app: { name: "connect", key },
+    signatures: [],
+  };
+}
+
+/** Answers the renown read model with `rows`; counts the requests. */
+function mockReadModel(rows: unknown[] = [CREDENTIAL_ROW]) {
+  return vi.spyOn(globalThis, "fetch").mockImplementation(() =>
+    Promise.resolve(
+      new Response(JSON.stringify({ data: { renownCredentials: rows } }), {
+        status: 200,
+      }),
+    ),
+  );
+}
+
+async function remotePolicy(
+  renown = stubRenown(),
+): Promise<SignatureTrustPolicy> {
+  const { trustPolicy } = await getRenownTrustPolicyConfig(
+    { source: "remote", switchboardUrl: GRAPHQL },
+    renown,
+  );
+  return trustPolicy!;
+}
+
+describe("getRenownTrustPolicyConfig", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it("accepts a key a credential binds to the claimed wallet", async () => {
+    const fetchMock = mockReadModel();
+    const policy = await remotePolicy();
+
+    await expect(
+      policy.authorizeSigner(claim(WALLET, CONNECT_KEY), CONNECT_KEY, "doc"),
+    ).resolves.toBe(true);
+    expect(fetchMock.mock.calls[0][0]).toBe(GRAPHQL);
+  });
+
+  it("refuses a mismatched address or key", async () => {
+    mockReadModel();
+    const policy = await remotePolicy();
+
+    await expect(
+      policy.authorizeSigner(
+        claim(SWITCHBOARD_USER.address, CONNECT_KEY),
+        CONNECT_KEY,
+        "doc",
+      ),
+    ).resolves.toBe(false);
+    await expect(
+      policy.authorizeSigner(
+        claim(WALLET, "did:key:zDnaeOther"),
+        "did:key:zDnaeOther",
+        "doc",
+      ),
+    ).resolves.toBe(false);
+  });
+
+  it("refuses a key no credential binds yet", async () => {
+    const fetchMock = mockReadModel([]);
+    const policy = await remotePolicy();
+
+    await expect(
+      policy.authorizeSigner(claim(WALLET, CONNECT_KEY), CONNECT_KEY, "doc"),
+    ).resolves.toBe(false);
+    await expect(
+      policy.authorizeSigner(claim(WALLET, CONNECT_KEY), CONNECT_KEY, "doc"),
+    ).resolves.toBe(false);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("caches an acceptance per (address, key)", async () => {
+    const fetchMock = mockReadModel();
+    const policy = await remotePolicy();
+    const signer = claim(WALLET, CONNECT_KEY);
+
+    await policy.authorizeSigner(signer, CONNECT_KEY, "doc-1");
+    fetchMock.mockRejectedValue(new TypeError("offline"));
+
+    await expect(
+      policy.authorizeSigner(signer, CONNECT_KEY, "doc-2"),
+    ).resolves.toBe(true);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("throws on a network failure rather than refusing", async () => {
+    vi.spyOn(globalThis, "fetch").mockRejectedValue(new TypeError("offline"));
+    const policy = await remotePolicy();
+
+    await expect(
+      policy.authorizeSigner(claim(WALLET, CONNECT_KEY), CONNECT_KEY, "doc"),
+    ).rejects.toThrow("offline");
+  });
+
+  it("accepts the switchboard's own key for its own user without a lookup", async () => {
+    const fetchMock = mockReadModel([]);
+    const policy = await remotePolicy();
+
+    await expect(
+      policy.authorizeSigner(
+        claim(SWITCHBOARD_USER.address, SWITCHBOARD_KEY),
+        SWITCHBOARD_KEY,
+        "doc",
+      ),
+    ).resolves.toBe(true);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("matches the switchboard's own key against its current user", async () => {
+    const fetchMock = mockReadModel([]);
+    const renown = stubRenown();
+    const policy = await remotePolicy(renown);
+
+    renown.signer.user = { address: WALLET, networkId: "eip155", chainId: 1 };
+
+    await expect(
+      policy.authorizeSigner(
+        claim(WALLET, SWITCHBOARD_KEY),
+        SWITCHBOARD_KEY,
+        "doc",
+      ),
+    ).resolves.toBe(true);
+    expect(fetchMock).not.toHaveBeenCalled();
+    await expect(
+      policy.authorizeSigner(
+        claim(SWITCHBOARD_USER.address, SWITCHBOARD_KEY),
+        SWITCHBOARD_KEY,
+        "doc",
+      ),
+    ).resolves.toBe(false);
+  });
+
+  it("gives pooled workers a spec that builds the same policy", async () => {
+    const fetchMock = mockReadModel();
+    const { workerTrustPolicy } = await getRenownTrustPolicyConfig(
+      { source: "remote", switchboardUrl: GRAPHQL },
+      stubRenown(),
+    );
+
+    const module = workerTrustPolicy!.module;
+    expect(module.exportName).toBe("createRenownTrustPolicy");
+    const filePath = "filePath" in module ? module.filePath : "";
+    expect(existsSync(filePath)).toBe(true);
+    expect(workerTrustPolicy!.initArgs).toEqual({
+      switchboard: GRAPHQL,
+      self: { key: SWITCHBOARD_KEY, user: SWITCHBOARD_USER },
+    });
+
+    const imported = (await import(pathToFileURL(filePath).href)) as Record<
+      string,
+      (args: unknown) => SignatureTrustPolicy
+    >;
+    const policy = imported[module.exportName](workerTrustPolicy!.initArgs);
+    await expect(
+      policy.authorizeSigner(claim(WALLET, CONNECT_KEY), CONNECT_KEY, "doc"),
+    ).resolves.toBe(true);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("reads a self source in process and gives workers no spec", async () => {
+    const request = vi.fn(() =>
+      Promise.resolve({ renownCredentials: [CREDENTIAL_ROW] }),
+    );
+    const config = await getRenownTrustPolicyConfig(
+      { source: "self", request },
+      null,
+    );
+
+    expect(config.workerTrustPolicy).toBeUndefined();
+    await expect(
+      config.trustPolicy!.authorizeSigner(
+        claim(WALLET, CONNECT_KEY),
+        CONNECT_KEY,
+        "doc",
+      ),
+    ).resolves.toBe(true);
+    expect(request).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("assertWorkerTrustPolicy", () => {
+  it("fails with workers, authEnforcement and a self source", () => {
+    expect(() =>
+      assertWorkerTrustPolicy({
+        workers: 2,
+        authEnforcement: true,
+        renownSource: "self",
+      }),
+    ).toThrow(
+      /REACTOR_WORKERS[\s\S]*REACTOR_AUTH_ENFORCEMENT[\s\S]*RENOWN_SOURCE/,
+    );
+  });
+
+  it.each([
+    { workers: 0, authEnforcement: true, renownSource: "self" as const },
+    { workers: 2, authEnforcement: false, renownSource: "self" as const },
+    { workers: 2, authEnforcement: true, renownSource: "remote" as const },
+  ])("passes %o", (config) => {
+    expect(() => assertWorkerTrustPolicy(config)).not.toThrow();
+  });
+});
+
+describe("applySwitchboardReactorDefaults with a trust policy", () => {
+  it("gives the reactor the policy and its worker spec", () => {
+    const reactorBuilder = new ReactorBuilder();
+    const withTrustPolicy = vi.spyOn(reactorBuilder, "withTrustPolicy");
+    const trustPolicy: SignatureTrustPolicy = {
+      authorizeSigner: () => Promise.resolve(true),
+    };
+    const workerTrustPolicy = {
+      module: { filePath: "/trust.js", exportName: "createTrustPolicy" },
+    };
+
+    applySwitchboardReactorDefaults(
+      reactorBuilder,
+      new ReactorClientBuilder(),
+      {
+        includeBaseModels: false,
+        signalHandlers: false,
+        trustPolicy: { trustPolicy, workerTrustPolicy },
+      },
+    );
+
+    expect(withTrustPolicy).toHaveBeenCalledWith(
+      trustPolicy,
+      workerTrustPolicy,
+    );
+    expect(reactorBuilder.hasTrustPolicy()).toBe(true);
+  });
+
+  it("leaves the reactor on the default without one", () => {
+    const reactorBuilder = new ReactorBuilder();
+
+    applySwitchboardReactorDefaults(
+      reactorBuilder,
+      new ReactorClientBuilder(),
+      {
+        includeBaseModels: false,
+        signalHandlers: false,
+      },
+    );
+
+    expect(reactorBuilder.hasTrustPolicy()).toBe(false);
+  });
+});

package/test/unsupported-stored-documents.test.ts

@@ -0,0 +1,72 @@
+import { UnsupportedStoredProtocolError } from "@powerhousedao/reactor";
+import { describe, expect, it } from "vitest";
+import {
+  StoredDocumentsRefusedError,
+  resolveUnsupportedStoredDocuments,
+} from "../src/unsupported-stored-documents.mjs";
+
+describe("resolveUnsupportedStoredDocuments", () => {
+  it("refuses by default", () => {
+    expect(resolveUnsupportedStoredDocuments(undefined, {})).toBe("refuse");
+    expect(
+      resolveUnsupportedStoredDocuments(undefined, {
+        REACTOR_UNSUPPORTED_STORED_DOCUMENTS: " ",
+      }),
+    ).toBe("refuse");
+  });
+
+  it("reads REACTOR_UNSUPPORTED_STORED_DOCUMENTS", () => {
+    expect(
+      resolveUnsupportedStoredDocuments(undefined, {
+        REACTOR_UNSUPPORTED_STORED_DOCUMENTS: " read-only ",
+      }),
+    ).toBe("read-only");
+    expect(
+      resolveUnsupportedStoredDocuments(undefined, {
+        REACTOR_UNSUPPORTED_STORED_DOCUMENTS: "refuse",
+      }),
+    ).toBe("refuse");
+  });
+
+  it("lets the option win over the env var", () => {
+    expect(
+      resolveUnsupportedStoredDocuments("refuse", {
+        REACTOR_UNSUPPORTED_STORED_DOCUMENTS: "read-only",
+      }),
+    ).toBe("refuse");
+  });
+
+  it("refuses an unknown value", () => {
+    expect(() =>
+      resolveUnsupportedStoredDocuments(undefined, {
+        REACTOR_UNSUPPORTED_STORED_DOCUMENTS: "readonly",
+      }),
+    ).toThrow(
+      'REACTOR_UNSUPPORTED_STORED_DOCUMENTS must be "refuse" or "read-only", got "readonly"',
+    );
+  });
+});
+
+describe("StoredDocumentsRefusedError", () => {
+  it("names the versions, the count and both ways forward", () => {
+    const cause = new UnsupportedStoredProtocolError(
+      [
+        { protocol: "base-reducer", version: 3 },
+        { protocol: "base-reducer", version: 7 },
+      ],
+      4,
+    );
+
+    const error = new StoredDocumentsRefusedError(cause);
+
+    expect(error.message).toBe(
+      "Refusing to start: 4 stored document(s) require base-reducer 3, base-reducer 7, which this switchboard does not run. " +
+        "Either start a switchboard build that runs base-reducer 3, base-reducer 7, or set REACTOR_UNSUPPORTED_STORED_DOCUMENTS=read-only to start with those documents read-only.",
+    );
+    expect(error.documents).toBe(4);
+    expect(error.versions).toBe(cause.versions);
+    expect(error.cause).toBe(cause);
+    expect(StoredDocumentsRefusedError.isError(error)).toBe(true);
+    expect(StoredDocumentsRefusedError.isError(cause)).toBe(false);
+  });
+});

package/test/workflow/harness.ts

@@ -0,0 +1,289 @@
+// Shared harness: the suites go over a real socket through the reactor's own
+// adapter, route service and webhook service, which the unit tests cannot.
+import {
+  createHttpAdapter,
+  getDbClient,
+  HttpRouteService,
+  MemoryWebhookStore,
+  WebhookService,
+} from "@powerhousedao/reactor-api";
+import {
+  createWorkflowRuntime,
+  type WorkflowRuntimeService,
+} from "@powerhousedao/reactor-workflow";
+import {
+  createRelationalDb,
+  type IRelationalDb,
+} from "@powerhousedao/shared/processors";
+import type { OperationWithContext } from "document-model";
+import type { Kysely } from "kysely";
+import { vi } from "vitest";
+import {
+  CORE_PIECE_NAME,
+  CORE_PIECE_VERSION,
+} from "@powerhousedao/reactor-workflow";
+
+export const WORKFLOW_TYPE = "powerhouse/workflow";
+export const PACKAGE_NAME = "@powerhousedao/workflow";
+/** A ref the harness's secret store resolves; anything else rejects. */
+export const SECRET_REF = "secret://v1:00112233445566778899aabbccddeeff";
+export const SECRET = "s3cret";
+// Minting an endpoint is a read of the workflow, so the harness asks as one.
+const CALLER = { headers: {}, db: {}, user: { address: "0xabc" } } as never;
+
+export interface FiredRun {
+  workflowId: string;
+  payload: unknown;
+  kind: string;
+}
+
+export interface TriggerFields {
+  pieceName: string;
+  pieceVersion: string;
+  triggerName: string;
+}
+
+// The core piece's webhook trigger, pinned to the installed core piece.
+export const WEBHOOK_TRIGGER: TriggerFields = {
+  pieceName: CORE_PIECE_NAME,
+  pieceVersion: CORE_PIECE_VERSION,
+  triggerName: "webhook",
+};
+
+export interface WebhookHost {
+  /** Origin the endpoint is served from, e.g. `http://127.0.0.1:53124`. */
+  readonly url: string;
+  /** Runs the trigger started, in order. Cleared by `arm`. */
+  readonly fired: FiredRun[];
+  readonly service: WorkflowRuntimeService;
+  /** Publishes an ENABLED workflow with `config`; returns its endpoint. */
+  arm(
+    config: Record<string, unknown>,
+    options?: { trigger?: TriggerFields; workflowId?: string },
+  ): Promise<{ token: string; url: string }>;
+  /** Publishes the same workflow as DISABLED, keeping its endpoint row. */
+  disarm(workflowId?: string): Promise<void>;
+  /** Deletes the workflow document, as the reactor reports it. */
+  remove(workflowId?: string): Promise<void>;
+  /** Whether the reactor's webhook store still holds this token. */
+  hasToken(token: string): Promise<boolean>;
+  /** The policy the service hands the reactor for one endpoint. */
+  policyFor(workflowId?: string): Promise<unknown>;
+  deliver(
+    token: string,
+    init?: {
+      method?: string;
+      headers?: Record<string, string>;
+      body?: string;
+      query?: Record<string, string>;
+    },
+  ): Promise<Response>;
+  stop(): Promise<void>;
+}
+
+export const DEFAULT_WORKFLOW = "wf-integration";
+
+// Module-scoped: the service ignores any ordinal at or below the highest it
+// has seen, so a per-host counter would make a file's second host see nothing.
+let ordinal = 0;
+
+export function workflowOperation(
+  state: Record<string, unknown>,
+  workflowId = DEFAULT_WORKFLOW,
+): OperationWithContext {
+  ordinal += 1;
+  return {
+    operation: {
+      index: ordinal,
+      timestampUtcMs: `${ordinal}`,
+      action: { type: "SET_WORKFLOW_NAME", input: {} },
+      resultingState: JSON.stringify(state),
+    },
+    context: {
+      documentId: workflowId,
+      documentType: WORKFLOW_TYPE,
+      scope: "global",
+      branch: "main",
+      ordinal,
+    },
+  } as unknown as OperationWithContext;
+}
+
+// `publicUrl` is known only after `listen`: a family registered against the
+// wrong origin advertises URLs no caller can reach.
+export async function startWebhookHost(
+  options: {
+    fire?: (run: FiredRun) => unknown;
+    // Reads and writes of the workflow documents; none by default.
+    reactorClient?: unknown;
+  } = {},
+): Promise<WebhookHost> {
+  // The public factory, not the adapter class: the class is internal, so
+  // constructing it would test a path no consumer can take.
+  const { adapter } = await createHttpAdapter("express");
+  adapter.setupMiddleware({});
+  const server = await adapter.listen(0, undefined, "127.0.0.1");
+  const { port } = server.address() as { port: number };
+  const url = `http://127.0.0.1:${port}`;
+
+  const webhookStore = new MemoryWebhookStore();
+  const webhooks = new WebhookService({ store: webhookStore });
+  const routes = new HttpRouteService({
+    httpAdapter: adapter,
+    webhooks,
+    publicUrl: url,
+  });
+  // Core serves the endpoint family from its own host scope, exactly as the
+  // reactor wires it: nothing here touches the adapter directly.
+  webhooks.attach(routes.hostScope("@powerhousedao/reactor-api", "/webhooks"));
+
+  const { db } = getDbClient();
+  const fired: FiredRun[] = [];
+
+  // Every host surface the runtime asks for, and nothing it does not: no run
+  // here reaches the reactor, and the secret store answers one fixed ref.
+  const service = createWorkflowRuntime({
+    relationalDb: createRelationalDb(
+      db as unknown as Kysely<unknown>,
+    ) as IRelationalDb,
+    reactorClient: options.reactorClient ?? {
+      get: () => Promise.reject(new Error("not used")),
+      find: () => Promise.resolve({ results: [] }),
+    },
+    assertCanRead: () => Promise.resolve(undefined),
+    assertCanWrite: () => Promise.resolve(undefined),
+    webhooks: routes.scopeFor(PACKAGE_NAME).webhooks,
+    secrets: {
+      get: (ref: string) =>
+        ref === SECRET_REF
+          ? Promise.resolve(SECRET)
+          : Promise.reject(new Error(`No secret found for ref "${ref}"`)),
+    },
+  } as never);
+  vi.spyOn(service, "fire").mockImplementation(
+    (workflowId: string, payload?: unknown, kind = "manual") => {
+      const run = { workflowId, payload, kind };
+      fired.push(run);
+      const outcome = options.fire?.(run);
+      return Promise.resolve(
+        (outcome ?? {
+          runId: `run-${fired.length}`,
+          status: "SUCCEEDED",
+          steps: [],
+        }) as never,
+      );
+    },
+  );
+
+  await service.registerWebhookEndpoint();
+
+  const publish = async (
+    config: Record<string, unknown>,
+    status: string,
+    trigger: TriggerFields,
+    workflowId: string,
+  ) => {
+    await service.onOperations([
+      workflowOperation(
+        {
+          name: "Integration",
+          status,
+          version: ordinal + 1,
+          trigger: { id: "t1", ...trigger, config },
+          steps: [],
+          edges: [],
+          variables: [],
+        },
+        workflowId,
+      ),
+    ]);
+  };
+
+  return {
+    url,
+    fired,
+    service,
+    async arm(config, opts = {}) {
+      const workflowId = opts.workflowId ?? DEFAULT_WORKFLOW;
+      // The runtime requires a scheme; an unsigned suite names "none".
+      await publish(
+        { scheme: "none", ...config },
+        "ENABLED",
+        opts.trigger ?? WEBHOOK_TRIGGER,
+        workflowId,
+      );
+      const endpoint = await service.webhookEndpoint(workflowId, CALLER);
+      if (!endpoint) throw new Error(`No endpoint minted for ${workflowId}`);
+      fired.length = 0;
+      return {
+        url: endpoint.url,
+        token: endpoint.url.slice(endpoint.url.lastIndexOf("/") + 1),
+      };
+    },
+    async disarm(workflowId = DEFAULT_WORKFLOW) {
+      await publish({}, "DISABLED", WEBHOOK_TRIGGER, workflowId);
+    },
+    async remove(workflowId = DEFAULT_WORKFLOW) {
+      ordinal += 1;
+      await service.onOperations([
+        {
+          operation: {
+            index: ordinal,
+            timestampUtcMs: `${ordinal}`,
+            action: {
+              type: "DELETE_DOCUMENT",
+              input: { documentId: workflowId },
+            },
+          },
+          context: {
+            documentId: workflowId,
+            documentType: WORKFLOW_TYPE,
+            scope: "document",
+            branch: "main",
+            ordinal,
+          },
+        } as unknown as OperationWithContext,
+      ]);
+    },
+    async hasToken(token) {
+      return (await webhookStore.find(token)) !== undefined;
+    },
+    policyFor(workflowId = DEFAULT_WORKFLOW) {
+      return service.webhookPolicy(workflowId);
+    },
+    deliver(token, init = {}) {
+      const query = init.query
+        ? `?${new URLSearchParams(init.query).toString()}`
+        : "";
+      return fetch(`${url}/webhooks/${token}${query}`, {
+        method: init.method ?? "POST",
+        headers: init.headers,
+        body: init.body,
+      });
+    },
+    stop() {
+      return new Promise<void>((resolve, reject) =>
+        server.close((error) => (error ? reject(error) : resolve())),
+      );
+    },
+  };
+}
+
+// A delivery is answered before its run starts, so asserting on `fired`
+// straight after a 202 is a race that passes for the wrong reason.
+export async function waitForRuns(
+  host: WebhookHost,
+  count: number,
+  timeoutMs = 2000,
+): Promise<FiredRun[]> {
+  const deadline = Date.now() + timeoutMs;
+  while (host.fired.length < count && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+  if (host.fired.length < count) {
+    throw new Error(
+      `Expected ${count} run(s), saw ${host.fired.length} within ${timeoutMs}ms`,
+    );
+  }
+  return host.fired;
+}