@boxxy/planning 0.1.0 → 0.1.3

package/README.md

@@ -12,7 +12,8 @@
 </div>
 
 boxxy's planning. `buildFrame` runs the plug-ins of the loaded rules over a snapshot of the open
-items, and `decide` picks the next item phase for each free pool slot.
+items, and `decide` picks the wakes and the item phases that start, while each limit has a free
+seat.
 
 The package does no I/O: the caller passes in the snapshot, the loaded rules and the time.
 
@@ -31,7 +32,9 @@ The package runs on [Bun](https://bun.sh) 1.3 or newer.
 - `buildFrame`, which returns the candidates, their holds, lifts, signal values and filter-field
   values, and each plug-in fault
   ([planning: buildFrame and decide](../../docs/design/boxxy/slice-1.md#planning-buildframe-and-decide)).
-- `decide`, which picks one candidate per free slot, pool by pool, and never names a concept.
+- `decide`, which puts each wake first, then picks pool by pool while each limit that counts a pick
+  has a free seat, gives the reason for each item and wake it passes over, and never names a concept
+  ([planning: limits and the decision](../../docs/design/boxxy/planning.md#limits-and-the-decision)).
 - `concepts`, the `pool`, `defer` and `expedite` concepts
   ([the slice 1 concepts](../../docs/design/boxxy/slice-1.md#the-slice-1-concepts)).
 - `conceptPins`, each concept's pin, which the build generates from the concept's source

package/dist/concepts/defer.d.ts

@@ -1,2 +1,2 @@
 import type { Concept } from '@boxxy/model';
-export declare const deferConcept: Concept;
+export declare const defer: Concept;

package/dist/concepts/expedite.d.ts

@@ -1,2 +1,2 @@
 import type { Concept } from '@boxxy/model';
-export declare const expediteConcept: Concept;
+export declare const expedite: Concept;

package/dist/concepts/pool.d.ts

@@ -1,2 +1,2 @@
 import type { Concept } from '@boxxy/model';
-export declare const poolConcept: Concept;
+export declare const pool: Concept;

package/dist/decide.d.ts

@@ -1,8 +1,9 @@
-import type { Decision, Frame, Pool, PoolName } from '@boxxy/model';
+import type { Decision, Frame, Pool, PoolName, Snapshot } from '@boxxy/model';
 interface DecideInput {
     readonly frame: Frame;
     readonly pools: readonly Pool[];
-    readonly freeSlots: Readonly<Record<PoolName, number>>;
+    readonly snapshot: Pick<Snapshot, 'limits' | 'wakes'>;
+    readonly backoff: readonly PoolName[];
 }
 export declare function decide(input: DecideInput): Decision;
 export {};

package/dist/propagate.d.ts

@@ -1,8 +1,8 @@
-import type { Fault, FrameItem, ItemId, LinkRow, PropagationLine, Resolved, SignalKey } from '@boxxy/model';
+import type { Fault, ItemId, ItemView, PropagationLine, RelationRow, Resolved, SignalKey } from '@boxxy/model';
 interface PropagateInput {
     readonly lines: readonly PropagationLine[];
-    readonly items: readonly FrameItem[];
-    readonly links: readonly LinkRow[];
+    readonly items: readonly ItemView[];
+    readonly relations: readonly RelationRow[];
     readonly signals: ReadonlyMap<SignalKey, Resolved<'signal'>>;
     readonly values: ReadonlyMap<SignalKey, ReadonlyMap<ItemId, number>>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boxxy/planning",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "boxxy's planning: builds the frame from the plug-ins and picks the next work for each free slot",
   "homepage": "https://github.com/zgeoff/boxxy/tree/main/modules/planning#readme",
   "bugs": "https://github.com/zgeoff/boxxy/issues",
@@ -31,9 +31,9 @@
     "typecheck": "tsrs --noEmit"
   },
   "dependencies": {
-    "@boxxy/content-hash": "0.1.0",
-    "@boxxy/model": "0.1.1",
-    "@boxxy/rules": "0.1.0",
+    "@boxxy/content-hash": "0.1.3",
+    "@boxxy/model": "0.1.3",
+    "@boxxy/rules": "0.1.3",
     "tiny-invariant": "1.3.3",
     "zod": "4.6.7"
   },

package/src/build-frame.ts

@@ -7,8 +7,7 @@ import type {
   Hold,
   Instant,
   ItemId,
-  ItemKindName,
-  KindRules,
+  ItemView,
   Lift,
   LoadedRules,
   PlanContext,
@@ -29,13 +28,13 @@ interface BuildFrameInput {
 }
 
 export function buildFrame(input: BuildFrameInput): Frame {
-  const items = collectFrameItems(input.snapshot, input.rules.kinds);
-  const candidates = items.filter((item) => item.derived.state === 'ready');
+  const items = input.snapshot.items;
+  const candidates = collectCandidates(items);
 
   const buildContext = (values: FrameValues): PlanContext => ({
     now: input.now,
     levers: input.snapshot.levers,
-    links: input.snapshot.links,
+    relations: input.snapshot.relations,
     values,
   });
 
@@ -48,7 +47,7 @@ export function buildFrame(input: BuildFrameInput): Frame {
   const propagated = propagate({
     lines: input.rules.propagation,
     items,
-    links: input.snapshot.links,
+    relations: input.snapshot.relations,
     signals: input.rules.signals,
     values: new Map(carried.map((entry) => [entry.key, entry.values])),
   });
@@ -90,14 +89,17 @@ export function buildFrame(input: BuildFrameInput): Frame {
   };
 }
 
-function collectFrameItems(
-  snapshot: Snapshot,
-  kinds: ReadonlyMap<ItemKindName, KindRules>,
-): FrameItem[] {
-  return snapshot.items.flatMap((item) => {
-    const phase = kinds.get(item.kind)?.pipeline.steps[0]?.phase;
+function collectCandidates(items: readonly ItemView[]): FrameItem[] {
+  return items.flatMap((item) => {
+    if (item.derived.state !== 'ready') {
+      return [];
+    }
+
+    const position = item.position;
+
+    invariant(position.kind === 'phase', `ready item ${item.id} stands at no phase`);
 
-    return phase === undefined ? [] : [{ ...item, phase }];
+    return [{ ...item, phase: position.phase, round: position.round }];
   });
 }
 
@@ -110,7 +112,7 @@ interface SignalValues {
 function collectSignalValues(
   key: SignalKey,
   signal: Resolved<'signal'>,
-  items: readonly FrameItem[],
+  items: readonly ItemView[],
   context: PlanContext,
 ): SignalValues {
   const values = new Map<ItemId, number>();

package/src/concepts/defer.ts

@@ -4,7 +4,7 @@ import { z } from 'zod';
 
 const expediteKey = signalKey('expedite', {});
 
-export const deferConcept: Concept = {
+export const defer: Concept = {
   name: 'defer',
   version: 1,
   gates: [

package/src/concepts/expedite.ts

@@ -2,7 +2,7 @@ import type { Concept } from '@boxxy/model';
 import { defineSignal } from '@boxxy/model';
 import { z } from 'zod';
 
-export const expediteConcept: Concept = {
+export const expedite: Concept = {
   name: 'expedite',
   version: 1,
   signals: [

package/src/concepts/pool.ts

@@ -2,9 +2,9 @@ import type { Concept } from '@boxxy/model';
 import { defineSignal } from '@boxxy/model';
 import { z } from 'zod';
 
-export const poolConcept: Concept = {
+export const pool: Concept = {
   name: 'pool',
-  version: 1,
+  version: 2,
   signals: [
     defineSignal({
       name: 'oldest',
@@ -16,5 +16,8 @@ export const poolConcept: Concept = {
     { name: 'phase', value: (item) => item.phase },
     { name: 'kind', value: (item) => item.kind },
     { name: 'repo', value: (item) => item.repo },
+
+    // an item that sets no design mode runs in agent mode
+    { name: 'designMode', value: (item) => item.fields.designMode ?? 'agent' },
   ],
 };

package/src/concepts.ts

@@ -1,6 +1,6 @@
 import type { Concept } from '@boxxy/model';
-import { deferConcept } from './concepts/defer.ts';
-import { expediteConcept } from './concepts/expedite.ts';
-import { poolConcept } from './concepts/pool.ts';
+import { defer } from './concepts/defer.ts';
+import { expedite } from './concepts/expedite.ts';
+import { pool } from './concepts/pool.ts';
 
-export const concepts: readonly Concept[] = [poolConcept, deferConcept, expediteConcept];
+export const concepts: readonly Concept[] = [pool, defer, expedite];

package/src/decide.ts

@@ -1,49 +1,165 @@
-import type { Decision, Frame, FrameItem, ItemId, Pick, Pool, PoolName } from '@boxxy/model';
+import type {
+  Decision,
+  FieldValues,
+  Filter,
+  Frame,
+  FrameItem,
+  LimitFill,
+  LimitName,
+  Pool,
+  PoolName,
+  Snapshot,
+  StartPick,
+  Wait,
+  WaitReason,
+  WakePick,
+} from '@boxxy/model';
 import { compareItemIDs } from './compare-item-ids.ts';
 
 interface DecideInput {
   readonly frame: Frame;
   readonly pools: readonly Pool[];
-  readonly freeSlots: Readonly<Record<PoolName, number>>;
+  readonly snapshot: Pick<Snapshot, 'limits' | 'wakes'>;
+
+  // the pools whose capacity or usage-limit backoff runs at the claim's time
+  readonly backoff: readonly PoolName[];
 }
 
 export function decide(input: DecideInput): Decision {
-  const frame = input.frame;
+  const seats = buildSeats(input.snapshot.limits);
 
-  const picked = new Set<ItemId>();
+  const backoff = new Set(input.backoff);
 
-  const picks: Pick[] = [];
+  const picks: (StartPick | WakePick)[] = [];
+  const waits: Wait[] = [];
 
-  for (const pool of input.pools) {
-    const free = input.freeSlots[pool.name] ?? 0;
+  for (const wake of input.snapshot.wakes) {
+    const subject = { kind: 'wake', attempt: wake.attempt } as const;
+    const taken = backoff.has(wake.pool) ? backoffOf(wake.pool) : seats.take(wake.fields);
 
-    const ranked = frame.candidates
-      .filter(
-        (item) =>
-          !picked.has(item.id) &&
-          (frame.holds.get(item.id) ?? []).length === 0 &&
-          isTakenBy(pool, frame.fields.get(item.id) ?? {}),
-      )
-      .toSorted((left, right) => compareCandidates(left, right, pool, frame));
+    if (taken.kind === 'taken') {
+      picks.push({ kind: 'wake', attempt: wake.attempt, limits: taken.limits });
+    } else {
+      waits.push({ subject, reason: taken.reason });
+    }
+  }
 
-    for (const item of ranked.slice(0, free)) {
-      picked.add(item.id);
-      picks.push({ item: item.id, phase: item.phase, pool: pool.name });
+  const offered = collectOffers(input.frame, input.pools);
+
+  waits.push(...offered.unpooled);
+
+  for (const offer of offered.offers) {
+    const subject = { kind: 'item', item: offer.item.id } as const;
+    const taken = backoff.has(offer.pool) ? backoffOf(offer.pool) : seats.take(offer.fields);
+
+    if (taken.kind === 'taken') {
+      picks.push({
+        kind: 'start',
+        item: offer.item.id,
+        phase: offer.item.phase,
+        round: offer.item.round,
+        pool: offer.pool,
+        fields: offer.fields,
+        limits: taken.limits,
+      });
+    } else {
+      waits.push({ subject, reason: taken.reason });
     }
   }
 
-  return { picks };
+  return { picks, waits };
+}
+
+type SeatTaking =
+  | { readonly kind: 'taken'; readonly limits: readonly LimitName[] }
+  | { readonly kind: 'refused'; readonly reason: WaitReason };
+
+interface Seats {
+  take: (fields: FieldValues) => SeatTaking;
 }
 
-function isTakenBy(pool: Pool, fields: Readonly<Record<string, readonly string[]>>): boolean {
-  return Object.entries(pool.takes).every(([field, accepted]) =>
+// The free seats of each limit, counted down by each pick of this decision. A limit held over its
+// max after a wake over the cap has fewer than none.
+function buildSeats(limits: readonly LimitFill[]): Seats {
+  const free = new Map(limits.map((limit) => [limit.name, limit.max - limit.held]));
+
+  return {
+    take: (fields) => {
+      const counting = limits.filter((limit) => isMatch(limit.counts, fields));
+      const full = counting.find((limit) => (free.get(limit.name) ?? 0) <= 0);
+
+      if (full !== undefined) {
+        return { kind: 'refused', reason: { kind: 'limit-full', limit: full.name } };
+      }
+
+      for (const limit of counting) {
+        free.set(limit.name, (free.get(limit.name) ?? 0) - 1);
+      }
+
+      return { kind: 'taken', limits: counting.map((limit) => limit.name) };
+    },
+  };
+}
+
+// An item matches a filter when, for every field, one of its values is in the filter's list.
+function isMatch(filter: Filter, fields: FieldValues): boolean {
+  return Object.entries(filter).every(([field, accepted]) =>
     (fields[field] ?? []).some((value) => accepted.includes(value)),
   );
 }
 
-function compareCandidates(left: FrameItem, right: FrameItem, pool: Pool, frame: Frame): number {
+function backoffOf(pool: PoolName): SeatTaking {
+  return { kind: 'refused', reason: { kind: 'backoff', pool } };
+}
+
+interface Offer {
+  readonly item: FrameItem;
+  readonly pool: PoolName;
+  readonly fields: FieldValues;
+}
+
+interface Offers {
+  // in pool order, then by each pool's `order`
+  readonly offers: readonly Offer[];
+  readonly unpooled: readonly Wait[];
+}
+
+// Each candidate that no gate holds belongs to the first pool, in declared order, that takes it.
+function collectOffers(frame: Frame, pools: readonly Pool[]): Offers {
+  const free = frame.candidates.filter((item) => (frame.holds.get(item.id) ?? []).length === 0);
+
+  const byPool = new Map<PoolName, FrameItem[]>(pools.map((pool) => [pool.name, []]));
+
+  const unpooled: Wait[] = [];
+
+  for (const item of free) {
+    const fields = frame.fields.get(item.id) ?? {};
+    const pool = pools.find((candidate) => isMatch(candidate.takes, fields));
+
+    if (pool === undefined) {
+      unpooled.push({ subject: { kind: 'item', item: item.id }, reason: { kind: 'no-pool' } });
+    } else {
+      byPool.get(pool.name)?.push(item);
+    }
+  }
+
+  const offers = pools.flatMap((pool) =>
+    (byPool.get(pool.name) ?? [])
+      .toSorted((left, right) => compareCandidates(left, right, pool, frame.values))
+      .map((item) => ({ item, pool: pool.name, fields: frame.fields.get(item.id) ?? {} })),
+  );
+
+  return { offers, unpooled };
+}
+
+function compareCandidates(
+  left: FrameItem,
+  right: FrameItem,
+  pool: Pool,
+  values: Frame['values'],
+): number {
   for (const key of pool.order) {
-    const byItem = frame.values.get(key);
+    const byItem = values.get(key);
     const order = compareValues(byItem?.get(left.id), byItem?.get(right.id));
 
     if (order !== 0) {

package/src/generated/concept-pins.ts

@@ -8,7 +8,7 @@ export const conceptPins: ReadonlyMap<ConceptName, ConceptPin> = new Map([
     {
       ref: 'defer@1',
       sourceHash: contentHashSchema.parse(
-        '465c5e5376b2de6814f08888cd479249e494d1986802aa6293e2495b88e846d9',
+        'cbe173e108ca3b290f7f48ea3a4145b28f44611ae7f4a43d29430f08b88f46df',
       ),
     },
   ],
@@ -17,16 +17,16 @@ export const conceptPins: ReadonlyMap<ConceptName, ConceptPin> = new Map([
     {
       ref: 'expedite@1',
       sourceHash: contentHashSchema.parse(
-        '672b566d996e4b8d1aeb6e9e768460726473d6f0181a0eedcf09494687679882',
+        'f75e37b479e49da4e68aab6f3d8e9960b04608eb7a9fdd53d4349578e1c213d3',
       ),
     },
   ],
   [
     'pool',
     {
-      ref: 'pool@1',
+      ref: 'pool@2',
       sourceHash: contentHashSchema.parse(
-        '93bb6fefe3cf95fc8a15bbe9381733427ba34c2118626449c7828929f895b984',
+        '1631a22966bd50fa39a8acc79f242fb0ac6603ead15b8f4ca3907f5e2cdd1214',
       ),
     },
   ],

package/src/propagate.ts

@@ -1,9 +1,9 @@
 import type {
   Fault,
-  FrameItem,
   ItemId,
-  LinkRow,
+  ItemView,
   PropagationLine,
+  RelationRow,
   Resolved,
   SignalKey,
 } from '@boxxy/model';
@@ -14,8 +14,8 @@ import { formatFault } from './format-fault.ts';
 
 interface PropagateInput {
   readonly lines: readonly PropagationLine[];
-  readonly items: readonly FrameItem[];
-  readonly links: readonly LinkRow[];
+  readonly items: readonly ItemView[];
+  readonly relations: readonly RelationRow[];
   readonly signals: ReadonlyMap<SignalKey, Resolved<'signal'>>;
   readonly values: ReadonlyMap<SignalKey, ReadonlyMap<ItemId, number>>;
 }
@@ -44,7 +44,7 @@ export function propagate(input: PropagateInput): Propagated {
     try {
       const start = values.get(key) ?? new Map<ItemId, number>();
 
-      values.set(key, carryLine(line, combine, start, { open, links: input.links }));
+      values.set(key, carryLine(line, combine, start, { open, relations: input.relations }));
     } catch (error) {
       faults.push({
         plugin: `propagation:${line.value}:${line.over}`,
@@ -70,7 +70,7 @@ function getCombine(signals: PropagateInput['signals'], key: SignalKey): Combine
 
 interface LineGraph {
   readonly open: ReadonlySet<ItemId>;
-  readonly links: readonly LinkRow[];
+  readonly relations: readonly RelationRow[];
 }
 
 function carryLine(
@@ -79,7 +79,7 @@ function carryLine(
   start: ReadonlyMap<ItemId, number>,
   graph: LineGraph,
 ): Map<ItemId, number> {
-  const next = collectNeighbours(line, graph.links);
+  const next = collectNeighbours(line, graph.relations);
 
   const carried = new Map(start);
 
@@ -112,13 +112,15 @@ function carryLine(
 
 function collectNeighbours(
   line: PropagationLine,
-  links: readonly LinkRow[],
+  relations: readonly RelationRow[],
 ): Map<ItemId, ItemId[]> {
   const next = new Map<ItemId, ItemId[]>();
 
-  for (const link of links.filter((candidate) => candidate.type === line.over)) {
+  for (const relation of relations.filter((candidate) => candidate.type === line.over)) {
     const [from, to] =
-      line.toward === 'source' ? [link.target, link.source] : [link.source, link.target];
+      line.toward === 'source'
+        ? [relation.target, relation.source]
+        : [relation.source, relation.target];
 
     const neighbours = next.get(from) ?? [];
 

package/src/test-utils/build-mock-loaded-rules.ts

@@ -1,5 +1,6 @@
 import { contentHash } from '@boxxy/content-hash';
 import type { Concept, ConceptPin, JsonValue, LoadedRules } from '@boxxy/model';
+import { buildMockPhaseKind } from '@boxxy/model/test-utils/build-mock-phase-kind';
 import { loadRules } from '@boxxy/rules';
 import invariant from 'tiny-invariant';
 import { concepts as builtInConcepts } from '../concepts.ts';
@@ -17,20 +18,14 @@ export function buildMockLoadedRules(input: MockRulesInput = {}): LoadedRules {
   const file = {
     version: 1,
     concepts: concepts.map((concept) => `${concept.name}@${concept.version}`),
-    kinds: {
-      'core.issue': {
-        pipeline: ['build'],
-        maxAttempts: { build: 2 },
-        recipes: { build: 'build-v1' },
-      },
+    pipelines: {
+      standard: [{ phase: 'build', maxAttempts: 2, timeoutMinutes: 180, on: { built: 'next' } }],
     },
+    kinds: { 'core.issue': { pipeline: 'standard', recipes: { build: 'build-v1' } } },
+    relationTypes: ['blocks'],
+    limits: [{ name: 'workers', max: 7, counts: {} }],
     pools: input.pools ?? [
-      {
-        name: 'build',
-        slots: 2,
-        takes: { phase: 'build', kind: ['core.issue'] },
-        order: ['oldest'],
-      },
+      { name: 'build', takes: { phase: 'build', kind: ['core.issue'] }, order: ['oldest'] },
     ],
     lead: input.lead ?? ['expedite'],
     propagation: input.propagation ?? [{ value: 'expedite', over: 'blocks', toward: 'source' }],
@@ -41,8 +36,10 @@ export function buildMockLoadedRules(input: MockRulesInput = {}): LoadedRules {
         effort: 'high',
         prompt: 'prompts/build-v1.md',
         source: 'subscription',
+        skills: [],
       },
     },
+    sleep: { afterIdleMinutes: 30, afterQuietMinutes: 60, afterUnattendedMinutes: 240 },
   };
 
   const encoder = new TextEncoder();
@@ -68,6 +65,7 @@ export function buildMockLoadedRules(input: MockRulesInput = {}): LoadedRules {
     },
     concepts,
     pins: new Map(pins),
+    phases: [buildMockPhaseKind({ name: 'build', outcomes: ['built'] })],
   });
 
   invariant(