Add types to legacy JS / Python (without rewriting it)

Add types to this code. Don't rewrite logic. Don't change behavior.

```{{language}}
{{paste code}}
```

Type system: {{TypeScript / Python type hints / Flow / etc.}}

Approach:
- Be conservative. `any` / `Any` is acceptable when the type is genuinely unknown rather than a guess.
- Where there's clear shape from usage, infer the type.
- For union/optional fields, prefer `T | null` over `T | undefined` unless usage indicates otherwise.
- If a function has multiple call sites with different shapes, flag it. Don't paper over the inconsistency.

Output:
1. The typed code
2. Each type decision in a bullet — "this is X because Y in usage at line Z"
3. Anywhere I should have used `any` because the real type would require runtime checks
4. Any actual bugs the typing exposed (incorrect assumptions in the original code)