@boxxy/model 0.1.2 → 0.1.3

package/src/closeouts/types.ts

@@ -0,0 +1,230 @@
+import type { JsonValue } from '@boxxy/content-hash';
+import type {
+  AttemptId,
+  CommitSha,
+  Criterion,
+  CriterionId,
+  DesignMode,
+  EvidenceRow,
+  FactId,
+  ItemId,
+  ItemKindName,
+  ItemView,
+  RelationTypeName,
+  RepoName,
+} from '../types.ts';
+
+// The four close-out bodies, one per v1 phase. Every body carries `friction` and
+// `frictionDropped`. The top-level keys of the four differ, so a stored close-out parses as one
+// of them only.
+export type CloseOut = TriageCloseOut | DesignCloseOut | BuildCloseOut | ReviewCloseOut;
+
+export interface TriageCloseOut {
+  readonly result:
+    | { readonly kind: 'accepted' }
+    | { readonly kind: 'duplicate'; readonly of: ItemId }
+    | { readonly kind: 'declined'; readonly reason: string };
+  readonly set?: {
+    readonly kind?: ItemKindName;
+    readonly designMode?: DesignMode;
+
+    // required with `accepted` when the item has no acceptance list (`no-acceptance`)
+    readonly acceptance?: readonly { readonly text: string }[];
+  };
+  readonly relations: readonly RelationDraft[];
+  readonly friction: readonly Friction[];
+  readonly frictionDropped: number;
+}
+
+export interface DesignCloseOut {
+  readonly result:
+    | { readonly kind: 'designed'; readonly design: DesignRef }
+    | { readonly kind: 'blocked'; readonly reason: string }
+    | { readonly kind: 'abandoned'; readonly reason: string };
+  readonly friction: readonly Friction[];
+  readonly frictionDropped: number;
+}
+
+// Where the design of an item is, and what it says in short. The build and the review get it in
+// their input.
+export interface DesignRef {
+  readonly summary: string;
+
+  // a URL or a repo path of the whole design; null when the summary is the whole design
+  readonly location: string | null;
+}
+
+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;
+}
+
+// The review close-out as stored: the review session sends noslop's whole result, and the parser
+// keeps `NoslopSummary` in its place.
+export interface ReviewCloseOut {
+  readonly verdict:
+    | { readonly kind: 'passed' }
+    | { readonly kind: 'changes-requested'; readonly findings: readonly Finding[] };
+  readonly noslop: NoslopSummary;
+  readonly friction: readonly Friction[];
+  readonly frictionDropped: number;
+}
+
+export interface NoslopSummary {
+  // the schema version of noslop's result
+  readonly version: number;
+  readonly reviewID: string;
+  readonly head: CommitSha;
+  readonly counts: {
+    readonly findings: number;
+    readonly failedCalls: number;
+    readonly fixChecks: number;
+  };
+
+  // the UTF-8 bytes of the JSON of the parsed result, as a stored copy would take them
+  readonly reportBytes: number;
+
+  // the whole result when `reportBytes` is within the close-out limit; else null, never a part
+  readonly report: JsonValue | null;
+}
+
+export interface Finding {
+  readonly title: string;
+  readonly body: string;
+  readonly path?: string;
+  readonly line?: number;
+}
+
+// A relation that a close-out asks for, from the attempt's item to `target`.
+export interface RelationDraft {
+  readonly type: RelationTypeName;
+  readonly target: ItemId;
+}
+
+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;
+}
+
+// What a phase kind's settle asks for. The settle of an attempt whose outcome maps to a hold
+// withholds each effect that changes an item, and keeps `record-proposal`.
+export type Effect =
+  | { readonly kind: 'file-item'; readonly item: OpenItem }
+  | { readonly kind: 'close-item'; readonly reason: string; readonly of: ItemId | null }
+  | { readonly kind: 'add-relation'; readonly relation: RelationDraft }
+  | { readonly kind: 'set-kind'; readonly itemKind: ItemKindName }
+  | { readonly kind: 'set-field'; readonly field: 'designMode'; readonly value: DesignMode }
+  | { readonly kind: 'set-acceptance'; readonly criteria: readonly Criterion[] }
+  | { readonly kind: 'record-proposal'; readonly friction: Friction };
+
+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[] }
+  | { readonly kind: 'no-acceptance' }
+  | { readonly kind: 'unknown-item'; readonly item: string }
+  | { readonly kind: 'unknown-kind'; readonly itemKind: string }
+  | {
+      readonly kind: 'refused-relation';
+      readonly type: string;
+      readonly target: string;
+      readonly reason: 'unknown-type' | 'self';
+    }
+
+  // a rule of one phase kind that its schema cannot hold, such as a finding for `changes-requested`
+  | { readonly kind: 'phase-rule'; readonly message: string }
+
+  // over `closeOutBytes` as stored; `bytes` tells the agent how much to cut
+  | { readonly kind: 'too-large'; readonly bytes: number; readonly max: number };
+
+export type CloseOutParse<Body> =
+  | { readonly kind: 'valid'; readonly closeOut: Body }
+  | { readonly kind: 'invalid'; readonly problems: readonly CloseOutProblem[] };
+
+export interface CloseOutParser<Body> {
+  parse: (raw: unknown, ctx: CloseOutContext) => CloseOutParse<Body>;
+
+  // the JSON Schema of the body that the agent sends, which `attempt.current` gives the session
+  readonly jsonSchema: JsonValue;
+}
+
+export interface CloseOutContext {
+  readonly item: ItemView;
+  readonly attempt: AttemptId;
+
+  // the attempt's own evidence rows
+  readonly evidence: readonly EvidenceRow[];
+  readonly world: CloseOutWorld;
+}
+
+// What a parser may check a named item, kind or relation type against.
+export interface CloseOutWorld {
+  // every item of the store, open or closed
+  readonly items: ReadonlySet<ItemId>;
+  readonly kinds: ReadonlySet<ItemKindName>;
+  readonly relationTypes: ReadonlySet<RelationTypeName>;
+}
+
+export interface CriterionText {
+  readonly id: CriterionId;
+  readonly text: string;
+}
+
+// The input of a triage or a design attempt: the item's acceptance list, which may be empty
+// before triage.
+export interface AcceptanceInput {
+  readonly acceptance: readonly CriterionText[];
+}
+
+// The input of a build attempt. In round 2 and later it holds the findings of the review that
+// sent the item back; in round 1 it holds none.
+export interface BuildInput {
+  readonly acceptance: readonly CriterionText[];
+  readonly design: DesignRef | null;
+  readonly findings: readonly Finding[];
+
+  // the item's latest pull request, which a build of round 2 pushes to
+  readonly pullRequest: PullRequestLink | null;
+}
+
+export interface ReviewInput {
+  readonly acceptance: readonly CriterionText[];
+  readonly design: DesignRef | null;
+  readonly pullRequest: PullRequestLink | null;
+}
+
+export interface PullRequestLink {
+  readonly repo: RepoName;
+  readonly number: number;
+  readonly url: string;
+}
+
+// What `attempt.closeOut` answers. `recorded` carries `repeat`: true when the same close-out
+// arrived again. `rejected` carries every problem at once.
+export type CloseOutAnswer =
+  | {
+      readonly kind: 'recorded';
+      readonly attempt: AttemptId;
+      readonly factId: FactId;
+      readonly repeat: boolean;
+    }
+  | { readonly kind: 'rejected'; readonly problems: readonly CloseOutProblem[] }
+  | {
+      readonly kind: 'refused';
+      readonly reason: 'no-attempt' | 'already-closed-out' | 'not-current';
+    };

