@boxxy/rules 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,41 @@
-# Temporary Holding Version
+<div align="center">
+  <h1>@boxxy/rules</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/rules"><img src="https://img.shields.io/npm/v/@boxxy/rules" 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 rules loader. `loadRules` checks a rules checkout's `rules.yaml` against the concepts boxxy
+compiles in, builds the plug-in registry, and gives the loaded rules a version.
+
+The package does no I/O: the caller reads the checkout and passes in its commit hash and its files'
+bytes.
+
+## Install
+
+Install the package from [npm](https://www.npmjs.com/package/@boxxy/rules) with Bun:
+
+```bash
+bun add @boxxy/rules
+```
+
+The package runs on [Bun](https://bun.sh) 1.3 or newer.
+
+## Features
+
+- `loadRules`, which returns the loaded rules, or every rejection with its file, its path in the
+  file and its reason ([rules for slice 1](../../docs/design/boxxy/slice-1.md#rules-for-slice-1)).
+- The rules version, a content hash of the commit, the files the loader read and each concept pin
+  ([the rules version](../../docs/design/boxxy/rules.md#the-rules-version)).
+
+## Documentation
+
+The [rules design](../../docs/design/boxxy/rules.md) says why rules live in git, and
+[`01-registries.ts`](../../docs/design/boxxy/sketches/01-registries.ts) gives the shape of the
+loaded rules.

package/dist/build-registry.d.ts

@@ -0,0 +1,6 @@
+import type { ConceptPin, LoadRejection, Registry } from '@boxxy/model';
+import type { PinnedConcept } from './types.ts';
+export declare function buildRegistry(pinned: readonly PinnedConcept[], pins: readonly ConceptPin[]): {
+    readonly value: Registry;
+    readonly rejections: readonly LoadRejection[];
+};

package/dist/build-rejection.d.ts

@@ -0,0 +1,2 @@
+import type { LoadRejection, LoadRejectionReason } from '@boxxy/model';
+export declare function buildRejection(path: readonly PropertyKey[], reason: LoadRejectionReason): LoadRejection;

package/dist/constants.d.ts

@@ -0,0 +1 @@
+export declare const rulesFileName = "rules.yaml";

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { loadRules } from './load-rules.ts';

package/dist/load-rules.d.ts

@@ -0,0 +1,11 @@
+import type { Concept, ConceptName, ConceptPin, LoadResult } from '@boxxy/model';
+interface LoadRulesInput {
+    readonly checkout: {
+        readonly commit: string;
+        readonly files: ReadonlyMap<string, Uint8Array>;
+    };
+    readonly concepts: readonly Concept[];
+    readonly pins: ReadonlyMap<ConceptName, ConceptPin>;
+}
+export declare function loadRules(input: LoadRulesInput): LoadResult;
+export {};

package/dist/parse-concept-entry.d.ts

@@ -0,0 +1,5 @@
+import type { ConceptEntry, ConceptName } from '@boxxy/model';
+export declare function parseConceptEntry(entry: ConceptEntry): {
+    readonly name: ConceptName;
+    readonly version: number;
+};

package/dist/parse-rules-file.d.ts

@@ -0,0 +1,11 @@
+import type { LoadRejection } from '@boxxy/model';
+import type { ParsedRulesFile } from './rules-file-schema.ts';
+type RulesFileParse = {
+    readonly kind: 'parsed';
+    readonly file: ParsedRulesFile;
+} | {
+    readonly kind: 'rejected';
+    readonly rejections: readonly LoadRejection[];
+};
+export declare function parseRulesFile(fileName: string, bytes: Uint8Array): RulesFileParse;
+export {};

package/dist/resolve-plugin.d.ts

@@ -0,0 +1,4 @@
+import type { JsonValue } from '@boxxy/content-hash';
+import type { ParamKindName, Registered, Resolved } from '@boxxy/model';
+import type { Checked } from './types.ts';
+export declare function resolvePlugin<K extends ParamKindName>(registered: Registered<K>, params: JsonValue, key: string, path: readonly PropertyKey[]): Checked<Resolved<K>>;

package/dist/resolve-signal-ref.d.ts

@@ -0,0 +1,3 @@
+import type { Registry, SignalRef } from '@boxxy/model';
+import type { Checked, ResolvedSignal } from './types.ts';
+export declare function resolveSignalRef(ref: SignalRef, path: readonly PropertyKey[], registry: Registry): Checked<ResolvedSignal>;

package/dist/rules-file-schema.d.ts

@@ -0,0 +1,49 @@
+import type { PipelineStep } from '@boxxy/model';
+import { z } from 'zod';
+export declare const rulesFileSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    concepts: z.ZodArray<z.ZodTemplateLiteral<`${string}@${number}`>>;
+    kinds: z.ZodRecord<z.core.$ZodBranded<z.ZodString, "ItemKindName", "out">, z.ZodPipe<z.ZodObject<{
+        pipeline: z.ZodArray<z.core.$ZodBranded<z.ZodString, "PhaseName", "out">>;
+        maxAttempts: z.ZodRecord<z.core.$ZodBranded<z.ZodString, "PhaseName", "out">, z.ZodInt>;
+        recipes: z.ZodRecord<z.core.$ZodBranded<z.ZodString, "PhaseName", "out">, z.core.$ZodBranded<z.ZodString, "RecipeName", "out">>;
+    }, z.core.$strict>, z.ZodTransform<{
+        pipeline: (string & z.$brand<"PhaseName">)[];
+        maxAttempts: Record<string & z.$brand<"PhaseName">, number>;
+        recipes: Record<string & z.$brand<"PhaseName">, string & z.$brand<"RecipeName">>;
+        steps: PipelineStep[];
+    }, {
+        pipeline: (string & z.$brand<"PhaseName">)[];
+        maxAttempts: Record<string & z.$brand<"PhaseName">, number>;
+        recipes: Record<string & z.$brand<"PhaseName">, string & z.$brand<"RecipeName">>;
+    }>>>;
+    pools: z.ZodArray<z.ZodObject<{
+        name: z.core.$ZodBranded<z.ZodString, "PoolName", "out">;
+        slots: z.ZodInt;
+        takes: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+        order: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodJSONSchema>]>>;
+    }, z.core.$strict>>;
+    lead: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodJSONSchema>]>>;
+    propagation: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        over: z.core.$ZodBranded<z.ZodString, "LinkTypeName", "out">;
+        toward: z.ZodEnum<{
+            source: "source";
+            target: "target";
+        }>;
+    }, z.core.$strict>>;
+    recipes: z.ZodRecord<z.core.$ZodBranded<z.ZodString, "RecipeName", "out">, z.ZodObject<{
+        agent: z.ZodString;
+        model: z.ZodString;
+        effort: z.ZodEnum<{
+            high: "high";
+            low: "low";
+            max: "max";
+            medium: "medium";
+            xhigh: "xhigh";
+        }>;
+        prompt: z.ZodString;
+        source: z.core.$ZodBranded<z.ZodString, "SourceName", "out">;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ParsedRulesFile = z.output<typeof rulesFileSchema>;

package/dist/types.d.ts

@@ -0,0 +1,13 @@
+import type { Concept, LoadRejection, Resolved, SignalKey } from '@boxxy/model';
+export interface Checked<T> {
+    readonly value: T | null;
+    readonly rejections: readonly LoadRejection[];
+}
+export interface ResolvedSignal {
+    readonly key: SignalKey;
+    readonly resolved: Resolved<'signal'>;
+}
+export interface PinnedConcept {
+    readonly concept: Concept;
+    readonly entryIndex: number;
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@boxxy/rules",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "boxxy's rules loader: checks a rules checkout and builds the plug-in registry",
+  "homepage": "https://github.com/zgeoff/boxxy/tree/main/modules/rules#readme",
+  "bugs": "https://github.com/zgeoff/boxxy/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zgeoff/boxxy.git",
+    "directory": "modules/rules"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsrs -p tsconfig.build.json",
+    "typecheck": "tsrs --noEmit"
+  },
+  "dependencies": {
+    "@boxxy/content-hash": "0.1.0",
+    "@boxxy/model": "0.1.1",
+    "tiny-invariant": "1.3.3",
+    "ts-pattern": "5.9.2",
+    "yaml": "2.9.1",
+    "zod": "4.6.7"
+  },
+  "engines": {
+    "bun": ">=1.3",
+    "node": ">=24"
+  }
+}

package/src/build-registry.ts

@@ -0,0 +1,67 @@
+import type { ConceptPin, LoadRejection, Registry } from '@boxxy/model';
+import { buildRejection } from './build-rejection.ts';
+import type { PinnedConcept } from './types.ts';
+
+export function buildRegistry(
+  pinned: readonly PinnedConcept[],
+  pins: readonly ConceptPin[],
+): { readonly value: Registry; readonly rejections: readonly LoadRejection[] } {
+  const signal = collectByName(pinned, (concept) => concept.signals ?? []);
+  const gate = collectByName(pinned, (concept) => concept.gates ?? []);
+  const waiver = collectByName(pinned, (concept) => concept.waivers ?? []);
+  const filterField = collectByName(pinned, (concept) => concept.filterFields ?? []);
+
+  const lever = collectByName(pinned, (concept) =>
+    (concept.levers ?? []).map((kind) => ({ name: kind, kind })),
+  );
+
+  return {
+    value: {
+      signal: signal.byName,
+      gate: gate.byName,
+      admission: new Map(),
+      waiver: waiver.byName,
+      'filter-field': filterField.byName,
+      lever: lever.byName,
+      view: new Map(),
+      pins,
+    },
+    rejections: [
+      ...signal.rejections,
+      ...gate.rejections,
+      ...waiver.rejections,
+      ...filterField.rejections,
+      ...lever.rejections,
+    ],
+  };
+}
+
+function collectByName<T extends { readonly name: string }>(
+  pinned: readonly PinnedConcept[],
+  pluginsOf: (concept: PinnedConcept['concept']) => readonly T[],
+): { readonly byName: ReadonlyMap<string, T>; readonly rejections: readonly LoadRejection[] } {
+  const byName = new Map<string, T>();
+  const owners = new Map<string, string>();
+
+  const rejections: LoadRejection[] = [];
+
+  for (const entry of pinned) {
+    for (const plugin of pluginsOf(entry.concept)) {
+      const owner = owners.get(plugin.name);
+
+      if (owner === undefined) {
+        byName.set(plugin.name, plugin);
+        owners.set(plugin.name, entry.concept.name);
+      } else {
+        rejections.push(
+          buildRejection(['concepts', entry.entryIndex], {
+            kind: 'invalid',
+            message: `the concepts ${owner} and ${entry.concept.name} both register ${plugin.name}`,
+          }),
+        );
+      }
+    }
+  }
+
+  return { byName, rejections };
+}

package/src/build-rejection.ts

@@ -0,0 +1,10 @@
+import type { LoadRejection, LoadRejectionReason } from '@boxxy/model';
+import { formatKeyPath } from '@boxxy/model';
+import { rulesFileName } from './constants.ts';
+
+export function buildRejection(
+  path: readonly PropertyKey[],
+  reason: LoadRejectionReason,
+): LoadRejection {
+  return { file: rulesFileName, path: formatKeyPath(path), reason };
+}

package/src/constants.ts

@@ -0,0 +1 @@
+export const rulesFileName = 'rules.yaml';

package/src/index.ts

@@ -0,0 +1 @@
+export { loadRules } from './load-rules.ts';

package/src/load-rules.ts

@@ -0,0 +1,320 @@
+import type { TreeFile } from '@boxxy/content-hash';
+import { contentHash, hashBytes, hashTree } from '@boxxy/content-hash';
+import type {
+  Concept,
+  ConceptName,
+  ConceptPin,
+  ItemKindName,
+  KindRules,
+  LoadRejection,
+  LoadResult,
+  LoadedRecipe,
+  Pool,
+  RecipeName,
+  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 { 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';
+
+interface LoadRulesInput {
+  readonly checkout: {
+    readonly commit: string;
+    readonly files: ReadonlyMap<string, Uint8Array>;
+  };
+  readonly concepts: readonly Concept[];
+  readonly pins: ReadonlyMap<ConceptName, ConceptPin>;
+}
+
+export function loadRules(input: LoadRulesInput): LoadResult {
+  const rulesBytes = input.checkout.files.get(rulesFileName);
+
+  if (rulesBytes === undefined) {
+    return {
+      kind: 'rejected',
+      rejections: [
+        buildRejection([], { kind: 'invalid', message: `the checkout has no ${rulesFileName}` }),
+      ],
+    };
+  }
+
+  return match(parseRulesFile(rulesFileName, rulesBytes))
+    .with({ kind: 'rejected' }, (rejected): LoadResult => rejected)
+    .with({ kind: 'parsed' }, (parsed) => buildLoadResult(parsed.file, rulesBytes, input))
+    .exhaustive();
+}
+
+function buildLoadResult(
+  file: ParsedRulesFile,
+  rulesBytes: Uint8Array,
+  input: LoadRulesInput,
+): LoadResult {
+  const pinned = collectPinnedConcepts(file, input.concepts);
+
+  const built = buildRegistry(
+    pinned.value,
+    pinned.value.map((entry) => getPin(input.pins, entry.concept)),
+  );
+
+  const registry = built.value;
+  const lead = file.lead.map((ref, index) => resolveSignalRef(ref, ['lead', index], registry));
+
+  const pools = file.pools.map((pool, poolIndex) => ({
+    pool,
+    order: pool.order.map((ref, index) =>
+      resolveSignalRef(ref, ['pools', poolIndex, 'order', index], registry),
+    ),
+  }));
+
+  const propagation = file.propagation.map((line, index) =>
+    resolveSignalRef(line.value, ['propagation', index, 'value'], registry),
+  );
+
+  const gates = pinned.value.flatMap((entry) =>
+    (entry.concept.gates ?? []).map((gate) =>
+      resolvePlugin(gate, {}, gate.name, ['concepts', entry.entryIndex]),
+    ),
+  );
+
+  const prompts = collectPrompts(file, input.checkout.files);
+  const signals = [...lead, ...pools.flatMap((pool) => pool.order), ...propagation];
+
+  const rejections = [
+    ...pinned.rejections,
+    ...built.rejections,
+    ...[...signals, ...gates].flatMap((checked) => checked.rejections),
+    ...collectPropagationRejections(file, propagation),
+    ...collectMissingRecipes(file),
+    ...prompts.rejections,
+  ];
+
+  if (rejections.length > 0) {
+    return { kind: 'rejected', rejections };
+  }
+
+  const version = buildRulesVersion(
+    input.checkout.commit,
+    [
+      { path: rulesFileName, bytes: rulesBytes, executable: false },
+      ...prompts.value.map((prompt) => ({
+        path: prompt.recipe.prompt,
+        bytes: prompt.bytes,
+        executable: false,
+      })),
+    ],
+    registry.pins,
+  );
+
+  const leadKeys = lead.map((checked) => getValue(checked).key);
+  const kinds = buildKinds(file);
+
+  return {
+    kind: 'loaded',
+    rules: {
+      version,
+      commit: input.checkout.commit,
+      registry,
+      signals: new Map(
+        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])),
+        ]),
+      ),
+      pools: pools.map((entry): Pool => ({
+        name: entry.pool.name,
+        slots: entry.pool.slots,
+        takes: buildTakes(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] => [
+          prompt.name,
+          {
+            name: prompt.name,
+            recipe: prompt.recipe,
+            promptHash: hashBytes(prompt.bytes),
+            rulesVersion: version,
+          },
+        ]),
+      ),
+    },
+    warnings: [],
+  };
+}
+
+function collectPinnedConcepts(
+  file: ParsedRulesFile,
+  concepts: readonly Concept[],
+): { readonly value: readonly PinnedConcept[]; readonly rejections: readonly LoadRejection[] } {
+  const pinned: PinnedConcept[] = [];
+  const rejections: LoadRejection[] = [];
+
+  for (const [entryIndex, entry] of file.concepts.entries()) {
+    const ref = parseConceptEntry(entry);
+
+    const concept = concepts.find(
+      (candidate) => candidate.name === ref.name && candidate.version === ref.version,
+    );
+
+    if (concept === undefined) {
+      rejections.push(
+        buildRejection(['concepts', entryIndex], { kind: 'unknown-concept', ref: entry }),
+      );
+    } else {
+      pinned.push({ concept, entryIndex });
+    }
+  }
+
+  return { value: pinned, rejections };
+}
+
+function getPin(pins: ReadonlyMap<ConceptName, ConceptPin>, concept: Concept): ConceptPin {
+  const ref = `${concept.name}@${concept.version}` as const;
+  const pin = pins.get(concept.name);
+
+  invariant(pin?.ref === ref, `the server passes a pin for each concept, and has none for ${ref}`);
+
+  return pin;
+}
+
+interface RecipePrompt {
+  readonly name: RecipeName;
+  readonly recipe: ParsedRulesFile['recipes'][RecipeName];
+  readonly bytes: Uint8Array;
+}
+
+function collectPrompts(
+  file: ParsedRulesFile,
+  files: ReadonlyMap<string, Uint8Array>,
+): { readonly value: readonly RecipePrompt[]; readonly rejections: readonly LoadRejection[] } {
+  const prompts: RecipePrompt[] = [];
+  const rejections: LoadRejection[] = [];
+
+  for (const [name, recipe] of Object.entries(file.recipes)) {
+    const bytes = files.get(recipe.prompt);
+
+    if (bytes === undefined) {
+      rejections.push(
+        buildRejection(['recipes', name, 'prompt'], {
+          kind: 'missing-prompt',
+          path: recipe.prompt,
+        }),
+      );
+    } else {
+      prompts.push({ name: brandSchemas.recipeName.parse(name), recipe, bytes });
+    }
+  }
+
+  return { value: prompts, rejections };
+}
+
+const knownLinkTypes: ReadonlySet<string> = new Set(['blocks']);
+
+function collectPropagationRejections(
+  file: ParsedRulesFile,
+  signals: readonly Checked<ResolvedSignal>[],
+): LoadRejection[] {
+  return file.propagation.flatMap((line, index) => {
+    const rejections: LoadRejection[] = [];
+    const signal = signals[index]?.value ?? null;
+
+    if (!knownLinkTypes.has(line.over)) {
+      rejections.push(
+        buildRejection(['propagation', index, 'over'], {
+          kind: 'unknown-link-type',
+          link: line.over,
+        }),
+      );
+    }
+
+    if (signal !== null && !signal.resolved.open((plugin) => plugin.combine !== undefined)) {
+      rejections.push(
+        buildRejection(['propagation', index, 'value'], {
+          kind: 'signal-without-combine',
+          signal: line.value,
+        }),
+      );
+    }
+
+    return rejections;
+  });
+}
+
+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 buildRulesVersion(
+  commit: string,
+  files: readonly TreeFile[],
+  pins: readonly ConceptPin[],
+): RulesVersion {
+  return brandSchemas.rulesVersion.parse(
+    contentHash({
+      commit,
+      files: hashTree(files),
+      pins: pins.map((pin) => ({ ref: pin.ref, sourceHash: pin.sourceHash })),
+    }),
+  );
+}
+
+function getValue<T>(checked: Checked<T>): T {
+  invariant(checked.value !== null, 'the loader builds rules only when every check passed');
+
+  return checked.value;
+}
+
+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,
+      },
+    ]),
+  );
+}
+
+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,
+    ]),
+  );
+}

