@llm4ts/flow 0.1.0

package/src/Equiv.ts

@@ -0,0 +1,378 @@
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { Capabilities } from "@llm4ts/core/Capability"
+import type { ProcessExecutorShape } from "@llm4ts/core/ProcessExecutor"
+import { guarded } from "./CapabilityGuard.ts"
+import {
+  PlanParseError,
+  ProcessError,
+  UnsupportedSchemaVersion,
+  type FlowError
+} from "./FlowError.ts"
+import type { FlowEventsShape } from "./FlowEvents.ts"
+import type { ComparisonPolicy } from "./Pack.ts"
+import type { PlainFileStoreShape } from "./Persistence.ts"
+
+export const EquivTier = Schema.Literals(["generated", "captured"])
+export type EquivTier = typeof EquivTier.Type
+
+export const RecordObservation = Schema.Struct({
+  type: Schema.Literal("record"),
+  kind: Schema.String,
+  fields: Schema.Record(Schema.String, Schema.String)
+})
+export type RecordObservation = typeof RecordObservation.Type
+
+export const DbMutationObservation = Schema.Struct({
+  type: Schema.Literal("db"),
+  table: Schema.String,
+  op: Schema.String,
+  key: Schema.Record(Schema.String, Schema.String),
+  set: Schema.Record(Schema.String, Schema.String)
+})
+export type DbMutationObservation = typeof DbMutationObservation.Type
+
+export const MessageObservation = Schema.Struct({
+  type: Schema.Literal("message"),
+  topic: Schema.String,
+  key: Schema.String,
+  fields: Schema.Record(Schema.String, Schema.String)
+})
+export type MessageObservation = typeof MessageObservation.Type
+
+export const EquivObservation = Schema.Union([
+  RecordObservation,
+  DbMutationObservation,
+  MessageObservation
+])
+export type EquivObservation = typeof EquivObservation.Type
+
+export const Observations = Object.freeze({
+  record: (kind: string, fields: Readonly<Record<string, string>>): RecordObservation => ({
+    type: "record",
+    kind,
+    fields
+  }),
+  dbMutation: (
+    table: string,
+    op: string,
+    key: Readonly<Record<string, string>>,
+    set: Readonly<Record<string, string>>
+  ): DbMutationObservation => ({ type: "db", table, op, key, set }),
+  message: (
+    topic: string,
+    key: string,
+    fields: Readonly<Record<string, string>>
+  ): MessageObservation => ({ type: "message", topic, key, fields })
+})
+
+export class EquivVector extends Schema.Class<EquivVector>("EquivVector")({
+  schemaVersion: Schema.Int,
+  program: Schema.String,
+  id: Schema.String,
+  tier: EquivTier,
+  rules: Schema.Array(Schema.String),
+  inputs: Schema.Json,
+  observations: Schema.Array(EquivObservation)
+}) {}
+
+export const CurrentEquivSchema = 1
+
+export class MissingObservation extends Schema.TaggedClass<MissingObservation>()("Missing", {
+  expected: EquivObservation
+}) {}
+
+export class UnexpectedObservation extends Schema.TaggedClass<UnexpectedObservation>()(
+  "Unexpected",
+  {
+    actual: EquivObservation
+  }
+) {}
+
+export class ObservationFieldDiff extends Schema.TaggedClass<ObservationFieldDiff>()("FieldDiff", {
+  at: Schema.String,
+  field: Schema.String,
+  expected: Schema.String,
+  actual: Schema.String
+}) {}
+
+export const EquivMismatch = Schema.Union([
+  MissingObservation,
+  UnexpectedObservation,
+  ObservationFieldDiff
+])
+export type EquivMismatch = typeof EquivMismatch.Type
+
+const sortedEntries = (
+  record: Readonly<Record<string, string>>
+): ReadonlyArray<readonly [string, string]> =>
+  Object.entries(record).sort(([left], [right]) => left.localeCompare(right))
+
+const identityOf = (observation: EquivObservation): string => {
+  switch (observation.type) {
+    case "record":
+      return `record ${observation.kind}`
+    case "message":
+      return `message ${observation.topic} ${observation.key}`
+    case "db":
+      return `db ${observation.table} ${observation.op} ${sortedEntries(observation.key)
+        .map(([key, value]) => `${key}=${value}`)
+        .join(",")}`
+  }
+}
+
+const fieldsOf = (observation: EquivObservation): Readonly<Record<string, string>> =>
+  observation.type === "db" ? observation.set : observation.fields
+
+const canonical = (observation: EquivObservation): string =>
+  JSON.stringify({
+    ...observation,
+    ...(observation.type === "db"
+      ? {
+          key: Object.fromEntries(sortedEntries(observation.key)),
+          set: Object.fromEntries(sortedEntries(observation.set))
+        }
+      : { fields: Object.fromEntries(sortedEntries(observation.fields)) })
+  })
+
+const scrub = (observation: EquivObservation, ignore: ReadonlySet<string>): EquivObservation => {
+  const omit = (fields: Readonly<Record<string, string>>): Readonly<Record<string, string>> =>
+    Object.fromEntries(Object.entries(fields).filter(([key]) => !ignore.has(key)))
+  switch (observation.type) {
+    case "record":
+      return Observations.record(observation.kind, omit(observation.fields))
+    case "message":
+      return Observations.message(observation.topic, observation.key, omit(observation.fields))
+    case "db":
+      return Observations.dbMutation(
+        observation.table,
+        observation.op,
+        omit(observation.key),
+        omit(observation.set)
+      )
+  }
+}
+
+const fieldDiffs = (
+  expected: EquivObservation,
+  actual: EquivObservation
+): ReadonlyArray<EquivMismatch> => {
+  const expectedFields = fieldsOf(expected)
+  const actualFields = fieldsOf(actual)
+  return [...new Set([...Object.keys(expectedFields), ...Object.keys(actualFields)])]
+    .sort()
+    .flatMap((field) =>
+      expectedFields[field] === actualFields[field]
+        ? []
+        : [
+            ObservationFieldDiff.make({
+              at: identityOf(expected),
+              field,
+              expected: expectedFields[field] ?? "(absent)",
+              actual: actualFields[field] ?? "(absent)"
+            })
+          ]
+    )
+}
+
+const positionalDiff = (
+  expected: ReadonlyArray<EquivObservation>,
+  actual: ReadonlyArray<EquivObservation>
+): ReadonlyArray<EquivMismatch> => {
+  const result: Array<EquivMismatch> = []
+  const maximum = Math.max(expected.length, actual.length)
+  for (let index = 0; index < maximum; index += 1) {
+    const expectedItem = expected[index]
+    const actualItem = actual[index]
+    if (expectedItem === undefined && actualItem !== undefined) {
+      result.push(UnexpectedObservation.make({ actual: actualItem }))
+    } else if (expectedItem !== undefined && actualItem === undefined) {
+      result.push(MissingObservation.make({ expected: expectedItem }))
+    } else if (expectedItem !== undefined && actualItem !== undefined) {
+      if (canonical(expectedItem) === canonical(actualItem)) {
+        continue
+      }
+      if (identityOf(expectedItem) === identityOf(actualItem)) {
+        result.push(...fieldDiffs(expectedItem, actualItem))
+      } else {
+        result.push(MissingObservation.make({ expected: expectedItem }))
+        result.push(UnexpectedObservation.make({ actual: actualItem }))
+      }
+    }
+  }
+  return result
+}
+
+export const diffObservations = (
+  expected: ReadonlyArray<EquivObservation>,
+  actual: ReadonlyArray<EquivObservation>,
+  policy: ComparisonPolicy
+): ReadonlyArray<EquivMismatch> => {
+  const expectedScrubbed = expected.map((item) => scrub(item, policy.ignore))
+  const actualScrubbed = actual.map((item) => scrub(item, policy.ignore))
+  if (policy.ordering === "Ordered") {
+    return positionalDiff(expectedScrubbed, actualScrubbed)
+  }
+  if (policy.ordering === "PerKey") {
+    const keys = [
+      ...new Set([...expectedScrubbed.map(identityOf), ...actualScrubbed.map(identityOf)])
+    ].sort()
+    return keys.flatMap((key) =>
+      positionalDiff(
+        expectedScrubbed.filter((item) => identityOf(item) === key),
+        actualScrubbed.filter((item) => identityOf(item) === key)
+      )
+    )
+  }
+
+  const remainingActual = [...actualScrubbed]
+  const unmatchedExpected: Array<EquivObservation> = []
+  for (const item of expectedScrubbed) {
+    const index = remainingActual.findIndex((candidate) => canonical(candidate) === canonical(item))
+    if (index < 0) {
+      unmatchedExpected.push(item)
+    } else {
+      remainingActual.splice(index, 1)
+    }
+  }
+  const mismatches: Array<EquivMismatch> = []
+  const missing: Array<EquivObservation> = []
+  for (const item of unmatchedExpected) {
+    const index = remainingActual.findIndex(
+      (candidate) => identityOf(candidate) === identityOf(item)
+    )
+    const matching = index < 0 ? undefined : remainingActual[index]
+    if (matching === undefined) {
+      missing.push(item)
+    } else {
+      mismatches.push(...fieldDiffs(item, matching))
+      remainingActual.splice(index, 1)
+    }
+  }
+  return [
+    ...mismatches,
+    ...missing.map((expectedItem) => MissingObservation.make({ expected: expectedItem })),
+    ...remainingActual.map((actualItem) => UnexpectedObservation.make({ actual: actualItem }))
+  ]
+}
+
+export class ReplayedObserved extends Schema.TaggedClass<ReplayedObserved>()("Observed", {
+  actual: Schema.Array(EquivObservation)
+}) {}
+
+export class ReplayedCrashed extends Schema.TaggedClass<ReplayedCrashed>()("Crashed", {
+  exitCode: Schema.Int,
+  problem: Schema.String
+}) {}
+
+export const Replayed = Schema.Union([ReplayedObserved, ReplayedCrashed])
+export type Replayed = typeof Replayed.Type
+
+const vectorCodec = Schema.fromJsonString(EquivVector)
+const observationsCodec = Schema.fromJsonString(Schema.Array(EquivObservation))
+
+export const writeEquivVectors = Effect.fn("@llm4ts/flow/Equiv.writeVectors")(function* (
+  files: PlainFileStoreShape,
+  path: string,
+  vectors: ReadonlyArray<EquivVector>
+): Effect.fn.Return<void, FlowError> {
+  const lines = yield* Effect.forEach(
+    vectors,
+    (vector) =>
+      Schema.encodeEffect(vectorCodec)(vector).pipe(
+        Effect.mapError((error) =>
+          PlanParseError.make({
+            message: `failed to encode equivalence vector: ${String(error)}`
+          })
+        )
+      ),
+    { concurrency: 1 }
+  )
+  yield* files.writeAtomic(path, `${lines.join("\n")}\n`)
+})
+
+export const readEquivVectors = Effect.fn("@llm4ts/flow/Equiv.readVectors")(function* (
+  files: PlainFileStoreShape,
+  path: string
+): Effect.fn.Return<ReadonlyArray<EquivVector>, FlowError> {
+  const contents = yield* files.read(path)
+  if (contents === undefined) {
+    return []
+  }
+  const vectors = yield* Effect.forEach(
+    contents
+      .split(/\r?\n/u)
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0),
+    (line, index) =>
+      Schema.decodeUnknownEffect(vectorCodec)(line).pipe(
+        Effect.mapError((error) =>
+          PlanParseError.make({
+            message: `malformed vector at ${path}:${index + 1}: ${String(error)}`
+          })
+        )
+      ),
+    { concurrency: 1 }
+  )
+  for (const vector of vectors) {
+    if (vector.schemaVersion !== CurrentEquivSchema) {
+      return yield* UnsupportedSchemaVersion.make({
+        path,
+        expected: CurrentEquivSchema,
+        actual: vector.schemaVersion
+      })
+    }
+  }
+  return vectors
+})
+
+export const replayEquivVector = Effect.fn("@llm4ts/flow/Equiv.replayVector")(function* (
+  process: ProcessExecutorShape,
+  events: FlowEventsShape,
+  command: ReadonlyArray<string>,
+  root: string,
+  vector: EquivVector
+): Effect.fn.Return<Replayed, FlowError> {
+  const executable = command[0]
+  if (executable === undefined) {
+    return yield* ProcessError.make({
+      message: "replay",
+      detail: "empty replay command"
+    })
+  }
+  const input = yield* Schema.encodeEffect(vectorCodec)(vector).pipe(
+    Effect.mapError((error) =>
+      PlanParseError.make({
+        message: `failed to encode vector ${vector.program}/${vector.id}: ${String(error)}`
+      })
+    )
+  )
+  const result = yield* guarded(
+    Capabilities.Exec(executable),
+    "equivalence replay",
+    events,
+    process.runWithStdin(command, root, {}, input).pipe(
+      Effect.mapError((error) =>
+        ProcessError.make({
+          message: "equivalence replay",
+          detail: error.message
+        })
+      )
+    )
+  )
+  if (result.exitCode !== 0) {
+    return ReplayedCrashed.make({
+      exitCode: result.exitCode,
+      problem: [...result.stderr, ...result.stdout].join("\n")
+    })
+  }
+  const output = result.stdout.join("\n")
+  const actual = yield* Schema.decodeUnknownEffect(observationsCodec)(output).pipe(
+    Effect.mapError((error) =>
+      PlanParseError.make({
+        message: `replay output for ${vector.program}/${vector.id} is not an observation array: ${String(error)}`
+      })
+    )
+  )
+  return ReplayedObserved.make({ actual })
+})

