@boxxy/model 0.1.1 → 0.1.3

package/dist/{types/core.d.ts → types.d.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]>;
 export type Instant = BrandOf<'instant'>;
 export type Minutes = number;
@@ -20,10 +21,11 @@ export interface PullRequestRef {
     readonly number: number;
 }
 export type ItemKindName = BrandOf<'itemKindName'>;
-export type LinkTypeName = BrandOf<'linkTypeName'>;
+export type RelationTypeName = BrandOf<'relationTypeName'>;
 export type PhaseName = BrandOf<'phaseName'>;
 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'>;
 export type SourceName = BrandOf<'sourceName'>;
@@ -32,6 +34,7 @@ export type LeverKind = `${string}.${string}`;
 export type RecipeHash = BrandOf<'recipeHash'>;
 export type SnapshotHash = BrandOf<'snapshotHash'>;
 export type RulesVersion = BrandOf<'rulesVersion'>;
+export type OutcomeName = BrandOf<'outcomeName'>;
 export interface ConceptPin {
     readonly ref: `${string}@${number}`;
     readonly sourceHash: ContentHash;
@@ -49,12 +52,22 @@ export type Actor = {
     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 CallerIdentity {
+    readonly issuer: string;
+    readonly subject: string;
+}
+export type EvidenceKind = 'pull_request' | 'commit' | 'test' | 'ci-run' | 'live-check';
 export interface Criterion {
     readonly id: CriterionId;
     readonly text: string;
     readonly evidence: readonly FactId[];
 }
+export type DesignMode = 'agent' | 'attended';
+export type SessionMode = 'agent' | 'attended';
+export type Product = 'claude_code' | 'codex';
+export interface ItemFields {
+    readonly designMode?: DesignMode;
+}
 export interface ItemRow {
     readonly id: ItemId;
     readonly kind: ItemKindName;
@@ -62,14 +75,31 @@ export interface ItemRow {
     readonly title: string;
     readonly outcome: string;
     readonly acceptance: readonly Criterion[];
+    readonly fields: ItemFields;
+    readonly labels: readonly string[];
     readonly foundInAttempt: AttemptId | null;
     readonly filedBy: ActorRef;
     readonly filedAt: Instant;
     readonly closedAt: Instant | null;
     readonly closeReason: string | null;
+    readonly keptSession: KeptSession | null;
+}
+export interface KeptSession {
+    readonly atcSession: AtcSessionId;
+    readonly target: string;
+    readonly attempt: AttemptId;
+    readonly keptAt: Instant;
+    readonly caller: CallerIdentity | null;
+}
+export interface NoteRow {
+    readonly item: ItemId;
+    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'>;
 } | {
@@ -78,24 +108,12 @@ export type DerivedState = {
 };
 export interface ItemView extends ItemRow {
     readonly derived: DerivedState;
+    readonly position: Position;
 }
-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 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;
@@ -107,13 +125,17 @@ export interface LeverRow {
     readonly until: Instant | null;
     readonly expiresAt: Instant | null;
     readonly reason: string | null;
+    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';
+export type EngineOutcome = 'lost' | 'unsettleable';
+export type FieldValues = Readonly<Record<string, readonly string[]>>;
 export interface AttemptRow {
     readonly id: AttemptId;
     readonly item: ItemId;
@@ -123,23 +145,42 @@ 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;
+    readonly caller: CallerIdentity | null;
     readonly claimedAt: Instant;
     readonly startedAt: Instant | null;
     readonly endedAt: Instant | null;
+    readonly fields: FieldValues;
+    readonly mode: SessionMode;
+    readonly round: number;
+    readonly input: JsonValue;
+    readonly holdGen: number;
+    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;
+    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;
 }
 export interface LeaseRow {
@@ -150,32 +191,40 @@ export interface LeaseRow {
     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 LimitSeatRow {
+    readonly limit: LimitName;
+    readonly attempt: AttemptId;
+    readonly holdGen: number;
+    readonly overCap: boolean;
+    readonly takenAt: Instant;
+    readonly releasedAt: Instant | null;
 }
 export interface ObservationBoundary {
     readonly storeVersion: number;
     readonly pepysOffsets: Readonly<Record<StreamName, number>>;
 }
+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[];
+    readonly limits: readonly LimitCount[];
     readonly at: Instant;
 }
 export interface FaultRecord {
     readonly plugin: string;
-    readonly kind: 'signal' | 'gate' | 'waiver' | 'admission' | 'propagation';
+    readonly kind: 'signal' | 'gate' | 'waiver' | 'admission' | 'propagation' | 'filter-field';
     readonly item: ItemId | null;
     readonly error: string;
 }
@@ -193,6 +242,8 @@ export interface PullRequestRow {
     readonly repo: RepoName;
     readonly number: number;
     readonly attempt: AttemptId;
+    readonly githubId: number;
+    readonly url: string;
     readonly state: 'open' | 'closed' | 'merged';
     readonly mergedAt: Instant | null;
     readonly mergeCommit: CommitSha | null;
@@ -203,6 +254,14 @@ export interface RunnerRow {
     readonly heartbeatAt: Instant;
     readonly paused: boolean;
 }
+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 {
     readonly agent: string;
@@ -210,15 +269,14 @@ export interface Recipe {
     readonly effort: Effort;
     readonly prompt: string;
     readonly source: SourceName;
+    readonly skills: readonly string[];
 }
 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;
 }

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

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boxxy/model",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "The types that boxxy's packages share",
   "homepage": "https://github.com/zgeoff/boxxy/tree/main/libs/model#readme",
   "bugs": "https://github.com/zgeoff/boxxy/issues",
@@ -31,10 +31,21 @@
     "typecheck": "tsrs --noEmit"
   },
   "dependencies": {
-    "@boxxy/content-hash": "0.1.0",
-    "@faker-js/faker": "10.6.0",
+    "@boxxy/content-hash": "0.1.3",
+    "tiny-invariant": "1.3.3",
     "zod": "4.6.7"
   },
+  "devDependencies": {
+    "@faker-js/faker": "10.6.0"
+  },
+  "peerDependencies": {
+    "@faker-js/faker": "10.6.0"
+  },
+  "peerDependenciesMeta": {
+    "@faker-js/faker": {
+      "optional": true
+    }
+  },
   "engines": {
     "bun": ">=1.3",
     "node": ">=24"

package/src/{build-close-out-schema.ts → closeouts/build-close-out-schema.ts}

@@ -1,7 +1,8 @@
 import { z } from 'zod';
-import { brandSchemas } from './brand-schemas.ts';
+import { brandSchemas } from '../rows/brand-schemas.ts';
 import { frictionSchema } from './friction-schema.ts';
-import type { BuildCloseOut } from './types/facts.ts';
+import { openItemSchema } from './open-item-schema.ts';
+import type { BuildCloseOut } from './types.ts';
 
 const reasonSchema = z.string().min(1);
 const builtSchema = z.object({ kind: z.literal('built') });
@@ -13,16 +14,10 @@ const citedEvidenceSchema = z.object({
   evidence: brandSchemas.factId,
 });
 
-const openItemSchema = z.object({
-  kind: z.literal('core.issue'),
-  title: z.string().min(1),
-  body: z.string(),
-});
-
-export const buildCloseOutSchema: z.ZodType<BuildCloseOut> = z.object({
+export const buildCloseOutSchema = z.strictObject({
   result: z.discriminatedUnion('kind', [builtSchema, blockedSchema, abandonedSchema]),
   criteria: z.array(citedEvidenceSchema),
   openItems: z.array(openItemSchema),
   friction: z.array(frictionSchema),
   frictionDropped: z.number().int().nonnegative(),
-});
+}) satisfies z.ZodType<BuildCloseOut>;

package/src/closeouts/close-out-answer-schema.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import type { CloseOutAnswer, CloseOutProblem } from './types.ts';
+
+const closeOutProblemSchema: z.ZodType<CloseOutProblem> = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('schema'), path: z.string(), message: z.string() }),
+  z.object({ kind: z.literal('unknown-criterion'), criterion: brandSchemas.criterionId }),
+  z.object({ kind: z.literal('foreign-evidence'), evidence: brandSchemas.factId }),
+  z.object({
+    kind: z.literal('built-without-evidence'),
+    criteria: z.array(brandSchemas.criterionId),
+  }),
+  z.object({ kind: z.literal('no-acceptance') }),
+  z.object({ kind: z.literal('unknown-item'), item: z.string() }),
+  z.object({ kind: z.literal('unknown-kind'), itemKind: z.string() }),
+  z.object({
+    kind: z.literal('refused-relation'),
+    type: z.string(),
+    target: z.string(),
+    reason: z.enum(['unknown-type', 'self']),
+  }),
+  z.object({ kind: z.literal('phase-rule'), message: z.string() }),
+  z.object({
+    kind: z.literal('too-large'),
+    bytes: z.number().int().nonnegative(),
+    max: z.number().int().nonnegative(),
+  }),
+]);
+
+export const closeOutAnswerSchema: z.ZodType<CloseOutAnswer> = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal('recorded'),
+    attempt: brandSchemas.attemptId,
+    factId: brandSchemas.factId,
+    repeat: z.boolean(),
+  }),
+  z.object({ kind: z.literal('rejected'), problems: z.array(closeOutProblemSchema) }),
+  z.object({
+    kind: z.literal('refused'),
+    reason: z.enum(['no-attempt', 'already-closed-out', 'not-current']),
+  }),
+]);

