@boxxy/pepys 0.1.3 → 0.1.4

package/dist/queries/types.d.ts

@@ -62,8 +62,8 @@ interface NullableColumn<Kind extends ColumnKind> {
 }
 type TelemetryColumns = Readonly<{
     session_id: Column<'entityID'>;
-    origin_issuer: NullableColumn<'text'>;
-    origin_subject: NullableColumn<'text'>;
+    origin_issuer: Column<'text'>;
+    origin_subject: Column<'text'>;
     product: Column<'text'>;
     at: Column<'timestamp'>;
 }>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boxxy/pepys",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "The pepys plug-in of boxxy, its fact sink and its report reader",
   "homepage": "https://github.com/zgeoff/boxxy/tree/main/packages/pepys#readme",
   "bugs": "https://github.com/zgeoff/boxxy/issues",
@@ -13,7 +13,6 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
-    "!src/test-utils",
     "dist"
   ],
   "type": "module",
@@ -29,7 +28,8 @@
     "./reader": {
       "types": "./dist/create-pepys-reader.d.ts",
       "default": "./src/create-pepys-reader.ts"
-    }
+    },
+    "./test-utils/*": "./src/test-utils/*.ts"
   },
   "publishConfig": {
     "access": "public"
@@ -40,7 +40,7 @@
     "typecheck": "tsrs --noEmit"
   },
   "dependencies": {
-    "@boxxy/model": "0.1.3"
+    "@boxxy/model": "0.1.4"
   },
   "devDependencies": {
     "@pepys/cli": "https://github.com/zgeoff/pepys/releases/download/preview-kit-0.0.1/pepys-cli-0.0.1.tgz",
@@ -52,8 +52,14 @@
   },
   "peerDependencies": {
     "@pepys/kit": "0.0.1",
+    "@pepys/testing": "0.0.1",
     "zod": "4.6.7"
   },
