@powerhousedao/switchboard 6.2.3-dev.30 → 6.2.3-dev.31

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@powerhousedao/switchboard",
   "type": "module",
-  "version": "6.2.3-dev.30",
+  "version": "6.2.3-dev.31",
   "main": "dist/index.mjs",
   "exports": {
     ".": {
@@ -41,7 +41,7 @@
     "@openfeature/core": "1.9.1",
     "@openfeature/env-var-provider": "0.3.1",
     "@openfeature/server-sdk": "1.19.0",
-    "@powerhousedao/config": "6.2.3-dev.30",
+    "@powerhousedao/config": "6.2.3-dev.31",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.218.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",
@@ -55,22 +55,22 @@
     "@opentelemetry/sdk-node": "^0.218.0",
     "@opentelemetry/sdk-trace-base": "^2.7.1",
     "@opentelemetry/semantic-conventions": "^1.41.1",
-    "@powerhousedao/opentelemetry-instrumentation-reactor": "6.2.3-dev.30",
-    "@powerhousedao/reactor": "6.2.3-dev.30",
-    "@powerhousedao/shared": "6.2.3-dev.30",
-    "@powerhousedao/vetra": "6.2.3-dev.30",
-    "@powerhousedao/reactor-api": "6.2.3-dev.30",
-    "@powerhousedao/reactor-attachments": "6.2.3-dev.30",
-    "@powerhousedao/reactor-drive": "6.2.3-dev.30",
-    "@powerhousedao/reactor-group": "6.2.3-dev.30",
-    "@powerhousedao/reactor-workflow": "6.2.3-dev.30",
-    "@powerhousedao/workflow": "6.2.3-dev.30",
-    "@powerhousedao/pglite-fs": "6.2.3-dev.30",
+    "@powerhousedao/opentelemetry-instrumentation-reactor": "6.2.3-dev.31",
+    "@powerhousedao/reactor": "6.2.3-dev.31",
+    "@powerhousedao/shared": "6.2.3-dev.31",
+    "@powerhousedao/vetra": "6.2.3-dev.31",
+    "@powerhousedao/reactor-api": "6.2.3-dev.31",
+    "@powerhousedao/reactor-attachments": "6.2.3-dev.31",
+    "@powerhousedao/reactor-drive": "6.2.3-dev.31",
+    "@powerhousedao/reactor-group": "6.2.3-dev.31",
+    "@powerhousedao/reactor-workflow": "6.2.3-dev.31",
+    "@powerhousedao/workflow": "6.2.3-dev.31",
+    "@powerhousedao/pglite-fs": "6.2.3-dev.31",
     "@pyroscope/nodejs": "^0.4.5",
-    "@renown/sdk": "6.2.3-dev.30",
+    "@renown/sdk": "6.2.3-dev.31",
     "@sentry/node": "^10.53.1",
     "@sentry/opentelemetry": "^10.53.1",
-    "document-model": "6.2.3-dev.30",
+    "document-model": "6.2.3-dev.31",
     "dotenv": "^16.4.7",
     "express": "^4.22.1",
     "graphql": "^16",

package/test/workflow/harness.ts

@@ -18,6 +18,10 @@ import {
 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";
@@ -33,6 +37,19 @@ export interface FiredRun {
   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;
@@ -42,10 +59,14 @@ export interface WebhookHost {
   /** Publishes an ENABLED workflow with `config`; returns its endpoint. */
   arm(
     config: Record<string, unknown>,
-    options?: { blockType?: string; workflowId?: string },
+    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(
@@ -91,7 +112,11 @@ export function workflowOperation(
 // `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 } = {},
+  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.
@@ -101,7 +126,8 @@ export async function startWebhookHost(
   const { port } = server.address() as { port: number };
   const url = `http://127.0.0.1:${port}`;
 
-  const webhooks = new WebhookService({ store: new MemoryWebhookStore() });
+  const webhookStore = new MemoryWebhookStore();
+  const webhooks = new WebhookService({ store: webhookStore });
   const routes = new HttpRouteService({
     httpAdapter: adapter,
     webhooks,
@@ -120,7 +146,7 @@ export async function startWebhookHost(
     relationalDb: createRelationalDb(
       db as unknown as Kysely<unknown>,
     ) as IRelationalDb,
-    reactorClient: {
+    reactorClient: options.reactorClient ?? {
       get: () => Promise.reject(new Error("not used")),
       find: () => Promise.resolve({ results: [] }),
     },
@@ -154,7 +180,7 @@ export async function startWebhookHost(
   const publish = async (
     config: Record<string, unknown>,
     status: string,
-    blockType: string,
+    trigger: TriggerFields,
     workflowId: string,
   ) => {
     await service.onOperations([
@@ -163,7 +189,7 @@ export async function startWebhookHost(
           name: "Integration",
           status,
           version: ordinal + 1,
-          trigger: { id: "t1", blockType, config },
+          trigger: { id: "t1", ...trigger, config },
           steps: [],
           edges: [],
           variables: [],
@@ -179,10 +205,11 @@ export async function startWebhookHost(
     service,
     async arm(config, opts = {}) {
       const workflowId = opts.workflowId ?? DEFAULT_WORKFLOW;
+      // The runtime requires a scheme; an unsigned suite names "none".
       await publish(
-        config,
+        { scheme: "none", ...config },
         "ENABLED",
-        opts.blockType ?? "core#webhook",
+        opts.trigger ?? WEBHOOK_TRIGGER,
         workflowId,
       );
       const endpoint = await service.webhookEndpoint(workflowId, CALLER);
@@ -194,7 +221,32 @@ export async function startWebhookHost(
       };
     },
     async disarm(workflowId = DEFAULT_WORKFLOW) {
-      await publish({}, "DISABLED", "core#webhook", workflowId);
+      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);

package/test/workflow/oauth.test.ts

@@ -0,0 +1,214 @@
+// The OAuth2 callback over a real socket through the reactor's route service,
+// and what startOAuth accepts as a redirect and a return URL.
+import {
+  createHttpAdapter,
+  HttpRouteService,
+  type Context,
+  type IAuthorizationService,
+} from "@powerhousedao/reactor-api";
+import type { WorkflowRuntimeService } from "@powerhousedao/reactor-workflow";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import {
+  callbackUrlOf,
+  registerOAuthCallback,
+} from "../../src/workflow/oauth-callback.js";
+import { getResolvers } from "../../src/workflow/resolvers.js";
+
+const PACKAGE_NAME = "@powerhousedao/workflow";
+
+type Resolver = (
+  parent: unknown,
+  args: unknown,
+  ctx: Context,
+) => Promise<unknown>;
+
+describe("the OAuth2 callback route", () => {
+  let url: string;
+  let callbackUrl: string;
+  const completeOAuth = vi.fn();
+  let close: () => Promise<void>;
+
+  beforeAll(async () => {
+    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 };
+    url = `http://127.0.0.1:${port}`;
+    const routes = new HttpRouteService({
+      httpAdapter: adapter,
+      publicUrl: url,
+    });
+    const scope = routes.scopeFor(PACKAGE_NAME);
+    registerOAuthCallback(scope, { completeOAuth } as never);
+    callbackUrl = callbackUrlOf(scope);
+    close = () => new Promise((done) => server.close(() => done()));
+  });
+
+  afterAll(() => close());
+
+  it("lives under the workflow package's namespace", () => {
+    expect(callbackUrl).toBe(
+      `${url}/api/@powerhousedao/workflow/oauth/callback`,
+    );
+  });
+
+  it("hands the provider's answer to the runtime and says it is done", async () => {
+    completeOAuth.mockResolvedValueOnce({
+      ok: true,
+      detail: null,
+      returnUrl: null,
+    });
+    const response = await fetch(`${callbackUrl}?state=s1&code=c1`);
+    expect(response.status).toBe(200);
+    expect(response.headers.get("cache-control")).toBe("no-store");
+    expect(await response.text()).toContain("<h1>Connected</h1>");
+    expect(completeOAuth).toHaveBeenLastCalledWith({
+      state: "s1",
+      code: "c1",
+      error: undefined,
+      errorDescription: undefined,
+    });
+  });
+
+  it("shows a failure without letting it write markup", async () => {
+    completeOAuth.mockResolvedValueOnce({
+      ok: false,
+      detail: "<script>alert(1)</script>",
+      returnUrl: null,
+    });
+    const response = await fetch(`${callbackUrl}?state=s2&error=access_denied`);
+    expect(response.status).toBe(400);
+    const html = await response.text();
+    expect(html).toContain("&lt;script&gt;alert(1)&lt;/script&gt;");
+    expect(html).not.toContain("window.close");
+  });
+
+  it("sends a full-page sign-in back where it started", async () => {
+    completeOAuth.mockResolvedValueOnce({
+      ok: true,
+      detail: null,
+      returnUrl: "https://connect.example/d/drive?tab=x",
+    });
+    const response = await fetch(`${callbackUrl}?state=s3&code=c3`, {
+      redirect: "manual",
+    });
+    expect(response.status).toBe(303);
+    expect(response.headers.get("location")).toBe(
+      "https://connect.example/d/drive?tab=x&ph_oauth=s3",
+    );
+  });
+
+  it("refuses a request with no state", async () => {
+    completeOAuth.mockClear();
+    const response = await fetch(`${callbackUrl}?code=c4`);
+    expect(response.status).toBe(400);
+    expect(completeOAuth).not.toHaveBeenCalled();
+  });
+});
+
+describe("startOAuth", () => {
+  const ORIGIN = "https://connect.example";
+  const ctx = (origin?: string) =>
+    ({
+      headers: origin ? { origin } : {},
+      db: {},
+      user: { address: "0xadmin" },
+    }) as unknown as Context;
+
+  function build(callbackUrl: string | undefined, isAdmin = true) {
+    const runtime = {
+      startOAuth: vi.fn(() => Promise.resolve({})),
+    };
+    const resolvers = getResolvers(
+      runtime as unknown as WorkflowRuntimeService,
+      { isSupremeAdmin: () => isAdmin } as unknown as IAuthorizationService,
+      callbackUrl ? { callbackUrl } : undefined,
+    ) as Record<string, Record<string, Resolver>>;
+    return {
+      runtime,
+      start: resolvers.WorkflowRuntimeMutations.startOAuth,
+      redirectUri: resolvers.WorkflowRuntimeQueries.oauthRedirectUri,
+    };
+  }
+
+  const PATH = "/api/@powerhousedao/workflow/oauth/callback";
+
+  it("is an administrator's, like minting a secret", () => {
+    const { start } = build(`https://sb.example${PATH}`, false);
+    expect(() => start({}, { connectionId: "c1" }, ctx())).toThrow(
+      "Admin access required",
+    );
+  });
+
+  it("uses the host's own redirect when it knows its origin", async () => {
+    const { runtime, start } = build(`https://sb.example${PATH}`);
+    await start(
+      {},
+      { connectionId: "c1", redirectUri: `https://evil.example${PATH}` },
+      ctx(),
+    );
+    expect(runtime.startOAuth).toHaveBeenCalledWith("c1", expect.anything(), {
+      redirectUri: `https://sb.example${PATH}`,
+    });
+  });
+
+  it("takes the caller's redirect only when it names this host's path", async () => {
+    const { runtime, start, redirectUri } = build(PATH);
+    expect(redirectUri({}, {}, ctx())).toBe(PATH);
+    expect(() => start({}, { connectionId: "c1" }, ctx())).toThrow(
+      "pass redirectUri",
+    );
+    expect(() =>
+      start(
+        {},
+        { connectionId: "c1", redirectUri: "http://localhost:4001/elsewhere" },
+        ctx(),
+      ),
+    ).toThrow(`redirectUri must be this host's ${PATH}`);
+    await start(
+      {},
+      { connectionId: "c1", redirectUri: `http://localhost:4001${PATH}` },
+      ctx(),
+    );
+    expect(runtime.startOAuth).toHaveBeenLastCalledWith(
+      "c1",
+      expect.anything(),
+      { redirectUri: `http://localhost:4001${PATH}` },
+    );
+  });
+
+  it("returns a full-page sign-in only to the page that asked", async () => {
+    const { runtime, start } = build(`https://sb.example${PATH}`);
+    expect(() =>
+      start(
+        {},
+        { connectionId: "c1", returnUrl: "https://evil.example/" },
+        ctx(ORIGIN),
+      ),
+    ).toThrow("returnUrl must be on the requesting page's origin");
+    expect(() =>
+      start({}, { connectionId: "c1", returnUrl: `${ORIGIN}/d` }, ctx()),
+    ).toThrow("returnUrl must be on the requesting page's origin");
+    await start(
+      {},
+      { connectionId: "c1", returnUrl: `${ORIGIN}/d?x=1` },
+      ctx(ORIGIN),
+    );
+    expect(runtime.startOAuth).toHaveBeenLastCalledWith(
+      "c1",
+      expect.anything(),
+      {
+        redirectUri: `https://sb.example${PATH}`,
+        returnUrl: `${ORIGIN}/d?x=1`,
+      },
+    );
+  });
+
+  it("has no redirect to offer on a host without HTTP routes", () => {
+    const { redirectUri, start } = build(undefined);
+    expect(redirectUri({}, {}, ctx())).toBeNull();
+    expect(() => start({}, { connectionId: "c1" }, ctx())).toThrow(
+      "This host serves no OAuth2 callback",
+    );
+  });
+});

package/test/workflow/resolvers.test.ts

@@ -4,7 +4,12 @@ import type {
   Context,
   IAuthorizationService,
 } from "@powerhousedao/reactor-api";
-import type { WorkflowRuntimeService } from "@powerhousedao/reactor-workflow";
+import {
+  WORKFLOW_SYNCING_MESSAGE,
+  WorkflowSyncingError,
+  type WorkflowRuntimeService,
+} from "@powerhousedao/reactor-workflow";
+import { parse, type FieldNode, type OperationDefinitionNode } from "graphql";
 import { describe, expect, it, vi } from "vitest";
 import { getResolvers } from "../../src/workflow/resolvers.js";
 
@@ -18,16 +23,33 @@ type Resolver = (
   parent: unknown,
   args: unknown,
   ctx: Context,
+  info?: unknown,
 ) => Promise<unknown>;
 
+// The resolve info for the first runtime field of a real query document.
+function runsInfo(query: string) {
+  const operation = parse(query).definitions[0] as OperationDefinitionNode;
+  const root = operation.selectionSet.selections[0] as FieldNode;
+  return { fieldNodes: [root.selectionSet!.selections[0] as FieldNode] };
+}
+
+const emptyPage = (): Promise<unknown> =>
+  Promise.resolve({ records: [], hasNextPage: false, cursor: null });
+
 function fakeRuntime() {
   return {
     webhookEndpoint: vi.fn(() => Promise.resolve(null)),
     triggerStates: vi.fn(() => Promise.resolve([])),
     runs: vi.fn(() => Promise.resolve([])),
+    runsPage: vi.fn(emptyPage),
     run: vi.fn(() => Promise.resolve(null)),
     fire: vi.fn(() => Promise.resolve({})),
     rerun: vi.fn(() => Promise.resolve({})),
+    testStep: vi.fn(() => Promise.resolve({})),
+    stepOutputTree: vi.fn(() => Promise.resolve({})),
+    blockResolutions: vi.fn(() => Promise.resolve([])),
+    testTrigger: vi.fn(() => Promise.resolve(null)),
+    cancelTriggerTestFor: vi.fn(() => Promise.resolve(true)),
     secrets: vi.fn(() =>
       Promise.resolve({
         create: vi.fn(() => Promise.resolve({ ref: "secret://v1:00" })),
@@ -64,10 +86,22 @@ describe("the workflow resolvers and the caller", () => {
     await queries.run({}, { id: "run-1" }, CTX);
     await mutations.fire({}, { workflowId: "wf-1", payload: { a: 1 } }, CTX);
     await mutations.rerun({}, { runId: "run-1" }, CTX);
+    await mutations.testStep({}, { workflowId: "wf-1", stepId: "s1" }, CTX);
+    await queries.stepOutputTree({}, { workflowId: "wf-1", stepId: "s1" }, CTX);
+    await queries.blockResolutions({}, { workflowId: "wf-1" }, CTX);
+    await mutations.testTrigger(
+      {},
+      { workflowId: "wf-1", payload: { a: 1 }, timeoutSeconds: 30 },
+      CTX,
+    );
+    await mutations.cancelTriggerTest({}, { workflowId: "wf-1" }, CTX);
 
-    expect(runtime.webhookEndpoint).toHaveBeenCalledWith("wf-1", CTX);
+    expect(runtime.webhookEndpoint).toHaveBeenCalledWith("wf-1", CTX, {});
     expect(runtime.triggerStates).toHaveBeenCalledWith(CTX);
-    expect(runtime.runs).toHaveBeenCalledWith({ driveId: "drive-1" }, CTX);
+    expect(runtime.runs).toHaveBeenCalledWith(
+      { driveId: "drive-1", withStepData: true },
+      CTX,
+    );
     expect(runtime.run).toHaveBeenCalledWith("run-1", CTX);
     expect(runtime.fire).toHaveBeenCalledWith(
       "wf-1",
@@ -77,6 +111,36 @@ describe("the workflow resolvers and the caller", () => {
       CTX,
     );
     expect(runtime.rerun).toHaveBeenCalledWith("run-1", CTX);
+    expect(runtime.testStep).toHaveBeenCalledWith("wf-1", "s1", CTX, {});
+    expect(runtime.stepOutputTree).toHaveBeenCalledWith("wf-1", "s1", CTX);
+    expect(runtime.blockResolutions).toHaveBeenCalledWith("wf-1", CTX);
+    expect(runtime.testTrigger).toHaveBeenCalledWith("wf-1", CTX, {
+      payload: { a: 1 },
+      timeoutMs: 30_000,
+    });
+    expect(runtime.cancelTriggerTestFor).toHaveBeenCalledWith("wf-1", CTX);
+  });
+
+  it("passes the caller's drive, and tags a still-syncing workflow", async () => {
+    const { runtime, queries, mutations } = build(true);
+    const drive = { driveId: "drive-1" };
+
+    await queries.webhookEndpoint({}, { workflowId: "wf-1", ...drive }, CTX);
+    await mutations.testTrigger({}, { workflowId: "wf-1", ...drive }, CTX);
+    runtime.testStep.mockRejectedValueOnce(new WorkflowSyncingError());
+    const syncing = mutations.testStep(
+      {},
+      { workflowId: "wf-1", stepId: "s1", ...drive },
+      CTX,
+    );
+
+    expect(runtime.webhookEndpoint).toHaveBeenCalledWith("wf-1", CTX, drive);
+    expect(runtime.testTrigger).toHaveBeenCalledWith("wf-1", CTX, drive);
+    await expect(syncing).rejects.toMatchObject({
+      message: WORKFLOW_SYNCING_MESSAGE,
+      extensions: { code: "WORKFLOW_SYNCING", retryable: true },
+    });
+    expect(runtime.testStep).toHaveBeenCalledWith("wf-1", "s1", CTX, drive);
   });
 
   it("refuses secret writes to a caller who does not administer the reactor", async () => {
@@ -102,4 +166,131 @@ describe("the workflow resolvers and the caller", () => {
 
     expect(runtime.secrets).toHaveBeenCalledTimes(1);
   });
+
+  it("serves the piece version a run's steps ran", async () => {
+    const { runtime, queries } = build(true);
+    runtime.run.mockResolvedValueOnce({
+      row: { id: "run-1", warnings: 1, trigger_payload: null },
+      steps: [
+        {
+          step_id: "s1",
+          input: null,
+          output: null,
+          piece_version: "2.1.0",
+          piece_source: "registry",
+          version_match: "fallback",
+          version_note:
+            "Pinned 3.0.0 is not available; runs 2.1.0 from registry",
+        },
+      ],
+    } as never);
+
+    const run = (await queries.run({}, { id: "run-1" }, CTX)) as {
+      warnings: number;
+      steps: Record<string, unknown>[];
+    };
+
+    expect(run.warnings).toBe(1);
+    expect(run.steps[0]).toMatchObject({
+      pieceVersion: "2.1.0",
+      pieceSource: "registry",
+      versionMatch: "fallback",
+      versionNote: "Pinned 3.0.0 is not available; runs 2.1.0 from registry",
+    });
+  });
+});
+
+describe("the runs listing and step data", () => {
+  it("reads step blobs only when the query selects them", async () => {
+    const { runtime, queries } = build(false);
+    const withData = (query: string) =>
+      queries.runs({}, {}, CTX, runsInfo(query)).then(
+        () =>
+          (runtime.runs.mock.calls.at(-1) as unknown[])[0] as {
+            withStepData: boolean;
+          },
+      );
+
+    expect(
+      (await withData("{ workflowRuntime { runs { id status } } }"))
+        .withStepData,
+    ).toBe(false);
+    expect(
+      (
+        await withData(
+          "{ workflowRuntime { runs { id steps { stepId status } } } }",
+        )
+      ).withStepData,
+    ).toBe(false);
+    expect(
+      (
+        await withData(
+          "{ workflowRuntime { runs { id steps { stepId output } } } }",
+        )
+      ).withStepData,
+    ).toBe(true);
+    // A fragment can select anything, so it reads as asking for the blobs.
+    expect(
+      (
+        await withData(
+          "{ workflowRuntime { runs { id steps { ...S } } } } fragment S on WorkflowStepRunRecord { input }",
+        )
+      ).withStepData,
+    ).toBe(true);
+  });
+});
+
+describe("the runs page", () => {
+  it("passes paging through and serves the page", async () => {
+    const { runtime, queries } = build(false);
+    runtime.runsPage.mockResolvedValueOnce({
+      records: [],
+      hasNextPage: true,
+      cursor: "next",
+    });
+
+    const page = await queries.runsPage(
+      {},
+      {
+        driveId: "drive-1",
+        excludeTriggerKinds: ["test"],
+        paging: { limit: 10, cursor: "prev" },
+      },
+      CTX,
+      runsInfo(
+        "{ workflowRuntime { runsPage { items { id steps { status } } cursor } } }",
+      ),
+    );
+
+    expect(runtime.runsPage).toHaveBeenCalledWith(
+      {
+        driveId: "drive-1",
+        excludeTriggerKinds: ["test"],
+        limit: 10,
+        cursor: "prev",
+        withStepData: false,
+      },
+      CTX,
+    );
+    expect(page).toEqual({
+      items: [],
+      hasNextPage: true,
+      hasPreviousPage: true,
+      cursor: "next",
+    });
+  });
+
+  it("reports a cursor it did not issue as bad input", async () => {
+    const { runtime, queries } = build(false);
+    const invalid = new Error("Invalid runs cursor");
+    invalid.name = "InvalidRunCursorError";
+    runtime.runsPage.mockRejectedValueOnce(invalid);
+
+    const error = (await queries
+      .runsPage({}, { paging: { cursor: "junk" } }, CTX)
+      .catch((thrown: unknown) => thrown)) as {
+      extensions?: { code?: string };
+    };
+    expect(error.extensions?.code).toBe("BAD_USER_INPUT");
+  });
 });

package/test/workflow/webhook-dedupe.test.ts

@@ -24,7 +24,7 @@ interface PolicyShape {
   challengeField?: unknown;
 }
 
-describe("core#webhook redelivery", () => {
+describe("the core webhook trigger redelivery", () => {
   it("dedupes on a bare field name found in the query string", async () => {
     host = await startWebhookHost();
     const { token } = await host.arm({
@@ -207,7 +207,7 @@ describe("core#webhook redelivery", () => {
   });
 });
 
-describe("core#webhook endpoint verification", () => {
+describe("the core webhook trigger endpoint verification", () => {
   it("echoes a bare challenge field from the query string without running", async () => {
     host = await startWebhookHost();
     const { token } = await host.arm({
@@ -262,7 +262,7 @@ describe("core#webhook endpoint verification", () => {
   });
 });
 
-describe("core#webhook field policy", () => {
+describe("the core webhook trigger field policy", () => {
   it("hands the reactor a source-tagged field for a prefixed config", async () => {
     host = await startWebhookHost();
     await host.arm({

package/test/workflow/webhook-signed.test.ts

@@ -1,4 +1,4 @@
-// The signature-verifying half of core#webhook, over a real socket: config,
+// The signature-verifying half of the core webhook trigger, over a real socket: config,
 // resolved policy and the reactor's verifier have to agree on the wire format.
 import { createHmac } from "node:crypto";
 import { afterEach, describe, expect, it } from "vitest";
@@ -42,7 +42,7 @@ async function expectNoRun(current: WebhookHost): Promise<void> {
   expect(current.fired).toHaveLength(0);
 }
 
-describe("core#webhook signature verification", () => {
+describe("the core webhook trigger signature verification", () => {
   describe("the three layouts", () => {
     it("accepts a bare digest under hmac and starts a run", async () => {
       host = await startWebhookHost();