@boxxy/model 0.1.1 → 0.1.3

package/src/test-utils/create-fake-pepys-reader.ts

@@ -0,0 +1,73 @@
+import type { PepysAnswer, PepysReader } from '../ports/types.ts';
+import { stageSteps } from '../reports/constants.ts';
+import type { CostToLand, StageTime } from '../reports/types.ts';
+import type { ItemId } from '../types.ts';
+
+interface FakeValues {
+  readonly cost?: CostToLand;
+  readonly stageTime?: StageTime;
+}
+
+export interface FakePepysReader extends PepysReader {
+  // an item with no value set answers as pepys does for an item it holds no fact of
+  set: (item: ItemId, values: FakeValues) => void;
+
+  // the next call, of either method, answers `unavailable` with this reason; each call of
+  // `failNext` fails one more call
+  failNext: (reason: string) => void;
+}
+
+export function createFakePepysReader(environment = 'production'): FakePepysReader {
+  const costs = new Map<ItemId, CostToLand>();
+  const stageTimes = new Map<ItemId, StageTime>();
+
+  const failures: string[] = [];
+
+  const answer = <Value>(value: Value): Promise<PepysAnswer<Value>> => {
+    const reason = failures.shift();
+
+    const answered: PepysAnswer<Value> =
+      reason === undefined ? { kind: 'value', value } : { kind: 'unavailable', reason };
+
+    return Promise.resolve(answered);
+  };
+
+  return {
+    set: (item, values) => {
+      if (values.cost !== undefined) {
+        costs.set(item, values.cost);
+      }
+
+      if (values.stageTime !== undefined) {
+        stageTimes.set(item, values.stageTime);
+      }
+    },
+    failNext: (reason) => {
+      failures.push(reason);
+    },
+    readCostToLand: (item) => answer(costs.get(item) ?? buildEmptyCost(item)),
+    readStageTime: (item) => answer(stageTimes.get(item) ?? buildEmptyStageTime(item, environment)),
+  };
+}
+
+function buildEmptyCost(item: ItemId): CostToLand {
+  return {
+    item: `boxxy:item:${item}`,
+    landedAt: null,
+    attempts: 0,
+    lines: [],
+    totals: { requests: 0, costUSD: 0, reworkCostUSD: 0, requestsWithoutCost: 0 },
+  };
+}
+
+function buildEmptyStageTime(item: ItemId, environment: string): StageTime {
+  return {
+    item: `boxxy:item:${item}`,
+    environment,
+    steps: stageSteps.map((step) => ({ step, minutes: null, endedAt: null })),
+    rework: { count: 0, minutes: 0 },
+    reviewWaitMinutes: null,
+    sleepMinutes: 0,
+    pullRequests: [],
+  };
+}

package/src/test-utils/fact-sink-contract.ts

@@ -0,0 +1,103 @@
+import type { FactId, FactSink, OutboxFact } from '@boxxy/model';
+import { buildMockOutboxFact } from '@boxxy/model/test-utils/build-mock-outbox-fact';
+
+export interface FactSinkHarness {
+  readonly sink: FactSink;
+
+  // the fact IDs the log holds, in the order they arrived, a copy of an ID counted once
+  readStored: () => Promise<readonly FactId[]>;
+
+  // the same fact, changed so that the sink refuses a batch that holds it
+  corrupt: (fact: OutboxFact) => OutboxFact;
+}
+
+export type FactSinkCase = readonly [
+  title: string,
+  check: (harness: FactSinkHarness) => Promise<{ received: unknown; expected: unknown }>,
+];
+
+// The cases that every adapter of the sink port must pass: the fake, and the pepys adapter behind
+// ingest's route handler. Each case gets a harness with an empty log.
+export const factSinkContract: readonly FactSinkCase[] = [
+  [
+    'a batch is stored whole and in order',
+    async (harness) => {
+      const batch = buildFacts(3, 1);
+
+      const answer = await harness.sink.send(batch);
+
+      return {
+        received: { answer, stored: await harness.readStored() },
+        expected: { answer: { kind: 'stored' }, stored: batch.map((fact) => fact.factId) },
+      };
+    },
+  ],
+  [
+    'the same batch sent twice is stored as one copy of each fact',
+    async (harness) => {
+      const batch = buildFacts(2, 1);
+
+      await harness.sink.send(batch);
+
+      const answer = await harness.sink.send(batch);
+
+      return {
+        received: { answer, stored: await harness.readStored() },
+        expected: { answer: { kind: 'stored' }, stored: batch.map((fact) => fact.factId) },
+      };
+    },
+  ],
+  [
+    'two batches sent one after the other keep their order',
+    async (harness) => {
+      const first = buildFacts(2, 1);
+      const second = buildFacts(2, 3);
+
+      await harness.sink.send(first);
+      await harness.sink.send(second);
+
+      return {
+        received: await harness.readStored(),
+        expected: [...first, ...second].map((fact) => fact.factId),
+      };
+    },
+  ],
+  [
+    'a batch with a bad fact is refused whole and stores none of it',
+    async (harness) => {
+      const [good, bad] = buildPair();
+
+      const answer = await harness.sink.send([good, harness.corrupt(bad)]);
+
+      return {
+        received: { kind: answer.kind, stored: await harness.readStored() },
+        expected: { kind: 'refused-batch', stored: [] },
+      };
+    },
+  ],
+  [
+    'a good batch is stored after a bad one was refused',
+    async (harness) => {
+      const [good, bad] = buildPair();
+
+      await harness.sink.send([good, harness.corrupt(bad)]);
+
+      const answer = await harness.sink.send([good]);
+
+      return {
+        received: { answer, stored: await harness.readStored() },
+        expected: { answer: { kind: 'stored' }, stored: [good.factId] },
+      };
+    },
+  ],
+];
+
+function buildFacts(count: number, firstSeq: number): OutboxFact[] {
+  return Array.from({ length: count }, (_unused, index) =>
+    buildMockOutboxFact({ seq: firstSeq + index }),
+  );
+}
+
+function buildPair(): [OutboxFact, OutboxFact] {
+  return [buildMockOutboxFact({ seq: 1 }), buildMockOutboxFact({ seq: 2 })];
+}

