@boxxy/rules 0.1.0 → 0.1.4

package/src/loading/collect-step-rejections.ts

@@ -0,0 +1,131 @@
+import type { LoadRejection, PhaseKind, PhaseName } from '@boxxy/model';
+import { engineHoldReasons, engineOutcomes } from '@boxxy/model';
+import { P, match } from 'ts-pattern';
+import type { ParsedRulesFile, ParsedStep } from '../parse/rules-file-schema.ts';
+import { buildRejection } from './build-rejection.ts';
+
+export function collectStepRejections(
+  file: ParsedRulesFile,
+  phases: ReadonlyMap<PhaseName, PhaseKind>,
+): LoadRejection[] {
+  return Object.entries(file.pipelines).flatMap(([pipeline, steps]) =>
+    steps.flatMap((step, index) => {
+      const path = ['pipelines', pipeline, index];
+      const phase = phases.get(step.phase);
+
+      return [
+        ...(phase === undefined
+          ? [buildRejection([...path, 'phase'], { kind: 'unknown-phase', phase: step.phase })]
+          : collectOutcomeRejections(step, phase, path)),
+        ...(step.timeoutMinutes === undefined
+          ? [buildRejection(path, { kind: 'step-without-timeout', phase: step.phase })]
+          : []),
+        ...Object.entries(step.on).flatMap(([outcome, edge]) =>
+          collectEdgeRejections(edge, {
+            steps,
+            index,
+            phase: step.phase,
+            outcome,
+            path: [...path, 'on', outcome],
+          }),
+        ),
+      ];
+    }),
+  );
+}
+
+function collectOutcomeRejections(
+  step: ParsedStep,
+  phase: PhaseKind,
+  path: readonly PropertyKey[],
+): LoadRejection[] {
+  const listed: readonly string[] = phase.outcomes;
+
+  return [
+    ...engineOutcomes
+      .filter((outcome) => listed.includes(outcome))
+      .map((outcome) =>
+        buildRejection([...path, 'phase'], {
+          kind: 'engine-outcome-listed',
+          phase: step.phase,
+          outcome,
+        }),
+      ),
+    ...listed
+      .filter((outcome) => !Object.hasOwn(step.on, outcome))
+      .map((outcome) =>
+        buildRejection([...path, 'on'], { kind: 'unmapped-outcome', phase: step.phase, outcome }),
+      ),
+    ...Object.keys(step.on)
+      .filter((outcome) => !listed.includes(outcome))
+      .map((outcome) =>
+        buildRejection([...path, 'on', outcome], {
+          kind: 'unknown-outcome',
+          phase: step.phase,
+          outcome,
+        }),
+      ),
+  ];
+}
+
+type ParsedEdge = ParsedStep['on'][string];
+
+interface EdgeContext {
+  readonly steps: readonly ParsedStep[];
+  readonly index: number;
+  readonly phase: PhaseName;
+  readonly outcome: string;
+  readonly path: readonly PropertyKey[];
+}
+
+function collectEdgeRejections(edge: ParsedEdge, context: EdgeContext): LoadRejection[] {
+  const engineReasons: readonly string[] = engineHoldReasons;
+
+  return match(edge)
+    .with(P.string, { end: P.string }, () => [])
+    .with({ hold: P.string }, (held) =>
+      engineReasons.includes(held.hold)
+        ? [
+            buildRejection([...context.path, 'hold'], {
+              kind: 'engine-hold-reason',
+              phase: context.phase,
+              outcome: context.outcome,
+              reason: held.hold,
+            }),
+          ]
+        : [],
+    )
+    .with({ to: P.string }, (jump) => collectJumpRejections(jump, context))
+    .exhaustive();
+}
+
+function collectJumpRejections(
+  jump: Extract<ParsedEdge, { to: string }>,
+  context: EdgeContext,
+): LoadRejection[] {
+  const target = context.steps.findIndex((step) => step.phase === jump.to);
+  const edge = { phase: context.phase, outcome: context.outcome };
+
+  if (target === -1) {
+    return [
+      buildRejection(context.path, {
+        kind: 'edge-to-unknown-phase',
+        phase: context.phase,
+        to: jump.to,
+      }),
+    ];
+  }
+
+  // an edge to its own step loops, as a backward edge does
+  const isBack = target <= context.index;
+
+  if (isBack && jump.max === undefined) {
+    return [buildRejection(context.path, { kind: 'open-loop', ...edge })];
+  }
+
+  if (!isBack && jump.resume === true) {
+    return [buildRejection(context.path, { kind: 'resume-on-forward-edge', ...edge })];
+  }
+
+  return [];
+}

