Add expiration chapter

book/05-events.md

@@ -162,10 +162,33 @@ impl EventContent {
 
 ### `StampedEvent`
 
-Stamping adds the `created_at` timestamp. Callers usually pass
-`SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_secs()`, but the
-library stays out of clock policy — the timestamp is whatever the caller says
-it is.
+Stamping adds the `created_at` timestamp. The library stays out of clock
+policy — the timestamp is whatever the caller says it is — but in practice
+"whatever the caller says" is almost always "right now," so we give that
+common case a name. The `now` helper lives in a `util` module, the home for
+the small, stateless helpers that don't belong to any one type.
+
+```rust {file=coracle-lib/src/lib.rs}
+pub mod util;
+```
+
+```rust {file=coracle-lib/src/util.rs}
+//! Small stateless helpers shared across the library.
+
+use std::time::{SystemTime, UNIX_EPOCH};
+
+/// The current time as a Unix timestamp in seconds.
+pub fn now() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|d| d.as_secs())
+        .unwrap_or(0)
+}
+```
+
+Stamping a template with the current time then reads as
+`template.stamp(now())`. `stamp` itself takes a plain `u64`, leaving the
+choice of clock to the caller.
 
 ```rust {file=coracle-lib/src/events.rs}
 /// A template with a `created_at` timestamp attached.