Phase 2 stage 1 — Foundations: provider, contracts, constants, and the error handler fix

[rsml]

Stage 1 of Phase 2. Small and early on purpose, so the Phase 3 client work can rebase on the shared types it needs without waiting for the full server restructure. Part of #41.

What this is

Three foundations: one source of truth for the AI providers, the shared response and SSE contract types the client will consume, and the server's named constants plus its HTTP helper modules. Plus one sanctioned behavior fix that had to land with the error-handling work.

The sanctioned fix: the error handler never ran

Phase 0's characterization tests recorded a real defect. buildServer() called setErrorHandler AFTER every route plugin had already been awaited through register(). Fastify only propagates an error handler to encapsulation contexts created after it is set, so all nine plugins booted against Fastify's default handler and the app's own handler was dead code. Phase 0 froze that behavior deliberately rather than fixing it out of scope.

Registering it ahead of the route plugins is the fix. The mapping is now a pure function, so it is unit tested without booting a server.

Seven Phase 0 assertions were updated, each marked in place with the reason.

#	File	Assertion	Before	After
1	books.characterization.test.ts	GET /api/books/:id unknown id	500, Fastify shape, message contained an absolute filesystem path	404 {error:'Not found'}, no path
2	books.characterization.test.ts	GET /api/books/:id bad id pattern	400 {statusCode,code,error,message}	400 {error}
3	books.characterization.test.ts	DELETE then GET	500 ENOENT	404 {error:'Not found'}
4	books.characterization.test.ts	chapter number out of range	400 {error,message,statusCode}	400 {error}, same message text
5	books.characterization.test.ts	non-numeric chapter param	400 FST_ERR_VALIDATION shape	400 {error}
6	books.characterization.test.ts	chapter 0	400 FST_ERR_VALIDATION shape	400 {error}
7	audiobook.characterization.test.ts	bad voiceId pattern	400 FST_ERR_VALIDATION shape	400 {error}

No status code changed except the two ENOENT cases going 500 to 404. The rest keep their status and only move to the {error} shape, which is what client/lib/api.ts already reads via err.error. The file-header FROZEN QUIRK note was rewritten to explain the resolution rather than deleted, since it is why those assertions carry a change marker.

The eight MCP authoring routes did NOT flip to 400 in this PR. They still return 500 on bad input, because they parse inline rather than through parseBody. Their body did change from Fastify's shape, which echoed the raw parser message, to a generic {error:'Internal server error'}, which is a leak fix. The 500 to 400 flip happens in stage 2 when parseBody reaches them.

Foundations

One provider list. 'anthropic', 'openai', 'google' was declared in three places and the default provider was repeated 12 times. All of it now comes from shared/provider.ts, along with MODEL_REGEX, which had two copies. A fifth duplicate, the Fastify param pattern in models.ts, is now derived from the shared list and verified to build the exact same string.

Shared contract types. shared/responses.ts and shared/events.ts are types only, so they compile away. Every type is read off the handler that produces it, with JSDoc naming the route. The SSE unions are discriminated on the real type discriminants found in the reply.raw.write calls.

Named values. Five files each defined their own five minute AI timeout. server/constants.ts now holds the tunable numbers, and server/http/ holds status.ts, route-params.ts (two files hand-rolled an identical book id schema), send-media-range.ts (lifted out of the books route file), plus parse.ts and error-handler.ts.

Gate

Check	Result
pnpm test	23 passed (23) files, 315 passed (315) tests, up from 286
pnpm typecheck	exit 0
pnpm lint	exit 0, zero warnings
Boot	/api/health returns ok, /api/books serves real data
Error handler live	/api/books/does-not-exist returns {"error":"Not found"} at HTTP 404, no path
Derived provider pattern	params/provider must match pattern "^(anthropic|openai|google)$" at HTTP 400, byte identical to the literal it replaced
rg "5 \* 60 \* 1000" server/	nothing
rg "AI_TIMEOUT_MS =" server/	nothing
Book id pattern	only in server/http/route-params.ts

TDD

Both new behaviors were specified before they existed. shared/provider.test.ts, server/http/parse.test.ts, and server/http/error-handler.test.ts were each committed red, with the pre-commit hook bypassed for that reason alone and stated in the commit body, then turned green by the following commit.

Findings handed to Phase 3

The contract work surfaced concrete drift the client team should know about.

• interface Book, duplicated byte-identically in client/App.tsx and client/components/BookListRow.tsx, marks five fields optional that the server always sends: hasCover, showTitleOnCover, coverUpdatedAt, hasAudiobook, prompt.
• It types status?: string. The server always sends one of six literals. shared/book-status.ts has the right type.
• It omits three fields the server does send: updatedAt, profileOverrides, audioGeneratedChapters.
• client/lib/parse-sse-stream.ts has ONE flattened event union covering four different streams, so its done variant conflates create-book's shape with generate-chapter's unrelated one, and its stage is a bare string. shared/events.ts replaces this with five separate discriminated unions.
• client/lib/api.ts's existing SearchResponse and EpubPreview already match the derived types exactly, so adopting them there is a pure rename.
• client/lib/providers.ts independently declares the provider list. It should adopt @shared/provider. Left alone because Phase 3 owns client/.

Deviations

1. Module paths. The plan specified shared/domain/provider.ts and a shared/contracts/ directory. Phase 1 delivered shared/ as flat modules, so directories of those names would collide with the existing shared/domain.ts and shared/contracts.ts. These land as shared/provider.ts, shared/responses.ts, and shared/events.ts, mirroring shared/book-status.ts. Chosen for zero import churn while Phase 3 is running concurrently.
2. http/sse.ts is deferred to stage 2. Extracting it now would create a module with no callers, since the streaming routes do not move until the route split.
3. A stage SSE event is declared but never emitted. No code path constructs one today. It is kept in the union because it is part of the server's own exported event type and the client already handles it in three places.
4. Server-side status literals and a duplicated profile-context builder remain. Both are stage 2 work, listed in the plan.

https://claude.ai/code/session_01FSkESkJTRpt3Ye2cM7c5n5