package/src/{load-rules.ts → loading/load-rules.ts}

@@ -6,25 +6,36 @@ import type {
   ConceptPin,
   ItemKindName,
   KindRules,
+  Limit,
   LoadRejection,
   LoadResult,
-  LoadedRecipe,
+  PhaseKind,
+  PhaseName,
+  Pipeline,
+  PipelineStep,
   Pool,
+  RecipeMaterial,
   RecipeName,
+  RelationType,
+  RelationTypeName,
   RulesVersion,
 } from '@boxxy/model';
 import { brandSchemas } from '@boxxy/model';
 import invariant from 'tiny-invariant';
 import { match } from 'ts-pattern';
-import { buildRegistry } from './build-registry.ts';
+import { rulesFileName } from '../constants.ts';
+import { parseConceptEntry } from '../parse/parse-concept-entry.ts';
+import { parseRulesFile } from '../parse/parse-rules-file.ts';
+import type { ParsedRulesFile, ParsedStep } from '../parse/rules-file-schema.ts';
+import { buildRegistry } from '../registry/build-registry.ts';
+import { resolvePlugin } from '../registry/resolve-plugin.ts';
+import { resolveSignalRef } from '../registry/resolve-signal-ref.ts';
+import type { Checked, PinnedConcept, ResolvedSignal } from '../types.ts';
 import { buildRejection } from './build-rejection.ts';
