OUT-3988: L0.4 — clock / determinism control toolkit

[SandipBajracharya]

L0.4 — Clock / determinism control

Test-only toolkit (test/time/) so time-dependent code can be tested deterministically and fast, with zero production change. Foundation primitive consumed by the resync backoff-boundary tests (L2.3) and webhook debounce tests (L3.3).

Linear: OUT-3988 · parent OUT-3984 · base branch: OUT-3987

The two-world model

Time is read in two places that need different tools:

Seam	Example	Tool
JS sleep() / Date.now() / new Date()	debounce window, 12h stuck-pending, sleep(5000)	useFakeClock / mockSleepInstant (no real waiting)
Postgres NOW()	resync backoff 5min × attempts	offset-seeding (minutesAgo(6), …) — JS can't fake SQL NOW()

What's here

• useFakeClock(iso?) — freeze / advance / setNow / restore over vitest fake timers; toFake scoped to Date + timer fns (never nextTick/microtask); async advance so sleep() flushes.
• offset helpers — msAgo/secondsAgo/minutesAgo/hoursAgo/daysAgo/fromNow, value-agnostic pure Date-math.
• mockSleepInstant() — instant spy over @/utils/sleep; assert the intended wait with no delay.
• boundary-examples.test.ts — executable docs of the two-world usage.
• vitest.setup.ts — one afterEach(vi.useRealTimers()) safety net (unit project only).

Verification

• pnpm typecheck clean · pnpm lint clean · full unit suite 164/164 (14 new).
• No production code touched; fake timers are opt-in per test; integration project untouched.

🤖 Generated with Claude Code

[linear-code]

OUT-3988

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
dropbox-integration	Ready	Preview	Aug 7, 2026 8:13am

[greptile-apps]

Greptile Summary

This PR adds a test-only deterministic-time toolkit without changing production behavior.

• Adds scoped Vitest fake-clock controls for dates and timers.
• Adds pure date-offset helpers for JavaScript and PostgreSQL-backed test scenarios.
• Adds an instant mocked-sleep helper and executable boundary examples.
• Restores real timers after every unit test as a leak-prevention safety net.

Confidence Score: 5/5

The PR appears safe to merge, with no concrete blocking or independently actionable non-blocking issue identified.

The new utilities are confined to tests, cover the repository’s current JavaScript timer APIs, explicitly separate fake JavaScript time from real database time, and restore global timer state after unit tests.

Important Files Changed

Filename	Overview
test/time/fakeClock.ts	Adds a scoped fake-clock abstraction that freezes JavaScript time, advances configured timers asynchronously, and restores real timers.
test/time/offsets.ts	Adds straightforward date-offset helpers suitable for both frozen JavaScript clocks and real PostgreSQL-time test seeding.
test/time/sleep.ts	Adds an instant sleep mock helper with an explicit requirement that callers hoist the corresponding module mock.
vitest.setup.ts	Adds unit-project teardown cleanup to prevent fake timers from leaking between tests.
test/time/boundary-examples.test.ts	Documents and tests the separate JavaScript-clock and PostgreSQL-clock testing strategies.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  T[Test case] -->|JS time behavior| F[useFakeClock]
  F --> D[Fake Date.now and new Date]
  F --> M[Advance fake timers]
  M --> S[Resolve sleep without waiting]
  T -->|PostgreSQL NOW behavior| O[Offset helpers]
  O --> P[Seed timestamps relative to real time]
  P --> Q[SQL boundary query]
  T -->|Retry wait assertion| I[mockSleepInstant]
  I --> A[Record duration and resolve immediately]

Loading

_{Reviews (1): Last reviewed commit: "test(OUT-3988): add two-world boundary e..." | Re-trigger Greptile}