What Information Does the Fidelity Ledger Report for Imported Diagrams?

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 §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:

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 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:

✅ 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 and 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 (line 545) and verify-drawio-import.py (line 292) check for the presence of a fidelity_ledger key in command output:

# 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:

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	Complete specification §5
commands/import-mermaid.md	CLI mandate for ledger reporting
commands/import-drawio.md	CLI mandate for ledger reporting
scripts/verify-mermaid-import.py	JSON validation (line 545)
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 §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 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 or 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}