@boxxy/pepys 0.1.3 → 0.1.5

package/dist/generated/boxxy-work-boundary.d.ts

@@ -51,7 +51,7 @@ export interface BoxxyItemFiledPayloadAcceptanceItem {
     evidence: string[];
 }
 export interface BoxxyItemFiledPayloadFields {
-    designMode: unknown;
+    designMode?: 'agent' | 'attended';
 }
 export interface BoxxyItemNotedPayload {
     seq: number;
@@ -59,15 +59,23 @@ export interface BoxxyItemNotedPayload {
     storeVersion: number;
 }
 export interface BoxxyItemEditedPayload {
-    title: unknown;
-    outcome: unknown;
-    acceptance: unknown;
-    kind: unknown;
-    fields: unknown;
-    labels: unknown;
+    title?: string;
+    outcome?: string;
+    acceptance?: BoxxyItemEditedPayloadAcceptanceItem[];
+    kind?: string;
+    fields?: BoxxyItemEditedPayloadFields;
+    labels?: string[];
     byAttempt: string | null;
     storeVersion: number;
 }
+export interface BoxxyItemEditedPayloadAcceptanceItem {
+    id: string;
+    text: string;
+    evidence: string[];
+}
+export interface BoxxyItemEditedPayloadFields {
+    designMode?: 'agent' | 'attended';
+}
 export interface BoxxyItemClosedPayload {
     reason: string;
     byAttempt: string | null;

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.5",
   "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,20 +40,49 @@
     "typecheck": "tsrs --noEmit"
   },
   "dependencies": {
-    "@boxxy/model": "0.1.3"
+    "@boxxy/model": "0.1.5"
   },
   "devDependencies": {
-    "@pepys/cli": "https://github.com/zgeoff/pepys/releases/download/preview-kit-0.0.1/pepys-cli-0.0.1.tgz",
-    "@pepys/kit": "https://github.com/zgeoff/pepys/releases/download/preview-kit-0.0.1/pepys-kit-0.0.1.tgz",
-    "@pepys/kysely-turso": "https://github.com/zgeoff/pepys/releases/download/preview-kit-0.0.1/pepys-kysely-turso-0.0.1.tgz",
-    "@pepys/schema": "https://github.com/zgeoff/pepys/releases/download/preview-kit-0.0.1/pepys-schema-0.0.1.tgz",
-    "@pepys/testing": "https://github.com/zgeoff/pepys/releases/download/preview-kit-0.0.1/pepys-testing-0.0.1.tgz",
+    "@orpc/client": "2.0.0-beta.50",
+    "@pepys/api": "0.1.0",
+    "@pepys/cli": "0.1.0",
+    "@pepys/ingest": "0.1.0",
+    "@pepys/kit": "0.1.0",
+    "@pepys/source-github": "0.1.0",
+    "@pepys/source-telemetry": "0.1.0",
+    "@pepys/testing": "0.1.0",
     "zod": "4.6.7"
   },
   "peerDependencies": {
-    "@pepys/kit": "0.0.1",
+    "@orpc/client": "2.0.0-beta.50",
+    "@pepys/api": "^0.1.0",
+    "@pepys/ingest": "^0.1.0",
+    "@pepys/kit": "^0.1.0",
+    "@pepys/source-github": "^0.1.0",
+    "@pepys/source-telemetry": "^0.1.0",
+    "@pepys/testing": "^0.1.0",
     "zod": "4.6.7"
   },
+  "peerDependenciesMeta": {
+    "@orpc/client": {
+      "optional": true
+    },
+    "@pepys/api": {
+      "optional": true
+    },
+    "@pepys/ingest": {
+      "optional": true
+    },
+    "@pepys/source-github": {
+      "optional": true
+    },
+    "@pepys/source-telemetry": {
+      "optional": true
+    },
+    "@pepys/testing": {
+      "optional": true
+    }
+  },
   "engines": {
     "bun": ">=1.3",
     "node": ">=24"

package/src/generated/boxxy-work-boundary.ts

@@ -125,7 +125,7 @@ export interface BoxxyItemFiledPayloadAcceptanceItem {
 }
 
 export interface BoxxyItemFiledPayloadFields {
-  designMode: unknown;
+  designMode?: 'agent' | 'attended';
 }
 
 export interface BoxxyItemNotedPayload {
@@ -135,16 +135,26 @@ export interface BoxxyItemNotedPayload {
 }
 
 export interface BoxxyItemEditedPayload {
-  title: unknown;
-  outcome: unknown;
-  acceptance: unknown;
-  kind: unknown;
-  fields: unknown;
-  labels: unknown;
+  title?: string;
+  outcome?: string;
+  acceptance?: BoxxyItemEditedPayloadAcceptanceItem[];
+  kind?: string;
+  fields?: BoxxyItemEditedPayloadFields;
+  labels?: string[];
   byAttempt: string | null;
   storeVersion: number;
 }
 
+export interface BoxxyItemEditedPayloadAcceptanceItem {
+  id: string;
+  text: string;
+  evidence: string[];
+}
+
+export interface BoxxyItemEditedPayloadFields {
+  designMode?: 'agent' | 'attended';
+}
+
 export interface BoxxyItemClosedPayload {
   reason: string;
   byAttempt: string | null;
@@ -955,10 +965,15 @@ function decodeBoxxyItemFiledPayloadFields(value: unknown): BoxxyItemFiledPayloa
     return undefined;
   }
 
-  const field0 = 'designMode' in value ? value.designMode : undefined;
+  const raw0 = 'designMode' in value ? value.designMode : undefined;
+  const field0 = raw0 === undefined ? undefined : raw0 === 'agent' || raw0 === 'attended' ? raw0 : undefined;
+
+  if (raw0 !== undefined && field0 === undefined) {
+    return undefined;
+  }
 
   return {
-    designMode: field0,
+    ...(field0 === undefined ? {} : { designMode: field0 }),
   };
 }
 
@@ -1021,17 +1036,47 @@ function decodeBoxxyItemEditedPayload(value: unknown): BoxxyItemEditedPayload |
     return undefined;
   }
 
-  const field0 = 'title' in value ? value.title : undefined;
+  const raw0 = 'title' in value ? value.title : undefined;
+  const field0 = raw0 === undefined ? undefined : typeof raw0 === 'string' ? raw0 : undefined;
+
+  if (raw0 !== undefined && field0 === undefined) {
+    return undefined;
+  }
+
+  const raw1 = 'outcome' in value ? value.outcome : undefined;
+  const field1 = raw1 === undefined ? undefined : typeof raw1 === 'string' ? raw1 : undefined;
+
+  if (raw1 !== undefined && field1 === undefined) {
+    return undefined;
+  }
+
+  const raw2 = 'acceptance' in value ? value.acceptance : undefined;
+  const field2 = raw2 === undefined ? undefined : decodeBoxxyItemEditedPayloadAcceptance(raw2);
 
-  const field1 = 'outcome' in value ? value.outcome : undefined;
+  if (raw2 !== undefined && field2 === undefined) {
+    return undefined;
+  }
 
-  const field2 = 'acceptance' in value ? value.acceptance : undefined;
+  const raw3 = 'kind' in value ? value.kind : undefined;
+  const field3 = raw3 === undefined ? undefined : typeof raw3 === 'string' ? raw3 : undefined;
 
-  const field3 = 'kind' in value ? value.kind : undefined;
+  if (raw3 !== undefined && field3 === undefined) {
+    return undefined;
+  }
 
-  const field4 = 'fields' in value ? value.fields : undefined;
+  const raw4 = 'fields' in value ? value.fields : undefined;
+  const field4 = raw4 === undefined ? undefined : decodeBoxxyItemEditedPayloadFields(raw4);
 
-  const field5 = 'labels' in value ? value.labels : undefined;
+  if (raw4 !== undefined && field4 === undefined) {
+    return undefined;
+  }
+
+  const raw5 = 'labels' in value ? value.labels : undefined;
+  const field5 = raw5 === undefined ? undefined : decodeBoxxyItemEditedPayloadLabels(raw5);
+
+  if (raw5 !== undefined && field5 === undefined) {
+    return undefined;
+  }
 
   const raw6 = 'byAttempt' in value ? value.byAttempt : undefined;
   const field6 = raw6 === null ? null : typeof raw6 === 'string' ? raw6 : undefined;
@@ -1048,17 +1093,130 @@ function decodeBoxxyItemEditedPayload(value: unknown): BoxxyItemEditedPayload |
   }
 
   return {
-    title: field0,
-    outcome: field1,
-    acceptance: field2,
-    kind: field3,
-    fields: field4,
-    labels: field5,
+    ...(field0 === undefined ? {} : { title: field0 }),
+    ...(field1 === undefined ? {} : { outcome: field1 }),
+    ...(field2 === undefined ? {} : { acceptance: field2 }),
+    ...(field3 === undefined ? {} : { kind: field3 }),
+    ...(field4 === undefined ? {} : { fields: field4 }),
+    ...(field5 === undefined ? {} : { labels: field5 }),
     byAttempt: field6,
     storeVersion: field7,
   };
 }
 
