red-team-temporal

name

red-team-temporal

description

Adversarial review of TIME — instants, calendar dates, zones, DST, precision and ordering — across this repo's store, wire and run planes; hunts the defect that never throws (a plausible-looking wrong moment) and reports it only with the input that produces it. Report-only, diagnoses without fixing. Use after any change that stores, converts, formats, compares, groups by or measures time, or when asked to "red team the time handling", "check the timezone", "is this DST-safe", "why is this on the wrong day", "audit the timestamps", "check the date bucketing".

red-team-temporal — the wrong moment, demonstrated

An OPTIONAL tool, not a checkpoint. Diagnoses only; folding a finding into the code is the next increment, not part of the review.

Why this exists

A temporal defect does not throw and does not look wrong. It returns a date, a timestamp, a duration — well-formed, in range, and plausible to anyone who does not already know the answer. Nothing reddens: the type is satisfied and the assertion compares the code against itself. Spot checks pass, because most instants are nowhere near a boundary. And the error is conditional — on the hour, the zone, the host — so the same code is right on a laptop at noon and wrong on a server at 8pm.

The one idea

A wrong time is a plausible time. So a temporal finding is worth nothing until it produces the wrong value.

"This might be off by a day" is an opinion. "This returns 2026-08-13 while the server's day was 2026-08-14" is a finding. Every check has an input that demonstrates it; prefer the version that runs.

Find the boundary, then stand on it. Every temporal defect lives on one — midnight, a DST transition, a year end, the edge of a page. Ordinary inputs prove nothing. Pick an input on the edge, and one each side.

Where time lives here

Plane	What it holds	Decided in
Store	timestamptz instants; analytics.mart_*.day and digests.week_start as UTC date	migrations 0001/0005/0006, pipeline/defs/marts.py
Wire	/query timeDimension as calendar dates in the analytics zone; instants as ISO-Z; annotations.timezone	query.sql.ts, query/timezone.ts, core/time.ts
Run	ingest mtimes, focus-time interval merge, request histograms	scanner.service.ts, alg/intervals.ts, common/metrics/

Three calendars are in play — the analytics zone (ANALYTICS_TZ, published at GET /metadata/features), UTC (marts, digest storage), and the browser's (display only, and only for instants). Every defect found here on 2026-08-13 lived on a seam between two of them, never inside one component.

How it runs — four passes

1. Read. Every site in the changed area that stores, parses, formats, compares, groups by or measures time. List the conversions, and the rules the code states in prose. A stated rule with nothing enforcing it is a finding.
2. Baseline. Run the suite once, unchanged, and record what fails. Not padding: without it every unrelated flake reads as a temporal finding.
3. Probe zones. pnpm tz-matrix [--filter <pkg>] — five hostile zones with the baseline subtracted, so only NEW failures are reported. A test that reddens under a hostile TZ and not at baseline is the strongest finding this skill can produce: it demonstrates that something consulted the host.
4. Probe values. Run each conversion against the specimens in temporal-defects.md and compare with a value computed OUTSIDE the code — by hand, or from a published transition date. Show the input, what came back, and the right answer.

If passes 3–4 cannot run here, say so and mark every finding UNVERIFIED. Never present a read-only opinion as a demonstration.

Classes, specimens, engine facts

temporal-defects.md — 25 defect classes (those marked † were found in this repo), the specimen inputs, and the engine behaviours to confirm rather than assume.

NOT findings

• a preference for a different date library, or for Temporal over Date
• "this could be clearer" with no wrong value behind it
• a hazard already refused, guarded or tested — check first, then say so
• a failure that also appears in the BASELINE run
• anything undemonstrated, unless clearly marked UNVERIFIED

Output

300–600 words, worst first. Per finding: file:line; one sentence naming the defect; the DEMONSTRATION (the input, what came back, the right answer — or the hostile-zone run that failed while the baseline passed); one sentence on which instant, zone or host makes it bite, and how often.

Reporting is unconditional. Emit a report however the run ends, and state COVERAGE: what was examined, what was read but not executed, and what was not reached, with the reason. Finding nothing is a result — name what was searched, so a real absence can be told from a lazy one.

Cleanup

Read-only. No git write commands. Never change the host's clock or system zone — TZ= on a single command is the whole mechanism, and a probe that sets a global zone leaves a machine somebody else has to fix. Findings go inline, not into a committed file.