TypeScript's narrowing through const-aliased conditions, constant-key element accesses and inferred predicates can silently disappear when someone changes a `const` to a `let` or adds a second `return` to a helper. Across a large codebase, how do you decide where to rely on inferred narrowing and where to make the narrow type explicit?

## What these features have in common Control-flow analysis of aliased conditions, narrowing through constant-key element accesses, and inferred type predicates are three separate conveniences, but they share one property that matters for codebase strategy: **the guarantee is derived, not declared.** Nothing in a signature or a type annotation records that `isReady` implies `user` is loaded, or that this helper refines its argument. The compiler works it out from the shape of the code each time it checks. Derived guarantees have a specific failure mode. They break on edits that look innocuous — `const` to `let`, adding an early return, adding a `: boolean` annotation for "clarity", introducing an assignment to a parameter. And they break *elsewhere*: the file you edited still compiles, while callers you have never opened start reporting that a value may be undefined. ## The locality rule The distinction I use is whether the check and its consumer are visible together. **Within one function**, inferred narrowing is the right default. The alias, the condition and the use are in the same body; if a refactor breaks the inference, the error lands next to the change, in the same review, usually within seconds in the editor. There is no cost to being wrong here beyond a moment's confusion, and the alternative — ceremony around every local check — makes code worse. **Across a boundary** — an exported function, a module's public surface, anything another team consumes — I want the invariant in the type. Concretely: validate at the edge and return the narrow type, so callers never hold the wide one. A parser that returns `Config` instead of `Config | undefined`, or throws, removes the question entirely. Where a boolean check genuinely must cross the boundary, the relationship belongs in the signature rather than being left to inference, because a signature is a contract that a change to the body cannot silently revoke. ## Why not just declare everything Because declarations that a human writes are also promises the checker will not verify, and each one is a place the code and the claim can drift apart. Erasure is the reason: none of this exists at run time, so no annotation is validated by execution. A codebase that reflexively hand-declares every relationship trades one risk (inference silently disappearing) for another (an assertion that was true when written and is false now), and pays in ceremony besides. The narrow-type-at-the-boundary approach avoids both, because there is nothing left to promise once the wide type never escapes the edge. ## What I actually enforce - **Boundaries return narrow types.** Parsing, validation and adapters are where the union collapses; downstream code should not be re-checking what was already established. - **A vanished narrowing is investigated, not silenced.** The tell in review is a non-null assertion or a cast appearing in a diff that had nothing to do with nullability. That is a compile error being converted into a run-time one, and it is the single habit most worth naming explicitly. - **Explicit return annotations on exported functions are a deliberate choice, not a blanket rule.** They are good documentation, but on a refining helper an annotation is exactly what turns off inference — so the team should know that writing `: boolean` there is a decision with a consequence. - **Version awareness.** These behaviours arrived in specific compiler versions, so a monorepo pinning an older TypeScript, or a published package supporting a range of consumer versions, cannot assume callers get the same inference. Anything shipped as a `.d.ts` should state its guarantees rather than hope the consumer's compiler derives them. ## The wider judgment The deeper trade is between *proving* an invariant repeatedly and *establishing* it once. Narrowing is proof-at-each-use: cheap, local, and re-derived every time the checker runs. Making the narrow type the declared type is establish-once: it costs a validation boundary and a type to name, and in exchange every downstream reader gets the guarantee for free and no refactor can quietly take it away. Small, local, fast-moving code favours the first. Long-lived shared code — anything with callers you will not personally fix — favours the second. Most of the pathologies I see in review come from applying the local answer at a boundary: a wide type spreading through a system, each consumer re-checking it, each check depending on inference that one edit can remove. ## How I would introduce this to a team Not as a lint rule, because none of this is mechanically detectable in a useful way. As a review heuristic with two questions: *would a reader of this signature know the invariant?* and *if this inference disappeared, where would the errors show up?* If the answers are "no" and "in someone else's module", the invariant belongs in the type.