@boxxy/model 0.1.2 → 0.1.3

package/src/{types/core.ts → types.ts}

@@ -1,7 +1,8 @@
 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';
+import type { CloseOut } from './closeouts/types.ts';
+import type { HoldReason, Position } from './pipeline/types.ts';
+import type { brandSchemas } from './rows/brand-schemas.ts';
 
 type BrandOf<K extends keyof typeof brandSchemas> = z.output<(typeof brandSchemas)[K]>;
 
@@ -15,6 +16,8 @@ export type AttemptId = BrandOf<'attemptId'>;
 
 export type DecisionId = BrandOf<'decisionId'>;
 
+// A bare UUID version 7. The outbox row's fact ID, an evidence ID that a close-out cites, and
+// each ID in `settled.criteria[].evidence` all have this one brand.
 export type FactId = BrandOf<'factId'>;
 
 export type RunnerId = BrandOf<'runnerId'>;
@@ -36,7 +39,7 @@ export interface PullRequestRef {
 
 export type ItemKindName = BrandOf<'itemKindName'>;
 
-export type LinkTypeName = BrandOf<'linkTypeName'>;
+export type RelationTypeName = BrandOf<'relationTypeName'>;
 
 export type PhaseName = BrandOf<'phaseName'>;
 
@@ -44,6 +47,8 @@ export type PipelineName = BrandOf<'pipelineName'>;
 
 export type PoolName = BrandOf<'poolName'>;
 
+export type LimitName = BrandOf<'limitName'>;
+
 export type RecipeName = BrandOf<'recipeName'>;
 
 export type WorkerKindName = BrandOf<'workerKindName'>;
@@ -60,6 +65,9 @@ export type SnapshotHash = BrandOf<'snapshotHash'>;
 
 export type RulesVersion = BrandOf<'rulesVersion'>;
 
+// A name from a phase kind's `outcomes` list.
+export type OutcomeName = BrandOf<'outcomeName'>;
+
 export interface ConceptPin {
   readonly ref: `${string}@${number}`;
   readonly sourceHash: ContentHash;
@@ -77,7 +85,14 @@ export type ActorRef =
   | `boxxy:attempt:${string}`
   | `boxxy:hook:${string}`;
 
-export type EvidenceKind = 'pr' | 'commit' | 'test' | 'ci-run' | 'live-check';
+// A proven caller: who runs an attempt's session, or who sent a request. The core compares two
+// of these for equality, on both fields, and reads nothing else from them.
+export interface CallerIdentity {
+  readonly issuer: string;
+  readonly subject: string;
+}
+
+export type EvidenceKind = 'pull_request' | 'commit' | 'test' | 'ci-run' | 'live-check';
 
 export interface Criterion {
   readonly id: CriterionId;
@@ -85,6 +100,20 @@ export interface Criterion {
   readonly evidence: readonly FactId[];
 }
 
+export type DesignMode = 'agent' | 'attended';
+
+// How dispatch reads an attempt's session. Only design gives 'attended' in v1.
+export type SessionMode = 'agent' | 'attended';
+
+// v1 writes `claude_code` only. The second value keeps the telemetry tables' other product.
+export type Product = 'claude_code' | 'codex';
+
+// The fields of an item that a filter reads. The one v1 field is the design mode, and an item
+// that sets none runs in agent mode.
+export interface ItemFields {
+  readonly designMode?: DesignMode;
+}
+
 export interface ItemRow {
   readonly id: ItemId;
   readonly kind: ItemKindName;
@@ -92,16 +121,48 @@ export interface ItemRow {
   readonly title: string;
   readonly outcome: string;
   readonly acceptance: readonly Criterion[];
+  readonly fields: ItemFields;
+
+  // free short strings: `item.file` sets them, and `item.edit` replaces the whole list
+  readonly labels: readonly string[];
   readonly foundInAttempt: AttemptId | null;
   readonly filedBy: ActorRef;
   readonly filedAt: Instant;
   readonly closedAt: Instant | null;
   readonly closeReason: string | null;
+
+  // state of the item between two attempts, which no fact carries
+  readonly keptSession: KeptSession | null;
+}
+
+export interface KeptSession {
+  readonly atcSession: AtcSessionId;
+
+  // the worker target the session runs on, as `SpawnRequest.target` has it
+  readonly target: string;
+  readonly attempt: AttemptId;
+  readonly keptAt: Instant;
+  readonly caller: CallerIdentity | null;
+}
+
+// Append-only: no procedure edits or removes a note.
+export interface NoteRow {
+  readonly item: ItemId;
+
+  // 1, 2, 3… per item
+  readonly seq: number;
+  readonly text: string;
+  readonly by: ActorRef;
+  readonly at: Instant;
 }
 
 export type ItemState = 'idea' | 'ready' | 'running' | 'blocked' | 'waiting' | 'done' | 'archived';
 
-export type WaitingReason = 'PR open' | 'no PR linked' | 'attempts used up';
+export type WaitingReason =
+  | 'pull request open'
+  | 'no pull request linked'
+  | 'pull request closed unmerged'
+  | HoldReason;
 
 export type DerivedState =
   | { readonly state: Exclude<ItemState, 'waiting'> }
@@ -109,43 +170,13 @@ export type DerivedState =
 
 export interface ItemView extends ItemRow {
   readonly derived: DerivedState;
+  readonly position: Position;
 }
 
-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 {
+export interface RelationRow {
   readonly source: ItemId;
   readonly target: ItemId;
-  readonly type: LinkTypeName;
+  readonly type: RelationTypeName;
   readonly addedBy: ActorRef;
   readonly addedAt: Instant;
   readonly removedAt: Instant | null;
@@ -158,17 +189,53 @@ export interface LeverRow {
   readonly until: Instant | null;
   readonly expiresAt: Instant | null;
   readonly reason: string | null;
+
+  // only `item.retry --phase` sets it
+  readonly phase: PhaseName | 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 type AttemptState =
+  | 'starting'
+  | 'running'
+  | 'reconciling'
+  | 'sleeping'
+  | 'waking'
+  | 'closing'
+  | 'succeeded'
+  | 'failed';
+
+export type LiveAttemptState = Exclude<AttemptState, 'succeeded' | 'failed'>;
+
+export type ClosingCause =
+  | 'closed-out'
+  | 'timed-out'
+  | 'item-closed'
+  | 'stalled'
+  | 'skill-missing'
+  | 'turn-ended'
+  | 'usage-limit';
+
+export type ForcedFailure =
+  | 'spawn-refused'
+  | 'no-capacity'
+  | 'spawn-lost'
+  | 'session-lost'
+  | 'resume-lost'
+  | 'timed-out'
+  | 'item-closed'
+  | 'skill-missing'
+  | 'stalled'
+  | 'usage-limit';
+
+export type KnownFailure = ForcedFailure | 'closeout-missing' | 'closeout-unsettleable';
+
+// The engine's own outcomes. No phase kind may list either name.
+export type EngineOutcome = 'lost' | 'unsettleable';
+
+// each field holds a list of values, never one string
+export type FieldValues = Readonly<Record<string, readonly string[]>>;
 
 export interface AttemptRow {
   readonly id: AttemptId;
@@ -179,24 +246,53 @@ export interface AttemptRow {
   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;
+
+  // null: the worker gave no caller, and every session and hook call for the attempt is refused
+  readonly caller: CallerIdentity | null;
   readonly claimedAt: Instant;
   readonly startedAt: Instant | null;
   readonly endedAt: Instant | null;
+
+  // what `decide` saw; a wake and a rules reload match limits against these
+  readonly fields: FieldValues;
+  readonly mode: SessionMode;
+  readonly round: number;
+  readonly input: JsonValue;
+
+  // 1 at the claim, one higher on each wake; every held seat carries it
+  readonly holdGen: number;
+
+  // the first valid close-out, never replaced
+  readonly closeOut: CloseOut | null;
+  readonly closeOutHash: ContentHash | null;
+  readonly closeOutFact: FactId | null;
+  readonly closing: ClosingCause | null;
+  readonly closingAt: Instant | null;
+  readonly suspendRequestedAt: Instant | null;
+  readonly sleptAt: Instant | null;
+  readonly wakeRequestedAt: Instant | null;
+  readonly wokenAt: Instant | null;
+  readonly outcome: OutcomeName | EngineOutcome | null;
+
+  // what the phase code returned, for an attempt settled as `closeout-unsettleable`
+  readonly returnedOutcome: string | null;
+  readonly strayedAt: Instant | null;
+  readonly sessionStoppedAt: Instant | null;
+  readonly sessionForgottenAt: Instant | null;
 }
 
 export interface AttemptSessionRow {
   readonly attempt: AttemptId;
   readonly agentSession: AgentSessionId;
   readonly atcSession: AtcSessionId;
+  readonly product: Product;
+  readonly source: 'worker' | 'hook';
   readonly seenAt: Instant;
 }
 
@@ -209,12 +305,16 @@ export interface LeaseRow {
   readonly releasedAt: Instant | null;
 }
 
-export interface PoolSlotRow {
-  readonly pool: PoolName;
-  readonly slot: number;
-  readonly holder: AttemptId | null;
-  readonly gen: number;
-  readonly retired: boolean;
+// A limit's count is its rows with no `releasedAt`.
+export interface LimitSeatRow {
+  readonly limit: LimitName;
+  readonly attempt: AttemptId;
+  readonly holdGen: number;
+
+  // taken past the limit's `max`, by a wake over the cap
+  readonly overCap: boolean;
+  readonly takenAt: Instant;
+  readonly releasedAt: Instant | null;
 }
 
 export interface ObservationBoundary {
@@ -222,21 +322,32 @@ export interface ObservationBoundary {
   readonly pepysOffsets: Readonly<Record<StreamName, number>>;
 }
 
+// A limit's count and `max` at the moment of a pick.
+export interface LimitCount {
+  readonly limit: LimitName;
+  readonly held: number;
+  readonly max: number;
+}
+
 export interface DecisionRow {
   readonly id: DecisionId;
   readonly attempt: AttemptId;
   readonly item: ItemId;
+  readonly kind: 'start' | 'wake';
   readonly pool: PoolName;
   readonly rulesVersion: RulesVersion;
   readonly snapshotHash: SnapshotHash;
   readonly storeVersion: number;
   readonly pepysOffsets: ObservationBoundary['pepysOffsets'];
   readonly faults: readonly FaultRecord[];
+
+  // each limit that counts the pick, with its count before the seat was taken
+  readonly limits: readonly LimitCount[];
   readonly at: Instant;
 }
 
 export interface FaultRecord {
-  // the signal, gate, waiver or filter field name, or `propagation:<signal>:<link>`
+  // the signal, gate, waiver or filter field name, or `propagation:<signal>:<relation>`
   readonly plugin: string;
   readonly kind: 'signal' | 'gate' | 'waiver' | 'admission' | 'propagation' | 'filter-field';
   readonly item: ItemId | null;
@@ -259,6 +370,10 @@ export interface PullRequestRow {
   readonly repo: RepoName;
   readonly number: number;
   readonly attempt: AttemptId;
+
+  // GitHub's own `id` of the pull request, which pepys builds its entity ID from
+  readonly githubId: number;
+  readonly url: string;
   readonly state: 'open' | 'closed' | 'merged';
   readonly mergedAt: Instant | null;
   readonly mergeCommit: CommitSha | null;
@@ -271,6 +386,16 @@ export interface RunnerRow {
   readonly paused: boolean;
 }
 
+// A hold notice for the `Notifier` port. The tick tries it again until `tries` reaches 5.
+export interface NoticeRow {
+  readonly id: number;
+  readonly item: ItemId;
+  readonly reason: HoldReason;
+  readonly at: Instant;
+  readonly tries: number;
+  readonly sentAt: Instant | null;
+}
+
 export type Effort = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 
 export interface Recipe {
@@ -281,19 +406,18 @@ export interface Recipe {
   // the prompt template's path in the rules checkout
   readonly prompt: string;
   readonly source: SourceName;
+
+  // the skills the phase needs; the recipe hash covers the list and the rules' pin
+  readonly skills: readonly string[];
 }
 
 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/dist/actor-ref-schema.d.ts

@@ -1,2 +0,0 @@
-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/build-applied-change.d.ts

@@ -1,13 +0,0 @@
-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

@@ -1,3 +0,0 @@
-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

@@ -1,2 +0,0 @@
-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

@@ -1,3 +0,0 @@
-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

@@ -1,3 +0,0 @@
-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

@@ -1,3 +0,0 @@
-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

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

package/dist/fact-schemas.d.ts

@@ -1,5 +0,0 @@
-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

@@ -1,5 +0,0 @@
-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/friction-schema.d.ts

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

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

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

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

@@ -1,2 +0,0 @@
-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

@@ -1,2 +0,0 @@
-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

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

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

@@ -1,2 +0,0 @@
-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

@@ -1,2 +0,0 @@
-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

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

package/dist/types/dispatch.d.ts

@@ -1,82 +0,0 @@
-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>;
-}