@boxxy/model 0.1.1 → 0.1.3

package/src/rows/decision-row-schema.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import type { DecisionRow } from '../types.ts';
+import { brandSchemas } from './brand-schemas.ts';
+
+const countSchema = z.number().int().nonnegative();
+
+const faultSchema = z.object({
+  plugin: z.string().min(1),
+  kind: z.enum(['signal', 'gate', 'waiver', 'admission', 'propagation', 'filter-field']),
+  item: brandSchemas.itemId.nullable(),
+  error: z.string(),
+});
+
+const limitCountSchema = z.object({
+  limit: brandSchemas.limitName,
+  held: countSchema,
+  max: countSchema,
+});
+
+// A plain object, so that the wire schema of `boxxy.decision.recorded` can extend it.
+export const decisionRowSchema = z.object({
+  id: brandSchemas.decisionId,
+  attempt: brandSchemas.attemptId,
+  item: brandSchemas.itemId,
+  kind: z.enum(['start', 'wake']),
+  pool: brandSchemas.poolName,
+  rulesVersion: brandSchemas.rulesVersion,
+  snapshotHash: brandSchemas.snapshotHash,
+  storeVersion: countSchema,
+  pepysOffsets: z.record(brandSchemas.streamName, countSchema),
+  faults: z.array(faultSchema),
+  limits: z.array(limitCountSchema),
+  at: brandSchemas.instant,
+}) satisfies z.ZodType<DecisionRow>;

