fix: seqlock writer-enter missing Release fence — torn reads on weak memory (#40)

Cargo.toml

@@ -17,8 +17,13 @@ memmap2 = "0.9"
 libc = "0.2"
 ahash = "0.8"
 
+# Loom is only pulled in for the seqlock memory-ordering model (issue #40), built
+# solely under `RUSTFLAGS="--cfg loom"`. It is absent from normal/release builds and CI.
+[target.'cfg(loom)'.dependencies]
+loom = "0.7"
+
 [lints.rust]
-unexpected_cfgs = { level = "warn", check-cfg = ['cfg(Py_GIL_DISABLED)'] }
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(Py_GIL_DISABLED)', 'cfg(loom)'] }
 
 [profile.release]
 lto = "fat"

docs/ARCHITECTURE.md

@@ -67,6 +67,14 @@ For day-to-day workflow and commands, see [`CLAUDE.md`](../CLAUDE.md) and
 - **Hash table capacity must be power-of-2** — bitmask probing uses
   `hash & (capacity - 1)`. Always use `.next_power_of_two()`.
 - **`#[repr(C)]` struct field ordering** — place u64 fields before u32 to avoid implicit
+  alignment padding; affects `size_of` assertions in `layout.rs`.
+- **Seqlock writer ordering (issue #40).** The writer must publish the odd ("writer active")
+  sequence number *before* its data mutations become visible: `write_lock` does the odd store
+  then an `atomic::fence(Release)` (a Release store alone orders only *prior* ops). This pairs
+  with the reader's `atomic::fence(Acquire)` in `read_validate` — without the writer fence, on
+  weak-memory hardware a data write can float ahead of the odd publish and a reader can validate
+  a torn read against a stale even seq. The ordering is model-checked under `loom` (run
+  `RUSTFLAGS="--cfg loom" cargo test --lib seqlock_ordering`; loom is a `cfg(loom)`-only dep).
   alignment padding; affects `size_of` assertions in `layout.rs`. Any field the lock-free
   read path *writes* (currently only `SlotHeader.visited`) must be an atomic type accessed
   with `Relaxed` — readers touch it without the write lock while writers reuse the slot, so a