package/src/closeouts/close-out-schema.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import { buildCloseOutSchema } from './build-close-out-schema.ts';
+import { designCloseOutSchema } from './design-close-out-schema.ts';
+import { reviewCloseOutSchema } from './review-close-out-schema.ts';
+import { triageCloseOutSchema } from './triage-close-out-schema.ts';
+import type { CloseOut } from './types.ts';
+
+export const closeOutSchema: z.ZodType<CloseOut> = z.union([
+  reviewCloseOutSchema,
+  triageCloseOutSchema,
+  buildCloseOutSchema,
+  designCloseOutSchema,
+]);

package/src/closeouts/design-close-out-schema.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { frictionSchema } from './friction-schema.ts';
+import type { DesignCloseOut } from './types.ts';
+
+const reasonSchema = z.string().min(1);
+
+const designRefSchema = z.object({
+  summary: z.string().min(1),
+  location: z.string().min(1).nullable(),
+});
+
+const designedSchema = z.object({ kind: z.literal('designed'), design: designRefSchema });
+const blockedSchema = z.object({ kind: z.literal('blocked'), reason: reasonSchema });
+const abandonedSchema = z.object({ kind: z.literal('abandoned'), reason: reasonSchema });
+
+export const designCloseOutSchema = z.strictObject({
+  result: z.discriminatedUnion('kind', [designedSchema, blockedSchema, abandonedSchema]),
+  friction: z.array(frictionSchema),
+  frictionDropped: z.number().int().nonnegative(),
+}) satisfies z.ZodType<DesignCloseOut>;

