@boxxy/model 0.1.0 → 0.1.2

package/README.md

@@ -5,12 +5,17 @@
     <a href="https://www.npmjs.com/package/@boxxy/model"><img src="https://img.shields.io/npm/v/@boxxy/model" alt="npm version"></a>
     <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
   </p>
+
+  <p>
+    <a href="../../docs/design/boxxy/README.md">Documentation</a>
+  </p>
 </div>
 
 The types that boxxy's packages share, with the fact catalog and its schemas.
 
-This version is a placeholder that exports only its package name, as `packageName`. The
-[boxxy README](https://github.com/zgeoff/boxxy#workspace) lists the workspace's packages.
+Every boxxy package that reads or writes a store row, a fact or a port imports its types from here.
+The package does no I/O: it takes the time as an argument, and it holds only types, zod schemas and
+pure functions.
 
 ## Install
 
@@ -21,3 +26,23 @@ bun add @boxxy/model
 ```
 
 The package runs on [Bun](https://bun.sh) 1.3 or newer.
+
+## Features
+
+- The branded ids and names, with a zod schema for each in `brandSchemas`.
+- The store rows, the port interfaces, the plug-in interfaces and the loaded rules.
+- The fact catalog, with a zod schema for each fact type's payload in `factSchemas`
+  ([facts and the outbox](../../docs/design/boxxy/slice-1.md#facts-and-the-outbox)).
+- `BuildCloseOut` and its schema, `buildCloseOutSchema`
+  ([the build close-out](../../docs/design/boxxy/slice-1.md#the-build-close-out)).
+- `deriveItemState`, which derives an item's state from its rows
+  ([derived item state](../../docs/design/boxxy/slice-1.md#derived-item-state)).
+- `liveLevers`, which drops the levers a later undo lever cancels and those past their expiry.
+- `signalKey`, which builds a signal's key from its name and the content hash of its parameters.
+- `defineSignal`, `defineGate` and `defineAdmission`, which register a plug-in with its parameter
+  type hidden.
+
+## Documentation
+
+The [boxxy design docs](../../docs/design/boxxy/README.md) describe each type, and the
+[interface sketches](../../docs/design/boxxy/sketches/README.md) give its shape.

package/dist/actor-ref-schema.d.ts

@@ -0,0 +1,2 @@
+import { z } from 'zod';
+export declare const actorRefSchema: z.ZodUnion<readonly [z.ZodLiteral<"boxxy:owner:local">, z.ZodTemplateLiteral<`boxxy:runner:${string & z.$brand<"RunnerId">}`>, z.ZodTemplateLiteral<`boxxy:attempt:${string & z.$brand<"AttemptId">}`>, z.ZodTemplateLiteral<`boxxy:hook:${string & z.$brand<"AttemptId">}`>]>;

package/dist/brand-schemas.d.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+export declare const brandSchemas: {
+    instant: z.core.$ZodBranded<z.ZodNumber, "Instant", "out">;
+    itemId: z.core.$ZodBranded<z.ZodString, "ItemId", "out">;
+    attemptId: z.core.$ZodBranded<z.ZodString, "AttemptId", "out">;
+    decisionId: z.core.$ZodBranded<z.ZodString, "DecisionId", "out">;
+    factId: z.core.$ZodBranded<z.ZodTemplateLiteral<`manual:${string}`>, "FactId", "out">;
+    runnerId: z.core.$ZodBranded<z.ZodString, "RunnerId", "out">;
+    atcSessionId: z.core.$ZodBranded<z.ZodString, "AtcSessionId", "out">;
+    agentSessionId: z.core.$ZodBranded<z.ZodString, "AgentSessionId", "out">;
+    commitSha: z.core.$ZodBranded<z.ZodString, "CommitSha", "out">;
+    repoName: z.core.$ZodBranded<z.ZodString, "RepoName", "out">;
+    criterionId: z.core.$ZodBranded<z.ZodString, "CriterionId", "out">;
+    itemKindName: z.core.$ZodBranded<z.ZodString, "ItemKindName", "out">;
+    linkTypeName: z.core.$ZodBranded<z.ZodString, "LinkTypeName", "out">;
+    phaseName: z.core.$ZodBranded<z.ZodString, "PhaseName", "out">;
+    pipelineName: z.core.$ZodBranded<z.ZodString, "PipelineName", "out">;
+    poolName: z.core.$ZodBranded<z.ZodString, "PoolName", "out">;
+    recipeName: z.core.$ZodBranded<z.ZodString, "RecipeName", "out">;
+    workerKindName: z.core.$ZodBranded<z.ZodString, "WorkerKindName", "out">;
+    sourceName: z.core.$ZodBranded<z.ZodString, "SourceName", "out">;
+    streamName: z.core.$ZodBranded<z.ZodString, "StreamName", "out">;
+    recipeHash: z.core.$ZodBranded<z.core.$ZodBranded<z.ZodString, "ContentHash", "out">, "RecipeHash", "out">;
+    snapshotHash: z.core.$ZodBranded<z.core.$ZodBranded<z.ZodString, "ContentHash", "out">, "SnapshotHash", "out">;
+    rulesVersion: z.core.$ZodBranded<z.core.$ZodBranded<z.ZodString, "ContentHash", "out">, "RulesVersion", "out">;
+};

package/dist/build-applied-change.d.ts

@@ -0,0 +1,13 @@
+import type { AttemptId, PoolName } from './types/core.ts';
+import type { StoreChange } from './types/ports.ts';
+export interface TakenSlot {
+    readonly holder: AttemptId;
+    readonly pool: PoolName;
+    readonly slot: number;
+    readonly gen: number;
+}
+export interface ChangeAssignments {
+    readonly taken: TakenSlot | null;
+    readonly lastLeverSeq: number;
+}
+export declare function buildAppliedChange(change: StoreChange, assignments: ChangeAssignments): Pick<StoreChange, 'writes' | 'facts'>;

package/dist/build-close-out-schema.d.ts

@@ -0,0 +1,3 @@
+import { z } from 'zod';
+import type { BuildCloseOut } from './types/facts.ts';
+export declare const buildCloseOutSchema: z.ZodType<BuildCloseOut>;

package/dist/build-item-views.d.ts

@@ -0,0 +1,2 @@
+import type { Instant, ItemSetRows, ItemWithLevers, MaxAttemptsByKind } from './types/core.ts';
+export declare function buildItemViews(rows: ItemSetRows, now: Instant, maxAttemptsByKind: MaxAttemptsByKind): ItemWithLevers[];

package/dist/define-admission.d.ts

@@ -0,0 +1,3 @@
+import type { Admission } from './types/planning.ts';
+import type { Registered } from './types/registries.ts';
+export declare function defineAdmission<P>(admission: Admission<P>): Registered<'admission'>;

package/dist/define-gate.d.ts

@@ -0,0 +1,3 @@
+import type { Gate } from './types/planning.ts';
+import type { Registered } from './types/registries.ts';
+export declare function defineGate<P>(gate: Gate<P>): Registered<'gate'>;

package/dist/define-signal.d.ts

@@ -0,0 +1,3 @@
+import type { Signal } from './types/planning.ts';
+import type { Registered } from './types/registries.ts';
+export declare function defineSignal<P>(signal: Signal<P>): Registered<'signal'>;

package/dist/derive-item-state.d.ts

@@ -0,0 +1,2 @@
+import type { DerivedState, ItemRow, ItemRows } from './types/core.ts';
+export declare function deriveItemState(item: ItemRow, rows: ItemRows): DerivedState;

package/dist/fact-schemas.d.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+import type { FactType, SliceOneFacts } from './types/facts.ts';
+export declare const factSchemas: {
+    readonly [T in FactType]: z.ZodType<SliceOneFacts[T]>;
+};

package/dist/find-slot-take.d.ts

@@ -0,0 +1,5 @@
+import type { RowWrite } from './types/ports.ts';
+export type SlotTake = Extract<RowWrite, {
+    op: 'take-slot';
+}>;
+export declare function findSlotTake(writes: readonly RowWrite[]): SlotTake | null;

package/dist/format-key-path.d.ts

@@ -0,0 +1 @@
+export declare function formatKeyPath(segments: readonly PropertyKey[]): string;

package/dist/friction-schema.d.ts

@@ -0,0 +1,3 @@
+import { z } from 'zod';
+import type { Friction } from './types/facts.ts';
+export declare const frictionSchema: z.ZodType<Friction>;

package/dist/index.d.ts

@@ -1 +1,24 @@
-export { packageName } from './package-name.ts';
+export type { ContentHash, JsonValue } from '@boxxy/content-hash';
+export { brandSchemas } from './brand-schemas.ts';
+export { buildAppliedChange, type ChangeAssignments, type TakenSlot, } from './build-applied-change.ts';
+export { buildCloseOutSchema } from './build-close-out-schema.ts';
+export { buildItemViews } from './build-item-views.ts';
+export { defineAdmission } from './define-admission.ts';
+export { defineGate } from './define-gate.ts';
+export { defineSignal } from './define-signal.ts';
+export { deriveItemState } from './derive-item-state.ts';
+export { factSchemas } from './fact-schemas.ts';
+export { findSlotTake, type SlotTake } from './find-slot-take.ts';
+export { formatKeyPath } from './format-key-path.ts';
+export { frictionSchema } from './friction-schema.ts';
+export { liveLevers } from './live-levers.ts';
+export { outboxFactSchema } from './outbox-fact-schema.ts';
+export { rowSchemas } from './row-schemas.ts';
+export { signalKey } from './signal-key.ts';
+export { toJSONValue } from './to-json-value.ts';
+export type { Actor, ActorRef, AgentSessionId, AtcSessionId, AttemptId, AttemptRow, AttemptSessionRow, AttemptState, CommitSha, ConceptPin, Criterion, CriterionId, DecisionId, DecisionRow, DerivedState, Effort, EvidenceKind, EvidenceRow, EvidenceSource, FactId, FaultRecord, ForcedFailure, Instant, ItemId, ItemKindName, ItemRow, ItemRows, ItemSetRows, ItemState, ItemView, ItemWithLevers, KnownFailure, LeaseRow, LeverKind, LeverRow, LinkRow, LinkTypeName, LiveAttemptState, LoadedRecipe, MaxAttemptsByKind, Minutes, ObservationBoundary, PhaseName, PipelineName, PoolName, PoolSlotRow, PullRequestRef, PullRequestRow, Recipe, RecipeHash, RecipeMaterial, RecipeName, RepoName, ResolvedRecipe, RulesVersion, RunnerId, RunnerRow, SnapshotHash, SourceName, StreamName, WaitingReason, WorkerKindName, } from './types/core.ts';
+export type { Claim, CloseOutContext, CloseOutParse, CloseOutParser, CloseOutProblem, ReconcileAction, ReconcileTable, SettleInput, Settlement, SettleRule, SpawnContext, } from './types/dispatch.ts';
+export type { BuildCloseOut, EntityRef, FactEnvelope, FactType, Friction, FrictionTargetKind, LinkPayload, NewFact, OpenItem, OutboxFact, SliceOneFacts, } from './types/facts.ts';
+export type { Admission, AdmissionGrant, AdmissionName, Decision, Fault, Frame, FrameItem, FrameValues, Gate, GateName, Hold, Lift, Pick, PlanContext, Pool, PropagationLine, Signal, SignalKey, SignalName, Snapshot, View, ViewName, Waiver, WaiverName, } from './types/planning.ts';
+export type { AnyNewFact, ApplyResult, ClaimStore, Clock, CostReader, CostToLandInput, CostToLandRow, FactSink, Forge, ItemDetailRows, ItemFilter, NewId, PullRequestReading, RowWrite, SessionFault, SessionReading, SpawnRequest, StartOutcome, StoreChange, StoreReader, StoreTx, TableName, Tables, WorkerKind, } from './types/ports.ts';
+export type { Concept, ConceptEntry, ConceptName, FilterField, KindRules, LoadedRules, LoadRejection, LoadRejectionReason, LoadResult, ParamKindName, ParamKinds, Pipeline, PipelineStep, PlainKinds, PluginKindName, PluginRef, Registered, Registry, Resolved, RulesFile, Schema, SignalRef, } from './types/registries.ts';

package/dist/live-levers.d.ts

@@ -0,0 +1,2 @@
+import type { Instant, LeverRow } from './types/core.ts';
+export declare function liveLevers(levers: readonly LeverRow[], now: Instant): LeverRow[];

package/dist/outbox-fact-schema.d.ts

@@ -0,0 +1,3 @@
+import { z } from 'zod';
+import type { OutboxFact } from './types/facts.ts';
+export declare const outboxFactSchema: z.ZodType<OutboxFact>;

package/dist/row-schemas.d.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+import type { TableName, Tables } from './types/ports.ts';
+export declare const rowSchemas: {
+    readonly [T in TableName]: z.ZodType<Tables[T]>;
+};

package/dist/signal-key.d.ts

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

package/dist/test-utils/build-mock-attempt-row.d.ts

@@ -0,0 +1,2 @@
+import type { AttemptRow } from '../types/core.ts';
+export declare function buildMockAttemptRow(overrides?: Partial<AttemptRow>): AttemptRow;

package/dist/test-utils/build-mock-evidence-row.d.ts

@@ -0,0 +1,2 @@
+import type { EvidenceRow } from '../types/core.ts';
+export declare function buildMockEvidenceRow(overrides?: Partial<EvidenceRow>): EvidenceRow;

package/dist/test-utils/build-mock-fact-id.d.ts

@@ -0,0 +1,2 @@
+import type { FactId } from '../types/core.ts';
+export declare function buildMockFactId(): FactId;

package/dist/test-utils/build-mock-frame-item.d.ts

@@ -0,0 +1,2 @@
+import type { FrameItem } from '../types/planning.ts';
+export declare function buildMockFrameItem(overrides?: Partial<FrameItem>): FrameItem;

package/dist/test-utils/build-mock-item-row.d.ts

@@ -0,0 +1,2 @@
+import type { ItemRow } from '../types/core.ts';
+export declare function buildMockItemRow(overrides?: Partial<ItemRow>): ItemRow;

package/dist/test-utils/build-mock-item-rows.d.ts

@@ -0,0 +1,2 @@
+import type { ItemRows } from '../types/core.ts';
+export declare function buildMockItemRows(overrides?: Partial<ItemRows>): ItemRows;

package/dist/test-utils/build-mock-item-view.d.ts

@@ -0,0 +1,2 @@
+import type { ItemView } from '../types/core.ts';
+export declare function buildMockItemView(overrides?: Partial<ItemView>): ItemView;

package/dist/test-utils/build-mock-lease-row.d.ts

@@ -0,0 +1,2 @@
+import type { LeaseRow } from '../types/core.ts';
+export declare function buildMockLeaseRow(overrides?: Partial<LeaseRow>): LeaseRow;

package/dist/test-utils/build-mock-lever-row.d.ts

@@ -0,0 +1,2 @@
+import type { LeverRow } from '../types/core.ts';
+export declare function buildMockLeverRow(overrides?: Partial<LeverRow>): LeverRow;

package/dist/test-utils/build-mock-link-row.d.ts

@@ -0,0 +1,2 @@
+import type { LinkRow } from '../types/core.ts';
+export declare function buildMockLinkRow(overrides?: Partial<LinkRow>): LinkRow;

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

@@ -0,0 +1,2 @@
+import type { PullRequestRow } from '../types/core.ts';
+export declare function buildMockPullRequestRow(overrides?: Partial<PullRequestRow>): PullRequestRow;

package/dist/test-utils/build-mock-snapshot.d.ts

@@ -0,0 +1,2 @@
+import type { Snapshot } from '../types/planning.ts';
+export declare function buildMockSnapshot(overrides?: Partial<Snapshot>): Snapshot;

package/dist/test-utils/seed-faker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/to-json-value.d.ts

@@ -0,0 +1,2 @@
+import type { JsonValue } from '@boxxy/content-hash';
+export declare function toJSONValue(value: unknown): JsonValue;

package/dist/types/core.d.ts

@@ -0,0 +1,233 @@
+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 {
+    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[];
+    readonly maxAttempts: number;
+}
+export interface ItemSetRows {
+    readonly items: readonly ItemRow[];
+    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 {
+    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;
+    readonly prompt: string;
+    readonly source: SourceName;
+}
+export interface RecipeMaterial {
+    readonly name: RecipeName;
+    readonly recipe: Recipe;
+    readonly promptHash: ContentHash;
+    readonly pluginFolderHash: ContentHash;
+    readonly rulesVersion: RulesVersion;
+}
+export type LoadedRecipe = Omit<RecipeMaterial, 'pluginFolderHash'>;
+export interface ResolvedRecipe extends RecipeMaterial {
+    readonly hash: RecipeHash;
+}
+export {};

package/dist/types/dispatch.d.ts

@@ -0,0 +1,82 @@
+import type { ContentHash } from '@boxxy/content-hash';
+import type { AttemptId, AttemptRow, CriterionId, EvidenceRow, FactId, ForcedFailure, Instant, ItemView, KnownFailure, LiveAttemptState, Minutes, RecipeName, RepoName } from './core.ts';
+import type { Friction, OpenItem } from './facts.ts';
+import type { SessionReading, SpawnRequest } from './ports.ts';
+export interface SpawnContext {
+    readonly repoPaths: ReadonlyMap<RepoName, string>;
+    readonly pluginFolder: {
+        readonly path: string;
+        readonly hash: ContentHash;
+    };
+    readonly promptTemplates: ReadonlyMap<RecipeName, string>;
+}
+export interface Claim {
+    readonly attempt: AttemptRow;
+    readonly spawn: SpawnRequest;
+}
+export type ReconcileAction = {
+    readonly kind: 'move-to-running';
+    readonly fact: 'boxxy.attempt.started' | 'boxxy.attempt.reconciled';
+} | {
+    readonly kind: 'bind-session';
+} | {
+    readonly kind: 'settle';
+} | {
+    readonly kind: 'fail';
+    readonly failure: Extract<KnownFailure, 'session-lost'>;
+} | {
+    readonly kind: 'respawn';
+    readonly giveUpAfter: Minutes;
+    readonly then: Extract<KnownFailure, 'spawn-lost'>;
+};
+export type ReconcileTable = Readonly<Record<SessionReading['kind'], Readonly<Record<LiveAttemptState, ReconcileAction>>>>;
+export interface Settlement {
+    readonly state: 'succeeded' | 'failed';
+    readonly failure: string | null;
+    readonly openItems: readonly OpenItem[];
+    readonly criteria: readonly {
+        readonly criterion: CriterionId;
+        readonly evidence: readonly FactId[];
+    }[];
+    readonly friction: readonly Friction[];
+    readonly frictionDropped: number;
+}
+export interface SettleRule<Out = unknown> {
+    settle: (input: SettleInput<Out>) => Settlement;
+}
+export interface SettleInput<Out> {
+    readonly attempt: AttemptRow;
+    readonly item: ItemView;
+    readonly closeOut: CloseOutParse<Out> | null;
+    readonly forced: ForcedFailure | null;
+    readonly now: Instant;
+}
+export interface CloseOutContext {
+    readonly item: ItemView;
+    readonly attempt: AttemptId;
+    readonly evidence: readonly EvidenceRow[];
+}
+export type CloseOutProblem = {
+    readonly kind: 'schema';
+    readonly path: string;
+    readonly message: string;
+} | {
+    readonly kind: 'unknown-criterion';
+    readonly criterion: CriterionId;
+} | {
+    readonly kind: 'foreign-evidence';
+    readonly evidence: FactId;
+} | {
+    readonly kind: 'built-without-evidence';
+    readonly criteria: readonly CriterionId[];
+};
+export type CloseOutParse<Out> = {
+    readonly kind: 'valid';
+    readonly closeOut: Out;
+} | {
+    readonly kind: 'invalid';
+    readonly problems: readonly CloseOutProblem[];
+};
+export interface CloseOutParser<Out> {
+    parse: (raw: unknown, ctx: CloseOutContext) => CloseOutParse<Out>;
+}