@boxxy/model 0.1.0 → 0.1.2

package/src/live-levers.ts

@@ -0,0 +1,22 @@
+import type { Instant, LeverKind, LeverRow } from './types/core.ts';
+
+export function liveLevers(levers: readonly LeverRow[], now: Instant): LeverRow[] {
+  return levers.filter((lever) => !isExpired(lever, now) && !isUndone(lever, levers));
+}
+
+function isExpired(lever: LeverRow, now: Instant): boolean {
+  return lever.expiresAt !== null && lever.expiresAt <= now;
+}
+
+const undoKinds: ReadonlyMap<LeverKind, LeverKind> = new Map([
+  ['plan.defer', 'plan.undefer'],
+  ['plan.expedite', 'plan.unexpedite'],
+]);
+
+function isUndone(lever: LeverRow, levers: readonly LeverRow[]): boolean {
+  const undoKind = undoKinds.get(lever.kind);
+
+  return levers.some(
+    (later) => later.item === lever.item && later.kind === undoKind && later.seq > lever.seq,
+  );
+}

package/src/outbox-fact-schema.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import { actorRefSchema } from './actor-ref-schema.ts';
+import { brandSchemas } from './brand-schemas.ts';
+import type { OutboxFact } from './types/facts.ts';
+
+const idSchema = z.string();
+
+const entityRefSchema = z.union([
+  z.templateLiteral(['boxxy:item:', idSchema]),
+  z.templateLiteral(['boxxy:link:', idSchema, ':', idSchema, ':', idSchema]),
+  z.templateLiteral(['boxxy:attempt:', idSchema]),
+  z.templateLiteral(['boxxy:decision:', idSchema]),
+  z.templateLiteral(['boxxy:runner:', idSchema]),
+]);
+
+export const outboxFactSchema: z.ZodType<OutboxFact> = z.object({
+  seq: z.number().int().positive(),
+  factId: brandSchemas.factId,
+  type: z.string().min(1),
+  entity: entityRefSchema,
+  actor: actorRefSchema,
+  at: brandSchemas.instant,
+  payload: z.json(),
+  sentAt: brandSchemas.instant.nullable(),
+});

package/src/row-schemas.ts

