agentic-mermaid 0.1.0 → 0.1.2

package/src/agent/journey-body.ts

@@ -1,414 +0,0 @@
-// ============================================================================
-// Journey structured body (BUILD-15 pilot for promoting source-level families).
-//
-// Modeled grammar (mirrors the legacy renderer parser, src/journey/parser.ts):
-//   title <text>
-//   accTitle: <text>
-//   accDescr: <text>
-//   accDescr { <multiline text> }
-//   section <label>
-//   <task text>: <score 1..5>[: <actor>[, <actor>…]]
-//
-// Structured-or-opaque: any other non-blank, non-comment line (unmodeled
-// syntax, out-of-range scores) returns null so the caller falls back to a
-// lossless opaque body. Render support stays unchanged — the legacy renderer
-// keeps parsing canonical source.
-// ============================================================================
-
-import { unknownOpMessage } from './mutation-ops.ts'
-import type {
-  JourneyBody, JourneySection, JourneyTask, JourneyMutationOp,
-  MutationError, Result, LayoutWarning, VerifyOptions,
-} from './types.ts'
-import { ok, err, DEFAULT_LABEL_CHAR_CAP } from './types.ts'
-import { labelOverflowWarning } from './label-metrics.ts'
-
-// ---- Parser -----------------------------------------------------------------
-
-const TITLE_RE = /^title\s+(.+)$/i
-const ACC_LINE_RE = (directive: 'accTitle' | 'accDescr') => new RegExp(`^${directive}\\s*:[ \\t]*(.+)$`, 'i')
-const SECTION_RE = /^section\s+(.+)$/i
-const TASK_RE = /^(.+?)\s*:\s*([0-9]+)\s*(?::\s*(.*))?$/
-
-function normalizeText(value: string): string {
-  return normalizeJourneyLabel(value).split(/\r?\n/).map(part => part.trim()).filter(Boolean).join('\n')
-}
-
-function normalizeActorText(value: string): string {
-  return normalizeText(value).split(/\r?\n/).map(part => part.trim()).filter(Boolean).join(' / ')
-}
-
-function normalizeJourneyLabel(label: string): string {
-  return label
-    .replace(/<br\s*\/?>/gi, '\n')
-    .replace(/\\n/g, '\n')
-    .replace(/<\/?(?:sub|sup|small|mark)\s*>/gi, '')
-    .replace(/\*\*(.+?)\*\*/g, '<b>$1</b>')
-    .replace(/(?<!\*)\*([^\s*](?:[^*]*[^\s*])?)\*(?!\*)/g, '<i>$1</i>')
-    .replace(/~~(.+?)~~/g, '<s>$1</s>')
-}
-
-function formatJourneyInline(value: string): string {
-  return value.split(/\r?\n/).map(part => part.trim()).join('<br>')
-}
-
-function isJourneyComment(line: string): boolean {
-  return line.startsWith('%%') || line.startsWith('#') || line.startsWith('%')
-}
-
-function validScore(score: number): boolean {
-  return Number.isInteger(score) && score >= 1 && score <= 5
-}
-
-/**
- * Parse journey body lines (header excluded). Returns a structured body only
- * if EVERY non-blank, non-comment line is a title, section, or task with a
- * valid 1..5 integer score. Otherwise returns null (opaque fallback).
- */
-export function parseJourneyBody(lines: string[]): JourneyBody | null {
-  const body: JourneyBody = { kind: 'journey', sections: [] }
-  let currentSection: JourneySection | undefined
-  let sIdx = 0, tIdx = 0
-
-  const implicitSection = (): JourneySection => {
-    if (!currentSection) {
-      currentSection = { id: `section-${sIdx++}`, tasks: [] }
-      body.sections.push(currentSection)
-    }
-    return currentSection
-  }
-
-  for (let i = 0; i < lines.length; i++) {
-    const raw = lines[i]!
-    const line = raw.trim()
-    if (!line) continue
-    if (isJourneyComment(line)) continue
-
-    const accTitle = parseAccessibilityLine(line, 'accTitle')
-    if (accTitle !== undefined) {
-      body.accessibilityTitle = accTitle
-      continue
-    }
-
-    const accDescrStart = line.match(/^accDescr\s*:?\s*\{\s*(.*)$/i)
-    if (accDescrStart) {
-      const initial = accDescrStart[1] ?? ''
-      const parsed = collectAccessibilityBlock(initial, lines, i)
-      if (!parsed) return null
-      body.accessibilityDescription = normalizeAccessibilityText(parsed.text)
-      i = parsed.nextIndex
-      continue
-    }
-
-    const accDescr = parseAccessibilityLine(line, 'accDescr')
-    if (accDescr !== undefined) {
-      body.accessibilityDescription = accDescr
-      continue
-    }
-
-    const tm = line.match(TITLE_RE)
-    if (tm) {
-      const title = normalizeText(tm[1]!)
-      if (!title) return null
-      body.title = title
-      continue
-    }
-
-    const sm = line.match(SECTION_RE)
-    if (sm) {
-      const label = normalizeText(sm[1]!)
-      if (!label || label.includes(':')) return null
-      currentSection = { id: `section-${sIdx++}`, label, tasks: [] }
-      body.sections.push(currentSection)
-      continue
-    }
-
-    const km = line.match(TASK_RE)
-    if (km) {
-      const text = normalizeText(km[1]!)
-      const score = Number.parseInt(km[2]!, 10)
-      if (!text || !validScore(score)) return null
-      const actors = (km[3] ?? '')
-        .split(',')
-        .map(normalizeActorText)
-        .filter(Boolean)
-      implicitSection().tasks.push({ id: `task-${tIdx++}`, text, score, actors })
-      continue
-    }
-
-    // Unmodeled line (anything else) → opaque fallback.
-    return null
-  }
-
-  // Upstream parity: title/acc metadata-only journeys are renderable header
-  // furniture. A truly empty journey still stays opaque for source fidelity.
-  if (body.sections.length === 0 && body.sections.every(s => s.tasks.length === 0) && !body.title && !body.accessibilityTitle && !body.accessibilityDescription) {
-    return null
-  }
-
-  return body
-}
-
-// ---- Serializer -------------------------------------------------------------
-
-export function renderJourney(body: JourneyBody): string {
-  const lines: string[] = ['journey']
-  if (body.title) lines.push(`  title ${formatJourneyInline(body.title)}`)
-  if (body.accessibilityTitle) lines.push(`  accTitle: ${formatJourneyInline(body.accessibilityTitle)}`)
-  if (body.accessibilityDescription) {
-    if (body.accessibilityDescription.includes('\n')) {
-      lines.push('  accDescr {')
-      for (const line of body.accessibilityDescription.split(/\r?\n/)) {
-        lines.push(`    ${line.trim()}`)
-      }
-      lines.push('  }')
-    } else {
-      lines.push(`  accDescr: ${formatJourneyInline(body.accessibilityDescription)}`)
-    }
-  }
-  for (const section of body.sections) {
-    if (section.label !== undefined) lines.push(`  section ${formatJourneyInline(section.label)}`)
-    for (const task of section.tasks) {
-      const actors = task.actors.length > 0 ? `: ${task.actors.join(', ')}` : ''
-      lines.push(`    ${formatJourneyInline(task.text)}: ${task.score}${actors}`)
-    }
-  }
-  return lines.join('\n') + '\n'
-}
-
-// ---- Mutator ----------------------------------------------------------------
-
-function cloneJourney(b: JourneyBody): JourneyBody {
-  return {
-    kind: 'journey',
-    title: b.title,
-    accessibilityTitle: b.accessibilityTitle,
-    accessibilityDescription: b.accessibilityDescription,
-    sections: b.sections.map(s => ({
-      id: s.id, label: s.label,
-      tasks: s.tasks.map(t => ({ id: t.id, text: t.text, score: t.score, actors: [...t.actors] })),
-    })),
-  }
-}
-
-function makeIdAllocator(body: JourneyBody): (prefix: 'section' | 'task') => string {
-  const seen = new Set<string>()
-  for (const s of body.sections) { seen.add(s.id); for (const t of s.tasks) seen.add(t.id) }
-  return prefix => {
-    let n = 0
-    while (seen.has(`${prefix}-${n}`)) n++
-    const id = `${prefix}-${n}`
-    seen.add(id)
-    return id
-  }
-}
-
-function normalizeOpText(value: string, field: string, opts: { allowColon?: boolean } = {}): Result<string, MutationError> {
-  if (typeof value !== 'string') return err({ code: 'INVALID_OP', message: `Journey ${field} must be a string` })
-  const normalized = normalizeText(value)
-  if (!normalized || (!opts.allowColon && normalized.includes(':'))) {
-    return err({ code: 'INVALID_OP', message: `Journey ${field} must be non-empty and must not contain :` })
-  }
-  return ok(normalized)
-}
-
-function normalizeActors(actors: string[] | undefined): Result<string[], MutationError> {
-  const out: string[] = []
-  for (const raw of actors ?? []) {
-    if (typeof raw !== 'string') return err({ code: 'INVALID_OP', message: 'Journey actor must be a string' })
-    const normalized = normalizeActorText(raw)
-    if (!normalized) return err({ code: 'INVALID_OP', message: 'Journey actor must be non-empty' })
-    out.push(normalized)
-  }
-  return ok(out)
-}
-
-function normalizeAccessibilityText(value: string): string {
-  return normalizeJourneyLabel(value)
-    .split(/\r?\n/)
-    .map(part => part.trim())
-    .filter(Boolean)
-    .join('\n')
-}
-
-function parseAccessibilityLine(
-  line: string,
-  directive: 'accTitle' | 'accDescr',
-): string | undefined {
-  const match = line.match(ACC_LINE_RE(directive))
-  return match ? normalizeAccessibilityText(match[1]!) : undefined
-}
-
-function collectAccessibilityBlock(
-  initial: string,
-  lines: string[],
-  startIndex: number,
-): { text: string; nextIndex: number } | null {
-  const initialEnd = initial.indexOf('}')
-  if (initialEnd !== -1) {
-    return {
-      text: initial.slice(0, initialEnd).trim(),
-      nextIndex: startIndex,
-    }
-  }
-
-  const parts = [initial.trim()].filter(Boolean)
-
-  for (let i = startIndex + 1; i < lines.length; i++) {
-    const line = lines[i]!
-    const end = line.indexOf('}')
-    if (end !== -1) {
-      const beforeBrace = line.slice(0, end).trim()
-      if (beforeBrace) parts.push(beforeBrace)
-      return {
-        text: parts.join('\n'),
-        nextIndex: i,
-      }
-    }
-    parts.push(line)
-  }
-
-  return null
-}
-
-export function mutateJourney(body: JourneyBody, op: JourneyMutationOp): Result<JourneyBody, MutationError> {
-  const next = cloneJourney(body)
-  const nextId = makeIdAllocator(next)
-
-  const getSection = (i: number): JourneySection | undefined => next.sections[i]
-  const getTask = (si: number, ti: number): JourneyTask | undefined => getSection(si)?.tasks[ti]
-
-  switch (op.kind) {
-    case 'set_title': {
-      if (op.title === null) delete next.title
-      else {
-        const title = normalizeOpText(op.title, 'title', { allowColon: true })
-        if (!title.ok) return title
-        next.title = title.value
-      }
-      break
-    }
-    case 'add_section': {
-      const label = normalizeOpText(op.label, 'section label')
-      if (!label.ok) return label
-      next.sections.push({ id: nextId('section'), label: label.value, tasks: [] })
-      break
-    }
-    case 'remove_section': {
-      if (!getSection(op.index)) return err({ code: 'SECTION_NOT_FOUND', message: `No section at index ${op.index}` })
-      next.sections.splice(op.index, 1)
-      break
-    }
-    case 'set_section_label': {
-      const s = getSection(op.index)
-      if (!s) return err({ code: 'SECTION_NOT_FOUND', message: `No section at index ${op.index}` })
-      const label = normalizeOpText(op.label, 'section label')
-      if (!label.ok) return label
-      s.label = label.value
-      break
-    }
-    case 'add_task': {
-      const s = getSection(op.sectionIndex)
-      if (!s) return err({ code: 'SECTION_NOT_FOUND', message: `No section at index ${op.sectionIndex}` })
-      const text = normalizeOpText(op.text, 'task text')
-      if (!text.ok) return text
-      if (!validScore(op.score)) return err({ code: 'INVALID_OP', message: `Journey score must be an integer 1..5, got ${op.score}` })
-      const actors = normalizeActors(op.actors)
-      if (!actors.ok) return actors
-      s.tasks.push({ id: nextId('task'), text: text.value, score: op.score, actors: actors.value })
-      break
-    }
-    case 'remove_task': {
-      const s = getSection(op.sectionIndex)
-      if (!s) return err({ code: 'SECTION_NOT_FOUND', message: `No section at index ${op.sectionIndex}` })
-      if (!s.tasks[op.taskIndex]) return err({ code: 'TASK_NOT_FOUND', message: `No task at index ${op.taskIndex}` })
-      s.tasks.splice(op.taskIndex, 1)
-      if (s.label === undefined && s.tasks.length === 0) next.sections.splice(op.sectionIndex, 1)
-      break
-    }
-    case 'set_task_text': {
-      const t = getTask(op.sectionIndex, op.taskIndex)
-      if (!t) return err({ code: 'TASK_NOT_FOUND', message: `No task at (${op.sectionIndex},${op.taskIndex})` })
-      const text = normalizeOpText(op.text, 'task text')
-      if (!text.ok) return text
-      t.text = text.value
-      break
-    }
-    case 'set_task_score': {
-      const t = getTask(op.sectionIndex, op.taskIndex)
-      if (!t) return err({ code: 'TASK_NOT_FOUND', message: `No task at (${op.sectionIndex},${op.taskIndex})` })
-      if (!validScore(op.score)) return err({ code: 'INVALID_OP', message: `Journey score must be an integer 1..5, got ${op.score}` })
-      t.score = op.score
-      break
-    }
-    case 'set_task_actors': {
-      const t = getTask(op.sectionIndex, op.taskIndex)
-      if (!t) return err({ code: 'TASK_NOT_FOUND', message: `No task at (${op.sectionIndex},${op.taskIndex})` })
-      const actors = normalizeActors(op.actors)
-      if (!actors.ok) return actors
-      t.actors = actors.value
-      break
-    }
-    case 'rename_actor': {
-      const from = normalizeOpText(op.from, 'actor', { allowColon: true })
-      if (!from.ok) return from
-      const to = normalizeOpText(op.to, 'actor', { allowColon: true })
-      if (!to.ok) return to
-      let found = false
-      for (const s of next.sections) {
-        for (const t of s.tasks) {
-          t.actors = t.actors.map(a => {
-            if (a === from.value) { found = true; return to.value }
-            return a
-          })
-        }
-      }
-      if (!found) return err({ code: 'ACTOR_NOT_FOUND', message: `Actor "${from.value}" not found` })
-      break
-    }
-    default: {
-      const _x: never = op
-      return err({ code: 'INVALID_OP', message: unknownOpMessage('journey', _x) })
-    }
-  }
-
-  // Preserve the structured floor: a journey without a scored task cannot
-  // render, so refuse mutations that would EMPTY a non-empty journey. A body
-  // that starts empty (createMermaid/buildMermaid) may stay empty while ops
-  // build it up — title/sections first, tasks after.
-  const hadTask = body.sections.some(s => s.tasks.length > 0)
-  if (hadTask && next.sections.every(s => s.tasks.length === 0)) {
-    return err({ code: 'INVALID_OP', message: 'Journey must keep at least one scored task' })
-  }
-
-  return ok(next)
-}
-
-// ---- Verifier (FamilyPlugin.verify hook) ------------------------------------
-
-export function verifyJourney(body: JourneyBody, opts: VerifyOptions): LayoutWarning[] {
-  const cap = opts.labelCharCap ?? DEFAULT_LABEL_CHAR_CAP
-  const warnings: LayoutWarning[] = []
-  const overflow = (target: string, text: string) => {
-    const w = labelOverflowWarning(target, text, cap)
-    if (w) warnings.push(w)
-  }
-  const hasTask = body.sections.some(s => s.tasks.length > 0)
-  const hasHeaderFurniture = body.title !== undefined
-    || body.accessibilityTitle !== undefined
-    || body.accessibilityDescription !== undefined
-    || body.sections.length > 0
-  if (!hasTask && !hasHeaderFurniture) warnings.push({ code: 'EMPTY_DIAGRAM' })
-  if (body.title !== undefined) {
-    const w = labelOverflowWarning('title', body.title, Math.max(cap, 80))
-    if (w) warnings.push(w)
-  }
-  for (const s of body.sections) {
-    if (s.label !== undefined) overflow(s.id, s.label)
-    for (const t of s.tasks) {
-      overflow(t.id, t.text)
-      for (const a of t.actors) overflow(t.id, a)
-    }
-  }
-  return warnings
-}

package/src/agent/label-metrics.ts

@@ -1,28 +0,0 @@
-// ============================================================================
-// Label display metrics — the LABEL_OVERFLOW cap measures what the renderer
-// draws, not raw source characters. The render pipeline decodes XML entities
-// (renderMermaidSVG runs decodeXML before parsing), converts <br> tags and
-// literal \n to line breaks, and strips formatting tags before measuring text
-// (multiline-utils.ts). Counting source chars instead flags legitimately-fine
-// multi-line labels whose markup (`<br/>`, `&#160;`) pads the count.
-// ============================================================================
-
-import { decodeXML } from 'entities'
-import { normalizeBrTags, stripFormattingTags } from '../multiline-utils.ts'
-import type { LayoutWarning } from './types.ts'
-
-/**
- * Length of a label as rendered: the longest line after entity decoding,
- * <br>/\n splitting, and formatting-tag stripping. `&#160;` counts as one
- * character; `<br/>` starts a new line and counts as zero.
- */
-export function labelDisplayLength(label: string): number {
-  const rendered = stripFormattingTags(normalizeBrTags(decodeXML(label)))
-  return rendered.split('\n').reduce((max, line) => Math.max(max, line.length), 0)
-}
-
-/** Build a LABEL_OVERFLOW warning when the rendered length exceeds the cap, else null. */
-export function labelOverflowWarning(target: string, text: string, cap: number): LayoutWarning | null {
-  const charCount = labelDisplayLength(text)
-  return charCount > cap ? { code: 'LABEL_OVERFLOW', target, charCount, limit: cap } : null
-}

package/src/agent/layout-to-rendered.ts

@@ -1,63 +0,0 @@
-// ============================================================================
-// Shared converter: ELK PositionedGraph → public RenderedLayout JSON.
-// Previously implemented in two places (verify.ts and index.ts's layoutMermaid)
-// — see DIVERGENCES "Cleanup findings". Single source of truth.
-// ============================================================================
-
-import type { PositionedGraph, PositionedNode, PositionedEdge, PositionedGroup } from '../types.ts'
-import type {
-  DiagramKind, Finite, RenderedLayout, RenderedLayoutNode, RenderedLayoutEdge, RenderedLayoutGroup,
-} from './types.ts'
-import { toFinite } from './types.ts'
-
-function f(n: number): Finite { return toFinite(Math.round(n)) }
-
-function node(n: PositionedNode): RenderedLayoutNode {
-  return { id: n.id, x: f(n.x), y: f(n.y), w: f(n.width), h: f(n.height), shape: n.shape, label: n.label }
-}
-
-function edge(e: PositionedEdge, debug: boolean): RenderedLayoutEdge {
-  return {
-    id: `${e.source}->${e.target}`,
-    from: e.source, to: e.target,
-    path: e.points.map(p => [f(p.x), f(p.y)] as [Finite, Finite]),
-    label: e.label && e.labelPosition
-      ? { x: f(e.labelPosition.x), y: f(e.labelPosition.y), text: e.label }
-      : undefined,
-    ...(debug && e.routeCertificate ? { route: e.routeCertificate } : {}),
-  }
-}
-
-export function positionedToRenderedLayout(p: PositionedGraph, kind: DiagramKind, opts: { debug?: boolean } = {}): RenderedLayout {
-  return {
-    version: 1, kind,
-    nodes: p.nodes.map(node),
-    edges: p.edges.map(e => edge(e, opts.debug === true)),
-    groups: renderedGroups(p.groups, p.nodes),
-    bounds: { w: f(p.width), h: f(p.height) },
-  }
-}
-
-function renderedGroups(groups: PositionedGroup[], nodes: PositionedNode[]): RenderedLayoutGroup[] {
-  const out: RenderedLayoutGroup[] = []
-  const containsNode = (g: PositionedGroup, n: PositionedNode): boolean =>
-    n.x >= g.x - 0.5 && n.y >= g.y - 0.5 && n.x + n.width <= g.x + g.width + 0.5 && n.y + n.height <= g.y + g.height + 0.5
-  const visit = (g: PositionedGroup, parentId?: string): void => {
-    const members = nodes
-      .filter(n => containsNode(g, n) && !g.children.some(child => containsNode(child, n)))
-      .map(n => n.id)
-    out.push({
-      id: g.id,
-      x: f(g.x), y: f(g.y), w: f(g.width), h: f(g.height),
-      members, label: g.label,
-      ...(parentId ? { parentId } : {}),
-    })
-    for (const child of g.children) visit(child, g.id)
-  }
-  for (const g of groups) visit(g)
-  return out
-}
-
-export function emptyRenderedLayout(kind: DiagramKind): RenderedLayout {
-  return { version: 1, kind, nodes: [], edges: [], groups: [], bounds: { w: f(0), h: f(0) } }
-}

package/src/agent/mutate.ts

@@ -1,97 +0,0 @@
-// ============================================================================
-// mutate: typed structural edits. Overloaded by family.
-// ============================================================================
-
-import type {
-  FlowchartValidDiagram, StateValidDiagram, SequenceValidDiagram, TimelineValidDiagram,
-  ClassValidDiagram, ErValidDiagram, JourneyValidDiagram, ArchitectureValidDiagram, XyChartValidDiagram, PieValidDiagram, QuadrantValidDiagram, GanttValidDiagram, MutableValidDiagram,
-  FlowchartMutationOp, StateMutationOp, SequenceMutationOp, TimelineMutationOp,
-  ClassMutationOp, ErMutationOp, JourneyMutationOp, ArchitectureMutationOp, XyChartMutationOp, PieMutationOp, QuadrantMutationOp, GanttMutationOp, AnyMutationOp,
-  MutationError, Result,
-} from './types.ts'
-import { ok, err } from './types.ts'
-import { wrapperPrefix } from './serialize.ts'
-import { logToolInvocation } from './trace-log.ts'
-import { getFamily } from './families.ts'
-import { validateOp, hasOpSchema } from './op-schema.ts'
-import './families-builtin.ts'  // registers built-in family mutate hooks
-
-export function mutate(d: FlowchartValidDiagram, op: FlowchartMutationOp): Result<FlowchartValidDiagram, MutationError>
-export function mutate(d: StateValidDiagram, op: StateMutationOp): Result<StateValidDiagram, MutationError>
-export function mutate(d: SequenceValidDiagram, op: SequenceMutationOp): Result<SequenceValidDiagram, MutationError>
-export function mutate(d: TimelineValidDiagram, op: TimelineMutationOp): Result<TimelineValidDiagram, MutationError>
-export function mutate(d: ClassValidDiagram, op: ClassMutationOp): Result<ClassValidDiagram, MutationError>
-export function mutate(d: ErValidDiagram, op: ErMutationOp): Result<ErValidDiagram, MutationError>
-export function mutate(d: JourneyValidDiagram, op: JourneyMutationOp): Result<JourneyValidDiagram, MutationError>
-export function mutate(d: ArchitectureValidDiagram, op: ArchitectureMutationOp): Result<ArchitectureValidDiagram, MutationError>
-export function mutate(d: XyChartValidDiagram, op: XyChartMutationOp): Result<XyChartValidDiagram, MutationError>
-export function mutate(d: PieValidDiagram, op: PieMutationOp): Result<PieValidDiagram, MutationError>
-export function mutate(d: QuadrantValidDiagram, op: QuadrantMutationOp): Result<QuadrantValidDiagram, MutationError>
-export function mutate(d: GanttValidDiagram, op: GanttMutationOp): Result<GanttValidDiagram, MutationError>
-// General form for callers holding the union (e.g. the CLI): dispatch is by
-// registry at runtime either way, so kind-agnostic call sites don't need a
-// per-family narrowing cascade.
-export function mutate(d: MutableValidDiagram, op: AnyMutationOp): Result<MutableValidDiagram, MutationError>
-export function mutate(
-  d: MutableValidDiagram,
-  op: AnyMutationOp,
-): Result<MutableValidDiagram, MutationError> {
-  // Log the OUTCOME (not just the call): an `{ok:false}` trace line records a
-  // failed op attempt — the observable signal the agent-usage eval reads to
-  // measure a run's op-error rate directly, rather than inferring retries from
-  // excess mutate-call counts.
-  const r = applyOneMutation(d, op)
-  logToolInvocation('mutate', r.ok)
-  return r
-}
-
-function applyOneMutation(
-  d: MutableValidDiagram,
-  op: AnyMutationOp,
-): Result<MutableValidDiagram, MutationError> {
-  // Every structured family mutates through its FamilyPlugin hook, then
-  // rebuilds canonicalSource from the new body so a mutated diagram never
-  // carries stale source. Lookup is by DIAGRAM kind, not body kind. State
-  // diagrams (BUILD-19) own a dedicated StateBody and bind the stateDiagram-v2
-  // header through their own plugin registration.
-  const plugin = getFamily(d.kind)
-  if (plugin?.mutate && plugin.serialize) {
-    const r = plugin.mutate(d.body, op)
-    if (!r.ok) return r
-    // 1C wrapper policy: a mutated diagram keeps its leading wrapper
-    // (frontmatter/directives/comments) byte-verbatim; only the body changes.
-    const canonicalSource = wrapperPrefix(d.meta) + plugin.serialize(r.value)
-    return ok({ ...d, body: r.value, canonicalSource } as MutableValidDiagram)
-  }
-  return err({ code: 'INVALID_OP', message: `Unsupported mutable diagram kind: ${d.kind}` })
-}
-
-/**
- * mutate with a shape check in front — the one choke point every UNTYPED edit
- * path funnels through: the declarative applyOps/buildChecked entrypoints, the
- * Code Mode facade, and the CLI `--op`/`--ops` path. Typed callers keep using
- * `mutate` directly, where the compiler already guarantees op shape;
- * `mutateChecked` restores that guarantee at the boundaries where ops arrive as
- * raw JSON.
- *
- * `validateOp` proves the op's SHAPE (field names, primitive types, enums)
- * BEFORE the mutator runs, so a malformed op is rejected with a prescriptive
- * INVALID_OP error instead of silently mangling the diagram. Semantics — does
- * the referenced node exist, is the id a duplicate — stay in the mutator, which
- * runs second on a shape-proven op. Result shape is identical to `mutate`, so
- * this is a drop-in wherever the raw mutator was called with untyped ops.
- */
-export function mutateChecked(d: MutableValidDiagram, op: unknown): Result<MutableValidDiagram, MutationError> {
-  if (hasOpSchema(d.kind)) {
-    const invalid = validateOp(d.kind, op)
-    // A shape rejection short-circuits before `mutate`, so record the failed
-    // attempt here — otherwise checked-path errors (e.g. the op-array slip)
-    // would go uncounted in the op-error rate.
-    if (invalid) { logToolInvocation('mutate', false); return err(invalid) }
-  }
-  return mutate(d, op as AnyMutationOp)
-}
-
-// Flowchart graph mutation + helpers live in flowchart-body.ts; edgeIdOf is
-// re-exported here for existing consumers (agent/index.ts, eval harness).
-export { edgeIdOf } from './flowchart-body.ts'

package/src/agent/mutation-ops.ts

@@ -1,51 +0,0 @@
-import type { BuiltinFamilyId } from './families.ts'
-import type { DiagramKind } from './types.ts'
-
-// Single source of truth for each family's structured mutation op `kind`s. It
-// lives in the agent layer, next to the mutators, so two consumers read the
-// same list: the CLI `capabilities` envelope (re-exported from src/cli/index.ts)
-// and the mutators' "unknown op" errors, which name the family's valid ops
-// instead of leaving a caller — especially a smaller model — to guess them.
-export const MUTATION_OPS_BY_FAMILY = {
-  flowchart: ['add_node', 'remove_node', 'rename_node', 'set_label', 'add_edge', 'remove_edge'],
-  state: ['add_state', 'remove_state', 'rename_state', 'set_state_label', 'add_transition', 'remove_transition', 'set_transition_label', 'make_composite'],
-  sequence: ['add_participant', 'remove_participant', 'add_message', 'remove_message', 'set_message_text'],
-  timeline: ['set_title', 'add_section', 'remove_section', 'set_section_label', 'add_period', 'remove_period', 'set_period_label', 'add_event', 'remove_event', 'set_event_text'],
-  class: ['set_title', 'add_class', 'remove_class', 'rename_class', 'add_member', 'remove_member', 'add_relation', 'remove_relation', 'add_note', 'remove_note'],
-  er: ['add_entity', 'remove_entity', 'rename_entity', 'add_attribute', 'remove_attribute', 'add_relation', 'remove_relation'],
-  journey: ['set_title', 'add_section', 'remove_section', 'set_section_label', 'add_task', 'remove_task', 'set_task_text', 'set_task_score', 'set_task_actors', 'rename_actor'],
-  architecture: ['add_service', 'remove_service', 'rename_service', 'set_service_label', 'set_service_icon', 'move_service', 'add_group', 'remove_group', 'add_edge', 'remove_edge'],
-  xychart: ['set_title', 'set_x_axis', 'set_y_axis', 'add_series', 'remove_series', 'set_series_values', 'set_series_name', 'reorder_series'],
-  pie: ['set_title', 'set_show_data', 'add_slice', 'remove_slice', 'rename_slice', 'set_slice_value', 'reorder_slice'],
-  quadrant: ['set_title', 'set_axis_labels', 'set_quadrant_label', 'add_point', 'remove_point', 'move_point', 'rename_point'],
-  gantt: ['set_title', 'add_section', 'rename_section', 'remove_section', 'add_task', 'remove_task', 'rename_task', 'set_task_status', 'set_task_dates'],
-} as const satisfies Record<BuiltinFamilyId, readonly string[]>
-
-export type MutableFamilyId = keyof typeof MUTATION_OPS_BY_FAMILY
-
-/** The valid mutation-op `kind`s for a family, as a display string — for
- *  prescriptive "unknown op" errors that hand the caller the actual menu. */
-export function validOpsFor(family: DiagramKind): string {
-  const ops = (MUTATION_OPS_BY_FAMILY as Record<string, readonly string[]>)[family]
-  return ops ? ops.join(', ') : '(none — this family has no structured ops)'
-}
-
-/** Message for an op whose `kind` a family's mutator does not recognize: names
- *  the offending kind AND the family's valid ops, so the caller can correct it
- *  from the error alone instead of guessing which ops exist. */
-export function unknownOpMessage(family: DiagramKind, op: unknown): string {
-  // Passing an op ARRAY where one op is expected is the single most common shape
-  // slip — it recurs on nearly every case across every model tier in the
-  // agent-usage eval (mutate() applies ONE op, but "apply these ops" reads as a
-  // list). Hand back the rule and the batch alternatives so the next action is
-  // in the message, not left to infer from a dumped array.
-  if (Array.isArray(op)) {
-    return `Expected a single ${family} op, got an array of ${op.length}. `
-      + `Ops apply one at a time: call mutate() once per op, or pass the whole list to a batch `
-      + `entrypoint — applyOps({ source, family, ops }) to edit source, or buildMermaid(kind, ops) `
-      + `to author — valid ${family} ops: ${validOpsFor(family)}`
-  }
-  const kind = (op as { kind?: unknown } | null | undefined)?.kind
-  const got = typeof kind === 'string' ? `"${kind}"` : JSON.stringify(op)
-  return `Unknown ${family} op ${got} — valid ops: ${validOpsFor(family)}`
-}