ADR 0098 D1: Clock/Entropy seam — time and randomness become injected world inputs

[nikhilunni]

First DST-harness PR of ADR 0098 (#694). Follows #695/#696.

What

The seam — engram_core::traits::{Clock, Entropy} (crates/engram-core/src/traits/clock.rs):

• Clock::now_utc() / now_mono() (Duration since a process epoch — replaces Instant pairs, since a fake can't mint opaque Instants) / sleep().
• Entropy::uuid() / u64(range) for jitter. Prod impls SystemClock / OsEntropy; Services gains clock + entropy fields.

The sweep — ~70 files: every decision-feeding Utc::now(), Instant::now(), Uuid::new_v4() in the coordinator reads through the seam. Highlights:

• idle_detector::classify takes a hoisted now (the event-age TTL decision the DST program targets); placement's ranking fns take a trailing now from callers; dead_host's ProbeMemory.last_rescue becomes a now_mono() Duration mark; Reconciler and CowStateCache carry injected clock fields (SystemClock default, with_clock() for the sim harness).
• Event/DB timestamps (at:) convert too — trace reproducibility under simulation needs them on the sim clock.

Enforcement — crates/engram-coordinator/clippy.toml disallowed-methods + workspace clippy::disallowed_methods = "deny": a direct call is a hard error. SystemClock/OsEntropy are the one honest caller of each; test modules that drive a live system carry one scoped allow with a standard justification comment.

Semantic fix the lane caught

The three GC sweeps (chunk / bundle / snapshot-blob) mark candidates — PG stamps first_seen_at DEFAULT now() — then promote in the same call. A now captured at sweep start never sees a same-sweep candidate as expired under zero grace (two admin_chunk_gc_live_pg tests failed). Fixed by threading the clock and reading it fresh at promote time, preserving pre-D1 ordering. The host-vs-PG cross-clock comparison is pre-existing (the f97a1c2 class) and is what D3's bind-param now() unifies.

Verification

• just check green (1680 passed); coordinator clippy clean across all targets.
• Full 143-test live-PG lane green 2× at --test-threads=16.
• Negative probe: a planted Utc::now() in src fails clippy with the ADR-0098 message, then reverted.

Next

D3 (bind-param now() in PostgresStore, 126 sites) and the engram-sim crate (D4) build on this seam.

🤖 Generated with Claude Code