agentic-mermaid 0.1.1 → 0.2.0

package/src/agent/journey-body.ts

@@ -1,374 +0,0 @@
-// ============================================================================
-// Journey structured body (BUILD-15 pilot for promoting source-level families).
-//
-// The grammar lives in src/journey/parse-core.ts and is shared with the
-// renderer parser, so the two surfaces cannot drift on documented syntax:
-//   title <text>
-//   accTitle: <text>
-//   accDescr: <text>
-//   accDescr { <multiline text> }
-//   section <label>
-//   <task text>: <score 1..5>[: <actor>[, <actor>…]]
-//
-// Structured-or-opaque with a typed reason: any line the grammar rejects
-// yields the JourneyParseIssue that triggered opacity, so the caller can fall
-// back to a lossless opaque body AND verify can say why. 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'
-import {
-  walkJourneyLines, normalizeJourneyText, normalizeJourneyActor,
-  isValidJourneyScore, type JourneyParseIssue,
-} from '../journey/parse-core.ts'
-
-// ---- Parser -----------------------------------------------------------------
-
-export type JourneyBodyParse =
-  | { ok: true; body: JourneyBody }
-  | { ok: false; issue: JourneyParseIssue }
-
-function formatJourneyInline(value: string): string {
-  return value.split(/\r?\n/).map(part => part.trim()).join('<br>')
-}
-
-/**
- * Parse journey body lines (header excluded). Returns a structured body only
- * if EVERY non-blank, non-comment statement is modeled grammar with a valid
- * 1..5 integer score. Otherwise returns the first JourneyParseIssue so the
- * opaque fallback can carry its reason.
- */
-export function parseJourneyBody(lines: string[]): JourneyBodyParse {
-  const body: JourneyBody = { kind: 'journey', sections: [] }
-  let currentSection: JourneySection | undefined
-  let sIdx = 0, tIdx = 0
-  let firstIssue: JourneyParseIssue | undefined
-
-  const implicitSection = (): JourneySection => {
-    if (!currentSection) {
-      currentSection = { id: `section-${sIdx++}`, tasks: [] }
-      body.sections.push(currentSection)
-    }
-    return currentSection
-  }
-
-  walkJourneyLines(lines, 0, {
-    title: text => { body.title = text },
-    accTitle: text => { body.accessibilityTitle = text },
-    accDescr: text => { body.accessibilityDescription = text },
-    section: label => {
-      currentSection = { id: `section-${sIdx++}`, label, tasks: [] }
-      body.sections.push(currentSection)
-    },
-    task: (text, score, actors) => {
-      implicitSection().tasks.push({ id: `task-${tIdx++}`, text, score, actors })
-    },
-    issue: issue => {
-      firstIssue = issue
-      return 'stop'
-    },
-  })
-
-  if (firstIssue) return { ok: false, issue: firstIssue }
-
-  // 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 {
-      ok: false,
-      issue: { code: 'empty_journey', lineIndex: 0, statement: '', detail: 'Journey has no title, sections, or scored tasks' },
-    }
-  }
-
-  return { ok: true, 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 = normalizeJourneyText(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 resolveInsertIndex(index: number | undefined, length: number): Result<number, MutationError> {
-  if (index === undefined) return ok(length)
-  if (!Number.isInteger(index) || index < 0 || index > length) {
-    return err({ code: 'INVALID_OP', message: `Journey insert index ${index} out of range (0..${length})` })
-  }
-  return ok(index)
-}
-
-/** Accessibility text is line-oriented free text, but `;` terminates a
- * journey statement and `{`/`}` delimit the accDescr block form — text
- * carrying them would not survive serialize → re-parse. null clears. */
-function normalizeAccessibilityOpText(
-  value: string | null,
-  field: string,
-): Result<string | undefined, MutationError> {
-  if (value === null) return ok(undefined)
-  if (typeof value !== 'string') return err({ code: 'INVALID_OP', message: `Journey ${field} must be a string or null` })
-  const normalized = normalizeJourneyText(value)
-  if (!normalized || /[;{}]/.test(normalized)) {
-    return err({ code: 'INVALID_OP', message: `Journey ${field} must be non-empty and must not contain ;, {, or }` })
-  }
-  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 = normalizeJourneyActor(raw)
-    if (!normalized) return err({ code: 'INVALID_OP', message: 'Journey actor must be non-empty' })
-    out.push(normalized)
-  }
-  return ok(out)
-}
-
-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
-      const index = resolveInsertIndex(op.index, next.sections.length)
-      if (!index.ok) return index
-      next.sections.splice(index.value, 0, { 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 (!isValidJourneyScore(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
-      const index = resolveInsertIndex(op.index, s.tasks.length)
-      if (!index.ok) return index
-      s.tasks.splice(index.value, 0, { 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 (!isValidJourneyScore(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 'move_task': {
-      const from = getSection(op.fromSection)
-      if (!from) return err({ code: 'SECTION_NOT_FOUND', message: `No section at index ${op.fromSection}` })
-      if (!from.tasks[op.fromIndex]) return err({ code: 'TASK_NOT_FOUND', message: `No task at index ${op.fromIndex}` })
-      const to = getSection(op.toSection)
-      if (!to) return err({ code: 'SECTION_NOT_FOUND', message: `No section at index ${op.toSection}` })
-      const [task] = from.tasks.splice(op.fromIndex, 1)
-      if (!Number.isInteger(op.toIndex) || op.toIndex < 0 || op.toIndex > to.tasks.length) {
-        return err({ code: 'TASK_NOT_FOUND', message: `No insert position ${op.toIndex} in section ${op.toSection} (0..${to.tasks.length})` })
-      }
-      to.tasks.splice(op.toIndex, 0, task!)
-      // remove_task parity: an emptied implicit (unlabeled) section disappears.
-      if (from !== to && from.label === undefined && from.tasks.length === 0) {
-        next.sections.splice(next.sections.indexOf(from), 1)
-      }
-      break
-    }
-    case 'move_section': {
-      if (!getSection(op.from)) return err({ code: 'SECTION_NOT_FOUND', message: `No section at index ${op.from}` })
-      if (!Number.isInteger(op.to) || op.to < 0 || op.to >= next.sections.length) {
-        return err({ code: 'SECTION_NOT_FOUND', message: `No section position ${op.to} (0..${next.sections.length - 1})` })
-      }
-      const [section] = next.sections.splice(op.from, 1)
-      next.sections.splice(op.to, 0, section!)
-      break
-    }
-    case 'set_accessibility_title': {
-      const title = normalizeAccessibilityOpText(op.title, 'accessibility title')
-      if (!title.ok) return title
-      if (title.value === undefined) delete next.accessibilityTitle
-      else next.accessibilityTitle = title.value
-      break
-    }
-    case 'set_accessibility_description': {
-      const description = normalizeAccessibilityOpText(op.description, 'accessibility description')
-      if (!description.ok) return description
-      if (description.value === undefined) delete next.accessibilityDescription
-      else next.accessibilityDescription = description.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', 'move_task', 'move_section', 'set_accessibility_title', 'set_accessibility_description'],
-  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)}`
-}