[upstream-queue] feat: shared foundation — generation API client + types (PR-1/8)

[damienriehl]

PR-1 of 8 — LLM node-expansion drain "shared foundation"

Queue policy (TODAY-2026-07-07): staged INSIDE the alea fork, base `dev`, UNMERGED (`dev`/`main` stay pure upstream mirrors). Retarget to CatholicOS decided post-today. Tracked in `docs/UPSTREAM-TRACKING.md` (A2.2).

What this is

The inert shared foundation the later slices build on: the typed LLM generation API client + its TypeScript types. Single clean commit cherry-picked from the `llm-helper` lineage (`a90ec39`) onto fresh `origin/dev`.

• `lib/api/generation.ts` (75 lines, new) — `generationApi.generateSuggestions()` + the exported types (`GeneratedSuggestion`, `GenerateSuggestionsRequest/Response`, `SuggestionType`, `Provenance`, `ValidationError`, `DuplicateCandidate`, `DuplicateVerdict`).
• `tests/lib/api/generation.test.ts` (124 lines, new) — 4 tests: request shape + conditional `X-BYO-API-Key` header logic.

Pure additions (199 insertions, 0 deletions). No UI, no backend dependency — nothing imports `generation.ts` yet, so it is behaviorally inert until PR-3/PR-5/PR-6 wire it up. This is why "deploy+verify on FOLIO DEV" is satisfied by the clean production build rather than a live redeploy (an inert types file exercises no runtime surface; a web rebuild is also gated on the L4.4 OIDC/disk chain).

Auth handling (reviewed)

`generateSuggestions` takes a required `token` and sends `Authorization: Bearer ${token}`, with a conditional `X-BYO-API-Key` only when a BYO key is supplied — the correct pattern (contrast: web#3 fixed a MEDIUM where the ported graph client dropped this header).

Scope decision — `suggestions.ts` type slice DEFERRED to PR-6

The roadmap tags type-only additions to `lib/api/suggestions.ts` as PR-1, but they live in a single atomic phase-16 commit (`1e17916`) that interleaves the 7 review interfaces WITH 3 implemented method bodies (`getSessionDetail`, `postShardReviews`, `createCleanPR`) + a 229-line test exercising them. Carving out only the types = a slice traceable to no upstream commit (exactly the messy slice to avoid). `1e17916` belongs to PR-6, and cherry-picks cleanly onto a foundation that already has `generation.ts`. Keeping PR-1 = the single inert `a90ec39`.

Verification (all green)

• `tsc --noEmit` — 0 errors
• `eslint` — 0 errors (slice files clean; folded in a fix removing 6 unused type imports the cherry-pick carried)
• `vitest` generation test — 4/4
• `vitest` full suite — 2753 passed / 160 files

Depends on nothing. PR-0 (entity-graph, web#3) and this can land independently. Merge order: 0 → 1 → 2 → 3 → 4 → 5 → 6 → (7).

[damienriehl]

/ce:review — CLEAN (kieran-typescript pass)

No BLOCKER/HIGH/MEDIUM findings. Auth traced end-to-end: Authorization: Bearer ${token} survives through api.post → request → fetch, and the X-BYO-API-Key spread uses a distinct key so it can never clobber Authorization — the sibling graph-client bug is not present here. Zero any; contract matches the FastAPI snake_case convention; confirmed inert (nothing imports generationApi yet).

Applied (LOW #1, 764244c): hardened the byoKey test to assert Authorization co-exists with X-BYO-API-Key (highest-value guard given the sibling token-drop regression) — the exact scenario a future refactor could silently break. Full generation suite still 4/4.

Documented follow-up (LOW #2, not a gate): GeneratedSuggestion is a flat pseudo-union (annotation/edge extras optional on one interface), so TS can't narrow on suggestion_type. Faithful to the backend's flat serialization and fine for an inert foundation; convert to a discriminated union in the consuming PR (PR-3/5/6) when code actually branches on suggestion type.

Backend contract note: field-level fidelity vs ontokit-api's GenerateSuggestionsResponse/GeneratedSuggestion Pydantic models is asserted by convention (backend not in this checkout) — worth a 30-sec cross-check before the consuming PR lands.

[damienriehl]

Superseded by consolidated ALEA web PR #25, which merged the complete recent-plan capability stack to dev. The slice history remains preserved; current residuals and activation gates are tracked in documentation PR #39 and its linked issues.