Typed Service Contracts

This is a strict architectural pattern for TypeScript services that treats inputs as untrusted data requiring parsing (via Zod schemas) and errors as typed return values instead of exceptions. You define a spec.ts with input/output/error schemas and a discriminated union Result type, then implement it in handler.ts that never throws. The split is deliberate: contract tests validate your Zod schemas catch bad data, logic tests mock dependencies and assert on Result objects. It's overkill for CRUD apps but makes sense for CLIs, libraries, or anything where unhandled exceptions are unacceptable. The "parse don't validate" philosophy and exhaustive error enums force you to think through failure modes upfront rather than discovering them in production.