agentic-mermaid 0.1.1 → 0.2.0

package/src/agent/op-schema.ts

@@ -1,443 +0,0 @@
-// ============================================================================
-// op-schema: shape validation for every family's structured mutation ops.
-//
-// The typed `mutate` surface is guaranteed by the compiler — but the MCP and
-// CLI boundaries hand it ops as untyped JSON, where those guarantees evaporate:
-// a model that writes `{kind:'add_class', name:'Duck'}` (using `name` where
-// `id` is expected) slips a shapeless object past the type system, and the
-// mutator silently produces `class undefined`. This layer restores the missing
-// check at the one place untyped ops arrive: it validates op SHAPE (field
-// presence, primitive type, enum membership) BEFORE the mutator runs, and
-// rejects a malformed op with a PRESCRIPTIVE INVALID_OP error that names the
-// offending field and lists the valid ones (with a nearest-match suggestion
-// for an obvious typo).
-//
-// Scope: shape only. Semantic checks — does the referenced class exist, is the
-// id already taken, is the index in range — stay in the existing mutators. The
-// two layers compose: shape first (here), semantics second (the mutator). The
-// field lists below are transcribed from the *MutationOp union types in
-// types.ts, so a valid typed op always passes; the whole unit suite exercising
-// the mutators through the checked core is the proof (see apply.ts).
-// ============================================================================
-
-import type { NodeShape, EdgeStyle } from '../types.ts'
-import type {
-  SequenceMessageStyle, ClassRelationKind, ErCardinality, ArchitectureSide, GanttBodyTaskTag,
-} from './types.ts'
-import { unknownOpMessage } from './mutation-ops.ts'
-import type { MutableFamilyId } from './mutation-ops.ts'
-
-export type OpFamily = MutableFamilyId
-
-/** Primitive kinds a field may hold. `enum` carries an explicit value list;
- *  `nullable` lets an enum/primitive also accept `null` (e.g. set_task_status). */
-type FieldType =
-  | { type: 'string' }
-  | { type: 'number' }
-  | { type: 'boolean' }
-  | { type: 'string-or-null' }
-  | { type: 'enum'; values: readonly string[]; nullable?: boolean }
-  | { type: 'string-array' }
-  | { type: 'number-array' }
-  | { type: 'object-or-null' } // a nested record (deep shape validated by the mutator)
-
-/** A field type plus its required flag. Intersection (not `extends`) because
- *  FieldType is a union — an interface cannot extend a union. */
-type FieldSpec = FieldType & {
-  /** required = must be present and non-undefined. Optional fields may be omitted. */
-  required: boolean
-  /** Optional human note surfaced in discovery: a value constraint the MUTATOR
-   *  (not this shape layer) enforces (e.g. "1..5"), or the default applied when
-   *  an optional field is omitted (e.g. "default: rectangle"). Descriptive only
-   *  — the mutator remains the single enforcement point. */
-  note?: string
-}
-
-interface OpSpec {
-  /** field-name -> spec. `kind` is implicit and never listed. */
-  fields: Record<string, FieldSpec>
-  /** Optional cross-field rule: at least one of these must be present (e.g.
-   *  architecture remove_edge accepts `index` OR `id`). */
-  requireOneOf?: readonly string[]
-}
-
-// Enum value lists, kept in sync with the type aliases they mirror.
-const NODE_SHAPES: readonly NodeShape[] = [
-  'rectangle', 'service', 'rounded', 'diamond', 'stadium', 'circle', 'subroutine',
-  'doublecircle', 'hexagon', 'cylinder', 'asymmetric', 'trapezoid', 'trapezoid-alt',
-  'lean-r', 'lean-l', 'state-start', 'state-end',
-]
-const EDGE_STYLES: readonly EdgeStyle[] = ['solid', 'dotted', 'thick', 'invisible']
-const SEQUENCE_MESSAGE_STYLES: readonly SequenceMessageStyle[] = ['sync', 'reply', 'async', 'async-dashed', 'lost', 'lost-dashed']
-const PARTICIPANT_KINDS = ['participant', 'actor'] as const
-const CLASS_REL_KINDS: readonly ClassRelationKind[] = ['inheritance', 'composition', 'aggregation', 'association', 'dependency', 'realization', 'link-solid', 'link-dashed']
-const ER_CARDINALITIES: readonly ErCardinality[] = ['one-only', 'zero-or-one', 'zero-or-many', 'one-or-many']
-const ARCH_SIDES: readonly ArchitectureSide[] = ['L', 'R', 'T', 'B']
-const SERIES_KINDS = ['bar', 'line'] as const
-const AXIS_KINDS = ['x', 'y'] as const
-const GANTT_STATUSES = ['active', 'done', 'crit'] as const
-const _GANTT_TAGS: readonly GanttBodyTaskTag[] = ['active', 'done', 'crit', 'milestone', 'vert'] // tags are shape-checked as string[]; deep enum check stays in the mutator
-
-// Field-spec shorthands.
-const str = (required = true): FieldSpec => ({ type: 'string', required })
-const num = (required = true): FieldSpec => ({ type: 'number', required })
-const bool = (required = true): FieldSpec => ({ type: 'boolean', required })
-const strOrNull = (required = true): FieldSpec => ({ type: 'string-or-null', required })
-const strArr = (required = true): FieldSpec => ({ type: 'string-array', required })
-const numArr = (required = true): FieldSpec => ({ type: 'number-array', required })
-const objOrNull = (required = true): FieldSpec => ({ type: 'object-or-null', required })
-const oneOf = (values: readonly string[], required = true, nullable = false): FieldSpec => ({ type: 'enum', values, nullable, required })
-/** Attach a discovery note (mutator-enforced constraint or omit-default) to a
- *  field spec without changing its shape validation. */
-const withNote = (spec: FieldSpec, note: string): FieldSpec => ({ ...spec, note })
-
-// ---- Per-op schemas (transcribed from the *MutationOp unions in types.ts) ---
-
-const FLOWCHART_SCHEMA: Record<string, OpSpec> = {
-  add_node:    { fields: { id: str(), label: str(), shape: withNote(oneOf(NODE_SHAPES, false), 'default: rectangle'), parent: str(false) } },
-  remove_node: { fields: { id: str() } },
-  rename_node: { fields: { from: str(), to: str() } },
-  set_label:   { fields: { target: str(), label: str() } },
-  add_edge:    { fields: { from: str(), to: str(), label: str(false), style: withNote(oneOf(EDGE_STYLES, false), 'default: solid') } },
-  remove_edge: { fields: { id: str() } },
-}
-
-const STATE_SCHEMA: Record<string, OpSpec> = {
-  add_state:            { fields: { id: str(), label: strOrNull(false), parent: strOrNull(false) } },
-  remove_state:         { fields: { id: str() } },
-  rename_state:         { fields: { from: str(), to: str() } },
-  set_state_label:      { fields: { id: str(), label: strOrNull() } },
-  add_transition:       { fields: { from: str(), to: str(), label: strOrNull(false), parent: strOrNull(false) } },
-  remove_transition:    { fields: { index: num(false), from: str(false), to: str(false), parent: strOrNull(false) }, requireOneOf: ['index', 'from', 'to'] },
-  set_transition_label: { fields: { index: num(false), from: str(false), to: str(false), label: strOrNull(), parent: strOrNull(false) }, requireOneOf: ['index', 'from', 'to'] },
-  make_composite:       { fields: { id: str(), members: strArr(), label: strOrNull(false) } },
-}
-
-const SEQUENCE_SCHEMA: Record<string, OpSpec> = {
-  add_participant:  { fields: { id: str(), label: str(false), participantKind: oneOf(PARTICIPANT_KINDS, false) } },
-  remove_participant: { fields: { id: str() } },
-  add_message:      { fields: { from: str(), to: str(), text: str(), style: withNote(oneOf(SEQUENCE_MESSAGE_STYLES, false), 'default: sync') } },
-  remove_message:   { fields: { index: num() } },
-  set_message_text: { fields: { index: num(), text: str() } },
-}
-
-const TIMELINE_SCHEMA: Record<string, OpSpec> = {
-  set_title:         { fields: { title: strOrNull() } },
-  add_section:       { fields: { label: str() } },
-  remove_section:    { fields: { index: num() } },
-  set_section_label: { fields: { index: num(), label: str() } },
-  add_period:        { fields: { sectionIndex: num(), label: str(), events: strArr(false) } },
-  remove_period:     { fields: { sectionIndex: num(), periodIndex: num() } },
-  set_period_label:  { fields: { sectionIndex: num(), periodIndex: num(), label: str() } },
-  add_event:         { fields: { sectionIndex: num(), periodIndex: num(), text: str() } },
-  remove_event:      { fields: { sectionIndex: num(), periodIndex: num(), eventIndex: num() } },
-  set_event_text:    { fields: { sectionIndex: num(), periodIndex: num(), eventIndex: num(), text: str() } },
-}
-
-const CLASS_SCHEMA: Record<string, OpSpec> = {
-  set_title:       { fields: { title: strOrNull() } },
-  add_class:       { fields: { id: str(), label: str(false), members: strArr(false) } },
-  remove_class:    { fields: { id: str() } },
-  rename_class:    { fields: { from: str(), to: str() } },
-  add_member:      { fields: { class: str(), text: str() } },
-  remove_member:   { fields: { class: str(), index: num() } },
-  add_relation:    { fields: { from: str(), to: str(), relKind: oneOf(CLASS_REL_KINDS), label: str(false) } },
-  remove_relation: { fields: { index: num() } },
-  add_note:        { fields: { text: str(), for: str(false) } },
-  remove_note:     { fields: { index: num() } },
-}
-
-const ER_SCHEMA: Record<string, OpSpec> = {
-  add_entity:       { fields: { id: str(), attributes: strArr(false) } },
-  remove_entity:    { fields: { id: str() } },
-  rename_entity:    { fields: { from: str(), to: str() } },
-  add_attribute:    { fields: { entity: str(), text: str() } },
-  remove_attribute: { fields: { entity: str(), index: num() } },
-  add_relation:     { fields: { from: str(), to: str(), leftCard: oneOf(ER_CARDINALITIES), rightCard: oneOf(ER_CARDINALITIES), dashed: bool(false), label: str(false) } },
-  remove_relation:  { fields: { index: num() } },
-}
-
-const JOURNEY_SCHEMA: Record<string, OpSpec> = {
-  set_title:         { fields: { title: strOrNull() } },
-  add_section:       { fields: { label: str(), index: withNote(num(false), 'insert position; omit to append') } },
-  remove_section:    { fields: { index: num() } },
-  set_section_label: { fields: { index: num(), label: str() } },
-  add_task:          { fields: { sectionIndex: num(), text: str(), score: withNote(num(), 'integer 1..5'), actors: strArr(false), index: withNote(num(false), 'insert position; omit to append') } },
-  remove_task:       { fields: { sectionIndex: num(), taskIndex: num() } },
-  set_task_text:     { fields: { sectionIndex: num(), taskIndex: num(), text: str() } },
-  set_task_score:    { fields: { sectionIndex: num(), taskIndex: num(), score: withNote(num(), 'integer 1..5') } },
-  set_task_actors:   { fields: { sectionIndex: num(), taskIndex: num(), actors: strArr() } },
-  rename_actor:      { fields: { from: str(), to: str() } },
-  move_task:         { fields: { fromSection: num(), fromIndex: num(), toSection: num(), toIndex: withNote(num(), 'insert position in the target section, applied after removal') } },
-  move_section:      { fields: { from: num(), to: num() } },
-  set_accessibility_title:       { fields: { title: strOrNull() } },
-  set_accessibility_description: { fields: { description: strOrNull() } },
-}
-
-const ARCHITECTURE_SCHEMA: Record<string, OpSpec> = {
-  add_service:       { fields: { id: str(), label: str(false), icon: strOrNull(false), group: strOrNull(false) } },
-  remove_service:    { fields: { id: str() } },
-  rename_service:    { fields: { from: str(), to: str() } },
-  set_service_label: { fields: { id: str(), label: str() } },
-  set_service_icon:  { fields: { id: str(), icon: strOrNull() } },
-  move_service:      { fields: { id: str(), group: strOrNull() } },
-  add_group:         { fields: { id: str(), label: str(false), icon: strOrNull(false), parent: strOrNull(false) } },
-  remove_group:      { fields: { id: str() } },
-  add_edge:          { fields: { from: str(), to: str(), fromSide: oneOf(ARCH_SIDES), toSide: oneOf(ARCH_SIDES), label: strOrNull(false), hasArrowStart: bool(false), hasArrowEnd: bool(false) } },
-  remove_edge:       { fields: { index: num(false), id: str(false) }, requireOneOf: ['index', 'id'] },
-}
-
-const XYCHART_SCHEMA: Record<string, OpSpec> = {
-  set_title:         { fields: { title: strOrNull() } },
-  set_x_axis:        { fields: { axis: objOrNull() } },
-  set_y_axis:        { fields: { axis: objOrNull() } },
-  add_series:        { fields: { kind2: withNote(oneOf(SERIES_KINDS), 'series type — the field is named kind2, not kind'), name: strOrNull(false), values: numArr() } },
-  remove_series:     { fields: { index: num() } },
-  set_series_values: { fields: { index: num(), values: numArr() } },
-  set_series_name:   { fields: { index: num(), name: strOrNull() } },
-  reorder_series:    { fields: { from: num(), to: num() } },
-}
-
-const PIE_SCHEMA: Record<string, OpSpec> = {
-  set_title:       { fields: { title: strOrNull() } },
-  set_show_data:   { fields: { showData: bool() } },
-  add_slice:       { fields: { label: str(), value: withNote(num(), '> 0, finite') } },
-  remove_slice:    { fields: { label: str() } },
-  rename_slice:    { fields: { from: str(), to: str() } },
-  set_slice_value: { fields: { label: str(), value: withNote(num(), '> 0, finite') } },
-  reorder_slice:   { fields: { from: num(), to: num() } },
-}
-
-const QUADRANT_SCHEMA: Record<string, OpSpec> = {
-  set_title:           { fields: { title: strOrNull() } },
-  set_axis_labels:     { fields: { axis: oneOf(AXIS_KINDS), near: strOrNull(), far: strOrNull(false) } },
-  set_quadrant_label:  { fields: { quadrant: num(), label: strOrNull() } },
-  add_point:           { fields: { label: str(), x: withNote(num(), '0..1'), y: withNote(num(), '0..1') } },
-  remove_point:        { fields: { label: str() } },
-  move_point:          { fields: { label: str(), x: withNote(num(), '0..1'), y: withNote(num(), '0..1') } },
-  rename_point:        { fields: { from: str(), to: str() } },
-}
-
-const GANTT_SCHEMA: Record<string, OpSpec> = {
-  set_title:       { fields: { title: strOrNull() } },
-  add_section:     { fields: { label: str() } },
-  rename_section:  { fields: { index: num(), label: str() } },
-  remove_section:  { fields: { index: num() } },
-  add_task:        { fields: { sectionIndex: num(), label: str(), taskId: str(false), tags: strArr(false), start: withNote(str(false), 'date, or "after <taskId>"'), end: withNote(str(), 'date, a duration like "3d", or "until <taskId>"') } },
-  remove_task:     { fields: { sectionIndex: num(), taskIndex: num() } },
-  rename_task:     { fields: { sectionIndex: num(), taskIndex: num(), label: str() } },
-  set_task_status: { fields: { sectionIndex: num(), taskIndex: num(), status: oneOf(GANTT_STATUSES, true, true) } },
-  set_task_dates:  { fields: { sectionIndex: num(), taskIndex: num(), start: strOrNull(false), end: str(false) } },
-}
-
-const SCHEMAS: Record<OpFamily, Record<string, OpSpec>> = {
-  flowchart: FLOWCHART_SCHEMA,
-  state: STATE_SCHEMA,
-  sequence: SEQUENCE_SCHEMA,
-  timeline: TIMELINE_SCHEMA,
-  class: CLASS_SCHEMA,
-  er: ER_SCHEMA,
-  journey: JOURNEY_SCHEMA,
-  architecture: ARCHITECTURE_SCHEMA,
-  xychart: XYCHART_SCHEMA,
-  pie: PIE_SCHEMA,
-  quadrant: QUADRANT_SCHEMA,
-  gantt: GANTT_SCHEMA,
-}
-
-/** True when `family` has a shape schema (i.e. is a mutable structured family). */
-export function hasOpSchema(family: string): family is OpFamily {
-  return family in SCHEMAS
-}
-
-// ---- Prescriptive error ---------------------------------------------------
-
-/**
- * Structured, model-actionable validation error. `code` is always INVALID_OP
- * (so it flows through the existing MutationError channel unchanged), but the
- * payload names the exact problem and enumerates the legal fields so a weak
- * model can self-correct in one turn.
- */
-export interface OpValidationError {
-  code: 'INVALID_OP'
-  /** 'expected_single_op' | 'unknown_kind' | 'unknown_field' | 'missing_field' | 'wrong_type' | 'require_one_of' */
-  reason: string
-  message: string
-  family: OpFamily
-  opKind?: string
-  /** the offending field, when applicable */
-  field?: string
-  /** valid field names for this op (or valid op kinds, for unknown_kind) */
-  validFields?: string[]
-  /** nearest valid name to a typo'd field/kind, when an obvious match exists */
-  didYouMean?: string
-}
-
-function levenshtein(a: string, b: string): number {
-  const m = a.length, n = b.length
-  const d = Array.from({ length: m + 1 }, (_, i) => [i, ...Array(n).fill(0)])
-  for (let j = 0; j <= n; j++) d[0]![j] = j
-  for (let i = 1; i <= m; i++)
-    for (let j = 1; j <= n; j++)
-      d[i]![j] = Math.min(d[i - 1]![j]! + 1, d[i]![j - 1]! + 1, d[i - 1]![j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1))
-  return d[m]![n]!
-}
-
-/** Nearest candidate within an edit-distance threshold (typo tolerance). */
-function nearest(target: string, candidates: string[]): string | undefined {
-  let best: string | undefined
-  let bestD = Infinity
-  for (const c of candidates) {
-    const dist = levenshtein(target.toLowerCase(), c.toLowerCase())
-    if (dist < bestD) { bestD = dist; best = c }
-  }
-  // Only suggest when the match is close (<= ~40% of the longer string).
-  return best !== undefined && bestD <= Math.max(2, Math.ceil(best.length * 0.4)) ? best : undefined
-}
-
-function typeName(f: FieldType): string {
-  switch (f.type) {
-    case 'string': return 'string'
-    case 'number': return 'number'
-    case 'boolean': return 'boolean'
-    case 'string-or-null': return 'string | null'
-    case 'string-array': return 'string[]'
-    case 'number-array': return 'number[]'
-    case 'object-or-null': return 'object | null'
-    case 'enum': return `one of ${f.values.map(v => JSON.stringify(v)).join(', ')}${f.nullable ? ' | null' : ''}`
-  }
-}
-
-function matchesType(spec: FieldType, value: unknown): boolean {
-  switch (spec.type) {
-    case 'string': return typeof value === 'string'
-    case 'number': return typeof value === 'number' && Number.isFinite(value)
-    case 'boolean': return typeof value === 'boolean'
-    case 'string-or-null': return value === null || typeof value === 'string'
-    case 'string-array': return Array.isArray(value) && value.every(v => typeof v === 'string')
-    case 'number-array': return Array.isArray(value) && value.every(v => typeof v === 'number' && Number.isFinite(v))
-    case 'object-or-null': return value === null || (typeof value === 'object' && !Array.isArray(value))
-    case 'enum': return (spec.nullable === true && value === null) || (typeof value === 'string' && spec.values.includes(value))
-  }
-}
-
-/**
- * Validate one op's SHAPE against its family schema. Returns null when valid.
- * The one and only shape choke point: every untyped edit path (declarative
- * applyOps / buildChecked and the Code Mode facade) calls this — through
- * mutateChecked — before touching a mutator.
- */
-export function validateOp(family: OpFamily, op: unknown): OpValidationError | null {
-  const schema = SCHEMAS[family]
-  // An op array is the common "apply these ops" slip — give it a dedicated
-  // reason so a caller can branch on it, and a message that names the batch fix.
-  if (Array.isArray(op)) {
-    return { code: 'INVALID_OP', reason: 'expected_single_op', family, message: unknownOpMessage(family, op), validFields: Object.keys(schema) }
-  }
-  if (!op || typeof op !== 'object') {
-    return { code: 'INVALID_OP', reason: 'unknown_kind', family, message: unknownOpMessage(family, op), validFields: Object.keys(schema) }
-  }
-  const rec = op as Record<string, unknown>
-  const kind = rec.kind
-  if (typeof kind !== 'string' || !(kind in schema)) {
-    const validKinds = Object.keys(schema)
-    const dym = typeof kind === 'string' ? nearest(kind, validKinds) : undefined
-    // Reuse the mutator's own prescriptive phrasing ("valid ops: …") so the
-    // message is identical no matter which layer catches the unknown kind; add
-    // a typo suggestion on top.
-    return {
-      code: 'INVALID_OP', reason: 'unknown_kind', family, opKind: typeof kind === 'string' ? kind : undefined,
-      message: `${unknownOpMessage(family, op)}${dym ? ` Did you mean "${dym}"?` : ''}`,
-      validFields: validKinds, didYouMean: dym,
-    }
-  }
-
-  const spec = schema[kind]!
-  const validFields = Object.keys(spec.fields)
-
-  // 1) Unknown / misnamed fields (this catches the `name`-instead-of-`id` bug).
-  for (const key of Object.keys(rec)) {
-    if (key === 'kind') continue
-    if (!(key in spec.fields)) {
-      const dym = nearest(key, validFields)
-      return {
-        code: 'INVALID_OP', reason: 'unknown_field', family, opKind: kind, field: key,
-        message: `Unknown field "${key}" for ${family} op "${kind}".${dym ? ` Did you mean "${dym}"?` : ''} Valid fields: ${validFields.join(', ')}.`,
-        validFields, didYouMean: dym,
-      }
-    }
-  }
-
-  // 2) Missing required fields.
-  for (const [name, fspec] of Object.entries(spec.fields)) {
-    if (!fspec.required) continue
-    if (rec[name] === undefined) {
-      return {
-        code: 'INVALID_OP', reason: 'missing_field', family, opKind: kind, field: name,
-        message: `Missing required field "${name}" (${typeName(fspec)}) for ${family} op "${kind}". Fields: ${validFields.join(', ')}.`,
-        validFields,
-      }
-    }
-  }
-
-  // 3) requireOneOf (e.g. remove_edge needs index OR id).
-  if (spec.requireOneOf && !spec.requireOneOf.some(f => rec[f] !== undefined)) {
-    return {
-      code: 'INVALID_OP', reason: 'require_one_of', family, opKind: kind,
-      message: `${family} op "${kind}" requires at least one of: ${spec.requireOneOf.join(', ')}.`,
-      validFields,
-    }
-  }
-
-  // 4) Present fields must match their declared type.
-  for (const [name, fspec] of Object.entries(spec.fields)) {
-    if (rec[name] === undefined) continue
-    if (!matchesType(fspec, rec[name])) {
-      return {
-        code: 'INVALID_OP', reason: 'wrong_type', family, opKind: kind, field: name,
-        message: `Field "${name}" of ${family} op "${kind}" must be ${typeName(fspec)}, got ${JSON.stringify(rec[name])}.`,
-        validFields,
-      }
-    }
-  }
-
-  return null
-}
-
-/** Machine-readable op menu for a family — { opKind: [fieldName, …] } — the
- *  basis for tool-discovery output. Optional fields are marked with a trailing
- *  `?`; the op's `kind` is implicit and omitted. */
-export function opMenu(family: OpFamily): Record<string, string[]> {
-  const out: Record<string, string[]> = {}
-  for (const [kind, spec] of Object.entries(SCHEMAS[family])) {
-    out[kind] = Object.entries(spec.fields).map(([n, f]) => (f.required ? n : `${n}?`))
-  }
-  return out
-}
-
-/** One field of an op, as a model needs it to fill the op correctly: the name,
- *  whether it is required, and a human type that spells out enum values inline
- *  (e.g. `one of "inheritance", "composition", …`). */
-export interface OpFieldDoc { name: string; required: boolean; type: string; note?: string }
-
-/** Full field shapes for every op of a family — the thing a model must know to
- *  author a correct op without guessing (which the prescriptive INVALID_OP error
- *  only teaches AFTER a wrong guess). Surfaced in `am capabilities --json` and
- *  the declarative MCP tool descriptions so field names, required-ness, and enum
- *  vocabularies are discoverable up front. */
-export function describeOps(family: OpFamily): Record<string, OpFieldDoc[]> {
-  const out: Record<string, OpFieldDoc[]> = {}
-  for (const [kind, spec] of Object.entries(SCHEMAS[family])) {
-    out[kind] = Object.entries(spec.fields).map(([name, f]) => ({ name, required: f.required, type: typeName(f), ...(f.note !== undefined ? { note: f.note } : {}) }))
-  }
-  return out
-}
-
-/** Compact one-line signatures for a family's ops — `add_relation(from, to,
- *  relKind, label?)` — for embedding in a tool description. Optional fields carry
- *  a trailing `?`; enum values are left to `describeOps`/the error to keep the
- *  menu short. */
-export function opSignatures(family: OpFamily): string[] {
-  const menu = opMenu(family)
-  return Object.entries(menu).map(([kind, fields]) => `${kind}(${fields.join(', ')})`)
-}