package/src/rows/evidence-row-schema.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import type { EvidenceRow } from '../types.ts';
+import { brandSchemas } from './brand-schemas.ts';
+
+export const evidenceRowSchema: z.ZodType<EvidenceRow> = z.object({
+  factId: brandSchemas.factId,
+  attempt: brandSchemas.attemptId,
+  kind: z.enum(['pull_request', '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,
+});

package/src/rows/item-row-schema.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import type { ItemRow } from '../types.ts';
+import { actorRefSchema } from './actor-ref-schema.ts';
+import { brandSchemas } from './brand-schemas.ts';
+import { callerIdentitySchema } from './caller-identity-schema.ts';
+import { criterionSchema } from './criterion-schema.ts';
+
+// A plain object, so that the fact schema of `boxxy.item.filed` can omit `keptSession`.
+export const itemRowSchema = z.object({
+  id: brandSchemas.itemId,
+  kind: brandSchemas.itemKindName,
+  repo: brandSchemas.repoName,
+  title: z.string().min(1),
+  outcome: z.string().min(1),
+  acceptance: z.array(criterionSchema),
+  fields: z.object({ designMode: z.enum(['agent', 'attended']).exactOptional() }),
+  labels: z.array(z.string().min(1)),
+  foundInAttempt: brandSchemas.attemptId.nullable(),
+  filedBy: actorRefSchema,
+  filedAt: brandSchemas.instant,
+  closedAt: brandSchemas.instant.nullable(),
+  closeReason: z.string().nullable(),
+  keptSession: z
+    .object({
+      atcSession: brandSchemas.atcSessionId,
+      target: z.string().min(1),
+      attempt: brandSchemas.attemptId,
+      keptAt: brandSchemas.instant,
+      caller: callerIdentitySchema.nullable(),
+    })
+    .nullable(),
+}) satisfies z.ZodType<ItemRow>;

package/src/rows/item-view-schema.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { positionSchema } from '../pipeline/position-schema.ts';
+import type { ItemView } from '../types.ts';
+import { brandSchemas } from './brand-schemas.ts';
+import { itemRowSchema } from './item-row-schema.ts';
+
+const holdReasonOrWaitingSchema = z.union([
+  z.literal('pull request open'),
+  z.literal('no pull request linked'),
+  z.literal('pull request closed unmerged'),
+  z.literal('attempts used up'),
+  z.literal('rounds used up'),
+  z.literal('outcome not in rules'),
+  brandSchemas.rulesHoldReason,
+]);
+
+const derivedSchema = z.discriminatedUnion('state', [
+  z.object({ state: z.literal('idea') }),
+  z.object({ state: z.literal('ready') }),
+  z.object({ state: z.literal('running') }),
+  z.object({ state: z.literal('blocked') }),
+  z.object({ state: z.literal('done') }),
+  z.object({ state: z.literal('archived') }),
+  z.object({ state: z.literal('waiting'), reason: holdReasonOrWaitingSchema }),
+]);
+
+// typed as the core type, so a handler returns the stored view with its read-only lists
+export const itemViewSchema: z.ZodType<ItemView> = itemRowSchema.extend({
+  derived: derivedSchema,
+  position: positionSchema,
+});

package/src/rows/lease-row-schema.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import type { LeaseRow } from '../types.ts';
+import { brandSchemas } from './brand-schemas.ts';
+
+export const leaseRowSchema: z.ZodType<LeaseRow> = z.object({
+  item: brandSchemas.itemId,
+  phase: brandSchemas.phaseName,
+  attempt: brandSchemas.attemptId,
+  gen: z.number().int().nonnegative(),
+  takenAt: brandSchemas.instant,
+  releasedAt: brandSchemas.instant.nullable(),
+});

package/src/rows/lever-row-schema.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import type { LeverRow } from '../types.ts';
+import { actorRefSchema } from './actor-ref-schema.ts';
+import { brandSchemas } from './brand-schemas.ts';
+
+// A plain object, so that the wire schema of `boxxy.lever.recorded` can extend it.
+export const leverRowSchema = z.object({
+  seq: z.number().int().nonnegative(),
+  kind: z.templateLiteral([z.string().min(1), '.', z.string().min(1)]),
+  item: brandSchemas.itemId,
+  until: brandSchemas.instant.nullable(),
+  expiresAt: brandSchemas.instant.nullable(),
+  reason: z.string().nullable(),
+  phase: brandSchemas.phaseName.nullable(),
+  actor: actorRefSchema,
+  at: brandSchemas.instant,
+}) satisfies z.ZodType<LeverRow>;

package/src/rows/limit-schema.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import type { Limit } from '../planning/types.ts';
+import { brandSchemas } from './brand-schemas.ts';
+
+const filterSchema = z.record(z.string(), z.array(z.string()));
+
+// A limit as the store keeps it from the last sync of the loaded limits.
+export const limitSchema: z.ZodType<Limit> = z.object({
+  name: brandSchemas.limitName,
+  max: z.number().int().nonnegative(),
+  counts: filterSchema,
+});

package/src/rows/limit-seat-row-schema.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import type { LimitSeatRow } from '../types.ts';
+import { brandSchemas } from './brand-schemas.ts';
+
+export const limitSeatRowSchema: z.ZodType<LimitSeatRow> = z.object({
+  limit: brandSchemas.limitName,
+  attempt: brandSchemas.attemptId,
+  holdGen: z.number().int().positive(),
+  overCap: z.boolean(),
+  takenAt: brandSchemas.instant,
+  releasedAt: brandSchemas.instant.nullable(),
+});

package/src/rows/note-row-schema.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import type { NoteRow } from '../types.ts';
+import { actorRefSchema } from './actor-ref-schema.ts';
+import { brandSchemas } from './brand-schemas.ts';
+
+export const noteRowSchema: z.ZodType<NoteRow> = z.object({
+  item: brandSchemas.itemId,
+  seq: z.number().int().positive(),
+  text: z.string().min(1),
+  by: actorRefSchema,
+  at: brandSchemas.instant,
+});

package/src/rows/notice-row-schema.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import type { NoticeRow } from '../types.ts';
+import { brandSchemas } from './brand-schemas.ts';
+
+const countSchema = z.number().int().nonnegative();
+
+export const noticeRowSchema: z.ZodType<NoticeRow> = z.object({
+  id: z.number().int().positive(),
+  item: brandSchemas.itemId,
+  reason: z.union([
+    z.enum(['attempts used up', 'rounds used up', 'outcome not in rules']),
+    brandSchemas.rulesHoldReason,
+  ]),
+  at: brandSchemas.instant,
+  tries: countSchema,
+  sentAt: brandSchemas.instant.nullable(),
+});

package/src/rows/pull-request-row-schema.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import type { PullRequestRow } from '../types.ts';
+import { brandSchemas } from './brand-schemas.ts';
+
+export const pullRequestRowSchema: z.ZodType<PullRequestRow> = z.object({
+  repo: brandSchemas.repoName,
+  number: z.number().int().positive(),
+  attempt: brandSchemas.attemptId,
+  githubId: z.number().int().positive(),
+  url: z.url(),
+  state: z.enum(['open', 'closed', 'merged']),
+  mergedAt: brandSchemas.instant.nullable(),
+  mergeCommit: brandSchemas.commitSha.nullable(),
+  checkedAt: brandSchemas.instant,
+});

package/src/rows/relation-row-schema.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import type { RelationRow } from '../types.ts';
+import { actorRefSchema } from './actor-ref-schema.ts';
+import { brandSchemas } from './brand-schemas.ts';
+
+export const relationRowSchema: z.ZodType<RelationRow> = z.object({
+  source: brandSchemas.itemId,
+  target: brandSchemas.itemId,
+  type: brandSchemas.relationTypeName,
+  addedBy: actorRefSchema,
+  addedAt: brandSchemas.instant,
+  removedAt: brandSchemas.instant.nullable(),
+});

package/src/rows/row-schemas.ts

@@ -0,0 +1,30 @@
+import type { z } from 'zod';
+import type { TableName, Tables } from '../ports/types.ts';
+import { attemptRowSchema } from './attempt-row-schema.ts';
+import { attemptSessionRowSchema } from './attempt-session-row-schema.ts';
+import { decisionRowSchema } from './decision-row-schema.ts';
+import { evidenceRowSchema } from './evidence-row-schema.ts';
+import { itemRowSchema } from './item-row-schema.ts';
+import { leaseRowSchema } from './lease-row-schema.ts';
+import { leverRowSchema } from './lever-row-schema.ts';
+import { noteRowSchema } from './note-row-schema.ts';
+import { noticeRowSchema } from './notice-row-schema.ts';
+import { pullRequestRowSchema } from './pull-request-row-schema.ts';
+import { relationRowSchema } from './relation-row-schema.ts';
+import { runnerRowSchema } from './runner-row-schema.ts';
+
+// The schema of each table that a row write may name, for a store that reads rows back.
+export const rowSchemas: { readonly [T in TableName]: z.ZodType<Tables[T]> } = {
+  items: itemRowSchema,
+  relations: relationRowSchema,
+  levers: leverRowSchema,
+  attempts: attemptRowSchema,
+  attempt_sessions: attemptSessionRowSchema,
+  leases: leaseRowSchema,
+  decisions: decisionRowSchema,
+  evidence: evidenceRowSchema,
+  pull_requests: pullRequestRowSchema,
+  runners: runnerRowSchema,
+  notes: noteRowSchema,
+  notices: noticeRowSchema,
+};

package/src/rows/runner-row-schema.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+import type { RunnerRow } from '../types.ts';
+import { brandSchemas } from './brand-schemas.ts';
+
+export const runnerRowSchema: z.ZodType<RunnerRow> = z.object({
+  id: brandSchemas.runnerId,
+  heartbeatAt: brandSchemas.instant,
+  paused: z.boolean(),
+});

package/src/rows/spawn-request-schema.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import type { SpawnRequest } from '../ports/types.ts';
+import { brandSchemas } from './brand-schemas.ts';
+
+// The spawn request as the attempt row stores it, read back for a respawn.
+export const spawnRequestSchema: z.ZodType<SpawnRequest> = z.object({
+  target: z.string().min(1),
+  cwd: z.string().min(1),
+  prompt: z.string(),
+  agent: z.string().min(1),
+  model: z.string().min(1),
+  effort: z.enum(['low', 'medium', 'high', 'xhigh', 'max']),
+  name: z.templateLiteral(['boxxy/', z.string()]),
+  idempotencyKey: brandSchemas.attemptId,
+});

package/src/rules/define-phase.ts

@@ -0,0 +1,12 @@
+import type { JsonValue } from '@boxxy/content-hash';
+import type { PhaseKind } from './types.ts';
+
+// Checks a phase kind against its own body, input and outcome list, then gives it the erased
+// type that the registry holds.
+export function definePhase<
+  Body,
+  Input extends JsonValue,
+  const Outcomes extends readonly string[],
+>(phase: PhaseKind<Body, Input, Outcomes>): PhaseKind {
+  return phase;
+}

package/src/rules/load-rejection-schema.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import type { LoadRejection, LoadRejectionReason } from './types.ts';
+
+const phase = brandSchemas.phaseName;
+const outcomeOfPhase = { phase, outcome: z.string() };
+
+const loadRejectionReasonSchema: z.ZodType<LoadRejectionReason> = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('invalid'), message: z.string() }),
+  z.object({ kind: z.literal('unknown-concept'), ref: z.string() }),
+  z.object({ kind: z.literal('unknown-signal'), signal: z.string() }),
+  z.object({
+    kind: z.literal('bad-plugin-params'),
+    pluginKind: z.enum(['signal', 'gate', 'admission']),
+    name: z.string(),
+    message: z.string(),
+  }),
+  z.object({ kind: z.literal('unknown-relation-type'), relation: z.string() }),
+  z.object({ kind: z.literal('signal-without-combine'), signal: z.string() }),
+  z.object({ kind: z.literal('missing-recipe'), itemKind: z.string(), phase: z.string() }),
+  z.object({ kind: z.literal('missing-prompt'), path: z.string() }),
+  z.object({ kind: z.literal('uncommitted-changes') }),
+  z.object({ kind: z.literal('unknown-filter-field'), field: z.string() }),
+  z.object({ kind: z.literal('pool-without-limit'), pool: z.string() }),
+  z.object({ kind: z.literal('unknown-phase'), phase: z.string() }),
+  z.object({ kind: z.literal('unmapped-outcome'), ...outcomeOfPhase }),
+  z.object({ kind: z.literal('unknown-outcome'), ...outcomeOfPhase }),
+  z.object({ kind: z.literal('open-loop'), ...outcomeOfPhase }),
+  z.object({ kind: z.literal('edge-to-unknown-phase'), phase, to: z.string() }),
+  z.object({
+    kind: z.literal('step-without-recipe'),
+    itemKind: brandSchemas.itemKindName,
+    phase,
+  }),
+  z.object({ kind: z.literal('step-without-timeout'), phase }),
+  z.object({ kind: z.literal('quiet-below-idle') }),
+  z.object({ kind: z.literal('unattended-below-quiet') }),
+  z.object({
+    kind: z.literal('engine-outcome-listed'),
+    phase,
+    outcome: z.enum(['lost', 'unsettleable']),
+  }),
+  z.object({ kind: z.literal('skills-without-pin'), recipe: z.string() }),
+  z.object({ kind: z.literal('resume-on-forward-edge'), ...outcomeOfPhase }),
+]);
+
+export const loadRejectionSchema: z.ZodType<LoadRejection> = z.object({
+  file: z.string(),
+  path: z.string(),
+  reason: loadRejectionReasonSchema,
+});

