# Deterministic Diagram Pipeline

Task: GH-462-DETERMINISTIC-DIAGRAM-PIPELINE
Status: first implementation slice

## Scope

This slice introduces a local TypeScript pipeline for source-free semantic
diagrams:

1. `DiagramModel` captures semantic intent: nodes, groups, connectors, labels,
   and Iconify icon references.
2. `layoutDiagram()` produces deterministic geometry from model order and group
   membership.
3. `renderDiagramSvg()` emits a minimal SVG artifact from the model and layout.
4. `validateDiagramArtifact()` checks text fit, canvas/container containment,
   connector endpoints, connector-node overlaps, connector labels covering
   other lines, and unnecessary bends where the path is already straight.
5. `generateDeterministicDiagram()` ties model, layout, rendering, and
   validation together for a single pass. It first validates the runtime
   payload against the structured diagram schema and fails with field-level
   errors before any layout or SVG rendering occurs.
6. `runDeterministicDiagramPipeline()` adds bounded iteration. It renders the
   first pass, applies deterministic text-fit repair when possible, regenerates
   the artifact, and retains only the final artifact unless
   `retainIterations=true` is requested for debug evidence.

The current slice is intentionally API-level. CLI routing is still pending so
this does not widen `command-routes*` or `tool-commands` ownership in the same
change. Consumers can call `runDeterministicDiagramPipeline()` directly to get a
stable final SVG plus optional retained iteration artifacts.

## Structured Output Contracts

Agents that generate deterministic artifacts must return structured JSON-like
payloads, not prose instructions for renderers to interpret.

Diagram payloads must satisfy `DiagramModel`:

- `id`, `title`, and `direction` are required.
- `direction` must be `right` or `down`.
- `nodes` must be a non-empty array. Each node needs `id`, `kind`, and
  `text.label`; `kind` must be one of `actor`, `system`, `service`, `database`,
  `queue`, or `boundary`.
- `connectors` must be an array. Each connector needs `id`, `from`, `to`, and
  `kind`; `from` and `to` must reference known node ids; `kind` must be one of
  `sync`, `async`, `data`, or `control`.
- Optional `groups` define labeled containers. Unused groups are allowed so
  generated drafts can keep future grouping intent, but duplicate group ids are
  rejected.

Report payloads use `ReportDocument` through `renderReportMarkdown()`:

- `id`, `title`, `summary`, and a non-empty `sections` array are required.
- Section `kind` must be one of `summary`, `findings`, `decisions`, `risks`,
  `evidence`, or `nextSteps`.
- Section items require `id` and `text`; optional severity must be one of
  `info`, `low`, `medium`, `high`, or `critical`.

Validation errors include JSON-path-like locations, for example
`$.connectors[0].to: references unknown node "api-gateway"`. Agent prompts
should pass those messages back to the generating role unchanged so the payload
can be corrected without guessing which field failed.

## Icon Policy

Diagram nodes reference icons by semantic purpose and Iconify id. Rendering
resolves the SVG body from an injected cache. Tests use the in-memory cache, so
the pipeline does not require network access to prove deterministic rendering.

Future slices can add a controlled cache warmer for Iconify sets. That command
should pin source metadata, record cache evidence, and fail closed when icons are
missing instead of fetching during tests.

## Target Guidance

- Use Mermaid for markdown-native semantic diagrams and fast syntax validation.
- Use this deterministic SVG pipeline when a generated diagram needs stable
  geometry, validation findings, and repeatable rendering without relying on LLM
  absolute coordinates.
- Use draw.io XML or Lucid when the acceptance target is editable,
  pixel-sensitive recreation, manual stakeholder editing, or exact connector
  anchors beyond this pipeline's current router.
- Use LLM prompt generation for semantic drafting, copy, and model suggestions;
  do not treat prompt-selected coordinates as the source of truth.

## Artifact Retention

Default generation keeps the final SVG artifact and reports how many internal
iterations were discarded. Debug generation can request `retainIterations=true`
to keep each intermediate artifact and its findings. This keeps normal
deliverables clean while allowing QA or architecture review to inspect how the
pipeline corrected text fit and regenerated the diagram.

## Known Gaps

- Connector routing is simple orthogonal routing, not a full obstacle-avoidance
  solver.
- Text measurement is deterministic approximation based on character and line
  counts, not browser font metrics.
- Iteration artifact retention is available through API, but not exposed through
  CLI yet.