@llm4ts/flow 2.37.0 → 2.39.0

package/src/GraphRules.ts

@@ -0,0 +1,293 @@
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { PlanParseError } from "./FlowError.ts"
+import { fingerprintOf } from "./ReviewCache.ts"
+import type { CoverageRule } from "./SpecChecks.ts"
+import type { JoinMatch } from "./Survey.ts"
+
+/**
+ * The pack's graph vocabulary (ADR 0030). A `## Node:` rule names a sub-file
+ * node kind, an `## Edge:` rule a captured link, a `## Join:` rule a link by
+ * attribute equality across files, a `## Probe:` a flow that must be
+ * connected end to end. `## Survey:` rules are folded in as file-to-file
+ * Edge rules so a pre-0030 pack produces the same graph.
+ */
+export class NodeRule extends Schema.Class<NodeRule>("NodeRule")({
+  kind: Schema.String,
+  files: Schema.String,
+  pattern: Schema.String,
+  descriptor: Schema.Boolean,
+  anchor: Schema.optionalKey(Schema.String),
+  /** `attr → named group` copies beyond the default "every group but name". */
+  attrs: Schema.Record(Schema.String, Schema.String)
+}) {}
+
+export class EdgeRule extends Schema.Class<EdgeRule>("EdgeRule")({
+  kind: Schema.String,
+  files: Schema.String,
+  pattern: Schema.String,
+  fromKind: Schema.String,
+  toKind: Schema.String,
+  /** A folded `## Survey:` rule: the target is the first positional group (or the whole match), as before ADR 0030. */
+  positional: Schema.optionalKey(Schema.Boolean)
+}) {}
+
+export const JoinMatchMode = Schema.Literals(["exact", "url"])
+export type JoinMatchMode = typeof JoinMatchMode.Type
+export const JoinScope = Schema.Literals(["estate", "app", "file"])
+export type JoinScope = typeof JoinScope.Type
+
+export class JoinRule extends Schema.Class<JoinRule>("JoinRule")({
+  kind: Schema.String,
+  fromKind: Schema.String,
+  fromAttr: Schema.String,
+  toKind: Schema.String,
+  toAttr: Schema.String,
+  match: JoinMatchMode,
+  scope: JoinScope
+}) {}
+
+export class ProbeRule extends Schema.Class<ProbeRule>("ProbeRule")({
+  name: Schema.String,
+  from: Schema.String,
+  to: Schema.String
+}) {}
+
+export interface GraphRules {
+  readonly nodes: ReadonlyArray<NodeRule>
+  readonly edges: ReadonlyArray<EdgeRule>
+  readonly joins: ReadonlyArray<JoinRule>
+  readonly probes: ReadonlyArray<ProbeRule>
+  readonly worklistMax: number
+  readonly batchSize: number
+}
+
+export const emptyGraphRules: GraphRules = {
+  nodes: [],
+  edges: [],
+  joins: [],
+  probes: [],
+  worklistMax: 200,
+  batchSize: 20
+}
+
+/**
+ * `## Survey:` is an Edge rule between files whose first positional capture
+ * (or the whole match) is the target. The pattern is kept verbatim: rewriting
+ * its first `(` would break `(?:…)`, lookbehinds and escaped parens.
+ */
+export const edgeRuleOfSurvey = (rule: CoverageRule): EdgeRule =>
+  EdgeRule.make({
+    kind: rule.name,
+    files: rule.files,
+    pattern: rule.unit,
+    fromKind: "file",
+    toKind: "file",
+    positional: true
+  })
+
+const fail = (message: string): Effect.Effect<never, PlanParseError> =>
+  Effect.fail(PlanParseError.make({ message }))
+
+const isValidRegExp = (source: string): boolean => {
+  try {
+    new RegExp(source, "gm")
+    return true
+  } catch {
+    return false
+  }
+}
+
+const fieldsOf = (lines: ReadonlyArray<string>): Readonly<Record<string, string>> =>
+  Object.fromEntries(
+    lines.flatMap((line) => {
+      const trimmed = line.replace(/^- /, "")
+      const index = trimmed.indexOf(":")
+      return index < 0 ? [] : [[trimmed.slice(0, index).trim(), trimmed.slice(index + 1).trim()]]
+    })
+  )
+
+const yes = (value: string | undefined): boolean =>
+  value !== undefined && ["yes", "true", "on"].includes(value.trim().toLowerCase())
+
+const attrCopies = (value: string | undefined): Readonly<Record<string, string>> =>
+  Object.fromEntries(
+    (value ?? "")
+      .split(",")
+      .map((item) => item.trim())
+      .filter((item) => item.length > 0)
+      .flatMap((item) => {
+        const [attr, group] = item.split("=").map((part) => part.trim())
+        return attr !== undefined && group !== undefined && attr.length > 0 && group.length > 0
+          ? [[attr, group]]
+          : []
+      })
+  )
+
+const kindAndAttr = (value: string | undefined): readonly [string, string] | undefined => {
+  const dot = (value ?? "").indexOf(".")
+  if (value === undefined || dot <= 0 || dot === value.length - 1) {
+    return undefined
+  }
+  return [value.slice(0, dot).trim(), value.slice(dot + 1).trim()]
+}
+
+export const parseGraphRules = (
+  sections: ReadonlyArray<string>,
+  survey: ReadonlyArray<CoverageRule>
+): Effect.Effect<GraphRules, PlanParseError> =>
+  Effect.gen(function* () {
+    const nodes: Array<NodeRule> = []
+    const edges: Array<EdgeRule> = survey.map(edgeRuleOfSurvey)
+    const joins: Array<JoinRule> = []
+    const probes: Array<ProbeRule> = []
+    let worklistMax = emptyGraphRules.worklistMax
+    let batchSize = emptyGraphRules.batchSize
+    for (const section of sections) {
+      const lines = section.split(/\r?\n/)
+      const heading = lines[0]?.trim() ?? ""
+      const fields = fieldsOf(lines.slice(1))
+      if (heading.startsWith("## Node: ")) {
+        const kind = heading.slice("## Node: ".length).trim()
+        if (fields.files === undefined || fields.pattern === undefined) {
+          return yield* fail(`'${heading}' needs 'files:' and 'pattern:'`)
+        }
+        if (!isValidRegExp(fields.pattern)) {
+          return yield* fail(`'${heading}' pattern is not a valid regex: ${fields.pattern}`)
+        }
+        if (!fields.pattern.includes("(?<name>")) {
+          return yield* fail(`'${heading}' pattern needs a (?<name>…) group`)
+        }
+        nodes.push(
+          NodeRule.make({
+            kind,
+            files: fields.files,
+            pattern: fields.pattern,
+            descriptor: yes(fields.descriptor),
+            ...(fields.anchor === undefined ? {} : { anchor: fields.anchor }),
+            attrs: attrCopies(fields.attrs)
+          })
+        )
+      } else if (heading.startsWith("## Edge: ")) {
+        const kind = heading.slice("## Edge: ".length).trim()
+        if (fields.files === undefined || fields.pattern === undefined) {
+          return yield* fail(`'${heading}' needs 'files:' and 'pattern:'`)
+        }
+        if (!isValidRegExp(fields.pattern)) {
+          return yield* fail(`'${heading}' pattern is not a valid regex: ${fields.pattern}`)
+        }
+        if (!fields.pattern.includes("(?<to>")) {
+          return yield* fail(`'${heading}' pattern needs a (?<to>…) group`)
+        }
+        edges.push(
+          EdgeRule.make({
+            kind,
+            files: fields.files,
+            pattern: fields.pattern,
+            fromKind: fields.from ?? "file",
+            toKind: fields.to ?? "file"
+          })
+        )
+      } else if (heading.startsWith("## Join: ")) {
+        const kind = heading.slice("## Join: ".length).trim()
+        const from = kindAndAttr(fields.from)
+        const to = kindAndAttr(fields.to)
+        if (from === undefined || to === undefined) {
+          return yield* fail(`'${heading}' needs 'from: <kind>.<attr>' and 'to: <kind>.<attr>'`)
+        }
+        const match: JoinMatchMode = fields.match === "url" ? "url" : "exact"
+        const scope: JoinScope =
+          fields.scope === "file" || fields.scope === "app" || fields.scope === "estate"
+            ? fields.scope
+            : match === "url"
+              ? "app"
+              : "estate"
+        joins.push(
+          JoinRule.make({
+            kind,
+            fromKind: from[0],
+            fromAttr: from[1],
+            toKind: to[0],
+            toAttr: to[1],
+            match,
+            scope
+          })
+        )
+      } else if (heading.startsWith("## Probe: ")) {
+        const name = heading.slice("## Probe: ".length).trim()
+        if (fields.from === undefined || fields.to === undefined) {
+          return yield* fail(`'${heading}' needs 'from:' and 'to:'`)
+        }
+        probes.push(ProbeRule.make({ name, from: fields.from, to: fields.to }))
+      } else if (heading === "## Graph") {
+        const max = Number.parseInt(fields["worklist-max"] ?? "", 10)
+        const batch = Number.parseInt(fields["batch-size"] ?? "", 10)
+        worklistMax = Number.isInteger(max) && max > 0 ? max : worklistMax
+        batchSize = Number.isInteger(batch) && batch > 0 ? batch : batchSize
+      }
+    }
+    const nodeKinds = new Set(["file", ...nodes.map((rule) => rule.kind)])
+    for (const rule of edges) {
+      for (const kind of [rule.fromKind, rule.toKind]) {
+        if (!nodeKinds.has(kind)) {
+          return yield* fail(
+            `'## Edge: ${rule.kind}' names node kind '${kind}' no '## Node:' declares`
+          )
+        }
+      }
+    }
+    for (const rule of joins) {
+      for (const kind of [rule.fromKind, rule.toKind]) {
+        if (!nodeKinds.has(kind)) {
+          return yield* fail(
+            `'## Join: ${rule.kind}' names node kind '${kind}' no '## Node:' declares`
+          )
+        }
+      }
+    }
+    return { nodes, edges, joins, probes, worklistMax, batchSize }
+  })
+
+/** Every edge kind the rules can produce: captured kinds plus join kinds. */
+export const edgeKindsOf = (rules: GraphRules): ReadonlySet<string> =>
+  new Set([...rules.edges.map((rule) => rule.kind), ...rules.joins.map((rule) => rule.kind)])
+
+/** Changes when any rule that shapes the graph changes; probes and budgets do not. */
+export const graphRulesHash = (rules: GraphRules): string =>
+  fingerprintOf([JSON.stringify({ n: rules.nodes, e: rules.edges, j: rules.joins })])
+
+/** `${ctx}/a/b?x=1` → `/a/b`; `salva.do` → `/salva.do`; scheme, host and fragment dropped. */
+export const normalizeUrl = (raw: string): string => {
+  let url = raw.trim()
+  url = url.replace(/^(\$\{[^}]*\}|<%=[^%]*%>)/, "")
+  url = url.replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]+/i, "")
+  url = url.replace(/[?#].*$/, "")
+  if (!url.startsWith("/")) {
+    url = `/${url}`
+  }
+  if (url.length > 1 && url.endsWith("/")) {
+    url = url.slice(0, -1)
+  }
+  return url
+}
+
+/**
+ * Servlet-spec matching of a normalised request against a `url-pattern`:
+ * exact, then a `/*` prefix, then a `*.ext` extension. The extension case
+ * reads the raw pattern, since normalising `*.do` would prefix a slash.
+ */
+export const matchUrl = (request: string, pattern: string): JoinMatch | undefined => {
+  const trimmed = pattern.trim()
+  if (trimmed.startsWith("*.")) {
+    return request.endsWith(trimmed.slice(1)) ? "extension" : undefined
+  }
+  const target = normalizeUrl(trimmed)
+  if (request === target) {
+    return "exact"
+  }
+  if (target.endsWith("/*")) {
+    const prefix = target.slice(0, -2)
+    return request === prefix || request.startsWith(`${prefix}/`) ? "prefix" : undefined
+  }
+  return undefined
+}

package/src/GraphWorklist.ts

@@ -0,0 +1,405 @@
+import * as Schema from "effect/Schema"
+import type { JsonSchema } from "@llm4ts/core/Models"
+import type { GraphRules } from "./GraphRules.ts"
+import {
+  Fill,
+  GraphEvidence,
+  SurveyEdge,
+  SurveyGraph,
+  applyFillsAndJoins,
+  nodeAttrs,
+  nodeId,
+  nodeKind,
+  nodeLabel,
+  nodeLineStart,
+  type SurveyNode,
+  type Unresolved
+} from "./Survey.ts"
+
+/**
+ * The bounded LLM pass of the code graph (ADR 0030 decision 4). The scanner's
+ * `unresolved` list becomes a worklist; the seat may fill an attr of an
+ * existing node or add an edge between two existing nodes, each tied to a
+ * source line that is checked here before anything is merged. It may not
+ * create nodes.
+ */
+export interface WorklistCandidate {
+  readonly id: string
+  readonly label: string
+  readonly attrs: Readonly<Record<string, string>>
+}
+
+export interface WorklistItem {
+  readonly unresolved: Unresolved
+  readonly node: SurveyNode
+  /** Fifteen lines either side of the item's line, numbered. */
+  readonly context: string
+  readonly candidates: ReadonlyArray<WorklistCandidate>
+}
+
+const contextWindow = 15
+const candidateLimit = 8
+
+const tokens = (text: string): ReadonlyArray<string> => [
+  ...new Set(
+    text
+      .toLowerCase()
+      .split(/[^a-z0-9]+/)
+      .filter((token) => token.length >= 3)
+  )
+]
+
+const numbered = (text: string, line: number): string =>
+  text
+    .split(/\r?\n/)
+    .map((content, index) => ({ number: index + 1, content }))
+    .filter(({ number }) => Math.abs(number - line) <= contextWindow)
+    .map(({ number, content }) => `${String(number).padStart(4, " ")}  ${content}`)
+    .join("\n")
+
+/**
+ * Up to eight existing nodes worth naming to the seat: lexical matches on the
+ * item's reference, name and attrs, and for a join hole every node of the
+ * join's target kind (a dynamic URL matches no token of any mapping).
+ */
+const candidatesFor = (
+  graph: SurveyGraph,
+  item: Unresolved,
+  node: SurveyNode,
+  rules: GraphRules | undefined
+): ReadonlyArray<WorklistCandidate> => {
+  const needles = tokens(
+    `${item.reference ?? ""} ${node.name} ${Object.values(nodeAttrs(node)).join(" ")}`
+  )
+  const targetKinds = new Set(
+    item.reason === "missing-attr" || item.reason === "join-from"
+      ? (rules?.joins ?? []).filter((rule) => rule.kind === item.rule).map((rule) => rule.toKind)
+      : []
+  )
+  return graph.nodes
+    .filter((candidate) => nodeId(candidate) !== nodeId(node))
+    .map((candidate) => {
+      const hay =
+        `${nodeId(candidate)} ${nodeLabel(candidate)} ${Object.values(nodeAttrs(candidate)).join(" ")}`.toLowerCase()
+      const lexical = needles.filter((needle) => hay.includes(needle)).length
+      return { candidate, score: lexical + (targetKinds.has(nodeKind(candidate)) ? 1 : 0) }
+    })
+    .filter(({ score }) => score > 0)
+    .sort(
+      (left, right) =>
+        right.score - left.score || nodeId(left.candidate).localeCompare(nodeId(right.candidate))
+    )
+    .slice(0, candidateLimit)
+    .map(({ candidate }) => ({
+      id: nodeId(candidate),
+      label: nodeLabel(candidate),
+      attrs: nodeAttrs(candidate)
+    }))
+}
+
+/** Unresolved items, highest-degree node first (hubs resolve first), capped at `max`. */
+export const worklistOf = (
+  graph: SurveyGraph,
+  contents: (path: string) => string | undefined,
+  max: number,
+  rules?: GraphRules
+): ReadonlyArray<WorklistItem> => {
+  const degree = (id: string): number => graph.incoming(id).length + graph.outgoing(id).length
+  // Rank and cut first; reading context and scoring candidates is paid only
+  // for the items actually offered.
+  const ranked = graph.unresolved
+    .flatMap((item) => {
+      const node = graph.node(item.node)
+      return node === undefined ? [] : [{ item, node, degree: degree(item.node) }]
+    })
+    .sort(
+      (left, right) => right.degree - left.degree || left.item.node.localeCompare(right.item.node)
+    )
+    .slice(0, max)
+  return ranked.map(({ item, node }) => ({
+    unresolved: item,
+    node,
+    context: numbered(contents(item.file) ?? "", item.line),
+    candidates: candidatesFor(graph, item, node, rules)
+  }))
+}
+
+export const worklistBatches = <A>(
+  items: ReadonlyArray<A>,
+  size: number
+): ReadonlyArray<ReadonlyArray<A>> => {
+  const step = Math.max(1, Math.floor(size))
+  const batches: Array<ReadonlyArray<A>> = []
+  for (let index = 0; index < items.length; index += step) {
+    batches.push(items.slice(index, index + step))
+  }
+  return batches
+}
+
+const describeCandidate = (candidate: WorklistCandidate): string =>
+  Object.keys(candidate.attrs).length === 0
+    ? candidate.id
+    : `${candidate.id} ${JSON.stringify(candidate.attrs)}`
+
+const describeItem = (item: WorklistItem, index: number): string =>
+  [
+    `### Item ${index + 1}: ${item.unresolved.reason} — rule '${item.unresolved.rule}'`,
+    `Node: ${nodeId(item.node)} (line ${nodeLineStart(item.node)} of ${item.node.path})`,
+    ...(item.unresolved.reference === undefined
+      ? []
+      : [`Reference the scanner could not resolve: ${item.unresolved.reference}`]),
+    `Candidates (existing nodes with matching tokens): ${
+      item.candidates.length === 0 ? "none" : item.candidates.map(describeCandidate).join("; ")
+    }`,
+    "Source context:",
+    "```",
+    item.context,
+    "```"
+  ].join("\n")
+
+const defaultGuidance = [
+  "Regexes miss links the source establishes indirectly: a URL assembled from a variable or",
+  "configuration entry, a target held in a field, wiring declared in a descriptor, a fragment",
+  "pulled in by templating."
+].join("\n")
+
+export const worklistPrompt = (
+  batch: ReadonlyArray<WorklistItem>,
+  guidance: string | undefined
+): string =>
+  [
+    "You are resolving holes in the dependency graph of a legacy estate. The graph was built",
+    "deterministically from pack rules; each item below is something the scanner could not",
+    "resolve. You have read-only access to the estate.",
+    guidance ?? defaultGuidance,
+    "",
+    "For each item, either resolve it or leave it. You may:",
+    '- fill a missing attribute of an EXISTING node ("attrs": node id, key, value) — e.g. the URL an',
+    "  ajax call actually hits once its prefix variable is known;",
+    '- add an edge between two EXISTING nodes ("edges": from id, to id, a short kebab-case kind).',
+    "Every entry carries evidence: the file, the 1-based line, and the exact statement on that line.",
+    "No evidence, no entry. Use node ids exactly as given; never invent a node, a file or a line.",
+    'External systems, platform services and third-party libraries are not nodes; put them in "notes".',
+    "",
+    ...batch.map(describeItem),
+    "",
+    'Respond only with JSON: {"edges":[{"from","to","kind","evidence":{"file","line","snippet"}}],',
+    '"attrs":[{"node","key","value","evidence":{"file","line","snippet"}}],"notes":[…]}'
+  ].join("\n")
+
+export class WorklistEdge extends Schema.Class<WorklistEdge>("WorklistEdge")({
+  from: Schema.String,
+  to: Schema.String,
+  kind: Schema.String,
+  evidence: GraphEvidence
+}) {}
+
+export class WorklistAttr extends Schema.Class<WorklistAttr>("WorklistAttr")({
+  node: Schema.String,
+  key: Schema.String,
+  value: Schema.String,
+  evidence: GraphEvidence
+}) {}
+
+export class WorklistAnswer extends Schema.Class<WorklistAnswer>("WorklistAnswer")({
+  edges: Schema.Array(WorklistEdge),
+  attrs: Schema.Array(WorklistAttr),
+  notes: Schema.Array(Schema.String)
+}) {}
+
+const evidenceJsonSchema: JsonSchema = {
+  type: "object",
+  properties: {
+    file: { type: "string" },
+    line: { type: "integer" },
+    snippet: { type: "string" }
+  },
+  required: ["file", "line", "snippet"]
+}
+
+export const worklistAnswerJsonSchema: JsonSchema = {
+  type: "object",
+  properties: {
+    edges: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          from: { type: "string" },
+          to: { type: "string" },
+          kind: { type: "string" },
+          evidence: evidenceJsonSchema
+        },
+        required: ["from", "to", "kind", "evidence"]
+      }
+    },
+    attrs: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          node: { type: "string" },
+          key: { type: "string" },
+          value: { type: "string" },
+          evidence: evidenceJsonSchema
+        },
+        required: ["node", "key", "value", "evidence"]
+      }
+    },
+    notes: { type: "array", items: { type: "string" } }
+  },
+  required: ["edges", "attrs", "notes"]
+}
+
+export interface VerifiedWorklist {
+  readonly edges: ReadonlyArray<SurveyEdge>
+  readonly fills: ReadonlyArray<Fill>
+  readonly dropped: ReadonlyArray<{ readonly what: string; readonly reason: string }>
+}
+
+/** The 1-based line within ±2 of `line` whose text contains the trimmed snippet, or undefined. */
+const locateSnippet = (
+  text: string | undefined,
+  line: number,
+  snippet: string
+): number | undefined => {
+  if (text === undefined) {
+    return undefined
+  }
+  const needle = snippet.trim()
+  if (needle.length === 0) {
+    return undefined
+  }
+  const lines = text.split(/\r?\n/)
+  for (const delta of [0, -1, 1, -2, 2]) {
+    const candidate = line + delta
+    if (candidate >= 1 && (lines[candidate - 1] ?? "").includes(needle)) {
+      return candidate
+    }
+  }
+  return undefined
+}
+
+export const verifyWorklistAnswer = (
+  answer: WorklistAnswer,
+  graph: SurveyGraph,
+  contents: (path: string) => string | undefined
+): VerifiedWorklist => {
+  const ids = new Set(graph.nodes.map(nodeId))
+  const existing = new Set(graph.edges.map((edge) => `${edge.from}\u0000${edge.to}`))
+  const edges: Array<SurveyEdge> = []
+  const fills: Array<Fill> = []
+  const dropped: Array<{ what: string; reason: string }> = []
+  const verified = (evidence: GraphEvidence): GraphEvidence | string => {
+    const line = locateSnippet(contents(evidence.file), evidence.line, evidence.snippet)
+    return line === undefined
+      ? `snippet not found within two lines of line ${evidence.line}`
+      : GraphEvidence.make({ file: evidence.file, line, snippet: evidence.snippet.trim() })
+  }
+  for (const edge of answer.edges) {
+    const what = `${edge.from} -> ${edge.to} (${edge.kind})`
+    const unknown = [edge.from, edge.to].find((id) => !ids.has(id))
+    if (unknown !== undefined) {
+      dropped.push({ what, reason: `unknown endpoint: ${unknown}` })
+      continue
+    }
+    if (edge.from === edge.to) {
+      dropped.push({ what, reason: "self loop" })
+      continue
+    }
+    if (existing.has(`${edge.from}\u0000${edge.to}`)) {
+      dropped.push({ what, reason: "duplicate of an existing edge" })
+      continue
+    }
+    const evidence = verified(edge.evidence)
+    if (typeof evidence === "string") {
+      dropped.push({ what, reason: evidence })
+      continue
+    }
+    existing.add(`${edge.from}\u0000${edge.to}`)
+    edges.push(
+      SurveyEdge.make({
+        from: edge.from,
+        to: edge.to,
+        kind: edge.kind.replace(/^llm-/, ""),
+        origin: "llm",
+        confidence: "inferred",
+        rule: "llm",
+        mechanism: "llm",
+        evidence
+      })
+    )
+  }
+  const nodesById = new Map(graph.nodes.map((node) => [nodeId(node), node]))
+  for (const attr of answer.attrs) {
+    const what = `${attr.node}.${attr.key} = ${attr.value}`
+    const node = nodesById.get(attr.node)
+    if (node === undefined) {
+      dropped.push({ what, reason: `unknown node: ${attr.node}` })
+      continue
+    }
+    // The seat fills holes; it never overrides what the scanner read.
+    if (nodeAttrs(node)[attr.key] !== undefined) {
+      dropped.push({ what, reason: `attr '${attr.key}' already set by the scanner` })
+      continue
+    }
+    const evidence = verified(attr.evidence)
+    if (typeof evidence === "string") {
+      dropped.push({ what, reason: evidence })
+      continue
+    }
+    fills.push(Fill.make({ node: attr.node, key: attr.key, value: attr.value, evidence }))
+  }
+  return { edges, fills, dropped }
+}
+
+export const mergeWorklist = (
+  graph: SurveyGraph,
+  verified: VerifiedWorklist,
+  rules: GraphRules
+): SurveyGraph =>
+  applyFillsAndJoins(
+    SurveyGraph.make({
+      nodes: graph.nodes,
+      edges: [...graph.edges, ...verified.edges],
+      unresolved: graph.unresolved,
+      fills: []
+    }),
+    [...graph.fills, ...verified.fills],
+    rules
+  )
+
+const cell = (text: string): string => text.split(/\r?\n/).join(" ").replaceAll("|", "\\|")
+
+export const renderWorklistReport = (
+  items: ReadonlyArray<WorklistItem>,
+  verified: VerifiedWorklist,
+  notes: ReadonlyArray<string>
+): string =>
+  [
+    "# Graph refine (LLM worklist)",
+    "",
+    `${items.length} unresolved item(s) offered; ${verified.edges.length} edge(s) and ${verified.fills.length} attr fill(s) accepted; ${verified.dropped.length} dropped.`,
+    "Accepted entries carry the source line that establishes them and are re-verified on every rebuild.",
+    "",
+    "## Accepted",
+    "",
+    "| What | Evidence |",
+    "| ---- | -------- |",
+    ...verified.edges.map(
+      (edge) =>
+        `| ${cell(`${edge.from} → ${edge.to} (${edge.kind})`)} | ${cell(`${edge.evidence?.file}:${edge.evidence?.line} ${edge.evidence?.snippet ?? ""}`)} |`
+    ),
+    ...verified.fills.map(
+      (fill) =>
+        `| ${cell(`${fill.node}.${fill.key} = ${fill.value}`)} | ${cell(`${fill.evidence.file}:${fill.evidence.line} ${fill.evidence.snippet}`)} |`
+    ),
+    "",
+    "## Dropped",
+    "",
+    "| What | Reason |",
+    "| ---- | ------ |",
+    ...verified.dropped.map((drop) => `| ${cell(drop.what)} | ${cell(drop.reason)} |`),
+    "",
+    ...(notes.length === 0 ? [] : ["## Notes", "", ...notes.map((note) => `- ${cell(note)}`), ""])
+  ].join("\n")