@boxxy/model 0.1.2 → 0.1.3

package/src/facts/types.ts

@@ -0,0 +1,235 @@
+import type { ContentHash, JsonValue } from '@boxxy/content-hash';
+import type { CloseOut, Effect, Friction } from '../closeouts/types.ts';
+import type { SeatRef } from '../planning/types.ts';
+import type { WakeSource } from '../ports/types.ts';
+import type {
+  ActorRef,
+  AgentSessionId,
+  AtcSessionId,
+  AttemptId,
+  CallerIdentity,
+  ClosingCause,
+  CommitSha,
+  Criterion,
+  CriterionId,
+  DecisionRow,
+  DesignMode,
+  EvidenceKind,
+  FactId,
+  FieldValues,
+  Instant,
+  ItemId,
+  ItemKindName,
+  ItemRow,
+  LeverRow,
+  Minutes,
+  PhaseName,
+  PoolName,
+  Product,
+  RecipeHash,
+  RelationTypeName,
+  RepoName,
+  RulesVersion,
+  SessionMode,
+} from '../types.ts';
+
+// Every fact on the stream names an item; a fact about an attempt names the attempt in its
+// payload. The consumer rebuilds an item from the one scope of the item.
+export type EntityRef = `boxxy:item:${string}`;
+
+export interface FactEnvelope<M extends object, 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 FactType> {
+  readonly id: FactId;
+  readonly type: T;
+  readonly entity: EntityRef;
+  readonly actor: ActorRef;
+  readonly payload: WorkFacts[T];
+}
+
+export type AnyNewFact = { [T in FactType]: NewFact<T> }[FactType];
+
+export interface OutboxFact {
+  readonly seq: number;
+  readonly factId: FactId;
+  readonly type: FactType;
+  readonly entity: EntityRef;
+  readonly actor: ActorRef;
+  readonly at: Instant;
+  readonly payload: JsonValue;
+  readonly sentAt: Instant | null;
+
+  // when the sender gave the row up, and why: `too-large`, `unknown-type` or the sink's refusal
+  readonly parkedAt: Instant | null;
+  readonly parkedReason: string | null;
+}
+
+export type FactType = keyof WorkFacts;
+
+export interface RelationPayload {
+  readonly source: ItemId;
+  readonly target: ItemId;
+  readonly type: RelationTypeName;
+}
+
+interface OfAttempt {
+  readonly attempt: AttemptId;
+}
+
+// The fact catalog of the stream `facts.boxxy.work`. A payload holds no `storeVersion`: the sink
+// adds it to the wire form. Instants in a payload are epoch milliseconds.
+export interface WorkFacts {
+  // the kept session is state between two attempts, and no fact carries it
+  'boxxy.item.filed': Omit<ItemRow, 'keptSession'>;
+  'boxxy.item.noted': { readonly seq: number; readonly text: string };
+  'boxxy.item.edited': {
+    readonly title?: string;
+    readonly outcome?: string;
+    readonly acceptance?: readonly Criterion[];
+    readonly kind?: ItemKindName;
+    readonly fields?: { readonly designMode?: DesignMode };
+
+    // the whole new list
+    readonly labels?: readonly string[];
+
+    // the attempt whose settle made the edit
+    readonly byAttempt: AttemptId | null;
+  };
+  'boxxy.item.closed': {
+    readonly reason: string;
+    readonly byAttempt: AttemptId | null;
+    readonly ended: readonly {
+      readonly attempt: AttemptId;
+      readonly how: 'settled' | 'closing';
+    }[];
+  };
+
+  // the entity is the source item
+  'boxxy.relation.added': RelationPayload;
+  'boxxy.relation.removed': RelationPayload;
+  'boxxy.lever.recorded': LeverRow;
+  'boxxy.attempt.claimed': OfAttempt & {
+    readonly phase: PhaseName;
+    readonly number: number;
+    readonly round: number;
+    readonly mode: SessionMode;
+    readonly pool: PoolName;
+    readonly fields: FieldValues;
+    readonly seats: readonly SeatRef[];
+    readonly recipeHash: RecipeHash;
+
+    // the skills pin of the rules at the claim
+    readonly skillsRef: CommitSha | null;
+    readonly rulesVersion: RulesVersion;
+  };
+  'boxxy.decision.recorded': DecisionRow;
+  'boxxy.attempt.started': OfAttempt & {
+    readonly atcSession: AtcSessionId;
+    readonly resumeFallback: boolean;
+    readonly caller: CallerIdentity | null;
+  };
+  'boxxy.attempt.spawn_unanswered': OfAttempt & { readonly reason: string };
+  'boxxy.attempt.reconciled': OfAttempt & {
+    readonly atcSession: AtcSessionId;
+    readonly caller: CallerIdentity | null;
+  };
+  'boxxy.attempt.session_bound': OfAttempt & {
+    readonly atcSession: AtcSessionId;
+    readonly agentSession: AgentSessionId;
+    readonly product: Product;
+    readonly source: 'worker' | 'hook';
+    readonly seenAt: Instant;
+  };
+  'boxxy.attempt.slept': OfAttempt & { readonly idleSince: Instant; readonly asked: boolean };
+  'boxxy.attempt.wake_requested': OfAttempt & { readonly by: WakeSource };
+  'boxxy.attempt.woken': OfAttempt & {
+    readonly holdGen: number;
+    readonly seats: readonly SeatRef[];
+    readonly overCap: boolean;
+  };
+  'boxxy.attempt.resumed': OfAttempt & {
+    readonly atcSession: AtcSessionId;
+    readonly caller: CallerIdentity | null;
+  };
+  'boxxy.attempt.closed_out': OfAttempt & {
+    readonly phase: PhaseName;
+    readonly closeOut: CloseOut;
+    readonly hash: ContentHash;
+  };
+  'boxxy.attempt.timed_out': OfAttempt & {
+    readonly phase: PhaseName;
+    readonly afterMinutes: Minutes;
+  };
+  'boxxy.attempt.turn_ended': OfAttempt & { readonly phase: PhaseName };
+  'boxxy.attempt.settled': OfAttempt & {
+    readonly phase: PhaseName;
+    readonly round: number;
+    readonly state: 'succeeded' | 'failed';
+    readonly failure: string | null;
+
+    // a name the phase kind lists, or an engine outcome
+    readonly outcome: string;
+    readonly returnedOutcome: string | null;
+
+    // null: the session was already gone
+    readonly closing: ClosingCause | null;
+    readonly asleep: boolean;
+
+    // false: settled by the give-up rule
+    readonly sessionStopped: boolean;
+    readonly endedAt: Instant;
+    readonly criteria: readonly {
+      readonly criterion: CriterionId;
+      readonly evidence: readonly FactId[];
+    }[];
+    readonly matched: readonly ItemId[];
+    readonly frictionDropped: number;
+    readonly skippedEffects: readonly {
+      readonly effect: Effect['kind'];
+      readonly reason: string;
+    }[];
+  };
+  'boxxy.proposal.recorded': OfAttempt & Friction;
+  'boxxy.evidence.recorded': OfAttempt & {
+    readonly kind: EvidenceKind;
+    readonly ref: string;
+    readonly observed: string | null;
+  };
+  'boxxy.pull_request.linked': OfAttempt & {
+    readonly repo: RepoName;
+    readonly number: number;
+    readonly url: string;
+
+    // the decimal text of GitHub's own ID of the pull request
+    readonly pullRequestId: string;
+    readonly source: 'hook' | 'watch';
+  };
+  'boxxy.commit.linked': OfAttempt & {
+    readonly repo: RepoName;
+    readonly sha: CommitSha;
+    readonly pullRequestNumber: number;
+  };
+  'boxxy.pull_request.merged': OfAttempt & {
+    readonly repo: RepoName;
+    readonly number: number;
+    readonly pullRequestId: string;
+    readonly mergedAt: Instant;
+    readonly mergeCommit: CommitSha;
+  };
+  'boxxy.pull_request.closed': OfAttempt & {
+    readonly repo: RepoName;
+    readonly number: number;
+    readonly pullRequestId: string;
+  };
+}

