Pitwall — Calculation & Math Alignment

Pace ratio & label — evaluatePace ✓ verified

Goal: answer "are you spending this window faster or slower than a straight, even burn?" — and turn that into an actionable label.

elapsedFraction         = (now − windowStart) / (resetAt − windowStart)
expectedUtilizationPct  = elapsedFraction × 100      // even-burn reference line
paceRatio               = utilizationPercent / expectedUtilizationPct

Suppression gates (return .notEnoughWindow instead of a noisy early/late read): weekly window ignores the first 6 h and last 1 h; session window ignores the first 15 min and last 5 min.

Label buckets on paceRatio (utilization ≥ 100 short-circuits to capped):

Verified: ranges are contiguous with no gaps/overlaps; boundaries inclusive on the lower (calmer) side. Matches PacingCalculatorTests exactly (e.g. day 4 of 7 at 60% → ratio 1.05 → onPace; 101% → capped). Gate edges pinned by tests at ±1 s.

Projected weekly maximum — projectedWeeklyMax ✓ verified

Goal: "if you keep the current average pace, what % of the weekly limit will you reach by reset?"

projectedWeeklyMaxPercent = paceRatio × 100
                          = utilizationPercent / elapsedFraction   // linear extrapolation

Verified: ratio 1.0 → 100%, 1.5 → 150%, 0.72 → 72% (tests). It is a straight-line projection of the window-average rate — intentionally not an instantaneous burn rate. Sensitive early in a window, which the 6 h gate mitigates.

Daily budget — dailyBudget ✓ verified

Goal: spread the remaining weekly allowance evenly across the days left, so you finish exactly at the reset.

remainingUtilizationPercent = max(0, 100 − weeklyUtilizationPercent)
daysRemaining               = max( (resetAt − now) / 86 400 ,  1/24 )   // floored at 1 hour
dailyBudgetPercent          = remainingUtilizationPercent / daysRemaining

Verified: 70% used with 36 h left → 30% / 1.5 d = 20%/day (test). The 1/24 floor prevents divide-by-zero and the blow-up when resetAt ≈ now or is already past (a past reset → "burn it now" signal, finite).

Today's usage baseline — todayUsage / snapshotsInCurrentWeeklyWindow ✓ verified

Goal: estimate "how much of the weekly counter did today consume" by diffing the live weekly % against the best baseline snapshot.

• Exact — last snapshot recorded before local midnight: delta = max(0, weeklyNow − baseline).
• Estimated — no pre-midnight snapshot, but one exists within a 2 h grace after midnight (and ≤ now): diff against it.
• Reset-aware — snapshots taken before a weekly reset (detected as any snapshot whose weekly % is higher than the current %) are dropped, so a counter that restarted mid-day doesn't poison the baseline.
• Unknown — no usable baseline (e.g. only a snapshot from after the 2 h grace) → no delta shown.

Verified: six dedicated tests in DailyBudgetTests cover the pre-midnight pick, the 2 h grace, rejection of a late same-day snapshot, and the mid-day-reset case (pre-reset 96% snapshot correctly ignored).

Window tiling & per-slice target — slices / evenDivisionSlices ✓ verified

Goal: lay the provider's repeating window onto the local day [dayStart, dayEnd] and give each visible slice a fair share of the day's target, proportional to how much of the slice falls inside today.

targetPercent(slice) = dailyTargetPercent × (displayEnd − displayStart) / dayDuration
observedActual(slice) = max(0, endWeekly − startWeekly)   // diff of bracketing history snapshots

Each slice is classified past / current / future × observed / unobserved, with an availability reason (waiting for first usage, offline, before Pitwall started, …) so the UI can explain gaps honestly.

Verified: windows tile backward from the current reset to cover the whole day; target weights sum to the day's target; the max(0, …) on the observed diff guards a snapshot ordering glitch. window(containing:) correctly snaps any instant into its [start, end) bracket.

Rebalance after observed usage — rebalanceTargets ✓ verified

Goal: once part of the day is spent, re-spread only the remaining day-budget across the slices you can still influence (current + future), so the targets you're shown reflect what's actually left.

remainingPaceBudget = dailyTargetPercent
                      − Σ observedActuals(past+current observed)
                      − Σ reservedTargets(past unobserved)        // keep their fair share parked
target(adjustable i) = remainingPaceBudget × duration(i) / Σ duration(adjustable)

Reset-scoped exclusion: slices whose displayEnd ≤ activeWeeklyResetAt are dropped from both sums, so usage and targets from before a mid-day weekly reset don't count against the post-reset day budget.

Verified: activeWeeklyResetAt is supplied by dailyPaceResetBoundary, which only ever returns a reset that is in the past and inside today (explicit, from the reset field, or inferred from a drop in the weekly counter previous > next + 0.1). So the ≤ comparison is semantically correct. If the day is overspent, remainingPaceBudget goes negative and downstream slices correctly turn red.

Rebalance policy — dailySessionRebalancePolicy ✓ verified

Goal: decide whether to keep the original fair per-slice targets or rebalance. If the week is at or under its straight-line trajectory you've earned slack, so keep fair targets; otherwise rebalance toward catch-up.

expectedWeeklyByNow = weeklyFinishTrajectoryPercent(at: now)
policy = weeklyUtilization ≤ expectedWeeklyByNow ? preserveFairTargets : rebalanceAfterObservedUsage

