@boxxy/model 0.1.2 → 0.1.3

package/src/test-utils/build-mock-cost-to-land.ts

@@ -0,0 +1,31 @@
+import { faker } from '@faker-js/faker';
+import type { CostToLand } from '../reports/types.ts';
+
+// The cost of a landed item: one build line with a reported cost.
+export function buildMockCostToLand(overrides: Partial<CostToLand> = {}): CostToLand {
+  const costUSD = faker.number.float({ min: 0.5, max: 20, fractionDigits: 2 });
+  const requests = faker.number.int({ min: 1, max: 80 });
+
+  return {
+    item: `boxxy:item:${faker.string.uuid({ version: 7 })}`,
+    landedAt: '2026-11-11T06:00:00Z',
+    attempts: 1,
+    lines: [
+      {
+        phase: 'build',
+        rework: false,
+        product: 'claude_code',
+        model: 'model-large',
+        requests,
+        inputTokens: requests * 10,
+        cacheReadTokens: requests * 1000,
+        cacheCreationTokens: requests * 50,
+        outputTokens: requests * 300,
+        costUSD,
+        costBasis: 'reported',
+      },
+    ],
+    totals: { requests, costUSD, reworkCostUSD: 0, requestsWithoutCost: 0 },
+    ...overrides,
+  };
+}

package/src/test-utils/build-mock-evidence-row.ts

@@ -1,6 +1,6 @@
 import { faker } from '@faker-js/faker';