@@ -0,0 +1,89 @@
+import { contentHashSchema } from '@boxxy/content-hash';
+import { z } from 'zod';
+import { actorRefSchema } from './actor-ref-schema.ts';
+import { brandSchemas } from './brand-schemas.ts';
+import { buildCloseOutSchema } from './build-close-out-schema.ts';
+import { factSchemas } from './fact-schemas.ts';
+import type { TableName, Tables } from './types/ports.ts';
+
+const countSchema = z.number().int().nonnegative();
+
+export const rowSchemas: { readonly [T in TableName]: z.ZodType<Tables[T]> } = {
+  items: factSchemas['boxxy.item.filed'],
+  links: z.object({
+    source: brandSchemas.itemId,
+    target: brandSchemas.itemId,
+    type: brandSchemas.linkTypeName,
+    addedBy: actorRefSchema,
+    addedAt: brandSchemas.instant,
+    removedAt: brandSchemas.instant.nullable(),
+  }),
+  levers: factSchemas['boxxy.lever.recorded'],
+  attempts: z.object({
+    id: brandSchemas.attemptId,
+    item: brandSchemas.itemId,
+    phase: brandSchemas.phaseName,
+    number: z.number().int().positive(),
+    runner: brandSchemas.runnerId,
+    recipeHash: brandSchemas.recipeHash,
+    rulesVersion: brandSchemas.rulesVersion,
+    pool: brandSchemas.poolName,
+    slot: countSchema,
+    slotGen: countSchema,
+    leaseGen: countSchema,
+    spawnRequest: z.json(),
+    spawnRequestHash: contentHashSchema,
+    state: z.enum(['starting', 'running', 'reconciling', 'succeeded', 'failed']),
+    failure: z.string().nullable(),
+    atcSession: brandSchemas.atcSessionId.nullable(),
+    closeOut: buildCloseOutSchema.nullable(),
+    claimedAt: brandSchemas.instant,
+    startedAt: brandSchemas.instant.nullable(),
+    endedAt: brandSchemas.instant.nullable(),
+  }),
+  attempt_sessions: z.object({
+    attempt: brandSchemas.attemptId,
+    agentSession: brandSchemas.agentSessionId,
+    atcSession: brandSchemas.atcSessionId,
+    seenAt: brandSchemas.instant,
+  }),
+  leases: z.object({
+    item: brandSchemas.itemId,
+    phase: brandSchemas.phaseName,
+    attempt: brandSchemas.attemptId,
+    gen: countSchema,
+    takenAt: brandSchemas.instant,
+    releasedAt: brandSchemas.instant.nullable(),
+  }),
+  pool_slots: z.object({
+    pool: brandSchemas.poolName,
+    slot: countSchema,
+    holder: brandSchemas.attemptId.nullable(),
+    gen: countSchema,
+    retired: z.boolean(),
+  }),
+  decisions: factSchemas['boxxy.decision.recorded'],
+  evidence: z.object({
+    factId: brandSchemas.factId,
+    attempt: brandSchemas.attemptId,
+    kind: z.enum(['pr', 'commit', 'test', 'ci-run', 'live-check']),
+    ref: z.string().min(1),
+    observed: z.string().nullable(),
+    source: z.enum(['hook', 'trailer', 'agent', 'watch']),
+    at: brandSchemas.instant,
+  }),
+  pull_requests: z.object({
+    repo: brandSchemas.repoName,
+    number: z.number().int().positive(),
+    attempt: brandSchemas.attemptId,
+    state: z.enum(['open', 'closed', 'merged']),
+    mergedAt: brandSchemas.instant.nullable(),
+    mergeCommit: brandSchemas.commitSha.nullable(),
+    checkedAt: brandSchemas.instant,
+  }),
+  runners: z.object({
+    id: brandSchemas.runnerId,
+    heartbeatAt: brandSchemas.instant,
+    paused: z.boolean(),
+  }),
+};

package/src/signal-key.ts

@@ -0,0 +1,7 @@
+import type { JsonValue } from '@boxxy/content-hash';
+import { contentHash } from '@boxxy/content-hash';
+import type { SignalKey, SignalName } from './types/planning.ts';
+
+export function signalKey(name: SignalName, params: JsonValue): SignalKey {
+  return `${name}#${contentHash(params)}`;
+}

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

@@ -0,0 +1,37 @@
+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';
+
+const hashOptions = { length: 64, casing: 'lower', prefix: '' } as const;
+
+export function buildMockAttemptRow(overrides: Partial<AttemptRow> = {}): AttemptRow {
+  const spawnRequest =
+    overrides.spawnRequest === undefined
+      ? { prompt: faker.lorem.sentence() }
+      : overrides.spawnRequest;
+
+  return {
+    id: brandSchemas.attemptId.parse(faker.string.uuid({ version: 7 })),
+    item: brandSchemas.itemId.parse(faker.string.uuid({ version: 7 })),
+    phase: brandSchemas.phaseName.parse('build'),
+    number: 1,
+    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,
+    leaseGen: 1,
+    spawnRequest,
+    spawnRequestHash: contentHash(spawnRequest),
+    state: 'succeeded',
+    failure: null,
+    atcSession: brandSchemas.atcSessionId.parse(faker.string.uuid()),
+    closeOut: 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 })),
+    ...overrides,
+  };
+}

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

@@ -0,0 +1,17 @@
+import { faker } from '@faker-js/faker';
+import { brandSchemas } from '../brand-schemas.ts';
+import type { EvidenceRow } from '../types/core.ts';
+import { buildMockFactId } from './build-mock-fact-id.ts';
+
+export function buildMockEvidenceRow(overrides: Partial<EvidenceRow> = {}): EvidenceRow {
+  return {
+    factId: buildMockFactId(),
+    attempt: brandSchemas.attemptId.parse(faker.string.uuid({ version: 7 })),
+    kind: 'test',
+    ref: faker.system.filePath(),
+    observed: null,
+    source: 'agent',
+    at: brandSchemas.instant.parse(faker.number.int({ max: 1_800_000_000_000 })),
+    ...overrides,
+  };
+}

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

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

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

