@llm4ts/flow 0.1.0

package/src/Review.ts

@@ -0,0 +1,337 @@
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import type { LlmServiceShape } from "@llm4ts/core/LlmService"
+import type { JsonSchema } from "@llm4ts/core/Models"
+import type { ProcessExecutorShape } from "@llm4ts/core/ProcessExecutor"
+import { Capabilities } from "@llm4ts/core/Capability"
+import { guarded } from "./CapabilityGuard.ts"
+import type { Chat } from "./Chat.ts"
+import { FlowLlmError, ProcessError, type FlowError } from "./FlowError.ts"
+import { Info, type FlowEventsShape } from "./FlowEvents.ts"
+import { Reviewer } from "./Reviewer.ts"
+
+export const Severity = Schema.Literals(["Critical", "Warning", "Info"])
+export type Severity = typeof Severity.Type
+
+export class ReviewIssue extends Schema.Class<ReviewIssue>("ReviewIssue")({
+  severity: Severity,
+  title: Schema.String,
+  description: Schema.String.pipe(Schema.withConstructorDefault(Effect.succeed(""))),
+  file: Schema.optionalKey(Schema.String),
+  line: Schema.optionalKey(Schema.Int),
+  suggestion: Schema.optionalKey(Schema.String),
+  confidence: Schema.Number.pipe(Schema.withConstructorDefault(Effect.succeed(1)))
+}) {}
+
+export class ReviewResult extends Schema.Class<ReviewResult>("ReviewResult")({
+  issues: Schema.Array(ReviewIssue),
+  summary: Schema.String.pipe(Schema.withConstructorDefault(Effect.succeed("")))
+}) {
+  get isClean(): boolean {
+    return this.issues.length === 0
+  }
+}
+
+export const reviewJsonSchema: JsonSchema = {
+  type: "object",
+  properties: {
+    issues: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          severity: { type: "string", enum: ["Critical", "Warning", "Info"] },
+          title: { type: "string" },
+          description: { type: "string" },
+          file: { type: "string" },
+          line: { type: "integer" },
+          suggestion: { type: "string" },
+          confidence: { type: "number" }
+        },
+        required: ["severity", "title", "description"]
+      }
+    },
+    summary: { type: "string" }
+  },
+  required: ["issues", "summary"]
+}
+
+const reviewer = (name: string, systemPrompt: string, files = ".*"): Reviewer =>
+  Reviewer.make({ name, systemPrompt, files })
+
+export const correctnessReviewer = reviewer(
+  "code-functionality",
+  [
+    "Review for functional correctness. Check that the change implements the task's intent,",
+    "handles obvious edge cases, and does not regress existing behavior. Report only concrete",
+    "logic errors, wrong conditions, mishandled error paths, and missing cases. Ignore style."
+  ].join("\n")
+)
+
+export const readabilityReviewer = reviewer(
+  "readability",
+  [
+    "Review for readability and clarity. Check names, focused functions, understandable control",
+    "flow, and useful comments. Report only concrete, actionable readability problems."
+  ].join("\n")
+)
+
+export const testReviewer = reviewer(
+  "test",
+  [
+    "Review test coverage and quality. Check that new behavior and important error paths are",
+    "covered by tests that assert real outcomes and would fail on regression. Report concrete gaps."
+  ].join("\n")
+)
+
+export const structureReviewer = reviewer(
+  "code-structure",
+  "Review module boundaries, dependency direction, cohesion, and unnecessary coupling. Report concrete structural problems."
+)
+
+export const performanceReviewer = reviewer(
+  "performance",
+  "Review for material performance regressions, unbounded work, avoidable repeated I/O, and resource leaks."
+)
+
+export const securityReviewer = reviewer(
+  "security",
+  "Review trust boundaries, input handling, secrets, authorization, injection risks, and unsafe defaults."
+)
+
+export const effectReviewer = reviewer(
+  "effect-ts",
+  "Review Effect usage: typed errors, scoped resources, service boundaries, interruption, concurrency, and runtime ownership.",
+  ".*\\.(ts|tsx|mts|cts)$"
+)
+
+export const minimalReviewers: ReadonlyArray<Reviewer> = Object.freeze([
+  correctnessReviewer,
+  readabilityReviewer,
+  testReviewer
+])
+
+export const allReviewers: ReadonlyArray<Reviewer> = Object.freeze([
+  correctnessReviewer,
+  testReviewer,
+  readabilityReviewer,
+  structureReviewer,
+  performanceReviewer,
+  securityReviewer,
+  effectReviewer
+])
+
+export interface ReviewerSelector {
+  readonly select: (
+    reviewers: ReadonlyArray<Reviewer>,
+    changedFiles: ReadonlyArray<string>,
+    round: number,
+    previous: ReviewResult | undefined
+  ) => Effect.Effect<ReadonlyArray<Reviewer>, FlowError>
+}
+
+export const allEveryRound: ReviewerSelector = {
+  select: (reviewers, changedFiles, _round, _previous) =>
+    Effect.succeed(reviewers.filter((candidate) => candidate.matches(changedFiles)))
+}
+
+export const whileDirty: ReviewerSelector = {
+  select: (reviewers, changedFiles, round, previous) =>
+    Effect.succeed(
+      round === 1 || previous === undefined || !previous.isClean
+        ? reviewers.filter((candidate) => candidate.matches(changedFiles))
+        : []
+    )
+}
+
+export class ReviewerPick extends Schema.Class<ReviewerPick>("ReviewerPick")({
+  reviewers: Schema.Array(Schema.String)
+}) {}
+
+const reviewerPickJsonSchema: JsonSchema = {
+  type: "object",
+  properties: {
+    reviewers: {
+      type: "array",
+      items: { type: "string" }
+    }
+  },
+  required: ["reviewers"]
+}
+
+export const llmDriven = (picker: LlmServiceShape): ReviewerSelector => ({
+  select: (reviewers, changedFiles, _round, _previous) => {
+    const scoped = reviewers.filter((candidate) => candidate.matches(changedFiles))
+    if (scoped.length <= 1 || changedFiles.length === 0) {
+      return Effect.succeed(scoped)
+    }
+    const names = scoped.map((candidate) => candidate.name)
+    const prompt = [
+      `Pick the reviewers relevant to these files. Available reviewers: ${names.join(", ")}.`,
+      "Changed files:",
+      ...changedFiles,
+      'Respond only with JSON: {"reviewers":["name", ...]}.'
+    ].join("\n")
+    return picker.executeStructured(prompt, ReviewerPick, reviewerPickJsonSchema).pipe(
+      Effect.map((pick) => scoped.filter((candidate) => pick.reviewers.includes(candidate.name))),
+      Effect.catch(() => Effect.succeed(scoped)),
+      Effect.map((chosen) => (chosen.length === 0 ? scoped : chosen))
+    )
+  }
+})
+
+export const reviewPrompt = (task: string, diff: string): string =>
+  [
+    `Review the change below for task "${task}". Report problems as JSON:`,
+    '{"issues":[{"severity":"Critical|Warning|Info","title":"...",',
+    '"description":"..."}],"summary":"..."}.',
+    'An empty "issues" array means the change is acceptable. Respond with JSON only.',
+    "",
+    "Diff:",
+    diff
+  ].join("\n")
+
+export const fixPrompt = (result: ReviewResult): string =>
+  [
+    "Address these review findings, then stop:",
+    ...result.issues.map((issue) => `- [${issue.severity}] ${issue.title}: ${issue.description}`)
+  ].join("\n")
+
+export const mergeReviewResults = (results: ReadonlyArray<ReviewResult>): ReviewResult =>
+  ReviewResult.make({
+    issues: results.flatMap((result) => result.issues),
+    summary: results
+      .map((result) => result.summary)
+      .filter((summary) => summary.length > 0)
+      .join("; ")
+  })
+
+const processProblem = (
+  stdout: ReadonlyArray<string>,
+  stderr: ReadonlyArray<string>,
+  exitCode: number
+): string => {
+  const detail = [...stdout, ...stderr].join("\n").trim()
+  return detail.length === 0 ? `process exited with code ${exitCode}` : detail
+}
+
+export const lintCommand = Effect.fn("@llm4ts/flow/Review.lintCommand")(function* (
+  process: ProcessExecutorShape,
+  events: FlowEventsShape,
+  command: ReadonlyArray<string>,
+  workDir: string
+): Effect.fn.Return<ReviewResult, FlowError> {
+  const executable = command[0]
+  if (executable === undefined) {
+    return ReviewResult.make({ issues: [], summary: "" })
+  }
+  const result = yield* guarded(
+    Capabilities.Exec(executable),
+    `lint: ${command.join(" ")}`,
+    events,
+    process.run(command, workDir, {}).pipe(
+      Effect.mapError((cause) =>
+        ProcessError.make({
+          message: command.join(" "),
+          detail: cause.message
+        })
+      )
+    )
+  )
+  if (result.exitCode === 0) {
+    return ReviewResult.make({ issues: [], summary: "lint passed" })
+  }
+  return ReviewResult.make({
+    issues: [
+      ReviewIssue.make({
+        severity: "Critical",
+        title: `lint failed: ${command.join(" ")}`,
+        description: processProblem(result.stdout, result.stderr, result.exitCode)
+      })
+    ],
+    summary: "lint failed"
+  })
+})
+
+export interface ReviewAndFixOptions {
+  readonly reviewers: ReadonlyArray<Reviewer>
+  readonly reviewerService: LlmServiceShape
+  readonly coder: Chat
+  readonly taskTitle: string
+  readonly currentDiff: Effect.Effect<string, FlowError>
+  readonly events: FlowEventsShape
+  readonly changedFiles?: Effect.Effect<ReadonlyArray<string>, FlowError>
+  readonly maxRounds?: number
+  readonly selector?: ReviewerSelector
+  readonly lint?: Effect.Effect<ReviewResult, FlowError>
+  readonly parallelism?: number
+  readonly format?: Effect.Effect<void, FlowError>
+}
+
+const reviewWith = (
+  service: LlmServiceShape,
+  lens: Reviewer,
+  taskTitle: string,
+  diff: string
+): Effect.Effect<ReviewResult, FlowLlmError> =>
+  service
+    .executeStructured(
+      `${lens.systemPrompt}\n\n${reviewPrompt(taskTitle, diff)}`,
+      ReviewResult,
+      reviewJsonSchema
+    )
+    .pipe(Effect.mapError(FlowLlmError.from))
+
+export const reviewAndFixLoop = Effect.fn("@llm4ts/flow/Review.reviewAndFixLoop")(function* (
+  options: ReviewAndFixOptions
+): Effect.fn.Return<ReviewResult, FlowError> {
+  const maxRounds = Math.max(1, options.maxRounds ?? 3)
+  const selector = options.selector ?? allEveryRound
+  const changedFiles = options.changedFiles ?? Effect.succeed([])
+  const format = options.format ?? Effect.void
+
+  const reviewOnce = (
+    round: number,
+    previous: ReviewResult | undefined
+  ): Effect.Effect<ReviewResult, FlowError> =>
+    Effect.gen(function* () {
+      const lint = yield* options.lint ?? Effect.succeed(ReviewResult.make({ issues: [] }))
+      if (!lint.isClean) {
+        return lint
+      }
+      const diff = yield* options.currentDiff
+      const files = yield* changedFiles
+      const chosen = yield* selector.select(options.reviewers, files, round, previous)
+      const run = (lens: Reviewer) =>
+        reviewWith(options.reviewerService, lens, options.taskTitle, diff)
+      const parallelism = options.parallelism ?? 0
+      const results =
+        parallelism > 0
+          ? yield* Effect.forEach(chosen, run, { concurrency: parallelism })
+          : yield* Effect.forEach(chosen, run, { concurrency: "unbounded" })
+      return mergeReviewResults(results)
+    })
+
+  const loop = (
+    round: number,
+    previous: ReviewResult | undefined
+  ): Effect.Effect<ReviewResult, FlowError> =>
+    Effect.gen(function* () {
+      yield* format
+      const result = yield* reviewOnce(round, previous)
+      const verdict = result.isClean ? "clean" : `${result.issues.length} issue(s)`
+      if (result.isClean || round >= maxRounds) {
+        yield* options.events.publish(
+          Info.make({ message: `review settled after round ${round}: ${verdict}` })
+        )
+        return result
+      }
+      yield* options.events.publish(
+        Info.make({ message: `review round ${round}: ${verdict}, fixing` })
+      )
+      yield* options.coder.ask(fixPrompt(result))
+      return yield* loop(round + 1, result)
+    })
+
+  return yield* loop(1, undefined)
+})

