refactor(planning): remove the original decision trace
CI / policy (push) Successful in 7s
CI / validate (push) Successful in 1m15s
CI / test (push) Successful in 3m18s
CI / benchmark (push) Failing after 5m53s
CI / build (push) Successful in 1m23s
CI / security (push) Successful in 7m6s
CI / policy (pull_request) Successful in 7s
CI / validate (pull_request) Successful in 1m9s
CI / build (pull_request) Successful in 43s
CI / test (pull_request) Successful in 3m19s
CI / images (push) Successful in 3m7s
CI / required (push) Successful in 2s
CI / benchmark (pull_request) Failing after 5m28s
CI / security (pull_request) Successful in 6m37s
CI / images (pull_request) Successful in 3m18s
CI / required (pull_request) Successful in 1s

This commit is contained in:
nessar committed 2026-10-15 20:42:33 +02:00
1 parent ea4256107f
commit d9d9befa12
43 files changed
+729 -8880

No files matched your search

@@ -1,5 +1,7 @@
# Separate Plan Explanations from Calculation Traces
# Stable Plan Explanations Without Decision History
The automatic planning deadline referenced below is superseded by [ADR 0006](0006-user-selected-horizons-and-cancellable-calculations.md), implemented by issue #59. Technical callers can still opt into an explicit planning-work budget; the user flow has no automatic cutoff.
Issue #76 supersedes this ADR's original requirement to capture and deliver a complete calculation trace. The original decision trace, historical analysis, replay and candidate-history retention are removed end to end.
VacOptimizer provides a stable plan explanation separately from the complete, untruncated calculation trace captured during the same planning run; on-demand counterfactual date analysis is identified as hypothetical and never presented as trace history. Explanation and tracing must not alter the planning outcome, so trace instrumentation is excluded from the planner deadline and the result may appear before the latest run's in-memory trace finishes loading; this narrows ADR 0003's ten-second hard limit to planning work rather than end-to-end trace delivery. This accepts additional transient memory and wall-clock time instead of inventing scalar day scores, truncating history, or reconstructing a trace by replay.
The stable explanation describes the displayed plan, including valid incomplete incumbents: entitlement and rule provenance, contributions, the full ordered objective comparison and first decisive objective, time-off periods, remaining balances and concrete non-placement reasons. Invalid input and obligation conflicts retain their distinct explanations.
Outcomes are delivered before explanation work. Explanation failures cannot discard an available outcome. Immutable calculation, valid-incumbent and final-state snapshots remain available for cancellation recovery and hypothetical analysis; they are independent of tracing. ADR 0006's opt-in technical planning-work budget excludes observer callbacks and post-outcome explanation work. The user flow has no automatic elapsed-time cutoff.
@@ -1,11 +1,9 @@
# Stable Explanation, Original Trace, and Counterfactuals
# Stable Explanation and Displayed-Placement Counterfactuals
The automatic planning deadline referenced below is superseded by [ADR 0006](0006-user-selected-horizons-and-cancellable-calculations.md), implemented by issue #59. Technical callers can still opt into an explicit planning-work budget; the user flow has no automatic cutoff.
Issue #76 supersedes the original decision-trace and historical-counterfactual requirements of this ADR. Calculations no longer capture, retain or deliver decision history, and the UI has no trace explorer, replay, historical candidate statuses or balance-attempt lists.
VacOptimizer exposes one client-side calculation context. Its immutable submitted snapshot and planning outcome are independent from three explanation concerns:
VacOptimizer exposes one client-side calculation context with an immutable submitted configuration. Its outcome is independent from the stable explanation, which describes the final displayed plan and remains useful for complete and valid incumbent plans.
- the stable plan explanation is derived from the final displayed plan and remains useful for complete or incumbent plans;
- the calculation trace is captured while the producing run executes, grouped by phase and atomic decision, and may become ready after the outcome;
- counterfactual date analysis is an explicitly hypothetical operation that removes only the selected final placement, or starts from a selected trace decision's exact pre-decision state, and never rewrites the plan or historical trace.
Counterfactual date analysis tests a displayed placement over every date of the submitted half-open horizon. It uses the captured configuration and final-state snapshot, releases only that placement, preserves its entitlement, leave type and rule provenance, and fixes unrelated placements. Earned-entitlement chronology and all obligations still apply. The result is explicitly hypothetical and never mutates the displayed plan. Historical decisions are not selectable analysis baselines.
The public planning outcome is delivered as soon as planning work finishes. Trace capture and delivery have separate readiness/failure state, remain local to the latest calculation, and cannot turn a valid outcome into an explanation error. Counterfactual work is cancellable or ignored when its calculation identity is stale. The existing deterministic constraint-first planner and its planning-work deadline remain unchanged.
The public outcome is delivered as soon as planning work finishes. Explanation delivery failures cannot replace it. Counterfactual work is cancelled or ignored when its calculation identity is stale. Search breadth, allocation previews, user priorities, deterministic selection and ADR 0006's cancellation, liveness and technical-budget contracts remain unchanged. Workers finish after required outcome and explanation delivery without acknowledgement queues.
@@ -1,17 +1,19 @@
# User-Selected Horizons and Cancellable Calculations
Accepted for [issue #12](https://gitea.nessar.fr/nessar/vac-optimizer/issues/12). Fixed, saved planning horizons are implemented by [issue #57](https://gitea.nessar.fr/nessar/vac-optimizer/issues/57); user cancellation with a retained valid plan and original trace is implemented by [issue #58](https://gitea.nessar.fr/nessar/vac-optimizer/issues/58); removal of the automatic calculation deadline and heartbeat-based worker liveness are implemented by [issue #59](https://gitea.nessar.fr/nessar/vac-optimizer/issues/59). The indicative duration estimate is implemented by [issue #60](https://gitea.nessar.fr/nessar/vac-optimizer/issues/60); its initial model, session-local refinement and calendar-rendering measurement are documented in [planning-duration.md](../planning-duration.md).
Accepted for [issue #12](https://gitea.nessar.fr/nessar/vac-optimizer/issues/12). Fixed, saved planning horizons are implemented by [issue #57](https://gitea.nessar.fr/nessar/vac-optimizer/issues/57); user cancellation with a retained valid plan is implemented by [issue #58](https://gitea.nessar.fr/nessar/vac-optimizer/issues/58); removal of the automatic calculation deadline and heartbeat-based worker liveness are implemented by [issue #59](https://gitea.nessar.fr/nessar/vac-optimizer/issues/59). The indicative duration estimate is implemented by [issue #60](https://gitea.nessar.fr/nessar/vac-optimizer/issues/60); its initial model, session-local refinement and calendar-rendering measurement are documented in [planning-duration.md](../planning-duration.md).
`deadlineMs` remains an opt-in contract for technical callers: a finite non-negative planning-work budget with no ten-second cap. An omitted value is unlimited. It starts after calendar preparation and excludes trace capture, observer callbacks, and post-outcome artifact work. The calendar and benchmark omit it. A one-second worker heartbeat renews the coordinator's thirty-second inactivity timer during cooperative preparation and search; total elapsed time never triggers that timer while activity continues. Worker errors and unavailable execution retain their explicit outcomes, and monitoring ends when the outcome arrives so delayed trace delivery cannot invalidate it.
`deadlineMs` remains an opt-in contract for technical callers: a finite non-negative planning-work budget with no ten-second cap. An omitted value is unlimited. It starts after calendar preparation and excludes observer callbacks and post-outcome explanation work. The calendar and benchmark omit it. A one-second worker heartbeat renews the coordinator's thirty-second inactivity timer during cooperative preparation and search; total elapsed time never triggers that timer while activity continues. Worker errors and unavailable execution retain their explicit outcomes, and monitoring ends when the outcome arrives so delayed explanation delivery cannot invalidate it.
VacOptimizer accepts explicitly selected, fixed planning horizons whose start may be past and whose duration may exceed twelve months, retaining today through the same date twelve months later as the default. Calculations remain in the browser and run to completion without an automatic elapsed-time cutoff, with an indicative duration estimate and an explicit Cancel action; this accepts variable waiting time and resource use to make longer horizons usable without silently changing the user's dates. This supersedes ADR 0003's ten-second automatic planning limit and its retention in both ADR 0004 documents, while preserving the separation between the planning outcome, stable explanation, and original trace.
VacOptimizer accepts explicitly selected, fixed planning horizons whose start may be past and whose duration may exceed twelve months, retaining today through the same date twelve months later as the default. Calculations remain in the browser and run to completion without an automatic elapsed-time cutoff, with an indicative duration estimate and an explicit Cancel action; this accepts variable waiting time and resource use to make longer horizons usable without silently changing the user's dates. This supersedes ADR 0003's ten-second automatic planning limit and its retention in both ADR 0004 documents, while preserving the separation between the planning outcome and stable explanation.
The planning-period control in Configure your leave uses an inclusive last planning date. The planner retains its half-open horizon by using the following calendar date as its exclusive end, matching the inclusive date-selection convention of TIME_WINDOW rules.
Editing the horizon does not trigger a calculation. The user can adjust dates, balances, and rules before using the existing Calculate action; until a new calculation is requested, the displayed calendar retains its preceding outcome and horizon.
A successful calculation displays the calendar once, as soon as the full planning objective order is complete, without displaying intermediate plans during optimization. Trace delivery continues in the background and never delays or changes that final calendar. The indicative duration estimate covers elapsed time until the final calendar is usable, including any trace capture that delays the outcome, rather than the additional time to deliver the complete trace.
A successful calculation displays the calendar once, as soon as the full planning objective order is complete, without displaying intermediate plans during optimization. Stable explanation delivery follows the outcome and never changes that final calendar. The indicative duration estimate covers elapsed time until the final calendar is usable, excluding later explanation work.
Before Calculate, the estimate is shown as an approximate range in seconds or minutes based on the horizon, balances, and rules. It starts with a rough estimate and is refined using measured calculation durations on the same device; it never becomes an automatic stopping deadline.
User cancellation during optimization preserves the best valid plan already found and labels it as a cancelled, incomplete calculation. Before any valid plan exists, cancellation reports that the calculation was cancelled without presenting a plan or claiming an obligation conflict.
Issue #76 supersedes all original-trace requirements in this ADR and both ADR 0004 documents. Decision capture, historical analysis and replay are removed. Immutable calculation, valid-incumbent and final-state snapshots remain for the retained explanation, cancellation recovery and displayed-placement counterfactuals. Cancellation still preserves the best available jointly valid plan and never implies an obligation conflict.