From e3d12fd040053b6e4fc25eef566e19c6624f1f5c Mon Sep 17 00:00:00 2001
From: kalvinparker <106995826+kalvinparker@users.noreply.github.com>
Date: Fri, 14 Nov 2025 15:13:40 +0000
Subject: [PATCH] docs(proposals): add clock interface proposal

---
 docs/proposals/clock-interface.md | 32 +++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)
 create mode 100644 docs/proposals/clock-interface.md

diff --git a/docs/proposals/clock-interface.md b/docs/proposals/clock-interface.md
new file mode 100644
index 0000000..26b50fe
--- /dev/null
+++ b/docs/proposals/clock-interface.md
@@ -0,0 +1,32 @@
+# Proposal: Clock interface for deterministic time
+
+Summary
+-------
+Introduce a `Clock` interface and replace package-level `now = time.Now` usages in targeted packages (e.g. `pkg/registry/auth`) with dependency injection via a `Clock` to allow deterministic tests and easier control over time in the future.
+
+Motivation
+----------
+- Currently some packages expose a package-level `now` variable used by tests to override time. A dedicated `Clock` interface reduces global state and improves testability across packages.
+
+Proposal
+--------
+- Define `type Clock interface { Now() time.Time }` in `pkg/clock/clock.go` and provide `RealClock` implementation that calls `time.Now()`.
+- Introduce constructors or package-level `SetClock(clock Clock)` functions where needed (e.g. `pkg/registry/auth`) or prefer injecting `Clock` via function parameters in higher-level constructors.
+
+Compatibility
+-------------
+- Backwards-compatible: default behavior uses `RealClock` when no override is provided.
+
+Migration
+---------
+1. Add `pkg/clock/clock.go` containing `Clock` and `RealClock`.
+2. Update `pkg/registry/auth` to use `clock.Now()` through injection or a package-level `clock` variable initialized to `RealClock{}`.
+3. Replace test overrides of `now` by using a `FakeClock` in tests.
+
+Risks
+-----
+- Small refactor; tests will need updates but should be straightforward.
+
+References
+----------
+- Current usage: `pkg/registry/auth/auth.go` uses `var now = time.Now`.