@@ -0,0 +1,9 @@
+import { brandSchemas } from '../brand-schemas.ts';
+import type { FrameItem } from '../types/planning.ts';
+import { buildMockItemView } from './build-mock-item-view.ts';
+
+export function buildMockFrameItem(overrides: Partial<FrameItem> = {}): FrameItem {
+  const { phase, ...view } = overrides;
+
+  return { ...buildMockItemView(view), phase: phase ?? brandSchemas.phaseName.parse('build') };
+}

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

@@ -0,0 +1,22 @@
+import { faker } from '@faker-js/faker';
+import { brandSchemas } from '../brand-schemas.ts';
+import type { ItemRow } from '../types/core.ts';
+
+export function buildMockItemRow(overrides: Partial<ItemRow> = {}): ItemRow {
+  return {
+    id: brandSchemas.itemId.parse(faker.string.uuid({ version: 7 })),
+    kind: brandSchemas.itemKindName.parse('core.issue'),
+    repo: brandSchemas.repoName.parse(`${faker.string.alpha(8)}/${faker.string.alpha(8)}`),
+    title: faker.lorem.sentence(),
+    outcome: faker.lorem.sentence(),
+    acceptance: [
+      { id: brandSchemas.criterionId.parse('a1'), text: faker.lorem.sentence(), evidence: [] },
+    ],
+    foundInAttempt: null,
+    filedBy: 'boxxy:owner:local',
+    filedAt: brandSchemas.instant.parse(faker.number.int({ max: 1_800_000_000_000 })),
+    closedAt: null,
+    closeReason: null,
+    ...overrides,
+  };
+}

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

@@ -0,0 +1,14 @@
+import type { ItemRows } from '../types/core.ts';
+
+export function buildMockItemRows(overrides: Partial<ItemRows> = {}): ItemRows {
+  return {
+    links: [],
+    blockerStates: new Map(),
+    levers: [],
+    attempts: [],
+    liveLease: null,
+    pullRequests: [],
+    maxAttempts: 2,
+    ...overrides,
+  };
+}

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

@@ -0,0 +1,8 @@
+import type { ItemView } from '../types/core.ts';
+import { buildMockItemRow } from './build-mock-item-row.ts';
+
+export function buildMockItemView(overrides: Partial<ItemView> = {}): ItemView {
+  const { derived, ...row } = overrides;
+
+  return { ...buildMockItemRow(row), derived: derived ?? { state: 'ready' } };
+}

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

@@ -0,0 +1,15 @@
+import { faker } from '@faker-js/faker';
+import { brandSchemas } from '../brand-schemas.ts';
+import type { LeaseRow } from '../types/core.ts';
+
+export function buildMockLeaseRow(overrides: Partial<LeaseRow> = {}): LeaseRow {
+  return {
+    item: brandSchemas.itemId.parse(faker.string.uuid({ version: 7 })),
+    phase: brandSchemas.phaseName.parse('build'),
+    attempt: brandSchemas.attemptId.parse(faker.string.uuid({ version: 7 })),
+    gen: 1,
+    takenAt: brandSchemas.instant.parse(faker.number.int({ max: 1_800_000_000_000 })),
+    releasedAt: null,
+    ...overrides,
+  };
+}

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

@@ -0,0 +1,17 @@
+import { faker } from '@faker-js/faker';
+import { brandSchemas } from '../brand-schemas.ts';
+import type { LeverRow } from '../types/core.ts';
+
+export function buildMockLeverRow(overrides: Partial<LeverRow> = {}): LeverRow {
+  return {
+    seq: faker.number.int({ min: 1, max: 10_000 }),
+    kind: 'plan.defer',
+    item: brandSchemas.itemId.parse(faker.string.uuid({ version: 7 })),
+    until: null,
+    expiresAt: null,
+    reason: faker.lorem.sentence(),
+    actor: 'boxxy:owner:local',
+    at: brandSchemas.instant.parse(faker.number.int({ max: 1_800_000_000_000 })),
+    ...overrides,
+  };
+}

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

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

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

