@llm4ts/core 2.13.0 → 2.14.0

package/dist/blackboard/Run.d.ts

@@ -0,0 +1,84 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { Board, DuplicateFact, type Fact } from "./Fact.ts";
+import type { Ruleset } from "./Ruleset.ts";
+declare const Firing_base: Schema.Class<Firing, Schema.Struct<{
+    readonly rule: Schema.String;
+    readonly kind: Schema.Literals<readonly ["derive", "judge", "rule"]>;
+    readonly readKeys: Schema.$Array<Schema.String>;
+    readonly postedKeys: Schema.$Array<Schema.String>;
+    /** Epoch milliseconds. */
+    readonly startedAt: Schema.Number;
+    /** Milliseconds. */
+    readonly duration: Schema.Number;
+    /** `failed`: the consequence failed and `postedKeys` are the rule's defaults. */
+    readonly outcome: Schema.Literals<readonly ["posted", "failed"]>;
+    readonly judgment: Schema.optionalKey<Schema.Struct<{
+        readonly backend: Schema.String;
+        readonly identity: Schema.String;
+    }>>;
+}>, {}>;
+export declare class Firing extends Firing_base {
+}
+declare const RuleFailure_base: Schema.Class<RuleFailure, Schema.Struct<{
+    readonly rule: Schema.String;
+    readonly tag: Schema.String;
+    readonly message: Schema.String;
+    readonly error: Schema.Defect;
+}>, {}>;
+/**
+ * A rule's typed failure. `error` is the value itself while the result is in
+ * memory; `tag` and `message` are what survive encoding, since `Defect`
+ * encodes any error as a plain one.
+ */
+export declare class RuleFailure extends RuleFailure_base {
+}
+declare const RunResult_base: Schema.Class<RunResult, Schema.Struct<{
+    readonly board: typeof Board;
+    readonly trace: Schema.$Array<typeof Firing>;
+    readonly failures: Schema.$Array<typeof RuleFailure>;
+}>, {}>;
+export declare class RunResult extends RunResult_base {
+}
+declare const UndeclaredFact_base: Schema.Class<UndeclaredFact, Schema.TaggedStruct<"UndeclaredFact", {
+    readonly rule: Schema.String;
+    readonly key: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class UndeclaredFact extends UndeclaredFact_base {
+    get message(): string;
+}
+declare const MissingImport_base: Schema.Class<MissingImport, Schema.TaggedStruct<"MissingImport", {
+    readonly keys: Schema.$Array<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+export declare class MissingImport extends MissingImport_base {
+    get message(): string;
+}
+declare const WaitingRule_base: Schema.Class<WaitingRule, Schema.Struct<{
+    readonly rule: Schema.String;
+    readonly missingKeys: Schema.$Array<Schema.String>;
+}>, {}>;
+export declare class WaitingRule extends WaitingRule_base {
+}
+declare const MissingExport_base: Schema.Class<MissingExport, Schema.Struct<{
+    readonly key: Schema.String;
+    readonly waitingRules: Schema.$Array<typeof WaitingRule>;
+    /** Producers that fired, failed or were vetoed by `when` without posting the key. */
+    readonly silentRules: Schema.$Array<Schema.String>;
+}>, {}>;
+/** Why an export is missing: who still waits, and who ran and did not post it. */
+export declare class MissingExport extends MissingExport_base {
+}
+declare const ExportsMissing_base: Schema.Class<ExportsMissing, Schema.TaggedStruct<"ExportsMissing", {
+    readonly missing: Schema.$Array<typeof MissingExport>;
+    /** What did run, so a stall can be explained. */
+    readonly trace: Schema.$Array<typeof Firing>;
+    readonly failures: Schema.$Array<typeof RuleFailure>;
+}>, import("effect/Cause").YieldableError>;
+export declare class ExportsMissing extends ExportsMissing_base {
+    get message(): string;
+}
+export declare const RunError: Schema.Union<readonly [typeof DuplicateFact, typeof UndeclaredFact, typeof MissingImport, typeof ExportsMissing]>;
+export type RunError = typeof RunError.Type;
+export declare const runRuleset: <E, R>(ruleset: Ruleset<E, R>, initial: ReadonlyArray<Fact>) => Effect.Effect<RunResult, RunError, R>;
+export {};
+//# sourceMappingURL=Run.d.ts.map

package/dist/blackboard/Run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Run.d.ts","sourceRoot":"","sources":["../../src/blackboard/Run.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,KAAK,EAAE,aAAa,EAAa,KAAK,IAAI,EAAE,MAAM,WAAW,CAAA;AAEtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;;;;;;IAiBzC,0BAA0B;;IAE1B,oBAAoB;;IAEpB,iFAAiF;;;;;;;AATnF,qBAAa,MAAO,SAAQ,WAY1B;CAAG;;;;;;;AAEL;;;;GAIG;AACH,qBAAa,WAAY,SAAQ,gBAK/B;CAAG;;;;;;AAaL,qBAAa,SAAU,SAAQ,cAI7B;CAAG;;;;;AAEL,qBAAa,cAAe,SAAQ,mBAGlC;IACA,IAAI,OAAO,IAAI,MAAM,CAEpB;CACF;;;;AAED,qBAAa,aAAc,SAAQ,kBAEjC;IACA,IAAI,OAAO,IAAI,MAAM,CAEpB;CACF;;;;;AAED,qBAAa,WAAY,SAAQ,gBAG/B;CAAG;;;;IAMH,qFAAqF;;;AAJvF,kFAAkF;AAClF,qBAAa,aAAc,SAAQ,kBAKjC;CAAG;;;IAIH,iDAAiD;;;;AAFnD,qBAAa,cAAe,SAAQ,mBAKlC;IACA,IAAI,OAAO,IAAI,MAAM,CAapB;CACF;AAED,eAAO,MAAM,QAAQ,mHAA+E,CAAA;AACpG,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAmD3C,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,CAAC,EAC7B,SAAS,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,EACtB,SAAS,aAAa,CAAC,IAAI,CAAC,KAC3B,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,QAAQ,EAAE,CAAC,CAiFnC,CAAA"}

package/dist/blackboard/Run.js

@@ -0,0 +1,195 @@
+import * as Clock from "effect/Clock";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { Board, DuplicateFact, writeOnce } from "./Fact.js";
+/**
+ * Forward chaining in rounds (ADR 0020). A round fires, concurrently, every
+ * rule whose condition is satisfied by the current snapshot; the facts they
+ * post are then applied one by one, write-once. The run ends when a round
+ * fires nothing, and it succeeds only if every export is on the board. A
+ * rule's failure is recorded and its defaults posted; a defect fails the run.
+ */
+const JudgmentNote = Schema.Struct({ backend: Schema.String, identity: Schema.String });
+export class Firing extends Schema.Class("Firing")({
+    rule: Schema.String,
+    kind: Schema.Literals(["derive", "judge", "rule"]),
+    readKeys: Schema.Array(Schema.String),
+    postedKeys: Schema.Array(Schema.String),
+    /** Epoch milliseconds. */
+    startedAt: Schema.Number,
+    /** Milliseconds. */
+    duration: Schema.Number,
+    /** `failed`: the consequence failed and `postedKeys` are the rule's defaults. */
+    outcome: Schema.Literals(["posted", "failed"]),
+    judgment: Schema.optionalKey(JudgmentNote)
+}) {
+}
+/**
+ * A rule's typed failure. `error` is the value itself while the result is in
+ * memory; `tag` and `message` are what survive encoding, since `Defect`
+ * encodes any error as a plain one.
+ */
+export class RuleFailure extends Schema.Class("RuleFailure")({
+    rule: Schema.String,
+    tag: Schema.String,
+    message: Schema.String,
+    error: Schema.Defect()
+}) {
+}
+const isTagged = (error) => typeof error === "object" && error !== null && "_tag" in error && typeof error._tag === "string";
+const ruleFailure = (rule, error) => RuleFailure.make({
+    rule,
+    tag: isTagged(error) ? error._tag : error instanceof Error ? error.name : typeof error,
+    message: error instanceof Error ? error.message : String(error),
+    error
+});
+export class RunResult extends Schema.Class("RunResult")({
+    board: Board,
+    trace: Schema.Array(Firing),
+    failures: Schema.Array(RuleFailure)
+}) {
+}
+export class UndeclaredFact extends Schema.TaggedError()("UndeclaredFact", {
+    rule: Schema.String,
+    key: Schema.String
+}) {
+    get message() {
+        return `rule ${this.rule} posted "${this.key}", which it does not declare`;
+    }
+}
+export class MissingImport extends Schema.TaggedError()("MissingImport", {
+    keys: Schema.Array(Schema.String)
+}) {
+    get message() {
+        return `initial facts miss the imports: ${this.keys.join(", ")}`;
+    }
+}
+export class WaitingRule extends Schema.Class("WaitingRule")({
+    rule: Schema.String,
+    missingKeys: Schema.Array(Schema.String)
+}) {
+}
+/** Why an export is missing: who still waits, and who ran and did not post it. */
+export class MissingExport extends Schema.Class("MissingExport")({
+    key: Schema.String,
+    waitingRules: Schema.Array(WaitingRule),
+    /** Producers that fired, failed or were vetoed by `when` without posting the key. */
+    silentRules: Schema.Array(Schema.String)
+}) {
+}
+export class ExportsMissing extends Schema.TaggedError()("ExportsMissing", {
+    missing: Schema.Array(MissingExport),
+    /** What did run, so a stall can be explained. */
+    trace: Schema.Array(Firing),
+    failures: Schema.Array(RuleFailure)
+}) {
+    get message() {
+        const reasons = this.missing.map((entry) => {
+            const waiting = entry.waitingRules.map((rule) => `${rule.rule} waits for ${rule.missingKeys.join(", ")}`);
+            const silent = entry.silentRules.map((rule) => `${rule} fired without posting it`);
+            return `"${entry.key}" (${[...waiting, ...silent].join("; ")})`;
+        });
+        const failed = this.failures.length === 0
+            ? ""
+            : `; failed: ${this.failures.map((f) => `${f.rule} (${f.tag})`).join(", ")}`;
+        return `the run ended without: ${reasons.join(", ")}${failed}`;
+    }
+}
+export const RunError = Schema.Union([DuplicateFact, UndeclaredFact, MissingImport, ExportsMissing]);
+/** Apply posted facts write-once; the keys actually written, in first-seen order. */
+const post = (facts, rule, allowed, posted) => Effect.gen(function* () {
+    let current = facts;
+    const keys = [];
+    for (const fact of posted) {
+        if (!allowed.includes(fact.key)) {
+            return yield* Effect.fail(UndeclaredFact.make({ rule, key: fact.key }));
+        }
+        const written = writeOnce(current, fact.key, yield* fact.encoded);
+        if (Result.isFailure(written))
+            return yield* Effect.fail(written.failure);
+        current = written.success;
+        if (!keys.includes(fact.key))
+            keys.push(fact.key);
+    }
+    return [current, keys];
+});
+const fireAll = (ready) => Effect.forEach(ready, ({ rule, firing }) => Effect.gen(function* () {
+    const startedAt = yield* Clock.currentTimeMillis;
+    const result = yield* Effect.result(firing);
+    const finishedAt = yield* Clock.currentTimeMillis;
+    return { rule, startedAt, duration: finishedAt - startedAt, result };
+}), { concurrency: "unbounded" });
+export const runRuleset = (ruleset, initial) => Effect.gen(function* () {
+    const initialKeys = initial.map((fact) => fact.key);
+    const missingImports = ruleset.imports.filter((key) => !initialKeys.includes(key));
+    if (missingImports.length > 0) {
+        return yield* Effect.fail(MissingImport.make({ keys: missingImports }));
+    }
+    let [facts] = yield* post(new Map(), "(initial)", ruleset.imports, initial);
+    const pending = new Map(ruleset.rules.map((rule) => [rule.name, rule]));
+    const trace = [];
+    const failures = [];
+    for (;;) {
+        const ready = [];
+        for (const rule of pending.values()) {
+            if (!rule.reads.every((key) => facts.has(key)))
+                continue;
+            const prepared = yield* rule.prepare(facts);
+            // Every read is present and facts never change, so a None now is a No forever.
+            pending.delete(rule.name);
+            if (Option.isSome(prepared))
+                ready.push({ rule, firing: prepared.value });
+        }
+        if (ready.length === 0)
+            break;
+        const outcomes = yield* fireAll(ready);
+        for (const outcome of outcomes) {
+            const failed = Result.isFailure(outcome.result);
+            if (Result.isFailure(outcome.result)) {
+                failures.push(ruleFailure(outcome.rule.name, outcome.result.failure));
+            }
+            const posted = Result.isSuccess(outcome.result)
+                ? outcome.result.success
+                : { facts: outcome.rule.defaults };
+            const [next, postedKeys] = yield* post(facts, outcome.rule.name, outcome.rule.produces, posted.facts);
+            facts = next;
+            trace.push(Firing.make({
+                rule: outcome.rule.name,
+                kind: outcome.rule.kind,
+                readKeys: outcome.rule.reads,
+                postedKeys,
+                startedAt: outcome.startedAt,
+                duration: outcome.duration,
+                outcome: failed ? "failed" : "posted",
+                ...(posted.judgment === undefined ? {} : { judgment: posted.judgment })
+            }));
+        }
+    }
+    const missing = ruleset.exports.filter((key) => !facts.has(key));
+    if (missing.length > 0) {
+        return yield* Effect.fail(ExportsMissing.make({
+            missing: missing.map((key) => MissingExport.make({
+                key,
+                waitingRules: [...pending.values()]
+                    .filter((rule) => rule.produces.includes(key))
+                    .map((rule) => WaitingRule.make({
+                    rule: rule.name,
+                    missingKeys: rule.reads.filter((read) => !facts.has(read))
+                })),
+                silentRules: ruleset.rules
+                    .filter((rule) => rule.produces.includes(key) && !pending.has(rule.name))
+                    .map((rule) => rule.name)
+            })),
+            trace,
+            failures
+        }));
+    }
+    return RunResult.make({
+        board: Board.make({ facts: Object.fromEntries(facts) }),
+        trace,
+        failures
+    });
+});
+//# sourceMappingURL=Run.js.map

package/dist/blackboard/Run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Run.js","sourceRoot":"","sources":["../../src/blackboard/Run.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/core",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "description": "Effect-native LLM contracts, providers, tools, evaluation, and observability",
   "license": "MIT",
   "type": "module",
@@ -14,6 +14,10 @@
   ],
   "exports": {
     "./AgentSession": "./dist/AgentSession.js",
+    "./blackboard/Fact": "./dist/blackboard/Fact.js",
+    "./blackboard/Rule": "./dist/blackboard/Rule.js",
+    "./blackboard/Ruleset": "./dist/blackboard/Ruleset.js",
+    "./blackboard/Run": "./dist/blackboard/Run.js",
     "./Capability": "./dist/Capability.js",
     "./Connector": "./dist/Connector.js",
     "./ConnectorConfig": "./dist/ConnectorConfig.js",

package/src/blackboard/Fact.ts

@@ -0,0 +1,104 @@
+import * as Effect from "effect/Effect"
+import * as Result from "effect/Result"
+import * as Schema from "effect/Schema"
+
+/**
+ * Facts on a blackboard (ADR 0020). A key names a fact and carries its
+ * schema; the board holds facts in their encoded JSON form, so it persists
+ * as-is and a read decodes through the key's schema instead of asserting a
+ * type. A key is written once per run: an equal rewrite is a no-op, a
+ * different one is a `DuplicateFact`.
+ */
+
+export interface Fact {
+  readonly key: string
+  /** The value in the key's encoded form; a value typed `A` cannot fail to encode. */
+  readonly encoded: Effect.Effect<Schema.Json>
+}
+
+export interface FactKey<A> {
+  readonly name: string
+  of(value: A): Fact
+  /** Decode a stored value; the board only holds what a key encoded, so a failure is a defect. */
+  readonly read: (encoded: unknown) => Effect.Effect<A>
+}
+
+export const makeKey = <A, I>(name: string, schema: Schema.Codec<A, I>): FactKey<A> => {
+  const encode = Schema.encodeEffect(schema)
+  const decode = Schema.decodeUnknownEffect(schema)
+  const json = Schema.decodeUnknownEffect(Schema.Json)
+  return {
+    name,
+    of: (value) => ({
+      key: name,
+      encoded: encode(value).pipe(Effect.flatMap(json), Effect.orDie)
+    }),
+    read: (encoded) => decode(encoded).pipe(Effect.orDie)
+  }
+}
+
+export class MissingFact extends Schema.TaggedError<MissingFact>()("MissingFact", {
+  key: Schema.String
+}) {
+  get message(): string {
+    return `fact "${this.key}" is not on the board`
+  }
+}
+
+export class DuplicateFact extends Schema.TaggedError<DuplicateFact>()("DuplicateFact", {
+  key: Schema.String
+}) {
+  get message(): string {
+    return `fact "${this.key}" was posted twice with different values`
+  }
+}
+
+export class Board extends Schema.Class<Board>("Board")({
+  facts: Schema.Record(Schema.String, Schema.Json)
+}) {
+  static readonly empty: Board = Board.make({ facts: {} })
+
+  has(name: string): boolean {
+    return Object.hasOwn(this.facts, name)
+  }
+
+  get<A>(key: FactKey<A>): Effect.Effect<A, MissingFact> {
+    return this.has(key.name)
+      ? key.read(this.facts[key.name])
+      : Effect.fail(MissingFact.make({ key: key.name }))
+  }
+}
+
+const isObject = (value: Schema.Json): value is { readonly [key: string]: Schema.Json } =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+
+/** Structural JSON equality: arrays ordered, object keys not. */
+export const sameJson = (a: Schema.Json, b: Schema.Json): boolean => {
+  if (a === b) return true
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((item, index) => sameJson(item, b[index] ?? null))
+  }
+  if (isObject(a) && isObject(b)) {
+    const keysA = Object.keys(a)
+    const keysB = Object.keys(b)
+    return (
+      keysA.length === keysB.length &&
+      keysA.every((key) => Object.hasOwn(b, key) && sameJson(a[key] ?? null, b[key] ?? null))
+    )
+  }
+  return false
+}
+
+/** The board after a write: unchanged for an equal rewrite, extended for a new key. */
+export const writeOnce = (
+  facts: ReadonlyMap<string, Schema.Json>,
+  key: string,
+  value: Schema.Json
+): Result.Result<ReadonlyMap<string, Schema.Json>, DuplicateFact> => {
+  if (!facts.has(key)) {
+    return Result.succeed(new Map(facts).set(key, value))
+  }
+  return sameJson(facts.get(key) ?? null, value)
+    ? Result.succeed(facts)
+    : Result.fail(DuplicateFact.make({ key }))
+}

package/src/blackboard/Rule.ts

@@ -0,0 +1,201 @@
+import * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
+import type * as Schema from "effect/Schema"
+import { Judgment, type JudgmentBackendError, type JudgmentInput } from "../judgment/Judgment.ts"
+import type { JudgmentResult } from "../judgment/Schemas.ts"
+import type { Fact, FactKey } from "./Fact.ts"
+
+/**
+ * Rules of a blackboard (ADR 0020). A condition names the keys it reads
+ * (what validation and pruning reason on) and evaluates to the typed value
+ * a consequence receives; a rule pairs a condition with a consequence that
+ * posts facts. Facts are write-once, so a rule fires at most once per run.
+ */
+
+/** A snapshot of the board: encoded facts by key. */
+export type Facts = ReadonlyMap<string, Schema.Json>
+
+export interface Condition<A> {
+  readonly keys: ReadonlyArray<string>
+  /** None while a key is missing or a `when` predicate rejects the value. */
+  readonly evaluate: (facts: Facts) => Effect.Effect<Option.Option<A>>
+}
+
+export const on = <A>(key: FactKey<A>): Condition<A> => ({
+  keys: [key.name],
+  evaluate: (facts) =>
+    facts.has(key.name)
+      ? Effect.map(key.read(facts.get(key.name)), Option.some)
+      : Effect.succeed(Option.none())
+})
+
+/**
+ * Satisfied once every key is present; the value is the tuple of decoded
+ * values, in order. Typed by overload up to eight keys: one implementation
+ * over a loose tuple, so no assertion is needed to give each call its shape.
+ */
+export function all<A>(k1: FactKey<A>): Condition<readonly [A]>
+export function all<A, B>(k1: FactKey<A>, k2: FactKey<B>): Condition<readonly [A, B]>
+export function all<A, B, C>(
+  k1: FactKey<A>,
+  k2: FactKey<B>,
+  k3: FactKey<C>
+): Condition<readonly [A, B, C]>
+export function all<A, B, C, D>(
+  k1: FactKey<A>,
+  k2: FactKey<B>,
+  k3: FactKey<C>,
+  k4: FactKey<D>
+): Condition<readonly [A, B, C, D]>
+export function all<A, B, C, D, E>(
+  k1: FactKey<A>,
+  k2: FactKey<B>,
+  k3: FactKey<C>,
+  k4: FactKey<D>,
+  k5: FactKey<E>
+): Condition<readonly [A, B, C, D, E]>
+export function all<A, B, C, D, E, F>(
+  k1: FactKey<A>,
+  k2: FactKey<B>,
+  k3: FactKey<C>,
+  k4: FactKey<D>,
+  k5: FactKey<E>,
+  k6: FactKey<F>
+): Condition<readonly [A, B, C, D, E, F]>
+export function all<A, B, C, D, E, F, G>(
+  k1: FactKey<A>,
+  k2: FactKey<B>,
+  k3: FactKey<C>,
+  k4: FactKey<D>,
+  k5: FactKey<E>,
+  k6: FactKey<F>,
+  k7: FactKey<G>
+): Condition<readonly [A, B, C, D, E, F, G]>
+export function all<A, B, C, D, E, F, G, H>(
+  k1: FactKey<A>,
+  k2: FactKey<B>,
+  k3: FactKey<C>,
+  k4: FactKey<D>,
+  k5: FactKey<E>,
+  k6: FactKey<F>,
+  k7: FactKey<G>,
+  k8: FactKey<H>
+): Condition<readonly [A, B, C, D, E, F, G, H]>
+export function all(...keys: ReadonlyArray<FactKey<unknown>>): Condition<ReadonlyArray<unknown>> {
+  return {
+    keys: keys.map((key) => key.name),
+    evaluate: (facts) =>
+      keys.every((key) => facts.has(key.name))
+        ? Effect.map(
+            Effect.forEach(keys, (key) => key.read(facts.get(key.name))),
+            (values) => Option.some(values)
+          )
+        : Effect.succeed(Option.none())
+  }
+}
+
+export const when = <A>(
+  condition: Condition<A>,
+  predicate: (value: A) => boolean
+): Condition<A> => ({
+  keys: condition.keys,
+  evaluate: (facts) =>
+    Effect.map(condition.evaluate(facts), (value) =>
+      Option.isSome(value) && predicate(value.value) ? value : Option.none()
+    )
+})
+
+export interface JudgmentNote {
+  readonly backend: string
+  readonly identity: string
+}
+
+export interface Posted {
+  readonly facts: ReadonlyArray<Fact>
+  /** Set by `judge`: which backend and checkpoint answered, for the trace. */
+  readonly judgment?: JudgmentNote
+}
+
+export type RuleKind = "derive" | "judge" | "rule"
+
+export interface Rule<E = never, R = never> {
+  readonly name: string
+  readonly kind: RuleKind
+  readonly reads: ReadonlyArray<string>
+  /** The keys this rule may post; posting another is an `UndeclaredFact`. */
+  readonly produces: ReadonlyArray<string>
+  /** Posted instead when the consequence fails. */
+  readonly defaults: ReadonlyArray<Fact>
+  /** Some(firing) when the condition is satisfied against the snapshot. */
+  readonly prepare: (facts: Facts) => Effect.Effect<Option.Option<Effect.Effect<Posted, E, R>>>
+}
+
+export interface RuleOptions<A, E, R> {
+  readonly name: string
+  readonly condition: Condition<A>
+  readonly produces: ReadonlyArray<FactKey<unknown>>
+  readonly consequence: (value: A) => Effect.Effect<ReadonlyArray<Fact>, E, R>
+  readonly defaults?: ReadonlyArray<Fact>
+  readonly kind?: RuleKind
+}
+
+export const rule = <A, E, R>(options: RuleOptions<A, E, R>): Rule<E, R> =>
+  makeRule(options, (value) => Effect.map(options.consequence(value), (facts) => ({ facts })))
+
+/** The general constructor other constructors build on: the firing may annotate the trace. */
+export const makeRule = <A, E, R>(
+  options: Omit<RuleOptions<A, E, R>, "consequence">,
+  fire: (value: A) => Effect.Effect<Posted, E, R>
+): Rule<E, R> => ({
+  name: options.name,
+  kind: options.kind ?? "rule",
+  reads: options.condition.keys,
+  produces: options.produces.map((key) => key.name),
+  defaults: options.defaults ?? [],
+  prepare: (facts) =>
+    Effect.map(options.condition.evaluate(facts), (value) =>
+      Option.isSome(value) ? Option.some(fire(value.value)) : Option.none()
+    )
+})
+
+export interface DeriveOptions<A> {
+  readonly name: string
+  readonly condition: Condition<A>
+  readonly produces: ReadonlyArray<FactKey<unknown>>
+  readonly derive: (value: A) => ReadonlyArray<Fact>
+}
+
+/** A pure, deterministic rule. */
+export const derive = <A>(options: DeriveOptions<A>): Rule =>
+  makeRule({ ...options, kind: "derive" }, (value) =>
+    Effect.succeed({ facts: options.derive(value) })
+  )
+
+export interface JudgeOptions<A> {
+  readonly name: string
+  readonly condition: Condition<A>
+  readonly produces: ReadonlyArray<FactKey<unknown>>
+  /** The State and Questions for this firing; `state` is data, never instructions. */
+  readonly ask: (value: A) => JudgmentInput
+  /**
+   * Facts from the typed result. Post the `Answer` itself (probability,
+   * support, origin), not a boolean read off it: deciding is another rule's
+   * job. Unanswered questions arrive in `result.failures`.
+   */
+  readonly post: (result: JudgmentResult, value: A) => ReadonlyArray<Fact>
+  /** Posted when the backend itself is unreachable or rejects the request. */
+  readonly defaults?: ReadonlyArray<Fact>
+}
+
+/** A rule that asks the Judgment service; its firing notes the backend and checkpoint for the trace. */
+export const judge = <A>(options: JudgeOptions<A>): Rule<JudgmentBackendError, Judgment> =>
+  makeRule({ ...options, kind: "judge" }, (value) =>
+    Effect.gen(function* () {
+      const judgment = yield* Judgment
+      const result = yield* judgment.judge(options.ask(value))
+      return {
+        facts: options.post(result, value),
+        judgment: { backend: judgment.backend, identity: judgment.identity }
+      }
+    })
+  )