Complete NextSteps roadmap: planning engine UI, calendar cluster, flexible wishes

Works through every numbered item in NextSteps260913.md section 3, plus the
three known verification issues in section 4.1.

Surface what the backend already computed:
- 3.1 render surplus_advice in PlanResults, mirroring the shortfall remedies
- 3.2 surface VacationBalance.is_assumed so assumed statutory years are visible
- 3.3 age-4 expiry given the proposed plan, via a new Age4Projection reusing
  the existing _age4_projections arithmetic (Dashboard stat verified, not rebuilt)

Calendar cluster (one pass over the holiday data):
- new GET /api/calendar/days exposing roda dagar, klamdagar and day overrides,
  paginated four years at a time
- 3.4 shade roda dagar/klamdagar, with R/K badges so colour is not the only signal
- 3.6 click-to-override behind an explicit mode toggle, leaving drag multi-select intact
- 3.7 click month/year to advance
- 3.8 per-year red-days list in Settings, statutory days plus overrides

i18n:
- 3.5 five backend-generated Swedish surfaces converted to message_key + data,
  following the tips_service pattern; old string fields replaced, not kept

Flexible wishes (3.9):
- PLANNING_ENGINE_SPEC section 10: window_mode, candidate search, cost function,
  deterministic tie-break, two-pass ordering, test matrix rows 15-24
- backend: entity, migration 006, _FULL_SCHEMA sync, repository, allocator
- frontend: season-preset toggle in WishEditor, unplaced outcome rendering

Fixes (4.1):
- pin typecheck to the local tsc rather than npx resolving a newer TypeScript
- ignore generated coverage/ and dist/ in the ESLint flat config
- fix the flaky usePlanApply test properly, with waitFor rather than a retry

Tests: backend 361 -> 404, frontend 540 -> 704. Coverage 89.47% -> 96.52% lines.

Not yet verified in a browser.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RXMhc9nT6sNz1SL4j8dznL

backend/app/entities/break_period.py

@@ -1,24 +0,0 @@
-"""Domain entity: BreakPeriod.
-
-A user-defined window the family wants to be home together (e.g. summer, winter
-holidays). Drives the parent-swap tip. Lengths and dates are entirely family-specific;
-seeded with editable defaults.
-"""
-
-from dataclasses import dataclass
-from datetime import date, datetime
-from uuid import UUID
-
-
-@dataclass
-class BreakPeriod:
-    """A user-defined window for the family to be home together."""
-
-    id: UUID
-    workspace_id: UUID
-    name: str  # 'Summer', 'Winter holidays', ...
-    start_date: date
-    end_date: date
-    target_weeks: int  # desired weeks home together for this break
-    created_at: datetime | None = None
-    updated_at: datetime | None = None

backend/app/entities/child.py

@@ -12,4 +12,7 @@ class Child:
     name: str
     birth_date: date  # use expected_birth_date (due date) if unborn
     preschool_start_date: date | None = None  # drives the preschool-day reserve tip
+    # Per-child override for annual preschool planning-day ("studiedagar") closures.
+    # Defaults to LeaveRules.preschool_planning_days_per_year (see app/config.py).
+    preschool_planning_days_per_year: int = 6
     created_at: datetime | None = None

backend/app/entities/day_override.py

@@ -0,0 +1,31 @@
+"""Domain entity: DayOverride.
+
+Workspace-scoped user correction to the calendar cache
+(`app/data/swedish_calendar.json`) / `holidays` fallback. Workplaces differ:
+some give klämdagar off, some require working julafton. A `DayOverride` lets
+a workspace say "the calendar is wrong for us on this date" in either
+direction — see `app.services.allocation_service.is_free_day`, which is the
+single place the override is applied on top of the calendar.
+"""
+
+from dataclasses import dataclass
+from datetime import date, datetime
+from uuid import UUID
+
+
+@dataclass
+class DayOverride:
+    """A single-date correction to the effective calendar for a workspace.
+
+    `is_working_day=False` means "we are off this day" (e.g. the employer
+    gives klämdagar off); `is_working_day=True` means "we must work this
+    day despite the calendar" (e.g. julafton is a normal workday here).
+    """
+
+    id: UUID
+    workspace_id: UUID
+    date: date
+    is_working_day: bool
+    note: str | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None

backend/app/entities/leave_wish.py