package/src/closeouts/friction-schema.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import type { Friction } from './types.ts';
+
+// A plain object, so that the fact schema of `boxxy.proposal.recorded` can extend it.
+export const frictionSchema = z.object({
+  target: z.object({
+    kind: z.enum(['skill', 'rule', 'lint', 'agents-md', 'tool']),
+    name: z.string().min(1),
+  }),
+  change: z.string().min(1),
+}) satisfies z.ZodType<Friction>;

package/src/closeouts/open-item-schema.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import type { OpenItem } from './types.ts';
+
+export const openItemSchema: z.ZodType<OpenItem> = z.object({
+  kind: z.literal('core.issue'),
+  title: z.string().min(1),
+  body: z.string(),
+});

package/src/closeouts/review-close-out-schema.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import { frictionSchema } from './friction-schema.ts';
+import type { ReviewCloseOut } from './types.ts';
+
+const countSchema = z.number().int().nonnegative();
+
+const findingSchema = z.object({
+  title: z.string().min(1),
+  body: z.string(),
+  path: z.string().min(1).exactOptional(),
+  line: z.number().int().positive().exactOptional(),
+});
+
+const passedSchema = z.object({ kind: z.literal('passed') });
+
+const changesRequestedSchema = z.object({
+  kind: z.literal('changes-requested'),
+  findings: z.array(findingSchema),
+});
+
+const noslopSummarySchema = z.object({
+  version: z.number().int().positive(),
+  reviewID: z.string().min(1),
+  head: brandSchemas.commitSha,
+  counts: z.object({ findings: countSchema, failedCalls: countSchema, fixChecks: countSchema }),
+  reportBytes: countSchema,
+  report: z.json().nullable(),
+});
+
+// The stored form. The parser of the review phase reads noslop's whole result and builds the
+// summary, so this schema never sees the raw result.
+export const reviewCloseOutSchema = z.strictObject({
+  verdict: z.discriminatedUnion('kind', [passedSchema, changesRequestedSchema]),
+  noslop: noslopSummarySchema,
+  friction: z.array(frictionSchema),
+  frictionDropped: countSchema,
+}) satisfies z.ZodType<ReviewCloseOut>;

package/src/closeouts/triage-close-out-schema.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import { frictionSchema } from './friction-schema.ts';
+import type { TriageCloseOut } from './types.ts';
+
+const acceptedSchema = z.object({ kind: z.literal('accepted') });
+const duplicateSchema = z.object({ kind: z.literal('duplicate'), of: brandSchemas.itemId });
+const declinedSchema = z.object({ kind: z.literal('declined'), reason: z.string().min(1) });
+const designModeSchema = z.enum(['agent', 'attended']);
+const criterionTextSchema = z.object({ text: z.string().min(1) });
+
+const setSchema = z.strictObject({
+  kind: brandSchemas.itemKindName.exactOptional(),
+  designMode: designModeSchema.exactOptional(),
+  acceptance: z.array(criterionTextSchema).exactOptional(),
+});
+
+const relationDraftSchema = z.object({
+  type: brandSchemas.relationTypeName,
+  target: brandSchemas.itemId,
+});
+
+export const triageCloseOutSchema = z.strictObject({
+  result: z.discriminatedUnion('kind', [acceptedSchema, duplicateSchema, declinedSchema]),
+  set: setSchema.exactOptional(),
+  relations: z.array(relationDraftSchema),
+  friction: z.array(frictionSchema),
+  frictionDropped: z.number().int().nonnegative(),
+}) satisfies z.ZodType<TriageCloseOut>;