feat(budget): move per-source filter to server-side via ?deselectedSources=

[steilerDev]

Summary

Moves the per-source filter from the client to the server, fixing the subsidy
oversubscription consistency bug introduced by #1356/#1358 (filtered Cost
could be lower than displayed Payback because the subsidy engine ran against
the unfiltered project).

• GET /api/budget/breakdown?deselectedSources=<id1>,<id2>,unassigned accepts
  a comma-separated list of deselected source IDs (and the unassigned
  literal). Empty/missing param = full project-wide breakdown.
• Backend filters lines at the top of the pipeline, re-runs the subsidy engine
  against the filtered cost set, and emits filter-aware aggregates +
  per-source pro-rata payback (subsidyPaybackMin, subsidyPaybackMax).
• Items / areas with no surviving lines are pruned server-side.
• Source detail rows still show their unfiltered Cost (architect decision A:
  the deselected source stays informative — user sees what they're filtering
  away).
• Client refetches on each chip toggle with 50ms debounce + AbortController +
  stale-while-revalidate (previous breakdown stays visible at reduced opacity).
• Removes ~530 lines of client-side aggregation (computeFilteredAggregates,
  computePerSourcePayback, all filtered memos, all cascade-hide guards).

Closes #1360

This explicitly supersedes the #1356 decision that "subsidy adjustments stay
project-wide".

Test plan

• Quality Gates green (lint, typecheck, unit + integration tests)
• E2E Tests across 16 shards × 3 viewports green (subsidy oversubscription
  consistency scenario added — canonical bug verification)
• Backend integration tests: filter param parsing, empty/missing/unknown
  source IDs, unassigned literal, cascade pruning, per-source unfiltered
  projections, per-source pro-rata payback
• Frontend unit tests: debounce + AbortController + stale-while-revalidate
• API client query-string encoding

Co-Authored-By: Claude dev-team-lead (Sonnet 4.6) noreply@anthropic.com

[steilerDev]

[product-architect] Approve (verdict: approve — comment instead of --approve since I co-authored).

Architect decisions A/B/C/D verified end-to-end:

• Pipeline order correct. filteredWiLineRows/filteredHiLineRows (budgetBreakdownService.ts:163-164) computed at top of pipeline, before entity aggregation (line 533+) and computeEntitySubsidyPayback (lines 600, 764). Subsidy engine runs against the filtered set — the canonical bug from Available Funds source rows act as per-source filter; Cost/Payback/Net per source #1356/Cost Breakdown Table: aggregated rows ignore source filter (subtotals and grand totals inconsistent) #1358 is fixed at the source.
• Decision A (per-source projectedMin/Max UNFILTERED) honored: per-source projection accumulators iterate workItemLineRows/hiLineRows (unfiltered) and reuse wiLineInvoiceMap/hiLineInvoiceMap for actuals — no leak from the filtered path.
• Decision B (per-source subsidyPaybackMin/Max from FILTERED engine) honored: sourcePaybackMap walks wiEntityData/hiEntityData (filtered) with pro-rata weighting by max-perspective resolved cost, falling back to equal split when total cost is 0 — sound. Deselected sources naturally yield {min: 0, max: 0}.
• Cascade pruning is server-side: items/areas with no surviving lines are dropped at aggregation, not at row render. Client deletes computeFilteredAggregates, computePerSourcePayback, all cascade-hide guards (~530 lines).
• Empty-state UX fix is correctly scoped: if (!hasData && !hasSources) (CostBreakdownTable.tsx:1958) only short-circuits when both areas are empty AND budgetSources is empty — preserves the "no data at all" path while keeping source rows visible when all sources are deselected.
• Wiki API contract (wiki@771c1df) fully documents the query param, the new BudgetSourceSummaryBreakdown shape with both new fields, the unfiltered/filtered split, and the "all sources always included + synthetic unassigned" behavior.
• discretionary-system seeded source flows through the standard budgetSourceId path with no special-case handling needed.

Nit (informational, not blocking): post-migration 0023, no production line has budget_source_id IS NULL, so the 'unassigned' literal in isLineFiltered is effectively dead in current data. Harmless and forward-compatible — keep as defensive code.

LGTM.

[steilerDev]

[security-engineer] PR #1361 security review — APPROVED

No blocking findings.

Verified the three security-relevant surfaces:

Query param parsing (): Raw string split on ,, trimmed, empty strings filtered out via filter(Boolean). Result is a Set<string> consumed only by Set.has() lookups — no user input reaches any SQL query. Unknown IDs are silently ignored, which is the correct behavior (no error oracle). No injection vector.

Filter implementation (): Filtering is entirely in-memory on already-fetched row arrays (filteredWiLineRows, filteredHiLineRows). The isLineFiltered() helper uses only Set.has() and strict null equality — no SQL interpolation of user input at any point. Per-source projections iterate the unfiltered original rows (architect decision A), which is correct and expected.

Authorization: The existing preValidation session hook remains in place and unchanged. The new query-param path is inside the same authenticated handler. No bypass introduced.

Frontend: encodeURIComponent(join(',')) correctly URL-encodes the deselected IDs before they reach the server. The unassigned literal is a hardcoded string in the client and is handled as a known sentinel on the server — no reflection of arbitrary user data into rendered output. No dangerouslySetInnerHTML or raw DOM injection found in the changed files.

Informational — no schema validation on deselectedSources: The query param has no Fastify schema constraint (no maxLength on individual IDs, no maxItems on the comma-separated list). In practice the Set is only ever used for Set.has() comparisons so there is no exploit path, but adding a schema-level bound (e.g., max param string length of 4096 chars) would be a defense-in-depth improvement. Low priority, consistent with prior findings on this route (#466).

Checklist: injection ✓ | auth ✓ | sensitive data ✓ | input validation ✓ | dependencies ✓ | secrets ✓

[steilerDev]

[security-engineer] PR #1361 security review -- APPROVED

No blocking findings.

Verified the three security-relevant surfaces:

Query param parsing (budgetOverview.ts lines 30-71): Raw string split on ,, trimmed, empty strings filtered out via filter(Boolean). Result is a Set<string> consumed only by Set.has() lookups -- no user input reaches any SQL query. Unknown IDs are silently ignored, which is the correct behavior (no error oracle). No injection vector.

Filter implementation (budgetBreakdownService.ts): Filtering is entirely in-memory on already-fetched row arrays (filteredWiLineRows, filteredHiLineRows). The isLineFiltered() helper uses only Set.has() and strict null equality -- no SQL interpolation of user input at any point. Per-source projections iterate the unfiltered original rows (architect decision A), which is correct and expected.

Authorization: The existing preValidation session hook remains in place and unchanged. The new query-param path is inside the same authenticated handler. No bypass introduced.

Frontend: encodeURIComponent(join(",")) correctly URL-encodes the deselected IDs before they reach the server. The unassigned literal is a hardcoded string in the client and handled as a known sentinel on the server -- no reflection of arbitrary user data into rendered output. No dangerouslySetInnerHTML or raw DOM injection found in the changed files.

Informational -- no schema validation on deselectedSources: The query param has no Fastify schema constraint (no maxLength on individual IDs, no maxItems on the comma-separated list). In practice the Set is only ever used for Set.has() comparisons so there is no exploit path, but a schema-level bound (e.g., max param string length of 4096 chars) would be a defense-in-depth improvement. Low priority, consistent with prior findings on this route (#466).

Checklist: injection OK | auth OK | sensitive data OK | input validation OK | dependencies OK | secrets OK

[steilerDev]

[product-owner] PR #1361 review — APPROVED (advisory; cannot self-approve as repo owner)

All 31 acceptance criteria from issue #1360 verified. Architect decisions A/B/C/D honored. The canonical bug (subsidy oversubscription consistency) is fixed.

Server (AC #1–#10) — getBudgetBreakdown(db, deselectedSources) filters at the top of the pipeline (filteredWiLineRows/filteredHiLineRows). Subsidy engine re-runs on the filtered set, items/areas with no surviving lines are pruned, route accepts ?deselectedSources= with comma-separated UUIDs and the unassigned literal. Unknown UUIDs degrade silently. Route defaults to empty Set (backward compatible). Backend tests Scenarios 1–10 in budgetBreakdownService.test.ts and Scenarios 11–15 in budgetOverview.breakdown.test.ts cover every server-side AC including the 401 unauth case.

Decision A honored: sourceProjectedMap iterates the UNFILTERED workItemLineRows/hiLineRows, so deselected sources keep their full projected contribution in budgetSources[]. BudgetSourceSummaryBreakdown in shared/src/types/budgetBreakdown.ts now carries subsidyPaybackMin/subsidyPaybackMax (Decision B), pro-rata attributed from the filtered engine run via sourcePaybackMap. Synthetic unassigned entry emitted whenever any null-source lines exist.

Client (AC #11–#17) — BudgetOverviewPage.tsx debounce + AbortController + stale-while-revalidate effect implements Decision D with DEBOUNCE_MS = 50. The wrapper div toggles styles.breakdownRefetching (opacity 0.6, pointer-events: none) so the previous breakdown stays visible during refetch — no flicker. Refetch errors render an inline role=\"alert\" banner with a Dismiss button; the previous breakdown is preserved (AC #14). Initial load reads deselectedSourceIds from the URL before the first fetch (AC #15).

Code deletion (AC #18–#28) — every named symbol from issue #1360 is gone: computeFilteredAggregates, computePerSourcePayback, filteredAdjustedTotalPayback, filteredRawProjected, filteredAvailableFunds, unassignedAllocatedCost, visibleLineIds, FilteredAggregates/FilteredEntityTotals, areaHasVisibleLines, all hasSourceFilter && … cascade guards, all filteredAggregates-conditional ternaries. Section/area/item rows read directly from server-provided *.rawProjectedMin/Max and *.subsidyPayback. Per-source row Payback reads source.subsidyPaybackMin/Max.

Tests (AC #29–#32) — service + route tests cover every server AC. Client tests cover debounce/abort/SWR/URL-on-mount/error path (Scenarios 24–29). E2E budget-source-filter.spec.ts adds the canonical subsidy oversubscription scenario (Scenario D), stale-while-revalidate (Scenario E), URL-on-mount (Scenario F), and rapid debounce coalescence (Scenario H).

Late-cycle empty-state UX fix — verified in CostBreakdownTable.tsx: early-return empty state now fires only when !hasData && !hasSources. When all sources are deselected (server prunes areas, but budgetSources[] is non-empty), the full table renders — source rows, Available Funds, Sum, Remaining Budget all visible with zeroed totals. The user is no longer trapped in an empty-state dead end. Regression test "Scenario 24" in CostBreakdownTable.test.tsx locks this in.

Security-engineer approved separately. Cleared for merge.

[steilerDev]

[ux-designer]

Reviewed the UX surfaces in PR #1361. Two findings — one critical (dark mode contrast), one medium (recurring focus token pattern). This would be --request-changes on an external PR; posting as a comment since this is our own PR.

---

Critical — Dark mode contrast failure in .breakdownErrorBanner

The error banner uses background: var(--color-bg-inverse) but color: var(--color-text-primary) for both the banner text and the dismiss button.

In dark mode these tokens resolve to:

• --color-bg-inverse → --color-gray-100 = #f3f4f6 (light gray surface)
• --color-text-primary → --color-slate-50 = #f1f5f9 (near-white text)

Near-white text on a light gray background is essentially invisible — far below WCAG AA 4.5:1. The same token conflict exists on the dismiss <button> inside the banner.

Fix: On any element using --color-bg-inverse as its background, pair it with --color-text-inverse for text (resolves to #fff in light mode, --color-gray-900 in dark mode — correct in both).

.breakdownErrorBanner {
  background: var(--color-bg-inverse);
  color: var(--color-text-inverse);   /* not --color-text-primary */
}
.breakdownErrorBanner button {
  color: var(--color-text-inverse);   /* not --color-text-primary */
}

This matches the established GanttTooltip pattern documented in the Style Guide.

---

Medium — Focus ring uses outline instead of --shadow-focus token

/* current */
.breakdownErrorBanner button:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 2px;
}

Per the design system, focus rings must use box-shadow: var(--shadow-focus). outline: 2px solid var(--color-primary) is a recurring pattern flagged in PRs #402 and #414.

Fix:

.breakdownErrorBanner button:focus-visible {
  box-shadow: var(--shadow-focus);
  outline: none;
}

---

Approved patterns

• .breakdownRefetching — opacity: 0.6, pointer-events: none, transition: opacity var(--transition-fast) — all tokens, correctly guarded by @media (prefers-reduced-motion: reduce) { transition: none; }. No issues.
• New i18n keys refetchError / dismissError use t() correctly in both EN and DE.
• Empty-state UX fix (deselecting all sources keeps table visible) — correct behavior, no styling concerns.
• No new design tokens introduced — confirmed.

[github-actions]

🎉 This PR is included in version 2.4.0-beta.4 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version 2.4.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