package/src/ReviewCache.ts

@@ -0,0 +1,45 @@
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { PersistenceError, type FlowError } from "./FlowError.ts"
+import type { PlainFileStoreShape } from "./Persistence.ts"
+import { ReviewResult } from "./Review.ts"
+
+class ReviewCacheEntry extends Schema.Class<ReviewCacheEntry>("ReviewCacheEntry")({
+  fingerprint: Schema.String,
+  result: ReviewResult
+}) {}
+
+const decodeEntry = (contents: string): Effect.Effect<ReviewCacheEntry | undefined> =>
+  Schema.decodeUnknownEffect(Schema.fromJsonString(ReviewCacheEntry))(contents).pipe(
+    Effect.option,
+    Effect.map((option) => (option._tag === "Some" ? option.value : undefined))
+  )
+
+export const cachedReview = Effect.fn("@llm4ts/flow/ReviewCache.cached")(function* <R>(
+  files: PlainFileStoreShape,
+  path: string,
+  fingerprint: string,
+  evaluate: Effect.Effect<ReviewResult, FlowError, R>
+): Effect.fn.Return<ReviewResult, FlowError, R> {
+  const contents = yield* files.read(path).pipe(Effect.catch(() => Effect.succeed(undefined)))
+  const entry = contents === undefined ? undefined : yield* decodeEntry(contents)
+  if (entry?.fingerprint === fingerprint) {
+    return entry.result
+  }
+  const result = yield* evaluate
+  const encoded = yield* Schema.encodeEffect(Schema.fromJsonString(ReviewCacheEntry))(
+    ReviewCacheEntry.make({
+      fingerprint,
+      result
+    })
+  ).pipe(
+    Effect.mapError((error) =>
+      PersistenceError.make({
+        message: `failed to encode review cache: ${String(error)}`,
+        cause: error
+      })
+    )
+  )
+  yield* files.writeAtomic(path, encoded)
+  return result
+})

