@boxxy/planning 0.0.0-stage → 0.1.0

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,43 @@
-# 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 next item phase for each free pool slot.
+
+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 picks one candidate per free slot, pool by pool, and never names a concept.
+- `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 deferConcept: Concept;

package/dist/concepts/expedite.d.ts

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

package/dist/concepts/pool.d.ts

@@ -0,0 +1,2 @@
+import type { Concept } from '@boxxy/model';
+export declare const poolConcept: 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,8 @@
+import type { Decision, Frame, Pool, PoolName } from '@boxxy/model';
+interface DecideInput {
+    readonly frame: Frame;
+    readonly pools: readonly Pool[];
+    readonly freeSlots: Readonly<Record<PoolName, number>>;
+}
+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, FrameItem, ItemId, LinkRow, PropagationLine, Resolved, SignalKey } from '@boxxy/model';
+interface PropagateInput {
+    readonly lines: readonly PropagationLine[];
+    readonly items: readonly FrameItem[];
+    readonly links: readonly LinkRow[];
+    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.0",
+  "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.0",
+    "@boxxy/model": "0.1.1",
+    "@boxxy/rules": "0.1.0",
+    "tiny-invariant": "1.3.3",
+    "zod": "4.6.7"
+  },
+  "engines": {
+    "bun": ">=1.3",
+    "node": ">=24"
+  }
+}

package/src/build-frame.ts

@@ -0,0 +1,274 @@
+import type {
+  Fault,
+  FilterField,
+  Frame,
+  FrameItem,
+  FrameValues,
+  Hold,
+  Instant,
+  ItemId,
+  ItemKindName,
+  KindRules,
+  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 = collectFrameItems(input.snapshot, input.rules.kinds);
+  const candidates = items.filter((item) => item.derived.state === 'ready');
+
+  const buildContext = (values: FrameValues): PlanContext => ({
+    now: input.now,
+    levers: input.snapshot.levers,
+    links: input.snapshot.links,
+    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,
+    links: input.snapshot.links,
+    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 collectFrameItems(
+  snapshot: Snapshot,
+  kinds: ReadonlyMap<ItemKindName, KindRules>,
+): FrameItem[] {
+  return snapshot.items.flatMap((item) => {
+    const phase = kinds.get(item.kind)?.pipeline.steps[0]?.phase;
+
+    return phase === undefined ? [] : [{ ...item, phase }];
+  });
+}
+
+interface SignalValues {
+  readonly key: SignalKey;
+  readonly values: Map<ItemId, number>;
+  readonly faults: readonly Fault[];
+}
+
+function collectSignalValues(
+  key: SignalKey,
+  signal: Resolved<'signal'>,
+  items: readonly FrameItem[],
+  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 deferConcept: 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 expediteConcept: 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,20 @@
+import type { Concept } from '@boxxy/model';
+import { defineSignal } from '@boxxy/model';
+import { z } from 'zod';
+
+export const poolConcept: Concept = {
+  name: 'pool',
+  version: 1,
+  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 },
+  ],
+};

package/src/concepts.ts

@@ -0,0 +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';
+
+export const concepts: readonly Concept[] = [poolConcept, deferConcept, expediteConcept];

package/src/decide.ts

@@ -0,0 +1,71 @@
+import type { Decision, Frame, FrameItem, ItemId, Pick, Pool, PoolName } 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>>;
+}
+
+export function decide(input: DecideInput): Decision {
+  const frame = input.frame;
+
+  const picked = new Set<ItemId>();
+
+  const picks: Pick[] = [];
+
+  for (const pool of input.pools) {
+    const free = input.freeSlots[pool.name] ?? 0;
+
+    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));
+
+    for (const item of ranked.slice(0, free)) {
+      picked.add(item.id);
+      picks.push({ item: item.id, phase: item.phase, pool: pool.name });
+    }
+  }
+
+  return { picks };
+}
+
+function isTakenBy(pool: Pool, fields: Readonly<Record<string, readonly string[]>>): boolean {
+  return Object.entries(pool.takes).every(([field, accepted]) =>
+    (fields[field] ?? []).some((value) => accepted.includes(value)),
+  );
+}
+
+function compareCandidates(left: FrameItem, right: FrameItem, pool: Pool, frame: Frame): number {
+  for (const key of pool.order) {
+    const byItem = frame.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(
+        '465c5e5376b2de6814f08888cd479249e494d1986802aa6293e2495b88e846d9',
+      ),
+    },
+  ],
+  [
+    'expedite',
+    {
+      ref: 'expedite@1',
+      sourceHash: contentHashSchema.parse(
+        '672b566d996e4b8d1aeb6e9e768460726473d6f0181a0eedcf09494687679882',
+      ),
+    },
+  ],
+  [
+    'pool',
+    {
+      ref: 'pool@1',
+      sourceHash: contentHashSchema.parse(
+        '93bb6fefe3cf95fc8a15bbe9381733427ba34c2118626449c7828929f895b984',
+      ),
+    },
+  ],
+]);

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,130 @@
+import type {
+  Fault,
+  FrameItem,
+  ItemId,
+  LinkRow,
+  PropagationLine,
+  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 FrameItem[];
+  readonly links: readonly LinkRow[];
+  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, links: input.links }));
+    } 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 links: readonly LinkRow[];
+}
+
+function carryLine(
+  line: PropagationLine,
+  combine: Combine,
+  start: ReadonlyMap<ItemId, number>,
+  graph: LineGraph,
+): Map<ItemId, number> {
+  const next = collectNeighbours(line, graph.links);
+
+  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,
+  links: readonly LinkRow[],
+): Map<ItemId, ItemId[]> {
+  const next = new Map<ItemId, ItemId[]>();
+
+  for (const link of links.filter((candidate) => candidate.type === line.over)) {
+    const [from, to] =
+      line.toward === 'source' ? [link.target, link.source] : [link.source, link.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,79 @@
+import { contentHash } from '@boxxy/content-hash';
+import type { Concept, ConceptPin, JsonValue, LoadedRules } from '@boxxy/model';
+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}`),
+    kinds: {
+      'core.issue': {
+        pipeline: ['build'],
+        maxAttempts: { build: 2 },
+        recipes: { build: 'build-v1' },
+      },
+    },
+    pools: input.pools ?? [
+      {
+        name: 'build',
+        slots: 2,
+        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',
+      },
+    },
+  };
+
+  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),
+  });
+
+  invariant(
+    result.kind === 'loaded',
+    `the mock rules file failed to load: ${JSON.stringify(result)}`,
+  );
+
+  return result.rules;
+}