package/src/dispatch/build-applied-change.ts

@@ -0,0 +1,57 @@
+import type { AnyNewFact } from '../facts/types.ts';
+import type { RowWrite, StoreChange } from '../ports/types.ts';
+
+export interface ChangeAssignments {
+  // 0 when the store holds no lever
+  readonly lastLeverSeq: number;
+
+  // 0 when the store holds no notice
+  readonly lastNoticeId: number;
+}
+
+// The store numbers each lever and each notice, so the caller's `seq` and `id` are replaced.
+export function buildAppliedChange(
+  change: StoreChange,
+  assignments: ChangeAssignments,
+): Pick<StoreChange, 'writes' | 'facts'> {
+  const leverSeqs: number[] = [];
+  let notices = 0;
+
+  const writes = change.writes.map((write): RowWrite => {
+    if (write.op !== 'insert') {
+      return write;
+    }
+
+    if (write.table === 'levers') {
+      const seq = assignments.lastLeverSeq + leverSeqs.length + 1;
+
+      leverSeqs.push(seq);
+
+      return { ...write, row: { ...write.row, seq } };
+    }
+
+    if (write.table === 'notices') {
+      notices += 1;
+
+      return { ...write, row: { ...write.row, id: assignments.lastNoticeId + notices } };
+    }
+
+    return write;
+  });
+
+  let leverFacts = 0;
+
+  const facts = change.facts.map((fact): AnyNewFact => {
+    if (fact.type !== 'boxxy.lever.recorded') {
+      return fact;
+    }
+
+    const seq = leverSeqs[leverFacts];
+
+    leverFacts += 1;
+
+    return seq === undefined ? fact : { ...fact, payload: { ...fact.payload, seq } };
+  });
+
+  return { writes, facts };
+}

