feat: optim pass for 1.0.0

[ob-aion]

Summary

Take @coroboros/location-timezone from migrated-and-typed to production-grade 1.0.0. No public API signatures change; subpath exports are additive.

Performance

Array.find / Array.filter / Array.includes over the parsed arrays were the dominant cost. Replaced with Map / Set indexes built once at module load. Benchmarks (Apple M1, Node 22.22.2):

Bench	Pre-optim	Post-optim	Speedup
findTimezoneByCityName (exact, late)	292.59 µs	27.03 ns	10,825×
findLocationsByCountryIso (US)	70.59 µs	20.36 ns	3,468×
findCountryByName (exact, late)	29.59 µs	12.06 ns	2,454×
findCapitalOfCountryIso (iso2, late)	4.12 µs	10.25 ns	402×
findCountryByIso (iso2, late)	4.19 µs	10.33 ns	405×
isValidCountryIso (iso2, late)	599.21 ns	5.36 ns	112×

Partial-match paths and findLocationsByCoordinates stay linear by design; full numbers and going-forward >5% regression budget in bench/baseline.md.

Types

• Internal CapitalWithCountry / CountryWithCapital at the data boundary; 8 non-null assertions removed.
• Public arrays now declare ReadonlyArray<X> return types — runtime backs the type with Object.freeze on data arrays, bucket arrays, fresh filter results, and nested country.timezones.
• helpers.ts is() simplified to typeof-based primitive checks.

Distribution

Subpath exports for fine-grained tree-shaking:

import { findStateAnsiByUspsCode } from '@coroboros/location-timezone/states-ansi'; // ~5 kB
import { findCountryByIso } from '@coroboros/location-timezone/countries';            // ~85 kB
import { findTimezoneByCityName } from '@coroboros/location-timezone/timezones';      // ~870 kB
import { findLocationsByCountryIso } from '@coroboros/location-timezone/locations';   // ~860 kB

tsdown multi-entry auto-emits shared chunks; main entry surface unchanged.

Other

• tests/location-timezone.property.test.ts — 13 fast-check invariants (ISO round-trips, closure, back-references, idempotency, case insensitivity, reflexivity).
• scripts/*.js ported to TypeScript ESM (run via tsx).
• README: swap branch-stable for ci badge, add Why this exists + Subpath exports sections.
• CLAUDE.md: Git, Publish auth, regression-budget rules; reflect new layout.
• .github/workflows/ci.yml — bootstrap shape calling the coroboros/ci reusable workflow (forwards NPM_PACKAGE_REGISTRY_TOKEN for the first publish; OIDC switch is a follow-up after 1.0.0 lands on npm).

Test plan

• CI preflight green (lint + typecheck + test + build) on the PR.
• pnpm test locally — 109/109 pass.
• pnpm bench reproduces the post-optim numbers (within the 5% budget).
• node -e "import('@coroboros/location-timezone/states-ansi').then(m => console.log(m.findStateAnsiByUspsCode('NY')))" — subpath import resolves after install.