-import { rulesFileName } from './constants.ts';
-import { parseConceptEntry } from './parse-concept-entry.ts';
-import { parseRulesFile } from './parse-rules-file.ts';
-import { resolvePlugin } from './resolve-plugin.ts';
-import { resolveSignalRef } from './resolve-signal-ref.ts';
-import type { ParsedRulesFile } from './rules-file-schema.ts';
-import type { Checked, PinnedConcept, ResolvedSignal } from './types.ts';
+import { collectFilterRejections } from './collect-filter-rejections.ts';
+import { collectRecipeRejections } from './collect-recipe-rejections.ts';
+import { collectStepRejections } from './collect-step-rejections.ts';
+import { toFilter } from './to-filter.ts';
 
 interface LoadRulesInput {
   readonly checkout: {
@@ -33,6 +44,9 @@ interface LoadRulesInput {
   };
   readonly concepts: readonly Concept[];
   readonly pins: ReadonlyMap<ConceptName, ConceptPin>;
+
+  // the phase kinds the server registers, as it registers the concepts
+  readonly phases: readonly PhaseKind[];
 }
 
 export function loadRules(input: LoadRulesInput): LoadResult {
@@ -66,6 +80,7 @@ function buildLoadResult(
   );
 
   const registry = built.value;
+  const phases = buildPhases(input.phases);
   const lead = file.lead.map((ref, index) => resolveSignalRef(ref, ['lead', index], registry));
 
   const pools = file.pools.map((pool, poolIndex) => ({
@@ -93,7 +108,10 @@ function buildLoadResult(
     ...built.rejections,
     ...[...signals, ...gates].flatMap((checked) => checked.rejections),
     ...collectPropagationRejections(file, propagation),
-    ...collectMissingRecipes(file),
+    ...collectStepRejections(file, phases),
+    ...collectRecipeRejections(file),
+    ...collectFilterRejections(file, registry),
+    ...collectSleepRejections(file),
     ...prompts.rejections,
   ];
 
@@ -101,9 +119,9 @@ function buildLoadResult(
     return { kind: 'rejected', rejections };
   }
 
-  const version = buildRulesVersion(
-    input.checkout.commit,
-    [
+  const version = buildRulesVersion({
+    commit: input.checkout.commit,
+    files: [
       { path: rulesFileName, bytes: rulesBytes, executable: false },
       ...prompts.value.map((prompt) => ({
         path: prompt.recipe.prompt,
@@ -111,11 +129,11 @@ function buildLoadResult(
         executable: false,
       })),
     ],
-    registry.pins,
-  );
+    pins: registry.pins,
+    phases: input.phases,
+  });
 
   const leadKeys = lead.map((checked) => getValue(checked).key);
-  const kinds = buildKinds(file);
 
   return {
     kind: 'loaded',
@@ -127,22 +145,21 @@ function buildLoadResult(
         signals.map((checked) => [getValue(checked).key, getValue(checked).resolved]),
       ),
       gates: gates.map((checked) => getValue(checked)),
-      kinds,
-      maxAttemptsByKind: new Map(
-        [...kinds].map(([kind, kindRules]) => [
-          kind,
-          new Map(kindRules.pipeline.steps.map((step) => [step.phase, step.maxAttempts])),
-        ]),
-      ),
+      kinds: buildKinds(file),
+      phases,
+      limits: file.limits.map((limit): Limit => ({
+        name: limit.name,
+        max: limit.max,
+        counts: toFilter(limit.counts),
+      })),
       pools: pools.map((entry): Pool => ({
         name: entry.pool.name,
-        slots: entry.pool.slots,
-        takes: buildTakes(entry.pool.takes),
+        takes: toFilter(entry.pool.takes),
         order: [...new Set([...leadKeys, ...entry.order.map((checked) => getValue(checked).key)])],
       })),
       propagation: file.propagation,
       recipes: new Map(
-        prompts.value.map((prompt): [RecipeName, LoadedRecipe] => [
+        prompts.value.map((prompt): [RecipeName, RecipeMaterial] => [
           prompt.name,
           {
             name: prompt.name,
@@ -152,6 +169,11 @@ function buildLoadResult(
           },
         ]),
       ),
+      sleep: file.sleep,
+      skills: file.skills ?? null,
+      relationTypes: new Map(
+        file.relationTypes.map((name): [RelationTypeName, RelationType] => [name, { name }]),
+      ),
     },
     warnings: [],
   };
@@ -192,6 +214,14 @@ function getPin(pins: ReadonlyMap<ConceptName, ConceptPin>, concept: Concept): C
   return pin;
 }
 
+function buildPhases(phases: readonly PhaseKind[]): ReadonlyMap<PhaseName, PhaseKind> {
+  const byName = new Map(phases.map((phase) => [phase.name, phase]));
+
+  invariant(byName.size === phases.length, 'the server registers each phase kind once');
+
+  return byName;
+}
+
 interface RecipePrompt {
   readonly name: RecipeName;
   readonly recipe: ParsedRulesFile['recipes'][RecipeName];
@@ -223,21 +253,21 @@ function collectPrompts(
   return { value: prompts, rejections };
 }
 
-const knownLinkTypes: ReadonlySet<string> = new Set(['blocks']);
-
 function collectPropagationRejections(
   file: ParsedRulesFile,
   signals: readonly Checked<ResolvedSignal>[],
 ): LoadRejection[] {
+  const relationTypes: ReadonlySet<string> = new Set(file.relationTypes);
+
   return file.propagation.flatMap((line, index) => {
     const rejections: LoadRejection[] = [];
     const signal = signals[index]?.value ?? null;
 
-    if (!knownLinkTypes.has(line.over)) {
+    if (!relationTypes.has(line.over)) {
       rejections.push(
         buildRejection(['propagation', index, 'over'], {
-          kind: 'unknown-link-type',
-          link: line.over,
+          kind: 'unknown-relation-type',
+          relation: line.over,
         }),
       );
     }
@@ -255,34 +285,35 @@ function collectPropagationRejections(
   });
 }
 
-function collectMissingRecipes(file: ParsedRulesFile): LoadRejection[] {
-  return Object.entries(file.kinds).flatMap(([itemKind, kind]) =>
-    kind.pipeline
-      .filter(
-        (phase) =>
-          !Object.hasOwn(kind.recipes, phase) ||
-          !Object.hasOwn(file.recipes, kind.recipes[phase] ?? ''),
-      )
-      .map((phase) =>
-        buildRejection(['kinds', itemKind, 'recipes', phase], {
-          kind: 'missing-recipe',
-          itemKind,
-          phase,
-        }),
-      ),
-  );
+function collectSleepRejections(file: ParsedRulesFile): LoadRejection[] {
+  const sleep = file.sleep;
+
+  return [
+    ...(sleep.afterQuietMinutes < sleep.afterIdleMinutes
+      ? [buildRejection(['sleep', 'afterQuietMinutes'], { kind: 'quiet-below-idle' })]
+      : []),
+    ...(sleep.afterUnattendedMinutes < sleep.afterQuietMinutes
+      ? [buildRejection(['sleep', 'afterUnattendedMinutes'], { kind: 'unattended-below-quiet' })]
+      : []),
+  ];
+}
+
+interface RulesVersionInput {
+  readonly commit: string;
+  readonly files: readonly TreeFile[];
+  readonly pins: readonly ConceptPin[];
+  readonly phases: readonly PhaseKind[];
 }
 
-function buildRulesVersion(
-  commit: string,
-  files: readonly TreeFile[],
-  pins: readonly ConceptPin[],
-): RulesVersion {
+// A replay needs the exact plug-in code, so each concept pin and each phase kind's version are
+// part of the version.
+function buildRulesVersion(input: RulesVersionInput): RulesVersion {
   return brandSchemas.rulesVersion.parse(
     contentHash({
-      commit,
-      files: hashTree(files),
-      pins: pins.map((pin) => ({ ref: pin.ref, sourceHash: pin.sourceHash })),
+      commit: input.commit,
+      files: hashTree(input.files),
+      pins: input.pins.map((pin) => ({ ref: pin.ref, sourceHash: pin.sourceHash })),
+      phases: input.phases.map((phase) => `${phase.name}@${phase.version}`).toSorted(),
     }),
   );
 }
@@ -294,27 +325,34 @@ function getValue<T>(checked: Checked<T>): T {
 }
 
 function buildKinds(file: ParsedRulesFile): ReadonlyMap<ItemKindName, KindRules> {
-  return new Map(
-    Object.entries(file.kinds).map(([name, kind]): [ItemKindName, KindRules] => [
-      brandSchemas.itemKindName.parse(name),
-      {
-        pipeline: {
-          name: brandSchemas.pipelineName.parse(name),
-          steps: kind.steps,
-        },
-        recipes: kind.recipes,
-      },
+  const pipelines = new Map(
+    Object.entries(file.pipelines).map(([name, steps]): [string, Pipeline] => [
+      name,
+      { name: brandSchemas.pipelineName.parse(name), steps: steps.map((step) => buildStep(step)) },
     ]),
   );
-}
 
-function buildTakes(
-  takes: ParsedRulesFile['pools'][number]['takes'],
-): Readonly<Record<string, readonly string[]>> {
-  return Object.fromEntries(
-    Object.entries(takes).map(([field, value]) => [
-      field,
-      typeof value === 'string' ? [value] : value,
-    ]),
+  return new Map(
+    Object.entries(file.kinds).map(([name, kind]): [ItemKindName, KindRules] => {
+      const pipeline = pipelines.get(kind.pipeline);
+
+      invariant(
+        pipeline,
+        `the rules file schema refuses the kind ${name}, whose pipeline is missing`,
+      );
+
+      return [brandSchemas.itemKindName.parse(name), { pipeline, recipes: kind.recipes }];
+    }),
   );
 }
+
+function buildStep(step: ParsedStep): PipelineStep {
+  invariant(step.timeoutMinutes !== undefined, 'the loader refuses a step with no time limit');
+
+  return {
+    phase: step.phase,
+    maxAttempts: step.maxAttempts,
+    timeoutMinutes: step.timeoutMinutes,
+    on: step.on,
+  };
+}

package/src/loading/to-filter.ts

@@ -0,0 +1,12 @@
+import type { Filter } from '@boxxy/model';
+import type { ParsedRulesFile } from '../parse/rules-file-schema.ts';
+
+// a filter in the rules file may give one value as a bare string; a loaded filter always holds a list
+export function toFilter(filter: ParsedRulesFile['pools'][number]['takes']): Filter {
+  return Object.fromEntries(
+    Object.entries(filter).map(([field, value]) => [
+      field,
+      typeof value === 'string' ? [value] : value,
+    ]),
+  );
+}

package/src/parse/rules-file-schema.ts

@@ -0,0 +1,177 @@
+import type { Effort } from '@boxxy/model';
+import { brandSchemas } from '@boxxy/model';
+import { z } from 'zod';
+import { parseConceptEntry } from './parse-concept-entry.ts';
+
+const nameSchema = z.string().min(1);
+
+const pluginRefSchema = z.union([
+  nameSchema,
+  z.record(nameSchema, z.json()).refine((ref) => Object.keys(ref).length === 1, {
+    message: 'a plug-in reference with parameters is a map with one key, the plug-in name',
+  }),
+]);
+
+const edgeSchema = z.union([
+  z.literal('next'),
+  z.literal('again'),
+  z.strictObject({
+    to: brandSchemas.phaseName,
+    max: z.int().positive().exactOptional(),
+    resume: z.boolean().exactOptional(),
+  }),
+  z.strictObject({ end: nameSchema }),
+  z.strictObject({ hold: brandSchemas.rulesHoldReason }),
+]);
+
+// `timeoutMinutes` is optional here so that the loader refuses a step without it by its own reason
+const stepSchema = z.strictObject({
+  phase: brandSchemas.phaseName,
+  maxAttempts: z.int().positive(),
+  timeoutMinutes: z.int().positive().optional(),
+  on: z.record(nameSchema, edgeSchema),
+});
+
+const kindSchema = z.strictObject({
+  pipeline: brandSchemas.pipelineName,
+
+  // by phase, and by `<phase>/attended` for an attended session of the phase
+  recipes: z.record(nameSchema, brandSchemas.recipeName),
+});
+
+const filterSchema = z.record(nameSchema, z.union([nameSchema, z.array(nameSchema).min(1)]));
+
+const limitSchema = z.strictObject({
+  name: brandSchemas.limitName,
+  max: z.int().positive(),
+  counts: filterSchema,
+});
+
+const poolSchema = z.strictObject({
+  name: brandSchemas.poolName,
+  slots: z.never({ error: 'a pool has no slot count; a limit caps its attempts' }).optional(),
+  takes: filterSchema,
+  order: z.array(pluginRefSchema),
+});
+
+const efforts = ['low', 'medium', 'high', 'xhigh', 'max'] as const satisfies readonly Effort[];
+
+const recipeSchema = z.strictObject({
+  agent: nameSchema,
+  model: nameSchema,
+  effort: z.enum(efforts),
+  prompt: nameSchema.refine(isCheckoutPath, {
+    message: 'a prompt path runs from the checkout root, with no empty, "." or ".." folder',
+  }),
+  source: brandSchemas.sourceName,
+  skills: z.array(nameSchema),
+});
+
+const skillsPinSchema = z.strictObject({
+  source: brandSchemas.repoName,
+  ref: brandSchemas.commitSha,
+});
+
+const conceptEntrySchema = z.templateLiteral([nameSchema, '@', z.int().positive()]);
+
+const propagationLineSchema = z.strictObject({
+  value: nameSchema,
+  over: brandSchemas.relationTypeName,
+  toward: z.enum(['source', 'target']),
+});
+
+const minutesSchema = z.int().positive();
+
+export const rulesFileSchema = z
+  .strictObject({
+    version: z.literal(1),
+    concepts: z.array(conceptEntrySchema),
+    pipelines: z.record(brandSchemas.pipelineName, z.array(stepSchema).min(1)),
+    kinds: z.record(brandSchemas.itemKindName, kindSchema),
+    skills: skillsPinSchema.optional(),
+    relationTypes: z.array(brandSchemas.relationTypeName),
+    recipes: z.record(brandSchemas.recipeName, recipeSchema),
+    limits: z.array(limitSchema),
+    pools: z.array(poolSchema),
+    lead: z.array(pluginRefSchema).default([]),
+    propagation: z.array(propagationLineSchema).default([]),
+    sleep: z.strictObject({
+      afterIdleMinutes: minutesSchema,
+      afterQuietMinutes: minutesSchema,
+      afterUnattendedMinutes: minutesSchema,
+    }),
+  })
+  .superRefine((file, ctx) => {
+    for (const issue of [
+      ...collectRepeats(
+        file.concepts.map((entry) => parseConceptEntry(entry).name),
+        ['concepts'],
+        [],
+        (name) => `the concept ${name} is pinned twice`,
+      ),
+      ...collectRepeats(
+        file.pools.map((pool) => pool.name),
+        ['pools'],
+        ['name'],
+        (name) => `the pool name ${name} is used twice`,
+      ),
+      ...collectRepeats(
+        file.limits.map((limit) => limit.name),
+        ['limits'],
+        ['name'],
+        (name) => `the limit name ${name} is used twice`,
+      ),
+      ...collectRepeats(
+        file.relationTypes,
+        ['relationTypes'],
+        [],
+        (name) => `the relation type ${name} is listed twice`,
+      ),
+      ...Object.entries(file.pipelines).flatMap(([pipeline, steps]) =>
+        collectRepeats(
+          steps.map((step) => step.phase),
+          ['pipelines', pipeline],
+          ['phase'],
+          (phase) => `the pipeline ${pipeline} names the phase ${phase} twice`,
+        ),
+      ),
+      ...Object.entries(file.kinds).flatMap(([kind, rules]) =>
+        Object.hasOwn(file.pipelines, rules.pipeline)
+          ? []
+          : [
+              {
+                path: ['kinds', kind, 'pipeline'],
+                message: `the file has no pipeline ${rules.pipeline}`,
+              },
+            ],
+      ),
+    ]) {
+      ctx.addIssue({ code: 'custom', ...issue });
+    }
+  });
+
+export type ParsedRulesFile = z.output<typeof rulesFileSchema>;
+
+export type ParsedStep = z.output<typeof stepSchema>;
+
+function isCheckoutPath(path: string): boolean {
+  return path.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..');
+}
+
+interface FileIssue {
+  readonly path: PropertyKey[];
+  readonly message: string;
+}
+
+function collectRepeats(
+  names: readonly string[],
+  listPath: readonly PropertyKey[],
+  itemPath: readonly PropertyKey[],
+  formatMessage: (name: string) => string,
+): FileIssue[] {
+  return names.flatMap((name, index) =>
+    names.indexOf(name) === index
+      ? []
+      : [{ path: [...listPath, index, ...itemPath], message: formatMessage(name) }],
+  );
+}

package/src/{build-registry.ts → registry/build-registry.ts}

@@ -1,6 +1,6 @@
 import type { ConceptPin, LoadRejection, Registry } from '@boxxy/model';
-import { buildRejection } from './build-rejection.ts';
-import type { PinnedConcept } from './types.ts';
+import { buildRejection } from '../loading/build-rejection.ts';
+import type { PinnedConcept } from '../types.ts';
 
 export function buildRegistry(
   pinned: readonly PinnedConcept[],

package/src/{resolve-plugin.ts → registry/resolve-plugin.ts}

@@ -2,8 +2,8 @@ import type { JsonValue } from '@boxxy/content-hash';
 import type { ParamKindName, Registered, Resolved } from '@boxxy/model';
 import { formatKeyPath } from '@boxxy/model';
 import type { z } from 'zod';
-import { buildRejection } from './build-rejection.ts';
-import type { Checked } from './types.ts';
+import { buildRejection } from '../loading/build-rejection.ts';
+import type { Checked } from '../types.ts';
 
 export function resolvePlugin<K extends ParamKindName>(
   registered: Registered<K>,

package/src/{resolve-signal-ref.ts → registry/resolve-signal-ref.ts}

@@ -2,9 +2,9 @@ import type { JsonValue } from '@boxxy/content-hash';
 import type { Registry, SignalRef } from '@boxxy/model';
 import { signalKey } from '@boxxy/model';
 import invariant from 'tiny-invariant';
-import { buildRejection } from './build-rejection.ts';
+import { buildRejection } from '../loading/build-rejection.ts';
+import type { Checked, ResolvedSignal } from '../types.ts';
 import { resolvePlugin } from './resolve-plugin.ts';
-import type { Checked, ResolvedSignal } from './types.ts';
 
 export function resolveSignalRef(
   ref: SignalRef,