Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

fix(frontend): match the member, and say what the rule is worth

zchpeterc089f03a65e7
diff --git a/docs/design/timestamp-display.md b/docs/design/timestamp-display.md
index 82a06ce8ef..6d4f6334ff 100644
--- a/docs/design/timestamp-display.md
+++ b/docs/design/timestamp-display.md
@@ -284,29 +284,36 @@ no seconds per D5. Relative age may accompany it in the tooltip.
its value — which can see a change the value just missed and schedule the one after — are
none of them reachable through the hook. What the hook cannot prevent is a display reaching
past it: a reading's `read` is public so readings can compose, and the hook's parameter is
- structurally typed. A Biome plugin holds that line — `read` and `nextChangeAt` may be called
- only inside the modules that define the readings.
- - **The shared clock accepts any instant.** Deadlines are wall-clock instants but timers skip
- time the machine sleeps, so the clock re-checks at least once a minute: a display is at most
- a minute behind after sleep or a clock adjustment. A boundary is only valid on a clock at
- least as late as the one it was computed on, so a clock stepped backward wakes every
- subscribed display at the next check. The evidence of a step is the highest clock reading the
- clock has seen, not the last one taken: arming happens on any commit, so a display mounting
- between the step and the next check would otherwise erase it. The detector's blind spot is a
- step smaller than the time since the clock last armed, which is safe because it self-tunes:
- a display that changes by the second arms often, shrinking exactly the window it needs, and a
- step too small for that window is also too small to change a reading that counts in minutes
- or days. A reading that has settled for
- good holds no subscription, so a clock stepped back past its last change leaves it as it was
- until something else renders it — the price of settled displays costing nothing. The clock
- wakes only the subscribers that are due, re-checks a woken display that names the same instant
- again after a resync interval rather than on every other display's wake, and leaves a short
- gap after each wake so a boundary that keeps naming
- a past instant cannot spin it.
- - **An absent timestamp has no reading.** The conversion yields nothing rather than a
+ structurally typed. A Biome plugin narrows that line rather than closing it: outside the
+ modules that define the readings, it rejects every mention of `read` or `nextChangeAt` as a
+ member or a destructured binding — under an alias, through a local, through a table, through
+ `.call`, passed as a callback, optionally chained, or keyed by a literal. What it cannot see
+ is a key held in a variable, which is not a spelling anyone reaches for by accident. The rule
+ is the convention; the plugin is what makes drifting off it loud.
+ - **The shared clock accepts any instant.** Deadlines are wall-clock instants but timers skip time
+ the machine sleeps, so the clock re-checks at least once a minute: a display is at most a
+ minute behind after sleep or a clock adjustment. A boundary is only valid on a clock at least
+ as late as the one it was computed on, so a clock stepped backward wakes every subscribed
+ display at the next check. The evidence of a step is the highest clock reading the clock has
+ seen, not the last one taken: arming happens on any commit, so a display mounting between the
+ step and the next check would otherwise erase it. The detector's blind spot is a step smaller
+ than the time since the clock last armed, which is safe because it self-tunes: a display that
+ changes by the second arms often, shrinking exactly the window it needs, and a step too small
+ for that window is also too small to change a reading that counts in minutes or days. A
+ reading that has settled for good holds no subscription, so a clock stepped back past its last
+ change leaves it as it was until something else renders it — the price of settled displays
+ costing nothing. A step wakes a display without consuming what it declared: the instant is
+ absolute, so it survives the step and still gets its own wake, and only a display the clock
+ finds due retires its deadline. A woken display that names the same instant again is
+ re-checked after a resync interval rather than on every other display's wake, and a short gap
+ after each wake keeps a boundary that keeps naming a past instant from spinning it.
+ - **An absent timestamp has no reading**, and neither has a value that is not an instant: a
+ number that is not finite, or one beyond the range a time value can occupy, which `Date` holds
+ no time for and the date formatters throw on. The conversion yields nothing rather than a
substitute — the current time and the epoch are both plausible-looking lies — and the
container picks the empty form: "-" in a table cell, or the label dropped along with its
- separator in an inline line.
+ separator in an inline line. The domain lives with the formatters, since they are what
+ rejects a value; a display asks them rather than guessing at the test.
- Guarded by fake-timer tests and a sweep of render-time `Date.now()` over the touched surfaces
at implementation time — a review pass, not a lint: telling render scope from handlers and
effects statically would flag most legitimate uses.
diff --git a/frontend/biome-plugins/time-reading-through-hook.grit b/frontend/biome-plugins/time-reading-through-hook.grit
index f60358a15d..3939cf47d8 100644
--- a/frontend/biome-plugins/time-reading-through-hook.grit
+++ b/frontend/biome-plugins/time-reading-through-hook.grit
@@ -1,16 +1,33 @@
// A value that changes with time must be read through `useTimeReading`, which
// pairs it with its own boundary and subscribes it to the shared clock. Reading
// one directly renders a label that never updates -- the staleness bug
-// docs/design/timestamp-display.md exists to prevent. The readings compose each
-// other inside utils/datetime.ts and utils/accessGrant.ts, which this rule
-// excludes.
+// docs/design/timestamp-display.md exists to prevent.
+//
+// The rule is about the member, not the name it is reached through, so this
+// matches `read` and `nextChangeAt` wherever they are named: under an alias,
+// through a local or a table, via `.call`, passed as a callback, optionally
+// chained, keyed by a literal, or destructured. A key held in a variable is
+// the one spelling left, and nobody reaches for it by accident.
+//
+// The modules that define readings compose and build them, so biome.json
+// excludes utils/datetime.ts, utils/accessGrant.ts, and the hook itself.
language js
-js"$reading.$member($args)" as $call where {
- $reading <: r"[A-Za-z]+Reading",
- or { $member <: `read`, $member <: `nextChangeAt` },
+pattern reached_past_the_hook() {
+ or {
+ js"$object.$member" where { or { $member <: `read`, $member <: `nextChangeAt` } },
+ js"$object?.read",
+ js"$object?.nextChangeAt",
+ js"{ read: $binding }",
+ js"{ nextChangeAt: $binding }",
+ js"{ $properties }" where { $properties <: contains or { `read`, `nextChangeAt` } },
+ js"$object[$key]" where { or { $key <: `"read"`, $key <: `"nextChangeAt"` } }
+ }
+}
+
+reached_past_the_hook() as $access where {
register_diagnostic(
- span=$call,
+ span=$access,
message="Read a time-varying value through useTimeReading(reading, input), which subscribes it to the shared clock."
)
}
diff --git a/frontend/src/hooks/useTimeReading.ts b/frontend/src/hooks/useTimeReading.ts
index 1c51b2766a..70616e1e99 100644
--- a/frontend/src/hooks/useTimeReading.ts
+++ b/frontend/src/hooks/useTimeReading.ts
@@ -5,11 +5,13 @@ import type { TimeReading } from "@/utils/datetime";
* A single clock shared by every time-varying display.
*
* Each subscriber declares the instant its rendering next changes, so the clock
- * holds one timeout, set for the earliest of those, and wakes only the
- * subscribers that are due. A due subscriber normally re-renders and declares
- * its next instant; one that names the same instant again -- a boundary held
- * stale, say -- is re-checked after a resync interval rather than on every
- * neighbour's wake.
+ * holds one timeout, set for the earliest of those, and wakes the subscribers
+ * that are due -- and every subscriber when the wall clock has stepped back,
+ * since a step invalidates what they show. Only a due subscriber retires the
+ * instant it declared: that instant is absolute, so a step leaves it standing.
+ * A due subscriber normally re-renders and declares its next instant; one that
+ * names the same instant again -- a boundary held stale, say -- is re-checked
+ * after a resync interval rather than on every neighbour's wake.
*/
type Subscriber = {
changesAtMs: number;
@@ -18,7 +20,10 @@ type Subscriber = {
const subscribers = new Set<Subscriber>();
let timer: ReturnType<typeof setTimeout> | undefined;
-let armedForMs = Number.POSITIVE_INFINITY;
+// The earliest deadline the live timer covers. The timer itself may fire
+// sooner -- a resync, or the gap held after a wake -- so this is what the
+// clock promises to reach, not when it next runs.
+let earliestDeadlineMs = Number.POSITIVE_INFINITY;
// The latest clock reading the clock has seen, so a later reading below it
// is proof the wall clock moved backward.
let clockHighWaterMs = Number.NEGATIVE_INFINITY;
@@ -38,7 +43,7 @@ function disarm(): void {
clearTimeout(timer);
timer = undefined;
}
- armedForMs = Number.POSITIVE_INFINITY;
+ earliestDeadlineMs = Number.POSITIVE_INFINITY;
}
function arm(changesAtMs: number): void {
@@ -47,7 +52,7 @@ function arm(changesAtMs: number): void {
return;
}
const nowMs = Date.now();
- armedForMs = changesAtMs;
+ earliestDeadlineMs = changesAtMs;
// A high-water mark, not the last reading: arming happens on any commit, and
// taking the reading as-is after a backward step would erase the evidence of
// it before the next check looked.
@@ -104,7 +109,7 @@ function useNow(changesAtMs: number | undefined): void {
}
const subscriber: Subscriber = { changesAtMs, wake };
subscribers.add(subscriber);
- if (changesAtMs < armedForMs) {
+ if (changesAtMs < earliestDeadlineMs) {
arm(changesAtMs);
}
return () => {