refactor(llm): consolidate LLM integration boundaries and shared report math (PR #1916 follow-ups)

[steilerDev]

Consolidated follow-up for the non-blocking findings raised by product-architect across both review rounds on PR #1916 (story #1901, AI-generated report content), plus two items from the product-owner review.

Nothing here is a functional defect — PR #1916 shipped correct behaviour with regression coverage. The theme is that the LLM integration has outgrown the naming and boundaries it was given when it only did auto-itemization, and that one shared derivation is duplicated across client and server.

Source: PR #1916 (architect review rounds 1 and 2, product-owner review rounds 1 and 2) · Story: #1901

---

Highest value first

M2 — Extract computeIncludedTotal into @cornerstone/shared

This is the highest-value item of the set and the reason this issue exists.

The included-total derivation (sum each included invoice's allocatedAmount, minus the allocatedPortion of every excluded budget line, rounded per invoice to the nearest cent) now exists in two independent implementations:

• Client: client/src/lib/reportExclusions.ts (applyLineExclusions) + client/src/lib/reportContent/buildReportContent.ts
• Server: server/src/services/reportContentGenerationService.ts

This duplication has already drifted once, in production-bound code. PR #1916's blocking finding was exactly that: the server rounded to whole currency units while the client rounded to cents, and the server's per-invoice amounts ignored line exclusions entirely while its total honoured them. Both were caught in review, but only because someone re-derived the arithmetic by hand.

Extract the rule into @cornerstone/shared as computeIncludedTotal(report, includedInvoiceIds, excludedLineIds) and have both sides import the single implementation, so the letter total and the report table total cannot disagree.

Note for whoever picks this up: the two implementations are currently equivalent but not identical — the server rounds every included invoice unconditionally, the client only rounds invoices actually affected by an exclusion. The architect re-derived parity in round 2 and confirmed they agree in production, because sourceReportService.ts already guarantees allocatedAmount is 2 dp upstream. The server's extra rounding is defensive-only. Preserve that defensiveness in the shared function rather than "simplifying" it away, and keep a test covering a >2 dp input.

---

Medium

M1 — llmEnabled / autoItemizeEnabled duplication has no deprecation path

AppConfigResponse now carries two always-equal required booleans. Adding the alias was the right direction; the missing half is retiring the old name — the duplication forced edits to eight-plus object literals in PR #1916 alone. getProvider() also still gates the report-content feature on config.autoItemizeEnabled, so a feature that has nothing to do with itemization is switched by a flag named after it.

• Add @deprecated JSDoc to autoItemizeEnabled in shared/src/types/config.ts
• Plan and land the removal of the old name
• The "no third alias; any divergence between the two flags needs an ADR" rule is already recorded on the API Contract wiki page

M3 — Route returns a server-internal type instead of the shared contract type

POST /api/source-reports/generate-content returns GenerateReportContentLlmResult (from server/src/services/budgetExtraction/types.ts) rather than the shared GenerateReportContentResponse. The two are structurally identical today, so any future drift is silent. Sibling handlers in the same file bind the shared type explicitly (const response: MarkClaimedResponse = …) — do the same here so a contract change becomes a compile error.

M4 — BudgetExtractionProvider is now a general LLM gateway under a budget-extraction name

The interface carries three unrelated capabilities (extract, summarizeMerge, generateReportContent), and five unrelated server test suites (backupService, draftCleanupService, and three invoiceAutoItemize* suites) now stub all of them just to construct a double.

Consolidating on one gateway was the correct architectural call — the name and module path should follow. Rename budgetExtraction/ to llmGateway/, or split the interface per capability. Standalone refactor; deliberately kept out of PR #1916.

---

Low

L5 — Missing unit annotation on the LLM input types (root cause of the PR #1916 blocking bug)

server/src/services/budgetExtraction/types.ts:

• GenerateReportContentLlmInvoice.amount
• GenerateReportContentLlmInput.totalAmount

Neither documents its unit. That silence is precisely what let the service → prompt seam break (major-unit euros consumed as if they were cents, making every figure in a bank-facing cover letter 100× too small). The behaviour is now correct and pinned by tests, but the next field added to these interfaces inherits the same ambiguity.

Two comment lines: /** Major currency units, 2 dp — not cents. */

L1 — sourceId! non-null assertion

client/src/pages/ReportWizardPage/ReportWizardPage.tsx, in runAiGeneration. Narrow it via the existing early return instead: if (!report || !useCase || !sourceId) return;

L2 — Array.includes() inside four loops where the Set already exists

server/src/services/reportContentGenerationService.ts calls includedInvoiceIds.includes(...) in four separate loops, two lines after building a Set for exactly this purpose. Cheap at the maxItems: 200 bound, but use the Set.

L3 — Konstruktionsprojekt prompt copy — DONE, delivered by #1931 (PR #1944)

Removed from this issue's scope on 2026-08-02. Story #1931 rewrote REPORT_CONTENT_SYSTEM_PROMPT and buildReportContentUserPrompt wholesale and fixed this line as part of that rewrite: the inverted ternary is gone, both 'en' and 'de' now emit the single language-independent phrase German construction project as project-domain context (output language is carried solely by the Language: line and system-prompt rule 1), and Konstruktionsprojekt no longer appears anywhere — prompts.test.ts pins its absence as a regression guard. No Bauprojekt rename is needed, because no German noun remains in the prompt.

Nothing else in this issue is affected. The rest of #1917 (M1–M4, L1, L2, L5, and the KI glossary entry below) remains open and unchanged.

Glossary — add KI / KI-Unterstützung to client/src/i18n/glossary.json

Approved by product-owner. Both the translator (during the #1901 translation pass) and the product-owner (review round 1) independently flagged this, and the architect asked for it to be settled in round 2.

The term is now user-visible in two places, so it needs to be pinned rather than left to per-story judgement:

• Report wizard UI copy: "KI-Unterstützung aktivieren", "Mit KI generieren", "Inhalt mit KI generiert", "KI-Generierung fehlgeschlagen"
• The four shared LLM_* error strings, reworded feature-neutrally in PR feat(reports): AI-generated usage descriptions and cover letter for bank report wizard #1916: "KI-Unterstützung ist auf diesem Server nicht konfiguriert.", "Der KI-Dienst …"

Decision: AI → KI (and the compound AI assistance → KI-Unterstützung) is approved as a glossary term. KI is the standard German rendering and the de copy already uses it consistently — the entry codifies existing practice rather than changing anything. No string changes should result from this; if implementing it surfaces a German string still using "AI", that is a bug to fix, not a sign the entry is wrong.

translator implements next cycle. The glossary was deliberately not edited as part of this decision.

---

Explicitly out of scope

• L4 (feature-neutral LLM_* error copy) — already delivered in PR feat(reports): AI-generated usage descriptions and cover letter for bank report wizard #1916 b70d821b.
• The B1 monetary-unit fix and its regression tests — delivered and verified in PR feat(reports): AI-generated usage descriptions and cover letter for bank report wizard #1916 round 2.
• Informational, no action: invoiceAmountsAdjusted.get(inv.invoiceId) ?? inv.allocatedAmount in reportContentGenerationService.ts — the fallback is unreachable, since the map is populated under exactly the same filter that guards the read. Harmless; recorded only so it is not later mistaken for a meaningful default.
• Shard-5 E2E flake (tests/invoices/invoices.spec.ts:841, "Effective Amount" column) — unrelated pre-existing flake, tracked separately as a beta → main promotion blocker under Deposit refunds with negative claim adjustments #1876.

Suggested sequencing

M2 first (it closes a proven drift risk), then L5 and M3 (cheap, both make a future seam break a compile-or-review error), then M1, then M4 as a standalone refactor. L1/L2 and the glossary entry can ride along with any of the above.

[steilerDev]

[product-owner] Scope handoff: #1931 rewrites REPORT_CONTENT_SYSTEM_PROMPT and buildReportContentUserPrompt wholesale (purpose-focused output + prompt/validator length-cap reconciliation).

That rewrite subsumes the Konstruktionsprojekt prompt nit tracked here — buildReportContentUserPrompt L153 inverts the language ternary and is wrong in both branches. Remove that item from this issue when #1931 lands.

Everything else here is unaffected and stays open, including the headline M2 item (extract computeIncludedTotal to @cornerstone/shared) and the approved KI glossary entry — #1931 stays consistent with the existing de "KI" copy but does not add the formal glossary entry.

[steilerDev]

[product-owner]

Scope reduction — L3 removed, everything else unchanged.

Story #1931 (PR #1944) rewrote the report-content prompt wholesale and, as its Notes required, fixed the inverted language ternary as part of that rewrite. L3 is therefore delivered and has been struck from this issue's body.

Verified on 980c51a2:

• buildReportContentUserPrompt emits the fixed literal German construction project for both 'en' and 'de' — the ternary is gone.
• Konstruktionsprojekt appears nowhere in the source; prompts.test.ts pins its absence (expect(result).not.toContain('Konstruktionsprojekt')) as a regression guard against reintroduction.
• No Bauprojekt rename is required — no German noun remains in the prompt at all.

Explicitly still open here, not absorbed by #1931:

• M2 (extract computeIncludedTotal into @cornerstone/shared) — still the headline item.
• M1, M3, M4, L1 (sourceId! in runAiGeneration — verified still present at ReportWizardPage.tsx:574), L2, L5.
• The KI / KI-Unterstützung glossary entry. PR feat(reports): single Enhance with AI action and purpose-focused prompt (#1931) #1944 did not touch client/src/i18n/glossary.json (confirmed against the diff), and glossary.json still has no KI entry. Single "Enhance with AI" action and purpose-focused report content prompt #1931 only stayed consistent with existing de practice by using "Mit KI verbessern"; codifying the term remains this issue's job for the translator.

[steilerDev]

[product-owner]

Glossary rulings for the next refinement pass — 2026-08-03

Two questions escalated by translator during the PR #1959 review. Both are decided here; the glossary.json edits belong to translator on the next pass, same as the KI entry already recorded on this issue. PO does not edit the glossary directly.

---

1. Abschlag — APPROVED as a short-form variant of the Deposit term

Decision: Abschlag is an approved short form of Abschlagszahlung, permitted only where a measured width constraint makes the full form impossible. Abschlagszahlung remains the default and the only correct form in prose, labels, badges, and error messages.

The concrete sanctioned instance: sourceReports.table.depositReducedInlineLabel = abzgl. Abschlag. It ships as written in #1959.

Reasoning:

1. The constraint is real and was measured, not asserted. translator measured against the actual embedded font (fontkit, Roboto-Regular.ttf, 8pt note size) inside the fixed ALLOCATED_AMOUNT_WIDTH (75pt) column, with dontBreakRows: true and all-numeric column widths — so there is no elastic growth to absorb an overflow:

   Text	Width	Fits 75pt?
   " (Abschlagszahlung)" (existing sibling badge)	72.85pt	yes — sets the real ceiling
   " (abzgl. Abschlag)" (as shipped)	63.95pt	yes
   " (abzgl. Abschlagszahlung)" (strict)	96.07pt	no — overflows by ~21pt

2. Option (c), "a different short string that fits", is arithmetically unavailable. Abschlagszahlung alone already consumes 72.85 of the 75pt budget, so no qualifier of any length fits alongside it — not abzgl., not ohne, not even the accounting ./.. Keeping the full term therefore requires dropping the qualifier, which would collapse this label into the constituted-deposit label ((Abschlagszahlung), AC2.1 of Report table cleanup: shared footnotes, inline deposit labels, claim metadata, total-only summary, area in Usage #1923). Those are different facts — "this row is a deposit" versus "this amount is reduced because deposits were claimed separately". Collapsing them is a worse information loss than the abbreviation.

3. Option (b), widening the column, is rejected on risk. ALLOCATED_AMOUNT_WIDTH is part of the geometry that Report PDF layout breaks: usage column overflows the page, rows split across page breaks, running header clipped #1929 took four review rounds and real render-and-rasterize measurement to settle, precisely because the Usage column was collapsing and the table was overflowing the page edge. Growing this column past ~97pt trades directly against Usage and reopens that geometry for zero reader benefit.

4. Abschlag is not a mistranslation. In German construction and financial practice Abschlag and Abschlagszahlung name the same concept, and the clipped form is standard (cf. Abschlagsrechnung). abzgl. Abschlag is idiomatic German invoice language. No bank reader is misled — which is the bar that matters for outbound financial copy, per the precedent set on Verwendungsnachweis / Einreichung.

Why it earns a glossary entry rather than a silent exception: without one, a future compliance sweep will "fix" Abschlag -> Abschlagszahlung in good faith and silently break a bank-facing PDF's layout — the failure is invisible in a unit suite. The entry exists to stop that. It must record the width constraint and the 75pt column as the reason, not merely list the variant.

Entry shape requested (wording is translator's): the Deposit -> Abschlagszahlung entry gains a short-form variant Abschlag, annotated as permitted only under a measured space constraint, naming depositReducedInlineLabel as the sanctioned site and citing the 75pt fixed column.

---

2. split rendering three ways — NO glossary entry, deliberately

translator observed that the split concept now surfaces as anteilig (adjective), Anteil (noun), and Teilbetrag (noun) within the budget namespace, each grammatically correct for its role, mirroring the English source's own partial / split / portion variation.

Decision: no glossary entry. This is not drift and needs no correction.

The glossary exists to prevent semantic divergence — one concept translated as two different concepts. It is not a single-surface-form registry. Pinning one German form here would force ungrammatical copy, since the three call sites need an adjective and two different nouns. The English source varies for the same reason.

Recorded so a future translator does not re-escalate it. If the English copy is ever unified, revisit — but that is a copy story, not a glossary one.

Reject if proposed later: any entry that pins a single German surface form for split.