package/src/EquivReport.ts

@@ -0,0 +1,92 @@
+import * as Schema from "effect/Schema"
+import { EquivMismatch, type EquivObservation, EquivVector } from "./Equiv.ts"
+
+export class VectorVerdict extends Schema.Class<VectorVerdict>("VectorVerdict")({
+  vector: EquivVector,
+  mismatches: Schema.Array(EquivMismatch)
+}) {
+  get passed(): boolean {
+    return this.mismatches.length === 0
+  }
+}
+
+export interface EquivVerdict {
+  readonly vector: EquivVector
+  readonly mismatches: ReadonlyArray<EquivMismatch>
+}
+
+const observation = (value: EquivObservation): string => {
+  const pairs = (fields: Readonly<Record<string, string>>): string =>
+    Object.entries(fields)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, item]) => `${key}=${item}`)
+      .join(", ")
+  switch (value.type) {
+    case "record":
+      return `record ${value.kind} ${pairs(value.fields)}`
+    case "message":
+      return `message ${value.topic} ${value.key} ${pairs(value.fields)}`
+    case "db":
+      return `db ${value.table} ${value.op} ${pairs(value.key)} → ${pairs(value.set)}`
+  }
+}
+
+const describe = (mismatch: EquivMismatch): string => {
+  switch (mismatch._tag) {
+    case "FieldDiff":
+      return `- ${mismatch.at}: \`${mismatch.field}\` expected ${mismatch.expected}, actual ${mismatch.actual}`
+    case "Missing":
+      return `- missing: ${observation(mismatch.expected)}`
+    case "Unexpected":
+      return `- unexpected: ${observation(mismatch.actual)}`
+  }
+}
+
+export const renderEquivReport = (
+  verdicts: ReadonlyArray<EquivVerdict>,
+  allRules: ReadonlyArray<string>
+): string => {
+  const rows = allRules.map((rule) => {
+    const exercising = verdicts.filter(({ vector }) => vector.rules.includes(rule))
+    const generated = exercising.filter(({ vector }) => vector.tier === "generated")
+    const captured = exercising.filter(({ vector }) => vector.tier === "captured")
+    const cell = (values: ReadonlyArray<EquivVerdict>): string =>
+      values.length === 0
+        ? "—"
+        : `${values.filter(({ mismatches }) => mismatches.length === 0).length}/${values.length}`
+    const status =
+      exercising.length === 0
+        ? "UNEXERCISED"
+        : exercising.some(({ mismatches }) => mismatches.length > 0)
+          ? "FAILING"
+          : captured.length > 0
+            ? "proven (captured)"
+            : "proven (generated)"
+    return `| ${rule} | ${cell(generated)} | ${cell(captured)} | ${status} |`
+  })
+  const failing = verdicts.filter(({ mismatches }) => mismatches.length > 0)
+  const failures =
+    failing.length === 0
+      ? []
+      : [
+          "",
+          "## Failing vectors",
+          ...failing.flatMap(({ vector, mismatches }) => [
+            "",
+            `### ${vector.program} ${vector.id} (${vector.tier})`,
+            ...mismatches.map(describe)
+          ])
+        ]
+  return [
+    "# Equivalence report",
+    "",
+    "| Rule | Generated | Captured | Status |",
+    "| ---- | --------- | -------- | ------ |",
+    ...rows,
+    ...failures,
+    "",
+    "Generated vectors prove spec conformance; captured vectors prove behavioural equivalence.",
+    "The two tiers are reported separately and never summed.",
+    ""
+  ].join("\n")
+}