package/src/dispatch/collect-seat-sync.ts

@@ -0,0 +1,86 @@
+import { isFilterMatch } from '../planning/is-filter-match.ts';
+import type { Limit } from '../planning/types.ts';
+import type { AttemptRow, AttemptState, Instant, LimitSeatRow } from '../types.ts';
+
+export interface SeatSync {
+  // held seats to release
+  readonly release: readonly LimitSeatRow[];
+  readonly take: readonly LimitSeatRow[];
+}
+
+interface SeatSyncInput {
+  // the limits as the rules now load them
+  readonly limits: readonly Limit[];
+
+  // the seats with no release time
+  readonly held: readonly LimitSeatRow[];
+  readonly attempts: readonly AttemptRow[];
+  readonly at: Instant;
+}
+
+// The seats follow the loaded limits, matched against each attempt's stored fields: a seat of a
+// limit that went, or that no longer counts its attempt, is released; a seated attempt gets a seat
+// in each limit that now counts it, past `max` when the limit is full.
+export function collectSeatSync(input: SeatSyncInput): SeatSync {
+  const seated = new Map(
+    input.attempts.filter((attempt) => isSeated(attempt)).map((attempt) => [attempt.id, attempt]),
+  );
+
+  const release = input.held.filter((seat) => {
+    const limit = input.limits.find((candidate) => candidate.name === seat.limit);
+    const attempt = seated.get(seat.attempt);
+
+    return (
+      limit === undefined || (attempt !== undefined && !isFilterMatch(limit.counts, attempt.fields))
+    );
+  });
+
+  const kept = input.held.filter((seat) => !release.includes(seat));
+  const take: LimitSeatRow[] = [];
+
+  for (const limit of input.limits) {
+    let count = kept.filter((seat) => seat.limit === limit.name).length;
+
+    for (const attempt of seated.values()) {
+      const hasSeat = kept.some(
+        (seat) =>
+          seat.limit === limit.name &&
+          seat.attempt === attempt.id &&
+          seat.holdGen === attempt.holdGen,
+      );
+
+      if (!hasSeat && isFilterMatch(limit.counts, attempt.fields)) {
+        take.push({
+          limit: limit.name,
+          attempt: attempt.id,
+          holdGen: attempt.holdGen,
+          overCap: count >= limit.max,
+          takenAt: input.at,
+          releasedAt: null,
+        });
+
+        count += 1;
+      }
+    }
+  }
+
+  return { release, take };
+}
+
+// A sleeping attempt holds no seat, and a settled one has released its seats.
+const seatedStates: ReadonlySet<AttemptState> = new Set([
+  'starting',
+  'reconciling',
+  'running',
+  'waking',
+  'closing',
+]);
+
+// A sleeping attempt that closes out moves to `closing` and takes no seat, so its last sleep,
+// later than its last wake, keeps it out.
+function isSeated(attempt: AttemptRow): boolean {
+  const isAsleep =
+    attempt.sleptAt !== null && (attempt.wokenAt === null || attempt.wokenAt < attempt.sleptAt);
+
+  return seatedStates.has(attempt.state) && !isAsleep;
+}

