Skip to content

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

docs(frontend): what absence means now, and what the rule reserves

zchpeter06c3b7716766
diff --git a/docs/design/timestamp-display.md b/docs/design/timestamp-display.md
index a29aaf3e1a..797f19025b 100644
--- a/docs/design/timestamp-display.md
+++ b/docs/design/timestamp-display.md
@@ -297,7 +297,9 @@ no seconds per D5. Relative age may accompany it in the tooltip.
past it, measured: a key that is not a plain identifier or quoted string, and a destructure of
two or more properties. Neither is what anyone writes by accident. Test files are excluded,
since a test builds a reading and reads it directly, and matching the member reserves both
- names across the app — a permission object spelled `{ read: true }` would be reported too. The rule
+ names across the app: a permission object spelled `{ read: true }`, a stream reader's
+ `.read()`, and — because the object-literal case descends the whole subtree — any literal with
+ an identifier `read` anywhere beneath it. Type annotations and interfaces are not reported. 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
@@ -324,8 +326,14 @@ no seconds per D5. Relative age may accompany it in the tooltip.
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. The domain lives with the formatters, since they are what
- rejects a value; a display asks them rather than guessing at the test.
+ 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. Absence is `undefined`
+ throughout: the epoch is an ordinary instant, so a surface that used to hide a zero now shows
+ 1970, which is what the server sending one would mean. No server does — every timestamp these
+ surfaces read is set from a real time or left unset. The container's empty form is a caller's
+ decision, and only absence reaches it: a value the domain rejects leaves the display rendering
+ nothing while its separator stays, which no proto-sourced timestamp can produce, since a
+ `Timestamp` is range-checked to years 1–9999.
- 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/src/utils/datetime.test.ts b/frontend/src/utils/datetime.test.ts
index 733e37a85f..6e45de66e1 100644
--- a/frontend/src/utils/datetime.test.ts
+++ b/frontend/src/utils/datetime.test.ts
@@ -306,11 +306,6 @@ describe("reading boundaries", () => {
describe.each([
["work-queue", queueTimeReading],
["relative", relativeTimeReading],
- // A constant rendering names no instant at all, which is what keeps every
- // absolute timestamp in every table off the shared clock.
- ["absolute", absoluteTimeReading],
- ["compact", compactTimeReading],
- ["operational", operationalTimeReading],
])("%s", (_name, reading) => {
test.each(boundaryCases(SAMPLED_AGES_MS))(
"names the instant the reading changes (age $offset ms from $start, +$fractionMs ms)",
@@ -320,6 +315,25 @@ describe("reading boundaries", () => {
}
);
});
+
+ // A constant rendering names no instant at all, which is what keeps every
+ // absolute timestamp in every table off the shared clock. Sampled rather
+ // than swept: the ages only matter to a reading that changes with them, and
+ // all of these take the same branch.
+ describe.each([
+ ["absolute", absoluteTimeReading],
+ ["compact", compactTimeReading],
+ ["operational", operationalTimeReading],
+ ])("%s", (_name, reading) => {
+ test.each([
+ ["moments ago", SECOND_MS],
+ ["within the day", 5 * HOUR_MS],
+ ["past the relative threshold", 40 * DAY_MS],
+ ])("never changes, %s", (_label, ageMs) => {
+ const startMs = startAt(BOUNDARY_STARTS[0]);
+ expectBoundaryMatchesReading(reading, startMs - ageMs);
+ });
+ });
});
describe("deadline readings", () => {