release: promote beta to main — source attribution & per-source filter for cost breakdown

[steilerDev]

Release Summary

Adds source attribution and a per-source filter to the Cost Breakdown table on the Budget Overview, plus the supporting backend pipeline. Each cost line now shows which budget source funds it (color-coded badge) and can be filtered out by toggling the corresponding source row. Filtering is server-side (?deselectedSources=…), so subsidy oversubscription, Sum, and Remaining Budget all stay mathematically consistent with the visible set.

This release supersedes the earlier chip-toolbar UX (PR #1354/#1355) with a row-as-toggle UX (#1357), and the originally client-side filter math (#1359) with a server-side filter pipeline (#1361). Followed by two small UX fixes (empty-state dead-end, dark-mode banner contrast).

Changes

Features

• Source attribution badges on every cost line — deterministic per-source color (10-slot palette, light/dark tokens), full source name on desktop, color dot + accessible name on mobile (feat(budget): add source attribution badges and per-source filter to cost breakdown overview #1355)
• Available Funds row redesign — source detail rows now display per-source Cost / Payback / Net columns (feat(budget): rework per-source filter to use source rows as toggles with Cost/Payback/Net columns #1357)
• Per-source filter — clicking a source detail row toggles that source on/off; URL state persists deselection via ?deselectedSources=<id>,<id>,unassigned; Escape selects all (feat(budget): rework per-source filter to use source rows as toggles with Cost/Payback/Net columns #1357)
• Server-side filter pipeline — GET /api/budget/breakdown accepts ?deselectedSources=…, filters lines at the top of the breakdown service, re-runs the subsidy engine against the filtered set, and emits filter-aware aggregates including subsidyPaybackMin/Max per source (feat(budget): move per-source filter to server-side via ?deselectedSources= #1361)
• Filtered Sum, totals, and Remaining Budget now match the visible lines exactly (fix(budget): make Cost Breakdown table aggregates filter-aware #1359 → fully replaced by feat(budget): move per-source filter to server-side via ?deselectedSources= #1361 server-side filter)

Fixes

• Keep source rows visible when all sources are deselected so users can re-enable them (no more empty-state dead-end) (Move per-source filter to server-side via ?deselectedSources= so subsidies recompute against the filtered cost set #1360)
• Error banner contrast & focus-visible in dark mode — switched to inverse text color and standard focus shadow (Move per-source filter to server-side via ?deselectedSources= so subsidies recompute against the filtered cost set #1360)

Tests

• 50+ new unit tests across budgetSourceColors, Badge (title prop), CostBreakdownTable (badge rendering, chip strip, filter active state, empty state, server-driven render path scenarios)
• Backend service tests updated for always-included system sources after migration 0021
• New E2E spec: e2e/tests/budget/budget-source-filter.spec.ts (filter toggle, URL persistence, mobile touch targets, dark-mode color, cascade-hide)

Docs

• Wiki: API Contract documents budgetSourceId per line, the budgetSources aggregate, and the deselectedSources query param

Change Inventory

Backend (server/, shared/)

• server/src/services/budgetBreakdownService.ts — accept deselectedSources, filter lines at top, per-source projected stays unfiltered, per-source payback derived pro-rata from filtered engine, cascade-prune empty items/areas server-side
• server/src/routes/budgetOverview.ts — parse ?deselectedSources=… (comma-separated source IDs + unassigned); unknown IDs silently ignored
• server/src/routes/budgetOverview.breakdown.test.ts — coverage for the new param + response shape
• server/src/services/budgetBreakdownService.test.ts — coverage for filter, source aggregation, and oversubscription math
• shared/src/types/budgetBreakdown.ts — added budgetSourceId per line, budgetSources[] aggregate, subsidyPaybackMin/Max per source
• shared/src/index.ts — re-exports

Frontend (client/)

• client/src/components/CostBreakdownTable/CostBreakdownTable.{tsx,module.css,test.tsx} — source badges per line; source detail rows are toggleable; per-source Cost / Payback / Net columns; renders directly from server fields (client-side aggregation removed); empty-state guard relaxed to also require budgetSources.length === 0
• client/src/components/Badge/{Badge.tsx,Badge.module.css,Badge.test.tsx} — added title prop
• client/src/pages/BudgetOverviewPage/BudgetOverviewPage.{tsx,module.css,test.tsx} — 50ms debounce + AbortController on filter change, stale-while-revalidate dim, error banner with dismiss + correct dark-mode contrast
• client/src/lib/budgetOverviewApi.{ts,test.ts} — fetchBudgetBreakdown accepts deselectedSources?: string[]
• client/src/lib/budgetSourceColors.{ts,test.ts} — new helper: deterministic id → palette slot
• client/src/i18n/{en,de}/budget.json — keys: availableFundsFilter, refetchError, dismissError, source filter strings (translated to DE)
• client/src/styles/tokens.css — new --color-source-N-{bg,text,dot} family (10 slots, light + dark)

E2E (e2e/)

• e2e/tests/budget/budget-source-filter.spec.ts — new spec
• e2e/pages/BudgetOverviewPage.ts — page-object updates for source detail rows + filter affordance

Docs / Config

• wiki/ — API Contract updates for budgetSourceId, budgetSources, deselectedSources
• package-lock.json

Manual Validation Checklist

• Source badges — Open Budget Overview → Cost Breakdown. Every line shows a colored badge with the source name (or 'Unassigned' if none assigned). Each unique source has a distinct color; the same source has the same color across all rows.
• Mobile/tablet — On a narrow viewport the badge collapses to a colored dot; the source name is still announced (long-press or screen reader).
• Available Funds row — Expanding the Available Funds row shows per-source rows with Cost, Payback, and Net columns; the Net column equals totalAmount + Payback − Cost.
• Toggle filter — Click a source detail row. The row becomes muted (no left-border accent, dimmed text), aria-pressed=\"false\", and lines funded by that source disappear from the table. Sum / Remaining Budget / Available Funds caption (X of Y selected) update accordingly.
• URL persistence — After deselecting one or more sources, the URL gains ?deselectedSources=<id>[,<id>]. Reload the page → the same sources stay deselected and the filter is restored on first paint.
• Subsidy math stays consistent — When you deselect a source that has subsidy payback, the Payback column shrinks to reflect the filtered cost set; subsidy oversubscription does not appear larger than the visible cost.
• Deselect everything — Deselect all sources. The table still renders source rows (so you can re-enable them), Sum is €0.00, and the empty-state copy is NOT shown.
• Re-enable a source — Click a deselected source row → the source comes back, lines reappear, totals update.
• Keyboard — Tab to a source row, press Space or Enter to toggle. Press Escape to select all.
• Cascade pruning — Deselect every source funding a particular work item / area; the empty item and (if all its items disappear) the area are hidden. They reappear when at least one source is reselected.
• Dark mode — Toggle dark mode. Source badge colors remain readable. The error banner (force one by going offline and toggling) has readable text and a visible focus ring on the dismiss button.
• API smoke — GET /api/budget/breakdown?deselectedSources=<known-id>,unassigned returns 200; lines from those sources are absent; budgetSources[] still includes ALL configured sources; per-source subsidyPaybackMin/Max is 0 for deselected sources.

Testing

• DockerHub beta image: docker pull steilerdev/cornerstone:beta
• PR-specific image: docker pull steilerdev/cornerstone:pr-1362 (replace once PR number is assigned)

[steilerDev]

Detailed Validation

Step-by-step instructions to manually validate the headline changes. Run on the beta image (docker pull steilerdev/cornerstone:beta) or the PR-specific image once available.

1 — Source attribution (visual)

1. Open Budget Overview → expand the Cost Breakdown table → drill into one work-item line (Level 3).
2. Expect: a colored source badge sits next to the existing confidence/quoted/invoiced badges. The badge label is the source name on desktop and a colored dot on mobile (long-press / screen reader still reveals the name).
3. Confirm the same source has the same color on every line, and two different sources use distinct colors.
4. Lines without an assigned source show an 'Unassigned' badge.

2 — Available Funds row layout

1. Expand the Available Funds row (above the Sum row at the bottom of the table).
2. Expect: each configured source has its own detail row with three columns: Cost, Payback, Net.
3. Confirm Net = totalAmount + Payback − Cost for at least one source where you can mentally check the math (a small project / single-source setup is easiest).

3 — Per-source filter toggle

1. Click a source detail row.
2. Expect:
   • The row visually mutes (text muted, dot opacity 0.4, no left-border accent).
   • aria-pressed=\"false\" (verify with DevTools).
   • All lines funded by that source disappear from the table; subtotals at item / area / section level update; Sum + Remaining Budget update.
   • The (X of Y selected) caption appears in the Available Funds heading.
3. Click the row again to re-enable it. State returns to original.

4 — URL persistence

1. Deselect two named sources + 'Unassigned'.
2. Expect the URL gains ?deselectedSources=<id-a>,<id-b>,unassigned (order in the URL is not significant).
3. Hard-reload the page.
4. Expect the filter is restored on first paint — no flicker of full-table-then-filter.

5 — Subsidy oversubscription consistency

1. Pick a source you know has a subsidy attached. Note the project-wide Payback amount before filtering.
2. Deselect that source.
3. Expect: the Sum row's Payback column shrinks; oversubscription (if any) does not exceed the visible Cost. (This is the bug class that feat(budget): move per-source filter to server-side via ?deselectedSources= #1361 fixed — the previous client-side filter let Payback exceed visible Cost.)

6 — Deselect everything (former dead-end, fixed in #1360)

1. Deselect every source row, including 'Unassigned' if present.
2. Expect:
   • Source rows STILL render (so you can re-enable them).
   • Sum row reads €0.00 across Cost / Payback / Net.
   • Remaining Budget shows the project-wide availableFunds.
   • The 'no lines match' empty-state copy is NOT shown.
3. Click any source row → that source is re-enabled, its lines reappear, totals update.

7 — Keyboard

1. Tab to focus a source detail row.
2. Space or Enter toggles the source.
3. Escape selects all sources (clears the filter).
4. Confirm focus ring is visible at every step.

8 — Cascade-hide

1. Find a work item whose lines are all funded by the same source. Deselect that source.
2. Expect the work item disappears entirely. If that work item was the only one in its area, the area also disappears.
3. Re-enable the source → the item and area reappear in their original position.

9 — Dark mode

1. Toggle dark mode (system preference or app toggle).
2. Expect badge colors remain readable. No light-on-light or dark-on-dark.
3. Force a refetch error (DevTools → throttle to Offline → toggle a source). The error banner appears.
4. Expect banner text is readable in both modes (it uses --color-text-inverse on --color-bg-inverse).
5. Tab to the banner's dismiss button.
6. Expect a visible focus ring (the standard --shadow-focus outline).

10 — API smoke

curl -s 'http://<host>/api/budget/breakdown?deselectedSources=<known-id>,unassigned' | jq '
{
  filteredLineCount: (
    [
      .workItems.areas[].items[].lines[],
      .householdItems.areas[].items[].lines[]
    ] | length
  ),
  sourcesIncluded: (.budgetSources | map({id, name, subsidyPaybackMin, subsidyPaybackMax}))
}
'

Expect:

• 200 OK.
• No lines remain that reference any of the deselected source IDs (or null for unassigned).
• budgetSources[] still includes ALL configured sources (deselection does not remove them).
• For each deselected source, subsidyPaybackMin and subsidyPaybackMax are 0.
• For selected sources, subsidyPaybackMin/Max reflect the filter (pro-rata from the filtered engine run).

[steilerDev]

Superseded by #1363, which includes a small ci.yml improvement (workflow_dispatch trigger) needed to get CI to fire on beta→main promotion PRs.