refactor: decompose v2 notebook route orchestration #7

Context

src/routes/notebooks-v2.ts is 398 lines, which is right at the architecture module-size cap of less than 400 lines. It is not a full god object yet, but it mixes several orchestration responsibilities that will become hard to evolve if more v2 notebook behavior lands here.

Current responsibilities include:

• notebook creation and request validation (src/routes/notebooks-v2.ts:49)
• source registration, D1 ingestion job creation, KV job payload persistence, and queue enqueueing (src/routes/notebooks-v2.ts:86)
• notebook-scoped chat retrieval, Vectorize fallback handling, D1 fallback chunks, generation, citations, and degraded response generation (src/routes/notebooks-v2.ts:170)
• artifact template validation, chunk gathering, prompt construction, generation fallback, snapshot hash capture, and artifact persistence (src/routes/notebooks-v2.ts:277)
• job polling query and response shaping (src/routes/notebooks-v2.ts:357)

Recommendation

Keep Hono route handlers thin and move orchestration into focused helpers/services.

Suggested split:

• source registration/enqueue helper for POST /:notebookId/sources
• notebook chat service for retrieval, fallback, generation, and citation shaping
• artifact generation service for prompt creation, fallback content, snapshot hashes, and persistence
• job status store/helper for ingestion job lookups
• shared v2 request validation/constants so notebooks-v2.ts and notebooks-v2-manage.ts do not drift

Acceptance criteria

• src/routes/notebooks-v2.ts drops well below the 400-line cap.
• Route handlers primarily parse inputs, call focused helpers, and shape HTTP responses.
• Existing API responses remain backward compatible.
• Error handling stays explicit for missing D1, missing notebook/source data, model-generation failure, and empty notebook content.
• Add focused tests around extracted pure helpers where possible.

Verification baseline

Current baseline from the audit:

• npm test passes: 12 tests across 2 files.
• npm run type-check passes.