package/src/Flow.ts

@@ -0,0 +1,72 @@
+import * as Effect from "effect/Effect"
+import type { LlmServiceShape } from "@llm4ts/core/LlmService"
+import { collect } from "@llm4ts/core/Streaming"
+import { makeChat } from "./Chat.ts"
+import type { FlowContextShape } from "./FlowContext.ts"
+import { FlowLlmError, type FlowError } from "./FlowError.ts"
+import { AssistantMessage, type FlowEventsShape } from "./FlowEvents.ts"
+import type { Plan, Task } from "./Plan.ts"
+import type { PlanStoreShape } from "./Persistence.ts"
+import { implementTaskLoop, stage } from "./PlanExecution.ts"
+import { minimalReviewers, reviewAndFixLoop, type ReviewResult } from "./Review.ts"
+import type { Reviewer } from "./Reviewer.ts"
+
+export const flowReviewer = (context: FlowContextShape): LlmServiceShape =>
+  context.reviewers[0] ?? context.reasoning
+
+export const completeAndPublish = Effect.fn("@llm4ts/flow/Flow.completeAndPublish")(function* (
+  service: LlmServiceShape,
+  events: FlowEventsShape,
+  prompt: string
+): Effect.fn.Return<string, FlowLlmError> {
+  const response = yield* collect(service.executeStream(prompt)).pipe(
+    Effect.mapError(FlowLlmError.from)
+  )
+  yield* events.publish(AssistantMessage.make({ text: response.content }))
+  return response.content
+})
+
+export interface ImplementPlanOptions {
+  readonly store: PlanStoreShape
+  readonly planPath: string
+  readonly plan: Effect.Effect<Plan, FlowError>
+  readonly system?: string
+  readonly reviewers?: ReadonlyArray<Reviewer>
+  readonly commitMessage?: (plan: Plan, task: Task) => string
+  readonly checkoutBranch?: boolean
+  readonly maxRounds?: number
+  readonly lint?: Effect.Effect<ReviewResult, FlowError>
+  readonly format?: Effect.Effect<void, FlowError>
+}
+
+const defaultCommitMessage = (plan: Plan, task: Task): string => `${plan.epicId}: ${task.title}`
+
+export const implementPlanFlow = Effect.fn("@llm4ts/flow/Flow.implementPlan")(function* (
+  context: FlowContextShape,
+  options: ImplementPlanOptions
+): Effect.fn.Return<Plan, FlowError> {
+  const plan = yield* options.store.recoverOrCreate(options.planPath, options.plan)
+  if (options.checkoutBranch !== false) {
+    yield* stage(context.events, "branch", context.git.checkoutOrCreate(plan.epicId))
+  }
+  const coder = yield* makeChat(context.coder, {
+    ...(options.system === undefined ? {} : { system: options.system })
+  })
+  return yield* implementTaskLoop(options.store, context.events, options.planPath, plan, (task) =>
+    Effect.gen(function* () {
+      yield* coder.ask(plan.taskPrompt(task))
+      yield* reviewAndFixLoop({
+        reviewers: options.reviewers ?? minimalReviewers,
+        reviewerService: flowReviewer(context),
+        coder,
+        taskTitle: task.title,
+        currentDiff: context.git.diff,
+        events: context.events,
+        ...(options.maxRounds === undefined ? {} : { maxRounds: options.maxRounds }),
+        ...(options.lint === undefined ? {} : { lint: options.lint }),
+        ...(options.format === undefined ? {} : { format: options.format })
+      })
+      yield* context.git.commitAll((options.commitMessage ?? defaultCommitMessage)(plan, task))
+    })
+  )
+})

