typescript-runtime-boundary-modeling

Accept the input as `unknown` at the runtime edge, then prove the exact fields the next layer relies on using a manual guard, assertion function, or schema-derived parser. Export only the trusted output shape, for example `parseX(input: unknown): TrustedX`, and keep raw DTO or record types out of core code.

Use manual guards when the shape is tiny, the proof fits in one readable function, and unknown-key policy is trivial. Choose schema-derived parsing when the shape is nested or reused, the trusted type should derive from the runtime proof, or unknown-key and transform policies must be explicit.

Throw when the boundary is terminal for the request path and a central error handler owns failure rendering. Return a structured result like `Result<TrustedX, Issues>` when the caller must branch on parse success or accumulate multiple validation failures.

Type assertions add no runtime checks, so `as unknown as T` lets unvalidated data cross the trust boundary invisibly. The same applies to `as any` and postfix `!`; trust must come from an actual parse or guard that runs before the type is claimed.

Treat `process.env` as string input, not typed config. Parse it once in a dedicated startup config module, apply defaults and number or URL coercion there, and export only the resulting trusted config object to the rest of the application.

Reject when extra keys likely indicate caller error or dangerous drift. Strip when you want a stable minimal internal shape and leniency is acceptable. Use passthrough only when preserved fields stay explicitly untrusted and downstream code never treats the whole object as trusted.