package/src/rules/types.ts

@@ -0,0 +1,291 @@
+import type { JsonValue } from '@boxxy/content-hash';
+import type { z } from 'zod';
+import type { CloseOutParser, Effect } from '../closeouts/types.ts';
+import type { RulesHoldReason } from '../pipeline/types.ts';
+import type {
+  Admission,
+  FrameItem,
+  Gate,
+  Limit,
+  Pool,
+  PropagationLine,
+  Signal,
+  SignalKey,
+  SignalName,
+  View,
+  Waiver,
+} from '../planning/types.ts';
+import type {
+  AttemptRow,
+  CommitSha,
+  ConceptPin,
+  EngineOutcome,
+  Instant,
+  ItemKindName,
+  ItemView,
+  LeverKind,
+  Minutes,
+  PhaseName,
+  PipelineName,
+  PullRequestRow,
+  RecipeMaterial,
+  RecipeName,
+  RelationTypeName,
+  RulesVersion,
+  SessionMode,
+  WorkerKindName,
+} from '../types.ts';
+
+export type Schema<T> = z.ZodType<T>;
+
+export interface ParamKinds<P> {
+  signal: Signal<P>;
+  gate: Gate<P>;
+  admission: Admission<P>;
+}
+
+export type ParamKindName = keyof ParamKinds<unknown>;
+
+export interface Registered<K extends ParamKindName> {
+  readonly kind: K;
+  readonly name: string;
+  open: <R>(use: <P>(plugin: ParamKinds<P>[K]) => R) => R;
+}
+
+export interface Resolved<K extends ParamKindName> {
+  readonly kind: K;
+  readonly name: string;
+
+  // `signalKey(name, params)` for a signal, and the name for a gate
+  readonly key: string;
+  open: <R>(use: <P>(plugin: ParamKinds<P>[K], params: P) => R) => R;
+}
+
+export type ConceptName = string;
+
+export interface Concept {
+  name: ConceptName;
+  version: number;
+  signals?: Registered<'signal'>[];
+  gates?: Registered<'gate'>[];
+  waivers?: Waiver[];
+  levers?: LeverKind[];
+  filterFields?: FilterField[];
+}
+
+export interface FilterField {
+  name: string;
+
+  // null never matches a filter on this field
+  value: (item: FrameItem) => string | readonly string[] | null;
+}
+
+export interface PlainKinds {
+  waiver: Waiver;
+  'filter-field': FilterField;
+  lever: { readonly kind: LeverKind };
+  view: View;
+}
+
+export type PluginKindName = ParamKindName | keyof PlainKinds;
+
+export type Registry = { readonly [K in ParamKindName]: ReadonlyMap<string, Registered<K>> } & {
+  readonly [K in keyof PlainKinds]: ReadonlyMap<string, PlainKinds[K]>;
+} & { readonly pins: readonly ConceptPin[] };
+
+// The code of one phase. Its `outcomes` are the one list of the phase's outcome names: the
+// loader checks the rules against it, and `settle` answers with one of them.
+export interface PhaseKind<
+  Body = unknown,
+  Input extends JsonValue = JsonValue,
+  Outcomes extends readonly string[] = readonly string[],
+> {
+  readonly name: PhaseName;
+  readonly version: number;
+  readonly worker: WorkerKindName;
+  readonly outcomes: Outcomes;
+  readonly needsAcceptance: boolean;
+
+  // the session mode of an attempt of this phase; agent when the kind sets none
+  readonly mode?: (item: ItemView) => SessionMode;
+  readonly input: (ctx: PhaseInputContext) => Input;
+  readonly closeOut: CloseOutParser<Body>;
+
+  // Called only with the attempt's valid close-out. A method's parameter is bivariant, so a
+  // phase kind of any body still fits `PhaseKind`; a plain function property would refuse it.
+  readonly settle: BivariantSettle<Body, Outcomes[number]>['settle'];
+}
+
+interface BivariantSettle<Body, Outcome extends string> {
+  // oxlint-disable-next-line typescript/method-signature-style -- the method form is what makes the parameter bivariant
+  settle(input: SettleInput<Body>): Settlement<Outcome>;
+}
+
+export interface PhaseInputContext {
+  readonly item: ItemView;
+
+  // the item's attempts, oldest first
+  readonly history: readonly AttemptRow[];
+  readonly pullRequests: readonly PullRequestRow[];
+}
+
+export interface SettleInput<Body> {
+  readonly attempt: AttemptRow;
+  readonly item: ItemView;
+  readonly closeOut: Body;
+  readonly now: Instant;
+}
+
+export interface Settlement<Outcome extends string = string> {
+  readonly state: 'succeeded' | 'failed';
+  readonly failure: string | null;
+  readonly outcome: Outcome;
+  readonly effects: readonly Effect[];
+  readonly frictionDropped: number;
+}
+
+export interface KindRules {
+  readonly pipeline: Pipeline;
+
+  // by phase, and by `<phase>/attended` for an attended session of the phase
+  readonly recipes: Readonly<Record<string, RecipeName>>;
+}
+
+export interface Pipeline {
+  readonly name: PipelineName;
+  readonly steps: readonly PipelineStep[];
+}
+
+export interface PipelineStep {
+  readonly phase: PhaseName;
+
+  // attempts in a row that ended `lost` or took an `again` edge
+  readonly maxAttempts: number;
+
+  // the clock of one stretch of running of an agent-mode attempt
+  readonly timeoutMinutes: Minutes;
+
+  // an entry for every outcome of the phase kind
+  readonly on: Readonly<Record<string, Edge>>;
+}
+
+export type Edge =
+  | 'next'
+  | 'again'
+  | { readonly to: PhaseName; readonly max?: number; readonly resume?: boolean }
+  | { readonly end: string }
+  | { readonly hold: RulesHoldReason };
+
+export interface SkillsPin {
+  // the repository, as owner/name
+  readonly source: string;
+  readonly ref: CommitSha;
+}
+
+// A relation type is registry data: the rules file lists the names, and a new type needs no code.
+export interface RelationType {
+  readonly name: RelationTypeName;
+}
+
+export interface SleepRules {
+  readonly afterIdleMinutes: Minutes;
+  readonly afterQuietMinutes: Minutes;
+  readonly afterUnattendedMinutes: Minutes;
+}
+
+export type ConceptEntry = `${string}@${number}`;
+
+export type PluginRef = string | Readonly<Record<string, JsonValue>>;
+
+export type SignalRef = SignalName | Readonly<Record<string, JsonValue>>;
+
+// What an item's position and state read of the rules loaded now; a `LoadedRules` is one.
+export interface ItemRules {
+  readonly kinds: ReadonlyMap<ItemKindName, { readonly pipeline: Pipeline }>;
+  readonly phases: ReadonlyMap<PhaseName, { readonly needsAcceptance: boolean }>;
+}
+
+export interface LoadedRules {
+  readonly version: RulesVersion;
+  readonly commit: string;
+  readonly registry: Registry;
+  readonly signals: ReadonlyMap<SignalKey, Resolved<'signal'>>;
+  readonly gates: readonly Resolved<'gate'>[];
+  readonly kinds: ReadonlyMap<ItemKindName, KindRules>;
+  readonly phases: ReadonlyMap<PhaseName, PhaseKind>;
+  readonly limits: readonly Limit[];
+
+  // in declared order, each pool's `order` starting with `lead`
+  readonly pools: readonly Pool[];
+  readonly propagation: readonly PropagationLine[];
+  readonly recipes: ReadonlyMap<RecipeName, RecipeMaterial>;
+  readonly sleep: SleepRules;
+
+  // null when the rules file has no `skills` block
+  readonly skills: SkillsPin | null;
+  readonly relationTypes: ReadonlyMap<RelationTypeName, RelationType>;
+}
+
+export interface LoadRejection {
+  readonly file: string;
+  readonly path: string;
+  readonly reason: LoadRejectionReason;
+}
+
+export type LoadRejectionReason =
+  | { readonly kind: 'invalid'; readonly message: string }
+  | { readonly kind: 'unknown-concept'; readonly ref: string }
+  | { readonly kind: 'unknown-signal'; readonly signal: string }
+  | {
+      readonly kind: 'bad-plugin-params';
+      readonly pluginKind: ParamKindName;
+      readonly name: string;
+      readonly message: string;
+    }
+  | { readonly kind: 'unknown-relation-type'; readonly relation: string }
+  | { readonly kind: 'signal-without-combine'; readonly signal: string }
+  | { readonly kind: 'missing-recipe'; readonly itemKind: string; readonly phase: string }
+  | { readonly kind: 'missing-prompt'; readonly path: string }
+  | { readonly kind: 'uncommitted-changes' }
+
+  // a limit's `counts` or a pool's `takes` names a field that no concept registers
+  | { readonly kind: 'unknown-filter-field'; readonly field: string }
+
+  // a pool can take an item that no limit counts, so its picks would have no bound
+  | { readonly kind: 'pool-without-limit'; readonly pool: string }
+  | { readonly kind: 'unknown-phase'; readonly phase: string }
+  | { readonly kind: 'unmapped-outcome'; readonly phase: PhaseName; readonly outcome: string }
+  | { readonly kind: 'unknown-outcome'; readonly phase: PhaseName; readonly outcome: string }
+  | { readonly kind: 'open-loop'; readonly phase: PhaseName; readonly outcome: string }
+  | { readonly kind: 'edge-to-unknown-phase'; readonly phase: PhaseName; readonly to: string }
+  | {
+      readonly kind: 'step-without-recipe';
+      readonly itemKind: ItemKindName;
+      readonly phase: PhaseName;
+    }
+  | { readonly kind: 'step-without-timeout'; readonly phase: PhaseName }
+  | { readonly kind: 'quiet-below-idle' }
+  | { readonly kind: 'unattended-below-quiet' }
+  | {
+      readonly kind: 'engine-outcome-listed';
+      readonly phase: PhaseName;
+      readonly outcome: EngineOutcome;
+    }
+  | { readonly kind: 'skills-without-pin'; readonly recipe: string }
+  | {
+      readonly kind: 'resume-on-forward-edge';
+      readonly phase: PhaseName;
+      readonly outcome: string;
+    }
+
+  // a `hold` edge names one of the engine's hold reasons
+  | {
+      readonly kind: 'engine-hold-reason';
+      readonly phase: PhaseName;
+      readonly outcome: string;
+      readonly reason: string;
+    };
+
+export type LoadResult =
+  | { readonly kind: 'loaded'; readonly rules: LoadedRules; readonly warnings: readonly string[] }
+  | { readonly kind: 'rejected'; readonly rejections: readonly LoadRejection[] };