Hardening a Healthcare Platform's Type Safety

Problem/Feature Description

A healthcare data platform stores and processes sensitive records including patient IDs, provider IDs, appointment IDs, validated email addresses, and license numbers. The current TypeScript codebase uses plain string for all of these, which has led to a production incident: a developer accidentally passed a providerId where a patientId was expected, and the resulting data corruption wasn't caught until end-to-end tests ran hours later.

The engineering team wants to harden this module so that TypeScript itself prevents mixing of these semantically distinct identifiers at compile time — without changing the runtime representation. They also want a principled way to validate raw strings (from API inputs) into these stronger types, covering two patterns: one where invalid input should throw immediately, and one where the caller decides how to handle the failure.

Output Specification

Produce a TypeScript file healthcare-types.ts that:

• Defines the nominal typing infrastructure (a reusable generic helper)
• Defines at minimum: PatientId, ProviderId, AppointmentId, ValidatedEmail
• Provides validation logic to convert raw string inputs into these types
• Illustrates how functions that accept these types are protected from misuse

Also produce a README.md that explains the type-theoretic reason this approach works, including a before/after code comparison showing how the old plain-string approach allowed bugs.

If you use utility types to extract return types from any async functions in the module, document how you apply them correctly.

Include a type-tests.ts file with compile-time assertions verifying the type constraints hold.