@boxxy/closeout 0.1.0 → 0.1.4

package/README.md

@@ -11,11 +11,11 @@
   </p>
 </div>
 
-boxxy's close-out parser. It checks the close-out an agent sends at the end of a build attempt, and
-splits the work the agent found into new items to file and matches of items already open.
+boxxy's phase kinds: triage, design, build and review. Each one gives the input of an attempt,
+checks the close-out the agent sends at the end of it, and settles the attempt from that close-out.
 
-The package does no I/O: the caller passes in the item, the attempt's evidence rows and the open
-items.
+The package does no I/O: the caller passes in the item, its attempts, the attempt's evidence rows
+and what a close-out may name.
 
 ## Install
 
@@ -29,13 +29,16 @@ The package runs on [Bun](https://bun.sh) 1.3 or newer.
 
 ## Features
 
-- `buildCloseOutParser`, which returns the parsed close-out, or every problem with it in one pass
-  ([the build close-out](../../docs/design/boxxy/slice-1.md#the-build-close-out)).
-- `missingCriteria`, which lists the item's criteria that the close-out cites no evidence for.
-- `dedupeOpenItems` and `normaliseTitle`, which match each open item the agent reports to an open
-  item with the same title.
+- `triage`, `design`, `build` and `review`, the four phase kinds, and `phaseKinds`, which lists them
+  for the rules loader. Each parser returns the stored close-out, or every problem with it in one
+  pass.
+- `closeOutLimits`, the byte limits of a close-out, and `measureJsonBytes`, which measures a value
+  as stored.
+- `dedupeOpenItems`, which matches each open item the agent reports to an open item with the same
+  title.
 
 ## Documentation
 
-The [close-outs design](../../docs/design/boxxy/close-outs.md) says what a close-out holds and why,
-and [`06-closeouts.ts`](../../docs/design/boxxy/sketches/06-closeouts.ts) gives the shapes.
+The [close-outs design](../../docs/design/boxxy/close-outs.md#the-v1-phase-kinds) says what each
+phase kind checks and settles, and
+[`02-types.ts`](../../docs/design/boxxy/sketches/v1/core/02-types.ts) gives the shapes.

package/dist/build-schema-parser.d.ts

@@ -0,0 +1,9 @@
+import type { CloseOutContext, CloseOutParser, CloseOutProblem } from '@boxxy/model';
+import { z } from 'zod';
+interface SchemaParserInput<Raw, Body> {
+    readonly schema: z.ZodType<Raw>;
+    readonly toBody: (raw: Raw, frictionDropped: number) => Body;
+    readonly check: (body: Body, ctx: CloseOutContext) => readonly CloseOutProblem[];
+}
+export declare function buildSchemaParser<Raw, Body>(input: SchemaParserInput<Raw, Body>): CloseOutParser<Body>;
+export {};

package/dist/close-out-limits.d.ts

@@ -0,0 +1,2 @@
+import type { CloseOutLimits } from './types.ts';
+export declare const closeOutLimits: CloseOutLimits;

package/dist/index.d.ts

@@ -1,4 +1,9 @@
-export { buildCloseOutParser } from './build-close-out-parser.ts';
+export { closeOutLimits } from './close-out-limits.ts';
 export { dedupeOpenItems } from './dedupe-open-items.ts';
-export { missingCriteria } from './missing-criteria.ts';
-export { normaliseTitle } from './normalise-title.ts';
+export { measureJsonBytes } from './measure-json-bytes.ts';
+export { phaseKinds } from './phase-kinds.ts';
+export { build } from './phases/build.ts';
+export { design } from './phases/design.ts';
+export { review } from './phases/review.ts';
+export { triage } from './phases/triage.ts';
+export type { CloseOutLimits, NoslopReport } from './types.ts';

package/dist/measure-json-bytes.d.ts

@@ -0,0 +1,2 @@
+import type { JsonValue } from '@boxxy/model';
+export declare function measureJsonBytes(value: JsonValue): number;

package/dist/noslop/build-noslop-summary.d.ts

@@ -0,0 +1,3 @@
+import type { NoslopSummary } from '@boxxy/model';
+import type { NoslopReport } from '../types.ts';
+export declare function buildNoslopSummary(report: NoslopReport): NoslopSummary;

package/dist/noslop/noslop-report-schema.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+export declare const noslopReportSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    reviewID: z.ZodString;
+    head: z.core.$ZodBranded<z.ZodString, "CommitSha", "out">;
+    findings: z.ZodArray<z.ZodUnknown>;
+    failedCalls: z.ZodArray<z.ZodUnknown>;
+    fixChecks: z.ZodExactOptional<z.ZodArray<z.ZodUnknown>>;
+}, z.core.$loose>;

package/dist/phase-kinds.d.ts

@@ -0,0 +1,2 @@
+import type { PhaseKind } from '@boxxy/model';
+export declare const phaseKinds: readonly PhaseKind[];

package/dist/phases/build.d.ts

@@ -0,0 +1 @@
+export declare const build: import("@boxxy/model").PhaseKind<unknown, import("@boxxy/content-hash").JsonValue, readonly string[]>;

package/dist/phases/design.d.ts

@@ -0,0 +1 @@
+export declare const design: import("@boxxy/model").PhaseKind<unknown, import("@boxxy/content-hash").JsonValue, readonly string[]>;

package/dist/phases/review.d.ts

@@ -0,0 +1 @@
+export declare const review: import("@boxxy/model").PhaseKind<unknown, import("@boxxy/content-hash").JsonValue, readonly string[]>;

package/dist/phases/triage.d.ts

@@ -0,0 +1 @@
+export declare const triage: import("@boxxy/model").PhaseKind<unknown, import("@boxxy/content-hash").JsonValue, readonly string[]>;

package/dist/test-utils/build-mock-noslop-report.d.ts

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

package/dist/types.d.ts

@@ -0,0 +1,7 @@
+import type { z } from 'zod';
+import type { noslopReportSchema } from './noslop/noslop-report-schema.ts';
+export interface CloseOutLimits {
+    readonly closeOutBytes: 120_000;
+    readonly noslopReportBytes: 32_768;
+}
+export type NoslopReport = z.output<typeof noslopReportSchema>;

package/dist/utils/build-criterion-texts.d.ts

@@ -0,0 +1,2 @@
+import type { CriterionText, ItemView } from '@boxxy/model';
+export declare function buildCriterionTexts(item: ItemView): CriterionText[];

package/dist/utils/find-latest-close-out.d.ts

@@ -0,0 +1,3 @@
+import type { AttemptRow } from '@boxxy/model';
+import type { z } from 'zod';
+export declare function findLatestCloseOut<Body>(history: readonly AttemptRow[], phase: string, schema: z.ZodType<Body>): Body | null;

package/dist/utils/find-latest-design.d.ts

@@ -0,0 +1,2 @@
+import type { AttemptRow, DesignRef } from '@boxxy/model';
+export declare function findLatestDesign(history: readonly AttemptRow[]): DesignRef | null;

package/dist/utils/find-pull-request-link.d.ts

@@ -0,0 +1,2 @@
+import type { PullRequestLink, PullRequestRow } from '@boxxy/model';
+export declare function findPullRequestLink(pullRequests: readonly PullRequestRow[]): PullRequestLink | null;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@boxxy/closeout",
-  "version": "0.1.0",
-  "description": "boxxy's close-out parser: checks the close-out an agent sends at the end of an attempt",
+  "version": "0.1.4",
+  "description": "boxxy's phase kinds: the input, the close-out parser and the settle rule of triage, design, build and review",
   "homepage": "https://github.com/zgeoff/boxxy/tree/main/modules/closeout#readme",
   "bugs": "https://github.com/zgeoff/boxxy/issues",
   "license": "MIT",
@@ -20,7 +20,8 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./src/index.ts"
-    }
+    },
+    "./test-utils/*": "./src/test-utils/*.ts"
   },
   "publishConfig": {
     "access": "public"
@@ -30,8 +31,23 @@
     "typecheck": "tsrs --noEmit"
   },
   "dependencies": {
-    "@boxxy/model": "0.1.1",
-    "tiny-invariant": "1.3.3"
+    "@boxxy/model": "0.1.4",
+    "tiny-invariant": "1.3.3",
+    "ts-pattern": "5.9.2",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@boxxy/planning": "0.1.4",
+    "@boxxy/rules": "0.1.4",
+    "@faker-js/faker": "10.6.0"
+  },
+  "peerDependencies": {
+    "@faker-js/faker": "10.6.0"
+  },
+  "peerDependenciesMeta": {
+    "@faker-js/faker": {
+      "optional": true
+    }
   },
   "engines": {
     "bun": ">=1.3",

package/src/build-schema-parser.ts

@@ -0,0 +1,124 @@
+import type { CloseOutContext, CloseOutParse, CloseOutParser, CloseOutProblem } from '@boxxy/model';
+import { formatKeyPath, toJSONValue } from '@boxxy/model';
+import invariant from 'tiny-invariant';
+import { z } from 'zod';
+import { closeOutLimits } from './close-out-limits.ts';
+import { measureJsonBytes } from './measure-json-bytes.ts';
+
+interface SchemaParserInput<Raw, Body> {
+  // the body as the agent sends it, with no `frictionDropped`: the parser counts that itself
+  readonly schema: z.ZodType<Raw>;
+  readonly toBody: (raw: Raw, frictionDropped: number) => Body;
+
+  // the rules of the phase that the schema cannot hold; each problem comes back
+  readonly check: (body: Body, ctx: CloseOutContext) => readonly CloseOutProblem[];
+}
+
+// The one parse of every phase kind: drop each friction entry with no target, check the
+// schema, build the stored body, check the phase's rules, then the stored size. A failed step
+// reports every problem it found, and stops the steps after it.
+export function buildSchemaParser<Raw, Body>(
+  input: SchemaParserInput<Raw, Body>,
+): CloseOutParser<Body> {
+  return {
+    parse: (raw, ctx) => parseCloseOut(input, raw, ctx),
+    jsonSchema: toJSONValue(z.toJSONSchema(input.schema)),
+  };
+}
+
+function parseCloseOut<Raw, Body>(
+  input: SchemaParserInput<Raw, Body>,
+  raw: unknown,
+  ctx: CloseOutContext,
+): CloseOutParse<Body> {
+  const split = splitFriction(raw);
+  const parsed = input.schema.safeParse(split.candidate);
+
+  if (!parsed.success) {
+    return {
+      kind: 'invalid',
+      problems: parsed.error.issues.map((issue) => buildSchemaProblem(issue, split.keptRawIndexes)),
+    };
+  }
+
+  const body = input.toBody(parsed.data, split.dropped);
+  const problems = input.check(body, ctx);
+
+  if (problems.length > 0) {
+    return { kind: 'invalid', problems };
+  }
+
+  const bytes = measureJsonBytes(toJSONValue(body));
+
+  return bytes > closeOutLimits.closeOutBytes
+    ? {
+        kind: 'invalid',
+        problems: [{ kind: 'too-large', bytes, max: closeOutLimits.closeOutBytes }],
+      }
+    : { kind: 'valid', closeOut: body };
+}
+
+interface FrictionSplit {
+  readonly candidate: unknown;
+  readonly keptRawIndexes: readonly number[];
+  readonly dropped: number;
+}
+
+// An agent's count of dropped entries is not trusted: the key is removed, and the parser counts.
+function splitFriction(raw: unknown): FrictionSplit {
+  if (!isRecord(raw)) {
+    return { candidate: raw, keptRawIndexes: [], dropped: 0 };
+  }
+
+  const { frictionDropped: _, ...rest } = raw;
+  const entries: readonly unknown[] = Array.isArray(rest['friction']) ? rest['friction'] : [];
+  const keptRawIndexes = entries.flatMap((entry, index) => (isUntargeted(entry) ? [] : [index]));
+
+  const friction = Array.isArray(rest['friction'])
+    ? keptRawIndexes.map((index) => entries[index])
+    : rest['friction'];
+
+  return {
+    candidate: { ...rest, friction },
+    keptRawIndexes,
+    dropped: entries.length - keptRawIndexes.length,
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isUntargeted(entry: unknown): boolean {
+  return isRecord(entry) && (entry['target'] === undefined || entry['target'] === null);
+}
+
+interface SchemaIssue {
+  readonly path: readonly PropertyKey[];
+  readonly message: string;
+}
+
+function buildSchemaProblem(
+  issue: SchemaIssue,
+  keptRawIndexes: readonly number[],
+): CloseOutProblem {
+  return {
+    kind: 'schema',
+    path: formatKeyPath(toRawPath(issue.path, keptRawIndexes)),
+    message: issue.message,
+  };
+}
+
+function toRawPath(path: readonly PropertyKey[], keptRawIndexes: readonly number[]): PropertyKey[] {
+  const [field, index, ...rest] = path;
+
+  if (field !== 'friction' || typeof index !== 'number') {
+    return [...path];
+  }
+
+  const rawIndex = keptRawIndexes[index];
+
+  invariant(rawIndex !== undefined, 'a friction issue points at an entry the parser kept');
+
+  return [field, rawIndex, ...rest];
+}

package/src/close-out-limits.ts

@@ -0,0 +1,9 @@
+import type { CloseOutLimits } from './types.ts';
+
+// The byte limits of a close-out, measured on the JSON of the value as stored. A close-out of
+// 120,000 bytes makes a `closed_out` fact under half of the 256 KiB a fact may take on the wire,
+// so a layer that escapes the JSON once more still fits.
+export const closeOutLimits: CloseOutLimits = {
+  closeOutBytes: 120_000,
+  noslopReportBytes: 32_768,
+};

package/src/index.ts

@@ -1,4 +1,9 @@
-export { buildCloseOutParser } from './build-close-out-parser.ts';
+export { closeOutLimits } from './close-out-limits.ts';
 export { dedupeOpenItems } from './dedupe-open-items.ts';
-export { missingCriteria } from './missing-criteria.ts';
-export { normaliseTitle } from './normalise-title.ts';
+export { measureJsonBytes } from './measure-json-bytes.ts';
+export { phaseKinds } from './phase-kinds.ts';
+export { build } from './phases/build.ts';
+export { design } from './phases/design.ts';
+export { review } from './phases/review.ts';
+export { triage } from './phases/triage.ts';
+export type { CloseOutLimits, NoslopReport } from './types.ts';

package/src/measure-json-bytes.ts

@@ -0,0 +1,8 @@
+import type { JsonValue } from '@boxxy/model';
+
+const encoder = new TextEncoder();
+
+// The UTF-8 bytes of the value's JSON, which is what a stored copy takes.
+export function measureJsonBytes(value: JsonValue): number {
+  return encoder.encode(JSON.stringify(value)).length;
+}

package/src/noslop/build-noslop-summary.ts

@@ -0,0 +1,25 @@
+import type { NoslopSummary } from '@boxxy/model';
+import { toJSONValue } from '@boxxy/model';
+import { closeOutLimits } from '../close-out-limits.ts';
+import { measureJsonBytes } from '../measure-json-bytes.ts';
+import type { NoslopReport } from '../types.ts';
+
+// Keeps the counts of noslop's result, and the result whole only when it fits the limit: a cut
+// part of the JSON would be no report at all.
+export function buildNoslopSummary(report: NoslopReport): NoslopSummary {
+  const whole = toJSONValue(report);
+  const reportBytes = measureJsonBytes(whole);
+
+  return {
+    version: report.version,
+    reviewID: report.reviewID,
+    head: report.head,
+    counts: {
+      findings: report.findings.length,
+      failedCalls: report.failedCalls.length,
+      fixChecks: report.fixChecks?.length ?? 0,
+    },
+    reportBytes,
+    report: reportBytes <= closeOutLimits.noslopReportBytes ? whole : null,
+  };
+}

package/src/noslop/noslop-report-schema.ts

@@ -0,0 +1,13 @@
+import { brandSchemas } from '@boxxy/model';
+import { z } from 'zod';
+
+// The fields of `noslop review --report json` that the summary reads. Every other field passes
+// through unread, and a list's entries are not checked, so a newer noslop still parses.
+export const noslopReportSchema = z.looseObject({
+  version: z.number().int().positive(),
+  reviewID: z.string().min(1),
+  head: brandSchemas.commitSha,
+  findings: z.array(z.unknown()),
+  failedCalls: z.array(z.unknown()),
+  fixChecks: z.array(z.unknown()).exactOptional(),
+});

package/src/phase-kinds.ts

@@ -0,0 +1,8 @@
+import type { PhaseKind } from '@boxxy/model';
+import { build } from './phases/build.ts';
+import { design } from './phases/design.ts';
+import { review } from './phases/review.ts';
+import { triage } from './phases/triage.ts';
+
+// The phase kinds that the server passes to the rules loader, in pipeline order
+export const phaseKinds: readonly PhaseKind[] = [triage, design, build, review];

package/src/phases/build.ts

@@ -0,0 +1,130 @@
+import type {
+  BuildCloseOut,
+  BuildInput,
+  CloseOutContext,
+  CloseOutProblem,
+  Criterion,
+  Effect,
+  ItemView,
+  PhaseInputContext,
+} from '@boxxy/model';
+import {
+  brandSchemas,
+  buildCloseOutSchema,
+  definePhase,
+  reviewCloseOutSchema,
+  toJSONValue,
+} from '@boxxy/model';
+import { match } from 'ts-pattern';
+import type { z } from 'zod';
+import { buildSchemaParser } from '../build-schema-parser.ts';
+import { missingCriteria } from '../missing-criteria.ts';
+import { buildCriterionTexts } from '../utils/build-criterion-texts.ts';
+import { findLatestCloseOut } from '../utils/find-latest-close-out.ts';
+import { findLatestDesign } from '../utils/find-latest-design.ts';
+import { findPullRequestLink } from '../utils/find-pull-request-link.ts';
+
+const buildBodySchema = buildCloseOutSchema.omit({ frictionDropped: true });
+
+export const build = definePhase({
+  name: brandSchemas.phaseName.parse('build'),
+  version: 1,
+  worker: brandSchemas.workerKindName.parse('atc.session'),
+  outcomes: ['built', 'blocked', 'abandoned'],
+  needsAcceptance: true,
+  input: (ctx) => toJSONValue(buildBuildInput(ctx)),
+  closeOut: buildSchemaParser({
+    schema: buildBodySchema,
+    toBody: (raw: z.output<typeof buildBodySchema>, frictionDropped): BuildCloseOut => ({
+      ...raw,
+      frictionDropped,
+    }),
+    check: collectBuildProblems,
+  }),
+
+  // A blocked or abandoned build did not reach its goal, so its attempt fails and keeps no
+  // session. The failure is the outcome name: the agent's reason is free text, and the engine
+  // reads some failure names, such as `no-capacity`. The reason stays in the close-out.
+  settle: (input) => ({
+    ...match(input.closeOut.result)
+      .with({ kind: 'built' }, () => ({ state: 'succeeded' as const, failure: null }))
+      .with({ kind: 'blocked' }, { kind: 'abandoned' }, (ended) => ({
+        state: 'failed' as const,
+        failure: ended.kind,
+      }))
+      .exhaustive(),
+    outcome: input.closeOut.result.kind,
+    effects: collectBuildEffects(input.closeOut, input.item),
+    frictionDropped: input.closeOut.frictionDropped,
+  }),
+});
+
+// The findings come from the latest review, and only when it asked for changes: a build after
+// a passed review, sent back by the owner, gets none.
+function buildBuildInput(ctx: PhaseInputContext): BuildInput {
+  const review = findLatestCloseOut(ctx.history, 'review', reviewCloseOutSchema);
+
+  return {
+    acceptance: buildCriterionTexts(ctx.item),
+    design: findLatestDesign(ctx.history),
+    findings: review?.verdict.kind === 'changes-requested' ? review.verdict.findings : [],
+    pullRequest: findPullRequestLink(ctx.pullRequests),
+  };
+}
+
+function collectBuildProblems(closeOut: BuildCloseOut, ctx: CloseOutContext): CloseOutProblem[] {
+  const acceptance = new Set(ctx.item.acceptance.map((criterion) => criterion.id));
+  const own = new Set(ctx.evidence.map((row) => row.factId));
+
+  const cited = closeOut.criteria;
+
+  const unknownCriteria = new Set(
+    cited.map((entry) => entry.criterion).filter((id) => !acceptance.has(id)),
+  );
+
+  const foreignEvidence = new Set(
+    cited.map((entry) => entry.evidence).filter((id) => !own.has(id)),
+  );
+
+  const missing =
+    closeOut.result.kind === 'built' ? missingCriteria(ctx.item, ctx.evidence, cited) : [];
+
+  return [
+    ...[...unknownCriteria].map((criterion) => ({ kind: 'unknown-criterion' as const, criterion })),
+    ...[...foreignEvidence].map((evidence) => ({ kind: 'foreign-evidence' as const, evidence })),
+    ...(missing.length > 0 ? [{ kind: 'built-without-evidence' as const, criteria: missing }] : []),
+  ];
+}
+
+function collectBuildEffects(closeOut: BuildCloseOut, item: ItemView): Effect[] {
+  const acceptance = buildCitedAcceptance(item.acceptance, closeOut.criteria);
+
+  // a failed build changes no item: the next build of the item cites its evidence again
+  const isChanged =
+    closeOut.result.kind === 'built' &&
+    acceptance.some(
+      (criterion, index) => criterion.evidence.length !== item.acceptance[index]?.evidence.length,
+    );
+
+  return [
+    ...closeOut.openItems.map((openItem) => ({ kind: 'file-item' as const, item: openItem })),
+    ...(isChanged ? [{ kind: 'set-acceptance' as const, criteria: acceptance }] : []),
+    ...closeOut.friction.map((friction) => ({ kind: 'record-proposal' as const, friction })),
+  ];
+}
+
+// Each criterion gains the evidence ids the close-out cites for it, once each.
+function buildCitedAcceptance(
+  acceptance: readonly Criterion[],
+  cited: BuildCloseOut['criteria'],
+): Criterion[] {
+  return acceptance.map((criterion) => ({
+    ...criterion,
+    evidence: [
+      ...new Set([
+        ...criterion.evidence,
+        ...cited.filter((entry) => entry.criterion === criterion.id).map((entry) => entry.evidence),
+      ]),
+    ],
+  }));
+}

package/src/phases/design.ts

@@ -0,0 +1,42 @@
+import type { AcceptanceInput, DesignCloseOut } from '@boxxy/model';
+import { brandSchemas, definePhase, designCloseOutSchema, toJSONValue } from '@boxxy/model';
+import { match } from 'ts-pattern';
+import type { z } from 'zod';
+import { buildSchemaParser } from '../build-schema-parser.ts';
+import { buildCriterionTexts } from '../utils/build-criterion-texts.ts';
+
+const designBodySchema = designCloseOutSchema.omit({ frictionDropped: true });
+
+export const design = definePhase({
+  name: brandSchemas.phaseName.parse('design'),
+  version: 1,
+  worker: brandSchemas.workerKindName.parse('atc.session'),
+  outcomes: ['designed', 'blocked', 'abandoned'],
+  needsAcceptance: true,
+  mode: (item) => (item.fields.designMode === 'attended' ? 'attended' : 'agent'),
+  input: (ctx) =>
+    toJSONValue({ acceptance: buildCriterionTexts(ctx.item) } satisfies AcceptanceInput),
+  closeOut: buildSchemaParser({
+    schema: designBodySchema,
+    toBody: (raw: z.output<typeof designBodySchema>, frictionDropped): DesignCloseOut => ({
+      ...raw,
+      frictionDropped,
+    }),
+    check: () => [],
+  }),
+
+  // A blocked or abandoned design did not reach its goal, so its attempt fails. The failure is
+  // the outcome name, never the agent's free text; the reason stays in the close-out.
+  settle: (input) => ({
+    ...match(input.closeOut.result)
+      .with({ kind: 'designed' }, () => ({ state: 'succeeded' as const, failure: null }))
+      .with({ kind: 'blocked' }, { kind: 'abandoned' }, (ended) => ({
+        state: 'failed' as const,
+        failure: ended.kind,
+      }))
+      .exhaustive(),
+    outcome: input.closeOut.result.kind,
+    effects: input.closeOut.friction.map((friction) => ({ kind: 'record-proposal', friction })),
+    frictionDropped: input.closeOut.frictionDropped,
+  }),
+});

package/src/phases/review.ts

@@ -0,0 +1,50 @@
+import type { PhaseInputContext, ReviewCloseOut, ReviewInput } from '@boxxy/model';
+import { brandSchemas, definePhase, reviewCloseOutSchema, toJSONValue } from '@boxxy/model';
+import type { z } from 'zod';
+import { buildSchemaParser } from '../build-schema-parser.ts';
+import { buildNoslopSummary } from '../noslop/build-noslop-summary.ts';
+import { noslopReportSchema } from '../noslop/noslop-report-schema.ts';
+import { buildCriterionTexts } from '../utils/build-criterion-texts.ts';
+import { findLatestDesign } from '../utils/find-latest-design.ts';
+import { findPullRequestLink } from '../utils/find-pull-request-link.ts';
+
+// The session sends noslop's whole result; the stored close-out holds its summary instead.
+const reviewBodySchema = reviewCloseOutSchema
+  .omit({ frictionDropped: true })
+  .extend({ noslop: noslopReportSchema });
+
+export const review = definePhase({
+  name: brandSchemas.phaseName.parse('review'),
+  version: 1,
+  worker: brandSchemas.workerKindName.parse('atc.session'),
+  outcomes: ['passed', 'changes-requested'],
+  needsAcceptance: true,
+  input: (ctx) => toJSONValue(buildReviewInput(ctx)),
+  closeOut: buildSchemaParser({
+    schema: reviewBodySchema,
+    toBody: (raw: z.output<typeof reviewBodySchema>, frictionDropped): ReviewCloseOut => ({
+      ...raw,
+      noslop: buildNoslopSummary(raw.noslop),
+      frictionDropped,
+    }),
+    check: (closeOut) =>
+      closeOut.verdict.kind === 'changes-requested' && closeOut.verdict.findings.length === 0
+        ? [{ kind: 'phase-rule', message: 'changes-requested needs at least one finding' }]
+        : [],
+  }),
+  settle: (input) => ({
+    state: 'succeeded',
+    failure: null,
+    outcome: input.closeOut.verdict.kind,
+    effects: input.closeOut.friction.map((friction) => ({ kind: 'record-proposal', friction })),
+    frictionDropped: input.closeOut.frictionDropped,
+  }),
+});
+
+function buildReviewInput(ctx: PhaseInputContext): ReviewInput {
+  return {
+    acceptance: buildCriterionTexts(ctx.item),
+    design: findLatestDesign(ctx.history),
+    pullRequest: findPullRequestLink(ctx.pullRequests),
+  };
+}

package/src/phases/triage.ts

@@ -0,0 +1,152 @@
+import type {
+  AcceptanceInput,
+  CloseOutContext,
+  CloseOutProblem,
+  Criterion,
+  Effect,
+  TriageCloseOut,
+} from '@boxxy/model';
+import { brandSchemas, definePhase, toJSONValue, triageCloseOutSchema } from '@boxxy/model';
+import { match } from 'ts-pattern';
+import type { z } from 'zod';
+import { buildSchemaParser } from '../build-schema-parser.ts';
+import { buildCriterionTexts } from '../utils/build-criterion-texts.ts';
+
+const triageBodySchema = triageCloseOutSchema.omit({ frictionDropped: true });
+
+export const triage = definePhase({
+  name: brandSchemas.phaseName.parse('triage'),
+  version: 1,
+  worker: brandSchemas.workerKindName.parse('atc.session'),
+  outcomes: ['accepted', 'duplicate', 'declined'],
+  needsAcceptance: false,
+  input: (ctx) =>
+    toJSONValue({ acceptance: buildCriterionTexts(ctx.item) } satisfies AcceptanceInput),
+  closeOut: buildSchemaParser({
+    schema: triageBodySchema,
+    toBody: (raw: z.output<typeof triageBodySchema>, frictionDropped): TriageCloseOut => ({
+      ...raw,
+      frictionDropped,
+    }),
+    check: collectTriageProblems,
+  }),
+  settle: (input) => ({
+    state: 'succeeded',
+    failure: null,
+    outcome: input.closeOut.result.kind,
+    effects: collectTriageEffects(input.closeOut),
+    frictionDropped: input.closeOut.frictionDropped,
+  }),
+});
+
+function collectTriageProblems(closeOut: TriageCloseOut, ctx: CloseOutContext): CloseOutProblem[] {
+  const acceptance = closeOut.set?.acceptance ?? ctx.item.acceptance;
+  const kind = closeOut.set?.kind;
+  const duplicateOf = closeOut.result.kind === 'duplicate' ? [closeOut.result.of] : [];
+
+  const named = [...duplicateOf, ...closeOut.relations.map((relation) => relation.target)].filter(
+    (item) => item !== ctx.item.id,
+  );
+
+  return [
+    ...(closeOut.result.kind === 'accepted' && acceptance.length === 0
+      ? [{ kind: 'no-acceptance' as const }]
+      : []),
+    ...(kind !== undefined && !ctx.world.kinds.has(kind)
+      ? [{ kind: 'unknown-kind' as const, itemKind: kind }]
+      : []),
+    ...[...new Set(named)]
+      .filter((item) => !ctx.world.items.has(item))
+      .map((item) => ({ kind: 'unknown-item' as const, item })),
+    ...duplicateOf
+      .filter((item) => item === ctx.item.id)
+      .map(() => ({
+        kind: 'phase-rule' as const,
+        message: 'an item is not a duplicate of itself',
+      })),
+    ...closeOut.relations.flatMap((relation) => collectRelationProblems(relation, ctx)),
+    ...collectRepeatedRelations(closeOut, duplicateOf),
+  ];
+}
+
+function collectRelationProblems(
+  relation: TriageCloseOut['relations'][number],
+  ctx: CloseOutContext,
+): CloseOutProblem[] {
+  const refused = (reason: 'unknown-type' | 'self'): CloseOutProblem => ({
+    kind: 'refused-relation',
+    type: relation.type,
+    target: relation.target,
+    reason,
+  });
+
+  return [
+    ...(ctx.world.relationTypes.has(relation.type) ? [] : [refused('unknown-type')]),
+    ...(relation.target === ctx.item.id ? [refused('self')] : []),
+  ];
+}
+
+// Each relation is one row of the store, so a close-out names each pair of type and target once.
+// A duplicate's `of` names the `duplicate-of` relation already.
+function collectRepeatedRelations(
+  closeOut: TriageCloseOut,
+  duplicateOf: readonly TriageCloseOut['relations'][number]['target'][],
+): CloseOutProblem[] {
+  const named = [
+    ...duplicateOf.map((target) => ({ type: 'duplicate-of', target })),
+    ...closeOut.relations,
+  ];
+
+  return named.flatMap((relation, index) =>
+    named
+      .slice(0, index)
+      .some((earlier) => earlier.type === relation.type && earlier.target === relation.target)
+      ? [
+          {
+            kind: 'phase-rule' as const,
+            message: `the close-out names ${relation.type} ${relation.target} more than once`,
+          },
+        ]
+      : [],
+  );
+}
+
+// A duplicate closes with `of`, which adds the `duplicate-of` relation in the same change.
+function collectTriageEffects(closeOut: TriageCloseOut): Effect[] {
+  const set = closeOut.set ?? {};
+
+  return [
+    ...(set.kind === undefined ? [] : [{ kind: 'set-kind' as const, itemKind: set.kind }]),
+    ...(set.designMode === undefined
+      ? []
+      : [{ kind: 'set-field' as const, field: 'designMode' as const, value: set.designMode }]),
+    ...(set.acceptance === undefined
+      ? []
+      : [{ kind: 'set-acceptance' as const, criteria: buildCriteria(set.acceptance) }]),
+    ...closeOut.relations.map((relation) => ({ kind: 'add-relation' as const, relation })),
+    ...buildCloseEffects(closeOut.result),
+    ...closeOut.friction.map((friction) => ({ kind: 'record-proposal' as const, friction })),
+  ];
+}
+
+// The list replaces the item's list whole, so its criteria are numbered from `a1`.
+function buildCriteria(acceptance: readonly { readonly text: string }[]): Criterion[] {
+  return acceptance.map((criterion, index) => ({
+    id: brandSchemas.criterionId.parse(`a${index + 1}`),
+    text: criterion.text,
+    evidence: [],
+  }));
+}
+
+function buildCloseEffects(result: TriageCloseOut['result']): Effect[] {
+  return match(result)
+    .returnType<Effect[]>()
+    .with({ kind: 'accepted' }, () => [])
+    .with({ kind: 'duplicate' }, (duplicate) => [
+      { kind: 'close-item', reason: 'duplicate', of: duplicate.of },
+    ])
+    .with({ kind: 'declined' }, (declined) => [
+      { kind: 'close-item', reason: declined.reason, of: null },
+    ])
+    .exhaustive();
+}

package/src/test-utils/build-mock-noslop-report.ts

@@ -0,0 +1,30 @@
+import { brandSchemas } from '@boxxy/model';
+import { faker } from '@faker-js/faker';
+import type { NoslopReport } from '../types.ts';
+
+// A review result as noslop's schema version 7 prints it, with no findings.
+export function buildMockNoslopReport(overrides: Partial<NoslopReport> = {}): NoslopReport {
+  return {
+    version: 7,
+    reviewID: faker.string.uuid(),
+    repo: `${faker.word.noun()}/${faker.word.noun()}`,
+    pullRequest: null,
+    base: faker.git.commitSha(),
+    head: brandSchemas.commitSha.parse(faker.git.commitSha()),
+    title: faker.lorem.sentence(),
+    depth: 'standard',
+    special: null,
+    riskClasses: [],
+    lenses: [],
+    calls: [],
+    findings: [],
+    dropped: [],
+    failedCalls: [],
+    notReviewed: [],
+    notReviewedByLens: [],
+    configHash: faker.string.hexadecimal({ length: 64, casing: 'lower', prefix: '' }),
+    startedAt: '2026-11-02T10:00:00.000Z',
+    endedAt: '2026-11-02T10:04:00.000Z',
+    ...overrides,
+  };
+}

package/src/types.ts

@@ -0,0 +1,13 @@
+import type { z } from 'zod';
+import type { noslopReportSchema } from './noslop/noslop-report-schema.ts';
+
+export interface CloseOutLimits {
+  // a close-out as stored, in any phase
+  readonly closeOutBytes: 120_000;
+
+  // the most of noslop's result that a review close-out keeps whole
+  readonly noslopReportBytes: 32_768;
+}
+
+// What `noslop review --report json` printed, as the review session sends it
+export type NoslopReport = z.output<typeof noslopReportSchema>;

package/src/utils/build-criterion-texts.ts

@@ -0,0 +1,6 @@
+import type { CriterionText, ItemView } from '@boxxy/model';
+
+// The item's acceptance list as a phase input holds it: the evidence ids stay out.
+export function buildCriterionTexts(item: ItemView): CriterionText[] {
+  return item.acceptance.map((criterion) => ({ id: criterion.id, text: criterion.text }));
+}

package/src/utils/find-latest-close-out.ts

@@ -0,0 +1,20 @@
+import type { AttemptRow } from '@boxxy/model';
+import type { z } from 'zod';
+
+// The close-out of the item's latest succeeded attempt of a phase, read through the schema of
+// its body, so a stored body of another shape reads as none.
+export function findLatestCloseOut<Body>(
+  history: readonly AttemptRow[],
+  phase: string,
+  schema: z.ZodType<Body>,
+): Body | null {
+  const attempt = history.findLast((row) => row.phase === phase && row.state === 'succeeded');
+
+  if (attempt === undefined) {
+    return null;
+  }
+
+  const parsed = schema.safeParse(attempt.closeOut);
+
+  return parsed.success ? parsed.data : null;
+}

package/src/utils/find-latest-design.ts

@@ -0,0 +1,9 @@
+import type { AttemptRow, DesignRef } from '@boxxy/model';
+import { designCloseOutSchema } from '@boxxy/model';
+import { findLatestCloseOut } from './find-latest-close-out.ts';
+
+export function findLatestDesign(history: readonly AttemptRow[]): DesignRef | null {
+  const closeOut = findLatestCloseOut(history, 'design', designCloseOutSchema);
+
+  return closeOut?.result.kind === 'designed' ? closeOut.result.design : null;
+}

package/src/utils/find-pull-request-link.ts

@@ -0,0 +1,12 @@
+import type { PullRequestLink, PullRequestRow } from '@boxxy/model';
+
+// The item's latest pull request, which a build of a later round pushes to and the review reads.
+export function findPullRequestLink(
+  pullRequests: readonly PullRequestRow[],
+): PullRequestLink | null {
+  const latest = pullRequests.at(-1);
+
+  return latest === undefined
+    ? null
+    : { repo: latest.repo, number: latest.number, url: latest.url };
+}

package/dist/build-close-out-parser.d.ts

@@ -1,2 +0,0 @@
-import type { BuildCloseOut, CloseOutParser } from '@boxxy/model';
-export declare const buildCloseOutParser: CloseOutParser<BuildCloseOut>;

package/src/build-close-out-parser.ts

@@ -1,115 +0,0 @@
-import type {
-  BuildCloseOut,
-  CloseOutContext,
-  CloseOutParse,
-  CloseOutParser,
-  CloseOutProblem,
-} from '@boxxy/model';
-import { buildCloseOutSchema, formatKeyPath } from '@boxxy/model';
-import invariant from 'tiny-invariant';
-import { missingCriteria } from './missing-criteria.ts';
-
-export const buildCloseOutParser: CloseOutParser<BuildCloseOut> = { parse: parseBuildCloseOut };
-
-function parseBuildCloseOut(raw: unknown, ctx: CloseOutContext): CloseOutParse<BuildCloseOut> {
-  const split = splitFriction(raw);
-  const parsed = buildCloseOutSchema.safeParse(split.candidate);
-
-  if (!parsed.success) {
-    return {
-      kind: 'invalid',
-      problems: parsed.error.issues.map((issue) => buildSchemaProblem(issue, split.keptRawIndexes)),
-    };
-  }
-
-  const problems = collectProblems(parsed.data, ctx);
-
-  return problems.length === 0
-    ? { kind: 'valid', closeOut: parsed.data }
-    : { kind: 'invalid', problems };
-}
-
-interface FrictionSplit {
-  readonly candidate: unknown;
-  readonly keptRawIndexes: readonly number[];
-}
-
-function splitFriction(raw: unknown): FrictionSplit {
-  if (!isRecord(raw)) {
-    return { candidate: raw, keptRawIndexes: [] };
-  }
-
-  const entries: readonly unknown[] = Array.isArray(raw['friction']) ? raw['friction'] : [];
-  const keptRawIndexes = entries.flatMap((entry, index) => (isUntargeted(entry) ? [] : [index]));
-
-  const friction = Array.isArray(raw['friction'])
-    ? keptRawIndexes.map((index) => entries[index])
-    : raw['friction'];
-
-  return {
-    candidate: { ...raw, friction, frictionDropped: entries.length - keptRawIndexes.length },
-    keptRawIndexes,
-  };
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-function isUntargeted(entry: unknown): boolean {
-  return isRecord(entry) && (entry['target'] === undefined || entry['target'] === null);
-}
-
-interface SchemaIssue {
-  readonly path: readonly PropertyKey[];
-  readonly message: string;
-}
-
-function buildSchemaProblem(
-  issue: SchemaIssue,
-  keptRawIndexes: readonly number[],
-): CloseOutProblem {
-  return {
-    kind: 'schema',
-    path: formatKeyPath(toRawPath(issue.path, keptRawIndexes)),
-    message: issue.message,
-  };
-}
-
-function toRawPath(path: readonly PropertyKey[], keptRawIndexes: readonly number[]): PropertyKey[] {
-  const [field, index, ...rest] = path;
-
-  if (field !== 'friction' || typeof index !== 'number') {
-    return [...path];
-  }
-
-  const rawIndex = keptRawIndexes[index];
-
-  invariant(rawIndex !== undefined, 'a friction issue points at an entry the parser kept');
-
-  return [field, rawIndex, ...rest];
-}
-
-function collectProblems(closeOut: BuildCloseOut, ctx: CloseOutContext): CloseOutProblem[] {
-  const acceptance = new Set(ctx.item.acceptance.map((criterion) => criterion.id));
-  const own = new Set(ctx.evidence.map((row) => row.factId));
-
-  const cited = closeOut.criteria;
-
-  const unknownCriteria = new Set(
-    cited.map((entry) => entry.criterion).filter((id) => !acceptance.has(id)),
-  );
-
-  const foreignEvidence = new Set(
-    cited.map((entry) => entry.evidence).filter((id) => !own.has(id)),
-  );
-
-  const missing =
-    closeOut.result.kind === 'built' ? missingCriteria(ctx.item, ctx.evidence, cited) : [];
-
-  return [
-    ...[...unknownCriteria].map((criterion) => ({ kind: 'unknown-criterion' as const, criterion })),
-    ...[...foreignEvidence].map((evidence) => ({ kind: 'foreign-evidence' as const, evidence })),
-    ...(missing.length > 0 ? [{ kind: 'built-without-evidence' as const, criteria: missing }] : []),
-  ];
-}