# What Information Does the Fidelity Ledger Report for Imported Diagrams?

> Discover what the Fidelity ledger reports for imported diagrams, including merged, collapsed, and dropped elements. Understand source versus rendered node counts.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-08-14

---

**The fidelity ledger reports exactly what was merged, collapsed, or dropped during diagram import, plus counts of source versus rendered nodes.**

When you import a diagram using the **Mermaid** or **draw.io** import commands in the `cathrynlavery/diagram-design` repository, the system generates a mandatory fidelity ledger that provides complete transparency into every transformation applied. This ledger is required for any import that reduces original content—including all `balanced` and `simplified` runs and most `faithful` runs—to ensure users understand precisely how their source diagram changed before rendering.

## Fidelity Ledger Structure and Required Fields

The ledger specification is defined in **[`skills/diagram-design/references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md)** §5. Every ledger contains five core fields that describe the transformation from source to rendered output:

| Field | Purpose |
|-------|---------|
| **Detail** | High‑level summary: selected detail level (e.g., `balanced`), source node count, and rendered node count |
| **Merged** | Elements combined into single nodes (e.g., identical workers collapsed into "Worker ×6") |
| **Collapsed** | Groups reduced to aggregate nodes (e.g., "Observability" zone with Grafana, Loki, Tempo → one node) |
| **Dropped** | Items completely removed (e.g., sticky notes, cross‑cutting CI pipelines) |
| **Kept in full** | Untouched portions, typically the main request path |

### Example Fidelity Ledger Output

From the official specification, a complete ledger looks like this:

```text
Detail: balanced · 18 source nodes → 9 drawn
Merged:  worker-01..06 → "Ingest Worker ×6"
Collapsed: "Observability" group (Grafana, Loki, Tempo) → one node
Dropped: 2 sticky notes, CI pipeline (cross‑cutting)
Kept in full: the request path (Client → Gateway → Orders → Postgres)

```

The ledger emits **after the file path** of the generated diagram, as specified in [`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/output-spec.md) lines 55–60.

## How the Fidelity Ledger Appears in CLI Output

After running an import command, you'll see the ledger immediately following the success indicator:

```text
✅ diagram.html
Detail: balanced · 12 source nodes → 6 drawn
Merged:  api‑01..04 → "API Server ×4"
Collapsed: "Cache" group (Redis, Memcached) → one node
Dropped: 1 annotation, 1 legacy endpoint
Kept in full: Client → API Gateway → Service A → Service B

```

This format matches the shell implementation in the import command scripts. The **[`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)** documentation explicitly mandate this reporting: developers must "report the fidelity ledger (what was merged, collapsed, or dropped)" for every qualifying import.

## Programmatic Access to Fidelity Ledger Data

Verification scripts and downstream tools consume the ledger as structured JSON. The validation scripts **[`verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-mermaid-import.py)** (line 545) and **[`verify-drawio-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-drawio-import.py)** (line 292) check for the presence of a `fidelity_ledger` key in command output:

```python

# Result structure from import commands

result = {
    "path": "diagram.html",
    "fidelity_ledger": {
        "detail": "balanced · 12 source nodes → 6 drawn",
        "merged": ["api‑01..04 → \"API Server ×4\""],
        "collapsed": ["Cache group (Redis, Memcached) → one node"],
        "dropped": ["1 annotation", "1 legacy endpoint"],
        "kept": ["Client → API Gateway → Service A → Service B"]
    }
}

# Standard rendering for CLI display

print("\n".join(result["fidelity_ledger"].values()))

```

## Internal Implementation in Import Commands

The ledger generation follows a consistent template across import implementations. From the `import-mermaid` command source:

```bash
echo "✅ $OUTPUT_PATH"
cat <<EOF
Detail: $DETAIL
Merged: $MERGED
Collapsed: $COLLAPSED
Dropped: $DROPPED
Kept in full: $KEPT
EOF

```

Variables are populated during the transformation pipeline based on actual modifications made to reach the target detail level.

## Source Files Defining Fidelity Ledger Behavior

| File | Role |
|------|------|
| [`skills/diagram-design/references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md) | Complete specification §5 |
| [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md) | CLI mandate for ledger reporting |
| [`commands/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md) | CLI mandate for ledger reporting |
| [`scripts/verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-mermaid-import.py) | JSON validation (line 545) |
| [`scripts/verify-drawio-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-drawio-import.py) | JSON validation (line 292) |

## Summary

- The **fidelity ledger** is mandatory for any diagram import that reduces source content
- It reports five categories: **Detail** (summary counts), **Merged**, **Collapsed**, **Dropped**, and **Kept in full**
- Output appears immediately after the generated file path in CLI results
- Verification scripts validate JSON structure with a `fidelity_ledger` key
- Specification lives in [`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/output-spec.md) §5 with implementation across `import-mermaid` and `import-drawio` commands

## Frequently Asked Questions

### When is the fidelity ledger generated?

The fidelity ledger generates for every import using `balanced` or `simplified` detail levels, plus most `faithful` runs—any transformation that reduces original diagram content. According to the [`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/output-spec.md) specification, the system produces this ledger to maintain transparency when source elements don't survive intact to the rendered output.

### What's the difference between "merged" and "collapsed" in the ledger?

**Merged** indicates separate elements combined into a single representative node—typically identical instances like "worker-01..06 → Worker ×6". **Collapsed** indicates logical groups reduced to aggregates—like an "Observability" zone containing multiple tools becoming one node. Both reduce node count but preserve different semantic relationships.

### How can I verify a fidelity ledger was produced correctly?

Run the verification scripts: **[`verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-mermaid-import.py)** or **[`verify-drawio-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-drawio-import.py)**. These scripts parse the JSON output and confirm the `fidelity_ledger` key exists with valid content. For manual verification, check that CLI output shows all five fields (Detail, Merged, Collapsed, Dropped, Kept in full) following the success checkmark and file path.

### Where is the fidelity ledger specification documented?

The canonical specification appears in **[`skills/diagram-design/references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md)** starting at line 51, section 5. This document defines field semantics, output ordering, and formatting requirements. The specification is referenced by both import command documentation files and implemented directly in the verification test suite.