package/src/Reviewer.ts

@@ -0,0 +1,31 @@
+import * as Schema from "effect/Schema"
+
+export class Reviewer extends Schema.Class<Reviewer>("Reviewer")({
+  name: Schema.String,
+  systemPrompt: Schema.String,
+  files: Schema.optionalKey(Schema.String)
+}) {
+  matches(changedFiles: ReadonlyArray<string>): boolean {
+    if (this.files === undefined || changedFiles.length === 0) {
+      return true
+    }
+    const pattern = new RegExp(this.files)
+    return changedFiles.some((path) => pattern.test(path))
+  }
+}
+
+export const parseReviewer = (name: string, text: string): Reviewer => {
+  const parts = text.split("---\n", 3)
+  const frontmatter = parts.length === 3 ? (parts[1] ?? "") : ""
+  const body = parts.length === 3 ? (parts[2] ?? "").trim() : text.trim()
+  const files = frontmatter
+    .split(/\r?\n/)
+    .find((line) => line.trim().startsWith("files:"))
+    ?.split("files:", 2)[1]
+    ?.trim()
+  return Reviewer.make({
+    name,
+    systemPrompt: body,
+    ...(files === undefined || files.length === 0 ? {} : { files })
+  })
+}

package/src/SpecChecks.ts

@@ -0,0 +1,143 @@
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { ReviewIssue, ReviewResult } from "./Review.ts"
+import type { WorkspaceError, WorkspaceShape } from "./Workspace.ts"
+
+export class CoverageRule extends Schema.Class<CoverageRule>("CoverageRule")({
+  name: Schema.String,
+  files: Schema.String,
+  unit: Schema.String
+}) {}
+
+const capture = (regex: RegExp, text: string): ReadonlyArray<string> => {
+  const expression = new RegExp(
+    regex.source,
+    regex.flags.includes("g") ? regex.flags : `${regex.flags}g`
+  )
+  const values: Array<string> = []
+  for (const match of text.matchAll(expression)) {
+    values.push(match[1] ?? match[0])
+  }
+  return values
+}
+
+export const matchingFiles = (
+  workspace: WorkspaceShape,
+  regex: string
+): Effect.Effect<ReadonlyArray<string>, WorkspaceError> =>
+  workspace.discover().pipe(
+    Effect.map((paths) => {
+      const expression = new RegExp(regex)
+      return paths.filter((path) => expression.test(path)).sort()
+    })
+  )
+
+export const coverageUnits = Effect.fn("@llm4ts/flow/SpecChecks.coverageUnits")(function* (
+  workspace: WorkspaceShape,
+  rules: ReadonlyArray<CoverageRule>
+): Effect.fn.Return<Readonly<Record<string, ReadonlyArray<string>>>, WorkspaceError> {
+  const paths = yield* workspace.discover()
+  const result: Record<string, ReadonlyArray<string>> = {}
+  for (const rule of rules) {
+    const filePattern = new RegExp(rule.files)
+    const unitPattern = new RegExp(rule.unit)
+    const units: Array<string> = []
+    for (const path of paths.filter((path) => filePattern.test(path))) {
+      const contents = yield* workspace.read(path)
+      for (const line of contents.split(/\r?\n/)) {
+        for (const unit of capture(unitPattern, line)) {
+          if (!units.includes(unit)) {
+            units.push(unit)
+          }
+        }
+      }
+    }
+    result[rule.name] = units
+  }
+  return result
+})
+
+export const coverage = Effect.fn("@llm4ts/flow/SpecChecks.coverage")(function* (
+  workspace: WorkspaceShape,
+  rules: ReadonlyArray<CoverageRule>,
+  traceability: string
+): Effect.fn.Return<ReviewResult, WorkspaceError> {
+  const units = yield* coverageUnits(workspace, rules)
+  const issues = rules.flatMap((rule) =>
+    (units[rule.name] ?? []).flatMap((unit) =>
+      traceability.includes(unit)
+        ? []
+        : [
+            ReviewIssue.make({
+              severity: "Critical",
+              title: `uncovered ${rule.name}: ${unit}`,
+              description:
+                `'${unit}' exists in the legacy source but does not ` +
+                "appear in the traceability matrix."
+            })
+          ]
+    )
+  )
+  return ReviewResult.make({
+    issues,
+    summary: issues.length === 0 ? "coverage complete" : `${issues.length} unit(s) uncovered`
+  })
+})
+
+const featureIssue = (path: string, contents: string): ReviewIssue | undefined => {
+  const lines = contents.split(/\r?\n/).map((line) => line.trim())
+  const scenarios = lines.filter(
+    (line) => line.startsWith("Scenario:") || line.startsWith("Scenario Outline:")
+  ).length
+  const steps = lines.filter((line) =>
+    ["Given ", "When ", "Then ", "And ", "But "].some((prefix) => line.startsWith(prefix))
+  ).length
+  const problem = !lines.some((line) => line.startsWith("Feature:"))
+    ? "missing a 'Feature:' header"
+    : scenarios === 0
+      ? "contains no scenarios"
+      : steps === 0
+        ? "has scenarios but no Given/When/Then steps"
+        : undefined
+  return problem === undefined
+    ? undefined
+    : ReviewIssue.make({
+        severity: "Critical",
+        title: `malformed feature: ${path}`,
+        description: problem,
+        file: path
+      })
+}
+
+export const features = Effect.fn("@llm4ts/flow/SpecChecks.features")(function* (
+  workspace: WorkspaceShape,
+  directory: string
+): Effect.fn.Return<ReviewResult, WorkspaceError> {
+  const prefix = directory.replace(/[\\/]+$/, "")
+  const paths = (yield* workspace.discover("**/*.feature")).filter(
+    (path) => path === prefix || path.startsWith(`${prefix}/`)
+  )
+  if (paths.length === 0) {
+    return ReviewResult.make({
+      issues: [
+        ReviewIssue.make({
+          severity: "Critical",
+          title: "no feature files",
+          description: `no .feature files found under ${directory}`
+        })
+      ],
+      summary: "no features"
+    })
+  }
+  const issues: Array<ReviewIssue> = []
+  for (const path of paths) {
+    const issue = featureIssue(path, yield* workspace.read(path))
+    if (issue !== undefined) {
+      issues.push(issue)
+    }
+  }
+  return ReviewResult.make({
+    issues,
+    summary: issues.length === 0 ? "features well-formed" : `${issues.length} malformed`
+  })
+})

