code-conventionslisted

# Code Conventions A set of conventions distilled from a large, heavily-gated TypeScript codebase. Each one prevents a recurring class of mistake. They are not style preferences; they are rules that keep behavior **explicit**, **reversible**, and **checked at the right boundary**. Apply the ones that fit your codebase's shape; most assume a typed language and module/package boundaries. **The defining constraint:** every convention makes one thing *unambiguous* — where a side effect can be undone, where a decision is made, where a value is validated, and what a swallow actually swallowed. ## Reversible side effects Registrations and contributions are effects, and every effect has a disposer. When a plugin, module, or service contributes something to a shared context — a listener, a schema, a provider, a slot — the registration path returns the function that undoes it. This makes reload and teardown unwind predictably. If a contribution cannot be undone, that is a design gap to name, not something to hide. ## Switch on discriminant tags When a union is closed, exhaustiveness is checked by ending the switch in `assertNever`. When the union is deliberately open to extension, fall through a **documented default** rather than a bare `default` that silently does nothing. The reader should always be able to tell "every case handled and proven" from "unknown case falls through on purpose." ## Explicit over implicit at boundaries Defaulting and choice-making happen at one named