feat: add functionality for declaring non-working days and their impact on leave balances

CONTEXT.md

@@ -1,6 +1,6 @@
 # Personal Leave Planning
 
-VacOptimizer helps one person turn expiring leave balances into a leave plan across a planning horizon. It combines leave placements with weekends, French public holidays, and ordered planning rules, then reports the resulting time-off periods and any unplaced balances.
+VacOptimizer helps one person turn expiring leave balances into a leave plan across a planning horizon. It combines leave placements with declared non-working days, weekends, French public holidays, and ordered planning rules, then reports the resulting time-off periods and any unplaced balances.
 
 ## Language
 
@@ -8,7 +8,7 @@ VacOptimizer helps one person turn expiring leave balances into a leave plan acr
 A quantity of leave granted by a company or generated by an applicable planning rule, with an availability date and an expiry date.
 
 **Leave balance**:
-The unspent quantity of a leave entitlement, identified by leave type, availability date, and expiry date.
+The unspent quantity of a leave entitlement, identified by leave type, availability date, and expiry date. Reported balances are assumed current on the calculation's Europe/Paris calendar date, with booked leave already deducted and earned entitlements available by that date already included.
 _Avoid_: vacation day, VacDay
 
 **At-risk balance**:
@@ -21,7 +21,7 @@ Leave whose expiry date precedes the planning horizon and therefore cannot be sa
 The unspent portion of a leave balance that expires after the planning horizon. It needs no ordinary placement in the current plan but remains available to explicit planning rules and supporting placements.
 
 **Leave type**:
-The category of leave in a balance: CP (paid leave), RTT (working-time reduction leave), or Other (a user-managed catch-all).
+The category of leave in a balance or on a declared non-working day: CP (paid leave), RTT (working-time reduction leave), or Other (a user-managed catch-all, including any other reason for not working).
 _Avoid_: ANY as a leave type; `ANY` is only a rule selector.
 
 **Planning horizon**:
@@ -32,13 +32,16 @@ The inclusive final calendar date selected by the user for leave placement; the
 _Avoid_: horizon end
 
 **Working day**:
-A Monday-to-Friday calendar date that is not a French national public holiday. Only working days can receive leave placements.
+A Monday-to-Friday calendar date that is not a French national public holiday. New leave placements are restricted to working days that have not been declared non-working.
+
+**Declared non-working day**:
+A working day on which the user declares they will not work, identified by a CP, RTT, or Other leave type. Its date and type are fixed during planning; it consumes no remaining leave balance and contributes to compatible planning rules.
 
 **Public holiday**:
 A French calendar date that cannot receive a leave placement and contributes to a time-off period.
 
 **Public-holiday week**:
-A Monday-to-Friday window containing a weekday French public holiday where every other working day is a leave placement.
+A Monday-to-Friday window containing a weekday French public holiday where every other working day is a leave placement or declared non-working day.
 
 **Public-holiday week value**:
 The distance of every weekday holiday from the nearest weekend, summed within and across completed public-holiday weeks: Monday or Friday is 1, Tuesday or Thursday is 2, and Wednesday is 3.
@@ -50,7 +53,7 @@ Using one or more working days from a leave balance on specific dates within the
 A leave placement from a deferred balance that completes a public-holiday week, captures additional adjacent non-working dates, eliminates a short work sequence, or reduces the longest work sequence. Merely extending an existing period by the placed day itself is not sufficient.
 
 **Time-off period**:
-A contiguous period containing at least one leave placement together with any adjacent weekends and public holidays, including those immediately outside the planning horizon.
+A contiguous period containing at least one leave placement or declared non-working day, together with any adjacent non-working dates, including those immediately outside the planning horizon.
 
 **Time-off duration**:
 The number of distinct calendar dates covered by all planned time-off periods.
@@ -80,13 +83,13 @@ A planning rule evaluated independently for every French public holiday on its c
 `before` and `after` fix every requested day on one side; `around` considers every split with at least one day on each side; `auto` considers every split, including the all-before and all-after extremes.
 
 **TIME_WINDOW rule**:
-A planning rule targeting working days in an inclusive date window. A preference requests up to its configured quantity; an obligation requires exactly that quantity.
+A planning rule counting compatible leave placements and declared non-working days in an inclusive date window. A preference requests up to its configured quantity; an obligation requires exactly that quantity.
 
 **Rule priority**:
 The user-defined lexicographic order of preference rules. Each earlier preference is satisfied as far as possible before a later preference is considered.
 
 **Rule satisfaction**:
-The relationship in which a plan fulfils a planning rule. One compatible leave placement may contribute to the satisfaction of multiple rules.
+The relationship in which a plan fulfils a planning rule. One compatible leave placement or declared non-working day may contribute to the satisfaction of multiple rules.
 
 **Placement provenance**:
 The consumed leave entitlement and every planning rule satisfied by a leave placement.
@@ -142,11 +145,11 @@ A calculation stopped by user cancellation or another interruption before it com
 The lexicographic quality order applied after joint obligation feasibility: minimize unplaced at-risk leave; satisfy each preference in user order; maximize public-holiday week value; maximize non-working-day gain; minimize the longest work sequence; minimize the total deficit of internal work sequences shorter than five days; minimize supporting placements; consume earlier-expiring balances; then prefer earlier placement dates. Complete holiday weeks therefore precede broader calendar-gain and work-sequence optimization. A lower criterion never degrades a higher one.
 
 **Earned leave entitlement**:
-A leave entitlement created for each completed occurrence of an applicable planning rule after its generating time-off period ends. It becomes available the following day, expires one year later, and may fund any later compatible placement.
+A leave entitlement earned for each completed occurrence of an applicable planning rule after its generating time-off period ends, whether that occurrence is fulfilled by leave placements, declared non-working days, or both. It becomes available the following day, expires one year later, and may fund later compatible placements; only entitlements becoming available after the calculation's Europe/Paris calendar date are added to the plan.
 _Avoid_: reward, bonus days
 
 **Optimization result**:
-A valid deterministic plan produced after completing the planning objective order, containing leave placements and their provenance, time-off periods, unsatisfied preference reasons, and remaining balances with reasons. It does not claim mathematical global optimality.
+A valid deterministic plan produced after completing the planning objective order, containing declared non-working days, leave placements and their provenance, time-off periods, unsatisfied preference reasons, and remaining balances with reasons. It does not claim mathematical global optimality.
 
 **Remaining balance**:
 Any quantity left unspent by the optimization result, reported as unavoidable expiry, an unplaced at-risk balance, or a deferred balance.