@boxxy/model 0.0.0 → 0.1.1

package/src/types/core.ts

@@ -0,0 +1,287 @@
+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;
+}
+
+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 or waiver name, or `propagation:<signal>:<link>`
+  readonly plugin: string;
+  readonly kind: 'signal' | 'gate' | 'waiver' | 'admission' | 'propagation';
+  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;
+}

package/src/types/dispatch.ts

@@ -0,0 +1,95 @@
+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;
+
+  // a `forced` reason wins over the close-out's state
+  readonly forced: ForcedFailure | null;
+  readonly now: Instant;
+}
+
+export interface CloseOutContext {
+  readonly item: ItemView;
+  readonly attempt: AttemptId;
+
+  // the attempt's own evidence rows
+  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>;
+}

package/src/types/facts.ts

@@ -0,0 +1,166 @@
+import type { JsonValue } from '@boxxy/content-hash';
+import type {
+  ActorRef,
+  AgentSessionId,
+  AtcSessionId,
+  CommitSha,
+  Criterion,
+  CriterionId,
+  DecisionRow,
+  EvidenceKind,
+  FactId,
+  Instant,
+  ItemId,
+  ItemRow,
+  LeverRow,
+  LinkTypeName,
+  PhaseName,
+  PoolName,
+  RecipeHash,
+  RepoName,
+  RulesVersion,
+  RunnerId,
+} from './core.ts';
+
+export interface BuildCloseOut {
+  readonly result:
+    | { readonly kind: 'built' }
+    | { readonly kind: 'blocked'; readonly reason: string }
+    | { readonly kind: 'abandoned'; readonly reason: string };
+  readonly criteria: readonly { readonly criterion: CriterionId; readonly evidence: FactId }[];
+  readonly openItems: readonly OpenItem[];
+  readonly friction: readonly Friction[];
+  readonly frictionDropped: number;
+}
+
+export interface OpenItem {
+  readonly kind: 'core.issue';
+  readonly title: string;
+  readonly body: string;
+}
+
+export type FrictionTargetKind = 'skill' | 'rule' | 'lint' | 'agents-md' | 'tool';
+
+export interface Friction {
+  readonly target: { readonly kind: FrictionTargetKind; readonly name: string };
+  readonly change: string;
+}
+
+export type EntityRef =
+  | `boxxy:item:${string}`
+  | `boxxy:link:${string}:${string}:${string}`
+  | `boxxy:attempt:${string}`
+  | `boxxy:decision:${string}`
+  | `boxxy:runner:${string}`;
+
+export interface FactEnvelope<
+  M extends object = SliceOneFacts,
+  T extends keyof M & string = keyof M & string,
+> {
+  readonly id: FactId;
+  readonly type: T;
+
+  // oxlint-disable-next-line id-length -- pepys's fact envelope names this field
+  readonly v: 1;
+  readonly api: 'boxxy/1';
+  readonly entity: EntityRef;
+  readonly actor: ActorRef;
+  readonly at: Instant;
+  readonly payload: M[T] & { readonly storeVersion: number };
+}
+
+export interface NewFact<T extends keyof M & string, M extends object = SliceOneFacts> {
+  readonly id: FactId;
+  readonly type: T;
+  readonly entity: EntityRef;
+  readonly actor: ActorRef;
+  readonly payload: M[T];
+}
+
+export interface OutboxFact {
+  readonly seq: number;
+  readonly factId: FactId;
+  readonly type: string;
+  readonly entity: EntityRef;
+  readonly actor: ActorRef;
+  readonly at: Instant;
+  readonly payload: JsonValue;
+  readonly sentAt: Instant | null;
+}
+
+export type FactType = keyof SliceOneFacts;
+
+export interface LinkPayload {
+  readonly source: ItemId;
+  readonly target: ItemId;
+  readonly type: LinkTypeName;
+}
+
+export interface SliceOneFacts {
+  'boxxy.item.filed': ItemRow;
+  'boxxy.item.edited': {
+    readonly title?: string;
+    readonly outcome?: string;
+    readonly acceptance?: readonly Criterion[];
+  };
+  'boxxy.item.closed': { readonly reason: string };
+  'boxxy.link.added': LinkPayload;
+  'boxxy.link.removed': LinkPayload;
+  'boxxy.lever.recorded': LeverRow;
+  'boxxy.attempt.claimed': {
+    readonly item: ItemId;
+    readonly phase: PhaseName;
+    readonly number: number;
+    readonly pool: PoolName;
+    readonly slot: number;
+    readonly gen: number;
+    readonly recipeHash: RecipeHash;
+    readonly rulesVersion: RulesVersion;
+  };
+  'boxxy.decision.recorded': DecisionRow;
+  'boxxy.attempt.started': { readonly atcSession: AtcSessionId };
+  'boxxy.attempt.reconciling': { readonly reason: string };
+  'boxxy.attempt.reconciled': { readonly atcSession: AtcSessionId };
+  'boxxy.attempt.session_bound': {
+    readonly atcSession: AtcSessionId;
+    readonly agentSession: AgentSessionId;
+    readonly seenAt: Instant;
+  };
+  'boxxy.attempt.closed_out': { readonly closeOut: BuildCloseOut };
+  'boxxy.attempt.settled': {
+    readonly state: 'succeeded' | 'failed';
+    readonly failure: string | null;
+    readonly endedAt: Instant;
+    readonly criteria: readonly {
+      readonly criterion: CriterionId;
+      readonly evidence: readonly FactId[];
+    }[];
+    readonly matched: readonly ItemId[];
+    readonly frictionDropped: number;
+  };
+  'boxxy.evidence.recorded': {
+    readonly kind: EvidenceKind;
+    readonly ref: string;
+    readonly observed: string | null;
+  };
+  'boxxy.evidence.pr_linked': {
+    readonly repo: RepoName;
+    readonly number: number;
+    readonly url: string;
+  };
+  'boxxy.evidence.commit_linked': {
+    readonly repo: RepoName;
+    readonly sha: CommitSha;
+    readonly pr: number;
+  };
+  'boxxy.pr.merged': {
+    readonly repo: RepoName;
+    readonly number: number;
+    readonly mergedAt: Instant;
+    readonly mergeCommit: CommitSha;
+  };
+  'boxxy.pr.closed': { readonly repo: RepoName; readonly number: number };
+  'boxxy.proposal.recorded': Friction;
+  'boxxy.runner.paused': { readonly runner: RunnerId };
+  'boxxy.runner.resumed': { readonly runner: RunnerId };
+}

