TypeScript backend service

Data crossing into the process — HTTP responses, queue payloads, `JSON.parse`, file contents — is parsed with a schema. `as`, `as unknown as`, `any` and `@ts-expect-error` without a linked issue are rejected at these boundaries. A cast is a compile-time claim about runtime data: the crash still happens, just later and in a place with no context.

Blocks: casting at the boundary defeats the reason the codebase is typed at all.

Every promise is awaited, returned, or explicitly discarded with `void` plus a `.catch` that logs. A bare async call as a statement is rejected. An unhandled rejection terminates the process on modern Node, so a fire-and-forget analytics call takes down the request handler that ignored it.

Blocks: the failure mode is process death under production load.

HTTP client calls, database statements, and lock acquisitions pass an explicit timeout or `AbortSignal`. Node sets no default socket timeout, so a single hung dependency holds connections and event-loop work until the pool is exhausted and the whole service is down — not just the feature that called it.

Blocks: a missing timeout converts a partner's slowdown into your outage.

Environment variables are read and parsed in the config module and imported from there. `process.env.X` anywhere else in application code is rejected. Config parsed at boot fails the deploy; config read lazily fails on whichever request first reaches that branch, possibly weeks later.

Blocks: it decides whether a misconfiguration is caught by the deploy or by a customer.

A queue or cron handler tolerates running twice on the same payload — guard with a unique constraint, an idempotency key, or an upsert. At-least-once delivery is the norm for every broker worth using, so a retry that charges a card twice is a scheduled incident, not an edge case.

Blocks: duplicate side effects on money or messaging are customer-visible and hard to unwind.

Monetary amounts are integer minor units or a decimal type, all the way through. `parseFloat`, `number` arithmetic on prices, and float columns are rejected. Binary floating point cannot represent 0.1, so totals drift by cents and the drift lands in a customer invoice.

Blocks: financial errors are unrecoverable in the sense that matters — trust.

Throw an error class from the shared errors module carrying a stable `code`. `throw new Error("failed")` and throwing a string are rejected. Callers cannot branch on prose, so they end up matching message text — and then a copy-edit changes behaviour in production.

Warns: it degrades maintainability rather than breaking the current code path.

Application code logs via the shared structured logger, passing an object that includes the request or job id. `console.log` and `console.error` outside of scripts and bootstrap are rejected. Unstructured lines cannot be filtered, correlated or sampled, so they cost money to store and give nothing back during an incident.

Warns: real operational cost, no functional risk.

Store, pass and compare timezone-aware UTC values; convert to a local timezone only at the presentation edge. Deriving business logic from a bare `YYYY-MM-DD` string, or from the server's local timezone, is rejected — it works until a deploy region changes or the clocks shift.

Warns: bugs appear twice a year and at region boundaries, not on the day of the merge.

A package added to the manifest is pinned to an exact version or a bounded range, lands in `devDependencies` when only tooling uses it, and is not a second copy of something else the same change adds — two HTTP clients, two date libraries, two validation libraries. Agents reach for a package by reflex; every added dependency is permanent supply-chain surface and someone's future upgrade.

Warns: sometimes the dependency is right — the point is that adding one becomes a decision rather than a reflex.

Functions exported from a module or a package annotate their return type instead of relying on inference. An inferred return type means an internal refactor can silently change a public contract, and the error surfaces in a consumer's build rather than in this PR.

Informational: it improves review signal; nothing breaks today.