Verified: equality favours the calmer preserveFairTargets; Claude/Codex only.

Weekly-finish trajectory target — weeklyFinishDailyTarget / weeklyFinishTrajectoryPercent ✓ verified

Goal: instead of "spread the remainder evenly," anchor to a fixed straight line that hits exactly 100% at the weekly reset, and hand today the segment of that line still owed — adjusted for where you actually started the day.

trajectory(at t)   = clamp((t − weeklyStart) / (weeklyReset − weeklyStart), 0…1) × 100
targetAtDayEnd     = trajectory( min(nextMidnight, weeklyReset) )

// when weekly% and today's usage are both known:
dayStartUtil       = max(0, weeklyUtilization − todayUsage)
dailyTarget        = max(0, targetAtDayEnd − dayStartUtil)

// otherwise (no live today figure):
dailyTarget        = max(0, targetAtDayEnd − trajectory(dayStart))

Verified well-formed: because dayStartUtil + dailyTarget = targetAtDayEnd ≤ 100, hitting the target lands end-of-day weekly exactly on the finish line and never projects past 100%. On the final partial day, dayEnd clamps to weeklyReset so the target becomes "all remaining." Differs from dailyBudgetPercent by design (fixed finish line vs. flat-remainder) — this is the intended product behaviour, not a discrepancy.

In-day reset boundary — dailyPaceResetBoundary ✓ verified

Goal: find a weekly reset that happened within today's visible strip so the UI can draw a marker and the rebalancer can scope to the post-reset window.

• Exact — a recorded weeklyResetAt inside (visibleStart, visibleEnd), ≤ now, bracketed by snapshots.
• Inferred — a consecutive pair of observations where the weekly % drops (previous > next + 0.1) inside the strip; the drop time is the reset.

Verified: all branches require the boundary to be ≤ now and within today, which is exactly the precondition the rebalancer's ≤ activeWeeklyResetAt exclusion relies on.

Codex midnight-crossing target — sessionAwareDailyTarget ℹ context

Goal: when a Codex session window straddles local midnight, count "today" as a partial extra day so the daily target isn't overstated.

inclusiveDaysRemaining = max(1, floor(daysRemaining) + (crossesMidnight ? 0.8 : 1))
target                 = remainingUtilizationPercent / inclusiveDaysRemaining

Note: the 0.8 partial-day weight is a deliberate heuristic, not a derived constant. Arithmetic is sound (floored at 1 day → no divide-by-zero). Only engages for Codex with remaining budget > 0.

Weekly-limit forecast — WeeklyLimitForecastText.capTime ✓ verified ⚠ see F2

Goal: if the projected max exceeds 100%, estimate when the weekly limit is hit, assuming the window-average pace continues.

projectedFutureUse = projectedWeeklyMaxPercent − weeklyUtilization
burnRatePerSecond  = projectedFutureUse / remainingWindowSeconds
secondsToCap       = (100 − weeklyUtilization) / burnRatePerSecond
capTime            = now + min(secondsToCap, remainingWindowSeconds)   // only when projected > 100

Verified internally consistent: substituting the definitions gives secondsToCap = remainingWindow × (100 − util)/(projected − util), which is always < remainingWindow when projected > 100 — the min() is a safety clamp, and all guards check finiteness/positivity. See finding F2: the alternate branch that would read a pre-computed projectedCapTime is never exercised in production because that field is never populated.

Per-segment color signal — dailySegmentSignal (ratio scale) ✓ verified

Goal: color a slice by how its actual usage compares to its (rebalanced) target as a ratio, so small targets aren't washed out.

Edge guards: expected < 0 → critical (overdrawn); |expected| < 0.05 (≈ zero target) → critical if any usage else onTrack; this keeps the color agreeing with what the "0%" rounding will display.

Verified: buckets are complete & non-overlapping on [0, ∞); the five signalColor RGB values match the palette hexes exactly (purple #9459fa, green #299e4f, yellow #e6b31f, orange #f57a1f, red #e0292e). Worked examples in the alignment doc reproduce.

Absolute-delta signal — paceSignal & raw-utilization fallback — sessionSignal/weeklySignal ⚠ see F3 / F4

Goal: the older band used for the aggregate Daily roll-up and for Session/Weekly rows when no pace target exists.

// paceSignal — absolute percentage-point delta
delta = actual − expected → >12 red · >6 orange · [−6, +6] purple · <−6 green

// sessionSignal — no target, color by raw utilization
≥100 limitHit · ≥80 red · ≥60 orange · [1, 60) purple · <1 unknown

Verified contiguous, but see findings F3 (two copies of paceSignal differ in their near-zero handling) and F4 (the aggregate Daily dot uses this absolute band while the chips use the ratio scale — they can disagree for small targets). The 60/80 session cutoffs are heuristics, not doc-governed.

"% left" & percent formatting ✓ verified ⚠ see F5

Goal: turn a utilization % into remaining headroom and format it cleanly.

headroom = 100 − utilizationPercent
formatPercent(v): show "N%" when within 0.05 of an integer, else one decimal "N.N%"

Verified for normal 0–100 inputs. Codex/Gemini clamp utilization upstream so headroom can't go negative; the Claude path does not (finding F5). Three slightly different "small but non-zero" labels exist (<1% at a 0.5 cutoff, <0.1% at a 0.1 cutoff) — cosmetic.