package/src/types/planning.ts

@@ -0,0 +1,136 @@
+import type {
+  FaultRecord,
+  Instant,
+  ItemId,
+  ItemView,
+  LeverRow,
+  LinkRow,
+  LinkTypeName,
+  PhaseName,
+  PoolName,
+} from './core.ts';
+import type { Schema } from './registries.ts';
+
+export type SignalName = string;
+
+export type GateName = string;
+
+export type WaiverName = string;
+
+export type AdmissionName = string;
+
+export type ViewName = string;
+
+export type SignalKey = `${SignalName}#${string}`;
+
+export interface Snapshot {
+  storeVersion: number;
+
+  // every item not yet done and not archived, with its state derived at the read's `now`
+  items: ItemView[];
+  links: LinkRow[];
+  levers: LeverRow[];
+  freeSlots: Record<PoolName, number>;
+}
+
+export interface FrameItem extends ItemView {
+  readonly phase: PhaseName;
+}
+
+export interface Frame {
+  // the open items in state `ready`, the only items decide picks
+  candidates: FrameItem[];
+  fields: Map<ItemId, Readonly<Record<string, readonly string[]>>>;
+  values: Map<SignalKey, Map<ItemId, number>>;
+  holds: Map<ItemId, Hold[]>;
+  lifted: Map<ItemId, Lift[]>;
+  faults: Fault[];
+}
+
+export type FrameValues = ReadonlyMap<SignalKey, ReadonlyMap<ItemId, number>>;
+
+export interface Hold {
+  readonly gate: GateName;
+  readonly reason: string;
+  readonly until?: Instant;
+}
+
+export interface Lift {
+  readonly waiver: WaiverName;
+  readonly gate: GateName;
+  readonly reason: string;
+}
+
+export type Fault = FaultRecord;
+
+export interface Decision {
+  // in pool order, then by each pool's `order`
+  picks: Pick[];
+}
+
+export interface Pick {
+  item: ItemId;
+  phase: PhaseName;
+  pool: PoolName;
+}
+
+export interface Pool {
+  readonly name: PoolName;
+  readonly slots: number;
+  readonly takes: Readonly<Record<string, readonly string[]>>;
+
+  // `lead`, then the pool's own `order`: lower first, no value last, then item id
+  readonly order: readonly SignalKey[];
+}
+
+export interface PlanContext {
+  now: Instant;
+  levers: LeverRow[];
+  links: LinkRow[];
+  values: FrameValues;
+}
+
+export interface Signal<P> {
+  name: SignalName;
+  params: Schema<P>;
+
+  // null is no opinion
+  value: (item: FrameItem, ctx: PlanContext, params: P) => number | null;
+  combine?: (left: number, right: number) => number;
+}
+
+export interface Gate<P> {
+  name: GateName;
+  liftable: boolean;
+  params: Schema<P>;
+  hold: (item: FrameItem, ctx: PlanContext, params: P) => Hold | null;
+}
+
+export interface Waiver {
+  name: WaiverName;
+  lifts: GateName;
+  lift: (item: FrameItem, hold: Hold, ctx: PlanContext) => Lift | null;
+}
+
+export interface Admission<P> {
+  name: AdmissionName;
+  params: Schema<P>;
+  admit: (item: FrameItem, ctx: PlanContext, params: P) => AdmissionGrant | null;
+}
+
+export interface AdmissionGrant {
+  readonly admission: AdmissionName;
+  readonly pools: readonly PoolName[] | 'any';
+  readonly reason: string;
+}
+
+export interface View<I = unknown, O = unknown> {
+  name: ViewName;
+  render: (frame: Frame, input: I) => O;
+}
+
+export interface PropagationLine {
+  readonly value: SignalName;
+  readonly over: LinkTypeName;
+  readonly toward: 'source' | 'target';
+}