package/src/dispatch/pick-seat-take.ts

@@ -0,0 +1,39 @@
+import type { LimitFill, SeatTake } from '../planning/types.ts';
+import type { Instant, LimitName, LimitSeatRow } from '../types.ts';
+
+export type SeatTakeAnswer =
+  | { readonly kind: 'take'; readonly seats: readonly LimitSeatRow[] }
+  | { readonly kind: 'limit-full' | 'unknown-limit'; readonly limit: LimitName };
+
+// All or none: one seat in each named limit, or the first limit that refuses. A take over the
+// cap ignores `max`, and still refuses a limit that the store does not hold.
+export function pickSeatTake(
+  take: SeatTake,
+  limits: readonly LimitFill[],
+  at: Instant,
+): SeatTakeAnswer {
+  const names = [...new Set(take.limits)];
+
+  for (const name of names) {
+    const limit = limits.find((candidate) => candidate.name === name);
+
+    if (limit === undefined) {
+      return { kind: 'unknown-limit', limit: name };
+    }
+
+    if (!take.overCap && limit.held >= limit.max) {
+      return { kind: 'limit-full', limit: name };
+    }
+  }
+
+  const seats = names.map((limit): LimitSeatRow => ({
+    limit,
+    attempt: take.attempt,
+    holdGen: take.holdGen,
+    overCap: take.overCap,
+    takenAt: at,
+    releasedAt: null,
+  }));
+
+  return { kind: 'take', seats };
+}

package/src/dispatch/types.ts

@@ -0,0 +1,14 @@
+import type { SpawnRequest } from '../ports/types.ts';
+import type { AttemptRow, KeptSession } from '../types.ts';
+
+// The second kind is `wake`: the claim of a sleeping attempt, which the worker resumes.
+export type Claim =
+  | {
+      readonly kind: 'start';
+      readonly attempt: AttemptRow;
+      readonly spawn: SpawnRequest;
+
+      // the item's kept session, when the claim came back through an edge with `resume: true`
+      readonly kept: KeptSession | null;
+    }
+  | { readonly kind: 'wake'; readonly attempt: AttemptRow };

package/src/facts/outbox-fact-schema.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { actorRefSchema } from '../rows/actor-ref-schema.ts';
+import { brandSchemas } from '../rows/brand-schemas.ts';
+import type { FactType, OutboxFact } from './types.ts';
+import { workFactSchemas } from './work-fact-schemas.ts';
+
+const factTypes = Object.keys(workFactSchemas).filter((type): type is FactType =>
+  Object.hasOwn(workFactSchemas, type),
+);
+
+export const outboxFactSchema: z.ZodType<OutboxFact> = z.object({
+  seq: z.number().int().positive(),
+  factId: brandSchemas.factId,
+  type: z.enum(factTypes),
+  entity: z.templateLiteral(['boxxy:item:', z.string().min(1)]),
+  actor: actorRefSchema,
+  at: brandSchemas.instant,
+  payload: z.json(),
+  sentAt: brandSchemas.instant.nullable(),
+  parkedAt: brandSchemas.instant.nullable(),
+  parkedReason: z.string().min(1).nullable(),
+});

package/src/facts/parse-new-fact.ts

@@ -0,0 +1,16 @@
+import type { z } from 'zod';
+import type { AnyNewFact } from './types.ts';
+import { workFactSchemas } from './work-fact-schemas.ts';
+
+// The store's check of each fact before the change writes it: a payload that its type's schema
+// refuses throws, and the change writes nothing.
+export function parseNewFact(fact: AnyNewFact): AnyNewFact {
+  const schema: z.ZodType = workFactSchemas[fact.type];
+  const parsed = schema.safeParse(fact.payload);
+
+  if (!parsed.success) {
+    throw new Error(`the payload of a ${fact.type} fact is not valid`, { cause: parsed.error });
+  }
+
+  return fact;
+}