# How the Fidelity Ledger Works for Imported Diagrams in diagram-design

> Discover how the fidelity ledger in diagram-design tracks all changes during Mermaid or Draw.io imports. Understand your imported diagram's complete audit trail for better design management.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: internals
- Published: 2026-08-18

---

**The fidelity ledger is an automatically generated audit trail that records every change, merge, collapse, or drop that occurs when diagram-design imports a diagram from Mermaid or Draw.io formats.**

When importing diagrams from external formats into **diagram-design**, the tool creates a **fidelity ledger** to ensure complete transparency during the conversion process. This ledger serves as a comprehensive record of how the source diagram was transformed, modified, or simplified during import, preventing any silent data loss.

## What Is the Fidelity Ledger?

The **fidelity ledger** is a structured report generated at the conclusion of every import operation. According to the repository's [`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/output-spec.md) file, anything cut during steps 2–6 of the import process must be recorded in this ledger (§5). The ledger captures the delta between the original source file and the final rendered output, ensuring users can audit exactly how their diagram was processed.

## When the Fidelity Ledger Is Generated

The fidelity ledger is created as the final step in both supported import workflows.

### Mermaid Import Flow

When importing Mermaid diagrams via the process documented in [`import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-mermaid.md), step 4 explicitly calls to "Report the fidelity ledger" after processing is complete. This step records the source count, drawn count, and every merge, collapse, or drop operation performed during the import [8†L75-L78].

### Draw.io Import Flow

Similarly, the [`import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-drawio.md) workflow outlines the same reporting requirement in step 4, referencing [`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/output-spec.md) §5 for the ledger specification [8†L115-L117]. Both import paths converge on the same fidelity reporting mechanism to maintain consistency across formats.

## What the Fidelity Ledger Contains

As defined in [`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/output-spec.md) §5, the fidelity ledger tracks four critical data points:

- **Source count**: The total number of elements read from the original diagram file.
- **Drawn count**: The number of elements actually rendered in the final output.
- **Merges**: Records of elements that were combined into single entities during import.
- **Collapses**: Groups of elements that were simplified or condensed.
- **Drops**: Elements that were silently discarded, such as unconnected legend nodes.

This structured accounting ensures users can verify exactly what happened to every component of their source diagram.

## Why the Fidelity Ledger Matters

The fidelity ledger provides essential transparency for diagram validation workflows. When components are silently dropped—such as unconnected legend nodes that do not fit the target format—the ledger preserves a record of these omissions [8†L110-L127]. This prevents hidden data loss and allows users to compare the ledger against their source files to determine if manual adjustments are necessary.

Additionally, the [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) file mandates the fidelity ledger as a required reporting step (§11), embedding auditability as a core requirement of the diagram-design import system.

## Example Fidelity Ledger Output

After importing a diagram, the command-line interface prints the fidelity ledger as a concise JSON-like report. Below is a representative example of the output structure:

```json
{
  "sourceCount": 42,
  "drawnCount": 38,
  "merged": [
    {"from": "nodeA", "into": "nodeB"},
    {"from": "nodeC", "into": "nodeD"}
  ],
  "collapsed": [
    {"group": "subgraph1", "elements": ["nodeE","nodeF"]}
  ],
  "dropped": [
    {"type": "legend", "id": "legend-1"},
    {"type": "note", "id": "note-42"}
  ]
}

```

The report appears after the standard CLI output showing file paths, sizes, and the four "dials" (paper, ink, accent, font), allowing immediate review of conversion fidelity.

## Summary

- **The fidelity ledger** automatically records all transformations applied during diagram import in diagram-design.
- **Source files** [`import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-mermaid.md) and [`import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-drawio.md) specify ledger reporting as the final step (step 4) in their respective workflows.
- **Content specifications** in [`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/output-spec.md) §5 mandate tracking source counts, drawn counts, merges, collapses, and drops.
- **Transparency** is guaranteed by recording even silently dropped elements like unconnected legend nodes.
- **CLI output** presents the ledger as structured JSON immediately after import completion for user verification.

## Frequently Asked Questions

### What triggers the creation of a fidelity ledger in diagram-design?

The fidelity ledger is generated automatically at the conclusion of any import operation, whether importing from Mermaid format via [`import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-mermaid.md) or Draw.io format via [`import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-drawio.md). According to the repository's [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) §11, reporting the fidelity ledger is a mandatory final step in the import workflow.

### Does the fidelity ledger show which specific elements were removed?

Yes, the fidelity ledger explicitly lists all dropped elements with their types and identifiers. For example, if unconnected legend nodes or unsupported note elements are removed during import, the ledger records these as "dropped" entries with specific IDs, ensuring you know exactly what content did not survive the conversion process.

### How is the fidelity ledger formatted when displayed to users?

The fidelity ledger is rendered as a concise JSON-like structure in the command-line output. It includes numeric counts for source and drawn elements, plus arrays detailing any merges, collapses, or drops. This format appears immediately after the import summary showing file paths and the four design dials (paper, ink, accent, font).

### Where can I find the formal specification for fidelity ledger contents?

The complete specification for fidelity ledger structure and requirements is documented in [`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/output-spec.md) §5. This file defines what information must be captured when elements are modified during steps 2–6 of the import process, and it is referenced by both [`import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-mermaid.md) and [`import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-drawio.md) as the authoritative source for ledger formatting.