+function decodeBoxxyItemEditedPayloadAcceptance(value: unknown): BoxxyItemEditedPayloadAcceptanceItem[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+
+  const items: BoxxyItemEditedPayloadAcceptanceItem[] = [];
+
+  for (let index = 0; index < value.length; index += 1) {
+    const element: unknown = value[index];
+    const item = decodeBoxxyItemEditedPayloadAcceptanceItem(element);
+
+    if (item === undefined) {
+      return undefined;
+    }
+
+    items.push(item);
+  }
+
+  return items;
+}
+
+function decodeBoxxyItemEditedPayloadAcceptanceItem(value: unknown): BoxxyItemEditedPayloadAcceptanceItem | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+
+  const raw0 = 'id' in value ? value.id : undefined;
+  const field0 = typeof raw0 === 'string' ? raw0 : undefined;
+
+  if (field0 === undefined) {
+    return undefined;
+  }
+
+  const raw1 = 'text' in value ? value.text : undefined;
+  const field1 = typeof raw1 === 'string' ? raw1 : undefined;
+
+  if (field1 === undefined) {
+    return undefined;
+  }
+
+  const raw2 = 'evidence' in value ? value.evidence : undefined;
+  const field2 = decodeBoxxyItemEditedPayloadAcceptanceItemEvidence(raw2);
+
+  if (field2 === undefined) {
+    return undefined;
+  }
+
+  return {
+    id: field0,
+    text: field1,
+    evidence: field2,
+  };
+}
+
+function decodeBoxxyItemEditedPayloadAcceptanceItemEvidence(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+
+  const items: string[] = [];
+
+  for (let index = 0; index < value.length; index += 1) {
+    const element: unknown = value[index];
+    const item = typeof element === 'string' ? element : undefined;
+
+    if (item === undefined) {
+      return undefined;
+    }
+
+    items.push(item);
+  }
+
+  return items;
+}
+
+function decodeBoxxyItemEditedPayloadFields(value: unknown): BoxxyItemEditedPayloadFields | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+
+  const raw0 = 'designMode' in value ? value.designMode : undefined;
+  const field0 = raw0 === undefined ? undefined : raw0 === 'agent' || raw0 === 'attended' ? raw0 : undefined;
+
+  if (raw0 !== undefined && field0 === undefined) {
+    return undefined;
+  }
+
+  return {
+    ...(field0 === undefined ? {} : { designMode: field0 }),
+  };
+}
+
+function decodeBoxxyItemEditedPayloadLabels(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+
+  const items: string[] = [];
+
+  for (let index = 0; index < value.length; index += 1) {
+    const element: unknown = value[index];
+    const item = typeof element === 'string' ? element : undefined;
+
+    if (item === undefined) {
+      return undefined;
+    }
+
+    items.push(item);
+  }
+
+  return items;
+}
+
 function decodeBoxxyItemClosedPayload(value: unknown): BoxxyItemClosedPayload | undefined {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) {
     return undefined;

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,
+  };
+}