I almost shipped a parser that couldn't read a single real file

I needed my tool to accept trace files in a standard format (OTLP / OpenInference) so any framework could feed it. I read the spec, pictured the JSON structure, and was about to write the parser against that mental model. Then I made myself do one annoying thing first: dump the actual output and compare.
Good thing I did. Almost every assumption was wrong.

I'd assumed uppercase-hex trace IDs, UnixNano string timestamps, and a nested resourceSpans structure — straight from the spec. The real SDK output had 0x-prefixed IDs, ISO datetimes, and a flat array. The "standard OTLP-JSON" I'd designed against turned out to be a spec example that no tool actually emits. If I'd written the parser against my mental model, it would have passed my own hand-made fixtures and then failed on every real file. The generalization would have been fake.

The second dump taught me something bigger. I'd assumed users have trace files sitting on disk. They mostly don't — OpenInference's own examples ship spans to a dashboard over HTTP. So the premise of "send me your trace file" was itself off. The most valuable output of this whole task wasn't the parser — it was a 3-line snippet that lets a user produce a file in the first place. A parser with no "here's how to make the file" guide is a tool nobody can use.

So the scope quietly shifted: support the one format real SDK output actually uses, reject the others with a clear "convert it like this" error instead of failing silently, and ship the copy-paste snippet — then verify that snippet actually runs end to end, not just the parser's unit tests.
The discipline here is the same one I keep relearning: a result that's correct against data you imagined tells you nothing about data the world produces. Verify the real shape before you build for it.

(Caveat kept explicit: one export format supported today; dashboard/proto exports get a conversion message, not silence. The detection engine and its known limits are unchanged — this was about the door, not the detector.)
Code: github.com/JEONSEWON/Clew-by-Custos