@boxxy/pepys 0.1.3 → 0.1.5

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-real-pepys.ts

@@ -0,0 +1,286 @@
+import { createORPCClient } from '@orpc/client';
+import { RPCLink } from '@orpc/client/fetch';
+import { buildQueryContext, createApp } from '@pepys/api';
+import { createFakeSenderProof, createIngest, createMemoryFactLog } from '@pepys/ingest';
+import { checkDeployment, parseStreamName } from '@pepys/kit';
+import type {
+  FactBatchBody,
+  FactEnvelope,
+  Sender,
+  SourceDefinition,
+  StreamName,
+  StreamOffset,
+} from '@pepys/kit';
+import {
+  githubDeliveryConsumers,
+  githubPlugin,
+  githubPullRequestConsumer,
+  parsePullRequestDeliveries,
+  selectPullRequestDelivery,
+} from '@pepys/source-github';
+import {
+  telemetryModelRequestConsumer,
+  telemetryPlugin,
+  telemetryTurnCostConsumer,
+} from '@pepys/source-telemetry';
+import { createTestStore } from '@pepys/testing';
+import type { AppliedFact } from '@pepys/testing';
+import { buildBoxxyPlugin } from '../build-boxxy-plugin.ts';
+import type { DeliveryReads, ForeignReads } from '../queries/types.ts';
+import type { UncheckedQueryClient } from '../types.ts';
+import type { TelemetryRequest, TestPepys, TestPepysOptions } from './create-test-pepys.ts';
+
+// The pull requests that the item's attempts produced, as boxxy's own rows give them, and then
+// the GitHub plug-in's delivery module on those pull requests.
+const delivery: DeliveryReads = {
+  consumers: [...githubDeliveryConsumers],
+  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()
+      .execute();
+
+    const [first, ...rest] = produced.map((row) => row.id);
+
+    if (first === undefined) {
+      return [];
+    }
+
+    const result = await selectPullRequestDelivery({
+      pullRequests: [first, ...rest],
+      environment: input.environment,
+    }).execute(db);
+
+    return parsePullRequestDeliveries(result.rows).map((row) => ({
+      pullRequest: row.pullRequest,
+      mergedAt: row.mergedAt,
+      release: row.release === null ? null : { at: row.release.at },
+      deploy: row.deploy === null ? null : { at: row.deploy.at },
+    }));
+  },
+};
+
+const foreign: ForeignReads = {
+  telemetryModelRequest: telemetryModelRequestConsumer,
+  telemetryTurnCost: telemetryTurnCostConsumer,
+  githubPullRequest: githubPullRequestConsumer,
+  delivery,
+};
+
+const telemetryToken = 'telemetry-test-token';
+
+// The real pepys ingest, the GitHub, telemetry and boxxy plug-ins, and the real query API, in
+// process. Ingest appends to its memory fact log. A host applies the log to the store; here each
+// query first applies what is new to the kit's test store, which the API then reads.
+export async function createRealPepys(options: TestPepysOptions): Promise<TestPepys> {
+  const plugins = [buildBoxxyPlugin(foreign), githubPlugin, telemetryPlugin];
+  const checked = checkDeployment({ name: 'boxxy-system-test', plugins });
+
+  if (!checked.ok) {
+    throw new Error(`the deployment does not check: ${JSON.stringify(checked.failure)}`);
+  }
+
+  const deployment = checked.value;
+
+  const streams = deployment.sources
+    .flatMap((source) => source.families.map((family) => family.stream))
+    .filter((stream) => isStreamName(stream));
+
+  const log = createMemoryFactLog(streams);
+  const senders: Record<string, Sender> = {};
+
+  const ingest = createIngest({
+    deployment,
+    secrets: {
+      PEPYS_BOXXY_SIGNING_SECRET: options.boxxySecret,
+      PEPYS_GITHUB_WEBHOOK_SECRET: options.webhookSecret,
+      PEPYS_TELEMETRY_TOKEN: telemetryToken,
+      PEPYS_GITHUB_APP_ID: '1',
+      PEPYS_GITHUB_APP_PRIVATE_KEY: 'unused',
+    },
+    log,
+    senderProof: createFakeSenderProof(senders),
+    appendRetry: { maxAttempts: 1, retryDelayMs: 0 },
+    now: () => Date.now(),
+  });
+
+  const store = await createTestStore({ plugins });
+
+  const applied = new Map<StreamName, StreamOffset>();
+
+  for (const stream of streams) {
+    const tail = await log.readTail(stream);
+
+    if (tail.ok) {
+      applied.set(stream, tail.value);
+    }
+  }
+
+  const applyLog = async () => {
+    for (const source of deployment.sources) {
+      for (const stream of source.families.map((family) => family.stream)) {
+        await applyStream(source, stream);
+      }
+    }
+  };
+
+  const applyStream = async (source: SourceDefinition, name: string) => {
+    const from = isStreamName(name) ? applied.get(name) : undefined;
+
+    if (!isStreamName(name) || from === undefined) {
+      throw new Error(`the log holds no stream ${name}`);
+    }
+
+    const tail = await log.readTail(name);
+
+    const read = tail.ok ? await log.read(name, from, tail.value - from) : tail;
+
+    if (!tail.ok || !read.ok) {
+      throw new Error(`the log refused a read of ${name}`);
+    }
+
+    const facts = read.value
+      .map((stored) => toOutgoingFact(source.name, stored.fact))
+      .filter((fact) => isAppliedFact(source, fact));
+
+    if (facts.length !== read.value.length) {
+      throw new Error(`the log holds a fact of ${name} that the source's families refuse`);
+    }
+
+    if (facts.length > 0) {
+      await store.apply(source, facts);
+    }
+
+    applied.set(name, tail.value);
+  };
+
+  const app = createApp(buildQueryContext(store.reader, deployment));
+  const sendRequest = (url: string, init: RequestInit) => app.handle(new Request(url, init));
+
+  const api = createORPCClient<UncheckedQueryClient>(
+    new RPCLink({ origin: 'http://pepys.test', url: '/rpc', fetch: sendRequest }),
+  );
+
+  return {
+    handleRequest: (request) => ingest.handleRequest(request),
+    client: {
+      boxxy_cost_to_land: async (input) => {
+        await applyLog();
+
+        return api.boxxy_cost_to_land(input);
+      },
+      boxxy_stage_time: async (input) => {
+        await applyLog();
+
+        return api.boxxy_stage_time(input);
+      },
+    },
+    writeTelemetry: async (requests) => {
+      for (const request of requests) {
+        const token = `token-${request.origin.issuer}-${request.origin.subject}`;
+
+        senders[token] = { ...request.origin, name: request.origin.subject };
+
+        const body = JSON.stringify(buildOTLPLogs(request));
+
+        const answer = await ingest.handleRequest(
+          new Request('http://pepys.test/v1/logs', {
+            method: 'POST',
+            headers: {
+              authorization: `Bearer ${telemetryToken}`,
+              'imp-identity': token,
+              'content-type': 'application/json',
+            },
+            body,
+          }),
+        );
+
+        if (answer.status !== 200) {
+          throw new Error(`telemetry answered ${answer.status}: ${await answer.text()}`);
+        }
+      }
+    },
+    [Symbol.asyncDispose]: () => store[Symbol.asyncDispose](),
+  };
+}
+
+// The kit tags a stream name it has parsed; a declared family stream always parses.
+function isStreamName(name: string): name is StreamName {
+  return parseStreamName(name).ok;
+}
+
+type WireFact = FactBatchBody['facts'][number];
+
+// 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(sourceName: string, fact: FactEnvelope<unknown>): WireFact {
+  return {
+    type: fact.type,
+    event: fact.id.replace(`event:${sourceName}:`, ''),
+    entity: fact.entity,
+    ...(fact.actor === undefined ? {} : { actor: fact.actor }),
+    at: fact.at,
+    payload: fact.payload,
+  };
+}
+
+// The check that ingest made before it stored the fact: a type of one of the source's families,
+// with a payload that the type's schema accepts.
+function isAppliedFact(
+  source: SourceDefinition,
+  fact: WireFact,
+): fact is WireFact & AppliedFact<SourceDefinition> {
+  return source.families.some(
+    (family) =>
+      Object.hasOwn(family.types, fact.type) &&
+      family.types[fact.type]?.safeParse(fact.payload).success === true,
+  );
+}
+
+// One Claude Code `api_request` log record in an OTLP logs body, as the telemetry route reads it.
+function buildOTLPLogs(request: TelemetryRequest) {
+  const nanos = `${Date.parse(request.at)}000000`;
+
+  const record = {
+    timeUnixNano: nanos,
+    observedTimeUnixNano: nanos,
+    body: { stringValue: 'event' },
+    attributes: buildOTLPAttributes({
+      'event.name': 'api_request',
+      'session.id': `agent-of-${request.session}`,
+      'event.timestamp': request.at,
+      request_id: request.id,
+      model: request.model,
+      cost_usd: request.costUSD,
+      input_tokens: request.inputTokens,
+      cache_read_tokens: 0,
+      cache_creation_tokens: 0,
+      output_tokens: request.outputTokens,
+      duration_ms: 1000,
+    }),
+  };
+
+  const scope = { scope: { name: 'com.anthropic.claude_code.events' }, logRecords: [record] };
+  const resource = { attributes: buildOTLPAttributes({ 'atc.session.id': request.session }) };
+
+  return { resourceLogs: [{ resource, scopeLogs: [scope] }] };
+}
+
+function buildOTLPAttributes(values: Record<string, string | number>) {
+  return Object.entries(values).map(([key, value]) => ({ key, value: toOTLPValue(key, value) }));
+}
+
+// OTLP sends an integer as text; the cost is a double even when it is whole.
+function toOTLPValue(key: string, value: string | number) {
+  if (typeof value === 'string') {
+    return { stringValue: value };
+  }
+
+  return Number.isInteger(value) && key !== 'cost_usd'
+    ? { intValue: String(value) }
+    : { doubleValue: value };
+}