@llm4ts/core 2.13.1 → 2.14.0

package/src/blackboard/Ruleset.ts

@@ -0,0 +1,216 @@
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import type { FactKey } from "./Fact.ts"
+import type { Rule } from "./Rule.ts"
+
+/**
+ * A ruleset (ADR 0020) is validated when it is built, not when it runs:
+ * every read is imported or produced, every export is produced, one
+ * producer per key, no constant or self-matching rule. Rules that cannot
+ * reach an export are pruned with a warning, so a company's ruleset never
+ * pays for a judgment nothing depends on. A valid ruleset is a value that
+ * runs many times.
+ */
+
+export const Problem = Schema.Union([
+  Schema.Struct({
+    kind: Schema.Literal("UnproducedMatch"),
+    rule: Schema.String,
+    key: Schema.String
+  }),
+  Schema.Struct({ kind: Schema.Literal("UnproducedExport"), key: Schema.String }),
+  Schema.Struct({
+    kind: Schema.Literal("ManyProducers"),
+    key: Schema.String,
+    rules: Schema.Array(Schema.String)
+  }),
+  Schema.Struct({ kind: Schema.Literal("EmptyCondition"), rule: Schema.String }),
+  Schema.Struct({ kind: Schema.Literal("SelfMatch"), rule: Schema.String, key: Schema.String }),
+  Schema.Struct({ kind: Schema.Literal("DuplicateRuleName"), rule: Schema.String }),
+  Schema.Struct({ kind: Schema.Literal("UnusedImport"), key: Schema.String }),
+  Schema.Struct({ kind: Schema.Literal("Unreachable"), rule: Schema.String })
+])
+export type Problem = typeof Problem.Type
+
+const warningKinds: ReadonlySet<Problem["kind"]> = new Set(["UnusedImport", "Unreachable"])
+
+export const isWarning = (problem: Problem): boolean => warningKinds.has(problem.kind)
+
+export const renderProblem = (problem: Problem): string => {
+  switch (problem.kind) {
+    case "UnproducedMatch":
+      return `rule ${problem.rule} reads "${problem.key}", which nothing imports or produces`
+    case "UnproducedExport":
+      return `export "${problem.key}" is produced by no rule`
+    case "ManyProducers":
+      return `"${problem.key}" has several producers: ${problem.rules.join(", ")}`
+    case "EmptyCondition":
+      return `rule ${problem.rule} reads nothing`
+    case "SelfMatch":
+      return `rule ${problem.rule} reads "${problem.key}", which it produces`
+    case "DuplicateRuleName":
+      return `two rules are named ${problem.rule}`
+    case "UnusedImport":
+      return `import "${problem.key}" is read by no rule`
+    case "Unreachable":
+      return `rule ${problem.rule} reaches no export and is not run`
+  }
+}
+
+export class RulesetInvalid extends Schema.TaggedError<RulesetInvalid>()("RulesetInvalid", {
+  name: Schema.String,
+  problems: Schema.Array(Problem)
+}) {
+  get message(): string {
+    return `ruleset "${this.name}" is invalid: ${this.problems.map(renderProblem).join("; ")}`
+  }
+}
+
+export interface RulesetOptions<Rs extends ReadonlyArray<Rule<unknown, unknown>>> {
+  readonly name: string
+  readonly imports: ReadonlyArray<FactKey<unknown>>
+  readonly exports: ReadonlyArray<FactKey<unknown>>
+  readonly rules: Rs
+}
+
+/** The union of the rules' error types, so a `judge` and a custom-error `rule` mix freely. */
+export type ErrorOf<Rs extends ReadonlyArray<Rule<unknown, unknown>>> =
+  Rs[number] extends Rule<infer E, unknown> ? E : never
+
+/** The union of the services the rules need. */
+export type RequirementsOf<Rs extends ReadonlyArray<Rule<unknown, unknown>>> =
+  Rs[number] extends Rule<unknown, infer R> ? R : never
+
+export interface Ruleset<E = never, R = never> {
+  readonly name: string
+  readonly imports: ReadonlyArray<string>
+  readonly exports: ReadonlyArray<string>
+  /** The rules that can reach an export, in the order given. */
+  readonly rules: ReadonlyArray<Rule<E, R>>
+  readonly warnings: ReadonlyArray<Problem>
+  /** One line per rule: `name: reads -> produces`. */
+  describe(): string
+  /** A Mermaid `flowchart LR` of keys and rules. */
+  mermaid(): string
+}
+
+const producersByKey = <E, R>(
+  imports: ReadonlyArray<string>,
+  rules: ReadonlyArray<Rule<E, R>>
+): ReadonlyMap<string, ReadonlyArray<string>> => {
+  const producers = new Map<string, ReadonlyArray<string>>()
+  for (const key of imports) producers.set(key, ["(import)"])
+  for (const rule of rules) {
+    for (const key of rule.produces) {
+      producers.set(key, [...(producers.get(key) ?? []), rule.name])
+    }
+  }
+  return producers
+}
+
+/** Rules whose products can reach an export, following reads backwards from the exports. */
+const reachable = <E, R>(
+  exports: ReadonlyArray<string>,
+  rules: ReadonlyArray<Rule<E, R>>
+): ReadonlySet<string> => {
+  const needed = new Set(exports)
+  const kept = new Set<string>()
+  let grew = true
+  while (grew) {
+    grew = false
+    for (const rule of rules) {
+      if (kept.has(rule.name) || !rule.produces.some((key) => needed.has(key))) continue
+      kept.add(rule.name)
+      for (const key of rule.reads) needed.add(key)
+      grew = true
+    }
+  }
+  return kept
+}
+
+const escapeLabel = (label: string): string => label.replaceAll('"', "'")
+
+const renderMermaid = <E, R>(name: string, rules: ReadonlyArray<Rule<E, R>>): string => {
+  const keys = [...new Set(rules.flatMap((rule) => [...rule.reads, ...rule.produces]))]
+  const keyId = new Map(keys.map((key, index) => [key, `k${index}`]))
+  const ruleId = new Map(rules.map((rule, index) => [rule.name, `r${index}`]))
+  const nodes = [
+    ...keys.map((key) => `  ${keyId.get(key)}(["${escapeLabel(key)}"])`),
+    ...rules.map((rule) => `  ${ruleId.get(rule.name)}["${escapeLabel(rule.name)}"]`)
+  ]
+  const edges = rules.flatMap((rule) => [
+    ...rule.reads.map((key) => `  ${keyId.get(key)} --> ${ruleId.get(rule.name)}`),
+    ...rule.produces.map((key) => `  ${ruleId.get(rule.name)} --> ${keyId.get(key)}`)
+  ])
+  return ["flowchart LR", `  %% ${escapeLabel(name)}`, ...nodes, ...edges].join("\n")
+}
+
+/**
+ * Typed by overload: the ruleset's error and service types are the unions
+ * over its rules, so a `judge` and a custom-error `rule` mix in one array.
+ * The implementation only needs names, so it works over loose rules.
+ */
+export function makeRuleset<const Rs extends ReadonlyArray<Rule<unknown, unknown>>>(
+  options: RulesetOptions<Rs>
+): Effect.Effect<Ruleset<ErrorOf<Rs>, RequirementsOf<Rs>>, RulesetInvalid>
+export function makeRuleset(
+  options: RulesetOptions<ReadonlyArray<Rule<unknown, unknown>>>
+): Effect.Effect<Ruleset<unknown, unknown>, RulesetInvalid> {
+  const given = options.rules
+  const imports = options.imports.map((key) => key.name)
+  const exports = options.exports.map((key) => key.name)
+  const problems: Array<Problem> = []
+  const seen = new Set<string>()
+  for (const rule of given) {
+    if (seen.has(rule.name)) problems.push({ kind: "DuplicateRuleName", rule: rule.name })
+    seen.add(rule.name)
+    if (rule.reads.length === 0) problems.push({ kind: "EmptyCondition", rule: rule.name })
+    for (const key of rule.reads) {
+      if (rule.produces.includes(key)) problems.push({ kind: "SelfMatch", rule: rule.name, key })
+    }
+  }
+  const producers = producersByKey(imports, given)
+  for (const [key, names] of producers) {
+    if (names.length > 1) problems.push({ kind: "ManyProducers", key, rules: names })
+  }
+  for (const rule of given) {
+    for (const key of rule.reads) {
+      if (!producers.has(key)) problems.push({ kind: "UnproducedMatch", rule: rule.name, key })
+    }
+  }
+  for (const key of exports) {
+    if (!producers.has(key)) problems.push({ kind: "UnproducedExport", key })
+  }
+  if (problems.length > 0) {
+    return Effect.fail(RulesetInvalid.make({ name: options.name, problems }))
+  }
+  const warnings: Array<Problem> = []
+  const kept = reachable(exports, given)
+  for (const rule of given) {
+    if (!kept.has(rule.name)) warnings.push({ kind: "Unreachable", rule: rule.name })
+  }
+  const rules = given.filter((rule) => kept.has(rule.name))
+  // An import only pruned rules read is unused too: nothing that runs needs it.
+  const read = new Set(rules.flatMap((rule) => rule.reads))
+  for (const key of imports) {
+    if (!read.has(key)) warnings.push({ kind: "UnusedImport", key })
+  }
+  return Effect.succeed({
+    name: options.name,
+    imports,
+    exports,
+    rules,
+    warnings,
+    describe: () =>
+      [
+        `ruleset ${options.name}`,
+        `imports: ${imports.join(", ")}`,
+        `exports: ${exports.join(", ")}`,
+        ...rules.map(
+          (rule) => `${rule.name}: ${rule.reads.join(", ")} -> ${rule.produces.join(", ")}`
+        ),
+        ...warnings.map((warning) => `warning: ${renderProblem(warning)}`)
+      ].join("\n"),
+    mermaid: () => renderMermaid(options.name, rules)
+  })
+}