package/src/facts/work-fact-schemas.ts

@@ -0,0 +1,201 @@
+import { contentHashSchema } from '@boxxy/content-hash';
+import { z } from 'zod';
+import { closeOutSchema } from '../closeouts/close-out-schema.ts';
+import { frictionSchema } from '../closeouts/friction-schema.ts';
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import { callerIdentitySchema } from '../rows/caller-identity-schema.ts';
+import { criterionSchema } from '../rows/criterion-schema.ts';
+import { decisionRowSchema } from '../rows/decision-row-schema.ts';
+import { itemRowSchema } from '../rows/item-row-schema.ts';
+import { leverRowSchema } from '../rows/lever-row-schema.ts';
+import type { FactType, WorkFacts } from './types.ts';
+
+const countSchema = z.number().int().nonnegative();
+const roundSchema = z.number().int().positive();
+const pullRequestNumberSchema = z.number().int().positive();
+const pullRequestIdSchema = z.string().regex(/^[1-9]\d*$/u);
+const ofAttempt = { attempt: brandSchemas.attemptId };
+const seatsSchema = z.array(z.object({ limit: brandSchemas.limitName }));
+const designModeSchema = z.enum(['agent', 'attended']);
+const editedFieldsSchema = z.object({ designMode: designModeSchema.exactOptional() });
+const fieldValuesSchema = z.record(z.string(), z.array(z.string()));
+
+const relationSchema = z.object({
+  source: brandSchemas.itemId,
+  target: brandSchemas.itemId,
+  type: brandSchemas.relationTypeName,
+});
+
+const endedAttemptSchema = z.object({
+  attempt: brandSchemas.attemptId,
+  how: z.enum(['settled', 'closing']),
+});
+
+const closingCauseSchema = z.enum([
+  'closed-out',
+  'timed-out',
+  'item-closed',
+  'stalled',
+  'skill-missing',
+  'turn-ended',
+  'usage-limit',
+]);
+
+const copiedEvidenceSchema = z.object({
+  criterion: brandSchemas.criterionId,
+  evidence: z.array(brandSchemas.factId),
+});
+
+const effectKindSchema = z.enum([
+  'file-item',
+  'close-item',
+  'add-relation',
+  'set-kind',
+  'set-field',
+  'set-acceptance',
+  'record-proposal',
+]);
+
+const skippedEffectSchema = z.object({ effect: effectKindSchema, reason: z.string().min(1) });
+
+// One schema per fact type, with no `storeVersion`: the wire schema of the pepys package adds
+// it. Each schema's output equals its payload type; the test of this file checks both ways.
+export const workFactSchemas = {
+  'boxxy.item.filed': itemRowSchema.omit({ keptSession: true }),
+  'boxxy.item.noted': z.object({ seq: roundSchema, text: z.string().min(1) }),
+  'boxxy.item.edited': z.object({
+    title: z.string().min(1).exactOptional(),
+    outcome: z.string().min(1).exactOptional(),
+    acceptance: z.array(criterionSchema).exactOptional(),
+    kind: brandSchemas.itemKindName.exactOptional(),
+    fields: editedFieldsSchema.exactOptional(),
+    labels: z.array(z.string().min(1)).exactOptional(),
+    byAttempt: brandSchemas.attemptId.nullable(),
+  }),
+  'boxxy.item.closed': z.object({
+    reason: z.string().min(1),
+    byAttempt: brandSchemas.attemptId.nullable(),
+    ended: z.array(endedAttemptSchema),
+  }),
+  'boxxy.relation.added': relationSchema,
+  'boxxy.relation.removed': relationSchema,
+  'boxxy.lever.recorded': leverRowSchema,
+  'boxxy.attempt.claimed': z.object({
+    ...ofAttempt,
+    phase: brandSchemas.phaseName,
+    number: roundSchema,
+    round: roundSchema,
+    mode: designModeSchema,
+    pool: brandSchemas.poolName,
+    fields: fieldValuesSchema,
+    seats: seatsSchema,
+    recipeHash: brandSchemas.recipeHash,
+    skillsRef: brandSchemas.commitSha.nullable(),
+    rulesVersion: brandSchemas.rulesVersion,
+  }),
+  'boxxy.decision.recorded': decisionRowSchema,
+  'boxxy.attempt.started': z.object({
+    ...ofAttempt,
+    atcSession: brandSchemas.atcSessionId,
+    resumeFallback: z.boolean(),
+    caller: callerIdentitySchema.nullable(),
+  }),
+  'boxxy.attempt.spawn_unanswered': z.object({ ...ofAttempt, reason: z.string().min(1) }),
+  'boxxy.attempt.reconciled': z.object({
+    ...ofAttempt,
+    atcSession: brandSchemas.atcSessionId,
+    caller: callerIdentitySchema.nullable(),
+  }),
+  'boxxy.attempt.session_bound': z.object({
+    ...ofAttempt,
+    atcSession: brandSchemas.atcSessionId,
+    agentSession: brandSchemas.agentSessionId,
+    product: z.enum(['claude_code', 'codex']),
+    source: z.enum(['worker', 'hook']),
+    seenAt: brandSchemas.instant,
+  }),
+  'boxxy.attempt.slept': z.object({
+    ...ofAttempt,
+    idleSince: brandSchemas.instant,
+    asked: z.boolean(),
+  }),
+  'boxxy.attempt.wake_requested': z.object({
+    ...ofAttempt,
+    by: z.enum(['command', 'session-ran', 'host-slept-unasked']),
+  }),
+  'boxxy.attempt.woken': z.object({
+    ...ofAttempt,
+    holdGen: roundSchema,
+    seats: seatsSchema,
+    overCap: z.boolean(),
+  }),
+  'boxxy.attempt.resumed': z.object({
+    ...ofAttempt,
+    atcSession: brandSchemas.atcSessionId,
+    caller: callerIdentitySchema.nullable(),
+  }),
+  'boxxy.attempt.closed_out': z.object({
+    ...ofAttempt,
+    phase: brandSchemas.phaseName,
+    closeOut: closeOutSchema,
+    hash: contentHashSchema,
+  }),
+  'boxxy.attempt.timed_out': z.object({
+    ...ofAttempt,
+    phase: brandSchemas.phaseName,
+    afterMinutes: z.number().positive(),
+  }),
+  'boxxy.attempt.turn_ended': z.object({ ...ofAttempt, phase: brandSchemas.phaseName }),
+  'boxxy.attempt.settled': z.object({
+    ...ofAttempt,
+    phase: brandSchemas.phaseName,
+    round: roundSchema,
+    state: z.enum(['succeeded', 'failed']),
+    failure: z.string().min(1).nullable(),
+    outcome: z.string().min(1),
+    returnedOutcome: z.string().min(1).nullable(),
+    closing: closingCauseSchema.nullable(),
+    asleep: z.boolean(),
+    sessionStopped: z.boolean(),
+    endedAt: brandSchemas.instant,
+    criteria: z.array(copiedEvidenceSchema),
+    matched: z.array(brandSchemas.itemId),
+    frictionDropped: countSchema,
+    skippedEffects: z.array(skippedEffectSchema),
+  }),
+  'boxxy.proposal.recorded': frictionSchema.extend(ofAttempt),
+  'boxxy.evidence.recorded': z.object({
+    ...ofAttempt,
+    kind: z.enum(['pull_request', 'commit', 'test', 'ci-run', 'live-check']),
+    ref: z.string().min(1),
+    observed: z.string().nullable(),
+  }),
+  'boxxy.pull_request.linked': z.object({
+    ...ofAttempt,
+    repo: brandSchemas.repoName,
+    number: pullRequestNumberSchema,
+    url: z.url(),
+    pullRequestId: pullRequestIdSchema,
+    source: z.enum(['hook', 'watch']),
+  }),
+  'boxxy.commit.linked': z.object({
+    ...ofAttempt,
+    repo: brandSchemas.repoName,
+    sha: brandSchemas.commitSha,
+    pullRequestNumber: pullRequestNumberSchema,
+  }),
+  'boxxy.pull_request.merged': z.object({
+    ...ofAttempt,
+    repo: brandSchemas.repoName,
+    number: pullRequestNumberSchema,
+    pullRequestId: pullRequestIdSchema,
+    mergedAt: brandSchemas.instant,
+    mergeCommit: brandSchemas.commitSha,
+  }),
+  'boxxy.pull_request.closed': z.object({
+    ...ofAttempt,
+    repo: brandSchemas.repoName,
+    number: pullRequestNumberSchema,
+    pullRequestId: pullRequestIdSchema,
+  }),
+} satisfies { readonly [T in FactType]: z.ZodType<WorkFacts[T]> };