Database governance built for humans and agents — controlling changes and access across every major database.
Go cicddata-governancedata-maskingdata-securitydatabase-accessdatabase-governancedevopsdevsecopsflywaygitopsliquibasemongodbmysqloraclepostgresqlschema-migrationssecuritysql-clientsqlservertidb
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.mdindex 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 — arenone of them reachable through the hook. What the hook cannot prevent is a display reachingpast 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 asubstitute — the current time and the epoch are both plausible-looking lies — and thecontainer 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 surfacesat implementation time — a review pass, not a lint: telling render scope from handlers andeffects 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.gritindex 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.tsindex 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 () => {