package/src/parse-concept-entry.ts

@@ -0,0 +1,10 @@
+import type { ConceptEntry, ConceptName } from '@boxxy/model';
+
+export function parseConceptEntry(entry: ConceptEntry): {
+  readonly name: ConceptName;
+  readonly version: number;
+} {
+  const at = entry.lastIndexOf('@');
+
+  return { name: entry.slice(0, at), version: Number(entry.slice(at + 1)) };
+}

package/src/parse-rules-file.ts

@@ -0,0 +1,109 @@
+import type { LoadRejection } from '@boxxy/model';
+import { formatKeyPath } from '@boxxy/model';
+import { match } from 'ts-pattern';
+import type { Document } from 'yaml';
+import { parseDocument } from 'yaml';
+import type { ParsedRulesFile } from './rules-file-schema.ts';
+import { rulesFileSchema } from './rules-file-schema.ts';
+
+type RulesFileParse =
+  | { readonly kind: 'parsed'; readonly file: ParsedRulesFile }
+  | { readonly kind: 'rejected'; readonly rejections: readonly LoadRejection[] };
+
+export function parseRulesFile(fileName: string, bytes: Uint8Array): RulesFileParse {
+  return match(toText(bytes))
+    .with({ kind: 'refused' }, (refused): RulesFileParse => ({
+      kind: 'rejected',
+      rejections: [buildInvalid(fileName, '', refused.message)],
+    }))
+    .with({ kind: 'converted' }, (text) => parseRulesText(fileName, text.value))
+    .exhaustive();
+}
+
+type Converted<T> =
+  | { readonly kind: 'converted'; readonly value: T }
+  | { readonly kind: 'refused'; readonly message: string };
+
+function toText(bytes: Uint8Array): Converted<string> {
+  // TextDecoder reports bytes that aren't UTF-8 only by throwing, in its fatal mode
+  try {
+    return { kind: 'converted', value: new TextDecoder('utf-8', { fatal: true }).decode(bytes) };
+  } catch {
+    return { kind: 'refused', message: 'the file is not valid UTF-8' };
+  }
+}
+
+function buildInvalid(file: string, path: string, message: string): LoadRejection {
+  return { file, path, reason: { kind: 'invalid', message } };
+}
+
+function parseRulesText(fileName: string, text: string): RulesFileParse {
+  const document = parseDocument(text);
+
+  if (document.errors.length > 0) {
+    return {
+      kind: 'rejected',
+      rejections: document.errors.map((error) => buildInvalid(fileName, '', error.message)),
+    };
+  }
+
+  return match(toPlainValue(document))
+    .with({ kind: 'refused' }, (refused): RulesFileParse => ({
+      kind: 'rejected',
+      rejections: [buildInvalid(fileName, '', refused.message)],
+    }))
+    .with({ kind: 'converted' }, (plain) => parseRulesValue(fileName, plain.value))
+    .exhaustive();
+}
+
+function toPlainValue(document: Document): Converted<unknown> {
+  // yaml throws, and returns no error, on a document whose aliases expand past its alias limit
+  try {
+    const value: unknown = document.toJS();
+
+    return { kind: 'converted', value };
+  } catch (error) {
+    return { kind: 'refused', message: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function parseRulesValue(fileName: string, value: unknown): RulesFileParse {
+  // zod's record schema drops a `__proto__` key with no issue, so the loader would miss its value
+  const protoKeyPaths = collectProtoKeyPaths(value, []);
+
+  if (protoKeyPaths.length > 0) {
+    return {
+      kind: 'rejected',
+      rejections: protoKeyPaths.map((path) =>
+        buildInvalid(fileName, formatKeyPath(path), 'the key __proto__ is reserved'),
+      ),
+    };
+  }
+
+  const checked = rulesFileSchema.safeParse(value);
+
+  if (!checked.success) {
+    return {
+      kind: 'rejected',
+      rejections: checked.error.issues.map((issue) =>
+        buildInvalid(fileName, formatKeyPath(issue.path), issue.message),
+      ),
+    };
+  }
+
+  return { kind: 'parsed', file: checked.data };
+}
+
+function collectProtoKeyPaths(value: unknown, path: readonly PropertyKey[]): PropertyKey[][] {
+  if (Array.isArray(value)) {
+    return value.flatMap((item: unknown, index) => collectProtoKeyPaths(item, [...path, index]));
+  }
+
+  if (typeof value !== 'object' || value === null) {
+    return [];
+  }
+
+  return Object.entries(value).flatMap(([key, item]: [string, unknown]) =>
+    key === '__proto__' ? [[...path, key]] : collectProtoKeyPaths(item, [...path, key]),
+  );
+}

package/src/resolve-plugin.ts

@@ -0,0 +1,51 @@
+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';
+
+export function resolvePlugin<K extends ParamKindName>(
+  registered: Registered<K>,
+  params: JsonValue,
+  key: string,
+  path: readonly PropertyKey[],
+): Checked<Resolved<K>> {
+  return registered.open((plugin): Checked<Resolved<K>> => {
+    const checked = plugin.params.safeParse(params);
+
+    if (!checked.success) {
+      return {
+        value: null,
+        rejections: [
+          buildRejection(path, {
+            kind: 'bad-plugin-params',
+            pluginKind: registered.kind,
+            name: registered.name,
+            message: formatIssues(checked.error.issues),
+          }),
+        ],
+      };
+    }
+
+    const parsedParams = checked.data;
+
+    return {
+      value: {
+        kind: registered.kind,
+        name: registered.name,
+        key,
+        open: (use) => use(plugin, parsedParams),
+      },
+      rejections: [],
+    };
+  });
+}
+
+function formatIssues(issues: readonly z.core.$ZodIssue[]): string {
+  return issues
+    .map((issue) =>
+      issue.path.length > 0 ? `${formatKeyPath(issue.path)}: ${issue.message}` : issue.message,
+    )
+    .join('; ');
+}

package/src/resolve-signal-ref.ts

@@ -0,0 +1,43 @@
+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 { resolvePlugin } from './resolve-plugin.ts';
+import type { Checked, ResolvedSignal } from './types.ts';
+
+export function resolveSignalRef(
+  ref: SignalRef,
+  path: readonly PropertyKey[],
+  registry: Registry,
+): Checked<ResolvedSignal> {
+  const parts = toPluginRefParts(ref);
+  const registered = registry.signal.get(parts.name);
+
+  if (registered === undefined) {
+    return {
+      value: null,
+      rejections: [buildRejection(path, { kind: 'unknown-signal', signal: parts.name })],
+    };
+  }
+
+  const key = signalKey(parts.name, parts.params);
+  const checked = resolvePlugin(registered, parts.params, key, path);
+
+  return {
+    value: checked.value === null ? null : { key, resolved: checked.value },
+    rejections: checked.rejections,
+  };
+}
+
+function toPluginRefParts(ref: SignalRef): { readonly name: string; readonly params: JsonValue } {
+  if (typeof ref === 'string') {
+    return { name: ref, params: {} };
+  }
+
+  const [entry] = Object.entries(ref);
+
+  invariant(entry, 'the rules file schema gives a plug-in reference with parameters one key');
+
+  return { name: entry[0], params: entry[1] };
+}

package/src/rules-file-schema.ts

@@ -0,0 +1,112 @@
+import type { Effort, PipelineStep, RulesFile } 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 kindSchema = z
+  .strictObject({
+    pipeline: z.array(brandSchemas.phaseName).min(1),
+    maxAttempts: z.record(brandSchemas.phaseName, z.int().positive()),
+    recipes: z.record(brandSchemas.phaseName, brandSchemas.recipeName),
+  })
+  .transform((kind, ctx) => {
+    const steps: PipelineStep[] = [];
+
+    for (const phase of kind.pipeline) {
+      const maxAttempts = Object.hasOwn(kind.maxAttempts, phase)
+        ? kind.maxAttempts[phase]
+        : undefined;
+
+      if (maxAttempts === undefined) {
+        ctx.issues.push({
+          code: 'custom',
+          input: kind.maxAttempts,
+          path: ['maxAttempts', phase],
+          message: `the pipeline phase ${phase} has no maxAttempts`,
+        });
+      } else {
+        steps.push({ phase, maxAttempts });
+      }
+    }
+
+    return { ...kind, steps };
+  });
+
+const takesValueSchema = z.union([nameSchema, z.array(nameSchema).min(1)]);
+
+const poolSchema = z.strictObject({
+  name: brandSchemas.poolName,
+  slots: z.int().positive(),
+  takes: z.record(nameSchema, takesValueSchema),
+  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,
+});
+
+const conceptEntrySchema = z.templateLiteral([nameSchema, '@', z.int().positive()]);
+
+const propagationLineSchema = z.strictObject({
+  value: nameSchema,
+  over: brandSchemas.linkTypeName,
+  toward: z.enum(['source', 'target']),
+});
+
+export const rulesFileSchema = z
+  .strictObject({
+    version: z.literal(1),
+    concepts: z.array(conceptEntrySchema),
+    kinds: z.record(brandSchemas.itemKindName, kindSchema),
+    pools: z.array(poolSchema),
+    lead: z.array(pluginRefSchema),
+    propagation: z.array(propagationLineSchema),
+    recipes: z.record(brandSchemas.recipeName, recipeSchema),
+  })
+  .superRefine((file, ctx) => {
+    const conceptNames = file.concepts.map((entry) => parseConceptEntry(entry).name);
+    const poolNames: string[] = file.pools.map((pool) => pool.name);
+
+    for (const [index, name] of conceptNames.entries()) {
+      if (conceptNames.indexOf(name) !== index) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['concepts', index],
+          message: `the concept ${name} is pinned twice`,
+        });
+      }
+    }
+
+    for (const [index, name] of poolNames.entries()) {
+      if (poolNames.indexOf(name) !== index) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['pools', index, 'name'],
+          message: `the pool name ${name} is used twice`,
+        });
+      }
+    }
+  }) satisfies z.ZodType<RulesFile>;
+
+export type ParsedRulesFile = z.output<typeof rulesFileSchema>;
+
+function isCheckoutPath(path: string): boolean {
+  return path.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..');
+}

package/src/types.ts

@@ -0,0 +1,16 @@
+import type { Concept, LoadRejection, Resolved, SignalKey } from '@boxxy/model';
+
+export interface Checked<T> {
+  readonly value: T | null;
+  readonly rejections: readonly LoadRejection[];
+}
+
+export interface ResolvedSignal {
+  readonly key: SignalKey;
+  readonly resolved: Resolved<'signal'>;
+}
+
+export interface PinnedConcept {
+  readonly concept: Concept;
+  readonly entryIndex: number;
+}