@@ -0,0 +1,16 @@
+import { faker } from '@faker-js/faker';
+import { brandSchemas } from '../brand-schemas.ts';
+import type { PullRequestRow } from '../types/core.ts';
+
+export function buildMockPullRequestRow(overrides: Partial<PullRequestRow> = {}): PullRequestRow {
+  return {
+    repo: brandSchemas.repoName.parse(`${faker.string.alpha(8)}/${faker.string.alpha(8)}`),
+    number: faker.number.int({ min: 1, max: 10_000 }),
+    attempt: brandSchemas.attemptId.parse(faker.string.uuid({ version: 7 })),
+    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-snapshot.ts

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

package/src/test-utils/seed-faker.ts

@@ -0,0 +1,3 @@
+import { faker } from '@faker-js/faker';
+
+faker.seed(1);

package/src/to-json-value.ts

@@ -0,0 +1,25 @@
+import type { JsonValue } from '@boxxy/content-hash';
+import invariant from 'tiny-invariant';
+
+export function toJSONValue(value: unknown): JsonValue {
+  if (
+    value === null ||
+    typeof value === 'boolean' ||
+    typeof value === 'number' ||
+    typeof value === 'string'
+  ) {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((entry: unknown) => toJSONValue(entry));
+  }
+
+  invariant(typeof value === 'object', `a ${typeof value} has no JSON form`);
+
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([, entry]: [string, unknown]) => entry !== undefined)
+      .map(([key, entry]: [string, unknown]) => [key, toJSONValue(entry)]),
+  );
+}

package/src/types/core.ts

