JSON Schema

Every transform call in CoreModels returns three things, and the third one is the reason we built it this way. You get the converted schema. You get the plan that produced it. And you get a ledger of everything the conversion could not carry across exactly - written in English, with a path pointing at the construct it happened to.

A couple of format keys in the CoreModels transform surface are honest about being one-way. `odm` decodes only, because entity documentation is authored, not generated. `synapse` encodes only, and says so out loud when you try the other direction: *"'synapse' is encode-only: a Synapse schema is plain draft-07 JSON Schema - decode it with the 'jsonschema' format."*

An agent working on your repository will find a `.schema.json` file long before it finds your conversion documentation. What happens next depends entirely on the tools it can reach. Without one, it writes a converter, or worse, writes the target schema from scratch and presents its guesses with the same confidence as facts.

A generator you cannot re-run and get identical output from is not a build step. It is a rumor with a timestamp. That is the practical objection to putting schema conversion in a pipeline: if today's run can differ from yesterday's for reasons nobody logged, then the generated Avro, the generated DDL, and the generated proto files are all provisional, and reviewing them is theater.

Every format coder in CoreModels has to answer the same awkward question: what do you do with the parts of a document you do not model? There are three bad answers - drop them, guess at them, or refuse the document - and one good one, which is to carry them untouched and be explicit about the handful of cases where carrying them is not enough.