package/src/blackboard/Run.ts

@@ -0,0 +1,251 @@
+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, type Fact } from "./Fact.ts"
+import type { Facts, Posted, Rule } from "./Rule.ts"
+import type { Ruleset } from "./Ruleset.ts"
+
+/**
+ * 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>("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>("RuleFailure")({
+  rule: Schema.String,
+  tag: Schema.String,
+  message: Schema.String,
+  error: Schema.Defect()
+}) {}
+
+const isTagged = (error: unknown): error is { readonly _tag: string } =>
+  typeof error === "object" && error !== null && "_tag" in error && typeof error._tag === "string"
+
+const ruleFailure = (rule: string, error: unknown): RuleFailure =>
+  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>("RunResult")({
+  board: Board,
+  trace: Schema.Array(Firing),
+  failures: Schema.Array(RuleFailure)
+}) {}
+
+export class UndeclaredFact extends Schema.TaggedError<UndeclaredFact>()("UndeclaredFact", {
+  rule: Schema.String,
+  key: Schema.String
+}) {
+  get message(): string {
+    return `rule ${this.rule} posted "${this.key}", which it does not declare`
+  }
+}
+
+export class MissingImport extends Schema.TaggedError<MissingImport>()("MissingImport", {
+  keys: Schema.Array(Schema.String)
+}) {
+  get message(): string {
+    return `initial facts miss the imports: ${this.keys.join(", ")}`
+  }
+}
+
+export class WaitingRule extends Schema.Class<WaitingRule>("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>("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>()("ExportsMissing", {
+  missing: Schema.Array(MissingExport),
+  /** What did run, so a stall can be explained. */
+  trace: Schema.Array(Firing),
+  failures: Schema.Array(RuleFailure)
+}) {
+  get message(): string {
+    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])
+export type RunError = typeof RunError.Type
+
+interface Ready<E, R> {
+  readonly rule: Rule<E, R>
+  readonly firing: Effect.Effect<Posted, E, R>
+}
+
+interface Outcome<E, R> {
+  readonly rule: Rule<E, R>
+  readonly startedAt: number
+  readonly duration: number
+  readonly result: Result.Result<Posted, E>
+}
+
+/** Apply posted facts write-once; the keys actually written, in first-seen order. */
+const post = (
+  facts: Facts,
+  rule: string,
+  allowed: ReadonlyArray<string>,
+  posted: ReadonlyArray<Fact>
+): Effect.Effect<[Facts, ReadonlyArray<string>], DuplicateFact | UndeclaredFact> =>
+  Effect.gen(function* () {
+    let current = facts
+    const keys: Array<string> = []
+    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 = <E, R>(
+  ready: ReadonlyArray<Ready<E, R>>
+): Effect.Effect<ReadonlyArray<Outcome<E, R>>, never, R> =>
+  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 = <E, R>(
+  ruleset: Ruleset<E, R>,
+  initial: ReadonlyArray<Fact>
+): Effect.Effect<RunResult, RunError, R> =>
+  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: Array<Firing> = []
+    const failures: Array<RuleFailure> = []
+    for (;;) {
+      const ready: Array<Ready<E, R>> = []
+      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: 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
+    })
+  })