C.W.K.
Stream
More →
Lesson 01 of 05 · published

The Completed-Close Baseline

~12 min · correctness, baseline, day-change, subtle-bug

Level 0Open Gate
0 XP0/36 lessons0/12 achievements
0/100 XP to next level100 XP to go0% complete
"'Change today' sounds obvious until you ask: change since when, exactly? Get the 'when' wrong and every green and red number is a small lie."

The innocent-looking number

Every portfolio app shows a "day change" — how much a position moved today. It looks trivial: current price minus previous close. But hidden inside "previous close" is a question that, answered carelessly, silently corrupts the number: which close? Keep answers it precisely: a live tick is always measured against the most recent completed close. Not "yesterday's close" by reflex — the most recent close that is actually finished and durable.

Why naive prev_close is wrong

Here's the trap. Suppose your stored daily row was last refreshed after Monday's session, holding Monday's close. Now it's Tuesday, mid-session, and a live tick arrives. If you compute change as tick - stored_prev_close, you might be subtracting a value from two sessions ago instead of one — because your stored "previous" close depends on when the row was last written, not on what "previous" should mean relative to today. The result: a two-session move gets labelled as a single day's change. On a volatile stretch, that's not a rounding error — it's a number that's confidently, visibly wrong.

A delta is only as correct as the baseline it's measured from. 'Change' is never a property of a single number — it's a relationship between a value and a chosen reference point. Pin the reference point wrong and the delta is wrong, no matter how precise the current value is. Always ask 'change relative to exactly what?' before trusting a difference.

How Keep resolves the right baseline

The rule has two branches. If the durable stored row's date equals the live tick's date — the row already covers today — then the correct baseline is the previous close (yesterday's), because today's row is the current session. If the stored row's date is earlier — the row was refreshed after an earlier session and hasn't caught up to today — then the stored last close is the right baseline. One small conditional, and the day change means exactly what it claims. And critically, the frontend mirrors this exact logic, so the browser never computes a different baseline than the server.

Don't 'simplify' this back to raw prev_close. A future reader will look at the two-branch baseline logic, think it's needlessly complex, and 'clean it up' to always use the stored previous close. That reintroduces the exact two-session bug. The complexity is load-bearing — it's the difference between a Day change that's true and one that's plausibly wrong. Comment it, and resist the urge to flatten it.
Two implementations, one truth. Because both the server and the browser compute a baseline, they must agree — so the frontend's baseline logic deliberately mirrors the backend's. When the same rule lives in two places, the danger is drift; here it's managed by making the mirror explicit and intentional, not by hoping two people keep them in sync by memory.

Code

The most-recent-completed-close rule (illustrative)·python
def completed_close(stored_row, live_tick_date):
    # If the durable row already covers the live day, the right
    # baseline is the PREVIOUS close (today's row is the live session).
    if stored_row.data_date == live_tick_date:
        return stored_row.prev_close
    # Otherwise the row was refreshed after an earlier session and
    # hasn't caught up to today: its last close IS the baseline.
    return stored_row.last_close

def day_change(live_tick, stored_row):
    base = completed_close(stored_row, live_tick.date)
    return live_tick.value - base   # a delta whose 'since when' is correct

External links

Exercise

Find a 'change since X' number in something you've built (steps today, spend this month, growth since last check). Write down exactly what the baseline is and how it's determined. Now construct the case where the baseline silently points at the wrong reference (a stale stored value, a timezone boundary, a missed refresh) and the delta becomes wrong while the current value is perfectly correct. What conditional fixes it?
Hint
The bug is never in the current value — it's always in the baseline. Ask: 'could my reference point be from a different period than I assume?' Stored 'previous' values are the usual culprit, because 'previous' quietly means 'whenever this row was last written,' not 'the period before now.'

Progress

Progress is local-only — sign in to sync across devices.
← 🛂 Provider BoundariesQuiz · 4 questionsNext →Live Ticks Expire
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign in — Please sign in to comment.

No comments yet — be the first.