@@ -0,0 +1,299 @@
+import type { ContentHash, JsonValue } from '@boxxy/content-hash';
+import type { z } from 'zod';
+import type { brandSchemas } from '../brand-schemas.ts';
+import type { BuildCloseOut } from './facts.ts';
+
+type BrandOf<K extends keyof typeof brandSchemas> = z.output<(typeof brandSchemas)[K]>;
+
+export type Instant = BrandOf<'instant'>;
+
+export type Minutes = number;
+
+export type ItemId = BrandOf<'itemId'>;
+
+export type AttemptId = BrandOf<'attemptId'>;
+
+export type DecisionId = BrandOf<'decisionId'>;
+
+export type FactId = BrandOf<'factId'>;
+
+export type RunnerId = BrandOf<'runnerId'>;
+
+export type AtcSessionId = BrandOf<'atcSessionId'>;
+
+export type AgentSessionId = BrandOf<'agentSessionId'>;
+
+export type CommitSha = BrandOf<'commitSha'>;
+
+export type RepoName = BrandOf<'repoName'>;
+
+export type CriterionId = BrandOf<'criterionId'>;
+
+export interface PullRequestRef {
+  readonly repo: RepoName;
+  readonly number: number;
+}
+
+export type ItemKindName = BrandOf<'itemKindName'>;
+
+export type LinkTypeName = BrandOf<'linkTypeName'>;
+
+export type PhaseName = BrandOf<'phaseName'>;
+
+export type PipelineName = BrandOf<'pipelineName'>;
+
+export type PoolName = BrandOf<'poolName'>;
+
+export type RecipeName = BrandOf<'recipeName'>;
+
+export type WorkerKindName = BrandOf<'workerKindName'>;
+
+export type SourceName = BrandOf<'sourceName'>;
+
+export type StreamName = BrandOf<'streamName'>;
+
+export type LeverKind = `${string}.${string}`;
+
+export type RecipeHash = BrandOf<'recipeHash'>;
+
+export type SnapshotHash = BrandOf<'snapshotHash'>;
+
+export type RulesVersion = BrandOf<'rulesVersion'>;
+
+export interface ConceptPin {
+  readonly ref: `${string}@${number}`;
+  readonly sourceHash: ContentHash;
+}
+
+export type Actor =
+  | { readonly kind: 'owner' }
+  | { readonly kind: 'attempt'; readonly attempt: AttemptId }
+  | { readonly kind: 'runner'; readonly runner: RunnerId }
+  | { readonly kind: 'hook'; readonly attempt: AttemptId };
+
+export type ActorRef =
+  | 'boxxy:owner:local'
+  | `boxxy:runner:${string}`
+  | `boxxy:attempt:${string}`
+  | `boxxy:hook:${string}`;
+
+export type EvidenceKind = 'pr' | 'commit' | 'test' | 'ci-run' | 'live-check';
+
+export interface Criterion {
+  readonly id: CriterionId;
+  readonly text: string;
+  readonly evidence: readonly FactId[];
+}
+
+export interface ItemRow {
+  readonly id: ItemId;
+  readonly kind: ItemKindName;
+  readonly repo: RepoName;
+  readonly title: string;
+  readonly outcome: string;
+  readonly acceptance: readonly Criterion[];
+  readonly foundInAttempt: AttemptId | null;
+  readonly filedBy: ActorRef;
+  readonly filedAt: Instant;
+  readonly closedAt: Instant | null;
+  readonly closeReason: string | null;
+}
+
+export type ItemState = 'idea' | 'ready' | 'running' | 'blocked' | 'waiting' | 'done' | 'archived';
+
+export type WaitingReason = 'PR open' | 'no PR linked' | 'attempts used up';
+
+export type DerivedState =
+  | { readonly state: Exclude<ItemState, 'waiting'> }
+  | { readonly state: 'waiting'; readonly reason: WaitingReason };
+
+export interface ItemView extends ItemRow {
+  readonly derived: DerivedState;
+}
+
+export interface ItemRows {
+  // live links whose target is the item
+  readonly links: readonly LinkRow[];
+  readonly blockerStates: ReadonlyMap<ItemId, ItemState>;
+  readonly levers: readonly LeverRow[];
+  readonly attempts: readonly AttemptRow[];
+  readonly liveLease: LeaseRow | null;
+  readonly pullRequests: readonly PullRequestRow[];
+
+  // the kind's `maxAttempts` for the item's current phase
+  readonly maxAttempts: number;
+}
+
+// the rows a store reads to derive the state of a set of items, with each blocking source item
+export interface ItemSetRows {
+  readonly items: readonly ItemRow[];
+
+  // live links only
+  readonly links: readonly LinkRow[];
+  readonly levers: readonly LeverRow[];
+  readonly attempts: readonly AttemptRow[];
+  readonly liveLeases: readonly LeaseRow[];
+  readonly pullRequests: readonly PullRequestRow[];
+}
+
+export type MaxAttemptsByKind = ReadonlyMap<ItemKindName, ReadonlyMap<PhaseName, number>>;
+
+export interface ItemWithLevers extends ItemView {
+  readonly levers: readonly LeverRow[];
+}
+
+export interface LinkRow {
+  readonly source: ItemId;
+  readonly target: ItemId;
+  readonly type: LinkTypeName;
+  readonly addedBy: ActorRef;
+  readonly addedAt: Instant;
+  readonly removedAt: Instant | null;
+}
+
+export interface LeverRow {
+  readonly seq: number;
+  readonly kind: LeverKind;
+  readonly item: ItemId;
+  readonly until: Instant | null;
+  readonly expiresAt: Instant | null;
+  readonly reason: string | null;
+  readonly actor: ActorRef;
+  readonly at: Instant;
+}
+
+export type AttemptState = 'starting' | 'running' | 'reconciling' | 'succeeded' | 'failed';
+
+export type LiveAttemptState = Extract<AttemptState, 'starting' | 'running' | 'reconciling'>;
+
+export type KnownFailure = 'spawn-refused' | 'session-lost' | 'spawn-lost' | 'closeout-missing';
+
+export type ForcedFailure = Extract<KnownFailure, 'spawn-refused' | 'session-lost' | 'spawn-lost'>;
+
+export interface AttemptRow {
+  readonly id: AttemptId;
+  readonly item: ItemId;
+  readonly phase: PhaseName;
+  readonly number: number;
+  readonly runner: RunnerId;
+  readonly recipeHash: RecipeHash;
+  readonly rulesVersion: RulesVersion;
+  readonly pool: PoolName;
+  readonly slot: number;
+  readonly slotGen: number;
+  readonly leaseGen: number;
+  readonly spawnRequest: JsonValue;
+  readonly spawnRequestHash: ContentHash;
+  readonly state: AttemptState;
+  readonly failure: string | null;
+  readonly atcSession: AtcSessionId | null;
+  readonly closeOut: BuildCloseOut | null;
+  readonly claimedAt: Instant;
+  readonly startedAt: Instant | null;
+  readonly endedAt: Instant | null;
+}
+
+export interface AttemptSessionRow {
+  readonly attempt: AttemptId;
+  readonly agentSession: AgentSessionId;
+  readonly atcSession: AtcSessionId;
+  readonly seenAt: Instant;
+}
+
+export interface LeaseRow {
+  readonly item: ItemId;
+  readonly phase: PhaseName;
+  readonly attempt: AttemptId;
+  readonly gen: number;
+  readonly takenAt: Instant;
+  readonly releasedAt: Instant | null;
+}
+
+export interface PoolSlotRow {
+  readonly pool: PoolName;
+  readonly slot: number;
+  readonly holder: AttemptId | null;
+  readonly gen: number;
+  readonly retired: boolean;
+}
+
+export interface ObservationBoundary {
+  readonly storeVersion: number;
+  readonly pepysOffsets: Readonly<Record<StreamName, number>>;
+}
+
+export interface DecisionRow {
+  readonly id: DecisionId;
+  readonly attempt: AttemptId;
+  readonly item: ItemId;
+  readonly pool: PoolName;
+  readonly rulesVersion: RulesVersion;
+  readonly snapshotHash: SnapshotHash;
+  readonly storeVersion: number;
+  readonly pepysOffsets: ObservationBoundary['pepysOffsets'];
+  readonly faults: readonly FaultRecord[];
+  readonly at: Instant;
+}
+
+export interface FaultRecord {
+  // the signal, gate, waiver or filter field name, or `propagation:<signal>:<link>`
+  readonly plugin: string;
+  readonly kind: 'signal' | 'gate' | 'waiver' | 'admission' | 'propagation' | 'filter-field';
+  readonly item: ItemId | null;
+  readonly error: string;
+}
+
+export type EvidenceSource = 'hook' | 'trailer' | 'agent' | 'watch';
+
+export interface EvidenceRow {
+  readonly factId: FactId;
+  readonly attempt: AttemptId;
+  readonly kind: EvidenceKind;
+  readonly ref: string;
+  readonly observed: string | null;
+  readonly source: EvidenceSource;
+  readonly at: Instant;
+}
+
+export interface PullRequestRow {
+  readonly repo: RepoName;
+  readonly number: number;
+  readonly attempt: AttemptId;
+  readonly state: 'open' | 'closed' | 'merged';
+  readonly mergedAt: Instant | null;
+  readonly mergeCommit: CommitSha | null;
+  readonly checkedAt: Instant;
+}
+
+export interface RunnerRow {
+  readonly id: RunnerId;
+  readonly heartbeatAt: Instant;
+  readonly paused: boolean;
+}
+
+export type Effort = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+
+export interface Recipe {
+  readonly agent: string;
+  readonly model: string;
+  readonly effort: Effort;
+
+  // the prompt template's path in the rules checkout
+  readonly prompt: string;
+  readonly source: SourceName;
+}
+
+export interface RecipeMaterial {
+  readonly name: RecipeName;
+  readonly recipe: Recipe;
+  readonly promptHash: ContentHash;
+  readonly pluginFolderHash: ContentHash;
+  readonly rulesVersion: RulesVersion;
+}
+
+// the loader can't see the plugin folder, so claimNext adds its hash
+export type LoadedRecipe = Omit<RecipeMaterial, 'pluginFolderHash'>;
+
+export interface ResolvedRecipe extends RecipeMaterial {
+  readonly hash: RecipeHash;
+}