Schema-Driven Output

## Generated source is an output, not an input When the message shapes of a device-telemetry pipeline are written down once, in an external **description**, and a generator turns that description into source for every consumer, the emitted files change role. They are no longer source in the sense a hand-written file is source: they are **build output that happens to be readable**. The description is the input; the files are what the build makes of it, before compilation, on the way to a binary. Every rule about editing them follows from that single fact. A hand edit inside a generated file is an edit to an output. Nothing in the pipeline reads it back. Any run that writes the file composes it from the description alone, and whatever was typed there is gone. There is no three-way merge, and a comment asking the generator to preserve a region is only honoured if that generator was built to parse its own previous output and reason about which parts a human meant to keep — a much harder program than the one most teams have. ## Why the loss is quiet The failure mode is not that the edit is rejected. It is that the edit **works**, until it silently does not: - The edit compiles and passes tests locally, so nothing at the moment of the change objects. - An incremental generator may skip a description that has not changed, so the file survives for days and the habit spreads to other files. - When the file is finally rewritten, the diff is full of churn — reordered members, regenerated headers — and the one deletion hides inside it. - The tests that fail are the tests for the hand-added behaviour, which point at the generator rather than at the habit that caused it. So the answer an interviewer wants is not "do not edit generated code" as a slogan. It is a **place for the addition to live** that survives regeneration by construction. ## The extension seam A generator that expects hand-written additions leaves a seam. Three shapes cover nearly everything: 1. **Extension by subtype.** The generator emits a type meant to be extended; a hand-owned type extends it and adds members. The generated file is rewritten freely; the hand-owned file is never touched. 2. **A hook the generated code calls.** The generated code invokes a named operation at a defined point, and the implementation of that operation is hand-written and discovered by declaration or registration. This is the only seam that lets hand-written code influence generated *behaviour* rather than merely adding beside it. 3. **Composition.** The generated type stays a plain data carrier; a hand-written wrapper holds the extra behaviour and delegates the generated parts. | Seam | What the generator emits | What the human writes | Main cost | |---|---|---|---| | Subtype | An extensible type | A type extending it | Hand code is coupled to the generated shape | | Hook | A call to a named operation | The implementation | The generator must have anticipated the point | | Wrapper | A plain carrier | A wrapper that delegates | Two types to keep in step in every consumer | ## When the addition belongs in the description instead The seam is for what is genuinely local to one consumer. Ask who needs the addition: - **Several consumers need the same thing** — that is a missing feature of the description. Add it once and every output gets it; otherwise the same helper is hand-written three times and the single source of truth quietly becomes four. - **Exactly one consumer needs it** — the seam is right. Widening the description for one consumer turns it into a union of everybody's special cases, and each one is generated into outputs that do not want it. - **The addition must change generated behaviour, not add to it** — the seam has to be an inversion point, where generated code delegates the decision to the hook. Without one you are back to editing output, and the only honest options are to extend the description or to fork the generator. ## The limits worth naming A seam is a design commitment made by whoever wrote the generator, and a generator with no seam forces every local need through the description. Extension by subtype couples hand-written code to the generated shape, so a description change can break the hand-written side at build time — which is usually the outcome you want, because it is loud and early rather than a silent behaviour change. And none of this removes the need for regeneration to be part of the ordinary build: a seam only helps if the generated file is genuinely rewritten often enough that an illegitimate edit dies quickly rather than months later.