typescript-conventionslisted

# TypeScript Conventions Applies to: `*.ts` across the repo's TypeScript packages. Target: TS 5.x → ES2022. Runtime: Node 22. Build: esbuild (or the project's bundler). Test: Vitest. > Naturalize: confirm the exact package paths, bundler, and test runner in `CLAUDE.md`. The defaults below assume a pnpm workspace shipping to a Node 22 runtime. ## Core Intent - Respect existing architecture; extend abstractions before inventing new ones. - Readable, explicit solutions over clever ones. - Pure ES modules — never `require` / `module.exports` / CJS helpers. ## Naming & Style - kebab-case filenames (`user-session.ts`, `data-service.ts`). - PascalCase for classes, interfaces, enums, type aliases. camelCase for everything else. - No `I`-prefix on interfaces. - Name for behavior/domain meaning, not implementation. ## Type System - Avoid `any` (implicit or explicit). Prefer `unknown` + narrowing. - Discriminated unions for state machines and event payloads. - Centralize shared contracts in a `shared`/`common` package rather than duplicating across packages. - Use TS utility types (`Readonly`, `Partial`, `Record`, etc.) to express intent. ## Async, Events, Errors - `async/await` with try/catch and structured errors. - Guard edge cases early to avoid deep nesting. - Route errors through the project's logging/telemetry utilities. ## Architecture - Single-purpose modules. - Keep transport / domain / presentation layers decoupled. - Instantiate clients (cloud SDKs, DB clients, e