package/src/FlowContext.ts

@@ -0,0 +1,23 @@
+import * as Context from "effect/Context"
+import type { ConnectorCapabilities } from "@llm4ts/core/Models"
+import type { LlmServiceShape } from "@llm4ts/core/LlmService"
+import type { FlowEventsShape } from "./FlowEvents.ts"
+import type { GitToolShape } from "./GitTool.ts"
+import type { GitHubToolShape } from "./GitHubTool.ts"
+
+export interface FlowContextShape {
+  readonly reasoning: LlmServiceShape
+  readonly coder: LlmServiceShape
+  readonly git: GitToolShape
+  readonly hosting: GitHubToolShape
+  readonly events: FlowEventsShape
+  readonly reviewers: ReadonlyArray<LlmServiceShape>
+  readonly coderCapabilities: ConnectorCapabilities
+  readonly userPrompt: string
+  readonly workDir: string
+  readonly workspace: string
+}
+
+export class FlowContext extends Context.Service<FlowContext, FlowContextShape>()(
+  "@llm4ts/flow/FlowContext"
+) {}

package/src/FlowError.ts

@@ -0,0 +1,112 @@
+import * as Schema from "effect/Schema"
+import { Capability } from "@llm4ts/core/Capability"
+import { LlmError } from "@llm4ts/core/Errors"
+
+export class PersistenceError extends Schema.TaggedErrorClass<PersistenceError>()("Persistence", {
+  message: Schema.String,
+  cause: Schema.optionalKey(Schema.Defect())
+}) {}
+
+export class PlanParseError extends Schema.TaggedErrorClass<PlanParseError>()("PlanParse", {
+  message: Schema.String
+}) {}
+
+export class UnsupportedSchemaVersion extends Schema.TaggedErrorClass<UnsupportedSchemaVersion>()(
+  "UnsupportedSchemaVersion",
+  {
+    path: Schema.String,
+    expected: Schema.Int,
+    actual: Schema.Int
+  }
+) {
+  get message(): string {
+    return `unsupported schema version in ${this.path}: expected ${this.expected}, received ${this.actual}`
+  }
+}
+
+export class WorkspacePathError extends Schema.TaggedErrorClass<WorkspacePathError>()(
+  "WorkspacePath",
+  {
+    path: Schema.String,
+    message: Schema.String
+  }
+) {}
+
+export class WorkspaceLimitError extends Schema.TaggedErrorClass<WorkspaceLimitError>()(
+  "WorkspaceLimit",
+  {
+    operation: Schema.String,
+    limit: Schema.Int,
+    actual: Schema.Int
+  }
+) {
+  get message(): string {
+    return `${this.operation} exceeded limit ${this.limit}; received ${this.actual}`
+  }
+}
+
+export class WorkspaceIoError extends Schema.TaggedErrorClass<WorkspaceIoError>()("WorkspaceIo", {
+  operation: Schema.String,
+  path: Schema.String,
+  message: Schema.String,
+  cause: Schema.optionalKey(Schema.Defect())
+}) {}
+
+export class FlowAborted extends Schema.TaggedErrorClass<FlowAborted>()("Aborted", {
+  message: Schema.String
+}) {}
+
+export class ProcessError extends Schema.TaggedErrorClass<ProcessError>()("Process", {
+  message: Schema.String,
+  detail: Schema.String
+}) {}
+
+export class FlowLlmError extends Schema.TaggedErrorClass<FlowLlmError>()("Llm", {
+  message: Schema.String,
+  cause: Schema.optionalKey(LlmError)
+}) {
+  static readonly from = (cause?: typeof LlmError.Type): FlowLlmError =>
+    FlowLlmError.make({
+      message: cause?.message ?? "LLM request failed",
+      ...(cause === undefined ? {} : { cause })
+    })
+}
+
+export class FlowCapabilityDenied extends Schema.TaggedErrorClass<FlowCapabilityDenied>()(
+  "CapabilityDenied",
+  {
+    capability: Capability,
+    operation: Schema.String
+  }
+) {
+  get message(): string {
+    const capability =
+      this.capability._tag === "Exec" ? `Exec(${this.capability.command})` : this.capability._tag
+    return `capability ${capability} denied for ${this.operation}`
+  }
+}
+
+export class BudgetExceeded extends Schema.TaggedErrorClass<BudgetExceeded>()("BudgetExceeded", {
+  metric: Schema.Literals(["tokens", "costUsd"]),
+  limit: Schema.Number,
+  actual: Schema.Number
+}) {
+  get message(): string {
+    return `${this.metric} budget exceeded: limit ${this.limit}, actual ${this.actual}`
+  }
+}
+
+export const FlowError = Schema.Union([
+  PersistenceError,
+  PlanParseError,
+  UnsupportedSchemaVersion,
+  WorkspacePathError,
+  WorkspaceLimitError,
+  WorkspaceIoError,
+  FlowAborted,
+  ProcessError,
+  FlowLlmError,
+  FlowCapabilityDenied,
+  BudgetExceeded
+])
+export type FlowError = typeof FlowError.Type