package/src/test-utils/pepys-reader-contract.ts

@@ -0,0 +1,117 @@
+import { faker } from '@faker-js/faker';
+import type { PepysReader } from '../ports/types.ts';
+import type { CostToLand } from '../reports/types.ts';
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import type { ItemId } from '../types.ts';
+import { buildMockCostToLand } from './build-mock-cost-to-land.ts';
+
+export interface PepysReaderHarness {
+  readonly reader: PepysReader;
+
+  // the environment the reader passes to the stage times
+  readonly environment: string;
+
+  // pepys holds this cost for the item
+  writeCost: (item: ItemId, cost: CostToLand) => Promise<void>;
+
+  // every later call finds pepys down
+  takeDown: () => Promise<void>;
+}
+
+export type PepysReaderCase = readonly [
+  title: string,
+  check: (harness: PepysReaderHarness) => Promise<{ received: unknown; expected: unknown }>,
+];
+
+// The cases that every adapter of the reader port must pass: the fake, and the pepys adapter
+// behind the plug-in's queries. Each case gets a harness with an empty pepys.
+export const pepysReaderContract: readonly PepysReaderCase[] = [
+  [
+    'an item that pepys holds no fact of gives the empty cost, not unavailable',
+    async (harness) => {
+      const item = buildItemId();
+
+      return {
+        received: await harness.reader.readCostToLand(item),
+        expected: {
+          kind: 'value',
+          value: {
+            item: `boxxy:item:${item}`,
+            landedAt: null,
+            attempts: 0,
+            lines: [],
+            totals: { requests: 0, costUSD: 0, reworkCostUSD: 0, requestsWithoutCost: 0 },
+          },
+        },
+      };
+    },
+  ],
+  [
+    'an item that pepys holds no fact of gives seven steps with null minutes',
+    async (harness) => {
+      const item = buildItemId();
+      const empty = { minutes: null, endedAt: null };
+
+      return {
+        received: await harness.reader.readStageTime(item),
+        expected: {
+          kind: 'value',
+          value: {
+            item: `boxxy:item:${item}`,
+            environment: harness.environment,
+            steps: [
+              { step: 'triage', ...empty },
+              { step: 'design', ...empty },
+              { step: 'build', ...empty },
+              { step: 'review', ...empty },
+              { step: 'merge', ...empty },
+              { step: 'release', ...empty },
+              { step: 'deploy', ...empty },
+            ],
+            rework: { count: 0, minutes: 0 },
+            reviewWaitMinutes: null,
+            sleepMinutes: 0,
+            pullRequests: [],
+          },
+        },
+      };
+    },
+  ],
+  [
+    'a cost that pepys holds comes back whole',
+    async (harness) => {
+      const item = buildItemId();
+      const cost = buildMockCostToLand({ item: `boxxy:item:${item}` });
+
+      await harness.writeCost(item, cost);
+
+      return {
+        received: await harness.reader.readCostToLand(item),
+        expected: { kind: 'value', value: cost },
+      };
+    },
+  ],
+  [
+    'a pepys that is down gives unavailable with a reason for both reads',
+    async (harness) => {
+      const item = buildItemId();
+
+      await harness.takeDown();
+
+      return {
+        received: [
+          await harness.reader.readCostToLand(item),
+          await harness.reader.readStageTime(item),
+        ].map((answer) => ({ kind: answer.kind, hasReason: 'reason' in answer })),
+        expected: [
+          { kind: 'unavailable', hasReason: true },
+          { kind: 'unavailable', hasReason: true },
+        ],
+      };
+    },
+  ],
+];
+
+function buildItemId(): ItemId {
+  return brandSchemas.itemId.parse(faker.string.uuid({ version: 7 }));
+}

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,31 +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;
-}
-
-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;
@@ -146,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;
@@ -167,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;
 }
 
@@ -197,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 {
@@ -210,23 +322,34 @@ 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 or waiver 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';
+  readonly kind: 'signal' | 'gate' | 'waiver' | 'admission' | 'propagation' | 'filter-field';
   readonly item: ItemId | null;
   readonly error: string;
 }
@@ -247,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;
@@ -259,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 {
@@ -269,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;
 }