+  "peerDependenciesMeta": {
+    "@pepys/testing": {
+      "optional": true
+    }
+  },
   "engines": {
     "bun": ">=1.3",
     "node": ">=24"

package/src/queries/build-stage-time.ts

@@ -170,16 +170,23 @@ interface SettledAttempt extends MeasuredAttempt {
   readonly ended_at: string;
 }
 
-// For each settled build that was built: the claim of the next review attempt, by number, less
-// the build's end. null when no build has a review after it.
+// For each settled build that was built: the claim of the review claimed next at or after the
+// build's end, less that end. An attempt's number counts within its phase, so it cannot order a
+// build against a review. null when no build has a review after it.
 function measureReviewWait(attempts: readonly MeasuredAttempt[]): number | null {
   const waits = attempts
     .filter((attempt): attempt is SettledAttempt => attempt.ended_at !== null)
     .filter((build) => build.phase === 'build' && build.outcome === outcomeNames.built)
     .flatMap((build) => {
       const [review] = attempts
-        .filter((attempt) => attempt.phase === 'review' && attempt.number > build.number)
-        .toSorted((left, right) => left.number - right.number);
+        .filter(
+          (attempt) =>
+            attempt.phase === 'review' && measureMinutes(build.ended_at, attempt.claimed_at) >= 0,
+        )
+        .toSorted(
+          (left, right) =>
+            measureMinutes(right.claimed_at, left.claimed_at) || left.id.localeCompare(right.id),
+        );
 
       return review === undefined ? [] : [measureMinutes(build.ended_at, review.claimed_at)];
     });

package/src/queries/types.ts

@@ -87,8 +87,8 @@ interface NullableColumn<Kind extends ColumnKind> {
 // columns fits. A table's columns take a type alias: an interface has no index signature.
 type TelemetryColumns = Readonly<{
   session_id: Column<'entityID'>;
-  origin_issuer: NullableColumn<'text'>;
-  origin_subject: NullableColumn<'text'>;
+  origin_issuer: Column<'text'>;
+  origin_subject: Column<'text'>;
   product: Column<'text'>;
   at: Column<'timestamp'>;
 }>;

package/src/test-utils/build-foreign-stand-in.ts

@@ -0,0 +1,139 @@
+import {
+  defineConsumer,
+  defineFactFamily,
+  definePlugin,
+  defineSource,
+  defineTable,
+} from '@pepys/kit';
+import type { DeliveryReadRow, ForeignReads } from '../queries/types.ts';
+
+// No fact reaches a stand-in consumer: a test writes its rows. Its entry is this file, which
+// exports no `applyFact`, so a fact sent to one fails the apply.
+const entry = new URL(import.meta.url);
+
+const logRecordFamily = defineFactFamily({
+  stream: 'facts.telemetry.log_record',
+  api: 'otlp-logs/1',
+  entityKind: 'telemetry:session',
+  types: {},
+});
+
+const pullRequestFamily = defineFactFamily({
+  stream: 'facts.github.pull_request',
+  api: 'github-webhook/1',
+  entityKind: 'github:pull_request',
+  types: {},
+});
+
+const telemetryColumns = {
+  id: { kind: 'entityID' },
+  session_id: { kind: 'entityID' },
+  origin_issuer: { kind: 'text' },
+  origin_subject: { kind: 'text' },
+  product: { kind: 'text' },
+  at: { kind: 'timestamp' },
+} as const;
+
+const telemetryModelRequestConsumer = defineConsumer({
+  name: 'telemetry_model_request',
+  entry,
+  input: { mode: 'fact', streams: [logRecordFamily.stream] },
+  tables: {
+    telemetry_model_request: defineTable({
+      columns: {
+        ...telemetryColumns,
+        model: { kind: 'text' },
+        cost_basis: { kind: 'text' },
+        cost_usd: { kind: 'real', nullable: true },
+        input_tokens: { kind: 'integer' },
+        cache_read_tokens: { kind: 'integer' },
+        cache_creation_tokens: { kind: 'integer' },
+        output_tokens: { kind: 'integer' },
+      },
+      primaryKey: ['id'],
+      indexes: [{ columns: ['session_id'] }],
+    }),
+  },
+  entityViews: [],
+  reads: [],
+  links: [],
+});
+
+const telemetryTurnCostConsumer = defineConsumer({
+  name: 'telemetry_turn_cost',
+  entry,
+  input: { mode: 'fact', streams: [logRecordFamily.stream] },
+  tables: {
+    telemetry_turn_cost: defineTable({
+      columns: {
+        ...telemetryColumns,
+        model: { kind: 'text', nullable: true },
+        cost_usd: { kind: 'real' },
+      },
+      primaryKey: ['id'],
+      indexes: [{ columns: ['session_id'] }],
+    }),
+  },
+  entityViews: [],
+  reads: [],
+  links: [],
+});
+
+const githubPullRequestConsumer = defineConsumer({
+  name: 'github_pull_request',
+  entry,
+  input: { mode: 'fact', streams: [pullRequestFamily.stream] },
+  tables: {
+    github_pull_request: defineTable({
+      columns: {
+        id: { kind: 'entityID' },
+        merged_at: { kind: 'timestamp', nullable: true },
+      },
+      primaryKey: ['id'],
+      indexes: [],
+    }),
+  },
+  entityViews: [],
+  reads: ['github_pull_request'],
+  links: [],
+});
+
+// The telemetry and GitHub plug-ins as far as the queries read them: the three consumers with the
+// columns the queries name, and the GitHub delivery read as rows the test sets per item.
+export function buildForeignStandIn() {
+  const deliveries = new Map<string, readonly DeliveryReadRow[]>();
+
+  const foreign: ForeignReads = {
+    telemetryModelRequest: telemetryModelRequestConsumer,
+    telemetryTurnCost: telemetryTurnCostConsumer,
+    githubPullRequest: githubPullRequestConsumer,
+    delivery: {
+      consumers: [githubPullRequestConsumer],
+      readDeliveries: (_db, input) => Promise.resolve(deliveries.get(input.item) ?? []),
+    },
+  };
+
+  return {
+    foreign,
+    plugins: [
+      definePlugin({
+        name: 'telemetry',
+        sources: [defineSource({ name: 'telemetry', families: [logRecordFamily] })],
+        consumers: [telemetryModelRequestConsumer, telemetryTurnCostConsumer],
+      }),
+      definePlugin({
+        name: 'github',
+        sources: [defineSource({ name: 'github', families: [pullRequestFamily] })],
+        consumers: [githubPullRequestConsumer],
+      }),
+    ],
+    consumers: {
+      telemetryModelRequest: telemetryModelRequestConsumer,
+      telemetryTurnCost: telemetryTurnCostConsumer,
+      githubPullRequest: githubPullRequestConsumer,
+    },
+    setDeliveries: (item: string, rows: readonly DeliveryReadRow[]) => {
+      deliveries.set(item, rows);
+    },
+  };
+}

package/src/test-utils/build-mock-applied-fact.ts

@@ -0,0 +1,39 @@
+import type { EntityRef } from '@boxxy/model';
+import { buildMockWorkFact } from '@boxxy/model/test-utils/build-mock-work-fact';
+import type { MockedFactType } from '@boxxy/model/test-utils/build-mock-work-fact';
+import type { OutgoingFact } from '@pepys/kit';
+import type { boxxySource } from '../boxxy-source.ts';
+import { isOutgoingFact } from '../sink/is-outgoing-fact.ts';
+import { toWireFact } from '../sink/to-wire-fact.ts';
+
+interface AppliedFactOverrides {
+  readonly payload?: Readonly<Record<string, unknown>>;
+
+  // ISO 8601, as boxxy's sink writes it
+  readonly at?: string;
+  readonly entity?: EntityRef;
+  readonly event?: string;
+}
+
+// One fact of a batch as boxxy's sink sends it: a model fact whose payload its schema accepts, in
+// the sink's wire form. Ingest gives it the fact ID `event:boxxy:<event>`.
+export function buildMockAppliedFact(
+  type: MockedFactType,
+  overrides: AppliedFactOverrides = {},
+): OutgoingFact<typeof boxxySource> {
+  const wire = toWireFact(
+    buildMockWorkFact(type, {
+      ...(overrides.payload === undefined ? {} : { payload: overrides.payload }),
+      ...(overrides.entity === undefined ? {} : { entity: overrides.entity }),
+      at: Date.parse(overrides.at ?? '2026-11-11T02:00:00.000Z'),
+    }),
+  );
+
+  const fact = { ...wire, event: overrides.event ?? wire.event };
+
+  if (!isOutgoingFact(fact)) {
+    throw new Error(`a mock ${type} fact fails the schema of the boxxy fact family`);
+  }
+
+  return fact;
+}

package/src/test-utils/build-mock-attempt-read-row.ts

@@ -0,0 +1,17 @@
+import type { AttemptReadRow } from '../queries/types.ts';
+
+export function buildMockAttemptReadRow(overrides: Partial<AttemptReadRow> = {}): AttemptReadRow {
+  return {
+    id: 'boxxy:attempt:0193a1b2-0000-7000-8000-0000000000a1',
+    phase: 'build',
+    number: 1,
+    round: 1,
+    state: 'succeeded',
+    outcome: null,
+    failure: null,
+    claimed_at: '2026-11-11T02:00:00.000Z',
+    ended_at: null,
+    sleeps: [],
+    ...overrides,
+  };
+}

package/src/test-utils/build-mock-binding-read-row.ts

@@ -0,0 +1,12 @@
+import type { BindingReadRow } from '../queries/types.ts';
+
+export function buildMockBindingReadRow(overrides: Partial<BindingReadRow> = {}): BindingReadRow {
+  return {
+    attempt_id: 'boxxy:attempt:0193a1b2-0000-7000-8000-0000000000a1',
+    session_id: 'telemetry:session:s-build',
+    bound_at: '2026-11-11T02:00:05.000Z',
+    caller_issuer: 'https://broker.example',
+    caller_subject: 'imp-builder',
+    ...overrides,
+  };
+}

package/src/test-utils/build-mock-item-facts.ts

@@ -0,0 +1,149 @@
+import type { OutgoingFact } from '@pepys/kit';
+import type { boxxySource } from '../boxxy-source.ts';
+import type { WorkFact } from '../work/types.ts';
+import { buildMockAppliedFact } from './build-mock-applied-fact.ts';
+import { toScopeFact } from './to-scope-fact.ts';
+
+type AppliedFact = OutgoingFact<typeof boxxySource>;
+
+interface ItemFacts {
+  // the facts as boxxy's sink sends them
+  readonly applied: AppliedFact[];
+
+  // the same facts as the consumer reads them from the item's scope
+  readonly facts: WorkFact[];
+  readonly attempts: {
+    readonly triage: string;
+    readonly build: string;
+    readonly review: string;
+    readonly rebuild: string;
+    readonly rereview: string;
+  };
+}
+
+// One item's facts in time order, events `f01` to `f21`: a triage, a build that slept 20 minutes
+// and linked pull request 9001, a review that asked for changes, a second build in the first
+// build's atc session, and a review that passed.
+export function buildMockItemFacts(): ItemFacts {
+  const attempts = {
+    triage: '0193a1b2-0000-7000-8000-0000000000a1',
+    build: '0193a1b2-0000-7000-8000-0000000000a2',
+    review: '0193a1b2-0000-7000-8000-0000000000a3',
+    rebuild: '0193a1b2-0000-7000-8000-0000000000a4',
+    rereview: '0193a1b2-0000-7000-8000-0000000000a5',
+  };
+
+  const applied = [
+    buildItemFact('boxxy.item.filed', {
+      event: 'f01',
+      at: '2026-11-11T02:00:00.000Z',
+      payload: {
+        id: '0193a1b2-0000-7000-8000-000000000001',
+        kind: 'core.issue',
+        title: 'Chart the shoals',
+        repo: 'shoal/charts',
+      },
+    }),
+    buildClaimed('f02', '02:01:00', { attempt: attempts.triage, phase: 'triage', number: 1 }),
+    buildStarted('f03', '02:01:05', attempts.triage, 's-triage'),
+    buildSettled('f04', '02:05:00', { attempt: attempts.triage, outcome: 'accepted' }),
+    buildClaimed('f05', '02:10:00', { attempt: attempts.build, phase: 'build', number: 1 }),
+    buildStarted('f06', '02:10:05', attempts.build, 's-build'),
+    buildItemFact('boxxy.attempt.session_bound', {
+      event: 'f07',
+      at: '2026-11-11T02:10:05.000Z',
+      payload: {
+        attempt: attempts.build,
+        atcSession: 's-build',
+        agentSession: 'agent-7',
+        product: 'claude_code',
+      },
+    }),
+    buildItemFact('boxxy.pull_request.linked', {
+      event: 'f08',
+      at: '2026-11-11T02:25:00.000Z',
+      payload: { attempt: attempts.build, pullRequestId: '9001' },
+    }),
+    buildMark('boxxy.attempt.slept', 'f09', '02:30:00', attempts.build),
+    buildMark('boxxy.attempt.woken', 'f10', '02:50:00', attempts.build),
+    buildMark('boxxy.attempt.closed_out', 'f11', '03:09:00', attempts.build),
+    buildSettled('f12', '03:10:00', { attempt: attempts.build, outcome: 'built' }),
+    buildClaimed('f13', '03:16:00', { attempt: attempts.review, phase: 'review', number: 1 }),
+    buildStarted('f14', '03:16:05', attempts.review, 's-review'),
+    buildSettled('f15', '03:36:00', { attempt: attempts.review, outcome: 'changes-requested' }),
+    buildClaimed('f16', '03:40:00', {
+      attempt: attempts.rebuild,
+      phase: 'build',
+      number: 2,
+      round: 2,
+    }),
+    buildStarted('f17', '03:40:05', attempts.rebuild, 's-build'),
+    buildSettled('f18', '04:10:00', { attempt: attempts.rebuild, outcome: 'built', round: 2 }),
+    buildClaimed('f19', '04:12:00', {
+      attempt: attempts.rereview,
+      phase: 'review',
+      number: 2,
+      round: 2,
+    }),
+    buildStarted('f20', '04:12:05', attempts.rereview, 's-rereview'),
+    buildSettled('f21', '04:30:00', { attempt: attempts.rereview, outcome: 'passed', round: 2 }),
+  ];
+
+  return { applied, facts: applied.map((fact) => toScopeFact(fact)), attempts };
+}
+
+function buildItemFact(
+  type: Parameters<typeof buildMockAppliedFact>[0],
+  overrides: Parameters<typeof buildMockAppliedFact>[1],
+): AppliedFact {
+  return buildMockAppliedFact(type, {
+    ...overrides,
+    entity: 'boxxy:item:0193a1b2-0000-7000-8000-000000000001',
+  });
+}
+
+function buildClaimed(event: string, time: string, payload: Record<string, unknown>): AppliedFact {
+  return buildItemFact('boxxy.attempt.claimed', {
+    event,
+    at: `2026-11-11T${time}.000Z`,
+    payload: { round: 1, ...payload },
+  });
+}
+
+function buildStarted(
+  event: string,
+  time: string,
+  attempt: string,
+  atcSession: string,
+): AppliedFact {
+  return buildItemFact('boxxy.attempt.started', {
+    event,
+    at: `2026-11-11T${time}.000Z`,
+    payload: {
+      attempt,
+      atcSession,
+      caller: { issuer: 'https://broker.example', subject: 'imp-builder' },
+    },
+  });
+}
+
+function buildSettled(event: string, time: string, payload: Record<string, unknown>): AppliedFact {
+  return buildItemFact('boxxy.attempt.settled', {
+    event,
+    at: `2026-11-11T${time}.000Z`,
+    payload,
+  });
+}
+
+function buildMark(
+  type: 'boxxy.attempt.slept' | 'boxxy.attempt.woken' | 'boxxy.attempt.closed_out',
+  event: string,
+  time: string,
+  attempt: string,
+): AppliedFact {
+  return buildItemFact(type, {
+    event,
+    at: `2026-11-11T${time}.000Z`,
+    payload: { attempt },
+  });
+}

package/src/test-utils/build-mock-request-read-row.ts

@@ -0,0 +1,20 @@
+import type { RequestReadRow } from '../queries/types.ts';
+
+// The origin matches the caller of the default binding row, so the two join.
+export function buildMockRequestReadRow(overrides: Partial<RequestReadRow> = {}): RequestReadRow {
+  return {
+    session_id: 'telemetry:session:s-build',
+    origin_issuer: 'https://broker.example',
+    origin_subject: 'imp-builder',
+    product: 'claude_code',
+    at: '2026-11-11T02:20:00.000Z',
+    model: 'model-large',
+    cost_basis: 'reported',
+    cost_usd: 0,
+    input_tokens: 10,
+    cache_read_tokens: 100,
+    cache_creation_tokens: 0,
+    output_tokens: 20,
+    ...overrides,
+  };
+}

package/src/test-utils/build-mock-scope-fact.ts

@@ -0,0 +1,13 @@
+import type { MockedFactType } from '@boxxy/model/test-utils/build-mock-work-fact';
+import type { WorkFact } from '../work/types.ts';
+import { buildMockAppliedFact } from './build-mock-applied-fact.ts';
+import { toScopeFact } from './to-scope-fact.ts';
+
+// One fact as the consumer reads it from its scope: a model fact through the sink's wire form,
+// with the fact ID that ingest gives it.
+export function buildMockScopeFact(
+  type: MockedFactType,
+  overrides: Parameters<typeof buildMockAppliedFact>[1] = {},
+): WorkFact {
+  return toScopeFact(buildMockAppliedFact(type, overrides));
+}

package/src/test-utils/create-ingest-stand-in.ts

@@ -0,0 +1,56 @@
+import { isDeliveryAuthentic } from '@pepys/kit';
+import { boxxySource } from '../boxxy-source.ts';
+
+export interface IngestStandIn {
+  // the receive route of the boxxy source, for the sender's `fetch` option
+  readonly handleRequest: (request: Request) => Promise<Response>;
+
+  // the events of the stored facts, in arrival order, a copy counted once
+  readStored: () => Promise<readonly string[]>;
+}
+
+// Ingest's receive route in memory, with the kit's own signature check and batch read. The kit
+// exports no route handler of ingest, so the answers are written here: 401, the read's 400 or
+// 422, or the batch stored whole with a copy of an event dropped.
+export function createIngestStandIn(secret: string): IngestStandIn {
+  const path = boxxySource.live;
+
+  if (path?.kind !== 'receive') {
+    throw new Error('the boxxy source has no receive path');
+  }
+
+  const stored: string[] = [];
+
+  return {
+    handleRequest: async (request) => {
+      const buffer = await request.arrayBuffer();
+
+      const body = new Uint8Array(buffer);
+
+      if (!isDeliveryAuthentic(path.check, secret, request.headers, body)) {
+        return Response.json({ error: 'the signature does not match' }, { status: 401 });
+      }
+
+      const received = path.read(
+        { headers: request.headers, body },
+        { name: boxxySource.name, families: boxxySource.families },
+      );
+
+      if (received.kind === 'refused') {
+        return Response.json({ error: received.reason }, { status: received.status });
+      }
+
+      if (received.kind === 'ignored') {
+        return Response.json({ status: 'ignored' }, { status: 202 });
+      }
+
+      const events = received.batch.facts.map((pending) => pending.fact.id);
+
+      stored.push(...events.filter((event) => !stored.includes(event)));
+
+      return Response.json({ status: 'stored', stored: events.length });
+    },
+    readStored: () =>
+      Promise.resolve(stored.map((event) => event.replace(`event:${boxxySource.name}:`, ''))),
+  };
+}

package/src/test-utils/create-query-stand-in.ts

@@ -0,0 +1,51 @@
+import type { CostToLand } from '@boxxy/model';
+import { buildCostToLand } from '../queries/build-cost-to-land.ts';
+import { buildStageTime } from '../queries/build-stage-time.ts';
+import type { UncheckedQueryClient } from '../types.ts';
+
+export interface QueryStandIn {
+  readonly client: UncheckedQueryClient;
+
+  // the cost the query answers for the item's entity ID
+  setCost: (item: string, cost: CostToLand) => void;
+
+  // every later call fails as a refused connection does
+  takeDown: () => void;
+}
+
+// The two queries in memory. An item with no cost set answers what each query's builder gives for
+// an item with no row.
+export function createQueryStandIn(): QueryStandIn {
+  const costs = new Map<string, CostToLand>();
+
+  let isDown = false;
+
+  const answer = (value: () => unknown): Promise<unknown> =>
+    isDown ? Promise.reject(new Error('connect ECONNREFUSED')) : Promise.resolve(value());
+
+  return {
+    client: {
+      boxxy_cost_to_land: (input) =>
+        answer(
+          () =>
+            costs.get(input.item) ??
+            buildCostToLand({
+              item: input.item,
+              attempts: [],
+              bindings: [],
+              requests: [],
+              turns: [],
+              pullRequests: [],
+            }),
+        ),
+      boxxy_stage_time: (input) =>
+        answer(() => buildStageTime({ ...input, attempts: [], deliveries: [] })),
+    },
+    setCost: (item, cost) => {
+      costs.set(item, cost);
+    },
+    takeDown: () => {
+      isDown = true;
+    },
+  };
+}

package/src/test-utils/create-test-pepys.ts

@@ -0,0 +1,228 @@
+import { isDeliveryAuthentic } from '@pepys/kit';
+import type { DeliveryCheck, FactEnvelope } from '@pepys/kit';
+import { createTestStore } from '@pepys/testing';
+import { z } from 'zod';
+import { boxxySource } from '../boxxy-source.ts';
+import { buildBoxxyPlugin } from '../build-boxxy-plugin.ts';
+import { buildCostToLandQuery } from '../queries/build-cost-to-land-query.ts';
+import { buildStageTimeQuery } from '../queries/build-stage-time-query.ts';
+import type { DeliveryReads, ForeignReads } from '../queries/types.ts';
+import { isOutgoingFact } from '../sink/is-outgoing-fact.ts';
+import type { UncheckedQueryClient } from '../types.ts';
+import { buildForeignStandIn } from './build-foreign-stand-in.ts';
+import { toEntityID } from './to-entity-id.ts';
+
+export interface TestPepysOptions {
+  // the value of `PEPYS_BOXXY_SIGNING_SECRET`, which the fact batch route checks
+  readonly boxxySecret: string;
+
+  // the value of `PEPYS_GITHUB_WEBHOOK_SECRET`, which the webhook route checks
+  readonly webhookSecret: string;
+}
+
+// One model request of an agent session, with the proven sender of its record.
+export interface TelemetryRequest {
+  readonly id: string;
+
+  // the atc session ID that the agent copies onto its records
+  readonly session: string;
+  readonly origin: { readonly issuer: string; readonly subject: string };
+  readonly model: string;
+  readonly costUSD: number;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+
+  // ISO 8601
+  readonly at: string;
+}
+
+export interface TestPepys extends AsyncDisposable {
+  // ingest's two routes that boxxy's journey reaches: the boxxy fact batch route and the GitHub
+  // webhook route; any other path answers 404
+  readonly handleRequest: (request: Request) => Promise<Response>;
+
+  // the two queries of the boxxy plug-in, as the pepys API answers them
+  readonly client: UncheckedQueryClient;
+
+  // the rows that the telemetry route would write for these records
+  readonly writeTelemetry: (requests: readonly TelemetryRequest[]) => Promise<void>;
+}
+
+const webhookRoute = '/webhook/github';
+
+const webhookCheck: DeliveryCheck = {
+  kind: 'hmac-sha256',
+  header: 'x-hub-signature-256',
+  secretEnv: 'PEPYS_GITHUB_WEBHOOK_SECRET',
+};
+
+// GitHub's `pull_request` event, as far as the merge time goes
+const pullRequestEventSchema = z.object({
+  action: z.string(),
+  pull_request: z.object({ id: z.number().int(), merged_at: z.string().nullable() }),
+});
+
+// The boxxy plug-in on the kit's test store, behind the kit's own signature check and batch read.
+// The GitHub and telemetry plug-ins are stand-ins: the webhook writes the pull request row, and
+// the delivery read knows merges only, no release and no deploy.
+export async function createTestPepys(options: TestPepysOptions): Promise<TestPepys> {
+  const standIn = buildForeignStandIn();
+
+  const merges = new Map<string, string | null>();
+
+  const foreign: ForeignReads = { ...standIn.foreign, delivery: buildDeliveryReads(merges) };
+  const plugin = buildBoxxyPlugin(foreign);
+
+  const store = await createTestStore({ plugins: [plugin, ...standIn.plugins] });
+
+  const costQuery = buildCostToLandQuery(foreign);
+  const stageQuery = buildStageTimeQuery(foreign.delivery);
+  const path = boxxySource.live;
+
+  if (path?.kind !== 'receive') {
+    throw new Error('the boxxy source has no receive path');
+  }
+
+  const stored = new Set<string>();
+
+  const receiveFacts = async (request: Request): Promise<Response> => {
+    const buffer = await request.arrayBuffer();
+
+    const body = new Uint8Array(buffer);
+
+    if (!isDeliveryAuthentic(path.check, options.boxxySecret, request.headers, body)) {
+      return Response.json({ error: 'the signature does not match' }, { status: 401 });
+    }
+
+    const received = path.read(
+      { headers: request.headers, body },
+      { name: boxxySource.name, families: boxxySource.families },
+    );
+
+    if (received.kind === 'refused') {
+      return Response.json({ error: received.reason }, { status: received.status });
+    }
+
+    if (received.kind === 'ignored') {
+      return Response.json({ status: 'ignored' }, { status: 202 });
+    }
+
+    const facts = received.batch.facts
+      .filter((pending) => !stored.has(pending.fact.id))
+      .map((pending) => toOutgoingFact(pending.fact))
+      .filter((fact) => isOutgoingFact(fact));
+
+    await store.apply(boxxySource, facts);
+
+    for (const pending of received.batch.facts) {
+      stored.add(pending.fact.id);
+    }
+
+    return Response.json({ status: 'stored', stored: received.batch.facts.length });
+  };
+
+  const receiveWebhook = async (request: Request): Promise<Response> => {
+    const buffer = await request.arrayBuffer();
+
+    const body = new Uint8Array(buffer);
+
+    if (!isDeliveryAuthentic(webhookCheck, options.webhookSecret, request.headers, body)) {
+      return Response.json({ error: 'the signature does not match' }, { status: 401 });
+    }
+
+    const raw: unknown = JSON.parse(new TextDecoder().decode(body));
+    const event = pullRequestEventSchema.safeParse(raw);
+
+    if (request.headers.get('x-github-event') !== 'pull_request' || !event.success) {
+      return Response.json({ status: 'ignored' }, { status: 202 });
+    }
+
+    const id = `github:pull_request:${event.data.pull_request.id}`;
+
+    merges.set(id, event.data.pull_request.merged_at);
+
+    await store.writeRows(standIn.consumers.githubPullRequest, 'github_pull_request', [
+      { id: toEntityID(id), merged_at: event.data.pull_request.merged_at },
+    ]);
+
+    return Response.json({ status: 'stored', stored: 1 });
+  };
+
+  return {
+    handleRequest: (request) => {
+      const route = new URL(request.url).pathname;
+
+      if (route === path.route) {
+        return receiveFacts(request);
+      }
+
+      return route === webhookRoute
+        ? receiveWebhook(request)
+        : Promise.resolve(Response.json({ error: 'no such route' }, { status: 404 }));
+    },
+    client: {
+      boxxy_cost_to_land: (input) => store.query(costQuery, input),
+      boxxy_stage_time: (input) => store.query(stageQuery, input),
+    },
+    writeTelemetry: (requests) =>
+      store.writeRows(
+        standIn.consumers.telemetryModelRequest,
+        'telemetry_model_request',
+        requests.map((request) => ({
+          id: toEntityID(`telemetry:model_request:${request.id}`),
+          session_id: toEntityID(`telemetry:session:${request.session}`),
+          origin_issuer: request.origin.issuer,
+          origin_subject: request.origin.subject,
+          product: 'claude_code',
+          model: request.model,
+          cost_basis: 'reported',
+          cost_usd: request.costUSD,
+          input_tokens: request.inputTokens,
+          cache_read_tokens: 0,
+          cache_creation_tokens: 0,
+          output_tokens: request.outputTokens,
+          at: request.at,
+        })),
+      ),
+    [Symbol.asyncDispose]: () => store[Symbol.asyncDispose](),
+  };
+}
+
+// The merge of each pull request that an attempt of the item produced, read through the
+// `produced` links as the GitHub plug-in's delivery module reads it.
+function buildDeliveryReads(merges: ReadonlyMap<string, string | null>): DeliveryReads {
+  return {
+    consumers: [],
+    readDeliveries: async (db, input) => {
+      const produced = await db
+        .selectFrom('link_effective as produced')
+        .innerJoin('boxxy_attempt as attempt', 'attempt.id', 'produced.from_id')
+        .where('produced.type', '=', 'produced')
+        .where('attempt.item_id', '=', input.item)
+        .select('produced.to_id as id')
+        .distinct()
+        .orderBy('produced.to_id')
+        .execute();
+
+      return produced.map((row) => ({
+        pullRequest: row.id,
+        mergedAt: merges.get(row.id) ?? null,
+        release: null,
+        deploy: null,
+      }));
+    },
+  };
+}
+
+// The fact of a batch that ingest built the envelope from; the event is the envelope's ID less
+// the source's prefix.
+function toOutgoingFact(fact: FactEnvelope<unknown>) {
+  return {
+    type: fact.type,
+    event: fact.id.replace(`event:${boxxySource.name}:`, ''),
+    entity: fact.entity,
+    ...(fact.actor === undefined ? {} : { actor: fact.actor }),
+    at: fact.at,
+    payload: fact.payload,
+  };
+}

package/src/test-utils/to-entity-id.ts

@@ -0,0 +1,14 @@
+import { buildEntityID, parseEntityID } from '@pepys/kit';
+import type { EntityID } from '@pepys/kit';
+
+// A row that a test writes takes its entity ID columns as the kit's entity ID type.
+export function toEntityID(text: string): EntityID {
+  const parsed = parseEntityID(text);
+  const built = parsed.ok ? buildEntityID(parsed.value) : parsed;
+
+  if (!built.ok) {
+    throw new Error(`${text} is no entity ID: ${built.failure.reason}`);
+  }
+
+  return built.value;
+}

package/src/test-utils/to-scope-fact.ts

@@ -0,0 +1,92 @@
+import type { OutgoingFact } from '@pepys/kit';
+import { z } from 'zod';
+import type { boxxySource } from '../boxxy-source.ts';
+import type { WorkFact } from '../work/types.ts';
+
+const base = { id: z.string(), entity: z.string(), at: z.string() };
+const ofAttempt = { attempt: z.string() };
+const callerSchema = z.object({ issuer: z.string(), subject: z.string() }).nullable();
+
+const filedPayload = z.object({
+  kind: z.string(),
+  repo: z.string(),
+  title: z.string(),
+  fields: z.object({ designMode: z.unknown().optional() }),
+});
+
+const editedPayload = z.object({
+  title: z.unknown().optional(),
+  kind: z.unknown().optional(),
+  fields: z.unknown().optional(),
+});
+
+const closedPayload = z.object({ reason: z.string() });
+
+const claimedPayload = z.object({
+  ...ofAttempt,
+  phase: z.string(),
+  number: z.number(),
+  round: z.number(),
+  mode: z.string(),
+  pool: z.string(),
+  recipeHash: z.string(),
+  rulesVersion: z.string(),
+});
+
+const sessionPayload = z.object({ ...ofAttempt, atcSession: z.string(), caller: callerSchema });
+
+const boundPayload = z.object({
+  ...ofAttempt,
+  atcSession: z.string(),
+  agentSession: z.string(),
+  product: z.string(),
+});
+
+const settledPayload = z.object({
+  ...ofAttempt,
+  state: z.string(),
+  outcome: z.string(),
+  failure: z.string().nullable(),
+  asleep: z.boolean(),
+});
+
+const linkedPayload = z.object({ ...ofAttempt, pullRequestId: z.string() });
+
+const sessionTypes = z.enum([
+  'boxxy.attempt.started',
+  'boxxy.attempt.reconciled',
+  'boxxy.attempt.resumed',
+]);
+
+const markPayload = z.object(ofAttempt);
+
+const markTypes = z.enum([
+  'boxxy.attempt.slept',
+  'boxxy.attempt.woken',
+  'boxxy.attempt.closed_out',
+]);
+
+const scopeFactSchema: z.ZodType<WorkFact> = z.discriminatedUnion('type', [
+  z.object({ ...base, type: z.literal('boxxy.item.filed'), payload: filedPayload }),
+  z.object({ ...base, type: z.literal('boxxy.item.edited'), payload: editedPayload }),
+  z.object({ ...base, type: z.literal('boxxy.item.closed'), payload: closedPayload }),
+  z.object({ ...base, type: z.literal('boxxy.attempt.claimed'), payload: claimedPayload }),
+  z.object({ ...base, type: sessionTypes, payload: sessionPayload }),
+  z.object({ ...base, type: z.literal('boxxy.attempt.session_bound'), payload: boundPayload }),
+  z.object({ ...base, type: markTypes, payload: markPayload }),
+  z.object({ ...base, type: z.literal('boxxy.attempt.settled'), payload: settledPayload }),
+  z.object({ ...base, type: z.literal('boxxy.pull_request.linked'), payload: linkedPayload }),
+]);
+
+// One fact of a batch as the consumer reads it from its scope, with the fact ID that ingest gives
+// it. The payload is read the way the glue's decoder reads it, so a field the fold needs and the
+// model lacks fails.
+export function toScopeFact(fact: OutgoingFact<typeof boxxySource>): WorkFact {
+  return scopeFactSchema.parse({
+    id: `event:boxxy:${fact.event}`,
+    type: fact.type,
+    entity: fact.entity,
+    at: fact.at,
+    payload: fact.payload,
+  });
+}