Skip to content

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

fix(frontend): stop the clock erasing its own evidence of a backward step

zchpeteraa8f72316aaa
diff --git a/docs/design/timestamp-display.md b/docs/design/timestamp-display.md
index 7057fdf700..ce9a9a4d51 100644
--- a/docs/design/timestamp-display.md
+++ b/docs/design/timestamp-display.md
@@ -279,21 +279,25 @@ no seconds per D5. Relative age may accompany it in the tooltip.
change otherwise hides.
- **A display gets a reading only through `useTimeReading`**, which takes the reading object,
evaluates its boundary before its value, and subscribes to the shared clock. Pairing,
- subscription and evaluation order therefore hold by construction rather than by convention at
- each call site: a boundary borrowed from a different reading or re-derived beside one, a
- display that forgot to subscribe, and a boundary evaluated after its value — which can see a
- change the value just missed and schedule the one after — are each impossible to write
- without leaving the hook.
+ subscription and evaluation order come with it: a boundary borrowed from a different reading
+ or re-derived beside one, a display that forgot to subscribe, and a boundary evaluated after
+ 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. 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
+ 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. 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
substitute — the current time and the epoch are both plausible-looking lies — and the
@@ -310,7 +314,9 @@ no seconds per D5. Relative age may accompany it in the tooltip.
- The audit log (already correct).
- Duration display (`humanizeDurationV1`, "4.2s"): durations are elapsed quantities with no
- calendar or timezone question.
+ calendar or timezone question. A running task's elapsed time is the one that keeps moving; it
+ advances when its row re-renders rather than on the shared clock, since counting it live would
+ wake every running row once a second for a number nobody reads to that precision.
- Relative wording under 30 days.
- No user or workspace preference (GitLab's model is the known shape if a customer ever asks).
- No backend or proto change.
diff --git a/frontend/biome-plugins/time-reading-through-hook.grit b/frontend/biome-plugins/time-reading-through-hook.grit
new file mode 100644
index 0000000000..f60358a15d
--- /dev/null
+++ b/frontend/biome-plugins/time-reading-through-hook.grit
@@ -0,0 +1,16 @@
+// 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.
+language js
+
+js"$reading.$member($args)" as $call where {
+ $reading <: r"[A-Za-z]+Reading",
+ or { $member <: `read`, $member <: `nextChangeAt` },
+ register_diagnostic(
+ span=$call,
+ message="Read a time-varying value through useTimeReading(reading, input), which subscribes it to the shared clock."
+ )
+}
diff --git a/frontend/biome.json b/frontend/biome.json
index 36d2bf2194..e87f2e41be 100644
--- a/frontend/biome.json
+++ b/frontend/biome.json
@@ -303,6 +303,17 @@
],
"plugins": ["./biome-plugins/cel-filter-literals.grit"]
},
+ {
+ "includes": [
+ "src/**/*.ts",
+ "src/**/*.tsx",
+ "!src/**/*.test.ts",
+ "!src/**/*.test.tsx",
+ "!src/utils/datetime.ts",
+ "!src/utils/accessGrant.ts"
+ ],
+ "plugins": ["./biome-plugins/time-reading-through-hook.grit"]
+ },
{
"includes": ["*.json", "**/*.json", "*.json5", "**/*.json5"],
"javascript": { "globals": [] },
diff --git a/frontend/src/hooks/useTimeReading.test.tsx b/frontend/src/hooks/useTimeReading.test.tsx
index 06ea45c00f..8c16841002 100644
--- a/frontend/src/hooks/useTimeReading.test.tsx
+++ b/frontend/src/hooks/useTimeReading.test.tsx
@@ -253,6 +253,20 @@ describe("useTimeReading", () => {
expect(values).toEqual(["after"]);
});
+ test("still wakes a display when another mounts after the clock steps back", () => {
+ // Arming re-reads the clock, so a display mounting in the window between
+ // the step and the next check must not erase the evidence of the step.
+ const deadlineMs = Date.now() + 5 * 60_000;
+ const { renders } = mount([{ changesAtMs: onceAt(deadlineMs) }]);
+
+ vi.setSystemTime(Date.now() - 10 * 60_000);
+ mount([{ changesAtMs: onceAt(Date.now() + 30_000) }]);
+ act(() => {
+ vi.advanceTimersByTime(60_000);
+ });
+ expect(renders[0]).toBe(2);
+ });
+
test("wakes every display when the wall clock steps backward", () => {
// Each boundary was computed on the later clock; on the earlier one it can
// be far off in either direction.
diff --git a/frontend/src/hooks/useTimeReading.ts b/frontend/src/hooks/useTimeReading.ts
index 1cdfb2c1a3..79ec3c87a5 100644
--- a/frontend/src/hooks/useTimeReading.ts
+++ b/frontend/src/hooks/useTimeReading.ts
@@ -19,7 +19,9 @@ type Subscriber = {
const subscribers = new Set<Subscriber>();
let timer: ReturnType<typeof setTimeout> | undefined;
let armedForMs = Number.POSITIVE_INFINITY;
-let armedAtMs = Number.NEGATIVE_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;
let lastWakeMs = Number.NEGATIVE_INFINITY;
// Deadlines are wall-clock instants, but timers do not count time the machine
@@ -46,7 +48,10 @@ function arm(changesAtMs: number): void {
}
const nowMs = Date.now();
armedForMs = changesAtMs;
- armedAtMs = nowMs;
+ // 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.
+ clockHighWaterMs = Math.max(clockHighWaterMs, nowMs);
// Bounded above too, so a clock stepped backward cannot stretch the gap.
const gapMs = Math.min(
Math.max(lastWakeMs + MIN_WAKE_GAP_MS - nowMs, 0),
@@ -58,10 +63,15 @@ function arm(changesAtMs: number): void {
function tick(): void {
const nowMs = Date.now();
- // A timer cannot fire before it was armed, so a wall clock reading earlier
- // than the arm means the clock stepped backward, and every boundary computed
- // on the later clock may now be wrong in either direction.
- const clockSteppedBack = nowMs < armedAtMs;
+ // A timer cannot fire before it was armed, so a reading earlier than the
+ // highest one seen means the wall clock stepped backward, and every boundary
+ // computed on the later clock may now be wrong in either direction.
+ const clockSteppedBack = nowMs < clockHighWaterMs;
+ if (clockSteppedBack) {
+ // The step is handled once here; without this the mark would stay ahead
+ // and every later check would wake everything again.
+ clockHighWaterMs = nowMs;
+ }
let nextMs = Number.POSITIVE_INFINITY;
for (const subscriber of subscribers) {
if (clockSteppedBack || subscriber.changesAtMs <= nowMs) {
diff --git a/frontend/src/modules/sql-editor/components/AccessGrantItem.tsx b/frontend/src/modules/sql-editor/components/AccessGrantItem.tsx
index ee2e355669..535fa4ffdf 100644
--- a/frontend/src/modules/sql-editor/components/AccessGrantItem.tsx
+++ b/frontend/src/modules/sql-editor/components/AccessGrantItem.tsx
@@ -42,6 +42,10 @@ export function AccessGrantItem({
}: Props) {
const { t } = useTranslation();
+ // Two readings, each on its own boundary. The countdown's last step lands on
+ // the deadline, the same instant the status turns expired, so the status
+ // subscription adds no wake today -- it is here so the badge does not depend
+ // on that coincidence holding.
const deadlineMs = getActiveAccessGrantDeadlineMs(grant);
const countdown = useTimeReading(countdownReading, deadlineMs);
const displayStatus = useTimeReading(accessGrantStatusReading, {
diff --git a/frontend/src/routes/project/plan-detail/components/deploy/DeployTaskHeader.tsx b/frontend/src/routes/project/plan-detail/components/deploy/DeployTaskHeader.tsx
index 3b40738245..5b899347ba 100644
--- a/frontend/src/routes/project/plan-detail/components/deploy/DeployTaskHeader.tsx
+++ b/frontend/src/routes/project/plan-detail/components/deploy/DeployTaskHeader.tsx
@@ -163,8 +163,7 @@ export function DeployTaskHeader({
<span className="rounded-full border bg-control-bg px-2 py-0.5 text-control-light">
<HumanizeTs
ts={
- getTimeForPbTimestampProtoEs(latestTaskRun.createTime, 0) /
- 1000
+ getTimeForPbTimestampProtoEs(latestTaskRun.createTime) / 1000
}
/>
</span>
diff --git a/frontend/src/routes/project/plan-detail/components/review/ReviewActivityTimeline.tsx b/frontend/src/routes/project/plan-detail/components/review/ReviewActivityTimeline.tsx
index d6dfe2d511..5912b2aa43 100644
--- a/frontend/src/routes/project/plan-detail/components/review/ReviewActivityTimeline.tsx
+++ b/frontend/src/routes/project/plan-detail/components/review/ReviewActivityTimeline.tsx
@@ -320,7 +320,7 @@ function SyntheticHeader({
{source.time && (
<HumanizeTs
className="text-xs text-control-light"
- ts={getTimeForPbTimestampProtoEs(source.time, 0) / 1000}
+ ts={getTimeForPbTimestampProtoEs(source.time) / 1000}
/>
)}
</>
diff --git a/frontend/src/routes/project/plan-detail/components/review/ReviewRejectionBanner.tsx b/frontend/src/routes/project/plan-detail/components/review/ReviewRejectionBanner.tsx
index be2e9e106e..c0c9bb06ef 100644
--- a/frontend/src/routes/project/plan-detail/components/review/ReviewRejectionBanner.tsx
+++ b/frontend/src/routes/project/plan-detail/components/review/ReviewRejectionBanner.tsx
@@ -96,9 +96,7 @@ export function ReviewRejectionBanner({
<span className="text-error/50">·</span>
<HumanizeTs
className="text-xs font-normal text-error/70"
- ts={
- getTimeForPbTimestampProtoEs(rejection.createTime, 0) / 1000
- }
+ ts={getTimeForPbTimestampProtoEs(rejection.createTime) / 1000}
/>
</>
)}
diff --git a/frontend/src/routes/project/plan-detail/components/threads/CommentThreadCard.tsx b/frontend/src/routes/project/plan-detail/components/threads/CommentThreadCard.tsx
index 32234558e1..6f187ba06a 100644
--- a/frontend/src/routes/project/plan-detail/components/threads/CommentThreadCard.tsx
+++ b/frontend/src/routes/project/plan-detail/components/threads/CommentThreadCard.tsx
@@ -421,7 +421,7 @@ function ThreadSummary({
{thread.root.createTime && (
<HumanizeTs
className="hidden shrink-0 text-xs text-control-light sm:inline"
- ts={getTimeForPbTimestampProtoEs(thread.root.createTime, 0) / 1000}
+ ts={getTimeForPbTimestampProtoEs(thread.root.createTime) / 1000}
/>
)}
<Badge className="shrink-0 gap-x-1 px-2 text-xs" variant="success">
diff --git a/frontend/src/routes/project/plan-detail/components/threads/ThreadStack.tsx b/frontend/src/routes/project/plan-detail/components/threads/ThreadStack.tsx
index c16ece8264..103aabe666 100644
--- a/frontend/src/routes/project/plan-detail/components/threads/ThreadStack.tsx
+++ b/frontend/src/routes/project/plan-detail/components/threads/ThreadStack.tsx
@@ -224,7 +224,7 @@ function CollapsedThreadRow({
{comment.createTime && (
<HumanizeTs
className="hidden shrink-0 text-xs text-control-light @xl:inline"
- ts={getTimeForPbTimestampProtoEs(comment.createTime, 0) / 1000}
+ ts={getTimeForPbTimestampProtoEs(comment.createTime) / 1000}
/>
)}
{resolved && (