@boxxy/pepys 0.0.1 → 0.1.4

package/src/queries/constants.ts

@@ -0,0 +1,10 @@
+// An attempt that the worker refused for capacity ran no session: it is no attempt of work, and
+// neither query counts it.
+export const noCapacityFailure = 'no-capacity';
+
+// Outcome names of boxxy's phase kinds. A phase kind that renames one must change this list.
+export const outcomeNames = {
+  built: 'built',
+  passed: 'passed',
+  changesRequested: 'changes-requested',
+} as const;

package/src/queries/find-item-entity-id.ts

@@ -0,0 +1,16 @@
+import { buildEntityID, parseEntityID } from '@pepys/kit';
+import type { EntityID } from '@pepys/kit';
+
+// The item of a query's input as an entity ID. undefined: the text names no boxxy item, so the
+// query answers as for an item with no row.
+export function findItemEntityID(text: string): EntityID | undefined {
+  const parsed = parseEntityID(text);
+
+  if (!parsed.ok || parsed.value.source !== 'boxxy' || parsed.value.kind !== 'item') {
+    return undefined;
+  }
+
+  const built = buildEntityID(parsed.value);
+
+  return built.ok ? built.value : undefined;
+}

package/src/queries/types.ts

@@ -0,0 +1,168 @@
+import type {
+  ColumnKind,
+  ConsumerDeclaration,
+  EntityID,
+  QueryCall,
+  TableDeclaration,
+} from '@pepys/kit';
+import type { boxxyWorkConsumer } from '../work/boxxy-work-consumer.ts';
+
+// The rows the statements of the two queries read. Each holds the columns of its table that the
+// builders need, under the column names.
+
+export interface AttemptReadRow {
+  id: string;
+  phase: string;
+  number: number;
+  round: number;
+  state: string;
+  outcome: string | null;
+  failure: string | null;
+  claimed_at: string;
+  ended_at: string | null;
+
+  // a JSON column: the list of sleep stretches, as text or as the parsed list
+  sleeps: unknown;
+}
+
+// A row of `boxxy_attempt_session` for every session that an attempt of the item used, with the
+// rows of the other attempts, of any item, that used the same session.
+export interface BindingReadRow {
+  attempt_id: string;
+  session_id: string;
+  bound_at: string;
+  caller_issuer: string | null;
+  caller_subject: string | null;
+}
+
+// the proven sender of a telemetry row, and its session and time
+interface TelemetryReadRow {
+  session_id: string;
+  origin_issuer: string | null;
+  origin_subject: string | null;
+  product: string;
+  at: string;
+}
+
+export interface RequestReadRow extends TelemetryReadRow {
+  model: string;
+  cost_basis: string;
+  cost_usd: number | null;
+  input_tokens: number;
+  cache_read_tokens: number;
+  cache_creation_tokens: number;
+  output_tokens: number;
+}
+
+export interface TurnReadRow extends TelemetryReadRow {
+  model: string | null;
+  cost_usd: number;
+}
+
+// one pull request that an attempt of the item produced
+export interface PullRequestReadRow {
+  id: string;
+  merged_at: string | null;
+}
+
+// One pull request of the item with its delivery times, as the GitHub plug-in's delivery module
+// gives them. Two attempts that produced one pull request give two equal rows.
+export interface DeliveryReadRow {
+  pullRequest: string;
+  mergedAt: string | null;
+  release: { at: string } | null;
+  deploy: { at: string } | null;
+}
+
+interface Column<Kind extends ColumnKind> {
+  readonly kind: Kind;
+}
+
+interface NullableColumn<Kind extends ColumnKind> {
+  readonly kind: Kind;
+  readonly nullable: true;
+}
+
+// The columns that the queries read of each consumer of another plug-in. A consumer with more
+// 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: Column<'text'>;
+  origin_subject: Column<'text'>;
+  product: Column<'text'>;
+  at: Column<'timestamp'>;
+}>;
+
+export type TelemetryModelRequestConsumer = ConsumerDeclaration<
+  'telemetry_model_request',
+  {
+    readonly telemetry_model_request: TableDeclaration<
+      TelemetryColumns & {
+        readonly model: Column<'text'>;
+        readonly cost_basis: Column<'text'>;
+        readonly cost_usd: NullableColumn<'real'>;
+        readonly input_tokens: Column<'integer'>;
+        readonly cache_read_tokens: Column<'integer'>;
+        readonly cache_creation_tokens: Column<'integer'>;
+        readonly output_tokens: Column<'integer'>;
+      }
+    >;
+  }
+>;
+
+export type TelemetryTurnCostConsumer = ConsumerDeclaration<
+  'telemetry_turn_cost',
+  {
+    readonly telemetry_turn_cost: TableDeclaration<
+      TelemetryColumns & {
+        readonly model: NullableColumn<'text'>;
+        readonly cost_usd: Column<'real'>;
+      }
+    >;
+  }
+>;
+
+export type GithubPullRequestConsumer = ConsumerDeclaration<
+  'github_pull_request',
+  {
+    readonly github_pull_request: TableDeclaration<{
+      readonly id: Column<'entityID'>;
+      readonly merged_at: NullableColumn<'timestamp'>;
+    }>;
+  }
+>;
+
+// A consumer whose tables the stage-time query does not type: the delivery read types its own,
+// so the query's statement on the boxxy tables keeps one table type. No table name holds a colon,
+// so the key pattern matches no real table and any consumer fits.
+export type OpaqueConsumer = ConsumerDeclaration<
+  string,
+  Readonly<Record<`opaque:${string}`, TableDeclaration>>
+>;
+
+export type StageTimeReads = readonly [typeof boxxyWorkConsumer, ...OpaqueConsumer[]];
+
+export interface DeliveryInput {
+  readonly item: EntityID;
+
+  // the environment whose deploy counts
+  readonly environment: string;
+}
+
+// The GitHub plug-in's delivery times of each pull request that an attempt of the item produced,
+// with the consumers that hold them.
+export interface DeliveryReads {
+  readonly consumers: readonly OpaqueConsumer[];
+  readonly readDeliveries: (
+    db: QueryCall<unknown, StageTimeReads>['db'],
+    input: DeliveryInput,
+  ) => Promise<readonly DeliveryReadRow[]>;
+}
+
+// The consumers of the GitHub and telemetry plug-ins that the two queries read.
+export interface ForeignReads {
+  readonly telemetryModelRequest: TelemetryModelRequestConsumer;
+  readonly telemetryTurnCost: TelemetryTurnCostConsumer;
+  readonly githubPullRequest: GithubPullRequestConsumer;
+  readonly delivery: DeliveryReads;
+}

