@boxxy/planning 0.0.0-stage → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the boxxy authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+<div align="center">
+  <h1>@boxxy/planning</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+  <p>
+    <a href="https://www.npmjs.com/package/@boxxy/planning"><img src="https://img.shields.io/npm/v/@boxxy/planning" alt="npm version"></a>
+    <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+  </p>
+
+  <p>
+    <a href="../../docs/design/boxxy/README.md">Documentation</a>
+  </p>
+</div>
+
+boxxy's planning. `buildFrame` runs the plug-ins of the loaded rules over a snapshot of the open
+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.
+
+## Install
+
+Install the package from [npm](https://www.npmjs.com/package/@boxxy/planning) with Bun:
+
+```bash
+bun add @boxxy/planning
+```
+
+The package runs on [Bun](https://bun.sh) 1.3 or newer.
+
+## Features
+
+- `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 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
+  ([rules for slice 1](../../docs/design/boxxy/slice-1.md#rules-for-slice-1)).
+
+## Documentation
+
+The [planning design](../../docs/design/boxxy/planning.md) says why concepts are plug-ins, and
+[`04-planning.ts`](../../docs/design/boxxy/sketches/04-planning.ts) gives the shapes.

package/dist/build-frame.d.ts

@@ -0,0 +1,8 @@
+import type { Frame, Instant, LoadedRules, Snapshot } from '@boxxy/model';
+interface BuildFrameInput {
+    readonly snapshot: Snapshot;
+    readonly rules: LoadedRules;
+    readonly now: Instant;
+}
+export declare function buildFrame(input: BuildFrameInput): Frame;
+export {};

package/dist/compare-item-ids.d.ts

@@ -0,0 +1,2 @@
+import type { ItemId } from '@boxxy/model';
+export declare function compareItemIDs(left: ItemId, right: ItemId): number;

package/dist/concepts/defer.d.ts

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

package/dist/concepts/expedite.d.ts

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

package/dist/concepts/pool.d.ts

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

package/dist/concepts.d.ts

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

package/dist/decide.d.ts

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

package/dist/format-fault.d.ts

@@ -0,0 +1 @@
+export declare function formatFault(error: unknown): string;

package/dist/generated/concept-pins.d.ts

@@ -0,0 +1,2 @@
+import type { ConceptName, ConceptPin } from '@boxxy/model';
+export declare const conceptPins: ReadonlyMap<ConceptName, ConceptPin>;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { buildFrame } from './build-frame.ts';
+export { concepts } from './concepts.ts';
+export { decide } from './decide.ts';
+export { conceptPins } from './generated/concept-pins.ts';

package/dist/propagate.d.ts

@@ -0,0 +1,14 @@
+import type { Fault, ItemId, ItemView, PropagationLine, RelationRow, Resolved, SignalKey } from '@boxxy/model';
+interface PropagateInput {
+    readonly lines: readonly PropagationLine[];
+    readonly items: readonly ItemView[];
+    readonly relations: readonly RelationRow[];
+    readonly signals: ReadonlyMap<SignalKey, Resolved<'signal'>>;
+    readonly values: ReadonlyMap<SignalKey, ReadonlyMap<ItemId, number>>;
+}
+interface Propagated {
+    readonly values: Map<SignalKey, Map<ItemId, number>>;
+    readonly faults: readonly Fault[];
+}
+export declare function propagate(input: PropagateInput): Propagated;
+export {};

package/dist/test-utils/build-mock-loaded-rules.d.ts

@@ -0,0 +1,9 @@
+import type { Concept, JsonValue, LoadedRules } from '@boxxy/model';
+interface MockRulesInput {
+    readonly concepts?: readonly Concept[];
+    readonly pools?: readonly JsonValue[];
+    readonly lead?: readonly JsonValue[];
+    readonly propagation?: readonly JsonValue[];
+}
+export declare function buildMockLoadedRules(input?: MockRulesInput): LoadedRules;
+export {};

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@boxxy/planning",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zgeoff/boxxy.git",
+    "directory": "modules/planning"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.ts"
+    },
+    "./test-utils/*": "./src/test-utils/*.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun ../../scripts/write-concept-pins.ts && rm -rf dist && tsrs -p tsconfig.build.json",
+    "typecheck": "tsrs --noEmit"
+  },
+  "dependencies": {
+    "@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"
+  },
+  "engines": {
+    "bun": ">=1.3",
+    "node": ">=24"
+  }
+}

package/src/build-frame.ts

@@ -0,0 +1,276 @@
+import type {
+  Fault,
+  FilterField,
+  Frame,
+  FrameItem,
+  FrameValues,
+  Hold,
+  Instant,
+  ItemId,
+  ItemView,
+  Lift,
+  LoadedRules,
+  PlanContext,
+  Resolved,
+  SignalKey,
+  Snapshot,
+  Waiver,
+} from '@boxxy/model';
+import { signalKey } from '@boxxy/model';
+import invariant from 'tiny-invariant';
+import { formatFault } from './format-fault.ts';
+import { propagate } from './propagate.ts';
+
+interface BuildFrameInput {
+  readonly snapshot: Snapshot;
+  readonly rules: LoadedRules;
+  readonly now: Instant;
+}
+
+export function buildFrame(input: BuildFrameInput): Frame {
+  const items = input.snapshot.items;
+  const candidates = collectCandidates(items);
+
+  const buildContext = (values: FrameValues): PlanContext => ({
+    now: input.now,
+    levers: input.snapshot.levers,
+    relations: input.snapshot.relations,
+    values,
+  });
+
+  const carriedKeys = new Set(input.rules.propagation.map((line) => signalKey(line.value, {})));
+
+  const carried = [...carriedKeys].map((key) =>
+    collectSignalValues(key, getSignal(input.rules, key), items, buildContext(new Map())),
+  );
+
+  const propagated = propagate({
+    lines: input.rules.propagation,
+    items,
+    relations: input.snapshot.relations,
+    signals: input.rules.signals,
+    values: new Map(carried.map((entry) => [entry.key, entry.values])),
+  });
+
+  const others = [...input.rules.signals]
+    .filter(([key]) => !carriedKeys.has(key))
+    .map(([key, signal]) =>
+      collectSignalValues(key, signal, candidates, buildContext(propagated.values)),
+    );
+
+  const values = new Map([
+    ...propagated.values,
+    ...others.map((entry): [SignalKey, Map<ItemId, number>] => [entry.key, entry.values]),
+  ]);
+
+  const context = buildContext(values);
+  const waivers = [...input.rules.registry.waiver.values()];
+  const gated = candidates.map((item) => collectHolds(item, input.rules.gates, waivers, context));
+  const filterFields = [...input.rules.registry['filter-field'].values()];
+  const fields = candidates.map((item) => collectFieldValues(item, filterFields));
+
+  return {
+    candidates,
+    fields: new Map(fields.map((entry) => [entry.item, entry.values])),
+    values,
+    holds: new Map(
+      gated.flatMap((entry) => (entry.holds.length > 0 ? [[entry.item, entry.holds]] : [])),
+    ),
+    lifted: new Map(
+      gated.flatMap((entry) => (entry.lifted.length > 0 ? [[entry.item, entry.lifted]] : [])),
+    ),
+    faults: [
+      ...carried.flatMap((entry) => entry.faults),
+      ...propagated.faults,
+      ...others.flatMap((entry) => entry.faults),
+      ...gated.flatMap((entry) => entry.faults),
+      ...fields.flatMap((entry) => entry.faults),
+    ],
+  };
+}
+
+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 [{ ...item, phase: position.phase, round: position.round }];
+  });
+}
+
+interface SignalValues {
+  readonly key: SignalKey;
+  readonly values: Map<ItemId, number>;
+  readonly faults: readonly Fault[];
+}
+
+function collectSignalValues(
+  key: SignalKey,
+  signal: Resolved<'signal'>,
+  items: readonly ItemView[],
+  context: PlanContext,
+): SignalValues {
+  const values = new Map<ItemId, number>();
+
+  const faults: Fault[] = [];
+
+  for (const item of items) {
+    try {
+      const value = signal.open((plugin, params) => plugin.value(item, context, params));
+
+      if (value !== null) {
+        values.set(item.id, value);
+      }
+    } catch (error) {
+      faults.push({
+        plugin: signal.name,
+        kind: 'signal',
+        item: item.id,
+        error: formatFault(error),
+      });
+    }
+  }
+
+  return { key, values, faults };
+}
+
+function getSignal(rules: LoadedRules, key: SignalKey): Resolved<'signal'> {
+  const signal = rules.signals.get(key);
+
+  invariant(signal, `the loader resolves the signal of each propagation line, and missed ${key}`);
+
+  return signal;
+}
+
+interface ItemHolds {
+  readonly item: ItemId;
+  readonly holds: Hold[];
+  readonly lifted: Lift[];
+  readonly faults: readonly Fault[];
+}
+
+function collectHolds(
+  item: FrameItem,
+  gates: readonly Resolved<'gate'>[],
+  waivers: readonly Waiver[],
+  context: PlanContext,
+): ItemHolds {
+  const outcomes = gates.map((gate) => pickGateOutcome(item, gate, context));
+  const faults = outcomes.flatMap((outcome) => outcome.faults);
+  const holds: Hold[] = [];
+  const lifted: Lift[] = [];
+
+  for (const outcome of outcomes) {
+    if (outcome.hold !== null) {
+      const waived = outcome.liftable
+        ? pickLift(item, outcome.hold, waivers, context)
+        : { lift: null, faults: [] };
+
+      faults.push(...waived.faults);
+
+      if (waived.lift === null) {
+        holds.push(outcome.hold);
+      } else {
+        lifted.push(waived.lift);
+      }
+    }
+  }
+
+  return { item: item.id, holds, lifted, faults };
+}
+
+interface GateOutcome {
+  readonly hold: Hold | null;
+  readonly liftable: boolean;
+  readonly faults: readonly Fault[];
+}
+
+function pickGateOutcome(
+  item: FrameItem,
+  gate: Resolved<'gate'>,
+  context: PlanContext,
+): GateOutcome {
+  try {
+    return gate.open((plugin, params) => ({
+      hold: plugin.hold(item, context, params),
+      liftable: plugin.liftable,
+      faults: [],
+    }));
+  } catch (error) {
+    const message = formatFault(error);
+
+    return {
+      hold: { gate: gate.name, reason: message },
+      liftable: false,
+      faults: [{ plugin: gate.name, kind: 'gate', item: item.id, error: message }],
+    };
+  }
+}
+
+interface Waived {
+  readonly lift: Lift | null;
+  readonly faults: readonly Fault[];
+}
+
+function pickLift(
+  item: FrameItem,
+  hold: Hold,
+  waivers: readonly Waiver[],
+  context: PlanContext,
+): Waived {
+  const faults: Fault[] = [];
+
+  for (const waiver of waivers.filter((candidate) => candidate.lifts === hold.gate)) {
+    try {
+      const lift = waiver.lift(item, hold, context);
+
+      if (lift !== null) {
+        return { lift, faults };
+      }
+    } catch (error) {
+      faults.push({
+        plugin: waiver.name,
+        kind: 'waiver',
+        item: item.id,
+        error: formatFault(error),
+      });
+    }
+  }
+
+  return { lift: null, faults };
+}
+
+interface FieldValues {
+  readonly item: ItemId;
+  readonly values: Readonly<Record<string, readonly string[]>>;
+  readonly faults: readonly Fault[];
+}
+
+function collectFieldValues(item: FrameItem, fields: readonly FilterField[]): FieldValues {
+  const values: Record<string, readonly string[]> = {};
+  const faults: Fault[] = [];
+
+  for (const field of fields) {
+    try {
+      const value = field.value(item);
+
+      if (value !== null) {
+        values[field.name] = typeof value === 'string' ? [value] : value;
+      }
+    } catch (error) {
+      faults.push({
+        plugin: field.name,
+        kind: 'filter-field',
+        item: item.id,
+        error: formatFault(error),
+      });
+    }
+  }
+
+  return { item: item.id, values, faults };
+}

package/src/compare-item-ids.ts

@@ -0,0 +1,10 @@
+import type { ItemId } from '@boxxy/model';
+
+// compares by UTF-16 code units, so the order never depends on the locale
+export function compareItemIDs(left: ItemId, right: ItemId): number {
+  if (left === right) {
+    return 0;
+  }
+
+  return left < right ? -1 : 1;
+}

package/src/concepts/defer.ts

@@ -0,0 +1,50 @@
+import type { Concept, LeverRow } from '@boxxy/model';
+import { defineGate, signalKey } from '@boxxy/model';
+import { z } from 'zod';
+
+const expediteKey = signalKey('expedite', {});
+
+export const defer: Concept = {
+  name: 'defer',
+  version: 1,
+  gates: [
+    defineGate({
+      name: 'defer',
+      liftable: true,
+      params: z.object({}),
+      hold: (item, ctx) => {
+        const latest = findLatestDefer(ctx.levers.filter((lever) => lever.item === item.id));
+
+        if (latest === null || (latest.until !== null && latest.until <= ctx.now)) {
+          return null;
+        }
+
+        const reason = latest.reason ?? 'deferred';
+
+        return latest.until === null
+          ? { gate: 'defer', reason }
+          : { gate: 'defer', reason, until: latest.until };
+      },
+    }),
+  ],
+  waivers: [
+    {
+      name: 'expedite-lifts-defer',
+      lifts: 'defer',
+      lift: (item, hold, ctx) =>
+        ctx.values.get(expediteKey)?.has(item.id) === true
+          ? { waiver: 'expedite-lifts-defer', gate: hold.gate, reason: 'expedited' }
+          : null,
+    },
+  ],
+  levers: ['plan.defer', 'plan.undefer'],
+};
+
+function findLatestDefer(levers: readonly LeverRow[]): LeverRow | null {
+  return levers
+    .filter((lever) => lever.kind === 'plan.defer')
+    .reduce<LeverRow | null>(
+      (latest, lever) => (latest === null || lever.seq > latest.seq ? lever : latest),
+      null,
+    );
+}

package/src/concepts/expedite.ts

@@ -0,0 +1,24 @@
+import type { Concept } from '@boxxy/model';
+import { defineSignal } from '@boxxy/model';
+import { z } from 'zod';
+
+export const expedite: Concept = {
+  name: 'expedite',
+  version: 1,
+  signals: [
+    defineSignal({
+      name: 'expedite',
+      params: z.object({}),
+      value: (item, ctx) => {
+        const position = ctx.levers
+          .filter((lever) => lever.kind === 'plan.expedite')
+          .toSorted((left, right) => left.seq - right.seq)
+          .findIndex((lever) => lever.item === item.id);
+
+        return position === -1 ? null : position;
+      },
+      combine: (left, right) => Math.min(left, right),
+    }),
+  ],
+  levers: ['plan.expedite', 'plan.unexpedite'],
+};

package/src/concepts/pool.ts

@@ -0,0 +1,23 @@
+import type { Concept } from '@boxxy/model';
+import { defineSignal } from '@boxxy/model';
+import { z } from 'zod';
+
+export const pool: Concept = {
+  name: 'pool',
+  version: 2,
+  signals: [
+    defineSignal({
+      name: 'oldest',
+      params: z.object({}),
+      value: (item) => item.filedAt,
+    }),
+  ],
+  filterFields: [
+    { 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

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

package/src/decide.ts

@@ -0,0 +1,187 @@
+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 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 seats = buildSeats(input.snapshot.limits);
+
+  const backoff = new Set(input.backoff);
+
+  const picks: (StartPick | WakePick)[] = [];
+  const waits: Wait[] = [];
+
+  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);
+
+    if (taken.kind === 'taken') {
+      picks.push({ kind: 'wake', attempt: wake.attempt, limits: taken.limits });
+    } else {
+      waits.push({ subject, reason: taken.reason });
+    }
+  }
+
+  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, waits };
+}
+
+type SeatTaking =
+  | { readonly kind: 'taken'; readonly limits: readonly LimitName[] }
+  | { readonly kind: 'refused'; readonly reason: WaitReason };
+
+interface Seats {
+  take: (fields: FieldValues) => SeatTaking;
+}
+
+// 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 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 = values.get(key);
+    const order = compareValues(byItem?.get(left.id), byItem?.get(right.id));
+
+    if (order !== 0) {
+      return order;
+    }
+  }
+
+  return compareItemIDs(left.id, right.id);
+}
+
+function compareValues(left: number | undefined, right: number | undefined): number {
+  if (left === right) {
+    return 0;
+  }
+
+  if (left === undefined) {
+    return 1;
+  }
+
+  if (right === undefined) {
+    return -1;
+  }
+
+  return left < right ? -1 : 1;
+}

package/src/format-fault.ts

@@ -0,0 +1,3 @@
+export function formatFault(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/generated/concept-pins.ts

@@ -0,0 +1,33 @@
+// scripts/write-concept-pins.ts writes this file; run `bun run build` in modules/planning
+import { contentHashSchema } from '@boxxy/content-hash';
+import type { ConceptName, ConceptPin } from '@boxxy/model';
+
+export const conceptPins: ReadonlyMap<ConceptName, ConceptPin> = new Map([
+  [
+    'defer',
+    {
+      ref: 'defer@1',
+      sourceHash: contentHashSchema.parse(
+        'cbe173e108ca3b290f7f48ea3a4145b28f44611ae7f4a43d29430f08b88f46df',
+      ),
+    },
+  ],
+  [
+    'expedite',
+    {
+      ref: 'expedite@1',
+      sourceHash: contentHashSchema.parse(
+        'f75e37b479e49da4e68aab6f3d8e9960b04608eb7a9fdd53d4349578e1c213d3',
+      ),
+    },
+  ],
+  [
+    'pool',
+    {
+      ref: 'pool@2',
+      sourceHash: contentHashSchema.parse(
+        '1631a22966bd50fa39a8acc79f242fb0ac6603ead15b8f4ca3907f5e2cdd1214',
+      ),
+    },
+  ],
+]);

package/src/index.ts

@@ -0,0 +1,4 @@
+export { buildFrame } from './build-frame.ts';
+export { concepts } from './concepts.ts';
+export { decide } from './decide.ts';
+export { conceptPins } from './generated/concept-pins.ts';

package/src/propagate.ts

@@ -0,0 +1,132 @@
+import type {
+  Fault,
+  ItemId,
+  ItemView,
+  PropagationLine,
+  RelationRow,
+  Resolved,
+  SignalKey,
+} from '@boxxy/model';
+import { signalKey } from '@boxxy/model';
+import invariant from 'tiny-invariant';
+import { compareItemIDs } from './compare-item-ids.ts';
+import { formatFault } from './format-fault.ts';
+
+interface PropagateInput {
+  readonly lines: readonly PropagationLine[];
+  readonly items: readonly ItemView[];
+  readonly relations: readonly RelationRow[];
+  readonly signals: ReadonlyMap<SignalKey, Resolved<'signal'>>;
+  readonly values: ReadonlyMap<SignalKey, ReadonlyMap<ItemId, number>>;
+}
+
+interface Propagated {
+  readonly values: Map<SignalKey, Map<ItemId, number>>;
+  readonly faults: readonly Fault[];
+}
+
+export function propagate(input: PropagateInput): Propagated {
+  const open = new Set(input.items.map((item) => item.id));
+
+  const faults: Fault[] = [];
+
+  const values = new Map(
+    [...input.values].map(([key, byItem]): [SignalKey, Map<ItemId, number>] => [
+      key,
+      new Map(byItem),
+    ]),
+  );
+
+  for (const line of input.lines) {
+    const key = signalKey(line.value, {});
+    const combine = getCombine(input.signals, key);
+
+    try {
+      const start = values.get(key) ?? new Map<ItemId, number>();
+
+      values.set(key, carryLine(line, combine, start, { open, relations: input.relations }));
+    } catch (error) {
+      faults.push({
+        plugin: `propagation:${line.value}:${line.over}`,
+        kind: 'propagation',
+        item: null,
+        error: formatFault(error),
+      });
+    }
+  }
+
+  return { values, faults };
+}
+
+type Combine = (left: number, right: number) => number;
+
+function getCombine(signals: PropagateInput['signals'], key: SignalKey): Combine {
+  const combine = signals.get(key)?.open((plugin) => plugin.combine);
+
+  invariant(combine, `the loader refuses a propagation line whose signal ${key} has no combine`);
+
+  return combine;
+}
+
+interface LineGraph {
+  readonly open: ReadonlySet<ItemId>;
+  readonly relations: readonly RelationRow[];
+}
+
+function carryLine(
+  line: PropagationLine,
+  combine: Combine,
+  start: ReadonlyMap<ItemId, number>,
+  graph: LineGraph,
+): Map<ItemId, number> {
+  const next = collectNeighbours(line, graph.relations);
+
+  const carried = new Map(start);
+
+  const starts = [...start].toSorted(([left], [right]) => compareItemIDs(left, right));
+
+  for (const [origin, value] of starts) {
+    const visited = new Set([origin]);
+
+    const queue = [...(next.get(origin) ?? [])];
+
+    while (queue.length > 0) {
+      const reached = queue.shift();
+
+      if (reached === undefined || visited.has(reached) || !graph.open.has(reached)) {
+        continue;
+      }
+
+      visited.add(reached);
+
+      const current = carried.get(reached);
+      const combined = current === undefined ? value : combine(current, value);
+
+      carried.set(reached, combined);
+      queue.push(...(next.get(reached) ?? []));
+    }
+  }
+
+  return carried;
+}
+
+function collectNeighbours(
+  line: PropagationLine,
+  relations: readonly RelationRow[],
+): Map<ItemId, ItemId[]> {
+  const next = new Map<ItemId, ItemId[]>();
+
+  for (const relation of relations.filter((candidate) => candidate.type === line.over)) {
+    const [from, to] =
+      line.toward === 'source'
+        ? [relation.target, relation.source]
+        : [relation.source, relation.target];
+
+    const neighbours = next.get(from) ?? [];
+
+    neighbours.push(to);
+    next.set(from, neighbours);
+  }
+
+  return next;
+}

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

@@ -0,0 +1,77 @@
+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';
+
+interface MockRulesInput {
+  readonly concepts?: readonly Concept[];
+  readonly pools?: readonly JsonValue[];
+  readonly lead?: readonly JsonValue[];
+  readonly propagation?: readonly JsonValue[];
+}
+
+export function buildMockLoadedRules(input: MockRulesInput = {}): LoadedRules {
+  const concepts = input.concepts ?? builtInConcepts;
+
+  const file = {
+    version: 1,
+    concepts: concepts.map((concept) => `${concept.name}@${concept.version}`),
+    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', takes: { phase: 'build', kind: ['core.issue'] }, order: ['oldest'] },
+    ],
+    lead: input.lead ?? ['expedite'],
+    propagation: input.propagation ?? [{ value: 'expedite', over: 'blocks', toward: 'source' }],
+    recipes: {
+      'build-v1': {
+        agent: 'claude',
+        model: 'example-model',
+        effort: 'high',
+        prompt: 'prompts/build-v1.md',
+        source: 'subscription',
+        skills: [],
+      },
+    },
+    sleep: { afterIdleMinutes: 30, afterQuietMinutes: 60, afterUnattendedMinutes: 240 },
+  };
+
+  const encoder = new TextEncoder();
+
+  // only modules/rules may import yaml, and JSON is YAML, so the loader reads this as it is
+  const rulesBytes = encoder.encode(JSON.stringify(file));
+
+  const pins = concepts.map((concept): [string, ConceptPin] => [
+    concept.name,
+    {
+      ref: `${concept.name}@${concept.version}`,
+      sourceHash: contentHash(`${concept.name} source`),
+    },
+  ]);
+
+  const result = loadRules({
+    checkout: {
+      commit: '3f2a1c0',
+      files: new Map([
+        ['rules.yaml', rulesBytes],
+        ['prompts/build-v1.md', encoder.encode('Build {{title}}.\n')],
+      ]),
+    },
+    concepts,
+    pins: new Map(pins),
+    phases: [buildMockPhaseKind({ name: 'build', outcomes: ['built'] })],
+  });
+
+  invariant(
+    result.kind === 'loaded',
+    `the mock rules file failed to load: ${JSON.stringify(result)}`,
+  );
+
+  return result.rules;
+}