package/src/agent/parse.ts

@@ -1,223 +0,0 @@
-// ============================================================================
-// parseMermaid: source → ValidDiagram (multi-error).
-//
-// v4 sequence fidelity: parseSequenceBody returns null if it encounters ANY
-// non-blank, non-comment line it doesn't fully understand. parse then falls
-// back to an opaque body (lossless round-trip via canonicalSource) rather
-// than silently dropping the unrecognized construct.
-// ============================================================================
-
-import { normalizeMermaidSource, detectLooseDiagramTypeFromFirstLine } from '../mermaid-source.ts'
-import { getFamily } from './families.ts'
-import './families-builtin.ts'  // registers built-in family parse/serialize/mutate hooks
-import { serializeMermaid } from './serialize.ts'
-import type {
-  ValidDiagram, ParseError, Result, DiagramKind, ValidDiagramMeta,
-  SourceMap, InitDirective, SourceComment,
-} from './types.ts'
-import { ok, err } from './types.ts'
-
-// Re-exports for callers/tests that used the previous in-tree parser homes.
-export { parseSequenceBody } from './sequence-body.ts'
-export { parseTimelineBody } from './timeline-body.ts'
-
-const FRONTMATTER_REGEX = /^?\s*---\s*\r?\n([\s\S]*?)\r?\n\s*---\s*(?:\r?\n|$)/
-const INIT_DIRECTIVE_REGEX = /^\s*%%\{\s*(?:init|initialize)\s*:\s*([\s\S]*?)\}\s*%%\s*(?:\r?\n|$)?/gm
-const COMMENT_LINE_REGEX = /^\s*%%(?!\{)\s*(.*)$/
-const ACC_TITLE_REGEX = /^\s*accTitle\s*:\s*(.+)$/i
-const ACC_DESCR_INLINE_REGEX = /^\s*accDescr\s*:\s*(.+)$/i
-const ACC_DESCR_BLOCK_START = /^\s*accDescr\s*\{\s*$/i
-
-export function parseMermaid(source: string): Result<ValidDiagram, ParseError[]> {
-  const errors: ParseError[] = []
-  // Normalize once and reuse its frontmatter in extractMeta, rather than
-  // re-running the full preprocess a second time just for frontmatter.
-  const normalized = normalizeMermaidSource(source)
-  const meta = extractMeta(source, normalized.frontmatter)
-  const canonicalSource = normalized.text
-  // For opaque bodies, preserve original indentation/blank lines so the
-  // serializer can re-emit the untouched body. canonicalSource at the
-  // ValidDiagram level remains the normalized (line-trimmed) form for
-  // back-compat with the existing flowchart/legacy paths.
-  const opaqueSource = normalized.body
-
-  if (normalized.lines.length === 0) {
-    errors.push({ code: 'EMPTY', message: 'Empty diagram' })
-    return err(errors)
-  }
-
-  const header = normalized.lines[0]!.toLowerCase()
-  const kind = detectKind(header)
-  if (!kind) {
-    errors.push({ code: 'UNKNOWN_HEADER', message: `Unrecognized header: "${normalized.lines[0]}"`, line: 1 })
-    return err(errors)
-  }
-
-  // BUILD-3: every family dispatches through its FamilyPlugin.parse hook —
-  // structured-or-opaque for the narrow families, error semantics for
-  // flowchart/state. Families without a hook stay source-level.
-  const plugin = getFamily(kind)
-  if (plugin?.parse) {
-    const parsed = plugin.parse(normalized.lines, opaqueSource, meta, canonicalSource)
-    if (!parsed.ok) {
-      errors.push(...parsed.error)
-      return err(errors)
-    }
-    const sourceMap = plugin.buildSourceMap?.(parsed.value, canonicalSource) ?? emptySourceMap()
-    const diagram: ValidDiagram = { kind, meta, body: parsed.value, source: sourceMap, canonicalSource }
-    markDroppedComments(diagram, normalized.body)
-    return ok(diagram)
-  }
-
-  return ok<ValidDiagram>({
-    kind, meta, body: { kind: 'opaque', family: kind, source: opaqueSource }, source: emptySourceMap(), canonicalSource,
-  })
-}
-
-/**
- * 2C comment policy: structured bodies serialize to canonical source, which
- * does not model `%%` comment lines. Rather than dropping them *silently*,
- * diff the parsed comments against what actually survives serialization
- * (wrapper comments ride along verbatim via meta.wrapperSource; sequence
- * opaque segments may preserve in-body comments) and record the casualties so
- * verify can surface the Tier 3 COMMENT_DROPPED lint. Opaque bodies preserve
- * everything and never reach here.
- */
-function markDroppedComments(diagram: ValidDiagram, sourceBody: string): void {
-  const comments = diagram.meta.comments
-  if (diagram.body.kind === 'opaque' || comments.length === 0) return
-
-  const sourceLines = sourceBody.split(/\r?\n/).map(line => line.trim())
-  const serializedLines = serializeMermaid(diagram).split(/\r?\n/).map(line => line.trim())
-  const keptSourceLines = longestCommonSubsequenceIndices(sourceLines, serializedLines)
-  const keptCommentLines = new Set<number>()
-  for (const sourceIndex of keptSourceLines) {
-    if (COMMENT_LINE_REGEX.test(sourceLines[sourceIndex]!)) keptCommentLines.add(sourceIndex + 1)
-  }
-
-  const dropped: SourceComment[] = comments.filter(comment => !keptCommentLines.has(comment.line))
-  if (dropped.length > 0) diagram.meta.droppedComments = dropped
-}
-
-function longestCommonSubsequenceIndices(a: string[], b: string[]): number[] {
-  const dp: number[][] = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0))
-  for (let i = a.length - 1; i >= 0; i--) {
-    for (let j = b.length - 1; j >= 0; j--) {
-      dp[i]![j] = a[i] === b[j]
-        ? dp[i + 1]![j + 1]! + 1
-        : Math.max(dp[i + 1]![j]!, dp[i]![j + 1]!)
-    }
-  }
-  const indices: number[] = []
-  let i = 0
-  let j = 0
-  while (i < a.length && j < b.length) {
-    if (a[i] === b[j]) {
-      indices.push(i)
-      i++
-      j++
-    } else if (dp[i + 1]![j]! >= dp[i]![j + 1]!) {
-      i++
-    } else {
-      j++
-    }
-  }
-  return indices
-}
-
-// ---- Family detection ----------------------------------------------------
-// Use the shared renderer detector for routed families; the agent layer only
-// splits state diagrams out from the renderer's flowchart route because state
-// and flowchart share the same legacy graph body but remain distinct families.
-
-function detectKind(header: string): DiagramKind | null {
-  if (/^statediagram(?:-v2)?\s*$/i.test(header)) return 'state'
-  const routed = detectLooseDiagramTypeFromFirstLine(header)
-  if (!routed) return null
-  return routed
-}
-
-// ---- Meta extraction -----------------------------------------------------
-
-function extractMeta(rawSource: string, frontmatter?: Record<string, unknown>): ValidDiagramMeta {
-  const meta: ValidDiagramMeta = { initDirectives: [], comments: [], accessibility: {} }
-
-  const wrapperSource = extractWrapperSource(rawSource)
-  if (wrapperSource !== undefined) meta.wrapperSource = wrapperSource
-
-  if (frontmatter && Object.keys(frontmatter).length > 0) {
-    meta.frontmatter = frontmatter as ValidDiagramMeta['frontmatter']
-  }
-
-  const directiveRegex = new RegExp(INIT_DIRECTIVE_REGEX.source, 'gm')
-  let m: RegExpExecArray | null
-  while ((m = directiveRegex.exec(rawSource)) !== null) {
-    meta.initDirectives.push({ raw: m[0], parsed: tryParseInitObject((m[1] ?? '').trim()) as InitDirective['parsed'] })
-  }
-
-  const stripped = rawSource
-    .replace(FRONTMATTER_REGEX, '')
-    .replace(new RegExp(INIT_DIRECTIVE_REGEX.source, 'gm'), '')
-  const lines = stripped.split(/\r?\n/)
-  let inAccDescr = false
-  let buf: string[] = []
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i]!
-    if (inAccDescr) {
-      if (/^\s*\}\s*$/.test(line)) { meta.accessibility.descr = buf.join('\n').trim(); inAccDescr = false; buf = [] }
-      else buf.push(line)
-      continue
-    }
-    if (ACC_DESCR_BLOCK_START.test(line)) { inAccDescr = true; continue }
-    const at = line.match(ACC_TITLE_REGEX)
-    if (at) { meta.accessibility.title = at[1]!.trim(); continue }
-    const ad = line.match(ACC_DESCR_INLINE_REGEX)
-    if (ad) { meta.accessibility.descr = ad[1]!.trim(); continue }
-    const cm = line.match(COMMENT_LINE_REGEX)
-    if (cm) meta.comments.push({ text: cm[1]!, line: i + 1 })
-  }
-
-  return meta
-}
-
-/**
- * The leading source wrapper, byte-verbatim: an optional frontmatter block
- * followed by any run of blank lines, `%%` comments, and `%%{init}%%`
- * directives, up to (excluding) the diagram header line. This is what
- * serializeMermaid re-emits untouched by default (1C wrapper policy).
- */
-function extractWrapperSource(rawSource: string): string | undefined {
-  let pos = 0
-  const fm = rawSource.match(FRONTMATTER_REGEX)
-  if (fm) pos = fm[0].length
-  const directiveAtStart = new RegExp(INIT_DIRECTIVE_REGEX.source)
-  for (;;) {
-    const rest = rawSource.slice(pos)
-    if (rest.length === 0) break
-    const dm = rest.match(directiveAtStart)
-    if (dm && dm.index === 0 && dm[0].length > 0) { pos += dm[0].length; continue }
-    const lineEnd = rest.indexOf('\n')
-    const line = lineEnd === -1 ? rest : rest.slice(0, lineEnd)
-    if (/^\s*$/.test(line) || COMMENT_LINE_REGEX.test(line)) {
-      pos += lineEnd === -1 ? rest.length : lineEnd + 1
-      continue
-    }
-    break
-  }
-  return pos > 0 ? rawSource.slice(0, pos) : undefined
-}
-
-function tryParseInitObject(inner: string): Record<string, unknown> {
-  try { return JSON.parse(inner) as Record<string, unknown> }
-  catch {
-    try {
-      const quoted = inner.replace(/([{,]\s*)([A-Za-z_$][\w$]*)\s*:/g, '$1"$2":')
-      return JSON.parse(quoted) as Record<string, unknown>
-    } catch { return {} }
-  }
-}
-
-function emptySourceMap(): SourceMap {
-  return { nodes: new Map(), edges: new Map(), groups: new Map(), labels: new Map() }
-}
-