-import { brandSchemas } from '../brand-schemas.ts';
-import type { EvidenceRow } from '../types/core.ts';
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import type { EvidenceRow } from '../types.ts';
 import { buildMockFactId } from './build-mock-fact-id.ts';
 
 export function buildMockEvidenceRow(overrides: Partial<EvidenceRow> = {}): EvidenceRow {

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

@@ -1,7 +1,7 @@
 import { faker } from '@faker-js/faker';
-import { brandSchemas } from '../brand-schemas.ts';
-import type { FactId } from '../types/core.ts';
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import type { FactId } from '../types.ts';
 
 export function buildMockFactId(): FactId {
-  return brandSchemas.factId.parse(`manual:${faker.string.uuid({ version: 7 })}`);
+  return brandSchemas.factId.parse(faker.string.uuid({ version: 7 }));
 }

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

@@ -1,9 +1,14 @@
-import { brandSchemas } from '../brand-schemas.ts';
-import type { FrameItem } from '../types/planning.ts';
-import { buildMockItemView } from './build-mock-item-view.ts';
+import type { FrameItem } from '../planning/types.ts';
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import { buildMockV1ItemView } from './build-mock-v1-item-view.ts';
 
+// The item's position is the phase and round of the frame item, unless an override sets it.
 export function buildMockFrameItem(overrides: Partial<FrameItem> = {}): FrameItem {
-  const { phase, ...view } = overrides;
+  const { phase = brandSchemas.phaseName.parse('build'), round = 1, ...view } = overrides;
 
-  return { ...buildMockItemView(view), phase: phase ?? brandSchemas.phaseName.parse('build') };
+  return {
+    ...buildMockV1ItemView({ position: { kind: 'phase', phase, round }, ...view }),
+    phase,
+    round,
+  };
 }

package/src/test-utils/build-mock-frame.ts

@@ -0,0 +1,13 @@
+import type { Frame } from '../planning/types.ts';
+
+export function buildMockFrame(overrides: Partial<Frame> = {}): Frame {
+  return {
+    candidates: [],
+    fields: new Map(),
+    values: new Map(),
+    holds: new Map(),
+    lifted: new Map(),
+    faults: [],
+    ...overrides,
+  };
+}

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

@@ -0,0 +1,17 @@
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import type { ItemRules } from '../rules/types.ts';
+import { buildMockPipeline } from './build-mock-pipeline.ts';
+
+// `core.issue` and `core.task` run the build phase alone; no phase needs acceptance criteria.
+export function buildMockItemRules(overrides: Partial<ItemRules> = {}): ItemRules {
+  const pipeline = buildMockPipeline({ phases: ['build'] });
+
+  return {
+    kinds: new Map([
+      [brandSchemas.itemKindName.parse('core.issue'), { pipeline }],
+      [brandSchemas.itemKindName.parse('core.task'), { pipeline }],
+    ]),
+    phases: new Map(),
+    ...overrides,
+  };
+}

package/src/test-utils/build-mock-lease-row.ts

@@ -1,6 +1,6 @@
 import { faker } from '@faker-js/faker';
-import { brandSchemas } from '../brand-schemas.ts';
-import type { LeaseRow } from '../types/core.ts';
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import type { LeaseRow } from '../types.ts';
 
 export function buildMockLeaseRow(overrides: Partial<LeaseRow> = {}): LeaseRow {
   return {

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

@@ -0,0 +1,22 @@
+import type { OutboxFact } from '../facts/types.ts';
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import { buildMockFactId } from './build-mock-fact-id.ts';
+
+// An unsent, unparked `boxxy.item.noted` row for the item `i-<seq>`.
+export function buildMockOutboxFact(overrides: Partial<OutboxFact> = {}): OutboxFact {
+  const seq = overrides.seq ?? 1;
+
+  return {
+    seq,
+    factId: buildMockFactId(),
+    type: 'boxxy.item.noted',
+    entity: `boxxy:item:i-${seq}`,
+    actor: 'boxxy:owner:local',
+    at: brandSchemas.instant.parse(1_800_000_000_000 + seq),
+    payload: { seq, text: 'a note' },
+    sentAt: null,
+    parkedAt: null,
+    parkedReason: null,
+    ...overrides,
+  };
+}

package/src/test-utils/build-mock-phase-kind.ts

@@ -0,0 +1,29 @@
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import { definePhase } from '../rules/define-phase.ts';
+import type { PhaseKind } from '../rules/types.ts';
+
+interface MockPhaseKindInput {
+  readonly name: string;
+  readonly outcomes: readonly string[];
+}
+
+// A phase kind with only a name and an outcome list: its close-out is any value, and it settles
+// with its first outcome.
+export function buildMockPhaseKind(input: MockPhaseKindInput): PhaseKind {
+  return definePhase({
+    name: brandSchemas.phaseName.parse(input.name),
+    version: 1,
+    worker: brandSchemas.workerKindName.parse('atc.session'),
+    outcomes: input.outcomes,
+    needsAcceptance: false,
+    input: () => ({}),
+    closeOut: { parse: (raw) => ({ kind: 'valid', closeOut: raw }), jsonSchema: {} },
+    settle: () => ({
+      state: 'succeeded',
+      failure: null,
+      outcome: input.outcomes[0] ?? '',
+      effects: [],
+      frictionDropped: 0,
+    }),
+  });
+}

package/src/test-utils/build-mock-pipeline.ts

@@ -0,0 +1,52 @@
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import type { Edge, Pipeline, PipelineStep } from '../rules/types.ts';
+
+const standardOrder = ['triage', 'design', 'build', 'review'];
+
+const standardEdges: Readonly<Record<string, Readonly<Record<string, Edge>>>> = {
+  triage: {
+    accepted: 'next',
+    duplicate: { hold: brandSchemas.rulesHoldReason.parse('duplicate') },
+    declined: { hold: brandSchemas.rulesHoldReason.parse('declined') },
+  },
+  design: {
+    designed: 'next',
+    blocked: { hold: brandSchemas.rulesHoldReason.parse('blocked') },
+    abandoned: 'again',
+  },
+  build: {
+    built: 'next',
+    blocked: { hold: brandSchemas.rulesHoldReason.parse('blocked') },
+    abandoned: 'again',
+  },
+  review: {
+    passed: { end: 'reviewed' },
+    'changes-requested': { to: brandSchemas.phaseName.parse('build'), max: 3, resume: true },
+  },
+};
+
+interface MockPipelineInput {
+  // the phases in order; the four standard phases when left out
+  readonly phases?: readonly string[];
+
+  // fields to replace on the step of a phase; `on` is replaced whole
+  readonly steps?: Readonly<Record<string, Partial<PipelineStep>>>;
+}
+
+// The `standard` pipeline of the v1 rules file: triage, design, build and review, with two
+// attempts in a row for each step.
+export function buildMockPipeline(input: MockPipelineInput = {}): Pipeline {
+  const steps: PipelineStep[] = [];
+
+  for (const phase of input.phases ?? standardOrder) {
+    steps.push({
+      phase: brandSchemas.phaseName.parse(phase),
+      maxAttempts: 2,
+      timeoutMinutes: 30,
+      on: standardEdges[phase] ?? {},
+      ...input.steps?.[phase],
+    });
+  }
+
+  return { name: brandSchemas.pipelineName.parse('standard'), steps };
+}

package/src/test-utils/{build-mock-link-row.ts → build-mock-relation-row.ts}

@@ -1,12 +1,12 @@
 import { faker } from '@faker-js/faker';
-import { brandSchemas } from '../brand-schemas.ts';
-import type { LinkRow } from '../types/core.ts';
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import type { RelationRow } from '../types.ts';
 
-export function buildMockLinkRow(overrides: Partial<LinkRow> = {}): LinkRow {
+export function buildMockRelationRow(overrides: Partial<RelationRow> = {}): RelationRow {
   return {
     source: brandSchemas.itemId.parse(faker.string.uuid({ version: 7 })),
     target: brandSchemas.itemId.parse(faker.string.uuid({ version: 7 })),
-    type: brandSchemas.linkTypeName.parse('blocks'),
+    type: brandSchemas.relationTypeName.parse('blocks'),
     addedBy: 'boxxy:owner:local',
     addedAt: brandSchemas.instant.parse(faker.number.int({ max: 1_800_000_000_000 })),
     removedAt: null,

package/src/test-utils/build-mock-settled.ts

@@ -0,0 +1,18 @@
+import type { Settled } from '../pipeline/types.ts';
+import { brandSchemas } from '../rows/brand-schemas.ts';
+
+interface MockSettledInput {
+  readonly phase: string;
+  readonly outcome: string;
+  readonly endedAt: number;
+  readonly failure?: string | null;
+}
+
+export function buildMockSettled(input: MockSettledInput): Settled {
+  return {
+    phase: brandSchemas.phaseName.parse(input.phase),
+    outcome: input.outcome,
+    endedAt: brandSchemas.instant.parse(input.endedAt),
+    failure: input.failure ?? null,
+  };
+}

package/src/test-utils/build-mock-snapshot.ts

@@ -1,5 +1,13 @@
-import type { Snapshot } from '../types/planning.ts';
+import type { Snapshot } from '../planning/types.ts';
 
 export function buildMockSnapshot(overrides: Partial<Snapshot> = {}): Snapshot {
-  return { storeVersion: 1, items: [], links: [], levers: [], freeSlots: {}, ...overrides };
+  return {
+    storeVersion: 1,
+    items: [],
+    relations: [],
+    levers: [],
+    limits: [],
+    wakes: [],
+    ...overrides,
+  };
 }

package/src/test-utils/{build-mock-attempt-row.ts → build-mock-v1-attempt-row.ts}

@@ -1,11 +1,13 @@
 import { contentHash } from '@boxxy/content-hash';
 import { faker } from '@faker-js/faker';
-import { brandSchemas } from '../brand-schemas.ts';
-import type { AttemptRow } from '../types/core.ts';
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import type { AttemptRow } from '../types.ts';
 
 const hashOptions = { length: 64, casing: 'lower', prefix: '' } as const;
 
-export function buildMockAttemptRow(overrides: Partial<AttemptRow> = {}): AttemptRow {
+// A running agent-mode build attempt of round 1. `buildMockAttemptRow` still builds the slice 1
+// row that the store reads and writes.
+export function buildMockV1AttemptRow(overrides: Partial<AttemptRow> = {}): AttemptRow {
   const spawnRequest =
     overrides.spawnRequest === undefined
       ? { prompt: faker.lorem.sentence() }
@@ -19,19 +21,36 @@ export function buildMockAttemptRow(overrides: Partial<AttemptRow> = {}): Attemp
     runner: brandSchemas.runnerId.parse('runner-1'),
     recipeHash: brandSchemas.recipeHash.parse(faker.string.hexadecimal(hashOptions)),
     rulesVersion: brandSchemas.rulesVersion.parse(faker.string.hexadecimal(hashOptions)),
-    pool: brandSchemas.poolName.parse('build'),
-    slot: 1,
-    slotGen: 1,
+    pool: brandSchemas.poolName.parse('main'),
     leaseGen: 1,
     spawnRequest,
     spawnRequestHash: contentHash(spawnRequest),
-    state: 'succeeded',
+    state: 'running',
     failure: null,
     atcSession: brandSchemas.atcSessionId.parse(faker.string.uuid()),
-    closeOut: null,
+    caller: null,
     claimedAt: brandSchemas.instant.parse(faker.number.int({ max: 1_800_000_000_000 })),
     startedAt: brandSchemas.instant.parse(faker.number.int({ max: 1_800_000_000_000 })),
-    endedAt: brandSchemas.instant.parse(faker.number.int({ max: 1_800_000_000_000 })),
+    endedAt: null,
+    fields: {},
+    mode: 'agent',
+    round: 1,
+    input: {},
+    holdGen: 1,
+    closeOut: null,
+    closeOutHash: null,
+    closeOutFact: null,
+    closing: null,
+    closingAt: null,
+    suspendRequestedAt: null,
+    sleptAt: null,
+    wakeRequestedAt: null,
+    wokenAt: null,
+    outcome: null,
+    returnedOutcome: null,
+    strayedAt: null,
+    sessionStoppedAt: null,
+    sessionForgottenAt: null,
     ...overrides,
   };
 }

package/src/test-utils/{build-mock-item-row.ts → build-mock-v1-item-row.ts}

@@ -1,8 +1,9 @@
 import { faker } from '@faker-js/faker';
-import { brandSchemas } from '../brand-schemas.ts';
-import type { ItemRow } from '../types/core.ts';
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import type { ItemRow } from '../types.ts';
 
-export function buildMockItemRow(overrides: Partial<ItemRow> = {}): ItemRow {
+// An open issue with one acceptance criterion, no labels and no kept session.
+export function buildMockV1ItemRow(overrides: Partial<ItemRow> = {}): ItemRow {
   return {
     id: brandSchemas.itemId.parse(faker.string.uuid({ version: 7 })),
     kind: brandSchemas.itemKindName.parse('core.issue'),
@@ -12,11 +13,14 @@ export function buildMockItemRow(overrides: Partial<ItemRow> = {}): ItemRow {
     acceptance: [
       { id: brandSchemas.criterionId.parse('a1'), text: faker.lorem.sentence(), evidence: [] },
     ],
+    fields: {},
+    labels: [],
     foundInAttempt: null,
     filedBy: 'boxxy:owner:local',
     filedAt: brandSchemas.instant.parse(faker.number.int({ max: 1_800_000_000_000 })),
     closedAt: null,
     closeReason: null,
+    keptSession: null,
     ...overrides,
   };
 }

package/src/test-utils/build-mock-v1-item-view.ts

@@ -0,0 +1,29 @@
+import { faker } from '@faker-js/faker';
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import type { ItemView } from '../types.ts';
+
+// A ready item at the build phase of round 1. `buildMockItemView` still builds the slice 1 view
+// that the store reads.
+export function buildMockV1ItemView(overrides: Partial<ItemView> = {}): ItemView {
+  return {
+    id: brandSchemas.itemId.parse(faker.string.uuid({ version: 7 })),
+    kind: brandSchemas.itemKindName.parse('core.issue'),
+    repo: brandSchemas.repoName.parse(`${faker.word.noun()}/${faker.word.noun()}`),
+    title: faker.lorem.sentence(),
+    outcome: faker.lorem.sentence(),
+    acceptance: [
+      { id: brandSchemas.criterionId.parse('a1'), text: faker.lorem.sentence(), evidence: [] },
+    ],
+    fields: {},
+    labels: [],
+    foundInAttempt: null,
+    filedBy: 'boxxy:owner:local',
+    filedAt: brandSchemas.instant.parse(faker.number.int({ max: 1_800_000_000_000 })),
+    closedAt: null,
+    closeReason: null,
+    keptSession: null,
+    derived: { state: 'ready' },
+    position: { kind: 'phase', phase: brandSchemas.phaseName.parse('build'), round: 1 },
+    ...overrides,
+  };
+}

package/src/test-utils/{build-mock-lever-row.ts → build-mock-v1-lever-row.ts}

@@ -1,8 +1,9 @@
 import { faker } from '@faker-js/faker';
-import { brandSchemas } from '../brand-schemas.ts';
-import type { LeverRow } from '../types/core.ts';
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import type { LeverRow } from '../types.ts';
 
-export function buildMockLeverRow(overrides: Partial<LeverRow> = {}): LeverRow {
+// A defer lever with no phase.
+export function buildMockV1LeverRow(overrides: Partial<LeverRow> = {}): LeverRow {
   return {
     seq: faker.number.int({ min: 1, max: 10_000 }),
     kind: 'plan.defer',
@@ -10,6 +11,7 @@ export function buildMockLeverRow(overrides: Partial<LeverRow> = {}): LeverRow {
     until: null,
     expiresAt: null,
     reason: faker.lorem.sentence(),
+    phase: null,
     actor: 'boxxy:owner:local',
     at: brandSchemas.instant.parse(faker.number.int({ max: 1_800_000_000_000 })),
     ...overrides,

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

@@ -0,0 +1,26 @@
+import { faker } from '@faker-js/faker';
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import type { PullRequestRow } from '../types.ts';
+
+// An open pull request, with its URL built from its repo and number. `buildMockPullRequestRow`
+// still builds the slice 1 row.
+export function buildMockV1PullRequestRow(overrides: Partial<PullRequestRow> = {}): PullRequestRow {
+  const repo =
+    overrides.repo ??
+    brandSchemas.repoName.parse(`${faker.string.alpha(8)}/${faker.string.alpha(8)}`);
+
+  const number = overrides.number ?? faker.number.int({ min: 1, max: 10_000 });
+
+  return {
+    repo,
+    number,
+    attempt: brandSchemas.attemptId.parse(faker.string.uuid({ version: 7 })),
+    githubId: faker.number.int({ min: 1, max: 2_000_000_000 }),
+    url: `https://github.com/${repo}/pull/${number}`,
+    state: 'open',
+    mergedAt: null,
+    mergeCommit: null,
+    checkedAt: brandSchemas.instant.parse(faker.number.int({ max: 1_800_000_000_000 })),
+    ...overrides,
+  };
+}

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

@@ -0,0 +1,179 @@
+import { contentHash } from '@boxxy/content-hash';
+import { faker } from '@faker-js/faker';
+import type { z } from 'zod';
+import type { EntityRef, OutboxFact, WorkFacts } from '../facts/types.ts';
+import { workFactSchemas } from '../facts/work-fact-schemas.ts';
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import type { Instant } from '../types.ts';
+import { toJSONValue } from '../utils/to-json-value.ts';
+import { buildMockFactId } from './build-mock-fact-id.ts';
+
+// The fact types that the pepys consumer reads.
+export type MockedFactType =
+  | 'boxxy.item.filed'
+  | 'boxxy.item.edited'
+  | 'boxxy.item.closed'
+  | 'boxxy.attempt.claimed'
+  | 'boxxy.attempt.started'
+  | 'boxxy.attempt.reconciled'
+  | 'boxxy.attempt.resumed'
+  | 'boxxy.attempt.session_bound'
+  | 'boxxy.attempt.slept'
+  | 'boxxy.attempt.woken'
+  | 'boxxy.attempt.closed_out'
+  | 'boxxy.attempt.settled'
+  | 'boxxy.pull_request.linked';
+
+// The payload's values are checked by the schema, so a test may give a plain string for a brand.
+interface WorkFactOverrides<Type extends MockedFactType> {
+  readonly payload?: { readonly [Key in keyof WorkFacts[Type]]?: unknown };
+  readonly at?: number;
+  readonly entity?: EntityRef;
+  readonly seq?: number;
+}
+
+const hashOptions = { length: 64, casing: 'lower', prefix: '' } as const;
+
+const defaultPayloads: { readonly [Type in MockedFactType]: () => WorkFacts[Type] } = {
+  'boxxy.item.filed': () => ({
+    id: brandSchemas.itemId.parse(faker.string.uuid({ version: 7 })),
+    kind: brandSchemas.itemKindName.parse('core.issue'),
+    repo: brandSchemas.repoName.parse('shoal/charts'),
+    title: faker.lorem.sentence(),
+    outcome: faker.lorem.sentence(),
+    acceptance: [],
+    fields: {},
+    labels: [],
+    foundInAttempt: null,
+    filedBy: 'boxxy:owner:local',
+    filedAt: toInstant(1_800_000_000_000),
+    closedAt: null,
+    closeReason: null,
+  }),
+  'boxxy.item.edited': () => ({ byAttempt: null }),
+  'boxxy.item.closed': () => ({ reason: 'done', byAttempt: null, ended: [] }),
+  'boxxy.attempt.claimed': () => ({
+    attempt: buildAttemptId(),
+    phase: brandSchemas.phaseName.parse('build'),
+    number: 1,
+    round: 1,
+    mode: 'agent',
+    pool: brandSchemas.poolName.parse('main'),
+    fields: {},
+    seats: [],
+    recipeHash: brandSchemas.recipeHash.parse(faker.string.hexadecimal(hashOptions)),
+    skillsRef: null,
+    rulesVersion: brandSchemas.rulesVersion.parse(faker.string.hexadecimal(hashOptions)),
+  }),
+  'boxxy.attempt.started': () => ({
+    attempt: buildAttemptId(),
+    atcSession: buildAtcSession(),
+    resumeFallback: false,
+    caller: null,
+  }),
+  'boxxy.attempt.reconciled': () => ({
+    attempt: buildAttemptId(),
+    atcSession: buildAtcSession(),
+    caller: null,
+  }),
+  'boxxy.attempt.resumed': () => ({
+    attempt: buildAttemptId(),
+    atcSession: buildAtcSession(),
+    caller: null,
+  }),
+  'boxxy.attempt.session_bound': () => ({
+    attempt: buildAttemptId(),
+    atcSession: buildAtcSession(),
+    agentSession: brandSchemas.agentSessionId.parse(`agent-${faker.string.alphanumeric(8)}`),
+    product: 'claude_code',
+    source: 'hook',
+    seenAt: toInstant(1_800_000_000_000),
+  }),
+  'boxxy.attempt.slept': () => ({
+    attempt: buildAttemptId(),
+    idleSince: toInstant(1_800_000_000_000),
+    asked: true,
+  }),
+  'boxxy.attempt.woken': () => ({
+    attempt: buildAttemptId(),
+    holdGen: 1,
+    seats: [],
+    overCap: false,
+  }),
+  'boxxy.attempt.closed_out': () => {
+    const closeOut = {
+      result: { kind: 'accepted' as const },
+      relations: [],
+      friction: [],
+      frictionDropped: 0,
+    };
+
+    return {
+      attempt: buildAttemptId(),
+      phase: brandSchemas.phaseName.parse('triage'),
+      closeOut,
+      hash: contentHash(closeOut),
+    };
+  },
+  'boxxy.attempt.settled': () => ({
+    attempt: buildAttemptId(),
+    phase: brandSchemas.phaseName.parse('build'),
+    round: 1,
+    state: 'succeeded',
+    failure: null,
+    outcome: 'built',
+    returnedOutcome: null,
+    closing: 'closed-out',
+    asleep: false,
+    sessionStopped: true,
+    endedAt: toInstant(1_800_000_000_000),
+    criteria: [],
+    matched: [],
+    frictionDropped: 0,
+    skippedEffects: [],
+  }),
+  'boxxy.pull_request.linked': () => ({
+    attempt: buildAttemptId(),
+    repo: brandSchemas.repoName.parse('shoal/charts'),
+    number: 14,
+    url: 'https://github.com/shoal/charts/pull/14',
+    pullRequestId: '9001',
+    source: 'hook',
+  }),
+};
+
+// An unsent outbox row of the type, with every payload field the test does not give filled with a
+// valid value. The payload passes the type's schema, or the factory throws.
+export function buildMockWorkFact<Type extends MockedFactType>(
+  type: Type,
+  overrides: WorkFactOverrides<Type> = {},
+): OutboxFact {
+  const schema: z.ZodType = workFactSchemas[type];
+  const payload = schema.parse({ ...defaultPayloads[type](), ...overrides.payload });
+  const seq = overrides.seq ?? 1;
+
+  return {
+    seq,
+    factId: buildMockFactId(),
+    type,
+    entity: overrides.entity ?? `boxxy:item:${faker.string.uuid({ version: 7 })}`,
+    actor: 'boxxy:owner:local',
+    at: toInstant(overrides.at ?? 1_800_000_000_000),
+    payload: toJSONValue(payload),
+    sentAt: null,
+    parkedAt: null,
+    parkedReason: null,
+  };
+}
+
+function toInstant(at: number): Instant {
+  return brandSchemas.instant.parse(at);
+}
+
+function buildAttemptId() {
+  return brandSchemas.attemptId.parse(faker.string.uuid({ version: 7 }));
+}
+
+function buildAtcSession() {
+  return brandSchemas.atcSessionId.parse(`s-${faker.string.alphanumeric(8)}`);
+}