@@ -0,0 +1,97 @@
+"""Domain entity: LeaveWish.
+
+A family's recurring intent to be home for N weeks inside a yearly window
+(e.g. "6 weeks every summer until the child turns 4"). Renamed and extended
+from `BreakPeriod` (see PLANNING_ENGINE_SPEC.md §2.1): the old entity was
+single-year with no notion of recurrence, priority, or which parent. This is
+the input side of the planning engine's allocator (§3); the allocator itself
+is Phase B.
+
+The recurring window is stored as month/day integers (not dates) so it can
+repeat yearly without a custom SQLite type. If the window's end sorts before
+its start, it wraps into the next year — e.g. Jullov 12-20 -> 01-07.
+"""
+
+from dataclasses import dataclass
+from datetime import date, datetime
+from uuid import UUID
+
+
+@dataclass
+class LeaveWish:
+    """A family's recurring intent to be home for N weeks inside a yearly window."""
+
+    id: UUID
+    workspace_id: UUID
+    child_id: UUID | None  # None = family-wide; set = tied to that child's pools
+    name: str  # "Sommar", "Jullov"
+
+    # Recurring anchor stored as month/day ints (SQLite-friendly, no custom type).
+    window_start_month: int  # 1-12
+    window_start_day: int  # 1-31
+    window_end_month: int
+    window_end_day: int
+
+    target_weeks: int  # 6
+    recurrence: str  # 'yearly' | 'once'
+    first_year: int  # 2027
+    last_year: int | None  # None = until the child's 4th birthday
+
+    priority: int  # 1 = highest; drives best-effort fill order
+    parent_mode: str  # 'either' | 'both' | 'specific'
+    parent_personal_data_uuid: UUID | None  # required when parent_mode == 'specific'
+
+    # Per-window override of workspace planning_goal. Nullable, no UI in v1 —
+    # the field exists now so enabling it later needs no migration.
+    goal_override: str | None = None  # 'max_time' | 'max_money' | 'balanced' | None
+
+    # PLANNING_ENGINE_SPEC.md §10.1 — 'fixed' (default): window_start_*/window_end_*
+    # are the exact placement, as above. 'flexible': the SAME four fields instead
+    # describe the BOUNDING RANGE the allocator searches inside for the
+    # best-costing placement (e.g. "vår" = 03-01..05-31) — target_weeks is still
+    # the wanted duration inside that range. recurrence/first_year/last_year are
+    # unchanged, so a 'yearly' flexible wish still re-resolves its bounding range
+    # every anchor year through window_for_year()/applies_to_year() below,
+    # completely unmodified.
+    window_mode: str = "fixed"  # 'fixed' | 'flexible'
+
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+    def window_wraps(self) -> bool:
+        """Whether (end_month, end_day) sorts before (start_month, start_day).
+
+        A wrapping window (e.g. Jullov 12-20 -> 01-07) ends in the year *after*
+        the anchor year passed to `window_for_year`.
+        """
+        return (self.window_end_month, self.window_end_day) < (
+            self.window_start_month,
+            self.window_start_day,
+        )
+
+    def window_for_year(self, year: int) -> tuple[date, date]:
+        """Concrete (start_date, end_date) for this wish's window anchored at `year`.
+
+        `year` is the year the window *starts* in. If the window wraps, the
+        end date lands in `year + 1` — this also means a wrapping window spans
+        two different vacation-year budgets (see PLANNING_ENGINE_SPEC.md §3.2);
+        callers that debit vacation must account for both years separately.
+        """
+        start = date(year, self.window_start_month, self.window_start_day)
+        end_year = year + 1 if self.window_wraps() else year
+        end = date(end_year, self.window_end_month, self.window_end_day)
+        return start, end
+
+    def applies_to_year(self, year: int) -> bool:
+        """Whether this wish recurs (or occurs once) with an anchor of `year`.
+
+        `year` is compared against `first_year`/`last_year` as an *anchor*
+        year (the year the window starts in), not a calendar year the window
+        merely overlaps.
+        """
+        if year < self.first_year:
+            return False
+        if self.recurrence == "once":
+            return year == self.first_year
+        # recurrence == 'yearly'
+        return self.last_year is None or year <= self.last_year

backend/app/entities/personal_data.py

@@ -20,6 +20,12 @@ class PersonalData:
     name: str
     salary_type: str = "monthly"  # 'monthly' | 'hourly'
     employment_status: str = "employed"  # 'employed' | 'jobseeking' | 'none'
+    # Semesterlagen: minimum vacation days that must be *taken* each year;
+    # only days above this may be saved (up to 5 years). Default is the
+    # statutory 20, but employers may set a higher floor and entitlements
+    # differ per parent, so this is user-editable (see PLANNING_ENGINE_SPEC
+    # §9.2 and app.config.LeaveRules.min_vacation_days_per_year).
+    min_vacation_days_per_year: int = 20
     personnummer_enc: str | None = None  # encrypted/HMAC; prefer None
     created_at: datetime | None = field(default=None)
     deleted_at: datetime | None = field(default=None)

backend/app/entities/vacation_days.py

@@ -1,7 +1,7 @@
 """Domain entity: VacationDays.
 
 This is the REFERENCE entity — copy this shape for the other entities
-(parental_leave, planned_leave, child, break_period, ...). A domain entity is a
+(parental_leave, planned_leave, child, leave_wish, ...). A domain entity is a
 plain dataclass with no framework or persistence concerns.
 """
 

backend/app/entities/workspace.py

@@ -10,4 +10,5 @@ class Workspace:
     id: UUID
     name: str
     planning_goal: str = "balanced"  # 'max_time' | 'max_money' | 'balanced'
+    planning_mode: str = "solo"  # 'solo' | 'couple' — explicit, not inferred from member count
     created_at: datetime | None = None