package/src/Survey.ts

@@ -0,0 +1,144 @@
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import type { CoverageRule } from "./SpecChecks.ts"
+import type { WorkspaceError, WorkspaceShape } from "./Workspace.ts"
+
+export class SurveyNode extends Schema.Class<SurveyNode>("SurveyNode")({
+  path: Schema.String,
+  name: Schema.String,
+  lines: Schema.Int,
+  units: Schema.Int
+}) {}
+
+export class SurveyEdge extends Schema.Class<SurveyEdge>("SurveyEdge")({
+  from: Schema.String,
+  to: Schema.String,
+  kind: Schema.String
+}) {}
+
+export class SurveyGraph extends Schema.Class<SurveyGraph>("SurveyGraph")({
+  nodes: Schema.Array(SurveyNode),
+  edges: Schema.Array(SurveyEdge)
+}) {
+  incoming(name: string): ReadonlyArray<SurveyEdge> {
+    return this.edges.filter((edge) => edge.to === name)
+  }
+
+  outgoing(name: string): ReadonlyArray<SurveyEdge> {
+    return this.edges.filter((edge) => edge.from === name)
+  }
+}
+
+const unitName = (path: string): string => {
+  const base = path.split("/").at(-1) ?? path
+  const dot = base.lastIndexOf(".")
+  return dot < 0 ? base : base.slice(0, dot)
+}
+
+const matches = (regex: string, contents: string): ReadonlyArray<string> => {
+  const expression = new RegExp(regex, "g")
+  return [...contents.matchAll(expression)].map((match) => match[1] ?? match[0])
+}
+
+export const surveyGraph = Effect.fn("@llm4ts/flow/Survey.graph")(function* (
+  workspace: WorkspaceShape,
+  sources: string,
+  units: ReadonlyArray<CoverageRule>,
+  edgeRules: ReadonlyArray<CoverageRule>
+): Effect.fn.Return<SurveyGraph, WorkspaceError> {
+  const sourcePattern = new RegExp(sources)
+  const paths = (yield* workspace.discover()).filter((path) => sourcePattern.test(path)).sort()
+  const nodes: Array<SurveyNode> = []
+  const contents = new Map<string, string>()
+  for (const path of paths) {
+    const text = yield* workspace.read(path)
+    contents.set(path, text)
+    nodes.push(
+      SurveyNode.make({
+        path,
+        name: unitName(path),
+        lines: text.split(/\r?\n/).length,
+        units: units
+          .filter((rule) => new RegExp(rule.files).test(path))
+          .reduce((count, rule) => count + matches(rule.unit, text).length, 0)
+      })
+    )
+  }
+  const edges: Array<SurveyEdge> = []
+  for (const rule of edgeRules) {
+    const filePattern = new RegExp(rule.files)
+    for (const path of paths.filter((path) => filePattern.test(path))) {
+      for (const target of new Set(matches(rule.unit, contents.get(path) ?? ""))) {
+        const edge = SurveyEdge.make({
+          from: unitName(path),
+          to: target,
+          kind: rule.name
+        })
+        if (
+          !edges.some(
+            (current) =>
+              current.from === edge.from && current.to === edge.to && current.kind === edge.kind
+          )
+        ) {
+          edges.push(edge)
+        }
+      }
+    }
+  }
+  return SurveyGraph.make({ nodes, edges })
+})
+
+export const mergeSurveyEdges = (
+  graph: SurveyGraph,
+  refined: ReadonlyArray<SurveyEdge>
+): SurveyGraph => {
+  const known = new Set(graph.nodes.map((node) => node.name))
+  const existing = new Set(graph.edges.map((edge) => `${edge.from}\u0000${edge.to}`))
+  const seen = new Set<string>()
+  const kept = refined.flatMap((edge) => {
+    const key = `${edge.from}\u0000${edge.to}`
+    if (
+      edge.from === edge.to ||
+      !known.has(edge.from) ||
+      !known.has(edge.to) ||
+      existing.has(key) ||
+      seen.has(key)
+    ) {
+      return []
+    }
+    seen.add(key)
+    return [
+      new SurveyEdge({
+        ...edge,
+        kind: edge.kind.startsWith("llm-") ? edge.kind : `llm-${edge.kind}`
+      })
+    ]
+  })
+  return new SurveyGraph({
+    nodes: graph.nodes,
+    edges: [...graph.edges, ...kept]
+  })
+}
+
+export const renderSurveyInventory = (graph: SurveyGraph): string => {
+  const rows = [...graph.nodes]
+    .sort((left, right) => left.name.localeCompare(right.name))
+    .map((node) => {
+      const incoming = graph.incoming(node.name).length
+      const outgoing = graph.outgoing(node.name).length
+      const flags = incoming === 0 && outgoing === 0 ? "unreferenced — retire candidate?" : ""
+      return `| ${node.name} | ${node.path} | ${node.lines} | ${node.units} | ${incoming} | ${outgoing} | ${flags} |`
+    })
+  const refined = graph.edges.filter((edge) => edge.kind.startsWith("llm-")).length
+  return [
+    "# Estate inventory",
+    "",
+    "| Unit | Path | Lines | Units | In | Out | Flags |",
+    "| ---- | ---- | ----- | ----- | -- | --- | ----- |",
+    ...rows,
+    "",
+    `${graph.nodes.length} unit(s), ${graph.edges.length} edge(s).`,
+    ...(refined === 0 ? [] : [`${refined} edge(s) came from the LLM graph-refine step.`]),
+    ""
+  ].join("\n")
+}