updated documentation to have mermaid diagrams; updated AGENTS.md to note that all future diagrams should be mermaid diagrams first with text-based diagrams as fallback where not applicable

2026-09-06 14:28:48 -06:00
parent 8c74efcedb
commit 3803787fe8
9 changed files with 133 additions and 41 deletions
@@ -139,7 +139,23 @@ side / flatc* — see the "cross-language fixture" section below.

 ### 4. Cross-language conformance suite (THE key integration test)

-This is the test that actually catches incompatibility. Design:
+This is the test that actually catches incompatibility. Pipeline:
+
+```mermaid
+flowchart LR
+    S["schema/catalog.fbs"]
+    J["testdata/catalog_sample.json"]
+    S --> F["flatc --binary"]
+    J --> F
+    F --> BIN["committed .bin fixtures<br/>repo-checked-in"]
+    BIN --> OT["Odin tests<br/>assert identical values"]
+    BIN --> RT["Rust tests<br/>assert expected values"]
+    RT -. "deterministic builder" .-> PAR["byte-for-byte parity"]
+    OT -. "reads it" .-> PAR
+    PAR -. "catch drift" .-> F
+```
+
+Design:

 1. **Static fixtures, committed to the repo** (`testdata/*.bin`):
   - Built once by `flatc --binary <schema>.fbs <data>.json` (deterministic,