package/src/sink/is-outgoing-fact.ts

@@ -0,0 +1,19 @@
+import type { FactBatchBody, OutgoingFact } from '@pepys/kit';
+import type { boxxySource } from '../boxxy-source.ts';
+import { workFamily } from '../boxxy-source.ts';
+
+// The check that ingest makes of each fact of a batch: a type of the family, an entity of the
+// family's kind, and a payload that the type's schema accepts.
+export function isOutgoingFact(
+  fact: FactBatchBody['facts'][number],
+): fact is OutgoingFact<typeof boxxySource> {
+  return (
+    isFamilyType(fact.type) &&
+    fact.entity.startsWith(`${workFamily.entityKind}:`) &&
+    workFamily.types[fact.type].safeParse(fact.payload).success
+  );
+}
+
+function isFamilyType(type: string): type is keyof typeof workFamily.types {
+  return Object.hasOwn(workFamily.types, type);
+}

package/src/sink/pick-sink-answer.ts

@@ -0,0 +1,29 @@
+import type { SinkAnswer } from '@boxxy/model';
+import type { Result, SendFailure } from '@pepys/kit';
+
+type SendResult = Result<{ stored: number }, SendFailure>;
+
+// A refusal with 400, 413 or 422 is the batch's content, which a split can find. Ingest answers
+// 500 when a source throws, it has no blob store, or its log refuses an append: no split fixes
+// those, so a 500 blocks the outbox like any other refusal of the sink.
+export function pickSinkAnswer(sent: SendResult | 'timeout', timeoutMs: number): SinkAnswer {
+  if (sent === 'timeout') {
+    return { kind: 'retry', reason: `no answer in ${timeoutMs} ms` };
+  }
+
+  if (sent.ok) {
+    return { kind: 'stored' };
+  }
+
+  const failure = sent.failure;
+
+  if (failure.kind === 'retry') {
+    return { kind: 'retry', reason: failure.reason };
+  }
+
+  const status = failure.status;
+
+  return status === 400 || status === 413 || status === 422
+    ? { kind: 'refused-batch', status, reason: failure.reason }
+    : { kind: 'refused-sink', status, reason: failure.reason };
+}

package/src/sink/to-wire-fact.ts

@@ -0,0 +1,31 @@
+import type { OutboxFact } from '@boxxy/model';
+import type { FactBatchBody } from '@pepys/kit';
+
+type WireFact = FactBatchBody['facts'][number];
+
+// One outbox row as one fact of a batch. The event is the row's fact ID on every send, so a
+// resend is a copy that pepys drops; ingest makes the fact ID `event:boxxy:<event>`. The store
+// version goes into the payload here and nowhere else.
+export function toWireFact(fact: OutboxFact): WireFact {
+  return {
+    type: fact.type,
+    event: fact.factId,
+    entity: fact.entity,
+    actor: fact.actor,
+    at: new Date(fact.at).toISOString(),
+    payload: { ...toPayloadFields(fact.payload), storeVersion: fact.seq },
+  };
+}
+
+type Payload = OutboxFact['payload'];
+
+// Every catalog payload is an object; `Array.isArray` does not narrow a readonly list.
+function toPayloadFields(payload: Payload): Readonly<Record<string, unknown>> {
+  return isPayloadObject(payload) ? payload : {};
+}
+
+function isPayloadObject(
+  payload: Payload,
+): payload is Extract<Payload, Readonly<Record<string, unknown>>> {
+  return typeof payload === 'object' && payload !== null && !Array.isArray(payload);
+}

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