left4me/docs/superpowers/specs/2026-05-16-tz-aware-datetime-handoff.md

Timezone-aware datetime migration — handoff

Follow-up artifact spawned by the timeago-shared-display work (docs/superpowers/specs/2026-05-16-timeago-shared-display-design.md). This is not an implementation plan — it is a brief for the next session to brainstorm the actual spec from evidence. Handoffs that pre-bake a plan tend to bury false premises; treat the "open questions" below as load-bearing.

Context

left4me's l4d2web package uses naive datetimes throughout the runtime because models.py declares DateTime columns without timezone=True. SQLAlchemy strips tzinfo on store (SQLite has no native TZ type) and returns naive datetimes on read. The now_utc() factory at models.py:22-23 writes aware UTC, but the DB layer collapses it back to naive on round-trip.

The pattern's cost is a defensive shell of .replace(tzinfo=None) calls sprinkled across routes and services, plus a permanent mental tax: all naive datetimes in this codebase are UTC by convention, but nothing in the type system says so. Aware-everywhere would let the defensive shell come down, the convention become explicit, and the _ensure_utc defensive line in l4d2web/l4d2web/services/timeago.py become a no-op safety net rather than load-bearing.

This was discussed during the timeago-shared-display brainstorm and deliberately scoped out to keep the diff focused. The user explicitly asked for this handoff so the work isn't forgotten.

What is currently known (evidence)

The convention is documented in code

l4d2web/l4d2web/routes/profile_routes.py:86-88 carries the canonical explanation:

# Strip tz so the marker matches what a subsequent DB read returns
# (SQLite DateTime columns don't preserve tzinfo).
user.password_changed_at = now_utc().replace(tzinfo=None)
new_marker = user.password_changed_at.isoformat()

The pw_changed_at session marker (auth.py:52, set in many routes) is compared as an ISO string, so the on-DB and on-session representations must match. Today they're both naive; an aware migration must keep both sides in sync.

Known workaround sites (definitive enumeration not done)

From a grep at the time of the timeago work:

• l4d2web/l4d2web/routes/profile_routes.py:88 — password-changed-at write
• l4d2web/l4d2web/routes/server_routes.py:210, 234 — cutoff / recent_cutoff for live-state staleness
• l4d2web/l4d2web/routes/page_routes.py:174 — cutoff for the same
• l4d2web/l4d2web/services/live_state_poller.py:37 — _now() helper returns naive UTC

The session that picks this up must re-enumerate fresh — the list above is a starting point, not an exhaustive inventory. New sites may have appeared after this handoff was written.

Column declarations to flip

l4d2web/l4d2web/models.py declares ~20 DateTime columns without timezone=True. Concrete count and list to be produced fresh during the next session — column lists drift.

What's already aware

• now_utc() (models.py:22-23) returns datetime.now(UTC)
• Most route-local time variables built via datetime.now(UTC) before the defensive .replace(tzinfo=None) is applied
• timeago.py::_ensure_utc (added in this session) handles both inputs defensively

Tests touching naive datetimes

l4d2web/tests/*.py contain ~30+ instances of datetime.now(UTC).isoformat() for the pw_changed_at session marker, and at least a few datetime.now(UTC).replace(tzinfo=None) / now - timedelta(...) patterns for fixture construction (e.g. test_servers.py:491, 535, 540). These will need to be reviewed once the production-side convention flips.

Open questions the next session must answer

These are load-bearing. Do not draft an implementation plan that assumes any particular answer.

1. SQLite + DateTime(timezone=True) round-trip behaviour in SQLAlchemy 2.x: does storing an aware UTC datetime and reading it back yield an aware UTC datetime (Python 3.13 + SQLAlchemy 2.x + pysqlite)? Or does it still strip and require a custom TypeDecorator? Spike with a throwaway test before assuming.

2. Existing data: the production SQLite DB at left4.me has rows stored as text-without-timezone (current behaviour). If the new column type changes how SQLAlchemy parses those strings on read, we may need a one-shot data migration (rewrite values to include +00:00). Verify behaviour on a copy of the production DB.

3. Alembic migrations (l4d2web/migrations/ if it exists, or wherever migrations live): do any existing migration files reference DateTime columns? If yes, do those need to be updated too? Any backfills that build datetime literals?

4. The session pw_changed_at marker round-trip is the highest-risk site. It's compared as an ISO string in auth.py:52. After the migration, both sides must produce the same ISO form (either both naive UTC or both aware UTC). Plan must spell out the marker format and where the conversion happens.

5. Comparisons crossing the boundary (DB-side aware vs Python-side naive constants, or vice versa) will raise TypeError post-migration. server_routes.py:210 (latest.last_seen_at >= cutoff) is the canonical example. Enumerate every such comparison; ensure both sides get fixed in lockstep.

6. Scope cut for tests: do the test fixtures need to flip in the same PR, or can the production code flip first and tests trail? (Likely needs to flip together — comparisons in test assertions will break if either side is mixed.)

Suggested first steps for the next session

1. Read this handoff and the parent spec (docs/superpowers/specs/2026-05-16-timeago-shared-display-design.md).
2. Re-enumerate .replace(tzinfo=None) sites: grep -rn 'replace(tzinfo=None)' l4d2web/.
3. Re-enumerate DateTime column declarations: grep -n 'mapped_column(DateTime' l4d2web/l4d2web/models.py.
4. Run the round-trip spike (open question #1) in a throwaway script or test. Document the actual behaviour observed.
5. Take a copy of the production SQLite DB; read existing datetime rows back through the candidate column definition. Document whether they parse as aware (and to what timezone) or require backfill.
6. Brainstorm scope and ordering with the user — only then write the spec.

Pointers — files to read first

• docs/superpowers/specs/2026-05-16-timeago-shared-display-design.md — parent spec, "Out of scope" + "Follow-up spec" sections.
• l4d2web/l4d2web/models.py:1-30, 22-23 — now_utc() factory, first few column declarations.
• l4d2web/l4d2web/routes/profile_routes.py:75-93 — the documented workaround comment that gave the convention its name.
• l4d2web/l4d2web/auth.py:40-60 — session marker comparison.
• l4d2web/l4d2web/services/timeago.py — _ensure_utc defensive line that becomes a no-op after the migration.

Anti-goals

• Don't bundle this with unrelated cleanup. It's a mechanical refactor when sized correctly. Adding "while I'm in there" scope grows the blast radius.
• Don't skip the round-trip spike. Believing SQLAlchemy's timezone=True "just works" on SQLite without checking is exactly the kind of false premise this handoff is shaped to prevent.
• Don't trust this handoff's enumerations as exhaustive. They are starting points from a point-in-time grep. Re-run them.