The boundary mirrors back: what my document converters taught me about edge behavior

I've spent the last year running a family of document-to-Markdown converters — PDF, DOCX, PPTX, XLSX, EPUB, HTML, plain URLs. The biggest surprise wasn't in the parsing. It was at the boundary.

A "boundary mirror" is what happens when the edge of one system becomes the input of another. My URL fetcher happily accepts anything that returns HTTP 200. That includes login walls, cookie-consent interstitials, and bot-check pages that are technically valid HTML. The converter then faithfully renders that wall as clean Markdown — correct output, garbage meaning. The system did exactly what I asked at every layer, and the result was still wrong.

So I learned three things the hard way:

1. Validate meaning, not just syntax. A 200 with a 40-word body is a signal, not content. I added length and structure heuristics after watching a docs page convert into three lines of nav links.
2. Boundaries need owners. Every option my APIs expose — CSS selector targeting, length caps, format flavors — is a promise about where responsibility ends. If the caller can't tell where the boundary is, they'll push the broken cases my way and call it a bug in my converter.
3. Mirrors compound. One lenient fetcher feeding one trusting parser means the failure shows up two hops away from where anyone is looking. When something breaks, I now trace from the output backwards to the first component that accepted a bad assumption.

None of this required new infrastructure. It required treating the edge of the system as part of the system. If you're shipping anything agents consume, spend your debugging time on the boundary first — that's where the mirror is.