Phase 2 — Server hexagonal restructure

[rsml]

Part of the demo-quality refactor tracked in docs/plans/refactor/. Branches phase-2-foundations then phase-2-server-hexagonal. Depends on Phase 1.

Objective

Make the server fully hexagonal. Every external dependency sits behind a named port with an in-memory fake and a contract test, services are unit tested against the fakes, and routes shrink to parse, call a service, reply. The 2,244 line server/routes/books.ts disappears.

Contents

• An early foundations PR consolidating provider constants into shared/domain/provider.ts and adding response contract types plus SSE event unions
• Ports with fakes and contract tests written before the adapters that satisfy them
• Adapters for text generation, book repository, speech synthesis, image generation, key vault, diagram rendering, EPUB import and export, and background tasks
• A composition root that wires ports into buildServer() and accepts overrides for tests
• Mechanical route split, then five service slices extracted in parallel
• Dead code removal

Gate

• Grep gates pass, meaning no ai SDK imports, no fs access, and no repeated Zod error blocks inside server/routes/
• Contract tests green for every port and every adapter
• server/routes/books.ts no longer exists
• Characterization tests from Phase 0 still green, apart from the one sanctioned assertion change for the MCP authoring routes returning 400 rather than 500 on invalid input
• Manual end to end pass

[rsml]

Shipped in #49, merged to master as e8a5dd1 with master CI green. server/routes/books.ts is gone. Thirteen ports each ship an interface, an in-memory fake, and a contract test, eight of those contracts also run against the real adapter over temp directories, fifteen adapters hold every piece of real I/O, and sixteen route modules replace the old nine, the largest of them 199 lines. createPorts(overrides) builds the ports, createSharedServices(ports) builds the state two route modules must observe as one instance, and buildServer(overrides) threads both into every route plugin, so server/composition-root.ts is the only module naming a concrete adapter apart from two documented exceptions, services/recover-from-crash.ts reaching for the filesystem repository's stray tmp file sweep and electron/main.ts naming its own diagram renderer.

Two behavior changes were sanctioned in advance and both are in the branch. Eight MCP authoring routes now answer 400 rather than 500 on invalid input, which had no characterization coverage to edit, so the phase adds server/routes/authoring.characterization.test.ts covering all eight instead. The kroki diagram renderer now emits an escaped source fallback for a chart it cannot render rather than an empty string, standardising on what the Electron renderer already did, so a reader sees the diagram's text instead of a hole. Two ports were also widened while their real adapters were built, AudioAssembly.concatToM4b taking coverPath and bookTitle, the latter because the real M4B stitch tags the file with the book title. Zero assertions changed anywhere in the branch, and zero files under client/ were touched.